context-guard-cli 2.1.0__py3-none-any.whl

context_guard/guard/errors.py

@@ -0,0 +1,71 @@
+"""Exit codes, typed exceptions, and command result type for guard middleware."""
+
+from collections import namedtuple
+
+# ---------------------------------------------------------------------------
+# Exit codes — machine-readable, consumidos por el harness
+# ---------------------------------------------------------------------------
+
+EXIT_OK = 0
+EXIT_GENERIC = 1             # corrupt manifest, missing session
+EXIT_LOCK_HELD = 2           # another agent holds the lock/claim — retry with backoff
+EXIT_LOCK_CONTENDED = 3      # lost the takeover race — retryable
+EXIT_VALIDATION = 4          # artifact missing / [PENDING] / too long / wrong language
+EXIT_BAD_TRANSITION = 5      # phase not authorized by the DAG — do NOT retry
+EXIT_APPROVAL_REQUIRED = 6   # human approval missing — only a human resolves it
+
+
+# ---------------------------------------------------------------------------
+# Command result — retornado por toda función de negocio
+# ---------------------------------------------------------------------------
+
+CommandResult = namedtuple("CommandResult", ["message", "exit_code"])
+
+
+# ---------------------------------------------------------------------------
+# Typed exceptions — para errores irrecuperables
+# ---------------------------------------------------------------------------
+
+class GuardError(Exception):
+    """Error base del middleware. Incluye exit_code para que cli.py traduzca."""
+    def __init__(self, message, exit_code=EXIT_GENERIC):
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+
+
+class ManifestCorruptError(GuardError):
+    """manifest.json existe pero no es JSON válido."""
+    def __init__(self, message):
+        super().__init__(f"FAIL|CORRUPT_MANIFEST|{message}", EXIT_GENERIC)
+
+
+class ValidationError(GuardError):
+    """Un artefacto no pasó validación (faltante, excede cap, etc.)."""
+    def __init__(self, failures):
+        msg = "\n".join(f"FAIL|{f}" for f in failures)
+        super().__init__(msg, EXIT_VALIDATION)
+
+
+class AmbiguousChangeError(GuardError):
+    """Varios changes activos y ninguno indicado explícitamente.
+
+    Never resolved by picking one: guessing here means the agent operates on a
+    change it did not choose while believing it did.
+    """
+    def __init__(self, message):
+        super().__init__(message, EXIT_VALIDATION)
+
+
+class LegacyLayoutError(GuardError):
+    """El contexto usa el layout plano de 1.x y necesita migración.
+
+    Reported rather than silently ignored: starting a fresh empty change on
+    top of a 1.x context makes the user's existing work look like it vanished.
+    """
+    def __init__(self, base):
+        super().__init__(
+            f"FAIL|LEGACY_LAYOUT|{base}|run `cg migrate` to convert it",
+            EXIT_GENERIC,
+        )
+

context_guard/guard/locking.py

