fss-link 1.6.12 → 1.7.6

package/docs/README.md

@@ -171,14 +171,15 @@ Reference files directly in your message with `@`:
 
 ## Testing
 
-**Do not run `npm test` from the project root.** It launches vitest across all workspaces in parallel (256+ test files) and will consume all available system memory. See [VITEST-SAFETY.md](../VITEST-SAFETY.md) for safe testing methods and emergency kill procedures.
+Full workspace test suites are safe with the `**/dist/**` excludes in all vitest configs. The historical OOM crash was caused by vitest picking up duplicate compiled `.js` test files from `packages/*/dist/`; this has been fixed. See [VITEST-SAFETY.md](../VITEST-SAFETY.md) for full guidance and emergency kill procedures.
 
 ```bash
-# Safe: run individual test files
-npx vitest run packages/cli/src/config/database.test.ts
-
-# Safe: run one workspace
+# Run all tests for a workspace
 npm run test --workspace=packages/cli
+npm run test --workspace=packages/core
+
+# Run a single test file
+npx vitest run packages/cli/src/config/database.test.ts
 ```
 
 ## Documentation

package/docs/TOOLS.md

@@ -148,6 +148,10 @@ Fetches a URL and returns its content. Handles HTML (extracted as readable text)
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `url` | string | URL to fetch |
+| `prompt` | string | Instructions for what to extract from the page |
+| `include_images` | boolean | When true, extract and return image URLs, alt text, and context found on the page |
+
+For persistent research with file output, use `web_scraper` instead.
 
 ### web_search
 
@@ -156,9 +160,12 @@ Searches the web using a search engine API.
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `query` | string | Search query |
-| `limit` | integer | Maximum results (optional) |
+| `max_results` | integer | Maximum results to return (1–20, default 5) |
+| `search_depth` | string | `"basic"` (fast, default) or `"advanced"` (AI-powered, costs more) |
+
+Requires a search API key (Tavily or Brave Search — configured automatically, Tavily preferred).
 
-Requires a search API key (Tavily or similar) configured via `--tavily-api-key` or environment variable.
+For persistent research with file output, use `web_scraper` instead.
 
 ### fetch_image
 
@@ -185,16 +192,182 @@ Specialized parsers for structured documents. These extract text, tables, metada
 
 | Tool | Formats | What It Extracts |
 |------|---------|-----------------|
-| `read_pdf` | PDF | Text, page structure, metadata |
-| `read_excel` | XLSX, XLS, CSV | Sheets, cells, formulas, structure |
-| `read_word` | DOCX | Text, headings, tables, styles |
-| `read_email` | EML, MSG | Headers, body, attachments metadata |
+| `pdf_parser` | PDF | Text, page structure, metadata, visual page rendering via `view_page` |
+| `excel_parser` | XLSX, XLS, CSV | Sheets, cells, formulas, structure, multi-sheet processing |
+| `word_parser` | DOCX, DOC, MD | Text, headings, tables, styles, embedded images |
+| `email_parser` | EML, MSG, MBOX | Headers, body, attachments metadata, multi-message .mbox |
 | `read_data` | CSV, JSON, YAML, XML, TOML | Parsed data with schema inference |
 
