@kntic/kntic 0.2.1 → 0.3.1

package/package.json

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

package/src/cli.js

@@ -21,6 +21,11 @@ if (!subcommand || subcommand === "usage") {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   }
+} else if (subcommand === "update") {
+  commands.update().catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else {
   console.error(`Unknown command: "${subcommand}"\n`);
   commands.usage();

package/src/commands/index.js

@@ -3,5 +3,6 @@
 const usage = require("./usage");
 const init = require("./init");
 const start = require("./start");
+const update = require("./update");
 
-module.exports = { usage, init, start };
+module.exports = { usage, init, start, update };

package/src/commands/init.js

@@ -111,6 +111,50 @@ function download(url, dest, maxRedirects = 5) {
   });
 }
 
+/**
+ * Extract a tarball into `destDir`, merging `.gitignore` instead of
+ * overwriting it.  If `.gitignore` already exists in `destDir`, the
+ * archive's version is appended (with a separator comment); otherwise
+ * the file is extracted normally alongside everything else.
+ *
+ * @param {string} tarball  – path to the .tar.gz file
+ * @param {string} destDir  – target directory (usually ".")
+ */
+function extractArchive(tarball, destDir) {
+  const gitignorePath = path.join(destDir, ".gitignore");
+  const gitignoreExists = fs.existsSync(gitignorePath);
+
+  if (gitignoreExists) {
+    // 1. Extract everything *except* .gitignore
+    execSync(
+      `tar xzf "${tarball}" -C "${destDir}" --exclude=".gitignore"`,
+      { stdio: "inherit" }
+    );
+
+    // 2. Read .gitignore content from the archive (may not exist in archive)
+    let archiveGitignore;
+    try {
+      archiveGitignore = execSync(
+        `tar xzf "${tarball}" --to-stdout .gitignore 2>/dev/null || tar xzf "${tarball}" --to-stdout "./.gitignore" 2>/dev/null`,
+        { encoding: "utf8" }
+      );
+    } catch {
+      // Archive does not contain a .gitignore — nothing to merge
+      archiveGitignore = null;
+    }
+
+    if (archiveGitignore && archiveGitignore.trim().length > 0) {
+      const existing = fs.readFileSync(gitignorePath, "utf8");
+      const separator = "\n# --- kntic bootstrap ---\n";
+      const merged = existing.trimEnd() + separator + archiveGitignore.trimEnd() + "\n";
+      fs.writeFileSync(gitignorePath, merged);
+    }
+  } else {
+    // No existing .gitignore — plain extraction
+    execSync(`tar xzf "${tarball}" -C "${destDir}"`, { stdio: "inherit" });
+  }
+}
+
 async function init() {
   // Resolve current version from the artifact metadata file
   const artifactFilename = await fetchText(BOOTSTRAP_ARTIFACT_URL);
@@ -122,7 +166,7 @@ async function init() {
   await download(BOOTSTRAP_URL, tmpFile);
 
   console.log("Extracting into current directory…");
-  execSync(`tar xzf "${tmpFile}" -C .`, { stdio: "inherit" });
+  extractArchive(tmpFile, ".");
 
   // Append version to .kntic.env (project root) — do not replace existing content
   fs.appendFileSync(".kntic.env", `KNTIC_VERSION=${version}\n`);
@@ -134,3 +178,5 @@ async function init() {
 }
 
 module.exports = init;
+module.exports.extractArchive = extractArchive;
+module.exports.extractVersion = extractVersion;

package/src/commands/init.test.js

@@ -0,0 +1,128 @@
+"use strict";
+
+const { describe, it, beforeEach, afterEach } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+
+const { extractArchive, extractVersion } = require("./init");
+
+/**
+ * Helper — create a tar.gz archive in `tmpDir` containing the given files.
+ * `files` is an object like { ".gitignore": "node_modules/\n", "README.md": "# Hi" }
+ */
+function createTarball(tmpDir, files) {
+  const contentDir = path.join(tmpDir, "_archive_content");
+  fs.mkdirSync(contentDir, { recursive: true });
+
+  for (const [name, content] of Object.entries(files)) {
+    const filePath = path.join(contentDir, name);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+
+  const tarball = path.join(tmpDir, "test.tar.gz");
+  execSync(`tar czf "${tarball}" -C "${contentDir}" .`, { stdio: "pipe" });
+  return tarball;
+}
+
+describe("extractArchive", () => {
+  let tmpDir;
+  let destDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-"));
+    destDir = path.join(tmpDir, "dest");
+    fs.mkdirSync(destDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("extracts all files when .gitignore does not exist", () => {
+    const tarball = createTarball(tmpDir, {
+      ".gitignore": "node_modules/\n",
+      "README.md": "# Hello\n",
+    });
+
+    extractArchive(tarball, destDir);
+
+    assert.equal(
+      fs.readFileSync(path.join(destDir, ".gitignore"), "utf8"),
+      "node_modules/\n"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "README.md"), "utf8"),
+      "# Hello\n"
+    );
+  });
+
+  it("appends archive .gitignore to existing one", () => {
+    // Pre-existing .gitignore
+    fs.writeFileSync(
+      path.join(destDir, ".gitignore"),
+      "*.log\n.env\n"
+    );
+
+    const tarball = createTarball(tmpDir, {
+      ".gitignore": "node_modules/\ndist/\n",
+      "README.md": "# Hello\n",
+    });
+
+    extractArchive(tarball, destDir);
+
+    const result = fs.readFileSync(path.join(destDir, ".gitignore"), "utf8");
+
+    // Original content must still be present
+    assert.ok(result.includes("*.log"), "original entry *.log must be preserved");
+    assert.ok(result.includes(".env"), "original entry .env must be preserved");
+
+    // Archive content must be appended
+    assert.ok(result.includes("node_modules/"), "archive entry node_modules/ must be appended");
+    assert.ok(result.includes("dist/"), "archive entry dist/ must be appended");
+
+    // Separator comment must be present
+    assert.ok(
+      result.includes("# --- kntic bootstrap ---"),
+      "separator comment must be present between original and appended content"
+    );
+
+    // Other files still extracted
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "README.md"), "utf8"),
+      "# Hello\n"
+    );
+  });
+
+  it("leaves existing .gitignore unchanged when archive has none", () => {
+    fs.writeFileSync(
+      path.join(destDir, ".gitignore"),
+      "*.log\n"
+    );
+
+    const tarball = createTarball(tmpDir, {
+      "README.md": "# Hello\n",
+    });
+
+    extractArchive(tarball, destDir);
+
+    assert.equal(
+      fs.readFileSync(path.join(destDir, ".gitignore"), "utf8"),
+      "*.log\n"
+    );
+  });
+});
+
+describe("extractVersion", () => {
+  it("parses version from artifact filename", () => {
+    assert.equal(extractVersion("kntic-bootstrap-v0.0.10.tar.gz"), "0.0.10");
+    assert.equal(extractVersion("kntic-bootstrap-v1.2.3.tar.gz"), "1.2.3");
+  });
+
+  it("throws on invalid filename", () => {
+    assert.throws(() => extractVersion("no-version-here.tar.gz"));
+  });
+});

