@firenet-designs/fnd-cli 2.4.0 → 2.7.0

package/oclif.manifest.json

@@ -1,5 +1,142 @@
 {
   "commands": {
+    "alt-text": {
+      "aliases": [
+        "caption"
+      ],
+      "args": {},
+      "description": "Generate alt text for a site's images with a local Ollama vision model and write it back.\n\nPick a platform with --platform (webflow or shopify). For Webflow, walks the site asset library and (with --cms) the image fields of CMS collection items and PATCHes each description back through the Data API. For Shopify, walks the store's file library and writes alt text back through the Shopify CLI (which owns the auth — no --api-key). Images are fetched and described one at a time; nothing but the platform API calls leaves your network.\n\nWebflow CMS writes go to STAGING, so publish the site in Webflow to make them live. Any required flag you omit is prompted for.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --platform webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b",
+        "<%= config.bin %> <%= command.id %> --platform shopify --site-id mystore",
+        "<%= config.bin %> <%= command.id %> --platform shopify --site-id mystore --dry",
+        "<%= config.bin %> <%= command.id %> --platform webflow --skip --limit 20",
+        "<%= config.bin %> <%= command.id %> --platform webflow --cms --select",
+        "<%= config.bin %> <%= command.id %> --platform webflow --cms --only products --only sku",
+        "<%= config.bin %> <%= command.id %> --platform webflow --output-stats ./alt-text-run.md",
+        "<%= config.bin %> <%= command.id %> --platform webflow --filter \"fileSize>=sizes.KB(100) && width>=100 && height>=100\"",
+        "<%= config.bin %> <%= command.id %> --platform webflow --filter \"type !== 'svg' && !url.includes('/icons/')\""
+      ],
+      "flags": {
+        "api-key": {
+          "description": "Webflow API token (site-scoped). Webflow only — Shopify auth comes from the Shopify CLI. Prompted for if omitted.",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "cms": {
+          "description": "also add alt text to the images in CMS collection items. Webflow only. Off by default — only the site asset library is walked.",
+          "name": "cms",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dry": {
+          "description": "report how many images the run would caption without describing or writing anything. Every image is still downloaded and run through --filter so the count is accurate, but nothing reaches the model. The --ollama-host/--ollama-model and --output-stats flags are ignored in this mode, so --dry can be added to (and removed from) a full command without changing the rest.",
+          "name": "dry",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "filter": {
+          "description": "a JavaScript expression deciding which images are worth describing, e.g. \"fileSize>=sizes.KB(100) && width>=100 && height>=100\". Available: fileSize (bytes), width, height (pixels), url, type (\"webp\", \"png\", \"jpeg\", \"svg\", …), and sizes.KB/MB/GB helpers. Images that fail it are skipped and reported separately. Evaluated after the download, since dimensions can't be known before it.",
+          "name": "filter",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "description": "stop after this many images have been transcribed (counted across assets and CMS together)",
+          "name": "limit",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ollama-host": {
+          "description": "base URL of the Ollama server. Prompted for if omitted.",
+          "name": "ollama-host",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ollama-model": {
+          "description": "the model used to describe the images. Omit it to pick from the vision-capable models pulled on the host.",
+          "name": "ollama-model",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "only": {
+          "dependsOn": [
+            "cms"
+          ],
+          "description": "only touch these CMS collections, matched case-insensitively against a collection's name or slug. Repeat the flag for more than one.",
+          "exclusive": [
+            "select"
+          ],
+          "name": "only",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "output-stats": {
+          "description": "also write the run stats to this file as Markdown: totals, a row per image (url, description, tokens, time, size), and the failures. Parent directories are created.",
+          "name": "output-stats",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "platform": {
+          "description": "which platform to run against. Prompted for if omitted.",
+          "name": "platform",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "webflow",
+            "shopify"
+          ],
+          "type": "option"
+        },
+        "select": {
+          "dependsOn": [
+            "cms"
+          ],
+          "description": "fetch the CMS collections and pick which ones to process interactively",
+          "exclusive": [
+            "only"
+          ],
+          "name": "select",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "site-id": {
+          "description": "Webflow site ID, or the Shopify store (mystore or mystore.myshopify.com). Prompted for if omitted.",
+          "name": "site-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "skip": {
+          "description": "leave images that already have alt text alone instead of overwriting them",
+          "name": "skip",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "alt-text",
+      "pluginAlias": "@firenet-designs/fnd-cli",
+      "pluginName": "@firenet-designs/fnd-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "alt-text.js"
+      ]
+    },
     "backfill-project": {
       "aliases": [],
       "args": {
@@ -80,7 +217,7 @@
           "required": false
         }
       },
-      "description": "Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.\n\nGitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI never stores credentials. Override the org with FND_GH_ORG.",
+      "description": "Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org with production and staging branches pushed.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.\n\nGitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI never stores credentials. Override the org with FND_GH_ORG.",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
         "<%= config.bin %> <%= command.id %> my-store",
@@ -183,76 +320,6 @@
         "token.js"
       ]
     },
-    "workspace:cleanup": {
-      "aliases": [],
-      "args": {},
-      "description": "Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.\n\nTerminates any Mutagen sync sessions this machine started for the directory. Pass --devtools or --rpc to also strip the matching MCP entries from the remote (only do this if the dropped session used those flags). With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place unless you pass --delete-remote-dir.",
-      "examples": [
-        "<%= config.bin %> <%= command.id %> --ssh user@host",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --devtools",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --rpc",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir"
-      ],
-      "flags": {
-        "delete-remote-dir": {
-          "description": "also delete the remote workspace directory (by default the synced files are left in place)",
-          "name": "delete-remote-dir",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "devtools": {
-          "description": "also strip the chrome-devtools MCP entry from the remote (only if the dropped session used --devtools)",
-          "name": "devtools",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "remote-base": {
-          "description": "base dir on the remote, used to derive the default remote directory path",
-          "name": "remote-base",
-          "default": "/home/fnd",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "remote-dir": {
-          "description": "exact remote directory to target (defaults to the current dir mapping)",
-          "name": "remote-dir",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "rpc": {
-          "description": "also strip the local-shell MCP entry from the remote (only if the dropped session used --rpc)",
-          "name": "rpc",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "ssh": {
-          "description": "remote to connect to, as user@host",
-          "name": "ssh",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "workspace:cleanup",
-      "pluginAlias": "@firenet-designs/fnd-cli",
-      "pluginName": "@firenet-designs/fnd-cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "workspace",
-        "cleanup.js"
-      ]
-    },
     "workspace": {
       "aliases": [],
       "args": {},
@@ -264,11 +331,21 @@
         "<%= config.bin %> <%= command.id %> --ssh user@host --ignore-vcs",
         "<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9222",
         "<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9333:9222",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --rpc port=7777:7700",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --rpc port=7777:7700,profile=false,shell=zsh",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir"
+        "<%= config.bin %> <%= command.id %> --ssh user@host --with-tool shopify-file-upload --site-id mystore",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --with-tool shopify-file-upload --with-tool shopify-file-search --with-tool \"shopify-file-delete[ask]\" --site-id mystore",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --with-tool shopify-file-upload --with-tool shopify-file-replace --with-tool shopify-file-delete --site-id mystore.myshopify.com",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --with-tool \"shopify-execute[scopes=read_products+read_orders]\" --site-id mystore",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --with-tool \"shopify-execute[ask,scopes=all]\" --site-id mystore",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --with-tool shopify-file-upload --site-id mystore --cleanup"
       ],
       "flags": {
+        "cleanup": {
+          "description": "tear down a leftover session instead of opening one — don't connect, just terminate this directory's Mutagen sync and (using whatever other flags are set) strip the remote --devtools/--with-tool MCP entries and, with --delete-remote-dir, remove the remote dir. Re-run your original command with --cleanup appended after a session that dropped without cleaning up.",
+          "name": "cleanup",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "delete-remote-dir": {
           "description": "on exit, delete the remote workspace directory instead of leaving the synced copy in place",
           "name": "delete-remote-dir",
@@ -296,9 +373,9 @@
           "multiple": false,
           "type": "option"
         },
-        "rpc": {
-          "description": "expose a run_local_command MCP tool to Claude on the remote that executes commands back on THIS machine (the one running fnd workspace). Value is port=<port|remote:local>[,profile=<true|1|false|0>][,shell=<bash|batch|powershell|sh|zsh>] — port opens a reverse tunnel (ssh -R <remote>:localhost:<local>) to a command server started here; shell defaults to the shell fnd workspace was called from; profile (default true) controls whether the shell loads its startup files — with it on, POSIX shells run interactively (-i) so rc files like ~/.bashrc or ~/.zshrc are sourced and tools such as nvm work.",
-          "name": "rpc",
+        "site-id": {
+          "description": "the Shopify store (mystore or mystore.myshopify.com) the Shopify --with-tool tools operate on. Required when any Shopify tool (shopify-file-* or shopify-execute) is selected; fixing the store here is a safety boundary — the remote AI cannot target another store.",
+          "name": "site-id",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -321,6 +398,13 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "with-tool": {
+          "description": "expose an fnd tool to Claude on the remote via a loopback MCP server on THIS machine (the one running fnd workspace), reached through a reverse tunnel. Repeatable. Value is <name> or <name>[options]; available: shopify-execute[<scopes=all|<list>[,ask]>], shopify-file-delete[[<ask>]], shopify-file-replace[[<ask>]], shopify-file-search[[<ask>]], shopify-file-upload[[<ask>]]. e.g. shopify-file-upload (with --site-id mystore) lets the remote AI upload files from the workspace into that Shopify store using your local Shopify CLI; shopify-file-replace and shopify-file-delete add in-place replace and delete; shopify-file-search looks up files by name/size/type/url (metadata only, no image bytes) to dedupe before upload or find oversized images; shopify-execute runs arbitrary Admin GraphQL and REQUIRES a scopes option — shopify-execute[scopes=all] for broad access or shopify-execute[scopes=read_products+write_orders] for an explicit set (which the store is then trimmed to, revoking anything extra, so the AI is held to least privilege). Append ,ask (e.g. shopify-file-delete[ask], shopify-execute[ask,scopes=all]) to make that tool prompt for confirmation before EVERY call, even under the remote's auto-accept/bypass permissions — use it to gate the powerful/destructive tools. Prerequisites (auth, scopes) are checked and set up before connecting.",
+          "name": "with-tool",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -340,5 +424,5 @@
       ]
     }
   },
-  "version": "2.4.0"
+  "version": "2.7.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firenet-designs/fnd-cli",
   "description": "A new CLI generated with oclif",
-  "version": "2.4.0",
+  "version": "2.7.0",
   "author": "Cole Denslow",
   "contributors": [
     "Justin Schellenberg"
@@ -11,11 +11,16 @@
   },
   "bugs": "https://github.com/FireNet-Designs/fnd-cli/issues",
   "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
     "@oclif/core": "^4",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-plugins": "^5",
+    "@oclif/plugin-warn-if-update-available": "^3.1.71",
+    "@resvg/resvg-js": "^2.6.2",
     "chalk": "^5.6.2",
+    "ollama": "^0.6.3",
     "ora": "^9.3.0",
+    "sharp": "^0.34.5",
     "simple-git": "^3.32.2",
     "zod": "^4.4.3"
   },
@@ -49,6 +54,12 @@
     "./oclif.manifest.json"
   ],
   "homepage": "https://github.com/FireNet-Designs/fnd-cli",
+  "imports": {
+    "#*": {
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
   "keywords": [
     "oclif"
   ],
@@ -63,14 +74,14 @@
     "bin": "fnd",
     "dirname": "fnd-cli",
     "commands": "./dist/commands",
-    "hooks": {
-      "init": [
-        "./dist/hooks/init/check-for-updates"
-      ]
-    },
     "plugins": [
-      "@oclif/plugin-help"
+      "@oclif/plugin-help",
+      "@oclif/plugin-warn-if-update-available"
     ],
+    "warn-if-update-available": {
+      "timeoutInDays": 1,
+      "message": "💡 Version <%= chalk.greenBright(latest) %> available! Run <%= chalk.greenBright('npm i -g ' + config.name) %> to update to the latest version."
+    },
     "topicSeparator": " ",
     "topics": {
       "hello": {
@@ -86,13 +97,13 @@
     "url": "git+https://github.com/FireNet-Designs/fnd-cli.git"
   },
   "scripts": {
-    "build": "shx rm -rf dist && tsc -b",
+    "build": "shx rm -rf dist && tsc -b && shx cp -r src/lib/shopify/graphql dist/lib/shopify/graphql",
     "lint": "eslint",
     "pack": "npm run prepack && npm run postpack",
     "postpack": "shx rm -f oclif.manifest.json",
     "posttest": "npm run lint",
-    "prepack": "oclif manifest && oclif readme",
-    "version": "oclif readme",
+    "prepack": "oclif manifest && oclif readme && node scripts/strip-os-from-readme.mjs",
+    "version": "oclif readme && node scripts/strip-os-from-readme.mjs",
     "prerelease": "npm run build && npm run prepack",
     "release": "npm run build && npm run prepack && npm publish"
   },

package/dist/commands/workspace/cleanup.d.ts

@@ -1,14 +0,0 @@
-import { Command } from '@oclif/core';
-export default class WorkspaceCleanup extends Command {
-    static description: string;
-    static examples: string[];
-    static flags: {
-        'delete-remote-dir': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        devtools: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        'remote-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        'remote-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        rpc: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        ssh: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-    };
-    run(): Promise<void>;
-}

package/dist/commands/workspace/cleanup.js

@@ -1,84 +0,0 @@
-import { Command, Flags } from '@oclif/core';
-import chalk from 'chalk';
-import { basename } from 'node:path';
-import { buildContext, buildMutagenTerminateSelectorArgs, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, parseSshTarget, runMutagen, runRemoteCleanup, slugify, } from '../../lib/workspace.js';
-export default class WorkspaceCleanup extends Command {
-    static description = 'Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.\n\nTerminates any Mutagen sync sessions this machine started for the directory. Pass --devtools or --rpc to also strip the matching MCP entries from the remote (only do this if the dropped session used those flags). With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place unless you pass --delete-remote-dir.';
-    static examples = [
-        '<%= config.bin %> <%= command.id %> --ssh user@host',
-        '<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli',
-        '<%= config.bin %> <%= command.id %> --ssh user@host --devtools',
-        '<%= config.bin %> <%= command.id %> --ssh user@host --rpc',
-        '<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir',
-    ];
-    static flags = {
-        'delete-remote-dir': Flags.boolean({
-            default: false,
-            description: 'also delete the remote workspace directory (by default the synced files are left in place)',
-        }),
-        devtools: Flags.boolean({
-            default: false,
-            description: 'also strip the chrome-devtools MCP entry from the remote (only if the dropped session used --devtools)',
-        }),
-        'remote-base': Flags.string({
-            default: DEFAULT_MOUNT_BASE,
-            description: 'base dir on the remote, used to derive the default remote directory path',
-        }),
-        'remote-dir': Flags.string({
-            description: 'exact remote directory to target (defaults to the current dir mapping)',
-        }),
-        rpc: Flags.boolean({
-            default: false,
-            description: 'also strip the local-shell MCP entry from the remote (only if the dropped session used --rpc)',
-        }),
-        ssh: Flags.string({
-            description: 'remote to connect to, as user@host',
-            required: true,
-        }),
-    };
-    async run() {
-        const { flags } = await this.parse(WorkspaceCleanup);
-        if (!hasSshClient()) {
-            this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
-        }
-        const target = parseSshTarget(flags.ssh);
-        const target2 = `${target.user}@${target.host}`;
-        const remoteDir = flags['remote-dir'] ??
-            buildContext({ cwd: process.cwd(), remoteBase: flags['remote-base'] }).remoteDir;
-        const slug = slugify(basename(remoteDir));
-        this.log(chalk.bold('Cleaning up workspace'));
-        this.log(`  ${chalk.dim('remote:')}     ${target2}`);
-        this.log(`  ${chalk.dim('remote dir:')} ${remoteDir}`);
-        this.log('');
-        // Terminate any lingering sync sessions for this directory (a local Mutagen op).
-        if (hasMutagen()) {
-            this.log(chalk.dim('Terminating any leftover Mutagen sync sessions…'));
-            await runMutagen(buildMutagenTerminateSelectorArgs(slug)).catch(() => 1);
-        }
-        else {
-            this.log(chalk.yellow('Mutagen CLI not found on PATH — skipping sync termination.'));
-        }
-        // Strip any MCP config this workspace left on the remote (only when asked),
-        // and optionally delete the synced directory itself.
-        if (flags.devtools) {
-            this.log(chalk.dim('Removing any leftover chrome-devtools MCP config on the remote…'));
-        }
-        if (flags.rpc) {
-            this.log(chalk.dim('Removing any leftover local-shell MCP config on the remote…'));
-        }
-        if (flags['delete-remote-dir']) {
-            this.log(chalk.dim('Deleting the remote workspace directory…'));
-        }
-        const code = await runRemoteCleanup(target2, remoteDir, {
-            deleteRemoteDir: flags['delete-remote-dir'],
-            removeDevtoolsMcp: flags.devtools,
-            removeRpcMcp: flags.rpc,
-        });
-        if (code === 0) {
-            this.log(chalk.green('✓ Done.'));
-        }
-        else {
-            this.error(`Remote cleanup ssh session exited with code ${code}.`, { code: '1' });
-        }
-    }
-}

package/dist/hooks/init/check-for-updates.d.ts

@@ -1,3 +0,0 @@
-import { Hook } from '@oclif/core';
-declare const hook: Hook<'init'>;
-export default hook;

package/dist/hooks/init/check-for-updates.js

@@ -1,15 +0,0 @@
-import chalk from 'chalk';
-import { exec } from 'node:child_process';
-const hook = async function (opts) {
-    const newestVersion = await new Promise((resolve, reject) => {
-        exec(`npm view @firenet-designs/fnd-cli version`, (error, stdout) => {
-            if (error)
-                return reject(error);
-            resolve(stdout.trim());
-        });
-    });
-    if (newestVersion !== opts.config.pjson.version) {
-        console.log(chalk.yellow('💡 Version', chalk.green(newestVersion), 'available! Run', chalk.green('`npm i -g @firenet-designs/fnd-cli`'), 'to update to the latest version!\n'));
-    }
-};
-export default hook;

package/dist/lib/kv-flag.d.ts

@@ -1,15 +0,0 @@
-import { z } from 'zod';
-type KvShape = Record<string, z.ZodType>;
-/** Usage string for the schema, required keys first: `a=<...>,b=<...>[,c=<...>]`. */
-export declare const kvUsage: (schema: z.ZodObject<KvShape>) => string;
-/** Example flag value built from each field's example meta (falls back to its hint), required keys first. */
-export declare const kvExample: (schema: z.ZodObject<KvShape>, opts?: {
-    requiredOnly?: boolean;
-}) => string;
-/**
- * Parse a key=value flag string against the schema. Keys are case-insensitive
- * and order-independent; unknown keys, duplicate keys, and missing required
- * keys are hard errors naming the flag and its usage.
- */
-export declare const parseKvFlag: <T extends KvShape>(flag: string, raw: string, schema: z.ZodObject<T>) => z.output<z.ZodObject<T>>;
-export {};

package/dist/lib/kv-flag.js

@@ -1,75 +0,0 @@
-const fieldMeta = (field) => (field.meta() ?? {});
-const isOptional = (field) => field.def.type === 'default' || field.def.type === 'optional';
-/** Unwrap default/optional/preprocess wrappers down to the schema describing the value. */
-const unwrap = (field) => {
-    const { def } = field;
-    if (def.type === 'default' || def.type === 'optional') {
-        return unwrap(def.innerType);
-    }
-    if (def.type === 'pipe') {
-        return unwrap(def.out);
-    }
-    return field;
-};
-/** The <placeholder> for a field's value: explicit hint meta, enum options, or "value". */
-const fieldHint = (field) => {
-    const { hint } = fieldMeta(field);
-    if (hint)
-        return hint;
-    const inner = unwrap(field);
-    if (inner.def.type === 'enum') {
-        return Object.values(inner.def.entries).join('|');
-    }
-    return 'value';
-};
-/** Usage string for the schema, required keys first: `a=<...>,b=<...>[,c=<...>]`. */
-export const kvUsage = (schema) => {
-    const fields = Object.entries(schema.shape);
-    const required = fields.filter(([, f]) => !isOptional(f));
-    const optional = fields.filter(([, f]) => isOptional(f));
-    const pair = ([key, field]) => `${key}=<${fieldHint(field)}>`;
-    return required.map((f) => pair(f)).join(',') + optional.map((f) => `[,${pair(f)}]`).join('');
-};
-/** Example flag value built from each field's example meta (falls back to its hint), required keys first. */
-export const kvExample = (schema, opts) => {
-    const fields = Object.entries(schema.shape).filter(([, field]) => !(opts?.requiredOnly && isOptional(field)));
-    return [...fields.filter(([, f]) => !isOptional(f)), ...fields.filter(([, f]) => isOptional(f))]
-        .map(([key, field]) => `${key}=${fieldMeta(field).example ?? fieldHint(field)}`)
-        .join(',');
-};
-/**
- * Parse a key=value flag string against the schema. Keys are case-insensitive
- * and order-independent; unknown keys, duplicate keys, and missing required
- * keys are hard errors naming the flag and its usage.
- */
-export const parseKvFlag = (flag, raw, schema) => {
-    const usage = `${flag} takes comma-separated key=value pairs: ${kvUsage(schema)}`;
-    const known = Object.keys(schema.shape);
-    const pairs = new Map();
-    for (const part of raw.trim().split(',')) {
-        const eq = part.indexOf('=');
-        if (eq === -1) {
-            throw new Error(`${usage} (got "${raw}")`);
-        }
-        const key = part.slice(0, eq).trim().toLowerCase();
-        if (!known.includes(key)) {
-            throw new Error(`${flag} has no "${key}" option. ${usage}`);
-        }
-        if (pairs.has(key)) {
-            throw new Error(`${flag} "${key}" was given more than once (got "${raw}")`);
-        }
-        pairs.set(key, part.slice(eq + 1).trim());
-    }
-    for (const key of known) {
-        if (!isOptional(schema.shape[key]) && !pairs.has(key)) {
-            throw new Error(`${flag} needs "${key}". ${usage}`);
-        }
-    }
-    const result = schema.safeParse(Object.fromEntries(pairs));
-    if (!result.success) {
-        const issue = result.error.issues[0];
-        const at = issue.path.join('.');
-        throw new Error(`${flag}${at ? ` ${at}` : ''}: ${issue.message}. ${usage}`);
-    }
-    return result.data;
-};

package/dist/lib/rpc.d.ts

@@ -1,69 +0,0 @@
-import { z } from 'zod';
-import { PortPair } from './workspace.js';
-/**
- * The --rpc local-command 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 the
- * `run_local_command` tool, the command executes HERE, on the calling machine,
- * under the shell chosen in the flag.
- *
- * The server binds loopback only; the sole way in from outside is the reverse
- * tunnel, which lives exactly as long as the ssh session.
- */
-declare const ShellSchema: z.ZodEnum<{
-    zsh: "zsh";
-    bash: "bash";
-    batch: "batch";
-    powershell: "powershell";
-    sh: "sh";
-}>;
-export declare const RPC_SHELLS: ("zsh" | "bash" | "batch" | "powershell" | "sh")[];
-export type RpcShell = z.infer<typeof ShellSchema>;
-/** Usage and example strings for the --rpc flag, derived from the schema. */
-export declare const RPC_FLAG_USAGE: string;
-export declare const RPC_FLAG_EXAMPLES: {
-    full: string;
-    required: string;
-};
-export interface RpcConfig {
-    /** local = port the server binds on this machine; remote = port opened on the workspace host via `ssh -R`. */
-    ports: PortPair;
-    /** Whether the shell loads its startup files (rc/profile). POSIX shells run with -i, powershell without -NoProfile. */
-    profile: boolean;
-    /** Shell used to execute commands on this machine. */
-    shell: RpcShell;
-}
-/** Handle for a running RPC server. */
-export interface RpcServer {
-    close: () => Promise<void>;
-}
-export declare const RPC_TOOL_NAME = "run_local_command";
-/**
- * The shell `fnd workspace` was called from: the parent process when it is a
- * supported shell, else $SHELL, else undefined (e.g. invoked from a script).
- */
-export declare const detectCallingShell: () => RpcShell | undefined;
-/**
- * Parse the --rpc value: comma-separated key=value pairs per RpcFlagSchema.
- *   port=<port> | port=<remote>:<local> — required; `local` is this machine
- *     (where commands run), `remote` the port opened on the workspace host.
- *     The single-port form uses the same port on both ends.
- *   shell=<bash|batch|powershell|sh|zsh> — optional, defaults to the shell
- *     `fnd workspace` was called from.
- *   profile=<true|1|false|0> — optional, default true: the shell loads its
- *     startup files (rc/profile), so tools like nvm are available.
- */
-export declare const parseRpcFlag: (raw: string) => RpcConfig;
-/** True if the chosen shell is runnable on this machine. */
-export declare const hasLocalShell: (shell: RpcShell, profile: boolean) => boolean;
-/**
- * Start the local RPC (MCP) server on 127.0.0.1:<ports.local>. Commands execute
- * with `cwd` as their working directory — the local side of the workspace sync.
- * Resolves once the port is bound; rejects if binding fails (e.g. port in use).
- */
-export declare const startRpcServer: (config: RpcConfig, cwd: string) => Promise<RpcServer>;
-export {};