primitive-admin 1.0.49 → 1.0.50

package/dist/src/commands/sync.js

@@ -7,7 +7,8 @@ import { ApiClient, ApiError, ConflictError, SchemaRequiredError, OperationRefEr
 import { buildDatabaseTypeTomlData, detectExistingOperationForms, normalizeOperationFromToml, normalizeSubscriptionFromToml, SubscriptionAccessKeyConflictError, } from "../lib/toml-database-config.js";
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { getServerUrl, resolveAppId } from "../lib/config.js";
-import { resolveSyncDir, isAutoResolvedSyncDir, checkLegacySyncMigration, } from "../lib/sync-paths.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";
@@ -17,6 +18,19 @@ function ensureDir(dirPath) {
         mkdirSync(dirPath, { recursive: true });
     }
 }
+/**
+ * Issue #974: when a type-config push newly declares fields `unique = true`
+ * and the type already has instances, the server returns a
+ * `staleInstanceWarning`. Surface it so the operator knows the existing
+ * instances still lack the index and how to back-provision them. The push
+ * itself still succeeded — this is informational, not a failure.
+ */
+function printStaleInstanceWarning(updated) {
+    const w = updated?.staleInstanceWarning;
+    if (w && typeof w.message === "string") {
+        warn(`  ${w.message}`);
+    }
+}
 function loadSyncState(configDir) {
     const syncFile = join(configDir, ".primitive-sync.json");
     if (!existsSync(syncFile)) {
@@ -720,6 +734,56 @@ export async function pullScripts(client, appId, configDir, logger = () => { })
     }
     return { scriptEntities, count: items.length };
 }
+/**
+ * Issue #973 — format the "stale referencing workflows" warning for a script
+ * push. Pure (no I/O) so it can be unit-tested directly.
+ *
+ * `staleWorkflows` is the server's report of active workflows whose frozen
+ * snapshot still pins a DIFFERENT (old) body hash for `scriptName` — i.e. the
+ * workflows that will keep running the previous script body until republished.
+ * Returns `null` when nothing is stale (no warning to print). When `dryRun` is
+ * true the wording reflects that nothing was mutated yet.
+ */
+export function formatStaleWorkflowsWarning(scriptName, staleWorkflows, dryRun = false) {
+    if (!staleWorkflows || staleWorkflows.length === 0)
+        return null;
+    const labels = staleWorkflows.map((w) => w.workflowKey || w.name || "(unknown workflow)");
+    const count = labels.length;
+    const noun = count === 1 ? "workflow" : "workflows";
+    const verb = dryRun ? "would still run" : "still run";
+    return (`Script "${scriptName}" ${dryRun ? "would be updated" : "updated"}, but ` +
+        `${count} ${noun} ${verb} the previous body until re-pushed: ` +
+        `${labels.join(", ")}. ` +
+        `Re-push (or republish) ${count === 1 ? "it" : "them"} to pick up the change ` +
+        `(the run path reads each workflow's frozen snapshot, not the live script).`);
+}
+/**
+ * Issue #973 — query the server for active workflows left stale by a script
+ * push and print a warning naming them. Best-effort: a missing route (older
+ * server) or any transport error is swallowed so it never fails the sync.
+ *
+ * `contentHash` is the body hash being pushed (the server's authoritative hash
+ * after a real push, or the locally-computed would-be hash for `--dry-run`).
+ */
+async function warnStaleWorkflowsForScript(client, appId, scriptId, contentHash, dryRun) {
+    let report;
+    try {
+        report = await client.getStaleWorkflowsForScript(appId, scriptId, contentHash);
+    }
+    catch {
+        // Older server without the route, or a transient failure — staleness
+        // info is advisory, so we stay silent rather than break the push.
+        return;
+    }
+    const message = formatStaleWorkflowsWarning(report.scriptName, report.staleWorkflows, dryRun);
+    if (message) {
+        warn(`  ${message}`);
+    }
+}
+/** SHA-256 hex of a string body, matching the server's script `contentHash`. */
+function sha256HexString(body) {
+    return createHash("sha256").update(body, "utf-8").digest("hex");
+}
 async function pullTestCasesForBlock(client, appId, blockType, blockId, blockKey, configDir, testCaseEntities, lookupMaps) {
     let testCases;
     try {
@@ -1153,6 +1217,35 @@ Directory Structure:
                     subscriptions: Array.isArray(subs) ? subs : [],
                 };
             }));
