devforgeai 1.0.8 → 1.0.9

package/docs/CNAME

@@ -0,0 +1 @@
+devforgeai.com

package/docs/NPM-Publish.md

@@ -0,0 +1,341 @@
+# NPM Package Publishing Guide
+
+Reference for publishing, versioning, deprecating, and unpublishing the `devforgeai` npm package.
+
+---
+
+## Prerequisites
+
+```bash
+# Verify npm is installed
+npm --version
+
+# Log in to npm (one-time, or when token expires)
+npm login
+
+# Verify you're authenticated
+npm whoami
+```
+
+---
+
+## 1. Publishing a New Package (First Time)
+
+### 1.1 Verify package.json
+
+Ensure these fields are set correctly:
+
+```json
+{
+  "name": "devforgeai",
+  "version": "1.0.0",
+  "description": "...",
+  "main": "lib/cli.js",
+  "bin": { "devforgeai": "bin/devforgeai.js" },
+  "files": ["bin/", "lib/", "src/cli/", "..."]
+}
+```
+
+Key fields:
+- `name` — must be unique on npm (or scoped: `@org/devforgeai`)
+- `version` — semver format (MAJOR.MINOR.PATCH)
+- `files` — whitelist of files to include in the package (everything else excluded)
+
+### 1.2 Dry Run (Preview What Gets Published)
+
+Always dry-run first to verify package contents:
+
+```bash
+# Show what files will be included
+npm pack --dry-run
+
+# Write files will be included to a text file
+npm pack --dry-run 2>&1 | tee npm-pack-manifest.txt                             
+
+# Creates a tarball locally without publishing (inspect contents)
+npm pack
+tar -tzf devforgeai-1.0.0.tgz
+```
+
+### 1.3 Publish
+
+```bash
+# Publish to npm registry
+npm publish
+
+# Publish with a specific tag (e.g., beta, next)
+npm publish --tag beta
+```
+
+### 1.4 Verify Publication
+
+```bash
+# Check the package on npm
+npm view devforgeai
+
+# Check specific version
+npm view devforgeai versions --json
+```
+
+---
+
+## 2. Version Bumping
+
+### 2.1 Semantic Versioning (SemVer)
+
+| Bump Type | When to Use | Example |
+|-----------|-------------|---------|
+| `patch` | Bug fixes, minor changes, no API changes | 1.0.0 -> 1.0.1 |
+| `minor` | New features, backward compatible | 1.0.0 -> 1.1.0 |
+| `major` | Breaking changes | 1.0.0 -> 2.0.0 |
+
+### 2.2 Bump and Publish
+
+```bash
+# Bump version in package.json (auto-updates package.json and package-lock.json)
+npm version patch    # 1.0.3 -> 1.0.4
+npm version minor    # 1.0.3 -> 1.1.0
+npm version major    # 1.0.3 -> 2.0.0
+
+# npm version also creates a git commit and tag automatically
+# To skip the git commit/tag:
+npm version patch --no-git-tag-version
+
+# Then publish
+npm publish
+```
+
+### 2.3 Pre-release Versions
+
+```bash
+# Create pre-release versions
+npm version prerelease --preid=beta    # 1.0.3 -> 1.0.4-beta.0
+npm version prerelease --preid=beta    # 1.0.4-beta.0 -> 1.0.4-beta.1
+
+# Publish with a tag so it doesn't become "latest"
+npm publish --tag beta
+
+# Users install pre-release with:
+npm install devforgeai@beta
+```
+
+### 2.4 Manual Version Bump
+
+If you prefer to edit `package.json` directly:
+
+1. Edit `version` field in `package.json`
+2. Run `npm publish`
+
+No `npm version` command needed — but you won't get the automatic git tag.
+
+---
+
+## 3. Managing Tags
+
+Tags control what version users get with `npm install devforgeai`.
+
+```bash
+# View current tags
+npm dist-tag ls devforgeai
+
+# Move the "latest" tag to a specific version
+npm dist-tag add devforgeai@1.0.3 latest
+
+# Add a custom tag
+npm dist-tag add devforgeai@2.0.0-beta.1 beta
+
+# Remove a tag
+npm dist-tag rm devforgeai beta
+```
+
+---
+
+## 4. Deprecating Versions
+
+Deprecation shows a warning when users install the version but does NOT remove it.
+This is the **recommended first step** before unpublishing.
+
+### 4.1 Deprecate Specific Versions
+
+```bash
+# Deprecate a single version
+npm deprecate devforgeai@1.0.0 "Upgrade to 1.0.3 - includes security hardening"
+
+# Deprecate a range of versions
+npm deprecate "devforgeai@<1.0.3" "Upgrade to >=1.0.3 - includes RCA-046/047 security hardening"
+
+# Deprecate with a detailed message
+npm deprecate devforgeai@1.0.1 "This version has known test integrity issues. Please upgrade to 1.0.3+"
+```
+
+### 4.2 What Users See
+
+When someone installs a deprecated version:
+
+```
+npm warn deprecated devforgeai@1.0.0: Upgrade to 1.0.3 - includes security hardening
+```
+
+The package still installs — deprecation is a warning, not a block.
+
+### 4.3 Un-deprecate a Version
+
+```bash
+# Remove deprecation by passing an empty string
+npm deprecate devforgeai@1.0.0 ""
+```
+
+---
+
+## 5. Unpublishing Versions
+
+Unpublishing **permanently removes** a version from npm. Use with caution.
+
+### 5.1 npm Unpublish Rules
+
+| Condition | Allowed? |
+|-----------|----------|
+| Within 72 hours of publish | Yes |
+| After 72 hours | No (requires npm support) |
+| Version has dependents | Blocked by npm |
+| Last version of a package | Requires `--force` |
+
+### 5.2 Unpublish a Specific Version
+
+```bash
+# Unpublish a single version (within 72-hour window)
+npm unpublish devforgeai@1.0.0
+
+# If npm warns about dependents, you can force (use carefully)
+npm unpublish devforgeai@1.0.0 --force
+```
+
+### 5.3 Unpublish the Entire Package
+
+```bash
+# Remove ALL versions (nuclear option - rarely appropriate)
+npm unpublish devforgeai --force
+```
+
+After unpublishing an entire package, the name is blocked for 24 hours — you cannot republish with the same name immediately.
+
+### 5.4 Recommended Workflow: Deprecate Then Unpublish
+
+```bash
+# Step 1: Deprecate first (gives users warning)
+npm deprecate devforgeai@1.0.0 "This version will be removed. Upgrade to 1.0.3+"
+
+# Step 2: Wait a reasonable period (days/weeks) for users to migrate
+
+# Step 3: Unpublish (within 72-hour window of original publish)
+npm unpublish devforgeai@1.0.0
+```
+
+---
+
+## 6. Checking Package Status
+
+```bash
+# View all published versions
+npm view devforgeai versions --json
+
+# View detailed info for a version
+npm view devforgeai@1.0.3
+
+# View download counts
+npm view devforgeai
+
+# Check who has publish access
+npm access ls-collaborators devforgeai
+
+# View package size
+npm pack --dry-run 2>&1 | tail -1
+```
+
+---
+
+## 7. Common Workflows
+
+### Patch Release (Bug Fix)
+
+```bash
+# 1. Make changes
+# 2. Bump version
+npm version patch --no-git-tag-version
+# 3. Dry-run
+npm pack --dry-run
+# 4. Publish
+npm publish
+# 5. Verify
+npm view devforgeai versions --json
+```
+
+### Deprecate Old Versions After Security Fix
+
+```bash
+# Deprecate all versions below the fix
+npm deprecate "devforgeai@<1.0.3" "Security fix in 1.0.3. Please upgrade."
+
+# Verify deprecation
+npm view devforgeai@1.0.0
+# Should show "DEPRECATED" in output
+```
+
+### Publish Beta for Testing
+
+```bash
+npm version prerelease --preid=beta --no-git-tag-version
+npm publish --tag beta
+# Users test with: npm install devforgeai@beta
+# When ready: npm dist-tag add devforgeai@1.1.0-beta.3 latest
+```
+
+---
+
+## 8. Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `npm ERR! 403 Forbidden` | Run `npm login` — token may have expired |
+| `npm ERR! 402 Payment Required` | Package name may be scoped — use `npm publish --access public` |
+| `npm ERR! You cannot publish over the previously published versions` | Bump version first with `npm version patch` |
+| `npm ERR! Cannot unpublish` | Past 72-hour window — contact npm support or deprecate instead |
+| `ENEEDAUTH` | Not logged in — run `npm login` |
+
+---
+
+## 9. .npmignore vs files Field
+
+This project uses the `files` whitelist in `package.json` (preferred approach). The `.npmignore` file provides a secondary exclusion layer.
+
+- **`files` in package.json**: Whitelist — only listed paths are included
+- **`.npmignore`**: Blacklist — listed paths are excluded from what `files` includes
+- **Both present**: `files` takes precedence, `.npmignore` filters within that
+
+`package.json`, `README.md`, and `LICENSE` are always included regardless of settings.
+
+---
+
+## Quick Reference Card
+
+```bash
+# Publish
+npm publish                                    # publish latest
+npm publish --tag beta                         # publish as beta
+
+# Version
+npm version patch|minor|major                  # bump + git tag
+npm version patch --no-git-tag-version         # bump only
+
+# Deprecate
+npm deprecate devforgeai@1.0.0 "message"       # warn users
+npm deprecate devforgeai@1.0.0 ""              # un-deprecate
+
+# Unpublish (within 72 hours)
+npm unpublish devforgeai@1.0.0                 # remove version
+
+# Inspect
+npm view devforgeai versions --json            # list versions
+npm pack --dry-run                             # preview package
+npm dist-tag ls devforgeai                     # list tags
+```