@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.
- package/README.md +127 -31
- package/README.zh-hans-cn.md +331 -0
- package/THIRD_PARTY_NOTICES.md +2 -0
- package/dist/ai/chatgpt-models.js +148 -0
- package/dist/ai/chatgpt.js +495 -0
- package/dist/ai/command-schema.js +15 -1
- package/dist/ai/errors.js +6 -0
- package/dist/ai/gemini.js +117 -4
- package/dist/ai/index.js +4 -1
- package/dist/ai/openai.js +105 -2
- package/dist/ai/usage-session.js +144 -0
- package/dist/auth/chatgpt/commands.js +90 -0
- package/dist/auth/chatgpt/errors.js +85 -0
- package/dist/auth/chatgpt/http.js +97 -0
- package/dist/auth/chatgpt/index.js +229 -0
- package/dist/auth/chatgpt/instructions.js +22 -0
- package/dist/auth/chatgpt/oauth.js +320 -0
- package/dist/auth/chatgpt/storage.js +366 -0
- package/dist/auth/chatgpt/types.js +1 -0
- package/dist/cli.js +77 -16
- package/dist/config-file.js +2 -0
- package/dist/config.js +11 -4
- package/dist/errors.js +6 -1
- package/dist/execute.js +4 -13
- package/dist/index.js +32 -12
- package/dist/init/ChatGptInitializationStep.js +223 -0
- package/dist/init/InitializationApp.js +74 -38
- package/dist/init/index.js +24 -5
- package/dist/init/state.js +14 -3
- package/dist/prompt.js +56 -10
- package/dist/safety/command-risk.js +11 -0
- package/dist/safety/dangerous-command.js +209 -0
- package/dist/shell/command-analysis.js +25 -5
- package/dist/shell/execution-environment.js +25 -0
- package/dist/shell/runtime-environment.js +61 -0
- package/dist/ui/App.js +104 -15
- package/dist/ui/ConfirmView.js +8 -41
- package/dist/ui/InteractiveSessionProvider.js +7 -8
- package/dist/ui/ResolvePlaceholdersView.js +8 -3
- package/dist/ui/SelectCommandView.js +2 -2
- package/dist/ui/UsageApprovalView.js +320 -0
- package/dist/ui/interactive-session.js +243 -33
- package/dist/ui/keyboard-framing.js +102 -0
- package/dist/ui/paste-framing.js +69 -32
- package/dist/ui/resize-safe-output.js +2 -2
- package/dist/ui/run-interactive-command.js +2 -2
- package/dist/ui/text-input.js +4 -1
- package/dist/ui/use-keyboard-input.js +17 -2
- package/dist/ui/use-paste-aware-input.js +12 -3
- package/dist/usage/arguments.js +61 -0
- package/dist/usage/generate.js +156 -0
- package/dist/usage/output.js +216 -0
- package/dist/usage/risk.js +17 -0
- package/dist/usage/runner.js +238 -0
- package/dist/usage/types.js +1 -0
- package/dist/validation/ai-response.js +24 -3
- package/dist/validation/command-tool.js +7 -6
- package/dist/validation/usage-response.js +39 -0
- package/package.json +31 -17
- 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
|
[](https://github.com/prettier/prettier)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
English | [简体中文](README.
|
|
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** -
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
97
|
-
howto use find
|
|
98
|
-
howto
|
|
99
|
-
howto --ai-provider openai --print
|
|
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
|
-
|
|
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
|
-
|
|
120
|
-
|
|
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
|
-
|
|
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
|
-
|
|
126
|
-
|
|
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 `
|
|
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.
|
|
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-
|
|
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-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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/` -
|
|
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:
|