contextforge-cli-ai-prompt-pirates 0.4.0

package/.contextforge/config.ai.example.json

@@ -0,0 +1,28 @@
+{
+  "ignore": ["node_modules", "dist", ".next", "coverage", ".git"],
+  "watch": true,
+  "autoGenerate": true,
+  "includeGitHistory": true,
+  "detectBugs": true,
+  "debounceMs": 2000,
+  "refreshIntervalMinutes": 15,
+  "trackChanges": true,
+  "maxTreeDepth": 4,
+  "gitCommitLimit": 20,
+  "ai": {
+    "enabled": true,
+    "provider": "openai",
+    "fallbackProvider": "groq",
+    "enrichContext": true,
+    "background": true,
+    "openai": {
+      "model": "gpt-4o-mini"
+    },
+    "groq": {
+      "model": "llama-3.3-70b-versatile"
+    },
+    "maxTokens": 4096,
+    "timeoutMs": 120000,
+    "promptsDir": ".contextforge/prompts"
+  }
+}

package/.contextforge/config.example.json

@@ -0,0 +1,29 @@
+{
+  "ignore": ["node_modules", "dist", "build", ".next", "coverage", ".git"],
+  "watch": true,
+  "autoGenerate": true,
+  "includeGitHistory": true,
+  "detectBugs": true,
+  "debounceMs": 2000,
+  "refreshIntervalMinutes": 0,
+  "trackChanges": true,
+  "maxTreeDepth": 4,
+  "gitCommitLimit": 20,
+  "maxFileSizeBytes": 524288,
+  "installCursorRules": true,
+  "postinstallGenerate": true,
+  "postinstallWatch": true,
+  "postinstallOnNpmInstall": true,
+  "ai": {
+    "enabled": false,
+    "provider": "openai",
+    "fallbackProvider": "groq",
+    "enrichContext": true,
+    "background": true,
+    "openai": { "model": "gpt-4o-mini" },
+    "groq": { "model": "llama-3.3-70b-versatile" },
+    "maxTokens": 4096,
+    "timeoutMs": 120000,
+    "promptsDir": ".contextforge/prompts"
+  }
+}

package/.contextforge/prompts/README.md

@@ -0,0 +1,50 @@
+# ContextForge Prompts
+
+Edit these files to change how AI enriches `context.md` — **no code changes needed**.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `system.md` | System message sent to OpenAI / Groq |
+| `user-template.md` | User message template (repository analysis request) |
+| `response-schema.md` | Required JSON keys the AI must return |
+| `retry-addon.md` | Extra instructions when validation fails (retry) |
+
+## Placeholders (user-template.md)
+
+| Placeholder | Replaced with |
+|-------------|----------------|
+| `{{SCAN_DATA}}` | Sanitized JSON scan snapshot |
+| `{{RETRY_NOTE}}` | Retry instructions (empty on first attempt) |
+| `{{PROJECT_NAME}}` | Project name from scan |
+
+## Per-project customization
+
+On `contextforge init`, prompts are copied to:
+
+```
+.contextforge/prompts/
+```
+
+Edit files there for **this project only**. Config key:
+
+```json
+"ai": {
+  "promptsDir": ".contextforge/prompts"
+}
+```
+
+Point to another folder:
+
+```json
+"ai": {
+  "promptsDir": "my-custom-prompts"
+}
+```
+
+## Tips
+
+- Keep `response-schema.md` keys in sync with `src/services/ai/validate.js` required keys.
+- Do not ask AI to read source files — only scan JSON is sent.
+- After edits, run: `npx contextforge generate --ai`

package/.env.example

