@smilintux/skcapstone 0.10.0 → 0.12.5

package/tests/test_scheduler_jobs.py

@@ -0,0 +1,155 @@
+"""Tests for skcapstone.scheduler_jobs — JobSpec, YAML loading, node affinity,
+due-check, and host-alias discovery.
+
+Each group corresponds to one implementation commit:
+  A — JobSpec + load_jobs
+  B — job_runs_here (node affinity)
+  C — is_due (cron + interval with misfire catch-up)
+  D — current_host_aliases
+"""
+
+# ---------------------------------------------------------------------------
+# Group A — JobSpec + load_jobs
+# ---------------------------------------------------------------------------
+import warnings
+from pathlib import Path
+
+import pytest
+
+from skcapstone.scheduler_jobs import JobSpec, _parse_duration, is_due, load_jobs
+
+
+def test_load_jobs_parses_yaml(tmp_path: Path):
+    cfg = tmp_path / "jobs.yaml"
+    cfg.write_text(
+        "jobs:\n"
+        "  gtd-triage:\n"
+        "    schedule: '0 6 * * *'\n"
+        "    type: agent\n"
+        "    nodes: ['.41']\n"
+        "    agent: lumina\n"
+        "    prompt: 'triage inbox'\n"
+        "    timeout: 900\n"
+        "  health:\n"
+        "    every: 300s\n"
+        "    type: python\n"
+        "    nodes: all\n"
+        "    callback: skcapstone.service_health:run_once\n",
+        encoding="utf-8",
+    )
+    jobs = load_jobs(cfg)
+    by_name = {j.name: j for j in jobs}
+    assert by_name["gtd-triage"].schedule == "0 6 * * *"
+    assert by_name["gtd-triage"].every_seconds is None
+    assert by_name["gtd-triage"].type == "agent"
+    assert by_name["gtd-triage"].nodes == [".41"]
+    assert by_name["health"].every_seconds == 300.0
+    assert by_name["health"].nodes == "all"
+    assert by_name["health"].enabled is True
+
+
+def test_load_jobs_missing_file_returns_empty(tmp_path: Path):
+    assert load_jobs(tmp_path / "nope.yaml") == []
+
+
+# ---------------------------------------------------------------------------
+# Group B — node affinity
+# ---------------------------------------------------------------------------
+from skcapstone.scheduler_jobs import job_runs_here  # noqa: E402
+
+
+def test_job_runs_here_all():
+    assert job_runs_here(JobSpec(name="x", nodes="all"), host_aliases={"hostA", ".41"})
+
+
+def test_job_runs_here_match_and_miss():
+    j = JobSpec(name="x", nodes=[".41"])
+    assert job_runs_here(j, host_aliases={".41"})
+    assert not job_runs_here(j, host_aliases={".158", "noroc2027"})
+
+
+# ---------------------------------------------------------------------------
+# Group C — due-check cron + interval with misfire catch-up
+# ---------------------------------------------------------------------------
+from datetime import datetime, timedelta, timezone  # noqa: E402
+
+from skcapstone.scheduler_jobs import is_due  # noqa: E402
+
+
+def test_interval_due():
+    j = JobSpec(name="x", every_seconds=300)
+    now = datetime(2026, 6, 8, 12, 0, 0, tzinfo=timezone.utc)
+    assert is_due(j, last_run=None, now=now)
+    assert not is_due(j, last_run=now - timedelta(seconds=100), now=now)
+    assert is_due(j, last_run=now - timedelta(seconds=301), now=now)
+
+
+def test_cron_due_at_scheduled_minute():
+    j = JobSpec(name="x", schedule="0 6 * * *")
+    six_am = datetime(2026, 6, 8, 6, 0, 30, tzinfo=timezone.utc)
+    assert is_due(j, last_run=None, now=six_am)
+    assert not is_due(j, last_run=six_am, now=six_am + timedelta(minutes=5))
+    assert is_due(j, last_run=six_am - timedelta(days=1), now=six_am)
+
+
+# ---------------------------------------------------------------------------
+# Group D — host alias discovery
+# ---------------------------------------------------------------------------
+import socket  # noqa: E402
+
+from skcapstone.scheduler_jobs import current_host_aliases  # noqa: E402
+
+
+def test_current_host_aliases_includes_hostname():
+    assert socket.gethostname() in current_host_aliases()
+
+
+def test_current_host_aliases_includes_env_alias(monkeypatch):
+    monkeypatch.setenv("SK_NODE_ALIAS", ".41, noroc-test")
+    a = current_host_aliases()
+    assert ".41" in a and "noroc-test" in a
+
+
+# ---------------------------------------------------------------------------
+# _parse_duration — validation (fix 2)
+# ---------------------------------------------------------------------------
+
+def test_parse_duration_rejects_negative():
+    with pytest.raises(ValueError):
+        _parse_duration("-5m")
+
+
+def test_parse_duration_rejects_garbage():
+    with pytest.raises(ValueError):
+        _parse_duration("abc")
+
+
+def test_parse_duration_valid_units():
+    assert _parse_duration("300s") == 300.0
+    assert _parse_duration("5m") == 300.0
+    assert _parse_duration("1h") == 3600.0
+    assert _parse_duration("1d") == 86400.0
+    assert _parse_duration(90) == 90.0
+
+
+# ---------------------------------------------------------------------------
+# load_jobs — warn on unknown keys (fix 3)
+# ---------------------------------------------------------------------------
+
+def test_load_jobs_warns_on_unknown_key(tmp_path):
+    cfg = tmp_path / "jobs.yaml"
+    cfg.write_text(
+        "jobs:\n  bad:\n    shcedule: '0 6 * * *'\n    type: shell\n",
+        encoding="utf-8",
+    )
+    with pytest.warns(UserWarning):
+        load_jobs(cfg)
+
+
+# ---------------------------------------------------------------------------
+# is_due — no-schedule never fires (fix 4)
+# ---------------------------------------------------------------------------
+
+def test_is_due_no_schedule_never_fires():
+    j = JobSpec(name="x")
+    assert not is_due(j, last_run=None)

