paperclip-github-plugin 0.9.8 → 0.9.10

package/README.md

@@ -19,7 +19,7 @@ With this plugin, you can:
 - import open GitHub issues into Paperclip without adding title prefixes or duplicate issues
 - keep descriptions, labels, and status aligned with GitHub over time
 - configure mappings and import defaults per Paperclip company
-- on authenticated Paperclip deployments, choose exactly which company agents should receive the saved GitHub token as `GITHUB_TOKEN`
+- choose exactly which company agents should receive the saved GitHub token as `GITHUB_TOKEN`
 - run sync manually or on a schedule
 - triage open pull requests from mapped Paperclip projects in a hosted queue
 - give Paperclip agents native GitHub tools for issues, pull requests, CI, review threads, and org-level projects
@@ -29,7 +29,7 @@ With this plugin, you can:
 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
+- setup controls for Paperclip board access and company-scoped agent token propagation
 - 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
@@ -44,7 +44,7 @@ The plugin adds a full in-host workflow instead of a one-off import script:
 2. Connect one or more GitHub repositories to Paperclip projects.
 3. Run a sync manually or let the scheduled job keep things up to date.
 
-During sync, the plugin imports one top-level Paperclip issue per GitHub issue, stamps it with a namespaced GitHub Sync plugin origin, 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. On Paperclip `2026.512.0` and newer, the plugin passes the intended initial import status explicitly so Paperclip's assigned-issue creation defaults cannot override GitHub Sync's routing, and the detail surfaces can recover GitHub issue and pull request links from Paperclip's own `originKind` / `originId` fields when the plugin registry or legacy hidden marker is missing.
+During sync, the plugin imports one top-level Paperclip issue per GitHub issue, stamps it with a namespaced GitHub Sync plugin origin, 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. On Paperclip `2026.517.0` and newer, the plugin passes the intended initial import status explicitly so Paperclip's assigned-issue creation defaults cannot override GitHub Sync's routing, and the detail surfaces can recover GitHub issue and pull request links from Paperclip's own `originKind` / `originId` fields when the plugin registry or legacy hidden marker is missing.
 
 When the host exposes plugin issue creation, imported GitHub issues are created through the Paperclip plugin SDK path so they are not attributed to the connected board user. The worker still uses direct local Paperclip REST calls for label sync and for description, assignee, or status repair paths when those routes are available.
 
@@ -106,7 +106,7 @@ They can also link a Paperclip issue to a GitHub issue or pull request in any ac
 ## Requirements
 
 - Node.js 20+
-- a Paperclip host with plugin installation enabled. GitHub Sync is built and tested against Paperclip `2026.512.0`; the manifest relies on explicit capabilities instead of a strict host-version gate because current latest/development hosts can report `0.0.0` during plugin upgrade.
+- a Paperclip host with plugin installation enabled. GitHub Sync is built and tested against Paperclip `2026.517.0`; the manifest relies on explicit capabilities instead of a strict host-version gate because current latest/development hosts can report `0.0.0` during plugin upgrade.
 - a GitHub token with API access to the repositories you want to sync
 
 ## Install from npm
@@ -137,8 +137,8 @@ npx paperclipai plugin install --local "$PWD"
 
 1. Open the plugin settings for **GitHub Sync** from inside the Paperclip company you want to configure.
 2. Paste a GitHub token, validate it, and save it.
-3. If the deployment is authenticated, connect Paperclip board access from the same settings page and complete the approval flow.
-4. If the deployment is authenticated, choose which agents in the current company should receive the saved GitHub token as `GITHUB_TOKEN`.
+3. If the deployment is authenticated or local trusted, connect Paperclip board access from the same settings page and complete the approval flow when host API calls need board credentials.
+4. Choose which agents in the current company should receive the saved GitHub token as `GITHUB_TOKEN`.
 5. Add one or more repository mappings for the current company.
 6. For each mapping, either choose an existing GitHub-linked Paperclip project or enter the project name that should receive synced issues.
 7. Optionally configure company-wide defaults for imported issues, including the default assignee, the default Paperclip status, executor/reviewer/approver handoff assignees for sync-driven transitions, and ignored GitHub usernames. When Paperclip board access is connected, each assignee dropdown also offers `Me` for the connected board user. `Automatic routing` means GitHub Sync follows the issue's Paperclip execution policy first and only uses the saved fallback when Paperclip does not expose the next reviewer, approver, or return assignee yet. Bot aliases such as `renovate[bot]` are matched when you save `renovate`.
