pacodexion 0.1.0__tar.gz

pacodexion-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tristan-gscn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pacodexion-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: pacodexion
+Version: 0.1.0
+Summary: Runner and validator for Codexion project test cases.
+Author: pacodexion
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pacodexion
+
+Installable CLI package that runs Codexion test scenarios against `./codexion` and validates output consistency.

pacodexion-0.1.0/README.md

@@ -0,0 +1,3 @@
+# pacodexion
+
+Installable CLI package that runs Codexion test scenarios against `./codexion` and validates output consistency.

pacodexion-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pacodexion"
+version = "0.1.0"
+description = "Runner and validator for Codexion project test cases."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "pacodexion" }]
+dependencies = []
+
+[project.scripts]
+pacodexion = "pacodexion.__main__:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

pacodexion-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pacodexion-0.1.0/src/pacodexion/CaseRegistry.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Dict, List, Sequence, Tuple
+
+from .TestCase import TestCase
+
+
+class CaseRegistry:
+    def __init__(self) -> None:
+        self._cases = self._build_cases()
+
+    def _build_cases(self) -> Dict[str, TestCase]:
+        cases = [
+            TestCase("1", "basic_fifo", ("4", "800", "200", "200", "200", "5", "10", "fifo")),
+            TestCase("2", "basic_edf", ("4", "800", "200", "200", "200", "5", "10", "edf")),
+            TestCase("3", "success_fifo", ("10", "10000", "100", "100", "100", "5", "50", "fifo")),
+            TestCase("4", "large_edf", ("20", "5000", "500", "500", "500", "10", "100", "edf")),
+            TestCase("5", "low_cooldown", ("5", "2000", "100", "100", "100", "20", "1", "fifo")),
+            TestCase("6", "long_actions", ("3", "10000", "2000", "2000", "2000", "2", "100", "fifo")),
+            TestCase("big", "big_test", ("100", "10000", "66", "24", "87", "10", "10", "fifo")),
+            TestCase("starvation", "starvation_case", ("3", "1000", "600", "10", "10", "5", "100", "fifo")),
+            TestCase("starvation2", "starvation_case", ("3", "1000", "600", "10", "10", "5", "100", "edf")),
+            TestCase("one_compiler_fifo", "one_compiler_fifo", ("1", "1000", "200", "200", "200", "5", "50", "fifo")),
+            TestCase("one_compiler_edf", "one_compiler_edf", ("1", "1000", "200", "200", "200", "5", "50", "edf")),
+            TestCase("zero_compile", "zero_compiles", ("5", "1000", "200", "200", "200", "0", "10", "fifo")),
+            TestCase("immediate_burnout", "immediate_burnout", ("2", "1", "200", "200", "200", "5", "10", "fifo")),
+            TestCase("cooldown_hell", "cooldown_hell", ("2", "1000", "100", "100", "100", "5", "2000", "fifo")),
+            TestCase("max_coders", "max_coders", ("300", "10000", "100", "100", "100", "5", "10", "edf")),
+            TestCase("toomany_compiler", "toomany_compiler", ("999", "1000", "200", "200", "200", "5", "50", "fifo")),
+            TestCase("error_arg1", "error_coder", ("banana", "200", "300", "400", "500", "5", "10", "fifo"), True),
+            TestCase("error_arg2", "error_coder", ("10", "banana", "300", "400", "500", "5", "10", "fifo"), True),
+            TestCase("error_arg3", "error_coder", ("10", "200", "banana", "400", "500", "5", "10", "fifo"), True),
+            TestCase("error_arg4", "error_coder", ("10", "200", "300", "banana", "500", "5", "10", "fifo"), True),
+            TestCase("error_arg5", "error_coder", ("10", "200", "300", "400", "banana", "5", "10", "fifo"), True),
+            TestCase("error_arg6", "error_coder", ("10", "200", "300", "400", "500", "banana", "10", "fifo"), True),
+            TestCase("error_arg7", "error_coder", ("10", "200", "300", "400", "500", "5", "banana", "fifo"), True),
+            TestCase("error_arg8", "error_coder", ("10", "200", "300", "400", "500", "5", "10", "banana"), True),
+            TestCase("error_arg9", "error_coder", ("10", "200", "300", "-400", "500", "5", "10", "edf"), True),
+            TestCase("error_arg10", "error_coder", ("too", "10", "200", "300", "400", "500", "5", "10", "edf"), True),
+            TestCase("error_missing_args", "error_missing_args", ("10", "200", "300", "400", "500", "5", "10"), True),
+            TestCase("error_no_args", "error_no_args", (), True),
+        ]
+        return {case.key: case for case in cases}
+
+    def select_cases(self, tokens: Sequence[str]) -> Tuple[List[TestCase], List[str]]:
+        if not tokens:
+            return list(self._cases.values()), []
+        selected: List[TestCase] = []
+        unknown: List[str] = []
+        for token in tokens:
+            case = self._cases.get(token)
+            if case is None:
+                unknown.append(token)
+            else:
+                selected.append(case)
+        return selected, unknown

