flipstream 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flipstream",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "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"
@@ -33,14 +35,26 @@
     "lint": "eslint .",
     "pack:prepare": "tsc -p tsconfig.json && oclif manifest",
     "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": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,yml,yaml}": [
+      "prettier --write"
+    ]
   },
   "dependencies": {
     "@napi-rs/keyring": "^1.3.0",
     "@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": {
@@ -51,6 +65,8 @@
     "eslint": "^10.4.1",
     "eslint-config-oclif": "^6.0.166",
     "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.7",
     "oclif": "^4.23.8",
     "prettier": "^3.8.3",
     "typescript": "^5"
@@ -73,6 +89,9 @@
       },
       "connections": {
         "description": "List your data-source connections, org-wide or per workspace (alias: conn)."
+      },
+      "log": {
+        "description": "Read and add workspace log entries — the logbook (list, add; alias: logs)."
       }
     }
   }

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}'
+```

package/dist/lib/auth/register.d.ts

@@ -1,4 +0,0 @@
-import type { Metadata } from './discovery.js';
-export declare function registerClient(meta: Metadata, redirectUri: string, scopes: string[], options?: {
-    timeoutMs?: number;
-}): Promise<string>;

package/dist/lib/auth/register.js

@@ -1,43 +0,0 @@
-import { CLIENT_NAME } from '../config/constants.js';
-import { AuthFailedError } from '../errors.js';
-// Dynamically register a PUBLIC OAuth client (RFC 7591) and return its
-// client_id. The CLI never requests, parses, or stores a client secret — the
-// return type is the bare client_id string so a refactor cannot leak a secret.
-export async function registerClient(meta, redirectUri, scopes, options = {}) {
-    const timeoutMs = options.timeoutMs ?? 30_000;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    const body = {
-        client_name: CLIENT_NAME,
-        grant_types: ['authorization_code', 'refresh_token'],
-        redirect_uris: [redirectUri],
-        response_types: ['code'],
-        scope: scopes.join(' '),
-        token_endpoint_auth_method: 'none',
-    };
-    let response;
-    try {
-        response = await fetch(meta.registrationEndpoint, {
-            body: JSON.stringify(body),
-            headers: { accept: 'application/json', 'content-type': 'application/json' },
-            method: 'POST',
-            signal: controller.signal,
-        });
-    }
-    catch (error) {
-        const reason = controller.signal.aborted ? `timed out after ${timeoutMs}ms` : error.message;
-        throw new AuthFailedError(`Client registration failed: ${reason}`, 'registration_failed');
-    }
-    finally {
-        clearTimeout(timer);
-    }
-    if (response.status >= 400) {
-        const text = await response.text().catch(() => '');
-        throw new AuthFailedError(`Client registration failed: HTTP ${response.status} ${text}`.trim(), 'registration_failed');
-    }
-    const json = (await response.json().catch(() => ({})));
-    if (typeof json.client_id !== 'string' || json.client_id.length === 0) {
-        throw new AuthFailedError('Client registration response did not include a client_id', 'registration_failed');
-    }
-    return json.client_id;
-}