paperclip-github-plugin 0.5.3 → 0.6.1

package/README.md

@@ -30,7 +30,8 @@ The plugin adds a full in-host workflow instead of a one-off import script:
 
 - a hosted settings page for GitHub auth, repository mappings, company defaults, execution-policy handoff fallbacks, and sync controls
 - authenticated-only setup controls for Paperclip board access and company-scoped agent token propagation
-- a dashboard widget that shows readiness, sync status, and last-run results
+- a dashboard widget that shows sync readiness, current sync status, and run/cancel controls
+- a separate KPI dashboard widget that tracks GitHub backlog size, GitHub issues closed, and Paperclip pull requests created with recent history and historical comparisons
 - saved sync diagnostics that let operators inspect the latest per-issue failures, raw errors, and suggested next steps
 - a project sidebar item that opens a live project-scoped Pull Requests page for the mapped repository and can show the open PR count through a lightweight badge read
 - manual sync actions from global, project, and issue surfaces
@@ -63,12 +64,22 @@ If a company already has a Paperclip project bound to a GitHub repository worksp
 
 The plugin does more than mirror issue text. It looks at linked pull requests, mergeability, CI, review threads, and trusted new GitHub comments so imported Paperclip issues can reflect where the work actually is. When GitHub links an issue to a pull request in another repository, GitHub Sync now follows that pull request's actual repository for status checks, review-thread state, and deep links instead of assuming the issue repository. When sync closes an imported issue as `done` or `cancelled`, it also clears any pending Paperclip review or approval execution state so the host accepts the terminal transition cleanly.
 
+### Company KPI dashboard
+
+GitHub Sync exposes a dedicated KPI dashboard widget alongside the operational sync widget. During full company syncs, the worker snapshots the current open GitHub backlog and records when already-imported GitHub issues move from open to closed. The KPI widget turns that worker-owned state into backlog, issue-closure, and Paperclip PR-creation cards with recent history and comparisons against older periods.
+
+Because GitHub alone cannot tell which pull requests came from a Paperclip company, the plugin uses explicit Paperclip attribution for delivery activity. `create_pull_request` automatically records a Paperclip-created PR event, and agents that use `gh` or another non-plugin GitHub client can post pull-request-created events to the plugin webhook so the KPI history stays specific to Paperclip work.
+
+That webhook path matters on authenticated Paperclip deployments today because a current host bug blocks agents from calling plugin tools unless the instance runs in `local_trusted` mode. Those agents can still use `gh` with the propagated `GITHUB_TOKEN`, then call the plugin-owned webhook from the shell after they create a PR. KPI webhook requests instead authenticate with `Authorization: Bearer <PAPERCLIP_API_KEY>`, which the deployment validates through `GET /api/agents/me`, so anonymous POSTs are rejected.
+
 ### Project pull request command center
 
 Each mapped project can expose a **Pull Requests** entry in the sidebar that opens a live GitHub queue page for that repository. The sidebar badge uses a lightweight total-count read, while the queue keeps the default view fast by loading only the current 10-row page, uses a repo-wide metrics read for the summary cards, reuses that cached metrics scan to keep filtered views fast by fetching only the visible filtered rows, keeps repo-scoped count, metrics, and per-PR review/check insight caches warm for repeat visits, lets operators explicitly bust those caches with Refresh when they want a live reread, shows total, mergeable, reviewable, and failing cards that filter the table, only treats a pull request as mergeable when it targets the current default branch with green checks, at least one approval, no outstanding change requests, and no unresolved review threads, includes an **Up to date** column that distinguishes current branches, clean update candidates, conflict cases, and unknown freshness when GitHub cannot confirm the comparison, shows the PR target branch with a highlighted default-branch badge, keeps the list sorted by most recently updated first, paginates larger repositories, keeps a compact bottom detail pane with markdown-and-HTML-rendered conversation plus an inline comment composer, supports deterministic **Update branch** actions for clean behind-base pull requests, adds Copilot quick actions that post `@copilot` requests for **Fix CI**, **Rebase**, and **Address review feedback**, requests Copilot through GitHub’s native reviewer flow for **Review**, keeps comment, review, quick approve/request-changes, re-run CI, merge, and close actions available, lets the review modal submit comment-only, approve, or request-changes reviews, hides any pull request action whose required GitHub permission is not verified for the saved token, and opens linked Paperclip issues in a plugin-provided right drawer so operators can stay on the queue page.
 
 Paperclip issue linkage on the queue prefers the GitHub issue that the pull request closes, so imported GitHub issues and delivery work stay connected in the same project view. If a pull request has no closing-issue-backed link yet, the queue falls back to the Paperclip issue created directly from that pull request and updates the table immediately when that create action returns.
 
