@chem-x/starter-kit 26.9.20-1298 → 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).

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/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':
@@ -433,11 +442,24 @@ const main = async () => {
   }
 };
 
-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/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/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@chem-x/starter-kit",
-  "version": "26.9.20-1298",
+  "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' }
   }
 ];