@ngockhoale/ukit 1.1.6

package/src/core/paths.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+
+export function buildPathConfig({ packageRoot, projectRoot }) {
+  return {
+    packageRoot,
+    projectRoot,
+    manifestPath: path.join(packageRoot, 'manifests', 'platform.full.yaml'),
+    templatesRoot: path.join(packageRoot, 'templates'),
+    ukitRoot: path.join(projectRoot, '.claude', 'ukit', '.ukit'),
+    installMetaPath: path.join(projectRoot, '.claude', 'ukit', '.ukit', 'install.json'),
+    backupRoot: path.join(projectRoot, '.claude', 'ukit', '.ukit', 'backups'),
+  };
+}

package/src/core/report.js

@@ -0,0 +1,17 @@
+export function summarizeDiff(diffResults) {
+  const summary = { create: 0, update: 0, unchanged: 0, skip: 0 };
+  for (const entry of diffResults) {
+    if (entry.action in summary) {
+      summary[entry.action] += 1;
+    }
+  }
+  return summary;
+}
+
+export function toDiffRows(diffResults) {
+  return diffResults.map((entry) => ({
+    id: entry.id,
+    action: entry.action,
+    targetPath: entry.targetPath,
+  }));
+}

package/src/core/router/advisor.js

@@ -0,0 +1,42 @@
+export function shouldEscalate(trigger) {
+  if (!trigger || typeof trigger !== 'object') {
+    return false;
+  }
+
+  if (trigger.type === 'user_requested') {
+    return true;
+  }
+
+  if (trigger.type === 'complexity_detected') {
+    return true;
+  }
+
+  if (trigger.type === 'retry_exceeded') {
+    return (trigger.attempts ?? 0) >= 2;
+  }
+
+  if (trigger.type === 'validation_failed') {
+    return (trigger.attempts ?? 0) >= 1;
+  }
+
+  return false;
+}
+
+export async function askAdvisor(request) {
+  const strategy = request?.question
+    ? `Break the task into verifiable steps, focusing on: ${request.question}`
+    : 'Break the task into smaller verifiable steps.';
+
+  return {
+    strategy,
+    steps: [
+      'Restate the goal in one short sentence.',
+      'List the smallest changes that can be verified locally.',
+      'Run focused checks before expanding the scope.',
+    ],
+    warnings: [
+      'Fallback advisor response used because no external advisor integration is wired in this local runtime.',
+    ],
+    confidence: 55,
+  };
+}

package/src/core/router/index.js

@@ -0,0 +1,2 @@
+export { askAdvisor, shouldEscalate } from './advisor.js';
+export { classifyTask, detectComplexity, selectModel } from './router.js';

package/src/core/router/router.js

