@supatype/cli 0.1.7 → 0.1.9

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
     }

package/src/cache-pins.ts

@@ -1,5 +1,5 @@
 /**
- * Pin-aware cache eviction — collect `versions.*` pins across local projects (C13).
+ * Pin-aware cache eviction: collect `versions.*` pins across local projects (C13).
  */
 
 import { existsSync, readdirSync, rmSync, statSync } from "node:fs"
@@ -219,7 +219,7 @@ export function cleanCachedBinaries(options: CleanCachedBinariesOptions): CleanC
       if (!force && explicitVersion && pinned) {
         const reason = pinReason(component, version, sources) ?? "pinned"
         result.warned.push(
-          `${component}@${version} is ${reason} — removing anyway (explicit version)`,
+          `${component}@${version} is ${reason}: removing anyway (explicit version)`,
         )
       }
 

package/src/cli-artifacts.ts

@@ -0,0 +1,65 @@
+/**
+ * Names and locations of the published standalone CLI artefacts.
+ *
+ * One place, because this layout had drifted into five: the release workflow, install.sh,
+ * this module's caller, the Homebrew generator and a now-deleted second installer all
+ * described it independently, and `supatype self-update` was asking for bare executables the
+ * publisher had stopped writing. `scripts/install.sh` cannot import this (it runs before any
+ * CLI exists on the machine), so the shell keeps its own copy; what holds the two together is
+ * the round-trip test in tests/integration/scripts/cli-artifact-roundtrip.sh, not this file.
+ */
+
+import { existsSync, readdirSync } from "node:fs"
+import { currentPlatform, type PlatformId } from "./binary-cache.js"
+
+/**
+ * Which C library the running system provides. Only meaningful on Linux: Bun links
+ * libstdc++ and libgcc dynamically, so a glibc build cannot start on Alpine, and installing a
+ * glibc binary over a working musl one is how a self-update would brick an Alpine install.
+ */
+export type LibcId = "glibc" | "musl"
+
+/** Detects musl by its dynamic loader, the same signal scripts/install.sh uses. */
+export function currentLibc(platform: PlatformId = currentPlatform()): LibcId {
+  if (platform.os !== "linux") return "glibc"
+  if (!existsSync("/lib")) return "glibc"
+  try {
+    const musl = readdirSync("/lib").some((f) => f.startsWith("ld-musl-") && f.endsWith(".so.1"))
+    return musl ? "musl" : "glibc"
+  } catch {
+    return "glibc"
+  }
+}
+
+/**
+ * The archive published for a platform. Windows gets a zip because that is what Windows
+ * users can open without extra tools; everything else is a tarball. Both hold a single
+ * executable called `supatype` (`supatype.exe` on Windows), whatever the archive is named.
+ */
+export function cliArchiveName(
+  platform: PlatformId = currentPlatform(),
+  libc: LibcId = currentLibc(platform),
+): string {
+  const suffix = platform.os === "linux" && libc === "musl" ? "-musl" : ""
+  const ext = platform.os === "windows" ? "zip" : "tar.gz"
+  return `supatype-cli-${platform.os}-${platform.arch}${suffix}.${ext}`
+}
+
+/** The executable inside the archive. */
+export function cliExecutableName(platform: PlatformId = currentPlatform()): string {
+  return platform.os === "windows" ? "supatype.exe" : "supatype"
+}
+
+/** CDN path of a version's archive, relative to the CDN root. */
+export function cliArchivePath(
+  version: string,
+  platform: PlatformId = currentPlatform(),
+  libc: LibcId = currentLibc(platform),
+): string {
+  return `/cli/v${version}/${cliArchiveName(platform, libc)}`
+}
+
+/** CDN path of the checksums file covering every archive in a version. */
+export function cliChecksumsPath(version: string): string {
+  return `/cli/v${version}/checksums.sha256`
+}

package/src/cli-install-method.ts

@@ -8,9 +8,29 @@ function normalizePath(path: string): string {
   return path.replace(/\\/g, "/")
 }
 
+/**
+ * Inside a Bun-compiled binary, argv[1] is a path in the embedded filesystem, not on disk:
+ * `/$bunfs/root/supatype` on Linux and macOS, `B:/~BUN/root/supatype.exe` on Windows. No
+ * filesystem call can touch either, which is why self-update failed with
+ * `ENOENT: copyfile '/$bunfs/root/supatype'` and could never have replaced itself.
+ */
+const EMBEDDED_FS_PATH = /(^|\/)(\$bunfs|~BUN)\//i
+
+/**
+ * The executable on disk.
+ *
+ * process.execPath is the compiled binary when running one, and the Node binary otherwise, so
+ * it is only correct to prefer it when argv[1] is an embedded path. Under Node the script path
+ * is what identifies the install.
+ */
+export function runningBinaryPath(): string {
+  const main = normalizePath(process.argv[1] ?? "")
+  return EMBEDDED_FS_PATH.test(main) ? process.execPath : (process.argv[1] ?? "")
+}
+
 /** The running binary sits in an npm or workspace layout. */
 function hasNpmInstallPath(): boolean {
-  const main = normalizePath(process.argv[1] ?? "")
+  const main = normalizePath(runningBinaryPath())
   return (
     main.includes("node_modules") ||
     main.includes("/dist/cli") ||
@@ -30,7 +50,7 @@ export function looksLikeNpmOrWorkspaceCLI(): boolean {
 
 /** Homebrew / Linuxbrew Cellar layout. */
 export function looksLikeHomebrewCLI(): boolean {
-  const main = normalizePath(process.argv[1] ?? "")
+  const main = normalizePath(runningBinaryPath())
   if (!main) return false
 
   if (/(?:^|\/)Cellar\/supatype\//.test(main)) return true
@@ -44,7 +64,7 @@ export function looksLikeHomebrewCLI(): boolean {
 }
 
 /**
- * Which installer owns the running binary — this decides what `self-update`
+ * Which installer owns the running binary. This decides what `self-update`
  * tells the user to run, so it has to describe the binary on disk.
  *
  * Path shape wins over `npm_*` in the environment: those are set whenever the
@@ -62,6 +82,6 @@ export function detectCliInstallMethod(): CliInstallMethod {
 
 /** The `curl | sh` installer's default target. */
 function isStandalonePath(): boolean {
-  const main = normalizePath(process.argv[1] ?? "")
+  const main = normalizePath(runningBinaryPath())
   return main.includes("/.supatype/bin/")
 }