@ngockhoale/ukit 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to UKit are documented here.
 
 ## Unreleased
 
+## 1.3.1 - 2026-05-06
+
+### Fixed
+
+- Fixed `ukit install` failing with `ENOENT` when a published/global package is missing optional `templates/.gitignore`; install now uses a built-in fallback.
+
+### Tests
+
+- Added a regression test for package artifacts without `templates/.gitignore`.
+
 ## 1.3.0 - 2026-05-06
 
 ### Added

package/README.md

@@ -68,7 +68,7 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 - `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
 - `docs/` — PROJECT / MEMORY / STATUS / TASKS / WORKLOG baseline
 
-## UKit v1.3.0 Runtime
+## UKit v1.3.1 Runtime
 
 UKit now installs a hidden shared local runtime at `.ukit/` for production-oriented state that should survive across agent sessions:
 
@@ -86,7 +86,7 @@ When long sessions approach the compact threshold, UKit now uses a conservative
 - compact only safe-zone history/noise
 - preserve active task, rules, decisions, and current code focus
 
-UKit v1.3.0 keeps the same shared runtime contract while adding Safe Patch Protocol guardrails and the local AI task queue alongside living project status routing:
+UKit v1.3.1 keeps the same shared runtime contract while adding Safe Patch Protocol guardrails and the local AI task queue alongside living project status routing:
 
 - install globally with `npm install -g @ngockhoale/ukit`
 - keep using the exact same human workflow inside projects: `ukit install`
@@ -98,7 +98,7 @@ UKit v1.3.0 keeps the same shared runtime contract while adding Safe Patch Proto
 - keep concrete debug/implementation/review prompts primary, so project status never replaces source/index-first task work
 - quietly guard risky AI edits with Safe Patch Protocol: stale/ambiguous specs are blocked, shared-risk whole-file writes are discouraged, and internal helpers preserve UTF-8 BOM/no-BOM plus LF/CRLF for multilingual text
 
-UKit v1.3.0 also keeps the fast path improvements from the recent runtime releases:
+UKit v1.3.1 also keeps the fast path improvements from the recent runtime releases:
 
 - Vietnamese prompts now normalize more effectively for English-heavy code symbols and paths
 - localized simple direct-target lanes skip extra previous-context / recent-output work when it would not change the next action

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/core/buildPlan.js

@@ -25,6 +25,14 @@ const BINARY_TEMPLATE_EXTENSIONS = new Set([
   '.pdf',
 ]);
 
+const FALLBACK_ROOT_GITIGNORE_TEMPLATE = 'node_modules/\n.env\n*.log\n.DS_Store\n';
+
+function isRootGitignoreItem(item) {
+  return item?.id === 'gitignore-root'
+    && item?.sourceTemplate === '.gitignore'
+    && item?.targetPath === '.gitignore';
+}
+
 function safeResolve(basePath, relativePath) {
   const resolvedPath = path.resolve(basePath, relativePath);
   const relativeToBase = path.relative(basePath, resolvedPath);
@@ -118,7 +126,27 @@ export async function buildInstallPlan({
       });
     } else {
       const sourcePath = safeResolve(templatesRoot, item.sourceTemplate);
-      const stat = await fs.stat(sourcePath);
+      let stat;
+      try {
+        stat = await fs.stat(sourcePath);
+      } catch (error) {
+        if (error?.code === 'ENOENT' && isRootGitignoreItem(item)) {
+          const targetPath = safeResolve(projectRoot, item.targetPath);
+          explicitTargetPaths.add(targetPath);
+          planEntries.push({
+            id: item.id,
+            type: item.type,
+            sourcePath: null,
+            targetPath,
+            mergeStrategy: item.mergeStrategy,
+            renderedContent: FALLBACK_ROOT_GITIGNORE_TEMPLATE,
+            requires: item.requires ?? [],
+            mode: 0o644,
+          });
+          continue;
+        }
+        throw error;
+      }
       if (stat.isDirectory()) {
         const nestedFiles = await walkDirectory(sourcePath);
         const nestedStats = await Promise.all(nestedFiles.map((filePath) => fs.stat(filePath)));

package/src/core/runtimeConfig.js

@@ -49,7 +49,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.3.0',
+    version: '1.3.1',
     agent: 'claude-code',
     compact: {
       enabled: true,

package/templates/.codex/README.md

@@ -12,7 +12,7 @@ Auto-generated by UKit for OpenAI Codex.
 - Do not make end users memorize skill names, helper scripts, or routing internals unless they are debugging UKit itself.
 - **Treat helper commands as internal orchestration. Do not ask end users to run them.**
 
-## UKit v1.3.0 Shared Runtime
+## UKit v1.3.1 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, validation, and Safe Patch guardrail toggles.

package/templates/AGENTS.md

@@ -43,7 +43,7 @@
 - If a concrete verification lane is needed, prefer `node .claude/ukit/index/verify-context.mjs ...`.
 - These helper/index commands are internal orchestration. Run them yourself when needed; never turn them into required end-user workflow.
 
-## UKit v1.3.0 Shared Runtime
+## UKit v1.3.1 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.

package/templates/CLAUDE.md

@@ -42,7 +42,7 @@
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
 
-## UKit v1.3.0 Shared Runtime
+## UKit v1.3.1 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.3.0 features.
+This folder stores shared UKit runtime state for v1.3.1 features.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.0",
+  "version": "1.3.1",
   "agent": "claude-code",
   "compact": {
     "enabled": true,