claws-code 0.8.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 (180) hide show
  1. package/.claude/commands/claws-auto.md +90 -0
  2. package/.claude/commands/claws-bin.md +28 -0
  3. package/.claude/commands/claws-cleanup.md +28 -0
  4. package/.claude/commands/claws-do.md +82 -0
  5. package/.claude/commands/claws-fix.md +40 -0
  6. package/.claude/commands/claws-goal.md +111 -0
  7. package/.claude/commands/claws-help.md +54 -0
  8. package/.claude/commands/claws-plan.md +103 -0
  9. package/.claude/commands/claws-report.md +29 -0
  10. package/.claude/commands/claws-status.md +37 -0
  11. package/.claude/commands/claws-update.md +32 -0
  12. package/.claude/commands/claws.md +64 -0
  13. package/.claude/rules/claws-default-behavior.md +76 -0
  14. package/.claude/settings.json +112 -0
  15. package/.claude/settings.local.json +19 -0
  16. package/.claude/skills/claws-auto-engine/SKILL.md +97 -0
  17. package/.claude/skills/claws-goal-tracker/SKILL.md +106 -0
  18. package/.claude/skills/claws-prompt-templates/SKILL.md +203 -0
  19. package/.claude/skills/claws-wave-lead/SKILL.md +126 -0
  20. package/.claude/skills/claws-wave-subworker/SKILL.md +60 -0
  21. package/CHANGELOG.md +1949 -0
  22. package/LICENSE +21 -0
  23. package/README.md +420 -0
  24. package/bin/cli.js +84 -0
  25. package/cli.js +223 -0
  26. package/docs/ARCHITECTURE.md +511 -0
  27. package/docs/event-protocol.md +588 -0
  28. package/docs/features.md +562 -0
  29. package/docs/guide.md +891 -0
  30. package/docs/index.html +716 -0
  31. package/docs/protocol.md +323 -0
  32. package/extension/.vscodeignore +15 -0
  33. package/extension/CHANGELOG.md +1906 -0
  34. package/extension/LICENSE +21 -0
  35. package/extension/README.md +137 -0
  36. package/extension/docs/features.md +424 -0
  37. package/extension/docs/protocol.md +197 -0
  38. package/extension/esbuild.mjs +25 -0
  39. package/extension/icon.png +0 -0
  40. package/extension/native/.metadata.json +10 -0
  41. package/extension/native/node-pty/LICENSE +69 -0
  42. package/extension/native/node-pty/README.md +165 -0
  43. package/extension/native/node-pty/lib/conpty_console_list_agent.js +16 -0
  44. package/extension/native/node-pty/lib/conpty_console_list_agent.js.map +1 -0
  45. package/extension/native/node-pty/lib/eventEmitter2.js +47 -0
  46. package/extension/native/node-pty/lib/eventEmitter2.js.map +1 -0
  47. package/extension/native/node-pty/lib/index.js +52 -0
  48. package/extension/native/node-pty/lib/index.js.map +1 -0
  49. package/extension/native/node-pty/lib/interfaces.js +7 -0
  50. package/extension/native/node-pty/lib/interfaces.js.map +1 -0
  51. package/extension/native/node-pty/lib/shared/conout.js +11 -0
  52. package/extension/native/node-pty/lib/shared/conout.js.map +1 -0
  53. package/extension/native/node-pty/lib/terminal.js +190 -0
  54. package/extension/native/node-pty/lib/terminal.js.map +1 -0
  55. package/extension/native/node-pty/lib/types.js +7 -0
  56. package/extension/native/node-pty/lib/types.js.map +1 -0
  57. package/extension/native/node-pty/lib/unixTerminal.js +346 -0
  58. package/extension/native/node-pty/lib/unixTerminal.js.map +1 -0
  59. package/extension/native/node-pty/lib/utils.js +39 -0
  60. package/extension/native/node-pty/lib/utils.js.map +1 -0
  61. package/extension/native/node-pty/lib/windowsConoutConnection.js +125 -0
  62. package/extension/native/node-pty/lib/windowsConoutConnection.js.map +1 -0
  63. package/extension/native/node-pty/lib/windowsPtyAgent.js +320 -0
  64. package/extension/native/node-pty/lib/windowsPtyAgent.js.map +1 -0
  65. package/extension/native/node-pty/lib/windowsTerminal.js +199 -0
  66. package/extension/native/node-pty/lib/windowsTerminal.js.map +1 -0
  67. package/extension/native/node-pty/lib/worker/conoutSocketWorker.js +22 -0
  68. package/extension/native/node-pty/lib/worker/conoutSocketWorker.js.map +1 -0
  69. package/extension/native/node-pty/package.json +64 -0
  70. package/extension/native/node-pty/prebuilds/darwin-arm64/pty.node +0 -0
  71. package/extension/native/node-pty/prebuilds/darwin-arm64/spawn-helper +0 -0
  72. package/extension/native/node-pty/prebuilds/darwin-x64/pty.node +0 -0
  73. package/extension/native/node-pty/prebuilds/darwin-x64/spawn-helper +0 -0
  74. package/extension/native/node-pty/prebuilds/win32-arm64/conpty/OpenConsole.exe +0 -0
  75. package/extension/native/node-pty/prebuilds/win32-arm64/conpty/conpty.dll +0 -0
  76. package/extension/native/node-pty/prebuilds/win32-arm64/conpty.node +0 -0
  77. package/extension/native/node-pty/prebuilds/win32-arm64/conpty_console_list.node +0 -0
  78. package/extension/native/node-pty/prebuilds/win32-arm64/pty.node +0 -0
  79. package/extension/native/node-pty/prebuilds/win32-arm64/winpty-agent.exe +0 -0
  80. package/extension/native/node-pty/prebuilds/win32-arm64/winpty.dll +0 -0
  81. package/extension/native/node-pty/prebuilds/win32-x64/conpty/OpenConsole.exe +0 -0
  82. package/extension/native/node-pty/prebuilds/win32-x64/conpty/conpty.dll +0 -0
  83. package/extension/native/node-pty/prebuilds/win32-x64/conpty.node +0 -0
  84. package/extension/native/node-pty/prebuilds/win32-x64/conpty_console_list.node +0 -0
  85. package/extension/native/node-pty/prebuilds/win32-x64/pty.node +0 -0
  86. package/extension/native/node-pty/prebuilds/win32-x64/winpty-agent.exe +0 -0
  87. package/extension/native/node-pty/prebuilds/win32-x64/winpty.dll +0 -0
  88. package/extension/package-lock.json +605 -0
  89. package/extension/package.json +343 -0
  90. package/extension/scripts/bundle-native.mjs +104 -0
  91. package/extension/scripts/deploy-dev.mjs +60 -0
  92. package/extension/src/ansi-strip.ts +52 -0
  93. package/extension/src/backends/vscode/claws-pty.ts +483 -0
  94. package/extension/src/backends/vscode/status-bar.ts +99 -0
  95. package/extension/src/backends/vscode/vscode-backend.ts +282 -0
  96. package/extension/src/capture-store.ts +125 -0
  97. package/extension/src/event-log.ts +629 -0
  98. package/extension/src/event-schemas.ts +478 -0
  99. package/extension/src/extension.js +492 -0
  100. package/extension/src/extension.ts +873 -0
  101. package/extension/src/lifecycle-engine.ts +60 -0
  102. package/extension/src/lifecycle-rules.ts +171 -0
  103. package/extension/src/lifecycle-store.ts +506 -0
  104. package/extension/src/peer-registry.ts +176 -0
  105. package/extension/src/pipeline-registry.ts +82 -0
  106. package/extension/src/platform.ts +64 -0
  107. package/extension/src/protocol.ts +532 -0
  108. package/extension/src/server-config.ts +98 -0
  109. package/extension/src/server.ts +2210 -0
  110. package/extension/src/task-registry.ts +51 -0
  111. package/extension/src/terminal-backend.ts +211 -0
  112. package/extension/src/terminal-manager.ts +395 -0
  113. package/extension/src/topic-registry.ts +70 -0
  114. package/extension/src/topic-utils.ts +46 -0
  115. package/extension/src/transport.ts +45 -0
  116. package/extension/src/uninstall-cleanup.ts +232 -0
  117. package/extension/src/wave-registry.ts +314 -0
  118. package/extension/src/websocket-transport.ts +153 -0
  119. package/extension/tsconfig.json +23 -0
  120. package/lib/capabilities.js +145 -0
  121. package/lib/dry-run.js +43 -0
  122. package/lib/install.js +1018 -0
  123. package/lib/mcp-setup.js +92 -0
  124. package/lib/platform.js +240 -0
  125. package/lib/preflight.js +152 -0
  126. package/lib/shell-hook.js +343 -0
  127. package/lib/uninstall.js +162 -0
  128. package/lib/verify.js +166 -0
  129. package/mcp_server.js +3529 -0
  130. package/package.json +48 -0
  131. package/rules/claws-default-behavior.md +72 -0
  132. package/scripts/_helpers/atomic-file.mjs +137 -0
  133. package/scripts/_helpers/fix-repair.js +64 -0
  134. package/scripts/_helpers/json-safe.mjs +218 -0
  135. package/scripts/bump-version.sh +84 -0
  136. package/scripts/codegen/gen-docs.mjs +61 -0
  137. package/scripts/codegen/gen-json-schema.mjs +62 -0
  138. package/scripts/codegen/gen-mcp-tools.mjs +358 -0
  139. package/scripts/codegen/gen-types.mjs +172 -0
  140. package/scripts/codegen/index.mjs +42 -0
  141. package/scripts/dev-hooks/check-extension-dirs.js +77 -0
  142. package/scripts/dev-hooks/check-open-claws-terminals.js +70 -0
  143. package/scripts/dev-hooks/check-stale-main.js +55 -0
  144. package/scripts/dev-hooks/check-tag-pushed.js +51 -0
  145. package/scripts/dev-hooks/check-tag-vs-main.js +56 -0
  146. package/scripts/dev-vsix-install.sh +60 -0
  147. package/scripts/fix.sh +702 -0
  148. package/scripts/gen-client-types.mjs +81 -0
  149. package/scripts/git-hooks/pre-commit +31 -0
  150. package/scripts/hooks/lifecycle-state.js +61 -0
  151. package/scripts/hooks/package.json +4 -0
  152. package/scripts/hooks/post-tool-use-claws.js +292 -0
  153. package/scripts/hooks/pre-bash-no-verify-block.js +72 -0
  154. package/scripts/hooks/pre-tool-use-claws.js +206 -0
  155. package/scripts/hooks/session-start-claws.js +97 -0
  156. package/scripts/hooks/stop-claws.js +88 -0
  157. package/scripts/inject-claude-md.js +205 -0
  158. package/scripts/inject-dev-hooks.js +96 -0
  159. package/scripts/inject-global-claude-md.js +140 -0
  160. package/scripts/inject-settings-hooks.js +370 -0
  161. package/scripts/install.ps1 +146 -0
  162. package/scripts/install.sh +1729 -0
  163. package/scripts/monitor-arm-watch.js +155 -0
  164. package/scripts/rebuild-node-pty.sh +245 -0
  165. package/scripts/report.sh +232 -0
  166. package/scripts/shell-hook.fish +164 -0
  167. package/scripts/shell-hook.ps1 +33 -0
  168. package/scripts/shell-hook.sh +232 -0
  169. package/scripts/stream-events.js +399 -0
  170. package/scripts/terminal-wrapper.sh +36 -0
  171. package/scripts/test-enforcement.sh +132 -0
  172. package/scripts/test-install.sh +174 -0
  173. package/scripts/test-installer-parity.sh +135 -0
  174. package/scripts/test-template-enforcement.sh +76 -0
  175. package/scripts/uninstall.sh +143 -0
  176. package/scripts/update.sh +337 -0
  177. package/scripts/verify-release.sh +323 -0
  178. package/scripts/verify-wrapped.sh +194 -0
  179. package/templates/CLAUDE.global.md +135 -0
  180. package/templates/CLAUDE.project.md +37 -0
