flipstream 0.5.0 → 0.6.0

package/README.md

@@ -107,14 +107,18 @@ If you already removed the binary, clean up manually:
 * [`flipstream auth login`](#flipstream-auth-login)
 * [`flipstream auth logout`](#flipstream-auth-logout)
 * [`flipstream auth status`](#flipstream-auth-status)
+* [`flipstream catalog [SOURCE]`](#flipstream-catalog-source)
 * [`flipstream commands`](#flipstream-commands)
 * [`flipstream conn list`](#flipstream-conn-list)
 * [`flipstream connections list`](#flipstream-connections-list)
+* [`flipstream contract`](#flipstream-contract)
+* [`flipstream health`](#flipstream-health)
 * [`flipstream log add MESSAGE`](#flipstream-log-add-message)
 * [`flipstream log list`](#flipstream-log-list)
 * [`flipstream logs add MESSAGE`](#flipstream-logs-add-message)
 * [`flipstream logs list`](#flipstream-logs-list)
 * [`flipstream query`](#flipstream-query)
+* [`flipstream skills install`](#flipstream-skills-install)
 * [`flipstream version`](#flipstream-version)
 * [`flipstream workspaces connections ID`](#flipstream-workspaces-connections-id)
 * [`flipstream workspaces get ID`](#flipstream-workspaces-get-id)
@@ -240,6 +244,45 @@ EXAMPLES
   $ flipstream auth status --json
 ```
 
+## `flipstream catalog [SOURCE]`
+
+Show the dimensions and metrics a source accepts.
+
+```
+USAGE
+  $ flipstream catalog [SOURCE] [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose] [--auth-host
+    <value>] [--url <value>]
+
+ARGUMENTS
+  [SOURCE]  A source name (omit to list every source).
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --auth-host=<value>  OAuth issuer host for credentials/refresh (defaults to the prod issuer).
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --timeout=<value>    Network timeout in milliseconds.
+      --url=<value>        Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).
+      --verbose            Print redacted diagnostics to stderr.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Show the dimensions and metrics a source accepts.
+
+  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
+  $ flipstream catalog
+
+  $ flipstream catalog gsc
+
+  $ flipstream catalog gsc --json
+```
+
 ## `flipstream commands`
 
 List all flipstream commands.
@@ -351,6 +394,68 @@ EXAMPLES
   $ flipstream conn list --all
 ```
 
+## `flipstream contract`
+
+Print the agent contract (machine-facing promises) to stdout.
+
+```
+USAGE
+  $ flipstream contract [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose]
+
+FLAGS
+  -H, --host=<value>     OAuth provider host (defaults to the prod issuer).
+      --ndjson           Stream output as NDJSON (one compact JSON object per line).
+      --timeout=<value>  Network timeout in milliseconds.
+      --verbose          Print redacted diagnostics to stderr.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Print the agent contract (machine-facing promises) to stdout.
+
+  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
+  $ flipstream contract
+
+  $ flipstream contract --json
+```
+
+## `flipstream health`
+
+Check that the query planner is reachable.
+
+```
+USAGE
+  $ flipstream health [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose] [--url <value>]
+
+FLAGS
+  -H, --host=<value>     OAuth provider host (defaults to the prod issuer).
+      --ndjson           Stream output as NDJSON (one compact JSON object per line).
+      --timeout=<value>  Network timeout in milliseconds.
+      --url=<value>      Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).
+      --verbose          Print redacted diagnostics to stderr.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Check that the query planner is reachable.
+
+  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
+  $ flipstream health
+
+  $ flipstream health --json
+
+  $ flipstream health --url http://localhost:8080
+```
+
 ## `flipstream log add MESSAGE`
 
 Add an entry to a workspace's log.
@@ -517,18 +622,69 @@ EXAMPLES
 
 ## `flipstream query`
 
-Run an opaque query against the Flipstream data API.
+Run a logical query against the Flipstream query planner.
 
 ```
 USAGE
   $ flipstream query [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose] [--auth-host <value>]
-    [--body <value> | --body-file <value>]
+    [--url <value>] [--body <value> | --body-file <value>] [--connection-id <value>] [-d <value>...] [--dry-run] [-f
+    <value>...] [-m <value>...] [--offset <value>] [--rows <value>] [-s <value>...] [--source <value>] [--table <value>]
+
+FLAGS
+  -H, --host=<value>           OAuth provider host (defaults to the prod issuer).
+  -d, --dimension=<value>...   Dimension name (repeatable).
+  -f, --filter=<value>...      Filter as col=a,b | col=from..to | col=<json> (repeatable). 'col=' is refused.
+  -m, --metric=<value>...      Metric name (repeatable).
+  -s, --sort=<value>...        FIELD[:asc|desc] (repeatable).
+      --auth-host=<value>      OAuth issuer host for credentials/refresh (defaults to the prod issuer).
+      --body=<value>           Send this JSON body verbatim.
+      --body-file=<value>      Path to a file holding the JSON body verbatim ("-" reads stdin).
+      --connection-id=<value>  Connection UUID, or a name to look up.
+      --dry-run                Print the request body and send nothing.
+      --ndjson                 Stream output as NDJSON (one compact JSON object per line).
+      --offset=<value>         Row offset.
+      --rows=<value>           Row limit (default 100).
+      --source=<value>         The dataset discriminator, e.g. gsc.
+      --table=<value>          Physical table — honoured only for an unmodelled source.
+      --timeout=<value>        Network timeout in milliseconds.
+      --url=<value>            Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).
+      --verbose                Print redacted diagnostics to stderr.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Run a logical query against the Flipstream query planner.
+
+  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
+  $ flipstream catalog gsc
+
+  $ flipstream 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
+
+  $ flipstream query --source gsc --connection-id <id> -d query -m clicks --dry-run
+
+  $ flipstream query --body-file request.json --json
+```
+
+## `flipstream skills install`
+
+Install the flipstream skill for detected AI coding agents.
+
+```
+USAGE
+  $ flipstream skills install [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose] [--agent
+    claude-code|codex|cursor|opencode...] [-y]
 
 FLAGS
   -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
-      --auth-host=<value>  OAuth issuer host for credentials/refresh (defaults to the prod issuer).
-      --body=<value>       Opaque JSON request body as a string.
-      --body-file=<value>  Path to a file holding the opaque JSON request body.
+  -y, --yes                Install without asking.
+      --agent=<option>...  Install for this agent id only (repeatable). Known: claude-code, codex, cursor, opencode.
+                           <options: claude-code|codex|cursor|opencode>
       --ndjson             Stream output as NDJSON (one compact JSON object per line).
       --timeout=<value>    Network timeout in milliseconds.
       --verbose            Print redacted diagnostics to stderr.
@@ -537,18 +693,18 @@ GLOBAL FLAGS
   --json  Format output as json.
 
 DESCRIPTION
-  Run an opaque query against the Flipstream data API.
+  Install the flipstream skill for detected AI coding agents.
 
-  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).
+  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
-  $ flipstream query --body '{"opaque":true}'
+  $ flipstream skills install
 
-  echo '{"opaque":true}' | flipstream query
+  $ flipstream skills install --yes
 
-  $ flipstream query --body-file query.json --json
+  $ flipstream skills install --agent claude-code --agent codex
 ```
 
 ## `flipstream version`

package/dist/commands/auth/login.js

@@ -44,6 +44,12 @@ export default class AuthLogin extends BaseCommand {
         }
         // Emit only the (redacted) decoded claims — never the raw token.
         const claims = redact(result.claims);
-        return this.respond(claims, (data) => this.log(JSON.stringify(data)));
+        return this.respond(claims, (data) => {
+            this.log(JSON.stringify(data));
+            // Close the loop (E11-3, #102): a fresh login has exactly two sensible
+            // next moves — prove the pipe works, then learn the vocabulary.
+            this.footer(`\nNext: ${this.config.bin} health   (checks the query planner is reachable)\n` +
+                `      ${this.config.bin} catalog  (lists the sources you can query)`);
+        });
     }
 }

package/dist/commands/auth/status.js

@@ -1,8 +1,15 @@
 import { tokenClaims } from '../../lib/auth/claims.js';
 import { BaseCommand } from '../../lib/command/base.js';
 import { ExitCode } from '../../lib/exit-codes.js';
-import { redact } from '../../lib/output/redact.js';
+import { isCI } from '../../lib/output/interactivity.js';
+import { maskAccount, redact } from '../../lib/output/redact.js';
 import { createStore } from '../../lib/store/index.js';
+// 'expires in 25m' below an hour, 'expires in 2h' above — never a rounded-to-0h.
+function formatRemaining(seconds) {
+    if (seconds < 3600)
+        return `${Math.max(1, Math.round(seconds / 60))}m`;
+    return `${Math.round(seconds / 3600)}h`;
+}
 export default class AuthStatus extends BaseCommand {
     static description = 'Show the current Flipstream authentication status for a host.';
     static examples = ['<%= config.bin %> auth status', '<%= config.bin %> auth status --json'];
@@ -37,11 +44,30 @@ export default class AuthStatus extends BaseCommand {
             scopes: creds.scopes,
         });
         return this.respond(status, () => {
-            const relative = expired ? 'expired' : `expires in ${Math.round((creds.expiresAt - nowSeconds) / 3600)}h`;
+            // ONE formatter for both the stdout line and the stderr note — a status
+            // command must not contradict itself about its own subject (E11-2 review).
+            const remaining = formatRemaining(creds.expiresAt - nowSeconds);
+            const relative = expired ? 'expired' : `expires in ${remaining}`;
+            // Disclosure tier (E11-4): mask the account in CI human output. This is
+            // HYGIENE for the human line, not a privacy control — the --json path
+            // (the one agents/CI actually consume) keeps the stable value by
+            // contract, so a public build log is not made safe by this alone.
+            const shown = typeof displayAccount === 'string' ? displayAccount : 'unknown';
             this.log(`Logged in to ${host}`);
-            this.log(`  account: ${typeof displayAccount === 'string' ? displayAccount : 'unknown'}`);
+            this.log(`  account: ${isCI() ? maskAccount(shown) : shown}`);
             this.log(`  expires: ${expiresAtIso} (${relative})`);
             this.log(`  scopes:  ${creds.scopes.join(' ')}`);
+            // Expiry narration (E11-2, #101): state the consequence, not just the fact.
+            // An expired ACCESS token is normal — commands refresh it on use — so the
+            // warning names the failure mode that actually needs the human (refresh
+            // rejected → session_expired) rather than crying wolf.
+            if (expired) {
+                this.note('the access token has expired; commands refresh it automatically — if one fails with ' +
+                    'session_expired, run `flipstream auth login`');
+            }
+            else if (creds.expiresAt - nowSeconds < 24 * 3600) {
+                this.note(`the access token expires in ${remaining} and will refresh automatically on use`);
+            }
         });
     }
 }

package/dist/commands/catalog.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../lib/command/base.js';
+export default class Catalog extends BaseCommand<typeof Catalog> {
+    static args: {
+        source: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'auth-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<unknown>;
+    private renderSource;
+}

package/dist/commands/catalog.js

@@ -0,0 +1,110 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../lib/command/base.js';
+import { plannerFlags } from '../lib/command/flags.js';
+import { authedPlannerClient } from '../lib/command/planner.js';
+import { resolveHost, resolvePlannerUrl } from '../lib/config/xdg.js';
+import { AuthRequiredError } from '../lib/errors.js';
+import { redact } from '../lib/output/redact.js';
+import { sanitizeTerminal } from '../lib/output/sanitize.js';
+import { renderTable } from '../lib/output/table.js';
+import { parseCatalogIndex, parseCatalogSource } from '../lib/planner/catalog.js';
+import { mapCatalogError } from '../lib/planner/errors.js';
+import { createStore } from '../lib/store/index.js';
+export default class Catalog extends BaseCommand {
+    static args = {
+        source: Args.string({
+            description: 'A source name (omit to list every source).',
+            // oclif fills a MISSING positional from stdin when stdin is not a TTY, so
+            // `echo x | flipstream catalog` would silently become `catalog x` — and a
+            // spawned process (the normal case for an agent) has a non-TTY stdin it may
+            // never close, which makes that read hang forever. Nothing here wants stdin.
+            ignoreStdin: true,
+            required: false,
+        }),
+    };
+    static 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.';
+    static examples = [
+        '<%= config.bin %> catalog',
+        '<%= config.bin %> catalog gsc',
+        '<%= config.bin %> catalog gsc --json',
+    ];
+    static flags = { ...plannerFlags };
+    static summary = 'Show the dimensions and metrics a source accepts.';
+    async run() {
+        const url = resolvePlannerUrl({ urlFlag: this.flags.url });
+        const authHost = resolveHost({ hostFlag: this.flags['auth-host'] ?? this.flags.host });
+        const store = createStore();
+        if (!store.load(authHost))
+            throw AuthRequiredError.notLoggedIn();
+        const client = authedPlannerClient({ authHost, store, timeoutMs: this.flags.timeout, url });
+        const { source } = this.args;
+        let raw;
+        const started = Date.now();
+        try {
+            raw = await client.getCatalog(source, { timeoutMs: this.flags.timeout });
+        }
+        catch (error) {
+            throw mapCatalogError(error, { bin: this.config.bin, source, url });
+        }
+        // Which host answered (E11-2): the planner and the admin API are different
+        // origins, and "which one did I just talk to" is the first debugging question.
+        this.verboseLog(`GET ${url}/catalog${source === undefined ? '' : `/${source}`} (${Date.now() - started} ms)`);
+        // Redact BEFORE the document becomes output, exactly as `query` does. The
+        // served catalog is an allowlist projection built by data-model, so nothing
+        // secret should be in it — but "should" is the service's promise, and this is
+        // our own output boundary. A projection here would instead drop fields the
+        // service legitimately adds, so redaction (which masks secret-NAMED keys and
+        // leaves the rest untouched) is the right tool: it keeps `--json` faithful to
+        // the document as served while still refusing to print a credential.
+        const payload = redact(raw);
+        if (source === undefined) {
+            const index = parseCatalogIndex(payload);
+            return this.respond(payload, () => {
+                renderTable(index.sources.map((entry) => ({ ...entry })), [
+                    { key: 'name', name: 'Source' },
+                    { key: 'label', name: 'Label' },
+                    { key: 'dimensions', name: 'Dimensions' },
+                    { key: 'metrics', name: 'Metrics' },
+                ], 'No sources.');
+                // Footer to STDERR: it is guidance, not data, and stdout must stay clean.
+                const hint = index.defaultSource === undefined ? '' : `, default ${index.defaultSource}`;
+                this.footer(`\n${index.sources.length} source(s)${hint}; \`${this.config.bin} catalog ${index.defaultSource ?? '<source>'}\` for its names`);
+            });
+        }
+        const entry = parseCatalogSource(payload);
+        return this.respond(payload, () => this.renderSource(entry));
+    }
+    renderSource(entry) {
+        this.log(sanitizeTerminal(`${entry.name} — ${entry.label}`));
+        if (entry.description)
+            this.log(sanitizeTerminal(entry.description));
+        for (const [heading, items] of [
+            ['DIMENSIONS', entry.dimensions],
+            ['METRICS', entry.metrics],
+        ]) {
+            this.log(`\n${heading}`);
+            renderTable(items.map((item) => ({ ...item })), [
+                { key: 'name', name: 'Name' },
+                { key: 'label', name: 'Label' },
+                { key: 'type', name: 'Type' },
+                { key: 'description', name: 'Description' },
+            ], '(none)');
+        }
+        if (entry.customDimensionsMax !== undefined) {
+            this.log(`\nCUSTOM DIMENSIONS  up to ${entry.customDimensionsMax} per connection`);
+        }
+        // A runnable next command built from THIS source's real names (E11-3, #102):
+        // the reader of a catalog is one edit away from a working query, so hand
+        // them that edit. stderr — guidance, not data.
+        const dimension = entry.dimensions[0]?.name;
+        const metric = entry.metrics[0]?.name;
+        if (dimension !== undefined && metric !== undefined) {
+            this.footer(`\nTry: ${this.config.bin} query --source ${entry.name} --connection-id <id|name> ` +
+                `-d ${dimension} -m ${metric} --json\n` +
+                `     (${this.config.bin} connections list prints the ids)`);
+        }
+    }
+}

package/dist/commands/connections/list.d.ts

@@ -16,4 +16,5 @@ export default class ConnectionsList extends BaseCommand<typeof ConnectionsList>
         count: number;
         records: unknown[];
     }>;
+    private printUsageFooter;
 }

package/dist/commands/connections/list.js

@@ -30,6 +30,7 @@ export default class ConnectionsList extends BaseCommand {
         if (!store.load(host))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
+        const startedMs = Date.now();
         const projected = await fetchConnections(client, {
             all: this.flags.all,
             limit: this.flags.limit,
@@ -39,6 +40,31 @@ export default class ConnectionsList extends BaseCommand {
             workspace,
         });
         await hydrate(client, projected.records, [WORKSPACE_NAME]);
-        return this.respondList(projected, (records) => renderConnectionsTable(records));
+        // Which origin answered (E11-2): planner vs admin is the first debugging question.
+        this.verboseLog(`GET ${host}/connections (${Date.now() - startedMs} ms)`);
+        return this.respondList(projected, (records) => {
+            renderConnectionsTable(records);
+            this.printUsageFooter(records);
+        });
+    }
+    // The exact next command with a REAL id from the results (E11-3, #102) — the
+    // whole reason an agent lists connections is to feed one into `query`.
+    // stderr — guidance, not data; only in the human path (respondList gates it).
+    printUsageFooter(records) {
+        const first = records.find((record) => {
+            const candidate = record;
+            return typeof candidate?.id === 'string' && candidate.active !== false;
+        });
+        if (first === undefined) {
+            // All-inactive is exactly when the reader is about to be confused:
+            // `query` will refuse every one of these ids.
+            if (records.length > 0) {
+                this.footer('\nNo ACTIVE connection in these results — query refuses an inactive connection.');
+            }
+            return;
+        }
+        // The id is a server-supplied string — footer() redacts + sanitizes it.
+        this.footer(`\nTry: ${this.config.bin} query --source <source> --connection-id ${first.id} -d <dim> -m <metric> --json\n` +
+            `     (${this.config.bin} catalog lists the sources and their names)`);
     }
 }

package/dist/commands/contract.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../lib/command/base.js';
+export default class Contract extends BaseCommand<typeof Contract> {
+    static description: string;
+    static examples: string[];
+    static flags: {};
+    static summary: string;
+    run(): Promise<{
+        contractVersion: string;
+        markdown: string;
+    }>;
+}

package/dist/commands/contract.js

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BaseCommand } from '../lib/command/base.js';
+import { CONTRACT_VERSION } from '../lib/config/constants.js';
+import { CliError } from '../lib/errors.js';
+import { ExitCode } from '../lib/exit-codes.js';
+// <package root>/docs/AGENT-CONTRACT.md, resolved relative to this module so it
+// works from dist in the published tarball and from src in dev.
+function contractPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', '..', 'docs', 'AGENT-CONTRACT.md');
+}
+export default class Contract extends BaseCommand {
+    static 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.';
+    static examples = ['<%= config.bin %> contract', '<%= config.bin %> contract --json'];
+    static flags = {};
+    static summary = 'Print the agent contract (machine-facing promises) to stdout.';
+    async run() {
+        let markdown;
+        try {
+            markdown = readFileSync(contractPath(), 'utf8');
+        }
+        catch {
+            // Never a raw ENOENT: the class name is not a contract code, and the
+            // absolute path (with the OS username) does not belong on stdout.
+            throw new CliError('The packaged agent contract is missing from this installation.', 'contract_unavailable', ExitCode.GENERIC).withDetails({ hint: 'Reinstall the CLI: npm i -g flipstream', retryable: false });
+        }
+        // The document IS the data here, so human mode prints it verbatim on
+        // stdout; --json wraps it with the version for programmatic consumers.
+        return this.respond({ contractVersion: CONTRACT_VERSION, markdown }, () => this.log(markdown));
+    }
+}

package/dist/commands/health.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../lib/command/base.js';
+export default class Health extends BaseCommand<typeof Health> {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<unknown>;
+}

package/dist/commands/health.js

@@ -0,0 +1,31 @@
+import { Flags } from '@oclif/core';
+import { mapDataError } from '../lib/api/errors.js';
+import { BaseCommand } from '../lib/command/base.js';
+import { resolvePlannerUrl } from '../lib/config/xdg.js';
+import { getPlannerHealth } from '../lib/planner/client.js';
+export default class Health extends BaseCommand {
+    static 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.';
+    static examples = [
+        '<%= config.bin %> health',
+        '<%= config.bin %> health --json',
+        '<%= config.bin %> health --url http://localhost:8080',
+    ];
+    static flags = {
+        url: Flags.string({
+            description: 'Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).',
+        }),
+    };
+    static summary = 'Check that the query planner is reachable.';
+    async run() {
+        const url = resolvePlannerUrl({ urlFlag: this.flags.url });
+        let payload;
+        try {
+            payload = await getPlannerHealth(url, { timeoutMs: this.flags.timeout });
+        }
+        catch (error) {
+            throw mapDataError(error);
+        }
+        return this.respond(payload, (data) => this.log(JSON.stringify(data, null, 2)));
+    }
+}

package/dist/commands/log/add.js

@@ -8,7 +8,7 @@ import { createStore } from '../../lib/store/index.js';
 export default class LogAdd extends BaseCommand {
     static aliases = ['logs:add'];
     static args = {
-        message: Args.string({ description: 'The log entry text.', required: true }),
+        message: Args.string({ description: 'The log entry text.', ignoreStdin: true, required: true }),
     };
     static 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). ' +
@@ -20,7 +20,11 @@ export default class LogAdd extends BaseCommand {
     static flags = {
         end: Flags.string({ description: 'End date (ISO 8601). Defaults to now.' }),
         start: Flags.string({ description: 'Start date (ISO 8601). Defaults to now.' }),
-        workspace: Flags.string({ aliases: ['ws'], description: 'Workspace id (UUID) the entry belongs to.', required: true }),
+        workspace: Flags.string({
+            aliases: ['ws'],
+            description: 'Workspace id (UUID) the entry belongs to.',
+            required: true,
+        }),
     };
     static summary = "Add an entry to a workspace's log.";
     async run() {

package/dist/commands/query.d.ts

@@ -3,11 +3,24 @@ export default class Query extends BaseCommand<typeof Query> {
     static description: string;
     static examples: string[];
     static flags: {
-        'auth-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         body: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'body-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'connection-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dimension: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        filter: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        metric: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        offset: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        rows: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        sort: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        source: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        table: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'auth-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static summary: string;
     run(): Promise<unknown>;
-    private parseBody;
+    private engineFailureDetails;
+    private enrichPlannerError;
+    private readVerbatimBody;
 }