@tdk-landscape/tdk-cli-core 1.3.50 → 1.3.52

package/engine/assets/docker/golden-layers.Dockerfile

@@ -7,7 +7,7 @@
 # 2. Or update service.json
 #
 # Generation Source: GoldenImage.generate_layered_dockerfile()
-# Service: beauty-crm-l1-l4
+# Service: tdk-project-l1-l4
 # Type: GOLDEN LAYERED IMAGES | L1-L4 Pre-built Layers
 ###############################################################################
 
@@ -15,14 +15,14 @@
 # 🏗️ GOLDEN LAYERED IMAGES - Multi-Stage Base Images
 # =============================================================================
 # This Dockerfile builds 8 golden images:
-#   - beauty-crm-l1:latest - OS base + Bun runtime
-#   - beauty-crm-l2:latest - Dependencies installed
-#   - beauty-crm-l3-backend:latest - Backend build tools (Prisma, no Infisical CLI)
-#   - beauty-crm-l3-frontend:latest - Frontend build tools (no Prisma)
-#   - beauty-crm-l3-migrator:latest - Migrator build tools (Prisma, no Infisical CLI)
-#   - beauty-crm-l4-backend:latest - Backend production runtime
-#   - beauty-crm-l4-frontend:latest - Frontend production runtime (Nginx)
-#   - beauty-crm-l4-migrator:latest - Migrator production runtime
+#   - tdk-project-l1:latest - OS base + Bun runtime
+#   - tdk-project-l2:latest - Dependencies installed
+#   - tdk-project-l3-backend:latest - Backend build tools (Prisma, no Infisical CLI)
+#   - tdk-project-l3-frontend:latest - Frontend build tools (no Prisma)
+#   - tdk-project-l3-migrator:latest - Migrator build tools (Prisma, no Infisical CLI)
+#   - tdk-project-l4-backend:latest - Backend production runtime
+#   - tdk-project-l4-frontend:latest - Frontend production runtime (Nginx)
+#   - tdk-project-l4-migrator:latest - Migrator production runtime
 #
 # Services use these as base images to skip heavy dependency installation.
 #
@@ -38,7 +38,7 @@
 # =============================================================================
 FROM oven/bun:1.3.11-alpine AS l1_golden
 
-LABEL layer="l1"       description="OS base with runtime environment"       maintainer="beauty-crm"
+LABEL layer="l1"       description="OS base with runtime environment"       maintainer="tdk-project"
 
 # System dependencies for all services
 RUN apk add --no-cache     ca-certificates     tzdata     curl     file     bash     openssl
@@ -57,7 +57,7 @@ WORKDIR /app
 # =============================================================================
 FROM l1_golden AS l2_golden
 
-LABEL layer="l2"       description="Base with common dependencies installed"       maintainer="beauty-crm"
+LABEL layer="l2"       description="Base with common dependencies installed"       maintainer="tdk-project"
 
 # Install minimal debugging tools (removed: vim, python3, make, g++ = -67MB)
 RUN apk add --no-cache     curl     netcat-openbsd     jq     bind-tools
@@ -74,7 +74,7 @@ RUN echo "Bun version: $(bun --version)"
 # =============================================================================
 FROM l2_golden AS l3_backend_golden
 
-LABEL layer="l3-backend"       description="Backend build tools with Prisma"       maintainer="beauty-crm"
+LABEL layer="l3-backend"       description="Backend build tools with Prisma"       maintainer="tdk-project"
 
 # Install Prisma CLI globally (pinned for deterministic builds)
 RUN bun add -g prisma@7.5.0 @prisma/client@7.5.0
@@ -94,7 +94,7 @@ RUN echo "Prisma version: $(bunx prisma --version | head -1)"
 # =============================================================================
 FROM l2_golden AS l3_frontend_golden
 
-LABEL layer="l3-frontend"       description="Frontend build tools without Prisma"       maintainer="beauty-crm"
+LABEL layer="l3-frontend"       description="Frontend build tools without Prisma"       maintainer="tdk-project"
 
 # Frontend doesn't need Prisma, just verify Bun
 RUN echo "Bun version: $(bun --version)"
