@shanyucoder/flowgrid 0.1.0

package/adapters/fastapi/codegen/runners/fast_gen/write_files.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import json
+import hashlib
+import os
+from pathlib import Path
+
+from fast_gen.plan import render_template
+
+GENERATOR = "fastapi-codegen"
+PACKAGE_INIT = '"""Generated module package."""\n'
+
+
+def repo_root() -> Path:
+  target = os.environ.get("FLOWGRID_PROJECT_ROOT")
+  if not target:
+    raise RuntimeError("FLOWGRID_PROJECT_ROOT is required for the FastAPI adapter")
+  return Path(target).resolve()
+
+
+def _sha256(content: str) -> str:
+  return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def _package_version() -> str:
+  package_json = Path(__file__).resolve().parents[5] / "package.json"
+  return str(json.loads(package_json.read_text(encoding="utf-8"))["version"])
+
+
+def _safe_target(root: Path, relative_path: str) -> Path:
+  relative = Path(relative_path)
+  if relative.is_absolute() or ".." in relative.parts:
+    raise ValueError(f"Unsafe generated path (absolute or traversal): {relative_path}")
+  target = root / relative
+  if os.path.commonpath((str(root), str(target))) != str(root):
+    raise ValueError(f"Generated path escapes FLOWGRID_PROJECT_ROOT: {relative_path}")
+  _reject_symlinks(target, root)
+  return target
+
+
+def _reject_symlinks(target: Path, boundary: Path | None = None) -> None:
+  current = target
+  stop = boundary.parent if boundary is not None else Path(current.anchor)
+  while current != stop:
+    if current.is_symlink():
+      raise ValueError(f"Unsafe symlink in output path: {current}")
+    current = current.parent
+
+
+def _router_content(contexts: list[dict], existing: str = "") -> str:
+  imports = {
+    line
+    for line in existing.splitlines()
+    if line.startswith("from app.modules.") and " import " in line
+  }
+  for ctx in contexts:
+    imports.add(
+      f"from app.modules.{ctx['module_package']}.{ctx['entity_snake']}.router import "
+      f"router as {ctx['module_package']}_{ctx['entity_snake']}_router"
+    )
+  ordered = sorted(imports)
+  aliases = [line.split(" as ")[-1].strip() for line in ordered]
+  return "\n".join([
+    '"""Auto-generated by fast-gen — do not edit manually."""',
+    "",
+    "from fastapi import APIRouter",
+    "",
+    *ordered,
+    "",
+    "ROUTERS: list[APIRouter] = [",
+    *[f"  {alias}," for alias in aliases],
+    "]",
+    "",
+  ])
+
+
+def _planned_outputs(plan: dict) -> list[dict]:
+  root = repo_root()
+  outputs: list[dict] = []
+  for file in plan["files"]:
+    outputs.append({
+      **file,
+      "content": render_template(file["template"], file["ctx"]),
+    })
+  for ctx in plan["contexts"]:
+    base = Path("src/app/modules") / ctx["module_package"] / ctx["entity_snake"]
+    for folder in [base.parent, base, base / "schemas", base / "services", base / "presenters"]:
+      outputs.append({
+        "relativePath": str(folder / "__init__.py"),
+        "content": PACKAGE_INIT,
+        "template": "package-init",
+        "layer": "package",
+        "entity": ctx["entity"],
+        "module": ctx["module"],
+      })
+  unique: dict[str, dict] = {}
+  for output in outputs:
+    unique.setdefault(output["relativePath"], output)
+  router_rel = "src/app/generated_routers.py"
+  router_path = _safe_target(root, router_rel)
+  existing_router = router_path.read_text(encoding="utf-8") if router_path.exists() else ""
+  unique[router_rel] = {
+    "relativePath": router_rel,
+    "content": _router_content(plan["contexts"], existing_router),
+    "template": "generated-router",
+    "layer": "router-index",
+    "entity": None,
+    "module": None,
+  }
+  return list(unique.values())
+
+
+def _load_prior_manifest(path: Path) -> dict:
+  if not path.exists():
+    return {}
+  try:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return data if data.get("schemaVersion") == 2 and isinstance(data.get("files"), dict) else {}
+  except (OSError, json.JSONDecodeError):
+    return {}
+
+
+def execute_generation(
+  plan: dict,
+  feature_dir: Path,
+  spec_path: Path,
+  *,
+  dry_run: bool = False,
+) -> dict:
+  root = repo_root()
+  manifest_path = feature_dir / "generated" / "codegen.manifest.json"
+  handoff_path = feature_dir / "generated" / "HANDOFF.md"
+  _reject_symlinks(manifest_path)
+  _reject_symlinks(handoff_path)
+  prior = _load_prior_manifest(manifest_path)
+  prior_files = prior.get("files") or {}
+  outputs = _planned_outputs(plan)
+  decisions: list[dict] = []
+
+  for output in outputs:
+    rel = output["relativePath"]
+    target = _safe_target(root, rel)
+    expected_hash = _sha256(output["content"])
+    if not target.exists():
+      status = "would-write"
+    else:
+      existing_hash = hashlib.sha256(target.read_bytes()).hexdigest()
+      if existing_hash == expected_hash:
+        status = "unchanged"
+      elif prior_files.get(rel, {}).get("sha256") == existing_hash:
+        status = "would-write"
+      elif plan["force"]:
+        status = "would-force"
+      else:
+        status = "conflict"
+    decisions.append({**output, "target": target, "sha256": expected_hash, "status": status})
+
+  conflicts = [item for item in decisions if item["status"] == "conflict"]
+  if conflicts:
+    return {"decisions": decisions, "conflicts": conflicts, "manifestPath": manifest_path}
+
+  manifest = {
+    "schemaVersion": 2,
+    "packageVersion": _package_version(),
+    "generator": GENERATOR,
+    "spec": str(spec_path),
+    "entities": [
+      {
+        "module": ctx["module"],
+        "modulePackage": ctx["module_package"],
+        "entity": ctx["entity"],
+        "entityPackage": ctx["entity_snake"],
+        "routePrefix": ctx["route_prefix"],
+      }
+      for ctx in plan["contexts"]
+    ],
+    "files": {
+      item["relativePath"]: {
+        "sha256": item["sha256"],
+        "template": item["template"],
+        "layer": item["layer"],
+        "entity": item["entity"],
+        "module": item["module"],
+      }
+      for item in decisions
+    },
+  }
+  if not dry_run:
+    for item in decisions:
+      if item["status"] != "unchanged":
+        item["target"].parent.mkdir(parents=True, exist_ok=True)
+        item["target"].write_text(item["content"], encoding="utf-8")
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    handoff_path.write_text(render_handoff(plan, spec_path), encoding="utf-8")
+  return {
+    "decisions": decisions,
+    "conflicts": [],
+    "manifestPath": manifest_path,
+    "handoffPath": handoff_path,
+    "manifest": manifest,
+  }
+
+
+def render_handoff(plan: dict, spec_path: Path) -> str:
+  lines = ["# fast-gen HANDOFF", "", f"- Spec: `{spec_path}`", "", "## Entities", ""]
+  lines.extend(
+    f"- `{ctx['module']}.{ctx['entity']}` → `{ctx['route_prefix']}`"
+    for ctx in plan["contexts"]
+  )
+  lines.extend([
+    "",
+    "## Verify",
+    "",
+    "```bash",
+    "PYTHONPATH=src .venv/bin/pytest -q",
+    "PYTHONPATH=src .venv/bin/uvicorn app.main:app --port 4000 --app-dir src",
+    "```",
+    "",
+  ])
+  return "\n".join(lines)
+
+
+def export_openapi(feature_dir: Path, _spec: dict) -> Path:
+  import yaml
+  from app.main import app
+
+  schema = app.openapi()
+  out_path = feature_dir / "backend" / "02-openapi.yaml"
+  out_path.parent.mkdir(parents=True, exist_ok=True)
+  out_path.write_text(yaml.dump(schema, sort_keys=False, allow_unicode=True), encoding="utf-8")
+  return out_path

