@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/engine/topologies/tilt/manifest/parser.star

@@ -0,0 +1,490 @@
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# 📋 MANIFEST MODULE - PARSER
+# =============================================================================
+# Path: .tilt/topologies/tilt/manifest/parser.star
+# Purpose: JSON parsing and manifest normalization
+# Status: Phase 2 of manifest system refactoring
+# =============================================================================
+
+# === INLINED CONSTANTS for pure extension loading ===
+ORM = "prisma"
+DEFAULTS = {}
+
+# === END INLINED CONSTANTS ===
+
+
+load("./constants.star", 
+    "MANIFEST_DEFAULTS",
+    "MANIFEST_FILENAME",
+    "VALID_APP_TYPES",
+    "DEFAULT_SYNCS",
+    "AUTOGENERATED_CONFIG_PATHS",
+    "TRAEFIK_DEFAULTS",
+)
+load("./schema.star", "ManifestSchema")
+load("./errors.star", "ManifestErrors")
+
+
+def parse(content, path=""):
+    """
+    Parse JSON content into manifest dict.
+    
+    Args:
+        content: Raw JSON string
+        path: Optional path for error context
+    
+    Returns:
+        struct(
+            manifest=None,    # Parsed manifest dict or None
+            error=None,       # Error message or None
+            warnings=[],      # List of warning messages
+        )
+    """
+    warnings = []
+    
+    if not content or not str(content).strip():
+        return struct(
+            manifest=None,
+            error="Empty content provided",
+            warnings=warnings,
+        )
+    
+    # Parse JSON
+    manifest = decode_json(content)
+    
+    if manifest == None:
+        error = ManifestErrors.new(
+            message="Failed to parse JSON" + (" in " + path if path else ""),
+            category=ManifestErrors.CATEGORY['PARSE'],
+            severity=ManifestErrors.SEVERITY['ERROR'],
+            context={'path': path} if path else {},
+        )
+        return struct(
+            manifest=None,
+            error=ManifestErrors.format(error),
+            warnings=warnings,
+        )
+    
+    # Note: 'dependencies' field is no longer supported, use 'dependsOn'
+    
+    return struct(
+        manifest=manifest,
+        error=None,
+        warnings=warnings,
+    )
+
+# Characters allowed in the string fields that are written into generated Compose, Traefik and NATS config as they are. A line break
+# or YAML syntax in one of them adds keys to the generated service (GHSA-phgf-pww4-7jxc). Keep in step with GENERATED_STRING_FIELDS
+# in cli/src/utils/service-manifest.ts.
+_ALPHANUM = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+_PATH_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789/-"
+_GENERATED_STRING_RULES = [
+    # (field path, allowed characters, required first character or "")
+    (['healthCheckPath'], _PATH_CHARS, '/'),
+    (['traefik', 'host'], _ALPHANUM + '.-', ''),
+    (['traefik', 'pathPrefix'], _PATH_CHARS, '/'),
+    (['traefik', 'healthCheck'], _PATH_CHARS, '/'),
+    (['nats', 'queueGroup'], _ALPHANUM + '_.-', ''),
+    (['databaseName'], _ALPHANUM + '_-', ''),
+    (['stack'], _ALPHANUM + '_-', ''),
+    (['image'], _ALPHANUM + '._/:@-', ''),
+]
+
+def generated_string_error(manifest, resource_path=""):
+    """
+    Return an error message if a value that is written into generated config has unsafe characters, else None.
+
+    The value is not echoed, because it may contain the line break that makes it dangerous.
+    """
+    for keys, allowed, first in _GENERATED_STRING_RULES:
+        value = manifest
+        for key in keys:
+            value = value.get(key) if type(value) == "dict" else None
+        if value == None or value == "":
+            continue
+        field = '.'.join(keys)
+        where = " in " + resource_path if resource_path else ""
+        if type(value) != "string":
+            return "MANIFEST ERROR: '{}' must be a string{}".format(field, where)
+        if first and not value.startswith(first):
+            return "MANIFEST ERROR: '{}' must start with '{}'{}".format(field, first, where)
+        for c in value.elems():
+            if c not in allowed:
+                return "MANIFEST ERROR: '{}' has characters that are not allowed (no spaces, line breaks or YAML syntax){}".format(field, where)
+    return _line_break_error(manifest, resource_path)
+
+# Line breaks (including the Unicode ones YAML 1.1 honours) and other control characters.
+_LINE_BREAK_OR_CONTROL = [chr(i) for i in range(32)] + [chr(127), "\u0085", "
", "
"]
+
+def _has_line_break(text):
+    for bad in _LINE_BREAK_OR_CONTROL:
+        if bad in text:
+            return True
+    return False
+
+def _line_break_error(manifest, resource_path):
+    """
+    Many more values than _GENERATED_STRING_RULES reach generated config (port, appName, dockerfile, buildContext, basePath, envVars,
+    ...). A key can only be added through a line break, so no string key or value may contain one. `smoke` is skipped: it is never
+    written into generated config. Keep in step with lineBreakErrors in cli/src/utils/service-manifest.ts.
+    """
+    where = " in " + resource_path if resource_path else ""
+    pending = [(value, key) for key, value in manifest.items() if key != 'smoke']
+    for key in manifest.keys():
+        if type(key) == "string" and _has_line_break(key):
+            return "MANIFEST ERROR: a key contains a line break{}".format(where)
+    # Starlark has no recursion or while loops; a service.json never nests anywhere near this many values.
+    for _ in range(100000):
+        if not pending:
+            return None
+        value, field = pending.pop()
+        if type(value) == "string":
+            if _has_line_break(value):
+                return "MANIFEST ERROR: '{}' must not contain line breaks or control characters{}".format(field, where)
+        elif type(value) == "list":
+            for index, item in enumerate(value):
+                pending.append((item, "{}[{}]".format(field, index)))
+        elif type(value) == "dict":
+            for key, item in value.items():
+                if type(key) == "string" and _has_line_break(key):
+                    return "MANIFEST ERROR: a key in '{}' contains a line break{}".format(field, where)
+                pending.append((item, "{}.{}".format(field, key)))
+    return "MANIFEST ERROR: service.json is nested too deeply{}".format(where)
+
+def normalize(manifest, resource_path=""):
+    """
+    Normalize manifest with default values and computed fields.
+
+    Args:
+        manifest: Raw parsed manifest dict
+        resource_path: Resource directory path for context
+
+    Returns:
+        Normalized manifest dict with all fields populated
+    """
+    normalized = {}
+    warnings = []
+
+    # Copy all existing fields
+    for key, value in manifest.items():
+        normalized[key] = value
+
+    unsafe_field_error = generated_string_error(normalized, resource_path)
+    if unsafe_field_error:
+        fail(unsafe_field_error)
+
+    # 1. Apply defaults for missing fields
+    for field, default_value in MANIFEST_DEFAULTS.items():
+        if field not in normalized or normalized[field] == None:
+            normalized[field] = default_value
+    
+    # 2. Compute derived fields
+    
+    # Compute appType from path if missing
+    if not normalized.get('appType'):
+        normalized['appType'] = _determine_app_type(normalized, resource_path)
+
+    # A bring-your-own service may not speak HTTP (a database, a mail relay). Its health path is optional, so do not invent /health
+    # for it. Only an explicit healthCheckPath in service.json gives it one.
+    if normalized['appType'] == 'bring-your-own' and 'healthCheckPath' not in manifest:
+        normalized.pop('healthCheckPath', None)
+    
+    # Compute stack from path if missing
+    if not normalized.get('stack'):
+        extracted = extract_stack_from_path(resource_path)
+        normalized['stack'] = extracted
+    
+    # Compute syncs if not provided
+    if normalized.get('syncs') == None or normalized.get('syncs') == []:
+        normalized['syncs'] = _compute_syncs(
+            normalized['appType'],
+            normalized.get('featuresEnabled', [])
+        )
+    
+    # Compute backendName for frontends if missing
+    if normalized['appType'] == 'frontend' and not normalized.get('backendName'):
+        app_name = normalized.get('appName', '')
+        if app_name.endswith('-frontend'):
+            normalized['backendName'] = app_name.replace('-frontend', '-backend')
+    
+    # Normalize environment variables
+    if not normalized.get('envVars'):
+        normalized['envVars'] = {}
+    
+    # Normalize dependsOn
+    if 'dependencies' in manifest and not normalized.get('dependsOn'):
+        normalized['dependsOn'] = manifest['dependencies']
+    if not normalized.get('dependsOn'):
+        normalized['dependsOn'] = []
+    
+    # 3. Set up Traefik configuration defaults
+    if not normalized.get('traefik'):
+        normalized['traefik'] = {}
+    
+    # Ensure traefik has pathPrefix - REQUIRED field
+    if not normalized['traefik'].get('pathPrefix'):
+        app_name = normalized.get('appName', 'unknown')
+        resource_path = normalized.get('_resource_path', 'unknown')
+        
+        # Fail loudly - pathPrefix is required
+        error_msg = """MANIFEST ERROR: Missing required 'traefik.pathPrefix' in {}
+
+Resource: {}
+File: service.json
+
+To fix, add:
+  "traefik": {{
+    "pathPrefix": "/api/v1/YOUR-PATH"
+  }}
+
+Example:
+  "traefik": {{
+    "pathPrefix": "/api/v1/order-management"
+  }}""".format(resource_path, app_name)
+        fail(error_msg)
+    
+    # Add default priority if not set
+    if 'priority' not in normalized['traefik']:
+        normalized['traefik']['priority'] = TRAEFIK_DEFAULTS['priority']
+    
+    # 4. Add internal metadata
+    normalized['_manifest'] = manifest  # Original manifest
+    normalized['_resource_path'] = resource_path
+    normalized['_normalized'] = True
+    
+    return normalized
+
+def extract_resource_path(manifest_path):
+    """
+    Extract resource directory path from manifest file path.
+    
+    Args:
+        manifest_path: Path to manifest JSON file
+    
+    Returns:
+        Resource directory path
+    """
+    # Remove manifest filename
+    if manifest_path.endswith("/" + MANIFEST_FILENAME):
+        return manifest_path[:-len("/" + MANIFEST_FILENAME)]
+    
+    # If it's just a filename, try to find the directory
+    parts = manifest_path.rsplit("/", 1)
+    if len(parts) == 2 and parts[1] == MANIFEST_FILENAME:
+        return parts[0]
+    
+    return manifest_path
+
+def extract_stack_from_path(resource_path):
+    """
+    Extract stack from resource path.
+    
+    Args:
+        resource_path: Resource directory path
+    
+    Returns:
+        Stack string from manifest (e.g., 'identity', 'booking')
+    """
+    parts = resource_path.split("/")
+    
+    # Expected path: services/product/{stack}/{resource-name}
+    if len(parts) >= 4 and parts[0] == "services" and parts[1] == "product":
+        stack = parts[2]
+        # Handle special cases
+        if stack == "profile":
+            return "identity"
+        if stack == "order-planner":
+            return "order-planner"
+        return stack
+    
+        # Fallback: try to extract from resource name
+    if len(parts) >= 1:
+        resource_name = parts[-1]
+        # Extract stack from resource name (e.g., {stack}-management-backend -> {stack})
+        name_parts = resource_name.split("-")
+        if len(name_parts) >= 1:
+            return name_parts[0]
+    
+    return "unknown"
+
+def _determine_app_type(manifest, resource_path):
+    """
+    Determine app type from manifest or resource path.
+    
+    Args:
+        manifest: Manifest dict
+        resource_path: Resource directory path
+    
+    Returns:
+        App type string ('frontend', 'backend', 'library', etc.)
+    """
+    # Check if manifest has explicit appType
+    if manifest.get("appType") and manifest["appType"] in VALID_APP_TYPES:
+        return manifest["appType"]
+    
+    # Extract from path
+    dir_name = resource_path.split("/")[-1] if resource_path else ""
+    
+    if dir_name.endswith("-frontend"):
+        return "frontend"
+    if dir_name.endswith("-backend"):
+        return "backend"
+    if dir_name.endswith("-migrator"):
+        return "migrator"
+    if dir_name.endswith("-sdk"):
+        return "sdk"
+    
+    # Default to backend
+    return "backend"
+
+def _compute_syncs(app_type, features):
+    """
+    Compute default sync paths based on app type and features.
+    
+    Args:
+        app_type: App type string
+        features: List of feature strings
+    
+    Returns:
+        List of sync paths
+    """
+    syncs = []
+    
+    # Start with default syncs for app type
+    if app_type in DEFAULT_SYNCS:
+        syncs.extend(DEFAULT_SYNCS[app_type])
+    
+    # Add feature-specific syncs
+    if ORM in features and app_type == "backend":
+        if ORM not in syncs:
+            syncs.append(ORM)
+    
+    # Remove duplicates while preserving order
+    seen = {}
+    unique_syncs = []
+    for sync in syncs:
+        if sync not in seen:
+            seen[sync] = True
+            unique_syncs.append(sync)
+    
+    return unique_syncs
+
+def parse_traefik_config(manifest):
+    """
+    Parse and normalize Traefik configuration.
+    
+    Args:
+        manifest: Manifest dict
+    
+    Returns:
+        Normalized Traefik config dict
+    """
+    traefik = manifest.get('traefik', {})
+    
+    normalized_traefik = {
+        'pathPrefix': traefik.get('pathPrefix', ''),
+        'host': traefik.get('host', ''),
+        'priority': traefik.get('priority', TRAEFIK_DEFAULTS['priority']),
+    }
+    
+    return normalized_traefik
+
+def merge_manifests(base, overlay):
+    """
+    Merge two manifest dicts (for inheritance patterns).
+    
+    Args:
+        base: Base manifest dict
+        overlay: Overlay manifest dict
+    
+    Returns:
+        Merged manifest dict
+    """
+    merged = {}
+    
+    # Start with base
+    for key, value in base.items():
+        merged[key] = value
+    
+    # Overlay takes precedence
+    for key, value in overlay.items():
+        # Special handling for nested dicts (like traefik, envVars)
+        if key in merged and type(merged[key]) == "dict" and type(value) == "dict":
+            merged[key] = {}
+            for k, v in merged[key].items():
+                merged[key][k] = v
+            for k, v in value.items():
+                merged[key][k] = v
+        else:
+            merged[key] = value
+    
+    return merged
+
+def get_normalized_manifest(manifest, resource_path=""):
+    """
+    Convenience function to parse and normalize in one call.
+    
+    Args:
+        manifest: Raw manifest (dict or JSON string)
+        resource_path: Resource directory path
+    
+    Returns:
+        struct(
+            manifest=None,    # Normalized manifest or None
+            error=None,       # Error message or None
+            warnings=[],      # List of warnings
+        )
+    """
+    # If it's a string, parse it
+    if type(manifest) == "string":
+        parse_result = parse(manifest, resource_path)
+        if parse_result.error:
+            return parse_result
+        manifest = parse_result.manifest
+        warnings = parse_result.warnings
+    else:
+        warnings = []
+    
+    # Normalize
+    normalized = normalize(manifest, resource_path)
+    
+    return struct(
+        manifest=normalized,
+        error=None,
+        warnings=warnings,
+    )
+
+def get_resource_type_description(manifest):
+    """
+    Get human-readable resource type description.
+    
+    Args:
+        manifest: Manifest dict
+    
+    Returns:
+        String description
+    """
+    app_type = manifest.get('appType', 'unknown')
+    stack = manifest.get('stack', 'unknown')
+    name = manifest.get('appName', 'unknown')
+    
+    return "{stack}/{app_type}/{name}".format(
+        stack=stack,
+        app_type=app_type,
+        name=name,
+    )
+
+# Export parser functions
+ManifestParser = struct(
+    parse=parse,
+    normalize=normalize,
+    generated_string_error=generated_string_error,
+    extract_resource_path=extract_resource_path,
+    extract_stack=extract_stack_from_path,
+    parse_traefik=parse_traefik_config,
+    merge=merge_manifests,
+    get_normalized=get_normalized_manifest,
+    get_description=get_resource_type_description,
+)