shortcutkit 0.8.1 → 1.0.0

package/README.md

@@ -1,274 +1,148 @@
 # shortcutkit
 
-Build, validate and sign Apple Shortcuts (`.shortcut`) files from TypeScript or Python.
+Build, validate, and sign Apple Shortcuts (`.shortcut`) files from TypeScript or Python.
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/frontboat/shortcutkit/ci.yml?branch=main)](https://github.com/frontboat/shortcutkit/actions)
+[![npm](https://img.shields.io/npm/v/shortcutkit)](https://www.npmjs.com/package/shortcutkit)
+[![PyPI](https://img.shields.io/pypi/v/shortcutkit)](https://pypi.org/project/shortcutkit/)
 
-## About
-
-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. Apple's own apps' actions come from the Shortcuts app's action index,
-the only readable copy of the App Intents registry. 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 434 identifiers, with each action's
-  name, description, summary, output and parameter keys as hover documentation.
-- **Apple's apps too.** 1,441 App Intents actions from 77 Apple apps and system components,
-  Create Reminder, Create Note, Send Message, the System Settings toggles, under the keys the
-  Shortcuts app itself assigns them: `actions.reminders_create_reminder`. Enumeration cases are
-  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.
-  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()`, `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.** `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
-
-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 434
-built-in actions and 1,441 Apple App Intents are covered today, and the next macOS update is
-one `bun run extract` away.
-
-## Installation
+A shortcut that asks your name and says hello:
 
-```bash
-npm install shortcutkit      # or: bun add shortcutkit
-```
+```ts
+import { Shortcut, actions, ref, text } from "shortcutkit";
 
-Python:
+const s = new Shortcut("Greeting");
+const name = s.action(actions.ask, { WFAskActionPrompt: "What's your name?" });
+s.action(actions.showresult, { Text: text("Hello, ", ref(name), "!") });
 
-```bash
-pip install shortcutkit
+await s.write(); // Greeting.shortcut
+Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut");
 ```
 
-### Requirements
+Open `Greeting-signed.shortcut` and Shortcuts adds it to your library. Shortcuts only imports
+signed files, and signing needs a Mac with an iCloud login; everything else runs on any OS.
 
-- Node 20 or newer, or Bun, for the TypeScript package. The published package is plain ES
-  module JavaScript with type declarations. Python 3.9 or newer for the Python package.
-- A Mac signed into iCloud for `sign()`. It runs `shortcuts sign`, which refuses to work
-  without an iCloud login even in `anyone` mode, so it cannot run on CI runners. `write()`
-  converts the plist to binary with `plutil` when present and otherwise leaves the XML form.
-  Building, validating and writing the unsigned file works anywhere.
+## Why
 
-## Usage
+The action catalog is extracted from the Shortcuts app's own frameworks, not written by hand,
+and one command refreshes it after a macOS update. Earlier libraries kept hand-written lists and
+are archived ([shortcuts-js](https://github.com/joshfarrant/shortcuts-js),
+[python-shortcuts](https://github.com/alexander-akhmetov/python-shortcuts));
+[Cherri](https://github.com/electrikmilk/cherri) is a separate language with its own compiler.
 
-```ts
-import { Shortcut, actions, ref, text, shortcutInput } from "shortcutkit";
+- All 434 built-in actions, typed, with documentation on hover.
+- 1,449 actions from Apple's apps: Reminders, Notes, Messages, Settings, and 73 more.
+- Third-party app actions, given their descriptor.
+- If, Repeat, Repeat with Each, and Choose from Menu blocks.
+- A wrong key or value fails at compile time in TypeScript, and at `action()` in Python.
 
-const s = new Shortcut("Greeting", { color: "Teal" });
-const got = s.action(actions.getstoredcontent, { WFStoredContentKey: "greeting" });
-s.action(actions.showresult, { Text: text("Stored: ", ref(got)) });
-await s.write();                                        // Greeting.shortcut
-Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut");
+## Install
+
+```bash
+npm install shortcutkit   # Node 20+ or Bun
+pip install shortcutkit   # Python 3.9+
 ```
 
-Open the signed file and Shortcuts imports it.
+## Usage
+
+These examples build on the one at the top.
 
 ### Share sheet
 
-A shortcut offered from the share sheet declares its surfaces and the input it accepts, and
-reads that input with `shortcutInput()`:
-
 ```ts
+import { shortcutInput } from "shortcutkit";
+
 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
-back:
-
 ```ts
-const gid = s.if(ref(got), "has_any_value");
-s.action(actions.showresult, { Text: text("Stored value: ", ref(got)) });
+const gid = s.if(ref(name), "has_any_value");
+s.action(actions.showresult, { Text: text("Hello, ", ref(name)) });
 s.otherwise(gid);
-s.action(actions.showresult, { Text: text("Nothing stored") });
+s.action(actions.showresult, { Text: text("Hello, stranger") });
 s.endIf(gid);
 ```
 
 ### Apple's apps
 
-Apple's App Intents actions are in the catalogue under the Shortcuts app's own keys. Their
-parameters are typed like the built-ins, and the `AppIntentDescriptor` every such action
-carries in the file is added automatically:
-
 ```ts
 const r = s.action(actions.reminders_create_reminder, { title: text("Buy milk"), priorityLevel: "high" });
 s.action(actions.notes_create_note, { name: "Shopping", content: text("Added ", ref(r)) });
 ```
 
-### Actions from other apps
+### Other apps
 
-Third-party App Intents actions are not in the catalogue, so pass the identifier as a string
-and the descriptor yourself. Parameter keys are then typed as `Record<string, Value>` and
-passed through as given:
+Pass the identifier and descriptor yourself; the parameters are untyped.
 
 ```ts
-s.action("com.example.app.CreateNote", { title: text("Hello"), body: ref(got) });
+s.action("com.example.app.CreateNoteIntent", {
+  AppIntentDescriptor: {
+    BundleIdentifier: "com.example.app", Name: "Example", TeamIdentifier: "ABCDE12345",
+    AppIntentIdentifier: "CreateNoteIntent", ActionRequiresAppInstallation: true,
+  },
+  title: text("Hello"),
+  body: ref(name),
+});
 ```
 
 ### Python
 
-Same API and same bundled data, with snake_case names and run-time value checks instead of
-compile-time ones:
+Same API in snake_case. See [`python/README.md`](python/README.md).
 
 ```python
 from shortcutkit import Shortcut, actions, ref, text
 
-s = Shortcut("Greeting", color="Teal")
-got = s.action(actions.GETSTOREDCONTENT, WFStoredContentKey="greeting")
-s.action(actions.SHOWRESULT, Text=text("Stored: ", ref(got)))
+s = Shortcut("Greeting")
+name = s.action(actions.ASK, WFAskActionPrompt="What's your name?")
+s.action(actions.SHOWRESULT, Text=text("Hello, ", ref(name), "!"))
+
 s.write()
 Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut")
 ```
 
-See [`python/README.md`](python/README.md) for the full Python surface.
-
-### Demo
-
-Both packages ship a demo that builds a working shortcut with storage, an If/Otherwise block
-and output:
-
-```bash
-bun run demo out.shortcut
-python -m shortcutkit demo out.shortcut
-```
-
-## Documentation
-
-- [`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 434 built-in
-  actions with their parameters.
-- [`docs/apple-app-intents-reference.md`](docs/apple-app-intents-reference.md): the 1,441 App
-  Intents actions of Apple's apps, by app, with parameter kinds and enumeration cases.
-- [`docs/parameter-encodings.md`](docs/parameter-encodings.md): how each parameter class is
-  serialized.
-- [`docs/extraction.md`](docs/extraction.md): how the data was obtained, what did not work,
-  and what remains approximate. A handful of condition codes rest on community documentation.
-
-## Development
-
-```bash
-git clone https://github.com/frontboat/shortcutkit.git && cd shortcutkit
-bun install
-bun test              # all tests
-bun run typecheck     # tsc --noEmit; also verifies the @ts-expect-error assertions in tests
-bun run build         # bundles src/ into dist/index.js for Node and emits the .d.ts files
-
-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, 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.
+## API
 
-### Repository layout
-
-| Path | Contents |
+| Export | What it does |
 |---|---|
-| `src/` | The TypeScript package source. `src/generated/actions.ts` is produced by the tools. `bun run build` bundles it into `dist/`, which is what npm ships. |
-| `python/` | The Python package. `actions.py` and `data/` are produced by the tools. |
-| `data/` | Everything extracted from the engine: definitions, parameter encodings, serialization table, `apple-app-intents.json` from the Shortcuts app's registry, and `provenance.json`. |
-| `docs/` | The format reference, action reference, encodings reference and extraction notes. |
-| `tools/` | The extraction pipeline. |
-
-Never hand-edit the generated files. Change the generator or the data and re-run the pipeline.
-
-### Regenerating the data
+| `new Shortcut(name, { color, glyph, types, inputClasses })` | A shortcut. |
+| `s.action(id, params)` | Appends an action and returns it. |
+| `s.if(subject, condition, value?)`, `s.otherwise(gid)`, `s.endIf(gid)` | An If block. |
+| `s.repeatEach(items)`, `s.endRepeatEach(gid)` | A Repeat with Each block. |
+| `s.repeatCount(n)`, `s.endRepeatCount(gid)` | A Repeat block. |
+| `s.chooseFromMenu(prompt, items)`, `s.menuItem(gid, title)`, `s.endMenu(gid)` | A Choose from Menu block. |
+| `s.write(path?)` | Writes the unsigned file and returns its path. |
+| `Shortcut.sign(input, output, mode?)` | Signs a file with `shortcuts sign`. |
+| `s.toPlist()`, `s.toXml()` | The shortcut as a plist object or XML. |
+| `ref(action)` | An action's output. |
+| `text(...parts)` | A string with references in it. |
+| `variable(name)`, `repeatItem()`, `repeatIndex()` | Named and repeat variables. |
+| `shortcutInput()`, `clipboard()`, `currentDate()`, `ask()`, `deviceDetails()`, `currentApp()` | Special variables. |
+| `actions`, `getAction(id)`, `getDefinition(id)` | Action identifiers and their catalog entries. |
+| `PARAM_KINDS`, `PARAM_CHOICES`, `PARAM_VARIABLE_TYPES` | What each parameter accepts. |
+| `CONDITION`, `ICON_COLORS`, `provenance` | If conditions, icon colors, and the build the data came from. |
 
-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 any Mac that has opened Shortcuts.app at least once. 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. Apple's App Intents come from the Shortcuts app's action index, which
-Shortcuts writes on launch.
+## Documentation
 
-```bash
-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
-```
+- [Shortcut file format](docs/shortcut-file-format.md)
+- [Built-in actions](docs/builtin-actions-reference.md)
+- [Apple app actions](docs/apple-app-intents-reference.md)
+- [Parameter encodings](docs/parameter-encodings.md)
+- [How the data was extracted](docs/extraction.md), and what is still approximate
 
-Both packages and the data are versioned together. A refresh that only adds actions or
-parameters is a minor release. One that removes or retypes any is a major release, because the
-generated catalogue is part of the type surface. Bump `package.json` and
-`python/pyproject.toml` together and add the `bun run changelog` output to `CHANGELOG.md`.
+## Status
 
-The tools also dump Apple's gallery workflows, installed apps' App Intents actions and the raw
-identifier list. Those files are local and gitignored.
+Extracted from macOS 27.2 and Shortcuts 10.0. A future macOS can break re-extraction, but not
+the published packages, which ship the data.
 
-## Status
+## Contributing
 
-Data extracted on macOS 27.0 with Shortcuts 10.0 (see `data/provenance.json`). Generated files
-declare minimum client version 900, which any current Shortcuts accepts. The private classes
-the tools call can change with any release; the package itself depends only on the committed
-data. Generated shortcuts import and run.
+Issues and pull requests are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 ## License
 
-shortcutkit is licensed under the MIT license. See [`LICENSE`](LICENSE) for details.
+[MIT](LICENSE).