@chemx/create-chemx 26.9.25-943 → 26.9.26-253

package/cli/audit/prompts.js

@@ -66,7 +66,7 @@ export const formatGroupedPromptViolations = (violations = [], options = {}) =>
 export const buildAgentCommandsSection = () => [
   '### AI AGENT DISCOVERY & REFACTORING COMMANDS:',
   '- Claim Work: Run `chemx team task list --status=queued` and claim via `chemx team task claim <id> --as=@coder`.',
-  '- Inspect Target: Run `chemx read <target_path> --outline` to inspect AST signatures without token bloat.',
+  '- Inspect Target: Run `chemx read <target_path> --outline` for AST signatures or `--outline --enrich` for signatures + logic flow without token bloat.',
   '- Verify & Auto-Resolve: Run `chemx verify`. Clean files auto-reconcile tasks to done in SQLite.',
   '- MCP Invocations: If invoking via MCP, pass command string directly via `chemx({ command: "..." })`.'
 ].join('\n');

package/cli/commands/cmd-router.js

@@ -75,6 +75,16 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runSearch(rawArgs.slice(1), true);
       break;
     }
+    case 'trace': {
+      const { runTraceCli } = await import('../search-commands-graph.js');
+      await runTraceCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'backtrace': {
+      const { runBacktraceCli } = await import('../search-commands-graph.js');
+      await runBacktraceCli(rawArgs.slice(1), true);
+      break;
+    }
     case 'build':
     case 'run':
     case 'wrap': {
@@ -166,9 +176,10 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
     case 'g':
     case 'gen':
     case 'generate':
-    case 'capsule': {
+    case 'capsule':
+    case 'jig': {
       const { runGenerateWizard } = await import('../scaffold.js');
-      await runGenerateWizard(rawArgs.slice(1));
+      await runGenerateWizard(rawArgs);
       break;
     }
     case 'badge':
@@ -201,6 +212,13 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runTypecheckAudit(rawArgs.slice(1), true);
       break;
     }
+    case 'lint':
+    case 'check:lint':
+    case 'eslint': {
+      const { runLintAudit } = await import('../verify-lint.js');
+      await runLintAudit(rawArgs.slice(1), true);
+      break;
+    }
     case 'test':
     case 'tests':
     case 'check:test': {

package/cli/commands-schema.js

@@ -16,7 +16,9 @@ export const COMMANDS_SCHEMA = [
       { 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: '--trace', desc: 'Forward call trace: downstream functions invoked by target' },
+      { flag: '--backtrace', desc: 'Reverse backtrace: upstream callers and causal paths leading to target' },
+      { flag: '--max-depth=<N>', desc: 'Max depth for blast radius / trace 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)' },
@@ -26,6 +28,8 @@ export const COMMANDS_SCHEMA = [
     examples: [
       'npx chemx search "badge"',
       'pnpm q a-button --blast-radius --json',
+      'pnpm q useUserCardController --trace',
+      'pnpm q handleAction --backtrace',
       'pnpm q "button click handler" --semantic',
       'pnpm q "useAttentionCardController" --hybrid --json',
       'pnpm q "useTheme" --inspect',
@@ -34,13 +38,18 @@ export const COMMANDS_SCHEMA = [
   },
   {
     name: 'read',
-    aliases: ['view'],
+    aliases: ['view', 'r'],
     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.',
+    summary: 'Token-minified file reader with AST outline and logic extraction.',
+    description: 'Extracts structural AST outlines, logic skeletons, 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: '--outline, -o', desc: 'Signatures only (80%+ token savings)' },
+      { flag: '--logic, -l', desc: 'AST logic skeleton: control flow, guards, and mutations without decorative syntax' },
+      { flag: '--template, -t', desc: 'Extract template markup only (Vue/Svelte/JSX)' },
+      { flag: '--enrich', desc: 'Append compacted logic skeleton after outline (free-lunch overlay). Compose with --outline for signatures + logic in one call.' },
+      { flag: '--trace=<name>', desc: 'Append forward call trace card inline (requires --enrich)' },
+      { flag: '--backtrace=<name>', desc: 'Append reverse caller chain card inline (requires --enrich)' },
+      { flag: '--symbol=<name>, -s', 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' },
@@ -50,10 +59,42 @@ export const COMMANDS_SCHEMA = [
     ],
     examples: [
       'npx chemx read src/store.ts --outline',
+      'npx chemx read src/controller.ts --outline --enrich',
+      'npx chemx read src/card.vue --outline --enrich --trace=handleSubmit',
+      'npx chemx read src/controller.ts --logic',
+      'npx chemx read src/card.vue --template',
       'npx chemx read api.ts --symbol=login --connections',
       'npx chemx read src/ui/atoms/a-button/types.d.ts --symbol=ButtonVariant'
     ]
   },
+  {
+    name: 'trace',
+    usage: 'npx chemx trace <symbol> [options]',
+    summary: 'Forward call trace: inspects downstream function invocations.',
+    description: 'Maps the execution tree of functions, services, and external APIs called by the target symbol.',
+    flags: [
+      { flag: '--max-depth=<N>', desc: 'Max depth for call trace traversal (default: 3)' },
+      { flag: '--json', desc: 'Output call tree as minified JSON' }
+    ],
+    examples: [
+      'npx chemx trace useCartController',
+      'npx chemx trace handleCheckout --json'
+    ]
+  },
+  {
+    name: 'backtrace',
+    usage: 'npx chemx backtrace <symbol> [options]',
+    summary: 'Reverse call backtrace: maps upstream caller chains leading to target.',
+    description: 'Traces the causal path of how user interactions, components, and views trigger the target symbol.',
+    flags: [
+      { flag: '--max-depth=<N>', desc: 'Max depth for backtrace traversal (default: 5)' },
+      { flag: '--json', desc: 'Output causal path as minified JSON' }
+    ],
+    examples: [
+      'npx chemx backtrace handleCheckout',
+      'npx chemx backtrace postOrder --json'
+    ]
+  },
   {
     name: 'patch',
     aliases: ['edit'],
@@ -178,6 +219,24 @@ export const COMMANDS_SCHEMA = [
       'pnpm chemx verify --json'
     ]
   },
+  {
+    name: 'lint',
+    aliases: ['check:lint', 'eslint'],
+    usage: 'npx chemx lint [path] [options]',
+    summary: 'Token-conserving linter runner and tree-formatter with automatic fix.',
+    description: 'Executes ESLint with token-efficient diagnostics, target scoping, and automatic --fix support.',
+    flags: [
+      { flag: '--fix', desc: 'Automatically fix fixable lint and tree-formatting errors' },
+      { flag: '--json', desc: 'Output structured diagnostics as JSON for AI agents' },
+      { flag: '--raw', desc: 'Do not capture or format output' }
+    ],
+    examples: [
+      'npx chemx lint',
+      'npx chemx lint --fix',
+      'npx chemx lint apps/youmeos/components/blueprints/desktop/u-desktop.vue --fix',
+      'pnpm chemx lint --json'
+    ]
+  },
   {
     name: 'pillars',
     aliases: ['config:pillars', 'rules'],

package/cli/generator-help.js

@@ -12,18 +12,29 @@ export const printGenerateHelp = () => {
     `  ${CYAN}npx chemx generate${RESET} <name> [options]`,
     `  ${CYAN}npx chemx generate${RESET} <tier> <name> [options]`,
     '',
-    `${BOLD}TIERS${RESET}`,
-    `  ${CYAN}atom${RESET} (a-)       Foundational UI elements (raw HTML permitted)`,
+    `${BOLD}TIERS & JIG KINDS${RESET}`,
     `  ${CYAN}molecule${RESET} (m-)   Groups of atoms (no raw HTML, co-located controller)`,
+    `  ${CYAN}atom${RESET} (a-)       Foundational UI elements (raw HTML permitted)`,
     `  ${CYAN}organism${RESET} (o-)   Complex feature modules`,
     `  ${CYAN}hook${RESET} (use-)     Domain state / headless composables (< 5 return properties)`,
     `  ${CYAN}view${RESET} (v-)       Declarative Table-of-Contents views`,
+    `  ${CYAN}service${RESET}        Domain service / API client with Result tuples and spec`,
+    `  ${CYAN}route${RESET}          HTTP API route handler with schema validation and test`,
+    `  ${CYAN}store${RESET}          State store / reactive machine with discriminated unions`,
+    `  ${CYAN}repo${RESET}           Database repository with CRUD methods and Result tuples`,
+    `  ${CYAN}util${RESET}           Pure stateless utility functions with test spec`,
+    `  ${CYAN}spec${RESET}           Isolated unit test spec for an existing target`,
     '',
     `${BOLD}OPTIONS${RESET}`,
-    `  ${CYAN}--tier=<tier>${RESET}                    Specify component tier`,
+    `  ${CYAN}--tier=<tier>${RESET}                    Specify component tier (atom, molecule, organism, hook, view)`,
+    `  ${CYAN}--jig=<kind>${RESET}                     Specify programmatic file kind (service, route, store, repo, util, spec)`,
     `  ${CYAN}--framework=<react|vue|svelte>${RESET}  Framework flavor (default: auto-detected or react)`,
-    `  ${CYAN}--dir=<path>${RESET}                     Target directory (default: src/components/<tier>s)`,
+    `  ${CYAN}--dir=<path>${RESET}                     Target directory (default: src/components/<tier>s or src/<kind>s)`,
     `  ${CYAN}--desc="<text>"${RESET}                  Describe functionality to tailor archetype and state`,
+    `  ${CYAN}--methods="<m1,m2>"${RESET}              Method names or signatures for service/repo/store`,
+    `  ${CYAN}--state="<s1,s2>"${RESET}                State property definitions for store or controller`,
+    `  ${CYAN}--routes="<r1,r2>"${RESET}               Route definitions for API route jig (e.g. GET /items, POST /items)`,
+    `  ${CYAN}--schema="<json>"${RESET}                Structured JSON schema definition payload`,
     `  ${CYAN}--dry-run${RESET}                        Preview planned files and lines without touching disk`,
     `  ${CYAN}--lean${RESET}                           Generate minimal capsule without controller/spec`,
     `  ${CYAN}--json${RESET}                           Output result as minified JSON`,
@@ -32,14 +43,23 @@ export const printGenerateHelp = () => {
     '',
     `${BOLD}EXAMPLES${RESET}`,
     `  ${CYAN}npx chemx generate m-task-list --framework=react${RESET}`,
-    `  ${CYAN}npx chemx generate m-task-list --desc="add, toggle, remove items"${RESET}`,
-    `  ${CYAN}npx chemx generate m-task-list --dry-run${RESET}`,
+    `  ${CYAN}npx chemx generate --jig=service payment-gateway --methods="processCharge,refund"${RESET}`,
+    `  ${CYAN}npx chemx jig route api-orders --routes="GET /orders, POST /orders"${RESET}`,
+    `  ${CYAN}npx chemx jig store session-machine --desc="user authentication lifecycle"${RESET}`,
     `  ${CYAN}npx chemx generate hook use-task-filter${RESET}`,
     `  ${CYAN}npx chemx generate view v-user-profile${RESET}`,
     '',
+    `${BOLD}TOKEN ECONOMICS & AGENT JIG${RESET}`,
+    `  ${DIM}Thesis:        Passing a 30-50 token parameter payload to chemx generate / jig replaces${RESET}`,
+    `  ${DIM}               1,000-2,500 output tokens of repetitive TypeScript, SCSS, and spec boilerplate.${RESET}`,
+    `  ${DIM}Reduction:     90%+ fewer LLM output tokens consumed per component, service, or route.${RESET}`,
+    `  ${DIM}Invariants:    Guarantees <100 LOC limits, Result tuples, 2-stage booleans, zero synthetic data,${RESET}`,
+    `  ${DIM}               and co-located unit test specs without LLM syntax drift or hallucination.${RESET}`,
+    '',
     `${BOLD}LINE LIMITS${RESET}`,
     `  ${DIM}Molecule capsule template:  < 100 lines (outer bound)${RESET}`,
     `  ${DIM}Co-located controller hook: < 100 lines (pure reactive state)${RESET}`,
+    `  ${DIM}Domain service / repo:      < 100 lines (stateless or cohesive atomic class)${RESET}`,
     `  ${DIM}Table of Contents view:     10-20 lines (declarative slot assembly)${RESET}`,
     ''
   ];

package/cli/generator-jig-cli.js

@@ -0,0 +1,67 @@
+import { createJigFiles, normalizeJigKind, JIG_KINDS } from './generator-jig.js';
+
+export const handleJigCli = ({ rawArgs, positional, rawName, dirArg, descArg, isDryRun, isJson }) => {
+  const jigFlag = (rawArgs.find((a) => a.startsWith('--jig=')) || '').split('=')[1];
+  const kindFlag = (rawArgs.find((a) => a.startsWith('--kind=')) || '').split('=')[1];
+
+  let resolvedKind = jigFlag || kindFlag;
+  let resolvedName = rawName;
+
+  if (!resolvedKind && positional[0] && JIG_KINDS.has(positional[0].toLowerCase())) {
+    resolvedKind = positional[0].toLowerCase();
+    resolvedName = positional[1] || rawName;
+  } else if (positional[0] && positional[0].toLowerCase() === 'jig') {
+    resolvedKind = positional[1];
+    resolvedName = positional[2] || rawName;
+  }
+  resolvedKind = normalizeJigKind(resolvedKind || 'service');
+
+  const methodsArg = (rawArgs.find((a) => a.startsWith('--methods=')) || '').replace(/^--methods=/, '');
+  const stateArg = (rawArgs.find((a) => a.startsWith('--state=')) || '').replace(/^--state=/, '');
+  const routesArg = (rawArgs.find((a) => a.startsWith('--routes=')) || '').replace(/^--routes=/, '');
+  const presetArg = (rawArgs.find((a) => a.startsWith('--preset=')) || '').replace(/^--preset=/, '');
+  const schemaArg = (rawArgs.find((a) => a.startsWith('--schema=')) || '').replace(/^--schema=/, '');
+
+  let schemaData = {};
+  if (schemaArg) {
+    try {
+      schemaData = JSON.parse(schemaArg);
+    } catch {
+      // ignore JSON parse error
+    }
+  }
+
+  const jigRes = createJigFiles({
+    kind: schemaData.kind || resolvedKind,
+    name: schemaData.name || resolvedName || `sample-${resolvedKind}`,
+    dir: dirArg,
+    preset: presetArg,
+    methods: schemaData.methods || methodsArg,
+    state: schemaData.state || stateArg,
+    routes: schemaData.routes || routesArg,
+    desc: descArg || schemaData.desc,
+    dryRun: isDryRun,
+    cwd: process.cwd()
+  });
+
+  if (isJson) {
+    process.stdout.write(JSON.stringify(jigRes) + '\n');
+    return jigRes;
+  }
+
+  if (jigRes.dryRun) {
+    process.stdout.write(`\n\x1b[1m\x1b[33m[DRY RUN]\x1b[0m Would generate programmatic jig (${jigRes.kind}) at \x1b[36m${jigRes.relativeDir}/\x1b[0m:\n`);
+    for (const f of jigRes.previews || []) {
+      process.stdout.write(`  \x1b[33m•\x1b[0m ${f.file} (${f.lines} lines)\n`);
+    }
+    process.stdout.write('\n\x1b[2mDry run complete. No files were written to disk.\x1b[0m\n\n');
+    return jigRes;
+  }
+
+  process.stdout.write(`\n\x1b[1m\x1b[32m✔ Successfully generated programmatic jig (${jigRes.kind}):\x1b[0m \x1b[36m${jigRes.relativeDir}/\x1b[0m\n`);
+  for (const f of jigRes.filesCreated) {
+    process.stdout.write(`  \x1b[32m✔\x1b[0m ${f}\n`);
+  }
+  process.stdout.write('\n\x1b[2mChemical X Standards verified: < 100 lines per file, Result tuples, co-located spec tests.\x1b[0m\n\n');
+  return jigRes;
+};