@chemx/starter-kit 26.9.13-383 → 26.9.14-205

package/cli/audit/social-git.js

@@ -2,9 +2,13 @@ import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 
-const safeSpawnSync = (command, args, options) => {
+const safeSpawnSync = (command, args, options = {}) => {
   try {
-    const res = spawnSync(command, args, options);
+    const optsWithDefaults = {
+      timeout: 1000,
+      ...options
+    };
+    const res = spawnSync(command, args, optsWithDefaults);
     if (res.error) {
       return [null, res.error];
     }
@@ -193,24 +197,92 @@ export const detectGitHubUser = (preferredUser) => {
   return 'Architect';
 };
 
+export const copyViaOsc52 = (text) => {
+  if (typeof text !== 'string' || !text) return false;
+  try {
+    const base64 = Buffer.from(text, 'utf-8').toString('base64');
+    const isTmux = Boolean(process.env.TMUX);
+    const isScreen = Boolean(process.env.TERM && process.env.TERM.startsWith('screen'));
+
+    let seq = `\x1b]52;c;${base64}\x07`;
+    if (isTmux) {
+      seq = `\x1bPtmux;\x1b\x1b]52;c;${base64}\x07\x1b\\`;
+    } else if (isScreen) {
+      seq = `\x1bP\x1b]52;c;${base64}\x07\x1b\\`;
+    }
+
+    if (process.stdout.isTTY) {
+      process.stdout.write(seq);
+      return true;
+    }
+    if (process.stderr.isTTY) {
+      process.stderr.write(seq);
+      return true;
+    }
+    try {
+      const fd = fs.openSync('/dev/tty', 'w');
+      fs.writeSync(fd, seq);
+      fs.closeSync(fd);
+      return true;
+    } catch {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+};
+
 export const copyToClipboard = (text) => {
+  if (typeof text !== 'string' || !text) return false;
+
+  let copied = false;
+
   if (process.platform === 'darwin') {
-    const [res] = safeSpawnSync('pbcopy', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
-    return res?.status === 0;
-  }
-  if (process.platform === 'win32') {
-    const [res] = safeSpawnSync('clip', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
-    return res?.status === 0;
-  }
-  const [wlWhich] = safeSpawnSync('which', ['wl-copy'], { stdio: 'ignore' });
-  if (wlWhich?.status === 0) {
-    const [res] = safeSpawnSync('wl-copy', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
-    if (res?.status === 0) return true;
-  }
-  const [xcWhich] = safeSpawnSync('which', ['xclip'], { stdio: 'ignore' });
-  if (xcWhich?.status === 0) {
-    const [res] = safeSpawnSync('xclip', ['-selection', 'clipboard'], { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
-    if (res?.status === 0) return true;
+    const [res] = safeSpawnSync('pbcopy', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'], timeout: 1000 });
+    if (res?.status === 0) copied = true;
+  } else if (process.platform === 'win32') {
+    const [res] = safeSpawnSync('clip', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'], timeout: 1000 });
+    if (res?.status === 0) copied = true;
+  } else {
+    // Linux / BSD / Unix environments
+    const isWsl = Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+    const isSommelier = Boolean(process.env.SOMMELIER_VM_IDENTIFIER || process.env.SOMMELIER_VERSION);
+
+    if (isWsl) {
+      const [wslRes] = safeSpawnSync('clip.exe', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'], timeout: 1000 });
+      if (wslRes?.status === 0) copied = true;
+    }
+
+    // wl-copy hangs in Sommelier / ChromeOS containers due to lack of unfocused data-control support
+    if (!copied && !isSommelier) {
+      const [wlWhich] = safeSpawnSync('which', ['wl-copy'], { stdio: 'ignore', timeout: 500 });
+      if (wlWhich?.status === 0) {
+        const [res] = safeSpawnSync('wl-copy', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'], timeout: 800 });
+        if (res?.status === 0) copied = true;
+      }
+    }
+
+    if (!copied) {
+      const [xcWhich] = safeSpawnSync('which', ['xclip'], { stdio: 'ignore', timeout: 500 });
+      if (xcWhich?.status === 0) {
+        const [res] = safeSpawnSync('xclip', ['-selection', 'clipboard'], { input: text, stdio: ['pipe', 'ignore', 'ignore'], timeout: 800 });
+        if (res?.status === 0) copied = true;
+      }
+    }
+
+    if (!copied) {
+      const [xsWhich] = safeSpawnSync('which', ['xsel'], { stdio: 'ignore', timeout: 500 });
+      if (xsWhich?.status === 0) {
+        const [res] = safeSpawnSync('xsel', ['--clipboard', '--input'], { input: text, stdio: ['pipe', 'ignore', 'ignore'], timeout: 800 });
+        if (res?.status === 0) copied = true;
+      }
+    }
   }
-  return false;
+
+  // OSC 52 ANSI escape sequence: universally supported across modern terminal emulators
+  // (ChromeOS Terminal, iTerm2, Alacritty, Kitty, WezTerm, VS Code, Windows Terminal, tmux, screen).
+  // This provides zero-hang clipboard access over SSH, Crostini containers, Docker, and remote sessions.
+  const oscCopied = copyViaOsc52(text);
+
+  return copied || oscCopied;
 };

package/cli/audit/social-git.spec.js

@@ -0,0 +1,71 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import {
+  copyViaOsc52,
+  copyToClipboard,
+  parseGitRemoteUrl
+} from './social-git.js';
+
+test('copyViaOsc52: edge cases and input validation', () => {
+  assert.strictEqual(copyViaOsc52(''), false);
+  assert.strictEqual(copyViaOsc52(null), false);
+  assert.strictEqual(copyViaOsc52(undefined), false);
+  assert.strictEqual(copyViaOsc52(123), false);
+});
+
+test('copyViaOsc52: generates OSC 52 sequence without throwing', () => {
+  const originalWrite = process.stdout.write;
+  let written = '';
+  process.stdout.write = (chunk) => {
+    written += chunk;
+    return true;
+  };
+
+  try {
+    const isTty = process.stdout.isTTY;
+    process.stdout.isTTY = true;
+    const res = copyViaOsc52('Hello Chemical X');
+    assert.strictEqual(res, true);
+    assert.ok(written.includes('\x1b]52;c;'));
+    assert.ok(written.includes(Buffer.from('Hello Chemical X').toString('base64')));
+    process.stdout.isTTY = isTty;
+  } finally {
+    process.stdout.write = originalWrite;
+  }
+});
+
+test('copyToClipboard: handles invalid and empty inputs gracefully', () => {
+  assert.strictEqual(copyToClipboard(''), false);
+  assert.strictEqual(copyToClipboard(null), false);
+  assert.strictEqual(copyToClipboard(undefined), false);
+});
+
+test('copyToClipboard: executes without hanging and respects timeout boundaries', () => {
+  const startTime = Date.now();
+  const res = copyToClipboard('Test refactoring prompt content');
+  const elapsed = Date.now() - startTime;
+
+  assert.ok(elapsed < 1000, `Expected elapsed time < 1000ms, got ${elapsed}ms`);
+  assert.strictEqual(typeof res, 'boolean');
+});
+
+test('parseGitRemoteUrl: handles SSH and HTTPS URLs correctly', () => {
+  const ssh = parseGitRemoteUrl('git@github.com:Chemical-X-Protocol/starter-kit.git');
+  assert.deepStrictEqual(ssh, {
+    owner: 'Chemical-X-Protocol',
+    repo: 'starter-kit',
+    nameWithOwner: 'Chemical-X-Protocol/starter-kit',
+    url: 'https://github.com/Chemical-X-Protocol/starter-kit'
+  });
+
+  const https = parseGitRemoteUrl('https://github.com/Chemical-X-Protocol/starter-kit.git');
+  assert.deepStrictEqual(https, {
+    owner: 'Chemical-X-Protocol',
+    repo: 'starter-kit',
+    nameWithOwner: 'Chemical-X-Protocol/starter-kit',
+    url: 'https://github.com/Chemical-X-Protocol/starter-kit'
+  });
+
+  assert.strictEqual(parseGitRemoteUrl(''), null);
+  assert.strictEqual(parseGitRemoteUrl(null), null);
+});

package/cli/audit/social.d.ts

@@ -23,6 +23,7 @@ export declare const DEFAULT_DISCUSSION_REPO: string;
 export declare function parseGitRemoteUrl(url: string): GitRepoInfo | null;
 export declare function detectGitRepoInfo(cwd?: string): GitRepoInfo;
 export declare function detectGitHubUser(preferredUser?: string): string;
+export declare function copyViaOsc52(text: string): boolean;
 export declare function copyToClipboard(text: string): boolean;
 export declare function resolveBadgeColor(score: number): string;
 export declare function resolveHotspotTierText(lineCount: number): string;

package/cli/audit/social.js

@@ -10,6 +10,7 @@ export {
   parseGitRemoteUrl,
   detectGitRepoInfo,
   detectGitHubUser,
+  copyViaOsc52,
   copyToClipboard
 } from './social-git.js';
 

package/cli/index.js

@@ -154,10 +154,14 @@ export const runAudit = async (customDir = null, isCli = false) => {
 
     if (hasFailingViolations && (isPromptOnFail || isCopyPrompt)) {
       const prompt = buildMasterPrompt(report);
-      const copied = copyToClipboard(prompt);
-      if (copied) {
-        process.stdout.write('\n\x1b[1m\x1b[32m✔ AI Agent refactoring prompt copied to clipboard!\x1b[0m\n');
-        process.stdout.write('\x1b[36mPaste directly into Cursor, Claude, or Windsurf to resolve architectural hazards.\x1b[0m\n\n');
+      if (prompt) {
+        const copied = copyToClipboard(prompt);
+        if (copied) {
+          process.stdout.write('\n\x1b[1m\x1b[32m✔ AI Agent refactoring prompt copied to clipboard!\x1b[0m\n');
+          process.stdout.write('\x1b[36mPaste directly into Cursor, Claude, or Windsurf to resolve architectural hazards.\x1b[0m\n\n');
+        } else if (isCopyPrompt) {
+          process.stdout.write('\n\x1b[33m⚠ Could not access system clipboard.\x1b[0m\n\n');
+        }
       }
     }
 
@@ -185,9 +189,11 @@ const main = async () => {
     case 'wrap':
       await runBuildAudit(rawArgs.slice(1), true);
       break;
-    case 'audit':
-      await runAudit(null, true);
+    case 'audit': {
+      const posDir = (rawArgs[1] && !rawArgs[1].startsWith('-')) ? rawArgs[1] : null;
+      await runAudit(posDir, true);
       break;
+    }
     case 'init':
       await runInit(rawArgs[1] || 'src/chemical-x', rawArgs, runAudit);
       break;

package/cli/navigator-actions.js

@@ -86,10 +86,9 @@ export const buildActiveGrades = (report) => {
     const riskWeight = resolvePillarRiskWeight(data);
     const icon = PILLAR_EMOJIS[pillarName] || '🏛️';
     const shortName = PILLAR_SHORT_NAMES[pillarName] || pillarName;
-    const isClean = data.violations === 0;
-    const countLabel = isClean
-      ? '0 items'
-      : `${data.violations} ${data.violations === 1 ? 'item' : 'items'}`;
+    const count = data.violations || 0;
+    const paddedCount = String(count).padStart(2, '0');
+    const countLabel = `(${paddedCount} Items)`;
 
     const handlePillarAction = async () => {
       await showPagedContent(
@@ -104,10 +103,10 @@ export const buildActiveGrades = (report) => {
       shortName,
       grade,
       riskWeight,
-      violations: data.violations || 0,
+      violations: count,
       originalIndex: index,
       tag: resolveGradeBadge(grade, 11),
-      label: `${icon} ${pillarName} (${countLabel})`,
+      label: `${countLabel} ${icon} ${pillarName}`,
       action: handlePillarAction
     });
   });
@@ -117,10 +116,8 @@ export const buildActiveGrades = (report) => {
     const slopGrade = aiSlop.grade || (slopViolations.length > 0 ? 'D' : 'A+');
     const slopRiskWeight = resolvePillarRiskWeight(aiSlop.breakdown);
     const slopCount = slopViolations.length;
-    const isSlopClean = slopCount === 0;
-    const slopCountLabel = isSlopClean
-      ? '0 items'
-      : `${slopCount} ${slopCount === 1 ? 'item' : 'items'}`;
+    const paddedSlopCount = String(slopCount).padStart(2, '0');
+    const slopCountLabel = `(${paddedSlopCount} Items)`;
 
     const handleSlopAction = async () => {
       await showPagedContent(formatAiSlopSection(report), buildAiSlopPrompt(report));
@@ -135,7 +132,7 @@ export const buildActiveGrades = (report) => {
       violations: slopCount,
       originalIndex: pillarEntries.length,
       tag: resolveGradeBadge(slopGrade, 11),
-      label: `🤖 AI Slop & Authenticity (${aiSlop.score ?? 100}/100 - ${aiSlop.label ?? 'Pure Artisanal'}) (${slopCountLabel})`,
+      label: `${slopCountLabel} 🤖 AI Slop & Authenticity (${aiSlop.score ?? 100}/100 - ${aiSlop.label ?? 'Pure Artisanal'})`,
       action: handleSlopAction
     });
   }
@@ -251,10 +248,11 @@ export const buildDashboardActionGroups = ({ report, onScaffold = null, onRerun
   const handleExitAction = async () => {};
 
   const monolithHotspots = (report?.hotspots || []).filter((h) => h.isMonolith || h.lineCount > 500);
+  const monoCount = String(monolithHotspots.length).padStart(2, '0');
   const hotspotsAction = {
     key: "hotspots",
     tag: formatButtonTag("Hotspots", "\x1b[38;5;208m"),
-    label: `🔥 Top Refactoring Hotspots & Monoliths (${monolithHotspots.length} files)`,
+    label: `🔥 Top Refactoring Hotspots & Monoliths (${monoCount} Files)`,
     action: handleHotspotsAction
   };
 

package/cli/terminal.js

@@ -6,11 +6,11 @@ export const openBrowser = (url) => {
   const platform = process.platform;
   try {
     if (platform === "darwin") {
-      spawnSync("open", [url], { stdio: "ignore" });
+      spawnSync("open", [url], { stdio: "ignore", timeout: 3000 });
     } else if (platform === "win32") {
-      spawnSync("cmd.exe", ["/c", "start", '""', url], { stdio: "ignore" });
+      spawnSync("cmd.exe", ["/c", "start", '""', url], { stdio: "ignore", timeout: 3000 });
     } else {
-      spawnSync("xdg-open", [url], { stdio: "ignore" });
+      spawnSync("xdg-open", [url], { stdio: "ignore", timeout: 3000 });
     }
   } catch (err) {
     const error = err instanceof Error ? err : new Error(String(err));

package/docs/CHANGELOG.md

@@ -10,6 +10,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **Gatekeeper SaaS & Sponsor Verification**: Integrated client license validation in `cli/license.js` with `Xophz Gatekeeper` (`/wp-json/compass/v1/gatekeeper/licenses/validate`), allowing verification of both license keys (`CX-ST-`, `CX-SP-`) and GitHub Sponsor handles.
 - **Community Edition Flow**: Added reciprocal free Community Edition scaffolding in `cli/scaffold.js` allowing developers to unpack blueprints locally while sharing scorecards with community GitHub Discussions.
 - **Local Blueprint Fallback**: Added `loadLocalBlueprintFiles` in `cli/license.js` enabling offline and community blueprint scaffolding without remote edge download dependencies.
+- **Co-located Social-Git Test Suite**: Added test suite (`cli/audit/social-git.spec.js`) covering clipboard copying, OSC 52 escape sequences, and remote Git repository parsing.
+
+### Fixed
+- **Zero-Hang Clipboard Copying**: Resolved indefinite process hangs during prompt copying in `cli/audit/social-git.js` by adding default timeouts (`timeout: 1000`) to `safeSpawnSync`, preventing child processes from blocking the Node event loop.
+- **ANSI OSC 52 Universal Clipboard Support**: Added `copyViaOsc52` in `cli/audit/social-git.js`, enabling instant, zero-hang prompt copying directly to system clipboards via ANSI OSC 52 sequences across modern terminal emulators (ChromeOS Terminal, iTerm2, Alacritty, Kitty, WezTerm, VS Code, Windows Terminal, tmux).
+- **ChromeOS Sommelier & Wayland Protection**: Added Sommelier container detection in `cli/audit/social-git.js` to avoid `wl-copy` window focus deadlocks, alongside timeouts for `wl-copy`, `xclip`, `xsel`, and WSL `clip.exe`.
+- **Positional Audit Directory Arguments**: Updated `cli/index.js` to accept positional directory paths for `chemx audit <dir>` and added empty prompt guard clause to skip clipboard writes on pristine Grade A+ codebases.
+- **Browser Launch Timeout**: Added explicit timeout guard (`timeout: 3000`) to `openBrowser` in `cli/terminal.js`.
+
+### Changed
+- **Menu Alignment & Double-Padded Item Counts**: Reordered grade menu options in `cli/navigator-actions.js` to place double-padded count tags `(## Items)` directly following `[ Grade: X  ]` badges, ensuring pixel-perfect column alignment across all architectural pillar categories and hotspot files.
 
 ## [2026-09-12]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemx/starter-kit",
-  "version": "26.9.13-383",
+  "version": "26.9.14-205",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {
@@ -25,6 +25,7 @@
   },
   "scripts": {
     "publish:both": "node scripts/publish-both.mjs",
+    "test": "node --test cli/audit/*.spec.js",
     "typecheck": "tsc --noEmit",
     "create-capsule": "node cli/index.js",
     "audit": "node cli/index.js audit"