Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
  jcwalker3andClaude Opus 4.8
|
08061b7b8a |
@@ -1,892 +0,0 @@
|
||||
"""ARCH-01 Foundation Slice A — atomic platform installation + authority kernel (#822).
|
||||
|
||||
Parents: #820, #821. **First implementation leaf of the ARCH-01 program.**
|
||||
|
||||
This module implements the smallest executable ARCH-01 foundation:
|
||||
|
||||
* a connection-bound authenticated actor context (``cp_actor_*`` /
|
||||
``cp_operation_mode`` / ``cp_context_epoch`` SQLite scalar functions that SQL
|
||||
may *read* but can never *set* — ``[TRUSTED-SERVICE]`` authenticity);
|
||||
* an immutable authority-dominance lattice with an exact seeded tuple set
|
||||
(``[SCHEMA]``);
|
||||
* the principal-equivalence root (a class exists *before* its first principal;
|
||||
``principals.current_class_id`` is ``NOT NULL``; ``[SCHEMA]``);
|
||||
* a single-transaction platform installation that seeds the initial
|
||||
``platform.bootstrap`` grant and an immutable ``installed`` marker, validated
|
||||
by a fail-closed ``install_state`` ``BEFORE INSERT`` trigger (``[SCHEMA]``).
|
||||
|
||||
Everything else in the ARCH-01/02/04 program (evidence stores, repository
|
||||
bindings, workspaces, PostgreSQL parity, full grant succession, full principal
|
||||
merge) is out of scope here and tracked in its own issue — see #822 §5/§17.
|
||||
|
||||
**Readiness / production posture.** This subsystem is *disabled by default*.
|
||||
Nothing in the running MCP server imports or enables it. It becomes a security
|
||||
boundary only once its readiness checks (the ACs in #822) pass in the target
|
||||
environment. Instantiating :class:`PlatformKernel` creates an isolated SQLite
|
||||
database and never touches the operational control-plane store.
|
||||
|
||||
Enforcement classification (per #820 vocabulary):
|
||||
|
||||
* ``[TRUSTED-SERVICE]`` — actor-context authenticity: the scalar functions are
|
||||
registered by the trusted Python process; SQL cannot define or redefine them.
|
||||
* ``[SCHEMA]`` — fail-closed aborts, the dominance/immutability/NOT-NULL-class/
|
||||
last-active-grant invariants, enforced by CHECK/FK/trigger.
|
||||
* ``[RUNTIME-ADAPTER]`` — *none* in this slice.
|
||||
|
||||
SQLite-first. ``BEGIN IMMEDIATE`` serializes concurrent installs and concurrent
|
||||
grant/revoke on the singleton invariant row. PostgreSQL parity is a distinct
|
||||
issue (#827); this module does **not** claim it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import sqlite3
|
||||
import threading
|
||||
from contextlib import contextmanager
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime, timezone
|
||||
from typing import Iterator, Optional
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Closed enumerations (#822 §4).
|
||||
# --------------------------------------------------------------------------- #
|
||||
|
||||
ACTOR_KINDS = ("operator", "supervisor", "service", "installer")
|
||||
OPERATION_MODES = ("normal", "install", "merge", "internal_service")
|
||||
|
||||
# Exact seeded authority-dominance tuple set (#822 §4). This set is normative:
|
||||
# the install-state trigger rejects any missing, additional, or malformed tuple.
|
||||
DOMINANCE_TUPLES = (
|
||||
("platform.bootstrap", "platform.bootstrap"),
|
||||
("platform.bootstrap", "project.admin"),
|
||||
("platform.bootstrap", "supervisor.root.establish"),
|
||||
("supervisor.root", "supervisor.register"),
|
||||
("supervisor.root", "supervisor.verify"),
|
||||
("supervisor.root", "supervisor.recover"),
|
||||
)
|
||||
|
||||
# The distinguished operator-key issuer seeded during install.
|
||||
DISTINGUISHED_ISSUER_KIND = "operator-key"
|
||||
DISTINGUISHED_ISSUER_ID = "platform.bootstrap.operator-key"
|
||||
|
||||
# Structured result codes (#822 §10).
|
||||
INSTALLED = "INSTALLED"
|
||||
ALREADY_INSTALLED = "ALREADY_INSTALLED"
|
||||
INVALID_ACTOR_CONTEXT = "INVALID_ACTOR_CONTEXT"
|
||||
INVALID_BOOTSTRAP_STATE = "INVALID_BOOTSTRAP_STATE"
|
||||
DOMINANCE_SET_MISMATCH = "DOMINANCE_SET_MISMATCH"
|
||||
AUTHORIZATION_DENIED = "AUTHORIZATION_DENIED"
|
||||
CONCURRENT_INSTALLATION_LOST = "CONCURRENT_INSTALLATION_LOST"
|
||||
|
||||
# Required audit events (#822 §14).
|
||||
EVT_PLATFORM_INSTALLED = "platform_installed"
|
||||
EVT_GRANT_CREATED = "platform_grant_created"
|
||||
EVT_GRANT_REVOKED = "platform_grant_revoked"
|
||||
EVT_PRINCIPAL_REGISTERED = "principal_registered"
|
||||
|
||||
SCHEMA_VERSION = 1
|
||||
|
||||
DB_PATH_ENV = "ARCH01_PLATFORM_DB"
|
||||
|
||||
|
||||
class PlatformKernelError(RuntimeError):
|
||||
"""Base class for structured, code-bearing kernel failures."""
|
||||
|
||||
def __init__(self, code: str, message: str = "") -> None:
|
||||
super().__init__(message or code)
|
||||
self.code = code
|
||||
|
||||
|
||||
class ActorContextError(PlatformKernelError):
|
||||
"""Raised when a mutation is attempted without a valid actor context."""
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Schema (#822 §6). Tables + fail-closed triggers.
|
||||
#
|
||||
# Every *mutating* trigger opens with the actor protocol: read the context
|
||||
# epoch, read the actor fields, and abort unless the context is present,
|
||||
# non-null, mode/kind well-formed, and epoch-consistent with the active
|
||||
# transaction. The scalar functions ``cp_*`` are registered from Python only;
|
||||
# SQL has no statement that can set them, which is the trusted-service boundary.
|
||||
# --------------------------------------------------------------------------- #
|
||||
|
||||
_ACTOR_KINDS_SQL = ", ".join("'%s'" % k for k in ACTOR_KINDS)
|
||||
_OP_MODES_SQL = ", ".join("'%s'" % m for m in OPERATION_MODES)
|
||||
|
||||
# Actor-protocol predicate: TRUE when the context is INVALID and the trigger
|
||||
# must abort. ``cp_actor_context_valid()`` folds "present + non-expired +
|
||||
# live-epoch == bound-epoch" (the read/re-read epoch equality of #822 §4) into
|
||||
# one trusted-service answer; the remaining reads assert field well-formedness.
|
||||
_INVALID_ACTOR = (
|
||||
"cp_actor_context_valid() IS NOT 1 "
|
||||
"OR cp_context_epoch() IS NULL "
|
||||
"OR cp_actor_principal() IS NULL "
|
||||
"OR cp_actor_kind() NOT IN (%s) "
|
||||
"OR cp_operation_mode() NOT IN (%s)" % (_ACTOR_KINDS_SQL, _OP_MODES_SQL)
|
||||
)
|
||||
|
||||
_ACTOR_GUARD = (
|
||||
"SELECT CASE WHEN (%s) "
|
||||
"THEN RAISE(ABORT, 'INVALID_ACTOR_CONTEXT') END;" % _INVALID_ACTOR
|
||||
)
|
||||
|
||||
# require_installed: abort a privileged mutation when there is no install
|
||||
# marker and we are not currently installing (#822 §4).
|
||||
_REQUIRE_INSTALLED = (
|
||||
"SELECT CASE WHEN ((SELECT COUNT(*) FROM install_state) = 0 "
|
||||
"AND cp_operation_mode() <> 'install') "
|
||||
"THEN RAISE(ABORT, 'NOT_INSTALLED') END;"
|
||||
)
|
||||
|
||||
_SCHEMA_SQL = f"""
|
||||
PRAGMA foreign_keys = ON;
|
||||
|
||||
CREATE TABLE IF NOT EXISTS arch01_meta (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- Equivalence classes are created BEFORE their first principal (#822 §4).
|
||||
CREATE TABLE IF NOT EXISTS principal_equivalence_classes (
|
||||
class_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS authoritative_issuers (
|
||||
issuer_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
issuer_kind TEXT NOT NULL,
|
||||
issuer_ref TEXT NOT NULL,
|
||||
created_at TEXT NOT NULL,
|
||||
UNIQUE (issuer_kind, issuer_ref)
|
||||
);
|
||||
|
||||
-- current_class_id is NOT NULL: a principal cannot exist without a class
|
||||
-- (#822 AC6). issuer_id is nullable ONLY for the installer during install
|
||||
-- (#822 AC7), enforced by trg_principals_null_issuer below.
|
||||
CREATE TABLE IF NOT EXISTS principals (
|
||||
principal_id TEXT PRIMARY KEY,
|
||||
actor_kind TEXT NOT NULL CHECK (actor_kind IN ({_ACTOR_KINDS_SQL})),
|
||||
current_class_id INTEGER NOT NULL REFERENCES principal_equivalence_classes(class_id),
|
||||
issuer_id INTEGER REFERENCES authoritative_issuers(issuer_id),
|
||||
registered_by TEXT REFERENCES principals(principal_id),
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS authority_dominance (
|
||||
dominant TEXT NOT NULL,
|
||||
subordinate TEXT NOT NULL,
|
||||
PRIMARY KEY (dominant, subordinate)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS platform_bootstrap_seed (
|
||||
seed_id INTEGER PRIMARY KEY CHECK (seed_id = 1),
|
||||
installer_principal_id TEXT NOT NULL REFERENCES principals(principal_id),
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS platform_bootstrap_grants (
|
||||
grant_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
grantee_principal_id TEXT NOT NULL REFERENCES principals(principal_id),
|
||||
granted_by TEXT REFERENCES principals(principal_id),
|
||||
active INTEGER NOT NULL DEFAULT 1 CHECK (active IN (0, 1)),
|
||||
created_at TEXT NOT NULL,
|
||||
revoked_at TEXT
|
||||
);
|
||||
|
||||
-- Singleton row; active_count floored at 1 by CHECK so the last active grant
|
||||
-- can never be revoked (#822 AC11).
|
||||
CREATE TABLE IF NOT EXISTS platform_active_invariant (
|
||||
id INTEGER PRIMARY KEY CHECK (id = 1),
|
||||
active_count INTEGER NOT NULL CHECK (active_count >= 1)
|
||||
);
|
||||
|
||||
-- The immutable install marker; inserted LAST in the install transaction.
|
||||
CREATE TABLE IF NOT EXISTS install_state (
|
||||
id INTEGER PRIMARY KEY CHECK (id = 1),
|
||||
marker TEXT NOT NULL CHECK (marker = 'installed'),
|
||||
installed_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- Append-only (#822 AC14).
|
||||
CREATE TABLE IF NOT EXISTS audit_records (
|
||||
audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
event TEXT NOT NULL,
|
||||
principal_id TEXT,
|
||||
detail TEXT,
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- ------------------------------------------------------------------------- --
|
||||
-- Actor protocol on every mutating trigger (#822 §4, [SCHEMA] fail-closed).
|
||||
-- ------------------------------------------------------------------------- --
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_classes_actor
|
||||
BEFORE INSERT ON principal_equivalence_classes
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_issuers_actor
|
||||
BEFORE INSERT ON authoritative_issuers
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_principals_actor
|
||||
BEFORE INSERT ON principals
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_dominance_actor
|
||||
BEFORE INSERT ON authority_dominance
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_seed_actor
|
||||
BEFORE INSERT ON platform_bootstrap_seed
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_grants_actor_insert
|
||||
BEFORE INSERT ON platform_bootstrap_grants
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
{_REQUIRE_INSTALLED}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_grants_actor_update
|
||||
BEFORE UPDATE ON platform_bootstrap_grants
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_invariant_actor_insert
|
||||
BEFORE INSERT ON platform_active_invariant
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_invariant_actor_update
|
||||
BEFORE UPDATE ON platform_active_invariant
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_audit_actor
|
||||
BEFORE INSERT ON audit_records
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
-- ------------------------------------------------------------------------- --
|
||||
-- NOT-NULL-issuer exception for the installer only (#822 AC7).
|
||||
-- A NULL issuer_id is accepted solely for an installer principal during
|
||||
-- install mode, before the marker exists; any other NULL-issuer principal is
|
||||
-- rejected. install-time issuer linkage (installer -> distinguished issuer)
|
||||
-- is applied by a later UPDATE, permitted while no marker exists.
|
||||
-- ------------------------------------------------------------------------- --
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_principals_null_issuer
|
||||
BEFORE INSERT ON principals
|
||||
WHEN NEW.issuer_id IS NULL
|
||||
BEGIN
|
||||
SELECT CASE WHEN NOT (
|
||||
NEW.actor_kind = 'installer'
|
||||
AND cp_operation_mode() = 'install'
|
||||
AND (SELECT COUNT(*) FROM install_state) = 0
|
||||
AND (SELECT COUNT(*) FROM principals WHERE issuer_id IS NULL) = 0
|
||||
) THEN RAISE(ABORT, 'INVALID_BOOTSTRAP_STATE') END;
|
||||
END;
|
||||
|
||||
-- ------------------------------------------------------------------------- --
|
||||
-- Post-install immutability of the authority root (#822 §4, AC9).
|
||||
-- Registration fields freeze only AFTER the marker exists, so the install
|
||||
-- transaction's own installer issuer-linkage UPDATE is permitted.
|
||||
-- ------------------------------------------------------------------------- --
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_principals_frozen_update
|
||||
BEFORE UPDATE ON principals
|
||||
WHEN (SELECT COUNT(*) FROM install_state) > 0
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_PRINCIPAL');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_principals_frozen_delete
|
||||
BEFORE DELETE ON principals
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_PRINCIPAL');
|
||||
END;
|
||||
|
||||
-- Distinguished issuer identity is immutable once written.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_issuers_immutable_update
|
||||
BEFORE UPDATE ON authoritative_issuers
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_ISSUER');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_issuers_immutable_delete
|
||||
BEFORE DELETE ON authoritative_issuers
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_ISSUER');
|
||||
END;
|
||||
|
||||
-- The dominance lattice is immutable once seeded.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_dominance_immutable_update
|
||||
BEFORE UPDATE ON authority_dominance
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_DOMINANCE');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_dominance_immutable_delete
|
||||
BEFORE DELETE ON authority_dominance
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_DOMINANCE');
|
||||
END;
|
||||
|
||||
-- The bootstrap seed is immutable once written.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_seed_immutable_update
|
||||
BEFORE UPDATE ON platform_bootstrap_seed
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_SEED');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_seed_immutable_delete
|
||||
BEFORE DELETE ON platform_bootstrap_seed
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_SEED');
|
||||
END;
|
||||
|
||||
-- The install marker is immutable once written.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_install_state_immutable_update
|
||||
BEFORE UPDATE ON install_state
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_INSTALL_STATE');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_install_state_immutable_delete
|
||||
BEFORE DELETE ON install_state
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_INSTALL_STATE');
|
||||
END;
|
||||
|
||||
-- Grants: identity is immutable; the ONLY permitted mutation is a single
|
||||
-- active 1 -> 0 revocation (#822 §4 initial-grant identity immutability +
|
||||
-- grant/revoke). Reactivation and identity edits are rejected.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_grants_identity_frozen
|
||||
BEFORE UPDATE ON platform_bootstrap_grants
|
||||
WHEN NOT (
|
||||
NEW.grant_id = OLD.grant_id
|
||||
AND NEW.grantee_principal_id = OLD.grantee_principal_id
|
||||
AND NEW.granted_by IS OLD.granted_by
|
||||
AND NEW.created_at = OLD.created_at
|
||||
AND OLD.active = 1
|
||||
AND NEW.active = 0
|
||||
)
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_GRANT');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_grants_no_delete
|
||||
BEFORE DELETE ON platform_bootstrap_grants
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_GRANT');
|
||||
END;
|
||||
|
||||
-- audit_records is append-only.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_audit_immutable_update
|
||||
BEFORE UPDATE ON audit_records
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_AUDIT');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_audit_immutable_delete
|
||||
BEFORE DELETE ON audit_records
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_AUDIT');
|
||||
END;
|
||||
|
||||
-- ------------------------------------------------------------------------- --
|
||||
-- install_state BEFORE INSERT: validate the whole bootstrap atomically
|
||||
-- (#822 §4, AC4). Each dominance tuple is checked individually; a missing,
|
||||
-- additional, or malformed tuple -> DOMINANCE_SET_MISMATCH. The seed<->installer
|
||||
-- link, the single active NULL-grantor installer grant, the installer's
|
||||
-- non-NULL issuer, the active invariant, and "no extra principal created under
|
||||
-- the NULL-issuer exception" -> INVALID_BOOTSTRAP_STATE.
|
||||
-- ------------------------------------------------------------------------- --
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_install_state_validate
|
||||
BEFORE INSERT ON install_state
|
||||
BEGIN
|
||||
SELECT CASE WHEN NOT (
|
||||
(SELECT COUNT(*) FROM authority_dominance) = {len(DOMINANCE_TUPLES)}
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='platform.bootstrap')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='project.admin')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='supervisor.root.establish')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.register')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.verify')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.recover')
|
||||
) THEN RAISE(ABORT, 'DOMINANCE_SET_MISMATCH') END;
|
||||
|
||||
SELECT CASE WHEN NOT (
|
||||
(SELECT COUNT(*) FROM platform_bootstrap_seed) = 1
|
||||
AND (SELECT COUNT(*) FROM principals) = 1
|
||||
AND (SELECT actor_kind FROM principals
|
||||
WHERE principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
|
||||
) = 'installer'
|
||||
AND (SELECT issuer_id FROM principals
|
||||
WHERE principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
|
||||
) IS NOT NULL
|
||||
AND (SELECT COUNT(*) FROM platform_bootstrap_grants
|
||||
WHERE granted_by IS NULL AND active = 1
|
||||
AND grantee_principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
|
||||
) = 1
|
||||
AND (SELECT COUNT(*) FROM platform_bootstrap_grants) = 1
|
||||
AND (SELECT active_count FROM platform_active_invariant WHERE id = 1) = 1
|
||||
) THEN RAISE(ABORT, 'INVALID_BOOTSTRAP_STATE') END;
|
||||
END;
|
||||
"""
|
||||
|
||||
|
||||
def default_db_path() -> str:
|
||||
return os.environ.get(
|
||||
DB_PATH_ENV,
|
||||
os.path.expanduser("~/.cache/gitea-tools/arch01/platform.sqlite3"),
|
||||
)
|
||||
|
||||
|
||||
def _utc_now_iso() -> str:
|
||||
return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OperationResult:
|
||||
"""Structured result of a kernel operation (#822 §10)."""
|
||||
|
||||
code: str
|
||||
detail: str = ""
|
||||
|
||||
@property
|
||||
def ok(self) -> bool:
|
||||
return self.code in (INSTALLED, ALREADY_INSTALLED)
|
||||
|
||||
|
||||
@dataclass
|
||||
class _ActorContext:
|
||||
principal: str
|
||||
kind: str
|
||||
mode: str
|
||||
session: Optional[str]
|
||||
bound_epoch: int
|
||||
live_epoch: int
|
||||
expired: bool = False
|
||||
|
||||
|
||||
class PlatformKernel:
|
||||
"""ARCH-01 authority kernel over a single SQLite connection.
|
||||
|
||||
The connection carries the trusted-service actor context: the ``cp_*``
|
||||
scalar functions read the context this object holds. Only Python code here
|
||||
can bind or clear it, so no SQL statement can assert an actor identity — the
|
||||
trusted-service authenticity boundary of #822 §4.
|
||||
"""
|
||||
|
||||
def __init__(self, db_path: Optional[str] = None, *, busy_timeout_ms: int = 5000) -> None:
|
||||
self.db_path = db_path or default_db_path()
|
||||
if self.db_path != ":memory:":
|
||||
parent = os.path.dirname(self.db_path)
|
||||
if parent:
|
||||
os.makedirs(parent, exist_ok=True)
|
||||
self._ctx: Optional[_ActorContext] = None
|
||||
self._epoch_seq = 0
|
||||
self._lock = threading.Lock()
|
||||
# check_same_thread=False is safe: every mutation path is serialized
|
||||
# by self._lock, so the connection is never used concurrently even when
|
||||
# callers drive the kernel from different threads (concurrency tests).
|
||||
self._conn = sqlite3.connect(
|
||||
self.db_path, isolation_level=None, check_same_thread=False
|
||||
)
|
||||
self._conn.execute("PRAGMA foreign_keys = ON")
|
||||
self._conn.execute(f"PRAGMA busy_timeout = {int(busy_timeout_ms)}")
|
||||
self._register_actor_functions()
|
||||
self._migrate()
|
||||
|
||||
# -- trusted-service actor functions ---------------------------------- #
|
||||
|
||||
def _register_actor_functions(self) -> None:
|
||||
c = self._conn
|
||||
c.create_function("cp_actor_principal", 0, lambda: self._ctx.principal if self._ctx else None)
|
||||
c.create_function("cp_actor_kind", 0, lambda: self._ctx.kind if self._ctx else None)
|
||||
c.create_function("cp_operation_mode", 0, lambda: self._ctx.mode if self._ctx else None)
|
||||
c.create_function("cp_service_session", 0, lambda: self._ctx.session if self._ctx else None)
|
||||
c.create_function("cp_context_epoch", 0, self._fn_context_epoch)
|
||||
# Trusted-service helper: folds present + non-expired + epoch-consistent
|
||||
# into the read/re-read epoch equality of #822 §4.
|
||||
c.create_function("cp_actor_context_valid", 0, self._fn_context_valid)
|
||||
|
||||
def _fn_context_epoch(self) -> Optional[int]:
|
||||
if self._ctx is None or self._ctx.expired:
|
||||
return None
|
||||
return self._ctx.live_epoch
|
||||
|
||||
def _fn_context_valid(self) -> int:
|
||||
ctx = self._ctx
|
||||
if ctx is None or ctx.expired:
|
||||
return 0
|
||||
# read/re-read epoch equality: a context whose live epoch has drifted
|
||||
# from the epoch it was bound to (a stale/replaced connection context)
|
||||
# is not bound to the active transaction and fails closed.
|
||||
if ctx.live_epoch != ctx.bound_epoch:
|
||||
return 0
|
||||
if ctx.principal is None:
|
||||
return 0
|
||||
if ctx.kind not in ACTOR_KINDS or ctx.mode not in OPERATION_MODES:
|
||||
return 0
|
||||
return 1
|
||||
|
||||
# -- context lifecycle ------------------------------------------------ #
|
||||
|
||||
@contextmanager
|
||||
def actor_context(
|
||||
self, principal: str, kind: str, mode: str, session: Optional[str] = None
|
||||
) -> Iterator[None]:
|
||||
"""Bind a trusted actor context for the duration of the block."""
|
||||
prev = self._ctx
|
||||
self._epoch_seq += 1
|
||||
epoch = self._epoch_seq
|
||||
self._ctx = _ActorContext(
|
||||
principal=principal, kind=kind, mode=mode, session=session,
|
||||
bound_epoch=epoch, live_epoch=epoch,
|
||||
)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
self._ctx = prev
|
||||
|
||||
def _clear_context(self) -> None:
|
||||
self._ctx = None
|
||||
|
||||
# -- migration -------------------------------------------------------- #
|
||||
|
||||
def _migrate(self) -> None:
|
||||
self._conn.executescript(_SCHEMA_SQL)
|
||||
self._conn.execute(
|
||||
"INSERT OR IGNORE INTO arch01_meta(key, value) VALUES ('schema_version', ?)",
|
||||
(str(SCHEMA_VERSION),),
|
||||
)
|
||||
self._conn.execute(
|
||||
"INSERT OR IGNORE INTO arch01_meta(key, value) VALUES "
|
||||
"('architecture', 'ARCH-01 Slice A: atomic install + authority kernel (#822); "
|
||||
"disabled by default until readiness checks pass')"
|
||||
)
|
||||
|
||||
# -- introspection ---------------------------------------------------- #
|
||||
|
||||
def is_installed(self) -> bool:
|
||||
row = self._conn.execute("SELECT COUNT(*) FROM install_state").fetchone()
|
||||
return bool(row[0])
|
||||
|
||||
def active_grant_count(self) -> int:
|
||||
row = self._conn.execute(
|
||||
"SELECT active_count FROM platform_active_invariant WHERE id = 1"
|
||||
).fetchone()
|
||||
return int(row[0]) if row else 0
|
||||
|
||||
def audit_events(self) -> list[str]:
|
||||
return [
|
||||
r[0]
|
||||
for r in self._conn.execute(
|
||||
"SELECT event FROM audit_records ORDER BY audit_id"
|
||||
).fetchall()
|
||||
]
|
||||
|
||||
def close(self) -> None:
|
||||
self._conn.close()
|
||||
|
||||
# -- operations ------------------------------------------------------- #
|
||||
|
||||
def install_platform(
|
||||
self,
|
||||
installer_principal_id: str = "platform.installer",
|
||||
*,
|
||||
session: Optional[str] = None,
|
||||
) -> OperationResult:
|
||||
"""Single atomic install transaction (#822 §4/§7).
|
||||
|
||||
``BEGIN IMMEDIATE`` serializes concurrent installs; the loser rechecks
|
||||
the marker and returns ``ALREADY_INSTALLED``, or — if it never acquires
|
||||
the write lock — ``CONCURRENT_INSTALLATION_LOST``. On any stage failure
|
||||
the whole transaction rolls back leaving no partial rows (AC3/AC5).
|
||||
"""
|
||||
now = _utc_now_iso()
|
||||
with self._lock:
|
||||
try:
|
||||
self._conn.execute("BEGIN IMMEDIATE")
|
||||
except sqlite3.OperationalError as exc:
|
||||
if "locked" in str(exc).lower() or "busy" in str(exc).lower():
|
||||
return OperationResult(CONCURRENT_INSTALLATION_LOST, str(exc))
|
||||
raise
|
||||
try:
|
||||
if self.is_installed():
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(ALREADY_INSTALLED, "install marker already present")
|
||||
|
||||
with self.actor_context(installer_principal_id, "installer", "install", session):
|
||||
c = self._conn
|
||||
# class -> installer principal (temporary NULL issuer)
|
||||
cur = c.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES (?)",
|
||||
(now,),
|
||||
)
|
||||
class_id = cur.lastrowid
|
||||
c.execute(
|
||||
"INSERT INTO principals"
|
||||
"(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES (?, 'installer', ?, NULL, ?, ?)",
|
||||
(installer_principal_id, class_id, installer_principal_id, now),
|
||||
)
|
||||
# distinguished operator-key issuer
|
||||
cur = c.execute(
|
||||
"INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) "
|
||||
"VALUES (?, ?, ?)",
|
||||
(DISTINGUISHED_ISSUER_KIND, DISTINGUISHED_ISSUER_ID, now),
|
||||
)
|
||||
issuer_id = cur.lastrowid
|
||||
# link installer -> issuer (permitted pre-marker)
|
||||
c.execute(
|
||||
"UPDATE principals SET issuer_id = ? WHERE principal_id = ?",
|
||||
(issuer_id, installer_principal_id),
|
||||
)
|
||||
# dominance tuples
|
||||
c.executemany(
|
||||
"INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)",
|
||||
DOMINANCE_TUPLES,
|
||||
)
|
||||
# seed
|
||||
c.execute(
|
||||
"INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) "
|
||||
"VALUES (1, ?, ?)",
|
||||
(installer_principal_id, now),
|
||||
)
|
||||
# initial grant (granted_by NULL, active)
|
||||
c.execute(
|
||||
"INSERT INTO platform_bootstrap_grants"
|
||||
"(grantee_principal_id, granted_by, active, created_at) "
|
||||
"VALUES (?, NULL, 1, ?)",
|
||||
(installer_principal_id, now),
|
||||
)
|
||||
# active invariant
|
||||
c.execute(
|
||||
"INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)"
|
||||
)
|
||||
# audit rows for the security-sensitive operation
|
||||
c.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_PRINCIPAL_REGISTERED, installer_principal_id, "installer", now),
|
||||
)
|
||||
c.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_GRANT_CREATED, installer_principal_id, "initial platform.bootstrap grant", now),
|
||||
)
|
||||
# install marker LAST -> fires the whole-bootstrap validator
|
||||
c.execute(
|
||||
"INSERT INTO install_state(id, marker, installed_at) VALUES (1, 'installed', ?)",
|
||||
(now,),
|
||||
)
|
||||
c.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_PLATFORM_INSTALLED, installer_principal_id, "platform installed", now),
|
||||
)
|
||||
self._conn.execute("COMMIT")
|
||||
return OperationResult(INSTALLED, "platform installed")
|
||||
except sqlite3.Error as exc:
|
||||
self._safe_rollback()
|
||||
return OperationResult(self._classify(exc), str(exc))
|
||||
|
||||
def register_principal(
|
||||
self,
|
||||
principal_id: str,
|
||||
actor_kind: str,
|
||||
issuer_ref: str,
|
||||
*,
|
||||
actor_principal: str,
|
||||
actor_kind_ctx: str = "operator",
|
||||
session: Optional[str] = None,
|
||||
) -> OperationResult:
|
||||
"""Atomically create an equivalence class and its first principal.
|
||||
|
||||
The class is inserted *before* the principal, and ``current_class_id``
|
||||
is ``NOT NULL`` (#822 AC6): a principal can never exist classless.
|
||||
The principal references an existing issuer (non-NULL); the temporary
|
||||
NULL-issuer exception is reserved for the installer during install
|
||||
(AC7).
|
||||
"""
|
||||
if actor_kind not in ACTOR_KINDS:
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, f"bad actor_kind {actor_kind!r}")
|
||||
now = _utc_now_iso()
|
||||
with self._lock:
|
||||
try:
|
||||
self._conn.execute("BEGIN IMMEDIATE")
|
||||
except sqlite3.OperationalError as exc:
|
||||
return OperationResult(AUTHORIZATION_DENIED, str(exc))
|
||||
try:
|
||||
if not self.is_installed():
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
|
||||
row = self._conn.execute(
|
||||
"SELECT issuer_id FROM authoritative_issuers WHERE issuer_ref = ?",
|
||||
(issuer_ref,),
|
||||
).fetchone()
|
||||
if row is None:
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, f"unknown issuer {issuer_ref!r}")
|
||||
issuer_id = row[0]
|
||||
with self.actor_context(actor_principal, actor_kind_ctx, "normal", session):
|
||||
cur = self._conn.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES (?)",
|
||||
(now,),
|
||||
)
|
||||
class_id = cur.lastrowid
|
||||
self._conn.execute(
|
||||
"INSERT INTO principals"
|
||||
"(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES (?, ?, ?, ?, ?, ?)",
|
||||
(principal_id, actor_kind, class_id, issuer_id, actor_principal, now),
|
||||
)
|
||||
self._conn.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_PRINCIPAL_REGISTERED, principal_id, actor_kind, now),
|
||||
)
|
||||
self._conn.execute("COMMIT")
|
||||
return OperationResult(INSTALLED, f"registered {principal_id}")
|
||||
except sqlite3.Error as exc:
|
||||
self._safe_rollback()
|
||||
return OperationResult(self._classify(exc), str(exc))
|
||||
|
||||
def grant_platform_bootstrap(
|
||||
self,
|
||||
grantee_principal_id: str,
|
||||
granted_by: str,
|
||||
*,
|
||||
actor_kind_ctx: str = "operator",
|
||||
session: Optional[str] = None,
|
||||
) -> OperationResult:
|
||||
"""Create an additional active platform.bootstrap grant.
|
||||
|
||||
Serialized on the singleton invariant row via ``BEGIN IMMEDIATE``.
|
||||
"""
|
||||
now = _utc_now_iso()
|
||||
with self._lock:
|
||||
try:
|
||||
self._conn.execute("BEGIN IMMEDIATE")
|
||||
except sqlite3.OperationalError as exc:
|
||||
return OperationResult(AUTHORIZATION_DENIED, str(exc))
|
||||
try:
|
||||
if not self.is_installed():
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
|
||||
with self.actor_context(granted_by, actor_kind_ctx, "normal", session):
|
||||
self._conn.execute(
|
||||
"INSERT INTO platform_bootstrap_grants"
|
||||
"(grantee_principal_id, granted_by, active, created_at) "
|
||||
"VALUES (?, ?, 1, ?)",
|
||||
(grantee_principal_id, granted_by, now),
|
||||
)
|
||||
self._conn.execute(
|
||||
"UPDATE platform_active_invariant SET active_count = active_count + 1 WHERE id = 1"
|
||||
)
|
||||
self._conn.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_GRANT_CREATED, grantee_principal_id, f"granted_by={granted_by}", now),
|
||||
)
|
||||
self._conn.execute("COMMIT")
|
||||
return OperationResult(INSTALLED, f"granted to {grantee_principal_id}")
|
||||
except sqlite3.Error as exc:
|
||||
self._safe_rollback()
|
||||
return OperationResult(self._classify(exc), str(exc))
|
||||
|
||||
def revoke_platform_bootstrap(
|
||||
self,
|
||||
grant_id: int,
|
||||
*,
|
||||
actor_principal: str,
|
||||
actor_kind_ctx: str = "operator",
|
||||
session: Optional[str] = None,
|
||||
) -> OperationResult:
|
||||
"""Revoke an active grant, floored so the last one can never drop.
|
||||
|
||||
The ``active_count >= 1`` CHECK plus ``BEGIN IMMEDIATE`` serialization
|
||||
make two concurrent revocations unable to remove the final active grant
|
||||
(#822 AC11): the decrement that would reach zero fails and rolls back.
|
||||
"""
|
||||
now = _utc_now_iso()
|
||||
with self._lock:
|
||||
try:
|
||||
self._conn.execute("BEGIN IMMEDIATE")
|
||||
except sqlite3.OperationalError as exc:
|
||||
return OperationResult(AUTHORIZATION_DENIED, str(exc))
|
||||
try:
|
||||
if not self.is_installed():
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
|
||||
row = self._conn.execute(
|
||||
"SELECT active, grantee_principal_id FROM platform_bootstrap_grants WHERE grant_id = ?",
|
||||
(grant_id,),
|
||||
).fetchone()
|
||||
if row is None or row[0] != 1:
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(AUTHORIZATION_DENIED, "grant absent or already inactive")
|
||||
grantee = row[1]
|
||||
with self.actor_context(actor_principal, actor_kind_ctx, "normal", session):
|
||||
# Decrement first: the CHECK floor rejects dropping below 1,
|
||||
# aborting the whole revoke before the grant flips inactive.
|
||||
self._conn.execute(
|
||||
"UPDATE platform_active_invariant SET active_count = active_count - 1 WHERE id = 1"
|
||||
)
|
||||
self._conn.execute(
|
||||
"UPDATE platform_bootstrap_grants SET active = 0, revoked_at = ? WHERE grant_id = ?",
|
||||
(now, grant_id),
|
||||
)
|
||||
self._conn.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_GRANT_REVOKED, grantee, f"grant_id={grant_id}", now),
|
||||
)
|
||||
self._conn.execute("COMMIT")
|
||||
return OperationResult(INSTALLED, f"revoked grant {grant_id}")
|
||||
except sqlite3.Error as exc:
|
||||
self._safe_rollback()
|
||||
return OperationResult(self._classify(exc), str(exc))
|
||||
|
||||
# -- helpers ---------------------------------------------------------- #
|
||||
|
||||
def _safe_rollback(self) -> None:
|
||||
try:
|
||||
self._conn.execute("ROLLBACK")
|
||||
except sqlite3.Error:
|
||||
pass
|
||||
|
||||
@staticmethod
|
||||
def _classify(exc: sqlite3.Error) -> str:
|
||||
msg = str(exc)
|
||||
if "INVALID_ACTOR_CONTEXT" in msg:
|
||||
return INVALID_ACTOR_CONTEXT
|
||||
if "DOMINANCE_SET_MISMATCH" in msg:
|
||||
return DOMINANCE_SET_MISMATCH
|
||||
if "active_count" in msg or "CHECK constraint failed: platform_active_invariant" in msg:
|
||||
# last-active-grant floor tripped
|
||||
return AUTHORIZATION_DENIED
|
||||
if any(tag in msg for tag in (
|
||||
"INVALID_BOOTSTRAP_STATE", "IMMUTABLE_", "NOT_INSTALLED",
|
||||
)):
|
||||
return INVALID_BOOTSTRAP_STATE
|
||||
return INVALID_BOOTSTRAP_STATE
|
||||
+27
-8
@@ -43,10 +43,6 @@ for the console architecture: layer and authority boundaries, the redaction
|
||||
boundary, `/api/v1/...` versioning, the target page map, and the phase gates
|
||||
that govern when a write path may open (#632, epic #631).
|
||||
|
||||
See [webui-project-registry-api.md](webui-project-registry-api.md) for the
|
||||
versioned project registry contract: registry schema versions 1 and 2, project
|
||||
status, onboarding checklist state, and the fail-closed error payloads (#635).
|
||||
|
||||
## Routes (MVP)
|
||||
|
||||
| Path | Description |
|
||||
@@ -55,11 +51,9 @@ status, onboarding checklist state, and the fail-closed error payloads (#635).
|
||||
| `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`) |
|
||||
| `/queue` | Live PR and issue queue dashboard (#429) |
|
||||
| `/api/queue` | JSON queue export with pagination metadata |
|
||||
| `/projects` | Project registry list with status and onboarding progress (#427, #635) |
|
||||
| `/projects` | Project registry list (#427) |
|
||||
| `/projects/{id}` | Project detail + onboarding checklist |
|
||||
| `/api/v1/projects` | Versioned JSON registry export (#635) |
|
||||
| `/api/v1/projects/{id}` | Versioned JSON project detail (#635) |
|
||||
| `/api/projects` | JSON registry export — unversioned Phase 1 alias of `/api/v1/projects` |
|
||||
| `/api/projects` | JSON registry export |
|
||||
| `/prompts` | Prompt library with per-prompt copy buttons (#428) |
|
||||
| `/api/prompts` | JSON prompt export with workflow hashes |
|
||||
| `/runtime` | MCP runtime health and stale detection (#430) |
|
||||
@@ -73,6 +67,11 @@ status, onboarding checklist state, and the fail-closed error payloads (#635).
|
||||
| `/api/actions/{id}/preview` | Mutation ledger preview (GET, read-only) |
|
||||
| `/leases` | Lease and collision visibility (#433) |
|
||||
| `/api/leases` | JSON lease/collision export |
|
||||
| `/sessions` | Phase 1 shell stub — session inventory (backed by #636) |
|
||||
| `/inventory` | Phase 1 shell stub — unified inventory (backed by #636) |
|
||||
| `/timeline` | Phase 1 shell stub — workflow event timeline |
|
||||
| `/policy` | Phase 1 shell stub — capability/role policy placeholder |
|
||||
| `/insights` | Phase 1 shell stub — operational insights placeholder |
|
||||
|
||||
Most routes are GET-only. POST/PUT/PATCH/DELETE return `405` with
|
||||
`read-only-mvp`, except `/audit` and `/api/audit` which accept POST for
|
||||
@@ -153,6 +152,26 @@ health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the
|
||||
checkout is behind merged safety-gate changes. Restart guidance links to #420;
|
||||
no tokens or MCP restart actions are exposed.
|
||||
|
||||
## Application shell — Phase 1 (#638)
|
||||
|
||||
The console shell (`webui/layout.py`) renders a grouped navigation driven by a
|
||||
single nav-config module, `webui/nav.py`. Nav groups follow the epic #631
|
||||
Phase 1 information architecture: **Health, Traffic, Runtime/Sessions,
|
||||
Projects, Inventory, Timeline, Policy** (placeholder), and **Insights**
|
||||
(placeholder). Live views and Phase 1 placeholders (`stub`) are declared in one
|
||||
place so the layout and the route table cannot drift.
|
||||
|
||||
The header carries two read-only status badges — an **environment** badge
|
||||
(`local` for loopback binds, `remote` otherwise, derived from `WEBUI_HOST`) and
|
||||
a **mode: read-only** badge — plus a **Docs** link to this document. No
|
||||
privileged action controls are present in the Phase 1 shell.
|
||||
|
||||
Not-yet-implemented surfaces (`/sessions`, `/inventory`, `/timeline`,
|
||||
`/policy`, `/insights`) resolve to graceful read-only stub pages instead of
|
||||
404s; their backing views land in later child issues of #631 (the inventory
|
||||
surfaces are backed by #636). Mutating methods on stub routes still fail closed
|
||||
with `read-only-mvp`.
|
||||
|
||||
## Deployment boundary (#435)
|
||||
|
||||
MVP serves on loopback by default. Binding `0.0.0.0` or `::` is **refused**
|
||||
|
||||
@@ -1,213 +0,0 @@
|
||||
# Project registry API (#635)
|
||||
|
||||
Phase 1 of the [console architecture ADR](architecture/webui-control-plane-console-architecture-adr.md)
|
||||
gives the project registry a versioned, read-only API. This document is the
|
||||
field-by-field contract for that API and for the registry file behind it.
|
||||
|
||||
Everything here is **read-only**. The console never writes the registry; an
|
||||
operator edits the JSON file, and an invalid file fails closed rather than
|
||||
rendering a partial inventory.
|
||||
|
||||
## Routes
|
||||
|
||||
| Route | Method | Description |
|
||||
|-------|--------|-------------|
|
||||
| `/api/v1/projects` | GET | Versioned registry export: all projects, with provenance |
|
||||
| `/api/v1/projects/{project_id}` | GET | Single project; `404` with `project_not_found` when unknown |
|
||||
| `/api/projects` | GET | Unversioned MVP alias (#427), retained for all of Phase 1 |
|
||||
| `/projects` | GET | HTML list — status and onboarding progress per project |
|
||||
| `/projects/{project_id}` | GET | HTML detail — identity, profiles, paths, checklist |
|
||||
|
||||
Per ADR section 6 the unversioned alias may be retired no earlier than Phase 2,
|
||||
and only after this document and `webui-local-dev.md` record the swap. The alias
|
||||
returns the same payload as `/api/v1/projects`, including the legacy `version`
|
||||
and `source_path` keys #427 consumers already read.
|
||||
|
||||
The HTML views render from the same DTO the JSON routes serialize
|
||||
(`project_to_dict`), so the console and the API cannot disagree about a
|
||||
project's status or onboarding progress.
|
||||
|
||||
## Registry file
|
||||
|
||||
Default location: `webui/data/projects.registry.json`. Override with the
|
||||
`WEBUI_PROJECT_REGISTRY` environment variable.
|
||||
|
||||
Schema versions: **1** and **2** are accepted; **2** is current. A version 1
|
||||
file loads unchanged and is normalized with the documented defaults, so an
|
||||
existing operator registry keeps working without edits.
|
||||
|
||||
### Root
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|-------|------|----------|-------|
|
||||
| `version` | int | yes | `1` or `2`. Anything else fails closed |
|
||||
| `projects` | array | yes | Must be non-empty |
|
||||
|
||||
### Project
|
||||
|
||||
| Field | Type | Required | Default | Notes |
|
||||
|-------|------|----------|---------|-------|
|
||||
| `id` | string | yes | — | Stable registry id used in URLs |
|
||||
| `repo_name` | string | yes | — | Gitea repository name |
|
||||
| `gitea_owner` | string | yes | — | Owning org or user |
|
||||
| `remote_host` | string | yes | — | Instance base URL, no credentials |
|
||||
| `remote_name` | string | no | `null` | Logical remote label, e.g. `prgs` (v2) |
|
||||
| `default_branch` | string | yes | — | Stable branch name |
|
||||
| `local_checkout_path` | string | yes | — | Control checkout path |
|
||||
| `status` | string | no | `active` | `active`, `onboarding`, `paused`, `archived` (v2) |
|
||||
| `profiles` | object | yes | — | Must map `author`, `reviewer`, `reconciler` |
|
||||
| `workflow_paths` | object | yes | — | Non-empty; label to repo-relative path |
|
||||
| `schema_paths` | object | no | `{}` | Label to repo-relative path |
|
||||
| `onboarding_checklist` | array | no | `[]` | See below |
|
||||
| `last_seen_health` | object | no | `null` | Redacted health only (v2) |
|
||||
|
||||
### Onboarding step
|
||||
|
||||
| Field | Type | Required | Default | Notes |
|
||||
|-------|------|----------|---------|-------|
|
||||
| `id` | string | yes | — | Stable step id |
|
||||
| `title` | string | yes | — | Short operator-facing label |
|
||||
| `description` | string | yes | — | Self-contained; assumes no chat history |
|
||||
| `state` | string | no | `pending` | `complete`, `pending`, `blocked`, `not_applicable` (v2) |
|
||||
| `required` | bool | no | `true` | Optional steps never block readiness (v2) |
|
||||
|
||||
### Last-seen health
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|-------|------|----------|-------|
|
||||
| `status` | string | no (default `unknown`) | `healthy`, `degraded`, `unreachable`, `unknown` |
|
||||
| `checked_at` | string | no | ISO-8601 UTC timestamp, e.g. `2026-01-01T00:00:00Z` |
|
||||
| `detail` | string | no | Short redacted note |
|
||||
|
||||
Health is recorded metadata, not a live probe: Phase 1 performs no outbound
|
||||
health checks. Endpoints, tokens, and keychain identifiers must never appear
|
||||
here.
|
||||
|
||||
## Response shape
|
||||
|
||||
`GET /api/v1/projects`:
|
||||
|
||||
```json
|
||||
{
|
||||
"api_version": "v1",
|
||||
"schema_version": 2,
|
||||
"version": 2,
|
||||
"source_path": "/path/to/webui/data/projects.registry.json",
|
||||
"source": {
|
||||
"kind": "file",
|
||||
"path": "/path/to/webui/data/projects.registry.json",
|
||||
"inventory_complete": true
|
||||
},
|
||||
"project_count": 1,
|
||||
"projects": [
|
||||
{
|
||||
"id": "example",
|
||||
"repo_name": "Example",
|
||||
"gitea_owner": "Org",
|
||||
"repo_full_name": "Org/Example",
|
||||
"remote_host": "https://gitea.example.invalid",
|
||||
"remote_name": "example-remote",
|
||||
"default_branch": "main",
|
||||
"local_checkout_path": ".",
|
||||
"status": "active",
|
||||
"profiles": {"author": "...", "reviewer": "...", "reconciler": "..."},
|
||||
"workflow_paths": {"skill": "skills/..."},
|
||||
"schema_paths": {},
|
||||
"onboarding_checklist": [
|
||||
{
|
||||
"id": "profiles",
|
||||
"title": "Configure execution profiles",
|
||||
"description": "...",
|
||||
"state": "complete",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"onboarding_summary": {
|
||||
"total": 1,
|
||||
"complete": 1,
|
||||
"pending": 0,
|
||||
"blocked": 0,
|
||||
"not_applicable": 0,
|
||||
"required_outstanding": 0,
|
||||
"onboarding_complete": true
|
||||
},
|
||||
"last_seen_health": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`GET /api/v1/projects/{project_id}` returns `api_version`, `schema_version`,
|
||||
`source`, and a single `project` object with the same fields.
|
||||
|
||||
The `source` block satisfies the ADR section 6 provenance rule: every payload
|
||||
states where the data came from and whether the inventory is complete. A
|
||||
file-backed registry is always complete — there is no pagination to truncate it.
|
||||
|
||||
`onboarding_summary` is derived, never stored. `required_outstanding` counts
|
||||
steps that are `required` **and** in state `pending` or `blocked`;
|
||||
`onboarding_complete` is true when that count is zero.
|
||||
|
||||
## Fail-closed errors
|
||||
|
||||
Validation failures raise `RegistryError`, which routes render instead of a
|
||||
traceback.
|
||||
|
||||
`404` — unknown project id on `/api/v1/projects/{project_id}`:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "project_not_found",
|
||||
"project_id": "not-registered",
|
||||
"known_project_ids": ["example"],
|
||||
"remediation": "Request one of the known project ids, or add the project ...",
|
||||
"source": {"kind": "file", "path": "...", "inventory_complete": true}
|
||||
}
|
||||
```
|
||||
|
||||
`500` — invalid registry, on both the versioned route and the alias:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "registry_invalid",
|
||||
"detail": "unsupported registry version: 42",
|
||||
"remediation": "Set 'version' to one of 1, 2 (current schema is 2) ...",
|
||||
"field_path": "version",
|
||||
"source_path": "/path/to/registry.json"
|
||||
}
|
||||
```
|
||||
|
||||
`field_path` points at the offending location (`projects[0].profiles.reconciler`,
|
||||
`projects[0].onboarding_checklist[2].state`, and so on). The HTML routes render
|
||||
the same detail, field, source, and remediation on a "Project registry
|
||||
unavailable" page.
|
||||
|
||||
Conditions that fail closed:
|
||||
|
||||
* file missing or unreadable;
|
||||
* invalid JSON (the remediation names line and column);
|
||||
* root not an object, or `projects` missing/empty;
|
||||
* unsupported `version`;
|
||||
* a credential-shaped key anywhere in the file (`token`, `*_secret`, `auth_*`, and similar);
|
||||
* a project missing a required field, or missing an `author`/`reviewer`/`reconciler` profile;
|
||||
* an unknown `status`, onboarding `state`, or health `status`.
|
||||
|
||||
## Credential rule
|
||||
|
||||
The registry stores redacted metadata only. Credential-shaped keys are
|
||||
rejected at load time, before any DTO is built, consistent with
|
||||
[safety-model.md](safety-model.md) and
|
||||
[credential-isolation.md](credential-isolation.md). Tokens live in the keychain
|
||||
and are resolved server-side by `gitea_auth`.
|
||||
|
||||
## Migrating a version 1 registry
|
||||
|
||||
1. Set `"version": 2`.
|
||||
2. Optionally add `"status"` per project (omitted means `active`).
|
||||
3. Optionally add `"remote_name"` per project.
|
||||
4. Optionally add `"state"` and `"required"` to each onboarding step (omitted
|
||||
means `pending` and `true`).
|
||||
5. Optionally add `"last_seen_health"`.
|
||||
|
||||
No step is mandatory: a version 1 file keeps loading. Bumping the version only
|
||||
declares that the file may use the v2 fields.
|
||||
+2
-18
@@ -9173,27 +9173,11 @@ def gitea_publish_unpublished_issue_branch(
|
||||
if blocked:
|
||||
return blocked
|
||||
|
||||
# #815: resolve the caller's worktree *before* preflight and forward it, so
|
||||
# every workspace-resolution layer behind verify_preflight_purity — including
|
||||
# the #618 branches-only guard — judges the registered issue worktree this
|
||||
# publication actually operates on. Resolving it afterwards let preflight
|
||||
# fall back to the MCP process root, so a daemon rooted at the stable control
|
||||
# checkout refused a valid explicit worktree before the assessor ever ran.
|
||||
# A caller supplying nothing usable forwards None and keeps the ordinary
|
||||
# fail-closed fallback.
|
||||
explicit_worktree = (worktree_path or "").strip()
|
||||
workspace = os.path.realpath(os.path.abspath(explicit_worktree or "."))
|
||||
|
||||
verify_preflight_purity(
|
||||
remote,
|
||||
worktree_path=workspace if explicit_worktree else None,
|
||||
task=task,
|
||||
org=org,
|
||||
repo=repo,
|
||||
)
|
||||
verify_preflight_purity(remote, task=task, org=org, repo=repo)
|
||||
|
||||
h, o, r = _resolve(remote, host, org, repo)
|
||||
git_remote = (git_remote_name or remote or "").strip()
|
||||
workspace = os.path.realpath(os.path.abspath((worktree_path or "").strip() or "."))
|
||||
|
||||
existing_lock = issue_lock_store.load_issue_lock(
|
||||
remote=remote, org=o, repo=r, issue_number=int(issue_number)
|
||||
|
||||
@@ -1,572 +0,0 @@
|
||||
"""Executable acceptance tests for ARCH-01 Slice A (#822).
|
||||
|
||||
Each acceptance criterion (#822 §12) and named test (#822 §13) is exercised
|
||||
against a real SQLite database. The migration runs on a fresh DB in ``setUp``;
|
||||
the test-run output is the durable evidence the issue requires (§14).
|
||||
|
||||
Enforcement being proven:
|
||||
|
||||
* ``[TRUSTED-SERVICE]`` — the ``cp_*`` actor functions exist only on the
|
||||
trusted kernel connection; a raw connection cannot satisfy the triggers.
|
||||
* ``[SCHEMA]`` — fail-closed aborts, exact dominance set, NOT-NULL class,
|
||||
immutability, and the last-active-grant floor are enforced by
|
||||
CHECK/FK/trigger, verified here including raw-write bypass and concurrency.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import sqlite3
|
||||
import tempfile
|
||||
import threading
|
||||
import unittest
|
||||
from concurrent.futures import ThreadPoolExecutor
|
||||
|
||||
import arch01_platform as ap
|
||||
from arch01_platform import (
|
||||
ALREADY_INSTALLED,
|
||||
AUTHORIZATION_DENIED,
|
||||
CONCURRENT_INSTALLATION_LOST,
|
||||
DISTINGUISHED_ISSUER_ID,
|
||||
DOMINANCE_SET_MISMATCH,
|
||||
DOMINANCE_TUPLES,
|
||||
INSTALLED,
|
||||
INVALID_ACTOR_CONTEXT,
|
||||
INVALID_BOOTSTRAP_STATE,
|
||||
PlatformKernel,
|
||||
)
|
||||
|
||||
INSTALLER = "platform.installer"
|
||||
|
||||
_BOOTSTRAP_TABLES = (
|
||||
"principal_equivalence_classes",
|
||||
"principals",
|
||||
"authoritative_issuers",
|
||||
"authority_dominance",
|
||||
"platform_bootstrap_seed",
|
||||
"platform_bootstrap_grants",
|
||||
"platform_active_invariant",
|
||||
"install_state",
|
||||
)
|
||||
|
||||
|
||||
def _count(kernel: PlatformKernel, table: str) -> int:
|
||||
return kernel._conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
|
||||
|
||||
|
||||
def _count_where(kernel: PlatformKernel, table: str, where: str) -> int:
|
||||
return kernel._conn.execute(f"SELECT COUNT(*) FROM {table} WHERE {where}").fetchone()[0]
|
||||
|
||||
|
||||
def _all_bootstrap_empty(kernel: PlatformKernel) -> bool:
|
||||
return all(_count(kernel, t) == 0 for t in _BOOTSTRAP_TABLES)
|
||||
|
||||
|
||||
class Arch01MemoryTest(unittest.TestCase):
|
||||
"""Single-connection behavior on an in-memory database."""
|
||||
|
||||
def setUp(self) -> None:
|
||||
self.kernel = PlatformKernel(":memory:")
|
||||
|
||||
def tearDown(self) -> None:
|
||||
self.kernel.close()
|
||||
|
||||
# -- AC1 -------------------------------------------------------------- #
|
||||
def test_install_clean(self) -> None: # t_install_clean(+)
|
||||
res = self.kernel.install_platform(INSTALLER)
|
||||
self.assertEqual(res.code, INSTALLED)
|
||||
self.assertTrue(self.kernel.is_installed())
|
||||
self.assertEqual(_count(self.kernel, "install_state"), 1)
|
||||
self.assertEqual(self.kernel.active_grant_count(), 1)
|
||||
self.assertIn(ap.EVT_PLATFORM_INSTALLED, self.kernel.audit_events())
|
||||
rows = set(
|
||||
self.kernel._conn.execute(
|
||||
"SELECT dominant, subordinate FROM authority_dominance"
|
||||
).fetchall()
|
||||
)
|
||||
self.assertEqual(rows, set(DOMINANCE_TUPLES))
|
||||
issuer_ref = self.kernel._conn.execute(
|
||||
"SELECT i.issuer_ref FROM principals p JOIN authoritative_issuers i "
|
||||
"ON p.issuer_id = i.issuer_id WHERE p.principal_id = ?",
|
||||
(INSTALLER,),
|
||||
).fetchone()
|
||||
self.assertEqual(issuer_ref[0], DISTINGUISHED_ISSUER_ID)
|
||||
|
||||
# -- AC2 -------------------------------------------------------------- #
|
||||
def test_install_twice(self) -> None: # t_install_twice(-)
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
res2 = self.kernel.install_platform(INSTALLER)
|
||||
self.assertEqual(res2.code, ALREADY_INSTALLED)
|
||||
self.assertEqual(_count(self.kernel, "principals"), 1)
|
||||
self.assertEqual(_count(self.kernel, "platform_bootstrap_grants"), 1)
|
||||
self.assertEqual(_count(self.kernel, "install_state"), 1)
|
||||
|
||||
# -- AC3 / AC5 -------------------------------------------------------- #
|
||||
def test_install_stage_rollback(self) -> None: # t_install_stage_rollback
|
||||
for stop in range(1, 9):
|
||||
with self.subTest(stages=stop):
|
||||
k = PlatformKernel(":memory:")
|
||||
try:
|
||||
self._partial_bootstrap_then_rollback(k, stop)
|
||||
self.assertTrue(
|
||||
_all_bootstrap_empty(k),
|
||||
f"partial rows survived rollback at stage {stop}",
|
||||
)
|
||||
self.assertFalse(k.is_installed())
|
||||
finally:
|
||||
k.close()
|
||||
|
||||
def test_no_partial_after_rollback(self) -> None: # t_no_partial_after_rollback
|
||||
k = PlatformKernel(":memory:")
|
||||
try:
|
||||
code = self._seed_bootstrap_and_mark(k, dominance=DOMINANCE_TUPLES[:-1])
|
||||
self.assertEqual(code, DOMINANCE_SET_MISMATCH)
|
||||
self.assertTrue(_all_bootstrap_empty(k))
|
||||
self.assertFalse(k.is_installed())
|
||||
finally:
|
||||
k.close()
|
||||
|
||||
# -- AC4 -------------------------------------------------------------- #
|
||||
def test_dominance_missing(self) -> None: # t_dominance_missing(-)
|
||||
k = PlatformKernel(":memory:")
|
||||
try:
|
||||
self.assertEqual(
|
||||
self._seed_bootstrap_and_mark(k, dominance=DOMINANCE_TUPLES[:-1]),
|
||||
DOMINANCE_SET_MISMATCH,
|
||||
)
|
||||
self.assertFalse(k.is_installed())
|
||||
finally:
|
||||
k.close()
|
||||
|
||||
def test_dominance_extra(self) -> None: # t_dominance_extra(-)
|
||||
k = PlatformKernel(":memory:")
|
||||
try:
|
||||
extra = DOMINANCE_TUPLES + (("platform.bootstrap", "rogue.extra"),)
|
||||
self.assertEqual(
|
||||
self._seed_bootstrap_and_mark(k, dominance=extra),
|
||||
DOMINANCE_SET_MISMATCH,
|
||||
)
|
||||
self.assertFalse(k.is_installed())
|
||||
finally:
|
||||
k.close()
|
||||
|
||||
def test_dominance_malformed(self) -> None: # t_dominance_malformed(-)
|
||||
k = PlatformKernel(":memory:")
|
||||
try:
|
||||
malformed = DOMINANCE_TUPLES[:-1] + (("supervisor.root", "WRONG.subordinate"),)
|
||||
self.assertEqual(
|
||||
self._seed_bootstrap_and_mark(k, dominance=malformed),
|
||||
DOMINANCE_SET_MISMATCH,
|
||||
)
|
||||
self.assertFalse(k.is_installed())
|
||||
finally:
|
||||
k.close()
|
||||
|
||||
# -- AC6 -------------------------------------------------------------- #
|
||||
def test_principal_no_class(self) -> None: # t_principal_no_class(-)
|
||||
with self.kernel.actor_context("op", "operator", "install"):
|
||||
with self.assertRaises(sqlite3.IntegrityError):
|
||||
self.kernel._conn.execute(
|
||||
"INSERT INTO principals"
|
||||
"(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES ('x', 'operator', NULL, NULL, NULL, '2026-01-01T00:00:00Z')"
|
||||
)
|
||||
|
||||
# -- AC7 -------------------------------------------------------------- #
|
||||
def test_noninstaller_null_issuer(self) -> None: # t_nonobstaller_null_issuer(-)
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
with self.kernel.actor_context("op", "operator", "normal"):
|
||||
cur = self.kernel._conn.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
|
||||
)
|
||||
class_id = cur.lastrowid
|
||||
with self.assertRaises(sqlite3.IntegrityError) as ctx:
|
||||
self.kernel._conn.execute(
|
||||
"INSERT INTO principals"
|
||||
"(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES ('rogue', 'operator', ?, NULL, NULL, '2026-01-01T00:00:00Z')",
|
||||
(class_id,),
|
||||
)
|
||||
self.assertIn("INVALID_BOOTSTRAP_STATE", str(ctx.exception))
|
||||
|
||||
def test_installer_null_issuer_only_during_install(self) -> None:
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
with self.kernel.actor_context("i2", "installer", "install"):
|
||||
cur = self.kernel._conn.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
|
||||
)
|
||||
class_id = cur.lastrowid
|
||||
with self.assertRaises(sqlite3.IntegrityError):
|
||||
self.kernel._conn.execute(
|
||||
"INSERT INTO principals"
|
||||
"(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES ('i2', 'installer', ?, NULL, NULL, '2026-01-01T00:00:00Z')",
|
||||
(class_id,),
|
||||
)
|
||||
|
||||
# -- AC8 -------------------------------------------------------------- #
|
||||
def test_context_missing(self) -> None: # t_context_missing(-)
|
||||
self.assertIsNone(self.kernel._ctx)
|
||||
with self.assertRaises(sqlite3.IntegrityError) as ctx:
|
||||
self.kernel._conn.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
|
||||
)
|
||||
self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception))
|
||||
|
||||
def test_context_stale(self) -> None: # t_context_stale(-)
|
||||
with self.kernel.actor_context("op", "operator", "normal"):
|
||||
self.kernel._ctx.expired = True
|
||||
with self.assertRaises(sqlite3.IntegrityError) as ctx:
|
||||
self.kernel._conn.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
|
||||
)
|
||||
self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception))
|
||||
|
||||
def test_context_epoch_shift(self) -> None: # t_context_epoch_shift(-)
|
||||
with self.kernel.actor_context("op", "operator", "normal"):
|
||||
self.kernel._ctx.live_epoch = self.kernel._ctx.bound_epoch + 99
|
||||
with self.assertRaises(sqlite3.IntegrityError) as ctx:
|
||||
self.kernel._conn.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
|
||||
)
|
||||
self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception))
|
||||
|
||||
def test_bad_actor_kind_or_mode_rejected(self) -> None:
|
||||
for kind, mode in (("intruder", "normal"), ("operator", "sabotage")):
|
||||
with self.subTest(kind=kind, mode=mode):
|
||||
with self.kernel.actor_context("op", kind, mode):
|
||||
with self.assertRaises(sqlite3.IntegrityError):
|
||||
self.kernel._conn.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) "
|
||||
"VALUES ('2026-01-01T00:00:00Z')"
|
||||
)
|
||||
|
||||
# -- AC9 -------------------------------------------------------------- #
|
||||
def test_bootstrap_immutable_update(self) -> None: # t_bootstrap_immutable_{update}
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
cases = [
|
||||
("UPDATE install_state SET installed_at = 'x' WHERE id = 1", "IMMUTABLE_INSTALL_STATE"),
|
||||
("UPDATE platform_bootstrap_seed SET created_at = 'x' WHERE seed_id = 1", "IMMUTABLE_SEED"),
|
||||
("UPDATE authority_dominance SET subordinate = 'x' WHERE dominant = 'supervisor.root'", "IMMUTABLE_DOMINANCE"),
|
||||
(f"UPDATE authoritative_issuers SET issuer_ref = 'x' WHERE issuer_ref = '{DISTINGUISHED_ISSUER_ID}'", "IMMUTABLE_ISSUER"),
|
||||
(f"UPDATE principals SET actor_kind = 'operator' WHERE principal_id = '{INSTALLER}'", "IMMUTABLE_PRINCIPAL"),
|
||||
]
|
||||
for sql, tag in cases:
|
||||
with self.subTest(sql=sql):
|
||||
with self.kernel.actor_context("op", "operator", "normal"):
|
||||
with self.assertRaises(sqlite3.IntegrityError) as ctx:
|
||||
self.kernel._conn.execute(sql)
|
||||
self.assertIn(tag, str(ctx.exception))
|
||||
|
||||
def test_bootstrap_immutable_delete(self) -> None: # t_bootstrap_immutable_{delete}
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
cases = [
|
||||
("DELETE FROM install_state WHERE id = 1", "IMMUTABLE_INSTALL_STATE"),
|
||||
("DELETE FROM platform_bootstrap_seed WHERE seed_id = 1", "IMMUTABLE_SEED"),
|
||||
("DELETE FROM authority_dominance", "IMMUTABLE_DOMINANCE"),
|
||||
("DELETE FROM authoritative_issuers", "IMMUTABLE_ISSUER"),
|
||||
(f"DELETE FROM principals WHERE principal_id = '{INSTALLER}'", "IMMUTABLE_PRINCIPAL"),
|
||||
("DELETE FROM platform_bootstrap_grants", "IMMUTABLE_GRANT"),
|
||||
]
|
||||
for sql, tag in cases:
|
||||
with self.subTest(sql=sql):
|
||||
with self.kernel.actor_context("op", "operator", "normal"):
|
||||
with self.assertRaises(sqlite3.IntegrityError) as ctx:
|
||||
self.kernel._conn.execute(sql)
|
||||
self.assertIn(tag, str(ctx.exception))
|
||||
|
||||
def test_grant_reactivation_rejected(self) -> None:
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
self.kernel.register_principal(
|
||||
"op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER
|
||||
)
|
||||
self.assertEqual(
|
||||
self.kernel.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED
|
||||
)
|
||||
gid = self.kernel._conn.execute(
|
||||
"SELECT grant_id FROM platform_bootstrap_grants WHERE grantee_principal_id = 'op1'"
|
||||
).fetchone()[0]
|
||||
self.assertEqual(
|
||||
self.kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code,
|
||||
INSTALLED,
|
||||
)
|
||||
with self.kernel.actor_context("op", "operator", "normal"):
|
||||
with self.assertRaises(sqlite3.IntegrityError) as ctx:
|
||||
self.kernel._conn.execute(
|
||||
"UPDATE platform_bootstrap_grants SET active = 1 WHERE grant_id = ?",
|
||||
(gid,),
|
||||
)
|
||||
self.assertIn("IMMUTABLE_GRANT", str(ctx.exception))
|
||||
|
||||
# -- AC12 ------------------------------------------------------------- #
|
||||
def test_raw_write_bypass(self) -> None: # t_raw_write_bypass(raw-bypass)
|
||||
with tempfile.TemporaryDirectory() as tmp:
|
||||
path = os.path.join(tmp, "p.sqlite3")
|
||||
k = PlatformKernel(path)
|
||||
self.assertEqual(k.install_platform(INSTALLER).code, INSTALLED)
|
||||
k.close()
|
||||
raw = sqlite3.connect(path)
|
||||
raw.execute("PRAGMA foreign_keys = ON")
|
||||
try:
|
||||
with self.assertRaises(sqlite3.Error):
|
||||
raw.execute(
|
||||
"INSERT INTO audit_records(event, created_at) "
|
||||
"VALUES ('forged', '2026-01-01T00:00:00Z')"
|
||||
)
|
||||
raw.commit()
|
||||
with self.assertRaises(sqlite3.Error):
|
||||
raw.execute("UPDATE install_state SET installed_at = 'x' WHERE id = 1")
|
||||
raw.commit()
|
||||
with self.assertRaises(sqlite3.Error):
|
||||
raw.execute("DELETE FROM platform_bootstrap_grants")
|
||||
raw.commit()
|
||||
finally:
|
||||
raw.close()
|
||||
|
||||
# -- AC13 ------------------------------------------------------------- #
|
||||
def test_audit_created(self) -> None: # t_audit_created(+)
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
self.kernel.register_principal(
|
||||
"op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER
|
||||
)
|
||||
self.assertEqual(
|
||||
self.kernel.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED
|
||||
)
|
||||
gid = self.kernel._conn.execute(
|
||||
"SELECT grant_id FROM platform_bootstrap_grants WHERE grantee_principal_id = 'op1'"
|
||||
).fetchone()[0]
|
||||
self.assertEqual(
|
||||
self.kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code,
|
||||
INSTALLED,
|
||||
)
|
||||
events = self.kernel.audit_events()
|
||||
for evt in (
|
||||
ap.EVT_PLATFORM_INSTALLED,
|
||||
ap.EVT_GRANT_CREATED,
|
||||
ap.EVT_GRANT_REVOKED,
|
||||
ap.EVT_PRINCIPAL_REGISTERED,
|
||||
):
|
||||
self.assertIn(evt, events)
|
||||
|
||||
# -- AC14 ------------------------------------------------------------- #
|
||||
def test_audit_immutable(self) -> None: # t_audit_immutable(raw-bypass)
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
with self.kernel.actor_context("op", "operator", "normal"):
|
||||
with self.assertRaises(sqlite3.IntegrityError) as up:
|
||||
self.kernel._conn.execute("UPDATE audit_records SET event = 'x' WHERE audit_id = 1")
|
||||
self.assertIn("IMMUTABLE_AUDIT", str(up.exception))
|
||||
with self.assertRaises(sqlite3.IntegrityError) as dl:
|
||||
self.kernel._conn.execute("DELETE FROM audit_records WHERE audit_id = 1")
|
||||
self.assertIn("IMMUTABLE_AUDIT", str(dl.exception))
|
||||
|
||||
# -- meta ------------------------------------------------------------- #
|
||||
def test_schema_meta(self) -> None:
|
||||
rows = dict(self.kernel._conn.execute("SELECT key, value FROM arch01_meta").fetchall())
|
||||
self.assertEqual(rows["schema_version"], str(ap.SCHEMA_VERSION))
|
||||
self.assertIn("disabled by default", rows["architecture"])
|
||||
|
||||
def test_register_principal_creates_class_first(self) -> None:
|
||||
self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
|
||||
res = self.kernel.register_principal(
|
||||
"svc1", "service", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER
|
||||
)
|
||||
self.assertEqual(res.code, INSTALLED)
|
||||
row = self.kernel._conn.execute(
|
||||
"SELECT current_class_id FROM principals WHERE principal_id = 'svc1'"
|
||||
).fetchone()
|
||||
self.assertIsNotNone(row[0])
|
||||
|
||||
# -- helpers ---------------------------------------------------------- #
|
||||
def _partial_bootstrap_then_rollback(self, k: PlatformKernel, stop: int) -> None:
|
||||
"""Execute the first ``stop`` bootstrap statements, then ROLLBACK."""
|
||||
now = "2026-01-01T00:00:00Z"
|
||||
k._conn.execute("BEGIN IMMEDIATE")
|
||||
class_id = None
|
||||
issuer_id = None
|
||||
try:
|
||||
with k.actor_context(INSTALLER, "installer", "install"):
|
||||
c = k._conn
|
||||
if stop >= 1:
|
||||
class_id = c.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES (?)", (now,)
|
||||
).lastrowid
|
||||
if stop >= 2:
|
||||
c.execute(
|
||||
"INSERT INTO principals(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES (?, 'installer', ?, NULL, ?, ?)",
|
||||
(INSTALLER, class_id, INSTALLER, now),
|
||||
)
|
||||
if stop >= 3:
|
||||
issuer_id = c.execute(
|
||||
"INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) VALUES ('operator-key', ?, ?)",
|
||||
(DISTINGUISHED_ISSUER_ID, now),
|
||||
).lastrowid
|
||||
if stop >= 4:
|
||||
c.execute(
|
||||
"UPDATE principals SET issuer_id = ? WHERE principal_id = ?",
|
||||
(issuer_id, INSTALLER),
|
||||
)
|
||||
if stop >= 5:
|
||||
c.executemany(
|
||||
"INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)",
|
||||
DOMINANCE_TUPLES,
|
||||
)
|
||||
if stop >= 6:
|
||||
c.execute(
|
||||
"INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) VALUES (1, ?, ?)",
|
||||
(INSTALLER, now),
|
||||
)
|
||||
if stop >= 7:
|
||||
c.execute(
|
||||
"INSERT INTO platform_bootstrap_grants(grantee_principal_id, granted_by, active, created_at) VALUES (?, NULL, 1, ?)",
|
||||
(INSTALLER, now),
|
||||
)
|
||||
if stop >= 8:
|
||||
c.execute("INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)")
|
||||
finally:
|
||||
k._conn.execute("ROLLBACK")
|
||||
|
||||
def _seed_bootstrap_and_mark(self, k: PlatformKernel, dominance) -> str:
|
||||
"""Seed a full bootstrap with a caller-supplied dominance set, then
|
||||
attempt the marker insert. Returns the classified failure code (or
|
||||
INSTALLED). Rolls back on failure so no partial rows remain."""
|
||||
now = "2026-01-01T00:00:00Z"
|
||||
k._conn.execute("BEGIN IMMEDIATE")
|
||||
try:
|
||||
with k.actor_context(INSTALLER, "installer", "install"):
|
||||
c = k._conn
|
||||
class_id = c.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES (?)", (now,)
|
||||
).lastrowid
|
||||
c.execute(
|
||||
"INSERT INTO principals(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES (?, 'installer', ?, NULL, ?, ?)",
|
||||
(INSTALLER, class_id, INSTALLER, now),
|
||||
)
|
||||
issuer_id = c.execute(
|
||||
"INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) VALUES ('operator-key', ?, ?)",
|
||||
(DISTINGUISHED_ISSUER_ID, now),
|
||||
).lastrowid
|
||||
c.execute(
|
||||
"UPDATE principals SET issuer_id = ? WHERE principal_id = ?",
|
||||
(issuer_id, INSTALLER),
|
||||
)
|
||||
c.executemany(
|
||||
"INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)",
|
||||
dominance,
|
||||
)
|
||||
c.execute(
|
||||
"INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) VALUES (1, ?, ?)",
|
||||
(INSTALLER, now),
|
||||
)
|
||||
c.execute(
|
||||
"INSERT INTO platform_bootstrap_grants(grantee_principal_id, granted_by, active, created_at) VALUES (?, NULL, 1, ?)",
|
||||
(INSTALLER, now),
|
||||
)
|
||||
c.execute("INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)")
|
||||
c.execute(
|
||||
"INSERT INTO install_state(id, marker, installed_at) VALUES (1, 'installed', ?)",
|
||||
(now,),
|
||||
)
|
||||
k._conn.execute("COMMIT")
|
||||
return INSTALLED
|
||||
except sqlite3.Error as exc:
|
||||
k._safe_rollback()
|
||||
return PlatformKernel._classify(exc)
|
||||
|
||||
|
||||
class Arch01ConcurrencyTest(unittest.TestCase):
|
||||
"""Concurrency invariants require file-backed DBs and independent connections."""
|
||||
|
||||
def setUp(self) -> None:
|
||||
self._tmp = tempfile.TemporaryDirectory()
|
||||
self.path = os.path.join(self._tmp.name, "p.sqlite3")
|
||||
|
||||
def tearDown(self) -> None:
|
||||
self._tmp.cleanup()
|
||||
|
||||
# -- AC10 ------------------------------------------------------------- #
|
||||
def test_concurrent_install(self) -> None: # t_concurrent_install(concurrency)
|
||||
k1 = PlatformKernel(self.path, busy_timeout_ms=0)
|
||||
k2 = PlatformKernel(self.path, busy_timeout_ms=0)
|
||||
barrier = threading.Barrier(2)
|
||||
results = {}
|
||||
|
||||
def _install(name, kernel):
|
||||
barrier.wait()
|
||||
results[name] = kernel.install_platform(INSTALLER).code
|
||||
|
||||
try:
|
||||
with ThreadPoolExecutor(max_workers=2) as ex:
|
||||
f1 = ex.submit(_install, "a", k1)
|
||||
f2 = ex.submit(_install, "b", k2)
|
||||
f1.result()
|
||||
f2.result()
|
||||
codes = sorted(results.values())
|
||||
self.assertEqual(codes.count(INSTALLED), 1, f"exactly one install expected: {results}")
|
||||
other = [c for c in results.values() if c != INSTALLED][0]
|
||||
self.assertIn(other, (ALREADY_INSTALLED, CONCURRENT_INSTALLATION_LOST))
|
||||
self.assertTrue(k1.is_installed())
|
||||
self.assertEqual(_count(k1, "install_state"), 1)
|
||||
self.assertEqual(_count(k1, "principals"), 1)
|
||||
finally:
|
||||
k1.close()
|
||||
k2.close()
|
||||
|
||||
# -- AC11 ------------------------------------------------------------- #
|
||||
def test_concurrent_last_grant_revoke(self) -> None: # t_concurrent_last_grant_revoke
|
||||
setup = PlatformKernel(self.path)
|
||||
self.assertEqual(setup.install_platform(INSTALLER).code, INSTALLED)
|
||||
setup.register_principal("op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER)
|
||||
self.assertEqual(setup.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED)
|
||||
self.assertEqual(setup.active_grant_count(), 2)
|
||||
gids = [
|
||||
r[0]
|
||||
for r in setup._conn.execute(
|
||||
"SELECT grant_id FROM platform_bootstrap_grants WHERE active = 1 ORDER BY grant_id"
|
||||
).fetchall()
|
||||
]
|
||||
setup.close()
|
||||
self.assertEqual(len(gids), 2)
|
||||
|
||||
k1 = PlatformKernel(self.path, busy_timeout_ms=3000)
|
||||
k2 = PlatformKernel(self.path, busy_timeout_ms=3000)
|
||||
barrier = threading.Barrier(2)
|
||||
results = {}
|
||||
|
||||
def _revoke(name, kernel, gid):
|
||||
barrier.wait()
|
||||
results[name] = kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code
|
||||
|
||||
try:
|
||||
with ThreadPoolExecutor(max_workers=2) as ex:
|
||||
f1 = ex.submit(_revoke, "a", k1, gids[0])
|
||||
f2 = ex.submit(_revoke, "b", k2, gids[1])
|
||||
f1.result()
|
||||
f2.result()
|
||||
codes = list(results.values())
|
||||
self.assertEqual(codes.count(INSTALLED), 1, f"exactly one revoke should win: {results}")
|
||||
self.assertEqual(codes.count(AUTHORIZATION_DENIED), 1, f"one revoke must be denied: {results}")
|
||||
self.assertEqual(k1.active_grant_count(), 1)
|
||||
self.assertEqual(_count_where(k1, "platform_bootstrap_grants", "active = 1"), 1)
|
||||
finally:
|
||||
k1.close()
|
||||
k2.close()
|
||||
|
||||
def test_revoke_final_grant_denied(self) -> None:
|
||||
k = PlatformKernel(self.path)
|
||||
try:
|
||||
self.assertEqual(k.install_platform(INSTALLER).code, INSTALLED)
|
||||
gid = k._conn.execute(
|
||||
"SELECT grant_id FROM platform_bootstrap_grants WHERE active = 1"
|
||||
).fetchone()[0]
|
||||
res = k.revoke_platform_bootstrap(gid, actor_principal=INSTALLER)
|
||||
self.assertEqual(res.code, AUTHORIZATION_DENIED)
|
||||
self.assertEqual(k.active_grant_count(), 1)
|
||||
self.assertEqual(_count_where(k, "platform_bootstrap_grants", "active = 1"), 1)
|
||||
finally:
|
||||
k.close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,622 +0,0 @@
|
||||
"""Publication preflight must receive the caller's worktree (#815).
|
||||
|
||||
``gitea_publish_unpublished_issue_branch`` takes a **required** ``worktree_path``
|
||||
but resolved it only *after* ``verify_preflight_purity`` had already run. Every
|
||||
workspace-resolution layer behind that preflight — canonical root, root checkout,
|
||||
create-issue bootstrap, the #618 branches-only guard, issue scope, and anti-stomp
|
||||
— therefore received ``None`` and fell back to the MCP process root. A daemon
|
||||
rooted at the stable control checkout refused a valid registered issue worktree
|
||||
that the caller had explicitly supplied, before the publication assessor ever ran.
|
||||
|
||||
The #812 suite could not see this. Its fixture sets ``self.worktree =
|
||||
os.path.realpath(self.repo)`` and patches ``PROJECT_ROOT`` to that same path, so
|
||||
the fallback resolved to the very worktree the argument named. The production
|
||||
topology — control checkout on a stable branch, issue worktree somewhere else —
|
||||
was never constructed, and preflight additionally no-ops under pytest unless
|
||||
production guards are forced on.
|
||||
|
||||
These tests build that topology honestly:
|
||||
|
||||
* ``PROJECT_ROOT`` is a control checkout sitting on ``master``;
|
||||
* the registered issue worktree is a genuinely separate path under ``branches/``;
|
||||
* ``GITEA_TEST_FORCE_PRODUCTION_GUARDS`` is set so the #618 guard really runs;
|
||||
* no patch makes the issue worktree appear to be ``PROJECT_ROOT``.
|
||||
|
||||
Nothing here reads, writes, or references the protected worktree named in #812
|
||||
AC17 and #815 AC9. Every fixture is built from scratch against a local bare
|
||||
remote, so publication and read-after-write verification genuinely execute.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from datetime import datetime, timedelta, timezone
|
||||
from unittest.mock import patch
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
import issue_lock_provenance # noqa: E402
|
||||
import issue_lock_store # noqa: E402
|
||||
import mcp_server # noqa: E402
|
||||
from mutation_profile_fixture import shared_mutation_env # noqa: E402
|
||||
|
||||
ISSUE = 9815
|
||||
BRANCH = f"feat/issue-{ISSUE}-forwarding-fixture"
|
||||
WORKTREE_DIRNAME = BRANCH.replace("/", "-")
|
||||
IDENTITY = "example-user"
|
||||
PROFILE = "test-author-prgs"
|
||||
ORG = "Scaled-Tech-Consulting"
|
||||
REPO = "Gitea-Tools"
|
||||
GIT_REMOTE = "prgs"
|
||||
|
||||
AUTHOR_PROFILE = {
|
||||
"profile_name": "prgs-author",
|
||||
"role": "author",
|
||||
"allowed_operations": [
|
||||
"gitea.read", "gitea.issue.create", "gitea.issue.comment",
|
||||
"gitea.pr.create", "gitea.repo.commit", "gitea.branch.push",
|
||||
],
|
||||
"forbidden_operations": [],
|
||||
"audit_label": "prgs-author",
|
||||
}
|
||||
|
||||
|
||||
def _ts(hours: int) -> str:
|
||||
return (
|
||||
(datetime.now(timezone.utc) + timedelta(hours=hours))
|
||||
.isoformat()
|
||||
.replace("+00:00", "Z")
|
||||
)
|
||||
|
||||
|
||||
class TestPreflightReceivesTheWorktree(unittest.TestCase):
|
||||
"""AC1 — the supplied path reaches ``verify_preflight_purity`` itself.
|
||||
|
||||
Follows the #735 capture pattern: replace preflight with a recorder that
|
||||
raises, so the argument can be proven forwarded without performing the
|
||||
mutation. This is the direct unit-level statement of the defect.
|
||||
"""
|
||||
|
||||
def _capture_preflight(self, **kwargs):
|
||||
captured: dict = {}
|
||||
|
||||
def _capture(*a, **kw):
|
||||
captured.update(kw)
|
||||
captured["_args"] = a
|
||||
raise RuntimeError("capture-only")
|
||||
|
||||
with patch.object(
|
||||
mcp_server, "verify_preflight_purity", side_effect=_capture
|
||||
), patch.object(
|
||||
mcp_server, "get_profile", return_value=AUTHOR_PROFILE
|
||||
), patch.object(
|
||||
mcp_server, "_resolve",
|
||||
return_value=("gitea.prgs.cc", ORG, REPO),
|
||||
), patch.object(
|
||||
mcp_server, "_auth", return_value="token fake",
|
||||
), patch.object(
|
||||
mcp_server.role_session_router,
|
||||
"check_author_mutation_after_reviewer_stop",
|
||||
return_value=(True, []),
|
||||
), patch.object(
|
||||
mcp_server, "_namespace_mutation_block", return_value=None
|
||||
), patch.object(
|
||||
mcp_server, "_profile_permission_block", return_value=None
|
||||
):
|
||||
try:
|
||||
mcp_server.gitea_publish_unpublished_issue_branch(**kwargs)
|
||||
except RuntimeError as exc:
|
||||
if "capture-only" not in str(exc) and not captured:
|
||||
raise
|
||||
self.assertTrue(
|
||||
captured,
|
||||
"gitea_publish_unpublished_issue_branch never called "
|
||||
"verify_preflight_purity",
|
||||
)
|
||||
return captured
|
||||
|
||||
def _base_kwargs(self, **overrides):
|
||||
kwargs = {
|
||||
"issue_number": ISSUE,
|
||||
"branch_name": BRANCH,
|
||||
"worktree_path": "/tmp/issue-815-explicit-worktree",
|
||||
"expected_head": "a" * 40,
|
||||
"remote": "prgs",
|
||||
"org": ORG,
|
||||
"repo": REPO,
|
||||
"git_remote_name": GIT_REMOTE,
|
||||
}
|
||||
kwargs.update(overrides)
|
||||
return kwargs
|
||||
|
||||
def test_explicit_worktree_path_reaches_preflight(self):
|
||||
captured = self._capture_preflight(**self._base_kwargs())
|
||||
self.assertEqual(
|
||||
captured.get("worktree_path"),
|
||||
os.path.realpath(os.path.abspath("/tmp/issue-815-explicit-worktree")),
|
||||
"the authoritative worktree_path must be forwarded into preflight",
|
||||
)
|
||||
|
||||
def test_forwarded_path_is_the_one_publication_uses(self):
|
||||
"""AC4 — preflight and publication must judge the same resolved path."""
|
||||
raw = "/tmp/issue-815-explicit-worktree/./"
|
||||
captured = self._capture_preflight(**self._base_kwargs(worktree_path=raw))
|
||||
expected = os.path.realpath(os.path.abspath(raw.strip()))
|
||||
self.assertEqual(captured.get("worktree_path"), expected)
|
||||
|
||||
def test_blank_worktree_path_forwards_none(self):
|
||||
"""AC5/AC8 — nothing usable supplied keeps the fail-closed fallback."""
|
||||
for blank in ("", " "):
|
||||
with self.subTest(blank=repr(blank)):
|
||||
captured = self._capture_preflight(
|
||||
**self._base_kwargs(worktree_path=blank)
|
||||
)
|
||||
self.assertIsNone(
|
||||
captured.get("worktree_path"),
|
||||
"a blank worktree must not resolve to the process cwd",
|
||||
)
|
||||
|
||||
def test_org_repo_and_task_forwarding_are_not_regressed(self):
|
||||
"""AC6 — #735's org/repo forwarding and the task name still hold."""
|
||||
captured = self._capture_preflight(**self._base_kwargs())
|
||||
self.assertEqual(captured.get("org"), ORG)
|
||||
self.assertEqual(captured.get("repo"), REPO)
|
||||
self.assertEqual(captured.get("task"), "publish_unpublished_branch")
|
||||
|
||||
|
||||
class _ProductionTopologyBase(unittest.TestCase):
|
||||
"""Control checkout on master + a distinct registered issue worktree.
|
||||
|
||||
This is the shape the production daemon runs in and the shape the #812
|
||||
fixture never built. ``PROJECT_ROOT`` is the control checkout; the issue
|
||||
worktree is a real registered worktree at a different path; production
|
||||
guards are forced on so the #618 branches-only guard genuinely evaluates.
|
||||
"""
|
||||
|
||||
def setUp(self):
|
||||
self.lock_dir = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.lock_dir.cleanup)
|
||||
self.origin = tempfile.mkdtemp(prefix="issue815-origin-")
|
||||
self.control = tempfile.mkdtemp(prefix="issue815-control-")
|
||||
for path in (self.origin, self.control):
|
||||
self.addCleanup(
|
||||
lambda p=path: subprocess.run(["rm", "-rf", p], check=False)
|
||||
)
|
||||
self._init_repos()
|
||||
self.remotes = patch.dict(
|
||||
mcp_server.REMOTES,
|
||||
{"prgs": {"host": "gitea.prgs.cc", "org": ORG, "repo": REPO}},
|
||||
)
|
||||
self.remotes.start()
|
||||
self.addCleanup(patch.stopall)
|
||||
mcp_server._IDENTITY_CACHE.clear()
|
||||
|
||||
def _git(self, *args, cwd=None):
|
||||
return subprocess.run(
|
||||
["git", "-C", cwd or self.control, *args],
|
||||
capture_output=True, text=True, check=True,
|
||||
)
|
||||
|
||||
def _init_repos(self):
|
||||
subprocess.run(
|
||||
["git", "init", "-q", "--bare", "-b", "master", self.origin], check=True
|
||||
)
|
||||
self._git("init", "-q", "-b", "master")
|
||||
self._git("config", "user.email", "[email protected]")
|
||||
self._git("config", "user.name", "Test")
|
||||
self._git("remote", "add", GIT_REMOTE, self.origin)
|
||||
|
||||
with open(os.path.join(self.control, "seed.txt"), "w") as fh:
|
||||
fh.write("seed\n")
|
||||
# The real repository gitignores branches/, so a registered worktree
|
||||
# living there does not dirty the stable control checkout. Mirror that,
|
||||
# or the #615 dirty-runtime block fires on the worktree we just created.
|
||||
with open(os.path.join(self.control, ".gitignore"), "w") as fh:
|
||||
fh.write("branches/\n")
|
||||
self._git("add", "seed.txt", ".gitignore")
|
||||
self._git("commit", "-q", "-m", "seed")
|
||||
self.base_sha = self._git("rev-parse", "HEAD").stdout.strip()
|
||||
self._git("push", "-q", GIT_REMOTE, "master")
|
||||
|
||||
# The control checkout STAYS on master. This is the whole point: the
|
||||
# daemon's process root is the stable control checkout, never the
|
||||
# worktree the publication targets.
|
||||
self.worktree = os.path.realpath(
|
||||
os.path.join(self.control, "branches", WORKTREE_DIRNAME)
|
||||
)
|
||||
self._git("worktree", "add", "-q", "-b", BRANCH, self.worktree, "master")
|
||||
|
||||
with open(os.path.join(self.worktree, "work.txt"), "w") as fh:
|
||||
fh.write("unpublished implementation\n")
|
||||
self._git("add", "work.txt", cwd=self.worktree)
|
||||
self._git("commit", "-q", "-m", "unpublished implementation", cwd=self.worktree)
|
||||
self.head_sha = self._git("rev-parse", "HEAD", cwd=self.worktree).stdout.strip()
|
||||
|
||||
self.control_branch = self._git(
|
||||
"rev-parse", "--abbrev-ref", "HEAD"
|
||||
).stdout.strip()
|
||||
|
||||
# ── durable lock naming the caller and the issue worktree ────────────
|
||||
def lock_path(self):
|
||||
return issue_lock_store.lock_file_path(
|
||||
remote="prgs", org=ORG, repo=REPO, issue_number=ISSUE,
|
||||
lock_dir=self.lock_dir.name,
|
||||
)
|
||||
|
||||
def write_lock(self, *, bind_session=True, **overrides):
|
||||
path = self.lock_path()
|
||||
claimant = overrides.pop(
|
||||
"claimant", {"username": IDENTITY, "profile": PROFILE}
|
||||
)
|
||||
pid = overrides.pop("session_pid", os.getpid())
|
||||
lease = {
|
||||
"operation_type": issue_lock_store.AUTHOR_ISSUE_WORK_LEASE,
|
||||
"issue_number": ISSUE,
|
||||
"pr_number": None,
|
||||
"branch": overrides.get("branch_name", BRANCH),
|
||||
"worktree_path": overrides.get("worktree_path", self.worktree),
|
||||
"claimant": claimant,
|
||||
"created_at": _ts(-2),
|
||||
"last_heartbeat_at": _ts(-2),
|
||||
"expires_at": _ts(-1),
|
||||
}
|
||||
lease.update(overrides.pop("work_lease", {}))
|
||||
data = {
|
||||
"issue_number": ISSUE,
|
||||
"branch_name": BRANCH,
|
||||
"remote": "prgs",
|
||||
"org": ORG,
|
||||
"repo": REPO,
|
||||
"worktree_path": self.worktree,
|
||||
"session_pid": pid,
|
||||
"pid": pid,
|
||||
"lock_generation": 1,
|
||||
"work_lease": lease,
|
||||
"lock_provenance": issue_lock_provenance.build_sanctioned_lock_provenance(
|
||||
tool="gitea_lock_issue", claimant=claimant
|
||||
),
|
||||
}
|
||||
data.update(overrides)
|
||||
data["lock_file_path"] = path
|
||||
issue_lock_store.save_lock_file(path, data)
|
||||
# Bind the session pointer so the #683 issue-scope guard resolves an
|
||||
# owning issue for this author session. In real production the publish
|
||||
# task does not require a session lock — require_author_lock is keyed on
|
||||
# the test-only production_guards_forced() flag, which this suite must
|
||||
# set to make preflight run at all — so this pointer is fixture
|
||||
# scaffolding to clear a guard production would not apply here, never a
|
||||
# softening of the worktree-forwarding behaviour under test. The
|
||||
# preflight-negative cases below leave it unbound precisely so the #618
|
||||
# guard is reached with no session fallback to rescue a bad worktree.
|
||||
if bind_session:
|
||||
pointer = {
|
||||
"pid": os.getpid(),
|
||||
"lock_file_path": path,
|
||||
"issue_number": ISSUE,
|
||||
"branch_name": data["branch_name"],
|
||||
"remote": "prgs",
|
||||
"org": ORG,
|
||||
"repo": REPO,
|
||||
}
|
||||
issue_lock_store.save_lock_file(
|
||||
issue_lock_store.session_pointer_path(self.lock_dir.name), pointer
|
||||
)
|
||||
return path
|
||||
|
||||
def _tool_env(self):
|
||||
env = shared_mutation_env(
|
||||
PROFILE, include_example_repo=True,
|
||||
GITEA_ISSUE_LOCK_DIR=self.lock_dir.name,
|
||||
)
|
||||
env["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
|
||||
# The defect only exists where preflight actually runs. Under pytest the
|
||||
# production root/branches/scope guards are skipped unless forced on, so
|
||||
# force them: this test exists to exercise the #618 guard, not to bypass
|
||||
# it. Parity is pinned to the server's own startup head so repointing
|
||||
# PROJECT_ROOT does not read as a stale daemon.
|
||||
env["GITEA_TEST_FORCE_PRODUCTION_GUARDS"] = "1"
|
||||
# Production is a promoted stable-control runtime. The pytest process
|
||||
# itself runs from a branches/ worktree, which the #615 runtime-mode
|
||||
# gate correctly classifies as dev-test; declaring the sanctioned mode
|
||||
# models the production daemon rather than defeating the gate. Without
|
||||
# this, forcing production guards on would trip the *runtime-mode* block
|
||||
# for a reason unrelated to the #815 worktree-forwarding defect.
|
||||
env["GITEA_MCP_RUNTIME_MODE"] = "stable-control"
|
||||
startup_head = mcp_server._STARTUP_PARITY.get("startup_head") or ""
|
||||
env["GITEA_TEST_CURRENT_HEAD"] = startup_head
|
||||
env["GITEA_TEST_LIVE_REMOTE_HEAD"] = startup_head
|
||||
return env
|
||||
|
||||
def run_publish(self, *, open_prs=None, expected_head=None, **kwargs):
|
||||
"""Drive the public tool with PROJECT_ROOT pinned to the CONTROL checkout."""
|
||||
env = self._tool_env()
|
||||
with patch(
|
||||
"mcp_server._list_open_pulls", return_value=list(open_prs or [])
|
||||
), patch(
|
||||
"mcp_server._auth", return_value="token x"
|
||||
), patch(
|
||||
"mcp_server.get_auth_header", return_value="token x"
|
||||
), patch(
|
||||
"mcp_server._work_lease_claimant",
|
||||
return_value={"username": IDENTITY, "profile": PROFILE},
|
||||
), patch.object(
|
||||
# NOTE: the control checkout — deliberately NOT self.worktree.
|
||||
mcp_server, "PROJECT_ROOT", self.control
|
||||
), patch.dict(os.environ, env, clear=True):
|
||||
os.environ["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
|
||||
return mcp_server.gitea_publish_unpublished_issue_branch(
|
||||
issue_number=kwargs.pop("issue_number", ISSUE),
|
||||
branch_name=kwargs.pop("branch_name", BRANCH),
|
||||
worktree_path=kwargs.pop("worktree_path", self.worktree),
|
||||
expected_head=expected_head or self.head_sha,
|
||||
remote="prgs",
|
||||
git_remote_name=kwargs.pop("git_remote_name", GIT_REMOTE),
|
||||
**kwargs,
|
||||
)
|
||||
|
||||
def remote_head(self, branch=BRANCH):
|
||||
res = subprocess.run(
|
||||
["git", "-C", self.origin, "rev-parse", "--verify", "--quiet", branch],
|
||||
capture_output=True, text=True, check=False,
|
||||
)
|
||||
return (res.stdout or "").strip() or None
|
||||
|
||||
|
||||
class TestForwardingClearsThe618Guard(_ProductionTopologyBase):
|
||||
"""AC2 — the faithful production reproduction, and the sharpest fix proof.
|
||||
|
||||
The production recovery worker had **no** session issue lock — acquiring one
|
||||
was the very thing the deadlock prevented — so preflight had nothing but the
|
||||
explicit ``worktree_path`` argument to resolve the workspace from. This class
|
||||
reproduces exactly that: no session pointer is bound, so there is no
|
||||
author-lock fallback to rescue a dropped argument.
|
||||
|
||||
With the argument forwarded (fixed source) the #618 branches-only guard
|
||||
accepts the registered issue worktree and the call advances to the next
|
||||
guard. With the argument dropped (the buggy source this issue reports)
|
||||
preflight falls back to ``PROJECT_ROOT`` — the stable control checkout — and
|
||||
the #618 guard traps the call there. The two outcomes are told apart by the
|
||||
guard that fired, on its own error text.
|
||||
|
||||
This test therefore *fails* against the unpatched source (the call is trapped
|
||||
at #618 instead of clearing it), which is what makes it a regression rather
|
||||
than a smoke test.
|
||||
"""
|
||||
|
||||
_CONTROL_CHECKOUT_MARKERS = ("stable control checkout", "#618")
|
||||
|
||||
def test_explicit_worktree_clears_618_without_a_session_lock(self):
|
||||
# No write_lock(): the session is deliberately unbound, as in production.
|
||||
with self.assertRaises(RuntimeError) as ctx:
|
||||
self.run_publish()
|
||||
message = str(ctx.exception)
|
||||
# The workspace guard is satisfied — the failure is the *later* scope
|
||||
# guard (no owning issue), never the control-checkout refusal. If the
|
||||
# argument were dropped, this call would be trapped at #618 instead.
|
||||
for marker in self._CONTROL_CHECKOUT_MARKERS:
|
||||
self.assertNotIn(
|
||||
marker, message,
|
||||
f"the explicit worktree must clear #618; got a control-checkout "
|
||||
f"refusal instead: {message}",
|
||||
)
|
||||
self.assertIn(
|
||||
"owning issue", message,
|
||||
f"expected the downstream scope guard to fire, got: {message}",
|
||||
)
|
||||
self.assertIsNone(self.remote_head())
|
||||
|
||||
def test_dropped_argument_would_be_trapped_at_618(self):
|
||||
# Simulate the buggy call shape directly: no session lock, and preflight
|
||||
# given no worktree, exactly as the unpatched source left it. This pins
|
||||
# the control-checkout refusal that the fix eliminates, so the pair of
|
||||
# tests brackets the defect from both sides regardless of which source
|
||||
# version is loaded.
|
||||
env = self._tool_env()
|
||||
with patch(
|
||||
"mcp_server._list_open_pulls", return_value=[]
|
||||
), patch(
|
||||
"mcp_server._auth", return_value="token x"
|
||||
), patch(
|
||||
"mcp_server.get_auth_header", return_value="token x"
|
||||
), patch(
|
||||
"mcp_server._work_lease_claimant",
|
||||
return_value={"username": IDENTITY, "profile": PROFILE},
|
||||
), patch.object(
|
||||
mcp_server, "PROJECT_ROOT", self.control
|
||||
), patch.dict(os.environ, env, clear=True):
|
||||
os.environ["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
|
||||
with self.assertRaises(RuntimeError) as ctx:
|
||||
# Drive verify_preflight_purity the way the buggy body did:
|
||||
# no worktree_path forwarded at all.
|
||||
mcp_server.verify_preflight_purity(
|
||||
"prgs",
|
||||
task="publish_unpublished_branch",
|
||||
org=ORG,
|
||||
repo=REPO,
|
||||
)
|
||||
message = str(ctx.exception)
|
||||
self.assertTrue(
|
||||
any(m in message for m in self._CONTROL_CHECKOUT_MARKERS),
|
||||
f"a dropped worktree must trap at the control checkout: {message}",
|
||||
)
|
||||
self.assertIsNone(self.remote_head())
|
||||
|
||||
|
||||
class TestProductionTopologyPublishes(_ProductionTopologyBase):
|
||||
"""AC2/AC4/AC7 — the explicit registered worktree is what preflight validates."""
|
||||
|
||||
def test_fixture_is_genuinely_the_production_topology(self):
|
||||
"""Guard the guard: if this drifts, the regression stops meaning anything."""
|
||||
self.assertNotEqual(
|
||||
os.path.realpath(self.control), self.worktree,
|
||||
"the issue worktree must not be PROJECT_ROOT",
|
||||
)
|
||||
self.assertEqual(
|
||||
self.control_branch, "master",
|
||||
"the control checkout must sit on a stable branch",
|
||||
)
|
||||
self.assertTrue(
|
||||
os.path.realpath(self.worktree).startswith(
|
||||
os.path.realpath(os.path.join(self.control, "branches")) + os.sep
|
||||
),
|
||||
"the issue worktree must live under branches/",
|
||||
)
|
||||
listed = subprocess.run(
|
||||
["git", "-C", self.control, "worktree", "list"],
|
||||
capture_output=True, text=True, check=True,
|
||||
).stdout
|
||||
self.assertIn(
|
||||
self.worktree, listed, "the issue worktree must be genuinely registered"
|
||||
)
|
||||
|
||||
def test_publishes_from_a_control_rooted_daemon(self):
|
||||
"""The exact production failure: this refused with #618 before the fix."""
|
||||
self.write_lock()
|
||||
self.assertIsNone(self.remote_head(), "fixture must start unpublished")
|
||||
res = self.run_publish()
|
||||
self.assertTrue(res.get("success"), res)
|
||||
self.assertTrue(res.get("performed"), res)
|
||||
self.assertEqual(self.remote_head(), self.head_sha)
|
||||
|
||||
def test_dry_run_uses_the_explicit_worktree(self):
|
||||
"""AC4 — dry-run reaches the same decision without publishing."""
|
||||
self.write_lock()
|
||||
res = self.run_publish(dry_run=True)
|
||||
self.assertTrue(res.get("success"), res)
|
||||
self.assertFalse(res.get("performed"), res)
|
||||
self.assertTrue(res.get("would_publish"), res)
|
||||
self.assertIsNone(self.remote_head(), "dry-run must not publish")
|
||||
|
||||
def test_dry_run_and_apply_agree_on_the_same_worktree(self):
|
||||
"""AC4 — both paths resolve the same workspace, so both succeed."""
|
||||
self.write_lock()
|
||||
dry = self.run_publish(dry_run=True)
|
||||
self.assertTrue(dry.get("would_publish"), dry)
|
||||
applied = self.run_publish()
|
||||
self.assertTrue(applied.get("performed"), applied)
|
||||
self.assertEqual(self.remote_head(), self.head_sha)
|
||||
|
||||
def test_read_after_write_verification_still_runs(self):
|
||||
"""AC6 — PR #814's post-publication verification is unchanged."""
|
||||
self.write_lock()
|
||||
res = self.run_publish()
|
||||
self.assertTrue(res.get("verified"), res)
|
||||
self.assertEqual(res.get("remote_head_sha"), self.head_sha)
|
||||
|
||||
|
||||
class TestProductionTopologyFailsClosed(_ProductionTopologyBase):
|
||||
"""AC3/AC5/AC8 — the fix does not weaken any refusal.
|
||||
|
||||
A refusal reaches the caller by one of two mechanisms, and this class holds
|
||||
them apart deliberately. A bad *workspace* is caught by the #618 preflight
|
||||
guard, which raises before the assessor is built. A bad *content/ownership*
|
||||
fact passes preflight (the worktree itself is fine) and is then refused by
|
||||
the publication assessor, which returns ``success: False``. Both are
|
||||
fail-closed; asserting the wrong mechanism would hide a regression.
|
||||
"""
|
||||
|
||||
# ── #618 preflight refusals: no session lock, so nothing rescues a bad
|
||||
# workspace and the guard fires exactly as it does in production ──────
|
||||
def _assert_preflight_raises(self, **kwargs):
|
||||
with self.assertRaises(RuntimeError) as ctx:
|
||||
self.run_publish(**kwargs)
|
||||
self.assertIsNone(
|
||||
self.remote_head(), "a blocked publication must not reach the remote"
|
||||
)
|
||||
return str(ctx.exception)
|
||||
|
||||
def test_blank_worktree_path_fails_closed_via_618(self):
|
||||
"""AC5 — a blank path forwards None, so preflight sees the control root."""
|
||||
for blank in ("", " "):
|
||||
with self.subTest(blank=repr(blank)):
|
||||
message = self._assert_preflight_raises(worktree_path=blank)
|
||||
self.assertIn("618", message)
|
||||
|
||||
def test_control_checkout_as_worktree_fails_closed_via_618(self):
|
||||
"""AC5 — naming the stable control checkout explicitly is still refused."""
|
||||
message = self._assert_preflight_raises(worktree_path=self.control)
|
||||
self.assertIn("618", message)
|
||||
|
||||
def test_unregistered_directory_fails_closed(self):
|
||||
"""AC3 — a plain directory under branches/ is not a registered worktree."""
|
||||
bogus = os.path.join(self.control, "branches", "not-a-worktree")
|
||||
os.makedirs(bogus, exist_ok=True)
|
||||
self._assert_preflight_raises(worktree_path=bogus)
|
||||
|
||||
def test_missing_worktree_path_fails_closed(self):
|
||||
"""AC3 — a path that does not exist is refused, not silently replaced."""
|
||||
missing = os.path.join(self.control, "branches", "absent-worktree")
|
||||
self._assert_preflight_raises(worktree_path=missing)
|
||||
|
||||
# ── assessor refusals: preflight passes on a valid worktree, then the
|
||||
# publication assessor refuses on content/ownership evidence ──────────
|
||||
def _assert_assessor_refuses(self, **kwargs):
|
||||
res = self.run_publish(**kwargs)
|
||||
self.assertFalse(res.get("success"), res)
|
||||
self.assertFalse(res.get("performed"), res)
|
||||
self.assertIsNone(self.remote_head())
|
||||
return res
|
||||
|
||||
def test_changed_local_head_still_refuses(self):
|
||||
"""AC6 — the declared expected_head remains authoritative."""
|
||||
self.write_lock()
|
||||
self._assert_assessor_refuses(expected_head="b" * 40)
|
||||
|
||||
def test_foreign_claimant_still_refuses(self):
|
||||
"""AC6 — ownership still comes from the durable lock record."""
|
||||
self.write_lock(claimant={"username": "someone-else", "profile": PROFILE})
|
||||
self._assert_assessor_refuses()
|
||||
|
||||
def test_dirty_worktree_still_refuses(self):
|
||||
"""AC6 — cleanliness enforcement survives the forwarding change."""
|
||||
self.write_lock()
|
||||
with open(os.path.join(self.worktree, "work.txt"), "a") as fh:
|
||||
fh.write("uncommitted drift\n")
|
||||
self._assert_assessor_refuses()
|
||||
|
||||
def test_competing_open_pr_still_refuses(self):
|
||||
"""AC6 — a rival claim on another branch still blocks."""
|
||||
self.write_lock()
|
||||
self._assert_assessor_refuses(
|
||||
open_prs=[{"number": 4242, "head": {"ref": f"fix/issue-{ISSUE}-rival"}}]
|
||||
)
|
||||
|
||||
def test_issue_lock_record_is_not_mutated_by_a_refusal(self):
|
||||
"""AC6 — record separation (#812 AC23) is unaffected by this change."""
|
||||
path = self.write_lock()
|
||||
with open(path, "rb") as fh:
|
||||
before = fh.read()
|
||||
self._assert_assessor_refuses(expected_head="c" * 40)
|
||||
with open(path, "rb") as fh:
|
||||
self.assertEqual(before, fh.read())
|
||||
|
||||
|
||||
class TestProtectedFixtureNotReferenced(unittest.TestCase):
|
||||
"""AC9 — this regression never names the protected #635 fixture.
|
||||
|
||||
The forbidden tokens are reconstructed from fragments so this assertion
|
||||
file does not itself contain them and produce a false positive.
|
||||
"""
|
||||
|
||||
def test_no_reference_to_the_protected_worktree(self):
|
||||
forbidden = [
|
||||
"issue-635-" + "project-registry-api",
|
||||
"b2f6e9a6dc40e9651ef8" + "76f322dd0a68bddebfd8",
|
||||
]
|
||||
here = os.path.abspath(__file__)
|
||||
with open(here, "r", encoding="utf-8") as fh:
|
||||
text = fh.read()
|
||||
for token in forbidden:
|
||||
self.assertNotIn(
|
||||
token, text,
|
||||
f"the protected #635 fixture must not be referenced: {token}",
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Tests for web UI project registry (#427) and its API evolution (#635)."""
|
||||
"""Tests for web UI project registry (#427)."""
|
||||
import json
|
||||
import sys
|
||||
import tempfile
|
||||
@@ -11,246 +11,57 @@ from starlette.testclient import TestClient
|
||||
|
||||
from webui.app import create_app
|
||||
from webui.project_registry import (
|
||||
CURRENT_SCHEMA_VERSION,
|
||||
REGISTRY_API_VERSION,
|
||||
SUPPORTED_SCHEMA_VERSIONS,
|
||||
RegistryError,
|
||||
default_registry_path,
|
||||
load_registry,
|
||||
onboarding_summary,
|
||||
project_to_dict,
|
||||
)
|
||||
from webui.registry_safety import is_forbidden_key
|
||||
|
||||
_REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
_API_DOC = _REPO_ROOT / "docs" / "webui-project-registry-api.md"
|
||||
|
||||
|
||||
def _valid_project(**overrides):
|
||||
project = {
|
||||
"id": "example",
|
||||
"repo_name": "Example",
|
||||
"gitea_owner": "Org",
|
||||
"remote_host": "https://gitea.example.invalid",
|
||||
"default_branch": "main",
|
||||
"local_checkout_path": ".",
|
||||
"profiles": {"author": "a", "reviewer": "r", "reconciler": "c"},
|
||||
"workflow_paths": {"skill": "skills/x.md"},
|
||||
}
|
||||
project.update(overrides)
|
||||
return project
|
||||
|
||||
|
||||
def _write_registry(payload) -> Path:
|
||||
with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as handle:
|
||||
json.dump(payload, handle)
|
||||
return Path(handle.name)
|
||||
|
||||
|
||||
class RegistryFileCase(unittest.TestCase):
|
||||
"""Base class that cleans up temporary registry files."""
|
||||
|
||||
def setUp(self):
|
||||
self._temp_paths: list[Path] = []
|
||||
|
||||
def tearDown(self):
|
||||
for path in self._temp_paths:
|
||||
path.unlink(missing_ok=True)
|
||||
|
||||
def write_registry(self, payload) -> Path:
|
||||
path = _write_registry(payload)
|
||||
self._temp_paths.append(path)
|
||||
return path
|
||||
|
||||
|
||||
class TestProjectRegistryLoader(RegistryFileCase):
|
||||
class TestProjectRegistryLoader(unittest.TestCase):
|
||||
def test_default_registry_loads_gitea_tools(self):
|
||||
registry = load_registry()
|
||||
self.assertEqual(registry.version, CURRENT_SCHEMA_VERSION)
|
||||
self.assertEqual(registry.schema_version, CURRENT_SCHEMA_VERSION)
|
||||
self.assertEqual(registry.api_version, REGISTRY_API_VERSION)
|
||||
self.assertEqual(registry.version, 1)
|
||||
self.assertEqual(len(registry.projects), 1)
|
||||
project = registry.projects[0]
|
||||
self.assertEqual(project.id, "gitea-tools")
|
||||
self.assertEqual(project.repo_name, "Gitea-Tools")
|
||||
self.assertEqual(project.gitea_owner, "Scaled-Tech-Consulting")
|
||||
self.assertEqual(project.repo_full_name, "Scaled-Tech-Consulting/Gitea-Tools")
|
||||
self.assertEqual(project.remote_host, "https://gitea.prgs.cc")
|
||||
self.assertEqual(project.remote_name, "prgs")
|
||||
self.assertEqual(project.status, "active")
|
||||
self.assertEqual(project.profiles["author"], "prgs-author")
|
||||
self.assertEqual(project.profiles["reviewer"], "prgs-reviewer")
|
||||
self.assertEqual(project.profiles["reconciler"], "prgs-reconciler")
|
||||
self.assertIn("skill", project.workflow_paths)
|
||||
self.assertGreaterEqual(len(project.onboarding_checklist), 4)
|
||||
|
||||
def test_default_registry_onboarding_summary_is_complete(self):
|
||||
summary = onboarding_summary(load_registry().projects[0])
|
||||
self.assertEqual(summary.total, summary.complete)
|
||||
self.assertEqual(summary.required_outstanding, 0)
|
||||
self.assertTrue(summary.onboarding_complete)
|
||||
|
||||
def test_version_1_registry_still_loads_with_defaults(self):
|
||||
path = self.write_registry({
|
||||
"version": 1,
|
||||
"projects": [
|
||||
_valid_project(
|
||||
onboarding_checklist=[
|
||||
{"id": "step", "title": "Step", "description": "Do it"}
|
||||
]
|
||||
)
|
||||
],
|
||||
})
|
||||
registry = load_registry(path)
|
||||
self.assertEqual(registry.schema_version, 1)
|
||||
self.assertIn(1, SUPPORTED_SCHEMA_VERSIONS)
|
||||
project = registry.projects[0]
|
||||
self.assertEqual(project.status, "active")
|
||||
self.assertIsNone(project.remote_name)
|
||||
self.assertIsNone(project.last_seen_health)
|
||||
step = project.onboarding_checklist[0]
|
||||
self.assertEqual(step.state, "pending")
|
||||
self.assertTrue(step.required)
|
||||
self.assertFalse(onboarding_summary(project).onboarding_complete)
|
||||
|
||||
def test_onboarding_summary_counts_states(self):
|
||||
path = self.write_registry({
|
||||
"version": 2,
|
||||
"projects": [
|
||||
_valid_project(
|
||||
onboarding_checklist=[
|
||||
{"id": "a", "title": "A", "description": "d", "state": "complete"},
|
||||
{"id": "b", "title": "B", "description": "d", "state": "blocked"},
|
||||
{
|
||||
"id": "c",
|
||||
"title": "C",
|
||||
"description": "d",
|
||||
"state": "pending",
|
||||
"required": False,
|
||||
},
|
||||
{
|
||||
"id": "d",
|
||||
"title": "D",
|
||||
"description": "d",
|
||||
"state": "not_applicable",
|
||||
},
|
||||
]
|
||||
)
|
||||
],
|
||||
})
|
||||
summary = onboarding_summary(load_registry(path).projects[0])
|
||||
self.assertEqual(summary.total, 4)
|
||||
self.assertEqual(summary.complete, 1)
|
||||
self.assertEqual(summary.blocked, 1)
|
||||
self.assertEqual(summary.pending, 1)
|
||||
self.assertEqual(summary.not_applicable, 1)
|
||||
# Only the blocked step is both required and outstanding.
|
||||
self.assertEqual(summary.required_outstanding, 1)
|
||||
self.assertFalse(summary.onboarding_complete)
|
||||
|
||||
def test_last_seen_health_is_parsed_when_present(self):
|
||||
path = self.write_registry({
|
||||
"version": 2,
|
||||
"projects": [
|
||||
_valid_project(
|
||||
last_seen_health={
|
||||
"status": "degraded",
|
||||
"checked_at": "2026-01-01T00:00:00Z",
|
||||
"detail": "daemon restart pending",
|
||||
}
|
||||
)
|
||||
],
|
||||
})
|
||||
health = load_registry(path).projects[0].last_seen_health
|
||||
self.assertIsNotNone(health)
|
||||
self.assertEqual(health.status, "degraded")
|
||||
self.assertEqual(health.checked_at, "2026-01-01T00:00:00Z")
|
||||
|
||||
def test_registry_rejects_credential_keys(self):
|
||||
path = self.write_registry({
|
||||
payload = {
|
||||
"version": 1,
|
||||
"projects": [_valid_project(id="bad", api_token="redacted-placeholder")],
|
||||
})
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(path)
|
||||
self.assertIn("credential", ctx.exception.remediation.lower())
|
||||
self.assertEqual(ctx.exception.field_path, "projects[0].api_token")
|
||||
|
||||
def test_unsupported_version_fails_closed_with_remediation(self):
|
||||
path = self.write_registry({"version": 99, "projects": [_valid_project()]})
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(path)
|
||||
self.assertIn("unsupported registry version", ctx.exception.message)
|
||||
self.assertIn(str(CURRENT_SCHEMA_VERSION), ctx.exception.remediation)
|
||||
self.assertEqual(ctx.exception.field_path, "version")
|
||||
|
||||
def test_missing_required_field_fails_closed(self):
|
||||
broken = _valid_project()
|
||||
del broken["default_branch"]
|
||||
path = self.write_registry({"version": 2, "projects": [broken]})
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(path)
|
||||
self.assertIn("default_branch", ctx.exception.message)
|
||||
self.assertEqual(ctx.exception.field_path, "projects[0]")
|
||||
|
||||
def test_unknown_status_fails_closed(self):
|
||||
path = self.write_registry({
|
||||
"version": 2,
|
||||
"projects": [_valid_project(status="mystery")],
|
||||
})
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(path)
|
||||
self.assertEqual(ctx.exception.field_path, "projects[0].status")
|
||||
self.assertIn("active", ctx.exception.remediation)
|
||||
|
||||
def test_unknown_onboarding_state_fails_closed(self):
|
||||
path = self.write_registry({
|
||||
"version": 2,
|
||||
"projects": [
|
||||
_valid_project(
|
||||
onboarding_checklist=[
|
||||
{"id": "a", "title": "A", "description": "d", "state": "almost"}
|
||||
]
|
||||
)
|
||||
{
|
||||
"id": "bad",
|
||||
"repo_name": "Bad",
|
||||
"gitea_owner": "Org",
|
||||
"remote_host": "https://gitea.example.invalid",
|
||||
"default_branch": "main",
|
||||
"local_checkout_path": ".",
|
||||
"profiles": {
|
||||
"author": "a",
|
||||
"reviewer": "r",
|
||||
"reconciler": "c",
|
||||
},
|
||||
"workflow_paths": {"skill": "skills/x.md"},
|
||||
"api_token": "secret",
|
||||
}
|
||||
],
|
||||
})
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(path)
|
||||
self.assertEqual(
|
||||
ctx.exception.field_path,
|
||||
"projects[0].onboarding_checklist[0].state",
|
||||
)
|
||||
|
||||
def test_missing_profile_role_fails_closed(self):
|
||||
path = self.write_registry({
|
||||
"version": 2,
|
||||
"projects": [_valid_project(profiles={"author": "a", "reviewer": "r"})],
|
||||
})
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(path)
|
||||
self.assertEqual(ctx.exception.field_path, "projects[0].profiles.reconciler")
|
||||
|
||||
def test_empty_projects_fails_closed(self):
|
||||
path = self.write_registry({"version": 2, "projects": []})
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(path)
|
||||
self.assertEqual(ctx.exception.field_path, "projects")
|
||||
|
||||
def test_invalid_json_fails_closed_with_location(self):
|
||||
}
|
||||
with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as handle:
|
||||
handle.write("{not json")
|
||||
json.dump(payload, handle)
|
||||
path = Path(handle.name)
|
||||
self._temp_paths.append(path)
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(path)
|
||||
self.assertIn("not valid JSON", ctx.exception.message)
|
||||
self.assertIn("line", ctx.exception.remediation)
|
||||
|
||||
def test_missing_file_fails_closed(self):
|
||||
missing = Path(tempfile.gettempdir()) / "webui-registry-does-not-exist.json"
|
||||
with self.assertRaises(RegistryError) as ctx:
|
||||
load_registry(missing)
|
||||
self.assertIn("could not be read", ctx.exception.message)
|
||||
try:
|
||||
with self.assertRaises(ValueError):
|
||||
load_registry(path)
|
||||
finally:
|
||||
path.unlink(missing_ok=True)
|
||||
|
||||
def test_default_registry_path_points_at_packaged_data(self):
|
||||
path = default_registry_path()
|
||||
@@ -270,147 +81,31 @@ class TestProjectRegistryRoutes(unittest.TestCase):
|
||||
self.assertIn("prgs-author", response.text)
|
||||
self.assertNotIn("child issue", response.text.lower())
|
||||
|
||||
def test_projects_page_shows_status_and_progress(self):
|
||||
response = self.client.get("/projects")
|
||||
self.assertIn("Status", response.text)
|
||||
self.assertIn("Onboarding", response.text)
|
||||
self.assertIn("4/4 complete", response.text)
|
||||
|
||||
def test_project_detail_renders_checklist(self):
|
||||
response = self.client.get("/projects/gitea-tools")
|
||||
self.assertEqual(response.status_code, 200)
|
||||
self.assertIn("Onboarding checklist", response.text)
|
||||
self.assertIn("Configure execution profiles", response.text)
|
||||
self.assertIn("branches/", response.text)
|
||||
self.assertIn("Complete", response.text)
|
||||
self.assertIn("required outstanding 0", response.text)
|
||||
|
||||
def test_project_detail_404(self):
|
||||
response = self.client.get("/projects/unknown-repo")
|
||||
self.assertEqual(response.status_code, 404)
|
||||
|
||||
def test_api_projects_alias_stays_compatible(self):
|
||||
def test_api_projects_json(self):
|
||||
response = self.client.get("/api/projects")
|
||||
self.assertEqual(response.status_code, 200)
|
||||
data = response.json()
|
||||
# #427 consumers keep these keys.
|
||||
self.assertEqual(data["version"], CURRENT_SCHEMA_VERSION)
|
||||
self.assertIn("source_path", data)
|
||||
self.assertEqual(data["version"], 1)
|
||||
self.assertEqual(len(data["projects"]), 1)
|
||||
self.assertEqual(data["projects"][0]["id"], "gitea-tools")
|
||||
self.assertIn("onboarding_checklist", data["projects"][0])
|
||||
|
||||
def test_api_v1_projects_payload(self):
|
||||
response = self.client.get("/api/v1/projects")
|
||||
self.assertEqual(response.status_code, 200)
|
||||
data = response.json()
|
||||
self.assertEqual(data["api_version"], REGISTRY_API_VERSION)
|
||||
self.assertEqual(data["schema_version"], CURRENT_SCHEMA_VERSION)
|
||||
self.assertEqual(data["project_count"], 1)
|
||||
self.assertEqual(data["source"]["kind"], "file")
|
||||
self.assertTrue(data["source"]["inventory_complete"])
|
||||
project = data["projects"][0]
|
||||
self.assertEqual(project["status"], "active")
|
||||
self.assertEqual(project["remote_name"], "prgs")
|
||||
self.assertEqual(
|
||||
project["repo_full_name"], "Scaled-Tech-Consulting/Gitea-Tools"
|
||||
)
|
||||
self.assertTrue(project["onboarding_summary"]["onboarding_complete"])
|
||||
self.assertEqual(project["onboarding_checklist"][0]["state"], "complete")
|
||||
self.assertIsNone(project["last_seen_health"])
|
||||
|
||||
def test_api_v1_project_detail(self):
|
||||
response = self.client.get("/api/v1/projects/gitea-tools")
|
||||
self.assertEqual(response.status_code, 200)
|
||||
data = response.json()
|
||||
self.assertEqual(data["api_version"], REGISTRY_API_VERSION)
|
||||
self.assertEqual(data["project"]["id"], "gitea-tools")
|
||||
self.assertEqual(data["source"]["kind"], "file")
|
||||
|
||||
def test_api_v1_project_detail_missing_fails_closed(self):
|
||||
response = self.client.get("/api/v1/projects/not-registered")
|
||||
self.assertEqual(response.status_code, 404)
|
||||
data = response.json()
|
||||
self.assertEqual(data["error"], "project_not_found")
|
||||
self.assertEqual(data["project_id"], "not-registered")
|
||||
self.assertIn("gitea-tools", data["known_project_ids"])
|
||||
self.assertIn("remediation", data)
|
||||
|
||||
def test_api_v1_projects_is_read_only(self):
|
||||
response = self.client.post("/api/v1/projects", json={})
|
||||
self.assertEqual(response.status_code, 405)
|
||||
self.assertEqual(response.json()["error"], "read-only-mvp")
|
||||
|
||||
def test_project_to_dict_is_json_safe(self):
|
||||
registry = load_registry()
|
||||
dto = project_to_dict(registry.projects[0])
|
||||
encoded = json.dumps(dto)
|
||||
encoded = json.dumps(project_to_dict(registry.projects[0]))
|
||||
self.assertIn("gitea-tools", encoded)
|
||||
# Prose may mention tokens; no serialized *key* may look like a secret.
|
||||
for key in dto:
|
||||
with self.subTest(key=key):
|
||||
self.assertFalse(is_forbidden_key(key))
|
||||
|
||||
|
||||
class TestInvalidRegistryFailsClosedOverHttp(RegistryFileCase):
|
||||
def setUp(self):
|
||||
super().setUp()
|
||||
self.path = self.write_registry({"version": 42, "projects": []})
|
||||
self.client = TestClient(create_app())
|
||||
|
||||
def _with_bad_registry(self, url: str):
|
||||
import os
|
||||
from unittest import mock
|
||||
|
||||
with mock.patch.dict(
|
||||
os.environ, {"WEBUI_PROJECT_REGISTRY": str(self.path)}, clear=False
|
||||
):
|
||||
return self.client.get(url)
|
||||
|
||||
def test_api_v1_reports_actionable_error(self):
|
||||
response = self._with_bad_registry("/api/v1/projects")
|
||||
self.assertEqual(response.status_code, 500)
|
||||
data = response.json()
|
||||
self.assertEqual(data["error"], "registry_invalid")
|
||||
self.assertIn("unsupported registry version", data["detail"])
|
||||
self.assertTrue(data["remediation"])
|
||||
self.assertEqual(data["field_path"], "version")
|
||||
|
||||
def test_unversioned_alias_reports_actionable_error(self):
|
||||
response = self._with_bad_registry("/api/projects")
|
||||
self.assertEqual(response.status_code, 500)
|
||||
self.assertEqual(response.json()["error"], "registry_invalid")
|
||||
|
||||
def test_html_page_reports_actionable_error(self):
|
||||
response = self._with_bad_registry("/projects")
|
||||
self.assertEqual(response.status_code, 500)
|
||||
self.assertIn("Project registry unavailable", response.text)
|
||||
self.assertIn("Remediation", response.text)
|
||||
|
||||
|
||||
class TestProjectRegistryApiDocs(unittest.TestCase):
|
||||
def test_api_contract_is_documented(self):
|
||||
self.assertTrue(_API_DOC.is_file(), f"missing {_API_DOC}")
|
||||
text = _API_DOC.read_text(encoding="utf-8")
|
||||
for token in (
|
||||
"/api/v1/projects",
|
||||
"/api/v1/projects/{project_id}",
|
||||
"/api/projects",
|
||||
"onboarding_summary",
|
||||
"last_seen_health",
|
||||
"registry_invalid",
|
||||
"#635",
|
||||
):
|
||||
with self.subTest(token=token):
|
||||
self.assertIn(token, text)
|
||||
|
||||
def test_route_table_lists_versioned_routes(self):
|
||||
local_dev = (_REPO_ROOT / "docs" / "webui-local-dev.md").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
self.assertIn("/api/v1/projects", local_dev)
|
||||
self.assertIn("webui-project-registry-api.md", local_dev)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
unittest.main()
|
||||
@@ -0,0 +1,135 @@
|
||||
"""Tests for the Phase 1 operator console application shell (#638)."""
|
||||
import sys
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
||||
|
||||
from starlette.routing import Route
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
from webui import layout
|
||||
from webui.app import create_app
|
||||
from webui.nav import NAV_GROUPS, STUB_PAGES, nav_hrefs
|
||||
|
||||
|
||||
class TestShellNav(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.client = TestClient(create_app())
|
||||
|
||||
def test_nav_group_labels_present(self):
|
||||
text = self.client.get("/").text
|
||||
for group in NAV_GROUPS:
|
||||
with self.subTest(group=group.label):
|
||||
self.assertIn(f">{group.label}<", text)
|
||||
|
||||
def test_phase1_group_labels_cover_expected_ia(self):
|
||||
labels = {group.label for group in NAV_GROUPS}
|
||||
for expected in (
|
||||
"Health",
|
||||
"Traffic",
|
||||
"Runtime/Sessions",
|
||||
"Projects",
|
||||
"Inventory",
|
||||
"Timeline",
|
||||
"Policy",
|
||||
"Insights",
|
||||
):
|
||||
with self.subTest(label=expected):
|
||||
self.assertIn(expected, labels)
|
||||
|
||||
def test_every_nav_href_resolves_to_a_get_route(self):
|
||||
app = create_app()
|
||||
get_paths = {
|
||||
route.path
|
||||
for route in app.routes
|
||||
if isinstance(route, Route) and "GET" in route.methods
|
||||
}
|
||||
for href in nav_hrefs():
|
||||
with self.subTest(href=href):
|
||||
self.assertIn(href, get_paths, f"nav href {href} has no GET route")
|
||||
|
||||
def test_legacy_hrefs_still_navigable(self):
|
||||
text = self.client.get("/").text
|
||||
for href in ("/queue", "/projects", "/prompts", "/runtime",
|
||||
"/audit", "/worktrees", "/leases", "/actions"):
|
||||
with self.subTest(href=href):
|
||||
self.assertIn(f'href="{href}"', text)
|
||||
|
||||
|
||||
class TestShellBadges(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.client = TestClient(create_app())
|
||||
|
||||
def test_mode_badge_present(self):
|
||||
self.assertIn("mode: read-only", self.client.get("/").text)
|
||||
|
||||
def test_environment_badge_present(self):
|
||||
self.assertIn("env:", self.client.get("/").text)
|
||||
|
||||
def test_default_environment_is_local(self):
|
||||
self.assertEqual(layout.environment_label(), "local")
|
||||
|
||||
def test_remote_bind_reports_remote_environment(self):
|
||||
import os
|
||||
|
||||
prior = os.environ.get("WEBUI_HOST")
|
||||
os.environ["WEBUI_HOST"] = "10.0.0.5"
|
||||
try:
|
||||
self.assertEqual(layout.environment_label(), "remote")
|
||||
finally:
|
||||
if prior is None:
|
||||
os.environ.pop("WEBUI_HOST", None)
|
||||
else:
|
||||
os.environ["WEBUI_HOST"] = prior
|
||||
|
||||
def test_docs_link_present(self):
|
||||
text = self.client.get("/").text
|
||||
self.assertIn(layout.DOCS_URL, text)
|
||||
self.assertIn(">Docs<", text)
|
||||
|
||||
|
||||
class TestShellStubs(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.client = TestClient(create_app())
|
||||
|
||||
def test_stub_routes_render_200(self):
|
||||
for path, (title, _desc) in STUB_PAGES.items():
|
||||
with self.subTest(path=path):
|
||||
response = self.client.get(path)
|
||||
self.assertEqual(response.status_code, 200, path)
|
||||
self.assertIn(title, response.text)
|
||||
self.assertIn("placeholder", response.text)
|
||||
|
||||
def test_stub_routes_are_read_only(self):
|
||||
for path in STUB_PAGES:
|
||||
with self.subTest(path=path):
|
||||
response = self.client.post(path)
|
||||
self.assertEqual(response.status_code, 405)
|
||||
self.assertEqual(response.json()["error"], "read-only-mvp")
|
||||
|
||||
def test_stub_pages_carry_nav_and_badges(self):
|
||||
response = self.client.get("/inventory")
|
||||
self.assertIn("mode: read-only", response.text)
|
||||
self.assertIn('href="/queue"', response.text)
|
||||
|
||||
|
||||
class TestShellHome(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.client = TestClient(create_app())
|
||||
|
||||
def test_home_summarizes_console(self):
|
||||
text = self.client.get("/").text
|
||||
self.assertIn("Operator console", text)
|
||||
self.assertIn("Phase 1", text)
|
||||
|
||||
def test_home_links_legacy_pages(self):
|
||||
text = self.client.get("/").text
|
||||
self.assertIn("MVP legacy pages", text)
|
||||
for href in ("/queue", "/audit", "/leases"):
|
||||
with self.subTest(href=href):
|
||||
self.assertIn(f'href="{href}"', text)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
+59
-83
@@ -11,20 +11,9 @@ from starlette.routing import Route
|
||||
|
||||
from webui.deployment_boundary import deployment_snapshot
|
||||
from webui.layout import render_page
|
||||
from webui.project_registry import (
|
||||
ProjectRegistry,
|
||||
RegistryError,
|
||||
find_project,
|
||||
known_project_ids,
|
||||
load_registry,
|
||||
project_detail_to_dict,
|
||||
registry_to_dict,
|
||||
)
|
||||
from webui.project_views import (
|
||||
render_project_detail,
|
||||
render_projects_list,
|
||||
render_registry_error,
|
||||
)
|
||||
from webui.nav import NAV_GROUPS, STUB_PAGES
|
||||
from webui.project_registry import find_project, load_registry, registry_to_dict
|
||||
from webui.project_views import render_project_detail, render_projects_list
|
||||
from webui.prompt_library import find_prompt, library_to_dict
|
||||
from webui.prompt_views import render_prompt_detail, render_prompts_page
|
||||
from final_report_validator import FINAL_REPORT_TASK_KINDS
|
||||
@@ -55,24 +44,62 @@ def _stub_page(title: str, description: str) -> HTMLResponse:
|
||||
return HTMLResponse(render_page(title=title, body_html=body))
|
||||
|
||||
|
||||
_LEGACY_PAGES = (
|
||||
("/queue", "Queue", "live PR and issue dashboard (#429)"),
|
||||
("/projects", "Projects", "registry and onboarding (#427)"),
|
||||
("/prompts", "Prompts", "canonical workflow prompt library (#428)"),
|
||||
("/runtime", "Runtime", "MCP health and stale-runtime detection (#430)"),
|
||||
("/audit", "Audit", "final-report paste and validator preview (#431)"),
|
||||
("/worktrees", "Worktrees", "branch hygiene dashboard (#432)"),
|
||||
("/leases", "Leases", "collision and lease visibility (#433)"),
|
||||
("/actions", "Actions", "gated write-action framework (#434)"),
|
||||
)
|
||||
|
||||
|
||||
def _render_home_nav_groups() -> str:
|
||||
groups = []
|
||||
for group in NAV_GROUPS:
|
||||
items = "".join(
|
||||
f'<li><a href="{item.href}">{item.label}</a>'
|
||||
+ ("" if item.status == "live" else " <span class=\"muted\">(stub)</span>")
|
||||
+ "</li>"
|
||||
for item in group.items
|
||||
)
|
||||
groups.append(f"<h3>{group.label}</h3><ul>{items}</ul>")
|
||||
return "".join(groups)
|
||||
|
||||
|
||||
async def home(_request: Request) -> HTMLResponse:
|
||||
legacy = "".join(
|
||||
f"<li><strong>{label}</strong> — {desc} "
|
||||
f'(<a href="{href}">{href}</a>)</li>'
|
||||
for href, label, desc in _LEGACY_PAGES
|
||||
)
|
||||
body = (
|
||||
"<h2>Operator console</h2>"
|
||||
"<p>Local entry point for MCP Control Plane operational views.</p>"
|
||||
"<ul>"
|
||||
"<li><strong>Queue</strong> — live PR and issue dashboard (#429)</li>"
|
||||
"<li><strong>Projects</strong> — registry and onboarding (#427)</li>"
|
||||
"<li><strong>Prompts</strong> — canonical workflow prompt library (#428)</li>"
|
||||
"<li><strong>Runtime</strong> — MCP health and stale-runtime detection (#430)</li>"
|
||||
"<li><strong>Audit</strong> — final-report paste and validator preview (#431)</li>"
|
||||
"<li><strong>Worktrees</strong> — branch hygiene dashboard (#432)</li>"
|
||||
"<li><strong>Leases</strong> — collision and lease visibility (#433)</li>"
|
||||
"<li><strong>Actions</strong> — gated write-action framework (#434)</li>"
|
||||
"</ul>"
|
||||
"<p>Read-only home for the MCP Control Plane Phase 1 operator console. "
|
||||
"Gitea, MCP capability gates, and canonical workflows remain the source "
|
||||
"of truth; this console never mutates them.</p>"
|
||||
"<h2>Phase 1 surfaces</h2>"
|
||||
+ _render_home_nav_groups()
|
||||
+ "<h2>MVP legacy pages</h2>"
|
||||
"<ul>" + legacy + "</ul>"
|
||||
)
|
||||
return HTMLResponse(render_page(title="Home", body_html=body))
|
||||
|
||||
|
||||
async def phase_stub(request: Request) -> HTMLResponse:
|
||||
"""Graceful read-only placeholder for a not-yet-implemented Phase 1 surface."""
|
||||
title, description = STUB_PAGES[request.url.path]
|
||||
body = (
|
||||
f"<h2>{title}</h2>"
|
||||
f'<div class="stub"><p>{description}</p>'
|
||||
"<p>Phase 1 shell placeholder — no write actions. Tracked under "
|
||||
"epic #631.</p></div>"
|
||||
)
|
||||
return HTMLResponse(render_page(title=title, body_html=body))
|
||||
|
||||
|
||||
async def health(_request: Request) -> JSONResponse:
|
||||
bind_host = _request.app.state.webui_bind_host
|
||||
return JSONResponse({
|
||||
@@ -93,26 +120,14 @@ async def api_queue(_request: Request) -> JSONResponse:
|
||||
return JSONResponse(queue_snapshot_to_dict(load_queue_snapshot()))
|
||||
|
||||
|
||||
def _load_project_registry() -> tuple[ProjectRegistry | None, RegistryError | None]:
|
||||
"""Load the registry, converting validation failure into a fail-closed pair."""
|
||||
try:
|
||||
return load_registry(), None
|
||||
except RegistryError as exc:
|
||||
return None, exc
|
||||
|
||||
|
||||
async def projects(_request: Request) -> HTMLResponse:
|
||||
registry, error = _load_project_registry()
|
||||
if error is not None:
|
||||
return HTMLResponse(render_registry_error(error), status_code=500)
|
||||
registry = load_registry()
|
||||
return HTMLResponse(render_projects_list(registry))
|
||||
|
||||
|
||||
async def project_detail(request: Request) -> HTMLResponse:
|
||||
project_id = request.path_params["project_id"]
|
||||
registry, error = _load_project_registry()
|
||||
if error is not None:
|
||||
return HTMLResponse(render_registry_error(error), status_code=500)
|
||||
registry = load_registry()
|
||||
project = find_project(registry, project_id)
|
||||
if project is None:
|
||||
return HTMLResponse(
|
||||
@@ -130,47 +145,10 @@ async def project_detail(request: Request) -> HTMLResponse:
|
||||
|
||||
|
||||
async def api_projects(_request: Request) -> JSONResponse:
|
||||
"""Unversioned MVP alias, retained through Phase 1 (#632 section 6)."""
|
||||
registry, error = _load_project_registry()
|
||||
if error is not None:
|
||||
return JSONResponse(error.to_dict(), status_code=500)
|
||||
registry = load_registry()
|
||||
return JSONResponse(registry_to_dict(registry))
|
||||
|
||||
|
||||
async def api_v1_projects(_request: Request) -> JSONResponse:
|
||||
registry, error = _load_project_registry()
|
||||
if error is not None:
|
||||
return JSONResponse(error.to_dict(), status_code=500)
|
||||
return JSONResponse(registry_to_dict(registry))
|
||||
|
||||
|
||||
async def api_v1_project_detail(request: Request) -> JSONResponse:
|
||||
project_id = request.path_params["project_id"]
|
||||
registry, error = _load_project_registry()
|
||||
if error is not None:
|
||||
return JSONResponse(error.to_dict(), status_code=500)
|
||||
project = find_project(registry, project_id)
|
||||
if project is None:
|
||||
return JSONResponse(
|
||||
{
|
||||
"error": "project_not_found",
|
||||
"project_id": project_id,
|
||||
"known_project_ids": known_project_ids(registry),
|
||||
"remediation": (
|
||||
"Request one of the known project ids, or add the project to the "
|
||||
"registry file named in 'source'."
|
||||
),
|
||||
"source": {
|
||||
"kind": "file",
|
||||
"path": str(registry.source_path),
|
||||
"inventory_complete": True,
|
||||
},
|
||||
},
|
||||
status_code=404,
|
||||
)
|
||||
return JSONResponse(project_detail_to_dict(registry, project))
|
||||
|
||||
|
||||
async def prompts(_request: Request) -> HTMLResponse:
|
||||
return HTMLResponse(render_prompts_page())
|
||||
|
||||
@@ -329,12 +307,6 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
|
||||
Route("/projects", projects, methods=["GET"]),
|
||||
Route("/projects/{project_id}", project_detail, methods=["GET"]),
|
||||
Route("/api/projects", api_projects, methods=["GET"]),
|
||||
Route("/api/v1/projects", api_v1_projects, methods=["GET"]),
|
||||
Route(
|
||||
"/api/v1/projects/{project_id}",
|
||||
api_v1_project_detail,
|
||||
methods=["GET"],
|
||||
),
|
||||
Route("/prompts", prompts, methods=["GET"]),
|
||||
Route("/prompts/{prompt_id}", prompt_detail, methods=["GET"]),
|
||||
Route("/api/prompts", api_prompts, methods=["GET"]),
|
||||
@@ -358,6 +330,10 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
|
||||
methods=["POST"],
|
||||
),
|
||||
Route("/api/leases", api_leases, methods=["GET"]),
|
||||
*[
|
||||
Route(path, phase_stub, methods=["GET"])
|
||||
for path in STUB_PAGES
|
||||
],
|
||||
],
|
||||
exception_handlers={405: method_not_allowed},
|
||||
)
|
||||
|
||||
@@ -1,15 +1,13 @@
|
||||
{
|
||||
"version": 2,
|
||||
"version": 1,
|
||||
"projects": [
|
||||
{
|
||||
"id": "gitea-tools",
|
||||
"repo_name": "Gitea-Tools",
|
||||
"gitea_owner": "Scaled-Tech-Consulting",
|
||||
"remote_name": "prgs",
|
||||
"remote_host": "https://gitea.prgs.cc",
|
||||
"default_branch": "master",
|
||||
"local_checkout_path": ".",
|
||||
"status": "active",
|
||||
"profiles": {
|
||||
"author": "prgs-author",
|
||||
"reviewer": "prgs-reviewer",
|
||||
@@ -28,32 +26,24 @@
|
||||
{
|
||||
"id": "profiles",
|
||||
"title": "Configure execution profiles",
|
||||
"description": "Install author, reviewer, and reconciler MCP profiles (prgs-author, prgs-reviewer, prgs-reconciler) in separate namespaces. Tokens stay in keychain — never in this registry.",
|
||||
"state": "complete",
|
||||
"required": true
|
||||
"description": "Install author, reviewer, and reconciler MCP profiles (prgs-author, prgs-reviewer, prgs-reconciler) in separate namespaces. Tokens stay in keychain — never in this registry."
|
||||
},
|
||||
{
|
||||
"id": "mcp_config",
|
||||
"title": "Wire MCP v2 contexts",
|
||||
"description": "Copy and customize gitea-mcp.v2-contexts.example.json for your machine. Map this repo path under projects with default_owner Scaled-Tech-Consulting and default_repo Gitea-Tools.",
|
||||
"state": "complete",
|
||||
"required": true
|
||||
"description": "Copy and customize gitea-mcp.v2-contexts.example.json for your machine. Map this repo path under projects with default_owner Scaled-Tech-Consulting and default_repo Gitea-Tools."
|
||||
},
|
||||
{
|
||||
"id": "wiki_gate",
|
||||
"title": "Wiki publication readiness",
|
||||
"description": "For wiki-tracked work, satisfy the live Gitea Wiki proof gate (#224) before closing issues. See docs/wiki/Safety-and-Gates.md.",
|
||||
"state": "complete",
|
||||
"required": true
|
||||
"description": "For wiki-tracked work, satisfy the live Gitea Wiki proof gate (#224) before closing issues. See docs/wiki/Safety-and-Gates.md."
|
||||
},
|
||||
{
|
||||
"id": "branches_layout",
|
||||
"title": "Isolate work under branches/",
|
||||
"description": "All LLM task edits happen in worktrees under branches/. Main checkout stays clean; use skills/llm-project-workflow templates for start-issue and review flows.",
|
||||
"state": "complete",
|
||||
"required": true
|
||||
"description": "All LLM task edits happen in worktrees under branches/. Main checkout stays clean; use skills/llm-project-workflow templates for start-issue and review flows."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
+95
-17
@@ -2,28 +2,66 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
NAV_ITEMS = (
|
||||
("/", "Home"),
|
||||
("/queue", "Queue"),
|
||||
("/projects", "Projects"),
|
||||
("/prompts", "Prompts"),
|
||||
("/runtime", "Runtime"),
|
||||
("/audit", "Audit"),
|
||||
("/worktrees", "Worktrees"),
|
||||
("/leases", "Leases"),
|
||||
("/actions", "Actions"),
|
||||
)
|
||||
import os
|
||||
|
||||
from webui.nav import NAV_GROUPS
|
||||
|
||||
MVP_NOTICE = (
|
||||
"Read-only MVP — Gitea, MCP tools, and canonical workflows remain the "
|
||||
"source of truth. No mutation endpoints."
|
||||
)
|
||||
|
||||
# Canonical docs entry point surfaced from the shell header (#638).
|
||||
DOCS_URL = (
|
||||
"https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/src/branch/"
|
||||
"master/docs/webui-local-dev.md"
|
||||
)
|
||||
|
||||
_LOCAL_HOSTS = frozenset({"", "127.0.0.1", "localhost", "::1"})
|
||||
|
||||
|
||||
def environment_label() -> str:
|
||||
"""Classify the serving environment as ``local`` or ``remote`` (#638).
|
||||
|
||||
Derived from the same ``WEBUI_HOST`` default the app binds to; loopback
|
||||
hosts are ``local``, anything else is ``remote``. Read-only signal only.
|
||||
"""
|
||||
host = (os.environ.get("WEBUI_HOST", "127.0.0.1") or "").strip().lower()
|
||||
return "local" if host in _LOCAL_HOSTS else "remote"
|
||||
|
||||
|
||||
def _render_nav() -> str:
|
||||
groups_html = []
|
||||
for group in NAV_GROUPS:
|
||||
links = "".join(
|
||||
f'<a href="{item.href}"'
|
||||
+ (' class="nav-stub"' if item.status == "stub" else "")
|
||||
+ f'>{item.label}</a>'
|
||||
for item in group.items
|
||||
)
|
||||
groups_html.append(
|
||||
'<div class="nav-group">'
|
||||
f'<span class="nav-group-label">{group.label}</span>'
|
||||
f'<span class="nav-group-links">{links}</span>'
|
||||
"</div>"
|
||||
)
|
||||
return "".join(groups_html)
|
||||
|
||||
|
||||
def _render_badges() -> str:
|
||||
env = environment_label()
|
||||
return (
|
||||
'<div class="header-badges">'
|
||||
f'<span class="badge env-badge env-{env}">env: {env}</span>'
|
||||
'<span class="badge mode-badge">mode: read-only</span>'
|
||||
f'<a class="badge docs-link" href="{DOCS_URL}">Docs</a>'
|
||||
"</div>"
|
||||
)
|
||||
|
||||
|
||||
def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
|
||||
nav_links = "".join(
|
||||
f'<a href="{href}">{label}</a>' for href, label in NAV_ITEMS
|
||||
)
|
||||
nav_links = _render_nav()
|
||||
header_badges = _render_badges()
|
||||
return f"""<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
@@ -53,21 +91,58 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
|
||||
padding: 0.75rem 1.25rem;
|
||||
}}
|
||||
header h1 {{
|
||||
margin: 0 0 0.5rem;
|
||||
margin: 0;
|
||||
font-size: 1.1rem;
|
||||
font-weight: 600;
|
||||
}}
|
||||
.header-top {{
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
gap: 0.5rem 1rem;
|
||||
margin-bottom: 0.6rem;
|
||||
}}
|
||||
.header-badges {{ display: inline-flex; flex-wrap: wrap; gap: 0.4rem; }}
|
||||
.env-badge.env-local {{ color: #8fd19e; border-color: #3d6b4a; }}
|
||||
.env-badge.env-remote {{ color: #e0c27a; border-color: #6b5730; }}
|
||||
.mode-badge {{ color: #9ec8f0; border-color: #3d5f7a; }}
|
||||
a.docs-link {{
|
||||
color: var(--accent);
|
||||
border-color: var(--accent);
|
||||
text-decoration: none;
|
||||
text-transform: none;
|
||||
}}
|
||||
a.docs-link:hover {{ filter: brightness(1.12); }}
|
||||
nav {{
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.75rem 1rem;
|
||||
gap: 0.5rem 1.25rem;
|
||||
}}
|
||||
.nav-group {{
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.15rem;
|
||||
}}
|
||||
.nav-group-label {{
|
||||
font-size: 0.68rem;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.04em;
|
||||
color: var(--muted);
|
||||
}}
|
||||
.nav-group-links {{ display: inline-flex; flex-wrap: wrap; gap: 0.6rem; }}
|
||||
nav a {{
|
||||
color: var(--accent);
|
||||
text-decoration: none;
|
||||
font-size: 0.9rem;
|
||||
}}
|
||||
nav a:hover {{ text-decoration: underline; }}
|
||||
nav a.nav-stub {{ color: var(--muted); }}
|
||||
nav a.nav-stub::after {{
|
||||
content: " ·stub";
|
||||
font-size: 0.7rem;
|
||||
color: var(--muted);
|
||||
}}
|
||||
main {{
|
||||
max-width: 52rem;
|
||||
margin: 0 auto;
|
||||
@@ -166,7 +241,10 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<h1>MCP Control Plane</h1>
|
||||
<div class="header-top">
|
||||
<h1>MCP Control Plane</h1>
|
||||
{header_badges}
|
||||
</div>
|
||||
<nav>{nav_links}</nav>
|
||||
</header>
|
||||
<main>
|
||||
|
||||
+111
@@ -0,0 +1,111 @@
|
||||
"""Navigation IA for the Phase 1 operator console shell (#638).
|
||||
|
||||
Single source of truth for the console navigation so ``webui/layout.py`` and
|
||||
the ``webui/app.py`` route table stay aligned with epic #631. Read-only: every
|
||||
destination is a GET view or a Phase 1 placeholder. No mutation links.
|
||||
|
||||
Nav groups follow the #631 Phase 1 information architecture: Health, Traffic,
|
||||
Runtime/Sessions, Projects, Inventory, Timeline, Policy (placeholder), and
|
||||
Insights (placeholder). Later-phase surfaces are declared as ``stub`` items and
|
||||
backed by ``STUB_PAGES`` so their nav links resolve to a graceful placeholder
|
||||
instead of a 404.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class NavItem:
|
||||
"""A single navigation destination.
|
||||
|
||||
``status`` is ``"live"`` for implemented views and ``"stub"`` for Phase 1
|
||||
placeholders whose backing view lands in a later child issue.
|
||||
"""
|
||||
|
||||
href: str
|
||||
label: str
|
||||
status: str = "live"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class NavGroup:
|
||||
label: str
|
||||
items: tuple[NavItem, ...]
|
||||
|
||||
|
||||
NAV_GROUPS: tuple[NavGroup, ...] = (
|
||||
NavGroup("Health", (
|
||||
NavItem("/health", "Liveness"),
|
||||
)),
|
||||
NavGroup("Traffic", (
|
||||
NavItem("/queue", "Queue"),
|
||||
NavItem("/leases", "Leases"),
|
||||
NavItem("/actions", "Actions"),
|
||||
)),
|
||||
NavGroup("Runtime/Sessions", (
|
||||
NavItem("/runtime", "Runtime health"),
|
||||
NavItem("/sessions", "Sessions", "stub"),
|
||||
)),
|
||||
NavGroup("Projects", (
|
||||
NavItem("/projects", "Projects"),
|
||||
)),
|
||||
NavGroup("Inventory", (
|
||||
NavItem("/inventory", "Inventory", "stub"),
|
||||
NavItem("/worktrees", "Worktrees"),
|
||||
)),
|
||||
NavGroup("Timeline", (
|
||||
NavItem("/timeline", "Timeline", "stub"),
|
||||
)),
|
||||
NavGroup("Policy", (
|
||||
NavItem("/policy", "Policy", "stub"),
|
||||
NavItem("/prompts", "Prompts"),
|
||||
)),
|
||||
NavGroup("Insights", (
|
||||
NavItem("/insights", "Insights", "stub"),
|
||||
NavItem("/audit", "Audit"),
|
||||
)),
|
||||
)
|
||||
|
||||
|
||||
# Phase 1 placeholder destinations whose backing views land in later child
|
||||
# issues of epic #631. Each maps a path to (title, description). Routes are
|
||||
# registered so nav links resolve to a graceful, read-only stub page.
|
||||
STUB_PAGES: dict[str, tuple[str, str]] = {
|
||||
"/sessions": (
|
||||
"Sessions",
|
||||
"Active session, capability, and role inventory. Backed by the unified "
|
||||
"inventory API (#636) once it lands.",
|
||||
),
|
||||
"/inventory": (
|
||||
"Inventory",
|
||||
"Unified sessions, leases, locks, namespaces, and worktree inventory. "
|
||||
"Backed by the Phase 1 inventory API (#636).",
|
||||
),
|
||||
"/timeline": (
|
||||
"Timeline",
|
||||
"Workflow event timeline across issues and PRs. A later Phase 1 surface.",
|
||||
),
|
||||
"/policy": (
|
||||
"Policy",
|
||||
"Capability and role policy surface. Placeholder until a later phase.",
|
||||
),
|
||||
"/insights": (
|
||||
"Insights",
|
||||
"Aggregate operational insights and trends. Placeholder until a later "
|
||||
"phase.",
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def iter_nav_items():
|
||||
"""Yield every ``NavItem`` across all groups in declared order."""
|
||||
for group in NAV_GROUPS:
|
||||
for item in group.items:
|
||||
yield item
|
||||
|
||||
|
||||
def nav_hrefs() -> tuple[str, ...]:
|
||||
"""Return every navigation href in declared order."""
|
||||
return tuple(item.href for item in iter_nav_items())
|
||||
+25
-460
@@ -1,16 +1,4 @@
|
||||
"""Load and validate the web UI project registry (#427, evolved for #635).
|
||||
|
||||
Phase 1 of the console architecture ADR keeps this loader read-only. It owns
|
||||
the versioned project registry contract served at ``/api/v1/projects``:
|
||||
|
||||
* the on-disk file carries a ``version`` (schema version 1 or 2);
|
||||
* version 1 files stay loadable and are normalized with explicit defaults, so
|
||||
an operator registry written for #427 keeps working;
|
||||
* every validation failure raises :class:`RegistryError`, which carries an
|
||||
actionable ``remediation`` string instead of leaking a traceback;
|
||||
* serialization never emits credentials — credential-shaped keys are rejected
|
||||
at load time, before any DTO is built.
|
||||
"""
|
||||
"""Load and validate the web UI project registry (#427)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -20,59 +8,7 @@ from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from webui.registry_safety import is_forbidden_key
|
||||
|
||||
#: Version of the JSON contract served under ``/api/v1/...``.
|
||||
REGISTRY_API_VERSION = "v1"
|
||||
|
||||
#: Schema version written by this repository's packaged registry.
|
||||
CURRENT_SCHEMA_VERSION = 2
|
||||
|
||||
#: Schema versions this loader accepts. Version 1 is normalized on load.
|
||||
SUPPORTED_SCHEMA_VERSIONS = (1, 2)
|
||||
|
||||
#: Lifecycle state of a registered project.
|
||||
PROJECT_STATUSES = ("active", "onboarding", "paused", "archived")
|
||||
_DEFAULT_PROJECT_STATUS = "active"
|
||||
|
||||
#: Completion state of a single onboarding step.
|
||||
ONBOARDING_STATES = ("complete", "pending", "blocked", "not_applicable")
|
||||
_DEFAULT_ONBOARDING_STATE = "pending"
|
||||
|
||||
#: Redacted, last-seen health of a project's control plane.
|
||||
HEALTH_STATUSES = ("healthy", "degraded", "unreachable", "unknown")
|
||||
|
||||
class RegistryError(ValueError):
|
||||
"""A registry file could not be loaded or failed validation.
|
||||
|
||||
Carries an operator-facing ``remediation`` so routes can fail closed with
|
||||
an actionable message rather than a stack trace.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
message: str,
|
||||
*,
|
||||
remediation: str,
|
||||
source_path: Path | None = None,
|
||||
field_path: str | None = None,
|
||||
) -> None:
|
||||
super().__init__(message)
|
||||
self.message = message
|
||||
self.remediation = remediation
|
||||
self.source_path = source_path
|
||||
self.field_path = field_path
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
"""Serialize for a fail-closed JSON error response."""
|
||||
return {
|
||||
"error": "registry_invalid",
|
||||
"detail": self.message,
|
||||
"remediation": self.remediation,
|
||||
"field_path": self.field_path,
|
||||
"source_path": str(self.source_path) if self.source_path else None,
|
||||
}
|
||||
|
||||
from webui.registry_safety import reject_credential_keys as _reject_credential_keys
|
||||
|
||||
_REQUIRED_PROJECT_FIELDS = (
|
||||
"id",
|
||||
@@ -93,30 +29,6 @@ class OnboardingStep:
|
||||
id: str
|
||||
title: str
|
||||
description: str
|
||||
state: str = _DEFAULT_ONBOARDING_STATE
|
||||
required: bool = True
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OnboardingSummary:
|
||||
"""Aggregate onboarding progress for a single project."""
|
||||
|
||||
total: int
|
||||
complete: int
|
||||
pending: int
|
||||
blocked: int
|
||||
not_applicable: int
|
||||
required_outstanding: int
|
||||
onboarding_complete: bool
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ProjectHealth:
|
||||
"""Redacted last-seen health. Never carries endpoints or credentials."""
|
||||
|
||||
status: str
|
||||
checked_at: str | None
|
||||
detail: str | None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -131,13 +43,6 @@ class ProjectRecord:
|
||||
workflow_paths: dict[str, str]
|
||||
schema_paths: dict[str, str]
|
||||
onboarding_checklist: tuple[OnboardingStep, ...]
|
||||
status: str = _DEFAULT_PROJECT_STATUS
|
||||
remote_name: str | None = None
|
||||
last_seen_health: ProjectHealth | None = None
|
||||
|
||||
@property
|
||||
def repo_full_name(self) -> str:
|
||||
return f"{self.gitea_owner}/{self.repo_name}"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -146,15 +51,6 @@ class ProjectRegistry:
|
||||
projects: tuple[ProjectRecord, ...]
|
||||
source_path: Path
|
||||
|
||||
@property
|
||||
def schema_version(self) -> int:
|
||||
"""Alias of :attr:`version` — the schema version read from disk."""
|
||||
return self.version
|
||||
|
||||
@property
|
||||
def api_version(self) -> str:
|
||||
return REGISTRY_API_VERSION
|
||||
|
||||
|
||||
def default_registry_path() -> Path:
|
||||
override = os.environ.get("WEBUI_PROJECT_REGISTRY", "").strip()
|
||||
@@ -163,221 +59,40 @@ def default_registry_path() -> Path:
|
||||
return (Path(__file__).resolve().parent / "data" / "projects.registry.json").resolve()
|
||||
|
||||
|
||||
def _reject_credential_keys(obj: Any, *, path: str = "", source: Path | None = None) -> None:
|
||||
"""Recursive credential-key guard that reports an actionable ``field_path``.
|
||||
|
||||
Key *shape* is decided by :func:`webui.registry_safety.is_forbidden_key`, the
|
||||
single source of truth shared with the worker registry (#798).
|
||||
"""
|
||||
if isinstance(obj, dict):
|
||||
for key, value in obj.items():
|
||||
key_path = f"{path}.{key}" if path else key
|
||||
if is_forbidden_key(key):
|
||||
raise RegistryError(
|
||||
f"registry must not store credentials ({key_path})",
|
||||
remediation=(
|
||||
f"Remove the credential-shaped key '{key_path}' from the registry. "
|
||||
"Tokens live in the keychain and are resolved server-side by "
|
||||
"gitea_auth; the registry is redacted metadata only."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=key_path,
|
||||
)
|
||||
_reject_credential_keys(value, path=key_path, source=source)
|
||||
elif isinstance(obj, list):
|
||||
for index, item in enumerate(obj):
|
||||
_reject_credential_keys(item, path=f"{path}[{index}]", source=source)
|
||||
|
||||
|
||||
def _require_enum(
|
||||
value: Any,
|
||||
*,
|
||||
allowed: tuple[str, ...],
|
||||
field_path: str,
|
||||
source: Path | None,
|
||||
) -> str:
|
||||
text = str(value)
|
||||
if text not in allowed:
|
||||
raise RegistryError(
|
||||
f"{field_path} must be one of {', '.join(allowed)} (got {text!r})",
|
||||
remediation=(
|
||||
f"Set {field_path} to one of: {', '.join(allowed)}. "
|
||||
"Unknown values fail closed so the console never renders an "
|
||||
"unverified state."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=field_path,
|
||||
)
|
||||
return text
|
||||
|
||||
|
||||
def _parse_onboarding(
|
||||
raw: Any,
|
||||
*,
|
||||
project_path: str,
|
||||
source: Path | None,
|
||||
) -> tuple[OnboardingStep, ...]:
|
||||
if raw is None:
|
||||
def _parse_onboarding(raw: list[dict[str, Any]] | None) -> tuple[OnboardingStep, ...]:
|
||||
if not raw:
|
||||
return ()
|
||||
if not isinstance(raw, list):
|
||||
raise RegistryError(
|
||||
f"{project_path}.onboarding_checklist must be an array",
|
||||
remediation=(
|
||||
f"Rewrite {project_path}.onboarding_checklist as a JSON array of "
|
||||
"steps with id, title, description, and optional state."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=f"{project_path}.onboarding_checklist",
|
||||
)
|
||||
steps: list[OnboardingStep] = []
|
||||
for index, item in enumerate(raw):
|
||||
step_path = f"{project_path}.onboarding_checklist[{index}]"
|
||||
if not isinstance(item, dict):
|
||||
raise RegistryError(
|
||||
f"{step_path} must be an object",
|
||||
remediation=f"Rewrite {step_path} as an object with id, title, description.",
|
||||
source_path=source,
|
||||
field_path=step_path,
|
||||
)
|
||||
missing = [field for field in ("id", "title", "description") if field not in item]
|
||||
if missing:
|
||||
raise RegistryError(
|
||||
f"{step_path} missing required fields: {', '.join(missing)}",
|
||||
remediation=(
|
||||
f"Add {', '.join(missing)} to {step_path}. Every onboarding step "
|
||||
"must be self-describing for an operator who has no chat history."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=step_path,
|
||||
)
|
||||
state = _require_enum(
|
||||
item.get("state", _DEFAULT_ONBOARDING_STATE),
|
||||
allowed=ONBOARDING_STATES,
|
||||
field_path=f"{step_path}.state",
|
||||
source=source,
|
||||
)
|
||||
for item in raw:
|
||||
steps.append(
|
||||
OnboardingStep(
|
||||
id=str(item["id"]),
|
||||
title=str(item["title"]),
|
||||
description=str(item["description"]),
|
||||
state=state,
|
||||
required=bool(item.get("required", True)),
|
||||
)
|
||||
)
|
||||
return tuple(steps)
|
||||
|
||||
|
||||
def _parse_health(
|
||||
raw: Any,
|
||||
*,
|
||||
project_path: str,
|
||||
source: Path | None,
|
||||
) -> ProjectHealth | None:
|
||||
if raw is None:
|
||||
return None
|
||||
if not isinstance(raw, dict):
|
||||
raise RegistryError(
|
||||
f"{project_path}.last_seen_health must be an object when present",
|
||||
remediation=(
|
||||
f"Rewrite {project_path}.last_seen_health as an object with status "
|
||||
f"(one of {', '.join(HEALTH_STATUSES)}), optional checked_at and detail, "
|
||||
"or remove it. Never store endpoints or credentials here."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=f"{project_path}.last_seen_health",
|
||||
)
|
||||
status = _require_enum(
|
||||
raw.get("status", "unknown"),
|
||||
allowed=HEALTH_STATUSES,
|
||||
field_path=f"{project_path}.last_seen_health.status",
|
||||
source=source,
|
||||
)
|
||||
checked_at = raw.get("checked_at")
|
||||
detail = raw.get("detail")
|
||||
return ProjectHealth(
|
||||
status=status,
|
||||
checked_at=str(checked_at) if checked_at is not None else None,
|
||||
detail=str(detail) if detail is not None else None,
|
||||
)
|
||||
|
||||
|
||||
def _parse_project(raw: Any, *, index: int, source: Path | None) -> ProjectRecord:
|
||||
project_path = f"projects[{index}]"
|
||||
if not isinstance(raw, dict):
|
||||
raise RegistryError(
|
||||
f"{project_path} must be an object",
|
||||
remediation=f"Rewrite {project_path} as a JSON object describing one project.",
|
||||
source_path=source,
|
||||
field_path=project_path,
|
||||
)
|
||||
|
||||
def _parse_project(raw: dict[str, Any]) -> ProjectRecord:
|
||||
missing = [field for field in _REQUIRED_PROJECT_FIELDS if field not in raw]
|
||||
if missing:
|
||||
raise RegistryError(
|
||||
f"{project_path} missing required fields: {', '.join(missing)}",
|
||||
remediation=(
|
||||
f"Add {', '.join(missing)} to {project_path}. See "
|
||||
"docs/webui-project-registry-api.md for the field-by-field contract."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=project_path,
|
||||
)
|
||||
raise ValueError(f"project missing required fields: {', '.join(missing)}")
|
||||
|
||||
profiles = raw["profiles"]
|
||||
if not isinstance(profiles, dict):
|
||||
raise RegistryError(
|
||||
f"{project_path}.profiles must be an object",
|
||||
remediation=(
|
||||
f"Rewrite {project_path}.profiles as an object mapping "
|
||||
f"{', '.join(_REQUIRED_PROFILE_ROLES)} to MCP profile names."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=f"{project_path}.profiles",
|
||||
)
|
||||
raise ValueError("profiles must be an object")
|
||||
for role in _REQUIRED_PROFILE_ROLES:
|
||||
if role not in profiles or not profiles[role]:
|
||||
raise RegistryError(
|
||||
f"{project_path}.profiles.{role} is required",
|
||||
remediation=(
|
||||
f"Set {project_path}.profiles.{role} to the configured MCP profile "
|
||||
"name for that role. Role separation is a workflow-safety invariant."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=f"{project_path}.profiles.{role}",
|
||||
)
|
||||
raise ValueError(f"profiles.{role} is required")
|
||||
|
||||
workflow_paths = raw["workflow_paths"]
|
||||
if not isinstance(workflow_paths, dict) or not workflow_paths:
|
||||
raise RegistryError(
|
||||
f"{project_path}.workflow_paths must be a non-empty object",
|
||||
remediation=(
|
||||
f"Add at least a 'skill' entry to {project_path}.workflow_paths pointing "
|
||||
"at the project's canonical workflow skill."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=f"{project_path}.workflow_paths",
|
||||
)
|
||||
raise ValueError("workflow_paths must be a non-empty object")
|
||||
|
||||
schema_paths = raw.get("schema_paths") or {}
|
||||
if not isinstance(schema_paths, dict):
|
||||
raise RegistryError(
|
||||
f"{project_path}.schema_paths must be an object when present",
|
||||
remediation=(
|
||||
f"Rewrite {project_path}.schema_paths as an object of label to repo path, "
|
||||
"or remove it."
|
||||
),
|
||||
source_path=source,
|
||||
field_path=f"{project_path}.schema_paths",
|
||||
)
|
||||
|
||||
status = _require_enum(
|
||||
raw.get("status", _DEFAULT_PROJECT_STATUS),
|
||||
allowed=PROJECT_STATUSES,
|
||||
field_path=f"{project_path}.status",
|
||||
source=source,
|
||||
)
|
||||
remote_name = raw.get("remote_name")
|
||||
raise ValueError("schema_paths must be an object when present")
|
||||
|
||||
return ProjectRecord(
|
||||
id=str(raw["id"]),
|
||||
@@ -389,211 +104,61 @@ def _parse_project(raw: Any, *, index: int, source: Path | None) -> ProjectRecor
|
||||
profiles={role: str(profiles[role]) for role in _REQUIRED_PROFILE_ROLES},
|
||||
workflow_paths={key: str(value) for key, value in workflow_paths.items()},
|
||||
schema_paths={key: str(value) for key, value in schema_paths.items()},
|
||||
onboarding_checklist=_parse_onboarding(
|
||||
raw.get("onboarding_checklist"),
|
||||
project_path=project_path,
|
||||
source=source,
|
||||
),
|
||||
status=status,
|
||||
remote_name=str(remote_name) if remote_name else None,
|
||||
last_seen_health=_parse_health(
|
||||
raw.get("last_seen_health"),
|
||||
project_path=project_path,
|
||||
source=source,
|
||||
),
|
||||
onboarding_checklist=_parse_onboarding(raw.get("onboarding_checklist")),
|
||||
)
|
||||
|
||||
|
||||
def load_registry(path: Path | None = None) -> ProjectRegistry:
|
||||
"""Load the versioned project registry from disk.
|
||||
|
||||
Raises:
|
||||
RegistryError: whenever the file is unreadable, is not valid JSON, or
|
||||
fails schema validation. The error carries an operator remediation.
|
||||
"""
|
||||
"""Load the versioned project registry from disk."""
|
||||
source = (path or default_registry_path()).resolve()
|
||||
try:
|
||||
raw_text = source.read_text(encoding="utf-8")
|
||||
except OSError as exc:
|
||||
raise RegistryError(
|
||||
f"registry file could not be read: {exc.strerror or exc}",
|
||||
remediation=(
|
||||
f"Create a readable registry at {source}, or point "
|
||||
"WEBUI_PROJECT_REGISTRY at an existing file."
|
||||
),
|
||||
source_path=source,
|
||||
) from exc
|
||||
|
||||
try:
|
||||
payload = json.loads(raw_text)
|
||||
except json.JSONDecodeError as exc:
|
||||
raise RegistryError(
|
||||
f"registry is not valid JSON: {exc.msg} (line {exc.lineno}, column {exc.colno})",
|
||||
remediation=(
|
||||
f"Fix the JSON syntax in {source} at line {exc.lineno}, column {exc.colno}."
|
||||
),
|
||||
source_path=source,
|
||||
) from exc
|
||||
|
||||
raw_text = source.read_text(encoding="utf-8")
|
||||
payload = json.loads(raw_text)
|
||||
if not isinstance(payload, dict):
|
||||
raise RegistryError(
|
||||
"registry root must be an object",
|
||||
remediation=(
|
||||
"Wrap the registry in a JSON object with 'version' and 'projects' keys."
|
||||
),
|
||||
source_path=source,
|
||||
)
|
||||
raise ValueError("registry root must be an object")
|
||||
|
||||
version = payload.get("version")
|
||||
if version not in SUPPORTED_SCHEMA_VERSIONS:
|
||||
supported = ", ".join(str(item) for item in SUPPORTED_SCHEMA_VERSIONS)
|
||||
raise RegistryError(
|
||||
f"unsupported registry version: {version!r}",
|
||||
remediation=(
|
||||
f"Set 'version' to one of {supported} (current schema is "
|
||||
f"{CURRENT_SCHEMA_VERSION}). Migration notes live in "
|
||||
"docs/webui-project-registry-api.md."
|
||||
),
|
||||
source_path=source,
|
||||
field_path="version",
|
||||
)
|
||||
if version != 1:
|
||||
raise ValueError(f"unsupported registry version: {version!r}")
|
||||
|
||||
_reject_credential_keys(payload, source=source)
|
||||
_reject_credential_keys(payload)
|
||||
|
||||
projects_raw = payload.get("projects")
|
||||
if not isinstance(projects_raw, list) or not projects_raw:
|
||||
raise RegistryError(
|
||||
"projects must be a non-empty array",
|
||||
remediation=(
|
||||
"Add at least one project object to 'projects'. An empty console "
|
||||
"registry fails closed rather than rendering a blank inventory."
|
||||
),
|
||||
source_path=source,
|
||||
field_path="projects",
|
||||
)
|
||||
raise ValueError("projects must be a non-empty array")
|
||||
|
||||
projects = tuple(
|
||||
_parse_project(item, index=index, source=source)
|
||||
for index, item in enumerate(projects_raw)
|
||||
)
|
||||
return ProjectRegistry(version=int(version), projects=projects, source_path=source)
|
||||
|
||||
|
||||
def onboarding_summary(project: ProjectRecord) -> OnboardingSummary:
|
||||
"""Aggregate a project's onboarding checklist state."""
|
||||
steps = project.onboarding_checklist
|
||||
counts = {state: 0 for state in ONBOARDING_STATES}
|
||||
for step in steps:
|
||||
counts[step.state] += 1
|
||||
required_outstanding = sum(
|
||||
1
|
||||
for step in steps
|
||||
if step.required and step.state in ("pending", "blocked")
|
||||
)
|
||||
return OnboardingSummary(
|
||||
total=len(steps),
|
||||
complete=counts["complete"],
|
||||
pending=counts["pending"],
|
||||
blocked=counts["blocked"],
|
||||
not_applicable=counts["not_applicable"],
|
||||
required_outstanding=required_outstanding,
|
||||
onboarding_complete=required_outstanding == 0,
|
||||
)
|
||||
projects = tuple(_parse_project(item) for item in projects_raw)
|
||||
return ProjectRegistry(version=version, projects=projects, source_path=source)
|
||||
|
||||
|
||||
def project_to_dict(project: ProjectRecord) -> dict[str, Any]:
|
||||
"""Serialize a project for JSON API responses and HTML views.
|
||||
|
||||
The HTML views render from this same DTO, so the console and the API can
|
||||
never disagree about a project's status or onboarding progress.
|
||||
"""
|
||||
summary = onboarding_summary(project)
|
||||
health = project.last_seen_health
|
||||
"""Serialize a project for JSON API responses."""
|
||||
return {
|
||||
"id": project.id,
|
||||
"repo_name": project.repo_name,
|
||||
"gitea_owner": project.gitea_owner,
|
||||
"repo_full_name": project.repo_full_name,
|
||||
"remote_host": project.remote_host,
|
||||
"remote_name": project.remote_name,
|
||||
"default_branch": project.default_branch,
|
||||
"local_checkout_path": project.local_checkout_path,
|
||||
"status": project.status,
|
||||
"profiles": dict(project.profiles),
|
||||
"workflow_paths": dict(project.workflow_paths),
|
||||
"schema_paths": dict(project.schema_paths),
|
||||
"onboarding_checklist": [
|
||||
{
|
||||
"id": step.id,
|
||||
"title": step.title,
|
||||
"description": step.description,
|
||||
"state": step.state,
|
||||
"required": step.required,
|
||||
}
|
||||
{"id": step.id, "title": step.title, "description": step.description}
|
||||
for step in project.onboarding_checklist
|
||||
],
|
||||
"onboarding_summary": {
|
||||
"total": summary.total,
|
||||
"complete": summary.complete,
|
||||
"pending": summary.pending,
|
||||
"blocked": summary.blocked,
|
||||
"not_applicable": summary.not_applicable,
|
||||
"required_outstanding": summary.required_outstanding,
|
||||
"onboarding_complete": summary.onboarding_complete,
|
||||
},
|
||||
"last_seen_health": (
|
||||
None
|
||||
if health is None
|
||||
else {
|
||||
"status": health.status,
|
||||
"checked_at": health.checked_at,
|
||||
"detail": health.detail,
|
||||
}
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def registry_to_dict(registry: ProjectRegistry) -> dict[str, Any]:
|
||||
"""Serialize the whole registry, including API provenance (#632 section 6)."""
|
||||
return {
|
||||
"api_version": registry.api_version,
|
||||
"schema_version": registry.schema_version,
|
||||
# Retained for the unversioned MVP alias consumers (#427).
|
||||
"version": registry.version,
|
||||
"source_path": str(registry.source_path),
|
||||
"source": {
|
||||
"kind": "file",
|
||||
"path": str(registry.source_path),
|
||||
"inventory_complete": True,
|
||||
},
|
||||
"project_count": len(registry.projects),
|
||||
"projects": [project_to_dict(project) for project in registry.projects],
|
||||
}
|
||||
|
||||
|
||||
def project_detail_to_dict(
|
||||
registry: ProjectRegistry,
|
||||
project: ProjectRecord,
|
||||
) -> dict[str, Any]:
|
||||
"""Serialize a single project for ``/api/v1/projects/{project_id}``."""
|
||||
return {
|
||||
"api_version": registry.api_version,
|
||||
"schema_version": registry.schema_version,
|
||||
"source": {
|
||||
"kind": "file",
|
||||
"path": str(registry.source_path),
|
||||
"inventory_complete": True,
|
||||
},
|
||||
"project": project_to_dict(project),
|
||||
}
|
||||
|
||||
|
||||
def find_project(registry: ProjectRegistry, project_id: str) -> ProjectRecord | None:
|
||||
for project in registry.projects:
|
||||
if project.id == project_id:
|
||||
return project
|
||||
return None
|
||||
|
||||
|
||||
def known_project_ids(registry: ProjectRegistry) -> list[str]:
|
||||
return [project.id for project in registry.projects]
|
||||
return None
|
||||
+25
-107
@@ -1,65 +1,34 @@
|
||||
"""HTML views for project registry pages (#427, evolved for #635).
|
||||
|
||||
Every view renders from :func:`webui.project_registry.project_to_dict`, the
|
||||
same DTO the ``/api/v1/projects`` JSON responses use, so the HTML console and
|
||||
the API can never disagree about status or onboarding progress.
|
||||
"""
|
||||
"""HTML views for project registry pages (#427)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import html
|
||||
from typing import Any
|
||||
|
||||
from webui.layout import render_page
|
||||
from webui.project_registry import (
|
||||
ProjectRecord,
|
||||
ProjectRegistry,
|
||||
RegistryError,
|
||||
project_to_dict,
|
||||
)
|
||||
|
||||
_STATE_LABELS = {
|
||||
"complete": "Complete",
|
||||
"pending": "Pending",
|
||||
"blocked": "Blocked",
|
||||
"not_applicable": "Not applicable",
|
||||
}
|
||||
from webui.project_registry import ProjectRecord, ProjectRegistry
|
||||
|
||||
|
||||
def _escape(text: str) -> str:
|
||||
return html.escape(text, quote=True)
|
||||
|
||||
|
||||
def _progress_label(summary: dict[str, Any]) -> str:
|
||||
total = summary["total"]
|
||||
if not total:
|
||||
return "no steps"
|
||||
label = f"{summary['complete']}/{total} complete"
|
||||
if summary["blocked"]:
|
||||
label += f", {summary['blocked']} blocked"
|
||||
return label
|
||||
|
||||
|
||||
def render_projects_list(registry: ProjectRegistry) -> str:
|
||||
rows = []
|
||||
for project in registry.projects:
|
||||
dto = project_to_dict(project)
|
||||
rows.append(
|
||||
"<tr>"
|
||||
f"<td><a href=\"/projects/{_escape(dto['id'])}\">{_escape(dto['repo_name'])}</a></td>"
|
||||
f"<td>{_escape(dto['gitea_owner'])}</td>"
|
||||
f"<td>{_escape(dto['remote_host'])}</td>"
|
||||
f"<td>{_escape(dto['default_branch'])}</td>"
|
||||
f"<td><code>{_escape(dto['status'])}</code></td>"
|
||||
f"<td>{_escape(_progress_label(dto['onboarding_summary']))}</td>"
|
||||
f"<td><code>{_escape(dto['profiles']['author'])}</code></td>"
|
||||
f"<td><a href=\"/projects/{_escape(project.id)}\">{_escape(project.repo_name)}</a></td>"
|
||||
f"<td>{_escape(project.gitea_owner)}</td>"
|
||||
f"<td>{_escape(project.remote_host)}</td>"
|
||||
f"<td>{_escape(project.default_branch)}</td>"
|
||||
f"<td><code>{_escape(project.profiles['author'])}</code></td>"
|
||||
"</tr>"
|
||||
)
|
||||
table = (
|
||||
"<table class=\"registry\">"
|
||||
"<thead><tr>"
|
||||
"<th>Repository</th><th>Owner</th><th>Remote</th>"
|
||||
"<th>Branch</th><th>Status</th><th>Onboarding</th><th>Author profile</th>"
|
||||
"<th>Branch</th><th>Author profile</th>"
|
||||
"</tr></thead>"
|
||||
f"<tbody>{''.join(rows)}</tbody></table>"
|
||||
)
|
||||
@@ -67,39 +36,32 @@ def render_projects_list(registry: ProjectRegistry) -> str:
|
||||
"<h2>Projects</h2>"
|
||||
"<p>Configured repositories managed by the MCP Control Plane.</p>"
|
||||
f"<p class=\"meta\">Registry: <code>{_escape(str(registry.source_path))}</code> "
|
||||
f"(schema version {registry.schema_version}, "
|
||||
f"API {_escape(registry.api_version)})</p>"
|
||||
f"(version {registry.version})</p>"
|
||||
f"{table}"
|
||||
"<p><a href=\"/api/v1/projects\">JSON API</a> "
|
||||
"(<a href=\"/api/projects\">unversioned alias</a>)</p>"
|
||||
"<p><a href=\"/api/projects\">JSON API</a></p>"
|
||||
)
|
||||
return render_page(title="Projects", body_html=body)
|
||||
|
||||
|
||||
def render_project_detail(project: ProjectRecord) -> str:
|
||||
dto = project_to_dict(project)
|
||||
profile_rows = "".join(
|
||||
f"<tr><th>{_escape(role)}</th><td><code>{_escape(name)}</code></td></tr>"
|
||||
for role, name in dto["profiles"].items()
|
||||
for role, name in project.profiles.items()
|
||||
)
|
||||
workflow_rows = "".join(
|
||||
f"<tr><th>{_escape(key)}</th><td><code>{_escape(path)}</code></td></tr>"
|
||||
for key, path in dto["workflow_paths"].items()
|
||||
for key, path in project.workflow_paths.items()
|
||||
)
|
||||
schema_rows = "".join(
|
||||
f"<tr><th>{_escape(key)}</th><td><code>{_escape(path)}</code></td></tr>"
|
||||
for key, path in dto["schema_paths"].items()
|
||||
for key, path in project.schema_paths.items()
|
||||
)
|
||||
checklist_items = []
|
||||
for index, step in enumerate(dto["onboarding_checklist"], start=1):
|
||||
state_label = _STATE_LABELS.get(step["state"], step["state"])
|
||||
requirement = "required" if step["required"] else "optional"
|
||||
for index, step in enumerate(project.onboarding_checklist, start=1):
|
||||
checklist_items.append(
|
||||
f"<li class=\"step-{_escape(step['state'])}\">"
|
||||
f"<strong>{index}. {_escape(step['title'])}</strong>"
|
||||
f" <span class=\"badge\">{_escape(state_label)}</span>"
|
||||
f" <span class=\"meta\">({_escape(requirement)})</span>"
|
||||
f"<p>{_escape(step['description'])}</p>"
|
||||
"<li>"
|
||||
f"<strong>{index}. {_escape(step.title)}</strong>"
|
||||
f"<p>{_escape(step.description)}</p>"
|
||||
"</li>"
|
||||
)
|
||||
checklist_html = (
|
||||
@@ -107,38 +69,16 @@ def render_project_detail(project: ProjectRecord) -> str:
|
||||
if checklist_items
|
||||
else "<p>No onboarding steps defined.</p>"
|
||||
)
|
||||
summary = dto["onboarding_summary"]
|
||||
summary_html = (
|
||||
"<p class=\"meta\">Onboarding: "
|
||||
f"{_escape(_progress_label(summary))}; required outstanding "
|
||||
f"{summary['required_outstanding']}.</p>"
|
||||
)
|
||||
health = dto["last_seen_health"]
|
||||
health_html = (
|
||||
"<p class=\"meta\">No health probe recorded (Phase 1 is read-only).</p>"
|
||||
if health is None
|
||||
else (
|
||||
"<table class=\"detail\">"
|
||||
f"<tr><th>Status</th><td><code>{_escape(health['status'])}</code></td></tr>"
|
||||
f"<tr><th>Checked at</th><td>{_escape(str(health['checked_at'] or 'unknown'))}</td></tr>"
|
||||
f"<tr><th>Detail</th><td>{_escape(str(health['detail'] or ''))}</td></tr>"
|
||||
"</table>"
|
||||
)
|
||||
)
|
||||
remote_name = dto["remote_name"] or "unset"
|
||||
body = (
|
||||
f"<h2>{_escape(dto['repo_name'])}</h2>"
|
||||
f"<h2>{_escape(project.repo_name)}</h2>"
|
||||
"<p><a href=\"/projects\">← All projects</a></p>"
|
||||
"<h3>Identity</h3>"
|
||||
"<table class=\"detail\">"
|
||||
f"<tr><th>Registry id</th><td><code>{_escape(dto['id'])}</code></td></tr>"
|
||||
f"<tr><th>Status</th><td><code>{_escape(dto['status'])}</code></td></tr>"
|
||||
f"<tr><th>Gitea owner</th><td>{_escape(dto['gitea_owner'])}</td></tr>"
|
||||
f"<tr><th>Repository</th><td><code>{_escape(dto['repo_full_name'])}</code></td></tr>"
|
||||
f"<tr><th>Remote name</th><td><code>{_escape(remote_name)}</code></td></tr>"
|
||||
f"<tr><th>Remote host</th><td>{_escape(dto['remote_host'])}</td></tr>"
|
||||
f"<tr><th>Default branch</th><td><code>{_escape(dto['default_branch'])}</code></td></tr>"
|
||||
f"<tr><th>Local checkout</th><td><code>{_escape(dto['local_checkout_path'])}</code></td></tr>"
|
||||
f"<tr><th>Registry id</th><td><code>{_escape(project.id)}</code></td></tr>"
|
||||
f"<tr><th>Gitea owner</th><td>{_escape(project.gitea_owner)}</td></tr>"
|
||||
f"<tr><th>Remote host</th><td>{_escape(project.remote_host)}</td></tr>"
|
||||
f"<tr><th>Default branch</th><td><code>{_escape(project.default_branch)}</code></td></tr>"
|
||||
f"<tr><th>Local checkout</th><td><code>{_escape(project.local_checkout_path)}</code></td></tr>"
|
||||
"</table>"
|
||||
"<h3>Profiles</h3>"
|
||||
f"<table class=\"detail\">{profile_rows}</table>"
|
||||
@@ -146,30 +86,8 @@ def render_project_detail(project: ProjectRecord) -> str:
|
||||
f"<table class=\"detail\">{workflow_rows}</table>"
|
||||
"<h3>Schema paths</h3>"
|
||||
f"<table class=\"detail\">{schema_rows}</table>"
|
||||
"<h3>Last seen health</h3>"
|
||||
f"{health_html}"
|
||||
"<h3>Onboarding checklist</h3>"
|
||||
"<p class=\"meta\">Read-only — complete these steps outside the UI.</p>"
|
||||
f"{summary_html}"
|
||||
"<p class=\"meta\">Read-only MVP — complete these steps outside the UI.</p>"
|
||||
f"{checklist_html}"
|
||||
f"<p><a href=\"/api/v1/projects/{_escape(dto['id'])}\">JSON detail</a></p>"
|
||||
)
|
||||
return render_page(title=dto["repo_name"], body_html=body)
|
||||
|
||||
|
||||
def render_registry_error(error: RegistryError) -> str:
|
||||
"""Render a fail-closed page for an invalid registry."""
|
||||
source = str(error.source_path) if error.source_path else "unknown"
|
||||
field = error.field_path or "n/a"
|
||||
body = (
|
||||
"<h2>Project registry unavailable</h2>"
|
||||
"<p>The registry failed validation, so the console refuses to render a "
|
||||
"partial inventory.</p>"
|
||||
"<table class=\"detail\">"
|
||||
f"<tr><th>Detail</th><td>{_escape(error.message)}</td></tr>"
|
||||
f"<tr><th>Field</th><td><code>{_escape(field)}</code></td></tr>"
|
||||
f"<tr><th>Source</th><td><code>{_escape(source)}</code></td></tr>"
|
||||
f"<tr><th>Remediation</th><td>{_escape(error.remediation)}</td></tr>"
|
||||
"</table>"
|
||||
)
|
||||
return render_page(title="Project registry unavailable", body_html=body)
|
||||
return render_page(title=project.repo_name, body_html=body)
|
||||
Reference in New Issue
Block a user