@geonosis/release 1.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,233 @@
+# @geonosis/release
+
+The release contract with its proofs.
+
+A release proves its **code** before serving it. Its **schema** serves immediately, to 100 % of
+traffic, while the previous version is still running — and no rollback undoes it. That sentence is
+the whole reason this package exists, and it is the sentence one consumer's adversarial review
+found its own runbook had inverted.
+
+Nothing here invokes a platform. There is no wrangler, no Railway, no `psql`. Which workers exist,
+in which order they promote, what a smoke asserts and how a version is uploaded all stay with the
+consumer; this package holds the contract, the refusals and the proofs.
+
+```bash
+geonosis-release migrations --since <ref> [--dialect <name>] [--root <dir>] [--json]
+```
+
+Exit **0** clean · **1** refusals · **2** the run could not be made.
+
+## `migrations` — expand-only, enforced
+
+For every file the diff ADDED under a directory `geonosis.json` names, in the dialect it names it
+in. A migration that already existed at the base already ran; the only SQL a release gate has an
+opinion about is the SQL it is proposing to run now.
+
+```jsonc
+{
+  "release": {
+    "migrations": [
+      { "dir": "packages/db/migrations", "dialect": "sqlite" },
+      {
+        "dir": "packages/db/migrations-tenant",
+        "dialect": "postgres",
+        "squawk": { "exclude": ["prefer-robust-stmts", "prefer-bigint-over-int"] }
+      },
+      { "dir": "packages/plugins", "dialect": "mikro-orm-ts", "phases": ["up"] }
+    ]
+  }
+}
+```
+
+Every field is an option and every default is empty. A repo that has named no directory gets exit
+2 and one line saying so — never a green run over nothing.
+
+### The dialects
+
+| `dialect` | Files | What runs |
+|---|---|---|
+| `sqlite` | `*.sql` under `dir` | the narrowing-verb check. D1 is not Postgres, and squawk cannot parse `CREATE TABLE \`account\`` at all |
+| `postgres` | `*.sql` under `dir` | `squawk-cli`, its exit code and output surfaced verbatim — it knows six things a verb list does not, three of them ways to stall a live database |
+| `mikro-orm-ts` | `*.ts` under `dir` | the SQL extracted from `addSql(…)` inside the phases, then BOTH the verb check and squawk |
+
+### The five narrowing verbs
+
+`DROP TABLE` · `DROP COLUMN` · `RENAME` · `ALTER COLUMN … TYPE` · `SET NOT NULL`.
+
+Each removes something a version that is still serving — or one a rollback could put back — may
+still be reading or writing. A refusal prints `path: verb (line)`.
+
+String literals are blanked before the search, because a verb inside one is data:
+`insert into audit values ('drop table orders')` narrows nothing. Comments are NOT blanked, because
+that is where the marker lives.
+
+### The marker
+
+```sql
+-- contract-migration: <what expanded it, and why nothing reads it any more> since:<ref>
+```
+
+`//` in a TypeScript migration. It excuses a narrowing only when **all** of the following hold, and
+names which one failed when they do not:
+
+| | |
+|---|---|
+| a reason | a marker with nothing after the colon is a comment. `\s` swallows a newline and adopts the next line as the reason, which is how a bare marker once excused the statement under it |
+| a `since:<ref>` | an expand nobody can date excuses nothing |
+| `git merge-base --is-ancestor <ref> <since>` | **the across-releases rule.** A contract is safe only once the version that still read the old shape has drained, so the ref that expanded must already be in history at this release's base. A marker naming a commit inside this very diff says "the code that stopped needing this column shipped" about code that has not shipped |
+
+A marker the gate cannot believe excuses nothing, and the narrowing it was written over is still
+reported — otherwise a typo in a ref would read as "your migration is fine".
+
+The marker is an argument about **drain**. It says nothing about locks or timeouts, so squawk's
+findings stand on an excused file: a repo that has decided about `require-lock-timeout` says so once
+in `squawk.exclude`, rather than by writing a sentence into every migration.
+
+### `phases`
+
+Default `["up"]`. In the corpus this was built from, `down()` holds the `drop table` in every single
+migration file — reading it would refuse every migration in the repo, for SQL a release never runs.
+
+### The `addSql` shapes the reader handles
+
+A template literal, a quoted string, either opening on the line after the call, a literal that
+itself spans lines, and adjacent literals joined by `+`.
+
+An **identifier** argument (`this.addSql(dropOperationChecks)`) and a **template interpolation**
+are refused BY NAME with exit 2. Resolving either is name resolution — a TypeScript parser — and
+this package will not grow one. A migration nobody could read is not a migration that passed.
+
+### squawk
+
+`squawk-cli` is a pinned dependency of this package, spawned from its own `node_modules/.bin`. Its
+bin is called `squawk`, and `squawk` on a public registry is an unrelated package that exits 0 on
+anything — a gate that passes because it linted nothing. Nothing here asks a resolver.
+
+Exit 0 is clean and exit 1 is findings. **Anything else is exit 2**, one line naming it: a linter
+that could not start has not measured, and a gate that cannot measure has not passed.
+
+## `plan` — the contract as data
+
+```jsonc
+{
+  "release": {
+    "steps": ["upload", "park", "prove", "promote"],
+    "proof": { "mustAssertVersion": true },
+    "workers": ["api", "edge", "web"]
+  }
+}
+```
+
+`upload` moves no traffic. `park` puts the new version into the deployment at 0 %, which is the only
+thing that makes it reachable by an override at all. `prove` reaches it and asks it who it is.
+`promote` swaps the pointer. Those four, in that order, and no other — a promote before its proof
+serves code nothing answered for, and a park before an upload is nothing.
+
+`proof.mustAssertVersion` is on unless a repo writes `false`, and writing `false` is refused unless
+the run also carries `--i-accept-an-unproven-smoke`, which prints why it matters.
+
+## `prove` — the runner protocol
+
+The runner is a **consumer executable** speaking JSON on stdio, one request per line and one reply
+per line. This is the whole seam: every platform call lives on the far side of it, in the repo that
+has the credentials and knows which workers exist. Nothing on this side has heard of Cloudflare.
+
+```
+→ {"step":"upload"}                    ← {"versionId":"…"}
+→ {"step":"smoke","versionId":"…"}     ← {"ok":true,"answeredVersionId":"…"}
+→ {"step":"promote","versionId":"…"}   ← {"ok":true}            (may carry "promotedVersionId")
+```
+
+The gate REFUSES, and the refusal means the next request is never written:
+
+| | |
+|---|---|
+| `answeredVersionId !== versionId` | the override did not apply and the smoke certified the version it was replacing |
+| no `answeredVersionId` at all | a smoke that cannot say who answered has proved nothing |
+| `ok: false` | the smoke failed |
+| `promotedVersionId !== versionId` | a promote went to a version nothing proved |
+
+With **no** `--runner`, the package plants each of those into its own stub runner and requires every
+one to be caught — and requires the honest runner to pass, because a gate that refused everything
+would be as useless as one that refused nothing.
+
+A runner that never answers is exit 2 inside the time it was given: a job that hangs until CI's own
+timeout kills it leaves no line anybody reads.
+
+## What this package does not cover
+
+Overrides never reach **Durable Objects**. Each DO instance is assigned a version by the deployment
+percentages, so at 0 % every workflow instance, queue consumer and cron runs the OLD code. `prove`
+proves the stateless fetch path and claims nothing more; the durable path's proof is a test suite,
+a drain discipline, and post-promotion observation.
+
+## `deployed --check` — declared ≠ deployed
+
+`versions upload` applies **no triggers**. A cron or a route edited in a wrangler config is
+therefore silently ignored in production for ever, with a green pipeline. And `wrangler secret put`
+creates AND deploys a version immediately, outside the gate entirely — which is why the versioned
+form is `wrangler versions secret put`, and why secret names are an option here rather than a key
+read out of a config that never holds them.
+
+`.geonosis/deployed.json` is what the consumer's pipeline writes **after promote**:
+
+```json
+{
+  "at": "2026-08-30T12:00:00.000Z",
+  "versions": { "api": "…" },
+  "triggers": { "crons": ["0 4 * * *"], "routes": ["api.example.test"] },
+  "secrets": ["AUTH_SECRET"],
+  "bindings": ["DB", "AUTH_KV"]
+}
+```
+
+```jsonc
+{
+  "release": {
+    "wrangler": ["apps/api/wrangler.jsonc", "apps/web/wrangler.toml"],
+    "wranglerEnv": "production",
+    "secrets": ["AUTH_SECRET", "EDGE_SECRET"]
+  }
+}
+```
+
+Drift in either direction is exit 1, listing `declared but not deployed` and
+`deployed but not declared` per kind. **The file being absent is exit 2**, not a pass: nothing there
+says what is deployed.
+
+`wranglerEnv` selects an `env.<name>` block, because named environments inherit nothing per
+binding — every block repeats what it needs, and reading the top level instead would report a
+deployment's own crons as drift.
+
+`.json` and `.jsonc` are read fully (comments and trailing commas included). `.toml` is read for
+exactly the keys this check needs — `[triggers] crons`, `routes`, and the binding lists — because
+`wrangler.toml` is wrangler's default and refusing it outright would make the command unusable;
+it is not a TOML implementation.
+
+`@geonosis/doctor` asks the same question of the same file as its `deployed` line. It reads the
+file; it does not import this package. A repo can install either one alone.
+
+## What stays with the consumer
+
+Everything that touches a platform, and everything that is a fact about one repo:
+
+| | |
+|---|---|
+| which workers exist, and in what order they promote | callee first, and the gate never learns their names |
+| how a version is uploaded, parked, overridden to, promoted | the runner, on the far side of the JSON protocol |
+| what the smoke asserts | a positive marker, a status, a signed-in render — the gate only requires that it says which version answered |
+| canary percentages, version affinity, OpenNext | not the gate's subject |
+| writing `.geonosis/deployed.json` after promote | the pipeline knows what it applied; this reads what it wrote |
+| which squawk rules a repo has decided about | `squawk.exclude`, once, in config |
+
+## Exit codes
+
+| | |
+|---|---|
+| **0** | clean |
+| **1** | refused — a narrowing, a marker nobody can believe, a smoke that certified the wrong version, drift |
+| **2** | the run could not be made: an option that was never configured, a shape the reader cannot read, a linter that would not start, a runner that never answered, no `.geonosis/deployed.json` |
+
+A gate that cannot measure has not passed. Nothing here answers 0 by default.
+
+Apache-2.0.

package/bin/geonosis-release.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
+// produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
+//
+// In the repo, `src/` sits beside `dist/`, and a dist older than src answered for a fix it did not
+// carry once (#62). The published package ships no src, so there the check is skipped.
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const newest = (dir) =>
+  existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true }).reduce((most, entry) => {
+        const at = join(dir, entry.name)
+        return Math.max(most, entry.isDirectory() ? newest(at) : statSync(at).mtimeMs)
+      }, 0)
+    : 0
+const src = join(here, '..', 'src')
+if (existsSync(src) && newest(src) > newest(join(here, '..', 'dist'))) {
+  process.stderr.write(
+    'geonosis-release: dist is older than src — run pnpm build before trusting this bin.\n',
+  )
+  process.exit(2)
+}
+
+await import('../dist/release-cli.js')