@@ -105,7 +105,7 @@ RUN echo "Bun version: $(bun --version)"
 # =============================================================================
 FROM l2_golden AS l3_migrator_golden
 
-LABEL layer="l3-migrator"       description="Migrator build tools with Prisma"       maintainer="beauty-crm"
+LABEL layer="l3-migrator"       description="Migrator build tools with Prisma"       maintainer="tdk-project"
 
 # Install Prisma CLI globally (required for migrations, pinned)
 RUN bun add -g prisma@7.5.0 @prisma/client@7.5.0
@@ -125,7 +125,7 @@ RUN echo "Prisma version: $(bunx prisma --version | head -1)"
 # =============================================================================
 FROM l1_golden AS l4_backend_bun
 
-LABEL layer="l4-backend-bun"       description="Backend production runtime (Bun)"       maintainer="beauty-crm"
+LABEL layer="l4-backend-bun"       description="Backend production runtime (Bun)"       maintainer="tdk-project"
 
 ENV NODE_ENV=production
 
@@ -150,7 +150,7 @@ WORKDIR /app
 # =============================================================================
 FROM node:22-alpine AS l4_backend_node
 
-LABEL layer="l4-backend-node"       description="Backend production runtime (Node.js - lightweight)"       maintainer="beauty-crm"
+LABEL layer="l4-backend-node"       description="Backend production runtime (Node.js - lightweight)"       maintainer="tdk-project"
 
 ENV NODE_ENV=production
 
@@ -180,7 +180,7 @@ FROM l4_backend_bun AS l4_backend_golden
 # =============================================================================
 FROM nginx:alpine AS l4_frontend_golden
 
-LABEL layer="l4-frontend"       description="Frontend production runtime with Nginx"       maintainer="beauty-crm"
+LABEL layer="l4-frontend"       description="Frontend production runtime with Nginx"       maintainer="tdk-project"
 
 ENV NODE_ENV=production
 
@@ -198,7 +198,7 @@ WORKDIR /usr/share/nginx/html
 # =============================================================================
 FROM l1_golden AS l4_migrator_golden
 
-LABEL layer="l4-migrator"       description="Migrator runtime with Prisma"       maintainer="beauty-crm"
+LABEL layer="l4-migrator"       description="Migrator runtime with Prisma"       maintainer="tdk-project"
 
 ENV NODE_ENV=production
 

package/engine/assets/docker/wake-gateway/Dockerfile

@@ -1,8 +1,9 @@
 # Wake gateway (see openspec/changes/prioritized-cold-start): fronts every
 # `sablier.deferStart` resource's Traefik static route, triggers cold
 # containers via `tilt trigger` and/or Sablier, then holds the request until
-# healthy. Needs the Docker CLI (client only, talks to the mounted
-# /var/run/docker.sock) and the real `tilt` CLI (D3: shells out to the
+# healthy. Needs the Docker CLI plus its Compose plugin (client only, talks
+# to the mounted /var/run/docker.sock; compose starts an already-built image
+# directly, ahead of Tilt's build queue) and the real `tilt` CLI (D3: shells out to the
 # documented `tilt trigger` command rather than depending on Tilt's
 # undocumented internal HTTP API).
 
@@ -13,7 +14,7 @@ FROM oven/bun:1.3.11-alpine AS base
 # directly (not via tilt-dev's install.sh, which shells out to `sudo` -- not
 # present in this minimal image, and unnecessary since we're already root).
 ARG TILT_VERSION=0.37.7
-RUN apk add --no-cache docker-cli curl gcompat \
+RUN apk add --no-cache docker-cli docker-cli-compose curl gcompat \
     && arch="$(uname -m)" \
     && case "$arch" in aarch64) tilt_arch=arm64 ;; x86_64) tilt_arch=x86_64 ;; *) echo "unsupported arch: $arch" >&2; exit 1 ;; esac \
     && curl -fsSL "https://github.com/tilt-dev/tilt/releases/download/v${TILT_VERSION}/tilt.${TILT_VERSION}.linux.${tilt_arch}.tar.gz" \

