flipstream 0.4.0 → 0.6.0

package/dist/lib/store/keyring.js

@@ -7,7 +7,37 @@ import { freshAccessToken, keyOf, parseCredentials } from './credentials.js';
 export const KEYRING_SERVICE = 'io.flipstream.cli';
 // TokenStore backed by the OS keychain. The whole Credentials JSON is the single
 // secret per host (keyed by host).
+//
+// Reads are CACHED for the life of the process. Without this, one command touches
+// the keychain several times — the auth gate reads it, then every authed request
+// re-reads it through withFreshToken, and a paginated call re-reads it per page.
+// On macOS each read is a separate access, so a user who granted "Allow" rather
+// than "Always Allow" gets prompted once per read: two dialogs for `catalog`,
+// three for `query`, more for anything that paginates or resolves a name.
+//
+// This costs nothing in EXPOSURE: the credentials are already in memory the moment
+// they are read — they have to be, to go in an Authorization header — so holding
+// them for the rest of a short-lived CLI process reveals nothing new. Nothing is
+// written to disk, and the cache dies with the process.
+//
+// It does cost COHERENCE, and that is worth stating plainly rather than glossing.
+// Another CLI process can log out or rotate tokens underneath us, and this cache
+// will not notice. Two consequences, handled differently:
+//
+//   Deleting someone else's session — handled. A failed refresh compare-and-deletes
+//   (see auth/refresh.ts): it re-reads past this cache and only clears when the
+//   stored token is still the one it tried. That race predates the cache; caching
+//   only widened the window.
+//
+//   Using a token after a concurrent `auth logout` — accepted. Logout REVOKES
+//   upstream, so a stale cached token gets a 401 from the server rather than data,
+//   surfacing as data_auth_failed. Re-reading before every request would fix it and
+//   would also undo the entire point of caching, for a case that already fails
+//   safely.
 export class KeyringStore {
+    // `null` is cached too: "this host has no credentials" is an answer worth
+    // remembering, or a logged-out run re-reads on every check.
+    #cache = new Map();
     accessTokenIfFresh(host) {
         return freshAccessToken(this.load(host));
     }
@@ -23,6 +53,7 @@ export class KeyringStore {
         }
     }
     clear(host) {
+        this.#cache.set(host, null);
         try {
             new Entry(KEYRING_SERVICE, keyOf(host)).deletePassword();
         }
@@ -31,15 +62,27 @@ export class KeyringStore {
         }
     }
     load(host) {
+        const cached = this.#cache.get(host);
+        if (cached !== undefined)
+            return cached;
+        return this.reload(host);
+    }
+    reload(host) {
+        let creds = null;
         try {
             const secret = new Entry(KEYRING_SERVICE, keyOf(host)).getPassword();
-            return secret ? parseCredentials(secret) : null;
+            creds = secret ? parseCredentials(secret) : null;
         }
         catch {
-            return null;
+            creds = null;
         }
+        this.#cache.set(host, creds);
+        return creds;
     }
     save(host, creds) {
         new Entry(KEYRING_SERVICE, keyOf(host)).setPassword(JSON.stringify(creds));
+        // Keep the cache authoritative: a refresh saves rotated tokens mid-command,
+        // and a later read must see them rather than the ones it started with.
+        this.#cache.set(host, creds);
     }
 }

package/dist/lib/store/memory-store.d.ts

@@ -6,5 +6,6 @@ export declare class MemoryStore implements TokenStore {
     available(): boolean;
     clear(host: string): void;
     load(host: string): Credentials | null;
+    reload(host: string): Credentials | null;
     save(host: string, creds: Credentials): void;
 }

package/dist/lib/store/memory-store.js

