feat: complete M2 content workspace and inspector

This commit is contained in:
Rbanh committed 2026-07-17 23:40:49 -04:00
1 parent 931f561e7f
commit cf6eaba534
438 files changed
+59749 -19043

No files matched your search

+127
View File
@@ -0,0 +1,127 @@
#!/usr/bin/env python3
"""Enforce Blacksite's module-size debt ratchet."""
from __future__ import annotations
import argparse
import tempfile
import tomllib
from pathlib import Path
def nonblank_lines(path: Path) -> int:
return sum(1 for line in path.read_text(encoding="utf-8").splitlines() if line.strip())
def module_limit(relative: str, policy: dict) -> int:
if relative in policy.get("shells", {}):
return int(policy["limits"]["ui_shell"])
if relative.startswith("crates/editor/src/ui/"):
return int(policy["limits"]["ui_module"])
return int(policy["limits"]["production_rust_module"])
def validate_exception(entry: dict) -> list[str]:
required = ("path", "issue", "rationale", "maximum", "extraction_target", "expiry_milestone")
missing = [name for name in required if not entry.get(name)]
errors = [f"invalid exception for {entry.get('path', '<unknown>')}: missing {name}" for name in missing]
if entry.get("issue") and not str(entry["issue"]).startswith("#"):
errors.append(f"invalid exception for {entry['path']}: issue must be a tracker reference")
return errors
def audit(root: Path, policy: dict) -> tuple[list[str], list[str]]:
errors: list[str] = []
notes: list[str] = []
baselines = {str(path): int(value) for path, value in policy.get("baselines", {}).items()}
exceptions = {entry.get("path"): entry for entry in policy.get("exceptions", [])}
for entry in policy.get("exceptions", []):
errors.extend(validate_exception(entry))
for path in sorted((root / "crates").glob("**/*.rs")):
relative = path.relative_to(root).as_posix()
count = nonblank_lines(path)
limit = module_limit(relative, policy)
baseline = baselines.get(relative)
exception = exceptions.get(relative)
if baseline is not None and count > baseline:
errors.append(f"{relative}: {count} nonblank lines exceeds frozen baseline {baseline}")
continue
if baseline is not None and count < baseline:
notes.append(f"{relative}: shrank from baseline {baseline} to {count}")
if count <= limit:
continue
if baseline is not None:
continue
if exception is not None and count <= int(exception["maximum"]):
notes.append(f"{relative}: temporary {exception['issue']} exception ({count}/{exception['maximum']})")
continue
errors.append(f"{relative}: {count} nonblank lines exceeds module budget {limit}")
return errors, notes
def load_policy(path: Path) -> dict:
with path.open("rb") as handle:
policy = tomllib.load(handle)
if policy.get("version") != 1:
raise SystemExit(f"unsupported architecture policy version in {path}")
return policy
def self_test() -> int:
with tempfile.TemporaryDirectory(prefix="blacksite-architecture-audit-") as directory:
root = Path(directory)
(root / "crates/editor/src/ui").mkdir(parents=True)
policy = {
"limits": {"ui_shell": 2, "ui_module": 3, "production_rust_module": 4},
"shells": {"crates/editor/src/ui/shell.rs": 2},
"baselines": {"crates/editor/src/ui/legacy.rs": 5},
"exceptions": [],
}
(root / "crates/editor/src/ui/new.rs").write_text("a\nb\nc\nd\n", encoding="utf-8")
errors, _ = audit(root, policy)
assert any("new.rs" in error for error in errors)
(root / "crates/editor/src/ui/new.rs").write_text("a\nb\n", encoding="utf-8")
(root / "crates/editor/src/ui/legacy.rs").write_text("a\nb\nc\nd\ne\nf\n", encoding="utf-8")
errors, _ = audit(root, policy)
assert any("frozen baseline" in error for error in errors)
(root / "crates/editor/src/ui/legacy.rs").write_text("a\nb\nc\nd\n", encoding="utf-8")
errors, notes = audit(root, policy)
assert not errors and any("shrank" in note for note in notes)
policy["exceptions"] = [{
"path": "crates/editor/src/ui/new.rs", "issue": "#1", "rationale": "test",
"maximum": 4, "extraction_target": "test module", "expiry_milestone": "M2",
}]
(root / "crates/editor/src/ui/new.rs").write_text("a\nb\nc\nd\n", encoding="utf-8")
errors, _ = audit(root, policy)
assert not errors
policy["exceptions"][0]["issue"] = "missing-prefix"
errors, _ = audit(root, policy)
assert any("tracker reference" in error for error in errors)
print("PASS architecture-audit self-test")
return 0
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("command", choices=("check", "self-test"), nargs="?", default="check")
parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[2])
arguments = parser.parse_args()
if arguments.command == "self-test":
return self_test()
root = arguments.root.resolve()
policy = load_policy(root / ".codex/architecture.toml")
errors, notes = audit(root, policy)
for note in notes:
print(f"NOTE {note}")
if errors:
for error in errors:
print(f"FAIL {error}")
return 1
print("PASS architecture-audit")
return 0
if __name__ == "__main__":
raise SystemExit(main())
+1745
View File
File diff suppressed because it is too large. Load diff
+848
View File
@@ -0,0 +1,848 @@
#!/usr/bin/env python3
"""Resolve and execute Cargo commands in bounded, signature-stable build lanes.
This module intentionally uses only the Python standard library. It is also
imported by build_storage.py, so lane identity and sentinel validation have one
implementation.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import re
import shlex
import shutil
import subprocess
import sys
import tempfile
from dataclasses import asdict, dataclass
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Iterable, Mapping, Sequence
try:
import tomllib
except ModuleNotFoundError as error: # pragma: no cover - Python < 3.11
raise SystemExit("cargo_lane.py requires Python 3.11 or newer") from error
SCHEMA_VERSION = 1
SENTINEL_NAME = ".blacksite-cargo-lane.json"
LANE_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
SEPARATE_BUILD_DIR_MINIMUM = (1, 91, 0)
DEFAULT_BUILD_STORAGE: dict[str, Any] = {
"cache_root": "cargo-cache-home",
"workspace_partition": "canonical-path-hash",
"dev_target_dir": "target",
"exceptional_target_root": "target/lanes",
"persistent_lane": "dev",
"candidate_lane": "candidate",
"hot_reload_lane": "hot-reload",
"full_debug_lane": "full-debug",
"package_lane": "package",
}
class LaneError(RuntimeError):
"""A lane cannot be resolved or safely reused."""
def utc_now() -> str:
return datetime.now(timezone.utc).isoformat(timespec="seconds")
def canonical_path(path: Path | str) -> Path:
return Path(path).expanduser().resolve(strict=False)
def workspace_root(start: Path | None = None) -> Path:
override = os.environ.get("BLACKSITE_WORKSPACE_ROOT")
if override:
candidate = canonical_path(override)
elif start is not None:
candidate = canonical_path(start)
else:
candidate = canonical_path(Path(__file__).parents[2])
for current in (candidate, *candidate.parents):
if (current / "Cargo.toml").is_file() and (current / ".git").exists():
return current
raise LaneError(f"could not locate a Cargo workspace from {candidate}")
def workspace_hash(root: Path) -> str:
return hashlib.sha256(os.fsencode(str(canonical_path(root)))).hexdigest()[:20]
def cargo_home() -> Path:
return canonical_path(os.environ.get("CARGO_HOME", Path.home() / ".cargo"))
def load_workflow(root: Path) -> dict[str, Any]:
path = root / ".codex" / "workflow.toml"
document: dict[str, Any] = {}
if path.is_file():
with path.open("rb") as handle:
loaded = tomllib.load(handle)
if not isinstance(loaded, dict):
raise LaneError(f"workflow config is not a TOML table: {path}")
document = loaded
storage = dict(DEFAULT_BUILD_STORAGE)
configured = document.get("build_storage", {})
if configured:
if not isinstance(configured, dict):
raise LaneError("[build_storage] must be a TOML table")
storage.update(configured)
verification = document.get("verification", {})
if isinstance(verification, dict):
for source, destination in (
("persistent_lane", "persistent_lane"),
("candidate_lane", "candidate_lane"),
("hot_reload_lane", "hot_reload_lane"),
("full_debug_lane", "full_debug_lane"),
("package_lane", "package_lane"),
):
if source in verification:
storage[destination] = verification[source]
document["build_storage"] = storage
return document
def _configured_path(root: Path, value: str, *, base: Path | None = None) -> Path:
expanded = Path(os.path.expandvars(os.path.expanduser(value)))
if expanded.is_absolute():
return canonical_path(expanded)
return canonical_path((base or root) / expanded)
def cache_root(root: Path, workflow: Mapping[str, Any]) -> Path:
override = os.environ.get("BLACKSITE_BUILD_CACHE_ROOT")
if override:
return canonical_path(override)
storage = workflow["build_storage"]
configured = str(storage.get("cache_root", "cargo-cache-home"))
if configured == "cargo-cache-home":
return cargo_home() / "blacksite-build"
if configured == "workspace-parent-cache":
return canonical_path(root.parent / ".blacksite-build-cache")
return _configured_path(root, configured)
def parse_version(text: str) -> tuple[int, int, int]:
match = re.search(r"\b(\d+)\.(\d+)\.(\d+)", text)
if not match:
return (0, 0, 0)
return tuple(int(part) for part in match.groups()) # type: ignore[return-value]
def _capture(command: Sequence[str]) -> str:
try:
completed = subprocess.run(
command,
check=False,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
text=True,
)
except OSError as error:
return f"unavailable: {error}"
return completed.stdout.strip()
def toolchain_info() -> dict[str, Any]:
cargo_text = _capture(["cargo", "-Vv"])
rustc_text = _capture(["rustc", "-Vv"])
host = "unknown"
for line in rustc_text.splitlines():
if line.startswith("host:"):
host = line.partition(":")[2].strip()
break
version = parse_version(cargo_text)
return {
"cargo": cargo_text.splitlines()[0] if cargo_text else "unavailable",
"cargo_version": ".".join(str(part) for part in version),
"rustc": rustc_text.splitlines()[0] if rustc_text else "unavailable",
"host": host,
"separate_build_dir": version >= SEPARATE_BUILD_DIR_MINIMUM,
}
def _repo_target_config(root: Path, target: str) -> dict[str, Any]:
path = root / ".cargo" / "config.toml"
result: dict[str, Any] = {"linker": None, "rustflags": []}
if path.is_file():
with path.open("rb") as handle:
config = tomllib.load(handle)
target_table = config.get("target", {})
if isinstance(target_table, dict):
values = target_table.get(target, {})
if isinstance(values, dict):
result["linker"] = values.get("linker")
flags = values.get("rustflags", [])
if isinstance(flags, list):
result["rustflags"] = [str(flag) for flag in flags]
encoded_flags = os.environ.get("CARGO_ENCODED_RUSTFLAGS")
if encoded_flags:
result["rustflags"] = [flag for flag in encoded_flags.split("\x1f") if flag]
result["rustflags_source"] = "CARGO_ENCODED_RUSTFLAGS"
elif os.environ.get("RUSTFLAGS"):
result["rustflags"] = shlex.split(os.environ["RUSTFLAGS"])
result["rustflags_source"] = "environment"
else:
result["rustflags_source"] = str(path) if path.is_file() else "cargo-default"
result["rustc_wrapper"] = os.environ.get("RUSTC_WRAPPER")
linker_variable = "CARGO_TARGET_" + target.upper().replace("-", "_") + "_LINKER"
if os.environ.get(linker_variable):
result["linker"] = os.environ[linker_variable]
return result
def validate_lane_name(lane: str) -> str:
if not LANE_RE.fullmatch(lane):
raise LaneError(
f"invalid lane {lane!r}; use lowercase letters, digits, and hyphens"
)
return lane
def profile_directory(profile: str) -> str:
if profile in {"dev", "test"}:
return "debug"
if profile in {"release", "bench"}:
return "release"
return profile
@dataclass(frozen=True)
class CommandContext:
profile: str
profile_dir: str
feature_signature: str
cargo_subcommand: str | None
target_triple: str | None
PROJECT_ALIAS_SUBCOMMANDS = {
"bake-navigation",
"package-project",
"process-assets",
"upgrade-project",
"validate-levels",
"validate-samples",
}
def command_context(command: Sequence[str], lane: str) -> CommandContext:
args = list(command)
cargo_index: int | None = None
for index, value in enumerate(args[:2]):
if Path(value).name == "cargo":
cargo_index = index
break
cargo_args = args[cargo_index + 1 :] if cargo_index is not None else []
subcommand = next((arg for arg in cargo_args if not arg.startswith("-")), None)
# Arguments following Blacksite's Cargo aliases are forwarded to the xtask
# binary by the alias's trailing `--`. They are not Cargo options. In
# particular, `cargo package-project --profile package-qa` selects the
# package manifest profile and must not repartition the Cargo build lane.
cargo_options = (
cargo_args[: cargo_args.index(subcommand) + 1]
if subcommand in PROJECT_ALIAS_SUBCOMMANDS
else cargo_args
)
if "--release" in cargo_options:
profile = "release"
else:
profile = "test" if subcommand == "test" else "dev"
for index, value in enumerate(cargo_options):
if value.startswith("--profile="):
profile = value.partition("=")[2]
elif value == "--profile" and index + 1 < len(cargo_options):
profile = cargo_options[index + 1]
features: set[str] = set()
all_features = "--all-features" in cargo_options
no_default = "--no-default-features" in cargo_options
for index, value in enumerate(cargo_options):
raw: str | None = None
if value.startswith("--features="):
raw = value.partition("=")[2]
elif value.startswith("-F") and value != "-F":
raw = value[2:]
elif value in {"--features", "-F"} and index + 1 < len(cargo_options):
raw = cargo_options[index + 1]
if raw:
features.update(part for part in re.split(r"[ ,]+", raw) if part)
target_triple: str | None = None
for index, value in enumerate(cargo_options):
if value.startswith("--target="):
target_triple = value.partition("=")[2]
elif value == "--target" and index + 1 < len(cargo_options):
target_triple = cargo_options[index + 1]
if all_features:
feature_signature = "all-features"
else:
parts = ["no-default" if no_default else "default"]
if features:
parts.append("features=" + ",".join(sorted(features)))
feature_signature = ";".join(parts)
# These disposable lanes intentionally contain a bounded family of
# package-specific feature sets. Hot reload needs the editor's
# `dev,hot-reload` build and `game_hot`'s `dylib` build in one isolated
# runtime lane; package aliases likewise expand to different internal
# features. They must never spill into the persistent default-feature lane.
if lane == "hot-reload":
if all_features:
raise LaneError("all-features belongs in the candidate lane")
feature_signature = "hot-reload-family"
elif lane == "package":
feature_signature = "package-family"
if lane == "dev" and (all_features or "hot-reload" in features):
raise LaneError(
"the persistent dev lane cannot be used for all-features or hot-reload"
)
if lane == "candidate" and subcommand is not None and not all_features:
raise LaneError("the candidate lane requires --all-features")
return CommandContext(
profile=profile,
profile_dir=profile_directory(profile),
feature_signature=feature_signature,
cargo_subcommand=subcommand,
target_triple=target_triple,
)
@dataclass(frozen=True)
class LaneLayout:
workspace: str
workspace_hash: str
lane: str
mode: str
cache_root: str
lane_root: str
target_dir: str
build_dir: str
profile: str
profile_dir: str
runtime_deps: str
feature_signature: str
toolchain: dict[str, Any]
linker: str | None
rustflags: list[str]
rustflags_source: str
rustc_wrapper: str | None
target_triple: str
def lane_layout(
root: Path,
lane: str,
workflow: Mapping[str, Any],
command: Sequence[str] = (),
*,
toolchain: Mapping[str, Any] | None = None,
) -> LaneLayout:
lane = validate_lane_name(lane)
root = canonical_path(root)
info = dict(toolchain or toolchain_info())
context = command_context(command, lane)
storage = workflow["build_storage"]
cache = canonical_path(cache_root(root, workflow))
partition = cache / workspace_hash(root)
lane_root = partition / lane
separate = bool(info.get("separate_build_dir"))
effective_target = context.target_triple or str(info.get("host", "unknown"))
if (
context.target_triple
and context.target_triple != info.get("host")
and not lane.startswith("cross-")
):
raise LaneError("cross-target Cargo commands require a cross-* disposable lane")
persistent = str(storage.get("persistent_lane", "dev"))
if separate:
if lane == persistent:
target = _configured_path(
root, str(storage.get("dev_target_dir", "target"))
)
else:
exceptional = _configured_path(
root, str(storage.get("exceptional_target_root", "target/lanes"))
)
target = exceptional / lane
build = lane_root
mode = "separate-build-dir"
else:
target = lane_root / "target"
build = target
mode = "external-target-dir-fallback"
target_config = _repo_target_config(root, effective_target)
profile_path = Path(context.profile_dir)
if context.target_triple:
profile_path = Path(context.target_triple) / profile_path
return LaneLayout(
workspace=str(root),
workspace_hash=workspace_hash(root),
lane=lane,
mode=mode,
cache_root=str(cache),
lane_root=str(lane_root),
target_dir=str(target),
build_dir=str(build),
profile=context.profile,
profile_dir=context.profile_dir,
runtime_deps=str(build / profile_path / "deps"),
feature_signature=context.feature_signature,
toolchain=info,
linker=target_config.get("linker"),
rustflags=list(target_config.get("rustflags", [])),
rustflags_source=str(target_config.get("rustflags_source")),
rustc_wrapper=target_config.get("rustc_wrapper"),
target_triple=effective_target,
)
def lane_environment(layout: LaneLayout) -> dict[str, str]:
environment = {
"CARGO_TARGET_DIR": layout.target_dir,
"BLACKSITE_CARGO_LANE": layout.lane,
"BLACKSITE_WORKSPACE_HASH": layout.workspace_hash,
}
if layout.mode == "separate-build-dir":
environment["CARGO_BUILD_BUILD_DIR"] = layout.build_dir
if layout.lane in {"candidate", "package", "full-debug"}:
environment["CARGO_INCREMENTAL"] = "0"
if layout.lane == "full-debug":
environment["CARGO_PROFILE_DEV_DEBUG"] = "full"
environment["CARGO_PROFILE_TEST_DEBUG"] = "full"
return environment
def sentinel_path(path: Path) -> Path:
return path / SENTINEL_NAME
def read_sentinel(path: Path) -> dict[str, Any] | None:
marker = sentinel_path(path)
if not marker.is_file() or marker.is_symlink():
return None
try:
with marker.open("r", encoding="utf-8") as handle:
value = json.load(handle)
except (OSError, json.JSONDecodeError):
return None
return value if isinstance(value, dict) else None
def validate_sentinel(
path: Path,
document: Mapping[str, Any],
*,
root: Path,
lane: str,
role: str,
) -> list[str]:
errors: list[str] = []
expected = {
"schema_version": SCHEMA_VERSION,
"workspace": str(canonical_path(root)),
"workspace_hash": workspace_hash(root),
"lane": lane,
"role": role,
"path": str(canonical_path(path)),
}
for key, value in expected.items():
if document.get(key) != value:
errors.append(f"{key}: expected {value!r}, found {document.get(key)!r}")
return errors
def _signature(layout: LaneLayout) -> dict[str, Any]:
# The persistent development and candidate lanes intentionally serve both
# Cargo's `dev` and `test` profiles. Cargo fingerprints those profiles
# independently, while keeping them in one bounded ordinary/candidate lane
# avoids multiplying the Bevy dependency graph into permanent caches.
profile_signature = "dev-test" if layout.profile in {"dev", "test"} else layout.profile
return {
"toolchain": layout.toolchain,
"target_triple": layout.target_triple,
"linker": layout.linker,
"rustflags": layout.rustflags,
"rustc_wrapper": layout.rustc_wrapper,
"feature_signature": layout.feature_signature,
"profile_signature": profile_signature,
"mode": layout.mode,
"lane_environment": lane_environment(layout),
}
def _signature_compatible(existing: object, requested: Mapping[str, Any]) -> bool:
if existing == requested:
return True
if not isinstance(existing, Mapping):
return False
previous = dict(existing)
current = dict(requested)
previous_profile = previous.pop("profile_signature", None)
current_profile = current.pop("profile_signature", None)
return (
previous == current
and previous_profile in {"dev", "test"}
and current_profile == "dev-test"
)
def _atomic_json(path: Path, document: Mapping[str, Any]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
descriptor, temporary = tempfile.mkstemp(
prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
)
try:
with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
json.dump(document, handle, indent=2, sort_keys=True)
handle.write("\n")
handle.flush()
os.fsync(handle.fileno())
os.replace(temporary, path)
finally:
try:
os.unlink(temporary)
except FileNotFoundError:
pass
def _prepare_marker(
path: Path, layout: LaneLayout, role: str, *, allow_create: bool
) -> dict[str, Any]:
if path.is_symlink():
raise LaneError(f"refusing symlinked lane path: {path}")
if allow_create:
path.mkdir(parents=True, exist_ok=True)
if not path.is_dir():
raise LaneError(f"lane path does not exist: {path}")
existing = read_sentinel(path)
now = utc_now()
signature = _signature(layout)
if existing is not None:
errors = validate_sentinel(
path, existing, root=Path(layout.workspace), lane=layout.lane, role=role
)
if errors:
raise LaneError(
f"invalid lane sentinel at {path}: " + "; ".join(errors)
)
if not _signature_compatible(existing.get("signature"), signature):
raise LaneError(
"lane signature changed; select the correct exceptional lane or reset "
f"the whole lane after a dry run: {layout.lane}"
)
document = dict(existing)
document["signature"] = signature
document["last_use"] = now
document["last_profile"] = layout.profile
else:
document = {
"schema_version": SCHEMA_VERSION,
"workspace": layout.workspace,
"workspace_hash": layout.workspace_hash,
"lane": layout.lane,
"role": role,
"path": str(canonical_path(path)),
"target_dir": layout.target_dir,
"build_dir": layout.build_dir,
"signature": signature,
"created_at": now,
"last_use": now,
"last_profile": layout.profile,
}
_atomic_json(sentinel_path(path), document)
return document
def prepare_lane(layout: LaneLayout) -> None:
lane_root = Path(layout.lane_root)
_prepare_marker(lane_root, layout, "build", allow_create=True)
target = Path(layout.target_dir)
workspace_target = Path(layout.workspace) / "target"
if target != workspace_target and target != Path(layout.build_dir):
_prepare_marker(target, layout, "target", allow_create=True)
def require_prepared_lane(layout: LaneLayout) -> None:
lane_root = Path(layout.lane_root)
marker = read_sentinel(lane_root)
if marker is None:
raise LaneError(
f"lane {layout.lane!r} has not been built through cargo_lane.py"
)
errors = validate_sentinel(
lane_root,
marker,
root=Path(layout.workspace),
lane=layout.lane,
role="build",
)
if errors:
raise LaneError("invalid prepared lane: " + "; ".join(errors))
def layout_document(layout: LaneLayout) -> dict[str, Any]:
document = asdict(layout)
document["environment"] = lane_environment(layout)
document["sentinel"] = str(sentinel_path(Path(layout.lane_root)))
return document
def _shell_environment(values: Mapping[str, str]) -> str:
return "\n".join(
f"export {name}={shlex.quote(value)}" for name, value in sorted(values.items())
)
def _run_command(layout: LaneLayout, command: Sequence[str], *, dry_run: bool) -> int:
if not command:
raise LaneError("missing command after --")
if dry_run:
print(
json.dumps(
{"layout": layout_document(layout), "command": list(command)},
indent=2,
sort_keys=True,
)
)
return 0
prepare_lane(layout)
environment = os.environ.copy()
environment.update(lane_environment(layout))
return subprocess.run(command, cwd=layout.workspace, env=environment).returncode
def _resolve_runtime_command(layout: LaneLayout, command: Sequence[str]) -> list[str]:
if not command:
raise LaneError("missing runtime command after --")
resolved = list(command)
executable = Path(resolved[0])
if not executable.is_absolute():
parts = executable.parts
if parts and parts[0] == "target":
executable = Path(layout.target_dir).joinpath(*parts[1:])
elif "/" in resolved[0]:
executable = Path(layout.workspace) / executable
resolved[0] = str(canonical_path(executable)) if "/" in str(executable) else str(executable)
return resolved
def _run_runtime(layout: LaneLayout, command: Sequence[str], *, dry_run: bool) -> int:
require_prepared_lane(layout)
resolved = _resolve_runtime_command(layout, command)
environment = os.environ.copy()
dependencies = layout.runtime_deps
existing = environment.get("LD_LIBRARY_PATH")
environment["LD_LIBRARY_PATH"] = (
dependencies if not existing else dependencies + os.pathsep + existing
)
environment.update(lane_environment(layout))
if dry_run:
print(
json.dumps(
{
"layout": layout_document(layout),
"command": resolved,
"LD_LIBRARY_PATH": environment["LD_LIBRARY_PATH"],
},
indent=2,
sort_keys=True,
)
)
return 0
os.chdir(layout.workspace)
os.execvpe(resolved[0], resolved, environment)
raise AssertionError("os.execvpe unexpectedly returned") # pragma: no cover
def _self_test() -> dict[str, Any]:
checks: list[str] = []
assert parse_version("cargo 1.97.0 (abc)") == (1, 97, 0)
checks.append("cargo-version-parsing")
assert profile_directory("test") == "debug"
assert profile_directory("package-qa") == "package-qa"
checks.append("profile-directory-mapping")
try:
validate_lane_name("../escape")
except LaneError:
checks.append("lane-name-traversal-rejected")
else: # pragma: no cover
raise AssertionError("unsafe lane name accepted")
with tempfile.TemporaryDirectory(prefix="blacksite-lane-self-test-") as temporary:
root = Path(temporary) / "workspace"
(root / ".git").mkdir(parents=True)
(root / "Cargo.toml").write_text("[workspace]\nmembers = []\n", encoding="utf-8")
workflow = {"build_storage": dict(DEFAULT_BUILD_STORAGE)}
workflow["build_storage"]["cache_root"] = str(Path(temporary) / "cache")
fake_toolchain = {
"cargo": "cargo 1.97.0",
"cargo_version": "1.97.0",
"rustc": "rustc 1.97.0",
"host": "x86_64-unknown-linux-gnu",
"separate_build_dir": True,
}
layout = lane_layout(root, "dev", workflow, ["cargo", "check"], toolchain=fake_toolchain)
prepare_lane(layout)
marker = read_sentinel(Path(layout.lane_root))
assert marker is not None
assert not validate_sentinel(
Path(layout.lane_root), marker, root=root, lane="dev", role="build"
)
checks.append("sentinel-round-trip")
assert Path(layout.target_dir) == root / "target"
assert Path(layout.build_dir) != Path(layout.target_dir)
checks.append("separate-build-dir-layout")
test_layout = lane_layout(
root, "dev", workflow, ["cargo", "test"], toolchain=fake_toolchain
)
prepare_lane(test_layout)
assert read_sentinel(Path(layout.lane_root))["signature"]["profile_signature"] == "dev-test"
checks.append("dev-and-test-share-persistent-lane")
hot_editor = lane_layout(
root,
"hot-reload",
workflow,
["cargo", "build", "-p", "editor", "--features", "dev,hot-reload"],
toolchain=fake_toolchain,
)
hot_game = lane_layout(
root,
"hot-reload",
workflow,
["cargo", "build", "-p", "game_hot", "--features", "dylib"],
toolchain=fake_toolchain,
)
assert hot_editor.feature_signature == hot_game.feature_signature == "hot-reload-family"
checks.append("hot-reload-feature-family-isolated")
package = lane_layout(
root,
"package",
workflow,
["cargo", "package-project", "--project", ".", "--profile", "package-qa"],
toolchain=fake_toolchain,
)
assert package.profile == "dev"
assert package.feature_signature == "package-family"
checks.append("project-alias-options-not-cargo-options")
fallback_toolchain = dict(fake_toolchain)
fallback_toolchain["cargo_version"] = "1.90.0"
fallback_toolchain["separate_build_dir"] = False
fallback = lane_layout(
root,
"candidate",
workflow,
["cargo", "test", "--all-features"],
toolchain=fallback_toolchain,
)
assert fallback.mode == "external-target-dir-fallback"
assert Path(fallback.target_dir) == Path(fallback.lane_root) / "target"
assert fallback.build_dir == fallback.target_dir
checks.append("external-target-dir-fallback")
cross = lane_layout(
root,
"cross-wasm",
workflow,
["cargo", "check", "--target", "wasm32-unknown-unknown"],
toolchain=fake_toolchain,
)
assert cross.target_triple == "wasm32-unknown-unknown"
assert "wasm32-unknown-unknown" in cross.runtime_deps
checks.append("cross-target-partition")
return {"ok": True, "checks": checks}
def _command_tail(values: Iterable[str]) -> list[str]:
result = list(values)
if result and result[0] == "--":
result.pop(0)
return result
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--workspace", type=Path, help="workspace root override")
subparsers = parser.add_subparsers(dest="action", required=True)
env_parser = subparsers.add_parser("env", help="describe a lane environment")
env_parser.add_argument("lane")
env_parser.add_argument("--json", action="store_true")
exec_parser = subparsers.add_parser("exec", help="execute a command in a lane")
exec_parser.add_argument("lane")
exec_parser.add_argument("--dry-run", action="store_true")
exec_parser.add_argument("command", nargs=argparse.REMAINDER)
run_parser = subparsers.add_parser("run", help="run an existing lane artifact")
run_parser.add_argument("lane")
run_parser.add_argument("--dry-run", action="store_true")
run_parser.add_argument("command", nargs=argparse.REMAINDER)
subparsers.add_parser("self-test", help="run temp-directory safety checks")
return parser
def main(argv: Sequence[str] | None = None) -> int:
arguments = build_parser().parse_args(argv)
if arguments.action == "self-test":
print(json.dumps(_self_test(), indent=2, sort_keys=True))
return 0
try:
root = workspace_root(arguments.workspace)
workflow = load_workflow(root)
raw_command = list(getattr(arguments, "command", []))
# argparse.REMAINDER intentionally preserves arbitrary child-command
# flags. Accept our one wrapper flag after the lane as well as before it.
if arguments.action in {"exec", "run"} and "--dry-run" in raw_command:
separator = raw_command.index("--") if "--" in raw_command else len(raw_command)
if raw_command.index("--dry-run") < separator:
arguments.dry_run = True
raw_command.remove("--dry-run")
command = _command_tail(raw_command)
layout = lane_layout(root, arguments.lane, workflow, command)
if arguments.action == "env":
document = layout_document(layout)
if arguments.json:
print(json.dumps(document, indent=2, sort_keys=True))
else:
print(_shell_environment(document["environment"]))
return 0
if arguments.action == "exec":
return _run_command(layout, command, dry_run=arguments.dry_run)
if arguments.action == "run":
return _run_runtime(layout, command, dry_run=arguments.dry_run)
except LaneError as error:
print(f"cargo-lane: {error}", file=sys.stderr)
return 2
return 2
if __name__ == "__main__":
raise SystemExit(main())
+315
View File
@@ -0,0 +1,315 @@
#!/usr/bin/env python3
"""Validate Blacksite documentation authority coverage and lifecycle banners."""
from __future__ import annotations
import argparse
import fnmatch
import json
import re
import subprocess
import sys
import tomllib
from collections import Counter
from dataclasses import dataclass
from pathlib import Path
from typing import Any
AUTHORITY_PATH = Path("docs/authority.toml")
BANNER_MARKERS = {
"active-plan": "**active plan",
"evidence": "**evidence record",
"historical": "**historical",
"superseded": "**superseded",
}
LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
@dataclass(frozen=True)
class Rule:
id: str
classification: str
priority: int
path: str | None = None
prefix: str | None = None
role: str | None = None
replacement: str | None = None
topics: tuple[str, ...] = ()
def matches(self, candidate: str) -> bool:
if self.path is not None:
return candidate == self.path
if self.prefix is not None:
return candidate.startswith(self.prefix)
return False
def repository_root() -> Path:
current = Path(__file__).resolve()
for parent in current.parents:
if (parent / AUTHORITY_PATH).is_file():
return parent
raise RuntimeError(f"cannot locate repository root containing {AUTHORITY_PATH}")
def load_authority(root: Path) -> tuple[dict[str, Any], list[Rule]]:
raw = tomllib.loads((root / AUTHORITY_PATH).read_text(encoding="utf-8"))
rules: list[Rule] = []
for item in raw.get("rules", []):
selectors = [name for name in ("path", "prefix") if item.get(name) is not None]
if len(selectors) != 1:
raise ValueError(f"rule {item.get('id', '<unknown>')} must set exactly one path or prefix")
rules.append(
Rule(
id=item["id"],
classification=item["classification"],
priority=int(item.get("priority", 0)),
path=item.get("path"),
prefix=item.get("prefix"),
role=item.get("role"),
replacement=item.get("replacement"),
topics=tuple(item.get("topics", [])),
)
)
return raw, rules
def discover_documents(root: Path, authority: dict[str, Any]) -> list[str]:
discovery = authority.get("discovery", {})
found: set[str] = set()
for relative in discovery.get("paths", []):
path = root / relative
if path.is_file() and path.suffix == ".md":
found.add(path.relative_to(root).as_posix())
for relative in discovery.get("trees", []):
tree = root / relative
if tree.is_dir():
found.update(path.relative_to(root).as_posix() for path in tree.rglob("*.md"))
return sorted(found)
def resolve_rule(path: str, rules: list[Rule]) -> tuple[Rule | None, str | None]:
matches = [rule for rule in rules if rule.matches(path)]
if not matches:
return None, None
highest = max(rule.priority for rule in matches)
winners = [rule for rule in matches if rule.priority == highest]
classifications = {rule.classification for rule in winners}
if len(classifications) != 1:
names = ", ".join(rule.id for rule in winners)
return None, f"equal-priority rules disagree: {names}"
winners.sort(key=lambda rule: (rule.path is not None, len(rule.path or rule.prefix or "")), reverse=True)
return winners[0], None
def normalized_link_target(root: Path, document: Path, raw_target: str) -> str | None:
target = raw_target.split("#", 1)[0].strip().strip("<>")
if not target or "://" in target or target.startswith("mailto:"):
return None
resolved = (document.parent / target).resolve()
try:
return resolved.relative_to(root.resolve()).as_posix()
except ValueError:
return None
def path_matches(path: str, pattern: str) -> bool:
if pattern.endswith("/**"):
return path.startswith(pattern[:-2])
return fnmatch.fnmatchcase(path, pattern)
def validate_links(root: Path, relative: str) -> list[str]:
path = root / relative
text = path.read_text(encoding="utf-8")
errors: list[str] = []
for raw_target in LINK_RE.findall(text):
target = raw_target.split("#", 1)[0].strip().strip("<>")
if not target or "://" in target or target.startswith(("mailto:", "#")):
continue
normalized = normalized_link_target(root, path, raw_target)
if normalized is None:
errors.append(f"link escapes the repository: {raw_target}")
continue
if not (root / normalized).exists():
errors.append(f"broken relative link: {raw_target}")
return errors
def changed_documents(root: Path) -> set[str]:
changed: set[str] = set()
commands = [
["git", "diff", "--name-only", "--relative", "HEAD"],
["git", "ls-files", "--others", "--exclude-standard"],
]
for command in commands:
result = subprocess.run(command, cwd=root, check=False, capture_output=True, text=True)
if result.returncode != 0:
raise RuntimeError(f"failed to query changed files: {' '.join(command)}")
changed.update(line.strip() for line in result.stdout.splitlines() if line.strip())
return changed
def validate_banner(root: Path, relative: str, rule: Rule) -> list[str]:
if rule.classification == "current":
return []
path = root / relative
text = path.read_text(encoding="utf-8")
head = "\n".join(text.splitlines()[:180])
lowered = head.lower()
marker = BANNER_MARKERS[rule.classification]
if marker not in lowered:
# ADR 0019 predates Markdown heading style but has an explicit first-line status.
if not (rule.classification == "superseded" and lowered.startswith("status: superseded")):
return [f"missing {rule.classification} banner near the start of the document"]
if rule.classification not in {"evidence", "historical", "superseded"}:
return []
links = {
normalized
for target in LINK_RE.findall(head)
if (normalized := normalized_link_target(root, path, target)) is not None
}
if not links:
return ["lifecycle banner must link to current canonical guidance"]
if rule.replacement and rule.replacement not in links:
return [f"lifecycle banner must link to configured replacement {rule.replacement}"]
return []
def audit(root: Path, *, changed_only: bool = False, topic: str | None = None) -> dict[str, Any]:
authority, rules = load_authority(root)
allowed = set(authority.get("classifications", []))
allowed_roles = set(authority.get("roles", []))
errors: list[str] = []
warnings: list[str] = []
if authority.get("version") != 1:
errors.append("docs/authority.toml: unsupported or missing version")
if allowed != {"current", "active-plan", "evidence", "historical", "superseded"}:
errors.append("docs/authority.toml: classifications must be the five workflow classes")
for rule in rules:
if rule.classification not in allowed:
errors.append(f"rule {rule.id}: unknown classification {rule.classification}")
if not rule.role or rule.role not in allowed_roles:
errors.append(f"rule {rule.id}: unknown or missing role {rule.role}")
if rule.path and not (root / rule.path).is_file():
errors.append(f"rule {rule.id}: exact path does not exist: {rule.path}")
if rule.replacement and not (root / rule.replacement).is_file():
errors.append(f"rule {rule.id}: replacement does not exist: {rule.replacement}")
counts: Counter[str] = Counter()
documents: list[dict[str, str]] = []
resolved: list[tuple[str, Rule]] = []
for relative in discover_documents(root, authority):
rule, conflict = resolve_rule(relative, rules)
if conflict:
errors.append(f"{relative}: {conflict}")
continue
if rule is None:
errors.append(f"{relative}: unclassified")
continue
resolved.append((relative, rule))
counts[rule.classification] += 1
documents.append(
{
"path": relative,
"classification": rule.classification,
"rule": rule.id,
"role": rule.role or "",
"topics": ",".join(rule.topics),
}
)
canonical_owners: dict[str, list[str]] = {}
for relative, rule in resolved:
if rule.role == "canonical" and rule.classification == "current":
for owned_topic in rule.topics:
canonical_owners.setdefault(owned_topic, []).append(relative)
for owned_topic, owners in sorted(canonical_owners.items()):
if len(owners) > 1:
errors.append(f"topic {owned_topic}: multiple canonical owners: {', '.join(owners)}")
selected = resolved
if changed_only:
changed = changed_documents(root)
if AUTHORITY_PATH.as_posix() not in changed:
selected = [(path, rule) for path, rule in selected if path in changed]
if topic:
selected = [(path, rule) for path, rule in selected if topic in rule.topics]
if not selected:
errors.append(f"topic {topic}: no classified documents")
stale_terms = authority.get("stale_terms", [])
for relative, rule in selected:
for error in validate_banner(root, relative, rule):
errors.append(f"{relative}: {error}")
for error in validate_links(root, relative):
errors.append(f"{relative}: {error}")
if rule.classification != "current":
continue
text = (root / relative).read_text(encoding="utf-8")
lowered = text.lower()
for stale in stale_terms:
if any(path_matches(relative, allowed_path) for allowed_path in stale.get("allowed_paths", [])):
continue
pattern = stale["pattern"]
if pattern.lower() in lowered:
errors.append(
f"{relative}: stale term {pattern!r}; use {stale.get('replacement', 'current terminology')}"
)
if rule.role == "canonical":
if re.search(r"(?im)^\s*- \[ \]", text):
warnings.append(f"{relative}: unchecked checklist in canonical documentation; review status semantics")
if re.search(r"(?i)\bnot implemented\b|\((?:still\s+)?planned\)", text):
warnings.append(f"{relative}: possible future-status language in canonical documentation; review semantically")
return {
"ok": not errors,
"authority": AUTHORITY_PATH.as_posix(),
"documents": documents,
"counts": dict(sorted(counts.items())),
"errors": errors,
"warnings": warnings,
"selected": len(selected),
}
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--json", action="store_true", help="emit the complete machine-readable report")
parser.add_argument("--list", action="store_true", help="list every classified document")
parser.add_argument("--changed", action="store_true", help="check lifecycle, links, and terms only in changed documents")
parser.add_argument("--topic", help="check lifecycle, links, and terms only for one configured topic")
args = parser.parse_args()
try:
result = audit(repository_root(), changed_only=args.changed, topic=args.topic)
except (OSError, RuntimeError, ValueError, tomllib.TOMLDecodeError) as error:
print(f"FAIL docs-authority — {error}", file=sys.stderr)
return 1
if args.json:
print(json.dumps(result, indent=2, sort_keys=True))
else:
status = "PASS" if result["ok"] else "FAIL"
counts = ", ".join(f"{name}={count}" for name, count in result["counts"].items())
print(
f"{status} docs-authority — {len(result['documents'])} classified, "
f"{result['selected']} checked — {counts}"
)
if args.list:
for document in result["documents"]:
print(f"{document['classification']:11} {document['path']} ({document['rule']})")
for error in result["errors"]:
print(f"ERROR {error}", file=sys.stderr)
for warning in result["warnings"]:
print(f"WARN {warning}", file=sys.stderr)
return 0 if result["ok"] else 1
if __name__ == "__main__":
raise SystemExit(main())
+348
View File
@@ -0,0 +1,348 @@
#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)"
SCENARIO_ROOT="$ROOT/.agents/skills/blacksite-native-qa/references/scenarios"
STATE_ROOT="$ROOT/.codex/session"
EVIDENCE_ROOT="$ROOT/.codex/evidence"
usage() {
echo "usage: $0 plan|launch|attach|capture|record|status|restore|close <scenario-name> [arguments]" >&2
exit 2
}
[[ $# -ge 2 ]] || usage
ACTION="$1"
NAME="$2"
SCENARIO="$SCENARIO_ROOT/$NAME.yaml"
[[ -f "$SCENARIO" ]] || { echo "native-qa: unknown scenario $NAME" >&2; exit 2; }
field() {
local key="$1"
sed -n "s/^${key}:[[:space:]]*//p" "$SCENARIO" | head -n 1
}
LANE="$(field build_lane)"
[[ -n "$LANE" ]] || LANE="dev"
FIXTURE="$(field fixture)"
mkdir -p "$STATE_ROOT" "$EVIDENCE_ROOT"
lane_json() {
python "$ROOT/scripts/codex/cargo_lane.py" env "$LANE" --json
}
list_section() {
local section="$1"
awk -v section="$section" '
$0 == section ":" { active = 1; next }
active && /^[^[:space:]]/ { exit }
active && /^[[:space:]]+-[[:space:]]+/ {
sub(/^[[:space:]]+-[[:space:]]+/, "")
print
}
' "$SCENARIO"
}
snapshot_fixture() {
local record="$STATE_ROOT/native-$NAME.json"
local snapshot="$STATE_ROOT/native-$NAME.fixture.snapshot"
python - "$ROOT" "$FIXTURE" "$record" "$snapshot" "$LANE" "$SCENARIO" <<'PY'
import hashlib, json, os, pathlib, shutil, sys, time
root = pathlib.Path(sys.argv[1]).resolve()
fixture_text, record_text, snapshot_text, lane, scenario = sys.argv[2:]
record = pathlib.Path(record_text)
snapshot = pathlib.Path(snapshot_text)
if record.is_file():
previous = json.loads(record.read_text(encoding="utf-8"))
pid = previous.get("pid")
if pid:
try:
os.kill(int(pid), 0)
except ProcessLookupError:
pass
except PermissionError:
raise SystemExit(f"native-qa: cannot verify existing runner PID {pid}; refusing launch")
else:
raise SystemExit(f"native-qa: existing runner PID {pid} is still active")
old_fixture = previous.get("fixture")
if old_fixture and not old_fixture.get("restored"):
raise SystemExit("native-qa: restore the previous fixture before launching this scenario again")
record.unlink()
snapshot.unlink(missing_ok=True)
data = {
"pid": None,
"lane": lane,
"scenario": scenario,
"spawned_by_runner": False,
"prepared_at": time.time(),
"assertions": {},
"evidence": [],
}
if fixture_text:
fixture = (root / fixture_text).resolve()
if fixture != root and root not in fixture.parents:
raise SystemExit(f"fixture escapes workspace: {fixture}")
if fixture.exists() and not fixture.is_file():
raise SystemExit(f"fixture is not a regular file: {fixture}")
existed = fixture.is_file()
baseline = hashlib.sha256(fixture.read_bytes()).hexdigest() if existed else None
if existed:
shutil.copy2(fixture, snapshot)
data["fixture"] = {
"path": str(fixture),
"existed": existed,
"baseline_sha256": baseline,
"snapshot": str(snapshot) if existed else None,
"restored": False,
}
record.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
PY
}
case "$ACTION" in
plan)
LANE_JSON="$(lane_json)" python - "$SCENARIO" "$FIXTURE" <<'PY'
import json, os, pathlib, sys
layout = json.loads(os.environ["LANE_JSON"])
scenario = pathlib.Path(sys.argv[1])
fixture = sys.argv[2]
binary = pathlib.Path(layout["target_dir"]) / layout["profile_dir"] / "editor"
print(f"PASS native-qa-plan — {scenario.stem}")
print(f"Lane: {layout['lane']} ({layout['mode']})")
print(f"Binary: {binary}")
print(f"Runtime deps: {layout['runtime_deps']}")
print(f"Fixture: {fixture or 'scenario-defined'}")
print("Visual interaction remains manual/user-controlled until explicitly delegated.")
PY
echo "Purpose: $(field purpose)"
echo "Preconditions: $(field preconditions)"
echo "Steps:"
list_section steps | nl -w2 -s'. '
echo "Assertions:"
list_section assertions | nl -w2 -s'. '
echo "Evidence: $(field evidence)"
echo "Cleanup: $(field cleanup)"
;;
launch)
snapshot_fixture
python "$ROOT/scripts/codex/build_storage.py" enforce --phase pre
python "$ROOT/scripts/codex/summarize_command.py" \
--gate "native-$NAME-build" \
--log "$ROOT/.codex/logs/native-$NAME-build.log" \
--json-result "$ROOT/.codex/logs/native-$NAME-build.json" \
-- python "$ROOT/scripts/codex/cargo_lane.py" exec "$LANE" -- cargo build -p editor --bin editor
python "$ROOT/scripts/codex/build_storage.py" enforce --phase post
nohup python "$ROOT/scripts/codex/cargo_lane.py" run "$LANE" -- \
target/debug/editor --project "$ROOT" \
>"$ROOT/.codex/logs/native-$NAME-launch.log" 2>&1 &
PID=$!
python - "$STATE_ROOT/native-$NAME.json" "$PID" <<'PY'
import json, pathlib, sys, time
path = pathlib.Path(sys.argv[1])
data = json.loads(path.read_text(encoding="utf-8"))
data.update({"pid": int(sys.argv[2]), "spawned_at": time.time(), "spawned_by_runner": True})
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
PY
echo "PASS native-qa-launch — $NAME — PID $PID"
;;
attach)
[[ $# -eq 3 ]] || usage
PID="$3"
kill -0 "$PID" 2>/dev/null || { echo "native-qa: PID $PID is not running" >&2; exit 2; }
CMDLINE="$(tr '\0' ' ' <"/proc/$PID/cmdline")"
[[ "$CMDLINE" == *"editor"* ]] || { echo "native-qa: refusing unexpected process: $CMDLINE" >&2; exit 2; }
snapshot_fixture
python - "$STATE_ROOT/native-$NAME.json" "$PID" <<'PY'
import json, pathlib, sys, time
path = pathlib.Path(sys.argv[1])
data = json.loads(path.read_text(encoding="utf-8"))
data.update({"pid": int(sys.argv[2]), "attached_at": time.time(), "spawned_by_runner": False})
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
PY
echo "PASS native-qa-attach — $NAME — PID $PID"
;;
capture)
[[ $# -eq 3 ]] || usage
PID="$3"
kill -0 "$PID" 2>/dev/null || { echo "native-qa: PID $PID is not running" >&2; exit 2; }
CLIENTS="$(hyprctl clients -j)"
GEOMETRY="$(CLIENTS_JSON="$CLIENTS" python - "$PID" <<'PY'
import json, os, sys
pid = int(sys.argv[1])
matches = [c for c in json.loads(os.environ["CLIENTS_JSON"]) if c.get("pid") == pid]
if len(matches) != 1:
raise SystemExit(f"expected one Hyprland window for PID {pid}, found {len(matches)}")
client = matches[0]
x, y = client["at"]
w, h = client["size"]
if w <= 0 or h <= 0:
raise SystemExit("target window has invalid geometry")
print(f"{x},{y} {w}x{h}")
PY
)"
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
IMAGE="$EVIDENCE_ROOT/$NAME-$STAMP.png"
grim -g "$GEOMETRY" "$IMAGE"
HASH="$(sha256sum "$IMAGE" | awk '{print $1}')"
python - "$STATE_ROOT/native-$NAME-evidence.json" "$PID" "$IMAGE" "$HASH" "$GEOMETRY" <<'PY'
import json, pathlib, sys, time
path = pathlib.Path(sys.argv[1])
path.write_text(json.dumps({
"pid": int(sys.argv[2]), "image": sys.argv[3], "sha256": sys.argv[4],
"geometry": sys.argv[5], "captured_at": time.time(),
}, indent=2) + "\n", encoding="utf-8")
PY
python - "$STATE_ROOT/native-$NAME.json" "$IMAGE" "$HASH" "$GEOMETRY" <<'PY'
import json, pathlib, sys, time
path = pathlib.Path(sys.argv[1])
if not path.is_file():
raise SystemExit("native-qa: missing runner record")
data = json.loads(path.read_text(encoding="utf-8"))
data.setdefault("evidence", []).append({
"image": sys.argv[2], "sha256": sys.argv[3], "geometry": sys.argv[4],
"captured_at": time.time(),
})
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
PY
echo "PASS native-qa-capture — $NAME — $IMAGE — $HASH"
;;
record)
[[ $# -ge 4 && $# -le 5 ]] || usage
INDEX="$3"
RESULT="$4"
NOTE="${5:-}"
[[ "$INDEX" =~ ^[1-9][0-9]*$ ]] || { echo "native-qa: assertion index must be positive" >&2; exit 2; }
[[ "$RESULT" = "pass" || "$RESULT" = "fail" ]] || { echo "native-qa: result must be pass or fail" >&2; exit 2; }
ASSERTION_COUNT="$(list_section assertions | wc -l)"
(( INDEX <= ASSERTION_COUNT )) || { echo "native-qa: assertion $INDEX exceeds count $ASSERTION_COUNT" >&2; exit 2; }
ASSERTION_TEXT="$(list_section assertions | sed -n "${INDEX}p")"
python - "$STATE_ROOT/native-$NAME.json" "$INDEX" "$RESULT" "$NOTE" "$ASSERTION_TEXT" <<'PY'
import json, pathlib, sys, time
path = pathlib.Path(sys.argv[1])
if not path.is_file():
raise SystemExit("native-qa: missing runner record")
data = json.loads(path.read_text(encoding="utf-8"))
data.setdefault("assertions", {})[sys.argv[2]] = {
"result": sys.argv[3], "note": sys.argv[4], "text": sys.argv[5],
"recorded_at": time.time(),
}
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
PY
echo "PASS native-qa-record — $NAME — assertion $INDEX = $RESULT"
;;
status)
[[ $# -eq 2 ]] || usage
RECORD="$STATE_ROOT/native-$NAME.json"
[[ -f "$RECORD" ]] || { echo "native-qa: no runner record for $NAME" >&2; exit 2; }
ASSERTION_COUNT="$(list_section assertions | wc -l)"
python - "$RECORD" "$ASSERTION_COUNT" <<'PY'
import json, pathlib, sys, time
path = pathlib.Path(sys.argv[1])
data = json.loads(path.read_text(encoding="utf-8"))
expected = int(sys.argv[2])
results = data.get("assertions", {})
passed = sum(item.get("result") == "pass" for item in results.values())
failed = sum(item.get("result") == "fail" for item in results.values())
print(f"native-qa-status — assertions {passed} pass, {failed} fail, {expected - len(results)} unrecorded")
print(f"evidence: {len(data.get('evidence', []))} capture(s)")
fixture = data.get("fixture")
if fixture:
print(f"fixture restored: {bool(fixture.get('restored'))}")
complete = not failed and len(results) == expected and bool(data.get("evidence"))
data["scenario_result"] = {"result": "PASS" if complete else "FAIL", "recorded_at": time.time()}
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
if not complete:
raise SystemExit(1)
PY
;;
restore)
[[ $# -eq 3 ]] || usage
MODE="$3"
[[ "$MODE" = "--dry-run" || "$MODE" = "--apply" ]] || usage
RECORD="$STATE_ROOT/native-$NAME.json"
[[ -f "$RECORD" ]] || { echo "native-qa: no runner record for $NAME" >&2; exit 2; }
python - "$RECORD" "$MODE" "$ROOT" <<'PY'
import hashlib, json, os, pathlib, shutil, sys, tempfile, time
record = pathlib.Path(sys.argv[1])
apply = sys.argv[2] == "--apply"
root = pathlib.Path(sys.argv[3]).resolve()
data = json.loads(record.read_text(encoding="utf-8"))
fixture = data.get("fixture")
if not fixture:
print("PASS native-qa-restore — scenario has no fixture")
raise SystemExit(0)
path = pathlib.Path(fixture["path"]).resolve()
if path != root and root not in path.parents:
raise SystemExit(f"native-qa: fixture escapes workspace: {path}")
pid = data.get("pid")
if apply and pid:
try:
os.kill(int(pid), 0)
except ProcessLookupError:
pass
except PermissionError:
raise SystemExit(f"native-qa: cannot verify runner PID {pid}; refusing fixture restore")
else:
raise SystemExit(f"native-qa: close runner PID {pid} before restoring the fixture")
current = hashlib.sha256(path.read_bytes()).hexdigest() if path.is_file() else None
baseline = fixture.get("baseline_sha256")
action = "restore snapshot" if fixture.get("existed") else "remove scenario-created fixture"
print(f"native-qa-restore-plan — {action}")
print(f"fixture: {path}")
print(f"baseline sha256: {baseline or '(absent)'}")
print(f"current sha256: {current or '(absent)'}")
sys.stdout.flush()
if not apply:
raise SystemExit(0)
if fixture.get("existed"):
snapshot = pathlib.Path(fixture["snapshot"])
if not snapshot.is_file():
raise SystemExit(f"native-qa: missing fixture snapshot: {snapshot}")
snapshot_hash = hashlib.sha256(snapshot.read_bytes()).hexdigest()
if snapshot_hash != baseline:
raise SystemExit("native-qa: fixture snapshot hash does not match recorded baseline")
path.parent.mkdir(parents=True, exist_ok=True)
with tempfile.NamedTemporaryFile(dir=path.parent, prefix=f".{path.name}.", delete=False) as handle:
temp = pathlib.Path(handle.name)
handle.write(snapshot.read_bytes())
os.replace(temp, path)
else:
if path.exists() and not path.is_file():
raise SystemExit(f"native-qa: refusing to remove non-file fixture path: {path}")
path.unlink(missing_ok=True)
fixture["restored"] = True
fixture["restored_at"] = time.time()
record.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
print("PASS native-qa-restore")
PY
;;
close)
[[ $# -eq 3 ]] || usage
PID="$3"
RECORD="$STATE_ROOT/native-$NAME.json"
[[ -f "$RECORD" ]] || { echo "native-qa: no runner record for $NAME" >&2; exit 2; }
RECORDED="$(python -c 'import json,sys; print(json.load(open(sys.argv[1]))["pid"])' "$RECORD")"
[[ "$RECORDED" = "$PID" ]] || { echo "native-qa: PID does not match runner record" >&2; exit 2; }
SPAWNED="$(python -c 'import json,sys; print(str(bool(json.load(open(sys.argv[1])).get("spawned_by_runner"))).lower())' "$RECORD")"
if [[ "$SPAWNED" = "true" ]] && kill -0 "$PID" 2>/dev/null; then
CMDLINE="$(tr '\0' ' ' <"/proc/$PID/cmdline")"
[[ "$CMDLINE" == *"editor"* ]] || { echo "native-qa: refusing to stop unexpected process: $CMDLINE" >&2; exit 2; }
kill -TERM "$PID"
fi
python - "$RECORD" <<'PY'
import json, pathlib, time, sys
path = pathlib.Path(sys.argv[1])
data = json.loads(path.read_text(encoding="utf-8"))
data["closed_at"] = time.time()
data["detached_only"] = not bool(data.get("spawned_by_runner"))
if data["detached_only"]:
data["detached_pid"] = data.get("pid")
data["pid"] = None
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
PY
echo "PASS native-qa-close — $NAME — PID $PID"
;;
*) usage ;;
esac
+995
View File
@@ -0,0 +1,995 @@
#!/usr/bin/env python3
"""Maintain Blacksite's compact, resumable Codex session state.
The state is intentionally Markdown rather than an opaque database so a resumed
agent can read it cheaply. This module uses only the Python standard library.
"""
from __future__ import annotations
import argparse
import contextlib
import copy
import hashlib
import io
import os
import subprocess
import sys
import tempfile
import tomllib
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Iterable, Sequence
TITLE = "# Codex session state"
WORKFLOW_PATH = Path(".codex/workflow.toml")
VALID_STATES = (
"Implementing",
"Engineering-complete",
"Acceptance-in-progress",
"Candidate-ready",
)
CLASSIFICATIONS = {
"active-slice-refinement": "active-slice refinement",
"active-slice refinement": "active-slice refinement",
"newly-discovered-blocker": "newly discovered blocker",
"newly discovered blocker": "newly discovered blocker",
"discovered-blocker": "newly discovered blocker",
"added-acceptance-criterion": "added acceptance criterion",
"added acceptance criterion": "added acceptance criterion",
"separate-follow-up": "separate follow-up",
"separate follow-up": "separate follow-up",
}
class StateError(RuntimeError):
"""The state operation cannot be completed safely."""
def clean_text(value: str | None, default: str = "None.") -> str:
"""Keep state entries single-line and compact."""
if value is None:
return default
compact = " ".join(value.split())
return compact or default
def utc_now() -> str:
return datetime.now(timezone.utc).isoformat(timespec="seconds")
def find_repository(start: Path | None = None) -> Path:
"""Locate the nearest repository containing the workflow configuration."""
override = os.environ.get("BLACKSITE_WORKSPACE_ROOT")
configured = None
config_path = (start or Path.cwd()) / ".codex/config.toml"
if not override and config_path.is_file():
with config_path.open("rb") as handle:
configured = tomllib.load(handle).get("workspace_root")
candidates = [Path(override or configured)] if (override or configured) else [start or Path.cwd()]
if start is None and not override:
candidates.append(Path(__file__).parent)
visited: set[Path] = set()
for candidate in candidates:
candidate = candidate.expanduser().absolute()
for current in (candidate, *candidate.parents):
canonical = current.resolve(strict=False)
if canonical in visited:
continue
visited.add(canonical)
if (current / WORKFLOW_PATH).is_file():
return current
searched = ", ".join(str(path) for path in candidates)
raise StateError(f"could not locate {WORKFLOW_PATH} from {searched}")
def load_workflow(root: Path) -> dict[str, Any]:
path = root / WORKFLOW_PATH
try:
with path.open("rb") as handle:
workflow = tomllib.load(handle)
except OSError as error:
raise StateError(f"cannot read workflow configuration {path}: {error}") from error
except tomllib.TOMLDecodeError as error:
raise StateError(f"invalid workflow configuration {path}: {error}") from error
if workflow.get("version") != 1:
raise StateError(f"unsupported or missing workflow version in {path}")
return workflow
def configured_path(root: Path, raw: str, *, label: str) -> Path:
candidate = Path(os.path.expandvars(os.path.expanduser(raw)))
if not candidate.is_absolute():
candidate = root / candidate
candidate = candidate.absolute()
try:
candidate.resolve(strict=False).relative_to(root.resolve(strict=False))
except ValueError as error:
raise StateError(f"configured {label} must remain inside the repository: {candidate}") from error
return candidate
def state_path(root: Path, workflow: dict[str, Any]) -> Path:
session = workflow.get("session", {})
if not isinstance(session, dict):
raise StateError("[session] must be a TOML table")
raw = session.get("state_file", ".codex/session/STATE.md")
if not isinstance(raw, str) or not raw:
raise StateError("session.state_file must be a non-empty path string")
return configured_path(root, raw, label="session.state_file")
def max_state_lines(workflow: dict[str, Any]) -> int:
session = workflow.get("session", {})
value = session.get("max_state_lines", 180) if isinstance(session, dict) else 180
if not isinstance(value, int) or value < 48:
raise StateError("session.max_state_lines must be an integer of at least 48")
return value
def run_git(root: Path, *arguments: str, check: bool = True) -> subprocess.CompletedProcess[str]:
try:
result = subprocess.run(
["git", "-C", str(root), *arguments],
check=False,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
)
except OSError as error:
raise StateError(f"cannot execute git: {error}") from error
if check and result.returncode != 0:
detail = clean_text(result.stderr or result.stdout, "git command failed")
raise StateError(detail)
return result
def worktree_summary(root: Path) -> str:
lines = run_git(root, "status", "--porcelain=v1", "--untracked-files=normal").stdout.splitlines()
if not lines:
return "clean"
staged = modified = deleted = untracked = conflicts = 0
conflict_codes = {"DD", "AU", "UD", "UA", "DU", "AA", "UU"}
for line in lines:
if len(line) < 2:
continue
code = line[:2]
if code == "??":
untracked += 1
continue
if code in conflict_codes:
conflicts += 1
if code[0] not in {" ", "?"}:
staged += 1
if code[1] not in {" ", "?"}:
modified += 1
if "D" in code:
deleted += 1
return (
"dirty "
f"(staged={staged}, modified={modified}, deleted={deleted}, "
f"untracked={untracked}, conflicts={conflicts})"
)
@dataclass
class RepositoryState:
root: str
real_path: str
branch: str
head: str
worktree: str
active_processes: str = "None recorded."
def repository_snapshot(root: Path, active_processes: str = "None recorded.") -> RepositoryState:
git_root = Path(run_git(root, "rev-parse", "--show-toplevel").stdout.strip())
real_path = git_root.resolve(strict=False)
branch_result = run_git(root, "symbolic-ref", "--quiet", "--short", "HEAD", check=False)
branch = branch_result.stdout.strip() if branch_result.returncode == 0 else "(detached)"
head = run_git(root, "rev-parse", "HEAD").stdout.strip()
return RepositoryState(
root=str(git_root),
real_path=str(real_path),
branch=branch,
head=head,
worktree=worktree_summary(root),
active_processes=clean_text(active_processes, "None recorded."),
)
@dataclass
class AcceptanceCriterion:
text: str
checked: bool = False
@dataclass
class ScopeDelta:
title: str
source: str
classification: str
requirement: str
evidence_valid: str
invalidated_gates: str
tracker_sync: str
@dataclass
class IntentionalFile:
path: str
reason: str
@dataclass
class GateRecord:
gate: str
status: str
digest: str
command: str
date: str
@dataclass
class SessionState:
repository: RepositoryState
goal: str
current_state: str = "Implementing"
issues: str = "None."
milestone: str = "None."
active_slice: str = "None."
non_goals: str = "None."
acceptance: list[AcceptanceCriterion] = field(default_factory=list)
deltas: list[ScopeDelta] = field(default_factory=list)
files: list[IntentionalFile] = field(default_factory=list)
gates: list[GateRecord] = field(default_factory=list)
native_evidence: list[str] = field(default_factory=list)
decisions: list[str] = field(default_factory=list)
remote_actions: list[str] = field(default_factory=list)
next_action: str = "Define the next action."
def section_map(text: str) -> dict[str, list[str]]:
sections: dict[str, list[str]] = {}
current: str | None = None
for line in text.splitlines():
if line.startswith("## "):
current = line[3:].strip()
sections[current] = []
elif current is not None:
sections[current].append(line)
return sections
def field_value(lines: Iterable[str], name: str, default: str = "None.") -> str:
prefix = f"- {name}:"
for line in lines:
if line.startswith(prefix):
return clean_text(line[len(prefix) :], default)
return default
def bullet_values(lines: Iterable[str]) -> list[str]:
values: list[str] = []
for line in lines:
if line.startswith("- ") and not line.startswith("- ["):
value = clean_text(line[2:])
if value != "None.":
values.append(value)
return values
def parse_deltas(lines: list[str]) -> list[ScopeDelta]:
chunks: list[tuple[str, list[str]]] = []
title: str | None = None
body: list[str] = []
for line in lines:
if line.startswith("### Delta "):
if title is not None:
chunks.append((title, body))
heading = line.partition("—")[2].strip()
title = heading or "Untitled scope delta"
body = []
elif title is not None:
body.append(line)
if title is not None:
chunks.append((title, body))
return [
ScopeDelta(
title=clean_text(title),
source=field_value(body, "Source"),
classification=field_value(body, "Classification"),
requirement=field_value(body, "Added/changed requirement"),
evidence_valid=field_value(body, "Prior evidence still valid"),
invalidated_gates=field_value(body, "Invalidated gates"),
tracker_sync=field_value(body, "Tracker sync required", "no"),
)
for title, body in chunks
]
def parse_state(text: str) -> SessionState:
if not text.startswith(TITLE):
raise StateError(f"state file must begin with {TITLE!r}")
sections = section_map(text)
repository_lines = sections.get("Repository", [])
task_lines = sections.get("Active task", [])
repository = RepositoryState(
root=field_value(repository_lines, "Root"),
real_path=field_value(repository_lines, "Real path"),
branch=field_value(repository_lines, "Branch"),
head=field_value(repository_lines, "HEAD"),
worktree=field_value(repository_lines, "Worktree status summary"),
active_processes=field_value(repository_lines, "Active processes/windows", "None recorded."),
)
acceptance: list[AcceptanceCriterion] = []
for line in sections.get("Acceptance target", []):
stripped = line.strip()
if stripped.startswith("- [ ] "):
acceptance.append(AcceptanceCriterion(clean_text(stripped[6:])))
elif stripped.lower().startswith("- [x] "):
acceptance.append(AcceptanceCriterion(clean_text(stripped[6:]), checked=True))
files: list[IntentionalFile] = []
for value in bullet_values(sections.get("Files intentionally changed", [])):
path, separator, reason = value.partition(" — ")
files.append(IntentionalFile(path, reason if separator else "Reason not recorded."))
gates: list[GateRecord] = []
for value in bullet_values(sections.get("Verification ledger summary", [])):
parts = value.split(" — ", 4)
if len(parts) == 5:
gates.append(GateRecord(*parts))
next_values = bullet_values(sections.get("Exact next action", []))
return SessionState(
repository=repository,
goal=field_value(task_lines, "Goal"),
current_state=field_value(task_lines, "Current state", "Implementing"),
issues=field_value(task_lines, "Gitea issue(s)"),
milestone=field_value(task_lines, "Gitea milestone"),
active_slice=field_value(task_lines, "Active slice"),
non_goals=field_value(task_lines, "Non-goals"),
acceptance=acceptance,
deltas=parse_deltas(sections.get("Scope deltas", [])),
files=files,
gates=gates,
native_evidence=bullet_values(sections.get("Native evidence", [])),
decisions=bullet_values(sections.get("Decisions", [])),
remote_actions=bullet_values(sections.get("Remote actions already performed", [])),
next_action=next_values[0] if next_values else "Define the next action.",
)
def render_lines(state: SessionState) -> list[str]:
lines = [
TITLE,
"",
"## Repository",
f"- Root: {clean_text(state.repository.root)}",
f"- Real path: {clean_text(state.repository.real_path)}",
f"- Branch: {clean_text(state.repository.branch)}",
f"- HEAD: {clean_text(state.repository.head)}",
f"- Worktree status summary: {clean_text(state.repository.worktree)}",
f"- Active processes/windows: {clean_text(state.repository.active_processes, 'None recorded.')}",
"",
"## Active task",
f"- Goal: {clean_text(state.goal)}",
f"- Current state: {clean_text(state.current_state, 'Implementing')}",
f"- Gitea issue(s): {clean_text(state.issues)}",
f"- Gitea milestone: {clean_text(state.milestone)}",
f"- Active slice: {clean_text(state.active_slice)}",
f"- Non-goals: {clean_text(state.non_goals)}",
"",
"## Acceptance target",
]
lines.extend(
f"- [{'x' if criterion.checked else ' '}] {clean_text(criterion.text)}"
for criterion in state.acceptance
)
lines.extend(["", "## Scope deltas"])
for index, delta in enumerate(state.deltas, start=1):
lines.extend(
[
f"### Delta {index} — {clean_text(delta.title)}",
f"- Source: {clean_text(delta.source)}",
f"- Classification: {clean_text(delta.classification)}",
f"- Added/changed requirement: {clean_text(delta.requirement)}",
f"- Prior evidence still valid: {clean_text(delta.evidence_valid)}",
f"- Invalidated gates: {clean_text(delta.invalidated_gates)}",
f"- Tracker sync required: {clean_text(delta.tracker_sync, 'no')}",
"",
]
)
lines.extend(["## Files intentionally changed"])
lines.extend(f"- {clean_text(item.path)} — {clean_text(item.reason)}" for item in state.files)
lines.extend(["", "## Verification ledger summary"])
lines.extend(
f"- {clean_text(item.gate)} — {clean_text(item.status)} — {clean_text(item.digest)} — "
f"{clean_text(item.command)} — {clean_text(item.date)}"
for item in state.gates
)
lines.extend(["", "## Native evidence"])
lines.extend(f"- {clean_text(item)}" for item in state.native_evidence)
lines.extend(["", "## Decisions"])
lines.extend(f"- {clean_text(item)}" for item in state.decisions)
lines.extend(["", "## Remote actions already performed"])
lines.extend(f"- {clean_text(item)}" for item in state.remote_actions)
lines.extend(
[
"",
"## Exact next action",
f"- {clean_text(state.next_action, 'Define the next action.')}",
]
)
return lines
def compact_state(state: SessionState, limit: int) -> SessionState:
"""Discard oldest ledger detail until the state fits its configured budget."""
compacted = copy.deepcopy(state)
collections: list[tuple[list[Any], int]] = [
(compacted.gates, 1),
(compacted.native_evidence, 0),
(compacted.remote_actions, 0),
(compacted.decisions, 1),
(compacted.deltas, 1),
(compacted.files, 1),
(compacted.acceptance, 1),
]
while len(render_lines(compacted)) > limit:
for values, keep in collections:
if len(values) > keep:
values.pop(0)
break
else:
raise StateError(
f"required state structure exceeds session.max_state_lines={limit}"
)
return compacted
def ensure_state_is_ignored(root: Path, path: Path) -> None:
relative = path.resolve(strict=False).relative_to(root.resolve(strict=False)).as_posix()
result = run_git(root, "check-ignore", "--quiet", "--", relative, check=False)
if result.returncode != 0:
raise StateError(
f"refusing to write tracked session state; add /{relative} or its directory to .gitignore"
)
def write_state(root: Path, workflow: dict[str, Any], state: SessionState) -> Path:
path = state_path(root, workflow)
ensure_state_is_ignored(root, path)
state = compact_state(state, max_state_lines(workflow))
text = "\n".join(render_lines(state)) + "\n"
path.parent.mkdir(parents=True, exist_ok=True)
temporary: Path | None = None
try:
with tempfile.NamedTemporaryFile(
"w",
encoding="utf-8",
dir=path.parent,
prefix=f".{path.name}.",
suffix=".tmp",
delete=False,
) as handle:
handle.write(text)
handle.flush()
os.fsync(handle.fileno())
temporary = Path(handle.name)
os.replace(temporary, path)
finally:
if temporary is not None and temporary.exists():
temporary.unlink()
return path
def read_state(root: Path, workflow: dict[str, Any]) -> SessionState:
path = state_path(root, workflow)
try:
return parse_state(path.read_text(encoding="utf-8"))
except FileNotFoundError as error:
raise StateError(f"no session state exists at {path}; run state.py init") from error
except OSError as error:
raise StateError(f"cannot read session state {path}: {error}") from error
def refresh_repository(root: Path, state: SessionState) -> list[str]:
previous = state.repository
current = repository_snapshot(root, previous.active_processes)
changes: list[str] = []
for label, before, after in (
("real path", previous.real_path, current.real_path),
("branch", previous.branch, current.branch),
("HEAD", previous.head, current.head),
):
if before not in {"None.", after}:
changes.append(f"{label}: {before} -> {after}")
state.repository = current
return changes
def normalize_repo_file(root: Path, raw: str) -> str:
candidate = Path(raw).expanduser()
if not candidate.is_absolute():
candidate = root / candidate
candidate = candidate.resolve(strict=False)
repository = root.resolve(strict=False)
try:
return candidate.relative_to(repository).as_posix()
except ValueError as error:
raise StateError(f"intentional file must be inside the repository: {candidate}") from error
def replace_or_append_file(state: SessionState, path: str, reason: str) -> None:
state.files = [item for item in state.files if item.path != path]
state.files.append(IntentionalFile(path, clean_text(reason, "Reason not recorded.")))
def replace_or_append_gate(state: SessionState, record: GateRecord) -> None:
state.gates = [item for item in state.gates if item.gate != record.gate]
state.gates.append(record)
def candidate_commit(root: Path, revision: str) -> str:
result = run_git(root, "rev-parse", "--verify", f"{revision}^{{commit}}", check=False)
if result.returncode != 0:
raise StateError(f"candidate revision is not a commit: {revision}")
return result.stdout.strip()
def git_bytes(root: Path, *arguments: str) -> bytes:
try:
result = subprocess.run(
["git", "-C", str(root), *arguments],
check=False,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
)
except OSError as error:
raise StateError(f"cannot execute git: {error}") from error
if result.returncode != 0:
detail = clean_text(result.stderr.decode("utf-8", "replace"), "git command failed")
raise StateError(detail)
return result.stdout
def _dirty_tree_digest_once(root: Path) -> str:
status_arguments = ("status", "--porcelain=v1", "-z", "--untracked-files=all")
status_before = git_bytes(root, *status_arguments)
if not status_before:
raise StateError("--dirty-tree requires a dirty worktree")
digest = hashlib.sha256()
digest.update(b"blacksite-dirty-tree-v1\0")
digest.update(git_bytes(root, "rev-parse", "HEAD"))
digest.update(b"\0status\0")
digest.update(status_before)
digest.update(b"\0tracked-diff\0")
digest.update(
git_bytes(
root,
"diff",
"--binary",
"--no-ext-diff",
"--submodule=diff",
"HEAD",
"--",
)
)
untracked = git_bytes(root, "ls-files", "--others", "--exclude-standard", "-z")
repository = root.resolve(strict=False)
for encoded in sorted(path for path in untracked.split(b"\0") if path):
relative = os.fsdecode(encoded)
relative_path = Path(relative)
if relative_path.is_absolute() or ".." in relative_path.parts:
raise StateError(f"untracked candidate path escapes the repository: {relative}")
path = repository / relative_path
digest.update(b"\0untracked\0")
digest.update(encoded)
if path.is_symlink():
digest.update(b"\0symlink\0")
digest.update(os.fsencode(os.readlink(path)))
elif path.is_file():
digest.update(b"\0file\0")
digest.update(str(path.stat().st_mode & 0o777).encode("ascii"))
with path.open("rb") as handle:
while chunk := handle.read(1024 * 1024):
digest.update(chunk)
else:
digest.update(b"\0special\0")
if git_bytes(root, *status_arguments) != status_before:
raise StateError("worktree changed while computing the candidate digest; nominate again")
return digest.hexdigest()
def dirty_tree_digest(root: Path) -> str:
"""Hash an exact stable base commit, tracked diff, and untracked source set."""
first = _dirty_tree_digest_once(root)
second = _dirty_tree_digest_once(root)
if first != second:
raise StateError("worktree changed while computing the candidate digest; nominate again")
return first
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=__doc__)
subparsers = parser.add_subparsers(dest="operation", required=True)
init = subparsers.add_parser("init", help="create a new compact session state")
init.add_argument("--goal", required=True)
init.add_argument("--accept", action="append", required=True, help="acceptance criterion; repeat as needed")
init.add_argument("--slice", dest="active_slice", required=True)
init.add_argument("--next", dest="next_action", required=True)
init.add_argument("--non-goals", default="None.")
init.add_argument("--issues", default="None.")
init.add_argument("--milestone", default="None.")
init.add_argument("--active-processes", default="None recorded.")
init.add_argument("--force", action="store_true", help="replace an existing state")
show = subparsers.add_parser("show", help="print the current state")
show.add_argument("--path", action="store_true", help="print only the state path")
subparsers.add_parser("resume", help="refresh repository identity and show the exact next action")
update = subparsers.add_parser("set", help="update active task fields")
update.add_argument("--goal")
update.add_argument("--state", choices=VALID_STATES)
update.add_argument("--issues")
update.add_argument("--milestone")
update.add_argument("--slice", dest="active_slice")
update.add_argument("--non-goals")
update.add_argument("--next", dest="next_action")
update.add_argument("--active-processes")
update.add_argument("--accept", action="append", help="replace acceptance criteria; repeat as needed")
update.add_argument("--decision", action="append", help="append a concise decision")
delta = subparsers.add_parser("scope-delta", help="record authoritative user steering")
delta.add_argument("--title", required=True)
delta.add_argument("--source", required=True)
delta.add_argument("--classification", required=True)
delta.add_argument("--requirement", required=True)
delta.add_argument("--evidence-valid", required=True)
delta.add_argument("--invalidated-gates", required=True)
delta.add_argument("--tracker-sync", choices=("yes", "no"), required=True)
delta.add_argument("--next", dest="next_action")
record_file = subparsers.add_parser("record-file", help="record an intentionally changed file")
record_file.add_argument("path")
record_file.add_argument("--reason", required=True)
record_gate = subparsers.add_parser("record-gate", help="record one compact verification result")
record_gate.add_argument("--gate", required=True)
record_gate.add_argument("--status", type=str.upper, choices=("PASS", "FAIL"), required=True)
record_gate.add_argument("--digest", required=True)
record_gate.add_argument("--command", required=True)
record_gate.add_argument("--date", default=None)
record_gate.add_argument("--next", dest="next_action")
nominate = subparsers.add_parser("nominate", help="nominate an exact candidate commit or tree digest")
candidate = nominate.add_mutually_exclusive_group()
candidate.add_argument("--commit", default="HEAD")
candidate.add_argument(
"--dirty-tree",
action="store_true",
help="explicitly nominate the current dirty tree by a reproducible digest",
)
nominate.add_argument("--next", dest="next_action")
return parser
def perform_operation(root: Path, workflow: dict[str, Any], args: argparse.Namespace) -> int:
path = state_path(root, workflow)
if args.operation == "init":
if path.exists() and not args.force:
raise StateError(f"session state already exists at {path}; use init --force to replace it")
state = SessionState(
repository=repository_snapshot(root, args.active_processes),
goal=clean_text(args.goal),
issues=clean_text(args.issues),
milestone=clean_text(args.milestone),
active_slice=clean_text(args.active_slice),
non_goals=clean_text(args.non_goals),
acceptance=[AcceptanceCriterion(clean_text(value)) for value in args.accept],
next_action=clean_text(args.next_action),
)
write_state(root, workflow, state)
print(f"PASS state-init — {path.relative_to(root.resolve(strict=False))}")
print(f"NEXT {state.next_action}")
return 0
if args.operation == "show":
# Loading the file validates that it remains template-compatible.
read_state(root, workflow)
if args.path:
print(path)
else:
print(path.read_text(encoding="utf-8"), end="")
return 0
state = read_state(root, workflow)
repository_changes = refresh_repository(root, state)
if args.operation == "resume":
write_state(root, workflow, state)
print(
f"RESUME {state.current_state} — {state.repository.branch}@{state.repository.head[:12]} — "
f"{state.goal}"
)
for change in repository_changes:
print(f"REPOSITORY CHANGED {change}")
print(f"NEXT {state.next_action}")
return 0
if args.operation == "set":
changed = False
for argument, attribute in (
("goal", "goal"),
("state", "current_state"),
("issues", "issues"),
("milestone", "milestone"),
("active_slice", "active_slice"),
("non_goals", "non_goals"),
("next_action", "next_action"),
):
value = getattr(args, argument)
if value is not None:
setattr(state, attribute, clean_text(value))
changed = True
if args.active_processes is not None:
state.repository.active_processes = clean_text(args.active_processes, "None recorded.")
changed = True
if args.accept is not None:
state.acceptance = [AcceptanceCriterion(clean_text(value)) for value in args.accept]
changed = True
if args.decision:
state.decisions.extend(clean_text(value) for value in args.decision)
changed = True
if not changed:
raise StateError("state.py set requires at least one field to update")
elif args.operation == "scope-delta":
classification_key = clean_text(args.classification).lower()
classification = CLASSIFICATIONS.get(classification_key)
if classification is None:
allowed = ", ".join(sorted(key for key in CLASSIFICATIONS if "-" in key))
raise StateError(f"unknown scope-delta classification; use one of: {allowed}")
state.deltas.append(
ScopeDelta(
title=clean_text(args.title),
source=clean_text(args.source),
classification=classification,
requirement=clean_text(args.requirement),
evidence_valid=clean_text(args.evidence_valid),
invalidated_gates=clean_text(args.invalidated_gates),
tracker_sync=args.tracker_sync,
)
)
if classification == "added acceptance criterion":
state.acceptance.append(AcceptanceCriterion(clean_text(args.requirement)))
if args.next_action:
state.next_action = clean_text(args.next_action)
elif args.operation == "record-file":
relative = normalize_repo_file(root, args.path)
replace_or_append_file(state, relative, args.reason)
elif args.operation == "record-gate":
replace_or_append_gate(
state,
GateRecord(
gate=clean_text(args.gate),
status=args.status,
digest=clean_text(args.digest),
command=clean_text(args.command),
date=clean_text(args.date or utc_now()),
),
)
if args.next_action:
state.next_action = clean_text(args.next_action)
elif args.operation == "nominate":
if args.dirty_tree:
digest = dirty_tree_digest(root)
candidate_label = f"dirty-tree sha256:{digest} based on {state.repository.head}"
else:
if state.repository.worktree != "clean":
raise StateError(
"candidate nomination requires a clean worktree; use --dirty-tree to nominate an exact dirty-tree digest"
)
commit = candidate_commit(root, args.commit)
candidate_label = f"commit {commit}"
state.current_state = "Candidate-ready"
state.decisions = [
item for item in state.decisions if not item.startswith("Candidate nominated:")
]
state.decisions.append(f"Candidate nominated: {candidate_label} at {utc_now()}.")
state.next_action = clean_text(
args.next_action,
f"Run candidate verification for {candidate_label}.",
)
else: # pragma: no cover - argparse prevents this
raise StateError(f"unknown operation: {args.operation}")
write_state(root, workflow, state)
relative = path.resolve(strict=False).relative_to(root.resolve(strict=False))
print(f"PASS state-{args.operation} — {relative}")
print(f"NEXT {state.next_action}")
return 0
def _git_fixture(root: Path) -> None:
(root / ".codex").mkdir(parents=True)
(root / ".codex/workflow.toml").write_text(
"""version = 1
[session]
state_file = ".codex/session/STATE.md"
max_state_lines = 70
""",
encoding="utf-8",
)
(root / ".gitignore").write_text("/.codex/session/\n", encoding="utf-8")
(root / "tracked.txt").write_text("fixture\n", encoding="utf-8")
env = dict(os.environ)
env.update(
{
"GIT_AUTHOR_NAME": "Blacksite self-test",
"GIT_AUTHOR_EMAIL": "self-test@example.invalid",
"GIT_COMMITTER_NAME": "Blacksite self-test",
"GIT_COMMITTER_EMAIL": "self-test@example.invalid",
}
)
for command in (
["git", "init", "--quiet", str(root)],
["git", "-C", str(root), "add", "."],
["git", "-C", str(root), "commit", "--quiet", "-m", "fixture"],
):
subprocess.run(command, check=True, env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
def self_test() -> int:
with tempfile.TemporaryDirectory(prefix="blacksite-state-self-test-") as temporary:
root = Path(temporary)
_git_fixture(root)
found = find_repository(root / "nested")
if found.resolve() != root.resolve():
raise AssertionError("repository locator did not find the temporary workflow")
workflow = load_workflow(found)
parser = build_parser()
operations = [
[
"init",
"--goal",
"Exercise resumable state",
"--accept",
"State stays concise",
"--slice",
"Workflow helpers",
"--next",
"Update the fixture state.",
],
["set", "--state", "Engineering-complete", "--next", "Record steering."],
[
"scope-delta",
"--title",
"Self-test steering",
"--source",
"self-test",
"--classification",
"active-slice-refinement",
"--requirement",
"Keep the newest exact action",
"--evidence-valid",
"Earlier fixture setup remains valid",
"--invalidated-gates",
"None",
"--tracker-sync",
"no",
"--next",
"Record the intentional file.",
],
[
"record-file",
"scripts/codex/state.py",
"--reason",
"exercise file recording",
],
[
"record-gate",
"--gate",
"state-fixture",
"--status",
"PASS",
"--digest",
"digest-fixture",
"--command",
"python state.py --self-test",
"--next",
"Resume the fixture.",
],
["resume"],
["nominate", "--next", "Run the candidate fixture gate."],
]
for operation in operations:
with contextlib.redirect_stdout(io.StringIO()):
result = perform_operation(root, workflow, parser.parse_args(operation))
if result != 0:
raise AssertionError(f"state operation failed: {operation[0]}")
state = read_state(root, workflow)
if state.current_state != "Candidate-ready":
raise AssertionError("nominate did not enter Candidate-ready state")
for index in range(12):
state.gates.append(
GateRecord(
gate=f"gate-{index}",
status="PASS",
digest=f"digest-{index}",
command=f"fixture {index}",
date=utc_now(),
)
)
state.next_action = "Nominate the fixture commit."
path = write_state(root, workflow, state)
lines = path.read_text(encoding="utf-8").splitlines()
if len(lines) > max_state_lines(workflow):
raise AssertionError("state exceeded configured line budget")
resumed = read_state(root, workflow)
if resumed.next_action != "Nominate the fixture commit.":
raise AssertionError("state round-trip lost the exact next action")
if resumed.repository.real_path != str(root.resolve()):
raise AssertionError("state did not record the canonical repository path")
commit = candidate_commit(root, "HEAD")
if len(commit) != 40:
raise AssertionError("candidate nomination did not resolve a commit")
tracked = root / "tracked.txt"
tracked.write_text("changed\n", encoding="utf-8")
dirty_digest = dirty_tree_digest(root)
if dirty_digest != dirty_tree_digest(root):
raise AssertionError("dirty candidate digest is not deterministic")
tracked.write_text("changed again\n", encoding="utf-8")
if dirty_digest == dirty_tree_digest(root):
raise AssertionError("dirty candidate digest ignored changed source bytes")
tracked.write_text("fixture\n", encoding="utf-8")
if worktree_summary(root) != "clean":
raise AssertionError("ignored state unexpectedly dirtied the fixture repository")
print("PASS state-self-test — temp repository lifecycle and line budget")
return 0
def main(argv: Sequence[str] | None = None) -> int:
arguments = list(sys.argv[1:] if argv is None else argv)
if arguments in (["--self-test"], ["self-test"]):
try:
return self_test()
except (AssertionError, OSError, StateError, subprocess.SubprocessError) as error:
print(f"FAIL state-self-test — {error}", file=sys.stderr)
return 1
parser = build_parser()
args = parser.parse_args(arguments)
try:
root = find_repository()
workflow = load_workflow(root)
return perform_operation(root, workflow, args)
except StateError as error:
print(f"FAIL state-{args.operation} — {error}", file=sys.stderr)
return 1
if __name__ == "__main__":
raise SystemExit(main())
+469
View File
@@ -0,0 +1,469 @@
#!/usr/bin/env python3
"""Run one command, retain its complete log, and print only a bounded result."""
from __future__ import annotations
import argparse
import contextlib
import io
import json
import os
import re
import shlex
import subprocess
import sys
import tempfile
import time
import tomllib
from collections import deque
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Iterable, Sequence
WORKFLOW_PATH = Path(".codex/workflow.toml")
ANSI_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
ACTIONABLE_PATTERNS = (
re.compile(r"^\s*error(?:\[[A-Z0-9]+\])?:", re.IGNORECASE),
re.compile(r"^\s*error\b", re.IGNORECASE),
re.compile(r"\bpanicked at\b", re.IGNORECASE),
re.compile(r"^\s*thread .+ panicked", re.IGNORECASE),
re.compile(r"^\s*Traceback \(most recent call last\):"),
re.compile(r"^\s*(?:AssertionError|RuntimeError|ValueError|TypeError):"),
re.compile(r"^\s*failures:\s*$", re.IGNORECASE),
re.compile(r"^\s*test result: FAILED", re.IGNORECASE),
re.compile(r"^\s*FAILED(?:\s|$)", re.IGNORECASE),
re.compile(r"^\s*FAIL(?:\s|$)", re.IGNORECASE),
re.compile(r"^\s*Caused by:\s*\S", re.IGNORECASE),
)
TEST_RESULT_RE = re.compile(
r"test result: ok\.\s*(\d+) passed;\s*(\d+) failed;\s*(\d+) ignored",
re.IGNORECASE,
)
SAFE_NAME_RE = re.compile(r"[^a-zA-Z0-9_.-]+")
class SummaryError(RuntimeError):
"""The wrapper cannot locate its configuration or output paths."""
def find_repository(start: Path | None = None) -> Path:
override = os.environ.get("BLACKSITE_WORKSPACE_ROOT")
configured = None
config_path = (start or Path.cwd()) / ".codex/config.toml"
if not override and config_path.is_file():
with config_path.open("rb") as handle:
configured = tomllib.load(handle).get("workspace_root")
candidates = [Path(override or configured)] if (override or configured) else [start or Path.cwd()]
if start is None and not override:
candidates.append(Path(__file__).parent)
visited: set[Path] = set()
for candidate in candidates:
candidate = candidate.expanduser().absolute()
for current in (candidate, *candidate.parents):
canonical = current.resolve(strict=False)
if canonical in visited:
continue
visited.add(canonical)
if (current / WORKFLOW_PATH).is_file():
return current
searched = ", ".join(str(path) for path in candidates)
raise SummaryError(f"could not locate {WORKFLOW_PATH} from {searched}")
def load_workflow(root: Path) -> dict[str, Any]:
path = root / WORKFLOW_PATH
try:
with path.open("rb") as handle:
workflow = tomllib.load(handle)
except OSError as error:
raise SummaryError(f"cannot read workflow configuration {path}: {error}") from error
except tomllib.TOMLDecodeError as error:
raise SummaryError(f"invalid workflow configuration {path}: {error}") from error
if workflow.get("version") != 1:
raise SummaryError(f"unsupported or missing workflow version in {path}")
return workflow
def output_settings(workflow: dict[str, Any]) -> tuple[str, int]:
output = workflow.get("output", {})
if not isinstance(output, dict):
raise SummaryError("[output] must be a TOML table")
log_dir = output.get("log_dir", ".codex/logs")
max_lines = output.get("max_failure_lines", 120)
if not isinstance(log_dir, str) or not log_dir:
raise SummaryError("output.log_dir must be a non-empty path string")
if not isinstance(max_lines, int) or not 1 <= max_lines <= 1000:
raise SummaryError("output.max_failure_lines must be an integer from 1 to 1000")
return log_dir, max_lines
def resolve_path(root: Path, raw: str) -> Path:
path = Path(os.path.expandvars(os.path.expanduser(raw)))
if not path.is_absolute():
path = root / path
return path.absolute()
def relative_display(root: Path, path: Path) -> str:
try:
return path.relative_to(root.resolve(strict=False)).as_posix()
except ValueError:
return str(path)
def safe_name(value: str) -> str:
cleaned = SAFE_NAME_RE.sub("-", value.strip()).strip("-._")
return cleaned[:80] or "command"
def default_log_path(root: Path, log_dir: str, gate: str) -> Path:
timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%fZ")
return resolve_path(root, str(Path(log_dir) / f"{timestamp}-{safe_name(gate)}.log"))
def strip_ansi(value: str) -> str:
return ANSI_RE.sub("", value).rstrip("\r\n")
def duration_text(seconds: float) -> str:
if seconds < 10:
return f"{seconds:.2f}s"
if seconds < 60:
return f"{seconds:.1f}s"
minutes, remainder = divmod(seconds, 60)
return f"{int(minutes)}m {remainder:.0f}s"
def is_actionable(line: str) -> bool:
plain = strip_ansi(line)
return any(pattern.search(plain) for pattern in ACTIONABLE_PATTERNS)
def failure_excerpt(path: Path, limit: int) -> tuple[list[str], str | None]:
"""Return bounded context around the first actionable failure.
The log is streamed rather than loaded wholesale, keeping the wrapper useful
for very large compiler output.
"""
before_count = min(12, max(0, limit // 4))
before: deque[str] = deque(maxlen=before_count)
excerpt: list[str] = []
first_actionable: str | None = None
matched = False
with path.open("r", encoding="utf-8", errors="replace") as handle:
for raw_line in handle:
line = strip_ansi(raw_line)
if not matched:
if is_actionable(line):
matched = True
first_actionable = line.strip() or None
excerpt.extend(before)
excerpt.append(line)
else:
before.append(line)
elif len(excerpt) < limit:
excerpt.append(line)
else:
break
if not matched:
# With no recognizable error, the command's tail is normally the most
# useful bounded evidence (signal termination, tool-specific errors).
tail: deque[str] = deque(maxlen=limit)
with path.open("r", encoding="utf-8", errors="replace") as handle:
for raw_line in handle:
tail.append(strip_ansi(raw_line))
excerpt = list(tail)
first_actionable = next((line.strip() for line in excerpt if line.strip()), None)
while excerpt and not excerpt[0].strip():
excerpt.pop(0)
while excerpt and not excerpt[-1].strip():
excerpt.pop()
return excerpt[:limit], first_actionable
def success_summary(path: Path) -> str:
last_nonempty = ""
test_result: tuple[str, str, str] | None = None
explicit_pass = ""
with path.open("r", encoding="utf-8", errors="replace") as handle:
for raw_line in handle:
line = strip_ansi(raw_line).strip()
if not line:
continue
last_nonempty = line
match = TEST_RESULT_RE.search(line)
if match:
test_result = match.groups()
if line.startswith("PASS "):
explicit_pass = line
if test_result is not None:
passed, failed, ignored = test_result
return f"{passed} passed, {failed} failed, {ignored} ignored"
if explicit_pass:
return explicit_pass[:240]
if last_nonempty.startswith("Finished "):
return last_nonempty[:240]
return "exit 0"
def write_result(path: Path, result: dict[str, Any]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
temporary: Path | None = None
try:
with tempfile.NamedTemporaryFile(
"w",
encoding="utf-8",
dir=path.parent,
prefix=f".{path.name}.",
suffix=".tmp",
delete=False,
) as handle:
json.dump(result, handle, indent=2, sort_keys=True)
handle.write("\n")
handle.flush()
os.fsync(handle.fileno())
temporary = Path(handle.name)
os.replace(temporary, path)
finally:
if temporary is not None and temporary.exists():
temporary.unlink()
def normalized_exit_code(returncode: int) -> int:
return 128 + abs(returncode) if returncode < 0 else returncode
def execute(
*,
root: Path,
workflow: dict[str, Any],
gate: str,
command: Sequence[str],
log: Path | None = None,
json_result: Path | None = None,
cwd: Path | None = None,
) -> int:
if not command:
raise SummaryError("a command is required after --")
configured_log_dir, max_lines = output_settings(workflow)
log_path = log or default_log_path(root, configured_log_dir, gate)
result_path = json_result or log_path.with_suffix(log_path.suffix + ".json")
if result_path == log_path:
raise SummaryError("the JSON result path must differ from the full log path")
command_cwd = cwd or Path.cwd()
if not command_cwd.is_dir():
raise SummaryError(f"command working directory does not exist: {command_cwd}")
log_path.parent.mkdir(parents=True, exist_ok=True)
started_wall = datetime.now(timezone.utc)
started = time.monotonic()
returncode = 127
launch_error: str | None = None
interrupted = False
with log_path.open("wb") as log_handle:
try:
process = subprocess.Popen(
list(command),
cwd=command_cwd,
stdout=log_handle,
stderr=subprocess.STDOUT,
shell=False,
)
except OSError as error:
launch_error = f"error: unable to execute {command[0]!r}: {error}"
log_handle.write((launch_error + "\n").encode("utf-8", errors="replace"))
else:
try:
returncode = normalized_exit_code(process.wait())
except KeyboardInterrupt:
interrupted = True
process.terminate()
try:
process.wait(timeout=5)
except subprocess.TimeoutExpired:
process.kill()
process.wait()
returncode = 130
log_handle.write(b"\nerror: command interrupted by user\n")
duration = time.monotonic() - started
status = "PASS" if returncode == 0 else "FAIL"
summary = success_summary(log_path) if returncode == 0 else "command failed"
excerpt: list[str] = []
actionable: str | None = launch_error
if returncode != 0:
excerpt, detected = failure_excerpt(log_path, max_lines)
actionable = actionable or detected
result = {
"schema_version": 1,
"gate": gate,
"status": status,
"exit_code": returncode,
"duration_seconds": round(duration, 6),
"log": relative_display(root, log_path),
"result": relative_display(root, result_path),
"command": list(command),
"command_display": shlex.join(command),
"cwd": str(command_cwd.resolve(strict=False)),
"started_at": started_wall.isoformat(timespec="seconds"),
"finished_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
"summary": summary,
"first_actionable_failure": actionable,
"interrupted": interrupted,
}
write_result(result_path, result)
if returncode == 0:
print(f"PASS {gate} — {duration_text(duration)} — {summary}")
else:
print(f"FAIL {gate} — {duration_text(duration)}")
for line in excerpt:
print(line)
print(f"Full log: {relative_display(root, log_path)}")
return returncode
def parse_arguments(argv: Sequence[str]) -> argparse.Namespace:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--gate", required=True, help="short verification gate name")
parser.add_argument("--json-result", help="machine-readable result path")
parser.add_argument("--log", help="complete combined-output log path")
parser.add_argument("--cwd", help="command working directory; defaults to the invocation directory")
parser.add_argument("command", nargs=argparse.REMAINDER)
args = parser.parse_args(argv)
if args.command and args.command[0] == "--":
args.command = args.command[1:]
if not args.command:
parser.error("a command is required after --")
return args
def self_test() -> int:
with tempfile.TemporaryDirectory(prefix="blacksite-summary-self-test-") as temporary:
root = Path(temporary)
(root / ".codex").mkdir()
(root / ".codex/workflow.toml").write_text(
"""version = 1
[output]
log_dir = ".codex/logs"
max_failure_lines = 4
""",
encoding="utf-8",
)
nested = root / "nested"
nested.mkdir()
found = find_repository(nested)
workflow = load_workflow(found)
parsed = parse_arguments(
[
"--gate",
"parser-fixture",
"--json-result",
".codex/logs/parser.json",
"--",
sys.executable,
"--version",
]
)
if parsed.command != [sys.executable, "--version"]:
raise AssertionError("command arguments after -- were not preserved")
success_log = root / ".codex/logs/success.log"
success_json = root / ".codex/logs/success.json"
captured = io.StringIO()
with contextlib.redirect_stdout(captured):
success = execute(
root=root,
workflow=workflow,
gate="self-test-pass",
command=[
sys.executable,
"-c",
"print('test result: ok. 3 passed; 0 failed; 1 ignored')",
],
log=success_log,
json_result=success_json,
cwd=root,
)
if success != 0:
raise AssertionError("successful fixture returned a failure")
if not captured.getvalue().startswith("PASS self-test-pass"):
raise AssertionError("successful fixture did not emit a compact PASS summary")
success_data = json.loads(success_json.read_text(encoding="utf-8"))
for key in ("status", "exit_code", "duration_seconds", "log"):
if key not in success_data:
raise AssertionError(f"result JSON omitted required key {key}")
if success_data["status"] != "PASS" or success_data["exit_code"] != 0:
raise AssertionError("successful result JSON is incorrect")
failure_log = root / ".codex/logs/failure.log"
failure_json = root / ".codex/logs/failure.json"
captured = io.StringIO()
with contextlib.redirect_stdout(captured):
failure = execute(
root=root,
workflow=workflow,
gate="self-test-fail",
command=[
sys.executable,
"-c",
"print('noise'); print('error[E0001]: actionable'); print('detail'); raise SystemExit(7)",
],
log=failure_log,
json_result=failure_json,
cwd=root,
)
if failure != 7:
raise AssertionError("failing fixture did not preserve exit code 7")
visible_lines = captured.getvalue().splitlines()
if not visible_lines or not visible_lines[0].startswith("FAIL self-test-fail"):
raise AssertionError("failing fixture did not emit a compact FAIL summary")
if len(visible_lines[1:-1]) > 4:
raise AssertionError("failure excerpt exceeded output.max_failure_lines")
failure_data = json.loads(failure_json.read_text(encoding="utf-8"))
if failure_data["status"] != "FAIL" or failure_data["exit_code"] != 7:
raise AssertionError("failure result JSON is incorrect")
if "error[E0001]" not in failure_log.read_text(encoding="utf-8"):
raise AssertionError("full failure output was not captured")
print("PASS summarize-command-self-test — logs, bounded failure, JSON, exit preservation")
return 0
def main(argv: Sequence[str] | None = None) -> int:
arguments = list(sys.argv[1:] if argv is None else argv)
if arguments in (["--self-test"], ["self-test"]):
try:
return self_test()
except (AssertionError, OSError, SummaryError, subprocess.SubprocessError, json.JSONDecodeError) as error:
print(f"FAIL summarize-command-self-test — {error}", file=sys.stderr)
return 1
try:
args = parse_arguments(arguments)
root = find_repository()
workflow = load_workflow(root)
log = resolve_path(root, args.log) if args.log else None
result = resolve_path(root, args.json_result) if args.json_result else None
cwd = resolve_path(root, args.cwd) if args.cwd else Path.cwd()
return execute(
root=root,
workflow=workflow,
gate=args.gate,
command=args.command,
log=log,
json_result=result,
cwd=cwd,
)
except (OSError, SummaryError) as error:
print(f"FAIL summarize-command — {error}", file=sys.stderr)
return 2
if __name__ == "__main__":
raise SystemExit(main())
+1167
View File
File diff suppressed because it is too large. Load diff