@ultimat3/cli 1.1.0 → 2.0.0

package/src/templates/scaffold-domain-package.ts

@@ -0,0 +1,90 @@
+// The generated app's `packages/domain`: the pure types and constants every other package reads,
+// with no I/O of any kind. Split out of scaffold-repo.ts, which was over the file-size ceiling —
+// one file per generated workspace package, the seam `scaffold-i18n.ts` already draws.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
+import { wrapImport } from './wrap';
+
+const DESCRIPTION = 'Pure types and constants, no I/O';
+
+/** `X_MYAPP_CURRENCY_MISMATCH` — the app's own namespace, so it can never collide with a framework
+ * code and `x errors explain` can tell whose it is. */
+const currencyCode = (app: NameSet): string =>
+  `X_${app.kebab.toUpperCase().split('-').join('_')}_CURRENCY_MISMATCH`;
+
+const domainIndex = (
+  app: NameSet,
+): string => `// Pure types and constants. No I/O of any kind: no fs, no network, no database, no env reads.
+// \`Money\` is @ultimat3/schema's, re-exported and never restated: one declaration of
+// { minor, currency } is what makes an entity column, a form field and this module the same type.
+import { UltimateError } from '@ultimat3/core';
+import type { MoneyValue as Money } from '@ultimat3/schema';
+
+export type { MoneyValue as Money } from '@ultimat3/schema';
+
+export const ROLES = ['owner', 'member', 'viewer'] as const;
+
+export type Role = (typeof ROLES)[number];
+
+/**
+ * Never a bare Error: an agent reading the failure needs the code, the cause and the exact command
+ * that resolves it. Adding across currencies is a bug in the caller's data, not a runtime hiccup,
+ * so the fix names the conversion that has to happen first.
+ */
+export class ${app.pascal}CurrencyMismatchError extends UltimateError {
+  constructor(input: { readonly left: string; readonly right: string }) {
+    super({
+      code: '${currencyCode(app)}',
+      cause: \`cannot add \${input.left} to \${input.right}: Money is only additive inside one currency\`,
+      fix: \`bun test packages/domain/src/index.test.ts   # add() is defined only inside one currency — convert \${input.right} to \${input.left} before calling it\`,
+      docs: 'https://ultimate.dev/errors/${currencyCode(app)}',
+    });
+  }
+}
+
+export const zero = (currency: string): Money => ({ minor: 0, currency });
+
+export const add = (a: Money, b: Money): Money => {
+  if (a.currency !== b.currency) {
+    throw new ${app.pascal}CurrencyMismatchError({ left: a.currency, right: b.currency });
+  }
+  return { minor: a.minor + b.minor, currency: a.currency };
+};
+`;
+
+const domainTest = (
+  app: NameSet,
+): string => `// Money arithmetic in minor units, and the currency mismatch that must throw rather than round.
+// A float here is a rounding error nobody sees until it is on an invoice.
+import { expect } from 'bun:test';
+import { unitTest } from '@ultimat3/testing';
+${wrapImport(['add', `${app.pascal}CurrencyMismatchError`, 'zero'], './index')}
+
+unitTest('money adds in minor units', () => {
+  expect(add({ minor: 1050, currency: 'USD' }, { minor: 250, currency: 'USD' })).toEqual({
+    minor: 1300,
+    currency: 'USD',
+  });
+});
+
+unitTest('money refuses to add across currencies, with a code and a fix', () => {
+  expect(() => add(zero('USD'), zero('EUR'))).toThrow(${app.pascal}CurrencyMismatchError);
+  try {
+    add(zero('USD'), zero('EUR'));
+  } catch (error) {
+    expect(error).toBeUltimateError('${currencyCode(app)}');
+  }
+});
+`;
+
+/** Every file the `packages/domain` workspace ships, in the order `x new` writes them. */
+export const domainPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
+  {
+    path: 'packages/domain/package.json',
+    contents: workspacePackageJson(app, 'domain', DESCRIPTION),
+  },
+  ...packageShapeFiles(app, 'domain', DESCRIPTION),
+  { path: 'packages/domain/src/index.ts', contents: domainIndex(app) },
+  { path: 'packages/domain/src/index.test.ts', contents: domainTest(app) },
+];

package/src/templates/scaffold-env.ts