@@ -15,6 +15,11 @@ export class MemoryStore {
     load(host) {
         return this.entries.get(keyOf(host)) ?? null;
     }
+    // No cache here, so a forced re-read is the same read. Present so the interface
+    // is honest and tests exercise the same call sites as the real store.
+    reload(host) {
+        return this.load(host);
+    }
     save(host, creds) {
         this.entries.set(keyOf(host), creds);
     }

package/docs/AGENT-CONTRACT.md

@@ -0,0 +1,238 @@
+# Flipstream CLI — Agent Contract (v3)
+
+The machine-facing promises the CLI makes so an AI coding agent (Claude Code,
+Codex, an MCP server) or a script can drive it deterministically. These are
+**frozen**: a conformance suite (`test/contract/agent-contract.test.ts`)
+auto-discovers every command and fails the build if any of these rules break.
+
+`CONTRACT_VERSION` is surfaced by `flipstream version` (`contractVersion`) and
+defined in `src/lib/config/constants.ts`. **Current: `3`.** A breaking change to
+anything below bumps it.
+
+> **v2 → v3 (E11-1).** Two changes are breaking by this document's own rules,
+> hence the bump. (1) **HTTP 429 moved** from `data_request_failed`/exit 1 to
+> `rate_limited`/exit 7 — the transient classification is correct, and v2
+> consumers branching on exit 1 must follow. (2) **`usage` narrowed**: missing
+> query inputs and malformed bodies now carry specific codes
+> (`missing_source`, `missing_connection_id`, `missing_source_and_connection_id`,
+> `missing_request`, `invalid_body_json`); `usage` still covers bad flags,
+> `--json`+`--ndjson`, and planner 422s. The envelope's new optional fields
+> (below) are additive and would NOT alone have bumped the version.
+
+> **v1 → v2 (E8).** `query` now targets the **query planner** and builds a
+> `LogicalRequest` from flags. Previously it forwarded an opaque body to
+> pulse-data. `--body`/`--body-file`/stdin still forward verbatim, so the escape
+> hatch is unchanged; the default target and default input mode are not. Adds
+> `catalog` and `health`.
+
+## Discovery — how an agent learns what it can do
+
+This is the capability map. **Enumerate it first**, then call commands.
+
+- **`flipstream commands --json`** → the full machine-readable catalog: every
+  command's `id`, `summary`, `description`, `examples`, `flags`, `args`, and
+  `aliases`. One call returns everything the CLI can do.
+- **`flipstream <command> --help`** → human help for a single command.
+- **`flipstream --help`** → topic overview (`auth`, `workspaces`/`ws`,
+  `connections`/`conn`, plus top-level `query`, `catalog`, `health`, `version`,
+  `commands`).
+- **`flipstream contract`** → this document, verbatim, from the installed
+  package — context self-service, offline, no auth.
+- **`flipstream skills install`** → installs the flipstream skill for detected
+  AI coding agents (local detection only; never in CI; never phones home).
+- **`flipstream catalog [source]`** → the *data* vocabulary (which is not the
+  same thing as the command surface): the exact names `-d`, `-m` and filter keys
+  accept. Read it before constructing a query; a name's `name` is what you send,
+  its `label` is only for humans.
+
+Every command obeys the rules below, and the conformance suite
+(`test/contract/agent-contract.test.ts`) auto-discovers commands and fails the
+build if any one drifts — so this contract stays true as commands are added.
+
+## Core rules
+
+1. **stdout = data, stderr = diagnostics.** Under `--json`/`--ndjson`, stdout
+   carries **only** machine output (a single JSON document, or NDJSON lines).
+   All human text — prompts, progress (`Opening your browser…`), `--verbose`
+   diagnostics — goes to **stderr**. So `flipstream <cmd> --json 2>/dev/null`
+   yields clean JSON.
+2. **`--json`** → exactly one JSON document on stdout. **`--ndjson`** → one
+   compact JSON object per line (streaming), no enclosing array, no blank lines.
+   `--json` and `--ndjson` together is a usage error (exit 2).
+3. **Failures are JSON too.** Under `--json`/`--ndjson`, a failure prints the
+   **error envelope to stdout** (not stderr):
+
+   ```json
+   { "error": { "code": "not_logged_in", "message": "Run `flipstream auth login`.", "exit": 4 } }
+   ```
+
+   This is what makes `flipstream <cmd> --json 2>/dev/null | jq .` work on
+   **both** success and failure. Branch on `error.code` (stable) and/or the
+   process exit code — never on the message wording (which may be reworded).
+
+   **Envelope remediation fields (E11-1, additive — absent unless set, never
+   `null`). "Envelope v3" refers to this error-envelope shape; it ships in
+   CONTRACT_VERSION 3:**
+
+   ```json
+   { "error": {
+       "code": "missing_connection_id", "message": "Missing --connection-id.", "exit": 2,
+       "hint": "List your connections and pass one of their ids.",
+       "next": ["flipstream connections list --json"],
+       "docs": "docs/AGENT-CONTRACT.md",
+       "retryable": false,
+       "retry_after_ms": 30000,
+       "upstream_code": "ENGINE_FAILED"
+   } }
+   ```
+
+   - `hint` — one imperative sentence: what to do next.
+   - `next` — ready-to-run command lines, most useful first. **Prefer executing
+     these over guessing** — they name the discovery command that produces
+     whatever was missing. Execute them **argv-split, never via `sh -c`**: they
+     are CLI-authored, redacted, and any interpolated value is validated against
+     a conservative charset, but they are not shell-quoted.
+   - `docs` — a URL or repo path for the failure class.
+   - `retryable` — `true`: re-running the SAME command may succeed (429/5xx/
+     transport). `false`: it deterministically fails again — do **not** retry
+     unchanged. Absent: unknown; use the exit code (7/8 lean retryable).
+   - `retry_after_ms` — server-stated wait (from `Retry-After`), only ever
+     alongside `retryable: true`, and clamped to at most 3 600 000 (one hour) —
+     a hostile header can never park an agent indefinitely.
+   - `upstream_code` — the backing service's own error code verbatim (e.g. the
+     planner's `ENGINE_FAILED` vs `UNKNOWN_DIMENSION`), for branching on the
+     upstream taxonomy when our `code` alone is too coarse.
+
+   Decision procedure: `retryable && retry_after_ms` → wait, retry. `retryable
+   === false` → change something (follow `next`) before any retry. Otherwise →
+   branch on `code`/exit as before. Human mode prints the same facts as
+   indented `hint:`/`next:`/`docs:`/`retry:` lines on stderr.
+4. **No secrets, ever.** No token / `Authorization` header / `code` / verifier
+   appears on stdout, stderr, argv, or in any error — including a malicious DATA
+   response that echoes a token-shaped key (it is redacted). No command exposes a
+   `--token`/`--secret`/`--verifier`/`--bearer` flag.
+5. **No telemetry / no phone-home.** The only network calls are to the OAuth
+   provider and the data host you query.
+
+## Exit codes (`src/lib/exit-codes.ts`)
+
+| code | name | meaning | agent guidance |
+|---|---|---|---|
+| 0 | success | data emitted | use the output |
+| 1 | generic | unclassified failure (incl. non-auth data 4xx) | inspect `error.message` |
+| 2 | usage | bad flags / unknown command / malformed input | fix the invocation |
+| 4 | auth-required | not logged in, or session expired | run `flipstream auth login` |
+| 5 | auth-failed | auth attempt rejected (state/iss/token/role/target) | re-auth / check permissions |
+| 7 | network | transport/discovery/upstream failure | retry later |
+| 8 | timeout | operation timed out | retry |
+
+## Observability sidecar & logs (E11-6, opt-in, local-only)
+
+None of this is ever sent anywhere — it is local files a supervising process
+opts into. It composes with `--json` rather than competing with it: stdout is
+untouched.
+
+- **`FLIPSTREAM_OUTPUT_FILE=<path>`** (or **`FLIPSTREAM_OUTPUT_FILE_DIRECTORY=<dir>`**
+  for a timestamped file) → one JSON object per line, each with its own
+  `version` so entry schemas evolve independently:
+  - `{type:"session", version:1, cli_version, contract_version, argv, log_file_path, timestamp}` (before the command runs; `argv` is redacted and capped)
+  - `{type:"result", version:1, command, duration_ms, exit:0, timestamp}` (clean exit)
+  - `{type:"command-failed", version:1, command, error_code, exit, message, log_file_path, retry_after_ms?, timestamp}` (failure)
+  Files are created `0600`. A write failure disables the sidecar for the run
+  and prints one stderr notice.
+- **`FLIPSTREAM_LOG=debug`** → request/response wire trace on stderr (headers
+  never traced; bodies omitted unless the escape hatch below is set).
+- **`FLIPSTREAM_LOG_SANITIZE=false`** → include redacted bodies in the trace.
+  This ALSO writes them to the run log even without `--verbose`, so it prints a
+  one-time stderr notice; the redaction floor (token masking) still applies.
+- Per-run logs live under `$XDG_STATE_HOME/flipstream-cli/logs/` (`0600`, newest
+  20 kept); a failing command prints `🪵 Logs were written to <path>` on stderr
+  in human mode.
+
+## Per-command `--json` shapes
+
+| command | success shape (stdout) |
+|---|---|
+| `version` | `{version, node, platform, contractVersion}` |
+| `auth login` | redacted decoded token claims (object) or `null` |
+| `auth status` | `{host, loggedIn}` — when logged in adds `{account, expired, expiresAt, scopes}` |
+| `auth logout` | `{host, loggedOut, revoked}` |
+| `auth clear-all` | `{clearedHosts, configRemoved}` |
+| `query` | the planner/engine response, verbatim (redacted); the CLI adds no fields. Under `--dry-run`, the `LogicalRequest` body instead — and nothing is sent |
+| `catalog` | the catalog document as served: `{sources:[…], defaultSource}`, or one source `{name, label, description, dimensions:[…], metrics:[…]}` |
+| `health` | the planner's health document (e.g. `{status:"ok"}`); needs no auth |
+| `contract` | `{contractVersion, markdown}` — this document; needs no auth |
+| `skills install` | `{installed:[{agent, path, status, backup?}]}` — `status` is `installed`/`updated`/`unchanged`; `backup` set when a differing local copy was preserved |
+| `ws list` · `ws connections` · `conn list` · `log list` | a list envelope `{count, records}`; each record is a projected object with a redacted `raw` passthrough (`--ndjson` streams the records) |
+| `log add` | the created log entry (projected object with a redacted `raw`) |
+
+### The `query` request shape (`LogicalRequest`)
+
+You name a **source**, then name dimensions, metrics and filters using the names
+`catalog <source>` prints. Which physical table answers that is the planner's
+problem, not yours — and it never tells you, by design.
+
+| field | flag | notes |
+|---|---|---|
+| `source` | `--source` | dataset discriminator, e.g. `gsc`. A source name, never a table |
+| `connection_id` | `--connection-id` | a UUID, or a **name** the CLI resolves (ambiguity is refused, exit 2) |
+| `dimensions` | `-d` (repeatable) | the group-by |
+| `metrics` | `-m` (repeatable) | |
+| `filters` | `-f` (repeatable) | `col=a,b` · `col=from..to` · `col=<json>`. **`col=` is refused** |
+| `sort` | `-s` (repeatable) | `FIELD[:asc\|desc]`, default `asc` |
+| `offset` / `rows` | `--offset` / `--rows` | default `0` / `100` |
+| `table` | `--table` | honoured only for an unmodelled source; ignored otherwise |
+
+**The filter gotcha, because it fails silently.** The routing predicate reads a
+selection by **length**: `[]` is length 0 (inactive → the summary table) and
+`[""]` is length 1 (active → the dimension's table). They mean different things,
+they are one comma apart, and neither warns — you just get different numbers. So
+`-f 'device='` is **refused** rather than guessed; write `device=[]` or
+`device=[""]` explicitly.
+
+The response is forwarded verbatim and is governed by the planner/engine, not
+this CLI. `--body`/`--body-file`/stdin still send a body verbatim for any shape
+the flags cannot express.
+
+## Error taxonomy
+
+`error.code` is stable; `exit` is the table above. Messages are illustrative.
+
+| `error.code` | exit | when | agent guidance |
+|---|---|---|---|
+| `usage` | 2 | bad flag / `--json`+`--ndjson` / planner 422 | fix the invocation |
+| `missing_source` | 2 | `query` flags path without `--source` | run `flipstream catalog`, pass a source |
+| `missing_connection_id` | 2 | `query` flags path without `--connection-id` | run `flipstream connections list`, pass an id |
+| `missing_source_and_connection_id` | 2 | `query` flags path missing both | follow `next` |
+| `missing_request` | 2 | bare `query` with empty piped stdin and no flags | build a request (see `next`) |
+| `invalid_body_json` | 2 | `--body`/`--body-file`/stdin body is not valid JSON | fix the body; message names its origin |
+| `rate_limited` | 7 | HTTP 429 from planner/admin | wait `retry_after_ms`, retry |
+| `non_interactive` | 2 | a prompt had no answerable context and no fallback | pass the named flag, or run interactively |
+| `prompt_aborted` | 2 | an interactive prompt was aborted (EOF / Ctrl-C) | re-run, or pass the named flag |
+| `contract_unavailable` | 1 | the packaged `AGENT-CONTRACT.md` is missing from this installation | reinstall the CLI |
+| `not_logged_in` | 4 | no stored session for the host | `auth login` |
+| `session_expired` | 4 | session existed but refresh was rejected | `auth login` (distinct from above) |
+| `auth_failed` | 5 | generic auth attempt failure | re-auth |
+| `state_mismatch` | 5 | loopback `state`/`iss` validation failed (possible CSRF) | retry login |
+| `token_exchange_failed` | 5 | `/oauth/token` rejected the exchange (e.g. `invalid_grant`) | retry login |
+| `data_auth_failed` | 5 | DATA/admin host returned 401 after refresh | re-auth |
+| `role_forbidden` | 5 | 403 — your role lacks permission for this action | check your role/permissions |
+| `invalid_target` | 5 | token audience rejected by the DATA host (defensive; not expected) | re-bind / contact support |
+| `discovery_failed` | 7 | OAuth discovery unreachable / invalid | retry later |
+| `network_error` | 7 | transport failure | retry later |
+| `data_upstream_error` | 7 | DATA host 5xx | retry later |
+| `loopback_timeout` / `timeout` | 8 | browser/loopback or request timed out | retry |
+| `not_found` | 1 | 404 — resource not found or not in your organization | verify the id / your org |
+| `data_request_failed` | 1 | other DATA/admin 4xx except 429 (surfaces the host's `detail`) | inspect `error.message` |
+
+Provider OAuth errors (`invalid_grant`, `access_denied` from clicking **Deny**,
+`invalid_client`, `unsupported_grant_type`) surface as `token_exchange_failed` /
+`auth_failed` (exit 5) with the provider's `<error>: <error_description>` message.
+
+## Consuming the CLI (the canonical pattern)
+
+```bash
+out=$(flipstream auth status --json 2>/dev/null); code=$?
+echo "$out" | jq .            # always valid JSON — data on 0, {error:…} otherwise
+[ "$code" -eq 4 ] && flipstream auth login
+```