Node.js CLI best-practices audit: vendor skill + non-breaking fixes

[Paveltarno]

Note

Description

This PR hardens the CLI's error-handling, telemetry, and startup behavior. It adds a pre-filled GitHub bug-report link plus the CLI version and error code to unexpected error output, redacts secret values from telemetry, shows a one-time telemetry notice with opt-out instructions, and fixes several robustness issues around unsupported Node.js versions, signal handling, shell usage, and stale asset cleanup.

Related Issue

None

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• Bug report link: On unexpected (non-user) errors, the CLI now prints a GitHub new-issue URL pre-filled with the error message, code, CLI version, command, and environment details (`bug-report.ts`), in both themed and plain-text error output.
• Version & error code in errors: Error output now includes `base44 v` and the error `Code:` (`theme.ts`, `render.ts`).
• Telemetry redaction: `KEY=VALUE` positional args (e.g. `secrets set`) have their values redacted, and request/response bodies for `/secrets` endpoints are dropped before being attached to error reports (`redact.ts`, `commander-hooks.ts`, `error-reporter.ts`).
• First-run telemetry notice: A one-time notice explains what error telemetry is collected and how to opt out via `BASE44_DISABLE_TELEMETRY=1`, recorded with a marker file (`first-run-notice.ts`, `config.ts`).
• Unsupported Node.js handling: `bin/run.js` now avoids syntax newer than Node 12, checks `engines.node` before loading the bundle, and fails with a clear upgrade message instead of a `SyntaxError`.
• Signal handling: The dev server now also handles `SIGHUP` so closing the terminal tears down child processes cleanly.
• Shell usage: Dropped `shell: true` from fixed-argument `execa` calls (`npm view`, `npx skills`) to remove injection surface.
• Stale asset cleanup: Old `~/.base44/assets/` directories are pruned on first run of a new version.
• Docs & changelog: Added telemetry docs, README notes, backfilled the changelog, and vendored the `nodejs-cli-best-practices` agent skill.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (`npm test`)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated `docs/` (AGENTS.md) if I made architectural changes

Additional Notes

New unit tests cover telemetry redaction (`tests/core/telemetry-redact.spec.ts`), and `exec` command assertions were updated for the new error output. All telemetry/UX helpers are best-effort and never throw, so they cannot break the CLI.

---

_{🤖 Generated by Claude | 2026-07-02 20:27 UTC | 40ca32e}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.1-pr.556.40ca32e

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.1.1-pr.556.40ca32e"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.1-pr.556.40ca32e"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.1-pr.556.40ca32e
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}