@firenet-designs/fnd-cli 2.6.0 → 2.7.0

package/dist/lib/mcp/tools/shopify-execute.js

@@ -0,0 +1,105 @@
+import { parseBracketArgs } from '#lib/mcp/bracket-args.js';
+import { defineTool } from '#lib/mcp/define-tool.js';
+import { runStoreExecute } from '#lib/shopify/shopify.js';
+import { requireBin, requireStore, shopifyPreflight } from './shopify-common.js';
+/**
+ * `--with-tool shopify-execute` — expose a `shopify_execute` MCP tool that runs an
+ * ARBITRARY Admin GraphQL operation against the store via the user's Shopify CLI.
+ * Store comes from `--site-id` (fixed — the AI can't change it).
+ *
+ * This is far more powerful than the file tools: it's raw Admin GraphQL, so what
+ * the AI can touch is exactly the store's granted scopes. That's why its bracket
+ * REQUIRES a `scopes=` option — `scopes=all` for broad access, or an explicit
+ * list like `scopes=read_products+write_orders` — and why the command reconciles
+ * the store to EXACTLY that set (revoking anything extra) before connecting, so
+ * the AI is confined to least privilege (see reconcileShopifyScopes). `ask` is
+ * optional and gates every call behind a confirmation prompt on the remote.
+ *
+ *   shopify-execute[scopes=read_products+read_orders]
+ *   shopify-execute[ask,scopes=all]
+ */
+/** The MCP tool name the remote AI sees. (The registry name activates it; this is what it calls.) */
+const MCP_TOOL_NAME = 'shopify_execute';
+/** A trimmed non-empty string from an untyped arg, or undefined. */
+const str = (value) => typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+/** Split a `scopes=` value into individual scopes. `+` or whitespace separate them (comma is the option separator). */
+const parseScopeList = (raw) => [...new Set(raw.split(/[\s+]+/).map((scope) => scope.trim().toLowerCase()).filter(Boolean))];
+/** A Shopify access scope is `read_x` / `write_x`; reject anything else so a typo fails up front. */
+const SCOPE_SHAPE = /^(read|write)_[a-z_]+$/;
+/**
+ * Parse a `shopify-execute` selection. Unlike the file tools, its scopes aren't
+ * fixed — they come from the required `scopes=` option, which is what the reconcile
+ * step trims the store down to. `[ask]` stays optional.
+ */
+const parseExecuteSelection = (arg, context) => {
+    const store = requireStore(context);
+    const parsed = parseBracketArgs(arg, { flags: ['ask'], values: ['scopes'] });
+    const ask = parsed.flags.has('ask');
+    const scopesRaw = parsed.values.get('scopes');
+    if (!scopesRaw) {
+        throw new Error('requires a scopes option, since it runs arbitrary Admin GraphQL: shopify-execute[scopes=all] for broad access, ' +
+            'or an explicit list like shopify-execute[scopes=read_products+write_orders] (add ,ask to confirm every call).');
+    }
+    // `scopes=all` = grant a broad set and never revoke (see ALL_ADMIN_SCOPES).
+    if (scopesRaw.toLowerCase() === 'all') {
+        return { ask, grantAll: true, restrictScopes: true, scopes: [], store };
+    }
+    const scopes = parseScopeList(scopesRaw);
+    if (scopes.length === 0) {
+        throw new Error('the scopes option is empty; list one or more scopes, e.g. scopes=read_products+write_orders, or scopes=all.');
+    }
+    const bad = scopes.find((scope) => !SCOPE_SHAPE.test(scope));
+    if (bad) {
+        throw new Error(`"${bad}" is not a valid Admin scope (expected read_<resource> or write_<resource>, e.g. read_products).`);
+    }
+    return { ask, grantAll: false, restrictScopes: true, scopes, store };
+};
+export const shopifyExecuteTool = defineTool({
+    argHint: 'scopes=all|<list>[,ask]',
+    argRequired: true,
+    build(config) {
+        const { grantAll, scopes, store } = config;
+        // preflight/reconcile ran first and resolved the CLI; assert it for the handler.
+        const bin = requireBin(config);
+        const scopeDesc = grantAll ? 'a broad set of Admin scopes' : (scopes.join(', ') || 'none');
+        const spec = {
+            description: `Run an arbitrary Admin GraphQL operation against the Shopify store ${store} via \`shopify store execute\` ` +
+                `(the user's Shopify CLI, so it uses their existing login — no token passes through here). Provide \`query\` ` +
+                `(a GraphQL document with ONE operation) and optional \`variables\`. Reads run by default; a MUTATION must set ` +
+                `\`mutate: true\` (the CLI refuses mutations otherwise). This installation is limited to these scopes: ` +
+                `${scopeDesc} — an operation needing anything else fails with an access-denied error, so stay within them. ` +
+                `The store is fixed to ${store} and cannot be changed here. Returns the raw JSON response, including any ` +
+                `GraphQL \`errors\`.`,
+            handler(args) {
+                const query = str(args.query);
+                if (!query)
+                    return { isError: true, text: 'The "query" argument must be a non-empty GraphQL document string.' };
+                const mutate = args.mutate === true;
+                const variables = args.variables && typeof args.variables === 'object' && !Array.isArray(args.variables)
+                    ? args.variables
+                    : undefined;
+                const result = runStoreExecute(bin, store, { mutate, query, variables });
+                return { isError: !result.ok, text: result.output };
+            },
+            inputSchema: {
+                properties: {
+                    mutate: {
+                        description: 'Set true to allow a mutation; `store execute` refuses mutations unless this is set. Leave false/omitted for read queries.',
+                        type: 'boolean',
+                    },
+                    query: { description: 'The Admin GraphQL document to run (a single operation).', type: 'string' },
+                    variables: { description: 'Optional variables object for the operation.', type: 'object' },
+                },
+                required: ['query'],
+                type: 'object',
+            },
+            name: MCP_TOOL_NAME,
+            // `[ask]` makes the remote prompt for confirmation before every execute.
+            requiresUserInteraction: config.ask,
+        };
+        return [spec];
+    },
+    name: 'shopify-execute',
+    parse: parseExecuteSelection,
+    preflight: shopifyPreflight,
+});

