add: automated release flow for widgets/packages, and event dispatch for automated wallet integration trigger

.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Release automation and integration contracts require maintainer review.
+/.github/workflows/ @GoodDollar/goodbuilders-maintainers
+/scripts/release/ @GoodDollar/goodbuilders-maintainers
+/schemas/ @GoodDollar/goodbuilders-maintainers
+/packages/*/integration-manifest.json @GoodDollar/goodbuilders-maintainers

.github/workflows/copilot-setup-steps.yml

@@ -32,17 +32,17 @@ jobs:
     steps:
       # 1. Check out the repository before running any package-manager commands.
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
 
       # 2. Install the declared pnpm version so pnpm is available on PATH.
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
         with:
           version: 9.15.0
 
       # 3. Install the repository's Node.js version and enable pnpm dependency caching.
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 22.x
           cache: pnpm

.github/workflows/deploy-ai-credits-web.yml

@@ -14,6 +14,9 @@ on:
       - 'pnpm-lock.yaml'
       - 'pnpm-workspace.yaml'
 
+permissions:
+  contents: read
+
 concurrency:
   group: deploy-ai-credits-web-${{ github.ref }}
   cancel-in-progress: true
@@ -30,15 +33,15 @@ jobs:
       url: ${{ steps.deploy.outputs.url }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
         with:
           version: 9.15.0
 
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 22
           cache: pnpm

.github/workflows/deploy-storybook.yml

@@ -11,6 +11,9 @@ on:
       - 'pnpm-lock.yaml'
       - 'pnpm-workspace.yaml'
 
+permissions:
+  contents: read
+
 concurrency:
   group: deploy-storybook-${{ github.ref }}
   cancel-in-progress: true
@@ -30,15 +33,15 @@ jobs:
         working-directory: examples/storybook
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
         with:
           version: 9.15.0
 
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 22
           cache: pnpm

.github/workflows/promote-next.yml

@@ -0,0 +1,59 @@
+name: Promote main to next
+
+# main remains the development/deployment branch. A reviewed manual promotion is the only
+# supported path to next, and only next is wired to npm publication.
+on:
+  workflow_dispatch:
+    inputs:
+      source:
+        description: Source branch (intentionally restricted)
+        required: true
+        type: choice
+        options: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: goodwidget-next-promotion
+  cancel-in-progress: false
+
+jobs:
+  promote:
+    permissions:
+      contents: write
+    # The release environment supplies the maintainer approval gate before next can move.
+    environment: release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require a maintainer and main as source
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ACTOR: ${{ github.actor }}
+          SOURCE: ${{ inputs.source }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          test "$SOURCE" = main
+          permission="$(gh api "repos/$REPOSITORY/collaborators/$ACTOR/permission" --jq .permission)"
+          test "$permission" = admin -o "$permission" = maintain
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          fetch-depth: 0
+          ref: main
+      - name: Create or update next
+        env:
+          GIT_AUTHOR_NAME: goodwidget-release
+          GIT_AUTHOR_EMAIL: goodwidget-release@users.noreply.github.com
+          GIT_COMMITTER_NAME: goodwidget-release
+          GIT_COMMITTER_EMAIL: goodwidget-release@users.noreply.github.com
+        run: |
+          git fetch origin main next || git fetch origin main
+          if git show-ref --verify --quiet refs/remotes/origin/next; then
+            # A normal merge preserves next's release history and exits before push on conflicts.
+            git switch --create next --track origin/next
+            git merge --no-edit origin/main
+          else
+            # The first promotion creates the long-lived publication branch from main.
+            git switch --create next origin/main
+          fi
+          git push origin next

.github/workflows/recover-release.yml

@@ -0,0 +1,57 @@
+name: Recover committed npm release
+
+# Recovery never computes a new version. It republishes (or only verifies) the version
+# already committed on next after an interrupted registry publication.
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        description: Already-versioned production package to publish or verify
+        required: true
+        type: choice
+        options:
+          - '@goodwidget/ui'
+          - '@goodwidget/core'
+          - '@goodwidget/embed'
+          - '@goodwidget/ai-credits-widget'
+          - '@goodwidget/citizen-claim-widget'
+          - '@goodwidget/goodreserve-widget'
+          - '@goodwidget/staking-migration-widget'
+          - '@goodwidget/streaming-widget'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: goodwidget-npm-release
+  cancel-in-progress: false
+
+jobs:
+  recover:
+    permissions:
+      contents: read
+      id-token: write
+    environment: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          fetch-depth: 0
+          ref: next
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 22.14.0
+          registry-url: https://registry.npmjs.org
+      - name: Configure pinned toolchain
+        run: |
+          corepack enable
+          corepack prepare pnpm@9.15.0 --activate
+      - run: pnpm install --frozen-lockfile
+      - name: Publish the authoritative committed version
+        env:
+          RECOVERY_PACKAGE: ${{ inputs.package }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: 'true'
+          GOODWALLET_DISPATCH_PAT: ${{ secrets.GOODWALLET_DISPATCH_PAT }}
+          ENABLE_GOODWALLET_DISPATCH: ${{ vars.ENABLE_GOODWALLET_DISPATCH }}
+        run: pnpm release:recover

.github/workflows/release-next.yml

@@ -0,0 +1,56 @@
+name: Release production packages
+
+# Publication is intentionally branch-gated: pushes to main may deploy demos, but cannot
+# enter this workflow. A maintainer must first promote main to next.
+on:
+  push:
+    branches: [next]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: goodwidget-npm-release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    # The release script pushes its authoritative version commit back to next. The marker
+    # prevents that bot-authored push from recursively starting another release.
+    if: ${{ !contains(github.event.head_commit.message, '[goodwidget release]') }}
+    permissions:
+      contents: write
+      id-token: write
+    environment: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          fetch-depth: 0
+          ref: next
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 22.14.0
+          registry-url: https://registry.npmjs.org
+      - name: Configure pinned toolchain
+        run: |
+          corepack enable
+          corepack prepare pnpm@9.15.0 --activate
+          node --version
+          pnpm --version
+      - name: Install immutable workspace
+        run: pnpm install --frozen-lockfile
+      - name: Configure release identity
+        run: |
+          git config user.name goodwidget-release
+          git config user.email goodwidget-release@users.noreply.github.com
+      - name: Build, pack, publish, verify, and dispatch
+        env:
+          RELEASE_BASE_SHA: ${{ github.event.before }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: 'true'
+          GOODWALLET_DISPATCH_PAT: ${{ secrets.GOODWALLET_DISPATCH_PAT }}
+          # Wallet automation remains inert until both this explicit switch and its scoped
+          # repository-dispatch credential are configured in the protected environment.
+          ENABLE_GOODWALLET_DISPATCH: ${{ vars.ENABLE_GOODWALLET_DISPATCH }}
+        run: pnpm release:widgets

.github/workflows/validate-release.yml

@@ -0,0 +1,35 @@
+name: Validate release contracts
+
+# Keep graph detection, packaging, and the wallet-facing manifest contract reviewable
+# before either promotion or release credentials can be reached.
+on:
+  pull_request:
+    paths:
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'pnpm-workspace.yaml'
+      - 'packages/**'
+      - 'schemas/**'
+      - 'scripts/release/**'
+      - '.github/workflows/**'
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 22.14.0
+      - name: Configure pinned toolchain
+        run: |
+          corepack enable
+          corepack prepare pnpm@9.15.0 --activate
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test:release
+      - run: pnpm lint
+      - run: pnpm build
+      - run: pnpm validate:register-entries

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GoodDollar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/PACKAGING.md

@@ -129,21 +129,30 @@ export const MyWidgetElement = createMiniAppElement(
 
 ```ts
 // src/register.ts
-import { MyWidgetElement } from './element'
-
 const TAG = 'my-widget'
 
-export function register(tagName: string = TAG): string {
+export async function register(tagName: string = TAG): Promise<string> {
+  // SSR-aware bundlers may evaluate this entry without browser globals. Keep
+  // the browser-focused element graph behind the guard as well as DOM access.
+  if (typeof customElements === 'undefined') return tagName
   if (!customElements.get(tagName)) {
+    const { MyWidgetElement } = await import('./element')
     customElements.define(tagName, MyWidgetElement)
   }
   return tagName
 }
 
 // Auto-register on import
-register()
+void register()
 ```
 
+`createMiniAppElement()` and `register.ts` must both be safe to evaluate in
+Node. The dynamic element import is deliberately reached only in a browser;
+registration becomes a no-op on the server and runs normally when the browser
+bundle evaluates. This lets Next.js inspect the package without loading
+browser-focused dependencies or attempting to mount a Custom Element during
+server rendering.
+
 ```ts
 // src/index.ts
 export { MyWidget } from './MyWidget'

package.json

@@ -1,6 +1,7 @@
 {
   "name": "goodwidget",
   "private": true,
+  "license": "MIT",
   "scripts": {
     "build": "turbo run build",
     "dev": "turbo run dev",
@@ -16,7 +17,12 @@
     "vercel:deploy:production": "pnpm vercel:build:production && vercel deploy --prebuilt --prod",
     "test:storybook": "pnpm --filter @goodwidget/storybook test:storybook",
     "test:demo": "playwright test",
-    "test:ai-credits-web": "playwright test --config apps/ai-credits-web/playwright.config.ts"
+    "test:ai-credits-web": "playwright test --config apps/ai-credits-web/playwright.config.ts",
+    "test:release": "node --test scripts/release/*.test.mjs && node scripts/release/validate-packages.mjs && node scripts/release/validate-manifests.mjs",
+    "release:widgets": "node scripts/release/release.mjs",
+    "release:recover": "node scripts/release/release.mjs recover",
+    "validate:manifests": "node scripts/release/validate-manifests.mjs",
+    "validate:register-entries": "node scripts/release/validate-register-entries.mjs"
   },
   "devDependencies": {
     "@playwright/test": "^1.44.0",
@@ -26,6 +32,7 @@
     "prettier": "^3.5.0",
     "@typescript-eslint/eslint-plugin": "^8.25.0",
     "@typescript-eslint/parser": "^8.25.0",
+    "ajv": "8.17.1",
     "vercel": "^54.14.2"
   },
   "packageManager": "pnpm@9.15.0"

packages/ai-credits-widget/integration-manifest.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "2.0.0",
+  "hostContractVersion": "1.0.0",
+  "widgetId": "goodwidget.ai-credits",
+  "packageName": "@goodwidget/ai-credits-widget",
+  "entries": {
+    "react": {
+      "export": "AiCreditsWidget"
+    },
+    "webComponent": {
+      "registerPath": "./register",
+      "tagName": "ai-credits-widget"
+    }
+  }
+}