contextforge-cli-ai-prompt-pirates 0.4.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextforge-cli-ai-prompt-pirates",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Background AI context engine — auto-generates context.md on npm install for Cursor, Claude, and ChatGPT",
   "type": "module",
   "main": "./src/index.js",
@@ -52,10 +52,11 @@
     "@babel/parser": "^7.26.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
+    "contextforge-cli-ai-prompt": "^0.3.0",
+    "dotenv": "^16.4.7",
     "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"
   },

package/src/core/cursor-rules.js

@@ -3,6 +3,20 @@ import path from 'node:path';
 import { getOutputPath, OUTPUT_FILES } from './paths.js';
 
 const RULE_FILENAME = 'contextforge.mdc';
+/** Max chars of context.md embedded in .mdc (Cursor rule size limits). */
+const MAX_EMBEDDED_CONTEXT_CHARS = 14000;
+
+/**
+ * Create `.cursor/` and `.cursor/rules/` if they do not exist.
+ * @param {string} projectRoot
+ * @returns {Promise<{ cursorDir: string, created: boolean }>}
+ */
+export async function ensureCursorRulesDir(projectRoot) {
+  const cursorDir = path.join(projectRoot, '.cursor', 'rules');
+  const existed = await fs.pathExists(cursorDir);
+  await fs.ensureDir(cursorDir);
+  return { cursorDir, created: !existed };
+}
 
 /**
  * @param {{ description?: string, alwaysApply?: boolean }} meta
@@ -78,7 +92,7 @@ function renderRoutesBrief(endpoints = []) {
     ...endpoints.slice(0, 20).map((e) => `| ${e.method} | ${e.path} | \`${e.file}\` |`),
   ];
   if (endpoints.length > 20) {
-    lines.push('', `_+ ${endpoints.length - 20} more in \`.contextforge/context.md\`_`);
+    lines.push('', `_+ ${endpoints.length - 20} more in full context below._`);
   }
   return lines.join('\n');
 }
@@ -92,11 +106,30 @@ function renderServicesBrief(businessLogic = []) {
 }
 
 /**
- * Build a single Cursor rule file from the pipeline snapshot (same source as context.md).
+ * @param {string} projectRoot
+ * @param {{ maxChars?: number }} [options]
+ */
+export async function readContextMarkdownForRule(projectRoot, options = {}) {
+  const maxChars = options.maxChars ?? MAX_EMBEDDED_CONTEXT_CHARS;
+  const mdPath = getOutputPath(projectRoot, OUTPUT_FILES.contextMd);
+  if (!(await fs.pathExists(mdPath))) return null;
+
+  let md = await fs.readFile(mdPath, 'utf8');
+  const truncated = md.length > maxChars;
+  if (truncated) {
+    md =
+      md.slice(0, maxChars) +
+      '\n\n---\n\n_…truncated. Full file: `.contextforge/context.md`._';
+  }
+  return { content: md, truncated, sourcePath: '.contextforge/context.md' };
+}
+
+/**
+ * Build rule body (markdown inside .mdc).
  * @param {object} snapshot
- * @returns {{ filename: string, content: string }[]}
+ * @param {string|null} embeddedContextMd
  */
-export function buildCursorRuleFiles(snapshot) {
+export function buildCursorRuleBody(snapshot, embeddedContextMd = null) {
   const projectName = snapshot.projectName || 'project';
   const generatedAt = snapshot.generatedAt || new Date().toISOString();
   const ts = snapshot.techStack || {};
@@ -107,18 +140,15 @@ export function buildCursorRuleFiles(snapshot) {
     '',
     `_Synced from \`.contextforge/context.md\` (${generatedAt})_`,
     '',
-    'Before answering questions about this codebase, **read [`.contextforge/context.md`](.contextforge/context.md)** for full detail.',
-    '',
     '## At a Glance',
     '',
     renderAtAGlanceTable(snapshot),
     '',
     '## Commands',
     '',
-    '- Regenerate: `npx contextforge generate`',
-    '- Watch: `npx contextforge watch`',
-    '- Changes: `npx contextforge changes` or `.contextforge/CHANGES.md`',
-    '- Timer: `CONTEXTFORGE_REFRESH_INTERVAL_MINUTES` in `.env` (e.g. 15)'
+    '- Regenerate: `npx cfpirates generate` or `npx contextforge-cli-ai-prompt-pirates generate`',
+    '- Watch: `npx cfpirates watch`',
+    '- Changes: `npx cfpirates changes`'
   );
 
   const importantRules = collectImportantRules(snapshot);
@@ -177,10 +207,33 @@ export function buildCursorRuleFiles(snapshot) {
     );
   }
 
-  sections.push(
-    '_More detail in `.contextforge/context.md` (architecture, git, database, full issue list)._'
-  );
+  if (embeddedContextMd) {
+    sections.push(
+      '',
+      '---',
+      '',
+      '## Full project context (from context.md)',
+      '',
+      embeddedContextMd
+    );
+  } else {
+    sections.push(
+      '',
+      '_Full detail: [`.contextforge/context.md`](.contextforge/context.md)._'
+    );
+  }
+
+  return sections.join('\n\n');
+}
 
