@ngockhoale/ukit 1.1.6

package/src/core/token/index.js

@@ -0,0 +1,328 @@
+import crypto from 'node:crypto';
+import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { buildRuntimePaths } from '../runtimePaths.js';
+
+export const DEFAULT_PROMPT_CACHE_MAX_ENTRIES = 20;
+
+const HEADER_RE = /^\s*(?:#{1,6}\s|={3,}|-{3,})/;
+const CODE_FENCE_RE = /^\s*```/;
+const BULLET_RE = /^(\s*[-*]\s+)(.*)$/;
+const COMMAND_RE = /^\s*(?:[$>#]\s*)?(?:node|npm|pnpm|yarn|bun|python(?:3)?|pip|git|docker|kubectl|make|cargo|go|java|pytest|vitest|npx)\b/i;
+const STRUCTURED_LINE_RE = /https?:\/\/|(?:^|[\s(])(?:src|tests?|docs|ukit|\.claude|\.codex|app|lib|packages|scripts)\//i;
+const VERBOSE_REPLACEMENTS = [
+  [/\bplease\b/gi, ''],
+  [/\bremember to\b/gi, ''],
+  [/\bmake sure to\b/gi, 'ensure '],
+  [/\bin order to\b/gi, 'to'],
+  [/\bfor the current task\b/gi, 'for this task'],
+  [/\bcurrent task\b/gi, 'task'],
+  [/\bprevious context block\b/gi, 'context block'],
+  [/\bshould still\b/gi, 'still'],
+  [/\bdo not wait for the user to\b/gi, "don't wait for the user to"],
+];
+
+export function estimateTokenCount(value) {
+  const text = String(value ?? '').trim();
+  if (!text) {
+    return 0;
+  }
+
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+export function buildCompactMachineKey(prefix, payload = {}) {
+  return `${prefix}:${crypto.createHash('sha256').update(JSON.stringify(payload)).digest('base64url')}`;
+}
+
+function isStructuredLine(line) {
+  return (
+    CODE_FENCE_RE.test(line)
+    || HEADER_RE.test(line)
+    || COMMAND_RE.test(line)
+    || STRUCTURED_LINE_RE.test(line)
+    || line.includes('`')
+  );
+}
+
+function normalizeWhitespace(value) {
+  return value
+    .replace(/\s+\|\s+/g, ' | ')
+    .replace(/\s*[:;]\s*/g, ': ')
+    .replace(/\s*,\s*/g, ', ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function compressLine(line) {
+  const raw = String(line ?? '');
+  if (!raw.trim()) {
+    return '';
+  }
+
+  const trimmed = raw.trim();
+  if (isStructuredLine(trimmed)) {
+    return trimmed;
+  }
+
+  const bulletMatch = raw.match(BULLET_RE);
+  const prefix = bulletMatch ? '- ' : '';
+  let next = bulletMatch ? bulletMatch[2].trim() : trimmed;
+
+  for (const [pattern, replacement] of VERBOSE_REPLACEMENTS) {
+    next = next.replace(pattern, replacement);
+  }
+
+  next = normalizeWhitespace(next);
+  return prefix ? `${prefix}${next}` : next;
+}
+
+export function compressMarkdownLines(
+  lines,
+  {
+    maxTokens = 300,
+    maxLines = 12,
+    preserveFirstLine = true,
+  } = {},
+) {
+  const sourceLines = Array.isArray(lines) ? lines : [];
+  const selected = [];
+  const seen = new Set();
+  let usedTokens = 0;
+  let nonEmptyCount = 0;
+  let pendingBlankLine = false;
+
+  for (const [index, line] of sourceLines.entries()) {
+    const compressed = compressLine(line);
+    if (!compressed) {
+      pendingBlankLine = selected.length > 0 && selected[selected.length - 1] !== '';
+      continue;
+    }
+
+    const dedupeKey = compressed.toLowerCase();
+    if (seen.has(dedupeKey)) {
+      continue;
+    }
+
+    const tokens = estimateTokenCount(compressed);
+    const wouldOverflow = selected.length > 0 && (usedTokens + tokens) > maxTokens;
+    const wouldExceedLines = index > 0 && nonEmptyCount >= maxLines;
+
+    if (wouldOverflow || wouldExceedLines) {
+      break;
+    }
+
+    if (pendingBlankLine && selected.length > 0) {
+      selected.push('');
+      pendingBlankLine = false;
+    }
+
+    selected.push(compressed);
+    seen.add(dedupeKey);
+    usedTokens += tokens;
+    nonEmptyCount += 1;
+  }
+
+  if (preserveFirstLine && selected.length === 0 && sourceLines.length > 0) {
+    const fallback = compressLine(sourceLines[0]);
+    if (fallback) {
+      return [fallback];
+    }
+  }
+
+  return selected;
+}
+
+export function compressPromptBlock(text, options = {}) {
+  const rawText = String(text ?? '');
+  const rawLines = rawText.split(/\r?\n/);
+  const compactedLines = compressMarkdownLines(rawLines, options);
+  const compactedText = compactedLines.join('\n').trim();
+  const tokensBefore = estimateTokenCount(rawText);
+  const tokensAfter = estimateTokenCount(compactedText);
+
+  return {
+    text: compactedText,
+    tokensBefore,
+    tokensAfter,
+    savedTokens: Math.max(0, tokensBefore - tokensAfter),
+  };
+}
+
+function normalizePromptCacheEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+
+  const requestKey = typeof entry.requestKey === 'string' ? entry.requestKey.trim() : '';
+  if (!requestKey) {
+    return null;
+  }
+
+  const updatedAt = Number(entry.updatedAt);
+  const hitCount = Number(entry.hitCount);
+  const lastHitAt = Number(entry.lastHitAt);
+  const normalizedEntry = {
+    ...entry,
+    requestKey,
+    updatedAt: Number.isFinite(updatedAt) ? updatedAt : Date.now(),
+    hitCount: Number.isFinite(hitCount) && hitCount >= 0 ? hitCount : 0,
+    lastHitAt: Number.isFinite(lastHitAt) ? lastHitAt : null,
+  };
+  delete normalizedEntry.entries;
+  return normalizedEntry;
+}
+
+function normalizePromptCacheDocument(raw, { maxEntries = DEFAULT_PROMPT_CACHE_MAX_ENTRIES } = {}) {
+  const candidates = [];
+
+  if (Array.isArray(raw?.entries)) {
+    candidates.push(...raw.entries);
+  }
+
+  if (
+    !Array.isArray(raw?.entries)
+    && raw
+    && typeof raw === 'object'
+    && typeof raw.requestKey === 'string'
+    && raw.requestKey.trim()
+  ) {
+    candidates.push(raw);
+  }
+
+  const entries = candidates
+    .map((entry) => normalizePromptCacheEntry(entry))
+    .filter(Boolean)
+    .sort((left, right) => (right.updatedAt ?? 0) - (left.updatedAt ?? 0))
+    .filter((entry, index, list) => list.findIndex((candidate) => candidate.requestKey === entry.requestKey) === index)
+    .slice(0, maxEntries);
+
+  return {
+    entries,
+  };
+}
+
+async function readPromptCacheDocument(projectRoot, options = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const raw = await readJsonIfExists(runtimePaths.promptCachePath);
+  return normalizePromptCacheDocument(raw, options);
+}
+
+async function writePromptCacheDocument(projectRoot, document) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  await writeJson(runtimePaths.promptCachePath, document);
+}
+
+export async function readPromptCache(projectRoot, options = {}) {
+  return readPromptCacheDocument(projectRoot, options);
+}
+
+export async function readPromptCacheEntry(
+  projectRoot,
+  requestKey,
+  {
+    maxEntries = DEFAULT_PROMPT_CACHE_MAX_ENTRIES,
+    touch = false,
+  } = {},
+) {
+  if (typeof requestKey !== 'string' || !requestKey.trim()) {
+    return null;
+  }
+
+  const cache = await readPromptCacheDocument(projectRoot, { maxEntries });
+  const entryIndex = cache.entries.findIndex((entry) => entry.requestKey === requestKey);
+  if (entryIndex < 0) {
+    return null;
+  }
+
+  const entry = cache.entries[entryIndex];
+  if (!touch) {
+    return entry;
+  }
+
+  const touchedEntry = {
+    ...entry,
+    updatedAt: Date.now(),
+    lastHitAt: Date.now(),
+    hitCount: (entry.hitCount ?? 0) + 1,
+  };
+  const entries = [
+    touchedEntry,
+    ...cache.entries.slice(0, entryIndex),
+    ...cache.entries.slice(entryIndex + 1),
+  ].slice(0, maxEntries);
+  const nextDocument = normalizePromptCacheDocument({ entries }, { maxEntries });
+  await writePromptCacheDocument(projectRoot, nextDocument);
+  return nextDocument.entries[0] ?? touchedEntry;
+}
+
+export async function writePromptCacheEntry(
+  projectRoot,
+  entry,
+  {
+    maxEntries = DEFAULT_PROMPT_CACHE_MAX_ENTRIES,
+  } = {},
+) {
+  const normalizedEntry = normalizePromptCacheEntry(entry);
+  if (!normalizedEntry) {
+    return readPromptCacheDocument(projectRoot, { maxEntries });
+  }
+
+  const cache = await readPromptCacheDocument(projectRoot, { maxEntries });
+  const entries = [
+    normalizedEntry,
+    ...cache.entries.filter((existingEntry) => existingEntry.requestKey !== normalizedEntry.requestKey),
+  ].slice(0, maxEntries);
+  const nextDocument = normalizePromptCacheDocument({ entries }, { maxEntries });
+  await writePromptCacheDocument(projectRoot, nextDocument);
+  return nextDocument;
+}
+
+export function buildPromptCacheStats(rawCache) {
+  const cache = normalizePromptCacheDocument(rawCache);
+  const totalEntries = cache.entries.length;
+  const totalHits = cache.entries.reduce((sum, entry) => sum + (entry.hitCount ?? 0), 0);
+  const totalBefore = cache.entries.reduce((sum, entry) => sum + (entry.tokensBefore ?? 0), 0);
+  const totalSaved = cache.entries.reduce((sum, entry) => sum + (entry.savedTokens ?? 0), 0);
+  const savingsPercent = totalBefore > 0 ? Math.trunc((totalSaved / totalBefore) * 100) : 0;
+  const byKindMap = new Map();
+
+  for (const entry of cache.entries) {
+    const kind = typeof entry.kind === 'string' && entry.kind.trim()
+      ? entry.kind.trim()
+      : 'unknown';
+    const bucket = byKindMap.get(kind) ?? {
+      kind,
+      entryCount: 0,
+      totalHits: 0,
+      totalBefore: 0,
+      totalSaved: 0,
+    };
+    bucket.entryCount += 1;
+    bucket.totalHits += Number(entry.hitCount ?? 0);
+    bucket.totalBefore += Number(entry.tokensBefore ?? 0);
+    bucket.totalSaved += Number(entry.savedTokens ?? 0);
+    byKindMap.set(kind, bucket);
+  }
+
+  const byKind = [...byKindMap.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.totalHits - left.totalHits
+      || right.totalSaved - left.totalSaved
+      || left.kind.localeCompare(right.kind)
+    ));
+
+  return {
+    entryCount: totalEntries,
+    totalHits,
+    totalBefore,
+    totalSaved,
+    savingsLabel: totalEntries > 0 && totalBefore > 0 ? `${savingsPercent}% avg` : 'n/a',
+    byKind,
+  };
+}

