scai 0.1.84 → 0.1.85

package/README.md

@@ -0,0 +1,452 @@
+# ⚙️ scai — Smart Commit AI ✨
+
+> AI-powered CLI tool for commit messages **and** pull request reviews — using local models.
+
+**scai** is your AI pair‑programmer in the terminal. Focus on coding while scai:
+
+- 🤖 **Reviews open pull requests** and provides AI‑driven feedback (BETA)  
+- 💬 **Suggests intelligent Git commit messages** based on your staged diff  
+- 📝 Summarizes files in plain English  
+- 📜 Auto‑updates your changelog  
+- 🔍 (ALPHA) Search & ask questions across your codebase  
+- 🔐 100% local — no API keys, no cloud, no telemetry  
+
+---
+
+## 🚀 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  
+
+---
+
+## ❤️ 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  
+
+---
+
+## 📦 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
+   ```
+
+## ✨ AI Code Review, Powered by Your Terminal
+
+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.
+
+> ⚠️ These features are in **beta** — feedback welcome!
+Ping [@ticcr](https://bsky.app/profile/ticcr.xyz) on Bluesky — I'd love to hear your thoughts!
+
+---
+
+### 🔑 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
+   ```
+
+3. **Set the index dir:**
+
+   ```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 review`
+
+```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
+```
+
+
+
+### 🔧  How to Use `scai git commit`
+
+Use AI to suggest a meaningful commit message based on your staged code:
+
+```bash
+git add .
+scai git commit
+```
+
+You can also include a changelog entry along with the commit:
+
+```bash
+scai git commit --changelog
+```
+
+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
+
+---
+
+### 📝 Generate a Standalone Changelog Entry
+
+If you want to generate a changelog entry without committing:
+
+```bash
+scai gen changelog
+```
+
+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)
+
+```bash
+scai gen summ <file>
+scai gen comm <file>
+scai gen changelog
+scai gen tests <file>
+```
+
+* `summ`: Summarize a file
+* `comm`: Add comments to a file
+* `changelog`: Update or create `CHANGELOG.md` from Git diff
+* `tests`: Create Jest test stubs (ALPHA)
+
+You can also pipe file content directly:
+
+```bash
+cat src/utils/math.ts | scai gen summ
+```
+
+---
+
+## ⚙️ Configuration
+
+scai stores settings in `~/.scai/config.json`. You can override or view them:
+
+* **Set model:**
+
+  ```bash
+  scai set model codellama:7b
+  ```
+* **Set language:**
+
+  ```bash
+  scai set lang ts
+  ```
+* **Show config:**
+
+  ```bash
+  scai config
+  ```
+
+<br>
+
+## 🔁 Background Daemon and Indexing ⚠️ ALPHA Notice
+
+These features are experimental and subject to change:
+
+* `index`, `find`, `ask`
+* `daemon`, `stop-daemon`
+* `gen tests` (test generation)
+
+<br>
+
+## Commands
+
+### `index`
+The `index` command is used to manage and perform operations on the indexed files and repositories.
+
+#### `scai index start`
+
+Index supported files in the configured index directory.
+
+```bash
+scai index set <dir>
+```
+
+Set and activate the index directory.
+```bash
+scai index list
+```
+
+List all indexed repositories.
+```bash
+scai index switch
+```
+
+Switch active repository (by key or indexDir). Run without input for an interactive list of repositories.
+
+
+--- 
+
+> **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. 
+
+---
+
+### 🔍 Codebase Search & Ask (ALPHA)
+
+> **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:
+
+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.
+
+---
+
+ 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:
+
+```bash
+scai reset-db
+scai index
+```
+</br>
+
+---
+
+## 🛍️ Maintenance & Utilities
+
+* **Reset database (w/ backup):**
+
+  ```bash
+  scai reset-db
+  ```
+* **Backup only of `~/.scai`:**
+
+  ```bash
+  scai backup
+  ```
+
+---
+
+## 🧺 Module Pipeline Mode
+
+For custom pipelines on a single file:
+
+```bash
+scai src/file.ts -m summary,comments
+```
+---
+
+## 🔐 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.
+
+---
+
+</br>
+
+## 🙌 Feedback
+
+Questions, ideas, or bugs?  
+Ping [@ticcr](https://bsky.app/profile/ticcr.xyz) on Bluesky — I'd love to hear your thoughts!
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scai",
-  "version": "0.1.84",
+  "version": "0.1.85",
   "type": "module",
   "bin": {
     "scai": "./dist/index.js"