@tokamakdev/tok 0.1.1-beta.107 → 0.1.1-beta.114

package/dist/vite.mjs

@@ -1,213 +1,35 @@
-import { X509Certificate } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { normalizePath, } from "vite";
-import { openDevSocket } from "./dev-socket.mjs";
-/** Modules tried in order when the options name none. */
-const DEFAULT_MODULES = ["src/tokamak.ts", "src/tokamak.js"];
-/** Wrangler configuration files Cloudflare's plugin tries in order. */
-const WRANGLER_FILES = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
-const MIDDLEWARE_MODE_ERROR = "Vite is running in middleware mode, so tokamak cannot find the development server's address; tok dev needs Vite's own dev server";
-/** The module that defines the development Worker's native calls. */
-const NATIVE_CALLS = normalizePath(fileURLToPath(new URL("./native.mjs", import.meta.url)));
-/**
- * Reports the app's tokamak configuration, and the development server's
- * address, HTTPS certificate, Worker name and dev socket port, to `tok`, and
- * makes the entry Worker import `module` and export `TokamakEvents`. In
- * development, the entry Worker also defines native calls that reach the
- * device through the dev socket. Without `TOKAMAK_VITE_OUTPUT`, which `tok`
- * sets, it adds no hooks.
- */
-export function tokamak({ module, ...config } = {}) {
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { createNativeWorker } from "./native-worker.mjs";
+import { createClientPlugin } from "./client.mjs";
+/** Cloudflare's Vite integration, with a separate native worker when run by tok. */
+export function tokamak(options = {}, cloudflareOptions = {}) {
     const output = process.env.TOKAMAK_VITE_OUTPUT;
-    if (!output) {
-        return [];
+    if (output && cloudflareOptions.auxiliaryWorkers?.length) {
+        throw new Error("Tokamak hosts the main and native workers; additional auxiliary workers are not supported.");
     }
-    let file;
-    const events = import.meta.resolve("@tokamakdev/plugin/events");
-    /** The module that defines `TokamakEvents`. */
-    const entrypoint = normalizePath(fileURLToPath(new URL("./entrypoint.js", events)));
-    /** The module that holds event listeners. */
-    const registryFile = normalizePath(fileURLToPath(new URL("./registry.ts", events)));
-    /** The module IDs of each entry environment's inputs. */
-    const entryIds = new Map();
-    /** The entry environments whose input exports `TokamakEvents`. */
-    const exporting = new Set();
-    /** The development server's dev socket, once open. */
-    let devSocket;
-    const token = process.env.TOKAMAK_SESSION_TOKEN;
-    return [
-        {
-            name: "tokamak",
-            // Keeps @tokamakdev/plugin out of pre-bundled dependencies, so they
-            // share the one module that holds event listeners.
-            configEnvironment() {
-                return { optimizeDeps: { exclude: ["@tokamakdev/plugin"] } };
-            },
-            configResolved({ root }) {
-                file = findModule(root, module);
-                writeJson(output, "config.json", { root, config });
-            },
-            // Runs before plugins that load the entry Worker, whose native calls
-            // need the dev socket's port.
-            configureServer: {
-                order: "pre",
-                async handler(server) {
-                    const httpServer = server.httpServer;
-                    // A middleware-mode server beside a reported one, such as the server
-                    // Astro syncs content with, leaves the report in place.
-                    if (!httpServer) {
-                        if (!fs.existsSync(path.join(output, "server.json"))) {
-                            writeJson(output, "server.json", { error: MIDDLEWARE_MODE_ERROR });
-                        }
-                        return;
-                    }
-                    const worker = await readWorker(server.config.root);
-                    const socket = await openDevSocket(worker?.name, token);
-                    devSocket = socket;
-                    httpServer.once("close", () => void socket.close());
-                    httpServer.once("listening", () => {
-                        const urls = server.resolvedUrls;
-                        writeJson(output, "server.json", {
-                            url: urls?.local[0] ?? urls?.network[0],
-                            workerName: worker?.topLevelName ?? worker?.name,
-                            certificates: endEntityCertificates(server.config.server.https),
-                            socketPort: socket.port,
-                        });
-                    });
-                },
-            },
-            async buildApp(builder) {
-                const environments = Object.values(builder.environments);
-                if (!environments.some((environment) => buildsEntryWorker(environment.config))) {
-                    throw new Error("no environment builds the entry Worker to export TokamakEvents from");
-                }
-            },
-        },
-        {
-            name: "tokamak:entry",
-            applyToEnvironment: ({ config }) => buildsEntryWorker(config),
-            async transform(code, id) {
-                const environment = this.environment;
-                const ids = entryIds.get(environment.name) ??
-                    Promise.all(inputs(environment.config.build).map(async (input) => (await this.resolve(input))?.id));
-                entryIds.set(environment.name, ids);
-                if (!(await ids).includes(id)) {
-                    return;
-                }
-                exporting.add(environment.name);
-                // In Cloudflare's Worker entry, which dev and build both start from,
-                // this follows the imports of its polyfills and of the app's entry.
-                const imports = file ? `import ${JSON.stringify(file)};\n` : "";
-                const native = environment.mode === "dev" && devSocket && token ? nativeCalls(devSocket.port, token) : "";
-                return {
-                    code: `${code}\n${imports}export { TokamakEvents } from ${JSON.stringify(entrypoint)};\n${native}`,
-                    map: null,
+    const native = output ? createNativeWorker(options, output) : undefined;
+    const client = createClientPlugin(options.module, !!output, native ? () => native.graph().types : undefined);
+    return [...native ? [native.plugin] : [], client, ...cloudflare({
+            ...cloudflareOptions,
+            config(worker) {
+                const custom = typeof cloudflareOptions.config === "function"
+                    ? cloudflareOptions.config(worker)
+                    : cloudflareOptions.config;
+                const configured = {
+                    ...worker, ...custom,
+                    services: [...custom?.services ?? [], ...worker.services ?? []],
                 };
+                client.configure(configured);
+                if (!native)
+                    return custom;
+                const graph = native.graph();
+                graph.configure(configured);
+                // Cloudflare merges returned service entries with those already in the config.
+                return { ...custom, main: configured.main, services: [...custom?.services ?? [], ...graph.services(graph.names().main)] };
             },
-            // A module that registers listeners adds them again each time it
-            // evaluates, so when an update re-evaluates one, the registry and every
-            // module that imports it evaluate again too.
-            async hotUpdate({ modules, timestamp }) {
-                const graph = this.environment.moduleGraph;
-                const registry = graph.getModuleById(registryFile);
-                if (!registry) {
-                    return;
-                }
-                const entries = (await entryIds.get(this.environment.name)) ?? [];
-                const registering = [...withImporters(registry)].filter((module) => !entries.some((id) => id === module.id));
-                const updated = new Set(modules.flatMap((changed) => [...withImporters(changed)]));
-                if (registering.some((module) => updated.has(module))) {
-                    graph.invalidateModule(registry, new Set(), timestamp, true);
-                }
-            },
-            generateBundle() {
-                if (!exporting.has(this.environment.name)) {
-                    this.error(`the input of the ${this.environment.name} environment did not export TokamakEvents`);
-                }
-            },
-        },
-    ];
-}
-/**
- * Code that defines the development Worker's native calls on the dev socket's
- * `port`, with the session `token`, which only the entry Worker's environment
- * sees.
- */
-function nativeCalls(port, token) {
-    return `import { waitUntil as __tokamakWaitUntil } from "cloudflare:workers";
-import { defineNativeCalls as __tokamakDefineNativeCalls } from ${JSON.stringify(NATIVE_CALLS)};
-__tokamakDefineNativeCalls(${String(port)}, ${JSON.stringify(token)}, __tokamakWaitUntil);
-`;
-}
-/** `module` and every module that imports it, directly or through others. */
-function withImporters(module) {
-    const found = new Set();
-    const pending = [module];
-    for (let current = pending.pop(); current; current = pending.pop()) {
-        if (!found.has(current)) {
-            found.add(current);
-            pending.push(...current.importers);
-        }
-    }
-    return found;
-}
-/** The module `name` under `root`, or else the first default under `root` that exists. */
-function findModule(root, name) {
-    const candidates = (name ? [name] : DEFAULT_MODULES).map((candidate) => normalizePath(path.resolve(root, candidate)));
-    const file = candidates.find((candidate) => fs.existsSync(candidate));
-    if (name && !file) {
-        throw new Error(`tokamak module not found: ${candidates[0]}`);
-    }
-    return file;
-}
-/**
- * The Worker in the Wrangler configuration file in `root`, read as
- * Cloudflare's plugin reads it without `configPath`, in the `CLOUDFLARE_ENV`
- * environment: its name, and its name without the environment's suffix.
- */
-async function readWorker(root) {
-    const file = WRANGLER_FILES.map((name) => path.join(root, name)).find((candidate) => fs.existsSync(candidate));
-    if (!file) {
-        return undefined;
-    }
-    const { unstable_readConfig } = await import("wrangler");
-    return unstable_readConfig({ config: file, env: process.env.CLOUDFLARE_ENV }, { hideWarnings: true });
-}
-/**
- * The PEM of the end-entity certificate of each chain in `https.cert`, which
- * Vite reads from a file when a string names one.
- */
-function endEntityCertificates(https) {
-    const cert = typeof https?.cert === "string" ? readFileIfExists(https.cert) : https?.cert;
-    return cert && [cert].flat().map((chain) => new X509Certificate(chain).toString()).join("");
-}
-function readFileIfExists(file) {
-    try {
-        return fs.readFileSync(path.resolve(file));
-    }
-    catch {
-        return file;
-    }
-}
-/**
- * Whether an environment builds from the entry Worker: Cloudflare's plugin
- * gives a manifest to its entry and prerender Workers, and Astro to its server
- * and prerender environments.
- */
-function buildsEntryWorker(config) {
-    return config.consumer === "server" && Boolean(config.build.manifest);
-}
-/** The modules an environment's build starts from. */
-function inputs(build) {
-    const { input } = build.rollupOptions;
-    return typeof input === "string" ? [input] : Object.values(input ?? {});
-}
-/** Writes `value` to `name` whole, as `tok` reads the file as soon as it exists. */
-function writeJson(output, name, value) {
-    const file = path.join(output, name);
-    fs.mkdirSync(output, { recursive: true });
-    fs.writeFileSync(`${file}.tmp`, `${JSON.stringify(value, null, 2)}\n`);
-    fs.renameSync(`${file}.tmp`, file);
+            auxiliaryWorkers: native ? [{
+                    viteEnvironment: { name: "tokamak" },
+                    config: (worker, context) => native.graph().native(worker, context),
+                }] : cloudflareOptions.auxiliaryWorkers,
+        })];
 }

package/dist/worker-contract.d.mts

@@ -0,0 +1,25 @@
+import type { PluginDefinition } from "./plugin-manifest.mjs";
+/** The callable prototype methods and source dependencies of a Worker entrypoint. */
+export interface WorkerContract {
+    methods: string[];
+    files: string[];
+    declarations: string;
+}
+export interface PluginContract extends WorkerContract {
+    definition: PluginDefinition;
+    webMethods: string[];
+    /** Every operation of the native SDK, including those only the Tokamak worker can call. */
+    operations: string[];
+}
+export declare function findModule(root: string, name: string | undefined): string | undefined;
+/** Resolve the application's types before generating its service adapters. */
+export declare function readWorkerContract(entry: string, root: string): WorkerContract;
+/** Check every WorkerEntrypoint exported by an application service bundle. */
+export declare function readServiceContracts(entry: string, root: string): Record<string, WorkerContract>;
+/** Analyze both entrypoints in one TypeScript program. */
+export declare function readWorkerContracts(entry: string | undefined, main: string | undefined, root: string, validate: boolean, plugins?: PluginDefinition[]): {
+    native: WorkerContract;
+    named: Record<string, WorkerContract>;
+    main: Record<string, WorkerContract>;
+    plugins: PluginContract[];
+};

package/dist/worker-contract.mjs

@@ -0,0 +1,343 @@
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { checkRpcMethod, WorkerOnlyMethod } from "./rpc-contract.mjs";
+import { serviceTypes } from "./service-types.mjs";
+export function findModule(root, name) {
+    const candidates = (name ? [name] : ["src/tokamak.ts", "src/tokamak.js"])
+        .map(candidate => path.resolve(root, candidate).split(path.sep).join("/"));
+    const file = candidates.find(candidate => fs.existsSync(candidate));
+    if (name && !file)
+        throw new Error(`tokamak module not found: ${candidates[0]}`);
+    return file;
+}
+/** Resolve the application's types before generating its service adapters. */
+export function readWorkerContract(entry, root) {
+    return readWorkerContracts(entry, undefined, root, true).native;
+}
+/** Check every WorkerEntrypoint exported by an application service bundle. */
+export function readServiceContracts(entry, root) {
+    return readWorkerContracts(undefined, entry, root, true).main;
+}
+/** Analyze both entrypoints in one TypeScript program. */
+export function readWorkerContracts(entry, main, root, validate, plugins = []) {
+    const entries = [entry, main, ...plugins.flatMap(plugin => [plugin.api.module, plugin.web?.module])]
+        .filter((file) => !!file);
+    const project = entries.length ? workerProgram(entries, root) : undefined;
+    const native = entry && project ? workerModule(entry, project) : undefined;
+    return {
+        native: native ? classContract(native, "default", true, validate)
+            : { methods: [], files: [], declarations: serviceTypes("{}", []) },
+        named: native ? namedContracts(native, validate) : {},
+        main: main && project ? serviceContracts(workerModule(main, project), validate) : {},
+        plugins: project ? plugins.map(plugin => pluginContract(workerModule(plugin.api.module, project), plugin, validate)) : [],
+    };
+}
+/** The Tokamak worker's named entrypoints: its other exported concrete entrypoint classes. */
+function namedContracts(module, validate) {
+    const contracts = {};
+    for (const [name, type] of module.exports) {
+        const instance = type.getConstructSignatures()[0]?.getReturnType();
+        const abstract = instance?.symbol?.declarations?.some(node => ts.getModifiers(node)?.some(modifier => modifier.kind === ts.SyntaxKind.AbstractKeyword));
+        if (name === "default" || !instance || abstract ||
+            !applicationPrototypes(module.program, module.checker, instance, module.entry, true))
+            continue;
+        if (name === "TokamakEvents" || name.startsWith("TOKAMAK_")) {
+            throw new Error(`Tokamak entrypoint ${name} has a name the generated worker reserves.`);
+        }
+        contracts[name] = classContract(module, name, true, validate);
+    }
+    return contracts;
+}
+function serviceContracts(module, validate) {
+    const { entry } = module;
+    const contracts = {};
+    for (const [name, type] of module.exports) {
+        const instance = type.getConstructSignatures()[0]?.getReturnType();
+        if (instance && applicationPrototypes(module.program, module.checker, instance, entry)) {
+            contracts[name] = classContract(module, name, false, validate);
+        }
+        else if (name === "default" && (type.flags & ts.TypeFlags.Object) && !type.getCallSignatures().length && !instance) {
+            contracts[name] = { methods: [], files: module.files, declarations: serviceTypes("{}", [], "Main") };
+        }
+        else if (name === "default") {
+            throw new Error(`Service entrypoint ${entry} must export a handler object or extend WorkerEntrypoint.`);
+        }
+    }
+    return contracts;
+}
+function workerProgram(entries, root) {
+    const config = projectConfig(root);
+    const modules = new Map(entries.map(entry => [entry,
+        ts.resolveModuleName(entry, path.join(root, "tokamak.ts"), config.options, ts.sys).resolvedModule?.resolvedFileName ?? entry,
+    ]));
+    const program = ts.createProgram({
+        rootNames: [...new Set([...modules.values(), ...config.fileNames.filter((file) => /\.d\.[cm]?ts$/.test(file))])],
+        options: config.options,
+        projectReferences: config.projectReferences,
+    });
+    const syntax = program.getSyntacticDiagnostics();
+    if (syntax.length)
+        throw diagnostics(syntax);
+    const checker = program.getTypeChecker();
+    const files = [...new Set([
+            ...entries,
+            ...config.configFiles,
+            ...program.getSourceFiles().filter((file) => !program.isSourceFileDefaultLibrary(file)).map((file) => file.fileName),
+        ])].sort();
+    return { program, checker, files, modules };
+}
+function workerModule(entry, project) {
+    const { program, checker } = project;
+    const source = program.getSourceFile(project.modules.get(entry) ?? entry);
+    if (!source)
+        throw new Error(`Cannot read Tokamak entrypoint ${entry}.`);
+    const module = checker.getSymbolAtLocation(source);
+    const exports = new Map((module ? checker.getExportsOfModule(module) : []).map(exported => {
+        const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+        return [exported.name, checker.getTypeOfSymbolAtLocation(symbol, source)];
+    }));
+    return { ...project, entry, source, exports };
+}
+function pluginContract(module, definition, validate) {
+    const { checker, program, source } = module;
+    const signatures = module.exports.get(definition.api.export)?.getCallSignatures() ?? [];
+    const signature = signatures[0];
+    const parameter = signature?.parameters[0];
+    const parameterType = parameter && checker.getTypeOfSymbol(parameter);
+    const symbol = nativeSdkExport(program, checker, module.entry, "TokamakContext");
+    const context = symbol && checker.getDeclaredTypeOfSymbol(symbol);
+    if (signatures.length !== 1 || signature.typeParameters?.length || signature.parameters.length !== 1 ||
+        !parameterType || parameterType.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown) || !context ||
+        !checker.isTypeAssignableTo(parameterType, context) || !checker.isTypeAssignableTo(context, parameterType)) {
+        throw new Error(`Plugin ${definition.id} factory must accept one TokamakContext.`);
+    }
+    const api = signature.getReturnType();
+    if (!apiObject(checker, api)) {
+        throw new Error(`Plugin ${definition.id} factory must return a synchronous object with declared methods.`);
+    }
+    const reference = nativeSdkExport(program, checker, module.entry, "NativeReference", "@tokamakdev/plugin");
+    const methods = [];
+    const operations = [];
+    for (const property of api.getProperties()) {
+        if (privateProperty(property))
+            continue;
+        if (property.name === "capabilities")
+            continue;
+        assertMethodName(property.name);
+        if (["fetch", "event", "queue", "scheduled", "email", "tail", "trace", "tailStream", "test"].includes(property.name)) {
+            throw new Error(`Plugin method ${property.name} is reserved for a Worker handler.`);
+        }
+        const method = checker.getTypeOfSymbolAtLocation(property, source);
+        if (!method.getCallSignatures().length || String(property.escapedName).startsWith("__@")) {
+            throw new Error(`Plugin ${definition.id}.${property.name} must be a method.`);
+        }
+        operations.push(property.name);
+        try {
+            checkRpcMethod(checker, method, `${definition.id}.${property.name}`, reference);
+        }
+        catch (error) {
+            // Methods that pass native references are available only in the Tokamak worker.
+            if (error instanceof WorkerOnlyMethod)
+                continue;
+            if (validate)
+                throw error;
+        }
+        methods.push(methodDeclaration(checker, property, method));
+    }
+    methods.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    const unknown = Object.keys(definition.operations).find(name => !operations.includes(name));
+    if (unknown)
+        throw new Error(`${definition.manifest}: operations.${unknown} names no method of ${definition.api.export}.`);
+    const webMethods = browserMethods(module, definition, methods, validate);
+    for (const method of methods) {
+        method.documentation = [method.documentation, availability(definition, method.name, webMethods.includes(method.name))]
+            .filter(Boolean).join("\n\n");
+    }
+    return {
+        definition, methods: methods.map(method => method.name), files: [...module.files, definition.manifest],
+        webMethods, operations: operations.sort(),
+        declarations: serviceTypes(`ReturnType<typeof import(${JSON.stringify(definition.api.module)}, { with: { "resolution-mode": "import" } })[${JSON.stringify(definition.api.export)}]>`, methods),
+    };
+}
+const platformNames = {
+    ios: "iOS", macos: "macOS", android: "Android", windows: "Windows", linux: "Linux",
+};
+/** Where the operation `name` is implemented, and what it needs there, for editor documentation. */
+function availability(definition, name, web) {
+    const operation = definition.operations[name];
+    const platforms = operation?.platforms ?? definition.platforms.map(platform => ({ name: platform, minimum: undefined }));
+    const native = platforms.map(({ name, minimum }) => {
+        const version = name === "android" ? `API ${minimum ?? ""}` : minimum;
+        return minimum ? `${platformNames[name]} ${version}+` : platformNames[name];
+    });
+    const foreground = operation?.foreground.map(platform => platformNames[platform]) ?? [];
+    return [
+        `Native: ${native.join(", ") || "none"}. Web: ${web ? "browser implementation" : "not supported"}.`,
+        foreground.length ? `May need the app in the foreground on ${foreground.join(", ")}, to show UI.` : "",
+    ].filter(Boolean).join(" ");
+}
+function browserMethods(project, definition, methods, validate) {
+    if (!definition.web)
+        return [];
+    const { checker } = project;
+    const module = workerModule(definition.web.module, project);
+    const api = module.exports.get(definition.web.export);
+    if (!api || !apiObject(checker, api)) {
+        throw new Error(`Plugin ${definition.id} web export must be an object implementing its frontend methods.`);
+    }
+    const clientModule = checker.getAmbientModules().find(symbol => symbol.name === JSON.stringify(definition.client));
+    const clientSymbol = clientModule && checker.getExportsOfModule(clientModule).find(symbol => symbol.name === "TokamakClient");
+    const client = clientSymbol && checker.getDeclaredTypeOfSymbol(clientSymbol);
+    return api.getProperties().filter(property => !privateProperty(property)).map(property => {
+        const method = methods.find(method => method.name === property.name);
+        if (!method)
+            throw new Error(`Plugin ${definition.id} web method ${property.name} has no native API method.`);
+        if (validate) {
+            const expected = client?.getProperty(property.name);
+            const actual = checker.getTypeOfSymbolAtLocation(property, module.source);
+            checkRpcMethod(checker, actual, `${definition.id}.web.${property.name}`);
+            if (!expected || !checker.isTypeAssignableTo(actual, checker.getTypeOfSymbol(expected))) {
+                throw new Error(`Plugin ${definition.id} web method ${property.name} must implement its generated asynchronous frontend signature.`);
+            }
+        }
+        return property.name;
+    }).sort();
+}
+function privateProperty(property) {
+    return property.declarations?.some(node => {
+        const name = node.name;
+        return Boolean(ts.getCombinedModifierFlags(node) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected)) ||
+            Boolean(name && ts.isPrivateIdentifier(name));
+    }) ?? false;
+}
+function apiObject(checker, type) {
+    if (type.isUnionOrIntersection())
+        return type.types.every(member => apiObject(checker, member));
+    return Boolean(type.flags & ts.TypeFlags.Object) && !type.getCallSignatures().length &&
+        !type.getConstructSignatures().length && !type.getProperty("then") && !checker.getIndexInfosOfType(type).length;
+}
+function classContract(module, name, native, validate) {
+    const { entry, program, checker, source } = module;
+    const constructor = module.exports.get(name)?.getConstructSignatures()[0];
+    const instance = constructor?.getReturnType();
+    const declarations = instance?.symbol?.declarations ?? [];
+    const concrete = declarations.some((node) => (ts.isClassDeclaration(node) || ts.isClassExpression(node)) &&
+        !ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.AbstractKeyword));
+    if (!instance || !concrete || constructor?.typeParameters?.length) {
+        throw new Error(name === "default" ? `Tokamak entrypoint ${entry} must default-export a concrete class.`
+            : `Tokamak entrypoint ${name} must be a concrete class.`);
+    }
+    const prototypes = applicationPrototypes(program, checker, instance, entry, native);
+    if (!prototypes) {
+        throw new Error(`Tokamak entrypoint ${entry} must extend TokamakEntrypoint from @tokamakdev/tok or WorkerEntrypoint from cloudflare:workers; include its type declarations.`);
+    }
+    const methods = [];
+    for (const property of instance.getProperties()) {
+        if (!property.declarations?.some((node) => prototypes.has(node.parent)))
+            continue;
+        if (!exposedMethod(property))
+            continue;
+        const type = checker.getTypeOfSymbolAtLocation(property, source);
+        if (validate)
+            checkRpcMethod(checker, type, property.name);
+        methods.push(methodDeclaration(checker, property, type));
+    }
+    methods.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    return {
+        methods: methods.map((method) => method.name),
+        declarations: serviceTypes(`InstanceType<typeof import(${JSON.stringify(entry.split(path.sep).join("/"))}, { with: { "resolution-mode": "import" } })[${JSON.stringify(name)}]>`, methods, native ? "Tokamak" : "Main"),
+        files: module.files,
+    };
+}
+function methodDeclaration(checker, property, type) {
+    return {
+        name: property.name,
+        overloads: type.getCallSignatures().length,
+        documentation: [
+            ts.displayPartsToString(property.getDocumentationComment(checker)),
+            ...property.getJsDocTags(checker).map(tag => `@${tag.name} ${ts.displayPartsToString(tag.text)}`.trim()),
+        ].filter(Boolean).join("\n"),
+    };
+}
+function applicationPrototypes(program, checker, instance, entry, allowNative = false) {
+    const module = checker.getAmbientModules().find((symbol) => symbol.name === '"cloudflare:workers"');
+    const exported = module && checker.getExportsOfModule(module).find((symbol) => symbol.name === "WorkerEntrypoint");
+    const base = exported && (exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported);
+    const native = allowNative ? nativeSdkExport(program, checker, entry, "TokamakEntrypoint") : undefined;
+    const prototypes = new Set();
+    let current = instance;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        const symbol = current.getSymbol();
+        if (symbol && (symbol === base || symbol === native))
+            return prototypes;
+        seen.add(current);
+        for (const node of current.getSymbol()?.declarations ?? [])
+            prototypes.add(node);
+        current = checker.getBaseTypes(current)?.[0];
+    }
+    return undefined;
+}
+/** The symbol `name` exported by the core SDK module `specifier`, which `@tokamakdev/tok` uses for `entry`. */
+function nativeSdkExport(program, checker, entry, name, specifier = "@tokamakdev/plugin/worker") {
+    const options = program.getCompilerOptions();
+    const sdk = ts.resolveModuleName("@tokamakdev/tok", entry, options, ts.sys).resolvedModule?.resolvedFileName;
+    const resolved = ts.resolveModuleName(specifier, sdk ?? fileURLToPath(import.meta.url), options, ts.sys).resolvedModule;
+    const source = resolved && program.getSourceFile(resolved.resolvedFileName);
+    const module = source && checker.getSymbolAtLocation(source);
+    const exported = module && checker.getExportsOfModule(module).find(symbol => symbol.name === name);
+    return exported && (exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported);
+}
+function exposedMethod(property) {
+    const declarations = property.declarations?.filter(ts.isMethodDeclaration) ?? [];
+    if (!declarations.length || declarations.some((node) => ts.isPrivateIdentifier(node.name)) ||
+        String(property.escapedName).startsWith("__@"))
+        return false;
+    if (declarations.some((node) => ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.PrivateKeyword || modifier.kind === ts.SyntaxKind.ProtectedKeyword))) {
+        throw new Error(`Method ${property.name} is on the public JavaScript prototype; use a #private method for a local helper.`);
+    }
+    assertMethodName(property.name);
+    return !["fetch", "event", "queue", "scheduled", "email", "tail", "trace", "tailStream", "test"].includes(property.name);
+}
+function assertMethodName(name) {
+    if (["then", "connect", "dup", "constructor", "alarm", "webSocketMessage", "webSocketClose", "webSocketError", "__tokamakRpc"].includes(name)) {
+        throw new Error(`Method ${name} is reserved by the service binding contract.`);
+    }
+}
+function projectConfig(root) {
+    const configFiles = [];
+    const host = {
+        ...ts.sys,
+        readFile(file) { configFiles.push(file); return ts.sys.readFile(file); },
+    };
+    const file = ts.findConfigFile(root, ts.sys.fileExists);
+    const loaded = file ? ts.readConfigFile(file, host.readFile) : { config: {} };
+    if (loaded.error)
+        throw diagnostics([loaded.error]);
+    const config = ts.parseJsonConfigFileContent(loaded.config, host, file ? path.dirname(file) : root, undefined, file);
+    // An explicit entrypoint can live outside a project's include patterns.
+    const errors = config.errors.filter((error) => error.code !== 18003);
+    if (errors.length)
+        throw diagnostics(errors);
+    config.options = {
+        target: ts.ScriptTarget.ES2023,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        strict: true,
+        types: [],
+        ...config.options,
+        allowJs: true,
+        checkJs: true,
+        noEmit: true,
+    };
+    return { ...config, configFiles };
+}
+function diagnostics(errors) {
+    return new Error(ts.formatDiagnostics(errors, {
+        getCanonicalFileName: (name) => name,
+        getCurrentDirectory: ts.sys.getCurrentDirectory,
+        getNewLine: () => "\n",
+    }));
+}

