@50arms/plugin-sdk 0.0.0-stage → 0.2.53

package/dist/publish.d.ts

@@ -0,0 +1,246 @@
+/** The lockfiles a project may carry; the archive must hold one so the download installs the exact versions it was built with. */
+declare const LOCKFILE_NAMES: string[];
+/**
+ * The files of a plugin project's source archive, sorted. Inside git: tracked plus untracked-unignored. Outside git: everything the top-level
+ * `.gitignore` does not ignore. Both drop `node_modules`, `.git`, a top-level `dist` and every `.env*` file.
+ */
+declare function sourceFiles(projectDir: string): Promise<string[]>;
+/** The project's source as a gzip-compressed tar archive, ready for `source_archive_base64`. The same files give the same bytes (fixed mtime, `portable`). */
+declare function archiveSource(projectDir: string): Promise<Buffer>;
+
+/** The names of the surface-wide settings, one per member of {@link SurfaceWideSettings} (a new member fails `tsc` here). */
+declare const SURFACE_WIDE_SETTING_KEYS: readonly ["date_range", "keyword"];
+type SurfaceWideSettingKey = (typeof SURFACE_WIDE_SETTING_KEYS)[number];
+
+/**
+ * DX-6233 / DX-6269 (PLAN-96 G-6) - the schema a Widget's config and settings are declared in, and the check of a value against it. Import-free of Node: the
+ * app imports this module at runtime (`@backend/widget-surfaces/value-schema.js`) to draw a placement's form and to check what is stored, and the server
+ * imports the same module to refuse a write the schema rejects, so the two can never disagree about what a Widget accepts.
+ *
+ * Every field carries its default, so the schema is also where a Widget's defaults live. A value is checked as a (possibly partial) set of the schema's
+ * fields: a key the schema does not name, or a value of the wrong type, is an issue, never read as a default.
+ */
+/**
+ * DX-6254 - the words that name a field, or one option of a field: a built-in Widget's message id, which the app looks up in the person's language, or the text a
+ * plugin's author wrote (a plugin brings no message catalog). The Configure form shows these, never a field's key or an option's stored id.
+ */
+type FieldText = {
+    readonly messageId: string;
+} | {
+    readonly text: string;
+};
+type ValueField = {
+    readonly type: "string";
+    readonly label: FieldText;
+    readonly default: string;
+    readonly maxLength?: number;
+    readonly enum?: readonly string[];
+    /** The words for each option of `enum`, by option id; present exactly when `enum` is, naming every option and no other. The stored value is the id. */
+    readonly optionLabels?: Readonly<Record<string, FieldText>>;
+} | {
+    readonly type: "number";
+    readonly label: FieldText;
+    readonly default: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly integer?: boolean;
+} | {
+    readonly type: "boolean";
+    readonly label: FieldText;
+    readonly default: boolean;
+};
+type ValueSchema = Readonly<Record<string, ValueField>>;
+
+/**
+ * DX-6269 (PLAN-96 G-6) - the layout rules of a widget surface, as pure functions: snapping to whole cells, a Widget's size limits, collision, clamping and the
+ * first free space. Import-free of Node. The app runs them live while a placement is dragged or resized (so what the person sees while dragging is what is
+ * saved), and the server runs the same functions to check every layout write and to place a new or changed placement, so the two never disagree.
+ *
+ * Positions are 0-based cells; the grid is `GRID_COLUMNS` wide with unlimited rows. A layout never has two boxes overlapping: moving, resizing or changing a
+ * box pushes whatever it now overlaps down to just below it, and whatever that one now overlaps in turn. The box being edited never moves for another.
+ */
+
+interface Size {
+    w: number;
+    h: number;
+}
+
+/**
+ * DX-6269 (PLAN-96 G-6; DX-6233 finding (d)) - a Widget's DECLARATION: the part of a Widget that is data - its key, the sizes it may take, its config and
+ * settings schemas, the surface-wide settings it reads and the host context it needs. The component that draws it, its title and its description are the
+ * app's (`frontend/src/lib/widgets/catalog.ts`). Import-free of Node, so the app, the server and DX-6254's plugin SDK all read the one declaration: the app
+ * to draw the Widget and its forms, the server to refuse a placement write the declaration rejects.
+ */
+
+type CellSize = Size;
+interface WidgetDeclaration<C extends ValueSchema = ValueSchema, S extends ValueSchema = ValueSchema> {
+    /** Stable identity, stored on every placement: lowercase words joined by `-` for a built-in, `plugin:<plugin key>:<widget key>` for a plugin's (`pluginWidgetKey`). */
+    readonly key: string;
+    /** The size a new placement gets, and the smallest and largest one may take, in cells. */
+    readonly size: {
+        readonly default: CellSize;
+        readonly min: CellSize;
+        readonly max: CellSize;
+    };
+    readonly config: C;
+    readonly settings: S;
+    readonly readsSurfaceSettings: readonly SurfaceWideSettingKey[];
+    /** The host context keys the Widget cannot render without. */
+    readonly needsHostContext: readonly string[];
+}
+
+/**
+ * DX-5170 / DX-4679 section 2 - the shape of `danx-plugin.json`, the manifest `@50arms/plugin-sdk` writes beside a built plugin and the
+ * upload validator (DX-5171) checks before a revision is stored: the entry module and every listed file present with the stated size and
+ * sha256, nothing unlisted, and `runtime` naming the majors the plugin was built against (`runtime-contract.ts`).
+ *
+ * Pure types and constants; the writer is the SDK's, the checks are the server's.
+ */
+
+/** One file of the built plugin, other than the manifest itself (a file cannot hold its own hash). */
+interface PluginManifestFile {
+    /** Relative to the output folder, `/` separated. */
+    readonly path: string;
+    readonly size: number;
+    /** Lowercase hex. */
+    readonly sha256: string;
+}
+declare const PLUGIN_VIEW_EXPORTS: readonly ["CardView", "CardListView"];
+type PluginViewExport = (typeof PLUGIN_VIEW_EXPORTS)[number];
+interface PluginManifest {
+    /** The ES module the app `import()`s, a `path` in `files`. */
+    readonly entry: string;
+    /** The stylesheets to add with the module, each a `path` in `files`; empty when the plugin ships none. */
+    readonly styles: readonly string[];
+    /** DX-5171: a screenshot taken at publish, a listed `.png` or `.webp` shown to the approver; absent when there is none. */
+    readonly screenshot?: string;
+    /** Each shared library's major the plugin was built against (`PLUGIN_RUNTIME_LIBRARIES`), compared with what the app serves. */
+    readonly runtime: Readonly<Record<string, number>>;
+    /**
+     * DX-6178: the card types the plugin's `CardView` is made for (card type keys, e.g. `["Bug"]`); absent when it is made for none. Each is that type's DEFAULT view
+     * while the plugin's active revision is approved and exports `CardView`: the admin's card-view board shows it as the type's "Default" and reverts to it.
+     * Where two plugins declare one type, the one activated first wins (`plugins.activated_at`).
+     */
+    readonly cardTypes?: readonly string[];
+    /** DX-5282: which view modules the entry exports (`PLUGIN_VIEW_EXPORTS`), recorded at build from the entry chunk's real exports; empty only for a plugin that declares Widgets. */
+    readonly exports: readonly PluginViewExport[];
+    /** DX-6254: the Widgets the plugin adds to the Widget Library, each drawn by one of the entry's exports; empty when it adds none. Checked by `manifestWidgetIssues`. */
+    readonly widgets: readonly PluginManifestWidget[];
+    readonly files: readonly PluginManifestFile[];
+}
+/** DX-6254: one Widget a plugin declares. Its words are the author's own text: a plugin brings no message catalog. */
+interface PluginManifestWidget {
+    /** The name of the entry's export that draws the Widget, recorded at build only when the entry chunk really exports it. */
+    readonly export: string;
+    readonly title: string;
+    /** One sentence for the Widget Library: what the Widget shows. */
+    readonly description: string;
+    /** The built-in Widgets' own declaration, with `key` the Widget's key inside the plugin; a placement stores `plugin:<plugin key>:<key>`. */
+    readonly declaration: WidgetDeclaration;
+}
+
+/** The project's build output folder: the SDK's Vite preset builds into Vite's default `dist`. */
+declare const PLUGIN_DIST_DIR = "dist";
+/** One built file, as the upload route takes it. */
+interface BuiltFile {
+    readonly path: string;
+    readonly bytes: Buffer;
+}
+interface BuiltPlugin {
+    readonly manifest: PluginManifest;
+    readonly files: readonly BuiltFile[];
+}
+/**
+ * Runs the project's own `npm run build` in a short-lived child process (the DX-4727 pattern): everything Vite loads belongs to that
+ * process and is released when it exits, so the long-lived MCP server never holds a file of the plugin's project. A non-zero exit
+ * rejects with the tail of the build's output.
+ */
+declare function runProjectBuild(projectDir: string): Promise<void>;
+/**
+ * Reads what a build left in `<projectDir>/dist`: the `danx-plugin.json` manifest the `danxPlugin()` preset wrote and the bytes of every
+ * file it lists. Whether the manifest is valid is the dashboard's to say (`manifest-validation.ts`); this only refuses a build that left
+ * no manifest, because there is nothing to upload then.
+ */
+declare function readBuiltPlugin(projectDir: string): Promise<BuiltPlugin>;
+/** Builds the project and reads the result. */
+declare function buildPlugin(projectDir: string): Promise<BuiltPlugin>;
+
+/** Where a screenshot lands in the bundle; the manifest's `screenshot` field names it (DX-5171). */
+declare const PLUGIN_SCREENSHOT_FILE = "screenshot.png";
+/**
+ * The built plugin with a screenshot added to the upload: the PNG joins the files, and the manifest lists it (size and sha256 like every other
+ * file) and names it in `screenshot`. Only the upload carries it; the project's `dist/` is untouched, so a rebuild from the source download
+ * yields the same files minus this one.
+ */
+declare function withScreenshot(built: BuiltPlugin, png: Buffer): BuiltPlugin;
+
+/**
+ * DX-5237 - the one seam between the publish flow and the dashboard. The MCP tool passes its authenticated `DashboardHttpClient`; the
+ * `danx-plugin` CLI passes {@link fetchTransport}. The flow never builds a URL or a header, so neither caller's credential handling leaks into it.
+ */
+/** A 2xx answer or a 4xx refusal, the body parsed and untouched: a refusal's named reason must reach the caller verbatim. 5xx and network failures throw. */
+interface TransportResult {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly body: unknown;
+}
+interface PluginTransport {
+    request(call: {
+        method: "GET" | "POST";
+        path: string;
+        query?: Record<string, string | number>;
+        body?: unknown;
+    }): Promise<TransportResult>;
+}
+/** A transport over `fetch` for a person's own API key (`Authorization: Bearer`, `.claude/rules/dashboard.md` "Scripting the API"). */
+declare function fetchTransport(config: {
+    baseUrl: string;
+    apiKey: string;
+}, fetchImpl?: typeof fetch): PluginTransport;
+
+/** The Settings page that lists a plugin's revisions and approves them (`frontend/src/app/settings-nav.ts`, `plugins`). */
+declare const PLUGINS_SETTINGS_PATH = "/settings/team/plugins";
+interface PublishInput {
+    /** The plugin's stable key within the team (lowercase letters, digits, - and _). Created on the first publish. */
+    readonly plugin: string;
+    /** The display name given to a plugin this publish creates; ignored when the plugin exists. Defaults to the key. */
+    readonly name?: string;
+    /** What this revision changes, shown to the approver. */
+    readonly note: string;
+    readonly built: BuiltPlugin;
+    /** The project's `source.tar.gz`. */
+    readonly source: Buffer;
+    /** The dashboard's base URL, the front of the approval link. */
+    readonly dashboardUrl: string;
+}
+/** What a published revision answers. */
+interface PublishedRevision {
+    readonly plugin: string;
+    readonly plugin_id: number;
+    readonly revision_id: string;
+    readonly revision_no: number;
+    /** Where a team admin approves it: Settings > Plugins. */
+    readonly approval_url: string;
+}
+/** `ok: true` carries the revision; a refusal is the dashboard's, untouched, with the step it came from (`find`, `create` or `upload`). */
+type PublishResult = {
+    readonly ok: true;
+    readonly status: number;
+    readonly body: PublishedRevision;
+} | {
+    readonly ok: false;
+    readonly status: number;
+    readonly body: unknown;
+    readonly step: "find" | "create" | "upload";
+};
+/** The one rule for a blank note. The MCP tool and the CLI call it first, before the build, so a blank note costs nothing; `uploadRevision` calls it too. */
+declare function assertNote(note: string): void;
+/**
+ * Uploads a built plugin as a new revision: finds the plugin by key (creating it when the key is new), then posts the bundle and its source in
+ * one request. The dashboard is the only validator: a refusal (a manifest rule, a size cap, a runtime-major mismatch, a missing permission)
+ * comes back verbatim in {@link PublishResult}, with the step that was refused.
+ */
+declare function uploadRevision(transport: PluginTransport, input: PublishInput): Promise<PublishResult>;
+
+export { LOCKFILE_NAMES, PLUGINS_SETTINGS_PATH, PLUGIN_DIST_DIR, PLUGIN_SCREENSHOT_FILE, archiveSource, assertNote, buildPlugin, fetchTransport, readBuiltPlugin, runProjectBuild, sourceFiles, uploadRevision, withScreenshot };
+export type { BuiltFile, BuiltPlugin, PluginTransport, PublishInput, PublishResult, PublishedRevision, TransportResult };