@ultimat3/cli 22.3.6 → 22.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.3.6",
+  "version": "22.5.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.3.6",
-    "@ultimat3/admin": "22.3.6",
-    "@ultimat3/ai": "22.3.6",
-    "@ultimat3/auth": "22.3.6",
-    "@ultimat3/cache": "22.3.6",
-    "@ultimat3/core": "22.3.6",
-    "@ultimat3/db": "22.3.6",
-    "@ultimat3/entity": "22.3.6",
-    "@ultimat3/flags": "22.3.6",
-    "@ultimat3/http": "22.3.6",
-    "@ultimat3/i18n": "22.3.6",
-    "@ultimat3/jobs": "22.3.6",
-    "@ultimat3/mail": "22.3.6",
-    "@ultimat3/manifest": "22.3.6",
-    "@ultimat3/mcp": "22.3.6",
-    "@ultimat3/money": "22.3.6",
-    "@ultimat3/notify": "22.3.6",
-    "@ultimat3/policy": "22.3.6",
-    "@ultimat3/pwa": "22.3.6",
-    "@ultimat3/query": "22.3.6",
-    "@ultimat3/realtime": "22.3.6",
-    "@ultimat3/render": "22.3.6",
-    "@ultimat3/schema": "22.3.6",
-    "@ultimat3/seo": "22.3.6",
-    "@ultimat3/storage": "22.3.6",
-    "@ultimat3/testing": "22.3.6",
-    "@ultimat3/time": "22.3.6",
+    "@ultimat3/action": "22.5.0",
+    "@ultimat3/admin": "22.5.0",
+    "@ultimat3/ai": "22.5.0",
+    "@ultimat3/auth": "22.5.0",
+    "@ultimat3/cache": "22.5.0",
+    "@ultimat3/core": "22.5.0",
+    "@ultimat3/db": "22.5.0",
+    "@ultimat3/entity": "22.5.0",
+    "@ultimat3/flags": "22.5.0",
+    "@ultimat3/http": "22.5.0",
+    "@ultimat3/i18n": "22.5.0",
+    "@ultimat3/jobs": "22.5.0",
+    "@ultimat3/mail": "22.5.0",
+    "@ultimat3/manifest": "22.5.0",
+    "@ultimat3/mcp": "22.5.0",
+    "@ultimat3/money": "22.5.0",
+    "@ultimat3/notify": "22.5.0",
+    "@ultimat3/policy": "22.5.0",
+    "@ultimat3/pwa": "22.5.0",
+    "@ultimat3/query": "22.5.0",
+    "@ultimat3/realtime": "22.5.0",
+    "@ultimat3/render": "22.5.0",
+    "@ultimat3/schema": "22.5.0",
+    "@ultimat3/seo": "22.5.0",
+    "@ultimat3/storage": "22.5.0",
+    "@ultimat3/testing": "22.5.0",
+    "@ultimat3/time": "22.5.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-dev-fixture.ts

@@ -6,7 +6,7 @@
 // What the app declares, and what each declaration is here to prove:
 //   app.config.ts               the root marker a real `x dev` cannot start without; `ai.mcp` by default
 //   apps/web/mcp.ts             the app's own MCP endpoint, mounted by the web role
-//   apps/web/runtime.ts         the app's middleware, reaching a development process
+//   apps/web/runtime.ts         the app's middleware and disks, reaching a development process
 //   .git/HEAD                   the fixture is its own repository — see the entry below
 //   apps/web/app/hello/*        an SSR page with a component, edited on disk while `x dev` runs
 //   apps/web/app/notes/*        a memory-backed entity and a live query, fed by the in-process bridge
