@drift-beacon/plugin 0.1.0

package/dist/internal/package-layout.js

@@ -0,0 +1,19 @@
+/**
+ * The plugin package: `manifest.json`, `package.json`, `main/index.js` (plus chunks) and `ui/index.html`
+ * (plus assets and the manifest icon). Shared by the pack tool and the server. Pure: the web app bundles
+ * `/internal`, so no `node:` imports.
+ */
+export const PACKAGE_LIMITS = {
+    entries: 2000,
+    fileBytes: 32 * 2 ** 20,
+    totalBytes: 128 * 2 ** 20,
+    archiveBytes: 32 * 2 ** 20,
+    manifestBytes: 256 * 2 ** 10,
+};
+/** The `package.json` every package gets: main is ESM. */
+export const PACKAGE_JSON = { type: "module", private: true };
+export const REQUIRED_FILES = ["main/index.js", "ui/index.html"];
+/** manifest.json, package.json, main/** and ui/** (directories: main, ui and below). `name` has no trailing slash. */
+export const isPackagePath = (name, directory) => name.startsWith("main/") ||
+    name.startsWith("ui/") ||
+    (directory ? name === "main" || name === "ui" : name === "manifest.json" || name === "package.json");

package/dist/internal/protocol.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Messages between a plugin UI (iframe) and the web app hosting it, over `postMessage`.
+ *
+ * The UI client ships inside every published UI bundle, so this protocol is frozen into
+ * them: change it only additively within an API version. The UI opens with `hello`; nothing
+ * else flows until the host answers `welcome` or `reject`.
+ */
+import type { PluginErrorCode, PluginInfo, UserInfo, WorkspaceInfo } from "../types.ts";
+import type { WorkspaceRows } from "./rows.ts";
+/** Marks our messages so both sides ignore unrelated `postMessage` traffic (dev tools, HMR). */
+export declare const UI_CHANNEL = "drift-beacon-plugin";
+/** Workspace data sent to a UI, as rows. */
+export type UiData = WorkspaceRows;
+export type UiRequest = {
+    readonly method: "sessions.start";
+    readonly params: {
+        readonly activityId: string;
+    };
+} | {
+    readonly method: "sessions.end";
+    readonly params: {
+        readonly sessionId: string;
+    };
+} | {
+    readonly method: "sessions.mark";
+    readonly params: {
+        readonly activityId: string;
+    };
+} | {
+    readonly method: "sessions.discard";
+    readonly params: {
+        readonly sessionId: string;
+    };
+} | {
+    readonly method: "storage.set";
+    readonly params: {
+        readonly key: string;
+        readonly value: unknown;
+    };
+} | {
+    readonly method: "storage.remove";
+    readonly params: {
+        readonly key: string;
+    };
+};
+export type UiToHostMessage = {
+    readonly channel: typeof UI_CHANNEL;
+    readonly type: "hello";
+    readonly apiVersion: string;
+} | ({
+    readonly channel: typeof UI_CHANNEL;
+    readonly type: "request";
+    readonly id: string;
+} & UiRequest);
+export interface UiError {
+    readonly code: PluginErrorCode;
+    readonly message: string;
+}
+export type HostToUiMessage = {
+    readonly channel: typeof UI_CHANNEL;
+    readonly type: "welcome";
+    readonly apiVersion: string;
+    readonly plugin: PluginInfo;
+    readonly user: UserInfo;
+    readonly workspace: WorkspaceInfo;
+    readonly config: Readonly<Record<string, unknown>>;
+    readonly data: UiData;
+    readonly storage: Readonly<Record<string, unknown>>;
+} | {
+    readonly channel: typeof UI_CHANNEL;
+    readonly type: "reject";
+    readonly reason: string;
+}
+/** The app restarted its side of the connection; the UI answers with `hello` and gets a new `welcome`. */
+ | {
+    readonly channel: typeof UI_CHANNEL;
+    readonly type: "reconnect";
+} | {
+    /** Replaces whichever parts are present. */
+    readonly channel: typeof UI_CHANNEL;
+    readonly type: "state";
+    readonly config?: Readonly<Record<string, unknown>>;
+    readonly data?: UiData;
+    readonly storage?: Readonly<Record<string, unknown>>;
+} | {
+    readonly channel: typeof UI_CHANNEL;
+    readonly type: "response";
+    readonly id: string;
+    readonly result?: unknown;
+    readonly error?: UiError;
+};
+export declare function isUiMessage(value: unknown): value is {
+    channel: typeof UI_CHANNEL;
+    type: string;
+};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/internal/protocol.js

