@meshxdata/fops 0.1.52 → 0.1.54

package/src/plugins/bundled/fops-plugin-cloud/ui/src/utils/Transition.jsx

@@ -0,0 +1,116 @@
+import React, { useRef, useEffect, useContext } from 'react';
+import { CSSTransition as ReactCSSTransition } from 'react-transition-group';
+
+const TransitionContext = React.createContext({
+  parent: {},
+})
+
+function useIsInitialRender() {
+  const isInitialRender = useRef(true);
+  useEffect(() => {
+    isInitialRender.current = false;
+  }, [])
+  return isInitialRender.current;
+}
+
+function CSSTransition({
+  show,
+  enter = '',
+  enterStart = '',
+  enterEnd = '',
+  leave = '',
+  leaveStart = '',
+  leaveEnd = '',
+  appear,
+  unmountOnExit,
+  tag = 'div',
+  children,
+  ...rest
+}) {
+  const enterClasses = enter.split(' ').filter((s) => s.length);
+  const enterStartClasses = enterStart.split(' ').filter((s) => s.length);
+  const enterEndClasses = enterEnd.split(' ').filter((s) => s.length);
+  const leaveClasses = leave.split(' ').filter((s) => s.length);
+  const leaveStartClasses = leaveStart.split(' ').filter((s) => s.length);
+  const leaveEndClasses = leaveEnd.split(' ').filter((s) => s.length);
+  const removeFromDom = unmountOnExit;
+
+  function addClasses(node, classes) {
+    classes.length && node.classList.add(...classes);
+  }
+
+  function removeClasses(node, classes) {
+    classes.length && node.classList.remove(...classes);
+  }
+
+  const nodeRef = React.useRef(null);
+  const Component = tag;
+
+  return (
+    <ReactCSSTransition
+      appear={appear}
+      nodeRef={nodeRef}
+      unmountOnExit={removeFromDom}
+      in={show}
+      addEndListener={(done) => {
+        nodeRef.current.addEventListener('transitionend', done, false)
+      }}
+      onEnter={() => {
+        if (!removeFromDom) nodeRef.current.style.display = null;
+        addClasses(nodeRef.current, [...enterClasses, ...enterStartClasses])
+      }}
+      onEntering={() => {
+        removeClasses(nodeRef.current, enterStartClasses)
+        addClasses(nodeRef.current, enterEndClasses)
+      }}
+      onEntered={() => {
+        removeClasses(nodeRef.current, [...enterEndClasses, ...enterClasses])
+      }}
+      onExit={() => {
+        addClasses(nodeRef.current, [...leaveClasses, ...leaveStartClasses])
+      }}
+      onExiting={() => {
+        removeClasses(nodeRef.current, leaveStartClasses)
+        addClasses(nodeRef.current, leaveEndClasses)
+      }}
+      onExited={() => {
+        removeClasses(nodeRef.current, [...leaveEndClasses, ...leaveClasses])
+        if (!removeFromDom) nodeRef.current.style.display = 'none';
+      }}
+    >
+      <Component ref={nodeRef} {...rest} style={{ display: !removeFromDom ? 'none': null }}>{children}</Component>
+    </ReactCSSTransition>
+  )
+}
+
+function Transition({ show, appear, ...rest }) {
+  const { parent } = useContext(TransitionContext);
+  const isInitialRender = useIsInitialRender();
+  const isChild = show === undefined;
+
+  if (isChild) {
+    return (
+      <CSSTransition
+        appear={parent.appear || !parent.isInitialRender}
+        show={parent.show}
+        {...rest}
+      />
+    )
+  }
+
+  return (
+    <TransitionContext.Provider
+      value={{
+        parent: {
+          show,
+          isInitialRender,
+          appear,
+        },
+      }}
+    >
+      <CSSTransition appear={appear} show={show} {...rest} />
+    </TransitionContext.Provider>
+  )
+}
+
+export default Transition;

package/src/plugins/bundled/fops-plugin-cloud/ui/src/utils/Utils.js

