build(zero-swift): bundle the CLI for npm

The CLI ran from its TypeScript sources and imported other workspace
packages' sources by relative path, so it couldn't be published.
`pnpm --filter zero-swift build` now bundles bin.ts with esbuild into
dist/, leaving out typescript and @rocicorp/zero. publishConfig points
the bin at the bundle. bin.ts is the entry point because cli.ts's
own check (its URL against argv[1]) fails behind npm's .bin symlink.

@rocicorp/zero is a peer dependency (>=1.11.0, the first release with
sync protocol 53): drift record must run the app's own copy. In the
workspace, a workspace:* devDependency satisfies it.

Checked by packing the CLI and running codegen, codegen --check, and
drift record in a scratch app against @rocicorp/zero 1.11.0 from npm.
The package stays private, at 0.1.0, until the publish is approved.

Amp-Thread-ID: https://ampcode.com/threads/T-c513a037-a257-45e0-b9a9-15c15edfe859
Co-authored-by: tmm <tmm@tmm.dev>

Author: ampagent

.github/workflows/swift.yml

@@ -47,6 +47,9 @@ jobs:
         run: pnpm --filter zero-swift run test
       - name: Check types
         run: pnpm --filter zero-conformance --filter zero-swift run check-types
+      # The published CLI is a bundle; this keeps it bundling.
+      - name: Build the zero-swift CLI
+        run: pnpm --filter zero-swift run build
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: generated-vectors

packages/zero-swift-cli/README.md

@@ -0,0 +1,61 @@
+# zero-swift
+
+The command-line tool for [Zero for Swift](https://github.com/wevm/zero-swift).
+Your Zero app's TypeScript schema, queries, and mutators stay the source of
+truth, and this tool generates what the Swift client needs from them.
+
+```sh
+npm install --save-dev zero-swift
+```
+
+It needs Node 22.18 or later, which loads TypeScript files directly. It also
+needs the app's own `@rocicorp/zero`, 1.11 or later.
+
+## `zero-swift codegen`
+
+Generates Swift from the TypeScript schema. For each table it writes a row
+struct, a `ZeroSchema`, and a `zql` builder with a `Query`.
+
+```sh
+npx zero-swift codegen            # reads zero-swift.json
+npx zero-swift codegen --check    # fails when the output is out of date
+```
+
+```json
+{
+  "schema": "../web/shared/schema.ts",
+  "output": "Sources/App/Schema.swift",
+  "schemaName": "app",
+  "tables": {
+    "issue": {"columns": {"shortID": {"type": "int"}}}
+  }
+}
+```
+
+`number()` columns are `Double`. Set a column's type to `int` to make it an
+`Int`; it must then hold integers. For a `json<T>()` column whose `T` is a
+plain object or a literal union, the tool generates a `Codable` type.
+
+`--schema`, `--out`, and `--config` override the config file.
+
+## `zero-swift drift record`
+
+You write the Swift queries and mutators by hand, and the drift harness
+checks them against the TypeScript ones. This command runs the TypeScript
+definitions on samples and records what they did. `Drift.expectNoDrift` in
+the Swift `ZeroTesting` library then fails a test wherever the Swift ones
+differ.
+
+```sh
+npx zero-swift drift record --samples drift-samples.ts --out Tests/AppTests/drift-vectors.json
+```
+
+The samples module's default export holds:
+
+- `schema`
+- the `queries` and `mutators` registries
+- `querySamples`, each a name with optional `args` and `context`
+- `mutatorSamples`, each also with optional `seed` rows
+
+Record again whenever either side changes. `--check` fails when the recorded
+file is out of date.

packages/zero-swift-cli/package.json

@@ -1,14 +1,23 @@
 {
   "name": "zero-swift",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "private": true,
   "description": "Generates the Swift row types and schema of a Zero app for the Zero Swift client.",
   "license": "Apache-2.0",
   "bin": {
-    "zero-swift": "./src/cli.ts"
+    "zero-swift": "./src/bin.ts"
   },
+  "files": [
+    "dist"
+  ],
   "type": "module",
+  "publishConfig": {
+    "bin": {
+      "zero-swift": "./dist/bin.js"
+    }
+  },
   "scripts": {
+    "build": "esbuild src/bin.ts --bundle --platform=node --format=esm --target=node22 --splitting --outdir=dist --external:@rocicorp/zero --external:typescript",
     "test": "vitest run",
     "generate": "UPDATE_GENERATED=1 vitest run",
     "check-types": "tsc",
@@ -20,11 +29,19 @@
     "typescript": "6.0.3"
   },
   "devDependencies": {
+    "@rocicorp/zero": "workspace:*",
     "@types/node": "^22.10.5",
+    "esbuild": "0.27.7",
     "oxfmt": "^0.65.0",
     "vitest": "^5.0.0",
     "zero-schema": "workspace:*",
     "zero-types": "workspace:*",
     "zql": "workspace:*"
+  },
+  "peerDependencies": {
+    "@rocicorp/zero": ">=1.11.0"
+  },
+  "engines": {
+    "node": ">=22.18"
   }
 }

packages/zero-swift-cli/src/bin.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import {main} from './cli.ts';
+
+process.exitCode = await main(process.argv.slice(2));

packages/zero-swift-cli/src/cli.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
  * `zero-swift codegen`: generates the Swift row types, schema, and query
  * builder of a Zero app from its TypeScript schema.
@@ -49,7 +48,7 @@ export async function codegenFile(config: Config, cwd: string) {
   );
 }
 