+**pdf_parser extras:**
+- `mode="preview"` — light deterministic overview (page count, metadata, first 40 lines) without dumping body text
+- `view_page=N` — renders a specific page as an image for visual inspection (sees layout, tables, diagrams, signatures)
+- `pages=[3, 5, 7]` or `page_range={start, end}` — extract specific pages with boundary detection confidence labels
+
+**excel_parser extras:**
+- `read_all_sheets` — read all sheets or just the first one
+- `range="A1:C10"` — extract a specific cell range
+- `include_formatting` — include cell formatting information
+- `preserve_formulas` — preserve Excel formulas in output
+
+**word_parser extras:**
+- `extract_images` — extract embedded images from the document
+- `preserve_formatting` — preserve document formatting
+
+**email_parser extras:**
+- `max_messages` — maximum number of messages to parse from .mbox files (default: 50, max: 500)
+- `prefer_html` — prefer HTML body over plain text when both are present
+
+---
+
+## Audio
+
+### read_audio
+
+Read an audio file and return its metadata and/or a segment-level transcript.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `absolute_path` | string | Absolute path to the audio file (mp3, wav, flac, ogg, m4a, etc.) |
+| `mode` | string | `metadata` for format/tag info only, `transcribe` for transcript only, or `full` (default) for both. |
+
+- Extracts duration, sample rate, channels, codec, bitrate, and embedded tags (title, artist, album, year, genre)
+- Transcription requires a Whisper-compatible server at `FSS_WHISPER_URL` (default `localhost:11453`, timeout 120s via `FSS_WHISPER_TIMEOUT`)
+- Returns segment-level transcript with timestamps and derived silence regions (gaps ≥ 0.5s)
+- Supports abort/cancellation during transcription
+
+---
+
+## Image Generation & Editing
+
+### generate_image
+
+Create new images from text descriptions via ComfyUI (FLUX.2 Klein). Single or batch mode. Upscaling is applied by generating at full resolution.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prompt` | string | Image generation prompt (single mode). Describe the image you want in detail. |
+| `batch_content` | string | Markdown batch content (batch mode). Use `###` headings as prompts, optional bullet overrides below each (seed, steps, negative_prompt, etc). |
+| `negative_prompt` | string | What to avoid in the image (single mode only). |
+| `width` | integer | Base width before upscaling (default: 1024). |
+| `height` | integer | Base height before upscaling (default: 1024). |
+| `steps` | integer | Sampling steps (default: 20 for 9b model). Higher = more detail, slower. |
+| `cfg_scale` | number | CFG scale (default: 1.0 for FLUX.2). Lower = more creative, higher = follows prompt more strictly. |
+| `seed` | integer | Random seed for reproducibility (-1 = random). |
+| `model` | string | Workflow preset: `9b` (FLUX.2 Klein 9B, best quality), `4b` (FLUX.2 Klein 4B, faster), `flux-q8` (quantized 8-bit). Default: `9b`. |
+| `output_dir` | string | Output directory. Defaults to current working directory. |
+| `output_filename` | string | Custom filename for the output image. Auto-generated if omitted. |
+
+### edit_image
+
+Edit an existing image using ComfyUI Qwen-Edit workflow with instruction-based modifications and optional reference images. ALWAYS creates a NEW output file — the original image is NEVER modified or overwritten.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `input_image` | string | Input image file path to edit (required). |
+| `prompt` | string | Edit instruction describing what to change (required). Be specific about what to keep and what to change. |
+| `reference_images` | array | Optional reference image paths for style or character consistency. Can be repeated up to 3×. |
+| `steps` | integer | Sampling steps (default: 4 for Lightning; 8 for more detail). |
+| `cfg` | number | CFG scale (default: 1.0 — Lightning works at 1.0). |
+| `seed` | integer | Random seed for reproducibility (-1 = random). |
+| `output_dir` | string | Output directory for the new edited image. Defaults to current working directory. |
+| `output_filename` | string | Custom filename for the output image. Auto-generated if omitted. |
+
+---
+
+## Web Scraping
+
+### web_scraper
+
+Scrape web pages, search the web, or crawl sites. Saves extracted content to files.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `operation` | string | Type of operation: `"scrape"` (direct URLs), `"crawl"` (recursive), `"search"` (search-driven), `"summarise"` (synthesise previous scrapes with LLM). |
+| `sources` | array | List of URLs or file paths to process (required for scrape/crawl operations). |
+| `searchQuery` | string | Search query for search-driven scraping (required for search operation). |
+| `outputDir` | string | Directory where scraped content will be saved (default: `~/.fss-link/scraper/`). |
+| `maxResults` | number | Maximum number of search results to process (for search operation, default: 10, max: 50). |
+| `maxDepth` | number | Maximum crawl depth for "crawl" operation (default: 2, max: 10). |
+| `maxPages` | number | Maximum pages to crawl (budget cap, default: 20, max: 100). |
+| `topic` | string | Filter results by topic relevance (keyword matching). Pages not relevant to this topic are dropped. |
+| `minQuality` | number | Minimum content quality score 0–1 (default: 0.3). Drops empty/boilerplate pages. |
+| `collectMedia` | boolean | Collect images from scraped pages. Downloads to media/ subfolder. |
+| `framing` | string | Perspective/lens for synthesis (summarise operation only). Not a question — a framing directive that guides how sources are synthesised. |
+
+- Supports topic filtering, quality thresholding, search result ranking
+- Media collection (opt-in) downloads images from scraped pages
+- Rate limiting, robots.txt compliance built in
+- Uses Brave/Tavily search APIs when available
+
+---
+
+## Structured Data Inspection
+
+### inspect_structured
+
+Inspect structured data files (JSON, JSONL/NDJSON, YAML, TOML, XML, CSV, TSV). Returns the file's shape — keys, types, array lengths, depth — with addressable paths, instead of dumping raw content. Far cheaper than `read_file` for large structured files where syntax noise overwhelms the actual data.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `absolute_path` | string | Absolute path to the structured data file. |
+| `mode` | string | `"overview"` (default) returns the structural shape with addressable paths. `"extract"` returns one subtree, located by `path`. |
+| `path` | string | Path to extract (extract mode only). Dot/bracket notation, e.g. `"Properties.Children[0]"` or `'items[0]["name"]'`. |
+| `max_depth` | integer | Overview only — descend at most this many levels (default 4). |
+| `max_array_samples` | integer | Overview only — number of array elements to expand inline (default 3). |
+
+Supported formats: `.json`, `.jsonl`, `.ndjson`, `.yaml`, `.yml`, `.toml`, `.xml`, `.csv`, `.tsv`
+
 ---
 
 ## Agent Utilities
 