@@ -0,0 +1,181 @@
+"""Locking primitives for guard middleware.
+
+Two independent lock levels:
+  - Session lock: OS-level lockfile (.lock) for cold-boot and archival
+  - Write lock: short-lived mutex (.write.lock) for serializing read-modify-write
+"""
+
+import os
+import time
+from datetime import datetime
+
+from .paths import get_paths, generate_agent_id
+from .manifest import load_manifest, save_manifest, create_initial_manifest
+from .errors import (
+    CommandResult,
+    EXIT_OK,
+    EXIT_LOCK_HELD,
+    EXIT_LOCK_CONTENDED,
+)
+
+
+# ---------------------------------------------------------------------------
+# Write lock — mutex de milisegundos para serializar read-modify-write
+# ---------------------------------------------------------------------------
+
+WRITE_LOCK_MAX_AGE = 30  # seconds before a write lock is considered stale
+WRITE_LOCK_HARD_CAP_FACTOR = 10  # age past which we stop trusting the PID
+
+
+def _is_write_lock_stale(lockfile):
+    """Detecta si un .write.lock es huérfano (proceso muerto o demasiado viejo).
+
+    Liveness is the primary signal. Age alone must NOT declare a lock stale:
+    the write lock serializes read-modify-write on the manifest, and tearing
+    it away from a process that is still running lets two writers race and
+    silently lose one of the writes.
+
+    The one exception is the hard cap. A PID can be reused by an unrelated
+    process, and trusting liveness forever would turn a recycled PID into a
+    permanent deadlock, so past WRITE_LOCK_HARD_CAP_FACTOR x WRITE_LOCK_MAX_AGE
+    we stop believing the PID belongs to the original owner.
+
+    Returns:
+        True si el lock es stale y puede ser removido de forma segura.
+    """
+    try:
+        with open(lockfile, "r") as f:
+            lines = f.readlines()
+
+        pid_alive = False
+        if len(lines) >= 1:
+            pid = int(lines[0].strip())
+            try:
+                os.kill(pid, 0)
+                pid_alive = True
+            except OSError:
+                return True  # proceso muerto, lock huérfano
+
+        if len(lines) >= 2:
+            created = float(lines[1].strip())
+            age = time.time() - created
+            if pid_alive:
+                return age > WRITE_LOCK_MAX_AGE * WRITE_LOCK_HARD_CAP_FACTOR
+            if age > WRITE_LOCK_MAX_AGE:
+                return True
+    except (ValueError, IOError):
+        return True  # no se puede leer, asumir stale
+    return False
+
+
+def with_write_lock(context, fn, timeout=5, retry_interval=0.05, change=None):
+    """Mutex de milisegundos para serializar read-modify-write.
+
+    Independiente del lock de negocio (que dura toda la sesión).
+    Escribe PID + timestamp en el lockfile para stale-detection.
+    Cada change tiene su propio write lock: dos changes son dos workstreams y
+    no deben serializarse entre sí.
+    """
+    p = get_paths(context, change)
+    lockfile = p["write_lock"]
+    os.makedirs(os.path.dirname(lockfile), exist_ok=True)
+    start = time.time()
+    while True:
+        try:
+            fd = os.open(lockfile, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            os.write(fd, f"{os.getpid()}\n{time.time()}\n".encode())
+            os.close(fd)
+            break
+        except FileExistsError:
+            if _is_write_lock_stale(lockfile):
+                try:
+                    os.remove(lockfile)
+                    continue
+                except FileNotFoundError:
+                    continue
+            if time.time() - start > timeout:
+                raise TimeoutError("write lock contention")
+            time.sleep(retry_interval)
+    try:
+        return fn()
+    finally:
+        try:
+            os.remove(lockfile)
+        except FileNotFoundError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Session lock — lockfile a nivel de SO
+# ---------------------------------------------------------------------------
+
+def try_create_lockfile(context, change=None):
+    """Atomic test-and-set at the OS level. Returns True if acquired."""
+    p = get_paths(context, change)
+    os.makedirs(os.path.dirname(p["lock"]), exist_ok=True)
+    try:
+        fd = os.open(p["lock"], os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        os.close(fd)
+        return True
+    except FileExistsError:
+        return False
+
+
+def acquire(context, ttl, change=None):
+    """Lógica compartida de claim/acquire: intenta tomar el lock, hace
+    stale-takeover si corresponde.
+
+    Returns:
+        CommandResult con message y exit_code.
+    """
+    p = get_paths(context, change)
+    os.makedirs(p["base"], exist_ok=True)
+    m = load_manifest(context, change)
+    if not m:
+        m = create_initial_manifest(context, p["change"])
+
+
+    if not try_create_lockfile(context, change):
+        existing = m.get("lock", {})
+        acquired_at = existing.get("acquired_at")
+        ttl_existing = existing.get("ttl_seconds", ttl)
+        stale = False
+        if acquired_at:
+            elapsed = (datetime.now() - datetime.fromisoformat(acquired_at)).total_seconds()
+            stale = elapsed > ttl_existing
+        else:
+            # Orphan lockfile: a peer died between creating .lock and recording
+            # its metadata. Without a fallback the staleness check silently
+            # evaluates to False and the session deadlocks forever, so age the
+            # lock by the file's own mtime instead.
+            try:
+                elapsed = time.time() - os.path.getmtime(p["lock"])
+                stale = elapsed > ttl_existing
+            except OSError:
+                # Lockfile vanished between the failed create and this stat —
+                # another agent released it; fall through and retry the create.
+                stale = True
+
+        if not stale:
+            return CommandResult(
+                f"FAIL|LOCK_HELD|{existing.get('acquired_by')}",
+                EXIT_LOCK_HELD,
+            )
+
+        try:
+            os.remove(p["lock"])
+        except FileNotFoundError:
+            # Another agent released or took over the lock first; the create
+            # below is what decides who actually wins.
+            pass
+        if not try_create_lockfile(context, change):
+            return CommandResult("FAIL|LOCK_CONTENDED", EXIT_LOCK_CONTENDED)
+
+    m["lock"] = {
+        "held": True,
+        "acquired_at": datetime.now().isoformat(),
+        "acquired_by": generate_agent_id(),
+        "ttl_seconds": ttl,
+    }
+    save_manifest(context, m, change)
+    return CommandResult("SUCCESS|LOCK_ACQUIRED", EXIT_OK)

context_guard/guard/manifest.py

@@ -0,0 +1,69 @@
+"""Manifest I/O with atomic writes for guard middleware."""
+
+import json
+import os
+
+from .paths import get_paths
+from .errors import ManifestCorruptError
+
+
+DEFAULT_PIPELINE = ["PLAN", "EXECUTE", "VERIFY"]
+
+# Bumped for the multi-change layout: manifests now live per change under
+# .context-guard/changes/{name}/ and carry the change name.
+SCHEMA_VERSION = 3
+
+
+def create_initial_manifest(context, change=None):
+    """Crea una estructura de manifest inicial con el pipeline de 3 estados."""
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "context_name": context,
+        "change_name": change,
+        "current_phase": "PLAN",
+        "lock_phase": "PLAN",
+        "completed_phases": [],
+        "pending_phases": list(DEFAULT_PIPELINE),
+        "lock": {},
+        "transaction": {
+            "txn_status": "idle",
+            "txn_phase": "None",
+            "txn_started_at": None,
+        },
+        "reference_docs": [],
+        "files_in_scope": [],
+        "task_claims": {},
+    }
+
+
+def load_manifest(context, change=None):
+    """Carga el manifest del change dado.
+
+    Returns:
+        dict or None: El manifest parseado, o None si no existe.
+
+    Raises:
+        ManifestCorruptError: Si el archivo existe pero no es JSON válido.
+    """
+    p = get_paths(context, change)
+    if not os.path.exists(p["manifest"]):
+        return None
+    try:
+        with open(p["manifest"], "r") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, ValueError) as e:
+        raise ManifestCorruptError(str(e))
+
+
+def save_manifest(context, data, change=None):
+    """Escribe el manifest con write atómico (tmp + rename).
+
+    Crea los directorios necesarios si no existen.
+    """
+    p = get_paths(context, change)
+    os.makedirs(os.path.dirname(p["manifest"]), exist_ok=True)
+    tmp_path = p["manifest"] + ".tmp"
+    with open(tmp_path, "w") as f:
+        json.dump(data, f, indent=2)
+    os.rename(tmp_path, p["manifest"])
+

