@mafdet/cli 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to `@mafdet/cli`.
+
+The version is the contract for the JSON output shapes and the exit codes.
+Being 0.x, semver still permits a break in a minor bump; the intent is not to
+use that latitude, and the promise becomes binding at 1.0.0.
+
+## 0.3.0 — 2026-08-07
+
+First published release. It contains everything through the plan's 0.3 scope,
+which is why it is numbered 0.3 rather than 0.1: a user installing it gets the
+write and shell tools, and the version should say so.
+
+### Model and account
+
+- `mafdet models list` shows what this key can actually call, joining the data
+  plane's access list with the catalogue's metadata. Metadata always comes from
+  the catalogue — the data plane reports a 1M context window for a 128K model.
+- `mafdet models show <id>` distinguishes "not allowed for this key", "not in
+  the catalogue" and "no such model", which the server's 403 cannot.
+- `mafdet account balance | usage | subscription`, needing the `account:read`
+  scope. A key without it is told about the scope, not that the key is invalid.
+- Money is integer micro-USD end to end. `--json` emits the exact strings the
+  API returned; the human view renders with integer division, and a sub-cent
+  charge stays visible rather than rounding to `$0.00`.
+
+### Calling models
+
+- `mafdet chat` streams by default, prints the answer on stdout and everything
+  else on stderr, and reports tokens plus an estimated charge computed with the
+  gateway's own arithmetic.
+- `mafdet embed` and `mafdet speech`. Output files are written atomically and
+  an existing file is never overwritten without `--force`.
+- The model's API surface is checked locally before a request is spent.
+
+### Agent
+
+- `mafdet agent "<goal>"` — read-only by default: list, search, read, and git
+  status/diff.
+- `--allow-write` adds `edit_file` and `create_file`. Every change is shown as
+  a diff and applied only after approval. A non-interactive run cannot write at
+  all, and the write tools are not even offered to the model.
+- `--allow-command "<prefix>"` adds `run_command` for exactly those commands.
+  There is no shell: the command is split into argv, so pipes, redirects,
+  chaining and substitution are refused rather than sanitised.
+- `mafdet agent` with no goal and a terminal starts an interactive session with
+  `/model`, `/permissions`, `/diff`, `/cost`, `/compact` and `/exit`.
+- Ceilings on turns, wall clock and cost stop a run with a limit status and
+  exit 7 instead of reporting success.
+
+### Diagnostics
+
+- `mafdet doctor` checks Node, both endpoints, the key, the workspace, git,
+  both API planes, the selected model, its tool-calling status and the balance.
+  Only a genuine blocker fails; a missing optional scope is a warning.
+- `mafdet config list` shows the resolved settings and which layer each came
+  from.
+
+### Safety
+
+- The key is read only from `MAFDET_API_KEY`. There is no `--api-key` flag, no
+  key in any config file, and no full key in any output — only a fingerprint.
+- A project's `.mafdet.json` may set `model`, `approvalMode` and `testCommands`.
+  Credentials and endpoints there are a hard error: cloning a repository must
+  not change where a key is sent.
+- Workspace containment is decided on real paths, so symlinks and junctions
+  cannot escape it, and a file that does not exist yet is checked against its
+  nearest existing ancestor.
+- `.env*`, private keys, `id_rsa*`, `kubeconfig`, `credentials*`, `.npmrc` and
+  the whole of `.ssh`, `.aws`, `.gnupg`, `.docker` and `.kube` are refused, with
+  no blanket override.
+- Tool output is stripped of terminal control, redacted and capped before it
+  reaches the model or the terminal.
+- Only an explicit 429 is retried. A timeout or a 5xx is never replayed,
+  because the model may already have generated — and billed for — an answer.
+
+### Known limitations
+
+- macOS and Windows are not verified. On Windows specifically, the timeout kill
+  relies on POSIX process groups, so only the direct child is terminated and a
+  grandchild can survive.
+- `/compact` truncates the conversation rather than summarising it.
+- Cancelling a stream produced no charge in testing, but that is an observation
+  rather than a guarantee: if the upstream has already finished generating, a
+  charge can still land.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mafdet AI
+
+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,173 @@
+# @mafdet/cli
+
+The official Mafdet AI command line: model calls, account queries, and a
+permissioned local agent.
+
+> **0.3.0.** 中文版见 [README.zh-CN.md](./README.zh-CN.md). The CLI never
+> advertises a command it cannot serve, so `mafdet help` always lists exactly
+> what works.
+>
+> macOS and Windows are not yet verified. On Windows the command timeout
+> relies on POSIX process groups, so only the direct child is terminated and a
+> grandchild can survive.
+
+## Requirements
+
+Node.js 20 or newer, and a Mafdet API key.
+
+## Install
+
+```bash
+npm install -g @mafdet/cli
+```
+
+Or build it from this repository:
+
+```bash
+pnpm --filter @mafdet/cli build
+cd packages/cli && npm pack          # -> mafdet-cli-0.3.0.tgz
+npm install -g ./mafdet-cli-0.3.0.tgz
+```
+
+## Quickstart
+
+```bash
+export MAFDET_API_KEY="sk-mafdet-live-..."     # never passed as a flag
+export MAFDET_MODEL="deepseek-v4-flash"
+
+mafdet doctor                    # check key, endpoints, model, balance
+mafdet models list               # what this key can actually call
+mafdet chat "Explain TypeScript decorators"
+mafdet account balance
+```
+
+### PowerShell
+
+```powershell
+$env:MAFDET_API_KEY = "sk-mafdet-live-..."
+$env:MAFDET_MODEL   = "deepseek-v4-flash"
+
+mafdet doctor
+mafdet chat "Explain TypeScript decorators"
+```
+
+Everything the CLI prints is ASCII, so output stays readable on a console
+running a non-UTF-8 code page (the Windows PowerShell 5.1 default). Piping a
+prompt works too, but PowerShell pipes UTF-16 by default — prefer passing the
+prompt as an argument, or use `--input <file>`.
+
+## Commands
+
+| Command                                                                                     | What it does                                                               |
+| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `mafdet doctor`                                                                             | One pass over key, endpoints, model, tool-calling, balance, workspace, git |
+| `mafdet models list [--surface chat\|embeddings\|speech] [--agent]`                         | Models this key can call, joined with catalogue metadata                   |
+| `mafdet models show <id>`                                                                   | One model in detail, including whether the agent may drive it              |
+| `mafdet chat [prompt] [--model] [--system <file>] [--input <file>] [--no-stream] [--quiet]` | Send a prompt; streams by default                                          |
+| `mafdet agent "<goal>" [--allow-write] [--allow-command "<prefix>"]`                        | Local agent; read-only unless told otherwise                               |
+| `mafdet agent` (no goal, needs a terminal)                                                  | Interactive session                                                        |
+| `mafdet embed [text\|<file>] --model <id> [--output <file>]`                                | Text to vector                                                             |
+| `mafdet speech [text\|<file>] --model <id> --output <file> --voice <name>`                  | Text to an audio file                                                      |
+| `mafdet account balance\|usage\|subscription`                                               | Wallet, spend and plan (needs the `account:read` scope)                    |
+| `mafdet config list`                                                                        | The resolved settings and where each came from                             |
+
+`--json` on any query command emits one complete JSON document; `--plain`
+emits tab-separated rows with no header, for `cut` and `awk`.
+
+## What the agent may do
+
+**Read-only by default**: list, search, read files, and `git status` / `git diff`.
+It cannot change anything.
+
+`--allow-write` adds `edit_file` and `create_file`, and then:
+
+- every change is shown as a diff and confirmed first, with Enter meaning no;
+- a non-interactive run cannot write at all, even with the flag - the write
+  tools are not offered to the model in the first place;
+- there is no flag that approves everything in advance.
+
+`--allow-command "<prefix>"` adds `run_command`, unprompted for exactly those
+prefixes: `pnpm test` permits `pnpm test --filter web` but never `pnpm publish`.
+**There is no shell** - the command is split into argv, so pipes, redirects,
+`;`, `&&`, backticks and `$( )` are refused with an explanation rather than
+sanitised.
+
+In a session: `/model`, `/permissions`, `/diff`, `/cost`, `/compact`, `/exit`.
+
+## Configuration
+
+Resolution order: `--model` > `MAFDET_MODEL` > project config > user config >
+default. `mafdet config list` shows which one won.
+
+| Variable             | Default                     |
+| -------------------- | --------------------------- |
+| `MAFDET_API_KEY`     | (required)                  |
+| `MAFDET_MODEL`       | none                        |
+| `MAFDET_BASE_URL`    | `https://api.mafdet.ai/v1`  |
+| `MAFDET_BACKEND_URL` | `https://backend.mafdet.ai` |
+
+User config lives at `~/.config/mafdet/config.json` (Linux),
+`~/Library/Application Support/mafdet/config.json` (macOS) or
+`%APPDATA%\mafdet\config.json` (Windows).
+
+A project may carry `.mafdet.json` with `model`, `approvalMode` and
+`testCommands` — and nothing else. Credentials and endpoints in a project file
+are rejected outright: cloning a repository must never change where your key
+is sent.
+
+## Exit codes
+
+Scripts may branch on these; a value never changes meaning once released.
+
+| Code | Meaning                                                       |
+| ---: | ------------------------------------------------------------- |
+|    0 | Success                                                       |
+|    1 | General failure (including `doctor` reporting a failed check) |
+|    2 | Bad command line or configuration                             |
+|    3 | Authentication or permission failure                          |
+|    4 | Model or API unavailable                                      |
+|    5 | Local permission denied                                       |
+|    6 | Cancelled by the user                                         |
+|    7 | Cost, time, or loop ceiling reached                           |
+
+## Compatibility
+
+If you build a script on this, here is what will and will not move.
+
+Within a major version:
+
+- an exit code never changes meaning, and a code is never reused for something
+  else;
+- a field in `--json` output keeps its name, type and meaning; new fields may
+  be added, so parse by name and ignore what you do not know;
+- `--plain` keeps its column order and stays tab-separated with no header.
+
+This is a 0.x release, so semver still permits a break in a minor bump. The
+intent is not to use that latitude, and any change will be listed in
+[CHANGELOG.md](./CHANGELOG.md); the promise becomes binding at 1.0.0.
+
+Money is always an integer count of micro-USD, sent as a string in `--json` so
+that no parser rounds it. Do not read the human-formatted dollar figure.
+
+## Output streams
+
+Results and machine-readable JSON go to stdout. Progress, warnings, summaries
+and diagnostics go to stderr, so `mafdet chat ... > answer.txt` captures the
+answer alone and `mafdet models list --json | jq` always parses.
+
+## Credentials
+
+The key is read from `MAFDET_API_KEY`. There is deliberately no `--api-key`
+flag: it would put the key into shell history and the process list. Keys are
+never written to a config file and never printed in full — only as a
+fingerprint like `sk-mafdet-live-<redacted>`.
+
+## Cost and cancellation
+
+`chat` prints tokens and an estimated charge to stderr, computed with the same
+arithmetic the gateway bills with. The wallet remains the authority.
+
+Cancelling with Ctrl+C closes the connection. In testing against production a
+cancelled stream produced no charge, but that is an observation, not a
+guarantee: if the upstream has already finished generating, a charge can still
+land. The summary after a cancel is labelled `partial:` for that reason.

