flipstream 0.4.0 → 0.6.0

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": [
@@ -518,6 +817,9 @@
           "type": "option"
         },
         "workspace": {
+          "aliases": [
+            "ws"
+          ],
           "description": "List only this workspace's connections (UUID).",
           "name": "workspace",
           "hasDynamicHelp": false,
@@ -542,6 +844,302 @@
         "list.js"
       ]
     },
+    "log:add": {
+      "aliases": [
+        "logs:add"
+      ],
+      "args": {
+        "message": {
+          "description": "The log entry text.",
+          "name": "message",
+          "required": true
+        }
+      },
+      "description": "Add an entry to a workspace's log (the logbook). You give the workspace (--workspace/--ws) and the message; the organization is derived from the workspace, and the dates default to now (override with --start/--end). Returns the created entry. Targets the OAuth/admin host.",
+      "examples": [
+        "<%= config.bin %> log add \"shipped the new pipeline\" --workspace <id>",
+        "<%= config.bin %> log add \"kickoff call done\" --ws <id> --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"
+        },
+        "end": {
+          "description": "End date (ISO 8601). Defaults to now.",
+          "name": "end",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "start": {
+          "description": "Start date (ISO 8601). Defaults to now.",
+          "name": "start",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workspace": {
+          "aliases": [
+            "ws"
+          ],
+          "description": "Workspace id (UUID) the entry belongs to.",
+          "name": "workspace",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "log:add",
+      "pluginAlias": "flipstream",
+      "pluginName": "flipstream",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Add an entry to a workspace's log.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "log",
+        "add.js"
+      ]
+    },
+    "log:list": {
+      "aliases": [
+        "logs:list"
+      ],
+      "args": {},
+      "description": "Read a workspace's log entries (the logbook). --workspace is required — a log entry only makes sense in a workspace's context, so there is no account-wide read. Shows each entry's description, dates, and author; the full record (including any new fields like tags) is under --json. Targets the OAuth/admin host.",
+      "examples": [
+        "<%= config.bin %> log list --workspace <id>",
+        "<%= config.bin %> logs list --ws <id> --json",
+        "<%= config.bin %> log list --ws <id> --all"
+      ],
+      "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"
+        },
+        "all": {
+          "description": "Fetch every page (drains pagination).",
+          "name": "all",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "limit": {
+          "description": "Page size.",
+          "name": "limit",
+          "default": 50,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "offset": {
+          "description": "Starting offset.",
+          "name": "offset",
+          "default": 0,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "q": {
+          "description": "Free-text filter.",
+          "name": "q",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "sort": {
+          "description": "Sort field.",
+          "name": "sort",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workspace": {
+          "aliases": [
+            "ws"
+          ],
+          "description": "The workspace whose log to read (UUID).",
+          "name": "workspace",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "log:list",
+      "pluginAlias": "flipstream",
+      "pluginName": "flipstream",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Read a workspace's log entries.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "log",
+        "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"
@@ -847,5 +1445,5 @@
       ]
     }
   },
-  "version": "0.4.0"
+  "version": "0.6.0"
 }