@firenet-designs/fnd-cli 2.3.3 → 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,9 +3,12 @@ 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>;
         'remote-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        rpc: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         source: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         ssh: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
@@ -13,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;
 }