@kntic/kntic 0.4.7 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kntic/kntic",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "author": "Thomas Robak <contact@kntic.ai> (https://kntic.ai)",
   "description": "KNTIC CLI — bootstrap and manage KNTIC projects",
   "main": "src/index.js",

package/src/commands/update.js

@@ -189,6 +189,8 @@ function extractLibOnly(tarball, destDir) {
  * - .kntic/lib and .kntic/adrs are **replaced** (cleared first, then extracted).
  * - .kntic/hooks/gia/internal is **updated** (existing files are overwritten or new files
  *   added, but files not present in the archive are preserved).
+ * - .kntic/hooks/gia/specific is **extracted only if the directory does not already exist**
+ *   (one-time bootstrap; user customizations are never overwritten).
  * - .kntic/gia/weights.json is **replaced** if present in the archive.
  *
  * @param {string} tarball  – path to the .tar.gz file
@@ -198,6 +200,7 @@ function extractUpdate(tarball, destDir) {
   const libDir = path.join(destDir, ".kntic", "lib");
   const adrsDir = path.join(destDir, ".kntic", "adrs");
   const giaInternalDir = path.join(destDir, ".kntic", "hooks", "gia", "internal");
+  const giaSpecificDir = path.join(destDir, ".kntic", "hooks", "gia", "specific");
   const giaDir = path.join(destDir, ".kntic", "gia");
 
   // Ensure target directories exist
@@ -211,6 +214,7 @@ function extractUpdate(tarball, destDir) {
   clearDirectory(adrsDir);
 
   // Note: gia/internal hooks are NOT cleared — update semantics (overwrite/add, preserve others)
+  // Note: gia/specific hooks are only extracted if the directory does NOT already exist
   // Note: gia is NOT cleared — only weights.json is replaced
 
   // Extract .kntic/lib/ and .kntic/adrs/ (guaranteed to be in the archive)
@@ -229,6 +233,20 @@ function extractUpdate(tarball, destDir) {
     // No .kntic/hooks/gia/internal/ in the archive — that's fine
   }
 
+  // Extract .kntic/hooks/gia/specific/ only if it does not already exist on disk.
+  // This is a one-time bootstrap — once the user has specific hooks, they are never
+  // overwritten by update.
+  if (!fs.existsSync(giaSpecificDir)) {
+    try {
+      execSync(
+        `tar xzf "${tarball}" -C "${destDir}" "./.kntic/hooks/gia/specific/"`,
+        { stdio: "pipe" }
+      );
+    } catch (_) {
+      // No .kntic/hooks/gia/specific/ in the archive — that's fine
+    }
+  }
+
   // Extract .kntic/gia/weights.json separately — archive may not contain it
   try {
     execSync(
@@ -256,7 +274,7 @@ async function update(options = {}) {
     console.log("Updating .kntic/lib …");
     extractLibOnly(tmpFile, ".");
   } else {
-    console.log("Updating .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, and .kntic/gia/weights.json …");
+    console.log("Updating .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), and .kntic/gia/weights.json …");
     extractUpdate(tmpFile, ".");
   }
 
@@ -270,7 +288,7 @@ async function update(options = {}) {
   if (libOnly) {
     console.log("Done. .kntic/lib updated successfully.");
   } else {
-    console.log("Done. .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, and .kntic/gia/weights.json updated successfully.");
+    console.log("Done. .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), and .kntic/gia/weights.json updated successfully.");
   }
 }
 

package/src/commands/update.test.js

@@ -408,6 +408,75 @@ describe("extractUpdate", () => {
     );
   });
 
+  it("extracts .kntic/hooks/gia/specific when the directory does not exist", () => {
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+      ".kntic/adrs/ADR-001.md": "# ADR 001\n",
+      ".kntic/hooks/gia/specific/my-hook.sh": "#!/bin/sh\necho specific\n",
+      ".kntic/hooks/gia/specific/another.sh": "#!/bin/sh\necho another\n",
+    });
+
+    // specific dir does not exist yet
+    const specificDir = path.join(destDir, ".kntic", "hooks", "gia", "specific");
+    assert.ok(!fs.existsSync(specificDir), "specific dir must not exist before extraction");
+
+    extractUpdate(tarball, destDir);
+
+    // specific hooks must be extracted
+    assert.equal(
+      fs.readFileSync(path.join(specificDir, "my-hook.sh"), "utf8"),
+      "#!/bin/sh\necho specific\n"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(specificDir, "another.sh"), "utf8"),
+      "#!/bin/sh\necho another\n"
+    );
+  });
+
+  it("does NOT overwrite .kntic/hooks/gia/specific when the directory already exists", () => {
+    const specificDir = path.join(destDir, ".kntic", "hooks", "gia", "specific");
+    fs.mkdirSync(specificDir, { recursive: true });
+    fs.writeFileSync(path.join(specificDir, "custom.sh"), "#!/bin/sh\necho custom\n");
+
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+      ".kntic/adrs/ADR-001.md": "# ADR 001\n",
+      ".kntic/hooks/gia/specific/my-hook.sh": "#!/bin/sh\necho from-archive\n",
+    });
+
+    extractUpdate(tarball, destDir);
+
+    // User's custom hook must be preserved
+    assert.equal(
+      fs.readFileSync(path.join(specificDir, "custom.sh"), "utf8"),
+      "#!/bin/sh\necho custom\n",
+      "user's custom specific hook must be preserved"
+    );
+
+    // Archive's specific hook must NOT be extracted
+    assert.ok(
+      !fs.existsSync(path.join(specificDir, "my-hook.sh")),
+      "archive specific hook must not be extracted when directory already exists"
+    );
+  });
+
+  it("works when archive has no .kntic/hooks/gia/specific and directory does not exist", () => {
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+      ".kntic/adrs/ADR-001.md": "# ADR 001\n",
+    });
+
+    // Should not throw
+    extractUpdate(tarball, destDir);
+
+    // specific dir should not be created
+    const specificDir = path.join(destDir, ".kntic", "hooks", "gia", "specific");
+    assert.ok(
+      !fs.existsSync(specificDir),
+      "specific dir must not be created when not in archive"
+    );
+  });
+
   it("preserves files outside .kntic/lib, .kntic/adrs, and .kntic/hooks/gia/internal", () => {
     const knticDir = path.join(destDir, ".kntic");
     fs.mkdirSync(knticDir, { recursive: true });

package/src/commands/usage.js

@@ -9,8 +9,8 @@ function usage() {
   console.log("  start    Build and start KNTIC services via docker compose (uses kntic.yml + .kntic.env)");
   console.log("             --screen   Run inside a GNU screen session");
   console.log("  stop     Stop KNTIC services via docker compose");
-  console.log("  update   Download the latest KNTIC bootstrap and update .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, and .kntic/gia/weights.json");
-  console.log("             --lib-only   Update only .kntic/lib (skip .kntic/adrs, .kntic/hooks/gia/internal, and .kntic/gia/weights.json)");
+  console.log("  update   Download the latest KNTIC bootstrap and update .kntic/lib, .kntic/adrs, .kntic/hooks/gia/internal, .kntic/hooks/gia/specific (if new), and .kntic/gia/weights.json");
+  console.log("             --lib-only   Update only .kntic/lib (skip adrs, hooks, and weights)");
   console.log("");
 }