fss-link 1.9.1 → 1.9.3

package/bundle/worktrees/SKILL.md

@@ -0,0 +1,102 @@
+---
+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 everything
+```
+
+## 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 everything | `exit_worktree({ name, action: "remove", discard_changes: 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`
+
+## 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/README.md

@@ -183,6 +183,7 @@ npx vitest run packages/cli/src/config/database.test.ts
 
 - [Configuration Guide](CONFIGURATION.md) — providers, models, database, context settings
 - [Tools Reference](TOOLS.md) — all available tools and their parameters
+- [Slash Commands](SLASH-COMMANDS.md) — `/resume`, `/rewind`, `/sessions`, and the Welcome Back dialog
 - [Tool Flow Diagrams](../fss-docs/tool-flow-diagrams/) — visual documentation with Mermaid diagrams
 
 ## License

package/docs/SLASH-COMMANDS.md

@@ -0,0 +1,186 @@
+# Slash Commands — Session Management
+
+## `/resume` — List and Resume Saved Sessions
+
+Resume a previous conversation session by number, title, or session ID.
+
+### Usage
+
+```
+/resume                          # List recent sessions
+/resume <number>                 # Resume by list position
+/resume <title substring>        # Resume by title match
+/resume <session-id>             # Resume by exact session ID
+```
+
+### Alternatives
+
+`/sessions`, `/continue` — all three names invoke the same command.
+
+### Listing Sessions
+
+Running `/resume` with no arguments displays a numbered list of up to 50 recent sessions for the current project, sorted by most recently updated:
+
+```
+Recent sessions:
+
+  1. Implement auth middleware for API endpoints    2 hours ago    14 turns
+  2. Fix login bug on password reset flow           1 day ago      8 turns
+  3. Set up CI pipeline with GitHub Actions         3 days ago     22 turns
+
+Type a number to resume, or /resume <partial title> to match by name.
+```
+
+Titles are truncated at 55 characters. The list is scoped to the current project (identified by project hash).
+
+### Selection Methods
+
+| Method | Example | Behavior |
+|--------|---------|----------|
+| **Numeric index** | `/resume 2` | Selects the second item in the listed order (1-based) |
+| **Title substring** | `/resume auth` | First session whose title contains "auth" (case-insensitive) |
+| **Exact session ID** | `/resume abc123def` | Matches the session's unique ID exactly |
+
+### Matching Rules
+
+- **Numeric index** is checked first. If the number is out of range (fewer sessions than the number given), it falls through to title matching.
+- **Title substring** uses `String.prototype.includes()` — any part of the title matching the input selects the first such session. There is no ranking or scoring; the first match wins.
+- **Exact session ID** is the final fallback if neither numeric nor title matching succeeds.
+- If no match is found at all, an error message is shown: `No session matched "foo". Use /resume to list sessions.`
+
+### Tab Completion
+
+Pressing Tab while typing `/resume <partial>` shows completions for session titles that **start with** the partial text (`startsWith`). This is intentionally stricter than the action's own matching (`includes`) — tab completion may show fewer options than what `/resume <text>` would actually match.
+
+### What Happens When You Resume
+
+The selected session's full conversation history is restored:
+- The Gemini client's history is replaced with the saved history from the session
+- The session ID is set so subsequent exchanges update the same session record
+- Turn count is restored from the session record
+- The UI displays the restored history as a scrollable message list
+
+### Session Storage
+
+Sessions are stored in `~/.fss-link/sessions.db` (a dedicated SQLite database). Each session record includes:
+- `id` — unique session identifier
+- `title` — auto-generated from the first user message (truncated to 80 chars)
+- `project_path`, `project_hash` — project identification
+- `provider`, `model_name` — which model was used
+- `created_at`, `updated_at` — timestamps
+- `turn_count`, `total_input_tokens`, `total_output_tokens` — usage metrics
+- `history_json` — full conversation history as JSON
+
+Sessions are created on the first exchange in a conversation and updated after each subsequent exchange. An auto-save timer flushes changes every 30 seconds.
+
+---
+
+## `/rewind` — Rewind to a Previous Turn
+
+Rewind the conversation to a selected past turn, discarding everything after it.
+
+### Usage
+
+```
+/rewind                          # Open rewind dialog
+```
+
+No arguments are accepted — `/rewind foo` behaves identically to `/rewind`.
+
+### How It Works
+
+Running `/rewind` opens an interactive dialog that shows all user-initiated turns in the current conversation. Selecting a turn discards everything after it, effectively rewinding the conversation to that point.
+
+### Turn Extraction
+
+The dialog filters the conversation history to show only meaningful user turns:
+- **Included**: User messages with text content
+- **Excluded**: Tool-response turns (all parts are `functionResponse`), system notes (`[System note:`), steering messages (`[Steering message`)
+
+Turns are displayed in reverse-chronological order (most recent first), numbered T1, T2, T3… from oldest to newest.
+
+### Navigation & Search
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Move selection up/down |
+| `Enter` | Confirm selection and rewind |
+| `Esc` (first press) | Clear the search filter |
+| `Esc` (second press) | Close the dialog without rewinding |
+| `Backspace` | Delete one character from the search filter |
+| Any printable character | Type into the search filter box |
+
+### Search
+
+The dialog has a working text filter. Type any characters to narrow the visible turns:
+
+- **Case-insensitive substring match** on turn text
+- Selection resets to the top (index 0) when the filter changes
+- Shows "No turns match" if the filter produces zero results
+- First `Esc` clears the filter and restores the full list; second `Esc` closes the dialog
+
+**Limitations:**
+- Single-term only — multi-word queries like "auth middleware" won't work as two separate terms
+- Searches only user message text, not tool calls, results, or delta events
+- No ranking or scoring — just `includes` substring match
+
+### What Happens When You Rewind
+
+1. The conversation history is cleared
+2. A preview message is built from the selected turn's content
+3. All turns after the selected one are discarded
+4. The model can then continue from the rewound point
+
+### Known Behavior
+
+The rewind point uses `fullHistory.slice(0, contentIndex)` — the selected turn is **included** in the rewound history. The dialog help text says "conversation after selected turn will be discarded," which is accurate: the selected turn itself is preserved, everything after it is removed.
+
+---
+
+## `/sessions` — Alias for `/resume`
+
+`/sessions` and `/continue` are aliases for `/resume`. All three names invoke the same command with identical behavior. See `/resume` above for full details.
+
+---
+
+## Welcome Back Dialog — Project-Level Resume
+
+The **Welcome Back dialog** is a separate feature from `/resume`. It appears automatically when you launch FSS Link in a project that has prior session history, offering a high-level choice to continue from where you left off or start fresh.
+
+### When It Appears
+
+- On startup, when `enableWelcomeBack` is enabled in settings (default: on)
+- Only when the project has existing conversation history
+- Uses `ProjectSummaryParser` to analyze project state — not `sessions.db` directly
+
+### Options
+
+| Option | Keyboard Shortcut | Behavior |
+|--------|-------------------|----------|
+| **Continue Project** | `C` | Resumes from the most recent session with contextual summary |
+| **Start Fresh Session** | `R` | Begins a new conversation with no history |
+| **Cancel** | `Q` / `Escape` | Exits without starting a session |
+
+### What It Shows
+
+The dialog displays project-level information including:
+- Project goal (if available)
+- Time since last activity
+- Session count and active sessions
+- Momentum indicator (high / building / stale / none)
+- Git status (branch, staged/unstaged changes, last commit)
+- Efficiency metrics and recent activity summary
+- Next suggestion (if available)
+
+### Key Differences from `/resume`
+
+| Aspect | Welcome Back Dialog | `/resume` |
+|--------|---------------------|-----------|
+| **Trigger** | Automatic on project launch | Manual slash command |
+| **Scope** | Project-level (one choice) | Per-session picker (up to 50) |
+| **Data source** | `ProjectSummaryParser` (analysis of project state) | `sessions.db` (direct session records) |
+| **Selection** | Continue / Restart / Cancel | Number, title substring, or session ID |
+| **Context** | Smart summary built from project analysis | Full conversation history restored verbatim |
+| **Search** | None — single decision point | Substring search across session titles |
+
+The Welcome Back dialog is best for quick decisions at project launch. `/resume` is for browsing and selecting from multiple saved sessions within an active conversation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fss-link",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "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.0"
+    "sandboxImageUri": "ghcr.io/fsscoding/fss-link:1.9.3"
   },
   "scripts": {
     "start": "node scripts/start.js",
@@ -82,6 +82,7 @@
     "LICENSE"
   ],
   "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
     "@types/ink-testing-library": "^1.0.4",
     "@vitest/coverage-v8": "^4.1.8",
     "concurrently": "^9.2.0",

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/');