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

package/dist/index.mjs

@@ -1,6 +1,574 @@
-import { createDomainCommand } from "@fluid-app/fluid-cli";
+import { createDomainCommand, getFluidApiBase } from "@fluid-app/fluid-cli";
+import { open } from "node:fs/promises";
+import Ajv2020 from "ajv/dist/2020.js";
+import { createHash } from "node:crypto";
 import { createInterface } from "node:readline/promises";
 import "commander";
+//#region ../../../apps/rails/config/droplet_manifest/v1.schema.json
+var v1_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://schemas.fluid.app/droplet/manifest/v1.json",
+	title: "Fluid droplet manifest v1",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"manifest_version",
+		"droplet",
+		"version",
+		"scopes",
+		"origin"
+	],
+	$defs: {
+		"path": {
+			"type": "string",
+			"maxLength": 2048,
+			"pattern": "^/(?!/)[^@\\\\?#\\s]*$"
+		},
+		"semver": {
+			"type": "string",
+			"maxLength": 128,
+			"pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-(0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(\\.(0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
+		},
+		"namespace": {
+			"type": "string",
+			"maxLength": 64,
+			"pattern": "^[a-z][a-z0-9_]{0,63}$"
+		},
+		"name": {
+			"type": "string",
+			"maxLength": 64,
+			"pattern": "^[a-z][a-z0-9_.]{0,63}$"
+		}
+	},
+	properties: {
+		"manifest_version": { "const": 1 },
+		"droplet": {
+			"type": "string",
+			"minLength": 1,
+			"maxLength": 64
+		},
+		"version": { "$ref": "#/$defs/semver" },
+		"min_supported_version": { "$ref": "#/$defs/semver" },
+		"origin": {
+			"type": "string",
+			"maxLength": 253,
+			"pattern": "^https://[A-Za-z0-9.-]+(:[0-9]{1,5})?$"
+		},
+		"scopes": {
+			"type": "array",
+			"maxItems": 64,
+			"uniqueItems": true,
+			"items": {
+				"type": "string",
+				"minLength": 1,
+				"maxLength": 64
+			}
+		},
+		"webhooks": {
+			"type": "array",
+			"maxItems": 256,
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["topic", "url_path"],
+				"properties": {
+					"topic": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 128,
+						"pattern": "^[a-z][a-z0-9_]*$"
+					},
+					"url_path": { "$ref": "#/$defs/path" }
+				}
+			}
+		},
+		"callbacks": {
+			"type": "array",
+			"maxItems": 64,
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["definition", "url_path"],
+				"properties": {
+					"definition": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 128
+					},
+					"url_path": { "$ref": "#/$defs/path" },
+					"country_codes": {
+						"type": "array",
+						"maxItems": 300,
+						"uniqueItems": true,
+						"items": {
+							"type": "string",
+							"pattern": "^[A-Z]{2}$"
+						}
+					}
+				}
+			}
+		},
+		"embeds": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"detail_page": { "$ref": "#/$defs/path" },
+				"drop_zones": {
+					"type": "array",
+					"maxItems": 64,
+					"uniqueItems": true,
+					"items": { "$ref": "#/$defs/path" }
+				}
+			}
+		},
+		"metafields": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"owns": {
+					"type": "array",
+					"maxItems": 64,
+					"uniqueItems": true,
+					"items": { "$ref": "#/$defs/namespace" }
+				},
+				"reads": {
+					"type": "array",
+					"maxItems": 64,
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["droplet", "namespace"],
+						"properties": {
+							"droplet": {
+								"type": "string",
+								"minLength": 1,
+								"maxLength": 64
+							},
+							"namespace": { "$ref": "#/$defs/namespace" }
+						}
+					}
+				}
+			}
+		},
+		"publishes": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"events": {
+					"type": "array",
+					"maxItems": 256,
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["name", "major"],
+						"properties": {
+							"name": { "$ref": "#/$defs/name" },
+							"major": {
+								"type": "integer",
+								"minimum": 1
+							},
+							"description": {
+								"type": "string",
+								"maxLength": 1024
+							},
+							"schema": { "type": "object" }
+						}
+					}
+				},
+				"actions": {
+					"type": "array",
+					"maxItems": 256,
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["name"],
+						"properties": {
+							"name": {
+								"type": "string",
+								"maxLength": 64,
+								"pattern": "^[a-z][a-z0-9_]{0,63}$"
+							},
+							"description": {
+								"type": "string",
+								"maxLength": 1024
+							},
+							"input_schema": { "type": "object" },
+							"output_schema": { "type": "object" },
+							"effects": { "enum": ["none", "writes"] },
+							"async": { "type": "boolean" },
+							"budgets": {
+								"type": "object",
+								"additionalProperties": false,
+								"properties": {
+									"concurrency": {
+										"type": "integer",
+										"minimum": 1
+									},
+									"timeout_ms": {
+										"type": "integer",
+										"minimum": 1
+									},
+									"bytes": {
+										"type": "integer",
+										"minimum": 1
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"subscribes": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": { "events": {
+				"type": "array",
+				"maxItems": 256,
+				"items": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": [
+						"publisher",
+						"event",
+						"major",
+						"required"
+					],
+					"properties": {
+						"publisher": {
+							"type": "string",
+							"minLength": 1,
+							"maxLength": 64
+						},
+						"event": { "$ref": "#/$defs/name" },
+						"major": {
+							"type": "integer",
+							"minimum": 1
+						},
+						"required": { "type": "boolean" }
+					}
+				}
+			} }
+		},
+		"mcp": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": { "tools": {
+				"type": "array",
+				"maxItems": 256,
+				"items": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["action", "class"],
+					"properties": {
+						"action": {
+							"type": "string",
+							"maxLength": 64,
+							"pattern": "^[a-z][a-z0-9_]{0,63}$"
+						},
+						"description": {
+							"type": "string",
+							"maxLength": 1024
+						},
+						"class": { "enum": ["read", "write"] }
+					}
+				}
+			} }
+		},
+		"health": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": { "path": {
+				"$ref": "#/$defs/path",
+				"default": "/api/health"
+			} }
+		},
+		"lifecycle": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"install_webhook_path": { "$ref": "#/$defs/path" },
+				"uninstall_webhook_path": { "$ref": "#/$defs/path" },
+				"events_webhook_path": { "$ref": "#/$defs/path" }
+			}
+		}
+	}
+};
+//#endregion
+//#region src/manifest/validate.ts
+const AUTHORITY = "The server is authoritative and checks additional catalogs, scope ceilings and publisher identity.";
+const checkSchema = new Ajv2020({
+	allErrors: true,
+	strict: false
+}).compile(v1_schema_default);
+function compareVersion(a, b) {
+	const split = (v) => v.split("+")[0].match(/^(\d+)\.(\d+)\.(\d+)(?:-(.*))?$/).slice(1);
+	const aa = split(a), bb = split(b);
+	const compare = (x, y) => {
+		if (x === y) return 0;
+		const xn = /^\d+$/.test(x), yn = /^\d+$/.test(y);
+		if (xn && yn) return BigInt(x) < BigInt(y) ? -1 : 1;
+		return xn !== yn ? xn ? -1 : 1 : x < y ? -1 : 1;
+	};
+	for (let i = 0; i < 3; i++) {
+		const n = compare(aa[i], bb[i]);
+		if (n) return n;
+	}
+	const ap = aa[3], bp = bb[3];
+	if (ap === void 0 || bp === void 0) return ap === bp ? 0 : ap === void 0 ? 1 : -1;
+	const ax = ap.split("."), bx = bp.split(".");
+	for (let i = 0; i < Math.max(ax.length, bx.length); i++) {
+		if (ax[i] === void 0 || bx[i] === void 0) return ax.length < bx.length ? -1 : 1;
+		const n = compare(ax[i], bx[i]);
+		if (n) return n;
+	}
+	return 0;
+}
+/** Public: Validate locally expressible manifest rules; the server checks the rest. */
+function validateManifest(text) {
+	const errors = [];
+	const add = (pointer, code, detail = code) => errors.push({
+		pointer,
+		code,
+		detail
+	});
+	if (Buffer.byteLength(text) > 256 * 1024) {
+		add("/", "manifest_too_large");
+		return { errors };
+	}
+	let value;
+	try {
+		value = JSON.parse(text);
+		const stack = [];
+		for (const token of text.matchAll(/"(?:[^"\\]|\\.)*"\s*:?|[{}]/g)) {
+			const t = token[0];
+			if (t === "{") stack.push(/* @__PURE__ */ new Set());
+			else if (t === "}") stack.pop();
+			else if (t.endsWith(":")) {
+				const key = JSON.parse(t.slice(0, -1));
+				if (stack.at(-1)?.has(key)) throw new Error("duplicate key");
+				stack.at(-1)?.add(key);
+			}
+		}
+	} catch {
+		add("", "invalid_json", "Invalid JSON or duplicate object keys");
+		return { errors };
+	}
+	function walk(node, pointer) {
+		if (typeof node === "number" && (!Number.isFinite(node) || Math.abs(node) > Number.MAX_SAFE_INTEGER)) add(pointer, "invalid_number");
+		if (typeof node === "string" && !node.isWellFormed()) add(pointer, "invalid_json", "Invalid Unicode");
+		if (node && typeof node === "object") for (const [key, item] of Object.entries(node)) {
+			if (!key.isWellFormed()) add(pointer, "invalid_json", "Invalid Unicode key");
+			walk(item, `${pointer}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`);
+		}
+		if (typeof node === "string" && /^\/(webhooks\/\d+\/url_path|callbacks\/\d+\/url_path|embeds\/(detail_page|drop_zones\/\d+)|health\/path|lifecycle\/(install|uninstall|events)_webhook_path)$/.test(pointer)) {
+			if (!/^\/(?!\/)[^@\\?#\s]*$/.test(node) || /[^\x21-\x7e]|%(?![\da-f]{2})|[<>"{}|^`[\]]/i.test(node) || /%(2f|5c)/i.test(node) || /(?:^|\/)(?:\.|%2e){1,2}(?:\/|$)/i.test(node)) add(pointer, "invalid_path");
+		}
+	}
+	walk(value, "");
+	if (value && typeof value === "object" && "manifest_version" in value && value.manifest_version !== 1) {
+		add("/manifest_version", "unsupported_manifest_version");
+		return { errors };
+	}
+	if (!checkSchema(value)) {
+		for (const e of checkSchema.errors ?? []) add(e.instancePath, "schema_violation", e.message ?? e.keyword);
+		return { errors };
+	}
+	try {
+		const origin = new URL(String(value.origin));
+		if (origin.protocol !== "https:" || origin.username || origin.password || !/^https:\/\/[^/]+$/.test(String(value.origin))) throw new Error();
+	} catch {
+		add("/origin", "origin_not_https");
+	}
+	if (typeof value.min_supported_version === "string" && compareVersion(value.min_supported_version, value.version) > 0) add("/min_supported_version", "min_supported_version_exceeds_version");
+	for (const [field, key, code] of [[
+		"callbacks",
+		"definition",
+		"definition_not_unique"
+	], [
+		"webhooks",
+		"topic",
+		"webhook_not_unique"
+	]]) {
+		const seen = /* @__PURE__ */ new Set();
+		const rows = value[field];
+		if (Array.isArray(rows)) rows.forEach((row, i) => {
+			if (seen.has(row[key])) add(`/${field}/${i}/${key}`, code);
+			seen.add(row[key]);
+		});
+	}
+	return {
+		manifest: errors.length ? void 0 : value,
+		errors
+	};
+}
+//#endregion
+//#region src/manifest/canonical.ts
+/** Public: Serialize JSON using RFC 8785 UTF-16 ordering and ECMAScript numbers. */
+function canonicalize(value) {
+	if (typeof value === "string") {
+		if (!value.isWellFormed()) throw new Error("string is not valid Unicode");
+		return JSON.stringify(value);
+	}
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error("non-finite number");
+		return JSON.stringify(value);
+	}
+	if (value === null || typeof value === "boolean") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+	if (typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) return `{${Object.keys(value).sort().map((key) => `${canonicalize(key)}:${canonicalize(Reflect.get(value, key))}`).join(",")}}`;
+	throw new Error("unsupported JSON value");
+}
+/** Public: Compute the manifest ledger key over its canonical UTF-8 bytes. */
+function manifestDigest(value) {
+	return `sha256:${createHash("sha256").update(canonicalize(value)).digest("hex")}`;
+}
+//#endregion
+//#region src/manifest/publish.ts
+var ManifestError = class extends Error {
+	constructor(code, exitCode = 1, details) {
+		super(code);
+		this.code = code;
+		this.exitCode = exitCode;
+		this.details = details;
+	}
+};
+async function request(url, token, body) {
+	let response;
+	try {
+		response = await fetch(url, {
+			method: body === void 0 ? "GET" : "POST",
+			redirect: "error",
+			signal: AbortSignal.timeout(3e4),
+			headers: {
+				Authorization: `Bearer ${token}`,
+				"Content-Type": "application/json"
+			},
+			...body === void 0 ? {} : { body: JSON.stringify(body) }
+		});
+	} catch {
+		throw new ManifestError("Publisher request failed");
+	}
+	let result;
+	try {
+		result = await response.json();
+	} catch {
+		throw new ManifestError("Invalid publisher response");
+	}
+	if (!response.ok) {
+		const code = result?.error?.details?.code ?? `HTTP ${response.status}`;
+		throw new ManifestError(code, code === "widening_not_allowed" ? 3 : code === "manifest_invalid" ? 2 : 1, code === "manifest_invalid" && Array.isArray(result?.error?.details?.details) ? result.error.details.details.map(({ pointer, code, detail }) => ({
+			pointer,
+			code,
+			detail
+		})) : void 0);
+	}
+	return result;
+}
+/** Public: Publish or preview using only GitHub OIDC and a single-use grant. */
+async function publishManifest(manifest, baseUrl, dryRun, allowWidening) {
+	const base = new URL(baseUrl);
+	if (!(base.origin === "https://api.fluid.app" && !base.username && !base.password || ["http:", "https:"].includes(base.protocol) && [
+		"localhost",
+		"127.0.0.1",
+		"[::1]"
+	].includes(base.hostname))) throw new ManifestError(`Rejected publisher host ${base.hostname}; allowed: https://api.fluid.app; HTTP/HTTPS localhost, 127.0.0.1, [::1]`);
+	const missing = ["ACTIONS_ID_TOKEN_REQUEST_URL", "ACTIONS_ID_TOKEN_REQUEST_TOKEN"].filter((key) => !process.env[key]);
+	if (process.env.GITHUB_ACTIONS !== "true") missing.unshift("GITHUB_ACTIONS=true");
+	if (missing.length) throw new ManifestError(`Actions only: missing ${missing.join(", ")}; configure permissions: id-token: write`);
+	const digest = manifestDigest(manifest);
+	const oidcUrl = new URL(process.env.ACTIONS_ID_TOKEN_REQUEST_URL);
+	oidcUrl.searchParams.set("audience", "https://api.fluid.app/droplets/manifest");
+	const oidc = await request(oidcUrl.toString(), process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN);
+	if (typeof oidc.value !== "string" || !oidc.value) throw new ManifestError("Missing OIDC token");
+	const prefix = `${baseUrl.replace(/\/$/, "")}/api/droplets/v2026-10`;
+	const token = (await request(`${prefix}/publish-grants`, oidc.value, {
+		droplet_uuid: manifest.droplet,
+		digest
+	})).publish_grant?.token;
+	if (typeof token !== "string" || !token) throw new ManifestError("Missing publish grant");
+	return request(`${prefix}/manifest-publications${dryRun ? "?dry_run=true" : ""}`, token, {
+		manifest,
+		digest,
+		...dryRun || allowWidening ? { allow_widening: true } : {}
+	});
+}
+//#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 {
@@ -228,6 +796,27 @@ function registerInstallCommands(parent, ctx) {
 	}));
 }
 //#endregion
