@ngockhoale/ukit 1.4.0 → 1.4.1

package/src/index/importResolution.js

@@ -27,6 +27,17 @@ const DEFAULT_ALIAS_RULES = [
 ];
 const ALIAS_CONTEXT_CACHE = new Map();
 const ROOT_ALIAS_CONFIG_FILES = ['tsconfig.json', 'jsconfig.json'];
+const MAX_CACHE_ENTRIES = 100;
+
+function setBoundedCacheEntry(map, key, value, maxEntries = MAX_CACHE_ENTRIES) {
+  if (map.has(key)) {
+    map.delete(key);
+  }
+  map.set(key, value);
+  while (map.size > maxEntries) {
+    map.delete(map.keys().next().value);
+  }
+}
 
 export async function loadImportAliasContext({ rootDir }) {
   const loaded = await loadImportAliasContextState({ rootDir });
@@ -49,7 +60,7 @@ export async function loadImportAliasContextState({ rootDir }) {
       ALIAS_CONTEXT_CACHE.delete(absoluteRoot);
       throw error;
     });
-  ALIAS_CONTEXT_CACHE.set(absoluteRoot, contextPromise);
+  setBoundedCacheEntry(ALIAS_CONTEXT_CACHE, absoluteRoot, contextPromise);
 
   return contextPromise;
 }
@@ -225,9 +236,9 @@ async function loadAliasConfig(configPath, visited = new Set(), tracker = null)
 
   let inherited = null;
   const extendsValue = typeof parsed?.extends === 'string' ? parsed.extends.trim() : '';
