@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/engine/spec.master.example

@@ -0,0 +1,341 @@
+#!/usr/bin/env starlark
+# BEFORE/AFTER: Making Tilt Obvious (Zig-Style Explicitness)
+# 
+# This file demonstrates how the new spec.master makes the system
+# completely explicit - addressing the Zig developer's critique about
+# "hidden control flow" and "no hidden allocations"
+
+# =============================================================================
+# ❌ BEFORE: Implicit, Hidden, Magic
+# =============================================================================
+
+# Magic load - where does this file live? Who knows.
+# load("./discovery/registry.star", "get_app_resources")
+
+# Magic context - what's inside ctx? Runtime mystery.
+# ctx = Context.build(full_graph, manifest)
+
+# Magic path construction - where does this write?
+# output_path = path.join(resource_path, "tsconfig.json")
+
+# Magic feature check - is this enabled? Where defined?
+# if features.is_enabled("istio"):
+
+# Magic port allocation - algorithm hidden
+# port = allocate_port(resource_name)
+
+# Magic dependency resolution - how does this work?
+# deps = resolve_dependencies(manifest)
+
+# =============================================================================
+# ✅ AFTER: Explicit, Obvious, No Magic
+# =============================================================================
+
+# Load the master spec - ALL paths are explicit constants
+load("{PROJECT_ROOT}/.tilt/spec.master", "SPEC", "CONSTANTS", "VALIDATION", "FEATURES", "OUTPUT", "DEBUG")
+
+# 💡 ALTERNATIVE: Use the easier-to-remember alias names
+# Both work identically - use whichever you prefer!
+#
+#     load("{PROJECT_ROOT}/.tilt/paths.star", "SPEC", "CONSTANTS", "DEBUG")
+#     load("{PROJECT_ROOT}/.tilt/where-things-live.star", "SPEC", "CONSTANTS", "DEBUG")
+#
+# Why aliases? Because "paths" is easier to remember than "spec.master" 😊
+
+# Explicit imports - you SEE exactly what files are loaded
+load(SPEC.DISCOVERY.REGISTRY, "get_app_resources", "get_resource_by_name")
+load(SPEC.DISCOVERY.LOADING, "load_manifest")
+load(SPEC.GENERATORS.VITE, "generate_vite_config")
+load(SPEC.GENERATORS.TSCONFIG, "generate_tsconfig")
+load(SPEC.GENERATORS.DOCKERFILE, "generate_dockerfile")
+load(SPEC.GENERATORS.MANIFEST_RESOURCE, "ManifestResource")
+
+# EXPLICIT path construction - no hidden logic
+def get_resource_path(resource_name):
+    """Build service path EXPLICITLY from constants."""
+    return SPEC.RESOURCES_DIR + "/product/" + resource_name
+
+def get_manifest_path(resource_path):
+    """Manifest path is EXPLICIT, not discovered."""
+    return resource_path + "/" + RESOURCE_PATTERNS.MANIFEST_FILE
+
+def get_output_path(resource_name, filename):
+    """Output path is EXPLICIT, constructed from constants."""
+    return OUTPUT.CONFIGS + "/" + resource_name + "/" + filename
+
+# =============================================================================
+# EXPLICIT CONFIGURATION GENERATION
+# =============================================================================
+
+def generate_resource_configs(resource_name, manifest):
+    """
+    Generate configs with EXPLICIT paths and constraints.
+    No hidden allocations. No magic context.
+    """
+    
+    # EXPLICIT: Validate inputs (Zig-style defensive programming)
+    if not resource_name:
+        fail("resource_name is empty - explicit validation")
+    
+    if not manifest:
+        fail("manifest is empty - explicit validation")
+    
+    # EXPLICIT: Port validation with visible constraints
+    port = manifest.get("port")
+    if port < VALIDATION.MIN_PORT or port > VALIDATION.MAX_PORT:
+        fail("port {} outside valid range [{}-{}]".format(
+            port, VALIDATION.MIN_PORT, VALIDATION.MAX_PORT
+        ))
+    
+    if port in VALIDATION.RESERVED_PORTS:
+        fail("port {} is in RESERVED_PORTS list".format(port))
+    
+    # EXPLICIT: Feature check - visible toggle
+    if FEATURES.ISTIO_INTEGRATION:
+        # 🗓️ ROADMAP: Will generate Istio configs when implemented
+        istio_config = generate_istio_config(manifest)
+    else:
+        # EXPLICIT: Currently using Traefik
+        istio_config = None
+    
+    # EXPLICIT: Path construction - you SEE where files go
+    resource_path = get_resource_path(resource_name)
+    output_dir = get_output_path(resource_name, "")
+    
+    configs = {
+        "tsconfig": {
+            "input": get_manifest_path(resource_path),
+            "output": output_dir + RESOURCE_PATTERNS.GENERATED_TSCONFIG,
+            "generator": SPEC.GENERATORS.TSCONFIG,
+        },
+        "vite": {
+            "input": get_manifest_path(resource_path),
+            "output": output_dir + RESOURCE_PATTERNS.GENERATED_VITE_CONFIG,
+            "generator": SPEC.GENERATORS.VITE,
+        },
+        "dockerfile": {
+            "input": get_manifest_path(resource_path),
+            "output": resource_path + "/" + RESOURCE_PATTERNS.DOCKERFILE,
+            "generator": SPEC.GENERATORS.DOCKERFILE,
+        },
+    }
+    
+    # EXPLICIT: Debug output (visible when DEBUG.DUMP_GENERATED_CONFIGS)
+    if DEBUG.DUMP_GENERATED_CONFIGS:
+        print("[DEBUG] Generated configs for {}:".format(resource_name))
+        for name, cfg in configs.items():
+            print("  {}: {}".format(name, cfg["output"]))
+    
+    return configs
+
+# =============================================================================
+# EXPLICIT SERVICE DISCOVERY (No Magic Globbing)
+# =============================================================================
+
+def discover_services_explicit():
+    """
+    Discover services with EXPLICIT search paths.
+    No hidden glob patterns. Everything visible.
+    """
+    discovered = []
+    
+    # EXPLICIT: Iterate declared search paths
+    for search_path in DISCOVERY.RESOURCE_SEARCH_PATHS:
+        # EXPLICIT: Glob pattern is declared in spec.master
+        pattern = search_path + "/" + DISCOVERY.MANIFEST_PATTERNS[0]  # service.json
+        
+        # EXPLICIT: Check exclusions
+        matches = glob([pattern], exclude=DISCOVERY.EXCLUDE_PATTERNS)
+        
+        for match in matches:
+            # EXPLICIT: Construct service info from path
+            resource_dir = os.path.dirname(match)
+            resource_name = os.path.basename(resource_dir)
+            
+            discovered.append({
+                "name": resource_name,
+                "path": resource_dir,
+                "manifest_path": match,
+            })
+    
+    return discovered
+
+# =============================================================================
+# EXPLICIT CONTEXT BUILDING (No Black Box)
+# =============================================================================
+
+def build_explicit_context(resource_manifest, all_services):
+    """
+    Build context EXPLICITLY - every field is visible.
+    No mystery black box.
+    """
+    ctx = struct(
+        # EXPLICIT: Source data
+        manifest = resource_manifest,
+        all_services = all_services,
+        
+        # EXPLICIT: Computed values (transparent logic)
+        resource_name = resource_manifest.get("appName"),
+        resource_path = get_resource_path(resource_manifest.get("appName")),
+        port = resource_manifest.get("port"),
+        
+        # EXPLICIT: Dependencies (resolved, not hidden)
+        dependencies = resolve_explicit_dependencies(
+            resource_manifest.get("dependsOn", []),
+            all_services
+        ),
+        
+        # EXPLICIT: System constants
+        constants = CONSTANTS,
+        validation = VALIDATION,
+        features = FEATURES,
+    )
+    
+    # EXPLICIT: Debug inspection
+    if DEBUG.DUMP_CONTEXT_ON_GENERATION:
+        print("[DEBUG] Context for {}:".format(ctx.resource_name))
+        print("  port: {}".format(ctx.port))
+        print("  dependencies: {}".format([d["name"] for d in ctx.dependencies]))
+        print("  features enabled: {}".format([f for f in dir(FEATURES) if not f.startswith("_")]))
+    
+    return ctx
+
+def resolve_explicit_dependencies(dep_names, all_services):
+    """
+    Resolve dependencies EXPLICITLY.
+    No hidden graph traversal.
+    """
+    resolved = []
+    
+    for dep_name in dep_names:
+        # EXPLICIT: Lookup in explicit list
+        found = None
+        for svc in all_services:
+            if svc["name"] == dep_name:
+                found = svc
+                break
+        
+        if not found:
+            fail("Dependency '{}' not found in explicit service list".format(dep_name))
+        
+        # EXPLICIT: Check for circular dependencies
+        if dep_name in resolved:
+            fail("Circular dependency detected involving '{}'".format(dep_name))
+        
+        resolved.append(found)
+    
+    return resolved
+
+# =============================================================================
+# EXPLICIT GENERATION ENTRY POINT
+# =============================================================================
+
+def generate_all_explicit():
+    """
+    Main generation with EXPLICIT flow.
+    Every step is visible. No magic.
+    """
+    
+    print("=" * 60)
+    print("TILT GENERATION - EXPLICIT MODE")
+    print("=" * 60)
+    
+    # EXPLICIT: Step 1 - Discovery
+    print("\n[1/5] DISCOVERY")
+    print("  Search paths: {}".format(DISCOVERY.RESOURCE_SEARCH_PATHS))
+    services = discover_services_explicit()
+    print("  Found {} services".format(len(services)))
+    for svc in services:
+        print("    - {} at {}".format(svc["name"], svc["path"]))
+    
+    # EXPLICIT: Step 2 - Validation
+    print("\n[2/5] VALIDATION")
+    for svc in services:
+        port = svc.get("port", 0)
+        if port < VALIDATION.MIN_PORT:
+            fail("  ❌ {}: port {} below minimum {}".format(
+                svc["name"], port, VALIDATION.MIN_PORT
+            ))
+        print("  ✅ {}: port {} valid".format(svc["name"], port))
+    
+    # EXPLICIT: Step 3 - Context Building
+    print("\n[3/5] CONTEXT BUILDING")
+    contexts = {}
+    for svc in services:
+        ctx = build_explicit_context(svc, services)
+        contexts[svc["name"]] = ctx
+        print("  ✅ {}: context built".format(svc["name"]))
+    
+    # EXPLICIT: Step 4 - Generation
+    print("\n[4/5] GENERATION")
+    generated = {}
+    for svc in services:
+        configs = generate_resource_configs(svc["name"], svc)
+        generated[svc["name"]] = configs
+        print("  ✅ {}: {} configs generated".format(svc["name"], len(configs)))
+    
+    # EXPLICIT: Step 5 - Output
+    print("\n[5/5] OUTPUT")
+    print("  Output directory: {}".format(OUTPUT.CONFIGS))
+    for svc_name, configs in generated.items():
+        for cfg_name, cfg in configs.items():
+            print("  Writing: {}".format(cfg["output"]))
+            # write_file(cfg["output"], cfg["content"])
+    
+    print("\n" + "=" * 60)
+    print("GENERATION COMPLETE")
+    print("  Services: {}".format(len(services)))
+    print("  Configs: {}".format(sum(len(c) for c in generated.values())))
+    print("  Output: {}".format(OUTPUT.CONFIGS))
+    print("=" * 60)
+
+# =============================================================================
+# ZIG-STYLE MANIFESTO APPLIED
+# =============================================================================
+
+"""
+WHAT CHANGED:
+
+BEFORE (Implicit):
+  - Paths discovered at runtime
+  - Features checked magically  
+  - Context is black box
+  - Errors at runtime
+
+AFTER (Explicit - Zig-style):
+  - Paths are CONSTANTS in spec.master
+  - Features are EXPLICIT STRUCT toggles
+  - Context is EXPLICIT STRUCT (every field visible)
+  - Errors at "compile time" (Tiltfile load)
+
+PRINCIPLES APPLIED:
+  ✅ No hidden control flow
+  ✅ No hidden allocations (paths explicit)
+  ✅ No magic (everything declared in spec.master)
+  ✅ Explicit is better than implicit
+  ✅ Fail fast with clear messages
+
+ANSWER TO ZIG DEVELOPER:
+  "You wanted obvious. Now it's obvious."
+  "Every path is a constant."
+  "Every feature is a toggle."
+  "Every context field is visible."
+  "No magic. No surprises."
+"""
+
+# =============================================================================
+# USAGE EXAMPLE
+# =============================================================================
+
+# To use in your Tiltfile:
+#
+# load("{}/.tilt/spec.master".format(PROJECT_ROOT), "SPEC", "CONSTANTS")
+# 
+# # Now EVERYTHING is explicit and obvious
+# print("Registry path: {}".format(SPEC.DISCOVERY.REGISTRY))
+# print("Max port: {}".format(VALIDATION.MAX_PORT))
+# print("Istio enabled: {}".format(FEATURES.ISTIO_INTEGRATION))
+#
+# # No more guessing where files live
+# # No more wondering what ctx contains
+# # No more hidden feature flags