@@ -0,0 +1,8 @@
+/** Marks our messages so both sides ignore unrelated `postMessage` traffic (dev tools, HMR). */
+export const UI_CHANNEL = "drift-beacon-plugin";
+export function isUiMessage(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.channel === UI_CHANNEL &&
+        typeof value.type === "string");
+}

package/dist/internal/rows.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Workspace data as it travels from the app to plugins: to plugin hosts over IPC and to plugin
+ * UIs over `postMessage`. Plugins never see rows; the model layer (`models.ts`) wraps them.
+ */
+import type { ActivityData, CategoryData } from "../types.ts";
+export type ActivityRow = ActivityData;
+export type CategoryRow = CategoryData;
+export interface SessionRow {
+    readonly id: string;
+    readonly activityId: string;
+    readonly type: "span" | "point";
+    readonly status: "live" | "completed";
+    readonly memberIds: readonly string[];
+    /** ISO timestamp: when a span started, or when a point was marked. */
+    readonly startedAt: string;
+    /** ISO timestamp when a span ended; null while live and for points. */
+    readonly endedAt: string | null;
+}
+export interface WorkspaceRows {
+    readonly activities: readonly ActivityRow[];
+    readonly categories: readonly CategoryRow[];
+    readonly sessions: readonly SessionRow[];
+}
+/** One change to a collection of rows. */
+export type RowChange<T> = {
+    readonly type: "added";
+    readonly item: T;
+} | {
+    readonly type: "updated";
+    readonly item: T;
+    readonly previous: T;
+} | {
+    readonly type: "removed";
+    readonly item: T;
+};
+export interface WorkspaceRowChanges {
+    readonly activities: readonly RowChange<ActivityRow>[];
+    readonly categories: readonly RowChange<CategoryRow>[];
+    readonly sessions: readonly RowChange<SessionRow>[];
+}
+//# sourceMappingURL=rows.d.ts.map

package/dist/internal/rows.js

@@ -0,0 +1 @@
+export {};

package/dist/internal.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Platform-only entry used by the plugin host, the web app and the server. Not part of the plugin API.
+ * Public entries never import this file; SDK modules may import `internal/*` directly. Publishing drops
+ * only its export key.
+ */
+export * from "./dev.ts";
+export type { PluginAction } from "./internal/actions.ts";
+export { Collection } from "./internal/collection.ts";
+export { type ApiCompatibility, type ApiVersion, checkApiCompatibility, parseApiVersion, SUPPORTED_API_VERSIONS, } from "./internal/compatibility.ts";
+export { jsonEqual } from "./internal/json-equal.ts";
+export { type BooleanConfigurationItem, type ConfigurationItem, type DropdownConfigurationItem, isStableVersion, type NumberConfigurationItem, type PluginManifest, type StringConfigurationItem, validateManifest, } from "./internal/manifest.ts";
+export { type ModelApis, type ModelChanges, type SessionActions, type WorkspaceCollections, WorkspaceModels, } from "./internal/models.ts";
+export { isPackagePath, PACKAGE_JSON, PACKAGE_LIMITS, REQUIRED_FILES } from "./internal/package-layout.ts";
+export * from "./internal/protocol.ts";
+export type { ActivityRow, CategoryRow, RowChange, SessionRow, WorkspaceRowChanges, WorkspaceRows, } from "./internal/rows.ts";
+export type { PluginErrorCode } from "./types.ts";
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.js

