@flisk-sh/flisk 0.0.0-stage → 1.3.189

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

@@ -0,0 +1,64 @@
+# AGENTS.md - Networking & Proxy
+
+## Purpose
+
+Traefik reverse proxy, networking configuration, and service routing.
+
+## Key Files
+
+### Traefik
+- **`proxy.star`** - Traefik configuration generation
+- **`labels.star`** - Docker labels for Traefik routing
+
+### Network Management
+- **`network.star`** - Docker network setup
+- **`hosts.star`** - /etc/hosts file management
+
+## Common Tasks
+
+### Generate Traefik labels
+```starlark
+load("./proxy.star", "generate_traefik_labels")
+labels = generate_traefik_labels(
+    resource_name="order-management-backend",
+    port=4000,
+    host="order.backend.{project}.localhost",
+    path_prefix="/api/orders"
+)
+```
+
+### Output
+```python
+{
+    "traefik.enable": "true",
+    "traefik.http.routers.order-management-backend.rule": "Host(`order.backend.{project}.localhost`) && PathPrefix(`/api/orders`)",
+    "traefik.http.routers.order-management-backend.entrypoints": "web",
+    "traefik.http.services.order-management-backend.loadbalancer.server.port": "4000"
+}
+```
+
+## Architecture
+
+```
+Internet/localhost
+       ↓
+   Traefik (port 80/443)
+       ↓
+   Routes to services by Host/Path
+       ↓
+   Service containers
+```
+
+## Integration
+
+- Called by `resources/` when creating service resources
+- Used by `platform/docker/` for Docker Compose generation
+- Labels applied to docker_build and docker_compose
+
+## Local Development
+
+Services accessible at:
+- `{service}.backend.{project}.localhost`
+- `{service}.frontend.{project}.localhost`
+
+Managed in `/etc/hosts` automatically.

package/engine/topologies/platform/net/proxy.star

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+load("../../tilt/resources/infra-loader.star", _Infra = "Infra")
+
+def load(should_enable):
+    return _Infra.load_proxy(should_enable)

package/engine/topologies/platform/registries/local.star

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+load("../../tilt/resources/infra-loader.star", _Infra = "Infra")
+
+def load(should_enable):
+    return _Infra.load_verdaccio(should_enable)

package/engine/topologies/platform/registries/verdaccio_loader.star

@@ -0,0 +1,20 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 📦 VERDACCIO (NPM Registry) - loader (free-tier stub)
+# =============================================================================
+# Path: engine/topologies/platform/registries/verdaccio_loader.star
+# =============================================================================
+# The real loader (stands up the Verdaccio private npm registry container and
+# wires it into the project's Docker network) is part of a paid Flisk license.
+# When a valid license grants the "verdaccio" resource,
+# cli/src/generator/template-engine.ts (vendorTdkExtension) overwrites this
+# file with the licensed version fetched via extension-fetch.ts before Tilt
+# loads it. Same function signature either way, so nothing else in the
+# loader pipeline changes.
+# =============================================================================
+
+
+def load_verdaccio(_should_enable, _root_prefix="", _env_file=None):
+    """Free-tier stub - see module header. Always skipped."""
+    print("ℹ️  Verdaccio skipped — requires a Flisk Premium license (run `flisk upgrade`)")

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

@@ -0,0 +1,49 @@
+# AGENTS.md - Security & Secrets
+
+## Purpose
+
+Secrets management, Infisical integration, and security configuration.
+
+## Key Files
+
+### Secrets Management
+- **`infisical.star`** - Infisical secrets provider integration
+- **`secrets.star`** - Generic secrets handling
+- **`encryption.star`** - Encryption utilities
+
+### Configuration
+- **`tokens.star`** - Token generation and validation
+- **`keys.star`** - Key management
+
+## Common Tasks
+
+### Load secrets from Infisical
+```starlark
+load("./infisical.star", "Infisical")
+secrets = Infisical.load_secrets(resource_name, environment)
+```
+
+### Get database credentials
+```starlark
+load("./infisical.star", "Infisical")
+db_url = Infisical.get_database_url(resource_name)
+```
+
+## Integration
+
+- Called by `resources/` when setting up service environment
+- Used in Docker Compose for injecting secrets
+- Part of service startup chain
+
+## Local Development
+
+Without Infisical, falls back to:
+- Environment variables
+- Default values in `spec.master`
+
+## Security Notes
+
+- Never commit real secrets
+- Use Infisical for production
+- Local development uses safe defaults
+- Secrets injected at runtime, not in images

package/engine/topologies/platform/security/secrets.star