package/README.zh-CN.md

@@ -0,0 +1,148 @@
+# @mafdet/cli
+
+Mafdet AI 官方命令行：模型调用、账户查询，以及一个受权限约束的本地 Agent。
+
+> **0.3.0。** 英文版见 [README.md](./README.md)。
+
+## 环境要求
+
+Node.js 20 或更高，以及一把 Mafdet API Key。
+
+## 安装
+
+```bash
+npm install -g @mafdet/cli
+```
+
+## 快速开始
+
+```bash
+export MAFDET_API_KEY="sk-mafdet-live-..."     # 只从环境变量读，没有 --api-key 参数
+export MAFDET_MODEL="deepseek-v4-flash"
+
+mafdet doctor                    # 一次查完 Key、端点、模型、余额、工作区、git
+mafdet models list               # 这把 Key 实际能调用的模型
+mafdet chat "解释一下 TypeScript 装饰器"
+mafdet account balance
+```
+
+### PowerShell
+
+```powershell
+$env:MAFDET_API_KEY = "sk-mafdet-live-..."
+$env:MAFDET_MODEL   = "deepseek-v4-flash"
+
+mafdet doctor
+```
+
+所有用户可见输出都是纯 ASCII，因此在非 UTF-8 代码页的控制台（Windows PowerShell 5.1
+的默认状态，中文系统为 cp936）也不会变成乱码。管道传入 prompt 也可以，但 PowerShell
+默认按 UTF-16 走管道——建议直接把 prompt 作为参数，或用 `--input <文件>`。
+
+⚠️ **macOS 与 Windows 尚未验收**。Windows 上有一个已知差异：命令超时终止依赖 POSIX 的
+进程组语义，Windows 只会终止直接子进程，孙子进程可能存活。
+
+## 命令
+
+| 命令                                                                                        | 作用                                                                |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `mafdet doctor`                                                                             | 一次检查 Node、两个端点、Key、工作区、git、模型与工具调用能力、余额 |
+| `mafdet models list [--surface chat\|embeddings\|speech] [--agent]`                         | 这把 Key 能调用的模型，并附上目录元数据                             |
+| `mafdet models show <id>`                                                                   | 单个模型详情，含 Agent 是否可以驱动它                               |
+| `mafdet chat [提示词] [--model] [--system <文件>] [--input <文件>] [--no-stream] [--quiet]` | 发一次对话，默认流式                                                |
+| `mafdet embed [文本\|<文件>] --model <id> [--output <文件>]`                                | 文本转向量                                                          |
+| `mafdet speech [文本\|<文件>] --model <id> --output <文件> --voice <音色>`                  | 文本转音频                                                          |
+| `mafdet agent "<目标>" [--allow-write] [--allow-command "<前缀>"]`                          | 本地 Agent，默认只读                                                |
+| `mafdet agent`（不带目标，需终端）                                                          | 交互会话                                                            |
+| `mafdet account balance\|usage\|subscription`                                               | 钱包、用量、套餐（需 `account:read` scope）                         |
+| `mafdet config list`                                                                        | 当前生效的配置及其来源                                              |
+
+查询类命令都支持 `--json`（输出一份完整 JSON 文档）与 `--plain`（无表头的 TSV，方便
+`cut`、`awk` 处理）。
+
+## Agent 的权限模型
+
+**默认只读**：可以列目录、搜索、读文件、看 git status/diff，**不能**改任何东西。
+
+`--allow-write` 才会加上 `edit_file` 与 `create_file`，并且：
+
+- 每次改动都**先展示 diff 再询问**，回车即拒绝；
+- **非交互环境（无终端）一律不给写权限**，即使显式传了 `--allow-write`——此时写工具
+  根本不会提供给模型；
+- **没有任何"全部同意"的开关**（无 `--yes`、无 `--force`、无 `--allow-secrets`）。
+
+`--allow-command "<前缀>"` 才会加上 `run_command`，且只对**这些命令前缀**免提示。
+`pnpm test` 放行 `pnpm test --filter web`，但不放行 `pnpm publish`。
+**没有 shell**：命令被切成 argv 直接执行，所以管道、重定向、`;`、`&&`、反引号、`$( )`
+一律被拒绝并说明原因，而不是尝试"消毒"。
+
+会话内命令：`/model`、`/permissions`、`/diff`、`/cost`、`/compact`、`/exit`。
+
+## 配置
+
+优先级：`--model` > `MAFDET_MODEL` > 项目配置 > 用户配置 > 默认值。
+`mafdet config list` 会告诉你最终是哪一层生效的。
+
+| 环境变量             | 默认值                      |
+| -------------------- | --------------------------- |
+| `MAFDET_API_KEY`     | （必填）                    |
+| `MAFDET_MODEL`       | 无                          |
+| `MAFDET_BASE_URL`    | `https://api.mafdet.ai/v1`  |
+| `MAFDET_BACKEND_URL` | `https://backend.mafdet.ai` |
+
+用户配置位置：Linux `~/.config/mafdet/config.json`、macOS
+`~/Library/Application Support/mafdet/config.json`、Windows `%APPDATA%\mafdet\config.json`。
+
+项目可以放一个 `.mafdet.json`，但**只允许** `model`、`approvalMode`、`testCommands` 三项。
+里面出现凭据或端点会**直接报错**：克隆一个仓库绝不该改变你的 Key 发往哪里。
+
+## 退出码
+
+脚本可以据此分支；一旦发布，某个值的含义就不再改变。
+
+|  码 | 含义                                   |
+| --: | -------------------------------------- |
+|   0 | 成功                                   |
+|   1 | 一般失败（含 `doctor` 有检查项未通过） |
+|   2 | 命令行或配置错误                       |
+|   3 | 认证或权限失败                         |
+|   4 | 模型或 API 不可用                      |
+|   5 | 本地权限被拒绝                         |
+|   6 | 用户取消                               |
+|   7 | 达到费用、时间或轮次上限               |
+
+## 兼容性承诺
+
+如果你要在脚本里依赖它，这里说明什么会变、什么不会。
+
+同一大版本内：
+
+- **退出码的含义不变**，某个码也不会被挪作他用；
+- `--json` 里的字段**保持名称、类型与含义**；只会新增字段——所以请按字段名解析，
+  忽略不认识的键；
+- `--plain` 的**列顺序固定**，始终是无表头的 TSV。
+
+这是 0.x 版本，按 semver 次版本号仍**允许**破坏性变更。我们不打算动用这个余地，
+任何调整都会写进 [CHANGELOG.md](./CHANGELOG.md)；**1.0.0 起正式生效**。
+
+金额一律是**整数微美元**，`--json` 里以字符串给出，避免任何解析器把它变成浮点。
+请不要去解析给人看的美元数字。
+
+## 输出约定
+
+结果与机器可读的 JSON 走 **stdout**；进度、警告、摘要、审批提示走 **stderr**。
+所以 `mafdet chat ... > answer.txt` 只会拿到答案本身，而
+`mafdet models list --json | jq` 永远能解析。
+
+## 凭据
+
+Key 只从 `MAFDET_API_KEY` 读取。**刻意不提供 `--api-key` 参数**——那会把 Key 写进
+shell 历史和进程列表。Key 不会被写入任何配置文件，也不会完整出现在任何输出里，
+只以 `sk-mafdet-live-<redacted>` 这样的指纹形式展示。
+
+## 费用与取消
+
+`chat` 会在 stderr 打印 token 数与预估费用，算法与网关计费一致，但**以钱包为准**。
+
+Ctrl+C 会关闭连接。实测中被取消的流式请求没有产生费用，但这是一次观察结果、**不是保证**：
+如果上游已经生成完毕，仍可能产生扣费。因此取消后的摘要标注为 `partial:`。

