@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/dist/ui-page-plugin.js

@@ -2,9 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UiPagePlugin = void 0;
 const sdk_build_core_1 = require("@servicenow/sdk-build-core");
-const sdk_build_core_2 = require("@servicenow/sdk-build-core");
 const fast_xml_parser_1 = require("fast-xml-parser");
+const xmlbuilder2_1 = require("xmlbuilder2");
 const now_id_plugin_1 = require("./now-id-plugin");
+const static_content_plugin_1 = require("./static-content-plugin");
+const now_attach_plugin_1 = require("./now-attach-plugin");
 const parserOptions = {
     ignoreAttributes: false,
     alwaysCreateTextNode: true,
@@ -31,6 +33,49 @@ const builderOptions = {
     ],
 };
 const POLARIS_APPSHELL_THEME_ID = 'c86a62e2c7022010099a308dc7c26022';
+const BYOUI_ARTIFACT_NAME_SUFFIX = 'BYOUI Files';
+// Matches the prefix HtmlImportPlugin prepends when it resolves an `import x from '*.html'`
+// identifier. Its presence on the html value means the developer used the import variable,
+// not an inline string — the only case where a source artifact should be created.
+const HTML_IMPORT_PREFIX = '<!-- @fluent-import-html';
+// sys_update_xml.payload has a max length of 4,096,000 characters. The artifact content goes
+// through two rounds of base64 encoding with gzip compression in between:
+//   raw → base64 → gzip → base64 (stored in sys_attachment_doc.data)
+// This means payload_chars ≈ raw_bytes × (4/3) × C × (4/3) = raw_bytes × 16C/9, where C is the
+// gzip compression ratio. For typical TS/JS source files (C ≈ 0.25), 4 MB of raw source produces
+// ~1.8 MB of payload data — safely within the 4,096,000-character limit.
+const MAX_FILE_SIZE = 2 * 1024 * 1024; // 2 MB — per-file guard (half of total budget)
+const MAX_TOTAL_SIZE = 4 * 1024 * 1024; // 4 MB — derived from sys_update_xml.payload limit
+/**
+ * Relationship configuration for source artifact tables.
+ *
+ * Defines the hierarchy: M2M → Artifact → Attachment → Attachment Docs
+ */
+const SOURCE_ARTIFACT_RELATIONSHIPS = {
+    sn_glider_source_artifact_m2m: {
+        via: 'application_file',
+        descendant: true,
+        relationships: {
+            sn_glider_source_artifact: {
+                via: 'source_artifact',
+                inverse: true,
+                descendant: true,
+                relationships: {
+                    sys_attachment: {
+                        via: 'table_sys_id',
+                        descendant: true,
+                        relationships: {
+                            sys_attachment_doc: {
+                                via: 'sys_attachment',
+                                descendant: true,
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
 const parser = new fast_xml_parser_1.XMLParser(parserOptions);
 // TODO: Remove this shim tag once we've shipped Glide support for this feature.
 const nowUxGlobals = (themeId = POLARIS_APPSHELL_THEME_ID) => {
@@ -72,6 +117,9 @@ const nodeTransformer = (nodes) => {
     for (let i = 0; i < nodes.length; i++) {
         const node = nodes[i];
         const tag = Object.keys(node)[0];
+        if (!tag) {
+            continue;
+        }
         if (tag === 'sdk:now-ux-globals') {
             const themeId = node[':@']?.['@_theme-id'];
             nodes.splice(i, 1, ...nowUxGlobals(themeId));
@@ -88,7 +136,23 @@ exports.UiPagePlugin = sdk_build_core_1.Plugin.create({
     name: 'UiPagePlugin',
     records: {
         sys_ui_page: {
-            toShape(record) {
+            composite: true,
+            coalesce: ['endpoint'],
+            relationships: SOURCE_ARTIFACT_RELATIONSHIPS,
+            async toShape(record, { descendants, fs, project, config, logger, diagnostics }) {
+                const shapeWithSourceArtifacts = await getShapeWithSourceArtifacts(record, descendants, {
+                    fs,
+                    project,
+                    config,
+                    logger,
+                    diagnostics,
+                });
+                if (shapeWithSourceArtifacts) {
+                    return {
+                        success: true,
+                        value: shapeWithSourceArtifacts,
+                    };
+                }
                 return {
                     success: true,
                     value: new sdk_build_core_1.CallExpressionShape({
@@ -109,25 +173,132 @@ exports.UiPagePlugin = sdk_build_core_1.Plugin.create({
                     }),
                 };
             },
+            async toFile(uiPage, { config, descendants, transform }) {
+                if (!uiPage.has('endpoint')) {
+                    return { success: false };
+                }
+                // Only use custom serialization if source artifacts are present
+                const sourceArtifacts = descendants.query('sn_glider_source_artifact_m2m');
+                if (sourceArtifacts.length === 0) {
+                    // No source artifacts, use default serialization
+                    return { success: false };
+                }
+                const uiPagePropsToSerialize = [
+                    'name',
+                    'endpoint',
+                    'description',
+                    'direct',
+                    'category',
+                    'html',
+                    'client_script',
+                    'processing_script',
+                ];
+                const result = await serializeWithArtifact(uiPage, uiPagePropsToSerialize, {
+                    config,
+                    descendants,
+                    transform,
+                });
+                return {
+                    success: true,
+                    value: result,
+                };
+            },
+        },
+        // These records are embedded as descendants of sys_ui_page XML but are also
+        // downloaded as standalone records during `init + transform`. Defining coalesce
+        // here ensures their sys_ids are registered in keys.ts during transform, so
+        // subsequent builds by any user reuse the same IDs rather than generating fresh UUIDs.
+        sn_glider_source_artifact: {
+            coalesce: ['name'],
+            relationships: SOURCE_ARTIFACT_RELATIONSHIPS.sn_glider_source_artifact_m2m.relationships.sn_glider_source_artifact
+                .relationships,
+            async toShape(record) {
+                return { success: true, value: sdk_build_core_1.Shape.noOp(record) };
+            },
+            // Custom diff: attachments use hash-based immutable IDs. New content → new attachment ID.
+            // Stale cleanup is handled via delete_multiple in serializeWithArtifact, so we must NOT
+            // emit DELETE records here — the default diff would conflict with that mechanism.
+            async diff(existing, incoming) {
+                if (incoming.query().length === 0 || existing.query().length === 0) {
+                    return {
+                        success: true,
+                        value: incoming.query().length === 0 ? new sdk_build_core_1.Database() : new sdk_build_core_1.Database(incoming.query()),
+                    };
+                }
+                const changedRecords = [];
+                const existingArtifacts = existing.query('sn_glider_source_artifact');
+                const incomingArtifacts = incoming.query('sn_glider_source_artifact');
+                const incomingAttachments = incoming.query('sys_attachment');
+                const incomingAttachmentDocs = incoming.query('sys_attachment_doc');
+                for (const incomingArtifact of incomingArtifacts) {
+                    const existingArtifact = existingArtifacts.find((a) => a.getId().getValue() === incomingArtifact.getId().getValue());
+                    changedRecords.push(existingArtifact ? existingArtifact.merge(incomingArtifact) : incomingArtifact);
+                    // Always add new attachments — unique hash-based IDs per content version.
+                    const artifactAttachments = incomingAttachments.filter((att) => att.get('table_sys_id').toString().getValue() === incomingArtifact.getId().getValue());
+                    for (const attachment of artifactAttachments) {
+                        changedRecords.push(attachment);
+                        changedRecords.push(...incomingAttachmentDocs.filter((doc) => doc.get('sys_attachment').toString().getValue() === attachment.getId().getValue()));
+                    }
+                }
+                return { success: true, value: new sdk_build_core_1.Database(changedRecords) };
+            },
+        },
+        sn_glider_source_artifact_m2m: {
+            coalesce: ['application_file', 'source_artifact'],
+            relationships: SOURCE_ARTIFACT_RELATIONSHIPS.sn_glider_source_artifact_m2m.relationships,
+            async toShape(record) {
+                return { success: true, value: sdk_build_core_1.Shape.noOp(record) };
+            },
+            async toFile() {
+                // Page M2Ms are already in handledGuids as descendants of sys_ui_page, so
+                // this handler only runs for asset M2Ms (application_file = sys_ux_lib_asset
+                // sys_id). Those are embedded in each sys_ux_lib_asset XML by
+                // static-content-plugin via sourceArtifactRelationships. Return success with
+                // no output to mark them as handled and prevent RecordPlugin's catch-all from
+                // serializing them as standalone XMLs.
+                return { success: true, value: [] };
+            },
         },
     },
     shapes: [
         {
             shape: sdk_build_core_1.CallExpressionShape,
             fileTypes: ['fluent'],
-            async toRecord(callExpression, { config, factory, diagnostics }) {
+            async toRecord(callExpression, { config, factory, diagnostics, fs, project, logger }) {
                 if (callExpression.getCallee() !== 'UiPage') {
                     return { success: false };
                 }
                 const arg = callExpression.getArgument(0).asObject();
                 const endpoint = arg.get('endpoint').asString();
                 const scope = config.scope;
-                if (scope !== 'global' && !(0, sdk_build_core_2.isSNScope)(scope) && !endpoint.getValue().startsWith(`${scope}_`)) {
+                if (scope !== 'global' && !(0, sdk_build_core_1.isSNScope)(scope) && !endpoint.getValue().startsWith(`${scope}_`)) {
                     diagnostics.error(endpoint.getOriginalNode(), `endpoint must begin with '${scope}_'`);
                     return { success: false };
                 }
                 const name = endpoint.asString().getValue().replace(`${scope}_`, '').replace(/\.do$/, '');
                 let html = arg.get('html').toString().getValue();
+                let sourceFilePaths = [];
+                let assetNames = [];
+                // HtmlImportPlugin (which runs before toRecord) resolves `html: _html` identifiers
+                // to the file content and prepends an HTML_IMPORT_PREFIX warning comment.
+                // Source artifacts are only created when that prefix is present, meaning the html
+                // argument actually referenced an imported .html file.
+                // An inline string (e.g. `html: '<h1>...</h1>'`) never gets the prefix, so an
+                // unrelated `.html` import in the same file does NOT trigger artifact creation.
+                if (html.trimStart().startsWith(HTML_IMPORT_PREFIX)) {
+                    const originalNode = callExpression.getOriginalNode();
+                    const sourceFile = originalNode.getSourceFile();
+                    // biome-ignore lint/suspicious/noExplicitAny: ts-morph ImportDeclaration type not exported
+                    const htmlImport = sourceFile.getImportDeclarations().find((imp) => imp.getModuleSpecifierValue().endsWith('.html'));
+                    if (htmlImport) {
+                        const relativeHtmlPath = htmlImport.getModuleSpecifierValue();
+                        const sourceFileDir = sdk_build_core_1.path.dirname(sourceFile.getFilePath());
+                        const absoluteHtmlPath = sdk_build_core_1.path.resolve(sourceFileDir, relativeHtmlPath);
+                        const manifest = getUIPageSourceFilePaths(absoluteHtmlPath, fs, logger, config, project.getRootDir());
+                        sourceFilePaths = manifest.files;
+                        assetNames = manifest.assetNames;
+                    }
+                }
                 if (html) {
                     try {
                         const nodes = parser.parse(html);
@@ -144,26 +315,668 @@ exports.UiPagePlugin = sdk_build_core_1.Plugin.create({
                         return { success: false };
                     }
                 }
+                const record = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_ui_page',
+                    explicitId: arg.get('$id'),
+                    properties: arg.transform(({ $ }) => ({
+                        name: $.val(name),
+                        endpoint: $.val(endpoint),
+                        description: $,
+                        direct: $.def(false),
+                        category: $,
+                        html: $.val(html).toCdata(),
+                        client_script: $.from('clientScript').toCdata(),
+                        processing_script: $.from('processingScript').toCdata(),
+                    })),
+                });
+                // Build source artifact if source files are present in the manifest
+                if (sourceFilePaths.length > 0) {
+                    logger.debug(`Found ${sourceFilePaths.length} source files in manifest`);
+                    // Manifest files already contain paths relative to project root
+                    const files = sourceFilePaths.map((file) => file.replace(/\\/g, '/'));
+                    const prebuildPath = sdk_build_core_1.path.join(project.getRootDir(), 'now.prebuild.mjs');
+                    if (sdk_build_core_1.FileSystem.existsSync(fs, prebuildPath)) {
+                        files.push('now.prebuild.mjs');
+                    }
+                    const artifactName = `${endpoint.getValue()} - ${BYOUI_ARTIFACT_NAME_SUFFIX}`;
+                    const sourceArtifactRecords = await buildArtifact(artifactName, files, record, {
+                        fs,
+                        project,
+                        factory,
+                        config,
+                        logger,
+                        diagnostics,
+                    }, assetNames);
+                    if (sourceArtifactRecords.length > 0) {
+                        record.with(...sourceArtifactRecords);
+                    }
+                    else {
+                        diagnostics.warn(record, 'No source artifact records were created despite source files being present');
+                    }
+                }
                 return {
                     success: true,
-                    value: await factory.createRecord({
-                        source: callExpression,
-                        table: 'sys_ui_page',
-                        explicitId: arg.get('$id'),
-                        properties: arg.transform(({ $ }) => ({
-                            name: $.val(name),
-                            endpoint: $.val(endpoint),
-                            description: $,
-                            direct: $.def(false),
-                            category: $,
-                            html: $.val(html).toCdata(),
-                            client_script: $.from('clientScript').toCdata(),
-                            processing_script: $.from('processingScript').toCdata(),
-                        })),
-                    }),
+                    value: record,
                 };
             },
         },
     ],
 });
+/**
+ * Reads source file paths from the UI source manifest file.
+ *
+ * The manifest is generated by isomorphic-rollup's sourceManifest plugin during build.
+ * It's a JSON file with the structure: { html, entry, files: string[] }
+ *
+ * @param htmlFilePath - Path to the HTML file
+ * @param fs - File system interface
+ * @param logger - Logger for diagnostics
+ * @param config - NowConfig with staticContentDir
+ * @param rootDir - Project root directory
+ * @returns Array of source file paths (empty array if manifest not found)
+ */
+const getUIPageSourceFilePaths = (htmlFilePath, fs, logger, config, rootDir) => {
+    const empty = { files: [], assetNames: [] };
+    try {
+        // Derive manifest path from HTML path
+        // The manifest is in the build output directory (staticContentDir), not the source directory
+        // e.g., src/client/index.html -> dist/static/index.ui-source-manifest.json
+        const htmlBasename = sdk_build_core_1.path.basename(htmlFilePath, '.html');
+        const staticContentAbsDir = sdk_build_core_1.path.join(rootDir, config.staticContentDir);
+        const manifestPath = sdk_build_core_1.path.join(staticContentAbsDir, `${htmlBasename}.ui-source-manifest.json`);
+        // Check if manifest file exists
+        try {
+            fs.accessSync(manifestPath);
+        }
+        catch {
+            logger.debug(`No source manifest found at ${manifestPath}`);
+            return empty;
+        }
+        const manifestContent = fs.readFileSync(manifestPath, { encoding: 'utf-8' });
+        const manifest = JSON.parse(manifestContent);
+        if (!manifest.files || !Array.isArray(manifest.files)) {
+            logger.warn(`Invalid manifest format at ${manifestPath}`);
+            return empty;
+        }
+        // Derive the JS asset name from the manifest's entry field, matching
+        // static-content-plugin's formula: path.join(scope, relativePath_without_ext).
+        // The manifest file is named after the HTML entry (e.g. index.ui-source-manifest.json)
+        // but the JS bundle is named after the JS entry (e.g. main.tsx -> main.jsdbx).
+        // Using manifest.entry's basename ensures the names align.
+        if (!manifest.entry || typeof manifest.entry !== 'string') {
+            logger.warn(`No entry field in manifest at ${manifestPath}`);
+            return empty;
+        }
+        const entryBasename = sdk_build_core_1.path.basename(manifest.entry, sdk_build_core_1.path.extname(manifest.entry));
+        const entryAssetName = sdk_build_core_1.path.join(config.scope, entryBasename).replace(/\\/g, '/');
+        // Check if a source map bundle also exists in staticContentDir.
+        // static-content-plugin names source map assets as: path.join(scope, relativePath.replace('dbx', ''))
+        // e.g. main.jsdbx.map -> main.js.map -> scope/main.js.map
+        const assetNames = [entryAssetName];
+        const sourceMapFilePath = sdk_build_core_1.path.join(staticContentAbsDir, `${entryBasename}.jsdbx.map`);
+        try {
+            fs.accessSync(sourceMapFilePath);
+            const sourceMapAssetName = sdk_build_core_1.path.join(config.scope, `${entryBasename}.js.map`).replace(/\\/g, '/');
+            assetNames.push(sourceMapAssetName);
+        }
+        catch {
+            // no source map in this build output — skip
+        }
+        return { files: manifest.files, assetNames };
+    }
+    catch (error) {
+        logger.warn(`Failed to read source manifest: ${error}`);
+        return empty;
+    }
+};
+/**
+ * Extracts source files from artifacts and generates a SourceFileShape for the UI page.
+ *
+ * This function is called during transform to:
+ * 1. Find the source artifact associated with the UI page
+ * 2. Extract source files to the project directory
+ * 3. Generate a .now.ts file that imports the extracted HTML
+ *
+ * @param uiPageRecord - The UI page record being transformed
+ * @param descendants - Database containing descendant records (artifacts, attachments)
+ * @param context - Transform context with config, file system, project, diagnostics, and logger
+ * @returns SourceFileShape for the UI page, or undefined if no source artifact found
+ */
+async function getShapeWithSourceArtifacts(uiPageRecord, descendants, context) {
+    const sourceArtifact = getSourceArtifact(descendants, { name: new RegExp(`${BYOUI_ARTIFACT_NAME_SUFFIX}$`) });
+    if (!sourceArtifact) {
+        return undefined;
+    }
+    const artifactName = sourceArtifact.get('name').toString().getValue();
+    context.logger.debug(`Found source artifact ${artifactName}`);
+    const unpackedFiles = await extractArtifact(sourceArtifact, descendants, '', {
+        fs: context.fs,
+        project: context.project,
+        logger: context.logger,
+        diagnostics: context.diagnostics,
+    });
+    context.logger.debug(`Unpacked ${unpackedFiles.length} files from artifact ${artifactName}`);
+    const entryHtmlFilePath = unpackedFiles.find((file) => file.endsWith('.html'));
+    if (!entryHtmlFilePath) {
+        context.logger.debug(`Failed to find entry HTML file in artifact ${artifactName}`);
+        return undefined;
+    }
+    const { generatedDir, taxonomy } = context.config;
+    const tableName = uiPageRecord.getTable();
+    const fluentFileDirByTaxonomy = tableName && taxonomy.mapping[tableName] ? sdk_build_core_1.path.join(generatedDir, taxonomy.mapping[tableName]) : generatedDir;
+    const originalFilePath = uiPageRecord.getOriginalFilePath();
+    let dirWhereTheFluentFileWillExistEventually = sdk_build_core_1.path.dirname(originalFilePath);
+    if (context.project.isInMetadataDir(originalFilePath) || !context.project.isInRootDir(originalFilePath)) {
+        // context.project.isInMetadataDir(originalFilePath) => init --from downloads XML to metadata dir
+        // !context.project.isInRootDir(originalFilePath) => simple transform downloads XML is in a temp metadata dir
+        dirWhereTheFluentFileWillExistEventually = fluentFileDirByTaxonomy;
+    }
+    // need an import statement for the html file; normalize to forward slashes for cross-platform imports
+    const htmlFileRelativePath = sdk_build_core_1.path
+        .relative(dirWhereTheFluentFileWillExistEventually, entryHtmlFilePath)
+        .replace(/\\/g, '/');
+    if (htmlFileRelativePath && !context.project.isInFluentDir(originalFilePath)) {
+        const endpoint = uiPageRecord.get('endpoint').toString().getValue();
+        const description = uiPageRecord.get('description').toString().getValue();
+        const category = uiPageRecord.get('category').toString().getValue();
+        const direct = uiPageRecord.get('direct').toString().getValue();
+        const clientScript = uiPageRecord.get('client_script').toString().getValue();
+        const processingScript = uiPageRecord.get('processing_script').toString().getValue();
+        const fileContent = `
+            import '@servicenow/sdk/global'
+            import { UiPage } from '@servicenow/sdk/core'
+            import htmlFile from '${htmlFileRelativePath}'
+
+            UiPage({
+                $id: Now.ID['${uiPageRecord.getId().getValue()}'],
+                endpoint: ${JSON.stringify(endpoint)},
+                description: ${JSON.stringify(description)},
+                category: ${JSON.stringify(category)},
+                direct: ${direct},
+                html: htmlFile,
+                clientScript: ${JSON.stringify(clientScript)},
+                processingScript: ${JSON.stringify(processingScript)},
+            })
+        `;
+        const newFileName = endpoint.replace('.do', '.now.ts');
+        const sourceFileShape = new sdk_build_core_1.SourceFileShape({
+            source: uiPageRecord,
+            path: `${sdk_build_core_1.path.join(fluentFileDirByTaxonomy, newFileName)}`,
+            content: fileContent,
+        });
+        return sourceFileShape;
+    }
+    return undefined;
+}
+// ─── Source Artifact: Build ───────────────────────────────────────────────────
+//
+// Asset M2M coordination between UiPagePlugin and StaticContentPlugin:
+//
+// UiPagePlugin creates two kinds of M2M records:
+//   - Page M2M  (application_file = sys_ui_page sys_id): embedded in sys_ui_page XML.
+//   - Asset M2Ms (application_file = sys_ux_lib_asset sys_id): embedded in
+//     sys_ux_lib_asset XML by StaticContentPlugin (transform direction), or claimed
+//     with no output by sn_glider_source_artifact_m2m.toFile (build direction) to
+//     prevent RecordPlugin from serializing them as standalone XMLs.
+//
+// A dummy sys_ux_lib_asset is created (but not added to the build database) solely
+// to derive the same stable sys_id that StaticContentPlugin would use, ensuring both
+// plugins always agree on the asset's sys_id.
+/**
+ * Builds a source artifact record from the given files and associates it with the provided metadata record.
+ *
+ * Reads files from disk, encodes them as base64, compresses with gzip, creates
+ * artifact/attachment/attachment_doc records with hash-based IDs, and links to metadata via M2M.
+ *
+ * @param artifactName - Descriptive name for the artifact (e.g., "home_page.do - BYOUI Files")
+ * @param files - Array of file paths relative to project root
+ * @param record - Parent metadata record to link to (the artifact will be associated via M2M)
+ * @param context - Build context (fs, project, factory, config, logger, diagnostics)
+ * @returns Array of records: artifact, attachment, attachment docs, M2M link record, and
+ *          per-asset M2M records (one per assetName). Returns empty array if no files
+ *          provided or all files were skipped.
+ */
+async function buildArtifact(artifactName, files, record, context, assetNames) {
+    if (files.length === 0) {
+        return [];
+    }
+    const { files: attachmentFiles, skippedFiles, totalSize, } = await getAttachmentContent(context.fs, context.project.getRootDir(), files);
+    // Report skipped files as warnings before the empty-content check so the
+    // caller knows *why* no records were created (e.g. all files exceeded size limits).
+    for (const warning of skippedFiles) {
+        context.diagnostics.warn(record, warning);
+    }
+    if (!attachmentFiles.size) {
+        context.logger.warn(`No source artifact records created for "${artifactName}": all ${files.length} source file(s) were skipped`);
+        return [];
+    }
+    const artifactRecord = await createArtifactRecord(artifactName, record, context);
+    const attachmentRecords = await createAttachmentRecords(context.factory, artifactRecord, attachmentFiles, totalSize);
+    const m2mRecord = await createArtifactM2mRecord(artifactRecord, record, context);
+    const totalSizeMB = (totalSize / (1024 * 1024)).toFixed(2);
+    context.logger.info(`Built source artifact "${artifactName}" (${totalSizeMB} MB, ${files.length} files)`);
+    const assetM2mRecords = await Promise.all((assetNames ?? []).map((assetName) => createAssetArtifactM2mRecord(artifactRecord, assetName, record, context)));
+    return [artifactRecord, ...attachmentRecords, m2mRecord, ...assetM2mRecords];
+}
+const createArtifactRecord = async (artifactName, metadataRecord, context) => {
+    return context.factory.createRecord({
+        source: metadataRecord.getSource(),
+        table: 'sn_glider_source_artifact',
+        explicitId: artifactName,
+        properties: {
+            name: artifactName,
+        },
+    });
+};
+const createArtifactM2mRecord = async (artifactRecord, metadataRecord, context) => {
+    return context.factory.createRecord({
+        source: metadataRecord.getSource(),
+        table: 'sn_glider_source_artifact_m2m',
+        explicitId: `${metadataRecord.getId().getValue()}-${artifactRecord.getId().getValue()}`,
+        properties: {
+            application_file: metadataRecord.getId().getValue(),
+            source_artifact: artifactRecord.getId().getValue(),
+        },
+    });
+};
+/**
+ * Creates a sn_glider_source_artifact_m2m record linking the given asset to the source artifact.
+ *
+ * A dummy sys_ux_lib_asset record is created with the same explicitId as static-content-plugin's
+ * real asset so both plugins resolve to the same sys_id. Only the M2M record is returned and
+ * added to the page's .with() tree so it enters the build database. static-content-plugin picks
+ * up the M2M via sourceArtifactRelationships (application_file = assetSysId) and embeds it in
+ * the sys_ux_lib_asset XML. UiPagePlugin's sn_glider_source_artifact_m2m.toFile marks the M2M as
+ * handled so RecordPlugin does not serialize it as a standalone XML in fluentFile.getOutput().
+ */
+const createAssetArtifactM2mRecord = async (artifactRecord, entryAssetName, metadataRecord, context) => {
+    const dummyAsset = await context.factory.createRecord({
+        source: metadataRecord.getSource(),
+        table: 'sys_ux_lib_asset',
+        explicitId: entryAssetName,
+        properties: {
+            name: entryAssetName,
+        },
+    });
+    return context.factory.createRecord({
+        source: metadataRecord.getSource(),
+        table: 'sn_glider_source_artifact_m2m',
+        explicitId: `${dummyAsset.getId().getValue()}-${artifactRecord.getId().getValue()}`,
+        properties: {
+            application_file: dummyAsset.getId().getValue(),
+            source_artifact: artifactRecord.getId().getValue(),
+        },
+    });
+};
+/**
+ * Creates attachment and attachment_doc records for the artifact.
+ *
+ * Attachments are compressed using zip and chunked for storage. The attachment ID includes
+ * a hash prefix to ensure immutability (each content version gets a unique ID).
+ */
+const createAttachmentRecords = async (factory, artifactRecord, files, totalSize) => {
+    // Build zip entries with a fixed mtime for deterministic output.
+    // ZIP format only supports dates 1980-2099; we use the minimum valid date.
+    // new Date(1982, 0, 1) creates midnight January 1, 1982 in local time,
+    // which fflate's local-time date encoding renders identically in any timezone.
+    const FIXED_MTIME = new Date(1982, 0, 1);
+    const zipEntries = {};
+    for (const [filePath, content] of files) {
+        zipEntries[filePath] = [content, { mtime: FIXED_MTIME }];
+    }
+    const zipped = (0, sdk_build_core_1.zipSync)(zipEntries);
+    const compressedData = Buffer.from(zipped);
+    const hash = await (0, now_attach_plugin_1.sha256)(compressedData);
+    // Uniform chunking — no special header split
+    const allChunks = (0, static_content_plugin_1.chunkData)(compressedData.toString('base64'));
+    // Deterministic sys_id derived from artifact + content hash — no keys registry entry needed.
+    // Same content always produces the same attachment ID without inflating keys.json.
+    const attachmentSysId = (0, static_content_plugin_1.generateId)(artifactRecord.getId().getValue(), 'sys_attachment', hash);
+    const attachment = await factory.createRecord({
+        source: artifactRecord.getSource(),
+        table: 'sys_attachment',
+        properties: {
+            sys_id: attachmentSysId,
+            average_image_color: '',
+            chunk_size_bytes: static_content_plugin_1.CHUNK_SIZE,
+            compressed: true,
+            content_type: 'application/zip',
+            hash,
+            image_height: '',
+            image_width: '',
+            size_bytes: totalSize,
+            size_compressed: compressedData.length,
+            file_name: `${artifactRecord.get('name').getValue()}.zip`,
+            table_name: artifactRecord.getTable(),
+            table_sys_id: artifactRecord.getId().getValue(),
+        },
+    });
+    const attachmentDocs = [];
+    for (let i = 0; i < allChunks.length; i++) {
+        const doc = await factory.createRecord({
+            source: artifactRecord.getSource(),
+            table: 'sys_attachment_doc',
+            properties: {
+                sys_id: (0, static_content_plugin_1.generateId)(attachmentSysId, 'sys_attachment_doc', i),
+                data: allChunks[i],
+                position: i,
+                sys_attachment: attachment.getId().getValue(),
+            },
+        });
+        attachmentDocs.push(doc);
+    }
+    return [attachment, ...attachmentDocs];
+};
+/**
+ * Reads files from disk and collects them for attachment storage.
+ *
+ * Error handling uses two distinct strategies:
+ * - **Recoverable** (per-file): files that cannot be read or exceed the per-file size limit are
+ *   skipped and their paths are collected in the returned `skippedFiles` array.
+ * - **Fatal** (aggregate): if adding a file would push the total over `MAX_TOTAL_SIZE`, an error
+ *   is thrown immediately.
+ *
+ * @returns Map of file paths to raw buffers, total size in bytes, and array of warning messages for skipped files
+ * @throws {Error} if the cumulative size of valid files would exceed `MAX_TOTAL_SIZE`
+ */
+const getAttachmentContent = async (fs, rootDir, files) => {
+    const fileMap = new Map();
+    let totalSize = 0;
+    const skippedFiles = [];
+    for (const filePath of files) {
+        let content;
+        try {
+            const absolutePath = sdk_build_core_1.path.join(rootDir, filePath.replace(/^[/\\]/, ''));
+            content = fs.readFileSync(absolutePath);
+        }
+        catch (error) {
+            skippedFiles.push(`Failed to read file ${filePath}: ${error}`);
+            continue;
+        }
+        const fileSize = content.length;
+        if (fileSize > MAX_FILE_SIZE) {
+            const sizeMB = (fileSize / (1024 * 1024)).toFixed(2);
+            skippedFiles.push(`Skipping file ${filePath}: exceeds max file size (${sizeMB} MB)`);
+            continue;
+        }
+        if (totalSize + fileSize > MAX_TOTAL_SIZE) {
+            const currentMB = (totalSize / (1024 * 1024)).toFixed(2);
+            const limitMB = (MAX_TOTAL_SIZE / (1024 * 1024)).toFixed(0);
+            throw new Error(`Total artifact size would exceed limit (${currentMB}/${limitMB} MB)`);
+        }
+        fileMap.set(filePath, content);
+        totalSize += fileSize;
+    }
+    return { files: fileMap, totalSize, skippedFiles };
+};
+// ─── Source Artifact: Extract ─────────────────────────────────────────────────
+/**
+ * Extracts and unpacks files from a source artifact record.
+ *
+ * Finds attachments for the artifact, reconstructs compressed data from chunks,
+ * decompresses with unzipSync, and writes files to disk.
+ *
+ * @param artifactRecord - The source artifact record (type: sn_glider_source_artifact)
+ * @param allDescendants - Query interface to access attachment and attachment_doc records
+ * @param targetDir - Target directory path relative to project root (use '' for project root)
+ * @param context - Context with fs, project, logger, diagnostics
+ * @returns Array of file paths that were unpacked (relative to project root)
+ */
+async function extractArtifact(artifactRecord, allDescendants, targetDir = '', context) {
+    const artifactSysId = artifactRecord.getId().getValue();
+    // Find all attachments for this artifact and select the most recent one
+    const allAttachments = allDescendants.query('sys_attachment');
+    const matchingAttachments = allAttachments
+        .filter((att) => att.get('table_sys_id').toString().getValue() === artifactSysId)
+        .sort((a, b) => {
+        const aTime = a.get('sys_created_on').toString().getValue();
+        const bTime = b.get('sys_created_on').toString().getValue();
+        return aTime.localeCompare(bTime);
+    });
+    if (matchingAttachments.length === 0) {
+        context.logger.debug(`No attachments found for artifact ${artifactSysId}`);
+        return [];
+    }
+    // Use the most recent attachment (last after sorting by creation time)
+    const latestAttachment = matchingAttachments.at(-1);
+    if (!latestAttachment) {
+        return [];
+    }
+    // Get attachment docs (chunks) for the latest attachment
+    const allAttachmentDocs = allDescendants.query('sys_attachment_doc');
+    const attachmentDocs = allAttachmentDocs.filter((doc) => doc.get('sys_attachment').toString().getValue() === latestAttachment.getId().getValue());
+    if (attachmentDocs.length === 0) {
+        context.logger.debug(`No attachment docs found for attachment ${latestAttachment.getId().getValue()}`);
+        return [];
+    }
+    // Sort docs by position to ensure correct byte order
+    const sortedDocs = attachmentDocs.sort((a, b) => Number(a.get('position').toString().getValue()) - Number(b.get('position').toString().getValue()));
+    // Reconstruct zip bytes from all chunks uniformly
+    const chunks = sortedDocs.map((doc) => Buffer.from(doc.get('data').toString().getValue(), 'base64'));
+    const compressedData = Buffer.concat(chunks);
+    // Decompress — returns { [filePath]: Uint8Array }
+    const entries = (0, sdk_build_core_1.unzipSync)(compressedData);
+    const unpackedFiles = [];
+    for (const [filePath, data] of Object.entries(entries)) {
+        try {
+            const fileContent = Buffer.from(data);
+            const absolutePath = sdk_build_core_1.path.join(context.project.getRootDir(), targetDir, filePath);
+            const dir = sdk_build_core_1.path.dirname(absolutePath);
+            context.fs.mkdirSync(dir, { recursive: true });
+            context.fs.writeFileSync(absolutePath, fileContent);
+            context.project.addFile({ path: absolutePath, content: fileContent.toString('utf-8') });
+            unpackedFiles.push(filePath);
+            context.logger.debug(`Extracted file: ${filePath}`);
+        }
+        catch (error) {
+            context.diagnostics.error(artifactRecord, `Failed to write file ${filePath}: ${error}`);
+        }
+    }
+    if (unpackedFiles.length > 0) {
+        context.logger.info(`Extracted ${unpackedFiles.length} files from artifact "${artifactRecord.get('name').toString().getValue()}"`);
+    }
+    return unpackedFiles;
+}
+/**
+ * Finds a source artifact record by ID or name pattern in descendants.
+ *
+ * @param descendants - Query interface to access source artifact records
+ * @param query - Search criteria: use either id (exact sys_id) OR name (regex against name)
+ * @returns The matching source artifact record, or undefined if not found
+ */
+function getSourceArtifact(descendants, query) {
+    return descendants.query('sn_glider_source_artifact').find((record) => {
+        if (query.id) {
+            return record.getId().getValue() === query.id;
+        }
+        if (query.name) {
+            const nameMatch = record.get('name').toString().getValue().match(query.name);
+            return nameMatch && nameMatch.length > 0;
+        }
+        return false;
+    });
+}
+// ─── Source Artifact: Serialize ───────────────────────────────────────────────
+/**
+ * Serializes a metadata record along with its embedded source artifacts to XML.
+ *
+ * Creates a custom XML format where source artifacts, attachments, M2M records,
+ * and the parent metadata record are all embedded within a single XML file.
+ *
+ * The generated XML contains (in order):
+ * 1. M2M records (sn_glider_source_artifact_m2m)
+ * 2. Artifact records (sn_glider_source_artifact)
+ * 3. Attachment records (sys_attachment)
+ * 4. Attachment doc records (sys_attachment_doc)
+ * 5. Parent metadata record
+ *
+ * Also emits delete_multiple elements to clean up stale attachments per artifact,
+ * since attachments use hash-based IDs that change with each new content version.
+ *
+ * @param metadataRecord - The main metadata record (e.g., sys_ui_page)
+ * @param metadataProps - List of property names to serialize from the metadata record
+ * @param context - Serialization context (descendants, config, transform)
+ */
+async function serializeWithArtifact(metadataRecord, metadataProps, context) {
+    const recordUpdate = (0, xmlbuilder2_1.create)().ele('record_update', { table: metadataRecord.getTable() });
+    // Embed the metadata record itself at the root, before descendant records
+    const metadataElement = recordUpdate.ele(metadataRecord.getTable(), { action: metadataRecord.getAction() });
+    metadataElement.ele('sys_id').txt(metadataRecord.getId().getValue());
+    metadataElement.ele('sys_scope', { display_value: context.config.scope }).txt(context.config.scopeId);
+    const updateName = await context.transform.getUpdateName(metadataRecord);
+    metadataElement.ele('sys_update_name').txt(updateName);
+    for (const prop of metadataProps) {
+        const value = metadataRecord.get(prop);
+        if (value.isDefined()) {
+            const stringValue = value.toString().getValue();
+            const contentType = value.toString().getContentType();
+            if (stringValue) {
+                if (contentType === 'plain') {
+                    metadataElement.ele(prop).txt(stringValue);
+                }
+                else {
+                    // Handle CDATA content
+                    // The ]]> sequence terminates CDATA, so we escape it as: ]]]]><![CDATA[>
+                    // This creates: <![CDATA[content before]]]]><![CDATA[>content after]]>
+                    if (stringValue.includes(']]>')) {
+                        // Split by ]]> and create multiple adjacent CDATA sections
+                        const parts = stringValue.split(']]>');
+                        const propElement = metadataElement.ele(prop);
+                        // Create adjacent CDATA sections for each part
+                        // First part
+                        propElement.dat(`${parts[0]}]]`);
+                        // Remaining parts (each starts with a new CDATA section containing >)
+                        for (let i = 1; i < parts.length; i++) {
+                            propElement.dat(`>${parts[i]}`);
+                        }
+                    }
+                    else {
+                        // No ]]> sequences, safe to use .dat() directly
+                        metadataElement.ele(prop).dat(stringValue);
+                    }
+                }
+            }
+            else {
+                metadataElement.ele(prop);
+            }
+        }
+    }
+    // Embed the M2M record linking this metadata record to its source artifact.
+    // Asset M2Ms (application_file = sys_ux_lib_asset sys_id) are embedded in
+    // each sys_ux_lib_asset XML by static-content-plugin.
+    context.descendants.query('sn_glider_source_artifact_m2m').forEach((m2m) => {
+        const m2mElement = recordUpdate.ele('sn_glider_source_artifact_m2m', {
+            action: m2m.getAction(),
+        });
+        m2mElement.ele('sys_id').txt(m2m.getId().getValue());
+        const applicationFile = m2m.get('application_file');
+        if (applicationFile.isDefined()) {
+            const appFileId = applicationFile.isRecord()
+                ? applicationFile.asRecord().getId().getValue()
+                : applicationFile.toString().getValue();
+            m2mElement.ele('application_file').txt(appFileId);
+        }
+        const artifactId = m2m.get('source_artifact');
+        if (artifactId.isDefined()) {
+            const artifactSysId = artifactId.isRecord()
+                ? artifactId.asRecord().getId().getValue()
+                : artifactId.toString().getValue();
+            m2mElement.ele('source_artifact').txt(artifactSysId);
+        }
+    });
+    // Embed artifact records
+    context.descendants.query('sn_glider_source_artifact').forEach((artifact) => {
+        const artifactElement = recordUpdate.ele('sn_glider_source_artifact', {
+            action: artifact.getAction(),
+        });
+        artifactElement.ele('sys_id').txt(artifact.getId().getValue());
+        const artifactName = artifact.get('name');
+        if (artifactName.isDefined()) {
+            artifactElement.ele('name').txt(artifactName.toString().getValue());
+        }
+    });
+    // Embed attachment records
+    context.descendants.query('sys_attachment').forEach((attachment) => {
+        const attachmentElement = recordUpdate.ele('sys_attachment', { action: attachment.getAction() });
+        attachmentElement.ele('sys_id').txt(attachment.getId().getValue());
+        attachmentElement.ele('sys_scope', { display_value: context.config.scope }).txt(context.config.scopeId);
+        const tableId = attachment.get('table_sys_id');
+        if (tableId.isDefined()) {
+            attachmentElement.ele('table_sys_id').txt(tableId.toString().getValue());
+        }
+        const tableName = attachment.get('table_name');
+        if (tableName.isDefined()) {
+            attachmentElement.ele('table_name').txt(tableName.toString().getValue());
+        }
+        const attachmentProps = [
+            'file_name',
+            'content_type',
+            'size_bytes',
+            'size_compressed',
+            'compressed',
+            'chunk_size_bytes',
+            'hash',
+            'average_image_color',
+            'image_width',
+            'image_height',
+        ];
+        for (const prop of attachmentProps) {
+            const value = attachment.get(prop);
+            if (value.isDefined()) {
+                attachmentElement.ele(prop).txt(value.toString().getValue());
+            }
+        }
+    });
+    // Embed attachment doc records (chunks)
+    context.descendants.query('sys_attachment_doc').forEach((doc) => {
+        const docElement = recordUpdate.ele('sys_attachment_doc', { action: doc.getAction() });
+        docElement.ele('sys_id').txt(doc.getId().getValue());
+        // Link to the attachment
+        const attachmentId = doc.get('sys_attachment');
+        if (attachmentId.isDefined()) {
+            const sysId = attachmentId.isRecord()
+                ? attachmentId.asRecord().getId().getValue()
+                : attachmentId.toString().getValue();
+            docElement.ele('sys_attachment').txt(sysId);
+        }
+        const position = doc.get('position');
+        if (position.isDefined()) {
+            docElement.ele('position').txt(position.toString().getValue());
+        }
+        const data = doc.get('data');
+        if (data.isDefined()) {
+            docElement.ele('data').txt(data.toString().getValue());
+        }
+    });
+    // Emit delete_multiple elements to clean up stale attachments and docs per artifact.
+    // Since attachments use hash-based IDs, each build produces a new attachment ID.
+    // These queries tell the platform to remove any attachment/doc on this artifact
+    // that is not part of the current build.
+    context.descendants.query('sn_glider_source_artifact').forEach((artifact) => {
+        const artifactId = artifact.getId().getValue();
+        const currentAttachments = context.descendants
+            .query('sys_attachment')
+            .filter((att) => att.get('table_sys_id').toString().getValue() === artifactId);
+        const currentAttachmentIds = currentAttachments.map((att) => att.getId().getValue());
+        const currentDocIds = context.descendants
+            .query('sys_attachment_doc')
+            .filter((doc) => currentAttachmentIds.includes(doc.get('sys_attachment').toString().getValue()))
+            .map((doc) => doc.getId().getValue());
+        const attachmentQuery = currentAttachmentIds.length > 0
+            ? `table_sys_id=${artifactId}^sys_idNOT IN${currentAttachmentIds.join(',')}`
+            : `table_sys_id=${artifactId}`;
+        recordUpdate.ele('sys_attachment', { action: 'delete_multiple', query: attachmentQuery });
+        const docQuery = currentDocIds.length > 0
+            ? `sys_attachment.table_sys_id=${artifactId}^sys_idNOT IN${currentDocIds.join(',')}`
+            : `sys_attachment.table_sys_id=${artifactId}`;
+        recordUpdate.ele('sys_attachment_doc', { action: 'delete_multiple', query: docQuery });
+    });
+    return {
+        source: metadataRecord,
+        name: `${updateName}.xml`,
+        category: metadataRecord.getInstallCategory(),
+        content: recordUpdate.end({ prettyPrint: true }),
+    };
+}
 //# sourceMappingURL=ui-page-plugin.js.map