package/engine/topologies/README.md

@@ -0,0 +1,33 @@
+---
+title: Topologies (Incremental Migration)
+status: backlog
+created: 2026-03-31
+updated: 2026-10-18
+---
+
+# Topologies (Incremental Migration)
+
+This folder holds the Starlark modules that turn `service.json` manifests into Docker Compose and Tilt resources for local development. Flisk generates these for `flisk up` on your machine; it does not generate Kubernetes deployment manifests.
+
+## How a `service.json` becomes running resources
+
+Paths below are relative to the repository root. The order is the order things run.
+
+1. **Generate the project Tiltfile.** `flisk up` (or `flisk config regenerate`) renders `.tdk/.tdk-out/Tiltfile` from [`cli/templates/Tiltfile.hbs`](../../cli/templates/Tiltfile.hbs). It loads the engine through the root [`Tiltfile`](../../Tiltfile), which re-exports `Manifest`, `Orchestrator`, `Infra` and the rest.
+2. **Discover and validate manifests.** The generated Tiltfile calls `Manifest.load_all(...)`. Discovery, normalization and the field checks live in [`discovery/loading.star`](../../discovery/loading.star), [`discovery/json_manifest_scanner.star`](../../discovery/json_manifest_scanner.star), [`discovery/manifest/normalize.star`](../../discovery/manifest/normalize.star) and [`discovery/manifest/validation.star`](../../discovery/manifest/validation.star). Parsing helpers and constants are in [`tilt/manifest/parser.star`](tilt/manifest/parser.star) and [`tilt/manifest/constants.star`](tilt/manifest/constants.star). The `dependsOn` check you see from `flisk config verify` is in [`cli/src/commands/config.ts`](../../cli/src/commands/config.ts).
+3. **Orchestrate each resource.** The Tiltfile calls `Orchestrator.apply_service(...)`, which reaches [`tilt/resources/orchestrator/apply.star`](tilt/resources/orchestrator/apply.star). For each enabled stack it validates the resource, loads its manifest, registers the Compose resource and, for migrators, registers the migration job. The helpers are the `apply_*.star` files next to it. [`apply_compose_resource_registration.star`](tilt/resources/orchestrator/apply_compose_resource_registration.star) turns `dependsOn` into Tilt `resource_deps`.
+4. **Generate the platform files.** The Docker modules under [`platform/docker/`](platform/docker/) write the files each resource needs: Compose entries in [`compose/compose.star`](platform/docker/compose/compose.star), Dockerfiles in [`dockerfile/dockerfile.star`](platform/docker/dockerfile/dockerfile.star) and the image layers in [`layers/`](platform/docker/layers/). Config generators such as `tsconfig` and Vite are in [`tilt/generators/`](tilt/generators/). Shared infrastructure (Traefik, Postgres) is loaded by [`tilt/resources/infra-loader.star`](tilt/resources/infra-loader.star).
+5. **Read the generated project files.** The output lands in each resource's `.autogenerated/` folder, for example `docker-compose.app.autogenerated.yml` and `Dockerfile.app.autogenerated`. Do not edit these by hand; see [generated files](../../docs/generated-files.md).
+
+If you change a field in `service.json`, start at step 2. If a container is built or wired wrongly, start at step 3 or 4.
+
+## Layout
+
+- `platform/`: Docker (`docker/`), proxy (`net/proxy.star`), shared Postgres (`state/relational.star`), secrets (`security/secrets.star`) and the local registry (`registries/local.star`).
+- `tilt/manifest/`: manifest parsing helpers, validators and constants. See its [README](tilt/manifest/README.md).
+- `tilt/config/`: global config, defaults, focus profiles and feature flags.
+- `tilt/resources/`: databases, libraries, ordering, watchers and the orchestrator.
+- `tilt/generators/`: `tsconfig`, Vite, nginx, `.npmrc` and AGENTS.md generators.
+- `tilt/common/`: shared helpers used by the modules above.
+
+Service discovery itself is in the top-level [`discovery/`](../../discovery/) folder, not in this one.

