scripting-cli 2.0.0 → 2.0.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/README.md +13 -10
- package/package.json +1 -1
- package/skills/scripting-development/SKILL.md +4 -4
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Scripting App Command-Line Tool
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Latest release: [2.0.1](docs/releases/2.0.1.md). Migration from 1.x: [2.0.0](docs/releases/2.0.0.md).
|
|
4
4
|
|
|
5
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).
|
|
6
6
|
|
|
@@ -254,14 +254,15 @@ scripting-cli jobs cancel <run-id> --json
|
|
|
254
254
|
deadline is 30 seconds (`--timeout`, 1–120). Forgetting to call `Script.exit`
|
|
255
255
|
can therefore produce a timeout. Request parameters retain the script's
|
|
256
256
|
normal App permission checks.
|
|
257
|
-
- `run --screenshot`
|
|
257
|
+
- `run --screenshot` attempts capture in either foreground or background. It waits for this
|
|
258
258
|
run's view, waits `--capture-after` seconds (0–10, default 2), captures the
|
|
259
259
|
view, and ends this run. Its result says `completionReason: preview_capture`;
|
|
260
260
|
this is a finite preview, not proof the script exited itself or that all
|
|
261
261
|
remote content finished loading. No rendered view means an explicit error,
|
|
262
262
|
not a successful blank image.
|
|
263
263
|
- Both widget modes render the current script's `widget.tsx` in the App's
|
|
264
|
-
|
|
264
|
+
preview and close automatically. Rendering is attempted in either App state;
|
|
265
|
+
unavailable views, render errors or timeouts are reported. Without `--screenshot`, no image
|
|
265
266
|
is generated. These commands do not install a home-screen widget or confirm
|
|
266
267
|
a WidgetKit timeline refresh. The supplied family/parameter do not overwrite
|
|
267
268
|
the user's normal preview preferences.
|
|
@@ -345,8 +346,8 @@ console.log("SCREENSHOT_READY")
|
|
|
345
346
|
|
|
346
347
|
Then run `scripting-cli run "MyScript" --screenshot --ready-log SCREENSHOT_READY --capture-after 1 --json`.
|
|
347
348
|
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
|
|
349
|
-
|
|
349
|
+
a valid view before its settling delay; missing signals/views never yield a
|
|
350
|
+
successful screenshot. Backgrounding alone does not cancel a capture attempt. A script that exits without its signal
|
|
350
351
|
returns `ready_signal_missing`. Existing timeout rules remain unchanged.
|
|
351
352
|
|
|
352
353
|
`widget-batch "MyScript" --cases ./cases.json --timeout 60 --stream` runs one
|
|
@@ -363,15 +364,17 @@ source revision across 1...8 serial widget cases. A manifest is a JSON array:
|
|
|
363
364
|
IDs use letters, digits, `_` and `-`, and must be unique. Results name each case
|
|
364
365
|
and any skipped cases; PNGs are `<output>/<run-id>/<case-id>.png`. Image bytes total
|
|
365
366
|
at most 8 MiB for the batch. A failed/cancelled batch can retain completed earlier
|
|
366
|
-
cases; remaining cases do not execute. Every preview
|
|
367
|
-
and closes automatically, without changing normal preview preferences.
|
|
367
|
+
cases; remaining cases do not execute. Every preview attempts rendering in the
|
|
368
|
+
current App state and closes automatically, without changing normal preview preferences.
|
|
368
369
|
|
|
369
|
-
Script commands need the App connected; create/attach
|
|
370
|
-
refuse an active manual run/preview. `create` uses an existing desktop directory
|
|
370
|
+
Script commands need the App connected; create/attach can bind in the background
|
|
371
|
+
and refuse an active manual run/preview. `create` uses an existing desktop directory
|
|
371
372
|
or creates a minimal local `script.json` / `index.tsx` scaffold when absent. App
|
|
372
373
|
name collisions return `script_exists`, without overwriting that App script.
|
|
373
374
|
A scaffold can remain locally if App creation is refused. `attach` publishes a
|
|
374
|
-
desktop snapshot and
|
|
375
|
+
desktop snapshot and binds the script immediately. If the App is backgrounded,
|
|
376
|
+
its debug page appears when the App returns to the foreground; this does not
|
|
377
|
+
rerun the command. Different App source
|
|
375
378
|
returns `script_conflict` with its current revision; only explicit `--replace`
|
|
376
379
|
plus the inspected `--expected-revision` permits replacement. A changed App
|
|
377
380
|
revision is rejected again at publication. Ignored files are preserved. The
|
package/package.json
CHANGED
|
@@ -18,20 +18,20 @@ Use the connected App as the source of API documentation and runtime/rendering e
|
|
|
18
18
|
- `scripts list --json` lists App scripts. `scripts inspect "Script" --json` returns source file hashes and the current App revision without modifying it.
|
|
19
19
|
- `scripts create "Script" --json` creates from an existing desktop script, or scaffolds a minimal desktop script if absent; App name collisions are rejected. It does not overwrite a colliding App script.
|
|
20
20
|
- `scripts attach "Script" --json` syncs the desktop snapshot and selects that App debug script. Matching source needs no replacement flag. If source differs, `script_conflict` returns the current App revision. Inspect both versions and resolve the user's intended source before replacing anything. Only when the user has authorized that overwrite, use `scripts attach "Script" --replace --expected-revision <inspected-App-revision> --json`. A changed revision is a fresh conflict, not a reason to retry blindly.
|
|
21
|
-
- Script
|
|
21
|
+
- Script create/attach can bind in the background; the debug page appears upon foregrounding without rerunning the command. They refuse an existing manual run or preview. Do not stop unrelated work, overwrite scripts, install the skill globally, or publish packages merely to make a command succeed.
|
|
22
22
|
|
|
23
23
|
## Iterate using evidence
|
|
24
24
|
|
|
25
25
|
- Edit only the requested script. `run "Script" --query-parameters '{"sample":true}' --json` takes a bounded snapshot and executes only after the App confirms its revision. Use `requestedRevision` versus `revision` to distinguish attempted from applied source. Changes after snapshot capture belong to another run.
|
|
26
26
|
- Ordinary scripts should call `Script.exit(result)` to finish. Inspect `status`, `error.code`, `result.value`, stdout/stderr and diagnostics; a nonzero result is not success because a page once appeared. Diagnostic paths are script-relative, lines/columns are one-based. Runtime errors and TypeScript diagnostics are distinct evidence.
|
|
27
27
|
- Use `--stream` for JSONL stage/log/diagnostic events followed by one `type: result` record. It replaces single-result stdout formatting; never parse the entire stream as one JSON value. A `gap` means retained events were lost; final logs may also report `logsTruncated`.
|
|
28
|
-
- Use `run "Script" --screenshot --output ./artifacts --json` for a finite UI preview.
|
|
28
|
+
- Use `run "Script" --screenshot --output ./artifacts --json` for a finite UI preview. Capture is attempted in either App state; backgrounding alone does not cancel the run. Treat unavailable views or timeouts as actual failures. The screenshot belongs to this run, then the run ends; `preview_capture` does not mean the script called `Script.exit`.
|
|
29
29
|
- For asynchronous UI, emit a distinctive exact `console.log("SCREENSHOT_READY")` after the intended data/state is ready and invoke `--screenshot --ready-log SCREENSHOT_READY --capture-after 1`. Only the current run's matching non-error log counts. The marker is the script author's readiness contract, not automatic proof all remote work is complete. Missing signal/view or background transition must remain a failure.
|
|
30
30
|
- Open the actual PNG listed in `result.artifacts` using the host's image-viewing tool. Compare the requested layout and content, fix specific discrepancies, and rerun the affected case. A file path alone does not prove rendering correctness. Keep requested final output files; clean only disposable artifacts you created.
|
|
31
31
|
|
|
32
32
|
## Widgets and batches
|
|
33
33
|
|
|
34
|
-
`widget "Script" --family systemMedium --parameter demo --screenshot --output ./artifacts --json`
|
|
34
|
+
`widget "Script" --family systemMedium --parameter demo --screenshot --output ./artifacts --json` attempts rendering `widget.tsx` in either App state, captures if requested, then closes. Require actual render/image evidence; report the real renderer error or timeout when unavailable. Omit `--screenshot` for render-and-close without an image. This does not install a home-screen widget or verify WidgetKit timeline delivery, and it does not overwrite normal preview preferences.
|
|
35
35
|
|
|
36
36
|
For multiple sizes or parameters, create a JSON array such as:
|
|
37
37
|
|
|
@@ -51,7 +51,7 @@ The overall deadline is finite (`--timeout` 1–120 seconds, default 30). Do not
|
|
|
51
51
|
|
|
52
52
|
Ctrl-C or `jobs cancel <run-id> --json` requests cancellation of that owned run. `cancelling` is not confirmed termination. Inspect `jobs show <run-id> --json` until a terminal state; a disconnect/timeout is failure with potentially uncertain side effects, so do not replay mutating scripts automatically. `jobs events <run-id> --after <cursor> --json` reads recent events. Results expire; absence is not proof of no execution.
|
|
53
53
|
|
|
54
|
-
Preserve App permission checks.
|
|
54
|
+
Preserve App permission checks. Older Apps may still return `needs_foreground`; do not proactively block a request solely because status reports background. Handle `busy`, `unsupported_capability`, `script_conflict`, `execution_timeout` and `screenshot_unavailable` according to their actual meaning. Report unavailable device, VoiceOver, long-background, audio interruption or real WidgetKit evidence as pending. Do not claim those from desktop mocks or Simulator success.
|
|
55
55
|
|
|
56
56
|
## Develop a Skill package
|
|
57
57
|
|