codepraxis 0.2.1__tar.gz → 0.3.0__tar.gz

{codepraxis-0.2.1 → codepraxis-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codepraxis
-Version: 0.2.1
+Version: 0.3.0
 Summary: Author and validate CodePraxis challenge packs.
 Project-URL: Documentation, https://docs.codepraxis.com/authoring
 Author: CodePraxis
@@ -29,8 +29,11 @@ Author and validate CodePraxis challenge packs from your own repository.
 
 ```bash
 pip install codepraxis
+codepraxis --example                         # see a real challenge, no account needed
+codepraxis new my-challenge                  # scaffold one that already validates
+codepraxis lint my-challenge                 # static checks, no execution
+codepraxis validate --local my-challenge     # run it, fast and advisory
 codepraxis --login
-codepraxis validate --local my-challenge     # fast, advisory
 codepraxis --publish my-challenge            # validates in the runner, then publishes
 ```
 
@@ -68,6 +71,42 @@ codepraxis validate --local my-challenge
 Once a key is configured the leniency stops: a model failure is then a real
 failure, because it can be judged.
 
+## Try it first
+
+```bash
+codepraxis --example
+```
+
+Starts a throwaway container with the featured challenge already cloned into it
+and prints a URL. That is exactly what a candidate sees. No login, no account,
+nothing recorded as an attempt. Add `--open` to launch it in your browser.
+
+## Starting a new pack
+
+```bash
+codepraxis new my-challenge
+codepraxis validate --local my-challenge     # → PASSED
+```
+
+The generated pack is complete and already passing — solution passes, starter
+fails. Edit `._course_data/feature.md`, `source/`, `._tests/test_1.py` and
+`../solution/` to make it yours.
+
+## Two kinds of checking
+
+| Command | Runs | Cost |
+|---|---|---|
+| `codepraxis lint` | Static rules over the files | milliseconds, no execution |
+| `codepraxis validate` | The tests, against both fixtures | seconds (local) or ~1 min (remote) |
+
+`lint` never imports pack code, so it is safe on a pack you did not write and
+fast enough for every save. It catches things that otherwise only surface inside
+a container — a two-argument `testCases.__init__`, zero-padded case names, a
+`solution/` directory nested inside the pack, LaTeX in the Instructions brief.
+`validate` runs it automatically first and stops if it finds an error, because
+executing a pack whose class cannot be constructed only produces a confusing
+traceback.
+
 ## The two fixtures
 
 Every pack is validated twice:

{codepraxis-0.2.1 → codepraxis-0.3.0}/README.md

@@ -4,8 +4,11 @@ Author and validate CodePraxis challenge packs from your own repository.
 
 ```bash
 pip install codepraxis
+codepraxis --example                         # see a real challenge, no account needed
+codepraxis new my-challenge                  # scaffold one that already validates
+codepraxis lint my-challenge                 # static checks, no execution
+codepraxis validate --local my-challenge     # run it, fast and advisory
 codepraxis --login
-codepraxis validate --local my-challenge     # fast, advisory
 codepraxis --publish my-challenge            # validates in the runner, then publishes
 ```
 
@@ -43,6 +46,42 @@ codepraxis validate --local my-challenge
 Once a key is configured the leniency stops: a model failure is then a real
 failure, because it can be judged.
 
+## Try it first
+
+```bash
+codepraxis --example
+```
+
+Starts a throwaway container with the featured challenge already cloned into it
+and prints a URL. That is exactly what a candidate sees. No login, no account,
+nothing recorded as an attempt. Add `--open` to launch it in your browser.
+
+## Starting a new pack
+
+```bash
+codepraxis new my-challenge
+codepraxis validate --local my-challenge     # → PASSED
+```
+
+The generated pack is complete and already passing — solution passes, starter
+fails. Edit `._course_data/feature.md`, `source/`, `._tests/test_1.py` and
+`../solution/` to make it yours.
+
+## Two kinds of checking
+
+| Command | Runs | Cost |
+|---|---|---|
+| `codepraxis lint` | Static rules over the files | milliseconds, no execution |
+| `codepraxis validate` | The tests, against both fixtures | seconds (local) or ~1 min (remote) |
+
+`lint` never imports pack code, so it is safe on a pack you did not write and
+fast enough for every save. It catches things that otherwise only surface inside
+a container — a two-argument `testCases.__init__`, zero-padded case names, a
+`solution/` directory nested inside the pack, LaTeX in the Instructions brief.
+`validate` runs it automatically first and stops if it finds an error, because
+executing a pack whose class cannot be constructed only produces a confusing
+traceback.
+
 ## The two fixtures
 
 Every pack is validated twice:

{codepraxis-0.2.1 → codepraxis-0.3.0}/src/codepraxis/__init__.py

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

{codepraxis-0.2.1 → codepraxis-0.3.0}/src/codepraxis/cli.py

@@ -12,6 +12,8 @@ import sys
 from pathlib import Path
 
 from . import __version__
+from .commands import example as example_command
+from .commands import lint as lint_command
 from .commands import login as login_command
 from .commands import publish as publish_command
 from .commands import validate as validate_command
@@ -21,6 +23,7 @@ from .execution.local.executor import LocalExecutor
 from .plugin import installer
 from .reporting.human import HumanReporter
 from .reporting.json_reporter import JsonReporter
+from .scaffold import generator
 
 EXIT_USAGE = 2
 
@@ -62,6 +65,11 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="TARGET",
         help="Install an integration. Currently: claude-plugin.",
     )
