code2okf 0.1.0__py3-none-any.whl

code2okf/clis/sizeokf/src/sizeokf/sizes.py

@@ -0,0 +1,155 @@
+"""Measure Markdown content size, excluding YAML frontmatter.
+
+Only ``*.md`` files count. A file's size is the number of whitespace-split words
+after its leading frontmatter block is removed. A directory's size is the sum
+over every Markdown file beneath it, recursively.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def strip_frontmatter(text: str) -> str:
+    """Return ``text`` without its leading YAML frontmatter block.
+
+    The block must open on the very first line with exactly ``---`` and close on
+    a later line that is also exactly ``---``; the body is everything after the
+    closing line, so a blank line following it still counts. Text with no such
+    block — including an *unterminated* one — is returned unchanged, which is
+    the same rule ``inspectmd`` applies when mapping headings.
+    """
+    if text.startswith(""):
+        text = text[1:]
+
+    if not text.startswith("---"):
+        return text
+
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return text
+
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            return "".join(lines[i + 1 :])
+    return text
+
+
+def count_words(text: str) -> int:
+    """Count whitespace-separated tokens in ``text``."""
+    return len(text.split())
+
+
+@dataclass(frozen=True)
+class Entry:
+    """One listed file or directory, with its content size."""
+
+    path: str
+    """Display path, rooted at the walk target's name. Directories end in ``/``."""
+
+    is_dir: bool
+    words: int
+    """Whitespace-split words of Markdown content, frontmatter excluded. Recursive for directories."""
+
+    files: int
+    """Number of Markdown files counted. Always 1 for a file."""
+
+    depth: int
+    """1 for entries directly inside the root; 0 for the root itself."""
+
+
+def _measure_file(path: Path) -> int:
+    """Words of content in one Markdown file, frontmatter excluded.
+
+    A file that cannot be read is reported on stderr and counted as zero rather
+    than aborting the walk — one unreadable page must not cost the rest.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        print(f"sizeokf: skipping {path}: {exc}", file=sys.stderr)
+        return 0
+    return count_words(strip_frontmatter(text))
+
+
+def collect(
+    root: Path, *, max_level: int | None = None, nolog: bool = False
+) -> tuple[list[Entry], Entry]:
+    """Walk ``root``, returning ``(listed_entries, root_total)``.
+
+    ``listed_entries`` always includes ``root_total``. Every directory total is
+    recursive regardless of ``max_level``; the level only decides which non-root
+    entries get listed. ``max_level=0`` lists only the walk root; ``max_level=1``
+    lists the entries directly inside ``root``, matching ``inspectokf -L 1``.
+
+    When ``nolog`` is true, ``okf/log.md`` is omitted entirely (not listed and
+    not counted). Nested ``log.md`` files and ``log.md`` under other roots are
+    still measured.
+    """
+    entries: list[Entry] = []
+    prefix = f"{root.name}/"
+
+    def walk(directory: Path, depth: int) -> tuple[int, int]:
+        """Return ``(words, files)`` for ``directory``, recording listed entries."""
+        words = files = 0
+        try:
+            children = sorted(directory.iterdir(), key=lambda p: p.name)
+        except OSError as exc:
+            # Same skip policy as an unreadable file: warn and contribute zero.
+            print(f"sizeokf: skipping {directory}: {exc}", file=sys.stderr)
+            return 0, 0
+
+        for child in children:
+            try:
+                # is_dir() follows symlinks; skip them so cycles and links
+                # outside root cannot be scanned.
+                if child.is_symlink():
+                    continue
+                is_directory = child.is_dir()
+            except OSError as exc:
+                print(f"sizeokf: skipping {child}: {exc}", file=sys.stderr)
+                continue
+
+            if is_directory:
+                child_words, child_files = walk(child, depth + 1)
+                words += child_words
+                files += child_files
+                if max_level is None or depth <= max_level:
+                    entries.append(
+                        Entry(
+                            path=f"{prefix}{child.relative_to(root)}/",
+                            is_dir=True,
+                            words=child_words,
+                            files=child_files,
+                            depth=depth,
+                        )
+                    )
+            elif child.suffix == ".md":
+                # Anchored to the walk root, not to any directory named "okf":
+                # a nested okf/ keeps its own log.md, as the docstring promises.
+                if nolog and child.name == "log.md" and root.name == "okf" and child.parent == root:
+                    continue
+                child_words = _measure_file(child)
+                words += child_words
+                files += 1
+                if max_level is None or depth <= max_level:
+                    entries.append(
+                        Entry(
+                            path=f"{prefix}{child.relative_to(root)}",
+                            is_dir=False,
+                            words=child_words,
+                            files=1,
+                            depth=depth,
+                        )
+                    )
+        return words, files
+
+    total_words, total_files = walk(root, 1)
+    total = Entry(path=prefix, is_dir=True, words=total_words, files=total_files, depth=0)
+    entries.append(total)
+
+    # Largest first; ties broken by path so repeated runs are byte-identical.
+    entries.sort(key=lambda e: (-e.words, e.path))
+    return entries, total

code2okf/compile.py

@@ -0,0 +1,267 @@
+"""Document resolution and the Ralph loop.
+
+The prompts, the loop, the cap and `merkleokf --nolog -L 0` as the convergence
+check are carried over from the retired scripts/compile-okf.sh (see the git
+history for the original, and .claude/plans/interface-plan.md for why each
+rule is what it is).
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from code2okf import events, sandbox, workbench
+
+DEFAULT_MAX_ITERATIONS = 10
+
+COMPILE_PROMPT = (
+    "Load the compile-okf skill: read ~/.pi/agent/skills/compile-okf/SKILL.md, "
+    "then follow it to compile {document} directly into the workspace root. "
+    "You are already in the OKF wiki; never create an okf/ child directory."
+)
+# Appended on Ralph loop iterations after the first, so Pi knows it may be
+# resuming unfinished work rather than starting the document over.
+CONTINUATION_PROMPT = (
+    "This is a follow-up pass on this document: the wiki may already hold "
+    "partial work from a previous pass. Compare the source against what is "
+    "on disk and continue at the first gap -- do not start over."
+)
+
+_HASH_RE = re.compile(r"^[0-9a-f]+$")
+
+# How much of pi's raw output to fold into a CompileError on a non-zero exit.
+# Bounded so one runaway session can't blow up an error message, generous
+# enough that the actual cause (a traceback, sbx's own diagnostic text) is
+# almost always still in view.
+_DIAGNOSTIC_TAIL_LINES = 20
+
+
+def _diagnostic_tail(raw_lines: list[str]) -> str:
+    """The last few non-JSON lines, for folding into a failure message.
+
+    Pi's own protocol events are JSON objects and say nothing useful about
+    why a run died; what does is whatever arrived on stderr in plain text
+    (a traceback, an sbx diagnostic), merged into the same stream. Keeping
+    only those makes the message the cause rather than a wall of envelopes.
+    """
+    meaningful = [line for line in raw_lines if line.strip() and not line.lstrip().startswith("{")]
+    return "\n".join(meaningful[-_DIAGNOSTIC_TAIL_LINES:])
+
+
+class UsageError(Exception):
+    """A problem decided before any work starts -- exit 2."""
+
+
+class CompileError(Exception):
+    """A run failure once compiling has started -- exit 1."""
+
+    def __init__(self, message: str, *, document: str | None = None) -> None:
+        """Fold `document` into the message itself, so naming it is not optional.
+
+        str(exc) is what every caller actually prints; a document recorded
+        only on a separate attribute is a document that silently never
+        reaches the user, which is exactly what the plan's "exit 1 naming
+        the document" contract requires.
+        """
+        self.document = document
+        super().__init__(f"{message} ({document})" if document else message)
+
+
+@dataclass(frozen=True)
+class Document:
+    """One document to compile, resolved from a CLI positional argument."""
+
+    display: str
+    """Printed verbatim in TSV rows -- the path as supplied, or "-" for stdin."""
+
+    basename: str
+    """The name it is staged under in work/md."""
+
+    stdin: bool = False
+
+
+@dataclass(frozen=True)
+class Row:
+    """One TSV output row: path, iterations, hash-before, hash-after."""
+
+    path: str
+    iterations: int
+    hash_before: str
+    hash_after: str
+
+    def as_tsv(self) -> str:
+        """Render as the one TSV line this document contributes to stdout."""
+        return f"{self.path}\t{self.iterations}\t{self.hash_before}\t{self.hash_after}"
+
+
+def _check_display_path(display: str) -> None:
+    """A tab or newline in a TSV row's path column would corrupt the row."""
+    if "\t" in display or "\n" in display:
+        raise UsageError(f"path contains a tab or newline: {display!r}")
+
+
+def resolve_documents(
+    paths: list[str], *, stdin_is_tty: Callable[[], bool] = lambda: sys.stdin.isatty()
+) -> list[Document]:
+    """Resolve CLI positionals into documents, per the input contract.
+
+    "-" or no arguments means stdin (refused on a TTY, via UsageError); a
+    directory means its *.md, sorted, non-recursive; duplicate arguments are
+    kept, in the order given, never de-duplicated; two different sources that
+    would stage under the same basename is a UsageError.
+    """
+    raw_paths = paths or ["-"]
+    if raw_paths.count("-") > 1:
+        raise UsageError("only one '-' (stdin) may be given")
+
+    docs: list[Document] = []
+    for raw in raw_paths:
+        if raw == "-":
+            if stdin_is_tty():
+                raise UsageError("refusing to read from a terminal; pipe input or name a file")
+            docs.append(Document(display="-", basename="stdin.md", stdin=True))
+            continue
+        _check_display_path(raw)
+        path = Path(raw)
+        workbench.reject_if_unsafe(path, what="an input path")
+        if path.is_dir():
+            for md in sorted(path.glob("*.md")):
+                # Checked individually, same as the directory argument above:
+                # a symlinked or tab/newline-carrying *.md discovered inside
+                # it must be rejected up front (exit 2), not surface later as
+                # a staging failure or a corrupted TSV row.
+                workbench.reject_if_unsafe(md, what="an input path")
+                display = str(md)
+                _check_display_path(display)
+                docs.append(Document(display=display, basename=md.name))
+        elif path.is_file():
+            docs.append(Document(display=raw, basename=path.name))
+        else:
+            raise UsageError(f"not a file or directory: {raw}")
+
+    seen: dict[str, str] = {}
+    for doc in docs:
+        if doc.basename in seen and seen[doc.basename] != doc.display:
+            raise UsageError(
+                f"two different inputs would both stage as {doc.basename!r}: "
+                f"{seen[doc.basename]!r} and {doc.display!r}"
+            )
+        seen[doc.basename] = doc.display
+
+    if not docs:
+        raise UsageError("no documents to compile")
+    return docs
+
+
+def stage_items(documents: Iterable[Document]) -> list[tuple[str, Path | bytes]]:
+    """(basename, source) pairs for workbench.stage_inputs, reading stdin now."""
+    items: list[tuple[str, Path | bytes]] = []
+    for doc in documents:
+        items.append((doc.basename, sys.stdin.buffer.read()) if doc.stdin else (doc.basename, Path(doc.display)))
+    return items
+
+
+def _parse_hash(output: str) -> str:
+    lines = output.splitlines()
+    if len(lines) < 3 or not lines[2].split():
+        raise CompileError(f"merkleokf produced no root row: {output!r}")
+    digest = lines[2].split()[0]
+    if not _HASH_RE.match(digest):
+        raise CompileError(f"merkleokf produced a malformed hash: {digest!r}")
+    return digest
+
+
+def wiki_root_hash(name: str, work_okf: Path) -> str:
+    """The wiki root's hash, validated -- a missing or malformed hash is never convergence."""
+    result = sandbox.exec_capture(name, ["merkleokf", "--nolog", "-L", "0", str(work_okf)])
+    if result.returncode != 0:
+        raise CompileError(f"merkleokf failed: {result.stderr.strip()}")
+    return _parse_hash(result.stdout)
+
+
+def compile_document(
+    name: str,
+    doc: Document,
+    wb: workbench.Workbench,
+    output_dir: Path,
+    max_iterations: int = DEFAULT_MAX_ITERATIONS,
+    *,
+    on_progress: Callable[[str], None] | None = None,
+    on_event: Callable[[str], None] | None = None,
+) -> Row:
+    """Run the Ralph loop for one document.
+
+    Re-runs Pi on the same document until merkleokf --nolog -L 0 reports an
+    unchanged wiki root hash, capped at max_iterations. Mirrors work_okf out
+    to output_dir after every iteration, so an interruption leaves the last
+    completed pass on disk. A hash-stable first pass is convergence, not
+    failure -- iterations=1, equal hashes.
+    """
+    document_path = wb.work_md / doc.basename
+    hash_before = wiki_root_hash(name, wb.work_okf)
+    had_markdown_before = workbench.has_markdown(wb.work_okf)
+
+    iteration = 0
+    current_hash = hash_before
+    while True:
+        iteration += 1
+        if iteration > max_iterations:
+            raise CompileError(f"hit {max_iterations} iterations without converging", document=doc.display)
+        if on_progress is not None:
+            on_progress(f"Compiling document {doc.display} (iteration {iteration})")
+
+        prompt = COMPILE_PROMPT.format(document=document_path)
+        if iteration > 1:
+            prompt = f"{prompt} {CONTINUATION_PROMPT}"
+
+        stream = sandbox.exec_stream(name, ["pi", "--mode", "json", prompt])
+        tool_calls = 0
+        raw_lines: list[str] = []
+        try:
+            for line, display, is_tool_call in events.process(stream):
+                raw_lines.append(line)
+                if is_tool_call:
+                    tool_calls += 1
+                # events.process() has already decided what is worth showing:
+                # rendered tool calls and assistant prose, plus any non-JSON
+                # diagnostic. Protocol events we do not render come back as
+                # None and are dropped here.
+                if on_event is not None and display and display.strip():
+                    on_event(display)
+        finally:
+            # Reached on Ctrl-C too, so an interrupted run does not leave the
+            # local `sbx exec` conduit behind. mirror_out() is below this
+            # point, which is what keeps a half-finished iteration from ever
+            # reaching -o DIR.
+            stream.close()
+        if stream.returncode != 0:
+            tail = _diagnostic_tail(raw_lines)
+            detail = f": {tail}" if tail else ""
+            raise CompileError(f"pi exited {stream.returncode}{detail}", document=doc.display)
+        if tool_calls == 0:
+            raise CompileError("pi session made no tool calls -- it did not follow the skill", document=doc.display)
+
+        try:
+            workbench.mirror_out(wb.work_okf, output_dir)
+        except workbench.WorkbenchError as exc:
+            # Re-raised as a CompileError, not left as a WorkbenchError: the
+            # caller's per-document loop only catches CompileError, and a
+            # failed mirror-out is a failed run for *this* document (exit 1),
+            # not a setup problem decided before any work started.
+            raise CompileError(str(exc), document=doc.display) from exc
+
+        next_hash = wiki_root_hash(name, wb.work_okf)
+        if on_progress is not None:
+            on_progress(f"{current_hash} -> {next_hash}")
+        if next_hash == current_hash:
+            break
+        current_hash = next_hash
+
+    if not had_markdown_before and not workbench.has_markdown(wb.work_okf):
+        raise CompileError("the wiki is still empty after compiling", document=doc.display)
+
+    return Row(path=doc.display, iterations=iteration, hash_before=hash_before, hash_after=current_hash)

