Skip to content

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.md
index 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.md
index 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, or
receives 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 wanting
to 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 path
afterwards.
- 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 goes
diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.md
index 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: MIT
compatibility: >-
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` and
the 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 for
every fact, including payload fields read only for logging and calls the
framework 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 app
receives 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 that
exists 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.md
index 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 card
Most 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 decides
what goes out, through their shared Slack channel with Cursor or to
`[email protected]` with "Origin API" and the app name in the subject, quoting the
spec 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.md
index 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 field
names, for "does the Origin object carry this field".
-`scripts/index-origin-spec.py openapi.yaml [ops|events|scopes|schema <Name>]`
-prints all four.
-
## Matching
Match in this order and stop at the first rule that yields a confirmed
diff --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.py
index 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 family
python3 index-origin-spec.py openapi.yaml schema PullRequest # one component
Fetch 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 from
the spec you pass in; nothing is pinned or embedded here.
"""
@@ -22,12 +23,17 @@ try:
except ImportError: # pragma: no cover
sys.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 = 2
def 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:
continue
print(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 spec
def 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 1
print(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