zero-swift 0.1.0 → 0.2.0

package/README.md

@@ -6,6 +6,7 @@ truth, and this tool generates what the Swift client needs from them.
 
 ```sh
 npm install --save-dev zero-swift
+npx zero-swift --help
 ```
 
 It needs Node 22.18 or later, which loads TypeScript files directly. It also
@@ -36,7 +37,28 @@ npx zero-swift codegen --check    # fails when the output is out of date
 `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.
+Every key is optional:
+
+| Key                           | Default             | Meaning                                   |
+| ----------------------------- | ------------------- | ----------------------------------------- |
+| `schema`                      | `schema.ts`         | The TypeScript schema module              |
+| `export`                      | `schema`            | The module export that holds the schema   |
+| `output`                      | `Schema.swift`      | The Swift file to write                   |
+| `schemaName`                  | `app`               | The `ZeroSchema` static, `ZeroSchema.app` |
+| `zql`                         | `zql`               | The global query builder, of type `ZQL`   |
+| `typePrefix`                  | none                | Prepended to every generated type name    |
+| `access`                      | `public`            | `public` or `internal`                    |
+| `tables.<t>.type`             | `<t>` in PascalCase | The row struct's name                     |
+| `tables.<t>.columns.<c>.type` | from the schema     | `int` or `double`                         |
+
+Rename a row struct whose name clashes with a type you use. A table named
+`list` generates `struct List`, which hides SwiftUI's `List`; set
+`tables.list.type` to `NoteList`, or set a `typePrefix`.
+
+Each config key has an option, such as `--schema-file`, `--out`,
+`--type-prefix`, and `--access`, that overrides it. `--config` picks the
+config file. Run `npx zero-swift codegen --help` for the full list.
+`--schema <path>` from 0.1.0 still works, as `--schema-file`.
 
 ## `zero-swift drift record`
 
@@ -59,3 +81,11 @@ The samples module's default export holds:
 
 Record again whenever either side changes. `--check` fails when the recorded
 file is out of date.
+
+## Output and agents
+
+The CLI is built on [incur](https://github.com/wevm/incur). Errors print a
+code and a message and exit 1, with no stack trace. `--json` (or `--format`)
+prints the result as JSON, for scripts and CI. `--llms` prints a manifest of
+the commands for a coding agent, and `npx zero-swift skills add` installs
+them as an agent skill.

package/dist/bin.js

@@ -4,7 +4,62 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { relative, resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
-import { parseArgs } from "node:util";
+import { Cli, z } from "incur";
+
+// package.json
+var package_default = {
+  name: "zero-swift",
+  version: "0.2.0",
+  description: "Generates the Swift row types and schema of a Zero app for the Zero Swift client.",
+  license: "Apache-2.0",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/wevm/zero.git",
+    directory: "packages/zero-swift-cli"
+  },
+  bin: {
+    "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 --external:incur",
+    test: "vitest run",
+    generate: "UPDATE_GENERATED=1 vitest run",
+    "check-types": "tsc",
+    lint: "oxlint --quiet --config ../../oxlint.config.ts src/",
+    format: "oxfmt .",
+    "check-format": "oxfmt --check .",
+    "version-packages": "cd ../.. && pnpm dlx @changesets/cli@3.0.3 version && jq -r .version packages/zero-swift-cli/package.json > swift/VERSION"
+  },
+  dependencies: {
+    incur: "0.7.1",
+    typescript: "6.0.3"
+  },
+  devDependencies: {
+    "@rocicorp/zero": "workspace:*",
+    "@types/node": "^22.19.19",
+    esbuild: "0.28.2",
+    oxfmt: "^0.74.0",
+    vitest: "^5.0.0",
+    "zero-schema": "workspace:*",
+    "zero-types": "workspace:*",
+    zql: "workspace:*"
+  },
+  peerDependencies: {
+    "@rocicorp/zero": ">=1.11.0"
+  },
+  engines: {
+    node: ">=22.18"
+  }
+};
 
 // src/generate.ts
 var reservedTypeNames = /* @__PURE__ */ new Set([
@@ -567,14 +622,32 @@ function aliasName(type) {
 }
 
 // src/cli.ts
+var UsageError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+};
+function mustExist(path, code, message) {
+  if (!existsSync(path)) {
+    throw new UsageError(code, message);
+  }
+}
 async function codegenFile(config, cwd) {
   const schemaPath = resolve2(cwd, config.schema ?? "schema.ts");
+  mustExist(
+    schemaPath,
+    "SCHEMA_NOT_FOUND",
+    `Schema ${relative(cwd, schemaPath)} doesn't exist. Pass --schema-file, or set "schema" in zero-swift.json.`
+  );
   const exportName = config.export ?? "schema";
   const module = await import(pathToFileURL(schemaPath).href);
   const schema = module[exportName];
   if (!schema || typeof schema !== "object" || !("tables" in schema)) {
-    throw new Error(
-      `${schemaPath} does not export a schema as "${exportName}"`
+    throw new UsageError(
+      "SCHEMA_NOT_EXPORTED",
+      `${relative(cwd, schemaPath)} does not export a schema as "${exportName}". Pass --export, or set "export" in zero-swift.json.`
     );
   }
   const customTypes = readCustomTypes(schemaPath, exportName);
@@ -585,65 +658,156 @@ async function codegenFile(config, cwd) {
     relative(cwd, schemaPath).replaceAll("\\", "/")
   );
 }