@@ -0,0 +1,87 @@
+// The scaffolded app's environment, declared ONCE as a real `EnvSchema` and projected twice: into
+// the `envSchema` export of `app.config.ts`, and into the `.env.example` committed beside it. A
+// hand-written example file would be a second list of variable names, and `x new` would ship an
+// app whose own `x verify` fails on the drift the framework exists to prevent.
+
+import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
+import { renderEnvExample } from '@ultimat3/core';
+
+/**
+ * Committed defaults only, so a fresh clone boots with `x dev` and no scavenger hunt. Every
+ * description stays under ~80 characters: the serializer below indents them four spaces inside a
+ * template Biome then checks at 100 columns, and a reflowed line is a failing `x verify` on file
+ * one of a brand-new app.
+ */
+export const SCAFFOLD_ENV_SCHEMA = {
+  DATABASE_URL: {
+    type: 'url',
+    required: false,
+    description: 'Postgres URL. Empty means embedded: x dev runs PGlite in-process.',
+  },
+  PORT: {
+    type: 'port',
+    default: 3000,
+    description: 'HTTP port this role binds. Every PaaS injects it.',
+  },
+  NATS_URL: {
+    type: 'url',
+    required: false,
+    role: 'sync',
+    description: 'Realtime fan-out cluster. Only the sync role is asked for it.',
+  },
+  SESSION_SECRET: {
+    type: 'string',
+    required: false,
+    secret: true,
+    description: 'Session cookie signing key. Generate: openssl rand -hex 32',
+  },
+} satisfies EnvSchema;
+
+const quoted = (value: string): string => `'${value.replaceAll("'", "\\'")}'`;
+
+/**
+ * The value kinds an `EnvVarDecl` field can hold in a scaffold: a string, a number, a boolean, or
+ * the string list `enum`'s `values` and a multi-role `role` use. `RegExp` (`pattern`) is
+ * deliberately not one — its source would need re-escaping into a literal, and the scaffold has no
+ * use for it. An unrenderable value is dropped rather than guessed at, so the projection stays
+ * total and `envSchemaSource` can never emit `[object Object]` into a generated app.
+ */
+const literal = (value: unknown): string | undefined => {
+  if (typeof value === 'string') return quoted(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value) && value.every((entry) => typeof entry === 'string')) {
+    return `[${value.map(quoted).join(', ')}]`;
+  }
+  return undefined;
+};
+
+/**
+ * The declaration as Biome-clean TypeScript. Always multi-line — Biome, like Prettier, keeps an
+ * object expanded when the source has a newline after its `{`, so the emitted text is a fixed
+ * point of the formatter and `x new` → `x verify` never fails on its own scaffold's layout.
+ */
+export function envSchemaSource(schema: EnvSchema = SCAFFOLD_ENV_SCHEMA): string {
+  // Biome prints an empty object inline no matter what the source did, so the empty case is
+  // emitted the way the formatter would rewrite it — otherwise the scaffold's own `lint` step
+  // would fail on a file the scaffold wrote.
+  if (Object.keys(schema).length === 0) return 'export const envSchema = {} satisfies EnvSchema;';
+  const lines = ['export const envSchema = {'];
+  for (const [key, decl] of Object.entries(schema)) {
+    lines.push(`  ${key}: {`);
+    for (const [prop, value] of Object.entries(decl)) {
+      const rendered = literal(value);
+      if (rendered !== undefined) lines.push(`    ${prop}: ${rendered},`);
+    }
+    lines.push('  },');
+  }
+  lines.push('} satisfies EnvSchema;');
+  return lines.join('\n');
+}
+
+/** Byte-identical to what `x env example` writes, because both call core's one renderer. */
+export const envExampleSource = (schema: EnvSchema = SCAFFOLD_ENV_SCHEMA): string =>
+  renderEnvExample(schema);
+
+/** Named so a reader of `repoFiles` can see the two projections come from one declaration. */
+export const scaffoldEnvVarNames = (): readonly string[] =>
+  Object.keys(SCAFFOLD_ENV_SCHEMA as Readonly<Record<string, EnvVarDecl>>);

package/src/templates/scaffold-i18n.ts

@@ -110,7 +110,10 @@ const i18nCatalog = (app: NameSet): string =>
     'admin.home.description': `Operations for ${app.pascal}.`,
   });
 