@@ -0,0 +1,73 @@
+# =============================================================================
+# ContextForge — Environment Variables
+# =============================================================================
+# 1. Copy this file:   cp .env.example .env   (Windows: copy .env.example .env)
+# 2. Fill in your API keys below
+# 3. Never commit .env (it is gitignored)
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# OpenAI — https://platform.openai.com/api-keys
+# -----------------------------------------------------------------------------
+OPENAI_API_KEY=
+
+# Optional model override (default in config: gpt-4o-mini)
+OPENAI_MODEL=gpt-4o-mini
+
+# -----------------------------------------------------------------------------
+# Groq — https://console.groq.com/keys
+# -----------------------------------------------------------------------------
+GROQ_API_KEY=
+
+# Optional model override (default in config: llama-3.3-70b-versatile)
+GROQ_MODEL=llama-3.3-70b-versatile
+
+# -----------------------------------------------------------------------------
+# ContextForge AI settings
+# -----------------------------------------------------------------------------
+# Primary provider when both keys are set: openai | groq
+CONTEXTFORGE_AI_PROVIDER=openai
+
+# Enable AI enrichment (used by generate / watch / npm install auto-setup)
+CONTEXTFORGE_AI_ENABLED=true
+
+# Alternate variable names (optional aliases)
+# CONTEXTFORGE_OPENAI_API_KEY=
+# CONTEXTFORGE_GROQ_API_KEY=
+
+# -----------------------------------------------------------------------------
+# npm install — auto-detect & start (no manual init required)
+# -----------------------------------------------------------------------------
+# Master switch: after npm install → create .contextforge + context.md + watch
+CONTEXTFORGE_AUTO_START=true
+
+# Run first context scan on install
+CONTEXTFORGE_POSTINSTALL_GENERATE=true
+
+# Start background watcher on install (updates on file save + timer below)
+CONTEXTFORGE_POSTINSTALL_WATCH=true
+
+# Disable all postinstall automation (same as AUTO_START=false)
+# CONTEXTFORGE_SKIP_POSTINSTALL=1
+
+# Allow postinstall in CI (skipped by default when CI=true)
+# CONTEXTFORGE_RUN_IN_CI=1
+
+# -----------------------------------------------------------------------------
+# Watch — auto-refresh timer (minutes). 0 = only when you save files.
+# -----------------------------------------------------------------------------
+CONTEXTFORGE_REFRESH_INTERVAL_MINUTES=15
+
+# Same as above (alias)
+# CONTEXTFORGE_WATCH_INTERVAL_MINUTES=15
+
+# Or use seconds instead of minutes (e.g. 300 = every 5 minutes)
+# CONTEXTFORGE_REFRESH_INTERVAL_SECONDS=300
+
+# Wait this long after a file save before regenerating (milliseconds)
+# CONTEXTFORGE_DEBOUNCE_MS=2000
+
+# -----------------------------------------------------------------------------
+# Node (optional)
+# -----------------------------------------------------------------------------
+# NODE_ENV=development

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ContextForge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# ContextForge
+
+**Persistent AI memory for your repository.** Install once with `npm install` — ContextForge scans your codebase in the background and keeps `.contextforge/context.md` (and a Cursor rule) up to date for ChatGPT, Claude, and Cursor.
+
+## Install (npm — works like local)
+
+In **any** Node.js 18+ project:
+
+```bash
+npm install -D contextforge-cli-ai-prompt-pirates
+```
+
+That is the only required step. On install, ContextForge automatically:
+
+1. Creates `.env` from `.env.example` (if you do not have one)
+2. Creates `.contextforge/` and generates `context.md`
+3. Writes `.cursor/rules/contextforge.mdc` for Cursor
+4. Starts a background watcher (`watch --daemon`) for file saves + optional timer
+
+You should see:
+
+```text
+[contextforge] npm install → auto setup starting in background
+```
+
+Verify after ~10–30 seconds:
+
+```bash
+npx contextforge-cli-ai-prompt-pirates doctor
+# or
+npx cfpirates doctor
+```
+
+Logs: `.contextforge/logs/postinstall.log` · Stop watcher: `npx cfpirates stop`
+
+### Optional: AI enrichment
+
+Edit `.env` in your project (created on first install):
+
+```env
+OPENAI_API_KEY=sk-...
+GROQ_API_KEY=gsk_...
+CONTEXTFORGE_AI_PROVIDER=openai
+CONTEXTFORGE_AI_ENABLED=true
+CONTEXTFORGE_REFRESH_INTERVAL_MINUTES=15
+```
+
+Regenerate with AI: `npx cfpirates generate`
+
+### Disable auto-start on install
+
+```env
+CONTEXTFORGE_AUTO_START=false
+```
+
+Or:
+
+```json
+"contextforge": { "postinstall": false }
+```
+
+Or: `CONTEXTFORGE_SKIP_POSTINSTALL=1`
+
+### Important: npm install flags
+
+| Command | Auto-setup |
+|---------|------------|
+| `npm install` | Yes |
+| `npm install --ignore-scripts` | **No** (npm skips postinstall) |
+| `npm ci` | Yes (unless ignore-scripts) |
+
+## Local development (this repo)
+
+```bash
+git clone <your-repo>
+cd contextforge-cli-ai-prompt-pirates   # your repo folder name may differ
+npm install
+npm test
+npx cfpirates doctor
+```
+
+Uses the same `postinstall` hook as published users.
+
+## Manual commands (optional)
+
+```bash
+npx cfpirates init          # full setup + tips
+npx cfpirates generate      # regenerate on demand
+npx cfpirates watch         # foreground watcher
+npx cfpirates changes       # change history
+npx cfpirates prompt        # export context for AI chat
+```
+
+## Output layout
+
+```
+.contextforge/
+├── config.json
+├── context.md          ← full project memory for AI
+├── CHANGES.md
+├── context.json
+├── architecture.json
+├── git-insights.json
+├── bugs-report.json
+├── cache/
+└── logs/
+.cursor/rules/
+└── contextforge.mdc    ← Cursor auto-rule (synced on generate)
+```
+
+## CLI commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Create `.contextforge/`, config, first context |
+| `generate` | Scan repo and regenerate artifacts |
+| `watch` | Watch files + optional timer refresh |
+| `changes` | Show change history between runs |
+| `stop` | Stop background watcher (`watch --daemon`) |
+| `doctor` | Health check |
+| `summary` | Short stdout summary |
+| `prompt` | Export context block for AI prompts |
+
+```bash
+npx cfpirates generate --cwd /path/to/project
+npx cfpirates watch --verbose
+npx cfpirates watch --interval 15
+npx cfpirates generate --ai
+npx cfpirates generate --no-ai
+```
+
+## Environment variables (`.env`)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `CONTEXTFORGE_AUTO_START` | `true` | Auto setup on `npm install` |
+| `CONTEXTFORGE_POSTINSTALL_GENERATE` | `true` | Create `context.md` on install |
+| `CONTEXTFORGE_POSTINSTALL_WATCH` | `true` | Start background watch on install |
+| `CONTEXTFORGE_SKIP_POSTINSTALL` | — | Set `1` to disable all install automation |
+| `CONTEXTFORGE_AI_ENABLED` | — | `true` / `false` overrides config |
+| `CONTEXTFORGE_AI_PROVIDER` | `openai` | `openai` or `groq` |
+| `CONTEXTFORGE_REFRESH_INTERVAL_MINUTES` | `0` | Timer while watch runs (`0` = file saves only) |
+| `OPENAI_API_KEY` / `GROQ_API_KEY` | — | AI enrichment |
+
+Copy from `.env.example` in your project after install.
+
+## Cursor integration
+
+ContextForge syncs **one rule file**: `.cursor/rules/contextforge.mdc` (includes stack summary + link to full `context.md`).
+
+Or add manually:
+
+> Read `.contextforge/context.md` before coding in this repository.
+
+## Configuration
+
+`.contextforge/config.json` (created automatically):
+
+```json
+{
+  "watch": true,
+  "autoGenerate": true,
+  "installCursorRules": true,
+  "postinstallGenerate": true,
+  "postinstallWatch": true,
+  "refreshIntervalMinutes": 0,
+  "ai": {
+    "enabled": false,
+    "provider": "openai",
+    "background": true
+  }
+}
+```
+
+`.env` overrides timer, debounce, and AI provider. Run `npx cfpirates init --force` to merge new config fields.
+
+## Programmatic API
+
+```js
+import { runPipeline, loadConfig } from 'contextforge-cli-ai-prompt-pirates';
+
+await runPipeline('/path/to/project', { verbose: true });
+```
+
+## Security
+
+- Static scan runs locally
+- AI sends aggregated metadata only (not `.env` or full source)
+- API keys stay in your `.env` (never published with the package)
+
+## Publish to npm
+
+**Before publish** (maintainers):
+
+```bash
+npm test
+npm run verify:pack
+npm publish --access public
+```
+
+Full guide: **[PUBLISHING.md](./PUBLISHING.md)**
+
+**After publish**, users only need:
+
+```bash
+npm install -D contextforge-cli-ai-prompt-pirates-cli-ai-prompt-pirates
+```
+
+No `file:` link or local path required.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| No `.contextforge` after install | Do not use `--ignore-scripts`; check `CONTEXTFORGE_AUTO_START` |
+| Works locally, not from npm | Publish **contextforge-cli-ai-prompt-pirates@0.4.0**; run `npm run verify:pack` |
+| Old name `contextforge` blocked on npm | Use **contextforge-cli-ai-prompt-pirates** (name `context-forge` was taken) |
+| Watch keeps running | `npx cfpirates stop` |
+| No Git history in context | Install Git and add to PATH |
+
+## License
+
+MIT

