@ngockhoale/ukit 2.3.22 → 2.3.23

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.23 - 2026-09-13
+
+Self-install no longer clobbers UKit's own canonical docs. Running `ukit install` inside the UKit
+source repository (e.g. the global CLI invoked from the repo) overwrote `docs/PROMPT_CACHING.md` —
+the canonical 368-line ruleset — with the distilled 127-line copy shipped under `templates/docs/`,
+because the manifest item is `overwrite_with_backup` and self-install went undetected.
+
+- **Self-install detection.** `buildInstallPlan` now recognizes an install targeting the UKit repo
+  by two independent signals: the templates resolving inside the install target (the repo has a
+  `templates/` directory, the global CLI does not), or the target `package.json` naming
+  `@ngockhoale/ukit`. This covers the common case where the global CLI runs inside the repo, which
+  the path-containment check alone misses.
+- **Docs downgraded to seed-only.** On a detected self-install, every `overwrite_with_backup`
+  entry whose target lives under `docs/` is downgraded to `skip`: a missing doc is seeded, but an
+  existing canonical doc is never overwritten. Downstream projects are unaffected — their docs
+  refresh on `ukit update` as before.
+- **Verification.** New `buildInstallPlan` regressions cover the containment signal, the
+  package-name signal, and the unchanged downstream path; the full suite stays green.
+
 ## 2.3.22 - 2026-09-13
 
 Consultation-question routing fix — pure questions no longer fabricate mutation debt that the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.22",
+  "version": "2.3.23",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/buildPlan.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { selectManifestItems } from '../manifest/selectItems.js';
 import { renderTemplateString } from '../render/renderTemplate.js';
+import { UKIT_PACKAGE_NAME } from './update.js';
 
 const BINARY_TEMPLATE_EXTENSIONS = new Set([
   '.ttf',
@@ -44,6 +45,52 @@ function safeResolve(basePath, relativePath) {
   return resolvedPath;
 }
 
+function isPathInside(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function isDocsTarget(targetPath, projectRoot) {
+  const relative = path.relative(projectRoot, targetPath);
+  return relative === 'docs' || relative.startsWith(`docs${path.sep}`);
+}
+
+// Detect `ukit install` running against the UKit source repository itself. Two independent
+// signals: the templates resolve inside the install target (the repo has a templates/ dir, the
+// global CLI does not), or the target's package.json declares UKIT_PACKAGE_NAME (the path check
+// misses the common case where the global CLI runs inside the repo).
+async function isSelfInstall({ templatesRoot, projectRoot }) {
+  if (isPathInside(projectRoot, templatesRoot)) {
+    return true;
+  }
+  try {
+    const raw = await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8');
+    return JSON.parse(raw)?.name === UKIT_PACKAGE_NAME;
+  } catch {
+    return false;
+  }
+}
+
+// In the UKit source repo, docs/ holds canonical sources that deliberately diverge from the
+// shipped copies under templates/ (docs/PROMPT_CACHING.md is the full ruleset while
+// templates/docs/ ships a distilled version). The refresh-on-update strategy would silently
+// clobber those canonical files, so downgrade docs overwrites to skip: seed a missing doc, but
+// never overwrite one that already exists.
+async function downgradeSelfInstallDocOverwrites(planEntries, { templatesRoot, projectRoot }) {
+  if (!(await isSelfInstall({ templatesRoot, projectRoot }))) {
+    return;
+  }
+
+  for (const entry of planEntries) {
+    if (entry.type === 'link' || entry.mergeStrategy !== 'overwrite_with_backup') {
+      continue;
+    }
+    if (isDocsTarget(entry.targetPath, projectRoot)) {
+      entry.mergeStrategy = 'skip';
+    }
+  }
+}
+
 async function readTemplateFile(filePath, { binary = false } = {}) {
   if (binary) {
     return fs.readFile(filePath);
@@ -263,6 +310,8 @@ export async function buildInstallPlan({
     }
   }
 
+  await downgradeSelfInstallDocOverwrites(planEntries, { templatesRoot, projectRoot });
+
   return {
     selectedItems,
     entries: planEntries,