code2okf 0.1.0__py3-none-any.whl

code2okf/kit/spec.yaml

@@ -0,0 +1,312 @@
+---
+schemaVersion: "2"
+kind: sandbox
+name: code2okf
+displayName: Pi kit
+description: >
+  Runs the Pi terminal coding agent in a Docker Sandbox microVM, configured for
+  OpenRouter and proxy-managed API credentials.
+
+sandbox:
+  image: "docker/sandbox-templates:shell-docker"
+  # Model and provider come from the kit's own config (files/home/.pi/agent/
+  # settings.json + models.json), delivered to ~/.pi/agent/ in the VM. No
+  # --provider/--model flags here — Pi resolves defaults from settings.json.
+  entrypoint:
+    - sh
+    - -c
+    - |
+      set -eu
+      mount_state_status=0
+      sh "$HOME/.local/lib/code2okf/mount-state.sh" \
+        "$HOME/.pi/agent/sessions" sessions || mount_state_status=$?
+      if [ "${mount_state_status}" -ne 0 ]; then
+        echo "code2okf: could not relocate Pi sessions onto state; refusing to start pi" >&2
+        exit "${mount_state_status}"
+      fi
+      exec pi "$@"
+    - code2okf-entrypoint
+
+# The AI profile Pi reads, and the text appended to it.
+agentInstructions:
+  filename: AGENTS.md
+  content: |
+    ## Sandbox environment
+    You are Pi running inside a Docker Sandbox microVM. Your workspace is the
+    OKF wiki itself, mounted read-write, and edits apply directly to the host
+    working tree. Four more host paths are mounted:
+
+    - `../md/` — read-only source documents
+    - `../scripts/` — read-only, the projects behind the CLIs listed below
+    - `../SPEC.md` — read-only, the OKF specification
+    - `$CODE2OKF_STATE_DIR/sessions` — writable persistent state for Pi sessions
+
+    Nothing else from the user's project is mounted, so no other file of theirs
+    is visible or reachable — not the repository, not its history, not its
+    configuration. Pi writes sessions to its native `~/.pi/agent/sessions`
+    path, which is bind-mounted onto `$CODE2OKF_STATE_DIR/sessions`. A write
+    anywhere outside the wiki and state directory either fails or lands in the
+    VM's own filesystem and is lost when the sandbox is removed.
+
+    `sudo` is passwordless. If a host is blocked by policy, ask the user to allow
+    it with `sbx policy allow network "<host>"`.
+
+    ## Installed tools
+    These commands are on PATH. Use them; do not reinstall them.
+
+    - `curl`, `fdfind` (fd; Ubuntu package `fd-find`), `jq`, `python3`,
+      `rg` (ripgrep), `shellcheck`, `tree`
+    - `okfctl` — OKF bundle tool: validate, lint, analyze, and the authoring
+      verbs (the curate-okf skill covers it)
+    - `markdownlint-cli2`, `cspell` — Markdown and spelling
+    - `ruff`, `yamllint` — Python and YAML
+    - `inspectmd` — Markdown heading map (line ranges and word counts)
+    - `inspectokf` — wiki directory tree (via `tree`)
+    - `sizeokf` — Markdown content word counts, excluding frontmatter
+    - `merkleokf` — wiki Merkle hash tree, for change detection
+    - `mq` — jq-like query/filter tool for Markdown (https://mqlang.org)
+
+# Outbound egress allowlist. Default-deny: every host the kit reaches must be
+# listed. Pointing Pi at a different provider means adding its host here too —
+# see "Using another provider" in the README.
+permissions:
+  network:
+    allow:
+      # Model API. Must match credentials[].apiKey.inject[].domain exactly.
+      - "openrouter.ai"
+      # Pi service bootstrap.
+      - "pi.dev"
+      # npm: pi-coding-agent, markdownlint-cli2, cspell.
+      - "registry.npmjs.org:443"
+      # uv tool install: ruff, yamllint (index + wheels).
+      - "pypi.org:443"
+      - "files.pythonhosted.org:443"
+      # apt-get update refreshes every template source, so all of them must
+      # be reachable: Ubuntu amd64 (archive/security), arm64 (ports), and
+      # Docker's apt repo (pre-added by shell-docker).
+      - "archive.ubuntu.com:80"
+      - "security.ubuntu.com:80"
+      - "ports.ubuntu.com:80"
+      - "download.docker.com:443"
+      # mq and okfctl release binaries: github.com redirects to a GitHub CDN
+      # host. Today that is objects.githubusercontent.com; release-assets is
+      # also used for release downloads and must stay allowlisted.
+      - "github.com:443"
+      - "objects.githubusercontent.com:443"
+      - "release-assets.githubusercontent.com:443"
+      # mq docs and language reference, for the agent to consult at runtime.
+      - "mqlang.org/book/"
+      # Context7 docs API (native @upstash/context7-pi extension).
+      - "context7.com:443"
+
+# Credentials declare WHAT the kit needs and how the proxy injects it — not
+# where it lives on the host (that comes from the user bindings / host env).
+# proxyManaged: true sets OPENROUTER_API_KEY inside the container as a
+# proxy-managed sentinel (replaces the v1 environment.proxyManaged list).
+credentials:
+  - service: openrouter
+    apiKey:
+      name: OPENROUTER_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: openrouter.ai
+          header: Authorization
+          format: "Bearer %s"
+
+# Runs once at sandbox create, in order, via `sh -c`. `user` defaults to root
+# ("0"); "1000" is the agent.
+setup:
+  install:
+    # Distro CLI tools the agent shells out to.
+    - command: |
+        set -eu
+        apt-get update
+        apt-get install -y \
+          curl \
+          fd-find \
+          jq \
+          python3 \
+          ripgrep \
+          shellcheck \
+          tree
+      description: Install distro CLI tools
+
+    # npm through the sandbox proxy is flaky: pin, one socket, 10-minute fetch,
+    # five attempts. `npm config` writes ~/.npmrc, so later npm steps inherit it.
+    - command: |
+        set -eu
+        PI_VERSION=0.85.1
+
+        npm config set proxy "$HTTP_PROXY"
+        npm config set https-proxy "$HTTP_PROXY"
+
+        npm_install_retry() {
+          pkg=$1
+          attempt=1
+          until npm install -g --ignore-scripts --maxsockets=1 \
+            --fetch-timeout=600000 "$pkg"
+          do
+            if [ "$attempt" -ge 5 ]; then
+              echo "${pkg} install failed after ${attempt} attempts" >&2
+              exit 1
+            fi
+            echo "${pkg} install failed (attempt ${attempt}/5), retrying..."
+            attempt=$((attempt + 1))
+            sleep 5
+          done
+        }
+
+        npm_install_retry "@earendil-works/pi-coding-agent@${PI_VERSION}"
+      user: "1000"
+      description: Configure npm proxy and install Pi
+
+    - command: npm install --global markdownlint-cli2@0.23.2 cspell@10.0.1
+      user: "1000"
+      description: Install Markdown and spelling linters
+
+    - command: |
+        set -eu
+        uv tool install ruff@0.16.2
+        uv tool install yamllint@1.38.0
+      user: "1000"
+      description: Install Python linters
+
+    # No apt/uv/npm package; fetched as a pinned, checksummed release binary.
+    - command: |
+        set -eu
+        MQ_VERSION=0.8.2
+
+        case "$(uname -m)" in
+          x86_64) MQ_TARGET=x86_64-unknown-linux-gnu ;;
+          aarch64) MQ_TARGET=aarch64-unknown-linux-gnu ;;
+          *)
+            echo "mq: unsupported architecture: $(uname -m)" >&2
+            exit 1
+            ;;
+        esac
+
+        tmp=$(mktemp -d)
+        base="https://github.com/harehare/mq/releases/download/v${MQ_VERSION}"
+        curl -fsSL -o "$tmp/mq" "${base}/mq-${MQ_TARGET}"
+        curl -fsSL -o "$tmp/checksums.txt" "${base}/checksums.txt"
+
+        expected=$(awk -v f="mq-${MQ_TARGET}/mq-${MQ_TARGET}" '$2 == f { print $1 }' \
+          "$tmp/checksums.txt")
+        actual=$(sha256sum "$tmp/mq" | awk '{ print $1 }')
+        if [ -z "$expected" ] || [ "$expected" != "$actual" ]; then
+          echo "mq: checksum mismatch for ${MQ_TARGET}" >&2
+          exit 1
+        fi
+
+        mkdir -p "$HOME/.local/bin"
+        install -m 0755 "$tmp/mq" "$HOME/.local/bin/mq"
+        rm -rf "$tmp"
+      user: "1000"
+      description: Install mq (Markdown query tool)
+
+    # Same story as mq, one release archive rather than a bare binary. The
+    # checksums.txt second column is a plain filename here, so the awk match is
+    # on the archive name. Only okfctl is extracted: the archive also carries
+    # okfctl-search, whose semantic index needs a model download from a host
+    # that is not allowlisted.
+    - command: |
+        set -eu
+        OKFCTL_VERSION=0.4.0
+
+        case "$(uname -m)" in
+          x86_64) OKFCTL_ARCH=amd64 ;;
+          aarch64) OKFCTL_ARCH=arm64 ;;
+          *)
+            echo "okfctl: unsupported architecture: $(uname -m)" >&2
+            exit 1
+            ;;
+        esac
+
+        tmp=$(mktemp -d)
+        archive="okfctl_${OKFCTL_VERSION}_linux_${OKFCTL_ARCH}.tar.gz"
+        base="https://github.com/cwest/okfctl/releases/download/v${OKFCTL_VERSION}"
+        curl -fsSL -o "$tmp/$archive" "${base}/${archive}"
+        curl -fsSL -o "$tmp/checksums.txt" "${base}/checksums.txt"
+
+        expected=$(awk -v f="$archive" '$2 == f { print $1 }' "$tmp/checksums.txt")
+        actual=$(sha256sum "$tmp/$archive" | awk '{ print $1 }')
+        if [ -z "$expected" ] || [ "$expected" != "$actual" ]; then
+          echo "okfctl: checksum mismatch for ${archive}" >&2
+          exit 1
+        fi
+
+        tar -xzf "$tmp/$archive" -C "$tmp" okfctl
+        mkdir -p "$HOME/.local/bin"
+        install -m 0755 "$tmp/okfctl" "$HOME/.local/bin/okfctl"
+        rm -rf "$tmp"
+      user: "1000"
+      description: Install okfctl (OKF bundle tool)
+
+    # Native Pi package (not MCP): tools + context7-docs skill under ~/.pi/agent/npm/.
+    - command: |
+        set -eu
+        CONTEXT7_PI_VERSION=0.1.2
+        pi install "npm:@upstash/context7-pi@${CONTEXT7_PI_VERSION}"
+      user: "1000"
+      description: Install Context7 Pi extension
+
+    # Static files/home/ copies do not reliably preserve the git 100755 bit;
+    # set it explicitly so the compile-okf skill can invoke the wrapper.
+    - command: |
+        set -eu
+        scripts=/home/agent/.pi/agent/skills/compile-okf/scripts
+        chmod 0755 "$scripts/check-okf.sh"
+      description: Make the compile-okf check script executable
+
+  # Bind mounts do not survive a sandbox stop. The startup hook covers normal
+  # starts and sbx exec; the entrypoint above is a second required call site for
+  # starts where the hook is not replayed. The helper is idempotent.
+  startup:
+    - command:
+        - sh
+        - -c
+        - |
+          set -eu
+          HOME="${HOME:-/home/agent}"
+          export HOME
+          sh "$HOME/.local/lib/code2okf/mount-state.sh" \
+            "$HOME/.pi/agent/sessions" sessions
+      user: "agent"
+      description: Bind-mount Pi sessions onto persistent state
+
+  # Workspace is not mounted during setup.install, so the CLIs are shims that
+  # resolve from ${WORKDIR} — the workspace path — rather than from a copy
+  # (always tracks the tree). ${WORKDIR} is the wiki, and the projects sit in
+  # the scripts/ mount beside it, hence the dirname.
+  files:
+    - path: /home/agent/.local/bin/inspectmd
+      mode: "0755"
+      description: Workspace-backed inspectmd CLI
+      content: |
+        #!/bin/sh
+        set -eu
+        exec uv tool run --from "$(dirname "${WORKDIR}")/scripts/inspectmd" inspectmd "$@"
+
+    - path: /home/agent/.local/bin/inspectokf
+      mode: "0755"
+      description: Workspace-backed inspectokf CLI
+      content: |
+        #!/bin/sh
+        set -eu
+        exec uv tool run --from "$(dirname "${WORKDIR}")/scripts/inspectokf" inspectokf "$@"
+
+    - path: /home/agent/.local/bin/sizeokf
+      mode: "0755"
+      description: Workspace-backed sizeokf CLI
+      content: |
+        #!/bin/sh
+        set -eu
+        exec uv tool run --from "$(dirname "${WORKDIR}")/scripts/sizeokf" sizeokf "$@"
+
+    - path: /home/agent/.local/bin/merkleokf
+      mode: "0755"
+      description: Workspace-backed merkleokf CLI
+      content: |
+        #!/bin/sh
+        set -eu
+        exec uv tool run --from "$(dirname "${WORKDIR}")/scripts/merkleokf" merkleokf "$@"

