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

package/src/__tests__/manifest.test.ts

@@ -0,0 +1,383 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { Command } from "commander";
+import type { CommandContext } from "@fluid-app/fluid-cli";
+import { canonicalize, manifestDigest } from "../manifest/canonical";
+import { schema, validateManifest } from "../manifest/validate";
+import { registerManifestCommands } from "../commands/manifest";
+import { registerRollbackCommands } from "../commands/rollback";
+
+const root = resolve(__dirname, "../../../../..");
+const fixture = (name: string) =>
+  readFileSync(
+    `${root}/apps/rails/test/fixtures/files/droplet_manifest/${name}.json`,
+    "utf8",
+  );
+const valid = JSON.parse(fixture("valid"));
+const path = `${root}/apps/rails/test/fixtures/files/droplet_manifest/valid.json`;
+
+test("Rails RFC 8785 numbers and structures", () => {
+  for (const [bits, expected] of JSON.parse(fixture("rfc8785_numbers")))
+    expect(canonicalize(Buffer.from(bits, "hex").readDoubleBE())).toBe(
+      expected,
+    );
+  const vectors = JSON.parse(fixture("rfc8785_structures"));
+  expect(canonicalize(JSON.parse(vectors.section_3_2_2.input))).toBe(
+    vectors.section_3_2_2.expected,
+  );
+  const ordered = canonicalize(JSON.parse(vectors.section_3_2_3.input));
+  expect(
+    [...ordered.matchAll(/("(?:[^"\\]|\\.)*"):/g)].map((m) =>
+      JSON.parse(m[1]!),
+    ),
+  ).toEqual(vectors.section_3_2_3.expected_key_order);
+  expect(canonicalize([1, 1.0, -3.0])).toBe("[1,1,-3]");
+  expect(canonicalize(1e30)).toBe("1e+30");
+  expect(canonicalize("\u0001\b\u007f")).toBe('"\\u0001\\b\u007f"');
+  for (const value of [NaN, Infinity, -Infinity, "\ud800", { "\udfff": 1 }])
+    expect(() => canonicalize(value)).toThrow();
+});
+test("digests pinned by running the real Ruby canonicalizer", () => {
+  expect(manifestDigest(valid)).toBe(
+    "sha256:48f9581f827469c3e7caba14df533b2f26b80f0ee7a6a69e0d117f5d56bfd6a2",
+  );
+  expect(manifestDigest(JSON.parse(fixture("full")))).toBe(
+    "sha256:071549c2be5d78bcecfcac6b1605c1751255b835de5768180facdaf9f42bc11b",
+  );
+  expect(
+    manifestDigest(JSON.parse('{"a":"é","b":[1,2],"c":{"x":1,"y":2}}')),
+  ).toBe(
+    manifestDigest(JSON.parse('{"c":{"y":2,"x":1},"b":[1,2.0],"a":"\\u00e9"}')),
+  );
+  for (const changed of [
+    { a: 2, b: [1, 2] },
+    { a: 1, b: [2, 1] },
+    { a: 1, b: [1, 2], c: null },
+  ])
+    expect(manifestDigest(changed)).not.toBe(
+      manifestDigest({ a: 1, b: [1, 2] }),
+    );
+});
+test("bundled schema matches Rails and accepts both fixtures", () => {
+  expect(schema).toEqual(
+    JSON.parse(
+      readFileSync(
+        `${root}/apps/rails/config/droplet_manifest/v1.schema.json`,
+        "utf8",
+      ),
+    ),
+  );
+  for (const name of ["valid", "full"])
+    expect(validateManifest(fixture(name)).errors).toEqual([]);
+});
+test.each([
+  "{",
+  '{"a":1,"a":2}',
+  '{"a":1,"\\u0061":2}',
+  " ".repeat(262145),
+  JSON.stringify({ ...valid, version: "bad" }),
+  JSON.stringify({ ...valid, origin: "https://user@drop.app/path" }),
+  JSON.stringify({ ...valid, min_supported_version: "999.0.0" }),
+  JSON.stringify({ ...valid, extra: 1e100 }),
+  JSON.stringify({
+    ...valid,
+    callbacks: [
+      { definition: "a", url_path: "/a" },
+      { definition: "a", url_path: "/b" },
+    ],
+  }),
+])("rejects invalid manifests %#", (text) =>
+  expect(validateManifest(text).errors.length).toBeGreaterThan(0),
+);
+test.each(
+  "//evil,/a%2fb,/a%5cb,/a/%2e.,/../a,/white space,/a%ZZ,/é,/a\u0000,/a\n,/a[b],/a|b".split(
+    ",",
+  ),
+)("rejects unsafe path %s", (p) =>
+  expect(
+    validateManifest(JSON.stringify({ ...valid, health: { path: p } })).errors
+      .length,
+  ).toBeGreaterThan(0),
+);
+
+const post = jest.fn();
+const get = jest.fn();
+const output = jest.fn();
+const ctx: CommandContext = {
+  output,
+  getClient: jest.fn(async () => ({ post, get }) as never),
+  getClientFor: jest.fn(),
+  parseBody: JSON.parse,
+  verbose: false,
+};
+const fetchMock = jest.fn();
+let stdout: jest.SpyInstance;
+const env = { ...process.env };
+beforeEach(() => {
+  process.exitCode = undefined;
+  jest.clearAllMocks();
+  stdout = jest.spyOn(process.stdout, "write").mockReturnValue(true);
+  jest.spyOn(process.stderr, "write").mockReturnValue(true);
+  global.fetch = fetchMock;
+  process.env.GITHUB_ACTIONS = "true";
+  process.env.ACTIONS_ID_TOKEN_REQUEST_URL = "https://github.test/token?x=1";
+  process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN = "request-secret";
+  fetchMock.mockReset();
+});
+afterEach(() => {
+  process.exitCode = undefined;
+  process.env = { ...env };
+  jest.restoreAllMocks();
+});
+function response(body: unknown, status = 200) {
+  return { ok: status < 400, status, json: async () => body };
+}
+function seed(body: unknown) {
+  fetchMock
+    .mockResolvedValueOnce(response({ value: "oidc-secret" }))
+    .mockResolvedValueOnce(
+      response({ publish_grant: { token: "grant-secret" } }, 201),
+    )
+    .mockResolvedValueOnce(response(body));
+}
+async function run(...args: string[]) {
+  const command = new Command("droplets").option("--base-url <url>");
+  registerManifestCommands(command, ctx);
+  registerRollbackCommands(command, ctx);
+  await command.parseAsync(args, { from: "user" });
+}
+test("validate output and local invalid exit 2 without network", async () => {
+  await run("manifest", "validate", path);
+  expect(output).toHaveBeenCalledWith(expect.objectContaining({ valid: true }));
+  expect(stdout).not.toHaveBeenCalled();
+  await run("manifest", "validate", path, "--json");
+  expect(JSON.parse(stdout.mock.calls[0]![0]).valid).toBe(true);
+  await run(
+    "manifest",
+    "validate",
+    path.replace("valid.json", "rfc8785_numbers.json"),
+    "--json",
+  );
+  expect(process.exitCode).toBe(2);
+  expect(fetchMock).not.toHaveBeenCalled();
+});
+test("oversized file exits 2 with the validator's too-large finding", async () => {
+  const dir = mkdtempSync(resolve(tmpdir(), "manifest-"));
+  const text = " ".repeat(256 * 1024 + 1);
+  writeFileSync(`${dir}/large.json`, text);
+  await run("manifest", "validate", `${dir}/large.json`, "--json").finally(() =>
+    rmSync(dir, { recursive: true, force: true }),
+  );
+  expect(process.exitCode).toBe(2);
+  expect(JSON.parse(stdout.mock.calls[0]![0]).error.details).toEqual(
+    validateManifest(text).errors,
+  );
+});
+test("an endless file with no reported size is refused without buffering it", async () => {
+  await run("manifest", "validate", "/dev/zero", "--json");
+  expect(process.exitCode).toBe(2);
+});
+test.each(["publish", "diff"])(
+  "%s uses OIDC, grant, correct auth and no platform client",
+  async (verb) => {
+    seed({ digest: "result", widening_atoms: [] });
+    await run(
+      "--base-url",
+      "https://api.fluid.app",
+      "manifest",
+      verb,
+      path,
+      "--json",
+    );
+    expect(fetchMock.mock.calls[0]![0]).toContain(
+      "audience=https%3A%2F%2Fapi.fluid.app%2Fdroplets%2Fmanifest",
+    );
+    expect(fetchMock.mock.calls[1]![0]).toBe(
+      "https://api.fluid.app/api/droplets/v2026-10/publish-grants",
+    );
+    expect(fetchMock.mock.calls.map((c) => c[1].headers.Authorization)).toEqual(
+      ["Bearer request-secret", "Bearer oidc-secret", "Bearer grant-secret"],
+    );
+    expect(fetchMock.mock.calls[2]![0]).toContain(
+      verb === "diff" ? "?dry_run=true" : "manifest-publications",
+    );
+    expect(JSON.parse(fetchMock.mock.calls[2]![1].body).allow_widening).toBe(
+      verb === "diff" ? true : undefined,
+    );
+    expect(ctx.getClient).not.toHaveBeenCalled();
+    expect(stdout).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(stdout.mock.calls[0]![0])).toEqual({
+      digest: "result",
+      widening_atoms: [],
+    });
+    expect(JSON.stringify(stdout.mock.calls)).not.toContain("secret");
+  },
+);
+test.each([false, true])(
+  "dry run widening exits 3 even with allow-widening=%s",
+  async (allow) => {
+    seed({ widening_atoms: ["scope:orders"] });
+    await run(
+      "manifest",
+      "publish",
+      path,
+      "--dry-run",
+      ...(allow ? ["--allow-widening"] : []),
+    );
+    expect(JSON.parse(fetchMock.mock.calls[2]![1].body).allow_widening).toBe(
+      true,
+    );
+    expect(process.exitCode).toBe(3);
+  },
+);
+test("explicit widening real publish succeeds", async () => {
+  seed({ version: "1.0.0" });
+  await run("manifest", "publish", path, "--allow-widening");
+  expect(JSON.parse(fetchMock.mock.calls[2]![1].body).allow_widening).toBe(
+    true,
+  );
+  expect(process.exitCode).toBeUndefined();
+});
+test.each([
+  "GITHUB_ACTIONS",
+  "ACTIONS_ID_TOKEN_REQUEST_URL",
+  "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+])("missing %s refuses without network", async (key) => {
+  delete process.env[key];
+  await run("manifest", "publish", path, "--json");
+  expect(process.exitCode).toBe(1);
+  expect(fetchMock).not.toHaveBeenCalled();
+  expect(stdout.mock.calls[0]![0]).toContain(key);
+  expect(stdout.mock.calls[0]![0]).toContain("id-token: write");
+});
+test.each([
+  [403, "publisher_not_bound", 1],
+  [409, "version_conflict", 1],
+  [422, "widening_not_allowed", 3],
+  [422, "manifest_invalid", 2],
+  [422, "digest_mismatch", 1],
+])("API %s %s maps exit", async (status, code, exit) => {
+  const finding = { pointer: "/x", code: "unknown", detail: "Unknown" };
+  fetchMock.mockResolvedValueOnce(response({ value: "oidc-secret" }));
+  if (status !== 403)
+    fetchMock.mockResolvedValueOnce(
+      response({ publish_grant: { token: "grant-secret" } }),
+    );
+  fetchMock.mockResolvedValueOnce(
+    response(
+      {
+        error: {
+          message: "secret must not leak",
+          details: { code, details: [{ ...finding, token: "grant-secret" }] },
+        },
+      },
+      Number(status),
+    ),
+  );
+  await run("manifest", "publish", path, "--json");
+  expect(process.exitCode).toBe(exit);
+  if (code === "manifest_invalid")
+    expect(JSON.parse(stdout.mock.calls[0]![0]).error.details).toEqual([
+      finding,
+    ]);
+  expect(JSON.parse(stdout.mock.calls[0]![0]).error.code).toBe(code);
+  expect(JSON.stringify(stdout.mock.calls)).not.toContain("secret");
+});
+test.each([
+  ["--install", "dri_1"],
+  ["--all", "--droplet", "drp_1"],
+])("rollback %j uses authenticated client", async (...args) => {
+  post.mockResolvedValue({ classification: "would_await_consent" });
+  await run("rollback", "1", ...args, "--yes");
+  expect(post).toHaveBeenCalledWith(
+    expect.stringContaining(
+      args[0] === "--install"
+        ? "/installations/dri_1/rollback"
+        : "/droplets/drp_1/rollback",
+    ),
+    args[0] === "--install" ? { version: 1 } : { version: 1, all: true },
+  );
+  expect(output).toHaveBeenCalledWith({
+    classification: "would_await_consent",
+  });
+});
+test.each([
+  [],
+  ["--all"],
+  ["--install", "dri_1", "--all"],
+  ["--install", "dri_1"],
+])("rollback invalid or unconfirmed %j makes no request", async (...args) => {
+  await run("rollback", "1", ...args);
+  expect(process.exitCode).toBe(1);
+  expect(post).not.toHaveBeenCalled();
+});
+
+test.each(["/%C3%A9", "/a%00", "/a%01", "/a%20b", "/a%5Bb%5D", "/a%7Cb"])(
+  "accepts Ruby URI path %s",
+  (p) => {
+    expect(
+      validateManifest(JSON.stringify({ ...valid, health: { path: p } }))
+        .errors,
+    ).toEqual([]);
+  },
+);
+test.each(["1.0.0", "0", "-1", "1.5", "9007199254740992", "1e2", "", " 1"])(
+  "rejects version %s",
+  async (version) => {
+    await run("rollback", "--install", "dri_1", "--", version);
+    expect(process.exitCode).toBe(1);
+    expect(post).not.toHaveBeenCalled();
+    expect(
+      JSON.stringify(jest.mocked(process.stderr.write).mock.calls),
+    ).toContain("positive safe integer");
+  },
+);
+test.each(
+  "-http://api.fluid.app -http://localhost.evil -http://127.0.0.2 +http://localhost +http://127.0.0.1 +http://[::1] -https://fluid.app +https://api.fluid.app -https://api.stage.fluid.app -https://shop.fluid.app -https://user@api.fluid.app -https://api.fluid.app:8443 -https://evil.com -https://evilfluid.app -https://fluid.app.evil.com -https://api.fluid.app@evil.com".split(
+    " ",
+  ),
+)("publisher transport %s", async (entry) => {
+  seed({ widening_atoms: [] });
+  await run("--base-url", entry.slice(1), "manifest", "diff", path);
+  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

@@ -0,0 +1,153 @@
+import { open } from "node:fs/promises";
+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(
+  parent: Command,
+  ctx: CommandContext,
+): void {
+  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: string | undefined,
+        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;
+          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: string;
+          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;
+        }
+      },
+    );
+  }
+}

package/src/commands/rollback.ts

@@ -0,0 +1,67 @@
+import type { Command } from "commander";
+import type { CommandContext } from "@fluid-app/fluid-cli";
+import { confirmChange, fail } from "./install.js";
+import { DropletsCliError } from "../install/api.js";
+
+/** Public: Register confirmed rollbacks for one installation or all of a droplet. */
+export function registerRollbackCommands(
+  parent: Command,
+  ctx: CommandContext,
+): void {
+  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: string,
+        opts: {
+          install?: string;
+          all?: boolean;
+          droplet?: string;
+          yes: boolean;
+        },
+      ) => {
+        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);
+        }
+      },
+    );
+}

package/src/index.ts

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

package/src/manifest/canonical.ts

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+
+/** Public: Serialize JSON using RFC 8785 UTF-16 ordering and ECMAScript numbers. */
+export function canonicalize(value: unknown): string {
+  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. */
+export function manifestDigest(value: unknown): string {
+  return `sha256:${createHash("sha256").update(canonicalize(value)).digest("hex")}`;
+}