@ultimat3/cli 6.0.0 → 7.0.0

package/src/templates/resource-form-island.ts

@@ -0,0 +1,279 @@
+// The slice's client entry: `x g resource <name>` emits its form as an ISLAND, because that is the
+// one shape the framework compiles for a browser. A plain `.tsx` with a signal and an `onSubmit`
+// is not a smaller version of this — the island glob never discovers it, and a server render drops
+// every `on*` prop (`packages/render/src/html.ts`) and reads each signal exactly once.
+
+// Bun ships no path API, and the one arithmetic this file does is a specifier: the island's path
+// seen from the page's directory, which `island-bundle.ts` resolves the same way at build time.
+import { posix } from 'node:path';
+import { upToAppRoot } from './island';
+import type { GeneratedFile, NameSet } from './naming';
+
+/**
+ * What the PAGE has to write, which is not what the island's own directory would suggest.
+ *
+ * `island({ src })` resolves against the route file, and `x g resource widget` writes its page at
+ * `apps/web/app/widgets/` while the island lands in `apps/web/app/widget/` — so the `'./…'` this
+ * file used to print resolved to `apps/web/app/widgets/widget-form.island.tsx`, a path the build
+ * never bundles, and an author following the comment got `X_ISLAND_INVALID`. Derived from the two
+ * directories rather than written down, so it cannot disagree with where the files actually go.
+ */
+export const formIslandSpecifier = (feature: NameSet, dir: string, pageDir: string): string => {
+  const relative = posix.join(posix.relative(pageDir, dir), `${feature.kebab}-form.island.tsx`);
+  return relative.startsWith('.') ? relative : `./${relative}`;
+};
+
+const formIslandSource = (
+  feature: NameSet,
+  specifier: string,
+): string => `// ${feature.pascal}Form: the only module of the ${feature.kebab} slice a browser downloads.
+//
+// The page names this file by SPECIFIER, never by import — and the specifier is resolved against
+// the PAGE, which is one directory across from this one:
+//   const ${feature.pascal}Form = island({
+//     src: '${specifier}',
+//     props: ['endpoint', 'locale', 'labels'],
+//   });
+//   <${feature.pascal}Form endpoint={derivePath('create${feature.pascal}').path} locale={locale} labels={labels} />
+// A string has no import edge, so the page's bundle graph stays the page's (axiom 6).
+
+import { Button, Form, Input, setSolidRuntime, UiProvider } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import * as solidRuntime from 'solid-js';
+import { createSignal } from 'solid-js';
+import { render } from 'solid-js/web';
+import styles from './ui.module.scss';
+
+/** Every string this module renders, and the path it posts to. An island's props cross the seam as
+ *  JSON inside the document, so \`t()\`'s catalog cannot travel — the server translates. */
+export interface ${feature.pascal}FormProps {
+  /** \`derivePath('create${feature.pascal}').path\`, minted on the server: one namer for the route. */
+  readonly endpoint: string;
+  /** The request's own locale. A browser has no ambient one the server ever agreed to. */
+  readonly locale: string;
+  readonly labels: {
+    readonly title: string;
+    readonly submit: string;
+    readonly saved: string;
+    readonly retry: string;
+  };
+}
+
+type SaveState = 'idle' | 'saved' | 'failed';
+
+/**
+ * Presentation only: the action this submits to owns validation server-side, so the form never
+ * re-implements the invariant — a blank title fails at the boundary, not in the DOM.
+ *
+ * A plain \`fetch\` to the path the server minted, not the typed client: \`rpc()\` pulls
+ * \`@ultimat3/action\` into the chunk, which is larger than everything else here put together. The
+ * naming rule is still the framework's; only the transport is second.
+ */
+function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Element {
+  const [title, setTitle] = createSignal('');
+  const [state, setState] = createSignal<SaveState>('idle');
+
+  // A rejected \`fetch\` — offline, DNS, an aborted request — is the same OUTCOME as a refused one,
+  // and it is the one \`retry\` exists for. Without the catch, \`setState\` is never reached: the
+  // status line stays empty, and the rejection escapes the \`void send()\` below as an unhandled one.
+  const send = async (): Promise<void> => {
+    try {
+      const response = await fetch(props.endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ title: title() }),
+      });
+      setState(response.ok ? 'saved' : 'failed');
+    } catch {
+      setState('failed');
+    }
+  };
+
+  const status = (): string => {
+    if (state() === 'saved') return props.labels.saved;
+    return state() === 'failed' ? props.labels.retry : '';
+  };
+
+  return (
+    <Form
+      class={styles.item}
+      onSubmit={(event) => {
+        event.preventDefault();
+        void send();
+      }}
+    >
+      <Input
+        aria-label={props.labels.title}
+        value={title()}
+        onInput={(event) => setTitle(event.currentTarget.value)}
+      />
+      <Button type="submit">{props.labels.submit}</Button>
+      <p data-role="status" role="status" aria-live="polite">
+        {status()}
+      </p>
+    </Form>
+  );
+}
+
+/**
+ * The one export the hydration runtime calls — \`import(entry).then((m) => m.mount(el, props))\`.
+ *
+ * \`setSolidRuntime\` comes FIRST and it is not optional: \`@ultimat3/ui\` imports *types* from
+ * solid-js and never a runtime, so the reactive graph a component reaches is the one an entry
+ * registers. Delete the line and the first \`<UiProvider>\` render throws X_UI_RUNTIME_MISSING —
+ * loud on purpose, because a DOM render that lost its runtime is a theme toggle that does nothing.
+ *
+ * The shell is cleared first: Solid's \`render\` APPENDS when the container already has children,
+ * so without it the server's markup stays on screen above a second, live copy of the same thing.
+ */
+export function mount(el: HTMLElement, props: ${feature.pascal}FormProps): void {
+  setSolidRuntime(solidRuntime);
+  el.textContent = '';
+  render(
+    () => (
+      <UiProvider locale={props.locale}>
+        <${feature.pascal}FormBody {...props} />
+      </UiProvider>
+    ),
+    el,
+  );
+}
+`;
+
+const formIslandTest = (
+  feature: NameSet,
+  dir: string,
+): string => `// The form the browser actually runs. \`mountIsland\` builds this entry with the same
+// \`buildIslands\` that \`x build\` and \`x dev\` use, imports the emitted chunk the way the hydration
+// runtime does, and drives \`mount\` against a DOM small enough to read.
+//
+// It is the test that keeps this file a CLIENT entry. A generated form that only typechecks is
+// what shipped before: server-rendered, every \`on*\` prop dropped, every signal read once.
+
+import { join } from 'node:path';
+import { buildIslands } from '@ultimat3/cli';
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  type FakeElement,
+  type MountedIsland,
+  mountIsland,
+  test,
+} from '@ultimat3/testing';
+
+const APP_ROOT = join(import.meta.dir, ${upToAppRoot(dir)});
+const ISLAND = '${dir}/${feature.kebab}-form.island.tsx';
+const ENDPOINT = '/api/${feature.kebab}/create-${feature.kebab}';
+
+const LABELS = { title: 'Title', submit: 'Save', saved: 'Saved', retry: 'Try again' };
+
+const calls: { url: string; body: Record<string, unknown> }[] = [];
+
+/** One stub, both outcomes: the mount costs seconds, so the network's answer is a switch. */
+let networkFails = false;
+
+let mounted: MountedIsland;
+
+// The build is a Babel pass plus a browser bundle — seconds, not milliseconds. It lives in
+// \`beforeAll\` with its own timeout because \`test\` takes no third argument: fixtures are resolved
+// per case, so the slow work goes where it can be given one and every case shares the result.
+beforeAll(async () => {
+  mounted = await mountIsland({
+    build: buildIslands,
+    root: APP_ROOT,
+    file: ISLAND,
+    props: { endpoint: ENDPOINT, locale: 'en', labels: LABELS },
+    // What the server rendered inside the island's wrapper. \`mount\` replaces it.
+    shell: '<p>Loading</p>',
+    globals: {
+      fetch: (url: string, init: { body: string }): Promise<{ ok: boolean }> => {
+        calls.push({ url, body: JSON.parse(init.body) as Record<string, unknown> });
+        // What a browser rejects with when there is no network. Not a response: \`response.ok\`
+        // is never read on this path, which is exactly why the form has to catch it.
+        return networkFails
+          ? Promise.reject(new TypeError('Failed to fetch'))
+          : Promise.resolve({ ok: true });
+      },
+    },
+  });
+}, 60_000);
+
+// The fake \`document\` is process-global: left installed it reaches every LATER FILE in the run.
+//
+// \`?.\` on a binding the type says is always set: TypeScript's definite-assignment analysis does not
+// cross the \`beforeAll\` closure, so a setup that REJECTED leaves this undefined at run time — and
+// bun runs \`afterAll\` regardless. Unguarded, the build failure is followed by a \`TypeError:
+// undefined is not an object\` that says nothing, and that second line is the one a tail reads.
+// Nothing is skipped by the guard: \`mountIsland\` restores the process itself when a mount throws.
+afterAll(() => {
+  mounted?.[Symbol.dispose]();
+});
+
+/**
+ * One mount, driven as a session: the cases below run in order against the same island, because
+ * building the real chunk costs seconds and repeating it per case would pay them for state each
+ * case sets up anyway. What each one asserts is independent.
+ */
+describe('the ${feature.kebab} form island', () => {
+  test('mount replaces the server shell with the editor', () => {
+    expect(mounted.find('p')?.getAttribute('data-role')).toBe('status');
+    // Solid compiles to real DOM calls; a chunk that fell back to the classic React factory names
+    // a global that is not in it, and \`Bun.build\` answers \`success: true\` over that all the same.
+    expect(mounted.code).not.toMatch(/\\bReact\\b/);
+  });
+
+  test('the field tracks, and submit posts what was typed', async () => {
+    const field: FakeElement | null = mounted.find('input');
+    expect(field).not.toBeNull();
+    if (field !== null) field.value = 'First ${feature.camel}';
+    // \`false\` means no handler ran — an island whose onInput never reached the DOM looks
+    // identical to a selector typo otherwise.
+    expect(mounted.fire(field, 'input')).toBe(true);
+    expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
+    await Promise.resolve();
+
+    expect(calls).toEqual([{ url: ENDPOINT, body: { title: 'First ${feature.camel}' } }]);
+  });
+
+  test('the status line answers the response', () => {
+    // The signal reached the DOM: an eager JSX factory renders '' here and never runs again.
+    expect(mounted.text('[data-role="status"]')).toBe(LABELS.saved);
+  });
+
+  test('a request that never got a response still reaches retry', async () => {
+    // The outcome \`retry\` is FOR. A \`fetch\` that rejects reaches no \`response.ok\`, so without
+    // the catch in \`send\` the status line stays on its last value and the rejection escapes.
+    networkFails = true;
+    expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(mounted.text('[data-role="status"]')).toBe(LABELS.retry);
+  });
+});
+`;
+
+/**
+ * The slice's form, as the one client shape: `<dir>/<feature>-form.island.tsx` plus its test.
+ *
+ * `pageDir` is the directory of the page that declares it — the caller's, because only the caller
+ * runs both generators and knows where the other one put its file.
+ */
+export function formIslandFiles(
+  feature: NameSet,
+  dir: string,
+  pageDir: string,
+): readonly GeneratedFile[] {
+  return [
+    {
+      path: `${dir}/${feature.kebab}-form.island.tsx`,
+      contents: formIslandSource(feature, formIslandSpecifier(feature, dir, pageDir)),
+    },
+    {
+      path: `${dir}/${feature.kebab}-form.island.test.ts`,
+      contents: formIslandTest(feature, dir),
+    },
+  ];
+}

