@fluid-app/fluid-cli-droplets 0.1.123 → 0.1.124

package/dist/index.mjs

@@ -17,7 +17,7 @@ function dropletInstallationsPath(dropletUuid) {
 function installationPath(installationUuid) {
 	return `${INSTALLATIONS_PATH}/${encodeURIComponent(installationUuid)}`;
 }
-function apiStatus(error) {
+function apiStatus$1(error) {
 	const status = error.status;
 	return typeof status === "number" ? status : void 0;
 }
@@ -34,7 +34,7 @@ async function installDroplet(client, dropletUuid, roleUuid) {
 			installation: (await client.post(dropletInstallationsPath(dropletUuid), { installation })).droplet_installation
 		};
 	} catch (error) {
-		if (apiStatus(error) === 409) return {
+		if (apiStatus$1(error) === 409) return {
 			installed: true,
 			alreadyInstalled: true,
 			dropletUuid
@@ -77,7 +77,7 @@ async function resolveInstallation(client, uuid) {
 	try {
 		return (await findInstallation(client, uuid))?.uuid ?? null;
 	} catch (error) {
-		if (apiStatus(error) === 403) throw new DropletsCliError(`Finding the installation of ${uuid} needs the droplets.view permission. Pass the installation's uuid (dri_…) instead.`);
+		if (apiStatus$1(error) === 403) throw new DropletsCliError(`Finding the installation of ${uuid} needs the droplets.view permission. Pass the installation's uuid (dri_…) instead.`);
 		throw error;
 	}
 }
@@ -90,7 +90,7 @@ async function preflightInstallation(client, dropletUuid) {
 	try {
 		return await findInstallation(client, dropletUuid);
 	} catch (error) {
-		if (apiStatus(error) === 403) return void 0;
+		if (apiStatus$1(error) === 403) return void 0;
 		throw error;
 	}
 }
@@ -114,7 +114,7 @@ async function uninstallDroplet(client, installationUuid) {
 			installation: (await client.delete(installationPath(installationUuid))).droplet_installation
 		};
 	} catch (error) {
-		if (apiStatus(error) === 404) throw notInstalled(installationUuid);
+		if (apiStatus$1(error) === 404) throw notInstalled(installationUuid);
 		throw error;
 	}
 }
@@ -159,10 +159,10 @@ function fail(err) {
 	}) + "\n");
 	process.exitCode = 1;
 }