package/engine/assets/docker/wake-gateway/decide.test.ts

@@ -1,5 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { decideWakeAction, evaluateReadiness } from "./decide";
+import {
+  COMPOSE_START_TIMEOUT_MS,
+  EARLY_RESPONSE_MS,
+  MAX_EARLY_RESPONSE_MS,
+  RETRY_AFTER_SECONDS,
+  TILT_TRIGGER_TIMEOUT_MS,
+  decideWakeAction,
+  earlyResponseMs,
+  evaluateReadiness,
+  wakeTimeoutMs,
+} from "./decide";
 
 describe("decideWakeAction", () => {
   test("never-created resource: tilt trigger only, no Sablier start", () => {
@@ -56,6 +66,31 @@ describe("decideWakeAction", () => {
     ]);
   });
 
+  test("never-created resource with compose details: started directly, not queued in Tilt", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "absent",
+      dependencies: [{ name: "peer-api", state: "absent" }],
+      hasComposeInvocation: true,
+    });
+    expect(action.useComposeStart).toBe(true);
+    // Dependencies carry no compose details, so they still go through Tilt.
+    expect(action.tiltTriggerNames).toEqual(["peer-api"]);
+    expect(action.useSablierStart).toBe(false);
+  });
+
+  test("existing (exited) container keeps the Sablier path even with compose details", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "exited",
+      dependencies: [],
+      hasComposeInvocation: true,
+    });
+    expect(action.useComposeStart).toBe(false);
+    expect(action.tiltTriggerNames).toEqual(["data-governance-api"]);
+    expect(action.useSablierStart).toBe(true);
+  });
+
   test("running dependency is not re-triggered", () => {
     const action = decideWakeAction({
       resourceContainerName: "data-governance-api",
@@ -66,6 +101,42 @@ describe("decideWakeAction", () => {
   });
 });
 
+describe("wakeTimeoutMs", () => {
+  test("a direct compose start only waits for boot + healthcheck", () => {
+    expect(wakeTimeoutMs(true)).toBe(COMPOSE_START_TIMEOUT_MS);
+  });
+
+  test("the tilt trigger path allows for an image build, under Bun's 255s idle cap", () => {
+    expect(wakeTimeoutMs(false)).toBe(TILT_TRIGGER_TIMEOUT_MS);
+    expect(TILT_TRIGGER_TIMEOUT_MS).toBeLessThan(255_000);
+  });
+
+  test("an explicit X-Wake-Timeout-Ms wins", () => {
+    expect(wakeTimeoutMs(false, 5_000)).toBe(5_000);
+  });
+});
+
+describe("earlyResponseMs", () => {
+  test("holds a waking request for EARLY_RESPONSE_MS by default", () => {
+    expect(earlyResponseMs()).toBe(EARLY_RESPONSE_MS);
+  });
+
+  test("the default answers well before Bun's 255s idle cap drops the connection", () => {
+    expect(EARLY_RESPONSE_MS).toBeLessThan(255_000);
+  });
+
+  test("an explicit X-Wake-Respond-Within-Ms wins, but is capped under Bun's idle limit", () => {
+    expect(earlyResponseMs(5_000)).toBe(5_000);
+    expect(earlyResponseMs(600_000)).toBe(MAX_EARLY_RESPONSE_MS);
+    expect(MAX_EARLY_RESPONSE_MS).toBeLessThan(255_000);
+  });
+
+  test("tells the caller to retry soon", () => {
+    expect(RETRY_AFTER_SECONDS).toBeGreaterThan(0);
+    expect(RETRY_AFTER_SECONDS * 1000).toBeLessThan(EARLY_RESPONSE_MS);
+  });
+});
+
 describe("evaluateReadiness", () => {
   test("ready once every required name reports healthy", () => {
     const outcome = evaluateReadiness(["a", "b"], { a: true, b: true });

package/engine/assets/docker/wake-gateway/decide.ts

@@ -20,11 +20,26 @@ export interface WakeRequestSnapshot {
   resourceContainerName: string;
   resourceState: ContainerState;
   dependencies: DependencySnapshot[];
+  /**
+   * Whether the route carried enough compose detail (project, files, image)
+   * for the gateway to create the resource's container itself.
+   */
+  hasComposeInvocation?: boolean;
 }
 
 export interface WakeAction {
   /** Resources to `tilt trigger` (task 1.5: Tilt never cascades this on its own). */
   tiltTriggerNames: string[];
+  /**
+   * Whether to create/start the resource's container directly with
+   * `docker compose up --no-build` instead of `tilt trigger`. `tilt trigger`
+   * only queues the resource: with Tilt's build slots busy (e.g. 100+
+   * resources rebuilding after a re-vendor), a triggered resource waited
+   * behind them and the request timed out (observed live against
+   * tdk-erp-system, see tasks.md 7.2). server.ts falls back to `tilt trigger`
+   * when no image exists yet to start from.
+   */
+  useComposeStart: boolean;
   /**
    * Whether to also try Sablier's own Docker-level start for the resource.
    * Only meaningful when the resource's container already exists (D2/D3):
@@ -39,8 +54,9 @@ export interface WakeAction {
  */
 export function decideWakeAction(snapshot: WakeRequestSnapshot): WakeAction {
   const tiltTriggerNames: string[] = [];
+  const useComposeStart = snapshot.resourceState === "absent" && snapshot.hasComposeInvocation === true;
 
-  if (snapshot.resourceState !== "running") {
+  if (snapshot.resourceState !== "running" && !useComposeStart) {
     tiltTriggerNames.push(snapshot.resourceContainerName);
   }
   for (const dep of snapshot.dependencies) {
@@ -51,7 +67,40 @@ export function decideWakeAction(snapshot: WakeRequestSnapshot): WakeAction {
 
   const useSablierStart = snapshot.resourceState === "exited" || snapshot.resourceState === "created";
 
-  return { tiltTriggerNames, useSablierStart };
+  return { tiltTriggerNames, useComposeStart, useSablierStart };
+}
+
+/** Wait budget when the gateway starts an existing image itself (boot + healthcheck only). */
+export const COMPOSE_START_TIMEOUT_MS = 180_000;
+/**
+ * Wait budget when the resource has to go through `tilt trigger` (image build
+ * included). Kept under Bun.serve's 255s idleTimeout cap in server.ts.
+ */
+export const TILT_TRIGGER_TIMEOUT_MS = 240_000;
+
+/** The wait budget for a wake: an explicit X-Wake-Timeout-Ms wins, else by start path. */
+export function wakeTimeoutMs(startedViaCompose: boolean, overrideMs?: number): number {
+  if (overrideMs && overrideMs > 0) return overrideMs;
+  return startedViaCompose ? COMPOSE_START_TIMEOUT_MS : TILT_TRIGGER_TIMEOUT_MS;
+}
+
+/**
+ * How long a waking request is held before the gateway answers
+ * `503` + `Retry-After` while the start keeps going in the background.
+ * Found live (task 7.2): during a full `tdk up` bring-up the Docker daemon
+ * took ~5 min to start one container, and Bun.serve's 255s idle cap dropped
+ * the held connection with no response at all.
+ */
+export const EARLY_RESPONSE_MS = 60_000;
+/** Largest hold allowed: stays under Bun.serve's 255s idle cap. */
+export const MAX_EARLY_RESPONSE_MS = 240_000;
+/** The `Retry-After` value sent with the early 503. */
+export const RETRY_AFTER_SECONDS = 10;
+
+/** How long to hold a request: an explicit X-Wake-Respond-Within-Ms wins, capped under Bun's idle limit. */
+export function earlyResponseMs(overrideMs?: number): number {
+  if (overrideMs && overrideMs > 0) return Math.min(overrideMs, MAX_EARLY_RESPONSE_MS);
+  return EARLY_RESPONSE_MS;
 }
 
 export interface WaitOutcome {

package/engine/assets/docker/wake-gateway/server.ts

@@ -10,11 +10,10 @@
  * injects (set by the file-provider entry generated in
  * traefik_static_routes.star) rather than the path, so the original request
  * path/query reach the real backend unchanged once it's ready:
- *   X-Wake-Resource        Tilt/Compose resource name (for `tilt trigger`,
- *                          and the proxy target -- Compose's embedded DNS
- *                          resolves a service by this name too).
+ *   X-Wake-Resource        Tilt/Compose resource name (for `tilt trigger` and
+ *                          `docker compose up <service>`).
  *   X-Wake-Container       The actual Docker container name (for `docker
- *                          inspect` state/health -- NOT the same string as
+ *                          inspect` state/health and the proxy target -- NOT the same string as
  *                          the resource name; Compose derives it as
  *                          <project>-<service>-<replica>, confirmed empirically
  *                          against a live TDK container, e.g.
@@ -23,15 +22,33 @@
  *   X-Wake-Deps            Comma-separated "resourceName=containerName" pairs
  *                          for required dependencies (task 1.5: Tilt never
  *                          cascades a trigger to these on its own).
+ *   X-Wake-Compose-Project The resource's Compose project (e.g. "analytics-autogenerated").
+ *   X-Wake-Compose-Files   Comma-separated absolute compose file paths, the
+ *                          same ones Tilt's `<resource>-run-only` resource
+ *                          passes. The project root is mounted into this
+ *                          container at the same absolute path, so relative
+ *                          paths inside those files resolve exactly as for Tilt.
+ *   X-Wake-Env-File        Absolute path of the project's .env (optional).
+ *   X-Wake-Image           The image the compose service declares
+ *                          (<service>_<resource>:dev).
  *   X-Wake-Timeout-Ms, X-Wake-Proxy-Port, X-Wake-Session-Duration
+ *   X-Wake-Respond-Within-Ms  How long to hold the request before answering
+ *                          503 + Retry-After while the start continues in the
+ *                          background (default decide.ts EARLY_RESPONSE_MS).
  */
-import { decideWakeAction, evaluateReadiness, type ContainerState } from "./decide";
+import {
+  RETRY_AFTER_SECONDS,
+  decideWakeAction,
+  earlyResponseMs,
+  evaluateReadiness,
+  wakeTimeoutMs,
+  type ContainerState,
+} from "./decide";
 
 const TILT_HOST = process.env.TILT_HOST || "host.docker.internal";
 const TILT_PORT = process.env.TILT_PORT || "10350";
 const SABLIER_URL = process.env.SABLIER_URL || "http://sablier:10000";
 const POLL_INTERVAL_MS = 1000;
-const DEFAULT_TIMEOUT_MS = 60_000;
 
 async function run(cmd: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
   const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
@@ -66,7 +83,52 @@ async function isHealthy(name: string): Promise<boolean> {
 }
 
 async function tiltTrigger(name: string): Promise<void> {
-  await run(["tilt", "trigger", name, "--host", TILT_HOST, "--port", TILT_PORT]);
+  const { code, stderr } = await run(["tilt", "trigger", name, "--host", TILT_HOST, "--port", TILT_PORT]);
+  console.log(`tilt trigger ${name}: ${code === 0 ? "queued" : `failed (${stderr.trim()})`}`);
+}
+
+interface ComposeInvocation {
+  project: string;
+  files: string[];
+  envFile: string;
+  image: string;
+}
+
+/**
+ * Make sure the compose service's declared image exists locally. Tilt tags its
+ * own builds `<repo>:tilt-<hash>` and injects that tag when it runs compose, so
+ * the declared `<repo>:dev` tag may be missing even though the resource was
+ * built; retag Tilt's newest build in that case. False when nothing was ever
+ * built -- only `tilt trigger` (which builds) can wake the resource then.
+ */
+async function ensureImage(image: string): Promise<boolean> {
+  if ((await run(["docker", "image", "inspect", "--format", "{{.Id}}", image])).code === 0) return true;
+  const repo = image.split(":")[0];
+  // `docker images` lists newest first.
+  const { code, stdout } = await run(["docker", "images", repo, "--format", "{{.Tag}}"]);
+  if (code !== 0) return false;
+  const tiltTag = stdout.split("\n").map((t) => t.trim()).find((t) => t.startsWith("tilt-"));
+  if (!tiltTag) return false;
+  return (await run(["docker", "tag", `${repo}:${tiltTag}`, image])).code === 0;
+}
+
+/**
+ * Create and start the resource's container directly, with the same
+ * `docker compose ... up -d --no-build` its Tilt `-run-only` resource runs,
+ * bypassing Tilt's build queue (see decide.ts useComposeStart).
+ */
+async function composeStart(compose: ComposeInvocation, service: string): Promise<boolean> {
+  if (!(await ensureImage(compose.image))) {
+    console.log(`compose start ${service}: no local image for ${compose.image}, falling back to tilt trigger`);
+    return false;
+  }
+  const args = ["docker", "compose", "-p", compose.project];
+  for (const file of compose.files) args.push("-f", file);
+  if (compose.envFile) args.push("--env-file", compose.envFile);
+  args.push("up", "-d", "--no-build", "--no-deps", service);
+  const { code, stderr } = await run(args);
+  console.log(`compose start ${service}: ${code === 0 ? "started" : `failed (${stderr.trim()})`}`);
+  return code === 0;
 }
 
 /**
@@ -110,39 +172,111 @@ function parseRequest(req: Request) {
   const resource = req.headers.get("X-Wake-Resource") || "";
   const container = req.headers.get("X-Wake-Container") || resource;
   const deps = parseDeps(req.headers.get("X-Wake-Deps") || "");
-  const timeoutMs = Number(req.headers.get("X-Wake-Timeout-Ms")) || DEFAULT_TIMEOUT_MS;
+  const timeoutOverrideMs = Number(req.headers.get("X-Wake-Timeout-Ms")) || undefined;
+  const respondWithinOverrideMs = Number(req.headers.get("X-Wake-Respond-Within-Ms")) || undefined;
   const proxyPort = req.headers.get("X-Wake-Proxy-Port") || "80";
   const sessionDuration = req.headers.get("X-Wake-Session-Duration") || "10m";
-  return { resource, container, deps, timeoutMs, proxyPort, sessionDuration };
+  const composeFiles = (req.headers.get("X-Wake-Compose-Files") || "").split(",").filter(Boolean);
+  const compose: ComposeInvocation = {
+    project: req.headers.get("X-Wake-Compose-Project") || "",
+    files: composeFiles,
+    envFile: req.headers.get("X-Wake-Env-File") || "",
+    image: req.headers.get("X-Wake-Image") || "",
+  };
+  const hasCompose = Boolean(compose.project && compose.files.length && compose.image);
+  return {
+    resource,
+    container,
+    deps,
+    timeoutOverrideMs,
+    respondWithinOverrideMs,
+    proxyPort,
+    sessionDuration,
+    compose,
+    hasCompose,
+  };
+}
+
+type WakeParams = ReturnType<typeof parseRequest>;
+type WakeOutcome = { ready: true } | { ready: false; timeoutMs: number };
+
+// One wake per resource at a time: a caller that got an early 503 and retries,
+// or a second caller arriving meanwhile, joins the wake already in progress
+// instead of starting the container again.
+const inflight = new Map<string, Promise<WakeOutcome>>();
+
+function wakeOnce(params: WakeParams): Promise<WakeOutcome> {
+  let wake = inflight.get(params.resource);
+  if (!wake) {
+    wake = runWake(params).finally(() => inflight.delete(params.resource));
+    inflight.set(params.resource, wake);
+  }
+  return wake;
 }
 
 async function handleWake(req: Request): Promise<Response> {
-  const { resource, container, deps, timeoutMs, proxyPort, sessionDuration } = parseRequest(req);
-  if (!resource) {
+  const params = parseRequest(req);
+  if (!params.resource) {
     return new Response("wake gateway: missing X-Wake-Resource header (set by the generated Traefik static route)", { status: 400 });
   }
 
+  const holdMs = earlyResponseMs(params.respondWithinOverrideMs);
+  const outcome = await Promise.race([wakeOnce(params), Bun.sleep(holdMs).then(() => null)]);
+  if (outcome === null) {
+    console.log(`wake ${params.resource}: still starting after ${holdMs}ms, answering 503`);
+    return new Response(
+      `wake gateway: ${params.resource} is starting; retry in ${RETRY_AFTER_SECONDS}s`,
+      { status: 503, headers: { "Retry-After": String(RETRY_AFTER_SECONDS) } },
+    );
+  }
+  if (outcome.ready) {
+    return proxyThrough(req, params.container, params.proxyPort);
+  }
+  return new Response(
+    `wake gateway: timed out after ${outcome.timeoutMs}ms waiting for ${params.resource} and its dependencies to become healthy`,
+    { status: 504 },
+  );
+}
+
+async function runWake(params: WakeParams): Promise<WakeOutcome> {
+  const { resource, container, deps, timeoutOverrideMs, sessionDuration, compose, hasCompose } = params;
   const resourceState = await containerState(container);
   const dependencies = await Promise.all(
     deps.map(async (dep) => ({ name: dep.resourceName, state: await containerState(dep.containerName) })),
   );
 
-  const action = decideWakeAction({ resourceContainerName: resource, resourceState, dependencies });
+  const action = decideWakeAction({
+    resourceContainerName: resource,
+    resourceState,
+    dependencies,
+    hasComposeInvocation: hasCompose,
+  });
+  console.log(
+    `wake ${resource}: state=${resourceState} compose=${action.useComposeStart} ` +
+      `trigger=[${action.tiltTriggerNames.join(",")}] sablier=${action.useSablierStart}`,
+  );
+
+  // Dependencies (and the resource itself when it can't be started directly)
+  // go through tilt trigger (task 1.5: Tilt never cascades this on its own).
+  const tiltNames = [...action.tiltTriggerNames];
+  let startedViaCompose = false;
+  if (action.useComposeStart) {
+    startedViaCompose = await composeStart(compose, resource);
+    if (!startedViaCompose) tiltNames.unshift(resource);
+  }
+  const timeoutMs = wakeTimeoutMs(startedViaCompose, timeoutOverrideMs);
   const deadline = Date.now() + timeoutMs;
 
-  // tilt trigger runs for everything cold (task 1.5: Tilt never cascades this
-  // on its own); Sablier's blocking call, when applicable, both starts AND
-  // waits for the resource itself in one round trip.
+  // Sablier's blocking call, when applicable, both starts AND waits for the
+  // resource itself in one round trip.
   const [, resourceReadyViaSablier] = await Promise.all([
-    Promise.all(action.tiltTriggerNames.map(tiltTrigger)),
+    Promise.all(tiltNames.map(tiltTrigger)),
     action.useSablierStart
       ? sablierBlockingWait(resource, sessionDuration, timeoutMs)
       : Promise.resolve(false),
   ]);
 
   const requiredNames = [resource, ...deps.map((d) => d.resourceName)];
-  const containerByName: Record<string, string> = { [resource]: container };
-  for (const dep of deps) containerByName[dep.resourceName] = dep.containerName;
 
   while (Date.now() < deadline) {
     const healthy: Record<string, boolean> = {};
@@ -152,17 +286,12 @@ async function handleWake(req: Request): Promise<Response> {
     for (const dep of deps) {
       healthy[dep.resourceName] = await isHealthy(dep.containerName);
     }
-    const outcome = evaluateReadiness(requiredNames, healthy);
-    if (outcome.ready) {
-      return proxyThrough(req, resource, proxyPort);
+    if (evaluateReadiness(requiredNames, healthy).ready) {
+      return { ready: true };
     }
     await Bun.sleep(POLL_INTERVAL_MS);
   }
-
-  return new Response(
-    `wake gateway: timed out after ${timeoutMs}ms waiting for ${resource} and its dependencies to become healthy`,
-    { status: 504 },
-  );
+  return { ready: false, timeoutMs };
 }
 
 // Headers that must not be forwarded verbatim to the upstream fetch: Host
@@ -174,11 +303,19 @@ const STRIPPED_REQUEST_HEADERS = new Set([
   "x-wake-container",
   "x-wake-deps",
   "x-wake-timeout-ms",
+  "x-wake-respond-within-ms",
   "x-wake-proxy-port",
   "x-wake-session-duration",
+  "x-wake-compose-project",
+  "x-wake-compose-files",
+  "x-wake-env-file",
+  "x-wake-image",
 ]);
 
-async function proxyThrough(req: Request, resource: string, port: string): Promise<Response> {
+// Proxies to the container name rather than the Compose service name: every
+// TDK project's resources share the traefik-public network, where a bare
+// service name is only an alias and could collide across projects.
+async function proxyThrough(req: Request, container: string, port: string): Promise<Response> {
   // The original path/query reach the gateway untouched (config travels via
   // X-Wake-* headers, not the path), so they're forwarded as-is.
   const target = new URL(req.url);
@@ -186,7 +323,7 @@ async function proxyThrough(req: Request, resource: string, port: string): Promi
   // Set hostname/port separately, not via `.host` -- confirmed empirically
   // that `target.host = "name:port"` silently keeps the URL's original port
   // when one is already present instead of replacing it.
-  target.hostname = resource;
+  target.hostname = container;
   target.port = port;
 
   const headers = new Headers();

package/engine/assets/scripts/mac-m1-resource-monitor.sh

@@ -84,7 +84,7 @@ while IFS= read -r container; do
         
         printf "%-20s\t%s%%\t%s\t%s\n" "$CONTAINER_DISPLAY" "$CPU_PERCENT" "$MEMORY_USAGE" "$STATUS"
     fi
-done <<< "$BEAUTY_CONTAINERS"
+done <<< "$PROJECT_CONTAINERS"
 
 echo ""
 echo -e "${BLUE}📈 Resource Summary:${NC}"

package/engine/scripts/debug-container.sh

@@ -13,6 +13,11 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
+# Container name filter: project name from .tdk/project.json (override with TDK_PROJECT_NAME)
+PROJECT_FILTER="${TDK_PROJECT_NAME:-$(sed -n 's/.*"name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' .tdk/project.json 2>/dev/null | head -1)}"
+PROJECT_FILTER="${PROJECT_FILTER:-tdk-project}"
+PROJECT_FILTER="${PROJECT_FILTER//-/[-_]}"
+
 # Help text
 show_help() {
     cat << EOF
@@ -68,11 +73,11 @@ EOF
 # List containers
 list_containers() {
     echo -e "${GREEN}=== Running Containers ===${NC}"
-    docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -i "beauty"
+    docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -iE "$PROJECT_FILTER"
     
     echo ""
     echo -e "${YELLOW}=== Recently Exited Containers ===${NC}"
-    docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -i "beauty" | grep -i "exited"
+    docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -iE "$PROJECT_FILTER" | grep -i "exited"
 }
 
 # Get container ID from service name
@@ -122,7 +127,7 @@ run_command() {
 # Show failed containers
 show_failed() {
     echo -e "${RED}=== Failed/Exited Containers ===${NC}"
-    docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -i "beauty" | grep -iE "(exited|error)"
+    docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -iE "$PROJECT_FILTER" | grep -iE "(exited|error)"
     
     echo ""
     echo -e "${YELLOW}To inspect logs of a failed container:${NC}"

package/engine/spec.master

@@ -62,7 +62,7 @@
 
 # PROJECT_ROOT is automatically set by Tiltfile based on where you run `tilt up`.
 # You don't need to set it. Example:
-#   - If you run in /home/dev/beauty-crm, PROJECT_ROOT = "/home/dev/beauty-crm"
+#   - If you run in /home/dev/tdk-project, PROJECT_ROOT = "/home/dev/tdk-project"
 #   - All other paths are built from this root.
 #
 # This file is manually maintained to match the directory structure.
@@ -563,7 +563,7 @@ FEATURES = struct(
 
 CONSTANTS = struct(
     # System identity - EXPLICIT
-    SYSTEM_NAME = "beauty-crm-tilt-platform",
+    SYSTEM_NAME = "tdk-project-tilt-platform",
     SYSTEM_VERSION = "2.0.0",
     
     # Runtimes - EXPLICIT supported options