@firenet-designs/fnd-cli 2.6.0 → 2.7.0

package/dist/lib/mcp/registry.js

@@ -0,0 +1,98 @@
+import { shopifyExecuteTool } from './tools/shopify-execute.js';
+import { shopifyFileDeleteTool } from './tools/shopify-file-delete.js';
+import { shopifyFileReplaceTool } from './tools/shopify-file-replace.js';
+import { shopifyFileSearchTool } from './tools/shopify-file-search.js';
+import { shopifyFileUploadTool } from './tools/shopify-file-upload.js';
+/**
+ * The `--with-tool` registry.
+ *
+ * `fnd workspace --with-tool <name>[<arg>]` exposes tools to Claude on the remote
+ * through the loopback MCP server (see server.ts). Each entry here is a
+ * WorkspaceTool built with defineTool (see define-tool.ts): it knows how to parse
+ * its bracketed argument, check its prerequisites BEFORE we connect (the same
+ * shape as the --devtools browser-port check), and build the MCP tool spec(s) the
+ * server actually serves. Adding a tool to the AI is: write one defineTool module
+ * and register it in TOOL_REGISTRY. Nothing else changes.
+ */
+/** Every tool `--with-tool` can name, keyed by tool name. */
+export const TOOL_REGISTRY = {
+    [shopifyExecuteTool.name]: shopifyExecuteTool,
+    [shopifyFileDeleteTool.name]: shopifyFileDeleteTool,
+    [shopifyFileReplaceTool.name]: shopifyFileReplaceTool,
+    [shopifyFileSearchTool.name]: shopifyFileSearchTool,
+    [shopifyFileUploadTool.name]: shopifyFileUploadTool,
+};
+/** `name` or `name[arg]` -> its pieces. The arg may itself contain brackets. */
+const parseSpec = (raw) => {
+    const match = raw.trim().match(/^([a-z0-9][a-z0-9-]*)(?:\[(.*)])?$/i);
+    if (!match) {
+        throw new Error(`--with-tool value "${raw}" is not valid; use <name> or <name>[<arg>], e.g. shopify-file-upload.`);
+    }
+    return { arg: match[2], name: match[1].toLowerCase() };
+};
+/** One-line usage listing the registered tools and their argument shape. */
+export const withToolUsage = () => Object.values(TOOL_REGISTRY)
+    .map((t) => {
+    if (!t.argHint)
+        return t.name; // takes no bracketed [arg]
+    return t.argRequired ? `${t.name}[<${t.argHint}>]` : `${t.name}[[<${t.argHint}>]]`;
+})
+    .join(', ');
+/**
+ * Resolve each `--with-tool` value into a {tool, config} selection, validating
+ * the tool name and its argument up front. `context` carries command-level flags
+ * a tool's parse may depend on (e.g. `--site-id` for the Shopify tools). Throws
+ * on an unknown tool, a stray/missing argument, a parse failure (a required flag
+ * absent), or the same tool selected twice (its MCP tool names would collide on
+ * the server).
+ */
+export const resolveWorkspaceTools = (specs, context) => {
+    const selections = [];
+    const seen = new Set();
+    for (const raw of specs) {
+        const { arg, name } = parseSpec(raw);
+        const tool = TOOL_REGISTRY[name];
+        if (!tool) {
+            const known = Object.keys(TOOL_REGISTRY).join(', ');
+            throw new Error(`--with-tool has no "${name}" tool. Available: ${known}.`);
+        }
+        if (seen.has(name))
+            throw new Error(`--with-tool "${name}" was given more than once.`);
+        seen.add(name);
+        if (!tool.argHint && arg !== undefined) {
+            throw new Error(`--with-tool ${name} takes no argument; drop the [${arg}].`);
+        }
+        if (tool.argHint && tool.argRequired && (arg === undefined || arg.trim() === '')) {
+            throw new Error(`--with-tool ${name} needs an argument: ${name}[<${tool.argHint}>].`);
+        }
+        // parse validates command-level dependencies (e.g. the Shopify tools need
+        // --site-id); prefix its message with the tool name so the user knows which.
+        let config;
+        try {
+            config = tool.parse(arg, context);
+        }
+        catch (error) {
+            throw new Error(`--with-tool ${name} ${error.message}`);
+        }
+        selections.push({ config, raw, tool });
+    }
+    return selections;
+};
+/**
+ * The MCP tool specs for a set of selections. Rejects two tools that would
+ * advertise the same MCP tool name — the server dispatches by name, so a
+ * collision would make one unreachable.
+ */
+export const collectToolSpecs = (selections, runtime) => {
+    const specs = [];
+    const names = new Set();
+    for (const { config, tool } of selections) {
+        for (const spec of tool.build(config, runtime)) {
+            if (names.has(spec.name))
+                throw new Error(`Two --with-tool tools both define an MCP tool named "${spec.name}".`);
+            names.add(spec.name);
+            specs.push(spec);
+        }
+    }
+    return specs;
+};

