@ndevai/ndx2 0.2.3

package/README.md

@@ -0,0 +1,55 @@
+Docker-backed npm launcher for ndx2.
+
+| Goal | File |
+| --- | --- |
+| Understand purpose | [README.md](README.md) |
+| API reference | [docs/api.md](docs/api.md) |
+| Constraints | [docs/constraints.md](docs/constraints.md) |
+| Testing | [docs/testing.md](docs/testing.md) |
+
+# @ndevai/ndx2
+
+```sh
+npm install @ndevai/ndx2
+npx ndx2
+```
+
+or install globally:
+
+```sh
+npm install -g @ndevai/ndx2
+ndx2
+```
+
+Without a prior install:
+
+```sh
+npx @ndevai/ndx2
+```
+
+The CLI does not build the local repository. It writes a dedicated Docker
+Compose file under `~/.ndx2/docker-compose.yml`, records initialization state in
+`~/.ndx2/npm-install.json`, and starts GHCR images for the selected npm
+package version.
+
+## Commands
+
+`ndx2` initializes once, starts the Docker Compose stack, and prints the local
+Agent URL.
+
+`ndx2 uninstall` removes the npm initialization flag, the generated compose
+file, and the ndx2 Docker Compose stack. It does not delete the selected ndx
+root volume directory.
+
+## Release Contract
+
+For each npm package version, publish matching public GHCR tags first:
+
+* `ghcr.io/hikamaeng/ndx2-agent:<version>`
+
+The npm compose template pulls only this final agent image. `npm/Dockerfile`
+builds it as one distribution image and does not depend on local base-image
+archive files.
+
+Only after the GHCR tag is public, multi-architecture, and immutable should
+`@ndevai/ndx2@<version>` be published to npmjs.

