@fluid-app/fluid-cli-droplets 0.1.103 → 0.1.104

package/dist/index.mjs

@@ -1,5 +1,202 @@
 import { createDomainCommand } from "@fluid-app/fluid-cli";
+import { createInterface } from "node:readline/promises";
 import "commander";
+//#region src/install/api.ts
+/** A failure the CLI reports as-is, with a non-zero exit. */
+var DropletsCliError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DropletsCliError";
+	}
+};
+const INSTALLATIONS_PATH = "/api/company/v2026-10/droplet-installations";
+/** Installations of a droplet are created under the droplet. */
+function dropletInstallationsPath(dropletUuid) {
+	return `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}/installations`;
+}
+function installationPath(installationUuid) {
+	return `${INSTALLATIONS_PATH}/${encodeURIComponent(installationUuid)}`;
+}
+function apiStatus(error) {
+	const status = error.status;
+	return typeof status === "number" ? status : void 0;
+}
+/**
+* Install a droplet. An installation that already exists answers 409, which
+* is reported rather than raised: the company has what it asked for.
+*/
+async function installDroplet(client, dropletUuid, roleUuid) {
+	const installation = roleUuid ? { role_uuid: roleUuid } : {};
+	try {
+		return {
+			installed: true,
+			alreadyInstalled: false,
+			installation: (await client.post(dropletInstallationsPath(dropletUuid), { installation })).droplet_installation
+		};
+	} catch (error) {
+		if (apiStatus(error) === 409) return {
+			installed: true,
+			alreadyInstalled: true,
+			dropletUuid
+		};
+		throw error;
+	}
+}
+/**
+* The company's installations. Without `full`, the navigation list (uuid,
+* droplet uuid, title and logo of every active installation). With `full`,
+* every installation not yet uninstalled, as full rows, newest first,
+* following `meta.pagination.next_cursor` to the last page.
+*/
+async function listInstallations(client, options = {}) {
+	if (!options.full) return (await client.get("/api/company/v2026-10/droplet-installations")).droplet_installations ?? [];
+	const rows = [];
+	let cursor;
+	for (let page = 0; page < 100; page += 1) {
+		const response = await client.get(INSTALLATIONS_PATH, {
+			view: "full",
+			...options.category ? { filter: { category: options.category } } : {},
+			page: {
+				limit: 100,
+				...cursor ? { cursor } : {}
+			}
+		});
+		rows.push(...response.droplet_installations ?? []);
+		cursor = response.meta?.pagination?.next_cursor;
+		if (!cursor) return rows;
+	}
+	throw new DropletsCliError(`Stopped after 100 pages of installations.`);
+}
+/**
+* The installation an uninstall names: an installation uuid as given, or the
+* company's installation of a droplet uuid, preferring an active one over
+* one already being removed. Null when the droplet is not installed.
+*/
+async function resolveInstallation(client, uuid) {
+	if (uuid.startsWith("dri_")) return 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.`);
+		throw error;
+	}
+}
+/**
+* The installation an install would duplicate, read before asking. Undefined
+* when the list cannot be read (403, no droplets.view): the install then goes
+* straight to the API, which answers 409 for one that exists.
+*/
+async function preflightInstallation(client, dropletUuid) {
+	try {
+		return await findInstallation(client, dropletUuid);
+	} catch (error) {
+		if (apiStatus(error) === 403) return void 0;
+		throw error;
+	}
+}
+/**
+* The company's installation of a droplet, preferring an active one over one
+* already being removed, or null when it has none.
+*/
+async function findInstallation(client, dropletUuid) {
+	const rows = (await listInstallations(client, { full: true })).filter((row) => (row.droplet_uuid ?? row.droplet?.uuid) === dropletUuid);
+	return rows.find((row) => row.status === "active") ?? rows[0] ?? null;
+}
+/**
+* Uninstall: Fluid revokes the installation's credentials and sends the
+* droplet its uninstall webhook. The installation reads `pending_uninstall`
+* until the droplet's cleanup finishes.
+*/
+async function uninstallDroplet(client, installationUuid) {
+	try {
+		return {
+			uninstalled: true,
+			installation: (await client.delete(installationPath(installationUuid))).droplet_installation
+		};
+	} catch (error) {
+		if (apiStatus(error) === 404) throw notInstalled(installationUuid);
+		throw error;
+	}
+}
+function notInstalled(uuid) {
+	return new DropletsCliError(`${uuid} is not installed for this company. List what is installed with \`fluid droplets installed\`.`);
+}
+//#endregion
+//#region src/commands/install.ts
+async function askOnTerminal(question) {
+	const readline = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		const answer = await readline.question(`${question} [y/N] `);
+		return /^y(es)?$/i.test(answer.trim());
+	} finally {
+		readline.close();
+	}
+}
+/**
+* Changes to what a company has installed need an explicit yes, as `fluid
+* connect install` does. Scripts and agents pass `--yes`; an interactive
+* terminal is asked. With neither, nothing runs.
+*/
+async function confirmChange(question, yes, interactive = Boolean(process.stdin.isTTY), ask = askOnTerminal) {
+	if (yes) return;
+	if (!interactive) throw new DropletsCliError(`${question} Pass --yes to confirm.`);
+	if (!await ask(question)) throw new DropletsCliError("Cancelled.");
+}
+/** Print a failure as JSON on stderr and exit non-zero, as `fluid connect`
+*  does. The API's `error.message` and `error.details` are passed on. */
+function fail(err) {
+	const status = err.status;
+	const apiError = err.body?.error;
+	const message = typeof apiError === "string" ? apiError : typeof apiError?.message === "string" ? apiError.message : err instanceof Error ? err.message : String(err);
+	const details = typeof apiError === "object" ? apiError?.details : void 0;
+	process.stderr.write(JSON.stringify({
+		error: message,
+		...typeof status === "number" ? { status } : {},
+		...details && typeof details === "object" && Object.keys(details).length > 0 ? { details } : {}
+	}) + "\n");
+	process.exitCode = 1;
+}
+function run(action) {
+	return action().catch(fail);
+}
+async function dropletsClient(ctx) {
+	return await ctx.getClient();
+}
+/**
+* `fluid droplets install|uninstall|installed`: friendly commands over the
+* 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);
+		const existing = await preflightInstallation(client, dropletUuid);
+		if (existing) {
+			ctx.output({
+				installed: true,
+				alreadyInstalled: true,
+				installation: existing
+			});
+			return;
+		}
+		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);
+		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 () => {
+		if (opts.category && !opts.full) throw new DropletsCliError("--category needs --full.");
+		ctx.output(await listInstallations(await dropletsClient(ctx), opts));
+	}));
+}
+//#endregion
 //#region src/generated/categories.ts
 function registerCategories(parent, ctx) {
 	parent.command("categories").description("categories").command("list").description("Returns a list of all droplet categories").action(async () => {
@@ -132,7 +329,10 @@ const plugin = {
 	name: "@fluid-app/fluid-cli-droplets",
 	version: "0.1.0",
 	register(ctx) {
-		ctx.program.addCommand(createDomainCommand("droplets", "Manage Fluid droplets and installations", registerAllCommands));
+		ctx.program.addCommand(createDomainCommand("droplets", "Manage Fluid droplets and installations", (parent, cmdCtx) => {
+			registerAllCommands(parent, cmdCtx);
+			registerInstallCommands(parent, cmdCtx);
+		}));
 	}
 };
 //#endregion

package/jest.config.cjs

@@ -0,0 +1,13 @@
+module.exports = {
+  testEnvironment: "node",
+  testMatch: ["**/src/**/__tests__/**/*.test.ts"],
+  transform: {
+    "^.+\\.(t|j)sx?$": ["@swc/jest", { module: { type: "commonjs" } }],
+  },
+  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+  moduleNameMapper: {
+    // The real package only ships ESM, which Jest can't resolve in CJS mode.
+    "^@fluid-app/fluid-cli$": "<rootDir>/jest.mocks/fluid-cli.ts",
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+};

