@unscientificjszhai/howto 1.0.1 → 1.1.0

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 (60) hide show
  1. package/README.md +127 -31
  2. package/README.zh-hans-cn.md +331 -0
  3. package/THIRD_PARTY_NOTICES.md +2 -0
  4. package/dist/ai/chatgpt-models.js +148 -0
  5. package/dist/ai/chatgpt.js +495 -0
  6. package/dist/ai/command-schema.js +15 -1
  7. package/dist/ai/errors.js +6 -0
  8. package/dist/ai/gemini.js +117 -4
  9. package/dist/ai/index.js +4 -1
  10. package/dist/ai/openai.js +105 -2
  11. package/dist/ai/usage-session.js +144 -0
  12. package/dist/auth/chatgpt/commands.js +90 -0
  13. package/dist/auth/chatgpt/errors.js +85 -0
  14. package/dist/auth/chatgpt/http.js +97 -0
  15. package/dist/auth/chatgpt/index.js +229 -0
  16. package/dist/auth/chatgpt/instructions.js +22 -0
  17. package/dist/auth/chatgpt/oauth.js +320 -0
  18. package/dist/auth/chatgpt/storage.js +366 -0
  19. package/dist/auth/chatgpt/types.js +1 -0
  20. package/dist/cli.js +77 -16
  21. package/dist/config-file.js +2 -0
  22. package/dist/config.js +11 -4
  23. package/dist/errors.js +6 -1
  24. package/dist/execute.js +4 -13
  25. package/dist/index.js +32 -12
  26. package/dist/init/ChatGptInitializationStep.js +223 -0
  27. package/dist/init/InitializationApp.js +74 -38
  28. package/dist/init/index.js +24 -5
  29. package/dist/init/state.js +14 -3
  30. package/dist/prompt.js +56 -10
  31. package/dist/safety/command-risk.js +11 -0
  32. package/dist/safety/dangerous-command.js +209 -0
  33. package/dist/shell/command-analysis.js +25 -5
  34. package/dist/shell/execution-environment.js +25 -0
  35. package/dist/shell/runtime-environment.js +61 -0
  36. package/dist/ui/App.js +104 -15
  37. package/dist/ui/ConfirmView.js +8 -41
  38. package/dist/ui/InteractiveSessionProvider.js +7 -8
  39. package/dist/ui/ResolvePlaceholdersView.js +8 -3
  40. package/dist/ui/SelectCommandView.js +2 -2
  41. package/dist/ui/UsageApprovalView.js +320 -0
  42. package/dist/ui/interactive-session.js +243 -33
  43. package/dist/ui/keyboard-framing.js +102 -0
  44. package/dist/ui/paste-framing.js +69 -32
  45. package/dist/ui/resize-safe-output.js +2 -2
  46. package/dist/ui/run-interactive-command.js +2 -2
  47. package/dist/ui/text-input.js +4 -1
  48. package/dist/ui/use-keyboard-input.js +17 -2
  49. package/dist/ui/use-paste-aware-input.js +12 -3
  50. package/dist/usage/arguments.js +61 -0
  51. package/dist/usage/generate.js +156 -0
  52. package/dist/usage/output.js +216 -0
  53. package/dist/usage/risk.js +17 -0
  54. package/dist/usage/runner.js +238 -0
  55. package/dist/usage/types.js +1 -0
  56. package/dist/validation/ai-response.js +24 -3
  57. package/dist/validation/command-tool.js +7 -6
  58. package/dist/validation/usage-response.js +39 -0
  59. package/package.json +31 -17
  60. package/README.CN.md +0 -235
