@gonvex/cli 0.5.2-staging.2 → 0.5.2-staging.21

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { lazyReferenceRuntime, renderLazyReferences } from "./lazy-reference-bindings.js";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -8,8 +9,10 @@ import { createInterface } from "node:readline/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import { Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
-import { buildModuleArtifact, detectProjectLanguage, moduleManifestFunctions, moduleSourceFiles, isModuleSchema, } from "./module-artifact.js";
+import { buildModuleArtifact, detectProjectLanguage, moduleManifestFunctions, moduleSourceFiles, } from "./module-artifact.js";
 import { renderFunctionCatalog } from "./function-catalog.js";
+import { localBindings, projectLocalSchema } from "./local-bindings.js";
+import { analyzeLocalReducerDependencies, formatLocalDependencyViolations, localDependencyTables, localDependencyViolations, } from "./local-dependencies.js";
 export * from "./function-catalog.js";
 const defaultRuntimeURL = "http://localhost:8080";
 const runtimeSyncRetryMs = 5000;
@@ -1102,15 +1105,50 @@ async function buildManifest(root, sources, projectID) {
         entrypoint: sources.config.module?.entrypoint,
         bundle: sources.config.module?.bundle,
     });
+    const functions = moduleManifestFunctions(module);
+    await applyLocalDependencies(root, sources, functions);
     return {
         project: projectID,
         generatedAt: new Date().toISOString(),
-        functions: moduleManifestFunctions(module),
+        functions,
         schema: emptySchemaDefinition(),
         module,
         ...(Object.keys(module.visibility).length > 0 ? { visibility: module.visibility } : {}),
     };
 }
