primitive-admin 1.1.0-alpha.78 → 1.1.0-alpha.79

package/dist/src/commands/sync.js

@@ -5,12 +5,14 @@ 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 { canEmitNative } from "../lib/toml-native-form.js";
+// #1446's `type: "json"` emission rule, shared with `serializeFunction` since
+// #3317 — see `config-json-field.ts`.
+import { serializeJsonField } from "../lib/config-json-field.js";
 import { parseMetadataCategoryToml, validateMetadataCategoryConfig, serializeMetadataCategoryConfig, parseDeclaredAccessManifestToml, validateDeclaredAccessManifest, serializeDeclaredAccessManifest, } from "../lib/toml-metadata-config.js";
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { isPlatformOwnedWorkflow, isPlatformOwnedWorkflowKey, } from "../lib/platform-owned.js";
-import { getServerUrl, resolveAppId } from "../lib/config.js";
-import { assertTreeApp } from "../lib/app-match-guard.js";
-import { resolveSyncDir, resolveSnapshotsRoot, assertSyncStateLayout, syncStatePath, SYNC_STATE_FILENAME, isAutoResolvedSyncDir, checkLegacySyncMigration, checkLegacyDatabaseTypesDir, } from "../lib/sync-paths.js";
+import { getCurrentAppId, getServerUrl } from "../lib/config.js";
+import { resolveSyncDir, resolveSnapshotsRoot, assertSyncStateLayout, syncStatePath, SYNC_STATE_FILENAME, checkLegacyDatabaseTypesDir, } from "../lib/sync-paths.js";
 import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, collectWorkflowTomlNotes, formatWorkflowTomlErrors, validateWorkflowExpressionsToml, validateWorkflowExpressionsRawToml, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
@@ -35,7 +37,7 @@ import { buildPayloadFromToml, projectEntityToPayload, projectRecordToToml, toml
 import { CONFIG_SURFACES, isEmptyForEmit, } from "../lib/generated-config-surfaces.js";
 // #3179 — the function's two halves: the header payloads and the envelope
 // `config push` sends, and the bytes `config pull` writes back.
-import { applyFunctionPull, buildFunctionConfigPush, buildFunctionCreatePayload, buildFunctionUpdatePayload, functionDiffEntity, planFunctionPull, serializeFunction, } from "../lib/function-sync.js";
+import { applyFunctionPull, buildFunctionConfigPush, buildFunctionCreatePayload, buildFunctionUpdatePayload, functionDiffEntity, functionTomlPreflightErrors, planFunctionPull, serializeFunction, } from "../lib/function-sync.js";
 import { FunctionBuildError } from "../lib/function-bundle.js";
 // #3182 — the local half of capability validation. The grammar is the vendored
 // module the server also imports; this is where an author's own file is read.
@@ -43,6 +45,12 @@ import { configObjectKeysFromTree, functionGrantErrors, mergeKnownGrantTargets,
 // #3182 — the typed handle's generated declarations and the compiler wiring
 // that makes an editor load them.
 import { functionTypeWiringProblems, staleFunctionTypeArtifacts, writeFunctionTypeArtifacts, } from "../lib/function-db-types.js";
+// #3281 — the functions declaration and the per-key invokers ride the same
+// plan; a malformed schema is their one refusal, named by file.
+import { FunctionSchemaCodegenError } from "../lib/function-schema-codegen.js";
+// #3331 — and the compiler is actually asked: a push holds the code it ships
+// to the declarations it just generated.
+import { createFunctionTypechecker, } from "../lib/function-typecheck.js";
 import { detectLayout, migrateLegacyToV2 } from "../lib/block-layout.js";
 import { ABSENT_FROM_EXPORT, LOCAL_ONLY_ABSENT, LOCAL_ONLY_NEW, PUSH_PRUNE_SPECS, REMOTE_ONLY_UNMANAGED, REMOTE_ONLY_WILL_DELETE, SYNC_RESOURCE_TYPES, VALIDATION_ERROR, applyPrune, attachmentWritePath, attemptFetch, classifyLocalOnly, classifyPruneDeleteFailure, classifyRemoteOnly, collectPushPruneCandidates, decidePushPruneCandidate, formatPrunePlan, hasUncommittedChanges, isSafeAttachmentFilename, isSafeSyncFilename, planPrune, preserveUnwrittenEntries, removePrunedSidecar, ruleSetFileKey, } from "../lib/sync-resource-types.js";
 import { normalizeTestCaseKey, testCaseKeyError, } from "../lib/test-case-keys.js";
@@ -1946,50 +1954,6 @@ export function buildPromptConfigPayload(tomlConfig, { mode = "update" } = {}) {
         },
     });
 }