pacodexion-0.1.0/src/pacodexion/CaseRunner.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import subprocess
+import time
+from typing import Callable, List, Optional, Tuple
+
+from .OutputValidator import OutputValidator
+from .TestCase import TestCase
+
+CaseResult = Tuple[TestCase, bool, str]
+
+
+class CaseRunner:
+    def __init__(self) -> None:
+        self.validator = OutputValidator()
+        self.last_stdout = ""
+        self.last_stderr = ""
+
+    def run_all(self, binary: str, cases: List[TestCase], timeout: float) -> Tuple[List[CaseResult], bool]:
+        results: List[CaseResult] = []
+        any_fail = False
+        for case in cases:
+            ok, detail = self.run_case(binary, case, timeout)
+            results.append((case, ok, detail))
+            if not ok:
+                any_fail = True
+        return results, any_fail
+
+    def run_case(self, binary: str, case: TestCase, timeout: float) -> Tuple[bool, str]:
+        return self.run_case_with_progress(binary, case, timeout)
+
+    def run_case_with_progress(
+        self,
+        binary: str,
+        case: TestCase,
+        timeout: float,
+        on_tick: Optional[Callable[[float], None]] = None,
+    ) -> Tuple[bool, str]:
+        try:
+            process = subprocess.Popen(
+                [binary, *case.args],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+        except OSError as exc:
+            self.last_stdout = ""
+            self.last_stderr = str(exc)
+            return False, f"execution error: {exc}"
+
+        started = time.monotonic()
+        stdout_data = ""
+        stderr_data = ""
+        while True:
+            try:
+                stdout_data, stderr_data = process.communicate(timeout=0.1)
+                break
+            except subprocess.TimeoutExpired:
+                elapsed = time.monotonic() - started
+                if on_tick is not None:
+                    on_tick(elapsed)
+                if elapsed >= timeout:
+                    process.kill()
+                    stdout_data, stderr_data = process.communicate()
+                    self.last_stdout = stdout_data
+                    self.last_stderr = stderr_data
+                    return (
+                        False,
+                        f"timeout after {timeout:.1f}s\n"
+                        f"partial_stdout={self._preview(stdout_data or '<empty>')}\n"
+                        f"partial_stderr={self._preview(stderr_data or '<empty>')}",
+                    )
+
+        self.last_stdout = stdout_data
+        self.last_stderr = stderr_data
+
+        completed = subprocess.CompletedProcess(
+            args=[binary, *case.args],
+            returncode=process.returncode or 0,
+            stdout=stdout_data,
+            stderr=stderr_data,
+        )
+
+        if case.expect_invalid_args:
+            return self.validator.validate_error_case(completed)
+        return self.validator.validate_regular_case(completed, case.args)
+
+    def get_last_output(self) -> str:
+        if self.last_stdout.strip():
+            return self.last_stdout
+        return self.last_stderr
+
+    def _preview(self, text: str, max_len: int = 240) -> str:
+        cleaned = text.replace("\n", "\\n")
+        if len(cleaned) <= max_len:
+            return cleaned
+        return f"{cleaned[:max_len]}...(truncated)"

pacodexion-0.1.0/src/pacodexion/KoTraceWriter.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .TestCase import TestCase
+
+
+class KoTraceWriter:
+    def __init__(self, trace_dir: str = "traces") -> None:
+        self.trace_path = Path(trace_dir)
+
+    def write(self, case: TestCase, codexion_output: str, detail: str) -> Path:
+        self.trace_path.mkdir(parents=True, exist_ok=True)
+        file_path = self.trace_path / self._file_name(case)
+        content = self._build_content(codexion_output, detail)
+        file_path.write_text(content, encoding="utf-8")
+        return file_path
+
+    def _file_name(self, case: TestCase) -> str:
+        safe_name = "".join(ch if ch.isalnum() or ch in ("-", "_") else "_" for ch in case.name)
+        return f"{case.key}_{safe_name}.log"
+
+    def _build_content(self, codexion_output: str, detail: str) -> str:
+        lines = codexion_output.splitlines()
+        if not lines:
+            return "PROBLEM HERE >>>\n"
+
+        line_no = self._extract_field(detail, "line")
+        idx = 0
+        if line_no is not None and line_no.isdigit():
+            candidate = int(line_no) - 1
+            if 0 <= candidate < len(lines):
+                idx = candidate
+        lines[idx] = f"PROBLEM HERE >>> {lines[idx]}"
+        return "\n".join(lines) + "\n"
+
+    def _extract_field(self, detail: str, key: str) -> str | None:
+        prefix = f"{key}="
+        for line in detail.splitlines():
+            if line.startswith(prefix):
+                return line[len(prefix) :]
+        return None

pacodexion-0.1.0/src/pacodexion/OutputValidator.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import re
+import subprocess
+from typing import Dict, List, Optional, Tuple
+
+
+class OutputValidator:
+    LOG_RE = re.compile(
+        r"^(?P<ts>\d+)\s+(?P<coder>\d+)\s+"
+        r"(?P<state>has taken a dongle|is compiling|is debugging|is refactoring|burned out)$"
+    )
+
+    def read_lines(self, output: str) -> List[str]:
+        return [line.strip() for line in output.splitlines() if line.strip()]
+
+    def validate_error_case(self, completed: subprocess.CompletedProcess[str]) -> Tuple[bool, str]:
+        merged = (completed.stdout or "") + "\n" + (completed.stderr or "")
+        lines = self.read_lines(merged)
+        has_error_word = any(
+            ("error" in line.lower()) or ("invalid" in line.lower()) or ("usage" in line.lower())
+            for line in lines
+        )
+        if completed.returncode != 0 or has_error_word:
+            return True, "invalid argument rejection detected"
+        return (
+            False,
+            "expected invalid-argument rejection but command looked successful\n"
+            f"return_code={completed.returncode}\n"
+            f"stdout={self._preview(completed.stdout or '<empty>')}\n"
+            f"stderr={self._preview(completed.stderr or '<empty>')}",
+        )
+
+    def validate_regular_case(self, completed: subprocess.CompletedProcess[str], raw_args: Tuple[str, ...]) -> Tuple[bool, str]:
+        parsed_args, parse_error = self._parse_regular_args(raw_args)
+        if parse_error is not None or parsed_args is None:
+            return False, parse_error or "invalid test case definition"
+
+        (
+            n_coders,
+            time_to_burnout,
+            time_to_compile,
+            time_to_debug,
+            time_to_refactor,
+            compiles_required,
+            _dongle_cooldown,
+            _scheduler,
+        ) = parsed_args
+
+        if completed.returncode != 0:
+            return (
+                False,
+                "unexpected non-zero exit code\n"
+                f"return_code={completed.returncode}\n"
+                f"stdout={self._preview(completed.stdout or '<empty>')}\n"
+                f"stderr={self._preview(completed.stderr or '<empty>')}",
+            )
+
+        lines = self.read_lines(completed.stdout or "")
+        if not lines:
+            if compiles_required == 0:
+                return True, "no log line emitted (accepted for required_compiles=0)"
+            return False, "empty output while compiles are required"
+
+        last_ts = -1
+        burnouts = 0
+        burnout_coder: Optional[int] = None
+        taken_counts = self._build_counter(n_coders)
+        compile_counts = self._build_counter(n_coders)
+        last_compile_start = {coder_id: 0 for coder_id in range(1, n_coders + 1)}
+        last_debug_start: Dict[int, Optional[int]] = {coder_id: None for coder_id in range(1, n_coders + 1)}
+        last_refactor_start: Dict[int, Optional[int]] = {coder_id: None for coder_id in range(1, n_coders + 1)}
+        last_state: Dict[int, str] = {coder_id: "init" for coder_id in range(1, n_coders + 1)}
+
+        for idx, line in enumerate(lines, start=1):
+            match = self.LOG_RE.match(line)
+            if not match:
+                return (
+                    False,
+                    "invalid log format\n"
+                    f"line={idx}\n"
+                    f"value={self._preview(line)}\n"
+                    "expected_format='<timestamp_ms> <coder_id> <state>'\n"
+                    "allowed_states=['has taken a dongle', 'is compiling', "
+                    "'is debugging', 'is refactoring', 'burned out']",
+                )
+
+            ts = int(match.group("ts"))
+            coder = int(match.group("coder"))
+            state = match.group("state")
+
+            if ts < last_ts:
+                return (
+                    False,
+                    "non-monotonic timestamps\n"
+                    f"line={idx}\n"
+                    f"previous_timestamp={last_ts}\n"
+                    f"current_timestamp={ts}\n"
+                    f"line_value={self._preview(line)}",
+                )
+            last_ts = ts
+
+            if coder < 1 or coder > n_coders:
+                return (
+                    False,
+                    "coder id out of expected range\n"
+                    f"line={idx}\n"
+                    f"coder_id={coder}\n"
+                    f"expected_range=1..{n_coders}\n"
+                    f"line_value={self._preview(line)}",
+                )
+
+            if self._transition_invalid(last_state[coder], state, taken_counts[coder]):
+                return (
+                    False,
+                    "invalid state transition sequence\n"
+                    f"line={idx}\n"
+                    f"coder_id={coder}\n"
+                    f"previous_state={last_state[coder]}\n"
+                    f"current_state={state}\n"
+                    f"line_value={self._preview(line)}",
+                )
+
+            if state == "has taken a dongle":
+                taken_counts[coder] += 1
+                if taken_counts[coder] > 2:
+                    return (
+                        False,
+                        "more than 2 dongles taken before compile\n"
+                        f"line={idx}\n"
+                        f"coder_id={coder}\n"
+                        f"dongles_seen_before_compile={taken_counts[coder]}\n"
+                        f"line_value={self._preview(line)}",
+                    )
+                if last_refactor_start[coder] is not None:
+                    waited = ts - last_refactor_start[coder]
+                    if waited < time_to_refactor:
+                        return (
+                            False,
+                            "refactor phase ended too early before taking dongles\n"
+                            f"line={idx}\n"
+                            f"coder_id={coder}\n"
+                            f"expected_min_refactor_ms={time_to_refactor}\n"
+                            f"actual_refactor_ms={waited}\n"
+                            f"line_value={self._preview(line)}",
+                        )
+            elif state == "is compiling":
+                if taken_counts[coder] < 2:
+                    return (
+                        False,
+                        "compile started without 2 prior dongle acquisitions\n"
+                        f"line={idx}\n"
+                        f"coder_id={coder}\n"
+                        f"dongles_seen_before_compile={taken_counts[coder]}\n"
+                        f"line_value={self._preview(line)}",
+                    )
+                taken_counts[coder] = 0
+                compile_counts[coder] += 1
+                last_compile_start[coder] = ts
+                last_debug_start[coder] = None
+                last_refactor_start[coder] = None
+            elif state == "is debugging":
+                elapsed_compile = ts - last_compile_start[coder]
+                if elapsed_compile < time_to_compile:
+                    return (
+                        False,
+                        "compile phase ended too early before debugging\n"
+                        f"line={idx}\n"
+                        f"coder_id={coder}\n"
+                        f"expected_min_compile_ms={time_to_compile}\n"
+                        f"actual_compile_ms={elapsed_compile}\n"
+                        f"line_value={self._preview(line)}",
+                    )
+                last_debug_start[coder] = ts
+            elif state == "is refactoring":
+                debug_start = last_debug_start[coder]
+                if debug_start is None:
+                    return (
+                        False,
+                        "refactoring started without debugging start\n"
+                        f"line={idx}\n"
+                        f"coder_id={coder}\n"
+                        f"line_value={self._preview(line)}",
+                    )
+                elapsed_debug = ts - debug_start
+                if elapsed_debug < time_to_debug:
+                    return (
+                        False,
+                        "debug phase ended too early before refactoring\n"
+                        f"line={idx}\n"
+                        f"coder_id={coder}\n"
+                        f"expected_min_debug_ms={time_to_debug}\n"
+                        f"actual_debug_ms={elapsed_debug}\n"
+                        f"line_value={self._preview(line)}",
+                    )
+                last_refactor_start[coder] = ts
+            elif state == "burned out":
+                burnouts += 1
+                burnout_coder = coder
+                deadline = last_compile_start[coder] + time_to_burnout
+                lateness = ts - deadline
+                if lateness < 0:
+                    return (
+                        False,
+                        "burned out before burnout deadline\n"
+                        f"line={idx}\n"
+                        f"coder_id={coder}\n"
+                        f"deadline_ms={deadline}\n"
+                        f"actual_burnout_ms={ts}\n"
+                        f"line_value={self._preview(line)}",
+                    )
+                if lateness > 10:
+                    return (
+                        False,
+                        "burnout detection delayed beyond 10ms requirement\n"
+                        f"line={idx}\n"
+                        f"coder_id={coder}\n"
+                        f"deadline_ms={deadline}\n"
+                        f"actual_burnout_ms={ts}\n"
+                        f"delay_ms={lateness}\n"
+                        f"line_value={self._preview(line)}",
+                    )
+                if idx != len(lines):
+                    next_line = lines[idx] if idx < len(lines) else "<none>"
+                    return (
+                        False,
+                        "burned out event is not the last log line\n"
+                        f"line={idx}\n"
+                        f"burned_out_line={self._preview(line)}\n"
+                        f"next_line={self._preview(next_line)}",
+                    )
+
+            last_state[coder] = state
+
+        if burnouts > 1:
+            return False, f"multiple burned out events detected\ncount={burnouts}"
+
+        if burnouts == 0:
+            if compiles_required > 0:
+                not_done = [str(coder_id) for coder_id, count in compile_counts.items() if count < compiles_required]
+                if not_done:
+                    return (
+                        False,
+                        "simulation ended before all coders reached required compile count\n"
+                        f"required_compiles={compiles_required}\n"
+                        f"coders_not_done={','.join(not_done[:20])}"
+                        f"{'...' if len(not_done) > 20 else ''}",
+                    )
+        else:
+            if compiles_required > 0 and all(count >= compiles_required for count in compile_counts.values()):
+                return (
+                    False,
+                    "burnout happened even though all coders reached required compile count\n"
+                    f"burnout_coder={burnout_coder}",
+                )
+
+        return True, "logs are coherent"
+
+    def _build_counter(self, n_coders: int) -> Dict[int, int]:
+        return {coder_id: 0 for coder_id in range(1, n_coders + 1)}
+
+    def _preview(self, text: str, max_len: int = 240) -> str:
+        cleaned = text.replace("\n", "\\n")
+        if len(cleaned) <= max_len:
+            return cleaned
+        return f"{cleaned[:max_len]}...(truncated)"
+
+    def _parse_regular_args(
+        self, raw_args: Tuple[str, ...]
+    ) -> Tuple[Optional[Tuple[int, int, int, int, int, int, int, str]], Optional[str]]:
+        if len(raw_args) != 8:
+            return None, f"invalid test case definition: expected 8 args, got {len(raw_args)}"
+
+        values = list(raw_args[:7])
+        parsed: List[int] = []
+        for idx, value in enumerate(values, start=1):
+            if not self._is_integer(value):
+                return None, f"invalid numeric argument in case definition\narg_index={idx}\nvalue={self._preview(value)}"
+            parsed.append(int(value))
+
+        scheduler = raw_args[7]
+        if scheduler not in ("fifo", "edf"):
+            return None, f"invalid scheduler in case definition\nvalue={self._preview(scheduler)}"
+
+        if parsed[0] <= 0:
+            return None, f"number_of_coders must be > 0\nvalue={parsed[0]}"
+        if parsed[5] < 0:
+            return None, f"number_of_compiles_required must be >= 0\nvalue={parsed[5]}"
+        for idx, value in enumerate(parsed[1:], start=2):
+            if idx == 6:
+                continue
+            if value < 0:
+                return None, f"time/cooldown arguments must be >= 0\narg_index={idx}\nvalue={value}"
+
+        return (parsed[0], parsed[1], parsed[2], parsed[3], parsed[4], parsed[5], parsed[6], scheduler), None
+
+    def _transition_invalid(self, previous_state: str, current_state: str, taken_count: int) -> bool:
+        if current_state == "burned out":
+            return False
+        if previous_state == "init":
+            return current_state != "has taken a dongle"
+        if previous_state == "has taken a dongle":
+            if current_state == "has taken a dongle":
+                return taken_count >= 2
+            return current_state != "is compiling"
+        if previous_state == "is compiling":
+            return current_state != "is debugging"
+        if previous_state == "is debugging":
+            return current_state != "is refactoring"
+        if previous_state == "is refactoring":
+            return current_state != "has taken a dongle"
+        return False
+
+    def _is_integer(self, value: str) -> bool:
+        if not value:
+            return False
+        if value[0] in "+-":
+            return value[1:].isdigit()
+        return value.isdigit()

pacodexion-0.1.0/src/pacodexion/PacodexionCLI.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import List, Sequence
+
+from .CaseRegistry import CaseRegistry
+from .CaseRunner import CaseRunner
+from .KoTraceWriter import KoTraceWriter
+from .ResultFormatter import ResultFormatter
+from .TestCase import TestCase
+
+
+class PacodexionCLI:
+    def __init__(self) -> None:
+        self.registry = CaseRegistry()
+        self.runner = CaseRunner()
+        self.trace_writer = KoTraceWriter()
+        self.use_color = sys.stdout.isatty()
+        self.formatter = ResultFormatter(use_color=self.use_color)
+
+    def parse_args(self, argv: Sequence[str]) -> argparse.Namespace:
+        parser = argparse.ArgumentParser(
+            prog="pacodexion",
+            description="Run Codexion scenarios against ./codexion and validate logs.",
+        )
+        parser.add_argument(
+            "cases",
+            nargs="*",
+            help="Case keys to run (example: 1 big error_arg3). If omitted, run all.",
+        )
+        parser.add_argument(
+            "--binary",
+            default="./codexion",
+            help="Path to codexion binary (default: ./codexion).",
+        )
+        parser.add_argument(
+            "--timeout",
+            type=float,
+            default=60.0,
+            help="Per-test timeout in seconds (default: 60).",
+        )
+        return parser.parse_args(argv)
+
+    def run(self, argv: Sequence[str]) -> int:
+        args = self.parse_args(argv)
+        selected, unknown = self.registry.select_cases(args.cases)
+
+        if unknown:
+            for token in unknown:
+                print(f"[FAIL] unknown test key: {token}", file=sys.stderr)
+            return 2
+
+        if not os.path.exists(args.binary):
+            print(f"[FAIL] binary not found: {args.binary}", file=sys.stderr)
+            return 2
+        if not os.access(args.binary, os.X_OK):
+            print(f"[FAIL] binary is not executable: {args.binary}", file=sys.stderr)
+            return 2
+
+        results = self._run_cases_live(args.binary, selected, args.timeout)
+        any_fail = any(not ok for _, ok, _ in results)
+        print(self.formatter.render_summary(results))
+        return 1 if any_fail else 0
+
+    def _run_cases_live(self, binary: str, selected: List[TestCase], timeout: float) -> List[tuple[TestCase, bool, str]]:
+        results: List[tuple[TestCase, bool, str]] = []
+        spinner_frames = ["|", "/", "-", "\\"]
+
+        for case in selected:
+            spinner_index = 0
+            started_line = False
+
+            def on_tick(_: float) -> None:
+                nonlocal spinner_index, started_line
+                if not sys.stdout.isatty():
+                    if not started_line:
+                        print(self.formatter.render_running(case, spinner_frames[0]))
+                        started_line = True
+                    return
+                frame = spinner_frames[spinner_index % len(spinner_frames)]
+                spinner_index += 1
+                print(self.formatter.render_running(case, frame), end="", flush=True)
+                started_line = True
+
+            ok, detail = self.runner.run_case_with_progress(binary, case, timeout, on_tick=on_tick)
+            if started_line and sys.stdout.isatty():
+                print("\r" + " " * 100 + "\r", end="")
+            print(self.formatter.render_result(case, ok, detail))
+            if not ok:
+                trace_file = self.trace_writer.write(case, self.runner.get_last_output(), detail)
+                print(f"  trace: {trace_file}")
+            results.append((case, ok, detail))
+
+        return results

pacodexion-0.1.0/src/pacodexion/ResultFormatter.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Iterable, Tuple
+
+from .TestCase import TestCase
+
+CaseResult = Tuple[TestCase, bool, str]
+
+
+class ResultFormatter:
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    GREEN = "\033[32m"
+    RED = "\033[31m"
+    CYAN = "\033[36m"
+
+    def __init__(self, use_color: bool) -> None:
+        self.use_color = use_color
+
+    def _color(self, text: str, color: str) -> str:
+        if not self.use_color:
+            return text
+        return f"{color}{text}{self.RESET}"
+
+    def _bold(self, text: str) -> str:
+        if not self.use_color:
+            return text
+        return f"{self.BOLD}{text}{self.RESET}"
+
+    def render_result(self, case: TestCase, ok: bool, detail: str) -> str:
+        raw_status = "OK" if ok else "KO"
+        color = self.GREEN if ok else self.RED
+        status = self._color(raw_status, color)
+        header = f"[{status}] {case.key} ({case.name})"
+        if ok:
+            return header
+        trace = self._color(detail, self.RED)
+        return f"{header}\n{trace}\n"
+
+    def render_results(self, results: Iterable[CaseResult]) -> Iterable[str]:
+        for case, ok, detail in results:
+            yield self.render_result(case, ok, detail)
+
+    def render_summary(self, results: Iterable[CaseResult]) -> str:
+        result_list = list(results)
+        passed = sum(1 for _, ok, _ in result_list if ok)
+        total = len(result_list)
+        summary = f"Summary: {passed}/{total} passed"
+        if passed == total:
+            return self._bold(self._color(summary, self.GREEN))
+        return self._bold(self._color(summary, self.RED))
+
+    def render_running(self, case: TestCase, frame: str) -> str:
+        if self.use_color:
+            return f"\r{self._color(frame, self.CYAN)} Running {case.key} ({case.name})..."
+        return f"Running {case.key} ({case.name})..."

pacodexion-0.1.0/src/pacodexion/TestCase.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from typing import Tuple
+
+
+@dataclass(frozen=True)
+class TestCase:
+    key: str
+    name: str
+    args: Tuple[str, ...]
+    expect_invalid_args: bool = False

pacodexion-0.1.0/src/pacodexion/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

pacodexion-0.1.0/src/pacodexion/__main__.py

@@ -0,0 +1,13 @@
+import sys
+from typing import Sequence
+
+from .PacodexionCLI import PacodexionCLI
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    cli = PacodexionCLI()
+    return cli.run(argv if argv is not None else sys.argv[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pacodexion-0.1.0/src/pacodexion.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: pacodexion
+Version: 0.1.0
+Summary: Runner and validator for Codexion project test cases.
+Author: pacodexion
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pacodexion
+
+Installable CLI package that runs Codexion test scenarios against `./codexion` and validates output consistency.

pacodexion-0.1.0/src/pacodexion.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/pacodexion/CaseRegistry.py
+src/pacodexion/CaseRunner.py
+src/pacodexion/KoTraceWriter.py
+src/pacodexion/OutputValidator.py
+src/pacodexion/PacodexionCLI.py
+src/pacodexion/ResultFormatter.py
+src/pacodexion/TestCase.py
+src/pacodexion/__init__.py
+src/pacodexion/__main__.py
+src/pacodexion.egg-info/PKG-INFO
+src/pacodexion.egg-info/SOURCES.txt
+src/pacodexion.egg-info/dependency_links.txt
+src/pacodexion.egg-info/entry_points.txt
+src/pacodexion.egg-info/top_level.txt

pacodexion-0.1.0/src/pacodexion.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pacodexion-0.1.0/src/pacodexion.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pacodexion = pacodexion.__main__:main

pacodexion-0.1.0/src/pacodexion.egg-info/top_level.txt

@@ -0,0 +1 @@
+pacodexion