refactor(cron): rebrand Cron Recipes -> Automation Blueprints

Product rename across every surface: module/file names (blueprint_catalog,
tools/blueprints, blueprint_cmd), slash command /cron-recipe -> /blueprint
(alias /bp), dashboard API /api/cron/blueprints, desktop deep-link
hermes://blueprint/<key>, docs catalog page + extract script, and the
skill frontmatter block metadata.hermes.blueprint. No behavior change.
This commit is contained in:
Teknium 2026-06-11 10:23:27 -07:00
parent 3c489fda81
commit cb29e8a82e
29 changed files with 627 additions and 627 deletions

View file

@ -1,7 +1,7 @@
"""Tests for Cron Recipes — the parameterized automation template system.
"""Tests for Automation Blueprints — the parameterized automation template system.
Covers the core catalog/slot schema/renderers/fill (cron/recipe_catalog.py),
the shared /cron-recipe command handler (hermes_cli/cron_recipe_cmd.py), and
Covers the core catalog/slot schema/renderers/fill (cron/blueprint_catalog.py),
the shared /blueprint command handler (hermes_cli/blueprint_cmd.py), and
the docs generator. Uses an isolated HERMES_HOME for anything that touches the
cron job store.
"""
@ -13,16 +13,16 @@ from unittest.mock import patch
import pytest
from cron.recipe_catalog import (
from cron.blueprint_catalog import (
CATALOG,
RecipeFillError,
RecipeSlot,
fill_recipe,
get_recipe,
recipe_catalog_entry,
recipe_deeplink,
recipe_form_schema,
recipe_slash_command,
BlueprintFillError,
BlueprintSlot,
fill_blueprint,
get_blueprint,
blueprint_catalog_entry,
blueprint_deeplink,
blueprint_form_schema,
blueprint_slash_command,
)
@ -30,7 +30,7 @@ class TestCatalog:
def test_catalog_nonempty_and_keyed(self):
assert len(CATALOG) >= 1
for r in CATALOG:
assert get_recipe(r.key) is r
assert get_blueprint(r.key) is r
def test_every_slot_has_known_type(self):
for r in CATALOG:
@ -39,60 +39,60 @@ class TestCatalog:
def test_bad_slot_type_rejected(self):
with pytest.raises(ValueError):
RecipeSlot(name="x", type="bogus", label="X")
BlueprintSlot(name="x", type="bogus", label="X")
class TestScheduleResolution:
def test_time_to_cron(self):
spec = fill_recipe(get_recipe("morning-brief"), {"time": "08:30"})
spec = fill_blueprint(get_blueprint("morning-brief"), {"time": "08:30"})
assert spec["schedule"] == "30 8 * * *"
def test_interval_schedule(self):
spec = fill_recipe(
get_recipe("important-mail"),
spec = fill_blueprint(
get_blueprint("important-mail"),
{"interval_min": "15", "criteria": "x", "deliver": "origin"},
)
assert spec["schedule"] == "*/15 * * * *"
def test_day_to_dow(self):
spec = fill_recipe(
get_recipe("weekly-review"),
spec = fill_blueprint(
get_blueprint("weekly-review"),
{"time": "18:00", "day": "sunday", "deliver": "origin"},
)
assert spec["schedule"] == "0 18 * * 0"
def test_weekday_preset_to_dow(self):
spec = fill_recipe(
get_recipe("custom-reminder"),
spec = fill_blueprint(
get_blueprint("custom-reminder"),
{"what": "stretch", "time": "14:00", "recurrence": "weekdays", "deliver": "origin"},
)
assert spec["schedule"] == "0 14 * * 1-5"
def test_defaults_fill_when_omitted(self):
spec = fill_recipe(get_recipe("morning-brief"), {})
spec = fill_blueprint(get_blueprint("morning-brief"), {})
assert spec["schedule"] == "0 8 * * *"
class TestValidation:
def test_invalid_time_rejected(self):
with pytest.raises(RecipeFillError, match="invalid time"):
fill_recipe(get_recipe("morning-brief"), {"time": "25:99"})
with pytest.raises(BlueprintFillError, match="invalid time"):
fill_blueprint(get_blueprint("morning-brief"), {"time": "25:99"})
def test_bad_enum_rejected_and_names_slot(self):
with pytest.raises(RecipeFillError, match="not allowed"):
fill_recipe(get_recipe("news-digest"), {"count": "42"})
with pytest.raises(BlueprintFillError, match="not allowed"):
fill_blueprint(get_blueprint("news-digest"), {"count": "42"})
def test_deliver_slot_accepts_any_platform(self):
# deliver is a non-strict enum: its options are suggestions, the real
# set of valid platforms depends on the user's configured gateways and
# is validated downstream by the cron scheduler.
spec = fill_recipe(get_recipe("morning-brief"), {"time": "08:00", "deliver": "slack"})
spec = fill_blueprint(get_blueprint("morning-brief"), {"time": "08:00", "deliver": "slack"})
assert spec["deliver"] == "slack"
def test_unknown_slot_name_rejected(self):
# A typo'd slot must NOT silently create a job with the default value.
with pytest.raises(RecipeFillError, match="unknown slot"):
fill_recipe(get_recipe("morning-brief"), {"tiem": "07:15"})
with pytest.raises(BlueprintFillError, match="unknown slot"):
fill_blueprint(get_blueprint("morning-brief"), {"tiem": "07:15"})
def test_hydration_hourly_step_actually_fires_at_chosen_cadence(self):
# Regression: a minute-field step (*/90) silently wraps to hourly.
@ -100,7 +100,7 @@ class TestValidation:
croniter = pytest.importorskip("croniter").croniter
from datetime import datetime
spec = fill_recipe(get_recipe("hydration-move"), {"interval_hours": "2"})
spec = fill_blueprint(get_blueprint("hydration-move"), {"interval_hours": "2"})
it = croniter(spec["schedule"], datetime(2026, 6, 10, 8, 0))
first_three = [it.get_next(datetime) for _ in range(3)]
gaps = {
@ -110,45 +110,45 @@ class TestValidation:
assert gaps == {7200.0}, f"expected 2h gaps, got {spec['schedule']} -> {first_three}"
def test_text_slot_renders_into_prompt(self):
spec = fill_recipe(
get_recipe("important-mail"),
spec = fill_blueprint(
get_blueprint("important-mail"),
{"interval_min": "30", "criteria": "from my CEO", "deliver": "origin"},
)
assert "from my CEO" in spec["prompt"]
def test_origin_threads_through(self):
spec = fill_recipe(
get_recipe("morning-brief"), {"time": "08:00"}, origin={"platform": "telegram", "chat_id": "9"}
spec = fill_blueprint(
get_blueprint("morning-brief"), {"time": "08:00"}, origin={"platform": "telegram", "chat_id": "9"}
)
assert spec["origin"] == {"platform": "telegram", "chat_id": "9"}
class TestRenderers:
def test_form_schema_fields(self):
schema = recipe_form_schema(get_recipe("morning-brief"))
schema = blueprint_form_schema(get_blueprint("morning-brief"))
names = [f["name"] for f in schema["fields"]]
assert names == ["time", "deliver"]
assert schema["key"] == "morning-brief"
def test_slash_command_defaults(self):
cmd = recipe_slash_command(get_recipe("morning-brief"))
assert cmd.startswith("/cron-recipe morning-brief")
cmd = blueprint_slash_command(get_blueprint("morning-brief"))
assert cmd.startswith("/blueprint morning-brief")
assert "time=08:00" in cmd
def test_slash_command_quotes_freetext(self):
cmd = recipe_slash_command(
get_recipe("custom-reminder"), {"what": "drink water", "time": "10:00"}
cmd = blueprint_slash_command(
get_blueprint("custom-reminder"), {"what": "drink water", "time": "10:00"}
)
assert '"drink water"' in cmd
def test_deeplink_shape(self):
url = recipe_deeplink(get_recipe("morning-brief"), {"time": "07:15"})
assert url.startswith("hermes://cron-recipe/morning-brief?")
url = blueprint_deeplink(get_blueprint("morning-brief"), {"time": "07:15"})
assert url.startswith("hermes://blueprint/morning-brief?")
assert "time=07" in url
def test_catalog_entry_has_all_surfaces(self):
entry = recipe_catalog_entry(get_recipe("morning-brief"))
assert entry["command"].startswith("/cron-recipe")
entry = blueprint_catalog_entry(get_blueprint("morning-brief"))
assert entry["command"].startswith("/blueprint")
assert entry["appUrl"].startswith("hermes://")
assert entry["scheduleHuman"]
assert "fields" in entry
@ -168,18 +168,18 @@ def isolated_home(tmp_path, monkeypatch):
class TestCommandHandler:
def test_bare_lists_catalog(self, isolated_home):
from hermes_cli.cron_recipe_cmd import handle_cron_recipe_command
from hermes_cli.blueprint_cmd import handle_blueprint_command
res = handle_cron_recipe_command("")
assert "morning-brief" in res.text and "Cron Recipes" in res.text
res = handle_blueprint_command("")
assert "morning-brief" in res.text and "Automation Blueprints" in res.text
assert res.agent_seed is None
def test_name_seeds_agent(self, isolated_home):
from hermes_cli.cron_recipe_cmd import handle_cron_recipe_command
from hermes_cli.blueprint_cmd import handle_blueprint_command
# `/cron-recipe <name>` (no inline slots) now seeds the agent to ask
# `/blueprint <name>` (no inline slots) now seeds the agent to ask
# the user for each value conversationally instead of dumping fields.
res = handle_cron_recipe_command("morning-brief")
res = handle_blueprint_command("morning-brief")
assert res.agent_seed is not None
assert "morning-brief" in res.agent_seed
assert "cronjob tool" in res.agent_seed
@ -187,22 +187,22 @@ class TestCommandHandler:
assert "* * *" in res.agent_seed
def test_name_match_is_forgiving(self, isolated_home):
from hermes_cli.cron_recipe_cmd import handle_cron_recipe_command, match_recipe
from hermes_cli.blueprint_cmd import handle_blueprint_command, match_blueprint
# prefix match
r, cands = match_recipe("morning")
r, cands = match_blueprint("morning")
assert r is not None and r.key == "morning-brief"
# fuzzy / typo
r2, _ = match_recipe("mornning-brief")
r2, _ = match_blueprint("mornning-brief")
assert r2 is not None and r2.key == "morning-brief"
# a forgiving name still seeds the agent
res = handle_cron_recipe_command("morning")
res = handle_blueprint_command("morning")
assert res.agent_seed is not None
def test_fill_creates_job(self, isolated_home):
from hermes_cli.cron_recipe_cmd import handle_cron_recipe_command
from hermes_cli.blueprint_cmd import handle_blueprint_command
res = handle_cron_recipe_command("morning-brief time=07:30 deliver=telegram")
res = handle_blueprint_command("morning-brief time=07:30 deliver=telegram")
assert "Scheduled" in res.text
assert res.agent_seed is None
jobs = isolated_home.load_jobs()
@ -210,17 +210,17 @@ class TestCommandHandler:
assert (jobs[0].get("schedule_display") or jobs[0].get("schedule")) == "30 7 * * *"
assert jobs[0].get("deliver") == "telegram"
def test_unknown_recipe(self, isolated_home):
from hermes_cli.cron_recipe_cmd import handle_cron_recipe_command
def test_unknown_blueprint(self, isolated_home):
from hermes_cli.blueprint_cmd import handle_blueprint_command
res = handle_cron_recipe_command("zzz-nope-nothing")
assert "No cron recipe" in res.text
res = handle_blueprint_command("zzz-nope-nothing")
assert "No automation blueprint" in res.text
assert res.agent_seed is None
def test_bad_value_names_slot(self, isolated_home):
from hermes_cli.cron_recipe_cmd import handle_cron_recipe_command
from hermes_cli.blueprint_cmd import handle_blueprint_command
res = handle_cron_recipe_command("morning-brief time=99:99")
res = handle_blueprint_command("morning-brief time=99:99")
assert "Can't set up" in res.text and "time" in res.text
assert res.agent_seed is None
@ -232,9 +232,9 @@ class TestDocsGenerator:
script = (
Path(__file__).resolve().parents[2]
/ "website" / "scripts" / "extract-cron-recipes.py"
/ "website" / "scripts" / "extract-automation-blueprints.py"
)
spec = importlib.util.spec_from_file_location("extract_cron_recipes", script)
spec = importlib.util.spec_from_file_location("extract_cron_blueprints", script)
assert spec is not None and spec.loader is not None
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)

View file

@ -1,7 +1,7 @@
"""Tests for the Suggested Cron Jobs feature.
Covers the store (add/dedup/cap/accept/dismiss/latch), catalog seeding, the
recipe->suggestion bridge, and the shared command handler. Uses an isolated
blueprint->suggestion bridge, and the shared command handler. Uses an isolated
HERMES_HOME so the real suggestions.json is never touched.
"""
@ -136,23 +136,23 @@ class TestCatalog:
assert Path(classify_items_script_path()).name == "classify_items.py"
class TestRecipeBridge:
def test_recipe_registers_suggestion(self, store):
from tools.recipes import RecipeSpec, register_recipe_suggestion
class TestBlueprintBridge:
def test_blueprint_registers_suggestion(self, store):
from tools.blueprints import BlueprintSpec, register_blueprint_suggestion
spec = RecipeSpec(skill_name="morning-brief", schedule="0 8 * * *", deliver="telegram")
spec = BlueprintSpec(skill_name="morning-brief", schedule="0 8 * * *", deliver="telegram")
with patch("cron.suggestions.add_suggestion", store.add_suggestion):
rec = register_recipe_suggestion(spec)
rec = register_blueprint_suggestion(spec)
assert rec is not None
assert rec["source"] == "recipe"
assert rec["source"] == "blueprint"
assert rec["job_spec"]["skills"] == ["morning-brief"]
assert rec["job_spec"]["schedule"] == "0 8 * * *"
def test_recipe_to_job_spec_matches_create_recipe_job(self):
from tools.recipes import RecipeSpec, recipe_to_job_spec
def test_blueprint_to_job_spec_matches_create_blueprint_job(self):
from tools.blueprints import BlueprintSpec, blueprint_to_job_spec
spec = RecipeSpec(skill_name="x", schedule="every 2h", deliver="origin", prompt="p")
js = recipe_to_job_spec(spec)
spec = BlueprintSpec(skill_name="x", schedule="every 2h", deliver="origin", prompt="p")
js = blueprint_to_job_spec(spec)
assert js["skills"] == ["x"]
assert js["schedule"] == "every 2h"
assert js["prompt"] == "p"

View file

@ -2360,39 +2360,39 @@ class TestNewEndpoints:
resp = self.client.get("/api/cron/jobs/nonexistent-id")
assert resp.status_code == 404
# --- Cron Recipes ---
# --- Automation Blueprints ---
def test_cron_recipes_list(self):
resp = self.client.get("/api/cron/recipes")
def test_cron_blueprints_list(self):
resp = self.client.get("/api/cron/blueprints")
assert resp.status_code == 200
recipes = resp.json()["recipes"]
assert len(recipes) >= 1
first = recipes[0]
blueprints = resp.json()["blueprints"]
assert len(blueprints) >= 1
first = blueprints[0]
assert "fields" in first
assert first["command"].startswith("/cron-recipe")
assert first["command"].startswith("/blueprint")
assert first["appUrl"].startswith("hermes://")
def test_cron_recipe_instantiate_creates_job(self):
def test_blueprint_instantiate_creates_job(self):
resp = self.client.post(
"/api/cron/recipes/instantiate",
json={"recipe": "morning-brief", "values": {"time": "07:30", "deliver": "local"}},
"/api/cron/blueprints/instantiate",
json={"blueprint": "morning-brief", "values": {"time": "07:30", "deliver": "local"}},
)
assert resp.status_code == 200
job = resp.json()
assert (job.get("schedule_display") or "").strip() == "30 7 * * *" or \
(job.get("schedule", {}) or {}).get("expr") == "30 7 * * *"
def test_cron_recipe_instantiate_unknown_404(self):
def test_blueprint_instantiate_unknown_404(self):
resp = self.client.post(
"/api/cron/recipes/instantiate",
json={"recipe": "does-not-exist", "values": {}},
"/api/cron/blueprints/instantiate",
json={"blueprint": "does-not-exist", "values": {}},
)
assert resp.status_code == 404
def test_cron_recipe_instantiate_bad_value_422(self):
def test_blueprint_instantiate_bad_value_422(self):
resp = self.client.post(
"/api/cron/recipes/instantiate",
json={"recipe": "morning-brief", "values": {"time": "99:99"}},
"/api/cron/blueprints/instantiate",
json={"blueprint": "morning-brief", "values": {"time": "99:99"}},
)
assert resp.status_code == 422

View file

@ -1,6 +1,6 @@
"""Tests for the recipes layer (skill frontmatter <-> cron automation bridge).
"""Tests for the blueprints layer (skill frontmatter <-> cron automation bridge).
A recipe is a skill with a metadata.hermes.recipe block. These verify parsing,
A blueprint is a skill with a metadata.hermes.blueprint block. These verify parsing,
the create-job bridge, and the export round-trip without touching the real
cron store.
"""
@ -11,24 +11,24 @@ from unittest.mock import patch
import pytest
from tools.recipes import (
RecipeError,
RecipeSpec,
create_recipe_job,
export_recipe,
parse_recipe,
recipe_spec_for_installed,
from tools.blueprints import (
BlueprintError,
BlueprintSpec,
create_blueprint_job,
export_blueprint,
parse_blueprint,
blueprint_spec_for_installed,
)
RECIPE_SKILL = """---
BLUEPRINT_SKILL = """---
name: morning-brief
description: Summarize unread email and calendar every morning.
version: 1.0.0
metadata:
hermes:
tags: [recipe, email]
recipe:
tags: [blueprint, email]
blueprint:
schedule: "0 8 * * *"
deliver: telegram
prompt: "Summarize my unread email and today's calendar."
@ -40,22 +40,22 @@ Every morning, gather unread email and the day's calendar and send a digest.
"""
PLAIN_SKILL = """---
name: not-a-recipe
name: not-a-blueprint
description: Just a regular skill.
metadata:
hermes:
tags: [misc]
---
# Not a recipe
# Not a blueprint
"""
MALFORMED_RECIPE = """---
MALFORMED_BLUEPRINT = """---
name: broken
description: Recipe with no schedule.
description: Blueprint with no schedule.
metadata:
hermes:
recipe:
blueprint:
deliver: origin
---
@ -63,49 +63,49 @@ metadata:
"""
class TestParseRecipe:
def test_parses_full_recipe(self):
spec = parse_recipe(RECIPE_SKILL)
class TestParseBlueprint:
def test_parses_full_blueprint(self):
spec = parse_blueprint(BLUEPRINT_SKILL)
assert spec is not None
assert spec.skill_name == "morning-brief"
assert spec.schedule == "0 8 * * *"
assert spec.deliver == "telegram"
assert spec.prompt is not None and spec.prompt.startswith("Summarize")
def test_plain_skill_is_not_a_recipe(self):
assert parse_recipe(PLAIN_SKILL) is None
def test_plain_skill_is_not_a_blueprint(self):
assert parse_blueprint(PLAIN_SKILL) is None
def test_no_frontmatter_is_not_a_recipe(self):
assert parse_recipe("just some text, no frontmatter") is None
def test_no_frontmatter_is_not_a_blueprint(self):
assert parse_blueprint("just some text, no frontmatter") is None
def test_missing_schedule_raises(self):
with pytest.raises(RecipeError):
parse_recipe(MALFORMED_RECIPE)
with pytest.raises(BlueprintError):
parse_blueprint(MALFORMED_BLUEPRINT)
def test_recipe_not_mapping_raises(self):
bad = "---\nname: x\nmetadata:\n hermes:\n recipe: not-a-dict\n---\n\nbody"
with pytest.raises(RecipeError):
parse_recipe(bad)
def test_blueprint_not_mapping_raises(self):
bad = "---\nname: x\nmetadata:\n hermes:\n blueprint: not-a-dict\n---\n\nbody"
with pytest.raises(BlueprintError):
parse_blueprint(bad)
def test_deliver_defaults_to_origin(self):
skill = (
"---\nname: r\ndescription: d\nmetadata:\n hermes:\n"
' recipe:\n schedule: "every 1h"\n---\n\nbody'
' blueprint:\n schedule: "every 1h"\n---\n\nbody'
)
spec = parse_recipe(skill)
spec = parse_blueprint(skill)
assert spec is not None
assert spec.deliver == "origin"
class TestRecipeSpecForInstalled:
def test_finds_and_parses_installed_recipe(self, tmp_path):
class TestBlueprintSpecForInstalled:
def test_finds_and_parses_installed_blueprint(self, tmp_path):
skills_dir = tmp_path / "skills"
rec_dir = skills_dir / "productivity" / "morning-brief"
rec_dir.mkdir(parents=True)
(rec_dir / "SKILL.md").write_text(RECIPE_SKILL, encoding="utf-8")
(rec_dir / "SKILL.md").write_text(BLUEPRINT_SKILL, encoding="utf-8")
with patch("tools.skills_hub.SKILLS_DIR", skills_dir):
spec = recipe_spec_for_installed("morning-brief")
spec = blueprint_spec_for_installed("morning-brief")
assert spec is not None
assert spec.schedule == "0 8 * * *"
@ -113,20 +113,20 @@ class TestRecipeSpecForInstalled:
skills_dir = tmp_path / "skills"
skills_dir.mkdir()
with patch("tools.skills_hub.SKILLS_DIR", skills_dir):
assert recipe_spec_for_installed("nope") is None
assert blueprint_spec_for_installed("nope") is None
def test_plain_skill_returns_none(self, tmp_path):
skills_dir = tmp_path / "skills"
d = skills_dir / "misc" / "not-a-recipe"
d = skills_dir / "misc" / "not-a-blueprint"
d.mkdir(parents=True)
(d / "SKILL.md").write_text(PLAIN_SKILL, encoding="utf-8")
with patch("tools.skills_hub.SKILLS_DIR", skills_dir):
assert recipe_spec_for_installed("not-a-recipe") is None
assert blueprint_spec_for_installed("not-a-blueprint") is None
class TestCreateRecipeJob:
class TestCreateBlueprintJob:
def test_bridges_to_create_job(self):
spec = parse_recipe(RECIPE_SKILL)
spec = parse_blueprint(BLUEPRINT_SKILL)
assert spec is not None
captured = {}
@ -135,7 +135,7 @@ class TestCreateRecipeJob:
return {"id": "abc123", **kwargs}
with patch("cron.jobs.create_job", fake_create_job):
job = create_recipe_job(spec, origin={"platform": "telegram"})
job = create_blueprint_job(spec, origin={"platform": "telegram"})
assert captured["schedule"] == "0 8 * * *"
assert captured["skills"] == ["morning-brief"]
@ -144,7 +144,7 @@ class TestCreateRecipeJob:
assert job["id"] == "abc123"
class TestExportRecipe:
class TestExportBlueprint:
def test_round_trips_job_to_skill_md(self):
job = {
"name": "My Morning Brief",
@ -153,19 +153,19 @@ class TestExportRecipe:
"deliver": "telegram",
"prompt": "Summarize my unread email.",
}
md = export_recipe(job, "# Morning Brief\n\nDoes the morning digest.")
# The exported SKILL.md must itself parse back as a recipe.
spec = parse_recipe(md)
md = export_blueprint(job, "# Morning Brief\n\nDoes the morning digest.")
# The exported SKILL.md must itself parse back as a blueprint.
spec = parse_blueprint(md)
assert spec is not None
assert spec.schedule == "0 8 * * *"
assert spec.deliver == "telegram"
# Name is sanitized to a valid skill identifier.
assert spec.skill_name == "my-morning-brief"
def test_export_has_recipe_tag(self):
def test_export_has_blueprint_tag(self):
job = {"name": "x", "schedule_display": "every 2h", "skills": ["x"]}
md = export_recipe(job, "body")
assert "recipe" in md
md = export_blueprint(job, "body")
assert "blueprint" in md
assert "automation" in md
def test_export_interval_job_without_display(self):
@ -177,12 +177,12 @@ class TestExportRecipe:
"schedule": {"kind": "interval", "minutes": 30},
"skills": ["poller"],
}
md = export_recipe(job, "body")
spec = parse_recipe(md)
md = export_blueprint(job, "body")
spec = parse_blueprint(md)
assert spec is not None
assert spec.schedule == "every 30m"
job["schedule"] = {"kind": "interval", "minutes": 120}
spec = parse_recipe(export_recipe(job, "body"))
spec = parse_blueprint(export_blueprint(job, "body"))
assert spec is not None
assert spec.schedule == "every 2h"