+### wait_for
+
+Wait for a long-running background process to complete by polling for one of two completion signals: a file appearing on disk, or a regex matching in a log file.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `wait_for_file` | object | Wait for a file to appear at a given absolute path. Set `stable_for_seconds` to require the file's size AND modification time to stop changing before counting as complete. |
+| `wait_for_log_match` | object | Wait for a regex to match somewhere in the tail of a log file. Use when the output file appears mid-process or has unpredictable size. |
+| `max_total_seconds` | number | Hard cap on total wait time, in seconds. Minimum 2, maximum 3600 (1 hour). |
+| `interval_seconds` | number | Seconds between checks. Default 5, minimum 2. |
+| `progress_pattern` | string | Optional regex for live progress display. If not set, the tool auto-detects common patterns (segments, percent, step counter, timing). |
+| `progress_log_path` | string | Optional path for progress tracking. Defaults to `wait_for_log_match.log_path`. |
+
+**`wait_for_file` properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | string | Absolute path to the target file. |
+| `stable_for_seconds` | number | File must exist and its size AND mtime must be unchanged for this many seconds. |
+
+**`wait_for_log_match` properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `log_path` | string | Absolute path to the log file. |
+| `pattern` | string | JavaScript regex matched against the last 64 KB of the log. Anchor tightly with `^` and `$`. |
+| `min_matches` | number | Minimum matches required before declaring done. Default 1. Use >1 for noisy logs. |
+| `anchored_to_end` | number | Require the match to appear in the last N lines. Ensures completion signal is at the END of output. |
+
+**Auto-progress detection:** When `progress_pattern` is not set, the tool auto-detects patterns from the log: segment counters (`158/162 segments`), percentages (`75%`), step counters (`Step 15/20`), timing (`12.3s / 45s`), and generic counters (`42 of 100`).
+
+**ETA estimation:** The tool tracks progress snapshots and displays estimated time remaining (e.g., `~3m 12s remaining`) based on the current progress rate.
+
+**Progress delta:** Shows how progress changed since last check (e.g., `158/162 → 159/162`).
+
+**Example:** Wait for a build log to show "Build completed successfully" in the last 5 lines:
+
+```
+wait_for_log_match:
+  log_path: /path/to/build.log
+  pattern: "^Build completed successfully$"
+  min_matches: 1
+  anchored_to_end: 5
+max_total_seconds: 300
+interval_seconds: 5
+```
+
 ### workplan_update (formerly `todo_write`)
 
 Manages a structured work plan for the current session. Helps the agent track multi-step work.
@@ -214,6 +387,33 @@ Usage guidelines:
 
 Reads and writes to the agent's persistent memory system. Stores user preferences, project context, and learned patterns across sessions.
 
