fix: base Git multi-file Compose deploy env and dossier on the effective config (#1391)

* fix: resolve the root .env at deploy and render time for Git context-dir stacks

A Git multi-file source with a context dir set --project-directory to that
dir, so Docker Compose looked for .env there and missed the root .env Sencho
writes. Validation already passed the root .env with --env-file, so a stack
could validate with one effective config but deploy or render another.

Add authoredComposeEnvFileArgs, which appends --env-file <stackDir>/.env when
the applied deploy spec has a context dir and a root .env exists, and wire it
into the deploy/update, image-scan, render, and container-listing compose
invocations so they all resolve env from the same file the validator used. A
non-ENOENT access error surfaces instead of silently dropping the flag.

* fix: base multi-file Git dossier and doc-drift on the effective Compose model

The Stack Dossier and its documentation-drift check parsed only the stored root
compose file. For a multi-file Git source, services, ports, networks, or volumes
that an override file adds were invisible, so the dossier showed incomplete facts
and doc-drift could falsely warn that a documented port is unpublished when an
override actually publishes it.

Add a secret-safe GET /stacks/:name/effective-anatomy that renders the merged
effective model and extracts only structural facts (services, ports, volumes,
networks, restart), never env, label, or command values. StackAnatomyPanel
fetches it for multi-file Git stacks and feeds those facts into the dossier and
doc-drift, falling back to the root-only parse for single-file or non-git stacks
and whenever the render is unavailable.

* fix: add an inline path-injection barrier to the Git env-file resolver

CodeQL js/path-injection flagged the fs.access in authoredComposeEnvFileArgs
because the env path derives from the route-supplied stack name and the only
containment check lived in the callers, not at the sink. Resolve the stack dir
against the compose base and assert containment with startsWith inline, then
derive the .env path from the validated dir, mirroring the existing inline guards
in renderConfig and validateCompose. Valid stack names are unaffected; a name
that escapes the base now yields no --env-file.

* test: stabilize the dossier doc-drift e2e against the dossier-load race

The first assertion filled the access_urls field as soon as the Dossier panel
was visible, but the panel's GET /stacks/:name/dossier resolves by overwriting
the fields from the server (empty access_urls) and only then flips the doc-drift
gate on. When the GET landed after the fill, it clobbered the typed value and the
warning never rendered, so the test failed intermittently under CI timing. Wait
for that GET to land before typing, mirroring the spec's openStack helper.

backend/src/services/ComposeService.ts

@@ -16,7 +16,7 @@ import { isDebugEnabled } from '../utils/debug';
 import { getErrorMessage } from '../utils/errors';
 import { describeSpawnError } from '../utils/spawnErrors';
 import { isPathWithinBase, isValidStackName } from '../utils/validation';
-import { authoredComposeFileArgs } from '../utils/authoredComposeArgs';
+import { authoredComposeFileArgs, authoredComposeEnvFileArgs } from '../utils/authoredComposeArgs';
 import { redactSensitiveText, sanitizeForLog } from '../utils/safeLog';
 
 export class ComposeRollbackError extends Error {
@@ -104,6 +104,9 @@ export class ComposeService {
     const args: string[] = ['compose'];
     const filePrefix = authoredComposeFileArgs(stackName, this.nodeId);
     args.push(...filePrefix);
+    // Pin env resolution to the root .env when a context dir shifts the project
+    // directory, so deploy/update resolve the same effective config the validator did.
+    args.push(...await authoredComposeEnvFileArgs(stackName, this.nodeId));
 
     let overridePath: string | null = null;
     try {
@@ -653,7 +656,8 @@ export class ComposeService {
     // Use the authored multi-file model (no mesh override) so override-only image
     // refs are scanned by the policy gate; single-file stacks get an empty prefix.
     const filePrefix = authoredComposeFileArgs(stackName, this.nodeId);
-    const stdout = await this.captureCompose([...filePrefix, 'config', '--images'], stackDir);
+    const envFileArgs = await authoredComposeEnvFileArgs(stackName, this.nodeId);
+    const stdout = await this.captureCompose([...filePrefix, ...envFileArgs, 'config', '--images'], stackDir);
     const seen = new Set<string>();
     const images: string[] = [];
     for (const raw of stdout.split(/\r?\n/)) {
@@ -708,11 +712,11 @@ export class ComposeService {
    * finding rather than an exception. Bounded by a timeout and an output cap.
    * Rejects only when the docker binary cannot be spawned.
    */
-  public renderConfig(
+  public async renderConfig(
     stackName: string,
   ): Promise<{ rendered: string | null; stderr: string; code: number | null; timedOut: boolean }> {
     if (!isValidStackName(stackName)) {
-      return Promise.reject(new Error('Invalid stack path'));
+      throw new Error('Invalid stack path');
     }
     // Canonical inline js/path-injection barrier, kept in the same scope as the
     // spawn cwd sink below. CodeQL credits neither the wrapped isPathWithinBase
@@ -722,17 +726,19 @@ export class ComposeService {
     const baseResolved = path.resolve(this.baseDir);
     const stackDir = path.resolve(baseResolved, stackName);
     if (!stackDir.startsWith(baseResolved + path.sep)) {
-      return Promise.reject(new Error('Invalid stack path'));
+      throw new Error('Invalid stack path');
     }
     // Render the authored multi-file model (no mesh override) so the Compose Doctor
-    // sees every override file; single-file stacks get an empty prefix.
+    // sees every override file; single-file stacks get an empty prefix. The env-file
+    // flag keeps render resolving the same root .env the validator and deploy use.
     let filePrefix: string[];
     try {
       filePrefix = authoredComposeFileArgs(stackName, this.nodeId);
     } catch (err) {
-      return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+      throw err instanceof Error ? err : new Error(String(err));
     }
-    const child = spawn('docker', ['compose', ...filePrefix, 'config', '--format', 'json'], {
+    const envFileArgs = await authoredComposeEnvFileArgs(stackName, this.nodeId);
+    const child = spawn('docker', ['compose', ...filePrefix, ...envFileArgs, 'config', '--format', 'json'], {
       cwd: stackDir,
       env: {
         ...process.env,

backend/src/services/DockerController.ts

@@ -13,7 +13,7 @@ import { isPathWithinBase } from '../utils/validation';
 import { isDebugEnabled } from '../utils/debug';
 import { sanitizeForLog } from '../utils/safeLog';
 import { describeSpawnError } from '../utils/spawnErrors';
-import { authoredComposeFileArgs } from '../utils/authoredComposeArgs';
+import { authoredComposeFileArgs, authoredComposeEnvFileArgs } from '../utils/authoredComposeArgs';
 
 const execFileAsync = promisify(execFile);
 const COMPOSE_DIR = process.env.COMPOSE_DIR || '/app/compose';
@@ -1289,9 +1289,10 @@ class DockerController {
       // empty prefix and behave exactly as before. execFile avoids shell quoting on
       // the absolute --project-directory path.
       const filePrefix = authoredComposeFileArgs(stackName, this.nodeId);
+      const envFileArgs = await authoredComposeEnvFileArgs(stackName, this.nodeId);
       const { stdout, stderr } = await execFileAsync(
         'docker',
-        ['compose', ...filePrefix, 'ps', '--format', 'json', '-a'],
+        ['compose', ...filePrefix, ...envFileArgs, 'ps', '--format', 'json', '-a'],
         {
           cwd: stackDir,
           env: {

backend/src/services/effectiveAnatomy.ts

@@ -0,0 +1,183 @@
+/**
+ * Effective Stack Anatomy: the structural facts a stack's Dossier and doc-drift
+ * read, derived from the FULLY-MERGED effective model (`docker compose config
+ * --format json`) instead of a single compose file. For a multi-file Git source,
+ * a service, port, network, or volume that only an override file adds is invisible
+ * to a root-only parse, so the dossier and its doc-drift would show misleading
+ * facts. Rendering the merged model and extracting the same anatomy shape keeps
+ * those signals honest.
+ *
+ * Secret-safe by construction: the extractor reads only structural fields
+ * (service keys, ports, volumes, restart, network keys). It never reads
+ * `environment`, `command`, `entrypoint`, `labels`, `secrets`, or `configs`, so a
+ * resolved secret VALUE in the rendered model can never reach this payload.
+ */
+import { ComposeService } from './ComposeService';
+import { parseMissingRequiredVars } from './ComposeDoctorService';
+import { getErrorMessage } from '../utils/errors';
+import { redactSensitiveText, sanitizeForLog } from '../utils/safeLog';
+
+const MAX_RENDER_ERROR = 600;
+
+export interface EffectiveAnatomyPort {
+  host: string;
+  container: string;
+  proto: string;
+  published: boolean;
+}
+
+export interface EffectiveAnatomyVolume {
+  host: string;
+  container: string;
+}
+
+export interface EffectiveAnatomy {
+  services: string[];
+  ports: Record<string, EffectiveAnatomyPort[]>;
+  volumes: Record<string, EffectiveAnatomyVolume[]>;
+  restart: string | null;
+  networks: string[];
+}
+
+export interface EffectiveAnatomyResult extends EffectiveAnatomy {
+  /** True when the merged model rendered; false leaves every fact list empty. */
+  renderable: boolean;
+  /** A redacted, secret-safe reason when the render failed, else null. */
+  renderError: string | null;
+}
+
+const EMPTY: EffectiveAnatomy = { services: [], ports: {}, volumes: {}, restart: null, networks: [] };
+
+function asString(v: unknown): string | undefined {
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number') return String(v);
+  return undefined;
+}
+
+/** Parse one rendered `ports:` entry (long object form, with a short-string fallback). */
+function parsePort(entry: unknown): EffectiveAnatomyPort | null {
+  if (entry && typeof entry === 'object') {
+    const o = entry as Record<string, unknown>;
+    const host = asString(o.published) ?? '';
+    const container = asString(o.target) ?? '';
+    const proto = asString(o.protocol) ?? 'tcp';
+    if (host === '' && container === '') return null;
+    return { host, container, proto, published: host !== '' };
+  }
+  const s = asString(entry);
+  if (s === undefined) return null;
+  const protoMatch = s.match(/\/(tcp|udp)$/i);
+  const proto = protoMatch ? protoMatch[1].toLowerCase() : 'tcp';
+  const body = s.replace(/\/(tcp|udp)$/i, '');
+  const parts = body.split(':');
+  if (parts.length === 2) return { host: parts[0], container: parts[1], proto, published: true };
+  if (parts.length === 3) return { host: parts[1], container: parts[2], proto, published: true };
+  return { host: '', container: body, proto, published: false };
+}
+
+/** Parse one rendered `volumes:` entry (long object form, with a short-string fallback). */
+function parseVolume(entry: unknown): EffectiveAnatomyVolume | null {
+  if (entry && typeof entry === 'object') {
+    const o = entry as Record<string, unknown>;
+    const host = asString(o.source);
+    const container = asString(o.target);
+    if (host && container) return { host, container };
+    return null;
+  }
+  const s = asString(entry);
+  if (s === undefined) return null;
+  const parts = s.split(':');
+  if (parts.length >= 2) return { host: parts[0], container: parts[1] };
+  return null;
+}
+
+function networkKeys(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.map(asString).filter((s): s is string => s !== undefined);
+  }
+  if (value && typeof value === 'object') return Object.keys(value as Record<string, unknown>);
+  return [];
+}
+
+/**
+ * Map parsed `docker compose config --format json` to the {@link EffectiveAnatomy}
+ * shape. Tolerant of missing fields; empty / garbage input yields an empty model
+ * rather than throwing. Mirrors the frontend `parseAnatomy` field handling so the
+ * dossier reads the same facts whether they came from a single file or the merge.
+ */
+export function parseEffectiveAnatomy(parsed: unknown): EffectiveAnatomy {
+  if (!parsed || typeof parsed !== 'object') return { ...EMPTY };
+  const root = parsed as Record<string, unknown>;
+  const servicesObj = (root.services && typeof root.services === 'object' && !Array.isArray(root.services))
+    ? root.services as Record<string, unknown>
+    : {};
+  const serviceNames = Object.keys(servicesObj);
+
+  const ports: Record<string, EffectiveAnatomyPort[]> = {};
+  const volumes: Record<string, EffectiveAnatomyVolume[]> = {};
+  let restart: string | null = null;
+  const networks = new Set<string>();
+
+  for (const name of serviceNames) {
+    const svc = servicesObj[name];
+    if (!svc || typeof svc !== 'object') continue;
+    const o = svc as Record<string, unknown>;
+
+    const p = Array.isArray(o.ports)
+      ? o.ports.map(parsePort).filter((r): r is EffectiveAnatomyPort => r !== null)
+      : [];
+    const v = Array.isArray(o.volumes)
+      ? o.volumes.map(parseVolume).filter((r): r is EffectiveAnatomyVolume => r !== null)
+      : [];
+    if (p.length) ports[name] = p;
+    if (v.length) volumes[name] = v;
+    if (restart === null && typeof o.restart === 'string') restart = o.restart;
+    for (const n of networkKeys(o.networks)) networks.add(n);
+  }
+
+  if (root.networks && typeof root.networks === 'object' && !Array.isArray(root.networks)) {
+    for (const n of Object.keys(root.networks as Record<string, unknown>)) networks.add(n);
+  }
+
+  return { services: serviceNames, ports, volumes, restart, networks: Array.from(networks) };
+}
+
+/**
+ * Render the merged effective model for a stack and extract its anatomy facts.
+ * Mirrors the Network Inspector's render-error handling: a missing required
+ * variable, an unparseable model, or an unavailable docker binary becomes a
+ * redacted `renderError` with empty facts, never raw stderr or an exception, so
+ * the dossier can fall back to its root-only view.
+ */
+export async function buildEffectiveAnatomy(nodeId: number, stackName: string): Promise<EffectiveAnatomyResult> {
+  let renderError: string;
+  try {
+    const result = await ComposeService.getInstance(nodeId).renderConfig(stackName);
+    if (result.rendered !== null) {
+      try {
+        return { renderable: true, renderError: null, ...parseEffectiveAnatomy(JSON.parse(result.rendered)) };
+      } catch (parseErr) {
+        // JSON.parse errors carry no file content, so the message is safe to log.
+        console.warn('[EffectiveAnatomy] Effective model parse failed for %s:',
+          sanitizeForLog(stackName), sanitizeForLog(getErrorMessage(parseErr, 'unknown')));
+        renderError = 'Sencho could not parse the rendered Compose model.';
+      }
+    } else {
+      // Raw stderr can echo file content/secrets and is never surfaced; only the
+      // names of any missing required variables, otherwise a generic nudge.
+      const missing = parseMissingRequiredVars(result.stderr);
+      renderError = missing.length
+        ? `Required variable${missing.length > 1 ? 's' : ''} ${missing.join(', ')} ${missing.length > 1 ? 'have' : 'has'} no value, so the effective model cannot be rendered.`
+        : 'Sencho could not render the effective Compose model. Check the compose and env files for a YAML syntax error, an unresolved include or merge, or a required variable with no value.';
+    }
+  } catch (err) {
+    // Spawn failure (docker unavailable), or an unexpected throw before/inside the
+    // render. Leave a sanitized breadcrumb so a non-spawn bug is not invisible, then
+    // redact the surfaced message defensively.
+    console.warn('[EffectiveAnatomy] Render failed for %s:',
+      sanitizeForLog(stackName), sanitizeForLog(getErrorMessage(err, 'unknown')));
+    renderError = redactSensitiveText(getErrorMessage(err, 'docker compose could not be started.')).slice(0, MAX_RENDER_ERROR).trim()
+      || 'Sencho could not run docker compose on this node.';
+  }
+  return { renderable: false, renderError, ...EMPTY };
+}