package/dist/lib/mcp/tools/shopify-file-delete.d.ts

@@ -0,0 +1,2 @@
+import { ShopifyToolConfig } from './shopify-common.js';
+export declare const shopifyFileDeleteTool: import("#lib/mcp/define-tool.js").WorkspaceTool<ShopifyToolConfig>;

package/dist/lib/mcp/tools/shopify-file-delete.js

@@ -0,0 +1,49 @@
+import { defineTool } from '#lib/mcp/define-tool.js';
+import { deleteFile } from '#lib/shopify/shopify.js';
+import { requireBin, shopifyPreflight, shopifyWriteFileParse } from './shopify-common.js';
+/**
+ * `--with-tool shopify-file-delete` — let Claude on the remote delete a file from
+ * the store's asset library, named ONLY by its exact `id` (GID). Store comes from
+ * `--site-id`. Deletion is permanent, so the tool takes no file bytes and does no
+ * filename lookup — a fuzzy name must never resolve to (and delete) the wrong file.
+ */
+/** The MCP tool name the remote AI sees. */
+const MCP_TOOL_NAME = 'delete_shopify_file';
+export const shopifyFileDeleteTool = defineTool({
+    argHint: 'ask',
+    argRequired: false,
+    build(config) {
+        const { store } = config;
+        const bin = requireBin(config);
+        const spec = {
+            description: `Permanently delete a file from the Shopify store ${store}'s asset library (Content > Files). \`id\` is the ` +
+                `file's exact gid://shopify/… GID — no filename lookup, so an ambiguous name can never delete the wrong file. ` +
+                `This cannot be undone. Runs through the user's Shopify CLI; the store is fixed to ${store} and cannot be changed here.`,
+            async handler(args) {
+                const id = typeof args.id === 'string' ? args.id.trim() : '';
+                if (id === '') {
+                    return { isError: true, text: 'The "id" argument must be the exact gid://shopify/… GID of the file to delete.' };
+                }
+                const deleted = deleteFile(bin, store, id);
+                return { text: `Deleted ${deleted} from ${store}.` };
+            },
+            inputSchema: {
+                properties: {
+                    id: {
+                        description: 'Exact GID (gid://shopify/…) of the file to delete.',
+                        type: 'string',
+                    },
+                },
+                required: ['id'],
+                type: 'object',
+            },
+            name: MCP_TOOL_NAME,
+            // `[ask]` makes the remote prompt for confirmation before every delete.
+            requiresUserInteraction: config.ask,
+        };
+        return [spec];
+    },
+    name: 'shopify-file-delete',
+    parse: shopifyWriteFileParse,
+    preflight: shopifyPreflight,
+});

