tripl 0.2.0__tar.gz → 0.2.2__tar.gz

{tripl-0.2.0 → tripl-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tripl
-Version: 0.2.0
+Version: 0.2.2
 Summary: Operator CLI for a tripl tracking-plan instance: diagnostics, health and live monitoring
 Project-URL: Homepage, https://vladenisov.github.io/tripl/
 Project-URL: Documentation, https://vladenisov.github.io/tripl/run/cli
@@ -98,6 +98,13 @@ tripl scans cancel <scan> <job-id> --project SLUG   # cancel an active job (WRIT
 tripl drifts list         # schema drifts; untriaged by default
 tripl drifts dismiss <drift-id> --project SLUG      # false_positive or snooze (WRITE)
 tripl drifts reopen <drift-id> --project SLUG       # back to open; drops the note (WRITE)
+tripl annotate "Deployed web 2026.09.25" --project SLUG --url URL   # deploy marker on monitoring charts (WRITE)
+tripl check               # validate the tracking calls in this checkout against the plan
+tripl check --payloads events.ndjson   # validate captured events; a missing required field fails
+tripl check --format sarif > tripl.sarif   # SARIF 2.1.0 for code scanning
+tripl codegen             # typed tracking code (Swift, Kotlin, TypeScript) from the plan
+tripl codegen --check     # CI: exit 1 when the committed generated files are out of date
+tripl export --out plan-schemas   # one JSON Schema (2020-12) per event, plus the bundle
 tripl install --app-url https://tripl.example.com --version 1.5.0   # provision a stack and start it (HOST)
 tripl install --app-url https://tripl.example.com --dry-run   # print the plan, write nothing
 tripl upgrade --to 1.6.0  # move an installed stack to a new image tag (HOST)
@@ -108,7 +115,7 @@ cannot move you onto an image you have not read the notes for. The command says
 so on stderr when you leave it at the default.
 
 `doctor`, `status`, `watch`, `scans list`, `scans jobs` and `drifts list` are
-**read-only** — a `tk_r_` key is enough. The four marked WRITE need a `tk_w_`
+**read-only** — a `tk_r_` key is enough. The five marked WRITE need a `tk_w_`
 key backed by an editor or owner, and the CLI does not pre-judge that: the key
 prefix is derived from the scope's first letter server-side and says nothing
 about the user's role, so the request is sent and the API's own 403 is printed.
@@ -116,12 +123,122 @@ about the user's role, so the request is sent and the API's own 403 is printed.
 `scans cancel`, `drifts dismiss` and `drifts reopen` prompt on a terminal and
 take `--yes`; when stdin is **not** a terminal and `--yes` was not given they
 refuse with exit 2 rather than hanging a cron job or proceeding silently.
-`scans run` does not prompt and has no `--yes` at all — passing one is exit 2,
-because a no-op flag here is a flag a script author will assume works on the next
-command too. All four writes take `--dry-run`, which resolves everything, prints
+`scans run` and `annotate` do not prompt and have no `--yes` at all — passing one
+is exit 2, because a no-op flag here is a flag a script author will assume works
+on the next command too. All five writes take `--dry-run`, which resolves everything, prints
 the exact request (method, path, params, body — never a credential) and sends
 nothing.
 
+`annotate` posts a chart marker with source `api`, for a deploy step in CI. On
+this one command `--url` is the release link the marker opens, not the instance:
+give the instance with `TRIPL_BASE_URL`, `--base-url`, or `--url` before the
+command name. The API de-duplicates the same `api` label within 24 hours (manual
+annotations are never de-duplicated) and answers
+200 with the existing marker; `annotate` says so and still exits 0, so a retried
+job is harmless.
+
+`check` validates code against the plan. `.tripl/check.yml` (found at or above
+the current directory, up to the repository root; `--check-config PATH`
+otherwise) names the project and, **per event type**, how its calls look — your
+own wrapper first, SDK presets as shorthands:
+
+```yaml
+project: my-app
+sources: ["Sources/**", "web/src/**"]
+enums: [{file: "Sources/**/Events.swift", languages: [swift]}]
+event_types:
+  se:
+    calls:
+      - function: "Analytics.shared.log"      # or `pattern:` (a regex)
+        args: {category: category, action: action, label: label, properties: properties}
+      - objc_selector: "trackWithCategory:action:label:"
+  page: {preset: snowplow_screen_view}
+  legacy: {calls: [{function: "Analytics.shared.logEvent", name_arg: 0}]}
+```
+
+Presets: `segment_track`, `amplitude_log_event`, `snowplow_structured`,
+`snowplow_screen_view`, `snowplow_self_describing`. Swift, Objective-C, Kotlin,
+Java and TypeScript/JavaScript are read; enum shorthand (`.home`) and qualified
+cases resolve through the enum files, interpolated names become plan variables
+(`"promo_sheet_\(id)_shown"` is `promo_sheet_${id}_shown`), Kotlin/Java
+`.name` / `name()` and Swift `.description` read an enum case's own name, and a
+value only known at runtime is sent as unknown, never as an error (`--strict`
+reports it). `--payloads` validates captured events instead, where a missing
+required field IS an error; a value over the validator's size limits (name 500,
+event type 100, field value 2000 characters, 200 fields) is sent as unknown and
+flagged as an `oversize_value` warning on its line.
+`check` reads nothing but the plan: any member's key works, `tk_r_` included.
+
+`codegen` turns the plan into typed tracking code, from the same
+`.tripl/check.yml`. It generates **per event-type style, never a function per
+event**, and the generated code calls **your own wrapper** (the `transport`) —
+or, with none configured, the shared `TriplDestination` in
+`TriplTransport.swift` / `.kt` / `triplTransport.ts` that you implement once.
+It never imports an SDK.
+
+| `style` | What is generated |
+|---------|-------------------|
+| `structured` | an enum per plan field (its cases are the plan's values; a variable-backed value contributes its allowed values; free text stays `String`), your wrapper's call with its argument types narrowed — `log(category: Category, action: Action, label: String, properties:)` — and a compiler-checked `knownEvents` list |
+| `screen_view` | the same, with `ScreenType` / `ScreenId` enums |
+| `named` | one generic `track(event)`: Swift `enum LegacyEvent { case homeScreenView(HomeScreenView) … }` with `name` and `properties`; Kotlin a sealed interface of data classes/objects; TypeScript `track<K extends LegacyEventName>(name: K, props: LegacyEventProps[K])` |
+| `self_describing` | one data class per schema with its fields, sharing one `track` |
+
+```yaml
+codegen:
+  out: {swift: Sources/Tracking/Generated, kotlin: app/src/main/java/tracking, ts: web/src/tracking}
+  kotlin_package: com.example.tracking
+event_types:
+  se:
+    calls: [{function: "Analytics.shared.log", args: {category: category, action: action, label: label, properties: properties}}]
+    codegen:
+      style: structured              # default: from the preset, else structured when the type has a name rule
+      transport:
+        swift: "Analytics.shared.log"                  # reuses the `calls` entry's args mapping
+        ts: {function: "analytics.log", positional: [category, action, label, properties],
+             import: "import { analytics } from './analytics';"}
+      type_names: {namespace: AppEvents, category: EventCategory, function: log}
+      template: {swift: .tripl/templates/structured.swift.mustache}   # optional override
+  legacy:
+    calls: [{function: "Analytics.shared.logEvent", name_arg: 0, properties_arg: parameters}]
+    codegen: {style: named, languages: [swift, kotlin]}
+```
+
+A `transport` given as a bare function reuses the `args` / `positional` /
+`object_arg` mapping of the `calls` entry with the same `function`. Swift passes
+labelled arguments with their labels, Kotlin as named arguments (give
+`positional` for a Java wrapper), TypeScript positionally — or as one object
+literal with `object_arg`. `type_names` renames `namespace`, `event` (the named
+/ self-describing event type), `function`, and any field's enum by field name.
+
+An event's parameters are the fields it does not fix plus one per `${token}` in
+its name (`promo_sheet_${sheet_id}_shown` takes `sheetId`, typed by the
+variable's allowed values). Plan strings become identifiers by splitting on
+anything that is not a letter or digit and on camelCase: `Home Screen View` ->
+`homeScreenView` (`HOME_SCREEN_VIEW` for Kotlin enum entries), `checkout:start`
+-> `checkoutStart`; a leading digit gets `_` (`_1stRun`), a reserved word a
+trailing `_` (`default_`), a reserved type name `Value` (`TypeValue`), and a
+collision `2`, `3` in sorted order. The raw plan string is always what is sent.
+Deprecated events are marked (`@available(*, deprecated)`, `@Deprecated`,
+`@deprecated`); archived ones are not generated.
+
+A custom `template` uses the built-in one's context (copy it from
+`tripl_cli/codegen/templates/`): a Mustache subset — `{{name}}`, `{{a.b}}`,
+`{{#list}}…{{/list}}`, `{{^empty}}…{{/empty}}`, `{{! comment }}` — where every
+plan string arrives already quoted or escaped for the language, and an unknown
+`{{name}}` is an error rather than an empty string.
+
+Output is deterministic (sorted, no timestamps) with a `Generated by tripl
+codegen — do not edit` header naming the project, branch and the plan's
+content hash (not its revision, so a new revision that changes nothing is not
+drift), so it can be committed: `tripl codegen --check` writes nothing and exits
+1 when a file is missing, differs, or is stale (generated earlier, no longer
+produced — a normal run deletes those, and only files carrying the header for
+the same project, in a language the run writes into that directory). `--model FILE`
+generates from a saved `tripl export --format codegen_model` without an
+instance. `export` writes `bundle.json` and `<event type>/<identity>.schema.json`
+per event (file names sanitised to `[A-Za-z0-9._-]`), or prints the export to
+stdout without `--out`. Both read nothing but the plan: any member's key works.
+
 `drifts reopen` is the one whose prompt is worth reading: reopening clears the
 drift's `resolution_note`, `resolved_by` and `resolved_at`, and dismissing it
 again does not bring them back.
@@ -238,10 +355,15 @@ not moved).
 
 | Exit | Meaning |
 |------|---------|