package/dist/agent/approvals.d.ts

@@ -0,0 +1,38 @@
+export interface ApprovalRequest {
+    /** What the tool wants to do, e.g. "edit src/app.ts". */
+    summary: string;
+    /** The diff or command the user is being asked to approve. */
+    preview: string;
+}
+export interface Approver {
+    approve(request: ApprovalRequest): Promise<boolean>;
+}
+/**
+ * `read-only`, and every non-interactive run that has not been given explicit
+ * permission. Plan §8.1: a CI job must not acquire write access by accident,
+ * and there is no global `--yes` that could hand it over in one flag.
+ */
+export declare const denyAll: Approver;
+/** `auto-edit`: the user pre-approved changes inside the workspace. */
+export declare const approveAll: Approver;
+/**
+ * `suggest`, the default: show the diff, ask, default to no.
+ *
+ * The prompt goes to stderr so it never lands in redirected output, and a bare
+ * Enter means no — the safe answer must be the one you get by not thinking.
+ */
+export declare function interactiveApprover(io: {
+    stderr: (text: string) => void;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}): Approver;
+export type ApprovalMode = "read-only" | "suggest" | "auto-edit";
+/**
+ * Pick the approver for a mode, refusing to be interactive when there is no
+ * terminal: prompting a pipe would either hang or read the next line of data
+ * as an answer.
+ */
+export declare function approverFor(mode: ApprovalMode, io: {
+    stderr: (text: string) => void;
+}, isInteractive?: boolean): Approver;
+//# sourceMappingURL=approvals.d.ts.map