@@ -197,10 +197,10 @@ The plugin is designed to avoid persisting raw credentials in plugin state.
 - GitHub tokens saved through the UI are stored as per-company Paperclip secret references.
 - Paperclip board access tokens are also stored as per-company secret references.
 - The settings UI also keeps lightweight non-secret identity labels for those saved connections, so later visits can still show who each company GitHub token and board access are connected as.
-- 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.
+- 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.
 - When the current Paperclip host rejects plugin secret refs, GitHub Sync keeps company-scoped worker-local compatibility copies for GitHub tokens and Paperclip board-access tokens in `${PAPERCLIP_HOME:-~/.paperclip}/plugins/github-sync/config.json`. Reconnect board access once after upgrading if sync still cannot authenticate Paperclip label or issue REST calls.
-- On authenticated Paperclip deployments, sync is blocked until the relevant company has connected Paperclip board access.
+- On authenticated Paperclip deployments, sync is blocked until the relevant company has connected Paperclip board access. On local trusted deployments, board access setup remains visible so operators can configure it for host API paths that still require board credentials, but missing board access does not by itself block sync preflight.
 - KPI API route requests must include `Authorization: Bearer <PAPERCLIP_API_KEY>` from an agent run; the Paperclip host authenticates the token and supplies the agent company before the worker records any metric event.
 
 ### Optional worker-local token file
@@ -225,7 +225,7 @@ Notes:
 - The raw token is never persisted back into plugin state or plugin config.
 - A GitHub token secret saved through the settings UI is the primary source. If the current Paperclip host rejects plugin secret-ref resolution while company-scoped plugin config is unavailable, GitHub Sync stores the validated token in `githubTokensByCompanyId` as a worker-local compatibility fallback.
 - A Paperclip board access secret saved through the settings UI is also the primary source. If the host cannot resolve it for plugin workers, reconnecting board access stores the approved board token in `paperclipBoardApiTokensByCompanyId` as a worker-local compatibility fallback for direct Paperclip REST calls.
-- On authenticated deployments, selected agents receive `GITHUB_TOKEN` as a latest-version secret-ref env binding, and the settings UI patches agent adapter config with `replaceAdapterConfig: true` so newer Paperclip hosts persist the merged env map.
+- Selected agents receive `GITHUB_TOKEN` as a latest-version secret-ref env binding, and the settings UI patches agent adapter config with `replaceAdapterConfig: true` so newer Paperclip hosts persist the merged env map.
 
 ### Worker-facing Paperclip API URL
 
@@ -366,8 +366,8 @@ 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 `2026.512.0` instance, installs the plugin, and verifies the hosted settings page renders
-- `pnpm verify:manual` builds the plugin, boots a local-trusted Paperclip `2026.512.0` 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.
+- `pnpm test:e2e` builds the plugin, boots an isolated Paperclip `2026.517.0` instance, installs the plugin, and verifies the hosted settings page renders
+- `pnpm verify:manual` builds the plugin, boots a local-trusted Paperclip `2026.517.0` 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

@@ -642,7 +642,7 @@ var PULL_REQUEST_ASSET_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_I
 var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
 var SCHEDULE_TICK_CRON = "* * * * *";
-var MANIFEST_VERSION = "0.9.8"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
+var MANIFEST_VERSION = "0.9.10"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
 var manifest = {
   id: GITHUB_SYNC_PLUGIN_ID,
   apiVersion: 1,

package/dist/ui/index.js

@@ -22408,10 +22408,21 @@ function normalizePaperclipHealthResponse(value) {
     ...authReady !== void 0 ? { authReady } : {}
   };
 }
