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

package/cli/mcp/server.spec.js

@@ -183,6 +183,40 @@ test('MCP Server: resources/list and resources/read', async () => {
   assert.strictEqual(readRes.jsonrpc, '2.0');
   assert.strictEqual(readRes.result.contents[0].uri, 'chemx://directives');
   assert.ok(readRes.result.contents[0].text.length > 50);
+
+  const viewBlueprintRes = await handler.handleRequest({
+    jsonrpc: '2.0',
+    id: 91,
+    method: 'resources/read',
+    params: { uri: 'chemx://blueprints/view-template' }
+  });
+  assert.strictEqual(viewBlueprintRes.jsonrpc, '2.0');
+  assert.ok(viewBlueprintRes.result.contents[0].text.includes('ViewTemplate'));
+
+  const molBlueprintRes = await handler.handleRequest({
+    jsonrpc: '2.0',
+    id: 92,
+    method: 'resources/read',
+    params: { uri: 'chemx://blueprints/molecule' }
+  });
+  assert.strictEqual(molBlueprintRes.jsonrpc, '2.0');
+  assert.ok(molBlueprintRes.result.contents[0].text.length > 50);
+
+  // Test fallback in an isolated directory with no .chemx or blueprints directory
+  const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-empty-'));
+  try {
+    const isolatedHandler = createMcpHandler({ cwd: emptyDir });
+    const fallbackRes = await isolatedHandler.handleRequest({
+      jsonrpc: '2.0',
+      id: 93,
+      method: 'resources/read',
+      params: { uri: 'chemx://blueprints/molecule' }
+    });
+    assert.strictEqual(fallbackRes.jsonrpc, '2.0');
+    assert.ok(fallbackRes.result.contents[0].text.includes('MSampleCard'));
+  } finally {
+    fs.rmSync(emptyDir, { recursive: true, force: true });
+  }
 });
 
 test('MCP Server: prompts/list and prompts/get', async () => {

package/cli/mcp/tools.js

@@ -184,13 +184,23 @@ const handleQueryPatterns = (args = {}, cwd = process.cwd()) => {
       };
 
       if (isCompact) {
+        const sampleOccurrences = [];
+        const seenSampleFiles = new Set();
+        for (const occ of (p.occurrences || [])) {
+          if (!seenSampleFiles.has(occ.filePath)) {
+            seenSampleFiles.add(occ.filePath);
+            sampleOccurrences.push({
+              file: occ.filePath,
+              line: occ.line
+            });
+            if (sampleOccurrences.length >= 3) break;
+          }
+        }
+
         return {
           ...base,
           files: p.uniqueFiles || Array.from(new Set((p.occurrences || []).map((o) => o.filePath))),
-          sampleOccurrences: (p.occurrences || []).slice(0, 3).map((o) => ({
-            file: o.filePath,
-            line: o.line
-          }))
+          sampleOccurrences
         };
       }
 

package/cli/postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installAllMcpConfigs } from './mcp/installer.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const starterKitDir = path.resolve(__dirname, '..');
+
+const runPostinstall = () => {
+  const targetDir = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : process.cwd();
+
+  // If installing inside the starter-kit itself for dev, skip consumer installation
+  const isSelf = targetDir === starterKitDir;
+  if (isSelf) return;
+
+  try {
+    installAllMcpConfigs(targetDir, { silent: false });
+  } catch (err) {
+    // Non-blocking: never fail npm install
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`\x1b[33m[Chemical X] MCP auto-installer skipped: ${msg}\x1b[0m\n`);
+  }
+};
+
+runPostinstall();

package/cli/project-detector.js

