@supatype/cli 0.1.7 → 0.1.10

package/scripts/generate-homebrew-formula.mjs

@@ -1,21 +1,21 @@
 #!/usr/bin/env node
 /**
- * Generate Formula/supatype.rb for the supatype/homebrew tap repo.
+ * Generate Formula/supatype.rb for the supatype/homebrew-tap repository.
  *
  * Usage:
- *   node packages/cli/scripts/generate-homebrew-formula.mjs 0.1.5 /path/to/artifacts
+ *   node packages/cli/scripts/generate-homebrew-formula.mjs 0.1.8 /path/to/artifacts
  *
- * Artifacts directory must contain:
- *   supatype-cli-darwin-arm64
- *   supatype-cli-darwin-amd64
- *   supatype-cli-linux-arm64
- *   supatype-cli-linux-amd64
+ * The artifacts directory is what build-release-artifacts.sh produced, so it holds the
+ * per-platform archives and the checksums.sha256 covering them. Hashes are read from that
+ * manifest rather than recomputed: the manifest is the signed record of what was published,
+ * and hashing the files again would let a formula disagree with the release it describes.
+ *
+ * Homebrew on Linux is glibc, so the -musl archives are not referenced here.
  *
  * Optional env:
- *   HOMEBREW_FORMULA_OUT — output path (default: ./Formula/supatype.rb relative to cwd)
+ *   HOMEBREW_FORMULA_OUT: output path (default: ./Formula/supatype.rb relative to cwd)
  */
 
