primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.40

package/dist/src/lib/toml-params-validator.js

@@ -0,0 +1,298 @@
+/**
+ * Validator: every `$params.X` reference inside an operation's
+ * `definition` must correspond to a declared param in
+ * `[[operations.params]]` (or the legacy JSON-string params object).
+ *
+ * Background (issue #752): a typo like `$params.proectId` used to
+ * silently no-op at runtime. With native TOML, we can catch these at
+ * `sync push` time with the file path and line number of the
+ * operation block where the bad reference appears.
+ *
+ * Design notes:
+ *   - Line attribution is per-operation, not per-reference. We don't
+ *     parse `definition` line-by-line; we just locate the
+ *     `[[operations]]` header for the named op in the raw source and
+ *     report that line. This is the load-bearing UX (jump to the
+ *     offending op block); pinpointing the exact `$params.X` reference
+ *     inside a sub-table would require swapping the TOML parser, which
+ *     the issue explicitly leaves to implementer judgement.
+ *   - We intentionally diverge from the server-side `collectParamRefs`
+ *     in `database-type-operations-controller.ts:1163`. The server pushes
+ *     the full path (e.g. `"X.Y"` for `$params.X.Y`); the CLI extracts
+ *     only the first segment (`"X"`). Net effect: the CLI validator is
+ *     more lenient than the server — `$params.X.Y` passes the CLI check
+ *     when `X` alone is declared in `[[operations.params]]`, even though
+ *     the server treats the full path as the lookup key. The server
+ *     remains authoritative; the CLI's first-segment extraction is a
+ *     pragmatic choice so authors can declare structured params (e.g.
+ *     `config: { type: "object" }`) and reference sub-fields like
+ *     `$params.config.subKey` without listing every sub-field
+ *     individually (review feedback r3246635661).
+ */
+import { collectUnknownOperators } from "./query-operators.js";
+/**
+ * Walk an arbitrary JSON-ish value and collect `$params.X` references
+ * found in string-valued leaves, returning only the first dotted segment
+ * (`"X"` for `$params.X.Y`). Intentionally more lenient than the
+ * server-side helper, which pushes the full path — see the module
+ * doc-comment for the rationale.
+ */
+export function collectParamRefs(value) {
+    const refs = [];
+    if (typeof value === "string") {
+        const match = value.match(/^\$params\.(.+)$/);
+        if (match) {
+            const first = match[1].split(/[.\[]/)[0];
+            if (first)
+                refs.push(first);
+        }
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value) {
+            refs.push(...collectParamRefs(item));
+        }
+    }
+    else if (value !== null && typeof value === "object") {
+        for (const v of Object.values(value)) {
+            refs.push(...collectParamRefs(v));
+        }
+    }
+    return refs;
+}
+/**
+ * Collect bare `params.X` references from a CEL string (issue #1239).
+ *
+ * Access rules reference operation params with the bare `params.X` form (no
+ * `$` prefix), unlike `definition`, which uses `$params.X` (scanned by
+ * {@link collectParamRefs}). This helper feeds the operation's `access` CEL
+ * and each per-param `access` CEL into the "referenced" set so a param used
+ * only by an access rule is not wrongly flagged "declared but not referenced".
+ *
+ * Supported forms, all whitespace-tolerant:
+ *   - dot notation:     `params.claimedUserId`, `params . claimedUserId`
+ *   - dot path:         `params.config.subField` → first segment `config`
+ *   - bracket notation: `params["claimedUserId"]`, `params['claimedUserId']`
+ *
+ * Word-boundary guard: a `params` preceded by an identifier char, `$`, or `.`
+ * is NOT a match, so `$params.x` (definition syntax), `myparams.x`, and a
+ * dotted member access like `database.metadata.params.userId` are ignored —
+ * `params` only counts as the params root when it's a standalone root
+ * identifier. To avoid counting a `params.` that merely appears inside a quoted
+ * string literal (e.g. `note == "see params.docs"`), bracket keys are scanned
+ * first (they legitimately contain quotes), then string literals are stripped
+ * before the dot-notation scan.
+ *
+ * Purely additive: this only grows the referenced set, loosening the soft
+ * warning. The blocking `$params` error path is untouched.
+ */
+export function collectCelParamRefs(cel) {
+    if (typeof cel !== "string" || cel.length === 0)
+        return [];
+    const refs = [];
+    // Bracket notation: params["X"] / params['X']. Run before stripping string
+    // literals so the quoted key survives.
+    const bracketRe = /(?<![\w$.])params\s*\[\s*["']([^"']+)["']\s*\]/g;
+    let m;
+    while ((m = bracketRe.exec(cel)) !== null) {
+        const first = m[1].split(/[.\[]/)[0];
+        if (first)
+            refs.push(first);
+    }
+    // Drop string literals so `params.` inside a quoted string is not counted.
+    const withoutStrings = cel.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, "");
+    // Dot notation: params.X (first segment only, mirroring collectParamRefs).
+    const dotRe = /(?<![\w$.])params\s*\.\s*([A-Za-z_$][\w$]*)/g;
+    while ((m = dotRe.exec(withoutStrings)) !== null) {
+        refs.push(m[1]);
+    }
+    return refs;
+}
+/**
+ * Collect the per-param `access` CEL strings from an operation's `params`
+ * value (object, array, or JSON string form). Used by issue #1239 to count
+ * params referenced only inside another param's `access` rule.
+ */
+function collectParamAccessCels(params) {
+    const cels = [];
+    if (params == null)
+        return cels;
+    let value = params;
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return cels;
+        }
+    }
+    if (Array.isArray(value)) {
+        for (const row of value) {
+            if (row && typeof row === "object" && typeof row.access === "string") {
+                cels.push(row.access);
+            }
+        }
+    }
+    else if (typeof value === "object" && value !== null) {
+        for (const entry of Object.values(value)) {
+            if (entry && typeof entry === "object" && typeof entry.access === "string") {
+                cels.push(entry.access);
+            }
+        }
+    }
+    return cels;
+}
+/**
+ * Normalize a `params` value (object, array, or JSON string) into the
+ * set of declared param names.
+ */
+export function declaredParamNames(params) {
+    const names = new Set();
+    if (params == null)
+        return names;
+    let value = params;
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return names;
+        }
+    }
+    if (Array.isArray(value)) {
+        for (const row of value) {
+            if (row && typeof row === "object" && typeof row.name === "string") {
+                names.add(row.name);
+            }
+        }
+    }
+    else if (typeof value === "object" && value !== null) {
+        for (const key of Object.keys(value)) {
+            names.add(key);
+        }
+    }
+    return names;
+}
+/**
+ * Find the 1-indexed line number in `rawToml` where the `[[operations]]`
+ * block declaring `opName` starts. Returns 0 if not found.
+ *
+ * Implementation: walk in source order, track the most recent
+ * `[[operations]]` header, and when we see a `name = "<opName>"` line
+ * before the next `[[operations]]` or top-level header, return that
+ * header's line.
+ */
+export function locateOperationLine(rawToml, opName) {
+    const lines = rawToml.split(/\r?\n/);
+    let lastOpHeader = 0;
+    let armed = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line === "[[operations]]") {
+            lastOpHeader = i + 1;
+            armed = true;
+            continue;
+        }
+        if (!armed)
+            continue;
+        // Another array-of-tables / top-level table → not this op anymore.
+        if (line.startsWith("[[") && line !== "[[operations]]" && !line.startsWith("[[operations.")) {
+            armed = false;
+            continue;
+        }
+        if (line.startsWith("[") && !line.startsWith("[[") && !line.startsWith("[operations.")) {
+            armed = false;
+            continue;
+        }
+        const m = line.match(/^name\s*=\s*["'](.+)["']\s*$/);
+        if (m && m[1] === opName) {
+            return lastOpHeader;
+        }
+    }
+    return 0;
+}
+/**
+ * Validate `$params` references across every operation in a parsed
+ * database-type config.
+ *
+ * Errors (blocking):
+ *   - A `$params.X` reference inside `definition` where `X` is not
+ *     declared in `[[operations.params]]`.
+ *
+ * Warnings (soft, not blocking):
+ *   - A param declared in `[[operations.params]]` that is not referenced
+ *     anywhere in `definition`. Authors may be staging a deprecation.
+ */
+export function validateOperations(opts) {
+    const errors = [];
+    const warnings = [];
+    for (const op of opts.operations) {
+        if (!op || !op.name)
+            continue;
+        const declared = declaredParamNames(op.params);
+        // `definitionRefs` drives the BLOCKING error loop and must stay limited to
+        // `$params.X` references inside `definition` — access CEL refs are NOT
+        // declarations, so they must never produce an "undeclared" error.
+        const definitionRefs = new Set(collectParamRefs(op.definition));
+        // Issue #1239: a param referenced only by an access CEL rule (bare
+        // `params.X`) is still referenced. The "declared but not referenced"
+        // warning uses a wider set that also counts the operation-level `access`
+        // and each per-param `access` CEL. Purely additive — the blocking error
+        // path below is built only from `definitionRefs`.
+        const referenced = new Set(definitionRefs);
+        for (const ref of collectCelParamRefs(op.access))
+            referenced.add(ref);
+        for (const cel of collectParamAccessCels(op.params)) {
+            for (const ref of collectCelParamRefs(cel))
+                referenced.add(ref);
+        }
+        const line = locateOperationLine(opts.rawToml, op.name);
+        for (const ref of definitionRefs) {
+            if (!declared.has(ref)) {
+                errors.push({
+                    file: opts.filePath,
+                    line,
+                    op: op.name,
+                    message: `$params.${ref} not declared in [[operations.params]] for operation '${op.name}'`,
+                });
+            }
+        }
+        for (const name of declared) {
+            if (!referenced.has(name)) {
+                warnings.push({
+                    file: opts.filePath,
+                    line,
+                    op: op.name,
+                    message: `param '${name}' declared but not referenced in operation '${op.name}'`,
+                });
+            }
+        }
+        // Issue #1255 (Fork 4): warn on unknown filter operators. The server only
+        // checks that `filter` is an object at push time, so a typo like
+        // `$gt` → `$gte` or an invented `$foo` slips through and throws
+        // `InvalidOperatorError` only at query execution. We warn (not error) to
+        // avoid CLI/server divergence — the operator set could drift, and the
+        // server stays authoritative.
+        const filter = op.definition && typeof op.definition === "object"
+            ? op.definition.filter
+            : undefined;
+        for (const badOp of collectUnknownOperators(filter)) {
+            warnings.push({
+                file: opts.filePath,
+                line,
+                op: op.name,
+                message: `unknown filter operator '${badOp}' in operation '${op.name}' — not a recognized query operator; it will fail at query execution`,
+            });
+        }
+    }
+    return { errors, warnings };
+}
+/**
+ * Format a validation issue as `<file>:<line>: <message>`.
+ */
+export function formatIssue(issue) {
+    if (issue.line > 0) {
+        return `${issue.file}:${issue.line}: ${issue.message}`;
+    }
+    return `${issue.file}: ${issue.message}`;
+}
+//# sourceMappingURL=toml-params-validator.js.map

