Release CoreSAFE

AI-powered CMS core for personal blogs and creator websites, with AI summaries, translation, moderation, and writing workflows.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: release-core
description: Use when releasing mx-core server (apps/core), @mx-space/api-client, or @mx-space/cli (mxs) — version bump, changelog, git tag, Docker build, GitHub Release, and Dokploy redeploy. Triggers on "发版", "release a new version", "cut a release", "bump version", "publish api-client", "publish cli", "release mxs".
---

# mx-core Release (Agent-native)

Helper scripts live in `.claude/skills/release-core/scripts/` (each `cd`s to repo root, runs fine from anywhere). They print compact, verifiable output — read it instead of re-deriving state with ad-hoc commands.

## Three pipelines (confirm which one with the user)

| Pipeline | Where | What ships | After `git push` |
|----------|-------|------------|------------------|
| **A. Server** | `apps/core` | DockerHub `innei/mx-server` + GitHub Release zip + Dokploy redeploy | `release.yml` triggers on tag `v*` |
| **B. api-client** | `packages/api-client` | npm `@mx-space/api-client` | `api-client.yml` runs CI only; agent publishes locally |
| **C. cli** | `packages/cli` | npm `@mx-space/cli` (binary `mxs`) | no workflow; agent publishes locally |

CI runs lint, typecheck, and smoke tests on the tag — don't re-run them locally before tagging; fix forward via a follow-up patch if CI fails.

Safety invariant: never use `git reset --hard`, `git checkout --`, `git restore`, force-push, or any destructive equivalent in this release flow. If recovery is needed, inspect the working tree, preserve diffs, and ask the user before touching existing files.

## A. Server release

### Step 1 — Preflight + decide version

```bash
bash .claude/skills/release-core/scripts/preflight.sh core
```

Prints tree/branch/origin checks, current version, the unreleased commit list (subjects + bodies — this is also the source material for step 3), and whether `apps/admin` changed. Any `RED` line → stop and confirm with the user.

Choose the bump from the commit list:

| Bump | Trigger |
|------|---------|
| `patch` | only `fix:` / `docs:` / `chore:` / `refactor:` / `test:` |
| `minor` | any `feat:` |
| `major` | `BREAKING CHANGE:` or `feat!:` / `fix!:` — **always confirm with user** |
| `prerelease` | RC / canary numeric suffix |

State the chosen version explicitly to the user, then continue.

### Step 2 — Prepare

```bash
bash .claude/skills/release-core/scripts/prepare-server.sh X.Y.Z
```

Does, in order: verifies no tracked files are already changed → fetches origin and aborts if `origin/master` moved since preflight → `node apps/core/scripts/bump-admin-version.js` (patch-bumps `apps/admin/package.json` iff admin changed since the last `v*` tag, so the bundled admin version stays distinct from the last R2-published one) → sets core version → regenerates `apps/core/CHANGELOG.md` (conventional-changelog, Angular preset, scoped to `apps/core`) → backs up old release notes to `/tmp` and deletes `apps/core/RELEASE_NOTES.md`. Prints changed files, version diffs, and the head of the new changelog block.

Check the printed changelog block: header `## [X.Y.Z](compare-link) (YYYY-MM-DD)`, entries grouped under `### Bug Fixes` / `### Features`, only feat/fix/breaking commits, each `* **scope:** subject ([sha7](link))`. If wrong: stop, inspect `git diff apps/core/CHANGELOG.md`, then edit the changelog manually while preserving unrelated hunks.

If preflight showed `apps/admin` changed but the script logged `admin unchanged`, stop and fix before tagging.

### Step 3 — Author `apps/core/RELEASE_NOTES.md`

This file becomes the GitHub Release body (CI reads it via `body_path`). Step 2 deletes the file after copying the old content to `/tmp` — it does not exist at this point. Create it with the Write tool directly; do not read the `/tmp` backup or reuse the previous release body.

**Select** from the commit list preflight printed:

1. Always: `feat:`, `fix:`, anything breaking (`BREAKING CHANGE:` footer, `feat!:` / `fix!:`).
2. Only if user-visible: `refactor:` / `chore:` / `perf:` / `docs:` (dependency major, behaviour change, performance, public API). Skip the rest.
3. Never: `style:`, `test:`, tooling with no runtime impact.

**Structure**: any feat or breaking, or ≥4 selected entries → **full**. All selected entries internal-only → **simple** with TL;DR `Internal maintenance release; no user-facing changes.` Otherwise → **simple**.

**Full**:

```markdown
## TL;DR

<one sentence>

## Breaking Changes   <!-- only when present -->

- **<area>**: <what + why>. **Migration**: <concrete operator action>.

## Highlights

<2–3 prose paragraphs, one topic each — user-visible behaviour and value>

## Changes

### Features
- <what users can now do> ([#PR] or [sha])

### Bug Fixes
- <what is fixed> ([#PR] or [sha])

### Other   <!-- only for selected user-visible refactor/chore/perf -->

## Upgrade Notes   <!-- only when manual operator action is required -->

---

**Full Changelog**: https://github.com/mx-space/core/compare/v<prev>...v<this>
```

**Simple**: just `## TL;DR` + `## Changes` (flat list) + the Full Changelog link.

**Rules**: rewrite in user-facing language, never copy a commit subject verbatim; link priority PR `#NNNN` > issue > 7-char sha with commit URL; every Breaking entry MUST carry a `**Migration**:` clause; TL;DR is one sentence, 15–25 words; Highlights paragraphs 40–80 words; omit empty sections entirely.

Print the rendered file to chat as a status update (visibility, not approval) and proceed — the flow runs unattended; only stop if a step 1 red flag is unresolved.

### Step 4 — Finalize + watch CI

```bash
bash .claude/skills/release-core/scripts/finalize-server.sh X.Y.Z
```

Does: assert notes non-empty → commit `release: vX.Y.Z` with `--no-verify` → annotated tag `vX.Y.Z` → push commit + tag (the tag push triggers `release.yml`) → print the commit stat and the matching tag-triggered run.

Verify the printed stat shows exactly 3 files (4 when admin was bumped). Then:

```bash
gh run watch <run-id>
```

`release.yml`: quality → build (Gi

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

apps/core/.env

Gates applied: no_behavioural_pass.