@geonosis/release 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+/** The dialects the gate can route to. A dialect is never sniffed: it is what the repo declared. */
+type Dialect = 'mikro-orm-ts' | 'postgres' | 'sqlite';
+type Phase = 'down' | 'up';
+type MigrationDir = {
+    dialect: Dialect;
+    dir: string;
+    phases?: Phase[];
+    squawk?: {
+        exclude?: string[];
+    };
+};
+type ProofConfig = {
+    mustAssertVersion?: boolean;
+};
+/**
+ * Law 6: every directory, dialect, secret name and worker is an OPTION. The defaults are empty, and
+ * a command that needs one it has not got refuses with 2 rather than measuring nothing and
+ * reporting green.
+ */
+type ReleaseConfig = {
+    migrations?: MigrationDir[];
+    proof?: ProofConfig;
+    secrets?: string[];
+    steps?: string[];
+    workers?: string[];
+    wrangler?: string[];
+    wranglerEnv?: string;
+};
+type Refusal = {
+    line: number;
+    path: string;
+    verb: string;
+};
+/** A marker the gate could not believe, and the sentence saying which part it could not believe. */
+type MarkerRefusal = {
+    line: number;
+    path: string;
+    why: string;
+};
+type MigrationsReport = {
+    linted: number;
+    markers: MarkerRefusal[];
+    ok: boolean;
+    read: number;
+    refusals: Refusal[];
+    squawk: {
+        findings: string;
+        path: string;
+    }[];
+};
+
+declare const parseReleaseConfig: (raw: unknown) => ReleaseConfig;
+/** geonosis.json is where a repo says what it has. Its absence is a repo that has said nothing. */
+declare const readReleaseConfig: (root: string) => ReleaseConfig;
+
+type Declared = {
+    bindings: string[];
+    crons: string[];
+    routes: string[];
+};
+/**
+ * JSON with comments and trailing commas — which is what `wrangler.jsonc` is, and the format both
+ * consumers actually use. Strings are walked over rather than regexed around, because a `//` inside
+ * a URL is not a comment and a repo whose route was silently truncated would read as no route.
+ */
+declare const parseJsonc: (source: string) => unknown;
+/**
+ * Enough TOML for the keys a deployment drift check reads: `[table]`, `[[array of tables]]`,
+ * `key = value` with strings, numbers, booleans, arrays (multi-line included) and inline tables.
+ * It is deliberately not a TOML implementation — it exists because `wrangler.toml` is wrangler's
+ * default and refusing it outright would make this command unusable for most repos.
+ */
+declare const parseToml: (source: string) => Record<string, unknown>;
+declare const declaredIn: (config: Record<string, unknown>) => Declared;
+declare const readWrangler: (root: string, relative: string, env?: string) => Declared;
+
+/** Where a consumer's pipeline writes what it actually put in front of a user, after promote. */
+declare const DEPLOYED_FILE = ".geonosis/deployed.json";
+declare const NOTHING_SAYS = "nothing here says what is deployed \u2014 .geonosis/deployed.json is written by the pipeline after promote, and its absence is not a pass";
+type Deployed = {
+    bindings: string[];
+    crons: string[];
+    routes: string[];
+    secrets: string[];
+};
+type Drift = {
+    kind: string;
+    missing: string[];
+    extra: string[];
+};
+type DeployedReport = {
+    at?: string;
+    drift: Drift[];
+    ok: boolean;
+};
+declare const readDeployed: (root: string) => {
+    at?: string;
+    deployed: Deployed;
+};
+/**
+ * The comparison itself, over two plain shapes. Ten lines, deliberately — the doctor asks the same
+ * question of the same file, and it asks it by reading the file rather than by importing this
+ * package, so a repo can install either one alone.
+ */
+declare const driftBetween: (declared: Declared & {
+    secrets: string[];
+}, deployed: Deployed) => Drift[];
+declare const runDeployed: (input: {
+    root: string;
+}) => DeployedReport;
+declare const formatDeployed: (report: DeployedReport) => string;
+
+type MigrationsInput = {
+    dialect?: Dialect;
+    root: string;
+    since: string;
+};
+declare const runMigrations: (input: MigrationsInput) => MigrationsReport;
+declare const formatMigrations: (report: MigrationsReport) => string;
+
+/**
+ * The contract, in the only order that means anything.
+ *
+ * `upload` moves no traffic. `park` puts the new version in the deployment at 0 %, which is what
+ * makes it reachable by an override at all. `prove` reaches it and asks it who it is. `promote`
+ * swaps the pointer. Promote before prove is the whole failure this package was extracted from;
+ * park before upload is nothing.
+ */
+declare const STEPS: readonly ["upload", "park", "prove", "promote"];
+/**
+ * C1.2 of the review this was extracted from. Cloudflare documents that an override which was not
+ * applied — propagation, a malformed dictionary, a version not in the deployment — causes the
+ * request to be routed by the configured PERCENTAGES instead, silently.
+ */
+declare const WHY_VERSION_IDENTITY = "An override that was not applied routes by the configured percentages, to the OLD version \u2014 so a smoke that does not assert which version answered can pass by testing the code it was replacing.";
+type PlanReport = {
+    accepted: boolean;
+    ok: boolean;
+    problems: string[];
+    steps: string[];
+};
+declare const runPlan: (input: {
+    accept: boolean;
+    root: string;
+}) => PlanReport;
+declare const formatPlan: (report: PlanReport) => string;
+
+type Verdict = {
+    ok: boolean;
+    steps: string[];
+    why?: string;
+};
+/**
+ * One release, over one runner. The gate never invokes a platform; it asks, reads the answer, and
+ * REFUSES — and a refusal means the promote request is never written, which is the only reason the
+ * park step exists.
+ */
+declare const proveOver: (input: {
+    args?: readonly string[];
+    command: string;
+    cwd: string;
+    timeoutMs?: number;
+}) => Promise<Verdict>;
+/** The three plants, and the honest runner that must still get through. */
+declare const PLANTS: readonly [{
+    readonly name: "answered";
+    readonly says: "a smoke that answered a version other than the one it overrode to is refused";
+}, {
+    readonly name: "failed";
+    readonly says: "a smoke that did not pass is refused";
+}, {
+    readonly name: "promoted";
+    readonly says: "a promote of a version nothing proved is refused";
+}];
+type ProveOutcome = {
+    lines: string[];
+    ok: boolean;
+};
+/**
+ * A gate whose failure has never been observed is a claim, not a gate. With no runner named, each
+ * refusal is planted into the package's own stub and required to be caught — and the honest runner
+ * is required to pass, because a gate that refused everything would be as useless as one that
+ * refused nothing.
+ */
+declare const prove: (cwd: string, stub?: string) => Promise<ProveOutcome>;
+declare const formatProve: (outcome: ProveOutcome) => string;
+declare const formatVerdict: (verdict: Verdict) => string;
+
+type Request = {
+    step: 'promote';
+    versionId: string;
+} | {
+    step: 'smoke';
+    versionId: string;
+} | {
+    step: 'upload';
+};
+type Reply = Record<string, unknown>;
+/**
+ * A consumer executable speaking JSON on stdio, one request per line and one reply per line.
+ *
+ * This is the whole seam. Every platform call — `wrangler versions upload`, the override header,
+ * `versions deploy` — lives on the far side of it, in the consumer's repo, where the credentials
+ * and the knowledge of which workers exist already are. Nothing on this side has ever heard of
+ * Cloudflare.
+ */
+declare class Runner {
+    private buffered;
+    private closed;
+    private readonly child;
+    private readonly waiting;
+    constructor(command: string, args: readonly string[], cwd: string);
+    ask(request: Request, timeoutMs?: number): Promise<Reply>;
+    close(): void;
+}
+
+type Extracted = {
+    line: number;
+    sql: string;
+};
+/**
+ * Every string argument of `addSql(` inside the requested phases. Handles a template literal, a
+ * quoted string, either of them opening on the line after the call, a literal that itself spans
+ * lines, and adjacent literals joined by `+`. Everything else — an identifier holding the SQL, an
+ * interpolation — is refused by name: resolving one is a TypeScript parser, and this package will
+ * not grow one.
+ */
+declare const addSqlIn: (source: string, phases: readonly Phase[]) => Extracted[];
+
+type Marker = {
+    line: number;
+    reason: string;
+    since?: string;
+};
+declare const markersIn: (source: string) => Marker[];
+
+/**
+ * Narrowing verbs. Each removes something a version that is still serving — or one a rollback could
+ * put back — may still be reading or writing. The schema is live from the instant the migration
+ * runs, minutes before any code has been proven and for ever if the release is rolled back.
+ */
+declare const NARROWING: readonly (readonly [string, RegExp])[];
+/**
+ * Comments are where the marker lives, so they are not stripped; strings are, because a verb inside
+ * one is data, not a statement. The replacement keeps the same length AND the same newlines, so a
+ * line number counted afterwards is still the line number in the file somebody has open.
+ */
+declare const statementsOf: (sql: string) => string;
+/** One refusal per verb per file, at the line of that verb's first occurrence. */
+declare const refusalsIn: (path: string, body: string, firstLine?: number) => Refusal[];
+
+export { DEPLOYED_FILE, type Declared, type Deployed, type DeployedReport, type Dialect, type Drift, type MigrationDir, type MigrationsReport, NARROWING, NOTHING_SAYS, PLANTS, type Phase, type PlanReport, type ProveOutcome, type Refusal, type ReleaseConfig, Runner, STEPS, type Verdict, WHY_VERSION_IDENTITY, addSqlIn, declaredIn, driftBetween, formatDeployed, formatMigrations, formatPlan, formatProve, formatVerdict, markersIn, parseJsonc, parseReleaseConfig, parseToml, prove, proveOver, readDeployed, readReleaseConfig, readWrangler, refusalsIn, runDeployed, runMigrations, runPlan, statementsOf };

