@aabadin/project-memory-context 0.1.0

package/cli/fail-enrichment.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+
+import { recordEnrichmentFailure } from '../src/fail-enrichment.mjs';
+
+const [, , symbolKey, errorMessage, failedAtArg] = process.argv;
+
+if (!symbolKey || !errorMessage) {
+  console.error('Usage: node fail-enrichment.mjs <symbol-key> <error-message> [failed-at]');
+  process.exit(1);
+}
+
+const projectRoot = resolve(process.cwd());
+const failedAt = failedAtArg ?? new Date().toISOString();
+const failed = await recordEnrichmentFailure({
+  projectRoot,
+  symbolKey,
+  error: errorMessage,
+  failedAt,
+});
+
+console.log(JSON.stringify({
+  saved: true,
+  worklistFile: failed.worklistFile,
+  failuresFile: failed.failuresFile,
+  symbolKey,
+  failedAt,
+}, null, 2));

package/cli/finalize-enrichment.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+
+import { finalizeEnrichment } from '../src/finalize-enrichment.mjs';
+import { loadResultInput } from '../src/result-input.mjs';
+
+const [, , rawResultInput] = process.argv;
+
+if (!rawResultInput) {
+  console.error('Usage: node finalize-enrichment.mjs <result-json|@result-file>');
+  process.exit(1);
+}
+
+const projectRoot = resolve(process.cwd());
+const result = await loadResultInput(rawResultInput);
+const finalized = await finalizeEnrichment({ projectRoot, result });
+
+console.log(JSON.stringify({
+  saved: true,
+  graphFile: finalized.graphFile,
+  indexFile: finalized.indexFile,
+  worklistFile: finalized.worklistFile,
+  symbolKey: result.symbolKey,
+  status: result.status,
+}, null, 2));

