wattetheria 0.1.0 → 0.1.2

package/.env.release.example

@@ -1,9 +1,9 @@
 # Coordinated release image set
-WATTETHERIA_KERNEL_IMAGE=ghcr.io/wattetheria/wattetheria-kernel:0.1.0
-WATTETHERIA_OBSERVATORY_IMAGE=ghcr.io/wattetheria/wattetheria-observatory:0.1.0
-WATTSWARM_KERNEL_IMAGE=ghcr.io/wattetheria/wattswarm-kernel:0.1.0
-WATTSWARM_RUNTIME_IMAGE=ghcr.io/wattetheria/wattswarm-runtime:0.1.0
-WATTSWARM_WORKER_IMAGE=ghcr.io/wattetheria/wattswarm-worker:0.1.0
+WATTETHERIA_KERNEL_IMAGE=ghcr.io/wattetheria/wattetheria-kernel:1.0.0
+WATTETHERIA_OBSERVATORY_IMAGE=ghcr.io/wattetheria/wattetheria-observatory:1.0.0
+WATTSWARM_KERNEL_IMAGE=ghcr.io/wattetheria/wattswarm-kernel:1.0.0
+WATTSWARM_RUNTIME_IMAGE=ghcr.io/wattetheria/wattswarm-runtime:1.0.0
+WATTSWARM_WORKER_IMAGE=ghcr.io/wattetheria/wattswarm-worker:1.0.0
 
 # Host bindings
 WATTETHERIA_CONTROL_PLANE_BIND_HOST=127.0.0.1

package/lib/cli.js

@@ -3,9 +3,11 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
+const { createInterface } = require("node:readline/promises");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const PACKAGE_JSON = require(path.join(PACKAGE_ROOT, "package.json"));
+const RELEASE_ENV_TEMPLATE = path.join(PACKAGE_ROOT, ".env.release.example");
 const DEFAULT_DEPLOY_DIR = path.join(os.homedir(), ".wattetheria", "deploy");
 const DEFAULT_PROJECT_NAME = "wattetheria";
 const DEFAULT_COMMAND = "install";
@@ -16,6 +18,15 @@ const IMAGE_KEYS = [
   "WATTSWARM_RUNTIME_IMAGE",
   "WATTSWARM_WORKER_IMAGE"
 ];