package/dist/lib/mcp/server.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The workspace tools MCP server.
+ *
+ * Topology: this machine (the one that ran `fnd workspace`) runs a tiny MCP
+ * server — Streamable HTTP transport, implemented on node:http with no
+ * dependencies — bound to 127.0.0.1:<local>. The workspace's `ssh -R` reverse
+ * tunnel exposes it on the REMOTE at 127.0.0.1:<remote>, where the `claude` CLI
+ * registers it as an HTTP MCP server. When the AI on the remote calls a tool,
+ * the tool's handler runs HERE, on the calling machine.
+ *
+ * The server binds loopback only; the sole way in from outside is the reverse
+ * tunnel, which lives exactly as long as the ssh session. What tools it serves
+ * is entirely up to the caller — see registry.ts / defineTool. The server itself
+ * knows nothing about any particular tool; it just dispatches tools/call to the
+ * matching spec's handler.
+ *
+ * STATELESS Streamable HTTP (MCP 2026-07-28): the server keeps no session. It
+ * never issues an `Mcp-Session-Id`, so it never requires one back, and every POST
+ * is handled independently — each request carries its own protocol version and
+ * capabilities in `_meta`, so a client may call any method (e.g. `tools/call`)
+ * directly. Discovery is the stateless `server/discover` request (there is no
+ * `initialize` handshake in the current spec, though we still answer the legacy
+ * one for older clients). Each POST gets a single `application/json` JSON-RPC
+ * reply; we open no server→client SSE stream, so GET (and any non-POST) gets 405.
+ * This suits a short-lived, single-client, loopback tunnel where session
+ * bookkeeping would only add fragility across a reconnect.
+ */
+/** The result a tool handler hands back: a text payload and whether it's an error. */
+export interface McpToolResult {
+    isError?: boolean;
+    text: string;
+}
+/**
+ * One tool the server advertises and can run. `inputSchema` is a JSON Schema
+ * object shown to the model; `handler` receives the parsed `arguments` and
+ * returns the text block the model sees. A thrown handler is turned into an
+ * isError result, so a handler may either return `{isError:true}` or throw.
+ */
+export interface McpToolSpec {
+    description: string;
+    handler: (args: Record<string, unknown>) => McpToolResult | Promise<McpToolResult>;
+    inputSchema: object;
+    name: string;
+    /**
+     * When true, advertise the tool with `_meta["anthropic/requiresUserInteraction"]`
+     * so the remote `claude` prompts for confirmation on EVERY call — even under
+     * broad auto-accept or bypass permissions (Claude Code ≥ 2.1.199; older clients
+     * ignore the hint and the tool just runs, so it degrades to today's behaviour).
+     * Used for destructive tools opted in with the `[ask]` selection arg.
+     */
+    requiresUserInteraction?: boolean;
+}
+/** Handle for a running MCP server. */
+export interface McpServer {
+    close: () => Promise<void>;
+    /** The 127.0.0.1 port the server bound to (OS-assigned when not requested). */
+    port: number;
+}
+/**
+ * Start the MCP server on 127.0.0.1, serving `tools`. With no `port` the OS
+ * assigns a free one, returned on the handle so the caller can point the reverse
+ * tunnel at it. Resolves once the port is bound; rejects if binding fails.
+ */
+export declare const startMcpServer: (tools: McpToolSpec[], opts?: {
+    port?: number;
+}) => Promise<McpServer>;

package/dist/lib/mcp/server.js