@@ -0,0 +1,13 @@
+/**
+ * Platform-only entry used by the plugin host, the web app and the server. Not part of the plugin API.
+ * Public entries never import this file; SDK modules may import `internal/*` directly. Publishing drops
+ * only its export key.
+ */
+export * from "./dev.js";
+export { Collection } from "./internal/collection.js";
+export { checkApiCompatibility, parseApiVersion, SUPPORTED_API_VERSIONS, } from "./internal/compatibility.js";
+export { jsonEqual } from "./internal/json-equal.js";
+export { isStableVersion, validateManifest, } from "./internal/manifest.js";
+export { WorkspaceModels, } from "./internal/models.js";
+export { isPackagePath, PACKAGE_JSON, PACKAGE_LIMITS, REQUIRED_FILES } from "./internal/package-layout.js";
+export * from "./internal/protocol.js";

package/dist/main.d.ts

@@ -0,0 +1,92 @@
+import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, Session, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+export type SessionEndReason = "completed" | "discarded";
+export interface MainSessionsApi extends SessionsApi {
+    /**
+     * A user just started a span session. Live events fire for actions happening now, never for
+     * sessions that arrive later from a client's offline sync.
+     */
+    onStarted(callback: (session: Session) => void): Unsubscribe;
+    /** A span session just ended or was discarded. */
+    onEnded(callback: (session: Session, reason: SessionEndReason) => void): Unsubscribe;
+    /** A point activity was just marked. */
+    onMarked(callback: (session: Session) => void): Unsubscribe;
+}
+export type MqttStatus = "connecting" | "connected" | "disconnected" | "error" | "unavailable";
+export interface MqttMessage {
+    readonly topic: string;
+    readonly payload: string;
+}
+export interface MqttApi {
+    /** Subscribe to a topic filter. `+` matches one level and `#` the remaining levels. */
+    subscribe(topic: string, callback: (message: MqttMessage) => void): Unsubscribe;
+    /** Rejects when no broker is configured or the broker refuses the message. */
+    publish(topic: string, payload: string): Promise<void>;
+    /** `unavailable` when no broker is configured for the workspace. */
+    readonly status: MqttStatus;
+    onStatusChange(callback: (status: MqttStatus) => void): Unsubscribe;
+}
+export interface RouteRequest {
+    readonly method: "GET" | "POST";
+    /** Parsed JSON body for POST requests. */
+    readonly body: unknown;
+    readonly query: Readonly<Record<string, string>>;
+    /** Request headers, without credentials such as `authorization` and `cookie`. */
+    readonly headers: Readonly<Record<string, string>>;
+}
+export interface RouteResponse {
+    /** Defaults to 200. */
+    readonly status?: number;
+    /** Sent as JSON. */
+    readonly body?: unknown;
+}
+export type RouteHandler = (request: RouteRequest) => RouteResponse | Promise<RouteResponse>;
+export interface RoutesApi {
+    /** Serve `GET <apiPath>/<name>`. Callers authenticate with a workspace API key. */
+    get(name: string, handler: RouteHandler): void;
+    /** Serve `POST <apiPath>/<name>`. Callers authenticate with a workspace API key. */
+    post(name: string, handler: RouteHandler): void;
+}
+export interface LogApi {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/** Everything a plugin's main code can use. One `ctx` per instance: a plugin for one user in one workspace. */
+export interface MainContext {
+    readonly plugin: PluginInfo;
+    readonly user: UserInfo;
+    readonly workspace: WorkspaceInfo;
+    /** The plugin's settings, validated, with defaults applied. A change restarts the instance. */
+    readonly config: Readonly<PluginConfig>;
+    readonly activities: ActivitiesApi;
+    readonly categories: CategoriesApi;
+    readonly sessions: MainSessionsApi;
+    /** Called once after each update to workspace data. */
+    onDataChange(callback: () => void): Unsubscribe;
+    readonly storage: StorageApi;
+    readonly mqtt: MqttApi;
+    readonly routes: RoutesApi;
+    readonly log: LogApi;
+    /**
+     * Run when the instance stops: disabled, reconfigured, updated or shut down. `ctx` still works
+     * while stop callbacks run; afterwards every subscription made through it is released.
+     */
+    onStop(callback: () => void | Promise<void>): void;
+}
+export interface PluginDefinition {
+    /** Called once per instance. Register everything through `ctx`; it is released when the instance stops. */
+    onStart(ctx: MainContext): void | Promise<void>;
+}
+/**
+ * Define a plugin's main code. Export the result as the module's default export:
+ *
+ * ```ts
+ * export default definePlugin({
+ *   onStart(ctx) {
+ *     ctx.mqtt.subscribe(ctx.config.mqttTopic, (message) => ctx.log.info(message.payload));
+ *   },
+ * });
+ * ```
+ */
+export declare function definePlugin(definition: PluginDefinition): PluginDefinition;
+//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -0,0 +1,14 @@
+/**
+ * Define a plugin's main code. Export the result as the module's default export:
+ *
+ * ```ts
+ * export default definePlugin({
+ *   onStart(ctx) {
+ *     ctx.mqtt.subscribe(ctx.config.mqttTopic, (message) => ctx.log.info(message.payload));
+ *   },
+ * });
+ * ```
+ */
+export function definePlugin(definition) {
+    return definition;
+}

package/dist/pack.d.ts

@@ -0,0 +1,24 @@
+export interface PackResult {
+    readonly id: string;
+    readonly version: string;
+    readonly tag: string;
+    readonly asset: string;
+    readonly archivePath: string;
+}
+/**
+ * Zip the package in `dir` into `<outDir>/<id>.zip`: its manifest, a generated `package.json`, and `main/**`
+ * and `ui/**`. Anything else in `dir` (the dev marker, its `package.json`) is left out. Never runs plugin code.
+ */
+export declare function packDirectory(dir: string, outDir: string): Promise<PackResult>;
+export interface PackOptions {
+    /** Where the zip goes. Default `<root>/releases`. */
+    readonly out?: string;
+}
+/**
+ * Build a release of the plugin package at `root`: prepare, typecheck main and UI with the package's own
+ * TypeScript, `vite build` into a fresh temp folder with the package's own Vite, then `packDirectory`. The
+ * package's `dist/` is never read or written. Everything printed meanwhile goes to stderr, so a caller's
+ * stdout carries only the result.
+ */
+export declare function pack(root: string, options?: PackOptions): Promise<PackResult>;
+//# sourceMappingURL=pack.d.ts.map

package/dist/pack.js

@@ -0,0 +1,131 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Release packaging. `packDirectory` zips a finished package folder (`dbplugin pack` and the server's
+ * `plugin:install`); `pack` typechecks a plugin package, builds it fresh into a temp folder and packs that.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { lstat, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { strToU8, zipSync } from "fflate";
+import { PACKAGE_JSON, PACKAGE_LIMITS, REQUIRED_FILES } from "./internal/package-layout.js";
+import { loadManifest, prepare } from "./prepare.js";
+/**
+ * Zip the package in `dir` into `<outDir>/<id>.zip`: its manifest, a generated `package.json`, and `main/**`
+ * and `ui/**`. Anything else in `dir` (the dev marker, its `package.json`) is left out. Never runs plugin code.
+ */
+export async function packDirectory(dir, outDir) {
+    const source = path.resolve(dir);
+    const { manifest, bytes: manifestBytes } = loadManifest(source);
+    const files = Object.create(null);
+    files["manifest.json"] = manifestBytes;
+    const packageBytes = strToU8(`${JSON.stringify(PACKAGE_JSON, null, 2)}\n`);
+    files["package.json"] = packageBytes;
+    let totalBytes = manifestBytes.length + packageBytes.length;
+    let entries = 2;
+    const names = new Set(["manifest.json", "package.json"]);
+    const collect = async (relativePath) => {
+        if (relativePath.length > 512 ||
+            /[\\:]/.test(relativePath) ||
+            [...relativePath].some((char) => char.charCodeAt(0) < 32))
+            throw new Error(`Unsupported package path: ${relativePath}`);
+        const absolute = path.join(source, relativePath);
+        const stat = await lstat(absolute);
+        if (stat.isSymbolicLink())
+            throw new Error(`Package cannot contain symlinks: ${relativePath}`);
+        if (stat.isDirectory()) {
+            for (const name of (await readdir(absolute)).sort()) {
+                if (name === "node_modules")
+                    throw new Error("Bundle dependencies instead of packaging node_modules");
+                await collect(`${relativePath}/${name}`);
+            }
+        }
+        else if (stat.isFile()) {
+            if (names.has(relativePath.toLowerCase()))
+                throw new Error(`Duplicate package path: ${relativePath}`);
+            names.add(relativePath.toLowerCase());
+            totalBytes += stat.size;
+            entries += 1;
+            if (stat.size > PACKAGE_LIMITS.fileBytes)
+                throw new Error(`File exceeds 32 MiB: ${relativePath}`);
+            if (totalBytes > PACKAGE_LIMITS.totalBytes || entries > PACKAGE_LIMITS.entries) {
+                throw new Error("Plugin exceeds package size/entry limits");
+            }
+            files[relativePath] = await readFile(absolute);
+        }
+        else {
+            throw new Error(`Package contains an unsupported file: ${relativePath}`);
+        }
+    };
+    const top = new Set(await readdir(source));
+    for (const part of ["main", "ui"])
+        if (top.has(part))
+            await collect(part);
+    for (const required of REQUIRED_FILES) {
+        if (!files[required])
+            throw new Error(`Missing ${required}`);
+    }
+    if (manifest.icon !== "" && !files[`ui/${manifest.icon}`]) {
+        throw new Error(`manifest.json names icon ${manifest.icon}, but ui/public/${manifest.icon} is missing`);
+    }
+    const asset = `${manifest.id}.zip`;
+    const archivePath = path.join(path.resolve(outDir), asset);
+    const archive = zipSync(files, { level: 6 });
+    if (archive.length > PACKAGE_LIMITS.archiveBytes)
+        throw new Error("Compressed package exceeds 32 MiB");
+    await mkdir(path.dirname(archivePath), { recursive: true });
+    await writeFile(archivePath, archive);
+    return { id: manifest.id, version: manifest.version, tag: `${manifest.id}-${manifest.version}`, asset, archivePath };
+}
+/**
+ * Build a release of the plugin package at `root`: prepare, typecheck main and UI with the package's own
+ * TypeScript, `vite build` into a fresh temp folder with the package's own Vite, then `packDirectory`. The
+ * package's `dist/` is never read or written. Everything printed meanwhile goes to stderr, so a caller's
+ * stdout carries only the result.
+ */
+export async function pack(root, options = {}) {
+    const pkg = path.resolve(root);
+    const write = process.stdout.write;
+    process.stdout.write = process.stderr.write.bind(process.stderr);
+    let temp;
+    try {
+        prepare(pkg, { strict: true });
+        const require = createRequire(path.join(pkg, "package.json"));
+        // Found through its package.json `bin`: TypeScript 7 doesn't export `typescript/bin/tsc`.
+        const typescript = require.resolve("typescript/package.json");
+        const { bin } = JSON.parse(await readFile(typescript, "utf8"));
+        const tsc = path.join(path.dirname(typescript), bin.tsc);
+        for (const project of ["tsconfig.main.json", "tsconfig.ui.json"]) {
+            const result = spawnSync(process.execPath, [tsc, "-p", path.join(".drift-beacon", project)], {
+                cwd: pkg,
+                stdio: ["ignore", 2, 2],
+            });
+            if (result.error)
+                throw result.error;
+            if (result.status !== 0)
+                throw new Error(`Type errors (.drift-beacon/${project}); nothing was packed`);
+        }
+        temp = await mkdtemp(path.join(tmpdir(), "dbplugin-pack-"));
+        const vite = await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("vite")).href));
+        await vite.build({ root: pkg, mode: "production", logLevel: "warn", build: { outDir: temp } });
+        if (!existsSync(path.join(temp, "main/index.js"))) {
+            throw new Error("vite build produced no main/index.js: add driftBeacon() to vite.config.ts");
+        }
+        return await packDirectory(temp, options.out ?? path.join(pkg, "releases"));
+    }
+    finally {
+        process.stdout.write = write;
+        if (temp)
+            await rm(temp, { recursive: true, force: true });
+    }
+}

