fss-link 1.6.1 → 1.6.12

package/LICENSE

@@ -189,6 +189,7 @@
 
   Copyright 2025 Google LLC
   Copyright 2025 Qwen
+  Copyright 2025 Fox Software Solutions
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -1,361 +1,108 @@
-# FSS Link 🔗
+# FSS Link
 
-<div align="center">
+A CLI coding agent forked from QwenCode, rebuilt around local-first model support and practical tooling for a solo developer's workflow.
 
-[![FSS Link](https://img.shields.io/badge/FSS-Link-emerald.svg)](https://github.com/FSSCoding/fss-link)
-[![TypeScript Tools](https://img.shields.io/badge/TypeScript-Tools-blue.svg)](https://github.com/FSSCoding/fss-link)
-[![RAG Integration](https://img.shields.io/badge/RAG-Integrated-purple.svg)](https://github.com/FSSCoding/fss-link)
-[![Voice Feedback](https://img.shields.io/badge/Voice-Enabled-orange.svg)](https://github.com/FSSCoding/fss-link)
-[![Local Models](https://img.shields.io/badge/Local-Models-red.svg)](https://github.com/FSSCoding/fss-link)
+## What it does
 
-**Spin up links. Get work done.** 🚀
+FSS Link is a terminal-based AI assistant that reads your codebase, runs tools, and helps you build software. It connects to local models (LM Studio, vLLM) or cloud APIs (OpenAI, Gemini) and gives the model access to file operations, web scraping, search, and shell commands.
 
-</div>
+It exists because the upstream project assumed cloud-only usage. This fork adds:
 
-**FSS Link** is a portable, scriptable agent that links tools, models, and knowledge into single-instance workflows. Install anywhere with Node.js, launch one agent at a time, feed it tasks, and watch it go.
+- **Local model priority** — LM Studio and vLLM as first-class providers, not afterthoughts
+- **Database-backed model config** — switch models via CLI flags, settings persist across sessions
+- **Web scraper tool** — search and extract web content from within the agent
+- **TTS integration** — audio feedback during long-running tasks via multi-voice TTS
+- **Image generation tool** — generate images via CLI from within the agent
+- **Vision support** — send images to vision-capable models with automatic format conversion and resizing
+- **Custom agents** — named agent personalities with distinct roles (research, testing, implementation, etc.)
+- **Private IP support** — works with vLLM/LM Studio on local network without SSL errors
 
-- **Lightweight distribution** (~15 MB bundle, requires Node.js 20+)
-- **Single-agent workflows** with structured prompts  
-- **Portable Mini-RAG** indices that travel with your projects (planned feature)
-- **Local-first** with LM Studio/Ollama priority
-- **Professional tools** built in TypeScript for seamless integration
+## Installation
 
-## 🎯 Why "Link"?
-
-Link connects things—tools, models, tasks, and knowledge. **FSS Link** is a lightweight distribution that runs wherever Node.js is installed. Start an agent, or spawn multiple agents with templated prompts (planned feature). Each project carries its own Mini-RAG index, so knowledge travels with the work.
-
-## 🚀 Quick Start
-
-```bash
-# Interactive mode
-fss-link
-
-# Single-shot task
-fss-link run "Audit the repo for security keys and open PR fixes."
-
-# Portable RAG - indexes travel with projects (planned feature)
-cd project && fss-link rag index . && fss-link rag query "error handling"
-```
-
-## ⚡ **NEW: UNIFIED PROVIDER SYSTEM (v1.0.54)**
-
-**Zero complexity model switching!** Complete provider/model management unification with eliminated spaghetti code:
+Requires Node.js 20+.
 
 ```bash
-# Quick Ollama tasks
-fss-link --provider ollama --model qwen3:4b -p "explain this code"
-fss-link --provider ollama --model qwen3-coder:latest -p "refactor this function"
-
-# LM Studio for specialized models  
-fss-link --provider lm-studio --model llama-3.1-8b -p "write documentation"
-
-# OpenAI for advanced reasoning
-fss-link --provider openai-api-key --model gpt-4o -p "complex analysis task"
-
-# Gemini for multimodal tasks
-fss-link --provider gemini-api-key --model gemini-2.0-flash-thinking -p "analyze this image"
-
-# Google Cloud providers (NEW)
-fss-link --provider vertex-ai --model gemini-1.5-pro -p "enterprise analysis"
-fss-link --provider oauth-personal --model gemini-flash -p "personal tasks"
-fss-link --provider cloud-shell --model default -p "cloud development"
-```
-
-### 🎯 **All 8 Providers Supported**
-- `ollama` - Local Ollama server (default port 11434)
-- `lm-studio` - LM Studio server (default port 1234)  
-- `openai-api-key` - OpenAI API (requires API key)
-- `gemini-api-key` - Google Gemini API (requires API key)
-- `vertex-ai` - Google Vertex AI (enterprise)
-- `oauth-personal` - Google OAuth (personal)
-- `cloud-shell` - Google Cloud Shell
-- `qwen-oauth` - FSS Link OAuth
-
-### 🔄 **Fallback Hierarchy**
-1. **CLI Arguments** - `--provider` and `--model` flags (highest priority)
-2. **Database Configuration** - Persistent model settings  
-3. **Environment Variables** - Traditional env var fallback
-
-## 📦 Installation
-
-**FSS Link v1.0.54 is now published to NPM with UNIFIED PROVIDER SYSTEM! Install it globally for the best experience:**
-
-```bash
-# Method 1: NPM Global Install (Recommended)
+# From npm
 npm install -g fss-link
 
-# Now you can use fss-link anywhere
-fss-link --help
-fss-link --version  # Should show v1.0.54
-```
-
-### 🎉 **NEW: Welcome Back System (v1.0.43)**
-
-FSS Link now features an intelligent **Welcome Back dialog** that appears when you return to projects with existing history:
-
-- **🔍 Project Status Dashboard** - Git status, session history, momentum analysis
-- **📊 Smart Context Generation** - Priority-based information filtering (7 levels)
-- **⚡ Multi-Agent Awareness** - Universal session tracking across all agents (planned feature)
-- **🎯 Seamless Resumption** - Intelligent context population for continuing work
-- **🚀 Production Quality** - Comprehensive error handling, performance optimization
-
-## 📁 File Access & Security
-
-### Workspace Boundaries
-FSS Link restricts file operations to **workspace directories** by design. Understanding workspace boundaries helps you work efficiently:
-
-**[Understanding Workspace Boundaries](./fss-docs/WORKSPACE-BOUNDARIES.md)** - Complete guide to:
-- How workspace scope is determined
-- Why files outside workspace are inaccessible
-- Configuration options to expand workspace
-- Troubleshooting "Path validation failed" errors
-
-### External Directory Access
-For accessing external directories like `/tmp`, user directories, or custom paths:
-
-**[External Directory Access Guide](./fss-docs/EXTERNAL-DIRECTORY-ACCESS.md)** - Explains:
-- Folder trust system configuration
-- Security considerations for external access
-- Trust levels (TRUST_FOLDER vs TRUST_PARENT)
-
-### 🔄 **Node.js Version Requirements**
-
-FSS Link requires **Node.js 20+**. If you have an older version, upgrade first:
-
-```bash
-# Check your current Node version
-node --version
-
-# If you have Node 18 or older, upgrade to Node 20:
-curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
-sudo apt-get install nodejs -y
-
-# Verify upgrade
-node --version  # Should show v20.x.x
-npm --version   # Should show v10.x.x
-```
-
-```bash
-# Method 2: Clone and Build from Source (Development)
-git clone http://gitea.internal.bobai.com.au:3000/foxadmin/fss-link.git
+# From source
+git clone https://github.com/FSScoding/fss-link.git
 cd fss-link
 npm install
 npm run build
-
-# Install globally for 'fss-link' command
-npm link
-
-# Now you can use fss-link anywhere
-fss-link --help
-```
-
-```bash
-# Method 3: Run without installing globally
-npx fss-link
-# OR from source
-cd fss-link
-npx fss-link
+npm run bundle
+sudo npm install -g .
 ```
 
-**✅ Note**: FSS Link is now published to npm as `fss-link` v1.0.54!
+## Usage
 
-## 🔧 Enhanced Features & Tools
-
-This agent extends FSS Link v0.0.10+ with professional development tools and intelligent workflow automation:
-
-### 🧠 **TypeScript Mini-RAG System**
-Built-in semantic search that travels with your projects. No Python dependencies, no setup complexity.
-
-- **Deep Semantic Search**: Find code by describing what it does, not just what it's called
-- **Cross-Reference Analysis**: Discover how different parts of the system interact
-- **Context-Aware Suggestions**: Get recommendations based on the entire project context
-- **Portable Indices**: Knowledge travels with your projects (planned feature)
-
-### 📋 **Enhanced Task Management**
-Built on FSS Link's native TodoWrite tool with professional enhancements for complex development workflows.
-
-- **Persistent Task Lists**: Never lose track of what needs to be done
-- **Visual Progress Indicators**: Instantly see what's complete, in-progress, or pending
-- **Intelligent Task Breakdown**: Automatically decompose complex features into actionable steps
-- **Multi-Agent Coordination**: Tasks shared across multiple agent instances (planned feature)
-
-### 🔍 **Professional Web Research**
-TypeScript-native web research tools eliminate context switching between development and external resources.
-
-- **Integrated Research**: Gather documentation without leaving the development workflow
-- **Content Processing**: Smart extraction and summarization of technical content
-- **Project Memory**: Maintain research context across sessions
-
-### 🎵 **Voice Feedback System**
-Long-running operations need progress updates. Audio feedback enables multitasking during complex automated tasks.
-
-- **TTS Integration**: Stay informed about progress without watching the screen
-- **Multi-Voice Support**: Assign different voices to different types of work
-- **Bluetooth Audio**: Use wireless speakers for clear feedback
-
-### ⚡ **Local Model Optimization**
-Designed for local-first development with intelligent model switching.
-
-- **LM Studio Priority**: Optimized for local inference workflows
-- **Ollama Secondary**: Fallback for different model architectures  
-- **Cloud Enhancement**: Remote models as capability extension, not dependency
-
-## 🖥️ **Local Model Recommendations**
-
-Based on extensive testing with the FSS Enhanced FSS Link prototype:
-
-### ⚡ **High-Speed Development** - `qwen/qwen3-4b-2507`
-- **Performance**: 120+ tokens/second on dual RTX 3090 setup
-- **Context Window**: 190k tokens with KV quantisation + Flash Attention
-- **Best for**: Code completion, refactoring, documentation, analysis
-- **Experience**: Comparable to Gemini Flash with enhanced system prompts
-
-### 🧠 **Complex Problem Solving** - `qwen/qwen3-30b-a3b-2507`  
-- **Performance**: Slower but significantly more capable reasoning
-- **Context Window**: 131k tokens with KV quantisation + Flash Attention
-- **Best for**: Architecture decisions, complex debugging, system design
-- **When to use**: Multi-step problems requiring deep analysis
-
-## 🚀 **CLI Commands**
-
-### **Interactive Mode**
 ```bash
-# Launch FSS Link interactive shell
+# Interactive mode
 fss-link
 
-# Launch with specific model
-fss-link --model qwen/qwen3-4b-2507
+# One-shot prompt
+fss-link -p "refactor the error handling in src/api.ts"
 
-# Launch with RAG index (planned feature)
-fss-link --rag ./project-index
-```
-
-### **Single-Shot Execution**
-```bash
-# Execute prompt and exit
-fss-link run "Analyse this codebase structure"
+# Specify provider and model
+fss-link --provider lm-studio --model qwen3-coder:latest
+fss-link --provider openai-api-key --model gpt-4o -p "review this PR"
 
-# With specific model
-fss-link run "Review security patterns" --model qwen/qwen3-30b-a3b-2507
-
-# With RAG context (planned feature)
-fss-link run "Find authentication bugs" --rag .
+# Non-interactive with auto-approval
+fss-link -p "fix the failing tests" --approval-mode yolo
 ```
 
-### **Multi-Agent Workflows** (Planned Feature)
-```bash
-# Launch multiple agents with template (planned feature)
-fss-link spawn --count 8 --template ./templates/build-test.yml
+### Providers
 
-# Parallel code review (planned feature)
-fss-link spawn --count 4 --template ./templates/code-review.yml --files src/
+| Provider | Flag | Notes |
+|---|---|---|
+| LM Studio | `--provider lm-studio` | Local, port 1234 |
+| vLLM / OpenAI-compatible | `--provider ollama` | Local or network |
+| OpenAI | `--provider openai-api-key` | Requires `OPENAI_API_KEY` |
+| Gemini | `--provider gemini-api-key` | Requires `GEMINI_API_KEY` |
+| BobAI Proxy | `--provider bob-ai` | Custom proxy endpoint |
+| Vertex AI | `--provider vertex-ai` | Google Cloud |
 
-# Load-balanced task processing (planned feature)
-fss-link spawn --count 6 --template ./templates/regression-test.yml
-```
+Model and provider settings persist to a local SQLite database. Once set, you don't need to specify them again.
 
-### **RAG Operations** (Planned Feature)
-```bash
-# Index current directory (planned feature)
-fss-link rag index .
+### Configuration hierarchy
 
-# Index with specific extensions (planned feature)
-fss-link rag index . --extensions py,js,md
+1. CLI flags (`--provider`, `--model`) — highest priority
+2. Database — persistent settings from previous sessions
+3. Environment variables — traditional fallback
 
-# Query with filters (planned feature)
-fss-link rag query "authentication logic" --topk 5
+## Project structure
 
-# Cross-reference search (planned feature)
-fss-link rag query "error handling patterns" --files py,js --recent
 ```
-
-## 📦 **Installation**
-
-### **Prerequisites**
-- Node.js 20+
-- LM Studio or Ollama (recommended for local models)
-
-### **Quick Install**
-```bash
-# Install from npm (Published v1.0.13)
-npm install -g fss-link
-
-# Or clone from source for development
-git clone http://gitea.internal.bobai.com.au:3000/foxadmin/fss-link.git
-cd fss-link
-npm install && npm run build && npm link
-
-# Verify installation
-fss-link --version  # Should show v1.0.54
+packages/
+  cli/          # CLI entry point, config, model management
+  core/         # Tools, services, content generation, utilities
+fss-tools/
+  webscraper/   # Python-based web scraper with search integration
+scripts/        # Build and utility scripts
+docs/           # Published documentation
+fss-docs/       # Internal development reference
 ```
 
-## ⚙️ **Configuration**
+## Building from source
 
-### **Model Profiles**
 ```bash
-# List available profiles
-fss-link profiles list
-
-# Create new profile
-fss-link profiles add local-fast --model qwen/qwen3-4b-2507 --provider lm-studio
+# Bundle (esbuild, bundles directly from TS source)
+npm run bundle
 
-# Set default profile
-fss-link profiles default local-fast
+# Install globally
+sudo npm install -g .
 ```
 
-### **Core Providers**
-- **Qwen OAuth** - 2000 requests/day free tier
-- **OpenAI Compatible** - OpenRouter, custom endpoints, local APIs
-- **Local Models** - LM Studio/Ollama priority for privacy and speed
-
-## 🛠️ **Database System Status**
+esbuild bundles directly from TypeScript source into `bundle/fss-link.js`. Do not run bare `tsc` — see issue #64.
 
-✅ **PRODUCTION READY**: Async locking system implemented and verified  
-✅ **Statement Closed Errors**: **ELIMINATED** via comprehensive async locking  
-✅ **44/44 Critical Tests**: All async locking tests passing  
-✅ **Auth System**: Race conditions eliminated, reliable model switching  
-✅ **Production Validation**: Complete - zero database errors under load  
+## Current version
 
-**Implementation Complete**: See `fss-docs/DATABASE-ASYNC-LOCKING-PLAN.md` for full details.
+v1.6.12 — see [CHANGELOG.md](./CHANGELOG.md) for history.
 
-## 🔧 **Development Philosophy**
-
-### **Fresh Fork Strategy**
-FSS Link builds on FSS Link v0.0.10+ using a clean fork approach:
-
-1. **Start Clean**: Fork latest upstream for stable foundation
-2. **TypeScript Native**: Build tools in TypeScript for seamless integration
-3. **Selective Enhancement**: Add value without complexity explosion
-4. **Professional Focus**: Target professional development workflows
-
-### **Tool Integration Principles**
-- **No Python Dependencies**: Everything builds with npm
-- **Portable by Design**: Works anywhere Node.js runs
-- **Performance First**: Local models, fast feedback, efficient workflows
-- **Professional Quality**: Battle-tested, reliable, focused on core needs
-
-## 🎨 **Brand & Visual Identity**
-
-- **Colour**: Emerald `#10B981` (linking/connection theme)
-- **Background**: Slate `#0F172A` 
-- **Accent**: Green headers, dim slate separators
-- **Icon**: Chain-link with spark (🔗⚡)
-- **Tagline**: "Spin up links. Get work done."
-
-## 📄 **License**
+## License
 
 [Apache 2.0](./LICENSE)
 
-## 🌟 **Acknowledgments**
-
-FSS Link builds on [QwenLM/fss-link](https://github.com/QwenLM/fss-link), which itself builds upon [Google Gemini CLI](https://github.com/google-gemini/gemini-cli). We acknowledge and appreciate the excellent work of both teams.
-
----
-
-<div align="center">
-
-**FSS Link** - *Portable, scriptable, single-instance AI agent*
-
-[Documentation](./FSS-LINK-IMPLEMENTATION-GUIDE.md) • [Examples](./examples/)
+## Acknowledgments
 
-</div>
+FSS Link is a hard fork of [QwenCode](https://github.com/QwenLM/qwen-code), which builds on [Google Gemini CLI](https://github.com/google-gemini/gemini-cli).