@ngockhoale/ukit 1.1.6

package/templates/.claude/ukit/index/query-index.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import crypto from 'node:crypto';
+import * as indexCore from './lib/index-core.mjs';
+import {
+  DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+  readRecentCacheEntry,
+  writeRecentCacheEntry,
+} from './cache-utils.mjs';
+
+const {
+  queryCodeIndex,
+  buildCodeIndex,
+  DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  getIndexArtifactGeneratedAt,
+} = indexCore;
+
+const args = process.argv.slice(2);
+const rootDir = getRootDir(args);
+const limitArg = readFlagValue(args, '--limit');
+const limit = Number.parseInt(limitArg ?? '5', 10);
+const query = collectPositionalArgs(args, ['--root', '--limit']);
+
+if (!query) {
+  console.error('Usage: node .claude/ukit/index/query-index.mjs "<error|symbol|path>"');
+  process.exitCode = 1;
+} else {
+  const indexGeneratedAtMs = await ensureFreshIndex({ rootDir, logPrefix: 'index:query' });
+  const effectiveLimit = Number.isNaN(limit) ? 5 : limit;
+  const cachePath = path.join(rootDir, '.claude', 'ukit', 'query-index-cache.json');
+  const requestKey = buildQueryRequestKey({
+    indexGeneratedAtMs,
+    query,
+    limit: effectiveLimit,
+  });
+  const cached = await readRecentCacheEntry(cachePath, requestKey, {
+    maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+    touch: true,
+  });
+  const results = cached?.result
+    ?? await queryCodeIndex({
+      rootDir,
+      query,
+      limit: effectiveLimit,
+    });
+
+  if (!cached) {
+    await writeRecentCacheEntry(cachePath, {
+      requestKey,
+      updatedAt: Date.now(),
+      result: results,
+    }, {
+      maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+    });
+  }
+
+  if (results.length === 0) {
+    console.log('[ukit:index:query] no matches');
+  } else {
+    console.log(`[ukit:index:query] top ${results.length} matches for: ${query}`);
+    for (const [idx, item] of results.entries()) {
+      console.log(`${idx + 1}. ${item.filePath} (score=${item.score})`);
+      if ((item.tests ?? []).length > 0) {
+        console.log(`   tests: ${item.tests.slice(0, 2).join(', ')}`);
+      }
+      if ((item.reasons ?? []).length > 0) {
+        console.log(`   reasons: ${item.reasons.join(', ')}`);
+      }
+    }
+  }
+}
+
+async function ensureFreshIndex({ rootDir, logPrefix }) {
+  const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
+  const stale = lastRefreshMs === null
+    ? true
+    : typeof indexCore.isIndexStale === 'function'
+      ? await indexCore.isIndexStale({
+          rootDir,
+          maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+          now: Date.now(),
+          generatedAtMs: lastRefreshMs,
+        })
+      : (Date.now() - lastRefreshMs) > DEFAULT_INDEX_CACHE_MAX_AGE_MS;
+
+  if (!stale) {
+    return lastRefreshMs;
+  }
+
+  const summary = await buildCodeIndex({ rootDir });
+  if (lastRefreshMs !== null) {
+    console.log(`[ukit:${logPrefix}] stale index refreshed (last=${new Date(lastRefreshMs).toISOString()})`);
+  } else {
+    console.log(`[ukit:${logPrefix}] stale index refreshed (no previous cache timestamp)`);
+  }
+  return Number.isFinite(summary?.generatedAtMs)
+    ? summary.generatedAtMs
+    : getIndexArtifactGeneratedAt({ rootDir });
+}
+
+function buildQueryRequestKey({
+  indexGeneratedAtMs = null,
+  query = '',
+  limit = 5,
+} = {}) {
+  return buildCompactMachineKey('query-v1', {
+    indexGeneratedAtMs,
+    query: String(query || '').trim(),
+    limit: Number(limit),
+  });
+}
+
+function buildCompactMachineKey(prefix, payload) {
+  return `${prefix}:${stableMachineDigest(payload)}`;
+}
+
+function stableMachineDigest(payload) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(payload))
+    .digest('base64url');
+}
+
+function getRootDir(argv) {
+  const value = readFlagValue(argv, '--root');
+  return value ? path.resolve(value) : process.cwd();
+}
+
+function readFlagValue(argv, flag) {
+  const exact = argv.indexOf(flag);
+  if (exact >= 0 && argv[exact + 1]) return argv[exact + 1];
+  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
+  return withEquals ? withEquals.slice(flag.length + 1) : null;
+}
+
+function collectPositionalArgs(argv, flagsWithValues = []) {
+  return argv
+    .filter((arg, index) => !isFlagOrValue(argv, index, flagsWithValues))
+    .join(' ')
+    .trim();
+}
+
+function isFlagOrValue(argv, index, flagsWithValues = []) {
+  const arg = argv[index];
+  if (!arg.startsWith('--')) {
+    const prev = argv[index - 1];
+    return Boolean(prev && flagsWithValues.includes(prev));
+  }
+  return true;
+}