-import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 
@@ -28,10 +28,6 @@ const PLATFORMS = [
 
 const CDN = "https://releases.supatype.com/cli"
 
-function sha256File(path) {
-  return createHash("sha256").update(readFileSync(path)).digest("hex")
-}
-
 function usage() {
   console.error(`Usage: ${process.argv[1]} <version> <artifacts-dir>`)
   process.exit(1)
@@ -45,65 +41,68 @@ const outPath =
   process.env.HOMEBREW_FORMULA_OUT?.trim() ||
   join(process.cwd(), "Formula", "supatype.rb")
 
-const checksums = {}
+const manifestPath = join(artifactsDir, "checksums.sha256")
+if (!existsSync(manifestPath)) {
+  console.error(`Missing ${manifestPath}. Run build-release-artifacts.sh first.`)
+  process.exit(1)
+}
+
+// `<hash>  <name>`, or `<hash> *<name>` when the publisher used binary mode.
+const hashes = new Map()
+for (const line of readFileSync(manifestPath, "utf8").split("\n")) {
+  const [hash, rawName] = line.trim().split(/\s+/)
+  if (hash && rawName) hashes.set(rawName.replace(/^\*/, ""), hash)
+}
+
+const archives = {}
 for (const { id } of PLATFORMS) {
-  const file = join(artifactsDir, `supatype-cli-${id}`)
-  if (!existsSync(file)) {
-    console.error(`Missing artifact: ${file}`)
+  const name = `supatype-cli-${id}.tar.gz`
+  const hash = hashes.get(name)
+  if (!hash) {
+    console.error(`No checksum for ${name} in ${manifestPath}.`)
+    console.error(`Manifest lists: ${[...hashes.keys()].join(", ")}`)
     process.exit(1)
   }
-  checksums[id] = sha256File(file)
+  archives[id] = { name, hash }
 }
 
-function urlBlock(os, arch, id) {
+function urlBlock(arch, id) {
   const indent = "    "
   const onArch = arch === "arm" ? "on_arm" : "on_intel"
   return `${indent}${onArch} do
-${indent}  url "${CDN}/v${version}/supatype-cli-${id}"
-${indent}  sha256 "${checksums[id]}"
+${indent}  url "${CDN}/v${version}/${archives[id].name}"
+${indent}  sha256 "${archives[id].hash}"
 ${indent}end`
 }
 
-const macBlocks = PLATFORMS.filter((p) => p.os === "macos")
-  .map((p) => urlBlock(p.os, p.arch, p.id))
-  .join("\n")
-
-const linuxBlocks = PLATFORMS.filter((p) => p.os === "linux")
-  .map((p) => urlBlock(p.os, p.arch, p.id))
-  .join("\n")
+const blocksFor = (os) =>
+  PLATFORMS.filter((p) => p.os === os).map((p) => urlBlock(p.arch, p.id)).join("\n")
 
+// Every archive holds one executable called `supatype`, whatever the archive is named, so the
+// install step needs no per-platform knowledge. Homebrew unpacks the tarball before `install`
+// runs, which is why this no longer renames a per-platform file.
 const formula = `# typed: false
 # frozen_string_literal: true
 
-# AUTO-GENERATED by packages/cli/scripts/generate-homebrew-formula.mjs — do not edit manually.
-# Regenerate on each cli-v* release (supatype/.github/workflows/cli-release.yml → supatype/homebrew).
+# AUTO-GENERATED by packages/cli/scripts/generate-homebrew-formula.mjs: do not edit manually.
+# Regenerated on each v* release by supatype/.github/workflows/cli-release.yml and pushed here.
 
 class Supatype < Formula
   desc "Type-first platform for PostgreSQL"
   homepage "https://supatype.com"
   version "${version}"
+  license "Apache-2.0"
 
   on_macos do
-${macBlocks}
+${blocksFor("macos")}
   end
 
   on_linux do
-${linuxBlocks}
+${blocksFor("linux")}
   end
 
   def install
-    arch = if OS.mac?
-      if Hardware::CPU.arm?
-        "darwin-arm64"
-      else
-        "darwin-amd64"
-      end
-    elsif Hardware::CPU.arm?
-      "linux-arm64"
-    else
-      "linux-amd64"
-    end
-    bin.install "supatype-cli-\#{arch}" => "supatype"
+    bin.install "supatype"
   end
 
   def post_install
@@ -118,4 +117,7 @@ end
 
 mkdirSync(dirname(outPath), { recursive: true })
 writeFileSync(outPath, formula, "utf8")
-console.log(`Wrote ${outPath}`)
+console.log(`Wrote ${outPath} for v${version}`)
+for (const { id } of PLATFORMS) {
+  console.log(`  ${archives[id].name}  ${archives[id].hash.slice(0, 16)}...`)
+}

package/scripts/mirror-deno-release.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# mirror-deno-release.sh — Download official Deno release zips and rename to Supatype CDN layout.
+# mirror-deno-release.sh: Download official Deno release zips and rename to Supatype CDN layout.
 #
 # Output binaries (cwd or $OUT_DIR):
 #   deno-linux-amd64, deno-linux-arm64, deno-darwin-amd64, deno-darwin-arm64, deno-windows-amd64.exe

package/src/TYPE-RESOLUTION.md

@@ -1,6 +1,6 @@
 # Type Resolution in the Schema Extractor
 
-`type-extractor.ts` converts TypeScript type definitions into `ExtractedSchemaAst` —
+`type-extractor.ts` converts TypeScript type definitions into `ExtractedSchemaAst`,
 the JSON handed to the engine binary for SQL generation and client type output.
 
 This document explains how type names are resolved, what patterns are supported,
@@ -12,24 +12,24 @@ and how the three-tier fallback chain works.
 
 The extractor uses the TypeScript **parser only** (`ts.createSourceFile`), not the
 full type checker. This is fast and requires no `tsconfig.json`, but it means the
-extractor only sees raw source text — it cannot evaluate what a type alias resolves to.
+extractor only sees raw source text, it cannot evaluate what a type alias resolves to.
 
 The consequence is that any indirection breaks resolution:
 
 ```typescript
-// Works — extractor sees "Optional" literally
+// Works: extractor sees "Optional" literally
 type Post = Model<{ email: Optional<Email> }>
 
-// Previously broken — extractor sees "Nullable", not "Optional"
+// Previously broken: extractor sees "Nullable", not "Optional"
 type Nullable<T> = Optional<T>
 type Post = Model<{ email: Nullable<Email> }>
 
-// Previously broken — import rename
+// Previously broken: import rename
 import { Optional as Maybe } from "@supatype/types"
 type Post = Model<{ email: Maybe<Email> }>
 ```
 
-Failures were silent — unknown types fell through to `{ kind: "text", pgType: "TEXT" }`
+Failures were silent: unknown types fell through to `{ kind: "text", pgType: "TEXT" }`
 instead of throwing an error.
 
 ---
@@ -40,18 +40,18 @@ Every type name encountered in a field definition is resolved through three tier
 in order. The first tier to succeed wins. If all three fail, an error is thrown.
 
 ```
-Tier 1 — syntactic switch      instant    inline primitives and modifiers by name
-Tier 2 — alias registry        instant    user-defined type aliases, import renames
-Tier 3 — TypeScript checker    ~300ms†    conditional types, mapped types
+Tier 1: syntactic switch      instant    inline primitives and modifiers by name
+Tier 2: alias registry        instant    user-defined type aliases, import renames
+Tier 3: TypeScript checker    ~300ms†    conditional types, mapped types
 ```
 
-† Tier 3 is **lazy** — the `ts.Program` and `TypeChecker` are only created the first
+† Tier 3 is **lazy**, the `ts.Program` and `TypeChecker` are only created the first
 time a conditional or mapped type is encountered. Schemas that use only tiers 1 and 2
 pay no cost.
 
 ---
 
-## Tier 1 — Syntactic Switch
+## Tier 1: Syntactic Switch
 
 The existing behaviour. The extractor walks the type reference chain and matches
 names exactly against a hardcoded switch:
@@ -71,12 +71,12 @@ This covers all types used inline with their canonical names.
 
 ---
 
-## Tier 2 — Alias Registry
+## Tier 2: Alias Registry
 
 Built once at startup from all source files loaded by `loadSchemaSourceFiles`.
 Covers two sub-cases:
 
-### 2a — Type alias declarations
+### 2a: Type alias declarations
 
 Any `type X = ...` that is not a `Model<>` declaration is indexed by name:
 
@@ -103,7 +103,7 @@ type B = Optional<Email>
 Cycle detection via a `resolving: Set<string>` guard prevents infinite loops and
 throws a descriptive error instead.
 
-### 2b — Import renames
+### 2b: Import renames
 
 Explicit `as` renames in import statements are indexed per file:
 
@@ -123,17 +123,17 @@ the current file. `Maybe` becomes `Optional`, `MaybeNull` becomes `Nullable`
 into the source file set and their aliases are available in the registry.
 
 Only relative specifiers (`.`-prefixed) are followed. Bare specifiers and scoped
-packages (`@supatype/types`, `node_modules/*`) are not loaded — their exported
+packages (`@supatype/types`, `node_modules/*`) are not loaded, their exported
 names are already covered by the tier 1 switch.
 
 ---
 
-## Tier 3 — TypeScript Checker
+## Tier 3: TypeScript Checker
 
 Required for types that cannot be evaluated syntactically:
 
-- **Conditional types**: `T extends U ? A : B` — requires evaluating the constraint
-- **Mapped types**: `{ [K in keyof T]: F<T[K]> }` — requires enumerating `keyof T`
+- **Conditional types**: `T extends U ? A : B`, requires evaluating the constraint
+- **Mapped types**: `{ [K in keyof T]: F<T[K]> }`, requires enumerating `keyof T`
 
 ### How it works
 
@@ -147,7 +147,7 @@ Required for types that cannot be evaluated syntactically:
 3. `checker.getTypeAtLocation(programNode)` resolves the type fully.
 
 4. `checker.typeToString(type, ..., TypeFormatFlags.UseAliasDefinedOutsideCurrentScope)`
-   converts it back to a string with **alias names preserved** — so `Optional<Email>`
+   converts it back to a string with **alias names preserved**, so `Optional<Email>`
    stays as `Optional<Email>` rather than expanding to the underlying branded
    intersection type.
 
@@ -160,7 +160,7 @@ Required for types that cannot be evaluated syntactically:
 
 - A field type is directly a conditional or mapped expression
 - A tier 2 alias body contains a conditional or mapped type (detected by
-  `needsChecker()` before text substitution is attempted — the original node,
+  `needsChecker()` before text substitution is attempted, the original node,
   which has valid source positions, is passed to the checker instead)
 - The `Model<>` fields argument is a mapped type alias:
   ```typescript
@@ -175,40 +175,40 @@ Required for types that cannot be evaluated syntactically:
 ## What Is Supported
 
 ```typescript
-// Tier 1 — inline, canonical names
+// Tier 1: inline, canonical names
 email:  Optional<Email>
 slug:   Unique<Slug<"title">>
 id:     PrimaryKey<UUID>
 
-// Tier 2a — simple alias
+// Tier 2a: simple alias
 type Nullable<T>  = Optional<T>
 type UniqueSlug   = Unique<Slug<"title">>
 email: Nullable<Email>
 slug:  UniqueSlug
 
-// Tier 2a — multi-hop
+// Tier 2a: multi-hop
 type A = B
 type B = Nullable<Email>
 email: A
 
-// Tier 2b — import rename of primitive
+// Tier 2b: import rename of primitive
 import { Optional as Maybe } from "@supatype/types"
 email: Maybe<Email>
 
-// Tier 2b — import rename of local alias
+// Tier 2b: import rename of local alias
 import { Nullable as MaybeNull } from "./field-types"
 email: MaybeNull<Email>
 
-// Tier 2b — cross-file alias (no rename)
+// Tier 2b: cross-file alias (no rename)
 // helpers.ts: export type Nullable<T> = Optional<T>
 import { Nullable } from "./helpers"
 email: Nullable<Email>
 
-// Tier 3 — conditional type
+// Tier 3: conditional type
 type NullableStr<T> = T extends string ? Optional<T> : T
 email: NullableStr<Email>
 
-// Tier 3 — mapped type as fields object
+// Tier 3: mapped type as fields object
 type AllOptional<T> = { [K in keyof T]: Optional<T[K]> }
 type Post = Model<AllOptional<{ email: Email; name: Text }>>
 ```
@@ -225,10 +225,10 @@ import { SomeHelper } from "some-library"
 // symbols only available in node_modules (other than @supatype/types)
 
 // TypeScript utility types used as field types
-email: NonNullable<string>    // error — not a @supatype/types primitive
+email: NonNullable<string>    // error, not a @supatype/types primitive
 
 // Namespace-qualified names
-email: Types.Optional<Email>  // error — only identifier references are resolved
+email: Types.Optional<Email>  // error, only identifier references are resolved
 ```
 
 ---
@@ -290,5 +290,5 @@ type CheckerContext = {
 ## Adding a New Tier 1 Primitive
 
 When a new type is added to `@supatype/types`, add a `case` to the `switch` in
-`parseScalarType`. No other changes are needed — tier 2 and tier 3 handle
+`parseScalarType`. No other changes are needed, tier 2 and tier 3 handle
 aliases and compositions of it automatically.

package/src/app/framework.ts

@@ -41,7 +41,7 @@ const FRAMEWORK_DETECTION: Array<{ dep: string; framework: AppFramework }> = [
   { dep: "@remix-run/react", framework: "remix-spa" },
   { dep: "@sveltejs/kit", framework: "sveltekit" },
   { dep: "nuxt", framework: "nuxt" },
-  // Vite last — many frameworks use Vite under the hood
+  // Vite last: many frameworks use Vite under the hood
   { dep: "vite", framework: "vite" },
 ]
 

package/src/augmentation-generator.ts

@@ -15,7 +15,7 @@ interface AstShape {
  * Shared with the hooks generator on purpose.
  *
  * A hook's `row` must be the same shape the client sees for that table, and two copies of this logic
- * would drift — the client would gain a column type the hook handler did not, which is the failure
+ * would drift: the client would gain a column type the hook handler did not, which is the failure
  * mode this codebase has already paid for once.
  */
 export function resolveTableName(model: AstModel): string {
@@ -43,7 +43,7 @@ export function generateClientAugmentation(ast: unknown): string {
     .sort((a, b) => a.tableName.localeCompare(b.tableName))
 
   const lines: string[] = []
-  lines.push("// Generated by supatype CLI — do not edit manually.")
+  lines.push("// Generated by supatype CLI, do not edit manually.")
   lines.push("")
   lines.push("declare module \"@supatype/client\" {")
   lines.push("  interface SupatypeModels {")
@@ -104,7 +104,7 @@ function toTsType(meta: Record<string, unknown>): string {
   const required = meta["required"] === true
   const base = (() => {
     // A field that knows its own shape says so. Without this, everything stored as JSONB collapses
-    // to `Record<string, unknown>` in the generated row — so `Currency` would arrive as an opaque
+    // to `Record<string, unknown>` in the generated row, so `Currency` would arrive as an opaque
     // object rather than `{ amount: string; code: "USD" }`, and the schema's precision would be
     // lost exactly where a caller reads it.
     const declared = meta["tsType"]

package/src/binary-cache.ts

@@ -1,5 +1,5 @@
 /**
- * Binary cache — manages supatype component binaries.
+ * Binary cache: manages supatype component binaries.
  *
  * Components: engine, server, postgres, deno, realtime.
  * Cache root: ~/.supatype/cache/{component}/{version}/
@@ -71,7 +71,7 @@ export function hasMeaningfulOverrides(config: SupatypeProjectConfig): boolean {
   return false
 }
 
-/** Lines for a startup banner — non-empty override paths only. */
+/** Lines for a startup banner, non-empty override paths only. */
 export function describeActiveOverrides(config: SupatypeProjectConfig): string[] {
   const o = config.overrides
   if (!o) return []
@@ -200,7 +200,7 @@ function binaryName(component: Component, version: string, platform: PlatformId)
  * Names a published archive may carry, most-canonical first.
  *
  * `supatype-postgres` published the Intel macOS archive as `darwin-x86_64` while every other platform
- * used `amd64` — the spelling the CLI derives from `process.arch === "x64"`. Releases already on the CDN
+ * used `amd64`, the spelling the CLI derives from `process.arch === "x64"`. Releases already on the CDN
  * carry the old name, so both are accepted and the *signed* checksums manifest decides which exists.
  * Nothing is guessed: the URL and the hash always come from the same manifest entry.
  */
@@ -242,9 +242,9 @@ export function currentPlatform(): PlatformId {
  * Resolve the binary path for a component.
  *
  * Resolution order:
- * 1. config.overrides?.[component] — local build path (must exist)
+ * 1. config.overrides?.[component]: local build path (must exist)
  * 2. Cached binary at ~/.supatype/cache/{component}/{version}/
- * 3. Throws — caller should call download() first.
+ * 3. Throws, so the caller should call download() first.
  *
  * Hard error if any meaningful `overrides` entry is set while the project is linked to cloud
  * (`project.ref`, `.supatype/cloud.json`, or `.supatype/linked.json`).
@@ -352,7 +352,7 @@ async function acquireDownloadSlot(
 
     if (isDownloadInProgress(component, version)) {
       console.log(
-        `[supatype] ${component} v${version} is downloading in another process — waiting...`,
+        `[supatype] ${component} v${version} is downloading in another process, waiting...`,
       )
       const outcome = await waitForComponentDownload(component, version, isReady, (c) => {
         console.log(`[supatype] Still waiting for ${c} download...`)
@@ -364,7 +364,7 @@ async function acquireDownloadSlot(
         )
       }
       console.warn(
-        `[supatype] ${component} v${version} download did not finish in the other process — retrying.`,
+        `[supatype] ${component} v${version} download did not finish in the other process, retrying.`,
       )
       continue
     }
@@ -384,7 +384,7 @@ export async function download(
 ): Promise<string> {
   if (version === VERSION_PIN_LOCAL) {
     throw new Error(
-      `cannot download CDN binary when version is "${VERSION_PIN_LOCAL}" — set overrides.${component === "postgres" ? "postgres_dir" : component} or pin a semver`,
+      `cannot download CDN binary when version is "${VERSION_PIN_LOCAL}": set overrides.${component === "postgres" ? "postgres_dir" : component} or pin a semver`,
     )
   }
 
@@ -400,7 +400,7 @@ export async function download(
       return destPath
     }
     console.warn(
-      `[supatype] ${component} v${version} cache invalid — re-downloading (${destPath}).`,
+      `[supatype] ${component} v${version} cache invalid, re-downloading (${destPath}).`,
     )
     unlinkSync(destPath)
   }
@@ -461,7 +461,15 @@ export async function download(
  * Fetch checksums.sha256, optionally verify its minisign signature, and
  * return the expected SHA256 for `binaryFilename`.
  */
-async function fetchChecksums(
+/**
+ * Fetch a checksums manifest and verify its minisign signature, returning the entry for one of
+ * `binaryFilenames`.
+ *
+ * Exported so the standalone CLI download path enforces the same rule as component downloads.
+ * It previously verified nothing at all, which made the CLI stricter about a postgres archive
+ * than about overwriting its own executable.
+ */
+export async function fetchChecksums(
   checksumsUrl: string,
   minisigUrl: string,
   binaryFilenames: string | string[],
@@ -476,16 +484,16 @@ async function fetchChecksums(
   if (!pubKey) {
     // Fail closed: a missing public key means we cannot verify authenticity, only
     // integrity (SHA256). Published builds always embed the key, so this only
-    // happens in source/contributor builds — never silently downgrade.
+    // happens in source/contributor builds. Never silently downgrade.
     if (process.env["SUPATYPE_ALLOW_UNVERIFIED_DOWNLOADS"] === "1") {
       console.warn(
-        "[supatype] \u26a0  SUPATYPE_ALLOW_UNVERIFIED_DOWNLOADS=1 — no minisign public " +
+        "[supatype] \u26a0  SUPATYPE_ALLOW_UNVERIFIED_DOWNLOADS=1: no minisign public " +
           "key configured; verifying SHA256 only (authenticity NOT checked).",
       )
       return extractChecksum(checksumsText, binaryFilenames)
     }
     throw new Error(
-      "No minisign public key configured — cannot verify release authenticity.\n" +
+      "No minisign public key configured, so cannot verify release authenticity.\n" +
         "Published @supatype/cli builds embed the key automatically; if you are building " +
         "from source, set SUPATYPE_RELEASE_PUBLIC_KEY to the release public key, or set " +
         "SUPATYPE_ALLOW_UNVERIFIED_DOWNLOADS=1 to download with SHA256-only verification (unsafe).",
@@ -511,7 +519,7 @@ async function fetchChecksums(
 // ---------------------------------------------------------------------------
 
 /**
- * Ed25519 SPKI DER prefix — wraps a raw 32-byte public key into the
+ * Ed25519 SPKI DER prefix, wraps a raw 32-byte public key into the
  * SubjectPublicKeyInfo structure that Node.js crypto.createPublicKey expects.
  *
  * Breakdown:
@@ -539,7 +547,7 @@ export function verifyMinisign(fileBytes: Buffer, sigFileContent: string, pubKey
 
   // Parse signature file:
   //   line 0: untrusted comment
-  //   line 1: base64 sig bytes — [2 algo][8 keyId][64 Ed25519 sig]
+  //   line 1: base64 sig bytes: [2 algo][8 keyId][64 Ed25519 sig]
   //   line 2: trusted comment
   //   line 3: base64 global sig (over sig bytes + trusted comment)
   const sigLines = sigFileContent.trim().split("\n")
@@ -552,12 +560,12 @@ export function verifyMinisign(fileBytes: Buffer, sigFileContent: string, pubKey
   const signature = sigBytes.subarray(10, 74)
 
   // Both Ed25519 modes are supported:
-  //   "Ed" (0x45, 0x64) — legacy: signature is over the raw file bytes.
-  //   "ED" (0x45, 0x44) — prehashed: signature is over BLAKE2b-512(file).
+  //   "Ed" (0x45, 0x64) legacy: signature is over the raw file bytes.
+  //   "ED" (0x45, 0x44) prehashed: signature is over BLAKE2b-512(file).
   // Modern minisign (and our release pipeline) default to prehashed mode.
   if (algo[0] !== 0x45 || (algo[1] !== 0x64 && algo[1] !== 0x44)) {
     throw new Error(
-      "Unsupported minisign algorithm — expected Ed25519 ('Ed' legacy or 'ED' prehashed).\n" +
+      "Unsupported minisign algorithm, expected Ed25519 ('Ed' legacy or 'ED' prehashed).\n" +
         `Got: 0x${algo[0]?.toString(16)}${algo[1]?.toString(16)}`,
     )
   }
@@ -565,7 +573,7 @@ export function verifyMinisign(fileBytes: Buffer, sigFileContent: string, pubKey
 
   if (!sigKeyId.equals(pkKeyId)) {
     throw new Error(
-      "Minisign key ID mismatch — signature was produced with a different key.\n" +
+      "Minisign key ID mismatch: the signature was produced with a different key.\n" +
         "This could indicate a compromised release. Do not proceed.",
     )
   }
@@ -582,7 +590,7 @@ export function verifyMinisign(fileBytes: Buffer, sigFileContent: string, pubKey
   const valid = cryptoVerify(null, signedData, keyObject, signature)
   if (!valid) {
     throw new Error(
-      "Minisign signature verification FAILED — the checksum file may have been tampered with.\n" +
+      "Minisign signature verification FAILED: the checksum file may have been tampered with.\n" +
         "This could indicate a supply chain attack. Aborting download.",
     )
   }
@@ -590,14 +598,21 @@ export function verifyMinisign(fileBytes: Buffer, sigFileContent: string, pubKey
 
 /**
  * Extract the SHA256 hash for `filename` from a checksums.sha256 file.
- * Format: `<hash>  <filename>` (sha256sum output, two spaces).
+ * Format: `<hash>  <filename>` (sha256sum output, two spaces), or `<hash> *<filename>` when
+ * the publisher used binary mode.
+ *
+ * Exported so the standalone CLI download path parses the manifest the same way rather than
+ * carrying a second implementation.
  */
-function extractChecksum(checksumsText: string, filenames: string | string[]): ChecksumMatch {
+export function extractChecksum(
+  checksumsText: string,
+  filenames: string | string[],
+): ChecksumMatch {
   const targets = (Array.isArray(filenames) ? filenames : [filenames]).map((f) => basename(f))
   for (const target of targets) {
     for (const line of checksumsText.split("\n")) {
       const parts = line.trim().split(/\s+/)
-      if (parts.length >= 2 && parts[1] === target) {
+      if (parts.length >= 2 && parts[1]?.replace(/^\*/, "") === target) {
         return { filename: target, checksum: parts[0]! }
       }
     }
@@ -608,7 +623,7 @@ function extractChecksum(checksumsText: string, filenames: string | string[]): C
   )
 }
 
-/** Which published name matched, and its hash — both from the same signed manifest entry. */
+/** Which published name matched, and its hash, both from the same signed manifest entry. */
 export interface ChecksumMatch {
   filename: string
   checksum: string
@@ -690,9 +705,9 @@ export function validateArtifactFormat(
 
 /**
  * Per-component CDN artifact shapes:
- *   engine, server, deno, realtime — native executable (ELF / Mach-O / PE)
- *   postgres (unix)      — .tar.gz (gzip)
- *   postgres (windows)   — .zip
+ *   engine, server, deno, realtime: native executable (ELF / Mach-O / PE)
+ *   postgres (unix)      .tar.gz (gzip)
+ *   postgres (windows)   .zip
  */
 function assertArtifactFormat(
   component: Component,
@@ -719,7 +734,7 @@ function assertGzipArchive(filePath: string): void {
     if (magic[0] !== 0x1f || magic[1] !== 0x8b) {
       throw new Error(
         "Downloaded postgres file is not a gzip archive (bad magic bytes). " +
-          "The CDN object may be corrupt or cached HTML — delete ~/.supatype/cache and retry.",
+          "The CDN object may be corrupt or cached HTML, so delete ~/.supatype/cache and retry.",
       )
     }
   } finally {
@@ -736,7 +751,7 @@ function assertZipArchive(filePath: string): void {
     if (magic[0] !== 0x50 || magic[1] !== 0x4b) {
       throw new Error(
         "Downloaded postgres file is not a zip archive (bad magic bytes). " +
-          "The CDN object may be corrupt or cached HTML — delete ~/.supatype/cache and retry.",
+          "The CDN object may be corrupt or cached HTML, so delete ~/.supatype/cache and retry.",
       )
     }
   } finally {
@@ -759,14 +774,14 @@ function assertNativeExecutable(
     if (goCArchive) {
       throw new Error(
         `Downloaded ${component} file is a Go static archive (c-archive), not an executable. ` +
-          "The CDN object may be from a bad release build — delete ~/.supatype/cache and retry.",
+          "The CDN object may be from a bad release build, so delete ~/.supatype/cache and retry.",
       )
     }
     if (platform.os === "windows") {
       if (magic[0] !== 0x4d || magic[1] !== 0x5a) {
         throw new Error(
           `Downloaded ${component} file is not a Windows PE executable (bad magic bytes). ` +
-            "The CDN object may be corrupt or cached HTML — delete ~/.supatype/cache and retry.",
+            "The CDN object may be corrupt or cached HTML, so delete ~/.supatype/cache and retry.",
         )
       }
       return
@@ -777,7 +792,7 @@ function assertNativeExecutable(
       if (!elf) {
         throw new Error(
           `Downloaded ${component} file is not an ELF executable (bad magic bytes). ` +
-            "The CDN object may be corrupt or cached HTML — delete ~/.supatype/cache and retry.",
+            "The CDN object may be corrupt or cached HTML, so delete ~/.supatype/cache and retry.",
         )
       }
       return
@@ -791,7 +806,7 @@ function assertNativeExecutable(
     if (!macho) {
       throw new Error(
         `Downloaded ${component} file is not a Mach-O executable (bad magic bytes). ` +
-          "The CDN object may be corrupt or cached HTML — delete ~/.supatype/cache and retry.",
+          "The CDN object may be corrupt or cached HTML, so delete ~/.supatype/cache and retry.",
       )
     }
   } finally {
@@ -837,7 +852,7 @@ async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
 // ---------------------------------------------------------------------------
 
 /**
- * On Windows, Git Bash represents paths as /c/Users/... — convert to C:\Users\...
+ * On Windows, Git Bash represents paths as /c/Users/..., convert to C:\Users\...
  */
 export function normalisePlatformPath(p: string): string {
   let result = p
@@ -931,7 +946,7 @@ export async function fetchAllLatestVersions(): Promise<Partial<Record<Component
  */
 /**
  * Verify cached binaries for the current platform (used by integration CI).
- * Only checks components present in `versions` — unpublished CDN components
+ * Only checks components present in `versions`; unpublished CDN components
  * (no latest.json yet) are skipped with a log so CI can land before first release.
  * Throws if a pinned component is missing from cache or fails format checks.
  */
@@ -944,7 +959,7 @@ export function verifyCachedBinaries(versions: Partial<ComponentVersions> | unde
     const version = versions[component]
     if (typeof version !== "string" || version.trim() === "") {
       console.log(
-        `[supatype] skipping verify for ${component} (no version — CDN latest.json not published yet)`,
+        `[supatype] skipping verify for ${component} (no version, CDN latest.json not published yet)`,
       )
       continue
     }