@ultimat3/cli 24.0.0 → 25.0.0

package/src/i18n-registration.ts

@@ -18,12 +18,13 @@ import {
   pluralVariantsOf,
   registeredLocales,
 } from '@ultimat3/i18n';
+import { APP_CATALOGS_PATH } from '@ultimat3/i18n/app-catalogs';
 import { mountedAdminKeys } from './admin-catalog-keys';
+import type { LoadedApp } from './app-load';
 import { loadApp } from './app-load';
 import type { DuplicateProbe } from './duplicate-packages';
 import { duplicateCause, duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
 import { auditApp } from './i18n-audit';
-import { I18N_INDEX_PATH } from './i18n-index';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { CATALOG_ROOT, catalogPath } from './templates/locales';
@@ -37,10 +38,7 @@ const I18N_PKG = '@ultimat3/i18n';
  * can resolve `@ultimat3/*`. `loadApp` is the production value, and it is the same call
  * `serveApp` makes: asking a different loader than the server uses would prove nothing.
  */
-export type AppLoader = (root: string) => Promise<{
-  readonly findings: readonly Finding[];
-  readonly defaultLocale: string;
-}>;
+export type AppLoader = (root: string) => Promise<Pick<LoadedApp, 'findings' | 'locales'>>;
 
 export interface RegistrationInput {
   readonly root: string;
@@ -121,9 +119,9 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
   let locales = gaps.length;
 
   if (Object.keys(input.catalogs).length === 0) {
-    const unresolved = unresolvedUsedKeys(input, app.defaultLocale);
+    const unresolved = unresolvedUsedKeys(input, app.locales.defaultLocale);
     if (unresolved.length > 0) {
-      findings.push(findingFrom(catalogsNeverRegistered(app.defaultLocale, unresolved)));
+      findings.push(findingFrom(catalogsNeverRegistered(app.locales.defaultLocale, unresolved)));
       unregistered += unresolved.length;
       locales += 1;
     }
@@ -182,7 +180,7 @@ function adminKeysFinding(locale: Locale, missing: readonly string[]): Finding {
  * the half that knows what an app's directories are.
  */
 async function indexSource(root: string): Promise<string | undefined> {
-  const file = Bun.file(join(root, I18N_INDEX_PATH));
+  const file = Bun.file(join(root, APP_CATALOGS_PATH));
   return (await file.exists()) ? file.text() : undefined;
 }
 
@@ -208,7 +206,7 @@ export function unregisteredFix(
   // report a registered locale as unregistered, which is the direction that costs trust.
   if (index.includes(`${CATALOG_ROOT.split('/').pop() ?? 'catalogs'}/${locale}.json`)) return {};
   return {
-    fix: `x i18n sync ${locale}   # re-derives ${I18N_INDEX_PATH} from the catalogs on disk`,
+    fix: `x i18n sync ${locale}   # re-derives ${APP_CATALOGS_PATH} from the catalogs on disk`,
   };
 }
 

package/src/import-scan.ts

@@ -42,12 +42,36 @@ export function scanRuntimeImports(file: ScannedFile): readonly string[] {
     .map((entry) => entry.path);
 }
 
+/**
+ * A type-position `import('…')` — `typeof import('@ultimat3/cli')`, `let x: import('a').B` — is no
+ * import statement, so the transpiler erases it whole and neither pass above sees it (K16: the tier
+ * rule passed one). Read off `masked`, the source with comments and string CONTENTS blanked and
+ * delimiters kept (`@ultimat3/core`'s `maskLiterals`): a match there is code, and the specifier is
+ * read back from `source` at the same offsets. Taken as an argument because this file is a leaf.
+ * A dynamic `import(x)` is reported too, which the runtime pass already holds — callers dedupe.
+ */
+const IMPORT_CALL = /(?<![\w$.])import\s*\(\s*(['"])/g;
+
+export function typePositionImports(source: string, masked: string): readonly string[] {
+  const found: string[] = [];
+  for (const match of masked.matchAll(IMPORT_CALL)) {
+    const quote = match[1] as string;
+    const open = match.index + match[0].length;
+    const close = masked.indexOf(quote, open);
+    if (close === -1) continue;
+    const specifier = source.slice(open, close);
+    if (specifier !== '' && !specifier.includes('\n')) found.push(specifier);
+  }
+  return found;
+}
+
 /**
  * Every specifier the file names, type-only ones included. Throws when the file does not parse —
  * a scan that answered `[]` there would read as a file importing nothing. The rewrite pass alone
- * is forgiving: a rewrite the parser refuses falls back to the runtime scan.
+ * is forgiving: a rewrite the parser refuses falls back to the runtime scan. Hand it `masked`
+ * (core's `maskLiterals(file.source)`) and a type-position `import('…')` is read as well.
  */
-export function scanAllImports(file: ScannedFile): readonly string[] {
+export function scanAllImports(file: ScannedFile, masked?: string): readonly string[] {
   const runtime = scanRuntimeImports(file);
   let typed: readonly string[] = [];
   try {
@@ -58,6 +82,7 @@ export function scanAllImports(file: ScannedFile): readonly string[] {
   } catch {
     typed = [];
   }
+  const inTypes = masked === undefined ? [] : typePositionImports(file.source, masked);
   // The rewritten pass first: it holds every import in SOURCE order, which callers report in.
-  return [...new Set([...typed, ...runtime])];
+  return [...new Set([...typed, ...inTypes, ...runtime])];
 }

package/src/index.ts

@@ -115,7 +115,6 @@ export { ICON_BASE_PATH, ICON_SOURCE } from './icon-assets';
 // `x build`'s and `x dev`'s wiring, and every name here is a semver promise forever.
 export type { IslandChunk, SharedChunk } from './island-bundle';
 export { buildIslands } from './island-bundle';
-export { JOB_STATES } from './jobs-report';
 export { renderJobTable } from './jobs-table';
 export { msg } from './messages';
 export { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
@@ -123,7 +122,7 @@ export { parseMigrationSql, readMigrations } from './migrations';
 export type { CommandResult, Finding, JsonValue } from './output';
 export { exitCodeFor, findingFrom, render, renderFinding, renderHuman } from './output';
 export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
-export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
+export { flagBool, flagList, flagString, GLOBAL_FLAGS, parseArgs } from './parse';
 export type { PrerenderedPage, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export type { PwaArtifacts } from './pwa-artifacts';
@@ -169,7 +168,6 @@ export { readVerifyFloor, skippedSuiteFinding, VERIFY_FLOOR_FILE } from './verif
 export type { HostCheck, StepOutcome, VerifyStep, VerifyStepName } from './verify-step';
 export { VERIFY_STEP_NAMES } from './verify-step';
 export type { TestType } from './verify-tests';
-export { TEST_TYPES } from './verify-tests';
 export {
   checkFileSizes,
   checkLockstep,

package/src/island-bundle.ts

@@ -15,25 +15,32 @@
 // `globalThis` object created lazily by the first transport call or realtime hook. Measured before
 // that decision on `examples/dummy`, a core-importing wrapper cost contact-sales 875 → 8,827 B.
 // What IS prepended is the realtime install, and only where the island's graph reaches
-// `@ultimat3/realtime` (`island-realtime.ts`). Measured on a fixture, As of 2026-09-22: a Solid
-// island reading `useConnection` 64,964 → 65,067 B (+103 B); an island not reaching realtime +0.
+// `@ultimat3/realtime` (`island-realtime.ts`); the page runtime it awaits is ONE more output,
+// `page-runtime.<identity>.js` beside the entries (`island-runtime.ts`), never inlined into one (#505).
 
 // Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
 // POSIX by construction), `join`/`basename` the filesystem side.
 import { basename, join, posix, relative, sep } from 'node:path';
-import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
+import { ISLAND_EXTENSION, islandModuleId } from '@ultimat3/render';
 import { loadAppConfig } from './app-config-load';
 import { IslandBuildFailedError } from './errors';
+import { refuseDuplicatedModules } from './island-duplicate-refusal';
+import { entryMissing, onlyMissing } from './island-entry-missing';
 import { describeBuildError, sourcesContentOf, stableChunk, stripDebugId } from './island-identity';
 import type { BuiltOutput, LinkedFile } from './island-link';
 import { linkOutputs, sharedChunkName } from './island-link';
+import { frameworkDedupePlugins } from './island-package-dedupe';
 import {
   islandRealtimePlugin,
   REALTIME_ISLAND_ENTRY,
   reachesRealtime,
   realtimeIslandEntry,
 } from './island-realtime';
+import type { Runtimes } from './island-runtime';
+import { loadingRuntime, mergeBuilds, runtimeBuilder, runtimeShared } from './island-runtime';
 import { solidDedupePlugin } from './island-solid-dedupe';
+import type { SourcePaths } from './island-sources';
+import { sourcesOnDisk } from './island-sources';
 import { islandStylesPlugin } from './island-styles';
 import { hasPathSegment } from './path-segments';
 import { solidJsxPlugin } from './solid-loader';
@@ -70,6 +77,8 @@ export interface IslandChunk {
    * beyond `bytes`, what a precached page must carry with it. Empty for an island sharing nothing.
    */
   readonly imports: readonly string[];
+  /** The files on disk it was built from (`island-sources.ts`). Absent on a chunk not built here. */
+  readonly sources?: SourcePaths;
 }
 
 /** A module two or more islands import, served once beside them. */
@@ -80,6 +89,7 @@ export interface SharedChunk {
   readonly bytes: number;
   /** The islands (app-root-relative) that load it — for a finding that names what an author edits. */
   readonly importers: readonly string[];
+  readonly sources?: SourcePaths;
 }
 
 export interface IslandBundle {
@@ -119,6 +129,7 @@ async function buildAll(
   root: string,
   files: readonly string[],
   splitting: boolean,
+  runtimes: Runtimes,
 ): Promise<{ readonly chunks: readonly IslandChunk[]; readonly shared: readonly SharedChunk[] }> {
   if (files.length === 0) return { chunks: [], shared: [] };
   // Inside the refusal: the realtime probe PARSES the island's graph, and a file that will not
@@ -134,6 +145,7 @@ async function buildAll(
   // Only an island whose own graph reaches `@ultimat3/realtime` is wrapped (`island-realtime.ts`);
   // every other one is built from its own file, byte for byte what it was.
   const live = files.filter((_, index) => realtime[index] === true);
+  const runtime = live[0] === undefined ? undefined : await runtimes(live[0]);
   const entrypoints = files.map((file, index) =>
     realtime[index] === true ? realtimeIslandEntry(file) : join(root, file),
   );
@@ -161,10 +173,13 @@ async function buildAll(
       //
       // The dedupe goes FIRST: it answers `solid-js` specifiers before either plugin loads a file,
       // so the `solid-js/web` helpers the JSX transform writes into a symlinked package resolve
-      // to the app's one copy. See `island-solid-dedupe.ts` for the measurement.
+      // to the app's one copy. See `island-solid-dedupe.ts` for the measurement. `@ultimat3/*`
+      // gets the same rule (`island-package-dedupe.ts`): a nested copy is a second module where no
+      // symlink folds it, which is every `file:` install on Windows.
       plugins: [
-        ...(live[0] === undefined ? [] : [islandRealtimePlugin(root, live[0])]),
+        ...(runtime === undefined ? [] : [islandRealtimePlugin(root, runtime)]),
         solidDedupePlugin(root),
+        ...frameworkDedupePlugins(root),
         solidJsxPlugin,
         islandStylesPlugin,
       ],
@@ -187,9 +202,13 @@ async function buildAll(
       // output has. See `graphHash`. Measured on 1.4.0 against a 131 kB island: 277ms with it and
       // 276ms without, so the map costs nothing worth naming.
       sourcemap: 'external',
+      // The fifth: which inputs each output carries, so one module bundled twice is refused below
+      // rather than shipped (`island-duplicates.ts`). Measured on 1.4.2 against examples/dummy's
+      // feed island, five interleaved builds each way: 44 ms without, 48 ms with, noise-level.
+      metafile: true,
     });
   } catch (error) {
-    throw await blame(root, files, error, splitting);
+    throw await blame(root, files, error, splitting, runtimes);
   }
   if (!built.success) {
     throw new IslandBuildFailedError({
@@ -197,9 +216,18 @@ async function buildAll(
       logs: built.logs.map((log) => String(log)).join('; '),
     });
   }
-  const linked = linkOutputs(await builtOutputs(files, built.outputs));
-  const chunks = entryChunks(files, linked);
-  return { chunks, shared: sharedChunks(chunks, linked) };
+  if (built.metafile === undefined) {
+    throw new IslandBuildFailedError({
+      file: files.join(', '),
+      logs: 'the bundler returned no metafile',
+    });
+  }
+  await refuseDuplicatedModules(files.join(', '), built.metafile);
+  const sources = new Map<string, SourcePaths>();
+  const linked = linkOutputs(await builtOutputs(root, files, built.outputs, sources));
+  const chunks = loadingRuntime(entryChunks(files, linked, sources), live, runtime);
+  const shared = sharedChunks(chunks, linked, sources);
+  return { chunks, shared: [...shared, ...runtimeShared(runtime, live)] };
 }
 
 /**
@@ -212,11 +240,12 @@ async function blame(
   files: readonly string[],
   error: unknown,
   splitting: boolean,
+  runtimes: Runtimes,
 ): Promise<IslandBuildFailedError> {
   if (files.length > 1) {
     for (const file of files) {
       try {
-        await buildAll(root, [file], splitting);
+        await buildAll(root, [file], splitting, runtimes);
       } catch (alone) {
         if (alone instanceof IslandBuildFailedError) return alone;
       }
@@ -241,8 +270,10 @@ const withoutExtension = (file: string): string =>
 
 /** Every code output paired with its source map's inputs and, for an entry, its island. */
 async function builtOutputs(
+  root: string,
   files: readonly string[],
   artifacts: readonly Bun.BuildArtifact[],
+  sourcePaths: Map<string, SourcePaths>,
 ): Promise<readonly BuiltOutput[]> {
   const byStem = new Map(files.map((file) => [withoutExtension(file), file]));
   const maps = new Map<string, string>();
@@ -255,7 +286,9 @@ async function builtOutputs(
     const key = outputKey(artifact.path);
     const file = artifact.kind === 'entry-point' ? byStem.get(withoutExtension(key)) : undefined;
     const map = maps.get(`${artifact.path}.map`);
-    const sources = map === undefined ? undefined : sourcesContentOf(JSON.parse(map), true);
+    const parsed: unknown = map === undefined ? undefined : JSON.parse(map);
+    const sources = parsed === undefined ? undefined : sourcesContentOf(parsed, true);
+    sourcePaths.set(key, await sourcesOnDisk(root, parsed));
     if (sources === undefined || (artifact.kind === 'entry-point' && file === undefined)) {
       throw new IslandBuildFailedError({
         file: file ?? key,
@@ -276,6 +309,7 @@ async function builtOutputs(
 function entryChunks(
   files: readonly string[],
   linked: readonly LinkedFile[],
+  sources: ReadonlyMap<string, SourcePaths>,
 ): readonly IslandChunk[] {
   const shared = new Map(
     linked
@@ -311,6 +345,7 @@ function entryChunks(
       // different files at one address. `bytes` is measured on THAT code, never on this build's.
       ...stableChunk(file, entry.identity, entry.code),
       imports: closure(entry.imports),
+      sources: sources.get(entry.path) ?? [],
     });
   }
   return chunks;
@@ -320,6 +355,7 @@ function entryChunks(
 function sharedChunks(
   chunks: readonly IslandChunk[],
   linked: readonly LinkedFile[],
+  sources: ReadonlyMap<string, SourcePaths>,
 ): readonly SharedChunk[] {
   const out: SharedChunk[] = [];
   for (const one of linked) {
@@ -332,6 +368,7 @@ function sharedChunks(
         .filter((chunk) => chunk.imports.includes(url))
         .map((chunk) => chunk.file)
         .sort(),
+      sources: sources.get(one.path) ?? [],
     });
   }
   return out.sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
@@ -373,43 +410,15 @@ export async function buildIslands(
   // an empty bundle here would surface two steps later, as a chunk table with no entry for a file
   // the caller can see on disk.
   if (only !== undefined && files.length === 0) throw onlyMissing(only, discovered);
+  const runtimes = runtimeBuilder(root, ISLAND_BASE_PATH);
   if (options.sharedChunks ?? (await loadSharedChunks(root))) {
-    const built = await buildAll(root, files, true);
+    const built = await buildAll(root, files, true, runtimes);
     return islandBundle(built.chunks, built.shared);
   }
-  // One build per island, splitting off: each chunk is self-contained, so its size is the whole
-  // answer to "what does booting this island cost?" and nothing is shaken for another island.
-  const solo = await Promise.all(files.map((file) => buildAll(root, [file], false)));
-  return islandBundle(solo.flatMap((one) => one.chunks));
-}
-
-/**
- * Same code as an unbuildable `src`: "this path cannot become a client entry" is one condition.
- *
- * Two fixes, because there are two causes and only one of them can be repaired by naming a path.
- * The line was `pass only: '<app-root-relative path>.island.tsx'` — a placeholder nobody can run,
- * which no gate could see: `fixProblem` fails a fix only for ADVICE with no command token, and a
- * sentence with neither is not advice. Both forms below are constructed from what the caller
- * already handed in, so neither can name a path this app does not have.
- */
-function onlyMissing(only: string, discovered: readonly string[]): IslandInvalidError {
-  const cause =
-    `buildIslands was asked for ${JSON.stringify(only)} alone, which is not one of the ` +
-    `${discovered.length} islands this app has (${discovered.length === 0 ? 'none' : discovered.join(', ')})`;
-  // The basename match first: a filter that misses normally missed on the PREFIX — a route-relative
-  // specifier where `discoverIslands`' app-root-relative path was wanted — and the filename
-  // survives that. Falling back to the first keeps the fix a real path rather than a shape.
-  const nearest =
-    discovered.find((file) => posix.basename(file) === posix.basename(only)) ?? discovered[0];
-  // An app with no islands cannot be pointed at one, so the fix WRITES the file that was asked
-  // for — the same command `entryMissing` hands back, split off the same path.
-  if (nearest === undefined) {
-    return new IslandInvalidError(
-      cause,
-      `x g island ${posix.basename(only, ISLAND_EXTENSION)} --at ${posix.dirname(only)}`,
-    );
-  }
-  return new IslandInvalidError(cause, `buildIslands(root, { only: '${nearest}' })`);
+  // One build per island, splitting off: each chunk is self-contained but for the page runtime,
+  // the ONE file beside it every realtime island loads, counted once however many load it.
+  const solo = await Promise.all(files.map((file) => buildAll(root, [file], false, runtimes)));
+  return islandBundle(...mergeBuilds(solo));
 }
 
 export function islandBundle(
@@ -437,25 +446,6 @@ export function islandBundle(
   };
 }
 
-/**
- * The specifier named no file the build could bundle. `X_ISLAND_INVALID` is render's and is
- * borrowed rather than renamed here: "this src cannot become a client entry" is the condition that
- * code already means, and a second name for it is a second thing to look up.
- */
-function entryMissing(
-  routeFile: string,
-  src: string,
-  target: string,
-  chunks: readonly IslandChunk[],
-): IslandInvalidError {
-  const known = chunks.map((chunk) => chunk.file);
-  return new IslandInvalidError(
-    `${routeFile} declares island src ${JSON.stringify(src)}, which resolves to ${target} — a ` +
-      `file this build did not bundle (${known.length === 0 ? 'it found no islands at all' : `it found ${known.join(', ')}`})`,
-    `x g island ${posix.basename(target, ISLAND_EXTENSION)} --at ${posix.dirname(target)}`,
-  );
-}
-
 /** Write every chunk under the static export, at the same URL the documents already carry. */
 export async function writeIslands(bundle: IslandBundle, out: string): Promise<void> {
   for (const chunk of [...bundle.chunks, ...bundle.shared]) {

package/src/island-capture.ts

@@ -265,7 +265,7 @@ export async function captureIslandState(
         state: target.state,
         theme: target.theme,
         reason: `produced ${bytes.byteLength} bytes, under the ${floor}-byte floor — that is not an image`,
-        fix: `x shot --island ${target.name} --browser /usr/bin/chromium --json`,
+        fix: `x shot --island ${target.name} --browser /usr/bin/chromium --json   # macOS: --browser "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; Windows: --browser "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"`,
       });
     }
     await Bun.write(join(options.outDir, target.file), bytes);

package/src/island-duplicate-refusal.ts

@@ -0,0 +1,57 @@
+// What a module bundled twice costs the build. A framework bug refuses it: one file under two
+// spellings, or a second `@ultimat3/*` copy, is the framework's resolver or dedupe failing. A
+// third-party package installed twice with identical bytes is the app's lockfile, which the app
+// did not write by hand — so it is a warning naming the bytes, never a broken build.
+
+import { logger, UltimateError } from '@ultimat3/core';
+import type { DuplicatedModule, IslandMetafile, ModuleIdentityIo } from './island-duplicates';
+import { duplicatedModules, hostIo } from './island-duplicates';
+import { quoteArg } from './shell-quote';
+
+/** The framework's own scope: a second copy of one of these is ours to fold (`island-package-dedupe.ts`). */
+const FRAMEWORK_SCOPE = '@ultimat3/';
+
+/** A duplicate only the framework can have caused. */
+export const isFrameworkDuplicate = (one: DuplicatedModule): boolean =>
+  one.sameFile || (one.packageName?.startsWith(FRAMEWORK_SCOPE) ?? false);
+
+/**
+ * Its own code, not `X_BUILD_FAILED`: that one's fix re-runs `bun build`, which SUCCEEDS here — the
+ * build did not fail, it shipped one module twice and said `success: true`. Every refusal is a
+ * framework defect, so the fix is the report that gets it fixed.
+ */
+export class IslandModuleDuplicatedError extends UltimateError {
+  constructor(island: string, found: readonly DuplicatedModule[]) {
+    const wasted = found.reduce((sum, one) => sum + one.wastedBytes, 0);
+    const listed = found
+      .slice(0, 3)
+      .map((one) => `${one.package ?? 'one file'} as ${one.spellings.join(' and ')}`)
+      .join('; ');
+    super({
+      code: 'X_ISLAND_MODULE_DUPLICATED',
+      cause:
+        `${island} bundles ${found.length} module(s) more than once in ${found[0]?.output ?? 'its chunk'} ` +
+        `(${wasted} B shipped twice): ${listed}${found.length > 3 ? `; and ${found.length - 3} more` : ''}`,
+      fix: `gh issue create --repo developerz-ai/ultimate --title ${quoteArg(`X_ISLAND_MODULE_DUPLICATED in ${island}`)} — paste this error's --json as the body: the framework bundled one of its own modules twice`,
+    });
+  }
+}
+
+/** The one line a third-party copy costs: the island, the package, the bytes, and what to run. */
+export const thirdPartyWarning = (island: string, one: DuplicatedModule): string =>
+  `X_ISLAND_MODULE_DUPLICATED (warning): ${island} bundles ${one.package ?? 'a package'} twice ` +
+  `(${one.wastedBytes} B shipped twice, as ${one.spellings.join(' and ')}) — fix: bun why ` +
+  `${quoteArg(one.packageName ?? '<package>')}, then bun install --force to fold the copies`;
+
+/** Refuse a framework duplicate; warn about each third-party one. */
+export async function refuseDuplicatedModules(
+  island: string,
+  metafile: IslandMetafile,
+  io: ModuleIdentityIo = hostIo(),
+  warn: (line: string) => void = (line) => logger.warn(line),
+): Promise<void> {
+  const found = await duplicatedModules(metafile, io);
+  const fatal = found.filter(isFrameworkDuplicate);
+  if (fatal.length > 0) throw new IslandModuleDuplicatedError(island, fatal);
+  for (const one of found) warn(thirdPartyWarning(island, one));
+}