@ultimat3/cli 22.15.0 → 24.0.0

package/src/cmd-db.ts

@@ -11,7 +11,7 @@
 // directory tree. `node:path` for `join` — Bun exposes no path joiner.
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { resolveEnvironment } from '@ultimat3/core';
+import { NotImplementedError, resolveEnvironment } from '@ultimat3/core';
 import { type DriftReport, driftError, withTransaction } from '@ultimat3/db';
 import { postgresDriver } from '@ultimat3/entity';
 import { requireAppRoot } from './app-root';
@@ -22,6 +22,13 @@ import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
 import { stepFinding } from './db-finding';
 import { generateAppMigration, unrenderedJson, unrenderedLines } from './db-generate';
+import { liveObjectDrift } from './db-object-drift';
+import {
+  afterWrittenMigration,
+  refreshSchemaDump,
+  type SchemaDumpRefresh,
+  schemaDumpJson,
+} from './db-schema-refresh';
 import type { SeedPassRow } from './db-seed';
 import {
   discoverSeeds,
@@ -33,7 +40,7 @@ import {
   selectSeeds,
 } from './db-seed';
 import { DevAlreadyRunningError, liveDevLock } from './dev-lock';
-import { CliNotImplementedError, MissingSubcommandError, UnknownCommandError } from './errors';
+import { MissingSubcommandError, UnknownCommandError } from './errors';
 import { withJobDriver } from './jobs-driver';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -109,34 +116,52 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
   // `x i18n add fr` failure, repeated. The count is the verdict; the gate's own `drift` step is
   // where a red belongs, and it reads the same list to decide that `x db gen` is not the fix.
   const lost = unrenderedLines(generated.unrendered);
+  // After the migration, from the migrations alone: the dump is what replaying them produces, so
+  // it is rewritten on all three outcomes — `unchanged` included, which is what makes this
+  // command the `fix:` on `X_SCHEMA_DUMP_DRIFT` when a framework table or a hand edit moved it.
+  const dump = await refreshSchemaDump(root, ctx.env);
+  const dumpFindings = dump.finding === undefined ? [] : [dump.finding];
   const migration = generated.migration;
   if (migration === undefined) {
     return {
-      ok: generated.findings.length === 0,
+      ok: generated.findings.length === 0 && dumpFindings.length === 0,
       command: 'db',
       // The sidecar path, never a bare id: `hash-recorded` writes exactly one, and it is the file
       // the `drift` step reads back.
+      // `blocked` FIRST: the app did not load, so nothing was diffed, and every sentence below
+      // it is a claim about a comparison that never ran. It read "entities and migrations agree"
+      // over an exit 1.
       summary:
-        generated.outcome === 'hash-recorded'
-          ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
-          : msg('cli.db.gen.unchanged'),
-      findings: generated.findings,
+        generated.outcome === 'blocked'
+          ? msg('cli.db.gen.blocked', { count: generated.findings.length })
+          : generated.outcome === 'hash-recorded'
+            ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
+            : dump.status === 'written'
+              ? msg('cli.db.gen.dumped', { count: dump.written.length + dump.removed.length })
+              : msg('cli.db.gen.unchanged'),
+      findings: [...generated.findings, ...dumpFindings],
       // `files` is what this command WROTE, so the empty array here was a false claim.
-      lines: [...generated.files.map((file) => `  ${file}`), ...lost],
+      lines: [...generated.files.map((file) => `  ${file}`), ...dumpLines(dump), ...lost],
       data: {
         outcome: generated.outcome,
         migration: null,
         files: [...generated.files],
         schemaHash: generated.schemaHash ?? null,
         unrendered: unrenderedJson(generated.unrendered),
+        schemaDump: schemaDumpJson(dump),
       },
     };
   }
   return {
-    ok: true,
+    ok: dumpFindings.length === 0,
     command: 'db',
-    summary: msg('cli.db.gen.written', { id: migration.id }),
-    lines: [...generated.files.map((file) => `  ${file}`), ...lost],
+    summary:
+      dumpFindings.length === 0
+        ? msg('cli.db.gen.written', { id: migration.id })
+        : msg('cli.db.gen.writtenDumpFailed', { id: migration.id }),
+    // Exit 1 with a migration on disk: the finding has to say so, or the next move is a duplicate.
+    findings: dumpFindings.map((finding) => afterWrittenMigration(finding, migration.id)),
+    lines: [...generated.files.map((file) => `  ${file}`), ...dumpLines(dump), ...lost],
     data: {
       outcome: generated.outcome,
       migration: migration.id,
@@ -144,10 +169,20 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
       files: [...generated.files],
       schemaHash: generated.schemaHash ?? null,
       unrendered: unrenderedJson(generated.unrendered),
+      schemaDump: schemaDumpJson(dump),
     },
   };
 }
 
