@ngockhoale/ukit 1.1.6

package/src/core/applyPlan.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { writeFileAtomic, copyFileSafe, createDirectoryLink, removeLinkOnly } from './fileOps.js';
+
+export async function applyDiffResults(diffResults, { backupRoot, projectRoot } = {}) {
+  const writes = [];
+  let skippedUpdates = 0;
+
+  for (const entry of diffResults) {
+    if (entry.action !== 'create' && entry.action !== 'update') {
+      continue;
+    }
+
+    if (entry.type === 'link') {
+      // Remove existing symlink before recreating.
+      // Use removeLinkOnly — NOT removeLinkOrDir — to protect real directories that may
+      // contain user content. If the path is not a symlink, skip and warn instead of
+      // recursively deleting it.
+      if (entry.action === 'update') {
+        const removed = await removeLinkOnly(entry.targetPath);
+        if (!removed) {
+          // Determine what actually exists at this path for a precise warning message.
+          let existingKind = 'unknown path';
+          try {
+            const stat = await fs.lstat(entry.targetPath);
+            existingKind = stat.isDirectory() ? 'real directory' : 'regular file';
+          } catch {
+            existingKind = 'unknown path';
+          }
+          console.warn(
+            `[UKit] Warning: skipping link update for ${entry.targetPath} — exists as a ${existingKind} (possible user content). Remove it manually if intended.`,
+          );
+          skippedUpdates += 1;
+          continue;
+        }
+      }
+      await createDirectoryLink(entry.linkTarget, entry.targetPath);
+      writes.push({
+        id: entry.id,
+        targetPath: entry.targetPath,
+        action: entry.action,
+        type: entry.type,
+      });
+      continue;
+    }
+
+    // Back up the existing file before overwriting
+    if (
+      entry.action === 'update' &&
+      entry.mergeStrategy === 'overwrite_with_backup' &&
+      backupRoot &&
+      projectRoot
+    ) {
+      const relPath = path.relative(projectRoot, entry.targetPath);
+      const timestamp = Date.now();
+      const backupPath = path.join(backupRoot, `${relPath}.${timestamp}.bak`);
+      await copyFileSafe(entry.targetPath, backupPath);
+    }
+
+    const binaryEntry = Buffer.isBuffer(entry.renderedContent);
+    const nextContent =
+      entry.mergeStrategy === 'append' && entry.exists && entry.existingContent !== null
+        ? (
+          binaryEntry
+            ? Buffer.concat([entry.existingContent, entry.renderedContent])
+            : `${entry.existingContent}${entry.renderedContent}`
+        )
+        : entry.mergeStrategy === 'prepend' && entry.exists && entry.existingContent !== null
+          ? (
+            binaryEntry
+              ? Buffer.concat([entry.renderedContent, entry.existingContent])
+              : `${entry.renderedContent}${entry.existingContent}`
+          )
+          : entry.renderedContent;
+
+    await writeFileAtomic(entry.targetPath, nextContent);
+    if (typeof entry.mode === 'number') {
+      await fs.chmod(entry.targetPath, entry.mode);
+    }
+    writes.push({
+      id: entry.id,
+      targetPath: entry.targetPath,
+      action: entry.action,
+      type: entry.type,
+    });
+  }
+
+  return { writes, skippedUpdates };
+}

package/src/core/buildPlan.js

