@danxbot/plugin-sdk 0.1.3 → 0.1.4

package/dist/publish.d.ts

@@ -0,0 +1,135 @@
+/** 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>;
+
+/** 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;
+}
+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>>;
+    readonly files: readonly PluginManifestFile[];
+}
+
+/** 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 };