package/dist/lib/mcp/tools/shopify-file-replace.d.ts

@@ -0,0 +1,2 @@
+import { ShopifyToolConfig } from './shopify-common.js';
+export declare const shopifyFileReplaceTool: import("#lib/mcp/define-tool.js").WorkspaceTool<ShopifyToolConfig>;

package/dist/lib/mcp/tools/shopify-file-replace.js

@@ -0,0 +1,79 @@
+import { defineTool } from '#lib/mcp/define-tool.js';
+import { replaceFile } from '#lib/shopify/shopify.js';
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { requireBin, shopifyPreflight, shopifyWriteFileParse } from './shopify-common.js';
+/**
+ * `--with-tool shopify-file-replace` — let Claude on the remote replace an
+ * existing file's contents in place with a file from the synced workspace. The
+ * target file keeps its GID (and typically its filename/theme reference), so any
+ * `shopify://shop_images/<filename>` a theme already stores stays valid. Store
+ * comes from `--site-id`; the target is named ONLY by its exact `id` (GID) — no
+ * filename lookup, so a fuzzy name can never resolve to the wrong file.
+ */
+/** The MCP tool name the remote AI sees. */
+const MCP_TOOL_NAME = 'replace_shopify_file';
+export const shopifyFileReplaceTool = defineTool({
+    argHint: 'ask',
+    argRequired: false,
+    build(config, runtime) {
+        const { store } = config;
+        const bin = requireBin(config);
+        const spec = {
+            description: `Replace an existing file's contents IN PLACE in the Shopify store ${store}'s asset library. \`id\` is the ` +
+                `existing file's exact gid://shopify/… GID (no filename lookup — an ambiguous name must never resolve to the ` +
+                `wrong file); \`path\` is the new file on the machine that launched \`fnd workspace\` — relative to the synced ` +
+                `workspace dir (${runtime.localCwd}) or absolute. The file keeps its GID (and usually its filename), so a theme ` +
+                `shopify://shop_images/<filename> reference stays valid. Returns the file's GID, CDN url, filename, and theme ` +
+                `reference. Runs through the user's Shopify CLI; the store is fixed to ${store} and cannot be changed here.`,
+            async handler(args) {
+                const rawPath = args.path;
+                if (typeof rawPath !== 'string' || rawPath.trim() === '') {
+                    return { isError: true, text: 'The "path" argument must be a non-empty string.' };
+                }
+                const abs = isAbsolute(rawPath) ? rawPath : resolve(runtime.localCwd, rawPath);
+                if (!existsSync(abs)) {
+                    return { isError: true, text: `No file at ${abs} on the local machine.` };
+                }
+                const id = typeof args.id === 'string' ? args.id.trim() : '';
+                if (id === '') {
+                    return { isError: true, text: 'The "id" argument must be the exact gid://shopify/… GID of the file to replace.' };
+                }
+                const alt = typeof args.alt === 'string' ? args.alt : undefined;
+                const result = await replaceFile(bin, store, { alt, id, path: abs });
+                return {
+                    text: [
+                        `Replaced ${id} in ${store} with ${abs}.`,
+                        `id: ${result.id}`,
+                        `filename: ${result.filename ?? '(processing — not available yet)'}`,
+                        `url: ${result.url ?? '(processing — not ready yet; poll the file later)'}`,
+                        `theme reference: ${result.reference ?? '(available once processing finishes)'}`,
+                        `status: ${result.status ?? 'unknown'}`,
+                    ].join('\n'),
+                };
+            },
+            inputSchema: {
+                properties: {
+                    alt: { description: 'Optional new alt text to set on the file.', type: 'string' },
+                    id: {
+                        description: 'Exact GID (gid://shopify/…) of the existing file to replace.',
+                        type: 'string',
+                    },
+                    path: {
+                        description: `Path to the replacement file on the local machine — relative to ${runtime.localCwd} or absolute.`,
+                        type: 'string',
+                    },
+                },
+                required: ['id', 'path'],
+                type: 'object',
+            },
+            name: MCP_TOOL_NAME,
+            // `[ask]` makes the remote prompt for confirmation before every replace.
+            requiresUserInteraction: config.ask,
+        };
+        return [spec];
+    },
+    name: 'shopify-file-replace',
+    parse: shopifyWriteFileParse,
+    preflight: shopifyPreflight,
+});