+    actions.add_argument(
+        "--example",
+        action="store_true",
+        help="Open the featured challenge in a live container. No account needed.",
+    )
 
     parser.add_argument(
         "--root",
@@ -87,6 +95,12 @@ def build_parser() -> argparse.ArgumentParser:
         help="Show passing cases and anything the tier cannot verify.",
     )
     parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    parser.add_argument(
+        "--open",
+        action="store_true",
+        dest="open_browser",
+        help="With --example, open the container in your browser.",
+    )
 
     subparsers = parser.add_subparsers(dest="command")
 
@@ -146,6 +160,37 @@ def build_parser() -> argparse.ArgumentParser:
     check.add_argument("-v", "--verbose", action="store_true", help="Show passing cases and notes.")
     check.set_defaults(handler=_handle_validate)
 
+    static = subparsers.add_parser(
+        "lint",
+        help="Static checks only — no execution, no container.",
+        description=(
+            "Reads the pack and reports problems without importing or running any "
+            "of its code. Fast enough to run on every save, and safe on a pack you "
+            "did not write."
+        ),
+    )
+    static.add_argument("selector", nargs="?", help="Pack directory or name.")
+    static.add_argument("--root", type=Path, default=None, help="Directory to search for packs.")
+    static.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    static.add_argument("-v", "--verbose", action="store_true", help="Show notes as well as problems.")
+    static.set_defaults(handler=_handle_lint)
+
+    scaffold = subparsers.add_parser(
+        "new",
+        help="Scaffold a new pack that already validates.",
+        description=(
+            "Writes a complete, passing pack you can edit: solution passes, starter "
+            "fails. Running `codepraxis validate --local` on it should go green "
+            "immediately, which also proves your setup works."
+        ),
+    )
+    scaffold.add_argument("name", help="Pack name (lowercase letters, digits, underscores).")
+    scaffold.add_argument("--root", type=Path, default=None, help="Where to create it (default: ./challenges).")
+    scaffold.add_argument("--backend", default="AI", help="BACKEND value: AI, DSA, EMB or LNX.")
+    scaffold.add_argument("--language", default="PYTHON", help="LANGUAGE value.")
+    scaffold.add_argument("--force", action="store_true", help="Overwrite an existing directory.")
+    scaffold.set_defaults(handler=_handle_new)
+
     return parser
 
 
@@ -177,6 +222,29 @@ def _handle_validate(args: argparse.Namespace) -> int:
     )
 
 