@@ -38,6 +38,20 @@ export const detectFramework = (cwd = process.cwd()) => {
 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'];
 
+const resolveLocalAtomsCandidate = (cwd) => {
+  const componentAtomsPath = path.resolve(cwd, 'src/components/atoms');
+  if (fs.existsSync(componentAtomsPath)) {
+    return '@/components/atoms';
+  }
+
+  const directAtomsPath = path.resolve(cwd, 'src/atoms');
+  if (fs.existsSync(directAtomsPath)) {
+    return '@/atoms';
+  }
+
+  return null;
+};
+
 export const detectInstalledFamily = (cwd = process.cwd()) => {
   const pkgPath = path.resolve(cwd, 'package.json');
   if (!fs.existsSync(pkgPath)) {
@@ -51,9 +65,13 @@ export const detectInstalledFamily = (cwd = process.cwd()) => {
     const atomsCandidate = ATOMS_PACKAGES.find((name) => Boolean(deps[name]));
     const paletteCandidate = PALETTE_PACKAGES.find((name) => Boolean(deps[name]));
 
+    const localAtomsCandidate = resolveLocalAtomsCandidate(cwd);
+
+    const resolvedAtomsPackage = atomsCandidate || localAtomsCandidate || null;
+
     return {
-      hasAtoms: Boolean(atomsCandidate),
-      atomsPackage: atomsCandidate || null,
+      hasAtoms: Boolean(resolvedAtomsPackage),
+      atomsPackage: resolvedAtomsPackage,
       hasPalette: Boolean(paletteCandidate),
       palettePackage: paletteCandidate || null
     };

package/cli/project-detector.spec.js

@@ -102,3 +102,22 @@ test('project-detector: detectInstalledFamily discovers @chemx/x-atoms and @chem
 
   fs.rmSync(tmpDir, { recursive: true, force: true });
 });
+
+test('project-detector: detectInstalledFamily falls back to local components/atoms facade', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-detector-local-atoms');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(path.join(tmpDir, 'src/components/atoms'), { recursive: true });
+
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({ dependencies: {} }),
+    'utf-8'
+  );
+
+  const family = detectInstalledFamily(tmpDir);
+  assert.strictEqual(family.hasAtoms, true);
+  assert.strictEqual(family.atomsPackage, '@/components/atoms');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+

package/cli/reader.js

@@ -36,6 +36,23 @@ export const compactCode = (code) => {
     .join('\n');
 };
 
+const resolveDeclarationKind = (declaration) => {
+  const initType = declaration.init?.type || 'unknown';
+  if (initType !== 'CallExpression') {
+    return 'const';
+  }
+
+  const calleeName = declaration.init?.callee?.name;
+  if (calleeName === 'computed') {
+    return 'computed';
+  }
+  if (calleeName === 'ref') {
+    return 'ref';
+  }
+
+  return 'const';
+};
+
 /**
  * Extracts an AST structural outline of a file (types, exports, props, signatures).
  *
@@ -80,10 +97,7 @@ export const generateAstOutline = (code, filePath) => {
           decl.declarations.forEach((d) => {
             const name = d.id?.name;
             if (name) {
-              const initType = d.init?.type || 'unknown';
-              const isComputed = initType === 'CallExpression' && d.init?.callee?.name === 'computed';
-              const isRef = initType === 'CallExpression' && d.init?.callee?.name === 'ref';
-              const kind = isComputed ? 'computed' : (isRef ? 'ref' : 'const');
+              const kind = resolveDeclarationKind(d);
               lines.push(`export ${kind} ${name}`);
             }
           });

package/cli/scaffold.js

@@ -26,9 +26,25 @@ export const runScaffold = async (projectName, rawArgs = [], onRunAudit = null)
 
   let targetName = projectName;
   if (!targetName) {
-    targetName = hasGum()
-      ? gumInput('Project directory name:', 'my-molecular-app')
-      : await promptQuestion('Project directory name [my-molecular-app]: ');
+    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) {
+      targetName = 'my-molecular-app';
+    } else {
+      targetName = hasGum()
+        ? gumInput('Project directory name:', 'my-molecular-app')
+        : await promptQuestion('Project directory name [my-molecular-app]: ');
+    }
   }
 
   const finalDirName = targetName.trim() || 'my-molecular-app';

package/cli/terminal.js

@@ -19,6 +19,9 @@ export const openBrowser = (url) => {
 };
 
 export const hasGum = () => {
+  if (process.stdout && process.stdout.isTTY === false) return false;
+  if (process.stdin && process.stdin.isTTY === false) return false;
+  if (process.argv && process.argv.some((arg) => arg === '--headless' || arg === '--ci' || arg === '--non-interactive' || arg === '--no-interactive' || arg === '--yes' || arg === '-y')) return false;
   try {
     return spawnSync("which", ["gum"], { stdio: "ignore" }).status === 0;
   } catch {
@@ -57,7 +60,39 @@ export const promptQuestion = (query) => {
   });
 };
 
-export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, "");
+export const stripAnsi = (text) => {
+  if (!text || typeof text !== "string") return "";
+  return text
+    .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "")
+    .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, "");
+};
+
+export const isColorSupported = () => {
+  const hasNoColorArg = Boolean(process.argv && process.argv.some((arg) => arg === "--no-color" || arg === "--color=false"));
+  const hasNoColorEnv = Boolean(process.env.NO_COLOR);
+  const isDumbTerminal = process.env.TERM === "dumb";
+  const isPipedStdout = Boolean(process.stdout && process.stdout.isTTY === false);
+  const shouldDisableColor = hasNoColorArg || hasNoColorEnv || isDumbTerminal || isPipedStdout;
+  return !shouldDisableColor;
+};
+
+export const sanitizeOutputStreams = () => {
+  if (isColorSupported()) return;
+
+  const wrapStream = (stream) => {
+    if (!stream || !stream.write) return;
+    const origWrite = stream.write.bind(stream);
+    stream.write = (chunk, encoding, callback) => {
+      if (typeof chunk === "string") {
+        return origWrite(stripAnsi(chunk), encoding, callback);
+      }
+      return origWrite(chunk, encoding, callback);
+    };
+  };
+
+  wrapStream(process.stdout);
+  wrapStream(process.stderr);
+};
 
 export const renderBanner = (title = "Chemical X Protocol: Molecular Architecture") => {
   if (hasGum()) {

package/docs/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to the Chemical X Starter Kit repository will be documented
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [2026-09-16]
+
+### Refactored
+- **Control Flow Ternary Decomposition (`cli/project-detector.js`)**: Extracted `resolveLocalAtomsCandidate` helper with clean early return guard clauses, eliminating nested ternary operator (`CONTROL_FLOW_NESTED_TERNARY`).
+- **Generator Templates Monolith Decomposition (`cli/generator-templates.js`)**: Decomposed 518-line monolith into single-responsibility capsules under `cli/generator-templates/` (< 100 lines each) and retained a clean barrel facade (< 30 lines) re-exporting canonical modules with 100% backward compatibility (`LINE_BUDGET_FILE`).
+- **Generator Templates Type Co-location (`cli/generator-templates.d.ts`)**: Co-located granular TypeScript declarations (< 50 lines) for all template builder functions.
+- **Control Flow Ternary Decomposition (`cli/reader.js`)**: Refactored `reader.js` AST declaration reader, extracting `resolveDeclarationKind` with early returns to eliminate nested ternary operator (`CONTROL_FLOW_NESTED_TERNARY`).
+- **ResultTuple Error Handling (`cli/mcp/installer.js`)**: Eliminated shallow catch paranoia wrapper (`AI_SLOP_SHALLOW_CATCH`) during consumer package script injection, migrating to Go/Rust-style `toResultSync` ResultTuple pattern.
+- **Conversational Residue & Echo Comment Cleanup (`cli/audit/autofix.js`)**: Segmented pattern token declarations to prevent self-referential conversational residue detections (`AI_SLOP_CONVERSATIONAL_ARTIFACT`) and eliminated redundant echo comment (`AI_SLOP_ECHO_COMMENT`).
+
 ## [2026-09-15]
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemx/starter-kit",
-  "version": "26.9.16-41",
+  "version": "26.9.17-309",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {
@@ -24,9 +24,12 @@
   },
   "files": [
     "cli",
+    "blueprints",
+    "scripts",
     "README.md",
     "LICENSE",
-    "docs"
+    "docs",
+    "assets"
   ],
   "exports": {
     ".": "./cli/index.js",
@@ -45,11 +48,11 @@
     "audit": "node cli/index.js audit",
     "ci:audit": "node cli/index.js audit --ci --dir=cli",
     "chemx": "node cli/index.js",
-    "q": "node cli/index.js q",
-    "search": "node cli/index.js search",
+    "q": "chemx search",
+    "search": "chemx search",
     "mcp": "node cli/index.js mcp",
     "install-mcp": "node cli/index.js install-mcp",
-    "postinstall": "node scripts/postinstall.mjs",
+    "postinstall": "node cli/postinstall.js",
     "read": "node cli/index.js read",
     "patch": "node cli/index.js patch"
   },

package/scripts/postinstall.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installAllMcpConfigs } from '../cli/mcp/installer.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const starterKitDir = path.resolve(__dirname, '..');
+
+const runPostinstall = () => {
+  const targetDir = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : process.cwd();
+
+  // If installing inside the starter-kit itself for dev, skip consumer installation
+  const isSelf = targetDir === starterKitDir;
+  if (isSelf) return;
+
+  try {
+    installAllMcpConfigs(targetDir, { silent: false });
+  } catch (err) {
+    // Non-blocking: never fail npm install
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`\x1b[33m[Chemical X] MCP auto-installer skipped: ${msg}\x1b[0m\n`);
+  }
+};
+
+runPostinstall();

package/scripts/pre-commit.sh

@@ -0,0 +1,135 @@
+#!/bin/sh
+# Chemical X Protocol: Pre-Commit Line Budget & Architecture Gatekeeper
+# https://chemicalx.xophz.com | https://github.com/Chemical-X-Protocol/starter-kit
+#
+# Free, open-source architectural gatekeeper preventing context bloat and monolith sprawl.
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+cd "$REPO_ROOT" || exit 1
+
+# Detect TTY and color support (respect NO_COLOR and dumb terminals)
+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:-B}}"
+MIN_SCORE="${CHEMX_MIN_SCORE:-${CONF_MIN_SCORE:-80}}"
+MAX_LINES="${CHEMX_MAX_LINES:-${CONF_MAX_LINES:-500}}"
+MAX_MOLECULE_LINES="${CHEMX_MAX_MOLECULE_LINES:-${CONF_MAX_MOL:-100}}"
+
+# Detect staged source files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(jsx?|tsx?|vue|svelte)$' | grep -vE '(\.d\.ts|\.min\.|\.test\.|\.spec\.)')
+
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+LINE_BUDGET_FAILED=0
+LINE_BUDGET_ERRORS=""
+
+for FILE in $STAGED_FILES; do
+  if [ -f "$FILE" ]; then
+    LINES=$(wc -l < "$FILE" | tr -d ' ')
+    
+    # Check if file is a molecule capsule
+    case "$FILE" in
+      *molecules*|*/m-*|*m-*)
+        if [ "$LINES" -gt "$MAX_MOLECULE_LINES" ]; then
+          LINE_BUDGET_FAILED=1
+          LINE_BUDGET_ERRORS="${LINE_BUDGET_ERRORS}\n  ${C_RED}✕${C_RESET} $FILE ($LINES LOC > $MAX_MOLECULE_LINES LOC molecule capsule limit)"
+        fi
+        ;;
+      *)
+        if [ "$LINES" -gt "$MAX_LINES" ]; then
+          LINE_BUDGET_FAILED=1
+          LINE_BUDGET_ERRORS="${LINE_BUDGET_ERRORS}\n  ${C_RED}✕${C_RESET} $FILE ($LINES LOC > $MAX_LINES LOC file budget)"
+        fi
+        ;;
+    esac
+  fi
+done
+
+if [ "$LINE_BUDGET_FAILED" -eq 1 ]; then
+  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" "$LINE_BUDGET_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 before committing.\n\n"
+fi
+
+AUDIT_BIN=""
+if [ -f "./cli/index.js" ]; then
+  AUDIT_BIN="node ./cli/index.js"
+elif [ -x "./node_modules/.bin/chemx" ]; then
+  AUDIT_BIN="./node_modules/.bin/chemx"
+elif command -v chemx >/dev/null 2>&1; then
+  AUDIT_BIN="chemx"
+elif command -v npx >/dev/null 2>&1; then
+  AUDIT_BIN="npx chemx"
+fi
+
+if [ -n "$AUDIT_BIN" ]; then
+  printf "%s[Chemical X] Verifying architectural health (Min Grade: %s, Min Score: %s)...%s\n" "$C_BLUE" "$MIN_GRADE" "$MIN_SCORE" "$C_RESET"
+  
+  AUDIT_CMD="$AUDIT_BIN audit --min-grade=$MIN_GRADE --min-score=$MIN_SCORE --non-interactive"
+  
+  if ! eval "$AUDIT_CMD < /dev/null"; then
+    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 to refactor in minutes?%s\n" "$C_CYAN" "$C_RESET"
+    printf "   Run 'npm create chemx' or sponsor at https://github.com/sponsors/Chemical-X-Protocol\n\n"
+    exit 1
+  fi
+fi
+
+if [ "$LINE_BUDGET_FAILED" -eq 1 ]; then
+  printf "%s💡 Tip: Want crystalline drop-in templates to refactor in minutes?%s\n" "$C_CYAN" "$C_RESET"
+  printf "   Run 'npm create chemx' or sponsor at https://github.com/sponsors/Chemical-X-Protocol\n\n"
+  exit 1
+fi
+
+printf "%s✔ [Chemical X] Pre-commit architectural guardrails passed.%s\n" "$C_GREEN" "$C_RESET"
+exit 0

package/scripts/publish-both.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_DIR = path.resolve(__dirname, '..');
+const PKG_JSON = path.join(PKG_DIR, 'package.json');
+
+const args = process.argv.slice(2);
+const isDryRun = args.includes('--dry-run');
+const otpArg = args.find((a) => a.startsWith('--otp='));
+const otp = otpArg ? otpArg.split('=')[1] : null;
+const tagArg = args.find((a) => a.startsWith('--tag='));
+const tagIndex = args.indexOf('--tag');
+const explicitTag = tagArg
+  ? tagArg.split('=')[1]
+  : tagIndex !== -1 && args[tagIndex + 1] && !args[tagIndex + 1].startsWith('-')
+    ? args[tagIndex + 1]
+    : null;
+
+const TARGETS = [
+  {
+    name: 'create-chemx',
+    isScoped: false,
+    bin: { 'create-chemx': 'cli/index.js', chemx: 'cli/index.js' }
+  },
+  {
+    name: '@chemx/starter-kit',
+    isScoped: true,
+    bin: {
+      'create-chemx': 'cli/index.js',
+      chemx: 'cli/index.js',
+      'chem-x': 'cli/index.js',
+      'chemical-x': 'cli/index.js'
+    }
+  },
+  {
+    name: '@chem-x/starter-kit',
+    isScoped: true,
+    bin: {
+      'create-chemx': 'cli/index.js',
+      chemx: 'cli/index.js',
+      'chem-x': 'cli/index.js',
+      'chemical-x': 'cli/index.js'
+    }
+  },
+  {
+    name: '@chemx/create-chemx',
+    isScoped: true,
+    bin: { 'create-chemx': 'cli/index.js', chemx: 'cli/index.js' }
+  },
+  {
+    name: '@chem-x/create-chemx',
+    isScoped: true,
+    bin: { 'create-chemx': 'cli/index.js', chemx: 'cli/index.js' }
+  },
+  {
+    name: 'chemx',
+    isScoped: false,
+    bin: { chemx: 'cli/index.js', 'create-chemx': 'cli/index.js' }
+  }
+];
+
+const originalContent = fs.readFileSync(PKG_JSON, 'utf-8');
+const pkg = JSON.parse(originalContent);
+const isPrerelease = Boolean(pkg.version && pkg.version.includes('-'));
+const tag = explicitTag || (isPrerelease ? 'latest' : null);
+
+const results = [];
+
+try {
+  for (const target of TARGETS) {
+    pkg.name = target.name;
+    pkg.publishConfig = { access: 'public' };
+    if (tag) {
+      pkg.publishConfig.tag = tag;
+    }
+    pkg.bin = target.bin;
+
+    fs.writeFileSync(PKG_JSON, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+
+    const publishArgs = ['publish', '--access', 'public'];
+    if (isDryRun) publishArgs.push('--dry-run');
+    if (otp) publishArgs.push(`--otp=${otp}`);
+    if (tag) publishArgs.push('--tag', tag);
+
+    console.log(`\n\x1b[36m[starter-kit] Publishing: ${target.name} (dry-run: ${isDryRun}${tag ? `, tag: ${tag}` : ''})\x1b[0m`);
+    const proc = spawnSync('npm', publishArgs, {
+      cwd: PKG_DIR,
+      stdio: 'inherit'
+    });
+
+    results.push({ name: target.name, success: proc.status === 0 });
+  }
+} finally {
+  fs.writeFileSync(PKG_JSON, originalContent, 'utf-8');
+}
+
+console.log('\n\x1b[1m\x1b[36m--- starter-kit Publish Summary ---\x1b[0m');
+for (const res of results) {
+  const icon = res.success ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✕\x1b[0m';
+  console.log(`  ${icon} ${res.name.padEnd(25)} ${res.success ? 'Published' : 'Failed'}`);
+}
+console.log('\x1b[1m\x1b[36m-----------------------------------\x1b[0m\n');