package/dist/agent/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/agent/approvals.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,QAIrB,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,UAAU,EAAE,QAIxB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE;IACtC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CAChC,GAAG,QAAQ,CAgBX;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,YAAY,EAClB,EAAE,EAAE;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACtC,aAAa,GAAE,OAAsC,GACpD,QAAQ,CAIV"}

package/dist/agent/approvals.js

@@ -0,0 +1,53 @@
+import { createInterface } from "node:readline/promises";
+/**
+ * `read-only`, and every non-interactive run that has not been given explicit
+ * permission. Plan §8.1: a CI job must not acquire write access by accident,
+ * and there is no global `--yes` that could hand it over in one flag.
+ */
+export const denyAll = {
+    async approve() {
+        return false;
+    },
+};
+/** `auto-edit`: the user pre-approved changes inside the workspace. */
+export const approveAll = {
+    async approve() {
+        return true;
+    },
+};
+/**
+ * `suggest`, the default: show the diff, ask, default to no.
+ *
+ * The prompt goes to stderr so it never lands in redirected output, and a bare
+ * Enter means no — the safe answer must be the one you get by not thinking.
+ */
+export function interactiveApprover(io) {
+    return {
+        async approve(request) {
+            io.stderr(`\n${request.summary}\n${request.preview}\n`);
+            const rl = createInterface({
+                input: io.input ?? process.stdin,
+                output: io.output ?? process.stderr,
+            });
+            try {
+                const answer = await rl.question("apply this change? [y/N] ");
+                return /^y(es)?$/i.test(answer.trim());
+            }
+            finally {
+                rl.close();
+            }
+        },
+    };
+}
+/**
+ * Pick the approver for a mode, refusing to be interactive when there is no
+ * terminal: prompting a pipe would either hang or read the next line of data
+ * as an answer.
+ */
+export function approverFor(mode, io, isInteractive = process.stdin.isTTY === true) {
+    if (mode === "read-only")
+        return denyAll;
+    if (mode === "auto-edit")
+        return approveAll;
+    return isInteractive ? interactiveApprover(io) : denyAll;
+}