@@ -0,0 +1,176 @@
+import { createServer } from 'node:http';
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+const SERVER_INFO = { name: 'fnd-tools', version: '1.0.0' };
+/**
+ * The MCP revisions this server accepts. Current-spec clients (2026-07-28+) speak
+ * the stateless `server/discover` model; the older revisions are here so a client
+ * still using the legacy `initialize` handshake also connects. `LATEST` is what
+ * discovery advertises as newest; `LEGACY` is the newest an `initialize`-era
+ * client understands, so we never answer that handshake with a discovery-only
+ * version it can't parse.
+ */
+const SUPPORTED_PROTOCOL_VERSIONS = ['2024-11-05', '2025-03-26', '2025-06-18', '2026-07-28'];
+const LEGACY_PROTOCOL_VERSION = '2025-06-18';
+/** How long a client may cache discovery / the tool list (freshness hints, ms). */
+const DISCOVER_TTL_MS = 60 * 60 * 1000;
+const TOOLS_LIST_TTL_MS = 5 * 60 * 1000;
+const rpcError = (id, code, message) => ({
+    error: { code, message },
+    id,
+    jsonrpc: '2.0',
+});
+const rpcResult = (id, result) => ({ id, jsonrpc: '2.0', result });
+/** The tools/list entry for a spec — the handler is server-side only. */
+const advertise = (spec) => ({
+    description: spec.description,
+    inputSchema: spec.inputSchema,
+    // Force a per-call confirmation prompt on the client for a tool opted into it.
+    // The key is the one Claude Code reads (`anthropic/requiresUserInteraction`);
+    // other MCP clients that don't know it simply ignore the _meta.
+    ...(spec.requiresUserInteraction ? { _meta: { 'anthropic/requiresUserInteraction': true } } : {}),
+    name: spec.name,
+});
+/** Turn a tool handler's result into the JSON-RPC result body for `tools/call`. */
+const callResult = (content, isError) => ({ content, isError, resultType: 'complete' });
+/**
+ * Handle one JSON-RPC message. Returns the response object for requests, or
+ * undefined for notifications (which get no response body).
+ *
+ * This follows the stateless data-layer model (MCP 2026-07-28): there is no
+ * session and no `initialize` round-trip — a client discovers the server with
+ * `server/discover` (optional; every request already carries its own protocol
+ * version and capabilities in `_meta`) and may call any method directly. The
+ * legacy `initialize`/`ping` methods are still answered so an older client
+ * connects too; unknown `_meta` on any request is simply ignored.
+ */
+const handleRpcMessage = async (msg, tools) => {
+    const isRequest = msg.id !== undefined && msg.id !== null;
+    if (msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+        return isRequest ? rpcError(msg.id, -32_600, 'Invalid request') : undefined;
+    }
+    if (!isRequest)
+        return undefined; // notifications (e.g. notifications/initialized) need no reply
+    const id = msg.id;
+    switch (msg.method) {
+        case 'initialize': {
+            // Legacy handshake (pre-2026-07-28). Echo the requested revision when we
+            // support it, else offer the newest an initialize-era client understands.
+            const requested = msg.params?.protocolVersion;
+            const protocolVersion = typeof requested === 'string' && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+                ? requested
+                : LEGACY_PROTOCOL_VERSION;
+            return rpcResult(id, { capabilities: { tools: {} }, protocolVersion, serverInfo: SERVER_INFO });
+        }
+        case 'ping': {
+            return rpcResult(id, {});
+        }
+        case 'server/discover': {
+            // The current stateless discovery request: advertise identity, capabilities
+            // and supported versions in one cacheable reply. `tools: {}` (no
+            // listChanged) because our tool set is fixed for the session — the client
+            // never needs to open a subscriptions/listen stream for tool changes.
+            return rpcResult(id, {
+                _meta: { 'io.modelcontextprotocol/serverInfo': SERVER_INFO },
+                cacheScope: 'public',
+                capabilities: { tools: {} },
+                resultType: 'complete',
+                supportedVersions: SUPPORTED_PROTOCOL_VERSIONS,
+                ttlMs: DISCOVER_TTL_MS,
+            });
+        }
+        case 'tools/call': {
+            const params = msg.params ?? {};
+            const tool = tools.find((t) => t.name === params.name);
+            if (!tool)
+                return rpcError(id, -32_602, `Unknown tool: ${String(params.name)}`);
+            const args = (params.arguments ?? {});
+            try {
+                const result = await tool.handler(args);
+                return rpcResult(id, callResult([{ text: result.text, type: 'text' }], result.isError ?? false));
+            }
+            catch (error) {
+                // A thrown handler is a tool-level error, not a protocol one: report it
+                // in-band so the model sees the reason instead of a dead connection.
+                return rpcResult(id, callResult([{ text: `Tool "${tool.name}" failed: ${error.message}`, type: 'text' }], true));
+            }
+        }
+        case 'tools/list': {
+            return rpcResult(id, {
+                cacheScope: 'public',
+                resultType: 'complete',
+                tools: tools.map((t) => advertise(t)),
+                ttlMs: TOOLS_LIST_TTL_MS,
+            });
+        }
+        default: {
+            return rpcError(id, -32_601, `Method not found: ${msg.method}`);
+        }
+    }
+};
+/** Read a request body, rejecting when it exceeds the size cap. */
+const readBody = (req) => new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+            reject(new Error('request body too large'));
+            req.destroy();
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.once('end', () => resolve(Buffer.concat(chunks).toString()));
+    req.once('error', reject);
+});
+const handleHttpRequest = async (req, res, tools) => {
+    // Streamable HTTP: clients POST JSON-RPC messages. We don't offer a
+    // server-initiated SSE stream, so GET (and anything else) gets 405.
+    if (req.method !== 'POST') {
+        res.writeHead(405, { allow: 'POST' }).end();
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readBody(req));
+    }
+    catch {
+        res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify(rpcError(null, -32_700, 'Parse error')));
+        return;
+    }
+    const messages = (Array.isArray(parsed) ? parsed : [parsed]);
+    const responses = (await Promise.all(messages.map((m) => handleRpcMessage(m, tools)))).filter((r) => r !== undefined);
+    // A body of nothing but notifications gets 202 Accepted with no content.
+    if (responses.length === 0) {
+        res.writeHead(202).end();
+        return;
+    }
+    const payload = Array.isArray(parsed) ? responses : responses[0];
+    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(payload));
+};
+/**
+ * Start the MCP server on 127.0.0.1, serving `tools`. With no `port` the OS
+ * assigns a free one, returned on the handle so the caller can point the reverse
+ * tunnel at it. Resolves once the port is bound; rejects if binding fails.
+ */
+export const startMcpServer = (tools, opts = {}) => new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+        handleHttpRequest(req, res, tools).catch(() => {
+            if (!res.headersSent)
+                res.writeHead(500);
+            res.end();
+        });
+    });
+    server.once('error', reject);
+    server.listen(opts.port ?? 0, '127.0.0.1', () => {
+        const address = server.address();
+        const port = typeof address === 'object' && address ? address.port : (opts.port ?? 0);
+        resolve({
+            close: () => new Promise((done) => {
+                server.closeAllConnections();
+                server.close(() => done());
+            }),
+            port,
+        });
+    });
+});

