@hasna/terminal 3.6.0 → 3.7.1

package/dist/mcp/server.js

@@ -153,7 +153,7 @@ export function createServer() {
         return { content: [{ type: "text", text: output }] };
     });
     // ── execute_smart: AI-powered output processing ────────────────────────────
-    server.tool("execute_smart", "Run a command and get AI-summarized output. The AI decides what's important — errors, failures, key results are kept; verbose logs, progress bars, passing tests are dropped. Saves 80-95% tokens vs raw output. Best tool for agents.", {
+    server.tool("execute_smart", "Run a command and get AI-summarized output (80-95% token savings). Use this for: test runs, builds, git operations, process management, system info. Do NOT use for file read/write — use your native Read/Write/Edit tools instead (they're faster, no shell overhead).", {
         command: z.string().describe("Shell command to execute"),
         cwd: z.string().optional().describe("Working directory"),
         timeout: z.number().optional().describe("Timeout in ms (default: 30000)"),
@@ -478,7 +478,7 @@ export function createServer() {
         };
     });
     // ── read_file: cached file reading ─────────────────────────────────────────
-    server.tool("read_file", "Read a file with session caching. Use summarize=true to get an AI-generated outline (~90% fewer tokens) instead of full content — ideal when you just want to understand what a file does without reading every line.", {
+    server.tool("read_file", "Read a file with summarize=true for AI outline (~90% fewer tokens). For full file reads without summarization, prefer your native Read tool (faster, no MCP overhead). Use this when you want cached reads or AI summaries.", {
         path: z.string().describe("File path"),
         offset: z.number().optional().describe("Start line (0-indexed)"),
         limit: z.number().optional().describe("Max lines to return"),
@@ -487,13 +487,25 @@ export function createServer() {
         const start = Date.now();
         const result = cachedRead(path, { offset, limit });
         if (summarize && result.content.length > 500) {
-            const processed = await processOutput(`cat ${path}`, result.content);
-            logCall("read_file", { command: path, outputTokens: estimateTokens(result.content), tokensSaved: processed.tokensSaved, durationMs: Date.now() - start, aiProcessed: true });
+            // AI-native file summary — ask directly what the file does
+            const provider = getOutputProvider();
+            const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+            const content = result.content.length > 8000 ? result.content.slice(0, 8000) : result.content;
+            const summary = await provider.complete(`File: ${path}\n\n${content}`, {
+                model: outputModel,
+                system: `Describe what this source file does in 2-4 lines. Include: main class/module name, key methods/functions, what it exports, and its purpose. Be specific — name the actual functions and what they do. Never just say "N lines of code."`,
+                maxTokens: 300,
+                temperature: 0.2,
+            });
+            const outputTokens = estimateTokens(result.content);
+            const summaryTokens = estimateTokens(summary);
+            const saved = Math.max(0, outputTokens - summaryTokens);
+            logCall("read_file", { command: path, outputTokens, tokensSaved: saved, durationMs: Date.now() - start, aiProcessed: true });
             return {
                 content: [{ type: "text", text: JSON.stringify({
-                            summary: processed.summary,
+                            summary,
                             lines: result.content.split("\n").length,
-                            tokensSaved: processed.tokensSaved,
+                            tokensSaved: saved,
                             cached: result.cached,
                         }) }],
             };
@@ -694,7 +706,7 @@ Match by function name, class name, method name (including ClassName.method), in
                         tokensSaved: processed.tokensSaved,
                     }) }] };
     });
-    server.tool("edit", "Find and replace text in a file. Agent says what to change, no sed/awk/python needed. Saves ~200 tokens vs constructing shell commands.", {
+    server.tool("edit", "Find and replace in a file. For simple edits, prefer your native Edit tool (faster). Use this for batch replacements (all=true) or when you don't have a native Edit tool available.", {
         file: z.string().describe("File path"),
         find: z.string().describe("Text to find (exact match)"),
         replace: z.string().describe("Replacement text"),

package/dist/recipes/storage.js

@@ -24,14 +24,31 @@ function saveStore(filePath, store) {
         mkdirSync(dir, { recursive: true });
     writeFileSync(filePath, JSON.stringify(store, null, 2));
 }
+// ── Built-in system recipes (always available, zero config) ─────────────────
+const SYSTEM_RECIPES = [
+    // Git workflows
+    { id: "sys-commit-push", name: "commit-push", description: "Stage all, commit, push to origin", command: "git add -A && git commit -m \"{message}\" && git push", tags: ["git"], collection: "git", variables: [{ name: "message", required: true }], createdAt: 0, updatedAt: 0 },
+    { id: "sys-pr", name: "create-pr", description: "Create GitHub PR from current branch", command: "gh pr create --title \"{title}\" --body \"{body}\"", tags: ["git", "github"], collection: "git", variables: [{ name: "title", required: true }, { name: "body", default: "" }], createdAt: 0, updatedAt: 0 },
+    { id: "sys-stash", name: "stash-switch", description: "Stash changes, switch branch, pop", command: "git stash && git checkout {branch} && git stash pop", tags: ["git"], collection: "git", variables: [{ name: "branch", required: true }], createdAt: 0, updatedAt: 0 },
+    // Quality checks
+    { id: "sys-todos", name: "find-todos", description: "Find all TODO/FIXME/HACK in source code", command: "grep -rn 'TODO\\|FIXME\\|HACK\\|XXX' {path} --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' --include='*.go' --include='*.rs' --include='*.java' --include='*.rb'", tags: ["quality"], collection: "quality", variables: [{ name: "path", default: "src/" }], createdAt: 0, updatedAt: 0 },
+    { id: "sys-deadcode", name: "find-unused-exports", description: "Find exported symbols that may be unused", command: "grep -rn 'export ' {path} --include='*.ts' | sed 's/.*export //' | sed 's/[(<:].*//' | sort -u", tags: ["quality"], collection: "quality", variables: [{ name: "path", default: "src/" }], createdAt: 0, updatedAt: 0 },
+    { id: "sys-security", name: "security-scan", description: "Scan for common security anti-patterns", command: "grep -rn 'eval\\|exec\\|spawn\\|innerHTML\\|dangerouslySetInnerHTML\\|password.*=.*[\"'\\']' {path} --include='*.ts' --include='*.js' --include='*.py'", tags: ["security"], collection: "quality", variables: [{ name: "path", default: "src/" }], createdAt: 0, updatedAt: 0 },
+    // Project info
+    { id: "sys-deps", name: "list-deps", description: "Show project dependencies", command: "cat package.json 2>/dev/null | grep -A 100 '\"dependencies\"' | head -30 || cat requirements.txt 2>/dev/null || cat Cargo.toml 2>/dev/null | grep -A 50 'dependencies'", tags: ["deps"], collection: "project", variables: [], createdAt: 0, updatedAt: 0 },
+    { id: "sys-size", name: "project-size", description: "Count lines of code by file type", command: "find {path} -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/.git/*' -type f | xargs wc -l 2>/dev/null | sort -rn | head -20", tags: ["stats"], collection: "project", variables: [{ name: "path", default: "src/" }], createdAt: 0, updatedAt: 0 },
+    // Process management
+    { id: "sys-port", name: "kill-port", description: "Kill whatever is running on a port", command: "lsof -ti :{port} | xargs kill -9 2>/dev/null || echo 'Port {port} is free'", tags: ["process"], collection: "system", variables: [{ name: "port", required: true }], createdAt: 0, updatedAt: 0 },
+    { id: "sys-disk", name: "disk-usage", description: "Show disk usage of current directory", command: "du -sh {path}/* 2>/dev/null | sort -rh | head -15", tags: ["system"], collection: "system", variables: [{ name: "path", default: "." }], createdAt: 0, updatedAt: 0 },
+];
 // ── CRUD operations ──────────────────────────────────────────────────────────
-/** Get all recipes (merged: global + project-scoped) */
+/** Get all recipes (merged: system + global + project-scoped) */
 export function listRecipes(projectPath) {
     const global = loadStore(GLOBAL_FILE).recipes;
     if (!projectPath)
-        return global;
+        return [...global, ...SYSTEM_RECIPES];
     const project = loadStore(projectFile(projectPath)).recipes;
-    return [...project, ...global]; // project recipes first (higher priority)
+    return [...project, ...global, ...SYSTEM_RECIPES]; // project > global > system priority
 }
 /** Get recipes filtered by collection */
 export function listByCollection(collection, projectPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/terminal",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "description": "Smart terminal wrapper for AI agents and humans — structured output, token compression, MCP server, natural language",
   "type": "module",
   "files": [

package/src/mcp/server.ts

@@ -181,7 +181,7 @@ export function createServer(): McpServer {
 
   server.tool(
     "execute_smart",
-    "Run a command and get AI-summarized output. The AI decides what's important — errors, failures, key results are kept; verbose logs, progress bars, passing tests are dropped. Saves 80-95% tokens vs raw output. Best tool for agents.",
+    "Run a command and get AI-summarized output (80-95% token savings). Use this for: test runs, builds, git operations, process management, system info. Do NOT use for file read/write — use your native Read/Write/Edit tools instead (they're faster, no shell overhead).",
     {
       command: z.string().describe("Shell command to execute"),
       cwd: z.string().optional().describe("Working directory"),
@@ -678,7 +678,7 @@ export function createServer(): McpServer {
 
   server.tool(
     "read_file",
-    "Read a file with session caching. Use summarize=true to get an AI-generated outline (~90% fewer tokens) instead of full content — ideal when you just want to understand what a file does without reading every line.",
+    "Read a file with summarize=true for AI outline (~90% fewer tokens). For full file reads without summarization, prefer your native Read tool (faster, no MCP overhead). Use this when you want cached reads or AI summaries.",
     {
       path: z.string().describe("File path"),
       offset: z.number().optional().describe("Start line (0-indexed)"),
@@ -690,13 +690,28 @@ export function createServer(): McpServer {
       const result = cachedRead(path, { offset, limit });
 
       if (summarize && result.content.length > 500) {
-        const processed = await processOutput(`cat ${path}`, result.content);
-        logCall("read_file", { command: path, outputTokens: estimateTokens(result.content), tokensSaved: processed.tokensSaved, durationMs: Date.now() - start, aiProcessed: true });
+        // AI-native file summary — ask directly what the file does
+        const provider = getOutputProvider();
+        const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+        const content = result.content.length > 8000 ? result.content.slice(0, 8000) : result.content;
+        const summary = await provider.complete(
+          `File: ${path}\n\n${content}`,
+          {
+            model: outputModel,
+            system: `Describe what this source file does in 2-4 lines. Include: main class/module name, key methods/functions, what it exports, and its purpose. Be specific — name the actual functions and what they do. Never just say "N lines of code."`,
+            maxTokens: 300,
+            temperature: 0.2,
+          }
+        );
+        const outputTokens = estimateTokens(result.content);
+        const summaryTokens = estimateTokens(summary);
+        const saved = Math.max(0, outputTokens - summaryTokens);
+        logCall("read_file", { command: path, outputTokens, tokensSaved: saved, durationMs: Date.now() - start, aiProcessed: true });
         return {
           content: [{ type: "text" as const, text: JSON.stringify({
-            summary: processed.summary,
+            summary,
             lines: result.content.split("\n").length,
-            tokensSaved: processed.tokensSaved,
+            tokensSaved: saved,
             cached: result.cached,
           }) }],
         };
@@ -944,7 +959,7 @@ Match by function name, class name, method name (including ClassName.method), in
 
   server.tool(
     "edit",
-    "Find and replace text in a file. Agent says what to change, no sed/awk/python needed. Saves ~200 tokens vs constructing shell commands.",
+    "Find and replace in a file. For simple edits, prefer your native Edit tool (faster). Use this for batch replacements (all=true) or when you don't have a native Edit tool available.",
     {
       file: z.string().describe("File path"),
       find: z.string().describe("Text to find (exact match)"),

package/src/recipes/storage.ts

@@ -28,14 +28,36 @@ function saveStore(filePath: string, store: RecipeStore): void {
   writeFileSync(filePath, JSON.stringify(store, null, 2));
 }
 
+// ── Built-in system recipes (always available, zero config) ─────────────────
+
+const SYSTEM_RECIPES: Recipe[] = [
+  // Git workflows
+  { id: "sys-commit-push", name: "commit-push", description: "Stage all, commit, push to origin", command: "git add -A && git commit -m \"{message}\" && git push", tags: ["git"], collection: "git", variables: [{ name: "message", required: true }], createdAt: 0, updatedAt: 0 },
+  { id: "sys-pr", name: "create-pr", description: "Create GitHub PR from current branch", command: "gh pr create --title \"{title}\" --body \"{body}\"", tags: ["git", "github"], collection: "git", variables: [{ name: "title", required: true }, { name: "body", default: "" }], createdAt: 0, updatedAt: 0 },
+  { id: "sys-stash", name: "stash-switch", description: "Stash changes, switch branch, pop", command: "git stash && git checkout {branch} && git stash pop", tags: ["git"], collection: "git", variables: [{ name: "branch", required: true }], createdAt: 0, updatedAt: 0 },
+
+  // Quality checks
+  { id: "sys-todos", name: "find-todos", description: "Find all TODO/FIXME/HACK in source code", command: "grep -rn 'TODO\\|FIXME\\|HACK\\|XXX' {path} --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' --include='*.go' --include='*.rs' --include='*.java' --include='*.rb'", tags: ["quality"], collection: "quality", variables: [{ name: "path", default: "src/" }], createdAt: 0, updatedAt: 0 },
+  { id: "sys-deadcode", name: "find-unused-exports", description: "Find exported symbols that may be unused", command: "grep -rn 'export ' {path} --include='*.ts' | sed 's/.*export //' | sed 's/[(<:].*//' | sort -u", tags: ["quality"], collection: "quality", variables: [{ name: "path", default: "src/" }], createdAt: 0, updatedAt: 0 },
+  { id: "sys-security", name: "security-scan", description: "Scan for common security anti-patterns", command: "grep -rn 'eval\\|exec\\|spawn\\|innerHTML\\|dangerouslySetInnerHTML\\|password.*=.*[\"'\\']' {path} --include='*.ts' --include='*.js' --include='*.py'", tags: ["security"], collection: "quality", variables: [{ name: "path", default: "src/" }], createdAt: 0, updatedAt: 0 },
+
+  // Project info
+  { id: "sys-deps", name: "list-deps", description: "Show project dependencies", command: "cat package.json 2>/dev/null | grep -A 100 '\"dependencies\"' | head -30 || cat requirements.txt 2>/dev/null || cat Cargo.toml 2>/dev/null | grep -A 50 'dependencies'", tags: ["deps"], collection: "project", variables: [], createdAt: 0, updatedAt: 0 },
+  { id: "sys-size", name: "project-size", description: "Count lines of code by file type", command: "find {path} -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/.git/*' -type f | xargs wc -l 2>/dev/null | sort -rn | head -20", tags: ["stats"], collection: "project", variables: [{ name: "path", default: "src/" }], createdAt: 0, updatedAt: 0 },
+
+  // Process management
+  { id: "sys-port", name: "kill-port", description: "Kill whatever is running on a port", command: "lsof -ti :{port} | xargs kill -9 2>/dev/null || echo 'Port {port} is free'", tags: ["process"], collection: "system", variables: [{ name: "port", required: true }], createdAt: 0, updatedAt: 0 },
+  { id: "sys-disk", name: "disk-usage", description: "Show disk usage of current directory", command: "du -sh {path}/* 2>/dev/null | sort -rh | head -15", tags: ["system"], collection: "system", variables: [{ name: "path", default: "." }], createdAt: 0, updatedAt: 0 },
+];
+
 // ── CRUD operations ──────────────────────────────────────────────────────────
 
-/** Get all recipes (merged: global + project-scoped) */
+/** Get all recipes (merged: system + global + project-scoped) */
 export function listRecipes(projectPath?: string): Recipe[] {
   const global = loadStore(GLOBAL_FILE).recipes;
-  if (!projectPath) return global;
+  if (!projectPath) return [...global, ...SYSTEM_RECIPES];
   const project = loadStore(projectFile(projectPath)).recipes;
-  return [...project, ...global]; // project recipes first (higher priority)
+  return [...project, ...global, ...SYSTEM_RECIPES]; // project > global > system priority
 }
 
 /** Get recipes filtered by collection */