@ngockhoale/ukit 1.1.6

package/src/core/metadata.js

@@ -0,0 +1,132 @@
+import path from 'node:path';
+import { ensureDir, writeJson, readJsonIfExists } from './fileOps.js';
+
+function normalizeTrackedRelativePath(relativePath) {
+  if (typeof relativePath !== 'string') {
+    return null;
+  }
+
+  const trimmed = relativePath.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return trimmed.replace(/\\/g, '/');
+}
+
+function isSameOrDescendantPath(candidatePath, parentPath) {
+  if (!candidatePath || !parentPath) {
+    return false;
+  }
+
+  return candidatePath === parentPath || candidatePath.startsWith(`${parentPath}/`);
+}
+
+export async function writeInstallMetadata({
+  installMetaPath,
+  packageVersion,
+  manifest,
+  stackContext,
+  providerContext,
+  summary,
+  writes = [],
+  projectRoot,
+  managedRelativePaths = null,
+  retainedManagedRelativePaths = [],
+}) {
+  // Accumulate file tracking across re-installs so files written in earlier runs
+  // remain tracked (they are 'skip'/'unchanged' on re-install and don't appear in
+  // the current writes, but we still need to remove them on uninstall).
+  const previousData = await readJsonIfExists(installMetaPath);
+  const previousFiles = previousData?.tool === 'ukit' && Array.isArray(previousData?.files)
+    ? previousData.files
+    : [];
+  const managedPathSet = Array.isArray(managedRelativePaths)
+    ? new Set(managedRelativePaths.map((value) => normalizeTrackedRelativePath(value)).filter(Boolean))
+    : null;
+  const retainedManagedPathSet = new Set(
+    retainedManagedRelativePaths.map((value) => normalizeTrackedRelativePath(value)).filter(Boolean),
+  );
+
+  // Convert writes to tracked entries stored as relative paths for portability.
+  const newEntries = projectRoot
+    ? writes.map((w) => ({
+        p: normalizeTrackedRelativePath(path.relative(projectRoot, w.targetPath)),
+        t: w.type, // 'link', 'command', 'agent', 'hook', 'config', 'skill', etc.
+      })).filter((entry) => {
+        if (!entry.p) {
+          return false;
+        }
+        if (!managedPathSet) {
+          return true;
+        }
+        return managedPathSet.has(entry.p) || retainedManagedPathSet.has(entry.p);
+      })
+    : [];
+
+  // Merge: keep entries from previous runs for paths not re-written this run,
+  // then append new entries (updating type info for any that were re-written).
+  const newPaths = new Set(newEntries.map((e) => e.p));
+  const retained = previousFiles.filter((e) => {
+    const p = normalizeTrackedRelativePath(typeof e === 'string' ? e : e?.p);
+    if (!p) {
+      return false;
+    }
+    if (managedPathSet && !managedPathSet.has(p) && !retainedManagedPathSet.has(p)) {
+      return false;
+    }
+    return !newPaths.has(p);
+  });
+  const allFiles = [...retained, ...newEntries];
+
+  const metadata = {
+    tool: 'ukit',
+    version: packageVersion,
+    installedAt: new Date().toISOString(),
+    manifest: {
+      name: manifest.name,
+      version: manifest.version,
+    },
+    stack: stackContext,
+    providers: providerContext,
+    summary,
+    files: allFiles,
+  };
+
+  await ensureDir(path.dirname(installMetaPath));
+  await writeJson(installMetaPath, metadata);
+}
+
+export async function removeTrackedPathsFromMetadata({
+  installMetaPath,
+  projectRoot,
+  removeRelativePaths = [],
+}) {
+  if (!removeRelativePaths.length) {
+    return;
+  }
+
+  const metadata = await readJsonIfExists(installMetaPath);
+  if (!metadata || metadata.tool !== 'ukit' || !Array.isArray(metadata.files)) {
+    return;
+  }
+
+  const normalizedTargets = new Set(
+    removeRelativePaths.map((relPath) => relPath && relPath.replace(/\\/g, '/')),
+  );
+
+  const filteredFiles = metadata.files.filter((entry) => {
+    const p = typeof entry === 'string' ? entry : entry?.p;
+    if (!p) {
+      return true;
+    }
+    const normalized = p.replace(/\\/g, '/');
+    return ![...normalizedTargets].some((targetPath) => isSameOrDescendantPath(normalized, targetPath));
+  });
+
+  if (filteredFiles.length === metadata.files.length) {
+    return;
+  }
+
+  await writeJson(installMetaPath, { ...metadata, files: filteredFiles });
+}

