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

package/cli/src/utils/__tests__/tilt.test.ts

@@ -104,6 +104,35 @@ describe("buildTiltUpArgs", () => {
     buildTiltUpArgs([], {});
     expect(findProjectRoot).toHaveBeenCalledTimes(1);
   });
+
+  it("should include -- --focus=<stack> before service names when focusTargets is set", async () => {
+    // Regression test: `tdk up <stack>` used to pass only bare positional service
+    // names, which the generated Tiltfile's focus filter never reads (it only reads
+    // --focus), so it silently fell back to building every stack instead of the one
+    // requested. --focus must be present, carry the stack name, and be preceded by
+    // `--` (tilt up rejects "--focus" as an unrecognized top-level flag otherwise -
+    // `--` is what routes it to the Tiltfile's own config.parse()).
+    const { buildTiltUpArgs } = await import("../tilt.js");
+    const args = buildTiltUpArgs(["finance-api", "finance-app"], { focusTargets: ["finance"] });
+    const dashDashIndex = args.indexOf("--");
+    expect(dashDashIndex).toBeGreaterThanOrEqual(0);
+    expect(args[dashDashIndex + 1]).toBe("--focus=finance");
+    expect(args.indexOf("--focus=finance")).toBeLessThan(args.indexOf("finance-api"));
+  });
+
+  it("should join multiple focusTargets with commas in a single --focus flag", async () => {
+    const { buildTiltUpArgs } = await import("../tilt.js");
+    const args = buildTiltUpArgs([], { focusTargets: ["finance", "hr"] });
+    expect(args).toContain("--focus=finance,hr");
+  });
+
+  it("should NOT include --focus when focusTargets is empty or omitted", async () => {
+    const { buildTiltUpArgs } = await import("../tilt.js");
+    const withEmpty = buildTiltUpArgs(["svc"], { focusTargets: [] });
+    const withOmitted = buildTiltUpArgs(["svc"], {});
+    expect(withEmpty.some((a) => a.startsWith("--focus"))).toBe(false);
+    expect(withOmitted.some((a) => a.startsWith("--focus"))).toBe(false);
+  });
 });
 
 describe("buildTiltDownArgs", () => {

package/cli/src/utils/constants.ts

@@ -27,6 +27,10 @@ export const REQUIRED_PACKAGE_SCRIPTS: Record<ResourceType, readonly string[]> =
   sdk: ["dev", "build"],
 } as const;
 
+// Version specifiers that pin nothing at all - a fresh `bun install`/`npm install`
+// can pull a different (possibly breaking) version on every run.
+export const UNPINNED_DEPENDENCY_VERSIONS = new Set(["latest", "*"]);
+
 export const OPTIONAL_INFRA_SERVICES = [
   "monitoring",
   "elk",

package/cli/src/utils/doctor-runtime.ts

@@ -5,6 +5,7 @@ import type { CheckResult } from "../types/index.js";
 import { formatCount } from "./formatting.js";
 import { findProjectRoot } from "./paths.js";
 import { getProjectName } from "./service-urls.js";
+import { discoverResources } from "./services.js";
 
 const EXEC_TIMEOUT_MS = 10_000;
 const REGISTRY_PROBE_TIMEOUT_MS = 3_000;
@@ -88,12 +89,41 @@ interface TiltUiResourceItem {
   };
 }
 
+/**
+ * Resource names with `sablier: {enable: true, deferStart: true}` in their
+ * manifest (openspec/changes/prioritized-cold-start): these are expected to
+ * sit at `runtimeStatus: none` until their first request, not a sign of
+ * anything stuck. Best-effort — returns an empty set if discovery fails
+ * (e.g. not run from inside a project), so callers degrade to today's
+ * behavior rather than erroring.
+ */
+export function getDeferredResourceNames(): Set<string> {
+  try {
+    return new Set(
+      discoverResources()
+        .filter((svc) => svc.config?.sablier?.enable && svc.config?.sablier?.deferStart)
+        .map((svc) => svc.name),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
 /**
  * Extract failing UIResources from `tilt get uiresources -o json`.
+ *
+ * `deferredNames` (typically from getDeferredResourceNames()) separates a
+ * `sablier.deferStart` resource's expected `none`/`pending` status into its
+ * own count so it's never described as "blocked" or otherwise lumped in with
+ * genuinely stuck resources.
  */
-export function parseTiltResourceFailures(jsonText: string): {
+export function parseTiltResourceFailures(
+  jsonText: string,
+  deferredNames: Set<string> = new Set(),
+): {
   failures: TiltResourceFailure[];
   pendingCount: number;
+  deferredCount: number;
   okCount: number;
   total: number;
 } {
@@ -101,6 +131,7 @@ export function parseTiltResourceFailures(jsonText: string): {
   const items = parsed.items ?? [];
   const failures: TiltResourceFailure[] = [];
   let pendingCount = 0;
+  let deferredCount = 0;
   let okCount = 0;
 
   for (const item of items) {
@@ -133,11 +164,15 @@ export function parseTiltResourceFailures(jsonText: string): {
         updateStatus === "none" ||
         runtimeStatus === "none")
     ) {
-      pendingCount += 1;
+      if (deferredNames.has(name)) {
+        deferredCount += 1;
+      } else {
+        pendingCount += 1;
+      }
     }
   }
 
-  return { failures, pendingCount, okCount, total: items.length };
+  return { failures, pendingCount, deferredCount, okCount, total: items.length };
 }
 
 /**
@@ -156,9 +191,7 @@ export function summarizeTiltBuildError(error: string): string {
   }
 
   const refusedPackages = [
-    ...normalized.matchAll(
-      /ConnectionRefused downloading package manifest (@[A-Za-z0-9._/-]+)/gi,
-    ),
+    ...normalized.matchAll(/ConnectionRefused downloading package manifest (@[A-Za-z0-9._/-]+)/gi),
   ].map((match) => match[1]);
   if (refusedPackages.length > 0) {
     const unique = [...new Set(refusedPackages)];
@@ -167,7 +200,11 @@ export function summarizeTiltBuildError(error: string): string {
     return `private registry ConnectionRefused for ${shown}${more} — Verdaccio (:4873) is down or unreachable from the build`;
   }
 
-  if (/failed to resolve source metadata for docker\.io\/library\/(beauty-crm-[^:\s]+)/i.test(normalized)) {
+  if (
+    /failed to resolve source metadata for docker\.io\/library\/(beauty-crm-[^:\s]+)/i.test(
+      normalized,
+    )
+  ) {
     const image = normalized.match(
       /failed to resolve source metadata for docker\.io\/library\/(beauty-crm-[^:\s]+)/i,
     )?.[1];
@@ -186,10 +223,12 @@ export function summarizeTiltBuildError(error: string): string {
     normalized.match(/No such image:\s*([^\s]+)/i)?.[1] ??
     normalized.match(/pull access denied for ([^,:\s]+)/i)?.[1] ??
     undefined;
-  const composeService = normalized.match(
-    /\bup\s+-d\s+--no-build\s+([A-Za-z0-9._-]+)/i,
-  )?.[1];
-  if (missingImage || composeService || /docker compose .*\bup\s+-d\s+--no-build\b/i.test(normalized)) {
+  const composeService = normalized.match(/\bup\s+-d\s+--no-build\s+([A-Za-z0-9._-]+)/i)?.[1];
+  if (
+    missingImage ||
+    composeService ||
+    /docker compose .*\bup\s+-d\s+--no-build\b/i.test(normalized)
+  ) {
     const imageLabel = missingImage ?? `${composeService ?? "service"}:dev`;
     const serviceHint = composeService ? ` for ${composeService}` : "";
     return `compose run failed because image is missing (${imageLabel})${serviceHint} — wait for the ImageBuild resource to finish, then re-trigger the *-run-only resource`;
@@ -212,7 +251,9 @@ export function isRegistryRelatedBuildError(error: string): boolean {
   );
 }
 
-export function projectExpectsVerdaccio(projectRoot: string = findProjectRoot() ?? process.cwd()): boolean {
+export function projectExpectsVerdaccio(
+  projectRoot: string = findProjectRoot() ?? process.cwd(),
+): boolean {
   const projectJsonPath = join(projectRoot, ".tdk", "project.json");
   if (existsSync(projectJsonPath)) {
     try {
@@ -236,10 +277,7 @@ export function projectExpectsVerdaccio(projectRoot: string = findProjectRoot()
   }
 
   // Heuristic: scoped private registry pointed at :4873
-  for (const candidate of [
-    join(projectRoot, ".npmrc"),
-    join(projectRoot, "package.json"),
-  ]) {
+  for (const candidate of [join(projectRoot, ".npmrc"), join(projectRoot, "package.json")]) {
     if (!existsSync(candidate)) continue;
     try {
       const text = readFileSync(candidate, "utf-8");
@@ -419,7 +457,7 @@ export function checkTiltResourceHealth(exec: typeof execSync = execSync): Check
 
   let parsed: ReturnType<typeof parseTiltResourceFailures>;
   try {
-    parsed = parseTiltResourceFailures(jsonText);
+    parsed = parseTiltResourceFailures(jsonText, getDeferredResourceNames());
   } catch {
     return {
       name: "Tilt Resources",
@@ -439,10 +477,11 @@ export function checkTiltResourceHealth(exec: typeof execSync = execSync): Check
   }
 
   if (parsed.failures.length === 0) {
+    const deferredNote = parsed.deferredCount > 0 ? `, ${parsed.deferredCount} deferred` : "";
     return {
       name: "Tilt Resources",
       didPass: true,
-      message: `Tilt resources healthy (${parsed.okCount} ok, ${parsed.pendingCount} pending)`,
+      message: `Tilt resources healthy (${parsed.okCount} ok, ${parsed.pendingCount} pending${deferredNote})`,
     };
   }
 
@@ -458,9 +497,7 @@ export function checkTiltResourceHealth(exec: typeof execSync = execSync): Check
     failure,
     why: describeTiltFailure(failure, exec),
   }));
-  const details = described
-    .map(({ failure, why }) => `${failure.name}: ${why}`)
-    .join("\n    ");
+  const details = described.map(({ failure, why }) => `${failure.name}: ${why}`).join("\n    ");
   const omittedNote =
     omitted > 0 ? `\n    …and ${formatCount(omitted, "more failed resource")}` : "";
 
@@ -468,6 +505,10 @@ export function checkTiltResourceHealth(exec: typeof execSync = execSync): Check
     parsed.pendingCount > 0
       ? `\n    ${formatCount(parsed.pendingCount, "resource")} still pending/not started — often blocked by the failures above.`
       : "";
+  const deferredNote =
+    parsed.deferredCount > 0
+      ? `\n    ${formatCount(parsed.deferredCount, "resource")} intentionally deferred (sablier.deferStart) — not started until first request, unrelated to the failures above.`
+      : "";
 
   const hasPortConflict = ordered.some((failure) =>
     /port is already allocated/i.test(failure.error),
@@ -497,13 +538,12 @@ export function checkTiltResourceHealth(exec: typeof execSync = execSync): Check
   return {
     name: "Tilt Resources",
     didPass: false,
-    message: `Tilt reports ${formatCount(parsed.failures.length, "failed resource")}:\n    ${details}${omittedNote}${pendingNote}`,
+    message: `Tilt reports ${formatCount(parsed.failures.length, "failed resource")}:\n    ${details}${omittedNote}${pendingNote}${deferredNote}`,
     fix,
   };
 }
 
-const INFRA_FAILURE_NAME =
-  /^(traefik|postgres|nats|infisical|verdaccio|proxy)([.-]|$)/i;
+const INFRA_FAILURE_NAME = /^(traefik|postgres|nats|infisical|verdaccio|proxy)([.-]|$)/i;
 
 export function isInfraTiltFailure(name: string): boolean {
   return INFRA_FAILURE_NAME.test(name);
@@ -563,9 +603,9 @@ export function probeContainerRuntimeError(
 
     // Zod env/config validation: pull required field paths from the dump.
     if (/ZodError/i.test(logs)) {
-      const requiredPaths = [
-        ...logs.matchAll(/"path"\s*:\s*\[\s*"([^"]+)"\s*\]/g),
-      ].map((match) => match[1]);
+      const requiredPaths = [...logs.matchAll(/"path"\s*:\s*\[\s*"([^"]+)"\s*\]/g)].map(
+        (match) => match[1],
+      );
       const uniquePaths = [...new Set(requiredPaths)].slice(0, 6);
       if (uniquePaths.length > 0) {
         return `runtime crash: ZodError missing required config/env: ${uniquePaths.join(", ")}`;

package/cli/src/utils/env-validator.ts

@@ -52,7 +52,7 @@ function generateDbPassword(): string {
   return randomBytes(16).toString("hex");
 }
 
-export function generateEnvFile(projectRoot: string): string {
+export function generateEnvFile(_projectRoot: string): string {
   const lines: string[] = [
     "# 🔧 TDK Environment Configuration",
     "# Auto-generated by TDK CLI - edit as needed",
@@ -107,7 +107,7 @@ export function validateEnvFile(projectRoot: string): {
       .split("\n")
       .filter((line) => !line.startsWith("#") && line.includes("="))
       .map((line) => line.split("=")[0])
-      .filter((name) => name.length > 0)
+      .filter((name) => name.length > 0),
   );
 
   for (const envVar of REQUIRED_ENV_VARS) {

package/cli/src/utils/project-templates.ts

@@ -11,7 +11,8 @@ export const PROJECT_TEMPLATES: Record<string, ProjectTemplate> = {
   },
   saas: {
     repo: "https://github.com/tdk-landscape/tdk-saas-starter.git",
-    description: "SaaS starter: account dashboard and a working checkout button (Hono + Vite + Bun)",
+    description:
+      "SaaS starter: account dashboard and a working checkout button (Hono + Vite + Bun)",
   },
   erp: {
     repo: "https://github.com/tdk-landscape/tdk-erp-system.git",

package/cli/src/utils/prompt.ts

@@ -1,5 +1,5 @@
-import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
 
 type ValidationResult = true | string;
 
@@ -67,9 +67,7 @@ export async function promptConfirm(options: ConfirmPromptOptions): Promise<bool
   }
 }
 
-export async function promptSelect<T extends string>(
-  options: ChoicePromptOptions<T>,
-): Promise<T> {
+export async function promptSelect<T extends string>(options: ChoicePromptOptions<T>): Promise<T> {
   console.log(options.message);
   options.choices.forEach((choice, index) => {
     console.log(`  ${index + 1}. ${choice.title}`);

package/cli/src/utils/resource-features.ts

@@ -92,7 +92,8 @@ export const RESOURCE_FEATURES: Record<string, ResourceFeature> = {
     description: "Docker container configuration for production builds",
     applies_to: ["frontend", "backend", "worker", "migrator", "sdk"],
     enabled_by_default: true, // Always enabled
-    generator_file: "engine/topologies/tilt/resources/orchestrator/generators/manifest_resource.star",
+    generator_file:
+      "engine/topologies/tilt/resources/orchestrator/generators/manifest_resource.star",
     output_file: ".autogenerated/Dockerfile.app",
   },
 
@@ -169,15 +170,20 @@ export const RESOURCE_FEATURES: Record<string, ResourceFeature> = {
     name: "sablier",
     description:
       "On-demand scaling: stop this resource when idle, wake it on the next request via a " +
-      "`sablier: {enable: true}` manifest block (not the featuresEnabled array) " +
+      "`sablier: {enable: true}` manifest block (not the featuresEnabled array). Add " +
+      "`deferStart: true` to also skip this resource during `tdk up` entirely — no container " +
+      "is created or started, and a Traefik static route wakes it on the first request instead " +
+      "(backends only for now), so it doesn't wait behind the rest of a large landscape's " +
+      "bring-up. Requires `enable: true`. " +
       "(Premium - requires TDK_LICENSE_KEY; free tier writes a disabled stub; see " +
       "hasSablierLicense() in extension-fetch.ts KNOWN_RESOURCES/PREMIUM_PATH_MAP)",
     applies_to: ["backend", "frontend"],
     enabled_by_default: false,
     category: "premium",
     generator_file:
-      "engine/topologies/platform/docker/networking/sablier_container_cycle.star (stub; real generator in tdk-cli-extensions/premium/networking/), engine/topologies/platform/docker/networking/traefik.star",
-    output_file: "(Traefik + Sablier Docker labels on the resource's own compose service, no autogenerated file)",
+      "engine/topologies/platform/docker/networking/sablier_container_cycle.star (stub; real generator in tdk-cli-extensions/premium/networking/), engine/topologies/platform/docker/networking/traefik.star, engine/topologies/platform/docker/compose/traefik_standalone.star (deferStart wake gateway + static route), engine/topologies/platform/docker/compose/compose.star (deferStart depends_on)",
+    output_file:
+      "(Traefik + Sablier Docker labels on the resource's own compose service; with deferStart, also a generated Traefik file-provider dynamic-config entry and a depends_on block)",
   },
 };
 

package/cli/src/utils/services.ts

@@ -73,7 +73,8 @@ function parseResource(serviceJsonPath: string): DiscoveredResource {
   const parsedConfig = parsed as unknown as ResourceConfig;
   const config: ResourceConfig = {
     ...parsedConfig,
-    appType: (parsedConfig.appType || (parsedConfig as any).type) as ResourceConfig["appType"],
+    appType: (parsedConfig.appType ||
+      (parsedConfig as unknown as { type?: string }).type) as ResourceConfig["appType"],
   };
   const resourceDir = dirname(serviceJsonPath);
 

package/cli/src/utils/tilt.ts

@@ -84,10 +84,30 @@ export function buildTiltUpArgs(
     quiet?: boolean;
     force?: boolean;
     watch?: boolean;
+    focusTargets?: string[];
   } = {},
 ): string[] {
   const args: string[] = [];
   addTiltfilePath(args);
+
+  // Bare positional resource names only scope what this `tilt up` invocation waits
+  // on - they do NOT limit which resources the generated Tiltfile enables. Its focus
+  // filter (Config.apply_focus / apply_focus_filter) only reads the `--focus` flag;
+  // the positional-args catch-all it also defines (`cfg['args']`) is never read. So
+  // without `--focus`, every `tdk up <stack>` silently fell back to Tilt's default
+  // "pre-alpha" phase and built every stack in that phase, not just the one asked
+  // for. Passing the stack name via `--focus` reuses the Tiltfile's own (already
+  // dependency-aware) domain expansion instead of re-deriving it here.
+  //
+  // `--focus=...` needs a `--` before it: Tilt's own `tilt up` only accepts its own
+  // fixed flag set directly (see `tilt up --help`) and rejects anything else with
+  // "unknown flag" - `--` is what routes a token through to the Tiltfile's own
+  // config.parse(). Bare words like a service name aren't flag-shaped, so they don't
+  // need `--` to reach the Tiltfile's positional `args` catch-all.
+  if (options.focusTargets && options.focusTargets.length > 0) {
+    args.push("--", `--focus=${options.focusTargets.join(",")}`);
+  }
+
   args.push(...serviceNames);
 
   if (options.verbose && !options.quiet) {

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

@@ -0,0 +1,26 @@
+# 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
+# documented `tilt trigger` command rather than depending on Tilt's
+# undocumented internal HTTP API).
+
+FROM oven/bun:1.3.11-alpine AS base
+
+# Pin to the same Tilt version this workspace runs (v0.37.7) so `tilt trigger`
+# talks the same protocol as the real daemon it's connecting to. Installed
+# 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 \
+    && 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" \
+       | tar -xz -C /usr/local/bin tilt
+
+WORKDIR /app
+COPY decide.ts server.ts ./
+
+EXPOSE 9999
+CMD ["bun", "run", "server.ts"]

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

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { decideWakeAction, evaluateReadiness } from "./decide";
+
+describe("decideWakeAction", () => {
+  test("never-created resource: tilt trigger only, no Sablier start", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "absent",
+      dependencies: [],
+    });
+    expect(action.tiltTriggerNames).toEqual(["data-governance-api"]);
+    expect(action.useSablierStart).toBe(false);
+  });
+
+  test("previously-run, now-exited resource: both tilt trigger and Sablier start", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "exited",
+      dependencies: [],
+    });
+    expect(action.tiltTriggerNames).toEqual(["data-governance-api"]);
+    expect(action.useSablierStart).toBe(true);
+  });
+
+  test("created-but-not-started resource: both paths apply", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "created",
+      dependencies: [],
+    });
+    expect(action.useSablierStart).toBe(true);
+  });
+
+  test("already running: no trigger needed", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "running",
+      dependencies: [],
+    });
+    expect(action.tiltTriggerNames).toEqual([]);
+    expect(action.useSablierStart).toBe(false);
+  });
+
+  test("cold dependency is triggered alongside the resource (task 1.5 finding)", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "absent",
+      dependencies: [
+        { name: "postgres", state: "running" },
+        { name: "data-governance-api-db-migrator", state: "absent" },
+      ],
+    });
+    expect(action.tiltTriggerNames).toEqual([
+      "data-governance-api",
+      "data-governance-api-db-migrator",
+    ]);
+  });
+
+  test("running dependency is not re-triggered", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "running",
+      dependencies: [{ name: "postgres", state: "running" }],
+    });
+    expect(action.tiltTriggerNames).toEqual([]);
+  });
+});
+
+describe("evaluateReadiness", () => {
+  test("ready once every required name reports healthy", () => {
+    const outcome = evaluateReadiness(["a", "b"], { a: true, b: true });
+    expect(outcome.ready).toBe(true);
+    expect(outcome.pending).toEqual([]);
+  });
+
+  test("not ready while some names are still unhealthy", () => {
+    const outcome = evaluateReadiness(["a", "b"], { a: true, b: false });
+    expect(outcome.ready).toBe(false);
+    expect(outcome.pending).toEqual(["b"]);
+  });
+
+  test("missing entries count as not healthy", () => {
+    const outcome = evaluateReadiness(["a", "b"], { a: true });
+    expect(outcome.ready).toBe(false);
+    expect(outcome.pending).toEqual(["b"]);
+  });
+});

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

@@ -0,0 +1,75 @@
+/**
+ * Pure decision logic for the wake gateway (see openspec/changes/prioritized-cold-start).
+ *
+ * The gateway sits behind a Traefik static (file-provider) route for every
+ * `sablier: {enable: true, deferStart: true}` resource. This module decides
+ * what to *do* given a snapshot of container state; the actual Docker/Tilt
+ * I/O and the healthcheck-polling loop live in server.ts, which is a thin
+ * wrapper around this so the decision itself stays testable without a live
+ * Docker daemon or Tilt instance.
+ */
+
+export type ContainerState = "absent" | "created" | "running" | "exited";
+
+export interface DependencySnapshot {
+  name: string;
+  state: ContainerState;
+}
+
+export interface WakeRequestSnapshot {
+  resourceContainerName: string;
+  resourceState: ContainerState;
+  dependencies: DependencySnapshot[];
+}
+
+export interface WakeAction {
+  /** Resources to `tilt trigger` (task 1.5: Tilt never cascades this on its own). */
+  tiltTriggerNames: string[];
+  /**
+   * Whether to also try Sablier's own Docker-level start for the resource.
+   * Only meaningful when the resource's container already exists (D2/D3):
+   * Sablier has nothing to manage for a container that was never created.
+   */
+  useSablierStart: boolean;
+}
+
+/**
+ * Decide which resources need `tilt trigger` and whether Sablier's Docker-level
+ * start also applies, given one point-in-time snapshot (D2/D3/D5).
+ */
+export function decideWakeAction(snapshot: WakeRequestSnapshot): WakeAction {
+  const tiltTriggerNames: string[] = [];
+
+  if (snapshot.resourceState !== "running") {
+    tiltTriggerNames.push(snapshot.resourceContainerName);
+  }
+  for (const dep of snapshot.dependencies) {
+    if (dep.state !== "running") {
+      tiltTriggerNames.push(dep.name);
+    }
+  }
+
+  const useSablierStart = snapshot.resourceState === "exited" || snapshot.resourceState === "created";
+
+  return { tiltTriggerNames, useSablierStart };
+}
+
+export interface WaitOutcome {
+  ready: boolean;
+  /** Names still not running/healthy when the wait ended (empty when ready). */
+  pending: string[];
+}
+
+/**
+ * Decide whether a set of health polls (resource + dependencies) means the
+ * request can be let through yet, or should keep waiting / time out.
+ * `healthy` maps each name from a WakeAction's tiltTriggerNames (plus the
+ * resource itself) to its latest observed health state.
+ */
+export function evaluateReadiness(
+  requiredNames: string[],
+  healthy: Record<string, boolean>,
+): WaitOutcome {
+  const pending = requiredNames.filter((name) => !healthy[name]);
+  return { ready: pending.length === 0, pending };
+}