@ngockhoale/ukit 1.1.6

package/src/core/diffPlan.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs/promises';
+import { isSymlinkTo } from './fileOps.js';
+
+async function readFileOrNull(filePath, encoding = 'utf8') {
+  try {
+    if (encoding === null) {
+      return await fs.readFile(filePath);
+    }
+    return await fs.readFile(filePath, encoding);
+  } catch {
+    return null;
+  }
+}
+
+async function checkLinkStatus(targetPath, linkTarget) {
+  try {
+    const stat = await fs.lstat(targetPath);
+    if (!stat.isSymbolicLink()) {
+      return 'update'; // exists but is not a symlink — needs replacing
+    }
+    return (await isSymlinkTo(targetPath, linkTarget)) ? 'unchanged' : 'update';
+  } catch {
+    return 'create'; // does not exist
+  }
+}
+
+function resolveFileAction(entry, existingContent) {
+  const exists = existingContent !== null;
+  const binaryEntry = Buffer.isBuffer(entry.renderedContent);
+
+  let action;
+  if (!exists) {
+    action = 'create';
+  } else if (entry.mergeStrategy === 'append' && !binaryEntry) {
+    action = existingContent.endsWith(entry.renderedContent) ? 'unchanged' : 'update';
+  } else if (entry.mergeStrategy === 'prepend' && !binaryEntry) {
+    action = existingContent.startsWith(entry.renderedContent) ? 'unchanged' : 'update';
+  } else if (binaryEntry) {
+    action = Buffer.isBuffer(existingContent) && existingContent.equals(entry.renderedContent)
+      ? 'unchanged'
+      : entry.mergeStrategy === 'skip'
+        ? 'skip'
+        : 'update';
+  } else if (existingContent === entry.renderedContent) {
+    action = 'unchanged';
+  } else if (entry.mergeStrategy === 'skip') {
+    action = 'skip';
+  } else {
+    action = 'update';
+  }
+
+  return { ...entry, exists, action, existingContent };
+}
+
+export async function diffInstallPlan(plan) {
+  // Check all entries in parallel
+  const results = await Promise.all(
+    plan.entries.map(async (entry) => {
+      if (entry.type === 'link') {
+        const action = await checkLinkStatus(entry.targetPath, entry.linkTarget);
+        return { ...entry, exists: action !== 'create', action, existingContent: null };
+      }
+
+      const existingContent = await readFileOrNull(
+        entry.targetPath,
+        Buffer.isBuffer(entry.renderedContent) ? null : 'utf8',
+      );
+      return resolveFileAction(entry, existingContent);
+    }),
+  );
+
+  return results;
+}