@@ -0,0 +1,164 @@
+const HIGH_COMPLEXITY_KEYWORDS = [
+  'architecture',
+  'architect',
+  'design',
+  'trade-off',
+  'tradeoff',
+  'security',
+  'compare',
+  'why',
+  'reasoning',
+  'scalable',
+  'system design',
+];
+
+const LOW_COMPLEXITY_KEYWORDS = [
+  'rename',
+  'add field',
+  'change text',
+  'format',
+  'typo',
+  'update label',
+  'refactor name',
+];
+
+const REVIEW_KEYWORDS = ['review', 'code review', 'audit'];
+const DEBUG_KEYWORDS = ['debug', 'bug', 'stack trace', 'error', 'crash', 'retry', 'failed attempt', 'failure'];
+const CODING_HINTS = ['src/', 'package.json', 'function', 'class', 'implement', 'file', '.js', '.ts', '.tsx', '.jsx', '```'];
+
+function normalize(text) {
+  return String(text ?? '').toLowerCase();
+}
+
+function countFileHints(text) {
+  const explicitCount = Number.parseInt(normalize(text).match(/\b(\d+)\s+files?\b/)?.[1] ?? '0', 10);
+  const pathMatches = normalize(text).match(/\b[\w./-]+\.(?:js|ts|tsx|jsx|json|md|yaml|yml)\b/g) ?? [];
+  return Math.max(explicitCount, new Set(pathMatches).size);
+}
+
+export function detectComplexity(message, context = '') {
+  const combined = normalize(`${message}\n${context}`);
+  const wordCount = combined.split(/\s+/).filter(Boolean).length;
+  const fileHints = countFileHints(combined);
+  const hasRetryPattern = /\b(retry|failed|failure|attempt)\b/.test(combined);
+  const highSignals = HIGH_COMPLEXITY_KEYWORDS.filter((keyword) => combined.includes(keyword)).length;
+  const lowSignals = LOW_COMPLEXITY_KEYWORDS.filter((keyword) => combined.includes(keyword)).length;
+
+  if (highSignals > 0 || fileHints > 5 || (hasRetryPattern && /\b(debug|error|crash|stack trace)\b/.test(combined))) {
+    return 'high';
+  }
+
+  if (lowSignals > 0 || (fileHints <= 1 && wordCount <= 24 && !hasRetryPattern)) {
+    return 'low';
+  }
+
+  return 'medium';
+}
+
+function detectTaskType(message, context = '', complexity = 'medium') {
+  const combined = normalize(`${message}\n${context}`);
+
+  if (DEBUG_KEYWORDS.some((keyword) => combined.includes(keyword)) && complexity === 'high') {
+    return 'debug_hard';
+  }
+
+  if (HIGH_COMPLEXITY_KEYWORDS.some((keyword) => combined.includes(keyword))) {
+    return 'reasoning';
+  }
+
+  if (REVIEW_KEYWORDS.some((keyword) => combined.includes(keyword))) {
+    return 'review';
+  }
+
+  if (CODING_HINTS.some((keyword) => combined.includes(keyword))) {
+    return 'coding';
+  }
+
+  return 'simple_chat';
+}
+
+function recommendTier(type, complexity) {
+  if (type === 'simple_chat' && complexity === 'low') {
+    return 'fast';
+  }
+
+  if (type === 'reasoning') {
+    return 'powerful';
+  }
+
+  if (type === 'debug_hard' && complexity === 'high') {
+    return 'powerful';
+  }
+
+  if (type === 'review') {
+    return complexity === 'high' ? 'powerful' : 'balanced';
+  }
+
+  if (type === 'coding') {
+    return complexity === 'high' ? 'powerful' : 'balanced';
+  }
+
+  return complexity === 'low' ? 'fast' : 'balanced';
+}
+
+function buildReason(type, complexity) {
+  if (type === 'simple_chat') {
+    return 'Short conversational request without strong coding or reasoning signals.';
+  }
+
+  if (type === 'debug_hard') {
+    return 'Debugging request includes repeated failures or stack-trace style signals.';
+  }
+
+  if (type === 'reasoning') {
+    return 'Request asks for architecture, comparison, trade-offs, or deeper analysis.';
+  }
+
+  if (type === 'review') {
+    return complexity === 'high'
+      ? 'Review request touches higher-risk or cross-cutting areas.'
+      : 'Review request is scoped enough for the balanced tier.';
+  }
+
+  if (type === 'coding') {
+    return complexity === 'high'
+      ? 'Implementation spans multiple modules or difficult trade-offs.'
+      : 'Normal implementation work is best handled by the balanced tier.';
+  }
+
+  return 'Fallback routing decision.';
+}
+
+export function classifyTask(userMessage, context = '') {
+  const complexity = detectComplexity(userMessage, context);
+  const type = detectTaskType(userMessage, context, complexity);
+  const recommendedTier = recommendTier(type, complexity);
+
+  return {
+    type,
+    complexity,
+    recommendedTier,
+    reason: buildReason(type, complexity),
+  };
+}
+
+export function selectModel(classification, config) {
+  const tier = classification?.recommendedTier ?? 'balanced';
+  if (config?.[tier]) {
+    return config[tier];
+  }
+
+  if (tier === 'powerful' && config?.advisorModel) {
+    return config.advisorModel;
+  }
+
+  if (tier === 'balanced' && config?.defaultModel) {
+    return config.defaultModel;
+  }
+
+  if (tier === 'fast' && config?.fast) {
+    return config.fast;
+  }
+
+  return config?.defaultModel ?? config?.balanced ?? config?.fast ?? config?.powerful ?? null;
+}

package/src/core/runInstallPipeline.js

