@uipath/maestro-builder-sdk 5.2.0

package/dist/registry/python.js

@@ -0,0 +1,46 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+/**
+ * Running the packaged Python generators.
+ *
+ * Three verbs shell out to Python — materialize, extract and prepare — and all
+ * three need the same three things: the script's path inside the installed
+ * package, an interpreter, and a failure translated into a message worth
+ * reading. Keeping that here means a fix (a new platform's interpreter name,
+ * a clearer error) lands once.
+ *
+ * The generators are copied to `dist/generators/` at build time and these
+ * modules live in `dist/registry/`, so the path is one level up. Resolving it
+ * from `import.meta.url` rather than `process.cwd()` is what lets the verbs run
+ * from anywhere.
+ */
+/** A generator shipped in `dist/generators/`. */
+export function packagedGenerator(fileName) {
+    return fileURLToPath(new URL(`../generators/${fileName}`, import.meta.url));
+}
+export function defaultPythonExecutable() {
+    return (process.env.UIP_PYTHON_PATH ||
+        (process.platform === "win32" ? "python" : "python3"));
+}
+export async function runGenerator(options) {
+    const executable = options.pythonExecutable ?? defaultPythonExecutable();
+    await new Promise((resolve, reject) => {
+        const child = spawn(executable, [options.script, ...options.args], {
+            stdio: "inherit",
+        });
+        child.once("error", (error) => {
+            reject(new Error(`Could not start Python with ${executable}: ${error.message}. ` +
+                "The connector generators are Python scripts; install Python 3 or " +
+                "point UIP_PYTHON_PATH at an interpreter."));
+        });
+        child.once("exit", (code, signal) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(signal
+                ? `${options.what} stopped with signal ${signal}`
+                : `${options.what} failed with exit code ${code ?? "unknown"}`));
+        });
+    });
+}

package/dist/registry/search-cli.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Search an extracted connector library for operations.
+ *
+ * Ported from the product CLI's `registry-search-service.ts` so discovery lives
+ * beside the rest of the authoring verbs. Two deliberate differences from that
+ * version:
+ *
+ * - the library defaults to the cached one, and `--library` overrides it the same
+ *   way `compile` and `check` take it
+ *   name it, instead of being resolved from a machine-global snapshot. `pull`
+ *   defaults to writing one into the project; this verb does not guess where
+ *   that ended up, it is told;
+ * - the result is plain JSON on stdout. The `Result` / `Code` / `Data` envelope
+ *   is a `uip` convention, and an agent parsing this output does not need it.
+ */
+export interface RegistryOperation {
+    nodeType: string;
+    version: string;
+    connectorKey: string;
+    label: string;
+    activityType: string;
+    objectName: string;
+    operationName: string;
+    /** v1 node definition the compiler consumes. */
+    definitionPath: string;
+    /** Markdown page describing the operation's fields, when one was found. */
+    markdownPath?: string;
+}
+export interface RegistrySearchOptions {
+    libraryPath: string;
+    markdownPath?: string;
+    query?: string;
+    connector?: string;
+    limit?: number;
+}
+export interface RegistrySearchResult {
+    total: number;
+    operations: RegistryOperation[];
+}
+export declare const DEFAULT_SEARCH_LIMIT = 20;
+/**
+ * Split a query into the words that all have to match.
+ *
+ * Every token must appear somewhere in the entry, but they may land in
+ * different fields and in any order, so a natural phrase works: "salesforce
+ * insert record" matches an entry whose connector key carries "salesforce" and
+ * whose node type carries "insert-record". Tokens match as substrings, so a
+ * word still finds its hyphenated form without normalising separators.
+ */
+export declare function queryTokens(query?: string): string[];
+export declare function searchRegistryOperations(options: RegistrySearchOptions): Promise<RegistrySearchResult>;
+export declare function run(argv: string[]): Promise<number>;

package/dist/registry/search-cli.js