-/**
- * Emit a `type: "json"` field (a JSON Schema, a provider-options blob) as TOML.
- *
- * Issue #1446: pull used to `JSON.stringify` schema fields into a single
- * escaped-JSON line — unreadable and undiffable. We now emit the parsed value
- * as a native table whenever it round-trips faithfully
- * (`canEmitNative === null`), falling back to the JSON string only for the
- * values TOML silently drops (`null` / `undefined` anywhere inside). The empty
- * object `{}` is a real, distinct value (for a schema: "accepts anything") and
- * emits as an empty table, so it survives a pull → push cycle instead of being
- * cleared server-side.
- *
- * Returns `undefined` for an absent value (the key is then omitted). The
- * sponsor-approved decision is to always move to native aggressively — no
- * form preservation — so this does not consult the existing file's form.
- *
- * `subject` names the object in the fallback warning, e.g. `Workflow 'greet'`.
- */
-function serializeJsonField(value, fieldName, subject, log) {
-    if (value === undefined || value === null)
-        return undefined;
-    // JSON fields arrive from the server GET parsed; defensively accept a JSON
-    // string too (e.g. an inline-authored file re-serialized here).
-    let obj = value;
-    if (typeof value === "string") {
-        try {
-            obj = JSON.parse(value);
-        }
-        catch {
-            // Not valid JSON — keep the original string as the emitted value.
-            return value;
-        }
-    }
-    if (obj && typeof obj === "object") {
-        const reason = canEmitNative(obj);
-        if (reason) {
-            log(`${subject}: cannot emit \`${fieldName}\` as native TOML (${reason}); using JSON string.`);
-            return JSON.stringify(obj);
-        }
-        return obj;
-    }
-    // A non-object value (unexpected) — preserve it as a JSON string.
-    return JSON.stringify(obj);
-}
 /** The `[workflow]` case of `serializeJsonField` (#1446, message unchanged). */
 function serializeWorkflowSchemaField(value, fieldName, workflowKey, log) {
     return serializeJsonField(value, fieldName, `Workflow '${workflowKey}'`, log);
@@ -2168,6 +2132,11 @@ function localConfigRowKey(label, tomlData, file) {
             return stated("prompt", "key");
         case "workflow":
             return stated("workflow", "key");
+        // #3320 — the declared key, like the function preflight collector, the
+        // apply loop and `--only`. A renamed file is one object, so both
+        // collectors' messages land on the one comparison row.
+        case "function":
+            return stated("function", "key");
         case "email-template":
             return stated("template", "emailType");
         case "database-type-config":
@@ -2251,6 +2220,75 @@ export function collectConfigFileValidationErrors(configDir) {
     }
     return found;
 }
+/**
+ * Every `functions/<key>.toml` whose file-decidable errors `config push` would
+ * refuse (#3320).
+ *
+ * A second collector rather than a branch inside
+ * `collectConfigFileValidationErrors`, and deliberately so: push calls that one
+ * UNBOUNDED over the whole tree, which is right for the checks it runs (a
+ * mistyped key anywhere means the tree is not pushable) and wrong for these — a
+ * `config push --only webhook/<key>` must not be blocked by a broken function
+ * the operator did not select (#2645). The push path therefore runs these
+ * inside its own `selectFiles`-bounded function loop, and `config diff`, which
+ * compares the whole tree by construction, runs them from here.
+ *
+ * A file that does not parse is skipped: the per-type loop that reads it names
+ * the parse error itself, and reporting it twice helps nobody.
+ */
+export function collectFunctionTomlValidationErrors(configDir) {
+    const found = [];
+    const functionsDir = join(configDir, "functions");
+    if (!existsSync(functionsDir))
+        return found;
+    for (const file of readdirSync(functionsDir).filter((f) => f.endsWith(".toml"))) {
+        const filePath = join(functionsDir, file);
+        let tomlData;
+        try {
+            tomlData = parseTomlFile(filePath);
+        }
+        catch {
+            continue;
+        }
+        // The DECLARED key, like the apply loop and `--only` selection: a file
+        // whose name and `[function].key` differ is one object, not two.
+        const key = tomlData?.function?.key || basename(file, ".toml");
+        const messages = functionTomlPreflightErrors({
+            filePath,
+            functionKey: key,
+            tomlData,
+        });
+        if (messages.length === 0)
+            continue;
+        found.push({ type: "function", key, filePath, messages });
+    }
+    return found;
+}
+/**
+ * The collectors' rows, one per diff row (#2880 symmetry, #3320).
+ *
+ * Two collectors reach the same function file — the definition-driven one
+ * every per-entity type runs, and the function preflight — and a file can
+ * break both at once (a mistyped `entrty`, which then leaves no `entry`).
+ * Push reports every message from both, so an overlay that let one row's
+ * messages REPLACE the other's would drop a diagnostic push prints, which is
+ * exactly the asymmetry #2880 forbids. Merging by row keeps the two commands
+ * reading identically.
+ */
+export function mergeConfigFileValidationErrors(collected) {
+    const byRow = new Map();
+    for (const rejected of collected) {
+        const rowId = `${rejected.type}${rejected.key}`;
+        const merged = byRow.get(rowId);
+        if (!merged) {
+            byRow.set(rowId, { ...rejected, messages: [...rejected.messages] });
+            continue;
+        }
+        // Collection order is the message order, the same order push prints.
+        merged.messages.push(...rejected.messages);
+    }
+    return [...byRow.values()];
+}
 /**
  * Every `<key>.tests/*.toml` sidecar under a config directory.
  *
@@ -3335,6 +3373,10 @@ export function classifyPushChange(input) {
     const { localHash, remoteHash, baselineHash, legacy } = input;
     if (localHash === remoteHash)
         return "unchanged";
+    // Ahead of both the baseline and the legacy inference, which are ways of
+    // GUESSING what this states outright.
+    if (input.serverUnchangedSinceSync === true)
+        return "local-edited";
     if (baselineHash) {
         if (remoteHash === baselineHash)
             return "local-edited";
@@ -3499,7 +3541,7 @@ const CONFIG_DIFF_SPECS = {
         describe: (entity) => `email template "${entity?.emailType}"`,
     },
     // #3179 — server functions. The compared entity spans the header AND the
-    // three keys the immutable version carries (`entry`, `durable`, `limits`),
+    // keys the immutable version carries (`entry`, `mode`, `limits`, …),
     // because an author writes one file and a version is never authored
     // separately: comparing only the header would report a changed entry point as
     // Synced. The SOURCE bytes are a second axis the table cannot express — they
@@ -3509,13 +3551,22 @@ const CONFIG_DIFF_SPECS = {
         table: SERVER_FUNCTION_TABLE,
         parse: (doc) => functionDiffEntity(doc),
         // `extra` is the ACTIVE config version, which is where the remote side's
-        // entry/durable/limits live; the header row does not carry them.
+        // entry/mode/limits live; the header row does not carry them.
         serialize: (record, _maps, extra) => serializeFunction(record, extra),
         // The version-carried keys are not fields of the header table, so they
         // travel as extras — present on both sides or absent on both.
         extras: (entity) => ({
+            // #3317 — `inputSchema` / `outputSchema` compared as the values they
+            // encode, the rule prompts have had since #2748. A schema reaches the
+            // two sides in either spelling (a native `[function.inputSchema]` table,
+            // or the JSON string the server stores and the fallback pull writes for
+            // a schema TOML cannot hold), and neither spelling is a difference.
+            ...jsonFieldsForDiff(SERVER_FUNCTION_TABLE, entity),
             entry: entity.entry ?? null,
-            durable: entity.durable === true,
+            // #3281 — the RESOLVED mode (`functionDiffEntity` reads both spellings),
+            // so a legacy `durable = true` file and a server serializing `mode`
+            // compare equal.
+            mode: entity.mode ?? null,
             limits: entity.limits ?? null,
             // #3182 — the grants are version-carried too, and a widened grant set is
             // exactly the change a reviewer must not read as Synced. Sorted because
@@ -3987,17 +4038,32 @@ export function decidePushForConfig(input) {
             fields,
         };
     }
+    // The recorded server timestamp still being the live one. It is the legacy
+    // path's inference signal, and — where the row's timestamp covers the whole
+    // projection — #3317's outright statement that the server did not move.
+    const liveModifiedAtMatchesStored = entry?.modifiedAt !== undefined &&
+        live.modifiedAt !== undefined &&
+        entry.modifiedAt === live.modifiedAt;
+    // The recorded version pointer still being the live one — or no pointer
+    // recorded, which is no claim. A pointer that moved is a server change by
+    // definition, whatever the two timestamps say (#3317: the baseline's
+    // timestamp comes from a refetch a concurrent activation can precede).
+    const liveActiveConfigMatchesStored = entry?.activeConfigId === undefined ||
+        (live.record?.activeConfigId !== undefined &&
+            live.record?.activeConfigId !== null &&
+            String(entry.activeConfigId) === String(live.record.activeConfigId));
     const direction = classifyPushChange({
         localHash,
         remoteHash,
         baselineHash: entry?.semanticHash,
+        serverUnchangedSinceSync: input.serverModifiedAtCoversProjection === true &&
+            liveModifiedAtMatchesStored &&
+            liveActiveConfigMatchesStored,
         legacy: {
             localBytesMatchStoredContentHash: entry?.contentHash !== undefined &&
                 localFileHash !== undefined &&
                 entry.contentHash === localFileHash,
-            liveModifiedAtMatchesStored: entry?.modifiedAt !== undefined &&
-                live.modifiedAt !== undefined &&
-                entry.modifiedAt === live.modifiedAt,
+            liveModifiedAtMatchesStored,
         },
     });
     // #2909 — the adopt, for a type whose push path adopts by key. `entry` is
@@ -4807,6 +4873,55 @@ selects = () => true) {
         : { ok: false };
     return { scriptEntities, count: written, presence, listOk: true, serverKeys };
 }
+/**
+ * The manifest row `config push` records for a function it just pushed
+ * (#3317), and whether the server had already moved past that push.
+ *
+ * The header is refetched AFTER the version push, so the row's `modifiedAt`
+ * is the live timestamp — but the version pointer and the envelope are the
+ * push's own: the manifest names what THIS run activated, not whatever the
+ * refetch happened to find. A concurrent activation landing between the push
+ * and the refetch is exactly the case those two must not be conflated in:
+ * recording the refetched pointer would make the other operator's version the
+ * baseline the local file is then read as a plain edit of, and the next push
+ * would roll it back without `--force`. Recording the pushed pointer beside
+ * the live timestamp is what `decidePushForConfig` reads as "the pointer
+ * moved" — a refusal, until the operator pulls or forces.
+ *
+ * `movedTo` names the version the refetched header points at when it is not
+ * the pushed one, so the caller can say so at the moment it is known rather
+ * than leaving it for the next push to report.
+ */
+export function pushedFunctionBaseline(input) {
+    const { refreshed, pushedVersion } = input;
+    const pushedConfigId = pushedVersion?.configId !== undefined && pushedVersion?.configId !== null
+        ? String(pushedVersion.configId)
+        : undefined;
+    const liveConfigId = refreshed?.activeConfigId !== undefined && refreshed?.activeConfigId !== null
+        ? String(refreshed.activeConfigId)
+        : undefined;
+    const movedTo = pushedConfigId !== undefined &&
+        liveConfigId !== undefined &&
+        liveConfigId !== pushedConfigId
+        ? liveConfigId
+        : null;
+    return {
+        entity: {
+            id: input.functionId,
+            modifiedAt: refreshed?.modifiedAt ||
+                input.existingModifiedAt ||
+                new Date().toISOString(),
+            contentHash: input.contentHash,
+            semanticHash: refreshed
+                ? hashRemoteConfigForDiff(input.spec, refreshed, input.maps, pushedVersion ?? undefined)
+                : undefined,
+            envelopeHash: input.envelopeHash,
+            activeConfigId: pushedConfigId,
+            sources: input.sources,
+        },
+        movedTo,
+    };
+}
 /**
  * Pull server-side `ServerFunction` rows into `functions/` (#3179).
  *
@@ -4864,7 +4979,10 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
         };
         if (!record.activeConfigId) {
             // No code pushed yet: the header is all there is to write.
-            writeFileSync(filePath, serializeFunction(record));
+            // The logger carries #1446's one warning: a schema holding a `null`
+            // anywhere cannot be a native table, so it is written as a JSON string
+            // and the operator is told which key that happened to.
+            writeFileSync(filePath, serializeFunction(record, undefined, logger));
             entity.contentHash = computeFileHash(filePath);
             entity.semanticHash = hashRemoteConfigForDiff(configDiffSpec("function"), record, { ruleSetIdToName: new Map(), ruleSetNameToId: new Map() });
             functionEntities[key] = entity;
@@ -6426,25 +6544,15 @@ export function registerConfigSyncCommands(sync) {
     // Init
     sync
         .command("init")
+        .allowExcessArguments(false)
         .description("Initialize the config directory structure")
-        .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)")
-        .action(async (appId, options) => {
-        // Refused before any tree read/write or request (#3153, F1): the tree
-        // path no longer partitions by app.
-        assertTreeApp(appId || options.app, "config init");
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ userDir: options.dir });
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
         // A baseline that was never renamed means an unmigrated tree; refused
         // here, before any request, snapshot or directory is made (#3153).
         assertSyncStateLayout(configDir);
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-            const legacyHint = checkLegacySyncMigration(configDir);
-            if (legacyHint)
-                warn(legacyHint);
-        }
+        info(`Using per-environment config directory: ${configDir}`);
         ensureDir(configDir);
         ensureDir(join(configDir, "integrations"));
         ensureDir(join(configDir, "webhooks"));
@@ -6473,10 +6581,8 @@ export function registerConfigSyncCommands(sync) {
     // Pull
     sync
         .command("pull")
+        .allowExcessArguments(false)
         .description("Download configuration from server to TOML files")
-        .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("--json", "Output as JSON instead of writing files")
         .option("--only <selectors>", "Fetch just these objects: <type>/<key>, app, or var/<key> (repeatable, or comma-separated). Everything else in the slot is left as it is.", 
     // Collect rather than replace, the same way push does: commander keeps
@@ -6484,20 +6590,14 @@ export function registerConfigSyncCommands(sync) {
     // narrow the pull to one object and report success.
     (value, previous) => [...(previous ?? []), value], [])
         .option("--no-prune", "Keep local files for entities that are absent from the sync export (the next push will re-create them)")
-        .action(async (appId, options) => {
-        // Refused before any tree read/write or request (#3153, F1): the tree
-        // path no longer partitions by app.
-        assertTreeApp(appId || options.app, "config pull");
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ userDir: options.dir });
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
         // A baseline that was never renamed means an unmigrated tree; refused
         // here, before any request, snapshot or directory is made (#3153).
         assertSyncStateLayout(configDir);
-        if (isAutoResolvedSyncDir(options.dir) && !options.json) {
+        if (!options.json) {
             info(`Using per-environment config directory: ${configDir}`);
-            const legacyHint = checkLegacySyncMigration(configDir);
-            if (legacyHint)
-                warn(legacyHint);
         }
         // Issue #2760: pull writes the renamed directory and leaves the old one
         // untouched beside it, which reads as a successful pull that lost the
@@ -6697,10 +6797,7 @@ export function registerConfigSyncCommands(sync) {
             // perform it without a recoverable backup. No-op on a fresh/empty
             // sync dir (nothing to back up). Prune to 28 days after success.
             try {
-                const snapshotsRoot = resolveSnapshotsRoot({
-                    appId: resolvedAppId,
-                    userDir: options.dir,
-                });
+                const snapshotsRoot = resolveSnapshotsRoot({ appId: resolvedAppId });
                 const snapshot = createSnapshot(configDir, snapshotsRoot);
                 if (snapshot) {
                     info(`  Snapshot: ${snapshot.path}`);
@@ -6711,7 +6808,7 @@ export function registerConfigSyncCommands(sync) {
                 error(`Failed to create a pre-pull snapshot: ${snapErr?.message ?? snapErr}`);
                 error("Aborting pull before any local file is modified. " +
                     "Resolve the snapshot error (e.g. disk space / permissions) and retry, " +
-                    "or pass a writable --dir.");
+                    "and that the project's .primitive/ is writable.");
                 process.exit(1);
             }
             // Ensure directories exist
@@ -7284,12 +7381,17 @@ export function registerConfigSyncCommands(sync) {
             // they are not in the envelope, and a fresh clone must end up with the
             // same three files a push would have written. Written here, after the
             // database types, so the declaration describes what this pull wrote.
-            {
+            try {
                 const artifacts = writeFunctionTypeArtifacts(configDir);
                 if (artifacts.length > 0) {
                     info(`  Wrote function types: ${artifacts.join(", ")}`);
                 }
             }
+            catch (err) {
+                if (!(err instanceof FunctionSchemaCodegenError))
+                    throw err;
+                warn(`  Function types not generated: ${err.message}`);
+            }
             // Write rule sets
             const ruleSetEntities = {};
             for (const ruleSet of ruleSets) {
@@ -7768,10 +7870,8 @@ export function registerConfigSyncCommands(sync) {
     // Push
     sync
         .command("push")
+        .allowExcessArguments(false)
         .description("Upload local TOML configuration to server")
-        .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 be changed without applying")
         .option("--force", "Overwrite remote even if modified since last pull")
         .option("--only <selectors>", "Apply just these objects: <type>/<key>, app, or var/<key> (repeatable, or comma-separated). Everything else about push is unchanged.", 
@@ -7782,21 +7882,35 @@ export function registerConfigSyncCommands(sync) {
         .option("--prune", "Delete remote entities whose local TOML was removed since the last sync (issue #1655)")
         .option("-y, --yes", "Skip the interactive confirmation before pruning (for CI / automation)")
         .option("--accept-warnings", "Commit schema diffs that have operations with dynamic refs (issue #666 SCHEMA_HAS_UNCHECKABLE_OPS escape hatch)")
-        .action(async (appId, options) => {
-        // Refused before any tree read/write or request (#3153, F1): the tree
-        // path no longer partitions by app.
-        assertTreeApp(appId || options.app, "config push");
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ userDir: options.dir });
+        // #3320 — what this command actually guarantees, said where it is run.
+        // Two stages, and only the first is all-or-nothing.
+        .addHelpText("after", `
+What a push guarantees (two stages):
+
+  Preflight — the local tree only. Unknown keys and declared types, workflow
+  lints, function grant grammar, a function's \`entry\`, the function trigger
+  rules, and a webhook trigger's signing-secret requirement and reference
+  shape. Any error among them aborts the whole run and nothing is applied.
+  Those are the server's own rules, run against your files.
+
+  Apply — incremental and convergent, and there is no rollback. A rejection
+  may stop the remaining work depending on the type; whatever was already
+  applied stays applied; the exit status is non-zero; re-running converges.
+  A refused FUNCTION is recorded and the loop continues, so the rest of the
+  tree still lands.
+
+  Not preflighted, because the file cannot answer it: whether a referenced
+  secret exists, whether a scheme's config is valid under this environment's
+  policy, per-app caps, key collisions. Those surface during apply.
+`)
+        .option("--no-typecheck", "Ship function code without typechecking it against the declarations this push generates (issue #3331)")
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
         // A baseline that was never renamed means an unmigrated tree; refused
         // here, before any request, snapshot or directory is made (#3153).
         assertSyncStateLayout(configDir);
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-            const legacyHint = checkLegacySyncMigration(configDir);
-            if (legacyHint)
-                warn(legacyHint);
-        }
+        info(`Using per-environment config directory: ${configDir}`);
         // Issue #2760. An un-renamed checkout's `database-types/` is ignored, so
         // an ordinary push applies nothing from it — worth a warning. `--prune`
         // is the destructive case: it flags every prior-state key whose local
@@ -8486,6 +8600,22 @@ export function registerConfigSyncCommands(sync) {
                         })) {
                             preflightValidationErrors.push(`  ${message}`);
                         }
+                        // #3320 — and everything else the file decides on its own: the
+                        // `entry`, the mode the two spellings resolve to, the trigger
+                        // rules, and a webhook trigger's signing-secret requirement and
+                        // reference shape. These used to be raised inside the apply loop,
+                        // after webhooks, integrations, vars and database types had
+                        // already been written — the partial tree this issue is about.
+                        // Bounded by the same `selectFiles` above, so `--only` keeps its
+                        // posture (#2645).
+                        const functionKey = tomlData?.function?.key || basename(file, ".toml");
+                        for (const message of functionTomlPreflightErrors({
+                            filePath,
+                            functionKey,
+                            tomlData,
+                        })) {
+                            preflightValidationErrors.push(`  ${filePath}: ${message}`);
+                        }
                     }
                 }
             }
@@ -12946,18 +13076,44 @@ export function registerConfigSyncCommands(sync) {
                 // TREE rather than from the server: the types describe the schemas
                 // this push is applying. Regenerated every time and never part of the
                 // envelope — `config pull` recreates them the same way.
-                if (!options.dryRun) {
-                    const artifacts = writeFunctionTypeArtifacts(configDir);
-                    if (artifacts.length > 0) {
-                        info(`  Wrote function types: ${artifacts.join(", ")}`);
+                // #3281 — a malformed schema in a function file cannot be typed;
+                // the file's own push below refuses it by name, so the generators
+                // warn here and the rest of the tree still lands.
+                try {
+                    if (!options.dryRun) {
+                        const artifacts = writeFunctionTypeArtifacts(configDir);
+                        if (artifacts.length > 0) {
+                            info(`  Wrote function types: ${artifacts.join(", ")}`);
+                        }
+                    }
+                    // A tsconfig push will not rewrite (comments are the author's) or
+                    // cannot read is still a tsconfig no compiler loads the handle
+                    // through. Say so rather than report success over it (CR3182-003).
+                    for (const problem of functionTypeWiringProblems(configDir)) {
+                        warn(`  functions/tsconfig.json: ${problem}`);
                     }
                 }
-                // A tsconfig push will not rewrite (comments are the author's) or
-                // cannot read is still a tsconfig no compiler loads the handle
-                // through. Say so rather than report success over it (CR3182-003).
-                for (const problem of functionTypeWiringProblems(configDir)) {
-                    warn(`  functions/tsconfig.json: ${problem}`);
+                catch (err) {
+                    if (!(err instanceof FunctionSchemaCodegenError))
+                        throw err;
+                    warn(`  Function types not generated: ${err.message}`);
                 }
+                // #3331 — the compiler, over the declarations written (or, under
+                // `--dry-run`, planned) just above. Built once for the tree and
+                // consulted per function, so one broken file refuses itself and
+                // nothing else; `--no-typecheck` is the escape hatch, and an
+                // unavailable compiler warns rather than failing the push.
+                let typecheckSetup = null;
+                const functionTypechecker = () => {
+                    if (options.typecheck === false)
+                        return null;
+                    if (typecheckSetup === null) {
+                        typecheckSetup = createFunctionTypechecker(configDir);
+                        for (const warning of typecheckSetup.warnings)
+                            warn(`  ${warning}`);
+                    }
+                    return typecheckSetup.checker;
+                };
                 const files = selectFiles("function", functionsPushDir, readdirSync(functionsPushDir).filter((f) => f.endsWith(".toml")));
                 const functionSpec = configDiffSpec("function");
                 const liveFunctions = new Map();
@@ -13010,8 +13166,26 @@ export function registerConfigSyncCommands(sync) {
                         });
                         continue;
                     }
+                    // #3331 — and then the types. esbuild erases them, so a build that
+                    // succeeded says nothing about whether the code holds against the
+                    // declarations this same push generated: `ctx.user` going nullable
+                    // (#3279) bundles cleanly and throws on the request path. Refused
+                    // here, against THIS function's own sources, before anything is
+                    // sent for it and whether or not this is a dry run.
+                    const typechecker = functionTypechecker();
+                    if (typechecker) {
+                        const failure = typechecker.check(key, push.sources.map((source) => source.path));
+                        if (failure) {
+                            applyFailures.push({
+                                type: "function",
+                                key,
+                                message: failure.message,
+                            });
+                            continue;
+                        }
+                    }
                     // The active version, needed by BOTH axes: the header comparison
-                    // reads `entry`/`durable`/`limits` off it, and the code axis
+                    // reads `entry`/`mode`/`limits` off it, and the code axis
                     // compares its `envelopeHash`.
                     let activeVersion = null;
                     let versionOk = functionsLiveOk;
@@ -13042,6 +13216,15 @@ export function registerConfigSyncCommands(sync) {
                             entry: existingEntry,
                             localFileHash: computeFileHash(filePath),
                             force: options.force,
+                            // #3317 — the header row's `modifiedAt` covers everything
+                            // compared here: its own fields, and the `activeConfigId`
+                            // pointer whose repointing is the only way the immutable
+                            // version behind the extras can change. So an unmoved
+                            // timestamp proves the server stood still, and a baseline hash
+                            // that disagrees is a stale baseline — the reporter's CONFLICT
+                            // over two identical timestamps, which is also what every
+                            // manifest written before this issue's schema fix would hit.
+                            serverModifiedAtCoversProjection: true,
                             // The create leg adopts by key on the server's 409 (#1006), so
                             // an untracked function the server already holds is that same
                             // adopt reached one step earlier.
@@ -13176,19 +13359,27 @@ export function registerConfigSyncCommands(sync) {
                             // Non-fatal: the baseline falls back to what the listing said.
                             // The next push reconciles it.
                         }
-                        syncState.entities.functions[key] = {
-                            id: String(functionId),
-                            modifiedAt: refreshed?.modifiedAt ||
-                                existingEntry?.modifiedAt ||
-                                new Date().toISOString(),
+                        // #3317 — the pointer recorded is the one THIS push activated,
+                        // whatever the refetch found: a concurrent activation in the
+                        // window between the two is a server move the next push must
+                        // refuse over, not a baseline it silently rolls back.
+                        const baseline = pushedFunctionBaseline({
+                            functionId: String(functionId),
+                            refreshed,
+                            existingModifiedAt: existingEntry?.modifiedAt,
                             contentHash: computeFileHash(filePath),
-                            semanticHash: refreshed
-                                ? hashRemoteConfigForDiff(functionSpec, refreshed, pushDiffMaps, pushedVersion ?? undefined)
-                                : undefined,
+                            pushedVersion,
                             envelopeHash: push.envelopeHash,
-                            activeConfigId: pushedVersion?.configId,
                             sources: push.sources.map((src) => src.path),
-                        };
+                            spec: functionSpec,
+                            maps: pushDiffMaps,
+                        });
+                        if (baseline.movedTo) {
+                            warn(`  Function ${key}: the server's active version moved to ${baseline.movedTo} ` +
+                                `while version ${pushedVersion?.configId} was being recorded; ` +
+                                "the next push will report the drift (`config pull` adopts it, `--force` overrides it).");
+                        }
+                        syncState.entities.functions[key] = baseline.entity;
                     }
                 }
             }
@@ -14507,27 +14698,17 @@ export function registerConfigSyncCommands(sync) {
     // Diff
     sync
         .command("diff")
+        .allowExcessArguments(false)
         .description("Show differences between local and remote configuration")
-        .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("--only <selectors>", "Compare just these objects: <type>/<key>, app, or var/<key> (repeatable, or comma-separated).", (value, previous) => [...(previous ?? []), value], [])
-        .option("--json", "Output as JSON (app.toml field diff, with --only app)")
-        .action(async (appId, options) => {
-        // Refused before any tree read/write or request (#3153, F1): the tree
-        // path no longer partitions by app.
-        assertTreeApp(appId || options.app, "config diff");
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ userDir: options.dir });
+        .option("--json", "Output as JSON: the app.toml field diff with --only app, the compared rows otherwise")
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
         // A baseline that was never renamed means an unmigrated tree; refused
         // here, before any request, snapshot or directory is made (#3153).
         assertSyncStateLayout(configDir);
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-            const legacyHint = checkLegacySyncMigration(configDir);
-            if (legacyHint)
-                warn(legacyHint);
-        }
+        info(`Using per-environment config directory: ${configDir}`);
         // Issue #2760: diff compares the renamed directory, so a legacy one is
         // simply invisible — an empty diff would otherwise read as "in sync".
         const legacyDbTypes = checkLegacyDatabaseTypesDir(configDir);
@@ -15205,7 +15386,7 @@ export function registerConfigSyncCommands(sync) {
                 }
                 let status = "exists";
                 let hint;
-                // The active version carries `entry`, `durable` and `limits`, and its
+                // The active version carries `entry`, `mode` and `limits`, and its
                 // `envelopeHash` is the code axis.
                 const versionOutcome = await attemptFetch(async () => {
                     if (!remote.activeConfigId)
@@ -15724,7 +15905,16 @@ export function registerConfigSyncCommands(sync) {
             // the same preflight push runs decides these rows, and its message —
             // verbatim, so the two commands read identically — replaces whatever
             // the comparison had to say about the file.
-            for (const rejected of collectConfigFileValidationErrors(configDir)) {
+            // #3320 — the function checks join them. Same posture, same messages:
+            // a function file whose `entry`, mode, triggers or webhook
+            // signing-secret the push preflight refuses is not a row this command
+            // calls Synced, Modified or "local only — new".
+            // Merged first: a file both collectors reject keeps every message push
+            // prints, rather than one collector's hint overwriting the other's.
+            for (const rejected of mergeConfigFileValidationErrors([
+                ...collectConfigFileValidationErrors(configDir),
+                ...collectFunctionTomlValidationErrors(configDir),
+            ])) {
                 const row = differences.find((d) => d.type === rejected.type && d.key === rejected.key);
                 const hint = rejected.messages.join("; ");
                 if (row) {
@@ -15755,6 +15945,22 @@ export function registerConfigSyncCommands(sync) {
                             ? selectionIncludesApp(diffSelection)
                             : selectionIncludesKey(diffSelection, row.type, row.key));
             }
+            // #3320 — `--json` over the whole comparison, not just `--only app`.
+            // The Invalid rows this issue adds have to be readable by the thing
+            // that reads a diff programmatically (an editor, a CI job), and the
+            // flag already existed for the app-settings case; a run that asked for
+            // JSON and got a human table was answering a different question.
+            // Emitted after the `--only` filter so a scoped run reports its scope.
+            if (options.json) {
+                console.log(JSON.stringify({
+                    appId: resolvedAppId,
+                    configDir,
+                    differences,
+                    testCases: testCaseDiffs,
+                    notCompared,
+                }, null, 2));
+                return;
+            }
             divider();
             const localOnly = differences.filter((d) => d.status === LOCAL_ONLY_NEW);
             const localOnlyAbsent = differences.filter((d) => d.status === LOCAL_ONLY_ABSENT);
@@ -15887,7 +16093,23 @@ export function registerConfigSyncCommands(sync) {
             // change, so `config diff` is where their freshness is answered: an
             // editor or a CI job asks the same command it already asks "what would
             // push do?", and gets these named alongside everything else.
-            const staleFunctionTypes = staleFunctionTypeArtifacts(configDir);
+            let staleFunctionTypes = [];
+            let wiringProblems = [];
+            try {
+                staleFunctionTypes = staleFunctionTypeArtifacts(configDir);
+                // Freshness is not the only way the handle stops working: a tsconfig
+                // push will not rewrite can be perfectly current and still load none
+                // of it. `config diff` is where CI asks, so it answers both
+                // (CR3182-003).
+                wiringProblems = functionTypeWiringProblems(configDir);
+            }
+            catch (err) {
+                if (!(err instanceof FunctionSchemaCodegenError))
+                    throw err;
+                // #3281 — a function file whose schema cannot be typed is reported
+                // like a wiring problem: the generators cannot answer for the tree.
+                wiringProblems = [err.message];
+            }
             if (staleFunctionTypes.length > 0) {
                 console.log();
                 info("Function types (regenerated by `config push`):");
@@ -15895,10 +16117,6 @@ export function registerConfigSyncCommands(sync) {
                     console.log(`  ${chalk.yellow("~")} ${relative}`);
                 }
             }
-            // Freshness is not the only way the handle stops working: a tsconfig
-            // push will not rewrite can be perfectly current and still load none of
-            // it. `config diff` is where CI asks, so it answers both (CR3182-003).
-            const wiringProblems = functionTypeWiringProblems(configDir);
             if (wiringProblems.length > 0) {
                 console.log();
                 info("Function types (compiler wiring `config push` cannot repair):");
@@ -15943,28 +16161,21 @@ export function registerConfigSyncCommands(sync) {
     // containing null) fall back to JSON-string per field with a log message.
     sync
         .command("migrate-toml")
+        .allowExcessArguments(false)
         .description("Rewrite database-type and workflow TOML files to native form " +
         "([operations.definition] / [[operations.params]] for database types; " +
         "[workflow.inputSchema] / [workflow.outputSchema] for workflows)")
-        .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")
-        .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-toml` is a purely local rewrite.
-        // Refused before any tree read/write or request (#3153, F1): the tree
-        // path no longer partitions by app.
-        assertTreeApp(appId || options.app, "config migrate-toml");
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ userDir: options.dir });
+        .action(async (options) => {
+        // The app ID is not used for any API call — `migrate-toml` is a purely
+        // local rewrite — but the environment that names it is what names the
+        // tree being rewritten.
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
         // A baseline that was never renamed means an unmigrated tree; refused
         // here, before any request, snapshot or directory is made (#3153).
         assertSyncStateLayout(configDir);
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-        }
+        info(`Using per-environment config directory: ${configDir}`);
         if (!existsSync(configDir)) {
             error(`Config directory not found: ${configDir}`);
             process.exit(1);
@@ -16114,27 +16325,19 @@ export function registerConfigSyncCommands(sync) {
     // proven), so re-running push/pull is unaffected.
     sync
         .command("migrate-v2")
+        .allowExcessArguments(false)
         .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).
-        // Refused before any tree read/write or request (#3153, F1): the tree
-        // path no longer partitions by app.
-        assertTreeApp(appId || options.app, "config migrate-v2");
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ userDir: options.dir });
+        .action(async (options) => {
+        // As with migrate-toml: a purely local rewrite, whose tree is the
+        // resolved environment's.
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
         // A baseline that was never renamed means an unmigrated tree; refused
         // here, before any request, snapshot or directory is made (#3153).
         assertSyncStateLayout(configDir);
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-        }
+        info(`Using per-environment config directory: ${configDir}`);
         if (!existsSync(configDir)) {
             error(`Config directory not found: ${configDir}`);
             process.exit(1);
@@ -16173,29 +16376,19 @@ export function registerConfigSyncCommands(sync) {
     // Revert — restore a pre-pull snapshot (issue #578, Phase 1).
     sync
         .command("revert")
+        .allowExcessArguments(false)
         .description("Restore the config directory from a snapshot taken before a previous pull")
-        .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("--snapshot <id>", "Snapshot id (timestamp dirname or a unique >=8-char prefix)")
         .option("--list", "List available snapshots without restoring")
         .option("-y, --yes", "Skip the confirmation prompt")
-        .action(async (appId, options) => {
-        // Refused before any tree read/write or request (#3153, F1): the tree
-        // path no longer partitions by app.
-        assertTreeApp(appId || options.app, "config revert");
-        const resolvedAppId = resolveAppId(appId, options);
-        const configDir = resolveSyncDir({ userDir: options.dir });
+        .action(async (options) => {
+        const resolvedAppId = getCurrentAppId();
+        const configDir = resolveSyncDir();
         // A baseline that was never renamed means an unmigrated tree; refused
         // here, before any request, snapshot or directory is made (#3153).
         assertSyncStateLayout(configDir);
-        const snapshotsRoot = resolveSnapshotsRoot({
-            appId: resolvedAppId,
-            userDir: options.dir,
-        });
-        if (isAutoResolvedSyncDir(options.dir)) {
-            info(`Using per-environment config directory: ${configDir}`);
-        }
+        const snapshotsRoot = resolveSnapshotsRoot({ appId: resolvedAppId });
+        info(`Using per-environment config directory: ${configDir}`);
         const snapshots = listSnapshots(snapshotsRoot);
         // --list, or no snapshots at all: enumerate and stop.
         if (options.list || snapshots.length === 0) {
@@ -16255,9 +16448,7 @@ export function registerConfigSyncCommands(sync) {
             }
         }
         try {
-            // Under legacy `--dir`, snapshotsRoot lives inside configDir; preserve
-            // it across the full-tree swap so we don't wipe backup history.
-            restoreSnapshot(target.path, configDir, { preserveDir: snapshotsRoot });
+            restoreSnapshot(target.path, configDir);
         }
         catch (err) {
             error(`Restore failed: ${err?.message ?? err}`);