@ultimat3/cli 29.4.0 → 30.1.0

package/src/messages.ts

@@ -3,6 +3,13 @@
 // built-in catalog in the same flat-key/loud-miss shape as @ultimat3/i18n instead of importing
 // one. Missing keys render as ⟦key⟧, never as English fallback.
 
+import { CLIENT_MESSAGES } from './messages-client';
+import { DB_MESSAGES } from './messages-db';
+import { GATE_MESSAGES } from './messages-gate';
+import { REPRO_MESSAGES } from './messages-repro';
+import { SHOT_MESSAGES } from './messages-shot';
+import { UPGRADE_MESSAGES } from './messages-upgrade';
+
 const CATALOG = {
   'cli.tagline': 'Ultimate — one command means shippable',
   'cli.usage': 'usage: x <command> [options]',
@@ -29,52 +36,6 @@ const CATALOG = {
   'cli.cron.inMonths': 'in {months}',
   'cli.cron.onDaysOfMonth': 'on day {days} of the month',
   'cli.cron.onWeekdays': 'on {days}',
-  'cli.db.backfill.empty': 'no backfill has run against this database yet',
-  'cli.db.backfill.listed': '{count} backfill pass(es)',
-  /** The empty cell in a `x db backfill --list` column — a value, not a column key. */
-  'cli.db.backfill.none': '-',
-  'cli.db.backfill.pending': '{count} of {declared} declared backfill(s) never completed',
-  'cli.db.backfill.swept': 'every one of {declared} declared backfill(s) has completed',
-  // Every action counted, never derived: `count - enqueued` folded a deduped pass into "blocked",
-  // so the summary said blocked while `--json` said deduped for the same row — two renderers
-  // stating different facts about one run, which is the thing `--json` exists to make impossible.
-  'cli.db.backfill.planned':
-    '{count} backfill(s): {enqueued} enqueued, {deduped} already live, {blocked} blocked',
-  'cli.db.backfill.dryRun': '{count} backfill(s) would run — nothing written without --write',
-  'cli.db.branch.ready': 'branch {name} ready',
-  'cli.db.branch.dropped': 'branch {name} dropped',
-  'cli.db.branch.failed': 'branch command failed',
-  'cli.db.branch.listed': '{count} branch(es) of this database',
-  'cli.db.branch.none': 'this database has no branch',
-  /** The empty cell in an `x db branch list` column — a value, not a column key. */
-  'cli.db.branch.unknown': '-',
-  'cli.db.gen.failed': 'migration not generated',
-  'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
-  'cli.db.gen.blocked':
-    'nothing was compared — the app did not load ({count} finding(s)); fix them, then run x db gen again',
-  // A THIRD outcome, and it is neither of the other two: nothing to generate, but the sidecar the
-  // `drift` step reads did move — an edit under `packages/db/src` that implies no DDL. Rendering it
-  // as `written` would name a migration nobody can apply; as `unchanged`, it would hide a file this
-  // command wrote. `GeneratedFiles.outcome` is what `--json` carries the same distinction on.
-  'cli.db.gen.recorded': 'no migration needed — schema hash re-recorded in {file}',
-  // The fourth: no DDL and no sidecar moved, but `packages/db/schema/` did — a hand edit repaired,
-  // or a framework table that changed under an upgrade. `unchanged` would deny a write the lines
-  // below it list, and this command is `X_SCHEMA_DUMP_DRIFT`'s whole `fix:`.
-  'cli.db.gen.dumped': 'no migration needed — schema dump rewritten ({count} file(s))',
-  'cli.db.gen.written': 'migration {id} generated',
-  // Exit 1 and a migration on disk at once: the summary carries the half the exit code hides.
-  'cli.db.gen.writtenDumpFailed':
-    'migration {id} generated and written — the schema dump was not; do not generate it again',
-  'cli.db.migrate.applied': 'migrations applied',
-  'cli.db.migrate.failed': 'migration failed',
-  'cli.db.reset.done': 'database reset and migrated',
-  // Every seed counted per outcome, exactly as the backfill summary is: a replayed seed writes
-  // nothing and skips everything, and a total that hid that would make the second run look idle.
-  'cli.db.seed.done':
-    '{count} seed(s): {inserted} inserted, {updated} updated, {skipped} already stored',
-  'cli.db.seed.dryRun': '{count} seed(s) would run — nothing written while --dry-run is set',
-  'cli.db.seed.failed': '{failed} of {count} seed(s) failed',
-  'cli.db.seed.none': 'no seed matched — nothing to run',
   'cli.dev.ready': 'dev ready on {url} — /_x mounted ({panels} panels), {services}',
   // The mail and CDN halves of that boot line. Rendered text, so it lives here — while
   // `describeMail`/`describeCdn` keep the same wording as the fixed vocabulary `x dev --json`
@@ -97,8 +58,24 @@ const CATALOG = {
   'cli.dev.introspect': '  introspect {url}',
   'cli.dev.manifest': '  manifest {path}',
   'cli.dev.mcp': '  mcp POST {path}',
+  // `x stop` (`cmd-stop.ts`): the lock's holder, and only it.
+  'cli.stop.none': 'no x dev is running in this checkout',
+  'cli.stop.stale':
+    'the dev.lock names a pid another process now holds — nothing signalled; the next x dev clears the lock',
+  'cli.stop.stopped': 'stopped x dev (pid {pid}, port {port}) in {ms}ms',
+  'cli.stop.terminated':
+    'terminated x dev (pid {pid}, port {port}) in {ms}ms — Windows stops a process without a drain',
   'cli.deploy.plan': 'containers only: {images} image, roles {roles}',
+  'cli.deploy.verified':
+    'build {build} held {windowMs} ms over {samples} sample(s); queues: {served} served, {idle} idle',
+  'cli.deploy.verifiedUngraded':
+    'build {build} held {windowMs} ms over {samples} sample(s); queues NOT graded: DATABASE_URL is unset, so no worker row was read',
+  'cli.deploy.unverified': 'build {build} not verified: {count} finding(s)',
   'cli.doctor.clean': 'no findings — environment is shippable',
+  'cli.doctor.poolerBound':
+    'DATABASE_POOLER={pooler}, {role} role: statement_timeout {statement} ms, idle_in_transaction_session_timeout {idle} ms, as the session reads them',
+  'cli.doctor.poolerWakeOff':
+    'wake off, pickup within idlePollMaxMs ({ms} ms by default): a transaction pooler delivers no notification. For the wake, give this role a direct or session-pooled DATABASE_URL and unset DATABASE_POOLER',
   'cli.doctor.findings': '{count} finding(s)',
   'cli.doctor.guards':
     '{count} shipped guard(s) this app does not hold — each line adds one, then x verify reports what it finds:',
@@ -107,6 +84,10 @@ const CATALOG = {
   // `x doctor`'s other listing: what the coverage floor in x.verify.json does not see, and why.
   'cli.doctor.coverageExclude':
     '{count} path(s) x.verify.json excludes from the coverage floor — each with the reason it gives:',
+  'cli.doctor.chartAlerts': '{count} monitoring template(s) missing from the chart:',
+  // `x doctor`'s reminder: the rolling rail is off until this key is set (`doctor-rolling.ts`).
+  'cli.doctor.rollingSince':
+    'the rolling-deploy rail is off: set "rollingSince": "{newest}" in x.verify.json to judge every migration after your newest',
   'cli.docs.code': '{code} is an error code — x errors explain answers it',
   'cli.docs.exports': 'exports: {list}',
   'cli.docs.installed': 'installed: {list}',
@@ -115,12 +96,19 @@ const CATALOG = {
   'cli.docs.found': '{count} doc(s) for "{query}"',
   'cli.docs.none': 'no framework doc matches "{query}"',
   'cli.docs.unresolved': 'the installed framework packages could not be located',
+  'cli.drill.listed': '{count} drill(s); run one with x drill <name> --json',
+  'cli.drill.summary': '{held} of {ran} drill(s) held; {notRun} not run, its service undeclared',
   'cli.errors.count': '{count} registered error code(s)',
   'cli.errors.explained': '{code} — {title}',
+  'cli.exercise.none': 'this app registers no action, query or job: nothing to exercise',
+  'cli.exercise.summary':
+    '{total} primitive(s): {reached} reached, {refused} refused, {off} off, {unreached} unreached — {file}',
   // One rendering of "this file was written", for every command that writes files — `x g`, its
   // own `--dry-run`, and `x new`. Three copies of the same two characters is how a fourth writer
   // arrives with a fifth marker; `--json` carries the paths themselves in `data.files`.
   'cli.file.added': '  + {path}',
+  // Its pair, for the one generator that deletes: `x g sign-in --oidc` drops `x new`'s dev viewer.
+  'cli.file.removed': '  - {path}',
   'cli.fix.clean': 'no boundary violation involves {file}',
   // "nothing written", the same admission `cli.generate.planned` makes and for the same reason: a
   // command called `fix` that only ever REPORTS teaches an agent to expect a repair and act as
@@ -135,6 +123,7 @@ const CATALOG = {
   // file(s)" while `data.dryRun` said nothing had landed, so an agent branching on `summary`
   // believed the files were on disk.
   'cli.generate.planned': 'would write {count} file(s) for {kind} {name} — nothing written',
+  'cli.generate.chartAlertsPrinted': '{count} alert rule(s), as Prometheus rule groups',
   'cli.i18n.added': 'added {locale} — {keys} key(s) seeded from {from}',
   'cli.i18n.dynamic': '{count} dynamic t() call(s) the extractor cannot verify:',
   'cli.i18n.gaps': '{missing} missing key(s) across {locales} locale(s)',
@@ -145,6 +134,9 @@ const CATALOG = {
     '{count} locale-parity finding(s) across {locales} locale(s) — a slot or an untranslated copy against {reference}',
   'cli.i18n.synced': 'synced {locale} from {from} — {added} key(s) added, {total} total',
   'cli.i18n.unused': '{count} key(s) defined in {locale} and never used:',
+  'cli.mail.preview.missing':
+    '{id}: {missing} of {locales} locale(s) miss a key — see data.previews[].missing',
+  'cli.mail.preview.ok': '{id}: rendered in {locales} locale(s), every key resolved',
   'cli.jobs.backfillNoCursor': 'no cursor yet',
   'cli.jobs.cancelled': 'job {id} cancelled — {state}',
   'cli.jobs.backfillRow': '{name} — {rows} row(s) so far, cursor {cursor}',
@@ -161,6 +153,7 @@ const CATALOG = {
   'cli.jobs.removed': 'job {id} removed — it was {state}',
   'cli.jobs.resumed': 'queue {queue} resumed',
   'cli.jobs.retried': 'job {id} re-queued — {state}',
+  'cli.jobs.stepResolved': 'job {id} step {step} resolved — {status}; next: x jobs retry {id}',
   'cli.jobs.shown': 'job {id} — {state}, attempt {attempt} of {attempts}',
   'cli.manifest.blocked': 'manifest not written — {count} module(s) did not load',
   'cli.manifest.fresh': 'manifest is fresh',
@@ -168,8 +161,10 @@ const CATALOG = {
   'cli.manifest.wrote': 'manifest written to {path} ({routes} routes, {actions} actions)',
   'cli.mcp.serving': 'mcp {transport} serving {tools} tools',
   'cli.mcp.scopes': '  scopes {scopes}',
+  'cli.mcp.locked': 'mcp lock: {server} — {tools} tool(s) written to {file}',
+  'cli.mcp.lock_current': 'mcp lock: {server} matches {file}',
   // `bun run setup` and nothing else: the scaffold ships it (`bin/setup.ts`), `README.md` and
-  // `bun run check` both name it, and it is the only spelling that is right on a fresh clone — it
+  // the generated `ci.yml` both name it, and it is the only spelling that is right on a fresh clone — it
   // installs, writes `.env.development.local`, runs `x db gen "initial"` (the scaffold writes no
   // migration, so the drift step is red until it has), migrates and seeds. The four-command line
   // this replaced named `x dev` off a tree where nothing had installed the CLI yet, and skipped the
@@ -191,6 +186,8 @@ const CATALOG = {
   // command is a broken one — the same split `Finding.fix` already makes.
   'cli.new.wrote': '  {count} files in {dir}',
   'cli.new.noRepository': '  no repository — {problem}',
+  // `git init` ran and the commit did not: `.git` exists, so "no repository" was false.
+  'cli.new.uncommitted': '  repository initialised, nothing committed — {problem}',
   'cli.policy.count':
     '{permissions} permission(s), {roles} role(s), {enforced} enforced by a declaration',
   // One row per (declaration, actor) pair, never per role: a permission two declarations enforce
@@ -213,95 +210,6 @@ const CATALOG = {
     'sealed {sealed} second-factor secret(s); {already} already sealed, {skipped} changed mid-run and left alone',
   'cli.tasks.count': '{count} task(s)',
   'cli.tasks.shown': '{name} — {cron} ({tz}), next {next}',
-  'cli.affected.count':
-    '{count} workspace(s) affected by {base}...HEAD, from {changed} changed file(s)',
-  'cli.affected.dirty':
-    '  including the working tree (--dirty): every uncommitted change in this checkout, whoever made it',
-  'cli.affected.none': 'no workspace is affected by {base}...HEAD, from {changed} changed file(s)',
-  'cli.affected.rootWide':
-    '  every workspace: {files} belongs to none of them and changes what all of them compile',
-  // `x shot` — the picture is the `lines`, the verdict is the artifact. The summary names the
-  // GATING fact, and a redirect comes first: a photograph of the sign-in page with every island
-  // missing reads as a bug in the app, and it is a bug in the capture.
-  'cli.shot.ok': '{route} clean — {islands} island(s) mounted, nothing logged and nothing threw',
-  'cli.shot.errors': '{route}: {errors} console error(s) — verdict.json names each one',
-  'cli.shot.redirected': '{route} redirected to {url} — the picture is not the route asked for',
-  // After the redirect and before everything else: a 404 page can be spotless, and a picture of
-  // "Not found" read as the route is the capture lying about its subject.
-  'cli.shot.status':
-    '{route} answered HTTP {status}, expected {expected} — the picture is that response, not the page',
-  'cli.shot.document': '  document HTTP {status}',
-  'cli.shot.documentUnknown': '  document status not seen — the driver recorded no response for it',
-  'cli.shot.server.booted': '  server   booted for this shot on {url}',
-  'cli.shot.server.reused': '  server   the x dev already running on {url}',
-  'cli.shot.canvas': '  canvas   {width}x{height}',
-  'cli.shot.canvasUnreadable': '  canvas   unreadable — {bytes} byte(s), not a decodable image',
-  'cli.shot.islands': '  islands  {booted} of {declared} mounted ({strategies})',
-  'cli.shot.islandsUnknown': '  islands  not counted — the page answered no probe',
-  // The failure a picture cannot show and a console count cannot see: a rejected mount promise
-  // calls no console method, so the FIRST one is named here rather than left to verdict.json.
-  'cli.shot.islandFailed': '{route}: {failed} island(s) failed to mount — {island}: {message}',
-  'cli.shot.network': '  network  {requests} request(s), {refused} refused, {dropped} dropped',
-  'cli.shot.console': '  console  {level}: {text}',
-  'cli.shot.threw': '{route}: {thrown} uncaught exception(s) — {first}',
-  'cli.shot.pageError': '  threw    {message}  {at}',
-  'cli.shot.picture': '  picture  {path}',
-  'cli.shot.verdict': '  verdict  {path}',
-  // `--viewport`: one route at several sizes. The summary is ONE size's verdict, so it says which
-  // size; each size line leads with its size and the per-size detail lines sit indented beneath.
-  'cli.shot.viewport.summary': '{size}: {summary}',
-  'cli.shot.viewport.line': '{size}  {summary}',
-  // `--island`. A component capture reports per STATE, so the summary counts pictures and the
-  // lines name one state each; nothing here restates a fact `--json` does not carry.
-  'cli.shot.island.ok':
-    '{island} clean — {pictures} picture(s), every one mounted, nothing logged and nothing threw',
-  'cli.shot.island.failed':
-    '{island}: {taken} of {expected} declared picture(s) taken — verdict.json names each refusal',
-  'cli.shot.island.state': '  {state}  {theme}  {width}x{height}  {file}',
-  'cli.shot.island.missing': '  missing  {file} — no picture was taken for this declared state',
-  'cli.shot.island.picture': '  pictures {path}',
-  'cli.shot.island.verdict': '  verdict  {path}',
-  'cli.shot.island.index': '  index    {path}',
-  'cli.shot.island.blind.crop':
-    "the picture is the crop target and a thin margin around it — anything further out, including the space a component's own fault sits in, is outside the frame; content that overflows the box is recorded per state as overflow, never shown",
-  'cli.shot.island.blind.locale':
-    'toLocaleString() on a Date resolves its zone inside the engine — only an explicit timeZone is pinned by this harness',
-  'cli.ci.failed':
-    '{failed} of {runs} workflow run(s) on {branch} failed — {findings} finding(s) recovered from the log',
-  'cli.ci.green': 'every one of {runs} workflow run(s) on {branch} passed',
-  'cli.ci.job': '  {conclusion}  {job}  ({steps})',
-  'cli.ci.jobs.other': '  {count} other job(s) in this run',
-  'cli.ci.logs.empty': '  the failed step wrote no log — {url}',
-  /** The conclusion of a run GitHub has not finished — a value, not a column key. */
-  'cli.ci.pending': 'pending',
-  'cli.ci.run': '{conclusion}  {workflow}  {url}',
-  'cli.ci.running':
-    '{running} of {runs} workflow run(s) on {branch} has not finished — nothing has failed yet',
-  'cli.ci.tail': '  log tail, {job}:',
-  'cli.pr.body.truncated': '      … {hidden} more line(s) — re-run with --full',
-  /** The line of a thread whose anchor GitHub answers null for — a value, not a column key. */
-  'cli.pr.line.unknown': '-',
-  'cli.pr.replied': 'replied on thread {id}: {url}',
-  // Resolving closes a CONVERSATION. Whether the finding is fixed is a fact about the code that
-  // no GitHub mutation observes, and a summary saying "addressed" would assert one from the other.
-  'cli.pr.resolved':
-    'thread {id} is marked resolved on GitHub — that records the conversation, not that the finding is fixed',
-  'cli.pr.review.count':
-    '{unresolved} unresolved and {resolved} resolved review thread(s) on {repo}#{pr}',
-  'cli.pr.review.current': '  submitted against the current head {head}',
-  'cli.pr.review.decision': '  review: {decision} by {author} at {submitted}',
-  'cli.pr.review.none': 'no review thread is anchored to a line on {repo}#{pr}',
-  'cli.pr.review.stale':
-    '  submitted against {commit}; the head is now {head} ({committed}) — this decision predates the current code',
-  'cli.pr.review.truncated':
-    '  more than {count} threads — this is the first page, not the whole review',
-  'cli.pr.review.undecided': '  GitHub reports no review decision yet',
-  'cli.pr.thread.closed': '  resolved    {path}:{line}  {id}',
-  'cli.pr.thread.comment': '    {author} at {createdAt}',
-  'cli.pr.thread.more': '    {hidden} more comment(s) on this thread',
-  'cli.pr.thread.open': '  unresolved  {path}:{line}  {id}',
-  'cli.pr.thread.outdated':
-    '    the diff has moved under this thread — {line} is where the comment was written',
   'cli.test.fail': '{failed} of {workers} shard(s) failed',
   'cli.test.affected.none': 'nothing is affected by {base}...HEAD — 0 test file(s) ran',
   'cli.test.empty': 'no test file matches {selection} — 0 test file(s) ran (--allow-empty)',
@@ -311,56 +219,17 @@ const CATALOG = {
   'cli.test.sampled': 'sampled {kept} of {total} {type} file(s)',
   'cli.test.type.fail': '{type} — {failed} of {workers} shard(s) failed',
   'cli.test.type.pass': '{type} — {files} test file(s) on {workers} worker(s) passed in {ms}ms',
-  // The banner a `--only` run carries, in front of whichever summary above it renders. Rendered
-  // output, so it lives here — `data.notAGateRun` is the machine marker, and a reader testing for
-  // one narrowed run reads that boolean rather than substring-matching this line.
-  'cli.verify.notAGateRun': 'NOT A GATE RUN — {summary}',
-  'cli.verify.pass': 'all {count} steps passed in {ms}ms',
-  'cli.verify.fail': '{failed} of {count} steps failed',
-  // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped
-  // ones are named, because "which suite has nothing to run here?" is the question a green gate
-  // over a missing suite has to answer on its own line. Whole sentences per case rather than a
-  // clause the caller glues on: a catalog clause cannot know the sentence it lands in.
-  'cli.verify.passSkipped':
-    '{passed} of {count} steps passed in {ms}ms — {skipped} skipped: {names}',
-  'cli.verify.failSkipped': '{failed} of {count} steps failed — {skipped} skipped: {names}',
-  // The `errors` step's own coverage, in `output`: a scan without a parser reads most fix lines
-  // and not all of them, and a step that reports findings alone claims a completeness it lacks.
-  'cli.verify.fixCoverage': 'checked {checked} fix line(s), could not read {unreadable}',
-  // Why a skipped step is a dash when the step can say so: the suite exists and not one of its
-  // tests ran. Each test's own name carries the reason it skipped, and `bun test` prints only the
-  // counts — so the line says how many and `x test <type>` prints the names.
-  'cli.verify.allSkipped': 'found {skipped} test(s) and every one skipped itself',
-  'cli.verify.warnings': '{count} warning(s) — --verbose or --json lists them',
-  'cli.verify.slowest': 'slowest: {files}',
-  'cli.verify.isrQueryUndeclared':
-    "{file}: render 'isr' with no revalidate.query — its stored pages are keyed on the whole query string, so any visitor can mint one per request. Declare revalidate: { query: [] } (or the parameters the page varies on)",
-  'cli.verify.isrQueryOmitted':
-    '{file}: reads the query parameter "{name}", which revalidate.query does not list — the page is stored under a key without it, so every visitor gets the document rendered for whichever value arrived first. Declare query: [{declared}], or stop reading it',
-  // The other shape the same counts can take: a suite that reported no test at all, skipped ones
-  // included. Its own line and not `allSkipped` with a zero, because the repair differs — there is
-  // no skipped test to read a reason off, so the files the step selected hold no test.
-  'cli.verify.ranNothing': 'found no test to run in the file(s) it selected',
-  'cli.verify.merged': 'merged {parts} part(s) — {summary}',
-  // The heartbeat `verify-progress.ts` writes while a step is still running: `{steps}` is
-  // `unit (12m 3s), live (4m 0s)`, each step with the time since it started.
-  'cli.verify.stillRunning': 'still running: {steps}',
-  // The `unit` step's own measurement, in `output`: what the suite covered of the app's whole
-  // source tree, beside the floor it was held to. A shard says it measured a slice instead.
-  'cli.verify.coverage':
-    'coverage: {lines}% of lines, {funcs}% of functions over {files} source file(s) — floor {floor}',
-  'cli.verify.coverageDeferred':
-    'coverage: this shard measured its own slice — x verify merge folds every shard and judges the floor',
-  'cli.verify.serial': 'serial',
-  'cli.verify.workers': '{workers} workers',
   'cli.clean.nothing': 'nothing to clean: no test leftovers under this app',
   'cli.clean.removed': 'removed {paths} path(s) and {databases} probe database(s)',
   'cli.clean.would':
     'would remove {paths} path(s) and {databases} probe database(s) — --dry-run removed nothing',
   'cli.env.checked': '{count} declared variable(s), all present and valid',
   'cli.env.invalid': '{count} of {total} declared variable(s) missing or malformed',
+  'cli.env.checkedAsProduction': 'checked as production: no ULTIMATE_ENV named',
   'cli.env.wrote': 'wrote {path} — {count} declared variable(s)',
   'cli.env.fresh': '{path} already matches the declaration',
+  'cli.env.initialised': 'wrote {path} — {count} value(s), secrets generated and never printed',
+  'cli.env.unfilled': '  {key} is required and empty — set it in {path}',
   'cli.secrets.init': 'sealed {path} — master key {kid}, and .gitignore now covers the key file',
   'cli.secrets.deploy': '  carry the key into a deploy with {env}="$(cat {keyPath})"',
   'cli.secrets.redeploy': '  set {env}="$(cat {keyPath})" in every deploy before the next release',
@@ -386,6 +255,12 @@ const CATALOG = {
   'cli.secrets.dropped':
     'dropped retired master key {kid} from {path} — {count} retired key(s) still declared',
   'cli.secrets.ring': 'retired master key(s) that still open sealed values: {kids}',
+  ...CLIENT_MESSAGES,
+  ...REPRO_MESSAGES,
+  ...DB_MESSAGES,
+  ...SHOT_MESSAGES,
+  ...UPGRADE_MESSAGES,
+  ...GATE_MESSAGES,
 } as const;
 
 export type MessageKey = keyof typeof CATALOG;

package/src/metrics-endpoint.ts

@@ -37,6 +37,13 @@ import { quoteArg } from './shell-quote';
  */
 export const DEFAULT_METRICS_PORT = 9090;
 
+/**
+ * A container's entry is `bun apps/web/server.ts`, so `x dev` is no instruction there, and the
+ * refusal itself stays: a deployed scrape target must not move on its own.
+ */
+const DEPLOYED_PORT_FIX =
+  "set METRICS_PORT=<free port> in this role's environment, one per role on a host";
+
 /**
  * `X_PORT_IN_USE` is the code the CLI already registers for "this dev port is taken", and the
  * scrape port is one — a synonym here would be a second code for one condition. The fix moves the
@@ -47,11 +54,13 @@ export const DEFAULT_METRICS_PORT = 9090;
  * that is 65536, and an instruction that cannot run is the failure this code exists to end.
  */
 export class MetricsPortInUseError extends UltimateError {
-  constructor(input: { port: number }) {
+  constructor(input: { port: number; dev: boolean }) {
     super({
       code: 'X_PORT_IN_USE',
       cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
-      fix: `METRICS_PORT=${quoteArg(String(neighbouringPort(input.port)))} x dev --json`,
+      fix: input.dev
+        ? `METRICS_PORT=${quoteArg(String(neighbouringPort(input.port)))} x dev --json`
+        : DEPLOYED_PORT_FIX,
     });
   }
 }
@@ -100,12 +109,17 @@ export function portApartFrom(reserved: readonly RolePort[], preferred: number):
 }
 
 export class MetricsPortSharedError extends UltimateError {
-  constructor(input: { port: number; with: RolePort; reserved: readonly RolePort[] }) {
+  constructor(input: {
+    port: number;
+    with: RolePort;
+    reserved: readonly RolePort[];
+    dev: boolean;
+  }) {
     const apart = portApartFrom(input.reserved, DEFAULT_METRICS_PORT);
     super({
       code: 'X_PORT_IN_USE',
       cause: `the metrics port ${input.port} is this process's ${input.with.role} port ${input.with.port}, so two listeners would answer on one number`,
-      fix: `METRICS_PORT=${quoteArg(String(apart))} x dev --json`,
+      fix: input.dev ? `METRICS_PORT=${quoteArg(String(apart))} x dev --json` : DEPLOYED_PORT_FIX,
     });
   }
 }
@@ -131,6 +145,8 @@ export interface MetricsEndpointOptions {
    * A host that opens the listener itself and names none is labelled `unknown`.
    */
   readonly role?: string;
+  /** Is this `x dev`? It picks the refusal's fix: a container has no `x dev` to rerun. Absent: no. */
+  readonly dev?: boolean;
   /**
    * What a taken port means. `refuse` (the default, and every container's): `X_PORT_IN_USE` —
    * Prometheus is configured against the declared port, so listening anywhere else is a scrape
@@ -164,12 +180,13 @@ export function bindScrapePort<T>(
   port: number,
   whenTaken: 'refuse' | 'free',
   bind: (port: number) => T,
+  dev = false,
 ): T {
   try {
     return bind(port);
   } catch (error) {
     if (!isAddressInUse(error)) throw error;
-    if (whenTaken === 'refuse' || port === 0) throw new MetricsPortInUseError({ port });
+    if (whenTaken === 'refuse' || port === 0) throw new MetricsPortInUseError({ port, dev });
     logger.warn('ultimate metrics port taken', {
       port,
       cause: `the metrics port ${String(port)} is already bound — another x dev, or a Prometheus — so this process listens on a free one`,
@@ -231,6 +248,7 @@ export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): Metr
       port: asked,
       with: shared,
       reserved: options.reserved ?? [],
+      dev: options.dev === true,
     });
   }
   const port = shared === undefined ? asked : 0;

package/src/new-shapes-generate.ts

@@ -0,0 +1,71 @@
+// The generators a shape runs once its files are on disk. `x g sign-in` IS how an app gets sign-in —
+// its pages, actions, catalog keys, `signInPath` and API registrations land together — so a shape
+// that starts signed-in runs it, rather than an overlay re-spelling its output (a second way).
+
+import { renderFixShellArg, UltimateError } from '@ultimat3/core';
+import type { CommandContext } from './command';
+import type { NewShape } from './new-shapes';
+import type { CommandResult, JsonValue } from './output';
+import { parseArgs } from './parse';
+import { quoteArg } from './shell-quote';
+
+/** A shape's generator refused or failed in the app `x new` just wrote: the framework's bug. */
+export class NewShapeGenerateError extends UltimateError {
+  constructor(input: {
+    readonly shape: NewShape;
+    readonly argv: readonly string[];
+    readonly target: string;
+    readonly result: CommandResult;
+  }) {
+    const codes = (input.result.findings ?? []).map((finding) => finding.code).join(', ');
+    super({
+      code: 'X_NEW_SHAPE_GENERATE_FAILED',
+      cause: `x new --shape ${input.shape} ran x ${input.argv.join(' ')} in the app it wrote and it failed${codes === '' ? '' : ` (${codes})`}: ${input.result.summary}`,
+      // Each word through `quoteArg`: the command is the generator's argv, joined, never a template.
+      fix: [
+        `cd ${renderFixShellArg(input.target, '<the new app directory>')}`,
+        '&&',
+        ...['bunx', 'x', ...input.argv, '--json'].map(quoteArg),
+        '  # reproduces it; then bun test packages/cli/src/templates/shapes',
+      ].join(' '),
+    });
+  }
+}
+
+/**
+ * Runs each of `generate` in `target`, in order, through the `x g` command itself, and answers the
+ * paths each wrote. The first that fails stops the run: a half-signed-in app is not a shape.
+ */
+export async function runShapeGenerators(
+  ctx: CommandContext,
+  shape: NewShape,
+  target: string,
+  generate: readonly (readonly string[])[],
+): Promise<readonly string[]> {
+  if (generate.length === 0) return [];
+  // Lazy, as the registry loads every command body: `x new` with no shape never pays for `x g`.
+  const [{ generateCommand }, { SPECS }] = await Promise.all([
+    import('./cmd-generate'),
+    import('./registry'),
+  ]);
+  const written: string[] = [];
+  for (const argv of generate) {
+    const args = parseArgs(['g', ...argv], SPECS);
+    const result = await generateCommand.run({ ...ctx, args, cwd: target });
+    if (!result.ok)
+      throw new NewShapeGenerateError({ shape, argv: ['g', ...argv], target, result });
+    written.push(...filesOf(result));
+  }
+  return written;
+}
+
+/** A JSON object, by its type: `result.data` is the generator's own `JsonValue`, never `unknown`. */
+const isJsonObject = (
+  value: JsonValue | undefined,
+): value is { readonly [key: string]: JsonValue } =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const filesOf = (result: CommandResult): readonly string[] => {
+  const files = isJsonObject(result.data) ? result.data['files'] : undefined;
+  return Array.isArray(files) ? files.filter((file) => typeof file === 'string') : [];
+};

package/src/new-shapes.ts

@@ -0,0 +1,63 @@
+// `x new --shape <shape>`: the closed set of app shapes and the one reader of the flag. Apart from
+// the templates (`templates/shapes/`) so `cmd-new-spec.ts` can list the names without loading them.
+
+import { UltimateError } from '@ultimat3/core';
+import type { ParsedArgs } from './parse';
+import { flagString } from './parse';
+import { quoteArg } from './shell-quote';
+
+/** Every shape `x new` writes. A name here and no overlay in `templates/shapes/` fails its test. */
+export const NEW_SHAPES = ['api', 'blog', 'dashboard'] as const;
+
+export type NewShape = (typeof NEW_SHAPES)[number];
+
+const isShape = (value: string): value is NewShape =>
+  (NEW_SHAPES as readonly string[]).includes(value);
+
+/** `--shape` names nothing `x new` ships. */
+export class NewShapeUnknownError extends UltimateError {
+  constructor(input: {
+    readonly shape: string;
+    readonly invocation: string;
+    readonly name: string;
+  }) {
+    super({
+      code: 'X_NEW_SHAPE_UNKNOWN',
+      cause: `--shape ${quoteArg(input.shape)} is not a shape x new writes; the shapes are ${NEW_SHAPES.join(', ')}`,
+      fix: `${input.invocation} ${quoteArg(input.name)} --shape ${NEW_SHAPES[0]}   # every shape: bunx @ultimat3/cli help new`,
+    });
+  }
+}
+
+/** `--shape` with `--no-example`: a shape is its own example, so the pair names two apps. */
+export class NewShapeConflictError extends UltimateError {
+  constructor(input: {
+    readonly shape: NewShape;
+    readonly invocation: string;
+    readonly name: string;
+  }) {
+    super({
+      code: 'X_NEW_SHAPE_CONFLICT',
+      cause: `--shape ${input.shape} and --no-example ask for two different apps: a shape is its own example, and --no-example is the default shape with an empty app/`,
+      fix: `${input.invocation} ${quoteArg(input.name)} --shape ${input.shape}`,
+    });
+  }
+}
+
+/**
+ * The shape the caller asked for, `undefined` for the default scaffold. Refuses an unknown name and
+ * the `--no-example` pairing before anything is planned, so a refusal writes no file.
+ */
+export function readShape(
+  args: ParsedArgs,
+  invocation: string,
+  name: string,
+): NewShape | undefined {
+  const raw = flagString(args, 'shape');
+  if (raw === undefined) return undefined;
+  if (!isShape(raw)) throw new NewShapeUnknownError({ shape: raw, invocation, name });
+  if (args.flags.get('example') === false) {
+    throw new NewShapeConflictError({ shape: raw, invocation, name });
+  }
+  return raw;
+}

package/src/openapi-compile-ir.ts

@@ -0,0 +1,68 @@
+// The neutral form `openapi-compile.ts` reduces an OpenAPI document to, and both client emitters
+// read: named types, operations, and nothing that still needs the document. Types only — the
+// compiler is the one reader of OpenAPI, the emitters never see a JSON pointer they must resolve.
+
+/** One value shape. `unknown` is a schema that states nothing (`{}`), never a construct skipped. */
+export type ClientType =
+  | { readonly kind: 'unknown' }
+  | { readonly kind: 'string' }
+  | { readonly kind: 'number'; readonly integer: boolean }
+  | { readonly kind: 'boolean' }
+  | { readonly kind: 'null' }
+  | { readonly kind: 'literal'; readonly value: string | number | boolean }
+  | { readonly kind: 'array'; readonly items: ClientType }
+  | { readonly kind: 'object'; readonly fields: readonly ClientField[] }
+  | { readonly kind: 'record'; readonly values: ClientType }
+  | { readonly kind: 'union'; readonly members: readonly ClientType[] }
+  | { readonly kind: 'ref'; readonly name: string };
+
+export type ClientObject = Extract<ClientType, { readonly kind: 'object' }>;
+
+export interface ClientField {
+  readonly name: string;
+  readonly type: ClientType;
+  readonly required: boolean;
+}
+
+export type ClientMethod = 'GET' | 'HEAD' | 'PUT' | 'DELETE' | 'POST' | 'PATCH' | 'OPTIONS';
+
+export interface ClientParameter {
+  readonly name: string;
+  readonly in: 'path' | 'query' | 'header';
+  readonly required: boolean;
+  readonly type: ClientType;
+}
+
+/**
+ * How the request body reaches the input: `fields` spreads an object body's fields into the input
+ * beside the parameters (a parameter of the same name reads the same field), `value` puts any
+ * other body under `input.body`.
+ */
+export type ClientBody =
+  | { readonly mode: 'fields'; readonly type: ClientType; readonly required: boolean }
+  | { readonly mode: 'value'; readonly type: ClientType; readonly required: boolean };
+
+export interface ClientOperation {
+  /** A TypeScript identifier from `operationId` — stable, so a rename is a contract change. */
+  readonly name: string;
+  readonly method: ClientMethod;
+  /** The template as the document states it: `/invoices/{invoiceId}`. */
+  readonly path: string;
+  readonly tags: readonly string[];
+  readonly summary?: string | undefined;
+  readonly parameters: readonly ClientParameter[];
+  readonly body?: ClientBody | undefined;
+  /** The 2xx JSON body; `undefined` when the success answer has none. */
+  readonly response?: ClientType | undefined;
+  /** Codes a refusal may carry, read from `x-ultimate-errors` on the non-2xx answers. */
+  readonly refusals: readonly string[];
+}
+
+export interface CompiledDocument {
+  readonly title: string;
+  readonly version: string;
+  /** Named component schemas, sorted by name — only those an operation kept reaches. */
+  readonly types: ReadonlyMap<string, ClientType>;
+  /** Sorted by name. */
+  readonly operations: readonly ClientOperation[];
+}