package/cli/init.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveConfigDirs } from '../src/platform.mjs';
+import { detectAgentType, installAgentTemplates } from '../src/template-installer.mjs';
+
+function parseArgs(args) {
+  const result = { agent: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--agent' && args[i + 1]) {
+      result.agent = args[++i];
+    }
+  }
+  return result;
+}
+
+function printHelp() {
+  console.log(`Usage: pmc init [--agent opencode|claude-code|cursor|generic]
+
+Options:
+  --agent <type>   Agent type to initialize. Auto-detected if omitted.
+
+Supported agents:
+  opencode         OpenCode (commands + agents + AGENTS.md autostart)
+  claude-code      Claude Code (CLAUDE.md instructions)
+  cursor           Cursor (.cursorrules instructions)
+  generic          Generic CLI-only (README-SETUP.md)`);
+}
+
+export async function main(args = process.argv.slice(2)) {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return 0;
+  }
+
+  const projectRoot = resolve(process.cwd());
+  const { agent: requestedAgent } = parseArgs(args);
+  const agent = requestedAgent || detectAgentType(projectRoot);
+
+  if (requestedAgent === null) {
+    console.error(`[pmc:init] Auto-detected agent: ${agent}`);
+  }
+
+  const { globalConfig } = resolveConfigDirs(projectRoot);
+
+  await installAgentTemplates({
+    projectRoot,
+    agent,
+    globalConfigDir: agent === 'opencode' ? globalConfig : undefined,
+  });
+
+  console.error(`[pmc:init] Installed PMC templates for ${agent}`);
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const exitCode = await main().catch((error) => {
+    console.error('[pmc:init] FATAL:', error.message);
+    return 1;
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}

package/cli/install-pmc.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  readdirSync,
+  mkdirSync,
+  copyFileSync,
+  writeFileSync,
+  existsSync,
+} from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SOURCE_ROOT = resolve(__dirname, '..');
+
+function log(msg) {
+  console.error(`[install-pmc] ${msg}`);
+}
+
+function copyMjsTree(srcDir, dstDir, opts = {}) {
+  const { skipPatterns = [] } = opts;
+  mkdirSync(dstDir, { recursive: true });
+  const entries = readdirSync(srcDir, { withFileTypes: true });
+  let copied = 0;
+
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'db') continue;
+    if (entry.name.endsWith('.test.mjs')) continue;
+    if (skipPatterns.some(p => entry.name.includes(p))) continue;
+
+    const srcPath = join(srcDir, entry.name);
+    const dstPath = join(dstDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copied += copyMjsTree(srcPath, dstPath, opts);
+    } else if (entry.isFile() && entry.name.endsWith('.mjs')) {
+      copyFileSync(srcPath, dstPath);
+      copied++;
+    }
+  }
+
+  return copied;
+}
+
+function copyTemplatesDir(srcTemplates, dstTemplates) {
+  if (!existsSync(srcTemplates)) return 0;
+  mkdirSync(dstTemplates, { recursive: true });
+  const entries = readdirSync(srcTemplates, { withFileTypes: true });
+  let copied = 0;
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    copyFileSync(join(srcTemplates, entry.name), join(dstTemplates, entry.name));
+    copied++;
+  }
+
+  return copied;
+}
+
+export function installPmcTools({ sourceRoot, targetRoot }) {
+  const srcCli = resolve(sourceRoot, 'cli');
+  const srcSrc = resolve(sourceRoot, 'src');
+  const srcTemplates = resolve(sourceRoot, 'templates');
+
+  const dstBase = resolve(targetRoot, 'tools', 'project-memory-context');
+  const dstCli = resolve(dstBase, 'cli');
+  const dstSrc = resolve(dstBase, 'src');
+  const dstTemplates = resolve(dstBase, 'templates');
+
+  mkdirSync(dstBase, { recursive: true });
+  mkdirSync(dstCli, { recursive: true });
+
+  let cliFiles = 0;
+  let srcFiles = 0;
+  let templateFiles = 0;
+
+  const cliEntries = readdirSync(srcCli, { withFileTypes: true });
+  for (const entry of cliEntries) {
+    if (!entry.isFile() || !entry.name.endsWith('.mjs')) continue;
+    if (entry.name.endsWith('.test.mjs')) continue;
+    copyFileSync(join(srcCli, entry.name), join(dstCli, entry.name));
+    cliFiles++;
+  }
+
+  if (existsSync(srcSrc)) {
+    srcFiles = copyMjsTree(srcSrc, dstSrc);
+  }
+
+  templateFiles = copyTemplatesDir(srcTemplates, dstTemplates);
+
+  const planningBase = resolve(targetRoot, '.planning', 'project-memory-context');
+  for (const sub of ['intake', 'graph', 'enrichment', 'memory-db', 'db']) {
+    mkdirSync(resolve(planningBase, sub), { recursive: true });
+  }
+
+  const installState = {
+    installedAt: new Date().toISOString(),
+    sourceRoot: resolve(sourceRoot),
+    version: '0.1.0',
+  };
+
+  writeFileSync(
+    resolve(planningBase, 'install.json'),
+    `${JSON.stringify(installState, null, 2)}\n`,
+    'utf8'
+  );
+
+  return { cliFiles, srcFiles, templateFiles };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+install-pmc - Copy PMC tools into a target project
+
+Usage:
+  node install-pmc.mjs [target-project-dir]
+
+Arguments:
+  target-project-dir   Path to target project (default: current directory)
+
+Options:
+  --help, -h           Show this help
+`);
+    process.exit(0);
+  }
+
+  const targetArg = args.find(a => !a.startsWith('-'));
+  const targetRoot = targetArg ? resolve(targetArg) : process.cwd();
+  const sourceRoot = DEFAULT_SOURCE_ROOT;
+
+  if (!existsSync(targetRoot)) {
+    console.error(`[install-pmc] ERROR: Target directory not found: ${targetRoot}`);
+    process.exit(1);
+  }
+
+  log(`Source: ${sourceRoot}`);
+  log(`Target: ${targetRoot}`);
+
+  const result = installPmcTools({ sourceRoot, targetRoot });
+
+  log(`Copied: ${result.cliFiles} CLI files, ${result.srcFiles} src files, ${result.templateFiles} templates`);
+  log('Created .planning/project-memory-context/ directory structure');
+  log('Done.');
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(err => {
+    console.error('[install-pmc] FATAL:', err.message);
+    process.exit(1);
+  });
+}

package/cli/materialize-enrichment-artifacts.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { join, resolve } from 'node:path';
+
+import { readJsonArtifact } from '../src/artifacts.mjs';
+import { persistEnrichmentArtifacts } from '../src/enrichment-artifacts.mjs';
+import { loadResultInput } from '../src/result-input.mjs';
+
+const [, , rawJobInput, rawReportInput, memoryIdArg, enrichedAtArg] = process.argv;
+
+if (!rawJobInput || !rawReportInput) {
+  console.error('Usage: node materialize-enrichment-artifacts.mjs <job-json|@job-file> <report-json|@report-file> [memory-id] [enriched-at]');
+  process.exit(1);
+}
+
+const projectRoot = resolve(process.cwd());
+const projectSlug = projectRoot.split(/[\\/]/).filter(Boolean).pop() ?? 'project';
+const enrichedAt = enrichedAtArg ?? new Date().toISOString();
+const memoryId = memoryIdArg && memoryIdArg !== '-' ? memoryIdArg : null;
+
+const job = await loadResultInput(rawJobInput);
+const report = await loadResultInput(rawReportInput);
+
+const persisted = await persistEnrichmentArtifacts({
+  projectRoot,
+  projectSlug,
+  job,
+  report,
+  memoryId,
+  enrichedAt,
+});
+
+console.log(JSON.stringify({
+  saved: true,
+  memoryPayloadFile: persisted.memoryPayloadFile,
+  enrichmentResultFile: persisted.enrichmentResultFile,
+  memoryId,
+  summary: persisted.semantic.summary,
+}, null, 2));

package/cli/new-project.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'bootstrap.mjs');
+
+export { buildDefaultEnrichmentConfig, mergeEnrichmentConfig } from './bootstrap.mjs';
+
+export async function main(args = process.argv.slice(2)) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+new-project - Bootstrap project-memory-context in any repo
+(Delegates to bootstrap.mjs - the portable PMC installer)
+
+Usage:
+  node new-project.mjs <target-repo> [--stage-a] [--stage-b] [--all] [--enrich]
+`);
+    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(`new-project exited from signal ${signal}`));
+        return;
+      }
+      resolvePromise(code ?? 0);
+    });
+  });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const exitCode = await main().catch((err) => {
+    console.error('[new-project] FATAL:', err.message);
+    return 1;
+  });
+  if (exitCode !== 0) process.exit(exitCode);
+}

