@ultimat3/cli 29.3.2 → 30.0.0

package/src/templates/shapes/index.ts

@@ -0,0 +1,17 @@
+// The one table from a `--shape` name to its overlay. Typed over `NEW_SHAPES`, so a name with no
+// overlay (or an overlay with no name) is a compile error rather than a shape `x new` half-writes.
+
+import type { NewShape } from '../../new-shapes';
+import { apiShape } from './api';
+import { blogShape } from './blog';
+import { dashboardShape } from './dashboard';
+import type { ShapeOverlay } from './overlay';
+
+export const SHAPE_OVERLAYS: { readonly [S in NewShape]: ShapeOverlay } = {
+  api: apiShape,
+  blog: blogShape,
+  dashboard: dashboardShape,
+};
+
+export type { ShapeEdit, ShapeOverlay } from './overlay';
+export { applyEdit, applyOverlay, dropCatalogKeys } from './overlay';

package/src/templates/shapes/overlay.ts

@@ -0,0 +1,99 @@
+// What a shape IS: an overlay over the one scaffold `x new` already writes — files it leaves out,
+// catalog keys it drops, in-place edits, and files it adds. Never a second scaffold, so every fix to
+// the default reaches every shape on the next release.
+
+import { assert } from '@ultimat3/core';
+import type { GeneratedFile, NameSet } from '../naming';
+
+/** One in-place edit of a scaffold file: `find` must occur exactly once, or the overlay is stale. */
+export interface ShapeEdit {
+  readonly path: string;
+  readonly find: string;
+  readonly replace: string;
+}
+
+export interface ShapeOverlay {
+  /** Which scaffold it starts from: `true` is the one with the example `post` slice. */
+  readonly example: boolean;
+  /** Path prefixes of the base scaffold this shape leaves out. */
+  readonly drop: readonly string[];
+  /** Dotted catalog keys (a whole subtree each) the dropped files were the only readers of. */
+  readonly dropKeys: readonly string[];
+  readonly edits: (app: NameSet) => readonly ShapeEdit[];
+  /** Added; a path the base already holds is REPLACED, never merged (catalogs merge as JSON). */
+  readonly files: (app: NameSet) => readonly GeneratedFile[];
+  /**
+   * `x g` argv run in the written app, in order, after these files land (`new-shapes-generate.ts`):
+   * a capability a generator owns arrives through it, never re-spelled here. Absent: none.
+   */
+  readonly generate?: readonly (readonly string[])[];
+}
+
+const CATALOG = 'packages/i18n/catalogs/en.json';
+
+/** A stale overlay is the framework's bug, never the app's: the shape tests name which one. */
+const FIX = 'bun test packages/cli/src/templates/shapes';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** The catalog with each dotted key's subtree removed, re-serialised the way `catalogJson` does. */
+export function dropCatalogKeys(contents: string, keys: readonly string[]): string {
+  const catalog: unknown = JSON.parse(contents);
+  assert(isRecord(catalog), `${CATALOG} is not a JSON object`, FIX);
+  for (const key of keys) {
+    const segments = key.split('.');
+    const leaf = segments.pop() ?? '';
+    let node: unknown = catalog;
+    for (const segment of segments) node = isRecord(node) ? node[segment] : undefined;
+    assert(
+      isRecord(node) && Object.hasOwn(node, leaf),
+      `a shape drops catalog key ${key}, which the base scaffold no longer writes`,
+      FIX,
+    );
+    delete node[leaf];
+  }
+  return `${JSON.stringify(catalog, null, 2)}\n`;
+}
+
+/** `edit` applied to `contents`; an edit whose anchor moved is refused rather than skipped. */
+export function applyEdit(contents: string, edit: ShapeEdit): string {
+  const at = contents.indexOf(edit.find);
+  assert(
+    at !== -1 && contents.indexOf(edit.find, at + 1) === -1,
+    `a shape edits ${edit.path} at an anchor that is missing or not unique`,
+    FIX,
+  );
+  return contents.slice(0, at) + edit.replace + contents.slice(at + edit.find.length);
+}
+
+const dropped = (overlay: ShapeOverlay, path: string): boolean =>
+  overlay.drop.some((prefix) => path === prefix || path.startsWith(prefix));
+
+/** The base scaffold with `overlay` applied, in the base's order, added files last. */
+export function applyOverlay(
+  base: readonly GeneratedFile[],
+  overlay: ShapeOverlay,
+  app: NameSet,
+): readonly GeneratedFile[] {
+  const added = overlay.files(app);
+  const replaced = new Set(added.filter((file) => file.merge !== 'json').map((file) => file.path));
+  const edits = overlay.edits(app);
+  const kept = base
+    .filter((file) => !dropped(overlay, file.path) && !replaced.has(file.path))
+    .map((file): GeneratedFile => {
+      const own = edits.filter((edit) => edit.path === file.path);
+      if (file.path === CATALOG && file.merge === 'json') {
+        return { ...file, contents: dropCatalogKeys(file.contents, overlay.dropKeys) };
+      }
+      if (own.length === 0 || typeof file.contents !== 'string') return file;
+      return { ...file, contents: own.reduce(applyEdit, file.contents) };
+    });
+  const unapplied = edits.filter((edit) => !kept.some((file) => file.path === edit.path));
+  assert(
+    unapplied.length === 0,
+    `a shape edits ${unapplied.map((edit) => edit.path).join(', ')}, which the base scaffold does not write`,
+    FIX,
+  );
+  return [...kept, ...added];
+}

