|
| 1 | +# AINXT.md |
| 2 | + |
| 3 | +This file provides guidance to AiNxt CLI agents when working with code in this |
| 4 | +repository. |
| 5 | + |
| 6 | +> **It is not loaded automatically under this name.** The agent reads project |
| 7 | +> rules from `Agents.md`, `AGENTS.md`, `AGENT.md`, `Claude.md`, `CLAUDE.md` or |
| 8 | +> `CLAUDE.local.md` — `AINXT.md` is not in that list and appears nowhere in the |
| 9 | +> source. To have these rules picked up automatically, copy or symlink this file |
| 10 | +> to `AGENTS.md`. See |
| 11 | +> [Project rules](crates/codegen/ainxt-pager/docs/user-guide/12-project-rules.md) |
| 12 | +> for the full resolution order. |
| 13 | +
|
| 14 | +> **Note:** This file was rewritten on 2026-07-23 (OSS-004). The previous version |
| 15 | +> described a Bun + TypeScript project that does not exist. The actual codebase is |
| 16 | +> described below. |
| 17 | +
|
| 18 | +--- |
| 19 | + |
| 20 | +## Project Overview |
| 21 | + |
| 22 | +**AiNxt CLI** — a terminal-native AI coding assistant and agentic engineering platform. |
| 23 | +Delivered as a single self-contained binary (`ainxt`). The product is a fork of |
| 24 | +SpaceXAI's "Grok Build" CLI (Apache-2.0), rebranded and extended for the AiNxt platform. |
| 25 | + |
| 26 | +| Fact | Value | |
| 27 | +|------|-------| |
| 28 | +| Language | **Rust** (edition 2024) | |
| 29 | +| Build system | **Cargo** workspace | |
| 30 | +| Crate count | ~80 first-party crates | |
| 31 | +| Source files | ~2,172 `.rs` files | |
| 32 | +| Dependencies | ~1,269 (via `Cargo.lock`) | |
| 33 | +| License | Apache-2.0 | |
| 34 | +| Binary name | `ainxt` | |
| 35 | +| Config dir | `~/.ainxt/` | |
| 36 | +| Env prefix | `AINXT_*` | |
| 37 | + |
| 38 | +There is **no** `src-v2/` directory, no TypeScript, no Bun, no React/Ink, and no |
| 39 | +`package.json` in this repository. |
| 40 | + |
| 41 | +--- |
| 42 | + |
| 43 | +## Workspace Layout |
| 44 | + |
| 45 | +``` |
| 46 | +ainxt-cli/ |
| 47 | +├── Cargo.toml # workspace root (resolver = "2") |
| 48 | +├── Cargo.lock |
| 49 | +├── deny.toml # cargo-deny license + advisory policy |
| 50 | +├── rust-toolchain.toml # pinned Rust toolchain (rustup auto-installs) |
| 51 | +├── bin/protoc # DotSlash descriptor — downloads protoc on demand |
| 52 | +├── crates/ |
| 53 | +│ ├── build/ |
| 54 | +│ │ └── ainxt-proto-build/ # build script: compiles .proto files |
| 55 | +│ ├── codegen/ # main product crates (see §Crate Map) |
| 56 | +│ └── common/ # shared utility crates |
| 57 | +├── third_party/ # vendored crates (mermaid-to-svg, dagre_rust, etc.) |
| 58 | +├── prod/ # production-only crates (e.g. cli-chat-proxy-types) |
| 59 | +├── assets/ # brand assets (logo, etc.) |
| 60 | +├── scripts/ # release scripts (build-release.sh, etc.) |
| 61 | +└── NOTICE, LICENSE, THIRD-PARTY-NOTICES, deny.toml |
| 62 | +``` |
| 63 | + |
| 64 | +--- |
| 65 | + |
| 66 | +## Key Crates (codegen/) |
| 67 | + |
| 68 | +| Crate | Role | |
| 69 | +|-------|------| |
| 70 | +| `ainxt-pager-bin` | **Main binary entry point** — builds the `ainxt` executable | |
| 71 | +| `ainxt-pager` | TUI shell: Ratatui-based terminal UI, REPL, rendering pipeline | |
| 72 | +| `ainxt-agent` | Agent builder, definition parsing, system prompt assembly | |
| 73 | +| `ainxt-agent-lifecycle` | Agent run lifecycle, turn management, compaction | |
| 74 | +| `ainxt-sampler` | HTTP sampling client — streams from the gateway (SSE/JSON) | |
| 75 | +| `ainxt-config` / `ainxt-config-types` | 8-source settings cascade, validation | |
| 76 | +| `ainxt-env` | Centralized default endpoint constants (all env-overridable) | |
| 77 | +| `ainxt-auth` | Bearer-token login/logout, credential storage (`~/.ainxt/credentials.json`) | |
| 78 | +| `ainxt-hooks` | Lifecycle hooks (PreToolUse, PostToolUse, SessionStart, …) | |
| 79 | +| `ainxt-tools` | Built-in tool implementations (file I/O, shell, git, web, …) | |
| 80 | +| `ainxt-mcp` | Model Context Protocol client + server (stdio/SSE/HTTP/WS) | |
| 81 | +| `ainxt-secrets` | Secret sanitizer — redacts keys/tokens from logs and output | |
| 82 | +| `ainxt-telemetry` | Telemetry (disabled by default; no hardcoded token) | |
| 83 | +| `ainxt-plugin-marketplace` | Plugin discovery, index, and install pipeline | |
| 84 | +| `ainxt-memory` | Per-project workspace memory store | |
| 85 | +| `ainxt-markdown` / `ainxt-markdown-core` | Markdown rendering for the TUI | |
| 86 | +| `ainxt-mermaid` | Mermaid diagram rendering (SVG via vendored JS) | |
| 87 | +| `ainxt-sandbox` | Sandboxed shell execution | |
| 88 | +| `ainxt-update` | Auto-update check and download | |
| 89 | +| `ainxt-workspace` / `ainxt-workspace-types` | Workspace detection and metadata | |
| 90 | +| `ainxt-http` | Shared HTTP client (reqwest wrapper, TLS policy, SSRF defense) | |
| 91 | +| `ainxt-gix-status` | Git status via `gix` (pure-Rust libgit2 alternative) | |
| 92 | +| `ainxt-codebase-graph` | Codebase graph construction for semantic search | |
| 93 | +| `ainxt-crash-handler` | Crash reporting and recovery | |
| 94 | +| `ainxt-tracing-macros` | Tracing/logging macros | |
| 95 | +| `ptyctl` / `ptyctl-cli` | PTY control for shell sessions | |
| 96 | + |
| 97 | +--- |
| 98 | + |
| 99 | +## Build Commands |
| 100 | + |
| 101 | +```sh |
| 102 | +# Fast validation (no codegen, no link) |
| 103 | +cargo check -p ainxt-pager-bin |
| 104 | + |
| 105 | +# Debug build |
| 106 | +cargo build -p ainxt-pager-bin --bin ainxt |
| 107 | + |
| 108 | +# Release binary → target/release-dist/ainxt |
| 109 | +cargo build --profile release-dist -p ainxt-pager-bin --bin ainxt |
| 110 | + |
| 111 | +# Run directly |
| 112 | +./target/release-dist/ainxt |
| 113 | +``` |
| 114 | + |
| 115 | +> The Rust toolchain is pinned in `rust-toolchain.toml`. `rustup` installs it |
| 116 | +> automatically on first build. `protoc` is provided via the DotSlash descriptor |
| 117 | +> at `bin/protoc` — install `dotslash` and put it on `PATH` before building. |
| 118 | +
|
| 119 | +--- |
| 120 | + |
| 121 | +## Test Commands |
| 122 | + |
| 123 | +```sh |
| 124 | +# Run all tests |
| 125 | +cargo test --workspace |
| 126 | + |
| 127 | +# Run tests for a specific crate |
| 128 | +cargo test -p ainxt-sampler |
| 129 | + |
| 130 | +# Run a specific test |
| 131 | +cargo test -p ainxt-secrets -- sanitizer |
| 132 | + |
| 133 | +# Clippy (lint) |
| 134 | +cargo clippy --workspace --all-targets -- -D warnings |
| 135 | + |
| 136 | +# Format check |
| 137 | +cargo fmt --check |
| 138 | + |
| 139 | +# Format (auto-fix) |
| 140 | +cargo fmt |
| 141 | +``` |
| 142 | + |
| 143 | +--- |
| 144 | + |
| 145 | +## Supply-Chain Gates (run before any release) |
| 146 | + |
| 147 | +```sh |
| 148 | +# Install tools (once) |
| 149 | +cargo install cargo-deny |
| 150 | +cargo install cargo-audit |
| 151 | + |
| 152 | +# License compliance (policy in deny.toml) |
| 153 | +cargo deny check licenses |
| 154 | + |
| 155 | +# Security advisories (checks Cargo.lock vs RustSec DB) |
| 156 | +cargo audit |
| 157 | + |
| 158 | +# All deny checks at once |
| 159 | +cargo deny check |
| 160 | +``` |
| 161 | + |
| 162 | +See `RUN.md §8` for full details and policy explanation. |
| 163 | + |
| 164 | +--- |
| 165 | + |
| 166 | +## Key Environment Variables |
| 167 | + |
| 168 | +| Variable | Effect | |
| 169 | +|----------|--------| |
| 170 | +| `AINXT_GATEWAY_URL` | Override the backend gateway URL | |
| 171 | +| `AINXT_CONFIG_DIR` | Override config dir (default `~/.ainxt`) | |
| 172 | +| `AINXT_ALLOW_INSECURE` | Set to `1` to allow plain HTTP (testing only) | |
| 173 | +| `AINXT_TELEMETRY_ENABLED` | Set to `1` to opt in to telemetry (off by default) | |
| 174 | +| `AINXT_MARKETPLACE_SOURCE_URL` | Override the plugin marketplace Git URL | |
| 175 | +| `AINXT_MARKETPLACE_ORG` | Override the marketplace org slug | |
| 176 | +| `RUST_LOG` | Tracing filter, e.g. `ainxt_sampler=debug,ainxt_agent=info` | |
| 177 | + |
| 178 | +All default production endpoints are defined in `crates/codegen/ainxt-env/src/lib.rs` |
| 179 | +and are overridable via environment variables — no endpoint is hardcoded without an |
| 180 | +escape hatch. |
| 181 | + |
| 182 | +--- |
| 183 | + |
| 184 | +## Important Conventions |
| 185 | + |
| 186 | +- **No TypeScript, no Bun, no Node.** This is a pure Rust project. |
| 187 | +- **Workspace dependencies** are declared in the root `Cargo.toml` `[workspace.dependencies]` |
| 188 | + section and referenced with `{ workspace = true }` in crate `Cargo.toml` files. |
| 189 | +- **Secret sanitizer** (`ainxt-secrets/src/sanitizer.rs`) must be applied to any output |
| 190 | + that could contain user credentials. Never log raw API keys or tokens. |
| 191 | +- **TLS is secure by default.** Plain HTTP is refused unless `AINXT_ALLOW_INSECURE=1`. |
| 192 | +- **Telemetry is off by default.** Do not add always-on telemetry calls. |
| 193 | +- **SSRF defense** is active in `ainxt-hooks/src/runner/http.rs` — RFC-1918 private IP |
| 194 | + ranges are blocked for outbound hook HTTP calls. |
| 195 | +- **License:** all first-party crates are `Apache-2.0`. Do not add |
| 196 | + GPL/AGPL/SSPL dependencies without legal review. MPL-2.0 requires sign-off (see `deny.toml`). |
| 197 | +- **Fork attribution:** `NOTICE` and `THIRD-PARTY-NOTICES` must be kept up to date. |
| 198 | + Do not remove the SpaceXAI/Grok Build attribution. |
| 199 | + |
| 200 | +--- |
| 201 | + |
| 202 | +## Key File Locations |
| 203 | + |
| 204 | +| Area | Path | |
| 205 | +|------|------| |
| 206 | +| Main binary entry | `crates/codegen/ainxt-pager-bin/src/main.rs` | |
| 207 | +| Default endpoints (env-overridable) | `crates/codegen/ainxt-env/src/lib.rs` | |
| 208 | +| Marketplace slug | `crates/codegen/ainxt-plugin-marketplace/src/lib.rs` | |
| 209 | +| Secret sanitizer | `crates/codegen/ainxt-secrets/src/sanitizer.rs` | |
| 210 | +| Telemetry config | `crates/codegen/ainxt-telemetry/src/config.rs` | |
| 211 | +| SSRF blocklist | `crates/codegen/ainxt-hooks/src/runner/http.rs` | |
| 212 | +| Auth / credentials | `crates/codegen/ainxt-auth/src/` | |
| 213 | +| License gate policy | `deny.toml` | |
| 214 | +| Build + run guide | `RUN.md` | |
| 215 | + |
0 commit comments