scai 0.1.105 → 0.1.107

package/README.md

@@ -1,15 +1,33 @@
 # ⚙️ scai — Smart Commit AI ✨
 
-> AI-powered CLI tool for commit messages **and** pull request reviews — using local models.
+> AI-powered CLI tool for commit messages, pull request reviews, **and agent-driven workflows** — using local models.
 
 **scai** is your AI pair‑programmer in the terminal. Focus on coding while scai:
- 
-- 💬 **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
-- 📜 Auto‑updates your changelog  
-- 🔍 (ALPHA) Search & ask questions across your codebase  
-- 🔐 100% local — no API keys, no cloud, no telemetry  
+
+* 💬 **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
+
+---
+
+### 🧩 Agent Mode Examples
+
+Run an agent workflow with goals:
+
+```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
+```
+
+The agent mode allows you to chain goals (`summary → comments → tests`) while processing files or directories automatically, keeping your workflow fast and focused.
+
 
 ---
 
@@ -52,6 +70,42 @@ scai runs entirely on your machine and doesn't require cloud APIs or API keys. T
    scai init
    ```
 
+---
+
+## 🤖 Agent Workflow Command
+
+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
+
+```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
+```
+
+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)
+
+#### Features
+
+* ✅ 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
+
+* 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.
+
+---
+
 ## ✨ 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.
@@ -95,6 +149,30 @@ To interact with GitHub and create pull requests, `scai` needs a personal access
 
 ---
 ## ⚒️ Usage Overview
+
+### 🔧  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
+
+---
+
 ### 🧠 How to Use `scai git review`
 
 ```bash
@@ -182,31 +260,6 @@ You might consider renaming `sessionManager` to better reflect its dual role in
 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:

package/dist/CHANGELOG.md

@@ -157,4 +157,9 @@ Type handling with the module pipeline
 • Introduce Agent class with minimal implementation
 • Improve test-module's filepath handling and variable naming
 • Rename workflowManager.ts to agent/workflowManager.ts
-• Improved formatting of agent run summary output
+• Improved formatting of agent run summary output
+
+## 2025-08-31
+
+• Update Spinner class to correctly display text and frames
+• Update CLI help to reflect new agent workflow examples.

package/dist/agent/agentManager.js

@@ -1,26 +1,25 @@
 // src/agent/agentManager.ts
 import chalk from "chalk";
 import fs from "fs/promises";
-import { getModuleByName } from "../pipeline/registry/moduleRegistry.js";
+import { resolveModuleOrder } from "../pipeline/registry/moduleRegistry.js";
 import { handleAgentRun } from "./workflowManager.js";