package/src/templates/shapes/shared-edits.ts

@@ -0,0 +1,46 @@
+// The edits more than one shape makes to the scaffold's own prose: the CLAUDE.md rows that point at
+// files a shape leaves out, and the one line each shape adds to CLAUDE.md (AGENTS.md) and README.md
+// naming itself.
+
+import type { NewShape } from '../../new-shapes';
+import type { ShapeEdit } from './overlay';
+
+/** The "Copy from" cells of CLAUDE.md's test table that name a file this shape does not write. */
+export const claudeRows = (instead: {
+  readonly page: string;
+  readonly island: string;
+}): readonly ShapeEdit[] => [
+  {
+    path: 'CLAUDE.md',
+    find: '| `apps/web/app/dashboard/page.test.ts` |',
+    replace: `| ${instead.page} |`,
+  },
+  {
+    path: 'CLAUDE.md',
+    find: '| `apps/web/shared/shell.test.ts` |',
+    replace: '| `packages/ui/src/card.test.ts` |',
+  },
+  {
+    path: 'CLAUDE.md',
+    find: '| `apps/web/shared/theme-toggle.island.test.ts` |',
+    replace: `| ${instead.island} |`,
+  },
+];
+
+const CLAUDE_ANCHOR =
+  'There is no global `x`: every command here is `bunx x …`, the CLI this app installs.\n';
+const README_ANCHOR = '## 🚀 Start\n\n';
+
+/** One line in CLAUDE.md and one in README.md: which shape this app started as, and what it is. */
+export const shapeLines = (shape: NewShape, what: string): readonly ShapeEdit[] => [
+  {
+    path: 'CLAUDE.md',
+    find: CLAUDE_ANCHOR,
+    replace: `${CLAUDE_ANCHOR}\nScaffolded as \`x new --shape ${shape}\`: ${what}.\n`,
+  },
+  {
+    path: 'README.md',
+    find: README_ANCHOR,
+    replace: `${README_ANCHOR}Scaffolded as \`--shape ${shape}\`: ${what}. Next: the three commands below, then \`bunx x g --help\`.\n\n`,
+  },
+];

package/src/templates/sign-in-action-tests.ts

