@supacloud/cli 0.110.0 → 0.111.0

package/README.md

@@ -605,6 +605,19 @@ supacloud release release_canary_fixture_disable_replay --ref abc123 \
   --issuer <issuer-url> --subject <central-subject-uuid>
 ```
 
+A standard cross-component release contract can be validated without mutation:
+
+```bash
+supacloud release contract_plan --file supacloud.release.json \
+  --ref abc123 --environment_id production --require_current_source
+```
+
+The plan rejects project or environment binding mismatches and returns the
+canonical `scope_sha256`; it does not apply migrations, Functions, Application
+releases, or frontend assets. See
+[docs/application-release-contract.md](../../docs/application-release-contract.md).
+
+
 Backup creation reports success only after the CLI verifies exactly one new
 logical-backup receipt against the inventory before and after the mutation.
 Logical restore is project-scoped: pause the selected project first, obtain the

package/dist/index.js

@@ -9341,7 +9341,7 @@ var ACTION_POLICY = {
   mutations: { read: ["status"] },
   release: {
     read: ["logical_backup_list", "logical_backup_status", "postgrest_status"],
-    local: ["scope_inspect", "scope_rebind", "scope_create"],
+    local: ["scope_inspect", "scope_rebind", "scope_create", "contract_plan"],
     write: ["logical_backup_create", "logical_backup_restore", "postgrest_restart", "release_canary_fixture_stage_replay", "release_canary_fixture_disable_replay"]
   },
   secrets: { read: ["list"], write: ["upsert", "delete"] },
@@ -9975,7 +9975,7 @@ class HttpTransport {
 }
 
 // src/shared/tools/database-tools.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync2 } from "node:fs";
 import { basename as basename3, join as join4 } from "node:path";
 
@@ -11486,6 +11486,108 @@ function buildDeliveryMigrationPlan(archive, inventory, ref) {
     dataRecovery: "separate-required"
   };
 }
+// node_modules/@supacloud/delivery/src/release-contract.ts
+import { createHash as createHash3 } from "node:crypto";
+var RELEASE_CONTRACT_SCHEMA = "supacloud.release-control.v2";
+var SHA256 = /^[0-9a-f]{64}$/;
+var COMMIT = /^[0-9a-f]{40}$/;
+var PROJECT_REF = /^[a-z0-9]{20}$/;
+var ENVIRONMENT_ID = /^[A-Za-z0-9_-]{1,64}$/;
+var FUNCTION_SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/;
+var MIGRATION_NAME = /^\d{14}_[a-z0-9_]+$/;
+function record3(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+function exactKeys(value, expected, label) {
+  const actual = Object.keys(value).sort();
+  const keys = [...expected].sort();
+  if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index])) {
+    throw new Error(`${label} contains unsupported or missing fields`);
+  }
+}
+function nonEmptyString(value, label, pattern) {
+  if (typeof value !== "string" || value.length === 0 || pattern && !pattern.test(value)) {
+    throw new Error(`${label} is invalid`);
+  }
+  return value;
+}
+function parseComponent(value, index) {
+  const candidate = record3(value, `Release component ${index}`);
+  if (candidate["kind"] === "migration") {
+    exactKeys(candidate, ["kind", "name"], `Release migration ${index}`);
+    return { kind: "migration", name: nonEmptyString(candidate["name"], `Release migration ${index}`, MIGRATION_NAME) };
+  }
+  if (candidate["kind"] === "function") {
+    exactKeys(candidate, ["artifactSha256", "kind", "slug"], `Release Function ${index}`);
+    return {
+      kind: "function",
+      slug: nonEmptyString(candidate["slug"], `Release Function ${index}`, FUNCTION_SLUG),
+      artifactSha256: nonEmptyString(candidate["artifactSha256"], `Release Function ${index}`, SHA256)
+    };
+  }
+  if (candidate["kind"] === "web") {
+    exactKeys(candidate, ["artifactSha256", "kind"], `Release Web ${index}`);
+    return {
+      kind: "web",
+      artifactSha256: nonEmptyString(candidate["artifactSha256"], `Release Web ${index}`, SHA256)
+    };
+  }
+  throw new Error(`Release component ${index} kind is invalid`);
+}
+function componentKey(component) {
+  return component.kind === "migration" ? `${component.kind}:${component.name}` : component.kind === "function" ? `${component.kind}:${component.slug}` : component.kind;
+}
+function parseReleaseScope(value) {
+  const candidate = record3(value, "Release scope");
+  exactKeys(candidate, [
+    "components",
+    "releaseId",
+    "schema",
+    "sourceCommit",
+    "targetEnvironmentId",
+    "targetProjectRef"
+  ], "Release scope");
+  if (candidate["schema"] !== RELEASE_CONTRACT_SCHEMA) {
+    throw new Error("Release scope schema is invalid");
+  }
+  if (!Array.isArray(candidate["components"]) || candidate["components"].length === 0) {
+    throw new Error("Release scope components must be non-empty");
+  }
+  const components = candidate["components"].map(parseComponent);
+  const componentKeys = components.map(componentKey);
+  if (new Set(componentKeys).size !== componentKeys.length || componentKeys.some((key, index) => key !== [...componentKeys].sort()[index])) {
+    throw new Error("Release scope components must be unique and sorted");
+  }
+  return {
+    schema: RELEASE_CONTRACT_SCHEMA,
+    releaseId: nonEmptyString(candidate["releaseId"], "Release scope releaseId"),
+    sourceCommit: nonEmptyString(candidate["sourceCommit"], "Release scope sourceCommit", COMMIT),
+    targetEnvironmentId: nonEmptyString(candidate["targetEnvironmentId"], "Release scope targetEnvironmentId", ENVIRONMENT_ID),
+    targetProjectRef: nonEmptyString(candidate["targetProjectRef"], "Release scope targetProjectRef", PROJECT_REF),
+    components
+  };
+}
+function canonical2(value) {
+  if (Array.isArray(value))
+    return value.map(canonical2);
+  if (!value || typeof value !== "object")
+    return value;
+  return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, canonical2(item)]));
+}
+function releaseScopeSha256(scope) {
+  return createHash3("sha256").update(JSON.stringify(canonical2(scope))).digest("hex");
+}
+var ALLOWED_PHASE_TRANSITIONS = new Map([
+  ["planned", ["mutating", "rollback-required"]],
+  ["mutating", ["applied", "rollback-required"]],
+  ["applied", ["reconciled", "rollback-required"]],
+  ["reconciled", []],
+  ["rollback-required", ["rolled-back", "reconciled"]],
+  ["rolled-back", []]
+]);
 
 // node_modules/@supacloud/delivery/src/index.ts
 async function readDeliveryExecutableArchive(manifestPath) {
@@ -12276,7 +12378,7 @@ async function writeMigrationImportPlan(plan, outputDirectory) {
   }
   return written;
 }
-function record3(value) {
+function record4(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function sqlFile(file, root, source) {
@@ -12288,17 +12390,17 @@ function sqlFile(file, root, source) {
   };
 }
 function hasuraMetadataSql(input) {
-  const metadata = record3(input["metadata"]) ?? input;
+  const metadata = record4(input["metadata"]) ?? input;
   const sources = Array.isArray(metadata["sources"]) ? metadata["sources"] : [];
   const sql = [];
   for (const rawSource of sources) {
-    const source = record3(rawSource);
+    const source = record4(rawSource);
     if (!source)
       continue;
     const tables = Array.isArray(source["tables"]) ? source["tables"] : [];
     for (const rawTable of tables) {
-      const table = record3(rawTable);
-      const tableName = record3(table?.["table"]);
+      const table = record4(rawTable);
+      const tableName = record4(table?.["table"]);
       const schema = typeof tableName?.["schema"] === "string" ? tableName["schema"] : "public";
       const name = typeof tableName?.["name"] === "string" ? tableName["name"] : null;
       if (!name || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(schema) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
@@ -12341,7 +12443,7 @@ function createMigrationImportPlan(input) {
     }
   }
   if (input.source === "hasura" && input.metadata !== undefined) {
-    const metadata = record3(input.metadata) ?? {};
+    const metadata = record4(input.metadata) ?? {};
     const generated = hasuraMetadataSql(metadata);
     if (generated.length > 0) {
       files.push({ file: "999999999999_hasura_rls_review.sql", name: "hasura_rls_review", sql: `${generated.join(`
@@ -12354,10 +12456,10 @@ function createMigrationImportPlan(input) {
     const actions = Array.isArray(metadata["actions"]) ? metadata["actions"] : [];
     const remoteSchemas = Array.isArray(metadata["remote_schemas"]) ? metadata["remote_schemas"] : [];
     const eventTriggers = Array.isArray(metadata["sources"]) ? metadata["sources"].flatMap((source) => {
-      const sourceRecord = record3(source);
+      const sourceRecord = record4(source);
       const tables = Array.isArray(sourceRecord?.["tables"]) ? sourceRecord["tables"] : [];
       return tables.flatMap((table) => {
-        const tableRecord = record3(table);
+        const tableRecord = record4(table);
         return Array.isArray(tableRecord?.["event_triggers"]) ? tableRecord["event_triggers"] : [];
       });
     }) : [];
@@ -12407,7 +12509,7 @@ function isMigrationInventoryAppliedAt(appliedAt) {
   return appliedAt === null || typeof appliedAt === "string" && appliedAt.trim() === appliedAt && appliedAt.length > 0 && !Number.isNaN(Date.parse(appliedAt));
 }
 function migrationInventoryChecksum(entry) {
-  return createHash3("sha256").update(JSON.stringify({
+  return createHash4("sha256").update(JSON.stringify({
     version: entry.version,
     name: entry.name,
     statements: entry.statements
@@ -12514,7 +12616,7 @@ function migrationVersionFromFilename(file) {
     }
     return version.toString();
   }
-  const digest = createHash3("sha256").update(basename3(file)).digest("hex");
+  const digest = createHash4("sha256").update(basename3(file)).digest("hex");
   const offset = BigInt(`0x${digest}`) % FALLBACK_MIGRATION_VERSION_RANGE;
   return (FALLBACK_MIGRATION_VERSION_BASE + offset).toString();
 }
@@ -12611,7 +12713,7 @@ function exactIdentityIsApplied(local, remote) {
     return false;
   if (statement === `baseline:${local.name}` || statement === `direct-apply:${local.name}`)
     return true;
-  const rawChecksum = createHash3("sha256").update(local.rawBytes).digest("hex");
+  const rawChecksum = createHash4("sha256").update(local.rawBytes).digest("hex");
   return statement === `sha256:${rawChecksum}` || statement.trim() === local.sql.trim();
 }
 function legacyIdentityIsApplied(local, remote) {
@@ -15074,7 +15176,7 @@ Actions: status, list_buckets, get_bucket, create_bucket, update_bucket, delete_
 }
 
 // src/shared/tools/advanced-tools.ts
-import { createHash as createHash5, timingSafeEqual } from "node:crypto";
+import { createHash as createHash6, timingSafeEqual } from "node:crypto";
 import {
   closeSync,
   constants as fsConstants,
@@ -15095,7 +15197,7 @@ import { basename as basename5, join as join5, relative as relative2, resolve as
 
 // src/shared/tools/function-aot.ts
 import { execFile } from "node:child_process";
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash5 } from "node:crypto";
 import { readFileSync as readFileSync5 } from "node:fs";
 import { dirname as dirname3, resolve as resolve6 } from "node:path";
 import { promisify } from "node:util";
@@ -15177,7 +15279,7 @@ async function buildFunctionAot(entrypoint, outfile, options = {}) {
   const code = readFileSync5(outfile, "utf8");
   if (!code.trim())
     throw new Error("AOT build produced an empty bundle");
-  return { code, prebundled: true, expectedSha256: createHash4("sha256").update(code).digest("hex") };
+  return { code, prebundled: true, expectedSha256: createHash5("sha256").update(code).digest("hex") };
 }
 
 // src/shared/tools/edge-function-response.ts
@@ -15531,7 +15633,7 @@ function assertExpectedSha256(bytes, expectedSha256) {
   if (!SHA256_HEX_PATTERN.test(expectedSha256)) {
     throw new Error("'--expected-sha256' must be a lowercase 64-character SHA-256");
   }
-  const actualDigest = createHash5("sha256").update(bytes).digest();
+  const actualDigest = createHash6("sha256").update(bytes).digest();
   const expectedDigest = Buffer.from(expectedSha256, "hex");
   if (!timingSafeEqual(actualDigest, expectedDigest)) {
     throw new Error("Prebundled file SHA-256 does not match --expected-sha256");
@@ -16075,7 +16177,8 @@ function validReceiptVersion(activeVersion) {
 }
 function confirmedMutationVersion(receipt, config, expectation) {
   const activeVersion = receipt.active_version;
-  if (!validReceiptVersion(activeVersion) || receipt.version !== activeVersion || config.version !== activeVersion || expectation.targetVersion !== undefined && activeVersion !== expectation.targetVersion) {
+  const configVersion = config.version;
+  if (!validReceiptVersion(activeVersion) || receipt.version !== activeVersion || configVersion !== undefined && configVersion !== activeVersion || expectation.targetVersion !== undefined && activeVersion !== expectation.targetVersion) {
     return null;
   }
   return activeVersion;
@@ -16565,13 +16668,13 @@ ${JSON.stringify(r.data, null, 2)}` : `❌ Failed (${r.status}): ${JSON.stringif
 }
 
 // src/shared/tools/frontend-release-control.ts
-import { createHash as createHash7 } from "node:crypto";
+import { createHash as createHash8 } from "node:crypto";
 import { constants as fsConstants2 } from "node:fs";
 import { open as open2 } from "node:fs/promises";
 import { resolve as resolve8 } from "node:path";
 
 // src/shared/mutation-protocol.ts
-import { createHash as createHash6 } from "node:crypto";
+import { createHash as createHash7 } from "node:crypto";
 var MUTATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 var FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
 var OPERATION_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,127}$/;
@@ -16650,7 +16753,7 @@ function stableStringifyNode(jsonValue) {
 }
 function mutationRequestFingerprint(normalizedRequest) {
   assertCanonicalJsonNode(normalizedRequest, new WeakSet, 0);
-  return createHash6("sha256").update(stableStringifyNode(normalizedRequest)).digest("hex");
+  return createHash7("sha256").update(stableStringifyNode(normalizedRequest)).digest("hex");
 }
 function objectRecord3(candidate) {
   return candidate && typeof candidate === "object" && !Array.isArray(candidate) ? candidate : null;
@@ -16831,7 +16934,7 @@ function releaseFailure(operation, code, status) {
     }]
   };
 }
-function exactKeys(candidate, keys) {
+function exactKeys2(candidate, keys) {
   const actual = Object.keys(candidate).sort();
   const expected = [...keys].sort();
   return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
@@ -16853,7 +16956,7 @@ function releaseRecord(candidate) {
     "kind",
     "archive_format"
   ];
-  if (!exactKeys(record, keys) || record.schema !== FRONTEND_ARCHIVE_RELEASE_SCHEMA || record.archive_format !== FRONTEND_ARCHIVE_FORMAT || typeof record.project_ref !== "string" || !PROJECT_REF_PATTERN3.test(record.project_ref) || typeof record.deployment_id !== "string" || !DEPLOYMENT_ID_PATTERN.test(record.deployment_id) || typeof record.release_id !== "string" || !RELEASE_ID_PATTERN.test(record.release_id) || record.sha256 !== record.release_id || typeof record.tree_sha256 !== "string" || !RELEASE_ID_PATTERN.test(record.tree_sha256) || !Number.isSafeInteger(record.size_bytes) || Number(record.size_bytes) < 1 || !Number.isSafeInteger(record.file_count) || Number(record.file_count) < 1 || !canonicalTimestamp2(record.created_at) || record.kind !== "prebuilt_static")
+  if (!exactKeys2(record, keys) || record.schema !== FRONTEND_ARCHIVE_RELEASE_SCHEMA || record.archive_format !== FRONTEND_ARCHIVE_FORMAT || typeof record.project_ref !== "string" || !PROJECT_REF_PATTERN3.test(record.project_ref) || typeof record.deployment_id !== "string" || !DEPLOYMENT_ID_PATTERN.test(record.deployment_id) || typeof record.release_id !== "string" || !RELEASE_ID_PATTERN.test(record.release_id) || record.sha256 !== record.release_id || typeof record.tree_sha256 !== "string" || !RELEASE_ID_PATTERN.test(record.tree_sha256) || !Number.isSafeInteger(record.size_bytes) || Number(record.size_bytes) < 1 || !Number.isSafeInteger(record.file_count) || Number(record.file_count) < 1 || !canonicalTimestamp2(record.created_at) || record.kind !== "prebuilt_static")
     return null;
   return {
     project_ref: record.project_ref,
@@ -16872,7 +16975,7 @@ function releaseEnvelope(candidate, expected) {
   if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
     return null;
   const envelope = candidate;
-  const release = exactKeys(envelope, ["project_ref", "deployment_id", "release"]) ? releaseRecord(envelope.release) : null;
+  const release = exactKeys2(envelope, ["project_ref", "deployment_id", "release"]) ? releaseRecord(envelope.release) : null;
   if (!release || envelope.project_ref !== expected.projectRef || envelope.deployment_id !== expected.deploymentId || release.project_ref !== expected.projectRef || release.deployment_id !== expected.deploymentId || release.release_id !== expected.releaseId)
     return null;
   return release;
@@ -16900,7 +17003,7 @@ function releaseInventory(candidate, expected) {
     "releases",
     "next_cursor"
   ];
-  if (!exactKeys(record, keys) || typeof record.project_ref !== "string" || !PROJECT_REF_PATTERN3.test(record.project_ref) || typeof record.deployment_id !== "string" || !DEPLOYMENT_ID_PATTERN.test(record.deployment_id) || !Array.isArray(record.releases))
+  if (!exactKeys2(record, keys) || typeof record.project_ref !== "string" || !PROJECT_REF_PATTERN3.test(record.project_ref) || typeof record.deployment_id !== "string" || !DEPLOYMENT_ID_PATTERN.test(record.deployment_id) || !Array.isArray(record.releases))
     return null;
   const activeReleaseId = nullableIdentity(record.active_release_id, RELEASE_ID_PATTERN);
   const activeActivationId = nullableIdentity(record.active_activation_id, MUTATION_ID_PATTERN2);
@@ -16939,7 +17042,7 @@ function sameArchiveIdentity(left, right) {
   return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
 }
 async function archiveSha256(handle, sizeBytes) {
-  const hash = createHash7("sha256");
+  const hash = createHash8("sha256");
   const chunk = new Uint8Array(Math.min(sizeBytes, ARCHIVE_CHUNK_BYTES));
   for (let offset = 0;offset < sizeBytes; ) {
     const requested = Math.min(chunk.byteLength, sizeBytes - offset);
@@ -17074,7 +17177,7 @@ function stableJson(candidate) {
   return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
 }
 function activationFingerprint(identity) {
-  return createHash7("sha256").update(stableJson({
+  return createHash8("sha256").update(stableJson({
     project_ref: identity.projectRef,
     deployment_id: identity.deploymentId,
     release_id: identity.releaseId,
@@ -17091,7 +17194,7 @@ function publicMutationReceipt(candidate, expected) {
     return null;
   const envelope = candidate;
   const mutation = safeMutationStatus(envelope.mutation);
-  if (!mutation || !exactKeys(envelope, ["project_ref", "mutation"]) || envelope.project_ref !== expected.projectRef || mutation.project_ref !== expected.projectRef || mutation.mutation_id !== expected.mutationId || mutation.resource_key !== expected.resourceKey || mutation.request_fingerprint !== expected.requestFingerprint)
+  if (!mutation || !exactKeys2(envelope, ["project_ref", "mutation"]) || envelope.project_ref !== expected.projectRef || mutation.project_ref !== expected.projectRef || mutation.mutation_id !== expected.mutationId || mutation.resource_key !== expected.resourceKey || mutation.request_fingerprint !== expected.requestFingerprint)
     return null;
   return {
     operation: mutation.operation,
@@ -17106,14 +17209,14 @@ function activationReceipt(candidate, input) {
   const record = candidate;
   const release = releaseRecord(record.release);
   const mutation = record.mutation;
-  if (!release || !mutation || !exactKeys(record, [
+  if (!release || !mutation || !exactKeys2(record, [
     "project_ref",
     "deployment_id",
     "active_release_id",
     "activation_id",
     "release",
     "mutation"
-  ]) || !exactKeys(mutation, ["mutation_id", "status", "replayed"]) || record.project_ref !== input.projectRef || record.deployment_id !== input.deploymentId || record.active_release_id !== input.releaseId || record.activation_id !== input.mutationId || release.project_ref !== input.projectRef || release.deployment_id !== input.deploymentId || release.release_id !== input.releaseId || mutation.mutation_id !== input.mutationId || mutation.status !== "succeeded" || typeof mutation.replayed !== "boolean")
+  ]) || !exactKeys2(mutation, ["mutation_id", "status", "replayed"]) || record.project_ref !== input.projectRef || record.deployment_id !== input.deploymentId || record.active_release_id !== input.releaseId || record.activation_id !== input.mutationId || release.project_ref !== input.projectRef || release.deployment_id !== input.deploymentId || release.release_id !== input.releaseId || mutation.mutation_id !== input.mutationId || mutation.status !== "succeeded" || typeof mutation.replayed !== "boolean")
     return null;
   return release;
 }
@@ -17370,7 +17473,7 @@ async function readPreviousFrontendRelease(http, projectRef, deploymentId) {
   const activeActivationId = value ? nullableIdentity(value.active_activation_id, MUTATION_ID_PATTERN2) : undefined;
   const previousActivationId = value ? nullableIdentity(value.previous_activation_id, MUTATION_ID_PATTERN2) : undefined;
   const previous = value?.previous_release === null ? null : releaseRecord(value?.previous_release);
-  if (!response.ok || response.status !== 200 || !value || !exactKeys(value, [
+  if (!response.ok || response.status !== 200 || !value || !exactKeys2(value, [
     "schema",
     "project_ref",
     "deployment_id",
@@ -29564,7 +29667,7 @@ import {
 } from "@supacloud/db";
 
 // src/shared/tools/db-workflow.ts
-import { createHash as createHash8 } from "node:crypto";
+import { createHash as createHash9 } from "node:crypto";
 import { lstat as lstat4, mkdir as mkdir6, mkdtemp, readFile as readFile5, readdir as readdir6, rename as rename3, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
 import { dirname as dirname11, isAbsolute as isAbsolute7, join as join15, relative as relative8, resolve as resolve20 } from "node:path";
@@ -29853,7 +29956,7 @@ function resolveOfficialSupabaseCommand2(workdir, environment = process.env) {
 }
 
 // src/shared/tools/db-workflow.ts
-var hash4 = (content) => createHash8("sha256").update(content).digest("hex");
+var hash4 = (content) => createHash9("sha256").update(content).digest("hex");
 var result = (value, isError = false) => ({
   isError,
   content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -30957,13 +31060,13 @@ var MUTATION_TOOL_SCHEMA = {
 };
 
 // src/shared/tools/release-tools.ts
-import { createHash as createHash9 } from "node:crypto";
+import { createHash as createHash10 } from "node:crypto";
 import { existsSync as existsSync14, mkdirSync as mkdirSync5, readdirSync as readdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname12, join as join17, relative as relative9, resolve as resolve23 } from "node:path";
 var SAFE_PROJECT_REF = /^[A-Za-z0-9_-]{1,64}$/;
 var SAFE_ENVIRONMENT_ID = /^[A-Za-z0-9_-]{1,64}$/;
 var BACKUP_ID = /^logical-full_[A-Za-z0-9_-]{1,64}_[a-f0-9]{32}$/;
-var SHA256 = /^[a-f0-9]{64}$/;
+var SHA2562 = /^[a-f0-9]{64}$/;
 var SAFE_DATABASE = /^[^\u0000-\u001f\u007f]{1,128}$/;
 var INVENTORY_MAX_BYTES = 1024 * 1024;
 var MUTATION_MAX_BYTES = 64 * 1024;
@@ -30993,7 +31096,7 @@ function backupBelongsToProject(backupId, projectRef) {
   return BACKUP_ID.test(backupId) && backupId.startsWith(prefix) && /^[a-f0-9]{32}$/.test(backupId.slice(prefix.length));
 }
 function verifiedBackup(value, projectRef) {
-  if (!isRecord6(value) || typeof value.backup_id !== "string" || !backupBelongsToProject(value.backup_id, projectRef) || value.project_ref !== projectRef || typeof value.database !== "string" || !SAFE_DATABASE.test(value.database) || value.kind !== "logical-full" || !canonicalTimestamp4(value.created_at) || !canonicalTimestamp4(value.completed_at) || new Date(value.completed_at).valueOf() < new Date(value.created_at).valueOf() || typeof value.bytes !== "number" || !Number.isSafeInteger(value.bytes) || value.bytes <= 0 || typeof value.sha256 !== "string" || !SHA256.test(value.sha256))
+  if (!isRecord6(value) || typeof value.backup_id !== "string" || !backupBelongsToProject(value.backup_id, projectRef) || value.project_ref !== projectRef || typeof value.database !== "string" || !SAFE_DATABASE.test(value.database) || value.kind !== "logical-full" || !canonicalTimestamp4(value.created_at) || !canonicalTimestamp4(value.completed_at) || new Date(value.completed_at).valueOf() < new Date(value.created_at).valueOf() || typeof value.bytes !== "number" || !Number.isSafeInteger(value.bytes) || value.bytes <= 0 || typeof value.sha256 !== "string" || !SHA2562.test(value.sha256))
     return null;
   return {
     backup_id: value.backup_id,
@@ -31039,7 +31142,7 @@ function restoreRequest(projectRef, backupId, expectedSha256, restoreConfirmatio
   if (typeof backupId !== "string" || !backupBelongsToProject(backupId, projectRef)) {
     throw new Error("'backup_id' must identify a logical-full backup for 'ref'");
   }
-  if (typeof expectedSha256 !== "string" || !SHA256.test(expectedSha256)) {
+  if (typeof expectedSha256 !== "string" || !SHA2562.test(expectedSha256)) {
     throw new Error("'expected_sha256' must be a lowercase SHA-256 digest");
   }
   const confirmation = `RESTORE_PROJECT:${projectRef}:${backupId}:${expectedSha256}`;
@@ -31200,7 +31303,7 @@ function genericScopedReleaseScopeJson(scope) {
   return JSON.stringify(canonicalValue(scope));
 }
 function genericScopedReleaseScopeSha256(scope) {
-  return createHash9("sha256").update(genericScopedReleaseScopeJson(scope)).digest("hex");
+  return createHash10("sha256").update(genericScopedReleaseScopeJson(scope)).digest("hex");
 }
 function scopeEnvironmentId(scope, action) {
   const environmentId = isRecord6(scope) ? scope.targetEnvironmentId : undefined;
@@ -31469,6 +31572,73 @@ function handleScopeInspect(args) {
     }
   });
 }
+function releaseComponentView(component) {
+  if (component.kind === "migration")
+    return { kind: component.kind, name: component.name };
+  if (component.kind === "function") {
+    return { kind: component.kind, slug: component.slug, artifact_sha256: component.artifactSha256 };
+  }
+  return { kind: component.kind, artifact_sha256: component.artifactSha256 };
+}
+function handleContractPlan(args, fallbackRef) {
+  const cwd = typeof args.cwd === "string" && args.cwd.trim() ? resolve23(args.cwd.trim()) : process.cwd();
+  const requestedRef = typeof args.ref === "string" && args.ref.trim() || fallbackRef;
+  if (!requestedRef || !validProjectRef(requestedRef)) {
+    throw new Error("'ref' is required for contract_plan and must identify one project");
+  }
+  const requestedEnvironmentId = requestedScopeEnvironment(args, "contract_plan");
+  const file = typeof args.file === "string" && args.file.trim() ? args.file.trim() : "supacloud.release.json";
+  const filePath = resolve23(cwd, file);
+  if (!existsSync14(filePath)) {
+    throw new Error(`Release contract not found: ${file}`);
+  }
+  let parsedValue;
+  try {
+    parsedValue = JSON.parse(readFileSync11(filePath, "utf8"));
+  } catch {
+    throw new Error(`Release contract '${file}' is not valid JSON`);
+  }
+  const scope = parseReleaseScope(parsedValue);
+  if (scope.targetProjectRef !== requestedRef) {
+    throw new Error(`Release contract target project '${scope.targetProjectRef}' does not match requested project '${requestedRef}'`);
+  }
+  if (scope.targetEnvironmentId !== requestedEnvironmentId) {
+    throw new Error(`Release contract target environment '${scope.targetEnvironmentId}' does not match requested environment '${requestedEnvironmentId}'`);
+  }
+  const git = gitCommitInfo(cwd);
+  const sourceMatchesHead = git.head !== null && scope.sourceCommit === git.head;
+  const sourceMatchesOriginMain = git.originMain !== null && scope.sourceCommit === git.originMain;
+  if (args.require_current_source === true && !sourceMatchesHead) {
+    throw new Error(`Release contract source commit '${scope.sourceCommit}' does not match current HEAD '${git.head ?? "unavailable"}'`);
+  }
+  const counts = scope.components.reduce((result, component) => {
+    result[component.kind] += 1;
+    return result;
+  }, { migration: 0, function: 0, web: 0 });
+  return releaseControlSuccess("release.contract_plan", {
+    plan_schema: "supacloud.release-plan.v1",
+    file: relative9(cwd, filePath),
+    release_id: scope.releaseId,
+    scope_sha256: releaseScopeSha256(scope),
+    source_commit: scope.sourceCommit,
+    target_project_ref: scope.targetProjectRef,
+    target_environment_id: scope.targetEnvironmentId,
+    components: scope.components.map(releaseComponentView),
+    component_counts: counts,
+    checks: {
+      source_commit_matches_head: sourceMatchesHead,
+      source_commit_matches_origin_main: sourceMatchesOriginMain,
+      target_project_ref_matches_requested: true,
+      target_environment_id_matches_requested: true,
+      components_unique_and_sorted: true
+    },
+    current_head: git.head,
+    origin_main: git.originMain,
+    source_is_current: sourceMatchesHead,
+    read_only: true,
+    mutations_performed: false
+  });
+}
 function parseCommaList(value) {
   if (!value)
     return [];
@@ -31525,7 +31695,7 @@ function handleScopeCreate(args, fallbackRef) {
   });
 }
 function registerReleaseTools(server, http, options = {}) {
-  const localActions = ["scope_inspect", "scope_rebind", "scope_create"];
+  const localActions = ["scope_inspect", "scope_rebind", "scope_create", "contract_plan"];
   const remoteActions = [
     "logical_backup_list",
     "logical_backup_status",
@@ -31540,18 +31710,19 @@ function registerReleaseTools(server, http, options = {}) {
   registerTool(server, "release", "Verified release controls. Scope management actions operate locally; management actions use the Management API; release canary stage/disable replay additionally require the selected project's SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.", {
     action: withDescription(stringEnum2(allActions), "Release control action"),
     ref: optional(String2(), options.projectRef ? "Optional override when not auto-linked" : "Project ref"),
-    file: optional(String2(), "[scope_inspect/scope_rebind/scope_create] Path to release scope JSON file"),
+    file: optional(String2(), "[scope_inspect/scope_rebind/scope_create/contract_plan] Path to release scope or release contract JSON file"),
     files: optional(String2(), "[scope_rebind] Comma-separated list of release scope JSON files"),
     dir: optional(String2(), "[scope_rebind] Directory containing release scope JSON files (defaults to supacloud/fa/release-scopes, release-scopes, or scopes)"),
     task: optional(String2(), "[scope_rebind/scope_create] Task ID or prefix filter for scope files"),
     base_commit: optional(String2(), "[scope_rebind/scope_create] Target 40-character base commit SHA or git ref (defaults to origin/main -> main -> HEAD^ -> HEAD)"),
-    environment_id: optional(String2(), "[scope_inspect/scope_rebind/scope_create] Exact target deployment environment"),
+    environment_id: optional(String2(), "[scope_inspect/scope_rebind/scope_create/contract_plan] Exact target deployment environment"),
     functions: optional(String2(), "[scope_create] Comma-separated list of functions to deploy"),
     excluded_functions: optional(String2(), "[scope_create] Comma-separated list of functions to exclude"),
     migrations: optional(String2(), "[scope_create] Comma-separated list of migrations to apply"),
     web: optional(Boolean2(), "[scope_create] Whether web assets are included in release scope"),
     dry_run: optional(Boolean2(), "[scope_rebind] Perform calculation and validation without writing files"),
-    cwd: optional(String2(), "[scope_inspect/scope_rebind/scope_create] Base directory for relative file and git resolution"),
+    cwd: optional(String2(), "[scope_inspect/scope_rebind/scope_create/contract_plan] Base directory for relative file and git resolution"),
+    require_current_source: optional(Boolean2(), "[contract_plan] Fail unless the contract sourceCommit equals current HEAD"),
     backup_id: optional(String2(), "[logical_backup_create/status/restore] Stable project-bound backup ID; create generates one when omitted"),
     expected_sha256: optional(String2(), "[logical_backup_restore] Exact lowercase SHA-256 from the selected project inventory"),
     restore_confirmation: optional(String2(), "[logical_backup_restore] Exact RESTORE_PROJECT:<ref>:<backup_id>:<sha256> confirmation"),
@@ -31571,6 +31742,9 @@ function registerReleaseTools(server, http, options = {}) {
     if (action === "scope_create") {
       return handleScopeCreate(args, options.projectRef);
     }
+    if (action === "contract_plan") {
+      return handleContractPlan(args, options.projectRef);
+    }
     if (options.localOnly || !http) {
       return {
         isError: true,
@@ -31744,7 +31918,7 @@ function registerReleaseTools(server, http, options = {}) {
 // src/shared/tools/deploy-tools.ts
 import { access, lstat as lstat5, mkdtemp as mkdtemp2, opendir, readFile as readFile6, rm as rm3, writeFile as writeFile6 } from "node:fs/promises";
 import { spawn as spawn2 } from "node:child_process";
-import { createHash as createHash10 } from "node:crypto";
+import { createHash as createHash11 } from "node:crypto";
 import { tmpdir as tmpdir3 } from "node:os";
 import { basename as basename8, dirname as dirname13, join as join18, relative as relative10, resolve as resolve24, sep as sep5 } from "node:path";
 
@@ -31840,7 +32014,7 @@ var deployToolSchema = {
   status: optional(String2({ format: "uuid" }), "Read a backend deployment status without publishing"),
   json: optional(Boolean2(), "Print only the final JSON result")
 };
-function record4(candidate) {
+function record5(candidate) {
   return candidate && typeof candidate === "object" && !Array.isArray(candidate) ? candidate : null;
 }
 function requiredString(candidate, field) {
@@ -31850,7 +32024,7 @@ function requiredString(candidate, field) {
   return candidate.trim();
 }
 function frontendDeployment(candidate) {
-  const value = record4(candidate);
+  const value = record5(candidate);
   if (!value)
     throw new Error("Invalid frontend deployment response");
   return {
@@ -31920,7 +32094,7 @@ function optionalStringArray(value, field) {
   });
 }
 function deployTargetConfig(candidate, name) {
-  const value = record4(candidate);
+  const value = record5(candidate);
   if (!value || value.type !== "frontend" && value.type !== "edge_function") {
     throw new Error(`supacloud.json targets.${name}.type must be 'frontend' or 'edge_function'`);
   }
@@ -31949,10 +32123,10 @@ async function readDeployConfig(configRoot) {
   const candidate = await readJson(configPath);
   if (candidate === null)
     return {};
-  const config = record4(candidate);
-  const frontend = record4(config?.frontend);
-  const application = record4(config?.application);
-  const targetValues = record4(config?.targets);
+  const config = record5(candidate);
+  const frontend = record5(config?.frontend);
+  const application = record5(config?.application);
+  const targetValues = record5(config?.targets);
   if (!config || config.frontend !== undefined && !frontend || config.application !== undefined && !application || config.targets !== undefined && !targetValues) {
     throw new Error("supacloud.json must contain object-valued 'application', 'frontend' or 'targets' configuration");
   }
@@ -31992,7 +32166,7 @@ async function readDeployConfig(configRoot) {
   };
 }
 async function packageName(projectDirectory) {
-  const candidate = record4(await readJson(join18(projectDirectory, "package.json")));
+  const candidate = record5(await readJson(join18(projectDirectory, "package.json")));
   return typeof candidate?.name === "string" && candidate.name.trim() ? candidate.name.trim() : null;
 }
 async function pathExists(path) {
@@ -32018,8 +32192,8 @@ async function hasProjectReleaseManifest(root) {
   return false;
 }
 async function defaultBuildCommand(projectDirectory, configRoot) {
-  const packageJson = record4(await readJson(join18(projectDirectory, "package.json")));
-  const scripts = record4(packageJson?.scripts);
+  const packageJson = record5(await readJson(join18(projectDirectory, "package.json")));
+  const scripts = record5(packageJson?.scripts);
   if (typeof scripts?.build !== "string" || !scripts.build.trim()) {
     throw new Error("No build command was configured and package.json has no build script");
   }
@@ -32041,7 +32215,7 @@ async function defaultBuildCommand(projectDirectory, configRoot) {
   return "npm run build";
 }
 function deploymentList(candidate) {
-  const values = Array.isArray(candidate) ? candidate : Array.isArray(record4(candidate)?.deployments) ? record4(candidate)?.deployments : null;
+  const values = Array.isArray(candidate) ? candidate : Array.isArray(record5(candidate)?.deployments) ? record5(candidate)?.deployments : null;
   if (!values)
     throw new Error("Invalid frontend deployment list response");
   return values.map(frontendDeployment);
@@ -32201,9 +32375,9 @@ async function collectArchiveFiles(root) {
       throw new Error(`Frontend output exceeds ${MAX_SOURCE_BYTES} bytes`);
     const archivePath = relative10(root, path).split(sep5).join("/");
     files.set(archivePath, data);
-    digests.push({ path: archivePath, size: data.byteLength, sha256: createHash10("sha256").update(data).digest("hex") });
+    digests.push({ path: archivePath, size: data.byteLength, sha256: createHash11("sha256").update(data).digest("hex") });
   }
-  const tree = createHash10("sha256");
+  const tree = createHash11("sha256");
   for (const file of digests.sort((left, right) => left.path.localeCompare(right.path))) {
     const pathBytes = Buffer.from(file.path, "utf8");
     const frame = Buffer.alloc(12);
@@ -32219,7 +32393,7 @@ async function createCollectedFrontendArchive(outputDirectory, collected) {
   try {
     const archiveBytes = await createFrontendTarZstd(collected.files);
     await writeFile6(archivePath, archiveBytes);
-    const sha256 = createHash10("sha256").update(archiveBytes).digest("hex");
+    const sha256 = createHash11("sha256").update(archiveBytes).digest("hex");
     return {
       archivePath,
       sha256,
@@ -32341,7 +32515,7 @@ function registerDeployTools(server, http, options = {}) {
 import { existsSync as existsSync15 } from "node:fs";
 import { readFile as readFile7 } from "node:fs/promises";
 import { readdir as readdir7 } from "node:fs/promises";
-import { createHash as createHash11 } from "node:crypto";
+import { createHash as createHash12 } from "node:crypto";
 import { join as join19, resolve as resolve25 } from "node:path";
 import { compileProject as compileProject2 } from "@supacloud/compiler";
 var SAFE_TOKEN = /^[A-Za-z0-9._:@/+,-]+$/;
@@ -32440,7 +32614,7 @@ async function sourceFingerprint(root) {
     }
   };
   await visit(root);
-  const hash = createHash11("sha256");
+  const hash = createHash12("sha256");
   for (const file of files) {
     hash.update(file.slice(root.length).replace(/\\/g, "/"));
     hash.update(await readFile7(file));
@@ -32840,7 +33014,7 @@ function textResult3(text, isError = false) {
 function jsonResult(value, isError = false) {
   return textResult3(JSON.stringify(value, null, 2), isError);
 }
-function record5(value) {
+function record6(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function packageDependencies(manifest) {
@@ -32863,12 +33037,12 @@ async function readPackageManifest(root) {
     return {};
   try {
     const parsed = JSON.parse(await readFile8(path, "utf8"));
-    const value = record5(parsed);
+    const value = record6(parsed);
     if (!value)
       throw new Error("package.json must contain an object");
-    const scripts = record5(value.scripts);
-    const dependencies = record5(value.dependencies);
-    const devDependencies = record5(value.devDependencies);
+    const scripts = record6(value.scripts);
+    const dependencies = record6(value.dependencies);
+    const devDependencies = record6(value.devDependencies);
     return {
       scripts: scripts ?? undefined,
       dependencies: dependencies ?? undefined,
@@ -33026,9 +33200,9 @@ async function inspectProfile(profile) {
         return "{}";
       throw error;
     });
-    const config = record5(JSON.parse(configText));
-    const hasFrontend = record5(config?.frontend) !== null || Object.values(record5(config?.targets) ?? {}).some((target) => record5(target)?.type === "frontend");
-    const deploy = deployMissing(context, record5(config?.application), hasFrontend);
+    const config = record6(JSON.parse(configText));
+    const hasFrontend = record6(config?.frontend) !== null || Object.values(record6(config?.targets) ?? {}).some((target) => record6(target)?.type === "frontend");
+    const deploy = deployMissing(context, record6(config?.application), hasFrontend);
     return {
       name: profile.name,
       path: profile.path,
@@ -33247,7 +33421,7 @@ async function runProjectDeployment(http, args) {
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.110.0",
+  version: "0.111.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -33300,13 +33474,13 @@ var package_default = {
   },
   dependencies: {
     "@supacloud/compiler": "^0.52.0",
-    "@supacloud/delivery": "0.22.0",
+    "@supacloud/delivery": "0.23.0",
     "@supacloud/db": "0.20.1",
     typebox: "1.4.2"
   },
   overrides: {
     "@supacloud/contracts": "0.15.1",
-    "@supacloud/delivery": "0.22.0",
+    "@supacloud/delivery": "0.23.0",
     "@graphql-tools/utils": "^12.0.4"
   },
   devDependencies: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/cli",
-  "version": "0.110.0",
+  "version": "0.111.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,13 +53,13 @@
   },
   "dependencies": {
     "@supacloud/compiler": "^0.52.0",
-    "@supacloud/delivery": "0.22.0",
+    "@supacloud/delivery": "0.23.0",
     "@supacloud/db": "0.20.1",
     "typebox": "1.4.2"
   },
   "overrides": {
     "@supacloud/contracts": "0.15.1",
-    "@supacloud/delivery": "0.22.0",
+    "@supacloud/delivery": "0.23.0",
     "@graphql-tools/utils": "^12.0.4"
   },
   "devDependencies": {