@hops-ops/distributed 4.9.0 → 4.10.0

package/dist/sveltekit/vite.d.ts

@@ -1,3 +1,5 @@
+import { type DistributedSvelteKitBoundaryRegistration } from './islands/boundaries.js';
+export { analyzeDistributedSvelteKitBoundaries, validateDistributedSvelteKitBoundaryPlan, type DistributedIslandInventory, type DistributedIslandPlanInput, type DistributedSvelteKitBoundary, type DistributedSvelteKitBoundaryAnalysisClient, type DistributedSvelteKitBoundaryAnalysisOptions, type DistributedSvelteKitBoundaryOccurrence, type DistributedSvelteKitBoundaryPlan, type DistributedSvelteKitBoundaryRegistration } from './islands/boundaries.js';
 export type DistributedGraphqlProxyOptions = {
     /** Absolute Distributed API origin, for example `http://127.0.0.1:8791`. */
     target: string;
@@ -28,8 +30,8 @@ export type DistributedSvelteKitClientCompiler = Readonly<{
     surface?: string;
     /** GraphQL globs passed verbatim as repeated `distributed client --documents`. */
     documents: readonly string[];
-    /** Explicit `OPERATION=/route` fallbacks. */
-    routes?: readonly string[];
+    /** Typed fallback when static component ownership cannot be proven. */
+    boundaries?: readonly DistributedSvelteKitBoundaryRegistration[];
     /** Compiler-owned artifact directory, relative to `cwd` by default. */
     out: string;
 }>;
@@ -40,6 +42,12 @@ export type DistributedSvelteKitViteOptions = Readonly<{
     command?: string;
     /** Prefix argv, e.g. `cargo run ... --`; never interpreted by a shell. */
     commandArgs?: readonly string[];
+    /** SvelteKit route source root. Defaults to `src/routes`. */
+    routesDir?: string;
+    /** SvelteKit library source root. Defaults to `src/lib`. */
+    libDir?: string;
+    /** Additional project-local `$name` aliases used by static component imports. */
+    aliases?: Readonly<Record<string, string>>;
     clients: readonly DistributedSvelteKitClientCompiler[];
 }>;
 type ViteWebSocketLike = Readonly<{
@@ -136,4 +144,3 @@ export declare function distributedSvelteKit(options: DistributedSvelteKitViteOp
  * generation and is safe to call from `svelte.config.js`.
  */
 export declare function distributedSvelteKitAliases(options: Pick<DistributedSvelteKitViteOptions, 'cwd' | 'clients'>): Readonly<Record<string, string>>;
-export {};

package/dist/sveltekit/vite.js

@@ -1,10 +1,13 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
-import { cp, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, unlink, writeFile } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { isMainThread } from 'node:worker_threads';
+import { analyzeDistributedSvelteKitBoundaries, validateDistributedSvelteKitBoundaryPlan } from './islands/boundaries.js';
+export { analyzeDistributedSvelteKitBoundaries, validateDistributedSvelteKitBoundaryPlan } from './islands/boundaries.js';
 const GENERATED_SVELTEKIT_MODULE = 'sveltekit.ts';
+const GENERATED_BOUNDARIES_MODULE = 'boundaries.ts';
 const MAX_COMMAND_OUTPUT_BYTES = 16 * 1024 * 1024;
 const MAX_GENERATED_COMPARE_FILES = 20_000;
 const MAX_GENERATED_COMPARE_BYTES = 128 * 1024 * 1024;
@@ -162,10 +165,14 @@ export function distributedSvelteKit(options) {
             configureLifecycleServer(server);
             const integration = requireResolved(resolved);
             if (!lifecycleOwnsCompile) {
-                const roots = integration.clients.flatMap((client) => [
-                    ...client.watchRoots,
-                    ...client.manifestWatchRoots
-                ]);
+                const roots = [
+                    integration.routesDir,
+                    integration.libDir,
+                    ...integration.clients.flatMap((client) => [
+                        ...client.watchRoots,
+                        ...client.manifestWatchRoots
+                    ])
+                ];
                 if (roots.length > 0)
                     server.watcher.add(roots);
             }
@@ -177,6 +184,8 @@ export function distributedSvelteKit(options) {
             const integration = requireResolved(resolved);
             if (lifecycleOwnsCompile)
                 return;
+            this.addWatchFile(integration.routesDir);
+            this.addWatchFile(integration.libDir);
             for (const client of integration.clients) {
                 for (const root of [...client.watchRoots, ...client.manifestWatchRoots])
                     this.addWatchFile(root);
@@ -203,7 +212,7 @@ export function distributedSvelteKit(options) {
             if (lifecycleOwnsCompile)
                 return [];
             try {
-                await compile(`GraphQL change ${context.file}`);
+                await compile(`GraphQL/Svelte change ${context.file}`);
             }
             catch (error) {
                 context.server.ws.send({
@@ -231,7 +240,7 @@ export function distributedSvelteKit(options) {
             if (lifecycleOwnsCompile)
                 return;
             if (isCompilerInput(id, integration)) {
-                await compile(`GraphQL watch change ${id}`);
+                await compile(`GraphQL/Svelte watch change ${id}`);
             }
         },
         closeBundle: stop
@@ -488,6 +497,14 @@ function resolveIntegration(options, fallbackCwd) {
     }
     const modules = new Set();
     const outputs = [];
+    const routesDir = containedPath(cwd, options.routesDir ?? 'src/routes', 'routesDir');
+    const libDir = containedPath(cwd, options.libDir ?? 'src/lib', 'libDir');
+    const aliases = Object.freeze(Object.fromEntries(Object.entries(options.aliases ?? {}).map(([key, value]) => {
+        if (!/^\$[A-Za-z0-9_-]+$/.test(key)) {
+            throw new TypeError(`Distributed SvelteKit alias \`${key}\` must be a single $name segment`);
+        }
+        return [key, portablePath(relative(cwd, containedPath(cwd, value, `alias ${key}`)))];
+    })));
     const clients = options.clients.map((client, index) => {
         if (client === null || typeof client !== 'object') {
             throw new TypeError(`Distributed client[${index}] must be an object`);
@@ -515,7 +532,21 @@ function resolveIntegration(options, fallbackCwd) {
             throw new TypeError(`Distributed client \`${client.module}\` requires at least one GraphQL document glob`);
         }
         const documents = client.documents.map((document, documentIndex) => nonempty(document, `${client.module} documents[${documentIndex}]`));
-        const routes = (client.routes ?? []).map((route, routeIndex) => nonempty(route, `${client.module} routes[${routeIndex}]`));
+        const boundaries = (client.boundaries ?? []).map((boundary, boundaryIndex) => {
+            if (boundary === null ||
+                typeof boundary !== 'object' ||
+                (boundary.kind !== 'page' && boundary.kind !== 'layout')) {
+                throw new TypeError(`${client.module} boundaries[${boundaryIndex}] is invalid`);
+            }
+            return Object.freeze({
+                operation: nonempty(boundary.operation, `${client.module} boundaries[${boundaryIndex}].operation`),
+                route: nonempty(boundary.route, `${client.module} boundaries[${boundaryIndex}].route`),
+                kind: boundary.kind,
+                ...(boundary.variables === undefined
+                    ? {}
+                    : { variables: boundary.variables })
+            });
+        });
         validateManifestSource(client.module, client.manifest);
         const out = containedPath(cwd, client.out, `${client.module} generated output`);
         if (out === cwd) {
@@ -527,14 +558,16 @@ function resolveIntegration(options, fallbackCwd) {
             }
         }
         outputs.push(out);
+        const adapterOut = join(cwd, '.svelte-kit', 'distributed', 'clients', Buffer.from(client.module).toString('base64url'));
         return Object.freeze({
             module: client.module,
             manifest: client.manifest,
             selector,
             documents: Object.freeze(documents),
-            routes: Object.freeze(routes),
+            boundaries: Object.freeze(boundaries),
             out,
             entry: join(out, GENERATED_SVELTEKIT_MODULE),
+            adapterOut,
             watchRoots: Object.freeze(documentWatchRoots(cwd, documents, out)),
             manifestWatchRoots: Object.freeze(manifestWatchRoots(cwd, client.manifest))
         });
@@ -548,6 +581,9 @@ function resolveIntegration(options, fallbackCwd) {
             }
             return argument;
         })),
+        routesDir,
+        libDir,
+        aliases,
         clients: Object.freeze(clients)
     });
 }
@@ -629,6 +665,11 @@ function isCompilerInput(file, integration) {
 }
 function isGraphqlInput(file, integration) {
     const absolute = resolve(integration.cwd, file);
+    if (absolute.endsWith('.svelte') &&
+        (isWithin(integration.routesDir, absolute) ||
+            isWithin(integration.libDir, absolute))) {
+        return true;
+    }
     if ((!absolute.endsWith('.graphql') && !absolute.endsWith('.gql')) ||
         !isWithin(integration.cwd, absolute)) {
         return false;
@@ -656,17 +697,12 @@ async function compileTransaction(integration, children, signal) {
                     throw new Error(`generated output ${client.out} must be a real directory`);
                 }
                 hadOutput = true;
-                await cp(client.out, output, {
-                    recursive: true,
-                    errorOnExist: true,
-                    force: false,
-                    dereference: false
-                });
             }
             catch (error) {
                 if (!isMissing(error))
                     throw error;
             }
+            await mkdir(output, { recursive: true });
             const args = [
                 'client',
                 '--manifest',
@@ -677,7 +713,6 @@ async function compileTransaction(integration, children, signal) {
                     '--documents',
                     document
                 ]),
-                ...client.routes.flatMap((route) => ['--route', route]),
                 '--out',
                 output
             ];
@@ -687,9 +722,24 @@ async function compileTransaction(integration, children, signal) {
                 client,
                 output,
                 backup: join(transaction, `backup-${index}`),
-                hadOutput
+                hadOutput,
+                adapterOutput: join(transaction, `adapter-${index}`),
+                adapterBackup: join(transaction, `adapter-backup-${index}`),
+                hadAdapterOutput: await realDirectoryExists(client.adapterOut)
             });
         }
+        const plans = await analyzeStagedBoundaries(integration, staged);
+        const plansByModule = new Map(plans.map((plan) => [plan.module, plan]));
+        for (const item of staged) {
+            const plan = plansByModule.get(item.client.module);
+            if (plan === undefined) {
+                throw new Error(`Distributed SvelteKit boundary analysis returned no plan for ${item.client.module}`);
+            }
+            await writeFile(join(item.output, GENERATED_BOUNDARIES_MODULE), boundaryModuleSource(plan), { encoding: 'utf8', flag: 'wx' });
+            await exposeBoundaryModule(item.output);
+            await mkdir(item.adapterOutput, { recursive: true });
+            await writeFile(join(item.adapterOutput, 'boundaries.json'), boundaryPlanSource(plan), { encoding: 'utf8', flag: 'wx' });
+        }
         throwIfAborted(signal);
         await commitOutputs(integration, staged, signal);
     }
@@ -703,12 +753,14 @@ async function checkTransaction(integration, children, signal) {
     const transactionRoot = await compilerTransactionRoot(integration);
     const transaction = await mkdtemp(join(transactionRoot, '.distributed-sveltekit-check-'));
     try {
+        const staged = [];
         for (const [index, client] of integration.clients.entries()) {
             throwIfAborted(signal);
             const manifest = await materializeManifest(integration, client, transaction, index, children, signal);
+            const output = join(transaction, `output-${index}`);
+            await mkdir(output, { recursive: true });
             await runCommand(integration, [
                 'client',
-                '--check',
                 '--manifest',
                 manifest,
                 client.selector[0],
@@ -717,10 +769,24 @@ async function checkTransaction(integration, children, signal) {
                     '--documents',
                     document
                 ]),
-                ...client.routes.flatMap((route) => ['--route', route]),
                 '--out',
-                client.out
+                output
             ], children, signal);
+            await validateGeneratedEntrypoint(integration.cwd, output, client.module);
+            staged.push(Object.freeze({ client, output }));
+        }
+        const plans = await analyzeStagedBoundaries(integration, staged);
+        const plansByModule = new Map(plans.map((plan) => [plan.module, plan]));
+        for (const [index, client] of integration.clients.entries()) {
+            const output = staged[index].output;
+            const plan = plansByModule.get(client.module);
+            if (plan === undefined) {
+                throw new Error(`Distributed SvelteKit boundary analysis returned no plan for ${client.module}`);
+            }
+            await writeFile(join(output, GENERATED_BOUNDARIES_MODULE), boundaryModuleSource(plan), { encoding: 'utf8', flag: 'wx' });
+            await exposeBoundaryModule(output);
+            await compareGeneratedTrees(client.out, output, client.module);
+            await validateAdapterBoundaryPlan(client, plan);
         }
     }
     finally {
@@ -735,6 +801,195 @@ async function compilerTransactionRoot(integration) {
     await mkdir(root, { recursive: true });
     return root;
 }
+async function validateAdapterBoundaryPlan(client, plan) {
+    let actual;
+    try {
+        actual = await readFile(join(client.adapterOut, 'boundaries.json'), 'utf8');
+    }
+    catch (error) {
+        /*
+         * `.svelte-kit` is SvelteKit-owned build state. A production build may
+         * replace it after our Vite startup generation, while the durable client
+         * tree (including boundaries.ts) remains current and was checked above.
+         */
+        if (isMissing(error))
+            return;
+        throw error;
+    }
+    let persisted;
+    try {
+        persisted = JSON.parse(actual);
+    }
+    catch {
+        throw new Error(`[distributed.island.boundary_plan_invalid] ${client.module} boundaries.json is not valid JSON`);
+    }
+    validateDistributedSvelteKitBoundaryPlan(persisted, client.module);
+    const expected = boundaryPlanSource(plan);
+    if (actual !== expected) {
+        throw new Error(`Distributed SvelteKit boundary plan for ${client.module} is stale; run generation without check`);
+    }
+}
+async function analyzeStagedBoundaries(integration, staged) {
+    return await analyzeDistributedSvelteKitBoundaries({
+        cwd: integration.cwd,
+        routesDir: portablePath(relative(integration.cwd, integration.routesDir)),
+        libDir: portablePath(relative(integration.cwd, integration.libDir)),
+        aliases: integration.aliases,
+        clients: await Promise.all(staged.map(async ({ client, output }) => ({
+            module: client.module,
+            inventory: await readIslandInventory(integration.cwd, output),
+            explicitBoundaries: client.boundaries
+        })))
+    });
+}
+async function readIslandInventory(cwd, output) {
+    const path = join(output, 'islands.json');
+    const metadata = await lstat(path);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        throw new Error(`Distributed island inventory ${portablePath(relative(cwd, path))} must be a regular file`);
+    }
+    const canonicalRoot = await realpath(cwd);
+    const canonical = await realpath(path);
+    if (!isWithin(canonicalRoot, canonical)) {
+        throw new Error('Distributed island inventory escaped the project root');
+    }
+    return JSON.parse(await readFile(canonical, 'utf8'));
+}
+function boundaryPlanSource(plan) {
+    return `${JSON.stringify(plan, null, 2)}\n`;
+}
+function boundaryModuleSource(plan) {
+    validateDistributedSvelteKitBoundaryPlan(plan, plan.module);
+    const occurrences = plan.boundaries.flatMap((boundary) => boundary.islands.map((island) => ({ boundary, island })));
+    const artifacts = new Map();
+    for (const { island } of occurrences) {
+        if (!/^operations\/[A-Za-z0-9._-]+\.ts$/.test(island.modulePath) ||
+            !/^[_A-Za-z][_0-9A-Za-z]*$/.test(island.exportName)) {
+            throw new Error(`[distributed.island.boundary_plan_invalid] ${island.graphqlSource} has an unsafe generated artifact reference`);
+        }
+        const key = `${island.modulePath}\u0000${island.exportName}`;
+        if (!artifacts.has(key)) {
+            artifacts.set(key, Object.freeze({
+                alias: `DistributedBoundaryArtifact_${artifacts.size}`,
+                module: island.modulePath.slice(0, -3),
+                exportName: island.exportName
+            }));
+        }
+    }
+    const imports = [...artifacts.values()].map(({ alias, module, exportName }) => `import { ${exportName} as ${alias} } from './${module}.js';`);
+    const definitions = occurrences.map(({ boundary, island }, index) => {
+        const artifact = artifacts.get(`${island.modulePath}\u0000${island.exportName}`);
+        const discovery = island.reason === 'static_component_import' ? 'component' : island.reason;
+        return [
+            `const DistributedBoundaryBinding_${index} = defineDistributedBoundaryBinding(`,
+            `  ${artifact.alias},`,
+            `  ${JSON.stringify(island.binding.sources, null, 2)} as const`,
+            `);`,
+            `const DistributedBoundaryOperation_${index} = defineDistributedBoundaryOperation(`,
+            `  ${JSON.stringify({
+                operation: island.operation,
+                route: boundary.route,
+                kind: boundary.kind,
+                sourcePath: island.graphqlSource,
+                discovery
+            }, null, 2)} as const,`,
+            `  ${artifact.alias},`,
+            `  DistributedBoundaryBinding_${index}`,
+            `);`
+        ].join('\n');
+    });
+    const operations = occurrences.map((_, index) => `  DistributedBoundaryOperation_${index}`);
+    return [
+        '/** GENERATED by the Distributed SvelteKit boundary planner. Do not edit. */',
+        "import { defineDistributedBoundaryBinding, defineDistributedBoundaryOperation } from '@hops-ops/distributed/sveltekit';",
+        ...imports,
+        '',
+        `export const DISTRIBUTED_BOUNDARY_PLAN = ${JSON.stringify(plan, null, 2)} as const;`,
+        '',
+        ...definitions,
+        '',
+        '/** Executable SSR/browser ownership assembled from the same boundary plan. */',
+        `export const DISTRIBUTED_BOUNDARY_OPERATIONS = ${operations.length === 0 ? '[]' : `[\n${operations.join(',\n')}\n]`} as const;`,
+        ''
+    ].join('\n');
+}
+async function exposeBoundaryModule(output) {
+    const path = join(output, GENERATED_SVELTEKIT_MODULE);
+    const source = await readFile(path, 'utf8');
+    if (!source.startsWith('/** GENERATED by distributed client. Do not edit. */')) {
+        throw new Error('generated SvelteKit entrypoint is missing its ownership marker');
+    }
+    await writeFile(path, `${source.trimEnd()}\n\nexport { DISTRIBUTED_BOUNDARY_OPERATIONS, DISTRIBUTED_BOUNDARY_PLAN } from './boundaries.js';\n`, 'utf8');
+}
+async function compareGeneratedTrees(actualRoot, expectedRoot, module) {
+    const [actual, expected] = await Promise.all([
+        readGeneratedTree(actualRoot),
+        readGeneratedTree(expectedRoot)
+    ]);
+    const drift = [];
+    for (const [path, contents] of expected) {
+        const current = actual.get(path);
+        if (current === undefined)
+            drift.push(`missing ${path}`);
+        else if (current !== contents)
+            drift.push(`changed ${path}`);
+    }
+    for (const path of actual.keys()) {
+        if (!expected.has(path))
+            drift.push(`unexpected ${path}`);
+    }
+    if (drift.length > 0) {
+        throw new Error(`Distributed SvelteKit client ${module} is stale:\n  ${drift.sort().join('\n  ')}\nrun generation without check`);
+    }
+}
+async function readGeneratedTree(root) {
+    const rootMetadata = await lstat(root);
+    if (rootMetadata.isSymbolicLink() || !rootMetadata.isDirectory()) {
+        throw new Error(`generated output ${root} must be a real directory`);
+    }
+    const files = new Map();
+    const pending = [
+        { absolute: root, relative: '' }
+    ];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        for (const entry of await readdir(directory.absolute, { withFileTypes: true })) {
+            const relativePath = directory.relative.length === 0
+                ? entry.name
+                : `${directory.relative}/${entry.name}`;
+            const absolutePath = join(directory.absolute, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`generated output contains unsupported symlink ${relativePath}`);
+            }
+            if (entry.isDirectory()) {
+                pending.push({ absolute: absolutePath, relative: relativePath });
+                continue;
+            }
+            if (!entry.isFile()) {
+                throw new Error(`generated output contains unsupported entry ${relativePath}`);
+            }
+            files.set(relativePath, await readFile(absolutePath, 'utf8'));
+            if (files.size > 8_192) {
+                throw new Error('generated output exceeds 8192 files');
+            }
+        }
+    }
+    return files;
+}
+async function realDirectoryExists(path) {
+    try {
+        const metadata = await lstat(path);
+        if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+            throw new Error(`Distributed SvelteKit adapter output ${path} must be a real directory`);
+        }
+        return true;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
 async function materializeManifest(integration, client, transaction, index, children, signal) {
     throwIfAborted(signal);
     if (typeof client.manifest === 'string') {
@@ -778,23 +1033,37 @@ async function validateGeneratedEntrypoint(cwd, output, module) {
 async function commitOutputs(integration, staged, signal) {
     throwIfAborted(signal);
     await validateResolvedPaths(integration);
+    const outputs = staged.flatMap((item) => [
+        {
+            target: item.client.out,
+            output: item.output,
+            backup: item.backup,
+            hadOutput: item.hadOutput
+        },
+        {
+            target: item.client.adapterOut,
+            output: item.adapterOutput,
+            backup: item.adapterBackup,
+            hadOutput: item.hadAdapterOutput
+        }
+    ]);
     const applied = [];
     try {
-        for (const item of staged) {
+        for (const item of outputs) {
             throwIfAborted(signal);
-            await mkdir(dirname(item.client.out), { recursive: true });
-            await validateNearestExistingParent(integration.cwd, item.client.out);
-            if (item.hadOutput && await generatedTreesEqual(item.client.out, item.output)) {
+            await mkdir(dirname(item.target), { recursive: true });
+            await validateNearestExistingParent(integration.cwd, item.target);
+            if (item.hadOutput && await generatedTreesEqual(item.target, item.output)) {
                 continue;
             }
             if (item.hadOutput)
-                await rename(item.client.out, item.backup);
+                await rename(item.target, item.backup);
             try {
-                await rename(item.output, item.client.out);
+                await rename(item.output, item.target);
             }
             catch (error) {
                 if (item.hadOutput)
-                    await rename(item.backup, item.client.out);
+                    await rename(item.backup, item.target);
                 throw error;
             }
             applied.push(item);
@@ -803,9 +1072,9 @@ async function commitOutputs(integration, staged, signal) {
     }
     catch (error) {
         for (const item of [...applied].reverse()) {
-            await rm(item.client.out, { recursive: true, force: true });
+            await rm(item.target, { recursive: true, force: true });
             if (item.hadOutput)
-                await rename(item.backup, item.client.out);
+                await rename(item.backup, item.target);
         }
         throw error;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hops-ops/distributed",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "description": "Typed GraphQL client, causal replica, command runtime, and framework adapters for Distributed services",
   "type": "module",
   "license": "UNLICENSED",
@@ -79,7 +79,7 @@
     "typescript": "5.9.3"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.3.0"
   },
   "publishConfig": {
     "access": "public"