+### enter_worktree
+
+Creates an isolated git worktree at `<projectRoot>/.fss-link/worktrees/<slug>` and returns its absolute path so subsequent file edits, shell commands, and other tools can operate inside it.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Optional slug (letters, digits, dot, underscore, hyphen; max 64 chars). Auto-generated when omitted. |
+
+- Creates a new branch `<prefix><slug>` based on the current branch
+- The worktree persists across the session until `exit_worktree` is invoked
+- Multiple agents can work in parallel in different worktrees without interfering with each other or the main checkout
+- **Only invoke when the user explicitly asks for a worktree** — not for routine bug fixes or feature work
+
+### exit_worktree
+
+Exits a worktree previously created by `enter_worktree`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Slug of the worktree to exit (must match the name used in `enter_worktree`). |
+| `action` | string | `"keep"` preserves the worktree on disk; `"remove"` deletes it and its branch. |
+| `discard_changes` | boolean | When `action="remove"`, must be true to delete a worktree with uncommitted changes. |
+
+- `action='keep'` — preserves the worktree directory and branch on disk so it can be revisited later
+- `action='remove'` — deletes the worktree directory and branch. Refuses to run if the worktree contains uncommitted changes unless `discard_changes: true` is set
+- Only invoke when the user explicitly asks to leave or clean up a worktree
+
 ---
 
 ## TTS (Text-to-Speech)
@@ -230,11 +430,31 @@ Synthesizes speech from text using the FSS-TTS server.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `text` | string | Text to speak |
-| `voice` | string | Voice name (Bella, Emma, George, Lewis, Sarah, Michael, Adam, Isabella, Nicole) |
+| `text` | string | Text to speak (max 5000 characters) |
+| `voice` | string | Voice personality to use (Bella, Emma, George, Lewis, Sarah, Michael, Adam, Isabella, Nicole). Default: Bella. |
+| `wait_for_playback` | boolean | If true, block until the TTS server has finished playing the audio before returning. Default false (fire-and-forget). Essential in non-interactive (`-p`) mode. |
 
 Requires the FSS-TTS server running at `FSS_TTS_URL` (default `localhost:11450`).
 
+### tts_narrate
+
+Play multiple voice segments sequentially — Bella says the intro, Emma continues, George adds a comment, etc. Each segment plays fully before the next begins. Use for multi-voice explanations, handoffs between speakers, or conversational narration.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `segments` | array | Ordered list of `{voice, text}` objects to play sequentially |
+
+Each segment:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `voice` | string | Voice name (Bella, Emma, George, Lewis, Sarah, Michael, Adam, Isabella, Nicole) |
+| `text` | string | Text for this segment (max 1000 chars) |
+
+- Minimum 2 segments, maximum 10
+- Each segment plays fully before the next begins
+- Supports abort/cancellation mid-sequence
+
 ---
 
 ## MCP (Model Context Protocol)
@@ -264,5 +484,5 @@ All file-modifying tools (edit, write_file) enforce:
 - **Workspace boundary checks** — can't write outside your project directory
 - **Diff previews** — see exactly what will change before approving
 - **Confirmation prompts** — unless in auto_edit or YOLO mode
-- **Tool result size limits** — outputs exceeding 25k characters are truncated to prevent context overflow
+- **Tool result size limits** — shell output capped at 32 KB, read-file at 4,000 lines, core tool results at 40K chars to prevent context overflow
 - **Error messages include the failed path** — so the agent knows exactly what went wrong and doesn't retry blindly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fss-link",