@@ -0,0 +1,241 @@
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 🔐 INFISICAL SECURITY MODULE
+# =============================================================================
+# Centralizes Infisical secrets management configuration
+# =============================================================================
+#
+# This module provides:
+#   - Infrastructure loading (Infisical containers)
+#   - Secret injection configuration for services
+#   - Machine identity management
+#   - Organization and path management
+#
+# Usage:
+#   load("../../platform/security/secrets.star", "Secrets")
+#   
+#   # Load Infisical infrastructure
+#   Secrets.load_infra(should_enable_fn)
+#   
+#   # Configure service secrets
+#   config = Secrets.configure_service("my-service", "/services/my-service")
+# =============================================================================
+
+# Infrastructure loader
+load("../../tilt/resources/infra-loader.star", _Infra="Infra")
+
+# Generators
+load("../../tilt/generators/infisical/index.star", _Infisical="Infisical")
+
+# Docker layers integration
+load("../../platform/docker/layers/infisical/index.star", "InfisicalLayers")
+
+# =============================================================================
+# Infrastructure Loading
+# =============================================================================
+
+def _load_infra(should_enable):
+    """Load Infisical infrastructure containers."""
+    return _Infra.load_infisical(should_enable)
+
+# =============================================================================
+# Resource Secret Configuration
+# =============================================================================
+
+def _configure_service(resource_name, secret_path, resource_type="backend", command=None):
+    """
+    Configure secret injection for a resource.
+
+    Args:
+        resource_name: Name of the resource
+        secret_path: Infisical path (e.g., "/services/my-service")
+        resource_type: Type of resource (backend, frontend, worker, etc.)
+        command: Entrypoint command (optional)
+
+    Returns:
+        Configuration dict for the resource
+    """
+    return _Infisical.Secrets.generate_for_service(
+        resource_name=resource_name,
+        secret_path=secret_path,
+        resource_type=resource_type,
+        command=command,
+    )
+
+def _configure_services_batch(services_config):
+    """
+    Configure secrets for multiple resources.
+
+    Args:
+        services_config: List of dicts with resource configuration
+
+    Returns:
+        Dict mapping resource names to configurations
+    """
+    return _Infisical.Secrets.generate_for_services_batch(services_config)
+
+# =============================================================================
+# Path Management
+# =============================================================================
+
+def _plan_resource_path(resource_name, resource_type="backend"):
+    """Plan Infisical path for a resource."""
+    return _Infisical.Paths.plan_resource_path(resource_name, resource_type)
+
+def _plan_batch_paths(resource_names, resource_type="backend"):
+    """Plan paths for multiple resources."""
+    return _Infisical.Paths.plan_batch_resource_paths(resource_names, resource_type)
+
+def _get_known_resource_path(resource_name):
+    """Get predefined path for a known resource."""
+    return _Infisical.Paths.get_known_resource_path(resource_name)
+
+# =============================================================================
+# Machine Identity
+# =============================================================================
+
+def _generate_machine_identity(identity_name, access_paths=None, project_id=None):
+    """
+    Generate machine identity configuration.
+    
+    Args:
+        identity_name: Name of the machine identity
+        access_paths: List of paths the identity can access
+        project_id: Project ID
+    
+    Returns:
+        Machine identity configuration
+    """
+    return _Infisical.Identity.generate_universal_auth(
+        identity_name=identity_name,
+        access_paths=access_paths,
+        project_id=project_id,
+    )
+
+def _get_development_machine(project_id=None):
+    """Get development machine identity configuration."""
+    return _Infisical.Identity.generate_development_machine(
+        identity_name="dev-machine",
+        project_id=project_id,
+    )
+
+def _get_ci_machine(project_id=None):
+    """Get CI/CD machine identity configuration."""
+    return _Infisical.Identity.generate_ci_machine(project_id=project_id)
+
+# =============================================================================
+# Organization Setup
+# =============================================================================
+
+def _generate_org_config(org_name=None, environments=None, resource_names=None):
+    """
+    Generate organization configuration.
+    
+    Args:
+        org_name: Organization name
+        environments: List of environment names
+        resource_names: List of service names
+    
+    Returns:
+        Organization configuration dict
+    """
+    return _Infisical.Org.generate_config(
+        org_name=org_name,
+        env_names=environments,
+        resource_names=resource_names,
+    )
+
+# =============================================================================
+# Predefined Services Configuration
+# =============================================================================
+
+# Project-specific service configurations should be defined in .tdk/project.json
+# This dict is kept for backward compatibility but should be empty for generic Flisk CLI
+PREDEFINED_RESOURCES = {}
+
+def _get_predefined_resource_config(resource_name):
+    """Get predefined configuration for a known resource."""
+    return PREDEFINED_RESOURCES.get(resource_name)
+
+def _configure_predefined_service(resource_name, command=None):
+    """
+    Configure a predefined resource by name.
+
+    Args:
+        resource_name: Name of the predefined resource
+        command: Entrypoint command (optional)
+
+    Returns:
+        Resource configuration or None if not predefined
+    """
+    config = _get_predefined_resource_config(resource_name)
+    if not config:
+        return None
+    
+    return _configure_service(
+        resource_name=resource_name,
+        secret_path=config["path"],
+        resource_type=config["type"],
+        command=command,
+    )
+
+# =============================================================================
+# Batch Configuration for All Resources
+# =============================================================================
+
+def _configure_all_predefined_services(command=None):
+    """
+    Configure all predefined resources.
+
+    Args:
+        command: Default entrypoint command (optional)
+
+    Returns:
+        Dict mapping resource names to configurations
+    """
+    results = {}
+    
+    for resource_name in PREDEFINED_RESOURCES:
+        config = _configure_predefined_service(resource_name, command)
+        if config:
+            results[resource_name] = config
+    
+    return results
+
+# =============================================================================
+# Public API
+# =============================================================================
+
+Secrets = struct(
+    # Infrastructure
+    load_infra=_load_infra,
+
+    # Resource configuration
+    configure_service=_configure_service,
+    configure_services_batch=_configure_services_batch,
+    configure_predefined_service=_configure_predefined_service,
+    configure_all_predefined_services=_configure_all_predefined_services,
+    
+    # Path management
+    plan_resource_path=_plan_resource_path,
+    plan_batch_paths=_plan_batch_paths,
+    get_known_resource_path=_get_known_resource_path,
+    
+    # Machine identity
+    generate_machine_identity=_generate_machine_identity,
+    get_development_machine=_get_development_machine,
+    get_ci_machine=_get_ci_machine,
+    
+    # Organization
+    generate_org_config=_generate_org_config,
+    
+    # Constants
+    PREDEFINED_RESOURCES=PREDEFINED_RESOURCES,
+    
+    # Direct access to submodules
+    Infisical=_Infisical,
+    
+    # Docker layers integration
+    Layers=InfisicalLayers,
+)

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