package/src/core/migrateLegacy.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { removeFileOrLinkOnly } from './fileOps.js';
+
+async function statIfExists(targetPath) {
+  try {
+    return await fs.lstat(targetPath);
+  } catch {
+    return null;
+  }
+}
+
+async function removeDirIfEmpty(dirPath) {
+  try {
+    const entries = await fs.readdir(dirPath);
+    if (entries.length === 0) {
+      await fs.rmdir(dirPath);
+      return true;
+    }
+  } catch {
+    // Directory does not exist or is not accessible — nothing to do.
+  }
+  return false;
+}
+
+/**
+ * Move legacy shared runtime data from ukit/ to .ukit/ without overwriting
+ * any newer runtime state that may already exist.
+ */
+export async function migrateLegacyRuntimeRoot(projectRoot) {
+  const legacyRuntimeRoot = path.join(projectRoot, 'ukit');
+  const runtimeRoot = path.join(projectRoot, '.ukit');
+
+  const legacyRootStat = await statIfExists(legacyRuntimeRoot);
+  if (!legacyRootStat?.isDirectory()) {
+    return { migrated: false, moved: 0, skipped: 0 };
+  }
+
+  const runtimeRootStat = await statIfExists(runtimeRoot);
+  if (runtimeRootStat && !runtimeRootStat.isDirectory()) {
+    return { migrated: false, moved: 0, skipped: 2 };
+  }
+
+  const runtimeEntries = [
+    {
+      legacyPath: path.join(legacyRuntimeRoot, 'README.md'),
+      targetPath: path.join(runtimeRoot, 'README.md'),
+      isExpectedType: (stat) => stat.isFile(),
+    },
+    {
+      legacyPath: path.join(legacyRuntimeRoot, 'storage'),
+      targetPath: path.join(runtimeRoot, 'storage'),
+      isExpectedType: (stat) => stat.isDirectory(),
+    },
+  ];
+
+  let moved = 0;
+  let skipped = 0;
+
+  for (const entry of runtimeEntries) {
+    const sourceStat = await statIfExists(entry.legacyPath);
+    if (!sourceStat) {
+      continue;
+    }
+
+    if (!entry.isExpectedType(sourceStat)) {
+      skipped += 1;
+      continue;
+    }
+
+    if (await statIfExists(entry.targetPath)) {
+      skipped += 1;
+      continue;
+    }
+
+    await fs.mkdir(path.dirname(entry.targetPath), { recursive: true });
+    await fs.rename(entry.legacyPath, entry.targetPath);
+    moved += 1;
+  }
+
+  if (moved > 0) {
+    await removeDirIfEmpty(legacyRuntimeRoot);
+  }
+
+  return {
+    migrated: moved > 0,
+    moved,
+    skipped,
+  };
+}
+
+/**
+ * Remove old flat-file skill paths that were replaced by folder/SKILL.md format.
+ * This runs after install to clean up files from previous UKit versions.
+ */
+export async function cleanupLegacyPaths(projectRoot) {
+  const legacySkillFiles = [
+    // Old installer leftovers stayed under ukit/ in earlier releases. Remove
+    // only known UKit-owned sub-paths, not the root.
+    // The root is only removed below if empty, to avoid deleting user-owned directories.
+    // Only delete the specific file UKit created — NOT the directory.
+    // Users may have added their own scripts to ukit/scripts/; deleting the
+    // whole directory would silently destroy their content (P0 data loss).
+    path.join(projectRoot, 'ukit', 'scripts', 'setup-mcp.sh'),
+    path.join(projectRoot, 'ukit', '.env.example'),
+    path.join(projectRoot, 'ukit', '.ukit', 'install.json'),
+    path.join(projectRoot, '.claude', 'skills', 'delivery.md'),
+    path.join(projectRoot, '.claude', 'skills', 'frontend.md'),
+    path.join(projectRoot, '.claude', 'skills', 'backend-api.md'),
+    path.join(projectRoot, '.claude', 'skills', 'postgres.md'),
+    // NOTE: AGENT.md is intentionally excluded from legacy cleanup.
+    // We cannot distinguish between UKit-generated and user-created AGENT.md.
+    // Deleting it unconditionally would be a P0 data loss for users who have
+    // their own AGENT.md. Users must remove any leftover AGENT.md manually.
+  ];
+
+  let cleaned = 0;
+  for (const legacyPath of legacySkillFiles) {
+    if (await removeFileOrLinkOnly(legacyPath)) {
+      cleaned += 1;
+    }
+  }
+
+  // Prune known legacy directories if they became empty.
+  if (await removeDirIfEmpty(path.join(projectRoot, 'ukit', 'scripts'))) {
+    cleaned += 1;
+  }
+  if (await removeDirIfEmpty(path.join(projectRoot, 'ukit', '.ukit'))) {
+    cleaned += 1;
+  }
+
+  // Only remove ukit/ root if it is now empty — never force-delete user content.
+  const ukitLegacyRoot = path.join(projectRoot, 'ukit');
+  if (await removeDirIfEmpty(ukitLegacyRoot)) {
+    cleaned += 1;
+  }
+
+  return { cleaned };
+}