@firenet-designs/fnd-cli 2.6.0 → 2.7.0

package/dist/lib/shopify/shopify.js

@@ -0,0 +1,662 @@
+/**
+ * Shopify support for `fnd alt-text`.
+ *
+ * The Webflow path talks to the Data API directly with a bearer token we hold.
+ * The Shopify path deliberately does NOT: it shells out to the user's own
+ * Shopify CLI (`shopify store execute` / `shopify store auth`), which owns the
+ * OAuth session and the token. We never see, store, or print a credential —
+ * which is exactly why `alt-text` takes no --api-key for Shopify.
+ *
+ * Files (the Shopify asset library) are read and captioned through Admin
+ * GraphQL, run via `shopify store execute --json`. GraphQL lives under graphql/,
+ * never string-interpolated here: named operations (one per file — see docPath)
+ * go to the CLI with --query-file and their parameters with --variables, while
+ * bulk query bodies (readBulkQuery) are handed to StartBulkQuery as a variable.
+ * Both the file list and the product→image map are read with bulk operations —
+ * one streamed JSONL each, no pagination and no per-minute throttle.
+ *
+ * Every CLI call has stderr routed to /dev/null (stdio 'ignore') on purpose:
+ * with --json the meaningful output is on stdout, and the CLI's progress/spinner
+ * chatter on stderr would otherwise corrupt what we try to JSON.parse.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The scopes the run needs: list files (read) and set their alt text (write),
+ * plus read products so a file can be captioned with the context of the product
+ * it's attached to. Nothing here should grow without a matching need — the point
+ * of asking for the least is that a client store grants the least.
+ */
+export const REQUIRED_SCOPES = ['read_files', 'write_files', 'read_products'];
+/**
+ * A --dry run only lists the files to count them — it never writes alt text and
+ * never maps product context — so read_files is the whole ask. Keeping this
+ * minimal means a dry run works against a store that only ever granted the read
+ * scope, and doesn't provoke an auth prompt for write access it won't use.
+ */
+export const DRY_RUN_SCOPES = ['read_files'];
+/**
+ * Writing to the store's asset library — uploading, replacing a file's bytes in
+ * place, or deleting a file — only needs write access to files. `write_files`
+ * subsumes `read_files` (see missingScopes), so this single scope is the whole
+ * ask — the least a store has to grant for any of the Shopify `--with-tool` tools.
+ */
+export const FILE_WRITE_SCOPES = ['write_files'];
+/**
+ * The `shopify-file-search` workspace tool only reads file metadata, so
+ * `read_files` is its whole ask — the least a store grants for a read-only
+ * search, and (unlike the write tools) it never provokes a write-scope prompt.
+ */
+export const FILE_READ_SCOPES = ['read_files'];
+/**
+ * Which of `required` the installation is still missing, given the scopes it
+ * already `granted`. A write scope subsumes its read counterpart — a store that
+ * granted `write_files` can read files too — so `write_files` satisfies a
+ * `read_files` requirement without read_files being listed separately.
+ */
+export const missingScopes = (granted, required) => required.filter((scope) => {
+    if (granted.includes(scope))
+        return false;
+    // `read_x` is implied by `write_x`; nothing implies a write scope.
+    return !(scope.startsWith('read_') && granted.includes(scope.replace('read_', 'write_')));
+});
+/**
+ * Absolute path to a bundled GraphQL document.
+ *
+ * Every document lives in the sibling graphql/ folder, resolved relative to this
+ * module — dist/lib/shopify under ts-node and when built, since the build copies
+ * graphql/ alongside the compiled JS. The document name and the file's basename
+ * are kept identical so a caller naming `'Files…'` always gets that file.
+ */
+const docPath = (name) => fileURLToPath(new URL(`graphql/${name}.graphql`, import.meta.url));
+/**
+ * The text of a bulk query body, cached after the first read. Unlike a named
+ * operation (handed to the CLI as a --query-file path), a bulk query body is
+ * passed by value as the $query variable, so its contents are read here.
+ */
+const bulkQueryCache = new Map();
+const readBulkQuery = (name) => {
+    let query = bulkQueryCache.get(name);
+    if (query === undefined) {
+        query = readFileSync(docPath(name), 'utf8');
+        bulkQueryCache.set(name, query);
+    }
+    return query;
+};
+/** `mystore`, `mystore.myshopify.com`, or `https://mystore.myshopify.com/` -> `mystore.myshopify.com`. */
+export const normalizeStore = (raw) => {
+    const host = raw
+        .trim()
+        .replace(/^https?:\/\//, '')
+        .replace(/\/.*$/, '');
+    return host.endsWith('.myshopify.com') ? host : `${host}.myshopify.com`;
+};
+const executeArgs = (store, operation, { mutate = false, variables }) => {
+    const args = ['store', 'execute', '--store', store, '--json', '--query-file', docPath(operation)];
+    if (variables)
+        args.push('--variables', JSON.stringify(variables));
+    if (mutate)
+        args.push('--allow-mutations');
+    return args;
+};
+/** Turn a finished CLI run into the operation's `data`, or throw with the reason. */
+const parseExecuteResult = (code, stdout, stderr) => {
+    if (code !== 0) {
+        // The CLI prints the real reason (auth, throttling, an invalid query) to
+        // stderr; fall back to stdout, then to nothing, so the message is useful.
+        const detail = (stderr || stdout || '').trim();
+        throw new Error(`shopify store execute failed (exit ${code ?? 'unknown'})${detail ? `: ${detail.slice(0, 500)}` : ''}`);
+    }
+    const json = JSON.parse(stdout);
+    if (json.errors)
+        throw new Error(`Shopify GraphQL error: ${JSON.stringify(json.errors).slice(0, 300)}`);
+    return json.data ?? json;
+};
+const execute = (bin, store, operation, opts = {}) => {
+    const result = spawnSync(bin, executeArgs(store, operation, opts), {
+        encoding: 'utf8',
+        // A page of file records is small, but headroom costs nothing and a
+        // truncated buffer would surface as an unhelpful JSON parse error.
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return parseExecuteResult(result.status, result.stdout ?? '', result.stderr ?? '');
+};
+const spawnAsync = (command, args, options = {}) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, options);
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.setEncoding('utf8').on('data', (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr?.setEncoding('utf8').on('data', (chunk) => {
+        stderr += chunk;
+    });
+    child.on('error', (error) => reject(error));
+    child.on('close', (status, signal) => {
+        resolve({ signal, status, stderr, stdout });
+    });
+});
+/**
+ * Same as `execute`, but non-blocking — the CLI runs in a real child process and
+ * we await its exit rather than parking the event loop on spawnSync. Used on any
+ * path that runs while an ora spinner is up (the bulk-status poll), so the
+ * spinner keeps animating.
+ */
+const executeAsync = async (bin, store, operation, opts = {}) => {
+    const result = await spawnAsync(bin, executeArgs(store, operation, opts), { stdio: ['ignore', 'pipe', 'pipe'] });
+    return parseExecuteResult(result.status, result.stdout, result.stderr);
+};
+/**
+ * Run an ARBITRARY Admin GraphQL document through the user's Shopify CLI and hand
+ * back the CLI's raw JSON output as text. This backs the `shopify-execute`
+ * workspace tool, whose whole point is to let the AI run a query it composed —
+ * unlike `execute`, the document isn't one of our bundled named operations, so it
+ * can't go through `--query-file <bundled>`; instead it's written to a throwaway
+ * temp file the CLI reads (and which we always delete). `store execute` refuses
+ * mutations unless `--allow-mutations`, so a mutation must set `mutate: true`.
+ *
+ * Deliberately never throws: the AI needs to SEE the failure text to fix its own
+ * query, so a non-zero exit or a GraphQL `errors` payload comes back as
+ * `{ ok: false, output }` (the message / the response body) rather than an
+ * exception. On success `output` is the response JSON verbatim.
+ */
+export const runStoreExecute = (bin, store, opts) => {
+    const dir = mkdtempSync(join(tmpdir(), 'fnd-shopify-exec-'));
+    const file = join(dir, 'operation.graphql');
+    try {
+        writeFileSync(file, opts.query);
+        const args = ['store', 'execute', '--store', store, '--json', '--query-file', file];
+        if (opts.variables)
+            args.push('--variables', JSON.stringify(opts.variables));
+        if (opts.mutate)
+            args.push('--allow-mutations');
+        const result = spawnSync(bin, args, {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = (result.stdout ?? '').trim();
+        const stderr = (result.stderr ?? '').trim();
+        if (result.status !== 0) {
+            // Auth, an invalid query, a missing scope: the CLI puts the reason on
+            // stderr (stdout as a fallback). Hand it straight back so the AI can react.
+            const detail = stderr || stdout;
+            return { ok: false, output: `shopify store execute failed (exit ${result.status ?? 'unknown'})${detail ? `:\n${detail}` : ''}` };
+        }
+        // A clean exit can still carry GraphQL `errors` (a bad field, a scope the
+        // installation lacks); flag those as not-ok while returning the body so the
+        // AI sees the message, matching how a real error reads.
+        try {
+            const json = JSON.parse(stdout);
+            if (json && typeof json === 'object' && json.errors)
+                return { ok: false, output: stdout };
+        }
+        catch {
+            // Not JSON (unusual with --json) — return whatever the CLI printed as-is.
+        }
+        return { ok: true, output: stdout || '(no output)' };
+    }
+    finally {
+        rmSync(dir, { force: true, recursive: true });
+    }
+};
+/**
+ * The scopes the store's app installation currently grants.
+ *
+ * `authenticated` is false when `shopify store execute` exits non-zero — the
+ * task's contract for "this store needs `shopify store auth`". A store that IS
+ * authenticated but is missing a scope still comes back authenticated, just with
+ * that scope absent from the list, so the caller can tell the two apart.
+ */
+export const getInstalledScopes = (bin, store) => {
+    const result = spawnSync(bin, ['store', 'execute', '--store', store, '--json', '--query-file', docPath('AccessScopes')], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0)
+        return { authenticated: false, scopes: [] };
+    try {
+        const json = JSON.parse(result.stdout);
+        const scopes = (json.data ?? json).currentAppInstallation?.accessScopes ?? [];
+        return { authenticated: true, scopes: scopes.map((scope) => scope.handle) };
+    }
+    catch {
+        // Authenticated (exit 0) but unparseable output — treat scopes as unknown
+        // rather than crash; the caller will just re-run auth to be safe.
+        return { authenticated: true, scopes: [] };
+    }
+};
+/**
+ * Grant `scopes` to the store via `shopify store auth`. This both authenticates
+ * a store that never was and adds any missing scopes to one that already is, so
+ * the caller always passes the full required set.
+ *
+ * stdin/stdout are inherited so the user can complete the browser/login flow the
+ * CLI may open; only stderr is suppressed, matching the task's `2> /dev/null`.
+ * Returns whether the CLI exited cleanly.
+ */
+export const authenticate = (bin, store, scopes) => {
+    const result = spawnSync(bin, ['store', 'auth', '--json', '--store', store, '--scopes', scopes.join(',')], {
+        stdio: ['inherit', 'inherit', 'ignore'],
+    });
+    return result.status === 0;
+};
+/**
+ * Every image in the store's asset library, streamed from a single **bulk
+ * operation** rather than paginated — one JSONL export, no per-minute throttle,
+ * however large the library.
+ *
+ * `media_type:IMAGE` keeps videos, 3D models and generic files out. `alt` and
+ * `id` are on the File interface; the CDN `url`, `mimeType`, dimensions and
+ * `originalSource.fileSize` are on the MediaImage. The metadata rides along so a
+ * --dry run can filter without downloading (see ShopifyImageFile). A bulk query
+ * takes no variables, so — unlike the old paged query — it can't @skip those
+ * fields for a real run; they're a few scalars per row in a stream a real run
+ * ignores anyway (it measures the bytes it downloads instead).
+ *
+ * @yields each image file.
+ */
+export async function* getImageFiles(bin, store) {
+    const jsonl = await runBulkQuery(bin, store, readBulkQuery('FilesBulkQuery'));
+    if (!jsonl)
+        return;
+    // Bulk output is one JSON object per line. The files connection has no nested
+    // connections in this query, so every line is a whole file node — `image` and
+    // `originalSource` are inline objects, not __parentId child rows.
+    for (const raw of jsonl.split('\n')) {
+        if (!raw.trim())
+            continue;
+        const node = JSON.parse(raw);
+        const url = node.image?.url;
+        // A MediaImage still processing has no url yet; skip it rather than fail.
+        if (url)
+            yield {
+                alt: node.alt ?? null,
+                fileSize: node.originalSource?.fileSize ?? null,
+                height: node.image?.height ?? null,
+                id: node.id,
+                mimeType: node.mimeType ?? null,
+                name: fileName(url),
+                url,
+                width: node.image?.width ?? null,
+            };
+    }
+}
+/**
+ * One `files` connection node → its metadata, or null when the file has no url
+ * yet (still processing). MediaImage carries image.url + dimensions +
+ * originalSource.fileSize; GenericFile carries url + originalFileSize.
+ */
+const toFileMeta = (node) => {
+    const url = node.image?.url ?? node.url ?? undefined;
+    if (!url)
+        return null;
+    return {
+        alt: node.alt ?? null,
+        fileSize: node.originalSource?.fileSize ?? node.originalFileSize ?? null,
+        height: node.image?.height ?? null,
+        id: node.id,
+        mimeType: node.mimeType ?? null,
+        name: fileName(url),
+        url,
+        width: node.image?.width ?? null,
+    };
+};
+export async function* searchFiles(bin, store, opts) {
+    const first = opts.pageSize ?? 250;
+    let after = null;
+    for (;;) {
+        const variables = { after, first, query: opts.query, reverse: opts.reverse, sortKey: opts.sortKey };
+        // eslint-disable-next-line no-await-in-loop -- sequential cursor pagination
+        const data = (await executeAsync(bin, store, 'SearchFiles', { variables }));
+        for (const { node } of data.files?.edges ?? []) {
+            const meta = toFileMeta(node);
+            if (meta)
+                yield meta;
+        }
+        const pageInfo = data.files?.pageInfo;
+        if (!pageInfo?.hasNextPage || !pageInfo.endCursor)
+            return;
+        after = pageInfo.endCursor;
+    }
+}
+/** How long to wait between polls of the bulk export's status. */
+const BULK_POLL_MS = 2000;
+/** Give up on the bulk export after this long rather than poll forever. */
+const BULK_TIMEOUT_MS = 5 * 60 * 1000;
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Run one bulk query to completion and hand back its JSONL result (null when the
+ * export produced nothing to download). Starting a bulk query counts as a
+ * mutation to the CLI, so StartBulkQuery opts into --allow-mutations even though
+ * it only reads. A store runs at most one bulk query at a time, so the two
+ * callers (the file list and the product map) invoke this sequentially.
+ */
+const runBulkQuery = async (bin, store, query) => {
+    // executeAsync (not execute) throughout: this whole flow runs under a spinner,
+    // so it must never block the event loop.
+    const started = (await executeAsync(bin, store, 'StartBulkQuery', { mutate: true, variables: { query } }));
+    const errors = started.bulkOperationRunQuery?.userErrors ?? [];
+    if (errors.length > 0)
+        throw new Error(`Could not start the bulk export: ${errors.map((e) => e.message).join('; ')}`);
+    const url = await waitForBulkQuery(bin, store);
+    return url ? downloadText(url) : null;
+};
+/**
+ * Map every product image to the product it belongs to, so a file can be
+ * captioned knowing it's (say) snowboard wax rather than a candle.
+ *
+ * The public Admin API has no field on a MediaImage pointing back to its
+ * product, so the relationship is walked from the product side via a **bulk
+ * operation** (see ProductsBulkQuery): the whole catalog streams into one JSONL
+ * file, which is the right tool when the map has to cover every product at once.
+ * The result is folded into a `{mediaImageId -> product}` lookup.
+ *
+ * An image shared by several products keeps the first product that claims it —
+ * a corner case whose only cost is a slightly-off hint, never a wrong caption.
+ */
+export const getImageProductContext = async (bin, store) => {
+    const jsonl = await runBulkQuery(bin, store, readBulkQuery('ProductsBulkQuery'));
+    // A null result means the export finished with nothing to download (no products).
+    return jsonl ? parseProductJsonl(jsonl) : new Map();
+};
+/** Poll the query bulk operation until it finishes, returning its result URL. */
+const waitForBulkQuery = async (bin, store) => {
+    const deadline = Date.now() + BULK_TIMEOUT_MS;
+    for (;;) {
+        // Async so the poll doesn't block the event loop — a spawnSync here would
+        // freeze the caller's ora spinner between polls.
+        // eslint-disable-next-line no-await-in-loop
+        const { currentBulkOperation } = (await executeAsync(bin, store, 'CurrentBulkOperation'));
+        const status = currentBulkOperation?.status;
+        if (status === 'COMPLETED')
+            return currentBulkOperation?.url ?? null;
+        if (status === 'CANCELED' || status === 'EXPIRED' || status === 'FAILED') {
+            const code = currentBulkOperation?.errorCode;
+            throw new Error(`Product bulk export ${status.toLowerCase()}${code ? ` (${code})` : ''}`);
+        }
+        if (Date.now() > deadline)
+            throw new Error('Timed out waiting for the product bulk export');
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(BULK_POLL_MS);
+    }
+};
+/** Download a bulk operation's JSONL result. No auth — the URL is pre-signed. */
+const downloadText = async (url) => {
+    const resp = await fetch(url);
+    if (!resp.ok)
+        throw new Error(`Could not download the product bulk export (${resp.status} ${resp.statusText})`);
+    return resp.text();
+};
+/**
+ * Fold a bulk export's JSONL into a `{mediaImageId -> product}` map.
+ *
+ * Bulk output is flat: each product is one line and each of its media is another
+ * line carrying `__parentId`, rather than nested. So products are collected
+ * first, then each media line is joined back to its product by that id.
+ */
+const parseProductJsonl = (jsonl) => {
+    const products = new Map();
+    const media = [];
+    for (const raw of jsonl.split('\n')) {
+        if (!raw.trim())
+            continue;
+        const line = JSON.parse(raw);
+        // A product line has a title; a media line has a __parentId. Only image
+        // media carries a MediaImage id (the fragment leaves videos/3D without one).
+        if (line.title !== undefined && line.id) {
+            products.set(line.id, {
+                productType: line.productType ?? '',
+                tags: line.tags ?? [],
+                title: line.title,
+                vendor: line.vendor ?? '',
+            });
+        }
+        else if (line.__parentId && line.id?.startsWith('gid://shopify/MediaImage/')) {
+            media.push({ mediaId: line.id, parent: line.__parentId });
+        }
+    }
+    const map = new Map();
+    for (const { mediaId, parent } of media) {
+        const context = products.get(parent);
+        // First product to claim a shared image wins.
+        if (context && !map.has(mediaId))
+            map.set(mediaId, context);
+    }
+    return map;
+};
+/** A one-line context hint for the prompt, skipping whatever fields are empty. */
+export const formatProductContext = (context) => {
+    const details = [];
+    if (context.productType)
+        details.push(`type: ${context.productType}`);
+    if (context.vendor)
+        details.push(`vendor: ${context.vendor}`);
+    if (context.tags.length > 0)
+        details.push(`tags: ${context.tags.join(', ')}`);
+    const suffix = details.length > 0 ? ` (${details.join('; ')})` : '';
+    return `It is used on the product "${context.title}"${suffix}`;
+};
+/** Set one file's alt text. Throws on any userErrors the mutation reports. */
+export const updateFileAlt = (bin, store, id, alt) => {
+    const data = execute(bin, store, 'UpdateFileAlt', { mutate: true, variables: { alt, id } });
+    const errors = data.fileUpdate?.userErrors ?? [];
+    if (errors.length > 0)
+        throw new Error(`Shopify fileUpdate error: ${errors.map((error) => error.message).join('; ')}`);
+};
+/** Guess a MIME type from a filename extension — enough for staging an upload. */
+const MIME_BY_EXT = {
+    avif: 'image/avif',
+    css: 'text/css',
+    csv: 'text/csv',
+    gif: 'image/gif',
+    heic: 'image/heic',
+    ico: 'image/x-icon',
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    js: 'text/javascript',
+    json: 'application/json',
+    mov: 'video/quicktime',
+    mp4: 'video/mp4',
+    pdf: 'application/pdf',
+    png: 'image/png',
+    svg: 'image/svg+xml',
+    txt: 'text/plain',
+    webm: 'video/webm',
+    webp: 'image/webp',
+};
+const mimeFromName = (name) => {
+    const ext = name.split('.').pop()?.toLowerCase() ?? '';
+    return MIME_BY_EXT[ext] ?? 'application/octet-stream';
+};
+/**
+ * Shopify's resource/content-type buckets. Images and videos get their own
+ * first-class media types in the library; everything else is a generic FILE.
+ * The same value serves stagedUploadsCreate's `resource` and fileCreate's
+ * `contentType`, which share these enum members.
+ */
+const resourceForMime = (mime) => {
+    if (mime.startsWith('image/'))
+        return 'IMAGE';
+    if (mime.startsWith('video/'))
+        return 'VIDEO';
+    return 'FILE';
+};
+/** Step 1: reserve a staging slot and return its pre-authorized upload target. */
+const startStagedUpload = (bin, store, file) => {
+    const staged = execute(bin, store, 'StagedUploadsCreate', {
+        mutate: true,
+        variables: { input: [{ filename: file.filename, httpMethod: 'POST', mimeType: file.mimeType, resource: file.resource }] },
+    });
+    const errors = staged.stagedUploadsCreate?.userErrors ?? [];
+    if (errors.length > 0)
+        throw new Error(`Shopify stagedUploadsCreate error: ${errors.map((e) => e.message).join('; ')}`);
+    const target = staged.stagedUploadsCreate?.stagedTargets?.[0];
+    if (!target)
+        throw new Error('Shopify returned no staged upload target for the file.');
+    return target;
+};
+/** Step 2: multipart-POST the bytes to the staged target (params first, file last — GCS's rule). */
+const postToStagedTarget = async (target, bytes, filename, mimeType) => {
+    const form = new FormData();
+    for (const param of target.parameters)
+        form.append(param.name, param.value);
+    form.append('file', new Blob([new Uint8Array(bytes)], { type: mimeType }), filename);
+    const resp = await fetch(target.url, { body: form, method: 'POST' });
+    if (!resp.ok) {
+        const detail = (await resp.text().catch(() => '')).slice(0, 300);
+        throw new Error(`Staged upload POST failed (${resp.status} ${resp.statusText})${detail ? `: ${detail}` : ''}`);
+    }
+};
+/** Step 3: register the staged upload as a real file, returning its id/url/status. */
+const createFile = (bin, store, input) => {
+    const created = execute(bin, store, 'FileCreate', {
+        mutate: true,
+        variables: { files: [{ alt: input.alt, contentType: input.resource, originalSource: input.resourceUrl }] },
+    });
+    const errors = created.fileCreate?.userErrors ?? [];
+    if (errors.length > 0)
+        throw new Error(`Shopify fileCreate error: ${errors.map((e) => e.message).join('; ')}`);
+    const file = created.fileCreate?.files?.[0];
+    if (!file)
+        throw new Error('Shopify fileCreate returned no file.');
+    return { alt: file.alt ?? null, id: file.id, status: file.fileStatus ?? null, url: file.image?.url ?? file.url ?? null };
+};
+/** How long to wait for a freshly-created file to finish processing (get a url). */
+const FILE_READY_TIMEOUT_MS = 60 * 1000;
+const FILE_POLL_MS = 1500;
+/**
+ * Re-read a just-created file until it has a live CDN url (fileCreate returns
+ * before processing finishes). Gives up after FILE_READY_TIMEOUT_MS and returns
+ * whatever it last saw, so the upload still succeeds — the caller just reports
+ * the url as not-ready-yet rather than blocking forever or failing.
+ */
+const waitForFileUrl = async (bin, store, id) => {
+    const deadline = Date.now() + FILE_READY_TIMEOUT_MS;
+    for (;;) {
+        // eslint-disable-next-line no-await-in-loop -- sequential poll of one file's status
+        const { node } = (await executeAsync(bin, store, 'FileStatus', { variables: { id } }));
+        const status = node?.fileStatus ?? null;
+        const url = node?.image?.url ?? node?.url ?? null;
+        if (url)
+            return { status, url };
+        if (status === 'FAILED' || Date.now() > deadline)
+            return { status, url: null };
+        // eslint-disable-next-line no-await-in-loop -- pacing the poll loop
+        await sleep(FILE_POLL_MS);
+    }
+};
+/** The `shopify://shop_images/<filename>` reference a theme image_picker setting stores. */
+const themeReference = (url) => {
+    if (!url)
+        return { filename: null, reference: null };
+    const name = fileName(url);
+    return name ? { filename: name, reference: `shopify://shop_images/${name}` } : { filename: null, reference: null };
+};
+/**
+ * Upload a local file into the store's asset library, in the three steps the
+ * Admin API requires (staged slot → POST bytes → register), then wait for it to
+ * finish processing so the returned url/reference are usable. The bytes are read
+ * from `path` on THIS machine (the caller); the GraphQL steps go through the
+ * user's Shopify CLI like every other operation here — no token ever passes
+ * through us. Throws with the CLI's or userErrors' reason on any failure.
+ *
+ * The result carries everything needed to then USE the file (e.g. reference it
+ * from a theme image_picker setting): the GID, CDN url, filename, and the
+ * `shopify://shop_images/…` reference. url/reference are null if processing
+ * hadn't finished within the wait window — the file still exists; poll later.
+ */
+export const uploadFile = async (bin, store, opts) => {
+    const bytes = readFileSync(opts.path);
+    const filename = opts.filename?.trim() || basename(opts.path);
+    const mimeType = mimeFromName(filename);
+    const resource = resourceForMime(mimeType);
+    const target = startStagedUpload(bin, store, { filename, mimeType, resource });
+    await postToStagedTarget(target, bytes, filename, mimeType);
+    const created = createFile(bin, store, { alt: opts.alt, resource, resourceUrl: target.resourceUrl });
+    // fileCreate hands back the url only if processing already finished; otherwise
+    // poll until it does, so the AI gets a usable url/reference in one call.
+    const ready = created.url ? { status: created.status, url: created.url } : await waitForFileUrl(bin, store, created.id);
+    return {
+        alt: created.alt,
+        id: created.id,
+        status: ready.status ?? created.status,
+        url: ready.url,
+        ...themeReference(ready.url),
+    };
+};
+/**
+ * Swap a file's bytes in place: fileUpdate with a new `originalSource` keeps the
+ * same file GID (so a theme `shopify://shop_images/<filename>` reference stays
+ * valid) while replacing the contents. Parsed like createFile.
+ */
+const replaceFileSource = (bin, store, input) => {
+    const updated = execute(bin, store, 'FileReplace', {
+        mutate: true,
+        variables: { files: [{ alt: input.alt, id: input.id, originalSource: input.resourceUrl }] },
+    });
+    const errors = updated.fileUpdate?.userErrors ?? [];
+    if (errors.length > 0)
+        throw new Error(`Shopify fileUpdate error: ${errors.map((error) => error.message).join('; ')}`);
+    const file = updated.fileUpdate?.files?.[0];
+    if (!file)
+        throw new Error('Shopify fileUpdate returned no file.');
+    return { alt: file.alt ?? null, id: file.id, status: file.fileStatus ?? null, url: file.image?.url ?? file.url ?? null };
+};
+/**
+ * Replace an existing file's contents with a new local file, in place — the same
+ * three-step staging as uploadFile, but the final step is fileUpdate on an
+ * existing `id` instead of fileCreate, so the file keeps its GID and (typically)
+ * its filename/theme reference. The new bytes are read from `path` on THIS
+ * machine; every GraphQL step goes through the user's Shopify CLI. Returns the
+ * updated file's id/url/reference/status, polling until processing finishes.
+ */
+export const replaceFile = async (bin, store, opts) => {
+    const bytes = readFileSync(opts.path);
+    const filename = basename(opts.path);
+    const mimeType = mimeFromName(filename);
+    const resource = resourceForMime(mimeType);
+    const target = startStagedUpload(bin, store, { filename, mimeType, resource });
+    await postToStagedTarget(target, bytes, filename, mimeType);
+    const updated = replaceFileSource(bin, store, { alt: opts.alt, id: opts.id, resourceUrl: target.resourceUrl });
+    // fileUpdate can return before the swapped-in image finishes processing; poll
+    // the same file id until its url is live, mirroring the upload path.
+    const ready = updated.url ? { status: updated.status, url: updated.url } : await waitForFileUrl(bin, store, opts.id);
+    return {
+        alt: updated.alt,
+        id: updated.id,
+        status: ready.status ?? updated.status,
+        url: ready.url,
+        ...themeReference(ready.url),
+    };
+};
+/**
+ * Delete a file from the store's asset library by GID, returning the id Shopify
+ * reports as actually removed. Throws on any userErrors the mutation reports.
+ */
+export const deleteFile = (bin, store, id) => {
+    const data = execute(bin, store, 'FileDelete', { mutate: true, variables: { fileIds: [id] } });
+    const errors = data.fileDelete?.userErrors ?? [];
+    if (errors.length > 0)
+        throw new Error(`Shopify fileDelete error: ${errors.map((error) => error.message).join('; ')}`);
+    const deleted = data.fileDelete?.deletedFileIds?.[0];
+    if (!deleted)
+        throw new Error(`Shopify fileDelete removed nothing for ${id}; the file may not exist.`);
+    return deleted;
+};
+/** A human label for a file, taken from the CDN URL's last path segment. */
+const fileName = (url) => {
+    try {
+        const name = new URL(url).pathname.split('/').pop();
+        return name ? decodeURIComponent(name.split('?')[0]) : url;
+    }
+    catch {
+        return url;
+    }
+};