@ngockhoale/ukit 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to UKit are documented here.
 
+## 2.5.1 - 2026-09-18
+
+Post-release fixes from C20 reviewer advisories.
+
+- **`projectImportant` symlink fallback**: the odd-open-error fallback imported
+  `stat` as `lstat`, which follows symlinks — a broken symlink degraded to `missing`
+  and a symlink-to-file to `unreadable` instead of the correct `unsafe-type`
+  (spec §6.1). Now uses real `lstat`; fixed in `src/core/projectImportant.js` and both
+  installed-runtime mirrors (parity-locked).
+- **`inspectProjectImportant` guard**: a non-string `projectRoot` threw `TypeError`
+  before the try block instead of degrading to `unreadable`, violating the
+  "no documented entry point throws" contract. Guard added (src + mirrors).
+- **Uninstall backup exhaustion surfaced**: when all 101 backup-name candidates are
+  occupied, `PROJECT_IMPORTANT.md` was silently preserved without a backup. Now emits
+  a `backupWarnings` line telling the user to free a slot and rerun.
+- **Test tightening**: the packed-install smoke now asserts `project-important.sh`
+  occupies SessionStart index 0 (spec: must run first); corrected a stale "~5%
+  headroom" comment on the unpacked-size ceiling.
+
 ## 2.5.0 - 2026-09-18
 
 C20 feature release (14 handoff tasks + 3-lane review): project-owner instructions via a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "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/projectImportant.js

@@ -17,7 +17,7 @@
  */
 
 import fs from 'node:fs';
-import { open, stat as lstat, readFile } from 'node:fs/promises';
+import { open, lstat, readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import {
@@ -112,6 +112,9 @@ function invalidResult(state) {
  */
 export async function inspectProjectImportant(options = {}) {
   const { projectRoot, config } = options;
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return invalidResult('unreadable');
+  }
   const target = path.join(projectRoot, PROJECT_IMPORTANT_FILENAME);
 
   let handle;

package/src/core/uninstall.js

@@ -89,6 +89,10 @@ async function planImportantBackup(projectRoot) {
   }
 
   plan.exhausted = true;
+  plan.backupWarnings.push(
+    `[UKit] Backup name space exhausted (${IMPORTANT_BACKUP_COLLISION_LIMIT + 1} candidates in use); `
+      + `${PROJECT_IMPORTANT_FILENAME} preserved in place without a backup. Free a backup slot and rerun \`ukit uninstall\`.`,
+  );
   return plan;
 }
 

package/templates/.claude/ukit/runtime/project-important.mjs

@@ -25,7 +25,7 @@
  */
 
 import fs from 'node:fs';
-import { open, stat as lstat } from 'node:fs/promises';
+import { open, lstat } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -129,6 +129,9 @@ function invalidResult(state) {
  */
 export async function inspectProjectImportant(options = {}) {
   const { projectRoot, config } = options;
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return invalidResult('unreadable');
+  }
   const target = path.join(projectRoot, PROJECT_IMPORTANT_FILENAME);
 
   let handle;