@chemx/starter-kit 26.9.9-786 → 26.9.11-481

package/docs/CHANGELOG.md

@@ -16,6 +16,107 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - `useSelfCleaningTimer`: unmount-safe interval and timeout utilities
 - Interactive CLI capsule generator (`cli/index.js`).
 
+## [2026-09-11]
+
+### Changed
+- Conditioned `[  Prompt   ] 📋 Copy AI Prompt Fix to Clipboard` dashboard action to hide when the codebase earns a pristine Grade A+ with no pending refactoring prompt (`cli/navigator.js`, `cli/navigator-actions.js`).
+- Added early-return guard clause to `handleCopyPromptAction` preventing empty clipboard copy operations on pristine Grade A+ audits (`cli/navigator-actions.js`).
+
+### Fixed
+- Fixed typographical artifact (`and p`) in the interactive audit publication confirmation prompt across navigator and terminal handlers (`cli/navigator.js`, `cli/terminal.js`).
+
+## [2026-09-10]
+
+### Changed
+- Decomposed warning monolith `cli/navigator.js` (515 lines to 123 lines) by extracting single-responsibility capsules: `cli/navigator-banner.js` (84 lines: Gamer HUD terminal rendering), `cli/navigator-menu.js` (115 lines: button tags, menu assembly, selection matching), and `cli/navigator-actions.js` (165 lines: grade drill-downs and dashboard actions), preserving all public exports and type declarations.
+- Extracted anonymous inline callbacks into named functions across navigator modules adhering to Chemical X code syntax standards.
+- Replaced all abbreviated `LOC` acronym references across dashboard banners, reports, Markdown exports, and refactoring prompts with fully spelled-out `lines of code` (`cli/navigator.js`, `cli/audit/reporter.js`, `cli/audit/reporter-grades.js`, `cli/audit/reporter-utils.js`, `cli/audit/reporter-markdown.js`, `cli/audit/prompts.js`, `cli/audit/social.js`, `cli/audit/history.js`, `cli/help.js`).
+- Reordered interactive Audit Navigator dashboard menu (`cli/navigator.js`) into four distinct operational sections separated by clean dividers: top actions (`[  Install  ]`, `[  Upgrade  ]`, `[Full Report]`), grade drill-downs (`[ Grade: A  ]`), community and metrics actions (`[   Share   ]`, `[ Progress  ]`, `[  Export   ]`), and footer actions (`[  Prompt   ]`, `[   Exit    ]`).
+- Conditioned `[  Install  ]` action to display only when git pre-commit hooks and GitHub Actions CI workflow are not already installed (`areGuardrailsInstalled` in `cli/installer.js`, `cli/navigator.js`).
+- Centered button bracket text across all dashboard actions and grade tags for uniform 13-character button width and column alignment (`formatButtonTag` in `cli/navigator.js`, `resolveGradeBadge` in `cli/navigator-grades.js`).
+- Renamed prompt copy menu item to `[  Prompt   ] 📋 Copy AI Prompt Fix to Clipboard` (`cli/navigator.js`).
+- Renamed full report menu button to `[Full Report]` and share option label to plug website and post to GitHub Discussions (`cli/navigator.js`).
+- Aligned terminal output columns across `METRIC COMPARISON TABLE` and `7-PILLAR PROGRESSION` in `formatTransformationTerminal` (`cli/audit/history.js`), expanding pillar and metric padding to 40 characters with uniform divider widths.
+
+### Added
+- Integrated real-time Token Estimate (`-TOKEN EST-`) and Currency Cost (`-CURRENCY-`) metrics into Gamer HUD (`cli/navigator-banner.js`, `cli/navigator.js`).
+- Embedded project name in top rounded border and project working directory (`pwd`) in bottom rounded border of Gamer HUD (`cli/navigator-banner.js`).
+- Swapped Gamer HUD column positions in `renderDashboardBanner` (`cli/navigator-banner.js`): `-FILES-` and `-LINES OF CODE-` on the left column, and `-HEALTH-` and `-HAZARDS-` on the right column.
+- Hazard emojis (💥 for Critical, 🔥 for High/Med, 💣 for Low) in `-HAZARDS-` HUD status row (`cli/navigator-banner.js`) and interactive grade drilldown actions (`cli/navigator-actions.js`).
+- Gamer HUD with 2-column layout in `renderDashboardBanner` (`cli/navigator.js`) grouping `-HEALTH-` and `-HAZARDS-` on the left and `-FILES-` and `-LINES OF CODE-` on the right, removing HUD title banner and quote text.
+- Heart emoji container display (`❤️❤️❤️❤️❤️` to `🖤🖤🖤🖤🖤`) in `resolveHealthHearts` (`cli/navigator-grades.js`).
+- Compact `X = [Grade]` ASCII art banner in `getChemicalXAsciiBanner` (`cli/audit/reporter.js`, `cli/audit/reporter-ascii.js`) removing the redundant `GRADE` text and linking Chemical X with bold ASCII `=` and dynamic letter grade typography (`A+`, `A`, `B`, etc.).
+- Four-line compact block `REPORT CARD` ASCII art banner (`REPORT_CARD_ASCII` in `cli/audit/reporter-ascii.js`) added to the top of all grade report card sections (`formatGradeASection`, `formatGradeBSection`, `formatGradeCSection`, `formatGradeDSection`, `formatGradeFSection`) and the audit scorecard overview (`formatScorecardSection`).
+- Free, standalone POSIX git pre-commit hook script (`scripts/pre-commit.sh`) enforcing 500-line file budgets, 100-line molecule capsule limits, and configurable minimum grade/score thresholds with automatic AI refactoring prompt clipboard copying.
+- Production GitHub Actions CI workflow blueprint (`blueprints/workflows/chemx-audit.yml`) executing architectural audits with configurable grade thresholds and artifact uploads.
+- Modular CLI installer capsule (`cli/installer.js`, `cli/installer.d.ts`) enabling interactive Gum and ANSI installation of pre-commit hooks, GitHub workflows, and `.chemx/config.json` project configurations.
+- Dedicated `[Install  ] 🪝 Install Pre-Commit Hook & GitHub CI Workflow` action in the interactive Audit Navigator dashboard (`cli/navigator.js`).
+- Standalone CLI subcommands `hook`, `hooks`, `install-hooks`, and `setup-ci` in `cli/index.js` for direct non-interactive setup.
+- Token financial telemetry engine in `cli/audit/metrics.js` translating context bloat into real-world dollar waste per AI prompt turn, weekly developer waste, and monthly team context tax based on configurable model baselines (`--model=claude|gpt4o|blended` or custom rate).
+- Financial metrics reporting in terminal reports (`formatContextAnalysisSection` in `cli/audit/reporter.js`), Markdown reports (`cli/audit/reporter-markdown.js`), and published GitHub Discussion reports (`generateDiscussionContent` and `generateTransformationDiscussionContent` in `cli/audit/social.js`).
+- Flexible audit threshold flags: `--min-grade`, `--min-score`, `--prompt-on-fail`, and `--copy-prompt`.
+- Hybrid GitHub Sponsors licensing CTAs in `cli/navigator-conversion.js` and `cli/license.js` spotlighting $9/mo solo and $49/mo team unlimited sponsorship.
+- Robust 7-pillar Quantum Engineering Architecture static analysis rule engine (`cli/audit/rules.js`) covering line budgets, control flow booleans, nested ternaries, hook saturation and return budgets, timer disposal, render-hack timeouts, type co-location, type monoliths, mock data patterns, inline styles, icon SVG leaks, and typography hygiene.
+- Full architectural metrics and scoring engine (`cli/audit/metrics.js`) computing Quantum Health Index (QHI: 0 to 100 score with A+ to F letter grades), codebase LOC distribution, molecule capsule compliance rate, and context token burn risk.
+- Multi-format audit reporter (`cli/audit/reporter.js`) supporting rich ANSI terminal scorecards, GitHub-flavored Markdown reports (`--markdown`), and structured JSON (`--json`).
+- Severity-grouped hazard categorization (`groupViolationsBySeverity`) isolating Critical Hazards (immediate action required), High & Medium Hazards (architecture debts), and Low Hygiene Issues (typography & logging).
+- Interactive Gum Audit Dashboard Navigator (`cli/index.js`) providing a zero-scroll terminal interface with drill-down line items into scorecards, critical hazards, high/medium debts, hygiene issues, 7 pillars, hotspots, and token analytics.
+- Integrated `gum pager` for terminal scrolling of full unrolled reports.
+- Sliding scale monolith detection system (`cli/audit/rules.js`) classifying files into three calibrated tiers: Warning / Medium (500 to 999 lines), Severe / High (1,000 to 1,999 lines), and Extreme / Critical (2,000+ lines), providing fair and balanced health scoring for existing codebases.
+- Priority-ranked refactoring hotspot leaderboard ranking files by hazard density and line budget overflow.
+- Vibrant 24-bit RGB gradient ASCII art banner (`getChemicalXAsciiBanner` in `cli/audit/reporter.js`) featuring "Chemical X" slant lettering styled with Pink -> Magenta -> Lavender color transitions, accompanied by the motto "The Secret Sauce to Vibe Coding" and the directive "Strict Quantum Engineering Standards for AI Agents to follow."
+- Social audit sharing module (`cli/audit/social.js`) enabling developers to publish audit reports to GitHub Discussions under the `npx chemx audit` category (`https://github.com/orgs/Chemical-X-Protocol/discussions`), with automated GitHub CLI (`gh`) publishing and cross-platform clipboard/browser fallback.
+- Local audit persistence and telemetry history module (`cli/audit/history.js`), persisting up to 50 audit snapshots to `.chemx/history.json` and establishing/tracking `.chemx/baseline.json`.
+- Automatic `.chemx/` directory provisioning and `.gitignore` registration to prevent accidental commit of local audit history.
+- Architectural delta calculation engine (`calculateTransformationDelta`) computing MHI score deltas, critical hazard reductions, monolith decompositions, token burn savings, and 7-pillar status progressions between baseline and refactored states.
+- Terminal transformation formatters (`formatTransformationTerminal` and `formatHistoryTimelineTerminal`) rendering side-by-side Before & After delta tables and audit timeline records.
+- Dedicated `[Progress ] 📈 View Before & After Transformation Progress` interactive dashboard action in `cli/navigator.js`.
+- Dual discussion sharing mode in `handleShareToDiscussions`: prompts developers to post either a Before & After Transformation Showcase (`generateTransformationDiscussionContent`) or a Single Audit Scorecard (`generateDiscussionContent`).
+- Privacy-safe GitHub Discussion publishing: all discussion templates strictly omit private file paths and repository code, displaying aggregate metrics, monolith counts, and 7-pillar progression badges (`🟢 RESOLVED`, `⚪ UNCHANGED`, `🔴 DEGRADED`).
+- CLI flags `--markdown`, `--md`, `--output=<file>`, `--unroll`, `--share`, and `--strict` for `npx chemx audit`.
+- Local `"audit"` script in `package.json` for running audits directly via `npm run audit`.
+- Automated AI Agent refactoring prompt generator module (`cli/audit/prompts.js`) synthesizing tailored, copy-pasteable prompts for each audit section and grade tier (Grade F Critical, Grade D Debts, Grade C Style/Handlers, Grade B Hygiene, Master Phased Prompt), embedded directly into terminal views, Markdown reports, and GitHub Discussions.
+- 1-Click Clipboard prompt copying in interactive report views: added automatic prompt detection and extraction (`extractPromptFromContent`) with a dedicated `📋 Copy AI Agent Prompt to Clipboard` action in `showPagedContent` for Gum and standard terminal environments.
+- Automatic git repository and owner detection (`detectGitRepoInfo`, `parseGitRemoteUrl` in `cli/audit/social.js`), resolving `owner/repo` (e.g. `Chemical-X-Protocol/starter-kit`) for discussion post titles, headers, and canonical repository URLs, while keeping auditor username detection strictly bound to the developer's personal GitHub account.
+- Pre-menu Gum confirmation button (`gumConfirm` and `confirmAction` in `cli/terminal.js` and `cli/navigator.js`) defaulting to asking whether developers would like to publish their audit report to GitHub Discussions immediately following report and ASCII banner presentation, prior to presenting the dashboard navigation menu.
+- Persistent discussion topic reuse and comment archival engine (`cli/audit/discussion-store.js` and `publishOrUpdateDiscussion` in `cli/audit/social-publisher.js`): tracks active discussion topics per project in `.chemx/discussion.json`; when posting an updated report, archives the prior report by posting it as a snapshot comment to the discussion thread and updates the primary discussion topic with the latest report.
+- Live deployment and project website URL publishing (`cli/navigator-share.js`, `cli/audit/social.js`): prompts developers for an optional project/website URL (auto-detected from `package.json` homepage or cached `.chemx/discussion.json`) and embeds it as a normalized, clickable markdown hyperlink (`[https://...](https://...)`) into published GitHub Discussion audit reports and transformation showcases.
+- Non-blocking evaluation mode ("nagware" reminder) for molecule capsule generation and scaffolding commands (`checkOrPromptEvaluation` in `cli/license.js` and `cli/scaffold.js`): provides an instant default-Enter bypass for unlicensed developers to evaluate code generation while displaying reminder banners to purchase a license.
+- Comprehensive CLI help and usage manual capsule (`cli/help.js`): provides an exhaustive `--help` reference covering all commands (`audit`, `generate`, `init`, `create`), all audit options (`--dir`, `--json`, `--markdown`, `--output`, `--unroll`, `--share`, `--strict`, `--license`), environment variables (`GH_TOKEN`, `CHEMICAL_X_API_URL`), and copy-pasteable examples.
+
+### Changed
+- Codified the Anti-Tailwind-Soup Directive into Pillar 5 across agent directives (`AGENTS.md`) and static audit rules registry (`cli/audit/rules-registry.js`): restricts inline utility chains to 4-5 classes maximum, prohibiting monolithic Tailwind class soup in templates and mandating visual decoupling into Level 1 atom props, Level 2 mixins, or Level 3 scoped classes utilizing `@apply`.
+- Updated ASCII banner subtitle in `cli/audit/reporter.js` to "Architectural guardrails to eliminate token burn and AI hallucinations" with dynamic column centering.
+- Updated default GitHub Discussions category to `npx chemx audit` in `cli/audit/social.js` with expanded case-insensitive and fallback resolution.
+- Modularized starter kit audit engine under `cli/audit/` while maintaining 100% backward compatibility with `cli/audit.js` and `./audit` subpath export.
+- Enhanced TypeScript type definitions in `cli/audit.d.ts` and `cli/audit/types.d.ts` for full typing across all metrics, pillars, and options.
+- Refactored internal audit code to eliminate nested ternaries in compliance with Quantum Engineering standards.
+- Streamlined interactive Gum Audit Navigator into consolidated Pass, Fail, and Full Report options (`Show Full Report`, `View Failed & Degraded Checks`, `View Passed & Compliant Checks`, and `View Scorecard`), eliminating the need to click through 7 separate sub-menus.
+- Reorganized audit navigator menu into an action-first and grade-tiered layout (Report, Share, Export, Upgrade, Grade F to A, Exit) with dynamic grade links that only appear if corresponding checks/hazards exist in the codebase.
+- Added dedicated grade section formatters (`formatGradeFSection`, `formatGradeDSection`, `formatGradeCSection`, `formatGradeBSection`, `formatGradeASection`) in `cli/audit/reporter.js` with individual exports and type definitions.
+- Rebranded terminology across the starter kit CLI, metrics, reporter, types, prompts, and social publisher from "Quantum Engineering" to "Chemical X Molecular Architecture Standards", replacing ambiguous buzzwords with grounded atomic and molecular architectural definitions.
+- Renamed `calculateQuantumHealthScore` to `calculateMolecularHealthScore` (Molecular Health Index / MHI) with backward-compatible aliases.
+- Updated ASCII art banner in `cli/audit/reporter.js` to block font lettering with 24-bit TrueColor gradient and centered alignment.
+- Updated CLI dashboard upgrade action label and conversion menu to `💎 Unlock Full Molecular Rules & Scaffolding (Chemical X: Team Power Puff)` with streamlined Single Developer License ($27) and Team Power Puff 100 seats Team Honor System licensing ($47: `Power Puff Team 💯`).
+- Refined terminal report color hierarchy: Critical hazards render in RED, High and Medium debts in ORANGE, and Low hygiene issues in YELLOW; top analytical overview, matrix, and hotspot sections dynamically illuminate in GREEN when 100% compliant and zero hazards remain.
+- Integrated codebase health grade directly into ASCII banner art: dynamically appends `= Grade <tier>` (e.g. `X = Grade A+`) at the center intersection of the ASCII `X` above the audit dashboard menu and within full terminal reports.
+### Fixed
+- Fixed discussion category recognition error by setting `DEFAULT_DISCUSSION_REPO` to `Chemical-X-Protocol/.github` and using category slug `npx-chemx-audit` in browser URLs.
+- Resolved `unable to read stdin` crash during report inspection by removing piped child process pager calls and directly streaming styled report output with interactive back-to-dashboard navigation.
+- Added automatic terminal screen clearing (`console.clear()`) between menu navigations and report inspections, eliminating duplicate banners and artifact stacking.
+- Executed phased Chemical X Molecular Architecture refactoring eliminating Grade F, Grade D, and Grade C hazards:
+  - Surgically refactored `blueprints/molecule-capsule/m-sample-card.tsx` to eliminate nested ternaries via `resolveBadgeDescriptor` computed descriptor and removed all 8 raw inline styles in favor of scoped BEM stylesheet `_m-sample-card.scss`.
+  - Refactored `blueprints/view-template.tsx` to eliminate raw inline styles via `_view-template.scss` while preserving a 21-line declarative Table-of-Contents template.
+  - Decomposed 1,070-line severe monolith `cli/index.js` into isolated single-responsibility domain capsules: `cli/terminal.js` (77 LOC), `cli/license.js` (188 LOC), `cli/scaffold.js` (167 LOC), `cli/navigator.js` (379 LOC), and lean orchestrator `cli/index.js` (134 LOC), preserving all public exports without breaking changes.
+  - Decomposed warning monolith `cli/audit/reporter.js` (831 LOC to 352 LOC) by extracting `cli/audit/reporter-utils.js` (88 LOC), `cli/audit/reporter-markdown.js` (122 LOC), and `cli/audit/reporter-grades.js` (243 LOC) with 100% backward-compatible re-exports.
+  - Decomposed warning monolith `cli/audit/rules.js` (554 LOC to 118 LOC) by extracting `cli/audit/rules-registry.js` (102 LOC), `cli/audit/rules-helpers.js` (109 LOC), and `cli/audit/ast-visitors.js` (230 LOC).
+  - Enhanced published and exported audit reports in `cli/audit/social.js` and `cli/audit/reporter-markdown.js`: added pillar icons and colored status/hazard emojis (`🟢`, `🟡`, `🔴`) to the 7-Pillar Architectural Matrix, replaced `#1`/`#2` priority tags with number emojis (`1️⃣`, `2️⃣`, `3️⃣`, etc.) to prevent GitHub Discussions auto-linking conflicts, and styled monolith tiers with severity indicator circles.
+  - Fixed Grade F critical AST nested ternary violations in `cli/audit/history.js` (`resolvePillarDeltaArrow` and `resolveScoreGradeColor`) and `cli/audit/social.js` (`resolvePillarProgressionBadge`).
+  - Decomposed warning monolith `cli/audit/social.js` (572 LOC to 221 LOC) by extracting `cli/audit/social-git.js` (214 LOC) and `cli/audit/social-publisher.js` (188 LOC) while preserving all public exports.
+  - Decomposed warning monolith `cli/navigator.js` (666 LOC to 343 LOC) by extracting focused sub-100 LOC capsules: `cli/navigator-grades.js` (70 LOC), `cli/navigator-paged.js` (86 LOC), `cli/navigator-conversion.js` (87 LOC), and `cli/navigator-share.js` (98 LOC) with full backward compatibility.
+  - Extracted anonymous inline callbacks into named functions across audit persistence and dashboard navigator modules.
+  - Co-located granular TypeScript definitions in `cli/audit/history.d.ts`, `cli/audit/social.d.ts`, and `cli/navigator.d.ts`, eliminating monolithic type hazards.
+
 ## [2026-09-09]
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemx/starter-kit",
-  "version": "26.9.9-786",
+  "version": "26.9.11-481",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {
@@ -25,20 +25,21 @@
   "scripts": {
     "publish:both": "node scripts/publish-both.mjs",
     "typecheck": "tsc --noEmit",
-    "create-capsule": "node cli/index.js"
+    "create-capsule": "node cli/index.js",
+    "audit": "node cli/index.js audit"
   },
   "dependencies": {
-    "@babel/parser": "^7.26.9",
-    "@babel/traverse": "^7.26.9",
-    "@babel/types": "^7.26.9",
+    "@babel/parser": "^7.29.8",
+    "@babel/traverse": "^7.29.8",
+    "@babel/types": "^7.29.8",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "@types/babel__traverse": "^7.20.6",
-    "@types/node": "^22.13.5",
-    "@types/react": "^18.3.18",
-    "@types/react-dom": "^18.3.5",
-    "typescript": "^5.7.3"
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^22.20.2",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "typescript": "^5.9.3"
   }
 }