shortcutkit 0.1.0__tar.gz

shortcutkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 frontboat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shortcutkit-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: shortcutkit
+Version: 0.1.0
+Summary: Build, validate and sign Apple Shortcuts (.shortcut) files.
+Author: frontboat
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/frontboat/shortcutkit
+Project-URL: Documentation, https://github.com/frontboat/shortcutkit/blob/main/docs/shortcut-file-format.md
+Project-URL: Repository, https://github.com/frontboat/shortcutkit.git
+Project-URL: Changelog, https://github.com/frontboat/shortcutkit/blob/main/CHANGELOG.md
+Keywords: apple,shortcuts,workflow,automation,macos,ios,plist
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# shortcutkit
+
+Build, validate and sign Apple Shortcuts (`.shortcut`) files from Python.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/frontboat/shortcutkit/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/frontboat/shortcutkit/ci.yml?branch=main)](https://github.com/frontboat/shortcutkit/actions)
+
+## About
+
+Shortcuts has no public file-format specification and no public list of what its actions
+accept. shortcutkit fills that gap with data extracted from WorkflowKit, the engine inside the
+Shortcuts app: every one of the 339 built-in actions is bundled with its identifier, parameter
+keys and the value kind each key accepts, and `action()` checks your parameters against them
+before anything is written. Pure Python, no dependencies. Signing shells out to the macOS
+`shortcuts` command; everything else runs anywhere.
+
+A TypeScript package of the same name shares the same data and adds compile-time checking.
+Both live at https://github.com/frontboat/shortcutkit.
+
+## Features
+
+- **Every built-in action, as a constant.** `actions.SETSTOREDCONTENT` and 338 more, so a
+  typo is an `AttributeError` rather than a silent bad file.
+- **Parameters checked before you write anything.** `ACTIONS[identifier]` gives the name,
+  parameter keys and output name; `PARAM_KINDS[identifier]` gives the value kind each key
+  accepts. Unknown keys and wrong kinds raise `ValueError`. Attachments and token strings are
+  accepted wherever a plain value is, because that is how Shortcuts works.
+- **Value helpers that match the engine's serialization.** `ref()` to another action's output,
+  `variable()`, `shortcut_input()`, `clipboard()`, `current_date()`, `ask()`, `text()` for
+  strings with embedded references, and `picker()` for variable-picker parameters.
+- **Control flow.** `if_()` / `otherwise()` / `end_if()` and `repeat_each()` /
+  `end_repeat_each()` manage the grouping identifiers for you.
+- **App Intents from installed apps.** Any identifier outside the built-in set is accepted and
+  its parameters are passed through as given.
+- **Reference tables.** `CONDITION` codes, `ICON_COLORS`, and `PROVENANCE` recording which
+  macOS and Shortcuts build the bundled data came from.
+
+## Installation
+
+```bash
+pip install shortcutkit
+```
+
+### Requirements
+
+- Python 3.9 or newer.
+- A Mac signed into iCloud for `Shortcut.sign()`. It runs `shortcuts sign`, which refuses to
+  work without an iCloud login even in `anyone` mode. Building and writing the unsigned file
+  works on any platform.
+
+## Usage
+
+```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.write()                                                        # Greeting.shortcut (unsigned)
+Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut")   # macOS
+```
+
+Open the signed file and Shortcuts imports it.
+
+### Control flow
+
+`if_()` returns a grouping identifier that the matching `otherwise()` and `end_if()` calls
+take back:
+
+```python
+gid = s.if_(ref(got), "has_any_value")
+s.action(actions.SHOWRESULT, Text=text("Stored value: ", ref(got)))
+s.otherwise(gid)
+s.action(actions.SHOWRESULT, Text=text("Nothing stored"))
+s.end_if(gid)
+```
+
+### Actions from other apps
+
+App Intents actions are not in the catalogue, so pass the identifier as a string:
+
+```python
+s.action("com.example.app.CreateNote", title=text("Hello"), body=ref(got))
+```
+
+### Demo
+
+The package ships a demo that builds a working shortcut with storage, an If/Otherwise block
+and output, then signs it:
+
+```bash
+python -m shortcutkit demo out.shortcut
+```
+
+## Documentation
+
+- [Shortcut file format](https://github.com/frontboat/shortcutkit/blob/main/docs/shortcut-file-format.md):
+  the `.shortcut` format end to end, every field.
+- [Built-in actions reference](https://github.com/frontboat/shortcutkit/blob/main/docs/builtin-actions-reference.md):
+  all 339 built-in actions with their parameters.
+- [Parameter encodings](https://github.com/frontboat/shortcutkit/blob/main/docs/parameter-encodings.md):
+  how each parameter class is serialized.
+- [Extraction notes](https://github.com/frontboat/shortcutkit/blob/main/docs/extraction.md):
+  how the data was obtained and what remains approximate.
+
+## Development
+
+From a checkout of the repository:
+
+```bash
+git clone https://github.com/frontboat/shortcutkit.git && cd shortcutkit/python
+uv venv .venv && uv pip install -e . --python .venv/bin/python   # or: python3 -m venv .venv && .venv/bin/pip install -e .
+.venv/bin/python -m shortcutkit demo /tmp/Demo.shortcut
+```
+
+`actions.py` and `data/` are generated by the repository's extraction tools from the Shortcuts
+engine on a Mac. Do not edit them; change the generator or the data and run `bun run extract`
+at the repository root. The Python and TypeScript packages are versioned together with the
+data, and are kept in feature parity.
+
+## License
+
+shortcutkit is licensed under the MIT license. See
+[LICENSE](https://github.com/frontboat/shortcutkit/blob/main/LICENSE) for details.

shortcutkit-0.1.0/README.md

@@ -0,0 +1,124 @@
+# shortcutkit
+
+Build, validate and sign Apple Shortcuts (`.shortcut`) files from Python.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/frontboat/shortcutkit/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/frontboat/shortcutkit/ci.yml?branch=main)](https://github.com/frontboat/shortcutkit/actions)
+
+## About
+
+Shortcuts has no public file-format specification and no public list of what its actions
+accept. shortcutkit fills that gap with data extracted from WorkflowKit, the engine inside the
+Shortcuts app: every one of the 339 built-in actions is bundled with its identifier, parameter
+keys and the value kind each key accepts, and `action()` checks your parameters against them
+before anything is written. Pure Python, no dependencies. Signing shells out to the macOS
+`shortcuts` command; everything else runs anywhere.
+
+A TypeScript package of the same name shares the same data and adds compile-time checking.
+Both live at https://github.com/frontboat/shortcutkit.
+
+## Features
+
+- **Every built-in action, as a constant.** `actions.SETSTOREDCONTENT` and 338 more, so a
+  typo is an `AttributeError` rather than a silent bad file.
+- **Parameters checked before you write anything.** `ACTIONS[identifier]` gives the name,
+  parameter keys and output name; `PARAM_KINDS[identifier]` gives the value kind each key
+  accepts. Unknown keys and wrong kinds raise `ValueError`. Attachments and token strings are
+  accepted wherever a plain value is, because that is how Shortcuts works.
+- **Value helpers that match the engine's serialization.** `ref()` to another action's output,
+  `variable()`, `shortcut_input()`, `clipboard()`, `current_date()`, `ask()`, `text()` for
+  strings with embedded references, and `picker()` for variable-picker parameters.
+- **Control flow.** `if_()` / `otherwise()` / `end_if()` and `repeat_each()` /
+  `end_repeat_each()` manage the grouping identifiers for you.
+- **App Intents from installed apps.** Any identifier outside the built-in set is accepted and
+  its parameters are passed through as given.
+- **Reference tables.** `CONDITION` codes, `ICON_COLORS`, and `PROVENANCE` recording which
+  macOS and Shortcuts build the bundled data came from.
+
+## Installation
+
+```bash
+pip install shortcutkit
+```
+
+### Requirements
+
+- Python 3.9 or newer.
+- A Mac signed into iCloud for `Shortcut.sign()`. It runs `shortcuts sign`, which refuses to
+  work without an iCloud login even in `anyone` mode. Building and writing the unsigned file
+  works on any platform.
+
+## Usage
+
+```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.write()                                                        # Greeting.shortcut (unsigned)
+Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut")   # macOS
+```
+
+Open the signed file and Shortcuts imports it.
+
+### Control flow
+
+`if_()` returns a grouping identifier that the matching `otherwise()` and `end_if()` calls
+take back:
+
+```python
+gid = s.if_(ref(got), "has_any_value")
+s.action(actions.SHOWRESULT, Text=text("Stored value: ", ref(got)))
+s.otherwise(gid)
+s.action(actions.SHOWRESULT, Text=text("Nothing stored"))
+s.end_if(gid)
+```
+
+### Actions from other apps
+
+App Intents actions are not in the catalogue, so pass the identifier as a string:
+
+```python
+s.action("com.example.app.CreateNote", title=text("Hello"), body=ref(got))
+```
+
+### Demo
+
+The package ships a demo that builds a working shortcut with storage, an If/Otherwise block
+and output, then signs it:
+
+```bash
+python -m shortcutkit demo out.shortcut
+```
+
+## Documentation
+
+- [Shortcut file format](https://github.com/frontboat/shortcutkit/blob/main/docs/shortcut-file-format.md):
+  the `.shortcut` format end to end, every field.
+- [Built-in actions reference](https://github.com/frontboat/shortcutkit/blob/main/docs/builtin-actions-reference.md):
+  all 339 built-in actions with their parameters.
+- [Parameter encodings](https://github.com/frontboat/shortcutkit/blob/main/docs/parameter-encodings.md):
+  how each parameter class is serialized.
+- [Extraction notes](https://github.com/frontboat/shortcutkit/blob/main/docs/extraction.md):
+  how the data was obtained and what remains approximate.
+
+## Development
+
+From a checkout of the repository:
+
+```bash
+git clone https://github.com/frontboat/shortcutkit.git && cd shortcutkit/python
+uv venv .venv && uv pip install -e . --python .venv/bin/python   # or: python3 -m venv .venv && .venv/bin/pip install -e .
+.venv/bin/python -m shortcutkit demo /tmp/Demo.shortcut
+```
+
+`actions.py` and `data/` are generated by the repository's extraction tools from the Shortcuts
+engine on a Mac. Do not edit them; change the generator or the data and run `bun run extract`
+at the repository root. The Python and TypeScript packages are versioned together with the
+data, and are kept in feature parity.
+
+## License
+
+shortcutkit is licensed under the MIT license. See
+[LICENSE](https://github.com/frontboat/shortcutkit/blob/main/LICENSE) for details.

shortcutkit-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shortcutkit"
+version = "0.1.0"
+description = "Build, validate and sign Apple Shortcuts (.shortcut) files."
+requires-python = ">=3.9"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "frontboat" }]
+keywords = ["apple", "shortcuts", "workflow", "automation", "macos", "ios", "plist"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/frontboat/shortcutkit"
+Documentation = "https://github.com/frontboat/shortcutkit/blob/main/docs/shortcut-file-format.md"
+Repository = "https://github.com/frontboat/shortcutkit.git"
+Changelog = "https://github.com/frontboat/shortcutkit/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+shortcutkit = ["data/*.json"]

shortcutkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shortcutkit-0.1.0/src/shortcutkit/__init__.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""shortcutkit: build, validate and sign Apple Shortcuts files from Python.
+
+The file format is the one Shortcuts.app uses (verified against Apple's gallery
+workflows in WorkflowKit and against this Mac's library). Actions and parameter keys
+are validated against _builtin-actions.json produced by extract-builtin-actions.sh.
+
+    from shortcutkit import Shortcut, ref, text, ask, shortcut_input, clipboard, variable
+
+    s = Shortcut("Demo", color="Teal", glyph=0xF000)
+    stored = s.action("is.workflow.actions.setstoredcontent",
+                      WFInput="hello", WFStoredContentKey="greeting", WFStoredContentGlobalValue=False)
+    got = s.action("is.workflow.actions.getstoredcontent", WFStoredContentKey="greeting")
+    s.action("is.workflow.actions.showresult", Text=text("Stored: ", ref(got)))
+    s.write("Demo.shortcut")            # unsigned plist
+    s.sign("Demo.shortcut", "Demo-signed.shortcut")   # runs `shortcuts sign --mode anyone`
+
+Command line:  python -m shortcutkit demo OUT.shortcut   (writes and signs the demo above)
+
+Value helpers return the exact structures WorkflowKit's state classes serialize:
+  ref(action)        WFTextTokenAttachment  -> that action's output
+  variable("Name")   WFTextTokenAttachment  -> a named variable
+  shortcut_input()   WFTextTokenAttachment  -> the shortcut's input
+  clipboard()        WFTextTokenAttachment  -> clipboard
+  current_date()     WFTextTokenAttachment  -> current date
+  ask("Prompt")      WFTextTokenAttachment  -> ask each time
+  text("a ", ref(x)) WFTextTokenString      -> text with embedded references
+  picker(att)        {"Type": "Variable", "Variable": att}  (variable-picker parameters)
+Plain str / int / float / bool / list are written as-is.
+"""
+import json
+import pathlib
+import plistlib
+import subprocess
+import sys
+import uuid
+
+HERE = pathlib.Path(__file__).resolve().parent
+DEFINITIONS = HERE / "data" / "builtin-actions.json"
+
+# WFWorkflowIcon.backgroundColorValue for palette colors 0-14, as the unsigned 32-bit
+# value the plist stores. Names follow Shortcuts' picker order.
+ICON_COLORS = {
+    "Red": 4282601983, "DarkOrange": 4251333119, "Orange": 4271458815, "Yellow": 4274264319,
+    "Green": 4292093695, "Teal": 431817727, "LightBlue": 1440408063, "Blue": 463140863,
+    "DarkBlue": 946986751, "Violet": 2071128575, "Purple": 3679049983, "Pink": 3980825855,
+    "Taupe": 255, "Gray": 3031607807, "DarkGray": 2846468607,
+}
+DEFAULT_GLYPH = 61440  # +[WFWorkflowIcon defaultGlyphCharacter]
+
+# Legacy WFCondition codes for is.workflow.actions.conditional. Shortcuts still reads these
+# and migrates them to the modern WFConditions template on load. Codes marked (v) were
+# verified against shortcuts on this Mac or Apple's gallery; the rest follow the same
+# enumeration as documented by the community (shortcuts-js, Cherri).
+CONDITION = {
+    "less_than": 0,            # (v) numbers
+    "less_or_equal": 1,
+    "greater_than": 2,         # (v) numbers
+    "greater_or_equal": 3,
+    "is": 4,
+    "is_not": 5,
+    "begins_with": 8,
+    "ends_with": 9,
+    "contains": 99,            # (v) as filter Operator in the gallery
+    "has_any_value": 100,      # (v) supportedComparisonOperators of every subject state
+    "has_no_value": 101,       # (v)
+    "does_not_contain": 999,
+    "is_between": 1003,
+}
+
+
+# Keys Shortcuts still accepts on load even though the current definition no longer lists
+# them. Legacy If: single condition on WFInput, migrated to WFConditions by the app.
+LEGACY_KEYS = {
+    "is.workflow.actions.conditional": {"WFInput", "WFCondition", "WFConditionalActionString", "WFNumberValue",
+                                        "WFConditionalLegacyComparisonBehavior", "WFEnumerationValue", "WFBooleanValue",
+                                        "WFDate", "WFAnotherDate", "WFDuration", "WFConditions"},
+    "is.workflow.actions.choosefrommenu": {"WFMenuPrompt", "WFMenuItems", "WFMenuItemTitle", "WFMenuItemAttributedTitle"},
+}
+
+
+def _is_reference(value):
+    """Attachments, token strings and picker wrappers are accepted wherever a plain value is."""
+    return isinstance(value, dict) and ("WFSerializationType" in value or value.get("Type") == "Variable")
+
+
+def _check_kind(kind, value):
+    """Run-time counterpart of the TypeScript ParamTypes: returns a problem string or None."""
+    if _is_reference(value):
+        return None
+    if kind == "bool" and not isinstance(value, bool):
+        return f"expected a bool or a reference, got {type(value).__name__}"
+    if kind in ("number", "plainNumber") and (isinstance(value, bool) or not isinstance(value, (int, float))):
+        return f"expected a number{'' if kind == 'plainNumber' else ' or a reference'}, got {type(value).__name__}"
+    if kind in ("string", "text", "plainString") and not isinstance(value, str):
+        return f"expected a string{'' if kind == 'plainString' else ' or a reference'}, got {type(value).__name__}"
+    if kind == "picker":
+        return "expected picker(<attachment>) or an attachment"
+    return None
+
+
+def _attachment(value):
+    return {"WFSerializationType": "WFTextTokenAttachment", "Value": value}
+
+
+def ref(action, output_name=None):
+    """Reference another action's output. `action` is the dict returned by Shortcut.action()."""
+    return _attachment({"Type": "ActionOutput", "OutputUUID": action["WFWorkflowActionParameters"]["UUID"],
+                        "OutputName": output_name or action.get("_outputName", "Output")})
+
+
+def variable(name):
+    return _attachment({"Type": "Variable", "VariableName": name})
+
+
+def shortcut_input():
+    return _attachment({"Type": "ExtensionInput"})
+
+
+def clipboard():
+    return _attachment({"Type": "Clipboard"})
+
+
+def current_date():
+    return _attachment({"Type": "CurrentDate"})
+
+
+def ask(prompt=None):
+    return _attachment({"Type": "Ask", **({"Prompt": prompt} if prompt else {})})
+
+
+def picker(attachment):
+    """Wrap an attachment for WFVariablePickerParameter keys (e.g. WFInput on Repeat with Each)."""
+    return {"Type": "Variable", "Variable": attachment}
+
+
+def text(*parts):
+    """A WFTextTokenString: strings and attachments interleaved. Each attachment becomes U+FFFC."""
+    string = ""
+    attachments = {}
+    for part in parts:
+        if isinstance(part, dict) and part.get("WFSerializationType") == "WFTextTokenAttachment":
+            # NSRange offsets are UTF-16 code units, not code points.
+            attachments[f"{{{len(string.encode('utf-16-le')) // 2}, 1}}"] = part["Value"]
+            string += ""
+        else:
+            string += str(part)
+    return {"WFSerializationType": "WFTextTokenString", "Value": {"string": string, "attachmentsByRange": attachments}}
+
+
+class Shortcut:
+    def __init__(self, name, color="Blue", glyph=DEFAULT_GLYPH, input_classes=None, definitions=DEFINITIONS):
+        self.name = name
+        self.color = ICON_COLORS[color] if isinstance(color, str) else color
+        self.glyph = glyph
+        self.input_classes = input_classes or []
+        self.actions = []
+        self.defs = json.load(open(definitions)) if pathlib.Path(definitions).exists() else {}
+
+    def action(self, identifier, **params):
+        """Append an action. Unknown identifiers or parameter keys raise ValueError."""
+        definition = self.defs.get(identifier)
+        if self.defs and definition is None and identifier.startswith("is.workflow."):
+            raise ValueError(f"unknown built-in action {identifier}")
+        if definition:
+            known = {p.get("Key") for p in definition.get("Parameters", []) if isinstance(p, dict)}
+            known |= {"UUID", "GroupingIdentifier", "WFControlFlowMode", "CustomOutputName"}
+            known |= LEGACY_KEYS.get(identifier, set())
+            inp = definition.get("Input")
+            if isinstance(inp, dict) and inp.get("ParameterKey"):
+                known.add(inp["ParameterKey"])
+            unknown = set(params) - known
+            if unknown and known - {"UUID", "GroupingIdentifier", "WFControlFlowMode", "CustomOutputName"}:
+                raise ValueError(f"{identifier}: unknown parameter(s) {sorted(unknown)}; known: {sorted(known)}")
+        for key, value in params.items():
+            problem = _check_kind(PARAM_KINDS.get(identifier, {}).get(key, "any"), value)
+            if problem:
+                raise ValueError(f"{identifier}.{key}: {problem}")
+        entry = {"WFWorkflowActionIdentifier": identifier,
+                 "WFWorkflowActionParameters": {"UUID": str(uuid.uuid4()).upper(), **params}}
+        output = (definition or {}).get("Output", {})
+        entry["_outputName"] = output.get("OutputName") if isinstance(output, dict) else None
+        if isinstance(entry["_outputName"], dict):
+            entry["_outputName"] = entry["_outputName"].get("format")
+        self.actions.append(entry)
+        return entry
+
+    # Control flow: each block is a group sharing a GroupingIdentifier, with
+    # WFControlFlowMode 0 = start, 1 = middle (Otherwise / menu item), 2 = end.
+    def if_(self, subject, condition, value=None):
+        gid = str(uuid.uuid4()).upper()
+        params = {"GroupingIdentifier": gid, "WFControlFlowMode": 0, "WFInput": picker(subject),
+                  "WFCondition": CONDITION[condition] if isinstance(condition, str) else condition}
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            params["WFNumberValue"] = value
+        elif value is not None:
+            params["WFConditionalActionString"] = value
+        self.action("is.workflow.actions.conditional", **params)
+        return gid
+
+    def otherwise(self, gid):
+        self.action("is.workflow.actions.conditional", GroupingIdentifier=gid, WFControlFlowMode=1)
+
+    def end_if(self, gid):
+        self.action("is.workflow.actions.conditional", GroupingIdentifier=gid, WFControlFlowMode=2)
+
+    def repeat_each(self, items):
+        """Open a Repeat with Each block; returns the grouping identifier to pass to end_repeat_each()."""
+        gid = str(uuid.uuid4()).upper()
+        self.action("is.workflow.actions.repeat.each", GroupingIdentifier=gid, WFControlFlowMode=0, WFInput=picker(items))
+        return gid
+
+    def end_repeat_each(self, gid):
+        self.action("is.workflow.actions.repeat.each", GroupingIdentifier=gid, WFControlFlowMode=2)
+
+    def to_plist(self):
+        actions = []
+        for a in self.actions:
+            actions.append({k: v for k, v in a.items() if not k.startswith("_")})
+        return {
+            "WFWorkflowClientVersion": "4018.0.4",
+            "WFWorkflowMinimumClientVersion": 900,
+            "WFWorkflowMinimumClientVersionString": "900",
+            "WFWorkflowIcon": {"WFWorkflowIconStartColor": self.color, "WFWorkflowIconGlyphNumber": self.glyph},
+            "WFWorkflowTypes": [],
+            "WFQuickActionSurfaces": [],
+            "WFWorkflowInputContentItemClasses": self.input_classes,
+            "WFWorkflowOutputContentItemClasses": [],
+            "WFWorkflowImportQuestions": [],
+            "WFWorkflowHasShortcutInputVariables": any(
+                json.dumps(a).find('"ExtensionInput"') >= 0 for a in actions),
+            "WFWorkflowHasOutputFallback": False,
+            "WFWorkflowActions": actions,
+        }
+
+    def write(self, path=None):
+        """Write the unsigned plist. Shortcuts names an imported shortcut after its file, so the
+        default file name is the shortcut's name."""
+        path = pathlib.Path(path) if path else pathlib.Path(f"{self.name}.shortcut")
+        with open(path, "wb") as f:
+            plistlib.dump(self.to_plist(), f, fmt=plistlib.FMT_BINARY)
+        return path
+
+    @staticmethod
+    def sign(src, dst, mode="anyone"):
+        subprocess.run(["shortcuts", "sign", "--mode", mode, "--input", str(src), "--output", str(dst)], check=True)
+        return dst
+
+
+def demo(out):
+    out = pathlib.Path(out)
+    s = Shortcut(out.stem, color="Teal")
+    stored = s.action("is.workflow.actions.setstoredcontent", WFInput="hello from python",
+                      WFStoredContentKey="demo-greeting", WFStoredContentGlobalValue=False)
+    got = s.action("is.workflow.actions.getstoredcontent", WFStoredContentKey="demo-greeting")
+    gid = s.if_(ref(got), "has_any_value")
+    s.action("is.workflow.actions.showresult", Text=text("Stored value: ", ref(got)))
+    s.otherwise(gid)
+    s.action("is.workflow.actions.showresult", Text=text("Nothing stored"))
+    s.end_if(gid)
+    unsigned = pathlib.Path(out).with_suffix(".unsigned.shortcut")
+    s.write(unsigned)
+    s.sign(unsigned, out)
+    print(f"wrote {out} ({len(s.actions)} actions)")
+
+
+from . import actions  # noqa: E402  (generated identifier constants and ACTIONS metadata)
+from .actions import ACTIONS, PARAM_KINDS  # noqa: E402
+
+PROVENANCE = json.load(open(HERE / "data" / "provenance.json")) if (HERE / "data" / "provenance.json").exists() else {}
+"""Which macOS and Shortcuts build the bundled data was extracted from."""
+
+__all__ = ["actions", "ACTIONS", "PARAM_KINDS", "PROVENANCE", "Shortcut", "ref", "variable", "shortcut_input", "clipboard", "current_date", "ask", "picker", "text",
+           "ICON_COLORS", "CONDITION", "DEFAULT_GLYPH", "LEGACY_KEYS", "demo"]
+__version__ = "0.1.0"

shortcutkit-0.1.0/src/shortcutkit/__main__.py

@@ -0,0 +1,7 @@
+import sys
+from . import demo
+
+if len(sys.argv) == 3 and sys.argv[1] == "demo":
+    demo(sys.argv[2])
+else:
+    sys.exit("usage: python -m shortcutkit demo OUT.shortcut")