ref: align monorepo infrastructure with amplify-backend patterns

.c8rc.json

@@ -0,0 +1,18 @@
+{
+    "lines": 85,
+    "functions": 85,
+    "branches": 85,
+    "exclude": [
+        "docs",
+        "scripts",
+        "packages/website",
+        "packages/test-infra",
+        "packages/integration-tests",
+        "packages/docs",
+        "**/*.test.ts",
+        "**/test/**"
+    ],
+    "all": true,
+    "check-coverage": true,
+    "src": "packages/"
+}

.changeset/monorepo-structure-refactor.md

@@ -0,0 +1,6 @@
+---
+"@nxsflow/amplify-overtone": patch
+"@nxsflow/amplify-overtone-client": patch
+---
+
+Align monorepo infrastructure with aws-amplify/amplify-backend patterns: migrate from pnpm to npm workspaces, replace tsup with tsc composite builds (output in lib/ instead of dist/), migrate tests from vitest to Node test runner (node:test + node:assert), add Microsoft API Extractor for public API tracking, add c8 coverage, add husky + lint-staged, and set up comprehensive GitHub Actions CI with health checks, canary builds, and multi-account E2E infrastructure

.claude/settings.json

@@ -14,36 +14,32 @@
             "Bash(gh run view:*)",
             "Bash(gh search:*)",
             "Bash(git ls-tree:*)",
+            "Bash(npm ci:*)",
+            "Bash(npm install:*)",
+            "Bash(npm run build:*)",
+            "Bash(npm run check:*)",
+            "Bash(npm run clean:*)",
+            "Bash(npm run client:*)",
+            "Bash(npm run diff:*)",
+            "Bash(npm run e2e:*)",
+            "Bash(npm run format:*)",
+            "Bash(npm run lint:*)",
+            "Bash(npm run overtone:*)",
+            "Bash(npm run test:*)",
+            "Bash(npm run test-infra:*)",
+            "Bash(npm run typecheck:*)",
+            "Bash(npm run update:*)",
+            "Bash(npm run vend:*)",
+            "Bash(npm run watch:*)",
+            "Bash(npm run website:*)",
+            "Bash(npm test:*)",
             "Bash(npm view:*)",
+            "Bash(npx api-extractor:*)",
             "Bash(npx biome:*)",
-            "Bash(npx vitest run:*)",
-            "Bash(pnpm add:*)",
-            "Bash(pnpm biome check:*)",
-            "Bash(pnpm build)",
-            "Bash(pnpm changeset:*)",
-            "Bash(pnpm client:build)",
-            "Bash(pnpm client:test)",
-            "Bash(pnpm client:typecheck)",
-            "Bash(pnpm e2e:test)",
-            "Bash(pnpm e2e:typecheck)",
-            "Bash(pnpm format)",
-            "Bash(pnpm install:*)",
-            "Bash(pnpm lint)",
-            "Bash(pnpm lint:*)",
-            "Bash(pnpm list:*)",
-            "Bash(pnpm overtone:build)",
-            "Bash(pnpm overtone:test)",
-            "Bash(pnpm overtone:test:*)",
-            "Bash(pnpm overtone:typecheck)",
-            "Bash(pnpm test)",
-            "Bash(pnpm test-infra:bootstrap)",
-            "Bash(pnpm test-infra:build)",
-            "Bash(pnpm test-infra:deploy)",
-            "Bash(pnpm test-infra:destroy)",
-            "Bash(pnpm test-infra:typecheck)",
-            "Bash(pnpm typecheck:*)",
-            "Bash(pnpm --filter website build)",
-            "Bash(pnpm --filter @nxsflow/test-infra typecheck:*)",
+            "Bash(npx c8:*)",
+            "Bash(npx changeset:*)",
+            "Bash(npx husky:*)",
+            "Bash(npx tsx:*)",
             "Fetch",
             "mcp__aws-knowledge-mcp-server__*",
             "mcp__awslabs_aws-documentation-mcp-server__*",