-| 0 | Every check passed, or only warned and `--strict` was not given. `status`, whenever it completed. `watch`, whenever the run completed — a failed job or a new signal is still 0. The `scans` / `drifts` verbs, whenever every read arrived or the write was accepted (`--dry-run` included). |
+| 0 | Every check passed, or only warned and `--strict` was not given. `status`, whenever it completed. `watch`, whenever the run completed — a failed job or a new signal is still 0. The `scans` / `drifts` verbs and `annotate`, whenever every read arrived or the write was accepted (`--dry-run` included, and a de-duplicated `annotate` too). |
 | 1 | The tool itself broke (doctor turns every API failure into a finding), or any other command could not complete a request — unreachable, or the API refused it. For `watch` this includes a key revoked mid-run. For `scans list` / `drifts list` it includes **any** failed read in the fan-out; for `scans run`, a job returned already `failed`; for `scans cancel` / `drifts dismiss` / `drifts reopen`, a declined prompt. |
-| 2 | Usage or configuration error. For `doctor` and `status` that is resolved before any socket opens; `watch` also refuses after reading the listings, when `--scan` matches nothing or more than 24 scan configs are selected. The `scans` / `drifts` verbs add a bare group, a missing or repeated `--project`, an unresolved or ambiguous `<scan>`, and a prompting write on a non-TTY without `--yes`. Either way **no JSON is emitted** and no write is sent. |
+| 2 | Usage or configuration error. For `doctor` and `status` that is resolved before any socket opens; `watch` also refuses after reading the listings, when `--scan` matches nothing or more than 24 scan configs are selected. The `scans` / `drifts` verbs add a bare group, a missing or repeated `--project`, an unresolved or ambiguous `<scan>`, and a prompting write on a non-TTY without `--yes`; `annotate` adds a `--url` that is not http(s), an `--at` that is not RFC 3339, and half a scope. Either way **no JSON is emitted** and no write is sent. |
 | 3 | `doctor` only: at least one check failed, or `--strict` and at least one warning. Nothing else ever exits 3. |
