qrcat 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +76 -40
  2. package/bin/qrcat.js +87 -4
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -7,72 +7,65 @@ qrcat is a terminal filter that detects URLs in your terminal output and generat
7
7
  **Example:**
8
8
 
9
9
  ```bash
10
- $ # Capture a terminal session, including both stdout and stderr
11
- $ (
12
- $ trap 'stty sane' EXIT
13
- $ script -qefc 'npm publish' /dev/null | qrcat
14
- $ )
10
+ $ # Login to npm in your computer by scanning a QR code with your phone
11
+ $ npm login | qrcat
12
+
13
+ $ # Or let qrcat run the command in a pseudo-terminal for you
14
+ $ qrcat -c "npm publish"
15
15
  ```
16
16
 
17
+ > **Note:** some interactive commands do not work with a simple pipe and need
18
+ > special redirection or a pseudo-terminal. Use `qrcat -c <command>` for such
19
+ > cases instead. See
20
+ > [Interactive commands and output streams](#interactive-commands-and-output-streams)
21
+ > for more information.
22
+
17
23
  ## Install
18
24
 
19
25
  ```bash
20
26
  npm install -g qrcat
21
27
  ```
22
28
 
23
- Or run from a checkout with `npm install` followed by `node bin/qrcat.js` (or `npm link`).
24
-
25
29
  ## Usage
26
30
 
27
- Pipe any command through `qrcat`. Each line is echoed unchanged; after any line
28
- containing an `http(s)` URL, one QR code per URL is printed directly below it.
29
- Multiple URLs on one line each get their own QR code.
31
+ Pipe any command through `qrcat` or use `qrcat -c` for interactive commands.
32
+ Each line is echoed unchanged; after any line containing an `http(s)` URL, one
33
+ QR code per URL is printed directly below it. Multiple URLs on one line each
34
+ get their own QR code.
30
35
 
31
36
  ```bash
32
37
  command | qrcat
38
+ qrcat -c "command"
33
39
  qrcat --help
34
40
  qrcat --version
35
41
  ```
36
42
 
37
43
  ### Interactive commands and output streams
38
44
 
39
- qrcat reads **stdin only**. A plain `|` connects stdout, while `2> >(qrcat)` sends
40
- only stderr. Commands may write different URLs to different streams. For
41
- example, `npm publish` writes its initial publishing notice to stderr, but its
42
- web-auth URL to stdout. Thus `npm publish 2> >(qrcat)` can show a QR for the
43
- registry notice but not the auth URL.
45
+ qrcat reads **stdin only**, and a plain `|` only pipes the command's stdout.
46
+ Interactive commands are trickier: they may write URLs to different streams,
47
+ and redirecting their output can change how they behave (for example, npm only
48
+ runs its interactive web-auth flow when stdout is a TTY).
44
49
 
45
- Redirecting stdout directly can also change command behavior: npm only runs its
46
- interactive web-auth flow when stdout is a TTY. `npm publish > >(qrcat)` makes
47
- stdout a pipe, and can make npm exit with `EOTP` instead of starting that flow.
48
-
49
- On Linux with util-linux `script`, capture both streams through a pseudo-terminal
50
- so the command still sees a TTY while qrcat receives its output:
50
+ The recommended way to run them is `-c`, which executes the command inside a
51
+ pseudo-terminal and processes its output directly (requires the util-linux
52
+ `script` utility, present on most GNU/Linux systems):
51
53
 
52
54
  ```bash
53
- (
54
- trap 'stty sane' EXIT
55
- script -qefc 'npm publish' /dev/null | qrcat
56
- )
55
+ qrcat -c "npm publish"
57
56
  ```
58
57
 
59
- This is useful for other interactive commands too. For non-interactive commands,
60
- ordinary pipes or process substitution are simpler; choose the stream(s) that
61
- actually contain the URLs. Process substitution (`> >(qrcat)`) requires bash or
62
- zsh and is not POSIX `sh`.
58
+ qrcat keeps the command's TTY checks intact, prints QR codes for its output as
59
+ it arrives, and restores your terminal settings when the command exits or is
60
+ interrupted, so Ctrl+C is safe.
63
61
 
64
- #### Caveat: restore the terminal after Ctrl+C
62
+ For non-interactive commands, ordinary pipes or process substitution are
63
+ simpler; choose the stream(s) that actually contain the URLs. If `-c` is not
64
+ available or does not fit your case, the
65
+ [Appendix](#appendix-manual-workarounds-for-interactive-commands) explains what
66
+ `-c` does and provides equivalent manual commands.
65
67
 
66
- On some systems, interrupting `script` with Ctrl+C can leave the outer terminal
67
- in raw mode. You may stop seeing typed input, and Ctrl+C may no longer interrupt
68
- the next command. Recover with:
69
-
70
- ```bash
71
- stty sane
72
- ```
73
-
74
- The example above runs `script` in a subshell with an `EXIT` trap to restore
75
- terminal settings automatically, including when interrupted.
68
+ ### Output handling notes
76
69
 
77
70
  qrcat emits newline-terminated lines as soon as they arrive. It also flushes an
78
71
  unterminated line after 100 ms of input inactivity, which supports interactive
@@ -90,8 +83,51 @@ they need a terminal with truecolor and `▀` support.
90
83
  ```bash
91
84
  npm install
92
85
  npm test # node:test suite
86
+ npm link . # Install locally for testing in your terminal
93
87
  ```
94
88
 
89
+ ## Appendix: manual workarounds for interactive commands
90
+
91
+ `qrcat -c "cmd"` is roughly equivalent to wrapping the command with util-linux
92
+ `script` and piping it through qrcat:
93
+
94
+ ```bash
95
+ (
96
+ trap 'stty sane' EXIT
97
+ script -qefc 'cmd' /dev/null | qrcat
98
+ )
99
+ ```
100
+
101
+ `script` runs the command inside a pseudo-terminal, so the command keeps its
102
+ TTYs while its combined stdout and stderr flow into qrcat.
103
+
104
+ The `trap` restores the outer terminal settings because interrupting `script`
105
+ with Ctrl+C can leave them in raw mode: you may stop seeing typed input, and
106
+ Ctrl+C may no longer interrupt the next command. Recover manually with:
107
+
108
+ ```bash
109
+ stty sane
110
+ ```
111
+
112
+ If you prefer to capture a single stream, process substitution connects it to
113
+ qrcat without touching the other one:
114
+
115
+ ```bash
116
+ some-command 2> >(qrcat) # capture stderr only
117
+ some-command > >(qrcat) # capture stdout only
118
+ ```
119
+
120
+ Beware that a plain `|` only pipes stdout, and `some-command 2>&1 | qrcat`
121
+ merges both streams into a pipe. Interactive commands can behave differently
122
+ when their stdout is not a TTY: npm, for instance, exits with `EOTP` instead of
123
+ starting its web-auth flow.
124
+
125
+ Platform notes:
126
+
127
+ - Process substitution (`> >(qrcat)`) requires bash or zsh; it is not POSIX `sh`.
128
+ - The `script -qefc` flags used by `-c` are util-linux's (GNU/Linux). BSD/macOS
129
+ `script` uses different flags, so `-c` is currently GNU/Linux-oriented.
130
+
95
131
  ## License
96
132
 
97
133
  [MIT](LICENSE)
package/bin/qrcat.js CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  import { readFileSync, realpathSync } from 'node:fs';
4
4
  import { fileURLToPath } from 'node:url';
5
+ import { spawn, execFileSync } from 'node:child_process';
5
6
  import QRCode from 'qrcode';
6
7
 
7
8
  const RESET = '\x1b[0m';
@@ -178,16 +179,86 @@ export function processInput(input, output = process.stdout, idleFlushMs = IDLE_
178
179
  function printHelp() {
179
180
  process.stdout.write(
180
181
  'qrcat - add QR codes for URLs in terminal output\n\n' +
181
- 'Usage: command | qrcat\n\n' +
182
- 'Reads stdin line by line, echoes each line unchanged, and prints a QR\n' +
183
- 'code right after any line containing an http(s) URL. Unterminated lines\n' +
184
- 'are flushed after 100 ms of input inactivity.\n\n' +
182
+ 'Usage: command | qrcat\n' +
183
+ ' qrcat -c "command"\n\n' +
184
+ 'qrcat reads the output of a command and prints a scannable QR code for\n' +
185
+ 'every http(s) URL it finds, so you can open the URL with your phone\n' +
186
+ 'instead of copying it by hand:\n\n' +
187
+ ' $ npm login | qrcat\n\n' +
188
+ 'Some interactive commands do not work "as is" and need special\n' +
189
+ 'redirection or a pseudo-terminal. With -c, qrcat runs the command in a\n' +
190
+ 'pseudo-terminal for you and prints its QR codes directly:\n\n' +
191
+ ' $ qrcat -c "npm publish"\n\n' +
192
+ 'Check the docs for details:\n\n' +
193
+ ' https://www.npmjs.com/package/qrcat\n\n' +
194
+ 'Tip: run `qrcat --help | qrcat` and get a QR code to the docs.\n\n' +
185
195
  'Options:\n' +
196
+ ' -c, --command run the given command in a pseudo-terminal and process\n' +
197
+ ' its output (requires the `script` utility)\n' +
186
198
  ' -h, --help show this help\n' +
187
199
  ' -v, --version show version\n',
188
200
  );
189
201
  }
190
202
 
203
+ /**
204
+ * Run `command` inside a pseudo-terminal (via the `script` utility) so the
205
+ * command keeps its TTY while qrcat processes its combined output, and restore
206
+ * the outer terminal settings on the way out (util-linux `script` can leave
207
+ * them in raw mode when interrupted).
208
+ */
209
+ async function runCommand(command) {
210
+ let savedTermios = null;
211
+ if (process.stdin.isTTY) {
212
+ try {
213
+ savedTermios = execFileSync('stty', ['-g'], {
214
+ stdio: ['ignore', 'pipe', 'ignore'],
215
+ encoding: 'utf8',
216
+ }).trim();
217
+ } catch {
218
+ savedTermios = null; // best effort: fall back to `stty sane` below
219
+ }
220
+ }
221
+
222
+ const restore = () => {
223
+ if (!process.stdin.isTTY) return;
224
+ try {
225
+ execFileSync('stty', [savedTermios ?? 'sane'], { stdio: ['ignore', 'ignore', 'ignore'] });
226
+ } catch {
227
+ // Nothing sensible left to try; the outer shell can still `stty sane`.
228
+ }
229
+ };
230
+
231
+ const child = spawn('script', ['-qefc', command, '/dev/null'], {
232
+ stdio: ['inherit', 'pipe', 'inherit'],
233
+ });
234
+
235
+ let childError = null;
236
+ child.on('error', (error) => {
237
+ childError = error;
238
+ });
239
+
240
+ const onSignal = (signal) => {
241
+ child.kill(signal);
242
+ };
243
+ process.on('SIGINT', onSignal);
244
+ process.on('SIGTERM', onSignal);
245
+
246
+ try {
247
+ await processInput(child.stdout);
248
+ } finally {
249
+ process.off('SIGINT', onSignal);
250
+ process.off('SIGTERM', onSignal);
251
+ restore();
252
+ }
253
+
254
+ const exitCode = await new Promise((resolve) => {
255
+ if (childError) return resolve(null);
256
+ child.on('close', (code) => resolve(code));
257
+ });
258
+ if (childError) throw childError;
259
+ if (exitCode !== 0) process.exitCode = exitCode ?? 1;
260
+ }
261
+
191
262
  async function main() {
192
263
  const args = process.argv.slice(2);
193
264
  if (args.includes('-h') || args.includes('--help')) {
@@ -205,6 +276,18 @@ async function main() {
205
276
  throw err;
206
277
  });
207
278
 
279
+ const commandIndex = args.findIndex((arg) => arg === '-c' || arg === '--command');
280
+ if (commandIndex !== -1) {
281
+ const command = args[commandIndex + 1];
282
+ if (!command || command.startsWith('-')) {
283
+ process.stderr.write('qrcat: -c/--command requires a command string\n');
284
+ process.exitCode = 1;
285
+ return;
286
+ }
287
+ await runCommand(command);
288
+ return;
289
+ }
290
+
208
291
  await processInput(process.stdin);
209
292
  }
210
293
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "qrcat",
3
- "version": "0.0.1",
3
+ "version": "0.0.2",
4
4
  "description": "Output filter to add QR codes to URLs",
5
5
  "keywords": [
6
6
  "QR",