@@ -0,0 +1,365 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadManifest } from '../manifest/loadManifest.js';
+import { detectStack } from '../stack/detectStack.js';
+import { detectProjectContext } from '../context/detectProjectContext.js';
+import { detectProviders } from '../context/detectProviders.js';
+import { buildTemplateVariables } from '../render/buildVariables.js';
+import { buildInstallPlan } from './buildPlan.js';
+import { diffInstallPlan } from './diffPlan.js';
+import { applyDiffResults } from './applyPlan.js';
+import { summarizeDiff, toDiffRows } from './report.js';
+import { writeInstallMetadata } from './metadata.js';
+import { cleanupLegacyPaths, migrateLegacyRuntimeRoot } from './migrateLegacy.js';
+import { ensureGitignore } from './ensureGitignore.js';
+import { readJsonIfExists, removeFileOrLinkOnly, resolveProjectRelativePath } from './fileOps.js';
+
+const AUTO_PRUNE_OBSOLETE_PREFIXES = [
+  '.claude/skills/',
+];
+
+function normalizeRelativePath(relativePath) {
+  if (typeof relativePath !== 'string') {
+    return null;
+  }
+
+  const trimmed = relativePath.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return trimmed.replace(/\\/g, '/');
+}
+
+function buildManagedRelativePathSet(plan, projectRoot) {
+  return new Set(
+    (plan?.entries || [])
+      .map((entry) => normalizeRelativePath(path.relative(projectRoot, entry.targetPath)))
+      .filter(Boolean),
+  );
+}
+
+function buildTrackedManagedRelativePathSet(plan, projectRoot) {
+  return new Set(
+    (plan?.entries || [])
+      .filter((entry) => entry?.mergeStrategy !== 'skip')
+      .map((entry) => normalizeRelativePath(path.relative(projectRoot, entry.targetPath)))
+      .filter(Boolean),
+  );
+}
+
+function shouldAutoPruneObsoletePath(relativePath) {
+  return AUTO_PRUNE_OBSOLETE_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
+}
+
+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);
+  }
+}
+
+async function isTrackedManagedDirectoryTree({
+  dirPath,
+  projectRoot,
+  trackedPathSet,
+  trackedPaths,
+}) {
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  if (entries.length === 0) {
+    return false;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    const relativePath = normalizeRelativePath(path.relative(projectRoot, fullPath));
+    if (!relativePath) {
+      return false;
+    }
+
+    if (entry.isDirectory()) {
+      const trackedDescendantPrefix = `${relativePath}/`;
+      const hasTrackedDescendant = trackedPaths.some((trackedPath) => trackedPath.startsWith(trackedDescendantPrefix));
+      if (!hasTrackedDescendant) {
+        return false;
+      }
+
+      const nestedSafe = await isTrackedManagedDirectoryTree({
+        dirPath: fullPath,
+        projectRoot,
+        trackedPathSet,
+        trackedPaths,
+      });
+      if (!nestedSafe) {
+        return false;
+      }
+      continue;
+    }
+
+    if (!trackedPathSet.has(relativePath)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function normalizeTrackedMetadataPath(entry) {
+  return normalizeRelativePath(typeof entry === 'string' ? entry : entry?.p);
+}
+
+async function removeManagedDirectoriesForLinkTargets({
+  installMetaData,
+  projectRoot,
+  plan,
+}) {
+  if (installMetaData?.tool !== 'ukit') {
+    return 0;
+  }
+
+  const trackedPathSet = new Set(
+    (Array.isArray(installMetaData?.files) ? installMetaData.files : [])
+      .map((entry) => normalizeTrackedMetadataPath(entry))
+      .filter(Boolean),
+  );
+  if (trackedPathSet.size === 0) {
+    return 0;
+  }
+  const trackedPaths = [...trackedPathSet];
+
+  let removedCount = 0;
+  for (const entry of plan?.entries ?? []) {
+    if (entry?.type !== 'link') {
+      continue;
+    }
+
+    let stat;
+    try {
+      stat = await fs.lstat(entry.targetPath);
+    } catch {
+      continue;
+    }
+
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      continue;
+    }
+
+    const safeToReplace = await isTrackedManagedDirectoryTree({
+      dirPath: entry.targetPath,
+      projectRoot,
+      trackedPathSet,
+      trackedPaths,
+    });
+    if (!safeToReplace) {
+      continue;
+    }
+
+    await fs.rm(entry.targetPath, { recursive: true, force: true });
+    removedCount += 1;
+  }
+
+  return removedCount;
+}
+
+async function pruneObsoleteManagedPaths({
+  installMetaData,
+  projectRoot,
+  managedRelativePaths,
+  managedLinkRelativePaths = [],
+}) {
+  if (installMetaData?.tool !== 'ukit') {
+    return 0;
+  }
+
+  const previousFiles = Array.isArray(installMetaData?.files) ? installMetaData.files : [];
+  if (previousFiles.length === 0) {
+    return 0;
+  }
+
+  const activePathSet = new Set(
+    [...managedRelativePaths]
+      .map((value) => normalizeRelativePath(value))
+      .filter(Boolean),
+  );
+  const activeLinkPathSet = new Set(
+    managedLinkRelativePaths
+      .map((value) => normalizeRelativePath(value))
+      .filter(Boolean),
+  );
+  const activeLinkPaths = [...activeLinkPathSet];
+
+  let removedCount = 0;
+  for (const entry of previousFiles) {
+    const relativePath = normalizeRelativePath(typeof entry === 'string' ? entry : entry?.p);
+    if (!relativePath || activePathSet.has(relativePath) || !shouldAutoPruneObsoletePath(relativePath)) {
+      continue;
+    }
+    if (activeLinkPaths.some((linkPath) => relativePath.startsWith(`${linkPath}/`))) {
+      continue;
+    }
+
+    const absolutePath = resolveProjectRelativePath(projectRoot, relativePath);
+    if (!absolutePath) {
+      continue;
+    }
+
+    const removed = await removeFileOrLinkOnly(absolutePath);
+    if (removed) {
+      removedCount += 1;
+      await cleanupEmptyParents(absolutePath, projectRoot);
+    }
+  }
+
+  return removedCount;
+}
+
+export async function runInstallPipeline({
+  packageVersion,
+  pathConfig,
+  dryRun,
+  selectedAdapterItemIds,
+  retainedManagedRelativePaths = [],
+}) {
+  // Check for an existing install before making any changes.
+  // cleanupLegacyPaths() is only safe to run on reinstalls: on a fresh install
+  // there are no legacy UKit files to migrate, so running it risks deleting user
+  // files that happen to share a legacy path name (e.g. .claude/skills/delivery.md).
+  const installMetaData = await readJsonIfExists(pathConfig.installMetaPath);
+  const isReinstall = Boolean(installMetaData?.tool === 'ukit');
+
+  if (isReinstall && !dryRun) {
+    await migrateLegacyRuntimeRoot(pathConfig.projectRoot);
+  }
+
+  const manifest = await loadManifest(pathConfig.manifestPath);
+  const stackContext = await detectStack(pathConfig.projectRoot);
+  const projectContext = await detectProjectContext(pathConfig.projectRoot);
+  const providerContext = await detectProviders(pathConfig.projectRoot);
+
+  const variables = buildTemplateVariables({
+    projectContext,
+    stackContext,
+    packageVersion,
+    providerContext,
+  });
+
+  const plan = await buildInstallPlan({
+    manifest,
+    stackContext,
+    templatesRoot: pathConfig.templatesRoot,
+    variables,
+    projectRoot: pathConfig.projectRoot,
+    selectedAdapterItemIds,
+  });
+  const managedRelativePaths = buildManagedRelativePathSet(plan, pathConfig.projectRoot);
+  const trackedManagedRelativePaths = buildTrackedManagedRelativePathSet(plan, pathConfig.projectRoot);
+  const managedLinkRelativePaths = (plan.entries ?? [])
+    .filter((entry) => entry?.type === 'link')
+    .map((entry) => normalizeRelativePath(path.relative(pathConfig.projectRoot, entry.targetPath)))
+    .filter(Boolean);
+
+  if (!dryRun) {
+    await removeManagedDirectoriesForLinkTargets({
+      installMetaData,
+      projectRoot: pathConfig.projectRoot,
+      plan,
+    });
+  }
+
+  const diffResults = await diffInstallPlan(plan);
+  const plannedSummary = summarizeDiff(diffResults);
+
+  if (!dryRun) {
+    const { writes, skippedUpdates } = await applyDiffResults(diffResults, {
+      backupRoot: pathConfig.backupRoot,
+      projectRoot: pathConfig.projectRoot,
+    });
+
+    // Only run migration cleanup on reinstalls. Fresh installs have no legacy
+    // UKit files to migrate, so running cleanup risks deleting user files that
+    // happen to share a legacy path name (e.g. .claude/skills/delivery.md).
+    if (isReinstall) {
+      await cleanupLegacyPaths(pathConfig.projectRoot);
+    }
+
+    await ensureGitignore(pathConfig.projectRoot);
+    await pruneObsoleteManagedPaths({
+      installMetaData,
+      projectRoot: pathConfig.projectRoot,
+      managedRelativePaths,
+      managedLinkRelativePaths,
+    });
+
+    // Adjust summary to reflect link updates that were skipped for safety
+    // (the planned diff counted them as 'update', but apply skipped them).
+    const summary =
+      skippedUpdates > 0
+        ? {
+            ...plannedSummary,
+            update: plannedSummary.update - skippedUpdates,
+            skip: plannedSummary.skip + skippedUpdates,
+          }
+        : plannedSummary;
+
+    await writeInstallMetadata({
+      installMetaPath: pathConfig.installMetaPath,
+      packageVersion,
+      manifest,
+      stackContext,
+      providerContext,
+      summary,
+      writes,
+      projectRoot: pathConfig.projectRoot,
+      managedRelativePaths: [...trackedManagedRelativePaths],
+      retainedManagedRelativePaths,
+    });
+
+    return {
+      manifest,
+      stackContext,
+      projectContext,
+      providerContext,
+      summary,
+      rows: toDiffRows(diffResults),
+      writes,
+    };
+  }
+
+  return {
+    manifest,
+    stackContext,
+    projectContext,
+    providerContext,
+    summary: plannedSummary,
+    rows: toDiffRows(diffResults),
+    writes: [],
+  };
+}