+/**
+ * Record each locally executing Reducer's table dependencies in the manifest
+ * and reject dependencies that no generated local collection can satisfy.
+ * See local-dependencies.ts for the analysis and its precision limits.
+ */
+async function applyLocalDependencies(root, sources, functions) {
+    const reducers = Object.entries(functions)
+        .filter(([, entry]) => entry.kind === "reducer" && entry.localExecution === 1 && !entry.internal)
+        .map(([path, entry]) => ({ path, file: entry.file, exportName: entry.handler }));
+    if (!reducers.length)
+        return;
+    const mode = sources.config.module?.localDependencyCheck ?? "error";
+    if (mode !== "error" && mode !== "warn")
+        throw new Error('gonvex.json module.localDependencyCheck must be "error" or "warn"');
+    const analyses = await analyzeLocalReducerDependencies({
+        root, backendDir: join(root, "gonvex"), files: sources.moduleFiles, reducers, tsconfig: sources.config.module?.tsconfig,
+    });
+    const schema = await projectLocalSchema(root);
+    const tableKeys = new Map(Object.entries(schema).map(([table, shape]) => [table, shape.key]));
+    const localTables = new Set(Object.entries(functions)
+        .filter(([path, entry]) => path.startsWith("__local.") && entry.replica)
+        .map(([, entry]) => entry.replica.table));
+    for (const analysis of analyses)
+        functions[analysis.path].localDependencies = localDependencyTables(analysis, tableKeys);
+    const violations = localDependencyViolations(analyses, localTables, tableKeys);
+    if (!violations.length)
+        return;
+    const report = formatLocalDependencyViolations(violations);
+    if (mode === "error") {
+        throw new Error(`Local Reducer dependency check failed. ${report}\nSet gonvex.json module.localDependencyCheck to "warn" only while migrating.`);
+    }
+    console.warn(color.yellow(`[gonvex] warning: ${report}`));
+}
 async function writeBindings(root, manifest) {
     const dir = join(root, "gonvex", "_generated");
     await mkdir(dir, { recursive: true });
@@ -1118,9 +1156,15 @@ async function writeBindings(root, manifest) {
     let changedFiles = 0;
     if (await writeManifestIfChanged(join(dir, "manifest.json"), manifest))
         changedFiles += 1;
+    const local = await localBindings(root, manifest);
+    if (local["local-reducers.js"])
+        await rm(join(dir, "local-reducers.ts"), { force: true });
     const outputs = {
+        ...local,
         "api.ts": renderAPI(manifest),
-        "client.ts": '// Generated by gonvex dev. Do not edit.\nexport { GonvexClient, createFirebaseAuthAdapter } from "@gonvex/client";\nexport type { GonvexExternalAuthAdapter, GonvexExternalIdentityHint, GonvexFirebaseAuthAdapterOptions } from "@gonvex/client";\n',
+        "client.ts": local["local-runtime.ts"]
+            ? '// Generated by Gonvex. Do not edit.\nimport { GonvexClient as BaseClient, type GonvexClientOptions } from "@gonvex/client";\nimport { localRuntime } from "./local-runtime.js";\nexport class GonvexClient extends BaseClient { constructor(url: string, options: GonvexClientOptions = {}) { super(url, { ...options, localRuntime: options.localRuntime ?? localRuntime }); } }\nexport { createFirebaseAuthAdapter } from "@gonvex/client";\n'
+            : '// Generated by gonvex dev. Do not edit.\nexport { GonvexClient, createFirebaseAuthAdapter } from "@gonvex/client";\nexport type { GonvexExternalAuthAdapter, GonvexExternalIdentityHint, GonvexFirebaseAuthAdapterOptions } from "@gonvex/client";\n',
         "react.ts": '// Generated by gonvex dev. Do not edit.\nexport { createFirebaseAuthAdapter, createGonvexAuth, GonvexAuthProvider, GonvexGoogleAuthButton, GonvexProvider, GonvexProviderWithAuth, useAction, useControlQuery, useCurrentTenantProfile, useEntity, useGonvexAuth, useGonvexAuthState, useGonvexClient, useGonvexConnectionState, useInvitationList, useLiveQuery, useLiveQueryState, useQuery, useReducer, useReplicaCollection, useReplicaCollectionState, useReplicaEntities, useReplicaSelector, useRetainedLiveQuery } from "@gonvex/react";\nexport type { GonvexAuthAccount, GonvexAuthConfig, GonvexAuthProviderName, GonvexAuthTenant, GonvexAuthValue, GonvexDeveloperModeState, GonvexExternalAuthAdapter, GonvexExternalIdentityHint, GonvexFirebaseAuthAdapterOptions } from "@gonvex/react";\n',
         "types.ts": "// Generated by gonvex dev. Do not edit.\nexport type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };\n",
         "schema.ts": renderSchemaIndex(manifest),
@@ -1136,6 +1180,22 @@ async function writeBindings(root, manifest) {
         if (await writeFileIfChanged(join(dir, name), contents))
             changedFiles += 1;
     }
+    // Agent catalogs are checked into some applications and imported by their
+    // browser bundle. Once a project opts in by creating either conventional
+    // output, keep it on the exact artifact built by `gonvex dev`/`codegen`.
+    // Otherwise a backend hot reload can activate a new artifact while the
+    // browser continues sending the old hash, making every delegated call fail
+    // with STALE_AGENT_CATALOG until somebody manually re-emits the files.
+    for (const [name, format] of [
+        ["agent-api.ndjson", "ndjson"],
+        ["agent-api.d.ts", "typescript"],
+    ]) {
+        const output = join(root, name);
+        if (existsSync(output) && await writeFileIfChanged(output, renderFunctionCatalog(manifest.module, format))) {
+            changedFiles += 1;
+            console.log(`[gonvex] refreshed ${name} for artifact ${manifest.module.hash}`);
+        }
+    }
     return { changedFiles };
 }
 async function writeManifestIfChanged(path, manifest) {
@@ -1244,8 +1304,9 @@ function renderAPI(manifest) {
             ...(entry.delivery ? { delivery: entry.delivery } : {}),
             ...(entry.delivery === "replica" && entry.replica ? { replica: entry.replica } : {}),
             ...(entry.offline !== undefined ? { offline: entry.offline } : {}),
-            ...(isModuleSchema(entry.args) ? { args: entry.args } : {}),
-            ...(isModuleSchema(entry.result) ? { result: entry.result } : {}),
+            ...(entry.localExecution !== undefined ? { localExecution: entry.localExecution } : {}),
+            // Args/Result are phantom types below. Validation schemas remain in the
+            // module manifest and agent catalog; the browser never consumes them.
         };
         if (entry.delivery === "live" && entry.dependencies?.liveQueryPlan) {
             const plan = entry.dependencies.liveQueryPlan;
@@ -1284,6 +1345,7 @@ function renderAPI(manifest) {
         "  readonly delivery?: \"oneShot\" | \"live\" | \"replica\";",
         "  readonly replica?: { readonly table: string; readonly key: string; readonly columns?: readonly string[] };",
         "  readonly offline?: { readonly mode: \"forbidden\" | \"allowed\" | \"onlineOnly\"; readonly conflict?: \"reject\" | \"expectedVersion\" | \"merge\"; readonly reason?: string };",
+        "  readonly localExecution?: 1;",
         "  readonly args?: Args;",
         "  readonly result?: Result;",
         "  readonly live?: { readonly entity: string; readonly key: string; readonly resultPath?: readonly string[]; readonly plan: LiveQueryPlan };",
@@ -1295,11 +1357,13 @@ function renderAPI(manifest) {
             `export type ${result} = ${renderSchemaType(manifest.functions[path]?.result)};`,
         ]),
         "",
-        `export const api = ${renderObject(publicRoot, 0)} as const;`,
+        lazyReferenceRuntime,
+        "",
+        `export const api = ${renderLazyReferences(publicRoot, 0, isFunctionRef, renderObject)};`,
         "",
         "export const control = gonvexControl;",
         "",
-        `export const internal = ${renderObject(internalRoot, 0)} as const;`,
+        `export const internal = ${renderLazyReferences(internalRoot, 0, isFunctionRef, renderObject)};`,
         "export type Api = typeof api;",
         "",
         `export const optimisticTransactions: Record<string, OptimisticTransactionDefinition> = ${renderObject(optimisticTransactions, 0)};`,