-async function main(argv: string[]): Promise<number> {
+export async function main(argv: string[]): Promise<number> {
   const {values, positionals} = parseArgs({
     args: argv,
     allowPositionals: true,
@@ -120,7 +119,3 @@ function writeOutput(
   process.stdout.write(`Wrote ${relative(cwd, output)}\n`);
   return 0;
 }
-
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
-  process.exitCode = await main(process.argv.slice(2));
-}

pnpm-lock.yaml

@@ -84,8 +84,11 @@ apps/zbugs-swift/           dogfood app (iOS + macOS)
   A `package` type with `@inlinable` members must itself be
   `@usableFromInline`, or other modules silently get unspecialized calls.
 - The CLI ships as the unscoped npm package `zero-swift` (we don't own the
-  `@rocicorp` scope) with a peer dependency on `@rocicorp/zero`. It is
-  versioned with the Swift releases.
+  `@rocicorp` scope) with a peer dependency on `@rocicorp/zero` (1.11 or
+  later: `drift record` must run the app's own copy). It is versioned with
+  the Swift releases. `pnpm --filter zero-swift build` bundles it with
+  esbuild, inlining the workspace sources it imports. The package stays
+  `private` until the first publish is approved.
 - License: Apache-2.0, like this repository.
 - Docs: a DocC catalog per library product, with a getting-started article
   and a JS→Swift parity matrix (`Zero.docc/JSParity.md`). Oxfmt skips the

swift/DESIGN.md

@@ -16,7 +16,7 @@ end-to-end tests against `zero-cache` and the zbugs app.
 
 - Swift 6.2
 - iOS 26 or macOS 26. The `Zero` module also builds on Linux.
-- A `zero-cache` that speaks sync protocol 53 (Zero 1.12 or later)
+- A `zero-cache` that speaks sync protocol 53 (Zero 1.11 or later)
 
 ## Install
 
@@ -89,7 +89,7 @@ Xcode with Product › Build Documentation.
 
 | Zero for Swift | Sync protocol | `zero-cache` | Conformance vectors from |
 | -------------- | ------------- | ------------ | ------------------------ |
-| 0.1            | 53            | 1.12+        | Zero 1.12.0              |
+| 0.1            | 53            | 1.11+        | Zero 1.12 (`main`)       |
 
 ## License