package/src/commands/update.js

@@ -0,0 +1,212 @@
+"use strict";
+
+const https = require("https");
+const http = require("http");
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const BOOTSTRAP_ARTIFACT_URL =
+  "https://minio.kommune7.wien/public/kntic-bootstrap-latest.artifact";
+const BOOTSTRAP_URL =
+  "https://minio.kommune7.wien/public/kntic-bootstrap-latest.tar.gz";
+
+/**
+ * Fetch a small text resource from a URL (follows redirects).
+ * Returns the response body as a trimmed string.
+ */
+function fetchText(url, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (maxRedirects <= 0) {
+      return reject(new Error("Too many redirects"));
+    }
+
+    const client = url.startsWith("https") ? https : http;
+
+    client
+      .get(url, (res) => {
+        if ([301, 302, 303, 307, 308].includes(res.statusCode)) {
+          const location = res.headers.location;
+          if (!location) {
+            return reject(new Error("Redirect with no Location header"));
+          }
+          res.resume();
+          return resolve(fetchText(location, maxRedirects - 1));
+        }
+
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(
+            new Error(`Fetch failed — HTTP ${res.statusCode}`)
+          );
+        }
+
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8").trim()));
+        res.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+/**
+ * Follow redirects and download a URL to a local file path.
+ */
+function download(url, dest, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (maxRedirects <= 0) {
+      return reject(new Error("Too many redirects"));
+    }
+
+    const client = url.startsWith("https") ? https : http;
+
+    client
+      .get(url, (res) => {
+        if ([301, 302, 303, 307, 308].includes(res.statusCode)) {
+          const location = res.headers.location;
+          if (!location) {
+            return reject(new Error("Redirect with no Location header"));
+          }
+          res.resume();
+          return resolve(download(location, dest, maxRedirects - 1));
+        }
+
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(
+            new Error(`Download failed — HTTP ${res.statusCode}`)
+          );
+        }
+
+        const file = fs.createWriteStream(dest);
+        res.pipe(file);
+        file.on("finish", () => file.close(resolve));
+        file.on("error", (err) => {
+          fs.unlink(dest, () => {});
+          reject(err);
+        });
+      })
+      .on("error", (err) => {
+        fs.unlink(dest, () => {});
+        reject(err);
+      });
+  });
+}
+
+/**
+ * Extract semantic version from an artifact filename.
+ * E.g. "kntic-bootstrap-v0.0.10.tar.gz" → "0.0.10"
+ */
+function extractVersion(artifactFilename) {
+  const match = artifactFilename.match(/v(\d+\.\d+\.\d+)/);
+  if (!match) {
+    throw new Error(
+      `Unable to extract version from artifact filename: ${artifactFilename}`
+    );
+  }
+  return match[1];
+}
+
+/**
+ * Update or create the KNTIC_VERSION variable in a .kntic.env file.
+ * If the file exists and contains a KNTIC_VERSION line, that line is replaced.
+ * If the file exists but has no KNTIC_VERSION, it is appended.
+ * If the file does not exist, it is created with the variable.
+ *
+ * @param {string} version   – semantic version string (e.g. "0.0.10")
+ * @param {string} envPath   – path to .kntic.env (default: ".kntic.env")
+ */
+function updateEnvVersion(version, envPath = ".kntic.env") {
+  const line = `KNTIC_VERSION=${version}`;
+
+  if (!fs.existsSync(envPath)) {
+    fs.writeFileSync(envPath, line + "\n");
+    return;
+  }
+
+  const content = fs.readFileSync(envPath, "utf8");
+  const regex = /^KNTIC_VERSION=.*$/m;
+
+  if (regex.test(content)) {
+    const updated = content.replace(regex, line);
+    fs.writeFileSync(envPath, updated);
+  } else {
+    const separator = content.endsWith("\n") ? "" : "\n";
+    fs.writeFileSync(envPath, content + separator + line + "\n");
+  }
+}
+
+/**
+ * Recursively remove all contents of a directory (but not the directory itself).
+ */
+function clearDirectory(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    return;
+  }
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      fs.rmSync(fullPath, { recursive: true, force: true });
+    } else {
+      fs.unlinkSync(fullPath);
+    }
+  }
+}
+
+/**
+ * Extract only .kntic/lib/** from a tarball into the destination directory.
+ * Clears the existing .kntic/lib directory first, then extracts fresh content.
+ *
+ * @param {string} tarball  – path to the .tar.gz file
+ * @param {string} destDir  – target directory (usually ".")
+ */
+function extractLibOnly(tarball, destDir) {
+  const libDir = path.join(destDir, ".kntic", "lib");
+
+  // Ensure the target directory exists
+  fs.mkdirSync(libDir, { recursive: true });
+
+  // Clear existing lib contents
+  clearDirectory(libDir);
+
+  // Extract only .kntic/lib/ from the archive.
+  // Tar entries are prefixed with ./ (created with `tar -C dir .`), so we
+  // pass the exact member path `./.kntic/lib/` which matches the directory
+  // and all its descendants.
+  execSync(
+    `tar xzf "${tarball}" -C "${destDir}" "./.kntic/lib/"`,
+    { stdio: "pipe" }
+  );
+}
+
+async function update() {
+  // Resolve current version from the artifact metadata file
+  const artifactFilename = await fetchText(BOOTSTRAP_ARTIFACT_URL);
+  const version = extractVersion(artifactFilename);
+
+  const tmpFile = path.join(os.tmpdir(), `kntic-bootstrap-${Date.now()}.tar.gz`);
+
+  console.log(`Downloading KNTIC bootstrap archive… (v${version})`);
+  await download(BOOTSTRAP_URL, tmpFile);
+
+  console.log("Updating .kntic/lib …");
+  extractLibOnly(tmpFile, ".");
+
+  // Update KNTIC_VERSION in .kntic.env
+  updateEnvVersion(version);
+
+  // Clean up
+  fs.unlinkSync(tmpFile);
+
+  console.log(`@kntic/kntic@${version}`);
+  console.log("Done. .kntic/lib updated successfully.");
+}
+
+module.exports = update;
+module.exports.extractLibOnly = extractLibOnly;
+module.exports.extractVersion = extractVersion;
+module.exports.clearDirectory = clearDirectory;
+module.exports.updateEnvVersion = updateEnvVersion;

