@chemx/create-chemx 26.9.25-747 → 26.9.25-789

package/cli/commands/cmd-router.js

@@ -94,12 +94,26 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       break;
     }
     case 'init': {
+      const isHelpRequested = rawArgs.includes('--help') || rawArgs.includes('-h') || rawArgs[1] === 'help';
+      if (isHelpRequested) {
+        const { printInitHelp } = await import('../help.js');
+        printInitHelp();
+        break;
+      }
+      const nonFlagArgs = rawArgs.slice(1).filter((arg) => !arg.startsWith('-'));
+      const targetSubDir = nonFlagArgs[0] || 'src/chemical-x';
       const { runInit } = await import('../scaffold.js');
-      await runInit(rawArgs[1] || 'src/chemical-x', rawArgs, runAudit);
+      await runInit(targetSubDir, rawArgs, runAudit);
       break;
     }
     case 'create':
     case 'scaffold': {
+      const isHelpRequested = rawArgs.includes('--help') || rawArgs.includes('-h') || rawArgs[1] === 'help';
+      if (isHelpRequested) {
+        const { printScaffoldHelp } = await import('../help.js');
+        printScaffoldHelp();
+        break;
+      }
       const { runScaffold } = await import('../scaffold.js');
       const nonFlagArgs = rawArgs.slice(1).filter((arg) => !arg.startsWith('-'));
       await runScaffold(nonFlagArgs[0], rawArgs, runAudit);

package/cli/commands-schema.js

@@ -222,5 +222,41 @@ export const COMMANDS_SCHEMA = [
       'npx chemx tesseract',
       'npx chemx tesseract --json'
     ]
+  },
+  {
+    name: 'init',
+    aliases: [],
+    usage: 'npx chemx init [directory] [options]',
+    summary: 'Unpack blueprints and molecular architecture drop-in files into an existing codebase.',
+    description: 'Installs blueprints, domain hooks, and foundation capsules into target directory (default: src/chemical-x).',
+    flags: [
+      { flag: '-h, --help', desc: 'Show this help message' },
+      { flag: '--license=<key>', desc: 'Provide commercial license key for enterprise starter kit assets' }
+    ],
+    examples: [
+      'npx chemx init',
+      'npx chemx init src/chemical-x',
+      'npx chemx init packages/ui/src/modules'
+    ]
+  },
+  {
+    name: 'create',
+    aliases: ['scaffold'],
+    usage: 'npm create chemx [directory] [options]',
+    summary: 'Scaffold a complete new Chemical X Molecular Architecture application.',
+    description: 'Generates a full starter project configured with Chemical X molecular architecture, framework presets, and agent steering directives.',
+    flags: [
+      { flag: '--framework=<id>', desc: 'Framework flavor: react (default), vue, svelte' },
+      { flag: '--yes, -y', desc: 'Skip interactive prompts and scaffold Community Edition immediately' },
+      { flag: '--install', desc: 'Auto-install dependencies after scaffolding' },
+      { flag: '--headless', desc: 'Run in headless mode for CI/CD and AI agent automation' },
+      { flag: '-h, --help', desc: 'Show this help message' },
+      { flag: '-v, --version', desc: 'Show version number' }
+    ],
+    examples: [
+      'npm create chemx my-molecular-app --framework=react',
+      'npx create-chemx my-vue-app --framework=vue --yes',
+      'npx chemx create my-app --framework=svelte --install'
+    ]
   }
 ];

package/cli/help.d.ts

@@ -1 +1,3 @@
 export declare function printHelp(): void;
+export declare function printInitHelp(): void;
+export declare function printScaffoldHelp(): void;

package/cli/help.js

@@ -54,3 +54,67 @@ export const printHelp = () => {
 
   process.stdout.write(lines.join('\n'));
 };
+
+export const printInitHelp = () => {
+  renderBanner('Chemical X: In-Repo Capsule Drop-in (chemx init)');
+
+  const BOLD = '\x1b[1m';
+  const CYAN = '\x1b[36m';
+  const RESET = '\x1b[0m';
+
+  const lines = [
+    `${BOLD}USAGE${RESET}`,
+    `  ${CYAN}npx chemx init${RESET} [directory] [options]`,
+    '',
+    `${BOLD}DESCRIPTION${RESET}`,
+    '  Unpack Chemical X blueprints and molecular architecture drop-in files',
+    '  into an existing codebase (defaults to src/chemical-x).',
+    '',
+    `${BOLD}OPTIONS${RESET}`,
+    `  ${CYAN}-h, --help${RESET}           Show this help message`,
+    `  ${CYAN}--license=<key>${RESET}     Provide commercial license key for enterprise starter kit assets`,
+    '',
+    `${BOLD}EXAMPLES${RESET}`,
+    `  ${CYAN}npx chemx init${RESET}`,
+    `  ${CYAN}npx chemx init src/chemical-x${RESET}`,
+    `  ${CYAN}npx chemx init packages/ui/src/modules${RESET}`,
+    ''
+  ];
+
+  process.stdout.write(lines.join('\n'));
+};
+
+export const printScaffoldHelp = () => {
+  renderBanner('Chemical X: Project Scaffolder (npm create chemx)');
+
+  const BOLD = '\x1b[1m';
+  const CYAN = '\x1b[36m';
+  const RESET = '\x1b[0m';
+
+  const lines = [
+    `${BOLD}USAGE${RESET}`,
+    `  ${CYAN}npm create chemx${RESET} [directory] [options]`,
+    `  ${CYAN}npx create-chemx${RESET} [directory] [options]`,
+    `  ${CYAN}npx chemx create${RESET} [directory] [options]`,
+    '',
+    `${BOLD}DESCRIPTION${RESET}`,
+    '  Scaffold a complete new Chemical X Molecular Architecture application.',
+    '',
+    `${BOLD}OPTIONS${RESET}`,
+    `  ${CYAN}--framework=<id>${RESET}   Framework flavor: react (default), vue, svelte`,
+    `  ${CYAN}--install${RESET}          Auto-install dependencies after scaffolding`,
+    `  ${CYAN}--skip-install${RESET}     Skip installing dependencies`,
+    `  ${CYAN}--yes, -y${RESET}          Skip interactive prompts and scaffold Community Edition immediately`,
+    `  ${CYAN}--headless${RESET}         Run in headless mode for CI/CD and AI agent automation`,
+    `  ${CYAN}-h, --help${RESET}         Show this help message`,
+    `  ${CYAN}-v, --version${RESET}      Show version number`,
+    '',
+    `${BOLD}EXAMPLES${RESET}`,
+    `  ${CYAN}npm create chemx my-molecular-app --framework=react${RESET}`,
+    `  ${CYAN}npx create-chemx my-vue-app --framework=vue --yes${RESET}`,
+    `  ${CYAN}npx chemx create my-app --framework=svelte --install${RESET}`,
+    ''
+  ];
+
+  process.stdout.write(lines.join('\n'));
+};

package/cli/help.spec.js

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { COMMANDS_SCHEMA } from './commands-schema.js';
-import { printHelp } from './help.js';
+import { printHelp, printInitHelp, printScaffoldHelp } from './help.js';
 
 test('commands-schema: contains all 9 core chemical-x CLI commands', () => {
   const expected = ['search', 'read', 'patch', 'mcp', 'build', 'audit', 'generate', 'team', 'verify'];
@@ -54,3 +54,56 @@ test('cli: unknown command exits immediately with code 1 and error message', ()
     );
   }
 });
+
+test('help: printInitHelp and printScaffoldHelp render without throwing', () => {
+  assert.doesNotThrow(() => {
+    printInitHelp();
+  });
+  assert.doesNotThrow(() => {
+    printScaffoldHelp();
+  });
+});
+
+test('cli: chemx init --help and -h display usage and do not scaffold /--help/ on disk', () => {
+  const cliPath = path.resolve('cli/index.js');
+  const helpFlags = ['--help', '-h', 'help'];
+
+  for (const flag of helpFlags) {
+    const res = spawnSync(process.execPath, [cliPath, 'init', flag], {
+      encoding: 'utf8',
+      timeout: 5000
+    });
+
+    assert.strictEqual(res.status, 0, `chemx init ${flag} should exit with code 0`);
+    assert.ok(
+      res.stdout.includes('chemx init') && res.stdout.includes('USAGE'),
+      `chemx init ${flag} output should include usage instructions`
+    );
+    assert.strictEqual(
+      fs.existsSync(path.resolve(flag)),
+      false,
+      `chemx init ${flag} must not create directory "${flag}" on disk`
+    );
+  }
+});
+
+test('cli: chemx create --help and scaffold -h display usage', () => {
+  const cliPath = path.resolve('cli/index.js');
+  const commands = [
+    ['create', '--help'],
+    ['scaffold', '-h']
+  ];
+
+  for (const [cmd, flag] of commands) {
+    const res = spawnSync(process.execPath, [cliPath, cmd, flag], {
+      encoding: 'utf8',
+      timeout: 5000
+    });
+
+    assert.strictEqual(res.status, 0, `chemx ${cmd} ${flag} should exit with code 0`);
+    assert.ok(
+      res.stdout.includes('USAGE') && (res.stdout.includes('create chemx') || res.stdout.includes('chemx create')),
+      `chemx ${cmd} ${flag} output should include scaffolder usage instructions`
+    );
+  }
+});

package/cli/reader-shorthand.spec.js

@@ -49,12 +49,12 @@ describe('Reader Shorthand Syntax', () => {
   it('supports MCP chemx({ action: "r" })', async () => {
     const output = await handleChemx({ action: 'r', params: { path: 'package.json:1-3' } });
     assert.ok(output.includes('package.json'));
-    assert.ok(output.includes('"name": "@chemx/starter-kit"'));
+    assert.ok(output.includes('"name":'));
   });
 
   it('supports MCP chemx({ command: "r path:1-3" })', async () => {
     const output = await handleChemx({ command: 'r package.json:1-3' });
     assert.ok(output.includes('package.json'));
-    assert.ok(output.includes('"name": "@chemx/starter-kit"'));
+    assert.ok(output.includes('"name":'));
   });
 });

package/cli/scaffold.js

@@ -7,6 +7,7 @@ import { runPillarsWizard } from './pillars-wizard.js';
 import { resolvePackageManager } from './build/detector.js';
 import { resolveFramework } from './project-detector.js';
 import { getFrameworkConfig, buildScaffoldPackageJson } from './scaffold-frameworks.js';
+import { printInitHelp, printScaffoldHelp } from './help.js';
 
 const extractTargetName = (projectName, rawArgs) => {
   if (projectName && !projectName.startsWith('-')) return projectName;
@@ -25,6 +26,19 @@ const extractTargetName = (projectName, rawArgs) => {
 };
 
 export const runScaffold = async (projectName, rawArgs = [], onRunAudit = null) => {
+  const isHelpRequested =
+    rawArgs.includes('--help') ||
+    rawArgs.includes('-h') ||
+    rawArgs.includes('help') ||
+    projectName === '--help' ||
+    projectName === '-h' ||
+    projectName === 'help';
+
+  if (isHelpRequested) {
+    printScaffoldHelp();
+    return;
+  }
+
   renderBanner('Chemical X: Molecular Architecture Scaffolder (npm create chemx)');
 
   const fwArg = (rawArgs.find((a) => a.startsWith('--framework=')) || '').split('=')[1]
@@ -125,9 +139,26 @@ export const runScaffold = async (projectName, rawArgs = [], onRunAudit = null)
 };
 
 export const runInit = async (targetSubDir = 'src/chemical-x', rawArgs = [], onRunAudit = null) => {
+  const isHelpRequested =
+    rawArgs.includes('--help') ||
+    rawArgs.includes('-h') ||
+    rawArgs.includes('help') ||
+    targetSubDir === '--help' ||
+    targetSubDir === '-h' ||
+    targetSubDir === 'help';
+
+  if (isHelpRequested) {
+    printInitHelp();
+    return;
+  }
+
+  const safeTargetSubDir = (targetSubDir && !targetSubDir.startsWith('-'))
+    ? targetSubDir
+    : (rawArgs.slice(1).find((arg) => !arg.startsWith('-')) || 'src/chemical-x');
+
   renderBanner('Chemical X: In-Repo Capsule Drop-in');
 
-  const targetDir = path.resolve(process.cwd(), targetSubDir);
+  const targetDir = path.resolve(process.cwd(), safeTargetSubDir);
   const licenseKey = await obtainLicenseKey(rawArgs, onRunAudit);
   let files = {};
 
@@ -141,7 +172,7 @@ export const runInit = async (targetSubDir = 'src/chemical-x', rawArgs = [], onR
     files = await fetchStarterKitFiles(licenseKey);
   }
 
-  process.stdout.write(`Unpacking blueprints and hooks into: \x1b[36m${targetSubDir}/\x1b[0m\n`);
+  process.stdout.write(`Unpacking blueprints and hooks into: \x1b[36m${safeTargetSubDir}/\x1b[0m\n`);
 
   let count = 0;
   for (const [relPath, content] of Object.entries(files)) {
@@ -160,9 +191,9 @@ export const runInit = async (targetSubDir = 'src/chemical-x', rawArgs = [], onR
   }
 
   process.stdout.write(
-    `\n\x1b[1m\x1b[32m✔ Successfully installed ${count} Chemical X assets into ${targetSubDir}!\x1b[0m\n\n`
+    `\n\x1b[1m\x1b[32m✔ Successfully installed ${count} Chemical X assets into ${safeTargetSubDir}!\x1b[0m\n\n`
   );
 };
 
 export { runGenerateCapsule, runGenerateWizard } from './generator.js';
-export { printHelp } from './help.js';
+export { printHelp, printInitHelp, printScaffoldHelp } from './help.js';

package/cli/ui-handlers.js

@@ -61,7 +61,7 @@ export const handleSwarmStatus = (db, cwd = process.cwd()) => {
       parentId: t.parent_id,
       subtaskCount,
       assignedAgentId: t.assigned_agent_id,
-      tokenStamp: `[P: ${p} | C: ${c} | Cost: ${cost.toFixed(4)}]`
+      tokenStamp: `[P: ${p} | C: ${c} | Cost: $${cost.toFixed(4)}]`
     };
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemx/create-chemx",
-  "version": "26.9.25-747",
+  "version": "26.9.25-789",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {