@firenet-designs/fnd-cli 2.4.0 → 2.7.0

package/dist/lib/alt-text.js

@@ -0,0 +1,196 @@
+/**
+ * Alt-text generation: fetch an image, make it something a vision model can
+ * read, and ask a locally-hosted Ollama model to describe it.
+ *
+ * Everything runs against the user's own Ollama host, so no image ever leaves
+ * their network and there is no per-image API cost — which is also why the
+ * caller drives this strictly sequentially: a single local model gains nothing
+ * from concurrent requests.
+ */
+import { Ollama } from 'ollama';
+export const DEFAULT_OLLAMA_HOST = 'http://localhost:11434';
+/** How long Ollama keeps the model resident between images, in seconds. */
+const KEEP_ALIVE = 60;
+const PROMPT = "Make alt text for this image. The alt text should be no more than 1 sentence. Don't be overly descriptive. Include any text in the image in your description. Verbs should be in present tense.";
+/**
+ * The part of an image URL worth showing the model: the file name, without the
+ * directory, query string, or extension. A name like `sample-normal-wax` says
+ * what the pixels can't — that yellow cube is a wax melt — while the rest of a
+ * CDN URL (shard digits, `?v=…`) is noise the model shouldn't have to wade
+ * through. Returns '' when there's nothing usable to pass along.
+ */
+const urlHint = (url) => {
+    try {
+        const last = new URL(url).pathname.split('/').pop() ?? '';
+        return decodeURIComponent(last).replace(/\.[a-z0-9]+$/i, '').trim();
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * The prompt for one image: the base instructions, the file name, and whatever
+ * usage context the caller passed. All of it is framed as a hint on purpose —
+ * file names are often stale, generic (`IMG_1234`), or plain wrong, and a
+ * product an image is filed under isn't guaranteed to be what the image shows —
+ * so the model is told to lean on the hints only where they agree with the
+ * pixels, and never to copy them into the alt text verbatim.
+ */
+const buildPrompt = (url, context) => {
+    const hints = [];
+    const hint = urlHint(url);
+    if (hint)
+        hints.push(`Its file name is "${hint}".`);
+    if (context)
+        hints.push(`${context}.`);
+    if (hints.length === 0)
+        return PROMPT;
+    return `${PROMPT} Extra context about this image: ${hints.join(' ')} Use this context only where it agrees with what you see, and never copy the file name, URL, or these details verbatim into the alt text.`;
+};
+/**
+ * Everything the model sees is PNG.
+ *
+ * Which formats a vision model can actually decode is not documented and varies
+ * by model — WebP in particular gets accepted and then described as if it were
+ * noise. Re-encoding every image removes the question: the model only ever
+ * receives the one format they all handle. The cost is a decode + encode per
+ * image, which is nothing next to the inference that follows.
+ *
+ * Both converters are native modules with real startup cost, so they're
+ * imported lazily — the first image of a run pays for sharp, and a run with no
+ * SVGs never loads resvg at all.
+ */
+const svgToPng = async (bytes) => {
+    const { Resvg } = await import('@resvg/resvg-js');
+    // Rendered on black: SVG icons are overwhelmingly dark-on-transparent, which
+    // flattens to invisible on the white the model would otherwise see.
+    const rendered = new Resvg(Buffer.from(bytes), { background: '#000000' }).render();
+    // An SVG has no intrinsic pixel size, so `width`/`height` in a filter mean the
+    // size resvg chose to rasterize at — the viewBox, in practice.
+    return { height: rendered.height, png: new Uint8Array(rendered.asPng()), width: rendered.width };
+};
+/** Raster → PNG. Covers WebP, JPEG, AVIF, GIF, TIFF and PNG itself. */
+const rasterToPng = async (bytes) => {
+    const { default: sharp } = await import('sharp');
+    // Alpha is left alone here, unlike the SVG path: a transparent raster image
+    // could be light or dark, so there's no background that's safe to guess.
+    // resolveWithObject gets the dimensions out of the same decode as the encode.
+    const { data, info } = await sharp(Buffer.from(bytes)).png().toBuffer({ resolveWithObject: true });
+    return { height: info.height, png: new Uint8Array(data), width: info.width };
+};
+/**
+ * The `type` a filter expression sees: a bare format token, not a MIME type.
+ *
+ * Content-Type is trusted first and the extension is the fallback, since CDNs
+ * serve plenty of images from extensionless URLs. `jpg` is normalized to `jpeg`
+ * and `svg+xml` to `svg` so an expression doesn't have to spell both.
+ *
+ * Exported so a caller that already knows an image's MIME type (e.g. Shopify's
+ * GraphQL `mimeType`) can produce the same `type` token a downloaded image would
+ * get, without re-fetching the bytes.
+ */
+export const detectType = (contentType, path) => {
+    const fromHeader = contentType.split(';')[0].trim().toLowerCase();
+    const subtype = fromHeader.startsWith('image/') ? fromHeader.slice('image/'.length) : '';
+    const raw = subtype || (path.includes('.') ? path.split('.').pop() : '');
+    const token = raw.replace('+xml', '');
+    return token === 'jpg' ? 'jpeg' : token;
+};
+/**
+ * Download an image, normalize it to bytes the model accepts, and measure it.
+ *
+ * The measuring has to happen here rather than before the download: width and
+ * height aren't knowable without the image itself, and Content-Length is absent
+ * often enough that fileSize is taken from the bytes we actually received. So a
+ * filter saves inference time — the expensive part — not bandwidth.
+ */
+const fetchImage = async (url) => {
+    const resp = await fetch(url);
+    if (!resp.ok)
+        throw new Error(`Could not download image (${resp.status} ${resp.statusText})`);
+    const bytes = new Uint8Array(await resp.arrayBuffer());
+    const contentType = resp.headers.get('content-type') ?? '';
+    const path = new URL(url).pathname.toLowerCase();
+    const type = detectType(contentType, path);
+    // SVG is vector, so it goes through the rasterizer rather than sharp's decoder.
+    const { height, png, width } = type === 'svg' || contentType.includes('svg') || path.endsWith('.svg')
+        ? await svgToPng(bytes)
+        : await rasterToPng(bytes);
+    return { meta: { fileSize: bytes.byteLength, height, type, url, width }, png };
+};
+/**
+ * Every model pulled on the host that can actually read an image.
+ *
+ * /api/tags (`list`) is the only endpoint that enumerates models, but it says
+ * nothing about what a model can do — the capability list lives on /api/show
+ * (`show`), so each tag is asked individually. The calls are local and run
+ * concurrently; a model whose show() fails (pulled but broken, or removed
+ * between the two calls) is simply left out rather than failing the run.
+ */
+export const listVisionModels = async (host) => {
+    const ollama = new Ollama({ host });
+    const { models } = await ollama.list();
+    const checked = await Promise.all(models.map(async ({ model }) => {
+        try {
+            const { capabilities } = await ollama.show({ model });
+            return capabilities?.includes('vision') ? model : undefined;
+        }
+        catch {
+        }
+    }));
+    return checked.filter((model) => model !== undefined).sort();
+};
+/**
+ * Bind a describer to one Ollama host and model. The client is created once and
+ * reused so the connection (and the loaded model, via keep_alive) survives
+ * across images.
+ *
+ * `filter`, when given, decides whether an image is worth describing — it runs
+ * after the download (see fetchImage) but before inference, and a rejected
+ * image comes back as `{skipped: true}` rather than throwing, because being
+ * filtered out is a normal outcome and not a failure.
+ *
+ * `dry` short-circuits right after the download: the image is fetched and
+ * measured (so the caller can filter on real metadata for images whose size or
+ * dimensions weren't known up front) but nothing is sent to the model, and the
+ * filter is NOT applied here — a dry run's filtering is the command's job, so it
+ * can decide uniformly whether the meta came from this download or from an API
+ * that already knew it. The returned Description carries real `meta`/`bytes` and
+ * an empty `alt` the caller never reads.
+ */
+export const createDescriber = (host, model, filter, dry = false) => {
+    const ollama = new Ollama({ host });
+    return async (url, context, onDownloaded) => {
+        const started = performance.now();
+        const { meta, png } = await fetchImage(url);
+        if (dry) {
+            return { alt: '', bytes: png.byteLength, meta, ms: performance.now() - started, skipped: false, tokens: 0 };
+        }
+        if (filter && !filter(meta))
+            return { meta, skipped: true };
+        // Downloaded and kept: from here the model runs, which is the slow part.
+        onDownloaded?.();
+        const images = [Buffer.from(png).toString("base64")];
+        const resp = await ollama.chat({
+            // eslint-disable-next-line camelcase
+            keep_alive: KEEP_ALIVE,
+            messages: [{ content: buildPrompt(url, context), images, role: 'user' }],
+            model,
+            stream: false,
+            // think: true,
+        });
+        const content = resp.message.content.trim();
+        if (!content)
+            throw new Error(`${model} returned an empty description`);
+        return {
+            alt: content,
+            bytes: png.byteLength,
+            meta,
+            ms: performance.now() - started,
+            skipped: false,
+            // Prompt tokens dominate here — an image is worth hundreds of them, the
+            // sentence that comes back is worth a few dozen — so both halves count.
+            tokens: (resp.prompt_eval_count ?? 0) + (resp.eval_count ?? 0),
+        };
+    };
+};

package/dist/lib/image-filter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The `--filter` expression for `fnd alt-text`.
+ *
+ * The expression is evaluated with `eval`, deliberately: it comes from the flag
+ * the person is typing into their own shell, so it is already code they are
+ * running on their own machine — there is no privilege boundary to cross and no
+ * mini-language worth inventing when JavaScript's operators are exactly what a
+ * filter needs. It is NOT safe to feed this a string from anywhere else (a
+ * config file pulled off the network, a CI variable someone else controls).
+ *
+ * What the expression can see is the image's metadata plus `sizes`; nothing is
+ * passed in from the surrounding scope, because the eval'd text is a standalone
+ * function expression whose only bindings are its own parameters.
+ */
+/** Everything a filter expression can test. Sizes are bytes, dimensions pixels. */
+export interface ImageMeta {
+    /** Bytes as served by the site — not the size of the PNG we convert it to. */
+    fileSize: number;
+    height: number;
+    /** Short format token: `webp`, `png`, `jpeg`, `svg`, `avif`, `gif`, … */
+    type: string;
+    url: string;
+    width: number;
+}
+export type ImageFilter = (meta: ImageMeta) => boolean;
+/**
+ * Byte-count helpers for filter expressions: `sizes.KB(100)` is 100 * 1024.
+ *
+ * Every casing of every unit is registered (`KB`, `Kb`, `kB`, `kb`) and they all
+ * mean the same thing — kb is NOT kilobits. Nobody filtering image files means
+ * bits, and a silent factor of eight is a worse outcome than a redundant alias.
+ * Multipliers are binary (1024), matching what an OS reports for a file.
+ */
+export declare const sizes: Record<string, (n: number) => number>;
+/**
+ * Compile a filter expression once, up front.
+ *
+ * Building it eagerly means a typo (`filesize`, a stray paren) fails before the
+ * first image is downloaded rather than four hundred images into a run — the
+ * expression is both parsed and run once against a probe here, since a bad
+ * identifier is a runtime ReferenceError, not a syntax error.
+ */
+export declare const createFilter: (expression: string) => ImageFilter;

package/dist/lib/image-filter.js

@@ -0,0 +1,71 @@
+/**
+ * The `--filter` expression for `fnd alt-text`.
+ *
+ * The expression is evaluated with `eval`, deliberately: it comes from the flag
+ * the person is typing into their own shell, so it is already code they are
+ * running on their own machine — there is no privilege boundary to cross and no
+ * mini-language worth inventing when JavaScript's operators are exactly what a
+ * filter needs. It is NOT safe to feed this a string from anywhere else (a
+ * config file pulled off the network, a CI variable someone else controls).
+ *
+ * What the expression can see is the image's metadata plus `sizes`; nothing is
+ * passed in from the surrounding scope, because the eval'd text is a standalone
+ * function expression whose only bindings are its own parameters.
+ */
+const UNITS = {
+    b: 1,
+    gb: 1024 ** 3,
+    kb: 1024,
+    mb: 1024 ** 2,
+    tb: 1024 ** 4,
+};
+/**
+ * Byte-count helpers for filter expressions: `sizes.KB(100)` is 100 * 1024.
+ *
+ * Every casing of every unit is registered (`KB`, `Kb`, `kB`, `kb`) and they all
+ * mean the same thing — kb is NOT kilobits. Nobody filtering image files means
+ * bits, and a silent factor of eight is a worse outcome than a redundant alias.
+ * Multipliers are binary (1024), matching what an OS reports for a file.
+ */
+export const sizes = Object.fromEntries(Object.entries(UNITS).flatMap(([unit, multiplier]) => {
+    const cased = unit.length === 1
+        ? [unit, unit.toUpperCase()]
+        : [unit, unit.toUpperCase(), unit[0].toUpperCase() + unit[1], unit[0] + unit[1].toUpperCase()];
+    return [...new Set(cased)].map((name) => [name, (n) => n * multiplier]);
+}));
+/** A metadata shape used only to smoke-test the expression at startup. */
+const PROBE = {
+    fileSize: 0,
+    height: 0,
+    type: 'png',
+    url: 'https://example.com/probe.png',
+    width: 0,
+};
+/**
+ * Compile a filter expression once, up front.
+ *
+ * Building it eagerly means a typo (`filesize`, a stray paren) fails before the
+ * first image is downloaded rather than four hundred images into a run — the
+ * expression is both parsed and run once against a probe here, since a bad
+ * identifier is a runtime ReferenceError, not a syntax error.
+ */
+export const createFilter = (expression) => {
+    let compiled;
+    try {
+        // Indirect eval: evaluated in global scope, so the expression can't reach
+        // anything local to this module even by accident.
+        // eslint-disable-next-line no-eval
+        compiled = (0, eval)(`(({ fileSize, height, sizes, type, url, width }) => (${expression}))`);
+    }
+    catch (error) {
+        throw new Error(`--filter is not valid JavaScript: ${error.message}`);
+    }
+    const run = (meta) => Boolean(compiled({ ...meta, sizes }));
+    try {
+        run(PROBE);
+    }
+    catch (error) {
+        throw new Error(`--filter could not be evaluated: ${error.message}. Available values: fileSize, width, height, url, type, sizes.`);
+    }
+    return run;
+};

package/dist/lib/mcp/bracket-args.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A small, reusable parser for a `--with-tool` selection's bracketed argument.
+ *
+ * The registry already splits `name[...]` into the tool name and the raw text
+ * between the brackets (see registry.ts `parseSpec`); this turns that raw text
+ * into named options. The grammar is a comma-separated list where each item is
+ * either a bare **flag** (`ask`) or a **key=value** option (`scopes=all`):
+ *
+ *   shopify-file-delete[ask]
+ *   shopify-execute[ask,scopes=read_products+write_orders]
+ *
+ * A tool declares which flags and value-keys it accepts, so a typo (`aks`, or a
+ * value option a tool doesn't understand) fails up front with a clear message
+ * rather than being silently ignored. Multi-valued options (e.g. a scope list)
+ * keep their value as one opaque string here — the tool splits it however it
+ * likes — because comma is already the option separator (so a list uses `+` or
+ * spaces internally, not commas).
+ */
+/** What a tool allows inside its brackets: bare flags and/or key=value options. */
+export interface BracketSpec {
+    /** Allowed bare flags, lower-cased. Present in the parse result => set to true. */
+    flags?: readonly string[];
+    /** Allowed key=value option keys, lower-cased. */
+    values?: readonly string[];
+}
+/** The parsed brackets: which flags were present, and each key=value pair. */
+export interface BracketArgs {
+    flags: Set<string>;
+    values: Map<string, string>;
+}
+/**
+ * Parse a selection's bracket text against `spec`. An undefined/empty arg yields
+ * an empty result (no flags, no values). Throws — with a message the registry
+ * prefixes with the tool name — on an unknown flag/key, a duplicate, or an empty
+ * value (`scopes=`), so the user learns exactly what they mistyped.
+ */
+export declare const parseBracketArgs: (arg: string | undefined, spec?: BracketSpec) => BracketArgs;

package/dist/lib/mcp/bracket-args.js

@@ -0,0 +1,65 @@
+/**
+ * A small, reusable parser for a `--with-tool` selection's bracketed argument.
+ *
+ * The registry already splits `name[...]` into the tool name and the raw text
+ * between the brackets (see registry.ts `parseSpec`); this turns that raw text
+ * into named options. The grammar is a comma-separated list where each item is
+ * either a bare **flag** (`ask`) or a **key=value** option (`scopes=all`):
+ *
+ *   shopify-file-delete[ask]
+ *   shopify-execute[ask,scopes=read_products+write_orders]
+ *
+ * A tool declares which flags and value-keys it accepts, so a typo (`aks`, or a
+ * value option a tool doesn't understand) fails up front with a clear message
+ * rather than being silently ignored. Multi-valued options (e.g. a scope list)
+ * keep their value as one opaque string here — the tool splits it however it
+ * likes — because comma is already the option separator (so a list uses `+` or
+ * spaces internally, not commas).
+ */
+/**
+ * Parse a selection's bracket text against `spec`. An undefined/empty arg yields
+ * an empty result (no flags, no values). Throws — with a message the registry
+ * prefixes with the tool name — on an unknown flag/key, a duplicate, or an empty
+ * value (`scopes=`), so the user learns exactly what they mistyped.
+ */
+export const parseBracketArgs = (arg, spec = {}) => {
+    const flags = new Set();
+    const values = new Map();
+    const allowedFlags = new Set(spec.flags ?? []);
+    const allowedValues = new Set(spec.values ?? []);
+    const raw = arg?.trim();
+    if (!raw)
+        return { flags, values };
+    for (const part of raw.split(',')) {
+        const token = part.trim();
+        if (!token)
+            continue; // tolerate a stray/trailing comma
+        const eq = token.indexOf('=');
+        if (eq === -1) {
+            // A bare flag, e.g. `ask`.
+            const name = token.toLowerCase();
+            if (!allowedFlags.has(name)) {
+                const hint = allowedFlags.size > 0 ? ` supported flags: ${[...allowedFlags].join(', ')}.` : '';
+                throw new Error(`does not support the "${token}" option.${hint}`);
+            }
+            if (flags.has(name))
+                throw new Error(`option "${name}" was given more than once.`);
+            flags.add(name);
+        }
+        else {
+            // A key=value option, e.g. `scopes=all`.
+            const key = token.slice(0, eq).trim().toLowerCase();
+            const value = token.slice(eq + 1).trim();
+            if (!allowedValues.has(key)) {
+                const hint = allowedValues.size > 0 ? ` supported: ${[...allowedValues].map((v) => `${v}=…`).join(', ')}.` : '';
+                throw new Error(`does not support the "${key}=" option.${hint}`);
+            }
+            if (values.has(key))
+                throw new Error(`option "${key}=" was given more than once.`);
+            if (!value)
+                throw new Error(`option "${key}=" needs a value.`);
+            values.set(key, value);
+        }
+    }
+    return { flags, values };
+};

package/dist/lib/mcp/define-tool.d.ts

@@ -0,0 +1,52 @@
+import type { McpToolSpec } from './server.js';
+/**
+ * The defineTool framework for `--with-tool`.
+ *
+ * A tool module builds itself with defineTool() and imports nothing from the
+ * registry — the registry imports the tools, never the other way round. Keeping
+ * the framework here (not in registry.ts) is what breaks that cycle: a tool can
+ * `import { defineTool }` without pulling the registry, and its own tool, back
+ * into its initialization.
+ */
+/** Runtime facts a tool's handler may need — resolved once the workspace is known. */
+export interface ToolRuntime {
+    /** Absolute path of the synced directory on THIS machine (the tool handler's cwd). */
+    localCwd: string;
+}
+/**
+ * Command-level context a tool's `parse` may need, beyond its own bracketed
+ * [arg]. Some tools take a shared flag rather than a per-tool argument — the
+ * Shopify tools read the store from `--site-id`, so they all target one store —
+ * and this is how that flag reaches them.
+ */
+export interface ParseContext {
+    /** The `--site-id` flag value, if given (the Shopify store for the Shopify tools). */
+    siteId?: string;
+}
+/**
+ * A tool selectable via `--with-tool`. `C` is the parsed config a selection
+ * produces (e.g. a normalized store domain). The lifecycle is:
+ *   parse(arg, context)        — validate the [arg] and any command-level flags
+ *                                it depends on, up front, before anything else
+ *   preflight(config, log)     — verify prerequisites & do interactive setup
+ *                                (auth, scope grants) BEFORE the remote connects;
+ *                                throw with a friendly message to abort
+ *   build(config, runtime)     — the MCP tool spec(s) the server serves
+ *
+ * `argHint` is undefined for a tool that takes no bracketed [arg] (the Shopify
+ * tools — their store comes from `--site-id`), which the registry uses both to
+ * reject a stray `[arg]` and to print bare-name usage.
+ */
+export interface WorkspaceTool<C = unknown> {
+    /** What the bracketed argument means, for usage text; undefined if the tool takes no [arg]. */
+    argHint?: string;
+    /** Whether `[arg]` is required. Only meaningful when `argHint` is set. */
+    argRequired?: boolean;
+    build: (config: C, runtime: ToolRuntime) => McpToolSpec[];
+    /** Registry key and the name used in `--with-tool <name>`. */
+    name: string;
+    parse: (arg: string | undefined, context: ParseContext) => C;
+    preflight: (config: C, log: (message: string) => void) => Promise<void> | void;
+}
+/** Identity helper that pins a tool's config type — the defineTool framework. */
+export declare const defineTool: <C>(tool: WorkspaceTool<C>) => WorkspaceTool<C>;

package/dist/lib/mcp/define-tool.js

@@ -0,0 +1,2 @@
+/** Identity helper that pins a tool's config type — the defineTool framework. */
+export const defineTool = (tool) => tool;

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

@@ -0,0 +1,38 @@
+import type { ParseContext, ToolRuntime, WorkspaceTool } from './define-tool.js';
+import type { McpToolSpec } from './server.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 declare const TOOL_REGISTRY: Record<string, WorkspaceTool>;
+/** A resolved `--with-tool` selection: the tool, its parsed config, and the raw spec. */
+export interface ToolSelection {
+    config: unknown;
+    raw: string;
+    tool: WorkspaceTool;
+}
+/** One-line usage listing the registered tools and their argument shape. */
+export declare const withToolUsage: () => string;
+/**
+ * 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 declare const resolveWorkspaceTools: (specs: string[], context: ParseContext) => ToolSelection[];
+/**
+ * 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 declare const collectToolSpecs: (selections: ToolSelection[], runtime: ToolRuntime) => McpToolSpec[];

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;
+};