squad-conventions

Cross-platform filesystem paths in Node.js CLI tools should be handled using path.join() to ensure Windows, macOS, and Linux compatibility. This approach prevents errors from inconsistent directory separators, maintaining safe and predictable filesystem operations across operating systems.

Testing Node.js CLI applications without external dependencies is best achieved using Node's built-in test runner, node:test, alongside strict assertions. This standardizes test authoring and execution while maintaining a minimal, deterministic zero-dependency npm package environment.

To display clean CLI errors without raw stack traces, implement a fatal(msg) error handling pattern. This method outputs user-facing failure messages directly, hiding internal stack traces and providing a predictable, safe terminal experience during execution failures.

Safe init and upgrade logic for a Node.js CLI tool requires idempotent initialization that skips existing files, while restricting overwrites to CLI-owned files during upgrades. This respects user-owned state and prevents accidental data loss across sessions.

Node.js CLI tools need zero runtime npm dependencies to keep the package minimal and deterministic. Relying strictly on Node built-ins prevents version conflicts, reduces installation overhead, and ensures consistent behavior across different execution environments.