Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /als-apg_osprey /tests /cli /test_build_cmd.py
"""Tests for the osprey build command and build profile system."""
from __future__ import annotations
import json
import subprocess
import tomllib
from pathlib import Path
from textwrap import dedent
import pytest
import yaml
from osprey.cli.build_profile import (
BuildProfile,
EnvConfig,
LifecycleConfig,
LifecycleStep,
McpServerDef,
load_profile,
)
from osprey.cli.channel_finder_cmd import FILE_DATABASE_PARADIGMS
from osprey.errors import BuildProfileError
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def bundle_data_root(bundle: str = "control_assistant") -> Path:
"""The packaged data tree ``osprey init`` copies for *bundle*.
A build sources ``data/`` from the profile's own ``data:`` tree and from
nowhere else, so a test that drives ``TemplateManager.create_project``
directly — without a profile — hands it the packaged tree the materialized
profile would have pointed at.
"""
import osprey
return Path(osprey.__file__).parent / "templates" / "apps" / bundle / "data"
def _create_project(manager, **kwargs) -> Path:
"""``create_project`` with the data tree every render now requires.
A build copies the tree its profile's ``data:`` key names, and that key is
required — nothing falls back to a packaged tree any more. These fixtures
render straight from a bundle rather than from a profile, so they name the
tree that bundle packages.
"""
kwargs.setdefault("data_bundle", "control_assistant")
kwargs.setdefault("data_root", bundle_data_root(kwargs["data_bundle"]))
return manager.create_project(**kwargs)
def materialize_data(profile_dir: Path, bundle: str = "control_assistant") -> Path:
"""Copy *bundle*'s packaged data tree to ``profile_dir/data``, as init does.
For a test that builds through the real verb: the render stages channel
databases, limits and seeds out of the profile's tree, so the tree has to
be a real one.
"""
import shutil
dst = profile_dir / "data"
shutil.copytree(bundle_data_root(bundle), dst, dirs_exist_ok=True)
return dst
# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------
@pytest.fixture()
def profile_dir(tmp_path: Path) -> Path:
"""Create a minimal profile directory with a data tree and an MCP server."""
data_dir = tmp_path / "data"
data_dir.mkdir()
(data_dir / "channels.json").write_text('{"pvs": ["SR:DCCT"]}')
mcp_dir = tmp_path / "mcp_servers" / "test_server"
mcp_dir.mkdir(parents=True)
(mcp_dir / "__init__.py").write_text("")
(mcp_dir / "server.py").write_text("# test server")
return tmp_path
@pytest.fixture()
def minimal_profile_yaml(profile_dir: Path) -> Path:
"""Write a minimal valid profile YAML and return its path."""
profile = {
"name": "Test Profile",
"data": "data",
"provider": "cborg",
"model": "haiku",
"config": {
"control_system.type": "mock",
},
"mcp_servers": {
"test_server": {
"command": "python",
"args": ["-m", "test_server"],
"env": {
"CONFIG": "{project_root}/config.yml",
},
"permissions": {
"allow": ["test_tool"],
"ask": ["dangerous_tool"],
},
},
},
}
path = profile_dir / "test-profile.yml"
path.write_text(yaml.dump(profile, default_flow_style=False))
return path
# ---------------------------------------------------------------------------
# Profile Loading
# ---------------------------------------------------------------------------
class TestProfileLoading:
"""Tests for load_profile() and YAML parsing."""
def test_load_minimal_profile(self, minimal_profile_yaml: Path):
profile = load_profile(minimal_profile_yaml)
assert profile.name == "Test Profile"
assert profile.data == "data"
assert profile.provider == "cborg"
assert profile.model == "haiku"
def test_load_profile_not_found(self, tmp_path: Path):
with pytest.raises(BuildProfileError, match="Profile not found"):
load_profile(tmp_path / "nonexistent.yml")
def test_load_profile_invalid_yaml(self, tmp_path: Path):
bad_yaml = tmp_path / "bad.yml"
bad_yaml.write_text("{{invalid yaml: [")
with pytest.raises(BuildProfileError, match="Invalid YAML"):
load_profile(bad_yaml)
def test_load_profile_not_a_mapping(self, tmp_path: Path):
list_yaml = tmp_path / "list.yml"
list_yaml.write_text("- item1\n- item2\n")
with pytest.raises(BuildProfileError, match="must be a YAML mapping"):
load_profile(list_yaml)
def test_load_profile_config_parsed(self, minimal_profile_yaml: Path):
profile = load_profile(minimal_profile_yaml)
assert profile.config["control_system.type"] == "mock"
def test_load_profile_mcp_servers_parsed(self, minimal_profile_yaml: Path):
profile = load_profile(minimal_profile_yaml)
assert "test_server" in profile.mcp_servers
server = profile.mcp_servers["test_server"]
assert server.command == "python"
assert server.args == ["-m", "test_server"]
assert server.env == {"CONFIG": "{project_root}/config.yml"}
assert server.permissions == {"allow": ["test_tool"], "ask": ["dangerous_tool"]}
def test_load_profile_mcp_server_url(self, tmp_path: Path):
"""URL-only MCP server should parse correctly."""
(tmp_path / "data").mkdir()
p = tmp_path / "profile.yml"
p.write_text(
yaml.dump(
{
"name": "Test",
"data": "data",
"mcp_servers": {
"remote": {
"url": "http://host:8001/sse",
"permissions": {"allow": ["search"]},
}
},
}
)
)
profile = load_profile(p)
server = profile.mcp_servers["remote"]
assert server.url == "http://host:8001/sse"
assert server.command == ""
assert server.permissions == {"allow": ["search"], "ask": []}
def test_load_profile_mcp_server_both_command_and_url_rejected(self, tmp_path: Path):
"""Server with both command and url should be rejected at parse time."""
p = tmp_path / "profile.yml"
p.write_text(
yaml.dump(
{
"name": "Test",
"mcp_servers": {"bad": {"command": "npx", "url": "http://host:8001/sse"}},
}
)
)
with pytest.raises(BuildProfileError, match="both 'command' and 'url'"):
load_profile(p)
def test_load_profile_defaults(self, tmp_path: Path):
"""A profile stating only what is required should use defaults.
``name:`` and ``data:`` are the two keys every profile must carry, so
they are what "only" means here.
"""
(tmp_path / "data").mkdir()
simple = tmp_path / "simple.yml"
simple.write_text("name: Simple\ndata: data\n")
profile = load_profile(simple)
assert profile.data == "data"
assert profile.provider is None
assert profile.config == {}
assert profile.mcp_servers == {}
assert profile.lifecycle == LifecycleConfig()
assert profile.env == EnvConfig()
assert profile.dependencies == []
assert profile.hooks == []
assert profile.rules == []
assert profile.skills == []
assert profile.agents == []
assert profile.output_styles == []
assert profile.web_panels == []
# Self-contained/deployable is the default posture.
assert profile.deploy_services is True
def test_deploy_services_defaults_true(self, tmp_path: Path):
"""Omitting the knob leaves a project self-contained (deploys its own stack)."""
(tmp_path / "data").mkdir()
p = tmp_path / "d.yml"
p.write_text("name: Deployable\ndata: data\n")
assert load_profile(p).deploy_services is True
def test_deploy_services_explicit_false_parses(self, tmp_path: Path):
"""An explicit false marks the project as attached."""
(tmp_path / "data").mkdir()
p = tmp_path / "a.yml"
p.write_text(
"name: Attached\ndata: data\ndeploy_services: false\n"
"config:\n services.qmd.port: 8180\n"
)
assert load_profile(p).deploy_services is False
def test_deploy_services_inherited_child_wins(self, tmp_path: Path):
"""A child's deploy_services: false overrides an implicitly-true base.
deploy_services is a plain scalar, so ``extends`` resolves it child-wins
like any other scalar: a base that leaves it defaulted-true is overridden
by a child that sets it false.
"""
(tmp_path / "data").mkdir()
base = tmp_path / "base.yml"
base.write_text("name: Base\ndata: data\ndeploy_services: true\n")
child = tmp_path / "child.yml"
child.write_text(
"name: Child\nextends: base.yml\ndeploy_services: false\n"
"config:\n services.qmd.port: 8180\n"
)
assert load_profile(child).deploy_services is False
def test_load_profile_lifecycle_parsed(self, tmp_path: Path):
(tmp_path / "data").mkdir()
profile_data = {
"name": "Lifecycle Test",
"data": "data",
"lifecycle": {
"pre_build": [{"name": "check deps", "run": "pip check"}],
"post_build": [{"name": "build index", "run": "python index.py", "cwd": "data"}],
"validate": [{"name": "smoke test", "run": "python -c 'print(1)'"}],
},
}
path = tmp_path / "lc.yml"
path.write_text(yaml.dump(profile_data, default_flow_style=False))
profile = load_profile(path)
assert len(profile.lifecycle.pre_build) == 1
assert profile.lifecycle.pre_build[0].name == "check deps"
assert profile.lifecycle.pre_build[0].run == "pip check"
assert len(profile.lifecycle.post_build) == 1
assert profile.lifecycle.post_build[0].cwd == "data"
assert len(profile.lifecycle.validate) == 1
def test_load_profile_env_parsed(self, tmp_path: Path):
(tmp_path / "data").mkdir()
profile_data = {
"name": "Env Test",
"data": "data",
"env": {
"required": ["API_KEY", "DB_HOST"],
"defaults": {"LOG_LEVEL": "info", "PORT": "8080"},
},
}
path = tmp_path / "env.yml"
path.write_text(yaml.dump(profile_data, default_flow_style=False))
profile = load_profile(path)
assert profile.env.required == ["API_KEY", "DB_HOST"]
assert profile.env.defaults == {"LOG_LEVEL": "info", "PORT": "8080"}
def test_load_profile_dependencies_parsed(self, tmp_path: Path):
(tmp_path / "data").mkdir()
profile_data = {
"name": "Deps Test",
"data": "data",
"dependencies": ["numpy>=1.24", "pandas", "scipy~=1.11"],
}
path = tmp_path / "deps.yml"
path.write_text(yaml.dump(profile_data, default_flow_style=False))
profile = load_profile(path)
assert profile.dependencies == ["numpy>=1.24", "pandas", "scipy~=1.11"]
# ---------------------------------------------------------------------------
# Validation
# ---------------------------------------------------------------------------
class TestValidation:
"""Tests for BuildProfile.validate()."""
def test_misshapen_convention_source(self, tmp_path: Path):
"""Convention-directory validation runs as part of profile validation."""
(tmp_path / "skills").mkdir()
(tmp_path / "skills" / "loose.md").write_text("# not a skill directory\n")
profile = BuildProfile(name="Test")
with pytest.raises(BuildProfileError, match="one directory per skill"):
profile.validate(tmp_path)
def test_non_bool_deploy_services_rejected(self, tmp_path: Path):
"""A non-boolean deploy_services is a validation error, not silently coerced."""
profile = BuildProfile(name="Test", deploy_services="yes") # type: ignore[arg-type]
with pytest.raises(BuildProfileError, match="deploy_services must be a boolean"):
profile.validate(tmp_path)
def test_reserved_mirror_path_blocked(self, tmp_path: Path):
"""The project/ mirror may not write a path the build owns."""
mirror = tmp_path / "project"
mirror.mkdir()
(mirror / "config.yml").write_text("facility: {}\n")
profile = BuildProfile(name="Test")
with pytest.raises(BuildProfileError, match="`config:` block"):
profile.validate(tmp_path)
def test_missing_mcp_server_command_or_url(self, tmp_path: Path):
profile = BuildProfile(
name="Test",
mcp_servers={"broken": McpServerDef()},
)
with pytest.raises(BuildProfileError, match="missing 'command' or 'url'"):
profile.validate(tmp_path)
def test_mcp_server_url_only_passes_validation(self, tmp_path: Path):
(tmp_path / "data").mkdir()
profile = BuildProfile(
name="Test",
data="data",
mcp_servers={"remote": McpServerDef(url="http://host:8001/sse")},
)
profile.validate(tmp_path) # Should not raise
def test_missing_name_reported(self, tmp_path: Path):
profile = BuildProfile(name="")
with pytest.raises(BuildProfileError, match="'name' is required"):
profile.validate(tmp_path)
def test_lifecycle_step_missing_name(self, tmp_path: Path):
profile = BuildProfile(
name="Test",
lifecycle=LifecycleConfig(
pre_build=[LifecycleStep(name="", run="echo hello")],
),
)
with pytest.raises(BuildProfileError, match="missing 'name'"):
profile.validate(tmp_path)
def test_lifecycle_step_missing_run(self, tmp_path: Path):
profile = BuildProfile(
name="Test",
lifecycle=LifecycleConfig(
post_build=[LifecycleStep(name="broken", run="")],
),
)
with pytest.raises(BuildProfileError, match="missing 'run'"):
profile.validate(tmp_path)
def test_lifecycle_step_absolute_cwd_blocked(self, tmp_path: Path):
profile = BuildProfile(
name="Test",
lifecycle=LifecycleConfig(
pre_build=[LifecycleStep(name="bad", run="echo", cwd="/tmp/evil")],
),
)
with pytest.raises(BuildProfileError, match="cwd must be relative without"):
profile.validate(tmp_path)
def test_lifecycle_step_traversal_cwd_blocked(self, tmp_path: Path):
profile = BuildProfile(
name="Test",
lifecycle=LifecycleConfig(
pre_build=[LifecycleStep(name="bad", run="echo", cwd="../escape")],
),
)
with pytest.raises(BuildProfileError, match="cwd must be relative without"):
profile.validate(tmp_path)
def test_invalid_env_var_name(self, tmp_path: Path):
profile = BuildProfile(
name="Test",
env=EnvConfig(required=["bad-name"]),
)
with pytest.raises(BuildProfileError, match="Invalid env var name"):
profile.validate(tmp_path)
def test_empty_dependency_rejected(self, tmp_path: Path):
profile = BuildProfile(
name="Test",
dependencies=["numpy", ""],
)
with pytest.raises(BuildProfileError, match="non-empty string"):
profile.validate(tmp_path)
def test_valid_profile_passes(self, profile_dir: Path, minimal_profile_yaml: Path):
profile = load_profile(minimal_profile_yaml)
# Should not raise
profile.validate(profile_dir)
def test_default_panel_typo_rejected(self, tmp_path: Path):
"""A `default_panel` value that doesn't match any known panel is rejected.
Without this check the frontend silently falls back to the framework
default — a typo never surfaces. Validation catches it at build time.
"""
profile = BuildProfile(name="Test", default_panel="areil")
with pytest.raises(BuildProfileError, match="Unknown default_panel 'areil'"):
profile.validate(tmp_path)
def test_default_panel_selected_builtin_accepted(self, tmp_path: Path):
"""A built-in panel id is accepted as default_panel once web_panels
selects it — the selection is what shows the tab."""
(tmp_path / "data").mkdir()
profile = BuildProfile(
name="Test", data="data", web_panels=["ariel"], default_panel="ariel"
)
profile.validate(tmp_path) # must not raise
def test_default_panel_unselected_builtin_rejected(self, tmp_path: Path):
"""A built-in the profile never selected renders no tab, so naming it
as default_panel would fall back to the workspace silently."""
profile = BuildProfile(name="Test", default_panel="ariel")
with pytest.raises(BuildProfileError, match="Unknown default_panel 'ariel'"):
profile.validate(tmp_path)
def test_default_panel_custom_via_config_accepted(self, tmp_path: Path):
"""A custom panel backed by a `web.panels.<id>.url` config override
is accepted as default_panel once web_panels selects it."""
(tmp_path / "data").mkdir()
profile = BuildProfile(
name="Test",
data="data",
web_panels=["grafana"],
default_panel="grafana",
config={"web.panels.grafana.url": "http://localhost:3000"},
)
profile.validate(tmp_path) # must not raise
# ---------------------------------------------------------------------------
# Build Command Helpers
# ---------------------------------------------------------------------------
class TestBuildHelpers:
"""Tests for build_cmd.py helper functions."""
def test_persist_mcp_servers_url(self, tmp_path: Path):
"""_persist_mcp_servers writes URL server to config.yml claude_code.servers."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text("facility_name: test\n")
servers = {
"matlab": McpServerDef(url="http://matlab:8001/sse"),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
assert "matlab" in config["claude_code"]["servers"]
assert config["claude_code"]["servers"]["matlab"]["url"] == "http://matlab:8001/sse"
def test_persist_mcp_servers_stdio(self, tmp_path: Path):
"""_persist_mcp_servers writes stdio server with command/args/env."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text("facility_name: test\n")
servers = {
"confluence": McpServerDef(
command="uvx",
args=["--python=3.12", "mcp-atlassian"],
env={"CONFLUENCE_URL": "https://wiki.example.com"},
),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
entry = config["claude_code"]["servers"]["confluence"]
assert entry["command"] == "uvx"
assert entry["args"] == ["--python=3.12", "mcp-atlassian"]
assert entry["env"]["CONFLUENCE_URL"] == "https://wiki.example.com"
def test_persist_mcp_servers_permissions(self, tmp_path: Path):
"""_persist_mcp_servers preserves permission structure in config.yml."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text("facility_name: test\n")
servers = {
"phoebus": McpServerDef(
url="http://phoebus:8003/sse",
permissions={"allow": ["phoebus_launch"], "ask": ["dangerous_op"]},
),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
entry = config["claude_code"]["servers"]["phoebus"]
assert entry["permissions"]["allow"] == ["phoebus_launch"]
assert entry["permissions"]["ask"] == ["dangerous_op"]
def test_apply_conventions_mirrors_files(self, tmp_path: Path):
"""The project/ mirror copies files verbatim onto the project root."""
from osprey.cli.build_cmd import _apply_conventions
profile_dir = tmp_path / "profile"
(profile_dir / "project" / "config").mkdir(parents=True)
(profile_dir / "project" / "config" / "data.json").write_text('{"key": "value"}')
project_path = tmp_path / "project"
project_path.mkdir()
_apply_conventions(profile_dir, project_path)
assert (project_path / "config" / "data.json").exists()
assert json.loads((project_path / "config" / "data.json").read_text()) == {"key": "value"}
def test_apply_conventions_copies_whole_directories(self, tmp_path: Path):
"""An MCP server directory is copied as a unit."""
from osprey.cli.build_cmd import _apply_conventions
profile_dir = tmp_path / "profile"
src_dir = profile_dir / "mcp_servers" / "server_pkg"
src_dir.mkdir(parents=True)
(src_dir / "__init__.py").write_text("")
(src_dir / "main.py").write_text("# main")
project_path = tmp_path / "project"
project_path.mkdir()
_apply_conventions(profile_dir, project_path)
assert (project_path / "_mcp_servers" / "server_pkg" / "__init__.py").exists()
assert (project_path / "_mcp_servers" / "server_pkg" / "main.py").exists()
def test_persist_mcp_servers_writes_to_config(self, tmp_path: Path):
"""_persist_mcp_servers adds servers to claude_code.servers in config.yml."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text("facility_name: test\n")
servers = {
"remote_server": McpServerDef(
url="http://remote-host:8001/sse",
permissions={"allow": ["search", "get"], "ask": []},
),
"local_tool": McpServerDef(
command="npx",
args=["-y", "some-mcp-server"],
env={"API_KEY": "secret"},
permissions={"allow": ["do_thing"], "ask": []},
),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
persisted = config["claude_code"]["servers"]
# URL server
assert persisted["remote_server"]["url"] == "http://remote-host:8001/sse"
assert "command" not in persisted["remote_server"]
assert persisted["remote_server"]["permissions"]["allow"] == ["search", "get"]
# Stdio server
assert persisted["local_tool"]["command"] == "npx"
assert persisted["local_tool"]["args"] == ["-y", "some-mcp-server"]
assert persisted["local_tool"]["env"]["API_KEY"] == "secret"
assert "url" not in persisted["local_tool"]
def test_persist_mcp_servers_preserves_existing_config(self, tmp_path: Path):
"""_persist_mcp_servers doesn't clobber existing config.yml entries."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text(
"facility_name: test\nclaude_code:\n permissions:\n allow: [existing]\n"
)
servers = {
"my_server": McpServerDef(url="http://host:8001/sse"),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
# Original config preserved
assert config["facility_name"] == "test"
assert config["claude_code"]["permissions"]["allow"] == ["existing"]
# Server added
assert config["claude_code"]["servers"]["my_server"]["url"] == "http://host:8001/sse"
def test_load_profile_mcp_server_port_derives_url(self, tmp_path: Path):
"""A bare `port:` should yield url=http://localhost:<port>/mcp."""
(tmp_path / "data").mkdir()
p = tmp_path / "profile.yml"
p.write_text(
yaml.dump(
{
"name": "PortTest",
"data": "data",
"mcp_servers": {
"matlab": {
"port": 8008,
"permissions": {"allow": ["mml_search"]},
}
},
}
)
)
profile = load_profile(p)
server = profile.mcp_servers["matlab"]
assert server.port == 8008
assert server.url == "http://localhost:8008/mcp"
assert server.command == ""
def test_load_profile_mcp_server_port_with_explicit_url(self, tmp_path: Path):
"""An explicit `url:` plus `port:` should keep the explicit url verbatim."""
(tmp_path / "data").mkdir()
p = tmp_path / "profile.yml"
p.write_text(
yaml.dump(
{
"name": "ExternalClient",
"data": "data",
"mcp_servers": {
"matlab": {
"port": 8008,
"url": "http://appsdev2:8008/mcp",
}
},
}
)
)
profile = load_profile(p)
server = profile.mcp_servers["matlab"]
assert server.port == 8008
assert server.url == "http://appsdev2:8008/mcp" # explicit wins, no derivation
def test_load_profile_mcp_server_port_with_command_rejected(self, tmp_path: Path):
"""A stdio server (`command:`) cannot also declare a port."""
p = tmp_path / "profile.yml"
p.write_text(
yaml.dump(
{
"name": "Bad",
"mcp_servers": {
"confluence": {
"command": "uvx",
"port": 8001,
}
},
}
)
)
with pytest.raises(BuildProfileError, match="both 'command' and 'port'"):
load_profile(p)
@pytest.mark.parametrize(
"bad_port",
[0, -1, 65536, 80080, 100000],
ids=["zero", "negative", "just-above-max", "typo-extra-digit", "way-too-big"],
)
def test_load_profile_mcp_server_port_out_of_range_rejected(
self,
tmp_path: Path,
bad_port: int,
):
"""A `port:` outside 1..65535 must raise BuildProfileError at parse
time, so a typo like `port: 80080` cannot silently flow into the
derived url and the persisted network block."""
p = tmp_path / "profile.yml"
p.write_text(
yaml.dump(
{
"name": "OutOfRange",
"mcp_servers": {
"matlab": {
"port": bad_port,
"permissions": {"allow": ["mml_search"]},
}
},
}
)
)
with pytest.raises(BuildProfileError, match="port"):
load_profile(p)
def test_load_profile_mcp_server_port_non_integer_rejected(self, tmp_path: Path):
"""A string `port:` (YAML quoting accident) must be rejected at parse time."""
p = tmp_path / "profile.yml"
p.write_text(
yaml.dump(
{
"name": "Stringy",
"mcp_servers": {
"matlab": {
"port": "8008",
"permissions": {"allow": ["mml_search"]},
}
},
}
)
)
with pytest.raises(BuildProfileError, match="port"):
load_profile(p)
def test_persist_mcp_servers_port_emits_network_block(self, tmp_path: Path):
"""_persist_mcp_servers emits transport + url + network block when port is set."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text("facility_name: test\n")
servers = {
"matlab": McpServerDef(
url="http://localhost:8008/mcp",
port=8008,
permissions={"allow": ["mml_search"], "ask": []},
),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
entry = config["claude_code"]["servers"]["matlab"]
# The default is written explicitly — the rendered config states its
# wire transport instead of implying it from the url's presence.
assert entry["transport"] == "http"
assert entry["url"] == "http://localhost:8008/mcp"
assert entry["network"]["port"] == 8008
assert entry["network"]["host_url"] == "http://localhost:8008/mcp"
assert entry["network"]["docker_url"] == "http://matlab:8008/mcp"
def test_persist_mcp_servers_stdio_emits_command_only(self, tmp_path: Path):
"""Stdio servers get command/args and no network block."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text("facility_name: test\n")
servers = {
"confluence": McpServerDef(
command="uvx",
args=["--python=3.12", "mcp-atlassian"],
),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
entry = config["claude_code"]["servers"]["confluence"]
# Stdio has no transport choice — the key must not appear.
assert "transport" not in entry
assert entry["command"] == "uvx"
assert "network" not in entry
def test_persist_mcp_servers_url_without_port_no_network_block(self, tmp_path: Path):
"""A url-only server (no port hint) gets no network block."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text("facility_name: test\n")
servers = {
"remote": McpServerDef(url="http://appsdev2:8008/mcp"),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
entry = config["claude_code"]["servers"]["remote"]
assert entry["transport"] == "http"
assert entry["url"] == "http://appsdev2:8008/mcp"
assert "network" not in entry
def test_persist_mcp_servers_sse_transport_and_network_path(self, tmp_path: Path):
"""An SSE server persists transport=sse; network URLs follow the url's path."""
from osprey.cli.build_cmd import _persist_mcp_servers
project_path = tmp_path / "project"
project_path.mkdir()
(project_path / "config.yml").write_text("facility_name: test\n")
servers = {
"legacy": McpServerDef(
url="http://localhost:9000/sse",
transport="sse",
port=9000,
),
}
_persist_mcp_servers(project_path, servers)
config = yaml.safe_load((project_path / "config.yml").read_text())
entry = config["claude_code"]["servers"]["legacy"]
assert entry["transport"] == "sse"
assert entry["url"] == "http://localhost:9000/sse"
assert entry["network"]["host_url"] == "http://localhost:9000/sse"
assert entry["network"]["docker_url"] == "http://legacy:9000/sse"
def test_apply_config_overrides(self, tmp_path: Path):
"""_apply_config_overrides should update config.yml fields."""
from osprey.cli.build_cmd import _apply_config_overrides
project_path = tmp_path / "project"
project_path.mkdir()
config_path = project_path / "config.yml"
config_path.write_text(
dedent("""\
control_system:
type: mock
archiver:
type: mock_archiver
""")
)
_apply_config_overrides(
project_path,
{
"control_system.type": "epics",
"system.timezone": "America/Los_Angeles",
},
)
updated = yaml.safe_load(config_path.read_text())
assert updated["control_system"]["type"] == "epics"
assert updated["system"]["timezone"] == "America/Los_Angeles"
# Verify untouched fields preserved
assert updated["archiver"]["type"] == "mock_archiver"
# ---------------------------------------------------------------------------
# Environment Template
# ---------------------------------------------------------------------------
def _render_env_example(**context) -> str:
"""Render ``project/env.example.j2`` with the build's own context defaults."""
from osprey.cli.templates import scaffolding
from osprey.cli.templates.manager import TemplateManager
ctx = {
"project_name": "test-project",
"project_root": "/tmp/test-project",
"provider_api_keys": scaffolding.provider_api_key_entries(),
"service_token_vars": scaffolding.service_token_var_entries(),
"env_required": [],
"env_defaults": {},
**context,
}
return TemplateManager().jinja_env.get_template("project/env.example.j2").render(**ctx)
class TestEnvExample:
"""``.env.example`` is the one file documenting the whole variable set.
It replaced ``.env.template``, which listed only the profile's own
``env:`` block and so documented a strict subset of what the agent reads.
"""
def test_dot_env_template_is_gone(self):
"""The generator and its build step are deleted, not merely unused."""
from osprey.cli import build_cmd, build_environment
assert not hasattr(build_environment, "_generate_env_template")
assert not hasattr(build_cmd, "_generate_env_template")
assert "_generate_env_template" not in build_cmd.__all__
def test_documents_required_vars(self):
content = _render_env_example(env_required=["API_KEY", "DB_HOST"])
assert "API_KEY=" in content
assert "DB_HOST=" in content
def test_documents_defaults_with_their_values(self):
content = _render_env_example(env_defaults={"LOG_LEVEL": "info", "PORT": "8080"})
assert "LOG_LEVEL=info" in content
assert "PORT=8080" in content
def test_documents_required_and_defaults_together(self):
content = _render_env_example(env_required=["API_KEY"], env_defaults={"PORT": "8080"})
assert "API_KEY=" in content
assert "PORT=8080" in content
assert content.index("API_KEY=") < content.index("PORT=8080")
def test_documents_every_provider_api_key(self):
from osprey.models.provider_registry import PROVIDER_API_KEYS
content = _render_env_example()
for var in PROVIDER_API_KEYS.values():
if var is not None:
assert var in content, f"{var} missing from .env.example"
def test_documents_every_deploy_minted_variable(self):
"""Completeness is derived, not curated: a new minted var appears here.
The list comes from the same ``_SERVICE_TOKEN_VARS`` map the deploy
path mints from, so a service token can never ship undocumented.
"""
from osprey.deployment.container_lifecycle import _SERVICE_TOKEN_VARS
content = _render_env_example()
for token_vars in _SERVICE_TOKEN_VARS.values():
for var in token_vars:
assert var in content, f"{var} missing from .env.example"
def test_deploy_minted_variables_are_commented_out(self):
"""They are minted, not set by hand — an active line would pin an empty
value and defeat the mint."""
from osprey.deployment.container_lifecycle import _SERVICE_TOKEN_VARS
content = _render_env_example()
minted = {v for token_vars in _SERVICE_TOKEN_VARS.values() for v in token_vars}
for line in content.splitlines():
var = line.split("=", 1)[0].strip()
if var in minted:
pytest.fail(f"{var} must be commented out in .env.example, got: {line!r}")
def test_profile_with_no_env_block_still_renders(self):
content = _render_env_example()
assert "Environment Configuration" in content
assert "CBORG_API_KEY" in content
class TestGeneratedProjectEnvExample:
"""The file the build actually writes into the project."""
@pytest.fixture()
def built_project(self, tmp_path: Path) -> Path:
from osprey.cli.templates.manager import TemplateManager
return _create_project(
TemplateManager(),
project_name="env-example-project",
output_dir=tmp_path,
data_root=bundle_data_root(),
context={"channel_finder_mode": "hierarchical"},
)
def test_env_example_is_written(self, built_project: Path):
assert (built_project / ".env.example").is_file()
def test_no_env_template_is_written(self, built_project: Path):
assert not (built_project / ".env.template").exists()
def test_minted_variables_are_documented(self, built_project: Path):
from osprey.deployment.container_lifecycle import _SERVICE_TOKEN_VARS
content = (built_project / ".env.example").read_text(encoding="utf-8")
for token_vars in _SERVICE_TOKEN_VARS.values():
for var in token_vars:
assert var in content, f"{var} missing from the built .env.example"
def test_gitignore_covers_every_env_variant_but_the_example(self, built_project: Path):
"""`.env` alone left the deploy-generated `.env.production` trackable."""
entries = [
line.strip()
for line in (built_project / ".gitignore").read_text().splitlines()
if line.strip() and not line.startswith("#")
]
assert ".env*" in entries
assert "!.env.example" in entries
assert entries.index(".env*") < entries.index("!.env.example"), (
"the negation must follow the pattern it re-includes"
)
# ---------------------------------------------------------------------------
# Dependencies
# ---------------------------------------------------------------------------
class TestProjectPyproject:
"""Tests for the pyproject.toml emitted by _create_project_venv().
The generated file is the built project's dependency record AND the anchor
that makes ``uv run`` resolve the project's own ``.venv`` instead of walking
up to an ancestor project. Both properties are load-bearing; see
:func:`osprey.cli.build_environment._write_project_pyproject`.
"""
def _make_profile(self, deps: list[str], osprey_install: str = "local") -> BuildProfile:
return BuildProfile(
name="test",
dependencies=deps,
osprey_install=osprey_install,
)
def _build(self, monkeypatch, project_path: Path, profile: BuildProfile) -> dict:
"""Build, then return the emitted pyproject.toml *parsed*.
Asserting on parsed TOML rather than raw text keeps the explanatory
comments in the generated file from colliding with assertions about its
tables — and makes a malformed emission a hard failure here rather than
a mystery inside uv.
"""
from osprey.cli.build_cmd import _create_project_venv
def fake_run(cmd, **kwargs):
return subprocess.CompletedProcess(args=cmd, returncode=0, stdout="", stderr="")
monkeypatch.setattr("osprey.cli.build_environment.subprocess.run", fake_run)
monkeypatch.setenv("UV", "/usr/bin/uv")
_create_project_venv(project_path, profile)
return tomllib.loads((project_path / "pyproject.toml").read_text())
def test_records_profile_deps(self, monkeypatch, tmp_path: Path):
project_path = tmp_path / "project"
project_path.mkdir()
data = self._build(monkeypatch, project_path, self._make_profile(["numpy>=1.24", "pandas"]))
assert "numpy>=1.24" in data["project"]["dependencies"]
assert "pandas" in data["project"]["dependencies"]
def test_records_osprey_spec(self, monkeypatch, tmp_path: Path):
project_path = tmp_path / "project"
project_path.mkdir()
data = self._build(monkeypatch, project_path, self._make_profile([], osprey_install="pip"))
assert "osprey-framework" in data["project"]["dependencies"]
def test_omits_build_system(self, monkeypatch, tmp_path: Path):
"""A [build-system] table would make uv try to BUILD the project.
Built projects have no ``src/`` package — they are config directories.
Declaring a build backend makes ``uv run`` fail on every invocation, so
the absence of this table is the contract, not an oversight.
"""
project_path = tmp_path / "project"
project_path.mkdir()
data = self._build(monkeypatch, project_path, self._make_profile([]))
assert "build-system" not in data
def test_normalizes_project_name(self, monkeypatch, tmp_path: Path):
project_path = tmp_path / "My Assistant v2"
project_path.mkdir()
data = self._build(monkeypatch, project_path, self._make_profile([]))
assert data["project"]["name"] == "my-assistant-v2"
def test_source_path_becomes_direct_reference(self, monkeypatch, tmp_path: Path):
"""A resolved source-tree path is not a valid PEP 508 requirement.
``_resolve_osprey_spec`` hands back a bare filesystem path for editable
and source-tree installs. Written verbatim it would make the dependency
list unparseable, so it is rendered as a direct reference instead.
"""
project_path = tmp_path / "project"
project_path.mkdir()
checkout = tmp_path / "osprey-checkout"
checkout.mkdir()
data = self._build(
monkeypatch, project_path, self._make_profile([], osprey_install=str(checkout))
)
assert f"osprey-framework @ {checkout.as_uri()}" in data["project"]["dependencies"]
def test_rewrites_rather_than_appends(self, monkeypatch, tmp_path: Path):
"""`osprey build` must not stack duplicate dependency blocks.
An appended emission produces a second ``[project]`` table, which is a
TOML redefinition error — so a successful parse on the second build is
itself the assertion.
"""
project_path = tmp_path / "project"
project_path.mkdir()
profile = self._make_profile(["numpy>=1.24"])
self._build(monkeypatch, project_path, profile)
data = self._build(monkeypatch, project_path, profile)
assert data["project"]["dependencies"].count("numpy>=1.24") == 1
def test_no_requirements_txt(self, monkeypatch, tmp_path: Path):
project_path = tmp_path / "project"
project_path.mkdir()
self._build(monkeypatch, project_path, self._make_profile(["numpy>=1.24"]))
assert not (project_path / "requirements.txt").exists()
# ---------------------------------------------------------------------------
# Lifecycle Phase Runner
# ---------------------------------------------------------------------------
class TestLifecyclePhaseRunner:
"""Tests for _run_lifecycle_phase()."""
def test_successful_step(self, tmp_path: Path):
from osprey.cli.build_cmd import _run_lifecycle_phase
steps = [LifecycleStep(name="echo test", run="echo hello")]
# Should not raise
_run_lifecycle_phase("post_build", steps, tmp_path, tmp_path)
def test_failing_step_aborts(self, tmp_path: Path):
from osprey.cli.build_cmd import _run_lifecycle_phase
steps = [LifecycleStep(name="bad cmd", run="false")]
with pytest.raises(BuildProfileError, match="'bad cmd' failed"):
_run_lifecycle_phase("pre_build", steps, tmp_path, tmp_path)
def test_failing_step_warns_when_no_abort(self, tmp_path: Path):
from osprey.cli.build_cmd import _run_lifecycle_phase
steps = [LifecycleStep(name="bad validate", run="false")]
# Should not raise
_run_lifecycle_phase("validate", steps, tmp_path, tmp_path, abort_on_failure=False)
def test_step_with_cwd(self, tmp_path: Path):
from osprey.cli.build_cmd import _run_lifecycle_phase
subdir = tmp_path / "subdir"
subdir.mkdir()
steps = [LifecycleStep(name="check cwd", run="pwd", cwd="subdir")]
# Should not raise — cwd relative to default_cwd
_run_lifecycle_phase("post_build", steps, tmp_path, tmp_path)
def test_project_root_placeholder(self, tmp_path: Path):
from osprey.cli.build_cmd import _run_lifecycle_phase
marker = tmp_path / "marker.txt"
steps = [
LifecycleStep(
name="touch marker",
run="touch {project_root}/marker.txt",
)
]
_run_lifecycle_phase("post_build", steps, tmp_path, tmp_path)
assert marker.exists()
def test_shell_metacharacters_handled(self, tmp_path: Path):
from osprey.cli.build_cmd import _run_lifecycle_phase
steps = [LifecycleStep(name="piped cmd", run="echo hello | cat")]
# Should not raise — shell=True for pipe
_run_lifecycle_phase("post_build", steps, tmp_path, tmp_path)
# ---------------------------------------------------------------------------
# Install Dependencies
# ---------------------------------------------------------------------------
class TestCreateProjectVenv:
"""Tests for _create_project_venv() — creates venv and installs deps."""
def _make_profile(self, deps: list[str], osprey_install: str = "local") -> BuildProfile:
return BuildProfile(
name="test",
dependencies=deps,
osprey_install=osprey_install,
)
def test_creates_venv_and_installs_with_uv(self, monkeypatch, tmp_path):
"""Should create project venv then install deps with uv."""
from osprey.cli.build_cmd import _create_project_venv
calls = []
def fake_run(cmd, **kwargs):
calls.append(cmd)
return subprocess.CompletedProcess(args=cmd, returncode=0, stdout="", stderr="")
monkeypatch.setattr("osprey.cli.build_environment.subprocess.run", fake_run)
monkeypatch.setenv("UV", "/home/user/.local/bin/uv")
_create_project_venv(tmp_path, self._make_profile(["numpy>=1.24", "pandas"]))
assert len(calls) == 2
# First call: create venv
venv_cmd = calls[0]
assert venv_cmd[0] == "/home/user/.local/bin/uv"
assert "venv" in venv_cmd
assert str(tmp_path / ".venv") in venv_cmd
# Second call: install deps
install_cmd = calls[1]
assert install_cmd[0] == "/home/user/.local/bin/uv"
assert install_cmd[1:3] == ["pip", "install"]
assert "numpy>=1.24" in install_cmd
assert "pandas" in install_cmd
def test_falls_back_to_stdlib_venv_and_pip(self, monkeypatch, tmp_path):
"""Should use python -m venv + pip when uv is not available."""
import sys
from osprey.cli.build_cmd import _create_project_venv
calls = []
def fake_run(cmd, **kwargs):
calls.append(cmd)
return subprocess.CompletedProcess(args=cmd, returncode=0, stdout="", stderr="")
monkeypatch.setattr("osprey.cli.build_environment.subprocess.run", fake_run)
monkeypatch.delenv("UV", raising=False)
monkeypatch.setattr("shutil.which", lambda name: None)
_create_project_venv(tmp_path, self._make_profile(["numpy>=1.24"]))
assert len(calls) == 2
# First call: python -m venv
venv_cmd = calls[0]
assert venv_cmd[0] == sys.executable
assert "-m" in venv_cmd and "venv" in venv_cmd
# Second call: pip install via venv python
install_cmd = calls[1]
assert str(tmp_path / ".venv" / "bin" / "python") in install_cmd
assert "-m" in install_cmd and "pip" in install_cmd
def test_raises_on_venv_failure(self, monkeypatch, tmp_path):
"""Should raise BuildProfileError if venv creation fails."""
from osprey.cli.build_cmd import _create_project_venv
def fake_run(cmd, **kwargs):
return subprocess.CompletedProcess(
args=cmd, returncode=1, stdout="", stderr="venv error"
)
monkeypatch.setattr("osprey.cli.build_environment.subprocess.run", fake_run)
monkeypatch.setenv("UV", "/usr/bin/uv")
with pytest.raises(BuildProfileError, match="Failed to create project venv"):
_create_project_venv(tmp_path, self._make_profile(["pkg"]))
def test_raises_on_install_failure(self, monkeypatch, tmp_path):
"""Should raise BuildProfileError when pip install fails."""
from osprey.cli.build_cmd import _create_project_venv
call_count = 0
def fake_run(cmd, **kwargs):
nonlocal call_count
call_count += 1
if call_count == 1:
# Venv creation succeeds
return subprocess.CompletedProcess(args=cmd, returncode=0, stdout="", stderr="")
# Install fails
return subprocess.CompletedProcess(
args=cmd, returncode=1, stdout="", stderr="ERROR: No matching distribution"
)
monkeypatch.setattr("osprey.cli.build_environment.subprocess.run", fake_run)
monkeypatch.setenv("UV", "/usr/bin/uv")
with pytest.raises(BuildProfileError, match="Failed to install project dependencies"):
_create_project_venv(tmp_path, self._make_profile(["nonexistent-xyz"]))
# ---------------------------------------------------------------------------
# Osprey install spec resolution
# ---------------------------------------------------------------------------
class TestResolveOspreySpec:
"""Tests for _resolve_osprey_spec() — auto-detect install mode from metadata.
Regression coverage for issue #216: building from a non-editable install
(e.g., ``uv tool install osprey-framework``) used to error with
"no pyproject.toml at <python lib>" because the resolver walked
``Path(__file__).parents[3]`` instead of consulting package metadata.
"""
def _fake_dist(
self,
version: str = "2026.5.0",
direct_url: dict | None = None,
):
class _Dist:
def __init__(self, ver, du):
self.version = ver
self._du = du
def read_text(self, name):
if name == "direct_url.json" and self._du is not None:
return json.dumps(self._du)
return None
return _Dist(version, direct_url)
def test_editable_install_uses_source_path(self, monkeypatch):
"""Editable install (``pip install -e .``) → spec is the source dir."""
from osprey.cli.build_cmd import _resolve_osprey_spec
fake = self._fake_dist(
direct_url={"url": "file:///abs/path/to/osprey", "dir_info": {"editable": True}},
)
monkeypatch.setattr("osprey.cli.build_environment.distribution", lambda _name: fake)
spec, label = _resolve_osprey_spec("local")
assert spec == "/abs/path/to/osprey"
assert "editable" in label
def _pretend_release(self, monkeypatch, version="2026.5.0", released=True):
"""Drive the version API, which is what the resolver now pins from."""
monkeypatch.setattr("osprey.version.get_release_version", lambda: version)
monkeypatch.setattr("osprey.version.is_release", lambda: released)
def test_wheel_install_pins_to_version(self, monkeypatch):
"""uv tool / pip wheel install → pinned to ``osprey-framework==<version>``."""
from osprey.cli.build_cmd import _resolve_osprey_spec
fake = self._fake_dist(
version="2026.5.0",
direct_url={"url": "https://pypi/...", "archive_info": {"hash": "sha256=abc"}},
)
monkeypatch.setattr("osprey.cli.build_environment.distribution", lambda _name: fake)
self._pretend_release(monkeypatch)
spec, label = _resolve_osprey_spec("local")
assert spec == "osprey-framework==2026.5.0"
assert label == "osprey-framework==2026.5.0"
def test_wheel_install_without_direct_url_pins_to_version(self, monkeypatch):
"""Older pip wheel install (no direct_url.json) → still pinned to version."""
from osprey.cli.build_cmd import _resolve_osprey_spec
fake = self._fake_dist(version="2026.5.0", direct_url=None)
monkeypatch.setattr("osprey.cli.build_environment.distribution", lambda _name: fake)
self._pretend_release(monkeypatch)
spec, _label = _resolve_osprey_spec("local")
assert spec == "osprey-framework==2026.5.0"
def test_unreleased_build_refuses_to_pin(self, monkeypatch):
"""A development build has no PyPI distribution — refuse rather than mislead.
Pinning to the nearest release would install code the operator never
wrote, with nothing saying the two differ.
"""
from osprey.cli.build_cmd import _resolve_osprey_spec
from osprey.errors import BuildProfileError
fake = self._fake_dist(
version="2026.5.0.post783+g83fda5e60",
direct_url={"url": "https://pypi/...", "archive_info": {"hash": "sha256=abc"}},
)
monkeypatch.setattr("osprey.cli.build_environment.distribution", lambda _name: fake)
monkeypatch.setattr(
"osprey.version.get_running_version", lambda: "2026.5.0.post783+g83fda5e60"
)
self._pretend_release(monkeypatch, released=False)
with pytest.raises(BuildProfileError, match="not a released version"):
_resolve_osprey_spec("local")
def test_pip_keyword_uses_unpinned_pypi(self, monkeypatch):
"""Explicit ``osprey_install: pip`` → unpinned ``osprey-framework``."""
from osprey.cli.build_cmd import _resolve_osprey_spec
spec, _label = _resolve_osprey_spec("pip")
assert spec == "osprey-framework"
def test_pep508_spec_passthrough(self):
"""Explicit PEP 508 spec → passed through verbatim."""
from osprey.cli.build_cmd import _resolve_osprey_spec
spec, label = _resolve_osprey_spec("osprey-framework==2026.4.0")
assert spec == "osprey-framework==2026.4.0"
assert label == "osprey-framework==2026.4.0"
def test_metadata_missing_falls_back_to_source_tree(self, monkeypatch, tmp_path):
"""If metadata is unavailable but a source tree exists at parents[3], use it."""
from importlib.metadata import PackageNotFoundError
from osprey.cli import build_environment
def _missing(_name):
raise PackageNotFoundError
monkeypatch.setattr(build_environment, "distribution", _missing)
# Real build_environment.py is in a source checkout (pyproject.toml at parents[3]).
spec, _label = build_environment._resolve_osprey_spec("local")
assert (Path(spec) / "pyproject.toml").exists()
# ---------------------------------------------------------------------------
# CLI Integration
# ---------------------------------------------------------------------------
class TestBuildCLI:
"""Tests for the Click command integration."""
def test_build_command_exists(self):
"""Verify build command is registered in the CLI."""
from click.testing import CliRunner
from osprey.cli.main import cli
runner = CliRunner()
result = runner.invoke(cli, ["build", "--help"])
assert result.exit_code == 0
# A fragment short enough that Click's help rewrapping cannot split it
# across a line break, whatever the terminal width.
assert "Render this deployment repo's" in result.output
def test_build_command_missing_profile(self):
"""Build should fail if profile file doesn't exist."""
from click.testing import CliRunner
from osprey.cli.main import cli
runner = CliRunner()
result = runner.invoke(cli, ["build", "test-proj", "/nonexistent/profile.yml"])
assert result.exit_code != 0
# ---------------------------------------------------------------------------
# Profile Inheritance (extends:)
# ---------------------------------------------------------------------------
def _write_yaml(path: Path, data: dict) -> Path:
"""Helper to write a YAML file and return its path."""
path.write_text(yaml.dump(data, default_flow_style=False))
return path
class TestProfileExtends:
"""Tests for profile inheritance via the ``extends:`` keyword."""
def _make_base(self, tmp_path: Path) -> Path:
"""Create a base profile with a data tree so validation passes."""
data_dir = tmp_path / "data"
data_dir.mkdir(exist_ok=True)
(data_dir / "channels.json").write_text("{}")
return _write_yaml(
tmp_path / "base.yml",
{
"name": "Base Profile",
"data": "data",
"provider": "cborg",
"model": "opus",
"hooks": ["hook-a", "hook-b"],
"rules": ["rule-x"],
"config": {
"control_system.type": "mock",
"archiver.type": "mock",
},
"mcp_servers": {
"server_one": {
"command": "python",
"args": ["-m", "server_one"],
"permissions": {"allow": ["tool_a", "tool_b"]},
},
},
"env": {
"required": ["API_KEY"],
"defaults": {"LOG_LEVEL": "info"},
},
"dependencies": ["fastmcp>=2.0", "pyepics>=3.5"],
},
)
def test_basic_extends(self, tmp_path: Path):
"""Child inherits base fields and overrides name."""
self._make_base(tmp_path)
child_path = _write_yaml(
tmp_path / "child.yml",
{"extends": "base.yml", "name": "Child Profile"},
)
profile = load_profile(child_path)
assert profile.name == "Child Profile"
assert profile.hooks == ["hook-a", "hook-b"]
assert profile.rules == ["rule-x"]
assert profile.provider == "cborg"
def test_scalar_override(self, tmp_path: Path):
"""Child overrides scalar fields; unmentioned scalars inherited."""
self._make_base(tmp_path)
child_path = _write_yaml(
tmp_path / "child.yml",
{"extends": "base.yml", "name": "Child", "model": "haiku"},
)
profile = load_profile(child_path)
assert profile.model == "haiku"
assert profile.provider == "cborg" # inherited
def test_dict_deep_merge(self, tmp_path: Path):
"""Config dicts are deep-merged; child keys override, base keys preserved."""
self._make_base(tmp_path)
child_path = _write_yaml(
tmp_path / "child.yml",
{
"extends": "base.yml",
"name": "Child",
"config": {
"archiver.type": "epics_archiver", # override
"system.timezone": "UTC", # new key
},
},
)
profile = load_profile(child_path)
assert profile.config["control_system.type"] == "mock" # inherited
assert profile.config["archiver.type"] == "epics_archiver" # overridden
assert profile.config["system.timezone"] == "UTC" # new
def test_list_union_dedup(self, tmp_path: Path):
"""String lists are unioned with dedup, base order preserved."""
self._make_base(tmp_path)
child_path = _write_yaml(
tmp_path / "child.yml",
{
"extends": "base.yml",
"name": "Child",
"hooks": ["hook-b", "hook-c"], # hook-b is a dup
},
)
profile = load_profile(child_path)
assert profile.hooks == ["hook-a", "hook-b", "hook-c"]
def test_mcp_server_deep_merge(self, tmp_path: Path):
"""MCP servers are deep-merged: child adds url, inherits permissions."""
# Base with permissions-only server (can't be built standalone)
data_dir = tmp_path / "data"
data_dir.mkdir(exist_ok=True)
(data_dir / "channels.json").write_text("{}")
_write_yaml(
tmp_path / "base.yml",
{
"name": "Base",
"data": "data",
"config": {"control_system.type": "mock"},
"mcp_servers": {
"matlab": {
"permissions": {"allow": ["mml_search", "mml_get"]},
},
},
},
)
child_path = _write_yaml(
tmp_path / "child.yml",
{
"extends": "base.yml",
"name": "Child",
"mcp_servers": {
"matlab": {"url": "http://localhost:8001/sse"},
},
},
)
profile = load_profile(child_path)
matlab = profile.mcp_servers["matlab"]
assert matlab.url == "http://localhost:8001/sse"
assert "mml_search" in matlab.permissions["allow"]
assert "mml_get" in matlab.permissions["allow"]
def test_env_merge(self, tmp_path: Path):
"""Env is deep-merged: file overridden, required unioned, defaults merged."""
self._make_base(tmp_path)
# Create the env file that the child references
(tmp_path / ".env.local").write_text("API_KEY=test\n")
child_path = _write_yaml(
tmp_path / "child.yml",
{
"extends": "base.yml",
"name": "Child",
"env": {
"file": ".env.local",
"required": ["API_KEY", "EXTRA_VAR"],
"defaults": {"DEBUG": "true"},
},
},
)
profile = load_profile(child_path)
assert profile.env.file == ".env.local" # overridden
assert "API_KEY" in profile.env.required # from both (deduped)
assert "EXTRA_VAR" in profile.env.required # from child
assert profile.env.defaults["LOG_LEVEL"] == "info" # inherited
assert profile.env.defaults["DEBUG"] == "true" # from child
def test_circular_extends(self, tmp_path: Path):
"""Circular extends chain is detected."""
_write_yaml(tmp_path / "a.yml", {"extends": "b.yml", "name": "A"})
_write_yaml(tmp_path / "b.yml", {"extends": "a.yml", "name": "B"})
with pytest.raises(BuildProfileError, match="Circular extends"):
load_profile(tmp_path / "a.yml")
def test_missing_base_file(self, tmp_path: Path):
"""Extends referencing a nonexistent file raises a clear, debuggable error.
The diagnostic surfaces BOTH the preset list (so typos against bundled
names are obvious) and the resolved filesystem path (so path-shaped
values are debuggable).
"""
child_path = _write_yaml(
tmp_path / "child.yml",
{"extends": "nonexistent.yml", "name": "Child"},
)
with pytest.raises(BuildProfileError) as exc:
load_profile(child_path)
msg = str(exc.value)
assert "nonexistent.yml" in msg
assert "no bundled preset" in msg.lower()
assert "no file at" in msg.lower()
def test_multi_level_extends(self, tmp_path: Path):
"""A extends B extends C resolves correctly."""
data_dir = tmp_path / "data"
data_dir.mkdir(exist_ok=True)
(data_dir / "channels.json").write_text("{}")
_write_yaml(
tmp_path / "grandparent.yml",
{
"name": "Grandparent",
"data": "data",
"provider": "cborg",
"model": "opus",
"hooks": ["hook-a"],
"config": {"control_system.type": "mock"},
"mcp_servers": {
"srv": {"command": "python", "args": ["-m", "srv"]},
},
},
)
_write_yaml(
tmp_path / "parent.yml",
{
"extends": "grandparent.yml",
"name": "Parent",
"hooks": ["hook-b"],
"rules": ["rule-x"],
},
)
child_path = _write_yaml(
tmp_path / "child.yml",
{
"extends": "parent.yml",
"name": "Child",
"hooks": ["hook-c"],
},
)
profile = load_profile(child_path)
assert profile.name == "Child"
assert profile.hooks == ["hook-a", "hook-b", "hook-c"]
assert profile.rules == ["rule-x"] # inherited from parent
assert profile.provider == "cborg" # inherited from grandparent
def test_no_extends_unchanged(self, minimal_profile_yaml: Path):
"""A profile without extends loads its own values verbatim."""
profile = load_profile(minimal_profile_yaml)
assert profile.name == "Test Profile"
assert profile.model == "haiku"
def test_lifecycle_concatenation(self, tmp_path: Path):
"""Lifecycle step lists are concatenated (base first, child appended)."""
data_dir = tmp_path / "data"
data_dir.mkdir(exist_ok=True)
(data_dir / "channels.json").write_text("{}")
_write_yaml(
tmp_path / "base.yml",
{
"name": "Base",
"data": "data",
"config": {"control_system.type": "mock"},
"mcp_servers": {
"srv": {"command": "python", "args": ["-m", "srv"]},
},
"lifecycle": {
"post_build": [{"name": "step-base", "run": "echo base"}],
},
},
)
child_path = _write_yaml(
tmp_path / "child.yml",
{
"extends": "base.yml",
"name": "Child",
"lifecycle": {
"post_build": [{"name": "step-child", "run": "echo child"}],
},
},
)
profile = load_profile(child_path)
names = [s.name for s in profile.lifecycle.post_build]
assert names == ["step-base", "step-child"]
def test_extends_key_stripped(self, tmp_path: Path):
"""The extends key does not leak into the parsed BuildProfile."""
self._make_base(tmp_path)
child_path = _write_yaml(
tmp_path / "child.yml",
{"extends": "base.yml", "name": "Child"},
)
profile = load_profile(child_path)
assert not hasattr(profile, "extends")
# ---------------------------------------------------------------------------
# Web Panels Rendering (profile web_panels: drives config.yml)
# ---------------------------------------------------------------------------
def _set_args(profile_keys: dict[str, object]) -> list[str]:
"""*profile_keys* as ``--set`` arguments for ``osprey init``.
One pair per top-level profile key. A ``--set`` value is YAML, and a
mapping given as one is written whole at the key it names, so a block like
``va_archiver:`` travels in a single pair.
"""
return [
arg
for key, value in profile_keys.items()
for arg in ("--set", f"{key}={json.dumps(value)}")
]
def _build_for_web_panels(
tmp_path: Path,
web_panels: list[str] | None,
overrides: dict | None = None,
default_panel: str | None = None,
) -> Path:
"""Build a minimal control_assistant project, optionally with web_panels,
a default_panel pin, and config overrides, and return the rendered
config.yml path.
Mirrors build_cmd.py steps 1b, 6, and 8 without running the full CLI.
"""
from osprey.cli.build_cmd import _apply_config_overrides
from osprey.cli.templates.artifact_library import validate_artifacts
from osprey.cli.templates.manager import TemplateManager
data_dir = tmp_path / "data"
data_dir.mkdir(exist_ok=True)
(data_dir / "channels.json").write_text("{}")
profile_data: dict = {
"name": "Panels Test",
"data": "data",
"provider": "cborg",
"model": "haiku",
# Ship the memory-guard hook the real control_assistant preset ships:
# without it the built profile leaves Write/MultiEdit/NotebookEdit
# ungated and the build-time write-tool lint (correctly) refuses it.
"hooks": ["memory-guard"],
}
if web_panels is not None:
profile_data["web_panels"] = web_panels
if default_panel is not None:
profile_data["default_panel"] = default_panel
if overrides:
profile_data["config"] = overrides
profile_path = tmp_path / "profile.yml"
profile_path.write_text(yaml.dump(profile_data, default_flow_style=False))
build_profile = load_profile(profile_path)
artifacts: dict[str, list[str]] = {}
for artifact_type in ("hooks", "rules", "skills", "agents", "output_styles"):
names = getattr(build_profile, artifact_type, [])
if names:
artifacts[artifact_type] = list(names)
if artifacts:
validate_artifacts(artifacts)
if build_profile.web_panels:
artifacts["web_panels"] = list(build_profile.web_panels)
template_context: dict = {}
if build_profile.default_panel:
template_context["default_panel"] = build_profile.default_panel
manager = TemplateManager()
project_dir = _create_project(
manager,
project_name="panels-test",
output_dir=tmp_path / "out",
context=template_context,
force=False,
artifacts=artifacts,
data_root=build_profile.resolved_data_root(tmp_path),
)
if build_profile.config:
_apply_config_overrides(project_dir, build_profile.config)
return project_dir / "config.yml"
class TestWebPanelsRendering:
"""Profile web_panels: list drives which builtin panels are enabled in config.yml."""
def test_builtin_panels_rendered_from_web_panels(self, tmp_path: Path):
"""Only builtin panels listed in web_panels appear with enabled: true."""
config_path = _build_for_web_panels(tmp_path, web_panels=["ariel", "lattice"])
config = yaml.safe_load(config_path.read_text())
panels = config["web"]["panels"]
assert panels.get("ariel", {}).get("enabled") is True
assert panels.get("lattice", {}).get("enabled") is True
assert "channel-finder" not in panels
def test_custom_panels_filtered_from_template_but_configurable(self, tmp_path: Path):
"""Non-builtin entries in web_panels are skipped by the template, but
their dotted-override config still lands in config.yml."""
config_path = _build_for_web_panels(
tmp_path,
web_panels=["ariel", "beam-viewer"],
overrides={
"web.panels.beam-viewer.label": "BEAM",
"web.panels.beam-viewer.url": "http://localhost:8007",
},
)
config = yaml.safe_load(config_path.read_text())
panels = config["web"]["panels"]
assert panels["ariel"]["enabled"] is True
# beam-viewer is custom (not in _BUILTIN_PANELS) — no enabled: true from template,
# but label/url from dotted overrides must land.
assert panels["beam-viewer"]["label"] == "BEAM"
assert panels["beam-viewer"]["url"] == "http://localhost:8007"
assert "enabled" not in panels["beam-viewer"]
def test_no_web_panels_renders_no_web_block(self, tmp_path: Path):
"""A profile that selects nothing renders no `web:` header at all.
The section is written only when a selection fills it — a default
panel, a builtin, or a layout preset. A bare `web:` is worse than none:
the web terminal cannot load one, and a `config: web.panels.<id>.*`
key creates the branch it needs on its own.
"""
config_path = _build_for_web_panels(tmp_path, web_panels=None)
config = yaml.safe_load(config_path.read_text())
assert "web" not in config
def test_builtin_enabled_from_template_merges_with_dotted_label(self, tmp_path: Path):
"""A builtin panel gets enabled: true from the template, then the dotted
override web.panels.<id>.label merges into the same dict."""
config_path = _build_for_web_panels(
tmp_path,
web_panels=["lattice"],
overrides={"web.panels.lattice.label": "LATTICE"},
)
config = yaml.safe_load(config_path.read_text())
lattice = config["web"]["panels"]["lattice"]
assert lattice["enabled"] is True
assert lattice["label"] == "LATTICE"
def test_default_panel_rendered_when_set(self, tmp_path: Path):
"""Profile default_panel: ariel ends up as web.default_panel in config.yml.
The web terminal reads this key on startup; the frontend pins the
cold-load tab to it.
"""
config_path = _build_for_web_panels(tmp_path, web_panels=["ariel"], default_panel="ariel")
config = yaml.safe_load(config_path.read_text())
assert config["web"]["default_panel"] == "ariel"
def test_default_panel_omitted_when_unset(self, tmp_path: Path):
"""Without a profile default_panel, the rendered config.yml omits
the key entirely so the frontend falls back to DEFAULT_PANEL_FALLBACK."""
config_path = _build_for_web_panels(tmp_path, web_panels=["ariel"])
config = yaml.safe_load(config_path.read_text())
assert "default_panel" not in config["web"]
# ---------------------------------------------------------------------------
# Tier Flattening (materialize_tier_artifacts)
# ---------------------------------------------------------------------------
def _preset_tier_source(tier: int, paradigm: str) -> Path:
"""Path to the bundled preset's tier-routed source DB."""
import osprey
osprey_root = Path(osprey.__file__).parent
return (
osprey_root
/ "templates"
/ "apps"
/ "control_assistant"
/ "data"
/ "channel_databases"
/ "tiers"
/ f"tier{tier}"
/ f"{paradigm}.json"
)
# The posture every deployment must state in its own `config:` block for a
# build to be allowed to render. Nothing supplies these behind the profile's
# back, so a hand-written test profile spells them the way a materialized one
# does.
POSTURE_CONFIG: dict = {
"control_system.type": "mock",
"archiver.type": "mock",
"claude_code.telemetry.enabled": False,
"hooks.debug": False,
}
def _write_tier_profile(profile_dir: Path, paradigm: str, tier: int | None = None) -> Path:
"""Write a minimal control_assistant profile pinned to a single paradigm
and (optionally) a tier."""
profile_data: dict = {
"name": "Tier Test",
"data": "data",
"provider": "cborg",
"model": "haiku",
"channel_finder_mode": paradigm,
"config": dict(POSTURE_CONFIG),
}
if tier is not None:
profile_data["tier"] = tier
path = profile_dir / "tier-profile.yml"
path.write_text(yaml.dump(profile_data, default_flow_style=False))
return path
def _tier_repo(tmp_path: Path, paradigm: str, tier: int | None = None) -> Path:
"""A deployment repo whose profile pins one paradigm and, optionally, a tier.
The tier lives in ``profile.yml`` — it is a property of the deployment, not
of the invocation that renders it — so a test that wants tier 1 writes tier
1 into the source and builds. ``osprey set tier=N`` is the CLI spelling of
the same edit and is pinned in tests/cli/test_set_verb.py.
"""
repo = tmp_path / f"tier-{paradigm}-{tier or 'default'}"
repo.mkdir(parents=True, exist_ok=True)
profile_data: dict = {
"name": "Tier Test",
"data": "data",
"provider": "cborg",
"model": "haiku",
"channel_finder_mode": paradigm,
"config": dict(POSTURE_CONFIG),
}
if tier is not None:
profile_data["tier"] = tier
(repo / "profile.yml").write_text(yaml.dump(profile_data, default_flow_style=False))
# The data tree `osprey init` lays down beside the profile: the build stages
# its channel databases out of this tree and no other, and the Reach
# Contract refuses a render whose bind source is not there.
materialize_data(repo)
(repo / "data" / "facility_knowledge").mkdir(parents=True, exist_ok=True)
return repo
def _render(repo: Path):
"""Render *repo*'s build zone through the real verb."""
from click.testing import CliRunner
from osprey.cli.build_cmd import build
return CliRunner().invoke(build, ["--repo", str(repo), "--skip-deps", "--skip-lifecycle"])
# Every paradigm whose store is a channel-database file, derived from the
# registry so a new paradigm cannot be added without landing here. ``graph`` is
# excluded by the same subtraction the CLI's ``click.Choice`` lists use: its
# store is a graph service, so a graph build materializes no
# ``channel_databases/<paradigm>.json`` for these tests to byte-compare against
# a preset tier source. See tests/build/test_mode_registry_single_source.py.
_PARADIGMS_FOR_BUILD: tuple[str, ...] = tuple(FILE_DATABASE_PARADIGMS)
#: The flat channel databases a build materializes for those paradigms. Named
#: here so the graph render can assert it flattened none of them without also
#: asserting the directory is empty: the app template ships an example database
#: and an ``examples/`` tree in there, which every render carries.
_PARADIGM_DATABASE_FILENAMES: frozenset[str] = frozenset(
f"{paradigm}.json" for paradigm in _PARADIGMS_FOR_BUILD
)
# Tier selection is restricted to {1, 3}, and tier 1 is in_context-only
# (it ships no hierarchical/middle_layer DB). Only these combos are buildable.
_VALID_TIER_PARADIGMS: tuple[tuple[int, str], ...] = (
(1, "in_context"),
(3, "in_context"),
(3, "hierarchical"),
(3, "middle_layer"),
)
@pytest.mark.parametrize("tier,paradigm", _VALID_TIER_PARADIGMS)
def test_build_tier_flatten(tmp_path: Path, tier: int, paradigm: str) -> None:
"""A build materializes the active paradigm's DB at the flat path and
removes the ``tiers/`` subtree.
- rendered config.yml emits ``data/channel_databases/<paradigm>.json``
(no ``tiers/`` segment).
- the file exists at that flat path and byte-equals the preset's
``tiers/tier{N}/<paradigm>.json`` source.
- the other paradigms' flat files are NOT created.
- the ``tiers/`` subdirectory has been removed.
"""
repo = _tier_repo(tmp_path, paradigm, tier)
result = _render(repo)
assert result.exit_code == 0, (
f"build failed (exit={result.exit_code})\n"
f"--- output ---\n{result.output}\n"
f"--- exception ---\n{result.exception}"
)
project_dir = repo / "build"
config = yaml.safe_load((project_dir / "config.yml").read_text())
pipelines = config["channel_finder"]["pipelines"]
# (a) Rendered config points to the FLAT path — no tiers/ segment.
assert pipelines[paradigm]["database"]["path"] == f"data/channel_databases/{paradigm}.json", (
f"paradigm={paradigm} got {pipelines[paradigm]['database']['path']!r}"
)
# (b) The flat DB exists and byte-equals the preset tier source.
flat_path = project_dir / "data" / "channel_databases" / f"{paradigm}.json"
assert flat_path.exists(), f"flat DB missing: {flat_path}"
src = _preset_tier_source(tier, paradigm)
assert src.exists(), f"preset source missing: {src}"
assert flat_path.read_bytes() == src.read_bytes(), (
f"flat DB does not byte-equal preset tier{tier}/{paradigm}.json"
)
# (c) Other paradigms are NOT materialized to the flat root.
for other in _PARADIGMS_FOR_BUILD:
if other == paradigm:
continue
other_flat = project_dir / "data" / "channel_databases" / f"{other}.json"
assert not other_flat.exists(), (
f"{other}.json should not have been materialized for mode={paradigm!r}"
)
# (d) The tiers/ subtree has been pruned.
assert not (project_dir / "data" / "channel_databases" / "tiers").exists(), (
"tiers/ subtree was not pruned after materialization"
)
# Re-tiering 1 → 3 only applies to in_context; tier 1 is in_context-only.
@pytest.mark.parametrize("paradigm", ["in_context"])
def test_build_retier(tmp_path: Path, paradigm: str) -> None:
"""Changing the tier is a source edit followed by a rebuild.
This is the source/output split doing its job: nothing about the tier lives
in the invocation, so re-tiering is `osprey set tier=3` and then `osprey
build`, and the render that comes out is a tier-3 render with no trace of
the tier-1 one it replaced.
"""
from click.testing import CliRunner
from osprey.cli.set_cmd import set as set_cmd
repo = _tier_repo(tmp_path, paradigm, 1)
first = _render(repo)
assert first.exit_code == 0, f"tier-1 build failed: {first.output}\n{first.exception}"
edited = CliRunner().invoke(set_cmd, ["--repo", str(repo), "tier=3"])
assert edited.exit_code == 0, edited.output
second = _render(repo)
assert second.exit_code == 0, f"tier-3 rebuild failed: {second.output}\n{second.exception}"
flat_path = repo / "build" / "data" / "channel_databases" / f"{paradigm}.json"
src = _preset_tier_source(3, paradigm)
assert flat_path.read_bytes() == src.read_bytes(), (
f"after re-tiering to 3, {paradigm}.json does not byte-equal preset tier3 source"
)
@pytest.mark.parametrize("paradigm", _PARADIGMS_FOR_BUILD)
def test_build_profile_only_tier(tmp_path: Path, paradigm: str) -> None:
"""The profile's ``tier: 3`` is what drives materialization.
There is no other source for it: the tier is a property of the deployment,
recorded where a facility can read and edit it, so a render can never
disagree with the profile it came from.
"""
repo = _tier_repo(tmp_path, paradigm, 3)
result = _render(repo)
assert result.exit_code == 0, (
f"profile-only-tier build failed: {result.output}\n{result.exception}"
)
flat_path = repo / "build" / "data" / "channel_databases" / f"{paradigm}.json"
src = _preset_tier_source(3, paradigm)
assert flat_path.read_bytes() == src.read_bytes(), (
f"profile tier=3 not honored for {paradigm}.json"
)
# ---------------------------------------------------------------------------
# Events-panel URL derivation (Task 1.4)
# ---------------------------------------------------------------------------
class TestEventsPanelUrlDerivation:
"""_inject_dispatch derives web.panels.events.url from dispatcher_port."""
def _write_minimal_config(self, project_path: Path) -> None:
"""Write the smallest config.yml that _inject_dispatch needs."""
from ruamel.yaml import YAML
yaml = YAML()
with open(project_path / "config.yml", "w") as fh:
yaml.dump({"deployed_services": [], "services": {}}, fh)
def _dispatch(self, dispatcher_port: int = 8020, **overrides: object):
from osprey.cli.build_profile import DispatchConfig
base: dict = {
"triggers": "tutorial_triggers.yml",
"worker_count": 1,
"workspace_mode": "isolated",
"max_concurrent_runs": 2,
"max_queue_depth": 50,
"dispatcher_port": dispatcher_port,
"worker_port_base": 9190,
"timeout_sec": 300,
"facility_name": "generic-facility",
"pv_strip_prefix": "",
}
base.update(overrides)
return DispatchConfig(**base) # type: ignore[arg-type]
def _inject(self, dispatch, project_path: Path, profile_dir: Path) -> None:
from osprey.cli.build_cmd import _inject_dispatch
_inject_dispatch(dispatch, profile_dir=profile_dir, project_path=project_path)
def _read_config(self, project_path: Path) -> dict:
import yaml
return yaml.safe_load((project_path / "config.yml").read_text()) or {}
def test_events_panel_url_derived_from_dispatcher_port(self, tmp_path: Path) -> None:
"""events.url is a bare host and events.path carries the /dashboard route."""
project_path = tmp_path / "project"
project_path.mkdir()
profile_dir = tmp_path / "profile"
profile_dir.mkdir()
self._write_minimal_config(project_path)
self._inject(self._dispatch(dispatcher_port=8888), project_path, profile_dir)
config = self._read_config(project_path)
events = config["web"]["panels"]["events"]
# Bare host in url + /dashboard in path matches the custom-panel proxy
# convention (url.rstrip('/') + '/' + path); /dashboard must NOT be baked
# into url or sub-routes would double-prefix.
assert events["url"] == "http://localhost:8888"
assert events["path"] == "/dashboard"
def test_events_panel_url_reflects_custom_port(self, tmp_path: Path) -> None:
"""Different dispatcher_port values produce different derived bare-host URLs."""
project_path = tmp_path / "project"
project_path.mkdir()
profile_dir = tmp_path / "profile"
profile_dir.mkdir()
self._write_minimal_config(project_path)
self._inject(self._dispatch(dispatcher_port=9999), project_path, profile_dir)
config = self._read_config(project_path)
events = config["web"]["panels"]["events"]
assert events["url"] == "http://localhost:9999"
assert events["path"] == "/dashboard"
def test_events_panel_path_pinned_by_profile_preserved(self, tmp_path: Path) -> None:
"""A facility-pinned web.panels.events.path is left untouched (setdefault)."""
from ruamel.yaml import YAML
project_path = tmp_path / "project"
project_path.mkdir()
profile_dir = tmp_path / "profile"
profile_dir.mkdir()
yaml = YAML()
config_pre = {
"deployed_services": [],
"services": {},
"web": {"panels": {"events": {"path": "/custom-route"}}},
}
with open(project_path / "config.yml", "w") as fh:
yaml.dump(config_pre, fh)
self._inject(self._dispatch(dispatcher_port=8020), project_path, profile_dir)
config = self._read_config(project_path)
events = config["web"]["panels"]["events"]
# url is still derived (no explicit url was set), but the pinned path wins.
assert events["url"] == "http://localhost:8020"
assert events["path"] == "/custom-route"
def test_explicit_events_url_not_overwritten(self, tmp_path: Path) -> None:
"""An explicit web.panels.events.url already in config.yml is not replaced,
and the derivation does not force-inject a path alongside it."""
from ruamel.yaml import YAML
project_path = tmp_path / "project"
project_path.mkdir()
profile_dir = tmp_path / "profile"
profile_dir.mkdir()
# Pre-set an explicit URL via a profile config override (simulated here by
# writing it directly into config.yml before _inject_dispatch runs).
yaml = YAML()
config_pre = {
"deployed_services": [],
"services": {},
"web": {"panels": {"events": {"url": "http://custom-host:7777/dashboard"}}},
}
with open(project_path / "config.yml", "w") as fh:
yaml.dump(config_pre, fh)
self._inject(self._dispatch(dispatcher_port=8020), project_path, profile_dir)
config = self._read_config(project_path)
events = config["web"]["panels"]["events"]
# Explicit URL must survive — derivation must not overwrite it.
assert events["url"] == "http://custom-host:7777/dashboard"
# Derivation is fully skipped when an explicit url exists; it must not
# inject a path that would compose a double route against the explicit url.
assert "path" not in events
def test_build_channel_finder_agent_requires_mode(tmp_path: Path, caplog) -> None:
"""A profile that selects the channel-finder agent but omits
channel_finder_mode must fail with a clear BuildProfileError."""
import logging
from click.testing import CliRunner
from osprey.cli.main import cli
profile_data = {
"name": "no mode",
"data": "data",
"provider": "cborg",
"model": "haiku",
"agents": ["channel-finder"],
# NOTE: channel_finder_mode intentionally omitted.
}
repo = tmp_path / "no-mode"
(repo / "data").mkdir(parents=True)
(repo / "profile.yml").write_text(yaml.dump(profile_data, default_flow_style=False))
runner = CliRunner()
with caplog.at_level(logging.WARNING):
result = runner.invoke(
cli, ["build", "--repo", str(repo), "--skip-deps", "--skip-lifecycle"]
)
assert result.exit_code != 0, f"build should have failed; output:\n{result.output}"
# The diagnostic is logged (stderr in a real terminal), not written to
# stdout; click's Result.output folds the two streams together and cannot
# tell them apart, so read the record itself.
reported = caplog.text + (str(result.exception) if result.exception else "")
assert "channel_finder_mode" in reported
assert "required" in reported.lower()
# ---------------------------------------------------------------------------
# Approval-overlap guard (extends clones share bare-name approval policies)
# ---------------------------------------------------------------------------
def test_build_context_warns_when_remove_ask_overrides_gated_tool(tmp_path: Path, caplog) -> None:
"""A facility permissions.remove_ask (or allow) entry naming an enabled
server's approval-gated tool — e.g. an extends clone's phoebus_drive —
must emit a build-time warning: it auto-approves the tool at the
permission layer, and approval policies apply to every instance of a
template (no per-instance gating)."""
import logging
from osprey.cli.templates import claude_code
from osprey.cli.templates.manager import TemplateManager
manager = TemplateManager()
project = _create_project(
manager,
project_name="remove-ask-warn",
output_dir=tmp_path,
data_bundle="hello_world",
data_root=bundle_data_root("hello_world"),
)
config = yaml.safe_load((project / "config.yml").read_text())
cc = config.setdefault("claude_code", {})
cc.setdefault("servers", {})["phoebus2"] = {"extends": "phoebus"}
cc["permissions"] = {"remove_ask": ["mcp__phoebus2__phoebus_drive"]}
with caplog.at_level(logging.WARNING):
claude_code.build_claude_code_context(
manager.template_root, manager.jinja_env, project, config
)
assert any(
"mcp__phoebus2__phoebus_drive" in r.message and "approval-gated" in r.message
for r in caplog.records
), f"expected approval-overlap warning; got: {[r.message for r in caplog.records]}"
# ---------------------------------------------------------------------------
# Build lint: no ungated write-capable built-in (Write/MultiEdit/NotebookEdit)
# ---------------------------------------------------------------------------
def test_lint_rejects_ungated_write_tool_when_memory_guard_absent(tmp_path: Path) -> None:
"""A profile whose PreToolUse layer no longer gates the write-capable
built-ins — e.g. the memory-guard hook dropped, leaving ``selected_hooks``
empty — must be refused at build time with a BuildProfileError naming the
ungated tool. Write/MultiEdit/NotebookEdit are not in DENY_DEFAULTS (denying
them outright would block legitimate memory writes), so with no memory-guard
PreToolUse rule they are gated by nothing at all: exactly the ship-able
ungated-writer the lint exists to stop."""
from osprey.cli.templates import claude_code
from osprey.cli.templates.manager import TemplateManager
manager = TemplateManager()
project = _create_project(
manager,
project_name="lint-no-guard",
output_dir=tmp_path,
data_bundle="hello_world",
data_root=bundle_data_root("hello_world"),
)
config = yaml.safe_load((project / "config.yml").read_text())
ctx = claude_code.build_claude_code_context(
manager.template_root, manager.jinja_env, project, config
)
# Drop every framework hook, so the widened memory-guard's
# 'Write|MultiEdit|NotebookEdit' PreToolUse matcher is no longer rendered.
ctx["selected_hooks"] = []
with pytest.raises(claude_code.BuildProfileError) as excinfo:
claude_code.create_claude_code_integration(
manager.template_root, manager.jinja_env, project, ctx
)
message = str(excinfo.value)
# Names the first ungated write-capable built-in.
assert "Write" in message
assert "PreToolUse" in message
def test_lint_passes_for_normal_build_with_memory_guard(tmp_path: Path) -> None:
"""A normally-built profile ships the widened memory-guard hook, whose single
'Write|MultiEdit|NotebookEdit' PreToolUse matcher gates all three
write-capable built-ins — so the build lint passes and the rendered
settings.json actually carries that gate. Guards that the shipped presets do
not trip the lint."""
from osprey.cli.templates.manager import TemplateManager
manager = TemplateManager()
# create_project runs create_claude_code_integration, which runs the lint;
# a trip would raise here and fail the test.
project = _create_project(
manager,
project_name="lint-normal",
output_dir=tmp_path,
data_bundle="hello_world",
data_root=bundle_data_root("hello_world"),
)
settings = json.loads((project / ".claude" / "settings.json").read_text())
pre_matchers = [rule["matcher"] for rule in settings["hooks"]["PreToolUse"]]
# The widened memory-guard matcher that satisfies the lint is present.
assert any({"Write", "MultiEdit", "NotebookEdit"} <= set(m.split("|")) for m in pre_matchers), (
f"expected a Write|MultiEdit|NotebookEdit PreToolUse matcher; got: {pre_matchers}"
)
# --- Matcher spellings the lint must read the way Claude Code does ---------
@pytest.mark.parametrize(
"matcher",
[
pytest.param("*", id="literal-star"),
pytest.param(".*", id="regex-dot-star"),
pytest.param("", id="empty-string"),
pytest.param(None, id="omitted-key"),
],
)
def test_matcher_covers_every_match_all_spelling(matcher) -> None:
"""All four "run on every tool" spellings gate every write-capable built-in.
Claude Code runs a PreToolUse hook on every call when the matcher is ``"*"``,
an empty string, or absent; ``".*"`` reaches the same place through the regex
path. A lint that recognised only the literal ``"*"`` would refuse builds
whose hooks genuinely do gate the tool.
"""
from osprey.cli.templates.claude_code import _WRITE_CAPABLE_BUILTINS, _matcher_covers
for tool in _WRITE_CAPABLE_BUILTINS:
assert _matcher_covers(matcher, tool), f"{matcher!r} should cover {tool}"
@pytest.mark.parametrize(
("matcher", "tool", "covers"),
[
# Exact single name, and the pipe alternation the memory-guard ships.
("Bash", "Bash", True),
("Bash", "Edit", False),
("Write|MultiEdit|NotebookEdit", "NotebookEdit", True),
("Write|MultiEdit|NotebookEdit", "Bash", False),
# Regex spellings a facility may reasonably write.
("Write.*", "Write", True),
("^(Write|Edit)$", "Edit", True),
("^(Write|Edit)$", "Bash", False),
# Unanchored, exactly like Claude Code: "Edit.*" really does fire on
# NotebookEdit, while the metacharacter-free "Edit" does not.
("Edit.*", "NotebookEdit", True),
("Edit", "NotebookEdit", False),
# A server rule must not be read as gating a built-in.
("mcp__controls__.*", "Bash", False),
# Not a compilable regex: falls back to exact alternation, covers nothing.
("Write(", "Write", False),
],
)
def test_matcher_covers_regex_and_literal_spellings(matcher: str, tool: str, covers: bool) -> None:
"""Regex matchers are compiled and searched; the rest compare literally."""
from osprey.cli.templates.claude_code import _matcher_covers
assert _matcher_covers(matcher, tool) is covers
# --- Bash and Edit are gated by the lint, not only by the deny floor -------
def test_write_capable_builtins_cover_the_shell_and_patch_escape_hatches() -> None:
"""Bash and Edit are in the linted set.
DENY_DEFAULTS' own docstring calls them "the two that matter most — the
unmediated shell-out and unmediated file-patch escape hatches around every
other control the profile installs", yet their only gate is that they sit in
that deny floor, which `claude_code.permissions.remove_deny` can take away.
They belong to the linted set so removing them from the floor has to be
replaced by some other gate.
"""
from osprey.cli.templates.claude_code import _WRITE_CAPABLE_BUILTINS, DENY_DEFAULTS
assert {"Bash", "Edit"} <= set(_WRITE_CAPABLE_BUILTINS)
# And they are still what the deny floor gates them with today.
assert {"Bash", "Edit"} <= set(DENY_DEFAULTS)
def _project_with_permissions(tmp_path: Path, name: str, permissions: dict) -> tuple[object, Path]:
"""A built project whose config carries ``claude_code.permissions``.
The manifest is written as well as the project, because that is where a
regen reads the artifact selection back from: without it the regenerated
context selects no hooks at all and every write-tool gate the lint looks
for is missing for a reason that has nothing to do with the permissions
under test. It is stamped with what a build stamps — the preset the profile
records AND the selection the render was made with — because a manifest
that names neither leaves the regen with nothing to select from.
"""
from osprey.cli.templates.manager import TemplateManager
manager = TemplateManager()
project = _create_project(
manager,
project_name=name,
output_dir=tmp_path,
data_bundle="hello_world",
data_root=bundle_data_root("hello_world"),
)
manager.generate_manifest(
project,
name,
recorded_preset="hello-world",
artifacts=manager._effective_artifacts("hello_world", None),
preset_name="hello-world",
)
config = yaml.safe_load((project / "config.yml").read_text())
config.setdefault("claude_code", {})["permissions"] = permissions
(project / "config.yml").write_text(yaml.dump(config))
return manager, project
@pytest.mark.parametrize("tool", ["Bash", "Edit"])
def test_lint_rejects_remove_deny_of_an_ungated_escape_hatch(tmp_path: Path, tool: str) -> None:
"""`permissions.remove_deny: ["Bash"]` (or Edit) with nothing else gating it
must fail the build.
Before the lint covered these two, this exact config built clean: the tool
dropped out of permissions.deny, no PreToolUse matcher covered it, and the
generated profile shipped an unmediated shell (or file-patch) with no gate
of any kind — silently, unlike remove_ask, which at least warns.
"""
manager, project = _project_with_permissions(
tmp_path, f"remove-deny-{tool.lower()}", {"remove_deny": [tool]}
)
with pytest.raises(BuildProfileError) as excinfo:
manager.regenerate_claude_code(project)
message = str(excinfo.value)
assert tool in message
assert "remove_deny" in message
def test_lint_still_allows_remove_deny_of_a_non_write_tool(tmp_path: Path) -> None:
"""`remove_deny` itself is not refused — only removing a gate the lint covers.
WebSearch is in the deny floor but is not write-capable, so a facility that
wants it back still gets it. Guards the lint against over-reach.
"""
manager, project = _project_with_permissions(
tmp_path, "remove-deny-websearch", {"remove_deny": ["WebSearch"]}
)
manager.regenerate_claude_code(project)
settings = json.loads((project / ".claude" / "settings.json").read_text())
assert "WebSearch" not in settings["permissions"]["deny"]
assert "Bash" in settings["permissions"]["deny"]
def _ship_declared_pre_hook(project: Path, filename: str, matcher: str) -> None:
"""Put a facility hook in the project and declare it under PreToolUse.
Both halves are needed: `_vet_declared_hook` refuses a declaration whose
script the resolved profile does not ship (`scaffold.user_owned`) or that is
not present on disk, and the user-owned registration is also what keeps the
regen's prune pass from unlinking it.
"""
hooks_dir = project / ".claude" / "hooks"
hooks_dir.mkdir(parents=True, exist_ok=True)
(hooks_dir / filename).write_text("# facility gate\n", encoding="utf-8")
config = yaml.safe_load((project / "config.yml").read_text())
owned = config.setdefault("scaffold", {}).setdefault("user_owned", [])
owned.append(f"hooks/{filename}")
config.setdefault("claude_code", {}).setdefault("hooks", {})["PreToolUse"] = [
{"hook": filename, "matcher": matcher}
]
(project / "config.yml").write_text(yaml.dump(config))
def test_lint_accepts_a_declared_matcher_but_warns_that_it_proves_nothing(
tmp_path: Path, caplog
) -> None:
"""A facility that takes Bash out of the deny floor and gates it with its own
PreToolUse hook builds — and is told, loudly, what the build did not check.
The lint verifies that a covering rule EXISTS; it cannot verify the hook
behind it ever refuses. A PreToolUse hook that exits 0 without a
permissionDecision falls through to the normal permission flow, i.e. allows.
So a tool whose only gate is a matcher the profile declared itself passes
with a warning rather than silently.
"""
import logging
manager, project = _project_with_permissions(
tmp_path, "declared-bash-gate", {"remove_deny": ["Bash"]}
)
_ship_declared_pre_hook(project, "facility_bash_gate.py", "Bash")
with caplog.at_level(logging.WARNING):
manager.regenerate_claude_code(project)
settings = json.loads((project / ".claude" / "settings.json").read_text())
assert "Bash" not in settings["permissions"]["deny"]
assert any(
"Bash" in record.message and "permissionDecision" in record.message
for record in caplog.records
), f"expected an unverifiable-gate warning; got: {[r.message for r in caplog.records]}"
def test_a_framework_matcher_gates_without_the_warning(tmp_path: Path, caplog) -> None:
"""The memory-guard hook is framework-wired, so the three file-writing
built-ins it covers pass the lint quietly — the warning is reserved for gates
the build cannot vouch for."""
import logging
from osprey.cli.templates.manager import TemplateManager
manager = TemplateManager()
with caplog.at_level(logging.WARNING):
project = _create_project(
manager,
project_name="framework-gate-quiet",
output_dir=tmp_path,
data_bundle="hello_world",
data_root=bundle_data_root("hello_world"),
)
assert project.is_dir()
assert not [r.message for r in caplog.records if "permissionDecision" in r.message], (
"a framework-wired gate must not warn"
)
def test_writes_disabled_hard_block_covers_extends_clones(tmp_path: Path) -> None:
"""With control_system.writes_enabled false, the kill-switch hard-block must
cover extends clones of the controls/python templates, not just the literal
template names: the clone's rewritten channel_write lands in the rendered
settings.json permissions.deny, and the clone's execute is pulled out of
permissions.ask exactly like mcp__python__execute."""
from osprey.cli.templates.manager import TemplateManager
from osprey.utils.config_writer import config_update_fields
manager = TemplateManager()
project = _create_project(
manager,
project_name="writes-block-clone",
output_dir=tmp_path,
data_bundle="hello_world",
data_root=bundle_data_root("hello_world"),
)
# The regen below reads its artifact selection back from the manifest, so
# the stamp carries what a build's stamp carries: the recorded preset and
# the selection the render was made with.
manager.generate_manifest(
project,
"writes-block-clone",
recorded_preset="hello-world",
artifacts=manager._effective_artifacts("hello_world", None),
preset_name="hello-world",
)
config_update_fields(
project / "config.yml",
{
"control_system.writes_enabled": False,
"claude_code.servers.controls2.extends": "controls",
"claude_code.servers.python2.extends": "python",
},
)
manager.regenerate_claude_code(project)
settings = json.loads((project / ".claude" / "settings.json").read_text())
deny = settings["permissions"]["deny"]
ask = settings["permissions"]["ask"]
# Template and clone both hard-blocked.
assert "mcp__controls__channel_write" in deny
assert "mcp__controls2__channel_write" in deny
# Template and clone execute both pulled out of ask (remove_ask leg).
assert "mcp__python__execute" not in ask
assert "mcp__python2__execute" not in ask
# ---------------------------------------------------------------------------
# Service template bundling (_copy_service_templates)
# ---------------------------------------------------------------------------
class TestCopyServiceTemplates:
"""Tests for _copy_service_templates() — bundles package service templates.
A service merely DECLARED under `services:` (an opt-in add-on left out of
`deployed_services`) must still have its package template bundled, so it can
be switched on later with a `deployed_services` edit + `osprey up`
without rebuilding.
"""
def _write_config(self, project_path: Path, config: dict) -> None:
from ruamel.yaml import YAML
yaml_rt = YAML()
with open(project_path / "config.yml", "w") as fh:
yaml_rt.dump(config, fh)
def test_declared_but_not_deployed_service_is_bundled(self, tmp_path: Path) -> None:
"""openobserve declared under `services:` but absent from
deployed_services is still copied into the project's services/ tree,
while a deployed service (postgresql) still bundles (no regression)."""
from osprey.cli.build_cmd import _copy_service_templates
project_path = tmp_path / "project"
project_path.mkdir()
self._write_config(
project_path,
{
# postgresql is deployed; openobserve is only declared (opt-in).
"deployed_services": ["postgresql"],
"services": {
"postgresql": {"path": "./services/postgresql"},
"openobserve": {"path": "./services/openobserve"},
},
},
)
count = _copy_service_templates(project_path)
# Deployed service still bundles (regression guard).
assert (project_path / "services" / "postgresql" / "docker-compose.yml.j2").exists()
# Declared-but-not-deployed add-on is bundled too.
assert (project_path / "services" / "openobserve" / "docker-compose.yml.j2").exists()
assert count == 2
def test_declared_only_service_bundles_without_deployed_services(self, tmp_path: Path) -> None:
"""With an empty deployed_services, a declared service with a package
template is still bundled — the copy path must not early-return when
deployed_services is empty."""
from osprey.cli.build_cmd import _copy_service_templates
project_path = tmp_path / "project"
project_path.mkdir()
self._write_config(
project_path,
{
"deployed_services": [],
"services": {"openobserve": {"path": "./services/openobserve"}},
},
)
count = _copy_service_templates(project_path)
assert (project_path / "services" / "openobserve" / "docker-compose.yml.j2").exists()
assert count == 1
def test_declared_service_without_package_template_skipped_silently(
self, tmp_path: Path, caplog
) -> None:
"""A declared-only service with no package template is skipped without
a warning (it may be facility-injected elsewhere)."""
import logging
from osprey.cli.build_cmd import _copy_service_templates
project_path = tmp_path / "project"
project_path.mkdir()
self._write_config(
project_path,
{
"deployed_services": [],
"services": {"typesense": {"path": "./services/typesense"}},
},
)
with caplog.at_level(logging.WARNING, logger="osprey.cli.build_cmd"):
count = _copy_service_templates(project_path)
assert count == 0
assert not (project_path / "services" / "typesense").exists()
assert not any("typesense" in r.getMessage() for r in caplog.records), (
"declared-only service without a template must not warn"
)
def test_deployed_service_without_package_template_warns(self, tmp_path: Path, caplog) -> None:
"""A *deployed* service missing its package template still warns —
that would break `osprey up`, so the operator must be told."""
import logging
from osprey.cli.build_cmd import _copy_service_templates
project_path = tmp_path / "project"
project_path.mkdir()
self._write_config(
project_path,
{
"deployed_services": ["typesense"],
"services": {"typesense": {"path": "./services/typesense"}},
},
)
with caplog.at_level(logging.WARNING, logger="osprey.cli.build_cmd"):
count = _copy_service_templates(project_path)
assert count == 0
assert any("typesense" in r.getMessage() for r in caplog.records), (
"a deployed service without a template must warn"
)
# ---------------------------------------------------------------------------
# Tier selection rules
# ---------------------------------------------------------------------------
class TestTierSelectionRules:
"""Tier selection is restricted to {1, 3}, and tier 1 is in_context-only.
The tier is a profile key, so the rule is enforced where the profile
resolves — these cases pin that a tier-2 or a tier1+non-in_context profile
fails with a rule-naming error rather than an opaque downstream scaffolding
FileNotFoundError.
"""
@pytest.fixture()
def test_profile_tier_2_rejected(self, tmp_path: Path) -> None:
"""A profile YAML with ``tier: 2`` fails validation naming the {1,3} rule."""
from osprey.cli.build_profile import resolve_build_profile
prof = tmp_path / "profile.yml"
prof.write_text("name: t\nchannel_finder_mode: in_context\ntier: 2\n")
with pytest.raises(BuildProfileError, match="tier must be 1 or 3"):
resolve_build_profile(prof.resolve(), preset=None)
def test_profile_tier1_hierarchical_rejected(self, tmp_path: Path) -> None:
"""tier 1 paired with a non-in_context paradigm fails at validation with
the tier rule — not later as a scaffolding FileNotFoundError."""
from osprey.cli.build_profile import resolve_build_profile
prof = tmp_path / "profile.yml"
prof.write_text("name: t\nchannel_finder_mode: hierarchical\ntier: 1\n")
with pytest.raises(
BuildProfileError, match="tier 1 requires channel_finder_mode: in_context"
):
resolve_build_profile(prof.resolve(), preset=None)
def test_profile_tier1_in_context_accepted(self, tmp_path: Path) -> None:
"""The valid tier-1 combo (in_context) resolves cleanly."""
from osprey.cli.build_profile import resolve_build_profile
(tmp_path / "data").mkdir()
prof = tmp_path / "profile.yml"
prof.write_text("name: t\ndata: data\nchannel_finder_mode: in_context\ntier: 1\n")
resolved, _ = resolve_build_profile(prof.resolve(), preset=None)
assert resolved.tier == 1
assert resolved.resolved_tier() == 1
def test_preset_build_never_touches_the_presets_package_dir(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A build sources conventions from the deployment repo, never the wheel.
The repo root IS the profile root, so the conventions pass has an
operator-owned directory to read by construction. What this still guards is
the consequence of getting that wrong: reading the shared presets package
would pick up neighbouring presets' files, and seeding per-user context
there would write into the installed wheel. Both show up here — the pass's
actual source directory, and the package directory being byte-for-byte
unchanged in its entry list (a stray ``web-terminal-context/`` at the
package root is exactly what a regression would leave).
"""
from click.testing import CliRunner
import osprey.cli.build_cmd as build_cmd_module
import osprey.profiles.presets as presets_pkg
from osprey.cli.build_persistence import _apply_conventions
from osprey.cli.main import cli
presets_dir = Path(presets_pkg.__file__).parent
entries_before = sorted(p.name for p in presets_dir.iterdir() if p.name != "__pycache__")
profile_dirs: list[Path] = []
def spy(profile_dir: Path, *args, **kwargs):
profile_dirs.append(Path(profile_dir).resolve())
return _apply_conventions(profile_dir, *args, **kwargs)
monkeypatch.setattr(build_cmd_module, "_apply_conventions", spy)
from osprey.cli.init_cmd import init
repo = tmp_path / "preset-proj"
runner = CliRunner()
created = runner.invoke(init, [str(repo), "--preset", "hello-world", "--no-git"])
assert created.exit_code == 0, created.output
result = runner.invoke(cli, ["build", "--repo", str(repo), "--skip-deps", "--skip-lifecycle"])
assert result.exit_code == 0, (
f"build failed (exit={result.exit_code})\n{result.output}\n{result.exception}"
)
assert profile_dirs, "the conventions pass should run for every build"
for profile_dir in profile_dirs:
assert not profile_dir.is_relative_to(presets_dir.resolve()), (
f"conventions must never be sourced from the presets package: {profile_dir}"
)
assert profile_dir.is_relative_to(tmp_path.resolve()), (
f"conventions should come from the materialized profile: {profile_dir}"
)
entries_after = sorted(p.name for p in presets_dir.iterdir() if p.name != "__pycache__")
assert entries_after == entries_before
# ---------------------------------------------------------------------------
# The archiver store + recorder (_inject_va_archiver, step 10e)
# ---------------------------------------------------------------------------
class TestInjectVAArchiver:
"""The two archiver services, and the config the profile block derives.
The injector's job is the pair of services; the connection block and the
archive's knobs are NOT its job — they are config overrides, so an attached
project (which reaches no injector) gets them too. Both halves are asserted
here because together they are what makes a built project's archive real.
"""
def _write_config(self, project_path: Path, **overrides: object) -> None:
"""The smallest config.yml the injector needs, plus any overrides."""
from ruamel.yaml import YAML
config: dict = {"deployed_services": [], "services": {}}
config.update(overrides)
yaml_rt = YAML()
with open(project_path / "config.yml", "w") as fh:
yaml_rt.dump(config, fh)
def _project(self, tmp_path: Path, **overrides: object) -> Path:
project_path = tmp_path / "project"
project_path.mkdir()
self._write_config(project_path, **overrides)
return project_path
def _inject(self, project_path: Path, **knobs: object):
from osprey.cli.build_cmd import _inject_va_archiver
from osprey.cli.build_profile_archiver import VAArchiverConfig
_inject_va_archiver(VAArchiverConfig(**knobs), project_path) # type: ignore[arg-type]
def _read_config(self, project_path: Path) -> dict:
return yaml.safe_load((project_path / "config.yml").read_text()) or {}
def test_both_service_templates_land_in_the_project(self, tmp_path: Path) -> None:
"""A store nothing writes to and a recorder with nowhere to write are
each half a feature, so both are copied or neither is."""
project_path = self._project(tmp_path)
self._inject(project_path)
for name in ("mongodb", "archiver_recorder"):
assert (project_path / "services" / name / "docker-compose.yml.j2").is_file()
def test_both_services_are_deployed(self, tmp_path: Path) -> None:
project_path = self._project(tmp_path)
self._inject(project_path)
assert self._read_config(project_path)["deployed_services"] == [
"mongodb",
"archiver_recorder",
]
def test_the_store_block_carries_what_its_compose_template_reads(self, tmp_path: Path) -> None:
"""port_host, username and compression are read by the template with a
`| default`, so a wrong value here renders a working-but-wrong store."""
project_path = self._project(tmp_path)
self._inject(project_path, port_host=27100, username="facility", compression="snappy")
mongodb = self._read_config(project_path)["services"]["mongodb"]
assert mongodb["path"] == "./services/mongodb"
assert mongodb["port_host"] == 27100
assert mongodb["username"] == "facility"
assert mongodb["compression"] == "snappy"
# No password key, following the postgres convention: one minted .env
# variable is what the container and every reader authenticate with, so
# a key here would be read by nothing and lose to it silently.
assert "password" not in mongodb
def test_the_store_defaults_match_what_its_template_assumes(self, tmp_path: Path) -> None:
"""The compose template supplies its own `| default` for each of these.
Writing a different value here would render a store the connection block
cannot authenticate against — with no error until deploy time."""
project_path = self._project(tmp_path)
self._inject(project_path)
mongodb = self._read_config(project_path)["services"]["mongodb"]
assert mongodb["port_host"] == 10801
assert mongodb["username"] == "osprey"
assert mongodb["compression"] == "zstd"
def test_the_recorder_block_carries_its_template_path(self, tmp_path: Path) -> None:
"""The compose generator resolves each deployed service's template dir
from `path`, and the recorder needs nothing else — everything it reads
arrives from the mounted config.yml at run time."""
project_path = self._project(tmp_path)
self._inject(project_path)
assert self._read_config(project_path)["services"]["archiver_recorder"] == {
"path": "./services/archiver_recorder"
}
def test_no_image_is_pinned_for_either_service(self, tmp_path: Path) -> None:
"""The store falls to the template's pinned upstream tag and the
recorder to the VA's image; writing either here would defeat the
env/config/default override chain."""
project_path = self._project(tmp_path)
self._inject(project_path)
services = self._read_config(project_path)["services"]
assert "image" not in services["mongodb"]
assert "image" not in services["archiver_recorder"]
def test_injecting_twice_does_not_deploy_a_service_twice(self, tmp_path: Path) -> None:
"""A rebuild over an existing project re-runs the injector."""
project_path = self._project(tmp_path)
self._inject(project_path)
self._inject(project_path)
assert self._read_config(project_path)["deployed_services"] == [
"mongodb",
"archiver_recorder",
]
def test_a_claimed_service_template_is_left_untouched(self, tmp_path: Path) -> None:
"""`osprey scaffold claim services/mongodb` means the facility owns that
copy — refreshing it would discard their edits on every rebuild."""
project_path = self._project(tmp_path, scaffold={"user_owned": ["services/mongodb"]})
claimed = project_path / "services" / "mongodb"
claimed.mkdir(parents=True)
(claimed / "docker-compose.yml.j2").write_text("# hand-edited", encoding="utf-8")
self._inject(project_path)
assert (claimed / "docker-compose.yml.j2").read_text() == "# hand-edited"
# The unclaimed half of the pair still refreshes.
assert (project_path / "services" / "archiver_recorder").is_dir()
def test_an_existing_va_service_block_survives_injection(self, tmp_path: Path) -> None:
"""Step 10e runs after the VA's own injector, and the recorder template
gates on `virtual_accelerator` being in deployed_services."""
project_path = self._project(
tmp_path,
deployed_services=["virtual_accelerator"],
services={"virtual_accelerator": {"path": "./services/virtual_accelerator"}},
)
self._inject(project_path)
config = self._read_config(project_path)
assert config["deployed_services"] == [
"virtual_accelerator",
"mongodb",
"archiver_recorder",
]
assert "virtual_accelerator" in config["services"]
def test_the_injector_writes_no_connection_block(self, tmp_path: Path) -> None:
"""It belongs to the config-override path, which an attached project
also runs — writing it here too would be a second home for it."""
project_path = self._project(tmp_path)
self._inject(project_path)
assert "archiver" not in self._read_config(project_path)
class TestVAArchiverConfigDerivation:
"""The `va_archiver:` block's keys reach a built project's config.yml."""
def _build(self, tmp_path: Path, project_name: str, **profile_keys: object) -> Path:
"""Init the hello-world preset with *profile_keys* stated, build, and
return the RENDER — the directory whose config.yml the deploy reads."""
from click.testing import CliRunner
from osprey.cli.build_cmd import build
from osprey.cli.init_cmd import init
repo = tmp_path / project_name
argv = [str(repo), "--preset", "hello-world", "--no-git", *_set_args(profile_keys)]
runner = CliRunner()
result = runner.invoke(init, argv)
assert result.exit_code == 0, result.output
result = runner.invoke(build, ["--repo", str(repo), "--skip-deps", "--skip-lifecycle"])
assert result.exit_code == 0, result.output
return repo / "build"
def _config(self, project_path: Path) -> dict:
return yaml.safe_load((project_path / "config.yml").read_text()) or {}
def test_the_connector_can_connect_to_what_the_build_wrote(self, tmp_path: Path) -> None:
"""The connector raises on the first missing key, so a partial block
would build cleanly and die at the first archiver call."""
project = self._build(tmp_path, "archived", va_archiver={"port_host": 27100})
mongo = self._config(project)["archiver"]["mongodb_archiver"]
# The agent runs on the host, so it reaches the store on the published
# port. Container-side consumers use the `archiver-mongodb` network
# alias instead and never this block.
assert mongo["host"] == "localhost"
assert mongo["port"] == 27100
assert mongo["name"] and mongo["collection"]
# The store mints its root user, and a root user's credentials live in
# `admin` — authenticating against the data database would fail.
assert mongo["auth"] == "admin"
assert mongo["username"] == "osprey"
assert mongo["password_env"] == "MONGO_ROOT_PASSWORD"
# Short by design: the common failure is a project built but never
# deployed, and a fast explanatory error beats a minute of silence.
assert mongo["timeout"] == 5
def test_the_password_is_never_written_into_the_project(self, tmp_path: Path) -> None:
"""It reaches the store, the recorder and the agent as one minted .env
variable. A literal anywhere in config.yml would be both a secret on
disk and a second value free to disagree with the minted one."""
project = self._build(tmp_path, "archived", va_archiver={})
config = self._config(project)
assert "password" not in config["services"]["mongodb"]
assert "password" not in config["archiver"]["mongodb_archiver"]
def test_the_archive_knobs_reach_the_services_that_read_them(self, tmp_path: Path) -> None:
"""FR7: retention and cadence are profile edits, not code changes, so
they must be in the config the seeder and recorder read."""
project = self._build(
tmp_path, "archived", va_archiver={"retention_days": 2, "hot_span_hours": 2}
)
knobs = self._config(project)["va_archiver"]
assert knobs["retention_days"] == 2
assert knobs["hot_span_hours"] == 2
assert knobs["hot_cadence_sec"] == 10
assert knobs["tail_cadence_sec"] == 60
assert knobs["recorder_cadence_sec"] == 10
assert knobs["recorder_poll_sec"] == 30
def test_the_services_are_injected_by_the_build(self, tmp_path: Path) -> None:
project = self._build(tmp_path, "archived", va_archiver={})
config = self._config(project)
assert {"mongodb", "archiver_recorder"} <= set(config["deployed_services"])
assert (project / "services" / "mongodb" / "docker-compose.yml.j2").is_file()
assert (project / "services" / "archiver_recorder" / "docker-compose.yml.j2").is_file()
def test_a_profile_without_the_block_gets_neither(self, tmp_path: Path) -> None:
"""Opt-in: nothing about an unarchived project changes."""
project = self._build(tmp_path, "plain")
config = self._config(project)
assert "va_archiver" not in config
assert "mongodb" not in config["deployed_services"]
assert not (project / "services" / "mongodb").exists()
def test_an_attached_project_is_told_where_the_archive_is(self, tmp_path: Path) -> None:
"""It scaffolds no services and so reaches no injector — the connection
block is exactly what it still needs, and the host it names is the one
running the shared store."""
project = self._build(
tmp_path,
"attached",
deploy_services=False,
va_archiver={"host": "archive.example.org", "port_host": 27100},
)
config = self._config(project)
assert config["archiver"]["mongodb_archiver"]["host"] == "archive.example.org"
assert config["archiver"]["mongodb_archiver"]["port"] == 27100
assert config["deployed_services"] == []
assert not (project / "services" / "mongodb").exists()
# ---------------------------------------------------------------------------
# What the build hands `create_project` as `tier`
# ---------------------------------------------------------------------------
class TestTierIsPinnedOnlyWhereTheParadigmAcceptsOne:
"""The `tier` `_render_project` hands `create_project`, per paradigm.
``create_project``'s ``tier`` argument means "the tier the profile PINNED",
not "the tier to use": given ``None`` it derives the paradigm-aware default
itself, and given a value it enforces ``tier_mode_conflict`` against the
paradigm (both boundaries pinned in ``tests/cli/test_templates.py``). So the
build has to hand it a tier only where the paradigm accepts one. ``graph``
is the paradigm that does not — it derives tier 3 like every
non-``in_context`` paradigm, but its store is a service rather than tiered
database files, so no tier selects anything for it and pinning one is a
rule error. A build that handed its own derived tier straight back as a pin
would be refused at the boundary it had just satisfied, and would render
nothing at all.
Two tests, one per side of that rule: dropped for the paradigm that refuses
a tier, and carried through unchanged — overriding the derivation — for the
paradigms that take one.
"""
def _tiers_handed_over(
self,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
name: str,
**profile_keys: object,
) -> tuple[Path, list[int | None]]:
"""Build the control-assistant preset with *profile_keys* stated.
Returns the render and the ``tier`` every render in the build handed
``create_project``. A build renders more than once — the deployment's
own project, its personas, its container copy — and the whole list comes
back rather than the first entry, because one render disagreeing with
the others is the interesting failure.
The argument is read off the bound signature rather than out of
``kwargs``, so a caller that ever passes it positionally is still
recorded rather than silently read as ``None`` — which would make this
spy agree with a build that had stopped passing a tier at all.
"""
import inspect
from click.testing import CliRunner
from osprey.cli.build_cmd import build
from osprey.cli.init_cmd import init
from osprey.cli.templates.manager import TemplateManager
repo = tmp_path / name
runner = CliRunner()
created = runner.invoke(
init,
[
str(repo),
"--preset",
"control-assistant",
"--no-git",
*_set_args(profile_keys),
],
)
assert created.exit_code == 0, created.output
create_project = TemplateManager.create_project
signature = inspect.signature(create_project)
seen: list[int | None] = []
def spy(self: TemplateManager, *args: object, **kwargs: object) -> Path:
bound = signature.bind(self, *args, **kwargs)
bound.apply_defaults()
seen.append(bound.arguments["tier"])
return create_project(self, *args, **kwargs)
monkeypatch.setattr(TemplateManager, "create_project", spy)
rendered = runner.invoke(build, ["--repo", str(repo), "--skip-deps", "--skip-lifecycle"])
assert rendered.exit_code == 0, rendered.output
assert seen, "the build rendered no project at all"
return repo / "build", seen
def test_graph_mode_renders_and_pins_no_tier(
self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""The graph paradigm builds, and nothing in the build pins its tier.
The exit code is half the claim: pinning the derived tier here is not a
subtle mis-selection but a hard refusal, so a regression shows up as a
build that cannot render the paradigm at all.
"""
render, tiers = self._tiers_handed_over(
tmp_path, monkeypatch, "graphed", channel_finder_mode="graph"
)
assert set(tiers) == {None}, (
f"a render pinned a tier for the graph paradigm: {tiers}. graph has no "
"tiered artifacts, so create_project refuses an explicit tier."
)
# The paradigm reached the render: graph flattens no paradigm channel
# database, so the server it declares is the whole of that evidence.
servers = json.loads((render / ".mcp.json").read_text(encoding="utf-8"))["mcpServers"]
assert servers["channel-finder"]["args"] == [
"-m",
"osprey.mcp_server.channel_finder_graph",
]
# What it DOES flatten into that directory is the search index derived
# from the corpus it stages: the file the roster, the explorer and the
# agent's keyword tool read instead of parsing the corpus again. The
# builder itself is pinned in tests/cli/test_build_graph_index.py; here
# it is the render's own inventory that has to name it.
databases = render / "data" / "channel_databases"
staged = sorted(path.name for path in databases.glob("*"))
assert "graph.duckdb" in staged, f"a graph render stages {staged}"
assert not [name for name in staged if name in _PARADIGM_DATABASE_FILENAMES], (
f"a graph render flattened a paradigm channel database: {staged}"
)
# And the manifest does not checksum it: a derived binary carrying its
# own content digest would read as render drift on every rebuild.
manifest = json.loads((render / ".osprey-manifest.json").read_text(encoding="utf-8"))
assert not [name for name in manifest["file_checksums"] if name.endswith(".duckdb")]
def test_an_explicit_tier_overrides_the_derivation_on_a_file_paradigm(
self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A pinned tier still reaches the materializer, and still decides the DB.
``in_context`` with an explicit ``tier: 3`` is the one legal pairing
where the pin and the paradigm's own default disagree — the derivation
would pick tier 1. So this is the case that can tell "the profile's
pin was passed through" from "``create_project`` derived the same
number anyway", which a ``hierarchical`` profile (deriving 3, pinning 3)
cannot.
"""
render, tiers = self._tiers_handed_over(
tmp_path, monkeypatch, "pinned", channel_finder_mode="in_context", tier=3
)
assert set(tiers) == {3}, (
f"the build dropped the profile's explicit tier: {tiers}. Passing None "
"here would have let create_project derive tier 1 from in_context, "
"silently building a smaller channel database than the profile asked for."
)
preset_tier3 = (
Path(__file__).resolve().parents[2]
/ "src"
/ "osprey"
/ "templates"
/ "apps"
/ "control_assistant"
/ "data"
/ "channel_databases"
/ "tiers"
/ "tier3"
/ "in_context.json"
)
flat = render / "data" / "channel_databases" / "in_context.json"
assert flat.read_bytes() == preset_tier3.read_bytes(), (
"the render materialized a channel database that is not the preset's "
"tier-3 in_context source — the pinned tier did not decide the artifact"
)
"""Tests for the osprey build command and build profile system."""
from __future__ import annotations
import json
import subprocess
import tomllib
from pathlib import Path
from textwrap import dedent
import pytest
import yaml
from osprey.cli.build_profile import (
BuildProfile,
EnvConfig,
LifecycleConfig,
LifecycleStep,
McpServerDef,
load_profile,
)
from osprey.cli.channel_finder_cmd import FILE_DATABASE_PARADIGMS
from osprey.errors import BuildProfileError
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def bundle_data_root(bundle: str = "control_assistant") -> Path:
"""The packaged data tree ``osprey init`` copies for *bundle*.
A build sources ``data/`` from the profile's own ``data:`` tree and from
nowhere else, so a test that drives ``TemplateManager.create_project``
directly — without a profile — hands it the packaged tree the materialized
profile would have pointed at.
"""
import osprey
return Path(osprey.__file__).parent / "templates" / "apps" / bundle / "data"
def _create_project(manager, **kwargs) -> Path:
"""``create_project`` with the data tree every render now requires.
A build copies the tree its profile's ``data:`` key names, and that key is
required — nothing falls back to a packaged tree any more. These fixtures
render straight from a bundle rather than from a profile, so they name the
tree that bundle packages.
"""
kwargs.setdefault("data_bundle", "control_assistant")
kwargs.setdefault("data_root", bundle_data_root(kwargs["data_bundle"]))
return manager.create_project(**kwargs)
def materialize_data(profile_dir: Path, bundle: str = "control_assistant") -> Path:
"""Copy *bundle*'s packaged data tree to ``profile_dir/data``, as init does.
For a test that builds through the real verb: the render stages channel
databases, limits and seeds out of the profile's tree, so the tree has to
be a real one.
"""
import shutil
dst = profile_dir / "data"
shutil.copytree(bundle_data_root(bundle), dst, dirs_exist_ok=True)
return dst
# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------
def profile_dir(tmp_path: Path) -> Path:
"""Create a minimal profile directory with a data tree and an MCP server."""
data_dir = tmp_path / "data"
data_dir.mkdir()
(data_dir / "channels.json").write_text('{"pvs": ["SR:DCCT"]}')
mcp_dir = tmp_path / "mcp_servers" / "test_server"
mcp_dir.mkdir(parents=True)
(mcp_dir / "__init__.py").write_text("")
(mcp_dir / "server.py").write_text("# test server")
return tmp_path
def minimal_profile_yaml(profile_dir: Path) -> Path:
"""Write a minimal valid profile YAML and return its path."""
profile = {
"name": "Test Profile",
"data": "data",
"provider": "cborg",
"model": "haiku",
"config": {
"control_system.type": "mock",
},
Xet Storage Details
- Size:
- 138 kB
- Xet hash:
- e89a1145a824fc9e8eb625bf76a4e252bf506cbc2b61ceac2365d7350ccb7cd0
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.