package/templates/.claude/ukit/index/refresh-index.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {
+  buildCodeIndex,
+  isIndexStale,
+  DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  getIndexArtifactGeneratedAt,
+} from './lib/index-core.mjs';
+
+const args = process.argv.slice(2);
+const rootDir = getRootDir(args);
+const changedArg = readFlagValue(args, '--changed');
+const changedFiles = changedArg ? changedArg.split(',').map((x) => x.trim()).filter(Boolean) : [];
+const force = args.includes('--force');
+
+const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
+const stale = force
+  ? true
+  : await isIndexStale({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS, generatedAtMs: lastRefreshMs });
+
+if (!stale) {
+  console.log('[ukit:index:refresh] skipped (cache fresh)');
+  if (lastRefreshMs !== null) {
+    console.log(`lastRefresh: ${new Date(lastRefreshMs).toISOString()}`);
+  }
+  if (changedFiles.length > 0) {
+    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+  }
+  console.log(`root: ${rootDir}`);
+} else {
+  const summary = await buildCodeIndex({ rootDir });
+
+  console.log('[ukit:index:refresh] completed');
+  if (lastRefreshMs !== null) {
+    console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+  }
+  if (changedFiles.length > 0) {
+    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+  }
+  console.log(`root: ${rootDir}`);
+  console.log(`files: ${summary.fileCount}`);
+  console.log(`parsed: ${summary.parsedCodeFileCount}`);
+  console.log(`reused: ${summary.reusedCodeFileCount}`);
+  console.log(`indexDir: ${summary.indexDir}`);
+}
+
+function getRootDir(argv) {
+  const value = readFlagValue(argv, '--root');
+  return value ? path.resolve(value) : process.cwd();
+}
+
+function readFlagValue(argv, flag) {
+  const exact = argv.indexOf(flag);
+  if (exact >= 0 && argv[exact + 1]) return argv[exact + 1];
+  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
+  return withEquals ? withEquals.slice(flag.length + 1) : null;
+}

