Contributing to Jaiph

Contributor docs answer a narrow question: where changes belong, how to run the same checks CI runs, and which test layer should encode a behavior change.

At a high level, Jaiph is built as described in Architecture — loadModuleGraph → per-module validateModule + script emit via buildScriptsFromGraph / emitScriptsForModuleFromGraph, the same graph consumed by buildRuntimeGraph(graph), validate-only jaiph compile (collectDiagnostics), NodeWorkflowRuntime, artifact layout, and Docker helper contracts. Treat that page as authoritative for pipelines and boundaries; if anything here diverges from it or from the implementation, prefer architecture + source.

For workflow syntax, library usage, tooling setup, and grammar details, see Language, Install & switch versions, Grammar, and Your first workflow. For the *.test.jh language and test blocks, see Write & run tests.

Branching and pull requests

Development moves quickly and may include breaking changes. Two primary branches: main (stable) and nightly (latest).

• If you want to fix a bug, point your PR to the main branch, and check if the issue has already been addressed in nightly.
• If you are adding a new feature, submit your PR to nightly (and add or update tests in e2e/tests).
• For non-trivial bugs or features, open an issue with enough context to prioritize and discuss before or alongside a PR.
• AI-assisted pull requests are welcome as long as they include comprehensive tests (including in e2e/tests).

Installing from source

Use the local installer wrapper script in this repo:

./docs/install-from-local.sh

After install, verify:

jaiph --version
jaiph --help

The script builds the self-contained standalone binary via docs/install (npm ci when a lockfile is present, else npm install, plus npm run build:standalone, including uncommitted changes) and installs dist/jaiph to ~/.local/bin by default (or JAIPH_BIN_DIR if set). It then builds runtime/Dockerfile from the same checkout and retags it as the default sandbox image — ghcr.io/jaiphlang/jaiph-runtime:<version> plus :nightly — so Docker runs use your local build without setting JAIPH_DOCKER_IMAGE. The image build is required (the script exits if Docker is missing, the daemon is down, or the build fails).

Set JAIPH_SKIP_DOCKER_BUILD=1 only to skip the image build (installer acceptance tests).

From-source prerequisites: npm, Bun, and a running Docker daemon (docker info must succeed).

Developing in the repository

For day-to-day work on the compiler and CLI you usually stay inside the clone: install dev dependencies once, then build and run tests from npm scripts.

Prerequisites: Node.js 20.x and npm (matching .github/workflows/ci.yml). Bun is also required for npm run build:standalone and ./docs/install-from-local.sh; standalone cross-compiles run in .github/workflows/release.yml via oven-sh/setup-bun, not in the main ci.yml unit/E2E jobs. End-user installs from docs/install need curl, shasum / sha256sum, and minisign to verify the release signature. The installers also expect bash. A missing minisign aborts the install on every host, including CI. For a deliberate checksum-only install, set JAIPH_ALLOW_UNSIGNED=1, which skips signature verification. End-to-end tests are written in bash and are run by e2e/test_all.sh.

Typical commands (from the repo root):

Run a single Node test file after a build with e.g. node --test dist/src/parse/parse-core.test.js. The dist/ paths mirror the source layout under src/.

Workspace hygiene

The root .gitignore blocks common debug and temp directory patterns so they never reach version control:

If you create throwaway directories during development, use one of these prefixes so they are automatically ignored. To track a file that matches a blocked pattern, use git add -f.

Code philosophy

Jaiph’s codebase is maintained by both humans and AI agents. Code should be easy to read, navigate, and modify for both — which means the same thing: straightforward, flat, and explicit.

Principles