@@ -0,0 +1,228 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { selectManifestItems } from '../manifest/selectItems.js';
+import { renderTemplateString } from '../render/renderTemplate.js';
+
+const BINARY_TEMPLATE_EXTENSIONS = new Set([
+  '.ttf',
+  '.otf',
+  '.woff',
+  '.woff2',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.ico',
+  '.webp',
+  '.avif',
+  '.mp3',
+  '.mp4',
+  '.mov',
+  '.zip',
+  '.gz',
+  '.tgz',
+  '.tar',
+  '.pdf',
+]);
+
+function safeResolve(basePath, relativePath) {
+  const resolvedPath = path.resolve(basePath, relativePath);
+  const relativeToBase = path.relative(basePath, resolvedPath);
+
+  if (relativeToBase.startsWith('..') || path.isAbsolute(relativeToBase)) {
+    throw new Error(`Path escapes base directory: ${relativePath}`);
+  }
+
+  return resolvedPath;
+}
+
+async function readTemplateFile(filePath, { binary = false } = {}) {
+  if (binary) {
+    return fs.readFile(filePath);
+  }
+  return fs.readFile(filePath, 'utf8');
+}
+
+async function walkDirectory(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (entry.name === '.DS_Store') {
+      continue;
+    }
+
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkDirectory(fullPath)));
+    } else if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function shouldTreatTemplateAsBinary(filePath) {
+  return BINARY_TEMPLATE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+export async function buildInstallPlan({
+  manifest,
+  stackContext,
+  templatesRoot,
+  variables,
+  projectRoot,
+  selectedAdapterItemIds,
+}) {
+  const selectedItems = selectManifestItems({
+    items: manifest.items,
+    detectedPacks: stackContext.detectedPacks,
+    selectedAdapterItemIds,
+  });
+
+  const planEntries = [];
+  const manifestSourcePaths = new Set();
+  const explicitTargetPaths = new Set();
+  const selectedIds = new Set(selectedItems.map((item) => item.id));
+
+  // Collect source directories of excluded manifest items so auto-discovery
+  // does not install files that belong to filtered-out packs.
+  // Skip link items — their sourceTemplate is relative to projectRoot, not templatesRoot.
+  const excludedSourceDirs = [];
+  for (const item of manifest.items) {
+    if (!selectedIds.has(item.id) && item.type !== 'link') {
+      const sourcePath = safeResolve(templatesRoot, item.sourceTemplate);
+      const stat = await fs.stat(sourcePath);
+      const sourceDir = (stat.isDirectory() ? sourcePath : path.dirname(sourcePath)) + path.sep;
+      excludedSourceDirs.push(sourceDir);
+    }
+  }
+
+  // Prepare items: resolve paths and collect template reads to parallelize
+  const fileItems = [];
+
+  for (const item of selectedItems) {
+    if (item.type === 'link') {
+      const targetPath = safeResolve(projectRoot, item.targetPath);
+      explicitTargetPaths.add(targetPath);
+      const linkTarget = safeResolve(projectRoot, item.sourceTemplate);
+      planEntries.push({
+        id: item.id,
+        type: 'link',
+        linkTarget,
+        targetPath,
+        mergeStrategy: item.mergeStrategy ?? 'overwrite_with_backup',
+        renderedContent: null,
+        requires: item.requires ?? [],
+      });
+    } else {
+      const sourcePath = safeResolve(templatesRoot, item.sourceTemplate);
+      const stat = await fs.stat(sourcePath);
+      if (stat.isDirectory()) {
+        const nestedFiles = await walkDirectory(sourcePath);
+        const nestedStats = await Promise.all(nestedFiles.map((filePath) => fs.stat(filePath)));
+
+        for (let index = 0; index < nestedFiles.length; index += 1) {
+          const nestedSourcePath = nestedFiles[index];
+          const relativeChildPath = path.relative(sourcePath, nestedSourcePath);
+          const targetPath = safeResolve(projectRoot, path.join(item.targetPath, relativeChildPath));
+          manifestSourcePaths.add(nestedSourcePath);
+          explicitTargetPaths.add(targetPath);
+          fileItems.push({
+            item,
+            sourcePath: nestedSourcePath,
+            targetPath,
+            sourceMode: nestedStats[index].mode & 0o777,
+            binary: shouldTreatTemplateAsBinary(nestedSourcePath),
+          });
+        }
+      } else {
+        const targetPath = safeResolve(projectRoot, item.targetPath);
+        manifestSourcePaths.add(sourcePath);
+        explicitTargetPaths.add(targetPath);
+        fileItems.push({
+          item,
+          sourcePath,
+          targetPath,
+          sourceMode: stat.mode & 0o777,
+          binary: shouldTreatTemplateAsBinary(sourcePath),
+        });
+      }
+    }
+  }
+
+  // Read all template files in parallel
+  const templateContents = await Promise.all(
+    fileItems.map(({ sourcePath, binary }) => readTemplateFile(sourcePath, { binary })),
+  );
+
+  for (let i = 0; i < fileItems.length; i++) {
+    const { item, sourcePath, targetPath } = fileItems[i];
+    const renderedContent = fileItems[i].binary
+      ? templateContents[i]
+      : renderTemplateString(templateContents[i], variables);
+
+    planEntries.push({
+      id: item.id,
+      type: item.type,
+      sourcePath,
+      targetPath,
+      mergeStrategy: item.mergeStrategy,
+      renderedContent,
+      requires: item.requires ?? [],
+      mode: fileItems[i].sourceMode,
+    });
+  }
+
+  // Auto-discover files in templates/ not covered by manifest
+  if (manifest.autoDiscoverTemplates === true) {
+    const allTemplateFiles = await walkDirectory(templatesRoot);
+
+    // Filter eligible files first
+    const autoFiles = [];
+    for (const filePath of allTemplateFiles) {
+      if (manifestSourcePaths.has(filePath)) continue;
+      if (excludedSourceDirs.some((dir) => filePath.startsWith(dir))) continue;
+
+      const relativePath = path.relative(templatesRoot, filePath);
+      const targetPath = safeResolve(projectRoot, relativePath);
+      if (explicitTargetPaths.has(targetPath)) continue;
+
+      autoFiles.push({ filePath, relativePath, targetPath });
+    }
+
+    // Read all auto-discovered templates in parallel
+    const autoContents = await Promise.all(
+      autoFiles.map(({ filePath }) => readTemplateFile(filePath, {
+        binary: shouldTreatTemplateAsBinary(filePath),
+      })),
+    );
+
+    const autoStats = await Promise.all(autoFiles.map(({ filePath }) => fs.stat(filePath)));
+
+    for (let i = 0; i < autoFiles.length; i++) {
+      const { filePath, relativePath, targetPath } = autoFiles[i];
+      const renderedContent = shouldTreatTemplateAsBinary(filePath)
+        ? autoContents[i]
+        : renderTemplateString(autoContents[i], variables);
+      const mode = autoStats[i].mode & 0o777;
+
+      planEntries.push({
+        id: `auto:${relativePath}`,
+        type: 'auto',
+        sourcePath: filePath,
+        targetPath,
+        mergeStrategy: 'overwrite_with_backup',
+        renderedContent,
+        requires: [],
+        mode,
+      });
+    }
+  }
+
+  return {
+    selectedItems,
+    entries: planEntries,
+  };
+}

package/src/core/compact/index.js

@@ -0,0 +1,294 @@
+import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { buildRuntimePaths } from '../runtimePaths.js';
+import { compressLine, compressMarkdownLines, estimateTokenCount } from '../token/index.js';
+
+export const DEFAULT_COMPACT_HISTORY_MAX_ENTRIES = 50;
+const DEFAULT_MAX_COMPACT_ANCHORS = 3;
+
+function normalizeCompactHistoryEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+
+  const timestamp = Number(entry.timestamp);
+  const tokensBefore = Number(entry.tokensBefore);
+  const tokensAfter = Number(entry.tokensAfter);
+  const savedTokens = Number(entry.savedTokens);
+
+  return {
+    ...entry,
+    timestamp: Number.isFinite(timestamp) ? timestamp : Date.now(),
+    tokensBefore: Number.isFinite(tokensBefore) ? tokensBefore : 0,
+    tokensAfter: Number.isFinite(tokensAfter) ? tokensAfter : 0,
+    savedTokens: Number.isFinite(savedTokens) ? savedTokens : 0,
+  };
+}
+
+function normalizeCompactHistoryDocument(raw, { maxEntries = DEFAULT_COMPACT_HISTORY_MAX_ENTRIES } = {}) {
+  const candidates = Array.isArray(raw?.entries)
+    ? raw.entries
+    : Array.isArray(raw)
+      ? raw
+      : [];
+
+  return {
+    entries: candidates
+      .map((entry) => normalizeCompactHistoryEntry(entry))
+      .filter(Boolean)
+      .sort((left, right) => (right.timestamp ?? 0) - (left.timestamp ?? 0))
+      .slice(0, maxEntries),
+  };
+}
+
+export function compactContextBlock(
+  lines,
+  {
+    header = null,
+    maxTokens = 300,
+    maxLines = 10,
+    anchorLines = [],
+    anchorPatterns = [],
+    maxAnchors = DEFAULT_MAX_COMPACT_ANCHORS,
+  } = {},
+) {
+  const contentLines = Array.isArray(lines)
+    ? lines.filter((line) => typeof line === 'string')
+    : [];
+  const rawLines = header ? [header, ...contentLines] : [...contentLines];
+  const rawText = rawLines.join('\n');
+  const normalizedMaxLines = header ? maxLines + 1 : maxLines;
+  const normalizedAnchorLines = resolveAnchorLines(rawLines, {
+    header,
+    anchorLines,
+    anchorPatterns,
+    maxAnchors,
+  });
+  const compactedLines = buildCompactedContextLines(rawLines, {
+    maxTokens,
+    maxLines: normalizedMaxLines,
+    preserveFirstLine: Boolean(header),
+    forceFirstCount: header ? 1 : 0,
+  });
+  let text = compactedLines.join('\n').trim();
+  let validationMode = 'default';
+
+  if (normalizedAnchorLines.length > 0 && findMissingAnchors(text, normalizedAnchorLines).length > 0) {
+    const anchorFirstLines = buildCompactedContextLines(
+      header
+        ? [header, ...normalizedAnchorLines, ...contentLines]
+        : [...normalizedAnchorLines, ...contentLines],
+      {
+        maxTokens,
+        maxLines: normalizedMaxLines,
+        preserveFirstLine: Boolean(header),
+        forceFirstCount: (header ? 1 : 0) + normalizedAnchorLines.length,
+      },
+    );
+    const anchorFirstText = anchorFirstLines.join('\n').trim();
+
+    if (findMissingAnchors(anchorFirstText, normalizedAnchorLines).length === 0) {
+      text = anchorFirstText;
+      validationMode = 'anchor-first';
+    } else {
+      text = buildCompactedContextLines(
+        header
+          ? [header, ...normalizedAnchorLines]
+          : [...normalizedAnchorLines],
+        {
+          maxTokens,
+          maxLines: normalizedMaxLines,
+          preserveFirstLine: Boolean(header),
+          forceFirstCount: (header ? 1 : 0) + normalizedAnchorLines.length,
+        },
+      ).join('\n').trim();
+      validationMode = 'forced-anchors';
+    }
+  }
+
+  const tokensBefore = estimateTokenCount(rawText);
+  const tokensAfter = estimateTokenCount(text);
+
+  return {
+    text,
+    tokensBefore,
+    tokensAfter,
+    savedTokens: Math.max(0, tokensBefore - tokensAfter),
+    validationMode,
+    anchorCount: normalizedAnchorLines.length,
+  };
+}
+
+function normalizeAnchorPattern(pattern) {
+  if (pattern instanceof RegExp) {
+    return (line) => pattern.test(line);
+  }
+  if (typeof pattern === 'string' && pattern.trim()) {
+    const prefix = pattern.trim();
+    return (line) => line.startsWith(prefix);
+  }
+  if (typeof pattern === 'function') {
+    return pattern;
+  }
+  return null;
+}
+
+function normalizeLineForDedupe(line) {
+  return String(line ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+function uniqueLines(lines) {
+  const seen = new Set();
+  const unique = [];
+
+  for (const line of lines) {
+    const trimmed = String(line ?? '').trim();
+    const normalized = normalizeLineForDedupe(trimmed);
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    unique.push(trimmed);
+  }
+
+  return unique;
+}
+
+function resolveAnchorLines(rawLines, { header = null, anchorLines = [], anchorPatterns = [], maxAnchors = DEFAULT_MAX_COMPACT_ANCHORS } = {}) {
+  const predicates = anchorPatterns
+    .map((pattern) => normalizeAnchorPattern(pattern))
+    .filter(Boolean);
+  const explicitAnchorLines = Array.isArray(anchorLines) ? anchorLines : [];
+  const matchedPatternLines = predicates.length > 0
+    ? rawLines.filter((line) => {
+        const trimmed = String(line ?? '').trim();
+        return trimmed && predicates.some((predicate) => predicate(trimmed));
+      })
+    : [];
+
+  return uniqueLines([
+    ...explicitAnchorLines,
+    ...matchedPatternLines,
+  ])
+    .filter((line) => !header || normalizeLineForDedupe(line) !== normalizeLineForDedupe(header))
+    .slice(0, Math.max(0, maxAnchors));
+}
+
+function buildCompactedContextLines(
+  lines,
+  {
+    maxTokens = 300,
+    maxLines = 10,
+    preserveFirstLine = true,
+    forceFirstCount = 0,
+  } = {},
+) {
+  const sourceLines = Array.isArray(lines) ? lines : [];
+  const selected = [];
+  const seen = new Set();
+  let usedTokens = 0;
+  let nonEmptyCount = 0;
+
+  for (const line of sourceLines) {
+    const compressed = compressLine(line);
+    if (!compressed) {
+      continue;
+    }
+
+    const dedupeKey = compressed.toLowerCase();
+    if (seen.has(dedupeKey)) {
+      continue;
+    }
+
+    const tokens = estimateTokenCount(compressed);
+    const forceLine = nonEmptyCount < forceFirstCount;
+    const wouldOverflow = selected.length > 0 && (usedTokens + tokens) > maxTokens;
+    const wouldExceedLines = nonEmptyCount >= maxLines;
+
+    if (!forceLine && (wouldOverflow || wouldExceedLines)) {
+      break;
+    }
+    if (forceLine && wouldExceedLines) {
+      break;
+    }
+
+    selected.push(compressed);
+    seen.add(dedupeKey);
+    usedTokens += tokens;
+    nonEmptyCount += 1;
+  }
+
+  if (selected.length === 0) {
+    return compressMarkdownLines(sourceLines, {
+      maxTokens,
+      maxLines,
+      preserveFirstLine,
+    });
+  }
+
+  return selected;
+}
+
+function findMissingAnchors(text, anchorLines) {
+  const normalizedText = String(text ?? '').toLowerCase();
+  return anchorLines.filter((line) => {
+    const compressed = compressLine(line).toLowerCase();
+    return compressed && !normalizedText.includes(compressed);
+  });
+}
+
+export async function readCompactHistory(projectRoot, options = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const raw = await readJsonIfExists(runtimePaths.compactHistoryPath);
+  return normalizeCompactHistoryDocument(raw, options);
+}
+
+export async function appendCompactHistory(
+  projectRoot,
+  entry,
+  {
+    maxEntries = DEFAULT_COMPACT_HISTORY_MAX_ENTRIES,
+  } = {},
+) {
+  const normalizedEntry = normalizeCompactHistoryEntry(entry);
+  if (!normalizedEntry) {
+    return readCompactHistory(projectRoot, { maxEntries });
+  }
+
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const history = await readCompactHistory(projectRoot, { maxEntries });
+  const nextDocument = normalizeCompactHistoryDocument({
+    entries: [normalizedEntry, ...history.entries],
+  }, { maxEntries });
+  await writeJson(runtimePaths.compactHistoryPath, nextDocument);
+  return nextDocument;
+}
+
+export async function recordCompaction(
+  projectRoot,
+  {
+    source = 'unknown',
+    beforeText = '',
+    afterText = '',
+    timestamp = Date.now(),
+    metadata = null,
+  } = {},
+) {
+  const tokensBefore = estimateTokenCount(beforeText);
+  const tokensAfter = estimateTokenCount(afterText);
+  const savedTokens = Math.max(0, tokensBefore - tokensAfter);
+
+  if (savedTokens <= 0) {
+    return null;
+  }
+
+  const entry = {
+    timestamp,
+    source,
+    tokensBefore,
+    tokensAfter,
+    savedTokens,
+    metadata,
+  };
+  await appendCompactHistory(projectRoot, entry);
+  return entry;
+}