@ngockhoale/ukit 2.6.7 → 2.6.8

package/src/cli/commands/doctor.js

@@ -22,10 +22,11 @@ import {
   inspectProjectImportant,
   inspectProjectImportantWiring,
 } from '../../core/projectImportant.js';
+import { runDocContractChecks } from '../../core/docContracts.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
-const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway']);
-const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway';
+const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs']);
+const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway, --docs';
 
 export function printDoctorHelp() {
   console.log('Usage: ukit doctor [options]');
@@ -36,6 +37,7 @@ export function printDoctorHelp() {
   console.log('  --help, -h      Show this help message');
   console.log('  --skills        Also print a skill word-count/budget report');
   console.log('  --gateway       Live gateway probe (streaming + non-streaming); advisory only');
+  console.log('  --docs          Run doc-contract checks (manifests/documentation.yaml projects only)');
 }
 
 export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir = os.homedir() }) {
@@ -366,6 +368,36 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
     }
   }
 
+  // FR-007: doc-contract checks (DOC-203 validator) — only when the project root
+  // carries manifests/documentation.yaml (doc-governed maintainer repo). Downstream
+  // projects get a skip advisory; error-severity failures block via exitCode 1,
+  // warnings are advisory only.
+  let docContractErrors = false;
+  if (argv.includes('--docs')) {
+    const docManifestPath = path.join(projectRoot, 'manifests', 'documentation.yaml');
+    if (!(await pathExists(docManifestPath))) {
+      console.log('');
+      console.log('[UKit] Doc contract checks — not a doc-governed project — skipped (no manifests/documentation.yaml).');
+    } else {
+      const report = await runDocContractChecks({ rootDir: projectRoot });
+      console.log('');
+      console.log('[UKit] Doc contract checks:');
+      for (const check of report.checks) {
+        const mark = check.skipped ? '-' : ok(check.passed);
+        const severity = check.severity === 'warning' ? ' (warning)' : '';
+        console.log(`[UKit]   ${mark}  ${check.label}${severity}`);
+        if (check.detail) console.log(`[UKit]      detail: ${check.detail}`);
+        if (check.remedy && (!check.passed || check.severity === 'warning')) {
+          console.log(`[UKit]      remedy: ${check.remedy}`);
+        }
+      }
+      console.log(
+        `[UKit]   summary: ${report.summary.passed} passed, ${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.skipped} skipped`,
+      );
+      docContractErrors = report.summary.errors > 0;
+    }
+  }
+
   const allPassed = Object.values(checks).every(Boolean);
   const failedProjectChecks = projectChecks.filter(
     (check) => check.applicable !== false && !check.passed,
@@ -381,7 +413,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
     }
   }
 