code2okf/events.py

@@ -0,0 +1,86 @@
+"""Turn Pi's `--mode json` event stream into the host-side progress view.
+
+Replaces the jq filter in the old shell driver
+(the retired `scripts/compile-okf.sh`): the same three cases, the same 120-character
+cut on tool calls.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Iterator
+
+DISPLAY_WIDTH = 120
+
+
+def _load(line: str) -> dict | None:
+    try:
+        event = json.loads(line)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    return event if isinstance(event, dict) else None
+
+
+def _translate_event(event: dict) -> str | None:
+    event_type = event.get("type")
+    if event_type == "tool_execution_start":
+        tool_name = event.get("toolName", "")
+        args = event.get("args", "")
+        return f"{tool_name} {args}"[:DISPLAY_WIDTH]
+
+    if event_type == "message_end":
+        message = event.get("message") or {}
+        if message.get("role") != "assistant":
+            return None
+        parts = []
+        for block in message.get("content") or []:
+            if block.get("type") == "thinking":
+                parts.append(f"[thinking]\n{block.get('thinking', '')}")
+            elif block.get("type") == "text":
+                parts.append(block.get("text", ""))
+        return "\n\n".join(parts) or None
+
+    return None
+
+
+def translate(line: str) -> str | None:
+    """One raw `pi --mode json` line -> the text worth showing, or None.
+
+    A tool call becomes "toolName args" (cut to DISPLAY_WIDTH); an assistant
+    `message_end` becomes its joined text/thinking parts; anything else,
+    including a line that is not JSON, produces nothing.
+    """
+    event = _load(line)
+    return _translate_event(event) if event is not None else None
+
+
+def is_tool_call(line: str) -> bool:
+    """Whether a raw line is a `tool_execution_start` event.
+
+    A session with zero of these did not follow the compile-okf skill (its
+    first two steps are tool calls) -- see compile.py's "did nothing" check.
+    """
+    event = _load(line)
+    return event is not None and event.get("type") == "tool_execution_start"
+
+
+def process(lines: Iterable[str]) -> Iterator[tuple[str, str | None, bool]]:
+    """Yield (raw line, display-or-None, is_tool_call) for each line, in order.
+
+    `display` is what a human should actually see, and the distinction it
+    draws matters in both directions:
+
+    - A line that is **not JSON at all** -- plain stderr text, a traceback
+      merged in from stderr -- is shown verbatim. Dropping these is what
+      left a failing run reporting only "pi exited 1" with no cause.
+    - A line that **is** a Pi protocol event we do not render is dropped.
+      Pi emits a `message_update` envelope per *token*, so showing these
+      floods the terminal with thousands of empty-delta JSON objects and
+      buries the tool calls -v exists to reveal.
+    """
+    for line in lines:
+        event = _load(line)
+        if event is None:
+            yield line, line, False  # not JSON: a diagnostic, worth showing
+            continue
+        yield line, _translate_event(event), event.get("type") == "tool_execution_start"

code2okf/kit/README.md

@@ -0,0 +1,128 @@
+# kits/code2okf
+
+The Docker Sandbox kit that runs Pi. `spec.yaml` declares the image, the network
+allowlist, the credentials and the pinned installs — Pi itself, the linters, and
+the `mq` and `okfctl` release binaries. Everything under
+`files/home/` is copied into the sandbox at `~/`, so `files/home/.pi/agent/`
+becomes Pi's config directory: `AGENTS.md`, `settings.json`, `models.json` and
+`skills/`.
+
+The `files/` level is fixed by the Sandbox Kit schema. It cannot be renamed or
+moved.
+
+Config is copied in when the kit is built, not mounted, so an edit reaches Pi on
+the next fresh sandbox — which `code2okf` builds when the kit changes, or on
+`--fresh`.
+
+## Model configuration
+
+The `openrouter` entry in `files/home/.pi/agent/models.json` names the provider
+and stops there. It carries no `models` array, which is deliberate, and JSON has
+nowhere to put the reason. So here it is. (The `litellm` entry alongside it does
+carry one, for the mirror-image reason — see
+[Using another provider](#using-another-provider).)
+
+Pi merges a custom `models` entry by `id`, and that entry replaces the built-in
+catalogue entry it matches. Name a model Pi already knows, such as `{"id":
+"deepseek/deepseek-v4-pro", "name": "…"}`, and you throw its real metadata away.
+What you get instead are Pi's defaults: 128K context, 16,384 max output tokens,
+no reasoning. That output cap cuts a long `write` call off mid-argument and
+takes the run down with it. Leave the array out and the catalogue values apply:
+1M context, 384K max output.
+
+Check after any change:
+
+```bash
+sbx exec code2okf -- pi --list-models deepseek
+```
+
+To change a single field of a catalogue model, use `modelOverrides`, not a
+`models` entry. And avoid `deepseek/deepseek-v4-flash` for this work: the
+catalogue caps its output at 4.1K.
+
+## Using another provider
+
+`models.json` carries a second provider, `litellm`, switched off by default. It
+points at a LiteLLM gateway, or at anything else that speaks the OpenAI
+protocol: `api: "openai-completions"` is the wire format OpenRouter uses too.
+The example model is `gemini-3.1-pro-preview`.
+
+Switching to it takes four steps.
+
+1. **Name the gateway.** In `files/home/.pi/agent/models.json`, put your
+   gateway's URL in `baseUrl` in place of the `litellm.example.com` placeholder,
+   and the model you want in `models`.
+2. **Choose it.** In `files/home/.pi/agent/settings.json`, set
+   `"defaultProvider": "litellm"` and `"defaultModel"` to the model id. Pi needs
+   both, and both must match an entry in `models.json`.
+3. **Open the road.** Add the gateway's host to `permissions.network.allow` in
+   `spec.yaml`, and give it a `credentials` entry like the OpenRouter one:
+   `header: Authorization`, `format: "Bearer %s"`, which is how LiteLLM
+   authenticates too.
+4. **Hand over the key**, then run `code2okf md/`, which builds the kit and
+   copies the config in.
+
+```bash
+sbx secret set-custom --sandbox code2okf --host <your-gateway-host> \
+  --env LITELLM_API_KEY --value "$LITELLM_API_KEY"
+```
+
+Only `set-custom` here. Plain `set` knows a fixed list of built-in services;
+OpenRouter is on it, a gateway is not. sbx still marks `set-custom`
+experimental. It has no stdin form either, so the key is visible to anything
+that can list processes for as long as the command runs. Reading it from an
+exported variable, as above, at least keeps it out of your shell history.
+
+## Context7 docs extension
+
+The kit installs `@upstash/context7-pi` (pinned in `setup.install` and listed
+under `packages` in `settings.json`). That is a native Pi package — not MCP —
+and registers `resolve-library-id`, `query-docs`, and the `context7-docs` skill.
+Egress to `context7.com` is allowlisted in `spec.yaml`.
+
+### Why the litellm entry spells out its numbers
+
+Pi ships a catalogue of 33 providers. OpenRouter is one of them; LiteLLM is not.
+The advice above about the `models` array therefore turns on its head here.
+Leave the array out for `openrouter` and the catalogue fills in real figures. Do
+the same for `litellm` and there is nothing to fill in, so Pi falls back to 128K
+of context, 16,384 output tokens and no reasoning.
+
+That output cap is shared, which makes it tighter than it looks. Thinking tokens
+come out of the same budget as the answer, so a small cap can buy a lot of
+thought and no words at all: the gateway returns 200 and an empty `choices`
+array. Hence the explicit numbers in the entry. `modelOverrides` is no help,
+because it patches ids Pi already knows and drops the rest without a word.
+
+Two of those numbers are guesses. `cost` feeds Pi's own usage tracking and says
+nothing about what your gateway charges. `thinkingLevelMap` folds Pi's seven
+thinking levels onto `low`, `medium` and `high`, which a gateway fronting Gemini
+takes as `reasoning_effort`. If yours rejects a level, change the map, or set
+`"reasoning": false` and Pi will stop sending one.
+
+### Two things to check before you debug the wrong one
+
+First, that the provider is there at all:
+
+```bash
+sbx exec code2okf -- pi --list-models litellm
+```
+
+The filter matches the provider name, so this lists your models and nothing
+else. An empty list means the key never reached Pi, which drops a provider whose
+`apiKey` resolves to nothing without an error or a warning. Beware that the
+listing and the lookup disagree: Pi will still choose the model when it runs,
+because the lookup that resolves `settings.json` pays no attention to keys. So a
+missing key shows up not here but at the first request.
+
+Second, that the gateway is reachable. A host that `permissions.network` allows
+may still be out of reach, because lifting sbx's own policy does not give the
+microVM a route to it. Ask from inside, not from your shell:
+
+```bash
+sbx exec code2okf -- curl -sS -o /dev/null -w '%{http_code}\n' \
+  https://<your-gateway-host>/v1/models
+```
+
+`200` or `401` means the path works, `401` being a credential problem rather
+than a routing one. A hang or a DNS failure means it does not.

code2okf/kit/files/home/.local/lib/code2okf/mount-state.sh

@@ -0,0 +1,48 @@
+#!/bin/sh
+# Relocate an agent's trace folder onto this sandbox's state mount.
+# Usage: sh mount-state.sh LINK SUBDIR
+#
+# A bind mount keeps LINK as a real directory while making its writes land in
+# host-backed state. It must be recreated after every sandbox start.
+set -eu
+[ -n "${CODE2OKF_STATE_DIR:-}" ] || exit 0
+link="$1"
+target="${CODE2OKF_STATE_DIR}/$2"
+
+same_fs() {
+	one="$(stat -c '%d:%i' "$1" 2>/dev/null || stat -f '%d:%i' "$1" 2>/dev/null)"
+	two="$(stat -c '%d:%i' "$2" 2>/dev/null || stat -f '%d:%i' "$2" 2>/dev/null)"
+	[ -n "${one}" ] && [ "${one}" = "${two}" ]
+}
+
+mkdir -p "${target}" || {
+	echo "mount-state: could not create ${target}" >&2
+	exit 1
+}
+mkdir -p "${link}" || {
+	echo "mount-state: could not create ${link}" >&2
+	exit 1
+}
+
+# shellcheck disable=SC2310 # false normally means "not bound yet"
+if same_fs "${link}" "${target}"; then
+	exit 0
+fi
+
+# Host state is authoritative. Merge only names absent from it, including
+# dotfiles, before covering the stock directory with the bind mount.
+for entry in "${link}"/.[!.]* "${link}"/..?* "${link}"/*; do
+	[ -e "${entry}" ] || continue
+	name="$(basename "${entry}")"
+	[ "${name}" = "lost+found" ] && continue
+	[ -e "${target}/${name}" ] && continue
+	if ! cp -R "${entry}" "${target}/"; then
+		echo "mount-state: could not copy ${link}/${name} into ${target}" >&2
+		exit 1
+	fi
+done
+
+if ! sudo -n mount --bind "${target}" "${link}"; then
+	echo "mount-state: could not bind-mount ${target} onto ${link}" >&2
+	exit 1
+fi