package/src/commands/update.test.js

@@ -0,0 +1,271 @@
+"use strict";
+
+const { describe, it, beforeEach, afterEach } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+
+const { extractLibOnly, extractVersion, clearDirectory, updateEnvVersion } = require("./update");
+
+/**
+ * Helper — create a tar.gz archive in `tmpDir` containing the given files.
+ * `files` is an object like { ".kntic/lib/foo.py": "content", "README.md": "# Hi" }
+ */
+function createTarball(tmpDir, files) {
+  const contentDir = path.join(tmpDir, "_archive_content");
+  fs.mkdirSync(contentDir, { recursive: true });
+
+  for (const [name, content] of Object.entries(files)) {
+    const filePath = path.join(contentDir, name);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+
+  const tarball = path.join(tmpDir, "test.tar.gz");
+  execSync(`tar czf "${tarball}" -C "${contentDir}" .`, { stdio: "pipe" });
+  return tarball;
+}
+
+describe("clearDirectory", () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-clear-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("removes all files and subdirectories but keeps the directory itself", () => {
+    const dir = path.join(tmpDir, "target");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "a.txt"), "hello");
+    fs.mkdirSync(path.join(dir, "sub"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "sub", "b.txt"), "world");
+
+    clearDirectory(dir);
+
+    assert.ok(fs.existsSync(dir), "directory itself must still exist");
+    assert.deepEqual(fs.readdirSync(dir), [], "directory must be empty");
+  });
+
+  it("does nothing if directory does not exist", () => {
+    // Should not throw
+    clearDirectory(path.join(tmpDir, "nonexistent"));
+  });
+});
+
+describe("extractLibOnly", () => {
+  let tmpDir;
+  let destDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-update-"));
+    destDir = path.join(tmpDir, "dest");
+    fs.mkdirSync(destDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("extracts only .kntic/lib files from the archive", () => {
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+      ".kntic/lib/skills/validator.py": "# validator\n",
+      ".kntic/MEMORY.MD": "# Memory\n",
+      ".kntic/adrs/ADR-001.md": "# ADR\n",
+      "README.md": "# Hello\n",
+      "package.json": '{"name":"test"}\n',
+    });
+
+    extractLibOnly(tarball, destDir);
+
+    // .kntic/lib files must be extracted
+    assert.equal(
+      fs.readFileSync(path.join(destDir, ".kntic", "lib", "orchestrator.py"), "utf8"),
+      "# orchestrator\n"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(destDir, ".kntic", "lib", "skills", "validator.py"), "utf8"),
+      "# validator\n"
+    );
+
+    // Files outside .kntic/lib must NOT be extracted
+    assert.ok(
+      !fs.existsSync(path.join(destDir, ".kntic", "MEMORY.MD")),
+      "MEMORY.MD must not be extracted"
+    );
+    assert.ok(
+      !fs.existsSync(path.join(destDir, ".kntic", "adrs", "ADR-001.md")),
+      "ADR files must not be extracted"
+    );
+    assert.ok(
+      !fs.existsSync(path.join(destDir, "README.md")),
+      "README.md must not be extracted"
+    );
+    assert.ok(
+      !fs.existsSync(path.join(destDir, "package.json")),
+      "package.json must not be extracted"
+    );
+  });
+
+  it("replaces existing .kntic/lib content", () => {
+    // Pre-existing lib content
+    const libDir = path.join(destDir, ".kntic", "lib");
+    fs.mkdirSync(libDir, { recursive: true });
+    fs.writeFileSync(path.join(libDir, "old_file.py"), "# old\n");
+    fs.writeFileSync(path.join(libDir, "orchestrator.py"), "# old orchestrator\n");
+
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# new orchestrator\n",
+      ".kntic/lib/new_file.py": "# new\n",
+    });
+
+    extractLibOnly(tarball, destDir);
+
+    // Old file must be gone
+    assert.ok(
+      !fs.existsSync(path.join(libDir, "old_file.py")),
+      "old_file.py must be removed"
+    );
+
+    // New files must be present
+    assert.equal(
+      fs.readFileSync(path.join(libDir, "orchestrator.py"), "utf8"),
+      "# new orchestrator\n"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(libDir, "new_file.py"), "utf8"),
+      "# new\n"
+    );
+  });
+
+  it("preserves files outside .kntic/lib that already exist on disk", () => {
+    // Pre-existing files outside lib
+    const knticDir = path.join(destDir, ".kntic");
+    fs.mkdirSync(knticDir, { recursive: true });
+    fs.writeFileSync(path.join(knticDir, "MEMORY.MD"), "# My memory\n");
+    fs.writeFileSync(path.join(destDir, "README.md"), "# My readme\n");
+
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+      ".kntic/MEMORY.MD": "# Archive memory\n",
+      "README.md": "# Archive readme\n",
+    });
+
+    extractLibOnly(tarball, destDir);
+
+    // Existing files outside lib must be untouched
+    assert.equal(
+      fs.readFileSync(path.join(knticDir, "MEMORY.MD"), "utf8"),
+      "# My memory\n",
+      "MEMORY.MD must not be overwritten"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "README.md"), "utf8"),
+      "# My readme\n",
+      "README.md must not be overwritten"
+    );
+
+    // Lib files must be extracted
+    assert.equal(
+      fs.readFileSync(path.join(knticDir, "lib", "orchestrator.py"), "utf8"),
+      "# orchestrator\n"
+    );
+  });
+
+  it("handles nested subdirectories in .kntic/lib", () => {
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/skills/validator.py": "# validator\n",
+      ".kntic/lib/skills/navigation.py": "# navigation\n",
+      ".kntic/lib/agent_runner.py": "# agent_runner\n",
+    });
+
+    extractLibOnly(tarball, destDir);
+
+    assert.equal(
+      fs.readFileSync(path.join(destDir, ".kntic", "lib", "skills", "validator.py"), "utf8"),
+      "# validator\n"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(destDir, ".kntic", "lib", "skills", "navigation.py"), "utf8"),
+      "# navigation\n"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(destDir, ".kntic", "lib", "agent_runner.py"), "utf8"),
+      "# agent_runner\n"
+    );
+  });
+});
+
+describe("updateEnvVersion", () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-env-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates the file with KNTIC_VERSION if it does not exist", () => {
+    const envPath = path.join(tmpDir, ".kntic.env");
+    updateEnvVersion("1.2.3", envPath);
+
+    assert.equal(fs.readFileSync(envPath, "utf8"), "KNTIC_VERSION=1.2.3\n");
+  });
+
+  it("appends KNTIC_VERSION if file exists but variable is missing", () => {
+    const envPath = path.join(tmpDir, ".kntic.env");
+    fs.writeFileSync(envPath, "UID=1000\nGID=1000\n");
+
+    updateEnvVersion("0.0.10", envPath);
+
+    const content = fs.readFileSync(envPath, "utf8");
+    assert.ok(content.includes("UID=1000"), "existing content must be preserved");
+    assert.ok(content.includes("GID=1000"), "existing content must be preserved");
+    assert.ok(content.includes("KNTIC_VERSION=0.0.10"), "version must be appended");
+  });
+
+  it("replaces existing KNTIC_VERSION in-place", () => {
+    const envPath = path.join(tmpDir, ".kntic.env");
+    fs.writeFileSync(envPath, "UID=1000\nKNTIC_VERSION=0.0.1\nGID=1000\n");
+
+    updateEnvVersion("2.0.0", envPath);
+
+    const content = fs.readFileSync(envPath, "utf8");
+    assert.ok(content.includes("KNTIC_VERSION=2.0.0"), "version must be updated");
+    assert.ok(!content.includes("KNTIC_VERSION=0.0.1"), "old version must be gone");
+    assert.ok(content.includes("UID=1000"), "other vars must be preserved");
+    assert.ok(content.includes("GID=1000"), "other vars must be preserved");
+  });
+
+  it("handles file without trailing newline when appending", () => {
+    const envPath = path.join(tmpDir, ".kntic.env");
+    fs.writeFileSync(envPath, "UID=1000");
+
+    updateEnvVersion("0.1.0", envPath);
+
+    const content = fs.readFileSync(envPath, "utf8");
+    assert.ok(content.includes("UID=1000"), "existing content must be preserved");
+    assert.ok(content.includes("KNTIC_VERSION=0.1.0"), "version must be appended");
+    // Ensure they're on separate lines
+    assert.ok(content.includes("UID=1000\nKNTIC_VERSION=0.1.0"), "must be on separate lines");
+  });
+});
+
+describe("extractVersion (update module)", () => {
+  it("parses version from artifact filename", () => {
+    assert.equal(extractVersion("kntic-bootstrap-v0.0.10.tar.gz"), "0.0.10");
+    assert.equal(extractVersion("kntic-bootstrap-v1.2.3.tar.gz"), "1.2.3");
+  });
+
+  it("throws on invalid filename", () => {
+    assert.throws(() => extractVersion("no-version-here.tar.gz"));
+  });
+});

package/src/commands/usage.js

@@ -7,6 +7,7 @@ function usage() {
   console.log("  usage    List all available sub-commands");
   console.log("  init     Download and extract the KNTIC bootstrap template into the current directory");
   console.log("  start    Build and start KNTIC services via docker compose (uses kntic.yml + .kntic.env)");
+  console.log("  update   Download the latest KNTIC bootstrap and update .kntic/lib only");
   console.log("");
 }