package/src/core/ensureGitignore.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { escapeRegExp, writeFileAtomic } from './fileOps.js';
+
+const UKIT_ENTRIES = [
+  '.cache/',
+  '.antigravity/',
+  '.claude/',
+  '.codex/',
+  '.ukit/',
+  'opencode.json',
+  'AGENTS.md',
+  'CLAUDE.md',
+  '.claude/ukit/.ukit/',
+  '.claude/ukit/permission-usage.json',
+  '.claude/ukit/permission-audit.log',
+  '.codex/settings.local.json',
+];
+
+const MARKER_START = '# UKit generated (do not edit)';
+const MARKER_END = '# /UKit';
+
+export async function ensureGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  let content = '';
+  try {
+    content = await fs.readFile(gitignorePath, 'utf8');
+  } catch {
+    // no .gitignore yet
+  }
+
+  const newBlock = [
+    MARKER_START,
+    ...UKIT_ENTRIES,
+    MARKER_END,
+  ].join('\n');
+
+  if (content.includes(MARKER_START)) {
+    // Replace existing UKit block with current entries
+    const blockPattern = new RegExp(
+      `${escapeRegExp(MARKER_START)}[\\s\\S]*?${escapeRegExp(MARKER_END)}`,
+    );
+    const existingBlock = content.match(blockPattern)?.[0];
+    if (existingBlock === newBlock) {
+      return false; // already up to date
+    }
+    const updated = content.replace(blockPattern, newBlock);
+    await writeFileAtomic(gitignorePath, updated);
+    return true;
+  }
+
+  // No marker block — check if entries are already present as active (non-comment) lines.
+  // Must filter out comment lines to avoid false-negatives like "# placeholder .claude/ukit/.ukit/"
+  // matching the entry check and incorrectly skipping the block insertion.
+  const activeLines = content
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((trimmed) => trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('!'));
+  const missing = UKIT_ENTRIES.filter((e) => !activeLines.some((l) => l.includes(e)));
+  if (missing.length === 0) {
+    return false;
+  }
+
+  // Append marker block with missing entries
+  const block = ['', newBlock, ''].join('\n');
+  await writeFileAtomic(gitignorePath, content.trimEnd() + '\n' + block);
+  return true;
+}
+
+/**
+ * Remove the UKit-managed block from .gitignore.
+ * Called by uninstall to leave the project in a clean state.
+ * @returns {boolean} true if the block was found and removed
+ */
+export async function removeGitignoreBlock(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  let content = '';
+  try {
+    content = await fs.readFile(gitignorePath, 'utf8');
+  } catch {
+    return false; // no .gitignore — nothing to remove
+  }
+
+  if (!content.includes(MARKER_START)) {
+    return false; // no UKit block present
+  }
+
+  // Walk lines and excise the block plus any leading blank line that
+  // ensureGitignore appended before the marker.
+  const lines = content.split('\n');
+  const result = [];
+  let inBlock = false;
+
+  for (const line of lines) {
+    if (line === MARKER_START) {
+      inBlock = true;
+      // Remove the blank separator line that ensureGitignore prepended.
+      if (result.length > 0 && result[result.length - 1] === '') {
+        result.pop();
+      }
+      continue;
+    }
+    if (inBlock) {
+      if (line === MARKER_END) {
+        inBlock = false;
+      }
+      continue;
+    }
+    result.push(line);
+  }
+
+  const joined = result.join('\n').trimEnd();
+  await writeFileAtomic(gitignorePath, joined ? joined + '\n' : '');
+  return true;
+}

package/src/core/fileOps.js

