# `deft` 二进制
`deft` 二进制是 TUI 之外一切功能的唯一入口：运行脚本、REPL、测试、格式化以及包管理器。它编译为单个自包含的可执行文件，无外部依赖。
## 子命令
```
deft <script>.dft Run a script file
deft repl Start the REPL
deft test [files...] Run tests
deft fmt [files...] Format source files
deft pkg <subcommand> Package manager
deft sandbox <subcmd> Manage landlock sandbox paths
deft init [name] Scaffold a new Deft project
deft --version
deft --help
````
## 运行脚本
```
$ deft hello.dft Alice
Hello, Alice!
````
带上 shebang 后，脚本可直接执行：
#!/usr/bin/env deft set a [os/args] echo "Hello, $(a(1))!"
```
$ chmod +x hello.dft
$ ./hello.dft Alice
Hello, Alice!
````
### 命令行参数
脚本名之后的参数可通过 `os/args` 获取：
def argv [os/args] def script-name $argv(first) def user-args $argv(rest)
### 退出码
`os/exit $n` 以状态码 `$n` 退出。默认为 0（成功）。
if not([fs/exists? "config.json"]) { echo "missing config" os/exit 1 }
## 测试运行器
```
$ deft test # all tests under ./test/
$ deft test test/test_sqlite.dft # one file
$ deft test test/test_refs.dft test/test_lazy_seq.dft
````
测试以 `defsuite` / `deftest` 块组织（见测试）。匹配 `test_*.dft` 的文件会被自动发现。运行器打印每个测试的通过/失败及断言消息，然后给出汇总。
## 格式化工具
```
$ deft fmt myfile.dft # in-place
$ deft fmt src/ # whole directory
$ deft fmt --check myfile.dft # exit 1 if not formatted
````
统一空白、缩进与结尾换行。适用于 pre-commit 钩子和 CI。
## 包管理器
```
$ deft pkg install owner/name
$ deft pkg install owner/name@1.2.0
$ deft pkg uninstall owner/name
$ deft pkg list
$ deft pkg available
$ deft pkg info owner/name
$ deft pkg registry <url> # switch registry
$ deft pkg registry # show current
````
底层 `pkg/*` 标准库函数与包清单格式参见包。
## 沙箱
`deft sandbox` 管理存储在 `.deft/prelude.dft` 中 `:sandbox {:readonly @[...] :writable @[...]}` 下的 Landlock 路径列表：
```
$ deft sandbox list # show read-only and writable lists
$ deft sandbox add /srv/data # add a read-only path
$ deft sandbox add ~/code/tmp -w # add a writable path (-w/--writable)
$ deft sandbox remove /srv/data # remove from either list
````
路径支持开头的 `~`（应用沙箱时展开为 `$HOME`）。沙箱本身在运行时通过 `DEFT_SANDBOX=1` 选择启用。完整文档参见沙箱。
## 构建标志
该二进制通过 `zig build` 构建。关键标志：
| 标志 | 效果 |
|---|---|
| `-Dffi=true` | 启用 `ffi/*` 命名空间（加载共享库、调用 C 函数）。默认关闭。 |
| `-Denable-tui=true` | 构建 TUI 宿主（`retro` / `retra` 二进制）。`retro`/`retra` 目标默认开启。 |
| `-Doptimize=ReleaseFast` | 面向生产环境的优化构建。 |
| `-Dtarget=x86_64-linux-gnu` | 交叉编译。 |
```
$ zig build deft -Doptimize=ReleaseFast
$ zig build deft -Dffi=true -Doptimize=ReleaseFast
$ zig build retro
````
关于 FFI，参见 FFI。
## 能力
`[capabilities]` 返回编译时内置的特性映射。用它编写可优雅降级的可移植脚本：
def caps [capabilities] if [get $caps :ffi] { # call into a C library } { # pure-Deft fallback }
常见键：`:ffi`、`:tui`、`:websockets`、`:sqlite`、`:crypto`。
## 常见模式
### 通过管道将脚本传入 stdin
```bash
$ echo 'echo "hello from stdin"' | deft -
hello from stdin
````
### 运行单行命令
```bash
$ deft -e 'echo "2 + 2 = $(2 + 2)"'
2 + 2 = 4
````
### 与 shell 管道结合
```bash
$ deft script.dft | jq '.users[]'
````
## 快速参考
| 命令 | 用途 |
|---|---|
| `deft <file>` | 运行脚本 |
| `deft -e "code"` | 运行单行代码 |
| `deft -` | 从 stdin 读取脚本 |
| `deft repl` | REPL |
| `deft test [files]` | 运行测试 |
| `deft fmt [files]` | 格式化 |
| `deft pkg <subcommand>` | 包管理器 |
| `deft sandbox <subcommand>` | 管理 Landlock 路径列表 |
| `deft init [name]` | 搭建项目脚手架 |
| `deft --version` | 版本 |
| `deft --help` | 帮助 |