+const DOCKER_INSTALL_URLS = {
+  darwin: "https://www.docker.com/products/docker-desktop/",
+  win32: "https://www.docker.com/products/docker-desktop/",
+  linux: "https://docs.docker.com/engine/install/"
+};
+const WINDOWS_DOCKER_CANDIDATES = [
+  "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe",
+  "C:\\Program Files\\Docker\\cli-plugins\\docker.exe"
+];
 
 function printHelp() {
   console.log(`Wattetheria CLI ${PACKAGE_JSON.version}
@@ -36,6 +47,7 @@ Commands:
   help        Show this help
 
 Options:
+  --version              Show CLI version
   --dir <path>           Deployment directory (default: ${DEFAULT_DEPLOY_DIR})
   --project-name <name>  Docker compose project name (default: ${DEFAULT_PROJECT_NAME})
   --tag <tag>            Override all release image tags
@@ -47,6 +59,22 @@ Options:
 }
 
 function parseArgs(argv) {
+  if (argv[0] === "--version" || argv[0] === "-v") {
+    return {
+      command: "version",
+      options: {
+        dir: DEFAULT_DEPLOY_DIR,
+        projectName: DEFAULT_PROJECT_NAME,
+        tag: null,
+        force: false,
+        healthChecks: true,
+        volumes: false,
+        purge: false,
+        composeArgs: []
+      }
+    };
+  }
+
   let command = DEFAULT_COMMAND;
   let index = 0;
   if (argv[0] && !argv[0].startsWith("-")) {
@@ -57,7 +85,7 @@ function parseArgs(argv) {
   const options = {
     dir: DEFAULT_DEPLOY_DIR,
     projectName: DEFAULT_PROJECT_NAME,
-    tag: PACKAGE_JSON.version,
+    tag: null,
     force: false,
     healthChecks: true,
     volumes: false,
@@ -104,29 +132,228 @@ function requireValue(flag, value) {
   return value;
 }
 
-function ensureCommandAvailable(command, helpText) {
-  const result = spawnSync(command, ["--version"], { stdio: "ignore" });
+function getDockerInstallUrl() {
+  return DOCKER_INSTALL_URLS[process.platform] || DOCKER_INSTALL_URLS.linux;
+}
+
+function getDockerCandidates() {
+  if (process.platform === "win32") {
+    return ["docker", ...WINDOWS_DOCKER_CANDIDATES];
+  }
+  return ["docker"];
+}
+
+function resolveDockerCommand() {
+  for (const candidate of getDockerCandidates()) {
+    const result = spawnSync(candidate, ["--version"], { stdio: "ignore" });
+    if (!result.error && result.status === 0) {
+      return candidate;
+    }
+  }
+  return "";
+}
+
+function getGitRevision() {
+  if (typeof PACKAGE_JSON.gitHead === "string" && PACKAGE_JSON.gitHead.trim()) {
+    return PACKAGE_JSON.gitHead.trim();
+  }
+
+  const result = spawnSync("git", ["rev-parse", "--short=7", "HEAD"], {
+    cwd: PACKAGE_ROOT,
+    stdio: "pipe",
+    encoding: "utf8"
+  });
   if (result.error || result.status !== 0) {
-    throw new Error(helpText);
+    return "";
   }
+  return (result.stdout || "").trim();
 }
 
-function ensureDockerAvailable() {
-  ensureCommandAvailable(
-    "docker",
-    "Docker is required. Install Docker Desktop or another Docker-compatible runtime first."
-  );
+function extractImageTag(imageRef) {
+  if (!imageRef) {
+    return "";
+  }
+  const lastColon = imageRef.lastIndexOf(":");
+  const lastSlash = imageRef.lastIndexOf("/");
+  if (lastColon <= lastSlash) {
+    return "";
+  }
+  return imageRef.slice(lastColon + 1).trim();
+}
+
+function getDefaultReleaseVersion() {
+  try {
+    const envMap = readEnvFile(RELEASE_ENV_TEMPLATE);
+    const tags = IMAGE_KEYS
+      .map((key) => extractImageTag(envMap.get(key)))
+      .filter(Boolean);
+    if (tags.length === IMAGE_KEYS.length && new Set(tags).size === 1) {
+      return tags[0];
+    }
+  } catch (error) {
+    // fall through to package version
+  }
+  return PACKAGE_JSON.version;
+}
+
+function formatVersionString() {
+  const revision = getGitRevision();
+  const releaseVersion = getDefaultReleaseVersion();
+  if (revision) {
+    return `Wattetheria ${releaseVersion} (${revision})`;
+  }
+  return `Wattetheria ${releaseVersion}`;
+}
+
+function formatBanner() {
+  return `${formatVersionString()} — Local agent runtime with swarm sync and external agent reach.`;
+}
+
+function formatDockerStatusMessage(status) {
+  const installUrl = status.installUrl || getDockerInstallUrl();
+  switch (status.code) {
+    case "missing-docker":
+      if (process.platform === "linux") {
+        return [
+          "Docker runtime not found.",
+          "Install Docker Engine or another Docker-compatible runtime, then run the command again.",
+          `Install guide: ${installUrl}`
+        ].join("\n");
+      }
+      return [
+        "Docker runtime not found.",
+        "Install Docker Desktop or another Docker-compatible runtime, then run the command again.",
+        process.platform === "win32"
+          ? "If you just installed Docker Desktop, open a new PowerShell window and retry."
+          : "",
+        `Download: ${installUrl}`
+      ].filter(Boolean).join("\n");
+    case "missing-compose":
+      return [
+        "Docker Compose v2 is required.",
+        process.platform === "linux"
+          ? "Install or upgrade Docker Engine/Compose so `docker compose` is available."
+          : "Install or upgrade Docker Desktop so `docker compose` is available.",
+        `Help: ${installUrl}`
+      ].join("\n");
+    case "daemon-unreachable":
+      return [
+        "Docker is installed but the daemon is not reachable.",
+        "Start Docker Desktop or your Docker service, wait until it is ready, then retry."
+      ].join("\n");
+    default:
+      return "Docker runtime check failed.";
+  }
+}
+
+function getDockerStatus() {
+  const installUrl = getDockerInstallUrl();
+  const dockerCommand = resolveDockerCommand();
+  if (!dockerCommand) {
+    return {
+      ready: false,
+      code: "missing-docker",
+      installUrl
+    };
+  }
 
-  const compose = spawnSync("docker", ["compose", "version"], {
+  const compose = spawnSync(dockerCommand, ["compose", "version"], {
     stdio: "ignore"
   });
   if (compose.error || compose.status !== 0) {
-    throw new Error("Docker Compose v2 is required.");
+    return {
+      ready: false,
+      code: "missing-compose",
+      installUrl,
+      dockerCommand
+    };
   }
 
-  const info = spawnSync("docker", ["info"], { stdio: "ignore" });
+  const info = spawnSync(dockerCommand, ["info"], { stdio: "ignore" });
   if (info.error || info.status !== 0) {
-    throw new Error("Docker daemon is not reachable. Start Docker Desktop or the Docker service first.");
+    return {
+      ready: false,
+      code: "daemon-unreachable",
+      installUrl,
+      dockerCommand
+    };
+  }
+
+  return {
+    ready: true,
+    dockerCommand
+  };
+}
+
+function isInteractiveTerminal() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function openUrl(url) {
+  let command;
+  let args;
+  if (process.platform === "darwin") {
+    command = "open";
+    args = [url];
+  } else if (process.platform === "win32") {
+    command = "cmd";
+    args = ["/c", "start", "", url];
+  } else {
+    command = "xdg-open";
+    args = [url];
+  }
+
+  const result = spawnSync(command, args, { stdio: "ignore" });
+  return !result.error && result.status === 0;
+}
+
+async function promptForDockerSetup(status) {
+  const installUrl = status.installUrl || getDockerInstallUrl();
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    while (true) {
+      console.log("");
+      console.log("Wattetheria needs Docker before it can install the local stack.");
+      console.log(formatDockerStatusMessage(status));
+      console.log("");
+      console.log("1. Open runtime install guide");
+      console.log("2. Retry Docker check");
+      console.log("3. Cancel");
+
+      const answer = (await rl.question("Select an option [1-3]: ")).trim();
+      if (answer === "1") {
+        const opened = openUrl(installUrl);
+        console.log(opened ? "Opened Docker install page." : `Open this URL in your browser: ${installUrl}`);
+        continue;
+      }
+      if (answer === "2") {
+        return;
+      }
+      if (answer === "3" || answer === "") {
+        throw new Error(formatDockerStatusMessage(status));
+      }
+      console.log("Please choose 1, 2, or 3.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+async function ensureDockerAvailable(options = {}) {
+  const interactive = Boolean(options.interactive);
+  while (true) {
+    const status = getDockerStatus();
+    if (status.ready) {
+      return status;
+    }
+    if (!interactive || !isInteractiveTerminal()) {
+      throw new Error(formatDockerStatusMessage(status));
+    }
+    await promptForDockerSetup(status);
   }
 }
 
@@ -221,8 +448,9 @@ function randomPassword() {
 }
 
 function runCompose(options, args, capture = false) {
+  const dockerCommand = resolveDockerCommand() || "docker";
   const result = spawnSync(
-    "docker",
+    dockerCommand,
     [
       "compose",
       "--project-name",
@@ -242,6 +470,16 @@ function runCompose(options, args, capture = false) {
     throw result.error;
   }
   if (result.status !== 0) {
+    const stderr = capture ? (result.stderr || "").trim() : "";
+    if (stderr.includes("failed to resolve reference") && stderr.includes(": not found")) {
+      throw new Error(
+        [
+          "One or more release images were not found in the container registry.",
+          "This usually means the requested image tag has not been published yet.",
+          "Publish the matching GHCR images first, or run the command with --tag <published-tag>."
+        ].join("\n")
+      );
+    }
     if (capture && result.stderr) {
       throw new Error(result.stderr.trim() || `docker compose ${args.join(" ")} failed`);
     }
@@ -303,7 +541,7 @@ function printSummary(options) {
 }
 
 async function install(options) {
-  ensureDockerAvailable();
+  await ensureDockerAvailable({ interactive: true });
   ensureDeploymentAssets(options);
   runCompose(options, ["config"], true);
   console.log("Pulling release images...");
@@ -317,7 +555,7 @@ async function install(options) {
 }
 
 async function start(options) {
-  ensureDockerAvailable();
+  await ensureDockerAvailable();
   if (!fs.existsSync(composeFilePath(options)) || !fs.existsSync(envFilePath(options))) {
     throw new Error("Deployment is not initialized. Run install first.");
   }
@@ -328,13 +566,13 @@ async function start(options) {
   printSummary(options);
 }
 
-function status(options) {
-  ensureDockerAvailable();
+async function status(options) {
+  await ensureDockerAvailable();
   runCompose(options, ["ps"]);
 }
 
 async function update(options) {
-  ensureDockerAvailable();
+  await ensureDockerAvailable();
   if (!fs.existsSync(composeFilePath(options)) || !fs.existsSync(envFilePath(options))) {
     throw new Error("Deployment is not initialized. Run install first.");
   }
@@ -349,13 +587,13 @@ async function update(options) {
   printSummary(options);
 }
 
-function stop(options) {
-  ensureDockerAvailable();
+async function stop(options) {
+  await ensureDockerAvailable();
   runCompose(options, ["down"]);
 }
 
-function uninstall(options) {
-  ensureDockerAvailable();
+async function uninstall(options) {
+  await ensureDockerAvailable();
   const args = ["down"];
   if (options.volumes) {
     args.push("-v");
@@ -367,20 +605,40 @@ function uninstall(options) {
   }
 }
 
-function logs(options) {
-  ensureDockerAvailable();
+async function logs(options) {
+  await ensureDockerAvailable();
   runCompose(options, ["logs", ...options.composeArgs]);
 }
 
 function doctor() {
-  ensureDockerAvailable();
+  const status = getDockerStatus();
+  if (!status.ready) {
+    throw new Error(formatDockerStatusMessage(status));
+  }
   console.log("Docker runtime is available.");
   console.log(`Node.js ${process.version} is available.`);
 }
 
+function printVersion() {
+  console.log(formatVersionString());
+}
+
+function shouldPrintBanner(command) {
+  return !["help", "--help", "-h", "version"].includes(command);
+}
+
+function printBanner() {
+  console.log(formatBanner());
+  console.log("");
+}
+
 async function run(argv) {
   const { command, options } = parseArgs(argv);
 
+  if (shouldPrintBanner(command)) {
+    printBanner();
+  }
+
   switch (command) {
     case "install":
       await install(options);
@@ -390,24 +648,27 @@ async function run(argv) {
       await start(options);
       return;
     case "status":
-      status(options);
+      await status(options);
       return;
     case "update":
       await update(options);
       return;
     case "stop":
     case "down":
-      stop(options);
+      await stop(options);
       return;
     case "uninstall":
-      uninstall(options);
+      await uninstall(options);
       return;
     case "logs":
-      logs(options);
+      await logs(options);
       return;
     case "doctor":
       doctor();
       return;
+    case "version":
+      printVersion();
+      return;
     case "help":
     case "--help":
     case "-h":

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "wattetheria",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Wattetheria deployment CLI",
   "license": "Apache-2.0",
   "type": "commonjs",
-  "bin": {
-    "wattetheria": "./bin/wattetheria.js"
-  },
+  "bin": "bin/wattetheria.js",
   "files": [
     "bin/",
     "lib/",