Added some stuff

Author: Endogen

README.md

@@ -159,6 +159,13 @@ If `WEB2API_RECIPE_CATALOG_SOURCE` is unset, Web2API uses the official remote re
 `https://github.com/Endogen/web2api-recipes.git`.
 `recipes update` works only for recipes tracked in the manifest.
 
+Catalog entries can include optional setup hints:
+- `requires_env`: list of required environment variable names (e.g. `["BIRD_AUTH_TOKEN", "BIRD_CT0"]`)
+- `docs_url` (or `readme_url`): URL shown in CLI/UI as setup documentation
+
+If `docs_url` is omitted and the recipe source resolves to GitHub, Web2API automatically
+links to `<repo>/blob/<ref-or-HEAD>/<subdir>/README.md`.
+
 Recipes installed from untrusted sources (for example git URLs) are blocked from executing
 install/healthcheck commands unless `--allow-untrusted` is passed.
 

tests/integration/test_api.py

@@ -371,7 +371,16 @@ async def test_recipe_management_api_lifecycle(
 ) -> None:
     recipes_dir = tmp_path / "active-recipes"
     catalog_root = tmp_path / "catalog-src"
-    _write_recipe(catalog_root / "recipes", "gamma")
+    missing_env = "WEB2API_TEST_GAMMA_TOKEN_UNLIKELY"
+    monkeypatch.delenv(missing_env, raising=False)
+    _write_recipe(
+        catalog_root / "recipes",
+        "gamma",
+        plugin={
+            "version": "1.0.0",
+            "requires_env": [missing_env],
+        },
+    )
 
     catalog_file = catalog_root / "catalog.yaml"
     catalog_file.parent.mkdir(parents=True, exist_ok=True)
@@ -383,6 +392,8 @@ async def test_recipe_management_api_lifecycle(
                         "source": "./recipes/gamma",
                         "trusted": True,
                         "description": "Gamma recipe",
+                        "docs_url": "https://example.com/gamma/readme",
+                        "requires_env": [missing_env],
                     }
                 }
             }
@@ -406,6 +417,9 @@ async def test_recipe_management_api_lifecycle(
             assert payload_before["catalog_error"] is None
             assert payload_before["catalog"][0]["name"] == "gamma"
             assert payload_before["catalog"][0]["installed"] is False
+            assert payload_before["catalog"][0]["docs_url"] == "https://example.com/gamma/readme"
+            assert payload_before["catalog"][0]["requires_env"] == [missing_env]
+            assert payload_before["catalog"][0]["plugin"] is None
 
             install_resp = await client.post("/api/recipes/manage/install/gamma")
             assert install_resp.status_code == 200
@@ -426,6 +440,10 @@ async def test_recipe_management_api_lifecycle(
             )
             assert gamma_catalog["installed"] is True
             assert gamma_catalog["enabled"] is False
+            assert gamma_catalog["docs_url"] == "https://example.com/gamma/readme"
+            assert gamma_catalog["requires_env"] == [missing_env]
+            assert gamma_catalog["plugin"] is not None
+            assert gamma_catalog["plugin"]["status"]["checks"]["env"]["missing"] == [missing_env]
 
             enable_resp = await client.post("/api/recipes/manage/enable/gamma")
             assert enable_resp.status_code == 200

tests/unit/test_cli.py

@@ -312,6 +312,8 @@ def test_recipes_catalog_add_installs_from_catalog(
                 source_subdir=None,
                 description=None,
                 trusted=True,
+                docs_url="https://example.com/demo/readme",
+                requires_env=["DEMO_TOKEN"],
             )
         },
     )
@@ -333,3 +335,38 @@ def _fake_add_recipe_from_source(**kwargs):
 
     assert result.exit_code == 0
     assert called["record_source_type"] == "catalog"
+
+
+def test_recipes_catalog_list_prints_docs_and_requires_env(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.setattr(
+        "web2api.cli.resolve_catalog_recipes",
+        lambda **kwargs: {
+            "x": CatalogRecipeSpec(
+                name="x",
+                slug="x",
+                source="https://github.com/acme/web2api-recipes.git",
+                source_ref="main",
+                source_subdir="recipes/x",
+                description="X recipe",
+                trusted=True,
+                docs_url="https://github.com/acme/web2api-recipes/blob/main/recipes/x/README.md",
+                requires_env=["BIRD_AUTH_TOKEN", "BIRD_CT0"],
+            )
+        },
+    )
+
+    catalog_file = tmp_path / "catalog.yaml"
+    catalog_file.write_text("recipes: {}\n", encoding="utf-8")
+
+    runner = CliRunner()
+    result = runner.invoke(
+        cli.app,
+        ["recipes", "catalog", "list", "--catalog-source", str(catalog_file)],
+    )
+
+    assert result.exit_code == 0
+    assert "requires env: BIRD_AUTH_TOKEN, BIRD_CT0" in result.output
+    assert "docs: https://github.com/acme/web2api-recipes/blob/main/recipes/x/README.md" in result.output

tests/unit/test_recipe_manager.py

@@ -186,6 +186,8 @@ def test_load_catalog_reads_recipe_entries(tmp_path: Path) -> None:
                         "source": "./demo",
                         "trusted": True,
                         "description": "demo plugin",
+                        "docs_url": "https://example.com/demo/readme",
+                        "requires_env": ["DEMO_TOKEN"],
                     }
                 }
             }
