scai 0.1.117 → 0.1.119

package/README.md

@@ -1,607 +1,192 @@
-# ⚙️ scai — Smart Commit AI ✨
+# ⚙️ SCAI — Source Code AI 🌿
 
-> AI-powered CLI tool for commit messages, pull request reviews, **and agent-driven workflows** — using local models.
+> **AI-powered CLI for local code analysis, commit message suggestions, and natural-language queries.** 100% local, private, GDPR-friendly, made in Denmark/EU with ❤️.
 
-**scai** is your AI pair‑programmer in the terminal. Focus on coding while scai:
+SCAI is your AI coding companion in the terminal. Focus on coding while Scai helps you understand, comment, and analyze your code. **Local Model Note:** Using local LLMs ensures privacy and offline usage, and **NO token cost, but capabilities are more limited compared to cloud-hosted AI.**
 
-* 💬 **Suggests intelligent Git commit messages** based on your staged diff
-* 🤖 **Reviews open pull requests** and provides AI‑driven feedback (BETA)
-* 📝 **Generates comments for multiple files** while you keep coding
-* 🤖 **Runs agent workflows** to automate repetitive tasks like summarizing, commenting, or running tests — run agents on single files or entire folders with custom goals
-* 📜 Auto‑updates your changelog
-* 🔍 (ALPHA) Search & ask questions across your codebase
-* 🔐 100% local — no API keys, no cloud, no telemetry
+> ⚠️ **Alpha Version Notice:** If you have previously installed Scai, please run `scai db reset && scai index start` before using this version.
 
 ---
 
-### 🧩 Agent Mode Examples
+## 💻 Getting Started
 
-Run an agent workflow with goals:
+### 1️⃣ Install & Initialize
 
 ```bash
-# Run comments and tests on a single file
-$ scai agent run comments tests -f path/to/myfile
-
-# Run summary on all files in a folder
-$ scai agent run summary -f path/to/myfolder
+npm install -g scai
+scai init
+scai index start
 ```
 
-The agent mode allows you to chain goals (`summary → comments → tests`) while processing files or directories automatically, keeping your workflow fast and focused.
-
-
----
-
-## 🚀 Features
-
-- ⚡ Powered by open-source models (e.g. `llama3`, `codellama`)  
-- 🔍 Full-text indexing & semantic search (ALPHA)  
-- 🛠️ Built with Node.js and TypeScript  
-- ✅ Easily configurable via CLI or global flags  
+This will initialize local models (recommended: `qwen3-coder:30b`) and start indexing your code repository.
 
----
-
-## ❤️ Why Local AI?
-
-**Your code stays yours.**  
-scai runs entirely on your machine and doesn't require cloud APIs or API keys. That means:
-
-- ✅ **Privacy-first**: no telemetry, no server round-trips  
-- ✅ **EU & GDPR-friendly**: designed with compliance in mind  
-- ✅ **Developer control**: full transparency and override options  
-- ✅ **Offline support**: works even without an internet connection  
-
----
+### 2️⃣ Check Available Commands
 
