@essential-apps/shopify-test-runner 1.0.0

package/dist/lib/functionBuild.js

@@ -0,0 +1,413 @@
+/**
+ * Compile a JS Shopify Function source tree into a deployable `.wasm`
+ * WITHOUT shelling out to the Shopify CLI.
+ *
+ * Why this exists
+ * ---------------
+ * `shopify app function build` is the canonical way to produce the
+ * `.wasm` artifact that Shopify Functions accepts. Tests in this repo
+ * are forbidden from depending on the Shopify CLI (binary mismatch
+ * across dev machines, interactive prompts, version drift) — so we
+ * replicate the pipeline directly.
+ *
+ * The pipeline is small and well-isolated. Traced from
+ * `Shopify/cli@packages/app/src/cli/services/function/build.ts`:
+ *
+ *   1. esbuild — bundle the user's JS source into a single ES module
+ *      whose default export is a thin wrapper around
+ *      `@shopify/shopify_function/run`. esbuild's Node API, no
+ *      subprocess.
+ *
+ *   2. javy build — wraps the bundled JS in a Wizened QuickJS runtime
+ *      AND links Shopify's host-binding plugin (`-C dynamic -C
+ *      plugin=shopify_functions_javy_v3.wasm`). Output: a stand-alone
+ *      .wasm module that the Shopify Functions runtime can invoke
+ *      directly.
+ *
+ * No "trampoline" step is required for current
+ * `@shopify/shopify_function` runtimes — the plugin v3 + Javy 7 combo
+ * already targets the modern host ABI. (Trampoline exists in the CLI
+ * but is conditional on legacy `shopify_function_v{1,2}` imports.)
+ *
+ * Pinned versions
+ * ---------------
+ * Javy:    bytecodealliance/javy v7.0.1 (stock upstream, NOT a Shopify
+ *          fork — the Shopify-specific glue lives entirely in the
+ *          plugin .wasm we pass to `-C plugin=`).
+ * Plugin:  https://cdn.shopify.com/shopifycloud/shopify-functions-javy-plugin/
+ *          shopify_functions_javy_v3.wasm
+ *          (version-pinned in URL path; Shopify CDN, effectively
+ *          immutable — when Shopify ships `_v4` we bump the const.)
+ *
+ * Binaries are cached at
+ *   ~/.cache/essential-apps-shopify-test/bin/
+ * keyed by version so multiple test workspaces share the same download.
+ */
+import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+import { createGunzip } from 'node:zlib';
+import { Readable } from 'node:stream';
+import * as esbuild from 'esbuild';
+const execFileP = promisify(execFile);
+/**
+ * Pinned Javy version. Bumping = updating the URL pattern in
+ * `binaryUrlForJavy` AND verifying the `-C` flag interface hasn't
+ * changed across the bump (Javy did break flags between v0.x and v3+).
+ */
+export const JAVY_VERSION = 'v7.0.1';
+/**
+ * Pinned Shopify Functions Javy plugin wasm. The URL contains the
+ * major version (`_v3`) — if Shopify publishes a `_v4`, we explicitly
+ * decide whether to upgrade (the plugin's host ABI is what user JS
+ * sees via `@shopify/shopify_function`).
+ */
+export const PLUGIN_URL = 'https://cdn.shopify.com/shopifycloud/shopify-functions-javy-plugin/shopify_functions_javy_v3.wasm';
+/** Filename under the cache dir for the plugin (derived from URL). */
+const PLUGIN_FILENAME = 'shopify_functions_javy_v3.wasm';
+/** `world` name we declare in the synthesized WIT — must match the
+ * `wit-world` flag passed to `javy build`. The literal string is
+ * uninteresting (Javy uses it only to disambiguate worlds in the WIT
+ * file); we follow the CLI's value to minimize surprise. */
+const JAVY_WORLD_NAME = 'shopify-function';
+function cacheDir() {
+    const dir = join(homedir(), '.cache', 'essential-apps-shopify-test', 'bin');
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/**
+ * Map Node's `process.{platform,arch}` to the asset-name suffix
+ * bytecodealliance/javy uses in its GitHub releases. Mismatches here
+ * surface as 404s from the GitHub redirect, so it's worth keeping the
+ * list explicit rather than guessing.
+ *
+ * Known asset names at v7.0.1:
+ *   javy-arm-macos-v7.0.1.gz
+ *   javy-x86_64-macos-v7.0.1.gz
+ *   javy-arm-linux-v7.0.1.gz
+ *   javy-x86_64-linux-v7.0.1.gz
+ *   javy-x86_64-windows-v7.0.1.gz   (no arm-windows)
+ */
+function platformArch() {
+    const p = process.platform;
+    const a = process.arch;
+    const plat = p === 'darwin' ? 'macos' : p === 'linux' ? 'linux' : p === 'win32' ? 'windows' : null;
+    const arch = a === 'arm64' ? 'arm' : a === 'x64' ? 'x86_64' : null;
+    if (!plat || !arch) {
+        throw new Error(`Unsupported platform/arch for Javy: ${p}/${a}`);
+    }
+    if (plat === 'windows' && arch === 'arm') {
+        throw new Error(`Javy ${JAVY_VERSION} has no arm-windows build; install x86_64 Node or run under Rosetta.`);
+    }
+    return `${arch}-${plat}`;
+}
+function javyUrl(version) {
+    return `https://github.com/bytecodealliance/javy/releases/download/${version}/javy-${platformArch()}-${version}.gz`;
+}
+/**
+ * Stream a remote .gz binary to a local file, decompressing on the
+ * way. Atomic via tmp + rename so concurrent test workers don't see
+ * partial files.
+ */
+async function downloadGz(url, dest) {
+    const tmp = `${dest}.tmp.${process.pid}`;
+    const r = await fetch(url);
+    if (!r.ok || !r.body) {
+        throw new Error(`Failed to download ${url} — HTTP ${r.status}`);
+    }
+    // `r.body` is a Web ReadableStream; convert to a Node Readable so
+    // we can pipe it through Node's gunzip + file sink.
+    const src = Readable.fromWeb(r.body);
+    await pipeline(src, createGunzip(), createWriteStream(tmp));
+    // chmod before rename so the executable bit is set atomically with
+    // the visible filename.
+    chmodSync(tmp, 0o755);
+    await import('node:fs/promises').then(({ rename }) => rename(tmp, dest));
+}
+/**
+ * Download a remote file as-is (no decompression). Used for the plugin
+ * wasm which is served uncompressed by Shopify's CDN.
+ */
+async function downloadFile(url, dest) {
+    const tmp = `${dest}.tmp.${process.pid}`;
+    const r = await fetch(url);
+    if (!r.ok || !r.body) {
+        throw new Error(`Failed to download ${url} — HTTP ${r.status}`);
+    }
+    const src = Readable.fromWeb(r.body);
+    await pipeline(src, createWriteStream(tmp));
+    await import('node:fs/promises').then(({ rename }) => rename(tmp, dest));
+}
+/**
+ * Return a path to the Javy binary, downloading it on first use.
+ * Idempotent — second call hits the on-disk cache. `JAVY_BIN`
+ * environment variable bypasses the download and points at a local
+ * build (useful when tracking Javy main).
+ */
+export async function ensureJavy() {
+    const override = process.env['JAVY_BIN'];
+    if (override) {
+        if (!existsSync(override)) {
+            throw new Error(`JAVY_BIN points at non-existent file: ${override}`);
+        }
+        return override;
+    }
+    const dest = join(cacheDir(), `javy-${JAVY_VERSION}`);
+    if (existsSync(dest))
+        return dest;
+    const url = javyUrl(JAVY_VERSION);
+    console.log(`  ↓ Downloading Javy ${JAVY_VERSION} from ${url}`);
+    await downloadGz(url, dest);
+    return dest;
+}
+/**
+ * Return a path to the Shopify Functions Javy plugin wasm,
+ * downloading it on first use. `JAVY_PLUGIN_WASM` env overrides for
+ * local plugin development.
+ */
+export async function ensureJavyPlugin() {
+    const override = process.env['JAVY_PLUGIN_WASM'];
+    if (override) {
+        if (!existsSync(override)) {
+            throw new Error(`JAVY_PLUGIN_WASM points at non-existent file: ${override}`);
+        }
+        return override;
+    }
+    const dest = join(cacheDir(), PLUGIN_FILENAME);
+    if (existsSync(dest))
+        return dest;
+    console.log(`  ↓ Downloading Shopify Functions Javy plugin from ${PLUGIN_URL}`);
+    await downloadFile(PLUGIN_URL, dest);
+    return dest;
+}
+/**
+ * Bespoke parser for the function's `shopify.extension.toml`. The
+ * minimal-toml reader in `deployAppVersion.ts` doesn't grok arrays of
+ * inline tables (`[[extensions.targeting]]`), so we do a tiny ad-hoc
+ * parse here. It's intentionally narrow — only handles the shape
+ * `shopify app function init` produces (essentially: a single
+ * `[[extensions]]` table containing N `[[extensions.targeting]]`
+ * sub-tables and one `[extensions.build]` sub-table).
+ *
+ * If/when we deploy a function with multiple top-level `[[extensions]]`
+ * entries (rare — usually one file per extension dir), this needs
+ * generalizing.
+ */
+export function parseFunctionToml(path) {
+    const txt = readFileSync(path, 'utf8');
+    const lines = txt.split('\n').map((l) => l.replace(/#.*$/, '').replace(/\s+$/, ''));
+    // We track the most-recently-opened table header so kv-lines are
+    // attached to the right place.
+    let section = 'other';
+    const targetingBlocks = [];
+    let cur = null;
+    const ext = {};
+    let apiVersion = '';
+    const build = {};
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (line === '[[extensions]]') {
+            section = 'extensions';
+            continue;
+        }
+        if (line === '[[extensions.targeting]]') {
+            section = 'targeting';
+            cur = {};
+            targetingBlocks.push(cur);
+            continue;
+        }
+        if (line === '[extensions.build]') {
+            section = 'build';
+            continue;
+        }
+        if (line.startsWith('[')) {
+            section = 'other';
+            continue;
+        }
+        const m = line.match(/^([a-z_][a-z0-9_]*)\s*=\s*"(.*)"$/i);
+        if (!m)
+            continue;
+        const [, k, v] = m;
+        if (section === 'targeting' && cur) {
+            if (k === 'target')
+                cur.target = v;
+            else if (k === 'export')
+                cur.export = v;
+            else if (k === 'input_query')
+                cur.inputQueryPath = v;
+        }
+        else if (section === 'extensions') {
+            if (k === 'handle')
+                ext.handle = v;
+            else if (k === 'uid')
+                ext.uid = v;
+            else if (k === 'type')
+                ext.type = v;
+        }
+        else if (section === 'build') {
+            if (k === 'path')
+                build.path = v;
+        }
+        else if (section === 'other') {
+            if (k === 'api_version')
+                apiVersion = v;
+        }
+    }
+    if (!ext.handle || !ext.uid || ext.type !== 'function') {
+        throw new Error(`Invalid function toml at ${path} — expected [[extensions]] with handle/uid/type=function. Got: ${JSON.stringify(ext)}`);
+    }
+    const targets = [];
+    for (const t of targetingBlocks) {
+        if (!t.target || !t.export || !t.inputQueryPath) {
+            throw new Error(`Invalid [[extensions.targeting]] in ${path} — needs target/export/input_query. Got: ${JSON.stringify(t)}`);
+        }
+        targets.push(t);
+    }
+    if (targets.length === 0) {
+        throw new Error(`No [[extensions.targeting]] blocks in ${path} — at least one is required.`);
+    }
+    return {
+        handle: ext.handle,
+        uid: ext.uid,
+        type: 'function',
+        apiVersion: apiVersion || 'unknown',
+        targets,
+        outputRelativePath: build.path ?? 'dist/function.wasm',
+    };
+}
+/**
+ * The CLI's `ExportJavyBuilder` synthesises an esbuild entry that
+ * re-exports each `[[extensions.targeting]].export` as a top-level
+ * function, delegating to the user's symbol of the same name. We
+ * mirror that exactly — variable names are arbitrary internal
+ * identifiers, only the EXPORTED names matter (they're what Javy
+ * sees and what Shopify's runtime invokes).
+ *
+ * Why kebab-case in the export string matches the JS identifier:
+ * Shopify's convention uses kebab-case in toml. The matching JS
+ * identifier is the camelCase form (per the Shopify CLI's
+ * convention). We accept both spellings — fall back to camelCase if
+ * the source happens not to define the literal kebab name (which is
+ * not a valid JS identifier anyway when used directly).
+ */
+function jsIdent(exportName) {
+    // kebab-case -> camelCase (Shopify CLI convention for the user-side
+    // entry symbol). `cart-lines-discounts-generate-run` →
+    // `cartLinesDiscountsGenerateRun`.
+    return exportName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function synthesizeEntry(targets) {
+    // The exported NAME has to be the camelCase form of the WIT identifier.
+    // Javy translates WIT `%kebab-case-name` → JS export `camelCaseName` when
+    // resolving the world's exports. If the JS module exports the kebab-case
+    // string form, Javy fails with:
+    //   "JS module does not export camelCaseName"
+    // (Confirmed empirically — see commit history.) The user's source code
+    // also exports camelCase by convention.
+    const importLines = [
+        `import __runFunction from "@shopify/shopify_function/run";`,
+    ];
+    const exportLines = [];
+    for (let i = 0; i < targets.length; i++) {
+        const t = targets[i];
+        const ident = jsIdent(t.export);
+        importLines.push(`import { ${ident} as __target${i} } from "user-function";`);
+        exportLines.push(`export function ${ident}() { return __runFunction(__target${i}); }`);
+    }
+    return `${importLines.join('\n')}\n${exportLines.join('\n')}\n`;
+}
+/**
+ * Synthesize the WIT world file that Javy needs to know which
+ * exports to lift from the JS module. The CLI generates this on the
+ * fly per build; we follow suit.
+ */
+function synthesizeWit(targets) {
+    const exports = targets
+        .map((t) => `  export %${t.export}: func();`)
+        .join('\n');
+    return `package shopify:function;\nworld ${JAVY_WORLD_NAME} {\n${exports}\n}\n`;
+}
+/** Identify the user-source entry path. Function dirs traditionally
+ *  use `src/index.ts` (TypeScript) or `src/index.js`. We accept both
+ *  — if neither exists, the error message points at the convention. */
+function findEntrySource(functionDir) {
+    for (const candidate of ['src/index.ts', 'src/index.js']) {
+        const p = resolve(functionDir, candidate);
+        if (existsSync(p))
+            return p;
+    }
+    throw new Error(`No function entry found in ${functionDir}. Expected one of: src/index.ts, src/index.js`);
+}
+/**
+ * Build a deployable `.wasm` for a JS Shopify Function.
+ *
+ * Idempotent: rebuilds on every call (we don't try to be clever about
+ * stale-cache detection — esbuild + javy together are ~hundreds of
+ * milliseconds, fast enough that incremental caching is unnecessary
+ * for our use case).
+ */
+export async function buildFunctionWasm(opts) {
+    const { functionDir } = opts;
+    const tomlPath = resolve(functionDir, 'shopify.extension.toml');
+    if (!existsSync(tomlPath)) {
+        throw new Error(`No shopify.extension.toml at ${tomlPath}`);
+    }
+    const toml = parseFunctionToml(tomlPath);
+    console.log(`  • function ${toml.handle} (uid=${toml.uid}, ${toml.targets.length} target(s), api ${toml.apiVersion})`);
+    const entryPath = opts.entrySource ?? findEntrySource(functionDir);
+    const outputWasm = resolve(functionDir, toml.outputRelativePath);
+    const distDir = dirname(outputWasm);
+    mkdirSync(distDir, { recursive: true });
+    // Step 1: bundle JS with esbuild.
+    const bundledJs = resolve(distDir, 'function.js');
+    const entryContents = synthesizeEntry(toml.targets);
+    await esbuild.build({
+        stdin: {
+            contents: entryContents,
+            resolveDir: functionDir,
+            loader: 'ts',
+            sourcefile: 'shopify-function-entry.ts',
+        },
+        bundle: true,
+        format: 'esm',
+        target: 'es2022',
+        legalComments: 'none',
+        outfile: bundledJs,
+        alias: {
+            'user-function': entryPath,
+        },
+        // Node-side bundler. Functions don't have access to Node APIs
+        // (the runtime is QuickJS via Javy), so we set platform=neutral
+        // and don't try to polyfill anything Node-specific.
+        platform: 'neutral',
+        // QuickJS exposes a recent-ish JS surface but ECMAScript modules
+        // are handled by Javy's runtime — esbuild's `format: esm` output
+        // is what Javy expects.
+        mainFields: ['module', 'main'],
+        conditions: ['shopify_function', 'import', 'default'],
+    });
+    // Step 2: WIT + javy build.
+    const witPath = resolve(distDir, 'javy-world.wit');
+    writeFileSync(witPath, synthesizeWit(toml.targets), 'utf8');
+    const [javy, plugin] = await Promise.all([ensureJavy(), ensureJavyPlugin()]);
+    const javyArgs = [
+        'build',
+        '-C', 'dynamic',
+        '-C', `plugin=${plugin}`,
+        '-C', `wit=${witPath}`,
+        '-C', `wit-world=${JAVY_WORLD_NAME}`,
+        '-o', outputWasm,
+        bundledJs,
+    ];
+    // `cwd: functionDir` so Javy resolves any relative paths in its
+    // diagnostics (it doesn't, AFAICT, but parity with the CLI is
+    // cheap).
+    await execFileP(javy, javyArgs, { cwd: functionDir, maxBuffer: 50 * 1024 * 1024 });
+    return { wasmPath: outputWasm, parsedToml: toml };
+}
+//# sourceMappingURL=functionBuild.js.map

package/dist/lib/functionBuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functionBuild.js","sourceRoot":"","sources":["../../src/lib/functionBuild.ts"],"names":[],"mappings":"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"}

package/dist/lib/neonWsProxy.d.ts

@@ -0,0 +1,41 @@
+export interface StartNeonWsProxyOptions {
+    /** Port to listen on (0 = OS-assigned). */
+    port?: number;
+    /** Listen host. Default 127.0.0.1. */
+    host?: string;
+    /** Postgres host to forward to. Default 127.0.0.1. */
+    targetHost?: string;
+    /** Postgres port to forward to. Default 5432. */
+    targetPort?: number;
+}
+export interface StartedNeonWsProxy {
+    /** Port the proxy listens on. */
+    port: number;
+    /** Stop the proxy + close all bridged sockets. */
+    close: () => Promise<void>;
+}
+/**
+ * Minimal WebSocket→TCP proxy implementing the transport the Neon
+ * serverless driver (`@neondatabase/serverless`) speaks to its
+ * `wsProxy`. It lets a consuming app's UNMODIFIED prisma client (which
+ * uses `new Pool()` from @neondatabase/serverless + `@prisma/adapter-neon`)
+ * talk to the offline-full suite's plain LOCAL Postgres — no app-source
+ * change, which is the whole point of zero-app-touch onboarding.
+ *
+ * Target resolution: when `wsProxy` is a custom function, the driver
+ * connects to `ws://<wsProxy()>` and does NOT append the DB address to
+ * the URL (verified empirically — `?address` is empty), so we forward to
+ * a CONFIGURED fixed Postgres (`targetHost`/`targetPort`). The Postgres
+ * wire-protocol startup packet (forwarded byte-for-byte) carries the
+ * user + database from the connection string, so a fixed server target
+ * is sufficient. We still honour `?address=` if a driver version sets it.
+ *
+ * `localhost` is normalised to `127.0.0.1`: some resolvers / Docker map
+ * localhost→::1 where Postgres may listen only on IPv4.
+ *
+ * Faithful passthrough by design: the REAL Neon driver runs unchanged;
+ * we only relocate its endpoint to local Postgres, avoiding the
+ * adapter-compat risk of swapping in a different pg driver.
+ */
+export declare function startNeonWsProxy(opts?: StartNeonWsProxyOptions): Promise<StartedNeonWsProxy>;
+//# sourceMappingURL=neonWsProxy.d.ts.map

package/dist/lib/neonWsProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neonWsProxy.d.ts","sourceRoot":"","sources":["../../src/lib/neonWsProxy.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CA6E7B"}

package/dist/lib/neonWsProxy.js

@@ -0,0 +1,101 @@
+import net from 'node:net';
+import { WebSocketServer } from 'ws';
+/**
+ * Minimal WebSocket→TCP proxy implementing the transport the Neon
+ * serverless driver (`@neondatabase/serverless`) speaks to its
+ * `wsProxy`. It lets a consuming app's UNMODIFIED prisma client (which
+ * uses `new Pool()` from @neondatabase/serverless + `@prisma/adapter-neon`)
+ * talk to the offline-full suite's plain LOCAL Postgres — no app-source
+ * change, which is the whole point of zero-app-touch onboarding.
+ *
+ * Target resolution: when `wsProxy` is a custom function, the driver
+ * connects to `ws://<wsProxy()>` and does NOT append the DB address to
+ * the URL (verified empirically — `?address` is empty), so we forward to
+ * a CONFIGURED fixed Postgres (`targetHost`/`targetPort`). The Postgres
+ * wire-protocol startup packet (forwarded byte-for-byte) carries the
+ * user + database from the connection string, so a fixed server target
+ * is sufficient. We still honour `?address=` if a driver version sets it.
+ *
+ * `localhost` is normalised to `127.0.0.1`: some resolvers / Docker map
+ * localhost→::1 where Postgres may listen only on IPv4.
+ *
+ * Faithful passthrough by design: the REAL Neon driver runs unchanged;
+ * we only relocate its endpoint to local Postgres, avoiding the
+ * adapter-compat risk of swapping in a different pg driver.
+ */
+export async function startNeonWsProxy(opts = {}) {
+    const host = opts.host ?? '127.0.0.1';
+    const norm = (h) => (h === 'localhost' ? '127.0.0.1' : h);
+    const defaultTargetHost = norm(opts.targetHost ?? '127.0.0.1');
+    const defaultTargetPort = opts.targetPort ?? 5432;
+    return new Promise((resolve, reject) => {
+        const wss = new WebSocketServer({ port: opts.port ?? 0, host });
+        wss.once('error', reject);
+        wss.once('listening', () => {
+            wss.off('error', reject);
+            const addr = wss.address();
+            const port = typeof addr === 'object' && addr ? addr.port : Number(opts.port ?? 0);
+            resolve({
+                port,
+                close: () => new Promise((res) => {
+                    for (const client of wss.clients) {
+                        try {
+                            client.terminate();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }
+                    wss.close(() => res());
+                }),
+            });
+        });
+        wss.on('connection', (ws, req) => {
+            let targetHost = defaultTargetHost;
+            let targetPort = defaultTargetPort;
+            // Honour `?address=host:port` if the driver ever provides it;
+            // otherwise fall back to the configured fixed Postgres.
+            const address = new URL(req.url ?? '/', 'http://localhost').searchParams.get('address');
+            if (address) {
+                const i = address.lastIndexOf(':');
+                if (i > 0) {
+                    targetHost = norm(address.slice(0, i));
+                    targetPort = Number(address.slice(i + 1)) || defaultTargetPort;
+                }
+            }
+            // net.connect queues writes until connected, so we can wire
+            // `ws → tcp` immediately without racing the connect.
+            const tcp = net.connect({ host: targetHost, port: targetPort });
+            let closed = false;
+            const cleanup = () => {
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                try {
+                    tcp.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+            };
+            // `ws` server delivers binary frames as Buffer (binaryType
+            // 'nodebuffer'); the Postgres wire protocol is binary.
+            ws.on('message', (data) => tcp.write(data));
+            tcp.on('data', (data) => {
+                if (ws.readyState === ws.OPEN)
+                    ws.send(data);
+            });
+            ws.on('close', cleanup);
+            ws.on('error', cleanup);
+            tcp.on('close', cleanup);
+            tcp.on('error', cleanup);
+        });
+    });
+}
+//# sourceMappingURL=neonWsProxy.js.map

package/dist/lib/neonWsProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"neonWsProxy.js","sourceRoot":"","sources":["../../src/lib/neonWsProxy.ts"],"names":[],"mappings":"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"}

package/dist/lib/sourceZipUpload.d.ts

@@ -0,0 +1,45 @@
+export interface RequestSourceUploadUrlOptions {
+    /** Bearer token from `exchangeAutomationToken`. */
+    accessToken: string;
+    /** Numeric Partner-org ID. Required — the endpoint won't infer it
+     *  from the access token, even though it's already scoped to one
+     *  org. (Discovered empirically: omitting it yields a generic 404.) */
+    organizationId: string;
+    /**
+     * Archive format. Defaults to 'BR' (tar+brotli) which the
+     * App Management server fully supports including function
+     * extensions. 'ZIP' is accepted for legacy callers but the
+     * server's function-deploy path 500s on zip-with-folders.
+     */
+    sourceExtension?: 'BR' | 'ZIP';
+}
+/**
+ * Mint a fresh signed upload URL. The URL is valid for 3600 seconds;
+ * upload + version-create should both happen well within that window.
+ *
+ * Returns the GCS URL verbatim — you pass the SAME URL to
+ * `appVersionCreate` as `sourceUrl`. Shopify maintains the mapping
+ * server-side between the signed URL and the uploaded object.
+ */
+export declare function requestSourceUploadUrl(opts: RequestSourceUploadUrlOptions): Promise<string>;
+export interface UploadSourceOptions {
+    uploadUrl: string;
+    /** Path on disk to the archive file (typically a `.tar.br` from
+     *  `buildSourceBundle`, or a legacy `.zip`). */
+    archivePath: string;
+}
+/**
+ * PUT an archive file to the signed GCS URL minted by
+ * `requestSourceUploadUrl`. The URL embeds its own auth (signed
+ * `X-Goog-*` query params), so no bearer is needed on this request.
+ *
+ * Headers: we send only `Content-Length`. The CLI doesn't set a
+ * Content-Type for these uploads (it builds a multipart form to
+ * derive headers but sends the raw buffer as body, and GCS ignores
+ * the content-type anyway because the signed URL pins everything
+ * server-side). We match that for parity.
+ *
+ * Streams the file so a multi-MB archive doesn't sit in memory.
+ */
+export declare function uploadSourceToSignedUrl(opts: UploadSourceOptions): Promise<void>;
+//# sourceMappingURL=sourceZipUpload.d.ts.map

package/dist/lib/sourceZipUpload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceZipUpload.d.ts","sourceRoot":"","sources":["../../src/lib/sourceZipUpload.ts"],"names":[],"mappings":"AAwEA,MAAM,WAAW,6BAA6B;IAC5C,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB;;2EAEuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,IAAI,GAAG,KAAK,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB;oDACgD;IAChD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,IAAI,CAAC,CAsBf"}