-// Minimal agent: just collects modules and delegates to handleAgentRun
+// Minimal agent: resolves modules (with before/after dependencies) and delegates to handleAgentRun
 export class Agent {
     constructor(goals) {
         // Trim goal names to avoid whitespace issues
-        this.goals = goals.map(g => g.trim());
+        this.goals = goals.map((g) => g.trim());
+    }
+    resolveModules(goals) {
+        // Use the registry helper to get the correct order
+        return resolveModuleOrder(goals);
     }
     async execute(filepath) {
         console.log(chalk.cyan(`🤖 Agent starting on: ${filepath}`));
-        // Map goal names → module objects
-        const modules = this.goals.map(goal => {
-            const mod = getModuleByName(goal);
-            if (!mod)
-                throw new Error(`❌ Unknown module: ${goal}`);
-            return mod;
-        });
-        console.log(chalk.green("📋 Modules to run:"), modules.map(m => m.name).join(" → "));
-        // Read file content
-        const content = await fs.readFile(filepath, "utf-8");
+        // Resolve modules (with before/after dependencies)
+        const modules = this.resolveModules(this.goals);
+        console.log(chalk.green("📋 Modules to run:"), modules.map((m) => m.name).join(" → "));
+        // Read file content (optional, could be used by modules in workflow)
+        await fs.readFile(filepath, "utf-8");
         // Delegate everything to handleAgentRun (like CLI commands do)
         await handleAgentRun(filepath, modules);
         console.log(chalk.green("✅ Agent finished!"));

package/dist/agent/workflowManager.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { runModulePipeline } from '../pipeline/runModulePipeline.js';
 import { countTokens, splitCodeIntoChunks } from '../utils/splitCodeIntoChunk.js';
 import { normalizePath } from '../utils/contentUtils.js';
+// basically handles all input (chunk if large), and writing of output (overwrite, append, new file)
 export async function handleAgentRun(filepath, modules) {
     try {
         filepath = normalizePath(filepath);

package/dist/context.js

@@ -1,12 +1,10 @@
 // context.ts
-import { readConfig, writeConfig, Config } from "./config.js";
+import { readConfig, writeConfig } from "./config.js";
 import { normalizePath } from "./utils/contentUtils.js";
 import { getHashedRepoKey } from "./utils/repoKey.js";
 import { getDbForRepo, getDbPathForRepo } from "./db/client.js";
 import fs from "fs";
 import chalk from "chalk";
-import { generate } from "./lib/generate.js"; // 👈 use your existing generate wrapper
-import { startModelProcess } from "./utils/checkModel.js";
 export async function updateContext() {
     const cwd = normalizePath(process.cwd());
     const cfg = readConfig();
@@ -56,17 +54,6 @@ export async function updateContext() {
     else if (isNewRepo || activeRepoChanged) {
         console.log(chalk.green("✅ Database present"));
     }
-    // ✅ NEW: Ensure model is available
-    if (ok) {
-        const modelReady = await ensureModelReady();
-        if (modelReady) {
-            console.log(chalk.green("✅ Model ready"));
-        }
-        else {
-            console.log(chalk.red("❌ Model not available"));
-            ok = false;
-        }
-    }
     // Final context status
     if (ok) {
         console.log(chalk.bold.green("\n✅ Context OK\n"));
@@ -76,15 +63,3 @@ export async function updateContext() {
     }
     return ok;
 }
-async function ensureModelReady() {
-    try {
-        // simple "ping" prompt that costs almost nothing
-        const res = await generate({ content: "ping" }, Config.getModel());
-        return Boolean(res?.content);
-    }
-    catch {
-        console.log(chalk.yellow("⚡ Model not responding. Attempting to start..."));
-        await startModelProcess();
-        return false;
-    }
-}

package/dist/index.js

@@ -25,16 +25,10 @@ import { runInteractiveSwitch } from "./commands/SwitchCmd.js";
 import { execSync } from "child_process";
 import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
-import { handleAgentRun } from './agent/workflowManager.js';
-import { addCommentsModule } from './pipeline/modules/commentModule.js';
-import { generateTestsModule } from './pipeline/modules/generateTestsModule.js';
-import { preserveCodeModule } from './pipeline/modules/preserveCodeModule.js';
 import { runInteractiveDelete } from './commands/DeleteIndex.js';
 import { resolveTargetsToFiles } from './utils/resolveTargetsToFiles.js';
 import { updateContext } from './context.js';
-import { cleanGeneratedTestsModule } from './pipeline/modules/cleanGeneratedTestsModule.js';
 import { Agent } from './agent/agentManager.js';
-import { builtInModules } from './pipeline/registry/moduleRegistry.js';
 // 🎛️ CLI Setup
 const cmd = new Command('scai')
     .version(version)
@@ -51,11 +45,13 @@ cmd
 // 🔧 Group: Agent-related commands
 const agent = cmd
     .command('agent')
-    .description(`Run an agent workflow. Available tools:\n` +
-    Object.keys(builtInModules).map(m => `  - ${m}`).join('\n') +
-    `\n\nExample usage:\n` +
-    `  $ scai agent run summary cleanup tests\n` +
-    `  This will run the agent with the goals: summary → cleanup → tests\n`);
+    .description(`Run an agent workflow. Example available tools:\n` +
+    `  - summary\n` +
+    `  - comments\n` +
+    `  - tests\n\n` +
+    `Example usage:\n` +
+    `  $ scai agent run comments tests -f path/to/myfile\n` +
+    `  This will run the agent with the goals: comments → tests\n`);
 // Run workflow subcommand
 const runCmd = agent
     .command('run <goals...>')
@@ -71,10 +67,12 @@ const runCmd = agent
         await agentInstance.execute(file);
     });
 });
-// Inject modules list into the --help output
+// Optional: show example modules on --help
 runCmd.on('--help', () => {
-    console.log('\nAvailable tools:');
-    Object.keys(builtInModules).forEach(m => console.log(`  - ${m}`));
+    console.log('\nExample tools:');
+    console.log('  - summary');
+    console.log('  - comments');
+    console.log('  - tests');
 });
 // 🔧 Group: Git-related commands
 const git = cmd.command('git').description('Git utilities');
@@ -155,10 +153,22 @@ gen
     .description("Write comments for the given file(s) or folder(s)")
     .action(async (targets) => {
     await withContext(async () => {
-        // Remove the file type filter to allow any file
         const files = await resolveTargetsToFiles(targets);
         for (const file of files) {
-            await handleAgentRun(file, [addCommentsModule, preserveCodeModule]);
+            const agent = new Agent(["comments"]); // goals: "comments"
+            await agent.execute(file); // run on the file
+        }
+    });
+});
+gen
+    .command("test <targets...>")
+    .description("Generate tests for the given file(s) or folder(s)")
+    .action(async (targets) => {
+    await withContext(async () => {
+        const files = await resolveTargetsToFiles(targets);
+        for (const file of files) {
+            const agent = new Agent(["tests"]); // goals: "tests"
+            await agent.execute(file);
         }
     });
 });
@@ -178,17 +188,6 @@ gen
         summarizeFile(file);
     });
 });
