@fluid-app/fluid-cli-droplets 0.1.199 → 0.1.200

package/dist/index.mjs

@@ -494,81 +494,6 @@ async function publishManifest(manifest, baseUrl, dryRun, allowWidening) {
 	});
 }
 //#endregion
-//#region src/commands/manifest.ts
-/** Public: Register local validation and Actions-only manifest publication commands. */
-function registerManifestCommands(parent, ctx) {
-	const manifest = parent.command("manifest").description(`Droplet manifests. ${AUTHORITY}`);
-	for (const verb of [
-		"validate",
-		"publish",
-		"diff"
-	]) {
-		const cmd = manifest.command(`${verb} [path]`).description(`${verb === "validate" ? "Validate locally" : verb === "diff" ? "Preview in GitHub Actions; exit 3 for widening (permissions: id-token: write)" : "Publish in GitHub Actions (permissions: id-token: write)"}. ${AUTHORITY}`).option("--json", "Print one JSON document");
-		if (verb === "publish") cmd.option("--allow-widening", "Permit widening when publishing; previews always report widening (exit 3)");
-		if (verb === "publish") cmd.option("--dry-run", "Preview without publishing");
-		cmd.action(async (path, opts, command) => {
-			const output = (data) => opts.json ? process.stdout.write(JSON.stringify(data) + "\n") : ctx.output(data);
-			try {
-				const file = path ?? "./fluid.droplet.json";
-				const limit = 256 * 1024;
-				const buffer = Buffer.alloc(limit + 1);
-				let length = 0;
-				const handle = await open(file, "r");
-				try {
-					while (length < buffer.length) {
-						const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
-						if (bytesRead === 0) break;
-						length += bytesRead;
-					}
-				} finally {
-					await handle.close();
-				}
-				if (length > limit) {
-					const code = "manifest_too_large";
-					throw new ManifestError("manifest_invalid", 2, [{
-						pointer: "/",
-						code,
-						detail: code
-					}]);
-				}
-				const bytes = buffer.subarray(0, length);
-				let text;
-				try {
-					text = new TextDecoder("utf-8", {
-						fatal: true,
-						ignoreBOM: true
-					}).decode(bytes);
-				} catch {
-					throw new ManifestError("invalid_json", 2);
-				}
-				const result = validateManifest(text);
-				if (!result.manifest) throw new ManifestError("manifest_invalid", 2, result.errors);
-				if (verb === "validate") {
-					output({
-						valid: true,
-						note: AUTHORITY
-					});
-					return;
-				}
-				const dryRun = verb === "diff" || Boolean(opts.dryRun);
-				const response = await publishManifest(result.manifest, command.optsWithGlobals().baseUrl ?? getFluidApiBase(), dryRun, Boolean(opts.allowWidening));
-				output(response);
-				if (dryRun && Array.isArray(response.widening_atoms) && response.widening_atoms.length) process.exitCode = 3;
-			} catch (error) {
-				const failure = error instanceof ManifestError ? error : new ManifestError("Unable to read or process manifest");
-				output({
-					error: {
-						code: failure.code,
-						...failure.details ? { details: failure.details } : {}
-					},
-					note: AUTHORITY
-				});
-				process.exitCode = failure.exitCode;
-			}
-		});
-	}
-}
-//#endregion
 //#region src/install/api.ts
 /** A failure the CLI reports as-is, with a non-zero exit. */
 var DropletsCliError = class extends Error {
@@ -796,6 +721,92 @@ function registerInstallCommands(parent, ctx) {
 	}));
 }
 //#endregion
