@aabadin/project-memory-context 0.1.0

package/src/command-dispatch.mjs

@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const COMMANDS = new Map([
+  ['bootstrap', 'cli/bootstrap.mjs'],
+  ['context', 'cli/context.mjs'],
+  ['doctor', 'cli/doctor.mjs'],
+  ['enrich', 'cli/enrich.mjs'],
+  ['help', null],
+  ['init', 'cli/init.mjs'],
+  ['install-pmc', 'cli/install-pmc.mjs'],
+  ['new-project', 'cli/new-project.mjs'],
+  ['project-context', 'cli/project-context.mjs'],
+  ['sanitize', 'cli/sanitize.mjs'],
+  ['setup', 'cli/setup.mjs'],
+  ['status', 'cli/status.mjs'],
+]);
+
+function usageText() {
+  return `Usage: pmc <${[...COMMANDS.keys()].join('|')}>`;
+}
+
+function writeLine(stream, message) {
+  stream.write(`${message}\n`);
+}
+
+export function resolveCommand(argv = []) {
+  const name = argv[0] ?? 'help';
+  const relativeModule = COMMANDS.get(name);
+
+  if (relativeModule === undefined) {
+    return { name, modulePath: null, args: argv.slice(1), valid: false };
+  }
+
+  return {
+    name,
+    modulePath: relativeModule ? resolve(PACKAGE_ROOT, relativeModule) : null,
+    args: argv.slice(1),
+    valid: true,
+  };
+}
+
+export async function runCommand(argv = [], options = {}) {
+  const { stdio = 'inherit', stdout = process.stdout, stderr = process.stderr } = options;
+  const command = resolveCommand(argv);
+
+  if (!command.valid) {
+    writeLine(stderr, `Invalid command: ${command.name}`);
+    writeLine(stdout, usageText());
+    return 1;
+  }
+
+  if (!command.modulePath) {
+    writeLine(stdout, usageText());
+    return 0;
+  }
+
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, [command.modulePath, ...command.args], { stdio });
+
+    if (stdio === 'pipe') {
+      child.stdout?.on('data', (chunk) => {
+        stdout.write(chunk);
+      });
+
+      child.stderr?.on('data', (chunk) => {
+        stderr.write(chunk);
+      });
+    }
+
+    child.once('error', rejectPromise);
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        rejectPromise(new Error(`Command exited from signal ${signal}`));
+        return;
+      }
+
+      resolvePromise(code ?? 0);
+    });
+  });
+}

package/src/declared-intake.mjs

@@ -0,0 +1,25 @@
+export function createDeclaredProjectContextTemplates({
+  architectureTarget = '',
+  technicalRules = [],
+  projectRequirements = [],
+  knownIssuesAndFixes = [],
+} = {}) {
+  return {
+    'architecture-target.json': {
+      title: 'Target project architecture',
+      architecture: architectureTarget,
+    },
+    'technical-rules.json': {
+      title: 'Technical rules',
+      rules: technicalRules,
+    },
+    'project-requirements.json': {
+      title: 'Project requirements',
+      requirements: projectRequirements,
+    },
+    'known-issues-and-fixes.json': {
+      title: 'Known issues and fixes',
+      items: knownIssuesAndFixes,
+    },
+  };
+}

package/src/doctor.mjs