package/dist/index.js

@@ -0,0 +1,62 @@
+import {
+  DEPLOYED_FILE,
+  NARROWING,
+  NOTHING_SAYS,
+  PLANTS,
+  Runner,
+  STEPS,
+  WHY_VERSION_IDENTITY,
+  addSqlIn,
+  declaredIn,
+  driftBetween,
+  formatDeployed,
+  formatMigrations,
+  formatPlan,
+  formatProve,
+  formatVerdict,
+  markersIn,
+  parseJsonc,
+  parseReleaseConfig,
+  parseToml,
+  prove,
+  proveOver,
+  readDeployed,
+  readReleaseConfig,
+  readWrangler,
+  refusalsIn,
+  runDeployed,
+  runMigrations,
+  runPlan,
+  statementsOf
+} from "./chunk-2JLVQK7Y.js";
+export {
+  DEPLOYED_FILE,
+  NARROWING,
+  NOTHING_SAYS,
+  PLANTS,
+  Runner,
+  STEPS,
+  WHY_VERSION_IDENTITY,
+  addSqlIn,
+  declaredIn,
+  driftBetween,
+  formatDeployed,
+  formatMigrations,
+  formatPlan,
+  formatProve,
+  formatVerdict,
+  markersIn,
+  parseJsonc,
+  parseReleaseConfig,
+  parseToml,
+  prove,
+  proveOver,
+  readDeployed,
+  readReleaseConfig,
+  readWrangler,
+  refusalsIn,
+  runDeployed,
+  runMigrations,
+  runPlan,
+  statementsOf
+};

