@aabadin/project-memory-context 0.2.0 → 0.2.1

package/cli/enrich-queue.mjs

@@ -29,6 +29,8 @@ let _symbolIndex = {};
 let _worklistFile = '';
 let _symbolIndexFile = '';
 let _enrichmentDir = '';
+let _queueStateFile = '';
+let _startedAt = '';
 
 async function loadJson(path) {
   return JSON.parse(await readFile(path, 'utf8'));
@@ -320,6 +322,30 @@ export async function runQueueSymbolEnrichment({
   throw createQueueEnrichmentError(failure);
 }
 
+export function buildQueueState({ status, pid, startedAt, heartbeatAt, finishedAt = null, lastError = null, summary }) {
+  return {
+    status,
+    pid,
+    startedAt,
+    heartbeatAt,
+    finishedAt,
+    lastError,
+    summary: {
+      pending: summary?.pending ?? 0,
+      enriched: summary?.enriched ?? 0,
+      errors: summary?.errors ?? 0,
+    },
+  };
+}
+
+export async function writeQueueState(input) {
+  await saveJson(input.queueStateFile, buildQueueState(input));
+}
+
+export async function finalizeQueueState(input) {
+  await writeQueueState(input);
+}
+
 async function checkpointSave() {
   if (!_worklistFile) return;
   console.error('\n[checkpoint] Saving progress...');
@@ -371,6 +397,9 @@ async function main() {
   _worklist = worklist;
   _symbolIndex = symbolIndex;
 
+  const queueStateFile = resolve(enrichmentDir, 'queue-state.json');
+  _queueStateFile = queueStateFile;
+
   for (const entry of worklist) {
     if (entry.status === 'enriched' && entry.memoryId) {
       entry.status = 'already_enriched';
@@ -385,10 +414,29 @@ async function main() {
 
   if (pending.length === 0) {
     const summary = buildQueueSummary(worklist);
+    await finalizeQueueState({
+      queueStateFile,
+      status: 'finished',
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+      heartbeatAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+      summary,
+    });
     console.log(JSON.stringify({ complete: true, total, enriched: summary.enriched, errors: summary.errors }));
     return;
   }
 
+  _startedAt = new Date().toISOString();
+  await writeQueueState({
+    queueStateFile,
+    status: 'running',
+    pid: process.pid,
+    startedAt: _startedAt,
+    heartbeatAt: _startedAt,
+    summary: buildQueueSummary(worklist),
+  });
+
   console.error(`[queue] Starting continuous enrichment: ${pending.length} pending (${staleCount} stale), ${alreadyEnriched} already enriched, ${PMC_CONCURRENCY} parallel slots`);
   console.error(`[queue] Modes: ${enrichmentConfig.preferredModes.join(', ')} | Local: ${enrichmentConfig.localModel.baseUrl} | Model: ${enrichmentConfig.localModel.model} | Timeout: ${TIMEOUT_MS}ms per symbol\n`);
 
@@ -458,7 +506,7 @@ async function main() {
   await Promise.all(initPromises);
 
   await new Promise((resolve) => {
-    const checkInterval = setInterval(() => {
+    const checkInterval = setInterval(async () => {
       if (!tracker.hasActiveSlots() && queue.length === 0) {
         clearInterval(checkInterval);
         resolve();
@@ -468,6 +516,14 @@ async function main() {
         const active = tracker.activeCount();
         const done = results.length + errors.length;
         console.error(`[queue status] done=${done} active=${active} queued=${remaining} elapsed=${Math.round(elapsedTotal / 1000)}s`);
+        await writeQueueState({
+          queueStateFile,
+          status: 'running',
+          pid: process.pid,
+          startedAt: _startedAt,
+          heartbeatAt: new Date().toISOString(),
+          summary: buildQueueSummary(worklist),
+        }).catch(() => {});
       }
     }, REPORT_INTERVAL_MS);
   });
@@ -504,6 +560,17 @@ async function main() {
   const summary = buildQueueSummary(worklist);
   const avgTime = results.length > 0 ? results.reduce((a, r) => a + r.elapsed, 0) / results.length : 0;
 
+  const finishedAt = new Date().toISOString();
+  await finalizeQueueState({
+    queueStateFile,
+    status: 'finished',
+    pid: process.pid,
+    startedAt: _startedAt,
+    heartbeatAt: finishedAt,
+    finishedAt,
+    summary,
+  });
+
   console.log(JSON.stringify({
     complete: summary.pending === 0,
     total: worklist.length,
@@ -518,7 +585,21 @@ async function main() {
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  main().catch(err => {
+  main().catch(async (err) => {
+    try {
+      const summary = Array.isArray(_worklist) ? buildQueueSummary(_worklist) : { pending: 0, enriched: 0, errors: 0 };
+      const enrichmentDir = _enrichmentDir || resolve(PROJECT_ROOT, '.planning/project-memory-context/enrichment');
+      await finalizeQueueState({
+        queueStateFile: resolve(enrichmentDir, 'queue-state.json'),
+        status: 'failed',
+        pid: process.pid,
+        startedAt: _startedAt || new Date().toISOString(),
+        heartbeatAt: new Date().toISOString(),
+        finishedAt: new Date().toISOString(),
+        lastError: err.message,
+        summary,
+      });
+    } catch {}
     console.error('[fatal]', err.message);
     process.exit(1);
   });

package/cli/retry-errors.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { appendProviderEvent, withRecordedAttempt } from '../src/enrichment-attempts.mjs';
+import { resolveEnrichmentConfig, PMC_ENRICHMENT_CONFIG_FILE } from '../src/enrichment-config.mjs';
+import { runEnrichmentWithFallback } from '../src/enrichment-driver.mjs';
+import { createLocalModelProvider } from '../src/providers/local-model-provider.mjs';
+import { appendSyncEntry, createSyncEntry } from '../src/sync-manifest.mjs';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+async function loadJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+async function loadOptionalJson(path, fallback = null) {
+  try {
+    return await loadJson(path);
+  } catch {
+    return fallback;
+  }
+}
+
+async function saveJson(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+function safeKey(key) {
+  return key.replace(/[^a-zA-Z0-9_-]+/g, '_');
+}
+
+async function buildSymbolPrompt(symbol, projectRoot, maxCodeLines = 80) {
+  const absoluteFile = resolve(projectRoot, symbol.filePath);
+  const content = await readFile(absoluteFile, 'utf8');
+  const lines = content.split('\n');
+  const totalSymbolLines = symbol.range.endLine - symbol.range.startLine + 1;
+  let codeSection = lines.slice(symbol.range.startLine - 1, symbol.range.endLine).join('\n');
+  let truncated = false;
+  if (totalSymbolLines > maxCodeLines) {
+    const header = lines.slice(symbol.range.startLine - 1, symbol.range.startLine - 1 + Math.floor(maxCodeLines * 0.6)).join('\n');
+    const footer = lines.slice(symbol.range.endLine - Math.floor(maxCodeLines * 0.4), symbol.range.endLine).join('\n');
+    codeSection = header + '\n  // ... truncated ...\n' + footer;
+    truncated = true;
+  }
+  const importsSection = lines.slice(0, symbol.range.startLine - 1).filter(l => /^\s*import\b/.test(l) || /^\s*using\b/.test(l)).join('\n');
+  return `Symbol: ${symbol.name}\nKind: ${symbol.kind}\nLanguage: ${symbol.language}\nLocation: ${symbol.filePath}:${symbol.range.startLine}-${symbol.range.endLine}${truncated ? ` (truncated from ${totalSymbolLines} lines)` : ''}\n\nContext (imports):\n${importsSection || '(none)'}\n\nCode:\n${codeSection}\n\nReturn a compact structured explanation (max 150 words) with:\n- responsibility\n- primary inputs\n- output\n- immediate dependencies\n- role in module`;
+}
+
+function parseArgs(argv) {
+  const args = { concurrency: 4, timeoutMs: 600000, model: null, baseUrl: null, reportFile: null, limit: null };
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--concurrency' && argv[i + 1]) { args.concurrency = parseInt(argv[++i], 10); }
+    else if (arg === '--timeout' && argv[i + 1]) { args.timeoutMs = parseInt(argv[++i], 10); }
+    else if (arg === '--model' && argv[i + 1]) { args.model = argv[++i]; }
+    else if (arg === '--base-url' && argv[i + 1]) { args.baseUrl = argv[++i]; }
+    else if (arg === '--report' && argv[i + 1]) { args.reportFile = argv[++i]; }
+    else if (arg === '--limit' && argv[i + 1]) { args.limit = parseInt(argv[++i], 10); }
+    else if (arg === '--help' || arg === '-h') { args.help = true; }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+PMC Retry Errors — Re-enriches symbols that failed using Ollama directly
+
+Usage: node tools/project-memory-context/cli/retry-errors.mjs [options]
+
+Options:
+  --concurrency N     Parallel slots (default: 4)
+  --timeout MS        Timeout per symbol in ms (default: 600000 = 10min)
+  --model NAME        Ollama model name (default: from config)
+  --base-url URL      Ollama base URL (default: http://localhost:11434)
+  --limit N           Only retry first N error entries (default: all)
+  --report PATH       Save JSON report to file (default: .planning/.../retry-report.json)
+  -h, --help          Show this help
+`);
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const projectRoot = rawArgs.find(a => !a.startsWith('-')) || process.cwd();
+  const args = parseArgs(process.argv);
+  if (args.help) { printHelp(); return 0; }
+
+  const enrichmentDir = resolve(projectRoot, '.planning/project-memory-context/enrichment');
+  await mkdir(enrichmentDir, { recursive: true });
+
+  const worklistFile = resolve(enrichmentDir, 'worklist.json');
+  const symbolIndexFile = resolve(enrichmentDir, 'symbol-index.json');
+
+  let worklist;
+  try {
+    worklist = await loadJson(worklistFile);
+  } catch {
+    console.error('[retry] No worklist found.');
+    process.exit(1);
+  }
+
+  const errorEntries = worklist.filter(e => e.status === 'error');
+  if (errorEntries.length === 0) {
+    console.log('[retry] No error entries found in worklist. Nothing to retry.');
+    return;
+  }
+
+  if (args.limit && args.limit < errorEntries.length) {
+    console.error(`[retry] Limiting to first ${args.limit} of ${errorEntries.length} error entries`);
+    errorEntries.splice(args.limit);
+  }
+
+  let symbolIndex = {};
+  try { symbolIndex = await loadJson(symbolIndexFile); } catch {}
+
+  const projectConfig = await loadOptionalJson(resolve(projectRoot, '.opencode', PMC_ENRICHMENT_CONFIG_FILE));
+  const globalConfig = await loadOptionalJson(resolve(homedir(), '.config', 'opencode', PMC_ENRICHMENT_CONFIG_FILE));
+  let config = resolveEnrichmentConfig({ projectConfig, globalConfig, env: process.env });
+
+  config.preferredModes = ['local-model'];
+
+  if (args.model) {
+    config.localModel.model = args.model;
+  }
+  if (args.baseUrl) {
+    config.localModel.baseUrl = args.baseUrl;
+  }
+
+  const projectSlug = process.env.PMC_PROJECT_SLUG || basename(projectRoot);
+
+  const providers = [createLocalModelProvider()];
+
+  console.error(`\n[retry] ═════════════════════════════════════════════════════`);
+  console.error(`[retry] Retrying ${errorEntries.length} error symbols`);
+  console.error(`[retry] Provider: ${config.localModel.provider} | Model: ${config.localModel.model}`);
+  console.error(`[retry] Base URL: ${config.localModel.baseUrl}`);
+  console.error(`[retry] Concurrency: ${args.concurrency} | Timeout: ${args.timeoutMs / 1000}s`);
+  console.error(`[retry] ═════════════════════════════════════════════════════\n`);
+
+  const report = {
+    startedAt: new Date().toISOString(),
+    config: { model: config.localModel.model, baseUrl: config.localModel.baseUrl, concurrency: args.concurrency, timeoutMs: args.timeoutMs },
+    previousErrors: {},
+    results: [],
+    summary: { succeeded: 0, failed: 0, skipped: 0 },
+  };
+
+  for (const entry of errorEntries) {
+    const lastLocalAttempt = (entry.attempts ?? []).find(a => a.mode === 'local-model');
+    report.previousErrors[entry.symbolKey] = {
+      name: entry.name,
+      filePath: entry.filePath,
+      kind: entry.kind,
+      previousError: entry.error,
+      localModelError: lastLocalAttempt?.errorMessage ?? null,
+      localModelErrorType: lastLocalAttempt?.errorType ?? null,
+      attemptCount: entry.attempts?.length ?? 0,
+    };
+  }
+
+  const queue = [...errorEntries];
+  const activeSlots = new Map();
+  const results = [];
+  let slotIdCounter = 0;
+
+  async function dispatchSlot() {
+    while (queue.length > 0) {
+      const entry = queue.shift();
+
+      entry.status = 'pending';
+      delete entry.error;
+      delete entry.failedAt;
+
+      const slotId = slotIdCounter++;
+      const startTime = Date.now();
+
+      activeSlots.set(slotId, { entry, startTime });
+
+      try {
+        const prompt = await buildSymbolPrompt(entry, projectRoot);
+        const result = await runEnrichmentWithFallback({
+          request: { prompt, timeoutMs: args.timeoutMs },
+          config,
+          providers,
+          env: process.env,
+        });
+
+        const elapsed = Date.now() - startTime;
+        activeSlots.delete(slotId);
+
+        for (const attempt of result.attempts ?? []) {
+          await appendProviderEvent(enrichmentDir, { symbolKey: entry.symbolKey, name: entry.name, ...attempt });
+        }
+
+        const reportEntry = {
+          symbolKey: entry.symbolKey,
+          name: entry.name,
+          filePath: entry.filePath,
+          kind: entry.kind,
+          language: entry.language,
+          elapsedMs: elapsed,
+          attempts: result.attempts ?? [],
+        };
+
+        if (result.status === 'succeeded') {
+          const memoryId = `queue-${safeKey(entry.symbolKey)}`;
+          const enrichedAt = new Date().toISOString();
+          const memoryFile = resolve(enrichmentDir, `${safeKey(entry.symbolKey)}.memory.json`);
+
+          await saveJson(memoryFile, {
+            content: result.content,
+            category: 'architecture',
+            tags: ['symbol', entry.language, entry.kind, `project:${projectSlug}`, `file:${entry.filePath}`],
+          });
+
+          const newAttempts = [...(entry.attempts ?? []), ...(result.attempts ?? [])];
+          Object.assign(entry, {
+            status: 'enriched',
+            memoryId,
+            enrichedAt,
+            error: undefined,
+            failedAt: undefined,
+            attempts: newAttempts,
+            lastModeUsed: 'local-model',
+          });
+
+          symbolIndex[entry.symbolKey] = {
+            memoryId,
+            graphNodeId: entry.graphNodeId ?? null,
+            codeHash: entry.codeHash,
+            status: 'enriched',
+            lastEnrichedAt: enrichedAt,
+          };
+
+          try {
+            await appendSyncEntry(enrichmentDir, createSyncEntry({
+              action: 'upsert',
+              keyTag: `key:symbol:${safeKey(entry.symbolKey)}`,
+              content: `## ${entry.name}\n\n${result.content}`,
+              category: 'architecture',
+              tags: ['symbol', entry.language, entry.kind, `project:${projectSlug}`, `file:${entry.filePath}`, 'enriched-by-retry'],
+              source: 'retry-errors',
+              symbolKey: entry.symbolKey,
+            }));
+          } catch (syncErr) {
+            console.error(`[retry] WARN: sync append failed for ${entry.name}: ${syncErr.message}`);
+          }
+
+          reportEntry.status = 'succeeded';
+          reportEntry.contentPreview = result.content?.substring(0, 200);
+          reportEntry.memoryId = memoryId;
+          report.summary.succeeded++;
+
+          const done = report.summary.succeeded + report.summary.failed;
+          console.error(`  [OK] ${entry.name} (${entry.filePath}:${entry.range.startLine}) — ${Math.round(elapsed / 1000)}s [${done}/${errorEntries.length}]`);
+        } else {
+          const lastError = result.attempts?.find(a => a.errorMessage)?.errorMessage ?? 'all providers failed';
+
+          const newAttempts = [...(entry.attempts ?? []), ...(result.attempts ?? [])];
+          Object.assign(entry, {
+            status: 'error',
+            error: lastError,
+            failedAt: new Date().toISOString(),
+            attempts: newAttempts,
+          });
+
+          symbolIndex[entry.symbolKey] = {
+            memoryId: null,
+            graphNodeId: entry.graphNodeId ?? null,
+            codeHash: entry.codeHash,
+            status: 'error',
+            lastEnrichedAt: new Date().toISOString(),
+          };
+
+          reportEntry.status = 'failed';
+          reportEntry.failureReason = lastError;
+          report.summary.failed++;
+
+          const done = report.summary.succeeded + report.summary.failed;
+          console.error(`  [FAIL] ${entry.name} (${entry.filePath}:${entry.range.startLine}) — ${lastError} — ${Math.round(elapsed / 1000)}s [${done}/${errorEntries.length}]`);
+        }
+
+        results.push(reportEntry);
+      } catch (err) {
+        const elapsed = Date.now() - startTime;
+        activeSlots.delete(slotId);
+
+        entry.status = 'error';
+        entry.error = err.message;
+        entry.failedAt = new Date().toISOString();
+
+        const reportEntry = {
+          symbolKey: entry.symbolKey,
+          name: entry.name,
+          filePath: entry.filePath,
+          kind: entry.kind,
+          language: entry.language,
+          elapsedMs: elapsed,
+          status: 'failed',
+          failureReason: err.message,
+          attempts: [],
+        };
+
+        results.push(reportEntry);
+        report.summary.failed++;
+
+        const done = report.summary.succeeded + report.summary.failed;
+        console.error(`  [ERR] ${entry.name} — ${err.message} — ${Math.round(elapsed / 1000)}s [${done}/${errorEntries.length}]`);
+      }
+
+      await saveJson(worklistFile, worklist);
+      await saveJson(symbolIndexFile, symbolIndex);
+    }
+  }
+
+  const slots = [];
+  for (let i = 0; i < args.concurrency; i++) {
+    slots.push(dispatchSlot());
+  }
+  await Promise.all(slots);
+
+  report.results = results;
+  report.finishedAt = new Date().toISOString();
+  report.totalElapsedMs = results.reduce((a, r) => a + (r.elapsedMs ?? 0), 0);
+
+  const reportPath = args.reportFile || resolve(enrichmentDir, 'retry-report.json');
+  await saveJson(reportPath, report);
+
+  console.error(`\n[retry] ═════════════════════════════════════════════════════`);
+  console.error(`[retry] DONE — ${report.summary.succeeded} succeeded, ${report.summary.failed} failed, ${report.summary.skipped} skipped`);
+  console.error(`[retry] Report: ${reportPath}`);
+  console.error(`[retry] ═════════════════════════════════════════════════════\n`);
+
+  console.log(JSON.stringify({
+    ok: true,
+    command: 'retry-errors',
+    total: errorEntries.length,
+    succeeded: report.summary.succeeded,
+    failed: report.summary.failed,
+    reportPath,
+  }, null, 2));
+
+  return report.summary.failed > 0 ? 1 : 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const exitCode = await main().catch(err => {
+    console.error('[retry] FATAL:', err.message);
+    return 1;
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aabadin/project-memory-context",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Portable project memory context CLI — bootstraps semantic enrichment workflows for any AI coding agent.",
   "license": "GPL-3.0-or-later",
   "type": "module",

package/src/command-dispatch.mjs

@@ -15,6 +15,7 @@ const COMMANDS = new Map([
   ['new-project', 'cli/new-project.mjs'],
   ['project-context', 'cli/project-context.mjs'],
   ['query', 'cli/query.mjs'],
+  ['retry-errors', 'cli/retry-errors.mjs'],
   ['sanitize', 'cli/sanitize.mjs'],
   ['setup', 'cli/setup.mjs'],
   ['status', 'cli/status.mjs'],

package/templates/claude-code/CLAUDE.md.snippet

@@ -53,7 +53,14 @@ When the user types `/sanitize`, run:
 When starting a session in a project with `.planning/project-memory-context/`:
 
 1. Check `.planning/project-memory-context/enrichment/worklist.json` for pending or stale entries.
-2. If pending/stale entries exist, launch background enrichment: `{{PMC_BIN}} enrich .`
+2. If pending/stale entries exist, launch background enrichment:
+   ```powershell
+   if (Test-Path "tools/project-memory-context/cli/enrich-queue.mjs") {
+     Start-Process -FilePath "node" -ArgumentList "tools/project-memory-context/cli/enrich-queue.mjs" -WindowStyle Hidden
+   } else {
+     Start-Process -FilePath "npx" -ArgumentList "--yes","--package","@aabadin/project-memory-context","pmc-enrich","." -WindowStyle Hidden
+   }
+   ```
 3. Check `.planning/project-memory-context/enrichment/sync-manifest.json` for pending entries.
 4. If sync-manifest has pending entries, inform the user: "PMC has {n} pending sync operations. Run `/sync-context` to apply them."
 5. Search agent-memory with `query: "project context overview"` and `tags: ["project-context"]` to fetch base context.

package/templates/cursor/.cursorrules.snippet

@@ -53,7 +53,14 @@ When the user types "/sanitize", run:
 When starting a session in a project with `.planning/project-memory-context/`:
 
 1. Check `.planning/project-memory-context/enrichment/worklist.json` for pending or stale entries.
-2. If pending/stale entries exist, launch background enrichment: `{{PMC_BIN}} enrich .`
+2. If pending/stale entries exist, launch background enrichment:
+   ```powershell
+   if (Test-Path "tools/project-memory-context/cli/enrich-queue.mjs") {
+     Start-Process -FilePath "node" -ArgumentList "tools/project-memory-context/cli/enrich-queue.mjs" -WindowStyle Hidden
+   } else {
+     Start-Process -FilePath "npx" -ArgumentList "--yes","--package","@aabadin/project-memory-context","pmc-enrich","." -WindowStyle Hidden
+   }
+   ```
 3. Check `.planning/project-memory-context/enrichment/sync-manifest.json` for pending entries.
 4. If sync-manifest has pending entries, inform the user: "PMC has {n} pending sync operations. Run /sync-context to apply them."
 5. Search agent-memory with query "project context overview" and tags ["project-context"] to fetch base context.