+            // Snapshot the pre-pull sync tree BEFORE we touch any local file
+            // (issue #578, Phase 1). All server data has been fetched and
+            // validated at this point — a failed pull already threw above, so we
+            // never create empty snapshots — but no local file has been
+            // overwritten yet. This is the proven copy-point: between the last
+            // server fetch and the first directory mutation.
+            //
+            // Fail LOUD: if the snapshot can't be written, abort the pull BEFORE
+            // the ensureDir below. Better to refuse a destructive pull than
+            // 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 snapshot = createSnapshot(configDir, snapshotsRoot);
+                if (snapshot) {
+                    info(`  Snapshot: ${snapshot.path}`);
+                    pruneSnapshots(snapshotsRoot, 28);
+                }
+            }
+            catch (snapErr) {
+                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.");
+                process.exit(1);
+            }
             // Ensure directories exist
             ensureDir(configDir);
             ensureDir(join(configDir, "integrations"));
@@ -1660,6 +1753,82 @@ Directory Structure:
             const promptKeyToId = new Map();
             const promptConfigNameToId = new Map(); // key: "promptKey#configName"
             const workflowConfigNameToId = new Map(); // key: "workflowKey#configName"
+            // ── Issue #976 (fix A): front-load ALL client-side TOML validation
+            // before the first mutating call. Push is apply-as-you-go and processes
+            // entities in a fixed sequence (cron triggers are created *before*
+            // workflows are validated). Previously each entity's validation lived
+            // inside its own apply loop and aborted via `process.exit(1)` — so a
+            // known-bad sibling file (e.g. an invalid workflow TOML) could let an
+            // earlier create (a cron trigger) be applied, then abort. The
+            // `process.exit` also bypassed the save-on-failure catch below, so the
+            // orphaned create never reached `.primitive-sync.json` and the retry
+            // re-issued a CREATE that the server rejected with 409 forever.
+            //
+            // Running every validation up-front means a known-bad file aborts
+            // BEFORE anything is created. We collect all errors (not just the first)
+            // and THROW — so the single save-on-failure catch is the only exit path
+            // (no more `process.exit` bypass class). The per-loop validators below
+            // remain as defense-in-depth but are converted to throws too.
+            const preflightValidationErrors = [];
+            // Validate all workflow TOMLs (issue #685 misnested-header check).
+            const preflightWorkflowsDir = join(configDir, "workflows");
+            if (existsSync(preflightWorkflowsDir)) {
+                for (const file of readdirSync(preflightWorkflowsDir).filter((f) => f.endsWith(".toml"))) {
+                    const filePath = join(preflightWorkflowsDir, file);
+                    try {
+                        const tomlData = parseTomlFile(filePath);
+                        const tomlErrors = validateWorkflowToml(tomlData);
+                        if (tomlErrors.length > 0) {
+                            preflightValidationErrors.push(formatWorkflowTomlErrors(filePath, tomlErrors));
+                        }
+                    }
+                    catch (err) {
+                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+                    }
+                }
+            }
+            // Validate all database-type TOMLs (issue #803 subscription
+            // access/accessRule conflict + issue #752 $params references).
+            const preflightDbTypesDir = join(configDir, "database-types");
+            if (existsSync(preflightDbTypesDir)) {
+                for (const file of readdirSync(preflightDbTypesDir).filter((f) => f.endsWith(".toml"))) {
+                    const filePath = join(preflightDbTypesDir, file);
+                    let rawToml;
+                    let tomlData;
+                    try {
+                        rawToml = readFileSync(filePath, "utf-8");
+                        tomlData = parseTomlFile(filePath);
+                    }
+                    catch (err) {
+                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+                        continue;
+                    }
+                    let operations = [];
+                    try {
+                        ({ operations } = parseDatabaseTypeToml(tomlData));
+                    }
+                    catch (err) {
+                        if (err instanceof SubscriptionAccessKeyConflictError) {
+                            preflightValidationErrors.push(`  ${file}: ${err.message}`);
+                            continue;
+                        }
+                        preflightValidationErrors.push(`  ${file}: ${err?.message || String(err)}`);
+                        continue;
+                    }
+                    const validation = validateOperations({
+                        filePath,
+                        rawToml,
+                        operations,
+                    });
+                    for (const e of validation.errors) {
+                        preflightValidationErrors.push(`  ${formatIssue(e)}`);
+                    }
+                }
+            }
+            if (preflightValidationErrors.length > 0) {
+                throw new Error(`Aborting push: ${preflightValidationErrors.length} TOML validation error(s) — no changes were applied.\n` +
+                    preflightValidationErrors.join("\n"));
+            }
             // Process app settings
             const appTomlPath = join(configDir, "app.toml");
             if (existsSync(appTomlPath)) {
@@ -2031,7 +2200,58 @@ Directory Structure:
                                 }
                             }
                             catch (err) {
-                                throw wrapEntityError(err, "create", "cron trigger", key);
+                                // Issue #976 (fix B): idempotent create — adopt-by-key on 409.
+                                // A cron trigger can be orphaned on the server (created by a
+                                // prior push that aborted before recording it in sync state,
+                                // a mid-apply crash, or an out-of-band create with the same
+                                // key). On retry this CREATE path then hits the
+                                // `triggerKeyPerApp` unique constraint and the server returns
+                                // 409 "A cron trigger with this key already exists". Rather
+                                // than hard-fail forever, look up the existing trigger by key
+                                // (the list endpoint is app-scoped, so every item is owned by
+                                // this app), verify the SAME triggerKey, adopt its id into
+                                // sync state, and re-issue as an UPDATE so the push converges.
+                                const msg = String(err?.message || err);
+                                const is409 = err?.statusCode === 409 || msg.includes("already exists");
+                                if (is409) {
+                                    info(`  Cron trigger already exists on server, adopting by key: ${key}`);
+                                    let adoptedId;
+                                    try {
+                                        const { items } = await client.listCronTriggers(resolvedAppId);
+                                        // Verify same key + app ownership: the list endpoint only
+                                        // returns triggers for `resolvedAppId`, so a triggerKey
+                                        // match is also an ownership match. Never overwrite an
+                                        // unrelated resource — require an exact key equality.
+                                        const existing = (items || []).find((t) => t?.triggerKey === key);
+                                        if (existing?.triggerId) {
+                                            adoptedId = existing.triggerId;
+                                        }
+                                    }
+                                    catch (lookupErr) {
+                                        throw wrapEntityError(new Error(`cron trigger "${key}" already exists but could not be adopted (lookup failed: ${String(lookupErr?.message || lookupErr)})`), "create", "cron trigger", key);
+                                    }
+                                    if (!adoptedId) {
+                                        // 409 but no matching key found on the server — surface
+                                        // the original error rather than silently overwriting.
+                                        throw wrapEntityError(err, "create", "cron trigger", key);
+                                    }
+                                    // Switch to UPDATE on the adopted trigger.
+                                    const updated = await client.updateCronTrigger(resolvedAppId, adoptedId, payload);
+                                    info(`  Adopted + updated cron trigger: ${key}`);
+                                    if (syncState) {
+                                        if (!syncState.entities.cronTriggers) {
+                                            syncState.entities.cronTriggers = {};
+                                        }
+                                        syncState.entities.cronTriggers[key] = {
+                                            id: adoptedId,
+                                            modifiedAt: updated?.modifiedAt || new Date().toISOString(),
+                                            contentHash: computeFileHash(filePath),
+                                        };
+                                    }
+                                }
+                                else {
+                                    throw wrapEntityError(err, "create", "cron trigger", key);
+                                }
                             }
                         }
                     }
