@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/ui-page-plugin.ts

@@ -1,7 +1,27 @@
-import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
-import { isSNScope } from '@servicenow/sdk-build-core'
+import {
+    CallExpressionShape,
+    Plugin,
+    Shape,
+    Database,
+    path,
+    SourceFileShape,
+    isSNScope,
+    zipSync,
+    unzipSync,
+    type Logger,
+    type Diagnostics,
+    type Project,
+    FileSystem,
+    type Record,
+    type NowConfig,
+    type Factory,
+    type Transform,
+} from '@servicenow/sdk-build-core'
 import { XMLParser, XMLBuilder, type X2jOptions, type XmlBuilderOptions } from 'fast-xml-parser'
+import { create } from 'xmlbuilder2'
 import { NowIdShape } from './now-id-plugin'
+import { CHUNK_SIZE, chunkData, generateId } from './static-content-plugin'
+import { sha256 } from './now-attach-plugin'
 
 const parserOptions: X2jOptions = {
     ignoreAttributes: false,
@@ -31,6 +51,51 @@ const builderOptions: XmlBuilderOptions = {
 }
 
 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 XMLParser(parserOptions)
 
@@ -74,7 +139,10 @@ window.g_ck = "$[gs.getSession().getSessionToken() || gs.getSessionToken()]";
 const nodeTransformer = (nodes: any[]) => {
     for (let i = 0; i < nodes.length; i++) {
         const node = nodes[i]
-        const tag = Object.keys(node)[0]!
+        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))
@@ -92,7 +160,24 @@ export const UiPagePlugin = 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 CallExpressionShape({
@@ -113,13 +198,125 @@ export const UiPagePlugin = 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: 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 Database() : new 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 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: 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: 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 }
                 }
@@ -133,6 +330,38 @@ export const UiPagePlugin = Plugin.create({
                 }
                 const name = endpoint.asString().getValue().replace(`${scope}_`, '').replace(/\.do$/, '')
                 let html = arg.get('html').toString().getValue()
+                let sourceFilePaths: string[] = []
+                let assetNames: string[] = []
+
+                // 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() as any[]).find((imp) =>
+                        imp.getModuleSpecifierValue().endsWith('.html')
+                    )
+                    if (htmlImport) {
+                        const relativeHtmlPath = htmlImport.getModuleSpecifierValue()
+                        const sourceFileDir = path.dirname(sourceFile.getFilePath())
+                        const absoluteHtmlPath = 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)
@@ -148,25 +377,839 @@ export const UiPagePlugin = Plugin.create({
                     }
                 }
 
+                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 = path.join(project.getRootDir(), 'now.prebuild.mjs')
+                    if (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: string,
+    fs: FileSystem,
+    logger: Logger,
+    config: NowConfig,
+    rootDir: string
+): { files: string[]; assetNames: string[] } => {
+    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 = path.basename(htmlFilePath, '.html')
+        const staticContentAbsDir = path.join(rootDir, config.staticContentDir)
+        const manifestPath = 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 = path.basename(manifest.entry, path.extname(manifest.entry))
+        const entryAssetName = 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 = path.join(staticContentAbsDir, `${entryBasename}.jsdbx.map`)
+        try {
+            fs.accessSync(sourceMapFilePath)
+            const sourceMapAssetName = 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: Record,
+    descendants: Database,
+    context: { config: NowConfig; fs: FileSystem; project: Project; diagnostics: Diagnostics; logger: Logger }
+): Promise<Shape | undefined> {
+    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] ? path.join(generatedDir, taxonomy.mapping[tableName]) : generatedDir
+
+    const originalFilePath = uiPageRecord.getOriginalFilePath()
+    let dirWhereTheFluentFileWillExistEventually = 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 = 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 SourceFileShape({
+            source: uiPageRecord,
+            path: `${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: string,
+    files: string[],
+    record: Record,
+    context: {
+        fs: FileSystem
+        project: Project
+        factory: Factory
+        config: NowConfig
+        logger: Logger
+        diagnostics: Diagnostics
+    },
+    assetNames?: string[]
+): Promise<Record[]> {
+    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: string,
+    metadataRecord: Record,
+    context: { factory: Factory; config: NowConfig }
+): Promise<Record> => {
+    return context.factory.createRecord({
+        source: metadataRecord.getSource(),
+        table: 'sn_glider_source_artifact',
+        explicitId: artifactName,
+        properties: {
+            name: artifactName,
+        },
+    })
+}
+
+const createArtifactM2mRecord = async (
+    artifactRecord: Record,
+    metadataRecord: Record,
+    context: { factory: Factory; config: NowConfig }
+): Promise<Record> => {
+    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: Record,
+    entryAssetName: string,
+    metadataRecord: Record,
+    context: { factory: Factory; config: NowConfig }
+): Promise<Record> => {
+    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: Factory,
+    artifactRecord: Record,
+    files: Map<string, Buffer>,
+    totalSize: number
+): Promise<Record[]> => {
+    // 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: { [path: string]: [Buffer, { mtime: Date }] } = {}
+    for (const [filePath, content] of files) {
+        zipEntries[filePath] = [content, { mtime: FIXED_MTIME }]
+    }
+    const zipped = zipSync(zipEntries)
+    const compressedData = Buffer.from(zipped)
+    const hash = await sha256(compressedData)
+
+    // Uniform chunking — no special header split
+    const allChunks = 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 = 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: 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: Record[] = []
+    for (let i = 0; i < allChunks.length; i++) {
+        const doc = await factory.createRecord({
+            source: artifactRecord.getSource(),
+            table: 'sys_attachment_doc',
+            properties: {
+                sys_id: 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: FileSystem,
+    rootDir: string,
+    files: string[]
+): Promise<{ files: Map<string, Buffer>; totalSize: number; skippedFiles: string[] }> => {
+    const fileMap = new Map<string, Buffer>()
+    let totalSize = 0
+    const skippedFiles: string[] = []
+
+    for (const filePath of files) {
+        let content: Buffer
+        try {
+            const absolutePath = path.join(rootDir, filePath.replace(/^[/\\]/, ''))
+            content = fs.readFileSync(absolutePath) as Buffer
+        } 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: Record,
+    allDescendants: { query: (table: string) => Record[] },
+    targetDir: string = '',
+    context: {
+        fs: FileSystem
+        project: Project
+        logger: Logger
+        diagnostics: Diagnostics
+    }
+): Promise<string[]> {
+    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 = unzipSync(compressedData)
+
+    const unpackedFiles: string[] = []
+
+    for (const [filePath, data] of Object.entries(entries)) {
+        try {
+            const fileContent = Buffer.from(data)
+            const absolutePath = path.join(context.project.getRootDir(), targetDir, filePath)
+            const dir = 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: (table: string) => Record[] },
+    query: { id?: string; name?: RegExp }
+): Record | undefined {
+    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: Record,
+    metadataProps: string[],
+    context: {
+        descendants: { query: (table: string) => Record[] }
+        config: { scope: string; scopeId: string }
+        transform: Transform
+    }
+) {
+    const recordUpdate = 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 }),
+    }
+}