@essential-apps/shopify-test-runner 1.0.0

package/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Public API of @essential-apps/shopify-test-runner.
+ *
+ * The CLI binaries (shopify-test-run-docker, etc.) are exposed via
+ * the `bin` field in package.json — they don't import from this
+ * file. This module re-exports a few utilities that consuming apps
+ * occasionally use programmatically (port checking, stealth browser
+ * launch).
+ *
+ * Most apps will only import from this package's `/playwright`
+ * subpath:
+ *   import { definePlaywrightConfig } from
+ *     '@essential-apps/shopify-test-runner/playwright';
+ */
+
+export { isPortFree, findFreePort } from './lib/freePort.js';
+
+export { launchStealthBrowser, stealthLaunchArgs } from './lib/stealthLaunch.js';
+
+/**
+ * Shopify Functions JS-source → deployable .wasm pipeline. Builds
+ * without the Shopify CLI; downloads stock Javy + the Shopify-CDN
+ * plugin .wasm on first use. See `./lib/functionBuild.ts` for the
+ * full rationale.
+ */
+export {
+  buildFunctionWasm,
+  ensureJavy,
+  ensureJavyPlugin,
+  parseFunctionToml,
+  JAVY_VERSION,
+  PLUGIN_URL,
+} from './lib/functionBuild.js';
+export type {
+  BuildFunctionWasmOptions,
+  BuildFunctionWasmResult,
+  FunctionTarget,
+  ParsedFunctionToml,
+} from './lib/functionBuild.js';
+
+/**
+ * App Management API source-zip upload helpers — used together
+ * when deploying app versions that contain a function or
+ * post-purchase extension (their binary artifacts don't fit
+ * inline in the `source` manifest).
+ */
+export {
+  requestSourceUploadUrl,
+  uploadSourceToSignedUrl,
+} from './lib/sourceZipUpload.js';
+export type {
+  RequestSourceUploadUrlOptions,
+  UploadSourceOptions,
+} from './lib/sourceZipUpload.js';
+
+/**
+ * Source-bundle (zip) assembly. Produces the artifact uploaded to
+ * GCS and referenced via `AppVersionInput.sourceUrl`.
+ */
+export {
+  buildSourceBundle,
+  readExtensionFilesAsBuffers,
+} from './lib/buildSourceBundle.js';
+export type {
+  BuildSourceBundleOptions,
+  ManifestModule,
+} from './lib/buildSourceBundle.js';

package/src/lib/buildSourceBundle.ts

