@ultimat3/cli 29.4.0 → 30.1.0

package/src/generate-feature.ts

@@ -3,7 +3,9 @@
 // `entity('reports', { title, price })` nobody asked for, and the `drift` step then demanded a
 // migration for the table. Only `x g entity` and `x g resource` create a feature's data.
 
-import { existsSync } from 'node:fs'; // why: a synchronous directory probe; Bun.file answers files, not directories.
+import { existsSync, readdirSync } from 'node:fs'; // why: a synchronous directory probe and listing; Bun.file answers files, not directories.
+// why: Bun ships no path helpers.
+import { dirname, join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
 import type { Generator } from './generate-kinds';
 import { containedPath } from './generate-write';
@@ -16,15 +18,89 @@ const WRITES_INTO_SLICE: ReadonlySet<Generator> = new Set<Generator>([
   'query',
   'job',
   'task',
+  'backfill',
 ]);
 
-/** Declared beside its one thrower: `errors.ts` sits at its 500-line ceiling. */
+/** What makes a directory a slice rather than a page: a page directory holds a route and no module. */
+const SLICE_MEMBERS = [
+  'entity.ts',
+  'policy.ts',
+  'repo.ts',
+  'service.ts',
+  'actions',
+  'queries',
+  'jobs',
+  'tasks',
+  'live',
+];
+
+/** How far a `--feature` may be from a slice and still read as a typo of it. */
+const NEAR_DISTANCE = 2;
+
+const editDistance = (a: string, b: string): number => {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j += 1) {
+      const swap = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+      row[j] = Math.min((previous[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, swap);
+    }
+    previous = row;
+  }
+  return previous[b.length] ?? 0;
+};
+
+/** The nearest slice within `NEAR_DISTANCE`, first in the given order on a tie. */
+export function closestSlice(feature: string, slices: readonly string[]): string | undefined {
+  let best: string | undefined;
+  let bestDistance = NEAR_DISTANCE + 1;
+  for (const slice of slices) {
+    const distance = editDistance(feature, slice);
+    if (distance < bestDistance) {
+      best = slice;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+
+/** The surface's slices, sorted. A surface with no directory yet has none. */
+export const slicesBeside = (root: string, slice: string): readonly string[] => {
+  const surface = containedPath(root, dirname(slice));
+  if (!existsSync(surface)) return [];
+  return readdirSync(surface, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => SLICE_MEMBERS.some((member) => existsSync(join(surface, name, member))))
+    .sort();
+};
+
+export interface FeatureUnknownInput {
+  readonly kind: Generator;
+  readonly name: string;
+  readonly feature: string;
+  readonly slice: string;
+  readonly slices: readonly string[];
+}
+
+/**
+ * Declared beside its one thrower: `errors.ts` sits at its 500-line ceiling.
+ *
+ * Near a real slice, the fix is the command the author meant. `x g resource <typo>` first is how a
+ * typo became a table. It stays the fix when nothing is near, with the slices in the cause.
+ */
 export class FeatureUnknownError extends UltimateError {
-  constructor(input: { readonly feature: string; readonly slice: string }) {
+  constructor(input: FeatureUnknownInput) {
+    const near = closestSlice(input.feature, input.slices);
+    const existing =
+      input.slices.length === 0 ? 'no slice exists yet' : `slices: ${input.slices.join(', ')}`;
     super({
       code: 'X_FEATURE_UNKNOWN',
-      cause: `--feature ${quoteArg(input.feature)} names ${input.slice}, which does not exist — a generator writing into a slice never invents one, or its entity table`,
-      fix: `x g resource ${quoteArg(input.feature)}`,
+      cause: `--feature ${quoteArg(input.feature)} names ${input.slice}, which does not exist (${existing}) — a generator writing into a slice never invents one, or its entity table`,
+      fix:
+        near === undefined
+          ? `x g resource ${quoteArg(input.feature)}`
+          : `x g ${quoteArg(input.kind)} ${quoteArg(input.name)} --feature ${quoteArg(near)}`,
     });
   }
 }
@@ -35,8 +111,9 @@ export function assertFeatureExists(
   kind: Generator,
   feature: string | undefined,
   slice: string,
+  name: string,
 ): void {
   if (feature === undefined || !WRITES_INTO_SLICE.has(kind)) return;
   if (existsSync(containedPath(root, slice))) return;
-  throw new FeatureUnknownError({ feature, slice });
+  throw new FeatureUnknownError({ kind, name, feature, slice, slices: slicesBeside(root, slice) });
 }

package/src/generate-files.ts

@@ -6,6 +6,7 @@ import { NotImplementedError } from '@ultimat3/core';
 import { BadFlagError } from './errors';
 import type { Generator } from './generate-kinds';
 import { assertLiveSupported, assertSurfaceSupported, GENERATORS } from './generate-kinds';
+import type { SignInMode } from './generate-sign-in-mode';
 import { dedupe } from './generate-write';
 import { quoteArg } from './shell-quote';
 import type { GeneratedFile, Surface } from './templates';
@@ -27,6 +28,9 @@ import {
   taskFiles,
 } from './templates';
 import { adminCatalogFiles } from './templates/admin-catalog';
+import { helmMonitoringFiles } from './templates/scaffold-helm-alerts';
+import { oidcSignInFiles } from './templates/sign-in-oidc';
+import { passwordSignInFiles } from './templates/sign-in-password';
 
 export interface GenerateOptions {
   readonly kind: Generator;
@@ -89,6 +93,8 @@ export interface GenerateOptions {
    * written beside it as `entity-<name>.ts` + `repo-<name>.ts`. Read off the disk by `run`.
    */
   readonly sibling?: boolean;
+  /** `sign-in` only: which shape — `--password` or `--oidc <provider>`. Required for that kind. */
+  readonly signIn?: SignInMode;
 }
 
 const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
@@ -234,6 +240,24 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
           ...(options.catalogModule === undefined ? {} : { catalogModule: options.catalogModule }),
         }),
       );
+    case 'sign-in': {
+      // The shape's own files only. The edits outside them — the authenticator swap, the config —
+      // read the app's disk, so `generate-sign-in.ts` makes them; this stays a pure function.
+      const signIn = options.signIn ?? { kind: 'password' };
+      const shape = {
+        locales: options.locales ?? ['en'],
+        ...(options.catalogModule === undefined ? {} : { catalogModule: options.catalogModule }),
+      };
+      return dedupe(
+        signIn.kind === 'password'
+          ? passwordSignInFiles(shape)
+          : oidcSignInFiles(signIn.provider, shape),
+      );
+    }
+    case 'chart-alerts':
+      // `name` is the chart's own (`Chart.yaml`), which its helpers are named after. The values
+      // blocks are an edit to a file the app owns, so `generate-chart-alerts.ts` makes it.
+      return helmMonitoringFiles(names(options.name));
     case 'route':
       // `--locales` reaches the route generator too: its catalog entry is the route's title and
       // description, and a locale asked for on the command line is a locale that gets a file.

package/src/generate-format-written.ts

@@ -0,0 +1,32 @@
+// `x g` formats the source it just wrote. Templates are pre-formatted (`generate-format.test.ts`
+// holds them to it), and a template is a string with its line breaks typed by hand, for every name
+// an app can pick: a name long enough to wrap a line none of those runs named landed in an app
+// whose first `lint` was then red over code nobody typed. The app's own Biome, under its own config.
+
+import { existsSync } from 'node:fs'; // why: a synchronous file probe; Bun.file answers asynchronously.
+// why: Bun exposes no path-join primitive.
+import { join } from 'node:path';
+import type { Runner } from './exec';
+
+const SOURCE = /\.tsx?$/;
+
+/**
+ * Best effort, and that is the whole contract: the files are already on disk and correct, this only
+ * re-wraps them. A binary the app has not installed, a config it has not written or a version that
+ * refuses them must not turn `x g` red over a file the `lint` step would have reported anyway, so
+ * the verdict is left for that step. The app's own binary or none: `bunx` would download one.
+ */
+export async function formatWritten(
+  root: string,
+  written: readonly string[],
+  runner: Runner,
+): Promise<void> {
+  const sources = written.filter((path) => SOURCE.test(path));
+  if (sources.length === 0) return;
+  if (!['biome.json', 'biome.jsonc'].some((config) => existsSync(join(root, config)))) return;
+  const biome = Bun.which('biome', { PATH: join(root, 'node_modules', '.bin') });
+  if (biome === null) return;
+  await runner([biome, 'check', '--write', '--files-ignore-unknown=true', ...sources], {
+    cwd: root,
+  });
+}

package/src/generate-kinds.ts

@@ -27,6 +27,8 @@ export const GENERATORS = [
   'island',
   'admin:page',
   'guard',
+  'sign-in',
+  'chart-alerts',
 ] as const;
 
 export type Generator = (typeof GENERATORS)[number];
@@ -280,4 +282,8 @@ const EXAMPLE_NAME: Readonly<Record<Generator, string>> = {
   island: 'counter',
   'admin:page': 'ops',
   guard: 'migration-safety',
+  // Sign-in takes no name: its "example" is the flag that picks a shape, so the line still runs.
+  'sign-in': '--password',
+  // No name either: an app has one chart. `--print` runs with or without one.
+  'chart-alerts': '--print',
 };

package/src/generate-sign-in-config.ts

@@ -0,0 +1,100 @@
+// The two edits `x g sign-in` makes to the app's `app.config.ts`: `auth.signInPath`, so a 401 page
+// links to the page it wrote, and — for an OIDC sign-in — the issuer and client keys declared in
+// `envSchema`, so `x env example` lists them. Text edits at anchors `x new` writes; a file reshaped
+// past them gets a finding with the exact lines, never a guess.
+
+import { ERROR_DOCS_URL, stripComments } from '@ultimat3/core';
+import type { Finding } from './output';
+
+export const APP_CONFIG = 'app.config.ts';
+
+/** One env key the sign-in needs, as `envSchema` declares it. */
+export interface SignInEnvKey {
+  readonly key: string;
+  readonly description: string;
+  readonly secret?: boolean;
+  readonly type?: 'string' | 'url';
+}
+
+export interface ConfigEdit {
+  readonly contents: string;
+  readonly findings: readonly Finding[];
+}
+
+/** `lines` is code to paste — the fix opens with it, and says where after a `#`. */
+const unplaced = (what: string, lines: string): Finding => ({
+  code: 'X_GENERATE_CONFLICT',
+  cause: `${APP_CONFIG} has no ${what} where x new writes one, so x g sign-in did not edit it`,
+  fix: `${lines}   # paste into ${what} in ${APP_CONFIG}`,
+  docs: ERROR_DOCS_URL,
+  at: APP_CONFIG,
+});
+
+const SIGN_IN_PATH_LINE = (path: string): string => `auth: { signInPath: '${path}' },`;
+
+/**
+ * `auth: { signInPath }` after the config's `name:` line, unless a sign-in path is declared. Both
+ * tests read the code with its comments blanked: a `// signInPath: …` the author parked declares
+ * nothing, and skipping the edit over it left a 401 page linking nowhere.
+ */
+function withSignInPath(source: string, path: string): ConfigEdit {
+  const code = stripComments(source);
+  if (/\bsignInPath\s*:/.test(code)) return { contents: source, findings: [] };
+  const anchor = /(export const config = defineConfig\(\{\n(\s*)name: [^\n]*\n)/.exec(source);
+  if (anchor === null || /\n\s*auth:\s*\{/.test(code)) {
+    return {
+      contents: source,
+      findings: [unplaced('defineConfig({ … })', SIGN_IN_PATH_LINE(path))],
+    };
+  }
+  const indent = anchor[2] ?? '  ';
+  const line = `${indent}// The page a refused browser is sent to: x g sign-in wrote it.\n${indent}${SIGN_IN_PATH_LINE(path)}\n`;
+  const at = anchor.index + (anchor[1] ?? '').length;
+  return { contents: `${source.slice(0, at)}${line}${source.slice(at)}`, findings: [] };
+}
+
+const envEntry = (entry: SignInEnvKey): string =>
+  [
+    `  ${entry.key}: {`,
+    `    type: '${entry.type ?? 'string'}',`,
+    '    required: false,',
+    "    role: ['web', 'sync'],",
+    ...(entry.secret === true ? ['    secret: true,'] : []),
+    // Descriptions are this generator's own constants, written without a quote.
+    `    description: '${entry.description}',`,
+    '  },',
+  ].join('\n');
+
+/** Each key `envSchema` does not already declare, before its closing `} satisfies EnvSchema;`. */
+function withEnvKeys(source: string, keys: readonly SignInEnvKey[]): ConfigEdit {
+  const missing = keys.filter((entry) => !new RegExp(`\\n\\s*${entry.key}\\s*:`).test(source));
+  if (missing.length === 0) return { contents: source, findings: [] };
+  const close = source.indexOf('\n} satisfies EnvSchema;');
+  if (close === -1) {
+    return {
+      contents: source,
+      findings: [
+        unplaced(
+          'the envSchema object',
+          `export const envSchema = { ${missing.map((entry) => `${entry.key}: { type: '${entry.type ?? 'string'}', required: false }`).join(', ')} }`,
+        ),
+      ],
+    };
+  }
+  const block = missing.map(envEntry).join('\n');
+  return {
+    contents: `${source.slice(0, close)}\n${block}${source.slice(close)}`,
+    findings: [],
+  };
+}
+
+/** Both edits, in order, over the file's text as it stands. */
+export function signInConfigEdit(
+  source: string,
+  signInPath: string,
+  keys: readonly SignInEnvKey[],
+): ConfigEdit {
+  const pathed = withSignInPath(source, signInPath);
+  const keyed = withEnvKeys(pathed.contents, keys);
+  return { contents: keyed.contents, findings: [...pathed.findings, ...keyed.findings] };
+}

package/src/generate-sign-in-manifest.ts

@@ -0,0 +1,28 @@
+// The two projections `x g` keeps current after a write, for `x g sign-in`: `x.manifest.json` and
+// `openapi.json`, refreshed only where the app already keeps them — the same rule `cmd-generate.ts`
+// holds, so a generator never hands an app a generated file it did not ask to maintain.
+
+import { existsSync } from 'node:fs'; // why: Bun has no synchronous existence check.
+import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { writeAppArtifacts } from './app-artifacts';
+import { appManifest } from './app-manifest';
+import { containedPath } from './generate-write';
+import type { Finding } from './output';
+
+/** The projections a real run would rewrite: the ones the app already keeps. */
+export const existingArtifacts = async (root: string): Promise<readonly string[]> =>
+  [MANIFEST_FILENAME, 'openapi.json'].filter((file) => existsSync(containedPath(root, file)));
+
+export interface Refreshed {
+  readonly written: readonly string[];
+  /** A module that would not load withholds the projection, and says so. */
+  readonly findings: readonly Finding[];
+}
+
+export async function appManifestIfAny(root: string): Promise<Refreshed> {
+  if (!existsSync(containedPath(root, MANIFEST_FILENAME))) return { written: [], findings: [] };
+  const { manifest, findings } = await appManifest(root);
+  if (findings.length > 0) return { written: [], findings };
+  const written = await writeAppArtifacts(root, manifest, { openapi: true, onlyExisting: true });
+  return { written, findings: [] };
+}

package/src/generate-sign-in-mode.ts

@@ -0,0 +1,101 @@
+// How `x g sign-in` is spelled: exactly one of `--oidc <provider>` or `--password`, and no `<name>`
+// — an app has one sign-in, so there is nothing to name. Both flags are refused on every other
+// generator: a flag accepted and ignored is a second spelling an agent believes did something.
+
+import { BUILTIN_OAUTH_PROVIDER_IDS } from '@ultimat3/auth';
+import { generateSpec } from './cmd-generate-spec';
+import { BadFlagError } from './errors';
+import type { Generator } from './generate-kinds';
+import type { ParsedArgs } from './parse';
+import { flagBool, flagString } from './parse';
+
+export type SignInMode =
+  | { readonly kind: 'password' }
+  | { readonly kind: 'oidc'; readonly provider: string };
+
+/** A provider id is one URL segment and two env-key prefixes: lowercase, digits, hyphens. */
+const PROVIDER = /^[a-z][a-z0-9-]{0,62}$/;
+
+/** What a run is called in its summary line: `password`, or the provider. */
+export const signInLabel = (mode: SignInMode): string =>
+  mode.kind === 'password' ? 'password' : mode.provider;
+
+/** The two flags, on a generator that is not `sign-in`, refused before anything is planned. */
+export function refuseSignInFlags(kind: Generator, args: ParsedArgs): void {
+  if (kind === 'sign-in') return;
+  for (const flag of ['oidc', 'password']) {
+    if (!args.flags.has(flag)) continue;
+    throw new BadFlagError({
+      flag,
+      command: `g ${kind}`,
+      reason: `--${flag} is the sign-in generator's`,
+      fix: flag === 'oidc' ? 'x g sign-in --oidc corp-sso' : 'x g sign-in --password',
+    });
+  }
+}
+
+/** The `x g` flags the sign-in generator reads; every other one would be ignored, so is refused. */
+const SIGN_IN_READS = new Set(['oidc', 'password', 'force', 'dry-run', 'locales']);
+
+/**
+ * Any other `x g` flag set to something but its default: the generator never reads `--feature`,
+ * `--surface`, `--at`, `--permission`, `--live`, `--admin` or `--locales`, so each would be a
+ * flag accepted and ignored — the second spelling the header refuses.
+ */
+function refuseUnreadFlags(args: ParsedArgs): void {
+  for (const flag of generateSpec.flags ?? []) {
+    if (SIGN_IN_READS.has(flag.name)) continue;
+    const value = args.flags.get(flag.name);
+    if (value === undefined || value === flag.default) continue;
+    throw new BadFlagError({
+      flag: flag.name,
+      command: 'g sign-in',
+      reason: `the sign-in generator does not read --${flag.name}, so it would change nothing`,
+      fix: 'x g sign-in --password',
+    });
+  }
+}
+
+export function readSignInMode(args: ParsedArgs): SignInMode {
+  refuseUnreadFlags(args);
+  const named = args.positionals[1];
+  if (named !== undefined) {
+    throw new BadFlagError({
+      flag: 'name',
+      command: 'g sign-in',
+      reason: `an app has one sign-in, so "${named}" names nothing — the shape is a flag`,
+      fix: 'x g sign-in --password',
+    });
+  }
+  const provider = flagString(args, 'oidc');
+  const passwordFlag = flagBool(args, 'password');
+  if ((provider === undefined) !== passwordFlag) {
+    throw new BadFlagError({
+      flag: passwordFlag ? 'password' : 'oidc',
+      command: 'g sign-in',
+      reason: passwordFlag
+        ? '--password and --oidc are two sign-ins, and the generator writes one'
+        : 'needs exactly one of --oidc <provider> or --password',
+      fix: 'x g sign-in --password',
+    });
+  }
+  if (provider === undefined) return { kind: 'password' };
+  if (!PROVIDER.test(provider)) {
+    throw new BadFlagError({
+      flag: 'oidc',
+      command: 'g sign-in',
+      reason: `"${provider}" is not a provider id: lowercase letters, digits and hyphens, a letter first`,
+      fix: 'x g sign-in --oidc corp-sso',
+    });
+  }
+  const builtin: readonly string[] = BUILTIN_OAUTH_PROVIDER_IDS;
+  if (builtin.includes(provider)) {
+    throw new BadFlagError({
+      flag: 'oidc',
+      command: 'g sign-in',
+      reason: `"${provider}" is a built-in provider, registered already; --oidc discovers a new issuer under its own id`,
+      fix: 'x g sign-in --oidc corp-sso',
+    });
+  }
+  return { kind: 'oidc', provider };
+}