package/dist/lib/mcp/tools/shopify-file-search.d.ts

@@ -0,0 +1,2 @@
+import { ShopifyToolConfig } from './shopify-common.js';
+export declare const shopifyFileSearchTool: import("#lib/mcp/define-tool.js").WorkspaceTool<ShopifyToolConfig>;

package/dist/lib/mcp/tools/shopify-file-search.js

@@ -0,0 +1,199 @@
+import { defineTool } from '#lib/mcp/define-tool.js';
+import { searchFiles } from '#lib/shopify/shopify.js';
+import { requireBin, shopifyPreflight, shopifyReadFileParse } from './shopify-common.js';
+/**
+ * `--with-tool shopify-file-search` — let Claude on the remote look up files in
+ * the store's asset library by **metadata only** (name / mime type / size / url),
+ * never downloading the bytes. Two jobs it's built for:
+ *   • check whether a file already exists before uploading — search by a similar
+ *     name, size and type instead of ingesting every image (which burns tokens);
+ *   • find oversized images to resize — search by a minimum size.
+ * Read-only, so it needs just `read_files`. Store comes from `--site-id`.
+ */
+/** The MCP tool name the remote AI sees. */
+const MCP_TOOL_NAME = 'search_shopify_files';
+/** Default / max number of matches returned, and how many files a scan will examine. */
+const DEFAULT_LIMIT = 25;
+const MAX_LIMIT = 100;
+const SCAN_CAP = 5000;
+const PAGE_SIZE = 250;
+/**
+ * The `sort` input → the Shopify `FileSortKeys` member it maps to. Ordering is
+ * server-side, so the scan streams in this order and the `limit` early-break
+ * returns the true top-N (e.g. biggest images first, not just the first page
+ * re-sorted).
+ */
+const SORT_KEYS = {
+    created: 'CREATED_AT',
+    name: 'FILENAME',
+    size: 'ORIGINAL_UPLOAD_SIZE',
+    updated: 'UPDATED_AT',
+};
+const DEFAULT_SORT = 'size';
+/** Default direction per sort when `order` is omitted: newest/largest first, but names A→Z. */
+const DEFAULT_DESC = { created: true, name: false, size: true, updated: true };
+/** A compact, human-readable byte size (metadata, so precision beyond ~0.1 unit is noise). */
+const humanBytes = (bytes) => {
+    if (bytes === null)
+        return 'size?';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unit]}`;
+};
+/** The Shopify file-search `query` string built from the name filter (null = whole library). */
+const buildQuery = (name) => {
+    const trimmed = name?.trim();
+    if (!trimmed)
+        return null;
+    // `filename:` is a contains match; wrap in quotes so spaces don't split the
+    // term, and drop any embedded quotes so the search string can't be broken.
+    return `filename:"${trimmed.replaceAll('"', '')}"`;
+};
+/** A trimmed non-empty string from an untyped arg, or undefined. */
+const str = (v) => (typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined);
+/** A finite number from an untyped arg, or undefined. */
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+/** Whether a file matches the client-side filters (size/mime/url) the search grammar can't express. */
+const matches = (file, f) => {
+    if (f.type && !(file.mimeType ?? '').toLowerCase().includes(f.type.toLowerCase()))
+        return false;
+    if (f.url && !file.url.toLowerCase().includes(f.url.toLowerCase()))
+        return false;
+    // A size bound on a file whose size Shopify hasn't reported can't be verified —
+    // exclude it rather than guess, so "larger than X" never returns an unknown.
+    if (f.minSize !== undefined || f.maxSize !== undefined) {
+        if (file.fileSize === null)
+            return false;
+        if (f.minSize !== undefined && file.fileSize < f.minSize)
+            return false;
+        if (f.maxSize !== undefined && file.fileSize > f.maxSize)
+            return false;
+    }
+    return true;
+};
+/** Validate the sort/order args into a searchFiles ordering, or return an error message. */
+const resolveOrdering = (args) => {
+    const sort = (str(args.sort) ?? DEFAULT_SORT).toLowerCase();
+    if (!(sort in SORT_KEYS))
+        return { error: `Unknown sort "${sort}"; use one of: ${Object.keys(SORT_KEYS).join(', ')}.` };
+    const orderArg = str(args.order)?.toLowerCase();
+    if (orderArg && orderArg !== 'asc' && orderArg !== 'desc')
+        return { error: `Unknown order "${orderArg}"; use "asc" or "desc".` };
+    // reverse flips the sort key's natural ascending order; default per sort.
+    const reverse = orderArg ? orderArg === 'desc' : DEFAULT_DESC[sort];
+    return { label: `${sort} ${reverse ? 'desc' : 'asc'}`, reverse, sortKey: SORT_KEYS[sort] };
+};
+/** One result line — everything useful about a file, no bytes. */
+const formatFile = (file) => {
+    const dims = file.width && file.height ? `${file.width}×${file.height}` : 'n/a';
+    const parts = [
+        file.name,
+        file.mimeType ?? 'type?',
+        humanBytes(file.fileSize),
+        dims,
+        `id=${file.id}`,
+    ];
+    if (file.alt)
+        parts.push(`alt=${JSON.stringify(file.alt)}`);
+    parts.push(`url=${file.url}`);
+    return `- ${parts.join(' | ')}`;
+};
+export const shopifyFileSearchTool = defineTool({
+    argHint: 'ask',
+    argRequired: false,
+    build(config) {
+        const { store } = config;
+        const bin = requireBin(config);
+        const spec = {
+            description: `Search the Shopify store ${store}'s asset library (Content > Files) by METADATA ONLY — filename, mime type, ` +
+                `size, and/or url — and get back each match's name, type, size, dimensions, GID, alt, and url. It never ` +
+                `downloads image bytes, so use it INSTEAD of ingesting images: e.g. before an upload, search by a similar ` +
+                `\`name\`/\`type\`/size to see if the file already exists; or find images to resize with \`minSize\`. ` +
+                `All filters are optional and AND together. \`minSize\`/\`maxSize\` are in BYTES. Order with \`sort\` ` +
+                `(size|name|created|updated, default size) and \`order\` (asc|desc; default desc for size/created/updated, asc ` +
+                `for name) — ordering is server-side, so \`sort:size order:desc\` returns the genuinely LARGEST files. Returns ` +
+                `up to \`limit\` matches (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}); a broad scan examines up to ${SCAN_CAP} ` +
+                `files — narrow with \`name\` for an exact-ish lookup. The store is fixed to ${store}.`,
+            async handler(args) {
+                const filters = { maxSize: num(args.maxSize), minSize: num(args.minSize), type: str(args.type), url: str(args.url) };
+                const rawLimit = num(args.limit) ?? DEFAULT_LIMIT;
+                const limit = Math.max(1, Math.min(MAX_LIMIT, Math.floor(rawLimit)));
+                const query = buildQuery(str(args.name));
+                const ordering = resolveOrdering(args);
+                if ('error' in ordering)
+                    return { isError: true, text: ordering.error };
+                const found = [];
+                let scanned = 0;
+                let hitScanCap = false;
+                try {
+                    // Server-side order: the scan streams sorted, so breaking at `limit`
+                    // yields the true top-N in that order (not just the first page re-sorted).
+                    for await (const file of searchFiles(bin, store, { pageSize: PAGE_SIZE, query, reverse: ordering.reverse, sortKey: ordering.sortKey })) {
+                        scanned += 1;
+                        if (matches(file, filters))
+                            found.push(file);
+                        if (found.length >= limit)
+                            break;
+                        if (scanned >= SCAN_CAP) {
+                            hitScanCap = true;
+                            break;
+                        }
+                    }
+                }
+                catch (error) {
+                    return { isError: true, text: `Search failed: ${error.message}` };
+                }
+                if (found.length === 0) {
+                    return { text: `No files in ${store} matched (scanned ${scanned}${hitScanCap ? `, hit the ${SCAN_CAP}-file scan cap` : ''}).` };
+                }
+                const notes = [];
+                if (found.length >= limit)
+                    notes.push(`stopped at the ${limit}-result limit — raise \`limit\` or narrow filters for more`);
+                if (hitScanCap)
+                    notes.push(`stopped after examining ${SCAN_CAP} files — add a \`name\` filter to search a subset`);
+                return {
+                    text: [
+                        `${found.length} match${found.length === 1 ? '' : 'es'} in ${store}, ordered by ${ordering.label} (examined ${scanned} file${scanned === 1 ? '' : 's'}):`,
+                        ...found.map((f) => formatFile(f)),
+                        ...(notes.length > 0 ? ['', ...notes.map((n) => `note: ${n}`)] : []),
+                    ].join('\n'),
+                };
+            },
+            inputSchema: {
+                properties: {
+                    limit: { description: `Max matches to return (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}).`, type: 'number' },
+                    maxSize: { description: 'Only files at most this many BYTES.', type: 'number' },
+                    minSize: { description: 'Only files at least this many BYTES (use to find oversized images).', type: 'number' },
+                    name: {
+                        description: 'Filename contains this text (server-side search; narrows the scan — give it for an existence check).',
+                        type: 'string',
+                    },
+                    order: { description: 'Sort direction: "asc" or "desc". Default: desc for size/created/updated, asc for name.', enum: ['asc', 'desc'], type: 'string' },
+                    sort: {
+                        description: 'Order results by "size" (default), "name", "created", or "updated". Server-side, so size+desc gives the truly largest.',
+                        enum: ['size', 'name', 'created', 'updated'],
+                        type: 'string',
+                    },
+                    type: { description: 'Mime type contains this text, e.g. "png", "image/jpeg", "svg".', type: 'string' },
+                    url: { description: 'CDN url contains this text.', type: 'string' },
+                },
+                required: [],
+                type: 'object',
+            },
+            name: MCP_TOOL_NAME,
+            // `[ask]` makes the remote prompt for confirmation before every search.
+            requiresUserInteraction: config.ask,
+        };
+        return [spec];
+    },
+    name: 'shopify-file-search',
+    parse: shopifyReadFileParse,
+    preflight: shopifyPreflight,
+});

