@signstack/cli 0.1.1

package/dist/apps/signstack-cli/src/lib/resource-puller.js

@@ -0,0 +1,800 @@
+import { AssetType, parseResourceId, ResourceKind, } from '@signstack/base';
+import { SchemaKind } from '../types/schema.types.js';
+import { YamlWriter } from './yaml-writer.js';
+/** Org-scoped pull source — uses authenticated org/namespace endpoints. */
+export class OrgPullSource {
+    orgId;
+    nsKey;
+    constructor(orgId, nsKey) {
+        this.orgId = orgId;
+        this.nsKey = nsKey;
+    }
+    buildDependencyTreeUrl(kind, key, version) {
+        return `/v1/orgs/${this.orgId}/namespaces/${this.nsKey}/resource-edges/${encodeURIComponent(kind)}/${encodeURIComponent(key)}/${encodeURIComponent(version)}/depends-on?transitive=true`;
+    }
+    buildResourceUrl(kind, key, version) {
+        const endpoint = KIND_TO_ENDPOINT[kind];
+        return `/v1/orgs/${this.orgId}/namespaces/${this.nsKey}/${endpoint}/${key}?version=${version}`;
+    }
+    async fetchFileDownloadUrl(client, fileId) {
+        const file = await client.get(`/v1/orgs/${this.orgId}/files/${fileId}`);
+        return file.downloadUrl;
+    }
+}
+/**
+ * Public library pull source — scoped by the listing that's being pulled. All
+ * URLs are keyed by the listing (`listingKey@listingVersion`), not the
+ * underlying resource. Sub-resources are fetched through the listing so the
+ * backend can authorize access once at the listing level. No auth required.
+ */
+export class LibraryPullSource {
+    listingKey;
+    listingVersion;
+    constructor(listingKey, listingVersion) {
+        this.listingKey = listingKey;
+        this.listingVersion = listingVersion;
+    }
+    get _prefix() {
+        return `/v1/library/listings/by-key/${encodeURIComponent(this.listingKey)}/${encodeURIComponent(this.listingVersion)}`;
+    }
+    // The dependency tree is per-listing (the listing knows its root resource
+    // and transitive deps), so the `kind`/`key`/`version` args are ignored.
+    buildDependencyTreeUrl() {
+        return `${this._prefix}/dependencies`;
+    }
+    buildResourceUrl(kind, key, version) {
+        const endpoint = KIND_TO_ENDPOINT[kind];
+        return `${this._prefix}/${endpoint}/${encodeURIComponent(key)}?resourceVersion=${encodeURIComponent(version)}`;
+    }
+    async fetchFileDownloadUrl(client, fileId) {
+        const resp = await client.get(`${this._prefix}/files/${encodeURIComponent(fileId)}/signed-url`);
+        return resp.url;
+    }
+}
+/** Map backend ResourceKind to CLI SchemaKind */
+const BACKEND_TO_SCHEMA_KIND = {
+    [ResourceKind.Blueprint]: SchemaKind.Blueprint,
+    [ResourceKind.Template]: SchemaKind.Template,
+    [ResourceKind.Schema]: SchemaKind.Schema,
+    [ResourceKind.Asset]: SchemaKind.Asset,
+    [ResourceKind.JsonataFunction]: SchemaKind.JsonataFunction,
+};
+/** Map CLI SchemaKind to backend ResourceKind */
+export const SCHEMA_KIND_TO_BACKEND = {
+    [SchemaKind.Blueprint]: ResourceKind.Blueprint,
+    [SchemaKind.Template]: ResourceKind.Template,
+    [SchemaKind.Schema]: ResourceKind.Schema,
+    [SchemaKind.Asset]: ResourceKind.Asset,
+    [SchemaKind.JsonataFunction]: ResourceKind.JsonataFunction,
+};
+/** Map backend ResourceKind to API endpoint path segment */
+export const KIND_TO_ENDPOINT = {
+    [ResourceKind.Blueprint]: 'blueprints',
+    [ResourceKind.Template]: 'templates',
+    [ResourceKind.Schema]: 'schemas',
+    [ResourceKind.Asset]: 'assets',
+    [ResourceKind.JsonataFunction]: 'jsonata-functions',
+};
+/** Default file extensions by asset type */
+const ASSET_TYPE_EXT = {
+    [AssetType.Pdf]: '.pdf',
+    [AssetType.Image]: '.png',
+    [AssetType.Html]: '.hbs',
+    [AssetType.Css]: '.css',
+};
+/** Content-Type to file extension reverse map */
+const CONTENT_TYPE_TO_EXT = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/gif': '.gif',
+    'image/svg+xml': '.svg',
+    'image/webp': '.webp',
+    'application/pdf': '.pdf',
+};
+const CONCURRENCY_LIMIT = 5;
+const API_VERSION = 'signstack/v1beta2';
+/**
+ * ResourcePuller — Fetches SignStack resources from the API and converts them to YAML files.
+ *
+ * This is the inverse of ResourcePusher. It:
+ * 1. Fetches the dependency tree for a resource
+ * 2. Downloads each dependent resource
+ * 3. Converts API responses to YAML format
+ * 4. Downloads binary files for assets with fileIds
+ * 5. Writes everything to a local folder structure
+ */
+export class ResourcePuller {
+    client;
+    source;
+    log;
+    constructor(client, source, log) {
+        this.client = client;
+        this.source = source;
+        this.log = log;
+    }
+    /**
+     * Pull a resource and all its dependencies from the API.
+     */
+    async pull(params) {
+        const { kind, key, version, outputDir, verbose } = params;
+        // Step 1: Fetch dependency tree
+        if (verbose) {
+            this.log(`Fetching dependency tree for ${kind}:${key}@${version}...`);
+        }
+        const resourceIds = await this.fetchAllDependencyIds(kind, key, version);
+        this.log(`Found ${resourceIds.size} dependencies (including root)`);
+        // Build a lookup map from "kind:key" -> version, so converters can resolve
+        // missing schemaVersion fields that the API sometimes omits.
+        const versionByKindAndKey = new Map();
+        for (const id of resourceIds) {
+            const { kind: k, key: rk, version: rv } = parseResourceId(id);
+            versionByKindAndKey.set(`${k}:${rk}`, rv);
+        }
+        // Step 2: Create output directory structure
+        const writer = new YamlWriter(outputDir);
+        writer.ensureDirectories();
+        // Step 3: Fetch and convert each resource
+        const results = [];
+        const byKind = {};
+        const resourceIdArray = Array.from(resourceIds);
+        // Process in batches for concurrency
+        for (let i = 0; i < resourceIdArray.length; i += CONCURRENCY_LIMIT) {
+            const batch = resourceIdArray.slice(i, i + CONCURRENCY_LIMIT);
+            const batchResults = await Promise.all(batch.map((id) => this.pullSingleResource(id, writer, verbose, versionByKindAndKey)));
+            for (const result of batchResults) {
+                results.push(result);
+                if (result.success) {
+                    byKind[result.kind] = (byKind[result.kind] ?? 0) + 1;
+                }
+            }
+        }
+        const succeeded = results.filter((r) => r.success).length;
+        const failed = results.filter((r) => !r.success).length;
+        return {
+            outputDir,
+            total: results.length,
+            succeeded,
+            failed,
+            results,
+            byKind,
+        };
+    }
+    /**
+     * Fetch the transitive dependency tree and collect all unique resource IDs.
+     * Also includes the root resource itself.
+     */
+    async fetchAllDependencyIds(kind, key, version) {
+        const rootId = `${kind}:${key}@${version}`;
+        const ids = new Set();
+        ids.add(rootId);
+        try {
+            const url = this.source.buildDependencyTreeUrl(kind, key, version);
+            const resp = await this.client.get(url);
+            if (resp.tree) {
+                this.flattenTree(resp.tree, ids);
+            }
+        }
+        catch (error) {
+            this.log(`Warning: Could not fetch dependency tree for ${rootId}: ${error.message}`);
+        }
+        return ids;
+    }
+    /**
+     * Recursively flatten a dependency tree into a set of resource IDs.
+     * Handles both org format ({ resourceId }) and library format ({ kind, key, version }).
+     */
+    flattenTree(node, ids) {
+        if ('resourceId' in node) {
+            ids.add(node.resourceId);
+        }
+        else {
+            ids.add(`${node.kind}:${node.key}@${node.version}`);
+        }
+        for (const child of node.children ?? []) {
+            this.flattenTree(child, ids);
+        }
+    }
+    /**
+     * Pull a single resource: fetch from API, convert to YAML, write files.
+     */
+    async pullSingleResource(resourceId, writer, verbose, versionByKindAndKey) {
+        const { kind: backendKind, key, version } = parseResourceId(resourceId);
+        const schemaKind = BACKEND_TO_SCHEMA_KIND[backendKind];
+        if (!schemaKind) {
+            return {
+                resourceId,
+                kind: SchemaKind.Schema, // fallback
+                key,
+                version,
+                success: false,
+                error: `Unknown resource kind: ${backendKind}`,
+            };
+        }
+        const baseResult = {
+            resourceId,
+            kind: schemaKind,
+            key,
+            version,
+            success: false,
+        };
+        try {
+            const path = this.source.buildResourceUrl(backendKind, key, version);
+            const resp = await this.client.get(path);
+            const { yamlDoc, additionalFiles } = await this.convertResource(schemaKind, key, version, resp, writer, versionByKindAndKey);
+            const yamlPath = writer.writeYaml(schemaKind, key, yamlDoc);
+            if (verbose) {
+                this.log(`  ${schemaKind}:${key}@${version} -> ${yamlPath}`);
+            }
+            return {
+                ...baseResult,
+                success: true,
+                yamlPath,
+                additionalFiles,
+            };
+        }
+        catch (error) {
+            const errMsg = error.message;
+            if (verbose) {
+                this.log(`  Failed: ${schemaKind}:${key}@${version} - ${errMsg}`);
+            }
+            return { ...baseResult, error: errMsg };
+        }
+    }
+    /**
+     * Convert an API response to a YAML document object.
+     * Also writes any additional files (JSON definitions, HTML/CSS content, binary files).
+     */
+    async convertResource(kind, key, version, resp, writer, versionByKindAndKey) {
+        switch (kind) {
+            case SchemaKind.Schema:
+                return this.convertSchema(key, resp, writer);
+            case SchemaKind.Asset:
+                return this.convertAsset(key, resp, writer);
+            case SchemaKind.Template:
+                return this.convertTemplateWithAssetStub(key, version, resp, writer, versionByKindAndKey);
+            case SchemaKind.Blueprint:
+                return {
+                    yamlDoc: this.convertBlueprint(resp, versionByKindAndKey),
+                    additionalFiles: [],
+                };
+            case SchemaKind.JsonataFunction:
+                return {
+                    yamlDoc: this.convertJsonataFunction(resp, versionByKindAndKey),
+                    additionalFiles: [],
+                };
+            default:
+                throw new Error(`Unknown resource kind: ${kind}`);
+        }
+    }
+    // ─── Schema Conversion ────────────────────────────────────────
+    convertSchema(key, resp, writer) {
+        const additionalFiles = [];
+        // Write JSON schema definition to file
+        const filePath = writer.writeJsonDefinition(key, resp.spec.schemaDefinition);
+        additionalFiles.push(filePath);
+        const yamlDoc = {
+            apiVersion: API_VERSION,
+            kind: 'Schema',
+            metadata: buildMetadata(resp.metadata),
+            spec: {
+                jsonSchemaDraft: resp.spec.jsonSchemaDraft,
+                file: filePath,
+            },
+        };
+        return { yamlDoc, additionalFiles };
+    }
+    // ─── Asset Conversion ─────────────────────────────────────────
+    async convertAsset(key, resp, writer) {
+        const additionalFiles = [];
+        const spec = {
+            type: resp.spec.type,
+        };
+        // Handle file content based on asset type
+        if (resp.spec.type === AssetType.Html || resp.spec.type === AssetType.Css) {
+            // Text assets: write content to file
+            if (resp.spec.content) {
+                const subdir = resp.spec.type === AssetType.Html ? 'html' : 'css';
+                const ext = ASSET_TYPE_EXT[resp.spec.type] ?? '.txt';
+                const filename = `${key}${ext}`;
+                const filePath = writer.writeTextContent(subdir, filename, resp.spec.content);
+                spec.file = filePath;
+                additionalFiles.push(filePath);
+            }
+        }
+        else if (resp.spec.type === AssetType.Pdf ||
+            resp.spec.type === AssetType.Image) {
+            // Binary assets: download via signed URL
+            if (resp.spec.fileId) {
+                try {
+                    const signedUrl = await this.getSignedUrl(resp.spec.fileId);
+                    const ext = await this.getFileExtension(resp.spec.type, signedUrl);
+                    const filePath = await writer.downloadBinaryFile(key, ext, signedUrl);
+                    spec.file = filePath;
+                    additionalFiles.push(filePath);
+                }
+                catch (error) {
+                    // Log but don't fail the entire resource
+                    this.log(`  Warning: Could not download file for asset ${key} (fileId: ${resp.spec.fileId}): ${error.message}`);
+                }
+            }
+        }
+        // Handle HTML config references
+        if (resp.spec.htmlConfig) {
+            this.convertHtmlConfig(resp.spec.htmlConfig, spec);
+        }
+        const yamlDoc = {
+            apiVersion: API_VERSION,
+            kind: 'Asset',
+            metadata: buildMetadata(resp.metadata),
+            spec,
+        };
+        return { yamlDoc, additionalFiles };
+    }
+    /**
+     * Convert API htmlConfig refs back to YAML format.
+     */
+    convertHtmlConfig(config, spec) {
+        // Partials: [{key, version, alias}] -> { alias: "key@version" }
+        if (config.partials && config.partials.length > 0) {
+            const partials = {};
+            for (const p of config.partials) {
+                partials[p.alias] = `${p.key}@${p.version}`;
+            }
+            spec.partials = partials;
+        }
+        // Styles: [{key, version}] -> ["key@version"]
+        if (config.styles && config.styles.length > 0) {
+            spec.styles = config.styles.map((s) => `${s.key}@${s.version}`);
+        }
+        // Images: [{key, version, alias}] -> { alias: "key@version" }
+        if (config.images && config.images.length > 0) {
+            const images = {};
+            for (const img of config.images) {
+                images[img.alias] = `${img.key}@${img.version}`;
+            }
+            spec.images = images;
+        }
+        // ViewModel schema
+        if (config.data?.schemaKey) {
+            spec.data = {
+                schema: toRef(config.data.schemaKey, config.data.schemaVersion),
+            };
+        }
+        // PDF settings
+        if (config.pdfSettings) {
+            spec.pdfSettings = config.pdfSettings;
+        }
+    }
+    // ─── Template Conversion ──────────────────────────────────────
+    /**
+     * Convert a template and, when contentKey was absent from the API response
+     * (supplement templates like exhibit_a_nwmls), also write a stub asset YAML
+     * so that --resolve local preview can find the content dependency.
+     */
+    convertTemplateWithAssetStub(key, version, resp, writer, versionByKindAndKey) {
+        const additionalFiles = [];
+        const yamlDoc = this.convertTemplate(resp, versionByKindAndKey);
+        // When contentKey was absent from the API, write a stub asset so that
+        // --resolve local preview can resolve the content reference.
+        if (!resp.spec.contentKey && resp.spec.type === 'pdf') {
+            const assetVersion = resp.metadata.version;
+            const stubAsset = {
+                apiVersion: API_VERSION,
+                kind: 'Asset',
+                metadata: {
+                    key,
+                    version: assetVersion,
+                    name: key,
+                },
+                spec: {
+                    type: 'pdf',
+                    file: `./${key}.pdf`,
+                },
+            };
+            const assetPath = writer.writeYaml(SchemaKind.Asset, key, stubAsset);
+            writer.writePlaceholderPdf(key);
+            this.log(`  Warning: template ${key}@${version} had no contentKey — wrote stub asset at ${assetPath}`);
+            additionalFiles.push(assetPath);
+        }
+        return { yamlDoc, additionalFiles };
+    }
+    convertTemplate(resp, versionByKindAndKey) {
+        const spec = {
+            type: resp.spec.type,
+        };
+        // Content reference — required for pdf templates.
+        // Fall back to the template's own key/version when the API omits contentKey
+        // or contentVersion (observed for supplement templates like exhibit_a_nwmls).
+        const contentKey = resp.spec.contentKey ||
+            (resp.spec.type === 'pdf' ? resp.metadata.key : undefined);
+        const contentVersion = resp.spec.contentVersion || resp.metadata.version;
+        if (contentKey) {
+            spec.content = toRef(contentKey, contentVersion);
+        }
+        // Inputs
+        if (resp.spec.inputs && resp.spec.inputs.length > 0) {
+            spec.inputs = resp.spec.inputs.map((i) => convertInputToYaml(i, versionByKindAndKey));
+        }
+        // Roles
+        if (resp.spec.roles && resp.spec.roles.length > 0) {
+            spec.roles = resp.spec.roles.map(convertRoleToYaml);
+        }
+        // Fields
+        if (resp.spec.fields && resp.spec.fields.length > 0) {
+            spec.fields = resp.spec.fields.map(convertFieldToYaml);
+        }
+        // Data transform
+        if (resp.spec.data?.transform) {
+            spec.data = { transform: resp.spec.data.transform };
+        }
+        if (resp.spec.functions && resp.spec.functions.length > 0) {
+            spec.functions = convertFunctionsToYaml(resp.spec.functions);
+        }
+        return {
+            apiVersion: API_VERSION,
+            kind: 'Template',
+            metadata: buildMetadata(resp.metadata),
+            spec,
+        };
+    }
+    // ─── Blueprint Conversion ─────────────────────────────────────
+    convertBlueprint(resp, versionByKindAndKey) {
+        const spec = {};
+        // Inputs
+        if (resp.spec.inputs && resp.spec.inputs.length > 0) {
+            spec.inputs = resp.spec.inputs.map((i) => convertInputToYaml(i, versionByKindAndKey));
+        }
+        // Participants
+        if (resp.spec.participants && resp.spec.participants.length > 0) {
+            spec.participants = resp.spec.participants.map(convertParticipantToYaml);
+        }
+        // Envelopes
+        if (resp.spec.envelopes && resp.spec.envelopes.length > 0) {
+            spec.envelopes = resp.spec.envelopes.map(convertEnvelopeToYaml);
+        }
+        if (resp.spec.functions && resp.spec.functions.length > 0) {
+            spec.functions = convertFunctionsToYaml(resp.spec.functions);
+        }
+        // Orchestration
+        if (resp.spec.orchestration) {
+            spec.orchestration = convertOrchestrationToYaml(resp.spec.orchestration);
+        }
+        return {
+            apiVersion: API_VERSION,
+            kind: 'Blueprint',
+            metadata: buildMetadata(resp.metadata),
+            spec,
+        };
+    }
+    // ─── JsonataFunction Conversion ───────────────────────────────
+    convertJsonataFunction(resp, versionByKindAndKey) {
+        const spec = {};
+        if (resp.spec.params && resp.spec.params.length > 0) {
+            spec.params = resp.spec.params.map((p) => {
+                const param = {
+                    name: p.name,
+                    type: p.type,
+                };
+                if (p.schemaKey) {
+                    param.schema = toRef(p.schemaKey, resolveVersion(ResourceKind.Schema, p.schemaKey, p.schemaVersion, versionByKindAndKey));
+                }
+                return param;
+            });
+        }
+        if (resp.spec.returnType) {
+            const rt = {
+                type: resp.spec.returnType.type,
+            };
+            if (resp.spec.returnType.schemaKey) {
+                rt.schema = toRef(resp.spec.returnType.schemaKey, resolveVersion(ResourceKind.Schema, resp.spec.returnType.schemaKey, resp.spec.returnType.schemaVersion, versionByKindAndKey));
+            }
+            spec.returnType = rt;
+        }
+        if (resp.spec.body) {
+            spec.body = resp.spec.body;
+        }
+        return {
+            apiVersion: API_VERSION,
+            kind: 'JsonataFunction',
+            metadata: buildMetadata(resp.metadata),
+            spec,
+        };
+    }
+    // ─── File Download Helpers ────────────────────────────────────
+    /**
+     * Get a signed download URL for a file.
+     */
+    async getSignedUrl(fileId) {
+        return this.source.fetchFileDownloadUrl(this.client, fileId);
+    }
+    /**
+     * Determine file extension by making a HEAD request to the signed URL.
+     * Falls back to the default extension for the asset type if the Content-Type
+     * is unrecognized or the request fails.
+     */
+    async getFileExtension(assetType, signedUrl) {
+        try {
+            const response = await fetch(signedUrl, { method: 'HEAD' });
+            if (response.ok) {
+                const contentType = response.headers.get('content-type');
+                // Strip parameters like "; charset=utf-8" before lookup
+                const mimeType = contentType?.split(';')[0].trim();
+                if (mimeType && CONTENT_TYPE_TO_EXT[mimeType]) {
+                    return CONTENT_TYPE_TO_EXT[mimeType];
+                }
+            }
+        }
+        catch {
+            // Fall through to default
+        }
+        return ASSET_TYPE_EXT[assetType] ?? '.bin';
+    }
+}
+// ─── Shared Conversion Helpers ────────────────────────────────
+/**
+ * Resolve a version for a resource, falling back to the dependency map when
+ * the API omits schemaVersion (it's an optional field on Input).
+ */
+function resolveVersion(kind, key, version, versionByKindAndKey) {
+    return version || versionByKindAndKey.get(`${kind}:${key}`);
+}
+/** Combine key and version into "key@version" reference */
+function toRef(key, version) {
+    if (!key)
+        return undefined;
+    if (!version)
+        return key;
+    return `${key}@${version}`;
+}
+/** Build the YAML metadata block, omitting undefined fields */
+function buildMetadata(metadata) {
+    const result = {
+        key: metadata.key,
+        version: metadata.version,
+    };
+    if (metadata.name)
+        result.name = metadata.name;
+    if (metadata.description)
+        result.description = metadata.description;
+    if (metadata.labels && Object.keys(metadata.labels).length > 0) {
+        // Label keys must match ^[a-z][a-z0-9]*(_[a-z0-9]+)*$ — sanitize by
+        // converting camelCase and any invalid chars to snake_case.
+        const sanitized = {};
+        for (const [k, v] of Object.entries(metadata.labels)) {
+            const safe = k
+                .replace(/([A-Z])/g, '_$1')
+                .toLowerCase()
+                .replace(/[^a-z0-9_]/g, '_')
+                .replace(/^[^a-z]+/, '')
+                .replace(/_+/g, '_')
+                .replace(/_$/, '');
+            if (safe)
+                sanitized[safe] = v;
+        }
+        if (Object.keys(sanitized).length > 0)
+            result.labels = sanitized;
+    }
+    return result;
+}
+/**
+ * Converts a spec.functions array to YAML form.
+ * Emits object-map when any entry has a distinct alias, otherwise a plain array.
+ */
+function convertFunctionsToYaml(functions) {
+    const hasDistinctAlias = functions.some((f) => f.alias);
+    if (hasDistinctAlias) {
+        return functions.reduce((acc, f) => {
+            acc[f.alias ?? f.functionKey] = `${f.functionKey}@${f.functionVersion}`;
+            return acc;
+        }, {});
+    }
+    return functions.map((f) => `${f.functionKey}@${f.functionVersion}`);
+}
+/**
+ * Convert API LiteralOrExpression to YAML expression format.
+ * Both sides use { expression: "..." }, so this is effectively a passthrough
+ * that strips undefined/null.
+ */
+function passthroughExpression(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    return value;
+}
+/** Convert API Input to YAML input format */
+function convertInputToYaml(input, versionByKindAndKey) {
+    const result = {
+        key: input.key,
+    };
+    if (input.name)
+        result.name = input.name;
+    if (input.description)
+        result.description = input.description;
+    if (input.schemaKey) {
+        result.schema = toRef(input.schemaKey, resolveVersion(ResourceKind.Schema, input.schemaKey, input.schemaVersion, versionByKindAndKey));
+    }
+    if (typeof input.required === 'boolean') {
+        result.required = input.required;
+    }
+    else if (input.required &&
+        typeof input.required === 'object' &&
+        'expression' in input.required) {
+        result.required = input.required.expression;
+    }
+    return result;
+}
+/** Convert API TemplateRole to YAML role format */
+function convertRoleToYaml(role) {
+    const result = {
+        key: role.key,
+    };
+    if (role.name)
+        result.name = role.name;
+    if (role.roleCategory)
+        result.roleCategory = role.roleCategory;
+    if (role.output) {
+        result.output = {
+            schema: toRef(role.output.schemaKey, role.output.schemaVersion),
+            transform: role.output.transform,
+        };
+    }
+    return result;
+}
+/** Convert API TemplateFieldInfo to YAML field format */
+function convertFieldToYaml(field) {
+    const result = {
+        key: field.key,
+        type: field.type,
+    };
+    // Value (LiteralOrExpression)
+    const yamlValue = passthroughExpression(field.value);
+    if (yamlValue !== undefined)
+        result.value = yamlValue;
+    // Role
+    if (field.role)
+        result.role = field.role;
+    // includeIf
+    if (field.includeIf)
+        result.includeIf = field.includeIf;
+    // Widget (flatten from widgets[0])
+    if (field.widgets && field.widgets.length > 0) {
+        const w = field.widgets[0];
+        const widget = {};
+        if (w.position) {
+            widget.page = w.position.pageNumber;
+            widget.x = w.position.x;
+            widget.y = w.position.y;
+        }
+        if (w.dimensions) {
+            widget.width = w.dimensions.width;
+            widget.height = w.dimensions.height;
+        }
+        if (w.style) {
+            const style = {};
+            if (w.style.fontSizePx !== undefined)
+                style.fontSize = w.style.fontSizePx;
+            if (w.style.fontColor)
+                style.fontColor = w.style.fontColor;
+            if (w.style.fontFamily)
+                style.fontFamily = w.style.fontFamily;
+            if (w.style.strokeWidth !== undefined)
+                style.strokeWidth = w.style.strokeWidth;
+            if (w.style.strokeColor)
+                style.strokeColor = w.style.strokeColor;
+            if (Object.keys(style).length > 0)
+                widget.style = style;
+        }
+        if (Object.keys(widget).length > 0)
+            result.widget = widget;
+    }
+    return result;
+}
+/** Convert API BlueprintParticipant to YAML format */
+function convertParticipantToYaml(participant) {
+    // Schema requires `name` and `email`; fall back to key-derived placeholders
+    // if the API didn't store LiteralOrExpression values for them.
+    const name = passthroughExpression(participant.participantName) ??
+        participant.name ??
+        participant.key;
+    // email must be a valid address or an { expression } object — never a freeform
+    // string. Use an expression placeholder when no expression was stored on the API.
+    const email = passthroughExpression(participant.participantEmail) ?? {
+        expression: `$.${participant.key}.email`,
+    };
+    const result = {
+        key: participant.key,
+        name,
+        email,
+    };
+    if (participant.roleCategory)
+        result.roleCategory = participant.roleCategory;
+    return result;
+}
+/** Convert API BlueprintEnvelope to YAML format */
+function convertEnvelopeToYaml(envelope) {
+    const result = {
+        key: envelope.key,
+    };
+    if (envelope.subject && envelope.subject !== envelope.key) {
+        result.name = envelope.subject;
+    }
+    if (envelope.documents && envelope.documents.length > 0) {
+        result.documents = envelope.documents.map((doc) => {
+            const d = {
+                key: doc.key,
+            };
+            if (doc.templateKey) {
+                d.template = toRef(doc.templateKey, doc.templateVersion);
+            }
+            if (doc.inputMap && doc.inputMap.length > 0) {
+                const inputMap = {};
+                for (const m of doc.inputMap) {
+                    inputMap[m.templateInputKey] = m.blueprintInputKey
+                        ? `$.${m.blueprintInputKey}`
+                        : m.blueprintInputKey;
+                }
+                d.inputMap = inputMap;
+            }
+            if (doc.includeIf)
+                d.includeIf = doc.includeIf;
+            if (doc.iterator)
+                d.iterator = doc.iterator;
+            const fileIdYaml = passthroughExpression(doc.fileId);
+            if (fileIdYaml !== undefined)
+                d.fileId = fileIdYaml;
+            return d;
+        });
+    }
+    return result;
+}
+/** Recursively convert API BlueprintStep to YAML orchestration format */
+function convertOrchestrationToYaml(step) {
+    const result = {
+        key: step.key,
+        type: step.type,
+    };
+    if (step.name)
+        result.name = step.name;
+    if (step.includeIf)
+        result.includeIf = step.includeIf;
+    if (step.onComplete)
+        result.onComplete = step.onComplete;
+    if (step.type === 'group') {
+        const group = step;
+        if (group.execution)
+            result.execution = group.execution;
+        if (group.completion)
+            result.completion = group.completion;
+        if (group.quorum)
+            result.quorum = group.quorum;
+        if (group.children && group.children.length > 0) {
+            // Filter out participant steps whose action has no assignments — they
+            // are unrepresentable in the YAML schema (sign action requires minItems:1).
+            result.children = group.children
+                .filter((child) => {
+                if (child.type !== 'participant')
+                    return true;
+                const p = child;
+                return !p.action || p.action.assignments?.length > 0;
+            })
+                .map(convertOrchestrationToYaml);
+        }
+    }
+    else {
+        const participant = step;
+        if (participant.participantKey) {
+            result.participant = participant.participantKey;
+        }
+        if (participant.action && participant.action.assignments?.length > 0) {
+            result.action = {
+                type: participant.action.type,
+                envelope: participant.action.envelopeKey,
+                assignments: participant.action.assignments.map((a) => ({
+                    document: a.documentKey,
+                    role: a.roleKey,
+                })),
+            };
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=resource-puller.js.map