-const i18nTest = (): string => `import { expect } from 'bun:test';
+const i18nTest =
+  (): string => `// Every locale carries the same keys as the default one. A key present in en and missing in fr
+// renders \u27e6key\u27e7 to a user, and nothing else in the app can notice.
+import { expect } from 'bun:test';
 import { unitTest } from '@ultimat3/testing';
 import { catalogs } from './index';
 

package/src/templates/scaffold-mcp-package.ts

@@ -0,0 +1,49 @@
+// The generated app's `packages/mcp`: the app's own MCP surface, projected straight from the
+// action registry rather than re-listed, plus the test that pins every projected tool describing
+// itself.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
+
+const DESCRIPTION = "The app's own MCP tools";
+
+const mcpIndex = (
+  app: NameSet,
+): string => `// The app's own MCP tools. Every action with mcp.expose is already a tool; add app-specific
+// read-only helpers here. Authorization is the action's policy, unchanged.
+import * as api from '@${app.kebab}/web/api/health';
+import { registerActions } from '@ultimat3/action';
+import { defineAppMcp } from '@ultimat3/mcp';
+
+// Names come from export names, so the registry agrees with the module the app already wrote.
+registerActions(api);
+
+// \`include: 'exposed'\` projects straight from the registry. Re-listing the actions here would
+// copy \`mcp: { expose: true }\` into a second place, and the copy goes stale in silence.
+export const mcp = defineAppMcp({
+  name: '${app.kebab}',
+  include: 'exposed',
+});
+`;
+
+const mcpTest =
+  (): string => `// The app exposes its actions as MCP tools, and each tool carries the action's own policy. An
+// agent reaching a tool that authorises differently is the failure this rules out.
+import { expect, unitTest } from '@ultimat3/testing';
+import { mcp } from './index';
+
+unitTest('the app exposes its actions as MCP tools', () => {
+  expect(mcp.tools.length).toBeGreaterThan(0);
+  // Every projected tool must describe itself: an agent picks a tool by its description. Assert
+  // on the value, not its length — a failure then prints the empty description, not "0 > 0".
+  for (const tool of mcp.tools) expect(tool.description).not.toBe('');
+});
+`;
+
+/** Every file the `packages/mcp` workspace ships, in the order `x new` writes them. */
+export const mcpPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: 'packages/mcp/package.json', contents: workspacePackageJson(app, 'mcp', DESCRIPTION) },
+  ...packageShapeFiles(app, 'mcp', DESCRIPTION),
+  { path: 'packages/mcp/src/index.ts', contents: mcpIndex(app) },
+  { path: 'packages/mcp/src/index.test.ts', contents: mcpTest() },
+];

package/src/templates/scaffold-package-shape.ts

@@ -1,7 +1,7 @@
-// The three contract files `x verify`'s `package-shape` step requires of every `packages/*` dir —
-// enforced on a generated app exactly like it is on this repo, so `x new` has to ship them itself
-// rather than leave the app's very first gate run red. Split out of scaffold-repo.ts to stay under
-// the file-size ceiling; every `packages/*` entry there calls `packageShapeFiles` once.
+// The manifest, plus the three contract files `x verify`'s `package-shape` step requires of every
+// `packages/*` dir — enforced on a generated app exactly like it is on this repo, so `x new` has
+// to ship them itself rather than leave the app's very first gate run red. Every scaffolded
+// workspace package calls both exports here exactly once.
 
 import type { GeneratedFile, NameSet } from './naming';
 
@@ -47,3 +47,24 @@ export const packageShapeFiles = (
   { path: `packages/${name}/CLAUDE.md`, contents: packageClaude(app, name, description) },
   { path: `packages/${name}/tsconfig.json`, contents: packageTsconfig(includes) },
 ];
+
+/**
+ * The manifest every scaffolded `packages/*` carries. Private, versionless-by-convention and
+ * dependency-free: these packages only re-export a framework package's types, so the one that does
+ * name a dependency writes its own (`scaffold-i18n.ts`, and it says why). Lives beside
+ * `packageShapeFiles` because every caller of one calls the other.
+ */
+export const workspacePackageJson = (app: NameSet, name: string, description: string): string => `{
+  "name": "@${app.kebab}/${name}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "${description}",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
+  }
+}
+`;