+
+`check` uses 0, 1 and 2: 1 when any call site or event has an error (or, with
+`--strict`, a warning), and 2 for a bad check config or payload file.
+`codegen` uses them too: 1 for drift under `--check` (or a plan without a
+configured event type), 2 for a bad check config or template.
 | 130 | Interrupted (SIGINT). For `watch` this is the **normal** ending — a run without `--duration` has no other way to stop. |
 
 An unreachable instance therefore exits **3** out of `doctor`, not 1 — it

{tripl-0.2.0 → tripl-0.2.2}/README.md

@@ -70,6 +70,13 @@ tripl scans cancel <scan> <job-id> --project SLUG   # cancel an active job (WRIT
 tripl drifts list         # schema drifts; untriaged by default
 tripl drifts dismiss <drift-id> --project SLUG      # false_positive or snooze (WRITE)
 tripl drifts reopen <drift-id> --project SLUG       # back to open; drops the note (WRITE)
+tripl annotate "Deployed web 2026.09.25" --project SLUG --url URL   # deploy marker on monitoring charts (WRITE)
+tripl check               # validate the tracking calls in this checkout against the plan
+tripl check --payloads events.ndjson   # validate captured events; a missing required field fails
+tripl check --format sarif > tripl.sarif   # SARIF 2.1.0 for code scanning
+tripl codegen             # typed tracking code (Swift, Kotlin, TypeScript) from the plan
+tripl codegen --check     # CI: exit 1 when the committed generated files are out of date
+tripl export --out plan-schemas   # one JSON Schema (2020-12) per event, plus the bundle
 tripl install --app-url https://tripl.example.com --version 1.5.0   # provision a stack and start it (HOST)
 tripl install --app-url https://tripl.example.com --dry-run   # print the plan, write nothing
 tripl upgrade --to 1.6.0  # move an installed stack to a new image tag (HOST)
