foldyard 0.0.1__tar.gz

foldyard-0.0.1/.github/workflows/foldyard-e2e.yml

@@ -0,0 +1,209 @@
+name: foldyard · live e2e
+
+# foldyard's live container e2es. Two advisory tiers run here:
+#   - Docker-in-container topology for proxy/box e2es that need a sibling box to reach the test
+#     process by container IP.
+#   - Native Linux host topology with `[machine].backend = "native"` so CI exercises the real
+#     host-side `foldyard up` / worktree stack lifecycle without nested virtualization.
+#
+# The VM-backed `podman machine` lifecycle still needs a real VM provider (/dev/kvm or macOS
+# virtualization) and stays in DEVELOPMENT.md, deliberately out of shared-runner CI.
+#
+# Split out from foldyard.yml so the fast lint/types/unit suite runs on every push (uniform with the
+# other areas), while this heavy 25-min job is OPT-IN — mirroring platform-e2e. The workflow triggers
+# on every push, but the job only runs on `main` (post-merge net), on a manual `workflow_dispatch`,
+# or when a commit message carries `[run-e2e]` (the pre-merge opt-in you add when a branch is ready
+# for the full check). On an ordinary feature-branch push the job is simply skipped — near-zero cost.
+# Deliberately excluded from the CI gate (ci-gate.yml) as too heavy, so it's advisory and never
+# blocks the required check.
+on:
+  push: # all branches; the job-level `if` decides whether to run
+  workflow_dispatch: # allow manual runs
+
+concurrency:
+  group: foldyard-e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  live-e2e:
+    name: live e2e (example stack + proxy + box, on Docker)
+    # Opt-in (mirrors platform-e2e): main, a manual dispatch, or a `[run-e2e]` commit message.
+    if: >-
+      github.ref == 'refs/heads/main'
+      || contains(github.event.head_commit.message, '[run-e2e]')
+      || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      # Repo-only read: don't leave the GitHub token in .git/config. This job bind-mounts the
+      # workspace into a sibling container, so a persisted token would ride into it — and nothing
+      # here pushes. persist-credentials: false keeps the checkout but drops the credential.
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      # Warm the host Docker cache, in PARALLEL, so neither the `docker run` below (the uv image)
+      # nor the in-test pulls (the api base, the box image, postgres, alpine) wait on a serial pull.
+      # python:3.12-slim is the example api's FROM: without it warm, `foldyard up`'s buildkit does a
+      # live `load metadata for python:3.12-slim` against Docker Hub, which intermittently 502s and
+      # fails the build hard (no buildkit retry). Pre-pulling it (with retry) lets the in-test
+      # `docker compose build` resolve the base from the local cache instead of the registry.
+      - name: Pre-pull e2e images (parallel)
+        run: |
+          pull() { for i in 1 2 3 4 5; do docker pull "$1" && return 0; sleep $((i * 5)); done; return 1; }
+          for img in \
+            ghcr.io/astral-sh/uv:python3.12-bookworm \
+            quay.io/podman/stable:latest \
+            docker.io/library/python:3.12-slim \
+            docker.io/library/postgres:16-alpine \
+            docker.io/library/alpine:latest; do
+            pull "$img" &
+          done
+          wait
+
+      # The proxy/box live e2es need the test process to run INSIDE a container so a sibling box can
+      # reach the in-process proxy/emulator by container IP. Use docker CLI only (no podman), mount
+      # the host socket, and keep the repo at the same path so daemon-side bind mounts resolve.
+      # IN_DEVBOX=1 is the box signature `config.in_box()` keys on — a preset DOCKER_HOST alone is
+      # NOT one (Linux/WSL2 hosts export a socket too). It is what stands the launch gates down
+      # here exactly as in the dev box: preflight's fail-closed default-backend block, the
+      # config-adopt gate and `machine.ensure` all skip in-box, because there is no VM to manage
+      # and nothing host-side to adopt.
+      - name: live e2e inside a docker-CLI container
+        run: |
+          docker run --rm \
+            -v /var/run/docker.sock:/var/run/docker.sock \
+            -v "$GITHUB_WORKSPACE:$GITHUB_WORKSPACE" \
+            -w "$GITHUB_WORKSPACE" \
+            -e FOLDYARD_E2E=1 \
+            -e IN_DEVBOX=1 \
+            -e DOCKER_HOST=unix:///var/run/docker.sock \
+            ghcr.io/astral-sh/uv:python3.12-bookworm \
+            bash -lc '
+              set -euo pipefail
+              apt-get update -qq
+              apt-get install -y -qq --no-install-recommends docker.io curl ca-certificates >/dev/null
+              # docker compose v2 plugin (the example-stack e2e shells `docker compose`); the static
+              # release binary, dropped into both plugin dirs the docker.io CLI searches.
+              for d in /usr/local/lib/docker/cli-plugins /usr/libexec/docker/cli-plugins; do
+                mkdir -p "$d"
+                curl -fsSL https://github.com/docker/compose/releases/download/v2.30.3/docker-compose-linux-x86_64 \
+                  -o "$d/docker-compose"
+                chmod +x "$d/docker-compose"
+              done
+              docker compose version
+              uv run --group e2e pytest tests -k e2e -v
+            '
+
+  native-host-e2e:
+    name: native host e2e (example + worktree, on Podman)
+    # Same opt-in policy as the heavier Docker topology.
+    if: >-
+      github.ref == 'refs/heads/main'
+      || contains(github.event.head_commit.message, '[run-e2e]')
+      || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    env:
+      FOLDYARD_E2E: "1"
+      FOLDYARD_ENGINE: podman
+      MACHINE_BACKEND: native
+      FOLDYARD_STATE_DIR: /tmp/foldyard-state
+      # NB: XDG_RUNTIME_DIR is set by the "Enable systemd --user session" step below to
+      # /run/user/$UID (NOT a /tmp path), so rootless podman can find the user systemd manager
+      # that schedules healthcheck timers. The native socket path derives from it
+      # (machine_backend.NativeBackend._socket_path → $XDG_RUNTIME_DIR/podman/podman.sock).
+    steps:
+      # Repo-only read (no push) — keep the token out of .git/config.
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v8.2.0
+
+      # Rootless podman schedules a container's healthcheck INTERVALS via `systemd --user`
+      # transient timers. On a GH runner the `runner` user has no login session — so no user
+      # systemd manager and no /run/user/$UID — and the old custom XDG_RUNTIME_DIR=/tmp/... made
+      # it strictly worse (podman then can't find ANY user systemd). With no timer the example db's
+      # healthcheck never re-runs, its health stays `starting`, and compose's `depends_on:
+      # service_healthy` (the api → db) blocks `foldyard up` FOREVER — the job hung to its 25-min
+      # timeout. enable-linger starts user@$UID.service + creates /run/user/$UID; we point
+      # XDG_RUNTIME_DIR + the D-Bus session there so podman's `systemd-run --user` reaches it.
+      - name: Enable systemd --user session (rootless podman healthcheck timers)
+        run: |
+          set -euo pipefail
+          sudo loginctl enable-linger "$(id -un)"
+          uid="$(id -u)"
+          for _ in $(seq 1 30); do
+            test -S "/run/user/$uid/bus" && break
+            sleep 1
+          done
+          {
+            echo "XDG_RUNTIME_DIR=/run/user/$uid"
+            echo "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$uid/bus"
+          } >> "$GITHUB_ENV"
+          # Sanity: the user manager is reachable (degraded is fine — we only need the timer path).
+          XDG_RUNTIME_DIR="/run/user/$uid" DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$uid/bus" \
+            systemctl --user is-system-running || true
+
+      - name: Install native Podman backend
+        run: |
+          set -euo pipefail
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq --no-install-recommends \
+            podman podman-compose uidmap slirp4netns fuse-overlayfs
+          mkdir -p "$XDG_RUNTIME_DIR/podman"
+          chmod 700 "$XDG_RUNTIME_DIR"
+          podman system service --time=0 "unix://$XDG_RUNTIME_DIR/podman/podman.sock" \
+            >"$RUNNER_TEMP/podman-service.log" 2>&1 &
+          echo "$!" > "$RUNNER_TEMP/podman-service.pid"
+          for _ in $(seq 1 20); do
+            if test -S "$XDG_RUNTIME_DIR/podman/podman.sock" && podman info >/dev/null 2>&1; then
+              break
+            fi
+            sleep 1
+          done
+          podman info
+          podman compose version || podman-compose --version
+
+      - name: Pre-pull native e2e images
+        run: |
+          set -euo pipefail
+          for img in \
+            docker.io/library/python:3.12-slim \
+            docker.io/library/postgres:16-alpine \
+            docker.io/library/alpine:latest; do
+            podman pull "$img" &
+          done
+          wait
+
+      # Prove the systemd --user timer path works BEFORE the e2e, so a broken healthcheck fails
+      # here in ~20s with a clear message instead of hanging `foldyard up`'s depends_on to the
+      # 25-min job timeout. A container with a trivial healthcheck must flip to `healthy`.
+      - name: Verify rootless healthchecks fire (fail fast, not a 25-min hang)
+        run: |
+          set -euo pipefail
+          cid=$(podman run -d --health-cmd 'true' --health-interval 2s --health-retries 3 \
+                  docker.io/library/alpine:latest sleep 300)
+          state=""
+          for _ in $(seq 1 15); do
+            state=$(podman inspect -f '{{.State.Health.Status}}' "$cid" 2>/dev/null || echo "")
+            [ "$state" = "healthy" ] && break
+            sleep 2
+          done
+          podman rm -f "$cid" >/dev/null 2>&1 || true
+          if [ "$state" != "healthy" ]; then
+            echo "✗ rootless podman healthchecks are NOT firing (last state: '${state:-none}')."
+            echo "  The example db's health would never flip → foldyard up hangs on depends_on."
+            echo "  Fix the systemd --user wiring (enable-linger / XDG_RUNTIME_DIR / DBUS above)."
+            exit 1
+          fi
+          echo "✓ rootless healthchecks fire — the example db will reach healthy."
+
+      - name: Native host e2e
+        run: uv run pytest tests/test_e2e.py -v
+
+      - name: Native backend diagnostics
+        if: always()
+        run: |
+          podman ps -a || true
+          cat "$RUNNER_TEMP/podman-service.log" || true