@@ -2372,11 +2592,18 @@ Directory Structure:
                                         contentHash: computeFileHash(filePath),
                                     };
                                 }
+                                // Issue #973 — warn if active workflows still pin the OLD
+                                // body. Use the server's authoritative post-push hash.
+                                await warnStaleWorkflowsForScript(client, resolvedAppId, existingId, updated?.contentHash || sha256HexString(body), false);
                             }
                             catch (err) {
                                 throw wrapEntityError(err, "update", "script", name);
                             }
                         }
+                        else {
+                            // Dry-run: surface the would-be stale set without mutating.
+                            await warnStaleWorkflowsForScript(client, resolvedAppId, existingId, sha256HexString(body), true);
+                        }
                     }
                     else {
                         // No id in local state — could be brand new OR could be
@@ -2401,11 +2628,17 @@ Directory Structure:
                                             contentHash: computeFileHash(filePath),
                                         };
                                     }
+                                    // Issue #973 — same staleness warning on the adopt path.
+                                    await warnStaleWorkflowsForScript(client, resolvedAppId, match.scriptId, updated?.contentHash || sha256HexString(body), false);
                                 }
                                 catch (err) {
                                     throw wrapEntityError(err, "update", "script", name);
                                 }
                             }
+                            else {
+                                // Dry-run on the adopt path.
+                                await warnStaleWorkflowsForScript(client, resolvedAppId, match.scriptId, sha256HexString(body), true);
+                            }
                         }
                         else {
                             changes.push({ type: "script", action: "create", key: name });
@@ -2445,10 +2678,14 @@ Directory Structure:
                     // place to catch the footgun. Validation happens BEFORE the
                     // skip-if-unchanged check so a previously-pushed-but-broken
                     // file gets a clear diagnostic on every push attempt.
+                    // Issue #976: validation is now front-loaded before any apply
+                    // (see the pre-flight pass above). This in-loop check remains as
+                    // defense-in-depth, but THROWS rather than `process.exit(1)` so the
+                    // single save-on-failure catch is the only exit path — never
+                    // bypassing it and orphaning an already-created resource.
                     const tomlErrors = validateWorkflowToml(tomlData);
                     if (tomlErrors.length > 0) {
-                        error(formatWorkflowTomlErrors(filePath, tomlErrors));
-                        process.exit(1);
+                        throw new Error(formatWorkflowTomlErrors(filePath, tomlErrors));
                     }
                     const workflow = tomlData.workflow || {};
                     const key = workflow.key || basename(file, ".toml");
@@ -2679,9 +2916,10 @@ Directory Structure:
                         // (issue #803). Surface it with the file name and abort the
                         // push rather than crashing with an opaque stack.
                         if (err instanceof SubscriptionAccessKeyConflictError) {
-                            error(`  ${file}: ${err.message}`);
-                            error(`Aborting push: subscription \`access\`/\`accessRule\` conflict in ${file}.`);
-                            process.exit(1);
+                            // Issue #976: throw (not `process.exit`) so the save-on-failure
+                            // catch is the only exit path. Validation is also front-loaded
+                            // above, so this is defense-in-depth.
+                            throw new Error(`  ${file}: ${err.message}\nAborting push: subscription \`access\`/\`accessRule\` conflict in ${file}.`);
                         }
                         throw err;
                     }
