patchground 0.1.0__py3-none-any.whl

patchground/catalog/release-version-ordering/environment/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "patchground-vitest-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "vitest": "5.0.5",
+    "vite": "8.3.5"
+  },
+  "scripts": {
+    "test": "node --check vitest-runner.mjs"
+  }
+}

patchground/catalog/release-version-ordering/environment/vitest-runner.mjs

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, writeFile, rename, rm, lstat, realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = '/workspace';
+const final = '/results/junit.xml';
+const self = fileURLToPath(import.meta.url);
+
+async function child(destination, files) {
+  const { startVitest } = await import('vitest/node');
+  let completed;
+  const reporter = {
+    onTestModuleCollected(module) {
+      for (const test of module.children.allTests()) {
+        const retry = test.options.retry;
+        const count = typeof retry === 'number' ? retry : retry?.count ?? 0;
+        if (count > 0 || (test.options.repeats ?? 0) > 0) {
+          throw Error('Retries and repeats are unsupported');
+        }
+      }
+    },
+    onTestRunEnd(modules, errors, reason) {
+      const cases = [];
+      let trustworthy = errors.length === 0 && reason !== 'interrupted';
+      for (const module of modules) {
+        if (module.errors().length) trustworthy = false;
+        for (const suite of module.children.allSuites()) {
+          if (suite.errors().length) trustworthy = false;
+        }
+        for (const test of module.children.allTests()) {
+          const state = test.result().state;
+          if (!['passed', 'failed', 'skipped'].includes(state)) trustworthy = false;
+          cases.push({ file: module.relativeModuleId, name: test.fullName, state });
+        }
+      }
+      completed = { trustworthy, cases };
+    },
+  };
+  const ctx = await startVitest([], {
+    root, config: false, watch: false, run: true,
+    include: files.length ? files : ['**/*.test.ts'], exclude: ['**/node_modules/**', '**/.git/**'],
+    reporters: [reporter], environment: 'node', pool: 'forks', maxWorkers: 1,
+    fileParallelism: false, isolate: true, retry: 0, allowOnly: false, maxConcurrency: 1,
+    passWithNoTests: false, testTimeout: 5000, hookTimeout: 5000,
+    sequence: { shuffle: false },
+  }, {
+    configFile: false, envDir: false, cacheDir: '/tmp/patchground-vite',
+    resolve: { alias: { vitest: '/opt/patchground/node_modules/vitest/dist/index.js' } },
+  });
+  await ctx.close();
+  if (!completed || ctx.state.getUnhandledErrors().length) return;
+  await writeFile(destination, JSON.stringify(completed), { flag: 'wx' });
+}
+
+function escape(value) {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;').replaceAll("'", '&apos;').replaceAll("\n", "&#10;")
+    .replaceAll("\r", "&#13;").replaceAll("\t", "&#9;");
+}
+
+async function parent() {
+  await rm(final, { force: true });
+  const temporary = await mkdtemp(path.join(tmpdir(), 'patchground-vitest-'));
+  try {
+    const receipt = path.join(temporary, 'receipt.json');
+    const args = process.argv.slice(2);
+    const files = args.length ? args.slice(1) : [];
+    if (args.length && (args[0] !== '--files' || !files.length)) return;
+    for (const file of files) {
+      const parts = file.split('/');
+      if (!file.endsWith('.test.ts') || parts.some(part =>
+        !/^[\p{L}\p{N}_. -]+$/u.test(part) || ['.', '..', '.git', 'node_modules'].includes(part))) return;
+    }
+    if (new Set(files).size !== files.length) return;
+    for (const file of files) {
+      const full = path.join(root, file);
+      if (!(await lstat(full)).isFile() || !(await realpath(full)).startsWith(root + '/')) return;
+    }
+    const code = await new Promise((resolve, reject) => {
+      const process = spawn(globalThis.process.execPath, [self, '--child', receipt, ...files], {
+        stdio: 'ignore', env: { ...globalThis.process.env, CI: 'true' },
+      });
+      process.once('error', reject);
+      process.once('exit', (code, signal) => resolve(signal ? null : code));
+    });
+    const result = JSON.parse(await readFile(receipt, 'utf8'));
+    if (!result.trustworthy || !result.cases.length) return;
+    const failed = result.cases.some(test => test.state === 'failed');
+    if (code !== (failed ? 1 : 0)) return;
+    const seen = new Set();
+    result.cases.sort((a, b) => {
+      const left = `${a.file}::${a.name}`;
+      const right = `${b.file}::${b.name}`;
+      return left < right ? -1 : left > right ? 1 : 0;
+    });
+    const cases = result.cases.map(test => {
+      if (!test.file || path.posix.isAbsolute(test.file) || test.file.split('/').includes('..')
+          || test.file.includes('\\') || !test.file.endsWith('.test.ts') || !test.name
+          || !test.file.isWellFormed() || !test.name.isWellFormed()
+          || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/u.test(test.file + test.name)) throw Error('unsafe identity');
+      const id = `${test.file}::${test.name}`;
+      if (seen.has(id)) throw Error('duplicate identity');
+      seen.add(id);
+      const status = test.state === 'failed' ? '<failure message="test failed"/>'
+        : test.state === 'skipped' ? '<skipped/>' : '';
+      return `<testcase classname="${escape(test.file)}" name="${escape(test.name)}">${status}</testcase>`;
+    });
+    const staging = '/results/.patchground-junit.xml';
+    await writeFile(staging, `<?xml version="1.0" encoding="UTF-8"?><testsuites><testsuite name="vitest">${cases.join('')}</testsuite></testsuites>`);
+    await rename(staging, final);
+    process.exitCode = failed ? 1 : 0;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+
+try {
+  if (process.argv[2] === '--child') await child(process.argv[3], process.argv.slice(4));
+  else { process.exitCode = 1; await parent(); }
+} catch {
+  process.exitCode = 1;
+}

patchground/catalog/release-version-ordering/solution/reference.patch

@@ -0,0 +1,36 @@
+--- a/src/releasekit/ordering.ts
++++ b/src/releasekit/ordering.ts
+@@ -6,15 +6,29 @@
+   return a === b ? 0 : a < b ? -1 : 1;
+ }
+
++function numeric(a: string, b: string): Order {
++  return a.length === b.length ? lexical(a, b) : a.length < b.length ? -1 : 1;
++}
++
+ function precedence(a: Version, b: Version): Order {
+   for (let i = 0; i < 3; i += 1) {
+-    const order = lexical(a.core[i], b.core[i]);
++    const order = numeric(a.core[i], b.core[i]);
+     if (order !== 0) return order;
+   }
+   if (a.prerelease.length === 0 && b.prerelease.length === 0) return 0;
+-  if (a.prerelease.length === 0) return -1;
+-  if (b.prerelease.length === 0) return 1;
+-  return lexical(a.prerelease.join("."), b.prerelease.join("."));
++  if (a.prerelease.length === 0) return 1;
++  if (b.prerelease.length === 0) return -1;
++  for (let i = 0; i < Math.min(a.prerelease.length, b.prerelease.length); i += 1) {
++    const left = a.prerelease[i];
++    const right = b.prerelease[i];
++    const leftNumeric = /^[0-9]+$/.test(left);
++    const rightNumeric = /^[0-9]+$/.test(right);
++    const order = leftNumeric && rightNumeric ? numeric(left, right)
++      : leftNumeric !== rightNumeric ? (leftNumeric ? -1 : 1) : lexical(left, right);
++    if (order !== 0) return order;
++  }
++  return a.prerelease.length === b.prerelease.length ? 0
++    : a.prerelease.length < b.prerelease.length ? -1 : 1;
+ }
+
+ export function compare(a: string, b: string): Order {

patchground/catalog/release-version-ordering/workspace/README.md

@@ -0,0 +1,7 @@
+# releasekit
+
+A small pure TypeScript library for ordering strict SemVer release labels. Public exports live in
+`src/releasekit/index.ts`; the challenge ticket specifies their contract. Editable checks are merged
+into `tests/` when a session starts. Use Patchground's container-backed `check` command to run them;
+all runner dependencies are preinstalled in the challenge image. No package install is needed in the
+workspace. Application code is original generated challenge material, licensed under Apache-2.0.

patchground/catalog/release-version-ordering/workspace/src/releasekit/index.ts

@@ -0,0 +1,2 @@
+export {InvalidVersionError} from "./parse";
+export {compare, sortVersions, latest} from "./ordering";

patchground/catalog/release-version-ordering/workspace/src/releasekit/ordering.ts

@@ -0,0 +1,41 @@
+import {parse, type Version} from "./parse";
+
+type Order = -1 | 0 | 1;
+
+function lexical(a: string, b: string): Order {
+  return a === b ? 0 : a < b ? -1 : 1;
+}
+
+function precedence(a: Version, b: Version): Order {
+  for (let i = 0; i < 3; i += 1) {
+    const order = lexical(a.core[i], b.core[i]);
+    if (order !== 0) return order;
+  }
+  if (a.prerelease.length === 0 && b.prerelease.length === 0) return 0;
+  if (a.prerelease.length === 0) return -1;
+  if (b.prerelease.length === 0) return 1;
+  return lexical(a.prerelease.join("."), b.prerelease.join("."));
+}
+
+export function compare(a: string, b: string): Order {
+  return precedence(parse(a), parse(b));
+}
+
+export function sortVersions(versions: readonly string[]): string[] {
+  const parsed = versions.map(value => ({value, parsed: parse(value)}));
+  parsed.sort((a, b) => precedence(a.parsed, b.parsed));
+  return parsed.map(item => item.value);
+}
+
+export function latest(
+  versions: readonly string[],
+  options: {includePrerelease?: boolean} = {},
+): string | undefined {
+  const parsed = versions.map(value => ({value, parsed: parse(value)}));
+  const eligible = parsed.filter(item => options.includePrerelease || item.parsed.prerelease.length === 0);
+  let best: typeof eligible[number] | undefined;
+  for (const item of eligible) {
+    if (best === undefined || precedence(item.parsed, best.parsed) > 0) best = item;
+  }
+  return best?.value;
+}

patchground/catalog/release-version-ordering/workspace/src/releasekit/parse.ts

@@ -0,0 +1,24 @@
+/** Strict label parsing; numeric components stay as strings to preserve precision. */
+export class InvalidVersionError extends Error {
+  constructor() {
+    super("Invalid semantic version");
+    this.name = "InvalidVersionError";
+  }
+}
+
+export interface Version {
+  readonly core: readonly string[];
+  readonly prerelease: readonly string[];
+}
+
+const grammar = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+export function parse(value: string): Version {
+  const match = grammar.exec(value);
+  if (match === null || match[0] !== value) throw new InvalidVersionError();
+  const prerelease = match[4] === undefined ? [] : match[4].split(".");
+  if (prerelease.some(part => /^[0-9]+$/.test(part) && part.length > 1 && part[0] === "0")) {
+    throw new InvalidVersionError();
+  }
+  return {core: [match[1], match[2], match[3]], prerelease};
+}

patchground/cli/__init__.py

@@ -0,0 +1 @@
+"""patchground.cli — see SPEC.md in this folder."""

patchground/cli/app.py

@@ -0,0 +1,59 @@
+"""Typer application behind `patchground` / `pgnd`."""
+
+import typer
+
+from patchground import __version__
+from patchground.cli.authoring import new
+from patchground.cli.discovery import DiscoveryCommand, list_challenges, show
+from patchground.cli.doctor import doctor
+from patchground.cli.packs import app as packs_app
+from patchground.cli.practice import RunCommand, hint, history, run, sessions
+from patchground.cli.reports import report, submit
+from patchground.cli.sessions import SessionCommand, check, reset, start, status
+from patchground.cli.validate import validate
+
+app = typer.Typer(name="patchground", no_args_is_help=True, add_completion=False)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    version: bool = typer.Option(
+        False, "--version", callback=_version, is_eager=True, help="Show the version and exit."
+    ),
+) -> None:
+    """Practice real software engineering on broken repositories. Checks run in Docker.
+
+    `pgnd` is a short alias of `patchground`. New here? Run `pgnd doctor`, then
+    `pgnd list --builtin` and `pgnd start <id>`.
+
+    Sessions are kept in ~/patchground/sessions. To keep them elsewhere, set
+    PATCHGROUND_SESSIONS_DIR to an absolute path.
+    """
+
+
+app.command("validate")(validate)
+app.command("start", cls=SessionCommand)(start)
+app.command("check", cls=SessionCommand)(check)
+app.command("status", cls=SessionCommand)(status)
+app.command("reset", cls=SessionCommand)(reset)
+app.command("doctor", cls=DiscoveryCommand)(doctor)
+app.command("list", cls=DiscoveryCommand)(list_challenges)
+app.command("show", cls=DiscoveryCommand)(show)
+app.command("new", cls=DiscoveryCommand)(new)
+app.command("submit", cls=SessionCommand)(submit)
+app.command("report", cls=SessionCommand)(report)
+app.command("hint", cls=SessionCommand)(hint)
+app.command("sessions", cls=SessionCommand)(sessions)
+app.command("history", cls=SessionCommand)(history)
+app.command("run", cls=RunCommand)(run)
+app.add_typer(packs_app, name="pack")
+
+
+def main() -> None:
+    app()

patchground/cli/authoring.py

@@ -0,0 +1,41 @@
+"""Thin authoring command; no build or run side effects."""
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from patchground.authoring import AuthoringError, CreatedChallenge, create_challenge
+from patchground.cli.render import EXIT_ERROR, EXIT_INTERRUPTED, emit, emit_error
+
+
+def _human(console: Console, result: CreatedChallenge) -> None:
+    console.print(Text(f"created {result.path} ({result.type}, {result.language})"))
+    console.print(Text("Edit the starter, then run:"))
+    console.print(Text(f"  pgnd validate {result.path}"))
+
+
+def new(
+    challenge_id: Annotated[str, typer.Argument(help="New challenge id and folder name.")],
+    type_: Annotated[
+        str, typer.Option("--type", help="Template type (debug or feature).")
+    ] = "debug",
+    language: Annotated[
+        str, typer.Option("--lang", help="Template language (python or typescript).")
+    ] = "python",
+    json_mode: Annotated[bool, typer.Option("--json", help="Print one JSON document.")] = False,
+) -> None:
+    """Create a runnable authored challenge without building or running it."""
+    try:
+        result = create_challenge(challenge_id, type_=type_, language=language)
+    except AuthoringError as exc:
+        emit_error("environment", str(exc), json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    except KeyboardInterrupt as exc:
+        emit_error("interrupted", "interrupted", json_mode)
+        raise typer.Exit(EXIT_INTERRUPTED) from exc
+    except Exception as exc:
+        emit_error("internal", "scaffold creation failed unexpectedly", json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    emit(result.model_dump(mode="json"), lambda console: _human(console, result), json_mode)

patchground/cli/consent.py

@@ -0,0 +1,77 @@
+"""Explicit pack-review prompting, shared by start, validate and update."""
+
+from collections.abc import Callable
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from patchground.cli.render import emit, stdout_console
+from patchground.packs.models import ConsentRequired, PackReview
+
+
+def literal(value: str, *, multiline: bool = False) -> str:
+    return "".join(
+        char if char.isprintable() or (multiline and char in "\n\t") else f"\\u{ord(char):04x}"
+        for char in value
+    )
+
+
+def show_review(console: Console, review: PackReview) -> None:
+    pack = review.pack
+    console.print(Text(f"UNOFFICIAL pack: {pack.name} {pack.version}"))
+    console.print(Text(f"commit: {pack.commit}"))
+    console.print(Text(f"source: {literal(pack.source)}"))
+    console.print(Text(f"approval identity: {pack.identity}"))
+    if review.previous_commit:
+        console.print(Text(f"previous commit: {review.previous_commit}"))
+        for label, names in (
+            ("added", review.added),
+            ("removed", review.removed),
+            ("changed", review.changed),
+        ):
+            console.print(Text(f"{label}: {', '.join(literal(name) for name in names) or 'none'}"))
+    console.print(Text("All indexed build/run recipes follow; control characters are escaped."))
+    for recipe in review.recipes:
+        console.print(Text(f"Challenge: {recipe.challenge_id}"))
+        console.print(Text(f"Dockerfile: {literal(recipe.dockerfile_path)}"))
+        for line in literal(recipe.dockerfile, multiline=True).split("\n"):
+            console.print(Text("    " + line))
+        console.print(Text(f"Services: {', '.join(literal(s) for s in recipe.services) or 'none'}"))
+        console.print(Text("Command:"))
+        for line in literal(recipe.command, multiline=True).split("\n"):
+            console.print(Text("    " + line))
+    console.print(
+        Text(
+            "Builds may use the network. Approval covers this exact whole pack revision, "
+            "not future updates. Opening its workspace in your editor can run tooling "
+            "outside Docker."
+        )
+    )
+
+
+def with_consent[T](operation: Callable[[bool, str | None], T], *, yes: bool, json_mode: bool) -> T:
+    try:
+        return operation(yes, None)
+    except ConsentRequired as required:
+        if json_mode:
+            raise
+        show_review(stdout_console(), required.review)
+        try:
+            accepted = typer.confirm("Approve this exact pack revision?", default=False)
+        except (EOFError, typer.Abort) as exc:
+            raise KeyboardInterrupt from exc
+        if not accepted:
+            raise KeyboardInterrupt from None
+        return operation(True, required.review.pack.identity)
+
+
+def emit_required(required: ConsentRequired, json_mode: bool) -> None:
+    emit(
+        {
+            "error": {"kind": "consent_required", "message": str(required)},
+            "review": required.review.model_dump(mode="json"),
+        },
+        lambda console: show_review(console, required.review),
+        json_mode,
+    )

patchground/cli/discovery.py

@@ -0,0 +1,189 @@
+"""`pgnd list` and `pgnd show`: render local challenge discovery; never build or run anything."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.text import Text
+from typer.core import TyperCommand
+
+from patchground.cli.render import (
+    EXIT_ERROR,
+    EXIT_FAILED,
+    EXIT_INTERRUPTED,
+    EXIT_OK,
+    emit,
+    emit_error,
+)
+from patchground.packs import (
+    ChallengeDetails,
+    DiscoveryError,
+    DiscoveryFilters,
+    DiscoveryResult,
+    discover_challenges,
+)
+from patchground.packs.builtin import builtin_root, is_builtin_path
+from patchground.packs.execution import InstalledDiscoveryResult
+from patchground.packs.models import PackError
+from patchground.packs.registry import discover_installed, show_reference
+from patchground.spec import ChallengeType, Difficulty
+
+Result = DiscoveryResult | ChallengeDetails
+JsonOption = Annotated[bool, typer.Option("--json", help="Print one JSON document.")]
+
+# Challenge text is untrusted: drop terminal control sequences before it reaches a terminal.
+_CONTROL = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+
+
+def _clean(value: str) -> str:
+    return _CONTROL.sub("", value)
+
+
+class DiscoveryCommand(TyperCommand):
+    """Keep argument-parsing failures inside the one-JSON-document contract under ``--json``."""
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        json_mode = "--json" in args
+        try:
+            return super().parse_args(ctx, args)
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            if not json_mode:
+                raise
+            emit_error("environment", "invalid command arguments", True)
+            raise typer.Exit(EXIT_ERROR) from exc
+
+
+def _human_list(console: Console, result: DiscoveryResult) -> None:
+    if result.challenges and is_builtin_path(Path(result.directory)):
+        console.print(Text("Built-in challenges. Start one with: pgnd start <id>", style="dim"))
+    if not result.challenges and not result.invalid:
+        console.print(Text(f"no challenges found in {_clean(result.directory)}"))
+        if not isinstance(result, InstalledDiscoveryResult) and builtin_root() is not None:
+            console.print(
+                Text("Challenges ship with Patchground. To see them:  pgnd list --builtin")
+            )
+            console.print(Text("Start one by ID, e.g.:  pgnd start pagination-last-page"))
+            console.print(Text("Or write your own:  pgnd new my-challenge"))
+    for item in result.challenges:
+        line = Text()
+        line.append(_clean(getattr(item, "reference", item.id)), style="bold")
+        line.append(f"  {item.type.value}  {item.difficulty.value}  {item.timebox_minutes}m")
+        line.append(f"  {_clean(', '.join(item.languages))}")
+        console.print(line)
+        console.print(Text(f"    {_clean(item.title)}"))
+        if not is_builtin_path(Path(item.path)):
+            console.print(Text(f"    {_clean(item.path)}", style="dim"))
+    for bad in result.invalid:
+        console.print(Text(f"invalid: {_clean(bad.path)}", style="bold red"))
+        for issue in bad.issues:
+            console.print(Text(f"    {_clean(issue)}"))
+
+
+def _human_show(console: Console, result: ChallengeDetails) -> None:
+    if not result.valid or result.challenge is None:
+        console.print(Text(f"invalid: {_clean(result.path)}", style="bold red"))
+        for issue in result.issues:
+            console.print(Text(f"    {_clean(issue)}"))
+        return
+    item = result.challenge
+    console.print(Text(f"{_clean(item.title)} ({_clean(item.id)} {_clean(item.version)})"))
+    rows = [
+        ("type", item.type.value),
+        ("difficulty", item.difficulty.value),
+        ("timebox", f"{item.timebox_minutes} minutes"),
+        ("ai policy", item.ai_policy.value),
+        ("languages", ", ".join(item.languages)),
+        ("tags", ", ".join(item.tags) or "-"),
+        ("hints", str(result.hint_count or 0)),
+        ("author", result.author or "-"),
+        ("license", result.content_license or "-"),
+        ("path", item.path),
+    ]
+    for label, value in rows:
+        console.print(Text(f"{label:<11} {_clean(value)}"))
+    console.print(Text(_clean(item.summary)))
+    console.print(Text(""))
+    console.print(Text(_clean(result.ticket or "")))
+
+
+def _human(console: Console, result: Result) -> None:
+    if isinstance(result, DiscoveryResult):
+        _human_list(console, result)
+    else:
+        _human_show(console, result)
+
+
+def _invoke(call: Callable[[], Result], json_mode: bool) -> None:
+    try:
+        result = call()
+    except (DiscoveryError, PackError) as exc:
+        emit_error("environment", str(exc), json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    except KeyboardInterrupt as exc:
+        emit_error("interrupted", "interrupted", json_mode)
+        raise typer.Exit(EXIT_INTERRUPTED) from exc
+    except Exception as exc:
+        # Exception text could quote challenge content; keep it out of the output.
+        emit_error("internal", "discovery failed unexpectedly", json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    emit(result.model_dump(mode="json"), lambda console: _human(console, result), json_mode)
+    failed = bool(result.invalid) if isinstance(result, DiscoveryResult) else not result.valid
+    raise typer.Exit(EXIT_FAILED if failed else EXIT_OK)
+
+
+def list_challenges(
+    directory: Annotated[
+        Path | None,
+        typer.Argument(help="Folder whose immediate subfolders are challenges (default: here)."),
+    ] = None,
+    installed: Annotated[
+        bool, typer.Option("--installed", help="List installed pack challenges.")
+    ] = False,
+    builtin: Annotated[
+        bool,
+        typer.Option("--builtin", help="List the curated challenges shipped with Patchground."),
+    ] = False,
+    type_: Annotated[
+        ChallengeType | None, typer.Option("--type", help="Only this challenge type.")
+    ] = None,
+    lang: Annotated[str | None, typer.Option("--lang", help="Only this language.")] = None,
+    difficulty: Annotated[
+        Difficulty | None, typer.Option("--difficulty", help="Only this difficulty.")
+    ] = None,
+    tag: Annotated[str | None, typer.Option("--tag", help="Only challenges with this tag.")] = None,
+    json_mode: JsonOption = False,
+) -> None:
+    """List challenges (here, built-in or installed) and report invalid ones; nothing runs."""
+    filters = DiscoveryFilters(type=type_, lang=lang, difficulty=difficulty, tag=tag)
+    if sum((installed, builtin, directory is not None)) > 1:
+        emit_error("environment", "choose one of a directory, --builtin or --installed", json_mode)
+        raise typer.Exit(EXIT_ERROR)
+    bundled = builtin_root()
+    if builtin and bundled is None:
+        emit_error("environment", "this installation has no built-in challenges", json_mode)
+        raise typer.Exit(EXIT_ERROR)
+
+    def discover() -> Result:
+        if installed:
+            return discover_installed(filters)
+        return discover_challenges(bundled if builtin else directory, filters)
+
+    _invoke(discover, json_mode)
+
+
+def show(
+    path: Annotated[
+        str,
+        typer.Argument(help="Local folder, built-in ID, installed ID or pack-name:challenge-id."),
+    ],
+    json_mode: JsonOption = False,
+) -> None:
+    """Show a local challenge's metadata and ticket; never the solution or hidden checks."""
+    _invoke(lambda: show_reference(path), json_mode)