@pithy-sh/cli 0.1.0

package/src/test-utils/migrateHarness.ts

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { Migration } from "kysely/migration";
+import { afterEach, beforeEach } from "vitest";
+import { type MigrationFanOutOptions, readProjectLedger, type WorkerScope } from "../migrations/run";
+
+/**
+ * Shared scaffolding for the `migrateProject` suites, extracted so those suites can live in more
+ * than one file.
+ *
+ * Splitting them is a speed decision, not a taste one. Vitest parallelizes across test *files* and
+ * runs the tests inside one file in sequence, and every `migrateProject` call spawns its own
+ * Miniflare — so a single file holding all of them serializes ~30 workerd boots. Measured before
+ * the split: `migrations/run.test.ts` took 21.1s, of which the `fan-out over workers` group alone
+ * was 11.8s, and it set the floor for the whole package's 28.0s node suite. One file per heavy
+ * group lets those groups run at the same time.
+ */
+
+/**
+ * The pending half of {@link readProjectLedger}, for the suites that assert how far a schema is behind.
+ * The other half — a migration the ledger records and the project no longer declares — has its own
+ * suite in `migrations/ledger.test.ts`, because it is a refusal rather than a number.
+ */
+export const pendingFrom = async (options: MigrationFanOutOptions): Promise<number> => {
+  const ledger = await readProjectLedger(options);
+  // These suites migrate databases they created a moment ago, so every one of them answers. A `partial`
+  // here is the harness reporting a sum with a hole in it, and asserting a number against that would be
+  // the #371 defect wearing a test's clothes — so it fails loudly instead (#371).
+  if (ledger.state !== "read") {
+    throw new InternalError({
+      message: "The migration harness could not read every database's ledger.",
+      action: "Check the fixture's wrangler.jsonc bindings — a database in scope did not answer.",
+      detail: `readProjectLedger returned state ${ledger.state}`,
+    });
+  }
+  return ledger.pending;
+};
+
+/** Creates a one-column table — the smallest migration that proves `up`/`down` ran. */
+export const createTable = (name: string): Migration => ({
+  up: async (db) => {
+    await db.schema
+      .createTable(name)
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .execute();
+  },
+  down: async (db) => {
+    await db.schema.dropTable(name).execute();
+  },
+});
+
+/** The `things` table migration, used by the default `app` capability. */
+export const createThings = createTable("things");
+
+/** A capability with one database on `DB` — the project's baseline registry. */
+export function appCapability(): Capability {
+  return defineCapability({
+    name: "app",
+    requiredBindings: [],
+    databases: {
+      app: { binding: "DB", tables: {}, migrations: { "0001_things": createThings }, migrationOrder: 1000 },
+    },
+  });
+}
+
+/** A second capability, on its own binding by default — the other worker's registry. */
+export function multiplayerCapability(binding = "COLLAB_DB"): Capability {
+  return defineCapability({
+    name: "multiplayer",
+    requiredBindings: [],
+    databases: {
+      collab: {
+        binding,
+        tables: {},
+        migrations: { "0001_rooms": createTable("rooms") },
+        migrationOrder: 500,
+      },
+    },
+  });
+}
+
+/** A throwaway project directory and the workers inside it, rebuilt per test. */
+export interface MigrateHarness {
+  /** The project root. A getter: `beforeEach` makes a new temp directory for every test. */
+  readonly projectDir: string;
+  /** The project's one worker, `apps/api`, composing `capabilities`. */
+  api(capabilities: Capability[]): WorkerScope;
+  /** A second worker, `apps/<name>`, so the fan-out has something to fan out over. */
+  worker(name: string, capabilities: Capability[]): Promise<WorkerScope>;
+}
+
+/**
+ * Registers the per-test temp project and returns the accessors the suites use. Call it once at
+ * `describe` scope; `projectDir` is a getter because each test gets a fresh directory, so a plain
+ * value captured at import would go stale after the first test.
+ */
+export function migrateHarness(): MigrateHarness {
+  let dir = "";
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "pithy-migrate-"));
+    await mkdir(join(dir, "apps", "api"), { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  return {
+    get projectDir(): string {
+      return dir;
+    },
+    api(capabilities: Capability[]): WorkerScope {
+      return { name: "api", dir: join(dir, "apps", "api"), capabilities };
+    },
+    async worker(name: string, capabilities: Capability[]): Promise<WorkerScope> {
+      const workerDir = join(dir, "apps", name);
+      await mkdir(workerDir, { recursive: true });
+      return { name, dir: workerDir, capabilities };
+    },
+  };
+}

package/src/test-utils/seedHarness.ts

@@ -0,0 +1,173 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { D1Database, KVNamespace } from "@cloudflare/workers-types";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import { d1SeedGroup, defineSeed, kvSeedGroup } from "@pithy-sh/core/src/seed/seed";
+import type { Migration } from "kysely/migration";
+import { Miniflare } from "miniflare";
+import { afterEach, beforeEach } from "vitest";
+import { z } from "zod";
+import type { WorkerScope } from "../migrations/run";
+
+/**
+ * Shared scaffolding for the `seedProject` suites, extracted so those suites can live in more than
+ * one file.
+ *
+ * Splitting them is a speed decision, not a taste one. Vitest parallelizes across test *files* and
+ * runs the tests inside one file in sequence, and every `seedProject`/`migrateProject` call spawns
+ * its own Miniflare — so a single file holding all of them serializes dozens of workerd boots.
+ * Measured before the split: `seed/run.test.ts` took 25.1s, of which `--redo` was 10.1s and
+ * `fan-out over workers` 9.6s, and it set the floor for the whole package's 28.0s node suite.
+ *
+ * See `test-utils/migrateHarness.ts` for the same treatment of the migration suites.
+ */
+
+/** A tiny two-column table — the D1 seed target. */
+export const Things = z.object({
+  id: z.number().int().describe("Auto-increment primary key."),
+  name: z.string().describe("The thing's name."),
+});
+
+/** The migration that creates the `things` table so a seed has somewhere to land. */
+export const createThings: Migration = {
+  up: async (db) => {
+    await db.schema
+      .createTable("things")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("name", "text", (c) => c.notNull())
+      .execute();
+  },
+  down: async (db) => {
+    await db.schema.dropTable("things").execute();
+  },
+};
+
+/** A typed KV store — the KV seed target. */
+export const notesStore = {
+  prefix: "notes",
+  key: z.object({ slug: z.string().describe("The note's slug segment.") }),
+  value: z.object({ body: z.string().describe("The note's body.") }),
+};
+
+/** The one worker's `wrangler.jsonc` for a local run: a D1 on `DB`, a KV on `CACHE`. */
+export const localWrangler = {
+  d1_databases: [{ binding: "DB", database_id: "db-local" }],
+  kv_namespaces: [{ binding: "CACHE", id: "cache-local" }],
+};
+
+/** A capability that both declares the `things` table / `notes` store and seeds them. */
+export function dataCapability(
+  environments: readonly string[] = ["dev", "staging"],
+  rows: readonly { id: number; name: string }[] = [
+    { id: 1, name: "one" },
+    { id: 2, name: "two" },
+  ],
+): Capability {
+  return defineCapability({
+    name: "app",
+    requiredBindings: [],
+    databases: {
+      app: {
+        binding: "DB",
+        tables: { things: Things },
+        migrations: { "0001_things": createThings },
+        migrationOrder: 1000,
+      },
+    },
+    kvNamespaces: { cache: { binding: "CACHE", stores: { notes: notesStore } } },
+    seeds: [
+      defineSeed({
+        name: "demo",
+        order: 1000,
+        environments,
+        d1: [d1SeedGroup("app", "things", Things, rows)],
+        kv: [kvSeedGroup("cache", "notes", notesStore, [{ key: { slug: "a" }, value: { body: "hello" } }])],
+      }),
+    ],
+  });
+}
+
+/** A fresh Miniflare over a seed run's persisted state, for reading back what the seed wrote. */
+export interface LocalStores {
+  /** The `DB` database, as the seeder wrote it. */
+  d1: D1Database;
+  /** The `CACHE` namespace, as the seeder wrote it. */
+  kv: KVNamespace;
+  /** Shuts the reader down — always call it, or the workerd process outlives the test. */
+  dispose: () => Promise<void>;
+}
+
+/** A throwaway project directory and the workers inside it, rebuilt per test. */
+export interface SeedHarness {
+  /** The project root. A getter: `beforeEach` makes a new temp directory for every test. */
+  readonly projectDir: string;
+  /** The one worker's directory — `apps/api`, under the project root. Also a getter. */
+  readonly workerDir: string;
+  /** The project's one worker, composing `capabilities`. */
+  api(capabilities: Capability[]): WorkerScope;
+  /** A second worker in `apps/<name>`, sharing the project root's local stores. */
+  worker(name: string, capabilities: Capability[], config?: unknown): Promise<WorkerScope>;
+  /** Writes the one worker's `wrangler.jsonc`. */
+  writeWrangler(config: unknown): Promise<void>;
+  /** Opens a fresh Miniflare over the same persisted state to read back what a seed wrote. */
+  openLocal(): Promise<LocalStores>;
+}
+
+/**
+ * Registers the per-test temp project and returns the accessors the suites use. Call it once at
+ * `describe` scope; the directories are getters because each test gets fresh ones, so a plain value
+ * captured at import would go stale after the first test.
+ */
+export function seedHarness(): SeedHarness {
+  let dir = "";
+  let workerDir = "";
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "pithy-seed-run-"));
+    workerDir = join(dir, "apps", "api");
+    await mkdir(workerDir, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  return {
+    get projectDir(): string {
+      return dir;
+    },
+    get workerDir(): string {
+      return workerDir;
+    },
+    api(capabilities: Capability[]): WorkerScope {
+      return { name: "api", dir: workerDir, capabilities };
+    },
+    async worker(name: string, capabilities: Capability[], config?: unknown): Promise<WorkerScope> {
+      const target = join(dir, "apps", name);
+      await mkdir(target, { recursive: true });
+      await writeFile(join(target, "wrangler.jsonc"), JSON.stringify(config ?? localWrangler));
+      return { name, dir: target, capabilities };
+    },
+    async writeWrangler(config: unknown): Promise<void> {
+      await writeFile(join(workerDir, "wrangler.jsonc"), JSON.stringify(config));
+    },
+    async openLocal(): Promise<LocalStores> {
+      const state = join(dir, ".wrangler", "state", "v3");
+      const mf = new Miniflare({
+        modules: true,
+        script: "export default {};",
+        d1Databases: { DB: "db-local" },
+        kvNamespaces: { CACHE: "cache-local" },
+        d1Persist: join(state, "d1"),
+        kvPersist: join(state, "kv"),
+      });
+      return {
+        d1: (await mf.getD1Database("DB")) as unknown as D1Database,
+        kv: (await mf.getKVNamespace("CACHE")) as unknown as KVNamespace,
+        dispose: () => mf.dispose(),
+      };
+    },
+  };
+}

package/src/test-utils/tempRepo.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { rm } from "node:fs/promises";
+
+/**
+ * The two halves of "a test made a git repository in a temp directory and then deleted it", which is a
+ * race unless both are handled.
+ *
+ * ## Why a repo is not an ordinary directory to delete
+ *
+ * `git commit` can leave work running after it exits. Auto-maintenance — `gc --auto`, and the
+ * commit-graph and `pack-refs` steps under it — is spawned in the background and detached, so the
+ * command returns while a second process is still writing inside `.git`. A recursive delete that starts
+ * in that window unlinks a directory's contents, then finds a file back in it, and `rmdir` fails:
+ *
+ * ```
+ * Error: ENOTEMPTY: directory not empty, rmdir '/tmp/pithy-pack-ke283n/checkout/.git/info'
+ * ```
+ *
+ * It reproduces on a loaded machine and essentially never on an idle one, which is why it arrived from
+ * CI rather than from anybody's laptop.
+ *
+ * ## Both halves, because either alone is a coin flip
+ *
+ * {@link GIT_NO_MAINTENANCE} removes the cause: with `gc.auto=0` and `maintenance.auto=false` there is no
+ * second process to race. {@link removeTempDir} survives it anyway — Node's `rm` retries exactly the
+ * errno family this produces (`ENOTEMPTY`, `EBUSY`, `EPERM`, `EMFILE`), and it defaults to **no** retries.
+ *
+ * Configuration is passed per invocation rather than written into the repo, so it holds for `init`
+ * itself. A `git config` line lands after the repository already exists, which is one command too late.
+ */
+export const GIT_NO_MAINTENANCE = ["-c", "gc.auto=0", "-c", "maintenance.auto=false"] as const;
+
+/**
+ * Delete a temp directory, tolerating a writer that has not finished.
+ *
+ * `force` so a directory already gone is not an error — a test that cleans up twice, or one whose
+ * fixture never got created, should not fail in teardown. The retries are the part that matters: ten
+ * attempts over roughly a second, which is far longer than any background git step needs and still short
+ * enough that a genuinely stuck delete fails the suite rather than hanging it.
+ */
+export async function removeTempDir(path: string): Promise<void> {
+  await rm(path, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+}

package/src/tokens/config.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ProfileOverride } from "@pithy-sh/cloudflare/src/tokens/profiles";
+import type { ProjectConfig } from "../project/config";
+
+/**
+ * Build the engine's profile-override resolver from `pithy.config.ts`'s `tokens.overrides`. A profile
+ * with no configured override resolves to `undefined` (its predefined defaults stand). This is the
+ * config half of overriding a profile; a `--permission` / `--store` flag is the per-mint half and
+ * wins over this.
+ */
+export function tokenOverrideResolver(config: ProjectConfig): (profile: string) => ProfileOverride | undefined {
+  const overrides = config.tokens?.overrides ?? {};
+  return (profile) => overrides[profile];
+}