Cursor plugin specification and official plugins
TypeScript
Keep only payload-field indexing in the script; cut internal context
Cursor Agent3bd5434dc47f
diff --git a/origin-apps/CHANGELOG.md b/origin-apps/CHANGELOG.mdindex 38ba40c9..0becd4d6 100644--- a/origin-apps/CHANGELOG.md+++ b/origin-apps/CHANGELOG.md@@ -1,15 +1,5 @@# Changelog-All notable changes to this plugin will be documented here.+## 0.1.0-## 0.1.0, initial release--- Added the `origin-api` skill. It lists the live Origin docs and OpenAPI spec- to fetch first, then the Origin rules that GitHub habits get wrong:- credentials and token minting, minimal scopes, webhook verification and- idempotency, opaque page tokens, TypeIDs, the error envelope, rate limits,- and the differences from GitHub that are decisions rather than gaps.-- Added the `port-github-app-to-origin` skill, built on `origin-api`. It reads- what a GitHub App uses from GitHub out of its codebase, maps that onto the- live Origin spec, and writes a porting brief with a capability table, a- webhook field map, a hello-world path, gap cards, and up-front questions.+Initial release with two skills, `origin-api` and `port-github-app-to-origin`.diff --git a/origin-apps/README.md b/origin-apps/README.mdindex 785328a9..c9955bf5 100644--- a/origin-apps/README.md+++ b/origin-apps/README.md@@ -31,7 +31,7 @@ Both skills fetch the spec at run time and never name an endpoint from memory.- Writing or reviewing code that calls Origin, mints installation tokens, orreceives Origin webhooks: `origin-api`.-- Creating an Origin App and wanting the first-week traps up front:+- Creating an Origin App and wanting the rules to know up front:`origin-api`.- Holding a GitHub App (Probot, Octokit, go-github, hand-rolled) and wantingto know what an Origin App version looks like before starting:@@ -50,11 +50,9 @@ or open Customize, find the plugin, and install it at user or project scope.## Use outside Cursor-The plugin ships three manifests for one set of skills. A root `plugin.json`-([Agent Plugins](https://agent-plugins.org) 1.0), `.cursor-plugin/plugin.json`-(Cursor Marketplace), and `.claude-plugin/plugin.json` (Claude Code). The-skills use only portable frontmatter (`name`, `description`, `license`,-`compatibility`).+The skills use only the portable+[Agent Skills](https://agentskills.io) frontmatter, so they work unchanged in+other agents.Claude Code, via the marketplace manifest at this repository's root:@@ -84,8 +82,8 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/needs no Origin credentials. You follow the brief's hello-world pathafterwards.- Optional: `python3` with PyYAML for the porting skill's- `scripts/index-origin-spec.py`, which turns the fetched spec into a- grep-friendly index. Without it the skill reads the spec directly.+ `scripts/index-origin-spec.py`, which prints webhook payload fields with+ their references resolved. Without it the skill reads the spec directly.## Where the brief goesdiff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.mdindex 3f1b2446..5ec551f8 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -9,8 +9,8 @@ description: >-license: MITcompatibility: >-Needs network access to https://cursor.com/docs/api/origin/* at run time.- The optional indexing script needs python3 with PyYAML; without it, read the- spec directly.+ The optional payload-field script needs python3 with PyYAML; without it,+ read the spec directly.---# Port a GitHub App to an Origin App@@ -35,8 +35,9 @@ GitHub. Follow it first. Nothing here repeats it. Two rules on top:1. **Load the spec** (`origin-api`, "Fetch first"). Record `info.version` andthe fetch time for the brief's provenance. Build the mapping index per- `references/spec-mapping.md`. `scripts/index-origin-spec.py openapi.yaml`- prints it and needs PyYAML.+ `references/spec-mapping.md`: two `rg` commands for operations, scopes,+ and slugs, and `scripts/index-origin-spec.py openapi.yaml` (needs PyYAML)+ for webhook payload fields.2. **Discover** per `references/discovery.md`. Record a file and line forevery fact, including payload fields read only for logging and calls theframework makes on the app's behalf. Note what you looked for and did not@@ -62,8 +63,7 @@ GitHub. Follow it first. Nothing here repeats it. Two rules on top:first is always native or mirror, because it decides whether the appreceives events at all.6. **Check the brief and fix.** Copy this list, tick each line, fix what- fails, and repeat until a pass changes nothing. Both validation runs found- a missed row on this pass.+ fails, and repeat until a pass changes nothing.- [ ] Every Origin cell names an `operationId`, slug, or anchor thatexists in the files fetched in step 1.@@ -94,4 +94,4 @@ cards to Cursor. The brief carries them and the team decides.| `references/origin-isms.md` | Labeling a missing GitHub feature. || `references/gap-bar.md` | Deciding whether a difference earns a card, and writing it. || `references/brief-template.md` | Writing the output. |-| `scripts/index-origin-spec.py` | Turning `openapi.yaml` into a grep-friendly index. Optional. |+| `scripts/index-origin-spec.py` | Listing webhook payload families with their fields resolved. Optional. |diff --git a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.mdindex 0fff925d..578d20eb 100644--- a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md+++ b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md@@ -1,7 +1,7 @@# The gap bar and the escalation cardMost differences are not gaps. A brief that files every difference buries the-two or three things Cursor needs to hear. When in doubt, write the row as+two or three that are worth raising. When in doubt, write the row as`workaround` with the tradeoff and an open question, not as a card.- A difference is any row whose parity label is not `same`.@@ -66,8 +66,8 @@ can act without a call.- **Spec version checked:** `<info.version>` on `<date>`.```-Do not propose scope, field, or route names. Cursor owns the shape. Do not-batch unrelated capabilities. Do not send cards yourself. The team decides+Do not propose scope, field, or route names. Do not batch unrelated+capabilities. Do not send cards yourself. The team decideswhat goes out, through their shared Slack channel with Cursor or to`[email protected]` with "Origin API" and the app name in the subject, quoting thespec version and any `X-Request-ID` from failed calls. "This is by design,diff --git a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.mdindex 836743a8..5c27442c 100644--- a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md+++ b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md@@ -14,22 +14,22 @@ table here. Build the index once. Every later step looks things up in it.## Build the index-1. **Operations**: `operationId`, method, path, `x-origin-scopes`,- visibility, parameter names, top-level request fields, response component.-2. **Webhook events**: slug → schema → properties and `$ref`s (or the- `x-origin-webhook-resource` target). From `llms-full.txt` § Webhooks,- which slugs are app-lifecycle (always delivered) versus repository events- (must be selected).-3. **Scopes**: the union of every `scopes` value, annotated with the- operations that need it. Separate installation-requestable scopes from- ambient and user-only ones. The user-only set tells you which GitHub flows- have no app-side equivalent.-4. **Resources**: component schemas returned by `Get…`/`List…`, with field+1. **Operations and scopes**: `rg -B1 -A4 'x-origin-scopes:' openapi.yaml`+ prints every `operationId` with its `scopes`, `tokenTypes`, and `ambient`+ flag. From it, note the union of scopes with the operations that need+ each, and separate installation-requestable scopes from ambient and+ user-only ones. The user-only set tells you which GitHub flows have no+ app-side equivalent. Read parameters and response components from the+ spec when a rule below asks for them.+2. **Webhook events**: `rg -A3 'x-origin-webhook-events:' openapi.yaml` lists+ every slug with its payload schema. `scripts/index-origin-spec.py+ openapi.yaml` prints each payload family with its fields and `$ref`s+ resolved two levels deep; `schema <Name>` does the same for one component.+ From `llms-full.txt` § Webhooks, note which slugs are app-lifecycle+ (always delivered) versus repository events (must be selected).+3. **Resources**: component schemas returned by `Get…`/`List…`, with fieldnames, for "does the Origin object carry this field".-`scripts/index-origin-spec.py openapi.yaml [ops|events|scopes|schema <Name>]`-prints all four.-## MatchingMatch in this order and stop at the first rule that yields a confirmeddiff --git a/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py b/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.pyindex 2bb1aa2a..b50ab04e 100644--- a/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py+++ b/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py@@ -1,16 +1,17 @@#!/usr/bin/env python3-"""Print a grep-friendly index of the Origin OpenAPI spec.+"""Print the Origin webhook payload families with their fields resolved.Usage:- python3 index-origin-spec.py openapi.yaml # everything- python3 index-origin-spec.py openapi.yaml ops # operations only- python3 index-origin-spec.py openapi.yaml events # webhook payload families- python3 index-origin-spec.py openapi.yaml scopes # scope catalog+ python3 index-origin-spec.py openapi.yaml # every payload familypython3 index-origin-spec.py openapi.yaml schema PullRequest # one componentFetch the spec first:curl -sSL https://cursor.com/docs/api/origin/openapi.yaml -o openapi.yaml+Operations and scopes do not need this script. Grep the spec directly:+ rg -B1 -A4 'x-origin-scopes:' openapi.yaml+ rg -A3 'x-origin-webhook-events:' openapi.yaml+Read-only. Needs PyYAML (`pip install pyyaml`). Everything printed comes fromthe spec you pass in; nothing is pinned or embedded here."""@@ -22,12 +23,17 @@ try:except ImportError: # pragma: no coversys.stderr.write("PyYAML is not installed. Run `pip install pyyaml`, or read the spec "- "directly (search for `operationId:`, `x-origin-scopes:`, and "- "`x-origin-webhook-events:`).\n"+ "directly (search for `x-origin-webhook-events:` and follow the "+ "`$ref`s by hand).\n")sys.exit(2)-METHODS = ("get", "post", "put", "patch", "delete")+# Field descriptions are cut to one sentence and this many characters so a+# family fits on one screen.+DESCRIPTION_CHARS = 140+# How many `$ref` levels to expand under a payload. Two reaches the embedded+# resource and its direct children, which is what field mapping needs.+SCHEMA_DEPTH = 2def ref_name(node):@@ -44,10 +50,10 @@ def ref_name(node):def first_sentence(text):- return " ".join((text or "").split()).split(". ")[0][:140]+ return " ".join((text or "").split()).split(". ")[0][:DESCRIPTION_CHARS]-def print_schema(components, name, depth=0, seen=None, max_depth=2):+def print_schema(components, name, depth=0, seen=None):seen = seen or set()schema = components.get(name)if not schema:@@ -58,86 +64,60 @@ def print_schema(components, name, depth=0, seen=None, max_depth=2):desc = first_sentence(node.get("description"))print(f"{' ' * depth}{field}: {kind}" + (f" -- {desc}" if desc else ""))inner = (ref_name(node) or "").rstrip("[]")- if inner and inner in components and depth < max_depth and inner not in seen:+ if inner and inner in components and depth < SCHEMA_DEPTH and inner not in seen:seen.add(inner)- print_schema(components, inner, depth + 1, seen, max_depth)---def print_ops(spec):- print("== OPERATIONS (operationId | METHOD path | scopes | tokenTypes | ambient | visibility)")- for path, methods in spec["paths"].items():- for method, op in methods.items():- if method not in METHODS:- continue- xs = op.get("x-origin-scopes") or {}- params = [p["name"] for p in op.get("parameters", [])]- body = None- rb = op.get("requestBody")- if rb:- schema = rb["content"]["application/json"]["schema"]- body = ref_name(schema) or list((schema.get("properties") or {}).keys())- resp = (- op.get("responses", {})- .get("200", {})- .get("content", {})- .get("application/json", {})- .get("schema", {})- )- print(- f"{op.get('operationId')} | {method.upper()} {path} | "- f"scopes={xs.get('scopes')} tokenTypes={xs.get('tokenTypes')} "- f"ambient={xs.get('ambient')} visibility={op.get('x-cursor-visibility')}"- )- print(f" params={params} body={body} -> {ref_name(resp) or '(empty)'}")- print(f" {first_sentence(op.get('description'))}")---def print_events(spec):- components = spec["components"]["schemas"]+ print_schema(components, inner, depth + 1, seen)+++def print_events(components):print("== WEBHOOK PAYLOAD FAMILIES (schema | slugs | x-origin-webhook-resource)")for name, schema in components.items():slugs = schema.get("x-origin-webhook-events")if not slugs:continueprint(f"{name} | {slugs} | resource={schema.get('x-origin-webhook-resource')}")- print_schema(components, name, depth=1, max_depth=2)---def print_scopes(spec):- print("== SCOPES (scope | tokenTypes seen | operations)")- table = {}- for path, methods in spec["paths"].items():- for method, op in methods.items():- if method not in METHODS:- continue- xs = op.get("x-origin-scopes") or {}- for scope in xs.get("scopes") or []:- entry = table.setdefault(scope, {"tokens": set(), "ops": [], "ambient": False})- entry["tokens"].update(xs.get("tokenTypes") or [])- entry["ops"].append(op.get("operationId"))- entry["ambient"] = entry["ambient"] or bool(xs.get("ambient"))- for scope in sorted(table):- e = table[scope]- print(f"{scope} | tokenTypes={sorted(e['tokens'])} ambient={e['ambient']} | {e['ops']}")+ print_schema(components, name, depth=1)+++def load_spec(path):+ try:+ with open(path, encoding="utf-8") as fh:+ spec = yaml.safe_load(fh)+ except FileNotFoundError:+ sys.stderr.write(f"{path}: not found. Fetch it first (command in --help).\n")+ return None+ except yaml.YAMLError as err:+ sys.stderr.write(f"{path}: not valid YAML ({err}).\n")+ return None+ if not isinstance(spec, dict) or "components" not in spec or "info" not in spec:+ sys.stderr.write(f"{path}: not an OpenAPI document (no `info` or `components`).\n")+ return None+ components = (spec.get("components") or {}).get("schemas") or {}+ if not any("x-origin-webhook-events" in s for s in components.values() if isinstance(s, dict)):+ sys.stderr.write(+ f"{path}: no schema carries `x-origin-webhook-events`; is this the Origin spec?\n"+ )+ return None+ return specdef main(argv):- if len(argv) < 2:+ if len(argv) < 2 or argv[1] in ("-h", "--help"):print(__doc__)return 1- with open(argv[1], encoding="utf-8") as fh:- spec = yaml.safe_load(fh)- mode = argv[2] if len(argv) > 2 else "all"+ spec = load_spec(argv[1])+ if spec is None:+ return 1+ components = spec["components"]["schemas"]+ schema_mode = len(argv) > 2 and argv[2] == "schema"+ if schema_mode and len(argv) < 4:+ sys.stderr.write("schema mode needs a component name.\n")+ return 1print(f"# {spec['info'].get('title')} {spec['info'].get('version')}")- if mode == "schema":- print_schema(spec["components"]["schemas"], argv[3])- return 0- if mode in ("ops", "all"):- print_ops(spec)- if mode in ("events", "all"):- print_events(spec)- if mode in ("scopes", "all"):- print_scopes(spec)+ if schema_mode:+ print_schema(components, argv[3])+ else:+ print_events(components)return 0