foldyard-0.0.1/.github/workflows/foldyard.yml

@@ -0,0 +1,26 @@
+name: foldyard
+
+# foldyard's fast lint/types/unit suite (no container engine, no KVM). Runs on every push that
+# touches foldyard, on ALL branches — uniform with the other areas' lint/test workflows
+# (platform-test, infra-lint, contracts) so the CI gate (ci-gate.yml, PR-only) reliably finds this
+# check across the PR's commits. The heavy live Docker e2es are split out into foldyard-e2e.yml,
+# which stays PR + post-merge scoped.
+on:
+  push:
+
+concurrency:
+  group: foldyard-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: lint + types + unit
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v8.2.0
+      # ruff (lint + format-check) + pyright + ty + the unit/golden/TUI suite. No engine. typecheck
+      # installs the `e2e` group so the opt-in proxy/box e2e tests resolve cryptography/requests.
+      - run: just check

foldyard-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: release
+
+# Tag → build → publish to PyPI. Lives under foldyard/.github/ in the origin monorepo so that repo
+# never runs it; in the standalone repo it is the .github/workflows/release.yml at the root.
+#
+# Trusted publishing: PyPI is told to trust THIS workflow in THIS repo (project settings →
+# Publishing → add a GitHub publisher: owner twistco, repo foldyard, workflow release.yml,
+# environment pypi). No API token is stored anywhere; `uv publish` exchanges the job's OIDC
+# token for a short-lived upload token. Build and publish are separate jobs so the publish job
+# holds the id-token permission and nothing else, and never runs project code.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v8.2.0
+      - name: Tag must match pyproject version
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv version --short)"
+          if [ "$tag" != "$version" ]; then
+            echo "✗ tag v$tag does not match [project].version = $version — bump pyproject first"
+            exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v8.2.0
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: uv publish

