@chemx/starter-kit 26.9.17-606 → 26.9.20-228

package/cli/build/detector.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const findFileUpward = (fileName, startDir) => {
+export const findFileUpward = (fileName, startDir) => {
   let currentDir = path.resolve(startDir);
   while (true) {
     const candidate = path.join(currentDir, fileName);
@@ -13,18 +13,17 @@ const findFileUpward = (fileName, startDir) => {
   return null;
 };
 
-const resolvePackageManager = (cwd) => {
-  const hasPnpmLock = Boolean(findFileUpward('pnpm-lock.yaml', cwd));
-  const hasYarnLock = Boolean(findFileUpward('yarn.lock', cwd));
-  const hasBunLock = Boolean(findFileUpward('bun.lockb', cwd) || findFileUpward('bun.lock', cwd));
-
-  if (hasPnpmLock) return 'pnpm';
-  if (hasYarnLock) return 'yarn';
-  if (hasBunLock) return 'bun';
-  return 'npm';
+export const findProjectRoot = (startDir = process.cwd()) => {
+  const pkgFile = findFileUpward('package.json', startDir);
+  if (pkgFile) return path.dirname(pkgFile);
+  const chemxDir = findFileUpward('.chemx', startDir);
+  if (chemxDir) return path.dirname(chemxDir);
+  const cardVault = '/home/xopher/www/elysium/apps/my-card-vault';
+  if (fs.existsSync(cardVault)) return cardVault;
+  return startDir;
 };
 
-const loadLocalPackageJson = (cwd) => {
+export const loadLocalPackageJson = (cwd) => {
   const pkgPath = path.join(cwd, 'package.json');
   if (!fs.existsSync(pkgPath)) return null;
   try {
@@ -34,6 +33,31 @@ const loadLocalPackageJson = (cwd) => {
   }
 };
 
+export const resolvePackageManager = (cwd) => {
+  const pkg = loadLocalPackageJson(cwd);
+  if (pkg && typeof pkg.packageManager === 'string') {
+    const pmField = pkg.packageManager.toLowerCase();
+    if (pmField.startsWith('pnpm')) return 'pnpm';
+    if (pmField.startsWith('bun')) return 'bun';
+    if (pmField.startsWith('yarn')) return 'yarn';
+    if (pmField.startsWith('npm')) return 'npm';
+  }
+
+  let currentDir = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(currentDir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (fs.existsSync(path.join(currentDir, 'bun.lockb')) || fs.existsSync(path.join(currentDir, 'bun.lock'))) return 'bun';
+    if (fs.existsSync(path.join(currentDir, 'yarn.lock'))) return 'yarn';
+    if (fs.existsSync(path.join(currentDir, 'package-lock.json'))) return 'npm';
+
+    const parent = path.dirname(currentDir);
+    if (parent === currentDir) break;
+    currentDir = parent;
+  }
+
+  return 'npm';
+};
+
 export const detectProjectBuildCommand = (customCmd, cwd = process.cwd()) => {
   const hasCustomCommand = Boolean(customCmd && customCmd.trim().length > 0);
   if (hasCustomCommand) return customCmd.trim();
@@ -42,18 +66,11 @@ export const detectProjectBuildCommand = (customCmd, cwd = process.cwd()) => {
   const pkg = loadLocalPackageJson(cwd);
   const scripts = (pkg && pkg.scripts) || {};
 
-  const hasBuildScript = Boolean(scripts.build);
-  const hasBuildPublicScript = Boolean(scripts['build:public']);
-  const hasBuildProdScript = Boolean(scripts['build:prod']);
-
-  if (hasBuildScript) {
-    return pm === 'yarn' ? 'yarn build' : `${pm} run build`;
-  }
-  if (hasBuildPublicScript) {
-    return pm === 'yarn' ? 'yarn build:public' : `${pm} run build:public`;
-  }
-  if (hasBuildProdScript) {
-    return pm === 'yarn' ? 'yarn build:prod' : `${pm} run build:prod`;
+  const scriptCandidates = ['build', 'build:prod', 'build:public', 'bundle'];
+  for (const scriptName of scriptCandidates) {
+    if (scripts[scriptName]) {
+      return pm === 'yarn' ? `yarn ${scriptName}` : `${pm} run ${scriptName}`;
+    }
   }
 
   const hasViteConfig = fs.existsSync(path.join(cwd, 'vite.config.js')) ||

package/cli/build/detector.spec.js

@@ -0,0 +1,81 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  findFileUpward,
+  resolvePackageManager,
+  detectProjectBuildCommand
+} from './detector.js';
+
+test('detector: resolvePackageManager detects packageManager field in package.json', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-detector-pm-field');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({ name: 'test-app', packageManager: 'pnpm@9.1.0' }),
+    'utf-8'
+  );
+
+  const pm = resolvePackageManager(tmpDir);
+  assert.strictEqual(pm, 'pnpm');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('detector: resolvePackageManager detects upward lockfiles', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-detector-lockfile');
+  const subDir = path.join(tmpDir, 'apps/sub-app');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(subDir, { recursive: true });
+
+  fs.writeFileSync(path.join(tmpDir, 'bun.lockb'), '', 'utf-8');
+  fs.writeFileSync(path.join(subDir, 'package.json'), JSON.stringify({ name: 'sub-app' }), 'utf-8');
+
+  const pm = resolvePackageManager(subDir);
+  assert.strictEqual(pm, 'bun');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('detector: detectProjectBuildCommand uses custom command verbatim', () => {
+  const cmd = detectProjectBuildCommand('vite build --mode production');
+  assert.strictEqual(cmd, 'vite build --mode production');
+});
+
+test('detector: detectProjectBuildCommand auto-detects from package.json scripts.build', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-detector-build-script');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({
+      name: 'test-app',
+      packageManager: 'pnpm@9.0.0',
+      scripts: { build: 'vue-tsc --noEmit && vite build' }
+    }),
+    'utf-8'
+  );
+
+  const cmd = detectProjectBuildCommand(null, tmpDir);
+  assert.strictEqual(cmd, 'pnpm run build');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('detector: detectProjectBuildCommand falls back to vite when vite.config exists', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-detector-vite-fallback');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({ name: 'test-app' }), 'utf-8');
+  fs.writeFileSync(path.join(tmpDir, 'vite.config.ts'), 'export default {}', 'utf-8');
+
+  const cmd = detectProjectBuildCommand('', tmpDir);
+  assert.strictEqual(cmd, 'npx vite build');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});

package/cli/build.js

@@ -1,9 +1,10 @@
-import { detectProjectBuildCommand } from './build/detector.js';
+import { detectProjectBuildCommand, findProjectRoot } from './build/detector.js';
 import { executeBuild } from './build/executor.js';
 import { parseBuildOutput } from './build/parser.js';
 import { groupBuildDiagnostics } from './build/grouper.js';
 import { formatTerminalBuildReport, formatJsonBuildReport } from './build/reporter.js';
 import { ANSI } from './theme.js';
+import { handleError } from './errors/index.js';
 
 const IGNORED_COMMAND_TOKENS = new Set(['build', 'run', 'wrap']);
 
@@ -21,21 +22,22 @@ const parseCommandFromArgs = (args) => {
 };
 
 export const runBuildAudit = async (rawArgs = [], isCli = false, options = {}) => {
-  const isJson = rawArgs.includes('--json');
+  const isJson = rawArgs.includes('--json') || options.json === true;
   const isSilent = rawArgs.includes('--silent') || options.silent === true;
-  const isRaw = rawArgs.includes('--raw');
-  const isSummary = rawArgs.includes('--summary');
+  const isRaw = rawArgs.includes('--raw') || options.raw === true;
+  const isSummary = rawArgs.includes('--summary') || options.summary === true;
   const shouldPrint = options.print !== false;
+  const cwd = findProjectRoot(options.cwd || process.cwd());
 
-  const customCommand = parseCommandFromArgs(rawArgs);
-  const command = detectProjectBuildCommand(customCommand, process.cwd());
+  const customCommand = parseCommandFromArgs(rawArgs) || options.command;
+  const command = detectProjectBuildCommand(customCommand, cwd);
 
   const shouldPrintStart = shouldPrint && !isJson && !isSilent && !isRaw;
   if (shouldPrintStart) {
     process.stdout.write(`${ANSI.CYAN}Auditing build:${ANSI.RESET} ${ANSI.DIM}${command}${ANSI.RESET}\n`);
   }
 
-  const executionResult = await executeBuild(command, process.cwd(), { raw: isRaw });
+  const executionResult = await executeBuild(command, cwd, { raw: isRaw });
   const rawDiagnostics = parseBuildOutput(executionResult.stdout, executionResult.stderr);
   const report = groupBuildDiagnostics(rawDiagnostics, executionResult);
 
@@ -52,6 +54,26 @@ export const runBuildAudit = async (rawArgs = [], isCli = false, options = {}) =
     process.stdout.write(terminalOutput);
   }
 
+  const isFailedBuild = report.exitCode !== 0;
+  const hasIssueFlag = rawArgs.includes('--prep-issue') || rawArgs.includes('--post-issue');
+  const shouldHandleError = isFailedBuild && (hasIssueFlag || options.postIssue || (isCli && !isJson));
+
+  if (shouldHandleError) {
+    const errorDetails = `Build command failed with exit code ${report.exitCode}: ${command}`;
+    await handleError(new Error(errorDetails), {
+      cwd,
+      command,
+      exitCode: report.exitCode,
+      autoPost: rawArgs.includes('--post-issue') || options.postIssue,
+      silent: isSilent || isJson,
+      context: {
+        totalErrors: report.totalErrors,
+        totalWarnings: report.totalWarnings,
+        categories: report.categories
+      }
+    });
+  }
+
   if (isCli) {
     process.exit(report.exitCode);
   }

package/cli/errors/catcher.js

@@ -0,0 +1,80 @@
+import { copyToClipboard } from '../audit/social-git.js';
+import { formatIssueContent } from './formatter.js';
+import { publishIssue } from './publisher.js';
+import { openBrowser, confirmAction } from '../terminal.js';
+import { resolveTargetIssuesRepo, saveIssueArtifact } from './storage.js';
+
+export { resolveTargetIssuesRepo, saveIssueArtifact };
+
+const promptUserToPublish = async (targetRepo, issue) => {
+  const confirmed = await confirmAction('Post this error report directly to GitHub Issues?', 'Post Issue', 'Skip', false);
+  if (!confirmed) {
+    return { success: false, url: null, issueNumber: null, error: null };
+  }
+
+  const publishResult = await publishIssue(targetRepo, issue.title, issue.body, issue.labels);
+  if (publishResult.success) {
+    process.stdout.write(`\x1b[32m✔ Issue published: ${publishResult.url}\x1b[0m\n`);
+    openBrowser(publishResult.url);
+  } else {
+    copyToClipboard(issue.body);
+    process.stdout.write(`\x1b[33m⚠ Publish failed. Markdown copied to clipboard. Opening browser...\x1b[0m\n`);
+    openBrowser(issue.webUrl);
+  }
+  return publishResult;
+};
+
+export const handleError = async (err, options = {}) => {
+  const cwd = options.cwd || process.cwd();
+  const errorObj = err instanceof Error ? err : new Error(String(err));
+  const targetRepo = resolveTargetIssuesRepo(options, cwd);
+
+  const rawCmd = options.command || process.argv.slice(2).join(' ');
+  const command = rawCmd || 'chemx';
+
+  const report = {
+    message: errorObj.message,
+    name: errorObj.name,
+    stack: errorObj.stack || '',
+    command,
+    cwd,
+    exitCode: options.exitCode ?? 1,
+    timestamp: new Date().toISOString(),
+    nodeVersion: process.version,
+    platform: `${process.platform}-${process.arch}`,
+    chemxVersion: options.chemxVersion || '26.9.17',
+    context: options.context || {}
+  };
+
+  const issue = formatIssueContent(report, targetRepo, options.labels);
+  const savedPath = saveIssueArtifact(cwd, issue, options);
+
+  const hasToken = Boolean(process.env.GH_TOKEN || process.env.GITHUB_TOKEN);
+  const isCiEnv = Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
+  const isExplicitAutoPost = Boolean(options.autoPost || process.env.CHEMX_AUTO_POST_ISSUES === 'true');
+  const isCiAutoPost = isCiEnv && hasToken && options.autoPost !== false;
+  const shouldAutoPost = isExplicitAutoPost || isCiAutoPost;
+
+  let publishResult = { success: false, url: null, issueNumber: null, error: null };
+
+  if (shouldAutoPost) {
+    publishResult = await publishIssue(targetRepo, issue.title, issue.body, issue.labels);
+    if (publishResult.success && !options.silent) {
+      process.stdout.write(`\n\x1b[32m✔ Issue automatically created: ${publishResult.url}\x1b[0m\n`);
+    }
+  } else if (!options.silent) {
+    const isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const isInteractive = isTty && !isCiEnv;
+    process.stderr.write(`\n\x1b[31m✕ Command Failed: ${report.message}\x1b[0m\n`);
+    process.stderr.write(`  \x1b[33m• Prepped Issue:\x1b[0m ${issue.webUrl}\n`);
+    if (savedPath) {
+      process.stderr.write(`  \x1b[33m• Local Report:\x1b[0m ${savedPath}\n`);
+    }
+
+    if (isInteractive) {
+      publishResult = await promptUserToPublish(targetRepo, issue);
+    }
+  }
+
+  return { report, issue, publishResult, savedPath };
+};

package/cli/errors/errors.spec.js

@@ -0,0 +1,163 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {
+  maskSensitiveTokens,
+  normalizeHomePath,
+  sanitizeText,
+  sanitizeStackTrace
+} from './sanitizer.js';
+import {
+  buildIssueTitle,
+  buildIssueBody,
+  buildIssueWebUrl,
+  formatIssueContent
+} from './formatter.js';
+import {
+  handleError,
+  resolveTargetIssuesRepo,
+  saveIssueArtifact
+} from './catcher.js';
+import { withErrorCatcher } from './index.js';
+
+describe('Universal Error Catcher: Sanitizer', () => {
+  it('masks GitHub personal access tokens and npm tokens', () => {
+    const input = 'Failed with token ghp_123456789012345678901234567890123456 and npm_abcdefghijklmnopqrstuvwxyz012345';
+    const sanitized = maskSensitiveTokens(input);
+    assert.ok(!sanitized.includes('ghp_1234567890'));
+    assert.ok(!sanitized.includes('npm_abcdefgh'));
+    assert.ok(sanitized.includes('[REDACTED_SECRET]'));
+  });
+
+  it('masks Bearer tokens and api-key parameters', () => {
+    const input = 'Authorization: Bearer mySecretToken123456789\napiKey="superSecretApiKey123"';
+    const sanitized = maskSensitiveTokens(input);
+    assert.ok(!sanitized.includes('mySecretToken123456789'));
+    assert.ok(!sanitized.includes('superSecretApiKey123'));
+    assert.ok(sanitized.includes('Bearer [REDACTED]'));
+  });
+
+  it('normalizes home directory paths', () => {
+    const home = os.homedir();
+    const input = `Error reading file in ${home}/my-project/index.ts`;
+    const normalized = normalizeHomePath(input);
+    assert.ok(!normalized.includes(home));
+    assert.ok(normalized.includes('~/my-project/index.ts'));
+  });
+
+  it('sanitizes full stack traces', () => {
+    const home = os.homedir();
+    const stack = `Error: crash\n    at test (${home}/apps/test.js:10:5)\n    token: ghp_123456789012345678901234567890`;
+    const sanitized = sanitizeStackTrace(stack);
+    assert.ok(!sanitized.includes(home));
+    assert.ok(!sanitized.includes('ghp_1234567890'));
+    assert.ok(sanitized.includes('~/apps/test.js'));
+  });
+});
+
+describe('Universal Error Catcher: Formatter', () => {
+  const sampleReport = {
+    message: 'TypeError: Cannot read properties of undefined',
+    name: 'TypeError',
+    stack: 'TypeError: Cannot read properties of undefined\n    at run (/src/app.ts:1:1)',
+    command: 'chemx build --production',
+    cwd: '/workspace',
+    exitCode: 1,
+    timestamp: '2026-09-17T12:00:00.000Z',
+    nodeVersion: 'v22.20.0',
+    platform: 'linux-x64',
+    chemxVersion: '26.9.17'
+  };
+
+  it('builds concise issue title', () => {
+    const title = buildIssueTitle(sampleReport);
+    assert.ok(title.startsWith('[ChemX Failure] chemx:'));
+    assert.ok(title.includes('TypeError: Cannot read properties'));
+  });
+
+  it('builds detailed markdown issue body with environment and details', () => {
+    const body = buildIssueBody(sampleReport);
+    assert.ok(body.includes('Execution Context'));
+    assert.ok(body.includes('`chemx build --production`'));
+    assert.ok(body.includes('v22.20.0'));
+    assert.ok(body.includes('Diagnostic Stack Trace'));
+    assert.ok(body.includes('<details open>'));
+  });
+
+  it('constructs valid GitHub new issue web url', () => {
+    const url = buildIssueWebUrl('org/repo', 'Issue Title', 'Issue Body', ['bug', 'build-failure']);
+    assert.ok(url.startsWith('https://github.com/org/repo/issues/new?'));
+    const parsed = new URL(url);
+    assert.equal(parsed.searchParams.get('title'), 'Issue Title');
+    assert.equal(parsed.searchParams.get('labels'), 'bug,build-failure');
+  });
+
+  it('formats full issue content object', () => {
+    const content = formatIssueContent(sampleReport, 'my-org/my-repo', ['critical-error']);
+    assert.equal(content.targetRepo, 'my-org/my-repo');
+    assert.deepEqual(content.labels, ['critical-error']);
+    assert.ok(content.webUrl.includes('my-org/my-repo/issues/new'));
+  });
+});
+
+describe('Universal Error Catcher: Catcher & Orchestration', () => {
+  it('resolves explicit repo option over defaults', () => {
+    const repo = resolveTargetIssuesRepo({ repo: 'custom/repo' }, '/tmp');
+    assert.equal(repo, 'custom/repo');
+  });
+
+  it('saves issue markdown artifact to .chemx/issues directory', () => {
+    const tempCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-err-test-'));
+    try {
+      const issue = {
+        title: 'Test Error',
+        body: '# Test Error Markdown Body',
+        labels: ['test'],
+        webUrl: 'https://github.com/test/repo/issues/new',
+        targetRepo: 'test/repo'
+      };
+      const savedPath = saveIssueArtifact(tempCwd, issue);
+      assert.ok(savedPath && fs.existsSync(savedPath));
+      const content = fs.readFileSync(savedPath, 'utf-8');
+      assert.equal(content, issue.body);
+
+      const lastPath = path.join(tempCwd, '.chemx', 'issues', 'last-error-issue.md');
+      assert.ok(fs.existsSync(lastPath));
+    } finally {
+      fs.rmSync(tempCwd, { recursive: true, force: true });
+    }
+  });
+
+  it('withErrorCatcher returns function result on success', async () => {
+    const result = await withErrorCatcher(async () => 42, { exitOnError: false });
+    assert.equal(result, 42);
+  });
+
+  it('withErrorCatcher catches error, prepares issue, and returns error result without crashing', async () => {
+    const tempCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-catcher-test-'));
+    try {
+      const res = await withErrorCatcher(
+        async () => {
+          throw new Error('Simulated build pipeline failure');
+        },
+        {
+          cwd: tempCwd,
+          silent: true,
+          exitOnError: false,
+          repo: 'test-org/test-repo'
+        }
+      );
+
+      assert.ok(res.report);
+      assert.equal(res.report.message, 'Simulated build pipeline failure');
+      assert.ok(res.issue);
+      assert.equal(res.issue.targetRepo, 'test-org/test-repo');
+      assert.ok(res.savedPath);
+      assert.ok(fs.existsSync(res.savedPath));
+    } finally {
+      fs.rmSync(tempCwd, { recursive: true, force: true });
+    }
+  });
+});

package/cli/errors/formatter.js

@@ -0,0 +1,94 @@
+import { sanitizeText, sanitizeStackTrace } from './sanitizer.js';
+
+export const buildIssueTitle = (report) => {
+  const cmd = report.command ? report.command.split(' ')[0] : 'chemx';
+  const rawMsg = report.message || 'Unknown error occurred';
+  const cleanMsg = rawMsg.split('\n')[0].replace(/[\r\n\t]+/g, ' ').trim();
+  const truncatedMsg = cleanMsg.length > 70 ? `${cleanMsg.slice(0, 67)}...` : cleanMsg;
+  return `[ChemX Failure] ${cmd}: ${truncatedMsg}`;
+};
+
+export const buildIssueBody = (report) => {
+  const rawStack = report.stack || report.message;
+  const stackContent = rawStack || 'No stack trace available';
+  const sanitizedStack = sanitizeStackTrace(stackContent);
+  const sanitizedCommand = sanitizeText(report.command || 'chemx');
+  const sanitizedCwd = sanitizeText(report.cwd || process.cwd());
+
+  const lines = [
+    '### 🚨 Chemical X Execution Failure Report',
+    '',
+    'An automated failure report was prepared by the Chemical X Universal Error Catcher.',
+    '',
+    '#### 📊 Execution Context',
+    `| Property | Value |`,
+    `| :--- | :--- |`,
+    `| **Command** | \`${sanitizedCommand}\` |`,
+    `| **Exit Code** | \`${report.exitCode ?? 1}\` |`,
+    `| **Timestamp** | \`${report.timestamp || new Date().toISOString()}\` |`,
+    `| **Node.js** | \`${report.nodeVersion || process.version}\` |`,
+    `| **Platform** | \`${report.platform || process.platform}\` |`,
+    `| **ChemX Version** | \`${report.chemxVersion || 'unknown'}\` |`,
+    `| **Working Dir** | \`${sanitizedCwd}\` |`
+  ];
+
+  if (report.gitBranch) {
+    lines.push(`| **Git Branch** | \`${report.gitBranch}\` |`);
+  }
+  if (report.gitCommit) {
+    lines.push(`| **Git Commit** | \`${report.gitCommit}\` |`);
+  }
+
+  lines.push('');
+  lines.push('#### 💥 Diagnostic Stack Trace');
+  lines.push('<details open>');
+  lines.push('<summary>Click to collapse error details</summary>');
+  lines.push('');
+  lines.push('```text');
+  lines.push(sanitizedStack.trim());
+  lines.push('```');
+  lines.push('</details>');
+
+  if (report.context && Object.keys(report.context).length > 0) {
+    lines.push('');
+    lines.push('#### 🔍 Additional Metadata');
+    lines.push('```json');
+    lines.push(JSON.stringify(report.context, null, 2));
+    lines.push('```');
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('> *Generated automatically by Chemical X Protocol Universal Error Catcher.*');
+
+  return lines.join('\n');
+};
+
+export const buildIssueWebUrl = (repo, title, body, labels = []) => {
+  const hasRepo = Boolean(repo && repo.includes('/'));
+  const safeRepo = hasRepo ? repo : 'Chemical-X-Protocol/starter-kit';
+  const base = `https://github.com/${safeRepo}/issues/new`;
+  const params = new URLSearchParams();
+  params.set('title', title);
+  params.set('body', body);
+  if (labels && labels.length > 0) {
+    params.set('labels', labels.join(','));
+  }
+  return `${base}?${params.toString()}`;
+};
+
+export const formatIssueContent = (report, targetRepo, customLabels = null) => {
+  const defaultLabels = ['chemx-failure', 'bug'];
+  const labels = customLabels || defaultLabels;
+  const title = buildIssueTitle(report);
+  const body = buildIssueBody(report);
+  const webUrl = buildIssueWebUrl(targetRepo, title, body, labels);
+
+  return {
+    title,
+    body,
+    labels,
+    webUrl,
+    targetRepo
+  };
+};

package/cli/errors/index.js

@@ -0,0 +1,52 @@
+import { handleError, resolveTargetIssuesRepo, saveIssueArtifact } from './catcher.js';
+import { formatIssueContent, buildIssueTitle, buildIssueBody, buildIssueWebUrl } from './formatter.js';
+import { publishIssue, publishIssueViaHttp, publishIssueViaGh } from './publisher.js';
+import { sanitizeText, sanitizeStackTrace, maskSensitiveTokens } from './sanitizer.js';
+
+export const withErrorCatcher = async (fn, options = {}) => {
+  try {
+    return await fn();
+  } catch (err) {
+    const res = await handleError(err, options);
+    const shouldExit = options.exitOnError !== false;
+    if (shouldExit) {
+      process.exit(options.exitCode ?? 1);
+    }
+    return res;
+  }
+};
+
+export const installGlobalErrorCatcher = (options = {}) => {
+  const handler = async (err, errorType) => {
+    const errorObj = err instanceof Error ? err : new Error(String(err));
+    await handleError(errorObj, {
+      ...options,
+      context: { ...options.context, errorType }
+    });
+    process.exit(1);
+  };
+
+  process.on('uncaughtException', (err) => {
+    handler(err, 'uncaughtException');
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    handler(reason, 'unhandledRejection');
+  });
+};
+
+export {
+  handleError,
+  resolveTargetIssuesRepo,
+  saveIssueArtifact,
+  formatIssueContent,
+  buildIssueTitle,
+  buildIssueBody,
+  buildIssueWebUrl,
+  publishIssue,
+  publishIssueViaHttp,
+  publishIssueViaGh,
+  sanitizeText,
+  sanitizeStackTrace,
+  maskSensitiveTokens
+};