package/cli/prepare-semantic-jobs.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+
+import { prepareSemanticJobs } from '../src/prepare-semantic-jobs.mjs';
+
+const projectRoot = resolve(process.cwd());
+const result = await prepareSemanticJobs({ projectRoot });
+console.log(JSON.stringify({ saved: true, file: result.file, count: result.count }, null, 2));

package/cli/project-context.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { basename, join, resolve, dirname } from 'node:path';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+
+import { ensureProjectMemoryContextDirs, writeJsonArtifact, readJsonArtifact } from '../src/artifacts.mjs';
+import { detectStackContext } from '../src/extractors/stack-extractor.mjs';
+import { detectStructureContext } from '../src/extractors/structure-extractor.mjs';
+import { detectArchitectureContext } from '../src/extractors/architecture-extractor.mjs';
+import { detectRulesContext } from '../src/extractors/rules-extractor.mjs';
+import { createDeclaredProjectContextTemplates } from '../src/declared-intake.mjs';
+import { materializeProjectContextMemories } from '../src/materializer.mjs';
+import { renderProjectContextMarkdown } from '../src/markdown-renderer.mjs';
+import { detectChangedFilesFromHashes } from '../src/change-detector.mjs';
+import { detectInvalidatedProjectContextKinds } from '../src/invalidation-matrix.mjs';
+import { appendSyncEntries, createSyncEntry } from '../src/sync-manifest.mjs';
+
+function log(message) {
+  console.error(`[project-context] ${message}`);
+}
+
+async function readText(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+const TRACKED_FILES = ['package.json', 'tsconfig.json', 'README.md'];
+
+async function buildDetectedContext(projectRoot) {
+  const stack = await detectStackContext(projectRoot);
+  const structure = await detectStructureContext(projectRoot);
+  const architecture = await detectArchitectureContext({ graph: { nodes: structure.entryPoints.map((entry) => ({ label: entry })), edges: [] } });
+  const rules = await detectRulesContext({ readmeText: await readText(join(projectRoot, 'README.md')) });
+  return { stack, structure, architecture, rules };
+}
+
+function buildDeclaredContext() {
+  return {
+    architectureTarget: { architecture: '' },
+    technicalRules: { rules: [] },
+    projectRequirements: { requirements: [] },
+    knownIssuesAndFixes: { items: [] },
+  };
+}
+
+async function writeMemories(dirs, memories) {
+  for (const memory of memories) {
+    const jsonName = `${memory.kind}.json`;
+    const markdownName = `${memory.kind.toUpperCase()}.md`;
+    await writeJsonArtifact(join(dirs.projectContextMaterialized, jsonName), memory);
+    const markdown = renderProjectContextMarkdown(memory);
+    await mkdir(dirname(join(dirs.projectContextMarkdown, markdownName)), { recursive: true });
+    await writeFile(join(dirs.projectContextMarkdown, markdownName), markdown, 'utf8');
+  }
+}
+
+async function computeHashes(projectRoot, files) {
+  const hashes = {};
+  for (const file of files) {
+    try {
+      const content = await readFile(join(projectRoot, file), 'utf8');
+      hashes[file] = createHash('sha256').update(content).digest('hex');
+    } catch {}
+  }
+  return hashes;
+}
+
+async function runBootstrap(projectRoot, dirs) {
+  const updatedAt = new Date().toISOString();
+  const detected = await buildDetectedContext(projectRoot);
+  const declared = buildDeclaredContext();
+
+  const templates = createDeclaredProjectContextTemplates();
+  for (const [fileName, payload] of Object.entries(templates)) {
+    await writeJsonArtifact(join(dirs.projectContextDeclared, fileName), payload);
+  }
+
+  const memories = materializeProjectContextMemories({
+    projectSlug: basename(projectRoot).toLowerCase(),
+    detected,
+    declared,
+    updatedAt,
+  });
+
+  await writeMemories(dirs, memories);
+
+  const nextHashes = await computeHashes(projectRoot, TRACKED_FILES);
+  await writeJsonArtifact(join(dirs.projectContextState, 'content-hashes.json'), { hashes: nextHashes });
+  await writeJsonArtifact(join(dirs.projectContextState, 'last-run.json'), { updatedAt, count: memories.length });
+
+  const syncEntries = memories.map((memory) => createSyncEntry({
+    action: 'upsert',
+    keyTag: `key:${memory.memory_key}`,
+    content: `# ${memory.title}\n\n${memory.summary}\n\n${memory.body}`,
+    category: 'architecture',
+    tags: [...memory.tags, `key:${memory.memory_key}`],
+    source: 'project-context',
+  }));
+  await appendSyncEntries(dirs.enrichment, syncEntries);
+
+  log(`Wrote ${memories.length} project-context memories.`);
+  log(`Appended ${syncEntries.length} sync-manifest entries.`);
+}
+
+async function runRefresh(projectRoot, dirs) {
+  const updatedAt = new Date().toISOString();
+
+  const nextHashes = await computeHashes(projectRoot, TRACKED_FILES);
+  const previousState = await readJsonArtifact(join(dirs.projectContextState, 'content-hashes.json'), { hashes: {} });
+  const changed = detectChangedFilesFromHashes(previousState.hashes, nextHashes);
+  const invalidatedKinds = detectInvalidatedProjectContextKinds(changed);
+
+  if (invalidatedKinds.length === 0) {
+    log('No changes detected. Nothing to refresh.');
+    return;
+  }
+
+  log(`Changed files: ${changed.join(', ')}`);
+  log(`Invalidated kinds: ${invalidatedKinds.join(', ')}`);
+
+  const detected = await buildDetectedContext(projectRoot);
+  const declared = buildDeclaredContext();
+
+  const allMemories = materializeProjectContextMemories({
+    projectSlug: basename(projectRoot).toLowerCase(),
+    detected,
+    declared,
+    updatedAt,
+  });
+
+  const invalidatedSet = new Set(invalidatedKinds);
+  const toRewrite = allMemories.filter((m) => invalidatedSet.has(m.kind));
+
+  await writeMemories(dirs, toRewrite);
+
+  const syncEntries = toRewrite.map((memory) => createSyncEntry({
+    action: 'upsert',
+    keyTag: `key:${memory.memory_key}`,
+    content: `# ${memory.title}\n\n${memory.summary}\n\n${memory.body}`,
+    category: 'architecture',
+    tags: [...memory.tags, `key:${memory.memory_key}`],
+    source: 'project-context-refresh',
+  }));
+  await appendSyncEntries(dirs.enrichment, syncEntries);
+
+  const affectsArchitecture = invalidatedSet.has('architecture-current') || invalidatedSet.has('structure-summary');
+  if (affectsArchitecture) {
+    await markEnrichedSymbolsStale(dirs, basename(projectRoot).toLowerCase());
+  }
+
+  await writeJsonArtifact(join(dirs.projectContextState, 'content-hashes.json'), { hashes: nextHashes });
+  await writeJsonArtifact(join(dirs.projectContextState, 'last-run.json'), { updatedAt, count: toRewrite.length });
+
+  log(`Refreshed ${toRewrite.length} memories.`);
+  log(`Appended ${syncEntries.length} sync-manifest entries.`);
+  if (affectsArchitecture) {
+    log('Marked enriched symbols as stale (architecture/structure changed).');
+  }
+}
+
+async function markEnrichedSymbolsStale(dirs, projectSlug) {
+  const worklistPath = join(dirs.enrichment, 'worklist.json');
+  let worklist;
+  try {
+    worklist = JSON.parse(await readFile(worklistPath, 'utf8'));
+  } catch {
+    log('  No worklist found, skipping stale marking.');
+    return;
+  }
+
+  const staleEntries = [];
+  let staleCount = 0;
+  for (const entry of worklist) {
+    if (entry.status === 'enriched') {
+      entry.status = 'stale';
+      entry.staleReason = 'base-memory-changed';
+      entry.staleAt = new Date().toISOString();
+      staleCount++;
+      staleEntries.push(createSyncEntry({
+        action: 'delete',
+        keyTag: `key:symbol:${entry.symbolKey.replace(/[^a-zA-Z0-9_-]+/g, '_')}`,
+        category: 'architecture',
+        tags: ['symbol', entry.language, entry.kind, `project:${projectSlug}`, `file:${entry.filePath}`, `key:symbol:${entry.symbolKey.replace(/[^a-zA-Z0-9_-]+/g, '_')}`],
+        source: 'project-context-refresh',
+        symbolKey: entry.symbolKey,
+      }));
+    }
+  }
+
+  if (staleCount > 0) {
+    await writeFile(worklistPath, `${JSON.stringify(worklist, null, 2)}\n`, 'utf8');
+    await appendSyncEntries(dirs.enrichment, staleEntries);
+    log(`  Marked ${staleCount} enriched symbols as stale in worklist.`);
+    log(`  Appended ${staleEntries.length} delete entries to sync-manifest.`);
+  }
+}
+
+export async function runProjectContextCli(projectRoot, options = {}) {
+  const refresh = !!options.refresh;
+  log(`Target: ${projectRoot} (refresh=${refresh})`);
+
+  const dirs = await ensureProjectMemoryContextDirs(projectRoot);
+
+  if (refresh) {
+    await runRefresh(projectRoot, dirs);
+  } else {
+    await runBootstrap(projectRoot, dirs);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const refresh = args.includes('--refresh');
+  const projectRoot = resolve(args.filter((a) => a !== '--refresh')[0] ?? process.cwd());
+  await runProjectContextCli(projectRoot, { refresh });
+}
+
+main().catch((error) => {
+  console.error('[project-context] FATAL:', error.message);
+  process.exit(1);
+});