flipstream 0.4.0

package/dist/commands/auth/clear-all.js

@@ -0,0 +1,50 @@
+import { Flags } from '@oclif/core';
+import { fetchMetadata } from '../../lib/auth/discovery.js';
+import { revokeToken } from '../../lib/auth/revoke.js';
+import { BaseCommand } from '../../lib/command/base.js';
+import { knownHosts, removeConfigDir } from '../../lib/config/xdg.js';
+import { createStore } from '../../lib/store/index.js';
+export default class AuthClearAll extends BaseCommand {
+    static description = 'Purge ALL Flipstream credentials: every keychain entry and the local config directory.';
+    static examples = ['<%= config.bin %> auth clear-all', '<%= config.bin %> auth clear-all --no-revoke'];
+    static flags = {
+        'no-revoke': Flags.boolean({ description: 'Clear local credentials only; skip the per-host server revocation calls.' }),
+    };
+    static summary = 'Purge ALL credentials: every keychain entry and the local config dir.';
+    async run() {
+        const store = createStore();
+        const hosts = knownHosts();
+        const timeoutMs = this.flags.timeout ?? 10_000;
+        // Best-effort revoke each host's refresh token (in parallel — no cross-host
+        // dependency), then clear its keychain entry regardless of the outcome.
+        await Promise.all(hosts.map(async (host) => {
+            const creds = store.load(host);
+            if (!this.flags['no-revoke'] && creds?.refreshToken) {
+                try {
+                    const meta = await fetchMetadata(host, { timeoutMs });
+                    await revokeToken({
+                        clientId: creds.clientId,
+                        revocationEndpoint: meta.revocationEndpoint,
+                        timeoutMs,
+                        token: creds.refreshToken,
+                        tokenTypeHint: 'refresh_token',
+                    });
+                }
+                catch {
+                    // Best-effort — proceed to clear the keychain entry anyway.
+                }
+            }
+            store.clear(host);
+        }));
+        const configRemoved = removeConfigDir();
+        return this.respond({ clearedHosts: hosts, configRemoved }, () => {
+            if (hosts.length === 0 && !configRemoved) {
+                this.log('Nothing to clear.');
+            }
+            else {
+                this.log(`Cleared ${hosts.length} host(s): ${hosts.join(', ') || '(none)'}`);
+                this.log(configRemoved ? 'Removed the local config directory.' : 'No local config directory to remove.');
+            }
+        });
+    }
+}

package/dist/commands/auth/login.d.ts

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

package/dist/commands/auth/login.js

@@ -0,0 +1,49 @@
+import { Flags } from '@oclif/core';
+import { login } from '../../lib/auth/flow.js';
+import { BaseCommand } from '../../lib/command/base.js';
+import { rememberHost } from '../../lib/config/xdg.js';
+import { redact } from '../../lib/output/redact.js';
+import { createStore } from '../../lib/store/index.js';
+export default class AuthLogin extends BaseCommand {
+    static description = 'Log in to Flipstream in the browser (OAuth2 Authorization Code + PKCE).';
+    static examples = ['<%= config.bin %> auth login', '<%= config.bin %> auth login --no-browser'];
+    static flags = {
+        'no-browser': Flags.boolean({
+            description: 'Headless mode: print the authorization URL, then paste the redirected URL back (no browser).',
+        }),
+        scope: Flags.string({ description: 'OAuth scope (repeatable).', multiple: true }),
+    };
+    static summary = 'Log in via the browser (OAuth2 + PKCE).';
+    async run() {
+        const result = await login({
+            host: this.resolvedHost(),
+            openBrowser: !this.flags['no-browser'],
+            scopes: this.flags.scope,
+            timeoutMs: this.flags.timeout,
+        });
+        const expiresAt = Math.floor(Date.now() / 1000) + result.expiresIn;
+        try {
+            createStore().save(result.host, {
+                accessToken: result.accessToken,
+                clientId: result.clientId,
+                expiresAt,
+                redirectUri: result.redirectUri,
+                refreshToken: result.refreshToken,
+                scopes: result.scopes,
+            });
+            // Record the host in the NON-secret index so logout/clear-all can find it.
+            rememberHost(result.host, {
+                clientId: result.clientId,
+                expiresAt,
+                redirectUri: result.redirectUri,
+                scopes: result.scopes,
+            });
+        }
+        catch {
+            this.warn('Could not save credentials to the OS keychain; you may need to re-login next time.');
+        }
+        // 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)));
+    }
+}