-function run(action) {
+function run$1(action) {
 	return action().catch(fail);
 }
-async function dropletsClient(ctx) {
+async function dropletsClient$1(ctx) {
 	return await ctx.getClient();
 }
 /**
@@ -170,8 +170,8 @@ async function dropletsClient(ctx) {
 * v2026-10 company API, next to the generated `installations` commands.
 */
 function registerInstallCommands(parent, ctx) {
-	parent.command("install <droplet_uuid>").description("Install a droplet for this company; it receives the scopes it requests (changes live config)").option("--role <role_uuid>", "The role the droplet acts with, by its uuid; a new role is made when left out").option("--yes", "Confirm without a prompt", false).action((dropletUuid, opts) => run(async () => {
-		const client = await dropletsClient(ctx);
+	parent.command("install <droplet_uuid>").description("Install a droplet for this company; it receives the scopes it requests (changes live config)").option("--role <role_uuid>", "The role the droplet acts with, by its uuid; a new role is made when left out").option("--yes", "Confirm without a prompt", false).action((dropletUuid, opts) => run$1(async () => {
+		const client = await dropletsClient$1(ctx);
 		const existing = await preflightInstallation(client, dropletUuid);
 		if (existing) {
 			ctx.output({
@@ -184,16 +184,146 @@ function registerInstallCommands(parent, ctx) {
 		await confirmChange(`Install droplet ${dropletUuid} for this company?`, opts.yes);
 		ctx.output(await installDroplet(client, dropletUuid, opts.role));
 	}));
-	parent.command("uninstall <uuid>").description("Uninstall a droplet by its uuid or its installation's uuid (dri_…); its credentials are revoked and it is sent its uninstall webhook (changes live config)").option("--yes", "Confirm without a prompt", false).action((uuid, opts) => run(async () => {
-		const client = await dropletsClient(ctx);
+	parent.command("uninstall <uuid>").description("Uninstall a droplet by its uuid or its installation's uuid (dri_…); its credentials are revoked and it is sent its uninstall webhook (changes live config)").option("--yes", "Confirm without a prompt", false).action((uuid, opts) => run$1(async () => {
+		const client = await dropletsClient$1(ctx);
 		const installationUuid = await resolveInstallation(client, uuid);
 		if (!installationUuid) throw notInstalled(uuid);
 		await confirmChange(`Uninstall ${installationUuid} from this company?`, opts.yes);
 		ctx.output(await uninstallDroplet(client, installationUuid));
 	}));
-	parent.command("installed").description("List the droplets this company has installed; --full for full installation rows, every page").option("--full", "Full rows (status, scopes, role), including installations being removed", false).option("--category <slug>", "With --full, only droplets in this category").action((opts) => run(async () => {
+	parent.command("installed").description("List the droplets this company has installed; --full for full installation rows, every page").option("--full", "Full rows (status, scopes, role), including installations being removed", false).option("--category <slug>", "With --full, only droplets in this category").action((opts) => run$1(async () => {
 		if (opts.category && !opts.full) throw new DropletsCliError("--category needs --full.");
-		ctx.output(await listInstallations(await dropletsClient(ctx), opts));
+		ctx.output(await listInstallations(await dropletsClient$1(ctx), opts));
+	}));
+}
+//#endregion
+//#region src/publish/api.ts
+/**
+* Asking Fluid to publish a droplet, and a root admin's review of those
+* requests, through the v2026-10 APIs
+* (apps/rails/docs/openapi/v2026-10/company-droplets.yaml and the root-admin
+* droplet spec).
+*/
+const PUBLISH_REQUESTS_PATH = "/api/root_admin/v2026-10/droplet-publish-requests";
+/** The publisher's request to publish lives under the droplet. */
+function publishRequestPath(dropletUuid) {
+	return `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}/publish-request`;
+}
+function reviewPath(requestId, decision) {
+	return `${PUBLISH_REQUESTS_PATH}/${encodeURIComponent(requestId)}/${decision}`;
+}
+function apiStatus(error) {
+	const status = error.status;
+	return typeof status === "number" ? status : void 0;
+}
+/** Publish review is released per publishing company; without it the
+*  request endpoints answer 404. */
+function notAvailable(dropletUuid) {
+	return new DropletsCliError(`${dropletUuid} is not one of this company's droplets, or asking Fluid to publish is not turned on for this company.`);
+}
+/**
+* Ask Fluid to publish a draft or internal droplet. Asking again while a
+* request waits returns that request.
+*/
+async function requestPublish(client, dropletUuid) {
+	try {
+		return {
+			requested: true,
+			publish_request: (await client.post(publishRequestPath(dropletUuid))).publish_request
+		};
+	} catch (error) {
+		if (apiStatus(error) === 404) throw notAvailable(dropletUuid);
+		throw error;
+	}
+}
+/** Withdraw the request to publish that is waiting. */
+async function withdrawPublish(client, dropletUuid) {
+	try {
+		await client.delete(publishRequestPath(dropletUuid));
+		return {
+			withdrawn: true,
+			droplet_uuid: dropletUuid
+		};
+	} catch (error) {
+		if (apiStatus(error) === 404) throw new DropletsCliError(`${dropletUuid} has no request to publish waiting, or is not one of this company's droplets.`);
+		throw error;
+	}
+}
+/**
+* Where a droplet stands: its status, whether this company can ask Fluid to
+* publish it, and Fluid's latest decision (with the reason once rejected).
+*/
+async function publishStatus(client, dropletUuid) {
+	const detail = await client.get(`/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}`);
+	return {
+		droplet_uuid: dropletUuid,
+		status: detail.droplet?.status,
+		publish_review_available: detail.droplet?.publish_review_available === true,
+		latest_publish_review: detail.droplet?.latest_publish_review ?? null
+	};
+}
+/** Requests to publish in a state (pending when left out), oldest first,
+*  every page. Root admin only. */
+async function listPublishRequests(client, options = {}) {
+	const filter = {
+		state: options.state ?? "pending",
+		...options.droplet ? { droplet_uuid: options.droplet } : {}
+	};
+	const rows = [];
+	let cursor;
+	for (let page = 0; page < 100; page += 1) {
+		const response = await client.get(PUBLISH_REQUESTS_PATH, {
+			filter,
+			...cursor ? { page: { cursor } } : {}
+		});
+		rows.push(...response.publish_requests ?? []);
+		cursor = response.meta?.pagination?.next_cursor;
+		if (!cursor) return rows;
+	}
+	throw new DropletsCliError(`Stopped after 100 pages of publish requests.`);
+}
+/** Approve a request, which publishes the droplet, or reject it with a
+*  reason its publisher is told. Root admin only. */
+async function decidePublishRequest(client, requestId, decision, reason) {
+	if (decision === "reject" && !reason?.trim()) throw new DropletsCliError("Say why with --reason.");
+	return (await client.post(reviewPath(requestId, decision), decision === "reject" ? { reason } : void 0)).publish_request;
+}
+//#endregion
+//#region src/commands/publish.ts
+function run(action) {
+	return action().catch(fail);
+}
+async function dropletsClient(ctx) {
+	return await ctx.getClient();
+}
+/**
+* `fluid droplets request-publish|withdraw-publish|publish-status` for a
+* droplet's publisher, and `fluid droplets publish-requests
+* list|approve|reject` for a Fluid root admin.
+*/
+function registerPublishCommands(parent, ctx) {
+	parent.command("request-publish <droplet_uuid>").description("Ask Fluid to publish a draft or internal droplet to the marketplace; Fluid reviews it first").option("--yes", "Confirm without a prompt", false).action((dropletUuid, opts) => run(async () => {
+		await confirmChange(`Ask Fluid to publish ${dropletUuid} to the marketplace?`, opts.yes);
+		ctx.output(await requestPublish(await dropletsClient(ctx), dropletUuid));
+	}));
+	parent.command("withdraw-publish <droplet_uuid>").description("Withdraw a droplet's request to be published").option("--yes", "Confirm without a prompt", false).action((dropletUuid, opts) => run(async () => {
+		await confirmChange(`Withdraw the request to publish ${dropletUuid}?`, opts.yes);
+		ctx.output(await withdrawPublish(await dropletsClient(ctx), dropletUuid));
+	}));
+	parent.command("publish-status <droplet_uuid>").description("Show a droplet's status and Fluid's latest publish decision, with the reason when rejected").action((dropletUuid) => run(async () => {
+		ctx.output(await publishStatus(await dropletsClient(ctx), dropletUuid));
+	}));
+	const review = parent.command("publish-requests").description("Review droplets asking to be published (Fluid root admins)");
+	review.command("list").description("List requests to publish, oldest first").option("--state <state>", "pending, approved, rejected, withdrawn or superseded", "pending").option("--droplet <droplet_uuid>", "Only this droplet's requests").action((opts) => run(async () => {
+		ctx.output(await listPublishRequests(await dropletsClient(ctx), opts));
+	}));
+	review.command("approve <request_id>").description("Approve a request, publishing the droplet (changes live config)").option("--yes", "Confirm without a prompt", false).action((requestId, opts) => run(async () => {
+		await confirmChange(`Approve ${requestId} and publish the droplet?`, opts.yes);
+		ctx.output(await decidePublishRequest(await dropletsClient(ctx), requestId, "approve"));
+	}));
+	review.command("reject <request_id>").description("Reject a request; the publisher is told the reason").requiredOption("--reason <text>", "Why it was rejected").option("--yes", "Confirm without a prompt", false).action((requestId, opts) => run(async () => {
+		await confirmChange(`Reject ${requestId}?`, opts.yes);
+		ctx.output(await decidePublishRequest(await dropletsClient(ctx), requestId, "reject", opts.reason));
 	}));
 }
 //#endregion
@@ -332,6 +462,7 @@ const plugin = {
 		ctx.program.addCommand(createDomainCommand("droplets", "Manage Fluid droplets and installations", (parent, cmdCtx) => {
 			registerAllCommands(parent, cmdCtx);
 			registerInstallCommands(parent, cmdCtx);
+			registerPublishCommands(parent, cmdCtx);
 		}));
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-droplets",
-  "version": "0.1.123",
+  "version": "0.1.124",
   "description": "Fluid CLI commands for droplet management",
   "type": "module",
   "main": "./dist/index.mjs",

package/src/__tests__/publish-api.test.ts

@@ -0,0 +1,222 @@
+import { DropletsCliError, type DropletsClient } from "../install/api";
+import {
+  decidePublishRequest,
+  listPublishRequests,
+  PUBLISH_REQUESTS_PATH,
+  publishRequestPath,
+  publishStatus,
+  requestPublish,
+  reviewPath,
+  withdrawPublish,
+} from "../publish/api";
+
+type Call = {
+  method: string;
+  endpoint: string;
+  body?: unknown;
+  params?: unknown;
+};
+
+/** Answers each request from a queue per `METHOD endpoint`; an Error is thrown. */
+function fakeClient(responses: Record<string, unknown[]> = {}) {
+  const calls: Call[] = [];
+  const respond = (method: string, endpoint: string) => {
+    const queue = responses[`${method} ${endpoint}`];
+    const value = queue && queue.length > 0 ? queue.shift() : {};
+    if (value instanceof Error) throw value;
+    return value;
+  };
+  const client: DropletsClient = {
+    get: async <T>(endpoint: string, params?: Record<string, unknown>) => {
+      calls.push({ method: "GET", endpoint, params });
+      return respond("GET", endpoint) as T;
+    },
+    post: async <T>(endpoint: string, body?: unknown) => {
+      calls.push({ method: "POST", endpoint, body });
+      return respond("POST", endpoint) as T;
+    },
+    delete: async <T>(endpoint: string) => {
+      calls.push({ method: "DELETE", endpoint });
+      return respond("DELETE", endpoint) as T;
+    },
+  };
+  return { client, calls };
+}
+
+const apiError = (status: number) =>
+  Object.assign(new Error(`HTTP ${status}`), { status });
+
+const review = {
+  id: "0199a1b2-0000-7000-8000-000000000001",
+  state: "pending",
+  status_before: "internal",
+  reason: null,
+  requested_at: "2026-10-22T10:00:00Z",
+  decided_at: null,
+};
+
+describe("requestPublish", () => {
+  it("asks under the droplet and returns the request", async () => {
+    const path = publishRequestPath("drp_1");
+    const { client, calls } = fakeClient({
+      [`POST ${path}`]: [{ publish_request: review }],
+    });
+
+    await expect(requestPublish(client, "drp_1")).resolves.toEqual({
+      requested: true,
+      publish_request: review,
+    });
+    expect(calls).toEqual([{ method: "POST", endpoint: path }]);
+  });
+
+  it("explains a 404: not the company's droplet, or not turned on", async () => {
+    const { client } = fakeClient({
+      [`POST ${publishRequestPath("drp_1")}`]: [apiError(404)],
+    });
+
+    await expect(requestPublish(client, "drp_1")).rejects.toBeInstanceOf(
+      DropletsCliError,
+    );
+  });
+
+  it("passes other failures on", async () => {
+    const { client } = fakeClient({
+      [`POST ${publishRequestPath("drp_1")}`]: [apiError(422)],
+    });
+
+    await expect(requestPublish(client, "drp_1")).rejects.toMatchObject({
+      status: 422,
+    });
+  });
+});
+
+describe("withdrawPublish", () => {
+  it("deletes the waiting request", async () => {
+    const path = publishRequestPath("drp_1");
+    const { client, calls } = fakeClient({ [`DELETE ${path}`]: [undefined] });
+
+    await expect(withdrawPublish(client, "drp_1")).resolves.toEqual({
+      withdrawn: true,
+      droplet_uuid: "drp_1",
+    });
+    expect(calls).toEqual([{ method: "DELETE", endpoint: path }]);
+  });
+
+  it("says when nothing is waiting", async () => {
+    const { client } = fakeClient({
+      [`DELETE ${publishRequestPath("drp_1")}`]: [apiError(404)],
+    });
+
+    await expect(withdrawPublish(client, "drp_1")).rejects.toThrow(
+      /no request to publish waiting/,
+    );
+  });
+});
+
+describe("publishStatus", () => {
+  it("reads the status and latest decision from the droplet", async () => {
+    const rejected = { ...review, state: "rejected", reason: "No logo" };
+    const { client } = fakeClient({
+      "GET /api/company/v2026-10/droplets/drp_1": [
+        {
+          droplet: {
+            uuid: "drp_1",
+            status: "internal",
+            publish_review_available: true,
+            latest_publish_review: rejected,
+          },
+        },
+      ],
+    });
+
+    await expect(publishStatus(client, "drp_1")).resolves.toEqual({
+      droplet_uuid: "drp_1",
+      status: "internal",
+      publish_review_available: true,
+      latest_publish_review: rejected,
+    });
+  });
+
+  it("reads review as unavailable when the fields are missing", async () => {
+    const { client } = fakeClient({
+      "GET /api/company/v2026-10/droplets/drp_1": [
+        { droplet: { uuid: "drp_1", status: "draft" } },
+      ],
+    });
+
+    await expect(publishStatus(client, "drp_1")).resolves.toMatchObject({
+      publish_review_available: false,
+      latest_publish_review: null,
+    });
+  });
+});
+
+describe("listPublishRequests", () => {
+  it("lists pending requests, following every page", async () => {
+    const second = { ...review, id: "0199a1b2-0000-7000-8000-000000000002" };
+    const { client, calls } = fakeClient({
+      [`GET ${PUBLISH_REQUESTS_PATH}`]: [
+        {
+          publish_requests: [review],
+          meta: { pagination: { next_cursor: "c2" } },
+        },
+        { publish_requests: [second], meta: { pagination: {} } },
+      ],
+    });
+
+    await expect(listPublishRequests(client)).resolves.toEqual([
+      review,
+      second,
+    ]);
+    expect(calls.map((call) => call.params)).toEqual([
+      { filter: { state: "pending" } },
+      { filter: { state: "pending" }, page: { cursor: "c2" } },
+    ]);
+  });
+
+  it("filters by state and droplet", async () => {
+    const { client, calls } = fakeClient();
+
+    await listPublishRequests(client, { state: "rejected", droplet: "drp_1" });
+
+    expect(calls[0]?.params).toEqual({
+      filter: { state: "rejected", droplet_uuid: "drp_1" },
+    });
+  });
+});
+
+describe("decidePublishRequest", () => {
+  it("approves without a body", async () => {
+    const path = reviewPath(review.id, "approve");
+    const { client, calls } = fakeClient({
+      [`POST ${path}`]: [{ publish_request: { ...review, state: "approved" } }],
+    });
+
+    await expect(
+      decidePublishRequest(client, review.id, "approve"),
+    ).resolves.toMatchObject({ state: "approved" });
+    expect(calls).toEqual([
+      { method: "POST", endpoint: path, body: undefined },
+    ]);
+  });
+
+  it("rejects with the reason", async () => {
+    const path = reviewPath(review.id, "reject");
+    const { client, calls } = fakeClient({
+      [`POST ${path}`]: [{ publish_request: { ...review, state: "rejected" } }],
+    });
+
+    await decidePublishRequest(client, review.id, "reject", "No logo");
+
+    expect(calls[0]?.body).toEqual({ reason: "No logo" });
+  });
+
+  it("refuses a rejection without a reason before calling the API", async () => {
+    const { client, calls } = fakeClient();
+
+    await expect(
+      decidePublishRequest(client, review.id, "reject", "  "),
+    ).rejects.toThrow("Say why with --reason.");
+    expect(calls).toEqual([]);
+  });
+});

package/src/commands/publish.ts

@@ -0,0 +1,135 @@
+import type { Command } from "commander";
+import type { CommandContext } from "@fluid-app/fluid-cli";
+
+import type { DropletsClient } from "../install/api.js";
+import {
+  decidePublishRequest,
+  listPublishRequests,
+  publishStatus,
+  requestPublish,
+  withdrawPublish,
+} from "../publish/api.js";
+import { confirmChange, fail } from "./install.js";
+
+function run(action: () => Promise<void>): Promise<void> {
+  return action().catch(fail);
+}
+
+async function dropletsClient(ctx: CommandContext): Promise<DropletsClient> {
+  return (await ctx.getClient()) as unknown as DropletsClient;
+}
+
+/**
+ * `fluid droplets request-publish|withdraw-publish|publish-status` for a
+ * droplet's publisher, and `fluid droplets publish-requests
+ * list|approve|reject` for a Fluid root admin.
+ */
+export function registerPublishCommands(
+  parent: Command,
+  ctx: CommandContext,
+): void {
+  parent
+    .command("request-publish <droplet_uuid>")
+    .description(
+      "Ask Fluid to publish a draft or internal droplet to the marketplace; Fluid reviews it first",
+    )
+    .option("--yes", "Confirm without a prompt", false)
+    .action((dropletUuid: string, opts: { yes: boolean }) =>
+      run(async () => {
+        await confirmChange(
+          `Ask Fluid to publish ${dropletUuid} to the marketplace?`,
+          opts.yes,
+        );
+        ctx.output(
+          await requestPublish(await dropletsClient(ctx), dropletUuid),
+        );
+      }),
+    );
+
+  parent
+    .command("withdraw-publish <droplet_uuid>")
+    .description("Withdraw a droplet's request to be published")
+    .option("--yes", "Confirm without a prompt", false)
+    .action((dropletUuid: string, opts: { yes: boolean }) =>
+      run(async () => {
+        await confirmChange(
+          `Withdraw the request to publish ${dropletUuid}?`,
+          opts.yes,
+        );
+        ctx.output(
+          await withdrawPublish(await dropletsClient(ctx), dropletUuid),
+        );
+      }),
+    );
+
+  parent
+    .command("publish-status <droplet_uuid>")
+    .description(
+      "Show a droplet's status and Fluid's latest publish decision, with the reason when rejected",
+    )
+    .action((dropletUuid: string) =>
+      run(async () => {
+        ctx.output(await publishStatus(await dropletsClient(ctx), dropletUuid));
+      }),
+    );
+
+  const review = parent
+    .command("publish-requests")
+    .description("Review droplets asking to be published (Fluid root admins)");
+
+  review
+    .command("list")
+    .description("List requests to publish, oldest first")
+    .option(
+      "--state <state>",
+      "pending, approved, rejected, withdrawn or superseded",
+      "pending",
+    )
+    .option("--droplet <droplet_uuid>", "Only this droplet's requests")
+    .action((opts: { state: string; droplet?: string }) =>
+      run(async () => {
+        ctx.output(await listPublishRequests(await dropletsClient(ctx), opts));
+      }),
+    );
+
+  review
+    .command("approve <request_id>")
+    .description(
+      "Approve a request, publishing the droplet (changes live config)",
+    )
+    .option("--yes", "Confirm without a prompt", false)
+    .action((requestId: string, opts: { yes: boolean }) =>
+      run(async () => {
+        await confirmChange(
+          `Approve ${requestId} and publish the droplet?`,
+          opts.yes,
+        );
+        ctx.output(
+          await decidePublishRequest(
+            await dropletsClient(ctx),
+            requestId,
+            "approve",
+          ),
+        );
+      }),
+    );
+
+  review
+    .command("reject <request_id>")
+    .description("Reject a request; the publisher is told the reason")
+    .requiredOption("--reason <text>", "Why it was rejected")
+    .option("--yes", "Confirm without a prompt", false)
+    .action((requestId: string, opts: { reason: string; yes: boolean }) =>
+      run(async () => {
+        await confirmChange(`Reject ${requestId}?`, opts.yes);
+        ctx.output(
+          await decidePublishRequest(
+            await dropletsClient(ctx),
+            requestId,
+            "reject",
+            opts.reason,
+          ),
+        );
+      }),
+    );
+}

package/src/index.ts

@@ -2,6 +2,7 @@ import type { FluidPlugin } from "@fluid-app/fluid-cli";
 import { createDomainCommand } from "@fluid-app/fluid-cli";
 
 import { registerInstallCommands } from "./commands/install.js";
+import { registerPublishCommands } from "./commands/publish.js";
 import { registerAllCommands } from "./generated/index.js";
 
 const plugin: FluidPlugin = {
@@ -16,8 +17,10 @@ const plugin: FluidPlugin = {
           registerAllCommands(parent, cmdCtx);
           // Hand-written commands on top of the generated OpenAPI surface:
           // `install`, `uninstall` and `installed`, over the v2026-10
-          // company API.
+          // company API, and asking Fluid to publish a droplet (with the
+          // root admin's review of those requests).
           registerInstallCommands(parent, cmdCtx);
+          registerPublishCommands(parent, cmdCtx);
         },
       ),
     );

package/src/publish/api.ts

@@ -0,0 +1,176 @@
+/**
+ * Asking Fluid to publish a droplet, and a root admin's review of those
+ * requests, through the v2026-10 APIs
+ * (apps/rails/docs/openapi/v2026-10/company-droplets.yaml and the root-admin
+ * droplet spec).
+ */
+
+import { DropletsCliError, type DropletsClient } from "../install/api.js";
+
+/** A publisher's view of a request to publish, on the droplet's detail. */
+export interface PublishReview {
+  id: string;
+  state: string;
+  status_before: string;
+  reason: string | null;
+  requested_at: string;
+  decided_at: string | null;
+}
+
+/** A root admin's view of a request to publish. */
+export interface PublishRequestRow extends PublishReview {
+  droplet?: { uuid: string; name: string | null; status: string };
+  company?: { uuid: string; name: string | null };
+  requested_by?: { uuid: string; name: string | null; email: string } | null;
+  closed_by?: { uuid: string; name: string | null; email: string } | null;
+}
+
+interface DropletDetail {
+  droplet?: {
+    uuid: string;
+    title?: string | null;
+    status?: string;
+    latest_publish_review?: PublishReview | null;
+    publish_review_available?: boolean;
+  };
+}
+
+interface PublishRequestsPage {
+  publish_requests?: PublishRequestRow[];
+  meta?: { pagination?: { next_cursor?: string | null } };
+}
+
+export const PUBLISH_REQUESTS_PATH =
+  "/api/root_admin/v2026-10/droplet-publish-requests";
+
+/** The publisher's request to publish lives under the droplet. */
+export function publishRequestPath(dropletUuid: string): string {
+  return `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}/publish-request`;
+}
+
+export function reviewPath(
+  requestId: string,
+  decision: "approve" | "reject",
+): string {
+  return `${PUBLISH_REQUESTS_PATH}/${encodeURIComponent(requestId)}/${decision}`;
+}
+
+function apiStatus(error: unknown): number | undefined {
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" ? status : undefined;
+}
+
+/** Publish review is released per publishing company; without it the
+ *  request endpoints answer 404. */
+function notAvailable(dropletUuid: string): DropletsCliError {
+  return new DropletsCliError(
+    `${dropletUuid} is not one of this company's droplets, or asking Fluid to publish is not turned on for this company.`,
+  );
+}
+
+/**
+ * Ask Fluid to publish a draft or internal droplet. Asking again while a
+ * request waits returns that request.
+ */
+export async function requestPublish(
+  client: DropletsClient,
+  dropletUuid: string,
+): Promise<{ requested: true; publish_request: PublishReview }> {
+  try {
+    const response = await client.post<{ publish_request: PublishReview }>(
+      publishRequestPath(dropletUuid),
+    );
+    return { requested: true, publish_request: response.publish_request };
+  } catch (error) {
+    if (apiStatus(error) === 404) throw notAvailable(dropletUuid);
+    throw error;
+  }
+}
+
+/** Withdraw the request to publish that is waiting. */
+export async function withdrawPublish(
+  client: DropletsClient,
+  dropletUuid: string,
+): Promise<{ withdrawn: true; droplet_uuid: string }> {
+  try {
+    await client.delete<void>(publishRequestPath(dropletUuid));
+    return { withdrawn: true, droplet_uuid: dropletUuid };
+  } catch (error) {
+    if (apiStatus(error) === 404)
+      throw new DropletsCliError(
+        `${dropletUuid} has no request to publish waiting, or is not one of this company's droplets.`,
+      );
+    throw error;
+  }
+}
+
+/**
+ * Where a droplet stands: its status, whether this company can ask Fluid to
+ * publish it, and Fluid's latest decision (with the reason once rejected).
+ */
+export async function publishStatus(
+  client: DropletsClient,
+  dropletUuid: string,
+): Promise<{
+  droplet_uuid: string;
+  status: string | undefined;
+  publish_review_available: boolean;
+  latest_publish_review: PublishReview | null;
+}> {
+  const detail = await client.get<DropletDetail>(
+    `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}`,
+  );
+  return {
+    droplet_uuid: dropletUuid,
+    status: detail.droplet?.status,
+    publish_review_available: detail.droplet?.publish_review_available === true,
+    latest_publish_review: detail.droplet?.latest_publish_review ?? null,
+  };
+}
+
+/** Stop paging after this many pages, so a cursor that never ends cannot
+ *  loop forever. */
+export const MAX_PAGES = 100;
+
+/** Requests to publish in a state (pending when left out), oldest first,
+ *  every page. Root admin only. */
+export async function listPublishRequests(
+  client: DropletsClient,
+  options: { state?: string; droplet?: string } = {},
+): Promise<PublishRequestRow[]> {
+  const filter = {
+    state: options.state ?? "pending",
+    ...(options.droplet ? { droplet_uuid: options.droplet } : {}),
+  };
+  const rows: PublishRequestRow[] = [];
+  let cursor: string | null | undefined;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const response = await client.get<PublishRequestsPage>(
+      PUBLISH_REQUESTS_PATH,
+      { filter, ...(cursor ? { page: { cursor } } : {}) },
+    );
+    rows.push(...(response.publish_requests ?? []));
+    cursor = response.meta?.pagination?.next_cursor;
+    if (!cursor) return rows;
+  }
+  throw new DropletsCliError(
+    `Stopped after ${MAX_PAGES} pages of publish requests.`,
+  );
+}
+
+/** Approve a request, which publishes the droplet, or reject it with a
+ *  reason its publisher is told. Root admin only. */
+export async function decidePublishRequest(
+  client: DropletsClient,
+  requestId: string,
+  decision: "approve" | "reject",
+  reason?: string,
+): Promise<PublishRequestRow> {
+  if (decision === "reject" && !reason?.trim())
+    throw new DropletsCliError("Say why with --reason.");
+  const response = await client.post<{ publish_request: PublishRequestRow }>(
+    reviewPath(requestId, decision),
+    decision === "reject" ? { reason } : undefined,
+  );
+  return response.publish_request;
+}