package/jest.mocks/fluid-cli.ts

@@ -0,0 +1,10 @@
+/**
+ * Jest mock for @fluid-app/fluid-cli, which only ships ESM. The droplets
+ * plugin's tests exercise its hand-written modules, so the command factory
+ * is inert.
+ */
+export function createDomainCommand(): never {
+  throw new Error(
+    "createDomainCommand is not available in unit tests (droplets)",
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-droplets",
-  "version": "0.1.103",
+  "version": "0.1.104",
   "description": "Fluid CLI commands for droplet management",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -17,13 +17,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@fluid-app/fluid-cli": "0.1.102",
+    "@fluid-app/fluid-cli": "0.1.103",
     "commander": "^12.0.0"
   },
   "devDependencies": {
     "@fluid-app/api-client-scripts": "0.0.0",
     "@fluid-app/typescript-config": "0.0.0",
+    "@swc/core": "^1.15.18",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^29.5.14",
     "@types/node": "24.10.12",
+    "jest": "^29.7.0",
     "tsdown": "^0.21.0",
     "tsx": "^4.21.0",
     "typescript": "^5"
@@ -46,6 +50,16 @@
           }
         ]
       },
+      "test": {
+        "dependsOn": [
+          {
+            "target": "build",
+            "projects": [
+              "@fluid-app/fluid-cli"
+            ]
+          }
+        ]
+      },
       "build": {
         "dependsOn": [
           "typecheck",
@@ -65,6 +79,7 @@
     "generate": "tsx scripts/generate.ts",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
-    "typecheck": "tsgo --noEmit"
+    "typecheck": "tsgo --noEmit",
+    "test": "jest"
   }
 }

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

