minutework 0.1.0

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

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from fastapi_sidecar.main import app
+
+
+def test_healthz_succeeds(configured_env) -> None:
+    with TestClient(app) as client:
+        response = client.get("/healthz")
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+
+def test_internal_route_rejects_missing_auth(configured_env) -> None:
+    with TestClient(app) as client:
+        response = client.post("/internal/v1/dispatch", json={"operation": "sync"})
+
+    assert response.status_code == 401
+    assert response.json()["detail"] == "Platform dispatch authentication required."
+
+
+def test_internal_route_accepts_platform_dispatch_auth(configured_env) -> None:
+    with TestClient(app) as client:
+        response = client.post(
+            "/internal/v1/dispatch",
+            json={"operation": "sync"},
+            headers={
+                "X-Platform-Dispatch-Token": configured_env["MW_PLATFORM_DISPATCH_TOKEN"],
+                "X-Request-Id": "req-test-123",
+            },
+        )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["accepted"] is True
+    assert payload["receipt"]["request_id"] == "req-test-123"
+    assert payload["receipt"]["auth_mode"] == "internal_only"

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

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from starlette.requests import Request
+
+from fastapi_sidecar.auth import require_runtime_token
+from fastapi_sidecar.settings import get_settings
+
+
+def _build_request(headers: dict[str, str]) -> Request:
+    scope = {
+        "type": "http",
+        "headers": [
+            (key.lower().encode("utf-8"), value.encode("utf-8")) for key, value in headers.items()
+        ],
+    }
+    return Request(scope)
+
+
+def test_require_runtime_token_accepts_runtime_machine_headers(configured_env) -> None:
+    request = _build_request(
+        {
+            "X-Runtime-Id": configured_env["MW_RUNTIME_ID"],
+            "X-Runtime-Key": "runtime-secret",
+            "X-Request-Id": "req-runtime-token",
+        }
+    )
+
+    context = require_runtime_token(request, get_settings())
+
+    assert context.request_id == "req-runtime-token"
+    assert context.auth_mode == "runtime_token"
+    assert context.principal_kind == "runtime_machine"

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

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import httpx
+
+from fastapi_sidecar.bridge.client import BridgeClient
+from fastapi_sidecar.settings import get_settings
+
+
+def test_bridge_client_builds_runtime_headers(configured_env) -> None:
+    client = BridgeClient(settings=get_settings(), client=httpx.Client(base_url="https://unused.test"))
+
+    assert client.runtime_headers() == {
+        "X-Runtime-Id": configured_env["MW_RUNTIME_ID"],
+        "X-Runtime-Key": "runtime-secret",
+    }
+
+
+def test_bridge_client_sends_runtime_headers(configured_env) -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["X-Runtime-Id"] == configured_env["MW_RUNTIME_ID"]
+        assert request.headers["X-Runtime-Key"] == "runtime-secret"
+        return httpx.Response(200, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+    http_client = httpx.Client(
+        base_url=configured_env["MW_API_BASE_URL"],
+        transport=transport,
+    )
+    client = BridgeClient(settings=get_settings(), client=http_client)
+
+    assert client.request_json("POST", "/api/v1/test/", payload={"hello": "world"}) == {"ok": True}

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

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+
+from conftest import TEMPLATE_ROOT
+
+
+def test_materialization_smoke(configured_env, tmp_path) -> None:
+    destination = tmp_path / "app"
+    shutil.copytree(TEMPLATE_ROOT, destination)
+
+    for required_path in (
+        destination / "template.json",
+        destination / "template.schema.json",
+        destination / "pyproject.toml",
+        destination / "src" / "fastapi_sidecar" / "main.py",
+        destination / "src" / "fastapi_sidecar" / "worker.py",
+    ):
+        assert required_path.exists()
+
+    env = os.environ.copy()
+    env.update(configured_env)
+    env["PYTHONPATH"] = str(destination / "src")
+
+    validator = subprocess.run(
+        [sys.executable, "tools/template/validate_template.py"],
+        cwd=destination,
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert validator.returncode == 0, validator.stderr
+
+    import_smoke = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            (
+                "from fastapi_sidecar.main import app; "
+                "from fastapi_sidecar.worker import main; "
+                "assert app is not None; "
+                "raise SystemExit(main())"
+            ),
+        ],
+        cwd=destination,
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert import_smoke.returncode == 0, import_smoke.stderr

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

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+
+from conftest import NEXT_TEMPLATE_ROOT, SHARED_SCHEMA_PATH, TEMPLATE_ROOT
+
+from fastapi_sidecar.template_validation import validate_template_manifest
+
+
+def _load_json(path):
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def test_schema_copies_stay_identical() -> None:
+    shared = SHARED_SCHEMA_PATH.read_text(encoding="utf-8")
+    next_copy = (NEXT_TEMPLATE_ROOT / "template.schema.json").read_text(encoding="utf-8")
+    fastapi_copy = (TEMPLATE_ROOT / "template.schema.json").read_text(encoding="utf-8")
+
+    assert shared == next_copy == fastapi_copy
+
+
+def test_next_manifest_validates_against_bundled_schema() -> None:
+    validate_template_manifest(NEXT_TEMPLATE_ROOT)
+
+
+def test_fastapi_manifest_validates_against_bundled_schema() -> None:
+    validate_template_manifest(TEMPLATE_ROOT)
+
+
+def test_fastapi_manifest_declares_expected_processes() -> None:
+    manifest = _load_json(TEMPLATE_ROOT / "template.json")
+    assert manifest["template_profile"] == "bridge_internal"
+    assert manifest["required_bootstrap_steps"] == ["python_env_sync", "python_import_smoke"]
+    assert manifest["example_features"] == {}
+    assert manifest["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"],
+        },
+    ]

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

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from fastapi_sidecar.worker import main
+
+
+def test_worker_bootstrap_starts_cleanly(configured_env) -> None:
+    assert main() == 0