-  "version": "1.6.12",
+  "version": "1.7.6",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -13,7 +13,7 @@
     "url": "git+https://github.com/FSSCoding/fss-link.git"
   },
   "config": {
-    "sandboxImageUri": "ghcr.io/fsscoding/fss-link:1.6.12"
+    "sandboxImageUri": "ghcr.io/fsscoding/fss-link:1.7.5"
   },
   "scripts": {
     "start": "node scripts/start.js",
@@ -44,8 +44,8 @@
     "format": "prettier --experimental-cli --write .",
     "typecheck": "npm run typecheck --workspaces --if-present",
     "preflight": "npm run clean && npm ci && npm run format && npm run lint:ci && npm run build && npm run typecheck && npm run test:ci",
-    "prepare": "npm run bundle",
-    "postinstall": "node scripts/postinstall-message.js",
+    "postinstall": "node scripts/postinstall-message.cjs",
+    "prepare": "patch-package || true",
     "prepare:package": "node scripts/prepare-package.js",
     "release:version": "node scripts/version.js",
     "telemetry": "node scripts/telemetry.js",
@@ -71,7 +71,7 @@
     "scripts/install-linux.sh",
     "scripts/install-macos.sh",
     "scripts/install-windows.ps1",
-    "scripts/postinstall-message.js",
+    "scripts/postinstall-message.cjs",
     "scripts/prebundle-sync-dist.js",
     "scripts/prepare-package.js",
     "scripts/sandbox_command.js",
@@ -82,59 +82,83 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@types/fs-extra": "^11.0.4",
-    "@types/marked": "^5.0.2",
-    "@types/micromatch": "^4.0.9",
-    "@types/mime-types": "^3.0.1",
-    "@types/minimatch": "^5.1.2",
-    "@types/mock-fs": "^4.13.4",
-    "@types/qrcode-terminal": "^0.12.2",
-    "@types/shell-quote": "^1.7.5",
-    "@types/sql.js": "^1.4.9",
-    "@types/turndown": "^5.0.5",
-    "@types/jsdom": "^21.1.7",
-    "@types/mozilla__readability": "^0.4.2",
-    "@types/update-notifier": "^6.0.8",
-    "@types/uuid": "^10.0.0",
-    "@vitest/coverage-v8": "^4.0.0",
+    "@types/ink-testing-library": "^1.0.4",
+    "@vitest/coverage-v8": "^4.1.8",
     "concurrently": "^9.2.0",
     "cross-env": "^7.0.3",
-    "esbuild": "^0.25.0",
     "eslint": "^9.24.0",
     "eslint-config-prettier": "^10.1.2",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-license-header": "^0.8.0",
+    "eslint-plugin-no-only-tests": "^3.4.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-vitest": "^0.5.4",
     "globals": "^16.0.0",
+    "ink": "^6.8.0",
+    "ink-testing-library": "^4.0.0",
     "json": "^11.0.0",
     "lodash": "^4.17.21",
-    "memfs": "^4.17.2",
+    "memfs": "^4.57.3",
     "mnemonist": "^0.40.3",
     "mock-fs": "^5.5.0",
-    "msw": "^2.10.4",
+    "msw": "^2.14.6",
+    "patch-package": "^8.0.1",
     "prettier": "^3.5.3",
+    "react": "^19.2.6",
     "react-devtools-core": "^7.0.1",
+    "react-dom": "^19.2.6",
     "tsx": "^4.20.3",
-    "typescript-eslint": "^8.30.1",
-    "vitest": "^4.0.0"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.30.1"
   },
   "dependencies": {
     "@google/genai": "1.13.0",
     "@iarna/toml": "^2.2.5",
     "@modelcontextprotocol/sdk": "^1.15.1",
     "@mozilla/readability": "^0.6.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/command-exists": "^1.2.3",
+    "@types/dompurify": "^3.0.5",
+    "@types/express": "^5.0.3",
+    "@types/fs-extra": "^11.0.4",
+    "@types/html-to-text": "^9.0.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/jsdom": "^21.1.7",
+    "@types/marked": "^5.0.2",
+    "@types/micromatch": "^4.0.9",
+    "@types/mime-types": "^3.0.1",
+    "@types/minimatch": "^5.1.2",
+    "@types/mock-fs": "^4.13.4",
+    "@types/mozilla__readability": "^0.4.2",
+    "@types/node": "^25.9.1",
+    "@types/pdf-parse": "^1.1.5",
+    "@types/picomatch": "^4.0.3",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@types/shell-quote": "^1.7.5",
+    "@types/sql.js": "^1.4.9",
+    "@types/turndown": "^5.0.6",
+    "@types/update-notifier": "^6.0.8",
+    "@types/uuid": "^10.0.0",
+    "@types/vscode": "^1.99.0",
+    "@types/ws": "^8.5.10",
+    "@types/xml2js": "^0.4.14",
+    "@types/yargs": "^17.0.33",
+    "@types/yauzl": "^2.10.3",
     "axios": "^1.11.0",
     "chalk": "^5.3.0",
     "cheerio": "^1.1.2",
     "command-exists": "^1.2.9",
     "diff": "^9.0.0",
     "dotenv": "^17.1.0",
+    "esbuild": "^0.25.0",
     "exceljs": "^4.4.0",
     "fs-extra": "^11.3.1",
     "glob": "^13.0.6",
     "highlight.js": "^11.11.1",
-    "ink": "^6.1.1",
     "ink-big-text": "^2.0.0",
     "ink-gradient": "^3.0.0",
     "ink-link": "^4.1.0",
@@ -144,13 +168,13 @@
     "jsdom": "^27.0.0",
     "lowlight": "^3.3.0",
     "mime-types": "^3.0.1",
+    "music-metadata": "^11.12.3",
     "open": "^10.1.2",
     "p-limit": "^7.1.1",
     "pdf-to-img": "^6.0.0",
     "proper-lockfile": "^4.1.2",
+    "punycode.js": "^2.3.1",
     "qrcode-terminal": "^0.12.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
     "read-package-up": "^11.0.0",
     "sharp": "^0.34.4",
     "shell-quote": "^1.8.3",
@@ -164,21 +188,13 @@
     "turndown": "^7.2.0",
     "turndown-plugin-gfm": "^1.0.2",
     "undici": "^7.10.0",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7",
     "xml2js": "^0.6.0",
     "yargs": "^17.7.2",
     "yauzl": "^3.0.0",
     "zod": "^4.0.0"
   },
