fss-link 1.9.2 → 1.9.4

package/bundle/worktrees/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: worktrees
+description: >
+  Git worktrees for isolated parallel development across agents.
+  Use when starting feature work that needs isolation, before executing
+  plans that risk breaking the main branch, or when another agent is
+  already working in the project.
+category: workflow
+triggers: [worktree, isolated, parallel, branch workspace]
+version: 1
+---
+
+# Git Worktrees — Isolated Parallel Development
+
+**Use when:** Multiple agents need to work on different features simultaneously without interfering with each other.
+
+## When to Use
+
+- Starting feature work that needs isolation from the current workspace
+- Before executing implementation plans that risk breaking the main branch
+- When another agent is already working in the project
+
+## When NOT to Use
+
+- The user simply asks to fix a bug or implement a feature — those belong to the regular working directory
+- You are already inside a worktree
+- The project is not a git repository
+
+## Creating a Worktree
+
+Use the `enter_worktree` tool:
+
+```
+enter_worktree({ name: "fix-auth-bug" })
+```
+
+Returns:
+- `worktreePath` — absolute path (e.g., `/path/to/project/.fss-link/worktrees/fix-auth-bug`)
+- `branch` — git branch name (e.g., `fss-link-fix-auth-bug`)
+
+**CRITICAL:** Every tool call must use the full absolute `worktreePath`. Never use relative paths.
+
+```bash
+# ✅ CORRECT — absolute path
+write_file({ path: "/path/to/project/.fss-link/worktrees/fix-auth-bug/src/auth.ts", ... })
+
+# ❌ WRONG — relative path modifies the MAIN checkout
+write_file({ path: "src/auth.ts", ... })
+```
+
+## Verifying You Are in the Worktree
+
+```bash
+pwd  # Should show .../.fss-link/worktrees/<slug>/
+git branch --show-current  # Should show fss-link-<slug>
+```
+
+## Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+cd /path/to/project/.fss-link/worktrees/fix-auth-bug && npm install
+cd /path/to/project/.fss-link/worktrees/fix-auth-bug && cargo build
+cd /path/to/project/.fss-link/worktrees/fix-auth-bug && pip install -r requirements.txt
+```
+
+## Exiting a Worktree
+
+```
+exit_worktree({ name: "fix-auth-bug", action: "keep" })      # Work in progress
+exit_worktree({ name: "fix-auth-bug", action: "remove" })    # Work committed
+exit_worktree({ name: "fix-auth-bug", action: "remove", discard_changes: true })  # Discard system metadata
+exit_worktree({ name: "fix-auth-bug", action: "remove", discard_changes: true, confirm_destruction: true })  # Discard everything
+```
+
+⚠️ **WARNING:** `discard_changes: true` is a destructive action. It will permanently delete all untracked content in the worktree.
+
+- Without `confirm_destruction`: the tool cleans up its own artifacts (.fss-link/) and lists any remaining user files. You must decide whether to delete them manually or confirm destruction.
+- With `confirm_destruction: true`: ALL untracked content is destroyed, including user files. Use only when you are certain no valuable untracked content exists.
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Need isolated workspace | `enter_worktree({ name: "feature-name" })` |
+| Already in a worktree | Do NOT call enter_worktree again |
+| Done, work in progress | `exit_worktree({ name, action: "keep" })` |
+| Done, work committed | `exit_worktree({ name, action: "remove" })` |
+| Done, discard system metadata only | `exit_worktree({ name, action: "remove", discard_changes: true })` |
+| Done, discard everything | `exit_worktree({ name, action: "remove", discard_changes: true, confirm_destruction: true })` |
+
+## Common Mistakes
+
+1. **Using relative paths** — Always use full `worktreePath` for every tool call
+2. **Creating nested worktrees** — Check path first; if it contains `.fss-link/worktrees/`, you're already in one
+3. **Running `git worktree add` manually** — Always use the `enter_worktree` tool
+4. **Removing with uncommitted changes** — Commit or stash first, or use `discard_changes: true` (system metadata only) or `confirm_destruction: true` (everything)
+
+## Global Flags
+
+N/A — this is a workflow skill, not a CLI tool.
+
+---
+
+*This skill is part of the FSS Parsers collection.*
+
+**References:**
+- Full procedural guide → `references/capabilities.md`

package/docs/TOOLS.md

@@ -408,10 +408,13 @@ Exits a worktree previously created by `enter_worktree`.
 |-----------|------|-------------|
 | `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. |
+| `discard_changes` | boolean | When `action="remove"`, bypasses the dirty-worktree check. Automatically cleans up system metadata (.fss-link/). Lists remaining user files. |
+| `confirm_destruction` | boolean | When `action="remove"` and `discard_changes=true`, destroys ALL untracked content including user files. Requires `discard_changes=true`. |
 
 - `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
+- `discard_changes: true` — cleans up system metadata (.fss-link/). If other untracked files remain, lists them and refuses to proceed unless `confirm_destruction: true`
+- `confirm_destruction: true` — destroys ALL untracked content. Requires `discard_changes: true`. Use with caution.
 - Only invoke when the user explicitly asks to leave or clean up a worktree
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fss-link",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "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.9.2"
+    "sandboxImageUri": "ghcr.io/fsscoding/fss-link:1.9.4"
   },
   "scripts": {
     "start": "node scripts/start.js",
@@ -95,6 +95,7 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-vitest": "^0.5.4",
+    "fast-check": "^4.9.0",
     "globals": "^16.0.0",
     "ink": "^6.8.0",
     "ink-testing-library": "^4.0.0",
@@ -189,7 +190,7 @@
     "turndown": "^7.2.0",
     "turndown-plugin-gfm": "^1.0.2",
     "undici": "^7.10.0",
-    "vite": "^8.0.14",
+    "vite": "^6.3.5",
     "vitest": "^4.1.7",
     "xml2js": "^0.6.0",
     "yargs": "^17.7.2",

package/scripts/copy_bundle_assets.js

@@ -46,4 +46,22 @@ for (const file of sbFiles) {
   copyFileSync(join(root, file), join(bundleDir, basename(file)));
 }
 
+// Copy bundled default skills (SKILL.md files) alongside the bundled JS.
+// bundledSkills.ts reads these via `path.join(__dirname, './<dir>/SKILL.md')`
+// relative to the running bundle/fss-link-main.js, so the source tree layout
+// (packages/core/src/bundled-skills/<dir>/SKILL.md) must be mirrored here as
+// bundle/<dir>/SKILL.md — esbuild only bundles JS, it never copies these.
+const skillFiles = glob.sync('packages/core/src/bundled-skills/**/SKILL.md', {
+  cwd: root,
+});
+for (const file of skillFiles) {
+  const rel = file.replace('packages/core/src/bundled-skills/', '');
+  const dest = join(bundleDir, rel);
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(join(root, file), dest);
+}
+if (skillFiles.length > 0) {
+  console.log(`Bundled skills copied to bundle/ (${skillFiles.length} file(s))`);
+}
+
 console.log('Assets copied to bundle/');