package/dist/lib/mcp/tools/shopify-common.d.ts

@@ -0,0 +1,139 @@
+import type { ParseContext } from '#lib/mcp/define-tool.js';
+/**
+ * Shared plumbing for the Shopify `--with-tool` tools (upload / replace / delete /
+ * search / execute).
+ *
+ * They all act on one store's data through the user's own Shopify CLI
+ * (`shopify store execute` / `shopify store auth`), which owns the OAuth session —
+ * we never hold a token. The store is NOT a bracketed argument: it comes from the
+ * workspace command's `--site-id` flag, so every Shopify tool in a run targets
+ * the same store and the remote AI cannot pick another (a deliberate safety
+ * boundary). The operations run on THIS machine (the caller), reading files from
+ * the local side of the sync.
+ *
+ * Scopes are reconciled ONCE across all the selected tools (reconcileShopifyScopes):
+ * the store is granted the union of what the tools need. The file tools
+ * (upload/replace/delete/search) are bounded by hardcoded gates — the delete tool
+ * can only ever call `fileDelete`, never touch a customer — so an over-granted
+ * store is harmless to them and their extra scopes are never stripped. The
+ * `shopify-execute` tool is different: it runs arbitrary Admin GraphQL, so its
+ * blast radius IS the granted scope set. When it's in the run we trim the store to
+ * exactly the union (revoking anything extra), confining the AI to least privilege.
+ */
+/** The config a Shopify tool's selection produces; shared by all of them. */
+export interface ShopifyToolConfig {
+    /**
+     * The `[ask]` selection opts the tool into a per-call confirmation prompt on
+     * the remote (via the MCP server's `requiresUserInteraction` hint), so a
+     * destructive tool always asks even under auto-accept.
+     */
+    ask: boolean;
+    /** Resolved shopify CLI path, filled in by preflight/reconcile once we know it exists. */
+    bin?: string;
+    /**
+     * shopify-execute[scopes=all]: grant a broad Admin scope set and never revoke —
+     * the AI gets wide access on purpose. Ignored (false) for the bounded file tools.
+     */
+    grantAll: boolean;
+    /**
+     * Whether this tool's presence should trim the store to EXACTLY the union of
+     * tool scopes, revoking anything extra. Only `shopify-execute` sets this (its
+     * reach is the scope set); the file tools leave it false, so selecting one never
+     * strips a store's other grants.
+     */
+    restrictScopes: boolean;
+    /** The Admin scopes this tool needs; unioned across all selected Shopify tools when reconciling. */
+    scopes: readonly string[];
+    /** The normalized `*.myshopify.com` domain, from `--site-id`. */
+    store: string;
+}
+/** The `--site-id` store, normalized; throws (the registry prefixes the tool name) when it's absent. */
+export declare const requireStore: (context: ParseContext) => string;
+/**
+ * Build a `parse` for a fixed-scope Shopify tool (the file tools): the store
+ * comes from `--site-id`, the only bracketed option is the optional `[ask]` gate,
+ * and the tool's scopes are constant (write_files / read_files). shopify-execute
+ * has its own parse — its scopes come from the `scopes=` option — so it doesn't
+ * use this.
+ */
+export declare const makeShopifyParse: (scopes: readonly string[]) => (arg: string | undefined, context: ParseContext) => ShopifyToolConfig;
+/** `parse` for the file-writing tools (upload/replace/delete): fixed `write_files`. */
+export declare const shopifyWriteFileParse: (arg: string | undefined, context: ParseContext) => ShopifyToolConfig;
+/** `parse` for the read-only search tool: fixed `read_files`. */
+export declare const shopifyReadFileParse: (arg: string | undefined, context: ParseContext) => ShopifyToolConfig;
+/**
+ * A Shopify tool's preflight: just resolve the CLI, so `build` has a path and a
+ * missing CLI aborts before we connect (with a friendly message, like the
+ * --devtools port check). Authentication and scope granting are NOT done here —
+ * they happen once across all the tools in reconcileShopifyScopes, so the store
+ * is authed with the union rather than re-prompting per tool.
+ */
+export declare const shopifyPreflight: (config: ShopifyToolConfig) => void;
+/** The CLI path build() needs, asserting preflight/reconcile already resolved it. */
+export declare const requireBin: (config: ShopifyToolConfig) => string;
+/**
+ * A broad Admin scope set for `shopify-execute[scopes=all]`. It is deliberately
+ * curated (the common read/write resources) rather than literally every scope
+ * Shopify defines — that list is version-specific and unbounded — so "all" means
+ * "wide access to the usual resources". Extend it if a run needs a resource
+ * that's missing; a caller who needs an exact set can always list it explicitly.
+ */
+export declare const ALL_ADMIN_SCOPES: readonly ["read_products", "write_products", "read_orders", "write_orders", "read_draft_orders", "write_draft_orders", "read_customers", "write_customers", "read_files", "write_files", "read_content", "write_content", "read_themes", "write_themes", "read_inventory", "write_inventory", "read_fulfillments", "write_fulfillments", "read_shipping", "write_shipping", "read_discounts", "write_discounts", "read_price_rules", "write_price_rules", "read_marketing_events", "write_marketing_events", "read_translations", "write_translations", "read_metaobjects", "write_metaobjects", "read_metaobject_definitions", "write_metaobject_definitions", "read_publications", "write_publications", "read_locations"];
+/** What one store's reconciliation should do, computed purely from its current grant. */
+export interface ScopePlan {
+    /** Granted scopes to strip (always empty unless restricting) — reported, never silent. */
+    extra: string[];
+    /** Needed scopes not yet granted. */
+    missing: string[];
+    /** Whether a `shopify store auth` call is required (unauthenticated, or a grant/revoke to apply). */
+    reauth: boolean;
+    /** Whether extras are being revoked (restrict mode) — drives the log wording. */
+    restrict: boolean;
+    /** The exact scope set the installation should end up granting. */
+    target: string[];
+}
+/** How the selected Shopify tools want their store scoped, folded across all of them. */
+export interface ScopeNeed {
+    /** `scopes=all`: grant the broad curated set and never revoke. */
+    grantAll: boolean;
+    /** Trim to exactly the union (revoke extras) — set by shopify-execute with an explicit list. */
+    restrict: boolean;
+    /** Union of every selected Shopify tool's scopes. */
+    toolScopes: readonly string[];
+}
+/**
+ * Decide, purely, what a store's scopes should become — the heart of the
+ * reconciliation, split out so it's testable without the Shopify CLI.
+ *
+ * The target the installation should end up granting is the union of the tools'
+ * scopes (plus ALL_ADMIN_SCOPES under `grantAll`). In `restrict` mode the grant
+ * becomes EXACTLY that union, so anything extra is revoked (a `read_x` already
+ * covered by a needed `write_x` isn't counted as extra — dropping it would churn
+ * the auth for nothing). Otherwise we only ever ADD, so the store's other grants
+ * are left untouched. A re-auth is needed when unauthenticated, or when there's
+ * anything to grant or revoke.
+ */
+export declare const planShopifyScopes: (granted: string[], authenticated: boolean, need: ScopeNeed) => ScopePlan;
+/**
+ * Reconcile the store's granted scopes with what the selected Shopify tools
+ * actually need — once, before connecting — so any interactive `shopify store
+ * auth` happens while the user is watching.
+ *
+ * Grant the union the tools need; REVOKE anything extra ONLY when `shopify-execute`
+ * is in the run with an explicit scope list — its reach is the granted scope set,
+ * so we trim it to least privilege. The file tools never trigger revocation:
+ * they're bounded by hardcoded gates (the delete tool can only delete a file), so
+ * an over-scoped store can't be abused through them, and stripping scopes they
+ * don't use would just churn the auth of the user's other Shopify work.
+ *
+ * `shopify store auth --scopes <set>` re-runs OAuth, so the installation ends up
+ * granting exactly <set>: that both adds the missing scopes and drops any not in
+ * <set>. That re-auth is how we revoke — there is no separate revoke command.
+ * (The decision is in planShopifyScopes; this just runs the CLI around it.)
+ *
+ * `selections` is the command's tool list (structurally `{ config }`); non-Shopify
+ * and non-selected tools are ignored, so a run with no Shopify tool is a no-op.
+ */
+export declare const reconcileShopifyScopes: (selections: readonly {
+    config: unknown;
+}[], log: (message: string) => void) => void;

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

