@ngockhoale/ukit 1.1.6

package/src/core/runtimeConfig.js

@@ -0,0 +1,190 @@
+import fs from 'node:fs/promises';
+import { buildRuntimePaths } from './runtimePaths.js';
+
+const VALID_AGENTS = new Set(['claude-code', 'codex', 'antigravity', 'opencode']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeObjects(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override === undefined ? base : override;
+  }
+
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const current = merged[key];
+    if (isPlainObject(current) && isPlainObject(value)) {
+      merged[key] = mergeObjects(current, value);
+      continue;
+    }
+
+    merged[key] = value;
+  }
+
+  return merged;
+}
+
+function pushBooleanError(errors, value, label) {
+  if (typeof value !== 'boolean') {
+    errors.push(`${label} must be boolean.`);
+  }
+}
+
+function pushPositiveNumberError(errors, value, label) {
+  if (typeof value !== 'number' || Number.isNaN(value) || value <= 0) {
+    errors.push(`${label} must be a positive number.`);
+  }
+}
+
+export function buildDefaultRuntimeConfig(overrides = {}) {
+  const safeOverrides = isPlainObject(overrides) ? overrides : {};
+
+  return mergeObjects({
+    version: '1.1.6',
+    agent: 'claude-code',
+    compact: {
+      enabled: true,
+      tokenThreshold: 100_000,
+      contextRotDetection: true,
+      askBeforeDrop: true,
+    },
+    tokenPipeline: {
+      inputCompression: true,
+      outputCompression: true,
+      promptCache: true,
+    },
+    router: {
+      enabled: true,
+      defaultModel: 'claude-sonnet-4-6',
+      advisorModel: 'claude-opus-4-6',
+      advisorEnabled: true,
+      maxAdvisorCalls: 3,
+    },
+    memory: {
+      enabled: true,
+      autoCapture: true,
+      progressiveRetrieval: true,
+      maxInjectionTokens: 1000,
+      archiveAfterDays: 30,
+      maxSessions: 20,
+      redactSecrets: true,
+    },
+    validation: {
+      enabled: true,
+      autoRetry: true,
+      maxRetries: 1,
+      confidenceThreshold: 50,
+    },
+  }, safeOverrides);
+}
+
+export function validateRuntimeConfig(config) {
+  const errors = [];
+
+  if (!isPlainObject(config)) {
+    return { valid: false, errors: ['Runtime config root must be an object.'] };
+  }
+
+  if (typeof config.version !== 'string' || config.version.trim() === '') {
+    errors.push('version must be a non-empty string.');
+  }
+
+  if (!VALID_AGENTS.has(config.agent)) {
+    errors.push(`agent must be one of: ${[...VALID_AGENTS].join(', ')}.`);
+  }
+
+  if (!isPlainObject(config.compact)) {
+    errors.push('compact must be an object.');
+  } else {
+    pushBooleanError(errors, config.compact.enabled, 'compact.enabled');
+    pushPositiveNumberError(errors, config.compact.tokenThreshold, 'compact.tokenThreshold');
+    pushBooleanError(errors, config.compact.contextRotDetection, 'compact.contextRotDetection');
+    pushBooleanError(errors, config.compact.askBeforeDrop, 'compact.askBeforeDrop');
+  }
+
+  if (!isPlainObject(config.tokenPipeline)) {
+    errors.push('tokenPipeline must be an object.');
+  } else {
+    pushBooleanError(errors, config.tokenPipeline.inputCompression, 'tokenPipeline.inputCompression');
+    pushBooleanError(errors, config.tokenPipeline.outputCompression, 'tokenPipeline.outputCompression');
+    pushBooleanError(errors, config.tokenPipeline.promptCache, 'tokenPipeline.promptCache');
+  }
+
+  if (!isPlainObject(config.router)) {
+    errors.push('router must be an object.');
+  } else {
+    pushBooleanError(errors, config.router.enabled, 'router.enabled');
+    if (typeof config.router.defaultModel !== 'string' || config.router.defaultModel.trim() == '') {
+      errors.push('router.defaultModel must be a non-empty string.');
+    }
+    if (typeof config.router.advisorModel !== 'string' || config.router.advisorModel.trim() == '') {
+      errors.push('router.advisorModel must be a non-empty string.');
+    }
+    pushBooleanError(errors, config.router.advisorEnabled, 'router.advisorEnabled');
+    pushPositiveNumberError(errors, config.router.maxAdvisorCalls, 'router.maxAdvisorCalls');
+  }
+
+  if (!isPlainObject(config.memory)) {
+    errors.push('memory must be an object.');
+  } else {
+    pushBooleanError(errors, config.memory.enabled, 'memory.enabled');
+    pushBooleanError(errors, config.memory.autoCapture, 'memory.autoCapture');
+    pushBooleanError(errors, config.memory.progressiveRetrieval, 'memory.progressiveRetrieval');
+    pushPositiveNumberError(errors, config.memory.maxInjectionTokens, 'memory.maxInjectionTokens');
+    pushPositiveNumberError(errors, config.memory.archiveAfterDays, 'memory.archiveAfterDays');
+    pushPositiveNumberError(errors, config.memory.maxSessions, 'memory.maxSessions');
+    pushBooleanError(errors, config.memory.redactSecrets, 'memory.redactSecrets');
+  }
+
+  if (!isPlainObject(config.validation)) {
+    errors.push('validation must be an object.');
+  } else {
+    pushBooleanError(errors, config.validation.enabled, 'validation.enabled');
+    pushBooleanError(errors, config.validation.autoRetry, 'validation.autoRetry');
+    pushPositiveNumberError(errors, config.validation.maxRetries, 'validation.maxRetries');
+    pushPositiveNumberError(errors, config.validation.confidenceThreshold, 'validation.confidenceThreshold');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+export async function inspectRuntimeConfig(projectRoot) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  let exists = false;
+  let rawConfig = null;
+  let parseError = null;
+
+  try {
+    const raw = await fs.readFile(runtimePaths.configPath, 'utf8');
+    exists = true;
+    rawConfig = JSON.parse(raw);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      exists = true;
+      parseError = error?.message ?? String(error);
+    }
+  }
+
+  const config = buildDefaultRuntimeConfig(rawConfig);
+  const validation = validateRuntimeConfig(config);
+  const errors = parseError ? [`config.json parse error: ${parseError}`, ...validation.errors] : validation.errors;
+
+  return {
+    exists,
+    rawConfig,
+    config,
+    parseError,
+    valid: exists && !parseError && validation.valid,
+    errors,
+  };
+}
+
+export async function loadRuntimeConfig(projectRoot) {
+  const inspection = await inspectRuntimeConfig(projectRoot);
+  return inspection.config;
+}

