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 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-project
35
- cd my-scripting-project
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 project you want to debug. The Scripting app will automatically sync the project’s code with your working directory.
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 project root so the prompt won't appear again.
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 {};