@@ -0,0 +1,283 @@
+import {
+  dropletInstallationsPath,
+  DropletsCliError,
+  findInstallation,
+  installDroplet,
+  INSTALLATIONS_PATH,
+  installationPath,
+  listInstallations,
+  preflightInstallation,
+  resolveInstallation,
+  uninstallDroplet,
+  type DropletsClient,
+} from "../install/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 };
+}
+
+function apiError(status: number, message = "failed"): Error {
+  return Object.assign(new Error(message), {
+    status,
+    body: { error: { message } },
+  });
+}
+
+const row = (uuid: string, dropletUuid: string, status = "active") => ({
+  uuid,
+  droplet_uuid: dropletUuid,
+  status,
+});
+
+describe("installDroplet", () => {
+  it("posts the role by uuid and returns the installation", async () => {
+    const path = dropletInstallationsPath("drp_order_sync");
+    const { client, calls } = fakeClient({
+      [`POST ${path}`]: [
+        { droplet_installation: row("dri_1", "drp_order_sync") },
+      ],
+    });
+
+    const outcome = await installDroplet(
+      client,
+      "drp_order_sync",
+      "0190c2d3-role",
+    );
+
+    expect(calls).toEqual([
+      {
+        method: "POST",
+        endpoint: path,
+        body: { installation: { role_uuid: "0190c2d3-role" } },
+      },
+    ]);
+    expect(outcome).toEqual({
+      installed: true,
+      alreadyInstalled: false,
+      installation: row("dri_1", "drp_order_sync"),
+    });
+  });
+
+  it("sends an empty installation without a role", async () => {
+    const { client, calls } = fakeClient();
+
+    await installDroplet(client, "drp_order_sync");
+
+    expect(calls[0]?.body).toEqual({ installation: {} });
+  });
+
+  it("reports a 409 as already installed", async () => {
+    const path = dropletInstallationsPath("drp_order_sync");
+    const { client } = fakeClient({
+      [`POST ${path}`]: [apiError(409, "Droplet already installed")],
+    });
+
+    await expect(installDroplet(client, "drp_order_sync")).resolves.toEqual({
+      installed: true,
+      alreadyInstalled: true,
+      dropletUuid: "drp_order_sync",
+    });
+  });
+
+  it("raises any other failure", async () => {
+    const path = dropletInstallationsPath("drp_secret");
+    const { client } = fakeClient({
+      [`POST ${path}`]: [apiError(404, "Droplet not found")],
+    });
+
+    await expect(installDroplet(client, "drp_secret")).rejects.toMatchObject({
+      status: 404,
+    });
+  });
+});
+
+describe("listInstallations", () => {
+  it("reads the navigation list by default", async () => {
+    const { client, calls } = fakeClient({
+      [`GET ${INSTALLATIONS_PATH}`]: [
+        {
+          droplet_installations: [
+            { uuid: "dri_1", droplet: { uuid: "drp_a" } },
+          ],
+        },
+      ],
+    });
+
+    const rows = await listInstallations(client);
+
+    expect(calls).toEqual([
+      { method: "GET", endpoint: INSTALLATIONS_PATH, params: undefined },
+    ]);
+    expect(rows).toEqual([{ uuid: "dri_1", droplet: { uuid: "drp_a" } }]);
+  });
+
+  it("follows every page of the full view, in the category asked for", async () => {
+    const { client, calls } = fakeClient({
+      [`GET ${INSTALLATIONS_PATH}`]: [
+        {
+          droplet_installations: [row("dri_2", "drp_b")],
+          meta: { pagination: { next_cursor: "c2" } },
+        },
+        {
+          droplet_installations: [row("dri_1", "drp_a")],
+          meta: { pagination: { next_cursor: null } },
+        },
+      ],
+    });
+
+    const rows = await listInstallations(client, {
+      full: true,
+      category: "payments",
+    });
+
+    expect(rows.map((r) => r.uuid)).toEqual(["dri_2", "dri_1"]);
+    expect(calls.map((c) => c.params)).toEqual([
+      { view: "full", filter: { category: "payments" }, page: { limit: 100 } },
+      {
+        view: "full",
+        filter: { category: "payments" },
+        page: { limit: 100, cursor: "c2" },
+      },
+    ]);
+  });
+});
+
+describe("resolveInstallation", () => {
+  it("takes an installation uuid as given", async () => {
+    const { client, calls } = fakeClient();
+
+    await expect(resolveInstallation(client, "dri_1")).resolves.toBe("dri_1");
+    expect(calls).toEqual([]);
+  });
+
+  it("finds a droplet's installation, preferring the active one", async () => {
+    const { client } = fakeClient({
+      [`GET ${INSTALLATIONS_PATH}`]: [
+        {
+          droplet_installations: [
+            row("dri_old", "drp_a", "pending_uninstall"),
+            row("dri_new", "drp_a"),
+            row("dri_x", "drp_b"),
+          ],
+        },
+      ],
+    });
+
+    await expect(resolveInstallation(client, "drp_a")).resolves.toBe("dri_new");
+  });
+
+  it("is null for a droplet that is not installed", async () => {
+    const { client } = fakeClient({
+      [`GET ${INSTALLATIONS_PATH}`]: [
+        { droplet_installations: [row("dri_x", "drp_b")] },
+      ],
+    });
+
+    await expect(findInstallation(client, "drp_a")).resolves.toBeNull();
+  });
+});
+
+describe("uninstallDroplet", () => {
+  it("deletes the installation", async () => {
+    const path = installationPath("dri_1");
+    const { client, calls } = fakeClient({
+      [`DELETE ${path}`]: [
+        { droplet_installation: row("dri_1", "drp_a", "pending_uninstall") },
+      ],
+    });
+
+    const outcome = await uninstallDroplet(client, "dri_1");
+
+    expect(calls).toEqual([{ method: "DELETE", endpoint: path }]);
+    expect(outcome).toEqual({
+      uninstalled: true,
+      installation: row("dri_1", "drp_a", "pending_uninstall"),
+    });
+  });
+
+  it("says plainly when the installation is not the company's", async () => {
+    const path = installationPath("dri_gone");
+    const { client } = fakeClient({
+      [`DELETE ${path}`]: [apiError(404, "Droplet installation not found")],
+    });
+
+    await expect(uninstallDroplet(client, "dri_gone")).rejects.toBeInstanceOf(
+      DropletsCliError,
+    );
+  });
+});
+
+describe("without droplets.view", () => {
+  const refused = () => ({
+    [`GET ${INSTALLATIONS_PATH}`]: [apiError(403, "Not authorized.")],
+  });
+
+  it("lets install go straight to the API, which answers 409 for an existing one", async () => {
+    const path = dropletInstallationsPath("drp_order_sync");
+    const { client } = fakeClient({
+      ...refused(),
+      [`POST ${path}`]: [apiError(409, "Droplet already installed")],
+    });
+
+    await expect(
+      preflightInstallation(client, "drp_order_sync"),
+    ).resolves.toBeUndefined();
+    await expect(
+      installDroplet(client, "drp_order_sync"),
+    ).resolves.toMatchObject({ alreadyInstalled: true });
+  });
+
+  it("asks for the installation uuid when a droplet uuid cannot be resolved", async () => {
+    const { client } = fakeClient(refused());
+
+    await expect(resolveInstallation(client, "drp_order_sync")).rejects.toThrow(
+      /Pass the installation's uuid \(dri_…\) instead/,
+    );
+  });
+
+  it("still resolves an installation uuid without reading the list", async () => {
+    const { client, calls } = fakeClient(refused());
+
+    await expect(resolveInstallation(client, "dri_1")).resolves.toBe("dri_1");
+    expect(calls).toEqual([]);
+  });
+
+  it("raises other list failures", async () => {
+    const { client } = fakeClient({
+      [`GET ${INSTALLATIONS_PATH}`]: [apiError(500)],
+    });
+
+    await expect(
+      preflightInstallation(client, "drp_order_sync"),
+    ).rejects.toMatchObject({ status: 500 });
+  });
+});

