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

package/README.md

@@ -11,29 +11,119 @@ npx tok targets
 
 | Entry | Contents |
 | --- | --- |
-| `@tokamakdev/tok` | The `Config` type of the Vite plugin's options |
+| `@tokamakdev/tok` | `TokamakEntrypoint`, `TokamakContext`, `TokamakEvent`, and the Vite plugin's `Config` type |
 | `@tokamakdev/tok/events` | The app's events, `onStart`, `onResume` and `onSuspend`, and `getLifecycleStage()` |
 | `@tokamakdev/tok/vite` | The Vite plugin, `tokamak()` |
+| `@tokamakdev/tok/astro` | The Astro adapter, `tokamak()` |
 | `tok` | The CLI |
 
-The Vite plugin goes next to Cloudflare's, and its options are the app's
-tokamak configuration:
+Create a plugin with `tok plugin my-plugin`. It starts as a TypeScript package
+composing native context APIs. Add `--native apple` or `--native android` for a
+small Swift or Kotlin implementation. Install it in an app as a workspace or
+local npm dependency; Tokamak generates its clients and service bindings.
+The generated README covers checking, local development, packing and publishing.
+
+The Vite integration includes Cloudflare's plugin. Its options are the app's
+tokamak configuration; the second argument accepts Cloudflare plugin options:
 
 ```ts
-import { cloudflare } from "@cloudflare/vite-plugin";
 import { tokamak } from "@tokamakdev/tok/vite";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-  plugins: [cloudflare(), tokamak({ name: "My App", version: "1.0.0" })],
+  plugins: [tokamak({ name: "My App", version: "1.0.0" })],
 });
 ```
 