package/dist/release-cli.js

@@ -0,0 +1,160 @@
+import {
+  CannotRun,
+  formatDeployed,
+  formatMigrations,
+  formatPlan,
+  formatProve,
+  formatVerdict,
+  prove,
+  proveOver,
+  runDeployed,
+  runMigrations,
+  runPlan
+} from "./chunk-2JLVQK7Y.js";
+
+// src/release-cli.ts
+import { resolve } from "path";
+var USAGE = `geonosis-release <command> [options]
+
+  migrations --since <ref> [--dialect <name>] [--root <dir>] [--json]
+
+              Refuse a schema change the version that is still serving cannot survive. The schema
+              serves 100 % of traffic the instant the migration runs \u2014 before any code has been
+              proven, and for ever if the release is rolled back \u2014 so a release may only WIDEN.
+
+              Dialects are routed by geonosis.json \u2192 release.migrations[], never sniffed:
+                sqlite         the narrowing-verb check (D1 is not Postgres and squawk cannot
+                               parse it)
+                postgres       squawk-cli, its exit code and output surfaced verbatim
+                mikro-orm-ts   the SQL extracted from addSql(\u2026) in up(), read both ways
+
+              Exit 0 clean, 1 refusals, 2 the run could not be made.
+
+  plan [--root <dir>] [--i-accept-an-unproven-smoke] [--json]
+
+              The contract as data \u2014 geonosis.json \u2192 release.steps and release.proof \u2014 validated
+              and printed. upload \u2192 park \u2192 prove \u2192 promote, in that order and no other.
+
+  prove [--runner <script>] [--root <dir>] [--json]
+
+              With a runner: one release over it, refusing a smoke that answered a version other
+              than the one it overrode to, a smoke that failed, and a promote of a version nothing
+              proved. With no runner: each of those three planted into this package's own stub and
+              required to be caught.
+
+              The runner is a consumer executable speaking JSON on stdio, one request per line:
+                {"step":"upload"}                      -> {"versionId":"\u2026"}
+                {"step":"smoke","versionId":"\u2026"}       -> {"ok":true,"answeredVersionId":"\u2026"}
+                {"step":"promote","versionId":"\u2026"}     -> {"ok":true}
+
+  deployed --check [--root <dir>] [--json]
+
+              What the pipeline REPORTED deploying, in .geonosis/deployed.json, against what the
+              tree declares in the wrangler configs geonosis.json names and release.secrets.
+              \`versions upload\` applies no triggers, and a secret can be put outside the gate
+              entirely \u2014 so declared and deployed drift apart silently, with a green pipeline.
+`;
+var VALUED = /* @__PURE__ */ new Set(["--dialect", "--root", "--runner", "--since"]);
+var FLAGS = /* @__PURE__ */ new Set(["--check", "--i-accept-an-unproven-smoke", "--json"]);
+var DIALECTS = /* @__PURE__ */ new Set(["mikro-orm-ts", "postgres", "sqlite"]);
+var parseArgs = (argv) => {
+  const read = {};
+  const flags = /* @__PURE__ */ new Set();
+  let json = false;
+  for (let index = 1; index < argv.length; index += 1) {
+    const flag = argv[index] ?? "";
+    if (FLAGS.has(flag)) {
+      if (flag === "--json") json = true;
+      flags.add(flag);
+      continue;
+    }
+    if (!VALUED.has(flag)) throw new CannotRun(`unknown argument "${flag}"`);
+    const value = argv[index + 1];
+    if (value === void 0 || value.startsWith("--")) throw new CannotRun(`${flag} needs a value`);
+    read[flag] = value;
+    index += 1;
+  }
+  return { command: argv[0] ?? "", flags, json, read };
+};
+var rootOf = (parsed, cwd) => resolve(cwd, parsed.read["--root"] ?? cwd);
+var migrations = (parsed, cwd) => {
+  const since = parsed.read["--since"];
+  if (since === void 0) throw new CannotRun("migrations needs --since <ref>");
+  const dialect = parsed.read["--dialect"];
+  if (dialect !== void 0 && !DIALECTS.has(dialect)) {
+    throw new CannotRun(`--dialect must be one of ${[...DIALECTS].toSorted().join(", ")}`);
+  }
+  const report = runMigrations({
+    ...dialect === void 0 ? {} : { dialect },
+    root: resolve(cwd, parsed.read["--root"] ?? cwd),
+    since
+  });
+  process.stdout.write(
+    parsed.json ? `${JSON.stringify(report, void 0, 2)}
+` : formatMigrations(report)
+  );
+  return report.ok ? 0 : 1;
+};
+var plan = (parsed, cwd) => {
+  const report = runPlan({
+    accept: parsed.flags.has("--i-accept-an-unproven-smoke"),
+    root: rootOf(parsed, cwd)
+  });
+  process.stdout.write(
+    parsed.json ? `${JSON.stringify(report, void 0, 2)}
+` : formatPlan(report)
+  );
+  return report.ok ? 0 : 1;
+};
+var proving = async (parsed, cwd) => {
+  const root = rootOf(parsed, cwd);
+  const named = parsed.read["--runner"];
+  if (named === void 0) {
+    const outcome = await prove(root);
+    process.stdout.write(
+      parsed.json ? `${JSON.stringify(outcome, void 0, 2)}
+` : formatProve(outcome)
+    );
+    return outcome.ok ? 0 : 1;
+  }
+  const verdict = await proveOver({ command: resolve(cwd, named), cwd: root });
+  process.stdout.write(
+    parsed.json ? `${JSON.stringify(verdict, void 0, 2)}
+` : formatVerdict(verdict)
+  );
+  return verdict.ok ? 0 : 1;
+};
+var deployed = (parsed, cwd) => {
+  if (!parsed.flags.has("--check")) throw new CannotRun("deployed needs --check");
+  const report = runDeployed({ root: rootOf(parsed, cwd) });
+  process.stdout.write(
+    parsed.json ? `${JSON.stringify(report, void 0, 2)}
+` : formatDeployed(report)
+  );
+  return report.ok ? 0 : 1;
+};
+var main = async () => {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const parsed = parseArgs(argv);
+  if (parsed.command === "migrations") return migrations(parsed, process.cwd());
+  if (parsed.command === "plan") return plan(parsed, process.cwd());
+  if (parsed.command === "prove") return proving(parsed, process.cwd());
+  if (parsed.command === "deployed") return deployed(parsed, process.cwd());
+  throw new CannotRun(
+    `no command called "${parsed.command}" \u2014 this bin has migrations, plan, prove, deployed`
+  );
+};
+try {
+  process.exit(await main());
+} catch (error) {
+  process.stderr.write(`geonosis-release: ${error.message}
+`);
+  process.exit(2);
+}
+export {
+  parseArgs
+};