-  if (!allPassed || blockingFailures.length > 0) {
+  if (!allPassed || blockingFailures.length > 0 || docContractErrors) {
     console.log('[UKit] Some checks failed.');
     if (!allPassed && blockingFailures.length === 0) {
       console.log('[UKit] Re-run `ukit install` to repair install-managed files.');

package/src/cli/commands/indexTools.js

@@ -10,6 +10,9 @@ import { deriveTaskRoute } from '../../index/taskRouting.js';
 import { queryCodeIndex, getFileOutline } from '../../index/queryIndex.js';
 import { triageBug } from '../../bug/triageBug.js';
 import { installIndexRefreshHooks, removeIndexRefreshHooks } from '../../index/gitHooks.js';
+import fs from 'node:fs/promises';
+import { INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, getArtifactPath } from '../../index/paths.js';
+import { computeIdentity, readSnapshot, guardLevel } from '../../core/codeintel/freshness.js';
 import {
   parseIndexArgs,
   CONTEXT_FLAG_DEFINITIONS,
@@ -221,6 +224,64 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (subcommand === 'status') {
+    // L0 freshness identity report (SPEC §7) — never refreshes, never throws.
+    const identity = await computeIdentity(projectRoot);
+    const snapshot = await readSnapshot(projectRoot);
+    const stale = !snapshot || snapshot.identity !== identity.identity;
+
+    console.log('[UKit] Index status:');
+    console.log(`identity: ${identity.identity}`);
+    console.log(`headSha: ${identity.headSha}`);
+    console.log(`overlayHash: ${identity.overlayHash}`);
+    console.log(`configHash: ${identity.configHash}`);
+    console.log(`snapshot: ${snapshot ? snapshot.identity : 'none'}`);
+    console.log(`stale: ${stale ? 'yes' : 'no'}`);
+
+    const artifacts = await collectArtifactAges(projectRoot);
+    if (artifacts.length === 0) {
+      console.log('artifacts: none (index not built)');
+    } else {
+      console.log('artifacts:');
+      for (const item of artifacts) {
+        console.log(`  ${item.name}: ${item.age}`);
+      }
+    }
+    return;
+  }
+
+  if (subcommand === 'doctor') {
+    // Freshness guard + artifact schema checks (SPEC §7). Exit non-zero when
+    // the recommended repair level is L2 or higher.
+    const guard = await guardLevel(projectRoot, { maxLevel: 'L4' });
+    const problems = [];
+
+    console.log('[UKit] Index doctor:');
+    console.log(`identity: ${guard.identity.identity}`);
+    console.log(`headSha: ${guard.identity.headSha}`);
+    console.log(`snapshot: ${guard.snapshot ? guard.snapshot.identity : 'none'}`);
+    console.log(`stale: ${guard.stale ? 'yes' : 'no'}`);
+    console.log(`recommendedLevel: ${guard.recommendedLevel}`);
+
+    const schemaIssues = await checkArtifactSchemas(projectRoot);
+    for (const issue of schemaIssues) {
+      problems.push(issue);
+      console.log(`problem: ${issue}`);
+    }
+    if (schemaIssues.length === 0) {
+      console.log('schema: ok');
+    }
+
+    const needsRepair = ['L2', 'L3', 'L4'].includes(guard.recommendedLevel) || problems.length > 0;
+    if (needsRepair) {
+      console.log('[UKit] Index needs repair. Run "ukit index build".');
+      process.exitCode = 1;
+    } else {
+      console.log('[UKit] Index healthy.');
+    }
+    return;
+  }
+
   if (subcommand === 'hooks') {
     const action = (rest[0] ?? 'install').toLowerCase();
     if (action === 'help' || action === '--help' || action === '-h') {
@@ -250,7 +311,7 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
 
 export function printIndexHelp() {
   console.log('UKit Index Commands');
-  console.log('Usage: ukit index <build|refresh|query|triage|context|verify|route> [args]');
+  console.log('Usage: ukit index <build|refresh|query|triage|context|verify|route|status|doctor> [args]');
   console.log('');
   console.log('Subcommands:');
   console.log('  build                 Build codebase index cache');
@@ -260,6 +321,8 @@ export function printIndexHelp() {
   console.log('  context "<intent>"    Suggest minimal file context with reasons');
   console.log('  verify "<intent>"     Suggest verification lane from indexed context');
   console.log('  route "<prompt>"      Suggest skill + context + verification next step');
+  console.log('  status                Show freshness identity, snapshot, artifact ages');
+  console.log('  doctor                Freshness guard + artifact schema checks');
   console.log('  hooks [install|remove]  Manage git-hook auto-refresh');
   console.log('');
   console.log('Aliases:');
@@ -275,6 +338,44 @@ function printIndexHooksHelp() {
   console.log('  ukit index hooks remove');
 }
 
+async function collectArtifactAges(rootDir) {
+  const entries = [];
+  for (const [key, fileName] of Object.entries(INDEX_ARTIFACTS)) {
+    try {
+      const stat = await fs.stat(getArtifactPath(rootDir, fileName));
+      const ageMs = Date.now() - stat.mtimeMs;
+      const ageMinutes = Math.max(0, Math.round(ageMs / 60000));
+      entries.push({ name: fileName, age: `${ageMinutes}m old` });
+    } catch {
+      // missing artifact — not listed
+    }
+  }
+  return entries;
+}
+
+async function checkArtifactSchemas(rootDir) {
+  const issues = [];
+  const required = ['meta', 'files', 'symbols'];
+  for (const key of required) {
+    const fileName = INDEX_ARTIFACTS[key];
+    let parsed;
+    try {
+      const raw = await fs.readFile(getArtifactPath(rootDir, fileName), 'utf8');
+      parsed = JSON.parse(raw);
+    } catch {
+      issues.push(`${fileName}: missing or unreadable`);
+      continue;
+    }
+    if (parsed?.schemaVersion !== INDEX_SCHEMA_VERSION) {
+      issues.push(`${fileName}: schemaVersion ${parsed?.schemaVersion ?? 'none'} != ${INDEX_SCHEMA_VERSION}`);
+    }
+    if (key !== 'meta' && !Array.isArray(parsed?.items)) {
+      issues.push(`${fileName}: items is not an array`);
+    }
+  }
+  return issues;
+}
+
 async function refreshIndexIfStale(rootDir) {
   const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
   const stale = await isIndexStale({

package/src/cli/commands/memory.js

@@ -7,6 +7,14 @@ import {
   resolvePatternCandidate,
   runProjectHygiene,
 } from '../../core/memory/store.js';
+import {
+  getRecord,
+  loadRecords,
+  queryRecords,
+  stats as v2Stats,
+  updateRecord,
+} from '../../core/memory/storeV2.js';
+import { runMigration } from '../../core/memory/migrate.js';
 import { getContextInjection, search } from '../../core/memory/retrieval.js';
 import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
@@ -26,6 +34,30 @@ function extractFlag(args, flag) {
 }
 
 async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
+  // 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);
+    if (config?.memoryV2?.enabled === false) v2Enabled = false;
+  } catch {
+    // unreadable config → default enabled
+  }
+  const records = v2Enabled ? await loadRecords(projectRoot) : [];
+  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);
+      for (const candidate of pending) {
+        results.push({ ...candidate, projectId });
+      }
+    }
+    return results;
+  }
+
   let entries = [];
   try {
     entries = await fs.readdir(runtimePaths.projectsDir, { withFileTypes: true });
@@ -45,6 +77,106 @@ async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
   return results;
 }
 
+// ---- `ukit memory v2` ops (SPEC §11) ----
+
+async function runMemoryV2(projectRoot, args) {
+  const [opRaw, ...rest] = args;
+  const op = (opRaw ?? 'list').toLowerCase();
+
+  if (op === 'list') {
+    const typeFlag = extractFlag(rest, '--type');
+    const scopeFlag = extractFlag(typeFlag.rest, '--scope');
+    const statusFlag = extractFlag(scopeFlag.rest, '--status');
+    const records = await queryRecords(projectRoot, {
+      type: typeFlag.value ?? undefined,
+      scope: scopeFlag.value ?? undefined,
+      status: statusFlag.value ?? undefined,
+    });
+    if (records.length === 0) {
+      console.log('[UKit] No memory v2 records found.');
+      return;
+    }
+    for (const record of records) {
+      const scopeLabel = record.project_id ?? record.scope;
+      console.log(`${record.id} [${record.type}/${scopeLabel}/${record.status}] — ${record.text}`);
+    }
+    return;
+  }
+
+  if (op === 'show') {
+    const id = rest.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory v2 show <id>');
+    }
+    const record = await getRecord(projectRoot, id);
+    if (!record) {
+      throw new Error(`Memory v2 record not found: ${id}`);
+    }
+    console.log(JSON.stringify(record, null, 2));
+    return;
+  }
+
+  if (op === 'promote') {
+    const id = rest.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory v2 promote <id>');
+    }
+    const record = await getRecord(projectRoot, id);
+    if (!record) {
+      throw new Error(`Memory v2 record not found: ${id}`);
+    }
+    if (record.type === 'project_rule') {
+      console.log(`[UKit] ${id} is already a project_rule — nothing to do.`);
+      return;
+    }
+    if (record.type !== 'derived_fact' && record.type !== 'episode') {
+      throw new Error(`Cannot promote ${record.type} records (only derived_fact or episode).`);
+    }
+    // Explicit approval only — no auto-promotion (SPEC §11,
+    // memoryV2.promotion.episodeToRuleRequiresApproval).
+    const updated = await updateRecord(projectRoot, id, {
+      type: 'project_rule',
+      scope: 'repo',
+      provenance: `${record.provenance ?? 'manual'};promoted-from:${record.id}`,
+    });
+    console.log(`[UKit] Promoted ${updated.id} → project_rule.`);
+    return;
+  }
+
+  if (op === 'stale') {
+    const id = rest.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory v2 stale <id>');
+    }
+    const updated = await updateRecord(projectRoot, id, { status: 'stale' });
+    if (!updated) {
+      throw new Error(`Memory v2 record not found: ${id}`);
+    }
+    console.log(`[UKit] Marked ${id} as stale.`);
+    return;
+  }
+
+  if (op === 'migrate') {
+    const dryRun = rest.includes('--dry-run');
+    const result = await runMigration(projectRoot, { dryRun });
+    if (dryRun) {
+      console.log(`[UKit] Dry-run: would migrate ${result.migrated} record(s), skip ${result.skipped}.`);
+      return;
+    }
+    if (result.migrated === 0) {
+      console.log('[UKit] Nothing to migrate (marker present or no legacy memory).');
+      return;
+    }
+    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);
+    console.log(`[UKit] v2 store: ${stats.total} record(s) — ${JSON.stringify(stats.byType)}`);
+    return;
+  }
+
+  throw new Error(`Unknown memory v2 op: ${op}. Expected list|show|promote|stale|migrate.`);
+}
+
 export async function runMemory({ projectRoot, argv = [] }) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   if (!(await pathExists(runtimePaths.runtimeRoot))) {
@@ -59,6 +191,11 @@ export async function runMemory({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (subcommand === 'v2') {
+    await runMemoryV2(projectRoot, rest);
+    return;
+  }
+
   if (subcommand === 'list') {
     if (rest.includes('--pending')) {
       const pending = await listAllPendingPatternCandidates(projectRoot, runtimePaths);

package/src/cli/index.js

@@ -6,6 +6,7 @@ import { runIndexTools } from './commands/indexTools.js';
 import { runStatus } from './commands/status.js';
 import { runMemory } from './commands/memory.js';
 import { runUpdate } from './commands/update.js';
+import { runCode } from './commands/code.js';
 
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
@@ -49,6 +50,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'code') {
+    await runCode({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'status') {
     await runStatus({ projectRoot, argv: commandArgv });
     return;
@@ -89,6 +95,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  doctor             Validate manifest, stack, docs, and UKit state');
     console.log('  uninstall          Remove all UKit-managed assets');
     console.log('  index              Codebase index tools (build/query/triage)');
+    console.log('  code               Context compiler surface (peek/search/context/impact)');
     console.log('  status             Show UKit runtime status');
     console.log('  memory             Inspect shared UKit memory');
     console.log('  update             Upgrade the global UKit CLI to the latest version');