Micronaut Plugin

Micronaut-focused Paperclip plugin that turns a project detail tab into a release cockpit: see the current and next version at a glance, inspect the default and upcoming release branches, create missing branches, and kick off merge-up work from inside Paperclip.

What You Get

• A project-scoped Micronaut branches detail tab for repositories in the micronaut-projects GitHub organization
• Current version from the latest GitHub release tag, normalized to plain semver
• Next version derived from projectVersion in the repository's gradle.properties
• Branch rows for the default branch plus the next minor and next major release lines
• Ahead/behind, diverged, missing, and version-alignment signals for each tracked branch
• A one-click Create branch action for missing upcoming branches
• A Merge up workflow that creates a real Paperclip issue, assigns it to a selected agent, and requests a Paperclip-managed assignment wakeup
• Cached project snapshots with a Last checked indicator and manual refresh

Requirements

• Node.js 24.11 or newer (the Paperclip plugin SDK baseline)
• A Paperclip instance with plugin support, version 2026.831.1 or newer
• A Paperclip project backed by a GitHub repository in the micronaut-projects organization
• Outbound access to the GitHub API from the plugin worker
• gh installed and authenticated on the Paperclip host if you want host-side branch creation and the GitHub CLI fallback path

Install

Install the published package into Paperclip:

paperclipai plugin install paperclip-micronaut-plugin

Pin a specific npm version if needed:

paperclipai plugin install paperclip-micronaut-plugin --version <version>

Install from a local checkout during development:

paperclipai plugin install --local .

Quick Start

1. Install the plugin in Paperclip.
2. Open a Paperclip project whose repository lives under micronaut-projects.
3. Open the Micronaut branches detail tab on that project.
4. Review the current version, next version, and branch health for the default, next minor, and next major lines.
5. Use Refresh to pull a fresh snapshot when needed.
6. Use Create branch when an expected future line does not exist yet.
7. Use Merge up to create and assign a Paperclip issue that tracks the merge from one branch into the next.

How It Works

The tab combines GitHub repository metadata with Paperclip-native workflow state:

• Current version comes from the latest GitHub release tag.
• Next version comes from projectVersion in the repository root gradle.properties on the default branch.
• Branch cards show last-updated data, ahead/behind status, and whether projectVersion matches the expected release-line value such as 4.2.0-SNAPSHOT.
• Create branch uses the GitHub CLI on the Paperclip host so branch creation happens with the operator's existing GitHub auth.
• Merge up creates a real Paperclip issue in todo, stamps it with Micronaut plugin origin and billing metadata, remembers the preferred assignee per company, and keeps the row linked to the issue until it closes.
• Assignment wakeups use Paperclip's issue wakeup API so scheduler, blocker, budget, and liveness checks stay in the host workflow instead of bypassing it with a direct agent invocation.
• PR chips appear when the assigned agent comments on that issue with a GitHub pull request URL.

For unsupported repositories, the hosted tab stays out of the way instead of rendering misleading fallback chrome.

Security And Privacy

• The plugin only requests the capabilities it needs for project reads, agent reads, issue reads/creation/wakeups, plugin state, outbound HTTP, and the hosted detail tab registration.
• Repository metadata is fetched from GitHub and cached in Paperclip plugin state to avoid unnecessary repeat requests.
• The plugin shells out to gh with explicit argv arguments instead of a shell command string, which reduces command-injection risk.
• gh is only needed for host-side branch creation and recoverable GitHub API fallback calls.
• Merge-up tracking stores lightweight operational metadata in plugin state and uses native Paperclip issues plus host-owned assignment wakeups for the actual work item.

Development

From the repository root:

pnpm install
pnpm typecheck
pnpm test
pnpm build

Additional verification commands:

• pnpm test:e2e for the headless Paperclip smoke flow
• pnpm verify:manual for an interactive local verification run

