@ultimat3/cli 22.15.0 → 24.0.0

package/src/cmd-generate.ts

@@ -4,7 +4,8 @@
 
 import { existsSync } from 'node:fs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
-import { registerGeneratedPrimitives } from './api-registration';
+import { registerAdminResources } from './admin-registration';
+import { indexBindingFindings, registerGeneratedPrimitives } from './api-registration';
 import { writeAppArtifacts } from './app-artifacts';
 import { appManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
@@ -13,18 +14,23 @@ import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
 import { assertFeatureExists } from './generate-feature';
 import { generate, sliceDir } from './generate-files';
+import { ungrantedByGenerator } from './generate-grant-findings';
 import { grantGeneratedPermissions } from './generate-grants';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
-import { containedPath, writeFiles } from './generate-write';
+import { refuseShadowedTypes } from './generate-shadow';
+import { containedPath, planWrites, writeFiles } from './generate-write';
+import { declareGeneratedImports } from './generated-imports';
+import { registerGeneratedEntities, resolveDbModule } from './handle-registration';
 import { resolveCatalogModule } from './i18n-audit';
-import { syncI18nIndex } from './i18n-index';
+import { catalogLocales, syncI18nIndex } from './i18n-index';
 import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
 import { quoteArg } from './shell-quote';
-import { kebab, resolveLocales } from './templates';
+import type { GeneratedFile } from './templates';
+import { kebab, names, resolveLocales } from './templates';
 
 // One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
 // fixture reach the kinds, the pure file list and the writer through this module, and a second path
@@ -36,6 +42,24 @@ export { GENERATORS } from './generate-kinds';
 export type { WriteReport } from './generate-write';
 export { dedupe, writeFiles } from './generate-write';
 
+/**
+ * Names to suggest when the API index already holds the requested one, in order: the feature's
+ * prefix, the kind's suffix, then that suffix numbered — kebab output, so each pastes into a shell
+ * as one argument. The caller re-plans each and offers the first the index does not hold either.
+ */
+const freeNames = (
+  kind: Generator,
+  name: string,
+  feature: string | undefined,
+): readonly string[] => {
+  const suffixed = `${kebab(name)}-${kind.split(':').at(-1) ?? kind}`;
+  return [
+    ...(feature === undefined ? [] : [`${kebab(feature)}-${kebab(name)}`]),
+    suffixed,
+    ...Array.from({ length: 8 }, (_unused, index) => `${suffixed}-${index + 2}`),
+  ];
+};
+
 export const generateCommand: CliCommand = {
   spec: generateSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -46,7 +70,7 @@ export const generateCommand: CliCommand = {
     // Both flags are resolved before a single file is planned: a bad surface or a locale that is
     // really a path fails here, with nothing written and nothing to undo.
     const surface = readSurface(flagString(ctx.args, 'surface'), kind, name);
-    const locales = resolveLocales(flagList(ctx.args, 'locales'));
+    const locales = resolveLocales(await namedOrAppLocales(root, flagList(ctx.args, 'locales')));
     const at = flagString(ctx.args, 'at');
     // Read with the two above, and refused here for their reason: the value is spliced into the
     // emitted source three times, and a value that is not a `<resource>:<verb>` is a page the app
@@ -55,6 +79,10 @@ export const generateCommand: CliCommand = {
     // Read before a file is planned, like the flags above: which module a generated component
     // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
     const catalogModule = await resolveCatalogModule(root);
+    // And for the same reason: which package a generated `repo.ts` imports the typed handle from.
+    const dbModule = await resolveDbModule(root);
+    // And whether the app has the frame a resource's page sits in.
+    const shell = existsSync(containedPath(root, SHELL_MODULE));
     // Read for the same reason: which errors the slice declares is written on THIS app's disk.
     const slice = sliceDir(surface, kebab(featureFlag ?? name));
     // A named slice that is not there is refused, never invented (X_FEATURE_UNKNOWN).
@@ -64,46 +92,91 @@ export const generateCommand: CliCommand = {
     // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
     const sliceEntity = await readSliceFile(root, kind, slice, 'entity.ts');
     const sliceRepo = await readSliceFile(root, kind, slice, 'repo.ts');
-    const files = generate({
-      kind,
-      name,
-      ...(featureFlag === undefined ? {} : { feature: featureFlag }),
-      ...(sliceErrors === undefined ? {} : { sliceErrors }),
-      ...(sliceEntity === undefined ? {} : { sliceEntity }),
-      ...(sliceRepo === undefined ? {} : { sliceRepo }),
-      ...(at === undefined ? {} : { at }),
-      ...(permission === undefined ? {} : { permission }),
-      surface,
-      live: flagBool(ctx.args, 'live'),
-      admin: flagBool(ctx.args, 'admin'),
-      locales,
-      ...(catalogModule === undefined ? {} : { catalogModule }),
-    });
+    const planFor = (planned: string) =>
+      generate({
+        kind,
+        name: planned,
+        ...(featureFlag === undefined ? {} : { feature: featureFlag }),
+        ...(sliceErrors === undefined ? {} : { sliceErrors }),
+        ...(sliceEntity === undefined ? {} : { sliceEntity }),
+        ...(sliceRepo === undefined ? {} : { sliceRepo }),
+        ...(at === undefined ? {} : { at }),
+        ...(permission === undefined ? {} : { permission }),
+        surface,
+        live: flagBool(ctx.args, 'live'),
+        admin: flagBool(ctx.args, 'admin'),
+        locales,
+        ...(catalogModule === undefined ? {} : { catalogModule }),
+        ...(dbModule === undefined ? {} : { dbModule }),
+        shell,
+      });
+    const files = planFor(name);
+    // On the planned files, before a dry run answers or anything lands: a name whose type spelling
+    // the emitted code also uses as a global is a slice that does not compile.
+    refuseShadowedTypes(files, kind, name);
+    // The caller's own invocation, EVERY flag it set included: without `--feature` the fix wrote
+    // a second slice beside the one that conflicted.
+    const flags = reproducedFlags(generateCommand.spec, ctx.args);
+    const invocation = [invocationOf(ctx, 'g'), kind, quoteArg(name), ...flags].join(' ');
+    // A module the API index would list under a name it already holds: refused before anything is
+    // written, with the same run under a name that is free — re-planned and re-checked, so the
+    // suggestion is never itself a conflict.
+    const pathsOf = (planned: readonly GeneratedFile[]) => planned.map((file) => file.path);
+    const held = await indexBindingFindings(root, pathsOf(files), '');
+    let bindings: readonly Finding[] = [];
+    if (held.length > 0) {
+      let free = freeNames(kind, name, featureFlag).at(-1) ?? name;
+      for (const candidate of freeNames(kind, name, featureFlag)) {
+        if ((await indexBindingFindings(root, pathsOf(planFor(candidate)), '')).length > 0)
+          continue;
+        free = candidate;
+        break;
+      }
+      const renamed = [invocationOf(ctx, 'g'), kind, quoteArg(free), ...flags].join(' ');
+      bindings = held.map((finding) => ({ ...finding, fix: renamed }));
+    }
+    const force = flagBool(ctx.args, 'force');
     if (flagBool(ctx.args, 'dry-run')) {
+      // The write plan, never the bare file list: what the real run would write, skip and refuse.
+      const plan = await planWrites(root, files, force, invocation);
+      const findings = [...plan.conflicts, ...bindings];
+      const planned = findings.length === 0 ? plan.written : [];
       return {
-        ok: true,
+        ok: findings.length === 0,
         command: 'g',
-        summary: msg('cli.generate.planned', { count: files.length, kind, name }),
-        data: { files: files.map((file) => file.path), dryRun: true },
-        lines: files.map((file) => msg('cli.file.added', { path: file.path })),
+        summary: msg('cli.generate.planned', { count: planned.length, kind, name }),
+        data: { files: planned, dryRun: true },
+        lines: planned.map((file) => msg('cli.file.added', { path: file })),
+        findings,
       };
     }
-    // The caller's own invocation, EVERY flag it set included: without `--feature` the fix wrote
-    // a second slice beside the one that conflicted.
-    const invocation = [
-      invocationOf(ctx, 'g'),
-      kind,
-      quoteArg(name),
-      ...reproducedFlags(generateCommand.spec, ctx.args),
-    ].join(' ');
-    const report = await writeFiles(root, files, flagBool(ctx.args, 'force'), invocation);
-    // The two edits a generated primitive needs outside its own slice, performed rather than left
-    // as findings: a declared permission granted to a role, and a job listed in `defineApi`.
-    // Before the manifest load below, so the projection sees both.
+    const report =
+      bindings.length > 0
+        ? { written: [], conflicts: bindings }
+        : await writeFiles(root, files, force, invocation);
+    // The three edits a generated primitive needs outside its own slice, performed rather than
+    // left as findings: a declared permission granted to a role, a job listed in `defineApi`, and
+    // an entity added to the typed handle its `repo.ts` reads through. Before the manifest load
+    // below, so the projection sees all three — a repo reading a table the handle lacks would not
+    // load at all.
+    const handle = await registerGeneratedEntities(root, report.written, dbModule);
+    // And a fourth, for `--admin`: the override it wrote, listed where `defineAdmin()` reads it.
+    const adminWiring = await registerAdminResources(root, report.written);
+    // And a fifth, last because the others add imports too: every sibling workspace a written file
+    // imports, declared in the manifest it landed under — or `package-shape` refuses the output.
     const edited = [
-      ...(await grantGeneratedPermissions(root, report.written)),
-      ...(await registerGeneratedPrimitives(root, report.written)),
+      ...new Set([
+        ...(await grantGeneratedPermissions(root, report.written)),
+        ...(await registerGeneratedPrimitives(root, report.written)),
+        ...handle.edited,
+        ...adminWiring.edited,
+        ...(await declareGeneratedImports(root, report.written)),
+      ]),
     ];
+    // A grant that edit could not place is said so, with the role each permission belongs to: an
+    // app whose role map is not the scaffold's got no grant and no word, and a 403 on every
+    // endpoint the run had just written.
+    const ungranted = await ungrantedByGenerator(root, report.written);
     // A locale's catalog existing on disk and the app being able to select it are two different
     // facts — see `syncI18nIndex`. Runs before the manifest load below so a route or resource
     // this same invocation just wrote never gets projected against a stale catalog registration.
@@ -133,17 +206,36 @@ export const generateCommand: CliCommand = {
         buildId = manifest.buildId;
       } else loadFailures.push(...findings);
     }
-    const findings = [...report.conflicts, ...indexSync.findings, ...loadFailures];
+    const findings = [
+      ...report.conflicts,
+      ...handle.findings,
+      ...ungranted,
+      ...adminWiring.findings,
+      ...indexSync.findings,
+      ...loadFailures,
+    ];
     // One list behind all three renderings. The manifest was printed as a `+` line while the count
     // beside it came from `report.written` alone, so `x g island` said "wrote 2 file(s)" over three
     // lines — and `--json` carried the shorter list, which is the drift `--json` exists to prevent.
     const written = [...report.written, ...edited, ...artifacts];
+    // Named only over a clean run: with a finding, the finding's own `fix:` is the next command.
+    const table = names(isEntityKind(kind) ? name : (featureFlag ?? name)).table;
+    const next = findings.length === 0 ? nextSteps(report.written, edited, table) : [];
     return {
       ok: findings.length === 0,
       command: 'g',
-      summary: msg('cli.generate.wrote', { count: written.length, kind, name }),
+      summary:
+        next.length === 0
+          ? msg('cli.generate.wrote', { count: written.length, kind, name })
+          : msg('cli.generate.wroteNext', {
+              count: written.length,
+              kind,
+              name,
+              next: next.join(' && '),
+            }),
       data: {
         files: written,
+        ...(next.length === 0 ? {} : { next }),
         ...(buildId === undefined ? {} : { manifest: { buildId } }),
       },
       lines: written.map((path) => msg('cli.file.added', { path })),
@@ -152,6 +244,59 @@ export const generateCommand: CliCommand = {
   },
 };
 
+/**
+ * `--locales` when the caller named any, and otherwise every locale the app already has a catalog
+ * for: a key written to `en` alone in an app that also ships `es` renders ⟦key⟧ for every Spanish
+ * reader. A stem that is not a locale tag is some other JSON file, and not a catalog to write to.
+ */
+async function namedOrAppLocales(
+  root: string,
+  named: readonly string[],
+): Promise<readonly string[]> {
+  if (named.length > 0) return named;
+  return (await catalogLocales(root)).filter((stem) => {
+    try {
+      return Intl.getCanonicalLocales(stem).length === 1;
+    } catch {
+      return false;
+    }
+  });
+}
+
+const isEntityKind = (kind: Generator): boolean => kind === 'entity' || kind === 'resource';
+
+/**
+ * What a run that declared a table owes before the app can read it, in the order it has to
+ * happen — each one a command that runs as printed. `bunx x`, never a bare `x`: `bun install`
+ * links the binary into `./node_modules/.bin` and nowhere on PATH.
+ *
+ * `bun install` leads when a manifest gained a workspace edge: the handle imports the entity from
+ * the web workspace, and an edge only a manifest declares is not linked until the install runs.
+ * `x db gen` then writes the migration AND `packages/db/schema/`, which the `drift` step holds.
+ */
+export function nextSteps(
+  written: readonly string[],
+  edited: readonly string[],
+  table: string,
+): readonly string[] {
+  if (!written.some((path) => path.endsWith('/entity.ts'))) return [];
+  return [
+    ...(edited.some((path) => path.endsWith('package.json')) ? ['bun install'] : []),
+    `bunx x db gen "create ${table}"`,
+    'bunx x db migrate',
+    // A page that mounts an island has a byte budget only a build can weigh — measured on `x new`'s
+    // app (`RESOURCE_PAGE_BUDGET`), and an app that charges more per document is over it on this
+    // run rather than on the next `bin/check`.
+    ...(written.some((path) => path.endsWith('/page.tsx')) ? [MEASURE_PAGE] : []),
+  ];
+}
+
+/** The two commands that weigh a page against its budget: the build writes the bytes it reads. */
+export const MEASURE_PAGE = 'bunx x build --target static && bunx x verify --only budgets';
+
+/** The frame `x new` writes: a resource's page renders inside it when the app has one. */
+export const SHELL_MODULE = 'apps/web/shared/shell.tsx';
+
 /**
  * The slice's `errors.ts`, for the two generators whose template throws from it. Only those two:
  * a route or an island names no slice, and the "feature" the fallback derives for them is a path
@@ -167,20 +312,23 @@ async function readSliceErrors(
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }
 
+/** The generators whose output depends on what the slice's `entity.ts` / `repo.ts` declare. */
+const READS_SLICE: ReadonlySet<Generator> = new Set(['job', 'task', 'action', 'mutator', 'query']);
+
 /**
- * `job`, `task`, `action` and `mutator`: the slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the
- * generator's kind is neither or the file does not exist yet. `readSliceErrors`'s reason —
- * whichever generator reads it decides on THIS app's disk, not on a default the template assumes.
+ * The slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the generator's kind reads
+ * neither or the file does not exist yet. `readSliceErrors`'s reason — whichever generator reads
+ * it decides on THIS app's disk, not on a default the template assumes. `query` reads them for its
+ * test alone: whether it may store a row is a fact about the entity an author may have reshaped.
+ * Exported so a test can ask which kinds read the disk without running a whole generation.
  */
-async function readSliceFile(
+export async function readSliceFile(
   root: string,
   kind: Generator,
   slice: string,
   name: 'entity.ts' | 'repo.ts',
 ): Promise<string | undefined> {
-  if (kind !== 'job' && kind !== 'task' && kind !== 'action' && kind !== 'mutator') {
-    return undefined;
-  }
+  if (!READS_SLICE.has(kind)) return undefined;
   const file = containedPath(root, `${slice}/${name}`);
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }

package/src/cmd-help.ts

@@ -2,7 +2,9 @@
 // never describe a flag that does not exist. Built as a factory over the spec list to keep the
 // registry acyclic.
 
+import { nearestName } from '@ultimat3/core';
 import type { CliCommand, CommandContext } from './command';
+import { UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import type { CommandSpec, FlagSpec } from './parse';
@@ -18,17 +20,28 @@ const flagLine = (flag: FlagSpec): string => {
  * The one resolution of a topic, read by both renderers. `--json` filtered on `spec.name === topic`
  * of its own, so the two disagreed about exactly the inputs a caller is least sure of: `x help
  * generate --json` answered `[]` — "that command does not exist" — while the page beside it printed
- * `g`, and `x help nosuch --json` answered `[]` while the page printed the whole catalogue.
+ * `g`. A topic naming no command is refused, as `x <topic>` itself is: answering the catalogue
+ * with exit 0 read as that command's usage to a caller that never compared the names.
  */
 const specFor = (
   specs: readonly CommandSpec[],
   topic: string | undefined,
-): CommandSpec | undefined =>
-  topic === undefined
-    ? undefined
-    : specs.find((entry) => entry.name === topic || (entry.aliases ?? []).includes(topic));
+): CommandSpec | undefined => {
+  if (topic === undefined) return undefined;
+  const found = specs.find(
+    (entry) => entry.name === topic || (entry.aliases ?? []).includes(topic),
+  );
+  if (found !== undefined) return found;
+  const names = specs.map((entry) => entry.name);
+  const nearest = nearestName(topic, [...names, ...specs.flatMap((entry) => entry.aliases ?? [])]);
+  throw new UnknownCommandError({
+    path: `help ${topic}`,
+    known: names,
+    suggestion: nearest === undefined ? 'help' : `help ${nearest}`,
+  });
+};
 
-/** What `--json` reports: the one resolved command, or — as the human render does — all of them. */
+/** What `--json` reports: the one resolved command, or — with no topic — all of them. */
 export function helpTopic(
   specs: readonly CommandSpec[],
   topic: string | undefined,

package/src/cmd-i18n.ts

@@ -196,14 +196,15 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   const { registered, findings: indexFindings } = await syncI18nIndex(root);
 
   const keys = catalogKeys(seeded).length;
+  // The catalog is on disk either way, but a finding fails the run: a `packages/i18n/src/index.ts`
+  // that would not import is why `from` may be the framework's `en` instead of the app's own
+  // default, and an index the locale could not be registered in is a red `i18n` gate step.
+  const findings = [...indexFindings, ...app.findings];
   return {
-    // The catalog is on disk, so the command did what it was asked. `loadApp`'s findings ride along
-    // rather than flip that: a `packages/i18n/src/index.ts` that would not import is why `from` may
-    // be the framework's `en` instead of the app's own default, and silence there is the bug.
-    ok: true,
+    ok: findings.length === 0,
     command: 'i18n',
     summary: msg('cli.i18n.added', { locale, keys, from: from ?? locale }),
-    findings: [...indexFindings, ...app.findings],
+    findings,
     // `registered` is false only for an app with no `packages/i18n` at all — a fact a caller has
     // to be able to read, because it is the one case where the locale is on disk and unselectable.
     data: { locale, from: from ?? locale, keys, path, registered },
@@ -274,16 +275,16 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
   const { registered, findings: indexFindings } = await syncI18nIndex(root);
 
   const total = catalogKeys(merged).length;
+  // Same as `runAdd`: the merge landed, and a finding still fails the run.
+  const findings = [...indexFindings, ...app.findings];
   return {
-    // Same as `runAdd`: the merge landed, and `loadApp`'s findings say whether `from` is the app's
-    // own default or the framework's fallback standing in for an i18n module that would not import.
-    ok: true,
+    ok: findings.length === 0,
     command: 'i18n',
     summary: msg('cli.i18n.synced', { locale, from: from ?? locale, added: added.length, total }),
     // The keys themselves, raw — `runCheck` lists gaps the same way, because a key is a value an
     // author copies and never prose the catalog owns.
     lines: seeded ? added.map((key) => `  ${key}`) : [],
-    findings: [...indexFindings, ...app.findings],
+    findings,
     data: {
       locale,
       from: from ?? locale,

package/src/cmd-jobs-spec.ts

@@ -3,7 +3,17 @@
 
 import type { CommandSpec } from './parse';
 
-export const JOBS_SUBCOMMANDS = ['ls', 'show', 'retry', 'cancel', 'drain'] as const;
+export const JOBS_SUBCOMMANDS = [
+  'ls',
+  'show',
+  'retry',
+  'cancel',
+  'rm',
+  'promote',
+  'pause',
+  'resume',
+  'drain',
+] as const;
 
 /**
  * The drivers a drain may move work ONTO — every one of them durable, and that is the whole rule.
@@ -13,9 +23,9 @@ export const DRAIN_TARGETS = ['redis', 'nats'] as const;
 
 export const jobsSpec: CommandSpec = {
   name: 'jobs',
-  summary: 'list, show, retry, cancel and drain the job queue',
+  summary: 'list, show, retry, cancel, remove and promote jobs; pause and resume a queue; drain',
   usage:
-    'x jobs [ls|show <id>|retry <id>|cancel <id>|drain --to <driver>] [--queue q] [--state s] [--limit n] [--from-step name] [--reason text] [--to driver] [--dry-run] [--json]',
+    'x jobs [ls|show <id>|retry <id>|cancel <id>|rm <id>|promote <id>|pause <queue>|resume <queue>|drain --to <driver>] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--to driver] [--dry-run] [--json]',
   requiresApp: true,
   subcommands: JOBS_SUBCOMMANDS,
   // The bare `x jobs` lists; it never retries, cancels or drains anything.
@@ -25,6 +35,12 @@ export const jobsSpec: CommandSpec = {
     { name: 'state', type: 'string', summary: 'filter by job state' },
     { name: 'limit', type: 'string', summary: 'max rows to return' },
     { name: 'name', type: 'string', summary: 'filter by job name' },
+    {
+      name: 'after',
+      type: 'string',
+      summary: 'ls: the next page — the cursor the previous page printed',
+      subcommands: ['ls'],
+    },
     // Each of these is read by ONE subcommand — `retryJob`, `cancelJob`, `runDrain` — and says
     // so in its own summary. The scope is what makes the parser refuse it anywhere else instead
     // of accepting it and ignoring it: `x db gen --dry-run` parsed and wrote the migration.