package/src/__tests__/install-commands.test.ts

@@ -0,0 +1,59 @@
+import { confirmChange, fail } from "../commands/install";
+import { DropletsCliError } from "../install/api";
+
+describe("confirmChange", () => {
+  it("runs at once with --yes", async () => {
+    const ask = jest.fn();
+
+    await expect(
+      confirmChange("Install?", true, false, ask),
+    ).resolves.toBeUndefined();
+    expect(ask).not.toHaveBeenCalled();
+  });
+
+  it("refuses without --yes when nobody can be asked", async () => {
+    await expect(confirmChange("Install?", false, false)).rejects.toThrow(
+      "Install? Pass --yes to confirm.",
+    );
+  });
+
+  it("asks an interactive terminal and stops on no", async () => {
+    await expect(
+      confirmChange("Install?", false, true, async () => true),
+    ).resolves.toBeUndefined();
+    await expect(
+      confirmChange("Install?", false, true, async () => false),
+    ).rejects.toBeInstanceOf(DropletsCliError);
+  });
+});
+
+describe("fail", () => {
+  afterEach(() => {
+    process.exitCode = undefined;
+    jest.restoreAllMocks();
+  });
+
+  it("prints the API's message and details on stderr and exits non-zero", () => {
+    const write = jest
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    const error = Object.assign(new Error("Request failed"), {
+      status: 422,
+      body: {
+        error: {
+          message: "Role not found",
+          details: { role_uuid: ["not found"] },
+        },
+      },
+    });
+
+    fail(error);
+
+    expect(JSON.parse(String(write.mock.calls[0]?.[0]))).toEqual({
+      error: "Role not found",
+      status: 422,
+      details: { role_uuid: ["not found"] },
+    });
+    expect(process.exitCode).toBe(1);
+  });
+});