package/bin/contextforge.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadProjectEnv } from '../src/core/env.js';
+import { runCli } from '../src/cli/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+await loadProjectEnv(path.join(__dirname, '..'));
+
+runCli(process.argv).catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/bin/postinstall-worker.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadProjectEnv } from '../src/core/env.js';
+import { runPostinstall } from '../src/core/postinstall.js';
+
+const projectRoot = process.argv[2];
+if (!projectRoot) {
+  process.exit(1);
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+await loadProjectEnv(path.join(__dirname, '..'));
+await runPostinstall(path.resolve(projectRoot));

package/bin/postinstall.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * npm lifecycle: runs after `npm install` in the consuming project (INIT_CWD).
+ * Spawns a background worker — does not block install.
+ */
+import { loadProjectEnv } from '../src/core/env.js';
+import {
+  resolveInstallProjectRoot,
+  shouldRunPostinstall,
+  spawnPostinstallWorker,
+} from '../src/core/postinstall.js';
+
+const projectRoot = resolveInstallProjectRoot();
+await loadProjectEnv(projectRoot);
+
+if (await shouldRunPostinstall(projectRoot)) {
+  console.log('');
+  console.log('[contextforge] npm install → auto setup starting in background');
+  console.log('  • .contextforge/ + context.md');
+  console.log('  • .cursor/rules/contextforge.mdc');
+  console.log('  • background watch (file saves + timer from .env)');
+  console.log('  • log: .contextforge/logs/postinstall.log');
+  console.log('  • stop watch: npx contextforge stop');
+  console.log('');
+  spawnPostinstallWorker(projectRoot);
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "contextforge-cli-ai-prompt-pirates",
+  "version": "0.4.0",
+  "description": "Background AI context engine — auto-generates context.md on npm install for Cursor, Claude, and ChatGPT",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "contextforge-cli-ai-prompt-pirates": "./bin/contextforge.js",
+    "cfpirates": "./bin/contextforge.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "prompts",
+    "README.md",
+    "LICENSE",
+    ".env.example",
+    ".contextforge/config.example.json",
+    ".contextforge/config.ai.example.json"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "generate": "node bin/contextforge.js generate --cwd .",
+    "watch": "node bin/contextforge.js watch --cwd .",
+    "postinstall": "node bin/postinstall.js",
+    "prepublishOnly": "npm test",
+    "verify:pack": "node scripts/verify-pack.js"
+  },
+  "keywords": [
+    "ai",
+    "context",
+    "cursor",
+    "claude",
+    "chatgpt",
+    "copilot",
+    "repository",
+    "documentation",
+    "developer-tools",
+    "contextforge",
+    "postinstall"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.26.3",
+    "chokidar": "^4.0.3",
+    "commander": "^13.1.0",
+    "fs-extra": "^11.3.0",
+    "glob": "^11.0.1",
+    "ignore": "^7.0.3",
+    "dotenv": "^16.4.7",
+    "openai": "^4.77.0",
+    "simple-git": "^3.27.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.5"
+  }
+}