+def _handle_lint(args: argparse.Namespace) -> int:
+    return lint_command.run(
+        root=args.root or Path.cwd(),
+        selector=args.selector,
+        reporter=_reporter(args),
+    )
+
+
+def _handle_new(args: argparse.Namespace) -> int:
+    # Default to ./challenges so the solution/ sibling lands outside the pack
+    # without the author having to think about layout.
+    root = args.root or (Path.cwd() / "challenges")
+    result = generator.create(
+        root=root,
+        raw_name=args.name,
+        backend=args.backend,
+        language=args.language,
+        force=args.force,
+    )
+    print(generator.describe(result, Path.cwd()))
+    return 0
+
+
 def _handle_install(target: str, force: bool) -> int:
     if target == "claude-plugin":
         result = installer.install(Path.cwd(), force=force)
@@ -203,6 +271,8 @@ def main(argv: list[str] | None = None) -> int:
             )
         if args.install:
             return _handle_install(args.install, args.force)
+        if args.example:
+            return example_command.run(open_browser=args.open_browser)
         if not getattr(args, "handler", None):
             parser.print_help()
             return EXIT_USAGE

codepraxis-0.3.0/src/codepraxis/commands/example.py

@@ -0,0 +1,73 @@
+"""``codepraxis --example`` — open the featured challenge in a live container.
+
+The fastest way to understand what a pack becomes: the platform allocates a
+throwaway container, clones the featured challenge into it, and returns a URL
+you can open in a browser to see exactly what a candidate sees.
+
+Deliberately unauthenticated. This is the first thing someone runs after
+installing, usually before they have a key, so requiring login would put a
+signup in front of the demo.
+"""
+
+from __future__ import annotations
+
+import webbrowser
+
+from ..errors import PraxisError
+from ..execution.remote.client import ApiClient
+from ..execution.remote.config import RemoteConfig
+
+EXIT_OK = 0
+
+FEATURED_PATH = "/challenges/featured"
+TRIAL_PATH = "/challenges/trial/setup-codebase"
+
+
+def run(client: ApiClient | None = None, open_browser: bool = False) -> int:
+    client = client or ApiClient(RemoteConfig.resolve_public())
+
+    challenge = (client.get(FEATURED_PATH) or {}).get("challenge") or {}
+    _describe(challenge)
+
+    print("\nStarting a container… this usually takes under a minute.")
+    session = client.post_json(TRIAL_PATH, {})
+
+    url = session.get("container_url")
+    if not url:
+        raise PraxisError("The platform started a session but returned no container URL.")
+
+    print(f"\n  {url}\n")
+    _footer(session)
+
+    if open_browser:
+        webbrowser.open(url)
+
+    return EXIT_OK
+
+
+def _describe(challenge: dict) -> None:
+    name = challenge.get("challenge_name") or "Featured challenge"
+    print(name)
+
+    description = challenge.get("description")
+    if description:
+        print(f"  {str(description).strip().splitlines()[0]}")
+
+    difficulty = {1: "Easy", 2: "Medium", 3: "Hard"}.get(challenge.get("difficulty"))
+    # Drop blanks: the field frequently carries an empty trailing entry.
+    stack = [item for item in (challenge.get("tech_stack") or []) if str(item).strip()]
+    bits = [bit for bit in (difficulty, ", ".join(stack) if stack else None) if bit]
+    if bits:
+        print(f"  {' · '.join(bits)}")
+
+    if challenge.get("max_time"):
+        print(f"  {challenge['max_time']} minutes")
+
+
+def _footer(session: dict) -> None:
+    expires = session.get("attempt_expires_at")
+    if expires:
+        print(f"The container is temporary and expires at {expires}.")
+    else:
+        print("The container is temporary and will be reclaimed when idle.")
+    print("Nothing you do in it is recorded as an attempt.")

codepraxis-0.3.0/src/codepraxis/commands/lint.py

