primitive-admin 1.0.60 → 1.0.62

package/dist/src/lib/workflow-fragments.js

@@ -14,6 +14,29 @@
  *   - Unique step ids validated post-expansion; collisions name both
  *     locations in the error message.
  *
+ * Parameterized includes (#1448):
+ *   - Two include forms are supported. The bare form
+ *     `include = ["name", ...]` (an array of fragment-name strings) is
+ *     unchanged. The parameterized form uses `[[include]]` array-of-tables:
+ *
+ *       [[include]]
+ *       fragment = "lifecycle-email"          # required
+ *       runIf = "input.type == 'x'"           # optional; ANDed onto each step
+ *       with = { id = "...", subject = "..." } # params, exposed as {{ params.* }}
+ *
+ *   - A file uses one form or the other — mixing string and table entries in a
+ *     single `include` array is an error.
+ *   - `{{ params.* }}` references inside the fragment's steps are substituted
+ *     at EXPAND time from the include's `with` table. A whole-string
+ *     `{{ params.x }}` splices the raw typed value (number/bool/table);
+ *     an embedded `{{ params.x }}` inside a larger string stringifies it.
+ *     A missing param is a hard error. Only the `params.` namespace is
+ *     touched — every other `{{ ... }}` template passes through to the server
+ *     verbatim, and `params.` never survives into the expanded output.
+ *   - The include-level `runIf` (CEL) is ANDed onto every expanded step:
+ *     both present → `(<includeRunIf>) && (<stepRunIf>)`; one present → that
+ *     one; neither → no runIf.
+ *
  * Wiring: `parseTomlFile()` in `cli/src/commands/sync.ts` calls
  * `expandWorkflowTomlData()` after parsing. All 24 push parse sites in
  * sync.ts route through that single seam, so the expansion is uniform.
@@ -23,6 +46,22 @@
 import { existsSync, readFileSync } from "fs";
 import { dirname, join, basename } from "path";
 import { parseConfigToml } from "./config-toml.js";
+/**
+ * True only for a genuine plain TOML table: a non-null, non-array object whose
+ * prototype is `Object.prototype` or `null`. This deliberately rejects the
+ * non-plain objects that a bare `typeof x === "object"` check would accept —
+ * notably smol-toml's `TomlDate` (a `Date` subclass) and any other boxed value
+ * — so a TOML date/time literal (`with = 1979-05-27T07:32:00Z`) can never slip
+ * through a guard that expects a parameter table. Used everywhere a `with` /
+ * params sub-table is required so the plain-table rule is applied consistently.
+ */
+function isPlainTable(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 /**
  * Read and expand a workflow TOML file from disk. Returns the parsed
  * TOML with all `include` fragments spliced in. If the file has no
@@ -58,16 +97,35 @@ export function expandWorkflowTomlData(parsed, workflowPath) {
         ? parsed.steps
         : [];
     const allOriginated = [];
-    for (const fragmentName of includeList) {
-        if (typeof fragmentName !== "string" || fragmentName.length === 0) {
-            throw new Error(`Workflow '${workflowPath}' has an invalid include entry: ${JSON.stringify(fragmentName)}. Each entry must be a fragment name string.`);
+    // Classify each entry as a bare fragment-name string or a parameterized
+    // `[[include]]` table. A single file must use one form throughout. A
+    // `[[include]]` entry must be a genuine plain table — a non-plain object
+    // (e.g. a TOML date literal parsed to a `TomlDate`) is neither a valid
+    // string entry nor a valid table and falls through to the per-entry error.
+    const isTable = (e) => isPlainTable(e);
+    const hasStringEntry = includeList.some((e) => typeof e === "string");
+    const hasTableEntry = includeList.some((e) => isTable(e));
+    if (hasStringEntry && hasTableEntry) {
+        throw new Error(`Workflow '${workflowPath}' mixes bare-string include entries and [[include]] tables in one 'include' array. Pick one form per file: either \`include = ["a", "b"]\` or repeated \`[[include]]\` tables.`);
+    }
+    includeList.forEach((entry, index) => {
+        if (typeof entry === "string") {
+            if (entry.length === 0) {
+                throw new Error(`Workflow '${workflowPath}' has an invalid include entry: ${JSON.stringify(entry)}. Each entry must be a fragment name string.`);
+            }
+            const fragmentPath = join(fragmentsDir, `${entry}.toml`);
+            const fragment = readFragmentSafely(fragmentPath, workflowPath, entry);
+            for (const step of fragment.steps) {
+                allOriginated.push({ step, origin: `fragment '${entry}'` });
+            }
+            return;
         }
-        const fragmentPath = join(fragmentsDir, `${fragmentName}.toml`);
-        const fragment = readFragmentSafely(fragmentPath, workflowPath, fragmentName);
-        for (const step of fragment.steps) {
-            allOriginated.push({ step, origin: `fragment '${fragmentName}'` });
+        if (isTable(entry)) {
+            expandParameterizedInclude(entry, index, fragmentsDir, workflowPath, allOriginated);
+            return;
         }
-    }
+        throw new Error(`Workflow '${workflowPath}' has an invalid include entry: ${JSON.stringify(entry)}. Each entry must be a fragment name string or a [[include]] table.`);
+    });
     for (const step of workflowOwnSteps) {
         allOriginated.push({ step, origin: `workflow '${basename(workflowPath)}'` });
     }
@@ -103,6 +161,169 @@ function readFragmentSafely(fragmentPath, workflowPath, fragmentName) {
         : [];
     return { steps };
 }
+// ── Parameterized include expansion (#1448) ─────────────────────────────────
+const ALLOWED_INCLUDE_KEYS = new Set(["fragment", "runIf", "with"]);
+// The dotted path after `params.`. Each segment is a TOML bare key, which may
+// contain letters, digits, `_` and `-`; segments are joined by dots. Keeping
+// the full bare-key charset means hyphenated keys like `subject-line` expand
+// instead of leaking `{{ params.subject-line }}` to the server.
+const PARAM_PATH = "[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*";
+// A string that is EXACTLY one `{{ params.<path> }}` token (raw typed splice).
+const WHOLE_PARAM_RE = new RegExp(`^\\{\\{\\s*params\\.(${PARAM_PATH})\\s*\\}\\}$`);
+// Any embedded `{{ params.<path> }}` token (string interpolation).
+const EMBEDDED_PARAM_RE = new RegExp(`\\{\\{\\s*params\\.(${PARAM_PATH})\\s*\\}\\}`, "g");
+function expandParameterizedInclude(entry, index, fragmentsDir, workflowPath, allOriginated) {
+    const includeLabel = `[[include]] #${index + 1}`;
+    for (const key of Object.keys(entry)) {
+        if (!ALLOWED_INCLUDE_KEYS.has(key)) {
+            throw new Error(`Workflow '${workflowPath}' has an unknown key '${key}' in ${includeLabel}. Allowed keys are: fragment, runIf, with.`);
+        }
+    }
+    const fragmentName = entry.fragment;
+    if (typeof fragmentName !== "string" || fragmentName.length === 0) {
+        throw new Error(`Workflow '${workflowPath}' has a ${includeLabel} missing a valid 'fragment' name (got ${JSON.stringify(fragmentName)}).`);
+    }
+    const includeRunIf = entry.runIf;
+    if (includeRunIf !== undefined && typeof includeRunIf !== "string") {
+        throw new Error(`Workflow '${workflowPath}' has a non-string 'runIf' in ${includeLabel} (fragment '${fragmentName}'). runIf must be a CEL string.`);
+    }
+    const withParams = entry.with;
+    // `with` must be a genuine plain table. `isPlainTable` rejects arrays and any
+    // non-plain object — including a TOML date/time literal (`with = 1979-…Z`),
+    // which parses to a `TomlDate` and would otherwise be accepted as a param
+    // table by a bare `typeof === "object"` check.
+    if (withParams !== undefined && !isPlainTable(withParams)) {
+        throw new Error(`Workflow '${workflowPath}' has a non-table 'with' in ${includeLabel} (fragment '${fragmentName}'). 'with' must be a table of parameters.`);
+    }
+    const params = withParams ?? {};
+    const fragmentPath = join(fragmentsDir, `${fragmentName}.toml`);
+    const fragment = readFragmentSafely(fragmentPath, workflowPath, fragmentName);
+    const ctx = {
+        fragment: fragmentName,
+        includeLabel,
+        workflowPath,
+    };
+    for (const rawStep of fragment.steps) {
+        const step = substituteParamsDeep(rawStep, params, ctx);
+        applyIncludeRunIf(step, includeRunIf, ctx);
+        allOriginated.push({
+            step,
+            origin: `fragment '${fragmentName}' (${includeLabel})`,
+        });
+    }
+}
+/**
+ * Recursively substitute `{{ params.* }}` references throughout a fragment
+ * step. Returns a new value; the input is not mutated. Only the `params.`
+ * namespace is touched — every other `{{ ... }}` template is preserved
+ * verbatim for the server to render.
+ */
+function substituteParamsDeep(node, params, ctx) {
+    if (typeof node === "string") {
+        return substituteParamsInString(node, params, ctx);
+    }
+    if (Array.isArray(node)) {
+        return node.map((el) => substituteParamsDeep(el, params, ctx));
+    }
+    if (node !== null && typeof node === "object") {
+        // Only recurse into plain tables. Non-plain objects (e.g. smol-toml's
+        // `TomlDate`, which extends `Date`) carry internal state that is not
+        // enumerable, so rebuilding them via `Object.entries` would collapse them
+        // to `{}`. TOML date/time literals can only appear as leaf param values —
+        // there is nothing to substitute inside them — so pass them through
+        // unchanged.
+        const proto = Object.getPrototypeOf(node);
+        if (proto !== Object.prototype && proto !== null) {
+            return node;
+        }
+        // Clone into a null-prototype object so a legal TOML key that collides with
+        // a prototype member — `__proto__`, `constructor`, `prototype` — is written
+        // as an ordinary own data property instead of tripping the `__proto__`
+        // setter (which would drop the field or reparent the clone). `Object.entries`
+        // reads only own enumerable keys, so no inherited members leak in either.
+        const out = Object.create(null);
+        for (const [k, v] of Object.entries(node)) {
+            out[k] = substituteParamsDeep(v, params, ctx);
+        }
+        return out;
+    }
+    return node;
+}
+function substituteParamsInString(value, params, ctx) {
+    // Whole-string `{{ params.x }}` → splice the raw typed value.
+    const whole = value.match(WHOLE_PARAM_RE);
+    if (whole) {
+        return resolveParamPath(whole[1], params, ctx);
+    }
+    // Embedded `{{ params.x }}` → stringify the resolved value in place.
+    return value.replace(EMBEDDED_PARAM_RE, (_match, path) => stringifyParamValue(resolveParamPath(path, params, ctx)));
+}
+/**
+ * Resolve a dotted `params.<path>` reference against the include's `with`
+ * table. A missing key (or missing sub-path) is a hard error naming the
+ * fragment, the param, and the include.
+ */
+function resolveParamPath(path, params, ctx) {
+    const segments = path.split(".");
+    let cursor = params;
+    for (const segment of segments) {
+        // Resolve only OWN properties at each segment. Using `in` here would walk
+        // the prototype chain, so `{{ params.constructor }}`, `{{ params.toString }}`,
+        // `{{ params.__proto__ }}`, or `{{ params.hasOwnProperty }}` would resolve
+        // an inherited `Object.prototype` member instead of hard-erroring like any
+        // other missing param. `Object.hasOwn` restricts the lookup to real,
+        // author-declared keys.
+        if (cursor === null ||
+            typeof cursor !== "object" ||
+            Array.isArray(cursor) ||
+            !Object.hasOwn(cursor, segment)) {
+            throw new Error(`Fragment '${ctx.fragment}' references '{{ params.${path} }}' but no matching key exists in the ${ctx.includeLabel} 'with' table (workflow '${ctx.workflowPath}').`);
+        }
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+function stringifyParamValue(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+/**
+ * AND the include-level `runIf` onto a step's own `runIf`. Each operand is
+ * paren-wrapped because CEL's `&&` binds tighter than `||`. Mutates `step`.
+ */
+function applyIncludeRunIf(step, includeRunIf, ctx) {
+    // A non-string step `runIf` (e.g. `runIf = 123`, or a param that spliced a
+    // non-string value in) must hard-error, consistent with the include-level
+    // non-string `runIf` rejection. Otherwise it would fall through the
+    // string-only guard below and be silently dropped, turning a guarded step
+    // into an unconditional one.
+    if ("runIf" in step &&
+        step.runIf !== undefined &&
+        typeof step.runIf !== "string") {
+        throw new Error(`Fragment '${ctx.fragment}' produced a non-string 'runIf' (got ${JSON.stringify(step.runIf)}) in ${ctx.includeLabel} (workflow '${ctx.workflowPath}'). runIf must be a CEL string.`);
+    }
+    const include = typeof includeRunIf === "string" && includeRunIf.length > 0
+        ? includeRunIf
+        : undefined;
+    const own = typeof step.runIf === "string" && step.runIf.length > 0
+        ? step.runIf
+        : undefined;
+    let combined;
+    if (include && own)
+        combined = `(${include}) && (${own})`;
+    else
+        combined = include ?? own;
+    if (combined === undefined) {
+        if ("runIf" in step)
+            delete step.runIf;
+    }
+    else {
+        step.runIf = combined;
+    }
+}
 function assertUniqueStepIds(originated, workflowPath) {
     const seen = new Map();
     for (const { step, origin } of originated) {

package/dist/src/lib/workflow-fragments.js.map

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

package/dist/src/lib/workflow-include-preserve.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Keep `[[include]]` fragment structure alive across `config pull` (issue #2416).
+ *
+ * Fragments are a CLI-only authoring form: `expandWorkflowTomlData()` splices
+ * the referenced fragments into a flat `[[steps]]` list and the server only
+ * ever stores that expansion (see `workflow-fragments.ts`). `config pull`
+ * serializes the server's flat steps straight back to disk, so before this
+ * module a pull unconditionally overwrote a fragment-authored file with its
+ * own expansion — the `[[include]]` blocks were gone and had to be rebuilt by
+ * hand, even when `config diff` reported the file as synced.
+ *
+ * `reconcileWorkflowIncludes()` decides what pull should write for one
+ * workflow file. It only ever engages for a local file that actually carries
+ * an `include` key; everything else takes the unchanged "write what the server
+ * gave us" path.
+ *
+ *   - **skip** — the local file expands to exactly what the server is running.
+ *     There is nothing to apply, so leave the fragment source (and its
+ *     comments and formatting) untouched. One thing still has to be applied to
+ *     an otherwise-unchanged file: a retired inline `[[configs]]` list (#2733).
+ *     Pull rewrites every other workflow file off it, and push rejects a file
+ *     that still carries one, so a plain skip left the fragment source in a
+ *     shape push refuses — pull → push of an untouched tree failed. Such a
+ *     file takes the write-merged path with only the list removed.
+ *   - **write-merged** — the server drifted, but its step list still *starts*
+ *     with exactly the steps the local includes expand to. The drift is
+ *     therefore expressible in fragment form: re-emit the file with the
+ *     original `[[include]]` blocks and put the remaining server steps in the
+ *     workflow's own `[[steps]]` list. Re-expanding that file reproduces the
+ *     server's step list in order, so the next `config diff` reads as synced.
+ *   - **write-expanded** — the fragment-derived prefix no longer matches what
+ *     the server is running (a fragment's steps were edited or removed
+ *     server-side), so no fragment-preserving file could reproduce it. Fall
+ *     back to the historical behavior — write the fully expanded form — and
+ *     say why, so the operator knows the fragment source was replaced rather
+ *     than silently losing it.
+ *
+ * The order rule comes from the expander: it emits every fragment's steps
+ * first (in `include` order) and then the workflow's own `[[steps]]`. So a
+ * fragment-preserving file can only represent a server step list whose leading
+ * steps are exactly the fragment expansion. Server steps inserted *between*
+ * fragment steps are not representable and take the write-expanded path.
+ */
+/**
+ * Hashes an already-parsed (and, for a local file, already-expanded) workflow
+ * TOML object to its canonical content hash. Injected by the caller so this
+ * module uses exactly the same normalization `config diff` does
+ * (`hashWorkflowTomlForDiff` in `commands/sync.ts`) without importing the
+ * command module back into `lib/`.
+ */
+export type WorkflowTomlHasher = (parsed: any) => string;
+export interface IncludeReconcileOutcome {
+    /**
+     * `write-expanded`: write the server's serialized TOML unchanged (the
+     * pre-#2416 behavior). `skip`: leave the local file alone. `write-merged`:
+     * write `content`, which preserves the local `[[include]]` blocks.
+     */
+    action: "write-expanded" | "skip" | "write-merged";
+    /** TOML to write. Only set when `action` is `write-merged`. */
+    content?: string;
+    /** Human-readable note for the pull log. Absent when there's nothing to say. */
+    message?: string;
+}
+export interface ReconcileWorkflowIncludesOptions {
+    /** Workflow key, used only for log messages. */
+    workflowKey: string;
+    /** Absolute path of the local workflow TOML (also resolves the fragments dir). */
+    localPath: string;
+    /** Current contents of that file, or `undefined` when it doesn't exist yet. */
+    localContent: string | undefined;
+    /** The TOML `config pull` would write, from `serializeWorkflow()`. */
+    remoteToml: string;
+    /** Canonical content hash for a parsed workflow TOML. */
+    hashParsedToml: WorkflowTomlHasher;
+}
+export declare function reconcileWorkflowIncludes(options: ReconcileWorkflowIncludesOptions): IncludeReconcileOutcome;

package/dist/src/lib/workflow-include-preserve.js

@@ -0,0 +1,286 @@
+/**
+ * Keep `[[include]]` fragment structure alive across `config pull` (issue #2416).
+ *
+ * Fragments are a CLI-only authoring form: `expandWorkflowTomlData()` splices
+ * the referenced fragments into a flat `[[steps]]` list and the server only
+ * ever stores that expansion (see `workflow-fragments.ts`). `config pull`
+ * serializes the server's flat steps straight back to disk, so before this
+ * module a pull unconditionally overwrote a fragment-authored file with its
+ * own expansion — the `[[include]]` blocks were gone and had to be rebuilt by
+ * hand, even when `config diff` reported the file as synced.
+ *
+ * `reconcileWorkflowIncludes()` decides what pull should write for one
+ * workflow file. It only ever engages for a local file that actually carries
+ * an `include` key; everything else takes the unchanged "write what the server
+ * gave us" path.
+ *
+ *   - **skip** — the local file expands to exactly what the server is running.
+ *     There is nothing to apply, so leave the fragment source (and its
+ *     comments and formatting) untouched. One thing still has to be applied to
+ *     an otherwise-unchanged file: a retired inline `[[configs]]` list (#2733).
+ *     Pull rewrites every other workflow file off it, and push rejects a file
+ *     that still carries one, so a plain skip left the fragment source in a
+ *     shape push refuses — pull → push of an untouched tree failed. Such a
+ *     file takes the write-merged path with only the list removed.
+ *   - **write-merged** — the server drifted, but its step list still *starts*
+ *     with exactly the steps the local includes expand to. The drift is
+ *     therefore expressible in fragment form: re-emit the file with the
+ *     original `[[include]]` blocks and put the remaining server steps in the
+ *     workflow's own `[[steps]]` list. Re-expanding that file reproduces the
+ *     server's step list in order, so the next `config diff` reads as synced.
+ *   - **write-expanded** — the fragment-derived prefix no longer matches what
+ *     the server is running (a fragment's steps were edited or removed
+ *     server-side), so no fragment-preserving file could reproduce it. Fall
+ *     back to the historical behavior — write the fully expanded form — and
+ *     say why, so the operator knows the fragment source was replaced rather
+ *     than silently losing it.
+ *
+ * The order rule comes from the expander: it emits every fragment's steps
+ * first (in `include` order) and then the workflow's own `[[steps]]`. So a
+ * fragment-preserving file can only represent a server step list whose leading
+ * steps are exactly the fragment expansion. Server steps inserted *between*
+ * fragment steps are not representable and take the write-expanded path.
+ */
+import { parseConfigToml, stringifyConfigToml } from "./config-toml.js";
+import { expandWorkflowTomlData } from "./workflow-fragments.js";
+import { canonicalJsonStringify } from "./canonical-json.js";
+export function reconcileWorkflowIncludes(options) {
+    const { workflowKey, localPath, localContent, remoteToml, hashParsedToml } = options;
+    const label = `workflows/${workflowKey}.toml`;
+    if (localContent === undefined) {
+        return { action: "write-expanded" };
+    }
+    let localParsed;
+    try {
+        localParsed = parseConfigToml(localContent);
+    }
+    catch {
+        // An unparseable local file carries no structure worth preserving — pull
+        // replaces it, exactly as it did before.
+        return { action: "write-expanded" };
+    }
+    if (localParsed === null ||
+        typeof localParsed !== "object" ||
+        !("include" in localParsed)) {
+        return { action: "write-expanded" };
+    }
+    let expandedLocal;
+    try {
+        expandedLocal = expandWorkflowTomlData(localParsed, localPath);
+    }
+    catch (err) {
+        return {
+            action: "write-expanded",
+            message: `${label}: could not expand its [[include]] fragments ` +
+                `(${err?.message ?? err}); wrote the fully expanded form from the server.`,
+        };
+    }
+    const remoteParsed = parseConfigToml(remoteToml);
+    // Nothing to apply: the fragment source already describes what's running —
+    // except for a retired inline `[[configs]]` list, which pull has to take out
+    // on its way past (#2733).
+    if (hashParsedToml(expandedLocal) === hashParsedToml(remoteParsed)) {
+        if (hasRetiredInlineConfigs(localParsed)) {
+            return {
+                action: "write-merged",
+                content: withoutRetiredInlineConfigs({
+                    localContent,
+                    localParsed,
+                    localPath,
+                    remoteHash: hashParsedToml(remoteParsed),
+                    hashParsedToml,
+                }),
+                message: `${label}: removed the retired [[configs]] list (#2645) and kept ` +
+                    `the local [[include]] fragment source. Named configurations are ` +
+                    `authored one per file at workflows/${workflowKey}.configs/<name>.toml.`,
+            };
+        }
+        return {
+            action: "skip",
+            message: `${label}: unchanged — kept the local [[include]] fragment source.`,
+        };
+    }
+    const ownSteps = Array.isArray(localParsed.steps) ? localParsed.steps : [];
+    const expandedSteps = Array.isArray(expandedLocal.steps)
+        ? expandedLocal.steps
+        : [];
+    const remoteSteps = Array.isArray(remoteParsed.steps)
+        ? remoteParsed.steps
+        : [];
+    const fragmentCount = expandedSteps.length - ownSteps.length;
+    if (fragmentCount < 0) {
+        // Defensive: the expander always emits fragment steps plus own steps.
+        return { action: "write-expanded" };
+    }
+    const mismatch = findFragmentPrefixMismatch(expandedSteps.slice(0, fragmentCount), remoteSteps);
+    if (mismatch) {
+        return {
+            action: "write-expanded",
+            message: `${label}: the running workflow no longer starts with the steps its ` +
+                `[[include]] fragments expand to (${mismatch}), so the fragment ` +
+                `structure can't be preserved. Wrote the fully expanded form — ` +
+                `re-author the includes by hand if you want them back.`,
+        };
+    }
+    const remainingSteps = remoteSteps.slice(fragmentCount);
+    // Rebuild the file from the server's content with the local include blocks
+    // spliced back in. `workflow` first, then `include`, then the steps the
+    // fragments don't cover, then everything else the server serialized
+    // (`configs`, `[expr.cel]`, the declared-access manifest, ...).
+    const data = {};
+    if ("workflow" in remoteParsed) {
+        data.workflow = remoteParsed.workflow;
+    }
+    data.include = localParsed.include;
+    if (remainingSteps.length > 0) {
+        data.steps = remainingSteps;
+    }
+    for (const [key, value] of Object.entries(remoteParsed)) {
+        if (!(key in data) && key !== "steps") {
+            data[key] = value;
+        }
+    }
+    return {
+        action: "write-merged",
+        content: stringifyConfigToml(data),
+        message: `${label}: kept ${fragmentCount} step(s) from [[include]] fragments; ` +
+            `wrote ${remainingSteps.length} server step(s) the fragments don't cover.`,
+    };
+}
+/**
+ * Whether the local file carries the inline `[[configs]]` list #2645 retired.
+ * Matches the push validator's rule exactly (`validateRetiredInlineConfigs` in
+ * `workflow-toml-validator.ts`): a non-empty array at the document root. An
+ * empty one is not rejected by push, so pull has no reason to touch the file
+ * over it.
+ */
+function hasRetiredInlineConfigs(localParsed) {
+    return Array.isArray(localParsed.configs) && localParsed.configs.length > 0;
+}
+/** A `[[configs]]` header line, the only form a retired list can be authored in as a table array. */
+const RETIRED_CONFIGS_HEADER = /^\[\[\s*configs\s*\]\]\s*(#.*)?$/;
+/** `[configs.x]` / `[[configs.x]]` — a subtable of the entry being removed. */
+const RETIRED_CONFIGS_SUBTABLE = /^\[\[?\s*configs\s*\./;
+/**
+ * The local file with its retired `[[configs]]` blocks taken out, preserving
+ * every other byte — comments, key order and formatting included. That matters
+ * here more than anywhere else in this module: the file is otherwise in sync,
+ * so re-emitting it would reformat an operator's hand-authored source for a
+ * change that only deletes a block nothing reads.
+ *
+ * Returns `undefined` when the list is not authored as `[[configs]]` blocks
+ * (an inline `configs = [ … ]` array, say), which the caller handles by
+ * re-emitting the parsed document instead.
+ */
+function stripRetiredInlineConfigsText(content) {
+    const kept = [];
+    /**
+     * Blank and comment lines seen since the last line that definitely belongs to
+     * the block being removed. A comment sitting between the retired list and the
+     * next table almost always documents *that* table, so it is handed back when
+     * the table arrives instead of being deleted with the block; trivia followed
+     * by another config line documented the removed entry and is dropped.
+     */
+    let trivia = [];
+    let removing = false;
+    let removedAny = false;
+    /** Give the pending trivia back, from its first comment line onwards. */
+    const keepTrivia = () => {
+        const firstComment = trivia.findIndex((line) => line.trim().startsWith("#"));
+        // Blank-only trivia is just the separator the removed block left behind.
+        if (firstComment >= 0)
+            kept.push(...trivia.slice(firstComment));
+        trivia = [];
+    };
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (RETIRED_CONFIGS_HEADER.test(trimmed)) {
+            trivia = [];
+            removing = true;
+            removedAny = true;
+            continue;
+        }
+        if (removing) {
+            // The block runs to the next top-level table header; a `configs.*`
+            // subtable belongs to the entry being removed and goes with it.
+            if (RETIRED_CONFIGS_SUBTABLE.test(trimmed)) {
+                trivia = [];
+                continue;
+            }
+            if (!trimmed.startsWith("[")) {
+                if (trimmed === "" || trimmed.startsWith("#"))
+                    trivia.push(line);
+                else
+                    trivia = [];
+                continue;
+            }
+            keepTrivia();
+            removing = false;
+        }
+        kept.push(line);
+    }
+    if (removing)
+        keepTrivia();
+    if (!removedAny)
+        return undefined;
+    const stripped = kept.join("\n");
+    // A block that ran to the end of the file takes the final newline with it.
+    return content.endsWith("\n") && !stripped.endsWith("\n")
+        ? `${stripped}\n`
+        : stripped;
+}
+/**
+ * What pull writes for an in-sync fragment source that still carries the
+ * retired list: the same file minus the `[[configs]]` blocks.
+ *
+ * The textual strip is verified before it is used — the result has to parse,
+ * carry no `configs` any more, and still expand to exactly the server's
+ * content hash. Anything else (an inline-array form, a shape the line scan
+ * misreads) falls back to re-emitting the parsed document without its
+ * `configs` key, which loses comments but is correct by construction.
+ */
+function withoutRetiredInlineConfigs(options) {
+    const { localContent, localParsed, localPath, remoteHash, hashParsedToml } = options;
+    const stripped = stripRetiredInlineConfigsText(localContent);
+    if (stripped !== undefined) {
+        try {
+            const reparsed = parseConfigToml(stripped);
+            if (!hasRetiredInlineConfigs(reparsed) &&
+                hashParsedToml(expandWorkflowTomlData(reparsed, localPath)) ===
+                    remoteHash) {
+                return stripped;
+            }
+        }
+        catch {
+            // Fall through to the re-emit below.
+        }
+    }
+    const { configs: _retired, ...rest } = localParsed;
+    return stringifyConfigToml(rest);
+}
+/**
+ * Returns a human-readable description of the first place the server's step
+ * list departs from the fragment-derived prefix, or `undefined` when the
+ * prefix matches exactly.
+ */
+function findFragmentPrefixMismatch(fragmentSteps, remoteSteps) {
+    if (remoteSteps.length < fragmentSteps.length) {
+        return `the server has ${remoteSteps.length} step(s), fewer than the ${fragmentSteps.length} the fragments produce`;
+    }
+    for (let i = 0; i < fragmentSteps.length; i++) {
+        if (canonicalJsonStringify(fragmentSteps[i]) !==
+            canonicalJsonStringify(remoteSteps[i])) {
+            const expectedId = describeStepId(fragmentSteps[i]);
+            const actualId = describeStepId(remoteSteps[i]);
+            return expectedId === actualId
+                ? `step ${i + 1} '${expectedId}' differs`
+                : `step ${i + 1} is '${actualId}' where the fragments produce '${expectedId}'`;
+        }
+    }
+    return undefined;
+}
+function describeStepId(step) {
+    const id = step?.id;
+    return typeof id === "string" && id.length > 0 ? id : "<no id>";
+}
+//# sourceMappingURL=workflow-include-preserve.js.map