@kntic/kntic 0.6.0 → 0.7.0

package/README.md

@@ -1,93 +1,162 @@
-# Control
+# @kntic/kntic
 
+KNTIC CLI — bootstrap and manage KNTIC AI-orchestrated projects.
 
+## Requirements
 
-## Getting started
+- **Node.js** >= 18.0.0
+- **Docker** (with `docker compose` v2) — required for `kntic start` / `kntic stop`
+- **GNU screen** _(optional)_ — needed for `kntic start --screen`
+- **Git** _(optional)_ — enables auto-detection of `GIT_HOST`, `GIT_REPO_PATH`, and `GITLAB_TOKEN` during `kntic init`
 
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+## Installation
+
+```bash
+npm install -g @kntic/kntic
+```
+
+## Preflight Checks
 
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+When running `kntic init`, the CLI performs automatic preflight checks before downloading the bootstrap archive. All checks are **warnings only** — they never block execution.
 
-## Add your files
+| Check | Condition | Warning |
+|-------|-----------|---------|
+| **Platform** | `process.platform !== "linux"` | `⚠ Non-Linux detected (<platform>) — KNTIC is designed for Linux, other platforms may have issues` |
+| **Docker** | `docker` binary not found in `$PATH` | `⚠ docker not found — required for \`kntic start\`` |
+| **Screen** | `screen` binary not found in `$PATH` | `⚠ screen not found — optional, needed for \`kntic start --screen\`` |
 
