arkaos 2.42.0 → 2.44.0

package/VERSION

@@ -1 +1 @@
-2.42.0
+2.44.0

package/core/governance/leak_scanner.py

@@ -0,0 +1,155 @@
+"""Client-name leak scanner (PR22 v2.44.0).
+
+Reads the user-local ``~/.arkaos/redaction-clients.json`` and scans
+source files / arbitrary text for word-boundary matches. Wired into
+the release preflight gate as a blocking check.
+
+Closes a real process gap: PR20 v2.42.0 shipped 9 client names in a
+production constant; the Quality Gate did not flag it; operator
+caught it manually pre-commit. Automation > checklist.
+
+Empty / missing config is a no-op by design — there are no false
+positives in CI clones that lack the operator's local list.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+_DEFAULT_CONFIG_PATH = Path.home() / ".arkaos" / "redaction-clients.json"
+_MAX_FILE_BYTES = 10 * 1024 * 1024  # 10 MB per-file cap
+_SCAN_EXTENSIONS: frozenset[str] = frozenset({
+    ".py", ".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs",
+    ".json", ".yaml", ".yml", ".toml", ".md", ".sh", ".txt",
+})
+_EXCLUDE_DIRS: frozenset[str] = frozenset({
+    "node_modules", "__pycache__", ".venv", ".git", "dist", "build",
+})
+_LINE_EXCERPT_LIMIT = 200
+
+
+@dataclass(frozen=True)
+class LeakHit:
+    """One client-name occurrence in a scanned file."""
+    path: Path
+    line_number: int
+    line_excerpt: str
+    matched_token: str
+
+
+@dataclass(frozen=True)
+class ScanReport:
+    """Result of a scan."""
+    config_path: Path
+    pattern_count: int
+    files_scanned: int
+    hits: list[LeakHit]
+
+    @property
+    def clean(self) -> bool:
+        return not self.hits
+
+
+def scan_paths(
+    paths: Iterable[Path],
+    *,
+    config_path: Path | None = None,
+) -> ScanReport:
+    """Recursively scan the given paths for client-name leaks."""
+    cfg = config_path or _DEFAULT_CONFIG_PATH
+    patterns = _load_patterns(cfg)
+    if not patterns:
+        return ScanReport(config_path=cfg, pattern_count=0, files_scanned=0, hits=[])
+    regex = _build_regex(patterns)
+    hits: list[LeakHit] = []
+    files_scanned = 0
+    for path in paths:
+        for file_path in _iter_scannable_files(Path(path)):
+            files_scanned += 1
+            hits.extend(_scan_file(file_path, regex))
+    return ScanReport(
+        config_path=cfg,
+        pattern_count=len(patterns),
+        files_scanned=files_scanned,
+        hits=hits,
+    )
+
+
+def scan_text(
+    text: str,
+    *,
+    config_path: Path | None = None,
+) -> list[str]:
+    """Return the list of matched tokens (lowercased) found in *text*."""
+    cfg = config_path or _DEFAULT_CONFIG_PATH
+    patterns = _load_patterns(cfg)
+    if not patterns:
+        return []
+    regex = _build_regex(patterns)
+    return [m.group(1).lower() for m in regex.finditer(text)]
+
+
+def _load_patterns(config_path: Path) -> tuple[str, ...]:
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8"))
+        raw = data.get("clients", [])
+        return tuple(
+            str(c).strip().lower() for c in raw
+            if c and isinstance(c, str)
+        )
+    except (OSError, json.JSONDecodeError, AttributeError):
+        return ()
+
+
+def _build_regex(patterns: tuple[str, ...]) -> re.Pattern[str]:
+    escaped = [re.escape(p) for p in patterns]
+    return re.compile(
+        r"(?<![a-z0-9])(" + "|".join(escaped) + r")(?![a-z0-9])",
+        re.IGNORECASE,
+    )
+
+
+def _iter_scannable_files(root: Path):
+    if root.is_file():
+        if _is_scannable(root):
+            yield root
+        return
+    if not root.is_dir():
+        return
+    for entry in sorted(root.rglob("*")):
+        if any(part in _EXCLUDE_DIRS for part in entry.parts):
+            continue
+        if entry.is_file() and _is_scannable(entry):
+            yield entry
+
+
+def _is_scannable(path: Path) -> bool:
+    if path.suffix.lower() not in _SCAN_EXTENSIONS:
+        return False
+    try:
+        if path.stat().st_size > _MAX_FILE_BYTES:
+            return False
+    except OSError:
+        return False
+    return True
+
+
+def _scan_file(path: Path, regex: re.Pattern[str]) -> list[LeakHit]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    hits: list[LeakHit] = []
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        for match in regex.finditer(line):
+            hits.append(LeakHit(
+                path=path,
+                line_number=line_no,
+                line_excerpt=line[:_LINE_EXCERPT_LIMIT],
+                matched_token=match.group(1).lower(),
+            ))
+    return hits

package/core/release/__init__.py

@@ -0,0 +1 @@
+"""Release pipeline tooling — preflight gate, version helpers."""

package/core/release/preflight.py

@@ -0,0 +1,284 @@
+"""Release preflight gate (PR21 v2.43.0).
+
+Runs BEFORE the irreversible tag/push/publish steps of the release
+pipeline. Catches expired tokens, version misalignment, and dirty
+git state at minute 0 instead of minute 60.
+
+Closes a real-world debt: v2.40.0 release took ~1h because the npm
+token had expired silently and the failure was only discovered
+after merge, tag, GH release. A 2-second check up front would have
+turned that into an immediate STOP-and-rotate.
+
+All shell-outs use ``subprocess.run(check=False, capture_output=True,
+timeout=10)`` with argv as a list — no ``shell=True``, no string
+interpolation of user input.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_DEFAULT_REPO_ROOT = Path.cwd()
+_SUBPROCESS_TIMEOUT = 10
+_NPM_PACKAGE_VERSION_RE = re.compile(r'"version"\s*:\s*"([^"]+)"')
+_PYPROJECT_VERSION_RE = re.compile(r'^version\s*=\s*"([^"]+)"', re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Single preflight check outcome."""
+    name: str
+    passed: bool
+    reason: str
+    remediation: str | None = None
+    severity: str = "blocking"
+
+
+@dataclass(frozen=True)
+class PreflightReport:
+    """Aggregated preflight verdict."""
+    all_passed: bool
+    results: list[CheckResult] = field(default_factory=list)
+    blocking_failures: list[CheckResult] = field(default_factory=list)
+    warnings: list[CheckResult] = field(default_factory=list)
+
+
+def run_preflight(
+    *,
+    repo_root: Path | None = None,
+    expected_npm_user: str | None = None,
+) -> PreflightReport:
+    """Run every preflight check and return an aggregated report."""
+    root = repo_root or _DEFAULT_REPO_ROOT
+    results = [
+        check_version_alignment(repo_root=root),
+        check_npm_auth(expected_user=expected_npm_user),
+        check_npm_publish_capability(),
+        check_gh_auth(),
+        check_git_remote(),
+        check_git_clean(),
+        check_no_client_name_leaks(repo_root=root),
+    ]
+    return _aggregate(results)
+
+
+def check_no_client_name_leaks(
+    *, repo_root: Path | None = None,
+) -> CheckResult:
+    """Scan tracked source files for client identifiers (PR22 v2.44.0).
+
+    No-op when the operator's ~/.arkaos/redaction-clients.json is absent
+    or empty — no false positives in CI clones lacking the local config.
+    """
+    from core.governance.leak_scanner import scan_paths
+
+    root = repo_root or _DEFAULT_REPO_ROOT
+    paths = _collect_tracked_paths(root)
+    if paths is None:
+        return CheckResult(
+            name="no-client-name-leaks", passed=True,
+            reason="git ls-files unavailable — skipped",
+        )
+    report = scan_paths(paths)
+    return _format_leak_check_result(report)
+
+
+def _collect_tracked_paths(root: Path) -> list[Path] | None:
+    tracked = _run(["git", "-C", str(root), "ls-files", "--cached"])
+    if tracked is None or tracked.returncode != 0:
+        return None
+    return [root / line for line in tracked.stdout.splitlines() if line.strip()]
+
+
+def _format_leak_check_result(report) -> CheckResult:
+    if report.pattern_count == 0:
+        return CheckResult(
+            name="no-client-name-leaks", passed=True,
+            reason="no redaction config — scan skipped (no-op)",
+        )
+    if report.clean:
+        return CheckResult(
+            name="no-client-name-leaks", passed=True,
+            reason=f"{report.files_scanned} file(s) scanned, no leaks",
+        )
+    first = report.hits[0]
+    # PR22 v2.44.0 introduces this check at WARNING severity to ship the
+    # scanner without blocking on pre-existing leaks in test fixtures
+    # (test_dreaming.py and siblings) + historical CHANGELOG/ADR
+    # references. PR23 cleans those up and flips severity to "blocking".
+    return CheckResult(
+        name="no-client-name-leaks", passed=False, severity="warning",
+        reason=(
+            f"{len(report.hits)} leak(s) — first: "
+            f"{first.path.name}:{first.line_number} matched `{first.matched_token}`"
+        ),
+        remediation=(
+            "move the literal to ~/.arkaos/ or sanitize before commit; "
+            "PR22 scope intentionally warning-only — PR23 will scrub "
+            "historical leaks and flip this check to blocking"
+        ),
+    )
+
+
+def _load_repo_versions(
+    root: Path,
+) -> tuple[str | None, str | None, str | None] | None:
+    """Read VERSION, package.json, pyproject.toml. None if any unreadable."""
+    try:
+        v = (root / "VERSION").read_text(encoding="utf-8").strip()
+        pkg_match = _NPM_PACKAGE_VERSION_RE.search(
+            (root / "package.json").read_text(encoding="utf-8"),
+        )
+        py_match = _PYPROJECT_VERSION_RE.search(
+            (root / "pyproject.toml").read_text(encoding="utf-8"),
+        )
+    except (OSError, AttributeError):
+        return None
+    pkg_v = pkg_match.group(1) if pkg_match else None
+    py_v = py_match.group(1) if py_match else None
+    return v, pkg_v, py_v
+
+
+def check_version_alignment(*, repo_root: Path | None = None) -> CheckResult:
+    """Verify VERSION, package.json, pyproject.toml all carry the same version."""
+    root = repo_root or _DEFAULT_REPO_ROOT
+    versions = _load_repo_versions(root)
+    if versions is None:
+        return CheckResult(
+            name="version-alignment", passed=False,
+            reason="could not read one of VERSION / package.json / pyproject.toml",
+            remediation="ensure all three files exist at repo root",
+        )
+    v, pkg_v, py_v = versions
+    if v and pkg_v == v and py_v == v:
+        return CheckResult(
+            name="version-alignment", passed=True,
+            reason=f"all three at {v}",
+        )
+    return CheckResult(
+        name="version-alignment", passed=False,
+        reason=f"mismatch: VERSION={v} package.json={pkg_v} pyproject={py_v}",
+        remediation="align all three files to the same version, then re-run",
+    )
+
+
+def check_npm_auth(*, expected_user: str | None = None) -> CheckResult:
+    """Verify `npm whoami` returns a valid user (and matches expected, if set)."""
+    out = _run(["npm", "whoami"])
+    if out is None:
+        return CheckResult(
+            name="npm-auth", passed=False,
+            reason="npm command not found or timed out",
+            remediation="install Node.js / npm and retry",
+        )
+    if out.returncode != 0:
+        return CheckResult(
+            name="npm-auth", passed=False,
+            reason=f"npm whoami failed: {out.stderr.strip() or 'unknown'}",
+            remediation="run `npm login` or rotate token in ~/.npmrc",
+        )
+    user = out.stdout.strip()
+    if expected_user and user != expected_user:
+        return CheckResult(
+            name="npm-auth", passed=False,
+            reason=f"npm authenticated as {user}, expected {expected_user}",
+            remediation=f"switch token to {expected_user} or update expected user",
+        )
+    return CheckResult(
+        name="npm-auth", passed=True,
+        reason=f"authenticated as {user}",
+    )
+
+
+def check_npm_publish_capability() -> CheckResult:
+    """Verify `npm pack --dry-run` succeeds — proves write scope on the package."""
+    out = _run(["npm", "pack", "--dry-run"])
+    if out is None or out.returncode != 0:
+        msg = (out.stderr.strip() if out else "command unavailable") or "unknown"
+        return CheckResult(
+            name="npm-publish-capability", passed=False,
+            reason=f"pack dry-run failed: {msg}",
+            remediation="check granular token has 'read and write' on this package",
+        )
+    return CheckResult(
+        name="npm-publish-capability", passed=True,
+        reason="pack dry-run OK",
+    )
+
+
+def check_gh_auth() -> CheckResult:
+    """Verify `gh auth status` reports a logged-in session."""
+    out = _run(["gh", "auth", "status"])
+    if out is None:
+        return CheckResult(
+            name="gh-auth", passed=False,
+            reason="gh command not found or timed out",
+            remediation="install the GitHub CLI and run `gh auth login`",
+        )
+    if out.returncode != 0:
+        return CheckResult(
+            name="gh-auth", passed=False,
+            reason="gh not authenticated",
+            remediation="run `gh auth login`",
+        )
+    return CheckResult(name="gh-auth", passed=True, reason="authenticated")
+
+
+def check_git_remote() -> CheckResult:
+    """Verify `git remote get-url origin` returns a real remote URL."""
+    out = _run(["git", "remote", "get-url", "origin"])
+    if out is None or out.returncode != 0:
+        return CheckResult(
+            name="git-remote", passed=False,
+            reason="no `origin` remote configured",
+            remediation="set up the remote with `git remote add origin <url>`",
+        )
+    return CheckResult(
+        name="git-remote", passed=True,
+        reason=out.stdout.strip(),
+    )
+
+
+def check_git_clean() -> CheckResult:
+    """Flag uncommitted changes as a WARNING (not blocking)."""
+    out = _run(["git", "status", "--porcelain"])
+    if out is None:
+        return CheckResult(
+            name="git-clean", passed=False, severity="warning",
+            reason="git not available",
+        )
+    dirty = out.stdout.strip()
+    if not dirty:
+        return CheckResult(name="git-clean", passed=True, reason="working tree clean")
+    file_count = len([line for line in dirty.splitlines() if line.strip()])
+    return CheckResult(
+        name="git-clean", passed=False, severity="warning",
+        reason=f"{file_count} uncommitted file(s)",
+        remediation="commit, stash, or proceed deliberately",
+    )
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess | None:
+    """subprocess.run with our defaults; returns None on missing exe / timeout."""
+    try:
+        return subprocess.run(
+            cmd, capture_output=True, text=True,
+            timeout=_SUBPROCESS_TIMEOUT, check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+
+
+def _aggregate(results: list[CheckResult]) -> PreflightReport:
+    blocking = [r for r in results if not r.passed and r.severity == "blocking"]
+    warnings = [r for r in results if not r.passed and r.severity == "warning"]
+    return PreflightReport(
+        all_passed=not blocking,
+        results=results,
+        blocking_failures=blocking,
+        warnings=warnings,
+    )

package/core/release/preflight_cli.py

@@ -0,0 +1,74 @@
+"""CLI entry for the release preflight gate (PR21 v2.43.0).
+
+Usage:
+    python -m core.release.preflight_cli [--expected-npm-user USER]
+
+Exit code: 0 if all blocking checks pass, 1 otherwise. Warnings never
+gate the exit code. Output is markdown so it renders cleanly in both
+terminal and PR comments.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, timezone
+
+from core.release.preflight import (
+    CheckResult,
+    PreflightReport,
+    run_preflight,
+)
+
+
+def _glyph(result: CheckResult) -> str:
+    if result.passed:
+        return "PASS"
+    if result.severity == "warning":
+        return "WARN"
+    return "FAIL"
+
+
+def _render(report: PreflightReport) -> str:
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    lines = [
+        f"# Release Preflight — {today}",
+        "",
+        "| Check | Status | Notes |",
+        "|---|---|---|",
+    ]
+    for r in report.results:
+        notes = r.reason or ""
+        if r.remediation and not r.passed:
+            notes = f"{notes} | remediation: {r.remediation}"
+        lines.append(f"| {r.name} | {_glyph(r)} | {notes} |")
+    lines.append("")
+    if report.blocking_failures:
+        lines.append(f"**BLOCKED — {len(report.blocking_failures)} failure(s).** "
+                     "Fix each remediation and rerun before tagging/publishing.")
+    elif report.warnings:
+        lines.append(f"All blocking checks passed ({len(report.warnings)} "
+                     "warning(s) noted, non-blocking).")
+    else:
+        lines.append("All checks green. Safe to proceed to tag → release → publish.")
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="arkaos-preflight",
+        description="Run release preflight checks. Exit 1 on any blocking failure.",
+    )
+    parser.add_argument(
+        "--expected-npm-user", default=None,
+        help="Assert that `npm whoami` returns this user (e.g. wizardingcode).",
+    )
+    args = parser.parse_args(argv[1:])
+
+    report = run_preflight(expected_npm_user=args.expected_npm_user)
+    print(_render(report))
+    return 0 if report.all_passed else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.42.0",
+  "version": "2.44.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.42.0"
+version = "2.44.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}