@delorenj/pjangler 1.4.6 → 1.5.3

package/templates/hermes-agent/template/.scripts/lib/profile-config-lock.py

@@ -1,182 +0,0 @@
-#!/usr/bin/env python3
-"""Shared serialization for one Hermes profile's generated configuration.
-
-All code that can read and then rewrite ``config.delta.yaml`` or ``config.yaml``
-must hold this lock from topology validation through commit or rollback.  A
-channel transaction already holds the fleet registry lock before it enters this
-lock; config-only reconcilers never acquire the registry lock.  The only valid
-ordering is therefore::
-
-    fleet registry lock -> profile config lock
-
-Never acquire the fleet registry lock while holding a profile config lock.
-``flock`` ownership is kernel-scoped, so process exit releases the lock even
-though the deliberately persistent lock file remains on disk.
-"""
-
-from __future__ import annotations
-
-import fcntl
-import os
-import pathlib
-import stat
-import time
-from types import TracebackType
-from typing import Self
-
-
-DEFAULT_TIMEOUT_SECONDS = 30.0
-LOCK_TIMEOUT_ENV = "HERMES_PROFILE_CONFIG_LOCK_TIMEOUT_SECONDS"
-TEST_BARRIER_ENV = "PJANGLER_TEST_PROFILE_CONFIG_BARRIER"
-TEST_BARRIER_TIMEOUT_ENV = "PJANGLER_TEST_PROFILE_CONFIG_BARRIER_TIMEOUT_SECONDS"
-TEST_BARRIER_LABEL_ENV = "PJANGLER_TEST_PROFILE_CONFIG_BARRIER_LABEL"
-TEST_LOCK_ATTEMPT_ENV = "PJANGLER_TEST_PROFILE_CONFIG_LOCK_ATTEMPT"
-
-
-class ProfileConfigLockError(RuntimeError):
-    """The profile lock could not be acquired safely."""
-
-
-def lock_path(profile: pathlib.Path) -> pathlib.Path:
-    """Return a lock path that does not require following the profile root."""
-
-    return profile.parent / f".{profile.name}.config.lock"
-
-
-def _timeout_seconds() -> float:
-    raw = os.environ.get(LOCK_TIMEOUT_ENV, str(DEFAULT_TIMEOUT_SECONDS))
-    try:
-        timeout = float(raw)
-    except ValueError as exc:
-        raise ProfileConfigLockError(
-            f"{LOCK_TIMEOUT_ENV} must be a non-negative number"
-        ) from exc
-    if timeout < 0 or timeout != timeout:
-        raise ProfileConfigLockError(
-            f"{LOCK_TIMEOUT_ENV} must be a non-negative number"
-        )
-    return timeout
-
-
-class ProfileConfigLock:
-    """Exclusive, bounded, symlink-safe lock for one profile config pair."""
-
-    def __init__(self, profile: pathlib.Path | str, timeout: float | None = None):
-        self.profile = pathlib.Path(profile)
-        self.path = lock_path(self.profile)
-        self.timeout = _timeout_seconds() if timeout is None else timeout
-        self.fd: int | None = None
-
-    def acquire(self) -> Self:
-        parent = self.profile.parent
-        if parent.is_symlink() or not parent.is_dir():
-            raise ProfileConfigLockError(
-                f"profile parent must be a real directory before locking: {parent}"
-            )
-        if self.path.is_symlink():
-            raise ProfileConfigLockError(
-                f"refusing profile config lock symlink: {self.path}"
-            )
-        flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_CLOEXEC", 0)
-        flags |= getattr(os, "O_NOFOLLOW", 0)
-        try:
-            fd = os.open(self.path, flags, 0o600)
-        except OSError as exc:
-            raise ProfileConfigLockError(
-                f"cannot open profile config lock {self.path}: {exc.strerror or type(exc).__name__}"
-            ) from exc
-        try:
-            if not stat.S_ISREG(os.fstat(fd).st_mode):
-                raise ProfileConfigLockError(
-                    f"profile config lock is not a regular file: {self.path}"
-                )
-            os.fchmod(fd, 0o600)
-            _notify_test_lock_attempt(self.path)
-            deadline = time.monotonic() + self.timeout
-            while True:
-                try:
-                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
-                    break
-                except BlockingIOError as exc:
-                    if time.monotonic() >= deadline:
-                        raise ProfileConfigLockError(
-                            f"timed out waiting for profile config lock: {self.path}"
-                        ) from exc
-                    time.sleep(min(0.05, max(0.0, deadline - time.monotonic())))
-        except BaseException:
-            os.close(fd)
-            raise
-        self.fd = fd
-        return self
-
-    def release(self) -> None:
-        if self.fd is None:
-            return
-        fd, self.fd = self.fd, None
-        try:
-            fcntl.flock(fd, fcntl.LOCK_UN)
-        finally:
-            os.close(fd)
-
-    def __enter__(self) -> Self:
-        return self.acquire()
-
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc: BaseException | None,
-        traceback: TracebackType | None,
-    ) -> None:
-        self.release()
-
-
-def _test_path_from_env(name: str) -> pathlib.Path | None:
-    configured = os.environ.get(name)
-    if not configured:
-        return None
-    if "PYTEST_CURRENT_TEST" not in os.environ:
-        raise ProfileConfigLockError(
-            f"{name} is test-only and requires a pytest process"
-        )
-    path = pathlib.Path(configured)
-    if path.is_symlink() or path.parent.is_symlink() or not path.parent.is_dir():
-        raise ProfileConfigLockError(f"unsafe test profile-config path: {path}")
-    return path
-
-
-def _notify_test_lock_attempt(lock: pathlib.Path) -> None:
-    target = _test_path_from_env(TEST_LOCK_ATTEMPT_ENV)
-    if target is not None:
-        target.write_text(str(lock) + "\n", encoding="utf-8")
-
-
-def test_snapshot_barrier(label: str) -> None:
-    """Pause a test process after its locked snapshot has been captured.
-
-    This hook is inert outside pytest.  It exists so the regression suite can
-    deterministically exercise the stale-snapshot interleaving that motivated
-    this lock without widening the production interface.
-    """
-
-    selected_label = os.environ.get(TEST_BARRIER_LABEL_ENV)
-    if selected_label and selected_label != label:
-        return
-    barrier = _test_path_from_env(TEST_BARRIER_ENV)
-    if barrier is None:
-        return
-    ready = pathlib.Path(f"{barrier}.ready")
-    resume = pathlib.Path(f"{barrier}.resume")
-    ready.write_text(label + "\n", encoding="utf-8")
-    try:
-        timeout = float(os.environ.get(TEST_BARRIER_TIMEOUT_ENV, "15"))
-    except ValueError as exc:
-        raise ProfileConfigLockError(
-            f"{TEST_BARRIER_TIMEOUT_ENV} must be a positive number"
-        ) from exc
-    deadline = time.monotonic() + timeout
-    while not resume.is_file():
-        if time.monotonic() >= deadline:
-            raise ProfileConfigLockError(
-                f"timed out waiting at test profile-config barrier: {barrier}"
-            )
-        time.sleep(0.02)