@@ -46,13 +46,19 @@ export const mcp = defineAppMcp({ include: 'exposed', resolveToken: () => null }
 
   // The app's own middleware, in the contract `app-runtime.ts` reads: a header on every response
   // is the cheapest proof that the chain `x dev` composed is the app's and not only the replica's.
-  'apps/web/runtime.ts': `const stamp = async (request, ctx, next) => {
+  // Its disks too: `x dev` built its own embedded disk and ignored this one until 22.4.
+  'apps/web/runtime.ts': `import { defineStorage, localDriver } from '@ultimat3/storage';
+const stamp = async (request, ctx, next) => {
   const response = await next(request, ctx);
   const headers = new Headers(response.headers);
   headers.set('x-dev-runtime', 'app');
   return new Response(response.body, { status: response.status, headers });
 };
-export const runtime = { middleware: [stamp] };
+const storage = defineStorage({
+  disks: { appdisk: localDriver({ root: new URL('../../.app-disk', import.meta.url).pathname }) },
+  default: 'appdisk',
+});
+export const runtime = { middleware: [stamp], storage };
 `,
 
   // A memory-backed entity, so the fixture needs no migration: the row observer sits on

package/src/cmd-dev.ts

@@ -47,6 +47,7 @@ import {
   withRealtimeEvents,
 } from './runtime-bindings';
 import { liveFeedLabel } from './runtime-live-feed';
+import type { RuntimeOverrides } from './runtime-overrides';
 import { replicaOverrides } from './runtime-replica';
 import type { RunningServices } from './runtime-services';
 import { cdnLabel, describeCdn, describeMail, mailLabel, startServices } from './runtime-services';
@@ -133,14 +134,20 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     ? { ...options.env, ULTIMATE_ENV: 'development' }
     : options.env;
   const resolved = resolveServices(options.root, env);
-  const runtime: RunningServices = await startServices(resolved, env);
+  // The app's `apps/<app>/runtime.ts`, read ONCE and handed to `startServices` exactly as
+  // `serve.ts`'s `withAppRuntime` does — so the disks (`storage`), the queue, the mail driver and
+  // every other override a deployment declares are the ones development runs too. Until 22.4 this
+  // boot passed nothing here and built its own embedded disk, so an app's `/_storage` routes and its
+  // actions wrote to two different places in `x dev` and to one in production.
+  const appRuntime = await loadAppRuntime(options.root);
+  const runtime: RunningServices = await startServices(resolved, env, appRuntime);
   // The events binding the boot line reports is the bus the runtime chose, read off it.
   const services = withRealtimeEvents(resolved, env, runtime.realtime);
   // `serve.ts`'s `releaseBoot` shape: everything acquired from here on is released, newest first,
   // if the boot throws — a failed `x dev` left PGlite holding `.x/pgdata` for the retry to meet.
   const acquired: (() => void | Promise<void>)[] = [() => runtime.stop()];
   try {
-    return await bootDev(options, services, runtime, acquired);
+    return await bootDev(options, services, runtime, acquired, appRuntime);
   } catch (error) {
     await releaseBoot(acquired);
     throw error;
@@ -152,6 +159,7 @@ async function bootDev(
   services: ReturnType<typeof resolveServices>,
   runtime: RunningServices,
   acquired: (() => void | Promise<void>)[],
+  appRuntime: RuntimeOverrides | undefined,
 ): Promise<DevServer> {
   // Installed before the app loads, so a span opened during registration is already recorded.
   // Tracing is always on in the framework and free until an exporter is configured; `x dev` is
@@ -229,11 +237,7 @@ async function bootDev(
   // The app's `apps/<app>/runtime.ts`, composed exactly as `runRole` composes a caller's
   // `runtime`: the replica scope in front, the app's own middleware behind it. Before this the
   // first argument was `undefined` here and an app's middleware reached no development process.
-  const replicaOverride = replicaOverrides(
-    await loadAppRuntime(options.root),
-    services.db,
-    options.env,
-  );
+  const replicaOverride = replicaOverrides(appRuntime, services.db, options.env);
   const running = await startRoles({
     roles: options.roles ?? DEV_ROLES,
     port: options.port,

package/src/generate-kinds.ts

@@ -114,11 +114,35 @@ export function readName(raw: string | undefined, kind: Generator): string {
       example: exampleFor(kind),
     });
   }
+  // A route's name IS its URL: `x g route casos/[id]/notificar` writes the page under the
+  // directory that serves it. Every other generator's name is one directory segment.
+  if (kind === 'route') return readRoutePath(raw);
   refusePath(raw, 'name', kind);
   refuseBadIdentifier(raw, kind);
   return raw;
 }
 
+/** A static segment, or `[param]` / `[...rest]` — the directory convention `x routes` reads. */
+const ROUTE_SEGMENT = /^(?:[A-Za-z0-9][A-Za-z0-9_-]*|\[(?:\.\.\.)?[A-Za-z][A-Za-z0-9_-]*\])$/;
+
+/**
+ * `x g route` refused any path until 22.4, so a nested or dynamic page (`casos/[id]/notificar`)
+ * had to be generated flat and moved by hand — and the move is where the generated test's URL and
+ * the directory stopped agreeing. Each segment is checked on its own, which is also the traversal
+ * guard: `..`, `.`, an empty segment and a backslash are not segments this pattern admits.
+ */
+function readRoutePath(raw: string): string {
+  const segments = raw.replace(/^\/+/, '').split('/');
+  const bad = segments.find((segment) => !ROUTE_SEGMENT.test(segment));
+  if (bad === undefined) return raw.replace(/^\/+/, '');
+  throw new BadFlagError({
+    flag: 'name',
+    command: 'g route',
+    reason: `"${raw}" has the segment "${bad}", and a route segment is a word (a-z, 0-9, -, _) or [param] / [...rest]`,
+    fix: 'x g route posts/[slug] --surface site',
+  });
+}
+
 /** `--feature`, refused where it is a path: it is a DIRECTORY under the surface, one segment. */
 export function readFeature(raw: string | undefined, kind: Generator): string | undefined {
   if (raw !== undefined) refusePath(raw, 'feature', kind);

package/src/pwa-artifacts.ts

@@ -32,12 +32,15 @@ import {
   renderThemeColorMeta,
   serializeWebManifest,
 } from '@ultimat3/pwa';
+import type { AssetPath } from '@ultimat3/render';
+import { assetPathProblem } from '@ultimat3/render';
 import { escapeAttribute } from '@ultimat3/seo';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
 import { hasSourceIcon, iconPlan, iconRenderer } from './icon-assets';
 import type { AppLocales } from './pwa-manifest-locales';
 import { appLocales, localeMembers, spellIn } from './pwa-manifest-locales';
+import { parseHashedAssetUrl, siteAssetTable } from './site-assets';
 
 /** What a browser fetches from `<link rel="manifest">`. The spec's own extension, not `.json`. */
 export const WEB_MANIFEST_PATH = '/manifest.webmanifest';
@@ -208,7 +211,7 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
       name: app.name,
       tokens: app.colors,
       icons: icons?.manifestIcons ?? [],
-      ...localeMembers(app.block, locale, app.locales),
+      ...withHashedAssets(localeMembers(app.block, locale, app.locales), root),
     });
     const path = spellIn(WEB_MANIFEST_PATH, locale, app.locales);
     return {
@@ -235,6 +238,41 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
   };
 }
 
+/**
+ * A screenshot or shortcut icon written as the asset it is — `assets/pwa/wide.png` or
+ * `/assets/pwa/wide.png` — answers the content-hashed URL the site actually serves, exactly as
+ * `asset()` does in a page. The site serves an asset ONLY at its hashed URL, and the manifest took
+ * `src` verbatim, so an app had to hash its own screenshots to avoid shipping a 404 in the install
+ * sheet (notificado.co's `pwa-install.ts`). A missing file is `X_ASSET_MISSING` at boot, never a
+ * broken image in an install prompt; any other `src` (absolute, already hashed) passes untouched.
+ */
+function withHashedAssets<M extends ReturnType<typeof localeMembers>>(members: M, root: string): M {
+  const resolve = (src: string): string => {
+    const path = src.replace(/^\//, '');
+    if (!path.startsWith('assets/') || parseHashedAssetUrl(`/${path}`) !== undefined) return src;
+    if (assetPathProblem(path) !== undefined) return src;
+    return siteAssetTable(root).resolve(path as AssetPath).url;
+  };
+  return {
+    ...members,
+    ...(members.screenshots === undefined
+      ? {}
+      : { screenshots: members.screenshots.map((shot) => ({ ...shot, src: resolve(shot.src) })) }),
+    ...(members.shortcuts === undefined
+      ? {}
+      : {
+          shortcuts: members.shortcuts.map((shortcut) =>
+            shortcut.icons === undefined
+              ? shortcut
+              : {
+                  ...shortcut,
+                  icons: shortcut.icons.map((icon) => ({ ...icon, src: resolve(icon.src) })),
+                },
+          ),
+        }),
+  };
+}
+
 /** The manifest `locale` names, by URL segment (`es-CO` is `es-co`), if the app routes it. */
 const manifestIn = (
   manifests: readonly LocalizedManifest[],

package/src/serve-boot.ts

@@ -4,6 +4,7 @@
 // — are this file's.
 
 import type { Role } from '@ultimat3/core';
+import { configureLifecycle } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
 import { describeRoutes } from '@ultimat3/render';
 import { createIsrController } from '@ultimat3/render/server';
@@ -26,7 +27,7 @@ import { replicaOverrides } from './runtime-replica';
 import type { RunningServices } from './runtime-services';
 import { servedStorage, storageRoutes } from './runtime-storage';
 import { seoRoutes } from './seo-routes';
-import { loadDrainConfig } from './serve-drain';
+import { loadDrainConfig, loadHealthConfig } from './serve-drain';
 import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
 import type { ServedApp, ServeOptions } from './serve-types';
 import { loadSiteSettings, publicOrigin } from './site-config';
@@ -77,6 +78,9 @@ export async function bootRoles(boot: {
   // still wins — that is the deploy talking.
   const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
   const drain = await loadDrainConfig(options.root);
+  // Process-wide, so every role's `/readyz` — web, sync, worker — answers in the declared mode.
+  const health = await loadHealthConfig(options.root);
+  if (health?.readiness !== undefined) configureLifecycle({ readiness: health.readiness });
   const replicaOverride = replicaOverrides(options.runtime, runtime.services.db, options.env);
   const running = await startRoles({
     roles: [role],

package/src/serve-drain.ts

@@ -1,7 +1,8 @@
-// `app.config.ts`'s `drain` section, read for the production boot — the same import every other
-// config reader here makes (`theme-boot.ts`, `app-auth.ts`), because the config is a module.
+// `app.config.ts`'s `drain` and `health` sections, read for the production boot — the same import
+// every other config reader here makes (`theme-boot.ts`, `app-auth.ts`), because the config is a
+// module. Both shape what `/readyz` tells the load balancer.
 
-import type { DrainConfig } from '@ultimat3/core';
+import type { DrainConfig, HealthConfig } from '@ultimat3/core';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
 
@@ -22,3 +23,19 @@ export async function loadDrainConfig(root: string): Promise<Partial<DrainConfig
   if (!isRecord(drain) || !Object.hasOwn(drain, 'readinessGraceMs')) return undefined;
   return { readinessGraceMs: drain['readinessGraceMs'] as number };
 }
+
+/**
+ * `health.readiness`, or `undefined` when the app declares none (core keeps `'dependencies'`). The
+ * value is handed to `configureLifecycle` as written, so a bad one is refused by core's own rule.
+ */
+export async function loadHealthConfig(root: string): Promise<Partial<HealthConfig> | undefined> {
+  const path = `${root}/${APP_CONFIG_FILE}`;
+  if (!(await Bun.file(path).exists())) return undefined;
+  const module = (await import(path)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  const health = isRecord(config)
+    ? (config['health'] as Partial<HealthConfig> | undefined)
+    : undefined;
+  if (!isRecord(health) || health.readiness === undefined) return undefined;
+  return { readiness: health.readiness };
+}