flipstream 0.4.0 → 0.5.0

package/README.md

@@ -6,25 +6,20 @@ authenticates once and prints clean **structured JSON** for AI coding agents.
 > **Architecture:** this supersedes `flipstream-cli-kickoff.md`. See [`CLAUDE.md`](./CLAUDE.md)
 > for the corrected model (thin client, two hosts, **no natural-language "ask"**).
 
-## Prerequisites
-
-- [Bun](https://bun.sh) (development toolchain)
-- Node.js **20+** (the published CLI runs under Node)
-
-## Install (development)
+## Install
 
 ```sh
-bun install
-bun run build
+npm i -g flipstream   # requires Node.js 20+
 ```
 
 ## Usage
 
 ```sh
-./bin/run.js --help          # or during dev: bun bin/dev.js --help
-./bin/run.js --version
-./bin/run.js version --json  # {version,node,platform,contractVersion}
-./bin/run.js auth login      # opens the browser to sign in (OAuth2 + PKCE)
+flipstream --help
+flipstream --version
+flipstream version --json  # {version,node,platform,contractVersion}
+flipstream auth login      # opens the browser to sign in (OAuth2 + PKCE)
+flipstream ws list         # list your organization's workspaces
 ```
 
 ## For agents (Claude Code / Codex / MCP)
@@ -46,19 +41,30 @@ taxonomy, per-command shapes, `CONTRACT_VERSION`) lives in
 [`docs/AGENT-CONTRACT.md`](./docs/AGENT-CONTRACT.md) and is enforced by a
 conformance suite.
 