+/**
+ * What the dump refresh did, one path per line — the same list `data.schemaDump` carries, so the
+ * human render and `--json` report one fact. A refresh that changed nothing prints nothing.
+ */
+const dumpLines = (dump: SchemaDumpRefresh): readonly string[] => [
+  ...dump.written.map((file) => `  ${file}`),
+  ...dump.removed.map((file) => `  - ${file}`),
+];
+
 /**
  * The post-migrate report, rendered. Through `driftError` rather than a second literal: the
  * three-line `X_DB_DRIFT` output is pinned by the framework contract, and this command must not be
@@ -175,16 +210,30 @@ async function runMigrate(
   try {
     const migrated = await runMigrations({ root, env: ctx.env });
     const report = migrated.report;
+    // A hand-written or pulled migration reaches the dump here, with no `x db gen` in between.
+    const dump = await refreshSchemaDump(root, ctx.env);
+    // The half a snapshot cannot hold: a trigger, function, view, type or sequence this database
+    // carries and no migration creates. Asked only when the replay produced a catalog to ask
+    // against — without one there is nothing that says what the migrations create.
+    const objects =
+      dump.catalog === undefined ? [] : await liveObjectDrift(root, ctx.env, dump.catalog);
+    const findings = [
+      ...driftFindings(migrated.drift),
+      ...objects.map((difference) => findingFrom(driftError(difference))),
+      ...(dump.finding === undefined ? [] : [dump.finding]),
+    ];
     return {
-      ok: migrated.drift.ok,
+      ok: findings.length === 0,
       command: 'db',
       summary,
-      findings: driftFindings(migrated.drift),
+      findings,
+      lines: dumpLines(dump),
       data: {
         applied: report.applied.map((entry) => entry.id),
         skipped: report.skipped.length,
         appVersion: report.appVersion,
         durationMs: report.durationMs,
+        schemaDump: schemaDumpJson(dump),
       },
     };
   } catch (error) {
@@ -205,8 +254,8 @@ async function runMigrate(
 async function runReset(ctx: CommandContext, root: string): Promise<CommandResult> {
   const services = resolveServices(root, ctx.env);
   if (services.db.mode === 'external') {
-    throw new CliNotImplementedError({
-      feature: 'x db reset against an external Postgres',
+    throw new NotImplementedError({
+      cause: 'x db reset against an external Postgres is not implemented in this build',
       fix: 'drop and recreate the database yourself, then run: x db migrate',
     });
   }
@@ -252,7 +301,8 @@ async function runSeed(ctx: CommandContext, root: string): Promise<CommandResult
   });
   if (chosen.length === 0) {
     return {
-      ok: true,
+      // A seed module that would not import may hold the seed that was asked for.
+      ok: discovery.findings.length === 0,
       command: 'db',
       summary: msg('cli.db.seed.none'),
       findings: discovery.findings,

package/src/cmd-deploy-helm.ts

@@ -8,8 +8,7 @@
 // why: Bun exposes no path-join primitive; the chart path is handed to helm as one joined string.
 import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { BadFlagError } from './errors';
 
 /** Long enough for a migration a pre-upgrade hook must finish; helm's own 5m default is not. */
