@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/engine/topologies/platform/docker/layers/prisma/db_readiness.star

@@ -0,0 +1,98 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+"""
+DB Readiness Shell Fragment
+
+Generates the shell script block that:
+  1. Parses DB_HOST / DB_PORT from DATABASE_URL when the separate vars are absent
+  2. Loops with `nc` until PostgreSQL accepts connections (120 s timeout)
+
+Returns a plain string that is embedded verbatim inside migrate.sh.
+"""
+
+load('../../../../tilt/common/utils_debug.star', 'DEBUG_MODE')
+load(
+    './constants.star',
+    'DB_URL_HOSTPORT_NO_AUTH_SED',
+    'DB_URL_HOSTPORT_WITH_AUTH_SED',
+    'DEFAULT_DB_PORT',
+    'DEFAULT_DB_WAIT_TIMEOUT_SECS',
+)
+
+
+def _host_port_parse_block():
+    """
+    Extract DB_HOST_VAL / DB_PORT_VAL from DATABASE_URL when the individual
+    DB_HOST / DB_PORT env vars are not available.
+
+    Handles both:
+      postgresql://user:pass@host:port/db   (with auth)
+      postgresql://host:port/db             (without auth)
+    """
+    return (
+        "# Extract host and port for the readiness probe\n"
+        + "DB_HOST_VAL=\"$DB_HOST\"\n"
+        + "DB_PORT_VAL=\"$DB_PORT\"\n"
+        + "if [ -z \"$DB_HOST_VAL\" ]; then\n"
+        + "  HOSTPORT=$(printf '%s\\n' \"$DATABASE_URL\" | "
+        + DB_URL_HOSTPORT_WITH_AUTH_SED + " | head -n1)\n"
+        + "  if [ -z \"$HOSTPORT\" ]; then\n"
+        + "    HOSTPORT=$(printf '%s\\n' \"$DATABASE_URL\" | "
+        + DB_URL_HOSTPORT_NO_AUTH_SED + " | head -n1)\n"
+        + "  fi\n"
+        + "  if printf '%s\\n' \"$HOSTPORT\" | grep -q '^\\['; then\n"
+        + "    DB_HOST_VAL=$(printf '%s\\n' \"$HOSTPORT\" | sed -n 's/^\\[\\([^]]*\\)\\]\\(:[0-9][0-9]*\\)\\?$/\\1/p' || true)\n"
+        + "    DB_PORT_VAL=$(printf '%s\\n' \"$HOSTPORT\" | sed -n 's/^\\[[^]]*\\]:\\([0-9][0-9]*\\)$/\\1/p' || true)\n"
+        + "  else\n"
+        + "    DB_HOST_VAL=$(printf '%s\\n' \"$HOSTPORT\" | awk -F: '{print $1}' || true)\n"
+        + "    DB_PORT_VAL=$(printf '%s\\n' \"$HOSTPORT\" | awk -F: 'NF>1{print $NF}' || true)\n"
+        + "  fi\n"
+        + "fi\n"
+        + "DB_PORT_VAL=\"${DB_PORT_VAL:-" + DEFAULT_DB_PORT + "}\"\n"
+        + "if [ -z \"$DB_HOST_VAL\" ]; then\n"
+        + "  echo \"\\u274c ERROR: Unable to parse DB host from DATABASE_URL\"\n"
+        + "  exit 1\n"
+        + "fi\n"
+    )
+
+
+def _wait_loop_block(log_wait, log_ready, timeout_secs = DEFAULT_DB_WAIT_TIMEOUT_SECS):
+    """
+    nc-based polling loop.  Retries every second up to `timeout_secs`.
+    """
+    return (
+        log_wait
+        + "i=0\n"
+        + "while ! nc -z \"${DB_HOST_VAL}\" \"${DB_PORT_VAL}\"; do\n"
+        + "  i=$((i+1))\n"
+        + "  if [ $i -gt " + str(timeout_secs) + " ]; then\n"
+        + "    echo \"\\u274c Timeout waiting for DB at ${DB_HOST_VAL}:${DB_PORT_VAL}\"\n"
+        + "    exit 1\n"
+        + "  fi\n"
+        + "  sleep 1\n"
+        + "done\n"
+        + log_ready
+    )
+
+
+def db_readiness_script(timeout_secs = DEFAULT_DB_WAIT_TIMEOUT_SECS):
+    """
+    Return the complete shell fragment that waits for PostgreSQL to accept
+    connections before proceeding to migration.
+
+    Args:
+        timeout_secs: Seconds to wait before aborting (default: 120)
+    """
+    if DEBUG_MODE:
+        log_wait  = "echo \"\\u23f3 Waiting for PostgreSQL at ${DB_HOST_VAL}:${DB_PORT_VAL}...\"\n"
+        log_ready = "echo \"\\u2705 PostgreSQL is ready!\"\n"
+    else:
+        log_wait = ""
+        log_ready = ""
+
+    return (
+        _host_port_parse_block()
+        + _wait_loop_block(log_wait, log_ready, timeout_secs)
+    )
+
+DEBUG = {}

