localsage 1.0.4 → 1.0.5

package/README.md

@@ -44,9 +44,10 @@ The first run downloads the model (~500 MB) to your Hugging Face cache. After th
 
 ## Commands
 
-- `exit` — save history and quit
-- `clear` — clear conversation history
+- `/knowledge` — list all loaded knowledge files as a tree
 - `history` — show number of stored messages
+- `clear` — clear conversation history
+- `exit` — save history and quit
 
 ## Options
 
@@ -103,7 +104,7 @@ main();
 
 ## How It Works
 
-1. **Knowledge loading** — reads all TXT, MD, and PDF files from the resolved knowledge folder (explicit `-k` path → `./knowledge` subfolder → current directory), plus an optional `knowledge.txt` in the working directory
+1. **Knowledge loading** — recursively reads all TXT, MD, and PDF files from the resolved knowledge folder (explicit `-k` path → `./knowledge` subfolder → current directory), including subfolders, while skipping `node_modules`, `.git`, and other junk directories
 2. **AI processing** — runs the Qwen model locally with `@huggingface/transformers`
 3. **History** — saves the conversation to `history.json` in the working directory
 

package/cli.js

@@ -4,10 +4,12 @@ const chalk = require('chalk');
 const inquirer = require('inquirer');
 const { program } = require('commander');
 const LocalSage = require('./index');
+const Spinner = require('./src/spinner');
+const { renderFileTree } = require('./src/filetree');
 
 program
   .name('localsage')