-async function main(argv) {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    allowPositionals: true,
-    options: {
-      schema: { type: "string" },
-      out: { type: "string" },
-      config: { type: "string" },
-      samples: { type: "string" },
-      check: { type: "boolean" }
+async function reporting(fail, body) {
+  try {
+    return await body();
+  } catch (e) {
+    if (e instanceof UsageError) {
+      return fail({ code: e.code, message: e.message });
     }
-  });
-  const [command = "codegen", subcommand] = positionals;
-  const cwd = process.cwd();
-  if (command === "drift" && subcommand === "record") {
-    const { recordDriftFile } = await import("./drift-S756Q2ZA.js");
-    const vectors = await recordDriftFile(
-      resolve2(cwd, values.samples ?? "drift-samples.ts")
-    );
-    return writeOutput(
-      resolve2(cwd, values.out ?? "drift-vectors.json"),
-      vectors,
-      values.check ?? false,
-      cwd
-    );
+    throw e;
   }
-  if (command !== "codegen") {
-    process.stderr.write(`Unknown command "${positionals.join(" ")}"
-`);
-    return 2;
-  }
-  const configPath = values.config ?? (existsSync(resolve2(cwd, "zero-swift.json")) ? "zero-swift.json" : void 0);
-  const fileConfig = configPath ? JSON.parse(readFileSync(resolve2(cwd, configPath), "utf8")) : {};
-  const config = {
-    ...fileConfig,
-    ...values.schema ? { schema: values.schema } : {},
-    ...values.out ? { output: values.out } : {}
-  };
-  const output = resolve2(cwd, config.output ?? "Schema.swift");
-  const swift = await codegenFile(config, cwd);
-  return writeOutput(output, swift, values.check ?? false, cwd);
 }
-function writeOutput(output, contents, check, cwd) {
+function writeOutput(fail, output, contents, check2, cwd) {
+  const path = relative(cwd, output);
   const current = existsSync(output) ? readFileSync(output, "utf8") : void 0;
-  if (check) {
+  if (check2) {
     if (current !== contents) {
-      process.stderr.write(`${relative(cwd, output)} is out of date
-`);
-      return 1;
+      return fail({
+        code: "OUT_OF_DATE",
+        message: `${path} is out of date. Run the command again without --check to update it.`
+      });
     }
-    return 0;
+    return { path, upToDate: true };
   }
   if (current !== contents) {
     writeFileSync(output, contents);
   }
-  process.stdout.write(`Wrote ${relative(cwd, output)}
-`);
-  return 0;
+  return { path, written: current !== contents };
+}
+function legacyArgv(argv) {
+  if (argv[0] !== "codegen") return [...argv];
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    const next = argv[i + 1];
+    if (token === "--schema" && next !== void 0 && !next.startsWith("-")) {
+      out.push("--schema-file", next);
+      i++;
+    } else if (token.startsWith("--schema=")) {
+      out.push("--schema-file", token.slice("--schema=".length));
+    } else {
+      out.push(token);
+    }
+  }
+  return out;
 }
+var check = z.boolean().optional().describe("Fail when the output is out of date instead of writing it");
+var cli = Cli.create("zero-swift", {
+  version: package_default.version,
+  description: "Generates what the Zero Swift client needs from a Zero app's TypeScript schema, queries, and mutators."
+}).command("codegen", {
+  description: "Generate the Swift row types, schema, and query builder from the app's TypeScript schema. Options override zero-swift.json, which is read when present.",
+  options: z.object({
+    config: z.string().optional().describe("Config file (default zero-swift.json, when present)"),
+    schemaFile: z.string().optional().describe("TS schema module (default schema.ts)"),
+    export: z.string().optional().describe("Export of the module that holds the schema (default schema)"),
+    out: z.string().optional().describe("Swift file to write (default Schema.swift)"),
+    schemaName: z.string().optional().describe("Name of the generated ZeroSchema static (default app)"),
+    zql: z.string().optional().describe("Name of the generated query builder global (default zql)"),
+    typePrefix: z.string().optional().describe("Prefix for every generated type name (default none)"),
+    access: z.enum(["public", "internal"]).optional().describe("Access level of the generated code (default public)"),
+    check
+  }),
+  examples: [
+    { description: "Generate from zero-swift.json" },
+    {
+      options: {
+        schemaFile: "shared/schema.ts",
+        out: "Sources/App/Schema.swift"
+      },
+      description: "Generate without a config file"
+    },
+    {
+      options: { check: true },
+      description: "Fail in CI when the output is stale"
+    }
+  ],
+  run: (c) => reporting(c.error, async () => {
+    const cwd = process.cwd();
+    const {
+      config: configOption,
+      schemaFile,
+      out,
+      check: check2,
+      ...overrides
+    } = c.options;
+    const configPath = configOption ?? (existsSync(resolve2(cwd, "zero-swift.json")) ? "zero-swift.json" : void 0);
+    if (configPath) {
+      mustExist(
+        resolve2(cwd, configPath),
+        "CONFIG_NOT_FOUND",
+        `Config ${configPath} doesn't exist.`
+      );
+    }
+    const fileConfig = configPath ? JSON.parse(readFileSync(resolve2(cwd, configPath), "utf8")) : {};
+    const config = {
+      ...fileConfig,
+      ...Object.fromEntries(
+        Object.entries(overrides).filter(([, v]) => v !== void 0)
+      ),
+      ...schemaFile ? { schema: schemaFile } : {},
+      ...out ? { output: out } : {}
+    };
+    const swift = await codegenFile(config, cwd);
+    return writeOutput(
+      c.error,
+      resolve2(cwd, config.output ?? "Schema.swift"),
+      swift,
+      check2 ?? false,
+      cwd
+    );
+  })
+});
+cli.command(
+  Cli.create("drift", {
+    description: "Record what the TS queries and mutators do, for the Swift drift test (Drift.failures in ZeroTesting)."
+  }).command("record", {
+    description: "Run the app's TS queries and mutators on the samples a module exports, and write what they did.",
+    options: z.object({
+      samples: z.string().optional().describe("Samples module (default drift-samples.ts)"),
+      out: z.string().optional().describe("Vectors file to write (default drift-vectors.json)"),
+      check
+    }),
+    examples: [
+      {
+        options: {
+          samples: "drift-samples.ts",
+          out: "Tests/AppTests/drift-vectors.json"
+        },
+        description: "Record the drift vectors"
+      }
+    ],
+    run: (c) => reporting(c.error, async () => {
+      const cwd = process.cwd();
+      const samples = resolve2(cwd, c.options.samples ?? "drift-samples.ts");
+      mustExist(
+        samples,
+        "SAMPLES_NOT_FOUND",
+        `Samples file ${relative(cwd, samples)} doesn't exist. Pass --samples.`
+      );
+      const { recordDriftFile } = await import("./drift-S756Q2ZA.js");
+      const vectors = await recordDriftFile(samples);
+      return writeOutput(
+        c.error,
+        resolve2(cwd, c.options.out ?? "drift-vectors.json"),
+        vectors,
+        c.options.check ?? false,
+        cwd
+      );
+    })
+  })
+);
 
 // src/bin.ts
-process.exitCode = await main(process.argv.slice(2));
+await cli.serve(legacyArgv(process.argv.slice(2)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-swift",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Generates the Swift row types and schema of a Zero app for the Zero Swift client.",
   "license": "Apache-2.0",
   "repository": {
@@ -16,15 +16,16 @@
   ],
   "type": "module",
   "dependencies": {
+    "incur": "0.7.1",
     "typescript": "6.0.3"
   },
   "devDependencies": {
-    "@types/node": "^22.10.5",
+    "@types/node": "^22.19.19",
     "esbuild": "0.28.2",
-    "oxfmt": "^0.65.0",
+    "oxfmt": "^0.74.0",
     "vitest": "^5.0.0",
-    "zero-schema": "0.0.0",
     "@rocicorp/zero": "1.12.0",
+    "zero-schema": "0.0.0",
     "zql": "0.0.0",
     "zero-types": "0.0.0"
   },
@@ -35,7 +36,7 @@
     "node": ">=22.18"
   },
   "scripts": {
-    "build": "esbuild src/bin.ts --bundle --platform=node --format=esm --target=node22 --splitting --outdir=dist --external:@rocicorp/zero --external:typescript",
+    "build": "esbuild src/bin.ts --bundle --platform=node --format=esm --target=node22 --splitting --outdir=dist --external:@rocicorp/zero --external:typescript --external:incur",
     "test": "vitest run",
     "generate": "UPDATE_GENERATED=1 vitest run",
     "check-types": "tsc",