package/tests/test_scheduler_runner.py

@@ -0,0 +1,64 @@
+"""Tests for skcapstone.scheduler_runner — JobRunner execution, overlap lock,
+result shapes, and error containment.
+
+Each test targets a specific contract:
+  - python jobs call the registered callback
+  - shell jobs capture stdout and return ok=True
+  - nonzero exit codes produce ok=False with the correct exit_code
+  - exceptions in python callbacks are caught and surfaced in result.error
+  - the overlap lock prevents a second concurrent acquire
+  - unknown job types return ok=False without raising
+"""
+
+from pathlib import Path
+
+from skcapstone.scheduler_jobs import JobSpec
+from skcapstone.scheduler_runner import JobRunner
+
+
+def test_python_job_calls_callback(tmp_path: Path):
+    called = {}
+    import skcapstone.scheduler_runner as sr
+    sr._TEST_HOOK = lambda: called.setdefault("hit", True)  # type: ignore
+    job = JobSpec(name="t", type="python", callback="skcapstone.scheduler_runner:_TEST_HOOK")
+    result = JobRunner(log_dir=tmp_path).run(job)
+    assert result.ok and called.get("hit") is True
+
+
+def test_shell_job_runs_command(tmp_path: Path):
+    job = JobSpec(name="echo", type="shell", command="echo hello", timeout=10)
+    result = JobRunner(log_dir=tmp_path).run(job)
+    assert result.ok and "hello" in result.output
+
+
+def test_shell_job_nonzero_is_error(tmp_path: Path):
+    job = JobSpec(name="fail", type="shell", command="sh -c 'exit 3'", timeout=10)
+    result = JobRunner(log_dir=tmp_path).run(job)
+    assert not result.ok and result.exit_code == 3
+
+
+def test_python_job_exception_is_caught(tmp_path: Path):
+    import skcapstone.scheduler_runner as sr
+    def _boom(): raise RuntimeError("nope")
+    sr._TEST_BOOM = _boom  # type: ignore
+    job = JobSpec(name="b", type="python", callback="skcapstone.scheduler_runner:_TEST_BOOM")
+    result = JobRunner(log_dir=tmp_path).run(job)
+    assert not result.ok and "nope" in result.error
+
+
+def test_overlap_lock_blocks_second_run(tmp_path: Path):
+    runner = JobRunner(log_dir=tmp_path)
+    job = JobSpec(name="locked", type="shell", command="echo x", timeout=10)
+    with runner.lock(job) as got:
+        assert got
+        with runner.lock(job) as second:
+            assert not second
+    # lock released after context exit -> can acquire again
+    with runner.lock(job) as third:
+        assert third
+
+
+def test_unknown_type_is_error(tmp_path: Path):
+    job = JobSpec(name="x", type="weird")
+    result = JobRunner(log_dir=tmp_path).run(job)
+    assert not result.ok