package/dist/worker-graph.d.mts

@@ -0,0 +1,43 @@
+import type { PluginConfig } from "@cloudflare/vite-plugin";
+import { type EnvironmentOptions, type Plugin } from "vite";
+import type { Availability, NativePlatform } from "@tokamakdev/plugin/capabilities";
+import type { WorkerContract } from "./worker-contract.mjs";
+import { WorkerTypes, type WorkerConfiguration } from "./worker-types.mjs";
+type ServiceConfiguration = Pick<WorkerConfiguration, "name" | "topLevelName" | "services" | "main" | "configPath" | "vars" | "kv_namespaces" | "d1_databases" | "r2_buckets">;
+type Auxiliary = NonNullable<PluginConfig["auxiliaryWorkers"]>[number];
+type AuxiliaryCustomizer = Extract<Extract<Auxiliary, {
+    config: unknown;
+}>["config"], (...args: never[]) => unknown>;
+export interface WorkerGraph {
+    generated: string;
+    /** Connects development invocations to a device on `platform` through the relay on `port`. */
+    relay(port: number, token: string, platform: NativePlatform | undefined): void;
+    /** Each plugin operation's native platforms, by plugin ID. */
+    availability(): Availability;
+    configure(config: ServiceConfiguration): void;
+    services(name: string): NonNullable<ServiceConfiguration["services"]>;
+    native: AuxiliaryCustomizer;
+    names(): {
+        main: string;
+        native: string;
+        app: string;
+    };
+    contract(): WorkerContract;
+    types: WorkerTypes;
+    cloudflare: PluginConfig;
+    plugin: Plugin & {
+        config: Extract<Plugin["config"], (...args: never[]) => unknown>;
+        configEnvironment: {
+            order: "post";
+            handler(name: string, config: EnvironmentOptions): EnvironmentOptions;
+        };
+        buildStart: Extract<Plugin["buildStart"], (...args: never[]) => unknown>;
+        hotUpdate: Extract<Plugin["hotUpdate"], (...args: never[]) => unknown>;
+        resolveId: Extract<Plugin["resolveId"], (...args: never[]) => unknown>;
+        load: Extract<Plugin["load"], (...args: never[]) => unknown>;
+    };
+}
+/** Configure the two bundles through Cloudflare's public auxiliary-worker API. */
+export declare function createWorkerGraph(root: string, entry: string | undefined, output: string): WorkerGraph;
+export declare function workerName(main: string): string;
+export {};