+/**
+ * Build a single Cursor rule file from the pipeline snapshot.
+ * @param {object} snapshot
+ * @param {string|null} [embeddedContextMd]
+ * @returns {{ filename: string, content: string }[]}
+ */
+export function buildCursorRuleFiles(snapshot, embeddedContextMd = null) {
+  const body = buildCursorRuleBody(snapshot, embeddedContextMd);
   return [
     {
       filename: RULE_FILENAME,
@@ -189,7 +242,7 @@ export function buildCursorRuleFiles(snapshot) {
           description: 'ContextForge project memory — read before coding',
           alwaysApply: true,
         },
-        sections.join('\n\n')
+        body
       ),
     },
   ];
@@ -198,9 +251,10 @@ export function buildCursorRuleFiles(snapshot) {
 /**
  * @param {string} projectRoot
  * @param {object} [snapshot]
+ * @param {{ embedContextMd?: boolean }} [options]
  */
-export async function installCursorRules(projectRoot, snapshot = null) {
-  const cursorDir = path.join(projectRoot, '.cursor', 'rules');
+export async function installCursorRules(projectRoot, snapshot = null, options = {}) {
+  const embedContextMd = options.embedContextMd !== false;
   const agentsPath = path.join(projectRoot, 'AGENTS.md');
 
   if (!snapshot) {
@@ -210,9 +264,17 @@ export async function installCursorRules(projectRoot, snapshot = null) {
     }
   }
 
-  await fs.ensureDir(cursorDir);
+  const { cursorDir, created } = await ensureCursorRulesDir(projectRoot);
+
+  let embeddedMd = null;
+  if (embedContextMd && snapshot) {
+    const loaded = await readContextMarkdownForRule(projectRoot);
+    if (loaded) embeddedMd = loaded.content;
+  }
 
-  const ruleFiles = snapshot ? buildCursorRuleFiles(snapshot) : [buildFallbackRule()];
+  const ruleFiles = snapshot
+    ? buildCursorRuleFiles(snapshot, embeddedMd)
+    : [buildFallbackRule()];
 
   const written = [];
   for (const { filename, content } of ruleFiles) {
@@ -225,7 +287,7 @@ export async function installCursorRules(projectRoot, snapshot = null) {
 
   await syncAgentsMd(agentsPath);
 
-  return { rulePaths: written, agentsPath };
+  return { rulePaths: written, agentsPath, createdCursorDir: created, cursorDir };
 }
 
 function buildFallbackRule() {
@@ -238,11 +300,10 @@ function buildFallbackRule() {
       },
       `# ContextForge — Project Memory
 
-Before answering questions about this codebase, **read \`.contextforge/context.md\`** in full.
+Run \`npx cfpirates generate\` to create \`.contextforge/context.md\`, then re-run to sync this rule.
 
-Regenerate context: \`npx contextforge generate\`
-Watch mode: \`npx contextforge watch\`
-Change history: \`npx contextforge changes\` or \`.contextforge/CHANGES.md\``
+Regenerate: \`npx cfpirates generate\`
+Watch: \`npx cfpirates watch\``
     ),
   };
 }

package/src/core/pipeline.js

@@ -203,10 +203,16 @@ export async function runPipeline(projectRoot, options = {}) {
   await renderContextMarkdown(projectRootResolved, snapshot);
 
   if (config.installCursorRules !== false) {
-    const { rulePaths } = await installCursorRules(projectRootResolved, snapshot);
+    const { rulePaths, createdCursorDir, cursorDir } = await installCursorRules(
+      projectRootResolved,
+      snapshot
+    );
+    if (createdCursorDir) {
+      log(projectRootResolved, `Created ${cursorDir}/`, verbose);
+    }
     log(
       projectRootResolved,
-      `Synced ${rulePaths.length} Cursor rule(s) in .cursor/rules/`,
+      `Synced ${rulePaths.length} Cursor rule(s) with embedded context.md`,
       verbose
     );
   }

package/src/services/ai/enrich.js

@@ -12,6 +12,12 @@ const PROVIDERS = {
 
 const MAX_RETRIES = 2;
 
+function isRateLimitError(err) {
+  const status = err?.status ?? err?.response?.status;
+  const msg = err?.message || String(err);
+  return status === 429 || /429|rate limit|tokens per day/i.test(msg);
+}
+
 /**
  * @param {object} snapshot
  * @param {object} config
@@ -72,11 +78,20 @@ export async function enrichWithAI(snapshot, config) {
         };
       } catch (err) {
         lastError = err;
+        if (isRateLimitError(err)) {
+          break;
+        }
         if (attempt >= MAX_RETRIES) break;
       }
     }
   }
 
+  if (lastError && isRateLimitError(lastError)) {
+    throw new Error(
+      `AI rate limit (${lastError.message}). Wait and retry, or set CONTEXTFORGE_AI_PROVIDER=openai in .env.`
+    );
+  }
+
   throw lastError || new Error('No AI provider available. Set OPENAI_API_KEY or GROQ_API_KEY in .env');
 }
 

package/src/services/ai/prompt.js

@@ -33,7 +33,10 @@ export function buildEnrichmentPrompt(snapshot, isRetry = false) {
 }
 
 export function parseAiResponse(text) {
-  const trimmed = text.trim();
+  const trimmed = (text ?? '').trim();
+  if (!trimmed) {
+    throw new Error('AI response was empty');
+  }
   const jsonMatch = trimmed.match(/\{[\s\S]*\}/);
   if (!jsonMatch) {
     throw new Error('AI response did not contain JSON');

package/src/services/ai/providers/openai.js

@@ -1,6 +1,18 @@
 import OpenAI from 'openai';
 import { getApiKey } from '../../../core/env.js';
 
+/** GPT-5 / o-series models use max_completion_tokens instead of max_tokens. */
+function usesCompletionTokensParam(model) {
+  return /^(gpt-5|o[0-9](-|$))/i.test(model || '');
+}
+
+function buildCompletionParams(model, maxTokens) {
+  if (usesCompletionTokensParam(model)) {
+    return { max_completion_tokens: maxTokens };
+  }
+  return { max_tokens: maxTokens };
+}
+
 /**
  * @param {{ model: string, maxTokens: number, timeoutMs: number }} options
  */
@@ -15,16 +27,31 @@ export async function callOpenAI(messages, options) {
     timeout: options.timeoutMs,
   });
 
-  const response = await client.chat.completions.create({
+  const request = {
     model: options.model,
     messages,
-    max_tokens: options.maxTokens,
-    temperature: 0.3,
+    ...buildCompletionParams(options.model, options.maxTokens),
     response_format: { type: 'json_object' },
-  });
+  };
+
+  if (!usesCompletionTokensParam(options.model)) {
+    request.temperature = 0.3;
+  }
+
+  const response = await client.chat.completions.create(request);
+  const choice = response.choices[0];
+  const content = choice?.message?.content ?? '';
+
+  if (!content.trim()) {
+    const finish = choice?.finish_reason ?? 'unknown';
+    throw new Error(
+      `OpenAI returned empty content (finish_reason=${finish}). ` +
+        'For gpt-5/o-series models, raise maxTokens — reasoning uses completion budget.'
+    );
+  }
 
   return {
-    content: response.choices[0]?.message?.content || '',
+    content,
     model: response.model,
     provider: 'openai',
     usage: response.usage,

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

@@ -1,28 +0,0 @@
-{
-  "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

@@ -1,29 +0,0 @@
-{
-  "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

@@ -1,50 +0,0 @@
-# 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`