@@ -0,0 +1,114 @@
+import { access, constants } from 'node:fs/promises';
+
+const DEFAULT_OLLAMA_URL = 'http://localhost:11434';
+
+export async function runDoctor({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  resolvePythonBin = () => null,
+  resolveGraphify = () => null,
+  spawnCheck = null,
+} = {}) {
+  const checks = await Promise.all([
+    checkNodeVersion(),
+    checkPython(resolvePythonBin, spawnCheck),
+    checkGraphify(resolvePythonBin, spawnCheck),
+    checkOllama(env, fetchImpl),
+    checkMemoryDbPath(env),
+    checkEmbeddingCachePath(env),
+  ]);
+  return { checks };
+}
+
+async function checkNodeVersion() {
+  const major = parseInt(process.version.slice(1).split('.')[0], 10);
+  return {
+    name: 'node-version',
+    status: major >= 18 ? 'ok' : 'fail',
+    message: major >= 18
+      ? `Node.js ${process.version} ✓`
+      : `Node.js ${process.version} requires ≥ 18 — upgrade Node.js`,
+  };
+}
+
+async function checkPython(resolvePythonBin, spawnCheck) {
+  const bin = resolvePythonBin?.() ?? null;
+  if (!bin) {
+    return { name: 'python', status: 'fail', message: 'Python 3 not found in PATH — install python3 or set PATH' };
+  }
+  if (!spawnCheck) {
+    return { name: 'python', status: 'ok', message: `${bin} found (not verified — no spawn check provided)` };
+  }
+  const result = await spawnCheck(bin, ['--version']);
+  return {
+    name: 'python',
+    status: result.exitCode === 0 ? 'ok' : 'fail',
+    message: result.exitCode === 0
+      ? `${bin} ${result.stdout?.trim() ?? ''} ✓`
+      : `${bin} failed to run — check Python installation`,
+  };
+}
+
+async function checkGraphify(resolvePythonBin, spawnCheck) {
+  const bin = resolvePythonBin?.() ?? 'python3';
+  if (!spawnCheck) {
+    return { name: 'graphifyy', status: 'warn', message: 'graphifyy check skipped (no spawn check provided)' };
+  }
+  const result = await spawnCheck(bin, ['-c', 'import graphifyy; print("ok")']);
+  return {
+    name: 'graphifyy',
+    status: result.exitCode === 0 ? 'ok' : 'fail',
+    message: result.exitCode === 0
+      ? 'graphifyy importable ✓'
+      : 'graphifyy not installed — run: pip install graphifyy',
+  };
+}
+
+async function checkOllama(env, fetchImpl) {
+  const baseUrl = env.PMC_LOCAL_MODEL_BASE_URL ?? DEFAULT_OLLAMA_URL;
+  try {
+    const res = await Promise.race([
+      fetchImpl(`${baseUrl}/api/tags`),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000)),
+    ]);
+    return {
+      name: 'ollama',
+      status: res.ok ? 'ok' : 'warn',
+      message: res.ok
+        ? `Ollama reachable at ${baseUrl} ✓`
+        : `Ollama responded ${res.status} at ${baseUrl}`,
+    };
+  } catch {
+    return {
+      name: 'ollama',
+      status: 'warn',
+      message: `Ollama not reachable at ${baseUrl} — enrichment will use cloud-api fallback`,
+    };
+  }
+}
+
+async function checkMemoryDbPath(env) {
+  const p = env.MEMORY_DB_PATH;
+  if (!p) {
+    return { name: 'memory-db-path', status: 'fail', message: 'MEMORY_DB_PATH not set — required for agent-memory-mcp' };
+  }
+  try {
+    await access(p, constants.W_OK);
+    return { name: 'memory-db-path', status: 'ok', message: `${p} writable ✓` };
+  } catch {
+    return { name: 'memory-db-path', status: 'warn', message: `${p} does not exist yet (will be created on first run)` };
+  }
+}
+
+async function checkEmbeddingCachePath(env) {
+  const p = env.EMBEDDING_CACHE_PATH;
+  if (!p) {
+    return { name: 'embedding-cache', status: 'ok', message: 'EMBEDDING_CACHE_PATH not set (cache disabled — optional)' };
+  }
+  try {
+    await access(p, constants.W_OK);
+    return { name: 'embedding-cache', status: 'ok', message: `${p} writable ✓` };
+  } catch {
+    return { name: 'embedding-cache', status: 'warn', message: `${p} does not exist yet (will be created on first run)` };
+  }
+}

package/src/enrichment-artifacts.mjs

@@ -0,0 +1,67 @@
+import { join, resolve } from 'node:path';
+
+import {
+  ensureProjectMemoryContextDirs,
+  writeJsonArtifact,
+} from './artifacts.mjs';
+import { buildEnrichmentResult, buildMemoryPayload } from './memory-payload.mjs';
+import { normalizeSemanticReport } from './semantic-report.mjs';
+
+function safeSymbolKey(symbolKey) {
+  return symbolKey.replace(/[^a-zA-Z0-9_-]+/g, '_');
+}
+
+export function buildEnrichmentArtifacts({ projectSlug, job, report, memoryId, enrichedAt }) {
+  const semantic = normalizeSemanticReport(report);
+  const memoryPayload = buildMemoryPayload({ projectSlug, job, semantic });
+  const enrichmentResult = memoryId
+    ? buildEnrichmentResult({
+        job,
+        memoryId,
+        semanticSummary: semantic.summary || semantic.responsibility,
+        status: 'enriched',
+        enrichedAt,
+      })
+    : null;
+
+  return {
+    semantic,
+    memoryPayload,
+    enrichmentResult,
+  };
+}
+
+export async function persistEnrichmentArtifacts({
+  projectRoot,
+  projectSlug,
+  job,
+  report,
+  memoryId,
+  enrichedAt,
+}) {
+  const resolvedRoot = resolve(projectRoot);
+  const dirs = await ensureProjectMemoryContextDirs(resolvedRoot);
+  const artifacts = buildEnrichmentArtifacts({
+    projectSlug,
+    job,
+    report,
+    memoryId,
+    enrichedAt,
+  });
+  const fileStem = safeSymbolKey(job.symbolKey);
+  const memoryPayloadFile = join(dirs.enrichment, `${fileStem}.memory.json`);
+  const enrichmentResultFile = memoryId
+    ? join(dirs.enrichment, `${fileStem}.result.json`)
+    : null;
+
+  await writeJsonArtifact(memoryPayloadFile, artifacts.memoryPayload);
+  if (artifacts.enrichmentResult && enrichmentResultFile) {
+    await writeJsonArtifact(enrichmentResultFile, artifacts.enrichmentResult);
+  }
+
+  return {
+    ...artifacts,
+    memoryPayloadFile,
+    enrichmentResultFile,
+  };
+}