package/src/templates/resource.ts

@@ -13,7 +13,8 @@ import type { GeneratedFile, NameSet } from './naming';
 import { names, pascal } from './naming';
 import { policyFiles } from './policy';
 import { queryFiles } from './query';
-import { routeFiles } from './route';
+import { formIslandFiles } from './resource-form-island';
+import { routeDir, routeFiles } from './route';
 
 const serviceSource = (
   feature: NameSet,
@@ -142,40 +143,6 @@ export function ${feature.pascal}Card(props: ${feature.pascal}CardProps) {${tran
 }
 `;
 
-const formSource = (
-  feature: NameSet,
-  module: string | undefined,
-): string => `// Presentation only: the mutator this submits to owns validation server-side, so this form
-// never re-implements the invariant — a blank title fails at the boundary, not in the DOM.
-
-${catalogImport(module)}
-import { createSignal } from 'solid-js';
-import styles from '../ui.module.scss';
-
-export interface ${feature.pascal}FormProps {
-  readonly onSubmit: (title: string) => void;
-}
-
-export function ${feature.pascal}Form(props: ${feature.pascal}FormProps) {
-  const [title, setTitle] = createSignal('');${translatorBinding(module)}
-  return (
-    <form
-      class={styles.item}
-      onSubmit={(event) => {
-        event.preventDefault();
-        props.onSubmit(title());
-      }}
-    >
-      <label>
-        {t('app.${feature.kebab}.titleLabel')}
-        <input value={title()} onInput={(event) => setTitle(event.currentTarget.value)} />
-      </label>
-      <button type="submit">{t('app.${feature.kebab}.submit')}</button>
-    </form>
-  );
-}
-`;
-
 // `admin.<feature>.title` is always here, `--admin` or not: `defineAdmin()` resolves that key the
 // moment anyone writes the override, and a missing key renders ⟦key⟧ and fails the i18n gate,
 // while an unused key is only ever reported (`auditCatalogs` fails on `missing`, never `unused`).
@@ -185,6 +152,8 @@ const catalogSource = (feature: NameSet): string =>
     [`app.${feature.kebab}.updated`]: 'Last updated',
     [`app.${feature.kebab}.titleLabel`]: 'Title',
     [`app.${feature.kebab}.submit`]: 'Save',
+    [`app.${feature.kebab}.saved`]: 'Saved',
+    [`app.${feature.kebab}.retry`]: 'Try again',
     [`admin.${feature.kebab}.title`]: pascal(feature.plural),
   });
 
@@ -204,6 +173,10 @@ export function resourceFiles(rawName: string, target: ResourceOptions): readonl
   const feature = names(rawName);
   const slice: FeatureTarget = { surfaceDir: target.surfaceDir, feature: feature.kebab };
   const dir = `${slice.surfaceDir}/${slice.feature}`;
+  // The page this same call writes, from the function that decides where a route goes — the island
+  // specifier is resolved against it, so re-deriving the path here would be two answers to one
+  // question and only one of them reaches `routeFiles`.
+  const pageDir = routeDir('app', feature.pluralKebab);
   const locales = resolveLocales(target.locales);
   return [
     ...entityFiles(rawName, slice),
@@ -220,18 +193,24 @@ export function resourceFiles(rawName: string, target: ResourceOptions): readonl
       path: `${dir}/ui/${feature.kebab}-card.tsx`,
       contents: cardSource(feature, target.catalogModule),
     },
-    {
-      path: `${dir}/ui/${feature.kebab}-form.tsx`,
-      contents: formSource(feature, target.catalogModule),
-    },
+    ...formIslandFiles(feature, dir, pageDir),
     ...locales.map((locale) => ({
       path: catalogPath(locale),
       contents: catalogSource(feature),
       merge: 'json' as const,
     })),
-    // Always an app route: a slice ships a live query, a form and actions, and `generate()`
+    // Always an app route: a slice ships a live query, a form island and actions, and `generate()`
     // refuses `--surface site` for a resource rather than emit them behind a 0kb budget.
-    ...routeFiles(feature.pluralKebab, { surface: 'app', locales }),
+    //
+    // `catalogModule` travels with it. It did not, so the page a RESOURCE writes imported `t` from
+    // `@ultimat3/i18n` while the components beside it imported `useT` from the app's own catalog
+    // module — one command, two idioms, and the framework-import one is issue #249's: it renders
+    // strings while depending on nothing that registers them.
+    ...routeFiles(feature.pluralKebab, {
+      surface: 'app',
+      locales,
+      ...(target.catalogModule === undefined ? {} : { catalogModule: target.catalogModule }),
+    }),
     ...(target.admin === true ? adminFiles(rawName, slice) : []),
   ];
 }

package/src/templates/route.ts

@@ -19,6 +19,14 @@ export type Surface = 'site' | 'app';
  * that was absent from `x routes`, from the manifest and from `budgets`. Ship the mode that works.
  */
 const RENDER: Record<Surface, string> = { site: 'isr', app: 'ssr' };
+/**
+ * `app` is `'visible'` on a page the generator writes with no island, and that is not an oversight.
+ * A declared strategy costs nothing when there is nothing to hydrate — `hydrateRuntime` is emitted
+ * per island DIRECTIVE and answers `''` for a page with none (`packages/render/src/hydrate.ts`), so
+ * `x routes` reads `visible` while the document ships 0 bytes. What it buys is that adding the
+ * first island is one edit: a declared `'never'` beside an island is `X_ISLAND_NOT_HYDRATED`, which
+ * `defineRoute` refuses on purpose, so the scaffold would break at the moment it is first used.
+ */
 const HYDRATE: Record<Surface, string> = { site: 'never', app: 'visible' };
 const OFFLINE: Record<Surface, string> = { site: 'precache', app: 'runtime' };
 /**
@@ -66,7 +74,12 @@ export const routeParams = (path: string): readonly string[] =>
     return name === undefined ? [] : [name];
   });
 
-const routeDir = (surface: Surface, path: string): string =>
+/**
+ * Where the page lands. Exported because an island's `src` is resolved relative to the PAGE, and
+ * only this function knows where `x g resource`'s page went — a second copy of the formula in the
+ * resource generator is how the specifier it prints stops matching the file it writes.
+ */
+export const routeDir = (surface: Surface, path: string): string =>
   `apps/web/${surface}/${segmentsOf(path).join('/')}`;
 
 /**

package/src/templates/scaffold-app.ts

@@ -136,6 +136,8 @@ export const config = defineRoute({
   // therefore failed x routes with X_ROUTE_MODE_INVALID on the first run, printing a fix nobody
   // could follow. Ship the mode that works. Async data needs no boundary: await it in the page.
   render: 'ssr',
+  // Stated with no island on the page, deliberately and for free — \`apps/admin/app/admin/page.tsx\`
+  // carries the reason.
   hydrate: 'visible',
   offline: 'runtime',
   // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
@@ -325,10 +327,16 @@ import { defineRoute } from '@ultimat3/render';
 
 export const config = defineRoute({
   render: 'ssr',
+  // Stated on a page whose body is one \`<h1>\`, and it costs nothing: the hydration runtime is
+  // emitted per island DIRECTIVE, so \`hydrateRuntime([])\` is \`''\` and this document ships 0 bytes
+  // (\`packages/render/src/hydrate.ts\`). It buys the first island being ONE file's edit —
+  // \`hydrate: 'never'\` beside an island is \`X_ISLAND_NOT_HYDRATED\`, which defineRoute refuses.
   hydrate: 'idle',
   offline: 'network-only',
-  // Behind auth, and \`ssr\` is the one mode that can be: it renders per request, so the guard runs
-  // on the server before the page does. \`static\` and \`isr\` refuse a policy outright.
+  // Behind auth, so the mode has to render per request: \`ssr\` and \`stream\` both do, and both take
+  // a \`policy\`. \`static\` and \`isr\` refuse one outright — a file on disk has no actor to decide
+  // against, and an ISR document is cached per URL, so the first actor's HTML would be served to
+  // every later one who passes the same policy.
   policy: { permission: 'admin:read' },
   budget: { js: '120kb' },
   meta: ({ t }) => ({ title: t('admin.home.title'), description: t('admin.home.description') }),
@@ -394,6 +402,12 @@ const prerender =
 // whatever its mode, so \`x verify\`'s \`budgets\` step has a number for it. \`unmeasured\` is the list
 // this build could not render — each one is an X_BUDGET_UNMEASURED at the gate, and this is where
 // the reason is.
+//
+// It writes the whole of \`pages\` and \`skipped\`, never a COUNT of either. A count is what let a
+// partial artifact read as a complete one: someone pointed a screenshot tool at \`.x/static\` and
+// filed "the island did not mount" against a route that had never been emitted (issue #242). Each
+// skipped route carries its own \`reason\` and \`why\`, and \`report\` is where the same inventory
+// landed on disk — which is what \`x build --target static --json\` reads back.
 
 import { join } from 'node:path';
 import { prerenderSite } from '@ultimat3/cli';
@@ -410,7 +424,7 @@ const origin = Bun.env.SITE_ORIGIN;
 if (import.meta.main) {
   const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
   await Bun.stdout.write(
-    \`\${JSON.stringify({ ok: true, out: report.out, pages: report.pages.length, skipped: report.skipped, unmeasured: report.unmeasured })}\\n\`,
+    \`\${JSON.stringify({ ok: true, out: report.out, emitted: report.pages, skipped: report.skipped, unmeasured: report.unmeasured, report: report.report })}\\n\`,
   );
 }
 `;

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.
@@ -101,7 +132,7 @@ export const ${app.camel}Seed = defineSeed('${app.kebab}', async () => {
 
 /** 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-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/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 => ({

package/src/verify-checks.ts

@@ -35,6 +35,7 @@ import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
 import { TEST_STEPS } from './verify-tests';
 import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
+import { checkWorkspaceDependencies } from './workspace-graph';
 
 /** The one file that makes the `roadmap` step answerable, and therefore what `applies` reads. */
 const ROADMAP_FILE = join('docs', 'idea', '14-roadmap.md');
@@ -100,7 +101,16 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     name: 'package-shape',
     summary: 'every package ships the same contract files',
     applies: (ctx) => hasWorkspacePackages(ctx.root),
-    run: async (ctx) => fromFindings(await checkPackageShape(ctx.root)),
+    // The dependency rule rides here rather than becoming a twentieth step because it is this
+    // step's own question — what does a workspace owe the repo it lives in? — asked of the
+    // manifest's `dependencies` instead of its `files`. It is deliberately NOT inside
+    // `checkPackageShape`: `scripts/release.ts --check` calls that one to ask whether the tree is
+    // at the version a tag claims, and an undeclared import is not that question.
+    run: async (ctx) =>
+      fromFindings([
+        ...(await checkPackageShape(ctx.root)),
+        ...(await checkWorkspaceDependencies(ctx.root)),
+      ]),
   },
   {
     name: 'errors',