code2okf/resources.py

@@ -0,0 +1,74 @@
+"""Locate the kit, the OKF spec, and the helper CLI sources this package ships.
+
+Prefers the installed package's own bundled copies (importlib.resources);
+falls back to the checkout's layout so `uv run code2okf` works with no build
+step. The checkout fallback is a second code path and is tested on its own.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+# src/code2okf/resources.py -> parents[0]=src/code2okf, [1]=src, [2]=repo root.
+_CHECKOUT_ROOT = Path(__file__).resolve().parents[2]
+
+
+class ResourcesError(Exception):
+    """code2okf cannot locate its own kit, spec, or helper CLI sources."""
+
+
+def _installed_root() -> Path | None:
+    """The installed package's own directory, if it carries a bundled kit.
+
+    A checkout (this package imported via `pythonpath`, with no wheel build)
+    has no ``kit/`` sibling next to ``resources.py``, so this returns None and
+    every lookup below falls back to the checkout's own layout.
+    """
+    try:
+        candidate = Path(str(files("code2okf")))
+    except (ModuleNotFoundError, TypeError):
+        return None
+    if (candidate / "kit").is_dir():
+        return candidate
+    return None
+
+
+def _checkout_path(relative: str, what: str) -> Path:
+    """The checkout fallback location for `relative`, verified to exist.
+
+    A released wheel carries the kit, the spec and the CLI sources, so
+    _installed_root finds them and this path is never taken. It is reached
+    from a checkout (`uv run code2okf`), and by an install built without those
+    assets -- where __file__ resolves under site-packages and a silent
+    parents[2] would compute a path that cannot ever exist, leaving every
+    caller downstream to report a generic "not a file" with no clue why.
+    Fail here instead, with the actual cause.
+    """
+    candidate = _CHECKOUT_ROOT / relative
+    if not candidate.exists():
+        raise ResourcesError(
+            f"cannot locate {what} ({candidate}). This looks like an installed "
+            "code2okf built without its bundled kit, and not a development "
+            "checkout either. Run from a checkout with `uv run code2okf`, or "
+            "install a release whose wheel carries the kit."
+        )
+    return candidate
+
+
+def kit_dir() -> Path:
+    """The code2okf sandbox kit: the installed ``code2okf/kit``, else ``kits/code2okf``."""
+    root = _installed_root()
+    return root / "kit" if root is not None else _checkout_path("kits/code2okf", "the sandbox kit")
+
+
+def spec_md() -> Path:
+    """The bundled OKF spec: the installed ``code2okf/SPEC.md``, else the checkout's."""
+    root = _installed_root()
+    return root / "SPEC.md" if root is not None else _checkout_path("SPEC.md", "the OKF spec")
+
+
+def clis_dir() -> Path:
+    """The four helper CLI projects: the installed ``code2okf/clis``, else ``scripts/``."""
+    root = _installed_root()
+    return root / "clis" if root is not None else _checkout_path("scripts", "the helper CLI projects")