package/adapters/fastapi/codegen/runners/generate

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+export PYTHONPATH="${ROOT}/codegen/runners:${ROOT}/unitgen/runners:${ROOT}/registries:${ROOT}/tools:${ROOT}/src"
+exec "${ROOT}/.venv/bin/python" -m fast_gen.cli "$@"

package/adapters/fastapi/codegen/runners/validate-registry.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { access, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const target = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+const adapter = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+async function exists(file) {
+  try {
+    await access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  const registryPath = path.join(target, 'registries/codegen.registry.json')
+  const registry = JSON.parse(await readFile(registryPath, 'utf8'))
+  const errors = []
+  if (!registry.version || !registry.profiles || !registry.genTags) {
+    errors.push('registry requires version, profiles and genTags')
+  }
+  for (const [tag, definition] of Object.entries(registry.genTags ?? {})) {
+    const templates = [
+      ...(definition.template ? [definition.template] : []),
+      ...(definition.templates ?? []),
+    ]
+    if (!templates.length) errors.push(`${tag}: template/templates missing`)
+    for (const template of templates) {
+      if (!(await exists(path.join(adapter, 'templates', template)))) {
+        errors.push(`${tag}: packaged template missing: ${template}`)
+      }
+    }
+  }
+  const commonPath = path.join(target, 'registries/common.registry.json')
+  if (await exists(commonPath)) {
+    const common = JSON.parse(await readFile(commonPath, 'utf8'))
+    if (!common.version || !common.entries || !common.aliasIndex) {
+      errors.push('common registry requires version, entries and aliasIndex')
+    }
+    for (const [alias, id] of Object.entries(common.aliasIndex ?? {})) {
+      if (!common.entries?.[id]) errors.push(`common alias "${alias}" targets missing "${id}"`)
+    }
+  }
+  if (errors.length) throw new Error(errors.join('\n'))
+  console.log(`fastapi-codegen.registry v${registry.version}: OK`)
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/adapters/fastapi/codegen/templates/presenter.py.j2

@@ -0,0 +1,11 @@
+from typing import Any
+
+from app.common.presenters.base import BasePresenter
+
+
+class {{ entity_pascal }}Presenter(BasePresenter):
+  def __init__(self, item: dict[str, Any]) -> None:
+    self._item = item
+
+  def to_contract(self) -> dict[str, Any]:
+    return dict(self._item)

package/adapters/fastapi/codegen/templates/router.py.j2

@@ -0,0 +1,69 @@
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.common.http.api_response import success
+from app.modules.{{ module_package }}.{{ entity_snake }}.presenters.{{ entity_snake }}_presenter import {{ entity_pascal }}Presenter
+{% if wire.search or wire.create or wire.update %}
+from app.modules.{{ module_package }}.{{ entity_snake }}.schemas.request import (
+{% if wire.search %}  {{ entity_pascal }}SearchRequest,
+{% endif %}
+{% if wire.create %}  {{ entity_pascal }}CreateRequest,
+{% endif %}
+{% if wire.update %}  {{ entity_pascal }}UpdateRequest,
+{% endif %}
+)
+{% endif %}
+{% if wire.search %}from app.modules.{{ module_package }}.{{ entity_snake }}.services.search_service import {{ entity_pascal }}SearchService
+{% endif %}
+{% if wire.create %}from app.modules.{{ module_package }}.{{ entity_snake }}.services.create_service import {{ entity_pascal }}CreateService
+{% endif %}
+{% if wire.update %}from app.modules.{{ module_package }}.{{ entity_snake }}.services.update_service import {{ entity_pascal }}UpdateService
+{% endif %}
+{% if wire.delete %}from app.modules.{{ module_package }}.{{ entity_snake }}.services.delete_service import {{ entity_pascal }}DeleteService
+{% endif %}
+
+router = APIRouter(prefix="{{ route_prefix }}", tags=["{{ module_kebab }}"])
+{% if wire.search %}_search = {{ entity_pascal }}SearchService()
+{% endif %}
+{% if wire.create %}_create = {{ entity_pascal }}CreateService()
+{% endif %}
+{% if wire.update %}_update = {{ entity_pascal }}UpdateService()
+{% endif %}
+{% if wire.delete %}_delete = {{ entity_pascal }}DeleteService()
+{% endif %}
+
+
+{% if wire.search %}
+@router.get("")
+async def search_{{ entity_snake }}(query: {{ entity_pascal }}SearchRequest = Depends()) -> dict:
+  items, total = await _search.search(query)
+  data = {"items": [{{ entity_pascal }}Presenter(i).to_contract() for i in items], "total": total}
+  return success(data, message=_("Retrieved successfully"), meta={"pagination": {"page": query.page, "per_page": query.per_page, "total": total}})
+{% endif %}
+
+
+{% if wire.create %}
+@router.post("", status_code=201)
+async def create_{{ entity_snake }}(body: {{ entity_pascal }}CreateRequest) -> dict:
+  item = await _create.create(body)
+  return success({{ entity_pascal }}Presenter(item).to_contract(), message=_("Created successfully"), code=201)
+{% endif %}
+
+
+{% if wire.update %}
+@router.patch("/{id}")
+async def update_{{ entity_snake }}(id: int, body: {{ entity_pascal }}UpdateRequest) -> dict:
+  item = await _update.update(id, body)
+  if item is None:
+    raise HTTPException(status_code=404, detail="Not Found")
+  return success({{ entity_pascal }}Presenter(item).to_contract(), message=_("Updated successfully"))
+{% endif %}
+
+
+{% if wire.delete %}
+@router.delete("/{id}")
+async def delete_{{ entity_snake }}(id: int) -> dict:
+  ok = await _delete.delete(id)
+  if not ok:
+    raise HTTPException(status_code=404, detail="Not Found")
+  return success({"success": True})
+{% endif %}

package/adapters/fastapi/codegen/templates/schemas_request.py.j2

@@ -0,0 +1,26 @@
+from pydantic import BaseModel, Field
+
+
+class {{ entity_pascal }}SearchRequest(BaseModel):
+  page: int = Field(default=1, ge=1)
+  per_page: int = Field(default=20, ge=1, le=100)
+
+
+{% if wire.create %}
+class {{ entity_pascal }}CreateRequest(BaseModel):
+{% for field in field_defs %}
+{% if field.name != 'id' %}
+  {{ field.name }}: {{ field.type }}{% if not field.required %} | None = None{% endif %}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+
+{% if wire.update %}
+class {{ entity_pascal }}UpdateRequest(BaseModel):
+{% for field in field_defs %}
+{% if field.name != 'id' %}
+  {{ field.name }}: {{ field.type }} | None = None
+{% endif %}
+{% endfor %}
+{% endif %}

package/adapters/fastapi/codegen/templates/schemas_response.py.j2

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+
+class {{ entity_pascal }}Resource(BaseModel):
+{% for field in field_defs %}
+  {{ field.name }}: {{ field.type }}{% if not field.required %} | None = None{% endif %}
+{% endfor %}

package/adapters/fastapi/codegen/templates/service_create.py.j2

@@ -0,0 +1,10 @@
+from app.modules.{{ module_package }}.{{ entity_snake }}.schemas.request import {{ entity_pascal }}CreateRequest
+from app.modules.{{ module_package }}.{{ entity_snake }}.services.store import _STORE
+
+
+class {{ entity_pascal }}CreateService:
+  async def create(self, body: {{ entity_pascal }}CreateRequest) -> dict:
+    new_id = max((row.get("id", 0) for row in _STORE), default=0) + 1
+    item = {"id": new_id, **body.model_dump(exclude_none=True)}
+    _STORE.append(item)
+    return item

package/adapters/fastapi/codegen/templates/service_delete.py.j2

@@ -0,0 +1,10 @@
+from app.modules.{{ module_package }}.{{ entity_snake }}.services.store import _STORE
+
+
+class {{ entity_pascal }}DeleteService:
+  async def delete(self, resource_id: int) -> bool:
+    for idx, row in enumerate(_STORE):
+      if row.get("id") == resource_id:
+        _STORE.pop(idx)
+        return True
+    return False

package/adapters/fastapi/codegen/templates/service_search.py.j2

@@ -0,0 +1,9 @@
+from app.modules.{{ module_package }}.{{ entity_snake }}.schemas.request import {{ entity_pascal }}SearchRequest
+from app.modules.{{ module_package }}.{{ entity_snake }}.services.store import _STORE
+
+
+class {{ entity_pascal }}SearchService:
+  async def search(self, query: {{ entity_pascal }}SearchRequest) -> tuple[list[dict], int]:
+    start = (query.page - 1) * query.per_page
+    items = _STORE[start : start + query.per_page]
+    return items, len(_STORE)

package/adapters/fastapi/codegen/templates/service_update.py.j2

@@ -0,0 +1,11 @@
+from app.modules.{{ module_package }}.{{ entity_snake }}.schemas.request import {{ entity_pascal }}UpdateRequest
+from app.modules.{{ module_package }}.{{ entity_snake }}.services.store import _STORE
+
+
+class {{ entity_pascal }}UpdateService:
+  async def update(self, resource_id: int, body: {{ entity_pascal }}UpdateRequest) -> dict | None:
+    for row in _STORE:
+      if row.get("id") == resource_id:
+        row.update(body.model_dump(exclude_none=True))
+        return row
+    return None

package/adapters/fastapi/codegen/templates/store.py.j2

@@ -0,0 +1 @@
+_STORE: list[dict] = [{"id": 1, "name": "Sample"}]

package/adapters/fastapi/codegen/templates/test_router.py.j2

@@ -0,0 +1,13 @@
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_{{ entity_snake }}_search_envelope():
+  response = client.get("/api{{ route_prefix }}")
+  assert response.status_code == 200
+  body = response.json()
+  assert body["success"] is True
+  assert "items" in body["data"]

package/adapters/fastapi/registries/codegen.registry.json

@@ -0,0 +1,47 @@
+{
+  "version": 1,
+  "description": "FastAPI codegen registry — Jinja2 templates for fast-api-base modules.",
+  "profiles": {
+    "crud-standard": {
+      "defaultGenTags": ["#gen:router", "#gen:schemas", "#gen:search", "#gen:create", "#gen:presenter", "#gen:test"]
+    }
+  },
+  "genTags": {
+    "#gen:router": {
+      "layer": "router",
+      "template": "router.py.j2"
+    },
+    "#gen:schemas": {
+      "layer": "schemas",
+      "templates": ["schemas_request.py.j2", "schemas_response.py.j2"]
+    },
+    "#gen:search": {
+      "layer": "service",
+      "template": "service_search.py.j2",
+      "when": "wire.search"
+    },
+    "#gen:create": {
+      "layer": "service",
+      "template": "service_create.py.j2",
+      "when": "wire.create"
+    },
+    "#gen:update": {
+      "layer": "service",
+      "template": "service_update.py.j2",
+      "when": "wire.update"
+    },
+    "#gen:delete": {
+      "layer": "service",
+      "template": "service_delete.py.j2",
+      "when": "wire.delete"
+    },
+    "#gen:presenter": {
+      "layer": "presenter",
+      "template": "presenter.py.j2"
+    },
+    "#gen:test": {
+      "layer": "test",
+      "template": "test_router.py.j2"
+    }
+  }
+}

package/adapters/fastapi/registries/common.registry.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "description": "Platform common patterns — helpers, deps, policies, clients (fast-api-base).",
+  "entries": {
+    "auth.current-roles": {
+      "status": "planned",
+      "tag": "#common:auth-current-roles",
+      "kind": "dependency",
+      "path": "src/app/common/auth/roles.py",
+      "symbol": "get_current_roles",
+      "summary": "Current user roles for policy checks — promote from inline module logic",
+      "usedBy": [],
+      "specRefs": [],
+      "tests": "tests/unit/common/auth/test_roles.py"
+    }
+  },
+  "aliasIndex": {
+    "check auth role": "auth.current-roles",
+    "current roles": "auth.current-roles",
+    "get current roles": "auth.current-roles",
+    "user roles": "auth.current-roles"
+  }
+}

package/adapters/fastapi/registries/unit-test.registry.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "description": "FastAPI unit test codegen registry.",
+  "layers": {
+    "service": {
+      "template": "test_service.py.j2"
+    },
+    "router": {
+      "template": "test_router.py.j2"
+    }
+  }
+}

package/adapters/fastapi/unitgen/runners/fast_unit_gen/__init__.py

@@ -0,0 +1 @@
+"""FastAPI unit test codegen."""