package/dist/commands/auth/logout.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class AuthLogout extends BaseCommand<typeof AuthLogout> {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'no-revoke': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    run(): Promise<Record<string, unknown>>;
+}

package/dist/commands/auth/logout.js

@@ -0,0 +1,51 @@
+import { Flags } from '@oclif/core';
+import { fetchMetadata } from '../../lib/auth/discovery.js';
+import { revokeToken } from '../../lib/auth/revoke.js';
+import { BaseCommand } from '../../lib/command/base.js';
+import { forgetHost } from '../../lib/config/xdg.js';
+import { createStore } from '../../lib/store/index.js';
+export default class AuthLogout extends BaseCommand {
+    static description = 'Log out of Flipstream: revoke the token (best-effort) and clear the keychain.';
+    static examples = ['<%= config.bin %> auth logout', '<%= config.bin %> auth logout --no-revoke'];
+    static flags = {
+        'no-revoke': Flags.boolean({ description: 'Clear local credentials only; skip the server revocation call.' }),
+    };
+    static summary = 'Log out: revoke the token (best-effort) and clear the keychain.';
+    async run() {
+        const host = this.resolvedHost();
+        const store = createStore();
+        const creds = store.load(host);
+        if (!creds) {
+            return this.respond({ host, loggedOut: true, revoked: false }, () => this.log(`Not logged in to ${host}; nothing to do.`));
+        }
+        let revoked = false;
+        if (!this.flags['no-revoke']) {
+            const timeoutMs = this.flags.timeout ?? 10_000;
+            try {
+                const meta = await fetchMetadata(host, { timeoutMs });
+                const token = creds.refreshToken || creds.accessToken;
+                if (token) {
+                    revoked = await revokeToken({
+                        clientId: creds.clientId,
+                        revocationEndpoint: meta.revocationEndpoint,
+                        timeoutMs,
+                        token,
+                        tokenTypeHint: creds.refreshToken ? 'refresh_token' : 'access_token',
+                    });
+                }
+            }
+            catch {
+                // Discovery/network failure — clear local credentials anyway so the user
+                // is logged out locally even when the server cannot be reached.
+            }
+        }
+        // Always clear local credentials, even if revocation could not be confirmed.
+        store.clear(host);
+        forgetHost(host);
+        return this.respond({ host, loggedOut: true, revoked }, () => {
+            this.log(`Logged out of ${host}.`);
+            if (!this.flags['no-revoke'] && !revoked)
+                this.log('  (server token revocation could not be confirmed)');
+        });
+    }
+}

package/dist/commands/auth/status.d.ts

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

package/dist/commands/auth/status.js

@@ -0,0 +1,47 @@
+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 { createStore } from '../../lib/store/index.js';
+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'];
+    static flags = {};
+    static summary = 'Show whether you are logged in, and your account, scopes, and expiry.';
+    async run() {
+        const host = this.resolvedHost();
+        const store = createStore();
+        if (!store.available()) {
+            process.stderr.write('The OS keychain is unavailable (e.g. a headless/SSH session). Browser login needs it; ' +
+                'a headless client_credentials / service-account path is PLANNED.\n');
+            return this.exit(ExitCode.NETWORK);
+        }
+        const creds = store.load(host);
+        if (!creds) {
+            return this.respond({ host, loggedIn: false }, () => this.log(`Not logged in to ${host}. Run \`flipstream auth login\`.`));
+        }
+        const claims = tokenClaims(host, store) ?? {};
+        // JSON keeps the stable subject id (agent-friendly); the human line prefers
+        // the friendlier email when present.
+        const account = [claims.sub, claims.email].find((value) => typeof value === 'string') ?? null;
+        const displayAccount = [claims.email, claims.sub].find((value) => typeof value === 'string') ?? account;
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const expired = creds.expiresAt <= nowSeconds;
+        const expiresAtIso = new Date(creds.expiresAt * 1000).toISOString();
+        const status = redact({
+            account,
+            expired,
+            expiresAt: expiresAtIso,
+            host,
+            loggedIn: true,
+            scopes: creds.scopes,
+        });
+        return this.respond(status, () => {
+            const relative = expired ? 'expired' : `expires in ${Math.round((creds.expiresAt - nowSeconds) / 3600)}h`;
+            this.log(`Logged in to ${host}`);
+            this.log(`  account: ${typeof displayAccount === 'string' ? displayAccount : 'unknown'}`);
+            this.log(`  expires: ${expiresAtIso} (${relative})`);
+            this.log(`  scopes:  ${creds.scopes.join(' ')}`);
+        });
+    }
+}

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