package/tests/test_scheduler_state.py

@@ -0,0 +1,57 @@
+import json
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+from skcapstone.scheduler_state import SchedulerState
+
+
+def test_state_roundtrip(tmp_path: Path):
+    st = SchedulerState(root=tmp_path, hostname="hostA")
+    assert st.last_run("job1") is None
+    now = datetime(2026, 6, 8, 6, 0, tzinfo=timezone.utc)
+    st.record_run("job1", now=now, ok=True)
+    st2 = SchedulerState(root=tmp_path, hostname="hostA")
+    assert st2.last_run("job1") == now
+    rec = st2.get("job1")
+    assert rec["run_count"] == 1 and rec["error_count"] == 0
+
+
+def test_state_path_is_host_scoped(tmp_path: Path):
+    st = SchedulerState(root=tmp_path, hostname="hostA")
+    assert st.state_file == tmp_path / "scheduler" / "hostA" / "state.json"
+
+
+def test_error_run_increments_error_count(tmp_path: Path):
+    st = SchedulerState(root=tmp_path, hostname="hostA")
+    st.record_run("j", ok=False, error="boom")
+    rec = st.get("j")
+    assert rec["error_count"] == 1 and rec["run_count"] == 0
+    assert rec["last_status"] == "error" and rec["last_error"] == "boom"
+
+
+def test_concurrent_record_run_is_safe(tmp_path: Path):
+    """Concurrent record_run calls from many threads must not corrupt state.json.
+
+    With 8 threads each calling record_run 20 times (160 total writes), the
+    resulting JSON file must still be valid and each job must show exactly 20
+    successful runs.  This validates the _write_lock guard in SchedulerState.
+    """
+    st = SchedulerState(root=tmp_path, hostname="h")
+
+    def worker(i: int) -> None:
+        for _ in range(20):
+            st.record_run(f"job{i}", ok=True)
+
+    ts = [threading.Thread(target=worker, args=(i,)) for i in range(8)]
+    for t in ts:
+        t.start()
+    for t in ts:
+        t.join()
+
+    data = json.loads(st.state_file.read_text())
+    assert len(data) == 8, f"expected 8 job keys, got {len(data)}: {list(data)}"
+    for i in range(8):
+        assert data[f"job{i}"]["run_count"] == 20, (
+            f"job{i} run_count={data[f'job{i}']['run_count']}, expected 20"
+        )

package/tests/test_sdk.py