-gen
-    .command("test <targets...>")
-    .description("Generate tests for the given file(s) or folder(s)")
-    .action(async (targets, options) => {
-    await withContext(async () => {
-        const files = await resolveTargetsToFiles(targets);
-        for (const file of files) {
-            await handleAgentRun(file, [generateTestsModule, cleanGeneratedTestsModule]);
-        }
-    });
-});
 // ⚙️ Group: Configuration settings
 const config = cmd.command('config').description('Manage SCAI configuration');
 config

package/dist/lib/generate.js

@@ -1,35 +1,40 @@
 // File: lib/generate.ts
 import { Spinner } from './spinner.js';
 import { readConfig } from '../config.js';
+import { startModelProcess } from '../utils/checkModel.js';
 export async function generate(input, model) {
     const contextLength = readConfig().contextLength ?? 8192;
     let prompt = input.content;
     if (prompt.length > contextLength) {
-        console.warn(`⚠️ Warning: Input prompt length (${prompt.length}) exceeds model context length (${contextLength}). `);
+        console.warn(`⚠️ Warning: Input prompt length (${prompt.length}) exceeds model context length (${contextLength}).`);
     }
     const spinner = new Spinner(`🧠 Thinking with ${model}...`);
     spinner.start();
     try {
-        const res = await fetch('http://localhost:11434/api/generate', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                model,
-                prompt, // use truncated prompt here
-                stream: false,
-            }),
-        });
-        const data = await res.json();
-        spinner.succeed('Model response received.');
-        process.stdout.write('\n');
-        return {
-            content: data.response?.trim() ?? '',
-            filepath: input.filepath,
-        };
+        return await doGenerate(prompt, model, spinner, false);
     }
     catch (err) {
-        spinner.fail('Model request failed.');
+        spinner.fail('Model request failed. Attempting to start model...');
         process.stdout.write('\n');
-        throw err;
+        await startModelProcess();
+        spinner.update(`🧠 Retrying with ${model}...`);
+        return await doGenerate(prompt, model, spinner, true); // retry once
     }
 }
+async function doGenerate(prompt, model, spinner, retrying) {
+    const res = await fetch('http://localhost:11434/api/generate', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            model,
+            prompt,
+            stream: false,
+        }),
+    });
+    const data = await res.json();
+    spinner.succeed(retrying ? 'Model response received after restart.' : 'Model response received.');
+    process.stdout.write('\n');
+    return {
+        content: data.response?.trim() ?? '',
+    };
+}

package/dist/lib/spinner.js

