@kntic/kntic 0.4.8 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kntic/kntic",
-  "version": "0.4.8",
+  "version": "0.6.0",
   "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

@@ -10,7 +10,8 @@ const subcommand = args[0];
 if (!subcommand || subcommand === "usage") {
   commands.usage();
 } else if (subcommand === "init") {
-  commands.init().catch((err) => {
+  const initOpts = { interactive: args.includes("--interactive") || args.includes("-i") };
+  commands.init(initOpts).catch((err) => {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
@@ -30,7 +31,10 @@ if (!subcommand || subcommand === "usage") {
     process.exit(1);
   }
 } else if (subcommand === "update") {
-  const updateOpts = { libOnly: args.includes("--lib-only") };
+  const updateOpts = {
+    libOnly: args.includes("--lib-only"),
+    compose: args.includes("--compose"),
+  };
   commands.update(updateOpts).catch((err) => {
     console.error(`Error: ${err.message}`);
     process.exit(1);

package/src/commands/init.js

@@ -6,6 +6,7 @@ const { execSync } = require("child_process");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const readline = require("readline");
 
 const BOOTSTRAP_ARTIFACT_URL =
   "https://minio.kommune7.wien/public/kntic-bootstrap-latest.artifact";
@@ -155,7 +156,121 @@ function extractArchive(tarball, destDir) {
   }
 }
 
-async function init() {
+/**
+ * Parse the git origin remote URL to extract host and repo path.
+ * Returns { host, repoPath } or null if not available.
+ */
+function parseGitRemote() {
+  try {
+    if (!fs.existsSync('.git')) return null;
+    const output = execSync('git remote -v', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    const fetchLine = output.split('\n').find(l => l.startsWith('origin') && l.includes('(fetch)'));
+    if (!fetchLine) return null;
+    const url = fetchLine.split(/\s+/)[1];
+    // SSH format: git@host:path
+    const sshMatch = url.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
+    if (sshMatch) return { host: sshMatch[1], repoPath: sshMatch[2] + '.git' };
+    // HTTPS with credentials: https://user:token@host/path.git
+    const httpsMatch = url.match(/^https?:\/\/(?:([^@]+)@)?([^/]+)\/(.+?)(?:\.git)?$/);
+    if (httpsMatch) {
+      const result = { host: httpsMatch[2], repoPath: httpsMatch[3] + '.git' };
+      // Extract glpat token from credentials (format: oauth2:glpat-xxx or just glpat-xxx)
+      if (httpsMatch[1]) {
+        const credParts = httpsMatch[1].split(':');
+        const token = credParts.find(p => p.startsWith('glpat-'));
+        if (token) result.gitlabToken = token;
+      }
+      return result;
+    }
+    return null;
+  } catch { return null; }
+}
+
+/**
+ * Read an env file, replace values for given keys (or append if missing),
+ * and write back.
+ */
+function fillEnvValues(envPath, values) {
+  let content = fs.readFileSync(envPath, 'utf8');
+  for (const [key, val] of Object.entries(values)) {
+    const regex = new RegExp(`^(${key}=).*$`, 'm');
+    if (regex.test(content)) {
+      content = content.replace(regex, `$1${val}`);
+    } else {
+      // Key missing from file — append it
+      content = content.trimEnd() + `\n${key}=${val}\n`;
+    }
+  }
+  fs.writeFileSync(envPath, content);
+}
+
+/**
+ * Interactively prompt the user for each env variable in the file.
+ * Skips KNTIC_VERSION. Shows current value as default.
+ */
+function interactiveEnvSetup(envPath) {
+  return new Promise((resolve) => {
+    const content = fs.readFileSync(envPath, 'utf8');
+    const lines = content.split('\n');
+
+    // Collect KEY=VALUE entries to prompt for
+    const entries = [];
+    for (let i = 0; i < lines.length; i++) {
+      const match = lines[i].match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (match) {
+        const key = match[1];
+        if (key === 'KNTIC_VERSION') continue;
+        // Also skip GITLAB_TOKEN if already auto-filled with a real token
+        if (key === 'GITLAB_TOKEN' && match[2].startsWith('glpat-')) continue;
+        entries.push({ index: i, key, value: match[2] });
+      }
+    }
+
+    if (entries.length === 0) {
+      resolve();
+      return;
+    }
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const updatedValues = {};
+    let idx = 0;
+
+    function promptNext() {
+      if (idx >= entries.length) {
+        rl.close();
+        // Write updated values back
+        const newLines = [...lines];
+        for (const entry of entries) {
+          const finalVal = updatedValues[entry.key] !== undefined
+            ? updatedValues[entry.key]
+            : entry.value;
+          newLines[entry.index] = `${entry.key}=${finalVal}`;
+        }
+        fs.writeFileSync(envPath, newLines.join('\n'));
+        resolve();
+        return;
+      }
+
+      const entry = entries[idx];
+      const displayVal = entry.value || '';
+      rl.question(`  ${entry.key} [${displayVal}]: `, (answer) => {
+        if (answer.length > 0) {
+          updatedValues[entry.key] = answer;
+        }
+        idx++;
+        promptNext();
+      });
+    }
+
+    promptNext();
+  });
+}
+
+async function init(options = {}) {
   // Resolve current version from the artifact metadata file
   const artifactFilename = await fetchText(BOOTSTRAP_ARTIFACT_URL);
   const version = extractVersion(artifactFilename);
@@ -174,9 +289,31 @@ async function init() {
   // Clean up
   fs.unlinkSync(tmpFile);
 
+  // Auto-detect git remote
+  const gitInfo = parseGitRemote();
+
+  // Auto-fill git values (both modes)
+  const autoValues = {};
+  if (gitInfo) {
+    autoValues.GIT_HOST = gitInfo.host;
+    autoValues.GIT_REPO_PATH = gitInfo.repoPath;
+    if (gitInfo.gitlabToken) {
+      autoValues.GITLAB_TOKEN = gitInfo.gitlabToken;
+    }
+  }
+  if (Object.keys(autoValues).length > 0) {
+    fillEnvValues('.kntic.env', autoValues);
+  }
+
+  if (options.interactive) {
+    await interactiveEnvSetup('.kntic.env');
+  }
+
   console.log("Done. KNTIC project bootstrapped successfully.");
 }
 
 module.exports = init;
 module.exports.extractArchive = extractArchive;
 module.exports.extractVersion = extractVersion;
+module.exports.parseGitRemote = parseGitRemote;
+module.exports.fillEnvValues = fillEnvValues;

package/src/commands/init.test.js

@@ -7,7 +7,7 @@ const path = require("path");
 const os = require("os");
 const { execSync } = require("child_process");
 
-const { extractArchive, extractVersion } = require("./init");
+const { extractArchive, extractVersion, parseGitRemote, fillEnvValues } = require("./init");
 
 /**
  * Helper — create a tar.gz archive in `tmpDir` containing the given files.
@@ -126,3 +126,136 @@ describe("extractVersion", () => {
     assert.throws(() => extractVersion("no-version-here.tar.gz"));
   });
 });
+
+describe("parseGitRemote", () => {
+  let tmpDir;
+  let originalCwd;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-git-test-"));
+    originalCwd = process.cwd();
+    process.chdir(tmpDir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("parses SSH remote", () => {
+    execSync("git init", { stdio: "pipe" });
+    execSync("git remote add origin git@gitlab.kommune7.wien:kntic-ai/orchestrator/control.git", { stdio: "pipe" });
+    const result = parseGitRemote();
+    assert.deepStrictEqual(result, {
+      host: "gitlab.kommune7.wien",
+      repoPath: "kntic-ai/orchestrator/control.git",
+    });
+  });
+
+  it("parses HTTPS remote", () => {
+    execSync("git init", { stdio: "pipe" });
+    execSync("git remote add origin https://github.com/org/repo.git", { stdio: "pipe" });
+    const result = parseGitRemote();
+    assert.deepStrictEqual(result, {
+      host: "github.com",
+      repoPath: "org/repo.git",
+    });
+  });
+
+  it("returns null when no .git dir", () => {
+    const result = parseGitRemote();
+    assert.equal(result, null);
+  });
+
+  it("returns null when no origin remote", () => {
+    execSync("git init", { stdio: "pipe" });
+    const result = parseGitRemote();
+    assert.equal(result, null);
+  });
+
+  it("parses HTTPS remote with embedded glpat token", () => {
+    execSync("git init", { stdio: "pipe" });
+    execSync("git remote add origin https://oauth2:glpat-abc123@gitlab.kommune7.wien/org/repo.git", { stdio: "pipe" });
+    const result = parseGitRemote();
+    assert.deepStrictEqual(result, {
+      host: "gitlab.kommune7.wien",
+      repoPath: "org/repo.git",
+      gitlabToken: "glpat-abc123",
+    });
+  });
+
+  it("HTTPS without credentials returns no gitlabToken", () => {
+    execSync("git init", { stdio: "pipe" });
+    execSync("git remote add origin https://github.com/org/repo.git", { stdio: "pipe" });
+    const result = parseGitRemote();
+    assert.equal(result.host, "github.com");
+    assert.equal(result.repoPath, "org/repo.git");
+    assert.equal(result.gitlabToken, undefined);
+  });
+
+  it("HTTPS with non-glpat credentials returns no gitlabToken", () => {
+    execSync("git init", { stdio: "pipe" });
+    execSync("git remote add origin https://user:password@github.com/org/repo.git", { stdio: "pipe" });
+    const result = parseGitRemote();
+    assert.equal(result.host, "github.com");
+    assert.equal(result.repoPath, "org/repo.git");
+    assert.equal(result.gitlabToken, undefined);
+  });
+});
+
+describe("fillEnvValues", () => {
+  let tmpDir;
+  let envPath;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-env-test-"));
+    envPath = path.join(tmpDir, ".kntic.env");
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("replaces existing key", () => {
+    fs.writeFileSync(envPath, "GIT_HOST=\nGIT_REPO_PATH=\n");
+    fillEnvValues(envPath, { GIT_HOST: "gitlab.kommune7.wien" });
+    const content = fs.readFileSync(envPath, "utf8");
+    assert.ok(content.includes("GIT_HOST=gitlab.kommune7.wien"));
+  });
+
+  it("appends missing key", () => {
+    fs.writeFileSync(envPath, "GIT_REPO_PATH=some/path.git\n");
+    fillEnvValues(envPath, { GIT_HOST: "gitlab.kommune7.wien" });
+    const content = fs.readFileSync(envPath, "utf8");
+    assert.ok(content.includes("GIT_HOST=gitlab.kommune7.wien"));
+    assert.ok(content.includes("GIT_REPO_PATH=some/path.git"));
+  });
+
+  it("preserves other lines and comments", () => {
+    fs.writeFileSync(envPath, "# This is a comment\nAPI_KEY=abc123\nGIT_HOST=\n# Another comment\n");
+    fillEnvValues(envPath, { GIT_HOST: "example.com" });
+    const content = fs.readFileSync(envPath, "utf8");
+    assert.ok(content.includes("# This is a comment"));
+    assert.ok(content.includes("API_KEY=abc123"));
+    assert.ok(content.includes("GIT_HOST=example.com"));
+    assert.ok(content.includes("# Another comment"));
+  });
+
+  it("handles multiple replacements", () => {
+    fs.writeFileSync(envPath, "GIT_HOST=\nGIT_REPO_PATH=\n");
+    fillEnvValues(envPath, {
+      GIT_HOST: "gitlab.kommune7.wien",
+      GIT_REPO_PATH: "kntic-ai/orchestrator/control.git",
+    });
+    const content = fs.readFileSync(envPath, "utf8");
+    assert.ok(content.includes("GIT_HOST=gitlab.kommune7.wien"));
+    assert.ok(content.includes("GIT_REPO_PATH=kntic-ai/orchestrator/control.git"));
+  });
+
+  it("fills GITLAB_TOKEN from git remote", () => {
+    fs.writeFileSync(envPath, "GITLAB_TOKEN=***\nGIT_HOST=\n");
+    fillEnvValues(envPath, { GITLAB_TOKEN: "glpat-abc123" });
+    const content = fs.readFileSync(envPath, "utf8");
+    assert.ok(content.includes("GITLAB_TOKEN=glpat-abc123"));
+  });
+});

package/src/commands/update.js

@@ -258,6 +258,153 @@ function extractUpdate(tarball, destDir) {
   }
 }
 
+/**
+ * Parse an env file into an ordered list of entries.
+ * Each entry is either:
+ *   { type: "comment", lines: ["# ...", "# ..."] }
+ *   { type: "variable", key: "KEY", line: "KEY=VALUE", commentLines: [] }
+ *   { type: "blank", lines: [""] }
+ *
+ * Comment lines immediately preceding a variable are attached to that variable.
+ */
+function parseEnvEntries(content) {
+  const rawLines = content.split("\n");
+  // Remove trailing empty string from final newline
+  if (rawLines.length > 0 && rawLines[rawLines.length - 1] === "") {
+    rawLines.pop();
+  }
+
+  const entries = [];
+  let pendingComments = [];
+
+  for (const line of rawLines) {
+    if (line === "" || (line.trim() === "" && !line.startsWith("#"))) {
+      // Blank line — if we're accumulating comments, treat blanks between
+      // comments as part of the comment block
+      pendingComments.push(line);
+    } else if (line.startsWith("#")) {
+      pendingComments.push(line);
+    } else {
+      // Variable line — KEY=VALUE (possibly with trailing comment)
+      const eqIdx = line.indexOf("=");
+      if (eqIdx !== -1) {
+        const key = line.substring(0, eqIdx).trim();
+        entries.push({
+          type: "variable",
+          key,
+          line,
+          commentLines: pendingComments.length > 0 ? [...pendingComments] : [],
+        });
+        pendingComments = [];
+      } else {
+        // Unknown line — treat as comment
+        pendingComments.push(line);
+      }
+    }
+  }
+
+  // Any trailing comments/blanks that didn't precede a variable
+  if (pendingComments.length > 0) {
+    entries.push({ type: "comment", lines: pendingComments });
+  }
+
+  return entries;
+}
+
+/**
+ * Extract the set of variable keys from parsed entries.
+ */
+function extractKeys(entries) {
+  const keys = new Set();
+  for (const entry of entries) {
+    if (entry.type === "variable") {
+      keys.add(entry.key);
+    }
+  }
+  return keys;
+}
+
+/**
+ * Merge new environment variables from a template .kntic.env into the user's .kntic.env.
+ *
+ * - Variables that exist in the user's file are never overwritten.
+ * - Variables in the template that are missing from the user's file are appended,
+ *   along with any preceding comment lines from the template.
+ *
+ * @param {string} templatePath – path to the template .kntic.env (from archive)
+ * @param {string} userEnvPath  – path to the user's .kntic.env
+ * @returns {string[]} list of newly added variable keys
+ */
+function mergeEnvFile(templatePath, userEnvPath) {
+  const templateContent = fs.readFileSync(templatePath, "utf8");
+  const templateEntries = parseEnvEntries(templateContent);
+
+  let userContent = "";
+  if (fs.existsSync(userEnvPath)) {
+    userContent = fs.readFileSync(userEnvPath, "utf8");
+  }
+
+  const userKeys = extractKeys(parseEnvEntries(userContent));
+  const newVars = [];
+
+  // Build the block to append
+  let appendBlock = "";
+
+  for (const entry of templateEntries) {
+    if (entry.type !== "variable") continue;
+    if (userKeys.has(entry.key)) continue;
+
+    // This is a new variable — append its comment lines + variable line
+    newVars.push(entry.key);
+
+    if (entry.commentLines.length > 0) {
+      appendBlock += entry.commentLines.join("\n") + "\n";
+    }
+    appendBlock += entry.line + "\n";
+  }
+
+  if (newVars.length === 0) {
+    console.log(".kntic.env is up to date.");
+    return newVars;
+  }
+
+  // Ensure user file ends with a newline before appending
+  let separator = "";
+  if (userContent.length > 0 && !userContent.endsWith("\n")) {
+    separator = "\n";
+  }
+  // Add blank line separator if user file doesn't end with a blank line
+  if (userContent.length > 0 && !userContent.endsWith("\n\n") && !(userContent.endsWith("\n") && userContent.length === 0)) {
+    separator += "\n";
+  }
+
+  fs.writeFileSync(userEnvPath, userContent + separator + appendBlock);
+
+  console.log(`Added new environment variables to .kntic.env: ${newVars.join(", ")}`);
+  return newVars;
+}
+
+/**
+ * Extract kntic.yml from the bootstrap archive, backing up any existing copy.
+ *
+ * @param {string} tarball  – path to the .tar.gz file
+ * @param {string} destDir  – target directory (usually ".")
+ */
+function extractCompose(tarball, destDir) {
+  const composePath = path.join(destDir, "kntic.yml");
+  // Backup existing
+  if (fs.existsSync(composePath)) {
+    fs.copyFileSync(composePath, composePath + ".bak");
+    console.log("Backing up kntic.yml → kntic.yml.bak");
+  }
+  // Extract from archive
+  execSync(
+    `tar xzf "${tarball}" -C "${destDir}" "./kntic.yml"`,
+    { stdio: "pipe" }
+  );
+  console.log("Updated kntic.yml from bootstrap template.");
+}
+
 async function update(options = {}) {
   const libOnly = options.libOnly || false;
 
@@ -278,6 +425,38 @@ async function update(options = {}) {
     extractUpdate(tmpFile, ".");
   }
 
+  // Merge new env variables from the archive's .kntic.env template
+  const timestamp = Date.now();
+  const tmpEnvTemplate = path.join(os.tmpdir(), `kntic-env-template-${timestamp}`);
+  try {
+    const tmpExtractDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-env-extract-"));
+    try {
+      execSync(`tar xzf "${tmpFile}" -C "${tmpExtractDir}" "./.kntic.env"`, { stdio: "pipe" });
+      const extractedEnv = path.join(tmpExtractDir, ".kntic.env");
+      if (fs.existsSync(extractedEnv)) {
+        fs.copyFileSync(extractedEnv, tmpEnvTemplate);
+        mergeEnvFile(tmpEnvTemplate, ".kntic.env");
+      } else {
+        console.log("No .kntic.env template in archive, skipping env merge.");
+      }
+    } catch (_) {
+      console.log("No .kntic.env template in archive, skipping env merge.");
+    } finally {
+      fs.rmSync(tmpExtractDir, { recursive: true, force: true });
+    }
+  } finally {
+    try { fs.unlinkSync(tmpEnvTemplate); } catch (_) {}
+  }
+
+  // Replace kntic.yml from archive if --compose flag is set
+  if (options.compose) {
+    try {
+      extractCompose(tmpFile, ".");
+    } catch (_) {
+      console.log("No kntic.yml in archive, skipping compose update.");
+    }
+  }
+
   // Update KNTIC_VERSION in .kntic.env
   updateEnvVersion(version);
 
@@ -295,6 +474,8 @@ async function update(options = {}) {
 module.exports = update;
 module.exports.extractLibOnly = extractLibOnly;
 module.exports.extractUpdate = extractUpdate;
+module.exports.extractCompose = extractCompose;
 module.exports.extractVersion = extractVersion;
 module.exports.clearDirectory = clearDirectory;
 module.exports.updateEnvVersion = updateEnvVersion;
+module.exports.mergeEnvFile = mergeEnvFile;

package/src/commands/update.test.js

@@ -7,7 +7,7 @@ const path = require("path");
 const os = require("os");
 const { execSync } = require("child_process");
 
-const { extractLibOnly, extractUpdate, extractVersion, clearDirectory, updateEnvVersion } = require("./update");
+const { extractLibOnly, extractUpdate, extractCompose, extractVersion, clearDirectory, updateEnvVersion, mergeEnvFile } = require("./update");
 
 /**
  * Helper — create a tar.gz archive in `tmpDir` containing the given files.
@@ -573,3 +573,274 @@ describe("extractVersion (update module)", () => {
     assert.throws(() => extractVersion("no-version-here.tar.gz"));
   });
 });
+
+describe("mergeEnvFile", () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-merge-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("appends new keys and their preceding comments from the template", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, [
+      "# Existing var",
+      "UID=1000",
+      "",
+      "# Project prefix used for naming",
+      "KNTIC_PRJ_PREFIX=myproject",
+      "",
+      "# UI port for the dashboard",
+      "KNTIC_UI_PORT=8080",
+      "",
+    ].join("\n"));
+
+    fs.writeFileSync(userPath, "UID=5000\n");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, ["KNTIC_PRJ_PREFIX", "KNTIC_UI_PORT"]);
+
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("UID=5000"), "existing var must be preserved");
+    assert.ok(content.includes("# Project prefix used for naming"), "comment for new var must be included");
+    assert.ok(content.includes("KNTIC_PRJ_PREFIX=myproject"), "new var must be appended");
+    assert.ok(content.includes("# UI port for the dashboard"), "comment for second new var must be included");
+    assert.ok(content.includes("KNTIC_UI_PORT=8080"), "second new var must be appended");
+  });
+
+  it("preserves user keys not in the template", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, "UID=1000\n");
+    fs.writeFileSync(userPath, "UID=5000\nMY_CUSTOM_VAR=hello\n");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, []);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("MY_CUSTOM_VAR=hello"), "user's extra key must be preserved");
+    assert.ok(content.includes("UID=5000"), "existing var must be preserved");
+  });
+
+  it("does not overwrite overlapping keys — user's value wins", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, "UID=1000\nGID=1000\n");
+    fs.writeFileSync(userPath, "UID=5000\nGID=5000\n");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, []);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("UID=5000"), "user's UID must be preserved");
+    assert.ok(content.includes("GID=5000"), "user's GID must be preserved");
+    assert.ok(!content.includes("UID=1000"), "template UID must not appear");
+    assert.ok(!content.includes("GID=1000"), "template GID must not appear");
+  });
+
+  it("writes all template entries when user file does not exist", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, [
+      "# User ID",
+      "UID=1000",
+      "# Group ID",
+      "GID=1000",
+      "",
+    ].join("\n"));
+
+    // user file does not exist
+    assert.ok(!fs.existsSync(userPath));
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, ["UID", "GID"]);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("# User ID"), "comment must be included");
+    assert.ok(content.includes("UID=1000"), "UID must be written");
+    assert.ok(content.includes("# Group ID"), "comment must be included");
+    assert.ok(content.includes("GID=1000"), "GID must be written");
+  });
+
+  it("includes comment lines that immediately precede a new key", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, [
+      "UID=1000",
+      "",
+      "# Branch strategy for the project",
+      "# Allowed values: trunk, gitflow",
+      "KNTIC_BRANCH_STRATEGY=trunk",
+      "",
+    ].join("\n"));
+
+    fs.writeFileSync(userPath, "UID=5000\n");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, ["KNTIC_BRANCH_STRATEGY"]);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("# Branch strategy for the project"), "first comment line must be included");
+    assert.ok(content.includes("# Allowed values: trunk, gitflow"), "second comment line must be included");
+    assert.ok(content.includes("KNTIC_BRANCH_STRATEGY=trunk"), "new var must be appended");
+  });
+
+  it("leaves file unchanged when there are no new keys", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, "UID=1000\nGID=1000\n");
+    fs.writeFileSync(userPath, "UID=5000\nGID=5000\n");
+
+    const originalContent = fs.readFileSync(userPath, "utf8");
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, []);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.equal(content, originalContent, "file must not be modified");
+  });
+
+  it("writes all template entries when user file is empty", () => {
+    const templatePath = path.join(tmpDir, "template.env");
+    const userPath = path.join(tmpDir, "user.env");
+
+    fs.writeFileSync(templatePath, "# Port\nPORT=3000\n");
+    fs.writeFileSync(userPath, "");
+
+    const added = mergeEnvFile(templatePath, userPath);
+
+    assert.deepEqual(added, ["PORT"]);
+    const content = fs.readFileSync(userPath, "utf8");
+    assert.ok(content.includes("# Port"), "comment must be included");
+    assert.ok(content.includes("PORT=3000"), "variable must be written");
+  });
+});
+
+describe("extractCompose", () => {
+  let tmpDir;
+  let destDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kntic-test-compose-"));
+    destDir = path.join(tmpDir, "dest");
+    fs.mkdirSync(destDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("extracts kntic.yml from archive", () => {
+    const composeContent = "services:\n  dashboard:\n    image: kntic/dashboard:latest\n";
+    const tarball = createTarball(tmpDir, {
+      "kntic.yml": composeContent,
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+    });
+
+    extractCompose(tarball, destDir);
+
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml"), "utf8"),
+      composeContent,
+      "kntic.yml content must match archive"
+    );
+  });
+
+  it("creates .bak backup of existing kntic.yml", () => {
+    const oldContent = "services:\n  dashboard:\n    image: old:v1\n";
+    const newContent = "services:\n  dashboard:\n    image: new:v2\n";
+    fs.writeFileSync(path.join(destDir, "kntic.yml"), oldContent);
+
+    const tarball = createTarball(tmpDir, {
+      "kntic.yml": newContent,
+    });
+
+    extractCompose(tarball, destDir);
+
+    // Backup must contain old content
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml.bak"), "utf8"),
+      oldContent,
+      "backup must contain previous content"
+    );
+    // New file must contain archive content
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml"), "utf8"),
+      newContent,
+      "kntic.yml must be replaced with archive content"
+    );
+  });
+
+  it("overwrites existing .bak file", () => {
+    const veryOldContent = "services:\n  old: true\n";
+    const oldContent = "services:\n  current: true\n";
+    const newContent = "services:\n  new: true\n";
+
+    fs.writeFileSync(path.join(destDir, "kntic.yml.bak"), veryOldContent);
+    fs.writeFileSync(path.join(destDir, "kntic.yml"), oldContent);
+
+    const tarball = createTarball(tmpDir, {
+      "kntic.yml": newContent,
+    });
+
+    extractCompose(tarball, destDir);
+
+    // .bak must now have the oldContent (not veryOldContent)
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml.bak"), "utf8"),
+      oldContent,
+      "backup must be overwritten with latest previous content"
+    );
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml"), "utf8"),
+      newContent,
+      "kntic.yml must contain archive content"
+    );
+  });
+
+  it("works when no existing kntic.yml on disk", () => {
+    const newContent = "services:\n  dashboard:\n    image: kntic/dashboard:latest\n";
+    const tarball = createTarball(tmpDir, {
+      "kntic.yml": newContent,
+    });
+
+    // No kntic.yml exists
+    assert.ok(!fs.existsSync(path.join(destDir, "kntic.yml")));
+
+    extractCompose(tarball, destDir);
+
+    // File must be extracted
+    assert.equal(
+      fs.readFileSync(path.join(destDir, "kntic.yml"), "utf8"),
+      newContent,
+      "kntic.yml must be extracted from archive"
+    );
+    // No backup should exist
+    assert.ok(
+      !fs.existsSync(path.join(destDir, "kntic.yml.bak")),
+      "no backup must be created when original did not exist"
+    );
+  });
+
+  it("throws when archive has no kntic.yml", () => {
+    const tarball = createTarball(tmpDir, {
+      ".kntic/lib/orchestrator.py": "# orchestrator\n",
+    });
+
+    assert.throws(
+      () => extractCompose(tarball, destDir),
+      "must throw when archive does not contain kntic.yml"
+    );
+  });
+});

package/src/commands/usage.js

@@ -6,11 +6,14 @@ function usage() {
   console.log("Available commands:\n");
   console.log("  usage    List all available sub-commands");
   console.log("  init     Download and extract the KNTIC bootstrap template into the current directory");
+  console.log("             --quick         Default mode — non-interactive, auto-detects git remote");
+  console.log("             --interactive   Walk through .kntic.env values interactively (-i)");
   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, .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("             --compose    Also replace kntic.yml from the bootstrap template (backs up to kntic.yml.bak)");
   console.log("");
 }