turboflux 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 孟圣博
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+<p align="center">
+  <img src="docs/assets/turboflux-mark.svg" alt="TurboFlux" width="96" />
+</p>
+
+<h1 align="center">TurboFlux</h1>
+
+<p align="center">A local TUI coding agent for real workspaces.</p>
+
+<p align="center">
+  <img alt="Node.js 20+" src="https://img.shields.io/badge/Node.js-20%2B-20242a?logo=node.js" />
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.x-20242a?logo=typescript" />
+  <img alt="License" src="https://img.shields.io/badge/License-MIT-20242a" />
+</p>
+
+TurboFlux is a terminal user interface (TUI) for AI-assisted development. It takes
+a project directory and a task, then searches code, edits files, runs commands,
+and reports progress and diffs in an Ink-based terminal UI.
+
+<p align="center">
+  <img src="turboflux-tui.png" alt="TurboFlux terminal interface" width="960" />
+</p>
+
+> [!NOTE]
+> TurboFlux is under active development. Commands, configuration, and UI details may change.
+
+## Quick start
+
+Requires Node.js 20 or newer.
+
+```bash
+npm install -g github:MengShengbo/TurboFluxCli
+turboflux setup
+cd your-project
+turboflux
+```
+
+The setup wizard configures a model provider. Then enter a task directly, for example:
+
+```text
+Inspect the login flow, fix session re-authentication, and run the relevant tests.
+```
+
+Install from the published repository instead:
+
+```bash
+# macOS, Linux, or Git Bash
+curl -fsSL https://raw.githubusercontent.com/MengShengbo/TurboFluxCli/main/install.sh | bash
+
+# Windows PowerShell
+irm https://raw.githubusercontent.com/MengShengbo/TurboFluxCli/main/install.ps1 | iex
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/MengShengbo/TurboFluxCli.git
+cd TurboFluxCli
+npm ci
+npm install -g .
+```
+
+## Features
+
+- Search and read code, edit files, and run foreground or background commands.
+- Show file- and hunk-level unified diffs with tool execution status.
+- Persist conversations with history restore, context compaction, and workspace memory.
+- Inspect, commit, restore, and revert agent changes through isolated Git operations.
+- Connect to OpenAI, Anthropic, DeepSeek, Kimi, GLM, OpenRouter, and custom OpenAI-compatible APIs.
+- Extend the workspace with Skills, MCP servers, and custom subagents.
+
+## Configuration
+
+```bash
+turboflux setup api          # Configure an API connection
+turboflux setup language     # Configure UI and output language
+turboflux setup persona      # Configure response style
+turboflux setup approval     # Configure tool approval policy
+turboflux setup show         # Show the active configuration
+```
+
+Normal settings are stored in `~/.turboflux/config.json`; API credentials are
+stored separately in `~/.turboflux/credentials.json`.
+
+Run a project or a single task:
+
+```bash
+turboflux /path/to/project
+turboflux /path/to/project --command "Inspect the login flow and fix the issue"
+```
+
+## Modes and approvals
+
+| Mode | Behavior |
+| --- | --- |
+| `vibe` | Default mode; search, edit, and validate the project. |
+| `plan` | Read-only analysis and planning. |
+
+Use `/vibe` and `/plan` to switch modes, and `/effort` to adjust the active model's reasoning effort.
+
+| Approval policy | Behavior |
+| --- | --- |
+| `ask` | Ask before writing files or running commands. |
+| `agent` | Continue low-risk actions automatically and ask when risk is detected. |
+| `full` | Hide approval prompts and enable full workspace, command, and network access. |
+
+Override the configured policy for one run with `--approval-policy <policy>`.
+
+## Common commands
+
+| Command | Purpose |
+| --- | --- |
+| `/help` | Show all commands. |
+| `/model` | Select or add a model. |
+| `/plan`, `/vibe` | Switch work mode. |
+| `/effort` | Adjust reasoning effort. |
+| `/approval` | Change the approval policy. |
+| `/context`, `/compact` | Inspect or compact context. |
+| `/resume`, `/new` | Restore or start a conversation. |
+| `/mcp`, `/skills` | Inspect loaded extensions. |
+| `/git [on\|off\|refresh]` | Inspect or refresh Git integration. |
+
+Press `Esc` twice in the input field to restore the previous message for editing.
+When a provider returns reasoning content, press `Ctrl+O` to expand or collapse it.
+
+## Git integration
+
+Git integration is enabled by default. Automatic commits use an isolated index,
+so existing staged changes stay untouched and nothing is pushed automatically.
+Structured Git tools do not force-push, hard-reset, or clean the working tree.
+
+## Workspace rules and extensions
+
+Put project rules in `TURBOFLUX.md`. TurboFlux also reads `CLAUDE.md`, `AGENTS.md`,
+`.cursorrules`, and `.cursor/rules/` when present.
+
+MCP is disabled by default. Select a server from the command line:
+
+```bash
+turboflux . --mcp all
+turboflux . --mcp server-name
+```
+
+The current MCP transport is stdio. See the [documentation index](docs/README.md)
+and the [provider/API compatibility guide](docs/provider-api-compatibility.md).
+
+## Terminal features
+
+On Windows, `Ctrl+V` can paste a clipboard image, or a message can contain a
+local image path. PNG, JPEG, WebP, GIF, and BMP are supported up to 5 MB per image;
+the selected model must support vision input.
+
+TurboFlux normally renders an opaque background. Windows Terminal transparency,
+Acrylic, and background images are detected automatically. Override detection with
+`turboflux . --transparent`, `--opaque`, or `TURBOFLUX_TRANSPARENT`.
+
+## Development
+
+```bash
+npm ci
+npm run dev:once -- .
+npm test
+npm run type-check
+npm run build
+```
+
+Start with the [documentation index](docs/README.md):
+
+- [System overview](docs/architecture/system-overview.md)
+- [Local development](docs/guides/development.md)
+- [Testing strategy](docs/guides/testing.md)
+- [Troubleshooting](docs/operations/troubleshooting.md)
+- [Provider/API compatibility](docs/provider-api-compatibility.md)
+- [Contribution guide](CONTRIBUTING.md)
+
+## License
+
+MIT