@@ -0,0 +1,19 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class ConnectionsList extends BaseCommand<typeof ConnectionsList> {
+    static aliases: string[];
+    static description: string;
+    static examples: string[];
+    static flags: {
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, 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/connections/list.js

@@ -0,0 +1,43 @@
+import { Flags } from '@oclif/core';
+import { fetchConnections, resolveWorkspaceNames } from '../../lib/api/connections.js';
+import { assertUuid } from '../../lib/api/ids.js';
+import { authedAdminClient, renderConnectionsTable } 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 ConnectionsList extends BaseCommand {
+    static aliases = ['conn:list'];
+    static description = 'List connections (data sources) — org-wide, or for one workspace via --workspace (or `ws connections <id>`). ' +
+        'Returns each connection id + source metadata; secret_id / parameters are redacted. Targets the OAuth/admin host.';
+    static examples = [
+        '<%= config.bin %> connections list',
+        '<%= config.bin %> connections list --workspace <id> --json',
+        '<%= config.bin %> conn list --all',
+    ];
+    static flags = {
+        ...paginationFlags,
+        workspace: Flags.string({ description: "List only this workspace's connections (UUID)." }),
+    };
+    static summary = 'List connections, org-wide or for one workspace.';
+    async run() {
+        const { workspace } = this.flags;
+        if (workspace !== undefined)
+            assertUuid(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 fetchConnections(client, {
+            all: this.flags.all,
+            limit: this.flags.limit,
+            offset: this.flags.offset,
+            q: this.flags.q,
+            sort: this.flags.sort,
+            workspace,
+        });
+        await resolveWorkspaceNames(client, projected.records);
+        return this.respondList(projected, (records) => renderConnectionsTable(records));
+    }
+}

package/dist/commands/query.d.ts

@@ -0,0 +1,13 @@
+import { BaseCommand } from '../lib/command/base.js';
+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>;
+    };
+    static summary: string;
+    run(): Promise<unknown>;
+    private parseBody;
+}

package/dist/commands/query.js

@@ -0,0 +1,76 @@
+import { Flags } from '@oclif/core';
+import { readFileSync } from 'node:fs';
+import { mapDataError } from '../lib/api/errors.js';
+import { createAuthedDataClient } from '../lib/api/retry.js';
+import { refresh } from '../lib/auth/refresh.js';
+import { BaseCommand } from '../lib/command/base.js';
+import { DATA_HOST } from '../lib/config/constants.js';
+import { resolveHost } from '../lib/config/xdg.js';
+import { AuthRequiredError, UsageError } from '../lib/errors.js';
+import { redact } from '../lib/output/redact.js';
+import { createStore } from '../lib/store/index.js';
+export default class Query extends BaseCommand {
+    static 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).';
+    static examples = [
+        '<%= config.bin %> query --body \'{"opaque":true}\'',
+        'echo \'{"opaque":true}\' | <%= config.bin %> query',
+        '<%= config.bin %> query --body-file query.json --json',
+    ];
+    static flags = {
+        'auth-host': Flags.string({
+            description: 'OAuth issuer host for credentials/refresh (defaults to the prod issuer).',
+        }),
+        body: Flags.string({ description: 'Opaque JSON request body as a string.', exclusive: ['body-file'] }),
+        'body-file': Flags.string({ description: 'Path to a file holding the opaque JSON request body.' }),
+    };
+    static summary = 'Run an opaque query against the Flipstream data API.';
+    async run() {
+        // --host overrides the DATA query target; --auth-host the issuer holding creds.
+        const dataHost = this.flags.host ?? DATA_HOST;
+        const authHost = resolveHost({ hostFlag: this.flags['auth-host'] });
+        const store = createStore();
+        // Distinguish never-logged-in (no creds) from a later expired/refresh-rejected
+        // session (the wrapper raises session_expired on a null refresh).
+        if (!store.load(authHost))
+            throw AuthRequiredError.notLoggedIn();
+        const body = this.parseBody();
+        const client = createAuthedDataClient({
+            accessTokenIfFresh: (host) => store.accessTokenIfFresh(host),
+            authHost,
+            host: dataHost,
+            refresh: (host) => refresh(host, { store, timeoutMs: this.flags.timeout }),
+            timeoutMs: this.flags.timeout,
+        });
+        let response;
+        try {
+            response = await client.postQuery(body, { timeoutMs: this.flags.timeout });
+        }
+        catch (error) {
+            throw mapDataError(error);
+        }
+        // Redact known secret KEY NAMES (E3-4) so a token-like key echoed by the DATA
+        // host never reaches --json/NDJSON/human output.
+        const safe = redact(response);
+        return this.respond(safe, (data) => this.log(JSON.stringify(data, null, 2)));
+    }
+    // Forward the body VERBATIM: parse-only, no schema and no field handling.
+    parseBody() {
+        let raw;
+        if (this.flags.body !== undefined)
+            raw = this.flags.body;
+        else if (this.flags['body-file'] !== undefined)
+            raw = readFileSync(this.flags['body-file'], 'utf8');
+        else if (process.stdin.isTTY)
+            throw new UsageError('Provide a body via --body, --body-file <path>, or piped stdin.');
+        else
+            raw = readFileSync(0, 'utf8');
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            throw new UsageError('Request body is not valid JSON.');
+        }
+    }
+}

package/dist/commands/version.d.ts

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

package/dist/commands/version.js

@@ -0,0 +1,17 @@
+import { BaseCommand } from '../lib/command/base.js';
+import { CONTRACT_VERSION } from '../lib/config/constants.js';
+export default class Version extends BaseCommand {
+    static description = 'Print the CLI version, runtime, and agent-contract version as JSON.';
+    static examples = ['<%= config.bin %> version', '<%= config.bin %> version --json'];
+    static flags = {};
+    static summary = 'Print version, runtime, and agent-contract version.';
+    async run() {
+        const info = {
+            contractVersion: CONTRACT_VERSION,
+            node: process.versions.node,
+            platform: process.platform,
+            version: this.config.version,
+        };
+        return this.respond(info, (data) => this.log(JSON.stringify(data)));
+    }
+}

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

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class WorkspacesConnections extends BaseCommand<typeof WorkspacesConnections> {
+    static aliases: string[];
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        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/workspaces/connections.js

@@ -0,0 +1,41 @@
+import { Args } from '@oclif/core';
+import { fetchConnections, resolveWorkspaceNames } from '../../lib/api/connections.js';
+import { assertUuid } from '../../lib/api/ids.js';
+import { authedAdminClient, renderConnectionsTable } 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 WorkspacesConnections extends BaseCommand {
+    static aliases = ['ws:connections'];
+    static args = {
+        id: Args.string({ description: 'Workspace id (UUID).', required: true }),
+    };
+    static description = "List one workspace's connections — the ergonomic form of `connections list --workspace <id>`. " +
+        'Targets the OAuth/admin host.';
+    static examples = [
+        '<%= config.bin %> workspaces connections <id>',
+        '<%= config.bin %> ws connections <id> --json',
+        '<%= config.bin %> ws connections <id> --all',
+    ];
+    static flags = { ...paginationFlags };
+    static summary = "List one workspace's connections.";
+    async run() {
+        assertUuid(this.args.id, '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 fetchConnections(client, {
+            all: this.flags.all,
+            limit: this.flags.limit,
+            offset: this.flags.offset,
+            q: this.flags.q,
+            sort: this.flags.sort,
+            workspace: this.args.id,
+        });
+        await resolveWorkspaceNames(client, projected.records);
+        return this.respondList(projected, (records) => renderConnectionsTable(records));
+    }
+}