package/engine/topologies/platform/docker/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md - Docker Platform Infrastructure
+
+## Purpose
+
+Docker image building, golden image layers, and Dockerfile generation for all services.
+
+## Key Concepts
+
+### Golden Image Architecture (L1-L4)
+```
+L1: Base (Alpine OS with essential tools, runtime environment variables)
+L2: Dependencies (package manifests and installed dependencies, cached)
+L3: Builder (backend compile, frontend build, production dependency pruning)
+L4: Runtime (backend on Bun, frontend on Nginx or Bun static)
+```
+
+## Key Files
+
+### Golden Images
+- **`build/golden_image.star`** - GoldenImage struct with L1-L4 builders
+- **`build/golden_image_*.star`** - Build, constants, and Dockerfile helpers used by `GoldenImage`
+- **`dockerfile/dockerfile.star`** - Dockerfile generation for apps
+- **`constants.star`** - Docker constants, image names
+
+### Layer Building
+- **`layers/l1_base_layers.star`** - Alpine OS base and runtime environment
+- **`layers/l2_dependency_layers.star`** - Dependency installation
+- **`layers/l3_builder_layers.star`** - Build stage
+- **`layers/l4_runtime_layers.star`** - Minimal runtime
+
+### Specialized
+- **`layers/prisma/`** - Prisma-specific Docker layers
+- **`generators/golden_docker_generator_v2.star`** - Current generator (v2)
+
+## Common Tasks
+
+### Generate Dockerfile for service
+```starlark
+load("./dockerfile/dockerfile.star", "generate_app_dockerfile")
+dockerfile = generate_app_dockerfile(res_path, resource_name, cmd = start_command)
+```
+
+### Get golden image
+```starlark
+load("./build/golden_image.star", "GoldenImage")
+image = GoldenImage.get_layer("l2")
+```
+
+## Integration
+
+- Called by `engine/topologies/tilt/resources/orchestrator/generators/manifest_resource.star` - when building service resources
+- Used by discovery - to determine Dockerfile paths
+- Outputs to services' `autogenerated/Dockerfile.*.autogenerated`
+
+## Important Notes
+
+- Golden images use digests for cache invalidation
+- L2 layer caches `node_modules` for faster rebuilds
+- Each service's Dockerfile starts `FROM {project}/golden-image-l4:latest`