-function requiresPaperclipBoardAccess(value) {
-  const health = normalizePaperclipHealthResponse(value);
+function requiresPaperclipBoardAccessForHealth(health) {
   return health?.deploymentMode?.toLowerCase() === "authenticated";
 }
+function shouldShowPaperclipBoardAccessSettingsForHealth(health) {
+  const deploymentMode = health?.deploymentMode?.toLowerCase();
+  return deploymentMode === "authenticated" || deploymentMode === "local_trusted";
+}
+function resolvePaperclipAuthControlsPolicy(value) {
+  const health = normalizePaperclipHealthResponse(value);
+  return {
+    boardAccessRequired: requiresPaperclipBoardAccessForHealth(health),
+    boardAccessSettingsVisible: shouldShowPaperclipBoardAccessSettingsForHealth(health),
+    githubTokenPropagationSettingsVisible: true
+  };
+}
 
 // src/ui/assignees.ts
 function normalizeCompanyAssigneeOptionsResponse(response) {
@@ -23098,7 +23109,12 @@ function getSyncSetupMessage(issue, hasCompanyContext) {
   }
 }
 function usePaperclipBoardAccessRequirement() {
-  const [status, setStatus] = useState2("loading");
+  const [state, setState] = useState2({
+    status: "loading",
+    required: false,
+    settingsVisible: false,
+    githubTokenPropagationSettingsVisible: true
+  });
   useEffect2(() => {
     let cancelled = false;
     void (async () => {
@@ -23107,19 +23123,28 @@ function usePaperclipBoardAccessRequirement() {
         return;
       }
       if (!health) {
-        setStatus("unknown");
+        const policy2 = resolvePaperclipAuthControlsPolicy(null);
+        setState({
+          status: "unknown",
+          required: policy2.boardAccessRequired,
+          settingsVisible: policy2.boardAccessSettingsVisible,
+          githubTokenPropagationSettingsVisible: policy2.githubTokenPropagationSettingsVisible
+        });
         return;
       }
-      setStatus(requiresPaperclipBoardAccess(health) ? "required" : "not_required");
+      const policy = resolvePaperclipAuthControlsPolicy(health);
+      setState({
+        status: policy.boardAccessRequired ? "required" : "not_required",
+        required: policy.boardAccessRequired,
+        settingsVisible: policy.boardAccessSettingsVisible,
+        githubTokenPropagationSettingsVisible: policy.githubTokenPropagationSettingsVisible
+      });
     })();
     return () => {
       cancelled = true;
     };
   }, []);
-  return {
-    status,
-    required: status === "required"
-  };
+  return state;
 }
 function getGitHubRateLimitResourceLabel(resource) {
   switch (resource?.trim().toLowerCase()) {
@@ -32384,6 +32409,8 @@ function GitHubSyncSettingsPage() {
   const hasSavedToken = Boolean(form.githubTokenConfigured || showSavedTokenHint);
   const boardAccessConfigured = Boolean(form.paperclipBoardAccessConfigured);
   const boardAccessRequired = boardAccessRequirement.required;
+  const boardAccessSettingsVisible = boardAccessRequirement.settingsVisible;
+  const githubTokenPropagationSettingsVisible = boardAccessRequirement.githubTokenPropagationSettingsVisible;
   const boardAccessReady = !boardAccessRequired || hasCompanyContext && boardAccessConfigured;
   const tokenStatus = tokenStatusOverride ?? (hasSavedToken ? "valid" : "required");
   const tokenTone = tokenStatus === "valid" ? "success" : tokenStatus === "invalid" ? "danger" : "warning";
@@ -32492,7 +32519,7 @@ function GitHubSyncSettingsPage() {
   const manualSyncScopePillLabel = hasCompanyContext ? "This company" : "All companies";
   const manualSyncButtonLabel = hasCompanyContext ? "Run sync for this company" : "Run sync across all companies";
   const advancedSettingsSummary = formatAdvancedSettingsSummary(form.advancedSettings, availableAssignees, {
-    includePropagation: boardAccessRequired
+    includePropagation: githubTokenPropagationSettingsVisible
   });
   const assigneeSelectOptions = [
     { value: "", label: "Unassigned" },
@@ -32646,9 +32673,6 @@ function GitHubSyncSettingsPage() {
     });
   }
   async function propagateGitHubTokenToSelectedAgents(options) {
-    if (!boardAccessRequired) {
-      return;
-    }
     const selectedAgentIds = normalizeAgentIds(options.selectedAgentIds);
     const previousAgentIds = normalizeAgentIds(options.previousAgentIds);
     if (selectedAgentIds.length === 0 && previousAgentIds.length === 0) {
@@ -32855,7 +32879,7 @@ function GitHubSyncSettingsPage() {
       }));
       toast({
         title: boardIdentity.label ? `Paperclip board access connected as ${boardIdentity.label}` : "Paperclip board access connected",
-        body: "Direct Paperclip REST calls can now authenticate in authenticated deployments.",
+        body: "Direct Paperclip REST calls can now authenticate when the host requires board access.",
         tone: "success"
       });
       notifyGitHubSyncSettingsChanged();
@@ -32928,7 +32952,7 @@ function GitHubSyncSettingsPage() {
       if (!trustedPaperclipApiBaseUrl) {
         throw new Error("Could not resolve the current browser origin for Paperclip API calls.");
       }
-      const nextConfiguredPaperclipApiBaseUrl = paperclipApiBaseUrlIsOverride ? normalizedPaperclipApiBaseUrlDraft ?? "" : "";
+      const nextConfiguredPaperclipApiBaseUrl = trustedPaperclipApiBaseUrl;
       await patchPluginConfig(pluginId, {
         paperclipApiBaseUrl: nextConfiguredPaperclipApiBaseUrl
       });
@@ -32963,11 +32987,11 @@ function GitHubSyncSettingsPage() {
         advancedSettings: normalizeAdvancedSettings(result.advancedSettings),
         availableAssignees: result.availableAssignees ?? current.availableAssignees,
         paperclipApiBaseUrl: result.paperclipApiBaseUrl,
-        paperclipApiBaseUrlConfigured: paperclipApiBaseUrlIsOverride,
+        paperclipApiBaseUrlConfigured: Boolean(nextConfiguredPaperclipApiBaseUrl),
         updatedAt: result.updatedAt
       }));
       setScheduleFrequencyDraft(String(normalizeScheduleFrequencyMinutes(result.scheduleFrequencyMinutes)));
-      setPaperclipApiBaseUrlDraft(paperclipApiBaseUrlIsOverride ? nextConfiguredPaperclipApiBaseUrl : trustedPaperclipApiBaseUrl);
+      setPaperclipApiBaseUrlDraft(nextConfiguredPaperclipApiBaseUrl);
       toast({
         title: "GitHub sync setup saved",
         body: `Advanced defaults, mappings, and automatic sync are saved for ${currentCompanyName}.`,
@@ -33224,7 +33248,7 @@ function GitHubSyncSettingsPage() {
             /* @__PURE__ */ jsx2("div", { className: "ghsync__permission-audit-list", children: /* @__PURE__ */ jsx2("div", { className: "ghsync__permission-audit-item", children: /* @__PURE__ */ jsx2("span", { children: tokenPermissionAuditData?.warnings[0] ?? "Add a mapped repository in this company so GitHub Sync can verify the token permissions it needs." }) }) })
           ] }) : null
         ] }),