-  .version('1.0.3')
+  .version('1.0.5')
   .description('LocalSage — local, offline AI assistant with PDF & document knowledge')
   .option('-m, --model <model>', 'Model name', 'onnx-community/Qwen2.5-0.5B-Instruct')
   .option(
@@ -35,14 +37,15 @@ async function runCLI() {
   console.log(chalk.blue('='.repeat(60)));
   console.log(chalk.green.bold(' 🧙 LocalSage — your local AI assistant '));
   console.log(chalk.blue('='.repeat(60)));
-  console.log(chalk.gray(` Model: ${options.model}`));
-  console.log(chalk.gray(` Knowledge: ${assistant.getResolvedKnowledgePath()}`));
-  console.log(chalk.gray(` PDF Support: ${options.pdf !== false ? 'Enabled' : 'Disabled'}`));
+  const kFiles = assistant.getKnowledgeFiles();
+  console.log(chalk.gray(` Knowledge (${kFiles.length} file${kFiles.length === 1 ? '' : 's'}):`));
+  console.log(renderFileTree(kFiles, ` ${assistant.getResolvedKnowledgePath()}`));
   console.log(chalk.blue('='.repeat(60)));
   console.log(chalk.gray(' Commands:'));
-  console.log(chalk.gray('   exit     - Save and exit'));
-  console.log(chalk.gray('   clear    - Clear conversation history'));
-  console.log(chalk.gray('   history  - Show number of stored messages'));
+  console.log(chalk.gray('   /knowledge - List all knowledge files (tree view)'));
+  console.log(chalk.gray('   history    - Show number of stored messages'));
+  console.log(chalk.gray('   clear      - Clear conversation history'));
+  console.log(chalk.gray('   exit       - Save and exit'));
   console.log(chalk.blue('='.repeat(60)));
   console.log(
     chalk.magenta(' 💼 Open to Work — built by a developer available for freelance')
@@ -85,14 +88,29 @@ async function runCLI() {
         continue;
       }
 
+      if (cmd === '/knowledge' || cmd === 'knowledge') {
+        const files = assistant.getKnowledgeFiles();
+        console.log('');
+        console.log(renderFileTree(files, assistant.getResolvedKnowledgePath()));
+        console.log(
+          chalk.gray(`\n${files.length} file(s) loaded into knowledge\n`)
+        );
+        continue;
+      }
+
       if (cmd === 'history') {
         console.log(chalk.yellow(`\nStored Messages : ${assistant.getHistoryCount()}`));
         continue;
       }
 
-      process.stdout.write(chalk.cyan('\nAI : '));
-      const response = await assistant.chat(trimmed);
-      console.log(chalk.green(response));
+      const spinner = new Spinner('AI is thinking...').start();
+      let response;
+      try {
+        response = await assistant.chat(trimmed);
+      } finally {
+        spinner.stop();
+      }
+      console.log(chalk.cyan('AI : ') + chalk.green(response));
       console.log('');
     } catch (error) {
       // inquirer throws when the prompt stream is closed (e.g. Ctrl+C / EOF)

package/index.js

@@ -91,6 +91,10 @@ ${knowledge}`;
     return this.knowledge.getResolvedPath();
   }
 
+  getKnowledgeFiles() {
+    return this.knowledge.getLoadedFiles();
+  }
+
   async reloadKnowledge() {
     await this.knowledge.loadKnowledge();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localsage",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "LocalSage — a local, offline AI assistant with PDF & document knowledge. Powered by Qwen via Transformers.js. Pure Node.js, no Python.",
   "main": "index.js",
   "bin": {

package/src/filetree.js

@@ -0,0 +1,66 @@
+const chalk = require('chalk');
+
+/**
+ * Render a list of relative file paths as an ASCII tree.
+ * e.g. ['a.txt', 'docs/b.pdf', 'docs/notes/c.md'] ->
+ *   ├── a.txt
+ *   └── docs
+ *       ├── b.pdf
+ *       └── notes
+ *           └── c.md
+ */
+function buildTree(paths) {
+  const root = {};
+  for (const p of paths) {
+    const parts = p.split('/');
+    let node = root;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const isFile = i === parts.length - 1;
+      if (!node[part]) {
+        node[part] = { __file: isFile, children: {} };
+      }
+      node = node[part].children;
+    }
+  }
+  return root;
+}
+
+function renderNode(node, prefix, lines) {
+  const keys = Object.keys(node).sort((a, b) => {
+    // folders first, then files, alphabetical
+    const af = node[a].__file ? 1 : 0;
+    const bf = node[b].__file ? 1 : 0;
+    return af - bf || a.localeCompare(b);
+  });
+
+  keys.forEach((key, idx) => {
+    const isLast = idx === keys.length - 1;
+    const branch = isLast ? '└── ' : '├── ';
+    const item = node[key];
+    const label = item.__file ? chalk.green(key) : chalk.blue.bold(key + '/');
+    lines.push(prefix + chalk.gray(branch) + label);
+    if (!item.__file) {
+      const childPrefix = prefix + (isLast ? '    ' : chalk.gray('│   '));
+      renderNode(item.children, childPrefix, lines);
+    }
+  });
+}
+
+/**
+ * @param {string[]} paths relative file paths
+ * @param {string} rootLabel label for the tree root (e.g. the knowledge dir)
+ * @returns {string} printable tree
+ */
+function renderFileTree(paths, rootLabel) {
+  const lines = [];
+  if (rootLabel) lines.push(chalk.blue.bold(rootLabel));
+  if (!paths || paths.length === 0) {
+    lines.push(chalk.gray('  (no knowledge files loaded)'));
+    return lines.join('\n');
+  }
+  renderNode(buildTree(paths), '', lines);
+  return lines.join('\n');
+}
+
+module.exports = { renderFileTree };

package/src/knowledge.js

@@ -1,6 +1,24 @@
 const fs = require('fs-extra');
 const path = require('path');
 
+// Folders that should never be scanned for knowledge
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.svn',
+  '.hg',
+  'dist',
+  'build',
+  'coverage',
+  'models',
+  '__pycache__',
+  '.cache',
+  'venv',
+  '.venv',
+]);
+
+const MAX_DEPTH = 6;
+
 class KnowledgeManager {
   /**
    * @param {string|null} knowledgePath - explicit path from the user, or null
@@ -11,6 +29,7 @@ class KnowledgeManager {
     this.requestedPath = knowledgePath;
     this.knowledgePath = null; // resolved in loadKnowledge()
     this.knowledge = '';
+    this.loadedFiles = []; // relative paths of every file loaded
   }
 
   resolvePath() {
@@ -27,18 +46,20 @@ class KnowledgeManager {
 
   async loadKnowledge() {
     this.knowledgePath = this.resolvePath();
+    this.loadedFiles = [];
     let combinedKnowledge = '';
 
     // Load a standalone knowledge.txt from the working directory —
-    // but only if it isn't already inside the folder we're about to scan
-    // (avoids loading it twice when knowledgePath === cwd).
+    // but only if it isn't inside the tree we're about to scan
+    // (avoids loading it twice when knowledgePath covers cwd).
     const txtFile = path.join(process.cwd(), 'knowledge.txt');
-    if (
-      path.dirname(txtFile) !== this.knowledgePath &&
-      (await fs.pathExists(txtFile))
-    ) {
+    const insideTree = !path
+      .relative(this.knowledgePath, txtFile)
+      .startsWith('..');
+    if (!insideTree && (await fs.pathExists(txtFile))) {
       try {
         combinedKnowledge += await fs.readFile(txtFile, 'utf-8');
+        this.loadedFiles.push('knowledge.txt (working directory)');
         console.log('Knowledge loaded from knowledge.txt');
       } catch (error) {
         console.error('Error loading knowledge.txt:', error.message);
@@ -47,7 +68,7 @@ class KnowledgeManager {
 
     if (await fs.pathExists(this.knowledgePath)) {
       console.log(`Loading knowledge from: ${this.knowledgePath}`);
-      const folderKnowledge = await this.loadFolder(this.knowledgePath);
+      const folderKnowledge = await this.loadFolder(this.knowledgePath, '', 0);
       if (folderKnowledge) {
         if (combinedKnowledge) {
           combinedKnowledge += '\n\n' + '='.repeat(50) + '\n\n';
@@ -63,18 +84,34 @@ class KnowledgeManager {
     if (!this.knowledge.trim()) {
       console.log('Warning: No knowledge loaded. Using general knowledge only.\n');
     } else {
-      console.log(`Total knowledge loaded: ${this.knowledge.length} characters\n`);
+      console.log(
+        `Total knowledge loaded: ${this.loadedFiles.length} file(s), ${this.knowledge.length} characters\n`
+      );
     }
 
     return this.knowledge;
   }
 
-  async loadFolder(folderPath) {
+  /**
+   * Recursively load .txt/.md/.pdf files.
+   * @param {string} folderPath absolute folder to scan
+   * @param {string} relBase    path of folderPath relative to knowledge root
+   * @param {number} depth      current recursion depth
+   */
+  async loadFolder(folderPath, relBase, depth) {
+    if (depth > MAX_DEPTH) return '';
     let combined = '';
-    const files = await fs.readdir(folderPath);
 
-    for (const file of files) {
-      const filePath = path.join(folderPath, file);
+    let entries;
+    try {
+      entries = await fs.readdir(folderPath);
+    } catch {
+      return '';
+    }
+
+    for (const entry of entries.sort()) {
+      const filePath = path.join(folderPath, entry);
+      const relPath = relBase ? `${relBase}/${entry}` : entry;
 
       let stat;
       try {
@@ -82,27 +119,34 @@ class KnowledgeManager {
       } catch {
         continue;
       }
-      if (stat.isDirectory()) continue;
 
-      const ext = path.extname(file).toLowerCase();
+      if (stat.isDirectory()) {
+        if (SKIP_DIRS.has(entry) || entry.startsWith('.')) continue;
+        combined += await this.loadFolder(filePath, relPath, depth + 1);
+        continue;
+      }
+
+      const ext = path.extname(entry).toLowerCase();
 
       try {
         if (ext === '.txt' || ext === '.md') {
           const content = await fs.readFile(filePath, 'utf-8');
-          combined += `\n\n--- Content from ${file} ---\n\n${content}`;
-          console.log(`Loaded: ${file}`);
+          combined += `\n\n--- Content from ${relPath} ---\n\n${content}`;
+          this.loadedFiles.push(relPath);
+          console.log(`Loaded: ${relPath}`);
         } else if (ext === '.pdf') {
-          console.log(`Reading PDF: ${file}`);
+          console.log(`Reading PDF: ${relPath}`);
           const content = await this.extractPDF(filePath);
           if (content.trim()) {
-            combined += `\n\n--- Content from ${file} ---\n\n${content}`;
-            console.log(`Loaded: ${file}`);
+            combined += `\n\n--- Content from ${relPath} ---\n\n${content}`;
+            this.loadedFiles.push(relPath);
+            console.log(`Loaded: ${relPath}`);
           } else {
-            console.log(`Warning: No text extracted from ${file}`);
+            console.log(`Warning: No text extracted from ${relPath}`);
           }
         }
       } catch (error) {
-        console.error(`Error reading ${file}:`, error.message);
+        console.error(`Error reading ${relPath}:`, error.message);
       }
     }
 
@@ -125,6 +169,11 @@ class KnowledgeManager {
     return this.knowledgePath || this.resolvePath();
   }
 
+  /** Relative paths of every file that was loaded into the knowledge. */
+  getLoadedFiles() {
+    return this.loadedFiles;
+  }
+
   getKnowledge(truncate = true, maxLength = 4000) {
     if (!truncate || this.knowledge.length <= maxLength) {
       return this.knowledge;

package/src/model.js

@@ -28,6 +28,9 @@ class QwenModel {
 
     console.log('Loading AI Model (first run downloads ~500MB, please wait)...');
 
+    const Spinner = require('./spinner');
+    const spinner = new Spinner('Preparing model...').start();
+
     try {
       const { pipeline, env } = await loadTransformers();
 
@@ -37,14 +40,26 @@ class QwenModel {
         env.cacheDir = path.resolve(process.env.LOCALSAGE_MODEL_DIR);
       }
 
+      const barWidth = 20;
       this.pipeline = await pipeline('text-generation', this.modelName, {
         dtype: 'q4', // quantized for speed / low RAM
+        progress_callback: (info) => {
+          if (info.status === 'progress' && typeof info.progress === 'number') {
+            const pct = Math.min(100, info.progress);
+            const filled = Math.round((pct / 100) * barWidth);
+            const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+            const file = (info.file || '').split('/').pop();
+            spinner.update(`Downloading ${file} [${bar}] ${pct.toFixed(1)}%`);
+          } else if (info.status === 'ready') {
+            spinner.update('Starting model...');
+          }
+        },
       });
 
+      spinner.succeed('✓ Model Loaded Successfully.\n');
       this.isLoaded = true;
-      console.log('Model Loaded Successfully.\n');
     } catch (error) {
-      console.error('Error loading model:', error.message);
+      spinner.fail(`Error loading model: ${error.message}`);
       throw error;
     }
   }

package/src/spinner.js

@@ -0,0 +1,73 @@
+const chalk = require('chalk');
+
+/**
+ * Tiny terminal spinner — no external dependencies.
+ * Falls back to a single static line when not running in a TTY
+ * (so piped/CI output doesn't fill with animation frames).
+ */
+class Spinner {
+  constructor(text = 'Loading...') {
+    this.text = text;
+    this.frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    this.interval = null;
+    this.frameIndex = 0;
+    this.isTTY = Boolean(process.stdout.isTTY);
+  }
+
+  start() {
+    if (!this.isTTY) {
+      process.stdout.write(chalk.cyan(`${this.text}\n`));
+      return this;
+    }
+    this.frameIndex = 0;
+    this.render();
+    this.interval = setInterval(() => this.render(), 80);
+    return this;
+  }
+
+  render() {
+    const frame = this.frames[this.frameIndex];
+    this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+    this.clearLine();
+    process.stdout.write(chalk.cyan(`${frame} ${this.text}`));
+  }
+
+  /** Update the message while spinning (e.g. download progress). */
+  update(text) {
+    this.text = text;
+    if (!this.isTTY) return this;
+    if (this.interval) this.render();
+    return this;
+  }
+
+  clearLine() {
+    if (!this.isTTY) return;
+    process.stdout.clearLine(0);
+    process.stdout.cursorTo(0);
+  }
+
+  /** Stop and remove the spinner line entirely. */
+  stop() {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+    this.clearLine();
+    return this;
+  }
+
+  /** Stop and replace the spinner line with a final message. */
+  succeed(text) {
+    this.stop();
+    if (text) console.log(chalk.green(text));
+    return this;
+  }
+
+  fail(text) {
+    this.stop();
+    if (text) console.log(chalk.red(text));
+    return this;
+  }
+}
+
+module.exports = Spinner;