flipstream 0.5.0 → 0.6.1

package/oclif.manifest.json

@@ -1,13 +1,232 @@
 {
   "commands": {
+    "catalog": {
+      "aliases": [],
+      "args": {
+        "source": {
+          "description": "A source name (omit to list every source).",
+          "name": "source",
+          "required": false
+        }
+      },
+      "description": "Print the request vocabulary the query planner accepts. The names shown ARE what `query` takes: `-d` and `-m` and filter keys use an item's `name` (the wire name, e.g. search_date), never its `label` (what a human reads, e.g. Date). Read from the SERVICE, never from a local data-model checkout — the two differ exactly when it matters most, right after a version bump.",
+      "examples": [
+        "<%= config.bin %> catalog",
+        "<%= config.bin %> catalog gsc",
+        "<%= config.bin %> catalog gsc --json"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "host": {
+          "char": "H",
+          "description": "OAuth provider host (defaults to the prod issuer).",
+          "name": "host",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ndjson": {
+          "description": "Stream output as NDJSON (one compact JSON object per line).",
+          "name": "ndjson",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Network timeout in milliseconds.",
+          "name": "timeout",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "verbose": {
+          "aliases": [
+            "debug"
+          ],
+          "description": "Print redacted diagnostics to stderr.",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "auth-host": {
+          "description": "OAuth issuer host for credentials/refresh (defaults to the prod issuer).",
+          "name": "auth-host",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "url": {
+          "description": "Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "catalog",
+      "pluginAlias": "flipstream",
+      "pluginName": "flipstream",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show the dimensions and metrics a source accepts.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "catalog.js"
+      ]
+    },
+    "contract": {
+      "aliases": [],
+      "args": {},
+      "description": "Print docs/AGENT-CONTRACT.md — the frozen machine contract (output modes, exit codes, error envelope, per-command JSON shapes) — to stdout, from the installed package, no network needed. Context self-service for agents: read this before driving the CLI programmatically.",
+      "examples": [
+        "<%= config.bin %> contract",
+        "<%= config.bin %> contract --json"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "host": {
+          "char": "H",
+          "description": "OAuth provider host (defaults to the prod issuer).",
+          "name": "host",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ndjson": {
+          "description": "Stream output as NDJSON (one compact JSON object per line).",
+          "name": "ndjson",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Network timeout in milliseconds.",
+          "name": "timeout",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "verbose": {
+          "aliases": [
+            "debug"
+          ],
+          "description": "Print redacted diagnostics to stderr.",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "contract",
+      "pluginAlias": "flipstream",
+      "pluginName": "flipstream",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Print the agent contract (machine-facing promises) to stdout.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "contract.js"
+      ]
+    },
+    "health": {
+      "aliases": [],
+      "args": {},
+      "description": "Check that the query planner is answering. This is the ONE endpoint that takes no token, so it separates \"the service is down\" from \"my credentials are wrong\" before any auth debugging starts.",
+      "examples": [
+        "<%= config.bin %> health",
+        "<%= config.bin %> health --json",
+        "<%= config.bin %> health --url http://localhost:8080"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "host": {
+          "char": "H",
+          "description": "OAuth provider host (defaults to the prod issuer).",
+          "name": "host",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ndjson": {
+          "description": "Stream output as NDJSON (one compact JSON object per line).",
+          "name": "ndjson",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Network timeout in milliseconds.",
+          "name": "timeout",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "verbose": {
+          "aliases": [
+            "debug"
+          ],
+          "description": "Print redacted diagnostics to stderr.",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "url": {
+          "description": "Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "health",
+      "pluginAlias": "flipstream",
+      "pluginName": "flipstream",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Check that the query planner is reachable.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "health.js"
+      ]
+    },
     "query": {
       "aliases": [],
       "args": {},
-      "description": "Send an OPAQUE JSON body (--body, --body-file, or piped stdin) to the Flipstream data API and print the structured JSON response. The CLI never constructs, validates, or transforms the query payload — the body is forwarded verbatim (your agent/Skill builds it).",
+      "description": "Send a LOGICAL query (source + dimensions + metrics + filters) to the Flipstream query planner, which resolves which physical table answers it and returns the rows. Run `flipstream catalog <source>` first — the names it prints ARE what -d, -m and filter keys take. --body/--body-file/stdin still forwards a JSON body verbatim for shapes the flags cannot express.",
       "examples": [
-        "<%= config.bin %> query --body '{\"opaque\":true}'",
-        "echo '{\"opaque\":true}' | <%= config.bin %> query",
-        "<%= config.bin %> query --body-file query.json --json"
+        "<%= config.bin %> catalog gsc",
+        "<%= config.bin %> query --source gsc --connection-id <id|name> -d search_date -d query -m clicks -f 'search_date=2026-01-01..2026-02-01' --rows 20",
+        "<%= config.bin %> query --source gsc --connection-id <id> -d query -m clicks --dry-run",
+        "<%= config.bin %> query --body-file request.json --json"
       ],
       "flags": {
         "json": {
@@ -54,8 +273,15 @@
           "multiple": false,
           "type": "option"
         },
+        "url": {
+          "description": "Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "body": {
-          "description": "Opaque JSON request body as a string.",
+          "description": "Send this JSON body verbatim.",
           "exclusive": [
             "body-file"
           ],
@@ -65,11 +291,84 @@
           "type": "option"
         },
         "body-file": {
-          "description": "Path to a file holding the opaque JSON request body.",
+          "description": "Path to a file holding the JSON body verbatim (\"-\" reads stdin).",
           "name": "body-file",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "connection-id": {
+          "description": "Connection UUID, or a name to look up.",
+          "name": "connection-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dimension": {
+          "char": "d",
+          "description": "Dimension name (repeatable).",
+          "name": "dimension",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "dry-run": {
+          "description": "Print the request body and send nothing.",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "filter": {
+          "char": "f",
+          "description": "Filter as col=a,b | col=from..to | col=<json> (repeatable). 'col=' is refused.",
+          "name": "filter",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "metric": {
+          "char": "m",
+          "description": "Metric name (repeatable).",
+          "name": "metric",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "offset": {
+          "description": "Row offset.",
+          "name": "offset",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "rows": {
+          "description": "Row limit (default 100).",
+          "name": "rows",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "sort": {
+          "char": "s",
+          "description": "FIELD[:asc|desc] (repeatable).",
+          "name": "sort",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "source": {
+          "description": "The dataset discriminator, e.g. gsc.",
+          "name": "source",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "table": {
+          "description": "Physical table — honoured only for an unmodelled source.",
+          "name": "table",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -79,7 +378,7 @@
       "pluginName": "flipstream",
       "pluginType": "core",
       "strict": true,
-      "summary": "Run an opaque query against the Flipstream data API.",
+      "summary": "Run a logical query against the Flipstream query planner.",
       "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
@@ -756,6 +1055,91 @@
         "list.js"
       ]
     },
+    "skills:install": {
+      "aliases": [],
+      "args": {},
+      "description": "Install the flipstream skill (SKILL.md) into the global skills directory of every detected AI coding agent (Claude Code, Codex, Cursor, OpenCode). Detection is local env/dir inspection only — nothing is reported anywhere. The skill teaches an agent to retrieve the command surface and data vocabulary from the CLI instead of guessing.",
+      "examples": [
+        "<%= config.bin %> skills install",
+        "<%= config.bin %> skills install --yes",
+        "<%= config.bin %> skills install --agent claude-code --agent codex"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "host": {
+          "char": "H",
+          "description": "OAuth provider host (defaults to the prod issuer).",
+          "name": "host",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ndjson": {
+          "description": "Stream output as NDJSON (one compact JSON object per line).",
+          "name": "ndjson",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Network timeout in milliseconds.",
+          "name": "timeout",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "verbose": {
+          "aliases": [
+            "debug"
+          ],
+          "description": "Print redacted diagnostics to stderr.",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "agent": {
+          "description": "Install for this agent id only (repeatable). Known: claude-code, codex, cursor, opencode.",
+          "name": "agent",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "options": [
+            "claude-code",
+            "codex",
+            "cursor",
+            "opencode"
+          ],
+          "type": "option"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Install without asking.",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "skills:install",
+      "pluginAlias": "flipstream",
+      "pluginName": "flipstream",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Install the flipstream skill for detected AI coding agents.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "skills",
+        "install.js"
+      ]
+    },
     "workspaces:connections": {
       "aliases": [
         "ws:connections"
@@ -1061,5 +1445,5 @@
       ]
     }
   },
-  "version": "0.5.0"
+  "version": "0.6.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flipstream",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Flipstream CLI — query your Flipstream data from the terminal.",
   "keywords": [
     "flipstream",
@@ -20,7 +20,9 @@
   "files": [
     "bin",
     "dist",
-    "oclif.manifest.json"
+    "oclif.manifest.json",
+    "skill",
+    "docs/AGENT-CONTRACT.md"
   ],
   "engines": {
     "node": ">=20"
@@ -35,7 +37,8 @@
     "posttest": "eslint .",
     "prepare": "husky || true",
     "smoke": "bun scripts/smoke.ts",
-    "test": "bun test"
+    "test": "bun test",
+    "schema:planner": "bun scripts/refresh-planner-schema.ts"
   },
   "lint-staged": {
     "*.ts": [
@@ -51,6 +54,7 @@
     "@oclif/core": "^4",
     "@oclif/plugin-commands": "^4.1.59",
     "@oclif/table": "^0.5.9",
+    "am-i-vibing": "^0.5.0",
     "open": "^11.0.0"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: flipstream
+description: Flipstream CLI for querying Flipstream data (query planner, catalog, connections, workspaces, auth). Load before running flipstream commands. Prefer retrieval over pre-training — enumerate the command surface and data vocabulary from the CLI itself instead of guessing flags or names.
+---
+
+# Flipstream CLI
+
+Your knowledge of flipstream flags, sources, dimensions and metrics may be
+outdated. **Prefer retrieval over pre-training** for any flipstream task.
+
+## Retrieval sources (run these instead of guessing)
+
+| What | Command |
+|---|---|
+| The whole command surface (ids, flags, args, aliases) | `flipstream commands --json` |
+| The machine contract (output modes, exit codes, error envelope) | `flipstream contract` |
+| The data vocabulary for queries | `flipstream catalog` then `flipstream catalog <source>` |
+| Your connections (ids for `--connection-id`) | `flipstream connections list --json` |
+| Session state, scopes | `flipstream auth status --json` |
+
+## Ground rules
+
+- **stdout is data, stderr is narration.** Under `--json`/`--ndjson`, stdout carries exactly one JSON document (or NDJSON lines) — even on failure: `flipstream <cmd> --json 2>/dev/null | jq .` always parses.
+- **Failures are envelopes.** `{error:{code, message, exit, hint?, next?, docs?, retryable?, retry_after_ms?, upstream_code?}}`. Branch on `code` and the exit code, never on message wording. If `next` is present, **run those commands** instead of guessing. If `retryable` is `false`, do not re-run unchanged. If `retryable` is `true` with `retry_after_ms`, wait that long and retry.
+- **Exit codes:** 0 ok · 1 generic · 2 usage · 4 auth needed (`flipstream auth login`) · 5 auth failed · 7 network/upstream (retryable) · 8 timeout.
+- **Auth is browser-based and keyring-only.** Never ask for, echo, or pass tokens; there is no `--token` flag. If a command exits 4, tell the user to run `flipstream auth login` in a terminal with a browser.
+
+## Querying
+
+1. `flipstream catalog <source>` FIRST — the `name` fields it prints ARE the only valid values for `-d`, `-m`, and filter keys (`label` is for humans; aliases do not exist).
+2. Build: `flipstream query --source <source> --connection-id <id|name> -d <dim> -m <metric> --json`
+3. Filters: `-f 'col=a,b'` (list), `-f 'col=from..to'` (inclusive range), `-f 'col=<json>'` (verbatim). Add `--dry-run` to print the request body without sending.
+
+### The filter gotcha (silent, load-bearing)
+
+The planner routes by selection LENGTH: `col=[]` (length 0) is inactive and
+routes to the SUMMARY table; `col=[""]` (length 1) is active and routes to the
+DIMENSION's table. They return different numbers and nothing warns. The CLI
+therefore refuses bare `col=` — when you mean one of those, write the JSON form
+explicitly, and don't "fix" the refusal by inventing a value.
+
+## Recipes
+
+```sh
+# Discover, then query
+flipstream catalog --json | jq '.sources[].name'
+flipstream connections list --json | jq '.records[] | {id, name}'
+flipstream query --source gsc --connection-id <id> -d search_date -m clicks --json 2>/dev/null | jq '.rows'
+
+# Stream large results
+flipstream workspaces list --ndjson
+
+# Inspect a failure programmatically
+flipstream query ... --json 2>/dev/null | jq '.error | {code, next, retryable}'
+```