recipes.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296
  1. """Static run-recipe detection for project verification.
  2. Ported nearly 1:1 from superagent-ai/grok-cli ``src/verify/recipes.ts`` (same
  3. detection order and command choices). Layer ownership: ``detect_project_facts``
  4. in :mod:`agent.coding_context` owns the cheap, byte-stable prompt-time facts —
  5. never push runtime detection into it. This module owns the deep runtime recipe
  6. (framework, bootstrap/build/test, start command, port, readiness path) that lets
  7. ``hermes verify`` boot the app; the CLI merges project-facts verify commands the
  8. recipe missed (``hermes_cli.verify_cmd._merge_project_facts_commands``).
  9. """
  10. from __future__ import annotations
  11. import json
  12. import re
  13. from dataclasses import dataclass, field
  14. from pathlib import Path
  15. from typing import Any
  16. def _as_strings(value: Any) -> list[str]:
  17. values = [value] if isinstance(value, str) else value if isinstance(value, list) else []
  18. return [v.strip() for v in values if isinstance(v, str) and v.strip()]
  19. @dataclass
  20. class Recipe:
  21. """A runnable verification recipe (grok-cli's ``VerifyRecipe``): ``name`` is the
  22. human label (``appLabel``), ``kind`` the detector id (``appKind``); command
  23. lists are shell strings executed in the project root."""
  24. name: str
  25. kind: str = "unknown"
  26. bootstrap: list[str] = field(default_factory=list)
  27. build: list[str] = field(default_factory=list)
  28. test: list[str] = field(default_factory=list)
  29. start: str | None = None
  30. port: int | None = None
  31. readiness_path: str = "/"
  32. evidence: list[str] = field(default_factory=list)
  33. def to_dict(self) -> dict[str, Any]:
  34. return {
  35. "name": self.name, "kind": self.kind, "bootstrap": list(self.bootstrap),
  36. "build": list(self.build), "test": list(self.test), "start": self.start,
  37. "port": self.port, "readinessPath": self.readiness_path, "evidence": list(self.evidence),
  38. }
  39. @classmethod
  40. def from_dict(cls, raw: Any) -> Recipe | None:
  41. """Tolerant loader mirroring grok's ``normalizeVerifyRecipe``; accepts
  42. both this module's field names and grok's camelCase aliases."""
  43. if not isinstance(raw, dict):
  44. return None
  45. name = raw.get("name") or raw.get("appLabel")
  46. if not isinstance(name, str) or not name.strip():
  47. return None
  48. kind = raw.get("kind") or raw.get("appKind")
  49. if not isinstance(kind, str) or not kind.strip():
  50. kind = "unknown"
  51. start = raw.get("start") or raw.get("startCommand")
  52. port_raw = raw.get("port") or raw.get("startPort")
  53. if isinstance(port_raw, str) and port_raw.strip().isdigit():
  54. port_raw = int(port_raw.strip())
  55. readiness = raw.get("readinessPath") or raw.get("readiness_path") or "/"
  56. return cls(
  57. name=name.strip(), kind=kind.strip(),
  58. start=start.strip() if isinstance(start, str) and start.strip() else None,
  59. port=port_raw if isinstance(port_raw, int) and 0 < port_raw < 65536 else None,
  60. readiness_path=readiness if isinstance(readiness, str) and readiness.startswith("/") else "/",
  61. bootstrap=_as_strings(raw.get("bootstrap") or raw.get("installCommands")),
  62. build=_as_strings(raw.get("build") or raw.get("buildCommands")),
  63. test=_as_strings(raw.get("test") or raw.get("testCommands")),
  64. evidence=_as_strings(raw.get("evidence")),
  65. )
  66. def _read_text(root: Path, name: str) -> str | None:
  67. try:
  68. return (root / name).read_text(encoding="utf-8-sig")
  69. except OSError:
  70. return None
  71. def _read_package_json(root: Path) -> dict[str, Any] | None:
  72. try:
  73. parsed = json.loads(_read_text(root, "package.json") or "")
  74. except ValueError: # includes JSONDecodeError; also the missing-file "" case
  75. return None
  76. return parsed if isinstance(parsed, dict) else None
  77. # Ordered: the first lockfile present wins (grok's detectPackageManager).
  78. _LOCKFILE_MANAGERS = (
  79. ("pnpm-lock.yaml", "pnpm"), ("bun.lock", "bun"), ("bun.lockb", "bun"), ("yarn.lock", "yarn"),
  80. ("package-lock.json", "npm"), ("uv.lock", "uv"), ("poetry.lock", "poetry"),
  81. ("Pipfile.lock", "pipenv"),
  82. )
  83. def _first_existing(root: Path, names: tuple[str, ...]) -> str | None:
  84. """First of ``names`` present under ``root``, else ``None``."""
  85. return next((n for n in names if (root / n).exists()), None)
  86. def detect_package_manager(root: Path) -> str | None:
  87. """Lockfile-based package-manager detection (grok's detectPackageManager)."""
  88. return next((m for f, m in _LOCKFILE_MANAGERS if (root / f).exists()), None)
  89. def _infer_port_from_command(command: str | None) -> int | None:
  90. """Port inference from a start command (grok's inferPortFromCommand)."""
  91. if not command:
  92. return None
  93. match = re.search(r"(?:--port|-p)\s+(\d{2,5})", command) or re.search(r"\bPORT=(\d{2,5})\b", command)
  94. return int(match.group(1)) if match else None
  95. def _dedupe(values: list[str | None]) -> list[str]:
  96. """Strip, drop empties, keep first occurrence order."""
  97. return list(dict.fromkeys(v.strip() for v in values if v and v.strip()))
  98. _SCRIPT_RUNNERS = {"pnpm": "pnpm {}", "bun": "bun run {}", "yarn": "yarn {}"}
  99. _NODE_INSTALL = {"pnpm": "pnpm install", "bun": "bun install", "yarn": "yarn install"}
  100. # Ordered: the first dependency present decides the framework (kind, label, default port).
  101. _NODE_FRAMEWORKS = (
  102. (("next",), "nextjs", "Next.js", 3000), (("@sveltejs/kit",), "sveltekit", "SvelteKit", 5173),
  103. (("astro",), "astro", "Astro", 4321),
  104. (("@remix-run/dev", "@remix-run/react"), "remix", "Remix", 3000),
  105. (("react-scripts",), "cra", "Create React App", 3000), (("vite",), "vite", "Vite", 5173),
  106. )
  107. def _script_runner(package_manager: str | None, entry: str) -> str:
  108. return _SCRIPT_RUNNERS.get(package_manager or "", "npm run {}").format(entry)
  109. def _detect_node_recipe(root: Path, pkg: dict[str, Any]) -> Recipe:
  110. raw_scripts = pkg.get("scripts")
  111. scripts: dict[str, str] = raw_scripts if isinstance(raw_scripts, dict) else {}
  112. deps: dict[str, Any] = {}
  113. for section in (pkg.get("dependencies"), pkg.get("devDependencies")):
  114. if isinstance(section, dict):
  115. deps.update(section)
  116. package_manager = detect_package_manager(root)
  117. kind, label, default_port = next(
  118. ((k, lbl, p) for names, k, lbl, p in _NODE_FRAMEWORKS if any(n in deps for n in names)),
  119. ("node", "Node.js app", None),
  120. )
  121. def runners(*names: str) -> list[str]:
  122. return _dedupe([_script_runner(package_manager, s) for s in names if scripts.get(s)])
  123. start_script = next((s for s in ("dev", "start") if scripts.get(s)), None)
  124. return Recipe(
  125. name=label, kind=kind, start=runners(start_script)[0] if start_script else None,
  126. port=(_infer_port_from_command(scripts[start_script]) or default_port) if start_script else None,
  127. bootstrap=[_NODE_INSTALL.get(package_manager or "", "npm install")],
  128. build=runners("build", "typecheck"), test=runners("test", "check", "lint"),
  129. evidence=_dedupe([
  130. "Detected package.json",
  131. f"Package manager: {package_manager}" if package_manager else None,
  132. f"Scripts: {', '.join(scripts) or '(none)'}",
  133. ]),
  134. )
  135. _PYTHON_INSTALL = {"uv": "uv sync", "poetry": "poetry install", "pipenv": "pipenv install"}
  136. def _detect_python_recipe(root: Path) -> Recipe | None:
  137. pyproject = _read_text(root, "pyproject.toml")
  138. requirements = _read_text(root, "requirements.txt")
  139. manage_py = (root / "manage.py").exists()
  140. if not (pyproject or requirements or manage_py or (root / "setup.py").exists()):
  141. return None
  142. lower = f"{pyproject or ''}\n{requirements or ''}".lower()
  143. install = _PYTHON_INSTALL.get(detect_package_manager(root) or "") or (
  144. "pip install -e ." if pyproject and not requirements else "pip install -r requirements.txt"
  145. )
  146. pytest_or_empty = ["pytest"] if (root / "tests").exists() else []
  147. # Precedence: Django, then FastAPI/uvicorn, then Flask, then generic.
  148. if manage_py or "django" in lower:
  149. return Recipe(
  150. name="Django app", kind="django", bootstrap=[install], test=["python manage.py test"],
  151. start="python manage.py runserver 0.0.0.0:8000", port=8000,
  152. evidence=["Detected manage.py" if manage_py else "Detected Django dependency"]
  153. + (["Detected pyproject.toml"] if pyproject else []),
  154. )
  155. if "fastapi" in lower or "uvicorn" in lower:
  156. app_module = (_first_existing(root, ("main.py", "app.py")) or "main.py").removesuffix(".py") + ":app"
  157. return Recipe(
  158. name="FastAPI app", kind="fastapi", bootstrap=[install], test=pytest_or_empty,
  159. start=f"uvicorn {app_module} --host 0.0.0.0 --port 8000", port=8000,
  160. evidence=["Detected Python project", "Detected FastAPI/Uvicorn dependency"],
  161. )
  162. if "flask" in lower:
  163. app_module = _first_existing(root, ("app.py", "main.py")) or "app.py"
  164. return Recipe(
  165. name="Flask app", kind="flask", bootstrap=[install], test=pytest_or_empty,
  166. start=f"flask --app {app_module} run --host 0.0.0.0 --port 5000", port=5000,
  167. evidence=["Detected Python project", "Detected Flask dependency"],
  168. )
  169. return Recipe(
  170. name="Python project", kind="python", bootstrap=[install],
  171. test=pytest_or_empty or ["python -m unittest discover"],
  172. evidence=["Detected Python project"],
  173. )
  174. # Single-manifest toolchains: manifest -> (label, kind, build, test, start command, entry file).
  175. _SIMPLE_TOOLCHAINS = (
  176. ("go.mod", "Go project", "go", "go build ./...", "go test ./...", "go run .", Path("main.go")),
  177. ("Cargo.toml", "Rust project", "rust", "cargo build", "cargo test", "cargo run", Path("src") / "main.rs"),
  178. )
  179. def _detect_simple_recipe(root: Path) -> Recipe | None:
  180. for manifest, label, kind, build, test, start, entry in _SIMPLE_TOOLCHAINS:
  181. if (root / manifest).exists():
  182. return Recipe(
  183. name=label, kind=kind, build=[build], test=[test],
  184. start=start if (root / entry).exists() else None, evidence=[f"Detected {manifest}"],
  185. )
  186. return None
  187. def _detect_java_recipe(root: Path) -> Recipe | None:
  188. if (root / "pom.xml").exists():
  189. return Recipe(name="Maven project", kind="maven", build=["mvn package"], test=["mvn test"], evidence=["Detected pom.xml"])
  190. if _first_existing(root, ("build.gradle", "build.gradle.kts")):
  191. gradle = "./gradlew" if (root / "gradlew").exists() else "gradle"
  192. return Recipe(
  193. name="Gradle project", kind="gradle", build=[f"{gradle} build"], test=[f"{gradle} test"],
  194. evidence=["Detected Gradle build file"],
  195. )
  196. return None
  197. _MAKE_TARGET_RE = re.compile(r"^([A-Za-z0-9_.-]+):(?:\s|$)")
  198. # Makefile phase -> candidate targets, first present wins.
  199. _MAKE_PHASE_TARGETS = {
  200. "bootstrap": ("install", "setup", "bootstrap"),
  201. "build": ("build", "compile"),
  202. "test": ("test", "check"),
  203. "start": ("run", "start", "serve", "dev"),
  204. }
  205. def _detect_make_recipe(root: Path) -> Recipe | None:
  206. makefile = _read_text(root, "Makefile")
  207. if makefile is None:
  208. return None
  209. targets = [m.group(1) for m in map(_MAKE_TARGET_RE.match, makefile.splitlines()) if m]
  210. picked = {
  211. phase: [f"make {n}" for n in names if n in targets][:1]
  212. for phase, names in _MAKE_PHASE_TARGETS.items()
  213. }
  214. return Recipe(
  215. name="Makefile-driven project", kind="make", start=(picked["start"] or [None])[0],
  216. bootstrap=picked["bootstrap"], build=picked["build"], test=picked["test"],
  217. evidence=["Detected Makefile", f"Targets: {', '.join(targets) or '(none)'}"],
  218. )
  219. _COMPOSE_FILES = ("docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml")
  220. def _detect_compose_recipe(root: Path) -> Recipe | None:
  221. compose_file = _first_existing(root, _COMPOSE_FILES)
  222. return None if compose_file is None else Recipe(
  223. name="docker-compose project", kind="compose", build=["docker compose build"],
  224. start="docker compose up", evidence=[f"Detected {compose_file}"],
  225. )
  226. def detect_recipe(root: Path) -> Recipe | None:
  227. """Detect a recipe for ``root`` (grok-cli's ``inferFallbackRecipe`` order): package.json
  228. wins, then Python, Go, Rust, Java, then Makefile / docker-compose; ``None`` if nothing matches."""
  229. root = Path(root)
  230. pkg = _read_package_json(root)
  231. if pkg is not None:
  232. return _detect_node_recipe(root, pkg)
  233. return (
  234. _detect_python_recipe(root)
  235. or _detect_simple_recipe(root)
  236. or _detect_java_recipe(root)
  237. or _detect_make_recipe(root)
  238. or _detect_compose_recipe(root)
  239. )