package/engine/topologies/platform/docker/layers/prisma/filesystem_setup.star

@@ -0,0 +1,131 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+"""
+Filesystem Setup Dockerfile Fragment
+
+Generates the RUN/COPY instructions that:
+  - Install Alpine utilities needed by migrate.sh at runtime (curl, jq, nc)
+  - Create required directories and fix ownership so Prisma can write generated files
+  - Ensure @prisma/engines is resolvable for the CLI (engines may land under
+    prisma/node_modules in Bun hoisting layouts)
+
+All functions return Dockerfile instruction strings.
+"""
+
+load(
+    '../bun_helpers.star',
+    'bun_hoisted_packages_symlink_fix',
+)
+load(
+    './constants.star',
+    'APP_BUN_STORE_DIR',
+    'APP_GENERATED_CLIENT_DIR',
+    'APP_NODE_MODULES_BIN_DIR',
+    'APP_NODE_MODULES_DIR',
+    'APP_PRISMA_DIR',
+    'APP_PRISMA_PACKAGE_DIR',
+    'APP_PRISMA_SCOPE_DIR',
+    'APP_SRC_DIR',
+    'BUN_USER',
+    'PRISMA_BIN_ABS_PATH',
+    'PRISMA_BIN_SYMLINK_TARGET',
+    'PRISMA_CONFIG_ABS_PATH',
+    'PRISMA_SCHEMA_PATH',
+)
+
+
+def apk_runtime_tools():
+    """
+    Install runtime utilities required by migrate.sh: bash, curl, jq, netcat-openbsd, postgresql-client.
+    """
+    return "RUN apk add --no-cache bash curl jq netcat-openbsd postgresql-client\n"
+
+
+def prisma_dir_and_permissions():
+    """
+    Create directories that Prisma writes to at runtime and ensure the `bun` user owns
+    them.  Handles both the standard `node_modules/.prisma/client` path and custom
+    output paths like `../src/generated` or `../generated-client`.
+    """
+    return (
+        "# Ensure Prisma can write generated files including custom output paths\n"
+        + "RUN mkdir -p " + APP_NODE_MODULES_DIR + " " + APP_SRC_DIR + " " + APP_GENERATED_CLIENT_DIR
+        + " && chown -R " + BUN_USER + ":" + BUN_USER
+        + " " + APP_PRISMA_DIR + " " + APP_NODE_MODULES_DIR + " " + APP_SRC_DIR + " " + APP_GENERATED_CLIENT_DIR
+        + " " + PRISMA_CONFIG_ABS_PATH + " || true\n"
+    )
+
+
+def prisma_engines_symlink():
+    """
+    Rebuild @prisma links from Bun's isolated store after cross-stage COPY.
+    Service-level node_modules symlinks are relative and can break when copied to
+    `/app/node_modules`. We relink from `/app/node_modules/.bun`.
+    
+    Handles two types of packages:
+    1. Nested packages: @prisma/client, @prisma/adapter-pg (under node_modules/@prisma/)
+    2. Top-level package: @prisma/engines (copied as real files, not symlinked)
+    """
+    return (
+        "# Re-link @prisma packages from Bun store so Prisma CLI can resolve engines\n"
+        # Written inline: the template this used to COPY is not shipped anywhere.
+        + "RUN cat > /usr/local/bin/prisma-runtime-relink.sh << 'EOF'\n"
+        + "#!/bin/sh\n"
+        + "set -e\n"
+        + "# Nested @prisma packages: replace the symlink into node_modules/.bun with a real copy.\n"
+        + "for name in client adapter-pg; do\n"
+        + "  src=$(ls -d /app/node_modules/.bun/@prisma+${name}@*/node_modules/@prisma/${name} 2>/dev/null | head -n 1 || true)\n"
+        + "  if [ -n \"$src\" ]; then\n"
+        + "    rm -rf /app/node_modules/@prisma/${name}\n"
+        + "    mkdir -p /app/node_modules/@prisma\n"
+        + "    cp -R \"$src\" /app/node_modules/@prisma/${name}\n"
+        + "  fi\n"
+        + "done\n"
+        + "# Top-level @prisma/engines: copy as real files, not a symlink.\n"
+        + "src=$(ls -d /app/node_modules/.bun/@prisma+engines@*/node_modules/@prisma/engines 2>/dev/null | head -n 1 || true)\n"
+        + "if [ -n \"$src\" ]; then\n"
+        + "  rm -rf /app/node_modules/@prisma/engines\n"
+        + "  mkdir -p /app/node_modules/@prisma\n"
+        + "  cp -R \"$src\" /app/node_modules/@prisma/engines\n"
+        + "fi\n"
+        + "EOF\n"
+        + "RUN chmod +x /usr/local/bin/prisma-runtime-relink.sh && /usr/local/bin/prisma-runtime-relink.sh\n"
+    )
+
+
+def prisma_config_inline():
+    """
+    Inline-generate /app/prisma.config.ts so Prisma v7 migration commands pick up
+    the datasource URL from the environment without requiring a build-time file copy.
+    """
+    return (
+        "# Prisma v7 migration commands require datasource.url in prisma.config.ts\n"
+        + "RUN cat > " + PRISMA_CONFIG_ABS_PATH + " << 'EOF'\n"
+        + "export default {\n"
+        + "  schema: '" + PRISMA_SCHEMA_PATH + "',\n"
+        + "  datasource: {\n"
+        + "    url: process.env.DATABASE_URL,\n"
+        + "  },\n"
+        + "};\n"
+        + "EOF\n"
+    )
+
+
+def migrator_filesystem_setup():
+    """
+    Convenience wrapper – returns all filesystem setup instructions in order:
+      1. Inline prisma.config.ts
+      2. Permission fixes
+      3. @prisma/engines symlink
+      4. Alpine utilities
+      5. General Bun hoisted packages symlink fix
+
+    The caller is responsible for wrapping these in `USER root` / `USER bun` guards.
+    """
+    return (
+        prisma_config_inline()
+        + prisma_dir_and_permissions()
+        + prisma_engines_symlink()
+        + apk_runtime_tools()
+        + bun_hoisted_packages_symlink_fix()
+    )