@@ -67,16 +66,18 @@ export function readLabel(flag: 'namespace' | 'release', raw: string): string {
  */
 export async function readReleaseName(root: string, flag: string | undefined): Promise<string> {
   if (flag !== undefined) return readLabel('release', flag);
-  const module = (await import(join(root, APP_CONFIG_FILE))) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const name = isRecord(config) ? config['name'] : undefined;
+  const config = await loadAppConfig(root);
+  // `unknown`, not the declared `string`: core reads an absent name as `"undefined"` and lets it by.
+  const name: unknown = config?.name;
   if (typeof name === 'string' && name.length <= RELEASE_MAX && LABEL.test(name)) return name;
   throw new UltimateError({
     code: 'X_CONFIG_INVALID',
     cause:
       typeof name === 'string'
         ? `app.config.ts names the app "${name.slice(0, 80)}", which is not a helm release name (a DNS-1123 label of at most ${RELEASE_MAX} characters)`
-        : 'app.config.ts exports no config.name, and x deploy --method helm names the release after it',
+        : config === undefined
+          ? `${root} has no app.config.ts, and x deploy --method helm names the release after its config.name`
+          : 'app.config.ts exports no config.name, and x deploy --method helm names the release after it',
     fix: 'name the release explicitly: x deploy --method helm --release my-app --json',
   });
 }

package/src/cmd-deploy.ts

@@ -176,10 +176,10 @@ export function planDeploy(
       command: [
         'docker',
         'compose',
-        // Compose interpolates `${SYNC_URL:?…}` and `${POSTGRES_PASSWORD:?…}` from the shell and
-        // `--env-file` only — never from a service's `env_file:`. Without this an operator who put
-        // them in `.env.production`, the one file the compose file tells them to fill, had every
-        // step die on a parse error. Global flag, so it precedes `-f`; the shell still wins over it.
+        // Compose interpolates `${SYNC_URL:?…}`, `${APP_URL:?…}` and `${POSTGRES_PASSWORD:?…}` from
+        // the shell and `--env-file` only — never from a service's `env_file:`. Without this an
+        // operator who put them in `.env.production`, the one file the compose file tells them to
+        // fill, had every step die on a parse error. Global flag, so it precedes `-f`; the shell still wins over it.
         '--env-file',
         join(root, PROD_ENV_FILE),
         '-f',

package/src/cmd-dev.ts

@@ -13,7 +13,6 @@ import type { OverlayNotice, RequestContext } from '@ultimat3/http';
 import { asCtx } from '@ultimat3/http';
 import type { Manifest } from '@ultimat3/manifest';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
-import { createIsrController } from '@ultimat3/render/server';
 import { loadSignInPath } from './app-auth';
 import { appManifest } from './app-manifest';
 import type { StalePin } from './app-reload-graph';
@@ -50,6 +49,7 @@ import {
   resolveServices,
   withRealtimeEvents,
 } from './runtime-bindings';
+import { attachedIsr } from './runtime-isr';
 import { liveFeedLabel } from './runtime-live-feed';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { replicaOverrides } from './runtime-replica';
@@ -239,9 +239,10 @@ async function bootDev(
   };
   const panels = devPanels(dashboard).map((panel) => panel.key);
 
-  // `x dev`'s own, so a reload can empty it: an `isr` page's first render was otherwise served for
-  // its whole ttl after every save, whatever the modules behind it now said.
-  const isr = createIsrController({ buildId });
+  // `x dev`'s own, so a reload can empty it (a save otherwise kept a page's first render for its
+  // ttl); attached, so a tag bust reaches it too. Released with the roles.
+  const { isr, release: releaseIsr } = attachedIsr({ buildId });
+  acquired.push(releaseIsr);
   const { routes, theme, speculation, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
     isr,
     root: options.root,
@@ -350,16 +351,16 @@ async function bootDev(
     async stop() {
       watcher.close();
       await running.stop();
+      releaseIsr();
       await runtime.stop();
       // Released after the roles: a span opened by an in-flight request still has an exporter to
       // end into. `configureTelemetry` merges, so handing back the noop is how it is uninstalled —
       // leaving it in place would keep every span of the next `startDev` in this process's buffer.
       configureTelemetry({ exporter: noopExporter });
       traces.reset();
-      // Released with the exporter, after the roles, for the same reason: a statement still in
-      // flight is observed by the ledger that counted the rest of its request. Leaving it
-      // installed would keep every statement of the next `startDev` in this process's counts —
-      // and, worse, keep instrumentation on in a process that is no longer a dev server.
+      // With the exporter, for the same reason: an in-flight statement is observed by the ledger
+      // that counted its request. Left installed, the next `startDev`'s statements land in these
+      // counts — and instrumentation stays on in a process that is no longer a dev server.
       setStatementObserver(undefined);
       statements.reset();
     },

package/src/cmd-doctor-spec.ts

@@ -3,19 +3,12 @@
 
 import type { CommandSpec } from './parse';
 
-/** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
-export const DEFAULT_DOCTOR_PORT = 3000;
-
 export const doctorSpec: CommandSpec = {
   name: 'doctor',
   summary: 'environment, versions, drift, ports, PWA prerequisites — each with a fix command',
   usage: 'x doctor [--port 3000] [--json]',
   flags: [
-    {
-      name: 'port',
-      type: 'string',
-      summary: 'port to test',
-      default: String(DEFAULT_DOCTOR_PORT),
-    },
+    // No `default`: it would be indistinguishable from a typed value, and `PORT` could never win.
+    { name: 'port', type: 'string', summary: 'port to test (default: PORT, then 3000)' },
   ],
 };

package/src/cmd-doctor.ts

@@ -19,12 +19,18 @@ import {
 } from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
-import { DEFAULT_DOCTOR_PORT, doctorSpec } from './cmd-doctor-spec';
+import { doctorSpec } from './cmd-doctor-spec';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
+import { appUrlFindings } from './doctor-app-url';
+import { type AuthStorageFact, authStorageFindings, authStorageProbe } from './doctor-auth';
+import { coverageExcludesProbe, withCoverageExcludes } from './doctor-coverage';
+import { shippedGuardsProbe, withGuardListing } from './doctor-guards';
 import type { OfflineFallbackFact } from './doctor-offline';
 import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
-import { intFlagOr, PORT_RANGE, portPairAfter } from './flag-number';
+import type { SealedKeysFact } from './doctor-sealed';
+import { sealedKeyFindings, sealedKeysProbe } from './doctor-sealed';
+import { PORT_RANGE, portPairAfter, readIntFlag } from './flag-number';
 import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -33,6 +39,7 @@ import type { ParsedArgs } from './parse';
 import { portFree } from './port-probe';
 import { syncPortFor } from './role-sync';
 import { checkMigrationDrift } from './schema-drift';
+import { portFromEnv } from './serve-env';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -45,6 +52,8 @@ export interface DoctorProbe {
   /** App root, or undefined when the command runs outside an app. */
   readonly root: string | undefined;
   readonly port: number;
+  /** `APP_URL` as this environment declares it; `undefined` when unset. */
+  readonly appUrl: string | undefined;
   /** True while cursors are signed with the key shipped in the published package. */
   readonly devCursorSecret: boolean;
   /**
@@ -91,6 +100,17 @@ export interface DoctorProbe {
    * reaching the disk — the same split `drift()` makes one question over.
    */
   offlineFallback(): Promise<OfflineFallbackFact>;
+  /**
+   * The app's `.sealed()` columns and the master keys this environment declares. A FACT, for the
+   * reason `offlineFallback` is one: loading the app and opening the secrets file is IO, and what
+   * a retired key beside a sealed column means is `sealedKeyFindings`' pure rule.
+   */
+  sealedKeys(): Promise<SealedKeysFact>;
+  /**
+   * What an upgrade left in the auth tables for an operator to finish: unsealed second-factor
+   * secrets, and tables no release reads. Asked of an external database only.
+   */
+  authStorage(): Promise<AuthStorageFact>;
 }
 
 /** What `x doctor` reads about the embedded database, without opening it. */
@@ -247,6 +267,7 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
     );
   }
   findings.push(...(await portFindings(probe)));
+  findings.push(...appUrlFindings(probe.appUrl, probe.port));
   // `@ultimat3/pwa`'s own codes, not CLI twins of them. `X_PWA_NO_ICON_SOURCE` and
   // `X_PWA_NO_FALLBACK` used to be declared here for the same two conditions the package already
   // names — two codes for one condition, one of them registered by nobody, so `x errors explain`
@@ -281,20 +302,30 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   // author reaches it from: `x db gen` throwing `X_MIGRATION_SNAPSHOT_MISSING` used to be a
   // condition this diagnostic could not see at all, so the fix line ran clean over a broken app.
   findings.push(...(await probe.snapshots()));
+  // Sealed columns against the key ring: no key at all, or a rotation whose re-seal is pending.
+  findings.push(...sealedKeyFindings(await probe.sealedKeys()));
+  findings.push(...authStorageFindings(await probe.authStorage()));
   return findings;
 }
 
 /**
- * The port to TEST, and the one place `x doctor` reads it. `PORT_RANGE.min` is 0 because `x dev
- * --port 0` means "let the kernel pick"; here 0 means nothing, and `Bun.serve({ port: 0 })` always
- * succeeds — so the port check could not fail, which is worse than not running it.
+ * The port to TEST, and the one place `x doctor` reads it: `devPortFor`'s order — `--port`, then
+ * `PORT` (`portFromEnv`, the one reader of it), then 3000 — so the probe answers about the port
+ * `x dev` will bind. It probed 3000 under `PORT=4000` while dev bound 4000 and 4001. `PORT_RANGE.min`
+ * is 0 because `x dev --port 0` means "let the kernel pick"; here 0 means nothing, and
+ * `Bun.serve({ port: 0 })` always succeeds — so the port check could not fail.
  */
-export const doctorPort = (args: ParsedArgs): number =>
-  intFlagOr(
-    args,
-    { name: 'port', command: 'doctor', ...PORT_RANGE, min: 1, example: 'x doctor --port 3000' },
-    DEFAULT_DOCTOR_PORT,
-  );
+export const doctorPort = (
+  args: ParsedArgs,
+  env: Readonly<Record<string, string | undefined>>,
+): number =>
+  readIntFlag(args, {
+    name: 'port',
+    command: 'doctor',
+    ...PORT_RANGE,
+    min: 1,
+    example: 'x doctor --port 3000',
+  }) ?? portFromEnv(env);
 
 /**
  * `DATABASE_URL` as BOTH halves of the database question read it: unset and blank are one case.
@@ -363,12 +394,19 @@ async function probeDatabase(url: string | undefined): Promise<Finding | null> {
   }
 }
 
-export function probeFor(cwd: string, bunVersion: string, port: number): DoctorProbe {
+export function probeFor(
+  cwd: string,
+  bunVersion: string,
+  port: number,
+  // The environment `doctorPort` read `PORT` from, so `APP_URL` is judged against the same one.
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): DoctorProbe {
   const root = findAppRoot(cwd)?.dir;
   return {
     bunVersion,
     root,
     port,
+    appUrl: env['APP_URL'],
     devCursorSecret: usesDevCursorSecret(),
     devStorageSecret: usesDevStorageSecret(),
     // `ULTIMATE_ENV`, through core — the one key that says which deploy this is, with `NODE_ENV`
@@ -394,23 +432,36 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     // `runDoctor` returns on `X_NOT_IN_APP` before this can be asked.
     offlineFallback: async () =>
       root === undefined ? { fallback: null, routes: undefined } : offlineFallbackProbe(root),
+    sealedKeys: async () =>
+      root === undefined ? { columns: undefined, keys: undefined } : sealedKeysProbe(root),
+    authStorage: () => authStorageProbe(process.env['DATABASE_URL']),
   };
 }
 
 export const doctorCommand: CliCommand = {
   spec: doctorSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const port = doctorPort(ctx.args);
-    const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
-    return {
-      ok: findings.length === 0,
-      command: 'doctor',
-      summary:
-        findings.length === 0
-          ? msg('cli.doctor.clean')
-          : msg('cli.doctor.findings', { count: findings.length }),
-      findings,
-      data: { count: findings.length, codes: findings.map((entry) => entry.code) },
-    };
+    const port = doctorPort(ctx.args, ctx.env);
+    const probe = probeFor(ctx.cwd, ctx.bunVersion, port, ctx.env);
+    const findings = await runDoctor(probe);
+    const listed = withGuardListing(
+      {
+        ok: findings.length === 0,
+        command: 'doctor',
+        summary:
+          findings.length === 0
+            ? msg('cli.doctor.clean')
+            : msg('cli.doctor.findings', { count: findings.length }),
+        findings,
+        data: { count: findings.length, codes: findings.map((entry) => entry.code) },
+      },
+      // A listing beside the verdict, never part of it (`doctor-guards.ts` says why).
+      probe.root === undefined ? [] : await shippedGuardsProbe(probe.root),
+    );
+    // The second listing: what the coverage floor does not see (`doctor-coverage.ts`).
+    return withCoverageExcludes(
+      listed,
+      probe.root === undefined ? [] : await coverageExcludesProbe(probe.root),
+    );
   },
 };

package/src/cmd-env.ts

@@ -4,15 +4,39 @@
 
 // Bun ships no path-join primitive, and `.env.example` is written app-root-relative.
 import { join } from 'node:path';
-import { checkEnv, ENV_EXAMPLE_PATH, ERROR_DOCS_URL, maskedEnvValues } from '@ultimat3/core';
+import {
+  checkEnv,
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  maskedEnvValues,
+  UltimateError,
+} from '@ultimat3/core';
 import { envExampleFor, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
 import { envSpec } from './cmd-env-spec';
 import type { CliCommand, CommandContext } from './command';
-import { EnvSchemaMissingError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 
+/**
+ * `x env` was run in an app whose `app.config.ts` exports no `envSchema`. Not a silent success:
+ * writing a `.env.example` with no variables in it, or reporting "0 declared variables, all
+ * present", both read as a working environment declaration to whoever runs the command next.
+ *
+ * `X_CONFIG_INVALID` is core's code for "a configuration this process cannot boot on — env or
+ * `app.config.ts`", which is exactly this; the CLI names it in `CLI_BORROWED_ERROR_CODES` rather
+ * than minting a synonym.
+ */
+export class EnvSchemaMissingError extends UltimateError {
+  constructor(input: { subcommand: string }) {
+    super({
+      code: 'X_CONFIG_INVALID',
+      cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
+      fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
+    });
+  }
+}
+
 /**
  * Every subcommand needs the declaration, and an app without one is a usage error rather than an
  * empty success: `x env example` writing a two-comment file would look like it worked.