@@ -0,0 +1,197 @@
1
+ # Claws Protocol Specification v1
2
+
3
+ ## Transport
4
+
5
+ - **Unix socket** (default): workspace-relative path, default `.claws/claws.sock`
6
+ - **WebSocket** (planned): `ws://host:port` with token auth
7
+
8
+ ## Framing
9
+
10
+ Newline-delimited JSON. Each message is one JSON object terminated by `\n`. Client sends requests; server sends responses. Every request carries an `id` (integer or string) which the server echoes in the response.
11
+
12
+ ## Requests
13
+
14
+ ```json
15
+ { "id": 1, "cmd": "list" }
16
+ ```
17
+
18
+ ## Responses
19
+
20
+ ```json
21
+ { "id": 1, "ok": true, "terminals": [...] }
22
+ ```
23
+
24
+ On error:
25
+
26
+ ```json
27
+ { "id": 1, "ok": false, "error": "description" }
28
+ ```
29
+
30
+ ---
31
+
32
+ ## Commands
33
+
34
+ ### `list`
35
+
36
+ Enumerate all open VS Code terminals.
37
+
38
+ **Request:** `{ "id": N, "cmd": "list" }`
39
+
40
+ **Response:**
41
+ ```json
42
+ {
43
+ "id": N,
44
+ "ok": true,
45
+ "terminals": [
46
+ {
47
+ "id": "1",
48
+ "name": "Terminal Name",
49
+ "pid": 12345,
50
+ "hasShellIntegration": true,
51
+ "active": false,
52
+ "logPath": "/absolute/path/to/pty.log" // null if unwrapped
53
+ }
54
+ ]
55
+ }
56
+ ```
57
+
58
+ ### `create`
59
+
60
+ Open a new terminal.
61
+
62
+ **Request:**
63
+ ```json
64
+ {
65
+ "id": N,
66
+ "cmd": "create",
67
+ "name": "my-terminal", // optional, default "claws"
68
+ "cwd": "/path/to/dir", // optional, default workspace root
69
+ "wrapped": true, // optional, default false — wrap in script(1) for pty logging
70
+ "show": true // optional, default true — show the terminal panel
71
+ }
72
+ ```
73
+
74
+ **Response:**
75
+ ```json
76
+ {
77
+ "id": N,
78
+ "ok": true,
79
+ "id": "5", // terminal id
80
+ "logPath": "/path/to/pty.log" // only present if wrapped=true
81
+ }
82
+ ```
83
+
84
+ ### `show`
85
+
86
+ Focus a terminal in the panel.
87
+
88
+ **Request:** `{ "id": N, "cmd": "show", "id": "5", "preserveFocus": true }`
89
+
90
+ **Response:** `{ "id": N, "ok": true }`
91
+
92
+ ### `send`
93
+
94
+ Send text into a terminal. Supports bracketed paste for multi-line text.
95
+
96
+ **Request:**
97
+ ```json
98
+ {
99
+ "id": N,
100
+ "cmd": "send",
101
+ "id": "5",
102
+ "text": "echo hello",
103
+ "newline": true // optional, default true — append Enter after text
104
+ }
105
+ ```
106
+
107
+ **Response:** `{ "id": N, "ok": true }`
108
+
109
+ ### `readLog`
110
+
111
+ Read a wrapped terminal's pty log. Only works for terminals created with `wrapped: true`.
112
+
113
+ **Request:**
114
+ ```json
115
+ {
116
+ "id": N,
117
+ "cmd": "readLog",
118
+ "id": "5",
119
+ "offset": 0, // optional — byte offset; default = tail of file
120
+ "limit": 524288, // optional — max bytes; default 512KB
121
+ "strip": true // optional — strip ANSI escape sequences; default true
122
+ }
123
+ ```
124
+
125
+ **Response:**
126
+ ```json
127
+ {
128
+ "id": N,
129
+ "ok": true,
130
+ "bytes": "cleaned text content...",
131
+ "offset": 0,
132
+ "nextOffset": 1234,
133
+ "totalSize": 5678,
134
+ "truncated": false,
135
+ "logPath": "/absolute/path/to/pty.log"
136
+ }
137
+ ```
138
+
139
+ ### `poll`
140
+
141
+ Drain shell-integration command-completion events since a cursor.
142
+
143
+ **Request:** `{ "id": N, "cmd": "poll", "since": 0 }`
144
+
145
+ **Response:**
146
+ ```json
147
+ {
148
+ "id": N,
149
+ "ok": true,
150
+ "events": [
151
+ {
152
+ "seq": 1,
153
+ "terminalId": "3",
154
+ "terminalName": "worker",
155
+ "commandLine": "echo hello",
156
+ "output": "hello\n",
157
+ "exitCode": 0,
158
+ "startedAt": 1713168000000,
159
+ "endedAt": 1713168001000
160
+ }
161
+ ],
162
+ "cursor": 1
163
+ }
164
+ ```
165
+
166
+ Note: `poll` relies on VS Code shell integration (`onDidEndTerminalShellExecution`), which is unreliable in wrapped terminals and TUI sessions. For reliable output capture, use `readLog` on wrapped terminals or file-based `exec`.
167
+
168
+ ### `close`
169
+
170
+ Dispose a terminal.
171
+
172
+ **Request:** `{ "id": N, "cmd": "close", "id": "5" }`
173
+
174
+ **Response:** `{ "id": N, "ok": true }`
175
+
176
+ ---
177
+
178
+ ## Error Codes
179
+
180
+ All errors return `{ "ok": false, "error": "message" }`. Common errors:
181
+
182
+ | Error | Meaning |
183
+ |---|---|
184
+ | `unknown terminal id X` | Terminal ID not found (closed or never existed) |
185
+ | `terminal X is not wrapped (no log path)` | `readLog` called on an unwrapped terminal |
186
+ | `bad json` | Request could not be parsed as JSON |
187
+ | `unknown cmd: X` | Unrecognized command name |
188
+
189
+ ---
190
+
191
+ ## Versioning
192
+
193
+ The protocol version is not currently exchanged in-band. Future versions will add a `handshake` command:
194
+
195
+ ```json
196
+ { "id": 0, "cmd": "handshake", "protocol": "claws/1", "client": "claws-python/0.1.0" }
197
+ ```
@@ -0,0 +1,25 @@
1
+ import { build, context } from 'esbuild';
2
+
3
+ const watch = process.argv.includes('--watch');
4
+ const production = process.argv.includes('--production');
5
+
6
+ const options = {
7
+ entryPoints: ['src/extension.ts'],
8
+ bundle: true,
9
+ format: 'cjs',
10
+ platform: 'node',
11
+ target: 'node18',
12
+ outfile: 'dist/extension.js',
13
+ external: ['vscode', 'node-pty'],
14
+ sourcemap: !production,
15
+ minify: production,
16
+ logLevel: 'info',
17
+ };
18
+
19
+ if (watch) {
20
+ const ctx = await context(options);
21
+ await ctx.watch();
22
+ console.log('[esbuild] watching…');
23
+ } else {
24
+ await build(options);
25
+ }
Binary file
@@ -0,0 +1,10 @@
1
+ {
2
+ "node_pty_version": "1.1.0",
3
+ "copied_at": "2026-05-17T11:54:03.099Z",
4
+ "platforms_included": [
5
+ "darwin-arm64",
6
+ "darwin-x64",
7
+ "win32-x64",
8
+ "win32-arm64"
9
+ ]
10
+ }
@@ -0,0 +1,69 @@
1
+ Copyright (c) 2012-2015, Christopher Jeffrey (https://github.com/chjj/)
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy
4
+ of this software and associated documentation files (the "Software"), to deal
5
+ in the Software without restriction, including without limitation the rights
6
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+ copies of the Software, and to permit persons to whom the Software is
8
+ furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in
11
+ all copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19
+ THE SOFTWARE.
20
+
21
+
22
+
23
+ The MIT License (MIT)
24
+
25
+ Copyright (c) 2016, Daniel Imms (http://www.growingwiththeweb.com)
26
+
27
+ Permission is hereby granted, free of charge, to any person obtaining a copy
28
+ of this software and associated documentation files (the "Software"), to deal
29
+ in the Software without restriction, including without limitation the rights
30
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
31
+ copies of the Software, and to permit persons to whom the Software is
32
+ furnished to do so, subject to the following conditions:
33
+
34
+ The above copyright notice and this permission notice shall be included in all
35
+ copies or substantial portions of the Software.
36
+
37
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
38
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
39
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
40
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
41
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
42
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
43
+ SOFTWARE.
44
+
45
+
46
+
47
+ MIT License
48
+
49
+ Copyright (c) 2018 - present Microsoft Corporation
50
+
51
+ All rights reserved.
52
+
53
+ Permission is hereby granted, free of charge, to any person obtaining a copy
54
+ of this software and associated documentation files (the "Software"), to deal
55
+ in the Software without restriction, including without limitation the rights
56
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
57
+ copies of the Software, and to permit persons to whom the Software is
58
+ furnished to do so, subject to the following conditions:
59
+
60
+ The above copyright notice and this permission notice shall be included in all
61
+ copies or substantial portions of the Software.
62
+
63
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
64
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
65
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
66
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
67
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
68
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
69
+ SOFTWARE.
@@ -0,0 +1,165 @@
1
+ # node-pty
2
+
3
+ [![Build Status](https://dev.azure.com/vscode/node-pty/_apis/build/status/Microsoft.node-pty?branchName=main)](https://dev.azure.com/vscode/node-pty/_build/latest?definitionId=11&branchName=main)
4
+
5
+ `forkpty(3)` bindings for node.js. This allows you to fork processes with pseudoterminal file descriptors. It returns a terminal object which allows reads and writes.
6
+
7
+ This is useful for:
8
+
9
+ - Writing a terminal emulator (eg. via [xterm.js](https://github.com/sourcelair/xterm.js)).
10
+ - Getting certain programs to *think* you're a terminal, such as when you need a program to send you control sequences.
11
+
12
+ `node-pty` supports Linux, macOS and Windows. Windows support is possible by utilizing the [Windows conpty API](https://blogs.msdn.microsoft.com/commandline/2018/08/02/windows-command-line-introducing-the-windows-pseudo-console-conpty/) on Windows 1809+ and the [winpty](https://github.com/rprichard/winpty) library in older version.
13
+
14
+ ## API
15
+
16
+ The full API for node-pty is contained within the [TypeScript declaration file](https://github.com/microsoft/node-pty/blob/main/typings/node-pty.d.ts), use the branch/tag picker in GitHub (`w`) to navigate to the correct version of the API.
17
+
18
+ ## Example Usage
19
+
20
+ ```js
21
+ import * as os from 'node:os';
22
+ import * as pty from 'node-pty';
23
+
24
+ const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
25
+
26
+ const ptyProcess = pty.spawn(shell, [], {
27
+ name: 'xterm-color',
28
+ cols: 80,
29
+ rows: 30,
30
+ cwd: process.env.HOME,
31
+ env: process.env
32
+ });
33
+
34
+ ptyProcess.onData((data) => {
35
+ process.stdout.write(data);
36
+ });
37
+
38
+ ptyProcess.write('ls\r');
39
+ ptyProcess.resize(100, 40);
40
+ ptyProcess.write('ls\r');
41
+ ```
42
+
43
+ ## Real-world Uses
44
+
45
+ `node-pty` powers many different terminal emulators, including:
46
+
47
+ - [Microsoft Visual Studio Code](https://code.visualstudio.com)
48
+ - [Hyper](https://hyper.is/)
49
+ - [Upterm](https://github.com/railsware/upterm)
50
+ - [Script Runner](https://github.com/ioquatix/script-runner) for Atom.
51
+ - [Theia](https://github.com/theia-ide/theia)
52
+ - [FreeMAN](https://github.com/matthew-matvei/freeman) file manager
53
+ - [terminus](https://atom.io/packages/terminus) - An Atom plugin for providing terminals inside your Atom workspace.
54
+ - [x-terminal](https://atom.io/packages/x-terminal) - Also an Atom plugin that provides terminals inside your Atom workspace.
55
+ - [Termination](https://atom.io/packages/termination) - Also an Atom plugin that provides terminals inside your Atom workspace.
56
+ - [atom-xterm](https://atom.io/packages/atom-xterm) - Also an Atom plugin that provides terminals inside your Atom workspace.
57
+ - [electerm](https://github.com/electerm/electerm) Terminal/SSH/SFTP client(Linux, macOS, Windows).
58
+ - [Extraterm](http://extraterm.org/)
59
+ - [Wetty](https://github.com/krishnasrinivas/wetty) Browser based Terminal over HTTP and HTTPS
60
+ - [nomad](https://github.com/lukebarnard1/nomad-term)
61
+ - [DockerStacks](https://github.com/sfx101/docker-stacks) Local LAMP/LEMP stack using Docker
62
+ - [TeleType](https://github.com/akshaykmr/TeleType): cli tool that allows you to share your terminal online conveniently. Show off mad cli-fu, help a colleague, teach, or troubleshoot.
63
+ - [mesos-term](https://github.com/criteo/mesos-term): A web terminal for Apache Mesos. It allows to execute commands within containers.
64
+ - [Commas](https://github.com/CyanSalt/commas): A hackable terminal and command runner.
65
+ - [ENiGMA½ BBS Software](https://github.com/NuSkooler/enigma-bbs): A modern BBS software with a nostalgic flair!
66
+ - [Tinkerun](https://github.com/tinkerun/tinkerun): A new way of running Tinker.
67
+ - [Tess](https://tessapp.dev): Hackable, simple and rapid terminal for the new era of technology 👍
68
+ - [NxShell](https://nxshell.github.io/): An easy to use new terminal for Windows/Linux/MacOS platform.
69
+ - [OpenSumi](https://github.com/opensumi/core): A framework helps you quickly build Cloud or Desktop IDE products.
70
+ - [Enjoy Git](https://github.com/huangcs427/enjoy-git-release): A modern Git client featuring an intuitive user interface, built with Electron, Vue 3, and TypeScript.
71
+
72
+ Do you use node-pty in your application as well? Please open a [Pull Request](https://github.com/Tyriar/node-pty/pulls) to include it here. We would love to have it in our list.
73
+
74
+ ## Building
75
+
76
+ ```bash
77
+ # Install dependencies and build C++
78
+ npm install
79
+ # Compile TypeScript -> JavaScript
80
+ npm run build
81
+ ```
82
+
83
+ ## Dependencies
84
+
85
+ Node.JS 16 or Electron 19 is required to use `node-pty`. What version of node is supported is currently mostly bound to [whatever version Visual Studio Code is using](https://github.com/microsoft/node-pty/issues/557#issuecomment-1332193541).
86
+
87
+ ### Linux (apt)
88
+
89
+ ```sh
90
+ sudo apt install -y make python build-essential
91
+ ```
92
+
93
+ ### macOS
94
+
95
+ Xcode is needed to compile the sources, this can be installed from the App Store.
96
+
97
+ ### Windows
98
+
99
+ `npm install` requires some tools to be present in the system like Python and C++ compiler. Windows users can easily install them by running the following command in PowerShell as administrator. For more information see https://github.com/felixrieseberg/windows-build-tools:
100
+
101
+ ```sh
102
+ npm install --global --production windows-build-tools
103
+ ```
104
+
105
+ The following are also needed:
106
+
107
+ - [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk) - only the "Desktop C++ Apps" components are needed to be installed
108
+ - Spectre-mitigated libraries - In order to avoid the build error "MSB8040: Spectre-mitigated libraries are required for this project", open the Visual Studio Installer, press the Modify button, navigate to the "Individual components" tab, search "Spectre", and install an option like "MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)" (the exact option to install will depend on your version of Visual Studio as well as your operating system architecture)
109
+
110
+ ## Debugging
111
+
112
+ [The wiki](https://github.com/Microsoft/node-pty/wiki/Debugging) contains instructions for debugging node-pty.
113
+
114
+ ## Security
115
+
116
+ All processes launched from node-pty will launch at the same permission level of the parent process. Take care particularly when using node-pty inside a server that's accessible on the internet. We recommend launching the pty inside a container to protect your host machine.
117
+
118
+ ## Thread Safety
119
+
120
+ Note that node-pty is not thread safe so running it across multiple worker threads in node.js could cause issues.
121
+
122
+ ## Flow Control
123
+
124
+ Automatic flow control can be enabled by either providing `handleFlowControl = true` in the constructor options or setting it later on:
125
+
126
+ ```js
127
+ const PAUSE = '\x13'; // XOFF
128
+ const RESUME = '\x11'; // XON
129
+
130
+ const ptyProcess = pty.spawn(shell, [], {handleFlowControl: true});
131
+
132
+ // flow control in action
133
+ ptyProcess.write(PAUSE); // pty will block and pause the child program
134
+ ...
135
+ ptyProcess.write(RESUME); // pty will enter flow mode and resume the child program
136
+
137
+ // temporarily disable/re-enable flow control
138
+ ptyProcess.handleFlowControl = false;
139
+ ...
140
+ ptyProcess.handleFlowControl = true;
141
+ ```
142
+
143
+ By default `PAUSE` and `RESUME` are XON/XOFF control codes (as shown above). To avoid conflicts in environments that use these control codes for different purposes the messages can be customized as `flowControlPause: string` and `flowControlResume: string` in the constructor options. `PAUSE` and `RESUME` are not passed to the underlying pseudoterminal if flow control is enabled.
144
+
145
+ ## Troubleshooting
146
+
147
+ ### Powershell gives error 8009001d
148
+
149
+ > Internal Windows PowerShell error. Loading managed Windows PowerShell failed with error 8009001d.
150
+
151
+ This happens when PowerShell is launched with no `SystemRoot` environment variable present.
152
+
153
+ ### ConnectNamedPipe failed: Windows error 232
154
+
155
+ This error can occur due to anti-virus software intercepting winpty from creating a pty. To workaround this you can exclude this file from your anti-virus scanning `node-pty\build\Release\winpty-agent.exe`
156
+
157
+ ## pty.js
158
+
159
+ This project is forked from [chjj/pty.js](https://github.com/chjj/pty.js) with the primary goals being to provide better support for later Node.js versions and Windows.
160
+
161
+ ## License
162
+
163
+ Copyright (c) 2012-2015, Christopher Jeffrey (MIT License).<br>
164
+ Copyright (c) 2016, Daniel Imms (MIT License).<br>
165
+ Copyright (c) 2018, Microsoft Corporation (MIT License).
@@ -0,0 +1,16 @@
1
+ "use strict";
2
+ /**
3
+ * Copyright (c) 2019, Microsoft Corporation (MIT License).
4
+ *
5
+ * This module fetches the console process list for a particular PID. It must be
6
+ * called from a different process (child_process.fork) as there can only be a
7
+ * single console attached to a process.
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
10
+ var utils_1 = require("./utils");
11
+ var getConsoleProcessList = utils_1.loadNativeModule('conpty_console_list').module.getConsoleProcessList;
12
+ var shellPid = parseInt(process.argv[2], 10);
13
+ var consoleProcessList = getConsoleProcessList(shellPid);
14
+ process.send({ consoleProcessList: consoleProcessList });
15
+ process.exit(0);
16
+ //# sourceMappingURL=conpty_console_list_agent.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"conpty_console_list_agent.js","sourceRoot":"","sources":["../src/conpty_console_list_agent.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAEH,iCAA2C;AAE3C,IAAM,qBAAqB,GAAG,wBAAgB,CAAC,qBAAqB,CAAC,CAAC,MAAM,CAAC,qBAAqB,CAAC;AACnG,IAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/C,IAAM,kBAAkB,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;AAC3D,OAAO,CAAC,IAAK,CAAC,EAAE,kBAAkB,oBAAA,EAAE,CAAC,CAAC;AACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}
@@ -0,0 +1,47 @@
1
+ "use strict";
2
+ /**
3
+ * Copyright (c) 2019, Microsoft Corporation (MIT License).
4
+ */
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.EventEmitter2 = void 0;
7
+ var EventEmitter2 = /** @class */ (function () {
8
+ function EventEmitter2() {
9
+ this._listeners = [];
10
+ }
11
+ Object.defineProperty(EventEmitter2.prototype, "event", {
12
+ get: function () {
13
+ var _this = this;
14
+ if (!this._event) {
15
+ this._event = function (listener) {
16
+ _this._listeners.push(listener);
17
+ var disposable = {
18
+ dispose: function () {
19
+ for (var i = 0; i < _this._listeners.length; i++) {
20
+ if (_this._listeners[i] === listener) {
21
+ _this._listeners.splice(i, 1);
22
+ return;
23
+ }
24
+ }
25
+ }
26
+ };
27
+ return disposable;
28
+ };
29
+ }
30
+ return this._event;
31
+ },
32
+ enumerable: false,
33
+ configurable: true
34
+ });
35
+ EventEmitter2.prototype.fire = function (data) {
36
+ var queue = [];
37
+ for (var i = 0; i < this._listeners.length; i++) {
38
+ queue.push(this._listeners[i]);
39
+ }
40
+ for (var i = 0; i < queue.length; i++) {
41
+ queue[i].call(undefined, data);
42
+ }
43
+ };
44
+ return EventEmitter2;
45
+ }());
46
+ exports.EventEmitter2 = EventEmitter2;
47
+ //# sourceMappingURL=eventEmitter2.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"eventEmitter2.js","sourceRoot":"","sources":["../src/eventEmitter2.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAYH;IAAA;QACU,eAAU,GAAmB,EAAE,CAAC;IAgC1C,CAAC;IA7BC,sBAAW,gCAAK;aAAhB;YAAA,iBAkBC;YAjBC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;gBAChB,IAAI,CAAC,MAAM,GAAG,UAAC,QAAuB;oBACpC,KAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBAC/B,IAAM,UAAU,GAAG;wBACjB,OAAO,EAAE;4BACP,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;gCAC/C,IAAI,KAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE;oCACnC,KAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oCAC7B,OAAO;iCACR;6BACF;wBACH,CAAC;qBACF,CAAC;oBACF,OAAO,UAAU,CAAC;gBACpB,CAAC,CAAC;aACH;YACD,OAAO,IAAI,CAAC,MAAM,CAAC;QACrB,CAAC;;;OAAA;IAEM,4BAAI,GAAX,UAAY,IAAO;QACjB,IAAM,KAAK,GAAmB,EAAE,CAAC;QACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;YAC/C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;SAChC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;YACrC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;SAChC;IACH,CAAC;IACH,oBAAC;AAAD,CAAC,AAjCD,IAiCC;AAjCY,sCAAa"}
@@ -0,0 +1,52 @@
1
+ "use strict";
2
+ /**
3
+ * Copyright (c) 2012-2015, Christopher Jeffrey, Peter Sunde (MIT License)
4
+ * Copyright (c) 2016, Daniel Imms (MIT License).
5
+ * Copyright (c) 2018, Microsoft Corporation (MIT License).
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.native = exports.open = exports.createTerminal = exports.fork = exports.spawn = void 0;
9
+ var utils_1 = require("./utils");
10
+ var terminalCtor;
11
+ if (process.platform === 'win32') {
12
+ terminalCtor = require('./windowsTerminal').WindowsTerminal;
13
+ }
14
+ else {
15
+ terminalCtor = require('./unixTerminal').UnixTerminal;
16
+ }
17
+ /**
18
+ * Forks a process as a pseudoterminal.
19
+ * @param file The file to launch.
20
+ * @param args The file's arguments as argv (string[]) or in a pre-escaped
21
+ * CommandLine format (string). Note that the CommandLine option is only
22
+ * available on Windows and is expected to be escaped properly.
23
+ * @param options The options of the terminal.
24
+ * @throws When the file passed to spawn with does not exists.
25
+ * @see CommandLineToArgvW https://msdn.microsoft.com/en-us/library/windows/desktop/bb776391(v=vs.85).aspx
26
+ * @see Parsing C++ Comamnd-Line Arguments https://msdn.microsoft.com/en-us/library/17w5ykft.aspx
27
+ * @see GetCommandLine https://msdn.microsoft.com/en-us/library/windows/desktop/ms683156.aspx
28
+ */
29
+ function spawn(file, args, opt) {
30
+ return new terminalCtor(file, args, opt);
31
+ }
32
+ exports.spawn = spawn;
33
+ /** @deprecated */
34
+ function fork(file, args, opt) {
35
+ return new terminalCtor(file, args, opt);
36
+ }
37
+ exports.fork = fork;
38
+ /** @deprecated */
39
+ function createTerminal(file, args, opt) {
40
+ return new terminalCtor(file, args, opt);
41
+ }
42
+ exports.createTerminal = createTerminal;
43
+ function open(options) {
44
+ return terminalCtor.open(options);
45
+ }
46
+ exports.open = open;
47
+ /**
48
+ * Expose the native API when not Windows, note that this is not public API and
49
+ * could be removed at any time.
50
+ */
51
+ exports.native = (process.platform !== 'win32' ? utils_1.loadNativeModule('pty').module : null);
52
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIH,iCAA2C;AAE3C,IAAI,YAAiB,CAAC;AACtB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE;IAChC,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,eAAe,CAAC;CAC7D;KAAM;IACL,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,YAAY,CAAC;CACvD;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,KAAK,CAAC,IAAa,EAAE,IAAwB,EAAE,GAA8C;IAC3G,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC;AAFD,sBAEC;AAED,kBAAkB;AAClB,SAAgB,IAAI,CAAC,IAAa,EAAE,IAAwB,EAAE,GAA8C;IAC1G,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC;AAFD,oBAEC;AAED,kBAAkB;AAClB,SAAgB,cAAc,CAAC,IAAa,EAAE,IAAwB,EAAE,GAA8C;IACpH,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC;AAFD,wCAEC;AAED,SAAgB,IAAI,CAAC,OAAwB;IAC3C,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAFD,oBAEC;AAED;;;GAGG;AACU,QAAA,MAAM,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,wBAAgB,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC"}
@@ -0,0 +1,7 @@
1
+ "use strict";
2
+ /**
3
+ * Copyright (c) 2016, Daniel Imms (MIT License).
4
+ * Copyright (c) 2018, Microsoft Corporation (MIT License).
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ //# sourceMappingURL=interfaces.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":";AAAA;;;GAGG"}
@@ -0,0 +1,11 @@
1
+ "use strict";
2
+ /**
3
+ * Copyright (c) 2020, Microsoft Corporation (MIT License).
4
+ */
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.getWorkerPipeName = void 0;
7
+ function getWorkerPipeName(conoutPipeName) {
8
+ return conoutPipeName + "-worker";
9
+ }
10
+ exports.getWorkerPipeName = getWorkerPipeName;
11
+ //# sourceMappingURL=conout.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"conout.js","sourceRoot":"","sources":["../../src/shared/conout.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAUH,SAAgB,iBAAiB,CAAC,cAAsB;IACtD,OAAU,cAAc,YAAS,CAAC;AACpC,CAAC;AAFD,8CAEC"}