@ultimat3/cli 27.3.0 → 27.5.0

package/package.json

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

package/src/app-layout.ts

@@ -0,0 +1,46 @@
+// The one feature layout, made a build error: a primitive module `actions.ts` (or `live`,
+// `queries`, `jobs`, `tasks`) beside the directory of the same name is refused. `x g` writes the
+// directory form — `<slice>/actions/<name>.ts`, one primitive per file — and an app that also keeps
+// `actions.ts` has two homes for one kind of thing, where `./actions` resolves to the file and never
+// the directory. A component module beside its folder (`ui.tsx` + `ui/`) is not a primitive's home,
+// and `x g resource` writes exactly that pair.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { SourceFile } from './app-boundaries';
+import type { Finding } from './output';
+
+/** The directories `x g` writes primitives into — the only names the refusal reads. */
+export const PRIMITIVE_DIRS: ReadonlySet<string> = new Set([
+  'actions',
+  'live',
+  'queries',
+  'jobs',
+  'tasks',
+]);
+
+const MODULE = /^(?<stem>.+)\.(?:ts|tsx)$/;
+
+/** Every primitive module `X.ts` among `files` beside a directory `X/` holding another of them. */
+export function siblingModuleFindings(files: readonly SourceFile[]): readonly Finding[] {
+  const directories = new Set<string>();
+  for (const { path } of files) {
+    const parts = path.split('/');
+    for (let depth = 1; depth < parts.length; depth += 1) {
+      directories.add(parts.slice(0, depth).join('/'));
+    }
+  }
+  return files.flatMap(({ path }): Finding[] => {
+    const stem = MODULE.exec(path)?.groups?.['stem'];
+    const name = stem?.split('/').at(-1) ?? '';
+    if (stem === undefined || !PRIMITIVE_DIRS.has(name) || !directories.has(stem)) return [];
+    return [
+      {
+        code: 'X_LAYOUT_SIBLING_MODULE',
+        cause: `${path} sits beside the directory ${stem}/ — \`./${name}\` resolves to the file, and the directory form is the one layout`,
+        fix: `x verify --only boundaries --json   # move each declaration in ${path} to ${stem}/<its-export-in-kebab-case>.ts, then delete ${path}`,
+        docs: ERROR_DOCS_URL,
+        at: path,
+      },
+    ];
+  });
+}

package/src/boundary-findings.ts

@@ -5,6 +5,7 @@
 
 import type { SourceFile } from './app-boundaries';
 import { appImportGraph, checkImportRules, readAppSources } from './app-boundaries';
+import { siblingModuleFindings } from './app-layout';
 import { appTransportFindings } from './app-transport';
 import { planBoundaryCuts } from './boundary-cuts';
 import type { Finding } from './output';
@@ -44,5 +45,6 @@ export async function appBoundaryFindings(
   return [
     ...withCutEdits(checkImportRules(files), appImportGraph(files)),
     ...(await appTransportFindings(root, files)),
+    ...siblingModuleFindings(files),
   ];
 }

package/src/error-codes.ts

@@ -232,6 +232,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_PACKAGE_TEST_ONLY_SHIPPED',
   'X_ISLAND_MODULE_DUPLICATED',
   'X_BACKFILL_SLICE_ENTITY',
