@tokamakdev/tok 0.1.1-beta.126 → 0.1.1-beta.128

package/dist/plugin-manifest.d.mts

@@ -4,16 +4,6 @@ export interface ModuleExport {
     module: string;
     export: string;
 }
-/** Where an operation runs, and what it needs there. */
-export interface Operation {
-    /** The native platforms that implement it, with any minimum OS version. */
-    platforms: {
-        name: NativePlatform;
-        minimum?: string;
-    }[];
-    /** The native platforms where it needs the app in the foreground, to show UI. */
-    foreground: NativePlatform[];
-}
 export interface PluginDefinition {
     id: string;
     package: string;
@@ -24,8 +14,6 @@ export interface PluginDefinition {
     client: string;
     /** The native platforms the plugin builds for. */
     platforms: NativePlatform[];
-    /** Each operation the manifest describes; others run on every platform the plugin builds for. */
-    operations: Record<string, Operation>;
 }
 /** Installed direct dependencies select the application's plugin services. */
 export declare function discoverPlugins(root: string): PluginDefinition[];

package/dist/plugin-manifest.mjs

@@ -35,6 +35,9 @@ export function discoverPlugins(root) {
         const reserved = reservedIds.find(word => data.id === word || data.id.startsWith(`${word}-`));
         if (reserved)
             throw new Error(`${manifest}: plugin id must not start with '${reserved}', which Tokamak's options use.`);
+        if (data.operations !== undefined) {
+            throw new Error(`${manifest}: operations is no longer read; tag a method that only some platforms implement with @platforms in its doc comment.`);
+        }
         const api = moduleExport(directory, data.api, "api");
         if (plugins.has(data.id))
             throw new Error(`Duplicate Tokamak plugin id ${data.id}.`);
@@ -45,7 +48,6 @@ export function discoverPlugins(root) {
             binding: `TOKAMAK_${data.id.toUpperCase().replaceAll("-", "_")}`,
             client: `${name}/client`,
             platforms,
-            operations: operations(manifest, data.operations ?? {}, platforms),
         });
     }
     return [...plugins.values()].sort((left, right) => left.id.localeCompare(right.id));
@@ -62,35 +64,3 @@ function moduleExport(root, reference, field) {
     }
     return { module: module.split(path.sep).join("/"), export: value.export };
 }