+//#region src/commands/rollback.ts
+/** Public: Register confirmed rollbacks for one installation or all of a droplet. */
+function registerRollbackCommands(parent, ctx) {
+	parent.command("rollback <version>").description("Roll back live config; would_await_consent still requires merchant consent").option("--install <uuid>", "Installation to roll back").option("--all", "Roll back all installations").option("--droplet <uuid>", "Owned droplet (required with --all)").option("--yes", "Confirm without a prompt", false).action(async (version, opts) => {
+		try {
+			if (Boolean(opts.install) === Boolean(opts.all) || opts.all && !opts.droplet || opts.install && opts.droplet) throw new DropletsCliError("Choose exactly one of --install <uuid> or --all --droplet <uuid>.");
+			const targetVersion = Number(version);
+			if (!/^\d+$/.test(version) || !Number.isSafeInteger(targetVersion) || targetVersion <= 0) throw new DropletsCliError("Version must be a positive safe integer.");
+			await confirmChange(`Roll back ${opts.install ?? opts.droplet} to ${version}?`, opts.yes);
+			const client = await ctx.getClient();
+			const target = opts.install ? `installations/${encodeURIComponent(opts.install)}` : `droplets/${encodeURIComponent(opts.droplet)}`;
+			ctx.output(await client.post(`/api/droplets/v2026-10/${target}/rollback`, {
+				version: targetVersion,
+				...opts.all ? { all: true } : {}
+			}));
+		} catch (error) {
+			fail(error);
+		}
+	});
+}
+//#endregion
 //#region src/publish/api.ts
 /**
 * Asking Fluid to publish a droplet, and a root admin's review of those
@@ -490,6 +1079,8 @@ const plugin = {
 	register(ctx) {
 		ctx.program.addCommand(createDomainCommand("droplets", "Manage Fluid droplets and installations", (parent, cmdCtx) => {
 			registerAllCommands(parent, cmdCtx);
+			registerManifestCommands(parent, cmdCtx);
+			registerRollbackCommands(parent, cmdCtx);
 			registerInstallCommands(parent, cmdCtx);
 			registerPublishCommands(parent, cmdCtx);
 		}));

package/jest.mocks/fluid-cli.ts

@@ -8,3 +8,8 @@ export function createDomainCommand(): never {
     "createDomainCommand is not available in unit tests (droplets)",
   );
 }
+
+/** Public: Resolve the API origin without loading credentials. */
+export function getFluidApiBase(): string {
+  return process.env.FLUID_API_BASE ?? "https://api.fluid.app";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-droplets",
-  "version": "0.1.197",
+  "version": "0.1.199",
   "description": "Fluid CLI commands for droplet management",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -17,7 +17,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@fluid-app/fluid-cli": "0.1.196",
+    "@fluid-app/fluid-cli": "0.1.197",
+    "ajv": "8.17.1",
     "commander": "^12.0.0"
   },
   "devDependencies": {