package/src/commands/install.ts

@@ -0,0 +1,167 @@
+import { createInterface } from "node:readline/promises";
+import type { Command } from "commander";
+import type { CommandContext } from "@fluid-app/fluid-cli";
+
+import {
+  DropletsCliError,
+  installDroplet,
+  listInstallations,
+  notInstalled,
+  preflightInstallation,
+  resolveInstallation,
+  uninstallDroplet,
+  type DropletsClient,
+} from "../install/api.js";
+
+/** Asks a yes/no question; true means yes. */
+export type Ask = (question: string) => Promise<boolean>;
+
+async function askOnTerminal(question: string): Promise<boolean> {
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+  try {
+    const answer = await readline.question(`${question} [y/N] `);
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    readline.close();
+  }
+}
+
+/**
+ * Changes to what a company has installed need an explicit yes, as `fluid
+ * connect install` does. Scripts and agents pass `--yes`; an interactive
+ * terminal is asked. With neither, nothing runs.
+ */
+export async function confirmChange(
+  question: string,
+  yes: boolean,
+  interactive: boolean = Boolean(process.stdin.isTTY),
+  ask: Ask = askOnTerminal,
+): Promise<void> {
+  if (yes) return;
+  if (!interactive)
+    throw new DropletsCliError(`${question} Pass --yes to confirm.`);
+  if (!(await ask(question))) throw new DropletsCliError("Cancelled.");
+}
+
+/** Print a failure as JSON on stderr and exit non-zero, as `fluid connect`
+ *  does. The API's `error.message` and `error.details` are passed on. */
+export function fail(err: unknown): void {
+  const status = (err as { status?: unknown }).status;
+  const body = (err as { body?: { error?: unknown } | null }).body;
+  const apiError = body?.error as
+    | { message?: unknown; details?: unknown }
+    | string
+    | undefined;
+  const message =
+    typeof apiError === "string"
+      ? apiError
+      : typeof apiError?.message === "string"
+        ? apiError.message
+        : err instanceof Error
+          ? err.message
+          : String(err);
+  const details = typeof apiError === "object" ? apiError?.details : undefined;
+  process.stderr.write(
+    JSON.stringify({
+      error: message,
+      ...(typeof status === "number" ? { status } : {}),
+      ...(details &&
+      typeof details === "object" &&
+      Object.keys(details).length > 0
+        ? { details }
+        : {}),
+    }) + "\n",
+  );
+  process.exitCode = 1;
+}
+
+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 install|uninstall|installed`: friendly commands over the
+ * v2026-10 company API, next to the generated `installations` commands.
+ */
+export function registerInstallCommands(
+  parent: Command,
+  ctx: CommandContext,
+): void {
+  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: string, opts: { role?: string; yes: boolean }) =>
+      run(async () => {
+        const client = await dropletsClient(ctx);
+        // Undefined when the list is refused; the install then relies on 409.
+        const existing = await preflightInstallation(client, dropletUuid);
+        if (existing) {
+          ctx.output({
+            installed: true,
+            alreadyInstalled: true,
+            installation: existing,
+          });
+          return;
+        }
+        await confirmChange(
+          `Install droplet ${dropletUuid} for this company?`,
+          opts.yes,
+        );
+        // A 409 here means another request installed it meanwhile.
+        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: string, opts: { yes: boolean }) =>
+      run(async () => {
+        const client = await dropletsClient(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: { full: boolean; category?: string }) =>
+      run(async () => {
+        if (opts.category && !opts.full)
+          throw new DropletsCliError("--category needs --full.");
+        ctx.output(await listInstallations(await dropletsClient(ctx), opts));
+      }),
+    );
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { FluidPlugin } from "@fluid-app/fluid-cli";
 import { createDomainCommand } from "@fluid-app/fluid-cli";
 
+import { registerInstallCommands } from "./commands/install.js";
 import { registerAllCommands } from "./generated/index.js";
 
 const plugin: FluidPlugin = {
@@ -11,7 +12,13 @@ const plugin: FluidPlugin = {
       createDomainCommand(
         "droplets",
         "Manage Fluid droplets and installations",
-        registerAllCommands,
+        (parent, cmdCtx) => {
+          registerAllCommands(parent, cmdCtx);
+          // Hand-written commands on top of the generated OpenAPI surface:
+          // `install`, `uninstall` and `installed`, over the v2026-10
+          // company API.
+          registerInstallCommands(parent, cmdCtx);
+        },
       ),
     );
   },

package/src/install/api.ts

@@ -0,0 +1,209 @@
+/**
+ * Installing, listing and uninstalling droplets for the signed-in company,
+ * through the v2026-10 company droplets API
+ * (apps/rails/docs/openapi/v2026-10/company-droplets.yaml).
+ */
+
+/** The slice of the CLI's API client these calls use. */
+export interface DropletsClient {
+  get<T>(endpoint: string, params?: Record<string, unknown>): Promise<T>;
+  post<T>(endpoint: string, body?: unknown): Promise<T>;
+  delete<T>(endpoint: string): Promise<T>;
+}
+
+/** A failure the CLI reports as-is, with a non-zero exit. */
+export class DropletsCliError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DropletsCliError";
+  }
+}
+
+export const INSTALLATIONS_PATH = "/api/company/v2026-10/droplet-installations";
+
+/** Installations of a droplet are created under the droplet. */
+export function dropletInstallationsPath(dropletUuid: string): string {
+  return `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}/installations`;
+}
+
+export function installationPath(installationUuid: string): string {
+  return `${INSTALLATIONS_PATH}/${encodeURIComponent(installationUuid)}`;
+}
+
+/** An installation's uuid starts with this; anything else is read as a
+ *  droplet's uuid (most are `drp_…`, some older ones are plain slugs). */
+export const INSTALLATION_UUID_PREFIX = "dri_";
+
+/** The most rows one page of `view=full` returns. */
+export const FULL_PAGE_LIMIT = 100;
+
+/** Stop paging after this many pages, so a cursor that never ends cannot
+ *  loop forever. 100 pages of 100 is far more than a company installs. */
+export const MAX_PAGES = 100;
+
+/** A full installation row (`view=full`, and every write's response). */
+export interface InstallationRow {
+  uuid: string;
+  droplet_uuid?: string;
+  droplet?: { uuid: string; title: string | null; logo_url: string | null };
+  status?: string;
+  role?: { uuid: string; name: string | null } | null;
+  scopes?: string[];
+  effective_scopes?: string[];
+  created_at?: string;
+  updated_at?: string;
+}
+
+interface InstallationsPage {
+  droplet_installations?: InstallationRow[];
+  meta?: { pagination?: { next_cursor?: string | null } };
+}
+
+function apiStatus(error: unknown): number | undefined {
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" ? status : undefined;
+}
+
+export type InstallOutcome =
+  | { installed: true; alreadyInstalled: false; installation: InstallationRow }
+  | { installed: true; alreadyInstalled: true; dropletUuid: string };
+
+/**
+ * Install a droplet. An installation that already exists answers 409, which
+ * is reported rather than raised: the company has what it asked for.
+ */
+export async function installDroplet(
+  client: DropletsClient,
+  dropletUuid: string,
+  roleUuid?: string,
+): Promise<InstallOutcome> {
+  const installation = roleUuid ? { role_uuid: roleUuid } : {};
+  try {
+    const created = await client.post<{
+      droplet_installation: InstallationRow;
+    }>(dropletInstallationsPath(dropletUuid), { installation });
+    return {
+      installed: true,
+      alreadyInstalled: false,
+      installation: created.droplet_installation,
+    };
+  } catch (error) {
+    if (apiStatus(error) === 409)
+      return { installed: true, alreadyInstalled: true, dropletUuid };
+    throw error;
+  }
+}
+
+/**
+ * The company's installations. Without `full`, the navigation list (uuid,
+ * droplet uuid, title and logo of every active installation). With `full`,
+ * every installation not yet uninstalled, as full rows, newest first,
+ * following `meta.pagination.next_cursor` to the last page.
+ */
+export async function listInstallations(
+  client: DropletsClient,
+  options: { full?: boolean; category?: string } = {},
+): Promise<InstallationRow[]> {
+  if (!options.full) {
+    const list = await client.get<InstallationsPage>(INSTALLATIONS_PATH);
+    return list.droplet_installations ?? [];
+  }
+
+  const rows: InstallationRow[] = [];
+  let cursor: string | null | undefined;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const response = await client.get<InstallationsPage>(INSTALLATIONS_PATH, {
+      view: "full",
+      ...(options.category ? { filter: { category: options.category } } : {}),
+      page: { limit: FULL_PAGE_LIMIT, ...(cursor ? { cursor } : {}) },
+    });
+    rows.push(...(response.droplet_installations ?? []));
+    cursor = response.meta?.pagination?.next_cursor;
+    if (!cursor) return rows;
+  }
+  throw new DropletsCliError(
+    `Stopped after ${MAX_PAGES} pages of installations.`,
+  );
+}
+
+/**
+ * The installation an uninstall names: an installation uuid as given, or the
+ * company's installation of a droplet uuid, preferring an active one over
+ * one already being removed. Null when the droplet is not installed.
+ */
+export async function resolveInstallation(
+  client: DropletsClient,
+  uuid: string,
+): Promise<string | null> {
+  if (uuid.startsWith(INSTALLATION_UUID_PREFIX)) return uuid;
+
+  try {
+    return (await findInstallation(client, uuid))?.uuid ?? null;
+  } catch (error) {
+    // Reading the list needs droplets.view; deleting by installation uuid
+    // needs only droplets.update.
+    if (apiStatus(error) === 403) {
+      throw new DropletsCliError(
+        `Finding the installation of ${uuid} needs the droplets.view permission. Pass the installation's uuid (dri_…) instead.`,
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * The installation an install would duplicate, read before asking. Undefined
+ * when the list cannot be read (403, no droplets.view): the install then goes
+ * straight to the API, which answers 409 for one that exists.
+ */
+export async function preflightInstallation(
+  client: DropletsClient,
+  dropletUuid: string,
+): Promise<InstallationRow | null | undefined> {
+  try {
+    return await findInstallation(client, dropletUuid);
+  } catch (error) {
+    if (apiStatus(error) === 403) return undefined;
+    throw error;
+  }
+}
+
+/**
+ * The company's installation of a droplet, preferring an active one over one
+ * already being removed, or null when it has none.
+ */
+export async function findInstallation(
+  client: DropletsClient,
+  dropletUuid: string,
+): Promise<InstallationRow | null> {
+  const rows = (await listInstallations(client, { full: true })).filter(
+    (row) => (row.droplet_uuid ?? row.droplet?.uuid) === dropletUuid,
+  );
+  return rows.find((row) => row.status === "active") ?? rows[0] ?? null;
+}
+
+/**
+ * Uninstall: Fluid revokes the installation's credentials and sends the
+ * droplet its uninstall webhook. The installation reads `pending_uninstall`
+ * until the droplet's cleanup finishes.
+ */
+export async function uninstallDroplet(
+  client: DropletsClient,
+  installationUuid: string,
+): Promise<{ uninstalled: true; installation: InstallationRow }> {
+  try {
+    const removed = await client.delete<{
+      droplet_installation: InstallationRow;
+    }>(installationPath(installationUuid));
+    return { uninstalled: true, installation: removed.droplet_installation };
+  } catch (error) {
+    if (apiStatus(error) === 404) throw notInstalled(installationUuid);
+    throw error;
+  }
+}
+
+export function notInstalled(uuid: string): DropletsCliError {
+  return new DropletsCliError(
+    `${uuid} is not installed for this company. List what is installed with \`fluid droplets installed\`.`,
+  );
+}