-## Scripts
+## Development
+
+Built with [Bun](https://bun.sh); the published CLI runs under **Node.js 20+**.
+
+```sh
+bun install
+bun run build
+./bin/run.js --help        # run from source (or during dev: bun bin/dev.js --help)
+```
+
+Scripts:
 
 - `bun run build` — compile TypeScript to `dist/`
 - `bun run lint` — eslint (flat config)
 - `bun run check:secrets` — static deny-list gate over `src/lib/auth` (CI-enforced)
 - `bun run format` — prettier
 - `bun test` — run the test suite
+- `bun run smoke` — pack the tarball + run the packaged binary (E5-4)
 - `bun run dev` — run the CLI from source (`./bin/dev.js`)
 
 ## Security
 
-The CLI is a **public OAuth2 client** (Authorization Code + PKCE + Dynamic Client
-Registration) — it holds **no client secret**.
+The CLI is a **public OAuth2 client** (Authorization Code + PKCE, a fixed
+first-party `client_id`) — it holds **no client secret**.
 
 - **Tokens live only in the OS keychain** (`@napi-rs/keyring`, service id
   `io.flipstream.cli`); nothing is written to disk in plaintext, and the
@@ -104,6 +110,10 @@ If you already removed the binary, clean up manually:
 * [`flipstream commands`](#flipstream-commands)
 * [`flipstream conn list`](#flipstream-conn-list)
 * [`flipstream connections list`](#flipstream-connections-list)
+* [`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 version`](#flipstream-version)
 * [`flipstream workspaces connections ID`](#flipstream-workspaces-connections-id)
@@ -341,6 +351,170 @@ EXAMPLES
   $ flipstream conn list --all
 ```
 
+## `flipstream log add MESSAGE`
+
+Add an entry to a workspace's log.
+
+```
+USAGE
+  $ flipstream log add MESSAGE --workspace <value> [--json] [-H <value>] [--ndjson] [--timeout <value>]
+    [--verbose] [--end <value>] [--start <value>]
+
+ARGUMENTS
+  MESSAGE  The log entry text.
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --end=<value>        End date (ISO 8601). Defaults to now.
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --start=<value>      Start date (ISO 8601). Defaults to now.
+      --timeout=<value>    Network timeout in milliseconds.
+      --verbose            Print redacted diagnostics to stderr.
+      --workspace=<value>  (required) Workspace id (UUID) the entry belongs to.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Add an entry to a workspace's log.
+
+  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.
+
+ALIASES
+  $ flipstream logs add
+
+EXAMPLES
+  $ flipstream log add "shipped the new pipeline" --workspace <id>
+
+  $ flipstream log add "kickoff call done" --ws <id> --json
+```
+
+## `flipstream log list`
+
+Read a workspace's log entries.
+
+```
+USAGE
+  $ flipstream log list --workspace <value> [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose]
+    [--all] [--limit <value>] [--offset <value>] [--q <value>] [--sort <value>]
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --all                Fetch every page (drains pagination).
+      --limit=<value>      [default: 50] Page size.
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --offset=<value>     Starting offset.
+      --q=<value>          Free-text filter.
+      --sort=<value>       Sort field.
+      --timeout=<value>    Network timeout in milliseconds.
+      --verbose            Print redacted diagnostics to stderr.
+      --workspace=<value>  (required) The workspace whose log to read (UUID).
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Read a workspace's log entries.
+
+  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.
+
+ALIASES
+  $ flipstream logs list
+
+EXAMPLES
+  $ flipstream log list --workspace <id>
+
+  $ flipstream logs list --ws <id> --json
+
+  $ flipstream log list --ws <id> --all
+```
+
+## `flipstream logs add MESSAGE`
+
+Add an entry to a workspace's log.
+
+```
+USAGE
+  $ flipstream logs add MESSAGE --workspace <value> [--json] [-H <value>] [--ndjson] [--timeout <value>]
+    [--verbose] [--end <value>] [--start <value>]
+
+ARGUMENTS
+  MESSAGE  The log entry text.
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --end=<value>        End date (ISO 8601). Defaults to now.
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --start=<value>      Start date (ISO 8601). Defaults to now.
+      --timeout=<value>    Network timeout in milliseconds.
+      --verbose            Print redacted diagnostics to stderr.
+      --workspace=<value>  (required) Workspace id (UUID) the entry belongs to.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Add an entry to a workspace's log.
+
+  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.
+
+ALIASES
+  $ flipstream logs add
+
+EXAMPLES
+  $ flipstream log add "shipped the new pipeline" --workspace <id>
+
+  $ flipstream log add "kickoff call done" --ws <id> --json
+```
+
+## `flipstream logs list`
+
+Read a workspace's log entries.
+
+```
+USAGE
+  $ flipstream logs list --workspace <value> [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose]
+    [--all] [--limit <value>] [--offset <value>] [--q <value>] [--sort <value>]
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --all                Fetch every page (drains pagination).
+      --limit=<value>      [default: 50] Page size.
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --offset=<value>     Starting offset.
+      --q=<value>          Free-text filter.
+      --sort=<value>       Sort field.
+      --timeout=<value>    Network timeout in milliseconds.
+      --verbose            Print redacted diagnostics to stderr.
+      --workspace=<value>  (required) The workspace whose log to read (UUID).
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Read a workspace's log entries.
+
+  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.
+
+ALIASES
+  $ flipstream logs list
+
+EXAMPLES
+  $ flipstream log list --workspace <id>
+
+  $ flipstream logs list --ws <id> --json
+
+  $ flipstream log list --ws <id> --all
+```
+
 ## `flipstream query`
 
 Run an opaque query against the Flipstream data API.

package/dist/commands/connections/list.js

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
-import { fetchConnections, resolveWorkspaceNames } from '../../lib/api/connections.js';
+import { fetchConnections } from '../../lib/api/connections.js';
+import { hydrate, WORKSPACE_NAME } from '../../lib/api/hydrate.js';
 import { assertUuid } from '../../lib/api/ids.js';
 import { authedAdminClient, renderConnectionsTable } from '../../lib/command/admin.js';
 import { BaseCommand } from '../../lib/command/base.js';
@@ -17,7 +18,7 @@ export default class ConnectionsList extends BaseCommand {
     ];
     static flags = {
         ...paginationFlags,
-        workspace: Flags.string({ description: "List only this workspace's connections (UUID)." }),
+        workspace: Flags.string({ aliases: ['ws'], description: "List only this workspace's connections (UUID)." }),
     };
     static summary = 'List connections, org-wide or for one workspace.';
     async run() {
@@ -37,7 +38,7 @@ export default class ConnectionsList extends BaseCommand {
             sort: this.flags.sort,
             workspace,
         });
-        await resolveWorkspaceNames(client, projected.records);
+        await hydrate(client, projected.records, [WORKSPACE_NAME]);
         return this.respondList(projected, (records) => renderConnectionsTable(records));
     }
 }

package/dist/commands/log/add.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class LogAdd extends BaseCommand<typeof LogAdd> {
+    static aliases: string[];
+    static args: {
+        message: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        end: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        start: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<unknown>;
+}

package/dist/commands/log/add.js

@@ -0,0 +1,44 @@
+import { Args, Flags } from '@oclif/core';
+import { assertUuid } from '../../lib/api/ids.js';
+import { addLogEntry, resolveWorkspaceOrg } from '../../lib/api/log.js';
+import { authedAdminClient } from '../../lib/command/admin.js';
+import { BaseCommand } from '../../lib/command/base.js';
+import { AuthRequiredError } from '../../lib/errors.js';
+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 }),
+    };
+    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). ' +
+        'Returns the created entry. Targets the OAuth/admin host.';
+    static examples = [
+        '<%= config.bin %> log add "shipped the new pipeline" --workspace <id>',
+        '<%= config.bin %> log add "kickoff call done" --ws <id> --json',
+    ];
+    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 }),
+    };
+    static summary = "Add an entry to a workspace's log.";
+    async run() {
+        assertUuid(this.flags.workspace, 'workspace id'); // exit 2, no request
+        const host = this.resolvedHost();
+        const store = createStore();
+        if (!store.load(host))
+            throw AuthRequiredError.notLoggedIn();
+        const client = authedAdminClient(host, store, this.flags.timeout);
+        const organizationId = await resolveWorkspaceOrg(client, this.flags.workspace);
+        const now = new Date().toISOString();
+        const created = await addLogEntry(client, {
+            clientId: this.flags.workspace,
+            description: this.args.message,
+            endDate: this.flags.end ?? now,
+            organizationId,
+            startDate: this.flags.start ?? now,
+        });
+        return this.respond(created, (entry) => this.log(`Logged entry ${String(entry.id)} to workspace ${this.flags.workspace}.`));
+    }
+}

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

@@ -0,0 +1,19 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class LogList extends BaseCommand<typeof LogList> {
+    static aliases: string[];
+    static description: string;
+    static examples: string[];
+    static flags: {
+        workspace: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        offset: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        q: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        sort: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<{
+        count: number;
+        records: unknown[];
+    }>;
+}

package/dist/commands/log/list.js

@@ -0,0 +1,43 @@
+import { Flags } from '@oclif/core';
+import { CREATOR_EMAIL, hydrate, WORKSPACE_NAME } from '../../lib/api/hydrate.js';
+import { assertUuid } from '../../lib/api/ids.js';
+import { fetchLog } from '../../lib/api/log.js';
+import { authedAdminClient, renderLogEntriesTable } from '../../lib/command/admin.js';
+import { BaseCommand } from '../../lib/command/base.js';
+import { paginationFlags } from '../../lib/command/flags.js';
+import { AuthRequiredError } from '../../lib/errors.js';
+import { createStore } from '../../lib/store/index.js';
+export default class LogList extends BaseCommand {
+    static aliases = ['logs:list'];
+    static 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.';
+    static examples = [
+        '<%= config.bin %> log list --workspace <id>',
+        '<%= config.bin %> logs list --ws <id> --json',
+        '<%= config.bin %> log list --ws <id> --all',
+    ];
+    static flags = {
+        ...paginationFlags,
+        workspace: Flags.string({ aliases: ['ws'], description: 'The workspace whose log to read (UUID).', required: true }),
+    };
+    static summary = "Read a workspace's log entries.";
+    async run() {
+        assertUuid(this.flags.workspace, 'workspace id'); // exit 2, no request
+        const host = this.resolvedHost();
+        const store = createStore();
+        if (!store.load(host))
+            throw AuthRequiredError.notLoggedIn();
+        const client = authedAdminClient(host, store, this.flags.timeout);
+        const projected = await fetchLog(client, {
+            all: this.flags.all,
+            limit: this.flags.limit,
+            offset: this.flags.offset,
+            q: this.flags.q,
+            sort: this.flags.sort,
+            workspace: this.flags.workspace,
+        });
+        await hydrate(client, projected.records, [WORKSPACE_NAME, CREATOR_EMAIL]);
+        return this.respondList(projected, (records) => renderLogEntriesTable(records));
+    }
+}

package/dist/commands/workspaces/connections.js

@@ -1,5 +1,6 @@
 import { Args } from '@oclif/core';
-import { fetchConnections, resolveWorkspaceNames } from '../../lib/api/connections.js';
+import { fetchConnections } from '../../lib/api/connections.js';
+import { hydrate, WORKSPACE_NAME } from '../../lib/api/hydrate.js';
 import { assertUuid } from '../../lib/api/ids.js';
 import { authedAdminClient, renderConnectionsTable } from '../../lib/command/admin.js';
 import { BaseCommand } from '../../lib/command/base.js';
@@ -35,7 +36,7 @@ export default class WorkspacesConnections extends BaseCommand {
             sort: this.flags.sort,
             workspace: this.args.id,
         });
-        await resolveWorkspaceNames(client, projected.records);
+        await hydrate(client, projected.records, [WORKSPACE_NAME]);
         return this.respondList(projected, (records) => renderConnectionsTable(records));
     }
 }

package/dist/lib/api/admin-client.d.ts

@@ -3,8 +3,13 @@ export interface AdminGetOptions {
     query?: Record<string, boolean | number | string | undefined>;
     timeoutMs?: number;
 }
+export interface AdminPostOptions {
+    body?: unknown;
+    timeoutMs?: number;
+}
 export interface AdminClient {
     get(path: string, options?: AdminGetOptions): Promise<unknown>;
+    post(path: string, options?: AdminPostOptions): Promise<unknown>;
 }
 export interface AdminClientOptions {
     getToken: () => null | Promise<null | string> | string;

package/dist/lib/api/admin-client.js

@@ -22,6 +22,16 @@ export function createAdminClient(options) {
                 url: `${base}${path}`,
             });
         },
+        async post(path, postOptions = {}) {
+            const token = await options.getToken();
+            return requestJson({
+                body: postOptions.body,
+                method: 'POST',
+                timeoutMs: postOptions.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}${path}`,
+            });
+        },
     };
 }
 // The authed admin client: the SAME withFreshToken 401->refresh->retry-once
@@ -40,5 +50,14 @@ export function createAuthedAdminClient(deps) {
                 url: `${base}${path}`,
             }));
         },
+        post(path, postOptions = {}) {
+            return withFreshToken(deps, (token) => requestJson({
+                body: postOptions.body,
+                method: 'POST',
+                timeoutMs: postOptions.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}${path}`,
+            }));
+        },
     };
 }

package/dist/lib/api/connections.d.ts

@@ -11,4 +11,3 @@ export declare function fetchConnections(client: AdminClient, query: Connections
     count: number;
     records: Array<Record<string, unknown>>;
 }>;
-export declare function resolveWorkspaceNames(client: AdminClient, records: Array<Record<string, unknown>>): Promise<void>;

package/dist/lib/api/connections.js

@@ -17,28 +17,3 @@ export async function fetchConnections(client, query) {
     const envelope = query.all ? await drainPages(fetchPage, start) : await fetchPage(start);
     return { count: envelope.count, records: envelope.records.map((record) => projectConnection(record)) };
 }
-// Fill `client_name` for connections that lack it (the API didn't nest the
-// client): one drained workspace lookup, keyed by id. Skipped when all already
-// have it; best-effort (leaves names unresolved rather than failing the list).
-export async function resolveWorkspaceNames(client, records) {
-    const missing = records.some((record) => record.client_name === undefined && record.client_id !== undefined);
-    if (!missing)
-        return;
-    const names = new Map();
-    try {
-        const workspaces = await drainPages(async (page) => normalizeList(await client.get('/clients', { query: { limit: page.limit, offset: page.offset } })), { limit: 100, offset: 0 });
-        for (const workspace of workspaces.records) {
-            const ws = workspace;
-            if (ws.id)
-                names.set(ws.id, ws.name ?? '');
-        }
-    }
-    catch {
-        return;
-    }
-    for (const record of records) {
-        if (record.client_name === undefined && typeof record.client_id === 'string') {
-            record.client_name = names.get(record.client_id) ?? null;
-        }
-    }
-}

package/dist/lib/api/hydrate.d.ts

@@ -0,0 +1,10 @@
+import { type AdminClient } from './admin-client.js';
+export interface HydrateSpec {
+    endpoint: string;
+    idField: string;
+    label: (entity: Record<string, unknown>) => unknown;
+    labelField: string;
+}
+export declare const WORKSPACE_NAME: HydrateSpec;
+export declare const CREATOR_EMAIL: HydrateSpec;
+export declare function hydrate(client: AdminClient, records: Array<Record<string, unknown>>, specs: HydrateSpec[]): Promise<void>;

package/dist/lib/api/hydrate.js

@@ -0,0 +1,46 @@
+import { drainPages, normalizeList } from './list.js';
+// The shared workspace-name and author-email specs (used across list commands).
+export const WORKSPACE_NAME = {
+    endpoint: '/clients',
+    idField: 'client_id',
+    label: (entity) => entity.name,
+    labelField: 'client_name',
+};
+export const CREATOR_EMAIL = {
+    endpoint: '/users',
+    idField: 'created_by_id',
+    label: (entity) => entity.email ?? entity.name,
+    labelField: 'created_by_email',
+};
+async function hydrateOne(client, records, spec) {
+    const needs = (record) => record[spec.labelField] === undefined &&
+        typeof record[spec.idField] === 'string' &&
+        record[spec.idField].length > 0;
+    if (!records.some((record) => needs(record)))
+        return;
+    const byId = new Map();
+    try {
+        const entities = await drainPages(async (page) => normalizeList(await client.get(spec.endpoint, { query: { limit: page.limit, offset: page.offset } })), { limit: 100, offset: 0 });
+        for (const raw of entities.records) {
+            const entity = (raw ?? {});
+            if (typeof entity.id === 'string') {
+                const label = spec.label(entity);
+                byId.set(entity.id, typeof label === 'string' ? label : '');
+            }
+        }
+    }
+    catch {
+        return; // best-effort: leave the label unresolved rather than fail the list
+    }
+    for (const record of records) {
+        if (needs(record))
+            record[spec.labelField] = byId.get(record[spec.idField]) ?? null;
+    }
+}
+// Hydrate a record set against one or more specs, running each lookup CONCURRENTLY
+// and ONCE. Each spec is skipped when no record needs it, and is best-effort: a
+// forbidden/unavailable lookup leaves its label unresolved rather than failing.
+// Mutates `records` in place.
+export async function hydrate(client, records, specs) {
+    await Promise.all(specs.map((spec) => hydrateOne(client, records, spec)));
+}

package/dist/lib/api/log.d.ts

@@ -0,0 +1,22 @@
+import { type AdminClient } from './admin-client.js';
+export interface LogQuery {
+    all?: boolean;
+    limit: number;
+    offset: number;
+    q?: string;
+    sort?: string;
+    workspace: string;
+}
+export declare function fetchLog(client: AdminClient, query: LogQuery): Promise<{
+    count: number;
+    records: Array<Record<string, unknown>>;
+}>;
+export interface NewLogEntry {
+    clientId: string;
+    description: string;
+    endDate: string;
+    organizationId: string;
+    startDate: string;
+}
+export declare function addLogEntry(client: AdminClient, entry: NewLogEntry): Promise<Record<string, unknown>>;
+export declare function resolveWorkspaceOrg(client: AdminClient, workspaceId: string): Promise<string>;

package/dist/lib/api/log.js

@@ -0,0 +1,56 @@
+import { DataHttpError } from '../errors.js';
+import { mapDataError, notFoundError } from './errors.js';
+import { drainPages, normalizeList } from './list.js';
+import { projectLogEntry, projectWorkspace } from './projections.js';
+// Fetch + project a workspace's log (event-log) entries via the per-client
+// endpoint, draining pages when requested. Errors are mapped to the E3 model.
+export async function fetchLog(client, query) {
+    const path = `/clients/${query.workspace}/event-logs`;
+    const fetchPage = async (page) => {
+        try {
+            return normalizeList(await client.get(path, { query: { limit: page.limit, offset: page.offset, q: query.q, sort: query.sort } }));
+        }
+        catch (error) {
+            throw mapDataError(error);
+        }
+    };
+    const start = { limit: query.limit, offset: query.offset };
+    const envelope = query.all ? await drainPages(fetchPage, start) : await fetchPage(start);
+    return { count: envelope.count, records: envelope.records.map((record) => projectLogEntry(record)) };
+}
+// Add a log entry: POST /event-logs (the workspace + org go in the body). The
+// body is a structured builder, so future fields (e.g. tags) drop in here.
+// Returns the projected created entry. Errors are mapped to the E3 model.
+export async function addLogEntry(client, entry) {
+    const body = {
+        client_id: entry.clientId,
+        description: entry.description,
+        end_date: entry.endDate,
+        organization_id: entry.organizationId,
+        start_date: entry.startDate,
+    };
+    try {
+        return projectLogEntry(await client.post('/event-logs', { body }));
+    }
+    catch (error) {
+        throw mapDataError(error);
+    }
+}
+// Derive a workspace's organization_id (required to create an entry) via one
+// workspace lookup. A foreign or missing id collapses to a single not-found
+// message (no existence leak), mirroring `ws get`.
+export async function resolveWorkspaceOrg(client, workspaceId) {
+    let raw;
+    try {
+        raw = await client.get(`/clients/${workspaceId}`);
+    }
+    catch (error) {
+        if (error instanceof DataHttpError && (error.status === 403 || error.status === 404))
+            throw notFoundError();
+        throw mapDataError(error);
+    }
+    const org = projectWorkspace(raw).organization_id;
+    if (typeof org !== 'string' || org.length === 0)
+        throw notFoundError();
+    return org;
+}

package/dist/lib/api/projections.d.ts

@@ -1,2 +1,3 @@
 export declare function projectWorkspace(raw: unknown): Record<string, unknown>;
 export declare function projectConnection(raw: unknown): Record<string, unknown>;
+export declare function projectLogEntry(raw: unknown): Record<string, unknown>;

package/dist/lib/api/projections.js

@@ -1,6 +1,7 @@
 import { redact } from '../output/redact.js';
 const WORKSPACE_CORE = ['organization_id', 'slug', 'business_type', 'client_main_goal', 'created_on'];
 const CONNECTION_CORE = ['name', 'client_id', 'type', 'active', 'backfill', 'data_refresh_status', 'created_on'];
+const LOG_CORE = ['description', 'start_date', 'end_date', 'client_id', 'organization_id', 'created_on', 'created_by_id'];
 // Project a raw admin Client into a stable "workspace" shape: id + name + present
 // core fields + owner_email (from the nested owner) + a redacted `raw` passthrough
 // so it survives schema drift. Adds/invents no fields.
@@ -32,3 +33,25 @@ export function projectConnection(raw) {
     out.raw = redact(raw);
     return out;
 }
+// Project a raw EventLog (the "log" / logbook entry) into a stable shape: id +
+// present core fields + the workspace name (nested `client`) and author (nested
+// `created_by`) + a redacted `raw` passthrough. New API fields (e.g. `tags`)
+// flow through `raw` automatically under --json; surface them by adding to
+// LOG_CORE + a table column when they ship.
+export function projectLogEntry(raw) {
+    const entry = (raw ?? {});
+    const out = { id: entry.id };
+    for (const key of LOG_CORE)
+        if (entry[key] !== undefined)
+            out[key] = entry[key];
+    const client = entry.client;
+    if (client?.name)
+        out.client_name = client.name;
+    const by = entry.created_by;
+    if (by?.name)
+        out.created_by_name = by.name;
+    if (by?.email)
+        out.created_by_email = by.email;
+    out.raw = redact(raw);
+    return out;
+}

package/dist/lib/auth/claims.js

@@ -2,11 +2,11 @@
 // MUST NOT be used for any authorization / request-gating decision (the CLI is a
 // thin client; the server validates tokens). A convention test guards this.
 export function decodeJwtClaimsUnverified(accessToken) {
-    const parts = accessToken.split('.');
-    if (parts.length < 2)
+    const [, payload] = accessToken.split('.');
+    if (payload === undefined)
         return null;
     try {
-        const padded = parts[1] + '='.repeat((4 - (parts[1].length % 4)) % 4);
+        const padded = payload + '='.repeat((4 - (payload.length % 4)) % 4);
         return JSON.parse(Buffer.from(padded, 'base64url').toString('utf8'));
     }
     catch {

package/dist/lib/command/admin.d.ts

@@ -2,3 +2,4 @@ import { type AdminClient } from '../api/admin-client.js';
 import { type TokenStore } from '../store/keyring.js';
 export declare function authedAdminClient(host: string, store: TokenStore, timeoutMs?: number): AdminClient;
 export declare function renderConnectionsTable(records: Array<Record<string, unknown>>): void;
+export declare function renderLogEntriesTable(records: Array<Record<string, unknown>>): void;

package/dist/lib/command/admin.js

@@ -28,3 +28,24 @@ export function renderConnectionsTable(records) {
         { key: 'id', name: 'ID' },
     ], 'No connections.');
 }
+// The log (event-log) human table — shared by `log list`. Date prefers
+// created_on (falls back to start_date); By prefers the author name then email;
+// Workspace falls back to the id when its name couldn't be resolved.
+// First non-empty string among the candidates, else an em-dash placeholder.
+function firstLabel(...values) {
+    return values.find((value) => typeof value === 'string' && value.length > 0) ?? '—';
+}
+export function renderLogEntriesTable(records) {
+    const rows = records.map((record) => ({
+        ...record,
+        by: firstLabel(record.created_by_name, record.created_by_email, record.created_by_id),
+        client_name: firstLabel(record.client_name, record.client_id),
+        when: firstLabel(record.created_on, record.start_date),
+    }));
+    renderTable(rows, [
+        { key: 'when', name: 'Date' },
+        { key: 'client_name', name: 'Workspace' },
+        { key: 'description', name: 'Entry' },
+        { key: 'by', name: 'By' },
+    ], 'No log entries.');
+}

package/dist/lib/errors.js

@@ -98,6 +98,11 @@ export function toExitCode(error) {
         if (error.name === 'LoopbackError') {
             return /tim(e|ed) ?out/i.test(error.message) ? ExitCode.TIMEOUT : ExitCode.AUTH_FAILED;
         }
+        // oclif parse/usage errors (missing or unknown flag, bad arg) carry their own
+        // exit — honor it so a missing required flag is exit 2 ("bad invocation").
+        const oclifExit = error.oclif?.exit;
+        if (typeof oclifExit === 'number' && oclifExit > 0)
+            return oclifExit;
     }
     return ExitCode.GENERIC;
 }
@@ -109,7 +114,13 @@ export function toExitCode(error) {
 // tokens never leak.
 export function renderError(error, options = {}) {
     const exitCode = toExitCode(error);
-    const code = error instanceof CliError ? error.code : error instanceof Error ? error.name : 'error';
+    let code = 'error';
+    if (error instanceof CliError)
+        code = error.code;
+    else if (exitCode === ExitCode.USAGE)
+        code = 'usage'; // oclif parse/usage errors
+    else if (error instanceof Error)
+        code = error.name;
     const rawMessage = error instanceof Error ? error.message : String(error);
     const message = redact(rawMessage);
     if (options.json) {

package/oclif.manifest.json

@@ -518,6 +518,9 @@
           "type": "option"
         },
         "workspace": {
+          "aliases": [
+            "ws"
+          ],
           "description": "List only this workspace's connections (UUID).",
           "name": "workspace",
           "hasDynamicHelp": false,
@@ -542,6 +545,217 @@
         "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"
+      ]
+    },
     "workspaces:connections": {
       "aliases": [
         "ws:connections"
@@ -847,5 +1061,5 @@
       ]
     }
   },
-  "version": "0.4.0"
+  "version": "0.5.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flipstream",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Flipstream CLI — query your Flipstream data from the terminal.",
   "keywords": [
     "flipstream",
@@ -33,9 +33,19 @@
     "lint": "eslint .",
     "pack:prepare": "tsc -p tsconfig.json && oclif manifest",
     "posttest": "eslint .",
+    "prepare": "husky || true",
     "smoke": "bun scripts/smoke.ts",
     "test": "bun test"
   },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
   "dependencies": {
     "@napi-rs/keyring": "^1.3.0",
     "@oclif/core": "^4",
@@ -51,6 +61,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 +85,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/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;
-}