@@ -80,7 +87,7 @@ cannot move you onto an image you have not read the notes for. The command says
 so on stderr when you leave it at the default.
 
 `doctor`, `status`, `watch`, `scans list`, `scans jobs` and `drifts list` are
-**read-only** — a `tk_r_` key is enough. The four marked WRITE need a `tk_w_`
+**read-only** — a `tk_r_` key is enough. The five marked WRITE need a `tk_w_`
 key backed by an editor or owner, and the CLI does not pre-judge that: the key
 prefix is derived from the scope's first letter server-side and says nothing
 about the user's role, so the request is sent and the API's own 403 is printed.
@@ -88,12 +95,122 @@ about the user's role, so the request is sent and the API's own 403 is printed.
 `scans cancel`, `drifts dismiss` and `drifts reopen` prompt on a terminal and
 take `--yes`; when stdin is **not** a terminal and `--yes` was not given they
 refuse with exit 2 rather than hanging a cron job or proceeding silently.
-`scans run` does not prompt and has no `--yes` at all — passing one is exit 2,
-because a no-op flag here is a flag a script author will assume works on the next
-command too. All four writes take `--dry-run`, which resolves everything, prints
+`scans run` and `annotate` do not prompt and have no `--yes` at all — passing one
+is exit 2, because a no-op flag here is a flag a script author will assume works
+on the next command too. All five writes take `--dry-run`, which resolves everything, prints
 the exact request (method, path, params, body — never a credential) and sends
 nothing.
 
