minutework 0.1.0

package/assets/templates/fastapi-sidecar/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "fastapi_sidecar", from = "src" }]
+
+[project]
+name = "fastapi-sidecar-template"
+version = "0.1.0"
+description = "Canonical FastAPI internal sidecar scaffold for MinuteWork Builder."
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+dependencies = [
+    "fastapi>=0.115,<1.0",
+    "httpx>=0.27,<1.0",
+    "pydantic-settings>=2.6,<3.0",
+    "uvicorn>=0.32,<1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "jsonschema>=4.23,<5.0",
+    "pytest>=8.3,<9.0",
+    "ruff>=0.11,<0.12",
+]
+
+[project.scripts]
+fastapi-sidecar-worker = "fastapi_sidecar.worker:main"
+fastapi-sidecar-template-validate = "fastapi_sidecar.template_validation:main"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+extend-exclude = ["build"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/__init__.py

@@ -0,0 +1,3 @@
+from fastapi_sidecar.main import app, create_app
+
+__all__ = ["app", "create_app"]

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/auth.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass
+from typing import Annotated
+from uuid import uuid4
+
+from fastapi import Depends, HTTPException, Request, status
+
+from fastapi_sidecar.settings import Settings, get_settings
+
+
+@dataclass(frozen=True, slots=True)
+class AuthContext:
+    request_id: str
+    tenant_id: str
+    auth_mode: str
+    principal_kind: str
+
+
+def _request_id(request: Request) -> str:
+    return request.headers.get("X-Request-Id", "").strip() or str(uuid4())
+
+
+def require_internal_only(
+    request: Request,
+    settings: Annotated[Settings, Depends(get_settings)],
+) -> AuthContext:
+    token = request.headers.get("X-Platform-Dispatch-Token", "").strip()
+
+    if not token or not secrets.compare_digest(token, settings.platform_dispatch_token):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Platform dispatch authentication required.",
+        )
+
+    return AuthContext(
+        request_id=_request_id(request),
+        tenant_id=settings.tenant_id,
+        auth_mode="internal_only",
+        principal_kind="platform_dispatch",
+    )
+
+
+def require_runtime_token(
+    request: Request,
+    settings: Annotated[Settings, Depends(get_settings)],
+) -> AuthContext:
+    runtime_id = request.headers.get("X-Runtime-Id", "").strip()
+    runtime_key = request.headers.get("X-Runtime-Key", "").strip()
+    expected_runtime_key = settings.read_runtime_key()
+
+    if runtime_id != settings.runtime_id or not runtime_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Runtime token authentication required.",
+        )
+
+    if not secrets.compare_digest(runtime_key, expected_runtime_key):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Runtime token authentication required.",
+        )
+
+    return AuthContext(
+        request_id=_request_id(request),
+        tenant_id=settings.tenant_id,
+        auth_mode="runtime_token",
+        principal_kind="runtime_machine",
+    )

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/bridge/__init__.py

