neatlogs-cli 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to `neatlogs-cli` are documented in this file.
 
+## 0.2.2
+
+- Release the user OAuth MCP setup, sign-in, proxy, and sign-out commands for customers.
+- Include patched Zod and preserve compatibility with the deployed action catalog.
+
+## 0.2.2-team-test.2
+
+- Require Zod 4.6.6 or later to address GHSA-mrhx-c7xc-m3w5 and validate packed
+  consumers against that patched minimum.
+- Retain the user MCP OAuth, custody and catalog integration from the previous
+  candidate. Publish under a new prerelease version without moving its reserved tag.
+
+## 0.2.2-team-test.1 (unpublished; superseded by 0.2.2-team-test.2)
+
+- Add user-scoped MCP OAuth, the local custody proxy, and negotiated v2/v4
+  action discovery and execution for DEV acceptance.
+- Preserve explicitly negotiated read-only v2 proxy preparation when v4
+  discovery is disabled.
+
+- Add opt-in live detection read discovery through `schema list`, `schema search`,
+  and `schema show` with `--live`.
+- Add `api <operationId> --live` execution from validated backend descriptors,
+  without a new local handler for each compatible read.
+- Keep friendly commands and default embedded-schema behavior compatible.
+
 ## 0.2.1
 
 - Verify `auth status` against the Public API instead of treating a configured
@@ -32,8 +57,12 @@ All notable changes to `neatlogs-cli` are documented in this file.
 
 ## 0.2.0-team-test.1
 
-- Add project lifecycle, existing-member access, reviewer-aware evaluation activation,
-  classifier workflows, and bounded historical job commands for Dev acceptance.
+- Add project archive, restore, soft deletion, and existing-member access commands.
+- Add evaluation draft discard and reviewer-aware activation commands.
+- Add classifier dataset, training, publication, and bounded job management commands.
+- Add bounded historical detection job commands and refresh the Public API contract.
+- Publish this candidate to the `team-test` channel for Dev acceptance; provider
+  admission and historical backfill still require their environment prerequisites.
 
 ## 0.1.0 (release candidate)
 
@@ -44,7 +73,7 @@ All notable changes to `neatlogs-cli` are documented in this file.
   contracts and safe request-ID diagnostics from the retest repairs.
 - Publication and deployed end-to-end acceptance remain release requirements.
 
-## 0.1.0-team-test.7
+## 0.1.0-team-test.7 (unpublished; superseded by 0.1.0)
 
 - Include the merged fresh-start fixes: read-only default OAuth scopes and
   field-specific guidance for required analytics dates and other arguments.
@@ -101,7 +130,3 @@ All notable changes to `neatlogs-cli` are documented in this file.
 ## 0.1.0-team-test.1
 
 - Team-testing prerelease of the NeatLogs public API CLI.
-
-## 0.1.0
-
-- Initial public release of the NeatLogs public API CLI.

package/README.md

@@ -34,18 +34,20 @@ flowchart LR
 
 ## Human quickstart
 
-This checkout prepares `neatlogs-cli@0.2.1`, under the MIT license in
-[LICENSE](LICENSE). Release changes are described in [CHANGELOG.md](CHANGELOG.md).
-Publication is a separate release step; check `npm view neatlogs-cli version`
-for the current stable release.
+The stable release candidate in this checkout is `neatlogs-cli@0.1.0`, under
+the MIT license in [LICENSE](LICENSE). It is not published by a source change.
+Verify `npm view neatlogs-cli@0.1.0 version` before using the stable install
+command; the currently published team-test release remains available through
+`npm install --global neatlogs-cli@team-test` until the reviewed release ships.
 
 1. Install the CLI and confirm that it runs.
 
    ```bash
-   npm install --global neatlogs-cli
+   npm install --global neatlogs-cli@0.1.0
    neatlogs --version
    ```
 
+   The stable candidate is `0.1.0`; publication must be independently verified.
    Use Node.js 22 or
    24. The complete dev setup and verification flow is in the
    [team quickstart](../backend/docs/public-api/dev-team-quickstart.md).
@@ -53,57 +55,34 @@ for the current stable release.
 2. Save the host, select the profile, and sign in.
 
    ```bash
-   neatlogs profile set work --host 'https://app.neatlogs.com'
+   neatlogs profile set work --host '<https-app-origin>'
    neatlogs profile use work
-   neatlogs --host https://app.neatlogs.com --profile work auth login --device
+   neatlogs auth login
    ```
 