package/engine/topologies/platform/docker/layers/prisma/migrate_script.star

@@ -0,0 +1,100 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+"""
+Migrate Script Builder
+
+Assembles the complete /app/migrate.sh entrypoint that runs inside the
+l4_migrator_runtime container.  Delegates each logical section to a
+dedicated module so this file stays focused on overall script structure.
+
+  secret_resolution  – resolves DATABASE_URL (Infisical or env vars)
+  db_readiness       – waits for PostgreSQL to accept connections
+"""
+
+load('../../../../tilt/common/utils_debug.star', 'DEBUG_MODE')
+load('./secret_resolution.star', 'secret_resolution_script')
+load('./db_readiness.star', 'db_readiness_script')
+load(
+    './constants.star',
+    'APP_DIR',
+    'MIGRATE_SH_ABS_PATH',
+    'PRISMA_BIN_ABS_PATH',
+    'PRISMA_GENERATE_SUBCOMMAND',
+    'PRISMA_MIGRATE_DEPLOY_SUBCOMMAND',
+)
+
+
+def _log(debug_msg, prod_msg = ""):
+    """Return debug_msg when DEBUG_MODE is on, prod_msg otherwise."""
+    return debug_msg if DEBUG_MODE else prod_msg
+
+
+def _prisma_run_block():
+    """
+    Shell fragment that locates the local Prisma CLI binary and runs
+    `migrate deploy` followed by `generate`.  Avoids `bunx prisma` to
+    prevent accidental network fetches of the latest Prisma version.
+    """
+    return (
+        "# Use locally installed Prisma CLI – avoids bunx fetching prisma@latest\n"
+        + "PRISMA_BIN=\"" + PRISMA_BIN_ABS_PATH + "\"\n"
+        + "if [ ! -x \"$PRISMA_BIN\" ]; then\n"
+        + "  echo \"\\u274c ERROR: Prisma CLI not found at $PRISMA_BIN\"\n"
+        + "  exit 1\n"
+        + "fi\n"
+        + "# Ensure DATABASE_URL is exported for Prisma CLI\n"
+        + "export DATABASE_URL\n"
+        + _log("echo \"\\U0001f504 Running Prisma migrations...\"\n")
+        + "cd " + APP_DIR + " && \"$PRISMA_BIN\" " + PRISMA_MIGRATE_DEPLOY_SUBCOMMAND + "\n"
+        + _log("echo \"\\U0001f527 Generating Prisma client...\"\n")
+        + "\"$PRISMA_BIN\" " + PRISMA_GENERATE_SUBCOMMAND + "\n"
+    )
+
+
+def migrate_sh_content(resource_name):
+    """
+    Return the full text of migrate.sh for the given service.
+
+    Args:
+        resource_name: Used in RESOURCE_NAME env var and Infisical secret path
+                      (e.g. 'user-service', 'order-service').
+    """
+    done_msg = (
+        _log("echo \"\\U0001f389 Database migration completed successfully!\"\n")
+        or "echo \"Database migration completed\"\n"
+    )
+
+    return (
+        "#!/bin/sh\n"
+        + "set -e\n"
+        + _log(
+            "echo \"\\U0001f5c4\\ufe0f Starting database migration for $RESOURCE_NAME...\"\n",
+            "echo \"Starting database migration...\"\n",
+        )
+        + "\n# --- 1. Resolve DATABASE_URL ---\n"
+        + secret_resolution_script()
+        + "\n# --- 2. Wait for PostgreSQL ---\n"
+        + db_readiness_script()
+        + "\n# --- 3. Run Prisma migrate + generate ---\n"
+        + _prisma_run_block()
+        + "\n"
+        + done_msg
+    )
+
+
+def migrate_sh_dockerfile_block(resource_name):
+    """
+    Return the Dockerfile fragment that writes migrate.sh and makes it executable.
+
+    Args:
+        resource_name: Forwarded to migrate_sh_content().
+    """
+    return (
+        "# Provide the migrate entrypoint\n"
+        + "RUN cat > " + MIGRATE_SH_ABS_PATH + " << 'EOF'\n"
+        + migrate_sh_content(resource_name)
+        + "EOF\n"
+        + "RUN chmod +x " + MIGRATE_SH_ABS_PATH + "\n"
+    )
+
+DEBUG = {}

