@shardflux/cli 0.4.0 → 0.5.0

package/dist/input.js

@@ -0,0 +1,167 @@
+/**
+ * Secrets a person types or a script pipes (0.5.0+): passwords never come from arguments (shell history and process
+ * listings would expose them; the parser refuses --password). On a terminal, `shard` prompts on stderr without echo
+ * (raw mode: Enter ends, Backspace and Ctrl-U edit, Ctrl-C interrupts, Ctrl-D on an empty line ends input); otherwise
+ * it reads standard input one line per secret, so a command that needs two (the current and the new password) reads
+ * two lines:
+ *
+ *   printf '%s\n' "$PASSWORD" | shard auth login --email me@example.com
+ *   printf '%s\n%s\n' "$OLD" "$NEW" | shard auth password change
+ *
+ * One Input serves the whole command, so several reads continue where the previous one stopped.
+ */
+import { InterruptedError, UsageError } from "./errors.js";
+/** More than any password or code: a runaway pipe is refused instead of buffered. */
+const MAX_PIPED_BYTES = 64 * 1024;
+export class Input {
+    #stdin;
+    #stderr;
+    #it = null;
+    #decoder = new TextDecoder('utf-8');
+    #buf = '';
+    #eof = false;
+    #read = 0;
+    constructor(stdin, stderr) {
+        this.#stdin = stdin;
+        this.#stderr = stderr;
+    }
+    /** True when standard input is a terminal `shard` can prompt on. */
+    get interactive() {
+        return this.#stdin.isTTY === true;
+    }
+    async #more() {
+        if (this.#eof)
+            return false;
+        this.#it ??= this.#stdin[Symbol.asyncIterator]();
+        const r = await this.#it.next();
+        if (r.done) {
+            this.#eof = true;
+            this.#buf += this.#decoder.decode();
+            return false;
+        }
+        const chunk = typeof r.value === 'string' ? Buffer.from(r.value) : r.value;
+        this.#read += chunk.length;
+        if (this.#read > MAX_PIPED_BYTES && !this.interactive)
+            throw new UsageError(`standard input exceeds ${MAX_PIPED_BYTES} bytes; pipe one secret per line`);
+        this.#buf += this.#decoder.decode(chunk, { stream: true });
+        return true;
+    }
+    /** The next line of piped input without its line ending, or null at the end of input. */
+    async line() {
+        for (;;) {
+            const nl = this.#buf.indexOf('\n');
+            if (nl >= 0) {
+                const line = this.#buf.slice(0, nl);
+                this.#buf = this.#buf.slice(nl + 1);
+                return line.endsWith('\r') ? line.slice(0, -1) : line;
+            }
+            if (!(await this.#more())) {
+                if (this.#buf.length === 0)
+                    return null;
+                const line = this.#buf;
+                this.#buf = '';
+                return line.endsWith('\r') ? line.slice(0, -1) : line;
+            }
+        }
+    }
+    /**
+     * A secret: a no-echo prompt on a terminal, else the next piped line. `what` names it in errors ("the password").
+     * An empty secret is refused.
+     */
+    async secret(prompt, what, pipeHint) {
+        const value = this.interactive ? await this.#prompt(prompt) : await this.line();
+        if (value === null) {
+            throw new UsageError(`${what} is read from standard input (never from arguments), and standard input ended: ${pipeHint}`);
+        }
+        if (value.length === 0)
+            throw new UsageError(`${what} is empty`);
+        return value;
+    }
+    /** A new password: asked twice (and compared) on a terminal, one piped line otherwise. */
+    async newPassword(prompt, what, pipeHint) {
+        const first = await this.secret(prompt, what, pipeHint);
+        if (!this.interactive)
+            return first;
+        const again = await this.secret('Repeat it: ', what, pipeHint);
+        if (again !== first)
+            throw new UsageError('the two passwords do not match');
+        return first;
+    }
+    /** A visible answer to a question on a terminal (e.g. an authenticator code), else the next piped line. */
+    async answer(prompt) {
+        if (!this.interactive)
+            return this.line();
+        return this.#prompt(prompt, true);
+    }
+    async #prompt(prompt, echo = false) {
+        const raw = this.#stdin.setRawMode;
+        if (typeof raw !== 'function')
+            throw new UsageError('standard input is a terminal that cannot hide what you type; pipe the value in instead');
+        this.#stderr.write(prompt);
+        raw.call(this.#stdin, true);
+        let value = '';
+        try {
+            for (;;) {
+                if (this.#buf.length === 0 && !(await this.#more())) {
+                    this.#stderr.write('\n');
+                    if (value.length > 0)
+                        return value;
+                    throw new UsageError('standard input ended before anything was entered');
+                }
+                while (this.#buf.length > 0) {
+                    const cp = this.#buf.codePointAt(0);
+                    const ch = String.fromCodePoint(cp);
+                    this.#buf = this.#buf.slice(ch.length);
+                    if (ch === '\r' || ch === '\n') {
+                        // A CR LF pair (a paste) ends the entry once.
+                        if (ch === '\r' && this.#buf.startsWith('\n'))
+                            this.#buf = this.#buf.slice(1);
+                        this.#stderr.write('\n');
+                        return value;
+                    }
+                    if (ch === '\u0003') {
+                        this.#stderr.write('\n');
+                        throw new InterruptedError('Interrupted.');
+                    }
+                    if (ch === '\u0004') {
+                        this.#stderr.write('\n');
+                        if (value.length > 0)
+                            return value;
+                        throw new UsageError('input ended before anything was entered');
+                    }
+                    if (ch === '\u007f' || ch === '\b') {
+                        if (value.length > 0) {
+                            const chars = [...value];
+                            chars.pop();
+                            value = chars.join('');
+                            if (echo)
+                                this.#stderr.write('\b \b');
+                        }
+                        continue;
+                    }
+                    if (ch === '\u0015') {
+                        if (echo)
+                            this.#stderr.write('\b \b'.repeat([...value].length));
+                        value = '';
+                        continue;
+                    }
+                    if (ch === '\u001b') {
+                        // An escape sequence (arrow keys, ...): CSI/SS3 up to its final byte, else the next character.
+                        const m = /^(?:\[[0-?]*[ -/]*[@-~]|O.|.)/s.exec(this.#buf);
+                        if (m)
+                            this.#buf = this.#buf.slice(m[0].length);
+                        continue;
+                    }
+                    if (cp < 0x20)
+                        continue;
+                    value += ch;
+                    if (echo)
+                        this.#stderr.write(ch);
+                }
+            }
+        }
+        finally {
+            raw.call(this.#stdin, false);
+        }
+    }
+}

package/dist/main.d.ts

@@ -1,6 +1,20 @@
 import type { Io } from './commands.js';
+import type { Distribution } from './update-check.js';
 /** A sleep that ends early when the signal aborts (so Ctrl-C never waits out a poll interval). */
 export declare function abortableSleep(signal: AbortSignal): (ms: number) => Promise<void>;
-export declare function run(argv: readonly string[], io: Io, opts?: {
+export interface RunOptions {
     signal?: AbortSignal;
-}): Promise<number>;
+    /** The package that runs the CLI, for the version check (default @shardflux/cli at CLI_VERSION). */
+    distribution?: Distribution;
+}
+export declare function run(argv: readonly string[], io: Io, opts?: RunOptions): Promise<number>;
+export interface MainOptions {
+    /** The package that runs the CLI (the `shardflux` bundle passes its name and version); default @shardflux/cli. */
+    distribution?: Distribution;
+}
+/**
+ * Runs `shard` as the process: argv, stdio and environment of this process. Ctrl-C aborts in-flight waits and
+ * streams cleanly (exit 130); a second Ctrl-C exits at once. Output is flushed before exiting (stdout/stderr pipes
+ * are asynchronous on macOS).
+ */
+export declare function main(opts?: MainOptions): Promise<never>;