@programinglive/commiter 1.2.6 → 1.2.12

package/PRD.md

@@ -1,91 +1,96 @@
-# Commiter Product Requirements Document (PRD)
-
-## 1. Overview
-Commiter is a CLI utility that bootstraps and automates conventional release workflows for JavaScript/TypeScript projects. It enforces commit conventions, orchestrates semantic version bumps, keeps release tooling configured, and surfaces feedback during release execution so teams can ship confidently.
-
-## 2. Problem Statement
-Growing teams often struggle to keep release processes consistent: commit messages drift from convention, changelogs become stale, and release scripts accumulate manual steps. Commiter removes this friction by installing opinionated tooling, providing curated scripts, and running guard rails (tests, linters) before invoking `standard-version` to publish a release.
-
-## 3. Goals & Success Metrics
-- **Consistent releases**: Every release run through Commiter formats commits, updates changelogs, tags, and version bumps without manual editing.
-- **Low ceremony onboarding**: A single `npx commiter` command prepares repositories (Husky, commitlint, release scripts).
-- **Signal-rich automation**: Release logs clearly show which steps ran, including any warnings (e.g., tests skipped). Zero noisy deprecation warnings.
-- **Reliability**: New releases do not regress existing behavior; the automated test suite passes (`node --test`).
-- **Adoption Metric**: Track installations (npm downloads) and successful release script exits.
-
-## 4. Personas
-1. **Solo Maintainer** – wants painless semantic releases without memorizing commands.
-2. **Team Lead** – enforces commit standards across contributors and ensures releases produce accurate changelogs.
-3. **DevOps/CI Engineer** – integrates Commiter’s release command into CI pipelines and expects deterministic, machine-readable output.
-
-## 5. Key Features
-- **Setup CLI (`index.js`)**
-  - Installs dev dependencies (`standard-version`, `commitlint`, `husky`).
-  - Configures package scripts (`npm run release`, `release:major/minor/patch`).
-  - Creates Husky hooks and commitlint configuration.
-  - Generates release helper script and ensures executable permissions (POSIX-friendly).
-- **Release Helper (`scripts/release.js`)**
-  - Detects release type from CLI args or npm context.
-  - Runs project tests via detected package manager before releasing.
-  - Invokes `standard-version` with additional flags (e.g., preload patch for deprecated APIs).
-  - **[NEW]** Automatically updates website version in `web/index.html`.
-- **Preload Patching (`scripts/preload/fs-f-ok.cjs`)**
-  - Hooks Node’s module loader to transparently replace deprecated `fs.F_OK` usages in `standard-version` without altering `node_modules`.
-- **Website & Documentation**
-  - Professional landing page in `web/` directory.
-  - Automated GitHub Releases generation.
-  - Open Graph social media preview support.
-- **Testing**
-  - Suite executed via `node --test` covers setup utilities, release argument parsing, and the preload patch.
-
-## 6. Functional Requirements
-1. Running `npx @programinglive/commiter` inside a Node project should configure release tooling without manual edits.
-2. `npm run release` must:
-   - Run the project’s tests (if defined) with the correct package manager.
-   - Execute `standard-version`, passing the preload script via `NODE_OPTIONS`.
-   - Exit with non-zero status if tests or standard-version commands fail.
-3. CLI should provide friendly console output (status icons, instructions).
-4. The preload script must eliminate `[DEP0176] fs.F_OK` warnings on supported Node versions.
-5. Documentation (README, PRD, release notes) remains shipped with the package.
-
-## 7. Non-Functional Requirements
-- **Compatibility**: Supports Node.js 18+ (aligning with dependencies); tested on Windows/macOS/Linux.
-- **Maintainability**: Avoid direct edits to dependencies; wrap behavior in Commiter-controlled modules.
-- **Performance**: Release command overhead minimal (<1s additional startup time) beyond running tests and standard-version.
-- **Security**: No network requests during CLI execution beyond npm installs triggered by the user.
-
-## 8. User Journeys
-1. **Initial Setup**
-   - Run `npx @programinglive/commiter`.
-   - Tool installs dependencies, updates `package.json`, and scaffolds Husky hooks.
-   - Maintainer confirms success message and new scripts.
-2. **Standard Release**
-   - Developer runs `npm run release minor`.
-   - Commiter runs tests, ensures preload patch prevents deprecation warnings, executes `standard-version`.
-   - Release completes with updated changelog and git tag.
-3. **CI Pipeline**
-   - CI job executes `npm run release -- --prerelease beta`.
-   - Logs show tests executed, no deprecation warnings, and release artifacts generated.
-
-## 9. Milestones & Roadmap
-- **v1.1.x** (current)
-  - Deprecation warning mitigation, enhanced tests, PRD + release documentation.
-- **Future Considerations**
-  - Support for monorepo detection (Lerna/Nx) to run scoped releases.
-  - Optional lint/test command customization via config file.
-  - Telemetry opt-in for release statistics (downloads, success rates).
-
-## 10. Risks & Mitigations
-- **Dependency API Changes**: Upstream packages may alter file paths. Mitigate with targeted module resolution and tests.
-- **User Customization Conflicts**: Custom scripts might skip tests. Provide documentation for overriding behavior.
-- **Platform Differences**: Windows path quoting; addressed via `buildPreloadFlag` helper.
-
-## 11. Release & QA Checklist
-- [x] `npm test` (alias for `node --test`) passes.
-- [x] Manual run of `node scripts/release.js --help` shows no `[DEP0176]` warning.
-- [ ] Update `CHANGELOG.md` (handled by standard-version during actual release).
-- [ ] Verify README reflects latest setup instructions before shipping.
-
-## 12. Appendices
-- **Release Notes**: See `docs/release-notes/` for per-change summaries.
-- **Testing Artifacts**: `test/` directory contains Node test runner suites.
+# Commiter Product Requirements Document (PRD)
+
+## 1. Overview
+Commiter is a CLI utility that bootstraps and automates conventional release workflows for JavaScript/TypeScript projects. It enforces commit conventions, orchestrates semantic version bumps, keeps release tooling configured, and surfaces feedback during release execution so teams can ship confidently.
+
+## 2. Problem Statement
+Growing teams often struggle to keep release processes consistent: commit messages drift from convention, changelogs become stale, and release scripts accumulate manual steps. Commiter removes this friction by installing opinionated tooling, providing curated scripts, and running guard rails (tests, linters) before invoking `standard-version` to publish a release.
+
+## 3. Goals & Success Metrics
+- **Consistent releases**: Every release run through Commiter formats commits, updates changelogs, tags, and version bumps without manual editing.
+- **Low ceremony onboarding**: A single `npx commiter` command prepares repositories (Husky, commitlint, release scripts).
+- **Signal-rich automation**: Release logs clearly show which steps ran, including any warnings (e.g., tests skipped). Zero noisy deprecation warnings.
+- **Reliability**: New releases do not regress existing behavior; the automated test suite passes (`node --test`).
+- **Adoption Metric**: Track installations (npm downloads) and successful release script exits.
+
+## 4. Personas
+1. **Solo Maintainer** – wants painless semantic releases without memorizing commands.
+2. **Team Lead** – enforces commit standards across contributors and ensures releases produce accurate changelogs.
+3. **DevOps/CI Engineer** – integrates Commiter’s release command into CI pipelines and expects deterministic, machine-readable output.
+
+## 5. Key Features
+- **Setup CLI (`index.js`)**
+  - Installs dev dependencies (`standard-version`, `commitlint`, `husky`).
+  - Configures package scripts (`npm run release`, `release:major/minor/patch`, `release:first`).
+  - Creates Husky hooks and commitlint configuration.
+  - Generates release helper script and ensures executable permissions (POSIX-friendly).
+- **Release Helper (`scripts/release.js`)**
+  - Detects release type from CLI args or npm context.
+  - Runs project tests via detected package manager before releasing.
+  - Invokes `standard-version`, passing the preload script via `NODE_OPTIONS`.
+  - Supports first release mode that sets version to 0.0.1 for new projects.
+  - Stays focused on repository assets only (website updates are intentionally manual to avoid cross-project impacts).
+- **Preload Patching (`scripts/preload/fs-f-ok.cjs`)**
+  - Hooks Node’s module loader to transparently replace deprecated `fs.F_OK` usages in `standard-version` without altering `node_modules`.
+- **Website & Documentation**
+  - Professional landing page in `web/` directory.
+  - Automated GitHub Releases generation.
+  - Open Graph social media preview support.
+- **Testing**
+  - Suite executed via `node --test` covers setup utilities, release argument parsing, and the preload patch.
+
+## 6. Functional Requirements
+1. Running `npx @programinglive/commiter` inside a Node project should configure release tooling without manual edits.
+2. `npm run release` must:
+   - Run the project’s tests (if defined) with the correct package manager.
+   - Execute `standard-version`, passing the preload script via `NODE_OPTIONS`.
+   - Exit with non-zero status if tests or standard-version commands fail.
+3. CLI should provide friendly console output (status icons, instructions).
+4. The preload script must eliminate `[DEP0176] fs.F_OK` warnings on supported Node versions.
+5. Documentation (README, PRD, release notes) remains shipped with the package.
+
+## 7. Non-Functional Requirements
+- **Compatibility**: Supports Node.js 18+ (aligning with dependencies); tested on Windows/macOS/Linux.
+- **Maintainability**: Avoid direct edits to dependencies; wrap behavior in Commiter-controlled modules.
+- **Performance**: Release command overhead minimal (<1s additional startup time) beyond running tests and standard-version.
+- **Security**: No network requests during CLI execution beyond npm installs triggered by the user.
+
+## 8. User Journeys
+1. **Initial Setup**
+   - Run `npx @programinglive/commiter`.
+   - Tool installs dependencies, updates `package.json`, and scaffolds Husky hooks.
+   - Maintainer confirms success message and new scripts.
+2. **First Release**
+   - Developer runs `npm run release:first` for new projects.
+   - Commiter sets version to 0.0.1, runs tests, creates initial changelog and git tag.
+   - Project foundation established with proper semantic versioning.
+3. **Standard Release**
+   - Developer runs `npm run release minor` or `npm run release` (defaults to patch).
+   - Commiter runs tests, ensures preload patch prevents deprecation warnings, executes `standard-version`.
+   - Release completes with updated changelog and git tag.
+4. **CI Pipeline**
+   - CI job executes `npm run release -- --prerelease beta`.
+   - Logs show tests executed, no deprecation warnings, and release artifacts generated.
+
+## 9. Milestones & Roadmap
+- **v1.1.x** (current)
+  - Deprecation warning mitigation, enhanced tests, PRD + release documentation.
+- **Future Considerations**
+  - Support for monorepo detection (Lerna/Nx) to run scoped releases.
+  - Optional lint/test command customization via config file.
+  - Telemetry opt-in for release statistics (downloads, success rates).
+
+## 10. Risks & Mitigations
+- **Dependency API Changes**: Upstream packages may alter file paths. Mitigate with targeted module resolution and tests.
+- **User Customization Conflicts**: Custom scripts might skip tests. Provide documentation for overriding behavior.
+- **Platform Differences**: Windows path quoting; addressed via `buildPreloadFlag` helper.
+
+## 11. Release & QA Checklist
+- [x] `npm test` (alias for `node --test`) passes.
+- [x] Manual run of `node scripts/release.js --help` shows no `[DEP0176]` warning.
+- [ ] Update `CHANGELOG.md` (handled by standard-version during actual release).
+- [ ] Verify README reflects latest setup instructions before shipping.
+
+## 12. Appendices
+- **Release Notes**: See `docs/release-notes/` for per-change summaries.
+- **Testing Artifacts**: `test/` directory contains Node test runner suites.

