justfile

# Engine: automerge-DAG tasks engine over keyhive + subduction +
# component-iroh (realtime) and an S3-compatible bucket (non-realtime).
#
# MinIO is fetched once into .deps/ and run as a user process.
#
# ---------------------------------------------------------------------------
# PINS (jsr-pins branch: replaces the IROH_CHECKOUT sibling-checkout
# convention with two independently-versioned, recorded artifacts).
#
#   JSR endpoint package : jsr:@polymorph/iroh@0.3.0
#     (published from polymorph-iroh @ 97c9cd4; endpoint component
#     ships base64-embedded in the
#     package and is extracted verbatim by `just fetch-endpoint-wasm` —
#     see tools/fetch-endpoint-wasm.ts for the extraction path and
#     integrity story.)
#   iroh-relay binary    : 1.0.3
#     (`cargo install --locked iroh-relay@1.0.3`; matches the .deps/iroh
#     vendor checkout inside the SAME f3d8990 publish tree, upstream
#     n0-computer/iroh @ f2eb930dda / tag v1.0.3 — the endpoint and the
#     relay speak the same wire version by construction of that publish.)
#
# These two are recorded as a PAIR: bump one, re-derive the other from
# whatever polymorph-iroh commit is published next, never drift them
# independently.
#
# STATUS (updated 2026-08-19, see README.md "JSR pins" section): the
# guest's vendored `polymorph:iroh` WIT
# (guest/wit/deps/polymorph-iroh/) is now the published package's shape,
# copied byte-for-byte from the f3d8990 publish tree — including the
# 8-case `error` variant (closed, reset(u64), connect-failed, timed-out,
# not-supported, in-use, invalid-argument, other) and the `close-info`
# record. `compose`/`run`/`pair` DEFAULT to the JSR-extracted endpoint;
# no sibling checkout is needed by any target here. `compose-checkout`
# remains as a non-default escape hatch for local endpoint development.
# ---------------------------------------------------------------------------

# Only `compose-checkout` reads this; nothing default-path does.
IROH_CHECKOUT := env_var_or_default("IROH_CHECKOUT", "../../../polymorph-iroh")
IROH_RELAY_VERSION := "1.0.3"
JSR_IROH_VERSION := "0.3.0"

# Pinned relay binary, installed once into a repo-local bin dir (no
# sibling checkout needed). `--locked` honors iroh-relay's own Cargo.lock
# at that release, so the resolved dependency graph matches what n0
# shipped for 1.0.3.
relay-bin:
    #!/usr/bin/env bash
    set -euo pipefail
    mkdir -p .deps/relay
    if [ ! -x .deps/relay/bin/iroh-relay ] || \
       [ "$(.deps/relay/bin/iroh-relay --version 2>/dev/null | awk '{print $2}')" != "{{IROH_RELAY_VERSION}}" ]; then
        echo "installing iroh-relay {{IROH_RELAY_VERSION}} into .deps/relay ..."
        cargo install --locked --root .deps/relay --features server iroh-relay@{{IROH_RELAY_VERSION}}
    fi

# Materialize iroh_endpoint.wasm from jsr:@polymorph/iroh@{{JSR_IROH_VERSION}}
# (see tools/fetch-endpoint-wasm.ts). A dependency of the default
# `compose`.
fetch-endpoint-wasm:
    #!/usr/bin/env bash
    set -euo pipefail
    mkdir -p .deps
    deno run --allow-read --allow-write --allow-net \
        --lock=tools/deno.lock --frozen \
        tools/fetch-endpoint-wasm.ts .deps/iroh_endpoint.wasm

fetcher:
    cargo build --target wasm32-wasip2 --release -p engine-fetcher

guest:
    cargo build --target wasm32-wasip2 --release -p engine-guest

# The fetcher component is deliberately NOT plugged in any more: storage
# egress is now three NAMED world imports the host wires per instance
# (#7/#11), so a single generic fetch implementation would defeat the
# point. The crate stays in-tree as a reference implementation.
#
# DEFAULT: the endpoint comes from the JSR package. The guest's vendored
# `polymorph:iroh` WIT is the published shape byte-for-byte, so no
# sibling checkout is needed by any target here.
compose: guest fetch-endpoint-wasm
    wac plug target/wasm32-wasip2/release/engine_guest.wasm \
        --plug .deps/iroh_endpoint.wasm \
        -o target/composed.wasm

# NON-DEFAULT escape hatch for local endpoint development: compose
# against a sibling polymorph-iroh checkout instead of the published
# package. Only meaningful while that checkout's `polymorph:iroh` WIT
# matches the vendored one — a checkout behind (or ahead of) the publish
# fails `wac plug` on the type mismatch, which is the correct outcome.
compose-checkout: guest
    wac plug target/wasm32-wasip2/release/engine_guest.wasm \
        --plug {{IROH_CHECKOUT}}/target/wasm32-wasip2/release/iroh_endpoint.wasm \
        -o target/composed.wasm