@@ -0,0 +1,43 @@
+"""``codepraxis lint`` — static checks only, no execution.
+
+Fast enough to run on every save, and safe to run against a pack you did not
+write, because no pack code is imported.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..domain.results import RunResult
+from ..errors import PackError
+from ..packio.discovery import find_packs, resolve_pack_dir
+from ..packio.loader import load_pack
+from ..reporting.reporter import Reporter
+from ..validation.registry import has_errors
+from ..validation.registry import lint as run_rules
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+
+
+def run(root: Path, selector: str | None, reporter: Reporter) -> int:
+    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)
+            findings = run_rules(pack)
+            reporter.report(
+                RunResult(pack_name=pack.name, executor="lint", diagnostics=tuple(findings))
+            )
+            if has_errors(findings):
+                exit_code = EXIT_FAILED
+    finally:
+        reporter.close()
+    return exit_code

{codepraxis-0.2.1 → codepraxis-0.3.0}/src/codepraxis/commands/validate.py

@@ -8,15 +8,18 @@ identical for both tiers and testable without a subprocess or a network.
 
 from __future__ import annotations
 
+import dataclasses
 from collections.abc import Sequence
 from pathlib import Path
 
-from ..domain.results import Fixture
+from ..domain.results import Fixture, RunResult
 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
+from ..validation.registry import has_errors
+from ..validation.registry import lint as run_rules
 
 EXIT_OK = 0
 EXIT_FAILED = 1
@@ -42,8 +45,25 @@ def run(
     try:
         for pack_dir in pack_dirs:
             pack = load_pack(pack_dir)
+
+            # Static rules first. A pack whose testCases cannot be constructed
+            # produces an opaque traceback when executed, so there is nothing to
+            # learn from running it — report the real cause and move on.
+            findings = run_rules(pack)
+            if has_errors(findings):
+                reporter.report(
+                    RunResult(pack_name=pack.name, executor="lint", diagnostics=tuple(findings))
+                )
+                exit_code = EXIT_FAILED
+                continue
+
             chosen = list(fixtures) if fixtures else _default_fixtures(pack)
             result = executor.execute(pack, chosen)
+            # Warnings from the static pass travel with the execution result so
+            # the author sees one report, not two.
+            result = dataclasses.replace(
+                result, diagnostics=tuple(findings) + tuple(result.diagnostics)
+            )
             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

{codepraxis-0.2.1 → codepraxis-0.3.0}/src/codepraxis/execution/remote/client.py

@@ -61,12 +61,15 @@ class ApiClient:
 
     def _headers(self, content_type: str | None = None) -> dict:
         headers = {
-            "Authorization": f"Bearer {self._config.token}",
             # Lets the server reject or warn on a CLI too old for the current
             # pack contract, instead of failing somewhere obscure.
             "X-Praxis-CLI-Version": __version__,
             "Accept": "application/json",
         }
+        # Public endpoints are called without credentials; sending an empty
+        # bearer token would be rejected as a malformed header.
+        if self._config.token:
+            headers["Authorization"] = f"Bearer {self._config.token}"
         if content_type:
             headers["Content-Type"] = content_type
         return headers

{codepraxis-0.2.1 → codepraxis-0.3.0}/src/codepraxis/execution/remote/config.py

@@ -67,6 +67,17 @@ class RemoteConfig:
     #: so the CLI can show it before a publish. The server is authoritative.
     company: str | None = None
 
+    @classmethod
+    def resolve_public(cls, api_url: str | None = None) -> RemoteConfig:
+        """Config for endpoints that need no key.
+
+        Used by ``--example``, which someone runs before they have credentials;
+        requiring a login there would put a signup in front of the demo.
+        """
+        stored = read_stored()
+        resolved_url = api_url or os.environ.get(ENV_API_URL) or stored.get("api_url") or DEFAULT_API_URL
+        return cls(api_url=resolved_url.rstrip("/"), token="", company=stored.get("company"))
+
     @classmethod
     def resolve(cls, api_url: str | None = None, token: str | None = None) -> RemoteConfig:
         """Build a config, or explain precisely what is missing."""

{codepraxis-0.2.1 → codepraxis-0.3.0}/src/codepraxis/reporting/human.py

@@ -124,6 +124,16 @@ class HumanReporter:
         style = self._style
         seconds = result.duration_ms / 1000.0
 
+        # A static-only result has no fixtures, so the pass/fail rules below —
+        # which are about solution vs starter — do not apply. Its verdict is
+        # simply whether any rule reported an error.
+        if not result.runs:
+            if result.errors:
+                self._line(style.bad("  FAILED") + f" {len(result.errors)} problem(s) must be fixed")
+            else:
+                self._line(style.good("  OK") + style.dim("  no problems found"))
+            return
+
         starter = result.run_for(Fixture.STARTER)
         if starter is not None and starter.all_passed:
             self._line(

codepraxis-0.3.0/src/codepraxis/scaffold/generator.py

@@ -0,0 +1,139 @@
+"""Generate a new pack from templates.
+
+The generated pack is deliberately *complete and passing*: run
+``codepraxis validate --local`` on it straight away and it goes green. That
+gives an author a known-good starting point and proves their toolchain works
+before they have written anything.
+
+Templates ship inside the wheel and are read through ``importlib.resources`` so
+this works from an installed package as well as a source checkout.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+from ..domain import contract
+from ..errors import PraxisError
+
+#: metadata.json "name" becomes a directory name inside the container, so it is
+#: restricted to what a shell and a filesystem both handle without quoting.
+_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_]{2,49}$")
+
+KNOWN_BACKENDS = ("AI", "DSA", "EMB", "LNX")
+
+
+@dataclass(frozen=True)
+class ScaffoldResult:
+    pack_dir: Path
+    solution_dir: Path
+    files: list
+
+
+def normalize_name(raw: str) -> str:
+    """Turn a user-supplied slug into a valid pack name."""
+    name = raw.strip().lower().replace("-", "_").replace(" ", "_")
+    name = re.sub(r"_+", "_", name).strip("_")
+    if not _NAME_PATTERN.match(name):
+        raise PraxisError(
+            f"{raw!r} is not a usable pack name. Use 3-50 characters, lowercase "
+            f"letters, digits and underscores, starting with a letter."
+        )
+    return name
+
+
+def title_from(name: str) -> str:
+    return name.replace("_", " ").strip().title()
+
+
+def _template(filename: str) -> str:
+    return (resources.files("codepraxis.scaffold") / "templates" / filename).read_text(encoding="utf-8")
+
+
+def _render(filename: str, name: str, backend: str, language: str) -> str:
+    return (
+        _template(filename)
+        .replace("__PACK_NAME__", name)
+        .replace("__TITLE__", title_from(name))
+        .replace("__BACKEND__", backend)
+        .replace("__LANGUAGE__", language)
+    )
+
+
+def create(
+    root: Path,
+    raw_name: str,
+    backend: str = "AI",
+    language: str = "PYTHON",
+    force: bool = False,
+) -> ScaffoldResult:
+    """Write a new pack under ``root`` and return what was created.
+
+    The pack directory and its ``solution/`` sibling are laid out the way the
+    tooling expects: the solution is *beside* the pack so it can never be
+    packaged and shipped to a candidate.
+    """
+    name = normalize_name(raw_name)
+    backend = backend.strip().upper()
+    language = language.strip().upper()
+
+    if backend not in KNOWN_BACKENDS:
+        raise PraxisError(f"Unknown BACKEND {backend!r}. Expected one of: {', '.join(KNOWN_BACKENDS)}")
+
+    pack_dir = (root / name).resolve()
+    solution_dir = pack_dir.parent / "solution"
+
+    if pack_dir.exists() and not force:
+        raise PraxisError(f"{pack_dir} already exists. Choose another name, or pass --force.")
+
+    written = []
+
+    def write(path: Path, content: str) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        written.append(path)
+
+    write(pack_dir / contract.METADATA_FILE, _render("metadata.json", name, backend, language))
+    write(pack_dir / contract.BACKEND_CONF_FILE, _render("backend.conf", name, backend, language))
+    write(pack_dir / contract.SOURCE_DIR / "main.py", _render("main.py", name, backend, language))
+    write(pack_dir / contract.SOURCE_DIR / "README.md", _render("README.md", name, backend, language))
+    write(pack_dir / contract.TESTS_DIR / "test_1.py", _render("test_1.py", name, backend, language))
+    write(
+        pack_dir / contract.COURSE_DATA_DIR / contract.COURSE_TOC_FILE,
+        _render("course_toc.json", name, backend, language),
+    )
+    write(pack_dir / contract.COURSE_DATA_DIR / "feature.md", _render("feature.md", name, backend, language))
+
+    # The reference solution overlays source/, so it mirrors those paths.
+    write(solution_dir / "main.py", _render("solution.py", name, backend, language))
+
+    return ScaffoldResult(pack_dir=pack_dir, solution_dir=solution_dir, files=written)
+
+
+def describe(result: ScaffoldResult, root: Path) -> str:
+    def relative(path: Path) -> str:
+        try:
+            return str(path.relative_to(root))
+        except ValueError:
+            return str(path)
+
+    return "\n".join(
+        [
+            f"Created {relative(result.pack_dir)} ({len(result.files)} files)",
+            f"  solution: {relative(result.solution_dir)}  (beside the pack — never uploaded)",
+            "",
+            "It already validates. Check your setup:",
+            "",
+            f"  codepraxis validate --local {result.pack_dir.name}",
+            "",
+            "Then make it your own:",
+            "",
+            "  ._course_data/feature.md   what the candidate reads",
+            "  source/                    what they start from",
+            "  ._tests/test_1.py          how it is graded",
+            "  ../solution/               the reference answer",
+        ]
+    )