-  if (extendsValue && (extendsValue.startsWith('.') || extendsValue.startsWith('/'))) {
-    const inheritedPath = resolveExtendedConfigPath(configDir, extendsValue);
-    inherited = await loadAliasConfig(inheritedPath, visited, tracker);
+  if (extendsValue) {
+    const inheritedPath = await resolveExtendedConfigPath(configDir, extendsValue);
+    inherited = inheritedPath ? await loadAliasConfig(inheritedPath, visited, tracker) : null;
   }
 
   const inheritedRules = inherited?.pathRules ?? [];
@@ -279,11 +290,48 @@ function buildBaseUrlDirs({ rootDir, compilerOptions }) {
   return [path.resolve(rootDir, baseUrl)];
 }
 
-function resolveExtendedConfigPath(configDir, extendsValue) {
+async function resolveExtendedConfigPath(configDir, extendsValue) {
   const withExtension = extendsValue.endsWith('.json')
     ? extendsValue
     : `${extendsValue}.json`;
-  return path.resolve(configDir, withExtension);
+  if (withExtension.startsWith('.') || withExtension.startsWith('/')) {
+    return path.resolve(configDir, withExtension);
+  }
+
+  const parts = withExtension.split('/').filter(Boolean);
+  if (parts.length === 0) {
+    return null;
+  }
+
+  const packageName = withExtension.startsWith('@')
+    ? parts.slice(0, 2).join('/')
+    : parts[0];
+  const packageRest = parts.slice(packageName.startsWith('@') ? 2 : 1).join('/');
+  const packageRoot = await findNodeModulePackageRoot(configDir, packageName);
+  if (!packageRoot) {
+    return null;
+  }
+
+  return path.join(packageRoot, packageRest || 'tsconfig.json');
+}
+
+async function findNodeModulePackageRoot(startDir, packageName) {
+  let currentDir = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(currentDir, 'node_modules', packageName);
+    try {
+      const stat = await fs.stat(candidate);
+      if (stat.isDirectory()) {
+        return candidate;
+      }
+    } catch {}
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+    currentDir = parentDir;
+  }
 }
 
 async function isAliasSnapshotValid(snapshot = []) {
@@ -319,18 +367,16 @@ function isSameSnapshotEntry(current, previous) {
 
 function parseJsonc(raw) {
   const withoutBom = raw.replace(/^\uFEFF/, '');
-  const withoutBlockComments = withoutBom.replace(/\/\*[\s\S]*?\*\//g, '');
-  const withoutLineComments = stripLineComments(withoutBlockComments);
-  const withoutTrailingCommas = withoutLineComments.replace(/,\s*([}\]])/g, '$1');
+  const withoutComments = stripJsoncComments(withoutBom);
+  const withoutTrailingCommas = stripJsoncTrailingCommas(withoutComments);
 
   return JSON.parse(withoutTrailingCommas);
 }
 
-function stripLineComments(raw) {
+function stripJsoncComments(raw) {
   let result = '';
   let inString = false;
-  let stringQuote = '';
-  let isEscaped = false;
+  let escaped = false;
 
   for (let index = 0; index < raw.length; index += 1) {
     const char = raw[index];
@@ -338,31 +384,28 @@ function stripLineComments(raw) {
 
     if (inString) {
       result += char;
-      if (isEscaped) {
-        isEscaped = false;
-      } else if (char === '\\') {
-        isEscaped = true;
-      } else if (char === stringQuote) {
-        inString = false;
-        stringQuote = '';
-      }
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === '"') inString = false;
       continue;
     }
 
-    if (char === '"' || char === '\'') {
+    if (char === '"') {
       inString = true;
-      stringQuote = char;
       result += char;
       continue;
     }
 
     if (char === '/' && nextChar === '/') {
-      while (index < raw.length && raw[index] !== '\n') {
-        index += 1;
-      }
-      if (index < raw.length) {
-        result += '\n';
-      }
+      while (index < raw.length && raw[index] !== '\n') index += 1;
+      if (index < raw.length) result += '\n';
+      continue;
+    }
+
+    if (char === '/' && nextChar === '*') {
+      index += 2;
+      while (index < raw.length && !(raw[index] === '*' && raw[index + 1] === '/')) index += 1;
+      index += 1;
       continue;
     }
 
@@ -372,6 +415,40 @@ function stripLineComments(raw) {
   return result;
 }
 
+function stripJsoncTrailingCommas(raw) {
+  let result = '';
+  let inString = false;
+  let escaped = false;
+
+  for (let index = 0; index < raw.length; index += 1) {
+    const char = raw[index];
+
+    if (inString) {
+      result += char;
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      result += char;
+      continue;
+    }
+
+    if (char === ',') {
+      let nextIndex = index + 1;
+      while (/\s/.test(raw[nextIndex] ?? '')) nextIndex += 1;
+      if (raw[nextIndex] === '}' || raw[nextIndex] === ']') continue;
+    }
+
+    result += char;
+  }
+
+  return result;
+}
+
 function dedupe(values) {
   return [...new Set(values)];
 }

package/src/index/paths.js

@@ -26,3 +26,32 @@ export function getArtifactPath(rootDir, artifactName) {
 export function normalizeRelative(rootDir, absolutePath) {
   return path.relative(rootDir, absolutePath).replace(/\\/g, '/');
 }
+
+export function isLikelyTestFilePath(filePath) {
+  const lower = filePath.toLowerCase();
+  return (
+    lower.startsWith('__tests__/')
+    || lower.startsWith('test/')
+    || lower.startsWith('tests/')
+    || lower.startsWith('spec/')
+    || lower.startsWith('specs/')
+    || lower.includes('/__tests__/')
+    || lower.includes('/test/')
+    || lower.includes('/spec/')
+    || lower.includes('/specs/')
+    || lower.endsWith('.test.js')
+    || lower.endsWith('.test.ts')
+    || lower.endsWith('.test.vue')
+    || lower.endsWith('.test.tsx')
+    || lower.endsWith('.test.jsx')
+    || lower.endsWith('.test.mjs')
+    || lower.endsWith('.test.cjs')
+    || lower.endsWith('.spec.js')
+    || lower.endsWith('.spec.ts')
+    || lower.endsWith('.spec.vue')
+    || lower.endsWith('.spec.tsx')
+    || lower.endsWith('.spec.jsx')
+    || lower.endsWith('.spec.mjs')
+    || lower.endsWith('.spec.cjs')
+  );
+}

package/src/index/queryIndex.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS } from './paths.js';
+import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, isLikelyTestFilePath } from './paths.js';
 import { importsNeedAliasContext, loadImportAliasContext, resolveImportSpecifier } from './importResolution.js';
 import { buildSearchDescriptor } from './languageTools.js';
 
@@ -10,8 +10,19 @@ const QUERY_SEARCH_BUNDLE_CACHE = new Map();
 const QUERY_SUPPORT_BUNDLE_CACHE = new Map();
 const QUERY_RESULT_CACHE = new Map();
 const ANALOG_RESULT_CACHE = new Map();
+const MAX_CACHE_ENTRIES = 100;
 const MAX_IMPORTER_HOPS = 2;
 
+function setBoundedCacheEntry(map, key, value, maxEntries = MAX_CACHE_ENTRIES) {
+  if (map.has(key)) {
+    map.delete(key);
+  }
+  map.set(key, value);
+  while (map.size > maxEntries) {
+    map.delete(map.keys().next().value);
+  }
+}
+
 export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
   if (!query || !query.trim()) {
     return [];
@@ -115,7 +126,7 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
     throw error;
   });
 
-  QUERY_RESULT_CACHE.set(queryCacheKey, queryPromise);
+  setBoundedCacheEntry(QUERY_RESULT_CACHE, queryCacheKey, queryPromise);
   return queryPromise;
 }
 
@@ -123,7 +134,8 @@ async function readArtifact(rootDir, artifactName) {
   const artifactPath = getArtifactPath(path.resolve(rootDir), artifactName);
 
   if (!ARTIFACT_CACHE.has(artifactPath)) {
-    ARTIFACT_CACHE.set(
+    setBoundedCacheEntry(
+      ARTIFACT_CACHE,
       artifactPath,
       fs.readFile(artifactPath, 'utf8')
         .then((content) => {
@@ -148,7 +160,8 @@ async function loadQuerySearchBundle(rootDir) {
   const absoluteRoot = path.resolve(rootDir);
 
   if (!QUERY_SEARCH_BUNDLE_CACHE.has(absoluteRoot)) {
-    QUERY_SEARCH_BUNDLE_CACHE.set(
+    setBoundedCacheEntry(
+      QUERY_SEARCH_BUNDLE_CACHE,
       absoluteRoot,
       Promise.all([
         readArtifact(absoluteRoot, INDEX_ARTIFACTS.files),
@@ -177,7 +190,8 @@ async function loadQuerySupportBundle(rootDir) {
   const absoluteRoot = path.resolve(rootDir);
 
   if (!QUERY_SUPPORT_BUNDLE_CACHE.has(absoluteRoot)) {
-    QUERY_SUPPORT_BUNDLE_CACHE.set(
+    setBoundedCacheEntry(
+      QUERY_SUPPORT_BUNDLE_CACHE,
       absoluteRoot,
       loadQuerySearchBundle(absoluteRoot)
         .then(({ files }) => Promise.all([
@@ -517,35 +531,6 @@ function buildResolvedImportGraphs(rootDir, imports, indexedFileSet, importAlias
   };
 }
 
-function isLikelyTestFilePath(filePath) {
-  const lower = filePath.toLowerCase();
-  return (
-    lower.startsWith('__tests__/')
-    || lower.startsWith('test/')
-    || lower.startsWith('tests/')
-    || lower.startsWith('spec/')
-    || lower.startsWith('specs/')
-    || lower.includes('/__tests__/')
-    || lower.includes('/test/')
-    || lower.includes('/spec/')
-    || lower.includes('/specs/')
-    || lower.endsWith('.test.js')
-    || lower.endsWith('.test.ts')
-    || lower.endsWith('.test.tsx')
-    || lower.endsWith('.test.jsx')
-    || lower.endsWith('.test.vue')
-    || lower.endsWith('.test.mjs')
-    || lower.endsWith('.test.cjs')
-    || lower.endsWith('.spec.js')
-    || lower.endsWith('.spec.ts')
-    || lower.endsWith('.spec.tsx')
-    || lower.endsWith('.spec.jsx')
-    || lower.endsWith('.spec.vue')
-    || lower.endsWith('.spec.mjs')
-    || lower.endsWith('.spec.cjs')
-  );
-}
-
 // ── Index V2: Analog Query ──
 
 export async function queryAnalog({ rootDir = process.cwd(), filePath, limit = 5 } = {}) {
@@ -577,7 +562,7 @@ export async function queryAnalog({ rootDir = process.cwd(), filePath, limit = 5
       throw error;
     });
 
-  ANALOG_RESULT_CACHE.set(analogCacheKey, analogPromise);
+  setBoundedCacheEntry(ANALOG_RESULT_CACHE, analogCacheKey, analogPromise);
   return analogPromise;
 }
 

package/src/index/relatedTests.js

@@ -12,6 +12,17 @@ const RELATED_TEST_RELATION_TYPES = [
 ];
 const RELATED_TEST_ARTIFACT_CACHE = new Map();
 const RELATED_TEST_LOOKUP_CACHE = new Map();
+const MAX_CACHE_ENTRIES = 100;
+
+function setBoundedCacheEntry(map, key, value, maxEntries = MAX_CACHE_ENTRIES) {
+  if (map.has(key)) {
+    map.delete(key);
+  }
+  map.set(key, value);
+  while (map.size > maxEntries) {
+    map.delete(map.keys().next().value);
+  }
+}
 
 export async function inferRelatedTests({
   rootDir = process.cwd(),
@@ -48,7 +59,8 @@ export async function loadRelatedTestArtifacts({
 
   if (!analogsArtifact && !relationsArtifact) {
     if (!RELATED_TEST_LOOKUP_CACHE.has(absoluteRoot)) {
-      RELATED_TEST_LOOKUP_CACHE.set(
+      setBoundedCacheEntry(
+        RELATED_TEST_LOOKUP_CACHE,
         absoluteRoot,
         Promise.all([
           readArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs),
@@ -193,7 +205,8 @@ async function readArtifact(rootDir, artifactName) {
   const artifactPath = getArtifactPath(path.resolve(rootDir), artifactName);
 
   if (!RELATED_TEST_ARTIFACT_CACHE.has(artifactPath)) {
-    RELATED_TEST_ARTIFACT_CACHE.set(
+    setBoundedCacheEntry(
+      RELATED_TEST_ARTIFACT_CACHE,
       artifactPath,
       fs.readFile(artifactPath, 'utf8')
         .then((content) => JSON.parse(content))

package/src/index/routeCatalog.js

@@ -66,7 +66,7 @@ export const ROUTE_CATALOG = [
   {
     id: 'postgres',
     path: '.claude/skills/postgres/SKILL.md',
-    order: 4,
+    order: 4.5,
     signals: [
       { type: 'prompt', regex: /\b(sql|postgres|postgresql|migration|schema|table|view|index|trigger|function|stored procedure|materialized view|query plan|explain)\b/i, score: 5 },
       { type: 'command', regex: /\b(psql|prisma|drizzle|knex|sequelize|typeorm)\b/i, score: 4 },

package/src/index/taskRouting.js

@@ -53,17 +53,28 @@ export async function deriveTaskRoute({
     targetFile: normalizedTarget,
   });
   const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
-  const contextResult = useIndexedContext && (contextIntent || normalizedTarget)
-    ? await resolveContext({
-        rootDir: absoluteRoot,
-        intent: contextIntent,
-        targetFile: normalizedTarget,
-        taskType: inferredTaskType,
-      })
-    : null;
+  const degradedWarnings = [];
+  let contextResult = null;
+  if (useIndexedContext && (contextIntent || normalizedTarget)) {
+    const indexReadError = await findUnreadableIndexArtifact(absoluteRoot);
+    if (indexReadError) {
+      degradedWarnings.push(`resolve-context failed: ${indexReadError.message}`);
+    } else {
+      try {
+        contextResult = await resolveContext({
+          rootDir: absoluteRoot,
+          intent: contextIntent,
+          targetFile: normalizedTarget,
+          taskType: inferredTaskType,
+        });
+      } catch (error) {
+        degradedWarnings.push(`resolve-context failed: ${error?.message ?? String(error)}`);
+      }
+    }
+  }
   const enrichedContextResult = expandRouteContext(contextResult);
 
-  const contextRecommendation = useIndexedContext
+  const contextRecommendation = useIndexedContext && degradedWarnings.length === 0
     ? buildContextRecommendation({
         commandNamespace,
         contextIntent,
@@ -72,8 +83,10 @@ export async function deriveTaskRoute({
         contextResult: enrichedContextResult,
       })
     : null;
-  const verificationPlan = useIndexedContext
-    ? await deriveVerificationPlan({
+  let verificationPlan = null;
+  if (useIndexedContext && contextResult) {
+    try {
+      verificationPlan = await deriveVerificationPlan({
         rootDir: absoluteRoot,
         intent: contextIntent,
         targetFile: normalizedTarget,
@@ -81,8 +94,11 @@ export async function deriveTaskRoute({
         contextResult: enrichedContextResult,
         skillIds: selectedIds,
         autonomyLevel,
-      })
-    : null;
+      });
+    } catch (error) {
+      degradedWarnings.push(`verify-context failed: ${error?.message ?? String(error)}`);
+    }
+  }
 
   const verificationRecommendation = verificationPlan
     ? {
@@ -134,6 +150,7 @@ export async function deriveTaskRoute({
     verificationRecommendation,
     nextAction,
     routeSummary,
+    ...(degradedWarnings.length > 0 ? { degradedWarnings } : {}),
   };
 }
 
@@ -857,12 +874,36 @@ function normalizeRelativeFile(rootDir, rawFilePath) {
     if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
       return relative.replaceAll('\\', '/');
     }
-    return trimmed.replaceAll('\\', '/');
+    return null;
   }
 
   return trimmed.replace(/^\.\/+/, '').replaceAll('\\', '/');
 }
 
+async function findUnreadableIndexArtifact(rootDir) {
+  const indexDir = path.join(rootDir, '.cache', 'index');
+  let entries;
+  try {
+    entries = await fs.readdir(indexDir);
+  } catch {
+    return null;
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) {
+      continue;
+    }
+
+    try {
+      JSON.parse(await fs.readFile(path.join(indexDir, entry), 'utf8'));
+    } catch (error) {
+      return new Error(`${entry}: ${error?.message ?? String(error)}`);
+    }
+  }
+
+  return null;
+}
+
 async function pathExists(filePath) {
   try {
     await fs.access(filePath);
@@ -879,6 +920,7 @@ function unique(values) {
 const DELEGATABLE_IMPLEMENTATION_SKILL_IDS = new Set([
   'delivery',
   'frontend',
+  'frontend-design',
   'frontend-vue',
   'backend-api',
   'postgres',

package/src/index/verificationPlan.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { detectPackageManagerFromFingerprint, getDeclaredPackageManager } from '../core/packageManager.js';
 import { resolveContext } from './resolveContext.js';
 
 const RISKY_SKILL_IDS = new Set(['discover-security', 'repo-maintenance']);
@@ -277,7 +278,7 @@ async function loadProjectVerificationEnvironment({
     .then((resolvedPkg) => ({
       pkg: resolvedPkg,
       scripts: extractScripts(resolvedPkg),
-      packageManager: detectPackageManager({ fingerprintEntries, pkg: resolvedPkg }),
+      packageManager: detectPackageManagerFromFingerprint({ fingerprintEntries, pkg: resolvedPkg }),
     }))
     .catch((error) => {
       PROJECT_VERIFICATION_ENV_CACHE.delete(cacheKey);
@@ -297,41 +298,6 @@ function extractScripts(pkg = null) {
   return pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
 }
 
-function detectPackageManager({ fingerprintEntries = [], pkg = null } = {}) {
-  const declaredPackageManager = getDeclaredPackageManager(pkg);
-  if (declaredPackageManager) return declaredPackageManager;
-
-  const existingFiles = new Set(
-    fingerprintEntries
-      .filter((entry) => entry && entry.mtimeMs !== null)
-      .map((entry) => entry.filePath),
-  );
-  const checks = [
-    ['pnpm-lock.yaml', 'pnpm'],
-    ['yarn.lock', 'yarn'],
-    ['bun.lockb', 'bun'],
-    ['bun.lock', 'bun'],
-    ['package-lock.json', 'npm'],
-  ];
-
-  for (const [lockFile, pm] of checks) {
-    if (existingFiles.has(lockFile)) {
-      return pm;
-    }
-  }
-
-  return 'npm';
-}
-
-function getDeclaredPackageManager(pkg = null) {
-  const declared = String(pkg?.packageManager ?? '').toLowerCase();
-  if (declared.startsWith('pnpm')) return 'pnpm';
-  if (declared.startsWith('yarn')) return 'yarn';
-  if (declared.startsWith('bun')) return 'bun';
-  if (declared.startsWith('npm')) return 'npm';
-  return null;
-}
-
 function buildScriptCommand(packageManager, scriptName, args = []) {
   const filteredArgs = args.filter(Boolean);
 

package/templates/.claude/ukit/index/route-catalog.mjs

@@ -66,7 +66,7 @@ export const ROUTE_CATALOG = [
   {
     id: 'postgres',
     path: '.claude/skills/postgres/SKILL.md',
-    order: 4,
+    order: 4.5,
     signals: [
       { type: 'prompt', regex: /\b(sql|postgres|postgresql|migration|schema|table|view|index|trigger|function|stored procedure|materialized view|query plan|explain)\b/i, score: 5 },
       { type: 'command', regex: /\b(psql|prisma|drizzle|knex|sequelize|typeorm)\b/i, score: 4 },

package/templates/.codex/README.md

@@ -12,7 +12,7 @@ Auto-generated by UKit for OpenAI Codex.
 - Do not make end users memorize skill names, helper scripts, or routing internals unless they are debugging UKit itself.
 - **Treat helper commands as internal orchestration. Do not ask end users to run them.**
 
-## UKit v1.4.0 Shared Runtime
+## UKit v1.4.1 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, validation, and Safe Patch guardrail toggles.

package/templates/CLAUDE.md

@@ -42,7 +42,7 @@
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
 
-## UKit v1.4.0 Shared Runtime
+## UKit v1.4.1 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.4.0 features.
+This folder stores shared UKit runtime state for v1.4.1 features.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4.0",
+  "version": "1.4.1",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",