package/dist/stub-runner.js

@@ -0,0 +1,31 @@
+// src/stub-runner.ts
+import { createInterface } from "readline";
+var plant = (process.argv.find((one) => one.startsWith("--plant=")) ?? "--plant=good").slice(
+  "--plant=".length
+);
+var reply = (answer) => {
+  process.stdout.write(`${JSON.stringify(answer)}
+`);
+};
+createInterface({ input: process.stdin }).on("line", (line) => {
+  const request = JSON.parse(line);
+  if (request.step === "upload") {
+    reply({ versionId: "version-under-test" });
+    return;
+  }
+  if (request.step === "smoke") {
+    reply({
+      answeredVersionId: plant === "answered" ? "the-version-that-was-already-serving" : "version-under-test",
+      ok: plant !== "failed"
+    });
+    return;
+  }
+  if (request.step === "promote") {
+    reply({
+      ok: true,
+      promotedVersionId: plant === "promoted" ? "a-version-nothing-proved" : "version-under-test"
+    });
+    return;
+  }
+  reply({ ok: false });
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@geonosis/release",
+  "version": "1.1.0",
+  "types": "./dist/index.d.ts",
+  "description": "The release contract with its proofs: an expand-only migration gate over three dialects, a smoke that must name the version that answered it, and declared ≠ deployed.",
+  "keywords": [
+    "release",
+    "migrations",
+    "expand-contract",
+    "squawk",
+    "zero-downtime",
+    "gate",
+    "ci",
+    "drift"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/release",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/release"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "geonosis-release": "bin/geonosis-release.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "dependencies": {
+    "squawk-cli": "2.63.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}