-/** The manifest's `operations`, each on platforms the plugin builds for. */
-function operations(manifest, value, built) {
-    const fail = (message) => { throw new Error(`${manifest}: ${message}`); };
-    const platform = (name, field) => built.includes(name) ? name : fail(`${field} names ${name}, which the plugin does not build for.`);
-    if (!isRecord(value))
-        return fail("operations must be an object.");
-    const result = {};
-    for (const [name, entry] of Object.entries(value)) {
-        const field = `operations.${name}`;
-        if (!isRecord(entry))
-            return fail(`${field} must be an object.`);
-        const { platforms, foreground = false, ...unknown } = entry;
-        if (Object.keys(unknown).length)
-            fail(`${field} has unknown keys: ${Object.keys(unknown).join(", ")}.`);
-        if (platforms !== undefined && (!isRecord(platforms) ||
-            !Object.values(platforms).every(version => typeof version === "string" || version === true))) {
-            fail(`${field}.platforms must map platforms to a minimum OS version, or true for the app's minimum.`);
-        }
-        if (typeof foreground !== "boolean" && !(Array.isArray(foreground) && foreground.every(name => typeof name === "string"))) {
-            fail(`${field}.foreground must be true or a list of platforms.`);
-        }
-        const implemented = platforms === undefined
-            ? built.map(name => ({ name }))
-            : Object.entries(platforms).map(([name, minimum]) => ({ name: platform(name, `${field}.platforms`), minimum: minimum === true ? undefined : minimum }));
-        const needs = foreground === true ? implemented.map(({ name }) => name) : foreground === false ? [] : foreground;
-        result[name] = { platforms: implemented, foreground: needs.map(name => platform(name, `${field}.foreground`)) };
-    }
-    return result;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/worker-contract.d.mts

@@ -1,4 +1,4 @@
-import type { PluginDefinition } from "./plugin-manifest.mjs";
+import type { NativePlatform, PluginDefinition } from "./plugin-manifest.mjs";
 /** The callable prototype methods and source dependencies of a Worker entrypoint. */
 export interface WorkerContract {
     methods: string[];
@@ -8,8 +8,11 @@ export interface WorkerContract {
 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[];
+    /**
+     * The native platforms that implement each operation of the native SDK, including those only the
+     * Tokamak worker can call.
+     */
+    operations: Record<string, NativePlatform[]>;
 }
 /** The contract of a Tokamak worker without a module. */
 export declare function emptyContract(): WorkerContract;

package/dist/worker-contract.mjs

@@ -123,7 +123,7 @@ function pluginContract(module, definition, validate) {
     }
     const reference = nativeSdkExport(program, checker, module.entry, "NativeReference", "@tokamakdev/plugin");
     const methods = [];
-    const operations = [];
+    const operations = {};
     for (const property of api.getProperties()) {
         if (privateProperty(property))
             continue;
@@ -137,7 +137,7 @@ function pluginContract(module, definition, validate) {
         if (!method.getCallSignatures().length || String(property.escapedName).startsWith("__@")) {
             throw new Error(`Plugin ${definition.id}.${property.name} must be a method.`);
         }
-        operations.push(property.name);
+        operations[property.name] = implementedOn(property, definition);
         try {
             checkRpcMethod(checker, method, `${definition.id}.${property.name}`, reference);
         }
@@ -148,39 +148,45 @@ function pluginContract(module, definition, validate) {
             if (validate)
                 throw error;
         }
-        methods.push(methodDeclaration(checker, property, method));
+        // Its `@platforms` tag becomes the availability line the documentation ends with.
+        methods.push(methodDeclaration(checker, property, method, ["platforms"]));
     }
     methods.sort(byName);
-    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))]
+        method.documentation = [method.documentation, availability(operations[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(),
+        webMethods, operations: Object.fromEntries(Object.entries(operations).sort(([left], [right]) => left.localeCompare(right))),
         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(" ");
+/** Where an operation is implemented, for editor documentation. */
+function availability(platforms, web) {
+    const native = platforms.map(platform => platformNames[platform]).join(", ") || "none";
+    return `Native: ${native}. Web: ${web ? "browser implementation" : "not supported"}.`;
+}
+/**
+ * The native platforms that implement the plugin method `property`: those the `@platforms` tag of
+ * its doc comment names, or every one the plugin builds for.
+ */
+function implementedOn(property, definition) {
+    const tag = property.declarations?.flatMap(node => ts.getJSDocTags(node)).find(({ tagName }) => tagName.text === "platforms");
+    if (!tag)
+        return definition.platforms;
+    const method = `Plugin ${definition.id}.${property.name}`;
+    const names = (ts.getTextOfJSDocComment(tag.comment) ?? "").split(/\s+/).filter(Boolean);
+    if (!names.length)
+        throw new Error(`${method}: @platforms names no platform.`);
+    const unknown = names.find(name => !definition.platforms.includes(name));
+    if (unknown)
+        throw new Error(`${method}: @platforms names ${unknown}, which the plugin does not build for (${definition.platforms.join(", ")}).`);
+    return names;
 }
 function browserMethods(project, definition, methods, validate) {
     if (!definition.web)
@@ -258,13 +264,15 @@ function classContract(module, name, native, validate) {
 function byName(left, right) {
     return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
 }
-function methodDeclaration(checker, property, type) {
+/** `property`'s declaration in generated service types, with its documentation apart from `consumed` tags. */
+function methodDeclaration(checker, property, type, consumed = []) {
     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()),
+            ...property.getJsDocTags(checker).filter(tag => !consumed.includes(tag.name))
+                .map(tag => `@${tag.name} ${ts.displayPartsToString(tag.text)}`.trim()),
         ].filter(Boolean).join("\n"),
     };
 }

package/dist/worker-graph.mjs

@@ -257,15 +257,9 @@ function nativeConnectionModule(relay) {
     return `import { connectDevice } from ${JSON.stringify(NATIVE_CALLS)};
 export const connect = ctx => connectDevice(${JSON.stringify(relay)}, ctx);`;
 }
-/** Each plugin operation's native platforms: those its manifest names, or every one the plugin builds for. */
+/** The native platforms of each plugin operation. */
 function availability(plugins) {
-    return Object.fromEntries(plugins.map(({ definition, operations }) => [
-        definition.id,
-        Object.fromEntries(operations.map(operation => [
-            operation,
-            definition.operations[operation]?.platforms.map(({ name }) => name) ?? definition.platforms,
-        ])),
-    ]));
+    return Object.fromEntries(plugins.map(({ definition, operations }) => [definition.id, operations]));
 }
 function serviceEntrypoint(entry, services) {
     const sdk = normalizePath(fileURLToPath(import.meta.resolve("@tokamakdev/plugin/worker")));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/tok",
-  "version": "0.1.1-beta.126",
+  "version": "0.1.1-beta.128",
   "description": "The tokamak CLI, Vite plugin and app API: build native apps from a Cloudflare Workers codebase",
   "repository": {
     "type": "git",
@@ -43,7 +43,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@tokamakdev/plugin": "0.1.0-beta.126",
+    "@tokamakdev/plugin": "0.1.0-beta.128",
     "typescript": "5.9.3",
     "ws": "^8.22.0"
   },
@@ -75,17 +75,17 @@
     "wrangler": "4.147.0"
   },
   "optionalDependencies": {
-    "@tokamakdev/platform-android-arm64": "0.1.1-beta.126",
-    "@tokamakdev/platform-ios-arm64": "0.1.1-beta.126",
-    "@tokamakdev/platform-ios-simulator-arm64": "0.1.1-beta.126",
-    "@tokamakdev/platform-ios-simulator-x64": "0.1.1-beta.126",
-    "@tokamakdev/platform-macos-arm64": "0.1.1-beta.126",
-    "@tokamakdev/platform-macos-x64": "0.1.1-beta.126",
-    "@tokamakdev/platform-windows-x64": "0.1.1-beta.126",
-    "@tokamakdev/tok-darwin-arm64": "0.1.1-beta.126",
-    "@tokamakdev/tok-darwin-x64": "0.1.1-beta.126",
-    "@tokamakdev/tok-linux-x64": "0.1.1-beta.126",
-    "@tokamakdev/tok-win32-x64": "0.1.1-beta.126"
+    "@tokamakdev/platform-android-arm64": "0.1.1-beta.128",
+    "@tokamakdev/platform-ios-arm64": "0.1.1-beta.128",
+    "@tokamakdev/platform-ios-simulator-arm64": "0.1.1-beta.128",
+    "@tokamakdev/platform-ios-simulator-x64": "0.1.1-beta.128",
+    "@tokamakdev/platform-macos-arm64": "0.1.1-beta.128",
+    "@tokamakdev/platform-macos-x64": "0.1.1-beta.128",
+    "@tokamakdev/platform-windows-x64": "0.1.1-beta.128",
+    "@tokamakdev/tok-darwin-arm64": "0.1.1-beta.128",
+    "@tokamakdev/tok-darwin-x64": "0.1.1-beta.128",
+    "@tokamakdev/tok-linux-x64": "0.1.1-beta.128",
+    "@tokamakdev/tok-win32-x64": "0.1.1-beta.128"
   },
   "publishConfig": {
     "access": "public"