package/dist/lib/mcp/tools/shopify-file-upload.d.ts

@@ -0,0 +1,2 @@
+import { ShopifyToolConfig } from './shopify-common.js';
+export declare const shopifyFileUploadTool: import("#lib/mcp/define-tool.js").WorkspaceTool<ShopifyToolConfig>;

package/dist/lib/mcp/tools/shopify-file-upload.js

@@ -0,0 +1,76 @@
+import { defineTool } from '#lib/mcp/define-tool.js';
+import { uploadFile } from '#lib/shopify/shopify.js';
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { requireBin, shopifyPreflight, shopifyWriteFileParse } from './shopify-common.js';
+/**
+ * `--with-tool shopify-file-upload` — let Claude on the remote upload a file from
+ * the synced workspace into the store's asset library. The store comes from
+ * `--site-id` (see shopify-common.ts), not a per-tool argument. Its sibling tools
+ * are shopify-file-replace and shopify-file-delete; each activates one MCP tool.
+ */
+/** The MCP tool name the remote AI sees. (The registry name activates it; this is what it calls.) */
+const MCP_TOOL_NAME = 'upload_shopify_file';
+export const shopifyFileUploadTool = defineTool({
+    argHint: 'ask',
+    argRequired: false,
+    build(config, runtime) {
+        const { store } = config;
+        // preflight ran first and resolved the CLI; assert it for the handler.
+        const bin = requireBin(config);
+        const spec = {
+            description: `Upload a file from the LOCAL machine into the Shopify store ${store}'s asset library (Content > Files). ` +
+                `\`path\` is a file on the machine that launched \`fnd workspace\` — relative to the synced workspace dir ` +
+                `(${runtime.localCwd}) or absolute. Returns the created file's GID, CDN url, filename, and the ` +
+                `shopify://shop_images/<filename> reference to drop into a theme image_picker setting or liquid. The upload ` +
+                `runs through the user's Shopify CLI on that machine, so it uses their existing store login. The store is ` +
+                `fixed to ${store} by the workspace command and cannot be changed here.`,
+            async handler(args) {
+                const rawPath = args.path;
+                if (typeof rawPath !== 'string' || rawPath.trim() === '') {
+                    return { isError: true, text: 'The "path" argument must be a non-empty string.' };
+                }
+                const abs = isAbsolute(rawPath) ? rawPath : resolve(runtime.localCwd, rawPath);
+                if (!existsSync(abs)) {
+                    return { isError: true, text: `No file at ${abs} on the local machine.` };
+                }
+                const alt = typeof args.alt === 'string' ? args.alt : undefined;
+                const filename = typeof args.filename === 'string' ? args.filename : undefined;
+                const result = await uploadFile(bin, store, { alt, filename, path: abs });
+                return {
+                    text: [
+                        `Uploaded ${abs} to ${store}.`,
+                        `id: ${result.id}`,
+                        `filename: ${result.filename ?? '(processing — not available yet)'}`,
+                        `url: ${result.url ?? '(processing — not ready yet; poll the file later)'}`,
+                        // The image_picker/theme-settings reference — what to store in settings JSON or liquid.
+                        `theme reference: ${result.reference ?? '(available once processing finishes)'}`,
+                        `status: ${result.status ?? 'unknown'}`,
+                    ].join('\n'),
+                };
+            },
+            inputSchema: {
+                properties: {
+                    alt: { description: 'Optional alt text to attach to the file.', type: 'string' },
+                    filename: {
+                        description: 'Optional name to store the file under; defaults to the basename of path.',
+                        type: 'string',
+                    },
+                    path: {
+                        description: `Path to the file on the local machine — relative to ${runtime.localCwd} or absolute.`,
+                        type: 'string',
+                    },
+                },
+                required: ['path'],
+                type: 'object',
+            },
+            name: MCP_TOOL_NAME,
+            // `[ask]` makes the remote prompt for confirmation before every upload.
+            requiresUserInteraction: config.ask,
+        };
+        return [spec];
+    },
+    name: 'shopify-file-upload',
+    parse: shopifyWriteFileParse,
+    preflight: shopifyPreflight,
+});