package/templates/.claude/ukit/index/reset-auto-permissions.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  return {
+    dryRun: argv.includes('--dry-run'),
+    quiet: argv.includes('--quiet'),
+  };
+}
+
+async function readJson(filePath, fallback) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await fs.writeFile(filePath, JSON.stringify(value, null, 2) + '\n', 'utf8');
+}
+
+async function main() {
+  const { dryRun, quiet } = parseArgs(process.argv.slice(2));
+  const rootDir = process.cwd();
+  const settingsLocalPath = path.join(rootDir, '.claude', 'settings.local.json');
+  const usagePath = path.join(rootDir, '.claude', 'ukit', 'permission-usage.json');
+  const auditPath = path.join(rootDir, '.claude', 'ukit', 'permission-audit.log');
+
+  const settings = await readJson(settingsLocalPath, {});
+  const usage = await readJson(usagePath, {});
+
+  const managedRules = Object.keys(usage?.managedRules || {});
+  const allow = Array.isArray(settings?.permissions?.allow) ? settings.permissions.allow : [];
+
+  const removedRules = allow.filter((rule) => managedRules.includes(rule));
+  if (managedRules.length === 0) {
+    if (!quiet) {
+      console.log('[UKit] No managed auto-permission rules to reset.');
+    }
+    return;
+  }
+
+  if (!dryRun) {
+    settings.permissions = settings.permissions && typeof settings.permissions === 'object' ? settings.permissions : {};
+    settings.permissions.allow = allow.filter((rule) => !managedRules.includes(rule));
+    await fs.mkdir(path.dirname(settingsLocalPath), { recursive: true });
+    await writeJson(settingsLocalPath, settings);
+
+    usage.managedRules = {};
+    usage.lastResetAt = new Date().toISOString();
+    await fs.mkdir(path.dirname(usagePath), { recursive: true });
+    await writeJson(usagePath, usage);
+
+    const lines = removedRules
+      .map((rule) => JSON.stringify({ ts: new Date().toISOString(), event: 'manual_reset', rule }))
+      .join('\n');
+    await fs.mkdir(path.dirname(auditPath), { recursive: true });
+    await fs.appendFile(auditPath, lines + '\n', 'utf8');
+  }
+
+  if (!quiet) {
+    const mode = dryRun ? 'Would remove' : 'Removed';
+    console.log(`[UKit] ${mode} ${managedRules.length} managed auto-permission rule(s).`);
+    for (const rule of removedRules) {
+      console.log(`- ${rule}`);
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error('[UKit] Failed to reset auto permissions:', error?.message || String(error));
+  process.exitCode = 1;
+});

package/templates/.claude/ukit/index/resolve-context.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import crypto from 'node:crypto';
+import * as indexCore from './lib/index-core.mjs';
+import {
+  DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+  readRecentCacheEntry,
+  writeRecentCacheEntry,
+} from './cache-utils.mjs';
+
+const {
+  resolveContext,
+  buildCodeIndex,
+  DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  getIndexArtifactGeneratedAt,
+} = indexCore;
+const CONTEXT_DISPLAY_LIMIT = 2;
+const CONTEXT_REASON_LIMIT = 2;
+
+const args = process.argv.slice(2);
+const rootDir = getRootDir(args);
+const targetFile = readFlagValue(args, '--target');
+const taskType = readFlagValue(args, '--type');
+const intent = collectPositionalArgs(args, ['--root', '--target', '--type']);
+const effectiveIntent = deriveHelperIntent({ intent, targetFile });
+
+if (!intent && !targetFile) {
+  console.error('Usage: node .claude/ukit/index/resolve-context.mjs "<intent>" [--target <file>] [--type trivial|simple|non-trivial]');
+  process.exitCode = 1;
+} else {
+  const indexGeneratedAtMs = await ensureFreshIndex({
+    rootDir,
+    logPrefix: 'context',
+  });
+  const cachePath = path.join(rootDir, '.claude', 'ukit', 'resolve-context-cache.json');
+  const requestKey = buildRequestKey({
+    indexGeneratedAtMs,
+    intent: effectiveIntent,
+    targetFile,
+    taskType,
+  });
+  const cached = await readRecentCacheEntry(cachePath, requestKey, {
+    maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+    touch: true,
+  });
+  const computedResult = cached?.result
+    ?? await resolveContext({ rootDir, intent: effectiveIntent, targetFile, taskType });
+  const result = expandHelperContext(computedResult);
+
+  if (!cached) {
+    await writeRecentCacheEntry(cachePath, {
+      requestKey,
+      updatedAt: Date.now(),
+      result,
+    }, {
+      maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+    });
+  }
+
+  printContextResult(result);
+}
+
+async function ensureFreshIndex({ rootDir, logPrefix }) {
+  const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
+  const stale = lastRefreshMs === null
+    ? true
+    : typeof indexCore.isIndexStale === 'function'
+      ? await indexCore.isIndexStale({
+          rootDir,
+          maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+          now: Date.now(),
+          generatedAtMs: lastRefreshMs,
+        })
+      : (Date.now() - lastRefreshMs) > DEFAULT_INDEX_CACHE_MAX_AGE_MS;
+
+  if (!stale) {
+    return lastRefreshMs;
+  }
+
+  const summary = await buildCodeIndex({ rootDir });
+  if (lastRefreshMs !== null) {
+    console.log(`[ukit:${logPrefix}] stale index refreshed (last=${new Date(lastRefreshMs).toISOString()})`);
+  } else {
+    console.log(`[ukit:${logPrefix}] stale index refreshed (no previous cache timestamp)`);
+  }
+  return Number.isFinite(summary?.generatedAtMs)
+    ? summary.generatedAtMs
+    : getIndexArtifactGeneratedAt({ rootDir });
+}
+
+function getRootDir(argv) {
+  const value = readFlagValue(argv, '--root');
+  return value ? path.resolve(value) : process.cwd();
+}
+
+function readFlagValue(argv, flag) {
+  const exact = argv.indexOf(flag);
+  if (exact >= 0 && argv[exact + 1]) return argv[exact + 1];
+  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
+  return withEquals ? withEquals.slice(flag.length + 1) : null;
+}
+
+function collectPositionalArgs(argv, flagsWithValues = []) {
+  return argv
+    .filter((arg, index) => !isFlagOrValue(argv, index, flagsWithValues))
+    .join(' ')
+    .trim();
+}
+
+function isFlagOrValue(argv, index, flagsWithValues = []) {
+  const arg = argv[index];
+  if (!arg.startsWith('--')) {
+    const prev = argv[index - 1];
+    return Boolean(prev && flagsWithValues.includes(prev));
+  }
+  return true;
+}
+
+function buildRequestKey({
+  indexGeneratedAtMs = null,
+  intent = '',
+  targetFile = null,
+  taskType = null,
+} = {}) {
+  return buildCompactMachineKey('resolve-v1', {
+    indexGeneratedAtMs,
+    intent: String(intent || '').trim(),
+    targetFile: String(targetFile || '').trim(),
+    taskType: String(taskType || '').trim(),
+  });
+}
+
+function buildCompactMachineKey(prefix, payload) {
+  return `${prefix}:${stableMachineDigest(payload)}`;
+}
+
+function stableMachineDigest(payload) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(payload))
+    .digest('base64url');
+}
+
+function deriveHelperIntent({ intent = '', targetFile = null } = {}) {
+  const normalizedIntent = String(intent || '').trim();
+  if (normalizedIntent) {
+    return normalizedIntent;
+  }
+
+  const normalizedTarget = String(targetFile || '').trim();
+  if (!normalizedTarget) {
+    return '';
+  }
+
+  if (/^docs\//i.test(normalizedTarget)) {
+    return `update docs for ${normalizedTarget}`;
+  }
+
+  return `work on ${normalizedTarget}`;
+}
+
+function expandHelperContext(contextResult) {
+  if (!contextResult) {
+    return contextResult;
+  }
+
+  const directTests = (contextResult.primaryTargets ?? []).filter(isTestLikeFile);
+  if (directTests.length === 0) {
+    return contextResult;
+  }
+
+  const relatedTests = unique([
+    ...(contextResult.relatedTests ?? []),
+    ...directTests,
+  ]);
+  const relatedTestExplanations = mergeRelatedTestExplanations(
+    contextResult.explanations?.relatedTests ?? [],
+    directTests,
+  );
+
+  return {
+    ...contextResult,
+    relatedTests,
+    explanations: {
+      ...(contextResult.explanations ?? {}),
+      relatedTests: relatedTestExplanations,
+    },
+  };
+}
+
+function mergeRelatedTestExplanations(existingExplanations = [], directTests = []) {
+  const next = [...existingExplanations];
+
+  for (const filePath of directTests) {
+    const existing = next.find((entry) => entry.filePath === filePath);
+    const reason = `direct test target ${filePath}`;
+    if (!existing) {
+      next.push({ filePath, reason });
+      continue;
+    }
+    if (!String(existing.reason || '').includes(reason)) {
+      existing.reason = existing.reason
+        ? `${existing.reason}; ${reason}`
+        : reason;
+    }
+  }
+
+  return next;
+}
+
+function isTestLikeFile(filePath) {
+  return /\.(test|spec)\.[a-z0-9]+$/i.test(filePath)
+    || /(^|\/)(?:__tests__|tests?|specs?)\//i.test(filePath);
+}
+
+function unique(values = []) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function printContextResult(result) {
+  console.log('[ukit:context]');
+  console.log(`taskType: ${result.taskType}`);
+  console.log(`budget: ${result.contextBudget.minFiles}-${result.contextBudget.maxFiles} files`);
+  printContextGroup('primaryTargets', result.primaryTargets, result.explanations?.primaryTargets);
+  printContextGroup('sharedAbstractions', result.sharedAbstractions, result.explanations?.sharedAbstractions);
+  printContextGroup('analogFiles', result.analogFiles, result.explanations?.analogFiles);
+  printContextGroup('relatedTests', result.relatedTests, result.explanations?.relatedTests);
+  printContextGroup('styleFiles', result.styleFiles, result.explanations?.styleFiles);
+}
+
+function printContextGroup(label, filePaths = [], explanations = []) {
+  console.log(`${label}: ${formatCompactDisplayList(filePaths)}`);
+
+  const normalizedExplanations = uniqueContextExplanations(explanations);
+  for (const item of normalizedExplanations.slice(0, CONTEXT_REASON_LIMIT)) {
+    console.log(`  - ${item.filePath}: ${item.reason}`);
+  }
+
+  const remainingReasonCount = normalizedExplanations.length - Math.min(normalizedExplanations.length, CONTEXT_REASON_LIMIT);
+  if (remainingReasonCount > 0) {
+    console.log(`  - +${remainingReasonCount} more reasons`);
+  }
+}
+
+function formatCompactDisplayList(values = [], limit = CONTEXT_DISPLAY_LIMIT) {
+  const normalized = [...new Set((values ?? []).filter(Boolean))];
+  if (normalized.length === 0) {
+    return 'none';
+  }
+
+  const shown = normalized.slice(0, limit);
+  const remaining = normalized.length - shown.length;
+  return remaining > 0
+    ? `${shown.join(', ')}, +${remaining} more`
+    : shown.join(', ');
+}
+
+function uniqueContextExplanations(explanations = []) {
+  const seen = new Set();
+  const unique = [];
+
+  for (const item of explanations ?? []) {
+    const filePath = String(item?.filePath ?? '').trim();
+    const reason = String(item?.reason ?? '').trim();
+    if (!filePath && !reason) {
+      continue;
+    }
+
+    const key = `${filePath}::${reason}`;
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    unique.push({ filePath, reason });
+  }
+
+  return unique;
+}