@dxos/plugin-github 0.7.4 → 0.14.0

package/PLUGIN.mdl

@@ -0,0 +1,784 @@
+---
+id: org.dxos.plugin.github
+name: GitHubPlugin
+version: 0.1.0
+---
+
+Bidirectional GitHub integration for DXOS Composer.
+
+Connects one or more GitHub OAuth integrations to a space and keeps
+organizations, people, repositories, issues, and pull requests
+synchronized with ECHO.  Users select repositories as sync targets; owning
+organizations and their members are pulled automatically.  Local edits to
+issue title, description, and open/closed status are pushed back to GitHub
+via snapshot-diff reconciliation.
+
+## Extensions
+
+The following extension dialects are used in this document.
+Each extension is defined in the Appendix or resolved via its URI.
+
+| Term        | URI                            |
+|-------------|--------------------------------|
+| `type`      | `org.dxos.mdl.type@1.0`       |
+| `feat`      | `org.dxos.mdl.feat@1.0`       |
+| `scenario`  | `org.dxos.mdl.scenario@1.0`   |
+| `component` | `org.dxos.mdl.component@1.0`  |
+| `op`        | `org.dxos.mdl.op@1.1`         |
+| `test`      | `org.dxos.mdl.test@1.0`       |
+
+## Types
+
+```mdl
+type SyncTargetDescriptor
+  desc: Lightweight descriptor returned by GetGitHubRepositories; never stored in ECHO directly.
+  fields:
+    id: string            # stringified GitHub numeric repo id
+    name: string          # full_name e.g. "acme/anvil"
+    description?: string
+```
+
+```mdl
+type SyncOptions
+  desc: Per-target sync tuning knobs stored on Integration.targets[i].options.
+  fields:
+    maxDaysBack?: number  # pull issues/PRs updated within this many days; omit for full history
+```
+
+```mdl
+type GitHubUser
+  desc: Subset of the GitHub REST user object consumed by the sync service.
+  fields:
+    id: number
+    login: string
+    name?: string
+    email?: string
+    avatar_url?: string
+    html_url?: string
+```
+
+```mdl
+type GitHubOrg
+  desc: Subset of the GitHub REST org object.
+  fields:
+    id: number
+    login: string
+    name?: string
+    description?: string
+    blog?: string
+    avatar_url?: string
+    html_url?: string
+```
+
+```mdl
+type GitHubRepo
+  desc: Subset of the GitHub REST repo object.
+  fields:
+    id: number
+    name: string
+    full_name: string
+    description?: string
+    html_url?: string
+    archived?: boolean
+    owner: GitHubUser    # owner.login used to derive org lookup
+```
+
+```mdl
+type GitHubIssue
+  desc: Subset of the GitHub REST issue object; PRs appear here with a non-null pull_request field.
+  fields:
+    id: number
+    number: number
+    title: string
+    body?: string
+    state: open | closed
+    assignees?: GitHubUser[]
+    labels?: GitHubLabel[]
+    pull_request?: GitHubPullRef  # non-null → this item is a PR
+    created_at?: string
+    updated_at?: string
+    closed_at?: string
+```
+
+```mdl
+type GitHubLabel
+  fields:
+    name: string
+```
+
+```mdl
+type GitHubPullRef
+  desc: Minimal PR marker stored inline on a GitHubIssue.
+  fields:
+    url: string
+    merged_at?: string
+```
+
+```mdl
+type GitHubComment
+  fields:
+    id: number
+    body?: string
+    user?: GitHubUser
+    created_at?: string
+    updated_at?: string
+    html_url?: string
+```
+
+```mdl
+type ProjectSnapshot
+  desc: Fields recorded on Integration.snapshots after each pull; used to detect local divergence on push.
+  fields:
+    name: string          # recorded but push is intentionally disabled
+    description: string
+```
+
+```mdl
+type TaskSnapshot
+  desc: Fields recorded on Integration.snapshots after each pull; used to detect local divergence on push.
+  fields:
+    title: string
+    description: string
+    status: todo | done   # collapsed from GitHub open/closed
+```
+
+```mdl
+type SyncResult
+  desc: Counters returned by SyncGitHubRepositories.
+  fields:
+    pulled:
+      organizations: number
+      people: number
+      projects: number
+      tasks: number
+      comments: number
+```
+
+## Operations
+
+Discovery operations — read-only, no local writes.
+
+```mdl
+op GetGitHubRepositories
+  key: org.dxos.operation.github.getRepositories
+  desc: |
+    List GitHub repositories reachable from an integration token.
+    Read-only: no local objects are created.  Orgs are NOT listed here;
+    they are auto-pulled during SyncGitHubRepositories.
+  input:
+    connection: Ref<Connection>   # renamed from `integration`; see plugin-connector's ConnectorSpec
+  output: GetSyncTargetsOutput
+  effects: [http]
+  errors:
+    Unauthorized: token missing or revoked
+    NetworkError: transient HTTP failure after retries
+```
+
+```mdl
+op MaterializeGitHubTarget
+  key: org.dxos.operation.github.materializeTarget
+  desc: |
+    Find-or-create the empty local root Project bound to a selected GitHub repo, keyed by the
+    repo's foreign id, so a Cursor can reference it as its `spec.target`.
+  input:
+    connection: Ref<Connection>
+    remoteTarget?: RemoteTarget
+  output: { target: Ref<Obj> }
+  effects: [echo:write]
+```
+
+Effectful sync operations — pull from GitHub, push diverged fields back.
+
+```mdl
+op SyncGitHubRepositories
+  key: org.dxos.operation.github.syncRepositories
+  desc: |
+    Reconcile selected GitHub repositories plus their owning organizations,
+    members, issues, PRs, and (future) comments with ECHO.
+    Pull direction: upserts Organization, Person, Project, Task via foreign-key.
+    Push direction: snapshot-diffs Project.description and Task title /
+    description / status and PATCHes diverged fields back to GitHub.
+    PR status is pull-only (push is intentionally disabled).
+    Updates Integration.targets[i].lastSyncAt / lastError per target.
+  input:
+    connection: Ref<Connection>   # renamed from `integration`; every binding of the connection is synced
+    priority?: string             # cursor id to sync first
+  output: SyncResult
+  effects: [echo:read, echo:write, http]
+  errors:
+    Unauthorized: token missing or revoked
+    NetworkError: transient HTTP failure after retries
+    RepositoryNotAccessible: token cannot see one or more selected repos
+  note: |
+    Parallelism: up to 4 repos concurrently (REPO_CONCURRENCY); up to 4
+    issues per repo (ISSUE_CONCURRENCY).  Person upserts are serialized via
+    a semaphore + login-keyed cache to prevent duplicates across fibers.
+    Pagination: up to 10 pages per paginated endpoint (1 000 items max).
+```
+
+```mdl
+op ImportPullRequest
+  key: org.dxos.operation.github.importPullRequest
+  desc: |
+    Add one pull request to the space, named by a github.com URL or `owner/repo#number`,
+    so a reviewer with a link in hand need not sync the whole repository first.
+    Idempotent by owner/repo/number: a pull request the space already holds is returned
+    as it stands.  The object is filed via SpaceOperation.AddObject, not merely added.
+  input:
+    reference: string             # https://github.com/owner/repo/pull/123, or owner/repo#123
+  output: { pullRequest: Ref<PullRequest>, imported: boolean }
+  effects: [echo:read, echo:write, http]
+  errors:
+    GitHubPullRequestReferenceError: the text names no pull request
+    NetworkError: transient HTTP failure after retries
+
+```
+
+```mdl
+op ImportPullRequestFromSnapshot
+  key: org.dxos.operation.github.importPullRequestFromSnapshot
+  desc: |
+    The browser extension's page action: import the pull request the open page shows.
+    Nothing is extracted from the DOM — the snapshot's `source.url` names the pull request
+    and ImportPullRequest does the rest, so the anonymous-read fallback and the
+    already-held check are shared.  Answers with the object's id, which is the shape the
+    extension bridge acks and the Composer side opens.
+  input:
+    snapshot: PageAction.Snapshot   # the extension's generic page snapshot; only source.url is read
+    target: Database                # the active space's database
+  output: { id: string }
+  effects: [echo:read, echo:write, http]
+  errors:
+    GitHubPullRequestReferenceError: the page's URL names no pull request
+```
+
+```mdl
+op SubmitPullRequestApproval
+  key: org.dxos.operation.github.submitPullRequestApproval
+  desc: |
+    Approve a pull request as the space's GitHub connection.  Where GitHub refuses the
+    review -- 422 on the author's own pull request, 403 on a token without review
+    permission -- the approval is posted as a conversation comment carrying the
+    `<!-- dxos:approval state=approved -->` marker instead, so the verdict is recorded
+    and an agent polling the conversation can still read "good to land".  Any other
+    failure (401, network) surfaces rather than becoming a comment.
+  input:
+    pullRequest: Ref<PullRequest>
+    body?: string                 # review summary, kept above the marker in the comment
+  output: { reviewId?: number, commentId?: number, url?: string, commented: boolean }
+  effects: [echo:read, http]
+  errors:
+    Unauthorized: token missing or revoked
+```
+
+## Features
+
+```mdl
+feat F-1: OAuth Integration
+
+  req F-1.1:
+    when: user connects a GitHub integration
+    then: plugin-connector OAuth flow redirects to GitHub for authorization
+
+  req F-1.2:
+    when: OAuth callback completes
+    then: accessToken stored in ECHO; fetchUser called to set accessToken.account to user login
+
+  req F-1.3: Integration source is "github.com"; provider id is "github".
+```
+
+```mdl
+feat F-2: Repository Discovery
+
+  req F-2.1:
+    when: user opens the integration target picker
+    then: GetGitHubRepositories returns all repos visible to the token sorted by full_name (case-insensitive)
+
+  req F-2.2: No local ECHO objects are created during discovery.
+
+  req F-2.3: Owner, collaborator, and org-member repo affiliations are included.
+```
+
+```mdl
+feat F-3: Pull — Organizations and People
+
+  req F-3.1:
+    when: a selected repo is owned by a GitHub organization
+    then: that org is upserted as an Organization in ECHO (name, description, website, image)
+
+  req F-3.2:
+    when: org is synced
+    then: org members are upserted as Person objects linked to the Organization
+
+  req F-3.3: Personal-account repos (owner is not an org) skip org/member pull without error.
+
+  req F-3.4: A single org is pulled at most once per sync pass regardless of how many repos it owns.
+```
+
+```mdl
+feat F-4: Pull — Repositories as Projects
+
+  req F-4.1:
+    when: a selected repo does not yet have a local mirror
+    then: Project created in ECHO with foreign key [source: "github.com", id: String(repo.id)]
+
+  req F-4.2:
+    when: a selected repo already has a local mirror
+    then: Project fields updated via three-way merge against the stored snapshot
+
+  req F-4.3:
+    when: Integration.targets[i].object is missing or points at a different Project
+    then: target.object is rewired to the upserted Project
+```
+
+```mdl
+feat F-5: Pull — Issues and PRs as Tasks
+
+  req F-5.1:
+    when: issue/PR does not yet have a local mirror
+    then: Task created with fields title, description, status (open→todo, closed→done), assignee, project ref
+
+  req F-5.2:
+    when: issue/PR already has a local mirror
+    then: Task fields updated via three-way merge against stored snapshot
+
+  req F-5.3: PRs are treated identically to issues on pull; pull_request field marks them as PRs.
+
+  req F-5.4:
+    when: maxDaysBack is set on a target
+    then: only issues/PRs updated within that window are fetched from GitHub
+```
+
+```mdl
+feat F-6: Push — Local Edits Back to GitHub
+
+  req F-6.1:
+    when: Project.description diverges from the last pulled snapshot
+    then: PATCH /repos/{owner}/{repo} sends the new description
+
+  req F-6.2:
+    when: Task.title or Task.description diverges from snapshot
+    then: PATCH /repos/{owner}/{repo}/issues/{number} sends the updated fields
+
+  req F-6.3:
+    when: Task.status diverges from snapshot and the issue is not a PR
+    then: PATCH sends state: open or closed accordingly
+
+  req F-6.4:
+    when: PR status diverges locally
+    then: divergence is logged; push is skipped (PRs are pull-only for status)
+
+  req F-6.5: Project.name (repo rename) divergence is logged but never pushed.
+```
+
+```mdl
+feat F-7: Error Handling and Resilience
+
+  req F-7.1:
+    when: a per-target sync fails
+    then: lastError is set on that target; other targets continue
+
+  req F-7.2:
+    when: a repo is inaccessible to the integration token
+    then: lastError is set to "Repository not accessible to integration token"
+
+  req F-7.3:
+    when: an HTTP request returns 429 or 5xx
+    then: request is retried with exponential backoff + jitter (max 3 retries, 500 ms base)
+
+  req F-7.4:
+    when: sync succeeds
+    then: LayoutOperation.AddToast fires a success notification
+
+  req F-7.5:
+    when: sync fails
+    then: LayoutOperation.AddToast fires an error notification with a human-readable message
+```
+
+```mdl
+feat F-8: Link Previews
+
+  req F-8.1:
+    when: a document contains a repository, pull-request or issue URL
+    then: githubLinks (contributed via MarkdownCapabilities.ExtensionProvider) renders it as an anchor chip
+
+  req F-8.2:
+    when: the chip is activated
+    then: the plugin's PreviewCapabilities.LinkResolver answers with an in-memory Repo, PullRequest or Issue (@dxos/types), never stored
+
+  req F-8.3: The object comes from a contributed GitHubCapabilities.LinkSource when a host provides one; otherwise it is fetched from the GitHub API with the space's connection token, or anonymously when the space has none.
+
+  req F-8.4: GitHubCard is the CardContent surface for Repo, Issue and PullRequest, so the popover shows reference, state, author, diff size (or default branch) and a link out.
+```
+
+```mdl
+feat F-9: Pull Request Review
+
+  req F-9.1:
+    when: the user runs the "Import pull request" command and names a pull request
+    then: ImportPullRequest files it in the active space and the deck opens it
+
+  req F-9.2: The article's subject is the PullRequest, not its walkthrough — so a pull request with no narration yet opens, showing its state, CI outcome and a "Generate walkthrough" action.
+
+  req F-9.3:
+    when: the space holds a walkthrough of the open pull request
+    then: the article's Walkthrough tab renders its prose and diff chunks, and the toolbar action regenerates rather than generates
+
+  req F-9.4: A Walkthrough opened by id resolves to the same article, through the pull request it narrates.
+
+  req F-9.5:
+    when: the user clicks "Open PR in Composer" in the browser extension on a github.com pull
+      request page
+    then: ImportPullRequestFromSnapshot files that pull request in the active space, and the
+      extension's auto-open setting opens it in the deck
+
+  req F-9.6: The article opens on an Overview tab showing the pull request's live description as markdown, with the harness's Claude Code footer and CI's Composer preview block taken out of the prose.
+
+  req F-9.7: A link into the agent-artifacts R2 bucket renders as a pill that previews its image or video in place, and each such artifact, the Composer preview and the Claude Code session are listed as related cards in a masonry grid.
+
+  req F-9.8: The Overview lists every check run on the head commit, failures first, with its outcome, duration and a link to the provider's logs.
+
+  req F-9.9: The Overview shows the pull request's reference, state, CI outcome and branches as a read-only form in a details card.
+
+  req F-9.10: A Files tab shows one changed file at a time as the walkthrough's own diff chunk, beside a tree of every changed file with its change counts; the toolbar steps to the previous or next file.
+
+  req F-9.11:
+    when: the reader checks a file off, in the tree or with the toolbar's Reviewed action
+    then: the file counts as reviewed in that browser until a push changes it, and the toolbar action moves on to the next file
+```
+
+## Acceptance
+
+```mdl
+scenario T-1: Token account populated on connect
+  given: user completes GitHub OAuth
+  when: onTokenCreated fires
+  then:
+    - GET /user is called with the new token
+    - accessToken.account === user.login
+```
+
+```mdl
+scenario T-2: Repository discovery is read-only
+  given: valid GitHub integration
+  when: GetGitHubRepositories is invoked
+  then:
+    - list of SyncTargetDescriptor returned sorted by full_name
+    - no Organization, Person, Project, or Task objects are created in ECHO
+```
+
+```mdl
+scenario T-3: First sync — create Project and Tasks
+  given: integration with one selected repo (no prior local mirror)
+  when: SyncGitHubRepositories runs
+  then:
+    - Project created with foreign key for the repo
+    - one Task created per issue/PR
+    - open issues map to status todo; closed issues map to status done
+    - ProjectSnapshot and TaskSnapshot written for each object
+```
+
+```mdl
+scenario T-4: Incremental pull — remote-wins merge
+  given: integration with a previously synced repo; remote title changed
+  when: SyncGitHubRepositories runs
+  then:
+    - Task.title updated to remote value
+    - TaskSnapshot.title updated to match
+```
+
+```mdl
+scenario T-5: Push issue edit
+  given: Task.description differs from TaskSnapshot.description; issue is not a PR
+  when: SyncGitHubRepositories runs
+  then:
+    - PATCH /repos/{owner}/{repo}/issues/{number} called with new body
+    - TaskSnapshot.description updated to sent value
+```
+
+```mdl
+scenario T-6: PR status not pushed
+  given: Task (backed by a PR) status differs from snapshot
+  when: SyncGitHubRepositories runs
+  then:
+    - no PATCH issued for that task's status
+    - divergence logged at warn level
+```
+
+```mdl
+scenario T-7: Inaccessible repo error surfaced
+  given: integration target whose repo id is not in fetchUserRepos response
+  when: SyncGitHubRepositories runs
+  then:
+    - target.lastError === "Repository not accessible to integration token"
+    - other targets continue and complete normally
+```
+
+```mdl
+scenario T-8: Org deduplication
+  given: two selected repos with the same owner org
+  when: SyncGitHubRepositories runs
+  then:
+    - fetchOrg called once for that owner
+    - exactly one Organization upserted
+```
+
+```mdl
+scenario T-9: Personal-account owner skips org pull
+  given: selected repo owned by a GitHub user (not an org)
+  when: SyncGitHubRepositories runs
+  then:
+    - org lookup returns 404
+    - no Organization created; sync continues without error
+```
+
+```mdl
+scenario T-10: maxDaysBack filters issue window
+  given: target with maxDaysBack = 7
+  when: SyncGitHubRepositories runs
+  then:
+    - fetchRepoIssues called with since = (now − 7 days).toISOString()
+    - issues older than the window are not fetched
+```
+
+---
+
+## QA
+
+Executable tests. Each step carries a human instruction (`do`) and, where the step maps to an
+invocable operation, an agent binding (`invoke`). Report failures by test and step number.
+
+```mdl
+test QA-1: Connect, select a repository, and sync
+  desc: The core round-trip — authorize a GitHub connection, discover repos, materialize and sync one as a Project with its issues as Tasks.
+  actors: both
+  covers: [F-1.1, F-1.2, F-2.1, F-2.2, F-4.1, F-5.1, T-2, T-3]
+  status: unverified
+  given:
+    - an identity exists
+    - space: a space is open
+    - a GitHub account reachable for OAuth, owning at least one repo with at least one open issue
+    - no Project with foreign key [source: "github.com", id: <that repo's numeric id>] exists —
+      ABORT rather than reusing a Project this test did not create
+  steps:
+    - name: Connect a GitHub account
+      id: connect
+      do: Open the GitHub connector panel (Settings -> Connectors -> GitHub) and complete the OAuth authorization test.
+      capture: connection
+      expect: a Connection object exists with accessToken.account set to the authorized user's GitHub login
+      note: |
+        NO `invoke` — the OAuth redirect and callback are real browser navigation through GitHub's
+        consent screen; the debug port cannot drive it. This step is human-only for any account
+        that has not already authorized the app.
+    - name: Discover repositories
+      do: Open the target picker for the new connection.
+      invoke: [op:GetGitHubRepositories] { connection: $connection.connection }
+      capture: targets
+      expect: the picker lists repos visible to the token, sorted by full_name, and no Organization/Person/Project/Task objects are created yet
+      assert: return $result.targets.length > 0 && !$result.targets.some((t) => /^\d+$/.test(t.id) === false)
+    - name: Select the repository as a sync target
+      do: Pick the target repo from the list and confirm.
+      invoke: [op:MaterializeGitHubTarget] { connection: $connection.connection, remoteTarget: $targets.targets[0] }
+      capture: materialized
+      expect: an empty local root Project now exists, bound to the selected repo
+      assert: return !!$materialized.target
+    - name: Sync the connection
+      do: Click "Sync now" on the connection (or wait for the scheduled sync).
+      invoke: [op:SyncGitHubRepositories] { connection: $connection.connection }
+      capture: synced
+      expect: the Project's fields are populated from the repo, and one Task exists per open/closed issue and PR in that repo
+      assert: return $synced.pulled.projects >= 1 && $synced.pulled.tasks >= 1
+  after:
+    - name: Remove the synced Project and its Tasks
+      do: Right-click the Project in the navtree and choose Delete, then repeat for each Task it produced (or delete the containing collection).
+      invoke: org.dxos.operation.space.removeObjects { objects: [$materialized.target] }
+      expect: the Project and its Tasks leave the navtree; the underlying GitHub repo and issues are untouched
+    - name: Disconnect the GitHub account
+      do: In Settings -> Connectors -> GitHub, remove the connection.
+      expect: the Connection object and its stored access token are removed
+```
+
+```mdl
+test QA-2: Local edit pushes back to GitHub
+  desc: A push-direction check — editing a synced Task's title round-trips to the GitHub issue via PATCH.
+  actors: human
+  covers: [F-6.2, T-5]
+  status: unverified
+  given:
+    - an identity exists
+    - space: a space is open
+    - a GitHub account reachable for OAuth, with write access to a repo owning at least one open
+      (non-PR) issue
+    - no Project with foreign key [source: "github.com", id: <that repo's numeric id>] exists —
+      ABORT rather than reusing a Project this test did not create
+    - connection: a fresh GitHub Connection, authorized against that account (same human-only
+      OAuth step as QA-1's "Connect a GitHub account")
+    - materialized: the target repo materialized and synced as a Project via
+      op:MaterializeGitHubTarget then op:SyncGitHubRepositories (same steps as QA-1), leaving at
+      least one open (non-PR) Task
+  steps:
+    - name: Edit the task title
+      do: Open the synced Task and change its title.
+      expect: the edit is saved locally
+      note: NO `invoke` — this is an ordinary field edit through the Task surface, not a github operation.
+    - name: Re-sync
+      do: Click "Sync now" on the connection again.
+      invoke: [op:SyncGitHubRepositories] { connection: $given.connection }
+      expect: GitHub shows the issue's title updated to match, and the local TaskSnapshot.title now matches the new value
+      note: |
+        Verify by opening the issue on github.com — SyncGitHubRepositories's snapshot-diff push has
+        no separate read-back operation in this document, so the effect is checked against GitHub
+        itself (Execution Rule 3).
+  after:
+    - name: Revert the title on GitHub
+      do: Edit the issue's title back to its original value directly on github.com, then re-sync.
+      invoke: [op:SyncGitHubRepositories] { connection: $given.connection }
+      expect: the local Task.title reflects the reverted value
+    - name: Remove the synced Project and its Tasks
+      do: Right-click the Project in the navtree and choose Delete, then repeat for each Task it
+        produced (or delete the containing collection).
+      invoke: |
+        org.dxos.operation.space.removeObjects {
+          refs: [$given.materialized.target,
+            ...(await space.db.query(dxos.Filter.type(dxos.DXN.make('org.dxos.type.task'))).run()).objects
+              .filter((task) => task.project?.target?.id === $given.materialized.target.target?.id)
+              .map((task) => window.__echo.Ref.make(task))]
+        }
+      note: |
+        `materialized.target` is a Ref, so it travels in `refs`, not `objects`; the synced Tasks
+        are resolved separately because removing the Project does not cascade to them.
+      expect: the Project and its Tasks leave the navtree; the underlying GitHub repo and issues are untouched
+    - name: Disconnect the GitHub account
+      do: In Settings -> Connectors -> GitHub, remove the connection.
+      expect: the Connection object and its stored access token are removed
+```
+
+```mdl
+test QA-3: Open a pull request from the browser extension
+  desc: |
+    The plugin-crx page action, end to end through the operation it names.  Uses a public pull
+    request so no GitHub connection is needed — the import falls back to an anonymous read.
+  actors: both
+  covers: [F-9.5, F-9.3]
+  status: unverified
+  automated:
+    - composer-e2e:crx.spec.ts#Extension page actions › contributes the pull request action to the extension registry
+    - composer-e2e:crx.spec.ts#Extension page actions › imports the pull request the page names
+    - composer-e2e:crx-extension.spec.ts#Extension › opens the pull request the toolbar action is clicked on
+  given:
+    - an identity exists
+    - space: a space is open
+    - no PullRequest with owner "dxos", repo "dxos", number 1 exists — ABORT rather than
+      deleting one this test did not create
+  steps:
+    - name: Open the pull request from the extension
+      do: |
+        On https://github.com/dxos/dxos/pull/1, open the Composer extension side panel and click
+        "Open PR in Composer".  The extension captures the page snapshot and invokes the operation
+        against the active space.
+      invoke: |
+        org.dxos.operation.github.importPullRequestFromSnapshot {
+          snapshot: { source: { url: "https://github.com/dxos/dxos/pull/1", title: "chore: release 1.0.0 by github-actions[bot] - Pull Request #1 - dxos/dxos", clippedAt: "2026-09-22T00:00:00Z" } },
+          target: $given.space.db
+        }
+      capture: imported
+      expect: a PullRequest titled "chore: release 1.0.0" now exists in the space
+      assert: return !!$imported.id
+      note: |
+        Only `source.url` is read — the page title above is ignored, which is the point of the
+        operation taking a snapshot rather than an extraction.
+    - name: Re-invoke on the same pull request
+      do: Click "Open PR in Composer" again on the same page.
+      invoke: |
+        org.dxos.operation.github.importPullRequestFromSnapshot {
+          snapshot: { source: { url: "https://github.com/dxos/dxos/pull/1", title: "chore: release 1.0.0", clippedAt: "2026-09-22T00:00:00Z" } },
+          target: $given.space.db
+        }
+      expect: the same object is returned and the space still holds exactly one copy
+      assert: return $result.id === $imported.id
+    - name: Generate its walkthrough
+      do: Open the imported pull request and click "Generate walkthrough" in the article toolbar.
+      invoke: |
+        org.dxos.operation.github.generateWalkthrough { pullRequest: { "/": "echo://$given.space.id/$imported.id" } }
+      expect: the article renders narrated prose with the change's diff chunks spliced in
+      assert: return !!$result.walkthrough
+      note: |
+        Needs an AI provider configured — the only step here that does. GitHub itself is still read
+        anonymously, so no GitHub connection is required.
+  after:
+    - name: Delete the imported pull request
+      do: Right-click the pull request in the navtree and choose Delete.
+      invoke: |
+        org.dxos.operation.space.removeObjects { objects: [{ "/": "echo://$given.space.id/$imported.id" }], target: $given.space.db }
+      expect: the pull request no longer appears in the space
+```
+
+---
+
+## Appendix: Extension Definitions
+
+Extension block types used in this document are defined below using
+the core `ext` primitive — the only construct the base language provides.
+
+```mdl
+ext type
+  uri: org.dxos.mdl.type@1.0
+  desc: A named data structure with typed fields and optional literals.
+  fields:
+    desc?: Prose
+    fields?: FieldMap        # name[?]: TypeExpr  (# inline comment)
+    literals?: UnionList     # a | b | c
+    extends?: TypeRef[]
+```
+
+```mdl
+ext feat
+  uri: org.dxos.mdl.feat@1.0
+  desc: A named feature grouping one or more requirements.
+  fields:
+    desc?: Prose
+    req: RequirementList
+  nesting: self              # feat blocks may contain feat blocks
+```
+
+```mdl
+ext scenario
+  uri: org.dxos.mdl.scenario@1.0
+  desc: An acceptance scenario expressed as given / when / then steps.
+  fields:
+    given?: Step | Step[]
+    when?: Step | Step[]
+    then: Step | Step[]
+    tags?: TagList
+```
+
+```mdl
+ext component
+  uri: org.dxos.mdl.component@1.0
+  desc: A UI component with props, internal state, slots, actions, and events.
+  fields:
+    desc?: Prose
+    props?: FieldMap            # external inputs (immutable inside component)
+    state?: FieldMap            # internal reactive state
+    slots?: FieldMap            # named ReactNode injection points
+    actions?: ActionMap         # methods the component exposes or handles
+    emits?: EventMap            # events the component raises to its parent
+    layout?: CodeBlock          # ASCII sketch of visual structure (non-normative)
+```
+
+```mdl
+ext op
+  uri: org.dxos.mdl.op@1.1
+  desc: |
+    A named operation with typed inputs, outputs, and declared errors.
+    Pure ops have no effects or requires. Effectful ops declare both.
+  fields:
+    key?: NSID                  # runtime operation key — what the invoker receives
+    desc?: Prose
+    input?: FieldMap            # named input parameters
+    output?: TypeExpr           # return type
+    errors?: ErrorMap           # name: Prose  (when this error occurs)
+    effects?: EffectList        # echo:read | echo:write | http | fs | ...
+    requires?: ServiceList      # injected service dependencies
+    note?: Prose                # implementation guidance (non-normative)
+```