flipstream 0.4.0 → 0.6.0

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() {
@@ -29,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,
@@ -37,7 +39,32 @@ export default class ConnectionsList extends BaseCommand {
             sort: this.flags.sort,
             workspace,
         });
-        await resolveWorkspaceNames(client, projected.records);
-        return this.respondList(projected, (records) => renderConnectionsTable(records));
+        await hydrate(client, projected.records, [WORKSPACE_NAME]);
+        // 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.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,48 @@
+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.', 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). ' +
+        '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/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;
 }