package/README.md CHANGED
@@ -7,7 +7,7 @@ _Use AI to quickly find commands within the terminal._
7
7
  [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
8
8
  [![License](https://img.shields.io/github/license/UnscientificJsZhai/HowTo)](LICENSE)
9
9
 
10
- English | [简体中文](README.CN.md)
10
+ English | [简体中文](README.zh-hans-cn.md)
11
11
 
12
12
  [Features](#features) • [Install](#install) • [Usage](#usage) • [Configuration](#configuration) • [Development](#development) • [Troubleshooting](#troubleshooting)
13
13
 
@@ -22,11 +22,19 @@ English | [简体中文](README.CN.md)
22
22
  - **Tool-constrained mode** - use `howto use <command>` to require candidates around a specific CLI tool.
23
23
  - **Interactive review flow** - select a candidate, resolve placeholders, and confirm the final command before execution.
24
24
  - **Non-interactive print mode** - use `--print` to output candidates without TTY interaction or command execution.
25
- - **OpenAI and Gemini support** - configure either provider from CLI flags, environment variables, or `~/.howto/config.json`.
25
+ - **ChatGPT, OpenAI, and Gemini support** - sign in with ChatGPT to use an eligible plan, or keep using API keys and OpenAI-compatible services.
26
26
  - **Local validation first** - AI JSON output, placeholder references, `use <command>` candidates, and obvious dangerous commands are checked locally.
27
27
 
28
28
  ## Install
29
29
 
30
+ Requires **Node.js 22 or newer**. The npm package declares this through `engines.node`, matching the minimum version required by its existing runtime dependencies.
31
+
32
+ Only **macOS and Linux** are supported. Native Windows is unsupported, including CMD, PowerShell, and Git Bash/MSYS2 using Windows Node.js. WSL requires Node.js installed and running inside Linux; dedicated WSL acceptance testing has not been completed. Both npm installation and CLI startup check the operating system.
33
+
34
+ Interactive execution only supports `sh`, `bash`, and `zsh`. `SHELL` may be one of these bare names or an absolute path with one of these filenames, such as `/bin/zsh` or `/opt/homebrew/bin/bash`; relative paths and additional arguments are rejected. A missing or whitespace-only `SHELL` defaults to `/bin/sh`, including the system-provided `/bin/sh` symlink. Other shells are rejected before initialization or AI requests, without silently switching interpreters; the check runs again immediately before execution. To select an execution shell explicitly, use `env SHELL=/bin/bash howto "list files"`.
35
+
36
+ `--print`, `--init`, and `--version` do not execute candidate commands, so they check the operating system but do not restrict `SHELL`. Unsupported operating systems or execution shells return exit code `2`. This restriction applies to the outer interpreter launched by howto, not programs launched by candidate commands, and does not provide a sandbox.
37
+
30
38
  Install the CLI package globally:
31
39
 
32
40
  ```bash
@@ -36,7 +44,7 @@ npm install -g @unscientificjszhai/howto
36
44
  Or run it from a cloned repository:
37
45
 
38
46
  ```bash
39
- npm install
47
+ npm ci
40
48
  npm run build
41
49
  npm link
42
50
  ```
@@ -53,6 +61,22 @@ howto --init
53
61
 
54
62
  The initializer writes a user-level config file at `~/.howto/config.json`.
55
63
 
64
+ Choose **Continue with ChatGPT** to sign in through the system browser, select a saved account or add one, and choose a model from that account's live catalog. The official open-source Sign in with ChatGPT flow uses a local callback on `127.0.0.1`. It requires neither a client secret nor a Codex installation. Existing API key settings are preserved when switching providers.
65
+
66
+ For account management outside initialization:
67
+
68
+ ```bash
69
+ howto --chatgpt-login
70
+ howto --chatgpt-status
71
+ howto --chatgpt-models --chatgpt-account <account-id>
72
+ howto --chatgpt-login --chatgpt-account <account-id>
73
+ howto --chatgpt-logout --chatgpt-account <account-id>
74
+ ```
75
+
76
+ Login without `--chatgpt-account` adds a registration; with an account ID it renews that registration. Login alone does not change the selected provider or model. Run `howto --init` to save those choices. Ordinary generation and `--print` never start browser authorization. ChatGPT uses the account's current visible model slugs; it never silently switches models or falls back to API key billing.
77
+
78
+ ChatGPT credentials are stored separately in `~/.howto/chatgpt/` (private directory, owner-only files), with serialized refresh and logout across processes. Tokens are never put in `config.json`. If a refresh response is lost, sign in again rather than replaying a potentially consumed refresh token. Logout retains the registration for later sign-in and reports when remote revocation was not confirmed. Review app usage and permissions in [ChatGPT Settings](https://chatgpt.com/settings/usage). Eligibility and available models depend on the account; see the [official open-source flow](https://developers.openai.com/siwc/token-sharing-open-source).
79
+
56
80
  Initialization and placeholder input delete complete characters on Backspace, including emoji and combining sequences. Alt/Meta shortcuts are not inserted into configuration fields as text.
57
81
  Key release events never confirm, cancel, navigate, or delete; pressing and releasing Enter once cannot skip the final confirmation.
58
82
  Keyboard text and Enter are processed in order even when the terminal delivers them together. Once a step finishes, remaining keys in that batch cannot skip the next confirmation screen. Newlines inside paste remain data.
@@ -63,13 +87,13 @@ Keyboard text and Enter are processed in order even when the terminal delivers t
63
87
  Ask for a command:
64
88
 
65
89
  ```bash
66
- howto "find files modified in the last 7 days" .
90
+ howto find files modified in the last 7 days under .
67
91
  ```
68
92
 
69
93
  Limit candidates to a specific tool:
70
94
 
71
95
  ```bash
72
- howto use git "show commits from last week"
96
+ howto use git show commits from last week
73
97
  ```
74
98
 
75
99
  `use` checks the first actual tool exactly after environment assignments and supported `sudo`/`env` options. For example, `sudo -u root git status` satisfies `use git`, while `sudo -u git id` does not. Unknown wrapper options, missing option values, dynamic executable prefixes, and complex shell structures are rejected. This constraint applies to the first command segment, not subsequent segments.
@@ -79,24 +103,47 @@ Declared placeholders may appear after the first tool, as in `git log -n {{count
79
103
  Print command candidates without entering the interactive UI:
80
104
 
81
105
  ```bash
82
- howto --print "list the largest files" /var/log
106
+ howto --print list the largest files under /var/log
107
+ ```
108
+
109
+ ### ChatGPT login over SSH
110
+
111
+ On your computer with a browser, connect to the server with a loopback port forward:
112
+
113
+ ```bash
114
+ ssh -o ExitOnForwardFailure=yes -L 127.0.0.1:1455:127.0.0.1:1455 user@server
115
+ ```
116
+
117
+ In that remote shell, start login:
118
+
119
+ ```bash
120
+ howto --chatgpt-login --no-browser --callback-port 1455
83
121
  ```
84
122
 
123
+ Open the printed authorization URL in your local browser. Keep both the SSH connection and HowTo running until login completes. Replace `user@server` with your SSH destination. The browser redirects to its own `127.0.0.1`; the tunnel forwards that callback to HowTo on the server. No public callback listener is needed. The server still needs outbound HTTPS access to OpenAI's authentication and API services.
124
+
125
+ To sign in and save your provider/model choices in one interactive session, run `howto --init --no-browser --callback-port 1455` instead, then choose **Continue with ChatGPT**. Initialization requires a TTY; the standalone login command does not.
126
+
127
+ Both options are optional and apply only to `--chatgpt-login` or `--init`, only for the current invocation. `--no-browser` skips the browser launcher entirely and prints a link even when renewing an existing account. `--callback-port` accepts a decimal integer from `1` to `65535`; without it, HowTo chooses an available port and prints forwarding instructions for that port. These options are not saved in configuration and do not affect API key providers.
128
+
129
+ If either end cannot bind the chosen port, choose another available port and use it on both ends of the tunnel and in `--callback-port`. HowTo does not silently change an explicitly requested port. If already connected over SSH, use the printed `ssh -N ...` command in another local terminal before opening the URL. Login waits up to 10 minutes; Ctrl+C cancels it and releases the callback listener. Once authenticated, ordinary requests and token refreshes need no browser. This flow still requires browser approval on your local computer; it does not use device codes or accept pasted callback URLs.
130
+
85
131
  ## Usage
86
132
 
87
133
  ```text
88
- howto [options] [use <command>] <question> [<argument>...]
89
- howto --init
134
+ howto [options] [use <command>] <question...>
135
+ howto --init [--no-browser] [--callback-port <port>]
90
136
  howto --version
137
+ howto --chatgpt-login [--chatgpt-account <id>] [--no-browser] [--callback-port <port>]
91
138
  ```
92
139
 
93
140
  Examples:
94
141
 
95
142
  ```bash
96
- howto "find package.json under the current directory"
97
- howto use find "find a filename" package.json
98
- howto "explain this option" -- --force
99
- howto --ai-provider openai --print "show listening ports"
143
+ howto find package.json under the current directory
144
+ howto use find find report.txt under /tmp
145
+ howto explain this option -- --force
146
+ howto --ai-provider openai --print show listening ports
100
147
  ```
101
148
 
102
149
  Options:
@@ -104,7 +151,10 @@ Options:
104
151
  - `--init` - start interactive provider setup and save `~/.howto/config.json`.
105
152
  - `--version` - use alone to print the current package version and exit successfully; requires no configuration or TTY and makes no AI request.
106
153
  - `--print` - print validated command candidates and exit without executing.
107
- - `--ai-provider <openai|gemini>` - select the AI provider.
154
+ - `--ai-provider <openai|gemini|chatgpt>` - select the AI provider.
155
+ - `--chatgpt-account <id>` / `--chatgpt-model <slug>` - choose a local registration and an available ChatGPT model.
156
+ - `--no-browser` - skip the ChatGPT browser launcher and print the authorization URL; only with `--chatgpt-login` or `--init`.
157
+ - `--callback-port <port>` - use a specific ChatGPT loopback callback port (`1`–`65535`, random available port by default); only with `--chatgpt-login` or `--init`.
108
158
  - `--gemini-api-key <key>` - provide a Gemini API key.
109
159
  - `--gemini-model <model>` - override the Gemini model.
110
160
  - `--openai-api-url <url>` - use a custom OpenAI-compatible base URL.
@@ -114,17 +164,25 @@ Options:
114
164
 
115
165
  ### Argument Parsing
116
166
 
117
- `question` is one shell argument. Quote it when it contains spaces:
167
+ All question fragments are joined with one ASCII space. In `use` mode, the first positional token is `use`, the next is the tool name, and all remaining fragments form the question. Global options may appear anywhere before `--`; unknown long options are rejected. Everything after `--` is positional text.
118
168
 
119
- ```bash
120
- howto "find recently changed files" /tmp
121
- ```
169
+ | Input | Final question |
170
+ | ------------------------------------------- | ---------------------------- |
171
+ | `howto list files changed today` | `list files changed today` |
172
+ | `howto "list files" /tmp` | `list files /tmp` |
173
+ | `howto use find find report.txt under /tmp` | `find report.txt under /tmp` |
174
+ | `howto list files --print` | `list files` (print mode) |
175
+ | `howto explain -- --force` | `explain --force` |
176
+ | `howto find files "/tmp/my files"` | `find files /tmp/my files` |
177
+ | `howto "" " "` | Usage error |
122
178
 
123
- Everything after the question is passed to the AI as `argument[]`. Use `--` when an argument starts with `--`:
179
+ Whitespace and line breaks inside each fragment are preserved. Missing or entirely whitespace questions exit with code `2` and Usage before configuration loading or AI requests. The question itself is never trimmed, and quotes or fragment boundaries are not reconstructed or sent separately.
124
180
 
125
- ```bash
126
- howto "explain this flag" -- --force
127
- ```
181
+ The model infers paths, filenames, counts, and options from the complete question. Clear values become command parameters; required values that are missing or ambiguous become placeholders for the existing fill-and-confirm flow.
182
+
183
+ Quoted questions remain valid. Older “question + extra parameters” invocations now form one question, with no separate parameter grouping. Original shell argument boundaries cannot be recovered after joining, so paths containing spaces are interpreted from the question's meaning; describe their purpose clearly.
184
+
185
+ Unquoted input is convenient for ordinary question text. Your shell still processes variables, wildcards, redirections, and other special syntax before howto receives it; quote or escape these when you need literal text. Existing management actions and repeated-option rules are unchanged; no configuration migration is needed.
128
186
 
129
187
  ## Configuration
130
188
 
@@ -139,12 +197,14 @@ The config path uses `HOME` when it is an absolute path. If `HOME` is missing or
139
197
 
140
198
  For each setting, the first configured source in that order wins:
141
199
 
142
- - `--ai-provider` / `HOWTO_AI_PROVIDER` / `aiProvider` - `openai` or `gemini`; no default.
200
+ - `--ai-provider` / `HOWTO_AI_PROVIDER` / `aiProvider` - `openai`, `gemini`, or `chatgpt`; no default.
201
+ - `--chatgpt-account` / `HOWTO_CHATGPT_ACCOUNT` / `chatgptAccount` - local ChatGPT registration ID; required when more than one account is saved.
202
+ - `--chatgpt-model` / `HOWTO_CHATGPT_MODEL` / `chatgptModel` - visible model slug from `--chatgpt-models`; no static default.
143
203
  - `--gemini-api-key` / `HOWTO_GEMINI_API_KEY` / `geminiApiKey` - Gemini API key; required for Gemini.
144
- - `--gemini-model` / `HOWTO_GEMINI_MODEL` / `geminiModel` - Gemini model; default `gemini-3.1-flash-lite`.
204
+ - `--gemini-model` / `HOWTO_GEMINI_MODEL` / `geminiModel` - Gemini model; default `gemini-3.5-flash-lite`.
145
205
  - `--openai-api-url` / `HOWTO_OPENAI_API_URL` / `openaiApiUrl` - OpenAI-compatible base URL; defaults to `https://api.openai.com/v1`.
146
206
  - `--openai-api-key` / `HOWTO_OPENAI_API_KEY` / `openaiApiKey` - OpenAI API key; defaults to an empty string for local services.
147
- - `--openai-model` / `HOWTO_OPENAI_MODEL` / `openaiModel` - OpenAI model; default `gpt-5.4-mini`.
207
+ - `--openai-model` / `HOWTO_OPENAI_MODEL` / `openaiModel` - OpenAI model; default `gpt-6-luna`.
148
208
  - `--structured-output` / `HOWTO_STRUCTURED_OUTPUT` / `structuredOutput` - use provider schema structured output; default `true`.
149
209
 
150
210
  howto sets the request endpoint and Gemini API mode explicitly. `OPENAI_BASE_URL`, `GOOGLE_GEMINI_BASE_URL`, `GOOGLE_VERTEX_BASE_URL`, and the Google SDK's Vertex/Enterprise environment switches do not override them. Gemini uses the official `generativelanguage.googleapis.com` `v1beta` API. Use the HOWTO settings above for a custom OpenAI endpoint.
@@ -155,7 +215,7 @@ Example:
155
215
 
156
216
  ```bash
157
217
  HOWTO_AI_PROVIDER=openai \
158
- HOWTO_OPENAI_MODEL=gpt-5.4-mini \
218
+ HOWTO_OPENAI_MODEL=gpt-6-luna \
159
219
  howto --print "show current branch"
160
220
  ```
161
221
 
@@ -167,12 +227,20 @@ howto --print "show current branch"
167
227
  - the response contains between one and three candidates;
168
228
  - all placeholders use `{{name}}` syntax and are declared consistently, with each name declared once per candidate and repeated references sharing one input value;
169
229
  - `use <command>` candidates clearly start with the requested tool after conservative prefix handling;
170
- - obvious dangerous patterns require typing `EXECUTE` before they can run; matching is case-insensitive.
230
+ - commands flagged by local checks, inconclusive local analysis, or AI require typing `EXECUTE` before they can run; matching is case-insensitive.
231
+
232
+ In the same request that generates candidates, AI must return a boolean `dangerous` and a string `dangerReason` for each candidate. A flagged command requires a brief, non-whitespace reason; an unflagged command requires exactly `""`. Missing fields, incorrect types, or inconsistent combinations reject the entire response with exit code `2`, including older responses without these fields. Both providers and output modes use the same contract.
233
+
234
+ The prompt asks AI to assess complete commands for data loss, important data overwrites, destructive history changes, system or permission changes, service disruption, sensitive information disclosure, and untrusted code execution, supplementing operations local rules may miss. Ordinary queries, file creation, and routine builds are not automatically flagged merely because they have side effects.
235
+
236
+ Final confirmation always checks the command after placeholder substitution and retains the original candidate's AI flag. An AI false flag cannot lower a local danger or inconclusive result. AI-only risks show `AI: <reason>`; when both checks flag a command, the local reason is preserved and the AI reason is appended. Filling placeholders does not trigger another AI request or send the entered values. `--print` validates these fields while continuing to output only commands.
171
237
 
172
238
  Dangerous-command detection currently covers high-risk patterns such as recursive destructive `rm`, disk and filesystem operations, broad recursive permission changes, downloaded scripts piped into a shell, high-impact package manager operations, and service changes.
173
239
 
174
240
  Local analysis handles literal quoting, absolute command paths, and supported `sudo`/`env` options, and checks each command segment. Unknown wrapper options, dynamic executable prefixes, and shell syntax outside the supported subset also require `EXECUTE`, so an inconclusive analysis does not skip the additional confirmation.
175
241
 
242
+ Command bodies passed to `ash` or `hush`, and BusyBox applet dispatch, conservatively require additional confirmation, including calls such as `busybox ls` whose applets are not analyzed. The outer execution shell remains limited to sh/bash/zsh.
243
+
176
244
  Line continuations within numeric file descriptors require additional confirmation and are rejected by `use` because shells interpret them differently. Risk analysis recognizes high-risk paths with redundant dots or slashes, such as `./../important` and `///dev/disk2`, without collapsing `..` or changing the command that runs.
177
245
 
178
246
  Assignments passed to `env` can use names starting with digits or containing hyphens or dots; the actual command after them is still checked. Official npm global install/uninstall aliases such as `i`, `add`, `un`, and `unlink` receive the same additional confirmation. Inconclusive abbreviations of those actions also require confirmation.
@@ -180,19 +248,27 @@ Leading `NAME+=value` requires additional confirmation and is rejected by `use`
180
248
 
181
249
  Homebrew uninstall aliases such as `rm/uninstal`, and yum/dnf upgrade or removal commands such as `update/erase`, receive the same additional confirmation. Actions are interpreted separately for each tool; metadata updates through `apt update` and `brew update/up` are not classified as system package upgrades.
182
250
 
183
- If howto detects bracketed paste during an interactive run, including automatic initialization, that run permanently switches to printing the final command for manual execution. At final confirmation, Enter prints the command without running it, and the terminal shows an explanation. Returning to selection or resizing the terminal does not restore execution. Keyboard-only runs keep the usual Enter or `EXECUTE` confirmation.
251
+ Linux checks also cover system package changes through apk, pacman, and zypper, and OpenRC service or runlevel changes, such as `apk upgrade`, `pacman -Syu`, `zypper dup`, `rc-service sshd stop`, and `rc-update del sshd`. Common queries and apk/zypper metadata refreshes keep ordinary confirmation; unsupported options, dynamic arguments, and additional service commands conservatively require `EXECUTE`. Query arguments are also checked: `zypper repos --export …`, which writes to a file, still requires additional confirmation.
252
+
253
+ Pasting does not disable command execution or `use` lookups. API key, placeholder, and query argument fields accept complete paste blocks; CR/LF remain data and never submit a field. Submitting a field discards remaining keys and pastes from that input batch. Selection, query approval, and final confirmation screens ignore paste. Type `EXECUTE` on the keyboard for dangerous commands; execution still requires a separate confirmation.
184
254
 
185
- Paste spanning a hidden terminal view is discarded as a whole. These rules apply to recognized bracketed-paste input; the terminal protocol cannot authenticate arbitrary pasted keystrokes or embedded end markers. The execution restriction applies to howto's own command launch.
255
+ Paste containing unsupported control characters (including Tab), or spanning a field, screen, or hidden view, is discarded with an explanation. Each paste is limited to 256 KiB. An unfinished paste cancels the interaction after 5 seconds without new data or 30 seconds in total, restores the terminal, and exits with status 1 without executing a command.
256
+
257
+ These rules cover complete, valid bracketed paste. The terminal protocol cannot authenticate embedded end markers or delayed bytes after them, or reliably distinguish unframed paste from typing. Screen isolation does not guarantee that arbitrary forged protocol input cannot trigger execution.
186
258
 
187
259
  > [!WARNING]
188
- > A command not flagged as dangerous is not guaranteed to be safe. The local checks add confirmation for known high-risk patterns and syntax they cannot analyze; they do not prove command safety.
260
+ > A command that passes local checks and is not flagged by AI is not guaranteed to be safe. These checks add confirmation requirements; they do not provide a complete safety proof or guarantee AI assessment accuracy.
189
261
 
190
262
  ## Development
191
263
 
192
264
  This project is built with TypeScript, React, Ink, OpenAI SDK, Gemini GenAI SDK, and Node's built-in test runner.
193
265
 
266
+ For development and the full test suite, use **Node.js 22.x (22.22.1 or later) or 24.x (24.3.0 or later)**. These versions satisfy the development dependencies.
267
+
268
+ Builds use TypeScript 7 through the `@typescript/native` npm alias. ESLint retains the TypeScript 6 JavaScript API through `typescript` → `@typescript/typescript6` (currently forwarding to 6.0.3), following the [official side-by-side setup](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0). Build scripts invoke the native compiler explicitly because incremental npm installs can change the shared `tsc` symlink. `npm run check:toolchain` verifies compiler versions, compatibility API resolution, and explicit build compiler paths. Run `npm run lint` to check project code with the existing type-aware rules. Keep both compilers compatible with the project until typescript-eslint supports the new API; this does not give ESLint TypeScript 7-only language support.
269
+
194
270
  ```bash
195
- npm install
271
+ npm ci
196
272
  npm run build
197
273
  npm test
198
274
  npm run lint
@@ -208,10 +284,30 @@ Useful paths:
208
284
  - `src/validation/` - AI response and command-tool validation.
209
285
  - `src/safety/` - dangerous command rules.
210
286
  - `src/ui/` - Ink-based terminal UI.
211
- - `tests/unit/` - unit tests for CLI, config, validation, execution, UI, and safety logic.
287
+ - `tests/unit/` - argument parsing, configuration merging, validation, prompts, pure UI logic and static rendering, and providers with dependency stubs.
288
+ - `tests/integration/` - filesystem and credential storage, real SDK serialization, Ink component interactions and complete UI flows, CLI processes, loopback HTTP providers, and PTY sessions.
289
+ - `tests/helpers/` - input streams, request data, and rendering helpers shared by both suites.
290
+
291
+ `npm test` runs both suites; use `npm run test:unit` or `npm run test:integration` to run one suite independently.
292
+
293
+ ### Linux validation
294
+
295
+ The 1.0.2 local validation used Debian 13.6 x86_64 in a Cloud container, Node 22.22.1 / 24.19.0, and real kernel PTYs with dash (`/bin/sh`), bash 5.2.37 and zsh 5.9. Both Node versions passed 719 tests without skips, including 42 PTY cases; stability rounds and additional boundary evidence are recorded in the validation report. The installed package was checked separately on Node 22.0.0 with npm 10.5.1. Evidence, fixes and coverage limits are recorded in the validation report delivered separately with this task.
296
+
297
+ The full POSIX suite requires Python 3 available on `/usr/bin:/bin`, sh/bash/zsh, an allocatable PTY, and a non-root user for permission checks. Some Linux process-group checks use a subprocess supervisor and are explicitly inapplicable to macOS. Tests use isolated temporary homes and fake providers; they do not require API keys. To verify a separately installed package, run `npm run test:package -- /absolute/path/to/bin/howto`; this compiles and runs `tests/package-smoke.ts`, uses a local HTTP fixture, and only executes a harmless print command after confirmation.
298
+
299
+ Test CI runs only on Ubuntu 24.04 with Node 24.19.0. Pushes run unit tests; pull requests and manual runs execute both unit and integration tests. All runs also build the project and check lint and formatting. macOS runners, Node 22 jobs, and installed-package smoke jobs are excluded from CI; the local package smoke command remains available. Alpine, native arm64, WSL, and real terminal-emulator visuals remain unverified; a PTY or a configured job is not evidence for those platforms. A separate environment passed bounded live Gemini native and OpenAI-compatible protocol smoke checks; native structured-output OFF, the default model, and the full live CLI remain unverified.
212
300
 
213
301
  ## Troubleshooting
214
302
 
303
+ ### Linux terminal and output failures
304
+
305
+ Linux interactive handoff requires access to `/proc/self/fd/0` to check pasted bytes still queued in the kernel. A read failure prevents execution. The corresponding macOS kernel-queue boundary still requires dedicated validation.
306
+
307
+ Both stdin and stdout must be TTYs for interactive mode and `--init`. Use `--print` when either stream is redirected. A closed stdout pipe now exits with status 1 and a fixed error message; do not treat truncated output as successful delivery. If PTY tests cannot find Python, check `PATH=/usr/bin:/bin python3 --version`; CI treats missing prerequisites and Linux test skips as failures.
308
+
309
+ HowTo invokes the selected shell with `-c`, not as a login shell. This does not promise a clean environment: shell startup files and inherited variables can affect commands. Configuration files are written atomically with mode 0600; existing directory permissions and symlinks are preserved. Protect the configuration directory and its parent from other users, especially with a permissive umask.
310
+
215
311
  ### AI provider is not configured
216
312
 
217
313
  Run: