@latitude-data/openclaw-telemetry-cli 0.0.7

package/LICENSE

@@ -0,0 +1,157 @@
+# GNU LESSER GENERAL PUBLIC LICENSE
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc.
+<https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates the
+terms and conditions of version 3 of the GNU General Public License,
+supplemented by the additional permissions listed below.
+
+## 0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the
+GNU General Public License.
+
+"The Library" refers to a covered work governed by this License, other
+than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library. The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+## 1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+## 2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+-   a) under this License, provided that you make a good faith effort
+    to ensure that, in the event an Application does not supply the
+    function or data, the facility still operates, and performs
+    whatever part of its purpose remains meaningful, or
+-   b) under the GNU GPL, with none of the additional permissions of
+    this License applicable to that copy.
+
+## 3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from a
+header file that is part of the Library. You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+-   a) Give prominent notice with each copy of the object code that
+    the Library is used in it and that the Library and its use are
+    covered by this License.
+-   b) Accompany the object code with a copy of the GNU GPL and this
+    license document.
+
+## 4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that, taken
+together, effectively do not restrict modification of the portions of
+the Library contained in the Combined Work and reverse engineering for
+debugging such modifications, if you also do each of the following:
+
+-   a) Give prominent notice with each copy of the Combined Work that
+    the Library is used in it and that the Library and its use are
+    covered by this License.
+-   b) Accompany the Combined Work with a copy of the GNU GPL and this
+    license document.
+-   c) For a Combined Work that displays copyright notices during
+    execution, include the copyright notice for the Library among
+    these notices, as well as a reference directing the user to the
+    copies of the GNU GPL and this license document.
+-   d) Do one of the following:
+    -   0) Convey the Minimal Corresponding Source under the terms of
+        this License, and the Corresponding Application Code in a form
+        suitable for, and under terms that permit, the user to
+        recombine or relink the Application with a modified version of
+        the Linked Version to produce a modified Combined Work, in the
+        manner specified by section 6 of the GNU GPL for conveying
+        Corresponding Source.
+    -   1) Use a suitable shared library mechanism for linking with
+        the Library. A suitable mechanism is one that (a) uses at run
+        time a copy of the Library already present on the user's
+        computer system, and (b) will operate properly with a modified
+        version of the Library that is interface-compatible with the
+        Linked Version.
+-   e) Provide Installation Information, but only if you would
+    otherwise be required to provide such information under section 6
+    of the GNU GPL, and only to the extent that such information is
+    necessary to install and execute a modified version of the
+    Combined Work produced by recombining or relinking the Application
+    with a modified version of the Linked Version. (If you use option
+    4d0, the Installation Information must accompany the Minimal
+    Corresponding Source and Corresponding Application Code. If you
+    use option 4d1, you must provide the Installation Information in
+    the manner specified by section 6 of the GNU GPL for conveying
+    Corresponding Source.)
+
+## 5. Combined Libraries.
+
+You may place library facilities that are a work based on the Library
+side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+-   a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities, conveyed under the terms of this License.
+-   b) Give prominent notice with the combined library that part of it
+    is a work based on the Library, and explaining where to find the
+    accompanying uncombined form of the same work.
+
+## 6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library
+as you received it specifies that a certain numbered version of the
+GNU Lesser General Public License "or any later version" applies to
+it, you have the option of following the terms and conditions either
+of that published version or of any later version published by the
+Free Software Foundation. If the Library as you received it does not
+specify a version number of the GNU Lesser General Public License, you
+may choose any version of the GNU Lesser General Public License ever
+published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,149 @@
+# @latitude-data/openclaw-telemetry-cli
+
+One-shot installer for the [`@latitude-data/openclaw-telemetry`](https://github.com/latitude-dev/latitude-llm/tree/main/packages/telemetry/openclaw#readme) OpenClaw plugin. Wraps `openclaw plugins install` + the manual `openclaw config set` flow into a single `npx -y` command, with TTY prompts, CI flags, dry-run, custom config dir, upgrade detection, and the gateway restart.
+
+For details on the plugin runtime itself — what it sends, the span tree, and the manual install flow — see the [runtime README](https://github.com/latitude-dev/latitude-llm/tree/main/packages/telemetry/openclaw#readme).
+
+## Requirements
+
+- **OpenClaw 2026.4.25 or newer** on PATH.
+- A **Latitude API key** and **project slug** — both from [console.latitude.so/settings/api-keys](https://console.latitude.so/settings/api-keys).
+
+## Install
+
+Interactive (recommended for first-time setup):
+
+```bash
+npx -y @latitude-data/openclaw-telemetry-cli@0.0.7 install
+```
+
+The CLI prompts for your API key and project slug, installs the plugin, writes the config, validates it, and offers to restart the gateway.
+
+Non-interactive / CI:
+
+```bash
+npx -y @latitude-data/openclaw-telemetry-cli@0.0.7 install \
+  --api-key="$LATITUDE_API_KEY" \
+  --project=my-project \
+  --yes \
+  --no-restart
+```
+
+`--yes` skips all prompts (required when you can't type into a TTY); `--no-restart` keeps the gateway running so you can finish other config first.
+
+## What the CLI does
+
+In order, on every install:
+
+1. **Verifies your OpenClaw version** (`openclaw --version` ≥ 2026.4.25). Aborts with an upgrade message on older versions.
+2. **Verifies the runtime contract** — that `@latitude-data/openclaw-telemetry@0.0.7` exists on npm. (Catches half-published releases.)
+3. **Detects any prior install** via `<configDir>/plugins/installs.json`. Renders `Upgrading 0.0.6 → 0.0.7` (or `Re-applying 0.0.7 (idempotent)`) if found.
+4. **Prompts for your API key and project slug** — interactive only; flags / `--yes` skip the prompts.
+5. **Backs up `openclaw.json`** to `openclaw.json.latitude-bak` before any change.
+6. **Runs `openclaw plugins install @latitude-data/openclaw-telemetry@0.0.7 --force`** — npm fetch, security scan, extension placement, install record, disabled `plugins.entries[id]`.
+7. **Writes the plugin config** atomically (temp + rename): `apiKey`, `project`, `baseUrl` (only if `--staging` / `--dev`), `config.allowConversationAccess` AND `hooks.allowConversationAccess` (always coupled — both `true` by default; `--no-content` to emit structural-only telemetry).
+8. **Adds the plugin id to `plugins.allow`** to silence OpenClaw's "untracked code" warning. Pass `--no-trust` to opt out.
+9. **Validates** the result with `openclaw config validate --json`. If it fails, restores the backup and aborts with the validator's message.
+10. **Restarts the gateway**. Default: prompts on TTY, skips non-TTY (with manual instructions). `--restart` always restarts; `--no-restart` always skips.
+
+## Flags
+
+| Flag | Effect |
+| --- | --- |
+| `--api-key=<key>` | Pass the API key non-interactively. |
+| `--project=<slug>` | Pass the project slug non-interactively. |
+| `--staging` | Target `https://staging.latitude.so` / `https://staging-ingest.latitude.so`. |
+| `--dev` | Target `http://localhost:3000` / `http://localhost:3002`. |
+| `--no-content` | Disable conversation capture (still emits structural-only telemetry — timing, tokens, ids). Mirrored into both `config.allowConversationAccess` and `hooks.allowConversationAccess`. |
+| `--allow-conversation` | Force conversation capture on (overrides existing config). |
+| `--no-trust` | Skip auto-adding the plugin id to `plugins.allow`. |
+| `--openclaw-dir=<path>` | Override the OpenClaw config directory. See [Custom config directory](#custom-config-directory). |
+| `--dry-run` | Preview every change without touching the filesystem or spawning subprocesses. See [Dry run](#dry-run). |
+| `--restart` | Always restart the gateway, even non-TTY. CI escape hatch for "do everything". |
+| `--no-restart` | Never restart the gateway, even on TTY. Always wins over `--restart`. |
+| `--yes` / `--no-prompt` | Skip all prompts. Required when running non-TTY without supplying `--api-key` / `--project`. |
+| `--version`, `-v` | Print the CLI version and exit. |
+| `--help`, `-h` | Print usage. |
+
+## Modes
+
+### Dry run
+
+Preview every change without touching the filesystem or spawning subprocesses:
+
+```bash
+npx -y @latitude-data/openclaw-telemetry-cli@0.0.7 install --dry-run \
+  --api-key=lat_xxx --project=my-project
+```
+
+Output includes the resolved config dir, the exact `openclaw plugins install` command we'd spawn, and a unified-ish JSON diff between the current `openclaw.json` and the proposed result. Useful for reviewing changes before applying them, or for verifying flag behaviour in CI.
+
+### Custom config directory
+
+The CLI resolves the OpenClaw config directory in this order, stopping at the first match:
+
+1. **`--openclaw-dir=<path>`** flag (absolute, or relative to cwd; the space-separated form `--openclaw-dir <path>` works too).
+2. **`OPENCLAW_HOME`** env var (absolute, or relative to cwd).
+3. **`./openclaw.json`** in the current working directory → use cwd.
+4. **`~/.openclaw`** (default).
+
+The resolved path is printed at install start. The CLI passes `OPENCLAW_HOME=<resolved>` to every spawned `openclaw` subprocess, so the runtime side picks up the same dir.
+
+> **Caveat.** OpenClaw's CLI may not honor `OPENCLAW_HOME` directly. When that happens, the runtime side may write the install record into `~/.openclaw/`, while we write `openclaw.json` to the custom dir. The post-install `openclaw config validate --json` step catches this — validation fails because the entry is in a different file from the install record, the backup is restored, and the CLI aborts with both paths in the error. **No silent two-place writes.**
+
+### Structural-only telemetry
+
+```bash
+npx -y @latitude-data/openclaw-telemetry-cli@0.0.7 install --no-content \
+  --api-key=lat_xxx --project=my-project
+```
+
+The plugin still emits the full span tree — timings, token usage, model name, agent name, ids — just with content attributes (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`, tool args/results) scrubbed. Each span carries `latitude.captured.content: false` so the gate state is visible in the Latitude UI.
+
+### Targeting staging or local dev
+
+```bash
+# Staging
+npx -y @latitude-data/openclaw-telemetry-cli@0.0.7 install --staging --yes \
+  --api-key=lat_xxx --project=my-project
+
+# Local dev
+npx -y @latitude-data/openclaw-telemetry-cli@0.0.7 install --dev --yes \
+  --api-key=lat_xxx --project=my-project
+```
+
+`--staging` writes `baseUrl: https://staging-ingest.latitude.so`; `--dev` writes `baseUrl: http://localhost:3002`. Without either flag, the runtime defaults to production (`https://ingest.latitude.so`).
+
+## Uninstall
+
+```bash
+npx -y @latitude-data/openclaw-telemetry-cli@0.0.7 uninstall
+```
+
+The uninstall flow:
+
+1. Confirms with the operator (TTY only — pass `--yes` to skip).
+2. Backs up `openclaw.json` to `openclaw.json.latitude-bak`.
+3. Runs `openclaw plugins uninstall @latitude-data/openclaw-telemetry --force`. OpenClaw removes the extension files, the install record, `plugins.entries[id]`, and the `plugins.allow` entry.
+4. Defensive cleanup of any lingering state in `openclaw.json` (idempotent — safe to re-run).
+5. Restart prompt (same TTY-vs-CI logic as install; `--restart` / `--no-restart` override).
+
+The backup at `openclaw.json.latitude-bak` is kept after uninstall — delete it manually when you don't need it anymore.
+
+## Lockstep policy
+
+This CLI installs **exactly** `@latitude-data/openclaw-telemetry@0.0.7` (pinned in source as `RUNTIME_VERSION`). Every CLI release is paired with a runtime release of the same version number; bumping the runtime requires bumping the CLI in the same commit and re-publishing both.
+
+If npm doesn't have the exact pinned version (half-published release), the CLI aborts with `Upgrade the CLI: npm install -g @latitude-data/openclaw-telemetry-cli@latest`.
+
+Pinning to an exact version also satisfies OpenClaw's `Pin install specs to exact versions` supply-chain audit warning automatically.
+
+## Why this is a separate package
+
+OpenClaw 2026.4.25+ runs an install-time security scan on `openclaw plugins install` (`plugins.code_safety`, looking for `dangerous-exec` / `env-harvesting` patterns). This CLI uses `child_process.spawn` to invoke OpenClaw — a `dangerous-exec` flag. Keeping the CLI in a **separate npm package** that's installed via `npx` / `npm install -g` rather than `openclaw plugins install` means the CLI never goes through OpenClaw's scanner. The runtime plugin ([`@latitude-data/openclaw-telemetry`](https://github.com/latitude-dev/latitude-llm/tree/main/packages/telemetry/openclaw)) is installed by this CLI on the operator's behalf and is itself scanner-clean (no `child_process`, no `node:fs` runtime reads).
+
+See the [runtime CHANGELOG](https://github.com/latitude-dev/latitude-llm/blob/main/packages/telemetry/openclaw/CHANGELOG.md) for the wider history of the split.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };