diff --git a/.github/workflows/hermes-drift.yml b/.github/workflows/hermes-drift.yml index ee6a758..7e5371f 100644 --- a/.github/workflows/hermes-drift.yml +++ b/.github/workflows/hermes-drift.yml @@ -57,7 +57,7 @@ jobs: env: HERMES_AGENT_PATH: ${{ github.workspace }}/.hermes-agent-upstream run: | - just test-contract-upstream > contract.log 2>&1 + mise run test-contract-upstream > contract.log 2>&1 echo "EXIT=$?" >> contract.log continue-on-error: true # `outcome` is the result before continue-on-error is applied; diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3f16b84..b4e5257 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -62,7 +62,7 @@ jobs: - name: Attach the exact trigger to local main env: EXPECTED_SHA: ${{ github.sha }} - run: just release-attach-trigger + run: mise run release-attach-trigger - name: Install the frozen release toolchain run: uv sync --frozen - name: Validate the tagged baseline and strict release intent @@ -208,7 +208,7 @@ jobs: run: | test "$(git rev-parse HEAD)" = "$RELEASE_SHA" test -z "$(git status --porcelain --untracked-files=no)" - just test + mise run test test "$(git rev-parse HEAD)" = "$RELEASE_SHA" test "$(git rev-parse HEAD^)" = "$TRIGGER_SHA" test "$(git rev-list -n 1 "$TAG")" = "$RELEASE_SHA" @@ -268,7 +268,7 @@ jobs: run: | test "$(git rev-parse HEAD)" = "$RELEASE_SHA" test -z "$(git status --porcelain --untracked-files=no)" - just test-contract-pinned + mise run test-contract-pinned # Record the revision actually exercised, from the checkout the # pinned lane created -- not the constant, so the evidence reflects # what ran. Cross-check it against the constant so a renamed @@ -351,8 +351,8 @@ jobs: run: | test "$(git rev-parse HEAD)" = "$RELEASE_SHA" test -z "$(git status --porcelain --untracked-files=no)" - just build - just check-dist + mise run build + mise run check-dist test "$(git rev-parse HEAD)" = "$RELEASE_SHA" test "$(git rev-parse HEAD^)" = "$TRIGGER_SHA" test "$(git rev-list -n 1 "$TAG")" = "$RELEASE_SHA" diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c2e5532..950792d 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -21,7 +21,7 @@ jobs: # the action still verifies it against mise's signed checksums. version: "2026.10.18" - name: Run unittest suite - run: just test + run: mise run test package: runs-on: ubuntu-latest @@ -35,13 +35,13 @@ jobs: version: "2026.10.18" - name: Build and validate package metadata run: | - just build - just check-dist + mise run build + mise run check-dist # `twine check` reads metadata and never opens the archive, so it passes # on a wheel that is missing a module entirely. Installing and importing # is the only thing that catches that. - name: Prove the public surface imports from the installed wheel - run: just check-install + run: mise run check-install # Amber admission gates on the exact deployed Hermes fork contract. Keep the # immutable revision aligned with infra's candidate image/source receipt. @@ -74,4 +74,4 @@ jobs: run: | test "$(git -C "$HERMES_AGENT_PATH" rev-parse HEAD)" = \ "$DEPLOYED_HERMES_REVISION" - just test-contract-pinned + mise run test-contract-pinned diff --git a/AGENTS.md b/AGENTS.md index c6e2d46..3a118b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,12 +73,13 @@ plugin. and recovery dispatch on `get_tool_schemas` / `handle_tool_call`; do not duplicate native engine tools through `@tool`. - Redact secret-looking values in logs and avoid logging full untrusted payloads. -- Get Python, `uv` and `just` from `mise.toml` and `mise.lock` +- Get Python and `uv` from `mise.toml` and `mise.lock` (`mise trust && mise install --locked`), the same toolchain CI installs; after changing a tool pin, regenerate the lock with `mise lock --platform linux-x64,linux-arm64,macos-arm64`. Then use the - `justfile` for local development: `just install`, `just test`, - `just test-one tests.test_kit.SchemaConventionTests`, and `just build`. + mise tasks for local development (`mise tasks ls` lists them; one-line tasks + live in `mise.toml`, longer ones in `mise-tasks/`): `mise run install`, `mise run test`, + `mise run test-one tests.test_kit.SchemaConventionTests`, and `mise run build`. ## Release Notes diff --git a/README.md b/README.md index e202583..b5ead7e 100644 --- a/README.md +++ b/README.md @@ -867,9 +867,9 @@ so the linked directory is self-contained. ## Development -Uses [mise](https://mise.jdx.dev/) to install the pinned Python, -[uv](https://docs.astral.sh/uv/) and [Just](https://github.com/casey/just) -from `mise.toml` and `mise.lock`, the same toolchain CI installs. Once per +Uses [mise](https://mise.jdx.dev/) to install the pinned Python and +[uv](https://docs.astral.sh/uv/) from `mise.toml` and `mise.lock`, the same +toolchain CI installs, and to run the project's tasks. Once per checkout: ```bash @@ -879,13 +879,13 @@ mise trust && mise install --locked Then: ```bash -just install # uv sync — create/sync the dev environment -just test # uv run python -m unittest discover -s tests -just test-one tests.test_kit.SchemaConventionTests -just test-release # release intent, artifact identity, and workflow contracts -just test-contract # real upstream Hermes contract -just build # uv build — wheel + sdist -just check-dist # validate wheel/sdist metadata with twine +mise run install # uv sync — create/sync the dev environment +mise run test # uv run python -m unittest discover -s tests +mise run test-one tests.test_kit.SchemaConventionTests +mise run test-release # release intent, artifact identity, and workflow contracts +mise run test-contract # real upstream Hermes contract +mise run build # uv build — wheel + sdist +mise run check-dist # validate wheel/sdist metadata with twine ``` CI pins every Action to an immutable commit and runs the unit, package metadata, diff --git a/justfile b/justfile deleted file mode 100644 index 64025c9..0000000 --- a/justfile +++ /dev/null @@ -1,228 +0,0 @@ -set shell := ["bash", "-cu"] - -uv := env_var_or_default("UV", "uv") -openspec := env_var_or_default("OPENSPEC", "openspec") -openspec_min := "1.13.1" -hermes_agent_repo := env_var_or_default("HERMES_AGENT_REPO", "https://github.com/NousResearch/hermes-agent.git") -hermes_pinned_dir := env_var_or_default("HERMES_PINNED_DIR", ".hermes-agent-pinned") -hermes_upstream_dir := env_var_or_default("HERMES_UPSTREAM_DIR", ".hermes-agent-upstream") -hermes_pinned_venv := env_var_or_default("HERMES_PINNED_VENV", ".hermes-venv-pinned") -hermes_upstream_venv := env_var_or_default("HERMES_UPSTREAM_VENV", ".hermes-venv-upstream") - -# Show available recipes. -default: - @just --list - -# Create or sync the uv-managed environment. -install: - {{ uv }} sync - -# Run the full unittest suite. -test: - {{ uv }} run python -m unittest discover -s tests - -# Run one unittest by dotted test name. -test-one test_name: - {{ uv }} run python -m unittest {{ test_name }} - -# Run deterministic release intent, identity, and workflow contracts. -test-release: - {{ uv }} run python -m unittest tests.test_release_contract -v - -# Attach an immutable CI trigger to the branch semantic-release matches. -[private] -release-attach-trigger: - #!/usr/bin/env bash - set -euo pipefail - test "$GITHUB_REF" = "refs/heads/main" - test "$(git rev-parse HEAD)" = "$EXPECTED_SHA" - git switch --force-create main "$EXPECTED_SHA" - test "$(git branch --show-current)" = "main" - test "$(git rev-parse HEAD)" = "$EXPECTED_SHA" - -# Check out hermes-agent at a given ref, in a directory of its own. -# -# Each ref gets its own directory. Sharing one meant a pinned checkout left a -# detached HEAD behind, and the next upstream run's `pull --ff-only || true` -# swallowed the resulting error -- so it silently re-tested the pin while -# reporting upstream. -[private] -prepare-hermes-ref ref dir: - #!/usr/bin/env bash - set -euo pipefail - if [[ -d "{{ dir }}/.git" ]]; then - git -C "{{ dir }}" fetch -q --depth 1 origin "{{ ref }}" - else - echo "Cloning hermes-agent into {{ dir }}" - git init -q "{{ dir }}" - git -C "{{ dir }}" remote add origin "{{ hermes_agent_repo }}" - git -C "{{ dir }}" fetch -q --depth 1 origin "{{ ref }}" - fi - git -C "{{ dir }}" checkout -q FETCH_HEAD - echo "hermes-agent at $(git -C "{{ dir }}" rev-parse HEAD)" - -# Build the host's own environment from the host's own lockfile. -# -# The kit's venv lacks the host's dependencies (ruamel, dotenv, ...), so the -# contract modules died at import there. The host's `pyproject.toml` alone -# does not resolve either, so its `uv.lock` is the only faithful source. -[private] -provision-hermes-host dir venv: - #!/usr/bin/env bash - set -euo pipefail - host="$(cd "{{ dir }}" && pwd)" - mkdir -p "{{ venv }}" - venv="$(cd "{{ venv }}" && pwd)" - test -f "$host/uv.lock" || { echo "no uv.lock in $host; cannot provision the host faithfully" >&2; exit 1; } - spec="$({{ uv }} run python -c 'import sys, tomllib; print(tomllib.load(open(sys.argv[1], "rb"))["project"]["requires-python"])' "$host/pyproject.toml")" - py="$({{ uv }} python find --system "$spec")" \ - || { echo "no interpreter on PATH satisfies the host's requires-python $spec; add one to mise.toml" >&2; exit 1; } - echo "hermes host python: $("$py" -V 2>&1) at $py (host requires-python $spec)" - (cd "$host" && UV_PROJECT_ENVIRONMENT="$venv" {{ uv }} sync --frozen --quiet --python "$py") - {{ uv }} pip install --quiet --python "$venv/bin/python" --reinstall-package hermes-plugin-kit . - -# Run the full contract suite against the deployed pin. -# -# HERMES_EXPECTED_REVISION makes the lane refuse a checkout at any other -# revision, so a stale HERMES_AGENT_PATH cannot receipt the wrong host. -test-contract-pinned: - #!/usr/bin/env bash - set -euo pipefail - pin="$({{ uv }} run python -c 'from hermes_plugin_kit.testing import DEPLOYED_HERMES_REVISION as r; print(r)')" - dir="${HERMES_AGENT_PATH:-{{ hermes_pinned_dir }}}" - if [[ -z "${HERMES_AGENT_PATH:-}" ]]; then - just prepare-hermes-ref "$pin" "{{ hermes_pinned_dir }}" - fi - just provision-hermes-host "$dir" "{{ hermes_pinned_venv }}" - HERMES_CONTRACT_REQUIRED=1 HERMES_EXPECTED_REVISION="$pin" \ - HERMES_AGENT_PATH="$(cd "$dir" && pwd)" \ - just _run-contract-suite "pinned $pin" "{{ hermes_pinned_venv }}" - -# Run the full contract suite against upstream main -- the drift lane. -test-contract-upstream: - #!/usr/bin/env bash - set -euo pipefail - dir="${HERMES_AGENT_PATH:-{{ hermes_upstream_dir }}}" - if [[ -z "${HERMES_AGENT_PATH:-}" ]]; then - just prepare-hermes-ref main "{{ hermes_upstream_dir }}" - fi - rev="$(git -C "$dir" rev-parse HEAD)" - just provision-hermes-host "$dir" "{{ hermes_upstream_venv }}" - HERMES_CONTRACT_REQUIRED=1 HERMES_AGENT_PATH="$(cd "$dir" && pwd)" \ - just _run-contract-suite "upstream $rev" "{{ hermes_upstream_venv }}" - -# Backwards-compatible alias for the upstream lane. -test-contract: test-contract-upstream - -# Run both contract modules and prove the run actually executed checks. -# -# The exit status alone cannot say whether anything ran: unittest exits 0 when -# every test skips. So the executed count is the evidence. -[private] -_run-contract-suite label venv: - #!/usr/bin/env bash - set -euo pipefail - log="$(mktemp)" - trap 'rm -f "$log"' EXIT - set +e - "{{ venv }}/bin/python" -m unittest tests.test_hermes_contract tests.test_context_engine_contract -v \ - > "$log" 2>&1 - echo "EXIT=$?" >> "$log" - set -e - cat "$log" - grep -qE '^EXIT=0' "$log" || { echo "contract suite failed ({{ label }})" >&2; exit 1; } - ran="$(grep -oE '^Ran [0-9]+' "$log" | grep -oE '[0-9]+' | head -n1)" - test -n "$ran" && [ "$ran" -gt 0 ] \ - || { echo "no contract tests ran ({{ label }}); a lane that checked nothing is not a lane that passed" >&2; exit 1; } - if grep -qE 'OK \(skipped=' "$log"; then - echo "contract suite skipped tests ({{ label }}); expected a host for every case" >&2 - exit 1 - fi - echo "contract receipt: {{ label }}; executed=$ran" - -# Run the context-engine contract. Requires an explicit checkout. -test-context-engine-contract: - #!/usr/bin/env bash - set -euo pipefail - : "${HERMES_AGENT_PATH:?set it to a hermes-agent checkout; this lane does not guess}" - just provision-hermes-host "$HERMES_AGENT_PATH" "{{ hermes_pinned_venv }}" - HERMES_CONTRACT_REQUIRED=1 "{{ hermes_pinned_venv }}/bin/python" -m unittest tests.test_context_engine_contract -v - -# Refuse to run when the installed OpenSpec predates the archive-correctness fixes. -[private] -openspec-floor: - #!/usr/bin/env bash - set -euo pipefail - have="$({{ openspec }} --version 2>/dev/null | tr -d '[:space:]' || true)" - if [[ -z "$have" ]]; then - echo "openspec not found on PATH; need >= {{ openspec_min }}" >&2 - exit 1 - fi - lowest="$(printf '%s\n%s\n' "$have" "{{ openspec_min }}" | sort -V | head -n1)" - if [[ "$have" != "{{ openspec_min }}" && "$lowest" != "{{ openspec_min }}" ]]; then - echo "openspec $have is below the required {{ openspec_min }}" >&2 - echo "Releases before {{ openspec_min }} could exit 0 from archive having applied" >&2 - echo "less than the delta specified. Upgrade before validating or archiving." >&2 - exit 1 - fi - -# Validate every OpenSpec change, and confirm each authored one will archive. -spec-validate: openspec-floor - #!/usr/bin/env bash - set -euo pipefail - changes="$({{ openspec }} list --json | {{ uv }} run python -c 'import json,sys; print("\n".join(c["name"] for c in json.load(sys.stdin)["changes"]))')" - test -n "$changes" || { echo "no OpenSpec changes found" >&2; exit 1; } - for change in $changes; do - echo "== $change" - {{ openspec }} validate "$change" --strict - # `validate --strict` can pass while `archive` refuses — a MODIFIED header - # matching nothing in the main spec is INFO at validate and fatal at archive. - # Resolving the deltas catches that early, but only once a proposal exists. - if [[ -f "openspec/changes/$change/proposal.md" ]]; then - {{ openspec }} show "$change" --diff >/dev/null - else - echo " (not yet authored — skipping delta resolution)" - fi - done - -# Build the wheel and source distribution. -build: - rm -rf dist - {{ uv }} build - -# Validate wheel and source-distribution metadata. -check-dist: - {{ uv }} run twine check dist/* - -# Prove every public name imports from an installed wheel, not just the source tree. -# -# `twine check` validates metadata and never opens the archive, so it cannot see -# a module missing from the build. Only installing and importing can. -check-install: build - #!/usr/bin/env bash - set -euo pipefail - wheel="$(ls dist/*.whl | head -n1)" - test -n "$wheel" || { echo "no wheel in dist/" >&2; exit 1; } - workdir="$(mktemp -d)" - trap 'rm -rf "$workdir"' EXIT - # --no-project keeps the source tree off sys.path, so a name that only - # resolves in-tree fails here instead of passing by accident. - repo="$PWD" - cat > "$workdir/probe.py" <<'PROBE' - import hermes_plugin_kit as hpk - missing = sorted(n for n in hpk.__all__ if not hasattr(hpk, n)) - if missing: - raise SystemExit("not importable from the installed wheel: " + ", ".join(missing)) - import hermes_plugin_kit.testing as t - t.RecordingPluginContext(name="install-probe") - print("installed wheel exports", len(hpk.__all__), "names; harness constructs") - PROBE - cd "$workdir" - {{ uv }} venv --quiet .venv - VIRTUAL_ENV="$workdir/.venv" {{ uv }} pip install --quiet "$repo/$wheel" - VIRTUAL_ENV="$workdir/.venv" {{ uv }} run --no-project python probe.py - -# Remove Python caches and build artifacts. -clean: - find . -type d -name __pycache__ -prune -exec rm -rf {} + - rm -rf .pytest_cache .coverage htmlcov dist build *.egg-info diff --git a/mise-tasks/check-install b/mise-tasks/check-install new file mode 100755 index 0000000..8fd4244 --- /dev/null +++ b/mise-tasks/check-install @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +#MISE description="Prove every public name imports from an installed wheel, not just the source tree" +#MISE depends=["build"] +# `twine check` validates metadata and never opens the archive, so it cannot see +# a module missing from the build. Only installing and importing can. +set -euo pipefail +wheel="$(ls dist/*.whl | head -n1)" +test -n "$wheel" || { echo "no wheel in dist/" >&2; exit 1; } +workdir="$(mktemp -d)" +trap 'rm -rf "$workdir"' EXIT +# --no-project keeps the source tree off sys.path, so a name that only +# resolves in-tree fails here instead of passing by accident. +repo="$PWD" +cat > "$workdir/probe.py" <<'PROBE' +import hermes_plugin_kit as hpk +missing = sorted(n for n in hpk.__all__ if not hasattr(hpk, n)) +if missing: + raise SystemExit("not importable from the installed wheel: " + ", ".join(missing)) +import hermes_plugin_kit.testing as t +t.RecordingPluginContext(name="install-probe") +print("installed wheel exports", len(hpk.__all__), "names; harness constructs") +PROBE +cd "$workdir" +"$UV" venv --quiet .venv +VIRTUAL_ENV="$workdir/.venv" "$UV" pip install --quiet "$repo/$wheel" +VIRTUAL_ENV="$workdir/.venv" "$UV" run --no-project python probe.py diff --git a/mise-tasks/openspec-floor b/mise-tasks/openspec-floor new file mode 100755 index 0000000..81f3987 --- /dev/null +++ b/mise-tasks/openspec-floor @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +#MISE description="Refuse to run when the installed OpenSpec predates the archive-correctness fixes" +#MISE hide=true +set -euo pipefail +min="$OPENSPEC_MIN" +have="$("$OPENSPEC" --version 2>/dev/null | tr -d '[:space:]' || true)" +if [[ -z "$have" ]]; then + echo "openspec not found on PATH; need >= $min" >&2 + exit 1 +fi +lowest="$(printf '%s\n%s\n' "$have" "$min" | sort -V | head -n1)" +if [[ "$have" != "$min" && "$lowest" != "$min" ]]; then + echo "openspec $have is below the required $min" >&2 + echo "Releases before $min could exit 0 from archive having applied" >&2 + echo "less than the delta specified. Upgrade before validating or archiving." >&2 + exit 1 +fi diff --git a/mise-tasks/prepare-hermes-ref b/mise-tasks/prepare-hermes-ref new file mode 100755 index 0000000..b0f6c96 --- /dev/null +++ b/mise-tasks/prepare-hermes-ref @@ -0,0 +1,22 @@ +#!/usr/bin/env bash +#MISE description="Check out hermes-agent at a given ref, in a directory of its own" +#MISE hide=true +#USAGE arg "" +#USAGE arg "" +# Each ref gets its own directory. Sharing one meant a pinned checkout left a +# detached HEAD behind, and the next upstream run's `pull --ff-only || true` +# swallowed the resulting error -- so it silently re-tested the pin while +# reporting upstream. +set -euo pipefail +ref="$usage_ref" +dir="$usage_dir" +if [[ -d "$dir/.git" ]]; then + git -C "$dir" fetch -q --depth 1 origin "$ref" +else + echo "Cloning hermes-agent into $dir" + git init -q "$dir" + git -C "$dir" remote add origin "$HERMES_AGENT_REPO" + git -C "$dir" fetch -q --depth 1 origin "$ref" +fi +git -C "$dir" checkout -q FETCH_HEAD +echo "hermes-agent at $(git -C "$dir" rev-parse HEAD)" diff --git a/mise-tasks/provision-hermes-host b/mise-tasks/provision-hermes-host new file mode 100755 index 0000000..a52b530 --- /dev/null +++ b/mise-tasks/provision-hermes-host @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +#MISE description="Build the host's own environment from the host's own lockfile" +#MISE hide=true +#USAGE arg "" +#USAGE arg "" +# The kit's venv lacks the host's dependencies (ruamel, dotenv, ...), so the +# contract modules died at import there. The host's `pyproject.toml` alone +# does not resolve either, so its `uv.lock` is the only faithful source. +set -euo pipefail +host="$(cd "$usage_dir" && pwd)" +mkdir -p "$usage_venv" +venv="$(cd "$usage_venv" && pwd)" +test -f "$host/uv.lock" || { echo "no uv.lock in $host; cannot provision the host faithfully" >&2; exit 1; } +spec="$("$UV" run python -c 'import sys, tomllib; print(tomllib.load(open(sys.argv[1], "rb"))["project"]["requires-python"])' "$host/pyproject.toml")" +py="$("$UV" python find --system "$spec")" \ + || { echo "no interpreter on PATH satisfies the host's requires-python $spec; add one to mise.toml" >&2; exit 1; } +echo "hermes host python: $("$py" -V 2>&1) at $py (host requires-python $spec)" +(cd "$host" && UV_PROJECT_ENVIRONMENT="$venv" "$UV" sync --frozen --quiet --python "$py") +"$UV" pip install --quiet --python "$venv/bin/python" --reinstall-package hermes-plugin-kit . diff --git a/mise-tasks/release-attach-trigger b/mise-tasks/release-attach-trigger new file mode 100755 index 0000000..e3429e8 --- /dev/null +++ b/mise-tasks/release-attach-trigger @@ -0,0 +1,9 @@ +#!/usr/bin/env bash +#MISE description="Attach an immutable CI trigger to the branch semantic-release matches" +#MISE hide=true +set -euo pipefail +test "$GITHUB_REF" = "refs/heads/main" +test "$(git rev-parse HEAD)" = "$EXPECTED_SHA" +git switch --force-create main "$EXPECTED_SHA" +test "$(git branch --show-current)" = "main" +test "$(git rev-parse HEAD)" = "$EXPECTED_SHA" diff --git a/mise-tasks/run-contract-suite b/mise-tasks/run-contract-suite new file mode 100755 index 0000000..e81a496 --- /dev/null +++ b/mise-tasks/run-contract-suite @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +#MISE description="Run both contract modules and prove the run actually executed checks" +#MISE hide=true +#USAGE arg "