foldyard-0.0.1/.gitignore

@@ -0,0 +1,21 @@
+# VM-visible scratch the box+proxy e2e mounts into a sibling box (cleaned up per run)
+.e2e-tmp/
+
+# hypothesis example database (property-based tests)
+.hypothesis/
+
+# uv-managed virtualenv + lockfile churn / build artefacts
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+
+# Covered by the monorepo root .gitignore today; listed here so the standalone repo has them too.
+.DS_Store
+.ruff_cache/
+# Per-developer overrides (deep-merged over foldyard.toml — documented by foldyard.local.toml.example)
+foldyard.local.toml
+.claude/settings.local.*

foldyard-0.0.1/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+Notable changes, per release. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [SemVer](https://semver.org/) once past `1.0`. Before that, minor versions may
+break config or CLI shape, and say so here.
+
+## Unreleased
+
+This repository is a force-pushed snapshot of the foldyard tree in its origin monorepo until
+`0.1.0` (see `CONTRIBUTING.md`).
+
+## 0.1.0 — unreleased
+
+- The first release intended for general use.
+
+## 0.0.1 — 2026-09-06
+
+First published release, and an **alpha**. The engine has run daily inside Twist's monorepo for
+months, but this is its first life as a standalone package — cut early to establish the name on
+PyPI and to exercise the release path before it matters. Expect the config and CLI shape to move
+before `0.1.0`; see the Status section of `README.md` for what is and isn't validated (the host
+side is exercised on macOS only).
+
+- Extracted from Twist's monorepo as a squash-start ([ADR-0013](./docs/adrs/0013-in-repo-carve-out-until-extraction.md)).
+- Consumption is PyPI-first ([ADR-0020](./docs/adrs/0020-post-extraction-consumption-model.md),
+  amended): `uv tool install foldyard`. Published by tag from the release workflow via PyPI
+  trusted publishing — no API token exists anywhere.

foldyard-0.0.1/CLAUDE.md

@@ -0,0 +1 @@
+DEVELOPMENT.md

foldyard-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to foldyard
+
+Thanks for looking. Two things to know before you start.
+
+**Where development happens.** Until `0.1.0` this repository is a *snapshot*: foldyard is still
+developed inside the monorepo it is being extracted from, and `main` here is re-created from it
+(one squash commit, force-pushed) as that work lands. Issues are welcome and read; a pull
+request will be ported by hand rather than merged, and its history will not survive. After
+`0.1.0` this becomes the home and that caveat goes away — `CHANGELOG.md` says which side of the
+line we are on.
+
+**How to work on it.** [`DEVELOPMENT.md`](./DEVELOPMENT.md) is the guide: the module map, the
+test tiers (what runs anywhere, what needs an engine, what only runs on a real host), the
+conventions, and the don't-break list. The short version:
+
+```bash
+uv tool install --force --editable ".[host]"   # the `fy` on your PATH runs your checkout
+just check                                     # ruff + pyright + ty + the suite — what CI gates on
+just test -k <pattern>                         # one area
+```
+
+- Design decisions live in [`docs/adrs/`](./docs/adrs/). A change that reverses one needs a new
+  ADR that supersedes it, not an edit to the old one.
+- New property-based tests are validated **red first** — mutate the code, watch hypothesis find
+  the counterexample, revert. Commit before you mutate.
+- Write "host", not "Mac"; the host being macOS is a fact about today's users, not the design.
+- Security-relevant findings go to the address in [`SECURITY.md`](./SECURITY.md), not an issue.
+
+By contributing you agree that your contributions are licensed under the Apache License 2.0
+that covers the project (`LICENSE`).