@@ -0,0 +1,197 @@
+/**
+ * Assemble the source archive uploaded for `appVersionCreate` via
+ * the `sourceUrl` path.
+ *
+ * What format does Shopify actually accept?
+ * -----------------------------------------
+ * Empirically (May 2026, App Management /unstable/ endpoint): the
+ * server accepts **tar + brotli** (`.tar.br`), AND requires
+ * `sourceExtension: BR` when minting the signed-upload URL via
+ * `appRequestSourceUploadUrl`. The legacy `sourceExtension: ZIP`
+ * branch exists in the schema and returns a working signed URL, but
+ * something downstream chokes on zips that contain a per-extension
+ * folder layout — the server 500s on any zip whose top level has a
+ * `<uid>/...` directory entry. Tar+brotli works.
+ *
+ * This was reverse-engineered from `Shopify/cli`'s bundle pipeline:
+ *   packages/app/src/cli/services/bundle.ts
+ *   packages/cli-kit/src/public/node/archiver.ts
+ * The CLI ALWAYS uses tar+brotli; the ZIP code path appears to be
+ * unused / vestigial.
+ *
+ * Layout inside the archive
+ * -------------------------
+ *   manifest.json                          ← top-level module list
+ *   <module_uid>/dist/index.wasm           ← function WASM, BASE64-
+ *                                            ENCODED AS TEXT (not raw
+ *                                            binary — see below)
+ *   <theme_uid>/assets/<file>              ← theme files, raw bytes
+ *   <theme_uid>/blocks/<file>
+ *   <theme_uid>/locales/<file>
+ *   <theme_uid>/snippets/<file>
+ *
+ * The base64-encoding-of-wasm is THE critical detail that gets you
+ * past `"Wasm file is not present"`. The Shopify CLI does this in
+ * `bundleFunctionExtension(wasmPath, bundlePath)` which calls
+ * `readFile(path, {encoding: 'base64'})` and `writeFile(bundlePath, b64)`.
+ * The server reads the file at `<uid>/dist/index.wasm` and expects
+ * base64 text content, decoding it back to WASM bytes on its side.
+ *
+ * Manifest format
+ * ---------------
+ * Mirrors the CLI's `app.manifest()` builder
+ * (`packages/app/src/cli/models/app/app.ts`). Each module entry has:
+ *   {
+ *     type: <externalIdentifier — e.g. 'function' for plain function>,
+ *     handle: <toml handle>,
+ *     uid: <stable uuid>,
+ *     assets: <uid>,        ← same string as uid; folder name in archive
+ *     target: <contextValue>, ← single-target handle, or '' for multi
+ *     config: { … per-spec deployConfig output … },
+ *   }
+ */
+import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { brotliCompressSync, constants as zlibConst } from 'node:zlib';
+import { pack as tarPack } from 'tar-stream';
+
+/** A single entry in the manifest.json's `modules` array. Matches
+ *  the CLI's `ManifestModule` interface from app.ts. */
+export interface ManifestModule {
+  type: string;
+  handle: string;
+  uid: string;
+  /** Folder name inside the archive that holds this module's
+   *  artifacts. Conventionally equal to `uid`. */
+  assets?: string;
+  /** Single-target handle (e.g. "cart.lines.discounts.generate.run").
+   *  Empty string for multi-target functions, omitted for non-targeted
+   *  modules like app_home / branding / app_access. */
+  target?: string;
+  config: Record<string, unknown>;
+}
+
+export interface BuildSourceBundleOptions {
+  /** The app's top-level display name. Goes into `manifest.name`. */
+  name: string;
+  /** All modules for this deploy. */
+  modules: ManifestModule[];
+  /**
+   * Files to embed in the archive, keyed by their path-inside-the-
+   * archive. Function .wasm files MUST be base64-encoded as text by
+   * the caller (we'd do it here, but the caller already has the
+   * raw wasm and may or may not have other text/binary content —
+   * doing it here would obscure the contract).
+   */
+  files: Record<string, Buffer | string>;
+  /** Output path. Caller owns the path — typically /tmp/<…>.tar.br. */
+  outPath: string;
+  /**
+   * Brotli quality (0-11). Default 7 matches the CLI's choice. Higher
+   * = smaller + slower. Functions + theme bundles fit comfortably in
+   * a few hundred KB at quality 7.
+   */
+  brotliQuality?: number;
+}
+
+/**
+ * Build a tar+brotli source bundle and write it to `outPath`. Returns
+ * the path written.
+ *
+ * Implementation note: we tar in-memory (chunked into Node Buffers)
+ * then brotli-compress in one shot. Suitable for the < 10MB bundles
+ * we deal with; switch to streaming if that changes.
+ */
+export async function buildSourceBundle(
+  opts: BuildSourceBundleOptions,
+): Promise<string> {
+  const manifestJson = JSON.stringify(
+    { name: opts.name, handle: '', modules: opts.modules },
+    null,
+    2,
+  );
+  const entries: Array<{ name: string; content: Buffer }> = [
+    { name: 'manifest.json', content: Buffer.from(manifestJson, 'utf8') },
+  ];
+  for (const [name, content] of Object.entries(opts.files)) {
+    entries.push({
+      name,
+      content: Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8'),
+    });
+  }
+
+  // tar-stream pack: collect chunks, finalize, then brotli-compress.
+  const tarBuf = await new Promise<Buffer>((resolve_, reject) => {
+    const pack = tarPack();
+    const chunks: Buffer[] = [];
+    pack.on('data', (c: Buffer) => chunks.push(c));
+    pack.on('end', () => resolve_(Buffer.concat(chunks)));
+    pack.on('error', reject);
+    (async () => {
+      for (const e of entries) {
+        await new Promise<void>((res, rej) => {
+          pack.entry({ name: e.name }, e.content, (err) => (err ? rej(err) : res()));
+        });
+      }
+      pack.finalize();
+    })().catch(reject);
+  });
+
+  const brBuf = brotliCompressSync(tarBuf, {
+    params: {
+      [zlibConst.BROTLI_PARAM_QUALITY]: opts.brotliQuality ?? 7,
+    },
+  });
+  writeFileSync(opts.outPath, brBuf);
+  return opts.outPath;
+}
+
+/**
+ * Walk an extension directory and return its file contents keyed by
+ * the path-inside-the-archive-folder (i.e. NOT prefixed with the
+ * uid; the caller prepends that). Returns raw Buffers.
+ *
+ * Skips dirs/files that aren't shipped (same list as the inline
+ * theme bundler in deployAppVersion.ts).
+ */
+export function readExtensionFilesAsBuffers(
+  extensionDir: string,
+): Record<string, Buffer> {
+  const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'src',
+    'frontend',
+    'generated',
+  ]);
+  const SKIP_FILES = new Set([
+    'shopify.extension.toml',
+    'package.json',
+    'package-lock.json',
+    'tsconfig.json',
+    '.shopifyignore',
+    '.gitignore',
+    'README.md',
+  ]);
+  const out: Record<string, Buffer> = {};
+  function walk(dir: string, rel: string): void {
+    for (const name of readdirSync(dir)) {
+      const full = resolve(dir, name);
+      const relPath = rel ? `${rel}/${name}` : name;
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        if (SKIP_DIRS.has(name) || name.startsWith('.')) continue;
+        walk(full, relPath);
+        continue;
+      }
+      if (SKIP_FILES.has(name)) continue;
+      if (name.endsWith('.config.ts') || name.endsWith('.config.mts')) continue;
+      if (name.endsWith('.config.js') || name.endsWith('.config.cjs')) continue;
+      if (name.endsWith('.js.map')) continue; // CLI excludes these
+      if (name.endsWith('.metafile.json')) continue; // CLI excludes these
+      out[relPath] = readFileSync(full);
+    }
+  }
+  walk(extensionDir, '');
+  return out;
+}

package/src/lib/freePort.ts

@@ -0,0 +1,33 @@
+import { createServer } from 'node:net';
+
+/** Asks the OS for a random free TCP port. */
+export function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      if (addr && typeof addr === 'object') {
+        const port = addr.port;
+        srv.close(() => resolve(port));
+      } else {
+        srv.close();
+        reject(new Error('Could not determine free port'));
+      }
+    });
+  });
+}
+
+/** Returns true if the given port is free to bind. */
+export function isPortFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const srv = createServer();
+    srv.unref();
+    srv.once('error', () => resolve(false));
+    srv.once('listening', () => {
+      srv.close(() => resolve(true));
+    });
+    srv.listen(port, '127.0.0.1');
+  });
+}