-   Approve the displayed code in your browser. Omit `--device` for browser
-   OAuth on an interactive terminal; headless terminals use Device Flow.
+   An interactive terminal opens browser OAuth and prints the URL as a
+   copy/paste fallback. A non-interactive or headless terminal automatically
+   uses Device Flow; `--device` selects it explicitly.
 
 3. List the projects you can access.
 
    ```bash
-   env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN -u NEATLOGS_PROJECT_ID neatlogs --profile work projects list
+   neatlogs projects list
    ```
 
 4. Save the project you want this profile to use.
 
    ```bash
-   neatlogs profile set work --host 'https://app.neatlogs.com' --project '<project-uuid>'
+   neatlogs profile set work --host '<https-app-origin>' --project '<project-uuid>'
    ```
 
 5. Check your identity and read recent traces.
 
    ```bash
-   env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN neatlogs --profile work whoami
-   env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN neatlogs --profile work traces list --limit 10
-   env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN neatlogs --profile work traces get <trace-id>
+   neatlogs whoami
+   neatlogs traces list --limit 10
    ```
 
-The read commands use POSIX `env -u` to exclude SDK credentials only from the
-CLI process, keeping them available to the application. In other shells, use
-an equivalent clean credential environment. These examples work with the
-published 0.2.0 package.
-
-These examples use the US dashboard host; use `https://eu.app.neatlogs.com`
-for EU. `projects list` must run without `--project` or `NEATLOGS_PROJECT_ID`.
-A saved profile's project is automatically omitted for discovery.
-
-`--credential-source profile` (available in 0.2.1) ignores both credential environment
-variables and uses the selected or active profile's stored OAuth login. This
-lets an SDK application keep its `NEATLOGS_API_KEY` in the same shell. With the
-published 0.2.0 CLI, omit this new option and run each OAuth CLI command through
-`env -u NEATLOGS_API_KEY -u NEATLOGS_TOKEN` on POSIX shells, or use an equivalent
-clean credential environment on other platforms. Do not remove the SDK key
-from the application's configuration.
-
-A key-only user can verify SDK ingestion/readback with the SDK's documented
-`doctor --local` and `doctor --probe` commands without CLI login. Report CLI
-readback as **waiting on a human** unless OAuth approval or a suitable service
-account is available. A synthetic probe proves the telemetry pipeline; verify
-the application's actual trace separately.
-
 `profile set` stores non-secret host and project preferences. Login stores the
 OAuth credentials separately in the native operating-system vault.
 
@@ -168,6 +147,10 @@ The consent page lists only the permissions requested by this login command.
 `offline_access` allows refresh tokens; it is not an API permission shown by
 `whoami`.
 
+Existing OAuth credentials retain their issued scopes after a CLI upgrade.
+Log out of the selected profile and sign in again to apply the stable release's
+read-oriented defaults; request write scopes explicitly when needed.
+
 ## Agent and CI automation
 
 In **Settings → Service Accounts**, create a dedicated account, bind only the
@@ -208,11 +191,13 @@ only with `--allow-file-credentials`; it uses directory mode `0700`, file mode
 equivalent ACL enforcement is not implemented.
 
 Credentials are never accepted as command-line flags. The CLI never follows
-redirects, executes arbitrary API URLs, or fetches a live API schema. Recognized
+redirects or executes arbitrary API URLs. Live detection reads fetch validated
+structured metadata only when `--live` is explicit. Recognized
 `nloa_`, `nlsa_`, and `nlpk_` prefixes select exactly one credential class; a
 foreign or mismatched prefix is rejected without fallback.
 
-`schema` inspects the release-embedded contract, not active deployment flags.
+`schema` inspects the release-embedded contract by default. Its subcommands with
+`--live` inspect the authenticated deployment catalog for the selected project.
 Each operation carries `x-neatlogs-operation-gate`; only `always` is enabled by
 default, while every other gate must be enabled by the server before the
 operation is callable.
@@ -358,6 +343,10 @@ printf '%s' '{"q":"failed checkout"}' | neatlogs --project <uuid> api post_api_v
 neatlogs schema list
 neatlogs schema search <query>
 neatlogs schema show <operationId>
