primitive-admin 1.1.0-alpha.37 → 1.1.0-alpha.39

package/dist/src/commands/sync.js

@@ -5,13 +5,16 @@ import * as TOML from "@iarna/toml";
 import { lookup as mimeLookup } from "mime-types";
 import { ApiClient, ApiError, ConflictError, SchemaRequiredError, OperationRefError, SchemaBreaksOpsError, SchemaHasUncheckableOpsError, TomlParseError, OpsExistError, } from "../lib/api-client.js";
 import { buildDatabaseTypeTomlData, detectExistingOperationForms, normalizeOperationFromToml, normalizeSubscriptionFromToml, SubscriptionAccessKeyConflictError, } from "../lib/toml-database-config.js";
+import { parseMetadataCategoryToml, validateMetadataCategoryConfig, serializeMetadataCategoryConfig, parseDeclaredAccessManifestToml, validateDeclaredAccessManifest, serializeDeclaredAccessManifest, } from "../lib/toml-metadata-config.js";
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { getServerUrl, resolveAppId } from "../lib/config.js";
 import { resolveSyncDir, resolveSnapshotsRoot, isAutoResolvedSyncDir, checkLegacySyncMigration, } from "../lib/sync-paths.js";
 import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
-import { success, error, info, warn, keyValue, json, divider, } from "../lib/output.js";
+import { applyWorkflowBody } from "../lib/workflow-apply.js";
+import { detectLayout, migrateLegacyToV2 } from "../lib/block-layout.js";
+import { success, error, printApiError, info, warn, keyValue, json, divider, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import chalk from "chalk";
 function ensureDir(dirPath) {
@@ -199,6 +202,87 @@ export function hashRemoteWorkflowForDiff(workflow, draft, configs) {
     const parsed = TOML.parse(serialized);
     return hashWorkflowTomlForDiff(parsed);
 }
+// Boolean [auth] keys in app.toml that map 1:1 to app-settings fields.
+const AUTH_BOOLEAN_KEYS = [
+    "googleOAuthEnabled",
+    "passkeyEnabled",
+    "magicLinkEnabled",
+    "appleSignInEnabled",
+    "otpEnabled",
+];
+// Every recognized [auth] key. Single source of truth shared by pull
+// serialization, push parsing, and the unrecognized-key warning so the three
+// never drift apart. `appleAudiences` is a string array and `passkeys` is the
+// passkey RP config object; the rest are booleans.
+const RECOGNIZED_AUTH_KEYS = new Set([
+    ...AUTH_BOOLEAN_KEYS,
+    "appleAudiences",
+    "passkeys",
+]);
+/**
+ * Build the [auth] block of app.toml from server settings (pull direction).
+ *
+ * Apple/OTP fields round-trip alongside the legacy google/passkey/magic-link
+ * keys. Two asymmetries are handled deliberately:
+ *  - `appleSignInEnabled` comes back as `boolean | null`; @iarna/toml throws on
+ *    null, so an unset value (null) is omitted rather than written.
+ *  - `appleAudiences` is omitted when empty. An empty array and an omitted key
+ *    both mean "no audiences" (the server normalizes [] -> null), so omitting
+ *    an empty list on pull is not lossy.
+ */
+export function serializeAuthBlock(settings) {
+    const auth = {
+        googleOAuthEnabled: settings.googleOAuthEnabled,
+        passkeyEnabled: settings.passkeyEnabled,
+        magicLinkEnabled: settings.magicLinkEnabled,
+    };
+    if (typeof settings.appleSignInEnabled === "boolean") {
+        auth.appleSignInEnabled = settings.appleSignInEnabled;
+    }
+    if (Array.isArray(settings.appleAudiences) &&
+        settings.appleAudiences.length > 0) {
+        auth.appleAudiences = settings.appleAudiences;
+    }
+    if (typeof settings.otpEnabled === "boolean") {
+        auth.otpEnabled = settings.otpEnabled;
+    }
+    if (settings.passkeyRpConfig) {
+        auth.passkeys = settings.passkeyRpConfig;
+    }
+    return auth;
+}
+/**
+ * Translate the [auth] block of app.toml into app-settings fields (push
+ * direction).
+ *
+ * Only keys actually present in the TOML are forwarded — an omitted key is left
+ * untouched so it never overwrites server state (e.g. flipping a previously-true
+ * flag to false). An explicit value, including `false`, is forwarded as-is.
+ * `appleAudiences = []` is forwarded too; the server normalizes [] -> null
+ * ("no audiences"). Keys outside RECOGNIZED_AUTH_KEYS produce a warning rather
+ * than a hard error, so a typo or a future key doesn't silently drop.
+ */
+export function parseAppAuthSettings(auth) {
+    const settings = {};
+    const warnings = [];
+    for (const key of AUTH_BOOLEAN_KEYS) {
+        if (key in auth)
+            settings[key] = auth[key];
+    }
+    if ("appleAudiences" in auth) {
+        settings.appleAudiences = auth.appleAudiences;
+    }
+    if ("passkeys" in auth) {
+        settings.passkeyRpConfig = auth.passkeys;
+    }
+    for (const key of Object.keys(auth)) {
+        if (!RECOGNIZED_AUTH_KEYS.has(key)) {
+            warnings.push(`Unrecognized [auth] key "${key}" in app.toml — ignored. ` +
+                `Recognized keys: ${[...RECOGNIZED_AUTH_KEYS].join(", ")}.`);
+        }
+    }
+    return { settings, warnings };
+}
 // TOML serialization helpers
 function serializeAppSettings(settings) {
     const data = {
@@ -208,15 +292,8 @@ function serializeAppSettings(settings) {
             waitlistEnabled: settings.waitlistEnabled,
             baseUrl: settings.baseUrl,
         },
-        auth: {
-            googleOAuthEnabled: settings.googleOAuthEnabled,
-            passkeyEnabled: settings.passkeyEnabled,
-            magicLinkEnabled: settings.magicLinkEnabled,
-        },
+        auth: serializeAuthBlock(settings),
     };
-    if (settings.passkeyRpConfig) {
-        data.auth.passkeys = settings.passkeyRpConfig;
-    }
     if (settings.corsMode === "custom") {
         data.cors = {
             mode: settings.corsMode,
@@ -256,6 +333,15 @@ function serializeWebhook(webhook) {
             secretGracePeriodMs: webhook.secretGracePeriodMs,
         },
     };
+    // Re-emit a `{{secrets.KEY}}` reference so a pull→push round-trip is lossless
+    // (#1235). The server only returns `signingSecret` when it is such a
+    // reference (a real secret is returned masked, never in plaintext); guard on
+    // the template shape here too so a masked or raw value can never be written
+    // to TOML.
+    if (typeof webhook.signingSecret === "string" &&
+        /\{\{secrets\.[A-Z][A-Z0-9_]{0,63}\}\}/.test(webhook.signingSecret)) {
+        data.webhook.signingSecret = webhook.signingSecret;
+    }
     // Parse JSON fields if they're strings
     if (webhook.allowedIpCidrs) {
         try {
@@ -371,7 +457,7 @@ function serializePrompt(prompt) {
     };
     return TOML.stringify(data);
 }
-function serializeWorkflow(workflow, draft, configs) {
+export function serializeWorkflow(workflow, draft, configs) {
     // Find the active config or use the first one
     const activeConfigId = workflow.activeConfigId;
     const activeConfig = configs?.find((c) => c.configId === activeConfigId) || configs?.[0];
@@ -391,6 +477,15 @@ function serializeWorkflow(workflow, draft, configs) {
             // #1081 — workflow principal mode. Emit only when set so a fresh
             // pull → push round-trips it without writing a noisy `runAs = ""`.
             runAs: workflow.runAs || undefined,
+            // #1233 — opt-in sensitive capability grants. The GET response always
+            // returns an array (empty when unset); emit only when non-empty so a
+            // fresh pull → push round-trips a real value without writing a noisy
+            // `capabilities = []`. This is the load-bearing fix: before this, pull
+            // dropped capabilities entirely and a pull → push cycle silently cleared
+            // them on the server.
+            capabilities: Array.isArray(workflow.capabilities) && workflow.capabilities.length > 0
+                ? workflow.capabilities
+                : undefined,
             perUserMaxRunning: workflow.perUserMaxRunning,
             perUserMaxQueued: workflow.perUserMaxQueued,
             dequeueOrder: workflow.dequeueOrder,
@@ -413,6 +508,10 @@ function serializeWorkflow(workflow, draft, configs) {
             status: config.status,
             isActive: config.configId === activeConfigId,
         })) || [],
+        // #1304 (P-C): the declared-access manifest — top-level `[metadata]` /
+        // `secrets`, merged the same way the collection/database type configs do so
+        // a workflow's `md`/`secrets` declarations round-trip through pull → push.
+        ...serializeDeclaredAccessManifest(workflow.metadataManifest),
     };
     return TOML.stringify(data);
 }
@@ -486,6 +585,9 @@ function serializeCollectionTypeConfig(config, ruleSetIdToName) {
             collectionType: config.collectionType,
             ruleSetName: ruleSetName,
         },
+        // Declared-access manifest (issue #1304, P-C): merge the top-level
+        // `[metadata]` + `secrets` fragments so a pull→push→pull cycle round-trips.
+        ...serializeDeclaredAccessManifest(config.metadataManifest),
     };
     return TOML.stringify(data);
 }
@@ -530,6 +632,17 @@ export function parseDatabaseTypeToml(tomlData) {
     if (tomlData.triggers) {
         typeConfig.triggers = tomlData.triggers;
     }
+    // Declared-access manifest (issue #1304, P-C): the top-level `[metadata]` +
+    // `secrets` blocks. Validated locally before push; the server re-validates
+    // (graph/schema) at persist time.
+    const manifest = parseDeclaredAccessManifestToml(tomlData);
+    if (manifest) {
+        const manifestError = validateDeclaredAccessManifest(manifest);
+        if (manifestError) {
+            throw new Error(`Invalid metadata manifest in database type "${typeSection.databaseType || ""}": ${manifestError}`);
+        }
+        typeConfig.metadataManifest = manifest;
+    }
     // Issue #666: extract the `[models.*]` subtree (if present) and re-serialize
     // it to a TOML string for the server's `schema` field.
     //
@@ -598,6 +711,17 @@ export function parseCollectionTypeConfigToml(tomlData) {
     else if (section.ruleSetId && section.ruleSetId !== "") {
         result.ruleSetId = section.ruleSetId;
     }
+    // Declared-access manifest (issue #1304, P-C): the top-level `[metadata]` +
+    // `secrets` blocks. Validated locally before push; the server re-validates
+    // (graph/schema) at persist time.
+    const manifest = parseDeclaredAccessManifestToml(tomlData);
+    if (manifest) {
+        const manifestError = validateDeclaredAccessManifest(manifest);
+        if (manifestError) {
+            throw new Error(`Invalid metadata manifest in collection type config "${section.collectionType || ""}": ${manifestError}`);
+        }
+        result.metadataManifest = manifest;
+    }
     return result;
 }
 // Parsing helpers
@@ -681,7 +805,14 @@ export function resolveSlugCollisions(slug, usedSlugs) {
     return resolved;
 }
 function getTestsDir(configDir, blockType, blockKey) {
-    const typeDir = blockType === "prompt" ? "prompts" : "workflows";
+    // Scripts (blockType "script") live under `transforms/` on disk (their
+    // bodies are `transforms/<name>.rhai`), so their test cases sit alongside at
+    // `transforms/<name>.tests/`. Prompts and workflows keep their own dirs.
+    const typeDir = blockType === "prompt"
+        ? "prompts"
+        : blockType === "script"
+            ? "transforms"
+            : "workflows";
     return join(configDir, typeDir, `${blockKey}.tests`);
 }
 export function serializeTestCase(testCase, lookupMaps) {
@@ -771,17 +902,33 @@ export function parseTestCaseToml(tomlData) {
 /**
  * Pull server-side `Script` rows into `transforms/*.rhai` and record
  * each in the returned sync-state map. Issue #892 slice 7 + codex
- * follow-up on PR #893. Exported so the unit test can drive it
- * against a stubbed `client.listScripts`.
+ * follow-up on PR #893; body materialization fixed in issue #1196.
+ * Exported so the unit test can drive it against stubbed
+ * `client.listScripts` / `client.getScript`.
+ *
+ * Two-call contract: `listScripts` returns the `Script` HEADER only
+ * (no `body` — see `serializeScript` in `src/admin-api.ts`). The Rhai
+ * source lives on a versioned `ScriptConfig`. So for each listed
+ * script we fetch the full record with `getScript`, which returns the
+ * header plus serialized `configs` (each carrying its `body`), and
+ * write the ACTIVE config's body. Reading the body off the list shape
+ * (the old behavior) always produced 0-byte files.
  *
- * Idempotency: every call writes the body the server returned, so
- * re-running `sync pull` on an unchanged server overwrites with the
- * same bytes and produces the same `contentHash`. The result map
- * always reflects the current server state for the writes performed.
+ * Idempotency: every call writes the active-config body the server
+ * returned, so re-running `sync pull` on an unchanged server overwrites
+ * with the same bytes and produces the same `contentHash`. The result
+ * map always reflects the current server state for the writes performed.
+ *
+ * `count` is the number of files actually written, not the number of
+ * scripts listed: scripts with no active config and scripts whose
+ * config fetch fails are skipped (we never clobber a `.rhai` with an
+ * empty file).
  *
  * Older-server graceful path: if `listScripts` rejects (e.g. older
  * server without the route), the caller catches and treats it as
- * "no scripts to pull", leaving the directory empty.
+ * "no scripts to pull", leaving the directory empty. A per-script
+ * `getScript` failure is caught and that one script is skipped without
+ * aborting the rest of the pull.
  */
 export async function pullScripts(client, appId, configDir, logger = () => { }) {
     const transformsDir = join(configDir, "transforms");
@@ -795,22 +942,49 @@ export async function pullScripts(client, appId, configDir, logger = () => { })
     catch {
         return { scriptEntities, count: 0 };
     }
+    let written = 0;
     for (const script of items) {
         const name = script?.name;
         if (!name)
             continue;
+        // The body lives on the active `ScriptConfig`, not the header. Skip
+        // scripts with no active config rather than writing an empty file.
+        if (!script.activeConfigId) {
+            logger(`  Skipped transforms/${name}.rhai (no active config)`);
+            continue;
+        }
+        // Fetch the full script (header + serialized configs with bodies).
+        // Tolerate a per-script failure: skip this one, keep the rest.
+        let full;
+        try {
+            full = await client.getScript(appId, script.scriptId);
+        }
+        catch {
+            logger(`  Skipped transforms/${name}.rhai (could not fetch config)`);
+            continue;
+        }
+        const configs = Array.isArray(full?.configs) ? full.configs : [];
+        const activeConfigId = full?.activeConfigId ?? script.activeConfigId;
+        const activeConfig = configs.find((c) => c.configId === activeConfigId) ||
+            configs.find((c) => c.status === "active");
+        if (!activeConfig || typeof activeConfig.body !== "string") {
+            logger(`  Skipped transforms/${name}.rhai (no active config body)`);
+            continue;
+        }
         const filename = `${name}.rhai`;
         const filePath = join(transformsDir, filename);
-        const body = typeof script.body === "string" ? script.body : "";
-        writeFileSync(filePath, body);
+        writeFileSync(filePath, activeConfig.body);
         scriptEntities[name] = {
             id: script.scriptId,
             modifiedAt: script.modifiedAt || new Date().toISOString(),
+            // Recompute from the written file (not the server's contentHash) so
+            // it matches what `sync push`'s `shouldPushFile` gate recomputes.
             contentHash: computeFileHash(filePath),
         };
+        written += 1;
         logger(`  Wrote transforms/${filename}`);
     }
-    return { scriptEntities, count: items.length };
+    return { scriptEntities, count: written };
 }
 async function pullTestCasesForBlock(client, appId, blockType, blockId, blockKey, configDir, testCaseEntities, lookupMaps) {
     let testCases;
@@ -920,8 +1094,10 @@ async function pushTestCasesForBlock(client, appId, blockType, blockId, blockKey
                 const configMapKey = `${blockKey}#${testPayload._configName}`;
                 const configMap = blockType === "prompt"
                     ? resolutionMaps.promptConfigNameToId
-                    : resolutionMaps.workflowConfigNameToId;
-                const resolvedId = configMap.get(configMapKey);
+                    : blockType === "script"
+                        ? resolutionMaps.scriptConfigNameToId
+                        : resolutionMaps.workflowConfigNameToId;
+                const resolvedId = configMap?.get(configMapKey);
                 if (resolvedId) {
                     testPayload.configId = resolvedId;
                 }
@@ -1123,6 +1299,7 @@ Directory Structure:
     rule-sets/*.toml                # Access rule sets
     group-type-configs/*.toml       # Group type configs
     collection-type-configs/*.toml  # Collection type configs
+    metadata-category-configs/*.toml # Resource-metadata category configs
     email-templates/*.toml          # Email template overrides
 `);
     // Init
@@ -1153,6 +1330,7 @@ Directory Structure:
         ensureDir(join(configDir, "rule-sets"));
         ensureDir(join(configDir, "group-type-configs"));
         ensureDir(join(configDir, "collection-type-configs"));
+        ensureDir(join(configDir, "metadata-category-configs"));
         ensureDir(join(configDir, "email-templates"));
         const state = {
             appId: resolvedAppId,
@@ -1224,11 +1402,12 @@ Directory Structure:
                 return;
             }
             // Fetch database config resources
-            const [databaseTypeConfigsResult, ruleSetsResult, groupTypeConfigsResult, collectionTypeConfigsResult,] = await Promise.all([
+            const [databaseTypeConfigsResult, ruleSetsResult, groupTypeConfigsResult, collectionTypeConfigsResult, metadataCategoryConfigsResult,] = await Promise.all([
                 client.listDatabaseTypeConfigs(resolvedAppId).catch(() => []),
                 client.listRuleSets(resolvedAppId).catch(() => []),
                 client.listGroupTypeConfigs(resolvedAppId).catch(() => []),
                 client.listCollectionTypeConfigs(resolvedAppId).catch(() => []),
+                client.listMetadataCategoryConfigs(resolvedAppId).catch(() => []),
             ]);
             // Fetch operations + subscriptions for each database type. Issue #803:
             // subscriptions are pulled symmetrically with operations so a
@@ -1287,6 +1466,7 @@ Directory Structure:
             ensureDir(join(configDir, "rule-sets"));
             ensureDir(join(configDir, "group-type-configs"));
             ensureDir(join(configDir, "collection-type-configs"));
+            ensureDir(join(configDir, "metadata-category-configs"));
             ensureDir(join(configDir, "email-templates"));
             // Write app settings
             if (settings) {
@@ -1425,6 +1605,23 @@ Directory Structure:
                     }
                 }
             }
+            // Include script config names so a pinned script test case
+            // round-trips its `configName` reference (the same way prompt/workflow
+            // configs above do). One extra `configs` fetch per pulled script.
+            for (const [name, entity] of Object.entries(scriptEntities)) {
+                try {
+                    const { items: scriptConfigs } = await client.listScriptConfigs(resolvedAppId, entity.id);
+                    for (const config of scriptConfigs) {
+                        configIdToName.set(config.configId, config.configName);
+                    }
+                }
+                catch {
+                    // Non-fatal: a script test case pinned to a config just serializes
+                    // without a resolvable name (falls back to active on push). The
+                    // header/body still pulled fine — `name` retained for clarity.
+                    void name;
+                }
+            }
             const testCaseLookupMaps = { configIdToName, promptIdToKey };
             // Write email templates (use detailed emailTemplates, not summaries)
             const emailTemplateEntities = {};
@@ -1467,6 +1664,15 @@ Directory Structure:
                 }
                 totalTestCases += count;
             }
+            // Pull test cases for scripts (transforms). Script blocks use
+            // blockType "script"; their tests land under transforms/<name>.tests/.
+            for (const [name, entity] of Object.entries(scriptEntities)) {
+                const count = await pullTestCasesForBlock(client, resolvedAppId, "script", entity.id, name, configDir, testCaseEntities, testCaseLookupMaps);
+                if (count > 0) {
+                    info(`  Wrote ${count} test case(s) for script: ${name}`);
+                }
+                totalTestCases += count;
+            }
             // Build ruleSetId → name map for database types and group type configs
             const ruleSets = Array.isArray(ruleSetsResult) ? ruleSetsResult : [];
             const ruleSetIdToName = new Map();
@@ -1562,6 +1768,23 @@ Directory Structure:
                 };
                 info(`  Wrote collection-type-configs/${filename}`);
             }
+            // Write metadata category configs (issue #1304, P-B). One file per
+            // `{resourceType, category}`; the entity key is the `resourceType#category`
+            // pair so push can match it back.
+            const metadataCategoryConfigEntities = {};
+            const metadataCategoryConfigs = Array.isArray(metadataCategoryConfigsResult)
+                ? metadataCategoryConfigsResult
+                : [];
+            for (const config of metadataCategoryConfigs) {
+                const filename = `${config.resourceType}.${config.category}.toml`;
+                const filePath = join(configDir, "metadata-category-configs", filename);
+                writeFileSync(filePath, serializeMetadataCategoryConfig(config));
+                metadataCategoryConfigEntities[`${config.resourceType}#${config.category}`] = {
+                    modifiedAt: config.modifiedAt || new Date().toISOString(),
+                    contentHash: computeFileHash(filePath),
+                };
+                info(`  Wrote metadata-category-configs/${filename}`);
+            }
             // Save sync state
             const state = {
                 appId: resolvedAppId,
@@ -1584,6 +1807,9 @@ Directory Structure:
                     collectionTypeConfigs: Object.keys(collectionTypeConfigEntities).length > 0
                         ? collectionTypeConfigEntities
                         : undefined,
+                    metadataCategoryConfigs: Object.keys(metadataCategoryConfigEntities).length > 0
+                        ? metadataCategoryConfigEntities
+                        : undefined,
                 },
             };
             saveSyncState(configDir, state);
@@ -1602,6 +1828,7 @@ Directory Structure:
             keyValue("Rule Sets", ruleSets.length);
             keyValue("Group Type Configs", groupTypeConfigs.length);
             keyValue("Collection Type Configs", collectionTypeConfigs.length);
+            keyValue("Metadata Category Configs", metadataCategoryConfigs.length);
         }
         catch (err) {
             error(err.message);
@@ -1877,11 +2104,10 @@ Directory Structure:
                         }
                     }
                     if (tomlData.auth) {
-                        settings.googleOAuthEnabled = tomlData.auth.googleOAuthEnabled;
-                        settings.passkeyEnabled = tomlData.auth.passkeyEnabled;
-                        settings.magicLinkEnabled = tomlData.auth.magicLinkEnabled;
-                        if (tomlData.auth.passkeys) {
-                            settings.passkeyRpConfig = tomlData.auth.passkeys;
+                        const { settings: authSettings, warnings: authWarnings } = parseAppAuthSettings(tomlData.auth);
+                        Object.assign(settings, authSettings);
+                        for (const w of authWarnings) {
+                            warn(`  ${w}`);
                         }
                     }
                     if (tomlData.cors) {
@@ -2099,6 +2325,14 @@ Directory Structure:
                         deduplicationWindowMs: webhook.deduplicationWindowMs,
                         secretGracePeriodMs: webhook.secretGracePeriodMs,
                     };
+                    // Forward the declared signing secret so a `{{secrets.KEY}}`
+                    // reference reaches the server intact (#1235). Without this the
+                    // value declared in TOML is silently dropped and the server
+                    // rejects a verified webhook with "signingSecret is required".
+                    // Mirrors how integrations forward requestConfig with refs intact.
+                    if (webhook.signingSecret !== undefined) {
+                        payload.signingSecret = webhook.signingSecret;
+                    }
                     // Handle JSON fields
                     if (tomlData.allowedIps?.cidrs) {
                         payload.allowedIpCidrs = JSON.stringify(tomlData.allowedIps.cidrs);
@@ -2731,6 +2965,19 @@ Directory Structure:
                     const workflow = tomlData.workflow || {};
                     const key = workflow.key || basename(file, ".toml");
                     const steps = tomlData.steps || [];
+                    // #1304 (P-C): the declared-access manifest lives at top-level
+                    // `[metadata]` / `secrets` (same shape the database/collection type
+                    // configs use). Parse + surface-validate it, then carry it on the
+                    // `workflow` payload object so it flows through both the create call
+                    // and the shared `applyWorkflowBody` update. A null manifest (no
+                    // `[metadata]`) clears it on the server so pull → push round-trips a
+                    // drop; the deep graph check runs server-side at persist.
+                    const workflowManifest = parseDeclaredAccessManifestToml(tomlData);
+                    const workflowManifestError = validateDeclaredAccessManifest(workflowManifest);
+                    if (workflowManifestError) {
+                        throw new Error(`${filePath}: ${workflowManifestError}`);
+                    }
+                    workflow.metadataManifest = workflowManifest;
                     const existingId = syncState?.entities?.workflows?.[key]?.id;
                     const existingActiveConfigId = syncState?.entities?.workflows?.[key]?.activeConfigId;
                     // Skip if file hasn't changed since last sync. Use the expanded
@@ -2751,6 +2998,45 @@ Directory Structure:
                         }
                         continue;
                     }
+                    // Shared update body for both the in-manifest update branch and the
+                    // adopt-by-key recovery branch (#1174). The body is large and
+                    // ordering-sensitive (metadata PATCH → config/draft steps →
+                    // deferred `syncCallable` PATCH); both call sites MUST run it
+                    // identically, so it lives here as a single closure rather than
+                    // being duplicated. `activeConfigId` is passed in explicitly: the
+                    // update branch reads it from sync state, while the adopt branch
+                    // seeds it from a fresh `getWorkflow` (sync state has none for an
+                    // out-of-manifest workflow).
+                    const applyWorkflowUpdate = async (workflowId, opts) => {
+                        const { expectedModifiedAt, activeConfigId } = opts;
+                        // The ordering-sensitive core (metadata PATCH → config/draft
+                        // steps → deferred `syncCallable` PATCH, #807) lives in the
+                        // shared `applyWorkflowBody` helper so `workflows update
+                        // --from-file` runs it identically (#1249, Fork 4). The
+                        // sync-specific bookkeeping (the progress log, sync-state
+                        // `modifiedAt`/hash, and config name→ID map) stays here.
+                        const { latestModifiedAt, updateSlotLabel, fullWorkflow } = await applyWorkflowBody(client, resolvedAppId, workflowId, workflow, steps, {
+                            expectedModifiedAt,
+                            activeConfigId,
+                            force: options.force,
+                        });
+                        info(`  Updated workflow: ${key} (${updateSlotLabel})`);
+                        // Update sync state with new modifiedAt. Store the *expanded*
+                        // content hash so future fragment-only edits are detected. The
+                        // adopt branch seeds the entity record before calling this, so
+                        // the entry exists for both call sites.
+                        if (syncState?.entities?.workflows?.[key] && latestModifiedAt) {
+                            syncState.entities.workflows[key].modifiedAt = latestModifiedAt;
+                            syncState.entities.workflows[key].contentHash = computeExpandedContentHash(tomlData);
+                        }
+                        // `applyWorkflowBody` already fetched the full workflow; reuse it
+                        // for the config name→ID mappings (the PATCH response omits configs).
+                        if (fullWorkflow?.configs) {
+                            for (const config of fullWorkflow.configs) {
+                                workflowConfigNameToId.set(`${key}#${config.configName}`, config.configId);
+                            }
+                        }
+                    };
                     if (existingId) {
                         // Update existing workflow
                         changes.push({ type: "workflow", action: "update", key });
@@ -2759,95 +3045,10 @@ Directory Structure:
                                 ? undefined
                                 : syncState?.entities?.workflows?.[key]?.modifiedAt;
                             try {
-                                // Update workflow metadata and schemas.
-                                //
-                                // Sync-callable ordering (#807, codex review): the metadata
-                                // PATCH must NOT carry `syncCallable: true` here. The server
-                                // re-validates `syncCallable: true` against the workflow's
-                                // CURRENTLY-active server steps (`loadCurrentActiveSteps`),
-                                // not the steps being pushed in the same sync. So when a
-                                // single TOML edit both enables `syncCallable` and replaces
-                                // sync-incompatible active steps with compatible ones, a
-                                // combined metadata-first PATCH would be rejected against the
-                                // stale steps. Defer `syncCallable` to a second PATCH issued
-                                // AFTER the config/step update lands, so it validates against
-                                // the new (compatible) active steps. `requiresClientApply`
-                                // has no step-dependent validation, so it stays in the first
-                                // PATCH unchanged.
-                                const updated = await client.updateWorkflow(resolvedAppId, existingId, {
-                                    name: workflow.name,
-                                    description: workflow.description,
-                                    status: workflow.status,
-                                    accessRule: workflow.accessRule !== undefined ? (workflow.accessRule || null) : undefined,
-                                    // #1081 — workflow principal mode. Absent key → undefined
-                                    // (server leaves it untouched); explicit value/empty is
-                                    // forwarded so it round-trips.
-                                    runAs: workflow.runAs !== undefined ? (workflow.runAs || null) : undefined,
-                                    perUserMaxRunning: workflow.perUserMaxRunning,
-                                    perUserMaxQueued: workflow.perUserMaxQueued,
-                                    dequeueOrder: workflow.dequeueOrder,
-                                    // Sync-callable flags (#807): pass through as-is. An absent
-                                    // TOML key is `undefined` (dropped by JSON.stringify, so the
-                                    // server's hasOwnProperty guard leaves the value untouched);
-                                    // an explicit `false` is preserved as a meaningful value.
-                                    requiresClientApply: workflow.requiresClientApply,
-                                    inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
-                                    outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : null,
-                                }, expectedModifiedAt);
-                                // Track the latest workflow `modifiedAt` for the sync-state
-                                // write below. The first PATCH bumps it; the `syncCallable`
-                                // PATCH (if any) bumps it again. The config/step update does
-                                // NOT touch the workflow definition's `modifiedAt`.
-                                let latestModifiedAt = updated?.workflow?.modifiedAt;
-                                // Update active configuration steps (or draft for legacy).
-                                // Issue #687: name the slot we touched so the dev-loop
-                                // user can confirm before previewing.
-                                let updateSlotLabel = "active config";
-                                if (existingActiveConfigId) {
-                                    await client.updateWorkflowConfig(resolvedAppId, existingId, existingActiveConfigId, {
-                                        steps,
-                                    });
-                                }
-                                else {
-                                    // Fallback to draft update for legacy workflows
-                                    await client.updateWorkflowDraft(resolvedAppId, existingId, {
-                                        steps,
-                                        inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
-                                    });
-                                    updateSlotLabel = "draft (legacy)";
-                                }
-                                // Second PATCH: apply `syncCallable` now that the new steps
-                                // are active (#807). Only sent when the TOML actually carries
-                                // the key — an absent key stays `undefined` and we skip the
-                                // call entirely, preserving the no-clobber discipline. Chain
-                                // `expectedModifiedAt` off the first PATCH's returned value so
-                                // optimistic concurrency stays intact (the step update above
-                                // doesn't change the workflow definition's `modifiedAt`).
-                                if (workflow.syncCallable !== undefined) {
-                                    const syncCallableUpdated = await client.updateWorkflow(resolvedAppId, existingId, { syncCallable: workflow.syncCallable }, 
-                                    // Mirror the first PATCH's concurrency posture: `--force`
-                                    // skips the check (undefined), otherwise reuse the fresh
-                                    // `modifiedAt` from the first PATCH.
-                                    options.force ? undefined : latestModifiedAt);
-                                    if (syncCallableUpdated?.workflow?.modifiedAt) {
-                                        latestModifiedAt = syncCallableUpdated.workflow.modifiedAt;
-                                    }
-                                }
-                                info(`  Updated workflow: ${key} (${updateSlotLabel})`);
-                                // Update sync state with new modifiedAt. Store the *expanded*
-                                // content hash so future fragment-only edits are detected.
-                                if (syncState?.entities?.workflows?.[key] && latestModifiedAt) {
-                                    syncState.entities.workflows[key].modifiedAt = latestModifiedAt;
-                                    syncState.entities.workflows[key].contentHash = computeExpandedContentHash(tomlData);
-                                }
-                                // Fetch full workflow to get config name→ID mappings
-                                // (updateWorkflow response doesn't include configs)
-                                const fullWorkflow = await client.getWorkflow(resolvedAppId, existingId);
-                                if (fullWorkflow?.configs) {
-                                    for (const config of fullWorkflow.configs) {
-                                        workflowConfigNameToId.set(`${key}#${config.configName}`, config.configId);
-                                    }
-                                }
+                                await applyWorkflowUpdate(existingId, {
+                                    expectedModifiedAt,
+                                    activeConfigId: existingActiveConfigId,
+                                });
                             }
                             catch (err) {
                                 if (err instanceof ConflictError) {
@@ -2888,6 +3089,9 @@ Directory Structure:
                                     // syncCallable=false); an explicit value is honored.
                                     requiresClientApply: workflow.requiresClientApply,
                                     syncCallable: workflow.syncCallable,
+                                    // #1304 (P-C): declared-access manifest (absent → undefined,
+                                    // server default null).
+                                    metadataManifest: workflow.metadataManifest ?? undefined,
                                 });
                                 info(`  Created workflow: ${key}`);
                                 // Add new entity to sync state (including activeConfigId)
@@ -2936,7 +3140,116 @@ Directory Structure:
                                 }
                             }
                             catch (err) {
-                                throw wrapEntityError(err, "create", "workflow", key);
+                                // Issue #1174: idempotent create — adopt-by-key on conflict.
+                                // A workflow can exist on the server but be absent from local
+                                // sync state — e.g. created out-of-band via the admin API
+                                // (#971), or orphaned by a prior push that aborted before
+                                // recording it. On retry this CREATE path hits the
+                                // `workflowKeyPerApp` unique constraint and the server
+                                // returns "workflowKey already exists" (HTTP 400; cron uses
+                                // 409). Rather than abort the whole push, look up the
+                                // existing workflow by key (the list endpoint is app-scoped,
+                                // so every item is owned by this app), verify the SAME key,
+                                // adopt its id into sync state, and re-issue as an UPDATE so
+                                // the push converges. Mirrors the cron-trigger recovery at
+                                // ~sync.ts:2627. Unexpected errors still surface via
+                                // `wrapEntityError`, matching the db-type precedent.
+                                const msg = String(err?.message || err);
+                                const isConflict = err?.statusCode === 409 || msg.includes("already exists");
+                                if (!isConflict) {
+                                    throw wrapEntityError(err, "create", "workflow", key);
+                                }
+                                info(`  Workflow already exists on server, adopting by key: ${key}`);
+                                let adoptedId;
+                                try {
+                                    // Use fetchAll — listWorkflows is paginated, so a single
+                                    // page could miss the by-key match on a large app.
+                                    const items = await fetchAll((p) => client.listWorkflows(resolvedAppId, p));
+                                    // Verify same key + app ownership: the list endpoint only
+                                    // returns workflows for `resolvedAppId`, so a workflowKey
+                                    // match is also an ownership match. Never overwrite an
+                                    // unrelated resource — require exact key equality.
+                                    const existing = (items || []).find((w) => w?.workflowKey === key);
+                                    if (existing?.workflowId) {
+                                        adoptedId = existing.workflowId;
+                                    }
+                                }
+                                catch (lookupErr) {
+                                    throw wrapEntityError(new Error(`workflow "${key}" already exists but could not be adopted (lookup failed: ${String(lookupErr?.message || lookupErr)})`), "create", "workflow", key);
+                                }
+                                if (!adoptedId) {
+                                    // "already exists" but no matching key found on the server —
+                                    // surface the original error rather than silently
+                                    // overwriting an unrelated workflow.
+                                    throw wrapEntityError(err, "create", "workflow", key);
+                                }
+                                // Out-of-manifest adopt: warn (info-level), matching the cron
+                                // adopt line, and seed the sync-state entity record so the
+                                // shared update body can write modifiedAt/contentHash into it.
+                                if (syncState) {
+                                    if (!syncState.entities.workflows) {
+                                        syncState.entities.workflows = {};
+                                    }
+                                    if (!syncState.entities.workflows[key]) {
+                                        syncState.entities.workflows[key] = {
+                                            id: adoptedId,
+                                        };
+                                    }
+                                    else {
+                                        syncState.entities.workflows[key].id = adoptedId;
+                                    }
+                                }
+                                // Seed the real activeConfigId from the server before the
+                                // shared update body runs. Sync state has none for an
+                                // out-of-manifest workflow, so without this the shared body
+                                // would wrongly fall back to `updateWorkflowDraft`.
+                                let adoptedActiveConfigId;
+                                try {
+                                    const fullWorkflow = await client.getWorkflow(resolvedAppId, adoptedId);
+                                    adoptedActiveConfigId =
+                                        fullWorkflow?.workflow?.activeConfigId;
+                                }
+                                catch (getErr) {
+                                    throw wrapEntityError(new Error(`workflow "${key}" was adopted but could not be loaded (getWorkflow failed: ${String(getErr?.message || getErr)})`), "update", "workflow", key);
+                                }
+                                // Persist the fetched activeConfigId into the seeded
+                                // sync-state record so it round-trips identically to the
+                                // CREATE path (~sync.ts:3387). Without this the *next*
+                                // content-changing push reads `existingActiveConfigId ===
+                                // undefined` (sync.ts:3187) and wrongly falls back to the
+                                // legacy `updateWorkflowDraft` instead of
+                                // `updateWorkflowConfig` — a persisted-state divergence from
+                                // a normally-created workflow.
+                                if (syncState?.entities?.workflows?.[key] &&
+                                    adoptedActiveConfigId) {
+                                    syncState.entities.workflows[key].activeConfigId =
+                                        adoptedActiveConfigId;
+                                }
+                                // Switch to UPDATE on the adopted workflow. First adopt has no
+                                // stored modifiedAt → omit expectedModifiedAt (force the
+                                // PATCH), matching the cron adopt + the --force path. An
+                                // unexpected ConflictError here is still adoptable resilience
+                                // scope, so collect it; any other error surfaces.
+                                try {
+                                    await applyWorkflowUpdate(adoptedId, {
+                                        expectedModifiedAt: undefined,
+                                        activeConfigId: adoptedActiveConfigId,
+                                    });
+                                    info(`  Adopted + updated workflow: ${key}`);
+                                }
+                                catch (updErr) {
+                                    if (updErr instanceof ConflictError) {
+                                        conflicts.push({
+                                            type: "workflow",
+                                            key,
+                                            serverModifiedAt: updErr.serverModifiedAt,
+                                            localModifiedAt: "unknown",
+                                        });
+                                    }
+                                    else {
+                                        throw wrapEntityError(updErr, "update", "workflow", key);
+                                    }
+                                }
                             }
                         }
                     }
@@ -3044,6 +3357,14 @@ Directory Structure:
                         if ("timestamps" in typeConfig) {
                             u.timestamps = typeConfig.timestamps || null;
                         }
+                        // Issue #1304 (P-C): declared-access manifest. `parseDatabaseTypeToml`
+                        // only sets `metadataManifest` when the TOML declares a `[metadata]`
+                        // / `secrets` block, so this forwards a set/update; clearing a
+                        // manifest by removing the block is a follow-on (mirrors the
+                        // schema-deletion tracking).
+                        if ("metadataManifest" in typeConfig) {
+                            u.metadataManifest = typeConfig.metadataManifest || null;
+                        }
                         const localHasSchema = typeof typeConfig.schema === "string" &&
                             typeConfig.schema.trim().length > 0;
                         if (localHasSchema) {
@@ -3413,7 +3734,8 @@ Directory Structure:
                                 "defaultAccess" in typeConfig ||
                                 "autoPopulatedFields" in typeConfig ||
                                 "timestamps" in typeConfig ||
-                                "schema" in typeConfig;
+                                "schema" in typeConfig ||
+                                "metadataManifest" in typeConfig;
                             if (wouldUpdate) {
                                 changes.push({ type: "database-type", action: "update", key: dbType });
                             }
@@ -3446,6 +3768,9 @@ Directory Structure:
                             // validating against the intended shape.
                             if (typeConfig.schema)
                                 createData.schema = typeConfig.schema;
+                            // Issue #1304 (P-C): declared-access manifest.
+                            if (typeConfig.metadataManifest)
+                                createData.metadataManifest = typeConfig.metadataManifest;
                             try {
                                 const created = await client.createDatabaseTypeConfig(resolvedAppId, createData);
                                 info(`  Created database type: ${dbType}`);
@@ -3979,6 +4304,7 @@ Directory Structure:
                             try {
                                 const updated = await client.updateCollectionTypeConfig(resolvedAppId, collectionType, {
                                     ruleSetId: configData.ruleSetId ?? null,
+                                    metadataManifest: configData.metadataManifest ?? null,
                                 }, expectedModifiedAt);
                                 info(`  Updated collection type config: ${collectionType}`);
                                 if (syncState?.entities?.collectionTypeConfigs?.[collectionType] && updated?.modifiedAt) {
@@ -4009,6 +4335,9 @@ Directory Structure:
                                 const created = await client.createCollectionTypeConfig(resolvedAppId, {
                                     collectionType,
                                     ruleSetId: configData.ruleSetId || undefined,
+                                    ...(configData.metadataManifest
+                                        ? { metadataManifest: configData.metadataManifest }
+                                        : {}),
                                 });
                                 info(`  Created collection type config: ${collectionType}`);
                                 if (syncState) {
@@ -4028,6 +4357,66 @@ Directory Structure:
                     }
                 }
             }
+            // Process metadata category configs (issue #1304, P-B). Idempotent
+            // upsert via the path-addressed PUT route — no create/update split.
+            const metadataCategoryConfigsDir = join(configDir, "metadata-category-configs");
+            if (existsSync(metadataCategoryConfigsDir)) {
+                const files = readdirSync(metadataCategoryConfigsDir).filter((f) => f.endsWith(".toml"));
+                for (const file of files) {
+                    const filePath = join(metadataCategoryConfigsDir, file);
+                    const tomlData = parseTomlFile(filePath);
+                    const configData = parseMetadataCategoryToml(tomlData);
+                    // Fall back to the filename (`resourceType.category.toml`) if the
+                    // section omits the identity fields.
+                    if (!configData.resourceType || !configData.category) {
+                        const base = basename(file, ".toml");
+                        const dot = base.indexOf(".");
+                        if (dot > 0) {
+                            configData.resourceType = configData.resourceType || base.slice(0, dot);
+                            configData.category = configData.category || base.slice(dot + 1);
+                        }
+                    }
+                    const validationError = validateMetadataCategoryConfig(configData);
+                    if (validationError) {
+                        throw new Error(`Invalid metadata category config in ${file}: ${validationError}`);
+                    }
+                    const entityKey = `${configData.resourceType}#${configData.category}`;
+                    const existingEntry = syncState?.entities?.metadataCategoryConfigs?.[entityKey];
+                    // Skip if the file hasn't changed since last sync.
+                    if (!options.force && existingEntry && !shouldPushFile(filePath, existingEntry.contentHash)) {
+                        skippedCount++;
+                        continue;
+                    }
+                    changes.push({
+                        type: "metadata-category-config",
+                        action: existingEntry ? "update" : "create",
+                        key: entityKey,
+                    });
+                    if (!options.dryRun) {
+                        try {
+                            const saved = await client.upsertMetadataCategoryConfig(resolvedAppId, configData.resourceType, configData.category, {
+                                schema: configData.schema,
+                                readRule: configData.readRule,
+                                writeRule: configData.writeRule,
+                                description: configData.description,
+                            });
+                            info(`  Upserted metadata category config: ${entityKey}`);
+                            if (syncState) {
+                                if (!syncState.entities.metadataCategoryConfigs) {
+                                    syncState.entities.metadataCategoryConfigs = {};
+                                }
+                                syncState.entities.metadataCategoryConfigs[entityKey] = {
+                                    modifiedAt: saved?.modifiedAt || new Date().toISOString(),
+                                    contentHash: computeFileHash(filePath),
+                                };
+                            }
+                        }
+                        catch (err) {
+                            throw wrapEntityError(err, existingEntry ? "update" : "create", "metadata category config", entityKey);
+                        }
+                    }
+                }
+            }
             // Process email templates
             const emailTemplatesDir = join(configDir, "email-templates");
             if (existsSync(emailTemplatesDir)) {
@@ -4064,11 +4453,13 @@ Directory Structure:
                     }
                 }
             }
-            // Push test cases for prompts and workflows
+            // Push test cases for prompts, workflows, and scripts
+            const scriptConfigNameToId = new Map(); // "scriptName#configName" → configId
             const pushMaps = {
                 promptKeyToId,
                 promptConfigNameToId,
                 workflowConfigNameToId,
+                scriptConfigNameToId,
             };
             const promptsDir2 = join(configDir, "prompts");
             if (existsSync(promptsDir2)) {
@@ -4092,6 +4483,33 @@ Directory Structure:
                     }
                 }
             }
+            // Push test cases for scripts (transforms). Each script's tests live at
+            // transforms/<name>.tests/; the scriptId was recorded in
+            // entities.scripts[name].id when the script body was pushed above.
+            const transformsDir2 = join(configDir, "transforms");
+            if (existsSync(transformsDir2)) {
+                for (const file of readdirSync(transformsDir2).filter((f) => f.endsWith(".rhai"))) {
+                    const scriptName = basename(file, ".rhai");
+                    const blockId = syncState?.entities?.scripts?.[scriptName]?.id;
+                    if (!blockId)
+                        continue;
+                    const scriptTestsDir = join(transformsDir2, `${scriptName}.tests`);
+                    if (!existsSync(scriptTestsDir))
+                        continue;
+                    // Populate scriptConfigNameToId for this script so a test case that
+                    // pins a config by name resolves to a live configId.
+                    try {
+                        const { items: scriptConfigs } = await client.listScriptConfigs(resolvedAppId, blockId);
+                        for (const config of scriptConfigs) {
+                            scriptConfigNameToId.set(`${scriptName}#${config.configName}`, config.configId);
+                        }
+                    }
+                    catch {
+                        // Non-fatal — unpinned (active-version) test cases still push.
+                    }
+                    skippedCount += await pushTestCasesForBlock(client, resolvedAppId, "script", blockId, scriptName, configDir, syncState, options.dryRun, changes, pushMaps, { force: options.force });
+                }
+            }
             divider();
             // Issue #813: a gate failure surfaced by the validate-first pass (which
             // also runs in dry-run mode via the server's dry-run gate endpoints).
@@ -4180,13 +4598,9 @@ Directory Structure:
                     // Don't mask the original error
                 }
             }
-            error(err.message);
-            // Print structured server-side validation details (issue #684).
-            if (err instanceof ApiError && Array.isArray(err.details) && err.details.length > 0) {
-                for (const detail of err.details) {
-                    console.error(`    - ${typeof detail === "string" ? detail : JSON.stringify(detail)}`);
-                }
-            }
+            // Print message + structured server-side validation details
+            // (issue #684; now via the shared #1173 helper).
+            printApiError(err);
             process.exit(1);
         }
     });
@@ -4309,6 +4723,30 @@ Directory Structure:
                     localEmailTemplates.add(emailType);
                 }
             }
+            // Transforms (Rhai scripts) — issue #1196. Before this, `sync diff`
+            // ignored scripts entirely, so a body that drifted between the local
+            // `.rhai` and the server's active config silently read as Synced. We
+            // list the server scripts (header only) and read the local file
+            // contents so the comparison below can hash both sides.
+            let scriptItemsDiff = [];
+            try {
+                const scriptsResult = await client.listScripts(resolvedAppId);
+                scriptItemsDiff = scriptsResult.items || [];
+            }
+            catch {
+                // Older server without the scripts route — treat as no scripts.
+            }
+            const remoteScripts = new Map(scriptItemsDiff
+                .filter((s) => s?.name)
+                .map((s) => [s.name, s]));
+            const localScripts = new Map();
+            const transformsDirPath = join(configDir, "transforms");
+            if (existsSync(transformsDirPath)) {
+                for (const file of readdirSync(transformsDirPath).filter((f) => f.endsWith(".rhai"))) {
+                    const name = basename(file, ".rhai");
+                    localScripts.set(name, readFileSync(join(transformsDirPath, file), "utf-8"));
+                }
+            }
             // Compare
             const differences = [];
             // Integrations
@@ -4464,6 +4902,55 @@ Directory Structure:
                     differences.push({ type: "email-template", key, status: "remote only" });
                 }
             }
+            // Transforms (Rhai scripts) — issue #1196. Content-aware, mirroring
+            // the workflow block: for scripts present on both sides we fetch the
+            // server's active-config body (via `getScript`, the same call pull
+            // uses) and compare it to the local `.rhai` contents. A difference is
+            // reported as `modified`, framed as a preview of `sync pull`. A
+            // per-script fetch failure degrades to key-only (Synced, not compared)
+            // rather than aborting the whole diff.
+            for (const [name, localBody] of localScripts) {
+                const remote = remoteScripts.get(name);
+                if (!remote) {
+                    differences.push({ type: "transform", key: name, status: "local only" });
+                    continue;
+                }
+                let status = "exists";
+                let hint;
+                try {
+                    if (!remote.activeConfigId) {
+                        // No active config server-side — nothing to compare against.
+                        status = "exists";
+                        hint = "content not compared (no active config)";
+                    }
+                    else {
+                        const full = await client.getScript(resolvedAppId, remote.scriptId);
+                        const configs = Array.isArray(full?.configs) ? full.configs : [];
+                        const activeConfigId = full?.activeConfigId ?? remote.activeConfigId;
+                        const activeConfig = configs.find((c) => c.configId === activeConfigId) ||
+                            configs.find((c) => c.status === "active");
+                        if (!activeConfig || typeof activeConfig.body !== "string") {
+                            status = "exists";
+                            hint = "content not compared (no active config body)";
+                        }
+                        else if (activeConfig.body !== localBody) {
+                            status = "modified";
+                            hint = "run `sync pull` to rewrite the local .rhai to match running state";
+                        }
+                    }
+                }
+                catch {
+                    // Per-script fetch failure must not abort the whole diff.
+                    status = "exists";
+                    hint = "content not compared (fetch failed)";
+                }
+                differences.push({ type: "transform", key: name, status, hint });
+            }
+            for (const name of remoteScripts.keys()) {
+                if (!localScripts.has(name)) {
+                    differences.push({ type: "transform", key: name, status: "remote only" });
+                }
+            }
             // Compare test cases for synced prompts and workflows
             const testCaseDiffs = [];
             // Helper to compare test cases for a block
@@ -4699,6 +5186,63 @@ Directory Structure:
             success(`Rewrote ${migratedCount} TOML file(s) to native form.`);
         }
     });
+    // migrate-v2 — convert a legacy sync directory into the unified block
+    // layout `blocks/<type>/<key>/block.toml` (issue #1183, Phase 3). Purely
+    // local: it reads already-pulled legacy files and writes the v2 tree. The
+    // legacy files are left in place (legacy stays the default until v2 is
+    // proven), so re-running push/pull is unaffected.
+    sync
+        .command("migrate-v2")
+        .description("Convert legacy per-type sync files (prompts/, integrations/, workflows/, transforms/) into the v2 blocks/<type>/<key>/block.toml layout")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
+        .option("--dry-run", "Show what would change without writing files")
+        .option("--force", "Overwrite existing block.toml files instead of skipping them")
+        .action(async (appId, options) => {
+        // Resolve appId so we land in the per-env sync dir even when the user
+        // didn't pass `--dir`. The app ID itself isn't used for any API calls —
+        // migrate-v2 is a purely local rewrite (like migrate-toml).
+        const resolvedAppId = resolveAppId(appId, options);
+        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        if (isAutoResolvedSyncDir(options.dir)) {
+            info(`Using per-environment sync directory: ${configDir}`);
+        }
+        if (!existsSync(configDir)) {
+            error(`Config directory not found: ${configDir}`);
+            process.exit(1);
+        }
+        const before = detectLayout(configDir);
+        if (!before.legacy) {
+            info("No legacy block files found (prompts/, integrations/, workflows/, transforms/); nothing to migrate.");
+            return;
+        }
+        const result = migrateLegacyToV2(configDir, {
+            dryRun: options.dryRun,
+            force: options.force,
+        });
+        for (const b of result.blocks) {
+            const suffix = b.testsCopied > 0 ? ` (+${b.testsCopied} test case(s))` : "";
+            if (options.dryRun) {
+                info(`Would write blocks/${b.type === "script" ? "scripts" : b.type + "s"}/${b.key}/block.toml${suffix}`);
+            }
+            else {
+                info(`Wrote blocks/${b.type === "script" ? "scripts" : b.type + "s"}/${b.key}/block.toml${suffix}`);
+            }
+        }
+        for (const s of result.skipped) {
+            warn(`Skipped ${s.type}/${s.key}: ${s.reason}`);
+        }
+        divider();
+        keyValue("Migrated", result.blocks.length);
+        keyValue("Skipped", result.skipped.length);
+        if (options.dryRun) {
+            info("Dry-run only — no files were modified.");
+        }
+        else if (result.blocks.length > 0) {
+            success(`Converted ${result.blocks.length} block(s) to the v2 layout. Legacy files were left in place.`);
+        }
+    });
     // Revert — restore a pre-pull snapshot (issue #578, Phase 1).
     sync
         .command("revert")