package/dist/prepare.d.ts

@@ -0,0 +1,28 @@
+import { type PluginManifest } from "./internal/manifest.ts";
+export interface PrepareOptions {
+    /**
+     * Throw on manifest problems (dev, build and pack). When false (`dbplugin prepare`, run on install), warn
+     * and leave `.drift-beacon/` as it was, so a manifest typo never fails `pnpm install`.
+     */
+    readonly strict: boolean;
+}
+/** A package's `manifest.json`: parsed and checked, with its bytes. */
+export interface LoadedManifest {
+    readonly manifest: PluginManifest;
+    readonly bytes: Buffer;
+}
+/**
+ * Generate `<root>/.drift-beacon/` from the manifest, and return the manifest (`loadManifest`). Files are
+ * rewritten only when their content changes.
+ */
+export declare function prepare(root: string, options: {
+    readonly strict: true;
+}): LoadedManifest;
+export declare function prepare(root: string, options: PrepareOptions): LoadedManifest | null;
+/**
+ * `<root>/manifest.json`, the one read of a manifest in the SDK (dev, build, prepare and pack): a regular
+ * file within the package limit, valid, and for an `apiVersion` this SDK runs (the server's check). The
+ * error names the file.
+ */
+export declare function loadManifest(root: string): LoadedManifest;
+//# sourceMappingURL=prepare.d.ts.map

