@shanyucoder/flowgrid 0.1.0

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

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+TOOLS_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(TOOLS_DIR))
+
+from fast_gen.plan import build_file_plan, repo_root  # noqa: E402
+from fast_gen.read_spec import read_spec_file  # noqa: E402
+from fast_gen.registry import load_registry  # noqa: E402
+from fast_gen.write_files import execute_generation, export_openapi  # noqa: E402
+
+def merge_i18n_flat(spec_i18n: dict, locales_dir: Path, dry_run: bool) -> None:
+  if not spec_i18n or not isinstance(spec_i18n, dict):
+    return
+  data_by_lang = {}
+  for key, translations in spec_i18n.items():
+    if isinstance(translations, dict):
+      for lang, val in translations.items():
+        if lang not in data_by_lang:
+          data_by_lang[lang] = {}
+        data_by_lang[lang][key] = val
+          
+  for lang, new_keys in data_by_lang.items():
+    locale_path = locales_dir / f"{lang}.json"
+    current_data = {}
+    if locale_path.exists():
+      try:
+        with open(locale_path, 'r', encoding='utf-8') as f:
+          current_data = json.load(f)
+      except Exception:
+        current_data = {}
+          
+    for k, v in new_keys.items():
+      current_data[k] = v
+        
+    if not dry_run:
+      locales_dir.mkdir(parents=True, exist_ok=True)
+      with open(locale_path, 'w', encoding='utf-8') as f:
+        json.dump(current_data, f, ensure_ascii=False, indent=2)
+        f.write('\n')
+          
+    print(f"  {'[dry] ' if dry_run else 'write'}: locales/{lang}.json (+{len(new_keys)} keys)")
+
+def registry_cmd() -> None:
+  data = load_registry(repo_root())
+  print(json.dumps(data, indent=2))
+
+
+def dry_cmd(spec: str, force: bool = False) -> None:
+  _run(spec, dry_run=True, force=force)
+
+
+def write_cmd(spec: str, force: bool = False) -> None:
+  _run(spec, dry_run=False, force=force)
+
+
+def openapi_cmd(spec: str) -> None:
+  spec_data, spec_path, feature_dir = read_spec_file(spec)
+  sys.path.insert(0, str(repo_root() / "src"))
+  out = export_openapi(feature_dir, spec_data)
+  print(f"openapi: {out}")
+
+
+def _run(spec: str, *, dry_run: bool, force: bool) -> None:
+  spec_data, spec_path, feature_dir = read_spec_file(spec)
+  plan = build_file_plan(spec_data, force=force)
+  print(f"fast-gen: entities={len(plan['contexts'])} profile={plan['ctx']['profile']}")
+  print(f"  spec: {spec_path}")
+  if dry_run:
+    print("  mode: dry-run")
+  if force:
+    print("  mode: force")
+
+  for warning in plan["warnings"]:
+    print(f"  warning: {warning}", file=sys.stderr)
+  result = execute_generation(plan, feature_dir, spec_path, dry_run=dry_run)
+  for item in result["decisions"]:
+    status = item["status"]
+    if not dry_run and status in ("would-write", "would-force"):
+      status = "write" if status == "would-write" else "force"
+    print(f"  {status}: {item['relativePath']}")
+  if result["conflicts"]:
+    print("Blocked: generated files have unmanaged or locally modified conflicts.", file=sys.stderr)
+    print("Resolve the listed files or re-run with --force:", file=sys.stderr)
+    for item in result["conflicts"]:
+      print(f"  conflict: {item['relativePath']}", file=sys.stderr)
+    raise SystemExit(2)
+  if not dry_run:
+    print(f"  manifest: {result['manifestPath']}")
+
+  if "i18n" in spec_data:
+    locales_dir = repo_root() / "locales"
+    merge_i18n_flat(spec_data["i18n"], locales_dir, dry_run)
+
+
+def resolve_spec_paths(spec: str | None, id_val: str | None) -> list[str]:
+  if spec:
+    return [spec]
+  if not id_val:
+    print("Error: --spec or --id required", file=sys.stderr)
+    sys.exit(1)
+  
+  import subprocess
+  script = TOOLS_DIR.parent.parent / "shared" / "resolve-cli.mjs"
+  try:
+    res = subprocess.run(
+      ["node", str(script), str(repo_root()), id_val, "api-codegen"],
+      capture_output=True, text=True, check=True
+    )
+    data = json.loads(res.stdout)
+    if not data.get("success"):
+      print(f"fast-gen: FAIL --id {id_val}: {data.get('error')}", file=sys.stderr)
+      sys.exit(1)
+    
+    paths = data.get("paths", [])
+    notes = data.get("notes", [])
+    kind = data.get("kind", "unknown")
+    
+    for note in notes:
+      print(f"  note: {note}")
+    if not paths:
+      print(f"Error: --id {id_val}: no codegen specs", file=sys.stderr)
+      sys.exit(1)
+      
+    print(f"fast-gen: --id {id_val} → {len(paths)} spec(s) ({kind})")
+    return paths
+  except Exception as e:
+    print(f"Error resolving --id {id_val}: {e}", file=sys.stderr)
+    sys.exit(1)
+
+def main() -> None:
+  parser = argparse.ArgumentParser(description="FastAPI codegen")
+  subparsers = parser.add_subparsers(dest="command", required=True)
+  subparsers.add_parser("registry")
+  for command in ("dry", "write", "openapi"):
+    child = subparsers.add_parser(command)
+    child.add_argument("--spec", required=False)
+    child.add_argument("--id", required=False)
+    if command != "openapi":
+      child.add_argument("--force", action="store_true")
+  args = parser.parse_args()
+  
+  if args.command == "registry":
+    registry_cmd()
+    return
+
+  paths = resolve_spec_paths(getattr(args, "spec", None), getattr(args, "id", None))
+  
+  if len(paths) > 1:
+    print(f"fast-gen: {len(paths)} spec(s) to process")
+
+  failed = 0
+  for spec_path in paths:
+    try:
+      if args.command == "dry":
+        dry_cmd(spec_path, getattr(args, "force", False))
+      elif args.command == "write":
+        write_cmd(spec_path, getattr(args, "force", False))
+      else:
+        openapi_cmd(spec_path)
+      if len(paths) > 1:
+        print("")
+    except Exception as e:
+      failed += 1
+      print(f"fast-gen: FAIL {spec_path}: {e}", file=sys.stderr)
+
+  if failed > 0:
+    sys.exit(1)
+
+if __name__ == "__main__":
+  main()

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

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import os
+import keyword
+import re
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from fast_gen.read_spec import to_kebab, to_pascal, to_snake
+from fast_gen.registry import load_registry
+from fast_gen.wire import resolve_wire
+
+
+def render_template(template_name: str, ctx: dict, *, templates_dir: Path | None = None) -> str:
+  base = templates_dir or (Path(__file__).resolve().parents[2] / "templates")
+  env = Environment(
+    loader=FileSystemLoader(str(base)),
+    autoescape=select_autoescape(enabled_extensions=()),
+    trim_blocks=True,
+    lstrip_blocks=True,
+  )
+  return env.get_template(template_name).render(**ctx)
+
+
+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 python_identifier(value: str, label: str) -> str:
+  identifier = to_snake(value)
+  if not identifier.isidentifier() or keyword.iskeyword(identifier):
+    raise ValueError(f"Invalid {label} for Python identifier: {value!r}")
+  return identifier
+
+
+def python_type(field: dict) -> str:
+  raw = str(field.get("type") or field.get("dataType") or "string").lower()
+  return {
+    "string": "str",
+    "str": "str",
+    "integer": "int",
+    "int": "int",
+    "number": "float",
+    "float": "float",
+    "boolean": "bool",
+    "bool": "bool",
+    "array": "list",
+    "list": "list",
+    "object": "dict",
+    "dict": "dict",
+  }.get(raw, "str")
+
+
+def _matches_endpoint(endpoint: dict, module: str, entity: str) -> bool:
+  module_tokens = {module.lower(), to_kebab(module), to_snake(module)}
+  entity_tokens = {entity.lower(), to_kebab(entity), to_snake(entity), to_pascal(entity).lower()}
+  explicit_module = endpoint.get("module") or endpoint.get("moduleName")
+  explicit_entity = endpoint.get("entity") or endpoint.get("entityName")
+  if explicit_module is not None:
+    if str(explicit_module).lower() not in module_tokens:
+      return False
+    if explicit_entity is not None:
+      return str(explicit_entity).lower() in entity_tokens
+  if explicit_entity is not None:
+    return str(explicit_entity).lower() in entity_tokens
+  values = [
+    str(endpoint.get(key) or "")
+    for key in ("id", "name", "path", "request", "requestName", "response", "responseName")
+  ]
+  entity_snake = to_snake(entity)
+  entity_kebab = to_kebab(entity)
+  for value in values:
+    normalized = to_snake(value)
+    words = set(re.split(r"[^a-z0-9]+", normalized))
+    if entity_snake in words:
+      return True
+    path_words = set(re.split(r"[^a-z0-9-]+", value.lower()))
+    if entity_kebab in path_words or f"{entity_kebab}s" in path_words:
+      return True
+    if entity_kebab.endswith("y") and f"{entity_kebab[:-1]}ies" in path_words:
+      return True
+  return False
+
+
+def _plural_route(entity_kebab: str) -> str:
+  if entity_kebab.endswith("y") and not entity_kebab.endswith(("ay", "ey", "iy", "oy", "uy")):
+    return f"{entity_kebab[:-1]}ies"
+  if entity_kebab.endswith(("s", "x", "z", "ch", "sh")):
+    return f"{entity_kebab}es"
+  return f"{entity_kebab}s"
+
+
+def _selector_key(value: object) -> str:
+  return to_snake(str(value))
+
+
+def _entity_sources(spec: dict) -> list[tuple[dict, dict]]:
+  codegen = spec.get("codegen") or {}
+  discovered: list[tuple[dict, dict]] = []
+  for module in spec.get("modules") or []:
+    if not isinstance(module, dict):
+      continue
+    for entity in module.get("entities") or []:
+      if isinstance(entity, dict):
+        discovered.append((module, entity))
+  if not discovered:
+    flat = [entity for entity in (spec.get("entities") or []) if isinstance(entity, dict)]
+    default_module = {"name": codegen.get("module") or "App"}
+    discovered = [(default_module, entity) for entity in flat]
+  if not discovered:
+    return [({"name": codegen.get("module") or "App"}, {"name": codegen.get("entity") or "Entity"})]
+
+  module_selector = codegen.get("module")
+  entity_selector = codegen.get("entity")
+  selected = discovered
+  if module_selector is not None:
+    wanted = _selector_key(module_selector)
+    selected = [(m, e) for m, e in selected if _selector_key(m.get("name") or "") == wanted]
+  if entity_selector is not None:
+    wanted = _selector_key(entity_selector)
+    selected = [(m, e) for m, e in selected if _selector_key(e.get("name") or "") == wanted]
+  if not selected:
+    available = ", ".join(
+      f"{module.get('name')}.{entity.get('name')}" for module, entity in discovered
+    )
+    requested = ".".join(
+      str(part) for part in (module_selector, entity_selector) if part is not None
+    )
+    raise ValueError(
+      f"codegen selector {requested!r} matches no module/entity; available: {available}"
+    )
+  return selected
+
+
+def resolve_codegen_context(
+  spec: dict,
+  module_data: dict | None = None,
+  entity_data: dict | None = None,
+  *,
+  multi_entity: bool = False,
+) -> dict:
+  codegen = spec.get("codegen") or {}
+  primary_module = module_data or {"name": codegen.get("module") or "App"}
+  primary_entity = entity_data or {"name": codegen.get("entity") or "Entity"}
+
+  module = primary_module.get("name") or codegen.get("module") or "App"
+  entity = primary_entity.get("name") or codegen.get("entity") or "Entity"
+  profile = codegen.get("profile") or "crud-standard"
+
+  module_kebab = to_kebab(module)
+  module_package = python_identifier(module, "module")
+  entity_kebab = to_kebab(entity)
+  entity_snake = python_identifier(entity, "entity")
+  entity_pascal = to_pascal(entity)
+  module_pascal = to_pascal(module)
+  all_endpoints = spec.get("api", {}).get("endpoints") or []
+  warnings: list[str] = []
+  if multi_entity:
+    endpoints = [e for e in all_endpoints if isinstance(e, dict) and _matches_endpoint(e, module, entity)]
+    if not endpoints:
+      warnings.append(
+        f"No unambiguous endpoints for {module}.{entity}; using generated CRUD defaults"
+      )
+      default_path = f"/{_plural_route(entity_kebab)}"
+      endpoints = [
+        {"action": "list", "method": "GET", "path": default_path},
+        {"action": "create", "method": "POST", "path": default_path},
+        {"action": "update", "method": "PATCH", "path": f"{default_path}/{{id}}"},
+        {"action": "delete", "method": "DELETE", "path": f"{default_path}/{{id}}"},
+      ]
+  else:
+    endpoints = [e for e in all_endpoints if isinstance(e, dict)]
+  entity_spec = {**spec, "api": {**(spec.get("api") or {}), "endpoints": endpoints}}
+  wire = resolve_wire(entity_spec)
+  search_ep = next(
+    (e for e in endpoints if e.get("action") in ("search", "list")),
+    endpoints[0] if endpoints else None,
+  )
+  route_prefix = "/"
+  if search_ep and search_ep.get("path"):
+    route_prefix = search_ep["path"]
+  elif endpoints and endpoints[0].get("path"):
+    route_prefix = endpoints[0]["path"]
+  route_prefix = re.sub(r"/\{[^/]+\}$", "", route_prefix).rstrip("/") or f"/{entity_kebab}s"
+
+  entity_fields = primary_entity.get("fields") or []
+  field_defs = []
+  for field in entity_fields:
+    raw_name = field.get("name") or field.get("key")
+    if not raw_name:
+      continue
+    name = python_identifier(str(raw_name), "field")
+    required = bool(field.get("required")) and name != "id"
+    field_defs.append({
+      "name": name,
+      "type": python_type(field),
+      "required": required,
+    })
+  if not field_defs:
+    field_defs = [
+      {"name": "id", "type": "int", "required": False},
+      {"name": "name", "type": "str", "required": False},
+    ]
+
+  return {
+    "module": module,
+    "entity": entity,
+    "profile": profile,
+    "module_kebab": module_kebab,
+    "module_package": module_package,
+    "module_pascal": module_pascal,
+    "entity_kebab": entity_kebab,
+    "entity_snake": entity_snake,
+    "entity_pascal": entity_pascal,
+    "wire": wire,
+    "route_prefix": route_prefix,
+    "field_names": [field["name"] for field in field_defs],
+    "field_defs": field_defs,
+    "endpoints": endpoints,
+    "warnings": warnings,
+    "spec": spec,
+  }
+
+
+def build_file_plan(spec: dict, *, force: bool = False) -> dict:
+  root = repo_root()
+  registry = load_registry(root)
+  files: list[dict] = []
+  contexts: list[dict] = []
+  sources = _entity_sources(spec)
+  multi_entity = len(sources) > 1
+
+  def add(ctx: dict, file_id: str, relative_path: str, template: str, layer: str) -> None:
+    files.append({
+      "id": file_id,
+      "relativePath": relative_path,
+      "template": template,
+      "layer": layer,
+      "entity": ctx["entity"],
+      "module": ctx["module"],
+      "ctx": ctx,
+    })
+
+  for module_data, entity_data in sources:
+    ctx = resolve_codegen_context(
+      spec, module_data, entity_data, multi_entity=multi_entity
+    )
+    contexts.append(ctx)
+    base = f"src/app/modules/{ctx['module_package']}/{ctx['entity_snake']}"
+    add(ctx, "router", f"{base}/router.py", "router.py.j2", "router")
+    add(ctx, "schemas_request", f"{base}/schemas/request.py", "schemas_request.py.j2", "schemas")
+    add(ctx, "schemas_response", f"{base}/schemas/response.py", "schemas_response.py.j2", "schemas")
+    add(ctx, "presenter", f"{base}/presenters/{ctx['entity_snake']}_presenter.py", "presenter.py.j2", "presenter")
+    if any(ctx["wire"].get(action) for action in ("search", "create", "update", "delete")):
+      add(ctx, "store", f"{base}/services/store.py", "store.py.j2", "service")
+    for action in ("search", "create", "update", "delete"):
+      if ctx["wire"].get(action):
+        add(ctx, f"service_{action}", f"{base}/services/{action}_service.py", f"service_{action}.py.j2", "service")
+    add(ctx, "test_router", f"tests/test_{ctx['entity_snake']}_router.py", "test_router.py.j2", "test")
+
+  paths = [file["relativePath"] for file in files]
+  duplicates = sorted({item for item in paths if paths.count(item) > 1})
+  for file in files:
+    if file["relativePath"] in duplicates and file["layer"] == "test":
+      ctx = file["ctx"]
+      file["relativePath"] = (
+        f"tests/test_{ctx['module_package']}_{ctx['entity_snake']}_router.py"
+      )
+  paths = [file["relativePath"] for file in files]
+  duplicates = sorted({item for item in paths if paths.count(item) > 1})
+  if duplicates:
+    raise ValueError(f"Duplicate generated output paths: {', '.join(duplicates)}")
+  return {
+    "ctx": contexts[0],
+    "contexts": contexts,
+    "files": files,
+    "registry": registry,
+    "force": force,
+    "root": root,
+    "warnings": [warning for ctx in contexts for warning in ctx["warnings"]],
+  }

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

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+
+def to_kebab(value: str) -> str:
+  s = re.sub(r"([a-z])([A-Z])", r"\1-\2", str(value))
+  return re.sub(r"[\s_]+", "-", s).lower()
+
+
+def to_snake(value: str) -> str:
+  s = re.sub(r"([a-z])([A-Z])", r"\1_\2", str(value))
+  return re.sub(r"[\s\-]+", "_", s).lower()
+
+
+def to_pascal(value: str) -> str:
+  parts = re.split(r"[-_\s]+", str(value))
+  return "".join(p[:1].upper() + p[1:] for p in parts if p)
+
+
+def read_spec_file(spec_path: str | Path) -> tuple[dict, Path, Path]:
+  abs_path = Path(spec_path).resolve()
+  raw = abs_path.read_text(encoding="utf-8")
+  spec = yaml.safe_load(raw)
+  if not isinstance(spec, dict):
+    raise ValueError(f"Invalid spec YAML: {abs_path}")
+  if "backend" in abs_path.parts:
+    feature_dir = abs_path.parent.parent
+  else:
+    feature_dir = abs_path.parent
+  return spec, abs_path, feature_dir

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

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def load_registry(repo_root: Path) -> dict:
+  path = repo_root / "registries" / "codegen.registry.json"
+  return json.loads(path.read_text(encoding="utf-8"))

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

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+
+def infer_wire_from_endpoints(endpoints: list[dict] | None) -> dict[str, bool]:
+  endpoints = endpoints or []
+  actions = {str(e.get("action", "")).lower() for e in endpoints}
+  paths = " ".join(str(e.get("path", "")) for e in endpoints).lower()
+
+  return {
+    "search": "search" in actions or "list" in actions or "search" in paths or "list" in paths,
+    "detail": "detail" in actions or "show" in actions,
+    "create": "create" in actions or any(str(e.get("method", "")).upper() == "POST" for e in endpoints),
+    "update": "update" in actions or "patch" in actions or any(
+      str(e.get("method", "")).upper() in ("PUT", "PATCH") for e in endpoints
+    ),
+    "delete": "delete" in actions or any(
+      str(e.get("method", "")).upper() == "DELETE" for e in endpoints
+    ),
+  }
+
+
+def resolve_wire(spec: dict) -> dict[str, bool]:
+  codegen = spec.get("codegen") or {}
+  wire = codegen.get("wire")
+  if isinstance(wire, dict):
+    base = infer_wire_from_endpoints(spec.get("api", {}).get("endpoints"))
+    return {**base, **{k: bool(v) for k, v in wire.items()}}
+  return infer_wire_from_endpoints(spec.get("api", {}).get("endpoints"))