-It does nothing unless `tok` runs the build or development command. Then it
-makes the entry Worker import `src/tokamak.ts` and export the entrypoint the
-runtime delivers events through. In development it delivers the device's
-events to the development Worker through Cloudflare's dev registry, and passes
-the development Worker's plugin calls to the device.
+In Astro, use `tokamak()` from `@tokamakdev/tok/astro` as the `adapter`, passing
+Cloudflare adapter options as the second argument.
+
+Web builds use the ordinary Cloudflare integration. When `tok` runs the
+command, `src/tokamak.ts` becomes a separate native worker. Its default export
+extends `TokamakEntrypoint`; public methods are checked against Tokamak's
+RPC contract. The main worker calls it through `env.TOKAMAK`; the native worker
+calls the main worker through `env.MAIN`. Development delivers native events
+through Cloudflare's dev registry and gives only the native worker the device
+relay. Vite reloads its modules and listeners when their source changes.
+Run `wrangler types` to generate the project's Workers declarations before
+building or starting development.
+
+Tokamak generates `tokamak-env.d.ts` in the project root, refreshing it during
+development. Include it in the project's TypeScript inputs alongside
+`worker-configuration.d.ts`, and ignore the generated file in version control.
+It adds the optional
+`Cloudflare.Env.TOKAMAK` binding and exports `TokamakService` and `TokamakClient`
+types from `virtual:tokamak/client`. Service methods return ordinary promises,
+preserve the entrypoint's overloads, and expose only its public RPC operations.
+`Tokamak.Env` describes the native worker's required `MAIN` service plus its
+shared variables, KV, D1, and R2 bindings. `this.env` in a `TokamakEntrypoint`
+and the `env` argument of native listeners use this type.
+
+Workspace implementation and API-reference edits reload through Vite.
+Installing, removing, or renaming plugins requires restarting `tok dev` so the
+native shell and worker bindings use the same installed capabilities.
+
+Plugin packages declare their native API factory in `tokamak-plugin.json`:
+
+```json
+{
+  "schemaVersion": 2,
+  "id": "widgets",
+  "api": { "module": "./src/index.ts", "export": "widgets" }
+}
+```
+
+The factory accepts a `TokamakContext` from `@tokamakdev/plugin` and returns
+an object with typed public methods. Its module path is relative to the package.
+Published JavaScript can supply adjacent TypeScript declarations. Existing
+native platform sections and build settings remain in the same manifest.
+
+Installing the package generates `env.TOKAMAK_WIDGETS` and its named native
+entrypoint. Page code imports the generated default client from
+`<package-name>/client`; native code calls `widgets(ctx)` directly. Both callers
+use the same declared methods and RPC value contract. Workspace dependencies
+work without publishing, and API source edits reload through Vite.
+
+A plugin can add `"web": { "module": "./web.ts", "export": "web" }` to the
+manifest. That export is an object implementing any subset of its generated
+asynchronous client methods. The generator checks the signatures. Web clients
+use those implementations and reject omitted methods with `NotSupportedError`;
+native clients always call the native worker.
+
+Page code imports the generated client as the module's default export:
+
+```ts
+// src/tokamak.ts
+import { TokamakEntrypoint } from "@tokamakdev/tok";
+
+export default class Native extends TokamakEntrypoint {
+  greeting(name: string): string {
+    return `Hello, ${name}`;
+  }
+}
+```
+
+```ts
+// Page code
+import native from "virtual:tokamak/client";
+
+const message = await native.greeting("Ada");
+```
+
+Native clients call the Tokamak worker through the reserved `/_tokamak/app`
+route. The native worker also receives other requests under `/_tokamak/` in
+its `fetch` handler. Arguments and results support the RPC value and readable
+byte-stream contract. Stream cancellation reaches its producer, and leaving
+the page closes its calls. Web builds expose the same app-method names, rejecting calls with
+`NotSupportedError`. The client bundle contains the callable interface and
+transport.
+
+The entrypoint receives its own bindings in `this.env` and native invocation
+context in `this.ctx`. Its default `event()` runs registered listeners; an
+override receives `{ type, data }` and can return a reply or promise. Native
+events use this handler independently of page requests. `event()` is excluded
+from the service binding's public methods. Listener callbacks receive the same
+invocation context and register follow-up work with `ctx.waitUntil()`.
 
 The package installs the `tok` binary for the current machine through an
 optional dependency (`@tokamakdev/tok-darwin-arm64`, `-darwin-x64`,

package/dist/astro.d.mts

@@ -0,0 +1,5 @@
+import { type Options as CloudflareOptions } from "@astrojs/cloudflare";
+import type { AstroIntegration } from "astro";
+import { type TokamakOptions } from "./native-worker.mjs";
+/** Astro's Cloudflare adapter, with Tokamak's native worker and development relay. */
+export declare function tokamak(options?: TokamakOptions, cloudflareOptions?: CloudflareOptions): AstroIntegration;

package/dist/astro.mjs

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import cloudflare, {} from "@astrojs/cloudflare";
+import { sessionDrivers } from "astro/config";
+import { normalizePath } from "vite";
+import { experimental_readRawConfig, unstable_readConfig } from "wrangler";
+import { createNativeWorker } from "./native-worker.mjs";
+import { createClientPlugin } from "./client.mjs";
+/** Astro's Cloudflare adapter, with Tokamak's native worker and development relay. */
+export function tokamak(options = {}, cloudflareOptions = {}) {
+    const output = process.env.TOKAMAK_VITE_OUTPUT;
+    const client = createClientPlugin(options.module, !!output, output ? () => native.graph().types : undefined);
+    if (!output) {
+        const adapter = cloudflare(cloudflareOptions);
+        let sessionBinding;
+        return {
+            ...adapter,
+            hooks: {
+                ...adapter.hooks,
+                async "astro:config:setup"(context) {
+                    const types = {
+                        name: "tokamak:astro-types",
+                        config(vite) {
+                            const root = path.resolve(vite.root ?? process.cwd());
+                            const source = configuration(root, cloudflareOptions.configPath, false);
+                            const raw = source ? experimental_readRawConfig({ config: source }, { useRedirectIfAvailable: false }).rawConfig : {};
+                            const environment = process.env.CLOUDFLARE_ENV;
+                            const selected = source ? unstable_readConfig({ config: source, env: environment }, { hideWarnings: true }) : {};
+                            const main = (environment ? raw.env?.[environment]?.main : undefined)
+                                ?? raw.main ?? "@astrojs/cloudflare/entrypoints/server";
+                            client.configure({
+                                ...selected,
+                                // Type inspection needs the server source, not a client-optimized module.
+                                main: main === "@astrojs/cloudflare/entrypoints/server"
+                                    ? fileURLToPath(import.meta.resolve(main)) : main,
+                                kv_namespaces: [...selected.kv_namespaces ?? [], ...sessionBinding ? [{ binding: sessionBinding }] : []],
+                            });
+                        },
+                    };
+                    context.updateConfig({ vite: { plugins: [client, types] } });
+                    await adapter.hooks["astro:config:setup"]?.(context);
+                },
+                async "astro:config:done"(context) {
+                    await adapter.hooks["astro:config:done"]?.(context);
+                    const driver = context.config.session?.driver;
+                    const entry = typeof driver === "string" ? driver : driver?.entrypoint.toString();
+                    if (entry === "cloudflareKVBinding" || entry?.endsWith("cloudflare-kv-binding") ||
+                        entry === sessionDrivers.cloudflareKVBinding().entrypoint) {
+                        sessionBinding = cloudflareOptions.sessionKVBindingName ?? "SESSION";
+                    }
+                },
+            },
+        };
+    }
+    if (cloudflareOptions.auxiliaryWorkers?.length) {
+        throw new Error("Tokamak hosts the main and native workers; additional auxiliary workers are not supported.");
+    }
+    const generated = path.join(path.dirname(cloudflareOptions.configPath ?? "."), `.tokamak.${randomUUID()}.json`);
+    let generatedPath;
+    const cleanup = () => {
+        if (generatedPath)
+            fs.rmSync(generatedPath, { force: true });
+        process.off("exit", cleanup);
+    };
+    const servers = new Set();
+    const lifecycle = {
+        name: "tokamak:astro-config",
+        configureServer({ httpServer }) {
+            if (!httpServer)
+                return;
+            servers.add(httpServer);
+            httpServer.once("close", () => {
+                servers.delete(httpServer);
+                if (!servers.size)
+                    cleanup();
+            });
+        },
+        buildEnd(error) {
+            if (error && this.environment.mode === "build")
+                cleanup();
+        },
+    };
+    const native = createNativeWorker(options, output, (root, graph) => {
+        const source = configuration(root, cloudflareOptions.configPath);
+        generatedPath = path.resolve(root, generated);
+        const rawConfig = experimental_readRawConfig({ config: source }, { useRedirectIfAvailable: false }).rawConfig;
+        const environment = process.env.CLOUDFLARE_ENV;
+        const selected = unstable_readConfig({ config: source, env: environment }, { hideWarnings: true });
+        selected.main = (environment ? rawConfig.env?.[environment]?.main : undefined)
+            ?? rawConfig.main ?? "@astrojs/cloudflare/entrypoints/server";
+        const main = selected.main;
+        graph.configure(selected);
+        const environments = [[undefined, rawConfig], ...Object.entries(rawConfig.env ?? {})];
+        for (const [env, config] of environments) {
+            const resolved = unstable_readConfig({ config: source, env }, { hideWarnings: true });
+            if (!resolved.name)
+                throw new Error("Tokamak requires a name in the main Worker's configuration.");
+            const services = graph.services(resolved.name);
+            const reserved = config.services?.find(binding => services.some(service => service.binding === binding.binding));
+            if (reserved) {
+                throw new Error(`${reserved.binding} is reserved for a generated native worker binding.`);
+            }
+            config.services = [...config.services ?? [], ...services];
+            if (selected.main !== main)
+                config.main = selected.main;
+        }
+        // Keeping the generated configuration beside its source preserves relative paths and .dev.vars.
+        const content = `${JSON.stringify(rawConfig, null, 2)}\n`;
+        if (!fs.existsSync(generatedPath) || fs.readFileSync(generatedPath, "utf8") !== content) {
+            fs.writeFileSync(generatedPath, content);
+        }
+        process.off("exit", cleanup);
+        process.once("exit", cleanup);
+    });
+    const adapter = cloudflare({
+        ...cloudflareOptions,
+        configPath: generated,
+        auxiliaryWorkers: [{
+                viteEnvironment: { name: "tokamak" },
+                config: (worker, context) => native.graph().native(worker, context),
+            }],
+    });
+    return {
+        ...adapter,
+        name: "@tokamakdev/tok/astro",
+        hooks: {
+            ...adapter.hooks,
+            async "astro:config:setup"(context) {
+                const source = configuration(fileURLToPath(context.config.root), cloudflareOptions.configPath);
+                context.addWatchFile(pathToFileURL(source));
+                context.updateConfig({
+                    vite: {
+                        server: { fs: { deny: [normalizePath(source)] } },
+                        plugins: [native.plugin, client, lifecycle],
+                    },
+                });
+                await adapter.hooks["astro:config:setup"]?.(context);
+            },
+            async "astro:build:done"(context) {
+                try {
+                    await adapter.hooks["astro:build:done"]?.(context);
+                }
+                finally {
+                    cleanup();
+                }
+            },
+        },
+    };
+}
+function configuration(root, configured, required = true) {
+    if (configured)
+        return path.resolve(root, configured);
+    const file = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"]
+        .map(name => path.join(root, name)).find(file => fs.existsSync(file));
+    if (!file && required)
+        throw new Error("Tokamak requires a Wrangler configuration in the Astro project root.");
+    return file;
+}

package/dist/client.d.mts

@@ -0,0 +1,6 @@
+import { type Plugin } from "vite";
+import { WorkerTypes, type BindingConfiguration } from "./worker-types.mjs";
+/** The app's public methods, without its native implementation. */
+export declare function createClientPlugin(module: string | undefined, native: boolean, shared?: () => WorkerTypes): Plugin & {
+    configure(config: BindingConfiguration): void;
+};

package/dist/client.mjs

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { normalizePath } from "vite";
+import { findModule } from "./worker-contract.mjs";
+import { WorkerTypes } from "./worker-types.mjs";
+const MODULE = "virtual:tokamak/client";
+/** The Tokamak worker's page module of each plugin operation's support on the app's platform. */
+const CAPABILITIES = "/_tokamak/capabilities.js";
+const TRANSPORT = normalizePath(fileURLToPath(new URL("./rpc/client.mjs", import.meta.resolve("@tokamakdev/plugin/events"))));
+/** The app's public methods, without its native implementation. */
+export function createClientPlugin(module, native, shared) {
+    let root;
+    /** Whether `id` is a generated client: the app's, a named entrypoint's or a plugin's. */
+    const isClient = (id) => id === MODULE || id.startsWith(`${MODULE}/`) ||
+        contracts.definitions.some(plugin => plugin.client === id);
+    let contracts;
+    let files = [];
+    const clients = new Set();
+    return {
+        name: "tokamak:client",
+        enforce: "pre",
+        config(config) {
+            clients.clear();
+            files = [];
+            root = path.resolve(config.root ?? process.cwd());
+            contracts = shared?.() ?? new WorkerTypes(root, findModule(root, module));
+        },
+        configure(config) { contracts.configure(config); },
+        buildStart() {
+            for (const file of contracts.metadata)
+                this.addWatchFile(file);
+        },
+        resolveId(id) {
+            if (id === CAPABILITIES)
+                return { id, external: true };
+            if (isClient(id))
+                return `\0${id}`;
+        },
+        async load(id) {
+            const name = id.slice(1);
+            if (!id.startsWith("\0") || !isClient(name))
+                return;
+            await contracts.resolve(source => this.resolve(source, undefined, { skipSelf: true }));
+            const service = contracts.services().find(service => service.client === name);
+            if (!service)
+                throw new Error(`${name} names no Tokamak worker entrypoint.`);
+            clients.add(id);
+            files = [...contracts.native.files, ...contracts.plugins.flatMap(plugin => plugin.files)]
+                .filter(file => file !== normalizePath(path.join(root, "tokamak-env.d.ts")));
+            for (const file of files)
+                this.addWatchFile(file);
+            const methods = JSON.stringify(service.contract.methods);
+            const route = JSON.stringify(service.route);
+            const plugin = service.plugin;
+            if (native && plugin)
+                return `import { createClient } from ${JSON.stringify(TRANSPORT)};
+import capabilities from ${JSON.stringify(CAPABILITIES)};
+export default createClient(${methods}, ${route}, capabilities[${JSON.stringify(plugin.definition.id)}]);`;
+            // The app's own operations run wherever its Tokamak worker does.
+            if (native)
+                return `import { createClient } from ${JSON.stringify(TRANSPORT)};
+export default createClient(${methods}, ${route}, Object.fromEntries(${methods}.map(method => [method, true])));`;
+            const browser = plugin?.definition.web;
+            const fallback = browser
+                ? `import { ${JSON.stringify(browser.export)} as browser } from ${JSON.stringify(browser.module)};`
+                : "const browser = {};";
+            const webMethods = JSON.stringify(plugin?.webMethods ?? []);
+            return `${fallback}
+async function unavailable() { throw new DOMException("This operation requires a native app", "NotSupportedError"); }
+const supported = new Set(${webMethods});
+const client = Object.fromEntries(${methods}.map(method => [method, supported.has(method) ? (...args) => Promise.resolve().then(() => browser[method](...args)) : unavailable]));
+export default Object.assign(client, { capabilities: Object.freeze(Object.fromEntries(${methods}.map(method => [method, supported.has(method)]))) });`;
+        },
+        hotUpdate({ file, timestamp, server }) {
+            if (contracts.metadata.includes(file)) {
+                if (this.environment.name === "client") {
+                    try {
+                        contracts.discover();
+                    }
+                    catch (error) {
+                        server.config.logger.error(String(error));
+                        throw error;
+                    }
+                    void server.restart().catch(error => server.config.logger.error(String(error)));
+                }
+                return [];
+            }
+            if (!files.includes(file))
+                return;
+            contracts.refresh({ file, timestamp });
+            for (const id of clients) {
+                const client = this.environment.moduleGraph.getModuleById(id);
+                if (!client)
+                    continue;
+                this.environment.moduleGraph.invalidateModule(client);
+                this.environment.hot.send({ type: "full-reload" });
+            }
+        },
+    };
+}

package/dist/dev-socket.d.mts

@@ -1,12 +1,9 @@
 /** The header that carries the device's session token, which `tok dev`'s relay forwards. */
 export declare const SESSION_HEADER = "x-tokamak-session";
-/** A plugin's result, as the page's native transport receives it. */
+/** The native endpoint's opaque result and completion status. */
 export interface PluginResult {
-    value?: unknown;
-    error?: {
-        name: string;
-        message: string;
-    };
+    payload: Uint8Array;
+    failed: boolean;
     done: boolean;
 }
 /** The loopback server the device's dev WebSocket reaches through `tok dev`'s relay. */