npm - @iflow-ai/iflow-cli - Versions diffs - 0.4.7 → 0.4.8-beta-20251217 - Mend

@iflow-ai/iflow-cli 0.4.7 → 0.4.8-beta-20251217

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +233 -156
package/bundle/iflow-cli-vscode-ide-companion-0.2.9.vsix +0 -0
package/bundle/iflow.js +3368 -3019
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -3,237 +3,314 @@
 **English** | [中文](README_CN.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Deutsch](README_DE.md) | [Español](README_ES.md) | [Русский](README_RU.md)
-iFlow CLI is a powerful AI assistant that runs directly in your terminal. It seamlessly analyzes code repositories, executes coding tasks, understands context-specific needs, and boosts productivity by automating everything from simple file operations to complex workflows.
+iFlow CLI is a powerful AI assistant that runs directly in your terminal. This repository contains the source code for the iFlow CLI application, built as a monorepo with TypeScript, Node.js, and React (via Ink). This document is intended for developers who want to understand, contribute to, or extend the iFlow CLI codebase.
-## ✨ Key Features
+## 📦 Project Overview
-1. **Free AI Models**: Access powerful and free AI models through the [iFlow open platform](https://docs.iflow.cn/en/docs), including Kimi K2, Qwen3 Coder, DeepSeek v3, and more
-2. **Flexible Integration**: Full support for OpenAI protocol model providers
-3. **Intuitive Interface**: Streamlined terminal experience with context-aware assistance
-4. **Ready-to-Use Assistant**: Pre-configured MCP servers and specialized agents that work together to solve complex problems right out of the box
+iFlow CLI is structured as a monorepo using npm workspaces. It consists of three main packages:
-## 📥 Installation
+- **`packages/cli`**: The command-line interface entry point, handling user interactions, command parsing, and terminal UI.
+- **`packages/core`**: The core engine providing AI agent orchestration, tool execution, context management, and integration with MCP (Model Context Protocol) servers.
+- **`packages/vscode-ide-companion`**: A VS Code extension that integrates iFlow CLI capabilities into the editor.
-### System requirements
-- Operating Systems: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)
-- Hardware: 4GB+ RAM
-- Software: Node.js 18+
-- Network: Internet connection required for authentication and AI processing
-- Shell: Works best in Bash, Zsh or Fish
+The application is built with modern JavaScript/TypeScript tooling, featuring a plugin-based architecture for extensibility.
-### Install Command
-```shell
-bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
+## 📁 Project Structure
+```
+iflow-cli/
+├── packages/                    # Monorepo packages (detailed below)
+├── scripts/                    # Build and utility scripts
+├── integration-tests/          # Integration test suites
+├── docs/                       # Documentation
+├── assets/                     # Images and static assets
+├── vendors/                    # Bundled third‑party tools (ripgrep)
+└── bundle/                     # Final bundled CLI (generated)
 ```
-This command automatically installs all necessary dependencies for your terminal.
+### Detailed Package Structure
-**Windows Users**:
-1. Go to https://nodejs.org/en/download to download the latest Node.js installer
-2. Run the installer to install Node.js
-3. Restart your terminal: CMD or PowerShell
-4. Run `npm install -g @iflow-ai/iflow-cli` to install iFlow CLI
-5. Run `iflow` to start iFlow CLI
+#### `packages/cli` – Command‑Line Interface
+```
+cli/
+├── src/
+│   ├── commands/              # Command definitions
+│   │   ├── agents/            # Agent‑related commands
+│   │   ├── commands/          # Slash command implementations
+│   │   ├── mcp/               # MCP command handlers
+│   │   └── workflows/         # Workflow commands
+│   ├── ui/                    # React components for terminal UI
+│   │   ├── components/        # Reusable UI components
+│   │   ├── contexts/          # React contexts (theme, state)
+│   │   ├── hooks/             # Custom React hooks
+│   │   ├── editors/           # Text‑editing components
+│   │   └── themes/            # UI theme definitions
+│   ├── services/              # CLI‑specific services
+│   ├── utils/                 # Utility functions
+│   ├── history/               # Conversation history management
+│   └── config/                # Configuration handling
+├── dist/                      # Compiled JavaScript (generated)
+└── [tests]/                   # Unit tests (alongside source files)
+```
-If you are in China Mainland, you can use the following command to install iFlow CLI:
-1. Go to https://cloud.iflow.cn/iflow-cli/nvm-setup.exe to download the latest nvm installer
-2. Run the installer to install nvm
-3. **Restart your terminal: CMD or PowerShell**
-4. Run `nvm node_mirror https://npmmirror.com/mirrors/node/` and `nvm npm_mirror https://npmmirror.com/mirrors/npm/`
-5. Run `nvm install 22` to install Node.js 22
-6. Run `nvm use 22` to use Node.js 22
-7. Run `npm install -g @iflow-ai/iflow-cli` to install iFlow CLI
-8. Run `iflow` to start iFlow CLI
+#### `packages/core` – Core Engine
+```
+core/
+├── src/
+│   ├── tools/                 # Tool implementations
+│   │   ├── task/              # Task tool & sub‑agent system
+│   │   ├── *.ts               # Individual tools (read‑file, shell, etc.)
+│   │   └── *.test.ts          # Tool unit tests
+│   ├── core/                  # Core AI client & orchestration
+│   │   ├── client.ts          # Gemini/iFlow API client
+│   │   ├── contentGenerator.ts# Content generation logic
+│   │   ├── coreToolScheduler.ts # Tool scheduling & concurrency
+│   │   └── ...
+│   ├── services/              # Background services
+│   │   ├── fileDiscoveryService.ts
+│   │   ├── gitService.ts
+│   │   ├── shellExecutionService.ts
+│   │   └── ...
+│   ├── config/                # Configuration management
+│   ├── mcp/                   # Model Context Protocol integration
+│   ├── telemetry/             # OpenTelemetry instrumentation
+│   ├── utils/                 # Shared utilities
+│   └── ...
+├── dist/                      # Compiled JavaScript (generated)
+└── [tests]/                   # Unit tests (alongside source files)
+```
-## 🔑 Authentication
+#### `packages/vscode‑ide‑companion` – VS Code Extension
+```
+vscode-ide-companion/
+├── src/
+│   ├── extension.ts           # VS Code extension entry point
+│   ├── ide‑server.ts          # Communication with iFlow CLI
+│   ├── diff‑manager.ts        # File diff handling
+│   └── open‑files‑manager.ts  # Open files state management
+├── assets/                    # Extension icons & assets
+├── .vscode/                   # VS Code configuration
+└── dist/                      # Compiled extension (generated)
+```
-iFlow offers two authentication options:
+### Other Key Directories
-1. **Recommended**: Use iFlow's native authentication
-2. **Alternative**: Connect via OpenAI-compatible APIs
+- **`scripts/`** – Build, release, and maintenance scripts (e.g., `build.js`, `telemetry.js`).
+- **`integration‑tests/`** – End‑to‑end tests for tool interactions and sandbox behavior.
+- **`docs/`** – Comprehensive documentation (architecture, CLI usage, troubleshooting).
+- **`vendors/`** – Bundled third‑party binaries (ripgrep) used by tools.
+- **`bundle/`** – Final bundled CLI artifact (created by `npm run bundle`).
-![iFlow CLI Login](./assets/login.jpg)
+## 🏛️ Architecture Deep Dive
-To get your API key:
-1. Register for an iFlow account
-2. Go to your profile settings or click [this direct link](https://iflow.cn/?open=setting)
-3. Click "Reset" in the pop-up dialog to generate a new API key
+iFlow CLI follows a layered, event‑driven architecture designed for extensibility and security. The core components are:
-![iFlow Profile Settings](./assets/profile-settings.jpg)
+### Core Layer (`packages/core`)
+- **Tool System**: Registration, discovery, and execution of tools (file operations, shell, web, etc.). Tools are defined as classes extending `BaseTool` with parameter validation and permission control.
+- **Agent System**: Orchestration of sub‑agents (`general‑purpose`, `plan‑agent`, `explore‑agent`) for parallel task execution. Each agent has isolated tool permissions and MCP access.
+- **MCP Integration**: Native support for Model Context Protocol servers, allowing dynamic tool discovery from external processes.
+- **Event System**: Asynchronous communication between components (tool calls, agent lifecycle, UI updates).
+- **Configuration & Auth**: Centralized config management and multiple authentication providers (iFlow native, OpenAI‑compatible).
-After generating your key, paste it into the terminal prompt to complete setup.
+### CLI Layer (`packages/cli`)
+- **React‑based UI**: Built with [Ink](https://github.com/vadimdemedes/ink) for terminal rendering, using hooks and components for interactive prompts, streaming output, and real‑time status.
+- **Command Parser**: Handles slash commands (`/init`), direct agent calls (`$explore‑agent`), and natural‑language queries.
+- **State Management**: React hooks manage conversation history, tool call status, and user preferences.
-## 🚀 Getting Started
+### Integration Layer
+- **Sandbox Environment**: Optional Docker/Podman isolation for risky tool executions.
+- **Telemetry**: OpenTelemetry‑based metrics, traces, and logs for debugging and performance monitoring.
+- **Git Integration**: Automatic detection of repositories, commit message generation, and diff viewing.
-To launch iFlow CLI, navigate to your workspace in the terminal and type:
+For a comprehensive architecture overview, see [Architecture Documentation](./docs/architecture/overview.md).
-```shell
-iflow
-```
+## 🛠️ Technology Stack
-### Starting New Projects
+- **Runtime**: Node.js ≥20
+- **Language**: TypeScript with strict mode
+- **UI Framework**: React via [Ink](https://github.com/vadimdemedes/ink) for terminal rendering
+- **Build Tool**: esbuild for bundling, tsc for type checking
+- **Package Manager**: npm (workspaces)
+- **Testing**: Vitest for unit tests, custom integration test runner
+- **Linting/Formatting**: ESLint, Prettier
-For new projects, simply describe what you want to create:
+## 🏗️ Building the Project
-```shell
-cd new-project/
-iflow
-> Create a web-based Minecraft game using HTML
+### Build All Packages
+```bash
+npm install && npm run build
 ```
-### Working with Existing Projects
+This command runs the TypeScript compiler for each package and produces output in `packages/*/dist`.
-For existing codebases, begin with the `/init` command to help iFlow understand your project:
+### Build with Bundling (Beta)
-```shell
-cd project1/
-iflow
-> /init
-> Analyze the requirements according to the PRD document in requirement.md file, and output a technical document, then implement the solution.
+```bash
+npm run release:version [version]
+npm pack
 ```
-The `/init` command scans your codebase, learns its structure, and creates an IFLOW.md file with comprehensive documentation.
+The `bundle` script generates the final standalone CLI artifact in the `bundle/` directory, which is what gets published to npm.
-For a complete list of slash commands and usage instructions, see [here](./docs/cli/commands.md).
-## 💡 Common Use Cases
-iFlow CLI extends beyond coding to handle a wide range of tasks:
+## 🧪 Testing
-### 📊 Information & Planning
+### Unit Tests
-```text
-> Help me find the best-rated restaurants in Los Angeles and create a 3-day food tour itinerary.
+test packages/cli module:
+```bash
+npm run build --workspaces && npm run typecheck --workspace=@iflow-ai/iflow-cli && npm run test:ci --workspace=@iflow-ai/iflow-cli
 ```
-```text
-> Search for the latest iPhone price comparisons and find the most cost-effective purchase option.
+test packages/core module:
+```bash
+npm run build --workspaces && npm run typecheck --workspace=@iflow-ai/iflow-cli-core && npm run test:ci --workspace=@iflow-ai/iflow-cli-core
 ```
-### 📁 File Management
+Runs Vitest tests across all packages.
-```text
-> Organize the files on my desktop by file type into separate folders.
-```
+### Integration Tests
-```text
-> Batch download all images from this webpage and rename them by date.
-```
+Integration tests verify tool interactions and sandbox behavior. They can run with different sandbox backends:
-### 📈 Data Analysis
+```bash
+# No sandbox
+npm run test:integration:sandbox:none
-```text
-> Analyze the sales data in this Excel spreadsheet and generate a simple chart.
-```
+# With Docker sandbox
+npm run test:integration:sandbox:docker
-```text
-> Extract customer information from these CSV files and merge them into a unified table.
+# With Podman sandbox
+npm run test:integration:sandbox:podman
 ```
-### 👨‍💻 Development Support
+### End‑to‑End Tests
-```text
-> Analyze the main architectural components and module dependencies of this system.
+```bash
+npm run test:e2e
 ```
-```text
-> I'm getting a null pointer exception after my request, please help me find the cause of the problem.
+### Linting and Formatting
+```bash
+npm run lint          # ESLint check
+npm run lint:fix      # ESLint auto‑fix
+npm run format        # Prettier formatting
+npm run typecheck     # TypeScript type checking
 ```
-### ⚙️ Workflow Automation
+## 🔌 Extending iFlow CLI
-```text
-> Create a script to periodically backup my important files to cloud storage.
-```
+### Adding a New Tool
-```text
-> Write a program that downloads stock prices daily and sends me email notifications.
-```
+1. **Create a new tool file** in `packages/core/src/tools/` (e.g., `my-tool.ts`).
+2. **Extend `BaseTool`** and implement the required methods:
+   ```typescript
+   export class MyTool extends BaseTool<MyParams, ToolResult> {
+     constructor() {
+       super('my_tool', 'My Tool', 'Description for the AI', Icon.Hammer);
+     }
+     // Define parameter schema, validation, execution logic
+   }
+   ```
+3. **Register the tool** in `packages/core/src/tools/tools.ts` by adding it to the `coreTools` array.
+4. **Write tests** following existing patterns (e.g., `my-tool.test.ts`).
-*Note: Advanced automation tasks can leverage MCP servers to integrate your local system tools with enterprise collaboration suites.*
+See [Tool System Design](./docs/architecture/tool-system-design.md) and [Tools API](./docs/core/tools-api.md) for detailed guidance.
-## 🔧 Switch to Custom Model
+### Adding a New Agent Type
-iFlow CLI can connect to any OpenAI-compatible API. Edit the settings file in `~/.iflow/settings.json` to change the model you use.
+1. **Define agent metadata** in `packages/core/src/tools/task/agentRegistry.ts` under `AGENT_DEFINITIONS`.
+2. **Specify allowed tools**, MCP servers, and execution constraints.
+3. **The `task` tool** automatically handles agent lifecycle, parallel execution, and result aggregation.
-Here is a settings demo file:
-```json
-{
-    "theme": "Default",
-    "selectedAuthType": "iflow",
-    "apiKey": "your iflow key",
-    "baseUrl": "https://apis.iflow.cn/v1",
-    "modelName": "Qwen3-Coder",
-    "searchApiKey": "your iflow key"
-}
-```
+### Adding a New CLI Command
-## 🐛 Crash Debugging
+1. **Add command definition** in `packages/cli/src/commands/` (e.g., create `my-command.ts`).
+2. **Register the command** in `packages/cli/src/commands/commands.ts`.
+3. **Implement command logic** using the existing CLI services and UI components.
-If you encounter runtime crashes, you can enable crash diagnostics to collect detailed information for debugging:
+### Integrating an MCP Server
-### Enable Crash Diagnostics
+1. **Configure the server** in user or project settings (`~/.iflow/settings.json`):
+   ```json
+   "mcpServers": {
+     "my_server": {
+       "command": "npx",
+       "args": ["-y", "my-mcp-server"]
+     }
+   }
+   ```
+2. **Tools from the server** will be automatically discovered and prefixed with the server name (e.g., `my_server__tool_name`).
-```bash
-# Enable crash debugging mode
-DEBUG=true iflow
+## 🔄 Development Workflow
-# Or with additional Node.js debugging flags
-DEBUG=true node --trace-warnings --trace-uncaught node_modules/.bin/iflow
-```
+### Typical Feature Development
-### System Configuration for Core Dumps
+1. **Explore existing code** using the built‑in `$explore‑agent`:
+   ```bash
+   $explore‑agent "How is the tool system organized?"
+   ```
+2. **Create a feature branch** from `main`.
+3. **Implement changes** following the coding standards and architectural patterns.
+4. **Run tests** locally (`npm test`, `npm run test:integration:sandbox:none`).
+5. **Update documentation** if the change affects user‑facing behavior or adds new APIs.
+6. **Submit a PR** with a clear description and link to any related issues.
-**macOS:**
-```bash
-# Enable core dumps
-ulimit -c unlimited
-sudo sysctl -w kern.coredump=1
-```
+### Code Review Checklist
-**Linux:**
-```bash
-# Configure core dump pattern and enable unlimited core dumps
-echo 'core.%p.%t' | sudo tee /proc/sys/kernel/core_pattern
-ulimit -c unlimited
-```
+- [ ] TypeScript types are strict and accurate.
+- [ ] New tools have proper parameter validation and user confirmation.
+- [ ] Added tests cover positive and negative scenarios.
+- [ ] No secrets or sensitive data are committed.
+- [ ] Bundle size impact is considered for new dependencies.
+- [ ] Documentation is updated (user guides, API docs, architecture notes).
+### Performance Profiling
-### Crash Information Collection
+- Use `DEBUG=true` to capture detailed timing logs.
+- Monitor memory usage via crash reports (`crash-*.json`).
+- For suspected bottlenecks, run the CLI with Node.js inspector and profile CPU/memory in Chrome DevTools.
-When `DEBUG=true` is enabled, the system will:
+## 🧩 Contributing
-1. **Generate crash files** - Create `crash-[timestamp]-[pid].json` files containing:
-   - Complete error stack trace
-   - Memory usage information
-   - Process information (PID, uptime, Node.js version)
-   - Environment variables
-   - Platform and architecture details
+We welcome contributions! Please follow these steps:
-2. **Create core dumps** - Generate system core dumps for advanced debugging
+1. **Fork** the repository and create a feature branch.
+2. **Ensure your changes pass** the existing tests and linting rules.
+3. **Add tests** for new functionality.
+4. **Update documentation** if needed.
+5. **Submit a pull request** with a clear description of the changes.
-3. **Monitor warnings** - Log Node.js warnings and unhandled promise rejections
+### Code Style
-### Analyzing Crash Files
+- Use TypeScript with strict mode.
+- Follow the existing ESLint and Prettier configuration.
+- Write meaningful commit messages (conventional commits are appreciated but not required).
+- Keep the bundle size in mind when adding dependencies.
-The generated crash files contain structured JSON data that can help identify:
-- The exact error that caused the crash
-- Memory usage patterns before the crash
-- System environment and configuration
-- Call stack at the time of crash
+### Commit Hooks
-Share these files when reporting crash issues for faster debugging assistance.
+The project uses Husky to run lint‑staged checks on commit. This ensures code consistency before pushing.
-## GitHub Actions
-You can also use iFlow CLI in your GitHub Actions workflows with the community-maintained action: [iflow-cli-action](https://github.com/vibe-ideas/iflow-cli-action)
+## 📚 Documentation
-## Community Communication
-If you encounter problems during use, you can directly raise Issues on the GitHub page.
+- **[Architecture](./docs/architecture/overview.md)**: High‑level design and component interactions.
+- **[Tool System](./docs/architecture/tool-system-design.md)**: How tools are implemented and scheduled.
+- **[MCP Integration](./docs/architecture/mcp-integration-guide.md)**: Integrating Model Context Protocol servers.
+- **[CLI Commands](./docs/cli/commands.md)**: User‑facing command reference.
+- **[Contributing Guide](./CONTRIBUTING.md)**: Detailed contribution instructions.
-You can also scan the following WeChat group to join the community group for communication and discussion.
+## 🤝 Community
+- **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/iflow-ai/iflow-cli/issues).
+- **WeChat Group**: Join the community discussion via the QR code below.
-### WeChat Group
 ![WeChat group](./assets/iflow-wechat.jpg)
-1235
-1235
+## 📄 License
+iFlow CLI is open‑source under the [MIT License](./LICENSE).

package/bundle/iflow-cli-vscode-ide-companion-0.2.9.vsix CHANGED Viewed

Binary file