primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

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

@@ -0,0 +1,342 @@
+/**
+ * CLI-only workflow fragment expansion.
+ *
+ * Workflows may declare `include = ["fragment-name", ...]` at the top of
+ * their TOML. The CLI expands those references into a fully-flattened
+ * `[[steps]]` list before push — the server never sees fragments and
+ * stores only the canonical, expanded JSON.
+ *
+ * Pinned decisions (#744):
+ *   - CLI-only. No server-side WorkflowFragment model.
+ *   - Fragments live at <workflowDir>/../workflow-fragments/<name>.toml.
+ *   - Fragment files are `[[steps]]` lists only — no `[workflow]` block.
+ *   - No recursive includes in v1 (fragments cannot themselves `include`).
+ *   - 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.
+ * The standalone `expandWorkflow(filePath)` helper backs the
+ * `primitive workflows expand` subcommand for debugging.
+ */
+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
+ * `include` key, the parsed TOML is returned unchanged.
+ */
+export function expandWorkflow(workflowPath) {
+    const content = readFileSync(workflowPath, "utf-8");
+    const parsed = parseConfigToml(content);
+    return expandWorkflowTomlData(parsed, workflowPath);
+}
+/**
+ * Expand the `include` key of an already-parsed TOML object. Resolves
+ * fragment files relative to `<workflowPath>/../../workflow-fragments/`.
+ * Use this when the TOML has already been parsed elsewhere (e.g. inside
+ * `parseTomlFile()`).
+ */
+export function expandWorkflowTomlData(parsed, workflowPath) {
+    // Fast path: nothing to expand. Preserve the original shape exactly —
+    // including the absence of a `steps` field, since not every TOML file
+    // routed through `parseTomlFile()` represents a workflow.
+    if (!("include" in parsed)) {
+        return parsed;
+    }
+    const includeList = parsed.include;
+    if (!Array.isArray(includeList)) {
+        throw new Error(`Workflow '${workflowPath}' has an 'include' key but it is not an array. Use \`include = ["fragment-name"]\`.`);
+    }
+    // Resolve fragments directory: sibling of workflow's parent directory.
+    // E.g. workflow at  config/workflows/foo.toml
+    //      fragments at config/workflow-fragments/<name>.toml
+    const fragmentsDir = join(dirname(workflowPath), "..", "workflow-fragments");
+    const workflowOwnSteps = Array.isArray(parsed.steps)
+        ? parsed.steps
+        : [];
+    const allOriginated = [];
+    // 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;
+        }
+        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)}'` });
+    }
+    assertUniqueStepIds(allOriginated, workflowPath);
+    // Build the expanded object: drop `include`, replace `steps` with the
+    // concatenated list. Preserve all other top-level keys (workflow,
+    // triggers, configs, etc.) exactly as parsed.
+    const result = { ...parsed };
+    delete result.include;
+    result.steps = allOriginated.map((o) => o.step);
+    return result;
+}
+function readFragmentSafely(fragmentPath, workflowPath, fragmentName) {
+    if (!existsSync(fragmentPath)) {
+        throw new Error(`Workflow '${workflowPath}' includes fragment '${fragmentName}' but the file does not exist at '${fragmentPath}'.`);
+    }
+    let parsed;
+    try {
+        const content = readFileSync(fragmentPath, "utf-8");
+        parsed = parseConfigToml(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse fragment '${fragmentName}' at '${fragmentPath}': ${err?.message ?? err}`);
+    }
+    if ("include" in parsed) {
+        throw new Error(`Fragment '${fragmentName}' at '${fragmentPath}' contains its own 'include' key — recursive includes are not supported in v1. Inline the steps directly into this fragment.`);
+    }
+    if ("workflow" in parsed) {
+        throw new Error(`Fragment '${fragmentName}' at '${fragmentPath}' contains a [workflow] block. Fragment files must be [[steps]] lists only.`);
+    }
+    const steps = Array.isArray(parsed.steps)
+        ? parsed.steps
+        : [];
+    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) {
+        const id = step?.id;
+        if (id === undefined || id === null)
+            continue; // let downstream code complain about missing ids
+        if (typeof id !== "string")
+            continue;
+        if (seen.has(id)) {
+            const firstOrigin = seen.get(id);
+            throw new Error(`Step id '${id}' appears twice when expanding workflow '${workflowPath}': first in ${firstOrigin}, then in ${origin}.`);
+        }
+        seen.set(id, origin);
+    }
+}
+//# sourceMappingURL=workflow-fragments.js.map

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

@@ -0,0 +1 @@
+{"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;