@chem-x/starter-kit 26.9.20-1257 → 26.9.20-1318

package/README.md

@@ -18,6 +18,47 @@ Access the interactive book, prompt generator, and asset vault at [https://chemi
 
 ---
 
+## Quickstart: Scaffolding a New Project
+
+Create a brand new molecular architecture project in seconds using your preferred package manager:
+
+```bash
+# npm (interactive or pass project directory)
+npm create chemx my-molecular-app
+
+# Automated / Agent / Headless mode (skips prompts, scaffolds Community Edition immediately)
+npm create chemx my-molecular-app -- --yes
+
+# npx
+npx create-chemx my-molecular-app --yes
+
+# pnpm / yarn / bun
+pnpm create chemx my-molecular-app
+yarn create chemx my-molecular-app
+bun create chemx my-molecular-app
+```
+
+### Headless & Autonomous Agent Mode
+When running in unattended environments (CI/CD pipelines, Cursor Agent, Windsurf, Claude Code, Antigravity), pass `--yes` (or `-y`, `--ci`, `--headless`) to bypass interactive terminal menus and immediately scaffold the free Community Edition with recommended architectural pillars:
+
+```bash
+npx create-chemx my-molecular-app --yes
+```
+
+### Package Architecture: Scaffolder vs Command Engine
+Chemical X provides two coordinated packages:
+- **`create-chemx`**: Dedicated zero-dependency project scaffolder (`npm create chemx`). Directly provisions project templates, test suites, and architectural configurations.
+- **`chemx`**: The full Molecular Architecture CLI & AST Query Engine. Manages audits, verifications, AST query lookups, code patching, and multi-agent swarm task coordination.
+
+```bash
+# Install chemx CLI globally or in your project:
+npm install -g chemx
+# or run on-demand:
+npx chemx --help
+```
+
+---
+
 ## Structure
 
 ```
@@ -138,6 +179,106 @@ $ npx chemx verify --dir=blueprints
 
 ---
 
+## CLI Command Reference & Workflow
+
+The `chemx` command suite is specifically tailored for token conservation, instant feedback, and zero terminal clutter:
+
+### 1. Verification & Quality
+```bash
+# Full verification pipeline (AST Audit + Typecheck + Tests) -> ~45 token status card
+chemx verify
+chemx verify --json
+
+# Run 7-Pillar static AST audit
+chemx audit
+chemx audit --unroll        # Inspect individual hazard lines and explanations
+chemx audit --strict        # Fail on any violation, including minor style warnings
+chemx audit --json          # Machine-readable format for agent pipelines
+
+# Silent TypeScript compilation check (suppresses passing noise, returns error lines)
+chemx typecheck
+chemx typecheck --json
+
+# Silent test runner (suppresses passing tests, extracts only failing assertions & stack diffs)
+chemx test
+chemx test --json
+
+# Silent build audit (categorizes diagnostics into TypeScript, Rollup, and style budgets)
+chemx build
+chemx build --json
+```
+
+### 2. AST Query Engine & Surgical Inspection
+```bash
+# Hybrid search (BM25 keyword + cosine vector similarity via Reciprocal Rank Fusion)
+chemx q "useAttentionCardController" --hybrid --json
+
+# Transitive blast radius analysis before refactoring foundational capsules
+chemx q "a-button" --blast-radius --json
+
+# Inspect component props, hooks, and types without reading entire files
+chemx q "m-task-list" --inspect
+
+# Surgical token-optimized file reader (AST outlines, stripped comments, specific symbols)
+chemx read src/components/m-card.vue --symbol=useCardController
+chemx read src/components/m-card.vue --outline
+chemx read src/components/m-card.vue --start=10 --end=40
+
+# Surgical file patching without full-file rewrites
+chemx patch <file> --target="oldCode" --replacement="newCode"
+```
+
+### 3. Crystalline Capsule Generator
+Scaffold production-ready component capsules matching strict zero-raw-DOM standards:
+```bash
+# Molecule capsule (component, controller, glass styling, types, spec)
+chemx m-task-card
+
+# Atom foundation (the only tier permitted raw HTML elements)
+chemx a-status-pill
+
+# Organism module (complex grouping of molecules and atoms)
+chemx o-workspace-header
+
+# Pure reactive hook / domain composable
+chemx use-task-filter
+```
+
+### 4. Database-Driven Multi-Agent Swarm Coordination
+Coordinate multi-agent swarms using the local SQLite store (`.chemx/index.db`) without multi-thousand-token markdown specification bloat:
+```bash
+# Auto-triage: convert AST audit hazards directly into assignable team tasks
+chemx team task triage
+
+# List tasks assigned to a specific agent
+chemx team task list --agent=@agent-alpha
+
+# Claim an open task
+chemx team task claim 1 --as=@agent-alpha
+
+# Mark task complete (automatically re-audits target file on disk to guarantee zero hazards)
+chemx team task done 1 --as=@agent-alpha
+
+# Inspect multi-agent swarm status and lock queues
+chemx team status
+```
+
+---
+
+## The 7 Molecular Architecture Pillars
+
+Chemical X enforces seven core architectural directives configured via `chemx pillars`:
+
+1. **Strict Molecular Line Budgets (< 100 Lines)**: Single-purpose files. Approaching 100 lines is a decomposition trigger. Eliminates context rot and cuts token ingestion costs.
+2. **Strict Component Tiers & Zero-Raw-DOM**: Raw HTML elements (`<button>`, `<input>`, `<div>`) are strictly isolated inside foundational **Atoms** (`a-*`). Molecules, Organisms, Templates, and Views assemble atoms and never contain raw tags.
+3. **Table-of-Contents Views**: Top-level page views are clean, 10–20 line declarative blueprints assembling self-contained molecules and organisms via named slots (`#header`, `#default`, `#modals`).
+4. **Molecular Composable Contracts**: Composables return plain destructurable objects with a strict 3-to-5 property limit (State + Status + Actions). Domain types use discriminated unions (zero impossible states).
+5. **Silent Verification Pipeline**: Verification tools suppress passing checkmarks and compiler banners, returning token-compact summaries (~45 tokens) to protect AI agent context windows.
+6. **AST Codebase Query Engine**: In-band AST symbol graph lookups, blast radius calculations, and outline extraction eliminate blind full-file context dumps.
+7. **Database-First Swarm Coordination**: Task backlogs, file locks, and agent communications live in local SQLite (`.chemx/index.db`) rather than monolithic markdown specifications.
+
+---
+
 ## Model Context Protocol (MCP) Server
 
 Chemical X includes a high-performance, zero-dependency JSON-RPC 2.0 Stdio MCP server that connects directly to AI agent hosts (Cursor, Claude Desktop, Windsurf, Antigravity, VS Code).
@@ -215,6 +356,11 @@ npx chemx --version
 # create-chemx v26.9.17-606
 ```
 
+### Package Pairing & npm Registry Propagation
+
+- **Package Pairing**: `@chemx/create-chemx` and `chemx` publish together under synchronized minute-precision CalVer timestamps (`YY.M.D-minute`). For consistent behavior, install or pin the matching release versions.
+- **npm Registry Propagation Note**: Newly published releases on npm can take 2–5 minutes to propagate across all edge CDN mirrors after `npm view` lists them. If `npm install` intermittently fails with a 404 on an exact newly published version, wait a few minutes and retry.
+
 Because autonomous coding agent models update frequently, this package is continuously integrated and deployed via automated CI whenever new agent directives, AST checks, or framework rules are tuned. Rapid version iterations reflect active, daily alignment rather than breaking SemVer shifts.
 
 > [!NOTE]

package/blueprints/_package.json

@@ -10,8 +10,10 @@
     "verify": "chemx verify"
   },
   "devDependencies": {
+    "@vue/test-utils": "^2.4.6",
     "create-chemx": "latest",
     "typescript": "^5.4.0",
-    "vitest": "^1.6.0"
+    "vitest": "^1.6.0",
+    "vue": "^3.4.0"
   }
 }

package/cli/create.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { runScaffold } from './scaffold.js';
+import { runAudit } from './index.js';
+import { sanitizeOutputStreams } from './terminal.js';
+import { installGlobalErrorCatcher } from './errors/index.js';
+
+sanitizeOutputStreams();
+installGlobalErrorCatcher();
+
+const rawArgs = process.argv.slice(2);
+const nonFlagArgs = rawArgs.filter((arg) => !arg.startsWith('-'));
+const dirArg = (nonFlagArgs[0] === 'create' || nonFlagArgs[0] === 'init' || nonFlagArgs[0] === 'scaffold')
+  ? nonFlagArgs[1]
+  : nonFlagArgs[0];
+
+await runScaffold(dirArg, rawArgs, runAudit);

package/cli/create.spec.js

@@ -0,0 +1,146 @@
+import { test, describe, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+
+const CLI_DIR = path.resolve(import.meta.dirname);
+const CREATE_BIN = path.join(CLI_DIR, 'create.js');
+const INDEX_BIN = path.join(CLI_DIR, 'index.js');
+
+describe('Scaffolding Entrypoint Invocations', () => {
+  const cleanupDirs = [];
+
+  afterEach(() => {
+    while (cleanupDirs.length > 0) {
+      const dir = cleanupDirs.pop();
+      if (fs.existsSync(dir)) {
+        try {
+          fs.rmSync(dir, { recursive: true, force: true });
+        } catch {
+          // ignore cleanup errors
+        }
+      }
+    }
+  });
+
+  test('node cli/create.js <dir> --yes scaffolds project directly into target directory', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+    const targetDir = path.join(tmpBase, 'test-target-app');
+
+    const result = spawnSync('node', [CREATE_BIN, targetDir, '--yes'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 15000
+    });
+
+    assert.equal(result.status, 0, `Expected exit 0, got: ${result.status}\nStdout: ${result.stdout}\nStderr: ${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(targetDir, 'package.json')), 'package.json should be created in targetDir');
+    assert.ok(fs.existsSync(path.join(targetDir, 'molecule-capsule')), 'molecule-capsule/ should be created in targetDir');
+  });
+
+  test('node cli/create.js --yes (no dir argument) scaffolds into default my-molecular-app', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+    const defaultTarget = path.join(tmpBase, 'my-molecular-app');
+
+    const result = spawnSync('node', [CREATE_BIN, '--yes'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 15000
+    });
+
+    assert.equal(result.status, 0, `Expected exit 0, got: ${result.status}\nStdout: ${result.stdout}\nStderr: ${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(defaultTarget, 'package.json')), 'package.json should exist in default directory');
+  });
+
+  test('node cli/create.js create <dir> --yes tolerates redundant create argument', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+    const targetDir = path.join(tmpBase, 'redundant-create-app');
+
+    const result = spawnSync('node', [CREATE_BIN, 'create', targetDir, '--yes'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 15000
+    });
+
+    assert.equal(result.status, 0, `Expected exit 0, got: ${result.status}\nStdout: ${result.stdout}\nStderr: ${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(targetDir, 'package.json')), 'package.json should be created in targetDir');
+  });
+
+  test('node cli/index.js create <dir> --yes scaffolds project via chemx create', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+    const targetDir = path.join(tmpBase, 'chemx-create-app');
+
+    const result = spawnSync('node', [INDEX_BIN, 'create', targetDir, '--yes'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 15000
+    });
+
+    assert.equal(result.status, 0, `Expected exit 0, got: ${result.status}\nStdout: ${result.stdout}\nStderr: ${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(targetDir, 'package.json')), 'package.json should exist');
+  });
+
+  test('node cli/index.js create --yes scaffolds project via chemx create without positional dir', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+    const defaultTarget = path.join(tmpBase, 'my-molecular-app');
+
+    const result = spawnSync('node', [INDEX_BIN, 'create', '--yes'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 15000
+    });
+
+    assert.equal(result.status, 0, `Expected exit 0, got: ${result.status}\nStdout: ${result.stdout}\nStderr: ${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(defaultTarget, 'package.json')), 'package.json should exist');
+  });
+
+  test('executing via create-chemx symlink scaffolds successfully', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+    const symlinkPath = path.join(tmpBase, 'create-chemx');
+    fs.symlinkSync(CREATE_BIN, symlinkPath);
+    const targetDir = path.join(tmpBase, 'symlink-app');
+
+    const result = spawnSync(symlinkPath, [targetDir, '--yes'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 15000
+    });
+
+    assert.equal(result.status, 0, `Expected exit 0, got: ${result.status}\nStdout: ${result.stdout}\nStderr: ${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(targetDir, 'package.json')), 'package.json should exist');
+  });
+
+  test('node cli/create.js <dir> -y (short flag) scaffolds successfully', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+    const targetDir = path.join(tmpBase, 'short-flag-app');
+
+    const result = spawnSync('node', [CREATE_BIN, targetDir, '-y'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 15000
+    });
+
+    assert.equal(result.status, 0, `Expected exit 0, got: ${result.status}\nStdout: ${result.stdout}\nStderr: ${result.stderr}`);
+    assert.ok(fs.existsSync(path.join(targetDir, 'package.json')), 'package.json should exist');
+  });
+
+  test('node cli/index.js config still fails fast as unknown command', () => {
+    const result = spawnSync('node', [INDEX_BIN, 'config'], {
+      encoding: 'utf-8',
+      timeout: 5000
+    });
+
+    assert.equal(result.status, 1, 'Unknown command should exit with code 1');
+    assert.match(result.stderr, /Unknown command "config"/, 'Should report unknown command');
+  });
+});
+

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',
+    destructure: 'items, activeCount, setFilter, toggleItem, removeItem, addItem',
     buildState: (name, pascal) => `export interface ${pascal}Item {
   readonly id: string;
   readonly title: string;
@@ -25,22 +25,23 @@ export interface ${pascal}State {
     buildProps: (name, pascal) => `export interface ${pascal}Props {
   readonly initialItems?: readonly ${pascal}Item[];
   readonly onItemsChange?: (items: readonly ${pascal}Item[]) => void;
+  readonly className?: string;
 }
 `,
     buildController: (name, pascal) => `import { useState, useMemo } from 'react';
-import type { ${pascal}Item, ${pascal}Filter, ${pascal}State } from './types';
+import type { ${pascal}Item, ${pascal}Filter } from './types';
 
 export const use${pascal}Controller = (options: { initialItems?: readonly ${pascal}Item[]; onItemsChange?: (items: readonly ${pascal}Item[]) => void } = {}) => {
   const [items, setItems] = useState<readonly ${pascal}Item[]>(options.initialItems || [
-    { id: '1', title: 'Initialize Chemical X molecular structure', completed: true },
-    { id: '2', title: 'Implement domain controller state', completed: false }
+    { id: '1', title: 'Review Chemical X molecular standards', completed: true },
+    { id: '2', title: 'Audit atomic and molecular tier boundaries', completed: false }
   ]);
   const [filter, setFilter] = useState<${pascal}Filter>('all');
 
-  const activeCount = useMemo(() => items.filter((i) => !i.completed).length, [items]);
+  const activeCount = useMemo(() => items.filter((i: ${pascal}Item) => !i.completed).length, [items]);
   const visibleItems = useMemo(() => {
-    if (filter === 'active') return items.filter((i) => !i.completed);
-    if (filter === 'completed') return items.filter((i) => i.completed);
+    if (filter === 'active') return items.filter((i: ${pascal}Item) => !i.completed);
+    if (filter === 'completed') return items.filter((i: ${pascal}Item) => i.completed);
     return items;
   }, [items, filter]);
 
@@ -52,13 +53,13 @@ export const use${pascal}Controller = (options: { initialItems?: readonly ${pasc
   };
 
   const toggleItem = (id: string) => {
-    const next = items.map((i) => (i.id === id ? { ...i, completed: !i.completed } : i));
+    const next = items.map((i: ${pascal}Item) => (i.id === id ? { ...i, completed: !i.completed } : i));
     setItems(next);
     options.onItemsChange?.(next);
   };
 
   const removeItem = (id: string) => {
-    const next = items.filter((i) => i.id !== id);
+    const next = items.filter((i: ${pascal}Item) => i.id !== id);
     setItems(next);
     options.onItemsChange?.(next);
   };
@@ -66,17 +67,44 @@ export const use${pascal}Controller = (options: { initialItems?: readonly ${pasc
   return { items: visibleItems, allItems: items, filter, activeCount, setFilter, addItem, toggleItem, removeItem };
 };
 `,
-    buildReactBody: (name, pascal) => `      <div className="${name}__controls">
-        <span className="${name}__count">{activeCount} pending</span>
+    buildReactBody: (name, pascal) => `      <form
+        className="${name}__form"
+        onSubmit={(e) => {
+          e.preventDefault();
+          const target = e.currentTarget;
+          const input = target.elements.namedItem('taskTitle') as HTMLInputElement;
+          if (input && input.value.trim()) {
+            addItem(input.value.trim());
+            input.value = '';
+          }
+        }}
+      >
+        <input
+          name="taskTitle"
+          type="text"
+          placeholder="Add a new task..."
+          className="${name}__input"
+        />
+        <button type="submit" className="${name}__add-btn">Add</button>
+      </form>
+      <div className="${name}__controls">
+        <span className="${name}__counter">{activeCount} active</span>
         <div className="${name}__filters">
-          <button type="button" onClick={() => setFilter('all')}>All</button>
-          <button type="button" onClick={() => setFilter('active')}>Active</button>
-          <button type="button" onClick={() => setFilter('completed')}>Done</button>
+          {(['all', 'active', 'completed'] as const).map((f) => (
+            <button
+              key={f}
+              type="button"
+              className={filter === f ? 'active' : ''}
+              onClick={() => setFilter(f)}
+            >
+              {f}
+            </button>
+          ))}
         </div>
       </div>
       <ul className="${name}__list">
         {items.map((item) => (
-          <li key={item.id} className={item.completed ? '${name}__item ${name}__item--done' : '${name}__item'}>
+          <li key={item.id} className={item.completed ? 'completed' : ''}>
             <input type="checkbox" checked={item.completed} onChange={() => toggleItem(item.id)} />
             <span>{item.title}</span>
             <button type="button" onClick={() => removeItem(item.id)}>×</button>
@@ -253,7 +281,7 @@ export const use${pascal}Controller = (options: { cards?: readonly ${pascal}Card
   const [activeCardId, setActiveCardId] = useState<string | null>(null);
 
   const moveCard = (cardId: string, toColumnId: string) => {
-    const next = cards.map((c) => (c.id === cardId ? { ...c, columnId: toColumnId } : c));
+    const next = cards.map((c: ${pascal}Card) => (c.id === cardId ? { ...c, columnId: toColumnId } : c));
     setCards(next);
     options.onCardMove?.(cardId, toColumnId);
   };

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

@@ -146,8 +146,8 @@ export const use${pascal}Controller = (options: { onCheckout?: (total: number) =
   const updateQuantity = (id: string, delta: number) => {
     setItems((prev) =>
       prev
-        .map((i) => (i.id === id ? { ...i, quantity: Math.max(0, i.quantity + delta) } : i))
-        .filter((i) => i.quantity > 0)
+        .map((i: ${pascal}CartItem) => (i.id === id ? { ...i, quantity: Math.max(0, i.quantity + delta) } : i))
+        .filter((i: ${pascal}CartItem) => i.quantity > 0)
     );
   };
 

package/cli/generator-templates/hooks.js

@@ -48,13 +48,37 @@ export const buildHookIndex = (name, camelName) => `export { ${camelName} } from
 export type * from './types';
 `;
 
-export const buildHookSpec = (name, camelName) => `import { describe, it } from 'node:test';
+export const buildHookSpec = (name, camelName, runner = 'node:test') => {
+  if (runner === 'vitest') {
+    return `import { describe, it, expect } from 'vitest';
+import { ${camelName} } from './${name}';
+
+describe('${camelName} Hook Composable', () => {
+  it('is defined as a hook function', () => {
+    expect(typeof ${camelName}).toBe('function');
+  });
+});
+`;
+  }
+  if (runner === 'jest') {
+    return `import { describe, it, expect } from '@jest/globals';
+import { ${camelName} } from './${name}';
+
+describe('${camelName} Hook Composable', () => {
+  it('is defined as a hook function', () => {
+    expect(typeof ${camelName}).toBe('function');
+  });
+});
+`;
+  }
+  return `import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { ${camelName} } from './${name}.ts';
+import { ${camelName} } from './${name}';
 
 describe('${camelName} Hook Composable', () => {
-  it('exports pure hook function', () => {
+  it('is defined as a hook function', () => {
     assert.equal(typeof ${camelName}, 'function');
   });
 });
 `;
+};

package/cli/generator-templates/react.js

@@ -19,8 +19,8 @@ export const buildReactComponent = (name, pascalName, options = {}) => {
     }
 
     const stateBindings = hasController
-      ? `  const { ${archetype.destructure} } = { ...props, ...use${pascalName}Controller(props as any) };`
-      : `  const { ${archetype.destructure} } = props as any;`;
+      ? `  const { ${archetype.destructure} } = { ...props, ...use${pascalName}Controller(props) };`
+      : `  const { ${archetype.destructure} } = props;`;
 
     return `import React from 'react';
 ${atomImport}import type { ${pascalName}Props } from './types';

package/cli/generator-templates/specs.js

@@ -1,8 +1,54 @@
-export const buildComponentSpec = (name, pascalName, hasController = true) => {
+export const buildComponentSpec = (name, pascalName, hasController = true, runner = 'node:test') => {
+  if (runner === 'vitest') {
+    if (hasController) {
+      return `import { describe, it, expect } from 'vitest';
+import { use${pascalName}Controller } from './${name}.controller';
+
+describe('${pascalName} Capsule Controller', () => {
+  it('exports pure controller hook', () => {
+    expect(typeof use${pascalName}Controller).toBe('function');
+  });
+});
+`;
+    }
+
+    return `import { describe, it, expect } from 'vitest';
+
+describe('${pascalName} Atom Foundation', () => {
+  it('defines foundational UI atom contract', () => {
+    expect(true).toBe(true);
+  });
+});
+`;
+  }
+
+  if (runner === 'jest') {
+    if (hasController) {
+      return `import { describe, it, expect } from '@jest/globals';
+import { use${pascalName}Controller } from './${name}.controller';
+
+describe('${pascalName} Capsule Controller', () => {
+  it('exports pure controller hook', () => {
+    expect(typeof use${pascalName}Controller).toBe('function');
+  });
+});
+`;
+    }
+
+    return `import { describe, it, expect } from '@jest/globals';
+
+describe('${pascalName} Atom Foundation', () => {
+  it('defines foundational UI atom contract', () => {
+    expect(true).toBe(true);
+  });
+});
+`;
+  }
+
   if (hasController) {
     return `import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { use${pascalName}Controller } from './${name}.controller.ts';
+import { use${pascalName}Controller } from './${name}.controller';
 
 describe('${pascalName} Capsule Controller', () => {
   it('exports pure controller hook', () => {

package/cli/generator-templates/views.js

@@ -65,12 +65,37 @@ export type * from './types';
 `;
 };
 
-export const buildViewSpec = (name, pascalName) => `import { describe, it } from 'node:test';
+export const buildViewSpec = (name, pascalName, runner = 'node:test') => {
+  if (runner === 'vitest') {
+    return `import { describe, it, expect } from 'vitest';
+import { ${pascalName}View } from './${name}';
+
+describe('${pascalName}View Table of Contents', () => {
+  it('is defined as a view component', () => {
+    expect(typeof ${pascalName}View).toBe('function');
+  });
+});
+`;
+  }
+  if (runner === 'jest') {
+    return `import { describe, it, expect } from '@jest/globals';
+import { ${pascalName}View } from './${name}';
+
+describe('${pascalName}View Table of Contents', () => {
+  it('is defined as a view component', () => {
+    expect(typeof ${pascalName}View).toBe('function');
+  });
+});
+`;
+  }
+  return `import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
+import { ${pascalName}View } from './${name}';
 
 describe('${pascalName}View Table of Contents', () => {
-  it('defines pure declarative blueprint layout', () => {
-    assert.ok(true);
+  it('is defined as a view component', () => {
+    assert.equal(typeof ${pascalName}View, 'function');
   });
 });
 `;
+};

package/cli/generator.js

@@ -27,7 +27,7 @@ import {
   buildViewIndex,
   buildViewSpec
 } from './generator-templates.js';
-import { detectFramework, detectTierBaseDir, detectInstalledFamily } from './project-detector.js';
+import { detectFramework, detectTierBaseDir, detectInstalledFamily, detectTestRunner } from './project-detector.js';
 
 const TIERS = [
   { prefix: 'm-', tier: 'molecule', label: '1. m- Molecule (Self-contained feature block < 100 lines - Recommended)' },
@@ -112,6 +112,7 @@ export const createCapsuleFiles = ({
   const parentDir = targetParent || detectedDir;
   const resolvedParent = path.resolve(cwd, parentDir || '.');
   const targetDir = path.resolve(resolvedParent, capsuleName);
+  const runner = detectTestRunner(targetDir || cwd);
 
   if (!dryRun && fs.existsSync(targetDir)) {
     throw new Error(`Directory ${capsuleName} already exists at ${targetDir}.`);
@@ -142,7 +143,7 @@ export const createCapsuleFiles = ({
 
     recordFile(hookFile, path.join(targetDir, hookFile), buildHook(capsuleName, camelName, pascalName));
     recordFile('index.ts', path.join(targetDir, 'index.ts'), buildHookIndex(capsuleName, camelName));
-    recordFile(specFile, path.join(targetDir, specFile), buildHookSpec(capsuleName, camelName));
+    recordFile(specFile, path.join(targetDir, specFile), buildHookSpec(capsuleName, camelName, runner));
 
     recordFile('types/options.d.ts', path.join(typesDir, 'options.d.ts'), buildHookOptionsType(pascalName));
     recordFile('types/return.d.ts', path.join(typesDir, 'return.d.ts'), buildHookReturnType(pascalName));
@@ -154,7 +155,7 @@ export const createCapsuleFiles = ({
 
     recordFile(viewFile, path.join(targetDir, viewFile), selectedFramework.viewBuilder(capsuleName, pascalName));
     recordFile('index.ts', path.join(targetDir, 'index.ts'), buildViewIndex(capsuleName, pascalName, selectedFramework.ext));
-    recordFile(specFile, path.join(targetDir, specFile), buildViewSpec(capsuleName, pascalName));
+    recordFile(specFile, path.join(targetDir, specFile), buildViewSpec(capsuleName, pascalName, runner));
 
     recordFile('types/params.d.ts', path.join(typesDir, 'params.d.ts'), buildViewParamsType(pascalName));
     recordFile('types/index.ts', path.join(typesDir, 'index.ts'), buildTypesIndex(['params']));
@@ -168,7 +169,7 @@ export const createCapsuleFiles = ({
 
     recordFile(compFile, path.join(targetDir, compFile), selectedFramework.compBuilder(capsuleName, pascalName, templateOpts));
     recordFile('index.ts', path.join(targetDir, 'index.ts'), buildIndex(capsuleName, pascalName, selectedFramework.ext, hasController));
-    recordFile(specFile, path.join(targetDir, specFile), buildComponentSpec(capsuleName, pascalName, hasController));
+    recordFile(specFile, path.join(targetDir, specFile), buildComponentSpec(capsuleName, pascalName, hasController, runner));
 
     recordFile('types/props.d.ts', path.join(typesDir, 'props.d.ts'), buildPropsType(capsuleName, pascalName, { description: capsuleDesc }));
     recordFile('types/state.d.ts', path.join(typesDir, 'state.d.ts'), buildStateType(capsuleName, pascalName, { description: capsuleDesc }));

package/cli/generator.spec.js

@@ -198,5 +198,62 @@ test('runGenerateWizard: --json with --help returns help object without mutation
   assert.strictEqual(res.help, true);
 });
 
+test('runGenerateWizard: description-driven task list wires addItem, toggleItem, removeItem and avoids implicit any or as any', async () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-gen-tasklist');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  const res = await runGenerateWizard([
+    'molecule',
+    'task-list',
+    '-y',
+    `--dir=${tmpDir}`,
+    '--framework=react',
+    '--desc=add, toggle, and remove tasks'
+  ]);
+
+  assert.strictEqual(res.success, true);
+  const capsuleDir = path.join(tmpDir, 'm-task-list');
+  const tsxContent = fs.readFileSync(path.join(capsuleDir, 'm-task-list.tsx'), 'utf8');
+  const controllerContent = fs.readFileSync(path.join(capsuleDir, 'm-task-list.controller.ts'), 'utf8');
+
+  // Verify all actions are destructured and wired in UI
+  assert.ok(tsxContent.includes('addItem'));
+  assert.ok(tsxContent.includes('toggleItem'));
+  assert.ok(tsxContent.includes('removeItem'));
+  assert.ok(tsxContent.includes('<form'));
+  assert.ok(!tsxContent.includes('as any'));
+
+  // Verify controller has explicit types and no implicit any
+  assert.ok(controllerContent.includes('(i: TaskListItem)'));
+  assert.ok(!controllerContent.includes('(i) =>'));
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('runGenerateWizard: spec uses Vitest imports when vitest is declared in package.json', async () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-gen-vitest');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({
+    name: 'test-project',
+    devDependencies: { vitest: '^1.6.0' }
+  }));
+
+  const res = await runGenerateWizard([
+    'molecule',
+    'demo-card',
+    '-y',
+    `--dir=${tmpDir}`,
+    '--framework=react'
+  ]);
+
+  assert.strictEqual(res.success, true);
+  const specContent = fs.readFileSync(path.join(tmpDir, 'm-demo-card/m-demo-card.spec.ts'), 'utf8');
+  assert.ok(specContent.includes("from 'vitest'"));
+  assert.ok(!specContent.includes("from 'node:test'"));
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
 
 

package/cli/help.spec.js

@@ -1,5 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
 import { COMMANDS_SCHEMA } from './commands-schema.js';
 import { printHelp } from './help.js';
 
@@ -25,3 +27,13 @@ test('help: printHelp renders without throwing', () => {
     printHelp();
   });
 });
+
+test('cli: unknown command exits immediately with code 1 and error message', () => {
+  const cliPath = path.resolve('cli/index.js');
+  const res = spawnSync(process.execPath, [cliPath, 'config'], {
+    encoding: 'utf8',
+    timeout: 10000
+  });
+  assert.strictEqual(res.status, 1);
+  assert.ok(res.stderr.includes('Unknown command "config"'));
+});

package/cli/index.js

@@ -3,6 +3,7 @@
 import './silence-warnings.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   runAudit as executeAstAudit,
   auditFile,
@@ -83,7 +84,10 @@ const loadProjectConfig = () => {
   }
 };
 const isCreateInvoked =
-  invokedBin.includes('create-chemx') || (rawArgs[0] && rawArgs[0] === 'create');
+  invokedBin.includes('create') ||
+  Boolean(process.argv[1] && process.argv[1].includes('create-chemx')) ||
+  Boolean(process.env.npm_lifecycle_event && process.env.npm_lifecycle_event.includes('create')) ||
+  Boolean(rawArgs[0] && (rawArgs[0] === 'create' || rawArgs[0] === 'init' || rawArgs[0] === 'scaffold'));
 
 export const runAudit = async (customDir = null, isCli = false) => {
   const projectConfig = loadProjectConfig();
@@ -293,7 +297,10 @@ const main = async () => {
   const firstArg = rawArgs[0];
 
   if (isCreateInvoked) {
-    const dirArg = firstArg === 'create' ? rawArgs[1] : firstArg;
+    const nonFlagArgs = rawArgs.filter((arg) => !arg.startsWith('-'));
+    const dirArg = (nonFlagArgs[0] === 'create' || nonFlagArgs[0] === 'init' || nonFlagArgs[0] === 'scaffold')
+      ? nonFlagArgs[1]
+      : nonFlagArgs[0];
     await runScaffold(dirArg, rawArgs, runAudit);
     return;
   }
@@ -339,9 +346,11 @@ const main = async () => {
     case 'init':
       await runInit(rawArgs[1] || 'src/chemical-x', rawArgs, runAudit);
       break;
-    case 'create':
-      await runScaffold(rawArgs[1], rawArgs, runAudit);
+    case 'create': {
+      const nonFlagArgs = rawArgs.slice(1).filter((arg) => !arg.startsWith('-'));
+      await runScaffold(nonFlagArgs[0], rawArgs, runAudit);
       break;
+    }
     case 'hook':
     case 'hooks':
     case 'install-hooks':
@@ -420,22 +429,37 @@ const main = async () => {
       printHelp();
       break;
     default:
-      if (firstArg && isCapsulePrefix(firstArg)) {
+      if (!firstArg) {
+        printHelp();
+      } else if (isCapsulePrefix(firstArg)) {
         await runGenerateWizard(rawArgs);
-      } else if (firstArg && !firstArg.startsWith('-')) {
-        await runScaffold(firstArg, rawArgs, runAudit);
       } else {
-        printHelp();
+        process.stderr.write(`\x1b[31mError:\x1b[0m Unknown command "${firstArg}".\n`);
+        process.stderr.write(`Run "chemx --help" for a list of available commands.\n\n`);
+        process.exit(1);
       }
       break;
   }
 };
 
-main().catch(async (err) => {
-  await handleError(err, {
-    command: process.argv.slice(2).join(' '),
-    cwd: process.cwd(),
-    exitCode: 1
+const isDirectExecution = () => {
+  if (!process.argv[1]) return false;
+  try {
+    const currentFile = fileURLToPath(import.meta.url);
+    const invokedFile = fs.realpathSync(process.argv[1]);
+    return currentFile === invokedFile;
+  } catch {
+    return false;
+  }
+};
+
+if (isDirectExecution()) {
+  main().catch(async (err) => {
+    await handleError(err, {
+      command: process.argv.slice(2).join(' '),
+      cwd: process.cwd(),
+      exitCode: 1
+    });
+    process.exit(1);
   });
-  process.exit(1);
-});
+}

package/cli/license.js

@@ -117,9 +117,10 @@ export const obtainLicenseKey = async (rawArgs = [], onRunAudit = null) => {
     rawArgs.includes('--non-interactive') ||
     rawArgs.includes('--no-interactive') ||
     Boolean(process.env.CI) ||
-    process.stdout?.isTTY === false ||
-    process.stdin?.isTTY === false ||
-    Boolean(process.argv?.some((arg) => arg === '--headless' || arg === '--ci' || arg === '--yes' || arg === '-y'));
+    !process.stdout?.isTTY ||
+    !process.stdin?.isTTY ||
+    process.env.TERM === 'dumb' ||
+    Boolean(process.argv?.some((arg) => arg === '--headless' || arg === '--ci' || arg === '--yes' || arg === '-y' || arg === '--non-interactive'));
 
   if (isHeadless) {
     return null;

package/cli/project-detector.js

@@ -35,6 +35,27 @@ export const detectFramework = (cwd = process.cwd()) => {
   return 'react';
 };
 
+export const detectTestRunner = (startDir = process.cwd()) => {
+  let curr = path.resolve(startDir);
+  while (curr && curr !== path.dirname(curr)) {
+    const pkgPath = path.join(curr, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        if (deps.vitest || (pkg.scripts?.test && pkg.scripts.test.includes('vitest'))) return 'vitest';
+        if (deps.jest || (pkg.scripts?.test && pkg.scripts.test.includes('jest'))) return 'jest';
+      } catch {
+        // ignore
+      }
+      break;
+    }
+    curr = path.dirname(curr);
+  }
+
+  return 'node:test';
+};
+
 const ATOMS_PACKAGES = ['@chemx/x-atoms', '@chemx/atoms', 'x-atoms', '@chem-x/x-atoms'];
 const PALETTE_PACKAGES = ['@chemx/o-command-palette', '@chemx/command-palette', 'o-command-palette', '@chem-x/o-command-palette'];
 

package/cli/scaffold.js

@@ -25,7 +25,7 @@ export const runScaffold = async (projectName, rawArgs = [], onRunAudit = null)
     files = await fetchStarterKitFiles(licenseKey);
   }
 
-  let targetName = projectName;
+  let targetName = (projectName && !projectName.startsWith('-')) ? projectName : null;
   if (!targetName) {
     const isHeadless =
       rawArgs.includes('--headless') ||

package/cli/team/team-triage.js

@@ -139,7 +139,7 @@ export const completeTaskWithAudit = (db, taskId, agentId, options = {}) => {
     if (fs.existsSync(fullPath)) {
       try {
         const auditRes = auditFile(fullPath, task.target_path);
-        const remainingHazards = auditRes?.fileViolations || [];
+        const remainingHazards = Array.isArray(auditRes) ? auditRes : (auditRes?.fileViolations || auditRes?.violations || []);
         hazardCount = remainingHazards.length;
         healthScore = Math.max(0, 100 - hazardCount * 15);
         verified = hazardCount === 0;
@@ -151,6 +151,7 @@ export const completeTaskWithAudit = (db, taskId, agentId, options = {}) => {
         if (hazardCount > 0 && options.force !== true) {
           return {
             refused: true,
+            verified: false,
             taskId: Number(taskId),
             taskTitle: task.title,
             hazardCount,

package/cli/team/team.spec.js

@@ -487,3 +487,31 @@ test('team-commands: runTeamCli handles task update and re-verifies AST upon com
   }
 });
 
+test('team-triage: completeTaskWithAudit correctly detects real on-disk violations and refuses completion', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-task-audit-'));
+  const testFile = path.join(tmpDir, 'm-test-hazard.tsx');
+  fs.writeFileSync(
+    testFile,
+    `import React from 'react';\nexport const MTest = () => {\n  return <div><button>Violating Raw Button</button></div>;\n};\nexport default MTest;\n`
+  );
+
+  const db = setupTestDb();
+  const task = createTask(db, {
+    title: 'Fix raw button in molecule',
+    target_path: testFile
+  });
+
+  const res = completeTaskWithAudit(db, task.id, '@auditor', { cwd: tmpDir });
+  assert.strictEqual(res.refused, true);
+  assert.ok(res.hazardCount > 0);
+  assert.strictEqual(res.verified, false);
+
+  // With force: true, completion succeeds with forced flag
+  const forced = completeTaskWithAudit(db, task.id, '@auditor', { cwd: tmpDir, force: true });
+  assert.ok(forced.id);
+  assert.strictEqual(forced.status, 'done');
+  assert.strictEqual(forced.result_payload.forced, true);
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@chem-x/starter-kit",
-  "version": "26.9.20-1257",
+  "version": "26.9.20-1318",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {
-    "create-chemx": "cli/index.js",
+    "create-chemx": "cli/create.js",
     "chemx": "cli/index.js",
     "chem-x": "cli/index.js",
     "chemical-x": "cli/index.js"

package/scripts/publish-both.mjs

@@ -26,13 +26,13 @@ const TARGETS = [
   {
     name: 'create-chemx',
     isScoped: false,
-    bin: { 'create-chemx': 'cli/index.js', chemx: 'cli/index.js' }
+    bin: { 'create-chemx': 'cli/create.js', chemx: 'cli/index.js' }
   },
   {
     name: '@chemx/starter-kit',
     isScoped: true,
     bin: {
-      'create-chemx': 'cli/index.js',
+      'create-chemx': 'cli/create.js',
       chemx: 'cli/index.js',
       'chem-x': 'cli/index.js',
       'chemical-x': 'cli/index.js'
@@ -42,7 +42,7 @@ const TARGETS = [
     name: '@chem-x/starter-kit',
     isScoped: true,
     bin: {
-      'create-chemx': 'cli/index.js',
+      'create-chemx': 'cli/create.js',
       chemx: 'cli/index.js',
       'chem-x': 'cli/index.js',
       'chemical-x': 'cli/index.js'
@@ -51,17 +51,17 @@ const TARGETS = [
   {
     name: '@chemx/create-chemx',
     isScoped: true,
-    bin: { 'create-chemx': 'cli/index.js', chemx: 'cli/index.js' }
+    bin: { 'create-chemx': 'cli/create.js', chemx: 'cli/index.js' }
   },
   {
     name: '@chem-x/create-chemx',
     isScoped: true,
-    bin: { 'create-chemx': 'cli/index.js', chemx: 'cli/index.js' }
+    bin: { 'create-chemx': 'cli/create.js', chemx: 'cli/index.js' }
   },
   {
     name: 'chemx',
     isScoped: false,
-    bin: { chemx: 'cli/index.js', 'create-chemx': 'cli/index.js' }
+    bin: { chemx: 'cli/index.js', 'create-chemx': 'cli/create.js' }
   }
 ];