-        boardAccessRequired ? /* @__PURE__ */ jsxs2("section", { className: "ghsync__section", children: [
+        boardAccessSettingsVisible ? /* @__PURE__ */ jsxs2("section", { className: "ghsync__section", children: [
           /* @__PURE__ */ jsxs2("div", { className: "ghsync__section-head", children: [
             /* @__PURE__ */ jsxs2("div", { className: "ghsync__section-copy", children: [
               /* @__PURE__ */ jsxs2("div", { className: "ghsync__section-title-row", children: [
@@ -33565,7 +33589,7 @@ function GitHubSyncSettingsPage() {
               ),
               /* @__PURE__ */ jsx2("p", { className: "ghsync__hint", children: "Comma or newline separated." })
             ] }),
-            boardAccessRequired ? /* @__PURE__ */ jsxs2("div", { className: "ghsync__field", children: [
+            githubTokenPropagationSettingsVisible ? /* @__PURE__ */ jsxs2("div", { className: "ghsync__field", children: [
               /* @__PURE__ */ jsx2("label", { htmlFor: "advanced-token-propagation", children: "Propagate GitHub token to agents" }),
               /* @__PURE__ */ jsx2(
                 SettingsAgentMultiPicker,
@@ -33769,7 +33793,7 @@ function GitHubSyncSettingsPage() {
             ] }),
             /* @__PURE__ */ jsx2("span", { children: !repositoriesUnlocked ? "Requires a token." : savedMappingCount > 0 ? hasCompanyContext ? `${savedMappingCount} saved.` : `${savedMappingCount} saved.` : hasCompanyContext ? "Add a repository." : "Select a company." })
           ] }),
-          boardAccessRequired ? /* @__PURE__ */ jsxs2("div", { className: "ghsync__check", children: [
+          boardAccessSettingsVisible ? /* @__PURE__ */ jsxs2("div", { className: "ghsync__check", children: [
             /* @__PURE__ */ jsxs2("div", { className: "ghsync__check-top", children: [
               /* @__PURE__ */ jsx2("strong", { children: "Paperclip board access" }),
               /* @__PURE__ */ jsx2("span", { className: `ghsync__badge ${getToneClass(boardAccessStatusTone)}`, children: boardAccessStatusLabel })