Modernize helper package distribution contracts

governance/repository-health/contract-baseline.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "recordedAt": "2026-07-26",
-  "findingCount": 83,
+  "findingCount": 70,
   "findings": [
     {
       "id": ".::missing-script::format:check",
@@ -39,74 +39,22 @@
       "id": "docs-site::missing-script::test",
       "message": "Profile documentation-site requires script test"
     },
-    {
-      "id": "packages/helpers/create-bsv-app::missing-script::format:check",
-      "message": "Profile cli requires script format:check"
-    },
-    {
-      "id": "packages/helpers/create-bsv-app::missing-script::pack:check",
-      "message": "Profile cli requires script pack:check"
-    },
-    {
-      "id": "packages/helpers/create-bsv-app::missing-script::typecheck",
-      "message": "Profile cli requires script typecheck"
-    },
     {
       "id": "packages/helpers/did-client::missing-script::format:check",
       "message": "Profile browser-library requires script format:check"
     },
-    {
-      "id": "packages/helpers/did-client::missing-script::pack:check",
-      "message": "Profile browser-library requires script pack:check"
-    },
-    {
-      "id": "packages/helpers/did-client::missing-script::test:browser",
-      "message": "Profile browser-library requires script test:browser"
-    },
-    {
-      "id": "packages/helpers/did-client::missing-script::typecheck",
-      "message": "Profile browser-library requires script typecheck"
-    },
     {
       "id": "packages/helpers/did::missing-script::format:check",
       "message": "Profile dual-runtime-library requires script format:check"
     },
-    {
-      "id": "packages/helpers/did::missing-script::pack:check",
-      "message": "Profile dual-runtime-library requires script pack:check"
-    },
-    {
-      "id": "packages/helpers/did::missing-script::typecheck",
-      "message": "Profile dual-runtime-library requires script typecheck"
-    },
     {
       "id": "packages/helpers/simple::missing-script::format:check",
       "message": "Profile browser-library requires script format:check"
     },
-    {
-      "id": "packages/helpers/simple::missing-script::pack:check",
-      "message": "Profile browser-library requires script pack:check"
-    },
-    {
-      "id": "packages/helpers/simple::missing-script::test:browser",
-      "message": "Profile browser-library requires script test:browser"
-    },
-    {
-      "id": "packages/helpers/simple::missing-script::typecheck",
-      "message": "Profile browser-library requires script typecheck"
-    },
     {
       "id": "packages/helpers/ts-templates::missing-script::format:check",
       "message": "Profile dual-runtime-library requires script format:check"
     },
-    {
-      "id": "packages/helpers/ts-templates::missing-script::pack:check",
-      "message": "Profile dual-runtime-library requires script pack:check"
-    },
-    {
-      "id": "packages/helpers/ts-templates::missing-script::typecheck",
-      "message": "Profile dual-runtime-library requires script typecheck"
-    },
     {
       "id": "packages/messaging/authsocket-client::missing-script::format:check",
       "message": "Profile browser-library requires script format:check"

package.json

@@ -28,8 +28,10 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
+    "esbuild": "0.28.1",
     "prettier": "3.9.6",
     "publint": "0.3.22",
+    "vite": "8.1.5",
     "yaml": "^2.9.0"
   },
   "engines": {

packages/helpers/create-bsv-app/README.md

@@ -42,41 +42,41 @@ The catalogue is defined once in `src/starters.ts` and drives the CLI, interacti
 
 ### Generated starters
 
-| id | What it creates |
-| --- | --- |
-| `custom` | Choose React, Express, or both and select capabilities yourself. |
-| `react` | Vite + React + TypeScript with the wallet baseline. |
-| `express` | Express + TypeScript with the wallet/auth server baseline. |
+| id           | What it creates                                                           |
+| ------------ | ------------------------------------------------------------------------- |
+| `custom`     | Choose React, Express, or both and select capabilities yourself.          |
+| `react`      | Vite + React + TypeScript with the wallet baseline.                       |
+| `express`    | Express + TypeScript with the wallet/auth server baseline.                |
 | `full-stack` | Independent `client/` and `server/` packages plus one root `npm run dev`. |
 
 ### Complete example starters
 
-| id | Example | BRC-102 project structure |
-| --- | --- | --- |
-| `brc102-frontend` | Frontend project template | Yes |
-| `brc102-backend` | Overlay backend project template | Yes |
-| `pollr` | Blockchain polls backed by overlays | Yes |
-| `meter` | Wallets, sCrypt contracts, and overlays | Yes |
-| `metamarket` | Marketplace for 3D objects | Yes |
-| `todo` | Wallet baskets and encryption | Yes |
-| `marscast` | Micropayment-monetized Mars weather | No |
-| `coinflip` | Trustless peer-to-peer interactions | Yes |
-| `postboard` | Public message board on an overlay | Yes |
-| `locksmith` | Lock and unlock coins with a message | Yes |
-| `peerpay` | Identity-backed peer-to-peer payments | Yes |
-| `atfinder` | Alternative PeerPay interface | No |
+| id                | Example                                 | BRC-102 project structure |
+| ----------------- | --------------------------------------- | ------------------------- |
+| `brc102-frontend` | Frontend project template               | Yes                       |
+| `brc102-backend`  | Overlay backend project template        | Yes                       |
+| `pollr`           | Blockchain polls backed by overlays     | Yes                       |
+| `meter`           | Wallets, sCrypt contracts, and overlays | Yes                       |
+| `metamarket`      | Marketplace for 3D objects              | Yes                       |
+| `todo`            | Wallet baskets and encryption           | Yes                       |
+| `marscast`        | Micropayment-monetized Mars weather     | No                        |
+| `coinflip`        | Trustless peer-to-peer interactions     | Yes                       |
+| `postboard`       | Public message board on an overlay      | Yes                       |
+| `locksmith`       | Lock and unlock coins with a message    | Yes                       |
+| `peerpay`         | Identity-backed peer-to-peer payments   | Yes                       |
+| `atfinder`        | Alternative PeerPay interface           | No                        |
 
 Complete examples are shallow-cloned from their declared branch, detached from the source repository by removing the copied `.git` directory, and recorded with repository, ref, and commit provenance. BRC-102 is useful deployment metadata, not a requirement for inclusion in the catalogue.
 
 ## Generated capabilities
 
 Generated starters can include these composable capabilities:
 
-| id | What it adds |
-| --- | --- |
-| `wallet-connect` | Default baseline: connect a BRC-100 desktop or relay wallet, expose app-wide wallet state, and provide the shared BRC-103 proof primitive. |
-| `wallet-login` | Passwordless login using a proof bound to the server identity and `action: "login"`. |
-| `signed-requests` | Per-request authentication using a proof bound to the route and request body. |
+| id                | What it adds                                                                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `wallet-connect`  | Default baseline: connect a BRC-100 desktop or relay wallet, expose app-wide wallet state, and provide the shared BRC-103 proof primitive. |
+| `wallet-login`    | Passwordless login using a proof bound to the server identity and `action: "login"`.                                                       |
+| `signed-requests` | Per-request authentication using a proof bound to the route and request body.                                                              |
 
 New generated projects include `wallet-connect` by default. Capability dependencies are expanded in new mode, so selecting `wallet-login` or `signed-requests` also installs the wallet baseline.
 
@@ -171,25 +171,25 @@ The UI listens only on `127.0.0.1`, shows the same registry-backed choices, and
 
 ## Flags
 
-| Flag | Description |
-| --- | --- |
-| `new` / `add` | Optional mode subcommand. |
-| `--dir <path>` | Target directory; also accepted as the one positional argument. |
-| `--starter <id>` | Generated or complete-example starter from the unified catalogue. |
-| `--name <name>` | Project name; defaults to the target directory in non-interactive new mode. |
-| `--frontend <react\|none>` | Custom generated frontend. |
-| `--backend <express\|none>` | Custom generated backend. |
-| `--variant <name>` | Vite template variant; defaults to `react-ts`. |
-| `--capabilities <a,b>` | Comma-separated generated capability ids. |
-| `--bsv-dir <path>` | Capability helper directory; defaults to `src/bsv`. |
-| `--package-manager <npm\|pnpm\|yarn\|bun>` | Generator and install package manager. |
-| `--network <main\|test>` | Generated BSV network default. |
-| `--install` / `--skip-install` | Enable or skip dependency installation; enabled by default. |
-| `--glue` / `--no-glue` | Enable or skip automatic generated app wiring. |
-| `--force` | In add mode, overwrite existing capability utility files. |
-| `--file <path>` | Read a complete JSON configuration. |
-| `--ui` | Use the local browser interface. |
-| `--yes` | Resolve from flags without prompting. |
+| Flag                                       | Description                                                                 |
+| ------------------------------------------ | --------------------------------------------------------------------------- |
+| `new` / `add`                              | Optional mode subcommand.                                                   |
+| `--dir <path>`                             | Target directory; also accepted as the one positional argument.             |
+| `--starter <id>`                           | Generated or complete-example starter from the unified catalogue.           |
+| `--name <name>`                            | Project name; defaults to the target directory in non-interactive new mode. |
+| `--frontend <react\|none>`                 | Custom generated frontend.                                                  |
+| `--backend <express\|none>`                | Custom generated backend.                                                   |
+| `--variant <name>`                         | Vite template variant; defaults to `react-ts`.                              |
+| `--capabilities <a,b>`                     | Comma-separated generated capability ids.                                   |
+| `--bsv-dir <path>`                         | Capability helper directory; defaults to `src/bsv`.                         |
+| `--package-manager <npm\|pnpm\|yarn\|bun>` | Generator and install package manager.                                      |
+| `--network <main\|test>`                   | Generated BSV network default.                                              |
+| `--install` / `--skip-install`             | Enable or skip dependency installation; enabled by default.                 |
+| `--glue` / `--no-glue`                     | Enable or skip automatic generated app wiring.                              |
+| `--force`                                  | In add mode, overwrite existing capability utility files.                   |
+| `--file <path>`                            | Read a complete JSON configuration.                                         |
+| `--ui`                                     | Use the local browser interface.                                            |
+| `--yes`                                    | Resolve from flags without prompting.                                       |
 
 Unknown options, missing flag values, invalid enum values, conflicting modes, and extra positional arguments are rejected.
 

packages/helpers/create-bsv-app/jest.config.cjs

@@ -6,6 +6,16 @@ module.exports = {
   moduleFileExtensions: ['ts', 'js', 'json', 'node'],
   moduleNameMapper: { '^(\\.{1,2}/.*)\\.js$': '$1' },
   transform: {
-    '^.+\\.tsx?$': ['ts-jest', { tsconfig: { module: 'commonjs', moduleResolution: 'bundler', esModuleInterop: true, types: ['node', 'jest'] } }]
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          module: 'commonjs',
+          moduleResolution: 'bundler',
+          esModuleInterop: true,
+          types: ['node', 'jest']
+        }
+      }
+    ]
   }
 }