-## 📦 Installation
-
-1. **Install Ollama (for local models)**  
-   - macOS: `brew install ollama`  
-   - Windows: [Download here](https://ollama.com/download)  
-   - Start Ollama after installing.
-
-2. **Install scai globally:**  
-   ```bash
-   npm install -g scai
-    ```
-
-3. **Initialize models:**
-
-   ```bash
-   scai init
-   ```
+```bash
+scai --help
+```
 
 ---
 
-## 🤖 Agent Workflow Command
+## 🏠 REPL Mode (Local AI Queries)
 
-The `agent` command allows you to run a sequence of AI-powered workflows (goals) on one or multiple files or even an entire folder. This is useful for tasks like generating comments, summaries, or tests, while letting the AI work in the background as you continue coding.
-
-### Usage
+Start an interactive REPL to ask natural-language questions about your code:
 
 ```bash
-# Run agent with comments and tests on a single file
-scai agent run comments tests -f path/to/file.ts
-
-# Run agent on an entire folder
-scai agent run comments tests -f path/to/folder
+scai shell
 ```
 
-You can provide multiple goals, which will be executed in the order specified. Currently supported example goals:
-
-* `summary` – Summarize a file
-* `comments` – Add inline comments to code
-* `tests` – Generate test stubs (ALPHA)
+Once in the REPL, you can:
 
-#### Features
+* Ask questions freely about your codebase:
 
-* ✅ Works on single files or entire folders recursively
-* ✅ Processes multiple files in the background, so you can continue coding
-* ✅ Modular design allows you to chain goals (e.g., `comments → tests → summary`)
-
-#### Notes
+```text
+scai> How many functions in spatialmap.js are missing tests?
+scai> Summarize utils/helpers.ts
+scai> Where are all the database queries defined?
+scai> List files involved in authentication
+```
 
-* Only `summary`, `comments`, and `tests` are currently fully supported. Other modules are experimental.
-* The agent resolves folders into all supported files (`.ts`, `.js`, etc.) automatically.
-* Background processing allows you to queue multiple files without waiting for each one to finish interactively.
+* Run slash commands inside the REPL for standard CLI operations:
 
----
+```text
+scai> /git commit
+scai> /index list
+scai> /index set /path/to/repo
+scai> /index switch
+scai> /index delete
+```
 
-## ✨ AI Code Review, Powered by Your Terminal
+* Execute shell commands directly:
 
-No more struggling to write pull request descriptions by hand. `scai git review` automatically generates a rich summary of your changes, complete with context, suggestions, and rationale.
+```text
+scai> !ls -la
+scai> !git status
+```
 
-> ⚠️ These features are in **beta** — feedback welcome!
-Ping [@ticcr](https://bsky.app/profile/ticcr.xyz) on Bluesky — I'd love to hear your thoughts!
+> ✅ Asking questions in the REPL is free, GDPR-friendly, and entirely local.
 
 ---
 
-### 🔑 Setting Up Authentication (Required)
-
-To interact with GitHub and create pull requests, `scai` needs a personal access token with **repo** permissions.
-
-1. **Create your GitHub Access Token**
-   Follow this link to generate a token: [https://github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens)
-
-   Make sure you enable at least:
-
-   * `repo` (Full control of private repositories)
-   * `workflow` (If you want PRs to trigger CI)
-
-2. **Set the token in scai:**
-
-   ```bash
-   scai auth set
-   ```
-
-   This stores your token locally in a secure config file. You can inspect the setup at any time:
-
-   ```bash
-   scai auth check
-   ```
+## 📦 Indexing Commands
 
-3. **Set the index dir:**
+Before asking questions, you should index your code repository:
 
-   ```bash
-   scai index set /path/to/repo
-   ```
-
-   This is the repo from which scai will look up pull requests that can be reviewed. 
-
----
-## ⚒️ Usage Overview
-
-### 🔧  How to Use `scai git commit`
-
-Use AI to suggest a meaningful commit message based on your staged code:
+* **Set index directory**
 
 ```bash
-git add .
-scai git commit
+scai index set /path/to/repo
 ```
 
-You can also include a changelog entry along with the commit:
+* **Start indexing**
 
 ```bash
-scai git commit --changelog
+scai index start
 ```
 
-This will:
-1. Suggest a commit message based on your `git diff --cached`
-2. Propose a changelog entry (if relevant)
-3. Allow you to approve, regenerate, or skip the changelog
-4. Automatically stage and commit the changes
-
----
-
-### 🧠 How to Use `scai git review`
+* **List all indexed repositories**
 
 ```bash
-scai git review
-```
-
-This will show you pull requests assigned to you for review:
-
-* Understand the diffs using a local model
-* Generate a structured pull request:
-
-  * ✅ Title
-  * ✅ Summary of changes
-  * ✅ Explanation of why the changes matter
-  * ✅ Optional changelog bullets
-
-
-SCAI supports an integrated review flow for GitHub pull requests. To get started:
-
-1. **Set your working index directory (once per repo):**
-
-   ```sh
-   scai index set /path/to/repo
-   ```
-
-2. **Authenticate with GitHub:**
-   ```sh
-   scai git review
-   ```
-
-   This command will query you for the Personal Access Token and set it for you. 
-   You may also do this with the auth commands below
-
-   ```sh
-   scai auth set
-   scai auth check
-   ```
-
-3. **Fetch and review pull requests:**
-
-   ```sh
-   scai git review
-   ```
-
-   Use `-a` to list all PRs that require a review:
-
-   ```sh
-   scai git review -a
-   ```
-
-#### Example Workflow
-
-```sh
-$ scai git review -a
-📦 Resolving GitHub repo info from indexDir: ./
-🔗 Git origin URL: git@github.com:org/repo.git
-✅ Parsed: owner='org', repo='repo'
-👤 Authenticated user: dev-user123
-
-🔍 Fetching pull requests and diffs...
-✅ Fetched 5 PR(s) with diffs.
-
-📦 Open Pull Requests with review requested:
-| # | ID   | TITLE                         | AUTHOR     | STATUS | CREATED    | REVIEWERS                     | REVIEWS             |
-| - | ---- | ----------------------------- | ---------- | ------ | ---------- | ----------------------------- | ------------------- |
-| 1 | #120 | fix/session-timeout         | dev-alice  | Open   | 2025-08-08 | code-analyzer\[bot], dev-bob  | ✅ Approved          |
-| 2 | #118 | feature/1482-support-wfs2   | dev-carol  | Open   | 2025-08-07 | code-analyzer\[bot], dev-dave | ✅ Approved          |
-| 3 | #117 | refactor/win-server-support | dev-erin   | Open   | 2025-08-06 | dev-frank, dev-alice          | ❌ Changes Requested |
-| 4 | #114 | bump/vue-i18n-9.14.5        | dependabot | Open   | 2025-08-04 | code-analyzer\[bot]           | ✅ Approved          |
-| 5 | #113 | bugfix/null-navigator-check | dev-bob    | Open   | 2025-08-03 | dev-alice, dev-carol          | ✅ Approved          |
-
-👉 Choose a PR to review [1-2]: 1
-✅ Model response received.
-
-💡 AI-suggested review:
-
-Solid improvement — this patch improves session stability and handles async state more reliably. 
-You might consider renaming `sessionManager` to better reflect its dual role in auth and persistence.
-
----
-1) ✅ Approve
-2) ❌ Reject
-3) ✍️ Edit
-4) Write your own review
-5) 🚪 Cancel
+scai index list
 ```
 
-### 📝 Generate a Standalone Changelog Entry
-
-If you want to generate a changelog entry without committing:
+* **Switch active repository**
 
 ```bash
-scai gen changelog
+scai index switch
 ```
 
-This will:
-- Analyze the current `git diff` (staged or unstaged)
-- Propose a list of **user-facing changes** in clean markdown bullet points
-- Let you accept, regenerate, or skip the update
-- Append the entry to `CHANGELOG.md` and stage it if accepted
-
-
-### 🛠️ Code Generation Commands (`gen` group)
+* **Delete a repository from index**
 
 ```bash
-scai gen comm <file|folder...>
-scai gen summ <file>
-scai gen changelog
-scai gen tests <file>
+scai index delete
 ```
 
-* `comm`: Add comments to one or more files, or to all matching files in a folder (recursive).
-
-   </br>
-
-  ```bash
-  scai gen comm src/ utils/helpers.ts
-  ```
-
-  </br>
-
-  This will add comments to all `.ts` and `.js` files under `src/` and to `utils/helpers.ts`.
-
-  </br>
-
-* `summ`: Summarize a file
-
-   You can also pipe file content directly:
-
-   ```bash
-   cat src/utils/math.ts | scai gen summ
-   ```
-
-   </br>
-
-
-* `changelog`: Update or create `CHANGELOG.md` from Git diff
-
-* `tests`: Create Jest test stubs (ALPHA)
+> Only indexed repositories can be queried by scai.
 
 ---
 
 ## ⚙️ Configuration
 
-scai stores settings in `~/.scai/config.json`. You can override or view them:
-
-* **Set model:**
-
-  ```bash
-  scai config set-model codellama:7b
-  ```
-* **Set language:**
-
-  ```bash
-  scai config set-lang ts
-  ```
-* **Show config:**
-
-  To see the config for the active repo
-  ```bash
-  scai config show
-  ```
-
-  To see the config for all repos
-
-    ```bash
-  scai config show --raw 
-  ```
-
----
-
-## Commands
-
-### `index`
-The `index` command is used to manage and perform operations on the indexed files and repositories. It allows you to control which repository you're working with and have indexed. 
-
-#### `scai index start`
-
-Index supported files in the configured index directory.
-
-```bash
-scai index set <dir>
-```
-
-Or just this for cwd (current working dir)
+Set the AI model for local usage (recommended: `qwen3-coder:30b`):
 
 ```bash
-scai index set
+scai config set-model qwen3-coder:30b
 ```
 
-Set and activate the index directory.
-```bash
-scai index list
-```
+Check current configuration:
 
-List all indexed repositories.
 ```bash
-scai index switch
+scai config show --raw
 ```
 
-Switch active repository (by key or indexDir). Run without input for an interactive list of repositories.
+---
 
-#### `scai index delete`
+## 🔧 Git Commit Assistant
 
-Delete a repository from the index (interactive).  
-This removes the repository entry from the `config.json` file, but does **not** delete the repository folder on disk.
+Use AI to suggest meaningful commit messages based on your staged changes:
 
 ```bash
-scai index delete
+git add .
+scai git commit
 ```
 
---- 
-
-## 🛍️ Maintenance & Utilities
-# Database Commands
-
-Your CLI now supports a set of **database management commands** under the `db` namespace. These commands allow you to check the status of the database, reset it, or run migrations.
+This generates a commit message reflecting your changes and context, entirely locally.
 
 ---
 
-### 📋 Available Commands
-
-#### 🔍 Check Database
-
-```bash
-scai db check
-```
+## 🔑 GitHub Authentication
 
-Runs the **dbcheck** script to verify the database status.
+To work with GitHub for repositories, scai needs a Personal Access Token:
 
-* Useful for quickly checking if the database is healthy.
-* Prints detailed output directly in the console.
-
----
-
-#### ♻️ Reset Database
+* **Set your token:**
 
 ```bash
-scai db reset
+scai auth set
 ```
 
-Deletes and resets the SQLite database.
-
-* Will ask for confirmation before proceeding.
-* Respond with `y` or `Y` to confirm.
-* Any other key (including `n`, `N`, or just pressing **Enter**) will cancel the reset.
-
----
-
-#### 📦 Run Migrations
+* **Check your token:**
 
 ```bash
-scai db migrate
+scai auth check
 ```
 
-Executes all database migration scripts.
-
-Note the **Migrate** command is for **internal use only**. Do **not** run it unless explicitly instructed, as it may delete existing data or corrupt your local database.
-
-If you're upgrading from an earlier version, please run the following commands to avoid indexing issues:
+* **Reset your token:**
 
 ```bash
-scai db reset
-scai index
+scai auth reset
 ```
-</br>
-
----
-
-### ✅ Example Workflow
-
-1. **Check** current database state:
-
-   ```bash
-   scai db check
-   ```
-
-2. Confirm you're in the correct repo. 
-
-   ```bash
-   scai index list
-   ```
-
-   Use the switch command to switch if necessary.
-   
-   ```bash
-   scai index switch
-   ```
-
-2. If necessary, **reset** the database:
-
-   ```bash
-   scai db reset
-   ```
-
-   → Confirm with `y` when prompted.
-   
-   </br>
 
 ---
 
-## 🔁 Background Daemon and Indexing ⚠️ ALPHA Notice
-
-These features are experimental and subject to change:
-
-* `find`, `ask`
-* `daemon`, `stop-daemon`
-* `gen tests` (test generation)
-
-<br>
+## 🧠 Example Queries in REPL
 
-> **Note:** Indexing very large repositories (millions of lines) may take **hours or days**. Please be patient, and only index huge codebases if you are ok with some extra processing taking place on your computer.
-
-The `scai index` command **automatically** starts a background daemon that continuously:
-
-* Scans your target directory
-* Summarizes new or changed files
-* Updates embeddings and the search index
-
-You won't gain much value from the index unless you scope it to one repository. 
+* `Summarize spatialmap.js`
+* `Explain utils/helpers.ts architecture`
+* `List all functions without tests in services/`
+* `Show where database queries are defined`
+* `Highlight potential memory leaks`
+* `Describe how authentication works`
+* `Which files handle error handling in contextReview.ts`
+* `Summarize repo architecture`
 
 ---
 
-> **Important:** You must `index` a **code repository** first or `find` and `ask` have no context to work with.
-
-1. **Set index directory:**
-
-    ```bash
-    scai index set /path/to/repo
-    ```
-
-2. **Index your repo (once):**
-
-   ```bash
-   scai index start
-   ```
-
-3. The daemon is designed to **consume minimal resources** and run unobtrusively. You can control it with:
-
-    ```bash
-    scai daemon        # Start or show daemon status
-    scai stop-daemon   # Stop the background indexer
-    ```
-
-
-4. **Keyword search:**
-
-   ```bash
-   scai find YourClassName
-   ```
-
-5. **Natural-language questions:**
-
-### 🧠 Natural-language questions
-
-Ask questions about your codebase using `scai ask`.
-
-You can run it in two ways:
+## 🔐 Privacy & GDPR
 
-1. **Inline question**
-
-   ```bash
-   scai ask "How does the controller work?"
-   ```
-
-2. **Interactive prompt**
-
-   ```bash
-   scai ask
-   ```
-
-   **Press enter**
-   , then type your question when prompted:
-
-   ```
-   > How does the controller work?
-   ```
-
-   </br>
-
-### 🚨 **OBS** 🚨
-
-`find` and `ask` rely on that index—without it they will return no useful results.
+* Fully local — no API keys, no cloud
+* GDPR-friendly, made in Denmark/EU with love ❤️
+* Free to ask questions about your code
 
 ---
 
-### Backup only of `~/.scai`:
-
-Creates a backup of the .scai folder in the user root dir. 
-
-  ```bash
-  scai backup
-  ```
-
-Results in this:
-~/.scai_backup_2025-08-12T06-58-00-227Z/
+## 🙌 Feedback & Support
 
-</br>
+Reach out with feedback or questions:
 
-## 🔐 License & Fair Use
-
-**scai is free to use** for individuals, teams, and commercial projects.
-
-You may:
-
-* ✅ Use internally or commercially
-* ✅ Fork and improve
-* ✅ Recommend to others
-
-You may **not**:
-
-* ❌ Resell as a product or service
-* ❌ Claim ownership of the tool
-
-</br>
-
-### 📄 License
-
-Free for personal and internal company use only.
-Commercial use (resale, SaaS, inclusion in paid tools) is prohibited.
-Contact me for commercial licensing.
+* Threads: [@scai.dk](https://threads.net/@scai.dk)
+* Bugs, feature requests, or ideas welcome!
 
 ---
 
-</br>
-
-## 🙌 Feedback
-
-Questions, ideas, or bugs?  
-Ping [@ticcr](https://bsky.app/profile/ticcr.xyz) on Bluesky — I'd love to hear your thoughts!
-
----
+Enjoy your AI-powered coding companion, fully local, private, and developer-friendly!