@@ -197,6 +199,8 @@ def test_load_catalog_reads_recipe_entries(tmp_path: Path) -> None:
     assert "demo" in catalog
     assert catalog["demo"]["source"] == "./demo"
     assert catalog["demo"]["trusted"] is True
+    assert catalog["demo"]["docs_url"] == "https://example.com/demo/readme"
+    assert catalog["demo"]["requires_env"] == ["DEMO_TOKEN"]
 
 
 def test_default_paths_exist(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -219,6 +223,8 @@ def test_resolve_catalog_recipes_from_local_file(tmp_path: Path) -> None:
                     "demo": {
                         "source": "./demo-recipe",
                         "trusted": True,
+                        "docs_url": "https://example.com/demo/setup",
+                        "requires_env": ["DEMO_TOKEN"],
                     }
                 }
             }
@@ -231,6 +237,30 @@ def test_resolve_catalog_recipes_from_local_file(tmp_path: Path) -> None:
     assert specs["demo"].slug == "demo"
     assert specs["demo"].source == str(source_recipe.resolve())
     assert specs["demo"].trusted is True
+    assert specs["demo"].docs_url == "https://example.com/demo/setup"
+    assert specs["demo"].requires_env == ["DEMO_TOKEN"]
+
+
+def test_resolve_catalog_recipes_derives_github_readme_url(tmp_path: Path) -> None:
+    catalog_file = tmp_path / "catalog.yaml"
+    catalog_file.write_text(
+        yaml.safe_dump(
+            {
+                "recipes": {
+                    "x": {
+                        "source": "https://github.com/acme/web2api-recipes.git",
+                        "ref": "main",
+                        "subdir": "recipes/x",
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    specs = resolve_catalog_recipes(catalog_source=str(catalog_file))
+    assert specs["x"].docs_url == "https://github.com/acme/web2api-recipes/blob/main/recipes/x/README.md"
+    assert specs["x"].requires_env == []
 
 
 def test_resolve_catalog_recipes_sparse_checkout_for_remote_catalog(
@@ -271,6 +301,8 @@ def _fake_run(command, check: bool, text: bool, **kwargs):  # noqa: ANN001
     assert "demo" in specs
     assert specs["demo"].source == "https://example.com/catalog.git"
     assert specs["demo"].source_subdir == "recipes/demo"
+    assert specs["demo"].docs_url is None
+    assert specs["demo"].requires_env == []
 
     assert any(
         command[:9]

web2api/cli.py

@@ -694,6 +694,8 @@ def recipes_catalog_list(
                 "subdir": spec.source_subdir,
                 "description": spec.description,
                 "trusted": spec.trusted,
+                "docs_url": spec.docs_url,
+                "requires_env": spec.requires_env,
             }
             for name, spec in sorted(catalog.items())
         }
@@ -717,6 +719,10 @@ def recipes_catalog_list(
         )
         if spec.description:
             typer.echo(f"  {spec.description}")
+        if spec.requires_env:
+            typer.echo(f"  requires env: {', '.join(spec.requires_env)}")
+        if spec.docs_url:
+            typer.echo(f"  docs: {spec.docs_url}")
 
 
 @catalog_app.command("add")

web2api/recipe_admin_api.py

@@ -87,9 +87,12 @@ async def recipes_manage(request: Request) -> JSONResponse:
                     "source": spec.source,
                     "source_ref": spec.source_ref,
                     "source_subdir": spec.source_subdir,
+                    "docs_url": spec.docs_url,
+                    "requires_env": spec.requires_env,
                     "installed": installed is not None and bool(installed.get("has_recipe")),
                     "enabled": installed.get("enabled") if installed is not None else None,
                     "managed": installed.get("managed") if installed is not None else False,
+                    "plugin": installed.get("plugin") if installed is not None else None,
                     "origin": (
                         str(installed.get("origin", "unmanaged"))
                         if installed is not None and bool(installed.get("has_recipe"))