alexandr 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexandr",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Run the alexandr workspace runtime locally (npx alexandr up), and develop alexandr apps against a workspace (alexandr app link | dev | build | deploy).",
   "type": "module",
   "bin": {

package/src/commands.js

@@ -616,6 +616,9 @@ export async function update(flags) {
     stampUpdaterEnv(inst);
   }
   const prevImage = readEnv(inst.dir).ALEXANDR_IMAGE || `${IMAGE_BASE}:latest`;
+  // What `.previous-image` said BEFORE this run — restored if the pull fails (see below).
+  const pointerPath = path.join(inst.dir, ".previous-image");
+  const priorPointer = fs.existsSync(pointerPath) ? fs.readFileSync(pointerPath, "utf8") : null;
   const base = kernelUrl(kernelPort(inst.dir));
   const before = (await kVersion(base))?.version ?? "?";
 
@@ -662,6 +665,21 @@ export async function update(flags) {
       pull = compose(inst.dir, inst.projectName, ["pull", "kernel"]);
     }
     if (pull.status !== 0) {
+      // ⚠ PUT THE PIN BACK. The new tag was written into .env before the pull so compose would
+      // pull it; a failed pull must not leave the box pointing at an image it does not have —
+      // the next `up` would then boot the new version behind the operator's back, which is
+      // exactly what the first sidecar press on aos did (2026-09-08). `.previous-image` is
+      // restored too, so a later `--rollback` still means what it says.
+      setEnv(inst.dir, "ALEXANDR_IMAGE", prevImage);
+      if (priorPointer === null) {
+        try {
+          fs.unlinkSync(pointerPath);
+        } catch {
+          /* nothing was recorded before this run either */
+        }
+      } else {
+        fs.writeFileSync(pointerPath, priorPointer);
+      }
       fail("Pull failed — check your network / the image tag.", EXIT.RUNTIME);
     }
   }

package/src/docker.js

@@ -2,6 +2,7 @@
 // `docker compose` against the published kernel image. Pure Node child_process.
 
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 
 import { EXIT } from "./exit.js";
@@ -38,12 +39,44 @@ function baseArgs(dir, projectName) {
   ];
 }
 
+/**
+ * ⚠⚠ THE INSTANCE'S `.env` IS THE ONLY SOURCE COMPOSE INTERPOLATES FROM. Compose gives the
+ * PROCESS environment precedence over the project's `.env`, and the updater sidecar's own
+ * environment is that very `.env`, frozen at the container's start (`env_file` on the service).
+ * So the recipe run from inside pinned `ALEXANDR_IMAGE=v0.0.13` in the file, then compose pulled
+ * and recreated v0.0.12 from the sidecar's stale variable — "Updated: 0.0.12 → 0.0.12", every
+ * press, including the one the 2026-09-08 E2E called a success (found on the first human press,
+ * aos, 2026-09-09). The same shadowing bites a host shell that exported `ALEXANDR_IMAGE` once.
+ * Every key the file defines is dropped from the child's environment; explicit `overrides`
+ * (a caller's deliberate one-off) still win.
+ */
+export function composeEnv(dir, base = process.env, overrides = {}) {
+  const env = { ...base };
+  for (const key of envFileKeys(dir)) delete env[key];
+  return { ...env, ...overrides };
+}
+
+// The KEYS the instance's `.env` defines (uncommented lines only) — a hand copy of the
+// instance module's parser, kept here because that module imports this one.
+function envFileKeys(dir) {
+  try {
+    return fs
+      .readFileSync(path.join(dir, ".env"), "utf8")
+      .split("\n")
+      .map((line) => line.match(/^\s*([A-Z0-9_]+)\s*=/))
+      .filter(Boolean)
+      .map((m) => m[1]);
+  } catch {
+    return [];
+  }
+}
+
 // 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 || {}) },
+    env: composeEnv(dir, process.env, opts.env || {}),
   });
   return { status: r.error ? 127 : r.status ?? 1 };
 }
@@ -52,7 +85,7 @@ export function compose(dir, projectName, args, opts = {}) {
 export function composeCapture(dir, projectName, args, env = {}) {
   const r = spawnSync("docker", [...baseArgs(dir, projectName), ...args], {
     encoding: "utf8",
-    env: { ...process.env, ...env },
+    env: composeEnv(dir, process.env, env),
   });
   return {
     status: r.error ? 127 : r.status ?? 1,

package/src/probe.js

@@ -1,7 +1,17 @@
 // Health/version probing of a running kernel over its loopback port. Uses the
 // global fetch (Node 18+). All probes are best-effort and never throw.
 
-export const kernelUrl = (port = 3030) => `http://127.0.0.1:${port}`;
+/**
+ * Where the kernel answers from HERE. On the host that is the loopback port compose mapped;
+ * inside the updater sidecar 127.0.0.1 is the sidecar itself, so the compose file sets
+ * `ALEXANDR_KERNEL_URL=http://kernel:3030` (the service name on the project network) — without
+ * it the recipe's health wait could not see the kernel from inside and reported `? → ?`
+ * (the first sidecar press on aos, 2026-09-08).
+ */
+export const kernelUrl = (port = 3030, env = process.env) => {
+  const explicit = (env.ALEXANDR_KERNEL_URL || "").trim();
+  return explicit ? explicit.replace(/\/+$/, "") : `http://127.0.0.1:${port}`;
+};
 
 async function getJson(url, timeoutMs = 2500) {
   const ctrl = new AbortController();

package/src/updater.js

@@ -124,6 +124,17 @@ export function createUpdaterHandler(deps) {
       } catch (e) {
         result = { ok: false, error: e?.message || String(e) };
       }
+      // ⚠ THE RECEIPT IS THE VERDICT, NOT THE EXIT CODE. `alexandr update` exits 0 after
+      // recreating whatever image compose resolved; when that is not the target, the box is
+      // "updated" onto the version it already ran (the 2026-09-09 press: `Updated: 0.0.12 →
+      // 0.0.12` with 0.0.13 asked for — the sidecar's own environment shadowed the pin). A done
+      // that names the wrong version is a failure with words, and the sheet offers the way back.
+      if (result.ok && !rollback && to && result.to && result.to !== to) {
+        result = {
+          ok: false,
+          error: `the box came back on ${result.to}, not ${to} — the recipe recreated the image it already ran`,
+        };
+      }
       if (result.ok) {
         write({ state: "done", phase: "done", to: result.to ?? to, from: result.from ?? null, rollback, startedAt, finishedAt: now() });
       } else {

package/templates/docker-compose.yml

@@ -48,6 +48,9 @@ services:
       ALEXANDR_INSTANCE_DIR: ${ALEXANDR_INSTANCE_DIR:-/nonexistent}
       ALEXANDR_COMPOSE_PROJECT: ${ALEXANDR_COMPOSE_PROJECT:-alexandr}
       ALEXANDR_UPDATER_SOCKET: /run/alexandr/updater.sock
+      # The kernel, by its service name: from inside this container 127.0.0.1 is the sidecar
+      # itself, and the recipe's health wait must see the kernel come back.
+      ALEXANDR_KERNEL_URL: http://kernel:3030
     env_file:
       - path: ./.env
         required: false            # ALEXANDR_CP_URL / ALEXANDR_RELEASES_URL → the feed it reads