+`annotate` posts a chart marker with source `api`, for a deploy step in CI. On
+this one command `--url` is the release link the marker opens, not the instance:
+give the instance with `TRIPL_BASE_URL`, `--base-url`, or `--url` before the
+command name. The API de-duplicates the same `api` label within 24 hours (manual
+annotations are never de-duplicated) and answers
+200 with the existing marker; `annotate` says so and still exits 0, so a retried
+job is harmless.
+
+`check` validates code against the plan. `.tripl/check.yml` (found at or above
+the current directory, up to the repository root; `--check-config PATH`
+otherwise) names the project and, **per event type**, how its calls look — your
+own wrapper first, SDK presets as shorthands:
+
+```yaml
+project: my-app
+sources: ["Sources/**", "web/src/**"]
+enums: [{file: "Sources/**/Events.swift", languages: [swift]}]
+event_types:
+  se:
+    calls:
+      - function: "Analytics.shared.log"      # or `pattern:` (a regex)
+        args: {category: category, action: action, label: label, properties: properties}
+      - objc_selector: "trackWithCategory:action:label:"
+  page: {preset: snowplow_screen_view}
+  legacy: {calls: [{function: "Analytics.shared.logEvent", name_arg: 0}]}
+```
+
+Presets: `segment_track`, `amplitude_log_event`, `snowplow_structured`,
+`snowplow_screen_view`, `snowplow_self_describing`. Swift, Objective-C, Kotlin,
+Java and TypeScript/JavaScript are read; enum shorthand (`.home`) and qualified
+cases resolve through the enum files, interpolated names become plan variables
+(`"promo_sheet_\(id)_shown"` is `promo_sheet_${id}_shown`), Kotlin/Java
+`.name` / `name()` and Swift `.description` read an enum case's own name, and a
+value only known at runtime is sent as unknown, never as an error (`--strict`
+reports it). `--payloads` validates captured events instead, where a missing
+required field IS an error; a value over the validator's size limits (name 500,
+event type 100, field value 2000 characters, 200 fields) is sent as unknown and
+flagged as an `oversize_value` warning on its line.
+`check` reads nothing but the plan: any member's key works, `tk_r_` included.
+
+`codegen` turns the plan into typed tracking code, from the same
+`.tripl/check.yml`. It generates **per event-type style, never a function per
+event**, and the generated code calls **your own wrapper** (the `transport`) —
+or, with none configured, the shared `TriplDestination` in
+`TriplTransport.swift` / `.kt` / `triplTransport.ts` that you implement once.
+It never imports an SDK.
+
+| `style` | What is generated |
+|---------|-------------------|
+| `structured` | an enum per plan field (its cases are the plan's values; a variable-backed value contributes its allowed values; free text stays `String`), your wrapper's call with its argument types narrowed — `log(category: Category, action: Action, label: String, properties:)` — and a compiler-checked `knownEvents` list |
+| `screen_view` | the same, with `ScreenType` / `ScreenId` enums |
+| `named` | one generic `track(event)`: Swift `enum LegacyEvent { case homeScreenView(HomeScreenView) … }` with `name` and `properties`; Kotlin a sealed interface of data classes/objects; TypeScript `track<K extends LegacyEventName>(name: K, props: LegacyEventProps[K])` |
+| `self_describing` | one data class per schema with its fields, sharing one `track` |
+
+```yaml
+codegen:
+  out: {swift: Sources/Tracking/Generated, kotlin: app/src/main/java/tracking, ts: web/src/tracking}
+  kotlin_package: com.example.tracking
+event_types:
+  se:
+    calls: [{function: "Analytics.shared.log", args: {category: category, action: action, label: label, properties: properties}}]
+    codegen:
+      style: structured              # default: from the preset, else structured when the type has a name rule
+      transport:
+        swift: "Analytics.shared.log"                  # reuses the `calls` entry's args mapping
+        ts: {function: "analytics.log", positional: [category, action, label, properties],
+             import: "import { analytics } from './analytics';"}
+      type_names: {namespace: AppEvents, category: EventCategory, function: log}
+      template: {swift: .tripl/templates/structured.swift.mustache}   # optional override
+  legacy:
+    calls: [{function: "Analytics.shared.logEvent", name_arg: 0, properties_arg: parameters}]
+    codegen: {style: named, languages: [swift, kotlin]}
+```
+
+A `transport` given as a bare function reuses the `args` / `positional` /
+`object_arg` mapping of the `calls` entry with the same `function`. Swift passes
+labelled arguments with their labels, Kotlin as named arguments (give
+`positional` for a Java wrapper), TypeScript positionally — or as one object
+literal with `object_arg`. `type_names` renames `namespace`, `event` (the named
+/ self-describing event type), `function`, and any field's enum by field name.
+
+An event's parameters are the fields it does not fix plus one per `${token}` in
+its name (`promo_sheet_${sheet_id}_shown` takes `sheetId`, typed by the
+variable's allowed values). Plan strings become identifiers by splitting on
+anything that is not a letter or digit and on camelCase: `Home Screen View` ->
+`homeScreenView` (`HOME_SCREEN_VIEW` for Kotlin enum entries), `checkout:start`
+-> `checkoutStart`; a leading digit gets `_` (`_1stRun`), a reserved word a
+trailing `_` (`default_`), a reserved type name `Value` (`TypeValue`), and a
+collision `2`, `3` in sorted order. The raw plan string is always what is sent.
+Deprecated events are marked (`@available(*, deprecated)`, `@Deprecated`,
+`@deprecated`); archived ones are not generated.
+
+A custom `template` uses the built-in one's context (copy it from
+`tripl_cli/codegen/templates/`): a Mustache subset — `{{name}}`, `{{a.b}}`,
+`{{#list}}…{{/list}}`, `{{^empty}}…{{/empty}}`, `{{! comment }}` — where every
+plan string arrives already quoted or escaped for the language, and an unknown
+`{{name}}` is an error rather than an empty string.
+
+Output is deterministic (sorted, no timestamps) with a `Generated by tripl
+codegen — do not edit` header naming the project, branch and the plan's
+content hash (not its revision, so a new revision that changes nothing is not
+drift), so it can be committed: `tripl codegen --check` writes nothing and exits
+1 when a file is missing, differs, or is stale (generated earlier, no longer
+produced — a normal run deletes those, and only files carrying the header for
+the same project, in a language the run writes into that directory). `--model FILE`
+generates from a saved `tripl export --format codegen_model` without an
+instance. `export` writes `bundle.json` and `<event type>/<identity>.schema.json`
+per event (file names sanitised to `[A-Za-z0-9._-]`), or prints the export to
+stdout without `--out`. Both read nothing but the plan: any member's key works.
+
 `drifts reopen` is the one whose prompt is worth reading: reopening clears the
 drift's `resolution_note`, `resolved_by` and `resolved_at`, and dismissing it
 again does not bring them back.
@@ -210,10 +327,15 @@ not moved).
 
 | Exit | Meaning |
 |------|---------|