minio:
    #!/usr/bin/env bash
    set -euo pipefail
    mkdir -p .deps
    if [ ! -x .deps/minio ]; then
        echo "fetching minio server binary..."
        curl -fsSL -o .deps/minio https://dl.min.io/server/minio/release/linux-amd64/minio
        chmod +x .deps/minio
    fi

run: compose minio relay-bin
    #!/usr/bin/env bash
    set -euo pipefail
    relay=".deps/relay/bin/iroh-relay"
    [ -x "$relay" ] || { echo "iroh-relay not installed at $relay (run: just relay-bin)" >&2; exit 1; }
    "$relay" --dev &
    relay_pid=$!
    data="$(mktemp -d /tmp/pm-tasks-minio.XXXXXX)"
    MINIO_ROOT_USER=minioadmin MINIO_ROOT_PASSWORD=minioadmin \
        .deps/minio server "$data" --address 127.0.0.1:9000 --quiet &
    minio_pid=$!
    # Ordered teardown: MinIO is still writing into $data when it is
    # signalled, so removing the tree without waiting for it to exit
    # loses the race often enough to fail an otherwise-passing recipe on
    # its own cleanup ("Directory not empty"). Wait, then remove, and
    # never let the removal itself decide the exit code.
    trap 'kill $relay_pid $minio_pid 2>/dev/null || true; wait $minio_pid 2>/dev/null || true; rm -rf "$data" 2>/dev/null || true' EXIT
    for i in $(seq 1 50); do
        if curl -sf http://127.0.0.1:9000/minio/health/live >/dev/null 2>&1; then break; fi
        sleep 0.2
    done
    cargo run --release -p engine-host -- target/composed.wasm \
        --relay http://127.0.0.1:3340 \
        --endpoint http://127.0.0.1:9000 --bucket pm-tasks \
        --access minioadmin --secret minioadmin

# The #20 G5 kill-and-resume acts: the engine checkpoints into a mounted
# state root and a FRESH instance resumes from it, then proves it is still
# the same device by syncing with a live peer.
#
# MinIO joins the recipe for the #93 bucket-state act, which asserts an
# OBJECT COUNT out of a real store across a kill. It takes a bucket of its
# own (named for the host process), so it cannot collide with `just run`.
#
# THE FIXED PORT, AND WHAT IS AND IS NOT TOLERATED. 9000 is what the rig's
# `--endpoint` default and `just run` both use. If another MinIO already
# holds it, OUR spawn dies and the act would quietly probe the stranger —
# passing for the wrong reason. Two things keep that honest: the guard
# below FAILS THE RECIPE when our own server is not the one that came up,
# and the act's bucket is named for the host pid, so nothing it counts is
# ever shared with a co-tenant. An ephemeral port would need MinIO to
# report the port it chose, which `--quiet` plus `--address :0` do not
# give us reliably; the guard is the smaller honest change.
#
# The state root is a real temp directory, so this is the native-parity
# half of the browser's OPFS path: same guest `std::fs` code, real files.
resume: compose relay-bin minio
    #!/usr/bin/env bash
    set -euo pipefail
    relay=".deps/relay/bin/iroh-relay"
    [ -x "$relay" ] || { echo "iroh-relay not installed at $relay (run: just relay-bin)" >&2; exit 1; }
    "$relay" --dev &
    relay_pid=$!
    data="$(mktemp -d /tmp/pm-resume-minio.XXXXXX)"
    MINIO_ROOT_USER=minioadmin MINIO_ROOT_PASSWORD=minioadmin \
        .deps/minio server "$data" --address 127.0.0.1:9000 --quiet &
    minio_pid=$!
    # Ordered teardown: MinIO is still writing into $data when it is
    # signalled, so removing the tree without waiting for it to exit
    # loses the race often enough to fail an otherwise-passing recipe on
    # its own cleanup ("Directory not empty"). Wait, then remove, and
    # never let the removal itself decide the exit code.
    trap 'kill $relay_pid $minio_pid 2>/dev/null || true; wait $minio_pid 2>/dev/null || true; rm -rf "$data" 2>/dev/null || true' EXIT
    for _ in $(seq 1 50); do
        if curl -sf http://127.0.0.1:9000/minio/health/live >/dev/null 2>&1; then break; fi
        sleep 0.2
    done
    if ! kill -0 "$minio_pid" 2>/dev/null; then
        echo "minio did not survive startup on 127.0.0.1:9000 (port already in use?)" >&2
        echo "the bucket-state act would have probed someone else's server; refusing" >&2
        exit 1
    fi
    sleep 0.5
    cargo run --release -p engine-host -- target/composed.wasm \
        --acts resume --relay http://127.0.0.1:3340 \
        --endpoint http://127.0.0.1:9000 \
        --access minioadmin --secret minioadmin

