From 65b6d538ae05b660a02723c92dd4780aefeae654 Mon Sep 17 00:00:00 2001 From: JustKira Date: Fri, 20 Nov 2026 17:43:20 +0200 Subject: [PATCH 1/3] TKM-175: Pack plugin builds into ZIP packages --- GLOSSARY.md | 4 ++ bun.lock | 5 ++ packages/build/src/artifact-bundle.ts | 2 + packages/build/src/ui-build-config.ts | 2 +- packages/build/src/vite.ts | 17 ++++--- packages/cli/README.md | 9 +++- packages/cli/package.json | 5 +- packages/cli/src/commands.ts | 2 + packages/cli/src/commands/build.ts | 16 ++---- packages/cli/src/commands/doctor.ts | 4 +- packages/cli/src/commands/pack.ts | 61 ++++++++++++++++++++++ packages/cli/src/plugin-build.ts | 30 +++++++++-- packages/cli/tests/cli-fixture.mjs | 6 +-- packages/cli/tests/cli.test.mjs | 67 +++++++++++++++++++++++-- packages/server/src/plugins/manifest.rs | 18 ++++--- packages/server/src/plugins/tests.rs | 13 +++++ packages/tokamak-version.ts | 5 ++ 17 files changed, 224 insertions(+), 42 deletions(-) create mode 100644 packages/cli/src/commands/pack.ts create mode 100644 packages/tokamak-version.ts diff --git a/GLOSSARY.md b/GLOSSARY.md index 53f1a7eb..4d67957f 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -40,6 +40,10 @@ _Avoid_: Hot swap, refresh, redeploy The window drops a plugin's views and mounts them again from the new code. The window itself stays open, and nothing inside the views is kept. _Avoid_: Refresh, window reload +**Package**: +One ZIP containing a built plugin’s manifest and the files it lists. +_Avoid_: Source archive + **Build id**: The SHA-256 of a built plugin's `manifest.json`. The manifest holds the hash of every other file, so the build id names one exact build. The version is only a label. _Avoid_: Revision, hash, version diff --git a/bun.lock b/bun.lock index 542e0b99..5ec6397c 100644 --- a/bun.lock +++ b/bun.lock @@ -67,6 +67,9 @@ "packages/cli": { "name": "@tokamak/cli", "version": "0.1.0", + "dependencies": { + "fflate": "0.8.3", + }, }, "packages/runtime": { "name": "@tokamak/runtime", @@ -900,6 +903,8 @@ "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="], + "fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="], + "flexsearch": ["flexsearch@0.8.212", "", {}, "sha512-wSyJr1GUWoOOIISRu+X2IXiOcVfg9qqBRyCPRUdLMIGJqPzMo+jMRlvE83t14v1j0dRMEaBbER/adQjp6Du2pw=="], "framer-motion": ["framer-motion@14.10.1", "", { "dependencies": { "motion-dom": "14.10.1", "motion-utils": "14.7.0", "tslib": "^2.4.0" }, "peerDependencies": { "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0", "remix": "^3.1.0" }, "optionalPeers": ["react", "react-dom", "remix"] }, "sha512-hT8WLczAcreOHG4EHymMtATztwUc3al1/88/stal3tpxYkMefGNzIPHHgFFHW3iLnrNY36BrKKJDuT2V7o8Tfw=="], diff --git a/packages/build/src/artifact-bundle.ts b/packages/build/src/artifact-bundle.ts index abc6fd6c..3c6a4f91 100644 --- a/packages/build/src/artifact-bundle.ts +++ b/packages/build/src/artifact-bundle.ts @@ -3,6 +3,7 @@ import { definePlugin, type PluginDefinition } from "@tokamak/sdk"; import { uiContributions } from "./contributions.ts"; import { createHash } from "node:crypto"; import type { Plugin } from "vite"; +import { tokamakVersion } from "../../tokamak-version"; type GenerateBundle = Extract, (...args: never[]) => unknown>; @@ -48,6 +49,7 @@ export function artifactBundle( ...(bundle["styles.css"] ? { css: "styles.css" } : {}), }; } + metadata.plugin = { ...metadata.plugin, api: `tokamak@${tokamakVersion()}` }; const hashes = bundleHashes(bundle); manifest.source = JSON.stringify({ ...metadata, hashes }, null, 2) + "\n"; }; diff --git a/packages/build/src/ui-build-config.ts b/packages/build/src/ui-build-config.ts index 0a59c6ed..a5cf5a66 100644 --- a/packages/build/src/ui-build-config.ts +++ b/packages/build/src/ui-build-config.ts @@ -23,7 +23,7 @@ export function uiBuildConfig(root: string): UserConfig { fileName: () => "ui.js", cssFileName: "styles", }, - rollupOptions: { output: { codeSplitting: false } }, + rollupOptions: { output: { codeSplitting: false, sourcemapExcludeSources: true } }, }, }; } diff --git a/packages/build/src/vite.ts b/packages/build/src/vite.ts index 82cb2fdd..4c71d44a 100644 --- a/packages/build/src/vite.ts +++ b/packages/build/src/vite.ts @@ -128,8 +128,8 @@ export function tokamak( const bundle = resolve(server, "dist/bundle.js"); const source = await readFile(bundle, "utf8"); const map = JSON.parse(await readFile(`${bundle}.map`, "utf8")); - // SDK maps are relative to the server half’s dist/. Rebase source names when the - // unchanged bundle is packaged into app/dist; retain original contents. + // Keep source locations for stack traces without shipping the original source. + delete map.sourcesContent; map.sources = map.sources.map((source: string) => relative(resolve(root, "dist"), resolve(dirname(bundle), source)) .split(sep) @@ -146,11 +146,14 @@ export function tokamak( this.emitFile({ type: "asset", fileName: "api.ts", source: api }); if (plugin.runtime === "worker") { for (const name of ["worker.js", "worker.js.map", "worker-entry.js"]) { - this.emitFile({ - type: "asset", - fileName: name, - source: await readFile(resolve(server, "dist", name), "utf8"), - }); + const contents = await readFile(resolve(server, "dist", name), "utf8"); + let source = contents; + if (name.endsWith(".map")) { + const map = JSON.parse(contents); + delete map.sourcesContent; + source = JSON.stringify(map); + } + this.emitFile({ type: "asset", fileName: name, source }); } entries.worker = { entry: "worker-entry.js", code: "worker.js", map: "worker.js.map" }; } diff --git a/packages/cli/README.md b/packages/cli/README.md index 370288a5..5b68c520 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -5,6 +5,7 @@ Run from a checkout with the pinned Bun: ```sh proto run bun -- run --silent tokamak --help proto run bun -- run --silent tokamak plugin build /path/to/my-plugin --json +proto run bun -- run --silent tokamak plugin pack /path/to/my-plugin --json proto run bun -- run --silent tokamak plugin add /path/to/my-plugin proto run bun -- run --silent tokamak plugin list --json proto run bun -- run --silent tokamak plugin logs my-plugin --errors --json @@ -15,7 +16,12 @@ proto run bun -- run --silent tokamak report --out diagnostics.md ``` `build` runs the artifact build once, defaults to the current folder, and -doesn't need a server. `add` reads the plugin's static identity from `plugin.ts` +doesn't need a server. `pack` also works without a server and defaults to the +current folder. It builds the plugin and writes `-.zip` in the +folder where the command was run. The ZIP contains `manifest.json` and the +files listed in its hashes. The build id is the SHA-256 of the manifest bytes. + +`add` reads the plugin's static identity from `plugin.ts` (or the build's `package.json` convention), and doesn't build it. `add` and `remove` edit the index. Run `tokamak plugin reload [id]` to build and apply indexed plugins, or omit the id to also apply removals. Both commands serialize index updates with an exclusive owner file: a dead owner can be removed, and a live owner is never displaced. An @@ -100,6 +106,7 @@ nonzero on failure. The CLI never prompts. Success has `ok: true` and: | Command | Additional result fields | | --------------- | ------------------------------------------------------------------ | | `plugin build` | `id`, `outputFolder` | +| `plugin pack` | `path` (absolute), `id`, `version`, `buildId` | | `plugin add` | `id`, `folder`, `reloadRequired: true`, `precedence: "index"` | | `plugin remove` | `id`, `reloadRequired: true` | | `plugin list` | `plugins`: an array of `{ id, version, fromIndex }` | diff --git a/packages/cli/package.json b/packages/cli/package.json index 09188a38..651b79ba 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -2,5 +2,8 @@ "name": "@tokamak/cli", "version": "0.1.0", "private": true, - "type": "module" + "type": "module", + "dependencies": { + "fflate": "0.8.3" + } } diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts index 3b98e84e..2f5960a9 100644 --- a/packages/cli/src/commands.ts +++ b/packages/cli/src/commands.ts @@ -1,5 +1,6 @@ import type { Command } from "./command"; import build from "./commands/build"; +import pack from "./commands/pack"; import add from "./commands/add"; import remove from "./commands/remove"; import list from "./commands/list"; @@ -17,6 +18,7 @@ const peopleAndServer = [members, invite, revoke, serverStart, serverStop, serve export const commands: readonly Command[] = [ build, + pack, add, remove, list, diff --git a/packages/cli/src/commands/build.ts b/packages/cli/src/commands/build.ts index e334a98f..3581b502 100644 --- a/packages/cli/src/commands/build.ts +++ b/packages/cli/src/commands/build.ts @@ -1,8 +1,7 @@ -import { readFile, realpath } from "node:fs/promises"; +import { readFile } from "node:fs/promises"; import { resolve } from "node:path"; import { CommandError, type Command } from "../command"; -import { runBuilder } from "../plugin-build"; -import { acquireLock } from "../plugin-index"; +import { runBuilder, withBuildLock } from "../plugin-build"; export default { path: "plugin build", @@ -10,16 +9,7 @@ export default { args: { name: "folder", optional: true }, example: "tokamak plugin build . --json", async run([folder]) { - const root = await realpath(resolve(folder ?? ".")).catch(() => resolve(folder ?? ".")); - // Let the builder report missing folders using its structured diagnostics. - const release = await acquireLock(root, ".tokamak-build").catch((error) => { - if (error.code !== "ENOENT") throw error; - }); - try { - return await buildInFolder(root); - } finally { - await release?.(); - } + return withBuildLock(folder, buildInFolder); }, } satisfies Command; diff --git a/packages/cli/src/commands/doctor.ts b/packages/cli/src/commands/doctor.ts index bea0deae..06e1210d 100644 --- a/packages/cli/src/commands/doctor.ts +++ b/packages/cli/src/commands/doctor.ts @@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url"; import type { Command } from "../command"; import { dataFolder } from "../data"; import { inspectLocalServer } from "../server"; -import { version } from "../../package.json"; +import { tokamakVersion } from "../../../tokamak-version"; const checkout = fileURLToPath(new URL("../../../../", import.meta.url)); const startServer = "tokamak server start"; @@ -70,7 +70,7 @@ export async function inspectDevelopment() { const server = discovery?.responsive ? discovery : undefined; const git = gitVersion(); const rows = [ - ready("Tokamak CLI", `${version} · ${fileURLToPath(new URL("../main.ts", import.meta.url))}`), + ready("Tokamak CLI", `${tokamakVersion()} · ${fileURLToPath(new URL("../main.ts", import.meta.url))}`), bun, git ? ready("git", git) diff --git a/packages/cli/src/commands/pack.ts b/packages/cli/src/commands/pack.ts new file mode 100644 index 00000000..57f57a9b --- /dev/null +++ b/packages/cli/src/commands/pack.ts @@ -0,0 +1,61 @@ +import { zipSync, type Zippable } from "fflate"; +import { createHash, randomUUID } from "node:crypto"; +import { readFile, rename, rm, writeFile } from "node:fs/promises"; +import { resolve } from "node:path"; +import type { Command } from "../command"; +import { runBuilder, withBuildLock } from "../plugin-build"; + +function sha256(bytes: Uint8Array) { + return createHash("sha256").update(bytes).digest("hex"); +} + +async function archive(outputFolder: string) { + const manifest = await readFile(resolve(outputFolder, "manifest.json")); + const { plugin, hashes } = JSON.parse(manifest.toString()) as { + plugin: { id: string; version: string }; + hashes: Record; + }; + const { id, version } = plugin; + if (!/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(id) || !/^[0-9][0-9A-Za-z.+-]*$/.test(version)) + throw new Error("Invalid plugin identity in the build manifest"); + + const entries: Zippable = Object.assign(Object.create(null), { "manifest.json": manifest }); + for (const [name, hash] of Object.entries(hashes)) { + if ( + name === "manifest.json" || + /[\\:]/.test(name) || + name.includes("\0") || + name.split("/").some((part) => !part || part === "." || part === "..") + ) { + throw new Error(`Invalid artifact path: ${name}`); + } + const bytes = await readFile(resolve(outputFolder, name)); + if (sha256(bytes) !== hash) throw new Error(`Artifact hash mismatch: ${name}`); + entries[name] = bytes; + } + + const path = resolve(`${id}-${version}.zip`); + const temporary = `${path}.${randomUUID()}.tmp`; + try { + await writeFile(temporary, zipSync(entries)); + await rename(temporary, path); + } finally { + await rm(temporary, { force: true }); + } + return { path, id, version, buildId: sha256(manifest) }; +} + +export default { + path: "plugin pack", + summary: "Build a plugin and write its ZIP package in the current folder.", + args: { name: "folder", optional: true }, + example: "tokamak plugin pack ./my-plugin --json", + async run([folder]) { + const data = await withBuildLock(folder, async (root) => { + const { outputFolder } = await runBuilder(root, "--result-json", "tokamak plugin pack --help"); + if (!outputFolder) throw new Error("The build did not report its output folder"); + return archive(outputFolder); + }); + return { data, text: `Packed ${data.id} ${data.version}: ${data.path} (build id ${data.buildId})` }; + }, +} satisfies Command; diff --git a/packages/cli/src/plugin-build.ts b/packages/cli/src/plugin-build.ts index 235fc717..6683e587 100644 --- a/packages/cli/src/plugin-build.ts +++ b/packages/cli/src/plugin-build.ts @@ -1,16 +1,26 @@ import { execFile } from "node:child_process"; +import { realpath } from "node:fs/promises"; +import { resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { promisify } from "node:util"; import { CommandError } from "./command"; +import { acquireLock } from "./plugin-index"; import type { BuildDiagnostic } from "../../build/src/diagnostics"; const builder = fileURLToPath(new URL("../../build/src/build.ts", import.meta.url)); +const checkout = fileURLToPath(new URL("../../../", import.meta.url)); const prefix = "Tokamak build result: "; type BuildResult = { ok: true; outputFolder?: string } | { ok: false; diagnostics: BuildDiagnostic[] }; -export async function runBuilder(folder: string, mode: "--result-json" | "--check-index") { - const processResult = promisify(execFile)(process.execPath, [builder, mode, folder], { +export async function runBuilder( + folder: string, + mode: "--result-json" | "--check-index", + next = mode === "--result-json" ? "tokamak plugin build --help" : "tokamak plugin add --help", +) { + const processResult = promisify(execFile)(process.execPath, [builder, mode, resolve(folder)], { + // Keep Vite’s generated module labels independent of the invocation folder. + cwd: checkout, maxBuffer: 16 * 1024 * 1024, }); processResult.child.stdin?.end(); @@ -26,7 +36,21 @@ export async function runBuilder(folder: string, mode: "--result-json" | "--chec if (result?.ok && !failed) return result; throw new CommandError( mode === "--result-json" ? "Plugin build failed" : "Could not add plugin", - mode === "--result-json" ? "tokamak plugin build --help" : "tokamak plugin add --help", + next, result?.ok === false ? result.diagnostics : [{ message: "The artifact builder did not return a result" }], ); } + +export async function withBuildLock(folder: string | undefined, work: (root: string) => Promise) { + const absolute = resolve(folder ?? "."); + const root = await realpath(absolute).catch(() => absolute); + // Let the builder report missing folders using its structured diagnostics. + const release = await acquireLock(root, ".tokamak-build").catch((error) => { + if (error.code !== "ENOENT") throw error; + }); + try { + return await work(root); + } finally { + await release?.(); + } +} diff --git a/packages/cli/tests/cli-fixture.mjs b/packages/cli/tests/cli-fixture.mjs index 87da6efb..db161c9c 100644 --- a/packages/cli/tests/cli-fixture.mjs +++ b/packages/cli/tests/cli-fixture.mjs @@ -1,9 +1,9 @@ import { join } from "node:path"; import { workspace } from "../../build/tests/outside-fixture.mjs"; -export function cli(root, args, extra = {}) { - const result = Bun.spawnSync([process.execPath, "run", "--silent", "tokamak", ...args], { - cwd: workspace, +export function cli(root, args, extra = {}, cwd = workspace) { + const result = Bun.spawnSync([process.execPath, join(workspace, "packages/cli/src/main.ts"), ...args], { + cwd, timeout: 60_000, env: { ...process.env, diff --git a/packages/cli/tests/cli.test.mjs b/packages/cli/tests/cli.test.mjs index 6479c9bb..d50bbbf5 100644 --- a/packages/cli/tests/cli.test.mjs +++ b/packages/cli/tests/cli.test.mjs @@ -1,10 +1,11 @@ import { expect, test } from "bun:test"; -import { chmod, cp, mkdir, readFile, realpath, symlink, writeFile } from "node:fs/promises"; +import { chmod, cp, mkdir, readdir, readFile, realpath, symlink, writeFile } from "node:fs/promises"; import { dirname, join, resolve, toNamespacedPath } from "node:path"; -import { randomBytes } from "node:crypto"; +import { createHash, randomBytes } from "node:crypto"; import { withPlugin, workspace } from "../../build/tests/outside-fixture.mjs"; import { createApi, TokamakClient, WebSocketTransport } from "../../sdk/src/index"; import { cli } from "./cli-fixture.mjs"; +import { version as tokamakVersion } from "../package.json"; test("adds and removes folders and protects an existing id", async () => { await withPlugin(async (plugin, root) => { @@ -53,6 +54,7 @@ test("every registered command shares help and JSON output rules", async () => { expect(commands.map(({ path }) => path)).toEqual( expect.arrayContaining([ "plugin build", + "plugin pack", "plugin add", "plugin remove", "plugin list", @@ -361,6 +363,25 @@ test("reload tells the user how to add an unknown plugin", async () => { }); }); +test("pack reports the source location of a failed build without writing a ZIP", async () => { + await withPlugin(async (plugin, root) => { + const file = join(plugin, "src/server/broken.ts"); + await writeFile(file, "\nexport const broken: string = 42;\n"); + const result = cli(root, ["plugin", "pack", plugin, "--json"], {}, root); + expect(result.code).not.toBe(0); + expect(JSON.parse(result.stdout)).toMatchObject({ + ok: false, + error: { + message: "Plugin build failed", + next: "tokamak plugin pack --help", + diagnostics: expect.arrayContaining([expect.objectContaining({ file, line: 2 })]), + }, + }); + expect(result.stderr).toContain(`${file}:2:`); + expect(await readdir(root)).toEqual(["plugin"]); + }); +}); + test("reload applies index additions and removals without a restart", async () => { await withPlugin(async (plugin, root) => { const run = (...args) => { @@ -368,12 +389,48 @@ test("reload applies index additions and removals without a restart", async () = expect(result.code, result.stderr).toBe(0); return JSON.parse(result.stdout); }; + const digest = (bytes) => createHash("sha256").update(bytes).digest("hex"); + const dist = join(plugin, "dist"); + await mkdir(dist); + await writeFile(join(dist, "stale.txt"), "An old file left in dist"); + const pack = (cwd, ...args) => { + const result = cli(root, ["plugin", "pack", ...args, "--json"], {}, cwd); + expect(result.code, result.stderr).toBe(0); + expect(result.stderr).toContain("Packed outside-fixture"); + return JSON.parse(result.stdout); + }; + const packed = pack(root, "plugin"); + const zip = join(root, "outside-fixture-0.1.0.zip"); + expect(packed).toEqual({ + ok: true, + path: zip, + id: "outside-fixture", + version: "0.1.0", + buildId: expect.stringMatching(/^[a-f0-9]{64}$/), + }); + expect(pack(plugin).buildId).toBe(packed.buildId); + const unzip = (...args) => { + const result = Bun.spawnSync(["unzip", ...args]); + expect(result.exitCode, result.stderr.toString()).toBe(0); + return result.stdout; + }; + const manifest = unzip("-p", zip, "manifest.json"); + const { plugin: metadata, hashes } = JSON.parse(manifest.toString()); + expect(metadata.api).toBe(`tokamak@${tokamakVersion}`); + expect(packed.buildId).toBe(digest(manifest)); + expect(unzip("-Z1", zip).toString().trimEnd().split("\n").sort()).toEqual( + ["manifest.json", ...Object.keys(hashes)].sort(), + ); + for (const [name, hash] of Object.entries(hashes)) { + const bytes = unzip("-p", zip, name); + expect(digest(bytes)).toBe(hash); + if (name.endsWith(".map")) expect(JSON.parse(bytes.toString())).not.toHaveProperty("sourcesContent"); + } + await withServer(root, async () => { run("add", plugin); expect(run("reload", "outside-fixture")).toMatchObject({ - plugins: [ - { id: "outside-fixture", status: "loaded", buildId: expect.stringMatching(/^[a-f0-9]{64}$/) }, - ], + plugins: [{ id: "outside-fixture", status: "loaded", buildId: packed.buildId }], }); expect(run("list").plugins).toEqual([{ id: "outside-fixture", version: "0.1.0", fromIndex: true }]); expect(run("reload", "outside-fixture").plugins).toEqual([ diff --git a/packages/server/src/plugins/manifest.rs b/packages/server/src/plugins/manifest.rs index 5e02fe87..71d79212 100644 --- a/packages/server/src/plugins/manifest.rs +++ b/packages/server/src/plugins/manifest.rs @@ -129,12 +129,18 @@ impl Manifest { .strip_prefix("tokamak@") .ok_or_else(|| invalid("Host API requirement must start with tokamak@"))?; - let requirement = VersionReq::parse(requirement) - .map_err(|e| invalid(format!("Invalid host API range: {e}")))?; - - if !requirement - .matches(&Version::parse(env!("CARGO_PKG_VERSION")).expect("package version")) - { + let server = Version::parse(env!("CARGO_PKG_VERSION")).expect("package version"); + // Full build versions pin the release line. Older manifests may declare a range. + let compatible = if let Ok(built_with) = Version::parse(requirement) { + server.major == built_with.major + && server.minor == built_with.minor + && !server.cmp_precedence(&built_with).is_lt() + } else { + VersionReq::parse(requirement) + .map_err(|e| invalid(format!("Invalid host API range: {e}")))? + .matches(&server) + }; + if !compatible { return Err(invalid(format!( "Incompatible host API for {}", self.plugin.id diff --git a/packages/server/src/plugins/tests.rs b/packages/server/src/plugins/tests.rs index de92eb3d..cc66f87c 100644 --- a/packages/server/src/plugins/tests.rs +++ b/packages/server/src/plugins/tests.rs @@ -84,6 +84,9 @@ fn resolves_dependencies_optional_providers_and_private_assets() { } #[test] fn rejects_missing_incompatible_conflicting_cyclic_and_duplicate_plugins() { + let server = Version::parse(env!("CARGO_PKG_VERSION")).unwrap(); + let newer_patch = Version::new(server.major, server.minor, server.patch + 1); + let other_line = Version::new(server.major, server.minor + 1, 0); for (a, b, expected) in [ ( json!({"id":"a","version":"1.0.0","depends":{"missing":"*"}}), @@ -120,6 +123,16 @@ fn rejects_missing_incompatible_conflicting_cyclic_and_duplicate_plugins() { json!({"id":"b","version":"1.0.0"}), "Incompatible host API", ), + ( + json!({"id":"a","version":"1.0.0","api":format!("tokamak@{newer_patch}")}), + json!({"id":"b","version":"1.0.0"}), + "Incompatible host API", + ), + ( + json!({"id":"a","version":"1.0.0","api":format!("tokamak@{other_line}")}), + json!({"id":"b","version":"1.0.0"}), + "Incompatible host API", + ), ] { let root = scratch(); write(&root.0, "first", a); diff --git a/packages/tokamak-version.ts b/packages/tokamak-version.ts new file mode 100644 index 00000000..f584d693 --- /dev/null +++ b/packages/tokamak-version.ts @@ -0,0 +1,5 @@ +import { version } from "./cli/package.json"; + +export function tokamakVersion(): string { + return version; +} From 55e7ac9439ab9eb922aaff6fc9da08febc37e0ea Mon Sep 17 00:00:00 2001 From: JustKira Date: Fri, 20 Nov 2026 17:44:39 +0200 Subject: [PATCH 2/3] Keep CLI help available without the ZIP writer --- packages/cli/src/commands/pack.ts | 3 ++- packages/cli/tests/cli.test.mjs | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/cli/src/commands/pack.ts b/packages/cli/src/commands/pack.ts index 57f57a9b..52117ef3 100644 --- a/packages/cli/src/commands/pack.ts +++ b/packages/cli/src/commands/pack.ts @@ -1,4 +1,4 @@ -import { zipSync, type Zippable } from "fflate"; +import type { Zippable } from "fflate"; import { createHash, randomUUID } from "node:crypto"; import { readFile, rename, rm, writeFile } from "node:fs/promises"; import { resolve } from "node:path"; @@ -34,6 +34,7 @@ async function archive(outputFolder: string) { entries[name] = bytes; } + const { zipSync } = await import("fflate"); const path = resolve(`${id}-${version}.zip`); const temporary = `${path}.${randomUUID()}.tmp`; try { diff --git a/packages/cli/tests/cli.test.mjs b/packages/cli/tests/cli.test.mjs index d50bbbf5..523fb2d7 100644 --- a/packages/cli/tests/cli.test.mjs +++ b/packages/cli/tests/cli.test.mjs @@ -1971,6 +1971,7 @@ test("help and report load with missing TypeScript and doctor runs an actual com await mkdir(join(checkout, "packages/build"), { recursive: true }); await cp(join(workspace, "packages/cli/src"), join(checkout, "packages/cli/src"), { recursive: true }); await cp(join(workspace, "packages/cli/package.json"), join(checkout, "packages/cli/package.json")); + await cp(join(workspace, "packages/tokamak-version.ts"), join(checkout, "packages/tokamak-version.ts")); await cp(join(workspace, "packages/build/src"), join(checkout, "packages/build/src"), { recursive: true, }); From c4687d445a8d4d18818a9030558dfed080c637b7 Mon Sep 17 00:00:00 2001 From: JustKira Date: Fri, 20 Nov 2026 18:25:09 +0200 Subject: [PATCH 3/3] TKM-175: Make plugin packages independent of their build folder --- packages/build/src/artifact-sources.ts | 63 +++++++++++++++ packages/build/src/build.ts | 2 + packages/build/src/descriptor.ts | 45 +++++++---- packages/build/src/ui-build-config.ts | 9 ++- packages/build/src/vite.ts | 44 +++++----- packages/cli/src/commands/build.ts | 4 +- packages/cli/src/commands/pack.ts | 6 +- packages/cli/src/commands/reload.ts | 20 +++-- packages/cli/src/plugin-build.ts | 20 +++-- packages/cli/tests/cli.test.mjs | 106 ++++++++++++++++++++++++- packages/sdk/src/plugin.ts | 23 ++++-- 11 files changed, 279 insertions(+), 63 deletions(-) create mode 100644 packages/build/src/artifact-sources.ts diff --git a/packages/build/src/artifact-sources.ts b/packages/build/src/artifact-sources.ts new file mode 100644 index 00000000..c7deb806 --- /dev/null +++ b/packages/build/src/artifact-sources.ts @@ -0,0 +1,63 @@ +import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path"; +import { fileURLToPath } from "node:url"; +import ts from "typescript"; + +const packages = fileURLToPath(new URL("../../", import.meta.url)); +const portable = (path: string) => path.split(sep).join("/"); +const syntheticEntry = /^(?:tokamak-feature|worker):entry$/; +const inside = (path: string) => path !== ".." && !path.startsWith("../") && !isAbsolute(path); + +export function artifactSourcePath(root: string, base: string, source: string): string { + if (!source || syntheticEntry.test(source)) return source; + const path = source.startsWith("file:") ? fileURLToPath(source) : resolve(base, source); + const installed = portable(path); + const dependency = installed.lastIndexOf("/node_modules/"); + if (dependency !== -1) return installed.slice(dependency + 1); + const local = portable(relative(root, path)); + if (inside(local)) return local; + const workspace = portable(relative(packages, path)); + if (inside(workspace)) return `node_modules/@tokamak/${workspace}`; + return `external/${basename(path)}`; +} + +export function artifactSourceMap(root: string, file: string, text: string) { + const map = JSON.parse(text) as { + file?: string; + sourceRoot?: string; + sources: string[]; + sourcesContent?: (string | null)[]; + debugId?: string; + }; + // Bun's debug ID includes its original path comments and source map paths. + delete map.debugId; + const base = resolve(dirname(file), map.sourceRoot ?? ""); + delete map.sourceRoot; + if (map.file) map.file = basename(map.file); + map.sources = map.sources.map((source, index) => { + const content = map.sourcesContent?.[index]; + if (syntheticEntry.test(source) && content && map.sourcesContent) { + // The synthetic entry imports absolute files so the compiler can resolve them. + map.sourcesContent[index] = content.replace(/\bfrom ("(?:[^"\\]|\\.)*")/g, (statement, specifier) => { + const path = JSON.parse(specifier) as string; + return isAbsolute(path) ? `from ${JSON.stringify(artifactSourcePath(root, base, path))}` : statement; + }); + } + return artifactSourcePath(root, base, source); + }); + return map; +} + +export function withoutBunPathComments(code: string) { + const file = ts.createSourceFile("bundle.js", code, ts.ScriptTarget.Latest, false, ts.ScriptKind.JS); + const edits: { pos: number; end: number }[] = []; + for (const node of [...file.statements, file.endOfFileToken]) { + for (const { pos, end } of ts.getLeadingCommentRanges(code, node.pos) ?? []) { + const comment = code.slice(pos, end); + if (/^\/\/ (?:\.{1,2}[/\\]|\/|[a-z]:[/\\]|file:)/i.test(comment) || comment.startsWith("//# debugId=")) + edits.push({ pos, end }); + } + } + // Leave the line breaks in place so the generated source map remains valid. + for (const { pos, end } of edits.reverse()) code = code.slice(0, pos) + code.slice(end); + return code; +} diff --git a/packages/build/src/build.ts b/packages/build/src/build.ts index 76c07f7a..987294cb 100644 --- a/packages/build/src/build.ts +++ b/packages/build/src/build.ts @@ -24,6 +24,8 @@ const config = ? resolve(root, "vite.config.ts") : false; async function run() { + // CLI builds give authored Vite hooks their plugin's working directory. + if (mode) process.chdir(root); let directory: string | undefined; function verifyOutput(output: string) { if (mode && output !== resolve(realpathSync(root), "dist") && output !== resolve(root, "dist")) diff --git a/packages/build/src/descriptor.ts b/packages/build/src/descriptor.ts index 407a0cf2..dbfea0b3 100644 --- a/packages/build/src/descriptor.ts +++ b/packages/build/src/descriptor.ts @@ -5,7 +5,8 @@ import ts from "typescript"; import { existsSync, readFileSync, readdirSync } from "node:fs"; import { readFile } from "node:fs/promises"; import { basename, relative, resolve, sep } from "node:path"; -import { definePlugin, type PluginDefinition } from "@tokamak/sdk"; +import { definePlugin, PluginDefinitionError, type PluginDefinition } from "../../sdk/src/plugin"; +import { BuildError, sourceLocation } from "./diagnostics"; export function serverDirectory(root: string): string { return resolve(root, existsSync(resolve(root, "src/server")) ? "src/server" : "backend"); @@ -23,8 +24,10 @@ export function readDescriptor(root: string): PluginDefinition | undefined { const path = resolve(root, "plugin.ts"); if (!existsSync(path)) return; const source = ts.createSourceFile(path, readFileSync(path, "utf8"), ts.ScriptTarget.Latest, true); - const fail = (): never => { - throw new Error("plugin.ts must export default definePlugin({...}) with static literal metadata"); + const at = (node: ts.Node, message: string) => + new BuildError([{ ...sourceLocation(path, source.text, node.getStart(source)), message }]); + const fail = (node: ts.Node = source): never => { + throw at(node, "plugin.ts must export default definePlugin({...}) with static literal metadata"); }; const helper = source.statements.flatMap((statement) => ts.isImportDeclaration(statement) && @@ -38,14 +41,15 @@ export function readDescriptor(root: string): PluginDefinition | undefined { : [], ); const assignment = source.statements.find(ts.isExportAssignment); - if (!assignment || assignment.isExportEquals || !ts.isCallExpression(assignment.expression)) return fail(); + if (!assignment || assignment.isExportEquals || !ts.isCallExpression(assignment.expression)) + return fail(assignment); const call = assignment.expression; if ( !ts.isIdentifier(call.expression) || !helper.includes(call.expression.text) || call.arguments.length !== 1 ) - return fail(); + return fail(call); function literal(node: ts.Node): unknown { if (ts.isStringLiteralLike(node)) return node.text; if (ts.isArrayLiteralExpression(node)) return node.elements.map(literal); @@ -56,16 +60,23 @@ export function readDescriptor(root: string): PluginDefinition | undefined { !ts.isPropertyAssignment(property) || !(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ) - return fail(); + return fail(property); const key = property.name.text; - if (Object.hasOwn(result, key)) return fail(); + if (Object.hasOwn(result, key)) return fail(property); result[key] = literal(property.initializer); } return result; } - return fail(); + return fail(node); } - const value = literal(call.arguments[0]!) as Record; + const descriptor = call.arguments[0]!; + if (!ts.isObjectLiteralExpression(descriptor)) return fail(descriptor); + const value = literal(descriptor) as Record; + const fields = new Map( + descriptor.properties + .filter(ts.isPropertyAssignment) + .map((property) => [property.name.getText(source).replace(/^['"]|['"]$/g, ""), property]), + ); const allowed = [ "id", "version", @@ -77,16 +88,22 @@ export function readDescriptor(root: string): PluginDefinition | undefined { "runtime", "maintenance", ]; - if (!value || Array.isArray(value) || Object.keys(value).some((key) => !allowed.includes(key))) - return fail(); + const unknown = Object.keys(value).find((key) => !allowed.includes(key)); + if (unknown !== undefined) return fail(fields.get(unknown) ?? descriptor); for (const key of ["depends", "optional"]) { if (value[key] === undefined) continue; const ids = value[key]; if (!Array.isArray(ids) || ids.some((id) => typeof id !== "string") || new Set(ids).size !== ids.length) - return fail(); + return fail(fields.get(key) ?? descriptor); value[key] = Object.fromEntries(ids.map((id) => [id, "*"])); } - return value as unknown as PluginDefinition; + try { + return definePlugin(value as unknown as PluginDefinition); + } catch (error) { + if (!(error instanceof Error)) throw error; + const node = error instanceof PluginDefinitionError ? fields.get(error.field) : undefined; + throw at(node ?? descriptor, error.message); + } } export async function readSourcePlugin( @@ -94,7 +111,7 @@ export async function readSourcePlugin( prefetched?: Record | null, ): Promise { const descriptor = readDescriptor(root); - if (descriptor) return definePlugin(descriptor); + if (descriptor) return descriptor; const manifest = prefetched === undefined ? JSON.parse(await readFile(resolve(root, "package.json"), "utf8")) : prefetched; if (!manifest) throw new Error("Expected plugin.ts or package.json"); diff --git a/packages/build/src/ui-build-config.ts b/packages/build/src/ui-build-config.ts index a5cf5a66..48174857 100644 --- a/packages/build/src/ui-build-config.ts +++ b/packages/build/src/ui-build-config.ts @@ -3,6 +3,7 @@ import { existsSync } from "node:fs"; import { dirname, resolve } from "node:path"; import { compileCss } from "./css.ts"; import { clientEntry } from "./descriptor.ts"; +import { artifactSourcePath } from "./artifact-sources.ts"; import { windowSharedImports } from "./shared-libraries.mts"; @@ -23,7 +24,13 @@ export function uiBuildConfig(root: string): UserConfig { fileName: () => "ui.js", cssFileName: "styles", }, - rollupOptions: { output: { codeSplitting: false, sourcemapExcludeSources: true } }, + rolldownOptions: { + experimental: { attachDebugInfo: "none" }, + output: { + codeSplitting: false, + sourcemapPathTransform: (source, map) => artifactSourcePath(root, dirname(map), source), + }, + }, }, }; } diff --git a/packages/build/src/vite.ts b/packages/build/src/vite.ts index 4c71d44a..b6b7da48 100644 --- a/packages/build/src/vite.ts +++ b/packages/build/src/vite.ts @@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url"; import { checkPluginImports } from "../../sdk/tools/plugin-boundary.mjs"; import { pluginBoundary } from "./plugin-boundary.ts"; import { artifactBundle } from "./artifact-bundle.ts"; +import { artifactSourceMap, withoutBunPathComments } from "./artifact-sources.ts"; import solid from "@solidjs/vite-plugin"; import { clientSurface } from "./client-surface.ts"; import { uiBuildConfig, clientAssets } from "./ui-build-config.ts"; @@ -126,15 +127,9 @@ export function tokamak( // in QuickJS. Keep that source authoritative instead of importing user // schema modules into the build host or duplicating them in manifests. const bundle = resolve(server, "dist/bundle.js"); - const source = await readFile(bundle, "utf8"); - const map = JSON.parse(await readFile(`${bundle}.map`, "utf8")); - // Keep source locations for stack traces without shipping the original source. - delete map.sourcesContent; - map.sources = map.sources.map((source: string) => - relative(resolve(root, "dist"), resolve(dirname(bundle), source)) - .split(sep) - .join("/"), - ); + const source = withoutBunPathComments(await readFile(bundle, "utf8")); + const mapFile = `${bundle}.map`; + const map = artifactSourceMap(root, mapFile, await readFile(mapFile, "utf8")); this.emitFile({ type: "asset", fileName: "bundle.js", source }); this.emitFile({ type: "asset", fileName: "bundle.js.map", source: JSON.stringify(map) }); // References are source-aware, matching the existing SDK contract. @@ -145,16 +140,27 @@ export function tokamak( ); this.emitFile({ type: "asset", fileName: "api.ts", source: api }); if (plugin.runtime === "worker") { - for (const name of ["worker.js", "worker.js.map", "worker-entry.js"]) { - const contents = await readFile(resolve(server, "dist", name), "utf8"); - let source = contents; - if (name.endsWith(".map")) { - const map = JSON.parse(contents); - delete map.sourcesContent; - source = JSON.stringify(map); - } - this.emitFile({ type: "asset", fileName: name, source }); - } + const workerMapFile = resolve(server, "dist/worker.js.map"); + const workerMap = artifactSourceMap(root, workerMapFile, await readFile(workerMapFile, "utf8")); + const { sourcesContent: _sources, ...runtimeMap } = workerMap; + const worker = await readFile(resolve(server, "dist/worker.js"), "utf8"); + const mapStart = worker.lastIndexOf("\nexport const workerSourceMap = "); + if (mapStart < 0) throw new Error("Missing runtime source map for the plugin worker"); + this.emitFile({ + type: "asset", + fileName: "worker.js", + source: `${withoutBunPathComments(worker.slice(0, mapStart))}\nexport const workerSourceMap = ${JSON.stringify(runtimeMap)};\n`, + }); + this.emitFile({ + type: "asset", + fileName: "worker.js.map", + source: JSON.stringify(workerMap), + }); + this.emitFile({ + type: "asset", + fileName: "worker-entry.js", + source: withoutBunPathComments(await readFile(resolve(server, "dist/worker-entry.js"), "utf8")), + }); entries.worker = { entry: "worker-entry.js", code: "worker.js", map: "worker.js.map" }; } entries.backend = { code: "bundle.js", map: "bundle.js.map", api: "api.ts" }; diff --git a/packages/cli/src/commands/build.ts b/packages/cli/src/commands/build.ts index 3581b502..9f2c1476 100644 --- a/packages/cli/src/commands/build.ts +++ b/packages/cli/src/commands/build.ts @@ -14,7 +14,7 @@ export default { } satisfies Command; export async function buildInFolder(folder: string) { - const { outputFolder } = await runBuilder(folder, "--result-json"); + const { outputFolder, warnings } = await runBuilder(folder, "--result-json"); if (!outputFolder) throw new Error("The build did not report its output folder"); const id = await readFile(resolve(outputFolder, "manifest.json"), "utf8") .then((source) => { @@ -27,5 +27,5 @@ export async function buildInFolder(folder: string) { { message: `Could not read the build manifest: ${error.message}` }, ]); }); - return { data: { id, outputFolder }, text: `Built ${id}: ${outputFolder}` }; + return { data: { id, outputFolder }, text: `Built ${id}: ${outputFolder}`, warnings }; } diff --git a/packages/cli/src/commands/pack.ts b/packages/cli/src/commands/pack.ts index 52117ef3..08f81bb0 100644 --- a/packages/cli/src/commands/pack.ts +++ b/packages/cli/src/commands/pack.ts @@ -1,7 +1,7 @@ import type { Zippable } from "fflate"; import { createHash, randomUUID } from "node:crypto"; import { readFile, rename, rm, writeFile } from "node:fs/promises"; -import { resolve } from "node:path"; +import { dirname, resolve } from "node:path"; import type { Command } from "../command"; import { runBuilder, withBuildLock } from "../plugin-build"; @@ -36,9 +36,9 @@ async function archive(outputFolder: string) { const { zipSync } = await import("fflate"); const path = resolve(`${id}-${version}.zip`); - const temporary = `${path}.${randomUUID()}.tmp`; + const temporary = resolve(dirname(path), `.tokamak-pack-${randomUUID()}.tmp`); try { - await writeFile(temporary, zipSync(entries)); + await writeFile(temporary, zipSync(entries, { mtime: new Date(1980, 0, 1) })); await rename(temporary, path); } finally { await rm(temporary, { force: true }); diff --git a/packages/cli/src/commands/reload.ts b/packages/cli/src/commands/reload.ts index 25841993..69c4fcc5 100644 --- a/packages/cli/src/commands/reload.ts +++ b/packages/cli/src/commands/reload.ts @@ -26,6 +26,7 @@ type Report = { skipped: Record; removalError?: string; warnings: Set; + buildWarnings: Set; }; const messageOf = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause)); @@ -41,8 +42,9 @@ function failed( return { id, buildId, status, error: { message: messageOf(cause), ...(diagnostics && { diagnostics }) } }; } -async function build(id: string, folder: string): Promise { - const { data } = await buildInFolder(folder); +async function build(report: Report, id: string, folder: string): Promise { + const { data, warnings } = await buildInFolder(folder); + for (const warning of warnings) report.buildWarnings.add(warning); if (data.id !== id) throw new Error(`Build produced plugin ${data.id}, expected ${id}`); const bytes = await readFile(join(data.outputFolder, "manifest.json")); return { @@ -174,7 +176,13 @@ async function runReload(id: string | undefined, server?: string) { if (id !== undefined && !index.has(id)) throw new CommandError(`Unknown indexed plugin: ${id}`, "tokamak plugin add"); const selected = id === undefined ? [...index] : [[id, index.get(id)!] as const]; - const report: Report = { results: new Map(), removed: new Set(), skipped: {}, warnings: new Set() }; + const report: Report = { + results: new Map(), + removed: new Set(), + skipped: {}, + warnings: new Set(), + buildWarnings: new Set(), + }; const releases = new Map Promise>(); const builds: Build[] = []; const sources: { id: string; folder: string; depends: string[] }[] = []; @@ -196,7 +204,7 @@ async function runReload(id: string | undefined, server?: string) { // Providers must publish their types before selected dependents build. for (const { id: plugin, folder } of dependencyOrder(sources)) { try { - builds.push(await build(plugin, folder)); + builds.push(await build(report, plugin, folder)); } catch (error) { report.results.set(plugin, failed(plugin, null, "build-failed", error)); } @@ -215,7 +223,7 @@ function reportOutput(report: Report, selected: string[]) { const plugins = selected.map((id) => report.results.get(id)!); const removed = [...report.removed]; const skipped = Object.fromEntries(Object.entries(report.skipped).filter(([id]) => !selected.includes(id))); - const warnings = [...report.warnings]; + const warnings = [...new Set([...report.buildWarnings, ...report.warnings])]; const data = { plugins, removed, skipped, ...(warnings.length && { warnings }) }; const lines = [ ...plugins.map(({ id, status, error }) => @@ -232,7 +240,7 @@ function reportOutput(report: Report, selected: string[]) { ), ...removed.map((id) => `Removed ${id} from the running index`), ...Object.entries(skipped).map(([id, reason]) => `Skipped ${id}: ${reason}`), - ...warnings.map((warning) => `Warning: ${warning}`), + ...[...report.warnings].map((warning) => `Warning: ${warning}`), ]; if (report.removalError) lines.push(`Could not confirm index removals: ${report.removalError}`); const text = lines.join("\n") || "No indexed plugins to reload."; diff --git a/packages/cli/src/plugin-build.ts b/packages/cli/src/plugin-build.ts index 6683e587..25a68912 100644 --- a/packages/cli/src/plugin-build.ts +++ b/packages/cli/src/plugin-build.ts @@ -8,7 +8,6 @@ import { acquireLock } from "./plugin-index"; import type { BuildDiagnostic } from "../../build/src/diagnostics"; const builder = fileURLToPath(new URL("../../build/src/build.ts", import.meta.url)); -const checkout = fileURLToPath(new URL("../../../", import.meta.url)); const prefix = "Tokamak build result: "; type BuildResult = { ok: true; outputFolder?: string } | { ok: false; diagnostics: BuildDiagnostic[] }; @@ -19,21 +18,28 @@ export async function runBuilder( next = mode === "--result-json" ? "tokamak plugin build --help" : "tokamak plugin add --help", ) { const processResult = promisify(execFile)(process.execPath, [builder, mode, resolve(folder)], { - // Keep Vite’s generated module labels independent of the invocation folder. - cwd: checkout, maxBuffer: 16 * 1024 * 1024, }); processResult.child.stdin?.end(); - const { stdout, failed } = await processResult.then( - ({ stdout }) => ({ stdout, failed: false }), - (error: { stdout?: string }) => ({ stdout: error.stdout ?? "", failed: true }), + const { stdout, stderr, failed } = await processResult.then( + ({ stdout, stderr }) => ({ stdout, stderr, failed: false }), + (error: { stdout?: string; stderr?: string }) => ({ + stdout: error.stdout ?? "", + stderr: error.stderr ?? "", + failed: true, + }), ); + if (stderr) process.stderr.write(stderr); const record = stdout .split("\n") .reverse() .find((line) => line.startsWith(prefix)); const result: BuildResult | undefined = record ? JSON.parse(record.slice(prefix.length)) : undefined; - if (result?.ok && !failed) return result; + if (result?.ok && !failed) + return { + ...result, + warnings: [...stderr.matchAll(/^Warning: (.+)$/gm)].map((match) => match[1]!), + }; throw new CommandError( mode === "--result-json" ? "Plugin build failed" : "Could not add plugin", next, diff --git a/packages/cli/tests/cli.test.mjs b/packages/cli/tests/cli.test.mjs index 523fb2d7..de71cbcd 100644 --- a/packages/cli/tests/cli.test.mjs +++ b/packages/cli/tests/cli.test.mjs @@ -363,6 +363,91 @@ test("reload tells the user how to add an unknown plugin", async () => { }); }); +test("build and pack run Vite hooks from the plugin folder", async () => { + await withPlugin(async (plugin, root) => { + await mkdir(join(plugin, "node_modules/@tokamak"), { recursive: true }); + await symlink(join(workspace, "packages/build"), join(plugin, "node_modules/@tokamak/build"), "junction"); + const id = "a".repeat(240); + const descriptor = join(plugin, "plugin.ts"); + await writeFile(descriptor, (await readFile(descriptor, "utf8")).replace("outside-fixture", id)); + await writeFile(join(plugin, "local-input.txt"), "read from the plugin folder"); + await writeFile( + join(plugin, "vite.config.ts"), + `import { readFileSync } from "node:fs"; + import { tokamak } from "@tokamak/build/vite"; + export default { plugins: [tokamak({ ui: false }), { + name: "local-input", + buildStart() { + this.emitFile({ type: "asset", fileName: "local-output.txt", source: readFileSync("local-input.txt") }); + }, + }] };`, + ); + for (const command of ["build", "pack"]) { + const result = cli(root, ["plugin", command, plugin, "--json"], {}, root); + expect(result.code, result.stderr).toBe(0); + const value = JSON.parse(result.stdout); + expect(value.ok).toBe(true); + if (command === "pack") expect(value.path).toBe(join(root, `${id}-0.1.0.zip`)); + expect(await readFile(join(plugin, "dist/local-output.txt"), "utf8")).toBe( + "read from the plugin folder", + ); + } + }); +}, 60_000); + +test("identical plugins in different temp folders produce identical ZIP bytes and build ids", async () => { + await withPlugin(async (first, firstRoot) => { + const descriptor = join(first, "plugin.ts"); + await writeFile( + descriptor, + (await readFile(descriptor, "utf8")).replace("id:", 'runtime: "worker", id:'), + ); + await writeFile( + join(first, "src/server/ping.ts"), + 'import { action } from "@tokamak/sdk"; export const ping = action({ handler: () => 42 });', + ); + await withPlugin(async (second, secondRoot) => { + const nested = join(second, "nested", "copy"); + await mkdir(dirname(nested), { recursive: true }); + await cp(first, nested, { recursive: true }); + const pack = (root, folder) => { + const result = cli(root, ["plugin", "pack", folder, "--json"], {}, root); + expect(result.code, result.stderr).toBe(0); + return JSON.parse(result.stdout); + }; + const a = pack(firstRoot, first); + const b = pack(secondRoot, nested); + expect(b.buildId).toBe(a.buildId); + expect((await readFile(a.path)).equals(await readFile(b.path))).toBe(true); + }); + }); +}, 60_000); + +test("pack reports the bad descriptor field's line without writing a ZIP", async () => { + await withPlugin(async (plugin, root) => { + const file = join(plugin, "plugin.ts"); + for (const [id, version, line, message] of [ + ["outside-fixture", "1.2.3/odd", 5, "Plugin version must be a semantic version"], + ["Invalid/ID", "1.2.3", 4, "Plugin id must be a stable lowercase identifier"], + ]) { + await writeFile( + file, + `import { definePlugin } from "@tokamak/sdk";\n\nexport default definePlugin({\n id: "${id}",\n version: "${version}",\n});\n`, + ); + const result = cli(root, ["plugin", "pack", plugin, "--json"], {}, root); + expect(result.code).not.toBe(0); + expect(JSON.parse(result.stdout)).toMatchObject({ + ok: false, + error: { + diagnostics: [expect.objectContaining({ file, line, message: expect.stringContaining(message) })], + }, + }); + expect(result.stderr).toContain(`${file}:${line}:`); + expect(await readdir(root)).toEqual(["plugin"]); + } + }); +}); + test("pack reports the source location of a failed build without writing a ZIP", async () => { await withPlugin(async (plugin, root) => { const file = join(plugin, "src/server/broken.ts"); @@ -384,19 +469,27 @@ test("pack reports the source location of a failed build without writing a ZIP", test("reload applies index additions and removals without a restart", async () => { await withPlugin(async (plugin, root) => { + const warning = /direct import "@ui-sdk\/solid".*Prefer @tokamak\/ui/; + const windowEntry = join(plugin, "src/client/api.tsx"); + await writeFile(windowEntry, 'import "@ui-sdk/solid";\n' + (await readFile(windowEntry, "utf8"))); const run = (...args) => { const result = cli(root, ["plugin", ...args, "--json"]); expect(result.code, result.stderr).toBe(0); + if (args[0] === "reload" && args[1]) expect(result.stderr).toMatch(warning); return JSON.parse(result.stdout); }; + const built = cli(root, ["plugin", "build", plugin, "--json"]); + expect(built.code, built.stderr).toBe(0); + expect(built.stderr).toMatch(warning); + expect(JSON.parse(built.stdout).ok).toBe(true); const digest = (bytes) => createHash("sha256").update(bytes).digest("hex"); const dist = join(plugin, "dist"); - await mkdir(dist); await writeFile(join(dist, "stale.txt"), "An old file left in dist"); const pack = (cwd, ...args) => { const result = cli(root, ["plugin", "pack", ...args, "--json"], {}, cwd); expect(result.code, result.stderr).toBe(0); expect(result.stderr).toContain("Packed outside-fixture"); + expect(result.stderr).toMatch(warning); return JSON.parse(result.stdout); }; const packed = pack(root, "plugin"); @@ -424,13 +517,18 @@ test("reload applies index additions and removals without a restart", async () = for (const [name, hash] of Object.entries(hashes)) { const bytes = unzip("-p", zip, name); expect(digest(bytes)).toBe(hash); - if (name.endsWith(".map")) expect(JSON.parse(bytes.toString())).not.toHaveProperty("sourcesContent"); + if (name.endsWith(".map")) { + const map = JSON.parse(bytes.toString()); + expect(map.sourcesContent).toHaveLength(map.sources.length); + expect(map.sources.every((source) => !source.startsWith("/") && !source.startsWith(".."))).toBe(true); + } } await withServer(root, async () => { run("add", plugin); expect(run("reload", "outside-fixture")).toMatchObject({ plugins: [{ id: "outside-fixture", status: "loaded", buildId: packed.buildId }], + warnings: [expect.stringMatching(warning)], }); expect(run("list").plugins).toEqual([{ id: "outside-fixture", version: "0.1.0", fromIndex: true }]); expect(run("reload", "outside-fixture").plugins).toEqual([ @@ -973,7 +1071,7 @@ test("records worker and embedded plugin output in order and clears only the rel expect.objectContaining({ level: "error", source: "server", - text: expect.stringMatching(/failure:save.*fixture mutation failed/s), + text: expect.stringMatching(/failure:save.*fixture mutation failed.*src\/server\/failure\.ts:15:/s), }), ]); expect(run("logs", "outside-fixture").entries).toContainEqual( @@ -1014,7 +1112,7 @@ test("records worker and embedded plugin output in order and clears only the rel ); } expect((await invoke(address, token, "action", "worker-fixture/flood:malformed")).Err).toMatch( - /mapped worker failure[\s\S]*flood\.ts:\d+/, + /mapped worker failure[\s\S]*src\/server\/flood\.ts:9:/, ); expect(await invoke(address, token, "action", "worker-fixture/flood:ping")).toEqual({ Ok: 42 }); const long = ( diff --git a/packages/sdk/src/plugin.ts b/packages/sdk/src/plugin.ts index 3e1e563a..6e7618bc 100644 --- a/packages/sdk/src/plugin.ts +++ b/packages/sdk/src/plugin.ts @@ -39,6 +39,15 @@ function versionSyntax(version: string): boolean { ); } +export class PluginDefinitionError extends Error { + constructor( + readonly field: keyof PluginDefinition, + message: string, + ) { + super(message); + } +} + export function definePlugin( authored: Omit & { readonly depends?: PluginDefinition["depends"] | readonly string[]; @@ -48,7 +57,7 @@ export function definePlugin( for (const key of ["depends", "optional"] as const) { const ids = authored[key]; if (Array.isArray(ids) && (ids.some((id) => typeof id !== "string") || new Set(ids).size !== ids.length)) - throw new Error(`Invalid plugin ${key} requirements`); + throw new PluginDefinitionError(key, `Invalid plugin ${key} requirements`); } let definition: PluginDefinition = { ...authored, @@ -65,7 +74,7 @@ export function definePlugin( typeof definition.id !== "string" || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(definition.id) ) { - throw new Error("Plugin id must be a stable lowercase identifier"); + throw new PluginDefinitionError("id", "Plugin id must be a stable lowercase identifier"); } const fields = [ "id", @@ -89,7 +98,7 @@ export function definePlugin( throw new Error("Unsupported plugin descriptor field"); } if (typeof definition.version !== "string" || !versionSyntax(definition.version)) { - throw new Error("Plugin version must be a semantic version"); + throw new PluginDefinitionError("version", "Plugin version must be a semantic version"); } validateRequirements(definition); validateLists(definition); @@ -117,7 +126,7 @@ function validateRequirements(definition: PluginDefinition) { !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(id) || typeof range !== "string" || !range, ) ) { - throw new Error(`Invalid plugin ${key} requirements`); + throw new PluginDefinitionError(key, `Invalid plugin ${key} requirements`); } } } @@ -131,16 +140,16 @@ function validateLists(definition: PluginDefinition) { list.some((value) => typeof value !== "string" || !value) || new Set(list).size !== list.length) ) - throw new Error(`Invalid plugin ${key}`); + throw new PluginDefinitionError(key, `Invalid plugin ${key}`); } } function validateMetadata(definition: PluginDefinition) { if (definition.runtime !== undefined && definition.runtime !== "worker") - throw new Error("Invalid plugin runtime"); + throw new PluginDefinitionError("runtime", "Invalid plugin runtime"); for (const field of ["name", "description", "maintenance"] as const) if (definition[field] !== undefined && typeof definition[field] !== "string") - throw new Error(`Invalid plugin ${field}`); + throw new PluginDefinitionError(field, `Invalid plugin ${field}`); if ( definition.api !== undefined && (typeof definition.api !== "string" || !definition.api.startsWith("tokamak@"))