-  "overrides": {
-    "archiver": "^8.0.0",
-    "unzipper": "^0.12.3",
-    "fast-csv": "^5.0.7",
-    "encoding-sniffer": "^1.0.2",
-    "gaxios": "^7.1.4",
-    "exceljs": {
-      "uuid": "^9.0.1"
-    }
-  },
   "optionalDependencies": {
     "@lydell/node-pty": "1.1.0",
     "@lydell/node-pty-darwin-arm64": "1.1.0",

package/scripts/check-publish.js

@@ -28,6 +28,10 @@ if (process.cwd().includes('packages')) {
 
 // Check 2: Bundle exists
 const bundlePath = path.join(projectRoot, 'bundle/fss-link.js');
+// The bin (bundle/fss-link.js) is a tiny bootstrap; the real code lives in
+// bundle/fss-link-main.js, which the bootstrap dynamically imports. Size and
+// version-content checks must target the main bundle, not the bootstrap.
+const mainBundlePath = path.join(projectRoot, 'bundle/fss-link-main.js');
 if (!fs.existsSync(bundlePath)) {
   console.error('❌ ERROR: bundle/fss-link.js not found');
   console.error('   Run: npm run bundle\n');
@@ -56,23 +60,30 @@ if (!fs.existsSync(bundlePath)) {
     console.log('✅ Bundle has correct shebang');
   }
 
-  // Check 5: Bundle size is reasonable (> 1MB)
-  const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
-  if (stats.size < 1024 * 1024) {
-    console.error(`❌ ERROR: Bundle suspiciously small (${sizeMB} MB)`);
-    console.error('   Expected: > 1 MB');
-    console.error('   This may indicate an incomplete build\n');
+  // Check 5: Main bundle exists and is a reasonable size (> 1MB)
+  if (!fs.existsSync(mainBundlePath)) {
+    console.error('❌ ERROR: bundle/fss-link-main.js not found');
+    console.error('   The bootstrap bin imports it — Run: npm run bundle\n');
     errors++;
   } else {
-    console.log(`✅ Bundle size reasonable (${sizeMB} MB)`);
+    const mainStats = fs.statSync(mainBundlePath);
+    const sizeMB = (mainStats.size / (1024 * 1024)).toFixed(2);
+    if (mainStats.size < 1024 * 1024) {
+      console.error(`❌ ERROR: Main bundle suspiciously small (${sizeMB} MB)`);
+      console.error('   Expected: > 1 MB');
+      console.error('   This may indicate an incomplete build\n');
+      errors++;
+    } else {
+      console.log(`✅ Main bundle size reasonable (${sizeMB} MB)`);
+    }
   }
 }
 
 // Check 6: Version in bundle matches package.json
 const pkgPath = path.join(projectRoot, 'package.json');
 const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-if (fs.existsSync(bundlePath)) {
-  const bundleContent = fs.readFileSync(bundlePath, 'utf8');
+if (fs.existsSync(mainBundlePath)) {
+  const bundleContent = fs.readFileSync(mainBundlePath, 'utf8');
   // Check for version in various formats: "version":"1.2.8", version = "1.2.8", etc.
   const versionPatterns = [
     `"version":"${pkg.version}"`,

package/scripts/copy_bundle_assets.js

@@ -17,7 +17,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { copyFileSync, existsSync, mkdirSync } from 'fs';
+import { copyFileSync, existsSync, mkdirSync, chmodSync } from 'fs';
 import { dirname, join, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { glob } from 'glob';
@@ -31,6 +31,15 @@ if (!existsSync(bundleDir)) {
   mkdirSync(bundleDir);
 }
 
+// Install the bootstrap as the published bin (bundle/fss-link.js). It forces
+// React's production build, then dynamically imports the esbuild output
+// (bundle/fss-link-main.js). See fss-docs/DESIGN-NOTE-react-production-mode.md.
+const bootstrapSrc = join(root, 'packages', 'cli', 'bootstrap.mjs');
+const bootstrapDest = join(bundleDir, 'fss-link.js');
+copyFileSync(bootstrapSrc, bootstrapDest);
+chmodSync(bootstrapDest, 0o755);
+console.log('Bootstrap bin installed at bundle/fss-link.js');
+
 // Find and copy all .sb files from packages to the root of the bundle directory
 const sbFiles = glob.sync('packages/**/*.sb', { cwd: root });
 for (const file of sbFiles) {

package/scripts/{postinstall-message.js → postinstall-message.cjs}

@@ -7,6 +7,24 @@
 // FSS Link postinstall guidance — printed after npm install -g fss-link
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
+
+// Patch tr46 to use punycode.js instead of the deprecated built-in punycode module.
+// This eliminates the Node 22 DEP0040 deprecation warning from the
+// jsdom → whatwg-url → tr46 dependency chain.
+try {
+  const tr46Path = path.join(__dirname, '..', 'node_modules', 'tr46', 'index.js');
+  if (fs.existsSync(tr46Path)) {
+    const content = fs.readFileSync(tr46Path, 'utf8');
+    if (content.includes('require("punycode/")')) {
+      fs.writeFileSync(tr46Path, content.replace('require("punycode/")', 'require("punycode.js")'));
+    }
+  }
+} catch {
+  // Non-fatal — tr46 may not be installed or patch already applied
+}
+
 const lines = [
   '',
   '╔════════════════════════════════════════╗',

package/scripts/version.js

@@ -36,15 +36,22 @@ if (!versionType) {
 // 2. Bump the version in the root and all workspace package.json files.
 run(`npm version ${versionType} --no-git-tag-version --allow-same-version`);
 
-// 3. Get all workspaces and filter out the one we don't want to version.
+// 3. Get all workspaces and filter out the ones we don't want to version.
 const workspacesToExclude = [];
-const lsOutput = JSON.parse(
-  execSync('npm ls --workspaces --json --depth=0').toString(),
-);
-const allWorkspaces = Object.keys(lsOutput.dependencies || {});
-const workspacesToVersion = allWorkspaces.filter(
-  (wsName) => !workspacesToExclude.includes(wsName),
-);
+const rootPkg = readJson(resolve(process.cwd(), 'package.json'));
+const workspaceDirs = rootPkg.workspaces || [];
+const workspacesToVersion = [];
+for (const dir of workspaceDirs) {
+  const pkgPath = resolve(process.cwd(), dir, 'package.json');
+  try {
+    const wsPkg = readJson(pkgPath);
+    if (!workspacesToExclude.includes(wsPkg.name)) {
+      workspacesToVersion.push(wsPkg.name);
+    }
+  } catch {
+    // Skip directories without package.json
+  }
+}
 
 for (const workspaceName of workspacesToVersion) {
   run(
@@ -78,6 +85,7 @@ if (cliPackageJson.config?.sandboxImageUri) {
 }
 
 // 8. Run `npm install` to update package-lock.json.
-run('npm install');
+// --ignore-scripts prevents the prepare hook (bundle) from firing before deps exist.
+run('npm install --ignore-scripts');
 
 console.log(`Successfully bumped versions to v${newVersion}.`);