code2okf/sandbox.py

@@ -0,0 +1,266 @@
+"""The one seam onto the `sbx` CLI.
+
+Every process this package spawns to talk to a sandbox goes through
+:func:`_run` or :class:`Exec` in this module, and nowhere else — so a test
+only ever needs to fake ``subprocess.run``/``subprocess.Popen`` once, at this
+one boundary, to exercise everything above it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+import secrets
+import shutil
+import subprocess
+import sys
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+MIN_VERSION = (0, 43, 0)
+
+# This is the plan's own documented fallback (interface-plan.md, "Risks and
+# open items"), not an invented deviation: which `sbx inspect` field (if any)
+# is a stable sandbox identity is explicitly left unverified there, to be
+# confirmed against a *live* sbx session in stage 3. Stage 2 is offline and
+# has no sandbox to inspect, so it implements the fallback the plan already
+# specifies instead of guessing at stage 3's job: a random token written into
+# the guest at creation and read back on reuse.
+#
+# Threat model: the token is guest-writable, so it is not proof against a
+# guest that deliberately tries to impersonate ownership. It only needs to
+# answer "did *we* create this sandbox" against accidental reuse (a stale
+# sandbox from a prior run, an unrelated sandbox that happens to hold this
+# name) — and resolve_sandbox_state() always compares the *live* token against
+# the one recorded at creation, so a missing or altered token can only cause a
+# false *rejection* (fails safe: exit 2, "sbx rm --force"), never a false
+# acceptance of a sandbox we did not create.
+#
+# Inside the guest VM only — never a host path, so this is not a shared-tmp
+# race on the host. Random per creation (see create()), so a stale file left
+# by an unrelated image could never be mistaken for our own.
+OWNER_TOKEN_PATH = "/tmp/code2okf-owner"  # noqa: S108
+
+
+class SandboxError(Exception):
+    """A checked failure talking to `sbx`."""
+
+
+def _run(argv: list[str], *, stdin: int | None = subprocess.DEVNULL) -> subprocess.CompletedProcess[str]:
+    """Run `argv` and capture it. The only place this module calls subprocess.run."""
+    return subprocess.run(argv, stdin=stdin, capture_output=True, text=True, check=False)  # noqa: S603
+
+
+def present() -> bool:
+    """Whether the `sbx` executable exists on PATH."""
+    return shutil.which("sbx") is not None
+
+
+def version() -> tuple[int, int, int] | None:
+    """Parsed (major, minor, patch) from `sbx version`, or None if unparsable."""
+    result = _run(["sbx", "version"])
+    if result.returncode != 0:
+        return None
+    match = re.search(r"(\d+)\.(\d+)\.(\d+)", result.stdout)
+    if not match:
+        return None
+    major, minor, patch = (int(part) for part in match.groups())
+    return (major, minor, patch)
+
+
+def version_at_least(minimum: tuple[int, int, int] = MIN_VERSION) -> bool:
+    """Whether `sbx version` is at least `minimum`."""
+    found = version()
+    return found is not None and found >= minimum
+
+
+def logged_in() -> bool:
+    """`sbx ls` succeeding is what a logged-in session looks like."""
+    return _run(["sbx", "ls"]).returncode == 0
+
+
+def preflight() -> None:
+    """Check the sbx environment before anything that would shell out to it.
+
+    Every other function in this module assumes `sbx` is on PATH: `_run`
+    calls `subprocess.run(["sbx", ...])` directly, which raises a bare
+    FileNotFoundError (not SandboxError) if it is missing. Callers -- cli.py
+    and `python -m code2okf.sandbox` alike -- must call this first and turn
+    SandboxError into a clean exit, or a missing `sbx` crashes instead.
+    """
+    if not present():
+        raise SandboxError("'sbx' CLI not found in PATH. Install it with: brew install docker/tap/sbx")
+    if not version_at_least():
+        minimum = ".".join(str(part) for part in MIN_VERSION)
+        raise SandboxError(f"sbx must be at least version {minimum}")
+    if not logged_in():
+        raise SandboxError("not logged in to sbx; run `sbx login`")
+
+
+def exists(name: str) -> bool:
+    """Whether a sandbox called `name` currently exists."""
+    result = _run(["sbx", "ls", "-q"])
+    return name in result.stdout.splitlines()
+
+
+@dataclass(frozen=True)
+class Mount:
+    """One `sbx run` workspace argument."""
+
+    path: Path
+    readonly: bool = False
+
+    def as_arg(self) -> str:
+        """The positional argument `sbx run` expects for this mount."""
+        return f"{self.path}:ro" if self.readonly else str(self.path)
+
+
+def create(name: str, kit_dir: Path, mounts: Iterable[Mount], env: dict[str, str]) -> str:
+    """Recreate `name` over `mounts`, and return its fresh owner token.
+
+    Tolerates a prior sandbox by this name not existing, mirroring today's
+    `sbx rm --force ... || true`. Raises SandboxError on any failure from here
+    on — a failed create must leave no ownership marker (see workbench.py).
+    """
+    _run(["sbx", "rm", "--force", name])
+
+    argv = ["sbx", "run", "--detached", "--name", name]
+    for key, value in env.items():
+        argv += ["-e", f"{key}={value}"]
+    argv.append(str(kit_dir))
+    argv += [mount.as_arg() for mount in mounts]
+    result = _run(argv)
+    if result.returncode != 0:
+        raise SandboxError(f"sbx run failed for {name!r}: {result.stderr.strip()}")
+
+    token = secrets.token_hex(16)
+    written = _run(["sbx", "exec", name, "--", "sh", "-c", f"echo {token} >{OWNER_TOKEN_PATH}"])
+    if written.returncode != 0:
+        # sbx run just succeeded, so name now exists but carries no owner
+        # token -- left alone, the next invocation would see it as an
+        # unowned sandbox and demand a manual `sbx rm --force`, even though
+        # we are the ones who just created it moments ago. Clean up after
+        # ourselves instead.
+        _run(["sbx", "rm", "--force", name])
+        raise SandboxError(f"could not record an ownership token in {name!r}: {written.stderr.strip()}")
+    return token
+
+
+def identity(name: str) -> str | None:
+    """The owner token left inside `name` at creation, or None if unreadable.
+
+    None covers both "no such sandbox" and "exists but is not ours" (no token
+    file) — either way, it cannot be recognised as a sandbox we created.
+    """
+    result = _run(["sbx", "exec", name, "--", "cat", OWNER_TOKEN_PATH])
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def remove(name: str) -> None:
+    """Delete the sandbox called `name`. Only call this on one we own."""
+    _run(["sbx", "rm", "--force", name])
+
+
+def probe(name: str, path: Path) -> bool:
+    """A cheap in-VM check that `path` (a workbench mount) is visible in `name`."""
+    return _run(["sbx", "exec", name, "--", "test", "-d", str(path)]).returncode == 0
+
+
+def key_is_proxy_managed(name: str) -> bool:
+    """Whether OPENROUTER_API_KEY inside `name` is the proxy-managed sentinel."""
+    result = _run(["sbx", "exec", name, "--", "sh", "-lc", 'echo "$OPENROUTER_API_KEY"'])
+    return result.returncode == 0 and result.stdout.strip() == "proxy-managed"
+
+
+class Exec:
+    """One streamed `sbx exec`: iterate stdout+stderr lines, then read .returncode."""
+
+    def __init__(self, argv: list[str]) -> None:
+        """Start `argv`, ready to iterate over its combined stdout+stderr."""
+        self.argv = argv
+        self.returncode: int | None = None
+        self._proc = subprocess.Popen(  # noqa: S603
+            argv,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+
+    def __iter__(self) -> Iterator[str]:
+        """Yield each line as it arrives; sets .returncode once exhausted."""
+        assert self._proc.stdout is not None  # noqa: S101
+        for line in self._proc.stdout:
+            yield line.rstrip("\n")
+        self.returncode = self._proc.wait()
+
+    def close(self) -> None:
+        """Best-effort local cleanup, safe to call on an already-finished run.
+
+        Stops the local `sbx exec` conduit so an interrupted run does not
+        leave one behind. Deliberately *only* the local side: `pi` runs
+        inside the VM and killing the conduit does not reap it, and remote
+        process reaping is out of scope (see the plan's deferred items).
+        """
+        if self._proc.poll() is None:
+            with contextlib.suppress(OSError):
+                self._proc.terminate()
+        if self._proc.stdout is not None:
+            with contextlib.suppress(OSError):
+                self._proc.stdout.close()
+
+
+def exec_stream(name: str, argv: list[str]) -> Exec:
+    """Run `argv` inside `name`, streamed. stdin is always /dev/null — see compile.py."""
+    return Exec(["sbx", "exec", name, "--", *argv])
+
+
+def exec_capture(name: str, argv: list[str]) -> subprocess.CompletedProcess[str]:
+    """Run a short `argv` inside `name` and capture it whole (e.g. a hash check)."""
+    return _run(["sbx", "exec", name, "--", *argv])
+
+
+def _ensure_default_sandbox() -> int:
+    """`python -m code2okf.sandbox`: ensure the code2okf sandbox exists (maintainers).
+
+    Imports workbench lazily: workbench imports this module at its own top
+    level, and by the time this function runs (only from the `__main__`
+    guard below) that import has already completed, so the late import here
+    just retrieves it from sys.modules rather than re-entering it.
+    """
+    from code2okf import workbench
+
+    try:
+        preflight()
+    except SandboxError as exc:
+        print(f"code2okf.sandbox: {exc}", file=sys.stderr)
+        return 2
+
+    wb = workbench.Workbench.default()
+    try:
+        # Same lock a real compile run takes: this helper touches the same
+        # sandbox, so it must not race a concurrent `code2okf` invocation.
+        with workbench.lock():
+            wb.ensure_roots()
+            state = workbench.ensure_sandbox(wb)
+    except workbench.LockHeld:
+        print("code2okf.sandbox: another code2okf run is using the sandbox; try again later", file=sys.stderr)
+        return 2
+    except (
+        workbench.UnsafeLockFile,
+        workbench.UnownedSandboxError,
+        workbench.KeyNotProxyManagedError,
+        SandboxError,
+    ) as exc:
+        print(f"code2okf.sandbox: {exc}", file=sys.stderr)
+        return 2
+    print(f"code2okf.sandbox: sandbox {workbench.SANDBOX_NAME!r} {state}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_ensure_default_sandbox())