scripting-cli 1.5.0 → 2.0.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 +208 -5
- package/dist/agent_broker.d.ts +94 -0
- package/dist/agent_broker.js +387 -0
- package/dist/agent_cli.d.ts +4 -0
- package/dist/agent_cli.js +122 -0
- package/dist/agent_control.d.ts +16 -0
- package/dist/agent_control.js +197 -0
- package/dist/agent_protocol.d.ts +71 -0
- package/dist/agent_protocol.js +188 -0
- package/dist/cli.js +15 -2
- package/dist/controller.d.ts +6 -1
- package/dist/controller.js +79 -4
- package/dist/dev_terms.d.ts +9 -0
- package/dist/dev_terms.js +36 -0
- package/dist/skill_sync.d.ts +39 -0
- package/dist/skill_sync.js +311 -0
- package/dist/start_server.js +10 -6
- package/dist/util.d.ts +1 -1
- package/dist/util.js +7 -4
- package/package.json +4 -3
- package/skills/scripting-development/SKILL.md +60 -0
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Scripting App Command-Line Tool
|
|
2
2
|
|
|
3
|
+
Release notes and migration from 1.x: [scripting-cli 2.0.0](docs/releases/2.0.0.md).
|
|
4
|
+
|
|
3
5
|
Welcome to the `scripting-cli`, the command-line tool designed for integrating with the Scripting app. This tool allows you to synchronize and preview your scripts in real-time as you develop them using your favorite desktop editor (VSCode, Cursor, Windsurf, Zed, WebStorm, Vim, and more).
|
|
4
6
|
|
|
5
7
|
[中文](./README_zh.md) | [日本語](./README_ja.md) | [Deutsch](./README_de.md) | [Français](./README_fr.md) | [Italiano](./README_it.md)
|
|
@@ -31,8 +33,8 @@ npx scripting-cli <command>
|
|
|
31
33
|
Start by creating a directory where your Scripting app scripts will reside. For example:
|
|
32
34
|
|
|
33
35
|
```bash
|
|
34
|
-
mkdir my-scripting-
|
|
35
|
-
cd my-scripting-
|
|
36
|
+
mkdir my-scripting-workspace
|
|
37
|
+
cd my-scripting-workspace
|
|
36
38
|
```
|
|
37
39
|
|
|
38
40
|
### 2. Start the Local Service
|
|
@@ -61,7 +63,7 @@ Once the service is running, open the **Scripting app** and connect to the local
|
|
|
61
63
|
|
|
62
64
|
### 4. Debug and Synchronize Your Code
|
|
63
65
|
|
|
64
|
-
After connecting, select the script
|
|
66
|
+
After connecting, select the script you want to debug. The Scripting app will automatically sync the script’s code with your working directory.
|
|
65
67
|
|
|
66
68
|
### 5. Real-Time Code Synchronization
|
|
67
69
|
|
|
@@ -69,7 +71,7 @@ As you write and save scripts using your desktop editor (e.g., VSCode), the chan
|
|
|
69
71
|
|
|
70
72
|
## Editor Selection and Config File
|
|
71
73
|
|
|
72
|
-
`scripting-cli` is no longer tied to VSCode. The first time you run `npx scripting-cli start`, you'll be prompted to choose the editor you actually use. Your choice is saved to `scripting.config.json` in your
|
|
74
|
+
`scripting-cli` is no longer tied to VSCode. The first time you run `npx scripting-cli start`, you'll be prompted to choose the editor you actually use. Your choice is saved to `scripting.config.json` in your workspace root so the prompt won't appear again.
|
|
73
75
|
|
|
74
76
|
### Supported editors
|
|
75
77
|
|
|
@@ -205,4 +207,205 @@ If you encounter issues:
|
|
|
205
207
|
|
|
206
208
|
---
|
|
207
209
|
|
|
208
|
-
Enjoy using `scripting-cli` in your Scripting app development workflow. Happy coding!
|
|
210
|
+
Enjoy using `scripting-cli` in your Scripting app development workflow. Happy coding!
|
|
211
|
+
|
|
212
|
+
## Desktop agent commands
|
|
213
|
+
|
|
214
|
+
Codex, Claude Code, and other desktop agents can query the connected App's docs,
|
|
215
|
+
sync the current debug script, run it, and inspect results without a separate
|
|
216
|
+
agent-specific plugin. These commands require a compatible Scripting App with
|
|
217
|
+
Desktop Agent protocol v1 support. Older App versions can continue normal file
|
|
218
|
+
syncing but do not support the new commands.
|
|
219
|
+
|
|
220
|
+
1. Run `scripting-cli start` in your workspace.
|
|
221
|
+
2. Connect Scripting to that server. Select a script and enter its debug page.
|
|
222
|
+
3. The existing sync workflow creates `scripts/<script>/` in the workspace.
|
|
223
|
+
4. Run the commands below from that same workspace. The first release only
|
|
224
|
+
runs the App's selected debug script. Use the explicit scripts commands below
|
|
225
|
+
to create or change that selection; execution never switches it implicitly.
|
|
226
|
+
|
|
227
|
+
```sh
|
|
228
|
+
scripting-cli devices --json
|
|
229
|
+
scripting-cli status --json
|
|
230
|
+
scripting-cli docs search "Navigation" --json
|
|
231
|
+
scripting-cli docs get navigation --lang zh --json # use an ID returned by search
|
|
232
|
+
scripting-cli api get Navigation.present --json
|
|
233
|
+
scripting-cli run "MyScript" --json
|
|
234
|
+
scripting-cli run "MyScript" --query-parameters '{"sample":true}' --json
|
|
235
|
+
scripting-cli run "MyScript" --screenshot --capture-after 2 --output ./artifacts --json
|
|
236
|
+
scripting-cli widget "MyScript" --family systemMedium --json
|
|
237
|
+
scripting-cli widget "MyScript" --family systemMedium --parameter demo --screenshot --output ./artifacts --json
|
|
238
|
+
scripting-cli jobs show <run-id> --json
|
|
239
|
+
scripting-cli jobs cancel <run-id> --json
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
- With several connected devices, pass `--device <device-id>` from `devices`.
|
|
243
|
+
`devices` makes a fresh request and reports `responsive`; a connected socket
|
|
244
|
+
alone is not proof the App can execute a command. `status` includes foreground
|
|
245
|
+
state, the selected script, current revision, `activeRunId` and background-keeper state.
|
|
246
|
+
- Docs and API declarations come from the connected App, with its version in
|
|
247
|
+
the response. Search returns IDs and summaries; `docs get` reads one document.
|
|
248
|
+
There is no silent offline fallback to older docs.
|
|
249
|
+
- `run` and `widget` first capture a bounded source snapshot, sync all included
|
|
250
|
+
files, and wait for the App to acknowledge its SHA256 revision. Files changed
|
|
251
|
+
after the snapshot belong to a later update. Delayed notifications for the
|
|
252
|
+
already-applied snapshot do not cause an extra automatic run.
|
|
253
|
+
- Ordinary `run` waits for `Script.exit(result)` or failure. The default overall
|
|
254
|
+
deadline is 30 seconds (`--timeout`, 1–120). Forgetting to call `Script.exit`
|
|
255
|
+
can therefore produce a timeout. Request parameters retain the script's
|
|
256
|
+
normal App permission checks.
|
|
257
|
+
- `run --screenshot` requires Scripting in the foreground. It waits for this
|
|
258
|
+
run's view, waits `--capture-after` seconds (0–10, default 2), captures the
|
|
259
|
+
view, and ends this run. Its result says `completionReason: preview_capture`;
|
|
260
|
+
this is a finite preview, not proof the script exited itself or that all
|
|
261
|
+
remote content finished loading. No rendered view means an explicit error,
|
|
262
|
+
not a successful blank image.
|
|
263
|
+
- Both widget modes render the current script's `widget.tsx` in the App's
|
|
264
|
+
foreground preview and close automatically. Without `--screenshot`, no image
|
|
265
|
+
is generated. These commands do not install a home-screen widget or confirm
|
|
266
|
+
a WidgetKit timeline refresh. The supplied family/parameter do not overwrite
|
|
267
|
+
the user's normal preview preferences.
|
|
268
|
+
- `--no-sync` explicitly uses the last acknowledged App revision; it fails if
|
|
269
|
+
the revision is unknown or later file updates invalidated it. Active manual
|
|
270
|
+
runs or previews return `busy`, and commands do not stop them automatically.
|
|
271
|
+
- Ctrl-C requests cancellation of this command only. Cancellation, disconnect,
|
|
272
|
+
source failure, execution failure and screenshot failure remain distinct
|
|
273
|
+
results. A cancellation request stays `cancelling` until the App confirms a
|
|
274
|
+
terminal result; a missing confirmation is a failure, not proof execution stopped. Disconnected runs are not automatically replayed.
|
|
275
|
+
|
|
276
|
+
With `--json`, stdout contains one JSON value (a device array for `devices`, or a
|
|
277
|
+
job record for other commands). Jobs contain `runId`, `requestId`, `deviceId`,
|
|
278
|
+
`sessionId`, `script`, `requestedRevision`, `revision`, `status`, and `result` or `error`. The requested revision and the App-applied revision are separate; failed
|
|
279
|
+
preconditions do not claim that source was applied. Script
|
|
280
|
+
values are in `result.value`, logs in `result.stdout` / `result.stderr`, and
|
|
281
|
+
screenshots in `result.artifacts`. PNG files are copied to
|
|
282
|
+
`<output>/<run-id>/screenshot.png`; base64 image data is never printed to stdout.
|
|
283
|
+
Keep user-requested output files as long as needed. The private server retains
|
|
284
|
+
at most 64 job records / 8 image results, expires results after 15 minutes, and
|
|
285
|
+
removes its temporary results on shutdown.
|
|
286
|
+
|
|
287
|
+
Exit codes: `0` success, `1` command failure, `2` invalid CLI usage, `124` execution
|
|
288
|
+
or device timeout, `130` caller cancellation. Stable error codes include
|
|
289
|
+
`device_ambiguous`, `script_mismatch`, `debug_session_required`, `busy`,
|
|
290
|
+
`needs_foreground`, `sync_failed`, `missing_entry`, `screenshot_unavailable`, and
|
|
291
|
+
`unsupported_capability`. Inspect the result instead of treating a successful
|
|
292
|
+
connection or preview presentation as completed execution.
|
|
293
|
+
|
|
294
|
+
Source snapshots include at most 8 MiB and 2000 regular files, using the existing
|
|
295
|
+
ignore rules. Source symlinks and unsafe paths are rejected. Screenshots are
|
|
296
|
+
bounded to 8 MiB and 16 megapixels. The App preserves excluded files and the
|
|
297
|
+
script's permission identity. A separate authenticated loopback control server
|
|
298
|
+
connects desktop commands to the running service; its credentials live in a
|
|
299
|
+
private per-user OS temporary directory, not the script or command output.
|
|
300
|
+
The existing App-facing LAN / Tailscale server remains available for file sync.
|
|
301
|
+
|
|
302
|
+
### Tests
|
|
303
|
+
|
|
304
|
+
`npm test` builds the existing TypeScript sources and runs the checked-in Node
|
|
305
|
+
tests. It covers file/byte revisions, traversal and symlink refusals, device and
|
|
306
|
+
session selection, duplicate IDs, cancellation, disconnects, local HTTP control
|
|
307
|
+
boundaries, artifact delivery, retention, and actual CLI child processes. It
|
|
308
|
+
uses only owned temporary fixtures and removes them afterward. Real App
|
|
309
|
+
execution and screenshots also require App-side integration evidence; mocked
|
|
310
|
+
peers do not substitute for device rendering.
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
## Live feedback, ready screenshots, batches, and script management
|
|
314
|
+
|
|
315
|
+
The next capabilities are negotiated separately. An older protocol-v1 App can
|
|
316
|
+
still use first-release commands, but unsupported ready-log, streaming or script
|
|
317
|
+
commands fail explicitly.
|
|
318
|
+
|
|
319
|
+
```sh
|
|
320
|
+
scripting-cli run "MyScript" --stream
|
|
321
|
+
scripting-cli jobs events <run-id> --after 0 --json
|
|
322
|
+
scripting-cli scripts list --json
|
|
323
|
+
scripting-cli scripts inspect "MyScript" --json
|
|
324
|
+
scripting-cli scripts create "NewScript" --json
|
|
325
|
+
scripting-cli scripts attach "MyScript" --json
|
|
326
|
+
# Only after reviewing an App/desktop source conflict and choosing desktop source:
|
|
327
|
+
scripting-cli scripts attach "MyScript" --replace --expected-revision <App-revision-from-inspect> --json
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
`--stream` emits JSONL stage/log/diagnostic records with monotonic `seq` and run,
|
|
331
|
+
request, device, session identity, then one `type: result` record with `job`.
|
|
332
|
+
It replaces the single JSON result format even with `--json`. Sync, compilation,
|
|
333
|
+
execution, ready waiting, rendering and capture are distinct stages. Events keep
|
|
334
|
+
256 recent records and 64 KiB of streamed log text per job; `gap` reports a slow
|
|
335
|
+
reader falling behind retention. Final logs also report truncation. Diagnostics
|
|
336
|
+
are collected on failures within the original deadline, with script-relative
|
|
337
|
+
`file`, one-based `line`/`column`, TypeScript `code` and message when available;
|
|
338
|
+
runtime failures do not necessarily have a TypeScript diagnostic.
|
|
339
|
+
|
|
340
|
+
For data-driven UI, emit an explicit exact log when the intended state is ready:
|
|
341
|
+
|
|
342
|
+
```ts
|
|
343
|
+
console.log("SCREENSHOT_READY")
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Then run `scripting-cli run "MyScript" --screenshot --ready-log SCREENSHOT_READY --capture-after 1 --json`.
|
|
347
|
+
Only a non-error log from this run matches. Capture waits for both the signal and
|
|
348
|
+
a valid view before its settling delay; missing signals/views and foreground
|
|
349
|
+
loss never yield a successful screenshot. A script that exits without its signal
|
|
350
|
+
returns `ready_signal_missing`. Existing timeout rules remain unchanged.
|
|
351
|
+
|
|
352
|
+
`widget-batch "MyScript" --cases ./cases.json --timeout 60 --stream` runs one
|
|
353
|
+
source revision across 1...8 serial widget cases. A manifest is a JSON array:
|
|
354
|
+
|
|
355
|
+
```json
|
|
356
|
+
[
|
|
357
|
+
{"id":"small","family":"systemSmall","parameter":"default","screenshot":true},
|
|
358
|
+
{"id":"medium","family":"systemMedium","parameter":"empty","screenshot":true},
|
|
359
|
+
{"id":"render-only","family":"systemSmall","screenshot":false}
|
|
360
|
+
]
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
IDs use letters, digits, `_` and `-`, and must be unique. Results name each case
|
|
364
|
+
and any skipped cases; PNGs are `<output>/<run-id>/<case-id>.png`. Image bytes total
|
|
365
|
+
at most 8 MiB for the batch. A failed/cancelled batch can retain completed earlier
|
|
366
|
+
cases; remaining cases do not execute. Every preview uses foreground rendering
|
|
367
|
+
and closes automatically, without changing normal preview preferences.
|
|
368
|
+
|
|
369
|
+
Script commands need the App connected; create/attach also need foreground and
|
|
370
|
+
refuse an active manual run/preview. `create` uses an existing desktop directory
|
|
371
|
+
or creates a minimal local `script.json` / `index.tsx` scaffold when absent. App
|
|
372
|
+
name collisions return `script_exists`, without overwriting that App script.
|
|
373
|
+
A scaffold can remain locally if App creation is refused. `attach` publishes a
|
|
374
|
+
desktop snapshot and enters that script's debug page. Different App source
|
|
375
|
+
returns `script_conflict` with its current revision; only explicit `--replace`
|
|
376
|
+
plus the inspected `--expected-revision` permits replacement. A changed App
|
|
377
|
+
revision is rejected again at publication. Ignored files are preserved. The
|
|
378
|
+
server changes its watcher only after native success; delayed old-script events
|
|
379
|
+
cannot write into the newly selected script. Type declarations are refreshed
|
|
380
|
+
from the same App for desktop editing.
|
|
381
|
+
|
|
382
|
+
### Portable agent skill
|
|
383
|
+
|
|
384
|
+
The package includes [skills/scripting-development/SKILL.md](skills/scripting-development/SKILL.md).
|
|
385
|
+
`scripting-cli skill` prints the complete portable skill. It explains the
|
|
386
|
+
connected documentation → edit → execute → inspect screenshot → refine loop,
|
|
387
|
+
script conflicts, readiness, batches and cancellation for Codex/Claude Code.
|
|
388
|
+
Copy its directory into your agent's configured skill location if desired;
|
|
389
|
+
this command does not install it or change global agent configuration. Inspect
|
|
390
|
+
App/desktop conflicts and obtain authorization for the particular overwrite
|
|
391
|
+
before running the replacement command.
|
|
392
|
+
|
|
393
|
+
If the local service itself stops, commands report `control_unavailable`; they do not replay execution. Reconnect, inspect App status, and explicitly attach the intended script before a new run.
|
|
394
|
+
|
|
395
|
+
## Skill development
|
|
396
|
+
|
|
397
|
+
Select **Skill** in the App’s Development Server page, then choose a package. The server creates `skills/` beside `scripts/`; the selected package lives at `skills/<name>/`. App-only and desktop-only packages can be copied across. When both sides differ, choose the source in the App. Later desktop saves synchronize only that package and do not execute it. Stop and reselect after a source conflict or reconnect.
|
|
398
|
+
|
|
399
|
+
A package needs `SKILL.md` with `name` and `description` frontmatter. Its `.ts`/`.tsx`, references and binary assets synchronize; `.git`, dependencies and configured ignored files stay local. `skill.json` remains App-managed and is preserved. A package is limited to 8 MiB / 2000 synced files; paths differing only in case or Unicode normalization are rejected. Deleting a whole package or its `SKILL.md` on the desktop does not delete the App package.
|
|
400
|
+
|
|
401
|
+
Run an entry relative to the **currently selected** skill:
|
|
402
|
+
|
|
403
|
+
```sh
|
|
404
|
+
scripting-cli skills run my-skill scripts/main.tsx --stream
|
|
405
|
+
scripting-cli skills run my-skill scripts/main.tsx --check --json
|
|
406
|
+
scripting-cli skills run my-skill scripts/main.tsx --query-parameters '{"sample":true}' --timeout 30 --json
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
Each run synchronizes one complete source revision, pauses synchronization while testing, and returns stdout/stderr, the result from `Script.exit(value)`, exit code and errors. Skill identity, permissions, `Script.directory` and Storage/Keychain behavior match the App’s `scripting-ts run`. End successful scripts with `Script.exit(...)`; otherwise the run times out. `--check` checks without executing. `--stream`, `--device`, Ctrl-C and `jobs show/events/cancel` work as for script runs. Entry paths must stay inside the selected package. Skill runs do not support screenshots in this version.
|
|
410
|
+
|
|
411
|
+
Use an updated App and CLI for this capability. The existing singular `scripting-cli skill` still prints the portable development guide.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { SourceSnapshot } from './agent_protocol';
|
|
2
|
+
type SocketPeer = {
|
|
3
|
+
id: string;
|
|
4
|
+
connected: boolean;
|
|
5
|
+
on: (event: string, cb: (...args: any[]) => void) => unknown;
|
|
6
|
+
emit: (event: string, ...args: any[]) => unknown;
|
|
7
|
+
};
|
|
8
|
+
interface Peer {
|
|
9
|
+
socket: SocketPeer;
|
|
10
|
+
metadata?: any;
|
|
11
|
+
pending: Map<string, {
|
|
12
|
+
request: any;
|
|
13
|
+
resolve: (reply: any) => void;
|
|
14
|
+
reject: (error: Error) => void;
|
|
15
|
+
}>;
|
|
16
|
+
hooks: {
|
|
17
|
+
script?: () => string | null;
|
|
18
|
+
project?: () => string | null;
|
|
19
|
+
ignore: () => string[];
|
|
20
|
+
pause: () => void;
|
|
21
|
+
resume: (snapshot?: SourceSnapshot, bindingId?: string) => void;
|
|
22
|
+
skill?: () => {
|
|
23
|
+
name: string;
|
|
24
|
+
bindingId: string;
|
|
25
|
+
revision: string;
|
|
26
|
+
} | null;
|
|
27
|
+
skillReady?: () => Promise<void>;
|
|
28
|
+
switchScript?: (script: string) => Promise<void>;
|
|
29
|
+
switchProject?: (project: string) => Promise<void>;
|
|
30
|
+
types?: (files: Record<string, string>) => Promise<void>;
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
interface Job {
|
|
34
|
+
runId: string;
|
|
35
|
+
requestId: string;
|
|
36
|
+
deviceId: string;
|
|
37
|
+
sessionId: string;
|
|
38
|
+
script?: string;
|
|
39
|
+
skill?: string;
|
|
40
|
+
entry?: string;
|
|
41
|
+
requestedRevision?: string;
|
|
42
|
+
revision?: string;
|
|
43
|
+
status: string;
|
|
44
|
+
result?: any;
|
|
45
|
+
error?: {
|
|
46
|
+
code: string;
|
|
47
|
+
message: string;
|
|
48
|
+
};
|
|
49
|
+
createdAt: number;
|
|
50
|
+
cancellationRequested?: boolean;
|
|
51
|
+
fingerprint: string;
|
|
52
|
+
cancel?: () => void;
|
|
53
|
+
}
|
|
54
|
+
interface JobEvent {
|
|
55
|
+
seq: number;
|
|
56
|
+
type: string;
|
|
57
|
+
[key: string]: unknown;
|
|
58
|
+
}
|
|
59
|
+
export declare class AgentBroker {
|
|
60
|
+
readonly workspace: string;
|
|
61
|
+
private eventLogs;
|
|
62
|
+
private peers;
|
|
63
|
+
private jobs;
|
|
64
|
+
private activeMutations;
|
|
65
|
+
private artifactDirectory?;
|
|
66
|
+
constructor(workspace: string);
|
|
67
|
+
register(socket: SocketPeer, hooks: Peer['hooks']): void;
|
|
68
|
+
private invalidate;
|
|
69
|
+
private selectedScript;
|
|
70
|
+
private select;
|
|
71
|
+
private call;
|
|
72
|
+
devices(): Promise<any[]>;
|
|
73
|
+
submit(raw: unknown): Job;
|
|
74
|
+
private execute;
|
|
75
|
+
get(id: string): any;
|
|
76
|
+
cancel(id: string): any;
|
|
77
|
+
private publicJob;
|
|
78
|
+
private removeArtifact;
|
|
79
|
+
private statusFields;
|
|
80
|
+
private storeArtifact;
|
|
81
|
+
private event;
|
|
82
|
+
events(id: string, after: number): {
|
|
83
|
+
events: JobEvent[];
|
|
84
|
+
nextCursor: number;
|
|
85
|
+
truncated: boolean;
|
|
86
|
+
terminal: boolean;
|
|
87
|
+
logsTruncated: boolean;
|
|
88
|
+
};
|
|
89
|
+
private scaffold;
|
|
90
|
+
prune(now?: number): void;
|
|
91
|
+
close(): void;
|
|
92
|
+
}
|
|
93
|
+
export declare const agentBroker: AgentBroker;
|
|
94
|
+
export {};
|