nuvanta-context-guard 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# Nuvanta Context Guard
+
+A developer tool that scans a software project, identifies files relevant to a task, and produces a context report for AI coding agents.
+
+## Installation
+
+```bash
+npm install -g nuvanta-context-guard
+```
+
+## Usage
+
+```bash
+nuvanta scan <path> --task <task> [--budget <tokens>]
+```
+
+## Examples
+
+Scan a project for files relevant to fixing a login bug:
+
+```bash
+nuvanta scan ./my-project --task "fix login button"
+```
+
+Scan with a token budget:
+
+```bash
+nuvanta scan ./my-project --task "fix login button" --budget 5000
+```
+
+## Example Output
+
+```
+Nuvanta Context Guard
+─────────────────────────────────────
+
+Task: fix login button
+Keywords: login, button
+Budget: 5000 tokens
+
+Files found: 24
+Relevant: 5
+Selected: 4
+Context used: 3,842 / 5,000 tokens
+Reduction: ~83%
+
+Selected files:
+ src\auth\login.ts                     820 tokens score 1.6
+ src\components\LoginButton.tsx        612 tokens score 1.0
+ src\api\auth.ts                       445 tokens score 0.5
+ src\index.ts                          392 tokens score 0.5
+```
+
+## How It Works
+
+1. **Scanner** — recursively discovers all files in the project
+2. **Relevance Engine** — scores each file based on filename, directory, and content
+3. **Budget Selector** — picks the most relevant files within the token limit
+4. **Output** — prints a clean report
+
+## License
+
+MIT

package/dist/budget/index.js

@@ -0,0 +1,11 @@
+export function selectFiles(files, budget) {
+    const selected = [];
+    let remaining = budget;
+    for (const file of files) {
+        if (file.tokens <= remaining) {
+            selected.push(file);
+            remaining -= file.tokens;
+        }
+    }
+    return selected;
+}

package/dist/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { scanDirectory } from "./scanner/index.js";
+import { extractKeywords, scoreFile, scoreContent } from "./relevance/index.js";
+import { selectFiles } from "./budget/index.js";
+import { printReport } from "./output/index.js";
+import fs from "fs/promises";
+const program = new Command();
+program
+    .name("nuvanta")
+    .description("AI context management for developer projects")
+    .version("0.1.0");
+program
+    .command("scan")
+    .description("Scan a project and find relevant files for a task")
+    .argument("<path>", "Path to the project directory")
+    .option("--task <task>", "The task you are working on")
+    .option("--budget <number>", "Max token budget", "10000")
+    .action(async (dirPath, options) => {
+    try {
+        const budget = parseInt(options.budget);
+        const files = await scanDirectory(dirPath);
+        const keywords = extractKeywords(options.task);
+        const scored = [];
+        for (const file of files) {
+            const content = await fs.readFile(file.path, "utf-8");
+            const score = scoreFile(file.path, keywords) + scoreContent(content, keywords);
+            if (score > 0) {
+                scored.push({ ...file, score });
+            }
+        }
+        scored.sort((a, b) => b.score - a.score);
+        const selected = selectFiles(scored, budget);
+        printReport({
+            task: options.task,
+            keywords,
+            budget,
+            totalFiles: files.length,
+            relevantFiles: scored.length,
+            selected,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("ENOENT")) {
+            console.error(`\nError: Folder "${dirPath}" does not exist.\n`);
+        }
+        else if (error instanceof Error) {
+            console.error(`\nError: ${error.message}\n`);
+        }
+        else {
+            console.error("\nUnknown error.\n");
+        }
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/output/index.js

@@ -0,0 +1,21 @@
+export function printReport(data) {
+    const totalTokens = data.selected.reduce((sum, f) => sum + f.tokens, 0);
+    const reduction = Math.round((1 - data.selected.length / data.totalFiles) * 100);
+    console.log("\nNuvanta Context Guard");
+    console.log("─────────────────────────────────────\n");
+    console.log(`Task: ${data.task}`);
+    console.log(`Keywords: ${data.keywords.join(", ")}`);
+    console.log(`Budget: ${data.budget} tokens\n`);
+    console.log(`Files found: ${data.totalFiles}`);
+    console.log(`Relevant: ${data.relevantFiles}`);
+    console.log(`Selected: ${data.selected.length}`);
+    console.log(`Context used: ${totalTokens} / ${data.budget} tokens`);
+    console.log(`Reduction: ~${reduction}%\n`);
+    console.log("Selected files:");
+    for (const file of data.selected) {
+        const tokens = `${file.tokens} tokens`.padStart(12);
+        const score = `score ${file.score}`.padEnd(10);
+        console.log(` ${file.path.padEnd(35)} ${tokens} ${score}`);
+    }
+    console.log("");
+}

package/dist/relevance/index.js

@@ -0,0 +1,45 @@
+import path from "path";
+const STOP_WORDS = new Set([
+    "fix",
+    "add",
+    "update",
+    "change",
+    "make",
+    "the",
+    "a",
+    "an",
+    "is",
+    "in",
+    "for",
+    "to",
+]);
+export function extractKeywords(task) {
+    return task
+        .toLowerCase()
+        .split(" ")
+        .filter((word) => !STOP_WORDS.has(word));
+}
+export function scoreFile(filePath, keywords) {
+    const fileName = path.basename(filePath).toLowerCase();
+    const dirName = path.dirname(filePath).toLowerCase();
+    let score = 0;
+    for (const keyword of keywords) {
+        if (fileName.includes(keyword)) {
+            score += 1.0;
+        }
+        if (dirName.includes(keyword)) {
+            score += 0.6;
+        }
+    }
+    return score;
+}
+export function scoreContent(content, keywords) {
+    const normalizedContent = content.toLowerCase();
+    let score = 0;
+    for (const keyword of keywords) {
+        if (normalizedContent.includes(keyword)) {
+            score += 0.5;
+        }
+    }
+    return score;
+}

package/dist/scanner/index.js

@@ -0,0 +1,53 @@
+import fs from "fs/promises";
+import path from "path";
+const IGNORED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    ".next",
+    "build",
+    "coverage",
+    ".cache",
+]);
+const IGNORED_EXTENSIONS = new Set([
+    ".md",
+    ".lock",
+    ".env",
+    ".log",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".ico",
+    ".woff",
+    ".woff2",
+    ".ttf",
+]);
+export async function scanDirectory(dirPath) {
+    const result = [];
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRS.has(entry.name))
+                continue;
+            const subFiles = await scanDirectory(fullPath);
+            result.push(...subFiles);
+        }
+        else {
+            const ext = path.extname(entry.name);
+            if (IGNORED_EXTENSIONS.has(ext))
+                continue;
+            const stat = await fs.stat(fullPath);
+            result.push({
+                path: fullPath,
+                name: entry.name,
+                extension: path.extname(entry.name),
+                size: stat.size,
+                tokens: Math.round(stat.size / 4),
+            });
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "nuvanta-context-guard",
+  "version": "0.1.0",
+  "description": "A developer tool that identifies relevant project files for AI coding agents",
+  "main": "dist/index.js",
+  "bin": {
+    "nuvanta": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "node dist/index.js",
+    "test": "vitest run --dir src",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": ["ai", "context", "developer-tools", "cli"],
+  "author": "zeeqsleepy",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.5.0",
+    "eslint": "^10.10.0",
+    "prettier": "^3.9.6",
+    "typescript": "5.8",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.0"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  }
+}