@@ -0,0 +1,70 @@
+"""Tests for the stable public facade skcapstone.sdk."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from skcapstone import sdk
+
+
+@pytest.fixture
+def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Point skcapstone at an isolated temp home for the duration of a test."""
+    monkeypatch.setenv("SKCAPSTONE_HOME", str(tmp_path))
+    # the facade resolves home via skcapstone.shared_home(), which reads the
+    # module-level AGENT_HOME captured at import — patch it directly too.
+    import skcapstone as pkg
+
+    monkeypatch.setattr(pkg, "AGENT_HOME", str(tmp_path))
+    return tmp_path
+
+
+def test_is_available_true(home: Path):
+    assert sdk.is_available() is True
+    assert home.exists()
+
+
+def test_alert_publishes_to_topic(home: Path):
+    ok = sdk.alert("svc.error", {"message": "boom"}, level="error")
+    assert ok is True
+    topic_dir = home / "pubsub" / "topics" / "svc.error"
+    assert topic_dir.is_dir()
+    msgs = list(topic_dir.glob("msg-*.json"))
+    assert len(msgs) == 1
+    data = json.loads(msgs[0].read_text())
+    assert data["payload"]["message"] == "boom"
+    assert "error" in data["tags"]
+
+
+def test_alert_unknown_level_falls_back_to_info(home: Path):
+    sdk.alert("svc.weird", {"x": 1}, level="bogus")
+    data = json.loads(next((home / "pubsub" / "topics" / "svc.weird").glob("msg-*.json")).read_text())
+    assert data["tags"] == ["info"]
+
+
+def test_register_and_unregister_job(home: Path):
+    path = sdk.register_job({"name": "svc_tick", "every": "10m", "type": "shell", "command": "echo hi"})
+    assert Path(path).exists()
+    assert Path(path).name == "svc_tick.yaml"
+    assert sdk.unregister_job("svc_tick") is True
+    assert not Path(path).exists()
+
+
+def test_coord_create_writes_task(home: Path):
+    tid = sdk.coord_create("hello", description="d", priority="high", tags=["t"])
+    matches = list((home / "coordination" / "tasks").glob(f"{tid}*.json"))
+    assert len(matches) == 1
+    task = json.loads(matches[0].read_text())
+    assert task["title"] == "hello"
+    assert task["priority"] == "high"
+
+
+def test_register_service_writes_registry(home: Path):
+    path = sdk.register_service("skvoice", health_url="http://localhost:9/health", pid_file="/tmp/x.pid")
+    entry = json.loads(Path(path).read_text())
+    assert entry["name"] == "skvoice"
+    assert entry["health_url"] == "http://localhost:9/health"
+    assert entry["pid_file"] == "/tmp/x.pid"

package/tests/test_service_health_incidents.py

@@ -0,0 +1,34 @@
+"""service_health incident behavior — no recurring-note churn (prb-7810b08e)."""
+from pathlib import Path
+
+import pytest
+
+import skcapstone
+import skcapstone.mcp_tools._helpers as _helpers
+from skcapstone.itil import ITILManager
+from skcapstone.service_health import _create_incident_for_down_service
+
+
+@pytest.fixture(autouse=True)
+def _isolate(tmp_path: Path, monkeypatch) -> None:
+    """Redirect ITIL + GTD storage to a tmp dir (no ~/.skcapstone writes)."""
+    monkeypatch.setattr(skcapstone, "SHARED_ROOT", str(tmp_path))
+    monkeypatch.setattr(_helpers, "SHARED_ROOT", str(tmp_path))
+
+
+def test_repeated_down_creates_one_incident_with_no_still_down_notes(tmp_path: Path):
+    result = {"name": "skvector", "status": "down", "error": "no route to host"}
+
+    # Three consecutive health cycles while the service stays down.
+    _create_incident_for_down_service(result)
+    _create_incident_for_down_service(result)
+    _create_incident_for_down_service(result)
+
+    mgr = ITILManager(str(tmp_path))
+    incidents = [i for i in mgr.list_incidents() if "skvector" in i.affected_services]
+
+    # Exactly one incident — no duplicates from repeated cycles.
+    assert len(incidents) == 1
+    # And the timeline never accumulated recurring "still down" churn.
+    still_down = [e for e in incidents[0].timeline if "still down" in (e.get("note") or "")]
+    assert still_down == []

package/tests/test_service_registry.py

