paperclip-github-plugin 0.2.1 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +177 -181
- package/dist/manifest.js +1 -1
- package/dist/ui/index.js +537 -83
- package/dist/ui/index.js.map +4 -4
- package/dist/worker.js +287 -37
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,147 +1,147 @@
|
|
|
1
1
|
# paperclip-github-plugin
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
- GitHub
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
- Imports one top-level Paperclip issue per GitHub issue.
|
|
64
|
-
- Can ignore GitHub issues from configured usernames such as `renovate`.
|
|
65
|
-
- Preserves the original GitHub issue title without adding a prefix.
|
|
66
|
-
- Uses the normalized GitHub issue body as the Paperclip issue description.
|
|
67
|
-
- Normalizes GitHub HTML that Paperclip descriptions cannot render cleanly, including constructs such as `<br>`, `<hr>`, `<details>`, `<summary>`, and inline images.
|
|
68
|
-
- Re-syncs descriptions so imported Paperclip issues stay aligned with the latest GitHub issue body.
|
|
69
|
-
- Repairs missing or stale descriptions when Paperclip create/update flows return incomplete issue content.
|
|
70
|
-
- Deduplicates repeated sync runs so previously imported GitHub issues are not recreated.
|
|
71
|
-
- Repairs stale or missing import-registry entries by reusing existing imported Paperclip issues when durable GitHub metadata or older source-link metadata is present.
|
|
72
|
-
- Continues tracking previously imported issues, including closed issues, so status and metadata can still be reconciled after the initial import.
|
|
73
|
-
|
|
74
|
-
### Labels and metadata
|
|
75
|
-
|
|
76
|
-
- Maps GitHub labels onto Paperclip issue labels.
|
|
77
|
-
- Prefers exact color matches when multiple Paperclip labels share the same name.
|
|
78
|
-
- Creates missing Paperclip labels through the local Paperclip API when the host URL is known.
|
|
79
|
-
- Re-syncs label changes, including removing labels that were removed on GitHub.
|
|
80
|
-
- Adds a GitHub detail tab on synced Paperclip issues showing:
|
|
81
|
-
- GitHub repository
|
|
82
|
-
- GitHub issue number and link
|
|
83
|
-
- GitHub state and close reason
|
|
84
|
-
- comment count
|
|
85
|
-
- linked pull requests
|
|
86
|
-
- synced labels
|
|
87
|
-
- last synced time
|
|
88
|
-
- Recovers older linked issues into the detail tab when legacy sync metadata exists, and refreshes that metadata on the next sync.
|
|
89
|
-
|
|
90
|
-
### Status synchronization
|
|
91
|
-
|
|
92
|
-
- Open GitHub issue with no linked pull request imports into the configured default Paperclip status, which defaults to `backlog`.
|
|
93
|
-
- Open GitHub issue with unfinished CI on a linked pull request maps to `in_progress`.
|
|
94
|
-
- Open GitHub issue with failing CI or unresolved review threads on a linked pull request maps to `todo`.
|
|
95
|
-
- Open GitHub issue with green CI and all review threads resolved maps to `in_review`.
|
|
96
|
-
- Closed GitHub issue completed as finished work maps to `done`.
|
|
97
|
-
- Closed GitHub issue closed as `not_planned` or `duplicate` maps to `cancelled`.
|
|
98
|
-
- New GitHub comments move an open imported Paperclip issue back to `todo` only when the new comment came from the original issue author or a repository maintainer/admin that the worker can verify through the GitHub API.
|
|
99
|
-
- Existing open issues that are already `backlog` stay in `backlog` until a human changes them in Paperclip.
|
|
100
|
-
- When the plugin changes a Paperclip issue status, it adds a Paperclip comment explaining the transition.
|
|
101
|
-
- When comment annotations are supported by the host, those transition comments also surface GitHub issue and pull request links directly under the comment.
|
|
102
|
-
|
|
103
|
-
### Resilience and safety
|
|
104
|
-
|
|
105
|
-
- Raw GitHub tokens are never persisted in plugin state.
|
|
106
|
-
- Raw GitHub tokens loaded from `~/.paperclip/plugins/github-sync/config.json` stay worker-local and are never returned by public data endpoints.
|
|
107
|
-
- Raw Paperclip board tokens are never persisted in plugin state or plugin config.
|
|
108
|
-
- Scheduled sync skips runs that are not due yet.
|
|
109
|
-
- Incomplete setup is surfaced as configuration guidance instead of silently failing.
|
|
110
|
-
- Authenticated deployments are detected before sync starts, and the plugin blocks sync until the required company board access has been connected.
|
|
111
|
-
- GitHub rate limiting pauses sync until the reported reset time and prevents pointless retries while the pause is active.
|
|
112
|
-
- Direct Paperclip REST label and issue calls attach the saved board token automatically when one has been connected for the mapping company.
|
|
113
|
-
- Sync failures retain repository and issue diagnostics to make troubleshooting easier.
|
|
114
|
-
|
|
115
|
-
## Paperclip surfaces added by this plugin
|
|
116
|
-
|
|
117
|
-
- Dashboard widget with setup/readiness messaging, last sync status, and a link to settings.
|
|
118
|
-
- Settings page for token validation, repository mappings, company-wide advanced defaults, save, and manual sync.
|
|
119
|
-
- Global toolbar action for a full sync.
|
|
120
|
-
- Project toolbar action for targeted project sync.
|
|
121
|
-
- Issue toolbar action for targeted issue sync.
|
|
122
|
-
- Issue detail tab for GitHub metadata.
|
|
123
|
-
- Comment annotation surface for GitHub references attached to sync-generated status transition comments.
|
|
3
|
+
[](https://www.npmjs.com/package/paperclip-github-plugin)
|
|
4
|
+
[](https://github.com/alvarosanchez/paperclip-github-plugin/actions/workflows/ci.yml)
|
|
5
|
+
[](https://www.npmjs.com/package/paperclip-github-plugin)
|
|
6
|
+
[](https://github.com/alvarosanchez/paperclip-github-plugin/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
GitHub Sync is a Paperclip plugin for teams that plan in Paperclip but still receive work through GitHub issues.
|
|
9
|
+
|
|
10
|
+
It connects GitHub repositories to Paperclip projects, imports open issues as top-level Paperclip issues, keeps those issues updated over time, and gives Paperclip agents first-class GitHub workflow tools for triage and delivery.
|
|
11
|
+
|
|
12
|
+
## Why teams use GitHub Sync
|
|
13
|
+
|
|
14
|
+
GitHub is often where work appears first, but it is not always where teams want to plan, prioritize, and coordinate. GitHub Sync lets GitHub stay the source of incoming work while Paperclip becomes the place where the team manages it.
|
|
15
|
+
|
|
16
|
+
With this plugin, you can:
|
|
17
|
+
|
|
18
|
+
- connect one or more GitHub repositories to Paperclip projects
|
|
19
|
+
- import open GitHub issues into Paperclip without adding title prefixes or duplicate issues
|
|
20
|
+
- keep descriptions, labels, and status aligned with GitHub over time
|
|
21
|
+
- configure mappings and import defaults per Paperclip company
|
|
22
|
+
- run sync manually or on a schedule
|
|
23
|
+
- give Paperclip agents native GitHub tools for issues, pull requests, CI, and review threads
|
|
24
|
+
|
|
25
|
+
## What you get in Paperclip
|
|
26
|
+
|
|
27
|
+
The plugin adds a full in-host workflow instead of a one-off import script:
|
|
28
|
+
|
|
29
|
+
- a hosted settings page for GitHub auth, repository mappings, company defaults, and sync controls
|
|
30
|
+
- a dashboard widget that shows readiness, sync status, and last-run results
|
|
31
|
+
- saved sync diagnostics that let operators inspect the latest per-issue failures, raw errors, and suggested next steps
|
|
32
|
+
- manual sync actions from global, project, and issue toolbar surfaces
|
|
33
|
+
- a GitHub detail tab on synced Paperclip issues
|
|
34
|
+
- GitHub link annotations on sync-generated status transition comments when the host supports comment annotations
|
|
35
|
+
|
|
36
|
+
## How it works
|
|
37
|
+
|
|
38
|
+
1. Save a GitHub token in the plugin settings.
|
|
39
|
+
2. Connect one or more GitHub repositories to Paperclip projects.
|
|
40
|
+
3. Run a sync manually or let the scheduled job keep things up to date.
|
|
41
|
+
|
|
42
|
+
During sync, the plugin imports one top-level Paperclip issue per GitHub issue, updates already imported issues instead of recreating them, maps GitHub labels into Paperclip labels, and keeps GitHub-specific metadata in dedicated Paperclip surfaces rather than stuffing everything into the issue description.
|
|
43
|
+
|
|
44
|
+
Long-running syncs continue in the background, so quick actions do not have to wait for the whole import to finish. Once a sync has started, the settings page, dashboard widget, and toolbar actions can request cancellation; the worker stops cooperatively after the current repository or issue step finishes.
|
|
45
|
+
|
|
46
|
+
## Highlights
|
|
47
|
+
|
|
48
|
+
### Company-aware configuration
|
|
49
|
+
|
|
50
|
+
GitHub tokens and sync cadence are shared at the plugin instance level, while repository mappings, advanced import defaults, and Paperclip board access are managed per company. When you open settings inside a specific company, you only edit that company's mappings and defaults.
|
|
51
|
+
|
|
52
|
+
### Project binding that respects existing work
|
|
53
|
+
|
|
54
|
+
If a company already has a Paperclip project bound to a GitHub repository workspace, the settings UI can reuse that project instead of creating a duplicate. New mappings can also create and bind a Paperclip project automatically.
|
|
55
|
+
|
|
56
|
+
### Status sync with delivery context
|
|
57
|
+
|
|
58
|
+
The plugin does more than mirror issue text. It looks at linked pull requests, CI, review threads, and trusted new GitHub comments so imported Paperclip issues can reflect where the work actually is.
|
|
59
|
+
|
|
60
|
+
### Agent workflows built in
|
|
61
|
+
|
|
62
|
+
Paperclip agents can search GitHub for duplicates, read and update issues, post comments, create pull requests, inspect changed files and CI, reply to review threads, resolve or unresolve threads, and request reviewers without leaving the Paperclip plugin surface.
|
|
124
63
|
|
|
125
64
|
## Requirements
|
|
126
65
|
|
|
127
66
|
- Node.js 20+
|
|
128
|
-
-
|
|
129
|
-
-
|
|
130
|
-
|
|
67
|
+
- a Paperclip host that supports plugin installation
|
|
68
|
+
- a GitHub token with API access to the repositories you want to sync
|
|
69
|
+
|
|
70
|
+
## Install from npm
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npx paperclipai plugin install paperclip-github-plugin
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
If you are installing into an isolated Paperclip instance, include the CLI flags you normally use for `--data-dir` and `--config`.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npx paperclipai plugin install paperclip-github-plugin \
|
|
80
|
+
--data-dir /path/to/paperclip-data \
|
|
81
|
+
--config /path/to/paperclip.config.json
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Install from a local checkout
|
|
131
85
|
|
|
132
|
-
|
|
86
|
+
If you are developing the plugin locally or testing an unpublished change, you will also need `pnpm`:
|
|
133
87
|
|
|
134
88
|
```bash
|
|
135
89
|
pnpm install
|
|
136
90
|
pnpm build
|
|
137
|
-
npx
|
|
91
|
+
npx paperclipai plugin install --local "$PWD"
|
|
138
92
|
```
|
|
139
93
|
|
|
140
|
-
|
|
94
|
+
## First-time setup in Paperclip
|
|
95
|
+
|
|
96
|
+
1. Open the plugin settings for **GitHub Sync** from inside the Paperclip company you want to configure.
|
|
97
|
+
2. Paste a GitHub token, validate it, and save it.
|
|
98
|
+
3. If the deployment requires authenticated Paperclip board access, connect it from the same settings page and complete the approval flow.
|
|
99
|
+
4. Add one or more repository mappings for the current company.
|
|
100
|
+
5. For each mapping, either choose an existing GitHub-linked Paperclip project or enter the project name that should receive synced issues.
|
|
101
|
+
6. Optionally configure company-wide defaults for imported issues, including the default assignee, the default Paperclip status, and ignored GitHub usernames.
|
|
102
|
+
7. Choose the automatic sync interval in minutes.
|
|
103
|
+
8. Save the settings and run the first manual sync.
|
|
104
|
+
9. Repeat inside other companies if they need their own mappings, defaults, or board access.
|
|
105
|
+
|
|
106
|
+
Repository input accepts either `owner/repo` or `https://github.com/owner/repo`.
|
|
107
|
+
|
|
108
|
+
## Synchronization behavior
|
|
109
|
+
|
|
110
|
+
Imported issues keep the original GitHub title and use the normalized GitHub body as the Paperclip description. The worker also normalizes GitHub HTML that Paperclip descriptions do not render cleanly, including elements such as `<br>`, `<hr>`, `<details>`, `<summary>`, and inline images.
|
|
111
|
+
|
|
112
|
+
Repeated syncs keep existing imports current instead of creating duplicates again. If the plugin's import registry is stale, the worker can repair deduplication by reusing existing Paperclip issues when durable GitHub link metadata is already present.
|
|
113
|
+
|
|
114
|
+
When the local Paperclip API is available, the plugin also syncs labels by name, prefers exact color matches when multiple Paperclip labels share the same name, and creates missing Paperclip labels when needed.
|
|
115
|
+
|
|
116
|
+
### Status mapping
|
|
141
117
|
|
|
142
|
-
|
|
118
|
+
| GitHub condition | Paperclip status |
|
|
119
|
+
| --- | --- |
|
|
120
|
+
| Open issue with no linked pull request | Configured default status, which defaults to `backlog` |
|
|
121
|
+
| Open issue with a linked pull request and unfinished CI | `in_progress` |
|
|
122
|
+
| Open issue with failing CI or unresolved review threads | `todo` |
|
|
123
|
+
| Open issue with green CI and all review threads resolved | `in_review` |
|
|
124
|
+
| Closed issue completed as finished work | `done` |
|
|
125
|
+
| Closed issue closed as `not_planned` or `duplicate` | `cancelled` |
|
|
143
126
|
|
|
144
|
-
|
|
127
|
+
Additional behavior:
|
|
128
|
+
|
|
129
|
+
- Open imported issues that are already in `backlog` stay in `backlog` until someone changes them in Paperclip.
|
|
130
|
+
- Trusted new GitHub comments from the original issue author or a verified maintainer/admin can move an open imported issue back to `todo`.
|
|
131
|
+
- When the sync changes a Paperclip issue status, it adds a Paperclip comment explaining what changed and why.
|
|
132
|
+
|
|
133
|
+
## Security and authentication
|
|
134
|
+
|
|
135
|
+
The plugin is designed to avoid persisting raw credentials in plugin state.
|
|
136
|
+
|
|
137
|
+
- GitHub tokens saved through the UI are stored as Paperclip secret references.
|
|
138
|
+
- Paperclip board access tokens are also stored as per-company secret references.
|
|
139
|
+
- The worker resolves those secret references at runtime instead of storing raw tokens in plugin state.
|
|
140
|
+
- On authenticated Paperclip deployments, sync is blocked until the relevant company has connected Paperclip board access.
|
|
141
|
+
|
|
142
|
+
### Optional worker-local token file
|
|
143
|
+
|
|
144
|
+
If Paperclip-managed secrets are not available, the worker can read a local fallback file at `~/.paperclip/plugins/github-sync/config.json`:
|
|
145
145
|
|
|
146
146
|
```json
|
|
147
147
|
{
|
|
@@ -149,68 +149,64 @@ If the Paperclip host cannot provide the GitHub token through environment variab
|
|
|
149
149
|
}
|
|
150
150
|
```
|
|
151
151
|
|
|
152
|
-
Save it at `~/.paperclip/plugins/github-sync/config.json`.
|
|
153
|
-
|
|
154
152
|
Notes:
|
|
155
153
|
|
|
156
154
|
- This file is read by the worker only.
|
|
157
|
-
- The raw token is
|
|
158
|
-
- A GitHub token secret saved through the
|
|
155
|
+
- The raw token is never persisted back into plugin state or plugin config.
|
|
156
|
+
- A GitHub token secret saved through the settings UI takes precedence over the local file.
|
|
159
157
|
|
|
160
|
-
##
|
|
158
|
+
## GitHub agent tools
|
|
159
|
+
|
|
160
|
+
The plugin exposes GitHub workflow tools to Paperclip agents, including:
|
|
161
|
+
|
|
162
|
+
- repository-scoped search for issues and pull requests
|
|
163
|
+
- issue reads, comment reads, comment writes, and metadata updates
|
|
164
|
+
- pull request creation, reads, updates, changed-file inspection, and CI-check inspection
|
|
165
|
+
- review-thread reads, replies, resolve and unresolve actions, and reviewer requests
|
|
166
|
+
|
|
167
|
+
When an agent posts a GitHub comment or review-thread reply through the plugin, the message includes a footer disclosing that it was created by a Paperclip AI agent and which model was used.
|
|
168
|
+
|
|
169
|
+
## Troubleshooting
|
|
170
|
+
|
|
171
|
+
- If setup is reported as incomplete, confirm that a GitHub token has been saved or that `~/.paperclip/plugins/github-sync/config.json` contains `githubToken`, and make sure at least one mapping has a created Paperclip project.
|
|
172
|
+
- If Paperclip says board access is required, open plugin settings inside the affected company and complete the Paperclip board access flow before retrying sync.
|
|
173
|
+
- If the worker reaches an authenticated HTML page instead of the Paperclip API JSON responses it expects, connect Paperclip board access for that company or set `PAPERCLIP_API_URL` to a worker-accessible Paperclip API origin.
|
|
174
|
+
- If a sync run finishes with partial failures, open the saved troubleshooting panel in GitHub Sync to inspect the repository, issue number, raw error, and suggested fix for each recorded failure.
|
|
175
|
+
- If sync says the Paperclip API URL is not trusted, reopen the plugin from the current Paperclip host so the settings UI can refresh the saved origin, or set `PAPERCLIP_API_URL` for the worker.
|
|
176
|
+
- If GitHub rate limiting is hit, the plugin pauses sync until the reported reset time instead of retrying pointlessly.
|
|
177
|
+
- If a manual sync takes longer than the host action window, it continues in the background and updates the UI when it finishes or when a cancellation request stops it.
|
|
178
|
+
|
|
179
|
+
## Development
|
|
180
|
+
|
|
181
|
+
Run the smallest relevant checks from the repository root:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
pnpm typecheck
|
|
185
|
+
pnpm test
|
|
186
|
+
pnpm build
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Useful scripts:
|
|
190
|
+
|
|
191
|
+
- `pnpm dev` watches the manifest, worker, and UI bundles and rebuilds them into `dist/`
|
|
192
|
+
- `pnpm dev:ui` starts a local Paperclip plugin UI dev server from `dist/ui` on port `4177`
|
|
193
|
+
- `pnpm test:e2e` builds the plugin, boots an isolated Paperclip instance, installs the plugin, and verifies the hosted settings page renders
|
|
194
|
+
- `pnpm verify:manual` builds the plugin, boots a Paperclip instance for manual inspection, seeds a project already mapped to `https://github.com/alvarosanchez/paperclip-github-plugin`, seeds a `CEO` agent on the Codex local adapter with model `gpt-5.4`, and opens the plugin settings page
|
|
195
|
+
|
|
196
|
+
For fast hosted UI iteration, run `pnpm dev` in one terminal and `pnpm dev:ui` in another.
|
|
161
197
|
|
|
162
|
-
|
|
163
|
-
2. Paste a GitHub token and validate it.
|
|
164
|
-
3. Save the validated token so Paperclip can store it as a secret reference.
|
|
165
|
-
4. If the settings page reports that this Paperclip deployment requires board access, connect **Paperclip board access** from the same settings page and approve the new tab that opens.
|
|
166
|
-
5. Add one or more repository mappings for the current company.
|
|
167
|
-
6. For each mapping, either enable sync for an existing GitHub-linked Paperclip project or enter a GitHub repository and the Paperclip project name that should receive synced issues.
|
|
168
|
-
7. Optionally configure the company-wide advanced defaults for new imports: default assignee, default status, and ignored GitHub usernames.
|
|
169
|
-
8. Choose the automatic sync interval in minutes.
|
|
170
|
-
9. Save the settings.
|
|
171
|
-
10. Repeat inside any other Paperclip companies that should have their own mappings, defaults, or board access.
|
|
172
|
-
11. Run a manual sync to import the first batch of issues.
|
|
173
|
-
|
|
174
|
-
## Expected workflow
|
|
175
|
-
|
|
176
|
-
After setup, the dashboard widget shows whether the integration is ready, syncing, paused, or needs attention. When you open settings or the dashboard inside a company, the repository list and manual sync controls only affect that company. When you open a global instance view with no company context, the sync status and cadence reflect the shared plugin instance.
|
|
177
|
-
|
|
178
|
-
Imported issues stay linked to GitHub and continue to receive description, label, and status updates. GitHub-specific context stays out of the Paperclip issue description and instead appears in the dedicated GitHub detail tab and sync annotations.
|
|
179
|
-
|
|
180
|
-
## Troubleshooting notes
|
|
181
|
-
|
|
182
|
-
- If one company’s mappings disappear after saving another company’s setup, reopen plugin settings inside the affected company and confirm each company’s mappings separately; the settings page now keeps those mapping lists isolated per company.
|
|
183
|
-
- If sync says setup is incomplete, confirm that either a validated token secret has been saved or `~/.paperclip/plugins/github-sync/config.json` contains `githubToken`, at least one repository mapping has a created Paperclip project, and authenticated deployments have connected Paperclip board access for the current company.
|
|
184
|
-
- If token validation fails, confirm the token is still valid and can access the target repositories through the GitHub API.
|
|
185
|
-
- If the dashboard, toolbar, or settings page says board access is required, open plugin settings inside the target company and complete the Paperclip board access approval flow before retrying sync.
|
|
186
|
-
- If sync reports that the Paperclip API returned an authenticated HTML page instead of JSON, the worker is reaching a board URL that requires the browser login session. Connect Paperclip board access from plugin settings for that company, or set `PAPERCLIP_API_URL` for the Paperclip worker to a worker-accessible Paperclip API origin, then rerun sync.
|
|
187
|
-
- If sync says the Paperclip API URL is not trusted, reopen GitHub Sync from the current Paperclip host so the settings UI can refresh the trusted origin in plugin config, or set `PAPERCLIP_API_URL` for the worker.
|
|
188
|
-
- If GitHub rate limiting is hit, the plugin pauses sync until the reset time shown in Paperclip.
|
|
189
|
-
- If a sync takes longer than a quick action window, the plugin continues in the background and updates the UI when it finishes.
|
|
190
|
-
- If older imported issues are missing rich GitHub metadata, run sync once to refresh the link, labels, and pull request details.
|
|
191
|
-
|
|
192
|
-
## Developer scripts
|
|
193
|
-
|
|
194
|
-
- `pnpm typecheck` runs TypeScript without emitting files.
|
|
195
|
-
- `pnpm test` runs the package-level automated tests.
|
|
196
|
-
- `pnpm build` bundles the manifest and worker for Node execution and the hosted UI for browser execution into `dist/`.
|
|
197
|
-
- `pnpm dev` watches the manifest, worker, and UI bundles and rebuilds them into `dist/`.
|
|
198
|
-
- `pnpm dev:ui` starts a local Paperclip plugin UI dev server from `dist/ui` on port `4177`.
|
|
199
|
-
- `pnpm test:e2e` builds the plugin, boots an isolated Paperclip instance, installs the plugin, and verifies the hosted settings page renders.
|
|
200
|
-
- `pnpm verify:manual` builds the plugin, boots a Paperclip instance for manual inspection, seeds a project already mapped to `https://github.com/alvarosanchez/paperclip-github-plugin`, seeds a `CEO` agent on the Codex local adapter with model `gpt-5.4`, and opens the plugin settings page.
|
|
201
|
-
- Set `PAPERCLIP_E2E_CEO_BYPASS_APPROVALS_AND_SANDBOX=true` if you want that seeded `CEO` agent to opt into Codex's bypass flag during manual verification.
|
|
202
|
-
|
|
203
|
-
For fast hosted-UI iteration, run `pnpm dev` in one terminal and `pnpm dev:ui` in another.
|
|
198
|
+
If you want the seeded `CEO` agent used in manual verification to opt into Codex's bypass flag, set `PAPERCLIP_E2E_CEO_BYPASS_APPROVALS_AND_SANDBOX=true`.
|
|
204
199
|
|
|
205
200
|
## Release process
|
|
206
201
|
|
|
207
202
|
- Publishing is driven by `.github/workflows/release.yml`.
|
|
208
|
-
- The npm publish job
|
|
209
|
-
- The
|
|
203
|
+
- The npm publish job runs from a published GitHub Release.
|
|
204
|
+
- The release job uses `actions/setup-node@v6` with Node `24`, which already satisfies npm trusted publishing requirements without an extra in-job npm self-upgrade step.
|
|
205
|
+
- The published version is derived from the GitHub release tag rather than the committed `package.json` version.
|
|
210
206
|
- Tags may be either `1.2.3` or `v1.2.3`; the workflow normalizes both to `1.2.3`.
|
|
211
|
-
- During
|
|
212
|
-
- The
|
|
207
|
+
- During release, the package version is stamped from the tag before build and publish, and the built plugin manifest uses that same resolved version.
|
|
208
|
+
- The workflow is intended for npm trusted publishing through GitHub Actions OIDC, so no long-lived `NPM_TOKEN` secret is required when trusted publishing is configured correctly.
|
|
213
209
|
|
|
214
210
|
## License
|
|
215
211
|
|
|
216
|
-
|
|
212
|
+
Apache License 2.0. See [LICENSE](LICENSE).
|
package/dist/manifest.js
CHANGED
|
@@ -435,7 +435,7 @@ var require2 = createRequire(import.meta.url);
|
|
|
435
435
|
var packageJson = require2("../package.json");
|
|
436
436
|
var DASHBOARD_WIDGET_CAPABILITY = "ui.dashboardWidget.register";
|
|
437
437
|
var SCHEDULE_TICK_CRON = "* * * * *";
|
|
438
|
-
var MANIFEST_VERSION =
|
|
438
|
+
var MANIFEST_VERSION = "0.2.3"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
|
|
439
439
|
var manifest = {
|
|
440
440
|
id: "paperclip-github-plugin",
|
|
441
441
|
apiVersion: 1,
|