package/templates/hermes-agent/template/.scripts/lib/profile-config-seed.py

@@ -1,108 +0,0 @@
-#!/usr/bin/env python3
-"""Seed a named profile's override delta under the shared profile lock."""
-
-from __future__ import annotations
-
-import argparse
-import errno
-import importlib.util
-import os
-import pathlib
-import stat
-import tempfile
-
-SEED_CONTENT = (
-    "# Override-only delta for this Hermes profile.\n"
-    "# Merged over ~/.hermes/config.yaml to produce config.yaml (which is GENERATED).\n"
-    "# Empty == identical to the fleet base. Add ONLY what must differ.\n"
-    "{}\n"
-).encode("utf-8")
-
-
-def load_profile_lock_module():
-    source = pathlib.Path(__file__).parent / "profile-config-lock.py"
-    if source.is_symlink() or not source.is_file():
-        raise RuntimeError(
-            f"trusted profile config lock helper is unavailable: {source}"
-        )
-    spec = importlib.util.spec_from_file_location(
-        "pjangler_profile_config_lock", source
-    )
-    if spec is None or spec.loader is None:
-        raise RuntimeError(f"cannot load profile config lock helper: {source}")
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-PROFILE_LOCK = load_profile_lock_module()
-
-
-def fsync_parent(path: pathlib.Path) -> None:
-    unsupported = {errno.EINVAL, getattr(errno, "ENOTSUP", errno.EINVAL), errno.ENOSYS}
-    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
-    try:
-        directory_fd = os.open(path.parent, flags)
-    except OSError as exc:
-        if exc.errno in unsupported:
-            return
-        raise
-    try:
-        try:
-            os.fsync(directory_fd)
-        except OSError as exc:
-            if exc.errno not in unsupported:
-                raise
-    finally:
-        os.close(directory_fd)
-
-
-def seed(profile: pathlib.Path) -> str:
-    with PROFILE_LOCK.ProfileConfigLock(profile):
-        PROFILE_LOCK.test_snapshot_barrier("seed")
-        if profile.is_symlink() or not profile.is_dir():
-            raise RuntimeError(f"profile root must be a real directory: {profile}")
-        target = profile / "config.delta.yaml"
-        if target.is_symlink():
-            raise RuntimeError(f"refusing config delta symlink: {target}")
-        if target.exists():
-            if not target.is_file():
-                raise RuntimeError(f"config delta is not a regular file: {target}")
-            return "exists"
-
-        descriptor, temporary_name = tempfile.mkstemp(
-            prefix=".config.delta.yaml.seed-", dir=profile
-        )
-        temporary = pathlib.Path(temporary_name)
-        try:
-            os.fchmod(descriptor, 0o600)
-            with os.fdopen(descriptor, "wb") as handle:
-                handle.write(SEED_CONTENT)
-                handle.flush()
-                os.fsync(handle.fileno())
-            os.replace(temporary, target)
-            os.chmod(target, stat.S_IRUSR | stat.S_IWUSR)
-            fsync_parent(target)
-        except BaseException:
-            try:
-                temporary.unlink()
-            except FileNotFoundError:
-                pass
-            raise
-        return "seeded"
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--profile", required=True)
-    args = parser.parse_args()
-    try:
-        print(seed(pathlib.Path(args.profile)))
-    except PROFILE_LOCK.ProfileConfigLockError as exc:
-        raise SystemExit(f"profile config seed failed: {exc}") from exc
-    except (OSError, RuntimeError) as exc:
-        raise SystemExit(f"profile config seed failed: {exc}") from exc
-
-
-if __name__ == "__main__":
-    main()