@@ -0,0 +1,159 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolveLibraryDir } from "./cache.js";
+import { dirname, join } from "node:path";
+export const DEFAULT_SEARCH_LIMIT = 20;
+const USAGE = "Usage: flow-sdk registry search [query] [--library <dir>] [--library-md <dir>] [--connector <key>] [--limit <n>]";
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+/**
+ * Split a query into the words that all have to match.
+ *
+ * Every token must appear somewhere in the entry, but they may land in
+ * different fields and in any order, so a natural phrase works: "salesforce
+ * insert record" matches an entry whose connector key carries "salesforce" and
+ * whose node type carries "insert-record". Tokens match as substrings, so a
+ * word still finds its hyphenated form without normalising separators.
+ */
+export function queryTokens(query) {
+    return (query ?? "")
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The markdown tree that pairs with `libraryPath`.
+ *
+ * Explicit `--library-md` wins. Otherwise look for a `library-md` sibling,
+ * which is how the materializer lays the two out. When neither exists the
+ * results simply carry no `markdownPath` — a missing page is not a reason to
+ * refuse a search.
+ */
+async function resolveMarkdownRoot(libraryPath, explicit) {
+    if (explicit)
+        return explicit;
+    const sibling = join(dirname(libraryPath), "library-md");
+    return (await isDirectory(sibling)) ? sibling : undefined;
+}
+export async function searchRegistryOperations(options) {
+    const indexPath = join(options.libraryPath, "index.json");
+    let content;
+    try {
+        content = await readFile(indexPath, "utf-8");
+    }
+    catch {
+        throw new Error(`Could not read ${indexPath}. Run \`flow-sdk registry pull\`, or point` +
+            " --library at an extracted connector library.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new Error(`${indexPath} is not valid JSON.`);
+    }
+    if (!parsed || !Array.isArray(parsed.entries)) {
+        throw new Error(`${indexPath} is not a valid connector index.`);
+    }
+    const tokens = queryTokens(options.query);
+    const connector = options.connector?.trim().toLowerCase();
+    const matches = parsed.entries.filter((entry) => {
+        const key = text(entry.connectorKey).toLowerCase();
+        if (connector && key !== connector)
+            return false;
+        if (tokens.length === 0)
+            return true;
+        // One haystack per entry, so a query may span fields. Matching each field
+        // separately meant a caller had to know which field held which word:
+        // "salesforce insert record" found nothing, because "salesforce" is in the
+        // connector key and "insert record" is in the node type, and no single
+        // field contained the whole phrase.
+        const haystack = [
+            text(entry.label),
+            text(entry.nodeType),
+            text(entry.objectName),
+            text(entry.operationName),
+            key,
+        ]
+            .join(" ")
+            .toLowerCase();
+        return tokens.every((token) => haystack.includes(token));
+    });
+    const markdownRoot = await resolveMarkdownRoot(options.libraryPath, options.markdownPath);
+    const limit = options.limit ?? DEFAULT_SEARCH_LIMIT;
+    const operations = matches.slice(0, limit).map((entry) => {
+        const relative = text(entry.path);
+        const operation = {
+            nodeType: text(entry.nodeType),
+            version: text(entry.version),
+            connectorKey: text(entry.connectorKey),
+            label: text(entry.label),
+            activityType: text(entry.activityType),
+            objectName: text(entry.objectName),
+            operationName: text(entry.operationName),
+            definitionPath: join(options.libraryPath, relative.replace(/\.json$/, ".v1def.json")),
+        };
+        if (markdownRoot) {
+            operation.markdownPath = join(markdownRoot, relative.replace(/\.json$/, ".md"));
+        }
+        return operation;
+    });
+    return { total: matches.length, operations };
+}
+function value(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+export async function run(argv) {
+    // Same resolution as compile and check: named, else the environment, else the
+    // shared cache `registry pull` filled. Requiring the flag here while the other
+    // verbs defaulted it was the inconsistency an author hit first.
+    const libraryPath = resolveLibraryDir(value(argv, "--library"));
+    if (!libraryPath) {
+        console.error(USAGE);
+        return 2;
+    }
+    const rawLimit = value(argv, "--limit");
+    const limit = rawLimit === undefined ? undefined : Number(rawLimit);
+    if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
+        console.error(`--limit expects a positive integer, received '${rawLimit}'.`);
+        return 2;
+    }
+    // The query is the one positional: every other token is a flag or its value.
+    const flagged = new Set();
+    for (const name of ["--library", "--library-md", "--connector", "--limit"]) {
+        const index = argv.indexOf(name);
+        if (index >= 0) {
+            flagged.add(String(index));
+            flagged.add(String(index + 1));
+        }
+    }
+    const query = argv
+        .filter((_, index) => !flagged.has(String(index)))
+        .join(" ")
+        .trim();
+    try {
+        const result = await searchRegistryOperations({
+            libraryPath,
+            markdownPath: value(argv, "--library-md"),
+            query: query || undefined,
+            connector: value(argv, "--connector"),
+            limit,
+        });
+        console.log(JSON.stringify(result, null, 2));
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

package/dist/schema-version.d.ts

@@ -0,0 +1,165 @@
+/**
+ * schema-version — the artifact's FILE-FORMAT version, as something an author
+ * can declare and a decompile can PRESERVE.
+ *
+ * Every artifact family this SDK writes carries a version that describes the
+ * DOCUMENT's grammar rather than the author's release: Flow's top-level
+ * `version`, Case's top-level `version`, BPMN's `uipath:migrationVersion`. Until
+ * now each family pinned exactly one value in its serializer's format profile
+ * and overwrote whatever the input said, which is right for greenfield
+ * authoring and wrong for the brownfield loop:
+ *
+ *   decompile(a 1.10 flow) -> compile -> a 1.9 flow, with nothing said.
+ *
+ * That silent rewrite is the hole this module closes. `.schemaVersion(v)` on
+ * each builder declares the version the emitted document targets, decompile
+ * emits the call so a round-trip re-declares what it read, and the serializer
+ * writes what was declared instead of the pin.
+ *
+ * ## A declared version is a CLAIM, not a switch
+ *
+ * The rule that shapes this whole module is the one CASE_PARITY §3.8 states for
+ * `.version()`: a document's version asserts that the whole document matches
+ * that schema. An author writing `.version('30.0.0')` against the old
+ * V20-emitting serializer produced an INVALID document, because the claim was
+ * false. So `.schemaVersion()` accepts only versions this SDK can actually
+ * write — {@link SchemaVersionPolicy.writable}, each row carrying the evidence
+ * that says so — and refuses anything else rather than stamping a claim it
+ * cannot back. Moving a document BETWEEN versions stays the product's job
+ * (`uip maestro flow migrate`), because a hop can carry data repairs this SDK
+ * has no way to reproduce.
+ *
+ * ## Comparing versions
+ *
+ * `'1.10' < '1.9'` as strings, which is exactly the wrong answer, and the same
+ * trap sits in Case's `'30.0.0'` vs `'9.0.0'`. Nothing here compares version
+ * strings with `<`; {@link compareSchemaVersions} splits on `.` and compares
+ * segments numerically, and every gate goes through it.
+ */
+/** The artifact families that carry a schema version. */
+export type ArtifactFamily = 'flow' | 'case' | 'bpmn';
+/** A version this SDK build can WRITE, with the evidence that says it can. */
+export interface WritableSchemaVersion {
+    /** The version string, exactly as it appears in the document. */
+    version: string;
+    /**
+     * The version whose emitted bytes this one shares, when it shares any. Two
+     * versions are byte-equal for this SDK when the newer schema only re-declares
+     * the version literal and its migration hop touches nothing the SDK emits —
+     * then writing it is the same output under a different claim.
+     */
+    sameBytesAs?: string;
+    /** Why this SDK can write it. Read from the platform's own schema/migration source, not assumed. */
+    evidence: string;
+}
+/**
+ * What one family's schema version means, what this SDK can write, and where
+ * the platform's own boundary sits.
+ */
+export interface SchemaVersionPolicy {
+    family: ArtifactFamily;
+    /**
+     * `'enumerated'` — the platform defines a closed set of grammars and a
+     * document's version claims one of them, so only {@link writable} versions
+     * may be declared (Flow, Case).
+     *
+     * `'verbatim'` — the version is a stamp the SDK copies through without
+     * varying its emission, so any well-formed value is accepted (BPMN's
+     * `uipath:migrationVersion`, a canvas schema generation).
+     */
+    mode: 'enumerated' | 'verbatim';
+    /**
+     * What an artifact declares when the author does not. For an enumerated
+     * family this is the fleet WRITE FLOOR — the oldest version every deployed
+     * reader accepts — not the newest version that exists. `undefined` means the
+     * document declares nothing at all (BPMN: an empty
+     * `uipath:migrationVersion` fails product validation, so absent beats blank).
+     */
+    default?: string;
+    /**
+     * The newest version the platform is known to define, from the family's
+     * snapshot. Kept here so the gap between "what we write" and "what exists"
+     * is a value the diagnostics can name rather than a comment.
+     */
+    latestKnown?: string;
+    /** Every version this build can write. Empty for a `'verbatim'` family. */
+    writable: readonly WritableSchemaVersion[];
+    /**
+     * One sentence naming what moves a document BETWEEN versions — a product
+     * command for Flow, the platform's on-read chain for Case. Free text rather
+     * than a command name because the two families answer it differently, and a
+     * refusal that names the wrong mechanism is worse than one that names none.
+     */
+    migration: string;
+    /**
+     * The builder method that declares it, WITHOUT parentheses (`.schemaVersion`)
+     * — every message appends its own argument list, so a value carrying `()`
+     * renders as `.schemaVersion()("1.9")`.
+     */
+    method: string;
+}
+/** True when `value` is shaped like a schema version at all. */
+export declare function isSchemaVersionSyntax(value: unknown): value is string;
+/**
+ * Compare two dotted-numeric versions SEGMENT BY SEGMENT: negative when `a` is
+ * older, 0 when equal, positive when `a` is newer. A missing segment reads as
+ * `0`, so `'1.9'` and `'1.9.0'` compare equal.
+ *
+ * Throws on a non-version string rather than guessing, because a silent 0 here
+ * would make every gate answer "equal" for garbage input.
+ */
+export declare function compareSchemaVersions(a: string, b: string): number;
+/** True when `version` is `floor` or newer. The gate every version-conditional step uses. */
+export declare function schemaVersionAtLeast(version: string, floor: string): boolean;
+/** The writable versions, oldest first. */
+export declare function writableSchemaVersions(policy: SchemaVersionPolicy): string[];
+/**
+ * True when this build can write `version` for `policy`.
+ *
+ * A `'verbatim'` family accepts any non-empty stamp, because the SDK copies it
+ * through without varying a byte of its emission — refusing an unfamiliar value
+ * there would DROP a stamp the platform wrote, which is the loss this whole
+ * module exists to stop. Only an empty one is refused, and that is a product
+ * rule: an empty `uipath:migrationVersion` fails validation outright, so absent
+ * beats blank.
+ */
+export declare function isWritableSchemaVersion(policy: SchemaVersionPolicy, version: string): boolean;
+/**
+ * Why `requested` cannot be declared, or `undefined` when it can.
+ *
+ * One message text, shared by the builder's own refusal, `check()`'s
+ * diagnostic and the serializer's throw, so an author who hits it in three
+ * places reads the same sentence three times instead of three near-misses.
+ */
+export declare function schemaVersionRefusal(policy: SchemaVersionPolicy, requested: string): string | undefined;
+/**
+ * The version an artifact declares: the author's when they declared one, else
+ * the policy default. Throws the shared refusal when it cannot be honoured —
+ * called from the serializer, which must not write a claim it cannot back even
+ * when `check()` was skipped (`compile --no-check`, `emitFlow`, a direct
+ * `serialize()`).
+ */
+export declare function resolveSchemaVersion(policy: SchemaVersionPolicy, requested: string | undefined): string | undefined;
+/**
+ * What a DECOMPILE should do with the version it just read.
+ *
+ * Preserving means re-declaring: emit `.schemaVersion(read)` so recompiling
+ * writes the version the file had, whatever this SDK's own default is today. It
+ * is deliberately emitted even when it equals the default — the point is that a
+ * later default bump must not silently upgrade a file that a decompile already
+ * captured.
+ *
+ * When the file declares a version this build cannot write, the honest output
+ * is neither a dropped version (today's silent downgrade) nor a call that
+ * `compile` would refuse: it is a report. `problem` carries it, for the source's
+ * `// TODO:` line and the CLI's stderr — the same shape as the other findings a
+ * decompile cannot encode in the chain (an unreachable node, a core version this
+ * SDK does not bundle).
+ */
+export interface SchemaVersionPreservation {
+    /** The builder call to emit, or `undefined` when there is nothing to declare. */
+    call?: string;
+    /** What could not be preserved, for a `// TODO:` line and stderr. */
+    problem?: string;
+}
+export declare function preserveSchemaVersion(policy: SchemaVersionPolicy, declared: unknown): SchemaVersionPreservation;

package/dist/schema-version.js

@@ -0,0 +1,148 @@
+/**
+ * schema-version — the artifact's FILE-FORMAT version, as something an author
+ * can declare and a decompile can PRESERVE.
+ *
+ * Every artifact family this SDK writes carries a version that describes the
+ * DOCUMENT's grammar rather than the author's release: Flow's top-level
+ * `version`, Case's top-level `version`, BPMN's `uipath:migrationVersion`. Until
+ * now each family pinned exactly one value in its serializer's format profile
+ * and overwrote whatever the input said, which is right for greenfield
+ * authoring and wrong for the brownfield loop:
+ *
+ *   decompile(a 1.10 flow) -> compile -> a 1.9 flow, with nothing said.
+ *
+ * That silent rewrite is the hole this module closes. `.schemaVersion(v)` on
+ * each builder declares the version the emitted document targets, decompile
+ * emits the call so a round-trip re-declares what it read, and the serializer
+ * writes what was declared instead of the pin.
+ *
+ * ## A declared version is a CLAIM, not a switch
+ *
+ * The rule that shapes this whole module is the one CASE_PARITY §3.8 states for
+ * `.version()`: a document's version asserts that the whole document matches
+ * that schema. An author writing `.version('30.0.0')` against the old
+ * V20-emitting serializer produced an INVALID document, because the claim was
+ * false. So `.schemaVersion()` accepts only versions this SDK can actually
+ * write — {@link SchemaVersionPolicy.writable}, each row carrying the evidence
+ * that says so — and refuses anything else rather than stamping a claim it
+ * cannot back. Moving a document BETWEEN versions stays the product's job
+ * (`uip maestro flow migrate`), because a hop can carry data repairs this SDK
+ * has no way to reproduce.
+ *
+ * ## Comparing versions
+ *
+ * `'1.10' < '1.9'` as strings, which is exactly the wrong answer, and the same
+ * trap sits in Case's `'30.0.0'` vs `'9.0.0'`. Nothing here compares version
+ * strings with `<`; {@link compareSchemaVersions} splits on `.` and compares
+ * segments numerically, and every gate goes through it.
+ */
+/** A version string the schema families use: dotted, numeric, e.g. `1.9`, `1.10`, `30.0.0`. */
+const SYNTAX = /^\d+(\.\d+)*$/;
+/** True when `value` is shaped like a schema version at all. */
+export function isSchemaVersionSyntax(value) {
+    return typeof value === 'string' && SYNTAX.test(value);
+}
+/**
+ * Compare two dotted-numeric versions SEGMENT BY SEGMENT: negative when `a` is
+ * older, 0 when equal, positive when `a` is newer. A missing segment reads as
+ * `0`, so `'1.9'` and `'1.9.0'` compare equal.
+ *
+ * Throws on a non-version string rather than guessing, because a silent 0 here
+ * would make every gate answer "equal" for garbage input.
+ */
+export function compareSchemaVersions(a, b) {
+    if (!isSchemaVersionSyntax(a) || !isSchemaVersionSyntax(b)) {
+        throw new Error(`compareSchemaVersions: "${a}" / "${b}" is not a dotted-numeric schema version.`);
+    }
+    const left = a.split('.').map(Number);
+    const right = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** True when `version` is `floor` or newer. The gate every version-conditional step uses. */
+export function schemaVersionAtLeast(version, floor) {
+    return compareSchemaVersions(version, floor) >= 0;
+}
+/** The writable versions, oldest first. */
+export function writableSchemaVersions(policy) {
+    return policy.writable.map((w) => w.version).sort(compareSchemaVersions);
+}
+/**
+ * True when this build can write `version` for `policy`.
+ *
+ * A `'verbatim'` family accepts any non-empty stamp, because the SDK copies it
+ * through without varying a byte of its emission — refusing an unfamiliar value
+ * there would DROP a stamp the platform wrote, which is the loss this whole
+ * module exists to stop. Only an empty one is refused, and that is a product
+ * rule: an empty `uipath:migrationVersion` fails validation outright, so absent
+ * beats blank.
+ */
+export function isWritableSchemaVersion(policy, version) {
+    if (policy.mode === 'verbatim')
+        return typeof version === 'string' && version.trim() !== '';
+    return policy.writable.some((w) => w.version === version);
+}
+/**
+ * Why `requested` cannot be declared, or `undefined` when it can.
+ *
+ * One message text, shared by the builder's own refusal, `check()`'s
+ * diagnostic and the serializer's throw, so an author who hits it in three
+ * places reads the same sentence three times instead of three near-misses.
+ */
+export function schemaVersionRefusal(policy, requested) {
+    const { method, family } = policy;
+    if (typeof requested !== 'string' || requested.trim() === '') {
+        return `${method}() needs a version string, e.g. ${method}("${policy.default ?? '1.0'}").`;
+    }
+    if (policy.mode === 'verbatim')
+        return undefined;
+    if (!isSchemaVersionSyntax(requested)) {
+        return `${method}("${requested}") is not a ${family} schema version — those are dotted and numeric, e.g. "${policy.default ?? '1.0'}".`;
+    }
+    if (isWritableSchemaVersion(policy, requested))
+        return undefined;
+    const writable = writableSchemaVersions(policy);
+    const newest = writable[writable.length - 1];
+    const direction = policy.latestKnown !== undefined && schemaVersionAtLeast(requested, policy.latestKnown)
+        ? compareSchemaVersions(requested, policy.latestKnown) > 0
+            ? `The platform's newest known ${family} schema version is ${policy.latestKnown}, so ${requested} is newer than anything this SDK has read.`
+            : `${requested} is the platform's current ${family} schema version, but this SDK build has not been taught to write it.`
+        : `${requested} is older than the ${writable.length === 1 ? 'one version' : 'versions'} this build writes.`;
+    return (`${method}("${requested}"): this SDK build writes ${family} schema ${writable.join(' / ')}. ${direction} `
+        + `A document's version claims that the WHOLE document matches that schema, so declaring one this build cannot emit `
+        + `would write a false claim rather than a different document. ${policy.migration}`);
+}
+/**
+ * The version an artifact declares: the author's when they declared one, else
+ * the policy default. Throws the shared refusal when it cannot be honoured —
+ * called from the serializer, which must not write a claim it cannot back even
+ * when `check()` was skipped (`compile --no-check`, `emitFlow`, a direct
+ * `serialize()`).
+ */
+export function resolveSchemaVersion(policy, requested) {
+    if (requested === undefined)
+        return policy.default;
+    const refusal = schemaVersionRefusal(policy, requested);
+    if (refusal)
+        throw new Error(refusal);
+    return requested;
+}
+export function preserveSchemaVersion(policy, declared) {
+    if (declared === undefined || declared === null || declared === '')
+        return {};
+    const version = String(declared);
+    if (isWritableSchemaVersion(policy, version)) {
+        return { call: `${policy.method}(${JSON.stringify(version)})` };
+    }
+    const writes = policy.default ?? writableSchemaVersions(policy)[0] ?? 'nothing';
+    return {
+        problem: `the file declares ${policy.family} schema version ${JSON.stringify(version)}, which this SDK build cannot write, `
+            + `so this source does not re-declare it and recompiling writes ${JSON.stringify(String(writes))} instead. `
+            + `${policy.migration} Until then, merge the recompiled graph back into the ORIGINAL file, which keeps its own `
+            + `declared version.`,
+    };
+}

package/dist/serialize.d.ts

@@ -0,0 +1,64 @@
+import type { BuiltFlow } from './flow-sdk.js';
+import type { Library, ResolvedConnector } from './library.js';
+import type { Bindings } from './bindings.js';
+import { type LookupResolutions, type LookupSpec } from './core/lookups.js';
+/**
+ * A compile-time observation that does not stop emission. `check()` has its
+ * diagnostics; this is the serializer's own channel for things it can only see
+ * once bindings are in hand — today, a connection or folder value that can never
+ * be a tenant resource key (`CONNECTION_STUB`).
+ */
+export interface SerializeWarning {
+    code: string;
+    message: string;
+}
+export interface SerializeOpts {
+    library?: Library;
+    bindings?: Bindings;
+    /**
+     * Receives each {@link SerializeWarning}. `compile-cli` prints them as
+     * `⚠ [CODE] …` after `check()`'s diagnostics; a caller that passes nothing
+     * hears nothing, which keeps `serialize()` silent in tests and libraries.
+     */
+    warn?: (warning: SerializeWarning) => void;
+    /**
+     * Filled in by `serialize` with the extra files the flow needs beside the
+     * `.flow`, relative to it. Today that is one `<source>/agent.json` per inline
+     * agent: the node points at that directory and the platform resolves the agent's
+     * real configuration there, so a `.flow` shipped without it references a
+     * definition that is not on disk.
+     *
+     * An out-parameter rather than a second return value so no caller that ignores
+     * sidecars has to change — but a caller that WRITES the flow has to write these
+     * too, which is why `compile-cli` does. `serializeWithSidecars` is the convenient
+     * form.
+     */
+    sidecars?: Array<{
+        path: string;
+        json: unknown;
+    }>;
+}
+/**
+ * `serialize`, plus the extra files the flow needs on disk beside it.
+ *
+ * Use this rather than `serialize` when you are about to WRITE the flow: an inline
+ * agent is two artifacts (the node and its `<source>/agent.json`), and a caller that
+ * writes only the first emits a flow whose agent definition is missing.
+ */
+export declare function serializeWithSidecars(built: BuiltFlow, opts?: SerializeOpts): {
+    flow: any;
+    sidecars: Array<{
+        path: string;
+        json: unknown;
+    }>;
+};
+export declare function serialize(built: BuiltFlow, opts?: SerializeOpts): any;
+/**
+ * What `compile` would refuse these connector inputs with, or `undefined` when it
+ * would accept them — the SAME code path `buildConnectorInputs` runs at emit time,
+ * so `check` and `compile` cannot disagree about a missing required field, an
+ * unknown or mistyped input, or a container part passed as a value. Unresolved
+ * lookups are the one thing skipped: `check` already reports them as
+ * LOOKUP_UNRESOLVED with the resolution recipe.
+ */
+export declare function connectorInputErrors(rc: ResolvedConnector, inputs: Record<string, unknown>, resolutions?: LookupResolutions, lookups?: Readonly<Record<string, LookupSpec>>): string | undefined;