+//#region src/commands/manifest.ts
+/** Public: Register local validation and Actions-only manifest publication commands. */
+function registerManifestCommands(parent, ctx) {
+	const manifest = parent.command("manifest").description(`Droplet manifests. ${AUTHORITY}`);
+	for (const verb of [
+		"validate",
+		"publish",
+		"diff"
+	]) {
+		const cmd = manifest.command(`${verb} [path]`).description(`${verb === "validate" ? "Validate locally" : verb === "diff" ? "Preview in GitHub Actions; exit 3 for widening (permissions: id-token: write)" : "Publish in GitHub Actions (permissions: id-token: write)"}. ${AUTHORITY}`).option("--json", "Print one JSON document");
+		if (verb === "publish") cmd.option("--allow-widening", "Permit widening when publishing; previews always report widening (exit 3)");
+		if (verb === "publish") cmd.option("--dry-run", "Preview without publishing");
+		if (verb === "diff") cmd.option("--against <version>", "Read-only: diff the droplet's latest ledger version against this one, with your session (needs --droplet)").option("--droplet <uuid>", "Owned droplet, with --against");
+		cmd.action(async (path, opts, command) => {
+			const output = (data) => opts.json ? process.stdout.write(JSON.stringify(data) + "\n") : ctx.output(data);
+			if (verb === "diff" && (opts.against !== void 0 || opts.droplet)) {
+				try {
+					if (path !== void 0 || !opts.droplet || opts.against === void 0) throw new DropletsCliError("Use --against <version> with --droplet <uuid> and no manifest path.");
+					if (!/^[1-9]\d{0,8}$/.test(opts.against)) throw new DropletsCliError("Version must be a positive safe integer.");
+					output(await (await ctx.getClient()).get(`/api/droplets/v2026-10/droplets/${encodeURIComponent(opts.droplet)}/manifest-diff`, { against: opts.against }));
+				} catch (error) {
+					fail(error);
+				}
+				return;
+			}
+			try {
+				const file = path ?? "./fluid.droplet.json";
+				const limit = 256 * 1024;
+				const buffer = Buffer.alloc(limit + 1);
+				let length = 0;
+				const handle = await open(file, "r");
+				try {
+					while (length < buffer.length) {
+						const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+						if (bytesRead === 0) break;
+						length += bytesRead;
+					}
+				} finally {
+					await handle.close();
+				}
+				if (length > limit) {
+					const code = "manifest_too_large";
+					throw new ManifestError("manifest_invalid", 2, [{
+						pointer: "/",
+						code,
+						detail: code
+					}]);
+				}
+				const bytes = buffer.subarray(0, length);
+				let text;
+				try {
+					text = new TextDecoder("utf-8", {
+						fatal: true,
+						ignoreBOM: true
+					}).decode(bytes);
+				} catch {
+					throw new ManifestError("invalid_json", 2);
+				}
+				const result = validateManifest(text);
+				if (!result.manifest) throw new ManifestError("manifest_invalid", 2, result.errors);
+				if (verb === "validate") {
+					output({
+						valid: true,
+						note: AUTHORITY
+					});
+					return;
+				}
+				const dryRun = verb === "diff" || Boolean(opts.dryRun);
+				const response = await publishManifest(result.manifest, command.optsWithGlobals().baseUrl ?? getFluidApiBase(), dryRun, Boolean(opts.allowWidening));
+				output(response);
+				if (dryRun && Array.isArray(response.widening_atoms) && response.widening_atoms.length) process.exitCode = 3;
+			} catch (error) {
+				const failure = error instanceof ManifestError ? error : new ManifestError("Unable to read or process manifest");
+				output({
+					error: {
+						code: failure.code,
+						...failure.details ? { details: failure.details } : {}
+					},
+					note: AUTHORITY
+				});
+				process.exitCode = failure.exitCode;
+			}
+		});
+	}
+}
+//#endregion
 //#region src/commands/rollback.ts
 /** Public: Register confirmed rollbacks for one installation or all of a droplet. */
 function registerRollbackCommands(parent, ctx) {

package/package.json

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

package/src/__tests__/manifest.test.ts

@@ -102,10 +102,11 @@ test.each(
 );
 
 const post = jest.fn();
+const get = jest.fn();
 const output = jest.fn();
 const ctx: CommandContext = {
   output,
-  getClient: jest.fn(async () => ({ post }) as never),
+  getClient: jest.fn(async () => ({ post, get }) as never),
   getClientFor: jest.fn(),
   parseBody: JSON.parse,
   verbose: false,
@@ -342,3 +343,41 @@ test.each(
   expect(fetchMock).toHaveBeenCalledTimes(entry[0] === "+" ? 3 : 0);
   expect(process.exitCode).toBe(entry[0] === "+" ? undefined : 1);
 });
+
+test("diff --against reads the ledger with the session client and no OIDC", async () => {
+  get.mockResolvedValue({ base_version: 1, target_version: 3, added: [] });
+  await run("manifest", "diff", "--droplet", "drp_1", "--against", "1");
+  expect(get).toHaveBeenCalledWith(
+    "/api/droplets/v2026-10/droplets/drp_1/manifest-diff",
+    { against: "1" },
+  );
+  expect(output).toHaveBeenCalledWith({
+    base_version: 1,
+    target_version: 3,
+    added: [],
+  });
+  expect(fetchMock).not.toHaveBeenCalled();
+  expect(post).not.toHaveBeenCalled();
+  expect(process.exitCode).toBeUndefined();
+});
+test.each([
+  [["--against", "0", "--droplet", "drp_1"]],
+  [["--against", "1.5", "--droplet", "drp_1"]],
+  [["--against", "abc", "--droplet", "drp_1"]],
+  [["--against", "1"]],
+  [["--droplet", "drp_1"]],
+  [[path, "--against", "1", "--droplet", "drp_1"]],
+])("diff --against %j makes no request", async (args) => {
+  await run("manifest", "diff", ...args);
+  expect(process.exitCode).toBe(1);
+  expect(get).not.toHaveBeenCalled();
+  expect(fetchMock).not.toHaveBeenCalled();
+});
+test("diff without --against still previews through Actions OIDC", async () => {
+  seed({ digest: "result", widening_atoms: ["scope:x"] });
+  await run("--base-url", "https://api.fluid.app", "manifest", "diff", path);
+  expect(fetchMock).toHaveBeenCalledTimes(3);
+  expect(get).not.toHaveBeenCalled();
+  expect(ctx.getClient).not.toHaveBeenCalled();
+  expect(process.exitCode).toBe(3);
+});

package/src/commands/manifest.ts

@@ -3,6 +3,8 @@ import type { Command } from "commander";
 import { getFluidApiBase, type CommandContext } from "@fluid-app/fluid-cli";
 import { AUTHORITY, validateManifest } from "../manifest/validate.js";
 import { ManifestError, publishManifest } from "../manifest/publish.js";
+import { DropletsCliError } from "../install/api.js";
+import { fail } from "./install.js";
 
 /** Public: Register local validation and Actions-only manifest publication commands. */
 export function registerManifestCommands(
@@ -26,16 +28,54 @@ export function registerManifestCommands(
       );
     if (verb === "publish")
       cmd.option("--dry-run", "Preview without publishing");
+    if (verb === "diff")
+      cmd
+        .option(
+          "--against <version>",
+          "Read-only: diff the droplet's latest ledger version against this one, with your session (needs --droplet)",
+        )
+        .option("--droplet <uuid>", "Owned droplet, with --against");
     cmd.action(
       async (
         path: string | undefined,
-        opts: { json?: boolean; dryRun?: boolean; allowWidening?: boolean },
+        opts: {
+          json?: boolean;
+          dryRun?: boolean;
+          allowWidening?: boolean;
+          against?: string;
+          droplet?: string;
+        },
         command: Command,
       ) => {
         const output = (data: Record<string, unknown>) =>
           opts.json
             ? process.stdout.write(JSON.stringify(data) + "\n")
             : ctx.output(data);
+        if (verb === "diff" && (opts.against !== undefined || opts.droplet)) {
+          try {
+            if (
+              path !== undefined ||
+              !opts.droplet ||
+              opts.against === undefined
+            )
+              throw new DropletsCliError(
+                "Use --against <version> with --droplet <uuid> and no manifest path.",
+              );
+            if (!/^[1-9]\d{0,8}$/.test(opts.against))
+              throw new DropletsCliError(
+                "Version must be a positive safe integer.",
+              );
+            const client = await ctx.getClient();
+            const response = await client.get(
+              `/api/droplets/v2026-10/droplets/${encodeURIComponent(opts.droplet)}/manifest-diff`,
+              { against: opts.against },
+            );
+            output(response as Record<string, unknown>);
+          } catch (error) {
+            fail(error);
+          }
+          return;
+        }
         try {
           const file = path ?? "./fluid.droplet.json";
           const limit = 256 * 1024;