+Those pull-request-created Paperclip issues also stay in the scheduled/manual sync loop even when the pull request does not close a GitHub issue. GitHub Sync checks their CI, merge state, and review threads so new failures or unresolved feedback move the Paperclip issue back into active work.
+
 The issue detail panel and sync-created comment annotations also preserve cross-repository linked pull requests, showing those PRs with their real repository path so operators land in the right place on GitHub.
 
 ### Agent workflows built in
@@ -167,6 +178,7 @@ The plugin is designed to avoid persisting raw credentials in plugin state.
 - On authenticated deployments, any selected propagation agents receive `GITHUB_TOKEN` as an agent env secret-ref binding that points at the same saved GitHub token secret instead of a copied raw token.
 - The worker resolves those secret references at runtime instead of storing raw tokens in plugin state.
 - On authenticated Paperclip deployments, sync is blocked until the relevant company has connected Paperclip board access.
+- KPI webhook requests must include `Authorization: Bearer <PAPERCLIP_API_KEY>`, and the worker validates that agent-scoped Paperclip token against `GET /api/agents/me` before it records any metric event.
 
 ### Optional worker-local token file
 
@@ -196,13 +208,50 @@ The plugin exposes GitHub workflow tools to Paperclip agents, including:
 
 When an agent sends GitHub body content through the plugin, including issue bodies, pull request descriptions, comments, and review-thread replies, the plugin adds a GitHub-flavored Markdown footer with a horizontal rule and compact heading that discloses AI authorship. If the tool caller supplies `llmModel`, the footer also includes the model name, for example `###### ✨ This comment was AI-generated using gpt-5.4`.
 
+### KPI attribution webhook
+
+The `create_pull_request` tool automatically records a company-level Paperclip PR creation metric. For delivery flows that use `gh` or another non-plugin GitHub client, post a JSON payload to `/api/plugins/paperclip-github-plugin/webhooks/record-company-metric-event` after the PR is created.
+
+Supported payload fields:
+
+- `metric` required: `pull_request_created`
+- `companyId` optional when `repository` maps to exactly one company
+- `repository` optional: `owner/repo` or `https://github.com/owner/repo`
+- `pullRequestNumber` optional
+- `pullRequestUrl` optional
+- `occurredAt` optional ISO timestamp
+- `eventKey` optional custom dedupe key
+- `count` optional positive integer
+
+Each request must include:
+
+- `Authorization: Bearer <PAPERCLIP_API_KEY>`
+
+The worker validates that bearer token against Paperclip's built-in `GET /api/agents/me` endpoint on the trusted Paperclip API origin (`PAPERCLIP_API_URL` when available, otherwise the saved plugin origin). Requests are rejected when the token is missing, invalid, expired, or belongs to a different company than the metric target.
+
+Example:
+
+```bash
+payload='{"metric":"pull_request_created","repository":"paperclipai/example-repo","pullRequestNumber":21}'
+
+curl -X POST "${PAPERCLIP_API_URL%/}/api/plugins/paperclip-github-plugin/webhooks/record-company-metric-event" \
+  -H "content-type: application/json" \
+  -H "authorization: Bearer ${PAPERCLIP_API_KEY}" \
+  -d "${payload}"
+```
+
+The worker deduplicates repeated PR events by preferring the pull request URL, then `repository + pullRequestNumber`, before falling back to the explicit `eventKey`.
+
 Current host caveat: on authenticated Paperclip deployments, the Paperclip host currently guards `GET /api/plugins/tools` and `POST /api/plugins/tools/execute` with board authentication before dispatching to any plugin worker. If an agent run does not have board access for the target company, GitHub Sync tool discovery and execution fail with `403 {"error":"Board access required"}` before this plugin's worker code runs.
 
