@ultimat3/cli 5.0.1 → 7.0.0

package/src/templates/scaffold-db-package.ts

@@ -13,6 +13,37 @@ import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shap
 
 const DESCRIPTION = 'Entity re-exports and SQL migrations, no business logic';
 
+/**
+ * The example slice's entity lives in `apps/web/app/post/`, so `src/schema.ts` re-exports it from
+ * there — an edge this manifest has to declare or it exists only inside the root tsconfig's
+ * `paths`, where `bun --filter` and every change-detection tool are blind to it
+ * (`X_WORKSPACE_DEP_UNDECLARED`). Written here rather than through `workspacePackageJson` for the
+ * reason `scaffold-i18n.ts` states: that helper is the dependency-free shape.
+ *
+ * Under `--no-example` there is no entity and no import, so there is no dependency either: a pin
+ * for an edge the package does not have is the same lie in the other direction.
+ */
+const dbPackage = (app: NameSet, example: boolean): string =>
+  example
+    ? `{
+  "name": "@${app.kebab}/db",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "${DESCRIPTION}",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
+  },
+  "dependencies": {
+    "@${app.kebab}/web": "0.0.0"
+  }
+}
+`
+    : workspacePackageJson(app, 'db', DESCRIPTION);
+
 const dbIndex =
   (): string => `// Schema and migrations only — no business logic lives in this package. The client itself is
 // @ultimat3/db's: one connection pool, sized by ROLE, shared by every package in the app.
@@ -28,20 +59,6 @@ export * as schema from './schema';
 const SCHEMA_HEADER = `// Every entity the app declares, re-exported here. This list is what the migration generator
 // reads, so an entity that is not exported here does not exist as far as the database is concerned.`;
 
-/**
- * `bun run db:seed`'s entry point. Identical either way — only the rows differ. Interpolated, not
- * nested, so it carries exactly the escaping a single template literal needs.
- */
-const SEED_MAIN = `
-
-if (import.meta.main) {
-  const count = await seed();
-  // Bun's stdout, not process.stdout: one runtime, one API. Awaited because the write resolves
-  // asynchronously, and this JSON line is the whole output of \`bun run db:seed\`.
-  await Bun.stdout.write(\`\${JSON.stringify({ ok: true, seeded: count })}\\n\`);
-}
-`;
-
 const dbSchema = (app: NameSet, example: boolean): string =>
   example
     ? `${SCHEMA_HEADER}
@@ -52,38 +69,70 @@ export { post } from '@${app.kebab}/web/app/post/entity';
 export {};
 `;
 
+/**
+ * The seed, as a `defineSeed()` — which is what `x db seed` discovers and what the framework has
+ * meant by "a seed" since 2.0.0.
+ *
+ * It used to be a plain `export async function seed()` with an `import.meta.main` block, run by a
+ * `bun run db:seed` npm script, and that shipped two defects at once. `x db seed` discovers
+ * every `seed*.ts` under a package's `src` and looks for an exported `Seed`, so the scaffold's
+ * own seed was invisible to its own command — `x db seed` on a fresh app answered "no seed
+ * matched".
+ * And `bun run db:seed` reaches the database through `@ultimat3/db`'s `db()`, which reads
+ * `DATABASE_URL` and speaks `postgres:` only, so on a clone with no Postgres it cannot see the
+ * embedded PGlite that `x db migrate` had just migrated in process. `bin/setup` therefore printed
+ * `✓ migrations applied` and then died on `X_DB_UNAVAILABLE`, whose `fix:` says "run `x dev` to use
+ * the embedded PGlite" — naming the mechanism that had just worked one line above.
+ *
+ * `x db seed` owns the connection, the tier and the per-seed transaction. One runner, one answer.
+ */
 const dbSeed = (app: NameSet, example: boolean): string =>
   example
-    ? `// Deterministic seed: same rows every time, so a test and a demo see the same database.
-import { db, sql } from '@ultimat3/db';
-
-const ORG = '00000000-0000-0000-0000-000000000002';
+    ? `// Deterministic fixtures: the same rows every time, so a test, a demo and a branch database
+// all see the same content.
+//
+// \`x db seed\` is the runner — it discovers every exported \`defineSeed()\` in a package's
+// \`src/seed*.ts\`, opens the database exactly as \`x db migrate\` does (embedded PGlite
+// included), and wraps each seed in its own transaction. Never a plain \`bun run\` script: that
+// reaches the database through \`db()\`, which needs a \`postgres:\` \`DATABASE_URL\` and so cannot
+// see the embedded database at all.
+import { defineSeed } from '@ultimat3/entity';
+import { post } from './schema';
 
