# v1.0.0 — Stable release 🎉

> The fork graduates. Code-identical to `0.5.0` and `1.0.0-rc.1` — what changes is the contract.

## What "stable" means

Starting now, [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) applies to the `capcut-cli-david` public surface in full. The contract is documented in [`RELEASE.md`](../RELEASE.md) §1 and bound to:

- **Patch** (`1.0.x`) — bug fixes, no API changes
- **Minor** (`1.x.0`) — new commands, new flags, additive JSON-output fields, and any change that older callers pass through unchanged
- **Major** (`2.0.0`) — breaking changes (renamed flags, removed commands, JSON-shape mutations, exit-code remaps, Node-version floor bumps). Telegraphed via `deprecated:` warnings in a prior minor.

The public surface, frozen at this point in time:

- **CLI commands** — `info`, `tracks`, `materials`, `segments`, `texts`, `export-srt`, `segment`, `material`, `init`, `add-video`, `add-audio`, `add-text`, `set-text`, `shift`, `shift-all`, `speed`, `volume`, `opacity`, `trim`, `add-keyframe`, `ken-burns`, `save-template`, `apply-template`, `cut`, `batch`, `psycho-build`
- **Flags** documented in `capcut-david <command> --help`
- **JSON output shape** for the inspect family
- **Exit codes** (`0` success, `1` user error, ≥`2` reserved for specific failure classes)
- **Written-draft invariants** (cutcli-shape variant by default; `new_version: "167.0.0"`, no `loudnesses` ref)
- **Node minimum** — `engines.node >= 18`
- **`bin` name** — `capcut-david`
- **CapCut versions tested** — desktop ≥ 5.x; cutcli emitter (167.x) and CapCut-UI emitter (169.x)

Anything not in that list (internal types, source structure, dist layout, undocumented helpers) is not covered.

## Highlights since 0.x — the journey to 1.0

| Phase | Tag | What landed |
|---|---|---|
| Phase A | `0.1.0` | Fork from `renezander030/capcut-cli`, restructure to modular `src/` (CLI / draft / commands / utils), keep custom arg parser, ship `0.1.0` |
| Phase B | `0.2.0` | Fixture-backed `node:test` harness; 9 anonymized CapCut fixtures; ≥80% line + function coverage on every command; CI matrix on Node 18/20/22 × Ubuntu/macOS/Windows |
| Phase C | `0.3.0` | Creation primitives: `add-keyframe` (generic per-property keyframe insertion with curves) and `ken-burns` (paired scale_x/scale_y opinionated zoom) |
| Phase D | `0.4.0` | The killer feature: `psycho-build <manifest.yaml>` — single command that consumes a YAML manifest of images + audio + SRT and produces a complete TikTok-format (1080×1920) draft. Hand-rolled YAML + SRT parsers, mulberry32 + FNV-1a seeded UUIDs for deterministic builds. Zero new draft-writing code in the pipeline module — pure orchestration |
| Phase E | `0.5.0` | Packaging consolidation: bundled `capcut-david` Claude skill (replaces 5 `cut-*` legacy skills), `docs/draft-schema/` 7-file in-repo schema reference (~3000 lines), README rewrite with comparison table, meta-docs (`COMPATIBILITY.md`, `UPSTREAM.md`, `RELEASE.md`) moved into the repo, `release-notes/` directory |
| Graduation | `1.0.0-rc.1` | Code-identical RC; pre-release audit verdict **SHIP**; soak checklist self-validated |
| **Graduation** | **`1.0.0`** | **You are here.** SemVer contract takes effect |

By the numbers (cumulative, `master` at `v1.0.0`):

- **27 CLI commands** across 6 families (inspect, edit, create, animate, template, pipeline)
- **173 tests** across 9 test files; ≥80% line + function coverage
- **3000+ lines** of in-repo schema documentation
- **0 runtime dependencies** (Node stdlib only)
- **52 files** in the published tarball, ~110 kB compressed

## Migration from 0.x

If you have automation pinned to any `0.x` tag:

