@ngockhoale/ukit 3.0.12 → 3.1.0

package/src/cli/commands/memory.js

@@ -51,24 +51,24 @@ function extractFlag(args, flag) {
   };
 }
 
-async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
+async function listAllPendingPatternCandidates(projectRoot, runtimePaths, { homeDir } = {}) {
   // v2 mode: pending pattern candidates live as derived_fact records with
   // meta.legacyStatus === 'pending' (facade handles the conversion).
   // Respect memoryV2.enabled — without this check loadRecords would run the
   // lazy v1→v2 migration even when the whole v2 lane is disabled.
   let v2Enabled = true;
   try {
-    const { config } = await inspectRuntimeConfig(projectRoot);
+    const { config } = await inspectRuntimeConfig(projectRoot, { homeDir });
     if (config?.memoryV2?.enabled === false) v2Enabled = false;
   } catch {
     // unreadable config → default enabled
   }
-  const records = v2Enabled ? await loadRecords(projectRoot) : [];
+  const records = v2Enabled ? await loadRecords(projectRoot, { homeDir }) : [];
   if (records.length > 0) {
     const projectIds = new Set(records.map((r) => r.project_id).filter(Boolean));
     const results = [];
     for (const projectId of projectIds) {
-      const pending = await listPendingPatternCandidates(projectRoot, projectId);
+      const pending = await listPendingPatternCandidates(projectRoot, projectId, { homeDir });
       for (const candidate of pending) {
         results.push({ ...candidate, projectId });
       }
@@ -87,7 +87,7 @@ async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
     const projectId = entry.name.replace(/\.json$/, '');
-    const pending = await listPendingPatternCandidates(projectRoot, projectId);
+    const pending = await listPendingPatternCandidates(projectRoot, projectId, { homeDir });
     for (const candidate of pending) {
       results.push({ ...candidate, projectId });
     }
@@ -128,7 +128,7 @@ function handleMutationResult(res, { notFoundMessage }) {
 
 // ---- `ukit memory v2` ops (SPEC §11) ----
 
-async function runMemoryV2(projectRoot, args) {
+async function runMemoryV2(projectRoot, homeDir, args) {
   const [opRaw, ...rest] = args;
   const op = (opRaw ?? 'list').toLowerCase();
 
@@ -140,6 +140,7 @@ async function runMemoryV2(projectRoot, args) {
       type: typeFlag.value ?? undefined,
       scope: scopeFlag.value ?? undefined,
       status: statusFlag.value ?? undefined,
+      homeDir,
     });
     if (records.length === 0) {
       console.log('[UKit] No memory v2 records found.');
@@ -157,7 +158,7 @@ async function runMemoryV2(projectRoot, args) {
     if (!id) {
       throw new Error('Missing record id. Usage: ukit memory v2 show <id>');
     }
-    const record = await getRecord(projectRoot, id);
+    const record = await getRecord(projectRoot, id, { homeDir });
     if (!record) {
       throw new Error(`Memory v2 record not found: ${id}`);
     }
@@ -170,7 +171,7 @@ async function runMemoryV2(projectRoot, args) {
     if (!id) {
       throw new Error('Missing record id. Usage: ukit memory v2 promote <id>');
     }
-    const record = await getRecord(projectRoot, id);
+    const record = await getRecord(projectRoot, id, { homeDir });
     if (!record) {
       throw new Error(`Memory v2 record not found: ${id}`);
     }
@@ -186,7 +187,7 @@ async function runMemoryV2(projectRoot, args) {
     // through mutateMemory with expectedRevision so a concurrent writer
     // surfaces as a conflict instead of a silent clobber (FR-023).
     const res = await mutateMemory(
-      { kind: 'project', projectRoot },
+      { kind: 'project', projectRoot, homeDir },
       {
         op: 'update',
         payload: {
@@ -216,12 +217,12 @@ async function runMemoryV2(projectRoot, args) {
     if (!id) {
       throw new Error('Missing record id. Usage: ukit memory v2 stale <id>');
     }
-    const record = await getRecord(projectRoot, id);
+    const record = await getRecord(projectRoot, id, { homeDir });
     if (!record) {
       throw new Error(`Memory v2 record not found: ${id}`);
     }
     const res = await mutateMemory(
-      { kind: 'project', projectRoot },
+      { kind: 'project', projectRoot, homeDir },
       {
         op: 'update',
         payload: { id, patch: { status: 'stale' } },
@@ -238,7 +239,7 @@ async function runMemoryV2(projectRoot, args) {
 
   if (op === 'migrate') {
     const dryRun = rest.includes('--dry-run');
-    const result = await runMigration(projectRoot, { dryRun });
+    const result = await runMigration(projectRoot, { dryRun, homeDir });
     if (dryRun) {
       // Per-record plan: counts per action + ids only — never record bodies.
       const counts = {};
@@ -259,7 +260,7 @@ async function runMemoryV2(projectRoot, args) {
     }
     console.log(`[UKit] Migrated ${result.migrated} record(s) to v2.`);
     console.log(`[UKit] Backup: ${result.backupDir ?? 'none'} — marker: ${result.markerPath}`);
-    const stats = await v2Stats(projectRoot);
+    const stats = await v2Stats(projectRoot, { homeDir });
     console.log(`[UKit] v2 store: ${stats.total} record(s) — ${JSON.stringify(stats.byType)}`);
     return;
   }
@@ -436,8 +437,8 @@ const MEM_REF_RE = /<!--\s*mem:(mem_[0-9a-f]{12})\s*-->/g;
 // Approved promotable records: active project_rule/procedure belonging to the
 // project, not bulk-migrated v1 leftovers (created_by 'migration'), and not
 // still-pending candidates (meta.legacyStatus 'pending').
-async function collectPromotableRecords(projectRoot, projectId) {
-  const records = await loadRecords(projectRoot);
+async function collectPromotableRecords(projectRoot, projectId, { homeDir } = {}) {
+  const records = await loadRecords(projectRoot, { homeDir });
   return records.filter((r) =>
     (r.type === 'project_rule' || r.type === 'procedure')
     && r.status === 'active'
@@ -478,9 +479,9 @@ async function writeTextAtomic(filePath, text) {
   await fs.rename(tmp, filePath);
 }
 
-async function runMemoryPromote(projectRoot, args) {
+async function runMemoryPromote(projectRoot, homeDir, args) {
   const dryRun = args.includes('--dry-run');
-  const projectId = (await detectProjectContext(projectRoot)).project.name;
+  const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
   const memoryMdPath = path.join(projectRoot, 'docs', 'MEMORY.md');
 
   let existing = '';
@@ -491,7 +492,7 @@ async function runMemoryPromote(projectRoot, args) {
   }
 
   const outsideIds = externallyReferencedIds(existing);
-  const promotable = (await collectPromotableRecords(projectRoot, projectId))
+  const promotable = (await collectPromotableRecords(projectRoot, projectId, { homeDir }))
     .filter((r) => !outsideIds.has(r.id));
 
   const block = renderLearnedBlock(promotable);
@@ -567,11 +568,11 @@ function episodeText(ledger, sessionId) {
   return text.slice(0, 300);
 }
 
-async function runMemoryEpisode(projectRoot, args) {
+async function runMemoryEpisode(projectRoot, homeDir, args) {
   const dryRun = args.includes('--dry-run');
   const sessionFlag = extractFlag(args, '--session').value;
 
-  const { config } = await inspectRuntimeConfig(projectRoot);
+  const { config } = await inspectRuntimeConfig(projectRoot, { homeDir });
   if (config?.memoryV2?.enabled === false) {
     console.log('[UKit] episode: skipped (memoryV2 disabled)');
     return;
@@ -592,19 +593,19 @@ async function runMemoryEpisode(projectRoot, args) {
     return;
   }
 
-  const existing = await loadRecords(projectRoot);
+  const existing = await loadRecords(projectRoot, { homeDir });
   if (existing.some((r) => r.meta?.ledgerKey === ledgerKey)) {
     console.log('[UKit] episode: already recorded');
     return;
   }
 
   const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
-  const projectId = (await detectProjectContext(projectRoot)).project.name;
+  const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
   // FR-023: the add goes through mutateMemory with the ledger key as the
   // idempotency key — a hook-invoked rerun is a journal 'duplicate' even if
   // the meta.ledgerKey fast-path above is bypassed.
   const res = await mutateMemory(
-    { kind: 'project', projectRoot },
+    { kind: 'project', projectRoot, homeDir },
     {
       op: 'add',
       idempotencyKey: ledgerKey,
@@ -745,7 +746,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
   }
 
   if (subcommand === 'v2') {
-    await runMemoryV2(projectRoot, rest);
+    await runMemoryV2(projectRoot, homeDir, rest);
     return;
   }
 
@@ -763,7 +764,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       return;
     }
 
-    const items = await listMemoryItems(projectRoot);
+    const items = await listMemoryItems(projectRoot, { homeDir });
     if (items.length === 0) {
       console.log('[UKit] No memory items found.');
       return;
@@ -783,12 +784,12 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       throw new Error('Missing pattern text. Usage: ukit memory propose "<text>" [--category <name>] [--project <id>]');
     }
 
-    const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot)).project.name;
+    const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
     const candidate = await proposePatternCandidate(projectRoot, projectId, {
       text,
       category: categoryFlag.value,
       detectedFrom: 'cli',
-    });
+    }, { homeDir });
 
     console.log(`[UKit] Proposed ${candidate.id} (${candidate.status}) for project ${projectId}.`);
     console.log('[UKit] Review with `ukit memory list --pending`, then `ukit memory approve <id>`.');
@@ -809,7 +810,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
     if (minFlag.value != null && (!Number.isFinite(minCount) || minCount < 1)) {
       throw new Error(`Invalid --min value: ${minFlag.value}`);
     }
-    const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot)).project.name;
+    const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
 
     const { proposeFromPatterns } = await import('../../learning/patternProposals.js');
     const result = await proposeFromPatterns(projectRoot, projectId, {
@@ -853,12 +854,13 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       throw new Error(`Missing candidate id. Usage: ukit memory ${subcommand} <candidateId> [--project <id>]`);
     }
 
-    const projectId = explicitProjectId ?? (await detectProjectContext(projectRoot)).project.name;
+    const projectId = explicitProjectId ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
     const resolved = await resolvePatternCandidate(
       projectRoot,
       projectId,
       candidateId,
       subcommand === 'approve' ? 'approve' : 'reject',
+      { homeDir },
     );
 
     console.log(`[UKit] ${resolved.status === 'approved' ? 'Approved' : 'Rejected'} ${candidateId}.`);
@@ -868,7 +870,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
   if (subcommand === 'hygiene') {
     const projectFlagIndex = rest.indexOf('--project');
     const explicitProjectId = projectFlagIndex >= 0 ? rest[projectFlagIndex + 1] : null;
-    const projectId = explicitProjectId ?? (await detectProjectContext(projectRoot)).project.name;
+    const projectId = explicitProjectId ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
 
     const result = await runProjectHygiene(projectRoot, projectId);
     console.log(`[UKit] Ran hygiene for project ${projectId}.`);
@@ -890,6 +892,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       // silently widening to cross-repo results.
       projectId: projectContext.project.id ?? null,
       projectAliases: projectContext.project.aliases ?? [],
+      homeDir,
     });
     if (results.length === 0) {
       console.log('[UKit] No memory matches found.');
@@ -923,6 +926,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       projectRoot,
       projectId: projectContext.project.id ?? null,
       projectAliases: projectContext.project.aliases ?? [],
+      homeDir,
     });
     // FR-007: the hit block carries citation/freshness/reasons — provenance
     // surface only, never record meta. Legacy lane has no hit; its
@@ -942,7 +946,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       throw new Error('Missing task/query. Usage: ukit memory recall <task>');
     }
 
-    const runtimeConfigInspection = await inspectRuntimeConfig(projectRoot);
+    const runtimeConfigInspection = await inspectRuntimeConfig(projectRoot, { homeDir });
     if (!runtimeConfigInspection.valid) {
       throw new Error('Runtime config is invalid. Run `ukit doctor` or rerun `ukit install`.');
     }
@@ -959,6 +963,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       maxTokens: runtimeConfig.memory.maxInjectionTokens,
       promptCache: Boolean(runtimeConfig.tokenPipeline?.promptCache),
       inputCompression: Boolean(runtimeConfig.tokenPipeline?.inputCompression),
+      homeDir,
     });
 
     if (!injection) {
@@ -971,12 +976,12 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
   }
 
   if (subcommand === 'promote') {
-    await runMemoryPromote(projectRoot, rest);
+    await runMemoryPromote(projectRoot, homeDir, rest);
     return;
   }
 
   if (subcommand === 'episode') {
-    await runMemoryEpisode(projectRoot, rest);
+    await runMemoryEpisode(projectRoot, homeDir, rest);
     return;
   }
 
@@ -986,7 +991,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
       throw new Error('Missing memory id. Usage: ukit memory forget <id>');
     }
 
-    const result = await forgetMemoryItem(projectRoot, memoryId);
+    const result = await forgetMemoryItem(projectRoot, memoryId, { homeDir });
     if (!result.removed) {
       throw new Error(`Memory item not found: ${memoryId}`);
     }
@@ -1003,7 +1008,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
     // FR-023/§9: purge removes the record, writes a tombstone, then sweeps
     // prompt-cache entries that embedded the purged record's text.
     const res = await mutateMemory(
-      { kind: 'project', projectRoot },
+      { kind: 'project', projectRoot, homeDir },
       { op: 'purge', payload: { id: memoryId } },
     );
     const handled = handleMutationResult(res, {
@@ -1016,10 +1021,10 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
   }
 
   if (subcommand === 'export') {
-    const data = await exportMemory(projectRoot);
+    const data = await exportMemory(projectRoot, { homeDir });
     // FR-023/025: defense-in-depth redaction at the CLI boundary too —
     // store.js exportMemory already redacts, this catches any future lane.
-    const { config } = await inspectRuntimeConfig(projectRoot);
+    const { config } = await inspectRuntimeConfig(projectRoot, { homeDir });
     const { payload: safe } = redactWritePayload({ meta: data }, { config });
     console.log(JSON.stringify(safe.meta, null, 2));
     return;