packages/helpers/create-bsv-app/package.json

@@ -4,23 +4,34 @@
   "sideEffects": false,
   "description": "The unified CLI and starter catalogue for creating BSV applications",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "bin": {
     "create-bsv-app": "dist/index.js"
   },
   "files": [
     "dist",
     ".claude",
+    "README.md",
     "LICENSE.txt"
   ],
   "scripts": {
     "build": "tsc",
+    "clean": "rm -rf dist coverage",
+    "dev": "node dist/index.js",
+    "format:check": "pnpm --workspace-root exec prettier --check \"packages/helpers/create-bsv-app/src/**/*.ts\" \"packages/helpers/create-bsv-app/README.md\" \"packages/helpers/create-bsv-app/*.{cjs,js,json}\"",
+    "lint": "oxlint src --deny-warnings",
+    "pack:check": "node ../../../scripts/check-package-artifact.mjs . --modes cli --bin create-bsv-app --bin-args --help",
+    "prepublishOnly": "pnpm build",
     "test": "jest",
     "test:coverage": "jest --coverage --coverageReporters=text --coverageReporters=lcov",
-    "lint": "oxlint src",
-    "lint:ci": "oxlint src",
-    "clean": "rm -rf dist coverage",
-    "dev": "node dist/index.js"
+    "typecheck": "tsc --project tsconfig.json --noEmit"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0"

packages/helpers/create-bsv-app/src/__tests__/agents-md.test.ts

@@ -21,6 +21,20 @@ const config: ProjectConfig = {
 }
 
 describe('renderAgentsMd', () => {
+  test('documents a project with no installed capabilities without empty wiring blocks', () => {
+    const md = renderAgentsMd(
+      {
+        ...config,
+        capabilities: []
+      },
+      []
+    )
+
+    expect(md).toContain('# demo — agent guide')
+    expect(md).not.toContain('## Wiring')
+    expect(md).not.toContain('### `server/src/index.ts`')
+  })
+
   test('includes header, deps, and the wallet-login section', () => {
     // wallet-login requires wallet-connect; render both so @bsv/auth (from wallet-connect) appears in deps
     const md = renderAgentsMd(config, [walletConnect, walletLogin])