package/assets/templates/fastapi-sidecar/tools/template/validate_template.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+TEMPLATE_ROOT = Path(__file__).resolve().parents[2]
+SRC_ROOT = TEMPLATE_ROOT / "src"
+
+
+def run() -> int:
+    if str(SRC_ROOT) not in sys.path:
+        sys.path.insert(0, str(SRC_ROOT))
+
+    from fastapi_sidecar.template_validation import main
+
+    return main()
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())

package/assets/templates/next-tenant-app/.env.example

@@ -0,0 +1,8 @@
+MW_PLATFORM_BASE_URL=http://127.0.0.1:8000
+MW_CONTENT_API_TOKEN=
+MW_TEMPLATE_APP_NAME=MinuteWork Combined Starter
+# Local development example. Set this explicitly per environment.
+MW_PUBLIC_BASE_URL=http://127.0.0.1:3000
+MW_PUBLIC_SITE_PROPERTY_KEY=main-site
+MW_PUBLIC_SITE_ENV=preview
+MW_ENABLE_RUNTIME_COMMAND_EXAMPLE=false

package/assets/templates/next-tenant-app/.storybook/main.ts

@@ -0,0 +1,19 @@
+import { defineMain } from "@storybook/nextjs-vite/node";
+
+export default defineMain({
+  stories: [
+    "../src/design-system/**/*.stories.@(ts|tsx|mdx)",
+    "../src/design-system/docs/**/*.mdx",
+  ],
+  addons: ["@storybook/addon-docs", "@storybook/addon-a11y"],
+  framework: {
+    name: "@storybook/nextjs-vite",
+    options: {
+      nextConfigPath: "../next.config.ts",
+    },
+  },
+  staticDirs: ["../public"],
+  docs: {
+    defaultName: "Overview",
+  },
+});

package/assets/templates/next-tenant-app/.storybook/preview.tsx

