Spec-driven MoonBit workspace release planning
moon install unmbt/moonset/cmd/moonset
moonset -Vcurl -fsSL https://raw.githubusercontent.com/unmbt/moonset/master/scripts/install.sh | bashirm https://raw.githubusercontent.com/unmbt/moonset/master/scripts/install.ps1 | iex注意:预编译二进制安装脚本会将文件安装到 ~/.unmbt(与同组织工具 moon-bump 共享目录),并自动将其加入 PATH。安装完成后可能需要重启终端;CI 环境请直接使用 unmbt/moonset/setup@v1 Action。
# 1. 初始化 .changeset/ 目录、默认配置与 .gitignore
moonset init
# 2. 检查本机工具链、Git 与 workspace 状态
moonset doctor
# 3. 记录一次变更(不传参数进入交互式 TUI,也可使用非交互参数)
moonset add
moonset add --package unmbt/example/core --type minor --summary "新增流式解析接口"
# 4. 预览待发布版本计划(只读)
moonset status --verbose
moonset publish-plan --pretty
# 5. 应用版本号、更新依赖范围并生成 CHANGELOG.md 与 .moonset/release-state.json
moonset version --dry-run
moonset version
# 6. 提交发布改动后,先预演发布再正式发布与打 tag
git add -A && git commit -m "chore: release"
moonset publish --dry-run
moonset publish --yes # 干净工作树下会自动触发 tag(可用 --no-tag 跳过后手动打标)
moonset tag --push --yes预发布模式提示:可通过 moonset pre enter alpha --initial-version 进入预发布,多次发布后执行 moonset pre exit && moonset version 毕业为正式版。--since main 只读取 HEAD 已提交快照,适合 CI 校验 PR 是否附带了 changeset。更多问题见 常见问题与排障 FAQ。
| 原则 | 释义 | |
|---|---|---|
| 🪶 | 变更即文稿 | 每一次改动,伴随一份 Markdown changeset,意图与影响一目了然。 |
| 🧮 | 规划器至纯 | 版本推演是不触碰文件、Git 与网络的纯计算,便于测试,亦便于信任。 |
| 🔌 | 适配器可换 | Git、Mooncakes、GitHub 等副作用皆收束于适配器,核心不作任何平台假设。 |
| 🛡️ | 写盘有度 | 先校验、后落笔;任何一步失败,皆不留下半成品。文件原子替换,失败可恢复。 |
| 🧾 | 输出皆契约 | 人类输出与 --json 同为接口,脚本只需依赖版本化的 JSON。 |
flowchart LR
A["✍️ add<br/>撰写 changeset"] --> B["🔎 status<br/>查看预计发布"]
B --> C["📦 version<br/>应用版本与日志"]
C --> D["🧳 pack<br/>打包"]
D --> E["🚀 publish<br/>发布"]
E --> F["🏷️ tag<br/>标记版本"]| 命令 | 作用 | 默认写盘 | 网络 |
|---|---|---|---|
| init | 初始化 .changeset 目录 | ✅ | — |
| add | 创建一份 changeset | ✅ | — |
| status | 查看变化与预计发布 | — | — |
| publish-plan | 输出完整 release plan(JSON) | — | — |
| version | 应用版本号并生成 changelog | ✅ | — |
| pre | 进入、退出或查看预发布模式 | ✅ | — |
| pack | 生成 MoonBit 包归档 | 可选 | — |
| publish | 发布已版本化的模块 | 可选 | ✅ |
| tag | 创建当前版本的 Git 标签 | 可选 | 可选 |
| doctor | 只读诊断本机与 workspace | — | 可选 |
---
"unmbt/example/core": minor
"unmbt/example/cli": patch
---
新增流式解析接口;CLI 随之修正了换行处理。{
"schemaVersion": 1,
"baseBranch": "main",
"access": "public",
"fixed": [["unmbt/core", "unmbt/cli"]],
"updateInternalDependencies": "patch",
"changelog": { "generator": "github", "options": { "repo": "unmbt/moonset" } },
"publisher": { "kind": "moon", "registry": "default", "dryRunFirst": true }
}name: moonset bot
on:
pull_request_target:
types: [opened, synchronize, reopened, ready_for_review]
concurrency:
group: moonset-pr-bot-${{ github.event.pull_request.number }}
cancel-in-progress: true
permissions: {}
jobs:
check:
runs-on: ubuntu-latest
permissions: { contents: read }
outputs:
comment: ${{ steps.check.outputs.comment }}
state: ${{ steps.check.outputs.state }}
should-comment: ${{ steps.check.outputs.should-comment }}
steps:
- uses: actions/checkout@v5
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
persist-credentials: false
- id: check
uses: unmbt/moonset/pr-check@v1
with:
base-sha: ${{ github.event.pull_request.base.sha }}
head-repo: ${{ github.event.pull_request.head.repo.full_name }}
head-ref: ${{ github.event.pull_request.head.ref }}
comment:
needs: check
runs-on: ubuntu-latest
permissions: { pull-requests: write }
steps:
- uses: unmbt/moonset/pr-comment@v1
with:
comment: ${{ needs.check.outputs.comment }}
state: ${{ needs.check.outputs.state }}
should-comment: ${{ needs.check.outputs.should-comment }}name: moonset release
on:
push:
branches: [main]
concurrency:
group: moonset-release-${{ github.ref }}
cancel-in-progress: false
permissions: {}
jobs:
version-pr:
runs-on: ubuntu-latest
permissions: { contents: write, pull-requests: write }
outputs:
has-changesets: ${{ steps.release.outputs.has-changesets }}
steps:
- uses: actions/checkout@v5
with: { fetch-depth: 0 }
- id: release
uses: unmbt/moonset@v1
with:
mode: version-pr
publish:
needs: version-pr
if: needs.version-pr.outputs.has-changesets == 'false'
runs-on: ubuntu-latest
permissions: { contents: write, id-token: write }
steps:
- uses: actions/checkout@v5
with: { fetch-depth: 0 }
- uses: hustcer/setup-moonbit@v1
- uses: unmbt/moonset@v1
with:
mode: publish
mooncakes-credentials: ${{ secrets.MOONCAKES_CREDENTIALS }}上线前两项必查:① 在仓库 Settings → Actions → General → Workflow permissions 勾选 Allow GitHub Actions to create and approve pull requests;② 在 Settings → Secrets and variables → Actions 配置 MOONCAKES_CREDENTIALS(与 ~/.moon/credentials.json 一致)。若默认分支为 master,请同步调整 branches 与 .changeset/config.json 中的 baseBranch。详细排障见 FAQ 与 自动化设计。
moonset/
├─ cmd/moonset/ CLI 入口、退出码与顶层错误
├─ model/ 领域类型与序列化 schema(纯核)
├─ engine/ 解析、校验、纯规划与 Markdown 评论渲染(纯核)
├─ changelog/ 内置 changelog 生成器与 registry(纯核)
├─ workspace/ moon.mod / moon.work / npm / pnpm / Cargo 发现
├─ adapters/ Capability 契约、PublisherRegistry 与 JSONL 插件
├─ executor/ ExecutionHost、原子 journal、staging、pack/publish/tag/doctor
├─ api/ 稳定编程 API facade
├─ cli/ 参数解析、TUI 与输出渲染
├─ setup/ pr-check/ pr-comment/ 模块化 PR Bot GitHub Actions
└─ action.yml 根发布 Action(version-pr / publish)| 阶段 | 主题 | 状态 |
|---|---|---|
| 0 | 规格与探针 | 已完成 |
| 1 | 核心读模型与规划器(status · publish-plan) | 已实现 |
| 2 | 贡献工作流(init · add · pre) | 已实现 |
| 3 | 版本与 Changelog(version · tag) | 已实现 |
| 4 | 发布与官方自动化(pack · publish · Actions) | 已实现(含发布 Action) |
| 5 | 扩展生态(稳定 API 与插件协议) | 已实现 |
| 6 | PR Bot Actions 与规模化治理 | PR Bot Action 与 100 包基准已发布 v0.1.0(1000 包 / FR-022 矩阵见 0.2.0+) |
moon check # 类型检查
moon test # 运行测试
moon info && moon fmt # 更新接口并格式化[!NOTE] Current status: Phases 1–5 core & mixed workspaces implemented; PR Bot GitHub Actions integrated. init, add, pre, status (human/json/markdown), publish-plan, version, pack, publish, tag, doctor, and unmbt/moonset/api are implemented. Cargo support is limited to crates.io, and Tauri/other registries remain deferred. See Requirements and Automation.
moon install unmbt/moonset/cmd/moonset
moonset -Vcurl -fsSL https://raw.githubusercontent.com/unmbt/moonset/master/scripts/install.sh | bashirm https://raw.githubusercontent.com/unmbt/moonset/master/scripts/install.ps1 | iexNote: The user install scripts place moonset into ~/.unmbt (alongside moon-bump) and add it to your PATH. Restart your terminal if needed. For CI workflows, use the dedicated unmbt/moonset/setup@v1 GitHub Action instead.
# 1. Initialise .changeset/ config, README, and .gitignore
moonset init
# 2. Verify local MoonBit, Git, and workspace configuration
moonset doctor
# 3. Create a changeset (interactive TUI by default, or pass flags)
moonset add
moonset add --package unmbt/example/core --type minor --summary "Add streaming parser"
# 4. Preview pending releases (read-only)
moonset status --verbose
moonset publish-plan --pretty
# 5. Apply version bumps, dependency ranges, CHANGELOG.md, and release-state.json
moonset version --dry-run
moonset version
# 6. Commit release changes, preflight, publish, and push tags
git add -A && git commit -m "chore: release"
moonset publish --dry-run
moonset publish --yes
moonset tag --push --yesPrereleases: run moonset pre enter alpha --initial-version to enter prerelease mode, then graduate back to stable with moonset pre exit && moonset version. See FAQ & Troubleshooting for common questions.
| Principle | In essence | |
|---|---|---|
| 🪶 | Changes as prose | Every change travels with a Markdown changeset, so intent and impact are plain to see. |
| 🧮 | A pure planner | Version planning is pure computation — no files, Git or network — easy to test, easy to trust. |
| 🔌 | Swappable adapters | Git, Mooncakes and GitHub live behind adapters; the core assumes no platform. |
| 🛡️ | Measured writes | Validate first, write later. Files are replaced atomically, and failures leave nothing half-done. |
| 🧾 | Output is contract | Human output and --json are both interfaces; scripts rely on versioned JSON alone. |
flowchart LR
A["✍️ add<br/>write a changeset"] --> B["🔎 status<br/>preview releases"]
B --> C["📦 version<br/>apply versions & logs"]
C --> D["🧳 pack<br/>archive"]
D --> E["🚀 publish<br/>release"]
E --> F["🏷️ tag<br/>mark the version"]| Command | Purpose | Writes by default | Network |
|---|---|---|---|
| init | Initialise the .changeset directory | ✅ | — |
| add | Create a changeset | ✅ | — |
| status | Inspect changes and the expected release | — | — |
| publish-plan | Emit the full release plan (JSON) | — | — |
| version | Apply versions and generate the changelog | ✅ | — |
| pre | Enter, exit or inspect pre-release mode | ✅ | — |
| pack | Produce MoonBit package archives | optional | — |
| publish | Publish versioned modules | optional | ✅ |
| tag | Create Git tags for the current version | optional | optional |
| doctor | Read-only diagnosis of host and workspace | — | optional |
---
"unmbt/example/core": minor
"unmbt/example/cli": patch
---
Add a streaming parser API; the CLI now handles line endings correctly.{
"schemaVersion": 1,
"baseBranch": "main",
"access": "public",
"fixed": [["unmbt/core", "unmbt/cli"]],
"updateInternalDependencies": "patch",
"changelog": { "generator": "github", "options": { "repo": "unmbt/moonset" } },
"publisher": { "kind": "moon", "registry": "default", "dryRunFirst": true }
}[!IMPORTANT] Before enabling automated Release PRs:
- Enable Allow GitHub Actions to create and approve pull requests under Settings → Actions → General → Workflow permissions.
- Add repository secret MOONCAKES_CREDENTIALS (contents of ~/.moon/credentials.json after moon login). See FAQ & Troubleshooting if you hit permission or runner queuing issues.
moonset/
├─ cmd/moonset/ entry point, exit codes, top-level errors
├─ model/ domain types and serialisation schema (pure core)
├─ engine/ parsing, pure release planner, Markdown bot renderer (pure core)
├─ changelog/ built-in generators & registry (pure core)
├─ workspace/ moon.mod / moon.work / npm / pnpm / Cargo discovery
├─ adapters/ capability contracts, PublisherRegistry & JSONL plugins
├─ executor/ ExecutionHost, atomic journal, staging, pack/publish/tag/doctor
├─ api/ stable public API facade
├─ cli/ argument parsing, TUI & output rendering
├─ setup/ pr-check/ pr-comment/ modular PR Bot GitHub Actions
└─ action.yml root release Action (version-pr / publish)| Phase | Theme | Status |
|---|---|---|
| 0 | Specification & probes | Completed |
| 1 | Core read model & planner (status · publish-plan) | Implemented |
| 2 | Contribution workflow (init · add · pre) | Implemented |
| 3 | Versioning & changelog (version · tag) | Implemented |
| 4 | Publishing & official automation (pack · publish · Actions) | Implemented |
| 5 | Extension ecosystem (stable API & plugin protocol) | Implemented |
| 6 | PR Bot Actions & governance at scale | PR Bot Actions & 100-pkg bench shipped in v0.1.0 (v0.2.0+ tracks 1000-pkg & FR-022 matrix) |
moon check # type-check
moon test # run the tests
moon info && moon fmt # refresh interfaces and formatInstall
Download zipSpec-driven MoonBit workspace release planning