@aabadin/project-memory-context 0.1.5 → 0.2.0

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/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);
+  }
+}

package/cli/status.mjs

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url';
 
 import { detectAgentType, resolveConfigDirs } from '../src/platform.mjs';
 
+const DEFAULT_STALE_AFTER_SECONDS = 90;
+
 export function summarizeWorklist(worklist) {
   return {
     pending: worklist.filter((e) => e.status === 'pending' || e.status === 'stale').length,
@@ -21,6 +23,52 @@ async function readJsonSafe(filePath) {
   }
 }
 
+function toIsoString(value) {
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function heartbeatIsFresh(heartbeatAt, now, staleAfterSeconds = DEFAULT_STALE_AFTER_SECONDS) {
+  if (!heartbeatAt) return false;
+  const heartbeat = new Date(heartbeatAt).getTime();
+  const current = new Date(now).getTime();
+  if (!Number.isFinite(heartbeat) || !Number.isFinite(current)) return false;
+  return current - heartbeat <= staleAfterSeconds * 1000;
+}
+
+function deriveRuntimeState(queueState, now, staleAfterSeconds = DEFAULT_STALE_AFTER_SECONDS) {
+  if (!queueState || typeof queueState !== 'object') {
+    return { state: 'idle', runtime: null };
+  }
+
+  const runtime = {
+    pid: Number.isInteger(queueState.pid) ? queueState.pid : null,
+    startedAt: toIsoString(queueState.startedAt),
+    heartbeatAt: toIsoString(queueState.heartbeatAt),
+    finishedAt: toIsoString(queueState.finishedAt),
+    staleAfterSeconds,
+    lastError: queueState.lastError ?? null,
+  };
+
+  if (queueState.status === 'finished') {
+    return { state: 'finished', runtime };
+  }
+
+  if (queueState.status === 'failed') {
+    return { state: 'failed', runtime };
+  }
+
+  if (queueState.status === 'running') {
+    return {
+      state: heartbeatIsFresh(runtime.heartbeatAt, now, staleAfterSeconds) ? 'running' : 'stalled',
+      runtime,
+    };
+  }
+
+  return { state: 'idle', runtime: null };
+}
+
 async function getLastSyncTimestamp(enrichmentDir) {
   const syncManifest = join(enrichmentDir, 'sync-manifest.json');
   try {
@@ -31,16 +79,20 @@ async function getLastSyncTimestamp(enrichmentDir) {
   }
 }
 
-export async function buildStatusReport({ projectRoot = process.cwd() } = {}) {
+export async function buildStatusReport({ projectRoot = process.cwd(), now = new Date().toISOString() } = {}) {
   const dirs = resolveConfigDirs(projectRoot);
   const planningDir = join(projectRoot, '.planning', 'project-memory-context');
   const enrichmentDir = join(planningDir, 'enrichment');
   const worklistPath = join(enrichmentDir, 'worklist.json');
   const installStatePath = join(planningDir, 'install.json');
+  const queueStatePath = join(enrichmentDir, 'queue-state.json');
 
   const worklist = await readJsonSafe(worklistPath);
   const installState = await readJsonSafe(installStatePath);
+  const queueState = await readJsonSafe(queueStatePath);
   const lastSync = await getLastSyncTimestamp(enrichmentDir);
+  const { state, runtime } = deriveRuntimeState(queueState, now);
+  const worklistSummary = Array.isArray(worklist) ? summarizeWorklist(worklist) : null;
 
   return {
     ok: true,
@@ -49,7 +101,9 @@ export async function buildStatusReport({ projectRoot = process.cwd() } = {}) {
     configLocation: dirs.projectConfig,
     agentType: detectAgentType(projectRoot),
     installState: installState ? { installedAt: installState.installedAt, version: installState.version } : null,
-    worklist: worklist ? summarizeWorklist(worklist) : null,
+    state,
+    runtime,
+    worklist: worklistSummary,
     lastSync,
   };
 }

package/mcp/pmc-query-server.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { createQueryOrchestrator } from '../src/query/orchestrator.mjs';
+
+const projectRoot = process.env.PMC_PROJECT_ROOT || process.cwd();
+const orchestrator = createQueryOrchestrator({ projectRoot });
+
+function textResult(value) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+  };
+}
+
+function errorResult(toolName, error) {
+  return {
+    content: [{ type: 'text', text: `${toolName} failed: ${String(error)}` }],
+    isError: true,
+  };
+}
+
+const server = new McpServer({
+  name: 'pmc-query',
+  version: '0.1.5',
+});
+
+server.tool(
+  'pmc_query_project',
+  'Query PMC project context and symbol artifacts using a natural-language question.',
+  {
+    question: z.string().describe('Natural-language project question'),
+  },
+  async ({ question }) => {
+    try {
+      return textResult(await orchestrator.query(question));
+    } catch (error) {
+      return errorResult('pmc_query_project', error);
+    }
+  },
+);
+
+server.tool(
+  'pmc_search_symbols',
+  'Search PMC symbols by semantic summary and optional file path filter.',
+  {
+    query: z.string().describe('Search query for symbols'),
+    file: z.string().optional().describe('Optional normalized file path filter'),
+  },
+  async ({ query, file }) => {
+    try {
+      return textResult(await orchestrator.searchSymbols(query, file));
+    } catch (error) {
+      return errorResult('pmc_search_symbols', error);
+    }
+  },
+);
+
+server.tool(
+  'pmc_get_dependents',
+  'List symbols that depend on the given symbol key.',
+  {
+    symbol: z.string().describe('Normalized PMC symbol key'),
+  },
+  async ({ symbol }) => {
+    try {
+      return textResult(await orchestrator.getDependents(symbol));
+    } catch (error) {
+      return errorResult('pmc_get_dependents', error);
+    }
+  },
+);
+
+server.tool(
+  'pmc_get_dependencies',
+  'List symbols the given symbol key depends on.',
+  {
+    symbol: z.string().describe('Normalized PMC symbol key'),
+  },
+  async ({ symbol }) => {
+    try {
+      return textResult(await orchestrator.getDependencies(symbol));
+    } catch (error) {
+      return errorResult('pmc_get_dependencies', error);
+    }
+  },
+);
+
+await server.connect(new StdioServerTransport());