- `0.4.0` → `1.0.0` — **no change required**. The CLI surface is byte-identical between `0.5.0`, `1.0.0-rc.1`, and `1.0.0`. Just bump the version pin.
- `0.1.0–0.3.0` → `1.0.0` — review your usage of the inspect family (added `0.1.0`) and creation primitives (added `0.3.0`). The CLI surface is additive across the `0.x` line; nothing was removed.

If you were using any of the 5 `cut-*` Claude skills (`cut-audio`, `cut-draft`, `cut-motion`, `cut-storyboard`, `cut-tiktok`):

- They are **deprecated as of `2026-05-12`** with `deprecated: true` frontmatter and a redirect callout in each `SKILL.md`.
- Migrate to the unified `capcut-david` skill bundled in this package.
- Install: `mkdir -p ~/.claude/skills && cp -r "$(npm root -g)/capcut-cli-david/skills/capcut-david" ~/.claude/skills/`
- Each old skill's redirect note points at the specific replacement recipe (e.g. `cut-motion` → `skills/capcut-david/SKILL.md` §Recipes / Ken Burns + `references/recipes-motion.md`).
- The `cut-draft` (Chinese cutcli command catalogue) is fully replaced by `capcut-david --help` plus the in-repo schema reference at `docs/draft-schema/`.

## Deprecated and removed

- The 5 legacy `cut-*` Claude skills (deprecated; file kept for reference; redirect in place).
- The `cutcli` Go binary as a runtime dependency for any of these workflows — `capcut-david` is a pure Node fork with zero runtime deps. (The upstream `cutcli` and `capcut-cli` continue to exist independently — see [`UPSTREAM.md`](../UPSTREAM.md).)

## Roadmap (1.x)

- **`1.x.0` — `capcut-david query`** — animation / sticker / effect / filter catalogue lookup. Already referenced by the bundled skill recipes; flagged `planned for v0.6.0` in the `0.5.0` skill notes (re-baselined to `1.x` post-graduation).
- **`1.x.0` — schema validation command** — `capcut-david validate <project>` against the `docs/draft-schema/` invariants
- **`1.x.0` — JianYing 6+ research** — currently unsupported (encrypted draft); track upstream progress in `COMPATIBILITY.md`
- **`1.x.0` — `psycho-build` audio modes** — dynamic ducking via voice-activity detection (`during_voice` mode)

Filed issues drive the order. None of the above is committed.

## Compatibility

Unchanged from `0.5.0` and `1.0.0-rc.1`:

- **CapCut**: ≥ 5.x desktop (Windows + macOS), both `cutcli`-emitted shape (`new_version: 167.x`) and CapCut-UI shape (`169.x`) supported
- **JianYing**: 5.x presumed-equivalent. **JianYing 6+ unsupported** — encrypted `draft_content.json`, see [`COMPATIBILITY.md`](../COMPATIBILITY.md) §5
- **Node**: ≥ 18 (`engines.node`)
- **Runtime deps**: zero

## Install

```bash
npm install -g capcut-cli-david
capcut-david --help
```

To wire up the bundled Claude Code skill:

```bash
mkdir -p ~/.claude/skills
cp -r "$(npm root -g)/capcut-cli-david/skills/capcut-david" ~/.claude/skills/
```

## Thanks

- [renezander030](https://github.com/renezander030) — `cutcli` and `capcut-cli` upstream authors. The fork would not exist without their work; both projects continue independently.
- ByteDance — the CapCut product itself. This project is unaffiliated and works against CapCut's local draft files only.
- Everyone who ran the `0.x` series in production and silently survived its sharp edges.

## Links

- [`CHANGELOG.md`](../CHANGELOG.md) — full prose changelog
- [`README.md`](../README.md) — tagline, Quickstart, comparison table, command index
- [`skills/capcut-david/SKILL.md`](../skills/capcut-david/SKILL.md) — unified Claude Code skill
- [`docs/draft-schema/`](../docs/draft-schema/) — `draft_content.json` reference (7 files, ~3000 lines)
- [`RELEASE.md`](../RELEASE.md) — release process and SemVer policy
- [`UPSTREAM.md`](../UPSTREAM.md) — upstream sync policy
- [`COMPATIBILITY.md`](../COMPATIBILITY.md) — CapCut / JianYing / Node version matrix