@@ -0,0 +1,3 @@
+from fastapi_sidecar.bridge.client import BridgeClient, BridgeClientProtocol
+
+__all__ = ["BridgeClient", "BridgeClientProtocol"]

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/bridge/client.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+import httpx
+
+from fastapi_sidecar.settings import Settings, get_settings
+
+
+class BridgeClientProtocol(Protocol):
+    def runtime_headers(self) -> dict[str, str]:
+        ...
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        ...
+
+    def publish_receipt(self, *, path: str, receipt: dict[str, Any]) -> dict[str, Any]:
+        ...
+
+
+class BridgeClient:
+    def __init__(
+        self,
+        *,
+        settings: Settings | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.settings = settings or get_settings()
+        self._client = client or httpx.Client(base_url=self.settings.api_base_url.rstrip("/"))
+        self._owns_client = client is None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def runtime_headers(self) -> dict[str, str]:
+        return {
+            "X-Runtime-Id": self.settings.runtime_id,
+            "X-Runtime-Key": self.settings.read_runtime_key(),
+        }
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        request_headers = self.runtime_headers()
+        if headers:
+            request_headers.update(headers)
+
+        response = self._client.request(method, path, json=payload, headers=request_headers)
+        response.raise_for_status()
+        if not response.content:
+            return {}
+        parsed = response.json()
+        if not isinstance(parsed, dict):
+            raise RuntimeError("Bridge client expected an object JSON response.")
+        return parsed
+
+    def publish_receipt(self, *, path: str, receipt: dict[str, Any]) -> dict[str, Any]:
+        return self.request_json("POST", path, payload=receipt)

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/logging_utils.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+
+def configure_logging(level: str) -> None:
+    logging.basicConfig(level=getattr(logging, level.upper(), logging.INFO))
+
+
+def log_structured_event(
+    logger: logging.Logger,
+    *,
+    event: str,
+    level: int = logging.INFO,
+    **fields: Any,
+) -> None:
+    payload = {
+        "event": event,
+        "timestamp": datetime.now(UTC).isoformat(),
+        **fields,
+    }
+    logger.log(level, json.dumps(payload, sort_keys=True, default=str))

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/main.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import Depends, FastAPI
+from pydantic import BaseModel, Field
+
+from fastapi_sidecar.auth import AuthContext, require_internal_only
+from fastapi_sidecar.logging_utils import configure_logging, log_structured_event
+from fastapi_sidecar.receipts import build_receipt
+from fastapi_sidecar.settings import get_settings
+
+logger = logging.getLogger("fastapi_sidecar.api")
+
+
+class InternalWorkRequest(BaseModel):
+    operation: str = Field(default="noop")
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    try:
+        settings = get_settings()
+        configure_logging(settings.log_level)
+        log_structured_event(
+            logger,
+            event="fastapi_sidecar.startup",
+            route_name="startup",
+            tenant_id=settings.tenant_id,
+            auth_mode="system",
+            outcome="ready",
+        )
+    except Exception as exc:  # pragma: no cover - defensive scaffolding path
+        configure_logging("INFO")
+        logger.warning("Sidecar startup logging skipped: %s", exc)
+    yield
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="MinuteWork FastAPI Sidecar",
+        lifespan=lifespan,
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+    )
+
+    @app.get("/healthz")
+    def healthz() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.post("/internal/v1/dispatch")
+    def dispatch_internal_work(
+        body: InternalWorkRequest,
+        auth: AuthContext = Depends(require_internal_only),
+    ) -> dict[str, Any]:
+        receipt = build_receipt(
+            request_id=auth.request_id,
+            tenant_id=auth.tenant_id,
+            handler_name="internal_dispatch",
+            auth_mode=auth.auth_mode,
+            outcome="accepted",
+            extra={"operation": body.operation},
+        )
+        log_structured_event(
+            logger,
+            event="fastapi_sidecar.internal_dispatch",
+            request_id=auth.request_id,
+            tenant_id=auth.tenant_id,
+            route_name="internal_dispatch",
+            auth_mode=auth.auth_mode,
+            outcome="accepted",
+        )
+        return {
+            "accepted": True,
+            "receipt": receipt,
+        }
+
+    return app
+
+
+app = create_app()

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/receipts.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_receipt(
+    *,
+    request_id: str,
+    tenant_id: str,
+    handler_name: str,
+    auth_mode: str,
+    outcome: str,
+    detail: str = "",
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return {
+        "request_id": request_id,
+        "tenant_id": tenant_id,
+        "handler_name": handler_name,
+        "auth_mode": auth_mode,
+        "outcome": outcome,
+        "detail": detail,
+        "extra": extra or {},
+    }

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/settings.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=(".env", ".env.local"),
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    api_base_url: str = Field(validation_alias="MW_API_BASE_URL")
+    runtime_id: str = Field(validation_alias="MW_RUNTIME_ID")
+    tenant_id: str = Field(validation_alias="MW_TENANT_ID")
+    runtime_key_path: Path = Field(validation_alias="MW_RUNTIME_KEY_PATH")
+    platform_dispatch_token: str = Field(validation_alias="MW_PLATFORM_DISPATCH_TOKEN")
+    log_level: str = Field(default="INFO", validation_alias="MW_LOG_LEVEL")
+    pubsub_subscription: str | None = Field(
+        default=None,
+        validation_alias="MW_PUBSUB_SUBSCRIPTION",
+    )
+    worker_poll_interval_seconds: float = Field(
+        default=5.0,
+        validation_alias="MW_WORKER_POLL_INTERVAL_SECONDS",
+    )
+
+    def read_runtime_key(self) -> str:
+        value = self.runtime_key_path.read_text(encoding="utf-8").strip()
+        if not value:
+            raise RuntimeError("Runtime key file is blank.")
+        return value
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/template_validation.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from jsonschema import Draft202012Validator
+
+
+def validate_template_manifest(template_root: Path | None = None) -> None:
+    resolved_root = template_root or Path(__file__).resolve().parents[2]
+    schema = json.loads((resolved_root / "template.schema.json").read_text(encoding="utf-8"))
+    manifest = json.loads((resolved_root / "template.json").read_text(encoding="utf-8"))
+    validator = Draft202012Validator(schema)
+    errors = sorted(validator.iter_errors(manifest), key=lambda error: error.path)
+    if errors:
+        details = "\n".join(
+            f"{'/'.join(str(part) for part in error.path) or '/'} {error.message}"
+            for error in errors
+        )
+        raise RuntimeError(f"Template manifest validation failed.\n{details}")
+
+
+def main() -> int:
+    validate_template_manifest()
+    print("template.json is valid")
+    return 0

package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/worker.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import logging
+from uuid import uuid4
+
+from fastapi_sidecar.logging_utils import configure_logging, log_structured_event
+from fastapi_sidecar.receipts import build_receipt
+from fastapi_sidecar.settings import get_settings
+
+logger = logging.getLogger("fastapi_sidecar.worker")
+
+
+def main() -> int:
+    settings = get_settings()
+    configure_logging(settings.log_level)
+    receipt = build_receipt(
+        request_id=str(uuid4()),
+        tenant_id=settings.tenant_id,
+        handler_name="worker_bootstrap",
+        auth_mode="worker_bootstrap",
+        outcome="started",
+        extra={"pubsub_subscription": settings.pubsub_subscription or ""},
+    )
+    log_structured_event(
+        logger,
+        event="fastapi_sidecar.worker_bootstrap",
+        request_id=receipt["request_id"],
+        tenant_id=settings.tenant_id,
+        worker_name="worker_bootstrap",
+        auth_mode=receipt["auth_mode"],
+        outcome=receipt["outcome"],
+    )
+    return 0

package/assets/templates/fastapi-sidecar/template.json

@@ -0,0 +1,43 @@
+{
+  "template_id": "fastapi-sidecar",
+  "template_kind": "sidecar_fastapi_internal",
+  "template_profile": "bridge_internal",
+  "template_bundle_ref": "runtime/builder/templates/fastapi-sidecar",
+  "template_version": "0.1.0",
+  "materialize": {
+    "destination": "app"
+  },
+  "builder_edit_mode": "workspace_copy_only",
+  "seed_source": "runtime/builder/templates/fastapi-sidecar",
+  "required_bootstrap_steps": [
+    "python_env_sync",
+    "python_import_smoke"
+  ],
+  "runtime_contract_refs": [
+    "reference/mwv3-dj6-docs/auth_and_credential_contract.md",
+    "reference/mwv3-dj6-docs/runtime_app_pack_contract.md",
+    "reference/mwv3-dj6-docs/runtime_compute_isolation_and_sandboxing_contract.md"
+  ],
+  "sidecar_processes": [
+    {
+      "name": "api",
+      "process_type": "fastapi",
+      "entrypoint": "fastapi_sidecar.main:app",
+      "health_check_path": "/healthz",
+      "composition_profiles": [
+        "internal_api_only",
+        "worker_plus_internal_api"
+      ]
+    },
+    {
+      "name": "worker",
+      "process_type": "worker",
+      "entrypoint": "fastapi_sidecar.worker:main",
+      "composition_profiles": [
+        "worker_only",
+        "worker_plus_internal_api"
+      ]
+    }
+  ],
+  "example_features": {}
+}

package/assets/templates/fastapi-sidecar/template.schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://minutework.dev/schemas/runtime/builder/template.schema.json",
+  "title": "Runtime Builder Template Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "template_id",
+    "template_kind",
+    "template_profile",
+    "template_version",
+    "materialize",
+    "builder_edit_mode",
+    "seed_source",
+    "required_bootstrap_steps",
+    "example_features"
+  ],
+  "properties": {
+    "template_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "template_kind": {
+      "type": "string",
+      "enum": [
+        "sidecar_nextjs_private",
+        "sidecar_fastapi_internal"
+      ]
+    },
+    "template_profile": {
+      "type": "string",
+      "enum": [
+        "platform_session_bff",
+        "bridge_internal"
+      ]
+    },
+    "template_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "materialize": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "destination"
+      ],
+      "properties": {
+        "destination": {
+          "type": "string",
+          "const": "app"
+        }
+      }
+    },
+    "builder_edit_mode": {
+      "type": "string",
+      "const": "workspace_copy_only"
+    },
+    "seed_source": {
+      "type": "string",
+      "minLength": 1
+    },
+    "template_bundle_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "required_bootstrap_steps": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": [
+          "next_typegen",
+          "design_system_tokens",
+          "python_env_sync",
+          "python_import_smoke"
+        ]
+      }
+    },
+    "runtime_contract_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "sidecar_processes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/sidecarProcess"
+      }
+    },
+    "example_features": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/exampleFeature"
+      }
+    }
+  },
+  "$defs": {
+    "exampleFeature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "default_enabled"
+      ],
+      "properties": {
+        "default_enabled": {
+          "type": "boolean"
+        }
+      }
+    },
+    "sidecarProcess": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "process_type",
+        "entrypoint",
+        "composition_profiles"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "process_type": {
+          "type": "string",
+          "enum": [
+            "fastapi",
+            "worker",
+            "cron"
+          ]
+        },
+        "entrypoint": {
+          "type": "string",
+          "minLength": 1
+        },
+        "health_check_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "composition_profiles": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": [
+              "worker_only",
+              "internal_api_only",
+              "worker_plus_internal_api"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/assets/templates/fastapi-sidecar/tests/conftest.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from fastapi_sidecar.settings import get_settings
+
+TEMPLATE_ROOT = Path(__file__).resolve().parents[1]
+REPO_ROOT = TEMPLATE_ROOT.parents[3]
+NEXT_TEMPLATE_ROOT = REPO_ROOT / "runtime" / "builder" / "templates" / "next-tenant-app"
+SHARED_SCHEMA_PATH = REPO_ROOT / "runtime" / "builder" / "templates" / "template.schema.json"
+
+
+@pytest.fixture
+def configured_env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> dict[str, str]:
+    runtime_key_path = tmp_path / "runtime-key"
+    runtime_key_path.write_text("runtime-secret", encoding="utf-8")
+
+    env = {
+        "MW_API_BASE_URL": "https://platform.example.test",
+        "MW_RUNTIME_ID": "rt_test_sidecar",
+        "MW_TENANT_ID": "tenant_test_sidecar",
+        "MW_RUNTIME_KEY_PATH": str(runtime_key_path),
+        "MW_PLATFORM_DISPATCH_TOKEN": "dispatch-secret",
+        "MW_LOG_LEVEL": "INFO",
+        "MW_PUBSUB_SUBSCRIPTION": "projects/test/subscriptions/sidecar-worker",
+        "MW_WORKER_POLL_INTERVAL_SECONDS": "1.5",
+    }
+
+    for key, value in env.items():
+        monkeypatch.setenv(key, value)
+
+    get_settings.cache_clear()
+    yield env
+    get_settings.cache_clear()