@@ -1,4 +1,3 @@
-// lib/spinner.ts
 export class Spinner {
     constructor(message) {
         this.frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
@@ -8,18 +7,25 @@ export class Spinner {
     }
     start() {
         process.stdout.write('\x1b[?25l'); // hide cursor
+        process.stdout.write(` ${this.text}`); // print text once
         this.interval = setInterval(() => {
-            const frame = this.frames[this.i = ++this.i % this.frames.length];
-            process.stdout.write(`\r${frame} ${this.text} `);
+            process.stdout.write('\r'); // return to start of line
+            process.stdout.write(`${this.frames[this.i]} ${this.text}`);
+            this.i = (this.i + 1) % this.frames.length;
         }, 80);
     }
+    update(text) {
+        this.text = text;
+    }
     succeed(msg) {
         this.stop();
-        process.stdout.write(`\r✅ ${msg}\n`);
+        process.stdout.write('\r'); // go to start
+        console.log(`✅ ${msg}`);
     }
     fail(msg) {
         this.stop();
-        process.stdout.write(`\r❌ ${msg}\n`);
+        process.stdout.write('\r'); // go to start
+        console.log(`❌ ${msg}`);
     }
     stop() {
         if (this.interval) {

package/dist/pipeline/modules/commentModule.js

@@ -43,16 +43,12 @@ You are a senior engineer reviewing a ${fileType} file.
 Please:
 
 - Add summary comments (2-3 lines) at relevant points for greater class insights
-- Add clear, helpful inline comments to explain non-obvious logic inside functions.  
+- Add clear, helpful inline-comments to explain non-obvious logic inside functions.  
 - Use "${commentSyntax}" as the comment syntax appropriate for ${fileType}.
-- Preserve all original formatting, whitespace, and code exactly.
 
 Rules:
-- Return the full original chunk of code with added comments only.
-- Do NOT remove, change, or overwrite any existing code or comments.
-- Summaries should be brief but meaningful.
-- Inline comments should clarify complex or tricky parts only.
-- Do NOT add any “chunk” start/end markers, numbering, or metadata to the output.
+- Return the full original chunk of code with added comments.
+- Inline comments should clarify complex or tricky parts.
 
 ${input.content}
 

package/dist/pipeline/registry/moduleRegistry.js

@@ -6,24 +6,88 @@ import { commitSuggesterModule } from '../modules/commitSuggesterModule.js';
 import { changelogModule } from '../modules/changeLogModule.js';
 import { cleanGeneratedTestsModule } from '../modules/cleanGeneratedTestsModule.js';
 import { preserveCodeModule } from '../modules/preserveCodeModule.js';
-// Add more as needed...
+// Built-in modules with metadata
 export const builtInModules = {
-    comments: addCommentsModule,
-    cleanup: cleanupModule,
-    summary: summaryModule,
-    tests: generateTestsModule,
-    suggest: commitSuggesterModule,
-    changelog: changelogModule,
-    cleanTests: cleanGeneratedTestsModule,
-    cleanComments: preserveCodeModule
+    comments: {
+        ...addCommentsModule,
+        group: 'documentation',
+        dependencies: {
+            after: ['cleanComments'], // run cleanComments after comments
+        },
+    },
+    cleanComments: {
+        ...preserveCodeModule,
+        group: 'documentation',
+    },
+    cleanup: {
+        ...cleanupModule,
+        group: 'maintenance',
+    },
+    summary: {
+        ...summaryModule,
+        group: 'documentation',
+    },
+    tests: {
+        ...generateTestsModule,
+        group: 'testing',
+        dependencies: {
+            after: ['cleanTests'], // run cleanTests after tests
+        },
+    },
+    cleanTests: {
+        ...cleanGeneratedTestsModule,
+        group: 'testing',
+    },
+    suggest: {
+        ...commitSuggesterModule,
+        group: 'git',
+    },
+    changelog: {
+        ...changelogModule,
+        group: 'git',
+    },
 };
+// Get module by name
 export function getModuleByName(name) {
     return builtInModules[name];
 }
 // Return module metadata for CLI or UI
 export function listAvailableModules() {
-    return Object.values(builtInModules).map(({ name, description }) => ({
+    return Object.values(builtInModules).map(({ name, description, group, dependencies }) => ({
         name,
         description: description || 'No description available',
+        group,
+        dependencies,
     }));
 }
+/**
+ * Resolve module execution order including before/after dependencies.
+ * Returns a unique ordered array of PromptModuleMeta.
+ */
+export function resolveModuleOrder(moduleNames) {
+    const resolved = [];
+    const visited = new Set();
+    function visit(name) {
+        if (visited.has(name))
+            return;
+        const mod = getModuleByName(name);
+        if (!mod)
+            return;
+        // Handle before dependencies first
+        if (mod.dependencies?.before) {
+            for (const dep of mod.dependencies.before)
+                visit(dep);
+        }
+        // Add the module itself
+        resolved.push(mod);
+        visited.add(name);
+        // Handle after dependencies
+        if (mod.dependencies?.after) {
+            for (const dep of mod.dependencies.after)
+                visit(dep);
+        }
+    }
+    for (const name of moduleNames)
+        visit(name);
+    return resolved;
+}

package/package.json

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