.claude/skills/cdk-construct-development/SKILL.md

@@ -88,7 +88,8 @@ CDK provides a powerful assertions API. Use it for construct unit tests:
 // packages/amplify-overtone/test/construct.test.ts
 import { App, Stack } from "aws-cdk-lib";
 import { Template } from "aws-cdk-lib/assertions";
-import { describe, expect, it } from "vitest";
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
 import { OvertoneConstruct } from "../src/construct.js";
 
 describe("OvertoneConstruct construct", () => {
@@ -122,7 +123,7 @@ describe("OvertoneConstruct construct", () => {
 
     const template = Template.fromStack(stack);
     // Assert on any additional resources created by the construct
-    expect(template.toJSON()).toBeDefined();
+    assert.ok(template.toJSON());
   });
 });
 ```
@@ -170,14 +171,24 @@ template.hasResourceProperties("AWS::IAM::Policy", {
 
 ---
 
-## tsup Build Notes
+## Build Notes
 
-The library uses tsup with `external: ["aws-cdk-lib", "constructs", "@aws-amplify/plugin-types"]`.
+The library uses `tsc` (TypeScript compiler) for building. Output goes to `lib/`.
 
-- All CDK imports are externalized — they must be provided by the consumer's project
-- Use `.js` extensions in source imports (tsup resolves them to `.ts` during build)
-- `dts: true` generates `.d.ts` files from TypeScript source
-- Build output: `dist/index.js` (ESM), `dist/index.cjs` (CJS), `dist/index.d.ts`
+- All CDK imports are externalized — they must be provided by the consumer's project (listed as peer deps in `package.json`)
+- Use `.js` extensions in source imports (tsc resolves them to `.ts` during build)
+- Build output: `lib/index.js` (ESM), `lib/index.d.ts` (declaration file)
+
+### API Extractor
+
+The library uses [API Extractor](https://api-extractor.com/) to enforce the public API surface. After changing public exports, run:
+
+```bash
+npm run check:api     # verifies the public API matches the committed report
+npm run update:api    # updates the API report file (commit the result)
+```
+
+The API report lives at `packages/amplify-overtone/api-report/amplify-overtone.api.md`. Commit changes to this file alongside the code change. CI runs `check:api` and fails if the report is out of date.
 
 ### Lambda handler bundling
 
@@ -195,7 +206,7 @@ Lambda handlers inside the construct (e.g. `packages/amplify-overtone/src/functi
 
 **Rules:**
 
-- Never bundle peer deps — they're externalized in tsup config
+- Never bundle peer deps — they're listed as `peerDependencies` in `package.json` and excluded from the build output
 - Test against the minimum supported version, not latest
 - Keep ranges permissive (`^2.0.0` not `^2.170.0`) — consumers have their own CDK constraints
 - Bumping a peer dep minimum range is a **major** version bump for this library

.claude/skills/cdk-testing/SKILL.md

@@ -23,7 +23,7 @@ packages/amplify-overtone/test/
 packages/integration-tests/  # E2E tests against deployed infrastructure (private)
 ```
 
-Vitest config for the construct package: `packages/amplify-overtone/vitest.config.ts` matches `include: ["test/**/*.test.ts"]`.
+Tests use the Node.js native test runner (`node:test`). Run them with `npm test` in the package or `npm test` from the repo root.
 
 **When to write which:**
 
@@ -40,7 +40,8 @@ Vitest config for the construct package: `packages/amplify-overtone/vitest.confi
 `OvertoneFactory` uses a static counter to enforce one `defineOvertone()` per backend. Reset between tests:
 
 ```typescript
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, it } from "node:test";
+import assert from "node:assert/strict";
 import { OvertoneFactory } from "../../src/factory.js"; // relative within packages/amplify-overtone/
 import { defineOvertone } from "../../src/index.js";
 
@@ -51,13 +52,13 @@ describe("defineOvertone", () => {
 
   it("returns an object with a getInstance method", () => {
     const factory = defineOvertone({});
-    expect(factory).toBeDefined();
-    expect(typeof factory.getInstance).toBe("function");
+    assert.ok(factory);
+    assert.strictEqual(typeof factory.getInstance, "function");
   });
 
   it("throws on second call", () => {
     defineOvertone({});
-    expect(() => defineOvertone({})).toThrow();
+    assert.throws(() => defineOvertone({}));
   });
 });
 ```