package/dist/src/lib/toml-params-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toml-params-validator.js","sourceRoot":"","sources":["../../../src/lib/toml-params-validator.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/version-check.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Checks if a newer version of the CLI is available on npm.
+ *
+ * - Stable versions (e.g. "1.0.22") check the "latest" dist-tag
+ * - Prerelease versions (e.g. "1.0.23-alpha.3") check their channel's
+ *   dist-tag (e.g. "alpha"), falling back to "latest" if that tag doesn't exist
+ *
+ * Caches results per dist-tag for 4 hours. Fails silently on any error.
+ */
+export declare function checkForUpdate(currentVersion: string): Promise<void>;

package/dist/src/lib/version-check.js

@@ -0,0 +1,172 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import chalk from "chalk";
+const CONFIG_DIR = process.env.PRIMITIVE_CONFIG_DIR || join(homedir(), ".primitive");
+const VERSION_CHECK_FILE = join(CONFIG_DIR, "version-check.json");
+// Cache the result for 4 hours — short enough that users see new
+// releases the same day they drop, long enough that chatty commands
+// (sync push, tests in loops, etc.) don't hammer the npm registry.
+const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000;
+const NPM_PACKAGE_NAME = "primitive-admin";
+const FETCH_TIMEOUT_MS = 3000;
+function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+function loadCache() {
+    try {
+        if (!existsSync(VERSION_CHECK_FILE))
+            return {};
+        return JSON.parse(readFileSync(VERSION_CHECK_FILE, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function saveCache(cache) {
+    try {
+        ensureConfigDir();
+        writeFileSync(VERSION_CHECK_FILE, JSON.stringify(cache, null, 2));
+    }
+    catch {
+        // Ignore write errors
+    }
+}
+/**
+ * Extracts the prerelease channel from a version string.
+ * "1.0.23-alpha.3" → "alpha"
+ * "1.0.23-beta.1"  → "beta"
+ * "1.0.23"         → null
+ */
+function getPrereleaseChannel(version) {
+    const match = version.match(/^[^-]+-([a-zA-Z]+)/);
+    return match ? match[1] : null;
+}
+/**
+ * Compares two semver version strings, including prerelease handling.
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ *
+ * Prerelease versions are only compared against their own channel.
+ * Within the same channel, prerelease segments are compared numerically.
+ */
+function compareVersions(a, b) {
+    const clean = (v) => v.replace(/^v/, "");
+    const cleanA = clean(a);
+    const cleanB = clean(b);
+    // Split into core and prerelease
+    const [coreA, preA] = cleanA.split("-", 2);
+    const [coreB, preB] = cleanB.split("-", 2);
+    // Compare core version (major.minor.patch)
+    const partsA = coreA.split(".").map(Number);
+    const partsB = coreB.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const ca = partsA[i] || 0;
+        const cb = partsB[i] || 0;
+        if (ca < cb)
+            return -1;
+        if (ca > cb)
+            return 1;
+    }
+    // Core versions are equal — compare prerelease
+    // No prerelease on either → equal
+    if (!preA && !preB)
+        return 0;
+    // A prerelease version is always less than the release version
+    if (preA && !preB)
+        return -1;
+    if (!preA && preB)
+        return 1;
+    // Both have prerelease — compare segments (e.g. "alpha.3" vs "alpha.5")
+    const segsA = preA.split(".");
+    const segsB = preB.split(".");
+    const len = Math.max(segsA.length, segsB.length);
+    for (let i = 0; i < len; i++) {
+        const sa = segsA[i];
+        const sb = segsB[i];
+        if (sa === undefined)
+            return -1;
+        if (sb === undefined)
+            return 1;
+        const na = Number(sa);
+        const nb = Number(sb);
+        const aIsNum = !isNaN(na);
+        const bIsNum = !isNaN(nb);
+        if (aIsNum && bIsNum) {
+            if (na < nb)
+                return -1;
+            if (na > nb)
+                return 1;
+        }
+        else {
+            // Lexicographic comparison for non-numeric segments
+            if (sa < sb)
+                return -1;
+            if (sa > sb)
+                return 1;
+        }
+    }
+    return 0;
+}
+async function fetchLatestVersion(distTag) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/${distTag}`, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (!response.ok)
+            return null;
+        const data = await response.json();
+        return data.version;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Checks if a newer version of the CLI is available on npm.
+ *
+ * - Stable versions (e.g. "1.0.22") check the "latest" dist-tag
+ * - Prerelease versions (e.g. "1.0.23-alpha.3") check their channel's
+ *   dist-tag (e.g. "alpha"), falling back to "latest" if that tag doesn't exist
+ *
+ * Caches results per dist-tag for 4 hours. Fails silently on any error.
+ */
+export async function checkForUpdate(currentVersion) {
+    try {
+        const channel = getPrereleaseChannel(currentVersion);
+        const distTag = channel || "latest";
+        const cache = loadCache();
+        const now = Date.now();
+        let latestVersion = null;
+        const cached = cache[distTag];
+        if (cached && (now - cached.lastCheck) < CHECK_INTERVAL_MS) {
+            latestVersion = cached.latestVersion;
+        }
+        else {
+            latestVersion = await fetchLatestVersion(distTag);
+            // If the prerelease dist-tag doesn't exist on npm, fall back to "latest"
+            // so alpha users still hear about new stable releases
+            if (!latestVersion && channel) {
+                latestVersion = await fetchLatestVersion("latest");
+            }
+            if (latestVersion) {
+                cache[distTag] = { lastCheck: now, latestVersion };
+                saveCache(cache);
+            }
+        }
+        if (latestVersion && compareVersions(currentVersion, latestVersion) < 0) {
+            const installCmd = channel
+                ? `npm i -g ${NPM_PACKAGE_NAME}@${channel}`
+                : `npm i -g ${NPM_PACKAGE_NAME}`;
+            console.error();
+            console.error(chalk.yellow(`Update available: ${chalk.dim(currentVersion)} -> ${chalk.green.bold(latestVersion)}`));
+            console.error(chalk.yellow(`Run ${chalk.cyan.bold(installCmd)} to update`));
+        }
+    }
+    catch {
+        // Never let version check errors affect CLI operation
+    }
+}
+//# sourceMappingURL=version-check.js.map

package/dist/src/lib/version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../../src/lib/version-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;AACrF,MAAM,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC;AAClE,iEAAiE;AACjE,oEAAoE;AACpE,mEAAmE;AACnE,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAC7C,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAC3C,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAU9B,SAAS,eAAe;IACtB,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,SAAS,SAAS;IAChB,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC;YAAE,OAAO,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,KAAwB;IACzC,IAAI,CAAC;QACH,eAAe,EAAE,CAAC;QAClB,aAAa,CAAC,kBAAkB,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,OAAe;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,CAAS,EAAE,CAAS;IAC3C,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAExB,iCAAiC;IACjC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC3C,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAE3C,2CAA2C;IAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAE5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,CAAC,CAAC;QACvB,IAAI,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,CAAC;IACxB,CAAC;IAED,+CAA+C;IAC/C,kCAAkC;IAClC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IAC7B,+DAA+D;IAC/D,IAAI,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC;IAE5B,wEAAwE;IACxE,MAAM,KAAK,GAAG,IAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAEjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC,CAAC;QAChC,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC;QAE/B,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;QACtB,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;QACtB,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAE1B,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;YACrB,IAAI,EAAE,GAAG,EAAE;gBAAE,OAAO,CAAC,CAAC,CAAC;YACvB,IAAI,EAAE,GAAG,EAAE;gBAAE,OAAO,CAAC,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,oDAAoD;YACpD,IAAI,EAAE,GAAG,EAAE;gBAAE,OAAO,CAAC,CAAC,CAAC;YACvB,IAAI,EAAE,GAAG,EAAE;gBAAE,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,OAAe;IAC/C,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAC;QAEvE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAC1B,8BAA8B,gBAAgB,IAAI,OAAO,EAAE,EAC3D,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAC9B,CAAC;QACF,YAAY,CAAC,OAAO,CAAC,CAAC;QAEtB,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAC9B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAyB,CAAC;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,cAAsB;IACzD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,oBAAoB,CAAC,cAAc,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,OAAO,IAAI,QAAQ,CAAC;QACpC,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,aAAa,GAAkB,IAAI,CAAC;QACxC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAE9B,IAAI,MAAM,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,iBAAiB,EAAE,CAAC;YAC3D,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;QACvC,CAAC;aAAM,CAAC;YACN,aAAa,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;YAElD,yEAAyE;YACzE,sDAAsD;YACtD,IAAI,CAAC,aAAa,IAAI,OAAO,EAAE,CAAC;gBAC9B,aAAa,GAAG,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YACrD,CAAC;YAED,IAAI,aAAa,EAAE,CAAC;gBAClB,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC;gBACnD,SAAS,CAAC,KAAK,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QAED,IAAI,aAAa,IAAI,eAAe,CAAC,cAAc,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;YACxE,MAAM,UAAU,GAAG,OAAO;gBACxB,CAAC,CAAC,YAAY,gBAAgB,IAAI,OAAO,EAAE;gBAC3C,CAAC,CAAC,YAAY,gBAAgB,EAAE,CAAC;YAEnC,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,qBAAqB,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC;YACpH,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sDAAsD;IACxD,CAAC;AACH,CAAC"}

package/dist/src/lib/workflow-apply.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared "apply a TOML body to an existing workflow" helper.
+ *
+ * Extracted from the `sync push` update-existing path (#1249, Fork 4) so that
+ * both `sync push` and `workflows update --from-file` push a revised body the
+ * same way. A second inlined copy would regress #807: the update is
+ * ordering-sensitive and a naive metadata-then-body sequence rejects valid
+ * sync-callable edits.
+ *
+ * Ordering invariant (#807 / codex review):
+ *   1. metadata PATCH — WITHOUT `syncCallable`. The server re-validates
+ *      `syncCallable: true` against the workflow's CURRENTLY-active server
+ *      steps (`loadCurrentActiveSteps`, src/admin-api.ts:4734), not the steps
+ *      being pushed in the same call. So enabling sync-callable in the first
+ *      PATCH would validate against the stale active steps and be rejected.
+ *   2. body write — steps to the active config (config-model) or the legacy
+ *      draft slot (no active config).
+ *   3. a SECOND `syncCallable` PATCH — issued AFTER the new steps are active,
+ *      so it validates against the new (compatible) steps.
+ */
+import type { ApiClient } from "./api-client.js";
+/**
+ * Safely parse a JSON field that may be a string or already an object. TOML can
+ * parse inline tables as objects, so we accept both. (Same semantics as the
+ * `safeJsonParse` in sync.ts — kept here so the shared apply helper owns its
+ * own parse decision without importing back into a command module.)
+ */
+export declare function safeJsonParse(value: any): any;
+export interface ApplyWorkflowBodyOptions {
+    /** Optimistic-concurrency guard for the metadata + syncCallable PATCHes. */
+    expectedModifiedAt?: string;
+    /**
+     * Active config to overwrite in place (config-model workflows). When absent,
+     * the body falls back to the legacy draft slot — non-live for config-model
+     * workflows, which the server rejects with 409 WORKFLOW_CONFIG_MODEL.
+     */
+    activeConfigId?: string;
+    /** When true, skip the optimistic-concurrency check (mirrors `--force`). */
+    force?: boolean;
+}
+export interface ApplyWorkflowBodyResult {
+    /** The freshest workflow `modifiedAt` after all PATCHes (for sync state). */
+    latestModifiedAt?: string;
+    /** Which slot the steps landed in: "active config" or "draft (legacy)". */
+    updateSlotLabel: string;
+    /** A fresh `getWorkflow` result so callers can read back configs/state. */
+    fullWorkflow: any;
+}
+/**
+ * Apply a parsed workflow body (metadata + steps) to an existing workflow,
+ * preserving the key/id. `workflow` is the TOML's `[workflow]` table (already
+ * merged with any explicit CLI flag overrides by the caller); `steps` is the
+ * TOML's `steps` array. The function performs the three-step ordered update
+ * and returns the latest `modifiedAt`, the slot label, and a fresh workflow.
+ */
+export declare function applyWorkflowBody(client: ApiClient, appId: string, workflowId: string, workflow: any, steps: any[], opts?: ApplyWorkflowBodyOptions): Promise<ApplyWorkflowBodyResult>;
+/**
+ * Fork 2 (#1249): a TOML pushed at a specific `<id>` may also declare a `key` /
+ * `workflowKey`. If it differs from the target's actual key, that's almost
+ * certainly the wrong file — error rather than silently ignoring it. An absent
+ * TOML key is advisory and allowed (the operation targets `<id>`).
+ *
+ * Returns an error message string when there is a mismatch, otherwise null.
+ * Pure function for unit testing.
+ */
+export declare function workflowKeyMismatchError(tomlWorkflow: any, existingWorkflowKey: string | undefined): string | null;