# 编程 API

> API 目标：让 MoonBit 库、CI action 和外部工具复用同一个模型与 planner。名称在实现前为设计名，发布时以生成的 `.mbti` 为准。

稳定入口位于 `unmbt/moonset/api`，由 root 包 re-export。`model`、`engine`（无 I/O）与 `workspace`（core/async 读取）仍分别拥有领域类型、纯规划能力和发现能力。公共 API 当前为 v1.0；adapter 扩展仍标记 experimental。

```text
engine.parse_config(source, path?) -> Config
engine.parse_changeset(source, id~, path~, mixed?) -> Changeset
engine.parse_pre_state(source, path?) -> PreState
engine.build_plan(snapshot, changesets, pre?, generated_at?) -> ReleasePlan
engine.status_json(snapshot, plan, changeset_directory?) -> Json
workspace.discover(cwd, config_path?, since?) -> LoadedWorkspace  // async
cli.run(args_without_executable) -> Int                         // async
```

纯函数使用 `MoonsetError` 报告输入错误；I/O 层可能返回底层文件或进程错误，CLI 将其转换为结构化诊断及退出码。LoadedWorkspace 同时包含 snapshot、changesets、pre 和 changeset 目录。`build_plan` 不读取任何外部状态。下文接口表和 adapter traits 保留为后续阶段设计。

## 1. 公共包

| 包 | 责任 | 稳定性 |
|---|---|---|
| `@moonset/api` | 稳定 facade 与 `api_version` | v1.0 |
| `@moonset/model` / `@moonset/engine` | 领域类型、纯规划、版本计划 | 由 api facade 暴露 |
| `@moonset/changelog` | 内置生成器、`ChangelogGenerator`、registry | v1 稳定 |
| `@moonset/adapters` | JSONL runner、publisher registry、capability contracts | v1 实验，v2 稳定 |

CLI 通过 workspace 读取输入，再调用同一个 engine planner；不能复制规划逻辑。

## 2. 核心函数形状

```text
async fn discover(root~ : String, io~ : WorkspaceIo) -> WorkspaceSnapshot raise
async fn read_changesets(snapshot~ : WorkspaceSnapshot, fs~ : FileSystem) -> Array[Changeset] raise
fn build_plan(snapshot~ : WorkspaceSnapshot, changesets~ : Array[Changeset], pre~ : PreState?) -> ReleasePlan raise
async fn apply_plan(plan~ : ReleasePlan, fs~ : FileSystem, clock~ : Clock) -> ApplyResult raise
async fn publish(plan~ : ReleasePlan, publisher~ : Publisher, options~ : PublishOptions) -> PublishResult raise
```

具体公共声明以各包生成的 `.mbti` 为准。API 遵循 SemVer；兼容新增走 minor，破坏性变更走 major。ReleasePlan JSON schema 单独版本化。

## 3. 适配器接口

- `FileSystem`：read/write/rename/hash/list；默认实现基于 `moonbitlang/core/async/fs`。
- `Git`：status、diff、changed_files、commit、tag、push；命令参数独立传递。
- `Publisher`：preflight、publish、already_published；默认实现调用 `moon publish`，可替换为 registry HTTP 或测试 double。
- `Clock`：`today_utc`、`unix_seconds`；测试使用固定时钟。
- `Prompt`：confirm/select/input；CI 使用 non-interactive 实现。

混合 workspace 新增 `EcosystemAdapter` 与 `ArtifactProvider`：

- `EcosystemAdapter`：发现成员、声明字段所有权、解析/更新原生依赖、生成清单 diff、校验版本/渠道能力、staging 锁文件、pack；各步骤返回结构化数据。其 I/O 步骤在 planner 外执行，不能把 install 隐藏在纯 build_plan 中。
- `ArtifactProvider`：规划时声明源与派生包、平台产物和构建依赖，执行时交付带版本/commit/hash 的产物。未知产物不能直接成为发布目标。
- `PublisherRegistry`：按 `(ecosystem, unitId, target)` 路由，区分 already-published、内容冲突和能力不支持。单一 `Publisher` 参数仅适用于单目标便捷 API。

原 `Module` 设计改为 ReleaseUnit；adapter trait 在 v1 标记 experimental，方法以生成的 `.mbti` 为准。

## 4. 版本策略

公共 API 版本化遵循：

- `model` 的字段只新增可选字段；删除或改变含义需要 major。
- `ReleasePlan.schemaVersion` 独立于 moonset CLI 版本。
- 适配器 trait 增加方法时提供 default 或新 trait，避免破坏旧实现。
- 生成器和 publisher 名称必须可在 plan 中追踪。

## 5. API 安全边界

核心 API 不接收原始 shell 字符串、不输出凭据、不允许 generator 直接写文件。JSONL runner 只启动显式登记的 executable，并可通过 `environment` 白名单传入运行所需变量。需要宿主权限的实现必须显式传入 adapter；这样 planner 和 changeset parser 可以在 wasm/native 测试中复用。
Operational adapter ports and the JSONL generator protocol are exposed from `unmbt/moonset/api`; adapter traits are experimental in API v1.