@@ -0,0 +1,64 @@
+# AGENTS.md - Database & State Management
+
+## Purpose
+
+PostgreSQL database virtualization, per-service database provisioning, and state management.
+
+## Key Files
+
+### Database Provisioning
+- **`relational.star`** - Main database provisioning logic
+- **`compose.star`** - Docker Compose entries for databases
+
+### Prisma Integration
+- **`prisma/migrate_script.star`** - Migration script generation
+- **`prisma/db_readiness.star`** - Database readiness checks
+- **`prisma/prisma_build.star`** - Prisma in Docker builds
+- **`prisma/prisma_runtime.star`** - Prisma client in runtime
+
+### Utilities
+- **`utils.star`** - Database utilities
+- **`constants.star`** - Database constants (ports, users)
+
+## Common Tasks
+
+### Provision database for service
+```starlark
+load("./relational.star", "provision_database")
+compose_entry = provision_database("order-management-backend", "{project}_order")
+```
+
+### Get database URL
+```starlark
+load("./relational.star", "get_database_url")
+url = get_database_url("order-management-backend")
+# Returns: postgresql://postgres:postgres@order-management-backend-db:5432/{project}_order
+```
+
+### Wait for database
+```starlark
+load("./prisma/db_readiness.star", "wait_for_db")
+script = wait_for_db(db_url, timeout=30)
+```
+
+## Architecture
+
+Each service with `databaseName` in manifest gets:
+1. PostgreSQL container in Docker Compose
+2. Volume for persistence
+3. Readiness check before migrations
+4. Dedicated port mapping (avoids conflicts)
+
+## Integration
+
+- Called by `resources/deps.star` - when setting up service dependencies
+- Used by `platform/docker/` - for Docker Compose generation
+- Part of service resource dependencies chain
+
+## Database Naming
+
+```
+{project}_{domain}  // e.g., {project}_order, {project}_user
+```
+
+Each domain gets one database shared by its services (backend, migrator, etc).

package/engine/topologies/platform/state/relational.star

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+load("../../tilt/resources/infra-loader.star", _Infra = "Infra")
+
+def load(should_enable):
+    return _Infra.load_database(should_enable)

package/engine/topologies/tilt/common/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md - Common Utilities
+
+## Purpose
+
+Shared utility functions used across all Tilt topologies.
+
+## Key Files
+
+### Core Utilities
+- **`utils.star`** - `Utils` struct with file operations, path manipulation
+- **`paths.star`** - Path utilities, path joining, normalization
+- **`strings.star`** - String manipulation helpers
+
+### Tilt Helpers
+- **`tilt.star`** - Tilt-specific utilities
+- **`debug.star`** - Debug logging, tracing
+
+## Common Tasks
+
+### Read JSON file
+```starlark
+load("./utils.star", "Utils")
+content = Utils.read_json_file(path)
+```
+
+### Check if path exists
+```starlark
+load("./utils.star", "Utils")
+exists = Utils.path_exists(path)
+```
+
+### Join paths
+```starlark
+load("./utils.star", "Utils")
+full_path = Utils.join_paths(base, relative)
+```
+
+## Usage
+
+Most topology modules load this:
+```starlark
+load("../common/utils.star", "Utils")
+```
+
+## Important Notes
+
+- These are pure Starlark functions (no Tilt builtins)
+- Safe to use in any context
+- No side effects
+
+## Available Functions
+
+See `Utils` struct for full list:
+- `read_json_file(path)`
+- `path_exists(path)`
+- `join_paths(base, rel)`
+- `sanitize_name(name)`
+- `extract_domain(path)`
+- `get_relative_path(from, to)`