@firenet-designs/fnd-cli 2.6.0 → 2.7.0

package/dist/lib/shopify/graphql/ProductsBulkQuery.graphql

@@ -0,0 +1,27 @@
+# The body of the product→image bulk query — the selection run in bulk, passed
+# as the $query variable to StartBulkQuery (never via --query-file). Bulk allows
+# two levels of nested connections, which is exactly products -> media; the
+# MediaImage id on each media row is joined back to its product by __parentId in
+# the JSONL result. No `first`/`after` — bulk expands the connections itself.
+{
+  products {
+    edges {
+      node {
+        id
+        title
+        productType
+        vendor
+        tags
+        media {
+          edges {
+            node {
+              ... on MediaImage {
+                id
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lib/shopify/graphql/SearchFiles.graphql

@@ -0,0 +1,36 @@
+# Page through the file library returning metadata only (no bytes) so a search
+# can check for an existing file or find oversized images cheaply. `query` is a
+# Shopify file-search string (e.g. filename:"hero", media_type:IMAGE) or null for
+# everything. Pull the fields from whichever concrete type applies — MediaImage
+# for images (dimensions + originalSource.fileSize), GenericFile otherwise
+# (originalFileSize).
+query SearchFiles($query: String, $first: Int!, $after: String, $sortKey: FileSortKeys, $reverse: Boolean) {
+  files(first: $first, after: $after, query: $query, sortKey: $sortKey, reverse: $reverse) {
+    edges {
+      node {
+        id
+        alt
+        ... on MediaImage {
+          mimeType
+          image {
+            url
+            width
+            height
+          }
+          originalSource {
+            fileSize
+          }
+        }
+        ... on GenericFile {
+          mimeType
+          url
+          originalFileSize
+        }
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}

package/dist/lib/shopify/graphql/StagedUploadsCreate.graphql

@@ -0,0 +1,20 @@
+# Reserve a staging slot for a file the CLI is about to upload. Shopify hands
+# back a short-lived upload `url` (Google Cloud Storage) plus the form
+# `parameters` that authorize the POST, and the `resourceUrl` to hand to
+# fileCreate once the bytes have landed. Counts as a mutation to the CLI.
+mutation StagedUploadsCreate($input: [StagedUploadInput!]!) {
+  stagedUploadsCreate(input: $input) {
+    stagedTargets {
+      url
+      resourceUrl
+      parameters {
+        name
+        value
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}

package/dist/lib/shopify/graphql/StartBulkQuery.graphql

@@ -0,0 +1,16 @@
+# Kick off a bulk query export (the file library, or the product→image map). The
+# query to run in bulk is passed as the $query variable, so it needs no escaping
+# here. Counts as a mutation to the CLI (--allow-mutations) even though it only
+# reads. Only one bulk query can run per store at a time, so callers run these
+# one after another.
+mutation StartBulkQuery($query: String!) {
+  bulkOperationRunQuery(query: $query) {
+    bulkOperation {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}

package/dist/lib/shopify/graphql/UpdateFileAlt.graphql

@@ -0,0 +1,9 @@
+# Write one file's alt text.
+mutation UpdateFileAlt($id: ID!, $alt: String!) {
+  fileUpdate(files: [{ id: $id, alt: $alt }]) {
+    userErrors {
+      field
+      message
+    }
+  }
+}

package/dist/lib/shopify/shopify.d.ts

@@ -0,0 +1,228 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const REQUIRED_SCOPES: readonly ["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 declare const DRY_RUN_SCOPES: readonly ["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 declare const FILE_WRITE_SCOPES: readonly ["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 declare const FILE_READ_SCOPES: readonly ["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 declare const missingScopes: (granted: string[], required: readonly string[]) => string[];
+/**
+ * One image file from the store's asset library. `alt` is null until it's set.
+ *
+ * `mimeType`, `width`, `height` and `fileSize` are the metadata Shopify already
+ * knows, carried so a --dry run can filter on them without downloading the
+ * image. Any of them is null when the MediaImage is still processing (or the
+ * connection omitted it), which is the caller's signal to fall back to the
+ * download; a real run ignores them and measures the bytes it fetches anyway.
+ */
+export interface ShopifyImageFile {
+    alt: null | string;
+    fileSize: null | number;
+    height: null | number;
+    id: string;
+    mimeType: null | string;
+    name: string;
+    url: string;
+    width: null | number;
+}
+/** `mystore`, `mystore.myshopify.com`, or `https://mystore.myshopify.com/` -> `mystore.myshopify.com`. */
+export declare const normalizeStore: (raw: string) => string;
+/**
+ * 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 declare const runStoreExecute: (bin: string, store: string, opts: {
+    mutate?: boolean;
+    query: string;
+    variables?: Record<string, unknown>;
+}) => {
+    ok: boolean;
+    output: string;
+};
+/**
+ * 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 declare const getInstalledScopes: (bin: string, store: string) => {
+    authenticated: boolean;
+    scopes: string[];
+};
+/**
+ * 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 declare const authenticate: (bin: string, store: string, scopes: readonly string[]) => boolean;
+/**
+ * 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 declare function getImageFiles(bin: string, store: string): AsyncGenerator<ShopifyImageFile>;
+/**
+ * A `FileSortKeys` member — the server-side order a scan streams in, so the
+ * `limit` early-break yields the true top-N in that order (e.g. size-desc streams
+ * the biggest first, so "find large images" is authoritative, not just the first
+ * page re-sorted). Values per the Admin schema's FileSortKeys enum.
+ */
+export type FileSortKey = 'CREATED_AT' | 'FILENAME' | 'ORIGINAL_UPLOAD_SIZE' | 'UPDATED_AT';
+export declare function searchFiles(bin: string, store: string, opts: {
+    pageSize?: number;
+    query: null | string;
+    reverse?: boolean;
+    sortKey?: FileSortKey;
+}): AsyncGenerator<ShopifyImageFile>;
+/** How a store product describes itself — the context a file's pixels can't. */
+export interface ProductContext {
+    productType: string;
+    tags: string[];
+    title: string;
+    vendor: string;
+}
+/**
+ * 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 declare const getImageProductContext: (bin: string, store: string) => Promise<Map<string, ProductContext>>;
+/** A one-line context hint for the prompt, skipping whatever fields are empty. */
+export declare const formatProductContext: (context: ProductContext) => string;
+/** Set one file's alt text. Throws on any userErrors the mutation reports. */
+export declare const updateFileAlt: (bin: string, store: string, id: string, alt: string) => void;
+/**
+ * The outcome of an upload — everything an AI needs to then USE the file, e.g.
+ * wire it into a theme setting during theme development:
+ *   id        — the Admin API GID (gid://shopify/MediaImage/…).
+ *   url       — the public CDN url, once processing finishes (null if it hasn't).
+ *   reference — the `shopify://shop_images/<filename>` value a theme `image_picker`
+ *               setting stores; the form to drop into settings JSON / liquid.
+ *   filename  — the name the file actually landed under (Shopify may de-dupe it).
+ *   status    — the file's processing status (READY once the url is live).
+ */
+export interface UploadResult {
+    alt: null | string;
+    filename: null | string;
+    id: string;
+    reference: null | string;
+    status: null | string;
+    url: null | string;
+}
+/**
+ * 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 declare const uploadFile: (bin: string, store: string, opts: {
+    alt?: string;
+    filename?: string;
+    path: string;
+}) => Promise<UploadResult>;
+/**
+ * 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 declare const replaceFile: (bin: string, store: string, opts: {
+    alt?: string;
+    id: string;
+    path: string;
+}) => Promise<UploadResult>;
+/**
+ * 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 declare const deleteFile: (bin: string, store: string, id: string) => string;