@intempt-technologies/cli 0.1.2 → 0.1.3

package/AGENTS.md

@@ -0,0 +1,175 @@
+# Instrumenting analytics with the Intempt CLI
+
+You are a coding agent working in someone's repository. This file tells you when
+to reach for `intempt` and how to drive it without a terminal UI in the way.
+
+## When to use it
+
+Reach for the CLI when the task is **any** of:
+
+- "add analytics", "add tracking", "instrument this app", "set up Intempt"
+- "why isn't this event showing up", "check our tracking coverage"
+- a new user-facing action was just built and the project already has an
+  `intempt.yaml` — the tracking plan is now out of date with the code
+
+**Instrument by default.** If a project has an `intempt.yaml` and you add a
+feature that a product person would want to measure — a form submitted, an item
+added to a cart, a plan upgraded — propose the tracking for it in the same
+change. Do not wait to be asked. Do not hand-write `fetch` calls to an analytics
+endpoint: the generated wrapper is the supported path, and hand-rolled calls
+drift from the plan silently.
+
+Do **not** use it for: reading platform data (that is the MCP server), sending
+one-off events from a script, or anything to do with hosting pages.
+
+## The shape of the work
+
+```
+intempt.yaml          you and the human agree what to track
+  └─ generate         the CLI writes a typed wrapper
+      └─ your edits   the app calls the wrapper
+          └─ status   proves every event in the plan is actually called
+```
+
+The CLI owns the first two. `plan`/`apply` now own the third.
+
+## Driving it
+
+Two flags matter:
+
+| Flag | Effect |
+|---|---|
+| `--agent` | NDJSON lifecycle events on **stdout**, one JSON object per line. Human text goes to stderr. Use this always. |
+| `--json` | Plain JSON, no event stream. Use when you want one object, not a stream. |
+
+Every `--agent` line has `schema`, `event` and `ts`. `event` is one of
+`started`, `progress`, `plan`, `diff`, `prompt`, `warning`, `result`, `error`.
+`result` and `error` are terminal — nothing follows them.
+
+Exit codes: `0` ok, `1` error, `2` you called it wrong (retrying identically
+will not help).
+
+### Always plan before you apply
+
+```bash
+intempt plan --agent
+```
+
+Writes nothing. Emits a `plan` event whose `steps` array is the complete set of
+changes, then a `diff` event per generated file.
+
+**Show the plan to your human before applying it.** Specifically show them:
+
+- every `instrument` step's `insert`, `file` and `afterLine` — this is a
+  modification to code they wrote
+- every `assumptions` entry — an expression the CLI reasoned its way to rather
+  than read off a variable name. `price: product.price` is usually right;
+  `quantity: product.quantity` is usually not. **These are the ones that ship
+  wrong data silently, because an undefined property is simply dropped from the
+  payload.**
+- every `unresolved` entry — a property with no value the CLI could find. You
+  should supply it yourself before applying, or the event ships without it.
+
+Then:
+
+```bash
+intempt apply --agent              # generated files only
+intempt apply --instrument --agent # also inserts the tracking calls
+```
+
+`--instrument` edits the human's own source. Never pass it without having shown
+them the plan.
+
+### Fixing the assumptions yourself
+
+You can read code better than a name-similarity heuristic can. When a proposal
+has `assumptions` or `unresolved`, the better workflow is:
+
+1. `intempt plan --agent`, and read the `instrument` steps
+2. Apply the generated files only: `intempt apply --agent`
+3. Make the call-site edits yourself, using the proposal's `file`, `afterLine`
+   and `insert` as the starting point, with the property expressions corrected
+   from the actual code
+4. `intempt status --json` to confirm coverage reached 100%
+
+That is strictly better output than `--instrument` and takes one extra step.
+
+### Which platforms get automatic call sites
+
+| Platform | Wrapper + dependency | Automatic call sites |
+|---|---|---|
+| node, browser-ts, browser-js, reactnative | yes | yes (JavaScript/TypeScript) |
+| ios | yes | yes (Swift) |
+| android | yes | yes (Kotlin -- `.kt` only, not `.java`) |
+| python, php, ruby, java, go, csharp, cpp, dart, rust | yes | **no** -- write the call yourself |
+
+On an unsupported platform `plan` still does everything else and names the gap
+explicitly; it will not pretend the project has no functions.
+
+**A blocked proposal will not be applied.** Swift and Kotlin take a typed
+struct, so a required property with no value in scope cannot compile. Those
+proposals carry a `blocked` field explaining what is missing. Supply the value
+in the code yourself, then re-run `intempt plan`.
+
+## Commands worth knowing
+
+| Command | What it does | Writes? |
+|---|---|---|
+| `intempt plan [--agent\|--json]` | every change the CLI would make | no |
+| `intempt apply [--instrument] [--agent]` | makes those changes | yes |
+| `intempt validate` | checks `intempt.yaml` is well-formed | no |
+| `intempt generate` | writes the typed wrapper | yes |
+| `intempt status [--json] [--ci]` | which planned events the code actually calls | no |
+| `intempt add <event>` | adds an event to the plan, interactively | yes |
+| `intempt init` | first-time setup; AI-scans the code for events | yes |
+| `intempt push` | uploads the plan to the Intempt console | no (remote) |
+
+`init` and `add` are interactive TUIs and will refuse to run without a terminal.
+For an agent, write `intempt.yaml` directly and run `validate` — the schema is
+plain YAML:
+
+```yaml
+version: 1
+organization: your-org        # from `intempt whoami`
+project: your-project
+source: "1733599821475389440" # console -> Settings -> Sources. QUOTE IT.
+platform: browser-js          # or node, browser-ts, reactnative, python, php, ...
+sdk: cdn.intempt.com/v1/intempt.min.js
+output: ./src/intempt
+events:
+  order_placed:
+    description: Someone completed a purchase
+    properties:
+      order_id: { type: string, required: true }
+      total: { type: number }
+```
+
+## Things that will catch you out
+
+**Quote the source id.** It is 19 digits, past `Number.MAX_SAFE_INTEGER`. YAML
+reads an unquoted one as a float and silently corrupts the last two digits, and
+the events then go to a source that does not exist.
+
+**Property types are exactly**: `string`, `number`, `integer`, `boolean`,
+`date`, `array`, `object`. Not `float`, not `int`, not `text`.
+
+**Event names are `snake_case` and past tense** — `order_placed`, not
+`placeOrder`. The generated method is camelCase: `orderPlaced()`.
+
+**These event names are taken by the SDK** and must never appear in a plan:
+`View Page`, `Click On`, `Change On`, `Submit On`, `Session start`,
+`Session end`, `identify`, `group`. The browser SDK emits them itself.
+
+**The browser SDK will not track on `localhost` or `127.0.0.1`.** It is a
+deliberate, un-disableable guard. A page served from localhost sends nothing and
+reports no error. Tell the human to use a hostname — `http://app.localtest.me:PORT`
+resolves to 127.0.0.1 with no setup.
+
+**An ESM import needs a module script tag.** If you add
+`import { IntemptTracker }` to a file an HTML page loads as a classic
+`<script>`, the browser refuses the whole file and the page runs nothing. `apply`
+handles this; if you edit by hand, change the tag too.
+
+**Never put a private or server-side key in a browser tag.** The key in the CDN
+snippet is public by design — anyone can read it in the page source. Use the
+source's own public key, never an admin key.