@chemx/starter-kit 26.9.16-41 → 26.9.17-309

package/cli/generator-templates.spec.js

@@ -0,0 +1,108 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  toPascalCase,
+  toCamelCase,
+  buildReactComponent,
+  buildVueComponent,
+  buildSvelteComponent,
+  buildController,
+  buildPropsType,
+  buildStateType,
+  buildTypesIndex,
+  buildTypes,
+  buildComponentSpec,
+  buildIndex,
+  buildScss,
+  buildHook,
+  buildHookOptionsType,
+  buildHookReturnType,
+  buildHookIndex,
+  buildHookSpec,
+  buildReactView,
+  buildVueView,
+  buildSvelteView,
+  buildViewParamsType,
+  buildViewIndex,
+  buildViewSpec
+} from './generator-templates.js';
+
+test('naming: toPascalCase and toCamelCase handle prefixes and hyphens', () => {
+  assert.equal(toPascalCase('m-user-avatar'), 'UserAvatar');
+  assert.equal(toPascalCase('use-spark-feed'), 'SparkFeed');
+  assert.equal(toPascalCase('v-dashboard-overview'), 'DashboardOverview');
+  assert.equal(toCamelCase('use-spark-feed'), 'useSparkFeed');
+  assert.equal(toCamelCase('m-spark-kpi'), 'sparkKpi');
+});
+
+test('components: buildReactComponent handles options', () => {
+  const standard = buildReactComponent('m-card', 'Card');
+  assert.ok(standard.includes('export const Card: React.FC<CardProps>'));
+  assert.ok(standard.includes('useCardController'));
+
+  const withAtoms = buildReactComponent('m-card', 'Card', { atomsPackage: '@chemx/x-atoms' });
+  assert.ok(withAtoms.includes("import { AtomButton } from '@chemx/x-atoms';"));
+
+  const lean = buildReactComponent('a-pill', 'Pill', { hasController: false });
+  assert.ok(!lean.includes('usePillController'));
+  assert.ok(lean.includes('const canProceed = true;'));
+});
+
+test('components: buildVueComponent and buildSvelteComponent handle options', () => {
+  const vue = buildVueComponent('m-card', 'Card', { atomsPackage: '@chemx/x-atoms' });
+  assert.ok(vue.includes('<a-button'));
+
+  const svelte = buildSvelteComponent('m-card', 'Card', { atomsPackage: '@chemx/x-atoms' });
+  assert.ok(svelte.includes('<AtomButton'));
+});
+
+test('controller: buildController generates valid react hook code', () => {
+  const code = buildController('m-card', 'Card');
+  assert.ok(code.includes('export const useCardController ='));
+  assert.ok(code.includes('useState<CardState>'));
+});
+
+test('types: buildPropsType, buildStateType, and buildTypes produce contract definitions', () => {
+  const types = buildTypes('m-card', 'Card');
+  assert.ok(types.includes('CardState'));
+  assert.ok(types.includes('CardProps'));
+  assert.ok(buildTypesIndex().includes("export type * from './props.d.ts';"));
+});
+
+test('specs and styles: buildComponentSpec, buildIndex, and buildScss generate expected assets', () => {
+  const specWithCtrl = buildComponentSpec('m-card', 'Card', true);
+  assert.ok(specWithCtrl.includes('useCardController'));
+  const specLean = buildComponentSpec('a-pill', 'Pill', false);
+  assert.ok(specLean.includes('Pill Atom Foundation'));
+
+  const idxVue = buildIndex('m-card', 'Card', 'vue');
+  assert.ok(idxVue.includes("export { default as Card } from './m-card.vue';"));
+
+  const scss = buildScss('m-card');
+  assert.ok(scss.includes('.m-card {'));
+});
+
+test('hooks: buildHook and related generators produce full composable suite', () => {
+  const hook = buildHook('use-feed', 'useFeed', 'Feed');
+  assert.ok(hook.includes('export const useFeed ='));
+  assert.ok(buildHookOptionsType('Feed').includes('FeedHookOptions'));
+  assert.ok(buildHookReturnType('Feed').includes('FeedHookReturn'));
+  assert.ok(buildHookIndex('use-feed', 'useFeed').includes("export { useFeed } from './use-feed';"));
+  assert.ok(buildHookSpec('use-feed', 'useFeed').includes("describe('useFeed Hook Composable'"));
+});
+
+test('views: buildReactView, buildVueView, buildSvelteView, and view helpers generate TOC templates', () => {
+  const reactView = buildReactView('v-home', 'Home');
+  assert.ok(reactView.includes('export const HomeView: React.FC<HomeViewParams>'));
+  assert.ok(reactView.includes('<main className="v-home">'));
+
+  const vueView = buildVueView('v-home', 'Home');
+  assert.ok(vueView.includes('<main class="v-home">'));
+
+  const svelteView = buildSvelteView('v-home', 'Home');
+  assert.ok(svelteView.includes('<main class="v-home">'));
+
+  assert.ok(buildViewParamsType('Home').includes('HomeViewParams'));
+  assert.ok(buildViewIndex('v-home', 'Home', 'tsx').includes("export { HomeView } from './v-home';"));
+  assert.ok(buildViewSpec('v-home', 'Home').includes("describe('HomeView Table of Contents'"));
+});

package/cli/generator.js

@@ -151,10 +151,10 @@ export const createCapsuleFiles = ({
     const specFile = `${capsuleName}.spec.ts`;
     const hasController = !isLean && selectedTier.tier !== 'atom';
     const installedFamily = detectInstalledFamily(cwd);
-    const templateOpts = { atomsPackage: installedFamily.atomsPackage };
+    const templateOpts = { atomsPackage: installedFamily.atomsPackage, hasController };
 
     fs.writeFileSync(path.join(targetDir, compFile), selectedFramework.compBuilder(capsuleName, pascalName, templateOpts), 'utf-8');
-    fs.writeFileSync(path.join(targetDir, 'index.ts'), buildIndex(capsuleName, pascalName, selectedFramework.ext), 'utf-8');
+    fs.writeFileSync(path.join(targetDir, 'index.ts'), buildIndex(capsuleName, pascalName, selectedFramework.ext, hasController), 'utf-8');
     fs.writeFileSync(path.join(targetDir, specFile), buildComponentSpec(capsuleName, pascalName, hasController), 'utf-8');
 
     fs.writeFileSync(path.join(typesDir, 'props.d.ts'), buildPropsType(capsuleName, pascalName), 'utf-8');

package/cli/generator.spec.js

@@ -8,9 +8,11 @@ import {
   toCamelCase,
   buildReactComponent,
   buildVueComponent,
-  buildSvelteComponent
+  buildSvelteComponent,
+  buildIndex
 } from './generator-templates.js';
 import { handleCheckCommand } from './search-commands.js';
+import { obtainLicenseKey } from './license.js';
 
 test('generator-templates: toPascalCase and toCamelCase convert slugs correctly', () => {
   assert.strictEqual(toPascalCase('m-user-avatar'), 'UserAvatar');
@@ -123,3 +125,61 @@ test('generator-templates: binds to @chemx/x-atoms when atomsPackage option is p
   assert.ok(svelteCode.includes('<AtomButton'));
   assert.ok(!svelteCode.includes('<button'));
 });
+
+test('generator-templates: supports hasController = false for atom/lean capsules', () => {
+  const reactCode = buildReactComponent('a-badge', 'Badge', { hasController: false });
+  assert.ok(!reactCode.includes('.controller'));
+  assert.ok(!reactCode.includes('useBadgeController'));
+  assert.ok(reactCode.includes('canProceed = true'));
+
+  const vueCode = buildVueComponent('a-badge', 'Badge', { hasController: false });
+  assert.ok(!vueCode.includes('.controller'));
+  assert.ok(!vueCode.includes('useBadgeController'));
+  assert.ok(vueCode.includes('canProceed = true'));
+
+  const svelteCode = buildSvelteComponent('a-badge', 'Badge', { hasController: false });
+  assert.ok(!svelteCode.includes('.controller'));
+  assert.ok(!svelteCode.includes('createBadgeController'));
+  assert.ok(svelteCode.includes('canProceed: true'));
+
+  const indexCode = buildIndex('a-badge', 'Badge', 'tsx', false);
+  assert.ok(!indexCode.includes('useBadgeController'));
+  assert.ok(indexCode.includes("export { Badge } from './a-badge';"));
+});
+
+test('runGenerateWizard: scaffolds atom capsule without controller or controller import', async () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-gen-atom');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  const res = await runGenerateWizard([
+    'atom',
+    'badge-pill',
+    '-y',
+    `--dir=${tmpDir}`,
+    '--framework=react'
+  ]);
+
+  assert.strictEqual(res.success, true);
+  assert.strictEqual(res.tier, 'atom');
+  assert.strictEqual(res.capsuleName, 'a-badge-pill');
+
+  const capsuleDir = path.join(tmpDir, 'a-badge-pill');
+  assert.ok(fs.existsSync(path.join(capsuleDir, 'a-badge-pill.tsx')));
+  assert.ok(!fs.existsSync(path.join(capsuleDir, 'a-badge-pill.controller.ts')));
+
+  const compContent = fs.readFileSync(path.join(capsuleDir, 'a-badge-pill.tsx'), 'utf-8');
+  assert.ok(!compContent.includes('useBadgePillController'));
+  assert.ok(!compContent.includes('.controller'));
+
+  const indexContent = fs.readFileSync(path.join(capsuleDir, 'index.ts'), 'utf-8');
+  assert.ok(!indexContent.includes('useBadgePillController'));
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('obtainLicenseKey: returns null immediately when --headless is passed without interactive prompts', async () => {
+  const key = await obtainLicenseKey(['--headless']);
+  assert.strictEqual(key, null);
+});
+
+

package/cli/help.js

@@ -111,6 +111,15 @@ export const printHelp = () => {
     `      Display this comprehensive CLI documentation and options guide.`,
     '',
     `${BOLD}AUDIT OPTIONS & FLAGS${RESET}`,
+    `  ${CYAN}--fast${RESET}, ${CYAN}--quick${RESET}`,
+    `      Fast scan: verify line budgets, token burn, and file metrics, bypassing deep AST traversal.`,
+    '',
+    `  ${CYAN}--git${RESET}, ${CYAN}--changed${RESET}`,
+    `      Scope audit strictly to modified, staged, or untracked source files in git.`,
+    '',
+    `  ${CYAN}-y${RESET}, ${CYAN}--yes${RESET}`,
+    `      Accept defaults and bypass interactive pre-flight wizard questions.`,
+    '',
     `  ${CYAN}--dir=<path>${RESET}`,
     `      Directory to analyze. Defaults to ${CYAN}src${RESET} if present, else current working directory.`,
     `      Example: ${CYAN}npx chemx audit --dir=apps/web/src${RESET}`,

package/cli/index.js

@@ -30,6 +30,7 @@ import {
   evaluateAuditFailure,
   isNonInteractiveSession
 } from './audit/rules-predicates.js';
+import { runAuditPreflight, resolveGitAuditScope } from './audit-preflight.js';
 import { runInstallWizard } from './installer.js';
 import { runBadgeCommand } from './badge.js';
 import { runBuildAudit } from './build.js';
@@ -38,6 +39,9 @@ import { runMutatorCli } from './mutators.js';
 import { runReaderCli, readTokenOptimized } from './reader.js';
 import { runPatcherCli, patchFile } from './patcher.js';
 import { runMcpServer, runMcpInstaller } from './mcp/index.js';
+import { sanitizeOutputStreams } from './terminal.js';
+
+sanitizeOutputStreams();
 
 const rawArgs = process.argv.slice(2);
 const invokedBin = path.basename(process.argv[1] || '');
@@ -84,8 +88,42 @@ export const runAudit = async (customDir = null, isCli = false) => {
   const costFlag = rawArgs.find((arg) => arg.startsWith('--cost-per-million='));
   const costPerMillion = costFlag ? parseFloat(costFlag.split('=')[1]) : null;
 
-  const targetDir = resolveTargetDir(customDir, dirFlag);
-  const report = executeAstAudit(targetDir, { outputFile, model, costPerMillion });
+  const isNonInteractive = isNonInteractiveSession(rawArgs);
+  const isInteractive = !isNonInteractive && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+  let targetDir = resolveTargetDir(customDir, dirFlag);
+  let isFast = rawArgs.includes('--fast') || rawArgs.includes('--quick');
+  let fileList = null;
+
+  const hasGitFlag = rawArgs.includes('--git') || rawArgs.includes('--changed');
+  if (hasGitFlag) {
+    const gitScope = resolveGitAuditScope(process.cwd());
+    if (gitScope.ok) {
+      fileList = gitScope.files;
+    }
+  }
+
+  const shouldRunPreflight = isCli && isInteractive && !isJson && !isMarkdown && !isShare;
+  if (shouldRunPreflight) {
+    const preflight = await runAuditPreflight(rawArgs, {
+      customDir,
+      defaultDir: targetDir,
+      cwd: process.cwd()
+    });
+    targetDir = preflight.targetDir;
+    isFast = preflight.fast;
+    fileList = preflight.fileList;
+  }
+
+  const auditOptions = {
+    outputFile,
+    model,
+    costPerMillion,
+    fast: isFast,
+    fileList
+  };
+
+  const report = executeAstAudit(targetDir, auditOptions);
   saveAuditSnapshot(report);
   const syncRes = syncSearchIndex(targetDir, process.cwd());
   if (syncRes?.db) {
@@ -120,12 +158,9 @@ export const runAudit = async (customDir = null, isCli = false) => {
       process.exit(0);
     }
 
-    const isNonInteractive = isNonInteractiveSession(rawArgs);
-    const isInteractive = !isNonInteractive && Boolean(process.stdin.isTTY && process.stdout.isTTY);
-
     if (isInteractive && !isUnroll) {
       const handleReAudit = () => {
-        const refreshed = executeAstAudit(targetDir, { outputFile, model, costPerMillion });
+        const refreshed = executeAstAudit(targetDir, auditOptions);
         saveAuditSnapshot(refreshed);
         return refreshed;
       };
@@ -198,7 +233,9 @@ export {
   runBuildAudit,
   runSearch,
   syncSearchIndex,
-  startMcpServer,
+  runMcpServer,
+  runMcpServer as startMcpServer,
+  runMcpInstaller,
   runReaderCli,
   readTokenOptimized,
   runPatcherCli,

package/cli/installer-templates.js

@@ -2,15 +2,66 @@ export const buildPreCommitHookScript = (minGrade = 'B', minScore = 80) => `#!/b
 # Chemical X Protocol: Pre-Commit Line Budget & Architecture Gatekeeper
 # Free architectural guardrail preventing context bloat and monolith sprawl.
 
-MIN_GRADE="\${CHEMX_MIN_GRADE:-${minGrade}}"
-MIN_SCORE="\${CHEMX_MIN_SCORE:-${minScore}}"
-MAX_LINES="\${CHEMX_MAX_LINES:-500}"
-MAX_MOLECULE_LINES="\${CHEMX_MAX_MOLECULE_LINES:-100}"
-
 REPO_ROOT="\$(git rev-parse --show-toplevel 2>/dev/null)"
 [ -z "\$REPO_ROOT" ] && exit 0
 cd "\$REPO_ROOT" || exit 1
 
+# Delegate to version-controlled script if present
+if [ -f "\$REPO_ROOT/scripts/pre-commit.sh" ]; then
+  exec "\$REPO_ROOT/scripts/pre-commit.sh" "\$@"
+fi
+
+# Detect TTY and color support
+if [ -t 1 ] && [ -z "\$NO_COLOR" ] && [ "\$TERM" != "dumb" ]; then
+  C_RESET="\$(printf '\\033[0m')"
+  C_BOLD="\$(printf '\\033[1m')"
+  C_RED="\$(printf '\\033[31m')"
+  C_GREEN="\$(printf '\\033[32m')"
+  C_YELLOW="\$(printf '\\033[33m')"
+  C_CYAN="\$(printf '\\033[36m')"
+  C_BLUE="\$(printf '\\033[38;2;98;201;255m')"
+else
+  C_RESET=""
+  C_BOLD=""
+  C_RED=""
+  C_GREEN=""
+  C_YELLOW=""
+  C_CYAN=""
+  C_BLUE=""
+  export NO_COLOR=1
+fi
+
+# Load thresholds from .chemx/config.json if available
+CONF_MAX_LINES=""
+CONF_MAX_MOL=""
+CONF_MIN_GRADE=""
+CONF_MIN_SCORE=""
+CONFIG_FILE="\$REPO_ROOT/.chemx/config.json"
+
+if [ -f "\$CONFIG_FILE" ]; then
+  if command -v node >/dev/null 2>&1; then
+    eval \$(node -e "
+      try {
+        const c = JSON.parse(require('fs').readFileSync('\$CONFIG_FILE', 'utf8'));
+        if (c.maxLineCount || c.maxLines) console.log('CONF_MAX_LINES=' + (c.maxLineCount || c.maxLines));
+        if (c.maxMoleculeLineCount || c.maxMoleculeLines) console.log('CONF_MAX_MOL=' + (c.maxMoleculeLineCount || c.maxMoleculeLines));
+        if (c.minGrade) console.log('CONF_MIN_GRADE=' + c.minGrade);
+        if (c.minScore) console.log('CONF_MIN_SCORE=' + c.minScore);
+      } catch (e) {}
+    ")
+  else
+    CONF_MAX_LINES=\$(grep -o '"maxLineCount"[[:space:]]*:[[:space:]]*[0-9]*' "\$CONFIG_FILE" 2>/dev/null | grep -o '[0-9]*\$')
+    CONF_MAX_MOL=\$(grep -o '"maxMoleculeLineCount"[[:space:]]*:[[:space:]]*[0-9]*' "\$CONFIG_FILE" 2>/dev/null | grep -o '[0-9]*\$')
+    CONF_MIN_GRADE=\$(grep -o '"minGrade"[[:space:]]*:[[:space:]]*"[^"]*"' "\$CONFIG_FILE" 2>/dev/null | sed 's/.*"minGrade"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\\1/')
+    CONF_MIN_SCORE=\$(grep -o '"minScore"[[:space:]]*:[[:space:]]*[0-9]*' "\$CONFIG_FILE" 2>/dev/null | grep -o '[0-9]*\$')
+  fi
+fi
+
+MIN_GRADE="\${CHEMX_MIN_GRADE:-\${CONF_MIN_GRADE:-${minGrade}}}"
+MIN_SCORE="\${CHEMX_MIN_SCORE:-\${CONF_MIN_SCORE:-${minScore}}}"
+MAX_LINES="\${CHEMX_MAX_LINES:-\${CONF_MAX_LINES:-500}}"
+MAX_MOLECULE_LINES="\${CHEMX_MAX_MOLECULE_LINES:-\${CONF_MAX_MOL:-100}}"
+
 STAGED_FILES=\$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(jsx?|tsx?|vue|svelte)\$' | grep -vE '(\\.(d\\.ts|min\\.|test\\.|spec\\.))')
 [ -z "\$STAGED_FILES" ] && exit 0
 
@@ -21,14 +72,18 @@ for F in \$STAGED_FILES; do
   L=\$(wc -l < "\$F" | tr -d ' ')
   case "\$F" in
     *molecules*|*/m-*|*m-*)
-      [ "\$L" -gt "\$MAX_MOLECULE_LINES" ] && FAILED=1 && ERRORS="\${ERRORS}\\n  \\033[31m✕\\033[0m \$F (\$L LOC > \$MAX_MOLECULE_LINES molecule limit)" ;;
+      [ "\$L" -gt "\$MAX_MOLECULE_LINES" ] && FAILED=1 && ERRORS="\${ERRORS}\\n  \${C_RED}✕\${C_RESET} \$F (\$L LOC > \$MAX_MOLECULE_LINES molecule limit)" ;;
     *)
-      [ "\$L" -gt "\$MAX_LINES" ] && FAILED=1 && ERRORS="\${ERRORS}\\n  \\033[31m✕\\033[0m \$F (\$L LOC > \$MAX_LINES file budget)" ;;
+      [ "\$L" -gt "\$MAX_LINES" ] && FAILED=1 && ERRORS="\${ERRORS}\\n  \${C_RED}✕\${C_RESET} \$F (\$L LOC > \$MAX_LINES file budget)" ;;
   esac
 done
 
 if [ "\$FAILED" -eq 1 ]; then
-  printf "\\n\\033[1m\\033[31m[Chemical X] Commit Blocked: Staged files exceed architectural line budgets\\033[0m\\n\$ERRORS\\n\\n"
+  printf "\\n%s%s[Chemical X] Commit Blocked: Staged files exceed architectural line budgets%s\\n" "\$C_BOLD" "\$C_RED" "\$C_RESET"
+  printf "%b\\n\\n" "\$ERRORS"
+  printf "%sMonolithic files degrade AI context windows and cause hallucination loops.%s\\n" "\$C_YELLOW" "\$C_RESET"
+  printf "Decompose large files into single-purpose crystalline capsules or configure thresholds in .chemx/config.json before committing.\\n\\n"
+  exit 1
 fi
 
 AUDIT_BIN=""
@@ -43,16 +98,15 @@ elif command -v npx >/dev/null 2>&1; then
 fi
 
 if [ -n "\$AUDIT_BIN" ]; then
-  printf "\\033[38;2;98;201;255m[Chemical X] Verifying architectural health (Min Grade: %s, Min Score: %s)...\\033[0m\\n" "\$MIN_GRADE" "\$MIN_SCORE"
+  printf "%s[Chemical X] Verifying architectural health (Min Grade: %s, Min Score: %s)...%s\\n" "\$C_BLUE" "\$MIN_GRADE" "\$MIN_SCORE" "\$C_RESET"
   if ! \$AUDIT_BIN audit --min-grade="\$MIN_GRADE" --min-score="\$MIN_SCORE" --non-interactive < /dev/null; then
-    printf "\\n\\033[1m\\033[31m[Chemical X] Commit Blocked: Architectural health verification failed\\033[0m\\n"
-    printf "\\033[36m💡 Tip: Want crystalline drop-in templates? Run 'npm create chemx' or sponsor at https://github.com/sponsors/Chemical-X-Protocol\\033[0m\\n\\n"
+    printf "\\n%s%s[Chemical X] Commit Blocked: Architectural health verification failed%s\\n" "\$C_BOLD" "\$C_RED" "\$C_RESET"
+    printf "%s💡 Tip: Want crystalline drop-in templates? Run 'npm create chemx' or sponsor at https://github.com/sponsors/Chemical-X-Protocol%s\\n\\n" "\$C_CYAN" "\$C_RESET"
     exit 1
   fi
 fi
 
-[ "\$FAILED" -eq 1 ] && exit 1
-printf "\\033[32m✔ [Chemical X] Pre-commit architectural guardrails passed.\\033[0m\\n"
+printf "%s✔ [Chemical X] Pre-commit architectural guardrails passed.%s\\n" "\$C_GREEN" "\$C_RESET"
 exit 0
 `;
 

package/cli/license.js

@@ -109,6 +109,22 @@ export const obtainLicenseKey = async (rawArgs = [], onRunAudit = null) => {
     return effectiveKey;
   }
 
+  const isHeadless =
+    rawArgs.includes('--headless') ||
+    rawArgs.includes('--yes') ||
+    rawArgs.includes('-y') ||
+    rawArgs.includes('--ci') ||
+    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'));
+
+  if (isHeadless) {
+    return null;
+  }
+
   const useGum = hasGum();
 
   if (useGum) {
@@ -211,7 +227,12 @@ export const checkOrPromptEvaluation = async (actionLabel = 'generate capsule',
     return { licensed: true, key: cachedKey };
   }
 
-  const isNonInteractive = options.isYes || Boolean(process.env.CI) || !process.stdin.isTTY;
+  const isNonInteractive =
+    options.isYes ||
+    Boolean(process.env.CI) ||
+    process.stdin?.isTTY === false ||
+    process.stdout?.isTTY === false ||
+    Boolean(process.argv?.some((arg) => arg === '--headless' || arg === '--yes' || arg === '-y' || arg === '--ci' || arg === '--non-interactive'));
   if (isNonInteractive) {
     return { licensed: false, proceed: true };
   }

package/cli/mcp/installer.js

@@ -4,18 +4,24 @@ import os from 'node:os';
 
 const SERVER_KEY = 'chemical-x';
 
+const toResultSync = (operation) => {
+  try {
+    const value = operation();
+    return [value, null];
+  } catch (err) {
+    const normalizedError = err instanceof Error ? err : new Error(String(err));
+    return [null, normalizedError];
+  }
+};
+
 export const mergeMcpServerConfig = (existingJsonString = '', serverDef = {}) => {
   let parsed = { mcpServers: {} };
 
   const hasExistingString = Boolean(existingJsonString && existingJsonString.trim());
   if (hasExistingString) {
-    try {
-      const json = JSON.parse(existingJsonString);
-      if (json && typeof json === 'object') {
-        parsed = json;
-      }
-    } catch {
-      parsed = { mcpServers: {} };
+    const [json, parseError] = toResultSync(() => JSON.parse(existingJsonString));
+    if (!parseError && json && typeof json === 'object') {
+      parsed = json;
     }
   }
 
@@ -104,22 +110,26 @@ export const installProjectMcpConfig = (targetDir = '.', options = {}) => {
   // 3. Inject helper script to consumer package.json if available
   const pkgPath = path.join(resolvedTarget, 'package.json');
   if (fs.existsSync(pkgPath)) {
-    try {
-      const pkgContent = fs.readFileSync(pkgPath, 'utf-8');
-      const pkg = JSON.parse(pkgContent);
-      if (!pkg.scripts) pkg.scripts = {};
-
-      const hasMcpScript = Boolean(pkg.scripts['chemx:mcp'] || pkg.scripts['mcp']);
-      if (!hasMcpScript) {
-        pkg.scripts['chemx:mcp'] = 'chemx mcp';
-        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
-        results.packageJson = true;
-        if (!isSilent) {
-          process.stdout.write('  \x1b[32m✔\x1b[0m Added "chemx:mcp" script to package.json\n');
+    const [pkgContent, readError] = toResultSync(() => fs.readFileSync(pkgPath, 'utf-8'));
+    if (!readError && pkgContent) {
+      const [pkg, parseError] = toResultSync(() => JSON.parse(pkgContent));
+      if (!parseError && pkg && typeof pkg === 'object') {
+        if (!pkg.scripts) pkg.scripts = {};
+
+        const hasMcpScript = Boolean(pkg.scripts['chemx:mcp'] || pkg.scripts['mcp']);
+        if (!hasMcpScript) {
+          pkg.scripts['chemx:mcp'] = 'chemx mcp';
+          const [, writeError] = toResultSync(() => {
+            fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+          });
+          if (!writeError) {
+            results.packageJson = true;
+            if (!isSilent) {
+              process.stdout.write('  \x1b[32m✔\x1b[0m Added "chemx:mcp" script to package.json\n');
+            }
+          }
         }
       }
-    } catch {
-      // Ignore package.json parsing issues gracefully
     }
   }
 

package/cli/mcp/resources.js

@@ -40,6 +40,103 @@ const readLocalFileSafely = (filePath) => {
   return '';
 };
 
+const FALLBACK_VIEW_TEMPLATE = `import React from 'react';
+
+export interface ViewTemplateProps {
+  readonly title: string;
+  readonly children: React.ReactNode;
+}
+
+export const ViewTemplate: React.FC<ViewTemplateProps> = ({ title, children }) => {
+  return (
+    <main className="view-template">
+      <header className="view-template__header">
+        <h1 className="view-template__title">{title}</h1>
+      </header>
+      <div className="view-template__content">
+        {children}
+      </div>
+    </main>
+  );
+};
+
+export default ViewTemplate;
+`;
+
+const FALLBACK_MOLECULE_TEMPLATE = `import React from 'react';
+import type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';
+
+export const resolveBadgeDescriptor = (
+  status: 'active' | 'archived',
+  isHighValue: boolean
+): SampleCardBadgeDescriptor => {
+  if (status !== 'active') {
+    return {
+      text: status,
+      className: 'm-sample-card__badge m-sample-card__badge--archived'
+    };
+  }
+
+  if (isHighValue) {
+    return {
+      text: status,
+      className: 'm-sample-card__badge m-sample-card__badge--high-value'
+    };
+  }
+
+  return {
+    text: status,
+    className: 'm-sample-card__badge m-sample-card__badge--standard'
+  };
+};
+
+export const MSampleCard: React.FC<MSampleCardProps> = ({
+  title,
+  subtitle,
+  value,
+  status = 'active',
+  onAction
+}) => {
+  const isHighValue = value > 1000;
+  const badge = resolveBadgeDescriptor(status, isHighValue);
+
+  const handleActionClick = () => {
+    if (!onAction) return;
+    onAction();
+  };
+
+  return (
+    <div className="m-sample-card">
+      <div className="m-sample-card__header">
+        <div className="m-sample-card__title-group">
+          <h3 className="m-sample-card__title">{title}</h3>
+          {subtitle && <p className="m-sample-card__subtitle">{subtitle}</p>}
+        </div>
+        <span className={badge.className}>
+          {badge.text}
+        </span>
+      </div>
+      <div className="m-sample-card__body">
+        <div className="m-sample-card__value">
+          \${value.toLocaleString()}
+        </div>
+        {onAction && (
+          <button
+            type="button"
+            className="m-sample-card__action"
+            onClick={handleActionClick}
+          >
+            Action
+          </button>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default MSampleCard;
+`;
+
 export const readMcpResource = async (uri, cwd = process.cwd()) => {
   switch (uri) {
     case 'chemx://directives': {
@@ -54,23 +151,33 @@ export const readMcpResource = async (uri, cwd = process.cwd()) => {
     }
 
     case 'chemx://blueprints/view-template': {
-      const blueprintPath = path.resolve(starterKitRoot, 'blueprints', 'view-template.tsx');
-      const content = readLocalFileSafely(blueprintPath);
+      const candidatePaths = [
+        path.resolve(cwd, '.chemx', 'blueprints', 'view-template.tsx'),
+        path.resolve(cwd, 'blueprints', 'view-template.tsx'),
+        path.resolve(starterKitRoot, 'blueprints', 'view-template.tsx')
+      ];
+      const foundPath = candidatePaths.find((p) => fs.existsSync(p));
+      const content = foundPath ? fs.readFileSync(foundPath, 'utf-8') : FALLBACK_VIEW_TEMPLATE;
       return {
         uri,
         mimeType: 'text/plain',
-        text: content || '// view-template.tsx blueprint not found'
+        text: content
       };
     }
 
     case 'chemx://blueprints/molecule': {
-      const sampleVue = path.resolve(starterKitRoot, 'blueprints', 'molecule-capsule', 'm-tab-button', 'm-tab-button.vue');
-      const sampleTsx = path.resolve(starterKitRoot, 'blueprints', 'molecule-capsule', 'm-sample-card.tsx');
-      const content = readLocalFileSafely(sampleVue) || readLocalFileSafely(sampleTsx);
+      const candidatePaths = [
+        path.resolve(cwd, '.chemx', 'blueprints', 'molecule-capsule', 'm-tab-button', 'm-tab-button.vue'),
+        path.resolve(cwd, '.chemx', 'blueprints', 'molecule-capsule', 'm-sample-card.tsx'),
+        path.resolve(cwd, 'blueprints', 'molecule-capsule', 'm-tab-button', 'm-tab-button.vue'),
+        path.resolve(cwd, 'blueprints', 'molecule-capsule', 'm-sample-card.tsx')
+      ];
+      const foundPath = candidatePaths.find((p) => fs.existsSync(p));
+      const content = foundPath ? fs.readFileSync(foundPath, 'utf-8') : FALLBACK_MOLECULE_TEMPLATE;
       return {
         uri,
         mimeType: 'text/plain',
-        text: content || '// molecule blueprint not found'
+        text: content
       };
     }