shortcutkit 0.6.1 → 0.8.1

package/README.md

@@ -34,18 +34,25 @@ files you are using.
   typed, and the `AppIntentDescriptor` the file needs is added for you.
 - **Parameters checked before you run anything.** `{ WFStoredContentGlobalValue: "yes" }` is a
   compile error; a switch takes a boolean or a reference. Enumeration choices are suggested.
-  Any plain value slot also accepts an attachment, because that is how Shortcuts works.
+  A plain value slot also accepts a reference where the engine reads one, and the type says
+  which: a Filter action's sort key takes none, a variable picker takes any except Ask, and the
+  engine was asked about every key (`PARAM_VARIABLE_TYPES`). Every action has a named
+  parameter type (`ShowresultParams`, `RemindersCreateReminderParams`), and its output content
+  types are on `ACTIONS[id].outputTypes` and on the returned `Action`.
 - **Value helpers that match the engine's serialization.** `ref()` to another action's output,
-  `variable()`, `shortcutInput()`, `clipboard()`, `currentDate()`, `ask()`, `text()` for
-  strings with embedded references, and `picker()` for variable-picker parameters. A bare
-  `ref()` given to a text parameter is wrapped into the token string the engine writes.
+  `variable()`, `shortcutInput()`, `clipboard()`, `currentDate()`, `ask()`, `deviceDetails()`,
+  `currentApp()`, `text()` for strings with embedded references. A bare `ref()` is what every
+  picker parameter takes; for a text parameter it is wrapped into the token string the engine
+  writes, and for an If subject into the form the app writes.
 - **Control flow.** `if()` / `otherwise()` / `endIf()`, `repeatEach()` / `endRepeatEach()`,
   `repeatCount()` / `endRepeatCount()` and `chooseFromMenu()` / `menuItem()` / `endMenu()`
   manage the grouping identifiers for you.
 - **App Intents from installed apps.** Any identifier outside the built-in set is accepted;
   built-in identifiers and their parameter keys are also validated at run time.
-- **Definitions and provenance.** `getDefinition(id)` returns the full record (icon, keywords,
-  parameter classes, required resources); `provenance` says which build produced the data.
+- **Definitions and provenance.** `getAction(id)` describes any identifier, built-in or App
+  Intent: name, parameter keys and kinds, output, descriptor. `getDefinition(id)` returns the
+  engine's full record for a built-in (icon, keywords, parameter classes, required resources);
+  `provenance` says which build produced the data.
 - **Signing.** `Shortcut.sign()` wraps `shortcuts sign` so the output imports on any device.
 
 ## How it compares
@@ -88,7 +95,7 @@ pip install shortcutkit
 ## Usage
 
 ```ts
-import { Shortcut, actions, ref, text } from "shortcutkit";
+import { Shortcut, actions, ref, text, shortcutInput } from "shortcutkit";
 
 const s = new Shortcut("Greeting", { color: "Teal" });
 const got = s.action(actions.getstoredcontent, { WFStoredContentKey: "greeting" });
@@ -99,6 +106,20 @@ Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut");
 
 Open the signed file and Shortcuts imports it.
 
+### Share sheet
+
+A shortcut offered from the share sheet declares its surfaces and the input it accepts, and
+reads that input with `shortcutInput()`:
+
+```ts
+const s = new Shortcut("Page Links", { types: ["ActionExtension"], inputClasses: ["WFSafariWebPageContentItem"] });
+const links = s.action(actions.runjavascriptonwebpage, { WFInput: shortcutInput(), WFJavaScript: "completion(document.links.length)" });
+s.action(actions.showresult, { Text: text("Links: ", ref(links)) });
+```
+
+`types` takes `ActionExtension` (share sheet), `QuickActions` (Finder and Services menus),
+`MenuBar`, `NCWidget`, `WatchKit`, `Sleep` and `ReceivesOnScreenContent`.
+
 ### Control flow
 
 `if()` returns a grouping identifier that the matching `otherwise()` and `endIf()` calls take
@@ -186,9 +207,23 @@ cd python && python3 -m venv .venv && .venv/bin/pip install -e .
 .venv/bin/python -m shortcutkit demo /tmp/Demo.shortcut
 ```
 
-CI runs the type check, the tests, a Node import of the built package, a Python install and an
-unsigned build of the demo shortcut on macOS. Signing is not exercised in CI because the runner
-has no iCloud login.
+CI runs the type check, the tests, a Node import of the built package, a Python install, the
+engine verification below and an unsigned build of the demo shortcut on macOS. Signing is not
+exercised in CI because the runner has no iCloud login.
+
+### Verifying against the engine
+
+```bash
+bun run verify        # ~3 min on a Mac that has opened Shortcuts.app once
+```
+
+Both packages are driven over every action, every parameter key and every value form their
+types admit, and the results are diffed against each other and then loaded through the
+Shortcuts engine's own action objects, which report whether each value was read. Forms the
+library refuses are written raw too, and the engine must refuse them as well. Whole shortcuts
+built through every block helper are imported the way the app imports a file. The run fails on
+any case the engine does not read; see `docs/extraction.md` for what it reports instead of
+failing.
 
 ### Repository layout