package/prompts/README.md

@@ -0,0 +1,50 @@
+# ContextForge Prompts
+
+Edit these files to change how AI enriches `context.md` — **no code changes needed**.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `system.md` | System message sent to OpenAI / Groq |
+| `user-template.md` | User message template (repository analysis request) |
+| `response-schema.md` | Required JSON keys the AI must return |
+| `retry-addon.md` | Extra instructions when validation fails (retry) |
+
+## Placeholders (user-template.md)
+
+| Placeholder | Replaced with |
+|-------------|----------------|
+| `{{SCAN_DATA}}` | Sanitized JSON scan snapshot |
+| `{{RETRY_NOTE}}` | Retry instructions (empty on first attempt) |
+| `{{PROJECT_NAME}}` | Project name from scan |
+
+## Per-project customization
+
+On `contextforge init`, prompts are copied to:
+
+```
+.contextforge/prompts/
+```
+
+Edit files there for **this project only**. Config key:
+
+```json
+"ai": {
+  "promptsDir": ".contextforge/prompts"
+}
+```
+
+Point to another folder:
+
+```json
+"ai": {
+  "promptsDir": "my-custom-prompts"
+}
+```
+
+## Tips
+
+- Keep `response-schema.md` keys in sync with `src/services/ai/validate.js` required keys.
+- Do not ask AI to read source files — only scan JSON is sent.
+- After edits, run: `npx contextforge generate --ai`