@@ -0,0 +1,63 @@
+export const formatValue = (value) => Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  maximumSignificantDigits: 3,
+  notation: 'compact',
+}).format(value);
+
+export const formatThousands = (value) => Intl.NumberFormat('en-US', {
+  maximumSignificantDigits: 3,
+  notation: 'compact',
+}).format(value);
+
+export const getCssVariable = (variable) => {
+  return getComputedStyle(document.documentElement).getPropertyValue(variable).trim();
+};
+
+const adjustHexOpacity = (hexColor, opacity) => {
+  // Remove the '#' if it exists
+  hexColor = hexColor.replace('#', '');
+
+  // Convert hex to RGB
+  const r = parseInt(hexColor.substring(0, 2), 16);
+  const g = parseInt(hexColor.substring(2, 4), 16);
+  const b = parseInt(hexColor.substring(4, 6), 16);
+
+  // Return RGBA string
+  return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+};
+
+const adjustHSLOpacity = (hslColor, opacity) => {
+  // Convert HSL to HSLA
+  return hslColor.replace('hsl(', 'hsla(').replace(')', `, ${opacity})`);
+};
+
+const adjustOKLCHOpacity = (oklchColor, opacity) => {
+  // Add alpha value to OKLCH color
+  return oklchColor.replace(/oklch\((.*?)\)/, (match, p1) => `oklch(${p1} / ${opacity})`);
+};
+
+export const adjustColorOpacity = (color, opacity) => {
+  if (color.startsWith('#')) {
+    return adjustHexOpacity(color, opacity);
+  } else if (color.startsWith('hsl')) {
+    return adjustHSLOpacity(color, opacity);
+  } else if (color.startsWith('oklch')) {
+    return adjustOKLCHOpacity(color, opacity);
+  } else {
+    throw new Error('Unsupported color format');
+  }
+};
+
+export const oklchToRGBA = (oklchColor) => {
+  // Create a temporary div to use for color conversion
+  const tempDiv = document.createElement('div');
+  tempDiv.style.color = oklchColor;
+  document.body.appendChild(tempDiv);
+  
+  // Get the computed style and convert to RGB
+  const computedColor = window.getComputedStyle(tempDiv).color;
+  document.body.removeChild(tempDiv);
+  
+  return computedColor;
+};

package/src/plugins/bundled/fops-plugin-cloud/ui/vite.config.js

@@ -0,0 +1,23 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  base: "/cloud/",
+  server: {
+    port: 5174,
+    proxy: {
+      "/cloud/api": {
+        target: "http://localhost:3099",
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
+  },
+});

package/src/plugins/bundled/fops-plugin-foundation/test-helpers.js

@@ -0,0 +1,65 @@
+/**
+ * Shared test setup for Foundation plugin tool tests.
+ *
+ * Provides mockClient, vi.mock() calls, and setup() used across all
+ * per-category test files (quality, profiling, classification, etc.).
+ */
+
+import { vi } from "vitest";
+
+export const mockClient = {
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  delete: vi.fn(),
+  patch: vi.fn(),
+  deleteWithBody: vi.fn(),
+  _config: { user: "test@example.com" },
+  healthCheck: vi.fn(),
+  ensureAuth: vi.fn(),
+};
+
+vi.mock("./lib/client.js", () => ({
+  FoundationClient: vi.fn(function () { return mockClient; }),
+}));
+
+vi.mock("./lib/storage.js", () => ({
+  StorageClient: vi.fn(function () { return { healthCheck: vi.fn() }; }),
+}));
+
+vi.mock("./lib/templates.js", () => ({
+  listTemplates: vi.fn(() => []),
+  getTemplate: vi.fn(),
+  resolveBuilder: vi.fn(),
+  buildPipeline: vi.fn((opts) => ({
+    config: { docker_tag: opts.docker_tag || "0.0.1" },
+    inputs: {},
+    transformations: opts.transformations || [],
+    finalisers: { input: "step_0" },
+    preview: false,
+  })),
+  normalizeSchemaField: vi.fn((f) => f),
+  resolveSchema: vi.fn(({ fields, data_product_type }) => ({
+    details: { data_product_type: data_product_type || "user", fields },
+  })),
+}));
+
+const { register } = await import("./index.js");
+
+export function setup() {
+  const tools = {};
+  const agents = [];
+  const api = {
+    config: { user: "test@example.com" },
+    registerTool: (t) => { tools[t.name] = t; },
+    registerCommand: vi.fn(),
+    registerAgent: (a) => { agents.push(a); },
+    registerDoctorCheck: vi.fn(),
+    registerKnowledgeSource: vi.fn(),
+    registerPreflight: vi.fn(),
+    registerService: vi.fn(),
+    getService: vi.fn(),
+  };
+  register(api);
+  return { tools, agents, api };
+}

package/src/plugins/loader.js