package/templates/hermes-agent/template/.scripts/lib/ticket-provider.sh

@@ -1,199 +0,0 @@
-# shellcheck shell=bash
-# Ticket-provider adapter dispatcher — the single seam between the Scrum Master
-# sentinel engine and a concrete ticket system (Linear | Plane | Trello).
-#
-# The engine NEVER calls a provider directly. It calls `tp <op> [args...]`,
-# which dispatches to providers/<provider>.sh. Repo-root .project.json owns the
-# provider/board binding; role.yaml is only a legacy provider-name fallback.
-#
-# Contract (operations every provider must implement):
-#   resolve                       -> JSON {provider, board_id, board_url}
-#   active_milestone              -> JSON {id, name, state}
-#   list_issues                   -> JSON [ {id,key,title,state,state_type,
-#                                            updated_at,assignee,url,...}, ... ]
-#   get_issue <issue-ref>         -> JSON {id,key,title,description,acceptance,
-#                                          state,state_type,comments:[...],
-#                                          attachments:[...]}
-#   comment <issue-ref> <body>    -> prints comment id
-#   transition <issue-ref> <normalized>
-#                                 -> resolves id/human key, then moves issue; normalized in
-#                                     backlog|unstarted|started|in_review|completed|
-#                                     cancelled
-#   create_board <name> <id> <d>  -> JSON {board_id, board_url}
-#   describe_board <ws> <board_id>
-#                                 -> JSON {board_id, identifier, workspace,
-#                                          name}
-#                                    Read-only lookup against an EXPLICIT
-#                                    workspace, so no ambient binding can send
-#                                    the query elsewhere. `identifier` is
-#                                    whatever the provider itself reports, and
-#                                    is empty when the provider mints none
-#                                    (Trello). Never a locally-computed guess.
-#   create_issue [--if-absent] <title> [desc]
-#                                 -> JSON {issue_id, key, issue_url, created}
-#                                    Files a new ticket on the bound board.
-#                                    NOT idempotent by default (two issues may
-#                                    share a title); --if-absent reuses an exact
-#                                    title match and reports created:false.
-#
-# Each provider reads its credentials from the environment (see providers/*.sh
-# headers) and the board binding from repo-root .project.json.
-
-# Read the human key prefix from the project binding. Plane list_issues exposes
-# sequence_id as a number while people use PREFIX-number; the dispatcher owns
-# that provider-neutral seam so callers never have to know the native id shape.
-tp_project_identifier() {
-  local role_dir
-  role_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
-  python3 - "$role_dir" <<'PY' 2>/dev/null
-import json
-import pathlib
-import sys
-
-start = pathlib.Path(sys.argv[1]).resolve()
-for parent in [start, *start.parents]:
-    manifest = parent / ".project.json"
-    if manifest.is_file():
-        try:
-            provider = json.loads(manifest.read_text()).get("ticket_provider") or {}
-            print(str(provider.get("identifier") or ""))
-        except Exception:
-            print("")
-        break
-else:
-    print("")
-PY
-}
-
-# Resolve an id, provider key, or project-prefixed numeric key against the
-# normalized list contract. Mutating operations fail before reaching a provider
-# if the reference is absent or ambiguous.
-tp_resolve_issue_reference() {
-  local name="$1" impl="$2" reference="$3" identifier issues
-  identifier="$(tp_project_identifier)"
-  issues="$(TICKET_PROVIDER="$name" sh "$impl" list_issues)" || return 1
-  TP_REFERENCE="$reference" TP_IDENTIFIER="$identifier" python3 -c 'import json,os,sys
-reference=os.environ["TP_REFERENCE"].strip(); identifier=os.environ.get("TP_IDENTIFIER", "").strip()
-try:
-    data=json.load(sys.stdin)
-except Exception as exc:
-    raise SystemExit(f"tp: could not resolve issue reference {reference!r}: list_issues returned invalid JSON ({exc})")
-rows=data if isinstance(data,list) else data.get("results", []) if isinstance(data,dict) else []
-want=reference.casefold(); matches=[]
-for issue in rows:
-    native=str(issue.get("id") or "").strip(); key=str(issue.get("key") or "").strip()
-    aliases={native.casefold(), key.casefold()}
-    if identifier and key.isdigit():
-        aliases.add(f"{identifier}-{key}".casefold())
-    if native and want in aliases:
-        matches.append(native)
-matches=list(dict.fromkeys(matches))
-if len(matches) != 1:
-    detail="not found" if not matches else "ambiguous"
-    raise SystemExit(f"tp: could not resolve issue reference {reference!r}: {detail}")
-print(matches[0])' <<EOF
-$issues
-EOF
-}
-
-# Resolve the provider name: explicit env wins, then repo-root .project.json
-# (the SOT), then role.yaml (self-parsed so this works even when _lib.sh /
-# yaml_get is not loaded), then default.
-tp_provider_name() {
-  if [ -n "${TICKET_PROVIDER:-}" ]; then
-    printf '%s\n' "$TICKET_PROVIDER"
-    return 0
-  fi
-  # .project.json ticket_provider.type — walk up from the role dir to repo root.
-  local role_dir
-  role_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)"
-  if [ -n "$role_dir" ]; then
-    local sot_type
-    sot_type="$(python3 - "$role_dir" <<'PY' 2>/dev/null
-import sys, json, pathlib
-start = pathlib.Path(sys.argv[1]).resolve()
-for parent in [start, *start.parents]:
-    f = parent / ".project.json"
-    if f.is_file():
-        try:
-            print((json.loads(f.read_text()).get("ticket_provider") or {}).get("type", ""))
-        except Exception:
-            print("")
-        break
-PY
-)"
-    [ -n "$sot_type" ] && { printf '%s\n' "$sot_type"; return 0; }
-  fi
-  local role_yaml
-  role_yaml="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." 2>/dev/null && pwd)/role.yaml"
-  if [ -f "$role_yaml" ]; then
-    local name
-    name="$(python3 - "$role_yaml" <<'PY'
-import re, sys, pathlib
-t = pathlib.Path(sys.argv[1]).read_text()
-m = re.search(r'(?ms)^ticket_provider:\s*$(.*?)(?=^\S)', t + "\n\x00")
-block = m.group(1) if m else ""
-mm = re.search(r'(?m)^\s*name:\s*"?([^"\n]*)"?\s*$', block)
-print(mm.group(1).strip() if mm else "")
-PY
-)"
-    [ -n "$name" ] && { printf '%s\n' "$name"; return 0; }
-  fi
-  printf 'linear\n'
-}
-
-# Directory holding provider implementations (sibling of this lib).
-tp_providers_dir() {
-  local here
-  here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  printf '%s/../providers\n' "$here"
-}
-
-# Dispatch one operation to the active provider.
-tp() {
-  local op="${1:-}"; shift || true
-  [ -n "$op" ] || { echo "tp: missing operation" >&2; return 2; }
-
-  # Reject blank references before provider discovery or list_issues. Besides
-  # being invalid input, an empty value can equal a provider's missing `key`
-  # field and must never become authority to read or mutate that issue.
-  case "$op" in
-    get_issue|comment|transition)
-      [ "$#" -ge 1 ] || { echo "tp: $op requires a non-blank issue reference" >&2; return 2; }
-      if [[ "$1" =~ ^[[:space:]]*$ ]]; then
-        echo "tp: $op requires a non-blank issue reference" >&2
-        return 2
-      fi
-      ;;
-  esac
-
-  local name impl
-  name="$(tp_provider_name)"
-  impl="$(tp_providers_dir)/${name}.sh"
-
-  if [ ! -f "$impl" ]; then
-    echo "tp: unknown ticket provider '$name' (no $impl)" >&2
-    return 2
-  fi
-
-  case "$op" in
-    get_issue|comment|transition)
-      local reference native_id
-      reference="$1"; shift
-      native_id="$(tp_resolve_issue_reference "$name" "$impl" "$reference")" || return 1
-      set -- "$native_id" "$@"
-      ;;
-  esac
-
-  TICKET_PROVIDER="$name" sh "$impl" "$op" "$@"
-}
-
-# Normalized states the engine reasons in. Adapters map these to provider terms.
-TP_STATES="backlog unstarted started in_review completed cancelled"
-
-tp_is_valid_state() {
-  case " $TP_STATES " in
-    *" $1 "*) return 0 ;;
-    *) return 1 ;;
-  esac
-}