scai 0.1.122 → 0.1.123

package/README.md

@@ -1,10 +1,34 @@
 # ⚙️ SCAI — Source Code AI 🌿
 
-> **AI-powered CLI for local code analysis, commit message suggestions, and natural-language queries.** 100% local, private, GDPR-friendly, made in Denmark/EU with ❤️.
+> **AI-powered CLI for local code analysis, commit message suggestions, and natural-language queries.**
+> **100% local • No token cost • Private by design • GDPR-friendly** — made in Denmark/EU with ❤️.
 
-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.**
+🔗 **Website:** [https://scai.dk](https://scai.dk)
 
-> ⚠️ **Alpha Version Notice:** If you have previously installed Scai, please run `scai db reset && scai index start` before using this version.
+SCAI is your AI coding companion in the terminal. Stay focused on coding while SCAI helps you understand, analyze, and reason about your codebase using local language models.
+
+**Local Model Note:** SCAI runs entirely on local LLMs. This means **no API keys, no token cost, and full privacy**, but also **more limited capabilities** compared to cloud-hosted AI.
+
+> ⚠️ **Alpha Version Notice**
+> If you have previously installed SCAI, please run:
+>
+> ```bash
+> scai db reset && scai index start
+> ```
+>
+> before using this version.
+
+---
+
+## 🗣️ Language Support (Important)
+
+SCAI is currently **tested and validated only on the following languages**:
+
+* **JavaScript (JS)**
+* **TypeScript (TS)**
+* **Java**
+
+Other languages may work partially, but analysis quality, indexing accuracy, and agent behavior are **not guaranteed** outside these languages. Broader language support is planned, but for now SCAI should be considered **JS/TS/Java-first**.
 
 ---
 
@@ -18,7 +42,9 @@ scai init
 scai index start
 ```
 
-This will initialize local models (recommended: `qwen3-coder:30b`) and start indexing your code repository.
+This initializes local models (recommended: `qwen3-coder:30b`) and starts indexing your code repository.
+
+> ⏳ **Note:** Initial indexing and analysis can take **minutes to hours** depending on repository size and enabled analysis tools.
 
 ### 2️⃣ Check Available Commands
 
@@ -38,7 +64,7 @@ scai shell
 
 Once in the REPL, you can:
 
-* Ask questions freely about your codebase:
+### Ask questions about your codebase
 
 ```text
 scai> How many functions in config.js are missing tests?
@@ -47,7 +73,7 @@ scai> Where are all the database queries defined?
 scai> List files involved in authentication
 ```
 
-* Run slash commands inside the REPL for standard CLI operations:
+### Run CLI commands from inside the REPL
 
 ```text
 scai> /git commit
@@ -57,64 +83,72 @@ scai> /index switch
 scai> /index delete
 ```
 
-* Execute shell commands directly:
+### Execute shell commands
 
 ```text
 scai> !ls -la
 scai> !git status
 ```
 
-> ✅ Asking questions in the REPL is free, GDPR-friendly, and entirely local.
+> ✅ REPL queries are free, offline, GDPR-friendly, and **no token cost**.
 
 ---
 
-## 📦 Indexing Commands
+## 📦 Repository Indexing
 
-Before asking questions, you should index your code repository:
+Before SCAI can answer questions, your repository must be indexed.
 
-* **Set index directory**
+### Common Index Commands
 
 ```bash
 scai index set /path/to/repo
+scai index start
+scai index list
+scai index switch
+scai index delete
 ```
 
-* **Start indexing**
+Only indexed repositories can be queried.
 
-```bash
-scai index start
-```
+---
 
-* **List all indexed repositories**
+## 🧠 Background Indexing & Analysis (Daemon)
 
-```bash
-scai index list
-```
+SCAI performs **deep repository indexing and static analysis** using background workers. This includes:
 
-* **Switch active repository**
+* File structure discovery
+* Language-aware parsing (JS / TS / Java)
+* Symbol and dependency mapping
+* Heuristic analysis for tests, architecture, and patterns
 
-```bash
-scai index switch
-```
+⚠️ **Important:** On first install or on large repositories, this process can take **several hours**.
+
+All background work is handled by the **SCAI daemon**, which can be fully controlled from the CLI.
 
-* **Delete a repository from index**
+### Daemon Commands
 
 ```bash
-scai index delete
+scai daemon start
+scai daemon stop
+scai daemon restart
+scai daemon status
+scai daemon unlock
+scai daemon logs
 ```
 
-> Only indexed repositories can be queried by scai.
+You can safely stop the daemon at any time. Indexing and analysis will resume when restarted.
 
 ---
 
 ## ⚙️ Configuration
 
-Set the AI model for local usage (recommended: `qwen3-coder:30b`):
+Set the local AI model (recommended):
 
 ```bash
 scai config set-model qwen3-coder:30b
 ```
 
-Check current configuration:
+View current configuration:
 
 ```bash
 scai config show --raw
@@ -124,42 +158,30 @@ scai config show --raw
 
 ## 🔧 Git Commit Assistant
 
-Use AI to suggest meaningful commit messages based on your staged changes:
+Generate meaningful commit messages based on staged changes:
 
 ```bash
 git add .
 scai git commit
 ```
 
-This generates a commit message reflecting your changes and context, entirely locally.
+All analysis is performed locally — **no token usage, no cloud calls**.
 
 ---
 
 ## 🔑 GitHub Authentication
 
-To work with GitHub for repositories, scai needs a Personal Access Token:
-
-* **Set your token:**
+For GitHub-related features, SCAI requires a Personal Access Token.
 
 ```bash
 scai auth set
-```
-
-* **Check your token:**
-
-```bash
 scai auth check
-```
-
-* **Reset your token:**
-
-```bash
 scai auth reset
 ```
 
 ---
 
-## 🧠 Example Queries in REPL
+## 🧠 Example Queries
 
 * `Summarize codeTransform.js`
 * `Explain utils/helpers.ts architecture`
@@ -167,26 +189,26 @@ scai auth reset
 * `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`
 
 ---
 
 ## 🔐 Privacy & GDPR
 
-* Fully local — no API keys, no cloud
-* GDPR-friendly, made in Denmark/EU with love ❤️
-* Free to ask questions about your code
+* Fully local — no cloud calls
+* No API keys
+* **No token cost**
+* GDPR-friendly, built in Denmark/EU 🇩🇰
 
 ---
 
 ## 🙌 Feedback & Support
 
-Reach out with feedback or questions:
+Feedback, bugs, and ideas are very welcome:
 
-* Threads: [@scai.dk](https://threads.net/@scai.dk)
-* Bugs, feature requests, or ideas welcome!
+* 🌍 Website: [https://scai.dk](https://scai.dk)
+* 🧵 Threads: [@scai.dk](https://threads.net/@scai.dk)
 
 ---
 
-Enjoy your AI-powered coding companion, fully local, private, and developer-friendly!
+Enjoy your **fully local, private, and developer-focused AI coding companion** ✨

package/dist/pipeline/modules/finalAnswerModule.js

@@ -3,58 +3,113 @@ import { generate } from "../../lib/generate.js";
 import chalk from "chalk";
 export const finalAnswerModule = {
     name: "finalAnswer",
-    description: "Generates a final answer using structured context and relevant working files.",
+    description: "Produces the final, post-execution explanation for the user.",
     groups: ["finalize"],
     run: async (input) => {
         const query = input.query;
         const context = input.context;
-        if (!context)
+        if (!context) {
             throw new Error("[finalAnswerModule] No context provided");
+        }
+        // ---------------------------------------------------------------------
+        // Detect execution state
+        // ---------------------------------------------------------------------
         const transformedFiles = context.execution?.codeTransformArtifacts?.files ?? [];
-        const workingFiles = context.workingFiles ?? [];
-        const filesToConsider = transformedFiles.length
+        const hasTransforms = transformedFiles.length > 0;
+        // ---------------------------------------------------------------------
+        // Select authoritative files
+        // ---------------------------------------------------------------------
+        const filesToConsider = hasTransforms
             ? transformedFiles.map(f => ({
                 path: f.filePath,
-                codeSnippet: f.content.slice(0, 500),
                 notes: f.notes,
+                codeSnippet: f.content.slice(0, 500),
             }))
-            : workingFiles.map(f => ({
+            : (context.workingFiles ?? []).map(f => ({
                 path: f.path,
-                codeSnippet: f.code ? f.code.slice(0, 500) : undefined,
                 summary: f.summary ?? "",
+                codeSnippet: f.code ? f.code.slice(0, 500) : undefined,
             }));
-        const analysisSummary = {
+        // ---------------------------------------------------------------------
+        // Analysis framing (before / after)
+        // ---------------------------------------------------------------------
+        const analysisPayload = {
             intent: context.analysis?.intent,
-            fileAnalysis: context.analysis?.fileAnalysis,
+            // BEFORE: what problem was being solved
+            understanding: context.analysis?.understanding,
+            // AFTER: what is now true across the system
             combinedAnalysis: context.analysis?.combinedAnalysis,
-            plan: context.plan,
-            executionArtifacts: context.execution,
+            // Supporting detail (optional but useful)
+            fileAnalysis: context.analysis?.fileAnalysis,
         };
+        // ---------------------------------------------------------------------
+        // Phase-aware prompt construction
+        // ---------------------------------------------------------------------
+        const phasePreamble = hasTransforms
+            ? `
+SYSTEM CONTEXT:
+This is the FINAL STEP in a long, multi-stage execution pipeline.
+
+All planned code transformations have already been executed.
+The files shown represent the FINAL and AUTHORITATIVE state of the codebase.
+
+Your role is to explain what was done and why — not to suggest changes.
+`
+            : `
+SYSTEM CONTEXT:
+This request does not include executed code changes.
+Provide a direct explanation based on the available context.
+`;
+        const instructions = hasTransforms
+            ? `
+INSTRUCTIONS (POST-EXECUTION EXPLANATION MODE):
+
+- Explain the completed changes using past tense.
+- Anchor the explanation in the original problem (understanding).
+- Describe system-wide effects using combinedAnalysis.
+- Refer to transformed files as evidence, not proposals.
+- Mention relevant risks or trade-offs, if any.
+- DO NOT explain how to implement the change.
+- DO NOT suggest additional work.
+- DO NOT ask questions.
+`
+            : `
+INSTRUCTIONS:
+
+- Answer the developer’s question clearly and concisely.
+- Base your response strictly on the provided context.
+- Do not invent changes or assume missing information.
+`;
         const promptText = `
-You are an AI assistant answering a developer query.
+${phasePreamble}
 
-Query:
+You are producing the FINAL ANSWER for this run.
+
+User query:
 ${query}
 
-Analysis summary:
-${JSON.stringify(analysisSummary, null, 2)}
+Analysis:
+${JSON.stringify(analysisPayload, null, 2)}
 
-Target files and content:
+Relevant files (final state):
 ${JSON.stringify(filesToConsider, null, 2)}
 
-Instructions:
-- Provide a clear, concise answer based only on the available files and analysis.
-- Highlight risks or important notes from fileAnalysis or combinedAnalysis.
-- Do not ask for additional files; assume the provided code is authoritative.
-`;
-        const aiResponse = await generate({ query, content: promptText });
+${instructions}
+`.trim();
+        // ---------------------------------------------------------------------
+        // Generate final answer
+        // ---------------------------------------------------------------------
+        const aiResponse = await generate({
+            query,
+            content: promptText,
+        });
         const output = {
             query,
-            content: '',
+            content: "",
             data: aiResponse.data,
         };
         logInputOutput("finalAnswer", "output", output.data);
-        console.log('\n\n\n\n--> Answer: ', chalk.blue(output.data));
+        console.log("\n\n\n\n--> Answer:\n", chalk.blue(output.data));
         return output;
-    }
+    },
 };

package/dist/utils/splitCodeIntoChunk.js

@@ -1,7 +1,5 @@
 import { encode } from 'gpt-3-encoder';
-export function splitCodeIntoChunks(text, softLimit = 1500, // first threshold
-hardLimitMultiplier = 2 // hard limit will be softLimit * multiplier
-) {
+export function splitCodeIntoChunks(text, softLimit = 1500, hardLimitMultiplier = 2) {
     const hardLimit = softLimit * hardLimitMultiplier;
     const lines = text.split('\n');
     const chunks = [];
@@ -10,12 +8,19 @@ hardLimitMultiplier = 2 // hard limit will be softLimit * multiplier
     let inMultiComment = false;
     let inFunction = false;
     let inTryBlock = false;
+    let inTryChain = false;
+    let tryChainHasHandler = false;
     let globalBraceDepth = 0;
     let functionBraceDepth = 0;
+    let tryBraceDepth = 0;
     let parenDepth = 0;
     let bracketDepth = 0;
+    let justClosedFunction = false;
+    let justClosedTryBlock = false;
     for (const line of lines) {
         const trimmed = line.trim();
+        justClosedFunction = false;
+        justClosedTryBlock = false;
         // ---------- comments ----------
         if (trimmed.includes('/*') && !trimmed.includes('*/'))
             inMultiComment = true;
@@ -30,22 +35,40 @@ hardLimitMultiplier = 2 // hard limit will be softLimit * multiplier
             inFunction = true;
             functionBraceDepth = 0;
         }
-        // ---------- try/catch ----------
-        if (trimmed.startsWith('try {'))
+        // ---------- try / catch / finally start ----------
+        if (!inTryChain && trimmed.startsWith('try')) {
+            inTryChain = true;
             inTryBlock = true;
-        if (trimmed.startsWith('catch') || trimmed.startsWith('finally'))
-            inTryBlock = false;
+            tryBraceDepth = 0;
+        }
+        if (inTryChain &&
+            (trimmed.startsWith('catch') || trimmed.startsWith('finally'))) {
+            inTryBlock = true;
+            tryChainHasHandler = true;
+        }
         // ---------- depth tracking ----------
         for (const char of line) {
             if (char === '{') {
                 globalBraceDepth++;
                 if (inFunction)
                     functionBraceDepth++;
+                if (inTryChain)
+                    tryBraceDepth++;
             }
             else if (char === '}') {
                 globalBraceDepth = Math.max(0, globalBraceDepth - 1);
-                if (inFunction)
+                if (inFunction) {
                     functionBraceDepth = Math.max(0, functionBraceDepth - 1);
+                    if (functionBraceDepth === 0) {
+                        justClosedFunction = true;
+                    }
+                }
+                if (inTryChain) {
+                    tryBraceDepth = Math.max(0, tryBraceDepth - 1);
+                    if (tryBraceDepth === 0) {
+                        justClosedTryBlock = true;
+                    }
+                }
             }
             else if (char === '(') {
                 parenDepth++;
@@ -60,6 +83,16 @@ hardLimitMultiplier = 2 // hard limit will be softLimit * multiplier
                 bracketDepth = Math.max(0, bracketDepth - 1);
             }
         }
+        if (justClosedFunction)
+            inFunction = false;
+        if (justClosedTryBlock) {
+            inTryBlock = false;
+            // Only close the chain if we've already seen a handler
+            if (tryChainHasHandler) {
+                inTryChain = false;
+                tryChainHasHandler = false;
+            }
+        }
         // ---------- add line ----------
         currentChunkLines.push(line);
         currentTokens += encode(line + '\n').length;
@@ -67,20 +100,18 @@ hardLimitMultiplier = 2 // hard limit will be softLimit * multiplier
         const softLimitReached = currentTokens >= softLimit;
         const hardLimitReached = currentTokens >= hardLimit;
         const safeToSplit = !inMultiComment &&
-            !inTryBlock &&
+            !inFunction &&
+            !inTryChain &&
+            !justClosedFunction &&
+            !justClosedTryBlock &&
             functionBraceDepth === 0 &&
             parenDepth === 0 &&
             bracketDepth === 0;
-        // try to split after soft limit if safe, or force at hard limit
         if ((softLimitReached && safeToSplit) || hardLimitReached) {
             chunks.push(currentChunkLines.join('\n'));
             currentChunkLines = [];
             currentTokens = 0;
         }
-        // ---------- function end ----------
-        if (inFunction && functionBraceDepth === 0) {
-            inFunction = false;
-        }
     }
     if (currentChunkLines.length > 0) {
         chunks.push(currentChunkLines.join('\n'));

package/package.json

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