From a4978e62adeb77ab897fb70c72bfac040ad824df Mon Sep 17 00:00:00 2001 From: Alex Holmberg Date: Thu, 1 Jan 2026 09:25:42 +0100 Subject: [PATCH] feat: updated docs and agent resume querry --- docs/command-overview.md | 965 ++++++++++++++++++++++++++++++++------- src/agent/mod.rs | 114 ++++- src/agent/session.rs | 49 +- 3 files changed, 951 insertions(+), 177 deletions(-) diff --git a/docs/command-overview.md b/docs/command-overview.md index 10122b40..06b694a6 100644 --- a/docs/command-overview.md +++ b/docs/command-overview.md @@ -1,39 +1,73 @@ -# 🚀 Syncable CLI - Complete Command Overview +# 🚀 Syncable CLI - Complete Command Reference -This document provides a comprehensive overview of all available commands and their different display modes. +This document provides a comprehensive reference for all Syncable CLI commands, options, and workflows. -## 📊 Analysis Commands +## 📑 Table of Contents -### 1. Basic Project Analysis +- [Global Options](#-global-options) +- [Commands](#-commands) + - [analyze](#1-sync-ctl-analyze) - Project analysis + - [generate](#2-sync-ctl-generate) - IaC generation + - [validate](#3-sync-ctl-validate) - IaC validation (planned) + - [support](#4-sync-ctl-support) - Show supported tech + - [dependencies](#5-sync-ctl-dependencies) - Dependency analysis + - [vulnerabilities](#6-sync-ctl-vulnerabilities) - CVE scanning + - [security](#7-sync-ctl-security) - Comprehensive security scan + - [tools](#8-sync-ctl-tools) - Tool management + - [chat](#9-sync-ctl-chat) - AI assistant + - [auth](#10-sync-ctl-auth) - Authentication +- [Configuration](#-configuration) +- [Common Workflows](#-common-workflows) +- [VS Code Integration](#-vs-code-integration) +- [Environment Variables](#-environment-variables) +- [Exit Codes](#-exit-codes) -```bash -# Modern matrix view (default) - compact dashboard -sync-ctl analyze . +--- -# Detailed view with full Docker analysis -sync-ctl analyze . --display detailed -# Or use the legacy flag -sync-ctl analyze . -d +## 🌐 Global Options -# Summary view for CI/CD pipelines -sync-ctl analyze . --display summary +Available for all commands: -# JSON output for scripts -sync-ctl analyze . --json +| Flag | Short | Description | +|------|-------|-------------| +| `--config ` | `-c` | Path to configuration file | +| `--verbose` | `-v` | Enable verbose logging (`-v` info, `-vv` debug, `-vvv` trace) | +| `--quiet` | `-q` | Suppress all output except errors | +| `--json` | | Output in JSON format where applicable | +| `--clear-update-cache` | | Clear update check cache and force a new check | +| `--disable-telemetry` | | Disable telemetry data collection | +| `--help` | `-h` | Show help information | +| `--version` | `-V` | Show version information | -# Analyze specific project path -sync-ctl analyze /path/to/project -``` +--- + +## 📚 Commands + +### 1. `sync-ctl analyze ` + +Analyze a project and display detected components (languages, frameworks, dependencies, architecture). + +**Arguments:** +- `` — Path to the project directory to analyze -### 2. Display Mode Comparison +**Options:** + +| Flag | Short | Description | +|------|-------|-------------| +| `--json` | `-j` | Output analysis results in JSON format | +| `--detailed` | `-d` | Show detailed analysis information (legacy format) | +| `--display ` | | Display format: `matrix` (default), `detailed`, `summary` | +| `--only ` | | Only analyze specific aspects (comma-separated: languages, frameworks, dependencies) | +| `--color-scheme ` | | Color scheme: `auto` (default), `dark`, `light` | + +**Display Mode Comparison:** #### Matrix View (Default) 🆕 - **Best for**: Quick overview, comparing multiple projects - **Features**: Modern dashboard with box-drawing characters, side-by-side project comparison, key metrics - **Docker Info**: Overview with service counts and orchestration patterns -- **Note**: Box alignment improvements in progress for better visual consistency -#### Detailed View +#### Detailed View - **Best for**: In-depth analysis, debugging, comprehensive reports - **Features**: Full Docker analysis, complete technology breakdown, all metadata - **Docker Info**: Complete Docker infrastructure analysis including: @@ -41,172 +75,695 @@ sync-ctl analyze /path/to/project - Docker Compose services with dependencies and networking - Orchestration patterns and service discovery - Port mappings and volume configurations -- **Usage**: Use this view when you need complete information about your project #### Summary View - **Best for**: CI/CD pipelines, quick status checks - **Features**: Brief overview with essential information only -- **Usage**: Perfect for automated scripts and quick validation -## 🔍 Security & Vulnerability Commands +**Examples:** + +```bash +# Basic analysis with modern matrix view +sync-ctl analyze . + +# Detailed view with full Docker analysis +sync-ctl analyze . --display detailed +# Or use the legacy flag +sync-ctl analyze . -d + +# Summary view for CI/CD pipelines +sync-ctl analyze . --display summary + +# JSON output for scripting +sync-ctl analyze . --json + +# Only show languages and frameworks +sync-ctl analyze . --only languages,frameworks + +# Use light terminal theme colors +sync-ctl analyze . --color-scheme light + +# Analyze specific project path +sync-ctl analyze /path/to/project +``` + +**Supported Technologies:** +- **Languages**: Rust, JavaScript/TypeScript, Python, Go, Java +- **Frameworks**: 260+ including React, Vue, Angular, Next.js, Express, Django, Flask, FastAPI, Spring Boot, and more +- **Databases**: PostgreSQL, MySQL, MongoDB, Redis, and more +- **Tools**: Docker, Kubernetes, Terraform, and more + +--- + +### 2. `sync-ctl generate ` + +Generate Infrastructure as Code files (Dockerfile, docker-compose.yml, Terraform config). + +**Arguments:** +- `` — Path to the project directory -### 3. Security Analysis (Turbo Engine - 10-100x Faster) +**Options:** + +| Flag | Short | Description | +|------|-------|-------------| +| `--output ` | `-o` | Output directory for generated files | +| `--dockerfile` | | Generate Dockerfile | +| `--compose` | | Generate Docker Compose file | +| `--terraform` | | Generate Terraform configuration | +| `--all` | | Generate all supported IaC files (default if no specific flag) | +| `--dry-run` | | Preview output without creating files | +| `--force` | | Overwrite existing files | + +**Examples:** ```bash -# Comprehensive security scan (default: thorough mode) -sync-ctl security . +# Generate all IaC files +sync-ctl generate . +sync-ctl generate . --all -# Different scan modes for speed vs coverage -sync-ctl security . --mode lightning # Fastest - critical files only -sync-ctl security . --mode fast # Smart sampling -sync-ctl security . --mode balanced # Good coverage -sync-ctl security . --mode thorough # Comprehensive (default) -sync-ctl security . --mode paranoid # Maximum coverage +# Only generate Dockerfile +sync-ctl generate . --dockerfile -# Include low-severity findings -sync-ctl security . --include-low +# Generate Dockerfile and Compose +sync-ctl generate . --dockerfile --compose -# Skip specific checks -sync-ctl security . --no-secrets --no-code-patterns +# Preview without creating files +sync-ctl generate . --dry-run -# Export security report -sync-ctl security . --output security-report.json --format json +# Custom output directory +sync-ctl generate . --output ./infrastructure/ -# Fail CI/CD on security findings -sync-ctl security . --fail-on-findings +# Generate and overwrite existing files +sync-ctl generate . --all --force ``` -#### Security Scan Modes +**Status:** 🚧 In Development +- Basic generation implemented +- Enhanced monorepo generation with per-project IaC files coming soon -| Mode | Speed | Coverage | Use Case | -|------|-------|----------|----------| -| **Lightning** | 🚀 Fastest | Critical files only | Pre-commit hooks, CI checks | -| **Fast** | ⚡ Very Fast | Smart sampling | Development workflow | -| **Balanced** | 🎯 Optimized | Good coverage | Regular security checks | -| **Thorough** | 🔍 Complete | Comprehensive | Security audits (default) | -| **Paranoid** | 🕵️ Maximum | Everything + low severity | Compliance, releases | +--- + +### 3. `sync-ctl validate ` -### 4. Vulnerability Scanning +Validate existing IaC files against best practices. + +**Arguments:** +- `` — Path to directory containing IaC files + +**Options:** + +| Flag | Description | +|------|-------------| +| `--types ` | Types of files to validate (comma-separated) | +| `--fix` | Automatically fix issues where possible | + +**Examples:** ```bash -# Scan all dependencies for vulnerabilities across all supported package managers -# Supports: npm, yarn, pnpm, bun (JavaScript), pip (Python), cargo (Rust), go mod (Go) -sync-ctl vulnerabilities . +# Validate all IaC files +sync-ctl validate . -# Filter by severity -sync-ctl vulnerabilities . --severity high -sync-ctl vulnerabilities . --severity critical +# Validate specific types +sync-ctl validate . --types dockerfile,compose + +# Auto-fix issues +sync-ctl validate . --fix +``` + +**Status:** ⚠️ Not yet implemented + +--- + +### 4. `sync-ctl support` + +Show supported languages and frameworks. + +**Options:** + +| Flag | Short | Description | +|------|-------|-------------| +| `--languages` | | Show only languages | +| `--frameworks` | | Show only frameworks | +| `--detailed` | `-d` | Show detailed information | + +**Examples:** + +```bash +# Show all supported tech +sync-ctl support -# Export vulnerability report -sync-ctl vulnerabilities . --format json --output vulns.json +# Only show languages +sync-ctl support --languages + +# Only show frameworks +sync-ctl support --frameworks -# Check specific project path -sync-ctl vulnerabilities /path/to/project +# Detailed information +sync-ctl support --detailed ``` -### 5. Dependency Analysis +**Supported Technologies:** + +
+260+ technologies across 5 ecosystems + +**JavaScript/TypeScript** — React, Vue, Angular, Next.js, Express, Nest.js, Fastify, and 40+ more + +**Python** — Django, Flask, FastAPI, Celery, NumPy, TensorFlow, PyTorch, and 70+ more + +**Go** — Gin, Echo, Fiber, gRPC, Kubernetes client, and 20+ more + +**Rust** — Actix-web, Axum, Rocket, Tokio, SeaORM, and 20+ more + +**Java/Kotlin** — Spring Boot, Micronaut, Quarkus, Hibernate, and 90+ more + +
+ +--- + +### 5. `sync-ctl dependencies ` + +Analyze project dependencies in detail. + +**Arguments:** +- `` — Path to the project directory + +**Options:** + +| Flag | Description | +|------|-------------| +| `--licenses` | Show license information for dependencies | +| `--vulnerabilities` | Check for known vulnerabilities | +| `--prod-only` | Show only production dependencies | +| `--dev-only` | Show only development dependencies | +| `--format ` | Output format: `table` (default) or `json` | + +**Examples:** ```bash -# Analyze dependencies with licenses +# Show all dependencies +sync-ctl dependencies . + +# Analyze with licenses sync-ctl dependencies . --licenses -# Include vulnerability checking +# Check for vulnerabilities sync-ctl dependencies . --vulnerabilities -# Production dependencies only -sync-ctl dependencies . --prod-only +# Show only production dependencies with licenses +sync-ctl dependencies . --prod-only --licenses -# Development dependencies only +# Development dependencies only sync-ctl dependencies . --dev-only # JSON output sync-ctl dependencies . --format json +sync-ctl dependencies . --vulnerabilities --format json > deps.json +``` + +**Supported Package Managers:** +- npm, yarn, pnpm, bun (JavaScript) +- pip, pipenv, poetry (Python) +- cargo (Rust) +- go.mod (Go) +- maven, gradle (Java) + +--- + +### 6. `sync-ctl vulnerabilities [PATH]` + +Check dependencies for known security vulnerabilities (CVEs). + +**Arguments:** +- `[PATH]` — Path to scan (default: current directory `.`) + +**Options:** + +| Flag | Description | +|------|-------------| +| `--severity ` | Show only vulnerabilities with severity >= threshold (`low`, `medium`, `high`, `critical`) | +| `--format ` | Output format: `table` (default) or `json` | +| `--output ` | Export report to file | + +**Examples:** + +```bash +# Scan current directory +sync-ctl vulnerabilities +sync-ctl vulnerabilities . + +# Only show high and critical vulnerabilities +sync-ctl vulnerabilities . --severity high +sync-ctl vulnerabilities . --severity critical + +# Only show critical vulnerabilities +sync-ctl vulnerabilities . --severity critical + +# Export report to file (table format) +sync-ctl vulnerabilities . --output report.txt + +# Export JSON report +sync-ctl vulnerabilities . --output report.json --format json + +# Scan specific path with severity filter +sync-ctl vulnerabilities /path/to/project --severity medium ``` -## 🛠️ Tool Management Commands +**Supported Package Managers:** +- npm, yarn, pnpm, bun (JavaScript) +- pip (Python) +- cargo (Rust) +- go mod (Go) +- maven, gradle (Java) + +**Exit Behavior:** +- Exits with code `1` if critical or high severity vulnerabilities are found +- Use this in CI/CD to fail builds on security issues + +--- + +### 7. `sync-ctl security [PROJECT_PATH]` + +Perform comprehensive security analysis (secrets detection, code patterns, vulnerabilities). + +**Arguments:** +- `[PROJECT_PATH]` — Path to analyze (default: current directory `.`) + +**Options:** + +| Flag | Description | +|------|-------------| +| `--mode ` | Scan mode: `lightning`, `fast`, `balanced`, `thorough` (default), `paranoid` | +| `--include-low` | Include low severity findings | +| `--no-secrets` | Skip secrets detection | +| `--no-code-patterns` | Skip code pattern analysis | +| `--format ` | Output format: `table` (default) or `json` | +| `--output ` | Export report to file | +| `--fail-on-findings` | Exit with error code on security findings | + +**Security Scan Modes:** -### 6. Vulnerability Scanning Tools +| Mode | Speed | Coverage | Use Case | +|------|-------|----------|----------| +| `lightning` | 🚀 Fastest | Critical files only | Pre-commit hooks, CI checks | +| `fast` | ⚡ Very Fast | Smart sampling | Development workflow | +| `balanced` | 🎯 Optimized | Good coverage | Regular security checks | +| `thorough` | 🔍 Complete | Comprehensive | Security audits (default) | +| `paranoid` | 🕵️ Maximum | Everything + low severity | Compliance, releases | + +**Examples:** ```bash -# Check tool installation status +# Comprehensive security scan (default: thorough mode) +sync-ctl security +sync-ctl security . + +# Lightning-fast scan for pre-commit hooks +sync-ctl security --mode lightning +sync-ctl security . --mode lightning + +# Fast scan for development +sync-ctl security . --mode fast + +# Balanced scan (recommended for regular checks) +sync-ctl security . --mode balanced + +# Paranoid scan with low severity findings +sync-ctl security . --mode paranoid +sync-ctl security . --mode paranoid --include-low + +# Skip specific checks +sync-ctl security . --no-secrets +sync-ctl security . --no-code-patterns +sync-ctl security . --no-secrets --no-code-patterns + +# Export security report +sync-ctl security . --output security-report.txt +sync-ctl security . --output security-report.json --format json + +# Fail CI/CD on security findings +sync-ctl security . --fail-on-findings +sync-ctl security . --mode fast --fail-on-findings --format json +``` + +**What It Detects:** +- **Secrets**: API keys, tokens, passwords, credentials +- **Code Patterns**: SQL injection, XSS, insecure crypto, hardcoded secrets +- **Vulnerabilities**: Known CVEs in dependencies +- **Security Best Practices**: File permissions, configuration issues + +**Performance:** +- Powered by Turbo Engine (10-100x faster than traditional scanners) +- Uses parallel processing and smart caching +- Blazing-fast secret detection powered by Rust + +--- + +### 8. `sync-ctl tools ` + +Manage vulnerability scanning tools (install, check status, verify). + +#### 8a. `sync-ctl tools status` + +Check which vulnerability scanning tools are installed. + +**Options:** + +| Flag | Description | +|------|-------------| +| `--format ` | Output format: `table` (default) or `json` | +| `--languages ` | Check tools for specific languages only (comma-separated) | + +**Examples:** + +```bash +# Check all tools sync-ctl tools status -# Install missing tools +# Check JavaScript tools only +sync-ctl tools status --languages javascript + +# Check multiple languages +sync-ctl tools status --languages rust,python,javascript + +# JSON output +sync-ctl tools status --format json +``` + +#### 8b. `sync-ctl tools install` + +Install missing vulnerability scanning tools. + +**Options:** + +| Flag | Short | Description | +|------|-------|-------------| +| `--languages ` | | Install tools for specific languages only (comma-separated) | +| `--include-owasp` | | Also install OWASP Dependency Check (large download) | +| `--dry-run` | | Show what would be installed without installing | +| `--yes` | `-y` | Skip confirmation prompts | + +**Examples:** + +```bash +# Install all missing tools (interactive) sync-ctl tools install -# Install for specific languages +# Install JavaScript tools only +sync-ctl tools install --languages javascript + +# Install multiple language tools sync-ctl tools install --languages rust,python # Include OWASP Dependency Check (large download) sync-ctl tools install --include-owasp -# Verify tool functionality +# Dry run to see what would be installed +sync-ctl tools install --dry-run + +# Install without prompts +sync-ctl tools install --yes +sync-ctl tools install -y +``` + +#### 8c. `sync-ctl tools verify` + +Verify that installed tools are working correctly. + +**Options:** + +| Flag | Short | Description | +|------|-------|-------------| +| `--languages ` | | Test tools for specific languages only | +| `--detailed` | `-d` | Show detailed verification output | + +**Examples:** + +```bash +# Verify all tools sync-ctl tools verify -# Get installation guide +# Verify specific language tools +sync-ctl tools verify --languages javascript + +# Verify with detailed output +sync-ctl tools verify --detailed +sync-ctl tools verify -d +``` + +#### 8d. `sync-ctl tools guide` + +Show tool installation guides for manual setup. + +**Options:** + +| Flag | Description | +|------|-------------| +| `--languages ` | Show guide for specific languages only | +| `--platform ` | Show platform-specific instructions | + +**Examples:** + +```bash +# Show all installation guides sync-ctl tools guide -# Platform-specific guides +# Show Python tools guide +sync-ctl tools guide --languages python + +# Platform-specific guide +sync-ctl tools guide --platform macos sync-ctl tools guide --platform linux +sync-ctl tools guide --platform windows ``` -## 🏗️ Generation Commands +**Supported Tools:** +- **JavaScript**: npm audit, yarn audit, pnpm audit, retire.js +- **Python**: pip-audit, safety +- **Rust**: cargo-audit +- **Go**: nancy +- **Java**: OWASP Dependency Check + +--- + +### 9. `sync-ctl chat [PROJECT_PATH]` + +Start an interactive AI chat session to analyze, generate, and understand your project. -### 7. IaC Generation +**Arguments:** +- `[PROJECT_PATH]` — Path to the project directory (default: current directory `.`) + +**Options:** + +| Flag | Short | Description | +|------|-------|-------------| +| `--provider ` | | LLM provider: `openai`, `anthropic`, `bedrock`, `ollama`, `auto` (default) | +| `--model ` | | Model to use (e.g., `gpt-4o`, `claude-3-5-sonnet-latest`, `llama3.2`) | +| `--query ` | | Run a single query instead of interactive mode | +| `--resume ` | `-r` | Resume a previous session (`latest`, session number, or UUID) | +| `--list-sessions` | | List available sessions for this project and exit | + +**Examples:** ```bash -# Generate all IaC files -sync-ctl generate . -sync-ctl generate . --all +# Start interactive chat (auto-detect provider) +sync-ctl chat +sync-ctl chat . -# Generate specific types -sync-ctl generate . --dockerfile --compose -sync-ctl generate . --terraform +# Use specific provider +sync-ctl chat --provider openai +sync-ctl chat --provider anthropic +sync-ctl chat --provider bedrock +sync-ctl chat --provider ollama -# Dry run (preview only) -sync-ctl generate . --dry-run +# Use specific model +sync-ctl chat --model gpt-4o +sync-ctl chat --model claude-3-5-sonnet-latest +sync-ctl chat --model llama3.2 -# Custom output directory -sync-ctl generate . --output ./infrastructure/ +# Run a single query +sync-ctl chat --query "Generate a Dockerfile for this project" +sync-ctl chat --query "What security issues are in my code?" +sync-ctl chat --query "Optimize my Docker Compose file" -# Overwrite existing files -sync-ctl generate . --force +# Resume latest session +sync-ctl chat --resume latest +sync-ctl chat -r latest + +# Resume specific session (by number) +sync-ctl chat --resume 3 +sync-ctl chat -r 3 + +# Resume by UUID +sync-ctl chat --resume 8f7a9b2c + +# List all sessions +sync-ctl chat --list-sessions + +# Analyze specific project path +sync-ctl chat /path/to/project ``` -## 🔄 Validation Commands (Coming Soon) +**Chat Commands** (inside interactive session): -### 8. IaC Validation +| Command | Description | +|---------|-------------| +| `/model` | Switch AI model (GPT-4, Claude, etc.) | +| `/provider` | Switch between OpenAI and Anthropic | +| `/clear` | Clear conversation history | +| `/help` | Show available commands | + +**Keyboard Shortcuts:** + +| Shortcut | Action | +|----------|--------| +| `Ctrl+J` | Insert newline (multi-line input) | +| `Shift+Enter` | Insert newline | +| `@filename` | Add file to context | +| `Ctrl+C` | Cancel / Exit | + +**Supported Providers:** + +| Provider | Models | API Key Required | +|----------|--------|------------------| +| **OpenAI** | GPT-4o, GPT-4, GPT-3.5 | Yes (`OPENAI_API_KEY`) | +| **Anthropic** | Claude 3 (Sonnet, Opus, Haiku) | Yes (`ANTHROPIC_API_KEY`) | +| **Bedrock** | Claude via AWS | Yes (AWS credentials) | +| **Ollama** | Llama 3.2, Mistral, etc. | No (local) | + +**Setup:** ```bash -# Validate generated IaC files (not yet implemented) -sync-ctl validate . +# OpenAI +export OPENAI_API_KEY="sk-..." -# Validate specific types (planned) -sync-ctl validate . --types dockerfile,compose +# Anthropic +export ANTHROPIC_API_KEY="sk-ant-..." -# Auto-fix issues (planned) -sync-ctl validate . --fix +# Ollama (no key needed, install Ollama first) +# Download from https://ollama.ai +``` + +**What the Agent Can Do:** +- Generate Dockerfiles, Docker Compose, Kubernetes manifests, Terraform configs +- Analyze your codebase and detect 260+ technologies +- Security scanning and vulnerability detection +- Create CI/CD pipelines (GitHub Actions, GitLab CI) +- Answer questions about your project structure +- Suggest optimizations and best practices + +--- + +### 10. `sync-ctl auth ` + +Authenticate with the Syncable platform. + +#### 10a. `sync-ctl auth login` + +Log in to Syncable (opens browser for authentication). + +**Options:** + +| Flag | Description | +|------|-------------| +| `--no-browser` | Don't open browser automatically | + +**Examples:** + +```bash +# Login (opens browser) +sync-ctl auth login + +# Login without auto-opening browser +sync-ctl auth login --no-browser ``` -## 📋 Information Commands +#### 10b. `sync-ctl auth logout` + +Log out and clear stored credentials. -### 9. Support Information +**Examples:** ```bash -# Show supported languages -sync-ctl support --languages +sync-ctl auth logout +``` -# Show supported frameworks -sync-ctl support --frameworks +#### 10c. `sync-ctl auth status` -# Show all supported technologies -sync-ctl support +Show current authentication status. -# Detailed support information -sync-ctl support --detailed +**Examples:** + +```bash +sync-ctl auth status ``` -## 🎯 Advanced Usage Examples +#### 10d. `sync-ctl auth token` + +Print current access token (for scripting). + +**Options:** + +| Flag | Description | +|------|-------------| +| `--raw` | Print raw token without formatting | + +**Examples:** + +```bash +# Show formatted token +sync-ctl auth token + +# Raw token for scripting +sync-ctl auth token --raw + +# Use in API calls +curl -H "Authorization: Bearer $(sync-ctl auth token --raw)" https://api.syncable.dev/ +``` + +--- + +## ⚙️ Configuration + +### Configuration File (`.syncable.toml`) + +Place in your project root or `~/.config/syncable/config.toml`: + +```toml +[agent] +default_provider = "anthropic" +default_model = "claude-sonnet-4-20250514" + +[security] +default_mode = "thorough" +fail_on_high_severity = true + +[analysis] +ignore_patterns = ["node_modules", "target", "dist", ".git"] + +[telemetry] +enabled = true +``` + +**Configuration Options:** + +#### `[agent]` Section +- `default_provider` — Default LLM provider (`openai`, `anthropic`, `bedrock`, `ollama`) +- `default_model` — Default model name (e.g., `gpt-4o`, `claude-3-5-sonnet-latest`) + +#### `[security]` Section +- `default_mode` — Default security scan mode (`lightning`, `fast`, `balanced`, `thorough`, `paranoid`) +- `fail_on_high_severity` — Exit with error on high severity findings (boolean) + +#### `[analysis]` Section +- `ignore_patterns` — Patterns to ignore during analysis (array of strings) + +#### `[telemetry]` Section +- `enabled` — Enable/disable telemetry (boolean) + +--- + +## 🎯 Common Workflows ### Complete Project Analysis Workflow @@ -234,13 +791,14 @@ sync-ctl generate . --all sync-ctl analyze . --display summary # Security scan that fails on findings -sync-ctl security . --fail-on-findings +sync-ctl security . --mode fast --fail-on-findings -# Vulnerability scan with threshold +# Vulnerability scan with threshold (fails on critical/high) sync-ctl vulnerabilities . --severity high # JSON reports for processing sync-ctl dependencies . --vulnerabilities --format json > deps.json +sync-ctl security . --format json --output security.json ``` ### Monorepo Analysis @@ -255,42 +813,110 @@ sync-ctl analyze . --display matrix # Individual project analysis cd frontend && sync-ctl analyze . --display detailed cd ../backend && sync-ctl analyze . --display detailed + +# Security scan across entire monorepo +sync-ctl security . --mode thorough +``` + +### Security Audit + +```bash +# Comprehensive security analysis +sync-ctl security . --mode paranoid --include-low + +# Check vulnerabilities +sync-ctl vulnerabilities . --severity low + +# Export reports +sync-ctl security . --output security-report.json --format json +sync-ctl vulnerabilities . --output vuln-report.json --format json + +# Fail on findings (for compliance) +sync-ctl security . --fail-on-findings ``` -## 🔧 Global Configuration Options - -### Global Flags (Available for all commands) -- `--config ` - Custom configuration file -- `--verbose` / `-v` - Verbose output (-v info, -vv debug, -vvv trace) -- `--quiet` - Suppress all output except errors -- `--json` - JSON output format where applicable -- `--clear-update-cache` - Force update check - -### Command-Specific Options - -#### Analysis Options -- `--display ` - matrix (default), detailed, summary -- `--only ` - Analyze specific components only -- `--json` - JSON output for the analyze command - -#### Security Options -- `--mode ` - lightning, fast, balanced, thorough, paranoid -- `--include-low` - Include low-severity findings -- `--no-secrets` - Skip secret detection -- `--no-code-patterns` - Skip code pattern analysis -- `--fail-on-findings` - Exit with error on security issues - -#### Generation Options -- `--output ` - Custom output directory -- `--dry-run` - Preview without creating files -- `--force` - Overwrite existing files -- `--all` - Generate all IaC types - -#### Tool Options -- `--languages ` - Target specific languages -- `--include-owasp` - Include OWASP Dependency Check -- `--dry-run` - Preview installation -- `--yes` - Skip confirmation prompts +### Development Workflow + +```bash +# Quick analysis before commit +sync-ctl analyze . --display summary + +# Fast security scan +sync-ctl security . --mode lightning + +# Generate Dockerfile for new service +sync-ctl generate . --dockerfile + +# Ask AI for help +sync-ctl chat --query "How do I optimize this Dockerfile?" +``` + +### Pre-commit Hook + +```bash +# .git/hooks/pre-commit +#!/bin/bash +sync-ctl security . --mode lightning --fail-on-findings +``` + +--- + +## 🔌 VS Code Integration + +Install the **Syncable IDE Companion** extension for enhanced AI chat experience: + +```bash +code --install-extension syncable.syncable-ide-companion +``` + +**Features:** +- **Native diff views** — Review file changes side-by-side in VS Code +- **One-click accept/reject** — Accept with `Cmd+S` or reject changes easily +- **Auto-detection** — Works automatically when running `sync-ctl chat` in VS Code's terminal + +**Without the extension:** +- The agent still works but shows diffs in the terminal instead + +--- + +## 🌍 Environment Variables + +| Variable | Description | +|----------|-------------| +| `OPENAI_API_KEY` | OpenAI API key for chat (required for OpenAI provider) | +| `ANTHROPIC_API_KEY` | Anthropic API key for chat (required for Anthropic provider) | +| `SYNC_CTL_DEBUG` | Enable debug logging (set to any value) | +| `CARGO_PKG_VERSION` | CLI version (auto-set by Cargo) | + +**Setup:** + +```bash +# OpenAI +export OPENAI_API_KEY="sk-..." + +# Anthropic +export ANTHROPIC_API_KEY="sk-ant-..." + +# Debug mode +export SYNC_CTL_DEBUG=1 +``` + +--- + +## 🚦 Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Success | +| `1` | Error occurred or security findings detected | + +**Exit Code Behavior:** + +- **`vulnerabilities` command**: Exits with `1` if critical or high severity vulnerabilities are found +- **`security` command**: Exits with `1` when `--fail-on-findings` is used and findings are detected +- **All commands**: Exits with `1` on any error + +--- ## 💡 Pro Tips @@ -302,28 +928,36 @@ cd ../backend && sync-ctl analyze . --display detailed 6. **For Automation**: Use `--json` output with other tools 7. **For Teams**: Share vulnerability reports with `--output` option 8. **For Updates**: Use `--clear-update-cache` to force update checks +9. **For Monorepos**: Use matrix view to see all projects at once +10. **For AI Help**: Use `sync-ctl chat` for interactive assistance + +--- ## 🚀 Implementation Status ### ✅ Fully Implemented -- **analyze** - Project analysis with multiple display modes -- **security** - Turbo security engine with 5 scan modes -- **vulnerabilities** - Dependency vulnerability scanning -- **dependencies** - Comprehensive dependency analysis -- **support** - Technology support information -- **tools** - Vulnerability tool management +- **analyze** — Project analysis with multiple display modes +- **security** — Turbo security engine with 5 scan modes +- **vulnerabilities** — Dependency vulnerability scanning +- **dependencies** — Comprehensive dependency analysis +- **support** — Technology support information +- **tools** — Vulnerability tool management +- **chat** — AI assistant with multiple providers +- **auth** — Platform authentication ### 🚧 In Development -- **validate** - IaC validation and best practices checking -- **generate** - IaC file generation (Dockerfile, Compose, Terraform) +- **generate** — IaC file generation (basic implementation done) - Enhanced monorepo generation with per-project IaC files - Advanced compliance framework checking ### 🔮 Coming Soon -- **Cloud Integration** - Deploy directly to cloud platforms -- **Monitoring Setup** - Automated monitoring configuration -- **Performance Analysis** - Resource optimization recommendations -- **Interactive Mode** - Guided setup and configuration wizard +- **validate** — IaC validation and best practices checking +- **Cloud Integration** — Deploy directly to cloud platforms +- **Monitoring Setup** — Automated monitoring configuration +- **Performance Analysis** — Resource optimization recommendations +- **Interactive Mode** — Guided setup and configuration wizard + +--- ## 📖 Getting Help @@ -331,8 +965,25 @@ cd ../backend && sync-ctl analyze . --display detailed # Get help with any command sync-ctl --help # Show all available commands sync-ctl analyze --help # Show analyze command options +sync-ctl generate --help # Show generation options sync-ctl security --help # Show security scanning options sync-ctl vulnerabilities --help # Show vulnerability check options -sync-ctl generate --help # Show generation options +sync-ctl dependencies --help # Show dependency analysis options sync-ctl tools --help # Show tool management options -``` \ No newline at end of file +sync-ctl chat --help # Show AI chat options +sync-ctl auth --help # Show authentication options +``` + +--- + +## 📚 Additional Resources + +- **GitHub**: [github.com/syncable-dev/syncable-cli](https://github.com/syncable-dev/syncable-cli) +- **Website**: [syncable.dev](https://syncable.dev) +- **Issues**: [github.com/syncable-dev/syncable-cli/issues](https://github.com/syncable-dev/syncable-cli/issues) +- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md) +- **Changelog**: [CHANGELOG.md](../CHANGELOG.md) + +--- + +**Built with 🦀 Rust** — Your AI-Powered DevOps Engineer in the Terminal diff --git a/src/agent/mod.rs b/src/agent/mod.rs index b054ee9f..9f28cc13 100644 --- a/src/agent/mod.rs +++ b/src/agent/mod.rs @@ -259,7 +259,119 @@ pub async fn run_interactive( raw_chat_history.clear(); } match session.process_command(&input) { - Ok(true) => continue, + Ok(true) => { + // Check if /resume loaded a session + if let Some(record) = session.pending_resume.take() { + // Display previous messages + println!(); + println!("{}", "─── Previous Conversation ───".dimmed()); + for msg in &record.messages { + match msg.role { + persistence::MessageRole::User => { + println!(); + println!( + "{} {}", + "You:".cyan().bold(), + truncate_string(&msg.content, 500) + ); + } + persistence::MessageRole::Assistant => { + println!(); + // Show tool calls if any (same format as live display) + if let Some(ref tools) = msg.tool_calls { + for tc in tools { + // Match live tool display: green dot for completed, cyan bold name + if tc.args_summary.is_empty() { + println!( + "{} {}", + "●".green(), + tc.name.cyan().bold() + ); + } else { + println!( + "{} {}({})", + "●".green(), + tc.name.cyan().bold(), + truncate_string(&tc.args_summary, 50).dimmed() + ); + } + } + } + // Show response (same ResponseFormatter as live) + if !msg.content.is_empty() { + ResponseFormatter::print_response(&truncate_string( + &msg.content, + 1000, + )); + } + } + persistence::MessageRole::System => { + // Skip system messages in display + } + } + } + println!("{}", "─── End of History ───".dimmed()); + println!(); + + // Load messages into raw_chat_history for AI context + for msg in &record.messages { + match msg.role { + persistence::MessageRole::User => { + raw_chat_history.push(rig::completion::Message::User { + content: rig::one_or_many::OneOrMany::one( + rig::completion::message::UserContent::text( + &msg.content, + ), + ), + }); + } + persistence::MessageRole::Assistant => { + raw_chat_history.push(rig::completion::Message::Assistant { + id: Some(msg.id.clone()), + content: rig::one_or_many::OneOrMany::one( + rig::completion::message::AssistantContent::text( + &msg.content, + ), + ), + }); + } + persistence::MessageRole::System => {} + } + } + + // Load into conversation_history for context tracking + for msg in &record.messages { + if msg.role == persistence::MessageRole::User { + // Find the next assistant message + let response = record + .messages + .iter() + .skip_while(|m| m.id != msg.id) + .skip(1) + .find(|m| m.role == persistence::MessageRole::Assistant) + .map(|m| m.content.clone()) + .unwrap_or_default(); + + conversation_history.add_turn( + msg.content.clone(), + response, + vec![], // Tool calls not loaded for simplicity + ); + } + } + + println!( + "{}", + format!( + " ✓ Loaded {} messages. You can now continue the conversation.", + record.messages.len() + ) + .green() + ); + println!(); + } + continue; + } Ok(false) => break, // /exit Err(e) => { eprintln!("{}", format!("Error: {}", e).red()); diff --git a/src/agent/session.rs b/src/agent/session.rs index 59291e4c..57cdbf5f 100644 --- a/src/agent/session.rs +++ b/src/agent/session.rs @@ -177,6 +177,8 @@ pub struct ChatSession { pub token_usage: TokenUsage, /// Current planning mode state pub plan_mode: PlanMode, + /// Session loaded via /resume command, to be processed by main loop + pub pending_resume: Option, } impl ChatSession { @@ -194,6 +196,7 @@ impl ChatSession { history: Vec::new(), token_usage: TokenUsage::new(), plan_mode: PlanMode::default(), + pending_resume: None, } } @@ -1422,7 +1425,8 @@ impl ChatSession { } /// Handle /resume command - browse and select a session to resume - pub fn handle_resume_command(&self) -> AgentResult<()> { + /// Returns true if a session was loaded and should be displayed + pub fn handle_resume_command(&mut self) -> AgentResult { use crate::agent::persistence::{SessionSelector, browse_sessions, format_relative_time}; let selector = SessionSelector::new(&self.project_path); @@ -1437,28 +1441,35 @@ impl ChatSession { "{}", "Sessions are automatically saved during conversations.".dimmed() ); - return Ok(()); + return Ok(false); } // Show the interactive browser if let Some(selected) = browse_sessions(&self.project_path) { - // User selected a session + // User selected a session - load it let time = format_relative_time(selected.last_updated); - println!( - "\n{} Selected: {} ({}, {} messages)", - "✓".green(), - selected.display_name.white().bold(), - time.dimmed(), - selected.message_count - ); - println!( - "{}", - "Note: To load the session, restart with: sync-ctl chat --resume ".dimmed() - ); - println!(" Session ID: {}", selected.id.cyan()); + + match selector.load_conversation(&selected) { + Ok(record) => { + println!( + "\n{} Resuming: {} ({}, {} messages)", + "✓".green(), + selected.display_name.white().bold(), + time.dimmed(), + record.messages.len() + ); + + // Store for main loop to process + self.pending_resume = Some(record); + return Ok(true); + } + Err(e) => { + eprintln!("{} Failed to load session: {}", "✗".red(), e); + } + } } - Ok(()) + Ok(false) } /// Handle /sessions command - list available sessions @@ -1834,9 +1845,9 @@ impl ChatSession { self.handle_plans_command()?; } "/resume" | "/s" => { - // Resume is handled specially - needs to return session data - // The command just shows the browser, actual loading happens in mod.rs - self.handle_resume_command()?; + // Resume loads session into self.pending_resume + // Main loop in mod.rs will detect and process it + let _ = self.handle_resume_command()?; } "/sessions" | "/ls" => { self.handle_list_sessions_command();