@@ -0,0 +1,188 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJsonIfExists(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function resolveProjectRelativePath(projectRoot, relPath) {
+  if (typeof relPath !== 'string') {
+    return null;
+  }
+
+  const trimmed = relPath.trim();
+  if (!trimmed || trimmed === '.' || trimmed === '..') {
+    return null;
+  }
+
+  if (path.isAbsolute(trimmed)) {
+    return null;
+  }
+
+  const absolute = path.resolve(projectRoot, trimmed);
+  const root = path.resolve(projectRoot);
+  const relative = path.relative(root, absolute);
+
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    return null;
+  }
+
+  return absolute;
+}
+
+export async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function writeFileAtomic(filePath, content) {
+  const dir = path.dirname(filePath);
+  await ensureDir(dir);
+
+  const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+  try {
+    if (Buffer.isBuffer(content)) {
+      await fs.writeFile(tempPath, content);
+    } else {
+      await fs.writeFile(tempPath, content, 'utf8');
+    }
+    await fs.rename(tempPath, filePath);
+  } catch (error) {
+    try {
+      await fs.rm(tempPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+
+    if (error?.code === 'EISDIR') {
+      throw new Error(
+        `Cannot write file ${filePath} because a directory already exists there. Remove or rename the directory and try again.`,
+        { cause: error },
+      );
+    }
+
+    throw error;
+  }
+}
+
+export async function copyFileSafe(fromPath, toPath) {
+  await ensureDir(path.dirname(toPath));
+  await fs.copyFile(fromPath, toPath);
+}
+
+export async function writeJson(filePath, data) {
+  await writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+/**
+ * Create a directory symlink (macOS/Linux) or junction (Windows).
+ * Junctions on Windows don't require elevated privileges.
+ * @param {string} target - Absolute path to the link target directory
+ * @param {string} linkPath - Absolute path where the link will be created
+ */
+export async function createDirectoryLink(target, linkPath) {
+  await ensureDir(path.dirname(linkPath));
+
+  if (process.platform === 'win32') {
+    // Junctions require absolute paths on Windows
+    await fs.symlink(path.resolve(target), linkPath, 'junction');
+  } else {
+    // Relative symlink for portability on macOS/Linux
+    const relTarget = path.relative(path.dirname(linkPath), target);
+    await fs.symlink(relTarget, linkPath);
+  }
+}
+
+/**
+ * Check if linkPath is a symlink/junction pointing to the expected target.
+ * @param {string} linkPath - Path to check
+ * @param {string} expectedTarget - Absolute path the link should resolve to
+ * @returns {boolean}
+ */
+export async function isSymlinkTo(linkPath, expectedTarget) {
+  try {
+    const stat = await fs.lstat(linkPath);
+    if (!stat.isSymbolicLink()) return false;
+
+    const actual = await fs.readlink(linkPath);
+    const resolved = path.resolve(path.dirname(linkPath), actual);
+    return resolved === path.resolve(expectedTarget);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove a symlink or junction only — does NOT remove real directories.
+ * Safe to call on adapter link paths where a real directory means user content.
+ * @param {string} linkPath - Path to remove
+ * @returns {boolean} true if a symlink/junction was removed
+ */
+export async function removeLinkOnly(linkPath) {
+  try {
+    const stat = await fs.lstat(linkPath);
+    if (!stat.isSymbolicLink()) return false;
+    await fs.unlink(linkPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove a managed file or symlink only — does NOT remove real directories.
+ * Safe for adapter-managed config/readme files where a directory would imply user content.
+ * @param {string} targetPath - Path to remove
+ * @returns {boolean} true if a file/symlink was removed
+ */
+export async function removeFileOrLinkOnly(targetPath) {
+  try {
+    const stat = await fs.lstat(targetPath);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+      return false;
+    }
+    await fs.unlink(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove a symlink, junction, or directory at the given path.
+ * @param {string} linkPath - Path to remove
+ * @returns {boolean} true if something was removed
+ */
+export async function removeLinkOrDir(linkPath) {
+  try {
+    const stat = await fs.lstat(linkPath);
+    if (stat.isSymbolicLink()) {
+      await fs.unlink(linkPath);
+    } else if (stat.isDirectory()) {
+      await fs.rm(linkPath, { recursive: true, force: true });
+    } else {
+      await fs.unlink(linkPath);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/core/memory/hygiene.js

@@ -0,0 +1,160 @@
+const DEFAULT_CONFIG = {
+  archiveAfterDays: 30,
+  maxSessionsKept: 20,
+  conflictResolution: 'latest_wins',
+  redactPatterns: [
+    /sk-[a-z0-9_-]+/gi,
+    /api[_-]?key\s*[:=]\s*[^\s,;]+/gi,
+    /password\s*[:=]\s*[^\s,;]+/gi,
+  ],
+};
+
+const CATEGORY_KEYWORDS = {
+  database: ['postgresql', 'mysql', 'sqlite', 'mariadb', 'mongodb', 'redis'],
+  api_style: ['rest', 'graphql', 'grpc'],
+  auth: ['jwt', 'session', 'oauth', 'saml', 'apikey', 'api key'],
+  backend_framework: ['express', 'fastify', 'nestjs', 'koa', 'hono'],
+  frontend_framework: ['react', 'vue', 'svelte', 'angular'],
+};
+
+function clone(value) {
+  if (value === undefined || value === null) {
+    return {};
+  }
+
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalize(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function uniqueStrings(values) {
+  return [...new Set((values ?? []).filter(Boolean))];
+}
+
+function redactString(text, patterns) {
+  let result = String(text ?? '');
+  for (const pattern of patterns) {
+    result = result.replace(pattern, '[REDACTED]');
+  }
+  return result;
+}
+
+function redactValue(value, patterns) {
+  if (typeof value === 'string') {
+    return redactString(value, patterns);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactValue(entry, patterns));
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, redactValue(entry, patterns)]),
+    );
+  }
+
+  return value;
+}
+
+function inferDecisionCategory(decisionText) {
+  const normalized = normalize(decisionText);
+  for (const [category, keywords] of Object.entries(CATEGORY_KEYWORDS)) {
+    if (keywords.some((keyword) => normalized.includes(keyword))) {
+      return category;
+    }
+  }
+
+  return null;
+}
+
+export function detectConflict(newDecision, existingDecisions = []) {
+  const newCategory = inferDecisionCategory(newDecision?.what);
+  if (!newCategory) {
+    return null;
+  }
+
+  const normalizedNewWhat = normalize(newDecision?.what);
+  return existingDecisions.find((decision) => {
+    if (!decision || decision.id === newDecision?.id) {
+      return false;
+    }
+
+    const existingCategory = inferDecisionCategory(decision.what);
+    if (existingCategory !== newCategory) {
+      return false;
+    }
+
+    return normalize(decision.what) !== normalizedNewWhat;
+  }) ?? null;
+}
+
+function resolveDecisionConflicts(projectMemory, conflictResolution) {
+  const decisions = [...(projectMemory.decisions ?? [])].sort((left, right) => (left.when ?? 0) - (right.when ?? 0));
+  const conflicts = [];
+
+  for (let index = 0; index < decisions.length; index += 1) {
+    const current = decisions[index];
+    const prior = decisions.slice(0, index).filter((decision) => !decision.supersededBy);
+    const conflict = detectConflict(current, prior);
+    if (!conflict) {
+      continue;
+    }
+
+    conflicts.push({ oldDecisionId: conflict.id, newDecisionId: current.id });
+    if (conflictResolution === 'latest_wins') {
+      conflict.supersededBy = current.id;
+    }
+  }
+
+  projectMemory.decisions = decisions;
+  return conflicts;
+}
+
+function archiveSessions(projectMemory, config) {
+  const now = config.now ?? Date.now();
+  const maxAgeMs = config.archiveAfterDays * 24 * 60 * 60 * 1000;
+  const sessions = [...(projectMemory.sessions ?? [])].sort((left, right) => (right.endedAt ?? 0) - (left.endedAt ?? 0));
+
+  const retained = [];
+  const archived = [];
+
+  for (const session of sessions) {
+    const sessionEndedAt = session.endedAt ?? session.startedAt ?? 0;
+    const isExpired = sessionEndedAt > 0 ? (now - sessionEndedAt) > maxAgeMs : false;
+    const overLimit = retained.length >= config.maxSessionsKept;
+
+    if (isExpired || overLimit) {
+      archived.push(session);
+    } else {
+      retained.push(session);
+    }
+  }
+
+  projectMemory.sessions = retained;
+  return archived;
+}
+
+export function runHygiene(projectMemory, config = {}) {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  const nextMemory = redactValue(clone(projectMemory), mergedConfig.redactPatterns);
+
+  nextMemory.conventions = uniqueStrings(nextMemory.conventions);
+  nextMemory.techStack = uniqueStrings(nextMemory.techStack);
+  nextMemory.activeRules = uniqueStrings(nextMemory.activeRules);
+
+  const conflicts = resolveDecisionConflicts(nextMemory, mergedConfig.conflictResolution);
+  const archivedSessions = archiveSessions(nextMemory, mergedConfig);
+
+  return {
+    projectMemory: nextMemory,
+    archivedSessions,
+    conflicts,
+  };
+}

package/src/core/memory/index.js

@@ -0,0 +1,2 @@
+export { detectConflict, runHygiene } from './hygiene.js';
+export { expand, getContextInjection, search } from './retrieval.js';