package/dist/lib/shopify/graphql/AccessScopes.graphql

@@ -0,0 +1,7 @@
+query AccessScopes {
+  currentAppInstallation {
+    accessScopes {
+      handle
+    }
+  }
+}

package/dist/lib/shopify/graphql/CurrentBulkOperation.graphql

@@ -0,0 +1,8 @@
+# Poll the status of the running product-export bulk query.
+query CurrentBulkOperation {
+  currentBulkOperation(type: QUERY) {
+    status
+    errorCode
+    url
+  }
+}

package/dist/lib/shopify/graphql/FileCreate.graphql

@@ -0,0 +1,25 @@
+# Register an already-staged upload as a file in the store's asset library. The
+# `originalSource` is the resourceUrl stagedUploadsCreate returned. The response
+# type is a union, so pull the CDN url from whichever concrete type applies —
+# MediaImage for images, GenericFile for everything else.
+mutation FileCreate($files: [FileCreateInput!]!) {
+  fileCreate(files: $files) {
+    files {
+      id
+      alt
+      fileStatus
+      ... on MediaImage {
+        image {
+          url
+        }
+      }
+      ... on GenericFile {
+        url
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}

package/dist/lib/shopify/graphql/FileDelete.graphql

@@ -0,0 +1,11 @@
+# Delete files from the store's asset library by id, returning the ids actually
+# removed. Counts as a mutation to the CLI (needs --allow-mutations).
+mutation FileDelete($fileIds: [ID!]!) {
+  fileDelete(fileIds: $fileIds) {
+    deletedFileIds
+    userErrors {
+      field
+      message
+    }
+  }
+}

package/dist/lib/shopify/graphql/FileReplace.graphql

@@ -0,0 +1,26 @@
+# Replace an existing file's contents in place: fileUpdate with a fresh
+# `originalSource` (a just-staged upload) swaps the bytes while keeping the same
+# file id/GID, so a theme `shopify://shop_images/<filename>` reference stays
+# valid. The response type is a union — pull the CDN url from whichever concrete
+# type applies (MediaImage for images, GenericFile for everything else).
+mutation FileReplace($files: [FileUpdateInput!]!) {
+  fileUpdate(files: $files) {
+    files {
+      id
+      alt
+      fileStatus
+      ... on MediaImage {
+        image {
+          url
+        }
+      }
+      ... on GenericFile {
+        url
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}

package/dist/lib/shopify/graphql/FileStatus.graphql

@@ -0,0 +1,19 @@
+# Re-read a just-created file by id to see whether it has finished processing.
+# fileCreate returns before the CDN url exists, so this is polled until `image.url`
+# (MediaImage) or `url` (GenericFile) is populated and fileStatus is READY.
+query FileStatus($id: ID!) {
+  node(id: $id) {
+    ... on MediaImage {
+      alt
+      fileStatus
+      image {
+        url
+      }
+    }
+    ... on GenericFile {
+      alt
+      fileStatus
+      url
+    }
+  }
+}

package/dist/lib/shopify/graphql/FilesBulkQuery.graphql

@@ -0,0 +1,27 @@
+# The body of the file-library bulk query — the selection run in bulk, passed as
+# the $query variable to StartBulkQuery (never via --query-file). Bulk queries
+# take no variables, so there is no pagination (`first`/`after`) and no
+# $skipMeta @skip: the metadata rides along unconditionally. A --dry run filters
+# straight from it without downloading; a real run ignores it and measures the
+# bytes it fetches anyway, so the few extra scalars per file are harmless.
+{
+  files(query: "media_type:IMAGE") {
+    edges {
+      node {
+        id
+        alt
+        ... on MediaImage {
+          mimeType
+          image {
+            url
+            width
+            height
+          }
+          originalSource {
+            fileSize
+          }
+        }
+      }
+    }
+  }
+}