package/bin/turboflux.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const root = join(__dirname, '..')
+const entry = join(root, 'dist', 'cli', 'index.js')
+const require = createRequire(import.meta.url)
+const tsxLoader = pathToFileURL(require.resolve('tsx')).href
+
+// Use tsx's resolver so extensionless ESM emitted by tsc can run under Node.
+const { spawnSync } = await import('node:child_process')
+const systemCaArgs = process.allowedNodeEnvironmentFlags.has('--use-system-ca') ? ['--use-system-ca'] : []
+const args = [...systemCaArgs, '--import', tsxLoader, entry, ...process.argv.slice(2)]
+
+const result = spawnSync(process.execPath, args, {
+  stdio: 'inherit',
+  cwd: process.cwd(),
+  env: { ...process.env, NODE_PATH: join(root, 'node_modules') },
+})
+
+if (result.error) {
+  console.error(result.error.message)
+  process.exit(1)
+}
+
+process.exit(result.status ?? 1)

package/dist/cli/brand.d.ts

@@ -0,0 +1,7 @@
+export declare const TURBOFLUX_WORDMARK_LINES: readonly ["  ______           __          ________         ", " /_  __/_  _______/ /_  ____  / ____/ /_  ___  __", "  / / / / / / ___/ __ \\/ __ \\/ /_  / / / / / |/_/", " / / / /_/ / /  / /_/ / /_/ / __/ / /_/ />  <  ", "/_/  \\__,_/_/  /_.___/\\____/_/ /_/\\__,_/_/|_|  "];
+export declare const TURBOFLUX_COMPACT_MARK = "TurboFlux";
+export declare const TURBOFLUX_VERSION = "1.0.0";
+export declare function centerText(text: string, width: number): string;
+export declare function centerTextBlock(lines: readonly string[], width: number): string[];
+export declare function revealTextBlock(lines: readonly string[], progress: number): string[];
+export declare function shouldUseCompactWordmark(columns: number, rows: number): boolean;

package/dist/cli/brand.js

@@ -0,0 +1,33 @@
+import stringWidth from 'string-width';
+export const TURBOFLUX_WORDMARK_LINES = [
+    '  ______           __          ________         ',
+    ' /_  __/_  _______/ /_  ____  / ____/ /_  ___  __',
+    '  / / / / / / ___/ __ \\/ __ \\/ /_  / / / / / |/_/',
+    ' / / / /_/ / /  / /_/ / /_/ / __/ / /_/ />  <  ',
+    '/_/  \\__,_/_/  /_.___/\\____/_/ /_/\\__,_/_/|_|  ',
+];
+export const TURBOFLUX_COMPACT_MARK = 'TurboFlux';
+export const TURBOFLUX_VERSION = '1.0.0';
+export function centerText(text, width) {
+    const padding = Math.max(0, Math.floor((width - stringWidth(text)) / 2));
+    return `${' '.repeat(padding)}${text}`;
+}
+export function centerTextBlock(lines, width) {
+    const blockWidth = lines.reduce((maximum, line) => Math.max(maximum, stringWidth(line)), 0);
+    const padding = Math.max(0, Math.floor((width - blockWidth) / 2));
+    const prefix = ' '.repeat(padding);
+    return lines.map(line => `${prefix}${line}`);
+}
+export function revealTextBlock(lines, progress) {
+    const blockWidth = lines.reduce((maximum, line) => Math.max(maximum, stringWidth(line)), 0);
+    const normalizedProgress = Math.max(0, Math.min(1, progress));
+    const visibleWidth = Math.round(blockWidth * normalizedProgress);
+    return lines.map(line => {
+        const visible = line.slice(0, visibleWidth);
+        return visible.padEnd(line.length, ' ');
+    });
+}
+export function shouldUseCompactWordmark(columns, rows) {
+    return columns < 88 || rows < 26;
+}
+//# sourceMappingURL=brand.js.map

package/dist/cli/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../../src/cli/brand.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,kDAAkD;IAClD,mDAAmD;IACnD,qDAAqD;IACrD,iDAAiD;IACjD,oDAAoD;CAC5C,CAAA;AAEV,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAA;AACjD,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAA;AAExC,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAa;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACxE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAA;AACxC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAwB,EAAE,KAAa;IACrE,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAC3F,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACjE,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAClC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC,CAAA;AAC9C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAwB,EAAE,QAAgB;IACxE,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAC3F,MAAM,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC7D,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,kBAAkB,CAAC,CAAA;IAEhE,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QACtB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAA;QAC3C,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACzC,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAe,EAAE,IAAY;IACpE,OAAO,OAAO,GAAG,EAAE,IAAI,IAAI,GAAG,EAAE,CAAA;AAClC,CAAC"}

package/dist/cli/commands/index.d.ts

@@ -0,0 +1,4 @@
+import { commandRegistry } from './registry';
+import { type Translator } from '../i18n/index';
+export declare function ensureProjectInstructions(wsPath: string, t?: Translator): string | null;
+export { commandRegistry };