@invarn/cibuild 2.4.0 → 2.4.1

package/dist/src/yaml/steps/ui-fidelity-render.js

@@ -71,7 +71,7 @@ export const DEFAULT_RENDER_SIZE = '393x852';
 /** Default display scale (@2x), matching how references are typically exported. */
 export const DEFAULT_SCALE = 2;
 /** Valid values for the package_source input. */
-export const PACKAGE_SOURCES = ['repo', 'inputs'];
+export const PACKAGE_SOURCES = ['repo', 'inputs', 'url'];
 /** Default package source: the package lives in the repo checkout. */
 export const DEFAULT_PACKAGE_SOURCE = 'repo';
 /** Valid values for the reference_source input. */
@@ -1264,6 +1264,154 @@ function buildPackageSourceMain() {
     return main;
 }
 const RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE = buildPackageSourceMain();
+/**
+ * Builds the runtime main for package_source "url" (fidelity-linux 03) by
+ * patching the package_source variant. Three departures, all forced by the
+ * same fact — a clone-free worker has no checkout:
+ *
+ * 1. The package is DOWNLOADED (curl, a runner requirement in this mode) to
+ *    `.ci/inputs/package.tar.gz` and extracted BEFORE the per-screen
+ *    reference stage, because committed references travel inside it. A failed
+ *    download is one structured per-build error, never per-screen noise.
+ * 2. Each screen's reference is the committed repo-relative path resolved
+ *    INSIDE the extracted package: it must sit under packagePath, and the
+ *    remainder resolves against the extracted package root.
+ * 3. The harness stage reuses the already-extracted root (no second extract);
+ *    cleanup mirrors the inputs path. Mirrors the Android step's url mode so
+ *    both platform kinds accept the same dispatched inputs.
+ */
+function buildPackageUrlMain() {
+    let main = RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE;
+    // Download + extract FIRST — the reference stage below reads from inside
+    // the extracted package.
+    main = replaceOnce(main, '  // 2. Per-screen validation + reference copies. Each screen gets its OWN\n' +
+        '  //    copy named by screen, even when two screens share a reference\n' +
+        '  //    basename.\n' +
+        '  currentEntries.forEach(function (entry) {', '  // 2a. Download + extract the shipped package FIRST (URL mode): committed\n' +
+        '  //     references live inside it, so the per-screen reference copies below\n' +
+        '  //     need the extracted package root. A failed download or an invalid\n' +
+        '  //     archive is ONE structured per-build error; per-screen reference\n' +
+        '  //     work then stops cleanly (no bogus REFERENCE_MISSING noise).\n' +
+        '  var urlPackageRoot = null;\n' +
+        '  (function () {\n' +
+        '    try {\n' +
+        '      fs.mkdirSync(inputsDir, { recursive: true });\n' +
+        '    } catch (mkdirError) {\n' +
+        '      // the download below reports the real failure\n' +
+        '    }\n' +
+        '    var dest = path.join(inputsDir, PACKAGE_ARCHIVE_NAME);\n' +
+        "    log('downloading render package');\n" +
+        '    var download = cp.spawnSync(\n' +
+        "      'curl',\n" +
+        "      ['-fsSL', '--retry', '2', '--max-time', '300', '-o', dest, CONFIG.packageUrl],\n" +
+        "      { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 }\n" +
+        '    );\n' +
+        '    if (download.error) {\n' +
+        '      download.status = download.status == null ? 127 : download.status;\n' +
+        "      download.stderr = (download.stderr || '') + String(download.error.message || download.error);\n" +
+        '    }\n' +
+        '    if (download.status !== 0) {\n' +
+        '      setBuildError(\n' +
+        "        'PACKAGE_DOWNLOAD_FAILED',\n" +
+        "        'render package download failed (curl exit ' + download.status + '):\\n' + outputTail(download)\n" +
+        '      );\n' +
+        '      return;\n' +
+        '    }\n' +
+        '    urlPackageRoot = prepareShippedPackage();\n' +
+        '  })();\n' +
+        '\n' +
+        '  // 2. Per-screen validation + reference copies. Each screen gets its OWN\n' +
+        '  //    copy named by screen, even when two screens share a reference\n' +
+        '  //    basename.\n' +
+        '  currentEntries.forEach(function (entry) {');
+    // References resolve INSIDE the extracted package: repo-relative path minus
+    // the packagePath prefix, against the extracted package root.
+    main = replaceOnce(main, 'var basename = params.screens[entry.screen];\n' +
+        '    if (\n' +
+        "      typeof basename !== 'string' || basename === '' ||\n" +
+        "      basename === '.' || basename === '..' ||\n" +
+        '      basename !== path.basename(basename)\n' +
+        '    ) {\n' +
+        '      setError(\n' +
+        '        entry,\n' +
+        "        'REFERENCE_MISSING',\n" +
+        "        'reference for ' + entry.screen + ' must be a plain file basename inside ' +\n" +
+        "          inputsDir + ', got: ' + JSON.stringify(basename)\n" +
+        '      );\n' +
+        '      return;\n' +
+        '    }\n' +
+        '    var source = path.join(inputsDir, basename);', 'var refPath = params.screens[entry.screen];\n' +
+        "    if (typeof refPath !== 'string' || refPath === '') {\n" +
+        '      setError(\n' +
+        '        entry,\n' +
+        "        'REFERENCE_MISSING',\n" +
+        "        'reference for ' + entry.screen + ' must be a non-empty repo-relative path, got: ' +\n" +
+        '          JSON.stringify(refPath)\n' +
+        '      );\n' +
+        '      return;\n' +
+        '    }\n' +
+        '    if (urlPackageRoot === null) {\n' +
+        '      // Package unavailable: the per-build error above carries the cause.\n' +
+        '      return;\n' +
+        '    }\n' +
+        "    var packagePrefix = CONFIG.packagePath.replace(/^\\.\\//, '').replace(/\\/+$/, '');\n" +
+        "    var normalizedRef = refPath.replace(/^\\.\\//, '');\n" +
+        "    if (normalizedRef.indexOf(packagePrefix + '/') !== 0) {\n" +
+        '      setError(\n' +
+        '        entry,\n' +
+        "        'REFERENCE_MISSING',\n" +
+        "        'reference for ' + entry.screen + ' must live inside the shipped package (' +\n" +
+        "          packagePrefix + '), got: ' + JSON.stringify(refPath)\n" +
+        '      );\n' +
+        '      return;\n' +
+        '    }\n' +
+        '    var source = path.join(urlPackageRoot, normalizedRef.slice(packagePrefix.length + 1));');
+    // Harness stage: build from the package extracted in stage 2a — no second
+    // extract. This variant only ever runs with packageSource "url".
+    main = replaceOnce(main, '  // 3. Resolve the package to build from, then render the remaining\n' +
+        '  //    screens through the synthesized harness.\n' +
+        '  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });\n' +
+        "  if (CONFIG.packageSource === 'inputs') {\n" +
+        '    try {\n' +
+        '      var shippedRoot = prepareShippedPackage();\n' +
+        '      if (shippedRoot !== null) {\n' +
+        '        if (renderable.length > 0) {\n' +
+        '          renderWithHarness(renderable, shippedRoot);\n' +
+        '        } else if (currentEntries.length > 0) {\n' +
+        "          log('no renderable screens, skipping harness build');\n" +
+        '        }\n' +
+        '      }\n' +
+        '    } finally {\n' +
+        '      cleanupShippedPackage();\n' +
+        '    }\n' +
+        '  } else if (renderable.length > 0) {\n' +
+        '    if (!fs.existsSync(resolvedPackagePath)) {\n' +
+        '      currentEntries.forEach(function (entry) {\n' +
+        "        setError(entry, 'RENDER_UNSUPPORTED', 'package_path does not exist: ' + resolvedPackagePath);\n" +
+        '      });\n' +
+        '    } else {\n' +
+        '      renderWithHarness(renderable, resolvedPackagePath);\n' +
+        '    }\n' +
+        '  } else if (currentEntries.length > 0) {\n' +
+        "    log('no renderable screens, skipping harness build');\n" +
+        '  }', '  // 3. Render from the package downloaded + extracted in stage 2a. The\n' +
+        '  //    extraction already reported packaging mistakes as the per-build\n' +
+        '  //    error, so a null root here just skips the harness build.\n' +
+        '  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });\n' +
+        '  try {\n' +
+        '    if (urlPackageRoot !== null) {\n' +
+        '      if (renderable.length > 0) {\n' +
+        '        renderWithHarness(renderable, urlPackageRoot);\n' +
+        '      } else if (currentEntries.length > 0) {\n' +
+        "        log('no renderable screens, skipping harness build');\n" +
+        '      }\n' +
+        '    }\n' +
+        '  } finally {\n' +
+        '    cleanupShippedPackage();\n' +
+        '  }');
+    return main;
+}
+const RENDER_SCRIPT_MAIN_URL = buildPackageUrlMain();
 /**
  * Patches the reference-sourcing block to read each screen's reference from a
  * repo-relative path (resolved against the checkout) instead of a plain
@@ -1322,7 +1470,9 @@ export function getRenderScriptInternals() {
 export function generateRenderScript(config) {
     let main = config.packageSource === undefined
         ? RENDER_SCRIPT_MAIN
-        : RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE;
+        : config.packageSource === 'url'
+            ? RENDER_SCRIPT_MAIN_URL
+            : RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE;
     // Reference-from-repo is an independent dimension layered on top of whichever
     // package base applies. Absent → byte-identical reference block (v1).
     if (config.referenceSource === 'repo') {
@@ -1344,13 +1494,18 @@ export function generateRenderScript(config) {
  */
 export class UiFidelityRenderStepExecutor extends BaseStepExecutor {
     getValidationRequirements(inputs, _env, _config) {
-        if (inputs && inputs.package_source === 'inputs') {
-            // The package ships as .ci/inputs/package.tar.gz at run time, so
+        if (inputs && (inputs.package_source === 'inputs' || inputs.package_source === 'url')) {
+            // The package ships as .ci/inputs/package.tar.gz at run time (uploaded
+            // run input, or downloaded from the signed package_url in url mode), so
             // neither package_path nor target is required up front.
-            return [
+            const requirements = [
                 this.requireCommand('swift', 'Swift toolchain used to build and run the render harness', 'Install Xcode (or the Swift toolchain) on the runner'),
                 this.requireCommand('tar', 'Archive tool used to extract the shipped package', 'Install tar on the runner'),
             ];
+            if (inputs.package_source === 'url') {
+                requirements.push(this.requireCommand('curl', 'Downloader used to fetch the render package by signed URL', 'Install curl on the runner'));
+            }
+            return requirements;
         }
         return [
             this.requireInput('package_path', inputs, 'Path to the SwiftPM package containing the screens'),
@@ -1375,10 +1530,21 @@ export class UiFidelityRenderStepExecutor extends BaseStepExecutor {
         }
         let packagePath = null;
         let target = null;
-        if (packageSource === 'inputs') {
-            // package_path is ignored: the package arrives as a run input.
-            // target is optional and discovered from the shipped manifest when
-            // the package declares exactly one library product.
+        let packageUrl;
+        if (packageSource === 'inputs' || packageSource === 'url') {
+            // package_path names no local directory here: inputs mode ignores it
+            // (the package arrives as a run input); url mode requires it as the
+            // repo-relative prefix committed reference paths sit under, inside the
+            // downloaded package. target is optional and discovered from the
+            // shipped manifest when the package declares exactly one library
+            // product.
+            if (packageSource === 'url') {
+                packageUrl = String(this.getRequiredInput(inputs, 'package_url', stepName));
+                if (!/^https?:\/\//.test(packageUrl)) {
+                    throw new Error(`Invalid package_url for step '${stepName}': expected an http(s) URL`);
+                }
+                packagePath = String(this.getRequiredInput(inputs, 'package_path', stepName));
+            }
             const configuredTarget = this.getInput(inputs, 'target', undefined);
             target = configuredTarget === undefined ? null : String(configuredTarget);
         }
@@ -1401,6 +1567,13 @@ export class UiFidelityRenderStepExecutor extends BaseStepExecutor {
                 throw new Error(`Invalid reference_source '${value}' for step '${stepName}': ` +
                     `expected one of: ${REFERENCE_SOURCES.join(', ')}`);
             }
+            // URL mode owns reference sourcing (inside the extracted package) —
+            // an explicit reference_source alongside it is a contradiction.
+            if (packageSource === 'url') {
+                throw new Error(`Invalid reference_source for step '${stepName}': ` +
+                    "package_source 'url' resolves references inside the downloaded " +
+                    'package; omit reference_source');
+            }
             if (value === 'repo') {
                 referenceSource = 'repo';
             }
@@ -1411,6 +1584,9 @@ export class UiFidelityRenderStepExecutor extends BaseStepExecutor {
         if (packageSource !== undefined) {
             config.packageSource = packageSource;
         }
+        if (packageUrl !== undefined) {
+            config.packageUrl = packageUrl;
+        }
         if (referenceSource !== undefined) {
             config.referenceSource = referenceSource;
         }

package/dist/src/yaml/steps/ui-fidelity-render.test.js

@@ -15,7 +15,7 @@
  * Swift toolchain (macOS with Xcode required, slow).
  */
 import { describe, test, expect, afterAll } from '@jest/globals';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { gzipSync } from 'node:zlib';
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -242,7 +242,9 @@ function makeTarGz(entries) {
     const blocks = [];
     for (const entry of entries) {
         const isDir = entry.name.endsWith('/');
-        const content = Buffer.from(entry.content ?? '', 'utf-8');
+        const content = Buffer.isBuffer(entry.content)
+            ? entry.content
+            : Buffer.from(entry.content ?? '', 'utf-8');
         blocks.push(tarHeader(entry.name, isDir ? 0 : content.length, isDir ? '5' : '0'));
         if (!isDir && content.length > 0) {
             const padded = Buffer.alloc(Math.ceil(content.length / 512) * 512);
@@ -450,6 +452,157 @@ describe('package_source input', () => {
         expect(inputsNames).toEqual(['swift', 'tar']);
     });
 });
+// Clone-free package delivery (fidelity-linux 03): the dispatched YAML carries
+// a signed package_url; the runtime downloads it to .ci/inputs/package.tar.gz
+// and proceeds like inputs mode, resolving each screen's committed reference
+// INSIDE the extracted package (repo-relative path minus the package_path
+// prefix) — there is no checkout on a clone-free worker. Mirrors the Android
+// step's url mode so both platform kinds accept the same dispatched inputs.
+describe('package_source: url', () => {
+    /**
+     * Serve one tar.gz (or a 404) from a loopback HTTP server IN A CHILD
+     * PROCESS. runScript executes the generated script via spawnSync, which
+     * blocks this process's event loop — an in-process server would deadlock
+     * against the script's curl.
+     */
+    const SERVE_PACKAGE_SRC = [
+        "var http = require('http');",
+        "var fs = require('fs');",
+        'var filePath = process.argv[1];',
+        'var server = http.createServer(function (req, res) {',
+        "  if (filePath === '-') { res.statusCode = 404; res.end('gone'); return; }",
+        "  res.setHeader('content-type', 'application/gzip');",
+        '  res.end(fs.readFileSync(filePath));',
+        '});',
+        "server.listen(0, '127.0.0.1', function () {",
+        "  console.log('PORT ' + server.address().port);",
+        '});',
+    ].join('\n');
+    async function servePackage(archive) {
+        let filePath = '-';
+        if (archive !== null) {
+            const dir = mkdtempSync(join(tmpdir(), 'ui-fidelity-url-serve-'));
+            tempDirs.push(dir);
+            filePath = join(dir, 'package.tar.gz');
+            writeFileSync(filePath, archive);
+        }
+        const child = spawn('node', ['-e', SERVE_PACKAGE_SRC, filePath], {
+            stdio: ['ignore', 'pipe', 'inherit'],
+        });
+        const port = await new Promise((resolvePort, rejectPort) => {
+            let buffered = '';
+            const timer = setTimeout(() => rejectPort(new Error('package server did not start')), 10_000);
+            child.stdout.on('data', (chunk) => {
+                buffered += chunk.toString();
+                const match = /PORT (\d+)/.exec(buffered);
+                if (match) {
+                    clearTimeout(timer);
+                    resolvePort(Number(match[1]));
+                }
+            });
+            child.on('exit', () => rejectPort(new Error('package server exited early')));
+        });
+        return {
+            url: `http://127.0.0.1:${port}/api/fidelity/packages/blob1?exp=1&sig=ab`,
+            close: () => new Promise((resolveClose) => {
+                child.once('exit', () => resolveClose(undefined));
+                child.kill('SIGKILL');
+            }),
+        };
+    }
+    /** Archive shaped like the dashboard's assembly: package-dir contents at the
+     *  archive root, committed references under references/. */
+    function packagedProjectWithReference() {
+        return makeTarGz([
+            ...shippedPackageEntries(''),
+            {
+                name: 'references/home.png',
+                content: Buffer.concat([PNG_MAGIC, Buffer.from('ref:url-home')]),
+            },
+        ]);
+    }
+    test('package_source url requires package_url and package_path', async () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        await expect(executor.execute({ package_source: 'url', package_path: 'ios-pkg' }, {}, testConfig)).rejects.toThrow(/package_url/);
+        await expect(executor.execute({ package_source: 'url', package_url: 'https://x.test/p' }, {}, testConfig)).rejects.toThrow(/package_path/);
+    });
+    test('rejects reference_source alongside package_source url', async () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        await expect(executor.execute({
+            package_source: 'url',
+            package_url: 'https://x.test/p',
+            package_path: 'ios-pkg',
+            reference_source: 'repo',
+        }, {}, testConfig)).rejects.toThrow(/reference_source/);
+    });
+    test('url mode requires swift, tar, and curl', () => {
+        const executor = new UiFidelityRenderStepExecutor();
+        const names = executor
+            .getValidationRequirements({ package_source: 'url' }, {}, testConfig)
+            .map((requirement) => requirement.name);
+        expect(names).toEqual(['swift', 'tar', 'curl']);
+    });
+    test('downloads the package, renders, and resolves references inside it', async () => {
+        const project = makeProject({ screens: { HomeView: 'ios-pkg/references/home.png' } });
+        const served = await servePackage(packagedProjectWithReference());
+        try {
+            const executor = new UiFidelityRenderStepExecutor();
+            const step = await executor.execute({ package_source: 'url', package_url: served.url, package_path: 'ios-pkg' }, {}, testConfig);
+            const run = runScript(project, step.script);
+            expect(run.status).toBe(0);
+            const doc = readResult(project);
+            expect(doc.package_source).toBe('url');
+            const screen = doc.screens.find((s) => s.screen === 'HomeView');
+            expect(screen?.status).toBe('rendered');
+            expect(screen?.reference_image_path).toBe('ui-fidelity/references/HomeView.png');
+            expect(isPng(artifact(project, 'ui-fidelity/references/HomeView.png'))).toBe(true);
+        }
+        finally {
+            await served.close();
+        }
+    });
+    test('a failed download is one structured build error, not per-screen noise', async () => {
+        const project = makeProject({ screens: { HomeView: 'ios-pkg/references/home.png' } });
+        const served = await servePackage(null); // 404
+        try {
+            const executor = new UiFidelityRenderStepExecutor();
+            const step = await executor.execute({ package_source: 'url', package_url: served.url, package_path: 'ios-pkg' }, {}, testConfig);
+            const run = runScript(project, step.script);
+            expect(run.status).not.toBe(0);
+            const doc = readResult(project);
+            expect(doc.error?.code).toBe('PACKAGE_DOWNLOAD_FAILED');
+            const screen = doc.screens.find((s) => s.screen === 'HomeView');
+            expect(screen?.error).toBeNull();
+            expectNoAbsolutePathLeaks(project, doc);
+        }
+        finally {
+            await served.close();
+        }
+    });
+    test('a reference outside the package directory fails that screen only', async () => {
+        const project = makeProject({
+            screens: {
+                HomeView: 'ios-pkg/references/home.png',
+                Stray: 'design/elsewhere/stray.png',
+            },
+        });
+        const served = await servePackage(packagedProjectWithReference());
+        try {
+            const executor = new UiFidelityRenderStepExecutor();
+            const step = await executor.execute({ package_source: 'url', package_url: served.url, package_path: 'ios-pkg' }, {}, testConfig);
+            const run = runScript(project, step.script, { FAKE_SWIFT_RUN_SILENT: 'Stray' });
+            expect(run.status).not.toBe(0);
+            const doc = readResult(project);
+            expect(doc.screens.find((s) => s.screen === 'HomeView')?.status).toBe('rendered');
+            const stray = doc.screens.find((s) => s.screen === 'Stray');
+            expect(stray?.status).toBe('render_failed');
+            expect(stray?.error?.code).toBe('REFERENCE_MISSING');
+        }
+        finally {
+            await served.close();
+        }
+    });
+});
 describe('render size and scale parsing', () => {
     test('default render size is 393x852 device points', () => {
         expect(DEFAULT_RENDER_SIZE).toBe('393x852');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invarn/cibuild",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "CI Build CLI — local pipeline orchestration and validation",
   "type": "module",
   "main": "dist/cli.cjs",