alexandr 0.0.1 → 0.1.0

package/src/completion.js

@@ -0,0 +1,122 @@
+// The canonical command surface (single source of truth for both `--help` and
+// shell completion) plus the completion-script generators for bash · zsh · fish.
+//
+// `cli.js` builds its help listing and dispatch from COMMANDS; this module never
+// imports cli.js, so there's no import cycle.
+
+import { fail } from "./util.js";
+import { EXIT } from "./exit.js";
+
+// One row per command: { name, usage, summary }. `usage` is the display form for
+// help (may carry an arg hint like "logs [-f]"); `name` is the bare verb used for
+// completion. Order is the help display order.
+export const COMMANDS = [
+  { name: "up", usage: "up", summary: "Sign in (first run), pull + boot the runtime; print the URL" },
+  { name: "down", usage: "down", summary: "Stop the runtime (data preserved)" },
+  { name: "status", usage: "status", summary: "Show state, version, URL, and data size" },
+  { name: "ls", usage: "ls", summary: "List all alexandr instances" },
+  { name: "logs", usage: "logs [-f]", summary: "Show kernel logs (-f to follow)" },
+  { name: "connect", usage: "connect", summary: "Print the desktop-app connect link / paste-string" },
+  { name: "link", usage: "link", summary: "Re-link this runtime to your alexandr account (--force re-registers)" },
+  { name: "update", usage: "update", summary: "Update the runtime image (--to <tag>, --rollback)" },
+  { name: "backup", usage: "backup", summary: "Archive the data volume (--out <file>)" },
+  { name: "restore", usage: "restore <f>", summary: "Restore a data-volume archive (--yes)" },
+  { name: "config", usage: "config", summary: "get | set | list | unset  (e.g. alexandr config set ai.url …)" },
+  { name: "init", usage: "init", summary: "Write a committable ./alexandr config folder" },
+  { name: "destroy", usage: "destroy", summary: "Remove containers (--volumes also wipes /data)" },
+  { name: "completion", usage: "completion", summary: "Print a shell completion script (bash|zsh|fish)" },
+  { name: "doctor", usage: "doctor", summary: "Check Docker, ports, and configuration" },
+  { name: "version", usage: "version", summary: "Show CLI + runtime versions" },
+];
+
+// Flags offered everywhere (mirrors the COMMON OPTIONS block in cli.js help).
+const GLOBAL_FLAGS = ["--port", "--domain", "--name", "--dir", "--open", "--offline", "--yes", "--json", "--help"];
+const SHELLS = ["bash", "zsh", "fish"];
+const NAMES = COMMANDS.map((c) => c.name);
+
+// Sub-surfaces worth completing one level deep.
+const CONFIG_SUBS = ["get", "set", "list", "unset"];
+
+// ---- generators -------------------------------------------------------------
+
+function bashScript() {
+  return `# alexandr completion (bash)
+# Load it for this shell:   source <(alexandr completion bash)
+# Make it permanent:        echo 'source <(alexandr completion bash)' >> ~/.bashrc
+_alexandr() {
+  local cur prev cmd
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "\$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( \$(compgen -W "${NAMES.join(" ")}" -- "\$cur") )
+    return
+  fi
+  cmd="\${COMP_WORDS[1]}"
+  case "\$cmd" in
+    completion) COMPREPLY=( \$(compgen -W "${SHELLS.join(" ")}" -- "\$cur") ); return ;;
+    config) if [ "\$COMP_CWORD" -eq 2 ]; then COMPREPLY=( \$(compgen -W "${CONFIG_SUBS.join(" ")}" -- "\$cur") ); return; fi ;;
+  esac
+  if [[ "\$cur" == -* ]]; then
+    COMPREPLY=( \$(compgen -W "${GLOBAL_FLAGS.join(" ")}" -- "\$cur") )
+  fi
+}
+complete -F _alexandr alexandr
+`;
+}
+
+function zshScript() {
+  // zsh autoload body form: save as `_alexandr` on your $fpath. The describe
+  // entries are `name:description`; our summaries contain no leading colon, so the
+  // first colon is always the separator.
+  const describe = COMMANDS.map((c) => `    '${c.name}:${c.summary.replace(/'/g, "''")}'`).join("\n");
+  const flags = GLOBAL_FLAGS.map((f) => `    '${f}'`).join("\n");
+  return `#compdef alexandr
+# alexandr completion (zsh)
+# Install on your $fpath, then restart zsh, e.g.:
+#   alexandr completion zsh | sudo tee /usr/local/share/zsh/site-functions/_alexandr
+local -a _alexandr_cmds _alexandr_flags
+_alexandr_cmds=(
+${describe}
+)
+_alexandr_flags=(
+${flags}
+)
+if (( CURRENT == 2 )); then
+  _describe -t commands 'alexandr command' _alexandr_cmds
+  return
+fi
+case "\${words[2]}" in
+  completion) _values 'shell' ${SHELLS.join(" ")}; return ;;
+  config) (( CURRENT == 3 )) && { _values 'subcommand' ${CONFIG_SUBS.join(" ")}; return } ;;
+esac
+_describe -t options 'option' _alexandr_flags
+`;
+}
+
+function fishScript() {
+  const lines = [
+    "# alexandr completion (fish)",
+    "# Install:  alexandr completion fish > ~/.config/fish/completions/alexandr.fish",
+    "complete -c alexandr -f",
+  ];
+  for (const c of COMMANDS) {
+    lines.push(`complete -c alexandr -n __fish_use_subcommand -a ${c.name} -d '${c.summary.replace(/'/g, "\\'")}'`);
+  }
+  lines.push("complete -c alexandr -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'");
+  lines.push(`complete -c alexandr -n '__fish_seen_subcommand_from config' -a '${CONFIG_SUBS.join(" ")}'`);
+  for (const f of GLOBAL_FLAGS) {
+    if (f.startsWith("--")) lines.push(`complete -c alexandr -l ${f.slice(2)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+const GENERATORS = { bash: bashScript, zsh: zshScript, fish: fishScript };
+
+// ---- command ----------------------------------------------------------------
+
+export async function completion(flags) {
+  const shell = flags._[0];
+  if (!shell) fail(`usage: alexandr completion <${SHELLS.join("|")}>`, EXIT.USAGE);
+  const gen = GENERATORS[shell];
+  if (!gen) fail(`Unsupported shell '${shell}'. Supported: ${SHELLS.join(", ")}.`, EXIT.USAGE);
+  process.stdout.write(gen());
+}

package/src/connect.js

@@ -0,0 +1,11 @@
+// Build the connection handoff artifacts the desktop app consumes (see
+// docs/plans/self-hosted-connection.md §3): a clickable deep link and a
+// paste-string. The CLI only PRINTS these — the app owns decoding them.
+// URL-only (account-required-runtimes D5): the box is CP-linked, so the app
+// verifies membership against the account — no token rides the handoff.
+
+export function buildConnect({ url }) {
+  const deepLink = `alexandr://connect?${new URLSearchParams({ url }).toString()}`;
+  const pasteString = `alexandr-connect_${Buffer.from(url, "utf8").toString("base64url")}`;
+  return { deepLink, pasteString };
+}

package/src/deps.js

@@ -0,0 +1,91 @@
+// Best-effort dependency installer: when `alexandr up` finds Docker/Compose missing on a
+// LINUX box (the self-host case), it offers to install them right there — Docker's official
+// convenience script (get.docker.com) + systemd start — instead of failing with a doc link.
+// Interactive-only (a real TTY, an explicit yes), root or sudo. macOS/Windows stay
+// guidance-only: Docker Desktop can't be installed silently, and the product's Mac story
+// ("On this Mac") uses the desktop app's own VM, never Docker.
+
+import { spawnSync } from "node:child_process";
+import { log, ok, warn, step, dim, bold } from "./util.js";
+import { select } from "./prompt.js";
+import { exec } from "./docker.js";
+
+const GET_DOCKER = "curl -fsSL https://get.docker.com | sh";
+
+/** What this host looks like for fixing purposes. Split from the planner so the plan
+ *  logic is a pure function (unit-testable without a Linux box). */
+export function detectHost() {
+  return {
+    platform: process.platform,
+    isRoot: typeof process.getuid === "function" && process.getuid() === 0,
+    hasSystemctl: exec("systemctl", ["--version"]).status === 0,
+    hasApt: exec("apt-get", ["--version"]).status === 0,
+    hasSudo: exec("sudo", ["--version"]).status === 0,
+  };
+}
+
+/**
+ * The fix plan for a set of dockerProblems() on a given host — an ordered list of
+ * `{ title, cmd }` shell steps, or null when there's nothing we can responsibly run
+ * (non-Linux, or a daemon we can't start without systemd). Pure — no side effects.
+ */
+export function planDependencyFix(problems, host) {
+  if (host.platform !== "linux") return null;
+  const kinds = new Set(problems.map((p) => p.kind));
+  const steps = [];
+  if (kinds.has("docker-missing")) {
+    // The official script installs Engine + the Compose v2 plugin on every major distro,
+    // so one step covers the compose gap too.
+    steps.push({ title: "Install Docker Engine + Compose v2 (Docker's official get.docker.com script)", cmd: GET_DOCKER });
+    if (host.hasSystemctl) steps.push({ title: "Start the Docker service (now + on boot)", cmd: "systemctl enable --now docker" });
+    return steps;
+  }
+  if (kinds.has("daemon-down")) {
+    if (!host.hasSystemctl) return null; // no systemd → we don't know how to start it here
+    steps.push({ title: "Start the Docker service (now + on boot)", cmd: "systemctl enable --now docker" });
+  }
+  if (kinds.has("compose-missing")) {
+    steps.push(
+      host.hasApt
+        ? { title: "Install the Compose v2 plugin (apt)", cmd: "apt-get update -qq && apt-get install -y docker-compose-plugin" }
+        : { title: "Upgrade Docker to a version with Compose v2 (get.docker.com)", cmd: GET_DOCKER },
+    );
+  }
+  return steps.length ? steps : null;
+}
+
+/**
+ * Offer to run the fix plan. Returns true when an install was ATTEMPTED (the caller
+ * should re-check dockerProblems()), false when declined/not applicable — the caller
+ * falls through to the normal failure messages either way.
+ */
+export async function offerDependencyInstall(problems) {
+  if (!(process.stdin.isTTY && process.stdout.isTTY)) return false;
+  const host = detectHost();
+  const steps = planDependencyFix(problems, host);
+  if (!steps) return false;
+  if (!host.isRoot && !host.hasSudo) {
+    warn("Dependencies are missing, but you're not root and sudo isn't available — install Docker manually, then re-run.");
+    return false;
+  }
+  const asRoot = (cmd) => (host.isRoot ? cmd : `sudo sh -c '${cmd}'`);
+  log(`${bold("alexandr")} ${dim("needs Docker + Compose v2 on this server. It can set that up now:")}`);
+  for (const s of steps) log(`  ${dim("•")} ${s.title}\n    ${dim(asRoot(s.cmd))}`);
+  const go = await select("Install the missing dependencies?", [
+    { label: "Yes, install them", hint: host.isRoot ? "runs as root" : "runs via sudo — you may be asked for your password", value: true },
+    { label: "No, I'll handle it myself", value: false },
+  ]);
+  if (!go) return false;
+  for (const s of steps) {
+    step(`${s.title}…`);
+    const r = host.isRoot
+      ? spawnSync("sh", ["-c", s.cmd], { stdio: "inherit" })
+      : spawnSync("sudo", ["sh", "-c", s.cmd], { stdio: "inherit" });
+    if ((r.status ?? 1) !== 0) {
+      warn(`That step failed (exit ${r.status ?? "?"}) — finish it manually, then re-run \`alexandr up\`.`);
+      return true;
+    }
+  }
+  ok("Dependencies installed.");
+  return true;
+}

package/src/docker.js

@@ -0,0 +1,94 @@
+// Thin shell over the Docker CLI. We never bundle a runtime — we orchestrate
+// `docker compose` against the published kernel image. Pure Node child_process.
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+import { EXIT } from "./exit.js";
+
+// Run a command, capturing output. Never throws on non-zero exit.
+export function exec(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", ...opts });
+  return {
+    status: r.error ? 127 : r.status ?? 1,
+    stdout: (r.stdout || "").trim(),
+    stderr: (r.stderr || "").trim(),
+  };
+}
+
+export const hasDocker = () => exec("docker", ["--version"]).status === 0;
+export const daemonUp = () => exec("docker", ["info"]).status === 0;
+export const composeV2 = () => exec("docker", ["compose", "version"]).status === 0;
+export const legacyComposeOnly = () =>
+  !composeV2() && exec("docker-compose", ["--version"]).status === 0;
+
+// Base args binding a compose invocation to one instance dir + project name.
+// --project-directory + an explicit -f make the relative ./Caddyfile and ./.env
+// binds resolve correctly even when invoked from elsewhere; -p pins the project
+// so npx-from-tmp and a global install land on the SAME named volumes.
+function baseArgs(dir, projectName) {
+  return [
+    "compose",
+    "--project-directory",
+    dir,
+    "-f",
+    path.join(dir, "docker-compose.yml"), // path.join → native separators (Windows-safe)
+    "-p",
+    projectName,
+  ];
+}
+
+// Run a compose subcommand, inheriting stdio by default (streams to the user).
+export function compose(dir, projectName, args, opts = {}) {
+  const r = spawnSync("docker", [...baseArgs(dir, projectName), ...args], {
+    stdio: opts.stdio ?? "inherit",
+    encoding: "utf8",
+    env: { ...process.env, ...(opts.env || {}) },
+  });
+  return { status: r.error ? 127 : r.status ?? 1 };
+}
+
+// Run a compose subcommand and capture its output.
+export function composeCapture(dir, projectName, args, env = {}) {
+  const r = spawnSync("docker", [...baseArgs(dir, projectName), ...args], {
+    encoding: "utf8",
+    env: { ...process.env, ...env },
+  });
+  return {
+    status: r.error ? 127 : r.status ?? 1,
+    stdout: (r.stdout || "").trim(),
+    stderr: (r.stderr || "").trim(),
+  };
+}
+
+// Pre-flight the three CLI dependencies. Returns a list of problems (empty = ok);
+// each problem carries the exit code its failure class maps to (see exit.js), so
+// callers can surface a specific code instead of a catch-all 1.
+export function dockerProblems() {
+  const problems = [];
+  if (!hasDocker()) {
+    problems.push({
+      kind: "docker-missing",
+      exit: EXIT.DOCKER_MISSING,
+      message: "Docker is not installed or not on your PATH — https://docs.docker.com/get-docker/",
+    });
+    return problems; // nothing else is checkable without it
+  }
+  if (!daemonUp()) {
+    problems.push({
+      kind: "daemon-down",
+      exit: EXIT.DOCKER_DAEMON_DOWN,
+      message: "The Docker daemon isn't running — start Docker Desktop / the docker service.",
+    });
+  }
+  if (!composeV2()) {
+    problems.push({
+      kind: "compose-missing",
+      exit: EXIT.COMPOSE_MISSING,
+      message: legacyComposeOnly()
+        ? "Only legacy `docker-compose` found — this CLI needs Compose v2 (`docker compose`). Update Docker."
+        : "`docker compose` (v2) is unavailable — update Docker to a version with the compose plugin.",
+    });
+  }
+  return problems;
+}

package/src/exit.js

@@ -0,0 +1,37 @@
+// The CLI's exit-code contract: a distinct, stable code per failure class so
+// scripts, CI, and `&&` chains can branch on *why* a command failed — not just
+// that it did. Codes are part of the public surface; keep them in sync with the
+// "Exit codes" table in README.md and docs/plans/standalone-cli.md.
+//
+//   0  ok
+//   1  general / uncategorized error (an unexpected throw)
+//   2  usage   — bad invocation: unknown command/subcommand, missing/bad args
+//   3  docker missing        — `docker` not installed or not on PATH
+//   4  docker daemon down    — installed, but the daemon is unreachable
+//   5  compose missing       — Docker present, but no Compose v2 plugin
+//   6  port busy             — the requested kernel/HTTP port is already in use
+//   7  no instance           — no materialized instance where one is required
+//   8  needs confirmation    — a destructive op was run without --yes
+//   9  runtime               — a docker/compose operation failed at runtime
+export const EXIT = Object.freeze({
+  OK: 0,
+  GENERAL: 1,
+  USAGE: 2,
+  DOCKER_MISSING: 3,
+  DOCKER_DAEMON_DOWN: 4,
+  COMPOSE_MISSING: 5,
+  PORT_BUSY: 6,
+  NO_INSTANCE: 7,
+  CONFIRMATION: 8,
+  RUNTIME: 9,
+});
+
+// The codes a healthy `doctor`/pre-flight may legitimately exit with on a host
+// that simply lacks a working Docker — used by the CI smoke test to tell a
+// "Docker isn't set up here" exit apart from an actual CLI crash.
+export const DOCTOR_OK_EXITS = Object.freeze([
+  EXIT.OK,
+  EXIT.DOCKER_MISSING,
+  EXIT.DOCKER_DAEMON_DOWN,
+  EXIT.COMPOSE_MISSING,
+]);

package/src/instance.js

@@ -0,0 +1,102 @@
+// Resolve which instance a command targets, materialize its files, and read/write
+// its .env. Two modes: a global instance under ~/.alexandr (the npx default) or a
+// project instance in ./alexandr (committable, created by `alexandr init`).
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+// templates/ ships inside the package; locate it relative to THIS file (never
+// process.cwd() or __dirname — neither is correct for a published ESM package).
+const TEMPLATES = path.resolve(fileURLToPath(import.meta.url), "..", "..", "templates");
+const GLOBAL_ROOT = path.join(os.homedir(), ".alexandr");
+const ENV_FILE = ".env";
+const sha8 = (s) => crypto.createHash("sha256").update(s).digest("hex").slice(0, 8);
+
+// Decide the target instance from flags. Precedence:
+//   --dir <d>                      → project instance at <d>
+//   ./alexandr/docker-compose.yml  → project instance in cwd
+//   --name <n>                     → global instance ~/.alexandr/<n>
+//   (default)                      → global instance ~/.alexandr/workspace
+export function resolveInstance(flags = {}) {
+  const cwdProject = path.resolve(process.cwd(), "alexandr");
+  if (flags.dir) {
+    const dir = path.resolve(String(flags.dir));
+    return { dir, mode: "project", name: path.basename(dir), projectName: `alexandr-${sha8(dir)}` };
+  }
+  if (fs.existsSync(path.join(cwdProject, "docker-compose.yml"))) {
+    return { dir: cwdProject, mode: "project", name: path.basename(path.dirname(cwdProject)), projectName: `alexandr-${sha8(cwdProject)}` };
+  }
+  const name = flags.name ? String(flags.name) : "workspace";
+  const dir = path.join(GLOBAL_ROOT, name);
+  return { dir, mode: "global", name, projectName: name === "workspace" ? "alexandr" : `alexandr-${name}` };
+}
+
+export const isMaterialized = (dir) => fs.existsSync(path.join(dir, "docker-compose.yml"));
+
+// Copy the compose + Caddyfile templates into the instance dir and ensure a .env
+// exists. Idempotent for the managed files; never clobbers an existing .env.
+export function materialize(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  for (const f of ["docker-compose.yml", "Caddyfile"]) {
+    fs.copyFileSync(path.join(TEMPLATES, f), path.join(dir, f));
+  }
+  const envPath = path.join(dir, ENV_FILE);
+  if (!fs.existsSync(envPath)) fs.copyFileSync(path.join(TEMPLATES, "env.example"), envPath);
+  return envPath;
+}
+
+// Parse the .env into a flat map. Commented lines are treated as unset.
+export function readEnv(dir) {
+  const p = path.join(dir, ENV_FILE);
+  const out = {};
+  if (!fs.existsSync(p)) return out;
+  for (const line of fs.readFileSync(p, "utf8").split("\n")) {
+    const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)$/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+// True only if KEY is present, uncommented, and non-empty (empty ≠ set).
+export const envHas = (dir, key) => {
+  const v = readEnv(dir)[key];
+  return v !== undefined && v !== "";
+};
+
+// Set KEY=value, replacing the first existing (commented or not) line, else append.
+export function setEnv(dir, key, value) {
+  const p = path.join(dir, ENV_FILE);
+  let lines = fs.existsSync(p) ? fs.readFileSync(p, "utf8").replace(/\n$/, "").split("\n") : [];
+  const re = new RegExp(`^\\s*#?\\s*${key}\\s*=`);
+  let done = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (re.test(lines[i])) {
+      lines[i] = `${key}=${value}`;
+      done = true;
+      break;
+    }
+  }
+  if (!done) lines.push(`${key}=${value}`);
+  if (lines.length === 1 && lines[0] === "") lines = [`${key}=${value}`];
+  fs.writeFileSync(p, `${lines.join("\n")}\n`);
+}
+
+// "Unset" by commenting the line out — preserves it as documentation, and keeps
+// empty (which the kernel reads as "explicitly off") distinct from absent.
+export function unsetEnv(dir, key) {
+  const p = path.join(dir, ENV_FILE);
+  if (!fs.existsSync(p)) return;
+  const re = new RegExp(`^\\s*${key}\\s*=`);
+  const lines = fs.readFileSync(p, "utf8").replace(/\n$/, "").split("\n").map((l) => (re.test(l) ? `# ${l}` : l));
+  fs.writeFileSync(p, `${lines.join("\n")}\n`);
+}
+
+// The loopback kernel port for this instance (host side), honoring the .env.
+export function kernelPort(dir) {
+  const v = readEnv(dir).ALEXANDR_KERNEL_PORT;
+  const n = v ? Number(v) : 3030;
+  return Number.isFinite(n) && n > 0 ? n : 3030;
+}