-| 0 | Every check passed, or only warned and `--strict` was not given. `status`, whenever it completed. `watch`, whenever the run completed — a failed job or a new signal is still 0. The `scans` / `drifts` verbs, whenever every read arrived or the write was accepted (`--dry-run` included). |
+| 0 | Every check passed, or only warned and `--strict` was not given. `status`, whenever it completed. `watch`, whenever the run completed — a failed job or a new signal is still 0. The `scans` / `drifts` verbs and `annotate`, whenever every read arrived or the write was accepted (`--dry-run` included, and a de-duplicated `annotate` too). |
 | 1 | The tool itself broke (doctor turns every API failure into a finding), or any other command could not complete a request — unreachable, or the API refused it. For `watch` this includes a key revoked mid-run. For `scans list` / `drifts list` it includes **any** failed read in the fan-out; for `scans run`, a job returned already `failed`; for `scans cancel` / `drifts dismiss` / `drifts reopen`, a declined prompt. |
-| 2 | Usage or configuration error. For `doctor` and `status` that is resolved before any socket opens; `watch` also refuses after reading the listings, when `--scan` matches nothing or more than 24 scan configs are selected. The `scans` / `drifts` verbs add a bare group, a missing or repeated `--project`, an unresolved or ambiguous `<scan>`, and a prompting write on a non-TTY without `--yes`. Either way **no JSON is emitted** and no write is sent. |
+| 2 | Usage or configuration error. For `doctor` and `status` that is resolved before any socket opens; `watch` also refuses after reading the listings, when `--scan` matches nothing or more than 24 scan configs are selected. The `scans` / `drifts` verbs add a bare group, a missing or repeated `--project`, an unresolved or ambiguous `<scan>`, and a prompting write on a non-TTY without `--yes`; `annotate` adds a `--url` that is not http(s), an `--at` that is not RFC 3339, and half a scope. Either way **no JSON is emitted** and no write is sent. |
 | 3 | `doctor` only: at least one check failed, or `--strict` and at least one warning. Nothing else ever exits 3. |