package/engine/topologies/platform/docker/layers/prisma/prisma_build.star

@@ -0,0 +1,128 @@
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# === INLINED CONSTANTS for pure extension loading ===
+OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
+# === END INLINED CONSTANTS ===
+
+
+"""
+Prisma Build Layers - L3 Prisma Client Generation and Migration Engine
+
+Encapsulates all Prisma-related Dockerfile instructions for the build stage:
+- Client generation (`bunx prisma generate`)
+- Output normalization (generated-client ↔ node_modules/.prisma/client)
+- Default module shim for Prisma v7 / @prisma/client compatibility
+- Migration engine stage for Prisma migrate deploy
+"""
+
+load('../l1_base_layers.star', 'BUN_BASE')
+load('../l2_dependency_layers.star', 'normalize_res_path')
+load('../../../../../../discovery/config.star', 'GLOBAL_CONFIG')
+load('../../../../tilt/manifest/constants.star', 'AUTOGENERATED_CONFIG_PATHS')
+
+load(
+    './constants.star',
+    'APP_BUN_STORE_DIR',
+    'DEFAULT_GOLDEN_L3_MIGRATOR_IMAGE',
+    'NODE_MODULES_DIR',
+    'PRISMA_CONFIG_WORKDIR_PATH',
+    'PRISMA_DIR_NAME',
+    'PRISMA_GENERATE_RUN',
+    'PRISMA_PACKAGE_NODE_MODULES_REL_PATH',
+    'PRISMA_SCHEMA_PATH',
+    'app_resource_dir',
+    'prisma_normalize_output_block',
+)
+
+_docker_cfg = GLOBAL_CONFIG['docker']
+GOLDEN_L3_MIGRATOR_IMAGE = _docker_cfg.get('golden_l3_migrator_image', DEFAULT_GOLDEN_L3_MIGRATOR_IMAGE)
+
+
+def prisma_copy_instructions(res_path, has_prisma_config = False):
+    """
+    Generate Dockerfile COPY instructions for Prisma schema and config.
+
+    Args:
+        res_path: Resource path (service directory)
+        has_prisma_config: Whether prisma.config.ts exists (Prisma v7)
+
+    Returns:
+        Dockerfile content string for copying Prisma files
+    """
+    # Normalize res_path for Docker COPY (must be relative to build context)
+    res_path_rel = normalize_res_path(res_path)
+    
+    parts = "COPY " + res_path_rel + "/" + PRISMA_DIR_NAME + " ./" + PRISMA_DIR_NAME + "\n"
+    if has_prisma_config:
+        # Prisma v7 requires prisma.config.ts in CWD for correct client generation
+        parts += "COPY " + res_path_rel + "/" + AUTOGENERATED_CONFIG_PATHS['prisma'] + " " + PRISMA_CONFIG_WORKDIR_PATH + "\n"
+    return parts
+
+
+def prisma_generate_instructions():
+    """
+    Generate Dockerfile RUN instruction for Prisma client generation.
+
+    Returns:
+        Dockerfile content string that runs `bunx prisma generate`
+    """
+    return PRISMA_GENERATE_RUN
+
+
+def prisma_normalize_output():
+    """
+    Generate Dockerfile instructions to normalize Prisma output for both
+    import styles: ../generated-client and node_modules/.prisma/client.
+
+    Also creates a default.js shim required by @prisma/client v7 which
+    resolves `.prisma/client/default` at runtime.
+
+    Returns:
+        Dockerfile content string for Prisma output normalization
+    """
+    return prisma_normalize_output_block(include_generated_client_export = True)
+
+
+def L3_generate_migration_engine(res_path, use_golden = True):
+    """
+    Generate the migration engine layer for Prisma database migrations.
+
+    Args:
+        res_path: Resource path (service directory)
+        use_golden: Whether to use golden L3-migrator image (default: True)
+
+    Returns:
+        Dockerfile content string for the l3_migration_build stage
+    """
+    # Normalize res_path for Docker COPY (must be relative to build context)
+    res_path_rel = normalize_res_path(res_path)
+    
+    # Use golden L3-migrator image if enabled (Prisma pre-installed)
+    base_image = GOLDEN_L3_MIGRATOR_IMAGE if use_golden else BUN_BASE
+    app_res_path = app_resource_dir(res_path)
+
+    return (
+        "# ---- L3: migration_engine ----\n"
+        + "FROM " + base_image + " AS l3_migration_build\n"
+        + "WORKDIR " + app_res_path + "\n"
+        + "# Copy manifest files for dependency installation\n"
+        + "COPY " + res_path_rel + "/package.json ./package.json\n"
+        + "COPY " + res_path_rel + "/" + PRISMA_DIR_NAME + " ./" + PRISMA_DIR_NAME + "\n"
+        + "COPY " + res_path_rel + "/" + OUTPUT.AUTOGENERATED_FOLDER + "/.npmrc.docker.autogenerated .npmrc\n"
+        + "COPY " + res_path_rel + "/" + OUTPUT.AUTOGENERATED_FOLDER + "/bunfig.docker.autogenerated.toml ./bunfig.toml\n"
+        + "COPY bun.lock* ./\n"
+        + "# Install runtime deps only for migrator image (skip test/dev toolchain)\n"
+        + "# NOTE: keep bunfig.toml (it carries the project/@tdk-landscape registry\n"
+        + "# scopes pointing at Verdaccio) - deleting it forces scoped packages to fall\n"
+        + "# back to the public npm registry and fail with ConnectionRefused/404.\n"
+        + "RUN --mount=type=cache,target=/cache/bun,sharing=shared rm -f bun.lock bun.lockb && env -u CI BUN_CONFIG_FROZEN_LOCKFILE=false BUN_TMPDIR=/tmp BUN_INSTALL=/tmp/bun-install bun install --production --no-frozen-lockfile --concurrent-scripts --cache-dir=/cache/bun\n"
+        + "# Prisma CLI is often in devDependencies; install it explicitly without mutating manifest files\n"
+        + "RUN --mount=type=cache,target=/cache/bun,sharing=shared PRISMA_VERSION=$(sed -n 's/.*\"prisma\"[[:space:]]*:[[:space:]]*\"[~^]*\\([^\"]*\\)\".*/\\1/p' package.json | head -n 1) && [ -n \"$PRISMA_VERSION\" ] && BUN_TMPDIR=/tmp BUN_INSTALL=/tmp/bun-install bun add --no-save --exact prisma@\"$PRISMA_VERSION\" --cache-dir=/cache/bun\n"
+        + "# Generate Prisma client and normalize output location for runtime compatibility\n"
+        + PRISMA_GENERATE_RUN
+        + prisma_normalize_output_block(include_generated_client_export = False)
+        + "RUN mkdir -p " + PRISMA_PACKAGE_NODE_MODULES_REL_PATH + "\n"
+        + "RUN test -f " + PRISMA_SCHEMA_PATH + "\n"
+    )
+
+GLOBAL_CONFIG = {}