@@ -0,0 +1,237 @@
+// The tests `x g sign-in` writes for its actions: each handler RUN inside a real request context,
+// over the app's migrated database (`migratedDatabase`, the framework tables included), so the
+// paths a person takes — refused, signed in, a second factor owed, signed out — are what is held.
+// `destroySessionTest` is both shapes'; the other two are the password shape's.
+
+/** The app's migrated database installed under `db()` for the file, as `page-db.test.ts` does. */
+const DATABASE = `// A template restore is ~0.5 s; its first build (initdb plus every migration) is what this bounds.
+const BOOT_MS = 120_000;
+
+const workerDatabase = reusableDatabase(() => migratedDatabase({ root: import.meta.dir }));
+beforeAll(async () => {
+  setDbClient(await workerDatabase());
+}, BOOT_MS);
+// Back to memory, so this file's database never reaches the next file's unit tests.
+afterAll(() => setDbClient(undefined));`;
+
+/** The imports every one of the three files shares, after its own `@ultimat3/auth` line. */
+const SHARED_IMPORTS = `import { migratedDatabase } from '@ultimat3/cli';
+import { runWithContext } from '@ultimat3/core';
+import { setDbClient } from '@ultimat3/db';
+import { asCtx, defineHttpConfig, requestContext } from '@ultimat3/http';
+import { afterAll, beforeAll, expect, reusableDatabase, unitTest } from '@ultimat3/testing';
+import { appAuth } from '../auth';`;
+
+/** The request the pipeline would build, the action run inside it, and both handed back. */
+const requestOf = (
+  path: string,
+  headers: string,
+  call: string,
+): string => `  const request = requestContext({
+    url: new URL('https://app.test${path}'),
+    method: 'POST',
+    role: 'web',
+    config: defineHttpConfig({ dev: true, rateLimit: { scope: 'process' } }),
+    requestHeaders: ${headers},
+  });
+  const ctx = asCtx(request);
+  const output = await runWithContext(ctx, () => ${call});
+  return { output, request };`;
+
+export const createSessionTest =
+  (): string => `// createSession, run inside a real request over the app's migrated database: a wrong password is
+// refused, a right one sets the session cookie, and a second factor still owed holds the challenge.
+import { generateTotpSecret, register, saveTotpSecret } from '@ultimat3/auth';
+${SHARED_IMPORTS}
+import { MFA_CHALLENGE_COOKIE, SECOND_FACTOR_PATH } from '../sign-in-challenge';
+import { AFTER_SIGN_IN } from '../sign-in-flow';
+import { createSession } from './create-session';
+
+${DATABASE}
+
+const target = createSession.named('createSession');
+const PASSWORD = 'a long scaffold test passphrase';
+
+/** One POST, as the pipeline hands it to the action: the response headers come back with it. */
+const post = async (input: Parameters<typeof target>[0], accept = 'application/json') => {
+${requestOf('/auth/sign-in', '{ accept }', 'target(input, { ctx })')}
+};
+
+/** A person who can sign in, under an address no other test in this file uses. */
+const person = (email: string) => register(appAuth(), { email, password: PASSWORD });
+
+/** Whether the response sets cookie \`name\`. */
+const sets = (request: { headers: Headers }, name: string): boolean =>
+  request.headers.getSetCookie().some((line) => line.startsWith(\`\${name}=\`));
+
+unitTest('createSession is a declared action', () => {
+  expect(target.kind).toBe('action');
+  expect(target.describe().name).toBe('createSession');
+});
+
+unitTest('createSession takes what its form posts and refuses the rest', async () => {
+  await expect(target.input).toAcceptInput({ email: 'ada@example.com', password: 'a passphrase' });
+  await expect(target.input).toRejectInput({ email: 'not an address', password: 'a passphrase' });
+});
+
+unitTest('a wrong password is refused with the one credential error', async () => {
+  await person('wrong@example.com');
+  const input = { email: 'wrong@example.com', password: 'not the passphrase' };
+  const refused = await post(input).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('X_UNAUTHENTICATED');
+});
+
+unitTest('the right password sets the session cookie and lands where it was going', async () => {
+  await person('right@example.com');
+  const input = { email: 'right@example.com', password: PASSWORD, next: '/posts' };
+  const { output, request } = await post(input);
+  expect(output).toEqual({ ok: true, next: '/posts', secondFactor: false });
+  expect(sets(request, appAuth().sessions.policy.cookieName)).toBe(true);
+  // An agent posting JSON gets the path as data, and no redirect.
+  expect(request.redirect).toBeUndefined();
+});
+
+unitTest('a browser posting the form is sent on with a 303', async () => {
+  await person('form@example.com');
+  const input = { email: 'form@example.com', password: PASSWORD };
+  const { output, request } = await post(input, 'text/html');
+  expect(output.next).toBe(AFTER_SIGN_IN);
+  expect(request.redirect).toEqual({ location: AFTER_SIGN_IN, status: 303 });
+});
+
+unitTest('a second factor still owed holds the challenge and sets no session', async () => {
+  const user = await person('mfa@example.com');
+  await saveTotpSecret(appAuth(), user.id, generateTotpSecret());
+  const { output, request } = await post({ email: 'mfa@example.com', password: PASSWORD });
+  expect(output).toEqual({ ok: false, next: SECOND_FACTOR_PATH, secondFactor: true });
+  expect(sets(request, MFA_CHALLENGE_COOKIE)).toBe(true);
+  expect(sets(request, appAuth().sessions.policy.cookieName)).toBe(false);
+});
+`;
+
+export const confirmSessionTest =
+  (): string => `// confirmSession, run inside a real request over the app's migrated database: with no challenge
+// held it refuses, a wrong code is refused, and the held challenge plus the right code signs in.
+import {
+  generateTotpSecret,
+  login,
+  register,
+  saveTotpSecret,
+  totpCode,
+  totpStep,
+} from '@ultimat3/auth';
+${SHARED_IMPORTS}
+import { challengeOf, MFA_CHALLENGE_COOKIE } from '../sign-in-challenge';
+import { confirmSession } from './confirm-session';
+
+${DATABASE}
+
+const target = confirmSession.named('confirmSession');
+const PASSWORD = 'a long scaffold test passphrase';
+
+/** One POST carrying \`cookie\`, as the pipeline hands it to the action. */
+const post = async (input: Parameters<typeof target>[0], cookie?: string) => {
+${requestOf(
+  '/auth/sign-in/second-factor',
+  "{ accept: 'application/json', ...(cookie === undefined ? {} : { cookie }) }",
+  'target(input, { ctx })',
+)}
+};
+
+/** A person with a second factor, and the cookie holding the challenge the first leg sealed. */
+const challenged = async (email: string) => {
+  const user = await register(appAuth(), { email, password: PASSWORD });
+  const secret = generateTotpSecret();
+  await saveTotpSecret(appAuth(), user.id, secret);
+  const first = await login(appAuth(), { email, password: PASSWORD }).catch((e: unknown) => e);
+  const challenge = challengeOf(first);
+  expect(challenge).not.toBeNull();
+  return { secret, cookie: \`\${MFA_CHALLENGE_COOKIE}=\${challenge}\` };
+};
+
+unitTest('confirmSession is a declared action', () => {
+  expect(target.kind).toBe('action');
+  expect(target.describe().name).toBe('confirmSession');
+});
+
+unitTest('confirmSession takes what its form posts and refuses the rest', async () => {
+  await expect(target.input).toAcceptInput({ code: '123456' });
+  await expect(target.input).toRejectInput({});
+});
+
+unitTest('a code with no challenge held is refused before anything is checked', async () => {
+  const refused = await post({ code: '123456' }).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('X_UNAUTHENTICATED');
+});
+
+unitTest('a wrong code against the held challenge is refused, and signs nobody in', async () => {
+  const { cookie } = await challenged('guess@example.com');
+  // Not six digits, so it is read as a recovery code — and this person was issued none.
+  const refused = await post({ code: 'not-a-recovery-code' }, cookie).catch((e: unknown) => e);
+  expect(refused).toBeUltimateError('X_UNAUTHENTICATED');
+});
+
+unitTest('the held challenge and the right code sign in, and drop the challenge', async () => {
+  const { secret, cookie } = await challenged('second@example.com');
+  const code = totpCode(secret, totpStep(new Date()));
+  const { output, request } = await post({ code, next: '/posts' }, cookie);
+  expect(output).toEqual({ ok: true, next: '/posts' });
+  const session = appAuth().sessions.policy.cookieName;
+  const lines = request.headers.getSetCookie();
+  expect(lines.some((line) => line.startsWith(\`\${session}=\`))).toBe(true);
+  // Cleared, an empty value: the challenge is spent, and a reload starts the sign-in over.
+  expect(lines.some((line) => line.startsWith(\`\${MFA_CHALLENGE_COOKIE}=;\`))).toBe(true);
+});
+`;
+
+export const destroySessionTest =
+  (): string => `// destroySession, run inside a real request over the app's migrated database: a live session is
+// revoked, and a caller with none still signs out — cleared, and landed at the home page.
+import { login, register } from '@ultimat3/auth';
+${SHARED_IMPORTS}
+import { destroySession } from './destroy-session';
+
+${DATABASE}
+
+const target = destroySession.named('destroySession');
+
+/** One sign-out POST carrying \`cookie\`, as the pipeline hands it to the action. */
+const signOut = async (accept: string, cookie?: string) => {
+${requestOf(
+  '/auth/sign-out',
+  '{ accept, ...(cookie === undefined ? {} : { cookie }) }',
+  "target({ confirm: 'sign-out' }, { ctx })",
+)}
+};
+
+unitTest('destroySession is a declared action off the MCP surface', () => {
+  expect(target.kind).toBe('action');
+  expect(target.describe().name).toBe('destroySession');
+});
+
+unitTest('it takes the one statement a sign-out form sends', async () => {
+  await expect(target.input).toAcceptInput({ confirm: 'sign-out' });
+  await expect(target.input).toRejectInput({});
+  await expect(target.input).toRejectInput({ confirm: 'yes' });
+});
+
+unitTest('a live session is revoked, and a second sign-out finds nothing to revoke', async () => {
+  const password = 'a long scaffold test passphrase';
+  await register(appAuth(), { email: 'leaving@example.com', password });
+  const { token } = await login(appAuth(), { email: 'leaving@example.com', password });
+  const cookie = \`\${appAuth().sessions.policy.cookieName}=\${token}\`;
+  const { output } = await signOut('application/json', cookie);
+  expect(output).toEqual({ ok: true, next: '/', revoked: true });
+  expect((await signOut('application/json', cookie)).output.revoked).toBe(false);
+});
+
+unitTest('with no session it still signs out, and a browser lands at the home page', async () => {
+  const { output, request } = await signOut('text/html');
+  expect(output).toEqual({ ok: true, next: '/', revoked: false });
+  expect(request.redirect).toEqual({ location: '/', status: 303 });
+  // The expired session cookie and the cleared browser state, whether or not a session existed.
+  const expired = \`\${appAuth().sessions.policy.cookieName}=;\`;
+  expect(request.headers.getSetCookie().some((line) => line.startsWith(expired))).toBe(true);
+  expect(request.headers.get('clear-site-data')).not.toBeNull();
+});
+`;