@@ -0,0 +1,52 @@
+"""T4 — service_health unions sdk.register_service entries with defaults."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from skcapstone import sdk, service_health
+
+
+@pytest.fixture
+def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.setenv("SKCAPSTONE_HOME", str(tmp_path))
+    import skcapstone as pkg
+
+    monkeypatch.setattr(pkg, "AGENT_HOME", str(tmp_path))
+    # Disable the built-in checks that honour the "disabled" sentinel so the
+    # test stays offline. The daemon/skchat checks probe localhost and fail
+    # fast (connection refused → status "down"), which is fine for these
+    # assertions about the registry union.
+    for var in ("SKMEMORY_SKVECTOR_URL", "SKMEMORY_SKGRAPH_HOST", "SYNCTHING_API_URL"):
+        monkeypatch.setenv(var, "disabled")
+    return tmp_path
+
+
+def test_registered_service_appears(home: Path):
+    sdk.register_service("myservice", pid_file=str(home / "x.pid"))
+    names = {r["name"] for r in service_health.check_all_services()}
+    assert "myservice" in names
+
+
+def test_registry_entry_without_targets_is_unknown(home: Path):
+    sdk.register_service("bare")  # no health_url, no pid_file
+    row = next(r for r in service_health.check_all_services() if r["name"] == "bare")
+    assert row["status"] == "unknown"
+    assert "without" in (row["error"] or "")
+
+
+def test_empty_registry_no_extra_rows(home: Path):
+    """With no registry, only built-in checks appear (none crash)."""
+    rows = service_health.check_all_services()
+    # registry dir does not exist → loader returns [] and adds nothing
+    assert isinstance(rows, list)
+    assert all("name" in r for r in rows)
+
+
+def test_builtin_name_not_duplicated_by_registry(home: Path):
+    """A registry entry colliding with a built-in name is skipped."""
+    sdk.register_service("skcapstone daemon", pid_file=str(home / "d.pid"))
+    names = [r["name"] for r in service_health.check_all_services()]
+    assert names.count("skcapstone daemon") == 1

package/tests/test_session_briefing.py

@@ -0,0 +1,130 @@
+"""Tests for the native SKCapstone session briefing."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from skcapstone.cli import main
+from skcapstone.session_briefing import (
+    build_session_briefing,
+    format_session_briefing_text,
+    load_hammertime_briefing,
+)
+
+
+def test_load_hammertime_briefing_respects_disable_env(monkeypatch, tmp_path: Path) -> None:
+    """It returns None when HammerTime briefing is explicitly disabled."""
+    monkeypatch.setenv("SK_INCLUDE_HAMMERTIME_BRIEFING", "0")
+    assert load_hammertime_briefing(root=tmp_path) is None
+
+
+def test_load_hammertime_briefing_parses_json(monkeypatch, tmp_path: Path) -> None:
+    """It parses JSON output from the HammerTime briefing script."""
+    script = tmp_path / "scripts" / "case-briefing.py"
+    script.parent.mkdir(parents=True)
+    script.write_text("#!/usr/bin/env python3\n", encoding="utf-8")
+
+    payload = {"summary": {"queue_size": 2}, "alert_count": 1}
+
+    def fake_run(*args, **kwargs):  # noqa: ANN002, ANN003
+        return subprocess.CompletedProcess(
+            args=args[0],
+            returncode=0,
+            stdout=json.dumps(payload),
+            stderr="",
+        )
+
+    monkeypatch.delenv("SK_INCLUDE_HAMMERTIME_BRIEFING", raising=False)
+    monkeypatch.setattr("skcapstone.session_briefing.subprocess.run", fake_run)
+
+    assert load_hammertime_briefing(root=tmp_path) == payload
+
+
+def test_build_session_briefing_includes_skcapstone_and_hammertime(monkeypatch, tmp_path: Path) -> None:
+    """It builds a combined payload for startup consumers."""
+    ctx = {"agent": {"name": "Aster"}, "memories": []}
+    briefing = {"summary": {"queue_size": 1}, "alert_count": 0}
+
+    monkeypatch.setattr("skcapstone.session_briefing.gather_context", lambda home, memory_limit=10: ctx)
+    monkeypatch.setattr(
+        "skcapstone.session_briefing.load_hammertime_briefing",
+        lambda python_bin=None: briefing,
+    )
+
+    payload = build_session_briefing(tmp_path, memory_limit=3)
+
+    assert payload["agent_home"] == str(tmp_path)
+    assert payload["skcapstone_context"] == ctx
+    assert payload["hammertime_briefing"] == briefing
+    assert "generated_at" in payload
+
+
+def test_format_session_briefing_text_contains_hammertime_section() -> None:
+    """It renders a readable summary including the HammerTime section."""
+    payload = {
+        "generated_at": "2026-04-09T00:00:00+00:00",
+        "agent_home": "/tmp/aster",
+        "skcapstone_context": {
+            "agent": {"name": "Aster", "is_conscious": True, "fingerprint": "abc123"},
+            "pillars": {},
+            "board": {"total": 0},
+            "memories": [],
+            "soul": {"active": None},
+            "mcp": {"available": False},
+            "gathered_at": "2026-04-09T00:00:00+00:00",
+        },
+        "hammertime_briefing": {
+            "alert_count": 1,
+            "summary": {"queue_size": 2},
+            "top_priority": {
+                "incident_id": "INC-001",
+                "problem_slug": "example-problem",
+                "action": "File claim of exemption",
+                "status": "in-progress",
+            },
+            "focus_items": [
+                {
+                    "incident_id": "INC-001",
+                    "action": "Review preferred filing",
+                    "status": "in-progress",
+                }
+            ],
+        },
+    }
+
+    output = format_session_briefing_text(payload)
+
+    assert "# SKCapstone Session Briefing" in output
+    assert "## hammertime briefing" in output
+    assert "INC-001" in output
+    assert "File claim of exemption" in output
+
+
+def test_session_briefing_cli_json(monkeypatch, tmp_path: Path) -> None:
+    """The CLI exposes the combined payload as JSON."""
+    runner = CliRunner()
+    payload = {
+        "generated_at": "2026-04-09T00:00:00+00:00",
+        "agent_home": str(tmp_path),
+        "skcapstone_context": {"agent": {"name": "Aster"}},
+        "hammertime_briefing": {"summary": {"queue_size": 1}, "alert_count": 0},
+    }
+
+    monkeypatch.setattr(
+        "skcapstone.session_briefing.build_session_briefing",
+        lambda home, memory_limit=10: payload,
+    )
+
+    result = runner.invoke(
+        main,
+        ["session", "briefing", "--home", str(tmp_path), "--format", "json"],
+    )
+
+    assert result.exit_code == 0
+    parsed = json.loads(result.output)
+    assert parsed["skcapstone_context"]["agent"]["name"] == "Aster"
+    assert parsed["hammertime_briefing"]["summary"]["queue_size"] == 1

