kanon-cli 3.2.0__tar.gz → 3.3.0__tar.gz

{kanon_cli-3.2.0 → kanon_cli-3.3.0}/CHANGELOG.md

@@ -2,8 +2,111 @@
 
 
 
+## v3.3.0 (2026-07-17)
+
+### Feature
+
+* feat: kanon list command + usage telemetry, full install-graph capture, and update-warning enhancement (#91)
+
+* feat: add usage telemetry, full install-graph capture, and update-warning enhancement
+
+Emit one structured usage-telemetry event per CLI command to the Caylent
+collector, fully capturing what was installed (every direct source plus every
+transitive repo package with URLs and resolved content SHAs), and enhance the
+"update available" warning.
+
+Telemetry (new core/telemetry.py):
+- Hooked via try/finally around dispatch in cli.py; captures command, subcommand,
+  boolean flag names, allowlisted flag values, outcome (exit code/status/error
+  class/duration), runtime environment, and credential-stripped git provenance.
+- OTLP/HTTP logs JSON with one log record whose body is a flat
+  {tool,timestamp,event_type,payload} object (payload a JSON string); POSTed via
+  stdlib urllib in a detached, non-blocking, silent, never-fail background
+  process (utils/spawn.spawn_detached), HTTPS-only guard, timeouts + body cap.
+- Auto opted-in by default; the only opt-out is KANON_TELEMETRY_DISABLED (no
+  --no-telemetry flag). KANON_TELEMETRY_ENDPOINT / --telemetry-endpoint and
+  KANON_TELEMETRY_DEBUG / --telemetry-debug are supported.
+- Zero-secret allowlist: never raw argv, keys, tokens, credentials, env-var
+  values, or file contents; every URL is credential-stripped.
+
+Full install-graph capture (core/install.py):
+- Populate SourceEntry.projects on install by resolving project -> remote -> URL
+  from the already-synced manifests (walk_includes_collecting_remotes +
+  join_project_repo_url + canonicalize_repo_url) joined with the captured content
+  pins. This also fixes `kanon why` showing an empty project layer on
+  install-written lockfiles. Telemetry emits payload.install_graph and a
+  flattened payload.installed_packages[] (direct + transitive), capped under the
+  collector body limit with install_graph_truncated on overflow.
+
+Update-warning enhancement (core/update_check.py):
+- Yellow banner with the current version in red and the latest in green; a red
+  "no internet access -- could not check for updates" notice on a failed fetch,
+  shown at most once per window; default KANON_UPDATE_CHECK_TTL lowered to 3h.
+
+Docs: new docs/privacy.md (collected fields, encryption, opt-out) linked from
+README; telemetry rows in docs/cli-reference.md and docs/configuration.md;
+regenerated help + completion snapshots.
+
+* test: include telemetry global flags in bash completion expectation
+
+The new --telemetry-debug / --telemetry-endpoint global flags now appear in the
+top-level bash completion, so the exact-match global_flags row in
+test_completion_bash.py is extended to include them.
+
+* test: use provider-neutral remote name in build_project_entries fixture
+
+The provider-agnostic host gate forbids the bare token 'gh'; rename the fixture
+manifest remote from 'gh' to 'origin' so the manifest XML fixtures carry no
+provider-specific reference.
+
+* fix: record real command outcome in telemetry and emit for --version/--help/bare invocations
+
+* feat: add kanon list command (declared vs installed source inventory)
+
+Add `kanon list`, the flat inventory command that reconciles the sources
+declared in .kanon against those installed in .kanon.lock and tags each one
+installed / not-installed / orphan -- the kanon analogue of `pip list` /
+`npm ls` / `poetry show`.
+
+Flags: --declared, --tree, --status <installed|not-installed|orphan>,
+--format <table|json>, --kanon-file, --lock-file. Every failure path yields a
+clean single-prefixed ERROR (no traceback). The command emits usage telemetry
+like every other command (command=list, --tree flag, --format/--status values
+via the flag-value allowlist).
+
+The declared-vs-installed partition reuses a new non-raising
+reconcile_declared_installed() extracted from check_lockfile_consistency (one
+source of truth). Covered by unit/functional/integration/scenario tests plus a
+real-git add->install->edit->list journey; list.py at 100% coverage. Help and
+shell-completion snapshots and docs updated.
+
+The 3.0.0 list->search rename left guards asserting `list` is an unknown
+command; those are updated to reflect `list` now being a distinct command.
+
+* test: isolate test subprocesses from coverage subprocess measurement
+
+Under `pytest --cov` (make test) pytest-cov and coverage export COV_CORE_* /
+COVERAGE_PROCESS_* so spawned subprocesses auto-start coverage. A measured
+`kanon` subprocess then writes a .coverage-data directory into its working
+directory -- resolved relative to the child CWD on some filesystems -- which
+behavioural subprocess tests that inspect the child filesystem
+(`kanon repo status --orphans`) or parse its stderr (`--telemetry-debug` JSON)
+then trip over, non-deterministically across OS / filesystem.
+
+Strip the coverage subprocess-trigger variables from the child environment in
+the functional and scenario subprocess runners and the telemetry-journey env
+builder via a shared strip_subprocess_coverage_env helper. Behavioural CLI
+subprocess tests do not need coverage of the child; the 90% coverage gate is
+measured in-process on the unit tier, which uses its own runner and is
+unaffected. ([`57246f8`](https://github.com/caylent-solutions/kanon/commit/57246f8a8a46b99ad2b35a954289d7a9e7d1966c))
+
+
 ## v3.2.0 (2026-07-13)
 
+### Chore
+
+* chore(release): 3.2.0 ([`b503e3c`](https://github.com/caylent-solutions/kanon/commit/b503e3cf92479b6192b186ad6b2481563c916074))
+
 ### Feature
 
 * feat(clean): ~/.kanon-home store rename, .kanon-dir guard, --purge/--purge-all (store-only teardown with no .kanon), no unconditional .gitignore (#89)
@@ -85,6 +188,12 @@ lifecycle also documents clean --purge-all running without a .kanon.
 
 Co-authored-by: t <t@e.x> ([`d9b0ad1`](https://github.com/caylent-solutions/kanon/commit/d9b0ad1856ab58487b7ed3efdc3ff9d87b60b193))
 
+### Unknown
+
+* Merge pull request #90 from caylent-solutions/release-3.2.0
+
+Release 3.2.0 ([`fb944e2`](https://github.com/caylent-solutions/kanon/commit/fb944e251cf650020070e29cb28a26cbffc886da))
+
 
 ## v3.1.1 (2026-06-27)
 

{kanon_cli-3.2.0 → kanon_cli-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanon-cli
-Version: 3.2.0
+Version: 3.3.0
 Summary: Kanon (Kanon Package Manager) CLI tool
 Project-URL: Homepage, https://github.com/caylent-solutions/kanon
 Project-URL: Issues, https://github.com/caylent-solutions/kanon/issues
@@ -55,6 +55,7 @@ via declarative manifests.
   - [kanon remove](#kanon-remove)
   - [kanon install](#kanon-install)
   - [kanon clean](#kanon-clean)
+  - [kanon list](#kanon-list)
   - [kanon outdated](#kanon-outdated)
   - [kanon why](#kanon-why)
   - [kanon doctor](#kanon-doctor)
@@ -208,6 +209,7 @@ persistent installation and advanced options, see
 | `kanon search` | List packages available in a catalog or show detail for one | [docs/list-and-add.md](docs/list-and-add.md) |
 | `kanon add` | Add a package (with optional version constraint) to `.kanon` | [docs/list-and-add.md](docs/list-and-add.md) |
 | `kanon remove` | Remove a package from `.kanon` | [docs/list-and-add.md](docs/list-and-add.md) |
+| `kanon list` | List sources declared in `.kanon` vs installed in `.kanon.lock` (installed / not-installed / orphan) | [docs/cli-reference.md](docs/cli-reference.md#kanon-list) |
 | `kanon outdated` | Show packages in `.kanon` that have newer versions available | [docs/outdated-and-why.md](docs/outdated-and-why.md) |
 | `kanon why` | Explain why a specific package version was resolved | [docs/outdated-and-why.md](docs/outdated-and-why.md) |
 | `kanon install` | Resolve, clone, and symlink all packages; writes `.kanon.lock` | [docs/lockfile.md](docs/lockfile.md) |
@@ -593,6 +595,26 @@ store directory (default `~/.kanon-home`), removing only kanon-owned content
 (`store/`, `cache/`, and the emptied root) and refusing unsafe `KANON_HOME`
 paths such as your home directory or the filesystem root.
 
+### kanon list
+
+Lists the sources declared in `.kanon` against those installed in `.kanon.lock`,
+tagging each `installed`, `not-installed`, or `orphan` -- the kanon analogue of
+`pip list` / `npm ls`.
+
+```bash
+kanon list                        # every source, declared vs installed, tagged
+kanon list --declared             # only sources declared in .kanon (no orphans)
+kanon list --status orphan        # only sources in the lock no longer declared
+kanon list --tree                 # expand installed sources to transitive packages
+kanon list --format json          # machine-readable JSON
+```
+
+A source is `installed` when it is in both files, `not-installed` when declared
+but not yet locked (run `kanon install`), and `orphan` when locked but no longer
+declared. Key options: `--declared`, `--tree`, `--status {installed,not-installed,orphan}`,
+`--format {table,json}`, `--kanon-file`, `--lock-file`. See
+[docs/cli-reference.md](docs/cli-reference.md#kanon-list).
+
 ### kanon outdated
 
 Compares each source in `.kanon` against the catalog and emits a table of
@@ -1483,6 +1505,23 @@ version bumps.
   supported; see [Platform support](#platform-support) and use WSL2)
 - [Contributing](CONTRIBUTING.md) -- How to create and maintain Kanon
   packages and marketplaces
+- [Privacy & Telemetry](docs/privacy.md) -- What usage telemetry kanon
+  collects, why, how it is encrypted, and how to turn it off
+
+---
+
+## Usage telemetry
+
+kanon emits one anonymised-by-design usage event per command to help the
+maintainers understand which commands and package sources are used. Telemetry
+is **on by default**, runs **silently** and **non-blocking**, never blocks or
+fails your command, and serialises only an explicit allowlist of kanon-computed
+fields -- never raw argv, credentials, keys, tokens, env-var values, or file
+contents (every URL is credential-stripped before it is sent).
+
+Disable it entirely by setting `KANON_TELEMETRY_DISABLED=1`. See
+[docs/privacy.md](docs/privacy.md) for the full list of collected fields and the
+transit/at-rest encryption.
 
 ---
 

{kanon_cli-3.2.0 → kanon_cli-3.3.0}/README.md

@@ -33,6 +33,7 @@ via declarative manifests.
   - [kanon remove](#kanon-remove)
   - [kanon install](#kanon-install)
   - [kanon clean](#kanon-clean)
+  - [kanon list](#kanon-list)
   - [kanon outdated](#kanon-outdated)
   - [kanon why](#kanon-why)
   - [kanon doctor](#kanon-doctor)
@@ -186,6 +187,7 @@ persistent installation and advanced options, see
 | `kanon search` | List packages available in a catalog or show detail for one | [docs/list-and-add.md](docs/list-and-add.md) |
 | `kanon add` | Add a package (with optional version constraint) to `.kanon` | [docs/list-and-add.md](docs/list-and-add.md) |
 | `kanon remove` | Remove a package from `.kanon` | [docs/list-and-add.md](docs/list-and-add.md) |
+| `kanon list` | List sources declared in `.kanon` vs installed in `.kanon.lock` (installed / not-installed / orphan) | [docs/cli-reference.md](docs/cli-reference.md#kanon-list) |
 | `kanon outdated` | Show packages in `.kanon` that have newer versions available | [docs/outdated-and-why.md](docs/outdated-and-why.md) |
 | `kanon why` | Explain why a specific package version was resolved | [docs/outdated-and-why.md](docs/outdated-and-why.md) |
 | `kanon install` | Resolve, clone, and symlink all packages; writes `.kanon.lock` | [docs/lockfile.md](docs/lockfile.md) |
@@ -571,6 +573,26 @@ store directory (default `~/.kanon-home`), removing only kanon-owned content
 (`store/`, `cache/`, and the emptied root) and refusing unsafe `KANON_HOME`
 paths such as your home directory or the filesystem root.
 
+### kanon list
+
+Lists the sources declared in `.kanon` against those installed in `.kanon.lock`,
+tagging each `installed`, `not-installed`, or `orphan` -- the kanon analogue of
+`pip list` / `npm ls`.
+
+```bash
+kanon list                        # every source, declared vs installed, tagged
+kanon list --declared             # only sources declared in .kanon (no orphans)
+kanon list --status orphan        # only sources in the lock no longer declared
+kanon list --tree                 # expand installed sources to transitive packages
+kanon list --format json          # machine-readable JSON
+```
+
+A source is `installed` when it is in both files, `not-installed` when declared
+but not yet locked (run `kanon install`), and `orphan` when locked but no longer
+declared. Key options: `--declared`, `--tree`, `--status {installed,not-installed,orphan}`,
+`--format {table,json}`, `--kanon-file`, `--lock-file`. See
+[docs/cli-reference.md](docs/cli-reference.md#kanon-list).
+
 ### kanon outdated
 
 Compares each source in `.kanon` against the catalog and emits a table of
@@ -1461,6 +1483,23 @@ version bumps.
   supported; see [Platform support](#platform-support) and use WSL2)
 - [Contributing](CONTRIBUTING.md) -- How to create and maintain Kanon
   packages and marketplaces
+- [Privacy & Telemetry](docs/privacy.md) -- What usage telemetry kanon
+  collects, why, how it is encrypted, and how to turn it off
+
+---
+
+## Usage telemetry
+
+kanon emits one anonymised-by-design usage event per command to help the
+maintainers understand which commands and package sources are used. Telemetry
+is **on by default**, runs **silently** and **non-blocking**, never blocks or
+fails your command, and serialises only an explicit allowlist of kanon-computed
+fields -- never raw argv, credentials, keys, tokens, env-var values, or file
+contents (every URL is credential-stripped before it is sent).
+
+Disable it entirely by setting `KANON_TELEMETRY_DISABLED=1`. See
+[docs/privacy.md](docs/privacy.md) for the full list of collected fields and the
+transit/at-rest encryption.
 
 ---
 

{kanon_cli-3.2.0 → kanon_cli-3.3.0}/docs/cli-reference.md

@@ -15,6 +15,12 @@ are registered once via `kanon_cli.core.cli_args` so every parser exposes them.
 | `--no-color` | `NO_COLOR` | auto | Disable ANSI color. Any non-empty `NO_COLOR` also disables color. |
 | `--no-update-check` | `KANON_SKIP_UPDATE_CHECK` | off | Skip the best-effort PyPI "update available" check. The flag is equivalent to setting `KANON_SKIP_UPDATE_CHECK=1`. |
 | `--home` / `--store-dir <path>` | `KANON_HOME` | `~/.kanon-home` | Shared kanon home root (content-addressed store plus caches). `--store-dir` is an accepted alias of `--home`. Precedence: flag > `KANON_HOME` env > `~/.kanon-home`. |
+| `--telemetry-debug` | `KANON_TELEMETRY_DEBUG` | off | Print the exact usage-telemetry JSON that would be sent to stderr for this invocation (still non-blocking). |
+| `--telemetry-endpoint <url>` | `KANON_TELEMETRY_ENDPOINT` | `https://collector.platform.solutions.caylent.com/v1/logs` | Override the usage-telemetry collector endpoint (`https://` only). Flag wins over the env var. |
+
+Usage telemetry is on by default and can be disabled entirely by setting
+`KANON_TELEMETRY_DISABLED` to a truthy value (there is no disable flag). See
+[docs/privacy.md](privacy.md) for exactly what is collected and why.
 
 ## Shared Argument Factories
 
@@ -68,6 +74,9 @@ completion variables), see [docs/configuration.md](configuration.md).
 | `KANON_CATALOG_SOURCES` | Remote catalog source(s) as `<git_url>@<ref>`, one entry per line. Sets the default for every command that accepts `--catalog-source`; the resolving commands require exactly one entry unless `--catalog-source` is passed. | (none) |
 | `KANON_HOME` | Shared kanon home root (store plus caches). Overridden by the `--home` / `--store-dir` flag. | `~/.kanon-home` |
 | `KANON_SKIP_UPDATE_CHECK` | Set to `1` to skip the PyPI update-available check (same effect as `--no-update-check`). | (unset) |
+| `KANON_TELEMETRY_DISABLED` | Set to a truthy value (`1`/`true`/`yes`/`on`) to disable usage telemetry entirely. The only opt-out; there is no disable flag. See [docs/privacy.md](privacy.md). | (unset) |
+| `KANON_TELEMETRY_ENDPOINT` | Usage-telemetry collector endpoint (`https://` only). Overridden by `--telemetry-endpoint`. | `https://collector.platform.solutions.caylent.com/v1/logs` |
+| `KANON_TELEMETRY_DEBUG` | Set to a truthy value to print the would-send telemetry JSON to stderr (same effect as `--telemetry-debug`). | (unset) |
 | `KANON_OUTDATED_FORMAT` | Default output format for `kanon outdated` (`table` or `json`). Overridden by `--format`. | `table` |
 | `KANON_OUTDATED_JSON_INDENT` | JSON indentation (number of spaces) used by `kanon outdated --format json`. | `2` |
 | `KANON_WHY_FORMAT` | Default output format for `kanon why` (`text` or `json`). Overridden by `--format`. | `text` |
@@ -129,6 +138,76 @@ and operating systems.
 
 ---
 
+### `kanon list`
+
+List the sources declared in `.kanon` against the sources installed in
+`.kanon.lock`, tagging each with its status. This is the flat inventory
+command -- the kanon analogue of `pip list` / `npm ls` / `poetry show`. It
+complements [`kanon why`](#kanon-why) (the dependency graph),
+[`kanon outdated`](#kanon-outdated) (version staleness), and `kanon validate
+lockfile` (which *fails* on the same declared-vs-installed drift this command
+merely reports).
+
+**Status tags:**
+
+| Status | Meaning |
+|---|---|
+| `installed` | declared in `.kanon` **and** present in `.kanon.lock` |
+| `not-installed` | declared in `.kanon` but not yet in the lock -- run `kanon install` |
+| `orphan` | present in `.kanon.lock` but no longer declared in `.kanon` |
+
+The status is computed from the same alias comparison that `kanon install` and
+`kanon validate lockfile` enforce (`core/lockfile.py:reconcile_declared_installed`);
+`list` presents the divergence read-only instead of failing on it. The tags
+apply to the direct source aliases (transitive packages are only ever shown as
+installed, under `--tree`).
+
+**Flags:**
+
+| Flag | Effect |
+|---|---|
+| _(none)_ | Show every source (the declared ∪ installed union), one row each. |
+| `--declared` | Show only sources declared in `.kanon` (omit `orphan` sources). |
+| `--tree` | Expand each installed source to its transitive packages (from the lock). |
+| `--status <installed\|not-installed\|orphan>` | Show only sources with the given status. |
+| `--format <table\|json>` | Output format (default `table`). `KANON_LIST_OUTPUT_FORMAT` sets the default; the flag wins. |
+| `--kanon-file <path>` | Path to `.kanon` (default: auto-discovery walking up from the cwd; `KANON_KANON_FILE` overrides). |
+| `--lock-file <path>` | Path to `.kanon.lock` (default `<kanon-file>.lock`; `KANON_LOCK_FILE` overrides). |
+
+**Behaviour:**
+
+1. **`.kanon` required** -- resolved via `--kanon-file`, the `KANON_KANON_FILE`
+   env var, or auto-discovery. When none is found the command exits `1` with a
+   clean `ERROR:` message.
+2. **Lockfile optional** -- when `.kanon.lock` is absent every declared source is
+   reported `not-installed` and a note is written to stderr; the command still
+   exits `0`. An explicit `--lock-file` / `KANON_LOCK_FILE` that does not exist
+   is an error.
+3. **Exit code** -- `0` for any successful inventory (including the empty and
+   not-yet-installed states); `1` for an unresolvable `.kanon`, an
+   unreadable/malformed lock, or an unrecognised `KANON_LIST_OUTPUT_FORMAT`.
+
+**Examples:**
+
+```console
+$ kanon list
+SOURCE | REF                  | STATUS
+-------+----------------------+--------------
+bar    | 2.0.0                | not-installed
+baz    | 0.9.0 (cccccccccccc) | orphan
+foo    | 1.0.0 (aaaaaaaaaaaa) | installed
+
+$ kanon list --status orphan
+SOURCE | REF                  | STATUS
+-------+----------------------+-------
+baz    | 0.9.0 (cccccccccccc) | orphan
+
+$ kanon list --format json
+{"sources":[{"alias":"foo","status":"installed","name":"foo", ...}]}
+```
+
+---
+
 ### `kanon outdated`
 
 Compare installed sources against the catalog and report which are behind.

{kanon_cli-3.2.0 → kanon_cli-3.3.0}/docs/coming-from-pip-npm-cargo.md

@@ -24,6 +24,7 @@ This guide is for engineers who are comfortable with one or more of:
 | Search | pip search | npm search | cargo search | kanon search |
 | Add | pip install x==1.0 | npm i x@1.0 | cargo add x@1.0 | kanon add x@1.0 |
 | Outdated | pip list -o | npm outdated | cargo outdated | kanon outdated |
+| List installed | pip list | npm ls | cargo tree | kanon list |
 
 ## Where the model differs
 

{kanon_cli-3.2.0 → kanon_cli-3.3.0}/docs/configuration.md

@@ -294,6 +294,16 @@ filter, `kanon search --tree` exits with an error suggesting `--regex`,
 `<substring>`, or `--max-depth 0`. Override with
 `--no-filter-required`.
 
+**`KANON_LIST_OUTPUT_FORMAT`** (default: `table`) -- Default output
+format for `kanon list` (the declared-vs-installed inventory command).
+Supported values: `table`, `json`. Overridden by the `--format` CLI
+flag. Distinct from `KANON_LIST_FORMAT` above, which configures
+`kanon search`'s output.
+
+**`KANON_LIST_JSON_INDENT`** (default: `2`) -- Number of spaces per
+indentation level in JSON output from `kanon list --format json`. Must
+be a non-negative integer parseable by Python `int()`.
+
 **`KANON_OUTDATED_FORMAT`** (default: `table`) -- Default output
 format for `kanon outdated`. Currently only `table` is supported.
 Overridden by `--format` CLI flag.
@@ -570,7 +580,11 @@ number of completion error lines surfaced by `kanon doctor` (subcheck
 
 kanon performs a best-effort PyPI check for a newer `kanon-cli` release
 and prints an upgrade hint when one is available. The check is cached and
-never blocks a command on failure.
+never blocks a command on failure. When an upgrade is available the banner
+is yellow with the current (installed) version in red and the latest
+version in green. When a check is attempted but the network is unreachable,
+a red `no internet access -- could not check for updates` notice is printed
+to stderr at most once per cache window.
 
 **`KANON_SKIP_UPDATE_CHECK`** (default: unset) -- When set to exactly `1`,
 the PyPI update-available check is skipped entirely. The global
@@ -584,9 +598,9 @@ kanon --no-update-check install .kanon
 export KANON_SKIP_UPDATE_CHECK=1
 ```
 
-**`KANON_UPDATE_CHECK_TTL`** (default: `86400`) -- Seconds the cached
+**`KANON_UPDATE_CHECK_TTL`** (default: `10800`) -- Seconds the cached
 "latest version" result is considered fresh before the next check refetches
-it. Must be a positive integer.
+it (default 3 hours). Must be a positive integer.
 
 **`KANON_UPDATE_CONNECT_TIMEOUT`** (default: `2`) -- Connect timeout in
 seconds for the PyPI request. Must be a positive integer.
@@ -600,6 +614,62 @@ integer.
 
 ---
 
+### Usage telemetry
+
+kanon emits one anonymised-by-design usage event per command to the Caylent
+telemetry collector so the maintainers can understand which commands and
+package sources are used. Telemetry is **on by default**, runs **silently**
+and **non-blocking** in a detached background process, and **never** blocks,
+delays, or fails your command. It serialises only an explicit allowlist of
+kanon-computed fields and never raw argv, credentials, keys, tokens, env-var
+values, or file contents; every URL is credential-stripped before it is sent.
+See [docs/privacy.md](privacy.md) for the exact fields collected, the reason
+for each, and the transit/at-rest encryption.
+
+**`KANON_TELEMETRY_DISABLED`** (default: unset) -- The single opt-out. Set to
+a truthy value (`1`, `true`, `yes`, or `on`) to disable telemetry entirely.
+There is no disable flag; this env var is the only off switch.
+
+```bash
+# Turn telemetry off for the whole session
+export KANON_TELEMETRY_DISABLED=1
+```
+
+**`KANON_TELEMETRY_ENDPOINT`** (default:
+`https://collector.platform.solutions.caylent.com/v1/logs`) -- The collector
+endpoint. Must be an `https://` URL. The global `--telemetry-endpoint <url>`
+flag overrides this for a single invocation.
+
+**`KANON_TELEMETRY_DEBUG`** (default: unset) -- When truthy, prints the exact
+JSON that would be sent to stderr (still non-blocking). Equivalent to the
+global `--telemetry-debug` flag. Use it to inspect precisely what an event
+contains.
+
+```bash
+# See exactly what an event contains without changing send behaviour
+kanon --telemetry-debug install .kanon
+```
+
+**`KANON_TELEMETRY_CONNECT_TIMEOUT`** (default: `2`) /
+**`KANON_TELEMETRY_READ_TIMEOUT`** (default: `3`) -- Connect / read timeouts
+in seconds for the background POST. Must be positive integers.
+
+**`KANON_TELEMETRY_MAX_BODY_BYTES`** (default: `4194304`) /
+**`KANON_TELEMETRY_GRAPH_SIZE_CAP`** (default: `3145728`) -- The maximum
+serialised body size and the install-graph size cap. When an install graph
+exceeds the cap it is dropped in favour of the flattened installed-packages
+summary with `install_graph_truncated: true`, so the fact that packages were
+installed is never lost. Must be positive integers.
+
+**`KANON_TELEMETRY_GIT_TIMEOUT`** (default: `3`) -- Per-command timeout in
+seconds for the read-only `git` probes used to collect credential-stripped
+repository provenance. Must be a positive integer.
+
+**`KANON_TELEMETRY_LOG`** (default: `${KANON_HOME}/cache/telemetry-errors.log`)
+-- Path to the append-only background telemetry error log.
+
+---
+
 ### Retry policy
 
 kanon retries `git ls-remote` calls on transient errors. Auth-failure

kanon_cli-3.3.0/docs/privacy.md

@@ -0,0 +1,90 @@
+# Privacy & Telemetry
+
+kanon emits one usage-telemetry event per command so the maintainers can
+understand which commands are used, which package sources are installed, and
+where failures occur. This page documents exactly what is collected, why, how it
+is protected in transit and at rest, and how to turn it off.
+
+## Design principles
+
+- **On by default.** Telemetry is enabled out of the box for every user. There
+  is no opt-in prompt, no first-run consent gate, and no enable toggle.
+- **Silent and non-blocking.** The event payload is built in the foreground from
+  local git and lockfile reads only (no network). The actual HTTPS POST is fired
+  in a detached background process, so your command is never blocked, delayed on
+  the network, or failed by telemetry. A happy-path command prints nothing about
+  telemetry on stdout or stderr.
+- **Never-fail.** Any telemetry error (payload build, serialisation, or network)
+  is swallowed for this best-effort feature and, where possible, recorded in a
+  background error log (`${KANON_HOME}/cache/telemetry-errors.log`). It never
+  surfaces to your command.
+- **Zero secrets by construction.** Only an explicit allowlist of kanon-computed
+  fields is serialised. Raw argv is never emitted. SSH/private keys, tokens,
+  credentials, key files, `~/.ssh`, environment-variable values, and file
+  contents are never read or emitted. Every git/source URL is credential-stripped
+  (any `user:pass@` / `token@` userinfo is dropped; host, org, and repo are kept)
+  before it is serialised.
+
+## What is collected
+
+Each event is a single OTLP/HTTP log record whose body is a flat JSON object with
+four top-level keys -- `tool` (always `kanon`), `timestamp`, `event_type`
+(always `cli_command`), and `payload`. The rich fields ride inside `payload`:
+
+| Field | Where | Collected? | Why / notes |
+|-------|-------|-----------|-------------|
+| `tool` = `kanon`, `timestamp`, `event_type` = `cli_command` | body | Yes | Routing and partitioning; `tool` is the partition key. |
+| `schema_version`, `run_id` | payload | Yes | Payload schema version and a per-invocation random id (a fresh UUID each run -- never a stable device or user id). |
+| `environment`: `kanon_version`, `python_version`, `os`, `arch`, `install_type`, `is_ci` | payload | Yes | Understand the runtime mix (versions, platform, wheel/editable/source install, CI vs interactive). No hostname, username, or path. |
+| `invocation`: `command`, `subcommand`, boolean flag **names**, allowlisted flag **values** | payload | Yes | Which command/subcommand ran and which boolean flags were set (names only). Only closed-domain values (e.g. `--format text|json`) are recorded. Never raw argv. |
+| `outcome`: `exit_code`, `status`, `error_type`, `duration_ms` | payload | Yes | Success/failure rates and latency. `error_type` is the exception **class name** only -- never a message or traceback. |
+| `git`: `user_email`, `remote_host`, `org`, `repo`, `branch` | payload | Yes | Attribute usage to a team/repo. The remote URL is **credential-stripped**; only host/org/repo are kept. |
+| `install_graph` (on `kanon install`) | payload | Yes | The complete resolved graph: per direct source (`alias`, `name`, `manifest_url`, `ref_spec`, `resolved_ref`, `resolved_sha`, `registered_marketplaces`) plus its transitive `projects[]` (`name`, `url`, `canonical_url`, `resolved_ref`, `resolved_sha`) and the include chain. All URLs credential-stripped. |
+| `installed_packages[]` (on `kanon install`) | payload | Yes | Flattened list of every direct source (`scope: direct`) and every transitive repo package (`scope: transitive`) with `name`, `url`, and `sha` -- easy analytics of what was installed. |
+| Raw argv, non-allowlisted or secret-capable flag values | -- | **Never** | -- |
+| SSH/private keys, tokens, credentials, key files, `~/.ssh`, env-var values | -- | **Never** | Never read or emitted. |
+| Source code, file contents, full local file paths | -- | **Never** | -- |
+| Error messages / stack traces | -- | **Never** | Exception class name only. |
+
+The serialised install graph is capped well under the collector's body limit. If
+a graph is very large it is dropped in favour of the flattened
+`installed_packages[]` summary plus `install_graph_truncated: true`, so the fact
+that packages were installed is never lost.
+
+## Encryption
+
+- **In transit:** the event is POSTed over HTTPS/TLS to the collector. The
+  emitter enforces an HTTPS-only guard and refuses any non-`https://` endpoint.
+- **At rest:** the collector stores events in an S3-backed data lake encrypted
+  with a customer-managed KMS key (SSE-KMS).
+
+## How to turn it off
+
+Set the environment variable `KANON_TELEMETRY_DISABLED` to a truthy value
+(`1`, `true`, `yes`, or `on`). This is the **only** opt-out -- there is no
+`--no-telemetry` flag.
+
+```bash
+# Disable telemetry for the whole session
+export KANON_TELEMETRY_DISABLED=1
+
+# Or for a single command
+KANON_TELEMETRY_DISABLED=1 kanon install .kanon
+```
+
+## Inspecting exactly what is sent
+
+Use the `--telemetry-debug` global flag (or `KANON_TELEMETRY_DEBUG=1`) to print
+the exact JSON that would be sent to stderr. This does not change the
+non-blocking send behaviour; it only surfaces the payload so you can audit it.
+
+```bash
+kanon --telemetry-debug install .kanon
+```
+
+## Related configuration
+
+See [docs/configuration.md](configuration.md#usage-telemetry) for the full list
+of telemetry environment variables (endpoint override, timeouts, size caps, and
+the error-log path) and [docs/cli-reference.md](cli-reference.md#global-flags)
+for the global flags.

{kanon_cli-3.2.0 → kanon_cli-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kanon-cli"
-version = "3.2.0"
+version = "3.3.0"
 description = "Kanon (Kanon Package Manager) CLI tool"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

{kanon_cli-3.2.0 → kanon_cli-3.3.0}/src/kanon_cli/__init__.py

@@ -1,3 +1,3 @@
 """Kanon CLI -- Kanon Package Manager."""
 
-__version__ = "3.2.0"
+__version__ = "3.3.0"