package/dist/commands/workspaces/get.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class WorkspacesGet extends BaseCommand<typeof WorkspacesGet> {
+    static aliases: string[];
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        refresh: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'with-connection-count': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    run(): Promise<unknown>;
+}

package/dist/commands/workspaces/get.js

@@ -0,0 +1,65 @@
+import { Args, Flags } from '@oclif/core';
+import { createAuthedAdminClient } from '../../lib/api/admin-client.js';
+import { mapDataError, notFoundError } from '../../lib/api/errors.js';
+import { assertUuid } from '../../lib/api/ids.js';
+import { normalizeList } from '../../lib/api/list.js';
+import { projectWorkspace } from '../../lib/api/projections.js';
+import { refresh } from '../../lib/auth/refresh.js';
+import { BaseCommand } from '../../lib/command/base.js';
+import { AuthRequiredError, DataHttpError } from '../../lib/errors.js';
+import { createStore } from '../../lib/store/index.js';
+export default class WorkspacesGet extends BaseCommand {
+    static aliases = ['ws:get'];
+    static args = {
+        id: Args.string({ description: 'Workspace id (UUID).', required: true }),
+    };
+    static description = 'Fetch one workspace by id (the admin API "Client"). A foreign or missing id collapses to a single ' +
+        "not-found message (no existence leak). Targets the OAuth/admin host.";
+    static examples = [
+        '<%= config.bin %> workspaces get <id>',
+        '<%= config.bin %> ws get <id> --json',
+        '<%= config.bin %> ws get <id> --with-connection-count',
+    ];
+    static flags = {
+        refresh: Flags.boolean({ description: 'Ask the server to refresh derived data (refresh=true).' }),
+        'with-connection-count': Flags.boolean({
+            description: 'Include connection_count (one extra request to the connections endpoint).',
+        }),
+    };
+    static summary = 'Show one workspace by id.';
+    async run() {
+        assertUuid(this.args.id, 'workspace id'); // exit 2, no request issued
+        const host = this.resolvedHost();
+        const store = createStore();
+        if (!store.load(host))
+            throw AuthRequiredError.notLoggedIn();
+        const client = createAuthedAdminClient({
+            accessTokenIfFresh: (authHost) => store.accessTokenIfFresh(authHost),
+            authHost: host,
+            host,
+            refresh: (authHost) => refresh(authHost, { store, timeoutMs: this.flags.timeout }),
+            timeoutMs: this.flags.timeout,
+        });
+        let raw;
+        try {
+            raw = await client.get(`/clients/${this.args.id}`, { query: { refresh: this.flags.refresh || undefined } });
+        }
+        catch (error) {
+            // Collapse a foreign-id 403 and a 404 to ONE message so neither leaks existence.
+            if (error instanceof DataHttpError && (error.status === 403 || error.status === 404))
+                throw notFoundError();
+            throw mapDataError(error);
+        }
+        const projected = projectWorkspace(raw);
+        if (this.flags['with-connection-count']) {
+            try {
+                const conns = normalizeList(await client.get(`/clients/${this.args.id}/connections`, { query: { limit: 1 } }));
+                projected.connection_count = conns.count;
+            }
+            catch {
+                projected.connection_count = null; // best-effort; never fails the get
+            }
+        }
+        return this.respond(projected, (data) => this.log(JSON.stringify(data, null, 2)));
+    }
+}

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

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class WorkspacesList extends BaseCommand<typeof WorkspacesList> {
+    static aliases: string[];
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'with-connection-counts': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        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[];
+    }>;
+    private addConnectionCounts;
+}