package/src/core/uninstall.js

@@ -0,0 +1,246 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  readJsonIfExists,
+  removeLinkOrDir,
+  removeLinkOnly,
+  resolveProjectRelativePath,
+} from './fileOps.js';
+import { removeGitignoreBlock } from './ensureGitignore.js';
+
+async function isDirEmpty(dirPath) {
+  try {
+    const entries = await fs.readdir(dirPath);
+    return entries.length === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function cleanupEmptyParents(targetPath, projectRoot) {
+  let currentDir = path.dirname(targetPath);
+  const stopDir = path.resolve(projectRoot);
+
+  while (currentDir.startsWith(stopDir) && currentDir !== stopDir) {
+    let stat;
+    try {
+      stat = await fs.lstat(currentDir);
+    } catch {
+      currentDir = path.dirname(currentDir);
+      continue;
+    }
+
+    if (!stat.isDirectory()) {
+      break;
+    }
+
+    if (!(await isDirEmpty(currentDir))) {
+      break;
+    }
+
+    await fs.rmdir(currentDir);
+    currentDir = path.dirname(currentDir);
+  }
+}
+
+// Use lstat (not access) so broken symlinks are also detected as existing.
+async function pathExistsLstat(targetPath) {
+  try {
+    await fs.lstat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const ALLOWED_UNINSTALL_PREFIXES = [
+  'CLAUDE.md',
+  'AGENTS.md',
+  'docs/',
+  '.claude/',
+  '.antigravity/',
+  '.codex/',
+  '.ukit/',
+  'opencode.json',
+];
+
+function normalizeToProjectRelative(projectRoot, absolutePath) {
+  const root = path.resolve(projectRoot);
+  const relative = path.relative(root, absolutePath);
+  if (!relative) {
+    return null;
+  }
+  return relative.replace(/\\/g, '/');
+}
+
+function isAllowedProjectPath(relativePath) {
+  if (!relativePath) {
+    return false;
+  }
+
+  return ALLOWED_UNINSTALL_PREFIXES.some((prefix) => {
+    if (prefix.endsWith('/')) {
+      // Only allow descendants under managed roots, never the root directory
+      // itself (e.g. ".claude"). Deleting the root could remove user content.
+      return relativePath.startsWith(prefix);
+    }
+    return relativePath === prefix;
+  });
+}
+
+function isSameOrDescendantProjectPath(candidatePath, parentPath) {
+  if (!candidatePath || !parentPath) {
+    return false;
+  }
+
+  return candidatePath === parentPath || candidatePath.startsWith(`${parentPath}/`);
+}
+
+// Hardcoded fallback for installs that predate file tracking (no 'files' field
+// in install.json). New installs always have a 'files' list, so this fallback
+// only applies when upgrading from a very old UKit version.
+function buildFallbackPaths(projectRoot) {
+  const stateDir = path.join(projectRoot, '.claude', 'ukit', '.ukit');
+  return {
+    regularPaths: [
+      path.join(projectRoot, 'CLAUDE.md'),
+      path.join(projectRoot, 'AGENTS.md'),
+      path.join(projectRoot, '.claude', 'commands', 'ukit.md'),
+      path.join(projectRoot, '.claude', 'ukit', 'mcp'),
+      path.join(projectRoot, '.claude', 'ukit', 'scripts', 'setup-mcp.sh'),
+      path.join(projectRoot, '.claude', 'ukit', '.env.example'),
+      path.join(projectRoot, '.claude', 'ukit', 'permission-usage.json'),
+      path.join(projectRoot, '.claude', 'ukit', 'permission-audit.log'),
+      path.join(projectRoot, '.antigravity', 'rules', 'rules.md'),
+      path.join(projectRoot, '.antigravity', 'README.md'),
+      path.join(projectRoot, '.codex', 'README.md'),
+      path.join(projectRoot, 'opencode.json'),
+      path.join(projectRoot, '.ukit'),
+      stateDir,
+    ],
+    linkPaths: [
+      path.join(projectRoot, '.antigravity', 'skills'),
+      path.join(projectRoot, '.antigravity', 'ukit'),
+      path.join(projectRoot, '.codex', 'skills'),
+      path.join(projectRoot, '.codex', 'ukit'),
+    ],
+  };
+}
+
+export async function uninstallUkit({ projectRoot, dryRun = false }) {
+  const installMetaPath = path.join(projectRoot, '.claude', 'ukit', '.ukit', 'install.json');
+
+  // Read and validate install.json — checking existence alone is not sufficient.
+  // An attacker (or confused user) could forge the file to trigger uninstall of
+  // the hardcoded managed paths. Requiring 'tool: ukit' ensures the file was
+  // written by the UKit installer, not created manually.
+  const installData = await readJsonIfExists(installMetaPath);
+  if (!installData || installData.tool !== 'ukit') {
+    return { removed: 0, attempted: 0, wasInstalled: false };
+  }
+
+  // Build the deletion list. When install.json contains a 'files' manifest (written
+  // by new UKit versions), use it for precise ownership — only delete files UKit
+  // actually created. Fall back to the hardcoded list for old installs.
+  let regularPaths;
+  let linkPaths;
+
+  const stateDir = path.join(projectRoot, '.claude', 'ukit', '.ukit');
+
+  if (Array.isArray(installData.files)) {
+    // New format: tracked files give us ownership metadata even when the list is
+    // empty. Skip invalid entries to avoid path traversal.
+    regularPaths = [stateDir]; // always delete state dir — it's always UKit-owned
+    linkPaths = [];
+
+    const skipped = [];
+    const trackedEntries = [];
+
+    for (const entry of installData.files) {
+      const relPath = typeof entry === 'string' ? entry : entry?.p;
+      const type = typeof entry === 'string' ? 'file' : typeof entry?.t === 'string' ? entry.t : 'file';
+      const absolutePath = resolveProjectRelativePath(projectRoot, relPath);
+      if (!absolutePath) {
+        continue;
+      }
+
+      const normalizedRelative = normalizeToProjectRelative(projectRoot, absolutePath);
+      if (!isAllowedProjectPath(normalizedRelative)) {
+        skipped.push(relPath ?? normalizedRelative ?? absolutePath);
+        continue;
+      }
+
+      trackedEntries.push({ absolutePath, normalizedRelative, type });
+    }
+
+    const trackedLinkRelativePaths = [
+      ...new Set(trackedEntries.filter((entry) => entry.type === 'link').map((entry) => entry.normalizedRelative)),
+    ];
+
+    for (const entry of trackedEntries) {
+      if (entry.type === 'link') {
+        linkPaths.push(entry.absolutePath);
+        continue;
+      }
+
+      const isUnderTrackedLinkPath = trackedLinkRelativePaths.some((linkRelativePath) =>
+        isSameOrDescendantProjectPath(entry.normalizedRelative, linkRelativePath),
+      );
+
+      if (isUnderTrackedLinkPath) {
+        skipped.push(entry.normalizedRelative);
+        continue;
+      }
+
+      regularPaths.push(entry.absolutePath);
+    }
+
+    if (skipped.length > 0 && dryRun) {
+      console.warn('[UKit] Skipping invalid uninstall paths from install metadata:', skipped);
+    }
+  } else {
+    // Old format (no files list): fall back to hardcoded managed paths.
+    // NOTE: docs/PROJECT.md, MEMORY.md, WORKLOG.md are intentionally excluded.
+    // These are user-created content (mergeStrategy: skip) — deleting them
+    // would cause data loss. Users must remove them manually if desired.
+    const fallback = buildFallbackPaths(projectRoot);
+    regularPaths = fallback.regularPaths;
+    linkPaths = fallback.linkPaths;
+  }
+
+  const allEntries = [
+    ...regularPaths.map((abs) => ({ abs, useLink: false })),
+    ...linkPaths.map((abs) => ({ abs, useLink: true })),
+  ];
+
+  if (dryRun) {
+    // Use lstat (not access) so broken symlinks are included in the report.
+    const wouldRemove = [];
+    for (const { abs } of allEntries) {
+      if (await pathExistsLstat(abs)) wouldRemove.push(abs);
+    }
+    return { removed: 0, attempted: allEntries.length, wasInstalled: true, wouldRemove };
+  }
+
+  // Remove all paths in parallel
+  const results = await Promise.all(
+    allEntries.map(({ abs, useLink }) => {
+      const remove = useLink ? removeLinkOnly : removeLinkOrDir;
+      return remove(abs).then((didRemove) => ({ abs, didRemove }));
+    }),
+  );
+
+  // Clean up .gitignore block added during install
+  await removeGitignoreBlock(projectRoot);
+
+  // Cleanup empty parent directories sequentially (order matters)
+  let removed = 0;
+  for (const { abs, didRemove } of results) {
+    if (didRemove) {
+      removed += 1;
+      await cleanupEmptyParents(abs, projectRoot);
+    }
+  }
+
+  return { removed, attempted: allEntries.length, wasInstalled: true };
+}

package/src/core/validation/confidence.js

@@ -0,0 +1,89 @@
+const HEDGING_WORDS = [
+  'maybe',
+  'might',
+  'i think',
+  'probably',
+  'possibly',
+  'could be',
+  'perhaps',
+  'có thể',
+  'chắc là',
+  'hình như',
+];
+
+const VERIFICATION_WORDS = [
+  'verified',
+  'tested',
+  'passes',
+  'passed',
+  'checked',
+  'confirmed',
+  'validated',
+  'đã test',
+  'đã kiểm tra',
+];
+
+function normalize(text) {
+  return String(text ?? '').toLowerCase();
+}
+
+function buildResult(score, factors) {
+  const clamped = Math.max(0, Math.min(100, Math.round(score)));
+  const level = clamped >= 80 ? 'high' : clamped >= 50 ? 'medium' : 'low';
+  const action = clamped >= 80 ? 'respond' : clamped >= 50 ? 'warn' : 'clarify';
+
+  return {
+    score: clamped,
+    level,
+    factors,
+    action,
+  };
+}
+
+export function scoreConfidence(output, taskType, context = '') {
+  const normalizedOutput = normalize(output);
+  const normalizedContext = normalize(context);
+  const factors = [];
+  let score = 50;
+
+  if (normalizedContext.trim().length >= 24) {
+    score += 15;
+    factors.push({ name: 'context_availability', impact: 'positive', reason: 'Enough task context is available.' });
+  } else {
+    score -= 20;
+    factors.push({ name: 'context_availability', impact: 'negative', reason: 'Very little context is available.' });
+  }
+
+  if (normalizedOutput.length >= 60 && !HEDGING_WORDS.some((word) => normalizedOutput.includes(word))) {
+    score += 15;
+    factors.push({ name: 'task_clarity', impact: 'positive', reason: 'Output is specific and direct.' });
+  } else if (normalizedOutput.length < 30) {
+    score -= 10;
+    factors.push({ name: 'task_clarity', impact: 'negative', reason: 'Output is too short to inspire confidence.' });
+  }
+
+  const hedges = HEDGING_WORDS.filter((word) => normalizedOutput.includes(word));
+  if (hedges.length > 0) {
+    score -= 30;
+    factors.push({ name: 'model_certainty', impact: 'negative', reason: `Hedging language detected: ${hedges.join(', ')}.` });
+  } else {
+    score += 10;
+    factors.push({ name: 'model_certainty', impact: 'positive', reason: 'Language is direct rather than hedged.' });
+  }
+
+  const verificationHits = VERIFICATION_WORDS.filter((word) => normalizedOutput.includes(word));
+  if (verificationHits.length > 0) {
+    score += 20;
+    factors.push({ name: 'verification', impact: 'positive', reason: `Verification signals found: ${verificationHits.join(', ')}.` });
+  } else if (taskType === 'coding' || taskType === 'debug' || taskType === 'debug_hard') {
+    score -= 10;
+    factors.push({ name: 'verification', impact: 'negative', reason: 'No verification evidence was provided for a technical task.' });
+  }
+
+  if (/\b(previous|existing|again|recall|memory)\b/.test(normalizedContext)) {
+    score += 5;
+    factors.push({ name: 'prior_knowledge', impact: 'positive', reason: 'Context suggests continuity with prior knowledge.' });
+  }
+
+  return buildResult(score, factors);
+}

package/src/core/validation/index.js

@@ -0,0 +1,2 @@
+export { scoreConfidence } from './confidence.js';
+export { validateOutput } from './validator.js';