paperclip-github-plugin 0.2.1

package/LICENSE

@@ -0,0 +1,184 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the purposes
+of this definition, "submitted" means any form of electronic, verbal, or
+written communication sent to the Licensor or its representatives, including
+but not limited to communication on electronic mailing lists, source code
+control systems, and issue tracking systems that are managed by, or on behalf
+of, the Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise designated in
+writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with the
+Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!)  The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,216 @@
+# paperclip-github-plugin
+
+GitHub Sync is a Paperclip plugin that connects GitHub repositories to Paperclip projects and keeps GitHub issues synchronized into your Paperclip workspace.
+
+It is designed for teams that plan in Paperclip but still receive work through GitHub issues. The plugin gives you a Paperclip-native setup flow, secure GitHub token handling through Paperclip secrets or an optional local worker config file, authenticated-deployment detection with required board-access connection when needed, manual sync controls, automatic background sync, and GitHub context directly on synced Paperclip issues.
+
+## What the plugin does
+
+- Connects one or more GitHub repositories to Paperclip projects.
+- Imports GitHub issues as top-level Paperclip issues.
+- Keeps already imported issues updated instead of recreating them.
+- Stores the GitHub token as a Paperclip secret reference instead of persisting the raw token in plugin state.
+- Supports an optional worker-local config file at `~/.paperclip/plugins/github-sync/config.json` for a raw `githubToken` fallback when Paperclip-managed secrets are not available.
+- Can store a per-company Paperclip board API token for worker-side REST calls when Paperclip board access requires sign-in.
+- Adds Paperclip UI surfaces for setup, sync status, manual sync actions, issue details, and GitHub link annotations.
+- Exposes agent tools so Paperclip agents can search GitHub for duplicates, read and update issues, open pull requests, inspect CI, work through review threads, and request reviewers without leaving the plugin surface.
+
+## User-facing features
+
+### Setup and configuration
+
+- Hosted settings page inside Paperclip.
+- GitHub token validation before saving.
+- GitHub token saved through Paperclip company secrets; the plugin stores only the secret reference.
+- Optional worker-local config file support at `~/.paperclip/plugins/github-sync/config.json` with a `githubToken` field for global runtime fallback.
+- GitHub token and automatic sync cadence stay shared across the plugin instance, while repository mappings, advanced import defaults, and Paperclip board access are managed per company from the same hosted settings flow.
+- The hosted settings page calls out the current company by name and separates company-scoped setup from shared plugin-wide settings.
+- Automatic detection of authenticated Paperclip deployments through `/api/health`.
+- Paperclip board access connection flow from settings, enforced when the deployment requires authenticated board access for worker-side REST calls.
+- Paperclip board tokens saved through Paperclip company secrets per company; the plugin stores only the secret reference and mirrors that ref into plugin config so workers can resolve it during sync.
+- Support for multiple repository-to-project mappings.
+- When settings are opened inside a company, the repository list only shows that company’s mappings and saving it preserves mappings that belong to other companies.
+- Company-wide advanced settings for imported issues, including a default assignee, a default Paperclip status, and ignored GitHub issue authors.
+- Repository input accepts either `owner/repo` or `https://github.com/owner/repo`.
+- When a company already has Paperclip projects bound to GitHub repository workspaces, the settings page surfaces those existing projects so sync can be enabled without recreating the project.
+- Automatic creation or reuse of the target Paperclip project when a mapping is saved.
+- Automatic binding of the GitHub repository URL to the target Paperclip project workspace.
+- Configurable automatic sync cadence in whole minutes.
+- Project name becomes read-only in the settings UI after the project has been created and linked.
+
+### Sync behavior
+
+- Manual sync from the settings page, scoped to the current company when settings are opened inside a company.
+- Global toolbar button for syncing from anywhere in Paperclip.
+- Global toolbar and dashboard sync actions target the current company when they are rendered inside one, and fall back to all saved mappings only when no company context is active.
+- Project toolbar button for syncing the repository mapped to a specific Paperclip project.
+- Issue toolbar button for syncing the GitHub issue linked to a specific Paperclip issue.
+- Automatic scheduled sync driven by a job that checks every minute and runs when the saved cadence is due.
+- Background completion for long-running manual or scheduled syncs so the host request can return promptly.
+- Live sync progress and troubleshooting details in the Paperclip UI.
+- Cumulative sync counts and last-run status in plugin state.
+
+### Agent tools
+
+- Repository-scoped search for issues and pull requests to support deduplication during triage.
+- GitHub issue read, comment-read, comment-write, and metadata update tools for agent implementation work.
+- Pull request creation, read, update, changed-file, CI-check, review-thread, and reviewer-request tools for agent delivery work.
+- Review-thread reply plus resolve and unresolve tools so agents can respond to automated review feedback directly from Paperclip.
+- Comment-posting tools automatically append a footer disclosing that a Paperclip AI agent authored the message and which LLM was used; callers must provide the LLM name when posting those messages.
+
+### Issue import and update behavior
+
+- Imports one top-level Paperclip issue per GitHub issue.
+- Can ignore GitHub issues from configured usernames such as `renovate`.
+- Preserves the original GitHub issue title without adding a prefix.
+- Uses the normalized GitHub issue body as the Paperclip issue description.
+- Normalizes GitHub HTML that Paperclip descriptions cannot render cleanly, including constructs such as `<br>`, `<hr>`, `<details>`, `<summary>`, and inline images.
+- Re-syncs descriptions so imported Paperclip issues stay aligned with the latest GitHub issue body.
+- Repairs missing or stale descriptions when Paperclip create/update flows return incomplete issue content.
+- Deduplicates repeated sync runs so previously imported GitHub issues are not recreated.
+- Repairs stale or missing import-registry entries by reusing existing imported Paperclip issues when durable GitHub metadata or older source-link metadata is present.
+- Continues tracking previously imported issues, including closed issues, so status and metadata can still be reconciled after the initial import.
+
+### Labels and metadata
+
+- Maps GitHub labels onto Paperclip issue labels.
+- Prefers exact color matches when multiple Paperclip labels share the same name.
+- Creates missing Paperclip labels through the local Paperclip API when the host URL is known.
+- Re-syncs label changes, including removing labels that were removed on GitHub.
+- Adds a GitHub detail tab on synced Paperclip issues showing:
+  - GitHub repository
+  - GitHub issue number and link
+  - GitHub state and close reason
+  - comment count
+  - linked pull requests
+  - synced labels
+  - last synced time
+- Recovers older linked issues into the detail tab when legacy sync metadata exists, and refreshes that metadata on the next sync.
+
+### Status synchronization
+
+- Open GitHub issue with no linked pull request imports into the configured default Paperclip status, which defaults to `backlog`.
+- Open GitHub issue with unfinished CI on a linked pull request maps to `in_progress`.
+- Open GitHub issue with failing CI or unresolved review threads on a linked pull request maps to `todo`.
+- Open GitHub issue with green CI and all review threads resolved maps to `in_review`.
+- Closed GitHub issue completed as finished work maps to `done`.
+- Closed GitHub issue closed as `not_planned` or `duplicate` maps to `cancelled`.
+- 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.
+- Existing open issues that are already `backlog` stay in `backlog` until a human changes them in Paperclip.
+- When the plugin changes a Paperclip issue status, it adds a Paperclip comment explaining the transition.
+- When comment annotations are supported by the host, those transition comments also surface GitHub issue and pull request links directly under the comment.
+
+### Resilience and safety
+
+- Raw GitHub tokens are never persisted in plugin state.
+- Raw GitHub tokens loaded from `~/.paperclip/plugins/github-sync/config.json` stay worker-local and are never returned by public data endpoints.
+- Raw Paperclip board tokens are never persisted in plugin state or plugin config.
+- Scheduled sync skips runs that are not due yet.
+- Incomplete setup is surfaced as configuration guidance instead of silently failing.
+- Authenticated deployments are detected before sync starts, and the plugin blocks sync until the required company board access has been connected.
+- GitHub rate limiting pauses sync until the reported reset time and prevents pointless retries while the pause is active.
+- Direct Paperclip REST label and issue calls attach the saved board token automatically when one has been connected for the mapping company.
+- Sync failures retain repository and issue diagnostics to make troubleshooting easier.
+
+## Paperclip surfaces added by this plugin
+
+- Dashboard widget with setup/readiness messaging, last sync status, and a link to settings.
+- Settings page for token validation, repository mappings, company-wide advanced defaults, save, and manual sync.
+- Global toolbar action for a full sync.
+- Project toolbar action for targeted project sync.
+- Issue toolbar action for targeted issue sync.
+- Issue detail tab for GitHub metadata.
+- Comment annotation surface for GitHub references attached to sync-generated status transition comments.
+
+## Requirements
+
+- Node.js 20+
+- `pnpm`
+- A Paperclip host that supports plugin installation
+- A GitHub token with API access to the repositories you want to sync
+
+## Install from this repository
+
+```bash
+pnpm install
+pnpm build
+npx paperclip plugin install --local "$PWD"
+```
+
+If you are installing into an isolated local Paperclip instance for testing, include the Paperclip CLI flags you normally use for `--data-dir` and `--config`.
+
+## Optional external worker config
+
+If the Paperclip host cannot provide the GitHub token through environment variables or plugin config, the worker can also read an optional local file:
+
+```json
+{
+  "githubToken": "ghp_your_token_here"
+}
+```
+
+Save it at `~/.paperclip/plugins/github-sync/config.json`.
+
+Notes:
+
+- This file is read by the worker only.
+- The raw token is not persisted into plugin state or plugin config.
+- A GitHub token secret saved through the Paperclip settings UI still takes precedence over the external file.
+
+## First-time setup in Paperclip
+
+1. Open Paperclip instance settings and go to the plugin settings for **GitHub Sync** from inside the company you want to configure.
+2. Paste a GitHub token and validate it.
+3. Save the validated token so Paperclip can store it as a secret reference.
+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.
+5. Add one or more repository mappings for the current company.
+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.
+7. Optionally configure the company-wide advanced defaults for new imports: default assignee, default status, and ignored GitHub usernames.
+8. Choose the automatic sync interval in minutes.
+9. Save the settings.
+10. Repeat inside any other Paperclip companies that should have their own mappings, defaults, or board access.
+11. Run a manual sync to import the first batch of issues.
+
+## Expected workflow
+
+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.
+
+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.
+
+## Troubleshooting notes
+
+- 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.
+- 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.
+- If token validation fails, confirm the token is still valid and can access the target repositories through the GitHub API.
+- 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.
+- 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.
+- 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.
+- If GitHub rate limiting is hit, the plugin pauses sync until the reset time shown in Paperclip.
+- If a sync takes longer than a quick action window, the plugin continues in the background and updates the UI when it finishes.
+- If older imported issues are missing rich GitHub metadata, run sync once to refresh the link, labels, and pull request details.
+
+## Developer scripts
+
+- `pnpm typecheck` runs TypeScript without emitting files.
+- `pnpm test` runs the package-level automated tests.
+- `pnpm build` bundles the manifest and worker for Node execution and the hosted UI for browser execution into `dist/`.
+- `pnpm dev` watches the manifest, worker, and UI bundles and rebuilds them into `dist/`.
+- `pnpm dev:ui` starts a local Paperclip plugin UI dev server from `dist/ui` on port `4177`.
+- `pnpm test:e2e` builds the plugin, boots an isolated Paperclip instance, installs the plugin, and verifies the hosted settings page renders.
+- `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.
+- 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.
+
+For fast hosted-UI iteration, run `pnpm dev` in one terminal and `pnpm dev:ui` in another.
+
+## Release process
+
+- Publishing is driven by `.github/workflows/release.yml`.
+- The npm publish job is triggered by a published GitHub Release.
+- The published version is derived from the GitHub release tag, not from the committed `package.json` version.
+- Tags may be either `1.2.3` or `v1.2.3`; the workflow normalizes both to `1.2.3`.
+- During the release workflow, the package version is stamped from the tag before build and publish, and the built plugin manifest uses that same resolved version.
+- The release 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.
+
+## License
+
+This repository is licensed under Apache License 2.0. See [LICENSE](LICENSE).