@@ -2701,11 +2939,11 @@ Directory Structure:
                         warn(`  ${formatIssue(w)}`);
                     }
                     if (validation.errors.length > 0) {
-                        for (const e of validation.errors) {
-                            error(`  ${formatIssue(e)}`);
-                        }
-                        error(`Aborting push: ${validation.errors.length} unresolved $params reference(s) in ${file}.`);
-                        process.exit(1);
+                        // Issue #976: throw (not `process.exit`) so the save-on-failure
+                        // catch is the only exit path. Validation is also front-loaded
+                        // above, so this is defense-in-depth.
+                        throw new Error(validation.errors.map((e) => `  ${formatIssue(e)}`).join("\n") +
+                            `\nAborting push: ${validation.errors.length} unresolved $params reference(s) in ${file}.`);
                     }
                     const existingEntry = syncState?.entities?.databaseTypes?.[dbType];
                     // Skip if file hasn't changed since last sync
@@ -3016,6 +3254,7 @@ Directory Structure:
                                         acceptWarnings: !!options.acceptWarnings,
                                     });
                                     info(`  Updated database type: ${dbType}`);
+                                    printStaleInstanceWarning(updated);
                                     if (syncState?.entities?.databaseTypes?.[dbType] && updated?.modifiedAt) {
                                         syncState.entities.databaseTypes[dbType].modifiedAt = updated.modifiedAt;
                                         syncState.entities.databaseTypes[dbType].contentHash = computeFileHash(filePath);
@@ -3258,6 +3497,7 @@ Directory Structure:
                                             dryRun: false,
                                             acceptWarnings: !!options.acceptWarnings,
                                         });
