@seamapi/cli 0.10.0 → 0.12.0

package/lib/interact-for-use-remote-api-defs.js

@@ -1,7 +1,8 @@
-import prompts from 'prompts';
 import { getConfigStore } from './config/index.js';
+import { getOutput } from './output/get-output.js';
+import { prompt } from './util/prompt.js';
 export async function interactForUseRemoteApiDefs() {
-    const { use_remote_api_defs } = await prompts([
+    const { use_remote_api_defs } = await prompt([
         {
             type: 'select',
             name: 'use_remote_api_defs',
@@ -20,6 +21,6 @@ export async function interactForUseRemoteApiDefs() {
     ]);
     const config = getConfigStore();
     config.set('use_remote_api_defs', use_remote_api_defs);
-    console.log(`Use remote API Definitions: ${use_remote_api_defs}`);
+    getOutput().info(`Use remote API Definitions: ${use_remote_api_defs}`);
 }
 //# sourceMappingURL=interact-for-use-remote-api-defs.js.map

package/lib/interact-for-use-remote-api-defs.js.map

@@ -1 +1 @@
-{"version":3,"file":"interact-for-use-remote-api-defs.js","sourceRoot":"","sources":["../src/lib/interact-for-use-remote-api-defs.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAA;AAE7B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElD,MAAM,CAAC,KAAK,UAAU,2BAA2B;IAC/C,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,OAAO,CAAC;QAC5C;YACE,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,oCAAoC;YAC7C,OAAO,EAAE;gBACP;oBACE,KAAK,EAAE,KAAK;oBACZ,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,KAAK,EAAE,IAAI;oBACX,KAAK,EAAE,KAAK;iBACb;aACF;SACF;KACF,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,cAAc,EAAE,CAAA;IAC/B,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,mBAAmB,CAAC,CAAA;IACtD,OAAO,CAAC,GAAG,CAAC,+BAA+B,mBAAmB,EAAE,CAAC,CAAA;AACnE,CAAC"}
+{"version":3,"file":"interact-for-use-remote-api-defs.js","sourceRoot":"","sources":["../src/lib/interact-for-use-remote-api-defs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEzC,MAAM,CAAC,KAAK,UAAU,2BAA2B;IAC/C,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC;QAC3C;YACE,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,oCAAoC;YAC7C,OAAO,EAAE;gBACP;oBACE,KAAK,EAAE,KAAK;oBACZ,KAAK,EAAE,IAAI;iBACZ;gBACD;oBACE,KAAK,EAAE,IAAI;oBACX,KAAK,EAAE,KAAK;iBACb;aACF;SACF;KACF,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,cAAc,EAAE,CAAA;IAC/B,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,mBAAmB,CAAC,CAAA;IACtD,SAAS,EAAE,CAAC,IAAI,CAAC,+BAA+B,mBAAmB,EAAE,CAAC,CAAA;AACxE,CAAC"}

package/lib/interact-for-workspace-id.js

@@ -1,8 +1,8 @@
 import { SeamHttpWithoutWorkspace } from '@seamapi/http/connect';
-import prompts from 'prompts';
 import { getConfigStore } from './config/index.js';
 import { getSeamMultiWorkspace } from './get-seam.js';
 import { getServer } from './get-server.js';
+import { prompt } from './util/prompt.js';
 import { withLoading } from './util/with-loading.js';
 export const interactForWorkspaceId = async (personalAccessToken) => {
     const config = getConfigStore();
@@ -12,7 +12,7 @@ export const interactForWorkspaceId = async (personalAccessToken) => {
         })
         : await getSeamMultiWorkspace();
     const workspaces = await withLoading('Fetching workspaces...', () => seam.workspaces.list());
-    const { workspaceId } = await prompts({
+    const { workspaceId } = await prompt({
         name: 'workspaceId',
         type: 'select',
         message: 'Select a workspace:',

package/lib/interact-for-workspace-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"interact-for-workspace-id.js","sourceRoot":"","sources":["../src/lib/interact-for-workspace-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,OAAO,MAAM,SAAS,CAAA;AAE7B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAEpD,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,EAAE,mBAA4B,EAAE,EAAE;IAC3E,MAAM,MAAM,GAAG,cAAc,EAAE,CAAA;IAC/B,MAAM,IAAI,GAAG,mBAAmB;QAC9B,CAAC,CAAC,wBAAwB,CAAC,uBAAuB,CAAC,mBAAmB,EAAE;YACpE,QAAQ,EAAE,SAAS,EAAE;SACtB,CAAC;QACJ,CAAC,CAAC,MAAM,qBAAqB,EAAE,CAAA;IAEjC,MAAM,UAAU,GAAG,MAAM,WAAW,CAAC,wBAAwB,EAAE,GAAG,EAAE,CAClE,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CACvB,CAAA;IACD,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,OAAO,CAAC;QACpC,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,qBAAqB;QAC9B,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAc,EAAE,EAAE,CAAC,CAAC;YAC3C,KAAK,EAAE,SAAS,CAAC,IAAI;YACrB,KAAK,EAAE,SAAS,CAAC,YAAY;YAC7B,WAAW,EAAE,SAAS,CAAC,YAAY;SACpC,CAAC,CAAC;KACJ,CAAC,CAAA;IAEF,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,CAAC,GAAG,CAAC,sBAAsB,EAAE,WAAW,CAAC,CAAA;QAC/C,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA"}
+{"version":3,"file":"interact-for-workspace-id.js","sourceRoot":"","sources":["../src/lib/interact-for-workspace-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAEpD,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,EAAE,mBAA4B,EAAE,EAAE;IAC3E,MAAM,MAAM,GAAG,cAAc,EAAE,CAAA;IAC/B,MAAM,IAAI,GAAG,mBAAmB;QAC9B,CAAC,CAAC,wBAAwB,CAAC,uBAAuB,CAAC,mBAAmB,EAAE;YACpE,QAAQ,EAAE,SAAS,EAAE;SACtB,CAAC;QACJ,CAAC,CAAC,MAAM,qBAAqB,EAAE,CAAA;IAEjC,MAAM,UAAU,GAAG,MAAM,WAAW,CAAC,wBAAwB,EAAE,GAAG,EAAE,CAClE,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CACvB,CAAA;IACD,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC;QACnC,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,qBAAqB;QAC9B,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAc,EAAE,EAAE,CAAC,CAAC;YAC3C,KAAK,EAAE,SAAS,CAAC,IAAI;YACrB,KAAK,EAAE,SAAS,CAAC,YAAY;YAC7B,WAAW,EAAE,SAAS,CAAC,YAAY;SACpC,CAAC,CAAC;KACJ,CAAC,CAAA;IAEF,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,CAAC,GAAG,CAAC,sBAAsB,EAAE,WAAW,CAAC,CAAA;QAC/C,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA"}

package/lib/output/create-memory-output.d.ts

@@ -0,0 +1,13 @@
+import { type CreateOutputOptions, type Output } from './create-output.js';
+export interface MemoryOutput {
+    output: Output;
+    /** Everything written to stdout so far. */
+    stdout: () => string;
+    /** Everything written to stderr so far. */
+    stderr: () => string;
+}
+/**
+ * An {@link Output} that captures writes in memory instead of
+ * touching the process streams, for asserting on CLI output.
+ */
+export declare const createMemoryOutput: (options?: Omit<CreateOutputOptions, "stdout" | "stderr">) => MemoryOutput;

package/lib/output/create-memory-output.js

@@ -0,0 +1,22 @@
+import { createOutput, } from './create-output.js';
+const createMemoryStream = () => {
+    const chunks = [];
+    return {
+        write: (chunk) => chunks.push(chunk),
+        read: () => chunks.join(''),
+    };
+};
+/**
+ * An {@link Output} that captures writes in memory instead of
+ * touching the process streams, for asserting on CLI output.
+ */
+export const createMemoryOutput = (options = {}) => {
+    const stdout = createMemoryStream();
+    const stderr = createMemoryStream();
+    return {
+        output: createOutput({ ...options, stdout, stderr }),
+        stdout: stdout.read,
+        stderr: stderr.read,
+    };
+};
+//# sourceMappingURL=create-memory-output.js.map

package/lib/output/create-memory-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-memory-output.js","sourceRoot":"","sources":["../../src/lib/output/create-memory-output.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAIb,MAAM,oBAAoB,CAAA;AAU3B,MAAM,kBAAkB,GAAG,GAA0C,EAAE;IACrE,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,OAAO;QACL,KAAK,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;QAC5C,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;KAC5B,CAAA;AACH,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,UAA0D,EAAE,EAC9C,EAAE;IAChB,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IAEnC,OAAO;QACL,MAAM,EAAE,YAAY,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACpD,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,MAAM,EAAE,MAAM,CAAC,IAAI;KACpB,CAAA;AACH,CAAC,CAAA"}

package/lib/output/create-output.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Minimal writable surface needed by {@link Output}.
+ *
+ * Both `process.stdout` and an in-memory buffer satisfy this,
+ * which is what makes output testable.
+ */
+export interface OutputStream {
+    write: (chunk: string) => unknown;
+}
+/**
+ * `json` is machine readable: only {@link Output.data} produces output.
+ * `text` is human readable: data is pretty printed and may be colorized.
+ */
+export type OutputFormat = 'json' | 'text';
+export interface Output {
+    readonly format: OutputFormat;
+    /**
+     * The result of a command, e.g., an API response.
+     *
+     * This is the only thing ever written to stdout,
+     * so it is safe to pipe into another program.
+     */
+    data: (value: unknown) => void;
+    /**
+     * A plain text command result, e.g., the version or the help guide.
+     *
+     * Written to stdout verbatim in every format: these results are already
+     * a single value, so encoding them as JSON would only make them harder
+     * to consume from a pipe.
+     */
+    text: (value: string) => void;
+    /**
+     * Human facing progress, context, and confirmations.
+     *
+     * Written to stderr and suppressed entirely in the json format.
+     */
+    info: (message?: string) => void;
+    /** Human facing warning. Written to stderr in every format. */
+    warn: (message: string) => void;
+    /** Human facing error. Written to stderr in every format. */
+    error: (message: string) => void;
+}
+export interface CreateOutputOptions {
+    format?: OutputFormat;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    /** Colorize pretty printed data. Never applied to the json format. */
+    colors?: boolean;
+}
+export declare const createOutput: ({ format, stdout, stderr, colors, }?: CreateOutputOptions) => Output;

package/lib/output/create-output.js

@@ -0,0 +1,34 @@
+import { inspect } from 'node:util';
+export const createOutput = ({ format = 'text', stdout = process.stdout, stderr = process.stderr, colors = false, } = {}) => {
+    const isJson = format === 'json';
+    return {
+        format,
+        data: (value) => {
+            if (value === undefined)
+                return;
+            stdout.write(`${formatData(value, format, colors)}\n`);
+        },
+        text: (value) => {
+            stdout.write(`${value}\n`);
+        },
+        info: (message = '') => {
+            if (isJson)
+                return;
+            stderr.write(`${message}\n`);
+        },
+        warn: (message) => {
+            stderr.write(`${message}\n`);
+        },
+        error: (message) => {
+            stderr.write(`${message}\n`);
+        },
+    };
+};
+const formatData = (value, format, colors) => {
+    if (format === 'json')
+        return JSON.stringify(value, null, 2);
+    if (typeof value === 'string')
+        return value;
+    return inspect(value, { depth: null, colors });
+};
+//# sourceMappingURL=create-output.js.map

package/lib/output/create-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-output.js","sourceRoot":"","sources":["../../src/lib/output/create-output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AA4DnC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAC3B,MAAM,GAAG,MAAM,EACf,MAAM,GAAG,OAAO,CAAC,MAAM,EACvB,MAAM,GAAG,OAAO,CAAC,MAAM,EACvB,MAAM,GAAG,KAAK,MACS,EAAE,EAAU,EAAE;IACrC,MAAM,MAAM,GAAG,MAAM,KAAK,MAAM,CAAA;IAEhC,OAAO;QACL,MAAM;QAEN,IAAI,EAAE,CAAC,KAAc,EAAQ,EAAE;YAC7B,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAM;YAC/B,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;QACxD,CAAC;QAED,IAAI,EAAE,CAAC,KAAa,EAAQ,EAAE;YAC5B,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAA;QAC5B,CAAC;QAED,IAAI,EAAE,CAAC,OAAO,GAAG,EAAE,EAAQ,EAAE;YAC3B,IAAI,MAAM;gBAAE,OAAM;YAClB,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAA;QAC9B,CAAC;QAED,IAAI,EAAE,CAAC,OAAe,EAAQ,EAAE;YAC9B,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAA;QAC9B,CAAC;QAED,KAAK,EAAE,CAAC,OAAe,EAAQ,EAAE;YAC/B,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAA;QAC9B,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,MAAM,UAAU,GAAG,CACjB,KAAc,EACd,MAAoB,EACpB,MAAe,EACP,EAAE;IACV,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,OAAO,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAA;AAChD,CAAC,CAAA"}

package/lib/output/get-output.d.ts

@@ -0,0 +1,12 @@
+import { type Output } from './create-output.js';
+/**
+ * The output used by the CLI.
+ *
+ * Defaults to a `text` output bound to the real process streams,
+ * so importing modules never write to stdout by accident.
+ */
+export declare const getOutput: () => Output;
+/** Replace the output, e.g., once flags are parsed, or from a test. */
+export declare const setOutput: (nextOutput: Output) => void;
+/** Restore the default output. Intended for tests. */
+export declare const resetOutput: () => void;

package/lib/output/get-output.js

@@ -0,0 +1,21 @@
+import { createOutput } from './create-output.js';
+let output = null;
+/**
+ * The output used by the CLI.
+ *
+ * Defaults to a `text` output bound to the real process streams,
+ * so importing modules never write to stdout by accident.
+ */
+export const getOutput = () => {
+    output ??= createOutput();
+    return output;
+};
+/** Replace the output, e.g., once flags are parsed, or from a test. */
+export const setOutput = (nextOutput) => {
+    output = nextOutput;
+};
+/** Restore the default output. Intended for tests. */
+export const resetOutput = () => {
+    output = null;
+};
+//# sourceMappingURL=get-output.js.map

package/lib/output/get-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-output.js","sourceRoot":"","sources":["../../src/lib/output/get-output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAe,MAAM,oBAAoB,CAAA;AAE9D,IAAI,MAAM,GAAkB,IAAI,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAW,EAAE;IACpC,MAAM,KAAK,YAAY,EAAE,CAAA;IACzB,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED,uEAAuE;AACvE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,UAAkB,EAAQ,EAAE;IACpD,MAAM,GAAG,UAAU,CAAA;AACrB,CAAC,CAAA;AAED,sDAAsD;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,GAAS,EAAE;IACpC,MAAM,GAAG,IAAI,CAAA;AACf,CAAC,CAAA"}

package/lib/output/resolve-output-format.d.ts

@@ -0,0 +1,16 @@
+import type { OutputFormat } from './create-output.js';
+export interface ResolveOutputFormatOptions {
+    /** Whether stdout is a terminal. */
+    isTty?: boolean;
+}
+/**
+ * Whether to write machine readable output.
+ *
+ * An explicit `--json` or `--no-json` wins, otherwise the CLI writes JSON
+ * whenever stdout is piped or redirected, and pretty output at a terminal.
+ *
+ * This reads the arguments rather than the parsed args because `--json` is
+ * declared as a boolean flag, so that it never consumes the argument after
+ * it, and a boolean cannot tell `--no-json` apart from not passing anything.
+ */
+export declare const resolveOutputFormat: (argv: string[], { isTty }?: ResolveOutputFormatOptions) => OutputFormat;

package/lib/output/resolve-output-format.js

@@ -0,0 +1,23 @@
+/**
+ * Whether to write machine readable output.
+ *
+ * An explicit `--json` or `--no-json` wins, otherwise the CLI writes JSON
+ * whenever stdout is piped or redirected, and pretty output at a terminal.
+ *
+ * This reads the arguments rather than the parsed args because `--json` is
+ * declared as a boolean flag, so that it never consumes the argument after
+ * it, and a boolean cannot tell `--no-json` apart from not passing anything.
+ */
+export const resolveOutputFormat = (argv, { isTty = false } = {}) => {
+    const flag = argv.filter((arg) => arg === '--json' || arg === '--no-json');
+    // The last one wins, matching how the argument parser resolves repeats.
+    switch (flag[flag.length - 1]) {
+        case '--json':
+            return 'json';
+        case '--no-json':
+            return 'text';
+        default:
+            return isTty ? 'text' : 'json';
+    }
+};
+//# sourceMappingURL=resolve-output-format.js.map

package/lib/output/resolve-output-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-output-format.js","sourceRoot":"","sources":["../../src/lib/output/resolve-output-format.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,IAAc,EACd,EAAE,KAAK,GAAG,KAAK,KAAiC,EAAE,EACpC,EAAE;IAChB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,WAAW,CAAC,CAAA;IAE1E,wEAAwE;IACxE,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAC9B,KAAK,QAAQ;YACX,OAAO,MAAM,CAAA;QACf,KAAK,WAAW;YACd,OAAO,MAAM,CAAA;QACf;YACE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAA;IAClC,CAAC;AACH,CAAC,CAAA"}

package/lib/output/select-response-payload.d.ts

@@ -0,0 +1,16 @@
+export interface SelectResponsePayloadOptions {
+    /**
+     * The response key for the endpoint, e.g., `devices` for `/devices/list`,
+     * usually taken from the API blueprint.
+     *
+     * When omitted, every top level field except {@link metaKeys} is kept.
+     */
+    responseKey?: string | null | undefined;
+}
+/**
+ * Reduce an API response body to the response key and pagination.
+ *
+ * The CLI never reports other top level fields: they are details of the
+ * transport, so including them would leak into anything parsing stdout.
+ */
+export declare const selectResponsePayload: (data: unknown, { responseKey }?: SelectResponsePayloadOptions) => unknown;

package/lib/output/select-response-payload.js

@@ -0,0 +1,33 @@
+/**
+ * Top level response fields that are transport details,
+ * not part of the result the CLI reports.
+ */
+const metaKeys = new Set(['ok']);
+const paginationKey = 'pagination';
+const errorKey = 'error';
+/**
+ * Reduce an API response body to the response key and pagination.
+ *
+ * The CLI never reports other top level fields: they are details of the
+ * transport, so including them would leak into anything parsing stdout.
+ */
+export const selectResponsePayload = (data, { responseKey } = {}) => {
+    if (!isRecord(data))
+        return data;
+    if (errorKey in data) {
+        return { [errorKey]: data[errorKey] };
+    }
+    const keys = responseKey != null && responseKey in data
+        ? [responseKey]
+        : Object.keys(data).filter((key) => !metaKeys.has(key) && key !== paginationKey);
+    const payload = {};
+    for (const key of keys) {
+        payload[key] = data[key];
+    }
+    if (paginationKey in data) {
+        payload[paginationKey] = data[paginationKey];
+    }
+    return payload;
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+//# sourceMappingURL=select-response-payload.js.map

package/lib/output/select-response-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-response-payload.js","sourceRoot":"","sources":["../../src/lib/output/select-response-payload.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;AAEhC,MAAM,aAAa,GAAG,YAAY,CAAA;AAClC,MAAM,QAAQ,GAAG,OAAO,CAAA;AAYxB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,IAAa,EACb,EAAE,WAAW,KAAmC,EAAE,EACzC,EAAE;IACX,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAEhC,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAA;IACvC,CAAC;IAED,MAAM,IAAI,GACR,WAAW,IAAI,IAAI,IAAI,WAAW,IAAI,IAAI;QACxC,CAAC,CAAC,CAAC,WAAW,CAAC;QACf,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CACtB,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,aAAa,CACrD,CAAA;IAEP,MAAM,OAAO,GAA4B,EAAE,CAAA;IAC3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAED,IAAI,aAAa,IAAI,IAAI,EAAE,CAAC;QAC1B,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAA;IAC9C,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA"}

package/lib/render-help.d.ts

@@ -0,0 +1,8 @@
+import { type CommandSpec } from './command-spec.js';
+/**
+ * Render the help guide for a command path, or `null` when no command or
+ * group goes by that path.
+ *
+ * An empty path is the guide for `seam` itself.
+ */
+export declare const renderHelp: (path: string[], spec: CommandSpec) => string | null;

package/lib/render-help.js

@@ -0,0 +1,150 @@
+import commandLineUsage, {} from 'command-line-usage';
+import { findCommand, findGroup, } from './command-spec.js';
+/**
+ * Render the help guide for a command path, or `null` when no command or
+ * group goes by that path.
+ *
+ * An empty path is the guide for `seam` itself.
+ */
+export const renderHelp = (path, spec) => {
+    const group = findGroup(spec, path);
+    if (group != null)
+        return commandLineUsage(groupSections(group, spec));
+    const command = findCommand(spec, path);
+    if (command != null)
+        return commandLineUsage(commandSections(command, spec));
+    return null;
+};
+const overview = 'Every seam command runs as soon as every required property is given, and otherwise prompts you for what is missing with helpful suggestions. Pass -i to always review properties first, or -y to never be prompted.';
+const outputSection = {
+    header: 'Output',
+    content: [
+        'Only the response is written to stdout, so it is safe to pipe. Prompts, progress, and other information are written to stderr.',
+        'The response is trimmed to the response key and pagination.',
+        'Request params may be piped or redirected in as a JSON object. Params given as arguments win over params read from stdin.',
+    ],
+};
+const examples = [
+    { name: 'seam', summary: 'Interactively select commands to execute.' },
+    { name: 'seam login', summary: 'Login to Seam.' },
+    { name: 'seam wizard', summary: 'Set up Seam in the current project.' },
+    { name: 'seam select workspace', summary: 'Select your workspace.' },
+    {
+        name: 'seam connect-webviews create',
+        summary: 'Create a connect webview to connect devices.',
+    },
+    { name: 'seam devices list', summary: 'List devices in your workspace.' },
+    {
+        name: 'seam devices list {bold --interactive}',
+        summary: 'Review and edit filters before listing devices.',
+    },
+    {
+        name: 'seam devices list {bold --non-interactive}',
+        summary: 'List devices, failing instead of prompting.',
+    },
+    {
+        name: 'seam locks unlock-door {bold --device-id} $MY_DOOR',
+        summary: 'Unlock a lock.',
+    },
+    {
+        name: "seam access-codes create {bold --code} '1234' {bold --name} 'My Code'",
+        summary: 'Create an access code.',
+    },
+    {
+        name: 'seam devices list > devices.json',
+        summary: 'Write the response to a file as JSON.',
+    },
+    {
+        name: 'cat params.json | seam locks unlock-door',
+        summary: 'Pipe request params in as JSON.',
+    },
+    {
+        name: 'seam completion bash',
+        summary: 'Print a shell completion script for bash, fish, or zsh.',
+    },
+];
+const groupSections = (group, spec) => {
+    const isRoot = group.path.length === 0;
+    const name = ['seam', ...group.path].join(' ');
+    return [
+        isRoot
+            ? { header: 'Seam CLI', content: overview }
+            : { header: name, content: `Commands under ${name}.` },
+        { header: 'Usage', content: `${name} <command> [options]` },
+        ...commandSectionsForGroup(group, isRoot),
+        optionSection(spec.globalFlags),
+        ...(isRoot
+            ? [outputSection, { header: 'Command List Examples', content: examples }]
+            : []),
+        { content: `Run '${name} <command> --help' to see a command in detail.` },
+    ];
+};
+const commandSectionsForGroup = (group, isRoot) => {
+    const content = (subcommands) => subcommands.map(({ name, description }) => ({ name, summary: description }));
+    // The root guide separates the commands of the CLI itself from the commands
+    // that call the Seam API. Anywhere deeper the split adds nothing: a group
+    // holds commands of one kind.
+    if (!isRoot) {
+        return [{ header: 'Commands', content: content(group.subcommands) }];
+    }
+    const cli = group.subcommands.filter(({ kind }) => kind === 'cli');
+    const api = group.subcommands.filter(({ kind }) => kind === 'api');
+    return [
+        { header: 'Commands', content: content(cli) },
+        { header: 'API Commands', content: content(api) },
+    ].filter((section) => section.content.length > 0);
+};
+const commandSections = (command, spec) => {
+    const name = ['seam', ...command.path].join(' ');
+    const hasFlags = command.flags.length > 0;
+    return [
+        {
+            header: name,
+            content: [command.title, command.description].filter((line) => line !== ''),
+        },
+        { header: 'Usage', content: `${name} [options]` },
+        // The command's own parameters are what the request is made of, so keep
+        // them apart from the options every seam command takes.
+        ...(hasFlags ? [optionSection(command.flags, 'Parameters')] : []),
+        optionSection(spec.globalFlags),
+        ...(hasFlags
+            ? [
+                {
+                    content: 'Any required parameter left out is prompted for interactively.',
+                },
+            ]
+            : []),
+    ];
+};
+const optionSection = (flags, header = 'Options') => ({
+    header,
+    optionList: flags.map(toOptionDefinition),
+});
+const maxDocumentedValues = 8;
+const toOptionDefinition = (flag) => {
+    const description = [
+        flag.isRequired ? '{bold [required]}' : '',
+        flag.description,
+        describeValues(flag),
+    ]
+        .filter((part) => part !== '')
+        .join(' ');
+    return {
+        // command-line-usage renders a nameless option as the short form alone.
+        name: flag.long ?? '',
+        ...(flag.short == null ? {} : { alias: flag.short }),
+        // A flag with no value must be typed as a boolean, or the guide labels it
+        // as taking a string.
+        type: flag.takesValue ? String : Boolean,
+        ...(flag.takesValue ? { typeLabel: '{underline value}' } : {}),
+        description,
+    };
+};
+const describeValues = (flag) => {
+    if (flag.values.length === 0)
+        return '';
+    const shown = flag.values.slice(0, maxDocumentedValues).join(', ');
+    const rest = flag.values.length - maxDocumentedValues;
+    return rest > 0 ? `One of: ${shown}, and ${rest} more.` : `One of: ${shown}.`;
+};
+//# sourceMappingURL=render-help.js.map

package/lib/render-help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-help.js","sourceRoot":"","sources":["../src/lib/render-help.ts"],"names":[],"mappings":"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"}

package/lib/util/cli-args.d.ts

@@ -15,6 +15,11 @@ export type Interactivity = 'auto' | 'interactive' | 'non-interactive';
  * and are therefore not command parameters.
  */
 export declare const interactivityFlags: string[];
+/**
+ * Argument keys that configure the CLI itself
+ * and are therefore never sent as command parameters.
+ */
+export declare const cliFlags: string[];
 /**
  * Thrown when the CLI needs input it cannot prompt for.
  */
@@ -22,7 +27,17 @@ export declare class NonInteractiveError extends Error {
     name: string;
 }
 export declare const parseCliArgs: (argv: string[]) => ParsedArgs;
-export declare const getInteractivity: (args: ParsedArgs) => Interactivity;
+export interface GetInteractivityOptions {
+    /**
+     * Whether there is a terminal to prompt on.
+     *
+     * When there is not, the CLI cannot ask for anything, so it behaves as
+     * though `--non-interactive` was given rather than waiting on a prompt
+     * nobody can answer.
+     */
+    canPrompt?: boolean;
+}
+export declare const getInteractivity: (args: ParsedArgs, { canPrompt }?: GetInteractivityOptions) => Interactivity;
 /**
  * Render a parameter name as the argument used to set it,
  * e.g., `device_id` as `--device-id`.

package/lib/util/cli-args.js

@@ -9,6 +9,19 @@ export const interactivityFlags = [
     'interactive',
     'i',
 ];
+/**
+ * Argument keys that configure the CLI itself
+ * and are therefore never sent as command parameters.
+ */
+export const cliFlags = [
+    ...interactivityFlags,
+    'h',
+    'help',
+    'json',
+    'remote_api_defs',
+    'update',
+    'version',
+];
 /**
  * Thrown when the CLI needs input it cannot prompt for.
  */
@@ -17,12 +30,12 @@ export class NonInteractiveError extends Error {
 }
 export const parseCliArgs = (argv) => parseArgs(argv, {
     string: ['code'],
-    boolean: ['non-interactive', 'interactive'],
+    boolean: ['non-interactive', 'interactive', 'json'],
     // Deliberately not aliased to -n, which is reserved for a future
     // --dry-run flag.
     alias: { 'non-interactive': 'y', interactive: 'i' },
 });
-export const getInteractivity = (args) => {
+export const getInteractivity = (args, { canPrompt = true } = {}) => {
     const isNonInteractive = args['non_interactive'] === true || args['y'] === true;
     const isInteractive = args['interactive'] === true || args['i'] === true;
     if (isNonInteractive && isInteractive) {
@@ -30,8 +43,11 @@ export const getInteractivity = (args) => {
     }
     if (isNonInteractive)
         return 'non-interactive';
+    // An explicit --interactive still asks, and fails loudly if it cannot.
     if (isInteractive)
         return 'interactive';
+    if (!canPrompt)
+        return 'non-interactive';
     return 'auto';
 };
 /**

package/lib/util/cli-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../src/lib/util/cli-args.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,EAAE,EAAmB,MAAM,UAAU,CAAA;AAcrD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAa;IAC1C,iBAAiB;IACjB,GAAG;IACH,aAAa;IACb,GAAG;CACJ,CAAA;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,qBAAqB,CAAA;CACtC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAc,EAAc,EAAE,CACzD,SAAS,CAAC,IAAI,EAAE;IACd,MAAM,EAAE,CAAC,MAAM,CAAC;IAChB,OAAO,EAAE,CAAC,iBAAiB,EAAE,aAAa,CAAC;IAC3C,iEAAiE;IACjE,kBAAkB;IAClB,KAAK,EAAE,EAAE,iBAAiB,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE;CACpD,CAAC,CAAA;AAEJ,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAgB,EAAiB,EAAE;IAClE,MAAM,gBAAgB,GACpB,IAAI,CAAC,iBAAiB,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAA;IACxD,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAA;IAExE,IAAI,gBAAgB,IAAI,aAAa,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAA;IACH,CAAC;IACD,IAAI,gBAAgB;QAAE,OAAO,iBAAiB,CAAA;IAC9C,IAAI,aAAa;QAAE,OAAO,aAAa,CAAA;IACvC,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,aAAqB,EAAU,EAAE,CACzD,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAA"}
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../src/lib/util/cli-args.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,EAAE,EAAmB,MAAM,UAAU,CAAA;AAcrD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAa;IAC1C,iBAAiB;IACjB,GAAG;IACH,aAAa;IACb,GAAG;CACJ,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAa;IAChC,GAAG,kBAAkB;IACrB,GAAG;IACH,MAAM;IACN,MAAM;IACN,iBAAiB;IACjB,QAAQ;IACR,SAAS;CACV,CAAA;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,qBAAqB,CAAA;CACtC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAc,EAAc,EAAE,CACzD,SAAS,CAAC,IAAI,EAAE;IACd,MAAM,EAAE,CAAC,MAAM,CAAC;IAChB,OAAO,EAAE,CAAC,iBAAiB,EAAE,aAAa,EAAE,MAAM,CAAC;IACnD,iEAAiE;IACjE,kBAAkB;IAClB,KAAK,EAAE,EAAE,iBAAiB,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE;CACpD,CAAC,CAAA;AAaJ,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,IAAgB,EAChB,EAAE,SAAS,GAAG,IAAI,KAA8B,EAAE,EACnC,EAAE;IACjB,MAAM,gBAAgB,GACpB,IAAI,CAAC,iBAAiB,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAA;IACxD,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAA;IAExE,IAAI,gBAAgB,IAAI,aAAa,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAA;IACH,CAAC;IACD,IAAI,gBAAgB;QAAE,OAAO,iBAAiB,CAAA;IAC9C,uEAAuE;IACvE,IAAI,aAAa;QAAE,OAAO,aAAa,CAAA;IACvC,IAAI,CAAC,SAAS;QAAE,OAAO,iBAAiB,CAAA;IACxC,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,aAAqB,EAAU,EAAE,CACzD,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAA"}

package/lib/util/prompt.d.ts

@@ -0,0 +1,17 @@
+import { type Answers, type Options, type PromptObject } from 'prompts';
+/**
+ * Whether the CLI can ask the user a question.
+ *
+ * Prompts read raw keypresses and render an interface, so they need a
+ * terminal on both ends: when stdin is a pipe or a file it holds request
+ * params, not answers, and when stderr is redirected nobody sees the
+ * question.
+ */
+export declare const canPrompt: () => boolean;
+/**
+ * Ask the user a question.
+ *
+ * Prompts are rendered to stderr: a selection is not a command result,
+ * so it must not end up in stdout when the CLI is piped.
+ */
+export declare const prompt: <T extends string = string>(questions: PromptObject<T> | Array<PromptObject<T>>, options?: Options) => Promise<Answers<T>>;

package/lib/util/prompt.js

@@ -0,0 +1,25 @@
+import prompts, {} from 'prompts';
+import { NonInteractiveError } from './cli-args.js';
+/**
+ * Whether the CLI can ask the user a question.
+ *
+ * Prompts read raw keypresses and render an interface, so they need a
+ * terminal on both ends: when stdin is a pipe or a file it holds request
+ * params, not answers, and when stderr is redirected nobody sees the
+ * question.
+ */
+export const canPrompt = () => process.stdin.isTTY === true && process.stderr.isTTY === true;
+/**
+ * Ask the user a question.
+ *
+ * Prompts are rendered to stderr: a selection is not a command result,
+ * so it must not end up in stdout when the CLI is piped.
+ */
+export const prompt = async (questions, options) => {
+    if (!canPrompt()) {
+        throw new NonInteractiveError('Cannot prompt without a terminal: pass the missing arguments, or pipe them in as JSON');
+    }
+    const questionList = Array.isArray(questions) ? questions : [questions];
+    return await prompts(questionList.map((question) => ({ ...question, stdout: process.stderr })), options);
+};
+//# sourceMappingURL=prompt.js.map

package/lib/util/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/lib/util/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAiD,MAAM,SAAS,CAAA;AAEhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAY,EAAE,CACrC,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,KAAK,EACzB,SAAmD,EACnD,OAAiB,EACI,EAAE;IACvB,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,mBAAmB,CAC3B,uFAAuF,CACxF,CAAA;IACH,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAEvE,OAAO,MAAM,OAAO,CAClB,YAAY,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,EACzE,OAAO,CACR,CAAA;AACH,CAAC,CAAA"}