+neatlogs --project <uuid> schema list --live
+neatlogs --project <uuid> schema search detections --live
+neatlogs --project <uuid> schema show get_api_v1_public_detections --live
+neatlogs --project <uuid> api get_api_v1_public_detections --live --query limit=1
 ```
 
 For confidential or multiline prompt text, prefer bounded stdin so content is
@@ -377,17 +366,20 @@ Version creation and label activation are intentionally separate authorization
 steps: `prompts create` requires prompt write access, while `prompts label`
 requires prompt management access.
 
-`api` accepts only operation IDs with an explicit handler compiled into this
-CLI release. `--param` and `--query` accept bounded `name=value` pairs, reject
+`api` without `--live` accepts only operation IDs with an explicit handler
+compiled into this CLI release. `--param` and `--query` accept bounded `name=value` pairs, reject
 duplicates, and are checked against that operation's embedded parameter
 allowlist before any request. Body-bearing safe reads accept one object from
 `--body-stdin`, bounded to 64 KiB and validated against the embedded request
-schema before any request. `schema` commands are offline and do not require credentials.
+schema before any request. `schema` commands without `--live` are offline and do not require credentials.
 `schema list` and `schema search` return concise descriptors. `schema show`
 returns the normalized embedded operation contract, including request and
 response schemas, authentication requirements, and execution/risk metadata.
-New schema operations default to non-executable until an explicit handler and
-risk classification are added.
+New bundled schema operations require an explicit local handler and risk
+classification. The detection read pilot adds `--live` to `api` and each `schema`
+subcommand. Supported live reads use their validated descriptor and the existing
+HTTP transport without a per-operation local handler. See the
+[runtime detection read reference](docs/runtime-detection-reads.md).
 
 Raw `api` execution fails closed for operations that require target-specific
 destructive confirmation. Use the operation's curated command instead; raw
@@ -522,6 +514,28 @@ neatlogs evals launch '<evaluation-uuid>' --assign-me --review-duration 7d
 This OAuth-user-only action requires creator ownership and sends no email or
 Slack notification; the assignment remains available in the NeatLogs app.
 
+The creator can activate selected members and explicitly opted-in retained
+human guests or AI reviewers with `evals activate <id> --body-stdin`. The JSON
+body also accepts `reminderConfig` and `notifications`:
+
+```json
+{
+  "reviewerUserIds": ["30000000-0000-4000-8000-000000000003"],
+  "reviewDuration": "7d",
+  "reminderConfig": { "frequency": "custom", "intervalHours": 24, "time": "9:00 AM" },
+  "notifications": ["email", "slack"]
+}
+```
+
+Cadences are `none`, `every-day`, `halfway`, `one-day-before`, and `custom`.
+Custom cadence requires 1–168 interval hours and a valid 12/24-hour time;
+the worker uses creator profile timezone, then project timezone, then UTC.
+Omitted settings preserve stored values. `notifications: []` disables external
+member lifecycle channels; in-app notifications remain. Guest invitation and
+reminder emails use the existing separate guest delivery rules. An active
+receipt confirms persisted settings, not provider acceptance or delivery.
+Use a stable `--idempotency-key` when retrying the same activation.
+
 Assigned-review discovery and reads are OAuth-only because an assignment belongs
 to a real user. Draft and submit additionally require `evaluation:write`,
 current `eval:submit`, and `PUBLIC_API_MUTATIONS_ENABLED=true` on the server.
@@ -608,26 +622,8 @@ request.
 ## Configuration and output
 
 - `NEATLOGS_TOKEN` is the primary credential source; `NEATLOGS_API_KEY` is the
-  legacy public API key fallback, not an SDK project key. In the default
-  `--credential-source auto` mode, environment credentials take precedence over
-  a selected stored profile and differing token/key values fail closed.
-- `--credential-source profile` explicitly ignores both credential environment
-  variables and uses the saved login, including its host/project defaults.
-  Host overrides must still match the credential-bound host.
-- `--credential-source token` reads only `NEATLOGS_TOKEN`, ignoring the SDK's
-  `NEATLOGS_API_KEY`. A missing or invalid token fails without falling back to
-  another identity. Use this for service-account automation sharing an SDK shell.
-- `auth status` now verifies access against the public API. OAuth and service
-  tokens use project discovery (`context:read`); legacy public API keys use
-  their bound `whoami` context. No selected project is needed. Rejected/missing
-  credentials report `authenticated: false` and exit 3. Scope failures and
-  network failures retain their distinct errors instead of claiming the user
-  is signed out. Success reports `verification: "public_api"`; this does not
-  guarantee permission to read every project's traces.
-  Older published clients only checked local credential presence, so use
-  project-scoped `whoami` and a trace read when validating those versions.
-- Authentication and configuration diagnostics include a static, secret-free
-  `hint` in JSON and human output with the recovery steps.
+  legacy fallback. An environment credential takes precedence over a selected
+  stored profile and is identified as `environment` by `auth status`.
 - `--profile <name>` selects non-secret host/project preferences and its
   separately stored OAuth credential. Stored tokens are never sent when a
   `--host` or `NEATLOGS_HOST` override differs from the credential-bound host.
@@ -638,7 +634,8 @@ request.
 - Product reads and selected-project context commands require `--project
   <uuid>` or `NEATLOGS_PROJECT_ID` for OAuth/service-account credentials.
   `--project` takes precedence. A project is optional for legacy credentials.
-  Discovery commands instead forbid any selected project.
+  Organization/project discovery commands forbid any selected project. Runtime
+  detection action discovery requires a selected project.
 - A service-account token is sent only as `Authorization: Bearer` and the
   selected project only as `x-project-id`. A legacy key is sent only as
   `x-api-key`.
@@ -660,12 +657,19 @@ request.
   `--fields id,name` projects at most 32 bounded object paths in JSON/JSONL
   output. The trace-payload command keeps its existing request-specific
   `--fields input[,output,error]` meaning.
+- `evals ai-insights --all --max-items <number>` collects runs and recomputes
+  evaluator metrics over exactly those returned runs. `metricsScope: "page"`
+  remains scoped to the returned collection; use `evals ai-metrics` for campaign
+  metrics. `metricsIncomplete` is true if any fetched page reports incomplete
+  metrics. JSONL and field projection select run rows.
 - `--debug` writes redacted request lifecycle records to stderr without
   credentials, headers, bodies, project IDs, or query values. `--no-color` and
   `NO_COLOR` are accepted; current output contains no ANSI color sequences.
 - Requests time out after 10 seconds and never follow redirects.
-- Idempotent GET requests and explicitly marked safe POST reads retry at most
-  twice after a `429` or `503`, honoring a safe, bounded `Retry-After` value.
+- Idempotent GET requests retry at most twice after a `429` or `503`, honoring
+  a safe, bounded `Retry-After` value. Unkeyed POST reads make one attempt,
+  including search and compute. A failed request may already have used compute;
+  another request can start and charge for new work.
 - Idempotent mutating operations retry at most twice after a `429` or `503`.
   Other mutating operations are never retried.
 
@@ -721,3 +725,80 @@ certificate temporary directories.
 |    9 | Partial bulk-operation success               |
 |   10 | Destructive confirmation required            |
 |   11 | Server or response-contract failure          |
+# Platform runtime discovery (unreleased)
+
+Use `neatlogs schema list --live --catalog-version 2` to discover compatible
+account reads and, when a project is selected, permitted project reads. Inspect
+with `schema show <operationId> --live --catalog-version 2` and execute with
+`api <operationId> --live --catalog-version 2`. Project-free organization/project
+discovery needs `context:read`, not detection access. v1 remains the default.
+
+The unreleased client also negotiates execution version 2 for bounded JSON POST
+reads via `--body-stdin`: one attempt, validated input/output and canonical
+operation budgets. Production POST discovery remains disabled pending shared
+acceptance. Bundled unkeyed POST reads also make one attempt in this version;
+older published CLI versions may retry them on `429` or `503`.
+
+Only explicitly qualified and activated read contracts are advertised. Writes, unsupported
+target/schema contracts, jobs and file workflows are not automatically enabled.
+See the [shared v2 contract and exposure decisions](../backend/docs/public-api/runtime-catalog-v2.md).
+These changes require backend deployment and a CLI release; neither has occurred.
+
+
+
+Runtime catalog v2 can negotiate account and organization reads without a project:
+
+```sh
+neatlogs schema list --live --catalog-version 2 --account
+neatlogs schema list --live --catalog-version 2 --organization <uuid>
+neatlogs api <operationId> --live --catalog-version 2 --organization <uuid>
+```
+
+`--account` suppresses a saved project for discovery. `--organization` binds discovery and execution to that organization and supplies its path parameter; a conflicting `--param organizationId=...` is rejected. The flags are mutually exclusive and require live v2 discovery. Account bootstrap requires `context:read`; organization bootstrap requires OAuth with `organization:read`. Each action still requires its own canonical permission and scope. These are unreleased local capabilities; hosted availability is separate.
+
+
+For service-account metadata, use `--service-account <uuid>` with live catalog v2. This selects the resource being read, while authentication remains OAuth. It cannot be combined with `--account` or `--organization`; a saved project is suppressed. The server retains the existing Owner/Admin, target-binding and audit-plan checks. Actor-specific detection draft discovery describes the OAuth management permission or workload read permission appropriate to the authenticated credential.
+
+### Complete action descriptions
+
+Use `schema list --live --catalog-version 3` to discover permitted reads and
+writes, or `schema show <operationId> --live --catalog-version 3` for full
+input, response, idempotency, authorization and workflow contracts. Discovery
+follows bounded revision-pinned pages. `--account`, `--organization <uuid>`,
+`--service-account <uuid>` and v3-only `--service-account-token <uuid>` select
+the target. Deployment gates and current permissions still filter results.
+
+Version 3 describes capabilities; it does not activate generic write/job/file
+execution. `api --live --catalog-version 3` fails explicitly. Use an activated
+read contract or the existing bundled workflow command for execution.
+
+### Live canonical actions (catalog v4)
+
+Discover with `neatlogs schema list --live --catalog-version 4`. Execute a reviewed
+write with `neatlogs api OPERATION --live --catalog-version 4 --confirm
+--idempotency-key KEY --body-stdin`. Keep the same key and exact original input for
+retries across clients. The generic v4 path requires explicit keys for keyed writes
+and sends one attempt. Compute reads additionally require `--compute-key KEY` with
+22–128 URL-safe characters; use a randomly generated key with adequate entropy.
+
+Use the same command with `--result` to read the saved mutation result without
+executing the mutation. It retains original target/input/key and current credentials.
+`--result` does not require `--confirm`. Pending or unknown does not authorize a new
+key or establish rollback. Domain job status/result/cancel operations are discoverable
+through each action's workflow metadata. Wrapped-secret commands use local custody;
+keys must never be passed in model-visible arguments or printed in ordinary output.
+
+Catalog v3 remains descriptive. v1/v2 read clients keep their existing contracts.
+Canonical binary responses are returned as bounded base64 with a SHA-256 digest.
+Use `--output /absolute/new-file` to save exact bytes in a new mode-0600 file;
+existing files are never overwritten. Private file export is supported on POSIX
+systems. Windows rejects `--output` because POSIX modes do not establish private
+Windows ACLs; omit `--output` to receive the bounded base64 response instead.
+The client follows no redirects and accepts
+only content types declared by the discovered action. Signed-URL JSON and domain
+job lifecycle responses retain their canonical schemas. Combined file/export
+acceptance remains required before release.
+
+For v4 compute actions, reuse the original input and key with `--execution <uuid>` to read durable status. Add `--cancel-execution --expected-version <version> --confirm` to request cancellation. Cancellation is a versioned PATCH; a successful request does not imply an already dispatched provider call stopped. Use `--result` separately to recover a keyed mutation's saved response.
+
+Compute submissions emit a bounded `{ "computeExecutionId": "<uuid>" }` receipt on stderr, including an HTTP error with an unknown outcome. Stdout retains the operation's canonical response. If the submission response was lost, use `--execution --compute-key <original-key>` with the same operation and original input to recover without dispatching again.

package/SECURITY.md

@@ -25,6 +25,10 @@
   implemented.
 - Profiles contain only host, issuer, selected organization/project, and the
   credential-store kind. They never contain tokens.
+- Execution custody may be explicitly selected with `--allow-file-custody`,
+  including when credentials come from `NEATLOGS_TOKEN`. Use the same choice
+  for result recovery. It selects the protected private-file store directly;
+  a native vault failure never triggers an automatic custody-store fallback.
 
 ## OAuth handling