package/src/enrichment-attempts.mjs

@@ -0,0 +1,17 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export async function appendProviderEvent(enrichmentDir, event) {
+  await mkdir(enrichmentDir, { recursive: true });
+  await appendFile(join(enrichmentDir, 'provider-events.jsonl'), `${JSON.stringify(event)}\n`, 'utf8');
+}
+
+export function withRecordedAttempt(entry, attempt) {
+  const attempts = [...(entry.attempts ?? []), attempt];
+
+  return {
+    ...entry,
+    attempts,
+    lastModeUsed: attempt.mode ?? entry.lastModeUsed ?? null,
+  };
+}

package/src/enrichment-config.mjs

@@ -0,0 +1,121 @@
+import { join } from 'node:path';
+
+import { resolveConfigDirs } from './platform.mjs';
+
+const DEFAULTS = {
+  preferredModes: ['local-model', 'cloud-api', 'agent-subagent'],
+  localModel: {
+    provider: 'ollama',
+    baseUrl: 'http://localhost:11434',
+    model: 'deepseek-coder-v2:16b-ctx32k',
+  },
+  cloudApi: {
+    provider: 'openai-compatible',
+    baseUrl: '',
+    model: '',
+    apiKeyEnv: 'PMC_CLOUD_API_KEY',
+  },
+  agentSubagent: {
+    enabled: true,
+    agentName: 'enrich',
+  },
+};
+
+export const PMC_ENRICHMENT_CONFIG_FILE = 'project-memory-context.json';
+
+const VALID_MODES = new Set(DEFAULTS.preferredModes);
+
+function normalizePreferredModes(modes) {
+  const filtered = [...new Set((modes ?? []).filter((mode) => VALID_MODES.has(mode)))];
+  return filtered.length > 0 ? filtered : [...DEFAULTS.preferredModes];
+}
+
+function mergeConfig(base, override) {
+  return {
+    ...base,
+    ...override,
+    localModel: {
+      ...base.localModel,
+      ...override?.localModel,
+    },
+    cloudApi: {
+      ...base.cloudApi,
+      ...override?.cloudApi,
+    },
+    agentSubagent: {
+      ...base.agentSubagent,
+      ...override?.agentSubagent,
+    },
+  };
+}
+
+function unwrapEnrichmentConfig(config) {
+  if (!config) {
+    return {};
+  }
+
+  return config.enrichment ?? config;
+}
+
+export function readEnvPreferredModes(env) {
+  return env.PMC_ENRICHMENT_PREFERRED_MODES
+    ? env.PMC_ENRICHMENT_PREFERRED_MODES
+      .split(',')
+      .map((mode) => mode.trim())
+      .filter(Boolean)
+    : null;
+}
+
+export function resolveEnrichmentConfigPaths({
+  projectRoot = process.cwd(),
+  env = process.env,
+  platformOptions,
+} = {}) {
+  const { projectConfigDir, globalConfigDir } = resolveConfigDirs(projectRoot, platformOptions);
+
+  return {
+    fileName: PMC_ENRICHMENT_CONFIG_FILE,
+    projectConfigPath: env.PMC_PROJECT_CONFIG ?? join(projectConfigDir, PMC_ENRICHMENT_CONFIG_FILE),
+    globalConfigPath: env.PMC_GLOBAL_CONFIG ?? join(globalConfigDir, PMC_ENRICHMENT_CONFIG_FILE),
+  };
+}
+
+export function resolveEnrichmentConfig({ projectConfig, globalConfig, env }) {
+  let resolved = mergeConfig(DEFAULTS, unwrapEnrichmentConfig(globalConfig));
+  resolved = mergeConfig(resolved, unwrapEnrichmentConfig(projectConfig));
+
+  const preferredModes = readEnvPreferredModes(env);
+  if (preferredModes) {
+    resolved.preferredModes = normalizePreferredModes(preferredModes);
+  }
+
+  if (env.PMC_LOCAL_MODEL_BASE_URL) {
+    resolved.localModel.baseUrl = env.PMC_LOCAL_MODEL_BASE_URL;
+  }
+
+  if (env.PMC_LOCAL_MODEL_NAME) {
+    resolved.localModel.model = env.PMC_LOCAL_MODEL_NAME;
+  }
+
+  if (env.PMC_CLOUD_API_BASE_URL) {
+    resolved.cloudApi.baseUrl = env.PMC_CLOUD_API_BASE_URL;
+  }
+
+  if (env.PMC_CLOUD_API_MODEL) {
+    resolved.cloudApi.model = env.PMC_CLOUD_API_MODEL;
+  }
+
+  if (env.PMC_CLOUD_API_KEY_ENV) {
+    resolved.cloudApi.apiKeyEnv = env.PMC_CLOUD_API_KEY_ENV;
+  }
+
+  if (env.PMC_AGENT_SUBAGENT_NAME) {
+    resolved.agentSubagent.agentName = env.PMC_AGENT_SUBAGENT_NAME;
+  }
+
+  resolved.preferredModes = normalizePreferredModes(resolved.preferredModes);
+
+  return resolved;
+}
+
+export { DEFAULTS };

package/src/enrichment-driver.mjs

@@ -0,0 +1,167 @@
+import { classifyEnrichmentError } from './enrichment-errors.mjs';
+
+function isFallbackEligible(type) {
+  return type === 'auth'
+    || type === 'timeout'
+    || type === 'network'
+    || type === 'rate-limit'
+    || type === 'provider';
+}
+
+function providerConfigForMode(config, mode) {
+  if (mode === 'local-model') {
+    return config?.localModel ?? {};
+  }
+
+  if (mode === 'cloud-api') {
+    return config?.cloudApi ?? {};
+  }
+
+  if (mode === 'agent-subagent') {
+    return config?.agentSubagent ?? {};
+  }
+
+  return {};
+}
+
+function providerNameForMode(config, mode, provider) {
+  return providerConfigForMode(config, mode).provider ?? provider?.kind ?? mode;
+}
+
+export async function runEnrichmentWithFallback({ request, config, providers, env = process.env }) {
+  const attempts = [];
+
+  for (const mode of config.preferredModes ?? []) {
+    const provider = providers.find((candidate) => candidate.kind === mode);
+    if (!provider) {
+      continue;
+    }
+
+    const providerName = providerNameForMode(config, mode, provider);
+    const startedAt = new Date().toISOString();
+    const configured = provider.isConfigured({ request, config, env });
+
+    if (!configured.ok) {
+      attempts.push({
+        mode,
+        provider: providerName,
+        status: 'skipped',
+        errorType: 'config',
+        errorMessage: configured.reason,
+        startedAt,
+        endedAt: new Date().toISOString(),
+      });
+      continue;
+    }
+
+    let available;
+    try {
+      available = await provider.isAvailable({ request, config, env });
+    } catch (error) {
+      const classified = classifyEnrichmentError(error);
+      attempts.push({
+        mode,
+        provider: providerName,
+        status: 'failed',
+        errorType: classified.type,
+        errorMessage: classified.message,
+        startedAt,
+        endedAt: new Date().toISOString(),
+      });
+
+      if (!isFallbackEligible(classified.type)) {
+        return {
+          status: 'error',
+          content: null,
+          mode: null,
+          provider: null,
+          model: null,
+          attempts,
+        };
+      }
+      continue;
+    }
+
+    if (!available.ok) {
+      const classified = available.errorType
+        ? { type: available.errorType, message: available.reason }
+        : classifyEnrichmentError(new Error(available.reason ?? 'provider unavailable'));
+      const attempt = {
+        mode,
+        provider: providerName,
+        status: 'skipped',
+        errorType: classified.type,
+        errorMessage: classified.message,
+        startedAt,
+        endedAt: new Date().toISOString(),
+      };
+      attempts.push(attempt);
+
+      if (!isFallbackEligible(classified.type)) {
+        return {
+          status: 'error',
+          content: null,
+          mode: null,
+          provider: null,
+          model: null,
+          attempts,
+        };
+      }
+      continue;
+    }
+
+    try {
+      const result = await provider.enrich(request, { request, config, env });
+      const attempt = {
+        mode,
+        provider: result.provider ?? providerName,
+        model: result.model ?? null,
+        status: 'succeeded',
+        startedAt,
+        endedAt: new Date().toISOString(),
+      };
+      attempts.push(attempt);
+
+      return {
+        status: 'succeeded',
+        content: result.content,
+        mode,
+        provider: result.provider ?? providerName,
+        model: result.model ?? null,
+        attempts,
+      };
+    } catch (error) {
+      const classified = classifyEnrichmentError(error);
+      const attempt = {
+        mode,
+        provider: providerName,
+        status: 'failed',
+        errorType: classified.type,
+        errorMessage: classified.message,
+        startedAt,
+        endedAt: new Date().toISOString(),
+      };
+      attempts.push(attempt);
+
+      if (!isFallbackEligible(classified.type)) {
+        return {
+          status: 'error',
+          content: null,
+          mode: null,
+          provider: null,
+          model: null,
+          attempts,
+        };
+      }
+    }
+  }
+
+  return {
+    status: 'error',
+    content: null,
+    mode: null,
+    provider: null,
+    model: null,
+    attempts,
+  };
+}

