@chemx/starter-kit 26.9.20-408 → 26.9.21-8

package/cli/commands/cmd-router.js

@@ -0,0 +1,190 @@
+/**
+ * cmd-router.js — CLI command dispatch table.
+ * Single responsibility: map first-arg tokens to their lazy-loaded command handlers.
+ * Extracted from cli/index.js per Directive 1.A (Monolith Decomposition).
+ */
+
+import { printHelp } from '../help.js';
+
+/**
+ * Dispatch the resolved CLI command to its handler module.
+ * @param {string} firstArg
+ * @param {string[]} rawArgs
+ * @param {(dir: string|null, isCli: boolean) => Promise<object>} runAudit
+ * @param {() => string} getPackageVersion
+ * @param {(arg: string) => boolean} isCapsulePrefix
+ */
+export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVersion, isCapsulePrefix) => {
+  switch (firstArg) {
+    case 'team':
+    case 'swarm':
+    case 'feed': {
+      const { runTeamCli } = await import('../team/index.js');
+      runTeamCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'mcp':
+    case 'mcp-server':
+    case 'server': {
+      const { runMcpServer } = await import('../mcp/index.js');
+      await runMcpServer(rawArgs.slice(1));
+      break;
+    }
+    case 'read':
+    case 'view': {
+      const { runReaderCli } = await import('../reader.js');
+      runReaderCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'patch':
+    case 'edit': {
+      const { runPatcherCli } = await import('../patcher.js');
+      runPatcherCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'write': {
+      const { runWriterCli } = await import('../patcher.js');
+      runWriterCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'search':
+    case 'q':
+    case 'query':
+    case 'find': {
+      const { runSearch } = await import('../search.js');
+      await runSearch(rawArgs.slice(1), true);
+      break;
+    }
+    case 'build':
+    case 'run':
+    case 'wrap': {
+      const { runBuildAudit } = await import('../build.js');
+      await runBuildAudit(rawArgs.slice(1), true);
+      break;
+    }
+    case 'audit': {
+      const posDir = (rawArgs[1] && !rawArgs[1].startsWith('-')) ? rawArgs[1] : null;
+      await runAudit(posDir, true);
+      break;
+    }
+    case 'init': {
+      const { runInit } = await import('../scaffold.js');
+      await runInit(rawArgs[1] || 'src/chemical-x', rawArgs, runAudit);
+      break;
+    }
+    case 'create':
+    case 'scaffold': {
+      const { runScaffold } = await import('../scaffold.js');
+      const nonFlagArgs = rawArgs.slice(1).filter((arg) => !arg.startsWith('-'));
+      await runScaffold(nonFlagArgs[0], rawArgs, runAudit);
+      break;
+    }
+    case 'hook':
+    case 'hooks':
+    case 'install-hooks':
+    case 'setup-ci': {
+      const { runInstallWizard } = await import('../installer.js');
+      await runInstallWizard(rawArgs[1] || process.cwd());
+      break;
+    }
+    case 'pillars':
+    case 'rules':
+    case 'config:pillars': {
+      const { runPillarsWizard } = await import('../pillars-wizard.js');
+      await runPillarsWizard(rawArgs.slice(1), process.cwd());
+      break;
+    }
+    case 'check': {
+      const { handleCheckCommand } = await import('../search.js');
+      handleCheckCommand(rawArgs[1], { isJson: rawArgs.includes('--json'), isCli: true });
+      break;
+    }
+    case 'add:prop':
+    case 'add:state':
+    case 'add:action':
+    case 'fix': {
+      const { runMutatorCli } = await import('../mutators.js');
+      await runMutatorCli(rawArgs, true);
+      break;
+    }
+    case 'add': {
+      if (['prop', 'state', 'action'].includes(rawArgs[1])) {
+        const { runMutatorCli } = await import('../mutators.js');
+        await runMutatorCli(rawArgs, true);
+      } else {
+        const { runGenerateWizard } = await import('../scaffold.js');
+        await runGenerateWizard(rawArgs.slice(1));
+      }
+      break;
+    }
+    case 'g':
+    case 'gen':
+    case 'generate':
+    case 'capsule': {
+      const { runGenerateWizard } = await import('../scaffold.js');
+      await runGenerateWizard(rawArgs.slice(1));
+      break;
+    }
+    case 'badge':
+    case 'badges': {
+      const { runBadgeCommand } = await import('../badge.js');
+      await runBadgeCommand(rawArgs.slice(1));
+      break;
+    }
+    case 'install-mcp':
+    case 'setup-mcp': {
+      const { runMcpInstaller } = await import('../mcp/index.js');
+      await runMcpInstaller(rawArgs.slice(1));
+      break;
+    }
+    case '-v':
+    case '--version':
+    case 'version':
+      process.stdout.write(`create-chemx v${getPackageVersion()}\n`);
+      break;
+    case 'verify':
+    case 'check:all': {
+      const { runProjectVerify } = await import('../verify.js');
+      await runProjectVerify(rawArgs.slice(1), true);
+      break;
+    }
+    case 'typecheck':
+    case 'check:types':
+    case 'tsc': {
+      const { runTypecheckAudit } = await import('../verify.js');
+      await runTypecheckAudit(rawArgs.slice(1), true);
+      break;
+    }
+    case 'test':
+    case 'tests':
+    case 'check:test': {
+      const { runTestAudit } = await import('../verify.js');
+      await runTestAudit(rawArgs.slice(1), true);
+      break;
+    }
+    case 'ui':
+    case 'preview':
+    case 'dashboard': {
+      const { startUiServer } = await import('../ui-server.js');
+      const portArg = rawArgs.find((a) => a.startsWith('--port='));
+      const port = portArg ? parseInt(portArg.split('=')[1], 10) : 4173;
+      await startUiServer({ port, isCli: true, cwd: process.cwd() });
+      break;
+    }
+    case 'help':
+    case '--help':
+    case '-h':
+      printHelp();
+      break;
+    default: {
+      if (isCapsulePrefix(firstArg)) {
+        const { runGenerateWizard } = await import('../scaffold.js');
+        await runGenerateWizard(rawArgs);
+      } else {
+        process.stderr.write(`Unknown command "${firstArg}". Run --help for usage.\n`);
+        process.exit(1);
+      }
+      break;
+    }
+  }
+};

package/cli/commands-schema.js

@@ -0,0 +1,198 @@
+/**
+ * Chemical X Protocol: Canonical Command Schema
+ * Single source of truth for CLI commands, aliases, flags, descriptions, and examples.
+ */
+
+export const COMMANDS_SCHEMA = [
+  {
+    name: 'search',
+    aliases: ['q', 'query', 'find'],
+    usage: 'npx chemx search [query] [options]',
+    summary: 'Architecture-aware AST codebase query engine powered by SQLite (.chemx/index.db).',
+    description: 'Instantly indexes component tiers (atom/molecule/organism), exported symbols, props, and hooks. Designed for AI agents to replace token-heavy grep/cat scans.',
+    flags: [
+      { flag: '--json', desc: 'Minified JSON format for LLM agents' },
+      { flag: '--columnar', desc: 'Token-compact columnar format (cols/rows) for agent pipelines' },
+      { flag: '-i, --inspect', desc: 'Inspect props and hooks without full source' },
+      { flag: '--tier=<tier>', desc: 'Filter by tier: atom, molecule, organism, hook, view' },
+      { flag: '--blast-radius', desc: 'Map direct consumers, transitive dependents & impacted tiers (aliases: --blast, --impact)' },
+      { flag: '--max-depth=<N>', desc: 'Max depth for blast radius traversal (default: 5)' },
+      { flag: '--semantic', desc: 'Concept search via vector cosine similarity' },
+      { flag: '--hybrid', desc: 'Blended BM25 keyword + Vector RRF ranking' },
+      { flag: '--hazards', desc: 'Query architectural rule violations directly (flags: --rule=<id>, --critical)' },
+      { flag: '--pack', desc: 'Assemble token-packed context bundle for target symbol or file' },
+      { flag: '--reindex', desc: 'Force re-index before running query' }
+    ],
+    examples: [
+      'npx chemx search "badge"',
+      'pnpm q a-button --blast-radius --json',
+      'pnpm q "button click handler" --semantic',
+      'pnpm q "useAttentionCardController" --hybrid --json',
+      'pnpm q "useTheme" --inspect',
+      'npx chemx search "card" --tier=molecule'
+    ]
+  },
+  {
+    name: 'read',
+    aliases: ['view'],
+    usage: 'npx chemx read <file> [options]',
+    summary: 'Token-minified file reader with AST outline extraction.',
+    description: 'Extracts structural AST outlines, stripped comments, line ranges, or targeted symbol declarations to minimize LLM context token consumption.',
+    flags: [
+      { flag: '--outline', desc: 'Signatures only (80%+ token savings)' },
+      { flag: '--symbol=<name>', desc: 'Target a specific symbol definition' },
+      { flag: '--connections', desc: 'Include caller graph and dependent references alongside symbol' },
+      { flag: '--strip-comments', desc: 'Remove all code comments' },
+      { flag: '--compact', desc: 'Remove blank lines and indentation' },
+      { flag: '--start=<N>', desc: 'Starting line number' },
+      { flag: '--end=<N>', desc: 'Ending line number' },
+      { flag: '--json', desc: 'Output metadata as JSON' }
+    ],
+    examples: [
+      'npx chemx read src/store.ts --outline',
+      'npx chemx read api.ts --symbol=login --connections',
+      'npx chemx read src/ui/atoms/a-button/types.d.ts --symbol=ButtonVariant'
+    ]
+  },
+  {
+    name: 'patch',
+    aliases: ['edit'],
+    usage: 'npx chemx patch <file> [options]',
+    summary: 'Surgically patch a target file using exact search and replacement blocks.',
+    description: 'Replaces targeted text blocks with automatic SQLite micro-indexing and architectural line budget verification.',
+    flags: [
+      { flag: '--target="<old>"', desc: 'Exact text block to replace' },
+      { flag: '--replacement="<new>"', desc: 'New replacement content' },
+      { flag: '--multiple', desc: 'Allow replacing multiple occurrences' },
+      { flag: '--dry-run', desc: 'Preview patch without writing to disk' },
+      { flag: '--json', desc: 'Output result as minified JSON' }
+    ],
+    examples: [
+      'npx chemx patch src/api.ts --target="v1" --replacement="v2"',
+      'npx chemx patch src/App.tsx --target="oldCode" --replacement="newCode" --dry-run'
+    ]
+  },
+  {
+    name: 'mcp',
+    aliases: ['server', 'mcp-server'],
+    usage: 'npx chemx mcp [options]',
+    summary: 'Launch the native Chemical X Model Context Protocol (MCP) Stdio server.',
+    description: 'Exposes token-minified tools (chemx_q, chemx_read, chemx_patch, chemx_audit, chemx_team_task) over JSON-RPC 2.0 stdio transport.',
+    flags: [
+      { flag: '--install', desc: 'Install and register MCP server in host client settings' },
+      { flag: '--sync', desc: 'Sync Antigravity MCP tool schema definitions and instructions' }
+    ],
+    examples: [
+      'npx chemx mcp',
+      'pnpm chemx:mcp',
+      'npx chemx mcp --sync'
+    ]
+  },
+  {
+    name: 'build',
+    aliases: ['run', 'wrap'],
+    usage: 'npx chemx build [options] [-- <command>]',
+    summary: 'Wrap and audit build scripts with token-conserving silent execution.',
+    description: 'Suppresses multi-thousand-line compiler noise, catalogs diagnostics into grouped categories, and provides actionable hints for AI agents.',
+    flags: [
+      { flag: '--json', desc: 'Minified JSON format with categorised diagnostics' },
+      { flag: '--command="<cmd>"', desc: 'Explicit build command (default: npm run build)' }
+    ],
+    examples: [
+      'npx chemx build',
+      'npx chemx build -- vite build'
+    ]
+  },
+  {
+    name: 'audit',
+    aliases: [],
+    usage: 'npx chemx audit [directory] [options]',
+    summary: 'Execute full architectural AST audit on codebase.',
+    description: 'Validates line budgets, molecular separation, zero-raw-DOM rules, and populates SQLite index tables.',
+    flags: [
+      { flag: '--triage', desc: 'Auto-convert unassigned hazards into team tasks' },
+      { flag: '--strict', desc: 'Fail on any architectural hazard' },
+      { flag: '--json', desc: 'Output structured audit report as JSON' },
+      { flag: '--markdown', desc: 'Generate Markdown audit report' },
+      { flag: '--min-grade=<A|B|C|D|F>', desc: 'Minimum acceptable architectural grade' }
+    ],
+    examples: [
+      'npx chemx audit',
+      'npx chemx audit --triage',
+      'npx chemx audit --strict --min-grade=A'
+    ]
+  },
+  {
+    name: 'generate',
+    aliases: ['g', 'gen', 'capsule'],
+    usage: 'npx chemx generate [tier] <name> [options]',
+    summary: 'Scaffold crystalline molecular capsules under 100 lines.',
+    description: 'Generates self-contained component capsules with co-located controllers, granular domain types, styles, and specs.',
+    flags: [
+      { flag: '--desc="<text>"', desc: 'Describe functionality to tailor archetype and state' },
+      { flag: '--dry-run', desc: 'Preview planned files and lines without touching disk' },
+      { flag: '--tier=<tier>', desc: 'Specify tier: atom, molecule, organism, hook, view' },
+      { flag: '--framework=<id>', desc: 'Framework flavor: react, vue, svelte' },
+      { flag: '--lean', desc: 'Generate minimal capsule without controller/spec' }
+    ],
+    examples: [
+      'npx chemx generate m-task-list --framework=react',
+      'npx chemx generate m-task-list --desc="add, toggle, remove items"',
+      'npx chemx generate m-task-list --dry-run'
+    ]
+  },
+  {
+    name: 'team',
+    aliases: ['swarm', 'feed'],
+    usage: 'npx chemx team <status|feed|task|lock|post> [options]',
+    summary: 'Multi-agent coordination layer backed by SQLite (.chemx/index.db).',
+    description: 'Manages autonomous agent task queues, status transitions, AST verification on completion, and file locks.',
+    flags: [
+      { flag: '--as=<@handle>', desc: 'Agent identity handle (e.g. @claude, @antigravity)' },
+      { flag: '--target=<path>', desc: 'Target file path for task AST verification' },
+      { flag: '--no-target-confirm', desc: 'Confirm completing a task that has no target file without verification' },
+      { flag: '--force, -f', desc: 'Force complete task even if hazards remain' },
+      { flag: '--tokens=<N>', desc: 'Prompt tokens consumed by task' },
+      { flag: '--cost=<USD>', desc: 'Estimated dollar cost for task' },
+      { flag: '--json', desc: 'Output data as JSON' }
+    ],
+    examples: [
+      'npx chemx team task list',
+      'npx chemx team task triage',
+      'npx chemx team task add "Implement dark mode toggle" --prio=1',
+      'npx chemx team task claim 1 --as=@coder',
+      'npx chemx team task done 1 --as=@coder --force'
+    ]
+  },
+  {
+    name: 'verify',
+    aliases: ['check:all'],
+    usage: 'npx chemx verify [options]',
+    summary: 'Runs full verification pipeline: AST audit, TypeScript typecheck, and test suite.',
+    description: 'Compact single-card verification returning token-efficient output for AI agents (~45 tokens when green).',
+    flags: [
+      { flag: '--json', desc: 'Minified JSON format' }
+    ],
+    examples: [
+      'npx chemx verify',
+      'pnpm chemx verify --json'
+    ]
+  },
+  {
+    name: 'pillars',
+    aliases: ['config:pillars', 'rules'],
+    usage: 'npx chemx pillars [options]',
+    summary: 'Interactive wizard to configure architectural pillars and agent steering directives.',
+    description: 'Customize which pillars and directives (AGENTS.md, .cursorrules) are installed in your codebase.',
+    flags: [
+      { flag: '--preset=<recommended|strict|minimal|none>', desc: 'Apply a predefined pillar configuration preset' },
+      { flag: '--dry-run', desc: 'Preview pillar configuration without writing files' },
+      { flag: '--json', desc: 'Output configuration as JSON' }
+    ],
+    examples: [
+      'npx chemx pillars',
+      'npx chemx pillars --preset=recommended',
+      'npx chemx pillars --preset=minimal --dry-run'
+    ]
+  }
+];

package/cli/create.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+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);
+
+if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+  process.stdout.write(`
+Chemical X Protocol: Project Scaffolder
+
+USAGE
+  npm create chemx [directory] [options]
+  npx create-chemx [directory] [options]
+
+OPTIONS
+  --yes, -y       Skip interactive prompts and scaffold Community Edition immediately
+  --headless      Run in headless mode for CI/CD and AI agent automation
+  -h, --help      Show this help message
+  -v, --version   Show version number
+
+EXAMPLES
+  npm create chemx my-molecular-app
+  npx create-chemx my-molecular-app --yes
+  pnpm create chemx my-app
+
+DOCUMENTATION
+  https://chemicalx.xophz.com
+\n`);
+  process.exit(0);
+}
+
+if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
+  try {
+    const pkgPath = new URL('../package.json', import.meta.url);
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    process.stdout.write(`create-chemx v${pkg.version || 'unknown'}\n`);
+  } catch {
+    process.stdout.write('create-chemx\n');
+  }
+  process.exit(0);
+}
+
+const KNOWN_FLAGS = new Set([
+  '--yes', '-y',
+  '--headless',
+  '-h', '--help',
+  '-v', '--version',
+  '--ci',
+  '--non-interactive',
+  '--no-interactive'
+]);
+
+for (const arg of rawArgs) {
+  if (arg.startsWith('-') && !KNOWN_FLAGS.has(arg)) {
+    process.stderr.write(`Unknown option "${arg}". Run --help for usage.\n`);
+    process.exit(1);
+  }
+}
+
+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,200 @@
+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 --help prints usage and does not scaffold', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+
+    const result = spawnSync('node', [CREATE_BIN, '--help'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 5000
+    });
+
+    assert.equal(result.status, 0, 'Should exit with code 0 on --help');
+    assert.match(result.stdout, /Chemical X Protocol: Project Scaffolder/, 'Should show scaffolder help');
+    assert.ok(!fs.existsSync(path.join(tmpBase, 'my-molecular-app')), 'Must not scaffold any directory on --help');
+  });
+
+  test('node cli/create.js --version prints version and does not scaffold', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+
+    const result = spawnSync('node', [CREATE_BIN, '--version'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      timeout: 5000
+    });
+
+    assert.equal(result.status, 0, 'Should exit with code 0 on --version');
+    assert.match(result.stdout, /create-chemx v/, 'Should print create-chemx version');
+    assert.ok(!fs.existsSync(path.join(tmpBase, 'my-molecular-app')), 'Must not scaffold any directory on --version');
+  });
+
+  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 fails fast as unknown command without creating directory', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+
+    const result = spawnSync('node', [INDEX_BIN, 'config'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      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');
+    assert.ok(!fs.existsSync(path.join(tmpBase, 'config')), 'Must NOT create a config directory');
+  });
+
+  test('node cli/index.js under create-chemx path STILL fails fast on unknown command (regression test)', () => {
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-test-'));
+    cleanupDirs.push(tmpBase);
+    // Simulate being installed inside a path with "create-chemx" in its name
+    const pkgDir = path.join(tmpBase, 'node_modules', '@chemx', 'create-chemx', 'cli');
+    fs.mkdirSync(pkgDir, { recursive: true });
+    const fakeIndex = path.join(pkgDir, 'index.js');
+    fs.symlinkSync(INDEX_BIN, fakeIndex);
+
+    const result = spawnSync('node', [fakeIndex, 'config'], {
+      encoding: 'utf-8',
+      cwd: tmpBase,
+      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');
+    assert.ok(!fs.existsSync(path.join(tmpBase, 'config')), 'Must NOT create a config directory when installed under create-chemx path');
+  });
+});