package/engine/topologies/platform/docker/layers/prisma/prisma_runtime.star

@@ -0,0 +1,205 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+"""
+Prisma Runtime Layers - L4 Prisma Runtime Copy and Resolution
+
+Public API (preserved for backward compatibility with l4_runtime_layers.star):
+  prisma_runtime_copy(res_path)       – copy .prisma artifacts from build stage
+  prisma_cli_runtime_copy(res_path)   – copy the pinned Prisma CLI into the runtime
+  prisma_bun_symlink_fix()            – fix Bun linker resolution for .prisma/client
+  prisma_config_copy(res_path)        – copy prisma.config.ts (Prisma v7)
+  L4_generate_migrator_runtime(...)   – full migrator stage (delegates to sub-modules)
+
+Internal heavy-lifting is split across:
+  filesystem_setup.star   – apk, dirs, permissions, engines symlink
+  shared docker template  – generic migrate.sh entrypoint script
+"""
+
+load('../l1_base_layers.star', 'BUN_BASE')
+load('../l2_dependency_layers.star', 'normalize_res_path')
+load('../../../../../../discovery/config.star', 'GLOBAL_CONFIG')
+load('../../../../tilt/manifest/constants.star', 'AUTOGENERATED_CONFIG_PATHS')
+load('./filesystem_setup.star', 'migrator_filesystem_setup')
+load('./migrate_script.star', 'migrate_sh_dockerfile_block')
+load(
+    './constants.star',
+    'APP_DIR',
+    'BUN_USER',
+    'L3_MIGRATION_BUILD_STAGE',
+    'DEFAULT_GOLDEN_L4_MIGRATOR_IMAGE',
+    'MIGRATE_SH_ABS_PATH',
+    'PRISMA_CONFIG_WORKDIR_PATH',
+    'PRISMA_DOT_DIR_REL_PATH',
+    'PRISMA_DIR_NAME',
+    'PRISMA_PACKAGE_REL_PATH',
+    'PRISMA_BIN_REL_PATH',
+    'NODE_MODULES_BIN_DIR',
+    'PRISMA_BIN_SYMLINK_TARGET',
+    'ROOT_USER',
+    'app_resource_dir',
+    'resource_node_modules_dir',
+)
+
+_docker_cfg = GLOBAL_CONFIG['docker']
+GOLDEN_L4_MIGRATOR_IMAGE = _docker_cfg.get('golden_l4_migrator_image', DEFAULT_GOLDEN_L4_MIGRATOR_IMAGE)
+
+
+# ---------------------------------------------------------------------------
+# Small copy/fix helpers (used by l4_runtime_layers.star for backend runtime)
+# ---------------------------------------------------------------------------
+
+def prisma_runtime_copy(res_path):
+    """
+    Copy .prisma generated client and prisma schema from the build stage.
+
+    Args:
+        res_path: Service directory relative to /app (e.g. 'services/product/users/...')
+    """
+    base = app_resource_dir(res_path)
+    return (
+        "COPY --from=l3_backend_build " + base + "/" + PRISMA_DOT_DIR_REL_PATH + " ./" + PRISMA_DOT_DIR_REL_PATH + "\n"
+        + "COPY --from=l3_backend_build " + base + "/" + PRISMA_DIR_NAME + " ./" + PRISMA_DIR_NAME + "\n"
+    )
+
+
+def prisma_cli_runtime_copy(res_path):
+    """
+    Copy the pinned Prisma CLI package into the backend runtime image.
+
+    The runtime node_modules come from l3_production_purger, which runs
+    `bun install --production` and then deletes every `.bin` directory, so the
+    Prisma CLI (a devDependency) is absent.  The entrypoint's auto-migration
+    would then fall back to `bunx prisma`, which downloads prisma@latest from
+    npm on every container start – slow at best, and a boot hang that fails the
+    healthcheck (and so blocks Traefik routing) on a slow network.
+
+    l3_migration_build already installs the CLI at the exact version pinned in
+    package.json, so reuse that instead of fetching at runtime.
+
+    Args:
+        res_path: Service directory relative to /app (e.g. 'services/app/dashboard-api')
+    """
+    base = resource_node_modules_dir(res_path)
+    return (
+        "# Prisma CLI at the version pinned in package.json - the entrypoint runs\n"
+        + "# migrations with it instead of `bunx prisma`, which would fetch prisma@latest.\n"
+        + "COPY --from=" + L3_MIGRATION_BUILD_STAGE + " " + base + "/" + PRISMA_DIR_NAME
+        + " ./" + PRISMA_PACKAGE_REL_PATH + "\n"
+        # bunx resolves a command against node_modules/.bin BEFORE considering a
+        # registry fetch - without this symlink it can't tell the CLI is already
+        # installed and falls back to `bun add prisma@latest` over the network.
+        # Needs root: at this point in the golden image we're already running
+        # as the unprivileged bun user, which doesn't own node_modules/.bin.
+        + "USER " + ROOT_USER + "\n"
+        # Relative to WORKDIR (/app/<res_path> here, unlike the migrator stage
+        # where WORKDIR is plain /app) - PRISMA_BIN_ABS_PATH assumes the latter
+        # and would point outside this service's node_modules entirely.
+        + "RUN mkdir -p " + NODE_MODULES_BIN_DIR
+        + " && ln -sf " + PRISMA_BIN_SYMLINK_TARGET + " ./" + PRISMA_BIN_REL_PATH
+        + " && chown -h " + BUN_USER + ":" + BUN_USER + " ./" + PRISMA_BIN_REL_PATH + "\n"
+        + "USER " + BUN_USER + "\n"
+    )
+
+
+def prisma_bun_symlink_fix():
+    """
+    Symlink .prisma/client into every Bun linker path so runtime imports resolve.
+
+    Bun hoists @prisma/client under node_modules/.bun/@prisma+client*/node_modules/
+    and looks for .prisma relative to that path.  The loop below covers all versions
+    that may be present.
+    """
+    return (
+        "# Fix Bun module resolution: .prisma/client must be reachable from .bun/ linker paths\n"
+        + "USER " + ROOT_USER + "\n"
+        + "COPY shared-platform-engineering/docker-templates/prisma-bun-client-link-fix.sh /usr/local/bin/prisma-bun-client-link-fix.sh\n"
+        + "RUN chmod +x /usr/local/bin/prisma-bun-client-link-fix.sh && /usr/local/bin/prisma-bun-client-link-fix.sh\n"
+        + "USER " + BUN_USER + "\n"
+    )
+
+
+def prisma_config_copy(res_path):
+    """
+    Copy the auto-generated prisma.config.ts into the WORKDIR (required by Prisma v7).
+
+    Args:
+        res_path: Service directory relative to workspace root
+    """
+    # Normalize res_path for Docker COPY (must be relative to build context)
+    res_path_rel = normalize_res_path(res_path)
+    return "COPY " + res_path_rel + "/" + AUTOGENERATED_CONFIG_PATHS['prisma'] + " " + PRISMA_CONFIG_WORKDIR_PATH + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Migrator stage builder
+# ---------------------------------------------------------------------------
+
+def _migrator_artifact_copies(res_path):
+    """
+    Runtime setup for migrator:
+      1. Copy schema from l3 migration build stage
+      2. Copy resolved node_modules from l3 migration build stage
+
+    This avoids Bun lockfile/frozen-lockfile edge cases in the l4 runtime image
+    while still keeping migrator logic simple (no pruner stage).
+    """
+    app_res_path = app_resource_dir(res_path)
+    base = resource_node_modules_dir(res_path)
+    return (
+        "# Copy migration schema + resolved deps from l3 stage\n"
+        + "COPY --from=l3_migration_build " + app_res_path + "/" + PRISMA_DIR_NAME + " ./" + PRISMA_DIR_NAME + "\n"
+        + "COPY --from=l3_migration_build " + base + " ./node_modules\n"
+    )
+
+
+def _migrate_script_copy_block(resource_name):
+    """
+    Write the migrate entrypoint inline. It used to be COPYed from
+    shared-platform-engineering/docker-templates, a file no package ships, so the
+    migrator image could not build.
+    """
+    return migrate_sh_dockerfile_block(resource_name)
+
+
+def L4_generate_migrator_runtime(res_path, resource_name = 'migrator', use_golden = True):
+    """
+    Generate the complete l4_migrator_runtime Dockerfile stage.
+
+    The stage:
+      1. Copies Prisma artifacts from l3_migration_build
+      2. Writes prisma.config.ts, fixes permissions, symlinks engines (filesystem_setup)
+      3. Installs Alpine utilities (curl, jq, nc) needed at runtime
+      4. Copies and chmod's /app/migrate.sh from shared docker templates
+      5. Sets ENTRYPOINT to migrate.sh
+
+    Args:
+        res_path:     Service directory relative to /app
+        resource_name: Used in RESOURCE_NAME env and Infisical secret path
+        use_golden:   Always True – golden image is always preferred
+    """
+    # Golden image is mandatory – it ships Prisma + Infisical pre-built.
+    base_image = GOLDEN_L4_MIGRATOR_IMAGE
+
+    return (
+        "# ---- L4: migrator_runtime ----\n"
+        + "FROM " + base_image + " AS l4_migrator_runtime\n"
+        + "WORKDIR " + APP_DIR + "\n"
+        + "# Build argument to skip Infisical setup (for local dev / fast builds)\n"
+        + "ARG SKIP_INFISICAL_SETUP=0\n"
+        + "ENV NODE_ENV=production RESOURCE_NAME=" + resource_name + "\n"
+        + _migrator_artifact_copies(res_path)
+        + "USER " + ROOT_USER + "\n"
+        + migrator_filesystem_setup()
+        + "USER " + ROOT_USER + "\n"
+        + _migrate_script_copy_block(resource_name)
+        # Migrators are one-shot jobs; they should not inherit long-running
+        # service healthchecks (e.g. HTTP probes on localhost:3000) from base layers.
+        + "HEALTHCHECK NONE\n"
+        + "USER " + BUN_USER + "\n"
+        + "ENTRYPOINT [\"" + MIGRATE_SH_ABS_PATH + "\"]\n"
+        + "\nFROM l4_migrator_runtime AS migrator\n"
+        + "FROM l4_migrator_runtime AS production\n"
+        + "FROM l4_migrator_runtime AS development\n"
+    )
+
+GLOBAL_CONFIG = {}