Both verification harnesses explicitly enable board approval for the disposable company, seed their test agents through Paperclip's board-governed hire flow, and approve pending hires before installing the local plugin. They also create the disposable Git-backed project with isolated issue workspaces enabled so merge-up issues exercise the current Paperclip project defaults.

Set PAPERCLIP_E2E_PAPERCLIPAI_PACKAGE=<package> to test a different paperclipai package; by default both harnesses run against [email protected] under node@24, matching the release's Docker baseline and this package's Node 24.11+ requirement (node:sqlite is not available on older runtimes).

Release

Paperclip 2026.831 adoption boundary

Paperclip 2026.831.1 makes plugin configuration company-scoped: ctx.config.get(companyId) requires a company context, workers start with an empty config and receive one configChanged replay per configured company, and workers that serve several companies with differing config must declare multiCompanyConfig: true. Plugin secret refs, which 2026.626 rejected at save time, are re-enabled as company-scoped { type: "secret_ref" } bindings resolved through ctx.secrets.resolve(ref, { companyId, configPath }). Agent tool execution now goes through the host tool gateway and is subject to each company's tool-access policy. The release also adds optional plugin capabilities for issue interactions (issue.interactions.read, issue.interactions.respond), issue attachments (issue.attachments.read), approvals (approvals.read, approvals.respond), and human-attributed comments (issue.comments.create_human_attributed).

The Micronaut release cockpit uses none of these surfaces, so this release-adoption PR keeps the plugin on the new SDK/runtime baseline without worker or manifest code changes. The worker declares no config schema, never calls ctx.config.get or ctx.secrets.resolve, registers no agent tools, jobs, or event subscriptions, and implements neither onConfigChanged nor onHealth, so the empty startup config, per-company replay, and multiCompanyConfig rules do not apply. Per-company settings (the preferred merge-up assignee) live in company-scoped plugin state, and every worker-to-host call happens inside a company-scoped data or action invocation, which satisfies the 2026.831 "company context is required" gate. The plugin does not request the new issue interaction, attachment, approval, or human-attributed comment capabilities.

As in 2026.626, the plugin does not create agents, routines, issue work modes, or external object providers, and does not use plugin entity mappings, environment drivers, or host-managed Skills Store APIs directly; those host/company-package capabilities stay with Paperclip and the live Micronaut Agent Company workflow.

When a company enables the experimental enableExternalObjects flag, any GitHub pull request URL posted in a merge-up issue's thread also gets a host-native external-object status chip (resolved by Paperclip's own GitHub provider), independent of and in addition to this plugin's own PR chips described above. The two are not the same mechanism and are not guaranteed to agree: the plugin's chip is scoped to the tracked merge-up row and reflects the plugin's own read of the linked pull request, while the host's chip is a generic per-comment resolution that applies to any PR URL in any issue thread. Operators should not expect the two to always be in lockstep if enableExternalObjects is on.

2026.831.1 also added an idempotencyKey field to Paperclip's issue-create API to deduplicate retried/concurrent creates. The plugin's merge-up assignment wakeup call already passes one (micronaut-merge-up:<issueId>), so repeated wakeup requests for the same tracked issue dedupe host-side. The merge-up issue creation call does not yet pass one: @paperclipai/[email protected]'s ctx.issues.create() does not forward idempotencyKey to the host (only requestWakeup/requestWakeups do), so this plugin still relies on its existing plugin-state existence check to avoid duplicate merge-up issues, which is not fully race-proof under concurrent "Start merge up" clicks. See the comment above the ctx.issues.create() call in src/worker.ts for details; this will be revisited once the SDK exposes the field on issue creation.

• Pull requests and pushes to main run GitHub Actions CI for typecheck, tests, build, and npm pack --dry-run.
• Published GitHub releases trigger the npm publish workflow.
• The release workflow derives the package version from the GitHub tag, writes that version into package.json, verifies the publish surface, and then publishes with provenance enabled.

License

MIT