1. Plain functions with explicit arguments. Avoid classes and abstraction-heavy generics. If a file already uses generics, follow the local style and keep additions minimal. No visitor patterns or dependency injection. A function takes data in, returns data out, or pushes to an array. If you need shared context, pass a plain object — not a class instance.
2. Flat control flow. If/else chains and switch statements, not multi-layer abstractions. An AI (or human) should be able to read a function top-to-bottom and understand what it does without jumping to 3 other files.
3. Short files. No source file should exceed ~400 lines. If a file grows past that, split it into sibling files in the same directory — not a deeper module tree.
4. No duplication across files. If the same logic exists in two places, extract it into one plain function and call it from both. Duplication means bug fixes get applied in one place and missed in the other.
5. Minimal touch surface for new features. Adding a new step type, CLI command, or runtime feature should require changes in at most 3 files (type definition, parser/handler, emitter/consumer). If it requires more, the architecture needs refactoring first.
6. No speculative abstractions. Don’t add indirection, registries, or plugin systems to “support future extensibility.” Add the simplest thing that works now. Refactor when the concrete need appears.
7. Red flag: >100 lines of custom code. Before writing a large chunk, check if the library or existing codebase already provides it. If not, explain why the new code is necessary.

Testing philosophy

Jaiph uses several test layers. Each layer catches a different class of bug. Use the narrowest layer that covers the behavior you’re verifying.

Key principles

1. Compile-time validation vs graph loading. buildScriptsFromGraph / emitScriptsForModuleFromGraph run validateModule before any script files are written. buildRuntimeGraph(graph) prepares the runtime view from the in-memory graph — it does not re-run compile-time validation. Lock compile errors in validator/txtar/acceptance tests; the runtime graph is the wrong layer for that. jaiph compile calls collectDiagnostics(graph) (same checks as validateReferences, all errors reported) — no buildScriptsFromGraph, no runner spawn; see Architecture — System overview.
2. jaiph test vs live events. jaiph test reuses NodeWorkflowRuntime with suppressLiveEvents: true so __JAIPH_EVENT__ lines are not written to stderr alongside node --test output while run_summary.jsonl and other artifact paths stay consistent where the harness writes them (Architecture — Test runner integration).
3. Tests are behavior contracts. E2E tests and acceptance tests define what the product does. Default approach: change production code to satisfy tests, not the other way around.
4. Modify existing tests only with a strong reason: intentional product behavior change, incorrect test expectation, or removal of an obsolete feature. Any such change should be minimal and paired with a clear rationale.
5. Golden tests are the compiler’s safety net. After transpiler changes, run npm test. Failures in src/transpile/compiler-golden.test.ts usually mean updating an explicit expected string in that file. Golden AST tests (test-fixtures/golden-ast/) complement this — if those fail, regenerate with UPDATE_GOLDEN=1 npm run test:golden-ast and review the diff.
6. E2E tests assert two things independently: what the user sees (CLI tree output via e2e::expect_stdout) and what the runtime persists (artifact files via e2e::expect_out, e2e::expect_file). A bug could break one without the other.
7. Prefer the narrowest test layer. A pure function bug should be caught by a unit test, not an E2E test. E2E tests are expensive to run and hard to debug — reserve them for integration-level behavior.

TypeScript test layout