-* [Create](https://docs.gitlab.com/user/project/repository/web_editor/#create-a-file) or [upload](https://docs.gitlab.com/user/project/repository/web_editor/#upload-a-file) files
-* [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:
+## Commands
 
+### `kntic usage`
+
+List all available sub-commands.
+
+```bash
+kntic usage
 ```
-cd existing_repo
-git remote add origin https://gitlab.kommune7.wien/kntic-ai/orchestrator/control.git
-git branch -M main
-git push -uf origin main
+
+---
+
+### `kntic init`
+
+Download and extract the KNTIC bootstrap template into the current directory. Sets up the `.kntic/` directory structure, `kntic.yml`, and `.kntic.env`.
+
+```bash
+kntic init [--quick | --interactive | -i]
 ```
 
-## Integrate with your tools
+| Option | Description |
+|--------|-------------|
+| `--quick` | **Default.** Non-interactive mode. Auto-detects `GIT_HOST` and `GIT_REPO_PATH` from the git origin remote (SSH and HTTPS). Extracts `GITLAB_TOKEN` from HTTPS credentials if available (`glpat-*` tokens). |
+| `--interactive`, `-i` | Walks through all `.kntic.env` values interactively, prompting for each variable. Auto-detected values are pre-filled as defaults. Skips `KNTIC_VERSION` and already-detected `GITLAB_TOKEN`. |
 
-* [Set up project integrations](https://gitlab.kommune7.wien/kntic-ai/orchestrator/control/-/settings/integrations)
+**What it does:**
 
-## Collaborate with your team
+1. Runs [preflight checks](#preflight-checks)
+2. Fetches version metadata from the bootstrap artifact URL
+3. Downloads and extracts the bootstrap archive (merges `.gitignore` if one already exists)
+4. Appends `KNTIC_VERSION=<version>` to `.kntic.env`
+5. Auto-detects git remote information and fills `GIT_HOST`, `GIT_REPO_PATH`, and `GITLAB_TOKEN`
+6. _(Interactive mode only)_ Prompts for remaining `.kntic.env` values
 
-* [Invite team members and collaborators](https://docs.gitlab.com/user/project/members/)
-* [Create a new merge request](https://docs.gitlab.com/user/project/merge_requests/creating_merge_requests/)
-* [Automatically close issues from merge requests](https://docs.gitlab.com/user/project/issues/managing_issues/#closing-issues-automatically)
-* [Enable merge request approvals](https://docs.gitlab.com/user/project/merge_requests/approvals/)
-* [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)
+---
 
-## Test and Deploy
+### `kntic start`
 
-Use the built-in continuous integration in GitLab.
+Build and start KNTIC services via Docker Compose.
 
-* [Get started with GitLab CI/CD](https://docs.gitlab.com/ci/quick_start/)
-* [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/user/application_security/sast/)
-* [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/topics/autodevops/requirements/)
-* [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/user/clusters/agent/)
-* [Set up protected environments](https://docs.gitlab.com/ci/environments/protected_environments/)
+```bash
+kntic start [--screen]
+```
 
-***
+| Option | Description |
+|--------|-------------|
+| `--screen` | Wrap the Docker Compose process in a GNU `screen` session. The session name is read from `KNTIC_PRJ_PREFIX` in `.kntic.env`, falling back to the current directory name. Skipped if already inside a screen session or if `screen` is not available. |
 
-# Editing this README
+Runs:
+```bash
+docker compose -f kntic.yml --env-file .kntic.env up --build
+```
 
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
+---
 
-## Suggestions for a good README
+### `kntic stop`
 
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+Stop KNTIC services via Docker Compose.
 
-## Name
-Choose a self-explaining name for your project.
+```bash
+kntic stop
+```
 
-## Description
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+Runs:
+```bash
+docker compose -f kntic.yml --env-file .kntic.env stop
+```
 
-## Badges
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+---
 
-## Visuals
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+### `kntic update`
 
-## Installation
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+Download the latest KNTIC bootstrap archive and update managed files.
+
+```bash
+kntic update [--lib-only] [--compose]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--lib-only` | Update only `.kntic/lib/` (skip ADRs, hooks, and weights). |
+| `--compose` | Also replace `kntic.yml` from the bootstrap template. Creates a backup at `kntic.yml.bak` before overwriting. |
+
+**Default update scope** (without `--lib-only`):
 
-## Usage
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
+| Path | Strategy |
+|------|----------|
+| `.kntic/lib/` | **Replaced** — cleared and re-extracted |
+| `.kntic/adrs/` | **Replaced** — cleared and re-extracted |
+| `.kntic/hooks/gia/internal/` | **Updated** — existing files overwritten, new files added, unlisted files preserved |
+| `.kntic/hooks/gia/specific/` | **Bootstrap only** — extracted only if the directory does not already exist (user customizations are never overwritten) |
+| `.kntic/gia/weights.json` | **Replaced** if present in the archive |
+| `.kntic.env` | **Merged** — new variables from the template are appended with their comments; existing values are never overwritten |
+| `KNTIC_VERSION` | Updated in `.kntic.env` to the latest version |
 
-## Support
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+## Environment Variables
 
-## Roadmap
-If you have ideas for releases in the future, it is a good idea to list them in the README.
+The `.kntic.env` file contains project configuration:
 
-## Contributing
-State if you are open to contributions and what your requirements are for accepting them.
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | API key for Anthropic (used by the orchestrator engine) |
+| `UID` | Host user ID for container user mapping |
+| `GID` | Host group ID for container user mapping |
+| `GITLAB_TOKEN` | GitLab personal access token (`glpat-*`) |
+| `GIT_HOST` | Git server hostname (auto-detected from origin remote) |
+| `GIT_REPO_PATH` | Repository path on the git server (auto-detected from origin remote) |
+| `KNTIC_VERSION` | Bootstrap version (set automatically by `kntic init` / `kntic update`) |
+| `KNTIC_PRJ_PREFIX` | Project prefix used for screen session naming in `kntic start --screen` |
 
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+## Services
 
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+Defined in `kntic.yml`:
 
-## Authors and acknowledgment
-Show your appreciation to those who have contributed to the project.
+| Service | Container | Image | Port |
+|---------|-----------|-------|------|
+| **Dashboard** | `control-dashboard` | `kntic/dashboard:latest` | `8002` |
+| **Orchestrator** | `control-engine` | `nexus.kommune7.wien/kntic/kntic-engine:latest` | — |
+
+Both services run as `${UID}:${GID}` (non-root) and use `.kntic.env` for environment configuration.
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs tests using the Node.js built-in test runner:
+```bash
+node --test src/**/*.test.js
+```
 
 ## License
-For open source projects, say how it is licensed.
 
-## Project status
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+[MIT](LICENSE)

package/package.json

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

package/src/commands/init.js

@@ -270,7 +270,46 @@ function interactiveEnvSetup(envPath) {
   });
 }
 
+/**
+ * Run preflight checks before downloading the bootstrap archive.
+ * All checks are warnings only — they never throw or exit.
+ * Returns an array of warning strings (empty if all checks pass).
+ */
+function preflightChecks() {
+  const warnings = [];
+
+  // 1. Linux platform check
+  if (process.platform !== "linux") {
+    warnings.push(
+      `⚠  Non-Linux detected (${process.platform}) — KNTIC is designed for Linux, other platforms may have issues`
+    );
+  }
+
+  // 2. docker binary check
+  try {
+    execSync("which docker", { stdio: "ignore" });
+  } catch {
+    warnings.push("⚠  docker not found — required for `kntic start`");
+  }
+
+  // 3. screen binary check
+  try {
+    execSync("which screen", { stdio: "ignore" });
+  } catch {
+    warnings.push("⚠  screen not found — optional, needed for `kntic start --screen`");
+  }
+
+  for (const w of warnings) {
+    console.log(w);
+  }
+
+  return warnings;
+}
+
 async function init(options = {}) {
+  // Run preflight checks before anything else
+  preflightChecks();
+
   // Resolve current version from the artifact metadata file
   const artifactFilename = await fetchText(BOOTSTRAP_ARTIFACT_URL);
   const version = extractVersion(artifactFilename);
@@ -317,3 +356,4 @@ module.exports.extractArchive = extractArchive;
 module.exports.extractVersion = extractVersion;
 module.exports.parseGitRemote = parseGitRemote;
 module.exports.fillEnvValues = fillEnvValues;
+module.exports.preflightChecks = preflightChecks;

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, parseGitRemote, fillEnvValues } = require("./init");
+const { extractArchive, extractVersion, parseGitRemote, fillEnvValues, preflightChecks } = require("./init");
 
 /**
  * Helper — create a tar.gz archive in `tmpDir` containing the given files.
@@ -28,6 +28,68 @@ function createTarball(tmpDir, files) {
   return tarball;
 }
 
+describe("preflightChecks", () => {
+  let originalPlatform;
+  let logMessages;
+  let originalLog;
+
+  beforeEach(() => {
+    originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+    originalLog = console.log;
+    logMessages = [];
+    console.log = (...args) => logMessages.push(args.join(" "));
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process, "platform", originalPlatform);
+    console.log = originalLog;
+  });
+
+  it("warns when platform is not linux", () => {
+    Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+    const warnings = preflightChecks();
+    const platformWarning = warnings.find((w) => w.includes("Non-Linux detected"));
+    assert.ok(platformWarning, "should warn about non-linux platform");
+    assert.ok(platformWarning.includes("darwin"));
+  });
+
+  it("does not warn about platform on linux", () => {
+    Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    const warnings = preflightChecks();
+    const platformWarning = warnings.find((w) => w.includes("Non-Linux detected"));
+    assert.equal(platformWarning, undefined, "should not warn on linux");
+  });
+
+  it("warns when docker is not found", () => {
+    // We test by checking the function handles missing binaries.
+    // On the test system docker may or may not exist, so we check the structure.
+    const warnings = preflightChecks();
+    // Each warning should be a string
+    for (const w of warnings) {
+      assert.equal(typeof w, "string");
+    }
+  });
+
+  it("each warning is independent (all checks run)", () => {
+    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+    const warnings = preflightChecks();
+    // Platform warning must be present regardless of binary check results
+    const platformWarning = warnings.find((w) => w.includes("Non-Linux detected"));
+    assert.ok(platformWarning, "platform warning must be present");
+    assert.ok(platformWarning.includes("win32"));
+    // All warnings are logged to console
+    assert.equal(logMessages.length, warnings.length, "all warnings must be logged");
+  });
+
+  it("prints warnings to console.log", () => {
+    Object.defineProperty(process, "platform", { value: "freebsd", configurable: true });
+    const warnings = preflightChecks();
+    // At least the platform warning should be logged
+    const platformLog = logMessages.find((m) => m.includes("Non-Linux detected"));
+    assert.ok(platformLog, "platform warning must be printed via console.log");
+  });
+});
+
 describe("extractArchive", () => {
   let tmpDir;
   let destDir;