context_guard/guard/migrate.py

@@ -0,0 +1,288 @@
+"""Migration from the two legacy layouts into the multi-change layout.
+
+Two sources are supported:
+
+  - state-guard's `.state-guard/changes/{name}/state.ini` (schema v2, INI)
+  - context-guard 1.x's flat `.context-guard/manifest.json`
+
+Both are *copied*, never moved: if a migration produces something wrong the
+user still has the original to go back to. Migration is idempotent, and it
+refuses to overwrite a change that already exists — the one thing worse than
+not migrating is migrating over live work.
+"""
+
+import configparser
+import os
+import shutil
+
+from .manifest import (
+    DEFAULT_PIPELINE,
+    SCHEMA_VERSION,
+    create_initial_manifest,
+    load_manifest,
+    save_manifest,
+)
+from .paths import (
+    DEFAULT_CHANGE,
+    get_archive_dir,
+    get_base,
+    get_changes_dir,
+    get_paths,
+    get_root,
+    list_changes,
+)
+from .errors import CommandResult, EXIT_OK, EXIT_VALIDATION
+
+STATE_GUARD_DIRNAME = ".state-guard"
+
+# state-guard writes phases in lowercase; this pipeline is uppercase. A missed
+# conversion leaves lock_phase="execute", which matches no valid phase and
+# locks the change out of every transition.
+_NO_PHASE = {"", "none", "None"}
+
+# Artifacts that must exist for the normal gates to work. A migrated change
+# genuinely lacks some of them, and saying so with [PENDING] routes it through
+# the usual validation instead of pretending it is complete.
+_REQUIRED_ARTIFACTS = {
+    "objective.md": "[PENDING] Define objective here",
+    "snapshot.md": "[PENDING] Define snapshot here",
+    "tasks.md": "[PENDING] Define tasks here",
+    "review-report.md": "[PENDING] Write static review here",
+    "verify-report.md": "[PENDING] Write dynamic verification here",
+}
+
+
+def _normalise_phase(value, default="PLAN"):
+    if value is None:
+        return default
+    value = value.strip()
+    if value in _NO_PHASE:
+        return default
+    return value.upper()
+
+
+def _normalise_phase_list(value):
+    if not value:
+        return []
+    out = []
+    for item in value.split(","):
+        item = item.strip()
+        if item and item not in _NO_PHASE:
+            out.append(item.upper())
+    return out
+
+
+def _split_recognised_phases(phases):
+    """Separate phases this pipeline knows about from ones it does not.
+
+    state-guard tracked pseudo-phases (a 'hotfix' bypass state, in the audit
+    that found this) that are not PLAN/EXECUTE/VERIFY. Carrying one straight
+    into completed_phases plants a value no future DAG invariant check would
+    expect. Silently dropping it would be just as wrong — it is real history
+    the user might want back — so the unrecognised ones go to legacy_phases
+    instead of vanishing.
+    """
+    recognised = [p for p in phases if p in DEFAULT_PIPELINE]
+    unrecognised = [p for p in phases if p not in DEFAULT_PIPELINE]
+    return recognised, unrecognised
+
+
+def _state_guard_changes_dir(context):
+    return os.path.join(get_root(context), STATE_GUARD_DIRNAME, "changes")
+
+
+def _find_state_guard_changes(context):
+    """Names of state-guard changes that carry a state.ini."""
+    root = _state_guard_changes_dir(context)
+    if not os.path.isdir(root):
+        return []
+    names = []
+    for entry in sorted(os.listdir(root)):
+        if entry == "archive":
+            continue
+        if os.path.exists(os.path.join(root, entry, "state.ini")):
+            names.append(entry)
+    return names
+
+
+def _manifest_from_state_ini(context, change, ini_path):
+    """Translate a state-guard state.ini (schema v2) into a manifest v3."""
+    config = configparser.ConfigParser()
+    config.read(ini_path, encoding="utf-8")
+
+    manifest = create_initial_manifest(context, change)
+
+    current = _normalise_phase(config.get("Graph", "current_phase", fallback=None))
+    lock_phase = _normalise_phase(config.get("Graph", "lock_phase", fallback=None))
+    completed_raw = _normalise_phase_list(
+        config.get("Graph", "completed_phases", fallback=""))
+    completed, legacy_phases = _split_recognised_phases(completed_raw)
+    pending = _normalise_phase_list(
+        config.get("Graph", "pending_phases", fallback=""))
+
+    manifest["current_phase"] = current
+    manifest["lock_phase"] = lock_phase
+    manifest["completed_phases"] = completed
+    manifest["pending_phases"] = pending or [
+        p for p in DEFAULT_PIPELINE if p not in completed
+    ]
+    if legacy_phases:
+        manifest["legacy_phases"] = legacy_phases
+
+    summary = config.get("Session", "session_summary", fallback="").strip()
+    if summary:
+        manifest.setdefault("session", {})["session_summary"] = summary
+
+    # A recorded human approval is preserved. Discarding it would make the user
+    # re-approve work they already signed off on. Read only — the approval flow
+    # itself is not wired up here.
+    if config.has_section("Gate"):
+        approved_at = config.get("Gate", "plan_approved_at", fallback="").strip()
+        approved_by = config.get("Gate", "plan_approved_by", fallback="").strip()
+        if approved_at or approved_by:
+            approval = {"by": approved_by or "unknown", "at": approved_at or None}
+            reason = config.get("Gate", "hotfix_bypass_reason", fallback="").strip()
+            if reason:
+                approval["hotfix"] = True
+                approval["reason"] = reason
+            manifest["approval"] = approval
+
+    manifest["migrated_from"] = "state-guard/state.ini"
+    return manifest
+
+
+def _copy_artifacts(src_dir, dest_dir, skip=()):
+    """Copy every regular file from a legacy change directory."""
+    os.makedirs(dest_dir, exist_ok=True)
+    for entry in sorted(os.listdir(src_dir)):
+        if entry in skip:
+            continue
+        src = os.path.join(src_dir, entry)
+        if not os.path.isfile(src):
+            continue
+        shutil.copy2(src, os.path.join(dest_dir, entry))
+
+
+def _scaffold_missing_artifacts(dest_dir):
+    for name, placeholder in _REQUIRED_ARTIFACTS.items():
+        path = os.path.join(dest_dir, name)
+        if not os.path.exists(path):
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(placeholder)
+
+
+def _migrate_state_guard(context, findings):
+    """Copy every state-guard change into changes/{name}/."""
+    src_root = _state_guard_changes_dir(context)
+    for name in _find_state_guard_changes(context):
+        src_dir = os.path.join(src_root, name)
+        p = get_paths(context, name)
+
+        # Idempotence and safety are the same rule here: an existing change may
+        # already carry work done after a previous migration.
+        if os.path.exists(p["manifest"]):
+            findings.append(f"SKIP|{name}|already migrated")
+            continue
+
+        os.makedirs(p["base"], exist_ok=True)
+        _copy_artifacts(src_dir, p["base"], skip=("state.ini",))
+        _scaffold_missing_artifacts(p["base"])
+        manifest = _manifest_from_state_ini(
+            context, name, os.path.join(src_dir, "state.ini"))
+        save_manifest(context, manifest, name)
+        findings.append(f"MIGRATED|{name}|from state-guard")
+
+
+def _migrate_flat_layout(context, findings):
+    """Move a context-guard 1.x flat layout into changes/default/."""
+    base = get_base(context)
+    flat_manifest = os.path.join(base, "manifest.json")
+    if not os.path.exists(flat_manifest):
+        return None
+
+    dest = get_paths(context, DEFAULT_CHANGE)
+    if os.path.exists(dest["manifest"]):
+        # The flat data and a live `default` change cannot both be right, and
+        # picking one silently would destroy the other.
+        return CommandResult(
+            f"FAIL|MIGRATE_CONFLICT|{DEFAULT_CHANGE}|"
+            "a flat 1.x manifest and an existing change both claim this name",
+            EXIT_VALIDATION,
+        )
+
+    with open(flat_manifest, "r", encoding="utf-8") as f:
+        import json
+        manifest = json.load(f)
+
+    manifest["schema_version"] = SCHEMA_VERSION
+    manifest["change_name"] = DEFAULT_CHANGE
+    manifest["migrated_from"] = "context-guard/1.x-flat"
+
+    os.makedirs(dest["base"], exist_ok=True)
+    for entry in sorted(os.listdir(base)):
+        if entry in ("manifest.json", "changes", "archive"):
+            continue
+        src = os.path.join(base, entry)
+        if os.path.isfile(src):
+            shutil.copy2(src, os.path.join(dest["base"], entry))
+
+    _scaffold_missing_artifacts(dest["base"])
+    save_manifest(context, manifest, DEFAULT_CHANGE)
+
+    # The flat manifest has to go, or is_legacy_flat_layout keeps firing and
+    # the context stays permanently "unmigrated".
+    os.remove(flat_manifest)
+    findings.append(f"MIGRATED|{DEFAULT_CHANGE}|from context-guard 1.x flat layout")
+    return None
+
+
+def _migrate_flat_archive(context, findings):
+    """Copy a 1.x flat layout's own archive/ subdirectories into
+    changes/archive/.
+
+    _migrate_flat_layout only ever copied files (`if os.path.isfile(src)`),
+    so a 1.x archive/ full of completed changes was silently left behind,
+    orphaned next to the new (empty) changes/archive/ — two archive
+    directories where the old one nothing pointed at anymore. Runs
+    independently of whether a flat manifest.json still exists, since the
+    archive can outlive it (e.g. the main manifest was already migrated by
+    an older `cg migrate` before this fix shipped).
+
+    Copies, not moves, like every other path in this module: if this
+    produces something wrong the original archive is still there.
+    """
+    old_archive = os.path.join(get_base(context), "archive")
+    if not os.path.isdir(old_archive):
+        return
+
+    new_archive = get_archive_dir(context)
+    for entry in sorted(os.listdir(old_archive)):
+        src = os.path.join(old_archive, entry)
+        if not os.path.isdir(src):
+            continue
+        dest = os.path.join(new_archive, entry)
+        if os.path.exists(dest):
+            findings.append(f"SKIP|archive/{entry}|already migrated")
+            continue
+        os.makedirs(new_archive, exist_ok=True)
+        shutil.copytree(src, dest)
+        findings.append(f"MIGRATED|archive/{entry}|from context-guard 1.x flat archive")
+
+
+def cmd_migrate(context):
+    """Convierte los layouts legacy al layout multi-change.
+
+    Idempotent: changes that already exist are skipped, not overwritten.
+    """
+    findings = []
+
+    conflict = _migrate_flat_layout(context, findings)
+    if conflict is not None:
+        return conflict
+
+    _migrate_flat_archive(context, findings)
+    _migrate_state_guard(context, findings)
+
+    if not findings:
+        return CommandResult("SUCCESS|NOTHING_TO_MIGRATE", EXIT_OK)
+    return CommandResult("\n".join(findings), EXIT_OK)