sayfirst-cli 0.2.0__tar.gz

sayfirst_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The gate, run by a machine. Every check it runs is `scripts/gate.sh`, with one
+# stated exception below — the sign-off check, which runs on a pull request and
+# reads the commits of the change against the ref it started from, a range no
+# run on a machine has to be given. Apart from it, what a contributor runs
+# locally is what decides a merge; a step that exists only here is a step nobody
+# can reproduce, and `tests/test_gate_modes.py` fails if this file grows a
+# second one. The rest of what is written below decides which of the gate's two
+# green outcomes this run reached and renders it, which is a rendering job
+# rather than a check.
+#
+# This workflow publishes nothing. `release.yml` is the only file here that can,
+# and only on a tag; a publish step added here is a constitutional change, not a
+# convenience.
+#
+# WHERE THIS WORKFLOW READS THE CONTRACT, AND WHY IT NEEDS NOTHING TO DO IT.
+# `scripts/gate.sh` builds `sayfirst-contract` from a source checkout rather
+# than installing it, so that what the gate reports on is the source the tag
+# this client pins actually names; the dependency-closure guard of articles 13
+# and 14 measures a real install, and does it separately. This file only says
+# where that checkout comes from. It is the control plane's PUBLIC repository,
+# at the tag this client's own pin names, and it carries NO credential: nothing
+# in this file can reach
+# anything a stranger reading it cannot reach too. That is article 16's « a fork
+# can build, test and contribute with nothing but this repository » held as a
+# file rather than promised in a sentence, and it is what publication changed
+# here — while the contract's repository was not open, this step needed a read
+# credential, and a fork that held none got the reduced leg below and nothing
+# else. The tag is `v` followed by the pinned contract version, read out of
+# `pyproject.toml` by the step below. `release.yml` reads the same pin with the
+# same script, and `tests/test_gate_modes.py` requires the two to be the same
+# text: neither file spells the version, because a version spelled twice is a
+# version that will eventually be spelled two ways.
+#
+# WHY A REDUCED LEG STILL RUNS, AND NOW RUNS ON EVERY RUN. A machine that cannot
+# reach that repository still exists — a fork with no network, a runner behind a
+# proxy, a contributor offline — and what it gets is a contract that is simply
+# absent. An absent contract is a fact about the world, not a crash. Article 2
+# says an absence is "never rendered as a negative fact, a zero or a healthy
+# state", so `scripts/gate.sh` has three outcomes and this workflow renders
+# three and not two:
+#
+#   gate (full)                     the contract was built from the control
+#                                   plane's public repository, at the tag this
+#                                   client pins, and every check ran.
+#                                   `scripts/gate.sh` exits 0.
+#   gate (reduced — contract        no checkout of the control plane was made,
+#   absent, some checks not run)    so the contract is absent. Format, lint and
+#                                   every test that does not import the
+#                                   contract ran; the rest are named and
+#                                   counted in the job's summary and in an
+#                                   annotation. `scripts/gate.sh` exits 75. The
+#                                   tick is green and the job says, in its own
+#                                   name, what it did not prove.
+#   failure                         anything else — including a full job whose
+#                                   gate came back reduced, and a reduced job
+#                                   whose gate came back full.
+#
+# The two legs run side by side now, rather than one of them instead of the
+# other. Which leg ran used to be decided by whether this repository held a
+# credential, and that question no longer exists; what is left is a leg that
+# proves the tree against the contract and a leg that proves the reduced path
+# still renders honestly on a machine that has nothing, which is the machine
+# article 16 is about. A reduced run proves nothing about the contract and
+# nothing about the installed dependency closure of articles 13 and 14, and
+# today nothing about this client against a daemon either — the job lists what
+# it did not run, so that sentence is checkable against the run rather than
+# trusted from here.
+name: gate
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  full:
+    name: gate (full)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          path: sayfirst-cli
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.12.5"
+
+      # Read out of the project file, never spelled here: `scripts/gate.sh`
+      # reads the same pin out of the same file, and `release.yml` derives the
+      # same tag with this same script — held as one text by
+      # `tests/test_gate_modes.py`, because two readings of one rule is how two
+      # files stop agreeing about it. Shell rather than an interpreter, so that
+      # the only program of this repository this job runs is the gate.
+      #
+      # THE ASSUMPTION THIS DERIVATION RESTS ON, stated rather than left to be
+      # discovered. One tag of the control plane is checked out here, and this
+      # client pins TWO of the distributions that tag builds. The tag is
+      # derived from the `sayfirst-contract` pin because the control plane moves
+      # every distribution it publishes to one version together — its own rule,
+      # held by its own guard, and by nothing in this repository. So the step
+      # reads both pins and refuses when they disagree: two pins that name two
+      # versions name no tag at all, and the honest answer is to say so here
+      # rather than to check one of them out and let the other pin fail later.
+      - name: The contract version this client pins
+        id: contract
+        working-directory: sayfirst-cli
+        run: |
+          pinned="$(sed -n 's/.*"sayfirst-contract==\([^"]*\)".*/\1/p' pyproject.toml | head -n 1)"
+          boundary="$(sed -n 's/.*"sayfirst-boundary==\([^"]*\)".*/\1/p' pyproject.toml | head -n 1)"
+          if [ -z "$pinned" ]; then
+            echo "::error::pyproject.toml pins no version of sayfirst-contract, so there is no ref to read the contract at"
+            exit 1
+          fi
+          if [ -z "$boundary" ]; then
+            echo "::error::pyproject.toml pins no version of sayfirst-boundary, and one tag of the control plane has to carry both"
+            exit 1
+          fi
+          if [ "$pinned" != "$boundary" ]; then
+            echo "::error::the pins disagree — sayfirst-contract ${pinned}, sayfirst-boundary ${boundary} — and one tag of the control plane carries one version of both, so there is no ref to read them at"
+            exit 1
+          fi
+          echo "tag=v${pinned}" >> "$GITHUB_OUTPUT"
+          echo "The contract is read at v${pinned}." >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/checkout@v5
+        with:
+          repository: fredaime/sayfirst-control-plane
+          ref: ${{ steps.contract.outputs.tag }}
+          path: sayfirst-control-plane
+          fetch-depth: 0
+
+      - name: gate
+        working-directory: sayfirst-cli
+        env:
+          SAYFIRST_CONTRACT_SOURCE: ${{ github.workspace }}/sayfirst-control-plane
+          SAYFIRST_CONTRACT_REF: ${{ steps.contract.outputs.tag }}
+        run: |
+          status=0
+          ./scripts/gate.sh || status=$?
+          case "$status" in
+            0)
+              echo "### gate: full green" >> "$GITHUB_STEP_SUMMARY"
+              echo "" >> "$GITHUB_STEP_SUMMARY"
+              echo "Format, lint, every test and the dependency-closure guard of articles 13" >> "$GITHUB_STEP_SUMMARY"
+              echo "and 14 ran against a contract built from the control plane's public" >> "$GITHUB_STEP_SUMMARY"
+              echo "repository, at the tag this client pins." >> "$GITHUB_STEP_SUMMARY"
+              ;;
+            75)
+              echo "::error::the control plane was checked out and the gate still came back reduced: the contract source was not there"
+              exit 1
+              ;;
+            *)
+              exit "$status"
+              ;;
+          esac
+
+  reduced:
+    name: gate (reduced — contract absent, some checks not run)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          path: sayfirst-cli
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.12.5"
+
+      # No second checkout, and that is the whole point of this leg: it is the
+      # machine that has nothing. `SAYFIRST_CONTRACT_SOURCE` is left unset so
+      # that the gate's own default finds nothing and says so, which is what a
+      # fork with no network meets.
+      - name: gate (reduced)
+        working-directory: sayfirst-cli
+        run: |
+          set +e
+          ./scripts/gate.sh 2>&1 | tee gate.log
+          status=${PIPESTATUS[0]}
+          set -e
+          case "$status" in
+            75)
+              headline=$(grep -m1 '^gate: contract absent:' gate.log | sed 's/^gate: //')
+              {
+                echo "### gate (reduced): green, and it proves less than a full gate"
+                echo ""
+                echo "No checkout of the control plane was made on this runner, so"
+                echo "\`sayfirst-contract\` was not built. **${headline}**"
+                echo ""
+                grep '^gate:   not run: ' gate.log | sed 's/^gate:   not run: /- not run: /'
+                echo ""
+                echo "This run proves that the source is formatted, that it lints, and that the"
+                echo "guards reading only this repository's own files hold. It proves nothing"
+                echo "about the contract, nothing about this client against a daemon, and nothing"
+                echo "about the installed dependency closure of articles 13 and 14."
+                echo ""
+                echo "What would make it full: point \`SAYFIRST_CONTRACT_SOURCE\` at a checkout"
+                echo "of the control plane's public repository, which needs no credential and is"
+                echo "exactly what the full leg of this workflow does."
+              } >> "$GITHUB_STEP_SUMMARY"
+              echo "::warning::${headline} — this is a reduced gate, not a full one"
+              ;;
+            0)
+              echo "::error::the gate reported a full run with no contract source; the reduced job cannot vouch for that"
+              exit 1
+              ;;
+            *)
+              exit "$status"
+              ;;
+          esac
+
+  # Article 15 asks every contributor to sign off each commit, and article 16
+  # calls this check required. It is the one check here that is not
+  # `scripts/gate.sh`: it reads the commits of the change against the ref the
+  # change started from, and a run on a machine has no such range to be given.
+  # The whole history is checked out for the same reason a shallow one is
+  # refused — a range that cannot be read answers 2, and 2 is not a pass.
+  developer-certificate-of-origin:
+    name: sign-off on every commit
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Every commit certifies the Developer Certificate of Origin
+        run: >-
+          python scripts/check_developer_certificate_of_origin.py
+          --base=${{ github.event.pull_request.base.sha }}
+          --head=${{ github.event.pull_request.head.sha }}

sayfirst_cli-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: Apache-2.0
+name: release
+
+# The only file in this repository that can publish anything.
+#
+# Article 0 forbids publishing under the decided name — no package on an index,
+# no public repository, no announcement — until the marks are filed. So the act
+# that starts a publication is the operator's tag and nothing else: there is no
+# `branches:` under `push` and no `pull_request:` here, and
+# `tests/test_release_workflow_publishes_only_on_a_tag.py` fails if either
+# arrives. A tag naming a version this distribution does not carry is refused
+# by name in the build and publishes nothing.
+#
+# The dry run exists so the mechanics are proven BEFORE the marks rather than
+# discovered after them: started by hand with publishing switched off, it runs
+# the gate, builds the distribution and checks the artefact, and stops.
+#
+# WHERE THIS WORKFLOW READS THE CONTRACT, AND WHY IT IS NOT WHERE `ci.yml`
+# READS IT. The gate builds `sayfirst-contract` from a checkout of the control
+# plane rather than installing it from an index. `ci.yml` takes that checkout
+# from the repository this project has not opened yet, and carries a read
+# credential to reach it. A release is different, because a release happens
+# after publication and in a fixed order: the contract is published before the
+# client that pins it. So this workflow reads the PUBLIC control plane,
+# `fredaime/sayfirst-control-plane`, at the tag the client's own pin names, and
+# carries NO credential — nothing here can reach a repository a stranger
+# cannot. The tag is `v` followed by the pinned contract version, read out of
+# `pyproject.toml` by the step below: the version is not spelled a second time
+# anywhere in this file, because a version spelled twice is a version that will
+# eventually be spelled two ways.
+#
+# One consequence, written here rather than met in a red run. BEFORE the
+# contract is published, NEITHER path of this workflow can finish on a runner:
+# the public repository does not exist, so the second checkout fails and the
+# gate never starts. That is the honest failure — a release checked against
+# nothing is not a release — and it is why the dry run is proven on the
+# operator's own machine instead, where the version reader, the build and the
+# artefact check run against a local checkout of the control plane. The first
+# green run of this file in CI is therefore a run after the contract is
+# published, which is also the day the second checkout becomes an ordinary
+# install and article 16's « a fork can build, test and contribute with nothing
+# but this repository » is met.
+#
+# A reduced gate is never a release. `scripts/gate.sh` has three outcomes and
+# not two: 75 means the contract was absent and some checks did not run. A
+# release cut from that would be a release nothing had checked against the
+# contract, so the gate step below reads the status and refuses it by name.
+#
+# The `pypi` environment must require a reviewer. That is a setting of the
+# repository — switched on the environment's own settings page, and readable by
+# no file here: this workflow names the environment, and the operator's
+# publication checklist carries this setting. No token is stored anywhere
+# below — the index verifies this workflow's own identity.
+#
+# Every interpreter here is uv's, never the runner's system `python`: this
+# project's own `uv run` cannot resolve the contract packages from an index, so
+# the two version-reader lines pass `--no-project` and name the interpreter,
+# and the reader needs nothing beyond the standard library's TOML module.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Leave false for a dry run: build and check, publish nothing."
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build and check the distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          path: sayfirst-cli
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.12.5"
+
+      # The switch is a statement of intent, and this step is what keeps it from
+      # being read as a permission. What actually refuses to publish from a
+      # dispatch is the `publish` job's own condition, further down; an operator
+      # who switches this on is told where publication comes from rather than
+      # left with a run that quietly ignored them.
+      - name: Publication comes from a tag, not from this button
+        if: github.event_name == 'workflow_dispatch' && inputs.publish
+        run: |
+          echo "::error::a dispatch publishes nothing: re-run it with publish false to dry-run, and publish by tagging"
+          exit 1
+
+      - name: The tag names the version this distribution carries
+        if: github.event_name == 'push'
+        working-directory: sayfirst-cli
+        run: uv run --no-project --python 3.12 python scripts/release_version.py --expect "${GITHUB_REF_NAME#v}"
+
+      - name: The distribution carries a version
+        if: github.event_name == 'workflow_dispatch'
+        working-directory: sayfirst-cli
+        run: uv run --no-project --python 3.12 python scripts/release_version.py
+
+      # Read out of the project file, never spelled here: `scripts/gate.sh`
+      # reads the same pin out of the same file for the same reason. Shell
+      # rather than an interpreter, so that the only lines of this workflow
+      # that run a program of this repository are the two above.
+      #
+      # THE ASSUMPTION THIS DERIVATION RESTS ON, stated rather than left to be
+      # discovered. One tag of the control plane is checked out here, and this
+      # client pins TWO of the distributions that tag builds. The tag is
+      # derived from the `sayfirst-contract` pin because the control plane moves
+      # every distribution it publishes to one version together — its own rule,
+      # held by its own guard, and by nothing in this repository. So the step
+      # reads both pins and refuses when they disagree: two pins that name two
+      # versions name no tag at all, and the honest answer is to say so here
+      # rather than to check one of them out and let the other pin fail later.
+      - name: The contract version this client pins
+        id: contract
+        working-directory: sayfirst-cli
+        run: |
+          pinned="$(sed -n 's/.*"sayfirst-contract==\([^"]*\)".*/\1/p' pyproject.toml | head -n 1)"
+          boundary="$(sed -n 's/.*"sayfirst-boundary==\([^"]*\)".*/\1/p' pyproject.toml | head -n 1)"
+          if [ -z "$pinned" ]; then
+            echo "::error::pyproject.toml pins no version of sayfirst-contract, so there is no ref to read the contract at"
+            exit 1
+          fi
+          if [ -z "$boundary" ]; then
+            echo "::error::pyproject.toml pins no version of sayfirst-boundary, and one tag of the control plane has to carry both"
+            exit 1
+          fi
+          if [ "$pinned" != "$boundary" ]; then
+            echo "::error::the pins disagree — sayfirst-contract ${pinned}, sayfirst-boundary ${boundary} — and one tag of the control plane carries one version of both, so there is no ref to read them at"
+            exit 1
+          fi
+          echo "tag=v${pinned}" >> "$GITHUB_OUTPUT"
+          echo "The contract is read at v${pinned}." >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          repository: fredaime/sayfirst-control-plane
+          ref: ${{ steps.contract.outputs.tag }}
+          path: sayfirst-control-plane
+
+      - name: gate
+        id: gate
+        working-directory: sayfirst-cli
+        env:
+          SAYFIRST_CONTRACT_SOURCE: ${{ github.workspace }}/sayfirst-control-plane
+          SAYFIRST_CONTRACT_REF: ${{ steps.contract.outputs.tag }}
+        run: |
+          status=0
+          ./scripts/gate.sh || status=$?
+          case "$status" in
+            0)
+              echo "### gate: full green" >> "$GITHUB_STEP_SUMMARY"
+              echo "" >> "$GITHUB_STEP_SUMMARY"
+              echo "Format, lint, every test and the dependency-closure guard of articles 13" >> "$GITHUB_STEP_SUMMARY"
+              echo "and 14 ran against the contract this release pins." >> "$GITHUB_STEP_SUMMARY"
+              ;;
+            75)
+              echo "::error::the gate came back reduced: a release is never cut from a reduced gate"
+              exit 1
+              ;;
+            *)
+              exit "$status"
+              ;;
+          esac
+
+      - name: Build the distribution
+        working-directory: sayfirst-cli
+        run: uv build --out-dir dist
+      # The checker is pinned, as the control plane's is and to the same version:
+      # an unpinned checker is a check whose rules can change between two
+      # releases without either release changing.
+      - name: The built artefacts are well formed
+        working-directory: sayfirst-cli
+        run: uvx twine@7.0.0 check dist/*
+      - name: What this run built
+        working-directory: sayfirst-cli
+        run: ls -l dist/ >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: sayfirst-cli/dist/
+
+  publish:
+    name: publish to the index
+    needs: build
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      # Pinned to a release, as the uv action and the artefact checker above
+      # are: the step that hands a distribution to the index is the last thing
+      # standing between a build and the world, and a moving ref is a step
+      # whose rules can change between two releases without either release
+      # changing — the change arriving as a red release, or as a published
+      # artefact, rather than as a diff somebody reviewed.
+      - uses: pypa/gh-action-pypi-publish@v1.14.2

sayfirst_cli-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.wheelhouse/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+.venv-reduced/

sayfirst_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Changelog
+
+Every release of this client carries a section here, named for the version the project file
+declares; a release with no section fails the gate.
+
+## Unreleased
+
+- Every commit of a change is read for its sign-off on every pull request, and one that carries
+  none is refused by name. A range that cannot be read is refused too, rather than reported as
+  passing.
+- The publication checklist carries every act the constitution names, in the order they are
+  performed, and a guard fails when one of them stops being a line of it. The security policy says
+  which of article 0's two paths this repository is published by: a fresh repository, never a
+  change of visibility.
+
+## 0.2.0
+
+- The evidence surface reads and verifies: `history` pages a scope, `audit` puts the served
+  verdict beside a local check and names a finding wherever the two disagree, `export` saves a
+  bundle a third party verifies offline with the contract distribution alone, and `exports`
+  checks a directory of saved bundles without opening a socket.
+- `instrument run` puts the boundary in front of somebody else's program, reversibly and writing
+  nothing; `instrument verify` runs it again under the interpreter's own audit hook and proves,
+  from that and the scope's evidence chain alone, that every effect of a named kind was preceded
+  by a decision; `instrument apply` is reserved and refuses, saying so.
+- `trace` reads back the record of one decision and follows it into the evidence that holds it:
+  the record itself, and where it sits in the chain, bounded to the pages the read walks. Like
+  every read from a daemon it names its scope explicitly, and it exits `0` on a read whatever the
+  decision it read said.
+- `explain` renders the reason the control plane gave for a decision — the rule it applied and
+  the policy version it ran under — in the plane's own words, and composes none of its own. A
+  client explains and invokes control semantics; it never derives them, and a command that
+  reasoned here would be a second control plane with no evidence behind it.
+- `packs list` prints the convenience packs this distribution ships, one line each with the path
+  `--pack` accepts, and `packs check` reads one the way the engine will.
+- `approvals` shows a suspended ask and ends the wait, so the next ask runs the body once.
+- A verdict the verifier could not reach is rendered as it was given rather than as a negative
+  fact about the chain.
+- The release itself: this distribution moves to `0.2.0`, and installing it pins
+  `sayfirst-contract==0.2.0` and `sayfirst-boundary==0.2.0` — the contract this client speaks and
+  the runtime a governed program holds its grant in — at that version and no other. An
+  installation of this version therefore carries exactly those two, and upgrading it moves all
+  three together.