codepraxis-0.3.0/src/codepraxis/scaffold/templates/README.md

@@ -0,0 +1,7 @@
+# __TITLE__
+
+`total()` in `main.py` is not implemented yet — it raises.
+
+Run it:
+
+    python3 main.py 1 2 3

codepraxis-0.3.0/src/codepraxis/scaffold/templates/backend.conf

@@ -0,0 +1,4 @@
+{
+  "BACKEND": "__BACKEND__",
+  "LANGUAGE": "__LANGUAGE__"
+}

codepraxis-0.3.0/src/codepraxis/scaffold/templates/course_toc.json

@@ -0,0 +1,8 @@
+{
+  "instruction_1": {
+    "file": "feature.md",
+    "metadata": {
+      "STATUS": "IN_PROGRESS"
+    }
+  }
+}

codepraxis-0.3.0/src/codepraxis/scaffold/templates/feature.md

@@ -0,0 +1,21 @@
+# __TITLE__
+
+Replace this with the task the candidate has to do.
+
+## What to build
+
+`main.py` currently raises instead of returning a result. Make it work.
+
+## Constraints
+
+- Read arguments from the command line.
+- Print one line to stdout and nothing else.
+
+## Example
+
+Running with the arguments 1, 2 and 3 prints 6.
+
+## Acceptance criteria
+
+- Summing 1, 2 and 3 prints 6.
+- Summing -5 and 5 prints 0.

codepraxis-0.3.0/src/codepraxis/scaffold/templates/main.py

@@ -0,0 +1,12 @@
+"""__TITLE__"""
+
+import sys
+
+
+def total(numbers):
+    """Return the sum of ``numbers``."""
+    raise NotImplementedError("implement total()")
+
+
+if __name__ == "__main__":
+    print(total([int(argument) for argument in sys.argv[1:]]))

codepraxis-0.3.0/src/codepraxis/scaffold/templates/metadata.json

@@ -0,0 +1,3 @@
+{
+  "name": "__PACK_NAME__"
+}