@voeu/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solus-QE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# voeu
+
+Keep integrations working when providers change — and prove it.
+
+A **contract pack** is one provider's rules, written down claim by claim, encoded in a simulator,
+and turned into scenarios your application has to survive. Shopify's expiring offline access
+tokens are the first pack and the one this page is mostly about; Stripe idempotency is the
+second — see [Contract packs](#contract-packs) for what each one covers and what it does not.
+
+Every public Shopify app that calls the GraphQL Admin API must use expiring offline access tokens
+[from 1 January 2027](https://shopify.dev/changelog/expiring-offline-access-tokens-required-for-all-public-apps-as-of-january-1-2027).
+Custom and merchant-created apps are exempt. After that date, apps still presenting a non-expiring
+token get authentication errors, which one developer on Shopify's own thread described as
+"you've essentially uninstalled the app from every one of your customer's stores."
+
+The mechanical part of that migration is documented and mostly not the problem. What the docs
+cannot tell you is whether **your** app survives the new lifecycle — your session storage, your
+background jobs, your worker topology, your failure handling. Those are runtime properties.
+
+```bash
+npx @voeu/cli inspect --repo .     # read the source. no credentials, no execution.
+npx @voeu/cli verify  --reference  # see what verify does, with no setup
+npx @voeu/cli init    --repo .     # scaffold the adapter verify drives
+npx @voeu/cli verify  --repo .     # run YOUR application against a simulated Shopify
+npx @voeu/cli fix     --repo .     # emit a patch for the deterministic findings
+npx @voeu/cli watch   --record     # record today, then run it nightly
+npx @voeu/cli contract             # print every rule this encodes, and its source
+
+npx @voeu/cli verify --provider stripe --reference   # the second pack: idempotency
+```
+
+## Why not a mock server
+
+Pointing a mock or a sandbox at your application gives you a substrate: somewhere to make calls
+that will not touch production. You still have to know which calls to make, what should happen,
+and whether what happened was right. That is the part voeu does, and it is three things a mock
+does not have.
+
+**A verdict, not a transcript.** Fourteen scenarios ask questions with a right answer — does a job
+enqueued before expiry still work when the queue reaches it, can an older session write overwrite
+newer credentials — and each returns `passed`, `failed`, `not_applicable` or `not_verified` with
+the consequence spelled out. A mock replies to requests; it has no opinion about whether your
+handling of the reply was correct.
+
+**A contract you can audit.** Every rule the simulator encodes is written down as data: the
+statement, the Shopify document it came from, the constant it became, and the checks that stop
+being believable if it moves. Run `voeu contract` and argue with it in five minutes instead of
+reading a state machine. A mock's behaviour is whatever somebody typed into it, with no record of
+why.
+
+**An alarm when the rule moves.** Shopify changed the refresh recovery window from 60 minutes to
+30 days on 28 August 2026 — no migration required, nothing to do, and no reason for anybody to
+notice that results verified the week before were verified against a rule that no longer existed.
+`voeu watch` re-reads every cited document nightly and downgrades the checks that rested on a
+phrase which has disappeared. A mock configured against the old rule keeps passing, confidently,
+forever.
+
+The first is why a run is worth reading. The third is why it is worth keeping.
+
+## `inspect`
+
+Static. Reads source only — never executes your code, never calls a model, never needs a
+credential. Runs in seconds on a repository it has never seen.
+
+```
+  voeu inspect — acme/inventory-sync
+
+  stack     @shopify/shopify-app-remix ^5.0.1 · prisma sessions · distribution unknown
+  contract  shopify-token-lifecycle@0.1.0
+
+  FAILED   Session model is missing refreshToken and refreshTokenExpires
+           prisma/schema.prisma:10
+  FAILED   Credential enqueued into deferred work via syncQueue.add
+           app/jobs/sync.server.ts:12:41
+  UNPROVEN No recognised per-shop serialisation around token refresh
+           Procfile:1
+
+  4 failed · 2 unproven
+
+  Static analysis only. Nothing in this repository was executed.
+  Run `voeu verify` to decide the unproven checks.
+```
+
+Because it reads source only, `inspect` is safe to run on a fork-originated pull request.
+
+## `verify`
+
+Executes your application against a simulator that encodes Shopify's token lifecycle — 60-minute
+access tokens, 90-day single-use refresh tokens, the
+[2026-08-28 recovery window](https://shopify.dev/changelog/more-resilient-refreshes-for-expiring-offline-access-tokens),
+and the failure modes you cannot provoke on your own: 5xx, rate limits, timeouts, and **lost
+responses**, where the provider commits and your code never learns what happened.
+
+Fourteen scenarios ask questions source cannot answer:
+
+| Family | What the Shopify pack asks |
+|---|---|
+| `credential-lifecycle` | Does the pair survive expiry, restart, a transient 5xx, and a lost refresh response? |
+| `deferred-execution` | Does a job enqueued before expiry still work when the queue reaches it? |
+| `concurrency` | Do two processes refreshing one shop converge on one live pair — and can an older session write overwrite newer credentials? |
+| `partial-failure` | Does a failed session write strand the shop? Is an ambiguous conversion replayed? |
+| `tenant-isolation` | Can one merchant's credential serve another? |
+
+Those five are the families that apply to Shopify's token lifecycle. The taxonomy has a sixth —
+`retry-identity` — which does not, and is reported as not applicable rather than silently absent.
+It is the main one the Stripe pack asks about, where the equivalent failure is a retry that mints
+a fresh idempotency key and bills the customer twice.
+
+`verify` needs one thing from you: an adapter. `voeu init` writes a starter one, already wired to
+whatever `inspect` could find:
+
+```
+$ npx @voeu/cli init --repo .
+  wrote    voeu.config.json  points verify at the adapter below
+  wrote    voeu/adapter.ts   wired to your Prisma session storage; queue methods left as TODO
+
+  Before `voeu verify` will run:
+    - enqueueJob() and runJobs() must call your real queue. Left as TODO because a
+      guess here would make the deferred-execution scenarios test the guess.
+```
+
+The adapter is yours from the moment it exists — checked in, never regenerated, never overwritten.
+That seam is deliberate: a harness that supplies its own session store proves only that the store
+it supplied works. A partly-filled adapter still gives honest answers, because scenarios it cannot
+exercise report UNPROVEN rather than passing.
+
+`npx @voeu/cli verify --reference` runs the whole suite against a built-in application, so you can see
+the output before writing anything.
+
+## `watch`
+
+A verified result decays, for three reasons that have nothing to do with each other.
+Your code changes. **The provider changes.** Time passes. Only the first is visible in
+your repository, and the second is the one that took Shopify's own developers by
+surprise: the refresh recovery window changed on
+[28 August 2026](https://shopify.dev/changelog/more-resilient-refreshes-for-expiring-offline-access-tokens)
+with no migration required and no reason for anybody to notice.
+
+```bash
+npx @voeu/cli watch --record --repo .   # once. commit voeu/baseline.json
+npx @voeu/cli watch --repo .            # nightly, in CI
+```
+
+`watch` re-inspects your tree, re-reads every provider document this contract cites,
+and reports only what moved.
+
+```
+  voeu watch — acme/inventory-sync
+
+  Something moved: 4 check(s) went stale.
+
+  contract  shopify-token-lifecycle@0.1.0
+  deadline  114 days to 1 January 2027
+
+  SAME     shopify.dev/docs/.../migrate-to-expiring-offline-access-tokens
+  DRIFTED  shopify.dev/changelog/more-resilient-refreshes-...
+           Text this contract depends on is no longer in the document:
+           "limited to 30 days from the original refresh token".
+```
+
+Two strengths of alarm, and only one of them is loud. **EDITED** means the page changed
+but every phrase the contract depends on is still there — worth a read, not evidence
+that a rule moved. **DRIFTED** means a phrase this contract rests on is gone, and every
+check resting on it is downgraded from passed to unverified until a human looks.
+
+Three rules make this usable rather than noisy:
+
+- **A phrase is only armed if it was seen to match when you recorded.** A guessed phrase
+  that never matched cannot tell drift from a bad guess, so it is reported as an unwatched
+  claim instead of firing on day one. When this file was first written it claimed the
+  migration guide said "60 minutes" and "90 days". It says neither — both numbers live in
+  the changelogs — and `--record` caught it in under a minute.
+- **A document that could not be read is never reported as unchanged.** It gets its own
+  state, because "we could not check" and "nothing changed" are different sentences.
+- **Nothing re-records itself.** A watch that acknowledged the drift it found would be a
+  green light wired to its own alarm.
+
+A finding that was already in your baseline does not fail the job. `watch` answers "has
+anything changed?", not "is this broken?" — a nightly job that is red every night is a
+nightly job that gets switched off.
+
+## `contract`
+
+The simulator is only worth trusting if you can check it, so every rule it encodes is
+written down as data: the statement, the Shopify document it came from, the constant it
+became, and the checks that stop being believable if it moves.
+
+```bash
+npx @voeu/cli contract          # all of it
+npx @voeu/cli contract --open   # only where the documentation is ambiguous
+```
+
+The `--open` list is the part nobody volunteers. Three of the claims rest on a reading
+rather than a rule — including the status code Shopify returns for a rejected refresh,
+which no page states and which applications branch on. Each one names the request
+sequence that would settle it against a real store.
+
+## `differential`
+
+The one command that can catch **Voeu** being wrong.
+
+```bash
+npx @voeu/cli differential --self-check   # no credentials. proves the comparison works.
+npx @voeu/cli differential --live         # a development store you own. proves the contract.
+```
+
+Every `verify` result rests on the simulator being a faithful account of Shopify, and
+until it has been compared against a real store that is an assertion rather than
+evidence. `--live` runs the contract's open questions against a development store and
+reports where the two disagree — as a finding **about the simulator**, never about your
+application.
+
+`--self-check` needs nothing. It runs the probes against the simulator twice, which must
+agree, and then against mutations of it that answer an open question the other way, which
+must be detected. That establishes the comparison works. It establishes nothing about
+Shopify, and it says so on every run.
+
+## `fix`
+
+Emits a patch for the findings that are deterministic — the two columns Shopify documents, the
+flag Shopify documents, and the additive migration to go with them. No model is involved, so the
+patch is reproducible from your commit.
+
+It never edits your working tree. It writes a patch, **re-runs the same checks over the patched
+tree**, and reports only what the re-check confirms. Findings it cannot repair safely — a
+credentialed client at module scope, a credential in a queue payload — are declined explicitly
+with reasons, because a repair tool that quietly skips the hard finding leaves you believing it
+was handled.
+
+## GitHub Action
+
+```yaml
+- uses: Solus-QE/voeu@v0
+  with:
+    command: inspect
+    distribution: public   # optional; see below
+```
+
+Writes `run.json` and a self-contained `report.html`, adds a job summary, and uploads both as an
+artifact.
+
+The Action lives in a repository that is not yet public, so `uses: Solus-QE/voeu@v0` resolves only
+for workflows in that account until it is. Everything the Action does, the CLI does directly:
+
+```yaml
+- run: npx @voeu/cli@0.1 inspect --repo . --out voeu-run
+```
+
+exits `1` on a failing check, `2` when the target could not be assessed, and leaves
+`voeu-run/inspect.json` and `voeu-run/report.html` to upload with `actions/upload-artifact`.
+
+### Reporting a run to Voeu Cloud
+
+The hosted product reads your repository's archive and never executes it, so every verdict it
+shows is static. `verify` is the runtime answer, and it runs in your CI. To put its result beside
+the hosted inspect on the repository's page:
+
+```yaml
+jobs:
+  verify:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write          # the only credential: GitHub's id-token for this run
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Solus-QE/voeu@v0
+        with:
+          command: verify
+          upload: "true"
+```
+
+The Action asks GitHub for an OIDC id-token with the `voeu` audience and POSTs the run with it.
+Voeu verifies the token's signature, issuer and audience and takes the repository from its
+`repository_id` claim — nothing in the run itself decides where it lands. There is no secret to
+configure, and nothing to rotate. Fork-triggered workflows are never issued an id-token, which is
+why this runs on `push` and not `pull_request`. Reporting never fails the job: a missing
+permission, a repository without the Voeu GitHub App, or an unreachable endpoint is a warning in
+the log, and the run's own exit code is unaffected.
+
+## Exit codes
+
+| | |
+|---|---|
+| `0` | no failing check. For `watch`: the baseline still holds |
+| `1` | at least one check failed. For `watch`: the baseline no longer holds |
+| `2` | unsupported target or missing configuration |
+| `3` | infrastructure failure |
+
+`2` is deliberately not `1`. "We could not assess this" is not "your app is broken," and CI that
+conflates them teaches people to ignore the tool. The Action leaves the job green on `2` with a
+notice.
+
+## Four verdicts, never three
+
+`passed` · `failed` · `not_applicable` · **`not_verified`**
+
+`not_verified` is the load-bearing one. It means the check is in scope, applies to your
+repository, and was not decided — the budget ran out, the stack was unsupported, an adapter
+capability was missing. Folding it into `passed` is how a verification tool starts lying; folding
+it into `failed` is how it starts crying wolf. It gets its own state and it is printed.
+
+Every finding also carries **how** it was reached — `static`, `simulated`, or `live` — because
+"this patch is verified" without an evidence level attached is the sentence this tool exists to
+stop people from saying.
+
+## What it will not tell you
+
+- **Whether your app is publicly distributed.** `shopify.app.toml` has no `distribution` field;
+  the setting lives in the Dev Dashboard and is not recoverable from source. Pass
+  `--distribution public` if you know, or treat findings as conditional.
+- **That your migration is complete.** `verify` proves fourteen behaviours held against a
+  simulator. It does not cover webhook verification, online sessions, billing, or Admin API
+  operations beyond the one used to prove authentication.
+- **That the simulator is right.** Where it diverges from Shopify, results are wrong with it.
+  Every report says so, and `voeu differential --live` is the command that closes it —
+  built, self-tested, and waiting on a Partner account rather than on more code. Until
+  that has run, no result in this repository carries the `live` evidence level.
+
+Voeu also never runs token conversion against your installed merchants. Conversion is
+[one-time and irreversible per shop](https://github.com/Shopify/shopify-app-js/blob/main/packages/apps/shopify-api/docs/reference/auth/migrateToExpiringToken.md);
+that call stays yours to make.
+
+## Contract packs
+
+Two, and they ask different questions — because the failure a provider can hand you is a
+property of that provider, not a house style.
+
+| Pack | Asks | Families exercised |
+|---|---|---|
+| `shopify-token-lifecycle@0.1.0` | Does your app survive a credential that expires, rotates, and can be lost mid-refresh? | credential-lifecycle, deferred-execution, concurrency, partial-failure, tenant-isolation |
+| `stripe-idempotency@0.1.0` | Across a retry, does an operation keep its identity — and does a genuinely new one get a fresh one? | retry-identity, partial-failure, tenant-isolation |
+
+Wrong in one direction bills the customer twice; wrong in the other silently no-ops. Neither is
+visible in the source, which is why the Stripe pack exists at all.
+
+```bash
+npx @voeu/cli verify --provider stripe --reference
+```
+
+**What the Stripe pack does not do yet, stated plainly.** It runs against the built-in reference
+application only. Verifying *your* Stripe integration needs an adapter interface this CLI does not
+yet document, a scaffold for `voeu init`, and static detectors so `inspect` has something to say.
+None of those are written, so `--provider stripe --repo .` exits 2 and says so rather than
+reporting every scenario `not_verified` while looking supported.
+
+`voeu contract --provider stripe` does work: it prints seven claims quoted from Stripe's
+idempotency reference, two of them carrying an open question that a live account would settle.
+
+`credential-lifecycle` and `deferred-execution` are reported **not applicable** for Stripe rather
+than omitted: secret keys do not expire or rotate on a schedule, and an absence that looks like
+coverage is the thing the four verdicts exist to prevent.
+
+## Requirements
+
+Node 22 or later. One runtime dependency.
+
+## Corrections
+
+If a finding is wrong, it is wrong in a way that matters, and a correction is more useful than a
+polite silence.

package/dist/build-info.json

@@ -0,0 +1,8 @@
+{
+  "version": "0.1.0",
+  "bytes": 252644,
+  "externals": [
+    "ts-parser"
+  ],
+  "inputs": 43
+}