package/dist/prepare.js

@@ -0,0 +1,121 @@
+/**
+ * Writes a plugin package's generated `.drift-beacon/` folder: `config.d.ts` (the `ctx.config` types from
+ * manifest.json), the main and UI tsconfigs, and a `.gitignore` that ignores the folder itself. Also reads
+ * and checks manifests for `driftBeacon()` and `dbplugin pack` (`loadManifest`).
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { checkApiCompatibility } from "./internal/compatibility.js";
+import { validateManifest } from "./internal/manifest.js";
+import { PACKAGE_LIMITS } from "./internal/package-layout.js";
+import { API_VERSION } from "./version.js";
+const COMPILER_OPTIONS = {
+    target: "ES2023",
+    module: "Preserve",
+    moduleResolution: "Bundler",
+    moduleDetection: "force",
+    strict: true,
+    skipLibCheck: true,
+    noEmit: true,
+    verbatimModuleSyntax: true,
+    allowImportingTsExtensions: true,
+    noFallthroughCasesInSwitch: true,
+    noUncheckedSideEffectImports: true,
+};
+// Explicit `types` keep UI typings (React, three.js) out of main; `vite/client` allows CSS and asset imports in the UI.
+const TSCONFIG_MAIN = {
+    compilerOptions: { ...COMPILER_OPTIONS, lib: ["ES2023"], types: ["node"] },
+    include: ["../main/src", "../vite.config.ts", "./config.d.ts"],
+};
+const TSCONFIG_UI = {
+    compilerOptions: {
+        ...COMPILER_OPTIONS,
+        lib: ["ES2022", "DOM", "DOM.Iterable"],
+        jsx: "react-jsx",
+        useDefineForClassFields: true,
+        types: ["vite/client"],
+    },
+    include: ["../ui/src", "./config.d.ts"],
+};
+export function prepare(root, { strict }) {
+    let loaded;
+    try {
+        loaded = loadManifest(root);
+    }
+    catch (error) {
+        if (strict)
+            throw error;
+        console.warn(`${error.message}\nLeft .drift-beacon/ unchanged; fix manifest.json and run dbplugin prepare.`);
+        return null;
+    }
+    const { manifest } = loaded;
+    const out = path.join(root, ".drift-beacon");
+    mkdirSync(out, { recursive: true });
+    writeIfChanged(path.join(out, ".gitignore"), "*\n");
+    writeIfChanged(path.join(out, "config.d.ts"), configTypes(manifest.configuration));
+    writeIfChanged(path.join(out, "tsconfig.main.json"), `${JSON.stringify(TSCONFIG_MAIN, null, 2)}\n`);
+    writeIfChanged(path.join(out, "tsconfig.ui.json"), `${JSON.stringify(TSCONFIG_UI, null, 2)}\n`);
+    return loaded;
+}
+/**
+ * `<root>/manifest.json`, the one read of a manifest in the SDK (dev, build, prepare and pack): a regular
+ * file within the package limit, valid, and for an `apiVersion` this SDK runs (the server's check). The
+ * error names the file.
+ */
+export function loadManifest(root) {
+    const file = path.join(root, "manifest.json");
+    let manifest;
+    let bytes;
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile())
+            throw new Error("must be a regular file");
+        if (stat.size > PACKAGE_LIMITS.manifestBytes)
+            throw new Error("exceeds 256 KiB");
+        bytes = readFileSync(file);
+        manifest = JSON.parse(bytes.toString("utf8"));
+        validateManifest(manifest);
+    }
+    catch (error) {
+        const reason = error.code === "ENOENT" ? "not found" : error.message;
+        throw new Error(`${file}: ${reason}`, { cause: error });
+    }
+    const compatibility = checkApiCompatibility(manifest.apiVersion, [API_VERSION]);
+    if (!compatibility.compatible)
+        throw new Error(`${file}: ${compatibility.message}`);
+    return { manifest, bytes };
+}
+/**
+ * Augments the SDK's `PluginConfig`. Mirrors the server's config validation: a setting can be missing
+ * unless it is required or has a default. The type-only import makes this a module, so `declare module`
+ * augments instead of declaring an ambient module, and it loads the SDK entry into every program: the UI
+ * imports only `@drift-beacon/plugin/ui`, and an augmentation of a module the program never loads has no effect.
+ */
+function configTypes(configuration) {
+    const lines = [
+        "// Generated by dbplugin prepare from manifest.json. Do not edit.",
+        'import type {} from "@drift-beacon/plugin";',
+        'declare module "@drift-beacon/plugin" {',
+        "  interface PluginConfig {",
+    ];
+    for (const item of configuration) {
+        const doc = [item.title, item.description].filter(Boolean).join(": ").replaceAll("*/", "*\\/");
+        if (doc)
+            lines.push(`    /** ${doc} */`);
+        const optional = item.required === true || item.default !== undefined ? "" : "?";
+        lines.push(`    ${JSON.stringify(item.name)}${optional}: ${valueType(item)};`);
+    }
+    lines.push("  }", "}", "");
+    return lines.join("\n");
+}
+const valueType = (item) => item.type !== "dropdown"
+    ? item.type
+    : item.data.length === 0
+        ? "string"
+        : [...new Set(item.data.map((option) => JSON.stringify(option.value)))].join(" | ");
+/** Leaves the file (and its mtime) alone when it already has `content`, so editors and watchers stay quiet. */
+function writeIfChanged(file, content) {
+    if (existsSync(file) && readFileSync(file, "utf8") === content)
+        return;
+    writeFileSync(file, content);
+}