package/src/enrichment-errors.mjs

@@ -0,0 +1,46 @@
+function messageOf(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error ?? 'Unknown enrichment error');
+}
+
+export function classifyEnrichmentError(error) {
+  const message = messageOf(error);
+  const normalized = message.toLowerCase();
+
+  let type = 'runtime';
+
+  if (normalized.includes('401') || normalized.includes('unauthorized') || normalized.includes('forbidden')) {
+    type = 'auth';
+  } else if (normalized.includes('429') || normalized.includes('rate limit')) {
+    type = 'rate-limit';
+  } else if (
+    normalized.includes('500')
+    || normalized.includes('502')
+    || normalized.includes('503')
+    || normalized.includes('504')
+    || normalized.includes('404')
+    || normalized.includes('provider unavailable')
+    || normalized.includes('model missing')
+  ) {
+    type = 'provider';
+  } else if (
+    normalized.includes('econnrefused')
+    || normalized.includes('enotfound')
+    || normalized.includes('econnreset')
+    || normalized.includes('socket')
+    || normalized.includes('network')
+  ) {
+    type = 'network';
+  } else if (normalized.includes('timeout')) {
+    type = 'timeout';
+  } else if (normalized.includes('config')) {
+    type = 'config';
+  } else if (normalized.includes('provider')) {
+    type = 'provider';
+  }
+
+  return { type, message };
+}

package/src/enrichment-linker.mjs

@@ -0,0 +1,29 @@
+import { backfillGraphNode } from './graph-backfill.mjs';
+import { upsertSymbolIndexEntry } from './symbol-index.mjs';
+
+export function applyEnrichmentResult({ graph, symbolIndex, result }) {
+  const updatedGraph = backfillGraphNode({
+    graph,
+    symbolKey: result.symbolKey,
+    graphNodeId: result.graphNodeId,
+    memoryId: result.memoryId,
+    semanticSummary: result.semanticSummary,
+    codeHash: result.codeHash,
+    enrichedAt: result.enrichedAt,
+    status: result.status,
+  });
+
+  const updatedIndex = upsertSymbolIndexEntry(symbolIndex, {
+    symbolKey: result.symbolKey,
+    graphNodeId: result.graphNodeId,
+    memoryId: result.memoryId,
+    codeHash: result.codeHash,
+    status: result.status,
+    lastEnrichedAt: result.enrichedAt,
+  });
+
+  return {
+    graph: updatedGraph,
+    symbolIndex: updatedIndex,
+  };
+}

package/src/extractors/architecture-extractor.mjs

@@ -0,0 +1,8 @@
+export async function detectArchitectureContext({ graph }) {
+  const labels = (graph?.nodes ?? []).map((node) => String(node.label ?? node.id ?? ''));
+  return {
+    pattern: 'detected-structure',
+    entryPoints: labels.filter((label) => /(?:^|\/)main\.[cm]?[jt]sx?$|(?:^|\/)app\.[cm]?[jt]sx?$/.test(label)),
+    graphRefs: labels.map((label) => `node:${label}`),
+  };
+}