+
+`check` uses 0, 1 and 2: 1 when any call site or event has an error (or, with
+`--strict`, a warning), and 2 for a bad check config or payload file.
+`codegen` uses them too: 1 for drift under `--check` (or a plan without a
+configured event type), 2 for a bad check config or template.
 | 130 | Interrupted (SIGINT). For `watch` this is the **normal** ending — a run without `--duration` has no other way to stop. |
 
 An unreachable instance therefore exits **3** out of `doctor`, not 1 — it

{tripl-0.2.0 → tripl-0.2.2}/pyproject.toml

@@ -1,10 +1,9 @@
 [project]
 name = "tripl"
-# 0.2.0: `tripl_cli.api` gained the `page_items` / `page_total` re-exports after
-# 0.1.0 shipped, and `tripl-mcp` imports them. The published 0.1.0 does not have
-# them, so tripl-mcp cannot be released against it — this has to go out FIRST
-# (tag `cli-v0.2.0`), then tripl-mcp 0.2.0 (tripl-yh8t).
-version = "0.2.0"
+# 0.2.2: `tripl_cli.api` gained the `docs` module and typed-property reads
+# that tripl-mcp 0.2.2 imports, so this has to reach the index FIRST (tag
+# `cli-v0.2.2`), then tripl-mcp 0.2.2. Versioned with the service release.
+version = "0.2.2"
 description = "Operator CLI for a tripl tracking-plan instance: diagnostics, health and live monitoring"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -91,6 +90,8 @@ build-backend = "hatchling.build"
 # package data already. Verified against a built wheel rather than assumed —
 # `uv build --wheel` then unzip, and both files are there (tripl-ey6j.3). They
 # are read through importlib.resources, which is why this matters at all.
+# The same holds for src/tripl_cli/codegen/templates/*.mustache, the built-in
+# `tripl codegen` templates (#262): package data by the same rule, read the same way.
 packages = ["src/tripl_cli"]
 
 [tool.pytest.ini_options]

{tripl-0.2.0 → tripl-0.2.2}/src/tripl_cli/api/__init__.py