package/bin/ndx2.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import net from "node:net";
+
+const stateDir = join(homedir(), ".ndx2");
+const statePath = join(stateDir, "npm-install.json");
+const composePath = join(stateDir, "docker-compose.yml");
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+const version = packageJson.version;
+const templatePath = join(packageRoot, "templates", "docker-compose.yml");
+
+const command = process.argv[2] ?? "start";
+
+if (command === "--version" || command === "-v" || command === "version") {
+  console.log(version);
+  process.exit(0);
+}
+
+if (command === "--help" || command === "-h" || command === "help") {
+  console.log(`ndx2 ${version}
+
+Usage:
+  ndx2              Initialize if needed, then start Docker containers.
+  ndx2 start        Same as ndx2.
+  ndx2 uninstall    Remove the npm initialization flag and ndx2 Docker stack.
+`);
+  process.exit(0);
+}
+
+if (command === "uninstall") {
+  uninstall();
+  process.exit(0);
+}
+
+if (command !== "start") {
+  console.error(`Unknown command: ${command}`);
+  console.error("Run `ndx2 --help` for usage.");
+  process.exit(1);
+}
+
+await start();
+
+async function start() {
+  ensureDockerReady();
+
+  if (existsSync(statePath)) {
+    const state = JSON.parse(readFileSync(statePath, "utf8"));
+    runCompose(["up", "-d"]);
+    printReady(state);
+    return;
+  }
+
+  const selectedRoot = await askNdxRoot();
+  const ndxRoot = resolve(selectedRoot);
+  const agentPort = await findPort(18082);
+
+  mkdirSync(join(ndxRoot, "pgvector"), { recursive: true });
+  mkdirSync(stateDir, { recursive: true });
+
+  const compose = readFileSync(templatePath, "utf8")
+    .replaceAll("__IMAGE_TAG__", version)
+    .replaceAll("__NDX_ROOT__", dockerPath(ndxRoot))
+    .replaceAll("__AGENT_WEB_HOST_PORT__", String(agentPort));
+
+  writeFileSync(composePath, compose);
+  const state = {
+    initializedAt: new Date().toISOString(),
+    version,
+    ndxRoot,
+    agentPort,
+    composePath
+  };
+  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+
+  runCompose(["up", "-d"]);
+  printReady(state);
+}
+
+async function askNdxRoot() {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(`ndx root volume path [${process.cwd()}]: `);
+    return answer.trim() === "" ? process.cwd() : answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+function ensureDockerReady() {
+  const docker = spawnSync("docker", ["--version"], { encoding: "utf8" });
+  if (docker.status !== 0) {
+    console.error("ndx2 runs only in a Docker-capable environment. Install Docker and try again.");
+    process.exit(1);
+  }
+
+  const info = spawnSync("docker", ["info"], { encoding: "utf8" });
+  if (info.status !== 0) {
+    console.error("Docker is installed, but the Docker daemon is not available. Start Docker and try again.");
+    process.exit(1);
+  }
+
+  const compose = spawnSync("docker", ["compose", "version"], { encoding: "utf8" });
+  if (compose.status !== 0) {
+    console.error("ndx2 requires Docker Compose v2 (`docker compose`). Install or enable it and try again.");
+    process.exit(1);
+  }
+}
+
+function runCompose(args) {
+  execFileSync("docker", ["compose", "-f", composePath, ...args], { stdio: "inherit" });
+}
+
+function uninstall() {
+  if (existsSync(composePath)) {
+    const docker = spawnSync("docker", ["compose", "version"], { encoding: "utf8" });
+    if (docker.status === 0) {
+      runCompose(["down", "--remove-orphans"]);
+    } else {
+      console.error("Docker Compose is not available, so only local ndx2 npm state will be removed.");
+    }
+  } else {
+    console.log("No ndx2 npm compose file was found.");
+  }
+
+  rmSync(statePath, { force: true });
+  rmSync(composePath, { force: true });
+  console.log("ndx2 npm initialization state and Docker stack have been removed.");
+}
+
+function printReady(state) {
+  console.log("");
+  console.log("ndx2 is running.");
+  console.log(`Agent: http://localhost:${state.agentPort}`);
+  console.log(`Root volume: ${state.ndxRoot}`);
+}
+
+function dockerPath(path) {
+  return process.platform === "win32" ? path.replaceAll("\\", "/") : path;
+}
+
+async function findPort(startAt) {
+  for (let port = startAt; port <= 18999; port += 1) {
+    if (await isPortFree(port)) {
+      return port;
+    }
+  }
+  throw new Error("No free ndx2 host port found in 18081-18999.");
+}
+
+function isPortFree(port) {
+  return new Promise((resolvePort) => {
+    const server = net.createServer();
+    server.once("error", () => resolvePort(false));
+    server.once("listening", () => {
+      server.close(() => resolvePort(true));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}

package/docs/api.md

@@ -0,0 +1,11 @@
+# API
+
+The package exposes one binary:
+
+| Command | Behavior |
+| --- | --- |
+| `ndx2` | Initialize if needed, then start the saved compose stack. |
+| `ndx2 start` | Same as `ndx2`. |
+| `ndx2 uninstall` | Run compose down, remove npm initialization state, and keep the selected ndx root volume directory. |
+| `ndx2 --help` | Print command help. |
+| `ndx2 --version` | Print the package version. |

package/docs/architecture.md

@@ -0,0 +1,12 @@
+# Architecture
+
+The CLI uses Node built-ins only. It checks Docker and Docker Compose v2, stores
+initialization state in `~/.ndx2/npm-install.json`, and controls
+`~/.ndx2/docker-compose.yml`.
+
+The compose stack uses one public GHCR runtime image:
+
+* `ghcr.io/hikamaeng/ndx2-agent:<version>`
+
+The npm user pulls that single final image. Repository release builds create it
+from `npm/Dockerfile`, not from local base-image archive files.

package/docs/constraints.md

@@ -0,0 +1,10 @@
+# Constraints
+
+The CLI must not build repository code. It only starts already-published public
+GHCR images.
+
+The package must not include npm tokens, GitHub tokens, generated compose state,
+or user volume data.
+
+The compose template must keep PostgreSQL internal to the compose network and
+must not expose a host PostgreSQL port.

package/docs/internals.md

@@ -0,0 +1,9 @@
+# Internals
+
+`bin/ndx2.js` resolves the image tag from `npm/package.json`.
+
+The generated compose file binds the selected ndx root to `/ndx` and stores
+PostgreSQL data under `<ndx-root>/pgvector`.
+
+GitHub Actions publish GHCR images before npm publication. The npm publish
+workflow expects the repository secret `NPM_TOKEN`.

package/docs/overview.md

@@ -0,0 +1,7 @@
+# Overview
+
+`@ndevai/ndx2` installs the `ndx2` command for end-user Docker launch.
+
+It is not the source build workflow. It writes npm-owned state under `~/.ndx2`,
+generates a compose file from `templates/docker-compose.yml`, and starts public
+GHCR images for the package version.

package/docs/testing.md

@@ -0,0 +1,14 @@
+# Testing
+
+Run static package checks from the repository root:
+
+```sh
+npm --prefix npm run check
+node --check npm/bin/ndx2.js
+```
+
+Run package contents verification from `npm/`:
+
+```sh
+npm pack --dry-run
+```

package/docs/usage.md

@@ -0,0 +1,18 @@
+# Usage
+
+Install in a project:
+
+```sh
+npm install @ndevai/ndx2
+npx ndx2
+```
+
+Install globally:
+
+```sh
+npm install -g @ndevai/ndx2
+ndx2
+```
+
+The first run asks for the ndx root volume path. Empty input selects the current
+directory.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ndevai/ndx2",
+  "version": "0.2.3",
+  "description": "Docker-backed installer and launcher for ndx2.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "ndx2": "bin/ndx2.js"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "templates",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "check": "node ./bin/ndx2.js --help"
+  }
+}

package/templates/docker-compose.yml

@@ -0,0 +1,20 @@
+name: ndx2
+
+services:
+  agent:
+    image: ghcr.io/hikamaeng/ndx2-agent:__IMAGE_TAG__
+    container_name: ndx2-agent
+    restart: unless-stopped
+    ports:
+      - "__AGENT_WEB_HOST_PORT__:18080"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      - type: bind
+        source: "__NDX_ROOT__"
+        target: /ndx
+      - type: bind
+        source: /var/run/docker.sock
+        target: /var/run/docker.sock
+    environment:
+      - NDX_ROOT=/ndx