package/PUBLISH.md

@@ -1,142 +1,142 @@
-# Publishing to NPM
-
-This guide explains how to publish the `@programinglive/commiter` package to npm.
-
-## Prerequisites
-
-1. **NPM Account**: Create an account at [npmjs.com](https://www.npmjs.com/)
-2. **Login to NPM**: Run `npm login` in your terminal
-3. **Organization Access**: Ensure you have access to the `@programinglive` organization on npm
-
-## Publishing Steps
-
-### 1. Login to NPM
-
-```bash
-npm login
-```
-
-Enter your npm credentials when prompted.
-
-### 2. Verify Package Configuration
-
-Check that `package.json` is correctly configured:
-
-```bash
-npm pack --dry-run
-```
-
-This shows what files will be included in the package.
-
-### 3. Publish the Package
-
-For the first publish:
-
-```bash
-npm publish --access public
-```
-
-**Note**: The `--access public` flag is required for scoped packages (@programinglive/commiter) to be publicly accessible.
-
-### 4. Verify Publication
-
-Check your package on npm:
-```
-https://www.npmjs.com/package/@programinglive/commiter
-```
-
-## Releasing New Versions
-
-After the initial publish, use the built-in release commands:
-
-### Patch Release (1.0.0 → 1.0.1)
-```bash
-npm run release:patch
-git push --follow-tags origin main
-npm publish
-```
-
-### Minor Release (1.0.0 → 1.1.0)
-```bash
-npm run release:minor
-git push --follow-tags origin main
-npm publish
-```
-
-### Major Release (1.0.0 → 2.0.0)
-```bash
-npm run release:major
-git push --follow-tags origin main
-npm publish
-```
-
-## Automated Release Workflow
-
-### Option 1: Manual Publishing (Traditional)
-1. Make changes and commit using conventional commits
-2. Run the appropriate release command
-3. Push to GitHub with tags
-4. Publish to npm
-
-Example:
-```bash
-# Make changes
-git add .
-git commit -m "feat(cli): add interactive setup wizard"
-
-# Create release
-npm run release:minor
-
-# Push to GitHub
-git push --follow-tags origin main
-
-# Publish to npm
-npm publish
-```
-
-### Option 2: Automated Publishing (Recommended)
-1. Make changes and commit using conventional commits
-2. Run the appropriate release command
-3. Push to GitHub with tags - **npm publishing happens automatically**
-
-Example:
-```bash
-# Make changes
-git add .
-git commit -m "feat(cli): add interactive setup wizard"
-
-# Create release
-npm run release:minor
-
-# Push to GitHub (triggers automatic npm publish)
-git push --follow-tags origin main
-```
-
-**Setup Required for Automated Publishing:**
-1. Add `NPM_TOKEN` secret to your GitHub repository
-2. The GitHub Actions workflow (`.github/workflows/publish.yml`) will automatically:
-   - Run tests
-   - Publish to npm when a tag starting with `v` is pushed
-   - Use the `--access public` flag for scoped packages
-
-## Unpublishing (Emergency Only)
-
-If you need to unpublish a version within 72 hours:
-
-```bash
-npm unpublish @programinglive/commiter@1.0.0
-```
-
-**Warning**: Unpublishing is permanent and should only be used in emergencies.
-
-## Package Visibility
-
-- **Public**: Anyone can install and use the package
-- **Open Source**: MIT licensed - users can modify and distribute
-- **Free**: No cost to install or use
-
-## Support
-
-For issues or questions:
-- GitHub Issues: https://github.com/programinglive/commiter/issues
-- NPM Package: https://www.npmjs.com/package/@programinglive/commiter
+# Publishing to NPM
+
+This guide explains how to publish the `@programinglive/commiter` package to npm.
+
+## Prerequisites
+
+1. **NPM Account**: Create an account at [npmjs.com](https://www.npmjs.com/)
+2. **Login to NPM**: Run `npm login` in your terminal
+3. **Organization Access**: Ensure you have access to the `@programinglive` organization on npm
+
+## Publishing Steps
+
+### 1. Login to NPM
+
+```bash
+npm login
+```
+
+Enter your npm credentials when prompted.
+
+### 2. Verify Package Configuration
+
+Check that `package.json` is correctly configured:
+
+```bash
+npm pack --dry-run
+```
+
+This shows what files will be included in the package.
+
+### 3. Publish the Package
+
+For the first publish:
+
+```bash
+npm publish --access public
+```
+
+**Note**: The `--access public` flag is required for scoped packages (@programinglive/commiter) to be publicly accessible.
+
+### 4. Verify Publication
+
+Check your package on npm:
+```
+https://www.npmjs.com/package/@programinglive/commiter
+```
+
+## Releasing New Versions
+
+After the initial publish, use the built-in release commands:
+
+### Patch Release (1.0.0 → 1.0.1)
+```bash
+npm run release:patch
+git push --follow-tags origin main
+npm publish
+```
+
+### Minor Release (1.0.0 → 1.1.0)
+```bash
+npm run release:minor
+git push --follow-tags origin main
+npm publish
+```
+
+### Major Release (1.0.0 → 2.0.0)
+```bash
+npm run release:major
+git push --follow-tags origin main
+npm publish
+```
+
+## Automated Release Workflow
+
+### Option 1: Manual Publishing (Traditional)
+1. Make changes and commit using conventional commits
+2. Run the appropriate release command
+3. Push to GitHub with tags
+4. Publish to npm
+
+Example:
+```bash
+# Make changes
+git add .
+git commit -m "feat(cli): add interactive setup wizard"
+
+# Create release
+npm run release:minor
+
+# Push to GitHub
+git push --follow-tags origin main
+
+# Publish to npm
+npm publish
+```
+
+### Option 2: Automated Publishing (Recommended)
+1. Make changes and commit using conventional commits
+2. Run the appropriate release command
+3. Push to GitHub with tags - **npm publishing happens automatically**
+
+Example:
+```bash
+# Make changes
+git add .
+git commit -m "feat(cli): add interactive setup wizard"
+
+# Create release
+npm run release:minor
+
+# Push to GitHub (triggers automatic npm publish)
+git push --follow-tags origin main
+```
+
+**Setup Required for Automated Publishing:**
+1. Add `NPM_TOKEN` secret to your GitHub repository
+2. The GitHub Actions workflow (`.github/workflows/publish.yml`) will automatically:
+   - Run tests
+   - Publish to npm when a tag starting with `v` is pushed
+   - Use the `--access public` flag for scoped packages
+
+## Unpublishing (Emergency Only)
+
+If you need to unpublish a version within 72 hours:
+
+```bash
+npm unpublish @programinglive/commiter@1.0.0
+```
+
+**Warning**: Unpublishing is permanent and should only be used in emergencies.
+
+## Package Visibility
+
+- **Public**: Anyone can install and use the package
+- **Open Source**: MIT licensed - users can modify and distribute
+- **Free**: No cost to install or use
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/programinglive/commiter/issues
+- NPM Package: https://www.npmjs.com/package/@programinglive/commiter