@firenet-designs/fnd-cli 2.4.0 → 2.6.0

package/dist/commands/alt-text.js

@@ -0,0 +1,404 @@
+import { checkbox, input, password, select } from '@inquirer/prompts';
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { createDescriber, DEFAULT_OLLAMA_HOST, listVisionModels } from '../lib/alt-text.js';
+import { createFilter } from '../lib/image-filter.js';
+import { getAssets, getCollectionItems, getCollections, isImageField, isImagesField, updateAssetAltText, updateCollectionItem, } from '../lib/webflow.js';
+const atLimit = (state) => state.transcribed >= state.limit;
+/** Non-empty validator for the @inquirer prompts that stand in for required flags. */
+const required = (value) => (value.trim().length > 0 ? true : 'Required');
+/** Trim a URL down to something that fits a terminal line. */
+const shortUrl = (url) => {
+    const name = url.split('?')[0].split('/').pop() ?? url;
+    return name.length > 60 ? `${name.slice(0, 57)}…` : name;
+};
+const formatMs = (ms) => (ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`);
+const formatBytes = (bytes) => bytes < 1024 * 1024 ? `${Math.round(bytes / 1024)} KB` : `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+const formatCount = (n) => n.toLocaleString('en-US');
+/**
+ * Make a value safe to drop in a Markdown table cell: pipes would end the cell
+ * early and a newline would end the row. Descriptions are model output, so both
+ * are possible even though the prompt asks for one plain sentence.
+ */
+const cell = (value) => value.replaceAll('|', String.raw `\|`).replaceAll(/\s*\n\s*/g, ' ').trim();
+const sum = (values) => values.reduce((total, value) => total + value, 0);
+/** The thumbnail that stands in for a URL in every table. */
+const thumbnail = (url) => cell(`<img src="${url}" style="object-fit: contain; object-position: center; max-width: 256px; max-height: 256px" />`);
+/**
+ * The --output-stats report: totals, a row per image, the filtered-out images,
+ * then the failures.
+ *
+ * Sizes throughout are the file as the site serves it (`meta.fileSize`) — the
+ * same number the --filter sees, so a report can be read against the expression
+ * that produced it. The PNG we actually send the model gets its own column.
+ */
+const buildStatsMarkdown = (state, model, host, totalMs) => {
+    const tokens = sum(state.images.map((image) => image.tokens));
+    const described = sum(state.images.map((image) => image.ms));
+    const count = state.images.length;
+    const skippedBytes = sum(state.skipped.map((meta) => meta.fileSize));
+    const skippedCount = state.skipped.length;
+    const lines = [
+        '# Alt text run',
+        '',
+        `- Model: \`${model}\` on \`${host}\``,
+        `- Run duration: ${formatMs(totalMs)}`,
+        '',
+        '## Summary',
+        '',
+        '| Metric | Value |',
+        '| --- | --- |',
+        `| Images modified | ${formatCount(count)} |`,
+        `| Images skipped by filter | ${formatCount(skippedCount)} |`,
+        `| Images failed | ${formatCount(state.failures.length)} |`,
+        `| Tokens used | ${formatCount(tokens)} |`,
+        `| Average tokens per image | ${count > 0 ? formatCount(Math.round(tokens / count)) : '—'} |`,
+        `| Average time per image | ${count > 0 ? formatMs(described / count) : '—'} |`,
+        `| Skipped image total size | ${formatBytes(skippedBytes)} |`,
+        `| Skipped image average size | ${skippedCount > 0 ? formatBytes(skippedBytes / skippedCount) : '—'} |`,
+        '',
+        '## Images',
+        '',
+    ];
+    if (count === 0) {
+        lines.push('_No images were transcribed._', '');
+    }
+    else {
+        lines.push('| URL | Description | Tokens | Time | Size | Sent | Type | Dimensions |', '| --- | --- | --- | --- | --- | --- | --- | --- |', ...state.images.map((image) => `| ${thumbnail(image.url)} | ${cell(image.description)} | ${formatCount(image.tokens)} | ${formatMs(image.ms)} | ${formatBytes(image.meta.fileSize)} | ${formatBytes(image.bytes)} | ${cell(image.meta.type)} | ${image.meta.width}x${image.meta.height} |`), '');
+    }
+    lines.push('## Skipped by filter', '');
+    if (skippedCount === 0) {
+        lines.push('_None._', '');
+    }
+    else {
+        lines.push('| URL | Size | Type | Dimensions |', '| --- | --- | --- | --- |', ...state.skipped.map((meta) => `| ${thumbnail(meta.url)} | ${formatBytes(meta.fileSize)} | ${cell(meta.type)} | ${meta.width}x${meta.height} |`), '');
+    }
+    lines.push('## Failures', '');
+    if (state.failures.length === 0) {
+        lines.push('_None._', '');
+    }
+    else {
+        lines.push('| URL | Reason |', '| --- | --- |', ...state.failures.map((failure) => `| ${cell(failure.url)} | ${cell(failure.reason)} |`), '');
+    }
+    return lines.join('\n');
+};
+export default class AltText extends Command {
+    static aliases = ['caption'];
+    static description = 'Generate alt text for a site\'s images with a local Ollama vision model and write it back.\n\nWalks the Webflow site asset library and (with --cms) the image fields of CMS collection items, describes every image that needs alt text, and PATCHes the description back. Images are fetched and described one at a time — a single local model gains nothing from concurrency, and Webflow rate-limits. Nothing leaves your network except the Webflow API calls.\n\nCMS writes go to STAGING, so publish the site in Webflow to make them live. Any required flag you omit is prompted for.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b',
+        '<%= config.bin %> <%= command.id %> --webflow --skip --limit 20',
+        '<%= config.bin %> <%= command.id %> --webflow --cms --select',
+        '<%= config.bin %> <%= command.id %> --webflow --cms --only products --only sku',
+        '<%= config.bin %> <%= command.id %> --webflow --output-stats ./alt-text-run.md',
+        '<%= config.bin %> <%= command.id %> --webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"',
+        '<%= config.bin %> <%= command.id %> --webflow --filter "type !== \'svg\' && !url.includes(\'/icons/\')"',
+    ];
+    static flags = {
+        'api-key': Flags.string({
+            dependsOn: ['webflow'],
+            description: 'Webflow API token (site-scoped). Prompted for if omitted.',
+        }),
+        cms: Flags.boolean({
+            dependsOn: ['webflow'],
+            description: 'also add alt text to the images in CMS collection items. Off by default — only the site asset library is walked.',
+        }),
+        filter: Flags.string({
+            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.',
+        }),
+        limit: Flags.integer({
+            description: 'stop after this many images have been transcribed (counted across assets and CMS together)',
+            min: 1,
+        }),
+        'ollama-host': Flags.string({
+            description: `base URL of the Ollama server. Prompted for if omitted.`,
+        }),
+        'ollama-model': Flags.string({
+            description: 'the model used to describe the images. Omit it to pick from the vision-capable models pulled on the host.',
+        }),
+        only: Flags.string({
+            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'],
+            multiple: true,
+        }),
+        'output-stats': Flags.string({
+            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.',
+        }),
+        select: Flags.boolean({
+            dependsOn: ['cms'],
+            description: 'fetch the CMS collections and pick which ones to process interactively',
+            exclusive: ['only'],
+        }),
+        shopify: Flags.boolean({
+            description: 'run against a Shopify store (not implemented yet)',
+            exclusive: ['webflow'],
+        }),
+        'site-id': Flags.string({
+            dependsOn: ['webflow'],
+            description: 'Webflow site ID. Prompted for if omitted.',
+        }),
+        skip: Flags.boolean({
+            description: 'leave images that already have alt text alone instead of overwriting them',
+        }),
+        webflow: Flags.boolean({
+            description: 'run against a Webflow site',
+            exclusive: ['shopify'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AltText);
+        if (await this.resolvePlatform(flags) === 'shopify') {
+            this.log(chalk.yellow('Shopify is not implemented yet — nothing to do.'));
+            return;
+        }
+        const auth = {
+            apiKey: flags['api-key'] ?? (await password({ mask: true, message: 'Webflow API token', validate: required })),
+            siteId: flags['site-id'] ?? (await input({ message: 'Webflow site ID', validate: required })),
+        };
+        const host = flags['ollama-host'] ??
+            (await input({ default: DEFAULT_OLLAMA_HOST, message: 'Ollama host', validate: required }));
+        const model = flags['ollama-model'] ?? (await this.pickModel(host));
+        // Compiled here, not at first use, so a broken expression costs nothing.
+        let filter;
+        if (flags.filter) {
+            try {
+                filter = createFilter(flags.filter);
+            }
+            catch (error) {
+                this.error(error.message, { code: '1' });
+            }
+        }
+        // Resolved up front so a bad --only value fails before any transcription.
+        const collections = flags.cms ? await this.pickCollections(auth, flags.select, flags.only) : [];
+        const state = {
+            describe: createDescriber(host, model, filter),
+            failures: [],
+            images: [],
+            limit: flags.limit ?? Number.POSITIVE_INFINITY,
+            skip: flags.skip ?? false,
+            skipped: [],
+            transcribed: 0,
+        };
+        this.log(chalk.dim(`Describing images with ${model} on ${host}`));
+        if (flags.filter)
+            this.log(chalk.dim(`Only images matching: ${flags.filter}`));
+        const started = performance.now();
+        await this.processAssets(auth, state);
+        for (const collection of collections) {
+            if (atLimit(state))
+                break;
+            // eslint-disable-next-line no-await-in-loop
+            await this.processCollection(auth, collection, state);
+        }
+        const totalMs = performance.now() - started;
+        this.report(state, collections.length > 0, totalMs);
+        if (flags['output-stats']) {
+            await this.writeStats(flags['output-stats'], state, model, host, totalMs);
+        }
+    }
+    /**
+     * Describe one image and account for it. Returns undefined when the model or
+     * the download failed — one bad image must not abort a run that may have
+     * hundreds of good ones behind it.
+     */
+    async describe(state, label, url) {
+        const counter = Number.isFinite(state.limit)
+            ? `${state.transcribed + 1}/${state.limit}`
+            : `${state.transcribed + 1}`;
+        this.log(chalk.dim(`  [${counter}] ${label} — ${shortUrl(url)}`));
+        try {
+            const result = await state.describe(url);
+            // Filtered out: no tokens spent, so it doesn't touch the transcribed
+            // count and doesn't spend any of the --limit budget either.
+            if (result.skipped) {
+                state.skipped.push(result.meta);
+                this.log(chalk.dim(`        – filtered out (${formatBytes(result.meta.fileSize)}, ${result.meta.width}x${result.meta.height}, ${result.meta.type})`));
+                return undefined;
+            }
+            const { alt, bytes, meta, ms, tokens } = result;
+            state.transcribed++;
+            state.images.push({ bytes, description: alt, meta, ms, tokens, url });
+            this.log(`        ${chalk.green('✓')} ${alt}`);
+            this.log(chalk.dim(`          ${formatCount(tokens)} tokens · ${formatMs(ms)} · ${formatBytes(bytes)} sent`));
+            return alt;
+        }
+        catch (error) {
+            const reason = error.message;
+            state.failures.push({ reason, url });
+            this.log(chalk.yellow(`        ⚠ skipped: ${reason}`));
+            return undefined;
+        }
+    }
+    /** Which CMS collections this run should walk. */
+    async pickCollections(auth, useSelect, only) {
+        const collections = await getCollections(auth);
+        if (collections.length === 0) {
+            this.log(chalk.yellow('This site has no CMS collections.'));
+            return [];
+        }
+        const label = (collection) => `${collection.displayName} (${collection.slug})`;
+        if (only) {
+            const wanted = only.map((name) => name.trim().toLowerCase());
+            const matches = (collection, name) => collection.displayName.toLowerCase() === name ||
+                collection.singularName.toLowerCase() === name ||
+                collection.slug.toLowerCase() === name;
+            const missing = wanted.filter((name) => !collections.some((collection) => matches(collection, name)));
+            if (missing.length > 0) {
+                this.error(`No CMS collection named ${missing.map((name) => `"${name}"`).join(', ')}. This site has: ${collections
+                    .map((collection) => label(collection))
+                    .join(', ')}.`, { code: '1' });
+            }
+            return collections.filter((collection) => wanted.some((name) => matches(collection, name)));
+        }
+        if (useSelect) {
+            return checkbox({
+                choices: collections.map((collection) => ({ name: label(collection), value: collection })),
+                message: 'Which CMS collections should get alt text?',
+            });
+        }
+        return collections;
+    }
+    /**
+     * Ask which model to use, offering only the vision-capable models the host has
+     * already pulled — a text-only model would happily accept the request and
+     * describe nothing, and a model that isn't pulled would stall the run behind a
+     * silent download.
+     */
+    async pickModel(host) {
+        let models;
+        try {
+            models = await listVisionModels(host);
+        }
+        catch (error) {
+            this.error(`Could not list models on ${host}: ${error.message}`, { code: '1' });
+        }
+        if (models.length === 0) {
+            this.error(`No vision-capable models are pulled on ${host}. Pull one (e.g. "ollama pull qwen3-vl:8b") or pass --ollama-model.`, { code: '1' });
+        }
+        return select({ choices: models, message: 'Which Ollama model should describe the images?' });
+    }
+    /** The site asset library pass. Always runs; --cms only adds work on top of it. */
+    async processAssets(auth, state) {
+        this.log(chalk.bold('\nSite assets'));
+        for await (const asset of getAssets(auth)) {
+            if (atLimit(state))
+                return;
+            // The asset library also holds PDFs, fonts and the like.
+            if (!asset.contentType.startsWith('image/'))
+                continue;
+            if (state.skip && asset.altText)
+                continue;
+            const alt = await this.describe(state, asset.displayName || asset.originalFileName, asset.hostedUrl);
+            if (alt !== undefined)
+                await updateAssetAltText(auth, asset.id, alt);
+        }
+    }
+    async processCollection(auth, collection, state) {
+        this.log(chalk.bold(`\nCollection: ${collection.displayName}`));
+        for await (const item of getCollectionItems(auth, collection.id)) {
+            if (atLimit(state))
+                return;
+            await this.processItem(auth, collection, item, state);
+        }
+    }
+    /**
+     * Fill in every image field on one item, then PATCH the item once. Fields that
+     * didn't change are left out of the payload entirely, and an item with no
+     * changed fields is never PATCHed.
+     */
+    async processItem(auth, collection, item, state) {
+        const fieldData = {};
+        for (const [fieldName, value] of Object.entries(item.fieldData)) {
+            if (atLimit(state))
+                break;
+            if (isImageField(value)) {
+                if (state.skip && value.alt)
+                    continue;
+                // eslint-disable-next-line no-await-in-loop
+                const alt = await this.describe(state, `${collection.displayName} > ${fieldName}`, value.url);
+                if (alt !== undefined)
+                    fieldData[fieldName] = { ...value, alt };
+            }
+            else if (isImagesField(value)) {
+                // A multi-image field has to be written back whole, so every image is
+                // carried over — only the ones we actually described come back changed.
+                const next = [];
+                let changed = false;
+                for (const image of value) {
+                    if (atLimit(state) || (state.skip && image.alt)) {
+                        next.push(image);
+                        continue;
+                    }
+                    // eslint-disable-next-line no-await-in-loop
+                    const alt = await this.describe(state, `${collection.displayName} > ${fieldName}`, image.url);
+                    next.push(alt === undefined ? image : { ...image, alt });
+                    changed ||= alt !== undefined;
+                }
+                if (changed)
+                    fieldData[fieldName] = next;
+            }
+        }
+        if (Object.keys(fieldData).length === 0)
+            return;
+        await updateCollectionItem(auth, collection.id, item.id, fieldData);
+    }
+    /** Totals and averages only — the per-image rows live in the --output-stats file. */
+    report(state, touchedCms, totalMs) {
+        const count = state.images.length;
+        const tokens = sum(state.images.map((image) => image.tokens));
+        const described = sum(state.images.map((image) => image.ms));
+        this.log('');
+        this.log(chalk.green(`✓ ${count} image${count === 1 ? '' : 's'} transcribed in ${formatMs(totalMs)}`));
+        if (count > 0) {
+            this.log(chalk.dim(`  ${formatCount(tokens)} tokens total, ${formatCount(Math.round(tokens / count))} avg`));
+            this.log(chalk.dim(`  ${formatMs(described / count)} avg per image`));
+            this.log(chalk.dim(`  ${formatBytes(sum(state.images.map((image) => image.meta.fileSize)) / count)} avg source size`));
+        }
+        if (state.skipped.length > 0) {
+            const skippedBytes = sum(state.skipped.map((meta) => meta.fileSize));
+            this.log(chalk.dim(`↷ ${state.skipped.length} image${state.skipped.length === 1 ? '' : 's'} skipped by filter`));
+            this.log(chalk.dim(`  ${formatBytes(skippedBytes)} total, ${formatBytes(skippedBytes / state.skipped.length)} avg source size`));
+        }
+        if (state.failures.length > 0) {
+            this.log(chalk.yellow(`⚠ ${state.failures.length} image${state.failures.length === 1 ? '' : 's'} could not be described`));
+        }
+        if (touchedCms) {
+            this.log(chalk.dim('CMS items were written to staging — publish the site in Webflow to make them live.'));
+        }
+    }
+    /** --webflow / --shopify, or ask when neither was given. */
+    async resolvePlatform(flags) {
+        if (flags.shopify)
+            return 'shopify';
+        if (flags.webflow)
+            return 'webflow';
+        return select({
+            choices: [
+                { name: 'Webflow', value: 'webflow' },
+                { description: 'Not implemented yet', name: 'Shopify', value: 'shopify' },
+            ],
+            message: 'Which platform?',
+        });
+    }
+    /**
+     * Write the Markdown report. This runs after everything else, so a run that
+     * gets this far has already written its alt text back to Webflow — failing to
+     * save the report loses the record, not the work, and the message says so.
+     */
+    async writeStats(path, state, model, host, totalMs) {
+        const target = resolve(path);
+        try {
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, buildStatsMarkdown(state, model, host, totalMs), 'utf8');
+        }
+        catch (error) {
+            this.error(`Alt text was written to Webflow, but the stats file could not be saved: ${error.message}`, {
+                code: '1',
+            });
+        }
+        this.log(chalk.dim(`Stats written to ${target}`));
+    }
+}

package/dist/commands/create-project.js

@@ -9,7 +9,7 @@ export default class CreateProject extends Command {
     static args = {
         shop: Args.string({ description: 'Shopify store handle — pulls the live theme from <shop>.myshopify.com (omit to skip)', required: false }),
     };
-    static 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.';
+    static 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.';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
         '<%= config.bin %> <%= command.id %> my-store',
@@ -106,17 +106,60 @@ export default class CreateProject extends Command {
         if (createCode !== 0) {
             this.error('gh repo create failed — see output above', { code: '1' });
         }
+        // gh pointed 'origin' at the URL GitHub returned, which carries the name
+        // the repo was ACTUALLY created under — GitHub normalizes names
+        // server-side ('my client' → 'my-client'). Recover it before forcing SSH
+        // so the remote, the default-branch edit, and the printed link all track
+        // the real repo, not the raw directory name.
+        const originUrl = (await git.raw(['remote', 'get-url', 'origin']).catch(() => '')).trim();
+        const canonicalRepo = /github\.com[/:](.+?)(?:\.git)?$/.exec(originUrl)?.[1] ?? repo;
         // Force SSH so the push authenticates with the user's key, not the
         // create-only token.
-        await git.raw(['remote', 'set-url', 'origin', `git@github.com:${repo}.git`]);
+        await git.raw(['remote', 'set-url', 'origin', `git@github.com:${canonicalRepo}.git`]);
         this.log(chalk.blue("⬆️  Pushing 'production' to origin over SSH…"));
         const pushCode = await run('git', ['push', '-u', 'origin', 'production']);
         if (pushCode === 0) {
-            spawnSync('gh', ['repo', 'edit', repo, '--default-branch', 'production'], { stdio: 'ignore' });
-            this.log(chalk.green(`✅ Created + pushed. origin = git@github.com:${repo}.git`));
+            spawnSync('gh', ['repo', 'edit', canonicalRepo, '--default-branch', 'production'], { stdio: 'ignore' });
+            this.log(chalk.green(`✅ Created + pushed. origin = git@github.com:${canonicalRepo}.git`));
+            // 6. Staging branch cut explicitly from 'production' — HEAD isn't a safe
+            // start point because a pre-existing repo (init step skipped) may be
+            // checked out elsewhere. No checkout, so the working tree stays put.
+            // A pre-existing 'staging' is pushed as-is (force-resetting it could
+            // destroy work), with divergence from production called out instead of
+            // silently published. try/catch so a git failure here can't swallow the
+            // URL line below — the repo exists either way.
+            try {
+                const { all: localBranches } = await git.branchLocal();
+                const stagingExisted = localBranches.includes('staging');
+                if (!stagingExisted) {
+                    await git.raw(['branch', 'staging', 'production']);
+                }
+                this.log(chalk.blue("⬆️  Pushing 'staging' to origin over SSH…"));
+                const stagingPushCode = await run('git', ['push', '-u', 'origin', 'staging']);
+                if (stagingPushCode !== 0) {
+                    this.warn("push of 'staging' failed — create it manually: git push -u origin staging");
+                }
+                else if (stagingExisted) {
+                    this.log(chalk.green("✅ pre-existing 'staging' branch pushed"));
+                    const [stagingSha, productionSha] = (await git.raw(['rev-parse', 'staging', 'production'])).trim().split('\n');
+                    if (stagingSha !== productionSha) {
+                        this.warn("'staging' does not match 'production' — it was pushed at its current commit");
+                    }
+                }
+                else {
+                    this.log(chalk.green("✅ 'staging' branch created + pushed"));
+                }
+            }
+            catch {
+                this.warn("could not create 'staging' — create it manually: git branch staging production && git push -u origin staging");
+            }
         }
         else {
             this.warn(`push failed — check your SSH access to the ${org} org`);
         }
+        // https form, not the SSH remote, and printed even when a push failed (the
+        // repo itself exists by now) — this line is for copy-pasting into Jira
+        // tickets and browsers.
+        this.log(`🔗 GitHub: ${chalk.green(`https://github.com/${canonicalRepo}`)}`);
     }
 }

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

@@ -3,6 +3,7 @@ export default class Workspace extends Command {
     static description: string;
     static examples: string[];
     static flags: {
+        cleanup: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'delete-remote-dir': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         devtools: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'ignore-vcs': import("@oclif/core/interfaces").BooleanFlag<boolean>;
@@ -15,6 +16,21 @@ export default class Workspace extends Command {
     /** Verify this machine can drive the sync before we connect. */
     private preflight;
     private printPlan;
+    /**
+     * Tear down leftovers from a session that dropped before cleaning up (--cleanup).
+     * Terminates this directory's Mutagen sync sessions locally, then reaches the
+     * remote to strip the MCP entries the matching flags imply and, with
+     * --delete-remote-dir, remove the synced dir. devtools/rpc are read for
+     * presence only — their port values are irrelevant to removal.
+     */
+    private runCleanup;
     /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
     private runSsh;
+    /**
+     * Best-effort: reach back to the remote after the session to strip any MCP
+     * config this run registered and, with --delete-remote-dir, remove the synced
+     * dir. No-op when the session left nothing behind to clean. A failure here is
+     * logged, not thrown — the local sync is already torn down by this point.
+     */
+    private teardownRemote;
 }

package/dist/commands/workspace/index.js

@@ -1,8 +1,9 @@
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { spawn } from 'node:child_process';
+import { basename } from 'node:path';
 import { hasLocalShell, parseRpcFlag, RPC_FLAG_EXAMPLES, RPC_FLAG_USAGE, startRpcServer } from '../../lib/rpc.js';
-import { browserDebugInstructions, buildContext, buildMutagenCreateArgs, buildMutagenFlushArgs, buildMutagenTerminateArgs, buildRemoteScript, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, isLocalDebugPortLive, mutagenInstallInstructions, parsePortPair, parseSshTarget, runMutagen, runRemoteCleanup, } from '../../lib/workspace.js';
+import { browserDebugInstructions, buildContext, buildMutagenCreateArgs, buildMutagenFlushArgs, buildMutagenTerminateArgs, buildMutagenTerminateSelectorArgs, buildRemoteScript, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, isLocalDebugPortLive, mutagenInstallInstructions, parsePortPair, parseSshTarget, runMutagen, runRemoteCleanup, slugify, } from '../../lib/workspace.js';
 export default class Workspace extends Command {
     static description = 'Open a remote workspace: two-way sync the current directory to a remote Linux box with Mutagen and drop into a shell there, tearing the sync down on exit.\n\nBoth sides keep a real copy on local disk and only deltas cross the network, so the remote reads files at native speed. Conflicting edits on both ends are flagged rather than silently overwritten; pass --source to auto-resolve them in favour of one side. Mutagen connects the normal direction (this machine → remote over SSH) and auto-deploys its agent to the remote, so no local SSH server, reverse tunnel, or authorized_keys trust is required. You need the Mutagen CLI installed on THIS machine.';
     static examples = [
@@ -15,8 +16,13 @@ export default class Workspace extends Command {
         `<%= config.bin %> <%= command.id %> --ssh user@host --rpc ${RPC_FLAG_EXAMPLES.required}`,
         `<%= config.bin %> <%= command.id %> --ssh user@host --rpc ${RPC_FLAG_EXAMPLES.full}`,
         '<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --rpc 7700 --cleanup',
     ];
     static flags = {
+        cleanup: Flags.boolean({
+            default: false,
+            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/--rpc 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.",
+        }),
         'delete-remote-dir': Flags.boolean({
             default: false,
             description: 'on exit, delete the remote workspace directory instead of leaving the synced copy in place',
@@ -48,6 +54,14 @@ export default class Workspace extends Command {
         const { flags } = await this.parse(Workspace);
         const target = parseSshTarget(flags.ssh);
         const target2 = `${target.user}@${target.host}`;
+        // --cleanup short-circuits everything: no connection, no sync, just tear down
+        // leftovers from a session that dropped before it could clean up. The other
+        // flags are reused for *what* to clean up (devtools/rpc MCP entries, dir), and
+        // any that don't matter here are ignored — so `↑` + ` --cleanup` just works.
+        if (flags.cleanup) {
+            await this.runCleanup(target2, flags);
+            return;
+        }
         const devtools = flags.devtools === undefined ? undefined : parsePortPair(flags.devtools, '--devtools');
         const rpc = flags.rpc === undefined ? undefined : parseRpcFlag(flags.rpc);
         if (devtools && rpc && devtools.remote === rpc.ports.remote) {
@@ -102,24 +116,7 @@ export default class Workspace extends Command {
             await runMutagen(buildMutagenTerminateArgs(ctx.syncName)).catch(() => 1);
             // Reach back to the remote if we left MCP config there to remove, or if we
             // were asked to delete the synced directory.
-            if (ctx.devtools || ctx.rpc || deleteRemoteDir) {
-                const actions = [
-                    ctx.devtools ? 'removing the remote chrome-devtools MCP config' : undefined,
-                    ctx.rpc ? 'removing the remote local-shell MCP config' : undefined,
-                    deleteRemoteDir ? 'deleting the remote dir' : undefined,
-                ].filter(Boolean);
-                this.log(chalk.dim(`${actions.join(' and ')}…`.replace(/^./, (c) => c.toUpperCase())));
-                try {
-                    await runRemoteCleanup(target2, ctx.remoteDir, {
-                        deleteRemoteDir,
-                        removeDevtoolsMcp: Boolean(ctx.devtools),
-                        removeRpcMcp: Boolean(ctx.rpc),
-                    });
-                }
-                catch (error) {
-                    this.log(chalk.yellow(`Could not reach the remote to clean up (${error.message}).`));
-                }
-            }
+            await this.teardownRemote(ctx, target2, deleteRemoteDir);
         }
         this.log('');
         this.log(code === 0
@@ -180,6 +177,51 @@ export default class Workspace extends Command {
         }
         this.log('');
     }
+    /**
+     * Tear down leftovers from a session that dropped before cleaning up (--cleanup).
+     * Terminates this directory's Mutagen sync sessions locally, then reaches the
+     * remote to strip the MCP entries the matching flags imply and, with
+     * --delete-remote-dir, remove the synced dir. devtools/rpc are read for
+     * presence only — their port values are irrelevant to removal.
+     */
+    async runCleanup(target, flags) {
+        if (!hasSshClient()) {
+            this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
+        }
+        const removeDevtoolsMcp = flags.devtools !== undefined;
+        const removeRpcMcp = flags.rpc !== undefined;
+        const deleteRemoteDir = flags['delete-remote-dir'];
+        const { remoteDir } = buildContext({ cwd: process.cwd(), remoteBase: flags['remote-base'] });
+        const slug = slugify(basename(remoteDir));
+        this.log(chalk.bold('Cleaning up workspace'));
+        this.log(`  ${chalk.dim('remote:')}     ${target}`);
+        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.'));
+        }
+        if (removeDevtoolsMcp) {
+            this.log(chalk.dim('Removing any leftover chrome-devtools MCP config on the remote…'));
+        }
+        if (removeRpcMcp) {
+            this.log(chalk.dim('Removing any leftover local-shell MCP config on the remote…'));
+        }
+        if (deleteRemoteDir) {
+            this.log(chalk.dim('Deleting the remote workspace directory…'));
+        }
+        const code = await runRemoteCleanup(target, remoteDir, { deleteRemoteDir, removeDevtoolsMcp, removeRpcMcp });
+        if (code === 0) {
+            this.log(chalk.green('✓ Done.'));
+        }
+        else {
+            this.error(`Remote cleanup ssh session exited with code ${code}.`, { code: '1' });
+        }
+    }
     /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
     runSsh(target, script, ctx) {
         // Reverse tunnels: remote 127.0.0.1:<remote> → this machine's 127.0.0.1:<local>.
@@ -199,4 +241,30 @@ export default class Workspace extends Command {
             child.once('close', (code) => resolve(code ?? 0));
         });
     }
+    /**
+     * Best-effort: reach back to the remote after the session to strip any MCP
+     * config this run registered and, with --delete-remote-dir, remove the synced
+     * dir. No-op when the session left nothing behind to clean. A failure here is
+     * logged, not thrown — the local sync is already torn down by this point.
+     */
+    async teardownRemote(ctx, target, deleteRemoteDir) {
+        if (!ctx.devtools && !ctx.rpc && !deleteRemoteDir)
+            return;
+        const actions = [
+            ctx.devtools ? 'removing the remote chrome-devtools MCP config' : undefined,
+            ctx.rpc ? 'removing the remote local-shell MCP config' : undefined,
+            deleteRemoteDir ? 'deleting the remote dir' : undefined,
+        ].filter(Boolean);
+        this.log(chalk.dim(`${actions.join(' and ')}…`.replace(/^./, (c) => c.toUpperCase())));
+        try {
+            await runRemoteCleanup(target, ctx.remoteDir, {
+                deleteRemoteDir,
+                removeDevtoolsMcp: Boolean(ctx.devtools),
+                removeRpcMcp: Boolean(ctx.rpc),
+            });
+        }
+        catch (error) {
+            this.log(chalk.yellow(`Could not reach the remote to clean up (${error.message}).`));
+        }
+    }
 }