Ops wire surface
tarsi-serve speaks ndjson JSON-lines: one {"op": …, "params": …} per line on stdin, one {"ok": …, "result"|"error"} per line on stdout — the same protocol shape as sepia serve / tamias-driver verbs. tarsi-serve manifest returns this list authoritatively.
Stage-wise note: granular per-stage ops may land as the surface grows. The six ops below are the current stable contract; check
manifestfor the live list before scripting against anything newer.
Ops
manifest
No params. Returns the service manifest:
{"name":"tarsi-serve","version":"0.1.0","ops":["manifest","profiles","plan","changelog","notes","release"]}profiles
No params (ignores dir). Returns every installed type: tarsi release profile:
{"profiles":[{"name":"9aia-release","version":"0.1.0","description":"…","source":"/path/to/dir"}]}Discovery order: $TARSI_PROFILES_DIR / ~/.config/tarsi/profiles/ (dir profiles) then the tamias store (name@label, newest label wins). See Author a release profile pack.
plan
Params: dir?, profile?, range?. Pure — computes, writes nothing.
{
"specs": [ …resolved ReleaseUnitSpec… ],
"plan": {
"units": [
{
"spec": { … },
"bump": "minor",
"new_version": "0.3.0",
"tag": "my-unit-v0.3.0",
"releases": true,
"changelog_markdown": "## [0.3.0] …",
"commits": 4,
"publish_targets": [{"target":"crates-io","enabled":false}]
}
],
"unattributed": [{"sha":"…","subject":"…"}],
"steps": ["write-changelogs","bump-manifests","commit-bump","tag","push","publish"],
"strategy": {"name":"conventional","resolved":{…rules…}}
}
}strategy echoes the release strategy resolved from [release] strategy (P-030) — name is the builtin name or "custom" for inline tables; resolved is the full rule set that produced the bumps/changelogs.
changelog
Same params as plan. Returns only the releasing units' rendered notes:
{"changelogs":[{"unit":"my-unit","version":"0.3.0","tag":"my-unit-v0.3.0","markdown":"…"}]}notes
Same params. Concatenated changelog_markdown of all releasing units in plan order:
{"notes":"## [0.3.0] …\n## [1.1.0] …\n"}release
Same params plus dry_run (default true). Executes the plan.
Dry-run result:
{"ok":true,"dry_run":true,"plan":{…},"steps_run":[],"publish":[{"target":…,"ok":…,"dry_run":true}…]}Real result (dry_run:false):
{
"ok": true,
"dry_run": false,
"plan": {…},
"steps_run": ["write-changelogs","bump-manifests","sync-refs","commit-bump","tag","push"],
"publish": [ {"target":"github-release","ok":true,…} ],
"sync_refs": {"status":"applied","old":"0.1.0","new":"0.2.0","changes":[…]}
}sync_refs reports the [release.sync_refs] stage (pack/doc version-ref rewrites folded into the bump commit — see config): status is disabled (no rules), skipped (+reason, e.g. mixed-version plan), dry-run, or applied; changes[] lists per-rule file/replacement counts and changed_files the touched paths. Dry-run results carry the same shape with status:"dry-run". The "sync-refs" steps_run entry appears only when rules are configured.
Failure shapes:
- Plan/build error → op-level
{"ok":false,"error":"…"}. - Mutation failure →
ok:falseresult withrolled_backper-step report (remote tag deletes, branch reset, local cleanup). - Publish failure with nothing published → rollback, same shape.
- Publish failure after a success →
ok:false,rolled_back: {"attempted":false,"reason":"…manual cleanup…"}— state left in place deliberately.
steps_run is the mutation-phase ledger; publish reports carry per-target ok, disabled, and target-specific fields (e.g. gh release URL, crates.io warnings).
Common params
| param | type | default | notes |
|---|---|---|---|
dir | string | "." | repo root being released |
profile | string | — | profile name; precedence: param > $TARSI_PROFILE > config profile |
range | string | per-unit tag range | "a..b" rev range applied to every unit |
dry_run | bool | true | release only — false is the mutation opt-in |
One-shot mapping
hypha-serve-cli translates argv to params:
tarsi-serve release --dir . --set profile=9aia-release --yes
# ≡ {"op":"release","params":{"dir":".","profile":"9aia-release","dry_run":false}}--set k=v values are strings; --yes/--dry-run set dry_run.