@aabadin/project-memory-context 0.1.5 → 0.2.1

package/cli/context.mjs

@@ -1,12 +1,211 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { dirname, resolve } from 'node:path';
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const SCRIPT_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'project-context.mjs');
+import { readJsonArtifact } from '../src/artifacts.mjs';
+import { createQueryEngine, focusToEdgeTypes } from '../src/retrieval/query-engine.mjs';
+import { resolveTarget } from '../src/retrieval/target-resolver.mjs';
+import { renderTargetContext } from '../src/retrieval/context-renderer-v1.mjs';
 
-function printHelp() {
-  console.log('Usage: pmc context [project-root] [--refresh]');
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function findProjectRoot(startDir = process.cwd()) {
+  let currentDir = resolve(startDir);
+
+  while (true) {
+    const installPath = join(currentDir, '.planning', 'project-memory-context', 'install.json');
+    if (await fileExists(installPath)) {
+      return currentDir;
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+
+    currentDir = parentDir;
+  }
+}
+
+export function parseArgs(args) {
+  const DEPTH_VALUES = ['compact', 'extended', 'deep', 'disk'];
+  const FOCUS_VALUES = ['dependencies', 'callers', 'containment', 'impact', 'all'];
+  const EXPLICIT_MODES = ['symbol', 'file', 'query'];
+
+  let explicitMode = null;
+  let target = undefined;
+  let depth = 'compact';
+  let focus = 'all';
+  let refresh = false;
+  let help = false;
+  const positional = [];
+
+  for (const arg of args) {
+    if (arg === '--help' || arg === '-h') {
+      help = true;
+      continue;
+    }
+
+    if (arg === '--refresh') {
+      refresh = true;
+      continue;
+    }
+
+    if (EXPLICIT_MODES.includes(arg) && explicitMode === null && positional.length === 0) {
+      explicitMode = arg;
+      continue;
+    }
+
+    if (DEPTH_VALUES.includes(arg)) {
+      depth = arg;
+      continue;
+    }
+
+    if (FOCUS_VALUES.includes(arg)) {
+      focus = arg;
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  if (positional.length > 0) {
+    target = positional[0];
+  }
+
+  return { explicitMode, target, depth, focus, refresh, help };
+}
+
+export async function loadArtifacts(projectRoot) {
+  const pmcRoot = join(projectRoot, '.planning', 'project-memory-context');
+  try {
+    const [graph, symbolIndex, worklist] = await Promise.all([
+      readJsonArtifact(join(pmcRoot, 'graph', 'graph.json'), { nodes: [], links: [] }),
+      readJsonArtifact(join(pmcRoot, 'enrichment', 'symbol-index.json'), {}),
+      readJsonArtifact(join(pmcRoot, 'enrichment', 'worklist.json'), []),
+    ]);
+    return { graph, symbolIndex, worklist };
+  } catch (error) {
+    throw new Error(`Failed to load PMC artifacts from ${pmcRoot}: ${error.message}`);
+  }
+}
+
+function groupEdges(edges, edgeTypes) {
+  const byKind = new Map();
+  for (const edge of edges) {
+    if (!edgeTypes.includes(edge.relation)) continue;
+    const kind = edge.relation;
+    const arr = byKind.get(kind);
+    if (arr) {
+      arr.push(edge.target);
+    } else {
+      byKind.set(kind, [edge.target]);
+    }
+  }
+
+  const result = [];
+  for (const [kind, items] of byKind) {
+    result.push({ kind, items });
+  }
+
+  return result;
+}
+
+export function buildRenderInput(engine, resolved, { depth, focus }) {
+  const edgeTypes = focusToEdgeTypes(focus);
+  let summary = [];
+  let target = {};
+  let relevant = [];
+  let relations = [];
+  let nextReads = [];
+
+  switch (resolved.mode) {
+    case 'symbol': {
+      const ctx = engine.querySymbolContext({ symbolKey: resolved.symbolKey, depth });
+      target = { mode: 'symbol', name: ctx.target?.name, filePath: ctx.target?.filePath };
+      summary = [`Symbol: ${ctx.target?.name || resolved.target} (${ctx.target?.kind || 'unknown'})`];
+      relevant = (ctx.neighbors || []).map((n) => ({
+        label: n.name || n.label || 'unknown',
+        filePath: n.filePath || undefined,
+      }));
+      relations = groupEdges(ctx.edges || [], edgeTypes);
+      nextReads = relevant.map((r) => r.filePath).filter(Boolean);
+      break;
+    }
+    case 'symbol-ambiguous': {
+      target = { mode: 'symbol-ambiguous', name: resolved.target };
+      summary = [`Multiple symbols match "${resolved.target}".`];
+      relevant = (resolved.symbolKeys || []).map((sk) => {
+        const parts = sk.split('|');
+        return {
+          label: parts.length >= 6 ? parts[parts.length - 2] : sk,
+          filePath: parts.length >= 2 ? parts[1] : undefined,
+        };
+      });
+      break;
+    }
+    case 'file': {
+      const ctx = engine.queryFileContext({ filePath: resolved.target, depth });
+      target = { mode: 'file', filePath: resolved.target };
+      summary = ctx.symbols && ctx.symbols.length > 0
+        ? ctx.symbols.map((s) => `${s.name || 'unknown'} (${s.kind || 'symbol'})`)
+        : [`File: ${resolved.target}`];
+      relevant = (ctx.neighbors || []).map((n) => ({
+        label: n.name || n.label || 'unknown',
+        filePath: n.filePath || undefined,
+      }));
+      relations = groupEdges(ctx.edges || [], edgeTypes);
+      nextReads = relevant.map((r) => r.filePath).filter(Boolean);
+      break;
+    }
+    case 'query':
+      target = { mode: 'query', value: resolved.target };
+      summary = [`Query: ${resolved.target} (no structural context available)`];
+      break;
+    case 'symbol-missing':
+      target = { mode: 'symbol-missing', name: resolved.target };
+      summary = [`Symbol "${resolved.target}" not found in project index.`];
+      break;
+    default:
+      target = { mode: resolved.mode || 'unknown', value: resolved.target };
+      summary = [`Unrecognized target mode: ${resolved.mode}`];
+      break;
+  }
+
+  return {
+    summary,
+    target,
+    relevant,
+    relations,
+    nextReads,
+    metadata: { depth, focus },
+  };
+}
+
+export async function runTargetContext({ projectRoot, target, explicitMode, depth, focus }) {
+  const artifacts = await loadArtifacts(projectRoot);
+  const engine = createQueryEngine({
+    graph: artifacts.graph,
+    symbolIndex: artifacts.symbolIndex,
+    worklist: artifacts.worklist,
+    enrichmentDir: join(projectRoot, '.planning', 'project-memory-context', 'enrichment'),
+    projectSlug: 'project',
+  });
+
+  const resolved = resolveTarget({ engine, explicitMode, target });
+
+  const input = buildRenderInput(engine, resolved, { depth, focus });
+  const output = renderTargetContext(input);
+
+  return { output, resolved, input };
 }
 
 export async function runProjectContext(projectRoot = process.cwd(), refresh = false) {
@@ -14,27 +213,104 @@ export async function runProjectContext(projectRoot = process.cwd(), refresh = f
   if (typeof mod.runProjectContextCli === 'function') {
     return mod.runProjectContextCli(projectRoot, { refresh });
   }
+
   return null;
 }
 
+function printHelp() {
+  console.log('Usage: pmc context [options] [<target>]');
+  console.log('       pmc context {symbol|file|query} <target> [depth] [focus]');
+  console.log('');
+  console.log('Get structural context about symbols, files, or free-text queries');
+  console.log('from the PMC project graph.');
+  console.log('');
+  console.log('Modes:');
+  console.log('  symbol   Resolve a symbol by name');
+  console.log('  file     Query context for a file path');
+  console.log('  query    Free-text query (structural only)');
+  console.log('');
+  console.log('Options:');
+  console.log('  depth    compact (default), extended, deep, disk');
+  console.log('  focus    all (default), dependencies, callers, containment, impact');
+  console.log('  --refresh  Run project-context detection and materialization');
+  console.log('  --help, -h Show this help');
+  console.log('');
+  console.log('Examples:');
+  console.log('  pmc context createQueryEngine');
+  console.log('  pmc context symbol MyFunc extended dependencies');
+  console.log('  pmc context file src/auth.ts deep callers');
+  console.log('  pmc context query "how auth works"');
+  console.log('  pmc context . --refresh');
+}
+
 export async function main(args = process.argv.slice(2)) {
-  if (args.includes('--help') || args.includes('-h')) {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
     printHelp();
     return 0;
   }
 
-  return await new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn(process.execPath, [SCRIPT_PATH, ...args], { stdio: 'inherit' });
-    child.once('error', rejectPromise);
-    child.once('exit', (code, signal) => {
-      if (signal) {
-        rejectPromise(new Error(`context exited from signal ${signal}`));
-        return;
+  if (parsed.refresh) {
+    let projectRoot;
+
+    if (parsed.target && parsed.target !== '.') {
+      const looksValid = /^[A-Za-z]:[\\/]/.test(parsed.target)
+        || /^[\\/]/.test(parsed.target)
+        || /^\.{2}[\\/]?/.test(parsed.target);
+
+      if (looksValid) {
+        projectRoot = resolve(parsed.target);
+      } else {
+        console.error(
+          `[context] --refresh does not accept a non-path target "${parsed.target}".`,
+          'Use . --refresh to refresh from cwd, or omit the target entirely.',
+        );
+        return 1;
       }
+    } else {
+      projectRoot = await findProjectRoot();
+    }
+
+    if (!projectRoot) {
+      console.error('[context] Not inside a PMC-enabled project.');
+      return 1;
+    }
 
-      resolvePromise(code ?? 0);
-    });
+    try {
+      return await runProjectContext(projectRoot, true);
+    } catch (error) {
+      console.error(`[context] Refresh failed: ${error.message}`);
+      return 1;
+    }
+  }
+
+  if (!parsed.target) {
+    if (parsed.explicitMode) {
+      console.error(`[context] Missing target for ${parsed.explicitMode} mode.`);
+      return 1;
+    }
+
+    printHelp();
+    return 0;
+  }
+
+  const projectRoot = await findProjectRoot();
+  if (!projectRoot) {
+    console.error('[context] Not inside a PMC-enabled project (no install.json found).');
+    return 1;
+  }
+
+  const { output } = await runTargetContext({
+    projectRoot,
+    target: parsed.target,
+    explicitMode: parsed.explicitMode,
+    depth: parsed.depth,
+    focus: parsed.focus,
   });
+
+  console.log(output);
+  return 0;
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

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/install-pmc.mjs

@@ -59,11 +59,16 @@ function copyTemplatesDir(srcTemplates, dstTemplates) {
 export function installPmcTools({ sourceRoot, targetRoot }) {
   const srcCli = resolve(sourceRoot, 'cli');
   const srcSrc = resolve(sourceRoot, 'src');
+  const srcMcp = resolve(sourceRoot, 'mcp');
+  const srcPlugin = resolve(sourceRoot, 'plugin');
   const srcTemplates = resolve(sourceRoot, 'templates');
+  const srcPackageJson = resolve(sourceRoot, 'package.json');
 
   const dstBase = resolve(targetRoot, 'tools', 'project-memory-context');
   const dstCli = resolve(dstBase, 'cli');
   const dstSrc = resolve(dstBase, 'src');
+  const dstMcp = resolve(dstBase, 'mcp');
+  const dstPlugin = resolve(dstBase, 'plugin');
   const dstTemplates = resolve(dstBase, 'templates');
 
   mkdirSync(dstBase, { recursive: true });
@@ -85,15 +90,30 @@ export function installPmcTools({ sourceRoot, targetRoot }) {
     srcFiles = copyMjsTree(srcSrc, dstSrc);
   }
 
+  if (existsSync(srcMcp)) {
+    copyMjsTree(srcMcp, dstMcp);
+  }
+
+  if (existsSync(srcPlugin)) {
+    copyMjsTree(srcPlugin, dstPlugin);
+  }
+
+  if (existsSync(srcPackageJson)) {
+    copyFileSync(srcPackageJson, resolve(dstBase, 'package.json'));
+  }
+
   templateFiles = copyTemplatesDir(srcTemplates, dstTemplates);
 
   const planningBase = resolve(targetRoot, '.planning', 'project-memory-context');
+  const memoryDbPath = resolve(planningBase, 'memory-db');
   for (const sub of ['intake', 'graph', 'enrichment', 'memory-db', 'db']) {
     mkdirSync(resolve(planningBase, sub), { recursive: true });
   }
 
   const installState = {
     installedAt: new Date().toISOString(),
+    memoryDbPath,
+    projectRoot: resolve(targetRoot),
     sourceRoot: resolve(sourceRoot),
     version: '0.1.0',
   };

package/cli/query.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createQueryOrchestrator } from '../src/query/orchestrator.mjs';
+
+function printHelp() {
+  console.log('Usage: pmc query <question> [--format text|json]');
+  console.log('');
+  console.log('Queries PMC project-context and symbol artifacts from the current project.');
+  console.log('Use --format json for machine-readable output.');
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findProjectRoot(startDir = process.cwd()) {
+  let currentDir = resolve(startDir);
+
+  while (true) {
+    const installPath = join(currentDir, '.planning', 'project-memory-context', 'install.json');
+    if (await fileExists(installPath)) {
+      return currentDir;
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+
+    currentDir = parentDir;
+  }
+}
+
+function parseArgs(args) {
+  let format = 'text';
+  const questionParts = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--format') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('-')) {
+        throw new Error('Missing value for --format. Expected text or json.');
+      }
+
+      format = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      throw new Error(`Unknown flag: ${arg}`);
+    }
+
+    questionParts.push(arg);
+  }
+
+  return {
+    format,
+    question: questionParts.join(' ').trim(),
+  };
+}
+
+function formatSource(source) {
+  if (source.type === 'project-context') {
+    return `- [project-context] ${source.title} (${source.path})`;
+  }
+
+  return `- [symbol] ${source.symbolKey} (${source.filePath})`;
+}
+
+function printTextResult(result) {
+  console.log(result.answer);
+  console.log('');
+  console.log('Sources:');
+  if (result.sources.length === 0) {
+    console.log('- none');
+  } else {
+    for (const source of result.sources) {
+      console.log(formatSource(source));
+    }
+  }
+  console.log(`tokens_saved: ${result.tokens_saved}`);
+}
+
+export async function main(args = process.argv.slice(2)) {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return 0;
+  }
+
+  const { format, question } = parseArgs(args);
+  if (format !== 'text' && format !== 'json') {
+    throw new Error(`Unsupported format: ${format}`);
+  }
+
+  if (!question) {
+    printHelp();
+    return 1;
+  }
+
+  const projectRoot = await findProjectRoot(process.cwd());
+  if (!projectRoot) {
+    throw new Error('pmc query must be run inside a PMC-enabled project (missing .planning/project-memory-context/install.json).');
+  }
+
+  const orchestrator = createQueryOrchestrator({ projectRoot });
+  const result = await orchestrator.query(question);
+
+  if (format === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  printTextResult(result);
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const exitCode = await main().catch((error) => {
+    console.error('[query] FATAL:', error.message);
+    return 1;
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}