package/src/templates/sign-in-authenticator.ts

@@ -0,0 +1,112 @@
+// The authenticator once sign-in exists: a session cookie is its user and no session is nobody, in
+// every environment — `x new`'s development viewer (`dev-actor.ts`) and its fallback line are gone,
+// because a developer now signs in the way everyone does. `x g sign-in --oidc` swaps it in, and only
+// over the files `x new` wrote byte for byte: an author's edit is never overwritten.
+
+import type { GeneratedFile } from './naming';
+import { AUTH_DIR } from './sign-in-shared';
+
+const authenticatorSource =
+  (): string => `// Who a request is: the session its cookie names, resolved by \`@ultimat3/auth\` — the one
+// authenticator this app installs, in every environment. Everything downstream (pages, policies,
+// live subscribers, MCP tools) reads the actor this returns. With no session the request is
+// anonymous, everywhere: a developer signs in through \`/auth/sign-in\` like everyone else.
+import { type Auth, authenticate } from '@ultimat3/auth';
+import type { Actor } from '@ultimat3/core';
+import { configureAuthenticator } from '@ultimat3/http';
+import { appAuth } from './auth';
+
+/** The one method this reads off a request. */
+export interface SessionRequest {
+  cookie(name: string): string | null;
+}
+
+/**
+ * A session cookie is that session's user, or a refusal — never a fallback to anyone else:
+ * \`X_SESSION_EXPIRED\` past its expiry, \`X_UNAUTHENTICATED\` for one unknown, revoked or forged.
+ */
+export const sessionAuthenticator =
+  (auth: () => Auth) =>
+  async (request: SessionRequest): Promise<Actor | null> => {
+    const resolved = auth();
+    const token = request.cookie(resolved.sessions.policy.cookieName);
+    return token !== null && token.length > 0 ? await authenticate(resolved, token) : null;
+  };
+
+/** Installs the session authenticator. */
+export function installAuthenticator(auth: () => Auth = appAuth): void {
+  configureAuthenticator(sessionAuthenticator(auth));
+}
+
+// Module scope, which IS the wiring: the boot scan imports every module under \`apps/*\` before a
+// listener binds, and \`x dev\` and the container both read the configured value back at start.
+installAuthenticator();
+`;
+
+const authenticatorTest =
+  (): string => `// A session cookie is the user it was issued to; a bad one is refused; none is nobody.
+import { defineAuth, login, memoryAuthAdapter, register } from '@ultimat3/auth';
+import { configuredAuthenticator, resetAuthenticator } from '@ultimat3/http';
+import { expect, unitTest } from '@ultimat3/testing';
+import { DEMO_ORG_ID } from '../../shared/demo-org';
+import { installAuthenticator, sessionAuthenticator } from './authenticator';
+
+const memoryAuth = () => {
+  const auth = defineAuth({ adapter: memoryAuthAdapter() });
+  return () => auth;
+};
+
+const requestWith = (cookies: Readonly<Record<string, string>>) => ({
+  cookie: (name: string) => cookies[name] ?? null,
+});
+
+const PASSWORD = 'a long scaffold test passphrase';
+
+unitTest('a session cookie is the user it was issued to', async () => {
+  const auth = memoryAuth();
+  const user = await register(auth(), {
+    email: 'ada@example.com',
+    password: PASSWORD,
+    orgId: DEMO_ORG_ID,
+    roles: ['member'],
+  });
+  const { token } = await login(auth(), { email: 'ada@example.com', password: PASSWORD });
+  const actor = await sessionAuthenticator(auth)(
+    requestWith({ [auth().sessions.policy.cookieName]: token }),
+  );
+  expect(actor?.id).toBe(user.id);
+  expect(actor?.roles).toEqual(['member']);
+});
+
+unitTest('a forged cookie is refused, and no cookie is anonymous', async () => {
+  const auth = memoryAuth();
+  const forged = requestWith({ [auth().sessions.policy.cookieName]: 'forged.token' });
+  await expect(sessionAuthenticator(auth)(forged)).rejects.toMatchObject({
+    code: 'X_UNAUTHENTICATED',
+  });
+  expect(await sessionAuthenticator(auth)(requestWith({}))).toBeNull();
+});
+
+unitTest('it installs', () => {
+  try {
+    installAuthenticator(memoryAuth());
+    expect(configuredAuthenticator()).toBeDefined();
+  } finally {
+    resetAuthenticator();
+  }
+});
+`;
+
+/** The two files the swap writes over `x new`'s, when those are still `x new`'s. */
+export function signedInAuthenticatorFiles(): readonly GeneratedFile[] {
+  return [
+    { path: `${AUTH_DIR}/authenticator.ts`, contents: authenticatorSource() },
+    { path: `${AUTH_DIR}/authenticator.test.ts`, contents: authenticatorTest() },
+  ];
+}
+
+/** The development viewer the swap deletes, with the authenticator's fallback that asked it. */
+export const DEV_ACTOR_FILES: readonly string[] = [
+  `${AUTH_DIR}/dev-actor.ts`,
+  `${AUTH_DIR}/dev-actor.test.ts`,
+];