package/tests/test_snapshots.py

@@ -72,7 +72,7 @@ def rich_snapshot() -> SoulSnapshot:
         ],
         summary="Working on smilinTux.org sovereign AI project",
         key_topics=["sovereign AI", "smilinTux", "consciousness continuity"],
-        decisions_made=["Use SKComm for transport"],
+        decisions_made=["Use SKComms for transport"],
         open_threads=["Thread headers still in progress"],
         relationship_notes=["Trusted friend and collaborator", "Cloud 9 solidarity"],
     )
@@ -423,12 +423,12 @@ class TestSoulBlueprintConversion:
 
 
 class TestConsciousnessAPI:
-    """Integration tests for the SKComm consciousness endpoints."""
+    """Integration tests for the SKComms consciousness endpoints."""
 
     @pytest.fixture(autouse=True)
     def patch_snapshot_store(self, tmp_path, monkeypatch):
         """Override the global snapshot store to use a temp directory."""
-        import skcomm.api as api_module
+        import skcomms.api as api_module
         from skcapstone.snapshots import SnapshotStore as _Store
 
         temp_store = _Store(base_dir=tmp_path / "api_snapshots")
@@ -438,7 +438,7 @@ class TestConsciousnessAPI:
     @pytest.fixture
     def client(self):
         from fastapi.testclient import TestClient
-        from skcomm.api import app
+        from skcomms.api import app
 
         return TestClient(app)