codepraxis 0.1.0__py3-none-any.whl

codepraxis/__init__.py

@@ -0,0 +1,3 @@
+"""Author and validate CodePraxis challenge packs."""
+
+__version__ = "0.1.0"

codepraxis/__main__.py

@@ -0,0 +1,8 @@
+"""Allows ``python -m praxis``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

codepraxis/cli.py

@@ -0,0 +1,219 @@
+"""Command-line entry point.
+
+Argument parsing and dependency wiring, nothing else. Concrete executors and
+reporters are chosen here and injected into commands, so commands stay
+independent of how results are produced or rendered.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .commands import login as login_command
+from .commands import publish as publish_command
+from .commands import validate as validate_command
+from .domain.results import Fixture
+from .errors import PraxisError
+from .execution.local.executor import LocalExecutor
+from .plugin import installer
+from .reporting.human import HumanReporter
+from .reporting.json_reporter import JsonReporter
+
+EXIT_USAGE = 2
+
+INSTALLABLES = ("claude-plugin",)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codepraxis",
+        description="Author, validate and publish CodePraxis challenge packs.",
+        epilog=(
+            "Typical flow:\n"
+            "  codepraxis --login\n"
+            "  codepraxis validate --local my-challenge     # fast, advisory\n"
+            "  codepraxis validate --remote my-challenge    # the real runner\n"
+            "  codepraxis --publish my-challenge            # validates, then publishes\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"codepraxis {__version__}")
+
+    # Top-level actions. Mutually exclusive because each is a whole task.
+    actions = parser.add_mutually_exclusive_group()
+    actions.add_argument(
+        "--login",
+        action="store_true",
+        help="Store an API key and show which company it publishes as.",
+    )
+    actions.add_argument(
+        "--publish",
+        nargs="?",
+        const="",
+        metavar="PACK",
+        help="Validate a pack in the runner, then publish it to your company.",
+    )
+    actions.add_argument(
+        "--install",
+        choices=INSTALLABLES,
+        metavar="TARGET",
+        help="Install an integration. Currently: claude-plugin.",
+    )
+
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path.cwd(),
+        help="Directory to search for packs (default: current directory).",
+    )
+    parser.add_argument("--force", action="store_true", help="With --install, overwrite an existing install.")
+    parser.add_argument("--yes", action="store_true", help="With --publish, skip the confirmation prompt.")
+    parser.add_argument(
+        "--live",
+        action="store_true",
+        help="With --publish, publish straight to candidates instead of as a draft.",
+    )
+    parser.add_argument(
+        "--validation-run-id",
+        help="With --publish, reuse a passing validation run instead of running a new one.",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show passing cases and anything the tier cannot verify.",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    check = subparsers.add_parser(
+        "validate",
+        help="Validate a pack: the solution must pass, the starter must fail.",
+        description=(
+            "Runs a pack's testCases against the reference solution and the starter. "
+            "--local is a fast advisory check on your machine; --remote runs the real "
+            "runner image on CodePraxis and is what publishing requires."
+        ),
+    )
+    check.add_argument(
+        "selector",
+        nargs="?",
+        help="Pack directory or name. Defaults to every pack found under --root.",
+    )
+    check.add_argument("--root", type=Path, default=None, help="Directory to search for packs.")
+
+    tier = check.add_mutually_exclusive_group()
+    tier.add_argument(
+        "--local",
+        dest="tier",
+        action="store_const",
+        const="local",
+        help="Run on this machine (default). Fast, advisory, no network.",
+    )
+    tier.add_argument(
+        "--remote",
+        dest="tier",
+        action="store_const",
+        const="remote",
+        help="Run in the real runner image on CodePraxis. Required before publishing.",
+    )
+    check.set_defaults(tier="local")
+
+    check.add_argument(
+        "--fixture",
+        choices=[fixture.value for fixture in Fixture],
+        action="append",
+        dest="fixtures",
+        help="Run only this fixture. Repeatable. Defaults to solution + starter.",
+    )
+    check.add_argument(
+        "--llm-base-url",
+        help=(
+            "OpenAI-compatible endpoint for packs that call a model. Defaults to "
+            "OPENAI_BASE_URL. Without a key, model-dependent cases are reported "
+            "unverifiable rather than failed."
+        ),
+    )
+    check.add_argument(
+        "--llm-api-key",
+        help="API key for --llm-base-url. Defaults to OPENAI_API_KEY (preferred: keep it in the environment).",
+    )
+    check.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    check.add_argument("-v", "--verbose", action="store_true", help="Show passing cases and notes.")
+    check.set_defaults(handler=_handle_validate)
+
+    return parser
+
+
+def _reporter(args: argparse.Namespace):
+    return JsonReporter() if args.json else HumanReporter(verbose=args.verbose)
+
+
+def _build_executor(args: argparse.Namespace):
+    if args.tier == "remote":
+        # Imported lazily so a local run never pays for the network stack, and
+        # a missing credential file cannot break an offline run.
+        from .execution.remote.executor import RemoteExecutor
+
+        return RemoteExecutor()
+    return LocalExecutor(
+        llm_base_url=getattr(args, "llm_base_url", None),
+        llm_api_key=getattr(args, "llm_api_key", None),
+    )
+
+
+def _handle_validate(args: argparse.Namespace) -> int:
+    fixtures = [Fixture(value) for value in args.fixtures] if args.fixtures else None
+    return validate_command.run(
+        root=args.root or Path.cwd(),
+        selector=args.selector,
+        executor=_build_executor(args),
+        reporter=_reporter(args),
+        fixtures=fixtures,
+    )
+
+
+def _handle_install(target: str, force: bool) -> int:
+    if target == "claude-plugin":
+        result = installer.install(Path.cwd(), force=force)
+        print(installer.describe(result))
+        return 0
+    raise PraxisError(f"Unknown install target: {target}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.login:
+            return login_command.run()
+        if args.publish is not None:
+            return publish_command.run(
+                root=args.root,
+                selector=args.publish or None,
+                reporter=_reporter(args),
+                assume_yes=args.yes,
+                live=args.live,
+                validation_run_id=args.validation_run_id,
+            )
+        if args.install:
+            return _handle_install(args.install, args.force)
+        if not getattr(args, "handler", None):
+            parser.print_help()
+            return EXIT_USAGE
+        return args.handler(args)
+    except PraxisError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    except KeyboardInterrupt:  # pragma: no cover
+        print("interrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

codepraxis/commands/login.py

@@ -0,0 +1,75 @@
+"""``codepraxis --login`` — store an API key and confirm who it belongs to.
+
+The key is verified against the platform before it is written, so a typo fails
+here rather than at the next publish. The response also tells the author which
+company they are acting for, which is what every later publish is scoped to.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+
+from ..errors import PraxisError
+from ..execution.remote.client import ApiClient
+from ..execution.remote.config import (
+    DEFAULT_API_URL,
+    ENV_API_URL,
+    RemoteConfig,
+    read_stored,
+    write_stored,
+)
+
+EXIT_OK = 0
+
+
+def run(api_url: str | None = None, token: str | None = None) -> int:
+    stored = read_stored()
+    resolved_url = api_url or os.environ.get(ENV_API_URL) or stored.get("api_url") or DEFAULT_API_URL
+    resolved_url = resolved_url.rstrip("/")
+
+    key = token or _prompt(resolved_url)
+    if not key:
+        raise PraxisError("No API key entered.")
+
+    # Verify before persisting: a stored bad key produces confusing failures
+    # much later, in commands that look unrelated to authentication.
+    client = ApiClient(RemoteConfig(api_url=resolved_url, token=key))
+    identity = client.get("/me")
+
+    company = identity.get("company") or {}
+    company_name = company.get("name") or identity.get("company_name")
+    company_id = company.get("id") or identity.get("company_id")
+
+    path = write_stored(
+        {
+            "api_url": resolved_url,
+            "token": key,
+            "company": company_name,
+            "company_id": company_id,
+        }
+    )
+
+    who = identity.get("email") or identity.get("user") or "this key"
+    print(f"Logged in as {who}")
+    if company_name:
+        print(f"Publishing as: {company_name}" + (f" (id {company_id})" if company_id else ""))
+    else:
+        # Without a company the key cannot publish; say so now rather than
+        # letting the author discover it at the end of an authoring session.
+        print("warning: this key is not associated with a company; publishing will be rejected.")
+    print(f"Credentials written to {path} (permissions 0600)")
+    return EXIT_OK
+
+
+def _prompt(api_url: str) -> str:
+    if not sys.stdin.isatty():
+        raise PraxisError(
+            "No API key given and stdin is not a terminal. "
+            "Set CODEPRAXIS_TOKEN in the environment instead (this is the CI path)."
+        )
+    print(f"Signing in to {api_url}")
+    print("Create a key at your CodePraxis dashboard -> Settings -> API keys.")
+    # getpass keeps the key out of the terminal scrollback and shell history.
+    return getpass.getpass("API key: ").strip()

codepraxis/commands/publish.py

@@ -0,0 +1,136 @@
+"""``codepraxis --publish`` — publish a validated pack to your company.
+
+Publishing is outward-facing and effectively irreversible: candidates can be
+assigned the challenge immediately. So the flow is deliberately strict.
+
+1. **Validate remotely first.** A pack is only publishable off the back of a
+   passing run in the real runner. Local results never qualify — they cannot
+   observe ``setup.sh``, the image's packages, or the LLM proxy.
+2. **Show the company and confirm.** The server derives ownership from the API
+   key; the CLI never sends a company id, because a client-supplied owner is
+   exactly the tenancy hole this design avoids. The name is displayed so the
+   author can catch a wrong-key mistake before it lands.
+3. **Publish as a draft by default.** Reaching candidates is a separate,
+   deliberate act in the dashboard unless ``--live`` is passed.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from ..domain.results import Fixture
+from ..errors import PraxisError
+from ..execution.remote.client import ApiClient
+from ..execution.remote.config import RemoteConfig
+from ..execution.remote.executor import RemoteExecutor
+from ..packio.discovery import resolve_pack_dir
+from ..packio.loader import load_pack
+from ..reporting.reporter import Reporter
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_ABORTED = 2
+
+
+def run(
+    root: Path,
+    selector: str | None,
+    reporter: Reporter,
+    assume_yes: bool = False,
+    live: bool = False,
+    validation_run_id: str | None = None,
+    client: ApiClient | None = None,
+) -> int:
+    if not selector:
+        raise PraxisError(
+            "Publishing needs an explicit pack: `codepraxis --publish <name>`. "
+            "Refusing to publish every pack it can find."
+        )
+
+    pack = load_pack(resolve_pack_dir(root, selector))
+
+    if not pack.has_solution:
+        raise PraxisError(
+            f"{pack.name} has no solution/ directory. A reference solution is required "
+            f"before publishing — it is what proves the challenge is solvable."
+        )
+
+    # Credentials are resolved lazily so an injected client (tests, and any
+    # future caller that already authenticated) never touches the filesystem.
+    config = None
+    if client is None:
+        config = RemoteConfig.resolve()
+        client = ApiClient(config)
+
+    run_id = validation_run_id
+    if run_id is None:
+        run_id = _validate(pack, client, reporter)
+
+    company = _company_name(client, config)
+    if not _confirm(pack.name, company, live, assume_yes):
+        print("Aborted.", file=sys.stderr)
+        return EXIT_ABORTED
+
+    payload = client.post_json(
+        "/challenges",
+        {
+            # No company_id: the server derives ownership from the API key.
+            "name": pack.name,
+            "validation_run_id": run_id,
+            "status": "published" if live else "draft",
+        },
+    )
+
+    challenge_id = payload.get("challenge_id")
+    version_id = payload.get("challenge_version_id")
+    state = "published" if live else "draft"
+
+    print(f"{pack.name} {state} for {company}")
+    if challenge_id:
+        print(f"  challenge {challenge_id}, version {version_id}")
+    if not live:
+        print("  Publish it to candidates from the dashboard when you are ready.")
+    return EXIT_OK
+
+
+def _validate(pack, client: ApiClient, reporter: Reporter) -> str:
+    """Run remote validation and refuse to continue unless it passes."""
+    print(f"Validating {pack.name} in the runner before publishing…")
+    executor = RemoteExecutor(client=client)
+    result = executor.execute(pack, [Fixture.SOLUTION, Fixture.STARTER])
+    reporter.report(result)
+
+    if not result.ok:
+        raise PraxisError(
+            "Remote validation failed, so nothing was published. "
+            "Fix the pack and try again, or re-run with --validation-run-id to reuse a passing run."
+        )
+
+    if not executor.last_run_id:
+        raise PraxisError("Validation passed but the platform returned no run id to publish against.")
+    return executor.last_run_id
+
+
+def _company_name(client: ApiClient, config: RemoteConfig | None) -> str:
+    """Ask the server who this key acts for; fall back to what login cached."""
+    cached = config.company if config else None
+    try:
+        identity = client.get("/me")
+    except PraxisError:
+        return cached or "your company"
+    company = identity.get("company") or {}
+    return company.get("name") or cached or "your company"
+
+
+def _confirm(pack_name: str, company: str, live: bool, assume_yes: bool) -> bool:
+    if assume_yes:
+        return True
+    if not sys.stdin.isatty():
+        raise PraxisError(
+            "Publishing needs confirmation, but stdin is not a terminal. "
+            "Pass --yes to publish non-interactively (CI)."
+        )
+    visibility = "LIVE to candidates" if live else "as a draft"
+    print(f"\nAbout to publish {pack_name} to {company}, {visibility}.")
+    return input("Continue? [y/N] ").strip().lower() in {"y", "yes"}

codepraxis/commands/validate.py

@@ -0,0 +1,67 @@
+"""``codepraxis validate`` — run a pack's tests.
+
+The command orchestrates and nothing else: it resolves packs, asks an executor
+to run them, hands results to a reporter, and turns them into an exit code.
+Which executor (local or remote) is chosen in ``cli.py``, so this code is
+identical for both tiers and testable without a subprocess or a network.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from ..domain.results import Fixture
+from ..errors import PackError
+from ..execution.executor import Executor
+from ..packio.discovery import find_packs, resolve_pack_dir
+from ..packio.loader import load_pack
+from ..reporting.reporter import Reporter
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+
+
+def run(
+    root: Path,
+    selector: str | None,
+    executor: Executor,
+    reporter: Reporter,
+    fixtures: Sequence[Fixture] | None = None,
+) -> int:
+    """Validate one pack, or every pack under ``root`` when ``selector`` is None."""
+    pack_dirs = [resolve_pack_dir(root, selector)] if selector else find_packs(root)
+
+    if not pack_dirs:
+        raise PackError(
+            f"No challenge packs found under {root}. "
+            f"A pack is a directory containing metadata.json and backend.conf."
+        )
+
+    exit_code = EXIT_OK
+    try:
+        for pack_dir in pack_dirs:
+            pack = load_pack(pack_dir)
+            chosen = list(fixtures) if fixtures else _default_fixtures(pack)
+            result = executor.execute(pack, chosen)
+            reporter.report(result)
+            # An inconclusive run means this tier lacked the infrastructure to
+            # judge the pack, not that the pack is wrong. Failing the command
+            # would block an inner loop over something the author cannot fix.
+            if not result.ok and not result.inconclusive:
+                exit_code = EXIT_FAILED
+    finally:
+        reporter.close()
+    return exit_code
+
+
+def _default_fixtures(pack) -> list[Fixture]:
+    """Run both fixtures when a solution exists.
+
+    The starter run is what proves the tests discriminate, so it is never
+    opt-in; the solution run is skipped only when there is no reference
+    solution yet.
+    """
+    if pack.has_solution:
+        return [Fixture.SOLUTION, Fixture.STARTER]
+    return [Fixture.STARTER]

codepraxis/domain/contract.py

@@ -0,0 +1,96 @@
+"""The pack execution contract, mirrored from the production runner.
+
+Every constant here has a counterpart in the runner image. When the runner
+changes, this file changes with it, and ``tests/conformance`` is what catches
+the drift. Provenance is recorded per constant so the mirror can be re-checked
+against the source rather than trusted.
+
+Sources (paths relative to the ``docker-image`` repo):
+  - ``setupCodeBase.py``  — pack mounting, test-file selection, workspace rsync
+  - ``koro/test_loader.py`` — testCases loading, test-case discovery and ordering
+  - ``koro/test_runner.py``  — per-override execution semantics
+"""
+
+from __future__ import annotations
+
+# --- Pack layout -----------------------------------------------------------
+# setupCodeBase.py mounts the pack at /praxis/codeFromServer/{foldername}/ and
+# reads these paths beneath it. The leading "._" is literal; the runner does not
+# tolerate renamed directories.
+TESTS_DIR = "._tests"
+COURSE_DATA_DIR = "._course_data"
+SOURCE_DIR = "source"
+METADATA_FILE = "metadata.json"
+BACKEND_CONF_FILE = "backend.conf"
+COURSE_TOC_FILE = "course_toc.json"
+
+#: Files/dirs a pack must contain. Mirrors REQUIRED_PACK_FILES in
+#: question-bank/tools/common.py so the CLI and the existing CI agree.
+REQUIRED_PACK_PATHS = (
+    METADATA_FILE,
+    BACKEND_CONF_FILE,
+    SOURCE_DIR,
+    f"{TESTS_DIR}/test_1.py",
+    f"{COURSE_DATA_DIR}/{COURSE_TOC_FILE}",
+    f"{COURSE_DATA_DIR}/feature.md",
+)
+
+# --- Workspace -------------------------------------------------------------
+#: setupCodeBase.py rsyncs ``source/`` *contents* (note the trailing slash in the
+#: runner's rsync) into /home/praxis/{foldername}/ — a flat copy, not a nested
+#: ``source`` directory. ``foldername`` comes from metadata.json's "name".
+CONTAINER_USER = "praxis"
+CONTAINER_WORKSPACE_TEMPLATE = "/home/{user}/{foldername}"
+
+# --- testCases contract ----------------------------------------------------
+#: koro/test_loader.py:87 — ``getattr(test_module, 'testCases')(question_folder)``.
+#: Exactly one argument after ``self``: the workspace path.
+TEST_CLASS_NAME = "testCases"
+
+#: koro/test_loader.py:18 — checked only in developer mode, but authors should
+#: satisfy all of them; a missing attribute here is a warning, not a hard error.
+EXPECTED_TEST_CASE_ATTRS = (
+    "RUN",
+    "RunCaseInputs",
+    "exe",
+    "userWxpace",
+    "default_timeout_window",
+    "msg",
+)
+
+#: koro/test_loader.py:115 — discovery is ``name.startswith('test_case')``,
+#: not a regex match, so ``test_caseFoo`` would also be collected.
+TEST_CASE_PREFIX = "test_case"
+
+#: koro/test_loader.py:130 — ordering key is ``int(re.search(r'\d+', name).group())``:
+#: the FIRST run of digits anywhere in the method name. This is why zero-padded
+#: names collide (``test_case_01`` and ``test_case_1`` both sort as 1) and why
+#: the authoring guide forbids them.
+TEST_CASE_ORDER_PATTERN = r"\d+"
+
+#: koro/test_loader.py:84 — the runner injects ``execute_bin`` into the test
+#: module's namespace before instantiation. Tests may reference it at module
+#: scope, so the harness must provide a binding or import fails.
+INJECTED_EXECUTE_BIN = "execute_bin"
+
+#: setupCodeBase.py:~225 — for EMB and LINUX question types the runner injects a
+#: dummy ``cmd`` handler as well.
+INJECTED_CMD = "cmd"
+
+# --- Execution semantics ---------------------------------------------------
+#: koro/test_runner.py:151 — ``timeout_secs = timeout / 1000.0``. Both
+#: ``default_timeout_window`` and a case's ``timeout_window`` default are in
+#: MILLISECONDS.
+TIMEOUT_UNIT_MS = True
+
+#: koro/test_runner.py:227 — a case passes if and only if ``self.msg == "PASS"``
+#: after the method returns. The return value never decides pass/fail.
+PASS_SENTINEL = "PASS"
+
+#: koro/test_runner.py:206 — ``._bad_input`` anywhere in ``str(result)`` forces
+#: a failure regardless of ``msg``.
+BAD_INPUT_SENTINEL = "._bad_input"
+
+#: koro/test_runner.py:220 — override 1 reads the returned tuple as
+#: ``(panel_text, success_message)`` and reports them as (expected, output).
+OVERRIDE_DEFAULT = 1