@@ -68,7 +69,8 @@ Test that invalid props produce clear error messages:
 
 ```typescript
 it("rejects invalid configuration", () => {
-  expect(() => defineOvertone({ invalidProp: "value" } as any)).toThrow(
+  assert.throws(
+    () => defineOvertone({ invalidProp: "value" } as any),
     /invalid/i,
   );
 });
@@ -118,13 +120,15 @@ import { Capture, Match, Template } from "aws-cdk-lib/assertions";
 Capture a dynamic value from the template for later assertion:
 
 ```typescript
+import assert from "node:assert/strict";
+
 const arnCapture = new Capture();
 template.hasResourceProperties("AWS::IAM::Policy", {
   PolicyDocument: {
     Statement: [{ Resource: arnCapture }],
   },
 });
-expect(arnCapture.asString()).toContain(":lambda:");
+assert.ok(arnCapture.asString().includes(":lambda:"));
 ```
 
 ### Key Principles
@@ -165,7 +169,7 @@ Common `beforeEach` pattern:
 
 ```typescript
 import { type Template } from "aws-cdk-lib/assertions";
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, it } from "node:test";
 import { createOvertoneTemplate } from "./helpers.js";
 
 let template: Template;
@@ -181,7 +185,8 @@ beforeEach(() => {
 
 ```typescript
 import { Match, type Template } from "aws-cdk-lib/assertions";
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, it } from "node:test";
+import assert from "node:assert/strict";
 import { createOvertoneTemplate } from "./helpers.js";
 
 describe("Core resources", () => {
@@ -194,7 +199,7 @@ describe("Core resources", () => {
   it("creates the primary resource", () => {
     // Assert the main AWS resource type created by OvertoneConstruct
     // Replace "AWS::SomeService::SomeResource" with the actual resource type
-    expect(template.toJSON().Resources).toBeDefined();
+    assert.ok(template.toJSON().Resources);
   });
 
   it("creates exactly one handler Lambda", () => {
@@ -207,7 +212,7 @@ describe("Core resources", () => {
 
 ```typescript
 import { Match, type Template } from "aws-cdk-lib/assertions";
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, it } from "node:test";
 import { createOvertoneTemplate } from "./helpers.js";
 
 describe("Handler Lambda", () => {
@@ -240,7 +245,7 @@ describe("Handler Lambda", () => {
 
 ```typescript
 import { Match, type Template } from "aws-cdk-lib/assertions";
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, it } from "node:test";
 import { createOvertoneTemplate } from "./helpers.js";
 
 describe("IAM permissions", () => {

.claude/skills/commit/SKILL.md

@@ -138,7 +138,7 @@ BREAKING CHANGE: OvertoneProps.config is now overtoneConfig
 This project uses `@changesets/cli` to track version bumps. When your commit affects the published package (new feature, bug fix, breaking change), you need a changeset:
 
 ```bash
-pnpm changeset
+npx changeset
 ```
 
 This creates a `.changeset/<random-name>.md` file. Commit it alongside your code:

.claude/skills/versioning-and-releases/SKILL.md

@@ -58,7 +58,7 @@ This preserves the invariant that `beta` is always a superset of `alpha` at the
 
 ```bash
 # Create changeset with your feature
-pnpm changeset
+npx changeset
 git add .changeset/ && git commit -m "feat: description"
 # Open PR targeting `alpha` (or `beta` if skipping alpha)
 ```
@@ -74,13 +74,13 @@ When the user says a feature is "ready for alpha":
 
    ```bash
    git checkout alpha
-   pnpm changeset pre enter alpha
+   npx changeset pre enter alpha
    ```
 
 3. **Version and publish:**
 
    ```bash
-   pnpm changeset version          # bumps to X.Y.Z-alpha.N
+   npx changeset version           # bumps to X.Y.Z-alpha.N
    git add .changeset/ packages/
    git commit -m "chore(release): version X.Y.Z-alpha.N"
    git push                        # CI publishes automatically
@@ -96,9 +96,9 @@ When the user says features are "ready for beta":
 
    ```bash
    git checkout beta && git merge alpha
-   pnpm changeset pre exit
-   pnpm changeset pre enter beta
-   pnpm changeset version          # bumps to X.Y.Z-beta.0
+   npx changeset pre exit
+   npx changeset pre enter beta
+   npx changeset version           # bumps to X.Y.Z-beta.0
    git add .changeset/ packages/
    git commit -m "chore(release): version X.Y.Z-beta.0"
    git push                        # CI publishes automatically
@@ -112,8 +112,8 @@ When the user says it's "ready to release" or "ready for stable":
 
    ```bash
    git checkout beta
-   pnpm changeset pre exit
-   pnpm changeset version          # bumps to stable X.Y.Z
+   npx changeset pre exit
+   npx changeset version           # bumps to stable X.Y.Z
    git add .changeset/ packages/
    git commit -m "chore(release): exit pre-release, bump to X.Y.Z"
    git push
@@ -139,13 +139,23 @@ npm view @nxsflow/amplify-overtone dist-tags
 npm view @nxsflow/amplify-overtone-client dist-tags
 ```
 
+## Local Publish Workflow (Verdaccio)
+
+Use `npm run vend` to publish packages locally via Verdaccio for manual integration testing before pushing to npm:
+
+```bash
+npm run vend          # starts Verdaccio, builds, and publishes packages locally
+```
+
+This spins up a local registry at `http://localhost:4873`. Useful for testing package installs in a consumer project without publishing to npm.
+
 ## CI Pipeline
 
-See `.github/workflows/publish.yml` for implementation. Key behaviors:
+See `.github/workflows/health_checks.yml` for implementation. Key behaviors:
 
-- **main push**: `changesets/action` creates a "Version Packages" PR (bumps versions, updates changelogs). Merging that PR publishes to npm with `latest` tag after manual approval (`production` environment).
-- **alpha/beta push**: Runs `changeset publish` directly. Pre mode sets the dist-tag automatically.
-- **PRs to main**: `.github/workflows/ci.yml` runs all four gates (build, typecheck, test, lint).
+- **main push**: `changesets/action` creates a "Version Packages" PR (bumps versions, updates changelogs). Merging that PR publishes to npm with `latest` tag after manual approval (`release` environment).
+- **alpha/beta push**: `publish_prerelease` job runs `changeset publish` directly. Pre mode sets the dist-tag automatically.
+- **PRs to main, alpha, or beta**: CI runs all gates (build, typecheck, test, lint, API checks).
 - **Publishing uses npm Trusted Publishing (OIDC)** — no npm token needed.
 
 ## Rollback

.github/CODEOWNERS

@@ -0,0 +1,9 @@
+# Default owners
+*  @nxsflow/amplify-overtone
+
+# API approval - public surface and dependencies
+**/API.md @nxsflow/amplify-overtone-api-approvers
+**/package.json @nxsflow/amplify-overtone-api-approvers
+
+# GitHub actions/checks approval
+/.github/ @nxsflow/amplify-overtone-admins

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,28 @@
+name: Bug Report
+description: Report a bug in Amplify Overtone
+labels: ["bug"]
+body:
+  - type: textarea
+    attributes:
+      label: Environment
+      description: Run `npx ampx info` and paste the output
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Description
+      description: Describe the bug
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to reproduce the bug
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Community Support
+    url: https://github.com/nxsflow/amplify-overtone/discussions
+    about: Ask questions and discuss with the community