+  'X_LAYOUT_SIBLING_MODULE',
 ] as const;
 
 /**
@@ -420,6 +421,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_PACKAGE_TEST_ONLY_SHIPPED: 'a test-only module ships in the tarball',
   X_ISLAND_MODULE_DUPLICATED: 'An island chunk bundles one module more than once',
   X_BACKFILL_SLICE_ENTITY: 'the slice holds no entity a generated backfill can sweep',
+  X_LAYOUT_SIBLING_MODULE: 'a primitive module beside its directory',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/mcp-errors.ts

@@ -302,6 +302,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'gh issue create --repo developerz-ai/ultimate --title "X_ISLAND_MODULE_DUPLICATED"   # paste this error\'s --json as the body: the framework bundled one of its own modules twice',
   X_BACKFILL_SLICE_ENTITY:
     'x errors explain X_BACKFILL_SLICE_ENTITY --json   # the refusal itself names the x g job line for this slice',
+  X_LAYOUT_SIBLING_MODULE:
+    'x verify --only boundaries --json   # then move each declaration in X.ts to X/<name>.ts, one primitive per file',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/role-start.ts

@@ -39,7 +39,7 @@ import { rolesUnderRealtime } from './role-realtime';
 import { startReplicator } from './role-replicator';
 import type { RunningRoles, StartRolesOptions } from './role-start-types';
 import { DEV_ROLES } from './role-start-types';
-import { prepareSync, type RunningSync } from './role-sync';
+import { prepareSync, type RunningSync, syncReadsChanges } from './role-sync';
 import { startWorkerWake } from './role-wake';
 import { devHooks } from './runtime-hooks';
 import { workerOptionsFor } from './runtime-jobs';
@@ -393,6 +393,7 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       dbMode: options.runtime.services.db.mode,
       transport: options.runtime.transport.name,
       replicatorHere: replicator !== null,
+      readsChanges: syncReadsChanges(),
     });
     started.push(async () => live.stop());
     // The web server and the sync node mark ready when they bind; a process with neither — a

package/src/role-sync.ts

@@ -14,6 +14,7 @@ import { listQueries } from '@ultimat3/query';
 import type { SyncNode, SyncWs } from '@ultimat3/realtime/server';
 import {
   ChannelHub,
+  describeChannels,
   LiveQueryRegistry,
   listenSyncNode,
   liveQueryDefinition,
@@ -195,6 +196,19 @@ export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegist
   return registry;
 }
 
+/**
+ * Whether a node in this process would read a committed change at all: a `live: true` query, or a
+ * declared channel that lists `records`. What is left when neither exists is events channels, and
+ * those ride the transport from whoever publishes them (`publishChannelEvent`) — so the boot asks
+ * this before it holds a real database to having a replicator (`runtime-live-feed.ts`).
+ */
+export function syncReadsChanges(): boolean {
+  return (
+    listQueries().some((target) => target.isLive) ||
+    describeChannels().some((declared) => declared.records.length > 0)
+  );
+}
+
 /**
  * Who dialled the socket, resolved by `@ultimat3/http`'s `clientAddress()` — the rule the web role's
  * `ctx.ip` follows, at the same `TRUSTED_PROXY_HOPS`. It keys an anonymous live reader's rate

package/src/runtime-live-feed.ts

@@ -40,6 +40,12 @@ export interface LiveFeedInput {
   readonly transport: string;
   /** Whether the `replicator` role runs in THIS process. */
   readonly replicatorHere: boolean;
+  /**
+   * Whether anything this node serves reads a committed change: a `live: true` query, or a channel
+   * that lists `records` (`role-sync.ts`'s `syncReadsChanges`). An events-only channel does not —
+   * the app publishes its frames through the transport — so such a node needs no replicator.
+   */
+  readonly readsChanges: boolean;
 }
 
 /** The label the `x dev` boot line carries beside `db=`, `events=` and `storage=`. */
@@ -49,11 +55,16 @@ export const liveFeedLabel = (feed: LiveFeed): string => `live=${feed}`;
  * `embedded` → the in-process bridge; anything else → replication, which is the WAL decoder's
  * job whether the replicator role runs in this process or another. Never both: with a real
  * database the decoder already delivers this process's own writes, and a bridge beside it would
- * deliver every one of them twice. No sync node, no feed to speak of.
+ * deliver every one of them twice. No sync node, no feed to speak of — and none for a node on a
+ * real database that serves only events channels, which the transport alone carries.
  */
 export async function startLiveFeed(input: LiveFeedInput): Promise<RunningLiveFeed> {
   if (input.sync === null) return { feed: 'none', bridge: null, stop: () => undefined };
   if (input.dbMode !== 'embedded') {
+    // Nothing here reads the log, so nothing is owed one: refusing this node demanded a
+    // replication slot (and the cluster-wide REPLICATION grant) to carry channel events the
+    // write-ahead log never held. `none`, said on the boot line, never a `replication` nobody runs.
+    if (!input.readsChanges) return { feed: 'none', bridge: null, stop: () => undefined };
     // A decoder this node can hear: in this process, or on a bus other processes share. Neither
     // is a sync node that reported `replication` while nothing could ever reach it.
     if (input.transport === 'in-process' && !input.replicatorHere)

package/src/runtime-services.ts

@@ -27,7 +27,7 @@ import {
   setMailDriver,
 } from '@ultimat3/mail';
 import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
-import { selectTransport } from '@ultimat3/realtime/server';
+import { selectTransport, setChannelTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
 import { loadAppConfig } from './app-config-load';
@@ -415,6 +415,10 @@ export async function startServices(
       started.push(() => bus.transport.close());
       transport = bus.transport;
     }
+    // The bus an app's own code publishes a channel event on (`publishChannelEvent`), in EVERY
+    // role: the hub is the `sync` role's, so a job or an action reached none, and an events-only
+    // channel — the one kind that needs no replicator — could be fed by nothing but a socket.
+    started.push(setChannelTransport(transport));
     // Only a transport that can be disconnected gets a check. `NatsTransport.connected` is a
     // synchronous getter over the client's own state, so no probe is needed; the in-process bus
     // has nothing to lose a connection to, and a check that can only answer `true` is a number in