+Because the KPI attribution endpoint is a normal plugin webhook rather than a plugin tool, authenticated agent runs can still call it directly with `PAPERCLIP_API_KEY` even while that host bug blocks the GitHub Sync tool surface.
+
 ## Troubleshooting
 
 - If setup is reported as incomplete, confirm that a GitHub token has been saved or that `${PAPERCLIP_HOME:-~/.paperclip}/plugins/github-sync/config.json` contains `githubToken`, and make sure at least one mapping has a created Paperclip project.
 - If Paperclip says board access is required, open plugin settings inside the affected company and complete the Paperclip board access flow before retrying sync.
 - If GitHub Sync agent tools fail with `403 {"error":"Board access required"}` on `/api/plugins/tools` or `/api/plugins/tools/execute`, the current Paperclip host rejected the request before the plugin worker ran. Re-run from a board-authenticated session or agent run that has board access to the target company.
+- If a KPI webhook call is rejected, make sure the request includes `Authorization: Bearer ${PAPERCLIP_API_KEY}`, that the token is still valid for the current run, and that it belongs to the same company the metric event targets.
 - 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.
 - 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.
 - 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.
@@ -227,7 +276,7 @@ Useful scripts:
 - `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
+- `pnpm verify:manual` builds the plugin, boots a local-trusted Paperclip instance for manual inspection, seeds a `Dummy Company` with a mapped review project and a `CEO` agent on the Codex local adapter using model `gpt-5.4`, installs the plugin, and opens the company dashboard without seeding KPI history.
 
 For fast hosted UI iteration, run `pnpm dev` in one terminal and `pnpm dev:ui` in another.
 

package/dist/manifest.js

@@ -506,14 +506,19 @@ var GITHUB_AGENT_TOOLS = [
   }
 ];
 
+// src/kpi-contract.ts
+var GITHUB_SYNC_PLUGIN_ID = "paperclip-github-plugin";
+var COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY = "record-company-metric-event";
+var COMPANY_METRIC_WEBHOOK_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/webhooks/${COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY}`;
+
 // src/manifest.ts
 var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
 var DASHBOARD_WIDGET_CAPABILITY = "ui.dashboardWidget.register";
 var SCHEDULE_TICK_CRON = "* * * * *";
-var MANIFEST_VERSION = "0.5.3"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
+var MANIFEST_VERSION = "0.6.1"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
 var manifest = {
-  id: "paperclip-github-plugin",
+  id: GITHUB_SYNC_PLUGIN_ID,
   apiVersion: 1,
   version: MANIFEST_VERSION,
   displayName: "GitHub Sync",
@@ -538,6 +543,7 @@ var manifest = {
     "issue.comments.create",
     "agents.read",
     "jobs.schedule",
+    "webhooks.receive",
     "http.outbound",
     "secrets.read-ref",
     "agent.tools.register"
@@ -573,6 +579,13 @@ var manifest = {
       schedule: SCHEDULE_TICK_CRON
     }
   ],
+  webhooks: [
+    {
+      endpointKey: COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY,
+      displayName: "Record Company KPI Event",
+      description: "Record Paperclip-attributed pull request activity from agent flows that use gh or other non-plugin GitHub clients."
+    }
+  ],
   tools: GITHUB_AGENT_TOOLS,
   entrypoints: {
     worker: "./dist/worker.js",
@@ -601,6 +614,12 @@ var manifest = {
         displayName: "GitHub Sync",
         exportName: "GitHubSyncDashboardWidget"
       },
+      {
+        type: "dashboardWidget",
+        id: "paperclip-github-plugin-kpi-dashboard-widget",
+        displayName: "GitHub KPIs",
+        exportName: "GitHubSyncKpiDashboardWidget"
+      },
       {
         type: "taskDetailView",
         id: "paperclip-github-plugin-issue-detail-tab",