package/src/core/runtimePaths.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+
+export function buildRuntimePaths(projectRoot) {
+  const runtimeRoot = path.join(projectRoot, '.ukit');
+  const storageRoot = path.join(runtimeRoot, 'storage');
+  const memoryRoot = path.join(storageRoot, 'memory');
+  const cacheRoot = path.join(storageRoot, 'cache');
+
+  return {
+    runtimeRoot,
+    storageRoot,
+    cacheRoot,
+    memoryRoot,
+    teeCacheDir: path.join(cacheRoot, 'tee'),
+    configPath: path.join(storageRoot, 'config.json'),
+    promptCachePath: path.join(cacheRoot, 'prompt-cache.json'),
+    compactHistoryPath: path.join(cacheRoot, 'compact-history.json'),
+    compactPressurePath: path.join(cacheRoot, 'compact-pressure.json'),
+    outputHistoryPath: path.join(cacheRoot, 'output-history.json'),
+    userMemoryPath: path.join(memoryRoot, 'user.json'),
+    projectsDir: path.join(memoryRoot, 'projects'),
+    sessionsDir: path.join(memoryRoot, 'sessions'),
+  };
+}

package/src/core/status.js

@@ -0,0 +1,186 @@
+import path from 'node:path';
+import { pathExists, readJsonIfExists } from './fileOps.js';
+import { buildRuntimePaths } from './runtimePaths.js';
+import { loadRuntimeConfig } from './runtimeConfig.js';
+import { summarizeOutputHistory } from './output/index.js';
+import { buildPromptCacheStats } from './token/index.js';
+import { countMemoryItems } from './memory/store.js';
+import { readCompactPressureState } from './compact/threshold.js';
+import { detectProjectContext } from '../context/detectProjectContext.js';
+
+function formatPrimaryAgent(agentKey) {
+  if (agentKey === 'claude-code') return 'Claude Code';
+  if (agentKey === 'codex') return 'OpenAI Codex';
+  if (agentKey === 'antigravity') return 'Antigravity';
+  if (agentKey === 'opencode') return 'OpenCode';
+  return agentKey || 'Unknown';
+}
+
+async function detectAdapterLabels(projectRoot, primaryAgent) {
+  const labels = [formatPrimaryAgent(primaryAgent)];
+
+  const checks = [
+    { label: 'Antigravity', path: '.antigravity/README.md' },
+    { label: 'OpenAI Codex', path: '.codex/settings.json' },
+    { label: 'OpenCode', path: 'opencode.json' },
+  ];
+
+  for (const check of checks) {
+    if (await pathExists(path.join(projectRoot, check.path))) {
+      labels.push(check.label);
+    }
+  }
+
+  return [...new Set(labels)];
+}
+
+function normalizeCompactEntries(rawHistory) {
+  if (Array.isArray(rawHistory)) {
+    return rawHistory;
+  }
+
+  if (Array.isArray(rawHistory?.entries)) {
+    return rawHistory.entries;
+  }
+
+  return [];
+}
+
+function buildCompactSummary(entries) {
+  if (entries.length === 0) {
+    return {
+      lastCompact: 'never',
+      savingsLabel: 'n/a',
+      bySource: [],
+    };
+  }
+
+  const sorted = [...entries].sort((left, right) => (left.timestamp ?? 0) - (right.timestamp ?? 0));
+  const latest = sorted[sorted.length - 1];
+  const totalBefore = sorted.reduce((sum, item) => sum + (item.tokensBefore ?? 0), 0);
+  const totalSaved = sorted.reduce((sum, item) => sum + (item.savedTokens ?? 0), 0);
+  const percentage = totalBefore > 0 ? Math.trunc((totalSaved / totalBefore) * 100) : 0;
+  const bySourceMap = new Map();
+
+  for (const entry of sorted) {
+    const source = typeof entry.source === 'string' && entry.source.trim()
+      ? entry.source.trim()
+      : 'unknown';
+    const bucket = bySourceMap.get(source) ?? {
+      source,
+      entryCount: 0,
+      totalBefore: 0,
+      totalSaved: 0,
+    };
+    bucket.entryCount += 1;
+    bucket.totalBefore += Number(entry.tokensBefore ?? 0);
+    bucket.totalSaved += Number(entry.savedTokens ?? 0);
+    bySourceMap.set(source, bucket);
+  }
+
+  const bySource = [...bySourceMap.values()]
+    .map((bucket) => ({
+      ...bucket,
+      savingsLabel: bucket.entryCount > 0 && bucket.totalBefore > 0
+        ? `${Math.trunc((bucket.totalSaved / bucket.totalBefore) * 100)}% avg`
+        : 'n/a',
+    }))
+    .sort((left, right) => (
+      right.totalSaved - left.totalSaved
+      || right.entryCount - left.entryCount
+      || left.source.localeCompare(right.source)
+    ));
+
+  return {
+    lastCompact: latest.timestamp ? new Date(latest.timestamp).toISOString() : 'unknown',
+    savingsLabel: `${percentage}% avg`,
+    bySource,
+  };
+}
+
+function padLabel(label) {
+  return `${label}:`.padEnd(15, ' ');
+}
+
+function formatBreakdown(entries, formatter, { fallback = 'n/a', maxItems = 3 } = {}) {
+  const normalized = Array.isArray(entries) ? entries : [];
+  if (normalized.length === 0) {
+    return fallback;
+  }
+
+  return normalized
+    .slice(0, maxItems)
+    .map((entry) => formatter(entry))
+    .filter(Boolean)
+    .join('; ') || fallback;
+}
+
+function formatRecoveryLabel(count) {
+  if (!count) return '';
+  return ` / ${count} recover${count === 1 ? 'y' : 'ies'}`;
+}
+
+export async function buildStatusReport(projectRoot) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const runtimeExists = await pathExists(runtimePaths.runtimeRoot);
+  if (!runtimeExists) {
+    throw new Error('Shared UKit runtime not found. Run `ukit install` first.');
+  }
+
+  const projectContext = await detectProjectContext(projectRoot);
+  const config = await loadRuntimeConfig(projectRoot);
+  const compactHistory = normalizeCompactEntries(await readJsonIfExists(runtimePaths.compactHistoryPath));
+  const compactSummary = buildCompactSummary(compactHistory);
+  const compactPressure = await readCompactPressureState(projectRoot, config);
+  const promptCacheStats = buildPromptCacheStats(await readJsonIfExists(runtimePaths.promptCachePath));
+  const outputCompressionStats = summarizeOutputHistory(await readJsonIfExists(runtimePaths.outputHistoryPath));
+  const memoryCounts = await countMemoryItems(projectRoot);
+  const adapters = await detectAdapterLabels(projectRoot, config.agent);
+
+  return {
+    version: config.version,
+    projectName: projectContext.project.name,
+    adapters,
+    memoryCounts,
+    lastCompact: compactSummary.lastCompact,
+    tokenSavings: compactSummary.savingsLabel,
+    compactLanes: formatBreakdown(
+      compactSummary.bySource,
+      (entry) => `${entry.source} ${entry.entryCount} / ${entry.savingsLabel}`,
+    ),
+    contextPressure: `${compactPressure.estimatedTotalTokens} est / soft ${compactPressure.softThreshold} / hard ${compactPressure.hardThreshold} (${compactPressure.phase})`,
+    thresholdCompact: `${compactPressure.stats.thresholdHits} runs (soft ${compactPressure.stats.softHits} / hard ${compactPressure.stats.hardHits})`,
+    promptCache: `${promptCacheStats.entryCount} entries / ${promptCacheStats.totalHits} hits`,
+    cacheLanes: formatBreakdown(
+      promptCacheStats.byKind,
+      (entry) => `${entry.kind} ${entry.totalHits} hit${entry.totalHits === 1 ? '' : 's'}`,
+    ),
+    outputCompression: `${outputCompressionStats.entryCount} entries / ${outputCompressionStats.savingsLabel}${formatRecoveryLabel(outputCompressionStats.recoveryCount)}`,
+    outputLanes: formatBreakdown(
+      outputCompressionStats.byProfile,
+      (entry) => `${entry.profile} ${entry.entryCount} / ${entry.savingsLabel}`,
+    ),
+    defaultModel: config.router.defaultModel,
+    advisorEnabled: Boolean(config.router.advisorEnabled),
+  };
+}
+
+export function formatStatusReport(report) {
+  return [
+    `UKit v${report.version} — Status`,
+    '─────────────────────',
+    `${padLabel('Project')} ${report.projectName}`,
+    `${padLabel('Adapters')} ${report.adapters.join(', ')}`,
+    `${padLabel('Memory items')} ${report.memoryCounts.projectCount} project / ${report.memoryCounts.sessionCount} session / ${report.memoryCounts.userCount} user`,
+    `${padLabel('Last compact')} ${report.lastCompact}`,
+    `${padLabel('Token savings')} ${report.tokenSavings}`,
+    `${padLabel('Compact lanes')} ${report.compactLanes}`,
+    `${padLabel('Ctx pressure')} ${report.contextPressure}`,
+    `${padLabel('Threshold cmp')} ${report.thresholdCompact}`,
+    `${padLabel('Prompt cache')} ${report.promptCache}`,
+    `${padLabel('Cache lanes')} ${report.cacheLanes}`,
+    `${padLabel('Output comp.')} ${report.outputCompression}`,
+    `${padLabel('Output lanes')} ${report.outputLanes}`,
+    `${padLabel('Model')} ${report.defaultModel} (advisor: ${report.advisorEnabled ? 'on' : 'off'})`,
+  ];
+}