@@ -0,0 +1,167 @@
+import { parseBracketArgs } from '#lib/mcp/bracket-args.js';
+import { findShopifyBin } from '#lib/scaffold.js';
+import { authenticate, FILE_READ_SCOPES, FILE_WRITE_SCOPES, getInstalledScopes, missingScopes, normalizeStore } from '#lib/shopify/shopify.js';
+/** The `--site-id` store, normalized; throws (the registry prefixes the tool name) when it's absent. */
+export const requireStore = (context) => {
+    const siteId = context.siteId?.trim();
+    if (!siteId) {
+        throw new Error('requires --site-id (the Shopify store, e.g. mystore or mystore.myshopify.com).');
+    }
+    return normalizeStore(siteId);
+};
+/**
+ * Build a `parse` for a fixed-scope Shopify tool (the file tools): the store
+ * comes from `--site-id`, the only bracketed option is the optional `[ask]` gate,
+ * and the tool's scopes are constant (write_files / read_files). shopify-execute
+ * has its own parse — its scopes come from the `scopes=` option — so it doesn't
+ * use this.
+ */
+export const makeShopifyParse = (scopes) => (arg, context) => {
+    const store = requireStore(context);
+    const parsed = parseBracketArgs(arg, { flags: ['ask'] });
+    return { ask: parsed.flags.has('ask'), grantAll: false, restrictScopes: false, scopes, store };
+};
+/** `parse` for the file-writing tools (upload/replace/delete): fixed `write_files`. */
+export const shopifyWriteFileParse = makeShopifyParse(FILE_WRITE_SCOPES);
+/** `parse` for the read-only search tool: fixed `read_files`. */
+export const shopifyReadFileParse = makeShopifyParse(FILE_READ_SCOPES);
+/**
+ * A Shopify tool's preflight: just resolve the CLI, so `build` has a path and a
+ * missing CLI aborts before we connect (with a friendly message, like the
+ * --devtools port check). Authentication and scope granting are NOT done here —
+ * they happen once across all the tools in reconcileShopifyScopes, so the store
+ * is authed with the union rather than re-prompting per tool.
+ */
+export const shopifyPreflight = (config) => {
+    const bin = findShopifyBin();
+    if (!bin) {
+        throw new Error('Shopify CLI not found on PATH (or any nvm node). Install it (npm i -g @shopify/cli) before using this tool.');
+    }
+    config.bin = bin;
+};
+/** The CLI path build() needs, asserting preflight/reconcile already resolved it. */
+export const requireBin = (config) => {
+    const bin = config.bin ?? findShopifyBin();
+    if (!bin)
+        throw new Error('Shopify CLI not found; cannot build the Shopify tool.');
+    return bin;
+};
+/**
+ * A broad Admin scope set for `shopify-execute[scopes=all]`. It is deliberately
+ * curated (the common read/write resources) rather than literally every scope
+ * Shopify defines — that list is version-specific and unbounded — so "all" means
+ * "wide access to the usual resources". Extend it if a run needs a resource
+ * that's missing; a caller who needs an exact set can always list it explicitly.
+ */
+export const ALL_ADMIN_SCOPES = [
+    'read_products', 'write_products',
+    'read_orders', 'write_orders',
+    'read_draft_orders', 'write_draft_orders',
+    'read_customers', 'write_customers',
+    'read_files', 'write_files',
+    'read_content', 'write_content',
+    'read_themes', 'write_themes',
+    'read_inventory', 'write_inventory',
+    'read_fulfillments', 'write_fulfillments',
+    'read_shipping', 'write_shipping',
+    'read_discounts', 'write_discounts',
+    'read_price_rules', 'write_price_rules',
+    'read_marketing_events', 'write_marketing_events',
+    'read_translations', 'write_translations',
+    'read_metaobjects', 'write_metaobjects',
+    'read_metaobject_definitions', 'write_metaobject_definitions',
+    'read_publications', 'write_publications',
+    'read_locations',
+];
+const unique = (scopes) => [...new Set(scopes)];
+/** A ShopifyToolConfig among the (type-erased) selection configs. */
+const isShopifyConfig = (config) => typeof config === 'object' &&
+    config !== null &&
+    typeof config.store === 'string' &&
+    Array.isArray(config.scopes);
+/**
+ * Whether a currently-granted scope is already covered by `needed`, so keeping it
+ * isn't "extra". `write_x` covers `read_x` (see missingScopes), so a granted
+ * `read_x` is redundant — not worth a re-auth to drop — when `write_x` is needed.
+ */
+const coveredByNeeded = (scope, needed) => needed.includes(scope) || (scope.startsWith('read_') && needed.includes(scope.replace('read_', 'write_')));
+/**
+ * Decide, purely, what a store's scopes should become — the heart of the
+ * reconciliation, split out so it's testable without the Shopify CLI.
+ *
+ * The target the installation should end up granting is the union of the tools'
+ * scopes (plus ALL_ADMIN_SCOPES under `grantAll`). In `restrict` mode the grant
+ * becomes EXACTLY that union, so anything extra is revoked (a `read_x` already
+ * covered by a needed `write_x` isn't counted as extra — dropping it would churn
+ * the auth for nothing). Otherwise we only ever ADD, so the store's other grants
+ * are left untouched. A re-auth is needed when unauthenticated, or when there's
+ * anything to grant or revoke.
+ */
+export const planShopifyScopes = (granted, authenticated, need) => {
+    const needed = need.grantAll ? unique([...need.toolScopes, ...ALL_ADMIN_SCOPES]) : unique([...need.toolScopes]);
+    const target = need.restrict ? needed : unique([...granted, ...needed]);
+    const missing = missingScopes(granted, needed);
+    const extra = need.restrict ? granted.filter((scope) => !coveredByNeeded(scope, needed)) : [];
+    const reauth = !authenticated || missing.length > 0 || extra.length > 0;
+    return { extra, missing, reauth, restrict: need.restrict, target };
+};
+/**
+ * Reconcile the store's granted scopes with what the selected Shopify tools
+ * actually need — once, before connecting — so any interactive `shopify store
+ * auth` happens while the user is watching.
+ *
+ * Grant the union the tools need; REVOKE anything extra ONLY when `shopify-execute`
+ * is in the run with an explicit scope list — its reach is the granted scope set,
+ * so we trim it to least privilege. The file tools never trigger revocation:
+ * they're bounded by hardcoded gates (the delete tool can only delete a file), so
+ * an over-scoped store can't be abused through them, and stripping scopes they
+ * don't use would just churn the auth of the user's other Shopify work.
+ *
+ * `shopify store auth --scopes <set>` re-runs OAuth, so the installation ends up
+ * granting exactly <set>: that both adds the missing scopes and drops any not in
+ * <set>. That re-auth is how we revoke — there is no separate revoke command.
+ * (The decision is in planShopifyScopes; this just runs the CLI around it.)
+ *
+ * `selections` is the command's tool list (structurally `{ config }`); non-Shopify
+ * and non-selected tools are ignored, so a run with no Shopify tool is a no-op.
+ */
+export const reconcileShopifyScopes = (selections, log) => {
+    const configs = selections.map((s) => s.config).filter((config) => isShopifyConfig(config));
+    if (configs.length === 0)
+        return;
+    const bin = findShopifyBin();
+    if (!bin) {
+        throw new Error('Shopify CLI not found on PATH (or any nvm node). Install it (npm i -g @shopify/cli) before using the Shopify tools.');
+    }
+    for (const config of configs)
+        config.bin = bin;
+    // One run targets one store (--site-id is shared), but group defensively in
+    // case that ever changes — each store reconciles independently.
+    for (const store of unique(configs.map((c) => c.store))) {
+        const forStore = configs.filter((c) => c.store === store);
+        const grantAll = forStore.some((c) => c.grantAll);
+        const need = {
+            grantAll,
+            // Revoke extras only when shopify-execute is confining itself to an explicit
+            // set; `scopes=all` deliberately opts out of trimming.
+            restrict: forStore.some((c) => c.restrictScopes) && !grantAll,
+            toolScopes: unique(forStore.flatMap((c) => [...c.scopes])),
+        };
+        log(`Reconciling Shopify access for ${store}…`);
+        const { authenticated, scopes: granted } = getInstalledScopes(bin, store);
+        const plan = planShopifyScopes(granted, authenticated, need);
+        if (!plan.reauth) {
+            log(`  ${store}: scopes already ${plan.restrict ? 'exactly ' : ''}as needed (${plan.target.join(', ') || 'none'})`);
+            continue;
+        }
+        if (!authenticated)
+            log(`  ${store}: not authenticated — opening the browser via shopify store auth`);
+        if (plan.missing.length > 0)
+            log(`  ${store}: granting ${plan.missing.join(', ')}`);
+        if (plan.extra.length > 0)
+            log(`  ${store}: revoking ${plan.extra.join(', ')} (not needed by the selected tools)`);
+        if (!authenticate(bin, store, plan.target)) {
+            throw new Error(`Could not authenticate ${store} with scopes ${plan.target.join(', ')}. Try it directly: shopify store auth --store ${store} --scopes ${plan.target.join(',')}`);
+        }
+    }
+};

package/dist/lib/mcp/tools/shopify-execute.d.ts

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