@flisk-sh/flisk 0.0.0-stage → 1.3.190

package/engine/topologies/tilt/resources/orchestrator/apply_compose_resource_registration.star

@@ -0,0 +1,864 @@
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 🧩 ORCHESTRATOR APPLY - COMPOSE RESOURCE REGISTRATION (Refactored)
+# =============================================================================
+
+# === INLINED CONSTANTS for pure extension loading ===
+OUTPUT = struct(AUTOGENERATED_FOLDER = ".autogenerated")
+# === END INLINED CONSTANTS ===
+
+
+load("../../common/utils_debug.star", "debug_log")
+load('../../../platform/docker/index.star', 'Docker')
+load('../../../platform/docker/build/frontend_build_plan.star', 'frontend_build_plan')
+load('../../../platform/docker/constants.star', 'PlatformDockerConstants')
+load('../../../tilt/manifest/constants.star', 'BASE_PORT_FRONTEND', 'BASE_PORT_BACKEND')
+load('../../../platform/docker/networking/traefik_static_routes.star', 'generate_static_wake_route', 'normalize_abs_path')
+load('../../../platform/docker/networking/sablier_container_cycle.star', 'sablier_middleware_suffix')
+# Shared platform Postgres force-start path. infra-loader.star must not load
+# apply_compose (no circular load): it only loads platform/docker + registries.
+load('../infra-loader.star', 'Infra')
+load('../shared-platform-postgres.star',
+     _shared_postgres_names = 'SHARED_POSTGRES_DEPENDENCY_NAMES',
+     _is_shared_platform_postgres_dependency = 'is_shared_platform_postgres_dependency',
+     _manifest_needs_shared_platform_postgres = 'manifest_needs_shared_platform_postgres')
+
+load('./builders/typescript.star', 'TypescriptBuilders')
+
+
+# Public wrappers for shared platform Postgres helpers. Starlark `load` does not
+# re-export loaded names. Canonical list + predicates live in
+# shared-platform-postgres.star — do not hardcode a second copy of the names here.
+
+def is_shared_platform_postgres_dependency(name):
+    """True when a dependsOn name is one of the shared platform Postgres aliases."""
+    return _is_shared_platform_postgres_dependency(name)
+
+
+def manifest_needs_shared_platform_postgres(manifest):
+    """True when a manifest's dependsOn lists postgres or database-management."""
+    return _manifest_needs_shared_platform_postgres(manifest)
+
+
+def selected_for_shared_platform_postgres(name, ctx):
+    """Use the same focus selection later passed to set_enabled_resources."""
+    if not ctx.get('focus_mode', False):
+        return True
+    return name in (ctx.get('focus_enabled_resources') or [])
+
+
+def force_start_shared_platform_postgres_once(ctx, should_enable, resource_name=""):
+    """Force-start shared platform Postgres at most once per Tiltfile evaluation.
+
+    `register_compose_resources` runs per stack and can see unselected nested
+    services; two selected services that both `dependsOn` Postgres would otherwise call
+    `Infra.force_start_postgres` twice (docker_compose + dc_resource each time).
+    Module-level mutable flags are unusable — Tilt freezes Starlark globals — so
+    the guard lives on `ctx`, a dict the Tiltfile already owns for this run.
+
+    Returns True when this call performed the force-start, False when it skipped
+    (already started this run, or database-management is already on).
+    """
+    if ctx.get('_shared_platform_postgres_force_started', False):
+        debug_log("COMPOSE: shared platform Postgres already force-started this run; skip for '{}'".format(resource_name))
+        return False
+    if should_enable('database-management'):
+        return False
+    project_root_for_env = ctx.get('project_root', '')
+    root_prefix = (project_root_for_env + '/') if project_root_for_env else ''
+    env_candidate = (project_root_for_env + '/.env') if project_root_for_env else '.env'
+    env_file = _env_file_if_exists(env_candidate)
+    write_fn = ctx.get('write_file', None)
+    if write_fn == None:
+        fail("dependsOn postgres/database-management on selected resource '{}' requires ctx.write_file to materialize services/platform/database-management/docker-compose.yml".format(resource_name))
+    debug_log("COMPOSE: force-starting shared platform Postgres once (selected '{}' dependsOn)".format(resource_name))
+    Infra.force_start_postgres(should_enable, root_prefix=root_prefix, env_file=env_file, write_fn=write_fn)
+    ctx['_shared_platform_postgres_force_started'] = True
+    return True
+
+
+def _env_file_if_exists(env_file):
+    """.env is gitignored (no .env.example shipped) across every Flisk example repo, so a
+    fresh clone must not hard-require it: docker_compose()'s env_file kwarg type-checks as
+    path|string (rejects None), so only return a path when the file actually exists."""
+    exists = str(local("test -f '" + env_file + "' && echo yes || echo no", quiet=True, echo_off=True)).strip() == 'yes'
+    return env_file if exists else None
+
+
+def _docker_compose_app(compose_paths, project_name, env_file):
+    resolved_env_file = _env_file_if_exists(env_file)
+    if resolved_env_file:
+        docker_compose(compose_paths, project_name=project_name, env_file=resolved_env_file)
+    else:
+        docker_compose(compose_paths, project_name=project_name)
+
+
+def _build_infra_dependencies(resource_name, should_enable, ctx, has_backend=False):
+    infra_deps = []
+    if should_enable('database-management'):
+        infra_deps.append('postgres')
+        if has_backend:
+            infra_deps.append('provision-db-' + resource_name)
+    if should_enable(PlatformDockerConstants.VERDACCIO_RESOURCE_NAME):
+        project_root = ctx.get('project_root', '')
+        verdaccio_compose = ((project_root.rstrip('/') + '/') if project_root else '') + 'docker-compose.verdaccio.yml'
+        if str(local("test -f '" + verdaccio_compose + "' && echo yes || echo no", quiet=True, echo_off=True)).strip() == 'yes':
+            infra_deps.append(PlatformDockerConstants.VERDACCIO_RESOURCE_NAME)
+    if should_enable('golden-image') and ctx.get('golden_image_resource'):
+        infra_deps.append(ctx['golden_image_resource'])
+    return infra_deps
+
+
+def _resolve_dependency_to_resource(dep_name, all_services_map):
+    """
+    Resolve a short dependency name (e.g., 'identity') to the full YAML resource name.
+
+    The discovery registry creates YAML resources with names like:
+    - 'identity-management-backend-yaml' for identity backend
+    - 'api-gateway-yaml' for api-gateway
+
+    But manifests reference them as short names like 'identity' or 'api-gateway'.
+
+    Shared platform Postgres aliases (`postgres`, `database-management`) resolve
+    to the literal Tilt resource `postgres` in BOTH feature states — they must
+    NOT fall through to `postgres-yaml` or any other name.
+    """
+    # Shared platform Postgres: exact names only (typos stay on the normal path).
+    if is_shared_platform_postgres_dependency(dep_name):
+        return 'postgres'
+
+    # Check if already a full YAML resource name
+    if dep_name in all_services_map:
+        return dep_name
+
+    # Try with -yaml suffix (for resources already resolved)
+    yaml_name = dep_name + '-yaml'
+    if yaml_name in all_services_map:
+        return yaml_name
+
+    # Try to find matching service by stack/short name
+    for resource_name, resource_info in all_services_map.items():
+        # Check if this service's stack matches the dependency
+        resource_domain = resource_info.get('stack', '')
+        if resource_domain == dep_name:
+            # Return the first resource of this service with -yaml suffix
+            resources = resource_info.get('resources', [])
+            if resources:
+                # Prefer backend resources over frontends
+                for res in resources:
+                    if not res.get('frontend', False):
+                        return res['name'] + '-yaml'
+                # Fallback to first resource
+                return resources[0]['name'] + '-yaml'
+
+    # Try pattern matching: identity -> identity-*-yaml
+    for resource_name in all_services_map.keys():
+        if resource_name.startswith(dep_name + '-') and resource_name.endswith('-yaml'):
+            return resource_name
+
+    # Return original with -yaml suffix as last resort
+    return dep_name + '-yaml'
+
+
+def resolve_dependency_to_resource(dep_name, all_services_map):
+    """Public wrapper over `_resolve_dependency_to_resource` (exported for tests)."""
+    return _resolve_dependency_to_resource(dep_name, all_services_map)
+
+
+def build_infra_dependencies(resource_name, should_enable, ctx=None, has_backend=False):
+    """Public wrapper over `_build_infra_dependencies` (exported for tests).
+
+    feature off → no postgres; feature on → has postgres (plus backend
+    provision-db edge when has_backend is true).
+    """
+    return _build_infra_dependencies(resource_name, should_enable, ctx if ctx != None else {}, has_backend)
+
+
+def build_resource_deps(res, res_name, manifest, resource_config, infra_deps, config_gen_resources=None, resource_manifests=None, runtime_flags=None, all_services_map=None):
+    """Public wrapper over `_build_resource_deps` (exported for tests).
+
+    Ensures the dependsOn→resource_deps edge is exercised by tests: feature off
+    + dependsOn postgres → postgres edge present; feature on + dependsOn →
+    exactly one postgres edge (infra_deps already carries it).
+    """
+    default_runtime_flags = {
+        'enforce_migrator_deps': False,
+        'auto_init_apps': True,
+        'disable_app_replicas': False,
+    }
+    return _build_resource_deps(
+        res, res_name, manifest, resource_config, infra_deps,
+        config_gen_resources if config_gen_resources != None else {},
+        resource_manifests if resource_manifests != None else {},
+        runtime_flags if runtime_flags != None else default_runtime_flags,
+        all_services_map,
+    )
+
+
+def _build_resource_deps(res, res_name, manifest, resource_config, infra_deps, config_gen_resources, resource_manifests, runtime_flags, all_services_map=None):
+    # Drop self-deps: shared infra_deps always includes verdaccio when enabled, so
+    # registering verdaccio itself would otherwise produce resource_deps=['verdaccio'].
+    res_deps = [dep for dep in infra_deps if dep != res_name]
+    if res_name in config_gen_resources:
+        res_deps.append(config_gen_resources[res_name])
+    if res.get('frontend', False):
+        backend_name = manifest.get('backendName', res_name.replace('frontend', 'backend'))
+        if backend_name != res_name and backend_name in resource_manifests:
+            res_deps.append(backend_name)
+    elif runtime_flags['enforce_migrator_deps'] and resource_config.get('has_migrator', False):
+        migrator_name = resource_config['name'] + '-db-migrator'
+        if migrator_name not in res_deps:
+            res_deps.append(migrator_name)
+    
+    # NEW: Resolve dependsOn from manifest
+    internal_deps = manifest.get('dependsOn', [])
+    for dep in internal_deps:
+        resolved_dep = _resolve_dependency_to_resource(dep, all_services_map)
+        if resolved_dep and resolved_dep != res_name and resolved_dep not in res_deps:
+            res_deps.append(resolved_dep)
+    
+    return res_deps
+
+
+def resource_defers_start(manifest):
+    """True when a manifest opts into `sablier.enable` + `sablier.deferStart`
+    AND the licensed sablier module is actually active.
+
+    deferStart stays behind the same TDK_LICENSE_KEY gate as the rest of
+    `sablier` (an explicit product decision, not just the opt-in manifest
+    flag): the free-tier stub's sablier_middleware_suffix() always reports
+    `enabled=False` regardless of what the manifest says, so checking through
+    it here -- rather than reading manifest['sablier']['enable'] directly --
+    is what keeps deferStart off for unlicensed projects. Without this check,
+    a project with no license would still get "no container created or
+    started," silently bypassing the license boundary for the disable-the-
+    container half of the feature even though the Docker-label wake half
+    stays correctly disabled.
+
+    A deferred resource's image still builds (docker_build has no auto_init
+    gate), but its dc_resource/run-only/replica resources are held back with
+    auto_init=False: no container is created or started until the Traefik
+    static route wakes it on first request (see openspec/changes/
+    prioritized-cold-start)."""
+    _, sablier_licensed_and_enabled = sablier_middleware_suffix(manifest, '')
+    sablier = manifest.get('sablier', {}) if manifest else {}
+    defers_start = bool(sablier.get('enable', False) and sablier.get('deferStart', False))
+    if defers_start and not sablier_licensed_and_enabled:
+        print("⚠️  '{}' requests sablier.deferStart but the licensed Sablier overlay is disabled; starting normally".format(manifest.get('name', 'resource')))
+    if not sablier_licensed_and_enabled:
+        return False
+    return defers_start
+
+
+def resolve_manifest_dependency_names(manifest, all_services_map):
+    """Resolve a manifest's `dependsOn` short names to full resource names,
+    reusing the same `_resolve_dependency_to_resource` that `_build_resource_deps`
+    already trusts for Tilt's own resource_deps ordering -- an ambiguous name
+    behaves identically here as it already does there."""
+    resolved = []
+    for dep in (manifest.get('dependsOn', []) if manifest else []):
+        resolved_dep = _resolve_dependency_to_resource(dep, all_services_map)
+        if resolved_dep and resolved_dep not in resolved:
+            resolved.append(resolved_dep)
+    return resolved
+
+
+def resolve_defer_start_dependencies(manifest, resource_manifests, all_services_map):
+    """Of a deferStart resource's manifest dependencies, resolve the subset
+    that are themselves deferStart resources, for the wake gateway's
+    X-Wake-Deps (see generate_static_wake_route's `dependencies` param and
+    openspec/changes/prioritized-cold-start design.md D5).
+
+    A dependsOn name `_resolve_dependency_to_resource` can't map to an exact
+    resource (its own fallback branches -- see that function) won't be a key
+    in `resource_manifests` either, so it's quietly excluded here rather than
+    guessed at -- consistent with D5's existing stance. Always-on infra
+    (database, NATS) is never itself a deferStart resource (D5), so in
+    practice this only ever picks up the one case D5 flags as mattering: a
+    deferStart resource depending on another."""
+    dependencies = []
+    for resolved_dep in resolve_manifest_dependency_names(manifest, all_services_map):
+        dep_manifest = resource_manifests.get(resolved_dep)
+        if not dep_manifest or not resource_defers_start(dep_manifest):
+            continue
+        dep_service_name = all_services_map.get(resolved_dep, {}).get('name', '')
+        if not dep_service_name:
+            continue
+        dependencies.append((resolved_dep, PlatformDockerConstants.compose_project_name(dep_service_name)))
+    return dependencies
+
+
+def _register_replicas(config, auto_init_apps):
+    """Register additional replica resources for high-availability services."""
+    replicas = config.get('replicas', 1)
+    if replicas <= 1:
+        return
+    # Docker compose generates replicas starting from 1 (e.g., service-1, service-2)
+    # Primary is the base name (service), replicas are service-1, service-2, etc.
+    for i in range(1, replicas):
+        replica_name = config['res_name'] + '-' + str(i)
+        dc_resource(
+            replica_name,
+            labels=config['labels'],
+            resource_deps=config['res_deps'],
+            auto_init=auto_init_apps,
+        )
+
+
+def _live_update_sync_source(project_root, full_res_path, sync_path):
+    """Local path Tilt watches for a live-update sync.
+
+    Tilt resolves sync() local paths against the Tiltfile directory (.tdk/.tdk-out), not
+    the docker_build context, so a project-relative path never matches the changed files
+    and every edit falls back to a full image rebuild ("Found file(s) not matching any
+    sync"). Anchor it at the project root, like the Dockerfile and build context.
+    """
+    relative_path = full_res_path + '/' + sync_path
+    if project_root:
+        return project_root.rstrip('/') + '/' + relative_path
+    return relative_path
+
+
+def _build_live_update_rules(res_path, full_res_path, syncs, project_root='', language='bun', go_live_reload=False):
+    """Build live update sync and run rules for a resource.
+
+    Python backends reload their own process after a sync (uvicorn --reload), so they have
+    no Bun install step. A changed pyproject.toml is not synced, so Tilt rebuilds the image instead.
+    Rust backends, and Go backends without `dev.liveReload`, have no live update (see the early return).
+    """
+    # Go and Rust are compiled into the image and have no reload process, so syncing sources would leave the
+    # old binary running. Return before any sync() step is built (Tilt rejects sync steps that are created
+    # but never used): no live-update rules means Tilt rebuilds the image when a watched file changes.
+    if language == 'rust' or (language == 'go' and not go_live_reload):
+        return []
+
+    if go_live_reload:
+        # Opted-in Go development loop: sync the sources into the development image, where the flisk-go-watch script rebuilds and restarts.
+        # Dependency and Dockerfile changes cannot be picked up by a restart, so they fall back to a full image rebuild.
+        source_dir = _live_update_sync_source(project_root, full_res_path, '')
+        return [
+            fall_back_on([
+                source_dir + 'go.mod',
+                source_dir + 'go.sum',
+                source_dir + OUTPUT.AUTOGENERATED_FOLDER,
+            ]),
+            sync(source_dir.rstrip('/'), '/app/' + full_res_path),
+        ]
+
+    live_update_rules = []
+    for sync_path in syncs:
+        # Python and Node images never read the Bun registry config, and the engine does not
+        # generate it for provider-owned languages, so there is nothing to sync.
+        if language == 'python' and (
+            sync_path.endswith('.npmrc.docker.autogenerated') or sync_path.endswith('bunfig.docker.autogenerated.toml')
+        ):
+            continue
+        if language == 'node' and (
+            sync_path.endswith('.npmrc.docker.autogenerated') or sync_path.endswith('bunfig.docker.autogenerated.toml')
+        ):
+            continue
+        full_sync_path = _live_update_sync_source(project_root, full_res_path, sync_path)
+        dest = '/app/' + full_res_path + '/' + sync_path
+        live_update_rules.append(sync(full_sync_path, dest))
+    
+    if language == 'python' or language == 'node':
+        return live_update_rules
+    
+    package_json_path = '/app/' + full_res_path + '/package.json'
+    bun_lock_path = '/app/' + full_res_path + '/bun.lock'
+    live_update_rules.append(run('cd /app/' + full_res_path + ' && bun install', 
+                                 trigger=[package_json_path, bun_lock_path]))
+    return live_update_rules
+
+
+def _app_image_name(resource_name, res_name):
+    """The image ref docker_build builds and the app compose service declares (project-scoped; see constants.star)."""
+    return PlatformDockerConstants.app_image_name(resource_name, res_name)
+
+
+def _wake_compose_invocation(project_root, resource_path, res_name, resource_name):
+    """Compose files, env file and image for the wake gateway's direct start.
+
+    The same files/--env-file the `-run-only` resource passes, as absolute
+    normalized paths: the gateway mounts the project at the same normalized
+    root (traefik_standalone.star), so these resolve identically there.
+    Returns None without a project root (paths would be relative to Tilt's cwd).
+    """
+    if not project_root:
+        return None
+    root = normalize_abs_path(project_root)
+    compose_dir = root + '/' + resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER
+    files = [compose_dir + '/docker-compose.app.autogenerated.yml']
+    port_override = compose_dir + '/docker-compose.port-override.yml'
+    if os.path.exists(port_override):
+        files.append(port_override)
+    env_file = root + '/.env'
+    return {
+        'compose_files': files,
+        'env_file': env_file if os.path.exists(env_file) else '',
+        'image': _app_image_name(resource_name, res_name),
+    }
+
+
+def _image_target(config):
+    """The Dockerfile target Tilt builds and the deferStart prebuild must match: `development` for Go with `dev.liveReload`."""
+    return 'development' if Docker.go_live_reload(config.get('manifest', {})) else 'production'
+
+
+def _register_docker_build(config, live_update_rules):
+    """Register docker_build with live_update for hot-reload support."""
+    TypescriptBuilders.build_typescript_service(
+        _app_image_name(config['resource_name'], config['res_name']),
+        config.get('project_root', '') or '.',
+        _resolve_dockerfile(config),
+        live_update_rules,
+        config['res_deps'],
+        target = _image_target(config),
+    )
+
+
+def _register_deferred_image_prebuild(config, auto_init_apps):
+    """Build a deferStart resource's image during `flisk up` without creating its container.
+
+    `auto_init=False` on the dc_resource skips its docker_build too (confirmed
+    live on tdk-erp-system, task 7.2), so a fresh project's first request would
+    find no image and the wake gateway would fall back to `tilt trigger`, which
+    queues behind every other build. This local_resource builds the same image
+    (same Dockerfile and target as docker_build: `production`, or `development` for Go with `dev.liveReload`; host network, and an allowlist
+    .dockerignore equivalent to docker_build's only=/ignore=) under the tag the
+    compose service declares, so the gateway can start it directly.
+    """
+    project_root = config.get('project_root', '')
+    dockerfile = _resolve_dockerfile(config)
+    prebuild_dockerfile = dockerfile + '.prebuild'
+    # The same target _register_docker_build picks: a Go service with `dev.liveReload` runs the development image (the watcher), so
+    # prebuilding `production` under the same tag would start the compiled binary with no reload.
+    target = _image_target(config)
+    ignore_content = TypescriptBuilders.prebuild_dockerignore(dockerfile, project_root, config['res_path'])
+    # BuildKit reads `<dockerfile>.dockerignore` for `-f <dockerfile>`; the
+    # original Dockerfile already has a (denylist) one, hence the copy.
+    cmd = (
+        "cp '" + dockerfile + "' '" + prebuild_dockerfile + "'"
+        + " && printf '%s' '" + ignore_content + "' > '" + prebuild_dockerfile + ".dockerignore'"
+        + " && docker build --network host --target " + target
+        + " -f '" + prebuild_dockerfile + "'"
+        + " -t '" + _app_image_name(config['resource_name'], config['res_name']) + "'"
+        + " '" + (project_root or '.') + "'"
+    )
+    local_resource(
+        name=config['res_name'] + '-image',
+        cmd=cmd,
+        labels=config['labels'],
+        resource_deps=config['res_deps'],
+        auto_init=auto_init_apps,
+    )
+
+
+def _resolve_dockerfile(config):
+    """Absolute (when project_root is set) path of a resource's Dockerfile."""
+    project_root = config.get('project_root', '')
+    # Use custom dockerfile from config if specified, otherwise use autogenerated default
+    # The res_path is relative to project_root (e.g., 'services/product/...')
+    # The dockerfile config is relative to res_path (e.g., '.autogenerated/Dockerfile...')
+    rel_dockerfile = config.get('dockerfile', '')
+    if rel_dockerfile:
+        if rel_dockerfile.startswith('/'):
+            dockerfile = config['res_path'] + rel_dockerfile
+        else:
+            dockerfile = config['res_path'] + '/' + rel_dockerfile
+    else:
+        dockerfile = config['res_path'] + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/Dockerfile.app.autogenerated'
+    # Prepend project_root to make absolute path from the Tilt working directory
+    if project_root:
+        if dockerfile.startswith('/'):
+            dockerfile = project_root + dockerfile
+        else:
+            dockerfile = project_root + '/' + dockerfile
+    return dockerfile
+
+
+def _register_run_only_resource(config, resource_path, compose_project_name, auto_init_apps=True):
+    """Register a run-only local resource for docker compose up."""
+    project_root = config.get('project_root', '')
+    compose_dir = resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER
+    compose_file = compose_dir + '/docker-compose.app.autogenerated.yml'
+    port_override = compose_dir + '/docker-compose.port-override.yml'
+    env_file = '.env'
+    if project_root:
+        root = project_root.rstrip('/')
+        compose_file = root + '/' + compose_file
+        port_override = root + '/' + port_override
+        env_file = root + '/.env'
+    compose_files = '-f ' + compose_file
+    if str(local("test -f '" + port_override + "' && echo yes || echo no", quiet=True, echo_off=True)).strip() == 'yes':
+        compose_files = compose_files + ' -f ' + port_override
+    # .env is gitignored (no .env.example shipped) across every Flisk example repo, so a
+    # fresh clone must not hard-require it: only pass --env-file when it actually exists.
+    env_file_flag = ''
+    if str(local("test -f '" + env_file + "' && echo yes || echo no", quiet=True, echo_off=True)).strip() == 'yes':
+        env_file_flag = ' --env-file ' + env_file
+    local_resource(
+        name=config['res_name'] + '-run-only',
+        cmd='docker compose -p '
+            + compose_project_name
+            + ' '
+            + compose_files
+            + env_file_flag
+            + ' up -d --no-build '
+            + config['res_name'],
+        labels=config['labels'] + ['run-only'],
+        # The run-only Compose command uses the image produced by the main
+        # resource. Keep it behind that resource so --no-build cannot race
+        # the ImageBuild and fail with a missing image.
+        resource_deps=config['res_deps'] + [config['res_name']],
+        auto_init=auto_init_apps,
+        allow_parallel=True,
+    )
+
+
+def _register_single_resource(config, resource_path, compose_project_name, auto_init_apps):
+    """Register a single dc_resource with optional docker_build and run-only resource."""
+    app_type = config.get('app_type', 'backend')
+    res_name = config['res_name']
+
+    # A sablier.enable + sablier.deferStart resource is held back from flisk up's
+    # normal bring-up: its container is never created or started here, only via
+    # the Traefik wake path on first request. auto_init=False also skips the
+    # dc_resource's docker_build, so its image is built by a separate
+    # `<name>-image` resource instead (_register_deferred_image_prebuild).
+    defers_start = resource_defers_start(config.get('manifest', {}))
+    effective_auto_init = auto_init_apps and not defers_start
+
+    debug_log("REGISTER: Registering '{}' app_type='{}' auto_init={}".format(res_name, app_type, effective_auto_init))
+
+    # Skip docker_build for libraries and SDKs - they don't have Dockerfiles
+    if app_type not in ['library', 'sdk', 'bring-your-own'] and config.get('syncs'):
+        debug_log("REGISTER: '{}' has syncs, calling docker_build".format(res_name))
+        live_update_rules = _build_live_update_rules(
+            config['res_path'],
+            config['res_path'],
+            config['syncs'],
+            project_root=config.get('project_root', ''),
+            language=config.get('manifest', {}).get('language', 'bun'),
+            go_live_reload=Docker.go_live_reload(config.get('manifest', {})),
+        )
+        _register_docker_build(config, live_update_rules)
+        if defers_start:
+            _register_deferred_image_prebuild(config, auto_init_apps)
+    else:
+        debug_log("REGISTER: '{}' skipping docker_build (app_type='{}', syncs={})".format(res_name, app_type, config.get('syncs')))
+
+    debug_log("REGISTER: Calling dc_resource for '{}' with deps={}".format(res_name, config['res_deps']))
+    dc_resource(
+        config['res_name'],
+        labels=config['labels'],
+        resource_deps=config['res_deps'],
+        auto_init=effective_auto_init,
+    )
+    debug_log("REGISTER: dc_resource completed for '{}'".format(res_name))
+
+    _register_run_only_resource(config, resource_path, compose_project_name, effective_auto_init)
+    _register_replicas(config, effective_auto_init)
+
+
+def _register_dc_resources(resource_configs, resource_path, compose_project_name, auto_init_apps):
+    """Register all dc_resources for the service."""
+    for config in resource_configs:
+        _register_single_resource(config, resource_path, compose_project_name, auto_init_apps)
+
+
+# appTypes whose containers get DATABASE_URL and therefore need their logical database provisioned. Bring-your-own
+# containers receive DATABASE_URL too (docs/byo.md), so without provisioning they point at a database that never exists.
+DATABASE_APP_TYPES = ['backend', 'bring-your-own']
+
+
+def resource_needs_database(manifest):
+    """True when a resource of this manifest receives DATABASE_URL and needs its database provisioned."""
+    return (manifest or {}).get('appType') in DATABASE_APP_TYPES
+
+
+def _has_backend_resource(resource_config, resource_manifests):
+    """Check if service has a resource that needs the provisioned database (backend or bring-your-own)."""
+    for resource in resource_config.get('resources', []):
+        manifest = resource_manifests.get(resource['name'], {})
+        if resource_needs_database(manifest):
+            return True
+    return False
+
+
+def _should_skip_frontend(res, should_enable):
+    """Check if frontend resource should be skipped (backends-only mode)."""
+    return res.get('frontend', False) and should_enable('backends-only')
+
+
+def _register_frontend_typecheck(res, service_dir, typecheck_cmd):
+    """Non-blocking `<service>-typecheck` resource: runs the planned tsc command so type errors show in Tilt without gating the image.
+
+    The command runs on the host, so TypeScript must resolve from the service directory (`bun install`, at the
+    service or workspace root). Without it the resource fails with that instruction instead of a bare module error.
+    """
+    local_resource(
+        name=res['name'] + '-typecheck',
+        cmd="cd '" + service_dir + "' && { bunx tsc --version >/dev/null 2>&1 || { echo 'typecheck needs host dependencies: run bun install in " + service_dir + "'; exit 1; }; } && " + typecheck_cmd,
+        deps=[service_dir + '/src', service_dir + '/tsconfig.json'],
+        labels=['app.' + res['name'], 'typecheck'],
+        # tsc --noEmit writes no files, so it can run alongside the image builds.
+        allow_parallel=True,
+    )
+
+
+def _process_frontend_resource(res, manifest, full_res_path, resource_path, resource_name, should_enable, project_root=''):
+    """Process a frontend resource and return compose entry."""
+    target_path = res.get('target_path', manifest.get('target_path', '/usr/share/nginx/html'))
+    use_nginx = 'nginx' in target_path or target_path == '/usr/share/nginx/html'
+    port = res.get('port', manifest.get('port', BASE_PORT_FRONTEND))
+    service_dir = (project_root.rstrip('/') + '/' if project_root else '') + full_res_path
+    plan = frontend_build_plan(service_dir + '/package.json')
+    Docker.frontend(
+        res_path=full_res_path,
+        resource_name=res['name'],
+        port=port,
+        target_path=target_path,
+        use_nginx=use_nginx,
+        use_golden=should_enable('golden-image'),
+        build_cmd=plan['build_cmd'],
+    )
+    if plan['typecheck']:
+        _register_frontend_typecheck(res, service_dir, plan['typecheck_cmd'])
+    return Docker.frontend_compose(resource_path=resource_path, resource_name=resource_name, res=res, manifest=manifest)
+
+
+def _process_backend_resource(res, manifest, full_res_path, resource_path, resource_name, should_enable):
+    """Process a backend resource and return compose entry."""
+    if manifest.get('appType') != 'bring-your-own':
+        Docker.backend(
+            res_path=full_res_path,
+            resource_name=res['name'],
+            port=None,  # Use default BASE_PORT_BACKEND
+            build_cmd=res.get('start_command', 'bun run build'),
+            use_golden=should_enable('golden-image'),
+        )
+    return Docker.backend_compose(resource_path=resource_path, resource_name=resource_name, res=res, manifest=manifest)
+
+
+def _build_resource_config(res, manifest, resource_config, full_res_path, infra_deps,
+                          config_gen_resources, resource_manifests, runtime_flags, all_services_map=None, project_root=''):
+    """Build configuration dict for a single resource."""
+    res_name = res['name']
+    res_deps = _build_resource_deps(
+        res, res_name, manifest, resource_config, infra_deps,
+        config_gen_resources, resource_manifests, runtime_flags, all_services_map,
+    )
+    replicas = manifest.get('replicas', 1)
+    if runtime_flags['disable_app_replicas']:
+        replicas = 1
+
+    # Extract environment variables from manifest params
+    env_vars = manifest.get('params', {})
+
+    return {
+        'res_name': res_name,
+        'resource_name': resource_config['name'],
+        'res_deps': res_deps,
+        'labels': ['app.' + res_name],
+        'replicas': replicas,
+        'syncs': res.get('syncs', []),
+        'app_type': manifest.get('appType', 'backend'),
+        'dockerfile': res.get('dockerfile', manifest.get('dockerfile', OUTPUT.AUTOGENERATED_FOLDER + '/Dockerfile.app.autogenerated')),
+        'res_path': full_res_path,
+        'env': env_vars,
+        'project_root': project_root,
+        'manifest': manifest,
+    }
+
+
+def count_routable_backends_by_stack(resource_config, resource_manifests, default_stack):
+    """Count the backends of each stack that get a Traefik route (workers, frontends, SDKs, libraries and unproxied BYO do not)."""
+    counts = {}
+    for resource in resource_config.get('resources', []):
+        manifest = resource_manifests.get(resource['name'], {})
+        app_type = manifest.get('appType', 'backend')
+        if resource.get('frontend', False) or app_type in ['frontend', 'worker', 'library', 'sdk', 'infra']:
+            continue
+        if app_type == 'bring-your-own' and not manifest.get('exposeViaProxy', True):
+            continue
+        stack = manifest.get('stack', default_stack)
+        counts[stack] = counts.get(stack, 0) + 1
+    return counts
+
+
+def register_compose_resources(resource_config, ctx, runtime_flags, manifest_state):
+    """Register all compose resources for a service."""
+    resource_name = resource_config.get('name', '')
+    resource_path = resource_config.get('path', '')
+    
+    debug_log("COMPOSE: register_compose_resources called for '{}' path='{}'".format(resource_name, resource_path))
+    
+    if not resource_name:
+        print("⚠️  Skipping service without name")
+        return {'compose_project_name': ''}
+    
+    if not resource_path:
+        # Silently skip services without paths - these may be library references
+        # or incomplete manifests
+        debug_log("COMPOSE: SKIPPING '{}' - no path".format(resource_name))
+        return {'compose_project_name': ''}
+    
+    debug_log("COMPOSE: Proceeding with '{}' - creating compose resources".format(resource_name))
+    should_enable = ctx['should_enable']
+    write_file = ctx['write_file']
+    compose_project_name = PlatformDockerConstants.compose_project_name(resource_name)
+    
+    resource_manifests = manifest_state['resource_manifests']
+    config_gen_resources = manifest_state['config_gen_resources']
+    has_backend = _has_backend_resource(resource_config, resource_manifests)
+    infra_deps = _build_infra_dependencies(resource_name, should_enable, ctx, has_backend)
+    
+    # Build map of all services for dependency resolution
+    # This maps short names like 'identity' to full resource names
+    all_services_map = {}
+    all_services = ctx.get('all_services', [])
+    for svc in all_services:
+        svc_name = svc.get('name', '')
+        if svc_name:
+            all_services_map[svc_name] = svc
+        # Also map resource names
+        for res in svc.get('resources', []):
+            res_name = res.get('name', '')
+            if res_name:
+                all_services_map[res_name] = svc
+
+    # Selection-bound shared platform Postgres start signal.
+    # Only enabled resources in THIS stack are evaluated. Registration sees
+    # unselected siblings before Tilt's enabled-resource filter runs.
+    # When database-management is off and any selected resource's
+    # manifest depends on postgres/database-management, force-start the shared
+    # platform Postgres via the existing infra loader (materializes
+    # services/platform/database-management/docker-compose.yml + registers the
+    # existing `postgres` Tilt resource). Does NOT open migrators/provision-db/Prisma.
+    # Idempotent across services: force_start_shared_platform_postgres_once
+    # guards on ctx so two selected dependents do not register postgres twice.
+    if not should_enable('database-management'):
+        for res in resource_config.get('resources', []):
+            if not selected_for_shared_platform_postgres(res.get('name', ''), ctx):
+                continue
+            res_manifest = resource_manifests.get(res['name'], {})
+            if manifest_needs_shared_platform_postgres(res_manifest):
+                debug_log("COMPOSE: selected '{}' dependsOn shared platform Postgres; force-starting postgres".format(res.get('name', '')))
+                force_start_shared_platform_postgres_once(ctx, should_enable, res.get('name', ''))
+                break
+
+    resource_entries = []
+    resource_configs = []
+    stack_backend_counts = count_routable_backends_by_stack(resource_config, resource_manifests, resource_name)
+
+    for res in resource_config.get('resources', []):
+        if _should_skip_frontend(res, should_enable):
+            continue
+        
+        full_res_path = res.get('_resource_path', resource_path + '/' + res['name'])
+        manifest = resource_manifests.get(res['name'], {})
+        if manifest:
+            # Tell the Traefik label generator how many routable backends share this stack (see _stack_is_shared in networking/traefik.star).
+            manifest = dict(manifest)
+            manifest['_stackBackendCount'] = stack_backend_counts.get(manifest.get('stack', resource_name), 1)
+        
+        # Skip non-app resources - they don't use the golden app Dockerfile pipeline.
+        # infra (e.g. verdaccio) is loaded via registries/verdaccio_loader.star instead.
+        # Building verdaccio as a backend produced broken COPY paths and missing package.json.
+        app_type = manifest.get('appType', 'backend')
+        if app_type in ['library', 'sdk', 'infra']:
+            debug_log("COMPOSE: Skipping '{}' appType='{}' (not an app container)".format(res.get('name', ''), app_type))
+            continue
+        
+        if res.get('frontend', False):
+            entry = _process_frontend_resource(res, manifest, full_res_path, resource_path, resource_name, should_enable, ctx.get('project_root', ''))
+        else:
+            entry = _process_backend_resource(res, manifest, full_res_path, resource_path, resource_name, should_enable)
+            # A deferStart resource has no container Traefik can discover via
+            # labels until its first request creates one (D2/D4) -- give it a
+            # static file-provider route instead, pointed at the wake gateway.
+            # Scoped to backends for now, matching the proposal's motivating
+            # case; frontend support is a natural follow-up, not implemented
+            # here. Dependency waking (D5): Flisk's real infra dependencies
+            # (database, NATS, a resource's own migrator) live in
+            # separately-registered compose files that `depends_on` cannot
+            # reference (confirmed empirically, see design.md D5), and they're
+            # always-on infra that's essentially never actually cold, so they
+            # never show up here regardless. The one real case D5 flags as
+            # mattering -- a peer resource that is itself deferStart -- is
+            # resolved via the manifest's own `dependsOn` below.
+            if resource_defers_start(manifest) and write_file:
+                internal_port = res.get('port', manifest.get('port', BASE_PORT_BACKEND))
+                static_route_path = PlatformDockerConstants.TRAEFIK_DYNAMIC_DIR_REL + '/' + res['name'] + '.yml'
+                compose_invocation = _wake_compose_invocation(
+                    ctx.get('project_root', ''), resource_path, res['name'], resource_name,
+                ) or {}
+                write_file(static_route_path, generate_static_wake_route(
+                    resource_entry_name=res['name'],
+                    compose_project_name=compose_project_name,
+                    manifest=manifest,
+                    internal_port=internal_port,
+                    gateway_host=PlatformDockerConstants.TRAEFIK_WAKE_GATEWAY_CONTAINER,
+                    gateway_port=PlatformDockerConstants.TRAEFIK_WAKE_GATEWAY_PORT,
+                    dependencies=resolve_defer_start_dependencies(manifest, resource_manifests, all_services_map),
+                    compose_files=compose_invocation.get('compose_files'),
+                    env_file=compose_invocation.get('env_file', ''),
+                    image=compose_invocation.get('image', ''),
+                ))
+
+        resource_entries.append(entry)
+        built_config = _build_resource_config(
+            res, manifest, resource_config, full_res_path, infra_deps,
+            config_gen_resources, resource_manifests, runtime_flags, all_services_map,
+            ctx.get('project_root', ''),
+        )
+        # A focused run still registers disabled siblings before Tilt applies
+        # set_enabled_resources. Do not leave their edge pointing at a Postgres
+        # resource that this evaluation did not register.
+        if not should_enable('database-management') and not ctx.get('_shared_platform_postgres_force_started', False):
+            built_config['res_deps'] = [dep for dep in built_config['res_deps'] if dep != 'postgres']
+        resource_configs.append(built_config)
+
+    debug_log("COMPOSE: Calling Docker.app_compose for '{}' with write_fn={}".format(resource_name, write_file))
+    Docker.app_compose(resource_path, resource_entries, write_file)
+    
+    debug_log("COMPOSE: {} resource_entries count = {}".format(resource_name, len(resource_entries)))
+    
+    # Prepend project root to make path absolute from project root
+    project_root = ctx.get('project_root', '')
+    
+    # Only register docker_compose if we have actual services (not just libraries)
+    if resource_entries:
+        compose_file_rel = resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/docker-compose.app.autogenerated.yml'
+        compose_file = project_root + '/' + compose_file_rel if project_root else compose_file_rel
+        # Load env file from project root for docker-compose variables (DB_PASSWORD, etc.)
+        env_file = project_root + '/.env' if project_root else '.env'
+        debug_log("COMPOSE: Calling docker_compose for '{}' with {} env_file={}".format(resource_name, compose_file, env_file))
+        _docker_compose_app(compose_file, compose_project_name, env_file)
+        port_override_rel = resource_path + '/' + OUTPUT.AUTOGENERATED_FOLDER + '/docker-compose.port-override.yml'
+        port_override = project_root + '/' + port_override_rel if project_root else port_override_rel
+        if str(local("test -f '" + port_override + "' && echo yes || echo no", quiet=True, echo_off=True)).strip() == 'yes':
+            debug_log("COMPOSE: Applying port override {}".format(port_override))
+            _docker_compose_app(port_override, compose_project_name, env_file)
+    else:
+        debug_log("COMPOSE: SKIPPING docker_compose for '{}' - no resource_entries".format(resource_name))
+
+    for compose_file in resource_config.get('compose_files', []):
+        if compose_file != '.autogenerated/docker-compose.app.autogenerated.yml':
+            compose_file_full = project_root + '/' + resource_path + '/' + compose_file if project_root else resource_path + '/' + compose_file
+            env_file = project_root + '/.env' if project_root else '.env'
+            _docker_compose_app(compose_file_full, compose_project_name, env_file)
+
+    debug_log("COMPOSE: Calling _register_dc_resources for '{}' with {} configs, auto_init={}".format(resource_name, len(resource_configs), runtime_flags['auto_init_apps']))
+    _register_dc_resources(resource_configs, resource_path, compose_project_name, runtime_flags['auto_init_apps'])
+
+    return {'compose_project_name': compose_project_name}
+
+
+ComposeResourceRegistration = struct(
+    register = register_compose_resources,
+)
+
+DEBUG = {}