package/dist/agent/command-policy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What a model is allowed to ask the machine to run.
+ *
+ * The central decision: there is no shell. A command is tokenised into argv
+ * and handed to execFile, so `;`, `&&`, backticks, `$(...)`, pipes and
+ * redirects have no meaning to anything downstream — there is nothing to
+ * inject into. Rather than accept them and try to sanitise, the policy refuses
+ * them and says why, because a sanitiser is a thing that can be wrong once.
+ */
+export interface CommandVerdict {
+    ok: boolean;
+    /** Present when ok: the argv to execute, already split. */
+    argv?: string[];
+    /**
+     * True when an --allow-command entry matched, which is the only way a
+     * command runs without a prompt (plan §8.1: CI declares its capabilities
+     * up front rather than being asked).
+     */
+    preApproved?: boolean;
+    reason?: string;
+}
+/**
+ * Split a command line the way a shell would for simple cases: whitespace
+ * separates, quotes group. Anything more exotic is refused above, so this
+ * never has to be clever.
+ */
+export declare function tokenize(command: string): string[];
+/**
+ * @param allowlist entries from `--allow-command`. An entry matches when it is
+ *   the whole command or a leading prefix of its tokens, so "pnpm test"
+ *   permits "pnpm test --filter x" but never "pnpm publish".
+ */
+export declare function assessCommand(command: string, allowlist?: readonly string[]): CommandVerdict;
+/** Terminal control sequences, stripped before any output is shown or sent. */
+export declare function stripAnsi(text: string): string;
+//# sourceMappingURL=command-policy.d.ts.map

package/dist/agent/command-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-policy.d.ts","sourceRoot":"","sources":["../../src/agent/command-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BlD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAAO,GAChC,cAAc,CAwChB;AAmBD,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAe9C"}