@@ -46,10 +46,14 @@ from __future__ import annotations
 from tripl_cli.api import (
     auth,
     branches,
+    chart_annotations,
     data_sources,
+    docs,
     event_types,
     events,
     monitoring,
+    plan_export,
+    plan_validation,
     projects,
     scans,
     search,
@@ -65,12 +69,16 @@ __all__ = [
     "ApiRequest",
     "auth",
     "branches",
+    "chart_annotations",
     "data_sources",
+    "docs",
     "event_types",
     "events",
     "monitoring",
     "page_items",
     "page_total",
+    "plan_export",
+    "plan_validation",
     "projects",
     "scans",
     "search",

{tripl-0.2.0 → tripl-0.2.2}/src/tripl_cli/api/branches.py

@@ -5,12 +5,13 @@ back to a human in the tripl UI (see ``tripl_mcp.tools.branches``). A builder
 would be the first half of shipping them.
 
 Note how the OTHER builders spell "the live plan": by leaving ``branch`` unset.
-``deps.get_branch_id_override`` reads the RAW query string, resolves main
-whenever ``?branch=`` is missing or empty, and refuses anything that is not a
-UUID belonging to this project (400) or names no branch of it (404). So there is
-no literal for main, here or anywhere — which is also why ``?branch=`` is absent
-from ``backend/openapi.json``: it is a dependency rather than a declared query
-parameter, and the contract test therefore cannot see it.
+``deps.get_branch_id_override`` resolves main whenever ``?branch=`` is missing or
+empty, and refuses anything that is not a UUID belonging to this project (400) or
+names no branch of it (404). So there is no literal for main, here or anywhere.
+It IS a declared query parameter, so ``backend/openapi.json`` carries it and the
+contract test can see it — typed ``str`` rather than ``format: uuid`` because the
+dependency parses the value itself, which is what keeps a malformed id a 400
+instead of FastAPI's own 422.
 """
 
 from __future__ import annotations
@@ -31,8 +32,9 @@ ENDPOINTS: tuple[tuple[str, str], ...] = (
 def list_branches(slug: str, *, include_diff_counts: bool = False) -> ApiRequest:
     """Answers ``{items, total}``, not a bare list.
 
-    ``include_diff_counts`` fills ``ahead`` and ``behind_base``; without it the
-    service leaves both null, because each row costs a snapshot comparison. Off
+    ``include_diff_counts`` fills ``ahead`` and ``behind_base`` on open branches
+    (merged and closed ones, like main, stay null); without it the service
+    leaves both null everywhere, because each row costs a snapshot comparison. Off
     by default for that reason, and asked for in exactly one place: ``tripl plan
     branches``, where those two columns are the reason to run the command at
     all. The branch RESOLUTION path must keep the default — it needs only id and

tripl-0.2.2/src/tripl_cli/api/chart_annotations.py

@@ -0,0 +1,73 @@
+"""Chart annotations: the markers charts draw at a point in time.
+
+Only the create route has a builder. ``tripl annotate`` is the one caller, and it
+exists for CI: a deploy step posts "Deployed web 2026.09.25" with a link to the
+release, and every monitoring (Volume tab) chart in the project shows it.
+
+The route answers **201** for a new row and **200** when it de-duplicated: the
+same label posted with source ``api`` to the same project within the last 24
+hours returns the row that already exists instead of creating a second one.
+Only ``api`` is de-duplicated here (``release`` is unique per label forever, and
+is worker-only); ``manual`` creates are never de-duplicated and always 201. A retried CI job is
+therefore safe to re-run, and the status code is the only way to tell the two
+answers apart - the bodies have the same shape.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from tripl_cli.api.request import ApiRequest
+from tripl_cli.model import JsonDict, to_rfc3339
+
+CREATE = "/projects/{slug}/annotations"
+
+ENDPOINTS: tuple[tuple[str, str], ...] = (("post", CREATE),)
+
+# `ChartAnnotationScopeType` verbatim. A scoped annotation only shows on charts
+# of that scope; a project-level one (no scope) shows on every monitoring
+# (Volume tab) chart in the project.
+SCOPE_TYPES: tuple[str, ...] = ("project_total", "event_type", "event", "metric")
+
+# What a client may send as `source`. `manual` is the app's own default and
+# `release` is reserved to the metrics worker (the API answers 422), so the CLI
+# always sends `api`.
+SOURCE_API = "api"
+
+# `ChartAnnotationCreate`'s own bounds, so a typo costs no request.
+LABEL_MAX_LENGTH = 200
+DESCRIPTION_MAX_LENGTH = 2000
+SCOPE_REF_MAX_LENGTH = 120
+URL_MAX_LENGTH = 500
+
+# 201 is a new annotation; 200 is the one that already existed.
+STATUS_CREATED = 201
+STATUS_DEDUPLICATED = 200
+
+
+def create_annotation(
+    slug: str,
+    *,
+    label: str,
+    at: datetime,
+    url: str | None = None,
+    description: str | None = None,
+    scope_type: str | None = None,
+    scope_ref: str | None = None,
+) -> ApiRequest:
+    """``POST /projects/{slug}/annotations`` with ``source="api"``.
+
+    Editor-gated: a ``tk_w_`` key backed by an editor or owner. ``bucket`` is the
+    route's name for the timestamp. Unset members are omitted rather than sent
+    as null, so the server's defaults (the colour among them) apply.
+    """
+    body: JsonDict = {"label": label, "bucket": to_rfc3339(at), "source": SOURCE_API}
+    if url is not None:
+        body["url"] = url
+    if description is not None:
+        body["description"] = description
+    if scope_type is not None:
+        body["scope_type"] = scope_type
+    if scope_ref is not None:
+        body["scope_ref"] = scope_ref
+    return ApiRequest("POST", CREATE.format(slug=slug), json_body=body)