@@ -0,0 +1,38 @@
+import { definePreview } from "@storybook/nextjs-vite";
+
+import "../src/app/globals.css";
+import { ThemeProvider } from "../src/lib/theme";
+
+export default definePreview({
+  decorators: [
+    (Story) => (
+      <ThemeProvider
+        attribute="class"
+        defaultTheme="light"
+        enableSystem
+        disableTransitionOnChange
+      >
+        <div className="min-h-screen bg-background p-6 text-foreground">
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+  parameters: {
+    layout: "centered",
+    nextjs: {
+      appDirectory: true,
+    },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    options: {
+      storySort: {
+        order: ["Design System"],
+      },
+    },
+  },
+});

package/assets/templates/next-tenant-app/README.md

@@ -0,0 +1,115 @@
+# Next Tenant App Template
+
+This directory is the canonical combined Next.js web starter for Builder. It is the bundle that Builder will later materialize into `BuilderWorkspace.sandbox_root/app/`.
+
+`apps/mw-next-client` is still the repo-side seed used to harden and evolve this scaffold. It is not the runtime template location.
+
+## Auth profile
+
+This template stays fixed to the `platform_session_bff` profile:
+
+- the browser talks only to the Next.js app
+- upstream platform `sessionid` and `csrftoken` stay server-owned
+- unsafe upstream requests bootstrap and forward CSRF through the BFF
+- there is no browser-to-runtime direct access
+- there is no local JWT system, local user table, or parallel auth stack
+
+## Runtime requirements
+
+- Node.js `20.9.0` or newer
+- `pnpm@9.0.0`
+
+## Default route shape
+
+The template ships one combined app with two explicit route surfaces:
+
+- public routes at the root: `/`, `/pricing`, `/docs`, `/blog`, `/login`
+- authenticated routes under `/app`
+- optional runtime example under `/app/examples/runtime-commands`
+
+Public marketing, docs, and blog routes render through a swappable public-content adapter seam. The authenticated shell keeps tenant context controls, password flows, and the platform-session BFF boundary.
+
+## Public content adapter
+
+The public content seam lives under `src/lib/content`.
+
+The default built-in adapter is `MinuteWorkPublicSiteContentAdapter`. It calls the
+MinuteWork gateway with a server-only content token and reads the narrow
+`mw.core.site` public-site snapshot contract.
+
+The gateway response carries an explicit boundary:
+
+- `environment=preview` must declare `source_boundary=runtime_preview`
+- `environment=live` must declare `source_boundary=published_live`
+
+That keeps preview free to use runtime-backed draft reads while keeping live
+publication-safe for static generation and anonymous delivery.
+
+To replace the built-ins for a tenant-specific CMS or content API, implement the hook in `src/lib/content/custom-adapter.ts`.
+
+## Example gating
+
+`MW_ENABLE_RUNTIME_COMMAND_EXAMPLE=false` by default.
+
+When disabled:
+
+- `/app/examples/runtime-commands` returns `404`
+- the example gateway API routes return `404`
+- the example navigation entry is omitted
+
+## Environment
+
+Copy `.env.example` to `.env.local` when running the template directly.
+
+- `MW_PLATFORM_BASE_URL` is required
+- `MW_CONTENT_API_TOKEN` is required and must stay server-only
+- `MW_TEMPLATE_APP_NAME` defaults to `MinuteWork Combined Starter`
+- `MW_PUBLIC_BASE_URL` is required and should match the deployed public origin
+- `MW_PUBLIC_SITE_PROPERTY_KEY` is required and selects the `PublishedWebProperty` backing the site
+- `MW_PUBLIC_SITE_ENV` defaults to `preview`
+- `MW_ENABLE_RUNTIME_COMMAND_EXAMPLE` defaults to `false`
+
+## SEO baseline
+
+The public route surface ships with:
+
+- canonical URLs derived from `MW_PUBLIC_BASE_URL`
+- `robots.ts` and `sitemap.ts`
+- Open Graph metadata for marketing and article/detail pages
+- server-rendered public pages by default, with no tenant/session reads during render
+- docs/blog static params generated from the same public-site snapshot used during render
+- graceful empty states for fresh properties with no authored or no published content
+
+Private routes under `/app` are marked `noindex`.
+
+## Generated artifact policy
+
+Checked-in generated artifacts are limited to:
+
+- `next-env.d.ts`
+- `src/design-system/tokens/manifest.ts`
+- `src/design-system/tokens/manifest.json`
+- `pnpm-lock.yaml`
+
+Generated build outputs such as `.next/`, `storybook-static/`, `test-results/`, and `tools/design-system/__screenshots__/` are not canonical template contents.
+
+## Validation
+
+Use `pnpm validate` from this directory. It runs:
+
+1. `template:validate`
+2. `template:route-contract`
+3. `next typegen`
+4. `design-system:tokens`
+5. `design-system:check`
+6. `typecheck`
+7. `lint`
+8. `test`
+9. `build`
+10. `build-storybook`
+
+`template:validate` validates `template.json` against the bundled `template.schema.json`, so the template remains self-validating after Builder materializes it into a workspace sandbox.
+
+`template:route-contract` verifies that the combined public/private route tree, metadata routes, and content-adapter entrypoints remain present in the template.
+
+Inside the repo, the shared schema at `runtime/builder/templates/template.schema.json` is authoritative. The bundled `template.schema.json` inside this template must stay byte-equivalent, and `template:validate` fails if the two drift.

package/assets/templates/next-tenant-app/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/design-system",
+    "utils": "@/lib/utils",
+    "ui": "@/design-system/primitives",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/assets/templates/next-tenant-app/eslint.config.mjs

@@ -0,0 +1,41 @@
+import nextCoreWebVitals from "eslint-config-next/core-web-vitals";
+import nextTypeScript from "eslint-config-next/typescript";
+
+import designSystemPlugin from "./tools/design-system/eslint-plugin-design-system.mjs";
+
+const eslintConfig = [
+  ...nextCoreWebVitals,
+  ...nextTypeScript,
+  {
+    ignores: [
+      ".next/**",
+      "node_modules/**",
+      "next-env.d.ts",
+      "storybook-static/**",
+      "src/design-system/tokens/manifest.ts",
+    ],
+  },
+  {
+    files: ["src/app/**/*.{ts,tsx}", "src/features/**/*.{ts,tsx}"],
+    plugins: {
+      "design-system": designSystemPlugin,
+    },
+    rules: {
+      "design-system/no-design-system-bypass-imports": "error",
+      "design-system/no-cva-outside-design-system": "error",
+      "design-system/no-raw-design-values": "error",
+      "design-system/no-bespoke-visual-stacks-in-features": "error",
+    },
+  },
+  {
+    files: ["src/design-system/**/*.{ts,tsx}"],
+    plugins: {
+      "design-system": designSystemPlugin,
+    },
+    rules: {
+      "design-system/no-raw-design-values": "error",
+    },
+  },
+];
+
+export default eslintConfig;

package/assets/templates/next-tenant-app/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/assets/templates/next-tenant-app/next.config.ts

@@ -0,0 +1,8 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+  typedRoutes: true,
+};
+
+export default nextConfig;