shortcutkit 0.1.0 → 0.2.0

package/README.md

@@ -7,17 +7,25 @@ Build, validate and sign Apple Shortcuts (`.shortcut`) files from TypeScript or
 
 ## About
 
-Shortcuts has no public file-format specification and no public list of what its actions
-accept. shortcutkit fills that gap by extracting the action definitions and value encodings
-from WorkflowKit, the engine inside the Shortcuts app, and generating a typed catalogue from
-them. Every one of the 339 built-in actions is available with its parameter keys and value
-shapes checked at compile time in TypeScript, or at run time in Python. Nothing was
-transcribed by hand, and `data/provenance.json` records exactly which macOS and Shortcuts build
-the data came from.
+Apple has never documented the `.shortcut` format or what its actions accept. shortcutkit
+does not guess at either. The tools in this repository load WorkflowKit and ActionKit, the private
+frameworks behind the Shortcuts app, and ask their own classes to describe and serialize
+every built-in action. Every action identifier, parameter key, value encoding, icon colour, and even the
+UTF-16 offset rule for embedded references came out of the engine, not from a person reading
+files. The package cannot disagree with the app.
+
+That turns an undocumented format into a typed one. In TypeScript, a wrong parameter key or a
+string where a boolean belongs is a compile error. In Python the same checks run when you call
+`action()`. A file built from plain code signs, imports and runs.
+
+The data stays current the same way it was made. After a macOS update, one command re-extracts
+everything in about a minute and prints a diff of what Apple changed, along with the semver
+bump it deserves. `data/provenance.json` records which macOS and Shortcuts build produced the
+files you are using.
 
 ## Features
 
-- **Every built-in action, typed.** `actions.*` lists all 339 identifiers, with each action's
+- **Every built-in action, typed.** `actions.*` lists all 392 identifiers, with each action's
   name, description, summary, output and parameter keys as hover documentation.
 - **Parameters checked before you run anything.** `{ WFStoredContentGlobalValue: "yes" }` is a
   compile error; a switch takes a boolean or a reference. Enumeration choices are suggested.
@@ -33,6 +41,21 @@ the data came from.
   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
+
+Every earlier library for writing Shortcuts as code kept its action list by hand, and that is
+how the two most used ones ended: [shortcuts-js](https://github.com/joshfarrant/shortcuts-js)
+(TypeScript, 129 actions, archived 2023) and
+[python-shortcuts](https://github.com/alexander-akhmetov/python-shortcuts) (Python, archived
+2024) both stopped once keeping up with Apple became a chore.
+[Cherri](https://github.com/electrikmilk/cherri) is the active project in this space and takes
+a different shape: a programming language with its own compiler, editor extension and package
+manager, whose actions are defined in that language.
+
+shortcutkit is a library, not a language. You write TypeScript or Python you already know, and
+the action catalogue comes from the Shortcuts engine rather than from a maintainer. All 392
+built-in actions are covered today, and the next macOS update is one `bun run extract` away.
+
 ## Installation
 
 ```bash
@@ -121,7 +144,7 @@ python -m shortcutkit demo out.shortcut
 
 - [`docs/shortcut-file-format.md`](docs/shortcut-file-format.md): the `.shortcut` format end
   to end, every field.
-- [`docs/builtin-actions-reference.md`](docs/builtin-actions-reference.md): all 339 built-in
+- [`docs/builtin-actions-reference.md`](docs/builtin-actions-reference.md): all 392 built-in
   actions with their parameters.
 - [`docs/parameter-encodings.md`](docs/parameter-encodings.md): how each parameter class is
   serialized.
@@ -161,10 +184,12 @@ Never hand-edit the generated files. Change the generator or the data and re-run
 
 The extracted data is committed on purpose. It can only be produced on a Mac, through private
 API that changes between releases, so committing it is what makes the package reproducible.
-To refresh after a macOS update, on a Mac with Xcode or the Command Line Tools:
+To refresh after a macOS update, on any Mac. No Xcode is needed: the probes are JavaScript
+for Automation scripts run by `osascript`, because ActionKit, which defines about a quarter of
+the built-in actions, only loads into Apple's own platform binaries.
 
 ```bash
-bun run extract        # ~1 minute: loads WorkflowKit, dumps and serializes everything
+bun run extract        # ~10 s: loads WorkflowKit and ActionKit in osascript, dumps and serializes everything
 bun install && bun test
 bun run diff-data      # what changed vs the committed data, and the semver bump it implies
 bun run changelog      # the same as a CHANGELOG.md section