@skathi-native/cli 0.0.0 → 0.1.0-beta.1
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/aot-inputs.ts +294 -0
- package/ascii.ts +397 -0
- package/build.ts +1236 -0
- package/check/builtins.json +1219 -0
- package/check/builtins.ts +112 -0
- package/check/codes.ts +178 -0
- package/check/command.ts +105 -0
- package/check/config.ts +76 -0
- package/check/finding.ts +30 -0
- package/check/graph.ts +69 -0
- package/check/highlight.ts +40 -0
- package/check/index.ts +308 -0
- package/check/packages.ts +54 -0
- package/check/program.ts +209 -0
- package/check/report.ts +219 -0
- package/check/rules.ts +307 -0
- package/check/schema.ts +69 -0
- package/check/typing.ts +703 -0
- package/cli/assets.ts +114 -0
- package/cli/build-app.ts +587 -0
- package/cli/config.ts +646 -0
- package/cli/create.ts +411 -0
- package/cli/dev.ts +92 -0
- package/cli/elf.ts +142 -0
- package/cli/host-fetch.ts +178 -0
- package/cli/host.ts +378 -0
- package/cli/icon.ts +303 -0
- package/cli/macos-bundle.ts +451 -0
- package/cli/pe.ts +429 -0
- package/cli/platform.ts +74 -0
- package/cli/sk.ts +356 -0
- package/cli/skpk.ts +268 -0
- package/cli/stamp.ts +254 -0
- package/cli/term.ts +176 -0
- package/cli/versioninfo.ts +123 -0
- package/css-prefixes.ts +118 -0
- package/devtools/apps.ts +68 -0
- package/devtools/commands.ts +860 -0
- package/devtools/ctl.ts +166 -0
- package/package.json +51 -3
- package/prod.ts +701 -0
- package/runtime-path.ts +24 -0
- package/tailwind.ts +76 -0
- package/vitecompat.ts +1151 -0
|
@@ -0,0 +1,860 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The command table: the one place a sk-devtools command is declared, shared by `ctl.ts` (the
|
|
3
|
+
* dependency-free CLI) and `mcp.ts` (the MCP server). It owns the wire `cmd` and its arguments, how
|
|
4
|
+
* a CLI invocation reads into a request, the `ctl --help` usage lines, and the MCP JSON Schema.
|
|
5
|
+
* The MCP tool name is derived (`sk_<cmd>`); `window` rides on every request.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { resolve } from "node:path";
|
|
9
|
+
|
|
10
|
+
export type Flags = Record<string, string | boolean>;
|
|
11
|
+
|
|
12
|
+
export class UsageError extends Error {}
|
|
13
|
+
|
|
14
|
+
// The explicit annotation is load-bearing: TypeScript narrows after a `never`-returning call only
|
|
15
|
+
// for a function declaration or a const with a declared type.
|
|
16
|
+
const die: (message: string) => never = (message) => {
|
|
17
|
+
throw new UsageError(message);
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
export const num = (v: unknown): number | undefined => {
|
|
21
|
+
if (v === undefined || v === "") return undefined;
|
|
22
|
+
const n = Number(v);
|
|
23
|
+
return Number.isFinite(n) ? n : undefined;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
const compact = (o: Record<string, unknown>): Record<string, unknown> => {
|
|
27
|
+
for (const k of Object.keys(o)) if (o[k] === undefined) delete o[k];
|
|
28
|
+
return o;
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const integerFlag = (
|
|
32
|
+
value: unknown,
|
|
33
|
+
name: string,
|
|
34
|
+
minimum = 0,
|
|
35
|
+
maximum = Number.MAX_SAFE_INTEGER,
|
|
36
|
+
): number | undefined => {
|
|
37
|
+
if (value === undefined) return undefined;
|
|
38
|
+
if (value === true || value === false || value === "") die(`${name} needs an integer`);
|
|
39
|
+
const parsed = Number(value);
|
|
40
|
+
if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum)
|
|
41
|
+
die(`${name} must be an integer between ${minimum} and ${maximum}`);
|
|
42
|
+
return parsed;
|
|
43
|
+
};
|
|
44
|
+
const stringFlag = (value: unknown): string | undefined => (typeof value === "string" ? value : undefined);
|
|
45
|
+
|
|
46
|
+
export interface ArgSpec {
|
|
47
|
+
type: "string" | "number" | "boolean";
|
|
48
|
+
description: string;
|
|
49
|
+
required?: boolean;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const str = (description: string, required?: boolean): ArgSpec =>
|
|
53
|
+
required ? { type: "string", description, required } : { type: "string", description };
|
|
54
|
+
const int = (description: string): ArgSpec => ({ type: "number", description });
|
|
55
|
+
const bool = (description: string): ArgSpec => ({ type: "boolean", description });
|
|
56
|
+
|
|
57
|
+
const SELECTOR = str("a CSS selector, matched by the same sk-css cascade matcher the app styles with");
|
|
58
|
+
const SELECTOR_REQ = str("a CSS selector, matched by the same sk-css cascade matcher the app styles with", true);
|
|
59
|
+
const INDEX = int("which match to use when the selector matches several (0-based)");
|
|
60
|
+
const NODE = int("a node id from sk_tree/sk_query, when you already have one");
|
|
61
|
+
const SINCE = int("first sequence number to return (the `next` from the last call)");
|
|
62
|
+
|
|
63
|
+
export const WINDOW_ARG = int(
|
|
64
|
+
"which of the target's OS windows the command is about (sk_windows lists them; " +
|
|
65
|
+
"default: the primary one). One process can paint several windows off one retained " +
|
|
66
|
+
"tree, and they are in different client spaces",
|
|
67
|
+
);
|
|
68
|
+
|
|
69
|
+
export interface CommandSpec {
|
|
70
|
+
cmd: string;
|
|
71
|
+
/** Other CLI spellings of the verb; the request still carries `cmd`. */
|
|
72
|
+
aliases?: string[];
|
|
73
|
+
description: string;
|
|
74
|
+
usage: string[];
|
|
75
|
+
args: Record<string, ArgSpec>;
|
|
76
|
+
cli: (rest: string[], flags: Flags) => Record<string, unknown>;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const withIndex = (o: Record<string, unknown>, flags: Flags): Record<string, unknown> => {
|
|
80
|
+
const index = num(flags.index);
|
|
81
|
+
return index === undefined ? o : { ...o, index };
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
const selectorOrNode = (cmd: string, rest: string[], flags: Flags): Record<string, unknown> => {
|
|
85
|
+
const node = num(flags.node);
|
|
86
|
+
if (!rest[0] && node === undefined) die(`${cmd} needs a selector or --node <id>`);
|
|
87
|
+
return compact({ selector: rest[0] || undefined, node });
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
export const COMMANDS: CommandSpec[] = [
|
|
91
|
+
{
|
|
92
|
+
cmd: "ping",
|
|
93
|
+
description: "Is a host alive on this dist slot? Returns {pid, root}.",
|
|
94
|
+
usage: [" ping is a host alive on this dist slot?"],
|
|
95
|
+
args: {},
|
|
96
|
+
cli: () => ({}),
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
cmd: "query",
|
|
100
|
+
description:
|
|
101
|
+
"querySelectorAll through the REAL cascade matcher. Returns [{id, tag, classes, text, " +
|
|
102
|
+
"bounds, scopes}]. An unsupported selector (`:has()`, `::before`, `:visited`, ...) is an " +
|
|
103
|
+
"error carrying the same advisory the stylesheet compiler prints.",
|
|
104
|
+
usage: [" query <selector> match through the real sk-css cascade matcher"],
|
|
105
|
+
args: { selector: SELECTOR_REQ },
|
|
106
|
+
cli: (rest) => {
|
|
107
|
+
if (!rest[0]) die("query needs a selector");
|
|
108
|
+
return { selector: rest[0] };
|
|
109
|
+
},
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
cmd: "text",
|
|
113
|
+
description: "textContent of the matched subtree (or a native <input>'s live buffer).",
|
|
114
|
+
usage: [" text <selector> [--index N] textContent of the subtree (or an <input>'s buffer)"],
|
|
115
|
+
args: { selector: SELECTOR_REQ, index: INDEX },
|
|
116
|
+
cli: (rest, flags) => {
|
|
117
|
+
if (!rest[0]) die("text needs a selector");
|
|
118
|
+
return withIndex({ selector: rest[0] }, flags);
|
|
119
|
+
},
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
cmd: "tree",
|
|
123
|
+
description:
|
|
124
|
+
"Dump the retained tree (kind / tag / classes / props / scopes / listeners / text / " +
|
|
125
|
+
"bounds / children). `kind` is element | text | anchor — a text node and a Vue fragment " +
|
|
126
|
+
"anchor both have an EMPTY tag, so label a row by kind, never by tag.",
|
|
127
|
+
usage: [" tree [selector] [--depth N] [--node ID] dump the retained tree"],
|
|
128
|
+
args: {
|
|
129
|
+
selector: str("subtree root (default: the mounted root, or what `window` paints)"),
|
|
130
|
+
node: int("subtree root as a node id, when you already have one"),
|
|
131
|
+
depth: int("levels to descend (default 6)"),
|
|
132
|
+
},
|
|
133
|
+
cli: (rest, flags) => compact({ selector: rest[0] || undefined, node: num(flags.node), depth: num(flags.depth) }),
|
|
134
|
+
},
|
|
135
|
+
{
|
|
136
|
+
cmd: "styles",
|
|
137
|
+
description:
|
|
138
|
+
"The node's folded ComputedStates: base + the hover/active/focus/focus-visible rungs, " +
|
|
139
|
+
"transitions and extras, plus `live` (the style in EFFECT this frame). Takes a node id " +
|
|
140
|
+
"instead of a selector when you already have one.",
|
|
141
|
+
usage: [" styles <selector|--node ID> [--index N] the node's folded ComputedStates"],
|
|
142
|
+
args: { selector: SELECTOR, index: INDEX, node: NODE },
|
|
143
|
+
cli: (rest, flags) => withIndex(selectorOrNode("styles", rest, flags), flags),
|
|
144
|
+
},
|
|
145
|
+
{
|
|
146
|
+
cmd: "rules",
|
|
147
|
+
description:
|
|
148
|
+
"WHICH rules produced this node's styles, in cascade order ((specificity, order) ascending, " +
|
|
149
|
+
"so the last declaration of a property wins). Each rule carries its selector, @media " +
|
|
150
|
+
"prelude, state bucket (base/hover/active/focus/...), pseudo-element, declarations as the " +
|
|
151
|
+
"author wrote them, and the sk-css advisories about THAT rule — i.e. which of its " +
|
|
152
|
+
"declarations this engine does not implement.",
|
|
153
|
+
usage: [
|
|
154
|
+
" rules <selector|--node ID> [--index N] the RULES that matched it, in",
|
|
155
|
+
" cascade order — selector, @media, source",
|
|
156
|
+
" order, declarations, per-rule advisories",
|
|
157
|
+
],
|
|
158
|
+
args: { selector: SELECTOR, index: INDEX, node: NODE },
|
|
159
|
+
cli: (rest, flags) => withIndex(selectorOrNode("rules", rest, flags), flags),
|
|
160
|
+
},
|
|
161
|
+
{
|
|
162
|
+
cmd: "highlight",
|
|
163
|
+
description:
|
|
164
|
+
"Draw the inspector's outline over a node in the app (a blue box plus a `tag.class · WxH` " +
|
|
165
|
+
"chip), or clear it. Painted by the host shell, so it never appears in the app's own tree " +
|
|
166
|
+
"and never takes a click. Pass ttlMs to make it expire by itself; `window` decides which " +
|
|
167
|
+
"window paints it.",
|
|
168
|
+
usage: [
|
|
169
|
+
" highlight <selector|--node ID> [--index N] [--ttl MS] [--label TEXT]",
|
|
170
|
+
" highlight --clear the inspector outline, drawn over the app",
|
|
171
|
+
],
|
|
172
|
+
args: {
|
|
173
|
+
selector: SELECTOR,
|
|
174
|
+
index: INDEX,
|
|
175
|
+
node: NODE,
|
|
176
|
+
ttlMs: int("expire after this many ms (default: until cleared)"),
|
|
177
|
+
label: str("chip text (default: tag.class · WxH)"),
|
|
178
|
+
clear: bool("remove the outline"),
|
|
179
|
+
},
|
|
180
|
+
cli: (rest, flags) => {
|
|
181
|
+
const node = num(flags.node);
|
|
182
|
+
if (flags.clear || (!rest[0] && node === undefined)) return { clear: true };
|
|
183
|
+
return withIndex(
|
|
184
|
+
compact({
|
|
185
|
+
selector: rest[0] || undefined,
|
|
186
|
+
node,
|
|
187
|
+
ttlMs: num(flags.ttl),
|
|
188
|
+
label: typeof flags.label === "string" && flags.label ? flags.label : undefined,
|
|
189
|
+
}),
|
|
190
|
+
flags,
|
|
191
|
+
);
|
|
192
|
+
},
|
|
193
|
+
},
|
|
194
|
+
{
|
|
195
|
+
cmd: "pick",
|
|
196
|
+
aliases: ["picker"],
|
|
197
|
+
description:
|
|
198
|
+
"Without op, poll the node under the real pointer: {x,y,insideWindow,window,path,node}. " +
|
|
199
|
+
"With op=start, arm the native element picker; the next target click is consumed before " +
|
|
200
|
+
"application handlers and selects a node. op=status renews its 15-second lease and returns " +
|
|
201
|
+
"active/selected/cancelled, generation and selection. Escape or op=stop cancels.",
|
|
202
|
+
usage: [" pick [start|status|stop] poll, or control the native click picker"],
|
|
203
|
+
args: { op: str('"start", "status" or "stop"; absent preserves stateless pointer polling') },
|
|
204
|
+
cli: (rest, flags) => {
|
|
205
|
+
const op = rest[0] ?? stringFlag(flags.op);
|
|
206
|
+
if (op !== undefined && !["start", "status", "stop"].includes(op)) die("pick op must be start, status or stop");
|
|
207
|
+
return compact({ op });
|
|
208
|
+
},
|
|
209
|
+
},
|
|
210
|
+
{
|
|
211
|
+
cmd: "click",
|
|
212
|
+
description:
|
|
213
|
+
"Synthesize mousedown -> mouseup -> click at the node's centre, through the app's own " +
|
|
214
|
+
"dispatch (capture/bubble, preventDefault honored). NOT a real pointer: :hover / :active " +
|
|
215
|
+
"visuals are not exercised and nothing proves the node is reachable — use sk_mouse for " +
|
|
216
|
+
"that. Errors on 0 or >1 matches unless `index` is given.",
|
|
217
|
+
usage: [" click <selector> [--index N] [--button N]"],
|
|
218
|
+
args: { selector: SELECTOR_REQ, index: INDEX, button: int("0 left, 1 middle, 2 right") },
|
|
219
|
+
cli: (rest, flags) => {
|
|
220
|
+
if (!rest[0]) die("click needs a selector");
|
|
221
|
+
return withIndex(compact({ selector: rest[0], button: num(flags.button) }), flags);
|
|
222
|
+
},
|
|
223
|
+
},
|
|
224
|
+
{
|
|
225
|
+
cmd: "focus",
|
|
226
|
+
description:
|
|
227
|
+
"el.focus(). The focus/blur events come from gpui's focus observers, so it reports " +
|
|
228
|
+
"identically to a click or a Tab.",
|
|
229
|
+
usage: [" focus <selector> [--index N]"],
|
|
230
|
+
args: { selector: SELECTOR_REQ, index: INDEX },
|
|
231
|
+
cli: (rest, flags) => {
|
|
232
|
+
if (!rest[0]) die("focus needs a selector");
|
|
233
|
+
return withIndex({ selector: rest[0] }, flags);
|
|
234
|
+
},
|
|
235
|
+
},
|
|
236
|
+
{
|
|
237
|
+
cmd: "type",
|
|
238
|
+
description:
|
|
239
|
+
"Focus the node and type `text` one keystroke at a time through gpui's real key path, so " +
|
|
240
|
+
"keydown / input / v-model all fire exactly as they do for a physical key — including the " +
|
|
241
|
+
"app's own preventDefault() guards.",
|
|
242
|
+
usage: [" type <selector> <text> [--index N]"],
|
|
243
|
+
args: { selector: SELECTOR_REQ, text: str("the text to type", true), index: INDEX },
|
|
244
|
+
cli: (rest, flags) => {
|
|
245
|
+
if (rest.length < 2) die('type needs a selector and text: ctl type ".field" "hello"');
|
|
246
|
+
return withIndex({ selector: rest[0], text: rest.slice(1).join(" ") }, flags);
|
|
247
|
+
},
|
|
248
|
+
},
|
|
249
|
+
{
|
|
250
|
+
cmd: "ime",
|
|
251
|
+
description:
|
|
252
|
+
"Stand in for the IME on a text field: `text` becomes the composition's pre-edit, or with " +
|
|
253
|
+
'`commit` its committed text ("" cancels it). compositionstart, beforeinput, ' +
|
|
254
|
+
"compositionupdate, input and compositionend fire in Chromium's order, from the widget's " +
|
|
255
|
+
"own path. For testing where no IME is installed; no keystroke is sent.",
|
|
256
|
+
usage: [" ime <selector> <text> [--commit] [--index N]"],
|
|
257
|
+
args: {
|
|
258
|
+
selector: SELECTOR_REQ,
|
|
259
|
+
text: str('the pre-edit, or the committed text; "" cancels the composition', true),
|
|
260
|
+
commit: bool("commit the composition with `text`"),
|
|
261
|
+
index: INDEX,
|
|
262
|
+
},
|
|
263
|
+
cli: (rest, flags) => {
|
|
264
|
+
if (!rest[0]) die('ime needs a selector and text: ctl ime ".field" "か" [--commit]');
|
|
265
|
+
return withIndex(
|
|
266
|
+
compact({ selector: rest[0], text: rest.slice(1).join(" "), commit: flags.commit === true || undefined }),
|
|
267
|
+
flags,
|
|
268
|
+
);
|
|
269
|
+
},
|
|
270
|
+
},
|
|
271
|
+
{
|
|
272
|
+
cmd: "key",
|
|
273
|
+
description:
|
|
274
|
+
"Send one keystroke: `Enter`, `Escape`, `Shift+Tab`, `Ctrl+A`, `ArrowDown`, ... With a " +
|
|
275
|
+
"selector the node is focused first; without one it goes to whatever already has focus.",
|
|
276
|
+
usage: [" key <Key|Mod+Key> [selector] [--index N]"],
|
|
277
|
+
args: { key: str("key name, optionally Mod+Key", true), selector: SELECTOR, index: INDEX },
|
|
278
|
+
cli: (rest, flags) => {
|
|
279
|
+
if (!rest[0]) die("key needs a key name: ctl key Enter [selector]");
|
|
280
|
+
return withIndex(compact({ key: rest[0], selector: rest[1] || undefined }), flags);
|
|
281
|
+
},
|
|
282
|
+
},
|
|
283
|
+
{
|
|
284
|
+
cmd: "mouse",
|
|
285
|
+
description:
|
|
286
|
+
"A REAL pointer event at a window coordinate, through gpui's own hit test — so z-order, " +
|
|
287
|
+
"content masks, `pointer-events` and the hover ladder all decide what happens. This is what " +
|
|
288
|
+
"proves an element is reachable (and the only way to exercise :hover); sk_click proves the " +
|
|
289
|
+
"handler chain instead. Aim it with a selector (the node's centre) or with x + y. Reports " +
|
|
290
|
+
"which node holds focus afterwards. No cursor moves and no window is activated.",
|
|
291
|
+
usage: [
|
|
292
|
+
" mouse [selector] [--x N --y N] [--kind move|down|up|click] [--button N]",
|
|
293
|
+
" [--held] [--clicks N] [--shift]",
|
|
294
|
+
" a REAL pointer event through gpui's hit",
|
|
295
|
+
" test (hover, z-order, pointer-events all",
|
|
296
|
+
" apply); reports which node has focus after",
|
|
297
|
+
],
|
|
298
|
+
args: {
|
|
299
|
+
selector: SELECTOR,
|
|
300
|
+
index: INDEX,
|
|
301
|
+
x: int("window x, when no selector is given"),
|
|
302
|
+
y: int("window y, when no selector is given"),
|
|
303
|
+
kind: str("move (default) | down | up | click"),
|
|
304
|
+
button: int("0 left, 1 middle, 2 right"),
|
|
305
|
+
held: bool("the move is a drag: the button is down during it (a text selection follows it)"),
|
|
306
|
+
clicks: int("the press's click count: 2 selects a word, 3 a paragraph"),
|
|
307
|
+
shift: bool("Shift is held (Shift+click extends a text selection)"),
|
|
308
|
+
},
|
|
309
|
+
cli: (rest, flags) => {
|
|
310
|
+
// Unlike `click`, this is decided by the hit test, so it proves an element is reachable and exercises `:hover`.
|
|
311
|
+
const base = compact({
|
|
312
|
+
kind: flags.kind ? String(flags.kind) : "move",
|
|
313
|
+
button: num(flags.button),
|
|
314
|
+
held: flags.held ? true : undefined,
|
|
315
|
+
clicks: num(flags.clicks),
|
|
316
|
+
shift: flags.shift ? true : undefined,
|
|
317
|
+
});
|
|
318
|
+
if (rest[0]) return withIndex({ ...base, selector: rest[0] }, flags);
|
|
319
|
+
const x = num(flags.x);
|
|
320
|
+
const y = num(flags.y);
|
|
321
|
+
if (x === undefined || y === undefined) die("mouse needs a selector, or both --x and --y");
|
|
322
|
+
return { ...base, x, y };
|
|
323
|
+
},
|
|
324
|
+
},
|
|
325
|
+
{
|
|
326
|
+
cmd: "scroll",
|
|
327
|
+
description:
|
|
328
|
+
"Scroll a container by (dx, dy) CSS pixels through its own gpui ScrollHandle and fire the " +
|
|
329
|
+
"`scroll` event. The node must have `overflow: scroll|auto` in the cascade. This proves a " +
|
|
330
|
+
"container CAN scroll and says nothing about the gesture — sk_wheel is the gesture.",
|
|
331
|
+
usage: [" scroll <selector> <dy> [--dx N] [--index N]"],
|
|
332
|
+
args: {
|
|
333
|
+
selector: SELECTOR_REQ,
|
|
334
|
+
dy: int("vertical delta, positive = down"),
|
|
335
|
+
dx: int("horizontal delta"),
|
|
336
|
+
index: INDEX,
|
|
337
|
+
},
|
|
338
|
+
cli: (rest, flags) => {
|
|
339
|
+
if (!rest[0]) die("scroll needs a selector");
|
|
340
|
+
return withIndex({ selector: rest[0], dx: num(flags.dx) ?? 0, dy: num(rest[1]) ?? num(flags.dy) ?? 0 }, flags);
|
|
341
|
+
},
|
|
342
|
+
},
|
|
343
|
+
{
|
|
344
|
+
cmd: "wheel",
|
|
345
|
+
description:
|
|
346
|
+
"A REAL wheel event at a window coordinate, through gpui's own hit test — what an app's own " +
|
|
347
|
+
"@wheel handler sees. THE DELTAS ARE THE DOM'S: dy > 0 scrolls DOWN, as WheelEvent.deltaY " +
|
|
348
|
+
"means (gpui carries the platform's opposite sign; the conversion is one place on each " +
|
|
349
|
+
"side). Aim it with a selector or with x + y.",
|
|
350
|
+
usage: [
|
|
351
|
+
" wheel [selector] [--x N --y N] --dy N [--dx N] [--ctrl] [--shift] [--alt]",
|
|
352
|
+
" a REAL wheel event through gpui's hit",
|
|
353
|
+
" test — what an app's own @wheel handler",
|
|
354
|
+
" sees. DOM signs: --dy 200 scrolls DOWN.",
|
|
355
|
+
" (`scroll` drives a container's handle",
|
|
356
|
+
" directly and never involves the wheel)",
|
|
357
|
+
],
|
|
358
|
+
args: {
|
|
359
|
+
selector: SELECTOR,
|
|
360
|
+
index: INDEX,
|
|
361
|
+
x: int("window x, when no selector is given"),
|
|
362
|
+
y: int("window y, when no selector is given"),
|
|
363
|
+
dy: int("vertical delta, DOM signs: positive scrolls DOWN"),
|
|
364
|
+
dx: int("horizontal delta"),
|
|
365
|
+
ctrl: bool("Ctrl is held (a ctrl+wheel zooms in most apps)"),
|
|
366
|
+
shift: bool("Shift is held"),
|
|
367
|
+
alt: bool("Alt is held"),
|
|
368
|
+
},
|
|
369
|
+
cli: (rest, flags) => {
|
|
370
|
+
const dy = num(flags.dy) ?? 0;
|
|
371
|
+
const dx = num(flags.dx) ?? 0;
|
|
372
|
+
if (!dy && !dx) die("wheel needs --dy (or --dx); DOM signs, so --dy 200 scrolls down");
|
|
373
|
+
const keys = {
|
|
374
|
+
...(flags.ctrl ? { ctrl: true } : {}),
|
|
375
|
+
...(flags.shift ? { shift: true } : {}),
|
|
376
|
+
...(flags.alt ? { alt: true } : {}),
|
|
377
|
+
};
|
|
378
|
+
if (rest[0]) return withIndex({ selector: rest[0], dx, dy, ...keys }, flags);
|
|
379
|
+
const x = num(flags.x);
|
|
380
|
+
const y = num(flags.y);
|
|
381
|
+
if (x === undefined || y === undefined) die("wheel needs a selector, or both --x and --y");
|
|
382
|
+
return { dx, dy, x, y, ...keys };
|
|
383
|
+
},
|
|
384
|
+
},
|
|
385
|
+
{
|
|
386
|
+
cmd: "eval",
|
|
387
|
+
description:
|
|
388
|
+
"Evaluate JavaScript inside the app's JSC, in global scope. Returns {value, type} or " +
|
|
389
|
+
"{exception, stack}. The escape hatch for everything the other tools do not cover.",
|
|
390
|
+
usage: [" eval <js source>"],
|
|
391
|
+
args: { js: str("JavaScript source", true) },
|
|
392
|
+
cli: (rest) => {
|
|
393
|
+
if (!rest.length) die("eval needs a JS source string");
|
|
394
|
+
return { js: rest.join(" ") };
|
|
395
|
+
},
|
|
396
|
+
},
|
|
397
|
+
{
|
|
398
|
+
cmd: "logs",
|
|
399
|
+
description:
|
|
400
|
+
"The host's log ring (500 entries): console output, [js uncaught] errors, CSS diagnostics " +
|
|
401
|
+
"and compat advisories, plus `next` (the cursor) and the current status line. An entry may " +
|
|
402
|
+
"carry `styles` — where each `%c` run began and what it declared. Page with `since`.",
|
|
403
|
+
usage: [" logs [--since N]"],
|
|
404
|
+
args: { since: SINCE },
|
|
405
|
+
cli: (_rest, flags) => compact({ since: num(flags.since) }),
|
|
406
|
+
},
|
|
407
|
+
{
|
|
408
|
+
cmd: "screenshot",
|
|
409
|
+
description:
|
|
410
|
+
"Capture the app window to a PNG. Default backend is gpui's render_to_image readback: the " +
|
|
411
|
+
"CLIENT area exactly (clientX/clientY come back 0), works unfocused, occluded, off-screen " +
|
|
412
|
+
"and minimized, and never raises or activates the window — but it cannot see a mica/acrylic " +
|
|
413
|
+
"backdrop, which DWM composites under the app. Pass backend=print_window for the composed " +
|
|
414
|
+
"image (PrintWindow(PW_RENDERFULLCONTENT), whole window rect, stale when minimized).",
|
|
415
|
+
usage: [" screenshot [path] [--backend auto|render_to_image|print_window]"],
|
|
416
|
+
args: {
|
|
417
|
+
path: str("output PNG path (default: <dist>/screenshots/<n>.png)"),
|
|
418
|
+
backend: str('"auto" (default), "render_to_image" or "print_window"'),
|
|
419
|
+
},
|
|
420
|
+
cli: (rest, flags) =>
|
|
421
|
+
compact({
|
|
422
|
+
// A relative path on a CLI means relative to where it was typed; the host's cwd is its own.
|
|
423
|
+
path: rest[0] ? resolve(rest[0]) : undefined,
|
|
424
|
+
backend: flags.backend ? String(flags.backend) : undefined,
|
|
425
|
+
}),
|
|
426
|
+
},
|
|
427
|
+
{
|
|
428
|
+
cmd: "windows",
|
|
429
|
+
description:
|
|
430
|
+
"Every OS window this process paints — {id, kind (main|popout), title, root, viewport, " +
|
|
431
|
+
"scale, focused, hovered} — plus `inspectors`, the devtools windows the target has open on " +
|
|
432
|
+
"ITSELF via F12. One process can paint several windows off one retained tree, so this is " +
|
|
433
|
+
"where the `window` argument's values come from.",
|
|
434
|
+
usage: [
|
|
435
|
+
" windows every OS window this process paints (and",
|
|
436
|
+
" every inspector it has open on itself)",
|
|
437
|
+
],
|
|
438
|
+
args: {},
|
|
439
|
+
cli: () => ({}),
|
|
440
|
+
},
|
|
441
|
+
{
|
|
442
|
+
cmd: "perf",
|
|
443
|
+
description:
|
|
444
|
+
"The rolling frame window, always on: {frames, uptimeMs, bootMs, avgMs, p50Ms, p95Ms, " +
|
|
445
|
+
"maxMs, fps, budgetMs, samples[], nodes, windows, phases}. `budgetMs` is the display's " +
|
|
446
|
+
"refresh interval (null when unreported). One Instant read and one store per frame, " +
|
|
447
|
+
'so "why is this janky" can be asked of a host that is already running. `phases` reports ' +
|
|
448
|
+
"whether SK_PERF's stderr breakdown is on rather than duplicating its counters (reading " +
|
|
449
|
+
"them would clear them under the person profiling).",
|
|
450
|
+
usage: [
|
|
451
|
+
" perf the rolling frame window: fps, p50/p95,",
|
|
452
|
+
" node count, boot->first-frame",
|
|
453
|
+
],
|
|
454
|
+
args: {},
|
|
455
|
+
cli: () => ({}),
|
|
456
|
+
},
|
|
457
|
+
{
|
|
458
|
+
cmd: "mem",
|
|
459
|
+
description:
|
|
460
|
+
"Where the process's memory is, computed on demand. `breakdown` (BYTES) has categories that " +
|
|
461
|
+
"SUM to the committed address space — loaded images (exe + DLLs), mapped files, JSC " +
|
|
462
|
+
"(mimalloc + JIT), the Rust heap (the process heap, split by subsystem when counted), and " +
|
|
463
|
+
"'other private' (driver heaps, stacks: what no allocator accounts for) — plus GPU memory " +
|
|
464
|
+
"beside them. The other sections (MB; `…Bytes` fields are bytes): OS counters, the " +
|
|
465
|
+
"address-space walk, heap summaries, the Rust heap count (on by default in a dev build, " +
|
|
466
|
+
"SK_MEMSTATS=0/1 overrides), JSC's GC heap and mimalloc, GPU per adapter LUID, gpui's sprite " +
|
|
467
|
+
"atlas and decoded-image cache, the painted-image registry, the retained tree per node, the " +
|
|
468
|
+
"devtools' own rings. `gc` first runs two full synchronous JSC collections and returns free " +
|
|
469
|
+
"pages to the OS (it changes state) and reports what that freed; `code` does the same after deleting " +
|
|
470
|
+
"all compiled code that is not running (it recompiles on demand), which tells code from data.",
|
|
471
|
+
usage: [
|
|
472
|
+
" mem [--gc] [--code] [--regions] where the process's memory is (--gc: a full JSC",
|
|
473
|
+
" collection first, before/after reported;",
|
|
474
|
+
" --code: also delete compiled code first;",
|
|
475
|
+
" --regions: walk the heap too, list the biggest",
|
|
476
|
+
" unattributed reservations)",
|
|
477
|
+
],
|
|
478
|
+
args: {
|
|
479
|
+
gc: bool("run two full JSC collections first and report before/after (changes state)"),
|
|
480
|
+
code: bool("like gc, after deleting all compiled code that is not running (bytecode, JIT): what is left is data"),
|
|
481
|
+
regions: bool(
|
|
482
|
+
"also walk the process heap (it is locked meanwhile — tens of ms on a big heap) so the " +
|
|
483
|
+
"address walk can tell the heap's reservations apart, and list the biggest unattributed ones",
|
|
484
|
+
),
|
|
485
|
+
},
|
|
486
|
+
cli: (_rest, flags) =>
|
|
487
|
+
compact({
|
|
488
|
+
gc: flags.gc ? true : undefined,
|
|
489
|
+
code: flags.code ? true : undefined,
|
|
490
|
+
regions: flags.regions ? true : undefined,
|
|
491
|
+
}),
|
|
492
|
+
},
|
|
493
|
+
{
|
|
494
|
+
cmd: "trace",
|
|
495
|
+
description:
|
|
496
|
+
"Record instrumented main-thread elapsed time. recording-start/recording-stop/recording-status " +
|
|
497
|
+
"control bounded ordered captures; frames pages summaries and frame pages nested calls with " +
|
|
498
|
+
"parentId, selfMs, durationMs, counters, callsites and hints. These are CPU/host timings, " +
|
|
499
|
+
"not GPU timestamps or sampled CPU cycles. Legacy start/stop/peek/mark retain their aggregate " +
|
|
500
|
+
"phase report (and still refuse SK_PERF counter ownership conflicts).",
|
|
501
|
+
usage: [
|
|
502
|
+
" trace recording-start [--cap N] | recording-stop | recording-status",
|
|
503
|
+
" trace frames [--offset N] [--limit N]",
|
|
504
|
+
" trace frame --frame-id ID [--offset N] [--limit N]",
|
|
505
|
+
" trace start [--cap N] | stop [--frames] | peek [--frames] | mark <label>",
|
|
506
|
+
],
|
|
507
|
+
args: {
|
|
508
|
+
op: str(
|
|
509
|
+
"recording-start | recording-stop | recording-status | frames | frame; legacy start | stop | peek (default) | mark",
|
|
510
|
+
),
|
|
511
|
+
frameId: int("for op=frame: a captured frame id"),
|
|
512
|
+
offset: int("paged result offset, starting at zero"),
|
|
513
|
+
limit: int("page size: frames <=240, frame spans <=1000"),
|
|
514
|
+
frames: bool("legacy stop/peek: include every stored aggregate frame"),
|
|
515
|
+
label: str("legacy mark: the label"),
|
|
516
|
+
cap: int("recording-start: 16..10000 frames (default 1200); legacy start default 20000"),
|
|
517
|
+
},
|
|
518
|
+
cli: (rest, flags) => {
|
|
519
|
+
const op = rest[0] || stringFlag(flags.op) || "peek";
|
|
520
|
+
if (["recording-start", "recording-stop", "recording-status", "frames", "frame"].includes(op)) {
|
|
521
|
+
const frameId = integerFlag(
|
|
522
|
+
flags["frame-id"] ?? flags.frameId ?? (op === "frame" ? rest[1] : undefined),
|
|
523
|
+
"--frame-id",
|
|
524
|
+
);
|
|
525
|
+
if (op === "frame" && frameId === undefined) die("trace frame needs --frame-id ID");
|
|
526
|
+
return compact({
|
|
527
|
+
op,
|
|
528
|
+
frameId,
|
|
529
|
+
offset: integerFlag(flags.offset, "--offset"),
|
|
530
|
+
limit: integerFlag(flags.limit, "--limit", 1, op === "frames" ? 240 : 1000),
|
|
531
|
+
cap: integerFlag(flags.cap, "--cap", 16, 10000),
|
|
532
|
+
});
|
|
533
|
+
}
|
|
534
|
+
if (!["start", "stop", "peek", "mark"].includes(op)) die("unknown trace op");
|
|
535
|
+
if (op === "mark" && !rest[1] && typeof flags.label !== "string") die("trace mark needs a label");
|
|
536
|
+
return compact({
|
|
537
|
+
op,
|
|
538
|
+
frames: flags.frames ? true : undefined,
|
|
539
|
+
label: op === "mark" ? (typeof flags.label === "string" ? flags.label : rest.slice(1).join(" ")) : undefined,
|
|
540
|
+
cap: num(flags.cap),
|
|
541
|
+
});
|
|
542
|
+
},
|
|
543
|
+
},
|
|
544
|
+
{
|
|
545
|
+
cmd: "net",
|
|
546
|
+
description:
|
|
547
|
+
"Every fetch(), XMLHttpRequest and WebSocket the app opened, from BOOT — a bounded ring of " +
|
|
548
|
+
"300 summary rows. `kind` is fetch, xhr or ws; a socket's `phase` is open-requested / open / " +
|
|
549
|
+
"error / close and its messages are COUNTED rather than logged. The ring outlives " +
|
|
550
|
+
"location.reload() and a dev host's cold restart: the host puts a `kind: reload` marker row " +
|
|
551
|
+
"(`cause` says which) between " +
|
|
552
|
+
"the runs, and the rows before it are the previous run's. " +
|
|
553
|
+
"Page with `since`. A row " +
|
|
554
|
+
"that came off the network carries `proto` (h2 / http/1.1), `conn` (connection id; equal ids " +
|
|
555
|
+
"shared one) and `reused`; `pool` is the transport's connection/request/reuse/retry counters. " +
|
|
556
|
+
"Headers, bodies, cookies and timing are NOT here — pass a row's `seq` to sk_net_detail.",
|
|
557
|
+
usage: [" net [--since N] the fetch / WebSocket / XHR log"],
|
|
558
|
+
args: { since: SINCE },
|
|
559
|
+
cli: (_rest, flags) => compact({ since: num(flags.since) }),
|
|
560
|
+
},
|
|
561
|
+
{
|
|
562
|
+
cmd: "net_detail",
|
|
563
|
+
aliases: ["net-detail"],
|
|
564
|
+
description:
|
|
565
|
+
"Everything behind ONE sk_net row, asked for by its `seq`: the request (URL, method, the " +
|
|
566
|
+
"headers the app passed, credentials, the body — text, form fields, or bytes) and the " +
|
|
567
|
+
"response (status, headers, a body preview). A body is `encoding: utf8` text or `base64` " +
|
|
568
|
+
"bytes (binary types such as application/ion are always base64), capped at 256 KB with " +
|
|
569
|
+
"`truncated` set; the most recent ~12 MB of bodies are kept and an older one says " +
|
|
570
|
+
"`evicted`. `cookies.sent` is the Cookie header the jar sent; `cookies.wire` the response's " +
|
|
571
|
+
"Set-Cookie lines exactly as received (`cookies.set`, reconstructed from the jar, when there " +
|
|
572
|
+
"is no wire copy) — script never sees either. `transport` has protocol, reused, " +
|
|
573
|
+
"connectionId and the remote address. " +
|
|
574
|
+
"`timing` has headersMs / bodyMs / failedMs; a WebSocket row answers with its socket: " +
|
|
575
|
+
"protocol, close code and reason, and sent/received message counts.",
|
|
576
|
+
usage: [
|
|
577
|
+
" net_detail <seq> headers, bodies, cookies and timing behind one",
|
|
578
|
+
" `net` row (also spelled net-detail)",
|
|
579
|
+
],
|
|
580
|
+
args: {
|
|
581
|
+
seq: { type: "number", description: "the row's `seq`, from sk_net", required: true },
|
|
582
|
+
},
|
|
583
|
+
cli: (rest, flags) => {
|
|
584
|
+
const seq = num(rest[0]) ?? num(flags.seq);
|
|
585
|
+
if (seq === undefined) die("net_detail needs a row's seq (from `net`): ctl net_detail 12");
|
|
586
|
+
return { seq };
|
|
587
|
+
},
|
|
588
|
+
},
|
|
589
|
+
{
|
|
590
|
+
cmd: "net_cache",
|
|
591
|
+
aliases: ["net-cache"],
|
|
592
|
+
description:
|
|
593
|
+
"The disk HTTP cache under fetch, XHR and every <img>/font load: its " +
|
|
594
|
+
"folder, cap, entries and size, whether this instance owns the folder (`writable`) and seals " +
|
|
595
|
+
"entries (`sealed`), and the counters since start (hits, revalidated, stored, misses, " +
|
|
596
|
+
'bypassed, evicted, errors). `op: "clear"` deletes every entry and answers `freed` (bytes). ' +
|
|
597
|
+
"`null` when no cache is installed (SK_HTTP_CACHE=0, httpCache.maxMB 0, or no storage).",
|
|
598
|
+
usage: [" net_cache [stats|clear] the disk HTTP cache: counters, or empty it"],
|
|
599
|
+
args: { op: str('"stats" (default) or "clear"') },
|
|
600
|
+
cli: (rest, flags) => compact({ op: rest[0] ?? (flags.op as string | undefined) }),
|
|
601
|
+
},
|
|
602
|
+
{
|
|
603
|
+
cmd: "storage",
|
|
604
|
+
description:
|
|
605
|
+
"localStorage / sessionStorage, read and written through the APP's own JS rather than the " +
|
|
606
|
+
"host's disk layer — so what you see is what getItem() answers, pending writes included. " +
|
|
607
|
+
"A host built without the `storages` feature answers with the error that says so, rather " +
|
|
608
|
+
"than an empty table.",
|
|
609
|
+
usage: [" storage [local|session] [list|set|remove|clear] [--key K] [--value V]"],
|
|
610
|
+
args: {
|
|
611
|
+
area: str('"local" (default) or "session"'),
|
|
612
|
+
op: str('"list" (default), "set", "remove" or "clear"'),
|
|
613
|
+
key: str("the entry to set or remove"),
|
|
614
|
+
value: str("the value, for op=set"),
|
|
615
|
+
},
|
|
616
|
+
cli: (rest, flags) =>
|
|
617
|
+
compact({
|
|
618
|
+
area: rest[0] || "local",
|
|
619
|
+
op: rest[1] || "list",
|
|
620
|
+
key: typeof flags.key === "string" ? flags.key : undefined,
|
|
621
|
+
value: typeof flags.value === "string" ? flags.value : undefined,
|
|
622
|
+
}),
|
|
623
|
+
},
|
|
624
|
+
{
|
|
625
|
+
cmd: "indexeddb",
|
|
626
|
+
description:
|
|
627
|
+
"Read-only IndexedDB inspection without opening/upgrading databases or running application JS. " +
|
|
628
|
+
"list returns names/versions; schema returns stores, indexes, key paths and counts; records " +
|
|
629
|
+
"returns bounded typed structured-clone previews, primary/index keys and an opaque nextCursor. " +
|
|
630
|
+
"Blob bodies are not searched. Busy databases report an error to retry, never an upgrade.",
|
|
631
|
+
usage: [
|
|
632
|
+
" indexeddb [list] database names and versions",
|
|
633
|
+
" indexeddb schema <database> object stores and indexes",
|
|
634
|
+
" indexeddb records <database> <store> [--index NAME] [--after CURSOR]",
|
|
635
|
+
" [--limit N] [--search TEXT] bounded typed previews (maximum 100 records)",
|
|
636
|
+
],
|
|
637
|
+
args: {
|
|
638
|
+
op: str('"list" (default), "schema" or "records"'),
|
|
639
|
+
database: str("database name"),
|
|
640
|
+
store: str("object store name"),
|
|
641
|
+
index: str("optional index name; absent walks primary keys"),
|
|
642
|
+
after: str("opaque hexadecimal nextCursor from the preceding page"),
|
|
643
|
+
limit: int("records per page, 1..100 (default 50)"),
|
|
644
|
+
search: str("key and bounded preview search, up to 256 characters; excludes Blob bodies"),
|
|
645
|
+
},
|
|
646
|
+
cli: (rest, flags) => {
|
|
647
|
+
const op = rest[0] || stringFlag(flags.op) || "list";
|
|
648
|
+
if (!["list", "schema", "records"].includes(op)) die("indexeddb op must be list, schema or records");
|
|
649
|
+
const database = stringFlag(flags.database) ?? rest[1],
|
|
650
|
+
store = stringFlag(flags.store) ?? rest[2];
|
|
651
|
+
if (op !== "list" && database === undefined) die(`indexeddb ${op} needs a database name`);
|
|
652
|
+
if (op === "records" && store === undefined) die("indexeddb records needs an object store name");
|
|
653
|
+
const search = stringFlag(flags.search),
|
|
654
|
+
after = stringFlag(flags.after);
|
|
655
|
+
if (search !== undefined && [...search].length > 256) die("--search is limited to 256 characters");
|
|
656
|
+
if (after !== undefined && (!/^[a-f0-9]*$/i.test(after) || after.length % 2 !== 0))
|
|
657
|
+
die("--after must be the opaque hexadecimal nextCursor");
|
|
658
|
+
return compact({
|
|
659
|
+
op,
|
|
660
|
+
database,
|
|
661
|
+
store,
|
|
662
|
+
index: stringFlag(flags.index),
|
|
663
|
+
after,
|
|
664
|
+
search,
|
|
665
|
+
limit: integerFlag(flags.limit, "--limit", 1, 100),
|
|
666
|
+
});
|
|
667
|
+
},
|
|
668
|
+
},
|
|
669
|
+
{
|
|
670
|
+
cmd: "allocations",
|
|
671
|
+
description:
|
|
672
|
+
"Bounded Rust allocator event capture: start/stop/status/snapshot, explicit scoped sites and " +
|
|
673
|
+
"size classes, observed churn and capture-born survivors. Pointer-hash sampling is not " +
|
|
674
|
+
"extrapolated; coverage states missing JS, JSC and native allocator hooks. Optional heap " +
|
|
675
|
+
"counter is separate from captured events. Dropped events/partial rows make complete=false.",
|
|
676
|
+
usage: [
|
|
677
|
+
" allocations [status|snapshot] [--category TEXT] [--site TEXT]",
|
|
678
|
+
" [--min-size N] [--max-size N] [--limit N]",
|
|
679
|
+
" allocations start [--sample-every N] [--max-events N] | stop",
|
|
680
|
+
],
|
|
681
|
+
args: {
|
|
682
|
+
op: str('"status" (default), "start", "stop" or "snapshot"'),
|
|
683
|
+
sampleEvery: int("pointer-hash sample interval, 1..4096; observed counts are not extrapolated"),
|
|
684
|
+
maxEvents: int("event buffer capacity, 1024..65536"),
|
|
685
|
+
category: str("category substring filter"),
|
|
686
|
+
site: str("explicit site substring filter"),
|
|
687
|
+
minSize: int("minimum allocation size in bytes"),
|
|
688
|
+
maxSize: int("maximum allocation size in bytes"),
|
|
689
|
+
limit: int("maximum grouped rows, 1..2000 (default 300)"),
|
|
690
|
+
},
|
|
691
|
+
cli: (rest, flags) => {
|
|
692
|
+
const op = rest[0] || stringFlag(flags.op) || "status";
|
|
693
|
+
if (!["start", "stop", "status", "snapshot"].includes(op))
|
|
694
|
+
die("allocations op must be start, stop, status or snapshot");
|
|
695
|
+
const minSize = integerFlag(flags["min-size"] ?? flags.minSize, "--min-size"),
|
|
696
|
+
maxSize = integerFlag(flags["max-size"] ?? flags.maxSize, "--max-size");
|
|
697
|
+
if (minSize !== undefined && maxSize !== undefined && minSize > maxSize) die("--min-size exceeds --max-size");
|
|
698
|
+
return compact({
|
|
699
|
+
op,
|
|
700
|
+
minSize,
|
|
701
|
+
maxSize,
|
|
702
|
+
category: stringFlag(flags.category),
|
|
703
|
+
site: stringFlag(flags.site),
|
|
704
|
+
sampleEvery: integerFlag(flags["sample-every"] ?? flags.sampleEvery, "--sample-every", 1, 4096),
|
|
705
|
+
maxEvents: integerFlag(flags["max-events"] ?? flags.maxEvents, "--max-events", 1024, 65536),
|
|
706
|
+
limit: integerFlag(flags.limit, "--limit", 1, 2000),
|
|
707
|
+
});
|
|
708
|
+
},
|
|
709
|
+
},
|
|
710
|
+
{
|
|
711
|
+
cmd: "dialog",
|
|
712
|
+
description:
|
|
713
|
+
"The dialogs waiting for an answer — <input type=file>, the File System Access pickers, " +
|
|
714
|
+
"<a download>'s Save As, and the app's permission prompt — when the app runs with " +
|
|
715
|
+
"SK_DIALOGS=scripted (nothing reaches the OS then). `list` names each one ({id, window, " +
|
|
716
|
+
"what, kind, ...}: a file dialog's multiple, filters, startIn, suggestedName; a question's " +
|
|
717
|
+
'(kind "ask") instruction and buttons); `answer` finishes a file dialog with absolute ' +
|
|
718
|
+
"paths, checked as the OS dialog would check them; `choose` presses a question's button " +
|
|
719
|
+
'(its label, e.g. "Allow", or its index); `cancel` dismisses either, as Esc would. ' +
|
|
720
|
+
"Without SK_DIALOGS=scripted every dialog is real and this command refuses.",
|
|
721
|
+
usage: [
|
|
722
|
+
" dialog [list] dialogs waiting for an answer (SK_DIALOGS=scripted)",
|
|
723
|
+
" dialog answer <id> <path>... answer a file dialog with absolute paths",
|
|
724
|
+
" dialog choose <id> <button> press a question's button (label or index)",
|
|
725
|
+
" dialog cancel <id> dismiss one, as Esc would",
|
|
726
|
+
],
|
|
727
|
+
args: {
|
|
728
|
+
op: str('"list" (default), "answer", "choose" or "cancel"'),
|
|
729
|
+
id: int("the dialog to answer, choose in or cancel (from `list`)"),
|
|
730
|
+
paths: str("for op=answer: absolute paths, separated by `|` (the wire also takes an array)"),
|
|
731
|
+
button: str('for op=choose: the button\'s label ("Allow", "Block") or its index'),
|
|
732
|
+
},
|
|
733
|
+
cli: (rest, flags) => {
|
|
734
|
+
const op = rest[0] || "list";
|
|
735
|
+
const flagged = num(flags.id);
|
|
736
|
+
const id = flagged ?? num(rest[1]);
|
|
737
|
+
if (op !== "list" && id === undefined) die(`dialog ${op} needs the dialog's id`);
|
|
738
|
+
const listed = rest.slice(flagged === undefined ? 2 : 1);
|
|
739
|
+
if (op === "choose") {
|
|
740
|
+
const button = typeof flags.button === "string" ? flags.button : listed.join(" ");
|
|
741
|
+
if (!button) die("dialog choose needs a button: its label or its index");
|
|
742
|
+
return compact({ op, id, button });
|
|
743
|
+
}
|
|
744
|
+
const paths = typeof flags.paths === "string" ? flags.paths : listed.length ? listed.join("|") : undefined;
|
|
745
|
+
if (op === "answer" && paths === undefined) die("dialog answer needs at least one path");
|
|
746
|
+
return compact({ op, id, paths });
|
|
747
|
+
},
|
|
748
|
+
},
|
|
749
|
+
{
|
|
750
|
+
cmd: "permissions",
|
|
751
|
+
description:
|
|
752
|
+
"The app's permissions: every capability's state (granted / denied / prompt / unsupported), " +
|
|
753
|
+
"the answers stored for the app's own prompt (microphone: allow / block, and when) and the " +
|
|
754
|
+
"file they live in (permissions.json in the app's storage folder). `reset` forgets a stored " +
|
|
755
|
+
"answer, so the next getUserMedia shows the prompt again. That and the app's own " +
|
|
756
|
+
'appPermissions.request("microphone") are the ways back after Block. It changes a real ' +
|
|
757
|
+
"decision on any host, scripted or not.",
|
|
758
|
+
usage: [
|
|
759
|
+
" permissions [list] states, stored answers, where they are kept",
|
|
760
|
+
" permissions reset [name] forget an answer (all of them without a name)",
|
|
761
|
+
],
|
|
762
|
+
args: {
|
|
763
|
+
op: str('"list" (default) or "reset"'),
|
|
764
|
+
name: str('for op=reset: the permission, e.g. "microphone" (default: every one with a prompt)'),
|
|
765
|
+
},
|
|
766
|
+
cli: (rest, flags) =>
|
|
767
|
+
compact({
|
|
768
|
+
op: rest[0] || "list",
|
|
769
|
+
name: typeof flags.name === "string" ? flags.name : rest[1],
|
|
770
|
+
}),
|
|
771
|
+
},
|
|
772
|
+
{
|
|
773
|
+
cmd: "raise",
|
|
774
|
+
description:
|
|
775
|
+
"Bring the addressed window to the front. The ONLY command here that deliberately takes " +
|
|
776
|
+
"focus — SK_DEVTOOLS_RAISE=off in the target's environment suppresses the activation, for " +
|
|
777
|
+
"an automated run on a machine somebody is using.",
|
|
778
|
+
usage: [" raise bring the window to the front"],
|
|
779
|
+
args: {},
|
|
780
|
+
cli: () => ({}),
|
|
781
|
+
},
|
|
782
|
+
];
|
|
783
|
+
|
|
784
|
+
export interface McpTool {
|
|
785
|
+
name: string;
|
|
786
|
+
description: string;
|
|
787
|
+
inputSchema: {
|
|
788
|
+
type: "object";
|
|
789
|
+
properties: Record<string, { type: string; description: string }>;
|
|
790
|
+
required?: string[];
|
|
791
|
+
};
|
|
792
|
+
build: (args: Record<string, unknown>) => Record<string, unknown>;
|
|
793
|
+
}
|
|
794
|
+
|
|
795
|
+
export const toolName = (cmd: string): string => `sk_${cmd}`;
|
|
796
|
+
|
|
797
|
+
export function mcpTools(): McpTool[] {
|
|
798
|
+
return COMMANDS.map((spec) => {
|
|
799
|
+
const names = Object.keys(spec.args);
|
|
800
|
+
const required = names.filter((n) => spec.args[n]!.required);
|
|
801
|
+
const properties: Record<string, { type: string; description: string }> = {};
|
|
802
|
+
for (const n of names) {
|
|
803
|
+
const arg = spec.args[n]!;
|
|
804
|
+
properties[n] = { type: arg.type, description: arg.description };
|
|
805
|
+
}
|
|
806
|
+
properties.window = { type: WINDOW_ARG.type, description: WINDOW_ARG.description };
|
|
807
|
+
return {
|
|
808
|
+
name: toolName(spec.cmd),
|
|
809
|
+
description: spec.description,
|
|
810
|
+
inputSchema: {
|
|
811
|
+
type: "object" as const,
|
|
812
|
+
properties,
|
|
813
|
+
...(required.length ? { required } : {}),
|
|
814
|
+
},
|
|
815
|
+
build: (args: Record<string, unknown>) => {
|
|
816
|
+
const wire: Record<string, unknown> = { cmd: spec.cmd };
|
|
817
|
+
for (const n of [...names, "window"]) if (args[n] !== undefined) wire[n] = args[n];
|
|
818
|
+
return wire;
|
|
819
|
+
},
|
|
820
|
+
};
|
|
821
|
+
});
|
|
822
|
+
}
|
|
823
|
+
|
|
824
|
+
export const commandNames = (): string[] => COMMANDS.map((c) => c.cmd);
|
|
825
|
+
|
|
826
|
+
export function usageBlock(): string {
|
|
827
|
+
return COMMANDS.flatMap((c) => c.usage).join("\n");
|
|
828
|
+
}
|
|
829
|
+
|
|
830
|
+
/** `["query", ".tab"]` + flags -> `{cmd: "query", selector: ".tab"}`. Throws [`UsageError`] for an unknown verb or malformed invocation. */
|
|
831
|
+
/** Split actual CLI argv using the same boolean arguments the MCP schema exposes. */
|
|
832
|
+
export function splitArgs(argv: string[]): { positional: string[]; flags: Flags } {
|
|
833
|
+
const switches = new Set([
|
|
834
|
+
"json",
|
|
835
|
+
"help",
|
|
836
|
+
...COMMANDS.flatMap((spec) =>
|
|
837
|
+
Object.entries(spec.args)
|
|
838
|
+
.filter(([, arg]) => arg.type === "boolean")
|
|
839
|
+
.map(([name]) => name),
|
|
840
|
+
),
|
|
841
|
+
]);
|
|
842
|
+
const positional: string[] = [];
|
|
843
|
+
const flags: Flags = {};
|
|
844
|
+
for (let i = 0; i < argv.length; i++) {
|
|
845
|
+
const value = argv[i]!;
|
|
846
|
+
if (!value.startsWith("--")) positional.push(value);
|
|
847
|
+
else {
|
|
848
|
+
const name = value.slice(2);
|
|
849
|
+
flags[name] = switches.has(name) ? true : (argv[++i] ?? "");
|
|
850
|
+
}
|
|
851
|
+
}
|
|
852
|
+
return { positional, flags };
|
|
853
|
+
}
|
|
854
|
+
|
|
855
|
+
export function buildRequest(argv: string[], flags: Flags): Record<string, unknown> {
|
|
856
|
+
const [cmd, ...rest] = argv;
|
|
857
|
+
const spec = COMMANDS.find((c) => c.cmd === cmd || (cmd !== undefined && (c.aliases ?? []).includes(cmd)));
|
|
858
|
+
if (!spec) die(`unknown command \`${cmd}\``);
|
|
859
|
+
return { cmd: spec.cmd, ...spec.cli(rest, flags) };
|
|
860
|
+
}
|