• Module tests — live next to the source they validate under src/ (e.g. src/parse/parse-core.test.ts, src/cli/run/display.test.ts, src/transpile/compiler-golden.test.ts). Names are *.test.ts or *.acceptance.test.ts.
• Integration tests — span multiple modules, need subprocess/PTY harnesses, or enforce docs structure/contracts; they live in integration/ (see Integration tests).
• E2E — bash scripts in e2e/tests/*.sh, driven by e2e/test_all.sh.
• npm test runs the compiled suites under dist/src/, dist/integration/, and dist/test-infra/ (after npm run build; see the Developing in the repository table for the exact command).

Module test layout (colocated)

Module tests live next to the source files they validate, inside the same src/ tree. Names are *.test.ts or *.acceptance.test.ts. To list them from the repo root:

find src -type f \( -name '*.test.ts' -o -name '*.acceptance.test.ts' \) | sort

Grouping (use the find output as authoritative after refactors):

When adding a new source module or extending an existing one, create or extend the corresponding *.test.ts in the same directory. For kernel internals, the compile path, and artifact contracts, see Architecture.

Integration tests

Tests that span multiple modules, require subprocess/PTY harnesses, exercise process-level behavior, or enforce documentation structure/contracts live in integration/. These do not belong to a single module:

The integration/sample-build/ directory also has a shared helpers.ts module used by the sample-build tests. Shared test fixtures (.jh source files and expected output) live in test-fixtures/sample-build/.

CI pipeline

The project uses GitHub Actions (.github/workflows/ci.yml). The workflow defines eight jobs. On a typical feature-branch push, seven of them run. The remaining job, Publish Docker runtime image, runs only on pushes to nightly and on v* version tags, after the test, E2E, docs, WSL, PowerShell-installer, and native-Windows-smoke jobs succeed, and it builds and pushes ghcr.io/jaiphlang/jaiph-runtime (the default runtime.docker_image / JAIPH_DOCKER_IMAGE when Docker sandboxing is on; see Docker runtime helper in Architecture). The Validate Kubernetes deploy manifest job is not one of those gates, so it does not block the image publish.

Version tags, releases, and npm

The supported release-prep path is the .jaiph/prepare_release.jh workflow. Run it as:

jaiph run .jaiph/prepare_release.jh -- 0.13.0    # explicit X.Y.Z
jaiph run .jaiph/prepare_release.jh             # next patch from package.json

The workflow refuses to start when the git tree is dirty or when v<version> already exists, then bumps package.json + package-lock.json via npm version X.Y.Z --no-git-tag-version --allow-same-version, refreshes the hardcoded release ref in docs/install and docs/install.ps1 (kept in lockstep), runs npm run build (rebuilding dist/), asserts node dist/src/cli.js --version matches the new version, and runs npm run registry:build to regenerate docs/registry. It creates no commits, no tags, and no git add — review the diff (git diff), stage the changes, commit, then git tag v<version> and push branch + tag yourself. The CLI version is single-sourced from package.json’s version field (codegen’d into src/version.ts by npm run embed-assets).

Pushing a v* tag triggers two things in this repo:

1. Docker image publish — the docker-publish job in ci.yml pushes ghcr.io/jaiphlang/jaiph-runtime:<version> and :latest after the other CI jobs succeed.
2. Standalone-binary release — .github/workflows/release.yml cross-compiles the Bun-compiled standalone binary for five targets via oven-sh/setup-bun and bun build --compile --target=…, generates a SHA256SUMS file, signs it with minisign (if MINISIGN_SECRET_KEY is set) to produce SHA256SUMS.minisig, runs a Linux x64 sanity gate and a windows-latest Windows x64 sanity gate (--version must equal jaiph <tag-without-v> for stable tags — both delegate to scripts/release-version-check.sh), and uploads all seven assets to the GitHub Release for the tag (creating it if needed). The Windows gate is a required dependency of the publish job, so a version mismatch there fails the whole release. The release job waits for the CI workflow on the same SHA to succeed before publishing. Re-runs are available via workflow_dispatch.

Pushes to the nightly branch follow the same matrix and upload to a rolling prerelease tagged nightly (gh release upload nightly --clobber), so jaiph use nightly keeps working under the binary installer.

Pushing a v* ref does not run any npm publish step from this repository — .github/workflows/ contains ci.yml (push CI), release.yml (standalone binaries; see above), nightly-engineer.yml (optional manual engineer run), the path-filtered editor-plugin jobs vscode-plugin.yml and zed-plugin.yml (each builds and tests its extension under plugins/ only when that extension’s tree changes), and the path-filtered setup-jaiph-action.yml (installs the nightly release through the actions/setup-jaiph composite action on Linux and macOS, only when that action or docs/install changes), and none publishes to npm. If you are preparing a release that includes the npm package, coordinate version bumps, registry publish, and smoke checks with the maintainers — that flow is intentionally outside this repo’s workflows.

Release asset naming contract

The installer (docs/install) downloads these exact filenames from the release for the resolved ref. The contract is fixed; do not rename or add architecture variants without updating the installer:

Bun has no bun-windows-arm64 target, so Windows ships x64 only. Every release (stable v* and rolling nightly) ships exactly these seven assets.

Release signing

Releases sign SHA256SUMS with minisign, publishing a detached SHA256SUMS.minisig. Both installers download that file and require a valid signature before installing (public key embedded in both installers; canonical copy in jaiph.pub). The checksum ships over the same channel as the binary, so the signature is the only independent defense, and verification is fail-closed. A missing minisign aborts the install on every host, including CI (finding M-5), rather than degrading to checksum-only, because a CI job is exactly where the whole install population would otherwise skip the signature check. A CI job that needs a signed install must make minisign available on the runner, which the setup-jaiph action does for you. A deliberate checksum-only install must opt in with JAIPH_ALLOW_UNSIGNED=1, which prints a prominent warning. The release build itself now fails when the MINISIGN_SECRET_KEY secret is unset, so it refuses to publish unsigned artifacts. An explicitly empty JAIPH_MINISIGN_PUBLIC_KEY is a misconfiguration and also fails closed.

Install-script integrity. The bootstrap entry points that fetch and run the installer (docs/run, docs/init, and jaiph use) do not pipe curl … | bash. They download docs/install and its published checksum docs/install.sha256, compare them, and run the script only when they match. A missing or mismatched checksum fails closed. Keep docs/install.sha256 in sync whenever you edit docs/install, regenerating it with printf '%s install\n' "$(shasum -a 256 docs/install | awk '{print $1}')" > docs/install.sha256. The e2e/tests/06_bootstrap_integrity.sh test pins the committed checksum to the current docs/install and fails the build if they drift.

Maintainers: generate once with minisign -G -W -p jaiph.pub -s jaiph.key -f (no passphrase; -W still labels the file “encrypted secret key” but uses an empty password). Store jaiph.key (not jaiph.pub) as the MINISIGN_SECRET_KEY GitHub Actions secret — paste both lines, or base64 -w0 jaiph.key as a single line. Commit jaiph.pub and keep installer defaults in sync.

Key rotation: generate a new keypair with the same command, commit the new jaiph.pub, update the embedded public key in both installers, rotate MINISIGN_SECRET_KEY in GitHub Actions, and cut a release signed with the new key. Until users upgrade to a release that ships the new public key, they can verify with JAIPH_MINISIGN_PUBLIC_KEY (see Verify the release signature).

Manual verification: Install & switch versions — Verify the release signature.

Library registry signing

jaiph install <name> fetches the registry index from JAIPH_REGISTRY (default https://jaiph.org/registry) and, for remote sources, fail-closed verifies it against a detached <source>.minisig using the same jaiph.pub trust anchor (embedded in the CLI as EMBEDDED_REGISTRY_PUBKEY — a parity test keeps it in sync with jaiph.pub). Local file:///path sources are read as trusted-local and skip the check. So publishing or regenerating docs/registry (served at https://jaiph.org/registry) requires committing a matching docs/registry.minisig beside it:

npm run registry:build                              # regenerate docs/registry
minisign -S -s jaiph.key -m docs/registry -x docs/registry.minisig

Without a valid registry.minisig, remote jaiph install <name> by design fails closed; local development can point JAIPH_REGISTRY at a file path to bypass the network entirely. Registry entries may additionally pin a commit (the cloned HEAD must match) and carry a per-library signature (a detached minisign signature over the commit SHA, verified fail-closed against the embedded project key only) — see CLI — jaiph install.

Dockerfile toolchain verification. Every remote toolchain fetch in runtime/Dockerfile goes through runtime/fetch-verify.sh, which downloads the URL and aborts unless the bytes match a required SHA-256. Each fetch pins its checksum through a build ARG: the installer scripts (UV_INSTALL_SHA256, RUSTUP_INIT_SHA256, BUN_INSTALL_SHA256, CURSOR_INSTALL_SHA256) and the downloaded binaries and archives (per-architecture GO_SHA256_*, YQ_SHA256_*, KUBECTL_SHA256_*, AWSCLI_SHA256_*, and TASK_SHA256_*). The ARGs default to the pinned hashes for the current versions, and an empty or mismatched value fails the build instead of installing unverified bytes. Some upstream URLs are rolling, such as https://astral.sh/uv/install.sh and https://sh.rustup.rs, so refresh the matching pin when you bump a version or upstream changes the installer. The NodeSource APT block uses GPG-signed packages directly, so it needs no checksum ARG.

Dockerfile base-image and npm pinning. For the same reproducibility and provenance reason (finding L-4), every FROM in runtime/Dockerfile references its base image by @sha256: digest rather than a bare mutable tag, and every global npm install -g of a registry package pins an exact version through a build ARG (PNPM_VERSION, YARN_VERSION, CLAUDE_CODE_VERSION). npm verifies each pinned version’s tarball integrity against the registry. Refresh a digest or version ARG deliberately when you bump it. To update a base image, pull the tag and read its digest with docker buildx imagetools inspect <image>:<tag>, then paste the digest after the tag. integration/release-workflow.test.ts and e2e/tests/09_dockerfile_fetch_verify.sh fail the build if a bare tag or an unpinned global install reappears, and the CI docker build of runtime/Dockerfile exercises the pinned inputs end to end.

Local docs site (Jekyll)

The Getting started (local) CI job validates that the documentation site under docs/ can be built and served from source. It uses Ruby 3.2 with bundler-cache, runs bundle exec jekyll serve --host 127.0.0.1 --port 4000 in the background, and polls http://127.0.0.1:4000/ for up to 30 seconds before asserting HTTP 200 on /, /getting-started, /setup, /libraries, and /artifacts. The same job also prepares Node, a local jaiph-ci-runtime:local image, Playwright Chromium, and external CLIs — see the docs-local job in .github/workflows/ci.yml for the exact package list.

To run the same check locally:

cd docs
bundle install          # first time only
bundle exec jekyll serve --host 127.0.0.1 --port 4000
# In another terminal:
curl -fsSL http://127.0.0.1:4000/

The Jekyll project lives entirely inside docs/ — Gemfile, _config.yml, layouts, and all Markdown pages.

Landing-page sample verification (Playwright)

After the Jekyll smoke-check, the CI job also verifies that code samples shown on the landing page match real CLI behavior. This uses Playwright (Chromium) with a test suite in e2e/playwright/landing-page.spec.ts.

The test does two things:

1. Source parity — extracts each sample’s source code from the DOM ([data-sample-source] elements inside [data-sample] tab panels) and compares it byte-for-byte against the corresponding file in examples/ (identified by data-sample-file).
2. Output verification — for each [data-sample-output] block whose sample/output key is not listed in SKIP_OUTPUT (e2e/playwright/landing-page.spec.ts), the test parses the ➜ command line, runs it against the temp copy of the page source (the executable .jh from examples/ named by data-sample-file, with say_hello.test.jh also copying companion say_hello.jh), and compares CLI output after Playwright’s normalize() in that spec file. It shares core rules with e2e::normalize_output (ANSI stripping, <time> placeholders, <agent-command>, <script-path>) and additionally collapses Logs/Summary/out/err path lines to <path> and normalizes spacing before ✓ PASS — it does not apply E2E-only rules such as __inline_<hash> → __inline_<id> or async subscript line sorting. Entries in SKIP_OUTPUT mark nondeterministic model or agent-backed tabs (e.g. say-hello / success, async / run, recover-loop / run).

To run locally:

npm run test:samples

The suite runs serially (test.describe.serial in landing-page.spec.ts): the Try it out case installs Jaiph from the local repo first (same Node / npm / Bun requirements as Installing from source), then the tabbed sample checks run ./examples/… files via the jaiph shebang with ~/.local/bin prepended to PATH. Install Playwright once with npx playwright install chromium if you have not already (also listed in the table above).

If a Jekyll server is already running on http://127.0.0.1:4000, Playwright reuses it (reuseExistingServer in playwright.config.ts). Otherwise it starts one.

Samples whose rendered output embeds nondeterministic model or agent transcripts skip output comparison per-tab via SKIP_OUTPUT in e2e/playwright/landing-page.spec.ts; those tabs still participate in DOM source parity.

E2E testing

The E2E test suite (e2e/tests/*.sh) drives the toolchain from outside the TypeScript harness: e2e::prepare_test_env in e2e/lib/common.sh calls e2e::prepare_shared_context (sanitizes stray JAIPH_* vars, prepends JAIPH_E2E_BIN_DIR to PATH, wires JAIPH_REPO_URL to the cloned tree, exports JAIPH_DOCKER_ENABLED=false by default) and e2e::ensure_local_install (builds a jaiph shim that prefers dist/src/cli.js when present). Each script then invokes jaiph run; Docker-specific assertions set JAIPH_DOCKER_ENABLED=true and usually call e2e::ensure_docker_test_image first, then pass JAIPH_DOCKER_IMAGE="${E2E_DOCKER_TEST_IMAGE}" ( jaiph-e2e-runtime:local when the harness builds it). Scripts assert on both the CLI tree (e2e::expect_stdout) and *.out / .err / run_summary.jsonl under .jaiph/runs/ — see also Architecture — Durable artifact layout.

Docker-daemon e2e helpers in e2e/lib/common.sh reduce Desktop flakes for named jaiph-run-* containers:

• e2e::wait_for_jaiph_run_container waits by name via docker ps -a (Created counts).
• e2e::docker_cleanup on EXIT force-removes leftover jaiph-run-* containers.
• e2e::run_logged surfaces jaiph run stderr on failure instead of a bare “artifact missing”.

Both GitHub Actions and the overnight engineer loop (.jaiph/ensure_ci_passes.jh) run the full Docker e2e suite (including kind / 150_k8s_deploy). Reliability rests on named jaiph-run-* waits, EXIT cleanup (including jaiph-probe-*), logged runs, probe flake classification (E_DOCKER_PROBE_FAILED vs E_DOCKER_NO_JAIPH), and kind heartbeats / wall timeouts.

You can set JAIPH_E2E_SKIP_DOCKER=1 locally to skip daemon scripts (basename *docker_* / *_docker / docker_*, plus E2E_DOCKER_DAEMON_SCRIPTS such as 148_standalone_image and 150_k8s_deploy). Static Dockerfile checks such as 09_dockerfile_fetch_verify still run. Nothing sets this variable by default.

Some scripts are contract tests: they validate persisted machine-readable output (for example e2e/tests/88_run_summary_event_contract.sh and run_summary.jsonl) in addition to or instead of golden CLI trees.

E2E philosophy: two surfaces and full equality

E2E tests are the outermost behavior contracts for the CLI and runtime. Each test should exercise the real pipeline and assert on two independent surfaces:

1. CLI tree output — what the user sees (e2e::expect_stdout with a heredoc).
2. Run artifacts — what the runtime persists under .jaiph/runs/<date>/<source>/ (e2e::expect_out, e2e::expect_file, e2e::expect_run_file). Inbox files live under the run directory when the feature touches inbox behavior.

Default contract: every assertion should compare the full expected text (stdout heredoc, artifact file contents, JSONL lines) unless there is a documented exception. Use e2e::expect_stdout, e2e::expect_out, e2e::expect_file, e2e::expect_run_file, or e2e::assert_equals / e2e::assert_output_equals for full comparisons.

e2e::assert_contains (substring check) is allowed only when full equality is not feasible. Every such use must have an inline comment explaining why. Valid reasons:

• Nondeterministic output — e.g. prompt transcripts with real agent backends, timestamps not covered by <time> normalization.
• Unbounded or variable-length logs — e.g. run_summary.jsonl with platform-dependent event counts, or live step output where line count varies.
• Platform-dependent text — e.g. OS-specific error messages, paths that differ across CI environments.

Normalization: e2e::normalize_output (in e2e/lib/common.sh) strips ANSI codes, replaces timing values with <time>, normalizes __inline_<hash> script names to __inline_<id>, swaps some CLI-specific strings (<agent-command>, <script-path>), and sorts a class of async progress lines (UTF-8 subscript markers) so strict equality stays stable when parallel branches finish in different orders. This keeps full-equality heredocs usable across machines.

Where files land on disk (directory tree, sequence prefixes): Architecture — Durable artifact layout. Runtime testing with *.test.jh is covered in Write & run tests. The run_summary.jsonl event contract is exercised in e2e/tests/88_run_summary_event_contract.sh.

Test structure

Every E2E test follows a Given / When / Then pattern using helper functions from e2e/lib/common.sh. The helpers eliminate boilerplate so each test reads like a specification:

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
source "${ROOT_DIR}/e2e/lib/common.sh"
trap e2e::cleanup EXIT

e2e::prepare_test_env "my_test"
TEST_DIR="${JAIPH_E2E_TEST_DIR}"

e2e::section "Feature under test"

# Given — create the workflow file inline (script + workflow; same shape as e2e/tests/10_basic_workflows.sh)
e2e::file "hello.jh" <<'EOF'
script hello_impl = `echo "hello-jh"`
workflow default() {
  const msg = run hello_impl()
  return "${msg}"
}
EOF

# When — run workflow (`jaiph` transpiles and executes inside the shim)
hello_out="$(e2e::run "hello.jh")"

# Then — assert on CLI tree output (include workflow return value when default() returns one)
e2e::expect_stdout "${hello_out}" <<'EOF'

Jaiph: Running hello.jh

workflow default
  ▸ script hello_impl
  ✓ script hello_impl (<time>)
✓ PASS workflow default (<time>)

hello-jh
EOF

# Then — assert on run artifacts
e2e::expect_out_files "hello.jh" 2
e2e::expect_out "hello.jh" "hello_impl" "hello-jh"

When you need a specific sequence-prefixed filename (e.g. 000002-module__step.out), use e2e::expect_run_file — see e2e/tests/72_docker_run_artifacts.sh and similar.

Helper reference

All helpers are defined in e2e/lib/common.sh.

Setup and lifecycle helpers

File and run helpers

Tree output assertions

Run artifact assertions

After a workflow runs, its step outputs are written as sequenced artifact files under .jaiph/runs/. These helpers verify artifact content independently from CLI display output. For the on-disk layout and naming scheme, see Architecture — Durable artifact layout.

Low-level assertions

Assertion policy

Quick reference: default to full-equality helpers (e2e::expect_stdout, e2e::expect_out, e2e::expect_file, e2e::expect_run_file, e2e::assert_equals). e2e::assert_contains is the exception — every use needs an inline comment; rationale list in E2E philosophy above. Audit substring usage:

rg 'e2e::assert_contains' e2e/tests -n

Orphan sample guard

Every top-level .jh and .test.jh file in e2e/ must be referenced by at least one test script (e2e/tests/*.sh, e2e/test_all.sh, or e2e/lib/). Unreferenced samples confuse contributors, hide drift from the canonical examples/ corpus, and make it unclear which fixtures are load-bearing.

The guard script e2e/check_orphan_samples.sh detects orphans automatically. It scans top-level e2e/*.jh and e2e/*.test.jh only (not nested paths), checks whether each basename appears in any test runner or helper, and also resolves indirect references (a file imported by another .jh that is itself referenced counts as covered). Any file that is neither directly nor indirectly referenced is reported as an orphan.

# Run manually from the repo root
bash e2e/check_orphan_samples.sh

On success the script prints OK: no orphan e2e samples detected. and exits 0. On failure it lists the unreferenced filenames and exits 1, with guidance to either wire them into a test, move them to examples/, or delete them.

When adding a new .jh fixture to e2e/, make sure it is exercised by a test in e2e/tests/ or imported by a file that is. If a sample exists purely for documentation or demonstration purposes, it belongs in examples/ instead.

Example matrix guard

Every .jh and .test.jh file under examples/ must be accounted for in e2e/tests/110_examples.sh. The script maintains three arrays that together form the example matrix:

An orphan guard at the bottom of the script fails CI if any example file is not listed in one of the three arrays. To add a new example:

1. Place the .jh file in examples/.
2. Add it to COVERED_RUN, COVERED_TEST, or EXCLUDED (with a comment).
3. If covered, add a test section with strict e2e::expect_stdout and artifact assertions.