@noldova/terminal.window 0.0.0-stage → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +38 -2
- package/package.json +69 -4
- package/src/api/index.d.ts +1850 -0
- package/src/api/index.js +40 -0
- package/src/api/index.js.map +1 -0
- package/src/app/components/terminal-pane/terminal-pane.component.js +451 -0
- package/src/app/components/terminal-pane/terminal-pane.component.js.map +1 -0
- package/src/app/components/terminal-panel/terminal-panel.component.js +108 -0
- package/src/app/components/terminal-panel/terminal-panel.component.js.map +1 -0
- package/src/app/components/terminal-session/terminal-session.component.js +115 -0
- package/src/app/components/terminal-session/terminal-session.component.js.map +1 -0
- package/src/app/enums/command-token-kind.js +19 -0
- package/src/app/enums/command-token-kind.js.map +1 -0
- package/src/app/enums/terminal-ended-by.js +13 -0
- package/src/app/enums/terminal-ended-by.js.map +1 -0
- package/src/app/exceptions/embedded-rows-refused.exception.js +22 -0
- package/src/app/exceptions/embedded-rows-refused.exception.js.map +1 -0
- package/src/app/exceptions/launch-argument-refused.exception.js +20 -0
- package/src/app/exceptions/launch-argument-refused.exception.js.map +1 -0
- package/src/app/exceptions/launch-folder-missing.exception.js +19 -0
- package/src/app/exceptions/launch-folder-missing.exception.js.map +1 -0
- package/src/app/exceptions/launch-part-inactive.exception.js +17 -0
- package/src/app/exceptions/launch-part-inactive.exception.js.map +1 -0
- package/src/app/exceptions/launch-rows-refused.exception.js +19 -0
- package/src/app/exceptions/launch-rows-refused.exception.js.map +1 -0
- package/src/app/exceptions/launch-rows-without-tab.exception.js +17 -0
- package/src/app/exceptions/launch-rows-without-tab.exception.js.map +1 -0
- package/src/app/exceptions/launch-title-refused.exception.js +19 -0
- package/src/app/exceptions/launch-title-refused.exception.js.map +1 -0
- package/src/app/exceptions/owners-provided.exception.js +16 -0
- package/src/app/exceptions/owners-provided.exception.js.map +1 -0
- package/src/app/exceptions/run-argument-refused.exception.js +20 -0
- package/src/app/exceptions/run-argument-refused.exception.js.map +1 -0
- package/src/app/exceptions/run-lines-refused.exception.js +20 -0
- package/src/app/exceptions/run-lines-refused.exception.js.map +1 -0
- package/src/app/exceptions/run-part-inactive.exception.js +17 -0
- package/src/app/exceptions/run-part-inactive.exception.js.map +1 -0
- package/src/app/exceptions/run-shell-kinds-missing.exception.js +19 -0
- package/src/app/exceptions/run-shell-kinds-missing.exception.js.map +1 -0
- package/src/app/exceptions/start-folder-provided.exception.js +16 -0
- package/src/app/exceptions/start-folder-provided.exception.js.map +1 -0
- package/src/app/exceptions/terminal-launch-refused.exception.js +15 -0
- package/src/app/exceptions/terminal-launch-refused.exception.js.map +1 -0
- package/src/app/exceptions/terminal-not-active.exception.js +16 -0
- package/src/app/exceptions/terminal-not-active.exception.js.map +1 -0
- package/src/app/exceptions/terminal-run-not-found.exception.js +20 -0
- package/src/app/exceptions/terminal-run-not-found.exception.js.map +1 -0
- package/src/app/exceptions/terminal-run-not-typed.exception.js +20 -0
- package/src/app/exceptions/terminal-run-not-typed.exception.js.map +1 -0
- package/src/app/exceptions/terminal-run-refused.exception.js +15 -0
- package/src/app/exceptions/terminal-run-refused.exception.js.map +1 -0
- package/src/app/exceptions/terminal-window.exception.js +15 -0
- package/src/app/exceptions/terminal-window.exception.js.map +1 -0
- package/src/app/interfaces/i-sized-pane.js +8 -0
- package/src/app/interfaces/i-sized-pane.js.map +1 -0
- package/src/app/interfaces/i-start-folder-provider.js +8 -0
- package/src/app/interfaces/i-start-folder-provider.js.map +1 -0
- package/src/app/interfaces/i-terminal-focus-target.js +8 -0
- package/src/app/interfaces/i-terminal-focus-target.js.map +1 -0
- package/src/app/interfaces/i-terminal-restart-target.js +8 -0
- package/src/app/interfaces/i-terminal-restart-target.js.map +1 -0
- package/src/app/interfaces/i-terminal-sink.js +8 -0
- package/src/app/interfaces/i-terminal-sink.js.map +1 -0
- package/src/app/models/command-color-run.js +23 -0
- package/src/app/models/command-color-run.js.map +1 -0
- package/src/app/models/command-color-span.js +39 -0
- package/src/app/models/command-color-span.js.map +1 -0
- package/src/app/models/command-colors.js +17 -0
- package/src/app/models/command-colors.js.map +1 -0
- package/src/app/models/command-continuation.js +16 -0
- package/src/app/models/command-continuation.js.map +1 -0
- package/src/app/models/command-token.js +18 -0
- package/src/app/models/command-token.js.map +1 -0
- package/src/app/models/ended-pane.js +20 -0
- package/src/app/models/ended-pane.js.map +1 -0
- package/src/app/models/launched-terminal.js +31 -0
- package/src/app/models/launched-terminal.js.map +1 -0
- package/src/app/models/stored-lines-window.js +66 -0
- package/src/app/models/stored-lines-window.js.map +1 -0
- package/src/app/models/terminal-appearance.js +20 -0
- package/src/app/models/terminal-appearance.js.map +1 -0
- package/src/app/models/terminal-dock-growth.js +15 -0
- package/src/app/models/terminal-dock-growth.js.map +1 -0
- package/src/app/models/terminal-end.js +16 -0
- package/src/app/models/terminal-end.js.map +1 -0
- package/src/app/models/terminal-launch.js +28 -0
- package/src/app/models/terminal-launch.js.map +1 -0
- package/src/app/models/terminal-new-arguments.js +46 -0
- package/src/app/models/terminal-new-arguments.js.map +1 -0
- package/src/app/models/terminal-run-end.js +16 -0
- package/src/app/models/terminal-run-end.js.map +1 -0
- package/src/app/models/terminal-run-target.js +17 -0
- package/src/app/models/terminal-run-target.js.map +1 -0
- package/src/app/models/terminal-run.js +20 -0
- package/src/app/models/terminal-run.js.map +1 -0
- package/src/app/models/terminal-tab-key.js +30 -0
- package/src/app/models/terminal-tab-key.js.map +1 -0
- package/src/app/models/terminal-tab-label.js +18 -0
- package/src/app/models/terminal-tab-label.js.map +1 -0
- package/src/app/services/command-coloring.js +259 -0
- package/src/app/services/command-coloring.js.map +1 -0
- package/src/app/services/command-line-tokens.js +267 -0
- package/src/app/services/command-line-tokens.js.map +1 -0
- package/src/app/services/command-suggestion.js +229 -0
- package/src/app/services/command-suggestion.js.map +1 -0
- package/src/app/services/completion-list.js +224 -0
- package/src/app/services/completion-list.js.map +1 -0
- package/src/app/services/embedded-terminal.js +99 -0
- package/src/app/services/embedded-terminal.js.map +1 -0
- package/src/app/services/key-router.js +33 -0
- package/src/app/services/key-router.js.map +1 -0
- package/src/app/services/link-policy.js +17 -0
- package/src/app/services/link-policy.js.map +1 -0
- package/src/app/services/pane-fitter.js +64 -0
- package/src/app/services/pane-fitter.js.map +1 -0
- package/src/app/services/pane-scrollbar.js +55 -0
- package/src/app/services/pane-scrollbar.js.map +1 -0
- package/src/app/services/paste-filter.js +14 -0
- package/src/app/services/paste-filter.js.map +1 -0
- package/src/app/services/renderer-switch.js +45 -0
- package/src/app/services/renderer-switch.js.map +1 -0
- package/src/app/services/session-sizing.js +61 -0
- package/src/app/services/session-sizing.js.map +1 -0
- package/src/app/services/terminal-connection.js +244 -0
- package/src/app/services/terminal-connection.js.map +1 -0
- package/src/app/services/terminal-dock-growths.js +27 -0
- package/src/app/services/terminal-dock-growths.js.map +1 -0
- package/src/app/services/terminal-focus.js +58 -0
- package/src/app/services/terminal-focus.js.map +1 -0
- package/src/app/services/terminal-launch-ends.js +23 -0
- package/src/app/services/terminal-launch-ends.js.map +1 -0
- package/src/app/services/terminal-launcher.js +143 -0
- package/src/app/services/terminal-launcher.js.map +1 -0
- package/src/app/services/terminal-line-encoder.js +45 -0
- package/src/app/services/terminal-line-encoder.js.map +1 -0
- package/src/app/services/terminal-owners.js +219 -0
- package/src/app/services/terminal-owners.js.map +1 -0
- package/src/app/services/terminal-pager.js +244 -0
- package/src/app/services/terminal-pager.js.map +1 -0
- package/src/app/services/terminal-part.js +21 -0
- package/src/app/services/terminal-part.js.map +1 -0
- package/src/app/services/terminal-restart-targets.js +28 -0
- package/src/app/services/terminal-restart-targets.js.map +1 -0
- package/src/app/services/terminal-run-ends.js +39 -0
- package/src/app/services/terminal-run-ends.js.map +1 -0
- package/src/app/services/terminal-run-notices.js +21 -0
- package/src/app/services/terminal-run-notices.js.map +1 -0
- package/src/app/services/terminal-runtime-client.js +231 -0
- package/src/app/services/terminal-runtime-client.js.map +1 -0
- package/src/app/services/terminal-shell-menu.js +48 -0
- package/src/app/services/terminal-shell-menu.js.map +1 -0
- package/src/app/services/terminal-start-folder.js +39 -0
- package/src/app/services/terminal-start-folder.js.map +1 -0
- package/src/app/services/terminal-theme-reader.js +93 -0
- package/src/app/services/terminal-theme-reader.js.map +1 -0
- package/src/app/services/terminal-window-part.js +164 -0
- package/src/app/services/terminal-window-part.js.map +1 -0
- package/src/app/services/url-link-provider.js +73 -0
- package/src/app/services/url-link-provider.js.map +1 -0
- package/src/app/types/ansi-color.js +8 -0
- package/src/app/types/ansi-color.js.map +1 -0
- package/src/app/types/ansi-key.js +8 -0
- package/src/app/types/ansi-key.js.map +1 -0
- package/src/resources.js +471 -0
- package/src/resources.js.map +1 -0
|
@@ -0,0 +1,1850 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Copyright (c) Noldova.
|
|
4
|
+
*
|
|
5
|
+
* This source code is licensed under the license found in the
|
|
6
|
+
* LICENSE file in the root directory of this source tree.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import type { EnvironmentInjector, Signal } from "@angular/core";
|
|
10
|
+
import type { IWindowPart, IWindowPartContext } from "@noldova/desktop.window";
|
|
11
|
+
import type { Exception, ExceptionOptions } from "@noldova/context.exceptions";
|
|
12
|
+
import type { TerminalRunBusy, TerminalRunOutcome, TerminalRunOutput, TerminalShellKind } from "@noldova/terminal.protocol";
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* The kinds of shell, re-exported from `@noldova/terminal.protocol`: `PowerShell`, `CommandPrompt`, `Bash`, `Zsh`, `Fish`, `Wsl` and
|
|
16
|
+
* `Other`. {@link TerminalOwners.runAsync} takes a list of them.
|
|
17
|
+
*/
|
|
18
|
+
export { TerminalShellKind } from "@noldova/terminal.protocol";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* What became of a run's commands, re-exported from `@noldova/terminal.protocol`: `Typed`, or why they weren't typed, `Input`, `Tab`,
|
|
22
|
+
* `Ended`, `Busy`, or `NoShell` when no shell of the run's kinds is installed, so nothing opened. {@link TerminalRunNotTypedException}
|
|
23
|
+
* carries the reasons but `NoShell`, for which {@link RunShellKindsMissingException} is thrown instead.
|
|
24
|
+
*/
|
|
25
|
+
export { TerminalRunOutcome } from "@noldova/terminal.protocol";
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* What a run into a given terminal does while that terminal's shell is busy, re-exported from `@noldova/terminal.protocol`: `Refuse` or
|
|
29
|
+
* `Interrupt`. A {@link TerminalRunTarget} carries it.
|
|
30
|
+
*/
|
|
31
|
+
export { TerminalRunBusy } from "@noldova/terminal.protocol";
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* A run's output with its colors, its last lines and how many earlier ones were cut, re-exported from `@noldova/terminal.protocol`.
|
|
35
|
+
* {@link TerminalOwners.readRunOutputAsync} gives it.
|
|
36
|
+
*/
|
|
37
|
+
export { TerminalRunOutput } from "@noldova/terminal.protocol";
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* A line of a run's output: its text, whether it continues the line before, and its runs of color and style, re-exported from
|
|
41
|
+
* `@noldova/terminal.protocol`.
|
|
42
|
+
*/
|
|
43
|
+
export { TerminalLine } from "@noldova/terminal.protocol";
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* A run of a line's text in one color and style, re-exported from `@noldova/terminal.protocol`; its colors are read with
|
|
47
|
+
* {@link TerminalOwners.defaultColor} and {@link TerminalOwners.rgbColor}.
|
|
48
|
+
*/
|
|
49
|
+
export { TerminalTextRun } from "@noldova/terminal.protocol";
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* The style flags of a line's text run, whose sum is the run's style, re-exported from `@noldova/terminal.protocol`: `Bold`, `Dim`,
|
|
53
|
+
* `Italic`, `Underline`, `Blink`, `Inverse`, `Invisible`, `Strikethrough` and `Overline`.
|
|
54
|
+
*/
|
|
55
|
+
export { TerminalTextStyle } from "@noldova/terminal.protocol";
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The terminal module's window part, which Noldova Desktop's window activates.
|
|
59
|
+
*
|
|
60
|
+
* @remarks
|
|
61
|
+
* Activation registers the bottom panel `terminal.panel`, the bottom view `terminal.session` with a tab for each instance, a session's id, and
|
|
62
|
+
* the command `terminal.new`, which opens a terminal in a new tab: in the `folder` and with the `shellId` its arguments give, else in the app's
|
|
63
|
+
* {@link TerminalStartFolder} with the default shell, in the `tabGroup` it gives, else where Noldova Desktop chooses, for the `owner` it gives, else
|
|
64
|
+
* without one, or with `takesNewOwner: true` for the app's new owner ({@link TerminalOwners}); its key is Ctrl+Shift+\`, and the View menu has it. The command `terminal.toggle`, Toggle Terminal, on Ctrl+\` (Control on macOS), shows the terminal used last and gives it the
|
|
65
|
+
* focus, else opens one, and from a terminal gives the focus back to where it was and hides the terminal's dock. The default shell is the
|
|
66
|
+
* `terminal.defaultShell` setting's while the runtime finds it, else the runtime's. Every tab row that holds a terminal tab shows + and a menu of
|
|
67
|
+
* the shells, which open a terminal in that group: the default shell's row runs `terminal.new` and shows its key, and the others run
|
|
68
|
+
* `terminal.newWithShell`, which has no key and stays out of command search; + takes the app's new owner, and the rows open a terminal without
|
|
69
|
+
* one. The tab menu of a terminal tab, but an agent's, and of the panel offers Restart, the command
|
|
70
|
+
* `terminal.restartShell`, which starts its shell again in place. A terminal tab is renamed in place, as Noldova Desktop edits a renamable tab's
|
|
71
|
+
* title, by a double-click, F2 or its own tab-menu Rename: Enter keeps the name, for its tabs in every window and across runs, Escape
|
|
72
|
+
* cancels, and an empty title takes it away. The panel shows a terminal of its own, which no tab shows: the one the runtime lists as
|
|
73
|
+
* the panel's, or the default shell it opens the first time it shows. xterm and the pane load with the first panel or tab that shows.
|
|
74
|
+
* Closing a tab ends its terminal, unless an agent's session owns it; activation reopens a tab for each of the person's terminals the runtime
|
|
75
|
+
* still has, but the panel's, so a reload keeps them. Before that it has the runtime open again, once a run, the terminals the last run left
|
|
76
|
+
* open, so a new start of the app keeps them too.
|
|
77
|
+
* After the runtime starts again, the part has it open the last run's terminals again first, and every pane attaches again from a snapshot;
|
|
78
|
+
* a pane whose terminal is gone keeps its last screen with a Restart action.
|
|
79
|
+
* @example
|
|
80
|
+
* ```ts
|
|
81
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
82
|
+
* import { windowPart } from "@noldova/terminal/window";
|
|
83
|
+
*
|
|
84
|
+
* export async function activateTerminalAsync(context: IWindowPartContext): Promise<void> {
|
|
85
|
+
* await windowPart.activateAsync(context);
|
|
86
|
+
* }
|
|
87
|
+
* ```
|
|
88
|
+
*/
|
|
89
|
+
export declare const windowPart: IWindowPart;
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* The base of every exception the window part throws, which a caller can catch to handle any of them.
|
|
93
|
+
*
|
|
94
|
+
* @example
|
|
95
|
+
* ```ts
|
|
96
|
+
* import { TerminalNotActiveException, TerminalWindowException } from "@noldova/terminal/window";
|
|
97
|
+
*
|
|
98
|
+
* console.log(new TerminalNotActiveException() instanceof TerminalWindowException);
|
|
99
|
+
* ```
|
|
100
|
+
*/
|
|
101
|
+
export declare class TerminalWindowException extends Exception {
|
|
102
|
+
/**
|
|
103
|
+
* `"TerminalWindowException"`, which a subclass replaces with its own.
|
|
104
|
+
*/
|
|
105
|
+
public override readonly name: string;
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Creates the exception.
|
|
109
|
+
*
|
|
110
|
+
* @param message The reason.
|
|
111
|
+
* @param options The options, such as the error that caused this one.
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* ```ts
|
|
115
|
+
* import { ExceptionOptions } from "@noldova/context.exceptions";
|
|
116
|
+
* import { TerminalWindowException } from "@noldova/terminal/window";
|
|
117
|
+
*
|
|
118
|
+
* const cause = new Error("The runtime closed.");
|
|
119
|
+
* console.log(new TerminalWindowException("The window failed.", new ExceptionOptions(cause)).cause === cause);
|
|
120
|
+
* ```
|
|
121
|
+
*/
|
|
122
|
+
public constructor(message: string, options?: ExceptionOptions);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Thrown when a window that already has a start folder provider is given another.
|
|
127
|
+
*
|
|
128
|
+
* @example
|
|
129
|
+
* ```ts
|
|
130
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
131
|
+
* import { StartFolderProvidedException, TerminalStartFolder } from "@noldova/terminal/window";
|
|
132
|
+
*
|
|
133
|
+
* export function provideHomeFolder(context: IWindowPartContext): void {
|
|
134
|
+
* try {
|
|
135
|
+
* TerminalStartFolder.provide(context, () => null);
|
|
136
|
+
* }
|
|
137
|
+
* catch (error) {
|
|
138
|
+
* console.log(error instanceof StartFolderProvidedException);
|
|
139
|
+
* }
|
|
140
|
+
* }
|
|
141
|
+
* ```
|
|
142
|
+
*/
|
|
143
|
+
export declare class StartFolderProvidedException extends TerminalWindowException {
|
|
144
|
+
/**
|
|
145
|
+
* `"StartFolderProvidedException"`.
|
|
146
|
+
*/
|
|
147
|
+
public override readonly name: string;
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* Creates the exception, whose message says to remove the first provider before providing another.
|
|
151
|
+
*
|
|
152
|
+
* @example
|
|
153
|
+
* ```ts
|
|
154
|
+
* import { StartFolderProvidedException } from "@noldova/terminal/window";
|
|
155
|
+
*
|
|
156
|
+
* console.log(new StartFolderProvidedException().message);
|
|
157
|
+
* ```
|
|
158
|
+
*/
|
|
159
|
+
public constructor();
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* The folder an app starts new terminals in. The terminal asks for it each time it opens a terminal without a folder of its own, such as the
|
|
164
|
+
* panel's first terminal and `terminal.new` without a `folder` argument.
|
|
165
|
+
*
|
|
166
|
+
* @remarks
|
|
167
|
+
* The home folder stands in when no app provides a folder, the provider gives `null`, or it gives a folder that is blank, relative or longer
|
|
168
|
+
* than the protocol's `Resources.maximumPathLength`, which the providing app's log says. A folder that no longer exists opens the terminal in
|
|
169
|
+
* the home folder too, which the module's log and the terminal's first line say.
|
|
170
|
+
*/
|
|
171
|
+
export declare class TerminalStartFolder {
|
|
172
|
+
/**
|
|
173
|
+
* Provides the window's start folder.
|
|
174
|
+
*
|
|
175
|
+
* @param context The providing app part's context, whose log says when its folder is refused.
|
|
176
|
+
* @param folder Gives the folder, an absolute path, or `null` for the home folder; it is called at each open.
|
|
177
|
+
* @returns A function that removes the provider.
|
|
178
|
+
* @throws {@link StartFolderProvidedException} Synchronously, when the window already has a provider.
|
|
179
|
+
*
|
|
180
|
+
* @example
|
|
181
|
+
* ```ts
|
|
182
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
183
|
+
* import { TerminalStartFolder } from "@noldova/terminal/window";
|
|
184
|
+
*
|
|
185
|
+
* export function provideProjectFolder(context: IWindowPartContext, project: { readonly folder: string | null }): () => void {
|
|
186
|
+
* const unregister: () => void = TerminalStartFolder.provide(context, () => project.folder);
|
|
187
|
+
* return unregister;
|
|
188
|
+
* }
|
|
189
|
+
* ```
|
|
190
|
+
*/
|
|
191
|
+
public static provide(context: IWindowPartContext, folder: () => string | null): () => void;
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Reads the start folder as the next terminal would open in it.
|
|
195
|
+
*
|
|
196
|
+
* @returns The provided folder, or `null` for the home folder.
|
|
197
|
+
*
|
|
198
|
+
* @example
|
|
199
|
+
* ```ts
|
|
200
|
+
* import { TerminalStartFolder } from "@noldova/terminal/window";
|
|
201
|
+
*
|
|
202
|
+
* console.log(TerminalStartFolder.read());
|
|
203
|
+
* ```
|
|
204
|
+
*/
|
|
205
|
+
public static read(): string | null;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Thrown when a window that already has an owners provider is given another.
|
|
210
|
+
*
|
|
211
|
+
* @example
|
|
212
|
+
* ```ts
|
|
213
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
214
|
+
* import { OwnersProvidedException, TerminalOwners } from "@noldova/terminal/window";
|
|
215
|
+
*
|
|
216
|
+
* export function provideNoOwner(context: IWindowPartContext): void {
|
|
217
|
+
* try {
|
|
218
|
+
* TerminalOwners.provide(context, () => null);
|
|
219
|
+
* }
|
|
220
|
+
* catch (error) {
|
|
221
|
+
* console.log(error instanceof OwnersProvidedException);
|
|
222
|
+
* }
|
|
223
|
+
* }
|
|
224
|
+
* ```
|
|
225
|
+
*/
|
|
226
|
+
export declare class OwnersProvidedException extends TerminalWindowException {
|
|
227
|
+
/**
|
|
228
|
+
* `"OwnersProvidedException"`.
|
|
229
|
+
*/
|
|
230
|
+
public override readonly name: string;
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Creates the exception, whose message says to remove the first provider before providing another.
|
|
234
|
+
*
|
|
235
|
+
* @example
|
|
236
|
+
* ```ts
|
|
237
|
+
* import { OwnersProvidedException } from "@noldova/terminal/window";
|
|
238
|
+
*
|
|
239
|
+
* console.log(new OwnersProvidedException().message);
|
|
240
|
+
* ```
|
|
241
|
+
*/
|
|
242
|
+
public constructor();
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* What an app ties a window's terminals to, such as its chats: an owner, a string of 1 to 256 UTF-16 code units the app chooses, which
|
|
247
|
+
* Terminal only compares.
|
|
248
|
+
*
|
|
249
|
+
* @remarks
|
|
250
|
+
* The window shows the terminals without an owner and one owner's at a time. Another owner's terminals have no tab: their shells keep running
|
|
251
|
+
* and the runtime keeps their output, and their tabs open again when their owner shows. The window starts with no owner shown, so after a
|
|
252
|
+
* reload the app shows its current owner again. The panel's terminal never has an owner.
|
|
253
|
+
*/
|
|
254
|
+
export declare class TerminalOwners {
|
|
255
|
+
private constructor();
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* The longest commands {@link TerminalOwners.runAsync} takes, `16384` UTF-16 code units.
|
|
259
|
+
*/
|
|
260
|
+
public static readonly maximumCommandLength: number;
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* The most lines {@link TerminalOwners.readRunOutputAsync} gives when not asked for fewer or more, `2000`.
|
|
264
|
+
*/
|
|
265
|
+
public static readonly defaultRunLines: number;
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* The most lines {@link TerminalOwners.readRunOutputAsync} gives, `5000`.
|
|
269
|
+
*/
|
|
270
|
+
public static readonly maximumRunLines: number;
|
|
271
|
+
|
|
272
|
+
/**
|
|
273
|
+
* The color of an output line's text run that stands for the terminal's default foreground or background, `-1`; another color is a palette
|
|
274
|
+
* index from `0` to `255`, or an RGB color.
|
|
275
|
+
*/
|
|
276
|
+
public static readonly defaultColor: number;
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* The offset of an RGB color in an output line's text run, `16777216` (`0x1000000`): a color `rgbColor + 0xRRGGBB` stands for that RGB
|
|
280
|
+
* color.
|
|
281
|
+
*/
|
|
282
|
+
public static readonly rgbColor: number;
|
|
283
|
+
|
|
284
|
+
/**
|
|
285
|
+
* The owner whose terminals the window shows, or `null`.
|
|
286
|
+
*/
|
|
287
|
+
public static get shown(): string | null;
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Provides the window's owners.
|
|
291
|
+
*
|
|
292
|
+
* @param context The providing app part's context, which makes the owners' requests and whose log says when its new owner is refused; the
|
|
293
|
+
* tabs open and close through Terminal's own window part, since a part may open and close only its own module's views.
|
|
294
|
+
* @param newOwner Gives the owner that a terminal from Terminal's + and Toggle Terminal's first open takes, or `null` for none; it is called
|
|
295
|
+
* at each open. A blank or over-long owner, or one it throws for, opens a terminal without an owner. The shell menu's rows, Ctrl+Shift+\`
|
|
296
|
+
* and the View menu open a terminal without an owner, whatever it gives.
|
|
297
|
+
* @returns The window's owners.
|
|
298
|
+
* @throws {@link OwnersProvidedException} Synchronously, when the window already has a provider.
|
|
299
|
+
*
|
|
300
|
+
* @example
|
|
301
|
+
* ```ts
|
|
302
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
303
|
+
* import { TerminalOwners } from "@noldova/terminal/window";
|
|
304
|
+
*
|
|
305
|
+
* export function provideChatOwners(context: IWindowPartContext, chat: { readonly id: string }): TerminalOwners {
|
|
306
|
+
* const owners = TerminalOwners.provide(context, () => `example.chat/${chat.id}`);
|
|
307
|
+
* return owners;
|
|
308
|
+
* }
|
|
309
|
+
* ```
|
|
310
|
+
*/
|
|
311
|
+
public static provide(context: IWindowPartContext, newOwner: () => string | null): TerminalOwners;
|
|
312
|
+
|
|
313
|
+
/**
|
|
314
|
+
* Reads the new owner as the next terminal from Terminal's own entries would take it.
|
|
315
|
+
*
|
|
316
|
+
* @returns The provided owner, or `null` for none.
|
|
317
|
+
*
|
|
318
|
+
* @example
|
|
319
|
+
* ```ts
|
|
320
|
+
* import { TerminalOwners } from "@noldova/terminal/window";
|
|
321
|
+
*
|
|
322
|
+
* console.log(TerminalOwners.readNewOwner());
|
|
323
|
+
* ```
|
|
324
|
+
*/
|
|
325
|
+
public static readNewOwner(): string | null;
|
|
326
|
+
|
|
327
|
+
/**
|
|
328
|
+
* Checks commands as {@link TerminalOwners.runAsync} does, so an app can offer Run only for commands it takes.
|
|
329
|
+
*
|
|
330
|
+
* @param command The commands.
|
|
331
|
+
* @returns `true` when they aren't blank, have at most {@link TerminalOwners.maximumCommandLength} UTF-16 code units, hold no control
|
|
332
|
+
* character but line feeds, carriage returns before line feeds, and tabs, and no format or default-ignorable character outside an emoji,
|
|
333
|
+
* such as a bidirectional mark, a zero-width character or a variation selector, which would make them read differently from what runs.
|
|
334
|
+
* A tab may still keep them from being typed, into a shell without bracketed paste ({@link TerminalRunNotTypedException}).
|
|
335
|
+
*
|
|
336
|
+
* @example
|
|
337
|
+
* ```ts
|
|
338
|
+
* import { TerminalOwners } from "@noldova/terminal/window";
|
|
339
|
+
*
|
|
340
|
+
* console.log(TerminalOwners.canRun("npm install\nnpm test"));
|
|
341
|
+
* ```
|
|
342
|
+
*/
|
|
343
|
+
public static canRun(command: string): boolean;
|
|
344
|
+
|
|
345
|
+
/**
|
|
346
|
+
* Shows the owner's terminals in this window, in the order they opened, and hides every other owner's. While Terminal's window part isn't
|
|
347
|
+
* active, or once it stops during the show, it only sets the owner, whose tabs open as the part activates.
|
|
348
|
+
*
|
|
349
|
+
* @param owner The owner, or `null` to hide every owned terminal.
|
|
350
|
+
* @returns A promise that resolves once the tabs have opened and closed; the shows run in the order asked, and one that rejects leaves the
|
|
351
|
+
* window as it was.
|
|
352
|
+
* @throws `ArgumentException` Synchronously, when the owner is blank or too long.
|
|
353
|
+
*
|
|
354
|
+
* @example
|
|
355
|
+
* ```ts
|
|
356
|
+
* import type { TerminalOwners } from "@noldova/terminal/window";
|
|
357
|
+
*
|
|
358
|
+
* export async function showChatAsync(owners: TerminalOwners, chat: { readonly id: string }): Promise<void> {
|
|
359
|
+
* await owners.showAsync(`example.chat/${chat.id}`);
|
|
360
|
+
* }
|
|
361
|
+
* ```
|
|
362
|
+
*/
|
|
363
|
+
public showAsync(owner: string | null): Promise<void>;
|
|
364
|
+
|
|
365
|
+
/**
|
|
366
|
+
* Ends every terminal of the owner, in every window, as closing its tab does, and forgets them for the next run; each window closes their
|
|
367
|
+
* tabs.
|
|
368
|
+
*
|
|
369
|
+
* @param owner The owner.
|
|
370
|
+
* @returns A promise that resolves once the runtime has ended them; it rejects with an `ArgumentException` when the owner is blank or too
|
|
371
|
+
* long.
|
|
372
|
+
*
|
|
373
|
+
* @example
|
|
374
|
+
* ```ts
|
|
375
|
+
* import type { TerminalOwners } from "@noldova/terminal/window";
|
|
376
|
+
*
|
|
377
|
+
* export async function closeChatAsync(owners: TerminalOwners, chat: { readonly id: string }): Promise<void> {
|
|
378
|
+
* await owners.closeAsync(`example.chat/${chat.id}`);
|
|
379
|
+
* }
|
|
380
|
+
* ```
|
|
381
|
+
*/
|
|
382
|
+
public closeAsync(owner: string): Promise<void>;
|
|
383
|
+
|
|
384
|
+
/**
|
|
385
|
+
* Runs commands the person asked to run, such as a chat's shell code block, in a terminal of the owner, as pasting them there and pressing
|
|
386
|
+
* Enter would.
|
|
387
|
+
*
|
|
388
|
+
* @remarks
|
|
389
|
+
* The runtime types them into the owner's newest terminal that is free: a person's terminal, not an agent's, whose shell is running, has the
|
|
390
|
+
* shell integration, is of one of the kinds, and is at its prompt with nothing typed after it and no keys within the last second. A shell
|
|
391
|
+
* without the integration, such as Command Prompt, can't be told free, so each run there opens a new terminal. With no free terminal, it
|
|
392
|
+
* opens one for the owner in the folder, with the window's default shell when it is of the kinds or none are given, else the first installed
|
|
393
|
+
* shell of the kinds, and types them once the shell is ready; with no shell of the kinds installed, nothing opens or is typed, since a shell
|
|
394
|
+
* of another kind would read them differently. Their line breaks are typed as Enter inside a bracketed paste when the shell asked for one,
|
|
395
|
+
* so several lines run as their paste would, and Enter follows once; blank lines at their start and line breaks at their end are dropped,
|
|
396
|
+
* so the first command stays on the prompt's line. Terminal never logs them.
|
|
397
|
+
* While the window shows the owner, the terminal's tab shows and its pane takes the focus, as a new terminal's does; a terminal of another
|
|
398
|
+
* owner gets its tab when that owner shows, so the app shows the owner first.
|
|
399
|
+
*
|
|
400
|
+
* @param owner The owner: not blank, at most 256 UTF-16 code units.
|
|
401
|
+
* @param command The commands, as {@link TerminalOwners.canRun} checks them.
|
|
402
|
+
* @param folder The absolute folder a new terminal starts in, or `null` for the app's {@link TerminalStartFolder}, else the person's home
|
|
403
|
+
* folder, which also stands in for a folder that no longer exists.
|
|
404
|
+
* @param shellKinds The kinds of shell that may run them, such as Bash and Zsh for a `bash` block; an empty list means any.
|
|
405
|
+
* @returns A promise of the terminal's session id, once the runtime has typed the commands, onto an empty prompt line with nothing typed
|
|
406
|
+
* since it picked the terminal, and the tab has opened; a new terminal's tab opens first, and the commands go in once its pane gave the
|
|
407
|
+
* terminal its size, so they draw at the pane's width.
|
|
408
|
+
* @throws {@link TerminalRunRefusedException} As the promise's rejection, never synchronously, before anything opens or is typed, when
|
|
409
|
+
* Terminal's window part isn't active, or the owner, the commands, the folder or a kind is refused, or for `shellKinds` when no shell of the
|
|
410
|
+
* kinds is installed, with a message that names them, such as "The commands weren't run, and nothing opened: no shell of the kinds they need
|
|
411
|
+
* is installed (Bash or Zsh)."
|
|
412
|
+
* @throws {@link TerminalRunNotTypedException} As the promise's rejection, once the tab has opened, when the runtime picked or opened a
|
|
413
|
+
* terminal but didn't type the commands; the promise rejects with what the runtime rejects with when it fails the run otherwise.
|
|
414
|
+
*
|
|
415
|
+
* @example
|
|
416
|
+
* ```ts
|
|
417
|
+
* import { TerminalOwners, TerminalShellKind } from "@noldova/terminal/window";
|
|
418
|
+
*
|
|
419
|
+
* export async function runBlockAsync(owners: TerminalOwners, chat: { readonly id: string; readonly folder: string | null },
|
|
420
|
+
* block: { readonly text: string }): Promise<void> {
|
|
421
|
+
* const owner = `example.chat/${chat.id}`;
|
|
422
|
+
* await owners.showAsync(owner);
|
|
423
|
+
* if (TerminalOwners.canRun(block.text))
|
|
424
|
+
* await owners.runAsync(owner, block.text, chat.folder, [TerminalShellKind.Bash, TerminalShellKind.Zsh]);
|
|
425
|
+
* }
|
|
426
|
+
* ```
|
|
427
|
+
*/
|
|
428
|
+
public runAsync(owner: string, command: string, folder: string | null, shellKinds: readonly TerminalShellKind[]): Promise<string>;
|
|
429
|
+
|
|
430
|
+
/**
|
|
431
|
+
* Runs commands as {@link TerminalOwners.runAsync} does, or into one given terminal, and gives the run, whose output
|
|
432
|
+
* {@link TerminalOwners.readRunOutputAsync} reads; `runAsync` is this with no target, giving the run's session id.
|
|
433
|
+
*
|
|
434
|
+
* @remarks
|
|
435
|
+
* With a target, the commands go only into that terminal, which must be a person's terminal of the owner, of one of the kinds, that the
|
|
436
|
+
* window reaches, such as one an app shows with {@link EmbeddedTerminal} under the commands; no tab opens or shows, since the app shows the
|
|
437
|
+
* terminal itself, and the folder isn't used. For any other target, as for one that ended, closed or restarted, the run fails as `Ended`,
|
|
438
|
+
* alike, so the app runs the commands in a new terminal. While the target's shell is busy, running a command or with text on its prompt line, or
|
|
439
|
+
* always for a shell without the shell integration, which can't be told free, a run whose target says `Refuse` types nothing and fails as
|
|
440
|
+
* `Busy`; one that says `Interrupt` waits up to two seconds for a command to start, sends it Ctrl+C, waits up to two seconds more for the
|
|
441
|
+
* shell to be back at an empty prompt, then types, else fails as `Busy`; a line that doesn't start gets no Ctrl+C. A run that comes while another run into the target is still starting types nothing and fails as `Busy` too.
|
|
442
|
+
*
|
|
443
|
+
* With `shown`, no tab opens or takes the focus for the run's terminal, whether the run picks a free one, opens a new one or is given a
|
|
444
|
+
* target, and none opens later as the owner shows, since the app shows the terminal in its own pane; the terminal stays in the window's list
|
|
445
|
+
* and the agents' tools, and its tab opens only when the person opens it. `shown` gets the terminal's session ID before anything is typed:
|
|
446
|
+
* the app attaches its pane then, and a new terminal waits for that pane's first fit, however long it takes, before the commands are typed
|
|
447
|
+
* at its size; it starts at 80 columns at once when the window closes or detaches the pane first. A window's runs with `shown` start one at a time.
|
|
448
|
+
*
|
|
449
|
+
* @param owner The owner: not blank, at most 256 UTF-16 code units.
|
|
450
|
+
* @param command The commands, as {@link TerminalOwners.canRun} checks them.
|
|
451
|
+
* @param folder The absolute folder a new terminal starts in, or `null`, as {@link TerminalOwners.runAsync} takes it.
|
|
452
|
+
* @param shellKinds The kinds of shell that may run them; an empty list means any.
|
|
453
|
+
* @param target The terminal the commands go into, and what a busy one gets, or `null` for the runtime's choice, as
|
|
454
|
+
* {@link TerminalOwners.runAsync} makes it.
|
|
455
|
+
* @param shown Called once with the terminal's session ID before the commands are typed, for a run without a tab, or `null`, the default,
|
|
456
|
+
* for a run whose terminal's tab opens as {@link TerminalOwners.runAsync} opens it.
|
|
457
|
+
* @returns A promise of the run, once the runtime has typed the commands and, without a target or `shown`, the tab has opened.
|
|
458
|
+
* @throws {@link TerminalRunRefusedException} As the promise's rejection, never synchronously, before anything opens or is typed, as
|
|
459
|
+
* {@link TerminalOwners.runAsync} rejects with it, or for `sessionId` or `whenBusy` when the target's own fields are refused.
|
|
460
|
+
* @throws {@link TerminalRunNotTypedException} As the promise's rejection, when the runtime picked, opened or was given a terminal but didn't
|
|
461
|
+
* type the commands, with
|
|
462
|
+
* the reason `Busy` for a busy target, and `Ended` for a target that isn't a person's terminal of the owner, of one of the kinds, that the
|
|
463
|
+
* window reaches; the promise rejects with what the runtime rejects with when it fails the run otherwise.
|
|
464
|
+
*
|
|
465
|
+
* @example
|
|
466
|
+
* ```ts
|
|
467
|
+
* import { TerminalRunBusy, TerminalRunTarget, type TerminalOwners } from "@noldova/terminal/window";
|
|
468
|
+
*
|
|
469
|
+
* export async function runTestsAsync(owners: TerminalOwners, chat: { readonly id: string }, sessionId: string): Promise<void> {
|
|
470
|
+
* const target = new TerminalRunTarget(sessionId, TerminalRunBusy.Interrupt);
|
|
471
|
+
* const run = await owners.startRunAsync(`example.chat/${chat.id}`, "npm test", null, [], target);
|
|
472
|
+
* console.log(run.runId);
|
|
473
|
+
* }
|
|
474
|
+
* ```
|
|
475
|
+
*/
|
|
476
|
+
public startRunAsync(owner: string, command: string, folder: string | null, shellKinds: readonly TerminalShellKind[],
|
|
477
|
+
target: TerminalRunTarget | null, shown?: ((sessionId: string) => void) | null): Promise<TerminalRun>;
|
|
478
|
+
|
|
479
|
+
/**
|
|
480
|
+
* Reads a run's output with its colors, such as to show it or hand it on after the person ran a block.
|
|
481
|
+
*
|
|
482
|
+
* @remarks
|
|
483
|
+
* The output holds the run's lines from the prompt where its commands were typed up to the prompt where the next run into the same terminal
|
|
484
|
+
* typed, or up to the cursor's line for the terminal's latest run, so the commands the person typed in between are in it. It gives the last
|
|
485
|
+
* of them, at most the number asked, each from a line's start, never the rest of a wrapped line, and `cutLines` counts the earlier lines it
|
|
486
|
+
* left out: those over the limit, and those the terminal no longer holds, such as lines past what it keeps of its scrollback or ones the
|
|
487
|
+
* shell erased, as `clear` does. Only a person's terminals' runs are read, and no agent tool reads them.
|
|
488
|
+
*
|
|
489
|
+
* @param run The run, from {@link TerminalOwners.startRunAsync}.
|
|
490
|
+
* @param maximumLines The most lines: a whole number from `1` to {@link TerminalOwners.maximumRunLines};
|
|
491
|
+
* {@link TerminalOwners.defaultRunLines} when left out.
|
|
492
|
+
* @returns A promise of the output.
|
|
493
|
+
* @throws {@link RunLinesRefusedException} As the promise's rejection, never synchronously, when the number of lines isn't a whole number in
|
|
494
|
+
* its range, before anything is asked.
|
|
495
|
+
* @throws {@link TerminalRunNotFoundException} As the promise's rejection, when the run's ids can't name a run, before anything is asked, or
|
|
496
|
+
* when the runtime can't give the run: its terminal never had it or no longer keeps it, as it keeps its latest 100 runs, its shell ended or
|
|
497
|
+
* restarted, or the runtime no longer has its terminal, such as after it started again; the promise rejects with what the runtime rejects
|
|
498
|
+
* with when it fails the read otherwise.
|
|
499
|
+
*
|
|
500
|
+
* @example
|
|
501
|
+
* ```ts
|
|
502
|
+
* import { TerminalRunNotFoundException, type TerminalLine, type TerminalOwners, type TerminalRun } from "@noldova/terminal/window";
|
|
503
|
+
*
|
|
504
|
+
* export async function logOutputAsync(owners: TerminalOwners, run: TerminalRun): Promise<void> {
|
|
505
|
+
* try {
|
|
506
|
+
* const output = await owners.readRunOutputAsync(run, 200);
|
|
507
|
+
* console.log(output.lines.map((t: TerminalLine) => t.text).join("\n"), output.cutLines);
|
|
508
|
+
* }
|
|
509
|
+
* catch (error) {
|
|
510
|
+
* console.log(error instanceof TerminalRunNotFoundException);
|
|
511
|
+
* }
|
|
512
|
+
* }
|
|
513
|
+
* ```
|
|
514
|
+
*/
|
|
515
|
+
public readRunOutputAsync(run: TerminalRun, maximumLines?: number): Promise<TerminalRunOutput>;
|
|
516
|
+
|
|
517
|
+
/**
|
|
518
|
+
* Hides every owned terminal and removes the provider, so another can be provided; it does nothing once removed.
|
|
519
|
+
*
|
|
520
|
+
* @returns A promise that resolves once the tabs have closed.
|
|
521
|
+
*
|
|
522
|
+
* @example
|
|
523
|
+
* ```ts
|
|
524
|
+
* import type { TerminalOwners } from "@noldova/terminal/window";
|
|
525
|
+
*
|
|
526
|
+
* export async function removeOwnersAsync(owners: TerminalOwners): Promise<void> {
|
|
527
|
+
* await owners.removeAsync();
|
|
528
|
+
* }
|
|
529
|
+
* ```
|
|
530
|
+
*/
|
|
531
|
+
public removeAsync(): Promise<void>;
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
/**
|
|
535
|
+
* The base of the exceptions {@link TerminalOwners.runAsync} and {@link TerminalOwners.startRunAsync} throw when they refuse a run, before
|
|
536
|
+
* anything opened or was typed, which a caller catches to handle any refusal; each refusal is its own subclass.
|
|
537
|
+
*
|
|
538
|
+
* @example
|
|
539
|
+
* ```ts
|
|
540
|
+
* import { TerminalRunRefusedException, type TerminalOwners } from "@noldova/terminal/window";
|
|
541
|
+
*
|
|
542
|
+
* export async function runInRelativeFolderAsync(owners: TerminalOwners): Promise<void> {
|
|
543
|
+
* try {
|
|
544
|
+
* await owners.runAsync("example.chat/42", "ls", "work", []);
|
|
545
|
+
* }
|
|
546
|
+
* catch (error) {
|
|
547
|
+
* console.log(error instanceof TerminalRunRefusedException && error.parameter);
|
|
548
|
+
* }
|
|
549
|
+
* }
|
|
550
|
+
* ```
|
|
551
|
+
*/
|
|
552
|
+
export declare abstract class TerminalRunRefusedException extends TerminalWindowException {
|
|
553
|
+
/**
|
|
554
|
+
* `"TerminalRunRefusedException"`, which a subclass replaces with its own.
|
|
555
|
+
*/
|
|
556
|
+
public override readonly name: string;
|
|
557
|
+
|
|
558
|
+
/**
|
|
559
|
+
* The refused field: `owner`, `command`, `folder`, a kind such as `shellKinds.1`, `sessionId` or `whenBusy` for a target's refused
|
|
560
|
+
* field, `shellKinds` when no shell of the kinds is installed, or `context` while the terminal's window part isn't active. The exception
|
|
561
|
+
* never carries the commands.
|
|
562
|
+
*/
|
|
563
|
+
public abstract readonly parameter: string;
|
|
564
|
+
|
|
565
|
+
/**
|
|
566
|
+
* Creates the exception, for a subclass.
|
|
567
|
+
*
|
|
568
|
+
* @param message The message, which says that nothing ran or opened, and why.
|
|
569
|
+
* @param options The options, such as the error that caused this one.
|
|
570
|
+
*/
|
|
571
|
+
protected constructor(message: string, options?: ExceptionOptions);
|
|
572
|
+
}
|
|
573
|
+
|
|
574
|
+
/**
|
|
575
|
+
* Thrown when {@link TerminalOwners.runAsync} or {@link TerminalOwners.startRunAsync} is called while Terminal's window part isn't active in
|
|
576
|
+
* the window, before anything opened or was typed.
|
|
577
|
+
*
|
|
578
|
+
* @example
|
|
579
|
+
* ```ts
|
|
580
|
+
* import { RunPartInactiveException, type TerminalOwners } from "@noldova/terminal/window";
|
|
581
|
+
*
|
|
582
|
+
* export async function runListAsync(owners: TerminalOwners): Promise<void> {
|
|
583
|
+
* try {
|
|
584
|
+
* await owners.runAsync("example.chat/42", "ls", null, []);
|
|
585
|
+
* }
|
|
586
|
+
* catch (error) {
|
|
587
|
+
* console.log(error instanceof RunPartInactiveException);
|
|
588
|
+
* }
|
|
589
|
+
* }
|
|
590
|
+
* ```
|
|
591
|
+
*/
|
|
592
|
+
export declare class RunPartInactiveException extends TerminalRunRefusedException {
|
|
593
|
+
/**
|
|
594
|
+
* `"RunPartInactiveException"`.
|
|
595
|
+
*/
|
|
596
|
+
public override readonly name: string;
|
|
597
|
+
|
|
598
|
+
/**
|
|
599
|
+
* `"context"`.
|
|
600
|
+
*/
|
|
601
|
+
public override readonly parameter: string;
|
|
602
|
+
|
|
603
|
+
/**
|
|
604
|
+
* Creates the exception, whose message says that nothing ran or opened, since the terminal's window part isn't active in the window.
|
|
605
|
+
*
|
|
606
|
+
* @example
|
|
607
|
+
* ```ts
|
|
608
|
+
* import { RunPartInactiveException } from "@noldova/terminal/window";
|
|
609
|
+
*
|
|
610
|
+
* console.log(new RunPartInactiveException().message);
|
|
611
|
+
* ```
|
|
612
|
+
*/
|
|
613
|
+
public constructor();
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
/**
|
|
617
|
+
* Thrown when {@link TerminalOwners.runAsync} or {@link TerminalOwners.startRunAsync} refuses one of its arguments, such as a blank owner, a
|
|
618
|
+
* command with a control character or a relative folder, before anything opened or was typed.
|
|
619
|
+
*
|
|
620
|
+
* @example
|
|
621
|
+
* ```ts
|
|
622
|
+
* import { RunArgumentRefusedException, type TerminalOwners } from "@noldova/terminal/window";
|
|
623
|
+
*
|
|
624
|
+
* export async function runInRelativeFolderAsync(owners: TerminalOwners): Promise<void> {
|
|
625
|
+
* try {
|
|
626
|
+
* await owners.runAsync("example.chat/42", "ls", "work", []);
|
|
627
|
+
* }
|
|
628
|
+
* catch (error) {
|
|
629
|
+
* console.log(error instanceof RunArgumentRefusedException && error.parameter);
|
|
630
|
+
* }
|
|
631
|
+
* }
|
|
632
|
+
* ```
|
|
633
|
+
*/
|
|
634
|
+
export declare class RunArgumentRefusedException extends TerminalRunRefusedException {
|
|
635
|
+
/**
|
|
636
|
+
* `"RunArgumentRefusedException"`.
|
|
637
|
+
*/
|
|
638
|
+
public override readonly name: string;
|
|
639
|
+
|
|
640
|
+
/**
|
|
641
|
+
* The refused field: `owner`, `command`, `folder`, a kind such as `shellKinds.1`, or `sessionId` or `whenBusy` for a target's refused field.
|
|
642
|
+
*/
|
|
643
|
+
public override readonly parameter: string;
|
|
644
|
+
|
|
645
|
+
/**
|
|
646
|
+
* Why the field is refused, such as "Expected a string that is not blank."; it never holds the commands.
|
|
647
|
+
*/
|
|
648
|
+
public readonly reason: string;
|
|
649
|
+
|
|
650
|
+
/**
|
|
651
|
+
* Creates the exception, whose message says that nothing ran or opened, and gives the reason.
|
|
652
|
+
*
|
|
653
|
+
* @param parameterName The refused field.
|
|
654
|
+
* @param reason Why it is refused.
|
|
655
|
+
*
|
|
656
|
+
* @example
|
|
657
|
+
* ```ts
|
|
658
|
+
* import { RunArgumentRefusedException } from "@noldova/terminal/window";
|
|
659
|
+
*
|
|
660
|
+
* console.log(new RunArgumentRefusedException("owner", "Expected a string that is not blank.").message);
|
|
661
|
+
* ```
|
|
662
|
+
*/
|
|
663
|
+
public constructor(parameterName: string, reason: string);
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
/**
|
|
667
|
+
* Thrown when {@link TerminalOwners.runAsync} or {@link TerminalOwners.startRunAsync} finds no installed shell of the run's kinds, so nothing
|
|
668
|
+
* opened and nothing was typed, since a shell of another kind would read the commands differently.
|
|
669
|
+
*
|
|
670
|
+
* @example
|
|
671
|
+
* ```ts
|
|
672
|
+
* import { RunShellKindsMissingException, TerminalShellKind, type TerminalOwners } from "@noldova/terminal/window";
|
|
673
|
+
*
|
|
674
|
+
* export async function runInBashAsync(owners: TerminalOwners): Promise<void> {
|
|
675
|
+
* try {
|
|
676
|
+
* await owners.runAsync("example.chat/42", "ls", null, [TerminalShellKind.Bash, TerminalShellKind.Zsh]);
|
|
677
|
+
* }
|
|
678
|
+
* catch (error) {
|
|
679
|
+
* if (error instanceof RunShellKindsMissingException)
|
|
680
|
+
* console.log(error.message);
|
|
681
|
+
* }
|
|
682
|
+
* }
|
|
683
|
+
* ```
|
|
684
|
+
*/
|
|
685
|
+
export declare class RunShellKindsMissingException extends TerminalRunRefusedException {
|
|
686
|
+
/**
|
|
687
|
+
* `"RunShellKindsMissingException"`.
|
|
688
|
+
*/
|
|
689
|
+
public override readonly name: string;
|
|
690
|
+
|
|
691
|
+
/**
|
|
692
|
+
* `"shellKinds"`.
|
|
693
|
+
*/
|
|
694
|
+
public override readonly parameter: string;
|
|
695
|
+
|
|
696
|
+
/**
|
|
697
|
+
* The kinds of shell the run needs, none of which is installed.
|
|
698
|
+
*/
|
|
699
|
+
public readonly shellKinds: readonly TerminalShellKind[];
|
|
700
|
+
|
|
701
|
+
/**
|
|
702
|
+
* Creates the exception, whose message names the kinds, such as "The commands weren't run, and nothing opened: no shell of the kinds they
|
|
703
|
+
* need is installed (Bash or Zsh)."
|
|
704
|
+
*
|
|
705
|
+
* @param shellKinds The kinds of shell the run needs.
|
|
706
|
+
*
|
|
707
|
+
* @example
|
|
708
|
+
* ```ts
|
|
709
|
+
* import { RunShellKindsMissingException, TerminalShellKind } from "@noldova/terminal/window";
|
|
710
|
+
*
|
|
711
|
+
* console.log(new RunShellKindsMissingException([TerminalShellKind.Bash, TerminalShellKind.Zsh]).message);
|
|
712
|
+
* ```
|
|
713
|
+
*/
|
|
714
|
+
public constructor(shellKinds: readonly TerminalShellKind[]);
|
|
715
|
+
}
|
|
716
|
+
|
|
717
|
+
/**
|
|
718
|
+
* Thrown by {@link TerminalOwners.readRunOutputAsync} when the number of lines isn't a whole number from 1 to
|
|
719
|
+
* {@link TerminalOwners.maximumRunLines}, before anything is asked.
|
|
720
|
+
*
|
|
721
|
+
* @example
|
|
722
|
+
* ```ts
|
|
723
|
+
* import { RunLinesRefusedException, type TerminalOwners, type TerminalRun } from "@noldova/terminal/window";
|
|
724
|
+
*
|
|
725
|
+
* export async function readNoLinesAsync(owners: TerminalOwners, run: TerminalRun): Promise<void> {
|
|
726
|
+
* try {
|
|
727
|
+
* await owners.readRunOutputAsync(run, 0);
|
|
728
|
+
* }
|
|
729
|
+
* catch (error) {
|
|
730
|
+
* console.log(error instanceof RunLinesRefusedException && error.lines);
|
|
731
|
+
* }
|
|
732
|
+
* }
|
|
733
|
+
* ```
|
|
734
|
+
*/
|
|
735
|
+
export declare class RunLinesRefusedException extends TerminalWindowException {
|
|
736
|
+
/**
|
|
737
|
+
* `"RunLinesRefusedException"`.
|
|
738
|
+
*/
|
|
739
|
+
public override readonly name: string;
|
|
740
|
+
|
|
741
|
+
/**
|
|
742
|
+
* The number of lines asked for.
|
|
743
|
+
*/
|
|
744
|
+
public readonly lines: number;
|
|
745
|
+
|
|
746
|
+
/**
|
|
747
|
+
* The most lines a read takes.
|
|
748
|
+
*/
|
|
749
|
+
public readonly maximum: number;
|
|
750
|
+
|
|
751
|
+
/**
|
|
752
|
+
* Creates the exception, whose message gives the range and the number asked for.
|
|
753
|
+
*
|
|
754
|
+
* @param lines The number of lines asked for.
|
|
755
|
+
* @param maximum The most lines a read takes.
|
|
756
|
+
*
|
|
757
|
+
* @example
|
|
758
|
+
* ```ts
|
|
759
|
+
* import { RunLinesRefusedException, TerminalOwners } from "@noldova/terminal/window";
|
|
760
|
+
*
|
|
761
|
+
* console.log(new RunLinesRefusedException(0, TerminalOwners.maximumRunLines).message);
|
|
762
|
+
* ```
|
|
763
|
+
*/
|
|
764
|
+
public constructor(lines: number, maximum: number);
|
|
765
|
+
}
|
|
766
|
+
|
|
767
|
+
/**
|
|
768
|
+
* Thrown by {@link TerminalOwners.runAsync} and {@link TerminalOwners.startRunAsync} when the runtime picked or opened a terminal, whose tab
|
|
769
|
+
* shows, or was given one, but didn't type the commands into it. An app can log it by its name and reason, and the person may run the
|
|
770
|
+
* commands again.
|
|
771
|
+
*
|
|
772
|
+
* @example
|
|
773
|
+
* ```ts
|
|
774
|
+
* import { TerminalRunNotTypedException, TerminalRunOutcome, type TerminalOwners } from "@noldova/terminal/window";
|
|
775
|
+
*
|
|
776
|
+
* export async function runTestsAsync(owners: TerminalOwners): Promise<void> {
|
|
777
|
+
* try {
|
|
778
|
+
* await owners.runAsync("example.chat/42", "npm test", null, []);
|
|
779
|
+
* }
|
|
780
|
+
* catch (error) {
|
|
781
|
+
* console.log(error instanceof TerminalRunNotTypedException && error.reason === TerminalRunOutcome.Input);
|
|
782
|
+
* }
|
|
783
|
+
* }
|
|
784
|
+
* ```
|
|
785
|
+
*/
|
|
786
|
+
export declare class TerminalRunNotTypedException extends TerminalWindowException {
|
|
787
|
+
/**
|
|
788
|
+
* `"TerminalRunNotTypedException"`.
|
|
789
|
+
*/
|
|
790
|
+
public override readonly name: string;
|
|
791
|
+
|
|
792
|
+
/**
|
|
793
|
+
* The terminal's session, whose tab shows while the window shows its owner, unless the run had a target.
|
|
794
|
+
*/
|
|
795
|
+
public readonly sessionId: string;
|
|
796
|
+
|
|
797
|
+
/**
|
|
798
|
+
* Why nothing was typed: `Input` when the person typed in the terminal after the run picked it, or its prompt line held text, `Tab` when the
|
|
799
|
+
* commands hold a tab and the shell hasn't turned bracketed paste on, so it would take the tab as completion, or `Ended` when the terminal
|
|
800
|
+
* ended, closed or restarted first, or `Busy` when a run's target was busy and stayed so, or another run into it was still starting. Never
|
|
801
|
+
* `Typed`.
|
|
802
|
+
*/
|
|
803
|
+
public readonly reason: TerminalRunOutcome;
|
|
804
|
+
|
|
805
|
+
/**
|
|
806
|
+
* Creates the exception, whose message names the terminal and why nothing was typed, and never holds the commands.
|
|
807
|
+
*
|
|
808
|
+
* @param sessionId The terminal's session.
|
|
809
|
+
* @param reason Why nothing was typed.
|
|
810
|
+
*
|
|
811
|
+
* @example
|
|
812
|
+
* ```ts
|
|
813
|
+
* import { TerminalRunNotTypedException, TerminalRunOutcome } from "@noldova/terminal/window";
|
|
814
|
+
*
|
|
815
|
+
* console.log(new TerminalRunNotTypedException("session-1", TerminalRunOutcome.Busy).message);
|
|
816
|
+
* ```
|
|
817
|
+
*/
|
|
818
|
+
public constructor(sessionId: string, reason: TerminalRunOutcome);
|
|
819
|
+
}
|
|
820
|
+
|
|
821
|
+
/**
|
|
822
|
+
* A run an app started with {@link TerminalOwners.startRunAsync}: the terminal its commands went into, the run's own id, which reads its
|
|
823
|
+
* output, and its end.
|
|
824
|
+
*
|
|
825
|
+
* @example
|
|
826
|
+
* ```ts
|
|
827
|
+
* import type { TerminalOwners } from "@noldova/terminal/window";
|
|
828
|
+
*
|
|
829
|
+
* export async function runTestsAsync(owners: TerminalOwners): Promise<void> {
|
|
830
|
+
* const run = await owners.startRunAsync("example.chat/42", "npm test", null, [], null);
|
|
831
|
+
* const end = await run.ended;
|
|
832
|
+
* const output = await owners.readRunOutputAsync(run);
|
|
833
|
+
* console.log(run.sessionId, end.endedBy, end.exitCode, output.lines.length);
|
|
834
|
+
* }
|
|
835
|
+
* ```
|
|
836
|
+
*/
|
|
837
|
+
export declare class TerminalRun {
|
|
838
|
+
/**
|
|
839
|
+
* The session of the terminal the commands went into.
|
|
840
|
+
*/
|
|
841
|
+
public readonly sessionId: string;
|
|
842
|
+
|
|
843
|
+
/**
|
|
844
|
+
* The run's id, which {@link TerminalOwners.readRunOutputAsync} reads the output by.
|
|
845
|
+
*/
|
|
846
|
+
public readonly runId: string;
|
|
847
|
+
|
|
848
|
+
/**
|
|
849
|
+
* Resolves once, when the run's commands have ended, and never rejects; a later run into the same terminal doesn't change it.
|
|
850
|
+
*
|
|
851
|
+
* - `"Command"` when the shell marked the end of the run's last command, with that command's exit code, or `null` when the shell gave none,
|
|
852
|
+
* as bash doesn't for a subshell such as `(exit 3)`. A run of several lines ends with its last line's command. A Ctrl+C, from
|
|
853
|
+
* {@link TerminalRunBusy.Interrupt} or from the person, ends a command like any other, with the code the shell gives.
|
|
854
|
+
* - `"NoIntegration"` when the shell has no integration to mark a command's end, such as Command Prompt, fish or WSL: it has already resolved
|
|
855
|
+
* when {@link TerminalOwners.startRunAsync} resolves, so a run in such a shell never looks running. A new terminal's shell that marked
|
|
856
|
+
* nothing within 10 seconds, such as one whose profile takes that long to load, counts as having none: the run is typed then and ends this
|
|
857
|
+
* way, though its commands may still run.
|
|
858
|
+
* - `"TerminalEnded"` when the terminal's shell exited or restarted, the terminal closed, or the runtime started again, before the end.
|
|
859
|
+
*
|
|
860
|
+
* A run's `ended` has resolved before a later run this window starts into the same terminal resolves {@link TerminalOwners.startRunAsync},
|
|
861
|
+
* whichever {@link TerminalRunBusy} it took, since the runtime ends a run still waiting before it types the next one; a run that waits with no
|
|
862
|
+
* end mark, as for a command that goes on over several lines in a shell that takes no bracketed paste, such as macOS's bash 3.2, then ends as
|
|
863
|
+
* `"Command"` with the last code the shell marked for it, or `null`.
|
|
864
|
+
*
|
|
865
|
+
* @example
|
|
866
|
+
* ```ts
|
|
867
|
+
* import type { TerminalOwners, TerminalRunTarget } from "@noldova/terminal/window";
|
|
868
|
+
*
|
|
869
|
+
* export async function logTestsEndAsync(owners: TerminalOwners, chat: { readonly id: string },
|
|
870
|
+
* target: TerminalRunTarget | null): Promise<void> {
|
|
871
|
+
* const run = await owners.startRunAsync(`example.chat/${chat.id}`, "npm test", null, [], target);
|
|
872
|
+
* const end = await run.ended;
|
|
873
|
+
* console.log(end.endedBy === "Command" ? `exited with ${end.exitCode}` : end.endedBy);
|
|
874
|
+
* }
|
|
875
|
+
* ```
|
|
876
|
+
*/
|
|
877
|
+
public readonly ended: Promise<TerminalRunEnd>;
|
|
878
|
+
|
|
879
|
+
/**
|
|
880
|
+
* Creates the run, as {@link TerminalOwners.startRunAsync} does; an app keeps the one it is given.
|
|
881
|
+
*
|
|
882
|
+
* @param sessionId The terminal's session.
|
|
883
|
+
* @param runId The run's id.
|
|
884
|
+
* @param ended The run's end, for {@link TerminalRun.ended}; {@link TerminalOwners.startRunAsync} gives it, and a run made without one
|
|
885
|
+
* resolves `"TerminalEnded"` at once.
|
|
886
|
+
*
|
|
887
|
+
* @example
|
|
888
|
+
* ```ts
|
|
889
|
+
* import { TerminalRun, TerminalRunEnd } from "@noldova/terminal/window";
|
|
890
|
+
*
|
|
891
|
+
* console.log(new TerminalRun("session-1", "run-1", Promise.resolve(new TerminalRunEnd("Command", 0))).runId);
|
|
892
|
+
* ```
|
|
893
|
+
*/
|
|
894
|
+
public constructor(sessionId: string, runId: string, ended?: Promise<TerminalRunEnd>);
|
|
895
|
+
}
|
|
896
|
+
|
|
897
|
+
/**
|
|
898
|
+
* How a run's commands ended, which {@link TerminalRun.ended} gives.
|
|
899
|
+
*
|
|
900
|
+
* @example
|
|
901
|
+
* ```ts
|
|
902
|
+
* import type { TerminalRunEnd } from "@noldova/terminal/window";
|
|
903
|
+
*
|
|
904
|
+
* function describe(end: TerminalRunEnd): string {
|
|
905
|
+
* return end.endedBy === "Command" ? `exited with ${end.exitCode}` : end.endedBy;
|
|
906
|
+
* }
|
|
907
|
+
* ```
|
|
908
|
+
*/
|
|
909
|
+
export declare class TerminalRunEnd {
|
|
910
|
+
/**
|
|
911
|
+
* `"Command"` when the shell marked the end of the run's last command, `"NoIntegration"` when the shell has no integration to mark it, or
|
|
912
|
+
* `"TerminalEnded"` when the terminal's shell exited or restarted, the terminal closed, or the runtime started again first.
|
|
913
|
+
*/
|
|
914
|
+
public readonly endedBy: "Command" | "NoIntegration" | "TerminalEnded";
|
|
915
|
+
|
|
916
|
+
/**
|
|
917
|
+
* The last command's exit code, or `null` unless `endedBy` is `"Command"`, and for a command the shell gave no code.
|
|
918
|
+
*/
|
|
919
|
+
public readonly exitCode: number | null;
|
|
920
|
+
|
|
921
|
+
/**
|
|
922
|
+
* Creates the end.
|
|
923
|
+
*
|
|
924
|
+
* @param endedBy How the run's commands ended.
|
|
925
|
+
* @param exitCode The last command's exit code, or `null`.
|
|
926
|
+
*
|
|
927
|
+
* @example
|
|
928
|
+
* ```ts
|
|
929
|
+
* import { TerminalRunEnd } from "@noldova/terminal/window";
|
|
930
|
+
*
|
|
931
|
+
* console.log(new TerminalRunEnd("TerminalEnded", null).endedBy);
|
|
932
|
+
* ```
|
|
933
|
+
*/
|
|
934
|
+
public constructor(endedBy: "Command" | "NoIntegration" | "TerminalEnded", exitCode: number | null);
|
|
935
|
+
}
|
|
936
|
+
|
|
937
|
+
/**
|
|
938
|
+
* The terminal a run goes into, a person's terminal of the run's owner, such as the one an app shows under the commands with
|
|
939
|
+
* {@link EmbeddedTerminal}, and what the run does while that terminal's shell is busy.
|
|
940
|
+
*
|
|
941
|
+
* @example
|
|
942
|
+
* ```ts
|
|
943
|
+
* import { TerminalRunBusy, TerminalRunTarget, type TerminalOwners } from "@noldova/terminal/window";
|
|
944
|
+
*
|
|
945
|
+
* export async function runTestsInAsync(owners: TerminalOwners, sessionId: string): Promise<void> {
|
|
946
|
+
* const target = new TerminalRunTarget(sessionId, TerminalRunBusy.Interrupt);
|
|
947
|
+
* await owners.startRunAsync("example.chat/42", "npm test", null, [], target);
|
|
948
|
+
* }
|
|
949
|
+
* ```
|
|
950
|
+
*/
|
|
951
|
+
export declare class TerminalRunTarget {
|
|
952
|
+
/**
|
|
953
|
+
* The terminal's session.
|
|
954
|
+
*/
|
|
955
|
+
public readonly sessionId: string;
|
|
956
|
+
|
|
957
|
+
/**
|
|
958
|
+
* What the run does while the terminal's shell is busy: `Refuse` types nothing, and `Interrupt` sends Ctrl+C to a command that starts within
|
|
959
|
+
* two seconds and types once the shell is back at an empty prompt within two seconds more; either fails the run as `Busy` when it types
|
|
960
|
+
* nothing.
|
|
961
|
+
*/
|
|
962
|
+
public readonly whenBusy: TerminalRunBusy;
|
|
963
|
+
|
|
964
|
+
/**
|
|
965
|
+
* Creates the target.
|
|
966
|
+
*
|
|
967
|
+
* @param sessionId The terminal's session, which {@link TerminalOwners.startRunAsync} checks.
|
|
968
|
+
* @param whenBusy What the run does while the shell is busy; `Refuse` when left out.
|
|
969
|
+
*
|
|
970
|
+
* @example
|
|
971
|
+
* ```ts
|
|
972
|
+
* import { TerminalRunBusy, TerminalRunTarget } from "@noldova/terminal/window";
|
|
973
|
+
*
|
|
974
|
+
* console.log(new TerminalRunTarget("session-1", TerminalRunBusy.Interrupt).whenBusy);
|
|
975
|
+
* ```
|
|
976
|
+
*/
|
|
977
|
+
public constructor(sessionId: string, whenBusy?: TerminalRunBusy);
|
|
978
|
+
}
|
|
979
|
+
|
|
980
|
+
/**
|
|
981
|
+
* Thrown by {@link TerminalOwners.readRunOutputAsync} when the runtime can't give a run's output: its terminal never had the run or no
|
|
982
|
+
* longer keeps it, its shell ended or restarted, or the runtime no longer has its terminal, such as after it started again.
|
|
983
|
+
*
|
|
984
|
+
* @example
|
|
985
|
+
* ```ts
|
|
986
|
+
* import { TerminalRunNotFoundException, type TerminalOwners, type TerminalRun } from "@noldova/terminal/window";
|
|
987
|
+
*
|
|
988
|
+
* export async function readOutputAsync(owners: TerminalOwners, run: TerminalRun): Promise<void> {
|
|
989
|
+
* try {
|
|
990
|
+
* await owners.readRunOutputAsync(run);
|
|
991
|
+
* }
|
|
992
|
+
* catch (error) {
|
|
993
|
+
* console.log(error instanceof TerminalRunNotFoundException && error.runId);
|
|
994
|
+
* }
|
|
995
|
+
* }
|
|
996
|
+
* ```
|
|
997
|
+
*/
|
|
998
|
+
export declare class TerminalRunNotFoundException extends TerminalWindowException {
|
|
999
|
+
/**
|
|
1000
|
+
* `"TerminalRunNotFoundException"`.
|
|
1001
|
+
*/
|
|
1002
|
+
public override readonly name: string;
|
|
1003
|
+
|
|
1004
|
+
/**
|
|
1005
|
+
* The session of the run's terminal.
|
|
1006
|
+
*/
|
|
1007
|
+
public readonly sessionId: string;
|
|
1008
|
+
|
|
1009
|
+
/**
|
|
1010
|
+
* The run's id.
|
|
1011
|
+
*/
|
|
1012
|
+
public readonly runId: string;
|
|
1013
|
+
|
|
1014
|
+
/**
|
|
1015
|
+
* Creates the exception, whose message names the terminal and the run.
|
|
1016
|
+
*
|
|
1017
|
+
* @param sessionId The session of the run's terminal.
|
|
1018
|
+
* @param runId The run's id.
|
|
1019
|
+
*
|
|
1020
|
+
* @example
|
|
1021
|
+
* ```ts
|
|
1022
|
+
* import { TerminalRunNotFoundException } from "@noldova/terminal/window";
|
|
1023
|
+
*
|
|
1024
|
+
* console.log(new TerminalRunNotFoundException("session-1", "run-1").message);
|
|
1025
|
+
* ```
|
|
1026
|
+
*/
|
|
1027
|
+
public constructor(sessionId: string, runId: string);
|
|
1028
|
+
}
|
|
1029
|
+
|
|
1030
|
+
/**
|
|
1031
|
+
* What an app asks of a terminal it launches with {@link TerminalLauncher.openAsync}, which checks it.
|
|
1032
|
+
*
|
|
1033
|
+
* @example
|
|
1034
|
+
* ```ts
|
|
1035
|
+
* import { TerminalLaunch } from "@noldova/terminal/window";
|
|
1036
|
+
*
|
|
1037
|
+
* const launch = new TerminalLaunch("/work/project", { AGENT_HOME: "/work/agent" }, "Run `agent login` to sign in.", "Sign in");
|
|
1038
|
+
* ```
|
|
1039
|
+
*/
|
|
1040
|
+
export declare class TerminalLaunch {
|
|
1041
|
+
/**
|
|
1042
|
+
* The folder the shell starts in, an absolute path, or `null` for the app's {@link TerminalStartFolder}, else the home folder.
|
|
1043
|
+
*/
|
|
1044
|
+
public readonly folder: string | null;
|
|
1045
|
+
|
|
1046
|
+
/**
|
|
1047
|
+
* The variables laid over the shell's environment, by name.
|
|
1048
|
+
*/
|
|
1049
|
+
public readonly environment: Readonly<Record<string, string>>;
|
|
1050
|
+
|
|
1051
|
+
/**
|
|
1052
|
+
* The lines shown above the shell's first output, or `null` for none.
|
|
1053
|
+
*/
|
|
1054
|
+
public readonly notice: string | null;
|
|
1055
|
+
|
|
1056
|
+
/**
|
|
1057
|
+
* The tab's title, or `null` for the shell's name.
|
|
1058
|
+
*/
|
|
1059
|
+
public readonly title: string | null;
|
|
1060
|
+
|
|
1061
|
+
/**
|
|
1062
|
+
* The command typed into the shell and entered once the shell is ready, as if the person typed it, or `null` for none.
|
|
1063
|
+
*/
|
|
1064
|
+
public readonly command: string | null;
|
|
1065
|
+
|
|
1066
|
+
/**
|
|
1067
|
+
* Whether the terminal gets a tab in the Terminals panel; `false` for one the app shows only in its own page, with {@link EmbeddedTerminal.open}.
|
|
1068
|
+
*/
|
|
1069
|
+
public readonly opensTab: boolean;
|
|
1070
|
+
|
|
1071
|
+
/**
|
|
1072
|
+
* The rows the terminal's tab shows at least while the terminal is open, or `null` for none: as the tab first shows in the bottom dock, the
|
|
1073
|
+
* dock grows, as far as the window allows, until the terminal ends or closes, when the dock goes back to its size unless the person resized it
|
|
1074
|
+
* meanwhile. A tab in a side dock, whose growth would widen it, or among the documents grows nothing.
|
|
1075
|
+
*/
|
|
1076
|
+
public readonly minimumRows: number | null;
|
|
1077
|
+
|
|
1078
|
+
/**
|
|
1079
|
+
* The kinds of shell the terminal may run, or none for any: with kinds, it runs the Default shell setting's shell when that is of them, else the
|
|
1080
|
+
* runtime's default when it is, else the first installed shell of them, as {@link TerminalOwners.runAsync} picks one. An app whose program the
|
|
1081
|
+
* person installed on the host asks for the host's own shells, such as PowerShell and Command Prompt on Windows, so a WSL distribution set as
|
|
1082
|
+
* the Default shell doesn't run its sign-in.
|
|
1083
|
+
*/
|
|
1084
|
+
public readonly shellKinds: readonly TerminalShellKind[];
|
|
1085
|
+
|
|
1086
|
+
/**
|
|
1087
|
+
* Creates the launch, which {@link TerminalLauncher.openAsync} checks rather than the constructor.
|
|
1088
|
+
*
|
|
1089
|
+
* @param folder The starting folder: an absolute path of at most 4,096 UTF-16 code units, or `null` for the start folder.
|
|
1090
|
+
* @param environment The variables: at most 256, each with a portable name (a letter or `_`, then letters, digits or `_`) of at most 256
|
|
1091
|
+
* UTF-16 code units, none of `TERM`, `COLORTERM`, `ZDOTDIR` or a name starting with `NOLDOVA_TERMINAL_`, in any case, no two whose names
|
|
1092
|
+
* differ only in case, each value at most 32,767 UTF-16 code units without a null character, and at most 131,072 UTF-16 code units of names
|
|
1093
|
+
* and values in all; none when left out.
|
|
1094
|
+
* @param notice The notice: `null`, or not blank and at most 4,096 UTF-16 code units, whose line breaks start new lines; `null` when left out.
|
|
1095
|
+
* @param title The tab's title: `null`, or not blank and at most 200 UTF-16 code units; `null` when left out.
|
|
1096
|
+
* @param command The command: `null`, or one line, not blank, of at most 16,384 UTF-16 code units, with no line break, tab or other control
|
|
1097
|
+
* character, since the runtime enters it; `null` when left out. The runtime types it once the shell shows its first prompt, or, for a shell
|
|
1098
|
+
* without Terminal's integration, once its first output has settled for half a second, waiting at most 10 seconds either way; the shell
|
|
1099
|
+
* runs it as the person's own command, so the app passes only commands it means the person to run.
|
|
1100
|
+
* @param opensTab Whether the terminal gets a tab: `false` for a terminal the app shows only in its own page, by passing the launched
|
|
1101
|
+
* terminal's session to {@link EmbeddedTerminal.open}, so the person doesn't see it twice; it runs and ends as a tabbed one does, and the app
|
|
1102
|
+
* ends it with {@link LaunchedTerminal.closeAsync}. `true` when left out.
|
|
1103
|
+
* @param minimumRows The rows the tab shows at least: `null`, or a whole number from 1 to 100, for a program that draws more rows than a short
|
|
1104
|
+
* dock shows, such as a sign-in's list; `null` when left out, and `null` for a launch without a tab.
|
|
1105
|
+
* @param shellKinds The kinds of shell the terminal may run, each one of {@link TerminalShellKind}'s, or none for any; none when left out. With
|
|
1106
|
+
* none of them installed, {@link TerminalLauncher.openAsync} opens nothing and rejects with Noldova Desktop's request error, as for any
|
|
1107
|
+
* failure of the launch in the runtime, not with a {@link TerminalLaunchRefusedException}, since the runtime finds that out.
|
|
1108
|
+
*
|
|
1109
|
+
* @example
|
|
1110
|
+
* ```ts
|
|
1111
|
+
* import { TerminalLaunch } from "@noldova/terminal/window";
|
|
1112
|
+
*
|
|
1113
|
+
* console.log(new TerminalLaunch(null).environment);
|
|
1114
|
+
* ```
|
|
1115
|
+
*/
|
|
1116
|
+
public constructor(folder: string | null, environment?: Readonly<Record<string, string>>, notice?: string | null, title?: string | null,
|
|
1117
|
+
command?: string | null, opensTab?: boolean, minimumRows?: number | null, shellKinds?: readonly TerminalShellKind[]);
|
|
1118
|
+
}
|
|
1119
|
+
|
|
1120
|
+
/**
|
|
1121
|
+
* How a launched terminal's shell ended.
|
|
1122
|
+
*
|
|
1123
|
+
* @example
|
|
1124
|
+
* ```ts
|
|
1125
|
+
* import type { TerminalEnd } from "@noldova/terminal/window";
|
|
1126
|
+
*
|
|
1127
|
+
* function describe(end: TerminalEnd): string {
|
|
1128
|
+
* return end.endedBy === "Exit" ? `exited with ${end.exitCode}` : end.endedBy;
|
|
1129
|
+
* }
|
|
1130
|
+
* ```
|
|
1131
|
+
*/
|
|
1132
|
+
export declare class TerminalEnd {
|
|
1133
|
+
/**
|
|
1134
|
+
* `"Exit"` when the shell exited by itself, `"Close"` when its terminal closed, or when a Restart ended its shell but couldn't start a new
|
|
1135
|
+
* one, or `"Detach"` when the window stopped hearing of it, since the runtime started again and opens no launched terminal again.
|
|
1136
|
+
*/
|
|
1137
|
+
public readonly endedBy: "Exit" | "Close" | "Detach";
|
|
1138
|
+
|
|
1139
|
+
/**
|
|
1140
|
+
* The shell's exit code, or `null` when it has none, as for a `"Detach"`.
|
|
1141
|
+
*/
|
|
1142
|
+
public readonly exitCode: number | null;
|
|
1143
|
+
|
|
1144
|
+
/**
|
|
1145
|
+
* Creates the end.
|
|
1146
|
+
*
|
|
1147
|
+
* @param endedBy How the shell ended.
|
|
1148
|
+
* @param exitCode The exit code, or `null`.
|
|
1149
|
+
*
|
|
1150
|
+
* @example
|
|
1151
|
+
* ```ts
|
|
1152
|
+
* import { TerminalEnd } from "@noldova/terminal/window";
|
|
1153
|
+
*
|
|
1154
|
+
* console.log(new TerminalEnd("Exit", 0).exitCode);
|
|
1155
|
+
* ```
|
|
1156
|
+
*/
|
|
1157
|
+
public constructor(endedBy: "Exit" | "Close" | "Detach", exitCode: number | null);
|
|
1158
|
+
}
|
|
1159
|
+
|
|
1160
|
+
/**
|
|
1161
|
+
* A terminal {@link TerminalLauncher.openAsync} opened.
|
|
1162
|
+
*
|
|
1163
|
+
* @example
|
|
1164
|
+
* ```ts
|
|
1165
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1166
|
+
* import { TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1167
|
+
*
|
|
1168
|
+
* export async function launchShellAsync(context: IWindowPartContext): Promise<void> {
|
|
1169
|
+
* const launched = await TerminalLauncher.openAsync(context, new TerminalLaunch(null));
|
|
1170
|
+
* console.log(launched.sessionId, (await launched.ended).endedBy);
|
|
1171
|
+
* }
|
|
1172
|
+
* ```
|
|
1173
|
+
*/
|
|
1174
|
+
export declare class LaunchedTerminal {
|
|
1175
|
+
/**
|
|
1176
|
+
* The terminal's session.
|
|
1177
|
+
*/
|
|
1178
|
+
public readonly sessionId: string;
|
|
1179
|
+
|
|
1180
|
+
/**
|
|
1181
|
+
* Resolves once, at the terminal's end, and never rejects. A Restart of a running shell doesn't end it, since the tab stays and the new
|
|
1182
|
+
* shell takes the same variables; a Restart after the shell exited starts it again, but `ended` has already resolved.
|
|
1183
|
+
*/
|
|
1184
|
+
public readonly ended: Promise<TerminalEnd>;
|
|
1185
|
+
|
|
1186
|
+
/**
|
|
1187
|
+
* Resolves once, when the launch's own command ({@link TerminalLaunch.command}) ends while the terminal stays open, with that command's exit
|
|
1188
|
+
* code, and never rejects; commands the person types after it don't count. It resolves `null` when the launch has no command, when the
|
|
1189
|
+
* terminal ends first, when the shell has no integration (Command Prompt, fish, WSL) or never took the command, when the person typed into the
|
|
1190
|
+
* terminal before the command went in, when a Restart comes first, or
|
|
1191
|
+
* when the shell gave no code or marked no end for it, as bash doesn't for a subshell such as `(exit 3)`.
|
|
1192
|
+
*
|
|
1193
|
+
* @example
|
|
1194
|
+
* ```ts
|
|
1195
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1196
|
+
* import { TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1197
|
+
*
|
|
1198
|
+
* export async function signInAsync(context: IWindowPartContext): Promise<void> {
|
|
1199
|
+
* const launched = await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, "Sign in", "tool auth login"));
|
|
1200
|
+
* if (await launched.commandEnded === 0)
|
|
1201
|
+
* await launched.closeAsync();
|
|
1202
|
+
* }
|
|
1203
|
+
* ```
|
|
1204
|
+
*/
|
|
1205
|
+
public readonly commandEnded: Promise<number | null>;
|
|
1206
|
+
|
|
1207
|
+
/**
|
|
1208
|
+
* Creates the launched terminal.
|
|
1209
|
+
*
|
|
1210
|
+
* @param sessionId The terminal's session.
|
|
1211
|
+
* @param ended The terminal's end.
|
|
1212
|
+
* @param closeTabAsync Ends the terminal as closing its tab does, for {@link LaunchedTerminal.closeAsync}; {@link TerminalLauncher.openAsync} gives
|
|
1213
|
+
* it, and a terminal made without one closes nothing.
|
|
1214
|
+
* @param commandEnded The launch's command's exit code, for {@link LaunchedTerminal.commandEnded}; {@link TerminalLauncher.openAsync} gives it,
|
|
1215
|
+
* and a terminal made without one resolves `null` at its end.
|
|
1216
|
+
*
|
|
1217
|
+
* @example
|
|
1218
|
+
* ```ts
|
|
1219
|
+
* import { LaunchedTerminal, TerminalEnd } from "@noldova/terminal/window";
|
|
1220
|
+
*
|
|
1221
|
+
* console.log(new LaunchedTerminal("session-1", Promise.resolve(new TerminalEnd("Exit", 0))).sessionId);
|
|
1222
|
+
* ```
|
|
1223
|
+
*/
|
|
1224
|
+
public constructor(sessionId: string, ended: Promise<TerminalEnd>, closeTabAsync?: () => Promise<void>, commandEnded?: Promise<number | null>);
|
|
1225
|
+
|
|
1226
|
+
/**
|
|
1227
|
+
* Ends the terminal as closing its tab does: its tab, when it has one, closes and its shell ends, so {@link LaunchedTerminal.ended} resolves
|
|
1228
|
+
* `"Close"`, as when the app stops what the terminal was for. A terminal launched without a tab ends through the runtime alone.
|
|
1229
|
+
*
|
|
1230
|
+
* @returns A promise that resolves once any tab has closed and the runtime has ended the terminal; for a terminal that already ended, at once,
|
|
1231
|
+
* doing nothing; a close asked while one is under way is that close. A terminal the runtime no longer has, as when the person closed its
|
|
1232
|
+
* tab meanwhile, counts as closed. It rejects with what the runtime rejects with when it fails the close of a terminal it still has.
|
|
1233
|
+
*
|
|
1234
|
+
* @example
|
|
1235
|
+
* ```ts
|
|
1236
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1237
|
+
* import { TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1238
|
+
*
|
|
1239
|
+
* export async function closeSignInAsync(context: IWindowPartContext): Promise<void> {
|
|
1240
|
+
* const launched = await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, "Sign in", "agent login"));
|
|
1241
|
+
* await launched.closeAsync();
|
|
1242
|
+
* console.log((await launched.ended).endedBy);
|
|
1243
|
+
* }
|
|
1244
|
+
* ```
|
|
1245
|
+
*/
|
|
1246
|
+
public closeAsync(): Promise<void>;
|
|
1247
|
+
}
|
|
1248
|
+
|
|
1249
|
+
/**
|
|
1250
|
+
* The base of the exceptions {@link TerminalLauncher.openAsync} throws when it refuses a launch, before anything opens, which a caller
|
|
1251
|
+
* catches to handle any refusal; each refusal is its own subclass.
|
|
1252
|
+
*
|
|
1253
|
+
* @example
|
|
1254
|
+
* ```ts
|
|
1255
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1256
|
+
* import { TerminalLaunch, TerminalLauncher, TerminalLaunchRefusedException } from "@noldova/terminal/window";
|
|
1257
|
+
*
|
|
1258
|
+
* export async function launchWithTermAsync(context: IWindowPartContext): Promise<void> {
|
|
1259
|
+
* try {
|
|
1260
|
+
* await TerminalLauncher.openAsync(context, new TerminalLaunch(null, { TERM: "dumb" }));
|
|
1261
|
+
* }
|
|
1262
|
+
* catch (error) {
|
|
1263
|
+
* console.log(error instanceof TerminalLaunchRefusedException && error.parameter);
|
|
1264
|
+
* }
|
|
1265
|
+
* }
|
|
1266
|
+
* ```
|
|
1267
|
+
*/
|
|
1268
|
+
export declare abstract class TerminalLaunchRefusedException extends TerminalWindowException {
|
|
1269
|
+
/**
|
|
1270
|
+
* `"TerminalLaunchRefusedException"`, which a subclass replaces with its own.
|
|
1271
|
+
*/
|
|
1272
|
+
public override readonly name: string;
|
|
1273
|
+
|
|
1274
|
+
/**
|
|
1275
|
+
* The refused field: `folder`, `environment`, a variable such as `environment.TERM`, `notice`, `title`, `command`, `minimumRows`, a kind
|
|
1276
|
+
* such as `shellKinds.0`, or `context` while the terminal's window part isn't active. The exception never carries a variable's value.
|
|
1277
|
+
*/
|
|
1278
|
+
public abstract readonly parameter: string;
|
|
1279
|
+
|
|
1280
|
+
/**
|
|
1281
|
+
* Creates the exception, for a subclass.
|
|
1282
|
+
*
|
|
1283
|
+
* @param message The message, which says that nothing opened, and why.
|
|
1284
|
+
* @param options The options, such as the error that caused this one.
|
|
1285
|
+
*/
|
|
1286
|
+
protected constructor(message: string, options?: ExceptionOptions);
|
|
1287
|
+
}
|
|
1288
|
+
|
|
1289
|
+
/**
|
|
1290
|
+
* Thrown by {@link TerminalLauncher.openAsync} while Terminal's window part isn't active in the window, before anything opens.
|
|
1291
|
+
*
|
|
1292
|
+
* @example
|
|
1293
|
+
* ```ts
|
|
1294
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1295
|
+
* import { LaunchPartInactiveException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1296
|
+
*
|
|
1297
|
+
* export async function launchInWorkAsync(context: IWindowPartContext): Promise<void> {
|
|
1298
|
+
* try {
|
|
1299
|
+
* await TerminalLauncher.openAsync(context, new TerminalLaunch("/work"));
|
|
1300
|
+
* }
|
|
1301
|
+
* catch (error) {
|
|
1302
|
+
* console.log(error instanceof LaunchPartInactiveException);
|
|
1303
|
+
* }
|
|
1304
|
+
* }
|
|
1305
|
+
* ```
|
|
1306
|
+
*/
|
|
1307
|
+
export declare class LaunchPartInactiveException extends TerminalLaunchRefusedException {
|
|
1308
|
+
/**
|
|
1309
|
+
* `"LaunchPartInactiveException"`.
|
|
1310
|
+
*/
|
|
1311
|
+
public override readonly name: string;
|
|
1312
|
+
|
|
1313
|
+
/**
|
|
1314
|
+
* `"context"`.
|
|
1315
|
+
*/
|
|
1316
|
+
public override readonly parameter: string;
|
|
1317
|
+
|
|
1318
|
+
/**
|
|
1319
|
+
* Creates the exception, whose message says that nothing opened, since the terminal's window part isn't active in the window.
|
|
1320
|
+
*
|
|
1321
|
+
* @example
|
|
1322
|
+
* ```ts
|
|
1323
|
+
* import { LaunchPartInactiveException } from "@noldova/terminal/window";
|
|
1324
|
+
*
|
|
1325
|
+
* console.log(new LaunchPartInactiveException().message);
|
|
1326
|
+
* ```
|
|
1327
|
+
*/
|
|
1328
|
+
public constructor();
|
|
1329
|
+
}
|
|
1330
|
+
|
|
1331
|
+
/**
|
|
1332
|
+
* Thrown by {@link TerminalLauncher.openAsync} when the launch's folder doesn't exist, which it never replaces with another, before anything
|
|
1333
|
+
* opens.
|
|
1334
|
+
*
|
|
1335
|
+
* @example
|
|
1336
|
+
* ```ts
|
|
1337
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1338
|
+
* import { LaunchFolderMissingException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1339
|
+
*
|
|
1340
|
+
* export async function launchInGoneFolderAsync(context: IWindowPartContext): Promise<void> {
|
|
1341
|
+
* try {
|
|
1342
|
+
* await TerminalLauncher.openAsync(context, new TerminalLaunch("/work/gone"));
|
|
1343
|
+
* }
|
|
1344
|
+
* catch (error) {
|
|
1345
|
+
* console.log(error instanceof LaunchFolderMissingException && error.folder);
|
|
1346
|
+
* }
|
|
1347
|
+
* }
|
|
1348
|
+
* ```
|
|
1349
|
+
*/
|
|
1350
|
+
export declare class LaunchFolderMissingException extends TerminalLaunchRefusedException {
|
|
1351
|
+
/**
|
|
1352
|
+
* `"LaunchFolderMissingException"`.
|
|
1353
|
+
*/
|
|
1354
|
+
public override readonly name: string;
|
|
1355
|
+
|
|
1356
|
+
/**
|
|
1357
|
+
* `"folder"`.
|
|
1358
|
+
*/
|
|
1359
|
+
public override readonly parameter: string;
|
|
1360
|
+
|
|
1361
|
+
/**
|
|
1362
|
+
* The folder that doesn't exist.
|
|
1363
|
+
*/
|
|
1364
|
+
public readonly folder: string;
|
|
1365
|
+
|
|
1366
|
+
/**
|
|
1367
|
+
* Creates the exception, whose message says that nothing opened and names the folder.
|
|
1368
|
+
*
|
|
1369
|
+
* @param folder The folder that doesn't exist.
|
|
1370
|
+
*
|
|
1371
|
+
* @example
|
|
1372
|
+
* ```ts
|
|
1373
|
+
* import { LaunchFolderMissingException } from "@noldova/terminal/window";
|
|
1374
|
+
*
|
|
1375
|
+
* console.log(new LaunchFolderMissingException("/work/gone").message);
|
|
1376
|
+
* ```
|
|
1377
|
+
*/
|
|
1378
|
+
public constructor(folder: string);
|
|
1379
|
+
}
|
|
1380
|
+
|
|
1381
|
+
/**
|
|
1382
|
+
* Thrown by {@link TerminalLauncher.openAsync} when the launch's title is blank or longer than its limit, before anything opens.
|
|
1383
|
+
*
|
|
1384
|
+
* @example
|
|
1385
|
+
* ```ts
|
|
1386
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1387
|
+
* import { LaunchTitleRefusedException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1388
|
+
*
|
|
1389
|
+
* export async function launchWithBlankTitleAsync(context: IWindowPartContext): Promise<void> {
|
|
1390
|
+
* try {
|
|
1391
|
+
* await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, " "));
|
|
1392
|
+
* }
|
|
1393
|
+
* catch (error) {
|
|
1394
|
+
* console.log(error instanceof LaunchTitleRefusedException && error.maximumLength);
|
|
1395
|
+
* }
|
|
1396
|
+
* }
|
|
1397
|
+
* ```
|
|
1398
|
+
*/
|
|
1399
|
+
export declare class LaunchTitleRefusedException extends TerminalLaunchRefusedException {
|
|
1400
|
+
/**
|
|
1401
|
+
* `"LaunchTitleRefusedException"`.
|
|
1402
|
+
*/
|
|
1403
|
+
public override readonly name: string;
|
|
1404
|
+
|
|
1405
|
+
/**
|
|
1406
|
+
* `"title"`.
|
|
1407
|
+
*/
|
|
1408
|
+
public override readonly parameter: string;
|
|
1409
|
+
|
|
1410
|
+
/**
|
|
1411
|
+
* The most characters a title has, `200`.
|
|
1412
|
+
*/
|
|
1413
|
+
public readonly maximumLength: number;
|
|
1414
|
+
|
|
1415
|
+
/**
|
|
1416
|
+
* Creates the exception, whose message says that nothing opened and gives the title's rule.
|
|
1417
|
+
*
|
|
1418
|
+
* @param maximumLength The most characters a title has.
|
|
1419
|
+
*
|
|
1420
|
+
* @example
|
|
1421
|
+
* ```ts
|
|
1422
|
+
* import { LaunchTitleRefusedException } from "@noldova/terminal/window";
|
|
1423
|
+
*
|
|
1424
|
+
* console.log(new LaunchTitleRefusedException(200).message);
|
|
1425
|
+
* ```
|
|
1426
|
+
*/
|
|
1427
|
+
public constructor(maximumLength: number);
|
|
1428
|
+
}
|
|
1429
|
+
|
|
1430
|
+
/**
|
|
1431
|
+
* Thrown by {@link TerminalLauncher.openAsync} when the launch's minimum rows aren't a whole number from 1 to their limit, before anything
|
|
1432
|
+
* opens.
|
|
1433
|
+
*
|
|
1434
|
+
* @example
|
|
1435
|
+
* ```ts
|
|
1436
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1437
|
+
* import { LaunchRowsRefusedException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1438
|
+
*
|
|
1439
|
+
* export async function launchWithNoRowsAsync(context: IWindowPartContext): Promise<void> {
|
|
1440
|
+
* try {
|
|
1441
|
+
* await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, null, null, true, 0));
|
|
1442
|
+
* }
|
|
1443
|
+
* catch (error) {
|
|
1444
|
+
* console.log(error instanceof LaunchRowsRefusedException && error.maximum);
|
|
1445
|
+
* }
|
|
1446
|
+
* }
|
|
1447
|
+
* ```
|
|
1448
|
+
*/
|
|
1449
|
+
export declare class LaunchRowsRefusedException extends TerminalLaunchRefusedException {
|
|
1450
|
+
/**
|
|
1451
|
+
* `"LaunchRowsRefusedException"`.
|
|
1452
|
+
*/
|
|
1453
|
+
public override readonly name: string;
|
|
1454
|
+
|
|
1455
|
+
/**
|
|
1456
|
+
* `"minimumRows"`.
|
|
1457
|
+
*/
|
|
1458
|
+
public override readonly parameter: string;
|
|
1459
|
+
|
|
1460
|
+
/**
|
|
1461
|
+
* The most minimum rows a launch asks for, `100`.
|
|
1462
|
+
*/
|
|
1463
|
+
public readonly maximum: number;
|
|
1464
|
+
|
|
1465
|
+
/**
|
|
1466
|
+
* Creates the exception, whose message says that nothing opened and gives the rows' range.
|
|
1467
|
+
*
|
|
1468
|
+
* @param maximum The most minimum rows a launch asks for.
|
|
1469
|
+
*
|
|
1470
|
+
* @example
|
|
1471
|
+
* ```ts
|
|
1472
|
+
* import { LaunchRowsRefusedException } from "@noldova/terminal/window";
|
|
1473
|
+
*
|
|
1474
|
+
* console.log(new LaunchRowsRefusedException(100).message);
|
|
1475
|
+
* ```
|
|
1476
|
+
*/
|
|
1477
|
+
public constructor(maximum: number);
|
|
1478
|
+
}
|
|
1479
|
+
|
|
1480
|
+
/**
|
|
1481
|
+
* Thrown by {@link TerminalLauncher.openAsync} when a launch without a tab asks for minimum rows, which only its tab takes; an embedded
|
|
1482
|
+
* terminal takes its rows from {@link EmbeddedTerminal.open}.
|
|
1483
|
+
*
|
|
1484
|
+
* @example
|
|
1485
|
+
* ```ts
|
|
1486
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1487
|
+
* import { LaunchRowsWithoutTabException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1488
|
+
*
|
|
1489
|
+
* export async function launchRowsWithoutTabAsync(context: IWindowPartContext): Promise<void> {
|
|
1490
|
+
* try {
|
|
1491
|
+
* await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, null, null, false, 10));
|
|
1492
|
+
* }
|
|
1493
|
+
* catch (error) {
|
|
1494
|
+
* console.log(error instanceof LaunchRowsWithoutTabException);
|
|
1495
|
+
* }
|
|
1496
|
+
* }
|
|
1497
|
+
* ```
|
|
1498
|
+
*/
|
|
1499
|
+
export declare class LaunchRowsWithoutTabException extends TerminalLaunchRefusedException {
|
|
1500
|
+
/**
|
|
1501
|
+
* `"LaunchRowsWithoutTabException"`.
|
|
1502
|
+
*/
|
|
1503
|
+
public override readonly name: string;
|
|
1504
|
+
|
|
1505
|
+
/**
|
|
1506
|
+
* `"minimumRows"`.
|
|
1507
|
+
*/
|
|
1508
|
+
public override readonly parameter: string;
|
|
1509
|
+
|
|
1510
|
+
/**
|
|
1511
|
+
* Creates the exception, whose message says that nothing opened, since minimum rows need the launch's tab.
|
|
1512
|
+
*
|
|
1513
|
+
* @example
|
|
1514
|
+
* ```ts
|
|
1515
|
+
* import { LaunchRowsWithoutTabException } from "@noldova/terminal/window";
|
|
1516
|
+
*
|
|
1517
|
+
* console.log(new LaunchRowsWithoutTabException().message);
|
|
1518
|
+
* ```
|
|
1519
|
+
*/
|
|
1520
|
+
public constructor();
|
|
1521
|
+
}
|
|
1522
|
+
|
|
1523
|
+
/**
|
|
1524
|
+
* Thrown by {@link TerminalLauncher.openAsync} when it refuses one of the launch's fields under the rules of {@link TerminalLaunch}'s
|
|
1525
|
+
* constructor, such as a relative folder, a variable's name or the command, before anything opens.
|
|
1526
|
+
*
|
|
1527
|
+
* @example
|
|
1528
|
+
* ```ts
|
|
1529
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1530
|
+
* import { LaunchArgumentRefusedException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1531
|
+
*
|
|
1532
|
+
* export async function launchInRelativeFolderAsync(context: IWindowPartContext): Promise<void> {
|
|
1533
|
+
* try {
|
|
1534
|
+
* await TerminalLauncher.openAsync(context, new TerminalLaunch("work"));
|
|
1535
|
+
* }
|
|
1536
|
+
* catch (error) {
|
|
1537
|
+
* console.log(error instanceof LaunchArgumentRefusedException && error.parameter);
|
|
1538
|
+
* }
|
|
1539
|
+
* }
|
|
1540
|
+
* ```
|
|
1541
|
+
*/
|
|
1542
|
+
export declare class LaunchArgumentRefusedException extends TerminalLaunchRefusedException {
|
|
1543
|
+
/**
|
|
1544
|
+
* `"LaunchArgumentRefusedException"`.
|
|
1545
|
+
*/
|
|
1546
|
+
public override readonly name: string;
|
|
1547
|
+
|
|
1548
|
+
/**
|
|
1549
|
+
* The refused field: `folder`, `environment`, a variable such as `environment.TERM`, `notice`, `command`, or a kind such as `shellKinds.0`.
|
|
1550
|
+
*/
|
|
1551
|
+
public override readonly parameter: string;
|
|
1552
|
+
|
|
1553
|
+
/**
|
|
1554
|
+
* Why the field is refused, such as "Expected an absolute path."; it never holds a variable's value.
|
|
1555
|
+
*/
|
|
1556
|
+
public readonly reason: string;
|
|
1557
|
+
|
|
1558
|
+
/**
|
|
1559
|
+
* Creates the exception, whose message says that nothing opened, and gives the reason.
|
|
1560
|
+
*
|
|
1561
|
+
* @param parameterName The refused field.
|
|
1562
|
+
* @param reason Why it is refused.
|
|
1563
|
+
*
|
|
1564
|
+
* @example
|
|
1565
|
+
* ```ts
|
|
1566
|
+
* import { LaunchArgumentRefusedException } from "@noldova/terminal/window";
|
|
1567
|
+
*
|
|
1568
|
+
* console.log(new LaunchArgumentRefusedException("folder", "Expected an absolute path.").message);
|
|
1569
|
+
* ```
|
|
1570
|
+
*/
|
|
1571
|
+
public constructor(parameterName: string, reason: string);
|
|
1572
|
+
}
|
|
1573
|
+
|
|
1574
|
+
/**
|
|
1575
|
+
* Opens terminals for an app: a terminal with the app's variables laid over the shell's environment and its notice shown above the shell's
|
|
1576
|
+
* first output, in a tab like the person's own or, when the launch asks for no tab, only in the app's own page, that tells the app when its
|
|
1577
|
+
* shell ends.
|
|
1578
|
+
*
|
|
1579
|
+
* @remarks
|
|
1580
|
+
* Nothing runs without the person: the notice says what to run, and nothing is typed into the shell. A launched terminal has no owner, isn't
|
|
1581
|
+
* the panel's, and isn't kept for the next run. The variables lie over the environment the shell starts from, under the shell integration's
|
|
1582
|
+
* own; on Windows a variable replaces the one whose name matches in any case. Their values are never logged, saved or restored: the runtime
|
|
1583
|
+
* holds them in memory only while the terminal is open, so that a Restart from its tab starts the shell with them again. The title is the
|
|
1584
|
+
* tab's, and isn't stored either, so after a reload the tab shows the shell's name. A terminal launched without a tab has none in any window,
|
|
1585
|
+
* even after a reload, and ends when the window that launched it closes or reloads, or when the app's connection closes; the app closes it with
|
|
1586
|
+
* {@link LaunchedTerminal.closeAsync} once it no longer shows it.
|
|
1587
|
+
*/
|
|
1588
|
+
export declare class TerminalLauncher {
|
|
1589
|
+
/**
|
|
1590
|
+
* Launches a terminal and opens its tab, unless the launch asks for none.
|
|
1591
|
+
*
|
|
1592
|
+
* @param context The calling app part's context, which makes the request; the app's module depends on the terminal module.
|
|
1593
|
+
* @param request The launch.
|
|
1594
|
+
* @returns A promise of the launched terminal, once its tab has opened, or with no tab when the launch asks for none or Terminal's window
|
|
1595
|
+
* part stopped while the runtime launched it.
|
|
1596
|
+
* @throws {@link TerminalLaunchRefusedException} Before anything opens, when the launch breaks a rule of {@link TerminalLaunch}'s
|
|
1597
|
+
* constructor, its folder no longer exists, which it never replaces with another, or the terminal's window part isn't active; the promise
|
|
1598
|
+
* rejects with what the runtime rejects with when it fails the launch.
|
|
1599
|
+
*
|
|
1600
|
+
* @example
|
|
1601
|
+
* ```ts
|
|
1602
|
+
* import type { IWindowPartContext } from "@noldova/desktop.window";
|
|
1603
|
+
* import { TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
|
|
1604
|
+
*
|
|
1605
|
+
* export async function launchSignInAsync(context: IWindowPartContext): Promise<void> {
|
|
1606
|
+
* const launched = await TerminalLauncher.openAsync(context, new TerminalLaunch("/work/project", { AGENT_HOME: "/work/agent" },
|
|
1607
|
+
* "Run `agent login` to sign in.", "Sign in"));
|
|
1608
|
+
* const end = await launched.ended;
|
|
1609
|
+
* console.log(end.endedBy, end.exitCode);
|
|
1610
|
+
* }
|
|
1611
|
+
* ```
|
|
1612
|
+
*/
|
|
1613
|
+
public static openAsync(context: IWindowPartContext, request: TerminalLaunch): Promise<LaunchedTerminal>;
|
|
1614
|
+
}
|
|
1615
|
+
|
|
1616
|
+
/**
|
|
1617
|
+
* Thrown by {@link EmbeddedTerminal.open} and {@link EmbeddedTerminal.setMaximumRows} for rows that aren't a whole number from 1 to 1,000.
|
|
1618
|
+
*
|
|
1619
|
+
* @example
|
|
1620
|
+
* ```ts
|
|
1621
|
+
* import type { EnvironmentInjector } from "@angular/core";
|
|
1622
|
+
* import { EmbeddedRowsRefusedException, EmbeddedTerminal } from "@noldova/terminal/window";
|
|
1623
|
+
*
|
|
1624
|
+
* export function openWithNoRows(sessionId: string, environmentInjector: EnvironmentInjector): void {
|
|
1625
|
+
* try {
|
|
1626
|
+
* EmbeddedTerminal.open(sessionId, environmentInjector, 0);
|
|
1627
|
+
* }
|
|
1628
|
+
* catch (error) {
|
|
1629
|
+
* console.log(error instanceof EmbeddedRowsRefusedException && error.rows);
|
|
1630
|
+
* }
|
|
1631
|
+
* }
|
|
1632
|
+
* ```
|
|
1633
|
+
*/
|
|
1634
|
+
export declare class EmbeddedRowsRefusedException extends TerminalWindowException {
|
|
1635
|
+
/**
|
|
1636
|
+
* `"EmbeddedRowsRefusedException"`.
|
|
1637
|
+
*/
|
|
1638
|
+
public override readonly name: string;
|
|
1639
|
+
|
|
1640
|
+
/**
|
|
1641
|
+
* The rows asked for.
|
|
1642
|
+
*/
|
|
1643
|
+
public readonly rows: number;
|
|
1644
|
+
|
|
1645
|
+
/**
|
|
1646
|
+
* The fewest rows an embedded terminal takes, `1`.
|
|
1647
|
+
*/
|
|
1648
|
+
public readonly minimum: number;
|
|
1649
|
+
|
|
1650
|
+
/**
|
|
1651
|
+
* The most rows an embedded terminal takes, `1000`.
|
|
1652
|
+
*/
|
|
1653
|
+
public readonly maximum: number;
|
|
1654
|
+
|
|
1655
|
+
/**
|
|
1656
|
+
* Creates the exception, whose message gives the range and the rows asked for.
|
|
1657
|
+
*
|
|
1658
|
+
* @param rows The rows asked for.
|
|
1659
|
+
* @param minimum The fewest rows an embedded terminal takes.
|
|
1660
|
+
* @param maximum The most rows an embedded terminal takes.
|
|
1661
|
+
*
|
|
1662
|
+
* @example
|
|
1663
|
+
* ```ts
|
|
1664
|
+
* import { EmbeddedRowsRefusedException } from "@noldova/terminal/window";
|
|
1665
|
+
*
|
|
1666
|
+
* console.log(new EmbeddedRowsRefusedException(0, 1, 1000).message);
|
|
1667
|
+
* ```
|
|
1668
|
+
*/
|
|
1669
|
+
public constructor(rows: number, minimum: number, maximum: number);
|
|
1670
|
+
}
|
|
1671
|
+
|
|
1672
|
+
/**
|
|
1673
|
+
* Thrown by {@link EmbeddedTerminal.open} while Terminal's window part isn't active in the window.
|
|
1674
|
+
*
|
|
1675
|
+
* @example
|
|
1676
|
+
* ```ts
|
|
1677
|
+
* import type { EnvironmentInjector } from "@angular/core";
|
|
1678
|
+
* import { EmbeddedTerminal, TerminalNotActiveException } from "@noldova/terminal/window";
|
|
1679
|
+
*
|
|
1680
|
+
* export function openEmbedded(sessionId: string, environmentInjector: EnvironmentInjector): void {
|
|
1681
|
+
* try {
|
|
1682
|
+
* EmbeddedTerminal.open(sessionId, environmentInjector, 15);
|
|
1683
|
+
* }
|
|
1684
|
+
* catch (error) {
|
|
1685
|
+
* console.log(error instanceof TerminalNotActiveException);
|
|
1686
|
+
* }
|
|
1687
|
+
* }
|
|
1688
|
+
* ```
|
|
1689
|
+
*/
|
|
1690
|
+
export declare class TerminalNotActiveException extends TerminalWindowException {
|
|
1691
|
+
/**
|
|
1692
|
+
* `"TerminalNotActiveException"`.
|
|
1693
|
+
*/
|
|
1694
|
+
public override readonly name: string;
|
|
1695
|
+
|
|
1696
|
+
/**
|
|
1697
|
+
* Creates the exception, whose message says that Terminal isn't active in the window.
|
|
1698
|
+
*
|
|
1699
|
+
* @example
|
|
1700
|
+
* ```ts
|
|
1701
|
+
* import { TerminalNotActiveException } from "@noldova/terminal/window";
|
|
1702
|
+
*
|
|
1703
|
+
* console.log(new TerminalNotActiveException().message);
|
|
1704
|
+
* ```
|
|
1705
|
+
*/
|
|
1706
|
+
public constructor();
|
|
1707
|
+
}
|
|
1708
|
+
|
|
1709
|
+
/**
|
|
1710
|
+
* A live terminal session an app shows in its own page, such as under the code block whose commands ran in it: Terminal's own pane, with its
|
|
1711
|
+
* keys, links, look and snapshot, in an element the app places and may move between hosts without the session reopening.
|
|
1712
|
+
*
|
|
1713
|
+
* @remarks
|
|
1714
|
+
* Its shell gets the element's width in columns and the rows the app asks for, while the element is only as tall as the rows drawn so far,
|
|
1715
|
+
* from the screen's top to the cursor's row, up to those rows; past them its terminal scrolls. A shell has one size, so within a window the
|
|
1716
|
+
* session's shown pane the person focused last sizes it, else the shown pane opened last, the element or a terminal tab or panel of the
|
|
1717
|
+
* session, so the element opening leaves the size with a pane the person has focused until {@link EmbeddedTerminal.focus}; the others draw at that size,
|
|
1718
|
+
* clipped or with blank space, and the element shows the last rows drawn when more are drawn than it shows. It never takes the focus as it
|
|
1719
|
+
* opens. Disposing of it detaches it from the session, which stays open.
|
|
1720
|
+
*/
|
|
1721
|
+
export declare class EmbeddedTerminal {
|
|
1722
|
+
/**
|
|
1723
|
+
* The element the app places in its page.
|
|
1724
|
+
*/
|
|
1725
|
+
public readonly element: HTMLElement;
|
|
1726
|
+
|
|
1727
|
+
/**
|
|
1728
|
+
* The rows the element shows, from 1 up to the rows the app asked for, all of them while a full-screen program has the alternate screen.
|
|
1729
|
+
*/
|
|
1730
|
+
public readonly rows: Signal<number>;
|
|
1731
|
+
|
|
1732
|
+
/**
|
|
1733
|
+
* Whether a full-screen program, such as an editor or a pager, has the alternate screen.
|
|
1734
|
+
*/
|
|
1735
|
+
public readonly isFullScreen: Signal<boolean>;
|
|
1736
|
+
|
|
1737
|
+
/**
|
|
1738
|
+
* Whether the session's shell ended; the element then keeps its last screen and takes no typing.
|
|
1739
|
+
*/
|
|
1740
|
+
public readonly hasEnded: Signal<boolean>;
|
|
1741
|
+
|
|
1742
|
+
/**
|
|
1743
|
+
* A row's height in CSS pixels, 0 until the pane has shown; it follows the pane as it draws or resizes, such as when the font size changes.
|
|
1744
|
+
* The element is taller than its rows by its inset, so an app counts the rows its page has room for with this rather than the element's
|
|
1745
|
+
* height.
|
|
1746
|
+
*
|
|
1747
|
+
* @example
|
|
1748
|
+
* ```ts
|
|
1749
|
+
* import type { EmbeddedTerminal } from "@noldova/terminal/window";
|
|
1750
|
+
*
|
|
1751
|
+
* export function fitRows(embedded: EmbeddedTerminal, historyHeight: number): void {
|
|
1752
|
+
* const height = embedded.rowHeight();
|
|
1753
|
+
* if (height > 0)
|
|
1754
|
+
* embedded.setMaximumRows(Math.max(1, Math.min(15, Math.floor(historyHeight / 2 / height))));
|
|
1755
|
+
* }
|
|
1756
|
+
* ```
|
|
1757
|
+
*/
|
|
1758
|
+
public readonly rowHeight: Signal<number>;
|
|
1759
|
+
|
|
1760
|
+
private constructor();
|
|
1761
|
+
|
|
1762
|
+
/**
|
|
1763
|
+
* Opens a pane of the session in a new element, shown.
|
|
1764
|
+
*
|
|
1765
|
+
* @param sessionId The session, such as the one {@link TerminalOwners.runAsync} gives.
|
|
1766
|
+
* @param injector The app's environment injector, which gives the window's services, such as its clipboard.
|
|
1767
|
+
* @param maximumRows The rows the shell gets, a whole number from 1 to 1,000.
|
|
1768
|
+
* @returns The embedded terminal, whose element the app places.
|
|
1769
|
+
* @throws {@link TerminalNotActiveException} While Terminal's window part isn't active in the window.
|
|
1770
|
+
* @throws {@link EmbeddedRowsRefusedException} For rows outside 1 to 1,000, or not a whole number.
|
|
1771
|
+
*
|
|
1772
|
+
* @example
|
|
1773
|
+
* ```ts
|
|
1774
|
+
* import type { EnvironmentInjector } from "@angular/core";
|
|
1775
|
+
* import { EmbeddedTerminal } from "@noldova/terminal/window";
|
|
1776
|
+
*
|
|
1777
|
+
* export function showEmbedded(sessionId: string, environmentInjector: EnvironmentInjector, host: HTMLElement): EmbeddedTerminal {
|
|
1778
|
+
* const embedded = EmbeddedTerminal.open(sessionId, environmentInjector, 15);
|
|
1779
|
+
* host.append(embedded.element);
|
|
1780
|
+
* embedded.focus();
|
|
1781
|
+
* return embedded;
|
|
1782
|
+
* }
|
|
1783
|
+
* ```
|
|
1784
|
+
*/
|
|
1785
|
+
public static open(sessionId: string, injector: EnvironmentInjector, maximumRows: number): EmbeddedTerminal;
|
|
1786
|
+
|
|
1787
|
+
/**
|
|
1788
|
+
* Gives its shell other rows, such as when the app's page changes height; fewer rows than are drawn shrink the element, and its terminal
|
|
1789
|
+
* scrolls inside.
|
|
1790
|
+
*
|
|
1791
|
+
* @param rows The rows the shell gets, a whole number from 1 to 1,000.
|
|
1792
|
+
* @throws {@link EmbeddedRowsRefusedException} For rows outside 1 to 1,000, or not a whole number; the shell keeps its rows.
|
|
1793
|
+
*
|
|
1794
|
+
* @example
|
|
1795
|
+
* ```ts
|
|
1796
|
+
* import type { EmbeddedTerminal } from "@noldova/terminal/window";
|
|
1797
|
+
*
|
|
1798
|
+
* export function fitToHistory(embedded: EmbeddedTerminal, historyRows: number): void {
|
|
1799
|
+
* embedded.setMaximumRows(Math.min(15, Math.floor(historyRows / 2)));
|
|
1800
|
+
* }
|
|
1801
|
+
* ```
|
|
1802
|
+
*/
|
|
1803
|
+
public setMaximumRows(rows: number): void;
|
|
1804
|
+
|
|
1805
|
+
/**
|
|
1806
|
+
* Stops or starts its drawing, such as while the app keeps the element out of its page; a hidden element leaves sizing the shell to another
|
|
1807
|
+
* shown pane of the session, while one taken out of the page and not hidden still counts as shown.
|
|
1808
|
+
*
|
|
1809
|
+
* @param shown Whether it draws.
|
|
1810
|
+
*
|
|
1811
|
+
* @example
|
|
1812
|
+
* ```ts
|
|
1813
|
+
* import type { EmbeddedTerminal } from "@noldova/terminal/window";
|
|
1814
|
+
*
|
|
1815
|
+
* export function followPageVisibility(embedded: EmbeddedTerminal): void {
|
|
1816
|
+
* embedded.setShown(!document.hidden);
|
|
1817
|
+
* }
|
|
1818
|
+
* ```
|
|
1819
|
+
*/
|
|
1820
|
+
public setShown(shown: boolean): void;
|
|
1821
|
+
|
|
1822
|
+
/**
|
|
1823
|
+
* Moves the focus into its terminal, so the person's keys reach the shell; one hidden or still loading takes it once it shows with its
|
|
1824
|
+
* terminal.
|
|
1825
|
+
*
|
|
1826
|
+
* @example
|
|
1827
|
+
* ```ts
|
|
1828
|
+
* import type { EmbeddedTerminal } from "@noldova/terminal/window";
|
|
1829
|
+
*
|
|
1830
|
+
* export function focusOnRun(embedded: EmbeddedTerminal, runButton: HTMLButtonElement): void {
|
|
1831
|
+
* runButton.addEventListener("click", () => embedded.focus());
|
|
1832
|
+
* }
|
|
1833
|
+
* ```
|
|
1834
|
+
*/
|
|
1835
|
+
public focus(): void;
|
|
1836
|
+
|
|
1837
|
+
/**
|
|
1838
|
+
* Detaches it from the session, which stays open, and removes its element from the page.
|
|
1839
|
+
*
|
|
1840
|
+
* @example
|
|
1841
|
+
* ```ts
|
|
1842
|
+
* import type { EmbeddedTerminal } from "@noldova/terminal/window";
|
|
1843
|
+
*
|
|
1844
|
+
* export function removeEmbedded(embedded: EmbeddedTerminal): void {
|
|
1845
|
+
* embedded.dispose();
|
|
1846
|
+
* }
|
|
1847
|
+
* ```
|
|
1848
|
+
*/
|
|
1849
|
+
public dispose(): void;
|
|
1850
|
+
}
|