-export async function seed(): Promise<number> {
-  const rows = [
-    { id: '00000000-0000-0000-0000-000000000101', title: 'Hello ${app.pascal}', minor: 0 },
-    { id: '00000000-0000-0000-0000-000000000102', title: 'Second post', minor: 1900 },
-  ];
-  for (const row of rows) {
-    // Idempotent by primary key, so re-seeding a branch database is a no-op rather than a crash.
-    await db().execute(sql\`
-      insert into posts (id, org_id, title, price_minor, price_currency)
-      values (\${row.id}, \${ORG}, \${row.title}, \${row.minor}, 'USD')
-      on conflict (id) do nothing\`);
-  }
-  return rows.length;
-}${SEED_MAIN}`
-    : `// Deterministic seed: same rows every time, so a test and a demo see the same database.
-// No entity is declared yet, so there is nothing to insert — the shape stays, so the first
-// \`x g entity\` has one obvious place to seed from.
+/** Stable across runs: \`id('post:hello')\` is a UUID v5 of the label, not a random one. */
+export const ${app.camel}Seed = defineSeed('${app.kebab}', async ({ insert, id }) => {
+  await insert(post, [
+    {
+      id: id('post:hello'),
+      orgId: id('org:demo'),
+      title: 'Hello ${app.pascal}',
+      price: { minor: 0, currency: 'USD' },
+    },
+    {
+      id: id('post:second'),
+      orgId: id('org:demo'),
+      title: 'Second post',
+      price: { minor: 1900, currency: 'USD' },
+    },
+  ]);
+});
+`
+    : `// Deterministic fixtures, run by \`x db seed\`. No entity is declared yet, so there is nothing
+// to insert — the shape stays so the first \`x g entity\` has one obvious place to seed from.
+//
+// \`x db seed\` discovers every exported \`defineSeed()\` in a package's \`src/seed*.ts\` and opens
+// the database the way \`x db migrate\` does, embedded PGlite included. Never a plain \`bun run\`
+// script: that needs a \`postgres:\` \`DATABASE_URL\` and cannot see the embedded database.
+import { defineSeed } from '@ultimat3/entity';
 
-export async function seed(): Promise<number> {
-  return 0;
-}${SEED_MAIN}`;
+export const ${app.camel}Seed = defineSeed('${app.kebab}', async () => {
+  // \`await insert(<entity>, [...])\` once an entity exists.
+});
+`;
 
 /** Every file the `packages/db` workspace ships, in the order `x new` writes them. */
 export const dbPackageFiles = (app: NameSet, example: boolean): readonly GeneratedFile[] => [
-  { path: 'packages/db/package.json', contents: workspacePackageJson(app, 'db', DESCRIPTION) },
+  { path: 'packages/db/package.json', contents: dbPackage(app, example) },
   ...packageShapeFiles(app, 'db', DESCRIPTION),
   { path: 'packages/db/src/index.ts', contents: dbIndex() },
   { path: 'packages/db/src/schema.ts', contents: dbSchema(app, example) },

package/src/templates/scaffold-docs.ts

@@ -88,7 +88,11 @@ bun install
 # this script is documented idempotent, and the guard is what makes that true here.
 ls packages/db/migrations/*.sql >/dev/null 2>&1 || bunx x db gen "initial"
 bunx x db migrate "$@"
-bun run db:seed
+# \`x db seed\`, never \`bun run\`: the CLI owns the connection, so this reaches the same embedded
+# PGlite the migration above just wrote to. A plain script goes through \`db()\`, which needs a
+# \`postgres:\` DATABASE_URL and so dies on a clone with no Postgres — one line after reporting a
+# successful migration.
+bunx x db seed
 echo "setup complete — next: x dev"
 `;
 
@@ -103,6 +107,19 @@ const binCheck = (): string => `#!/usr/bin/env bash
 # The gate. Same steps as CI, because a check that lives only in CI cannot be run locally.
 set -euo pipefail
 cd "$(dirname "$0")/.."
+# The build FIRST, and not as a convenience: \`x verify\`'s budgets step compares declared limits
+# against measured bytes in .x/build-stats.json, so with no build it reports X_BUDGET_UNMEASURED and
+# the very first gate anyone runs on a brand-new app is red for a reason that has nothing to do with
+# their code. Cheap on a warm tree, and it makes "green" reachable from a fresh clone.
+#
+# \`--json\` is forwarded to BOTH, or the contract breaks: \`bin/check --json\` would otherwise print
+# the build's human renderer to stdout and then the gate's JSON, and a machine consumer reading one
+# document off stdout gets neither. Both commands emit one object; a reader takes the last line.
+build_flags=""
+for arg in "$@"; do
+  case "$arg" in --json|-j) build_flags="--json" ;; esac
+done
+bunx x build --target static $build_flags
 exec bunx x verify "$@"
 `;
 

package/src/templates/scaffold-i18n.ts

@@ -87,8 +87,15 @@ export type AppCatalog = typeof en;
 export type TranslationKey = KeyOf<AppCatalog>;
 
 /**
- * Use this, never \`useI18n()\` directly — the type parameter is what makes an unknown key a
- * compile error instead of a \`⟦key⟧\` someone notices in production.
+ * The app's ONE way to read a string. Never \`useI18n()\` directly and never \`t\` from
+ * \`@ultimat3/i18n\`, for two independent reasons:
+ *
+ * 1. the type parameter makes an unknown key a compile error instead of a \`⟦key⟧\` someone
+ *    notices in production;
+ * 2. importing THIS module is what registers the catalogs — \`defineCatalogs()\` above runs on
+ *    import and nowhere else. A page that reached past it rendered every string as \`⟦key⟧\`
+ *    with \`x verify\` green, because nothing in the app depended on the module that registers
+ *    (issue #249). \`x i18n check\` now refuses that app; this import is why it never happens.
  */
 export const useT = (): Translator<AppCatalog> => useI18n<AppCatalog>();
 `;

package/src/templates/scaffold-mcp-package.ts

@@ -3,10 +3,43 @@
 // itself.
 
 import type { GeneratedFile, NameSet } from './naming';
-import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
+import { packageShapeFiles } from './scaffold-package-shape';
 
 const DESCRIPTION = "The app's own MCP tools";
 
+/**
+ * Writes its own manifest, for the reason `scaffold-i18n.ts` does: `workspacePackageJson` is the
+ * dependency-free shape, and this package has a real dependency — `src/index.ts` below imports the
+ * app's actions out of `apps/web/api`, because `registerActions` has to see them.
+ *
+ * The edge points AT the app, which is unusual and correct. `apps/web` is a workspace like any
+ * other; reversing it would put the tool catalog upstream of the actions it projects. Declared
+ * rather than left to the root tsconfig's `paths`: an undeclared edge resolves for `tsc` and for
+ * nothing else — not for `bun --filter` ordering, not for any tool asking what a change affects
+ * (`X_WORKSPACE_DEP_UNDECLARED`).
+ *
+ * `"0.0.0"` and not `workspace:*`: it is the version `apps/web` really carries, which is what
+ * `checkLockstep` compares a sibling pin against, and it is the one spelling every other manifest
+ * `x new` writes already uses.
+ */
+const mcpPackage = (app: NameSet): string => `{
+  "name": "@${app.kebab}/mcp",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "${DESCRIPTION}",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
+  },
+  "dependencies": {
+    "@${app.kebab}/web": "0.0.0"
+  }
+}
+`;
+
 const mcpIndex = (
   app: NameSet,
 ): string => `// The app's own MCP tools. Every action with mcp.expose is already a tool; add app-specific
@@ -42,7 +75,7 @@ unitTest('the app exposes its actions as MCP tools', () => {
 
 /** Every file the `packages/mcp` workspace ships, in the order `x new` writes them. */
 export const mcpPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
-  { path: 'packages/mcp/package.json', contents: workspacePackageJson(app, 'mcp', DESCRIPTION) },
+  { path: 'packages/mcp/package.json', contents: mcpPackage(app) },
   ...packageShapeFiles(app, 'mcp', DESCRIPTION),
   { path: 'packages/mcp/src/index.ts', contents: mcpIndex(app) },
   { path: 'packages/mcp/src/index.test.ts', contents: mcpTest() },

package/src/templates/scaffold-package-shape.ts

@@ -50,8 +50,13 @@ export const packageShapeFiles = (
 
 /**
  * The manifest every scaffolded `packages/*` carries. Private, versionless-by-convention and
- * dependency-free: these packages only re-export a framework package's types, so the one that does
- * name a dependency writes its own (`scaffold-i18n.ts`, and it says why). Lives beside
+ * dependency-free: these packages only re-export a framework package's types. Three now DO name a
+ * dependency and each writes its own manifest — `scaffold-i18n.ts`, `scaffold-mcp-package.ts` and
+ * `scaffold-db-package.ts` (the last only under `--example`, which is the branch that emits the
+ * import). Each says why at its own site. They write their own rather than taking a `dependencies`
+ * parameter here because the edge is a fact about the SOURCE that template emits, and a parameter
+ * would let a caller declare an edge its generated code does not have — which is the drift
+ * `X_WORKSPACE_DEP_UNDECLARED` exists to catch, pointed the other way. Lives beside
  * `packageShapeFiles` because every caller of one calls the other.
  */
 export const workspacePackageJson = (app: NameSet, name: string, description: string): string => `{

package/src/templates/scaffold-repo.ts

@@ -45,12 +45,12 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "lint": "biome check .",
     "test": "bun test",
     "db:migrate": "x db migrate",
-    "db:seed": "bun run packages/db/src/seed.ts"
+    "db:seed": "x db seed"
   },
   "devDependencies": {
     "@biomejs/biome": "${BIOME_VERSION}",
     "@electric-sql/pglite": "^0.5.4",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "@ultimat3/testing": "^${version}",
     "typescript": "^6.0.3"
   },

package/src/test-shards.ts

@@ -3,6 +3,7 @@
 // cmd-test.ts because a printed reproduction is only true if it carries every input to the split —
 // that rule is this file's, and argv parsing is that one's.
 
+import type { AffectedSelection } from './affected';
 import { docsFor } from './error-codes';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
@@ -72,12 +73,18 @@ export interface ReproduceOptions {
   readonly type?: TestType;
   /** Files `--sample` kept, so the rerun samples the same corpus instead of the whole type. */
   readonly sample?: number;
+  /**
+   * The `--affected` narrowing, when there was one. The fourth input to the split and the one most
+   * easily forgotten: `--affected` decides which files exist to shard at all, so a rerun without it
+   * re-splits the WHOLE corpus and its shard 2 is a different shard 2.
+   */
+  readonly affected?: AffectedSelection;
 }
 
 /**
- * Every input to the split, printed back. The type and `--filter` decide which files exist to
- * shard, `--sample` decides how many of them survive, `--workers` decides the bins — drop any one
- * and the command still runs, over a different file set, which reproduces nothing.
+ * Every input to the split, printed back. The type, `--filter` and `--affected` decide which files
+ * exist to shard, `--sample` decides how many of them survive, `--workers` decides the bins — drop
+ * any one and the command still runs, over a different file set, which reproduces nothing.
  */
 export function reproduceFor(shard: Shard, options: ReproduceOptions): string {
   return [
@@ -85,6 +92,12 @@ export function reproduceFor(shard: Shard, options: ReproduceOptions): string {
     ...(options.type === undefined ? [] : [quoteArg(options.type)]),
     ...(options.filter === undefined ? [] : ['--filter', quoteArg(options.filter)]),
     ...(options.sample === undefined ? [] : ['--sample', String(options.sample)]),
+    // `--base` is emitted always rather than only when non-default: the default is `main`, and a
+    // rerun days later against a moved `main` is a different diff wearing the same flag.
+    ...(options.affected === undefined
+      ? []
+      : ['--affected', '--base', quoteArg(options.affected.base)]),
+    ...(options.affected?.dirty === true ? ['--dirty'] : []),
     '--workers',
     String(options.workers),
     '--worker',
@@ -107,6 +120,8 @@ export interface RunShardsOptions {
    * shard of the sample and would otherwise report that shard's size as the corpus.
    */
   readonly sample?: { readonly kept: number; readonly total: number };
+  /** Passed straight to `reproduceFor`: see `ReproduceOptions.affected`. */
+  readonly affected?: AffectedSelection;
 }
 
 /** The reproduction's inputs, resolved once: `workers` is the split's real width, not the ask. */
@@ -115,6 +130,7 @@ const planOf = (options: RunShardsOptions, workers: number): ReproduceOptions =>
   ...(options.filter === undefined ? {} : { filter: options.filter }),
   ...(options.type === undefined ? {} : { type: options.type }),
   ...(options.sample === undefined ? {} : { sample: options.sample.kept }),
+  ...(options.affected === undefined ? {} : { affected: options.affected }),
 });
 
 const failureOf = (shard: Shard, code: number, plan: ReproduceOptions): Finding => ({