fluxflow-cli 1.7.20 → 1.7.21

package/README.md

@@ -1,14 +1,38 @@
-# 🌌 Flux Flow (`fluxflow-cli`)
-![Flux Flow Logo](https://github.com/KushalRoyChowdhury/fluxflow-cli/blob/main/fluxflow.png)
+# 🌊 Flux Flow
+![Flux Flow Hero](./fluxflow.png)
 
-### *The High-Fidelity Agentic Terminal for the Flux Era.*
+**A Beautiful, Autonomous Terminal AI Agent**
 
-**Flux Flow** is not just another CLI—it's a high-speed, sassy, and goal-oriented CLI AI Agent powered by the latest Gemini/Gemma frontier models. Designed for developers who demand a premium UI/UX while managing complex file-system tasks, web research, and autonomous workflows.
+Flux Flow is an advanced, fully autonomous AI agent that lives directly in your terminal. Built with Node.js and [Ink](https://github.com/vadimdemedes/ink) (React for interactive command-line apps), it provides a highly responsive, component-based UI powered by a sophisticated dual-model AI architecture.
+
+Whether you need a conversational partner or an autonomous developer that can write code, run shell commands, and read your project files, Flux Flow adapts to your needs.
 
 ---
 
-## 🚀 Instant Ignition (No Setup Required)
-You don't even need to install it. Just fire up your terminal and run:
+## ✨ Features
+
+- **Native Multimodality**: Flux Flow can now see! Analyze images (JPG, PNG) and PDF documents natively through the `view_file` tool with high-fidelity context retention.
+- **Document Engineering Suite**: Generate professional, branded PDF, DOCX, and PPTX documents on the fly. Features native HTML-to-Office translation for selectable text, high-performance rendering, and automatic watermarking.
+- **External Data Sanctuary**: Redirect your logs, history, and memories to any external path for maximum portability and privacy.
+- **Responsive Terminal UI**: A gorgeous, reactive interface built with React and Ink, featuring multi-line input, status bars, modals, and diff views.
+- **Dual-Model Architecture**: A primary agent interacts with you and executes tasks, while a silent background "Janitor" model handles chat summarization and long-term memory extraction without blocking the main UI.
+- **Two Operating Modes**:
+  - **Flux (Dev Mode)**: Full system access. The agent can read/write files, execute shell commands, and run autonomous agentic loops (up to 45 iterations) to solve complex coding tasks.
+  - **Flow (Chat Mode)**: Focused on conversation and web research, with limited agentic loops for faster response times.
+- **Advanced Memory System**: Features both temporary session context and persistent, cross-session user memories encrypted locally on your machine.
+- **Agentic Tooling**: Built-in tools for smart file patching, web scraping, web searching, terminal execution and high-fidelity Office document generation (PDF/DOCX/PPTX).
+- **Autonomous Project Alignment**: Automatically detects and adheres to project-specific instructions in `Agent.md`, `Skills.md`, and `Fluxflow.md` for high-fidelity coding standards and complex workflows.
+- **Customizable "Thinking" Levels**: Adjust the depth of the model's reasoning process (from Minimal to Max).
+- **High-Reliability Fallback**: Automatic failover to a lighter, high-concurrency model (Gemini 3.1 Flash Lite) during peak traffic to ensure 100% session persistence.
+
+## 🚀 Quick Start
+
+### Prerequisites
+- [Node.js](https://nodejs.org/) (v18 or higher recommended)
+- `npm`, `yarn`, or `pnpm`
+
+### Via NPM (Global & Instant)
+You can run the agent instantly or install it globally for high-speed access:
 
 ```bash
 # Run instantly (Zero Setup)
@@ -16,69 +40,45 @@ npx fluxflow-cli
 
 # OR Install Globally
 npm install -g fluxflow-cli
-fluxflow-cli
+fluxflow
 ```
 
-*The agent will prompt you for your Gemini API Key on the first run and store it securely in an XOR-encrypted vault.* Free API Key recomemded to use Gemma 4 (Default Model).
-
----
-
-## ✨ Why Flux Flow?
-
-### 🎨 **Premium Visual Sovereignty**
-Experience a terminal UI that feels alive. Built with **Ink** and **React**, Flux Flow features:
-- **Dynamic Status Bar**: Real-time telemetry showing your "Neural Headroom" (token usage), Thinking Level, and Session ID.
+### From Source (Local Development)
+1. Clone the repository and install dependencies:
+   ```bash
+   git clone <repository-url>
+   cd Flux-Flow
+   npm install
+   ```
 
-### 👁️ **Native Multimodality**
-Flux Flow can now see! Use the `view_file` tool to analyze images (JPG, PNG) or deep-dive into PDF technical papers. The agent extracts high-fidelity visual context natively, making it a true multimodal companion.
+2. Start the agent:
+   ```bash
+   npm start
+   ```
 
-### 📑 **Document Engineering Suite**
-Need a report or a presentation? Just ask. Flux Flow features a high-fidelity "Printing Press" that generates professional, branded documents natively:
-- **PDF**: Branded documents from HTML/CSS with automatic watermarking.
-- **DOCX**: Native Word documents with multi-page support and automatic numbering.
-- **PPTX**: High-fidelity PowerPoint presentations using native elements (selectable text, shapes) translated directly from HTML.
+## 📖 Documentation
 
-### 🚑 **Self-Healing Infrastructure**
-Zero setup means zero setup. On first run, Flux Flow performs an integrity check and autonomously installs its own Chromium engine if needed, ensuring features like PDF generation work 100% of the time without manual intervention.
+To keep this README concise, detailed information about specific components of Flux Flow has been split into separate documents:
 
-- **Archived Terminal Flow**: See execution outputs transform from live elements into permanent conversation records.
-- **Rich Aesthetics**: High-contrast, sleek design with smooth transitions and micro-animations.
+- **[Architecture & Design](./ARCHITECTURE.md)**: Deep dive into the React/Ink rendering, the Agentic Loop, and the Janitor background process.
+- **[Agent Tools & Capabilities](./TOOLS.md)**: A comprehensive list of the tools available to the agent (e.g., File I/O, Execution, Web tools).
+- **[UI & Interaction Features](./UI_FEATURES.md)**: Details on commands, thinking levels, and human-in-the-loop verification.
 
-### 🧠 **The Dual-Intelligence System**
-- **Flux Mode (Dev)**: High-speed, agentic problem solving with a 50-turn persistent loop for massive coding tasks.
-- **Flow Mode (Chat)**: Optimized for deep research, high-quality conversation, and web-assisted reasoning.
+## 🔒 Security & Privacy
 
-### 🛡️ **Digital Fortress Governance**
-Security isn't an afterthought; it's a boundary.
-- **External Path Hardlock**: Restricts the agent to your Current Working Directory (CWD) unless you explicitly unlock it.
-- **Human-in-the-Loop (HITL)**: Every file write and terminal command requires your high-fidelity approval.
-- **XOR Vaulting**: All local session histories, memories, and API keys are obfuscated and encrypted at rest.
-- **Adaptive Failover**: Automatic multi-stage retry logic with high-concurrency fallback model switching (Gemini 3.1 Flash Lite) during peak API congestion.
+Flux Flow runs entirely locally on your machine.
+- **Global Storage**: All history, memories, and API keys are stored securely in your home directory at `~/.fluxflow`. Sensitive data is encrypted.
+- **Nuclear Reset**: Use the `/reset` command to instantly purge all logs, secrets, and settings from the global storage directory.
+- **Configurable Boundaries**: In Flux mode, file access can be strictly confined to the Current Working Directory, or expanded globally via settings.
+- **API Keys**: You supply your own Gemini/Google AI Studio API keys.
 
-### 🧹 **The Background Janitor**
-While you move at high speed, the Janitor follows behind—refining session titles, compressing data, and ensuring your context window remains at absolute peak performance.
-
----
-
-## 🛠️ Key Capabilities
-- **Deep File-System Interaction**: Edit, move, and refactor code across multiple files with atomic precision.
-- **Real-Time Web Intelligence**: Autonomous web-searching via DuckDuckGo for live news and technical research.
-- **Autonomous Project Alignment**: Automatically detects and adheres to project-specific instructions in `Agent.md`, `Skills.md`, and `Fluxflow.md` for high-fidelity alignment with your coding standards and custom workflows.
-- **High-Reliability Fallback**: Automatic failover to a lighter, high-concurrency model during peak traffic to ensure zero session loss.
-- **Persistent Memory**: The agent learns from your preferences and project requirements across sessions.
-
----
-
-## ⚙️ Configuration
-Type `/settings` in-app to live-configure:
-- **Thinking Level**: Low, Medium, or High (Deep-Reasoning).
-- **Auto-Execution**: For ultimate high-speed flow (Advanced users only).
-- **Security Perimeter**: Toggle External Workspace access.
-
----
+## 🛠️ Built With
 
-## 🏁 License
-MIT © 2026 Flux Flow Team.
+- **[React](https://react.dev/) & [Ink](https://github.com/vadimdemedes/ink)**: For the interactive CLI rendering.
+- **[@google/genai](https://www.npmjs.com/package/@google/genai)**: The core AI SDK powering the agent's intelligence.
+- **[chalk](https://www.npmjs.com/package/chalk) & [gradient-string](https://www.npmjs.com/package/gradient-string)**: For terminal styling and aesthetics.
+- **[fs-extra](https://www.npmjs.com/package/fs-extra)**: For robust file system operations.
+- **[pptxgenjs](https://www.npmjs.com/package/pptxgenjs) & [html-to-docx](https://www.npmjs.com/package/html-to-docx)**: For native Office document generation.
 
 ---
-*Forged with ⚡ and 🧬. Welcome to the FluxFlow.*
+*Created as a demonstration of highly capable AI tooling.*

package/dist/fluxflow.js

@@ -716,7 +716,7 @@ ${mode === "Flux" ? `
     2. List Files: tool:functions.list_files(path="relative/path"). Lists content of a directory.
     3. Read Folder: tool:functions.read_folder(path="relative/path"). Detailed stats of a directory. Prefer this one over list_files.
     4. Write File: tool:functions.write_file(path="path", content="content"). Creates/Overwrites. NO CODE BLOCKS. RETURNS: Disk verification + original content (if overwritten) for 100% reversibility. Escape your double quotes '"' using backslash.
-    5. Update File: tool:functions.update_file(path="relative/path", content_to_replace="old", content_to_add="new"). Surgical patching. RETURNS: High-fidelity visual diff and old code block. You MUST verify that the change specifically matches your intent using the returned diff. PREFFER UPDATE FILE OVER WRITE FILE if file already exists for better reversal tracking (if a file has 500+ lines, try to stick with update_file over full-rewrite). DONT WRAP UPDATE FILE CALL CONTENT IN MARKDOWN CODE BLOCKS. KEEP YOUR PATCH INDENTATION AT BASE LEVEL WITH INTERNAL NESTED INDENTATION IN YOUR PROVIDED CODE INTACT, THE SYSTEM WILL HANDLE FILE LEVEL INDENTATION.
+    5. Update File: tool:functions.update_file(path="relative/path", content_to_replace="old/fuzzy indentation matching supported", content_to_add="new"). Surgical patching. RETURNS: High-fidelity visual diff and old code block. You MUST verify that the change specifically matches your intent using the returned diff. PREFFER UPDATE FILE OVER WRITE FILE if file already exists for better reversal tracking (if a file has 500+ lines, try to stick with update_file over full-rewrite). DONT WRAP UPDATE FILE CALL CONTENT IN MARKDOWN CODE BLOCKS. KEEP YOUR PATCH INDENTATION AT BASE LEVEL WITH INTERNAL NESTED INDENTATION IN YOUR PROVIDED CODE INTACT, THE SYSTEM WILL HANDLE FILE LEVEL INDENTATION.
     6. Write PDF: tool:functions.write_pdf(path="path", content="<html/css content>", orientation="portrait/landscape"). Generates a professional PDF document. Orientation are optional. A4 size page will be used, so any multi-page PDFs calculate your alightment and page breaks to not mess up A4 page layout. DO NOT ADD FOOTER MANUALLY, the system will handle it automatically. USE CSS TO VISUALLY BEAUTIFY THE DOCUMENT, USE full 100vh & 100vw for page area. ENSURE THE CONTENT IS NEVER BROKEN IN BETWEEN PAGES, USE PAGE BREAKS PROACTIVELY FOR A A4 PAGE LAYOUT. Keep generous margins for better redability.
     7. Write DOCX: tool:functions.write_docx(path="path", content="<html content>"). Generates a professional Word document (.docx) from HTML. You can make multiple pages. Default Page dimentions will be A4, use proper margins and page break strategy.
     8. Write PPTX: tool:functions.write_pptx(path="path", content="<h1 style='color: #0088CC;'>Title</h1><ul style='font-size: 14pt;'><li>Point A</li></ul>
@@ -728,7 +728,8 @@ ${mode === "Flux" ? `
 
 AFTER GETTING THE TOOL RESULT, YOU MUST VERIFY THAT ITS A SUCCESS, IF IT GIVES A ERROR, TELL THE USER AND TRY TO FIX IF YOU CAN. DO NOT HALLUCINATE SUCCESS IF TOOL RETURNS ERROR.
 NEVER GUESS A CODE, IF UNSURE READ THE FILE FIRST BEFORE EDITING IT.
-**CRITICAL POLICY: WHEN WRITING/UPDATING FILES, ALWAYS USE ACTUAL NEW LINE CONTROL CHARACTER (LF) FOR LINE BREAKS. WHEN YOU WANT TO WRITE \\n IN THE FILE PROPERLY ESPACE IT.**`.trim() : `
+**CRITICAL POLICY: WHEN WRITING/UPDATING FILES, ALWAYS USE ACTUAL NEW LINE CONTROL CHARACTER (LF) FOR LINE BREAKS. WHEN YOU WANT TO WRITE '
+' IN THE FILE PROPERLY ESPACE IT WITH DOUBLE BACKSLASHES.**`.trim() : `
     - DEV & FILE TOOLS ARE NOT AVAILABLE IN FLOW MODE. If you need to access files, tell the user to switch to FLUX MODE (manually by user).`.trim()}
 -----------------
 
@@ -1808,8 +1809,8 @@ var init_update_file = __esm({
           diskContent = normalizedDisk;
         }
         const currentContent = diskContent;
-        const adjustIndentation = (newText, originalMatch) => {
-          if (!newText || !originalMatch) return newText;
+        const adjustIndentation = (newText, originalMatch, leadingContext = "") => {
+          if (!newText || originalMatch === void 0) return newText;
           const getMinIndent = (text) => {
             const lines = text.split("\n").filter((l) => l.trim() !== "");
             if (lines.length === 0) return "";
@@ -1820,38 +1821,39 @@ var init_update_file = __esm({
             }
             return min;
           };
-          const originalMinIndent = getMinIndent(originalMatch);
+          const originalMinIndent = getMinIndent(leadingContext + originalMatch);
           const newMinIndent = getMinIndent(newText);
-          const newLines2 = newText.split("\n");
-          return newLines2.map((line) => {
-            if (line.trim() === "") return "";
-            if (line.startsWith(newMinIndent)) {
-              return originalMinIndent + line.substring(newMinIndent.length);
+          const newLines = newText.split("\n");
+          return newLines.map((line, i) => {
+            if (line.trim() === "" && i !== 0) return "";
+            const currentOriginalIndent = i === 0 ? originalMinIndent.substring(Math.min(originalMinIndent.length, leadingContext.length)) : originalMinIndent;
+            const lineIndent = line.match(/^\s*/)[0];
+            if (lineIndent.startsWith(newMinIndent)) {
+              return currentOriginalIndent + line.substring(newMinIndent.length);
             }
-            return originalMinIndent + line.trimStart();
+            if (newMinIndent.startsWith(lineIndent)) {
+              const diff = newMinIndent.length - lineIndent.length;
+              const adjustedIndent = currentOriginalIndent.substring(0, Math.max(0, currentOriginalIndent.length - diff));
+              return adjustedIndent + line.trimStart();
+            }
+            return currentOriginalIndent + line.trimStart();
           }).join("\n");
         };
-        let matchRegex = null;
         let instances = 0;
         let startPos = -1;
-        if (currentContent.includes(content_to_replace)) {
-          instances = currentContent.split(content_to_replace).length - 1;
-          startPos = currentContent.indexOf(content_to_replace);
+        let matchRegex = null;
+        const escaped = content_to_replace.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        if (content_to_replace !== "" && currentContent.includes(content_to_replace)) {
+          matchRegex = new RegExp(escaped, "g");
         } else {
-          const escaped = content_to_replace.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-          const fuzzyPattern = escaped.trim().replace(/\s+/g, "\\s+");
+          const fuzzyPattern = escaped.trim().replace(/\s+/g, "\\s*");
           try {
-            const fuzzyRegex = new RegExp(fuzzyPattern, "g");
-            const matches = [...currentContent.matchAll(fuzzyRegex)];
-            if (matches.length > 0) {
-              matchRegex = fuzzyRegex;
-              instances = matches.length;
-              startPos = matches[0].index;
-              content_to_replace = matches[0][0];
-            }
+            matchRegex = new RegExp(fuzzyPattern, "g");
           } catch (e) {
           }
         }
+        const matches = matchRegex ? [...currentContent.matchAll(matchRegex)] : [];
+        instances = matches.length;
         if (instances === 0) {
           const diskLen = currentContent.length;
           const matchLen = content_to_replace.length;
@@ -1860,13 +1862,24 @@ var init_update_file = __esm({
 - Match String Length (Normalized): ${matchLen}
 - Check indentation/whitespace. Try re-reading the file for latest changes.`;
         }
-        const startLine = currentContent.substring(0, startPos).split(/\r?\n/).length;
-        const newFileContent = matchRegex ? currentContent.replace(matchRegex, (match) => adjustIndentation(content_to_add, match)) : currentContent.split(content_to_replace).join(adjustIndentation(content_to_add, content_to_replace));
-        content_to_add = adjustIndentation(content_to_add, content_to_replace);
+        if (instances > 1) {
+          return `ERROR: Unable to find unique match. [${instances}] instances of the specified "content_to_replace" were found in [${targetPath}]. Try providing more context (surrounding lines) to make the match unique.`;
+        }
+        startPos = matches[0].index;
+        const firstMatchContent = matches[0][0];
+        const newFileContent = currentContent.replace(matchRegex, (match, offset) => {
+          const lineStart = currentContent.lastIndexOf("\n", offset) + 1;
+          const leadingContext = currentContent.substring(lineStart, offset);
+          return adjustIndentation(content_to_add, match, leadingContext);
+        });
+        const firstLineStart = currentContent.lastIndexOf("\n", startPos) + 1;
+        const firstLeadingContext = currentContent.substring(firstLineStart, startPos);
+        const finalContentToAdd = adjustIndentation(content_to_add, firstMatchContent, firstLeadingContext);
+        const finalContentToReplace = firstMatchContent;
         fs11.writeFileSync(absolutePath, newFileContent, "utf8");
         const allOriginalLines = currentContent.split(/\r?\n/);
+        const startLine = currentContent.substring(0, startPos).split(/\r?\n/).length;
         const oldLines = content_to_replace.split(/\r?\n/);
-        const newLines = content_to_add.split(/\r?\n/);
         const endLine = startLine + oldLines.length - 1;
         let diffText = `SUCCESS: File [${targetPath}] updated. [${instances}] instances replaced.
 
@@ -4766,7 +4779,7 @@ var init_app = __esm({
     init_text();
     SESSION_START_TIME = Date.now();
     CHANGELOG_URL = "https://fluxflow-cli.onrender.com/changelog.html";
-    versionFluxflow = "1.7.20";
+    versionFluxflow = "1.7.21";
     updatedOn = "2026-05-07";
     ResolutionModal = ({ data, onResolve, onEdit }) => /* @__PURE__ */ React10.createElement(Box10, { flexDirection: "column", borderStyle: "round", borderColor: "magenta", paddingX: 2, paddingY: 1, width: "100%" }, /* @__PURE__ */ React10.createElement(Text10, { color: "magenta", bold: true, underline: true }, "\u{1F7E3} STEERING HINT RESOLUTION"), /* @__PURE__ */ React10.createElement(Text10, { marginTop: 1 }, "The agent already finished the task before your hint was consumed."), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1, backgroundColor: "#222", paddingX: 1, width: "100%" }, /* @__PURE__ */ React10.createElement(Text10, { italic: true, color: "gray" }, '"', data, '"')), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1 }, /* @__PURE__ */ React10.createElement(Text10, { color: "cyan" }, "How would you like to proceed?")), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1 }, /* @__PURE__ */ React10.createElement(
       CommandMenu,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "fluxflow-cli",
-	"version": "1.7.20",
+	"version": "1.7.21",
 	"description": "A high-fidelity agentic terminal assistant for the Flux Era.",
 	"keywords": [
 		"ai",