+                                        printStaleInstanceWarning(reconciled);
                                         if (syncState?.entities?.databaseTypes?.[dbType] &&
                                             reconciled?.modifiedAt) {
                                             syncState.entities.databaseTypes[dbType].modifiedAt =
@@ -4264,5 +4504,119 @@ Directory Structure:
             success(`Rewrote ${migratedCount} TOML file(s) to native form.`);
         }
     });
+    // Revert — restore a pre-pull snapshot (issue #578, Phase 1).
+    sync
+        .command("revert")
+        .description("Restore the sync 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) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const configDir = resolveSyncDir({
+            appId: resolvedAppId,
+            userDir: options.dir,
+        });
+        const snapshotsRoot = resolveSnapshotsRoot({
+            appId: resolvedAppId,
+            userDir: options.dir,
+        });
+        if (isAutoResolvedSyncDir(options.dir)) {
+            info(`Using per-environment sync directory: ${configDir}`);
+        }
+        const snapshots = listSnapshots(snapshotsRoot);
+        // --list, or no snapshots at all: enumerate and stop.
+        if (options.list || snapshots.length === 0) {
+            if (snapshots.length === 0) {
+                info(`No snapshots found in ${snapshotsRoot}`);
+                info("Snapshots are created automatically before each 'sync pull'.");
+                return;
+            }
+            divider();
+            info(`Snapshots for this slot (${snapshotsRoot}), newest first:`);
+            for (const snap of snapshots) {
+                const flags = [];
+                if (!snap.complete)
+                    flags.push("INCOMPLETE");
+                if (snap.auditId)
+                    flags.push(`audit=${snap.auditId}`);
+                const suffix = flags.length ? `  (${flags.join(", ")})` : "";
+                keyValue(snap.id, `${snap.createdAt.toISOString()}${suffix}`);
+            }
+            if (!options.list) {
+                info("");
+                info("Run 'primitive sync revert --snapshot <id>' to restore one, " +
+                    "or 'primitive sync revert' to restore the most recent.");
+            }
+            return;
+        }
+        // Resolve the target snapshot (exact id, unique prefix, or most-recent).
+        let target;
+        try {
+            target = resolveSnapshot(snapshotsRoot, options.snapshot);
+        }
+        catch (err) {
+            error(err?.message ?? String(err));
+            process.exit(1);
+        }
+        if (!target.complete) {
+            error(`Snapshot ${target.id} is incomplete (missing the integrity marker) and cannot be restored safely.`);
+            process.exit(1);
+        }
+        // Confirmation, with a dirty-git warning.
+        if (!options.yes) {
+            if (await hasUncommittedChanges(configDir)) {
+                warn(`You have uncommitted git changes under ${configDir}. ` +
+                    "Reverting will overwrite them.");
+            }
+            const inquirer = await import("inquirer");
+            const { confirm } = await inquirer.default.prompt([
+                {
+                    type: "confirm",
+                    name: "confirm",
+                    message: `Restore snapshot ${target.id} into ${configDir}? This overwrites the current sync directory.`,
+                    default: false,
+                },
+            ]);
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        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 });
+        }
+        catch (err) {
+            error(`Restore failed: ${err?.message ?? err}`);
+            process.exit(1);
+        }
+        success(`Restored snapshot ${target.id} into ${configDir} (including .primitive-sync.json).`);
+        info("Run 'primitive sync diff' to inspect the restored state versus the server.");
+    });
+}
+/**
+ * Best-effort check for uncommitted git changes under `dir`. Used only to warn
+ * before a revert overwrites local edits — never fatal. Returns false if git
+ * isn't available, the dir isn't in a repo, or anything goes wrong.
+ */
+async function hasUncommittedChanges(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        const { execSync } = await import("child_process");
+        const out = execSync(`git status --porcelain -- "${dir}"`, {
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf-8",
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
 }
 //# sourceMappingURL=sync.js.map