@@ -22,6 +22,30 @@ function syncBundledPlugins() {
   const globalDir = path.join(os.homedir(), ".fops", "plugins");
   fs.mkdirSync(globalDir, { recursive: true });
 
+  // Lock to prevent concurrent sync from parallel fops processes
+  const lockFile = path.join(globalDir, ".sync.lock");
+  try {
+    fs.writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+  } catch {
+    // Lock exists — another process is syncing, skip
+    try {
+      const lockPid = parseInt(fs.readFileSync(lockFile, "utf8"));
+      const lockAge = Date.now() - fs.statSync(lockFile).mtimeMs;
+      // Stale lock (>30s), take over
+      if (lockAge > 30_000) {
+        fs.writeFileSync(lockFile, String(process.pid));
+      } else {
+        return; // Another process is actively syncing
+      }
+    } catch { return; }
+  }
+  try { _doSync(bundledDir, globalDir); } finally {
+    try { fs.unlinkSync(lockFile); } catch {}
+  }
+}
+
+function _doSync(bundledDir, globalDir) {
+
   const rootPkg = path.join(globalDir, "package.json");
   if (!fs.existsSync(rootPkg)) {
     fs.writeFileSync(rootPkg, '{ "type": "module" }\n');
@@ -49,7 +73,16 @@ function syncBundledPlugins() {
     const destDir = path.join(globalDir, entry.name);
 
     // Always overwrite — bundled plugins must stay in sync with the CLI
-    fs.cpSync(srcDir, destDir, { recursive: true });
+    try { fs.rmSync(destDir, { recursive: true, force: true }); } catch {}
+    try {
+      fs.cpSync(srcDir, destDir, { recursive: true, dereference: false, filter: (src) => {
+        // Skip node_modules to avoid broken symlinks and save time
+        return !src.includes("node_modules");
+      }});
+    } catch (cpErr) {
+      // Best-effort — skip plugins that fail to copy
+      if (process.env.DEBUG) console.error(`  Plugin sync failed for ${entry.name}: ${cpErr.message}`);
+    }
   }
 }
 

package/src/plugins/registry.js

@@ -14,6 +14,7 @@ import {
   doctorCheckSchema,
   knowledgeSourceSchema,
   preflightSchema,
+  webPanelSchema,
   mcpServerSchema,
   formatZodError,
 } from "./schemas.js";
@@ -47,6 +48,7 @@ export function createRegistry() {
     tools: [],         // { pluginId, name, description, inputSchema, execute, requiresConfirmation, annotations? }
     preflights: [],    // { pluginId, name, description, check }
     services: [],      // { pluginId, name, instance }
+    webPanels: [],     // { pluginId, name, title, prefix, distDir, apiFactory? }
     mcpConnections: [], // { name, client, transport, toolNames, status, error }
     _pendingMcpServers: [], // queued by plugins via registerMcpServer(), connected in loader
     _foundationCredentialPrompter: null,
@@ -141,6 +143,19 @@ export function createRegistry() {
       return validated;
     },
 
+    addWebPanel(panel) {
+      const validated = validate(webPanelSchema, panel, "web panel");
+      const existing = this.webPanels.find((p) => p.prefix === validated.prefix);
+      if (existing) {
+        throw new Error(
+          `Web panel prefix "${validated.prefix}" is already registered by plugin "${existing.pluginId}". ` +
+          `Plugin "${validated.pluginId}" cannot register a duplicate.`
+        );
+      }
+      this.webPanels.push(validated);
+      return validated;
+    },
+
     setFoundationCredentialPrompter(fn) {
       this._foundationCredentialPrompter = fn;
     },

package/src/plugins/schemas.js

@@ -108,6 +108,23 @@ export const preflightSchema = z.object({
   ),
 });
 
+// ── Web Panel ───────────────────────────────────────────────────────
+
+export const webPanelSchema = z.object({
+  pluginId: z.string().min(1),
+  name: z.string().min(1, "Web panel name is required"),
+  title: z.string().min(1, "Web panel title is required"),
+  prefix: z.string().min(1, "Web panel prefix is required").refine(
+    (v) => v.startsWith("/"),
+    { message: "prefix must start with /" },
+  ),
+  distDir: z.string().min(1, "Web panel distDir is required"),
+  apiFactory: z.any().refine(
+    (v) => v === undefined || v === null || typeof v === "function",
+    { message: "apiFactory must be a function or omitted" },
+  ).optional(),
+});
+
 // ── MCP Server ───────────────────────────────────────────────────────
 
 export const mcpServerSchema = z.object({

package/src/project.js

@@ -105,7 +105,7 @@ export function requireRoot(program) {
       chalk.red("Not a Foundation project (no docker-compose + Makefile).")
     );
     console.error(chalk.dim("  Run `fops init` to set up, or set FOUNDATION_ROOT."));
-    program.error({ exitCode: 1 });
+    program.error("", { exitCode: 1 });
   }
   return r;
 }

package/src/serve.js

@@ -39,6 +39,9 @@ const FOUNDATION_ENTITIES_TTL_MS = 60_000; // 1 min in-memory; file cache used f
  *   GET  /api/test/compare        Test result comparison from blob (delta, p50, p95)
  *   POST /api/fleet/scrape        Trigger immediate fleet scrape
  *   POST /api/fleet/scrape/:vm    Scrape a single VM
+ *   GET  /api/grafana/:env/prometheus   Prometheus instant query (SSH → VM:9091)
+ *   GET  /api/grafana/:env/prometheus/range  Prometheus range query
+ *   GET  /api/grafana/:env/loki     Loki log query (SSH → VM:3100)
  *   GET  /api/docs/vms            List VMs available for API docs
  *   GET  /docs                    Docs index page (HTML)
  *   GET  /docs/:vm                Swagger UI for a VM (HTML)
@@ -60,6 +63,68 @@ export function setFleetRegistry(fleet) {
 
 const COMPOSE_ROOT_DEFAULT = process.env.COMPOSE_ROOT || "/opt/foundation-compose";
 
+// ── Grafana SSH proxy helpers ─────────────────────────────────────────────────
+
+async function _resolveVm(envName) {
+  if (!_fleet) return null;
+  const vms = await _fleet._getTrackedVms();
+  return vms.find(v => v.vmName === envName) || null;
+}
+
+async function _sshCurl(envName, localUrl) {
+  const vm = await _resolveVm(envName);
+  if (!vm) return { error: `VM "${envName}" not found` };
+
+  try {
+    const { lazyExeca, sshCmd, knockForVm } = await import(
+      "./plugins/bundled/fops-plugin-azure/lib/azure.js"
+    );
+    const execa = await lazyExeca();
+    const user = vm.adminUser || "azureuser";
+    await knockForVm(vm);
+    // Encode the URL to base64 to avoid shell escaping issues with brackets, pipes, etc.
+    const b64 = Buffer.from(localUrl).toString("base64");
+    const { stdout, exitCode } = await sshCmd(
+      execa, vm.publicIp, user,
+      `curl -sf "$(echo ${b64} | base64 -d)"`,
+      30000
+    );
+    if (exitCode !== 0) return { error: `SSH curl failed (exit ${exitCode})` };
+    return JSON.parse(stdout);
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+async function _sshPromQuery(envName, query, time) {
+  const qs = new URLSearchParams({ query });
+  if (time) qs.set("time", time);
+  return _sshCurl(envName, `http://localhost:9091/api/v1/query?${qs.toString()}`);
+}
+
+async function _sshPromRangeQuery(envName, query, start, end, step) {
+  const qs = new URLSearchParams({ query, start, end, step });
+  return _sshCurl(envName, `http://localhost:9091/api/v1/query_range?${qs.toString()}`);
+}
+
+async function _sshLokiQuery(envName, query, limit, start, end) {
+  const qs = new URLSearchParams({ query, limit, start, end, direction: "backward" });
+  return _sshCurl(envName, `http://localhost:3100/loki/api/v1/query_range?${qs.toString()}`);
+}
+
+async function _sshTempoSearch(envName, serviceName, limit) {
+  const qs = new URLSearchParams({ "service.name": serviceName, limit: String(limit) });
+  return _sshCurl(envName, `http://localhost:3200/api/search?${qs.toString()}`);
+}
+
+async function _sshTempoTrace(envName, traceID) {
+  return _sshCurl(envName, `http://localhost:3200/api/traces/${traceID}`);
+}
+
+async function _sshHealthCheck(envName, port, path = "/api/ping/json") {
+  return _sshCurl(envName, `http://localhost:${port}${path}`);
+}
+
 /**
  * Start embed index in the background so query data is warm on this node (e.g. each VM's fops-api).
  * Skips when FOPS_SERVE_SKIP_EMBED_INDEX=1 or skipEmbedIndex option (e.g. when --scrape is used).
@@ -265,10 +330,12 @@ async function route(req, res, registry) {
     const { execa } = await import("execa");
     const args = command.split(/\s+/).filter(Boolean);
     try {
+      const root = process.env.FOUNDATION_ROOT || COMPOSE_ROOT_DEFAULT;
       const { stdout, stderr, exitCode } = await execa("fops", args, {
         timeout: (parsed.timeout || 300) * 1000,
         reject: false,
-        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+        cwd: root,
+        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1", FOUNDATION_ROOT: root },
       });
       json(res, 200, { command, exitCode, stdout, stderr });
     } catch (err) {
@@ -738,6 +805,105 @@ async function route(req, res, registry) {
     return;
   }
 
+  // ── Grafana proxy: SSH into VM → query Prometheus (:9091) / Loki (:3100) ──
+
+  // GET /api/grafana/:env/prometheus?query=...&time=...
+  const promMatch = method === "GET" && pathname.match(/^\/api\/grafana\/([^/]+)\/prometheus$/);
+  if (promMatch) {
+    if (!_fleet) {
+      json(res, 503, { error: "Fleet registry not active", message: "Start with: fops serve --scrape" });
+      return;
+    }
+    const envName = decodeURIComponent(promMatch[1]);
+    const query = url.searchParams.get("query");
+    if (!query) { json(res, 400, { error: "Missing ?query= parameter" }); return; }
+    const time = url.searchParams.get("time") || "";
+    const result = await _sshPromQuery(envName, query, time);
+    json(res, result.error ? 502 : 200, result);
+    return;
+  }
+
+  // GET /api/grafana/:env/prometheus/range?query=...&start=...&end=...&step=...
+  const promRangeMatch = method === "GET" && pathname.match(/^\/api\/grafana\/([^/]+)\/prometheus\/range$/);
+  if (promRangeMatch) {
+    if (!_fleet) {
+      json(res, 503, { error: "Fleet registry not active", message: "Start with: fops serve --scrape" });
+      return;
+    }
+    const envName = decodeURIComponent(promRangeMatch[1]);
+    const query = url.searchParams.get("query");
+    if (!query) { json(res, 400, { error: "Missing ?query= parameter" }); return; }
+    const start = url.searchParams.get("start") || String(Math.floor(Date.now() / 1000) - 1800);
+    const end = url.searchParams.get("end") || String(Math.floor(Date.now() / 1000));
+    const step = url.searchParams.get("step") || "60";
+    const result = await _sshPromRangeQuery(envName, query, start, end, step);
+    json(res, result.error ? 502 : 200, result);
+    return;
+  }
+
+  // GET /api/grafana/:env/loki?query=...&limit=...
+  const lokiMatch = method === "GET" && pathname.match(/^\/api\/grafana\/([^/]+)\/loki$/);
+  if (lokiMatch) {
+    if (!_fleet) {
+      json(res, 503, { error: "Fleet registry not active", message: "Start with: fops serve --scrape" });
+      return;
+    }
+    const envName = decodeURIComponent(lokiMatch[1]);
+    const query = url.searchParams.get("query");
+    if (!query) { json(res, 400, { error: "Missing ?query= parameter" }); return; }
+    const limit = url.searchParams.get("limit") || "50";
+    const start = url.searchParams.get("start") || String((Date.now() - 30 * 60 * 1000) * 1_000_000);
+    const end = url.searchParams.get("end") || String(Date.now() * 1_000_000);
+    const result = await _sshLokiQuery(envName, query, limit, start, end);
+    json(res, result.error ? 502 : 200, result);
+    return;
+  }
+
+  // GET /api/grafana/:env/tempo?service=...&limit=...
+  const tempoMatch = method === "GET" && pathname.match(/^\/api\/grafana\/([^/]+)\/tempo$/);
+  if (tempoMatch) {
+    if (!_fleet) {
+      json(res, 503, { error: "Fleet registry not active", message: "Start with: fops serve --scrape" });
+      return;
+    }
+    const envName = decodeURIComponent(tempoMatch[1]);
+    const service = url.searchParams.get("service");
+    if (!service) { json(res, 400, { error: "Missing ?service= parameter" }); return; }
+    const limit = url.searchParams.get("limit") || "10";
+    const result = await _sshTempoSearch(envName, service, limit);
+    json(res, result.error ? 502 : 200, result);
+    return;
+  }
+
+  // GET /api/grafana/:env/tempo/:traceID — get full trace detail
+  const tempoTraceMatch = method === "GET" && pathname.match(/^\/api\/grafana\/([^/]+)\/tempo\/([a-f0-9]+)$/);
+  if (tempoTraceMatch) {
+    if (!_fleet) {
+      json(res, 503, { error: "Fleet registry not active", message: "Start with: fops serve --scrape" });
+      return;
+    }
+    const envName = decodeURIComponent(tempoTraceMatch[1]);
+    const traceID = tempoTraceMatch[2];
+    const result = await _sshTempoTrace(envName, traceID);
+    json(res, result.error ? 502 : 200, result);
+    return;
+  }
+
+  // GET /api/grafana/:env/health/:port — health check a service on a VM
+  const healthMatch = method === "GET" && pathname.match(/^\/api\/grafana\/([^/]+)\/health\/(\d+)$/);
+  if (healthMatch) {
+    if (!_fleet) {
+      json(res, 503, { error: "Fleet registry not active", message: "Start with: fops serve --scrape" });
+      return;
+    }
+    const envName = decodeURIComponent(healthMatch[1]);
+    const port = healthMatch[2];
+    const healthPath = url.searchParams.get("path") || "/api/ping/json";
+    const result = await _sshHealthCheck(envName, port, healthPath);
+    json(res, result.error ? 502 : 200, result);
+    return;
+  }
+
   // GET / — Admin dashboard (only when --admin flag is set)
   if (method === "GET" && (pathname === "/" || pathname === "/index.html") && registry._adminEnabled) {
     const html = getAdminHtml();
@@ -770,6 +936,9 @@ async function route(req, res, registry) {
       "POST /api/fleet/scrape",
       "POST /api/fleet/scrape/:vm",
       "GET  /api/foundation/entities",
+      "GET  /api/grafana/:env/prometheus?query=...",
+      "GET  /api/grafana/:env/prometheus/range?query=...&start=...&end=...&step=...",
+      "GET  /api/grafana/:env/loki?query=...&limit=...",
       "GET  /api/docs/vms",
       "GET  /docs",
       "GET  /docs/:vm",
@@ -1034,7 +1203,32 @@ async function collectNodeSnapshot() {
       featureFlags,
     },
 
-    services: { backend, frontend, storage },
+    services: {
+      backend,
+      frontend,
+      storage,
+      // Extract version tags from container images for the fleet UI
+      versions: (() => {
+        const SERVICE_IMAGE_MAP = {
+          be: "foundation-backend",
+          fe: "foundation-frontend",
+          pr: "foundation-processor",
+          wa: "foundation-watcher",
+          sc: "foundation-scheduler",
+          se: "foundation-storage-engine",
+        };
+        const versions = {};
+        for (const [key, imageName] of Object.entries(SERVICE_IMAGE_MAP)) {
+          const c = containers.find((c) => c.image?.includes(imageName));
+          if (c?.image) {
+            const tag = c.image.split(":").pop() || "";
+            const sha = c.image.includes("@sha256:") ? c.image.split("@sha256:")[1]?.substring(0, 7) : null;
+            versions[key] = { tag, sha, health: c.health || c.state };
+          }
+        }
+        return versions;
+      })(),
+    },
     sessions: (() => {
       const all = listLocalSessions();
       return {

package/src/shell.js

@@ -1,9 +1,28 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
 let _execa;
 async function lazyExeca() {
   if (!_execa) _execa = (await import("execa")).execa;
   return _execa;
 }
 
+function loadVersionsEnv(root) {
+  try {
+    const content = readFileSync(join(root, ".env.versions"), "utf8");
+    const env = {};
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq > 0) env[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+    }
+    return env;
+  } catch {
+    return {};
+  }
+}
+
 export async function retry(fn, { attempts = 3, delay = 1000, onRetry } = {}) {
   let lastErr;
   for (let i = 0; i < attempts; i++) {
@@ -44,5 +63,6 @@ export async function makeNormalized(root, target, args = []) {
 
 export async function dockerCompose(root, args, { timeout } = {}) {
   const execa = await lazyExeca();
-  return execa("docker", ["compose", ...args], { cwd: root, stdio: "inherit", reject: false, ...(timeout ? { timeout } : {}) });
+  const versionsEnv = loadVersionsEnv(root);
+  return execa("docker", ["compose", ...args], { cwd: root, env: { ...process.env, ...versionsEnv }, stdio: "inherit", reject: false, ...(timeout ? { timeout } : {}) });
 }