@hasna/terminal 1.6.5 → 1.6.7

package/README.md

@@ -183,12 +183,44 @@ Every command through `terminal exec` goes through:
 6. **Structured Parsing** — JSON instead of text
    - Git status/log, test results, build output, npm install, errors
 
+## Best Practices for 95%+ Reliability
+
+Tested across 149 queries by 3 independent agents on 3 different repos:
+
+```bash
+# Session start (100% reliable)
+terminal repo                                    # Git status + recent commits
+terminal "ls packages/"                          # Package overview (monorepo)
+terminal symbols src/main.ts                     # Key file structure
+
+# Code exploration (use path hints!)
+terminal "in src/lib, what functions are exported"  # Path hint = 80%+ reliability
+terminal "grep -rn 'pattern' src/"               # Command passthrough works too
+terminal symbols src/db/tasks.ts                 # 100% reliable on valid files
+
+# Git queries (100% reliable, any phrasing)
+terminal "what changed in the last 3 commits"
+terminal "who made the most recent change"
+
+# System queries (100% reliable)
+terminal "how many typescript files"
+terminal "what testing framework is used"
+terminal "show me the package.json scripts"
+```
+
+**Key rules:**
+- Include package/directory paths in your query for best results
+- Use `terminal symbols <file>` for file outlines (100% reliable)
+- Use `terminal repo` at session start (replaces 3 git commands)
+- For literal commands: `terminal "grep -rn pattern src/"` works with answer framing
+- Git and system queries work with any phrasing
+
 ## CLI Commands
 
 ```
-terminal                        Launch NL terminal (TUI)
-terminal exec <command>         Smart execution with full pipeline
-terminal repo                   Git repo state in one call
+terminal "your request"         NL → AI runs command → smart answer
+terminal                        Launch interactive NL terminal (TUI)
+terminal repo                   Git status + diff + log in one call
 terminal symbols <file>         File outline (functions, classes, exports)
 terminal stats                  Token economy dashboard
 terminal sessions               List recent sessions

package/dist/cli.js

@@ -421,20 +421,24 @@ else if (args.length > 0) {
         command = await translateToCommand(prompt, perms, []);
     }
     catch (e) {
-        // If BLOCKED, try fallback: read README or package.json for conceptual questions
+        // If BLOCKED, try README fallback ONLY for conceptual questions (not file access)
         if (e.message?.startsWith("BLOCKED:")) {
-            try {
-                const { existsSync, readFileSync } = await import("fs");
-                if (existsSync("README.md")) {
-                    const readme = readFileSync("README.md", "utf8").slice(0, 3000);
-                    const processed = await processOutput("cat README.md", readme, prompt);
-                    if (processed.aiProcessed) {
-                        console.log(processed.summary);
-                        process.exit(0);
+            const isConceptual = /\b(explain|why|what does|how does|describe|architecture|overview|summary)\b/i.test(prompt);
+            const isFileAccess = /\b(cat|show|read|find|ls|list)\b.*\b(\.\w+\/|src\/|packages\/)/i.test(prompt);
+            if (isConceptual && !isFileAccess) {
+                try {
+                    const { existsSync, readFileSync } = await import("fs");
+                    if (existsSync("README.md")) {
+                        const readme = readFileSync("README.md", "utf8").slice(0, 3000);
+                        const processed = await processOutput("cat README.md", readme, prompt);
+                        if (processed.aiProcessed) {
+                            console.log(processed.summary);
+                            process.exit(0);
+                        }
                     }
                 }
+                catch { }
             }
-            catch { }
         }
         console.error(e.message);
         process.exit(1);

package/package.json

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

package/src/cli.tsx

@@ -402,19 +402,23 @@ else if (args.length > 0) {
   try {
     command = await translateToCommand(prompt, perms, []);
   } catch (e: any) {
-    // If BLOCKED, try fallback: read README or package.json for conceptual questions
+    // If BLOCKED, try README fallback ONLY for conceptual questions (not file access)
     if (e.message?.startsWith("BLOCKED:")) {
-      try {
-        const { existsSync, readFileSync } = await import("fs");
-        if (existsSync("README.md")) {
-          const readme = readFileSync("README.md", "utf8").slice(0, 3000);
-          const processed = await processOutput("cat README.md", readme, prompt);
-          if (processed.aiProcessed) {
-            console.log(processed.summary);
-            process.exit(0);
+      const isConceptual = /\b(explain|why|what does|how does|describe|architecture|overview|summary)\b/i.test(prompt);
+      const isFileAccess = /\b(cat|show|read|find|ls|list)\b.*\b(\.\w+\/|src\/|packages\/)/i.test(prompt);
+      if (isConceptual && !isFileAccess) {
+        try {
+          const { existsSync, readFileSync } = await import("fs");
+          if (existsSync("README.md")) {
+            const readme = readFileSync("README.md", "utf8").slice(0, 3000);
+            const processed = await processOutput("cat README.md", readme, prompt);
+            if (processed.aiProcessed) {
+              console.log(processed.summary);
+              process.exit(0);
+            }
           }
-        }
-      } catch {}
+        } catch {}
+      }
     }
     console.error(e.message);
     process.exit(1);