check:
    cargo clippy --target wasm32-wasip2 \
        -p provider-common -p provider-s3 -p provider-dropbox -p provider-gdrive -- -D warnings
    cargo clippy --target wasm32-wasip2 -p engine-fetcher -- -D warnings
    cargo clippy --target wasm32-wasip2 -p engine-guest -- -D warnings
    cargo clippy -p engine-host -- -D warnings

# The PAIRING.md §6 acts: device pairing + the user-system partition.
#
# MinIO joins the recipe for the NAME-KEY CHAIN act (SYNC.md §1): the
# chain is account state now, and the only honest way to assert that two
# paired devices agree on it is to watch them flush into one real bucket
# and compare the OBJECT NAMES (the keys themselves never leave the
# guest). Bucket named for the host pid, and the act refuses to run if
# it is not empty — same co-tenancy discipline as `resume`.
pair: compose relay-bin minio
    #!/usr/bin/env bash
    set -euo pipefail
    relay=".deps/relay/bin/iroh-relay"
    [ -x "$relay" ] || { echo "iroh-relay not installed at $relay (run: just relay-bin)" >&2; exit 1; }
    "$relay" --dev &
    relay_pid=$!
    data="$(mktemp -d /tmp/pm-pair-minio.XXXXXX)"
    MINIO_ROOT_USER=minioadmin MINIO_ROOT_PASSWORD=minioadmin \
        .deps/minio server "$data" --address 127.0.0.1:9000 --quiet &
    minio_pid=$!
    # Ordered teardown: MinIO is still writing into $data when it is
    # signalled, so removing the tree without waiting for it to exit
    # loses the race often enough to fail an otherwise-passing recipe on
    # its own cleanup ("Directory not empty"). Wait, then remove, and
    # never let the removal itself decide the exit code.
    trap 'kill $relay_pid $minio_pid 2>/dev/null || true; wait $minio_pid 2>/dev/null || true; rm -rf "$data" 2>/dev/null || true' EXIT
    for _ in $(seq 1 50); do
        if curl -sf http://127.0.0.1:9000/minio/health/live >/dev/null 2>&1; then break; fi
        sleep 0.2
    done
    if ! kill -0 "$minio_pid" 2>/dev/null; then
        echo "minio did not survive startup on 127.0.0.1:9000 (port already in use?)" >&2
        echo "the chain act would have probed someone else's server; refusing" >&2
        exit 1
    fi
    sleep 0.5
    cargo run --release -p engine-host -- target/composed.wasm \
        --acts pairing --relay http://127.0.0.1:3340 \
        --endpoint http://127.0.0.1:9000 \
        --access minioadmin --secret minioadmin

# The RECOVERY.md T-A acts (#11): the recovery kit ceremony, the restore
# on a fresh engine, consume, double-restore refusal, and revocation.
#
# NO RELAY IS DIALLED and none is needed — which is the whole claim under
# test: "restores on a fresh browser with no live peer anywhere". The
# relay is still a recipe dependency so the binary is present and the
# recipe's shape matches `pair`/`resume`; nothing here connects to it.
#
# MinIO is the only channel. Own bucket, named for the host pid, and the
# same fixed-port guard `pair`/`resume` carry: the acts assert over the
# WHOLE key set (bundle objects present, then exactly two objects gone at
# consume), so probing a co-tenant's server would pass for the wrong
# reason.
recover: compose relay-bin minio
    #!/usr/bin/env bash
    set -euo pipefail
    data="$(mktemp -d /tmp/pm-recover-minio.XXXXXX)"
    MINIO_ROOT_USER=minioadmin MINIO_ROOT_PASSWORD=minioadmin \
        .deps/minio server "$data" --address 127.0.0.1:9000 --quiet &
    minio_pid=$!
    # Ordered teardown, as in `pair`/`resume`: MinIO is still writing into
    # $data when it is signalled, so removing the tree without waiting
    # loses the race often enough to fail an otherwise-passing recipe on
    # its own cleanup.
    trap 'kill $minio_pid 2>/dev/null || true; wait $minio_pid 2>/dev/null || true; rm -rf "$data" 2>/dev/null || true' EXIT
    for _ in $(seq 1 50); do
        if curl -sf http://127.0.0.1:9000/minio/health/live >/dev/null 2>&1; then break; fi
        sleep 0.2
    done
    if ! kill -0 "$minio_pid" 2>/dev/null; then
        echo "minio did not survive startup on 127.0.0.1:9000 (port already in use?)" >&2
        echo "the recovery acts would have probed someone else's server; refusing" >&2
        exit 1
    fi
    sleep 0.5
    cargo run --release -p engine-host -- target/composed.wasm \
        --acts recover \
        --endpoint http://127.0.0.1:9000 \
        --access minioadmin --secret minioadmin