@askexenow/exe-os 0.9.372 → 0.9.374

package/dist/stack-generate-manifest-MFMDWRUP.js

@@ -0,0 +1,810 @@
+#!/usr/bin/env node
+import {
+  writeSignedStackManifest
+} from "./chunk-3UUX5OY4.js";
+import "./chunk-ZGYNKA3O.js";
+import "./chunk-GHR4ZPJ7.js";
+import "./chunk-C5HUMAA7.js";
+import "./chunk-L25OAFOU.js";
+import "./chunk-L6RXG36J.js";
+import "./chunk-A7XLR3K7.js";
+import "./chunk-GQOEWNVM.js";
+import "./chunk-ZIG7VPJV.js";
+import "./chunk-HSGBZSCA.js";
+import "./chunk-RH4AH3YB.js";
+import {
+  isMainModule
+} from "./chunk-6Y4B3QF6.js";
+import "./chunk-JKKZGDLP.js";
+import "./chunk-MLKGABMK.js";
+
+// src/bin/stack-generate-manifest.ts
+import { execFile as execFileCb } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import { promisify } from "util";
+
+// src/lib/stack-manifest-generate.ts
+var STACK_SERVICE_SPECS = Object.freeze([
+  // ---- AskExe releases -----------------------------------------------------
+  {
+    key: "exe-os",
+    composeServices: ["exe-os", "exe-os-worker", "exe-update"],
+    origin: "askexe-release",
+    deployment: "stack",
+    ghRepo: "AskExe/exe-os",
+    imageName: "update.askexe.com/askexe/exe-os",
+    sourceImageName: "ghcr.io/askexe/exe-os",
+    // The version tag and the commit tag live in DIFFERENT ghcr repositories:
+    // release-stack-image.yml pushes `${stack.release.json image}` (exe-os:vX.Y.Z)
+    // and `ghcr.io/askexe/exed:sha-${github.sha}` from the same build.
+    commitImageName: "ghcr.io/askexe/exed",
+    env: "EXE_OS_IMAGE_TAG",
+    healthUrl: "http://127.0.0.1:8765/health",
+    required: true,
+    category: "core",
+    description: "exe-os daemon + MCP server"
+  },
+  {
+    key: "crm",
+    composeServices: ["exe-crm", "exe-crm-worker"],
+    origin: "askexe-release",
+    deployment: "stack",
+    ghRepo: "AskExe/exe-crm",
+    imageName: "update.askexe.com/askexe/exe-crm",
+    sourceImageName: "ghcr.io/askexe/exe-crm",
+    env: "CRM_IMAGE_TAG",
+    healthUrl: "http://127.0.0.1:3000/healthz",
+    category: "app",
+    description: "Customer relationship management",
+    note: "BLOCKED PENDING PROVENANCE (2026-08-20), not exempt: production runs an untagged image (digest bc0405717ed1) with EMPTY org.opencontainers.image.version and .revision labels, built 2026-08-07, matching no git tag, while main is 50 commits past v0.9.54. Resolving it to v0.9.54 would be a change of unknown scope. Trace the running image, cut a real release, then this entry flows through the identical code path as every other service with no special-casing."
+  },
+  {
+    key: "wiki",
+    composeServices: ["exe-wiki"],
+    origin: "askexe-release",
+    deployment: "stack",
+    ghRepo: "AskExe/exe-wiki",
+    imageName: "update.askexe.com/askexe/exe-wiki",
+    sourceImageName: "ghcr.io/askexe/exe-wiki",
+    env: "WIKI_IMAGE_TAG",
+    healthUrl: "http://127.0.0.1:3001/api/ping",
+    category: "app"
+  },
+  {
+    key: "gateway",
+    composeServices: ["exe-gateway"],
+    origin: "askexe-release",
+    deployment: "stack",
+    ghRepo: "AskExe/exe-gateway",
+    imageName: "update.askexe.com/askexe/exe-gateway",
+    sourceImageName: "ghcr.io/askexe/exe-gateway",
+    env: "GATEWAY_IMAGE_TAG",
+    healthUrl: "http://127.0.0.1:3100/health",
+    category: "app",
+    description: "WhatsApp/messaging gateway"
+  },
+  {
+    key: "auth",
+    composeServices: ["exe-auth"],
+    origin: "askexe-release",
+    deployment: "stack",
+    ghRepo: "AskExe/exe-auth",
+    // NO sourceImageName: exe-auth is published ONLY to the private
+    // update.askexe.com registry and is not mirrored to GHCR (bug 58840873 —
+    // the same reason deploy/compose/generate-env.ts carries a dedicated
+    // AUTH_REGISTRY constant). Probing ghcr.io for its `sha-*`/version tags
+    // resolves nothing, so provenance is read from — and the pin emitted for —
+    // the one registry the artifact actually exists in.
+    imageName: "update.askexe.com/askexe/exe-auth",
+    env: "AUTH_IMAGE_TAG",
+    healthUrl: "http://127.0.0.1:3300/api/health",
+    category: "auth",
+    description: "Shared SSO sign-in/sign-up"
+  },
+  {
+    key: "erp",
+    composeServices: ["exe-erp", "exe-erp-nginx", "exe-erp-websocket", "exe-erp-queue", "exe-erp-scheduler"],
+    origin: "askexe-release",
+    deployment: "stack",
+    ghRepo: "AskExe/exe-erp",
+    imageName: "update.askexe.com/askexe/exe-erp",
+    sourceImageName: "ghcr.io/askexe/exe-erp",
+    env: "ERP_IMAGE_TAG",
+    healthUrl: "http://127.0.0.1:8069/api/method/ping",
+    healthHost: "erp.askexe.com",
+    required: false,
+    category: "app",
+    description: "Enterprise resource planning"
+  },
+  {
+    key: "monitorHub",
+    composeServices: ["exe-monitor-hub"],
+    origin: "askexe-release",
+    deployment: "stack",
+    ghRepo: "AskExe/exe-monitor",
+    imageName: "update.askexe.com/askexe/exe-monitor-hub",
+    sourceImageName: "ghcr.io/askexe/exe-monitor-hub",
+    env: "MONITOR_HUB_IMAGE_TAG",
+    category: "monitoring"
+  },
+  {
+    key: "monitorAgent",
+    composeServices: ["exe-monitor-agent"],
+    origin: "askexe-release",
+    deployment: "stack",
+    ghRepo: "AskExe/exe-monitor",
+    imageName: "update.askexe.com/askexe/exe-monitor-agent",
+    sourceImageName: "ghcr.io/askexe/exe-monitor-agent",
+    env: "MONITOR_AGENT_IMAGE_TAG",
+    category: "monitoring"
+  },
+  {
+    key: "dashboard",
+    composeServices: ["exe-dashboard"],
+    origin: "askexe-release",
+    deployment: "stack",
+    // SOURCE IS KNOWN: exe-dashboard is built from THIS repo (AskExe/exe-os),
+    // build context dashboard-page/, by .github/workflows/dashboard-image.yml.
+    // Production's sha256:950699473914… came from exe-os commit 1d5b69cffa8d
+    // (#703, 2026-08-13), confirmed in build run 31714341386.
+    ghRepo: "AskExe/exe-os",
+    // …but it is OUTSIDE THE RELEASE LANE: that workflow pushes only
+    // `:sha-<sha>` and `:main`, sets no org.opencontainers.image.version, and
+    // neither stack.release.json nor the stack manifest mentions it. Production
+    // is three builds stale and nothing auto-deploys it.
+    releaseLane: "none",
+    imageName: "ghcr.io/askexe/exe-dashboard",
+    env: "DASHBOARD_IMAGE_TAG",
+    category: "app",
+    description: "Customer dashboard (credits, usage, keys, billing)",
+    note: "BLOCKED \u2014 NOT WIRED INTO THE RELEASE LANE (2026-08-20). Give dashboard-image.yml a versioned release tag + org.opencontainers.image.version/.revision stamps, and add it to stack.release.json, then it flows through the identical path as every other service."
+  },
+  {
+    key: "exe-build",
+    composeServices: [],
+    origin: "askexe-release",
+    // Control-plane only: exe-build was removed from the customer stack and
+    // runs on askexe-control-plane. Stated here so its absence from the
+    // customer manifest is a decision on the record, not an omission.
+    deployment: "control-plane",
+    ghRepo: "AskExe/exe-build",
+    imageName: "update.askexe.com/askexe/exe-build",
+    env: "EXE_BUILD_IMAGE_TAG",
+    category: "control-plane"
+  },
+  // ---- Upstream (third-party) artifacts ------------------------------------
+  {
+    key: "exe-db",
+    composeServices: ["exe-db", "exe-wiki-schema-guard"],
+    origin: "upstream-pinned",
+    deployment: "stack",
+    ghRepo: null,
+    imageName: "update.askexe.com/askexe/pgvector",
+    env: "EXE_DB_IMAGE",
+    pinnedImage: "update.askexe.com/askexe/pgvector:0.8.0-pg16@sha256:a132765ec351c65111b5b675928a3a0515a466a40f97277329db8b8209ad8bc9",
+    required: true,
+    category: "core",
+    description: "Postgres (pgvector)"
+  },
+  {
+    key: "gotrue",
+    composeServices: ["gotrue"],
+    origin: "upstream-pinned",
+    deployment: "stack",
+    ghRepo: null,
+    imageName: "update.askexe.com/askexe/gotrue",
+    pinnedImage: "update.askexe.com/askexe/gotrue:v2.172.1@sha256:b0dd7aa28dd1f9a8bd31f136c8b912661f701d9b863171e5843cb08f18f49de4",
+    healthUrl: "http://127.0.0.1:9999/health",
+    category: "infra"
+  },
+  {
+    key: "redis",
+    composeServices: ["redis"],
+    origin: "upstream-pinned",
+    deployment: "stack",
+    ghRepo: null,
+    imageName: "update.askexe.com/askexe/redis",
+    pinnedImage: "update.askexe.com/askexe/redis:7.4-alpine@sha256:6ab0b6e7381779332f97b8ca76193e45b0756f38d4c0dcda72dbb3c32061ab99",
+    category: "infra"
+  },
+  {
+    key: "clickhouse",
+    composeServices: ["clickhouse"],
+    origin: "upstream-pinned",
+    deployment: "stack",
+    ghRepo: null,
+    imageName: "update.askexe.com/askexe/clickhouse-server",
+    pinnedImage: "update.askexe.com/askexe/clickhouse-server:24.8.4.13-alpine@sha256:88a45f9e328549b2579256c46ee38e5c0e25ae58303d9eb6d9c7ed8d6d2bbf3c",
+    category: "infra"
+  },
+  {
+    key: "cloudflared",
+    composeServices: ["cloudflared"],
+    origin: "upstream-pinned",
+    deployment: "stack",
+    ghRepo: null,
+    imageName: "update.askexe.com/askexe/cloudflared",
+    pinnedImage: "update.askexe.com/askexe/cloudflared:2026-07@sha256:ba461b8aa9c042156dbd39c38657fe7431bafa063220eab8d5330a523863da9f",
+    category: "infra"
+  },
+  {
+    key: "exe-sso-edge",
+    composeServices: ["exe-sso-edge"],
+    origin: "upstream-pinned",
+    deployment: "stack",
+    ghRepo: null,
+    imageName: "update.askexe.com/askexe/nginx",
+    pinnedImage: "update.askexe.com/askexe/nginx:alpine@sha256:20316569d8f81a160065d7d2a5eeffc7ca97d79022462ee255fd23fa103a6b5c",
+    category: "infra"
+  },
+  {
+    key: "exe-otel-collector",
+    composeServices: ["exe-otel-collector"],
+    origin: "upstream-pinned",
+    deployment: "stack",
+    ghRepo: null,
+    imageName: "update.askexe.com/askexe/otel-collector-contrib",
+    env: "OTEL_COLLECTOR_IMAGE",
+    pinnedImage: "update.askexe.com/askexe/otel-collector-contrib:0.114.0@sha256:37fa87091cfaaec7234a27e4e395a40c31c2bfaea97a349a4afef6d9e9681197",
+    category: "infra"
+  }
+]);
+function stackServiceSpecs(specs = STACK_SERVICE_SPECS) {
+  return specs.filter((s) => s.deployment === "stack");
+}
+var DIGEST_RE = /@sha256:[0-9a-f]{64}$/i;
+function isDigestPinned(ref) {
+  return typeof ref === "string" && DIGEST_RE.test(ref.trim());
+}
+function tagOf(ref) {
+  if (typeof ref !== "string" || ref.trim() === "") return void 0;
+  const raw = ref.trim();
+  const at = raw.indexOf("@");
+  const withoutDigest = at === -1 ? raw : raw.slice(0, at);
+  const slash = withoutDigest.lastIndexOf("/");
+  const colon = withoutDigest.lastIndexOf(":");
+  if (colon <= slash) return void 0;
+  const tag = withoutDigest.slice(colon + 1);
+  return tag === "" ? void 0 : tag;
+}
+function parseVersionCore(tag) {
+  if (typeof tag !== "string") return null;
+  const stripped = tag.trim().replace(/^v/i, "");
+  if (stripped === "") return null;
+  const core = stripped.split("-")[0];
+  const parts = core.split(".");
+  const nums = [];
+  for (const p of parts) {
+    if (!/^\d+$/.test(p)) return null;
+    nums.push(Number(p));
+  }
+  return nums.length > 0 ? nums : null;
+}
+function compareVersionTags(a, b) {
+  const ca = parseVersionCore(a);
+  const cb = parseVersionCore(b);
+  if (!ca || !cb) return null;
+  const len = Math.max(ca.length, cb.length);
+  for (let i = 0; i < len; i++) {
+    const x = ca[i] ?? 0;
+    const y = cb[i] ?? 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+var REQUIRED_IMAGE_LABELS = Object.freeze([
+  "org.opencontainers.image.version",
+  "org.opencontainers.image.revision"
+]);
+function evaluateService(spec, facts = {}, options = {}) {
+  const refuse = (reason) => ({ ok: false, service: spec.key, reason });
+  const sourceName = spec.sourceImageName ?? spec.imageName;
+  const commitName = spec.commitImageName ?? sourceName;
+  if (facts.deployed?.ref) {
+    const deployedTag = tagOf(facts.deployed.ref);
+    const deployedVersion = facts.deployed.versionLabel?.trim();
+    if (!deployedTag || !deployedVersion) {
+      const missing = [
+        !deployedVersion ? "no org.opencontainers.image.version label" : null,
+        !deployedTag ? "matches no release tag (bare digest)" : null
+      ].filter(Boolean).join(" and ");
+      return refuse(
+        `deployed image ${facts.deployed.ref} has ${missing}; provenance unresolved. Trace the running image and cut a real release before ${spec.key} can be manifest-governed. Re-pinning it to a tag we cannot prove it came from would be a change of unknown scope.`
+      );
+    }
+  }
+  if (spec.origin === "upstream-pinned") {
+    if (!spec.pinnedImage) {
+      return refuse(
+        `upstream-pinned service declares no pinnedImage. Third-party artifacts are not tag-resolved, so their digest pin must be stated in STACK_SERVICE_SPECS and changed by code review.`
+      );
+    }
+    if (!isDigestPinned(spec.pinnedImage)) {
+      return refuse(
+        `upstream pin "${spec.pinnedImage}" is not digest-pinned. Tags move, digests do not \u2014 pin third-party images by @sha256 digest.`
+      );
+    }
+    const prev = facts.previousImageRef;
+    if (prev && !options.allowDowngrade?.includes(spec.key)) {
+      const cmp = compareVersionTags(tagOf(spec.pinnedImage), tagOf(prev));
+      if (cmp === -1) {
+        return refuse(
+          `DOWNGRADE REFUSED: upstream pin ${tagOf(spec.pinnedImage)} is LOWER than the currently pinned ${tagOf(prev)}. Roll third-party images backwards only with an explicit, named --allow-downgrade ${spec.key}.`
+        );
+      }
+    }
+    return { ok: true, service: spec.key, image: spec.pinnedImage, version: tagOf(spec.pinnedImage) };
+  }
+  if (!spec.ghRepo) {
+    return refuse(
+      `no source repo identified \u2014 ${spec.key} is deployed from ${spec.imageName} but no repository in the AskExe org builds it. Identify (or create) the source repo and cut a tagged release. This is a block, not an exemption: the repo name must not be guessed.`
+    );
+  }
+  if (spec.releaseLane === "none") {
+    return refuse(
+      `not wired into the release lane \u2014 ${spec.ghRepo} builds ${spec.imageName}, but only as floating refs (:main / :sha-<sha>) with no version stamp, and no release descriptor references it. There is no released artifact to pin. Give its workflow a versioned tag plus org.opencontainers.image.version/.revision stamps and add it to the release descriptor.`
+    );
+  }
+  if (!facts.latestTag) {
+    return refuse(
+      `no release tag found for ${spec.ghRepo}. The manifest pins released versions only \u2014 tag a release before this service can be manifest-governed.`
+    );
+  }
+  if (!facts.tagCommit) {
+    return refuse(
+      `could not resolve ${spec.ghRepo}@${facts.latestTag} to a commit. Provenance is anchored to the COMMIT a tag names, never to the tag string, so an unresolvable tag cannot be pinned.`
+    );
+  }
+  const resolvedDigest = facts.digestByCommit ?? facts.digestByTag;
+  if (!resolvedDigest || !/^sha256:[0-9a-f]{64}$/i.test(resolvedDigest)) {
+    return refuse(
+      `no resolvable image for release ${facts.latestTag}: neither ${commitName}:sha-${facts.tagCommit} (commit-addressed) nor ${sourceName}:${facts.latestTag} could be resolved to a digest. A release with no artifact cannot be deployed \u2014 fix the release workflow rather than hand-pinning an older image.`
+    );
+  }
+  if (facts.digestByTag && facts.digestByCommit && facts.digestByTag.toLowerCase() !== facts.digestByCommit.toLowerCase()) {
+    return refuse(
+      `TAG/COMMIT MISMATCH: the image tagged ${facts.latestTag} is ${facts.digestByTag}, but the image built from the commit that tag names (${facts.tagCommit}) is ${facts.digestByCommit}. The image called ${facts.latestTag} was not built from the commit called ${facts.latestTag}. A version tag in this registry is not provenance \u2014 refusing to pin either until the release workflow is fixed so the two agree.`
+    );
+  }
+  const missingLabels = REQUIRED_IMAGE_LABELS.filter((l) => !facts.labels?.[l]?.trim());
+  if (missingLabels.length > 0) {
+    return refuse(
+      `image ${sourceName}@${resolvedDigest} is missing ${missingLabels.join(" and ")}. An unlabelled image is an unreproducible build \u2014 it cannot prove which source it was built from.`
+    );
+  }
+  const norm = (v) => (v ?? "").trim().toLowerCase();
+  const claimed = norm(facts.imageCommit);
+  const expected = norm(facts.tagCommit);
+  const prefixLen = Math.min(claimed.length, expected.length);
+  if (!claimed || prefixLen < 7 || claimed.slice(0, prefixLen) !== expected.slice(0, prefixLen)) {
+    return refuse(
+      claimed ? `image ${resolvedDigest} says it was built from commit ${facts.imageCommit}, but ${facts.latestTag} is commit ${facts.tagCommit}. The artifact's own record contradicts the release it would be pinned as.` : `image ${resolvedDigest} carries no source-commit label, so nothing corroborates that it was built from ${facts.tagCommit}. Unverified provenance fails closed.`
+    );
+  }
+  if (facts.commitIsAncestorOfTag !== true) {
+    return refuse(
+      facts.commitIsAncestorOfTag === false ? `commit ${facts.tagCommit} is NOT an ancestor of ${spec.ghRepo}@${facts.latestTag} \u2014 the image was built from code outside that release's history.` : `could not verify that commit ${facts.tagCommit} is an ancestor of ${spec.ghRepo}@${facts.latestTag}. An unverifiable ancestry is not a passing ancestry \u2014 fail closed.`
+    );
+  }
+  const image = `${spec.imageName}:${facts.latestTag}@${resolvedDigest}`;
+  if (facts.previousImageRef && !options.allowDowngrade?.includes(spec.key)) {
+    const previousTag = tagOf(facts.previousImageRef);
+    const cmp = compareVersionTags(facts.latestTag, previousTag);
+    if (cmp === -1) {
+      return refuse(
+        `DOWNGRADE REFUSED: candidate ${facts.latestTag} is LOWER than the currently pinned ${previousTag}. Applying it would roll ${spec.key} backwards. If that is genuinely intended, re-run with an explicit --allow-downgrade ${spec.key}.`
+      );
+    }
+    if (cmp === null) {
+      return refuse(
+        `cannot order candidate ${facts.latestTag} against the currently pinned ${previousTag ?? "(untagged)"}, so a downgrade cannot be ruled out. Fail-closed: re-run with --allow-downgrade ${spec.key} only after confirming by hand that this is a roll-forward.`
+      );
+    }
+  }
+  return {
+    ok: true,
+    service: spec.key,
+    image,
+    version: facts.labels?.["org.opencontainers.image.version"],
+    revision: facts.labels?.["org.opencontainers.image.revision"]
+  };
+}
+var ManifestGenerationRefused = class extends Error {
+  refusals;
+  constructor(refusals) {
+    super(
+      `Manifest generation REFUSED \u2014 ${refusals.length} service(s) failed the fail-closed guards. No manifest was written (a partial manifest is never emitted):
+` + refusals.map((r) => `  \u2717 ${r.service}: ${r.reason}`).join("\n")
+    );
+    this.name = "ManifestGenerationRefused";
+    this.refusals = refusals;
+  }
+};
+function generateStackServices(specs, factsByKey, options = {}) {
+  const services = {};
+  const resolved = [];
+  const refusals = [];
+  for (const spec of stackServiceSpecs(specs)) {
+    const verdict = evaluateService(spec, factsByKey[spec.key] ?? {}, options);
+    if (!verdict.ok) {
+      refusals.push({ service: verdict.service, reason: verdict.reason });
+      continue;
+    }
+    const entry = { image: verdict.image };
+    if (spec.env) entry.env = spec.env;
+    if (spec.composeServices[0]) entry.composeService = spec.composeServices[0];
+    if (spec.healthUrl) entry.healthUrl = spec.healthUrl;
+    if (spec.healthHost) entry.healthHost = spec.healthHost;
+    if (spec.required !== void 0) entry.required = spec.required;
+    if (spec.category) entry.category = spec.category;
+    if (spec.description) entry.description = spec.description;
+    if (verdict.revision) entry.gitSha = verdict.revision;
+    services[spec.key] = entry;
+    resolved.push({ service: spec.key, image: verdict.image });
+  }
+  if (refusals.length > 0) throw new ManifestGenerationRefused(refusals);
+  return { services, resolved };
+}
+function extractComposeImagePins(composeYaml) {
+  const lines = composeYaml.split("\n");
+  const pins = [];
+  let inServices = false;
+  let current;
+  for (const line of lines) {
+    if (/^services:\s*$/.test(line)) {
+      inServices = true;
+      continue;
+    }
+    if (/^[a-zA-Z_-]+:\s*$/.test(line)) {
+      inServices = /^services:/.test(line);
+      current = void 0;
+      continue;
+    }
+    if (!inServices) continue;
+    const svc = line.match(/^ {2}([A-Za-z0-9._-]+):\s*$/);
+    if (svc) {
+      current = svc[1];
+      continue;
+    }
+    const img = line.match(/^\s+image:\s*(.+?)\s*$/);
+    if (img && current) {
+      const raw = img[1];
+      const envMatch = raw.match(/\$\{([A-Za-z_][A-Za-z0-9_]*)/);
+      pins.push({ service: current, envVar: envMatch?.[1], raw });
+    }
+  }
+  return pins;
+}
+function assertServiceCoverage(pins, specs = STACK_SERVICE_SPECS) {
+  const byComposeService = /* @__PURE__ */ new Set();
+  const byEnv = /* @__PURE__ */ new Set();
+  for (const spec of specs) {
+    for (const cs of spec.composeServices) byComposeService.add(cs);
+    if (spec.env) byEnv.add(spec.env);
+  }
+  const gaps = [];
+  for (const pin of pins) {
+    if (/^\$\{[A-Za-z_][A-Za-z0-9_]*:-\}$/.test(pin.raw.trim())) continue;
+    const covered = byComposeService.has(pin.service) || pin.envVar !== void 0 && byEnv.has(pin.envVar);
+    if (!covered) {
+      gaps.push({
+        service: pin.service,
+        envVar: pin.envVar,
+        reason: `compose deploys an image for "${pin.service}"${pin.envVar ? ` (pinned by ${pin.envVar})` : ""} but no STACK_SERVICE_SPECS entry governs it`
+      });
+    }
+  }
+  if (gaps.length > 0) {
+    throw new Error(
+      `Stack manifest coverage GAP \u2014 ${gaps.length} deployed service(s) are not manifest-governed. A manifest that silently omits a running service is the exact failure mode being eliminated. Add an entry to STACK_SERVICE_SPECS for each:
+` + gaps.map((g) => `  \u2717 ${g.reason}`).join("\n")
+    );
+  }
+}
+function nextStackVersion(latest) {
+  const parts = latest.split(".").map((p) => Number(p));
+  if (parts.length !== 3 || parts.some((n) => !Number.isFinite(n))) {
+    throw new Error(`Cannot derive the next stack version from latest="${latest}" (expected x.y.z).`);
+  }
+  return `${parts[0]}.${parts[1]}.${(parts[2] ?? 0) + 1}`;
+}
+function previousImageRefs(manifest) {
+  const entry = manifest.stacks?.[manifest.latest];
+  const out = {};
+  for (const [key, svc] of Object.entries(entry?.services ?? {})) {
+    if (typeof svc?.image === "string") out[key] = svc.image;
+  }
+  return out;
+}
+function buildStackEntry(input) {
+  return {
+    version: input.version,
+    releasedAt: input.releasedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    notes: input.notes ?? `Generated from published releases by stack-generate-manifest.`,
+    ...input.npmVersion ? { npmVersion: input.npmVersion } : {},
+    breakingChanges: [],
+    services: input.services,
+    rolloutStage: input.canary ? "canary" : "ga"
+  };
+}
+
+// src/bin/stack-generate-manifest.ts
+var execFile = promisify(execFileCb);
+function repoRoot() {
+  let dir = path.dirname(new URL(import.meta.url).pathname);
+  for (let i = 0; i < 6; i++) {
+    if (existsSync(path.join(dir, "deploy", "stack-manifests", "v0.9.json"))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+function parseGenerateArgs(argv, root = repoRoot()) {
+  const opts = {
+    manifestPath: path.join(root, "deploy", "stack-manifests", "v0.9.json"),
+    composePath: path.join(root, "deploy", "compose", "docker-compose.yml"),
+    allowDowngrade: [],
+    canary: false,
+    dryRun: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const take = () => argv[++i] ?? "";
+    if (arg === "--manifest") opts.manifestPath = take();
+    else if (arg === "--compose") opts.composePath = take();
+    else if (arg === "--stack-version") opts.stackVersion = take();
+    else if (arg === "--allow-downgrade") opts.allowDowngrade.push(take());
+    else if (arg.startsWith("--allow-downgrade=")) opts.allowDowngrade.push(arg.slice("--allow-downgrade=".length));
+    else if (arg === "--deployed-state") opts.deployedStatePath = take();
+    else if (arg === "--notes") opts.notes = take();
+    else if (arg === "--canary") opts.canary = true;
+    else if (arg === "--dry-run") opts.dryRun = true;
+  }
+  return opts;
+}
+async function run(cmd, args) {
+  try {
+    const { stdout } = await execFile(cmd, args, { maxBuffer: 16 * 1024 * 1024 });
+    return { ok: true, stdout: stdout.toString().trim() };
+  } catch {
+    return { ok: false, stdout: "" };
+  }
+}
+var MAX_TAG_PROBES = 50;
+async function tagCreatorEmail(ghRepo, tag) {
+  const ref = await run("gh", [
+    "api",
+    `repos/${ghRepo}/git/refs/tags/${tag}`,
+    "--jq",
+    ".object.sha,.object.type"
+  ]);
+  if (!ref.ok) return void 0;
+  const [sha, type] = ref.stdout.split("\n").map((v) => v.trim());
+  if (!sha) return void 0;
+  const res = type === "tag" ? await run("gh", ["api", `repos/${ghRepo}/git/tags/${sha}`, "--jq", ".tagger.email"]) : await run("gh", ["api", `repos/${ghRepo}/git/commits/${sha}`, "--jq", ".author.email"]);
+  return res.ok && res.stdout.trim() !== "" ? res.stdout.trim() : void 0;
+}
+async function fetchLatestTag(ghRepo) {
+  const { inReleaseNamespace, isOurIdentity } = await import("./ref-provenance-gate-M4AQO4OT.js");
+  const res = await run("gh", [
+    "api",
+    `repos/${ghRepo}/git/refs/tags`,
+    "--paginate",
+    "--jq",
+    ".[].ref"
+  ]);
+  if (!res.ok) return void 0;
+  const candidates = res.stdout.split("\n").map((r) => r.trim().replace(/^refs\/tags\//, "")).filter((t) => t !== "" && inReleaseNamespace(t) && !t.startsWith("stack-v")).sort((a, b) => compareVersionTags(a, b) ?? 0).reverse();
+  for (const tag of candidates.slice(0, MAX_TAG_PROBES)) {
+    if (isOurIdentity(await tagCreatorEmail(ghRepo, tag))) return tag;
+  }
+  return void 0;
+}
+async function resolveTagCommit(ghRepo, tag) {
+  const res = await run("gh", [
+    "api",
+    `repos/${ghRepo}/git/refs/tags/${tag}`,
+    "--jq",
+    ".object.sha,.object.type"
+  ]);
+  if (!res.ok) return void 0;
+  const [sha, type] = res.stdout.split("\n").map((v) => v.trim());
+  if (!sha) return void 0;
+  if (type !== "tag") return sha;
+  const deref = await run("gh", ["api", `repos/${ghRepo}/git/tags/${sha}`, "--jq", ".object.sha"]);
+  return deref.ok && deref.stdout.trim() !== "" ? deref.stdout.trim() : void 0;
+}
+async function commitIsAncestorOfTag(ghRepo, commit, tag) {
+  const res = await run("gh", [
+    "api",
+    `repos/${ghRepo}/compare/${tag}...${commit}`,
+    "--jq",
+    ".status"
+  ]);
+  if (!res.ok) return void 0;
+  const status = res.stdout.trim();
+  if (status === "identical" || status === "behind") return true;
+  if (status === "ahead" || status === "diverged") return false;
+  return void 0;
+}
+async function resolveImageDigest(ref) {
+  const res = await run("docker", ["buildx", "imagetools", "inspect", ref]);
+  if (!res.ok) return void 0;
+  const match = res.stdout.match(/^\s*Digest:\s*(sha256:[0-9a-f]{64})\s*$/m);
+  return match?.[1];
+}
+async function readProvenanceLabels(ref) {
+  const { resolveImageLabels } = await import("./resolve-image-labels-ZI6UBW5W.js");
+  return resolveImageLabels(ref, [
+    "org.opencontainers.image.version",
+    "org.opencontainers.image.revision",
+    "org.exe.git_sha"
+  ]);
+}
+function loadDeployedState(filePath) {
+  if (!filePath) return {};
+  if (!existsSync(filePath)) {
+    throw new Error(`--deployed-state file not found: ${filePath}`);
+  }
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+async function gatherFacts(spec, previous, deployed) {
+  const facts = {
+    previousImageRef: previous[spec.key],
+    deployed: deployed[spec.key]
+  };
+  if (spec.origin === "upstream-pinned" || !spec.ghRepo || spec.releaseLane === "none") return facts;
+  facts.latestTag = await fetchLatestTag(spec.ghRepo);
+  if (!facts.latestTag) return facts;
+  facts.tagCommit = await resolveTagCommit(spec.ghRepo, facts.latestTag);
+  if (!facts.tagCommit) return facts;
+  const source = spec.sourceImageName ?? spec.imageName;
+  const commitSource = spec.commitImageName ?? source;
+  facts.digestByCommit = await resolveImageDigest(`${commitSource}:sha-${facts.tagCommit}`);
+  facts.digestByTag = await resolveImageDigest(`${source}:${facts.latestTag}`);
+  const resolved = facts.digestByCommit ?? facts.digestByTag;
+  if (!resolved) return facts;
+  facts.labels = await readProvenanceLabels(
+    `${facts.digestByCommit ? commitSource : source}@${resolved}`
+  );
+  facts.imageCommit = facts.labels["org.exe.git_sha"] ?? facts.labels["org.opencontainers.image.revision"];
+  facts.commitIsAncestorOfTag = await commitIsAncestorOfTag(
+    spec.ghRepo,
+    facts.tagCommit,
+    facts.latestTag
+  );
+  return facts;
+}
+function printUsage() {
+  console.log(`
+Usage: exe-os stack-generate-manifest [options]
+
+Generate the stack manifest from each repo's latest PUBLISHED release. The
+manifest is the single source of truth: the VPS and the live site pull only
+from it, .env is derived from it, and compose carries no fallback defaults.
+
+Options:
+  --manifest <path>          Manifest to update (default deploy/stack-manifests/v0.9.json)
+  --compose <path>           Compose file whose deployed surface must be fully covered
+  --stack-version <x.y.z>    Version for the new entry (default: patch-bump of latest)
+  --deployed-state <path>    JSON snapshot of what production runs (enables the
+                             deployed-provenance guard)
+  --allow-downgrade <svc>    Explicitly permit ONE named service to move backwards.
+                             Repeatable. The only override \u2014 it cannot manufacture
+                             provenance for a missing repo, label, or digest.
+  --notes <text>             Release notes for the entry
+  --canary                   Publish without bumping manifest.latest
+  --dry-run                  Resolve and report; write nothing
+  --help                     Show this message
+
+FAIL-CLOSED: the run REFUSES (and writes nothing) when a repo has no published
+release, a release has no published image, a digest cannot be resolved, an image
+lacks org.opencontainers.image.version/.revision, a candidate is LOWER than the
+current pin, or compose deploys a service the roster does not govern.
+`);
+}
+async function runStackGenerateManifestCli(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printUsage();
+    return 0;
+  }
+  const opts = parseGenerateArgs(argv);
+  if (!existsSync(opts.manifestPath)) {
+    console.error(`[stack-generate-manifest] Manifest not found: ${opts.manifestPath}`);
+    return 1;
+  }
+  const manifest = JSON.parse(readFileSync(opts.manifestPath, "utf8"));
+  if (existsSync(opts.composePath)) {
+    try {
+      assertServiceCoverage(extractComposeImagePins(readFileSync(opts.composePath, "utf8")));
+    } catch (err) {
+      console.error(`[stack-generate-manifest] ${err instanceof Error ? err.message : String(err)}`);
+      return 1;
+    }
+  } else {
+    console.warn(`[stack-generate-manifest] compose file not found (${opts.composePath}) \u2014 coverage NOT verified.`);
+  }
+  const previous = previousImageRefs(manifest);
+  let deployed;
+  try {
+    deployed = loadDeployedState(opts.deployedStatePath);
+  } catch (err) {
+    console.error(`[stack-generate-manifest] ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  const specs = stackServiceSpecs(STACK_SERVICE_SPECS);
+  const factsByKey = {};
+  for (const spec of specs) {
+    process.stderr.write(`[stack-generate-manifest] resolving ${spec.key}\u2026
+`);
+    factsByKey[spec.key] = await gatherFacts(spec, previous, deployed);
+  }
+  let services;
+  let resolved;
+  try {
+    ({ services, resolved } = generateStackServices(specs, factsByKey, {
+      allowDowngrade: opts.allowDowngrade
+    }));
+  } catch (err) {
+    if (err instanceof ManifestGenerationRefused) {
+      console.error(`
+[stack-generate-manifest] ${err.message}
+`);
+      console.error(
+        `[stack-generate-manifest] Nothing was written. Fix the provenance above (or, for a genuine roll-back only, re-run with an explicit --allow-downgrade <service>).`
+      );
+      return 1;
+    }
+    throw err;
+  }
+  const version = opts.stackVersion ?? nextStackVersion(manifest.latest);
+  const entry = buildStackEntry({
+    version,
+    services,
+    notes: opts.notes,
+    npmVersion: readNpmVersion(),
+    canary: opts.canary
+  });
+  console.log(`
+[stack-generate-manifest] Resolved ${resolved.length} service(s) for stack ${version}:`);
+  for (const r of resolved) console.log(`  \u2713 ${r.service.padEnd(20)} ${r.image}`);
+  if (opts.dryRun) {
+    console.log(`
+[stack-generate-manifest] --dry-run: nothing written.`);
+    return 0;
+  }
+  manifest.stacks[version] = entry;
+  if (!opts.canary) manifest.latest = version;
+  writeSignedStackManifest(opts.manifestPath, manifest);
+  console.log(
+    `
+[stack-generate-manifest] \u2713 Wrote stack ${version}${opts.canary ? " (CANARY \u2014 latest unchanged)" : ` (latest -> ${version})`} to ${opts.manifestPath}`
+  );
+  return 0;
+}
+function readNpmVersion() {
+  const pkgPath = path.join(repoRoot(), "package.json");
+  if (!existsSync(pkgPath)) return void 0;
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  return pkg.version;
+}
+if (isMainModule(import.meta.url) && process.argv[1]?.includes("stack-generate-manifest")) {
+  runStackGenerateManifestCli(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  }).catch((err) => {
+    console.error(`[stack-generate-manifest] Fatal: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
+  });
+}
+export {
+  commitIsAncestorOfTag,
+  fetchLatestTag,
+  gatherFacts,
+  loadDeployedState,
+  parseGenerateArgs,
+  readProvenanceLabels,
+  resolveImageDigest,
+  resolveTagCommit,
+  runStackGenerateManifestCli
+};