package/prompts/response-schema.md

@@ -0,0 +1,22 @@
+Return JSON with exactly these keys:
+
+```json
+{
+  "executiveSummary": "2-4 sentences overview of the project purpose and stack",
+  "techStackNarrative": "paragraph combining frontend, backend, database, and tools",
+  "architectureDeepDive": "detailed architecture explanation with folder/layer roles",
+  "apiAndDataFlow": "how HTTP/API requests move from client to database",
+  "businessLogicAnalysis": "where business logic lives; key modules and patterns",
+  "databaseAnalysis": "ORM/models, collections, relationships",
+  "authenticationNotes": "auth strategy, JWT/session/OAuth, middleware",
+  "deploymentNotes": "Docker, Vercel, env vars, how to run in production",
+  "gitEvolution": "what recent git activity suggests (or not a git repo)",
+  "importantRules": ["rule 1 for AI assistants", "rule 2"],
+  "codingConventions": ["convention 1", "convention 2"],
+  "possibleIssues": ["issue 1 from scan/heuristics"],
+  "suggestedImprovements": ["actionable improvement 1"]
+}
+```
+
+- `importantRules`, `codingConventions`, `possibleIssues`, `suggestedImprovements` must be JSON **arrays of strings**.
+- All other fields are strings (can be multi-sentence).

package/prompts/retry-addon.md

@@ -0,0 +1 @@
+**RETRY:** Your previous response was invalid or incomplete. Output complete valid JSON with ALL required keys. Do not omit any field. Do not invent technologies absent from the scan.

package/prompts/system.md

@@ -0,0 +1,10 @@
+You are ContextForge, an expert software architect and technical writer.
+
+Your job is to analyze repository scan data and produce accurate, actionable documentation for AI coding assistants (Cursor, Claude, ChatGPT, Copilot).
+
+Rules:
+- Output ONLY valid JSON (no markdown code fences, no commentary outside JSON).
+- Never invent frameworks, libraries, or files not supported by the scan data.
+- Be specific: name folders, patterns, and layers that appear in the scan.
+- Write rules that help AI assistants write code consistent with this project.
+- If data is missing, say "not detected" rather than guessing.

package/prompts/user-template.md

@@ -0,0 +1,22 @@
+Analyze the repository scan below and produce detailed AI-ready project context for **{{PROJECT_NAME}}**.
+
+{{RETRY_NOTE}}
+
+## Analysis goals
+
+1. Explain architecture and how requests/data flow through the system.
+2. Describe where business logic lives (services, controllers, components).
+3. Summarize database/ORM usage and relationships.
+4. Document authentication and deployment approach.
+5. List **importantRules** AI assistants must follow when editing this codebase.
+6. Note risks and improvements based only on scan evidence.
+
+## Scan data (JSON)
+
+```json
+{{SCAN_DATA}}
+```
+
+Return a single JSON object matching the schema in your instructions. Use only facts from the scan.
+
+Be **thorough**: each text field should be 3–6 sentences with concrete file paths, library names, and patterns from the scan. `importantRules` should have at least 5 actionable items for developers and AI assistants.