package/engine/topologies/platform/docker/auth/auth.star

@@ -0,0 +1,207 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 🔐 TILT SDK - AUTH CONFIGURATION UTILITIES
+# =============================================================================
+# Path: .tilt/topologies/platform/docker/auth.star
+# Purpose: Centralized authentication configuration helpers for docker-compose
+#          and environment file generation across the platform.
+# 
+# Design Principle: This module is decoupled from manifest.json structure.
+#          It accepts auth configuration as a dictionary parameter and does
+#          not know where the config comes from. Callers (env.star, compose.star)
+#          are responsible for extracting auth fields from manifest and passing
+#          them as the auth_config dict.
+# =============================================================================
+
+# Default values for auth configuration.
+#
+# There is deliberately no default JWT secret: a secret that is the same in every project is not a secret. The JWT secret is
+# generated once per project by the CLI into the project `.env` (JWT_SECRET) and Compose reads it from there.
+DEFAULT_AUTH_MODE = 'local-jwt'
+DEFAULT_IDENTITY_RESOURCE_URL = 'http://identity-service:3000'
+
+# Shown by Compose when the project `.env` has no JWT_SECRET.
+JWT_SECRET_MISSING_MESSAGE = 'JWT_SECRET is not set. Run `flisk up` (it adds a generated one to the project .env) or add JWT_SECRET to .env'
+
+
+def _setting(auth_config, key, default):
+    """A configured value, or the default when the key is missing OR present with a None value.
+
+    Callers build the config dict with every key present and None for anything unset, and `dict.get(key, default)` returns that
+    None instead of the default, which used to turn into the literal text `AUTH_MODE=None` in generated files.
+    """
+    if not auth_config:
+        return default
+    value = auth_config.get(key)
+    if value == None or value == '':
+        return default
+    return value
+
+
+def _first_set(*values):
+    """The first value that is not None or an empty string, else None."""
+    for value in values:
+        if value != None and value != '':
+            return value
+    return None
+
+
+def auth_config_from_manifest(manifest):
+    """Build the auth configuration both the env file and the Compose entry use, from one place.
+
+    The two writers used to build this separately and drifted: the env file read `identityServiceUrl` while Compose read
+    `envVars.IDENTITY_RESOURCE_URL`, so setting one field changed only one output.
+
+    - authMode: the manifest's `authMode`, else `identity-service` when `dependsOn` contains `identity`, else unset (local-jwt).
+    - identityServiceUrl: the manifest's `identityServiceUrl`. The deprecated `params` / `envVars` entry named
+      `IDENTITY_RESOURCE_URL` is still honoured when the field is absent, so an existing manifest keeps working.
+
+    Args:
+        manifest: The service manifest dict (may be None)
+
+    Returns:
+        dict: {'authMode': str or None, 'identityServiceUrl': str or None}; None means "use the default"
+    """
+    if not manifest:
+        return {'authMode': None, 'identityServiceUrl': None}
+
+    auth_mode = _first_set(
+        manifest.get('authMode'),
+        'identity-service' if 'identity' in (manifest.get('dependsOn') or []) else None,
+    )
+    identity_url = _first_set(
+        manifest.get('identityServiceUrl'),
+        (manifest.get('params') or {}).get('IDENTITY_RESOURCE_URL'),
+        (manifest.get('envVars') or {}).get('IDENTITY_RESOURCE_URL'),
+    )
+    return {'authMode': auth_mode, 'identityServiceUrl': identity_url}
+
+
+def get_auth_mode(auth_config):
+    """Get auth mode from auth config with default fallback.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: Auth mode ('local-jwt' or 'identity-service')
+    """
+    return _setting(auth_config, 'authMode', DEFAULT_AUTH_MODE)
+
+
+def get_identity_resource_url(auth_config):
+    """Get identity service URL from auth config with default fallback.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: URL for identity service
+    """
+    return _setting(auth_config, 'identityServiceUrl', DEFAULT_IDENTITY_RESOURCE_URL)
+
+
+def get_auth_config(auth_config):
+    """Get complete auth configuration from auth config dict.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        struct: Auth configuration with mode and identity_resource_url (the JWT secret lives in the project .env, not here)
+    """
+    return struct(
+        mode = get_auth_mode(auth_config),
+        identity_resource_url = get_identity_resource_url(auth_config),
+    )
+
+
+def is_local_jwt_mode(auth_config):
+    """Check if auth mode is local-jwt.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        bool: True if auth mode is 'local-jwt'
+    """
+    return get_auth_mode(auth_config) == 'local-jwt'
+
+
+def is_identity_resource_mode(auth_config):
+    """Check if auth mode is identity-service.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        bool: True if auth mode is 'identity-service'
+    """
+    return get_auth_mode(auth_config) == 'identity-service'
+
+
+def generate_docker_compose_auth_env(auth_config):
+    """Generate docker-compose environment variables for auth configuration.
+
+    This function returns the properly formatted environment variable block
+    for docker-compose.yml files based on the auth mode.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: Formatted auth environment variables for docker-compose
+    """
+    auth_mode = get_auth_mode(auth_config)
+    identity_resource_url = get_identity_resource_url(auth_config)
+
+    if auth_mode == 'local-jwt':
+        # Required from the project .env (see JWT_SECRET_MISSING_MESSAGE); there is no shared default.
+        return """      - AUTH_MODE=local-jwt
+      - JWT_SECRET=${JWT_SECRET:?%(message)s}""" % {'message': JWT_SECRET_MISSING_MESSAGE}
+    else:
+        return """      - AUTH_MODE=identity-service
+      - IDENTITY_RESOURCE_URL=${IDENTITY_RESOURCE_URL:-%(identity_resource_url)s}""" % {'identity_resource_url': identity_resource_url}
+
+
+def generate_env_file_auth_section(auth_config):
+    """Generate .env file auth section content.
+
+    This function returns the formatted authentication configuration section
+    for .env.backend.autogenerated files. These files are generated, checked by
+    `flisk config verify` and never carry secrets, so there is no JWT secret here:
+    in local-jwt mode Compose takes JWT_SECRET from the project .env.
+
+    Args:
+        auth_config: Auth configuration dictionary (may be None or empty)
+
+    Returns:
+        str: Formatted auth section for .env files
+    """
+    auth_mode = get_auth_mode(auth_config)
+    identity_resource_url = get_identity_resource_url(auth_config)
+
+    content = """
+# Authentication Configuration
+# Mode: {auth_mode} (options: local-jwt, identity-service)
+AUTH_MODE={auth_mode}
+""".format(auth_mode=auth_mode)
+
+    if auth_mode != 'local-jwt':
+        content += "IDENTITY_RESOURCE_URL={identity_resource_url}\n".format(identity_resource_url=identity_resource_url)
+
+    return content
+
+
+# Export all functions as a struct for easy importing
+AuthConfig = struct(
+    from_manifest = auth_config_from_manifest,
+    get_auth_mode = get_auth_mode,
+    get_identity_resource_url = get_identity_resource_url,
+    get_auth_config = get_auth_config,
+    is_local_jwt_mode = is_local_jwt_mode,
+    is_identity_resource_mode = is_identity_resource_mode,
+    generate_docker_compose_auth_env = generate_docker_compose_auth_env,
+    generate_env_file_auth_section = generate_env_file_auth_section,
+)