@awebai/oats 0.51.0 → 0.52.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/bin/oats.mjs +109 -37
- package/docs/capabilities.md +9 -2
- package/docs/configuration.md +134 -88
- package/docs/desktop-cli-api.md +927 -92
- package/docs/desktop-instance-start.md +56 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +144 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +66 -9
- package/docs/integrations.md +9 -8
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +15 -5
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/schedules.md +91 -4
- package/docs/souls-and-instances.md +95 -25
- package/docs/tui.md +152 -0
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +186 -46
- package/lib/core.mjs +730 -185
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-inspect.mjs +40 -11
- package/lib/instance-lifecycle.mjs +169 -47
- package/lib/launch-preference.mjs +16 -0
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/schedule-host.mjs +154 -22
- package/lib/schedule.mjs +73 -24
- package/lib/system-tools.mjs +39 -0
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +5 -11
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +3 -3
- package/package.json +7 -2
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +548 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +68 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +34 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +142 -0
- package/packages/client/deployment-read-cli.mjs +53 -0
- package/packages/client/display-text.mjs +44 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +54 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +74 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +22 -0
- package/packages/client/instance-tree.mjs +453 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +165 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +372 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +35 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +286 -0
- package/packages/client/readiness-contract.mjs +172 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +126 -0
- package/packages/client/remote-roster.mjs +67 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +183 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +119 -0
- package/packages/client/spawn-preview-cli.mjs +32 -0
- package/packages/client/spawn-preview-contract.mjs +314 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +147 -0
- package/packages/tui/README.md +46 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +29 -0
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/main.mjs +105 -0
- package/packages/tui/lib/term/keys.mjs +323 -0
- package/packages/tui/lib/term/screen.mjs +122 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +49 -0
- package/packages/tui/lib/term/tty.mjs +168 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/frame.mjs +62 -0
- package/packages/tui/lib/views/help.mjs +28 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +29 -22
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
/** The key parser of `oats tui`: raw terminal input bytes in, key events out.
|
|
2
|
+
* Pure: no IO, no timers, no imports; the only clock is the injected `now`.
|
|
3
|
+
* It reads escape sequences and never writes one.
|
|
4
|
+
*
|
|
5
|
+
* Events are plain objects of exactly three shapes:
|
|
6
|
+
* a named key { name, ctrl, alt, shift }
|
|
7
|
+
* a grapheme { text } or { text, alt: true }
|
|
8
|
+
* a paste { paste } or { paste: "", truncated: true } */
|
|
9
|
+
|
|
10
|
+
export const ESC_TIMEOUT_MS = 50;
|
|
11
|
+
export const PASTE_LIMIT = 1024 * 1024;
|
|
12
|
+
export const PASTE_PAUSE_MS = 1000;
|
|
13
|
+
|
|
14
|
+
/** Parameter and intermediate bytes held for one CSI or SS3. A longer sequence
|
|
15
|
+
* is discarded as it streams: input can never grow the parser. */
|
|
16
|
+
const SEQUENCE_LIMIT = 64;
|
|
17
|
+
const ESC = 0x1b;
|
|
18
|
+
const PASTE_END = Uint8Array.of(ESC, 0x5b, 0x32, 0x30, 0x31, 0x7e); // CSI 201 ~
|
|
19
|
+
|
|
20
|
+
const GROUND = 0, ESCAPE = 1, CSI = 2, SS3 = 3, LINUX = 4, MOUSE = 5, STRING = 6, STRING_ESC = 7, PASTE = 8;
|
|
21
|
+
|
|
22
|
+
const LETTER_KEYS = Object.freeze({
|
|
23
|
+
__proto__: null,
|
|
24
|
+
A: "up", B: "down", C: "right", D: "left", H: "home", F: "end", P: "f1", Q: "f2", R: "f3", S: "f4",
|
|
25
|
+
});
|
|
26
|
+
const TILDE_KEYS = Object.freeze({
|
|
27
|
+
__proto__: null,
|
|
28
|
+
1: "home", 7: "home", 4: "end", 8: "end", 2: "insert", 3: "delete", 5: "pageup", 6: "pagedown",
|
|
29
|
+
11: "f1", 12: "f2", 13: "f3", 14: "f4", 15: "f5", 17: "f6", 18: "f7", 19: "f8", 20: "f9", 21: "f10", 23: "f11", 24: "f12",
|
|
30
|
+
});
|
|
31
|
+
/** The Linux console sends F1..F5 as `ESC [ [ A` .. `ESC [ [ E`. */
|
|
32
|
+
const LINUX_KEYS = Object.freeze({ __proto__: null, A: "f1", B: "f2", C: "f3", D: "f4", E: "f5" });
|
|
33
|
+
const KEY_PARAMS = /^\d*(?:;\d*)?$/;
|
|
34
|
+
const GRAPHEMES = new Intl.Segmenter("en", { granularity: "grapheme" });
|
|
35
|
+
|
|
36
|
+
const named = (name, ctrl = false, alt = false, shift = false) => ({ name, ctrl, alt, shift });
|
|
37
|
+
|
|
38
|
+
/** The key of a C0 byte or DEL, or null for a byte that is no key (NUL, 0x1c..0x1f). */
|
|
39
|
+
function c0Key(b) {
|
|
40
|
+
if (b === 0x0d || b === 0x0a) return named("enter");
|
|
41
|
+
if (b === 0x09) return named("tab");
|
|
42
|
+
if (b === 0x7f || b === 0x08) return named("backspace");
|
|
43
|
+
return b >= 0x01 && b <= 0x1a ? named(String.fromCharCode(b + 0x60), true) : null;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** xterm's modifier parameter: m - 1 is a bit mask (1 shift, 2 alt, 4 ctrl, 8 meta,
|
|
47
|
+
* ignored). A value outside 1..16 is no key report, so the sequence is dropped:
|
|
48
|
+
* that keeps most cursor position reports (`CSI row ; col R`) from reading as F3. */
|
|
49
|
+
function modified(name, param, shift = false) {
|
|
50
|
+
const m = param === "" ? 1 : Number(param);
|
|
51
|
+
if (!(m >= 1 && m <= 16)) return null;
|
|
52
|
+
return named(name, ((m - 1) & 4) !== 0, ((m - 1) & 2) !== 0, shift || ((m - 1) & 1) !== 0);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** A complete CSI as a key, or null when it is not one (then it is dropped whole).
|
|
56
|
+
* Only `CSI [n] [; m] final` is a key: a private marker, an intermediate or a
|
|
57
|
+
* third parameter makes it a terminal report. */
|
|
58
|
+
function csiKey(params, final) {
|
|
59
|
+
if (params === null || !KEY_PARAMS.test(params)) return null;
|
|
60
|
+
const [first, mod = ""] = params.split(";");
|
|
61
|
+
if (final === "~") return TILDE_KEYS[Number(first)] ? modified(TILDE_KEYS[Number(first)], mod) : null;
|
|
62
|
+
if (first !== "" && Number(first) !== 1) return null;
|
|
63
|
+
if (final === "Z") return modified("tab", mod, true);
|
|
64
|
+
return LETTER_KEYS[final] ? modified(LETTER_KEYS[final], mod) : null;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** `ESC O X`, and the modifier forms `ESC O m X` and `ESC O 1 ; m X`. */
|
|
68
|
+
function ss3Key(params, final) {
|
|
69
|
+
if (params === null || !KEY_PARAMS.test(params) || !LETTER_KEYS[final]) return null;
|
|
70
|
+
return modified(LETTER_KEYS[final], params.slice(params.lastIndexOf(";") + 1));
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const MORE = -1, BAD = -2, RETRY = -3;
|
|
74
|
+
|
|
75
|
+
/** A streaming UTF-8 decoder (the WHATWG algorithm: no overlong form, no surrogate,
|
|
76
|
+
* nothing above U+10FFFF). `push` returns a code point, MORE when the character is
|
|
77
|
+
* incomplete, BAD for a byte that is not UTF-8, or RETRY when the byte ended an
|
|
78
|
+
* incomplete character: that character is invalid and the byte must be offered again. */
|
|
79
|
+
function utf8Decoder() {
|
|
80
|
+
let need = 0, cp = 0, lo = 0x80, hi = 0xbf;
|
|
81
|
+
return {
|
|
82
|
+
get pending() { return need > 0; },
|
|
83
|
+
push(b) {
|
|
84
|
+
if (need === 0) {
|
|
85
|
+
if (b < 0x80) return b;
|
|
86
|
+
if (b >= 0xc2 && b <= 0xdf) { need = 1; cp = b & 0x1f; }
|
|
87
|
+
else if (b >= 0xe0 && b <= 0xef) { need = 2; cp = b & 0x0f; if (b === 0xe0) lo = 0xa0; else if (b === 0xed) hi = 0x9f; }
|
|
88
|
+
else if (b >= 0xf0 && b <= 0xf4) { need = 3; cp = b & 0x07; if (b === 0xf0) lo = 0x90; else if (b === 0xf4) hi = 0x8f; }
|
|
89
|
+
else return BAD;
|
|
90
|
+
return MORE;
|
|
91
|
+
}
|
|
92
|
+
const valid = b >= lo && b <= hi;
|
|
93
|
+
lo = 0x80; hi = 0xbf;
|
|
94
|
+
if (!valid) { need = 0; return RETRY; }
|
|
95
|
+
cp = (cp << 6) | (b & 0x3f);
|
|
96
|
+
return --need === 0 ? cp : MORE;
|
|
97
|
+
},
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Paste content is decoded leniently: what is not UTF-8 becomes U+FFFD, never an error. */
|
|
102
|
+
function decodeLenient(bytes, length) {
|
|
103
|
+
const decoder = utf8Decoder(), points = [];
|
|
104
|
+
let text = "";
|
|
105
|
+
const put = (cp) => {
|
|
106
|
+
if (points.push(cp) < 4096) return;
|
|
107
|
+
text += String.fromCodePoint.apply(null, points);
|
|
108
|
+
points.length = 0;
|
|
109
|
+
};
|
|
110
|
+
for (let i = 0; i < length; i++) {
|
|
111
|
+
const cp = decoder.push(bytes[i]);
|
|
112
|
+
if (cp >= 0) put(cp);
|
|
113
|
+
else if (cp !== MORE) { put(0xfffd); if (cp === RETRY) i--; }
|
|
114
|
+
}
|
|
115
|
+
if (decoder.pending) put(0xfffd);
|
|
116
|
+
return text + String.fromCodePoint.apply(null, points);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** `now` is the injected clock in milliseconds; the parser reads it once per
|
|
120
|
+
* `feed` and once per `expire`, and nowhere else.
|
|
121
|
+
*
|
|
122
|
+
* feed(bytes) the events of these bytes, in order. Text is never held back:
|
|
123
|
+
* a complete character is emitted by the feed that completes it.
|
|
124
|
+
* expire() call when the clock reaches timeoutAt(): the Esc key, if a lone
|
|
125
|
+
* ESC has waited ESC_TIMEOUT_MS; else nothing.
|
|
126
|
+
* timeoutAt() the clock time at which expire() is due, or null. */
|
|
127
|
+
export function createKeyParser({ now } = {}) {
|
|
128
|
+
if (typeof now !== "function") throw new TypeError("createKeyParser needs an injected clock: { now: () => milliseconds }");
|
|
129
|
+
const utf8 = utf8Decoder();
|
|
130
|
+
let state = GROUND, out = [], feedAt = 0, lastFeedAt = 0;
|
|
131
|
+
let run = ""; // consecutive printable code points of this feed, not yet cut into graphemes
|
|
132
|
+
let alt = false; // ESC came before the multi-byte character being decoded
|
|
133
|
+
let escAt = 0; // feed time of the pending lone ESC
|
|
134
|
+
let seq = ""; // CSI/SS3 parameter and intermediate bytes; null once over SEQUENCE_LIMIT
|
|
135
|
+
let bel = false; // the string sequence is an OSC, which BEL also ends
|
|
136
|
+
let mouse = 0; // bytes of an X10 mouse report still to swallow
|
|
137
|
+
let held = null, size = 0, over = false, matched = 0; // paste: content, its length, limit hit, end-marker bytes matched
|
|
138
|
+
|
|
139
|
+
/** Whatever comes between two code points, a key or a dropped byte or sequence,
|
|
140
|
+
* ends the run: only code points that arrive consecutively join into a grapheme. */
|
|
141
|
+
const flush = () => {
|
|
142
|
+
if (run.length === 1) out.push({ text: run });
|
|
143
|
+
else if (run !== "") for (const { segment } of GRAPHEMES.segment(run)) out.push({ text: segment });
|
|
144
|
+
run = "";
|
|
145
|
+
};
|
|
146
|
+
const emit = (event) => { flush(); out.push(event); };
|
|
147
|
+
const startEscape = () => { flush(); state = ESCAPE; escAt = feedAt; };
|
|
148
|
+
|
|
149
|
+
const ground = (b) => {
|
|
150
|
+
if (b >= 0x80 || utf8.pending) {
|
|
151
|
+
const cp = utf8.push(b);
|
|
152
|
+
if (cp === MORE) return;
|
|
153
|
+
const withAlt = alt;
|
|
154
|
+
alt = false;
|
|
155
|
+
if (cp === RETRY) { flush(); ground(b); return; }
|
|
156
|
+
if (cp === BAD || cp <= 0x9f) { flush(); return; } // not UTF-8, or a C1 control: dropped
|
|
157
|
+
if (withAlt) emit({ text: String.fromCodePoint(cp), alt: true });
|
|
158
|
+
else run += String.fromCodePoint(cp);
|
|
159
|
+
return;
|
|
160
|
+
}
|
|
161
|
+
if (b === ESC) { startEscape(); return; }
|
|
162
|
+
if (b >= 0x20 && b !== 0x7f) { run += String.fromCharCode(b); return; }
|
|
163
|
+
const key = c0Key(b);
|
|
164
|
+
if (key) emit(key);
|
|
165
|
+
else flush();
|
|
166
|
+
};
|
|
167
|
+
|
|
168
|
+
/** The byte after an ESC: a sequence introducer, or Alt plus a key. */
|
|
169
|
+
const afterEscape = (b) => {
|
|
170
|
+
state = GROUND;
|
|
171
|
+
if (b === ESC) { emit(named("escape")); startEscape(); }
|
|
172
|
+
else if (b === 0x5b) { state = CSI; seq = ""; }
|
|
173
|
+
else if (b === 0x4f) { state = SS3; seq = ""; }
|
|
174
|
+
else if (b === 0x5d) { state = STRING; bel = true; } // OSC
|
|
175
|
+
else if (b === 0x50 || b === 0x58 || b === 0x5e || b === 0x5f) { state = STRING; bel = false; } // DCS SOS PM APC
|
|
176
|
+
else if (b >= 0x80) { alt = true; ground(b); }
|
|
177
|
+
else if (b >= 0x20 && b !== 0x7f) emit({ text: String.fromCharCode(b), alt: true });
|
|
178
|
+
else {
|
|
179
|
+
const key = c0Key(b);
|
|
180
|
+
if (key) { key.alt = true; emit(key); }
|
|
181
|
+
}
|
|
182
|
+
};
|
|
183
|
+
|
|
184
|
+
/** Inside a CSI, an SS3 or the Linux console form. A control byte is dropped and
|
|
185
|
+
* the sequence goes on, an ESC starts over, a byte >= 0x80 aborts and is dropped. */
|
|
186
|
+
const inSequence = (b) => {
|
|
187
|
+
if (b === ESC) { startEscape(); return; }
|
|
188
|
+
if (b < 0x20 || b === 0x7f) return;
|
|
189
|
+
if (b >= 0x80) { state = GROUND; return; }
|
|
190
|
+
const from = state;
|
|
191
|
+
// CSI: parameters 0x30..0x3f and intermediates 0x20..0x2f. SS3: parameters only.
|
|
192
|
+
if (from !== LINUX && b <= 0x3f && (from === CSI || b >= 0x30)) {
|
|
193
|
+
seq = seq !== null && seq.length < SEQUENCE_LIMIT ? seq + String.fromCharCode(b) : null;
|
|
194
|
+
return;
|
|
195
|
+
}
|
|
196
|
+
const final = String.fromCharCode(b);
|
|
197
|
+
state = GROUND;
|
|
198
|
+
let key = null;
|
|
199
|
+
if (from === LINUX) key = LINUX_KEYS[final] ? named(LINUX_KEYS[final]) : null;
|
|
200
|
+
else if (from === SS3) key = ss3Key(seq, final);
|
|
201
|
+
else if (seq === "" && final === "[") state = LINUX;
|
|
202
|
+
else if (seq === "" && final === "M") { state = MOUSE; mouse = 3; } // X10 mouse report: 3 raw bytes follow
|
|
203
|
+
else if (seq === "200" && final === "~") state = PASTE;
|
|
204
|
+
else key = csiKey(seq, final);
|
|
205
|
+
if (key) emit(key);
|
|
206
|
+
};
|
|
207
|
+
|
|
208
|
+
const endPaste = (truncated) => {
|
|
209
|
+
emit(truncated ? { paste: "", truncated: true } : { paste: decodeLenient(held, size) });
|
|
210
|
+
held = null; size = 0; over = false; matched = 0;
|
|
211
|
+
state = GROUND;
|
|
212
|
+
};
|
|
213
|
+
|
|
214
|
+
/** Holds paste content, up to the limit. Content that reaches PASTE_LIMIT is
|
|
215
|
+
* dropped and nothing more is held: the paste will end as truncated. */
|
|
216
|
+
const hold = (source, from, to) => {
|
|
217
|
+
if (over) return;
|
|
218
|
+
const length = size + to - from;
|
|
219
|
+
if (length >= PASTE_LIMIT) { over = true; held = null; size = 0; return; }
|
|
220
|
+
if (held === null || length > held.length) {
|
|
221
|
+
const grown = new Uint8Array(Math.min(PASTE_LIMIT, Math.max(length, 2 * (held === null ? 128 : held.length))));
|
|
222
|
+
if (held !== null) grown.set(held.subarray(0, size));
|
|
223
|
+
held = grown;
|
|
224
|
+
}
|
|
225
|
+
held.set(source.subarray(from, to), size);
|
|
226
|
+
size = length;
|
|
227
|
+
};
|
|
228
|
+
|
|
229
|
+
/** Inside a bracketed paste every byte is content, up to the end marker `CSI 201 ~`,
|
|
230
|
+
* which may arrive split at any byte. Returns the index after the bytes it consumed. */
|
|
231
|
+
const inPaste = (bytes, i) => {
|
|
232
|
+
while (i < bytes.length) {
|
|
233
|
+
const b = bytes[i];
|
|
234
|
+
if (b === PASTE_END[matched]) {
|
|
235
|
+
i++;
|
|
236
|
+
if (++matched === PASTE_END.length) { endPaste(over); break; }
|
|
237
|
+
} else if (matched > 0) {
|
|
238
|
+
// Not the marker after all: its bytes were content. This byte is looked at again.
|
|
239
|
+
hold(PASTE_END, 0, matched);
|
|
240
|
+
matched = 0;
|
|
241
|
+
} else {
|
|
242
|
+
const stop = bytes.indexOf(ESC, i);
|
|
243
|
+
hold(bytes, i, stop === -1 ? bytes.length : stop);
|
|
244
|
+
i = stop === -1 ? bytes.length : stop;
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
return i;
|
|
248
|
+
};
|
|
249
|
+
|
|
250
|
+
/** The paste pause rule, and it lives only here. A paste whose end marker never
|
|
251
|
+
* arrives must not deafen the program for ever (Ctrl+C is a byte here): when a
|
|
252
|
+
* feed arrives PASTE_PAUSE_MS or more after the previous feed while a paste is
|
|
253
|
+
* open (under or over the limit), the paste is abandoned as truncated and this
|
|
254
|
+
* feed is read as keys. No timer: the clock is only read at feed.
|
|
255
|
+
*
|
|
256
|
+
* This is acceptable only because bracketed paste is a second guard, never the
|
|
257
|
+
* only one. A terminal may lack it, a paste can carry its own end marker, and a
|
|
258
|
+
* stalled paste ends here: nothing in the TUI may rely on this parser to stop a
|
|
259
|
+
* pasted key from acting. An act that matters asks for its own confirmation. */
|
|
260
|
+
const abandonStalledPaste = () => {
|
|
261
|
+
if (state === PASTE && feedAt - lastFeedAt >= PASTE_PAUSE_MS) endPaste(true);
|
|
262
|
+
};
|
|
263
|
+
|
|
264
|
+
return {
|
|
265
|
+
feed(bytes) {
|
|
266
|
+
if (!(bytes instanceof Uint8Array)) throw new TypeError("feed expects bytes (a Uint8Array)");
|
|
267
|
+
feedAt = now();
|
|
268
|
+
// A lone ESC that already waited its time is the Esc key; these bytes start fresh.
|
|
269
|
+
if (state === ESCAPE && feedAt >= escAt + ESC_TIMEOUT_MS) { state = GROUND; emit(named("escape")); }
|
|
270
|
+
abandonStalledPaste();
|
|
271
|
+
lastFeedAt = feedAt;
|
|
272
|
+
for (let i = 0; i < bytes.length; i++) {
|
|
273
|
+
if (state === PASTE) { i = inPaste(bytes, i) - 1; continue; }
|
|
274
|
+
const b = bytes[i];
|
|
275
|
+
switch (state) {
|
|
276
|
+
case GROUND: ground(b); break;
|
|
277
|
+
case ESCAPE: afterEscape(b); break;
|
|
278
|
+
case MOUSE:
|
|
279
|
+
if (b === ESC) startEscape();
|
|
280
|
+
else if (--mouse === 0) state = GROUND;
|
|
281
|
+
break;
|
|
282
|
+
case STRING: // swallowed as it streams, never held
|
|
283
|
+
if (b === ESC) state = STRING_ESC;
|
|
284
|
+
else if (bel && b === 0x07) state = GROUND;
|
|
285
|
+
break;
|
|
286
|
+
case STRING_ESC:
|
|
287
|
+
// `ESC \` is ST and ends the string. An ESC before anything else abandons
|
|
288
|
+
// the string and starts a new sequence, as in a CSI: the next key that
|
|
289
|
+
// sends an ESC recovers from a string whose end never arrives.
|
|
290
|
+
if (b === 0x5c) state = GROUND;
|
|
291
|
+
else if (b !== ESC) afterEscape(b);
|
|
292
|
+
break;
|
|
293
|
+
default: inSequence(b);
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
flush();
|
|
297
|
+
const events = out;
|
|
298
|
+
out = [];
|
|
299
|
+
return events;
|
|
300
|
+
},
|
|
301
|
+
expire() {
|
|
302
|
+
if (state !== ESCAPE || now() < escAt + ESC_TIMEOUT_MS) return [];
|
|
303
|
+
state = GROUND;
|
|
304
|
+
return [named("escape")];
|
|
305
|
+
},
|
|
306
|
+
/** Only a lone ESC has a deadline. Every other incomplete sequence waits for its end. */
|
|
307
|
+
timeoutAt() {
|
|
308
|
+
return state === ESCAPE ? escAt + ESC_TIMEOUT_MS : null;
|
|
309
|
+
},
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** The canonical string the action table binds: "ctrl+c", "shift+tab", "escape",
|
|
314
|
+
* "?", "space", "alt+q". Modifiers come in the order ctrl, alt, shift. A paste
|
|
315
|
+
* is not a key: null. */
|
|
316
|
+
export function keyId(event) {
|
|
317
|
+
if (typeof event?.name === "string") {
|
|
318
|
+
return `${event.ctrl ? "ctrl+" : ""}${event.alt ? "alt+" : ""}${event.shift ? "shift+" : ""}${event.name}`;
|
|
319
|
+
}
|
|
320
|
+
if (typeof event?.text !== "string") return null;
|
|
321
|
+
const id = event.text === " " ? "space" : event.text;
|
|
322
|
+
return event.alt ? `alt+${id}` : id;
|
|
323
|
+
}
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
// The screen: a buffer of cells and the bytes that turn the previous frame into the next one.
|
|
2
|
+
// With term/tty.mjs it is the only module that produces an ESC byte, and what it writes is a closed
|
|
3
|
+
// list: a position, an erase, an SGR of style.mjs's parameters. Text reaches it as safe text only
|
|
4
|
+
// (term/text.mjs); a string is refused.
|
|
5
|
+
//
|
|
6
|
+
// The rules a width disagreement cannot break (docs/tui.md): every row write starts with an
|
|
7
|
+
// absolute position and is erased to its end, so a character the terminal draws wider or narrower
|
|
8
|
+
// than width.mjs counts moves nothing outside its own row; nothing is written past the last column.
|
|
9
|
+
import { cells } from "./width.mjs";
|
|
10
|
+
import { textOf } from "./text.mjs";
|
|
11
|
+
import { PLAIN, isStyle, sgr } from "./style.mjs";
|
|
12
|
+
|
|
13
|
+
const CSI = "\x1b[";
|
|
14
|
+
const RESET = `${CSI}0m`;
|
|
15
|
+
const CLEAR = `${CSI}2J`;
|
|
16
|
+
const ERASE_TO_END = `${CSI}K`;
|
|
17
|
+
const position = (row, col) => `${CSI}${row + 1};${col + 1}H`;
|
|
18
|
+
|
|
19
|
+
const cell = (text, width, style) => Object.freeze({ text, width, style });
|
|
20
|
+
const BLANK = cell(" ", 1, PLAIN);
|
|
21
|
+
/** The second cell of a two-cell grapheme: it holds nothing to write. */
|
|
22
|
+
const TAIL = cell("", 0, PLAIN);
|
|
23
|
+
const PRINTABLE_ASCII = /^[\x20-\x7e]$/;
|
|
24
|
+
/** A cell that shows nothing: a space in a style that draws nothing on a space. */
|
|
25
|
+
const shows = (c) => c.text !== " " || c.style.underline || c.style.reverse;
|
|
26
|
+
|
|
27
|
+
/** What the locale and `--ascii` decide: `utf8`, whether the terminal is told to read UTF-8
|
|
28
|
+
* (LC_ALL, else LC_CTYPE, else LANG names it), and `ascii`, whether the TUI's own marks and rules
|
|
29
|
+
* are ASCII (not UTF-8, or asked for). */
|
|
30
|
+
export function glyphs(env, { ascii = false } = {}) {
|
|
31
|
+
const locale = [env.LC_ALL, env.LC_CTYPE, env.LANG].find((value) => typeof value === "string" && value !== "") ?? "";
|
|
32
|
+
const utf8 = /utf-?8/i.test(locale);
|
|
33
|
+
return { utf8, ascii: ascii || !utf8 };
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** A screen. `render(rows, size, { full })` answers the bytes for one frame and remembers it.
|
|
37
|
+
* `rows[r]` is the spans of row r: `{ col, text, style?, width? }`, `text` safe text, `width` the
|
|
38
|
+
* cells the span may take (default: to the right edge). */
|
|
39
|
+
export function createScreen({ utf8 = true, ascii = !utf8, color = true } = {}) {
|
|
40
|
+
const mark = cells(ascii ? "..." : "\u2026");
|
|
41
|
+
let previous = null;
|
|
42
|
+
|
|
43
|
+
/** Overwriting one half of a two-cell grapheme blanks the other half. */
|
|
44
|
+
function clear(line, x) {
|
|
45
|
+
if (line[x] === TAIL) line[x - 1] = BLANK;
|
|
46
|
+
else if (line[x].width === 2) line[x + 1] = BLANK;
|
|
47
|
+
line[x] = BLANK;
|
|
48
|
+
}
|
|
49
|
+
function place(line, span) {
|
|
50
|
+
const { col, style = PLAIN } = span;
|
|
51
|
+
const source = textOf(span.text);
|
|
52
|
+
if (!isStyle(style)) throw new TypeError("a span's style is a style value: make one with style()");
|
|
53
|
+
if (!Number.isInteger(col) || col < 0) throw new RangeError("a span's column is a cell index from 0");
|
|
54
|
+
const limit = span.width === undefined ? line.length : Math.min(line.length, col + span.width);
|
|
55
|
+
if (col >= limit) return;
|
|
56
|
+
let drawn = cells(source);
|
|
57
|
+
// A terminal that is not reading UTF-8 would show each byte of a character on its own.
|
|
58
|
+
if (!utf8) drawn = drawn.map((g) => (PRINTABLE_ASCII.test(g.text) ? g : { text: "?", width: 1 }));
|
|
59
|
+
if (drawn.reduce((sum, g) => sum + g.width, 0) > limit - col) {
|
|
60
|
+
// Clipped: what fits before the mark, then the mark (or as much of it as the span holds).
|
|
61
|
+
const room = limit - col - mark.reduce((sum, g) => sum + g.width, 0);
|
|
62
|
+
const kept = [];
|
|
63
|
+
for (let used = 0, i = 0; i < drawn.length && used + drawn[i].width <= room; used += drawn[i].width, i++) kept.push(drawn[i]);
|
|
64
|
+
drawn = [...kept, ...mark];
|
|
65
|
+
}
|
|
66
|
+
let x = col;
|
|
67
|
+
for (const g of drawn) {
|
|
68
|
+
if (x + g.width > limit) break;
|
|
69
|
+
clear(line, x);
|
|
70
|
+
if (g.width === 2) { clear(line, x + 1); line[x + 1] = TAIL; }
|
|
71
|
+
line[x] = cell(g.text, g.width, style);
|
|
72
|
+
x += g.width;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
function layout(rows, size) {
|
|
76
|
+
return Array.from({ length: size.rows }, (_, r) => {
|
|
77
|
+
const line = Array.from({ length: size.cols }, () => BLANK);
|
|
78
|
+
for (const span of rows[r] ?? []) place(line, span);
|
|
79
|
+
return line;
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const same = (a, b) => a === b || (a.text === b.text && a.style === b.style);
|
|
84
|
+
const asciiOnly = (line) => line.every((c) => PRINTABLE_ASCII.test(c.text));
|
|
85
|
+
/** The bytes of one row from column `from`: a position, the cells up to the last one that shows,
|
|
86
|
+
* and an erase when the row ends before the right edge. Every row ends in the plain style, so the
|
|
87
|
+
* erase paints nothing and the next row starts from a known state. */
|
|
88
|
+
function writeRow(r, line, from) {
|
|
89
|
+
let end = line.length;
|
|
90
|
+
while (end > 0 && !shows(line[end - 1])) end--;
|
|
91
|
+
const start = Math.min(from, end);
|
|
92
|
+
let out = position(r, start), current = RESET;
|
|
93
|
+
for (let x = start; x < end; x++) {
|
|
94
|
+
const c = line[x];
|
|
95
|
+
if (c === TAIL) continue;
|
|
96
|
+
// Always from a reset: a style never inherits from the cell before it.
|
|
97
|
+
const look = `${CSI}${[0, ...sgr(c.style, { color })].join(";")}m`;
|
|
98
|
+
if (look !== current) { out += look; current = look; }
|
|
99
|
+
out += c.text;
|
|
100
|
+
}
|
|
101
|
+
if (current !== RESET) out += RESET;
|
|
102
|
+
return end < line.length ? out + ERASE_TO_END : out;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function render(rows, size, { full = false } = {}) {
|
|
106
|
+
const lines = layout(rows, size);
|
|
107
|
+
const redraw = full || !previous || previous.cols !== size.cols || previous.rows !== size.rows;
|
|
108
|
+
let out = redraw ? RESET + CLEAR : "";
|
|
109
|
+
for (let r = 0; r < size.rows; r++) {
|
|
110
|
+
const line = lines[r], old = redraw ? null : previous.lines[r];
|
|
111
|
+
if (!old) { if (line.some(shows)) out += writeRow(r, line, 0); continue; }
|
|
112
|
+
const changed = line.findIndex((c, x) => !same(c, old[x]));
|
|
113
|
+
if (changed < 0) continue;
|
|
114
|
+
// A row with any grapheme outside printable ASCII is rewritten whole: its columns are only
|
|
115
|
+
// as sure as the width table, so nothing in it is addressed by column.
|
|
116
|
+
out += writeRow(r, line, asciiOnly(line) && asciiOnly(old) ? changed : 0);
|
|
117
|
+
}
|
|
118
|
+
previous = { cols: size.cols, rows: size.rows, lines };
|
|
119
|
+
return out;
|
|
120
|
+
}
|
|
121
|
+
return { render };
|
|
122
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
// Style values, by name. A style is the terminal's own sixteen colours and four attributes
|
|
2
|
+
// (docs/tui.md): no background, no 256-colour or RGB value, so the user's theme stays the theme.
|
|
3
|
+
// This module holds SGR parameters as numbers; the screen is what writes the sequence.
|
|
4
|
+
|
|
5
|
+
const FOREGROUND = Object.freeze({
|
|
6
|
+
black: 30, red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, white: 37,
|
|
7
|
+
brightBlack: 90, brightRed: 91, brightGreen: 92, brightYellow: 93, brightBlue: 94, brightMagenta: 95, brightCyan: 96, brightWhite: 97,
|
|
8
|
+
});
|
|
9
|
+
const ATTRIBUTE = Object.freeze({ bold: 1, dim: 2, underline: 4, reverse: 7 });
|
|
10
|
+
export const COLORS = Object.freeze(Object.keys(FOREGROUND));
|
|
11
|
+
export const ATTRIBUTES = Object.freeze(Object.keys(ATTRIBUTE));
|
|
12
|
+
|
|
13
|
+
/** One value per distinct style, so two equal styles are the same object and the screen compares
|
|
14
|
+
* cells by identity. */
|
|
15
|
+
const made = new Map();
|
|
16
|
+
const parameters = new WeakMap();
|
|
17
|
+
|
|
18
|
+
/** The style with that colour and those attributes: `style({ fg: "red", bold: true })`. */
|
|
19
|
+
export function style(spec = {}) {
|
|
20
|
+
for (const key of Object.keys(spec)) if (key !== "fg" && !ATTRIBUTES.includes(key)) throw new TypeError(`unknown style key ${key}`);
|
|
21
|
+
if (spec.fg !== undefined && !Object.hasOwn(FOREGROUND, spec.fg)) throw new TypeError("a style's colour is one of the sixteen ANSI names");
|
|
22
|
+
const attributes = ATTRIBUTES.filter((name) => spec[name] === true);
|
|
23
|
+
const id = [...attributes, spec.fg ?? ""].join(",");
|
|
24
|
+
if (!made.has(id)) {
|
|
25
|
+
const value = Object.freeze({ fg: spec.fg ?? null, ...Object.fromEntries(ATTRIBUTES.map((name) => [name, attributes.includes(name)])) });
|
|
26
|
+
parameters.set(value, Object.freeze({ attributes: attributes.map((name) => ATTRIBUTE[name]), colour: spec.fg === undefined ? [] : [FOREGROUND[spec.fg]] }));
|
|
27
|
+
made.set(id, value);
|
|
28
|
+
}
|
|
29
|
+
return made.get(id);
|
|
30
|
+
}
|
|
31
|
+
export const PLAIN = style();
|
|
32
|
+
export const isStyle = (value) => parameters.has(value);
|
|
33
|
+
|
|
34
|
+
/** The SGR parameters of a style, attributes first. Without `color` the colour is dropped and the
|
|
35
|
+
* attributes stay. */
|
|
36
|
+
export function sgr(value, { color = true } = {}) {
|
|
37
|
+
const own = parameters.get(value);
|
|
38
|
+
if (!own) throw new TypeError("not a style value: make one with style()");
|
|
39
|
+
return color ? [...own.attributes, ...own.colour] : [...own.attributes];
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** NO_COLOR (no-color.org): set and not empty switches colour off. */
|
|
43
|
+
export const colorEnabled = (env) => !(typeof env.NO_COLOR === "string" && env.NO_COLOR !== "");
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
// Safe text: the only thing the screen draws. A terminal acts on what is written to it, so the
|
|
2
|
+
// screen takes strings from nobody: it takes values only this module can make (docs/tui.md,
|
|
3
|
+
// awebai/oats#855 section 3.9). There are two ways in, and no third:
|
|
4
|
+
// lit(string) the TUI's own words;
|
|
5
|
+
// shown(value) text the TUI did not write, through the shared display filter.
|
|
6
|
+
// A safe value is for display only: nothing compares it, selects by it or passes it to a command.
|
|
7
|
+
//
|
|
8
|
+
// Every view meets this: the filter folds a run of spaces into one and trims both ends, so lit()
|
|
9
|
+
// refuses a string with two spaces together or a space at an end. A row is therefore spans placed
|
|
10
|
+
// by column (`{ col, text, style }`), never one padded string: the gap between two spans is the
|
|
11
|
+
// screen's blank cells, not text.
|
|
12
|
+
import { displayLine, DETAIL_WITHHELD } from "../client.mjs";
|
|
13
|
+
|
|
14
|
+
/** The brand: a value is safe text when it is a key here. Nothing outside this module can add one,
|
|
15
|
+
* and a look-alike object is not one. */
|
|
16
|
+
const TEXT = new WeakMap();
|
|
17
|
+
function make(string) {
|
|
18
|
+
const value = Object.freeze(Object.create(null));
|
|
19
|
+
TEXT.set(value, string);
|
|
20
|
+
return value;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Nothing to show. */
|
|
24
|
+
export const EMPTY = make("");
|
|
25
|
+
/** Text the filter withheld whole (a control character, a secret shape): the TUI's own mark. */
|
|
26
|
+
export const WITHHELD = make("[withheld]");
|
|
27
|
+
|
|
28
|
+
/** The TUI's own one-line text. It throws unless the display filter would show the string as it is:
|
|
29
|
+
* a developer who hands it kernel text by mistake still cannot write a control character. The
|
|
30
|
+
* message never repeats the string, which may be the very thing that must not be written. */
|
|
31
|
+
export function lit(string) {
|
|
32
|
+
if (typeof string !== "string" || displayLine(string) !== string) throw new TypeError("lit() takes the TUI's own one-line text, exactly as the display filter shows it; text from anywhere else goes through shown()");
|
|
33
|
+
return make(string);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Text the TUI did not write (a kernel answer, a name, anything relayed), as one display line. */
|
|
37
|
+
export function shown(value) {
|
|
38
|
+
const line = displayLine(value);
|
|
39
|
+
return line === null ? EMPTY : line === DETAIL_WITHHELD ? WITHHELD : make(line);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export const isSafeText = (value) => TEXT.has(value);
|
|
43
|
+
|
|
44
|
+
/** The string of a safe value, for the screen (and the tests that read a row). A raw string and a
|
|
45
|
+
* forged object are refused. */
|
|
46
|
+
export function textOf(value) {
|
|
47
|
+
if (!TEXT.has(value)) throw new TypeError("the screen draws safe text only: lit() for the TUI's own words, shown() for anything else");
|
|
48
|
+
return TEXT.get(value);
|
|
49
|
+
}
|