From eea2565dd5bdff3e870b6cd598dc411e84eaa35a Mon Sep 17 00:00:00 2001
From: Kris Nye <krisnye@gmail.com>
Date: Tue, 28 Jul 2026 14:03:06 -0700
Subject: [PATCH] refactor: uniform workspace scripts; no package-identity
 forks in root/CI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root and CI forked on package identity: CI ran unit tests for a hardcoded
subset and applied test:node only to data-persistence, root typecheck listed
sample packages by name, and publish enumerated the six publishable packages
by name — a list that had already drifted from the `private` field (it omitted
data-persistence and data-sync, both private:false). Every new package forced
edits to these central lists.

Replace all of it with uniform recursive invocation. Each package owns HOW it
builds/tests/typechecks via standard script names; root and CI just call
`pnpm -r run <script>`, which pnpm runs in dependency order and skips for
packages that don't define the script.

- CI: one job running check:workspace, typecheck, lint, build, test — each a
  single `pnpm -r run` with zero package names. Now typechecks every package
  (samples included) and runs each package's complete suite (data-persistence's
  browser tests now run in CI, previously never did).
- Publishing is governed solely by `private`: `pnpm -r publish` ships every
  private:false package and skips the rest. Removed all `publish-public`
  scripts (6 real + 7 stale no-ops on private samples) and the hardcoded root
  publish list. NOTE: data-persistence and data-sync are private:false, so they
  become publishable — set private:true if either should stay unreleased.
- core `test` now skips perf tests by default (folds the old test:ci); perf
  moved to test:perf.
- Root typecheck collapses the foundation/libraries/samples name lists into
  `pnpm -r run typecheck`.
- scripts/check-workspace-conventions.mjs (CI: pnpm run check:workspace) enforces
  the rules: every package sets `private` explicitly, and no publish-public
  scripts. Convention documented in CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      | 77 +++++--------------
 CLAUDE.md                                     | 31 ++++++++
 package.json                                  |  8 +-
 packages/data-ai/package.json                 |  3 +-
 packages/data-gpu-hopper/package.json         |  3 +-
 packages/data-gpu/package.json                |  1 -
 .../data-lit-space-rock-game/package.json     |  3 +-
 packages/data-lit-tictactoe/package.json      |  3 +-
 packages/data-lit-todo/package.json           |  3 +-
 packages/data-lit/package.json                |  1 -
 packages/data-react-hello/package.json        |  3 +-
 packages/data-react-pixie/package.json        |  3 +-
 packages/data-react/package.json              |  1 -
 packages/data-solid-dashboard/package.json    |  3 +-
 packages/data-solid/package.json              |  1 -
 packages/data/package.json                    |  5 +-
 scripts/check-workspace-conventions.mjs       | 44 +++++++++++
 17 files changed, 107 insertions(+), 86 deletions(-)
 create mode 100644 scripts/check-workspace-conventions.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8323c2c1..a1277004 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,15 +1,12 @@
 name: CI
 
-# Validates every pull request (and pushes to main) before merge. Prior to
-# this workflow the only GitHub Action was the post-merge docs deploy, so a PR
-# whose `tsc -b` / unit tests were red could still be merged green — exactly
-# what happened with #114. This gate makes those failures block the merge.
-#
-# Two jobs:
-#   data     — @adobe/data core: typecheck (tsc -b + WASM), lint, unit tests.
-#   packages — downstream published packages: build (tsc -b) + tests for each.
-#              Runs after `data` so a core failure surfaces once, not twice.
-#              @adobe/data is rebuilt here to provide dist/ for downstream tsc.
+# Validates every pull request (and pushes to main) before merge. The gate is
+# fully uniform: it never names individual packages. Each package owns how it
+# builds/tests/typechecks via standard script names, and every step here is a
+# single recursive invocation that pnpm runs in dependency (topological) order,
+# skipping packages that don't define the script. Adding a package therefore
+# needs no change to this file — see `scripts/check-workspace-conventions.mjs`
+# and the "Workspace script conventions" section of CLAUDE.md.
 
 on:
   pull_request:
@@ -24,8 +21,8 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  data:
-    name: "@adobe/data — typecheck, lint, test"
+  ci:
+    name: typecheck · lint · build · test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -41,53 +38,17 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - name: Type-check (tsc -b, project references)
-        run: pnpm --filter @adobe/data run typecheck
+      - name: Check workspace conventions
+        run: pnpm run check:workspace
 
-      - name: Lint
-        run: pnpm --filter @adobe/data run lint
+      - name: Type-check (every package, topological)
+        run: pnpm -r run typecheck
 
-      - name: Unit tests
-        run: pnpm --filter @adobe/data run test:ci
+      - name: Lint (every package that defines it)
+        run: pnpm -r run lint
 
-  packages:
-    name: "downstream packages — build, test"
-    runs-on: ubuntu-latest
-    needs: [data]
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: pnpm/action-setup@v6
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - run: pnpm install --frozen-lockfile
-
-      - name: Build @adobe/data (provides dist/ for downstream tsc)
-        run: pnpm --filter @adobe/data run typecheck
-
-      - name: Build every downstream package (type-check via tsc -b / vite)
-        # Builds ALL workspace packages except the core (already built above),
-        # including the private, unscoped sample apps (data-p2p-tictactoe,
-        # data-lit-todo, …). A previous `--filter '@adobe/data-*'` only matched
-        # scoped published packages, so a type/build error that surfaced only in
-        # a private sample (e.g. a stripped `.d.ts` member) merged green.
-        run: pnpm --filter '!@adobe/data' run build
+      - name: Build (every package, topological)
+        run: pnpm -r run build
 
-      - name: Test downstream packages
-        # Every workspace package except the core (tested in the `data` job) and
-        # data-persistence (whose `test` script pulls in Playwright — run its
-        # node project instead). pnpm skips packages that declare no `test`
-        # script. This now includes the private sample apps (data-lit-todo,
-        # data-lit-tictactoe, …); previously they were only built, so a broken
-        # sample unit test (e.g. the data-lit-todo conformance suite) merged green.
-        run: |
-          pnpm --filter '!@adobe/data' \
-               --filter '!@adobe/data-persistence' \
-               run test
-          pnpm --filter @adobe/data-persistence run test:node
+      - name: Test (each package runs its own complete suite)
+        run: pnpm -r run test
diff --git a/CLAUDE.md b/CLAUDE.md
index 86c5de07..6f1c3734 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,3 +7,34 @@ Do not use `await` at module top level anywhere in this repo's package sources.
 **Why:** Bundlers (Rolldown / Vite 8) wrap any module containing TLA — and every module that transitively imports it — in an async lazy-init function whose exports are only available via `await`. When those wrappers participate in an import cycle (very common through barrel re-exports), the cycle becomes a circular-await chain with no live-binding escape hatch, and the whole graph deadlocks silently. Native ESM in dev resolves cycles via live bindings, so dev appears fine; only the bundled output hangs, with no console error.
 
 See `packages/data/src/cache/data-cache.ts` (`createGlobalDataCache`) for the lazy-init pattern, and `packages/data/src/cache/blob-store.ts` (`cachePromise` inside `createBlobStore`) for the same idea applied at factory scope.
+
+## Workspace script conventions
+
+The root and CI never name individual packages. They invoke uniform recursive
+scripts (`pnpm -r run <script>`), which pnpm runs in dependency order and skips
+for packages that don't define the script. Each package owns *how* it does each
+step; the pipeline just calls the standard name. This is what keeps the monorepo
+scalable — a new package "just works" with zero edits to any central list.
+
+Standard script names a package may define:
+
+- **`build`** — produce dist / bundle; must fail on type or bundler errors.
+- **`typecheck`** — type-check (usually `tsc -b` or `tsc --noEmit`).
+- **`test`** — run the package's *complete* suite, self-contained and runnable
+  in CI. If a package needs a browser it installs and drives it itself (see
+  `data-persistence`, whose `test` installs chromium and runs both projects).
+  Keep long/optional lanes under suffixed names (`test:browser`, `test:perf`)
+  that the uniform pipeline does not call.
+- **`lint`** — lint the package.
+- **`dev`** — local dev/watch.
+
+Do **not** add a `publish-public` (or similar) script. Publishing is governed
+*only* by the `private` field: `pnpm -r publish` publishes every package with
+`private: false` and skips the rest. Every package must set `private`
+explicitly — an absent `private` means "publishable" to npm, which we forbid so
+nothing ships by accident. `scripts/check-workspace-conventions.mjs` (run in CI
+via `pnpm run check:workspace`) enforces both rules.
+
+To make a package publishable, set `private: false`; to hold it back, set
+`private: true`. That one field is the single source of truth — there is no list
+to update anywhere else.
diff --git a/package.json b/package.json
index f4a2e9b8..771233b9 100644
--- a/package.json
+++ b/package.json
@@ -10,15 +10,13 @@
     "test": "pnpm -r run test",
     "lint": "pnpm -r run lint",
     "lint-fix": "pnpm -r run lint-fix",
-    "typecheck": "pnpm run typecheck:foundation && pnpm run typecheck:libraries && pnpm run typecheck:samples",
-    "typecheck:foundation": "pnpm --filter @adobe/data run typecheck",
-    "typecheck:libraries": "pnpm --parallel --filter '@adobe/data-*' --filter '!@adobe/data' run typecheck",
-    "typecheck:samples": "pnpm --parallel --filter data-lit-todo --filter data-react-hello --filter data-react-pixie --filter data-lit-tictactoe --filter data-p2p-tictactoe --filter data-solid-dashboard --filter data-gpu-samples run typecheck",
+    "typecheck": "pnpm -r run typecheck",
+    "check:workspace": "node scripts/check-workspace-conventions.mjs",
     "dev": "pnpm -r --parallel run dev",
     "dev:data": "pnpm --filter @adobe/data run dev",
     "dev-gpu": "pnpm --parallel --filter @adobe/data --filter @adobe/data-gpu --filter data-gpu-samples run dev",
     "link": "pnpm -r --filter @adobe/data* run link",
-    "publish": "sh -c 'for x in \"$@\"; do OTP=\"$x\"; done; export NPM_CONFIG_OTP=\"$OTP\"; pnpm -r --filter @adobe/data --filter @adobe/data-ai --filter @adobe/data-react --filter @adobe/data-lit --filter @adobe/data-solid --filter @adobe/data-gpu run publish-public' sh",
+    "publish": "sh -c 'for x in \"$@\"; do OTP=\"$x\"; done; export NPM_CONFIG_OTP=\"$OTP\"; pnpm -r run build && pnpm -r publish --no-git-checks --access public' sh",
     "bump": "pnpm version patch --no-git-tag-version && V=$(node -p \"require('$PWD/package.json').version\") && pnpm -r exec pnpm version $V --no-git-tag-version --allow-same-version && node -e \"const fs=require('fs');const p='packages/data-ai/.claude-plugin/plugin.json';const j=JSON.parse(fs.readFileSync(p,'utf8'));j.version=process.argv[1];fs.writeFileSync(p,JSON.stringify(j,null,2)+'\\n')\" $V",
     "release": "pnpm bump && pnpm publish",
     "bp": "pnpm bump && pnpm run publish"
diff --git a/packages/data-ai/package.json b/packages/data-ai/package.json
index 349289e4..7316f368 100644
--- a/packages/data-ai/package.json
+++ b/packages/data-ai/package.json
@@ -22,8 +22,7 @@
   "scripts": {
     "build": "cp ../../LICENSE .",
     "typecheck": "true",
-    "test": "vitest --run --passWithNoTests",
-    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public"
+    "test": "vitest --run --passWithNoTests"
   },
   "keywords": [
     "adobe",
diff --git a/packages/data-gpu-hopper/package.json b/packages/data-gpu-hopper/package.json
index f8c8b760..690c720f 100644
--- a/packages/data-gpu-hopper/package.json
+++ b/packages/data-gpu-hopper/package.json
@@ -11,8 +11,7 @@
     "build": "vite build",
     "dev": "vite",
     "test": "vitest --run --passWithNoTests",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "publish-public": "true"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@adobe/data": "workspace:*",
diff --git a/packages/data-gpu/package.json b/packages/data-gpu/package.json
index 6c3ee24e..78df48ea 100644
--- a/packages/data-gpu/package.json
+++ b/packages/data-gpu/package.json
@@ -12,7 +12,6 @@
     "build": "cp ../../LICENSE . && tsc -b",
     "dev": "tsc -b -w",
     "test": "vitest --run --passWithNoTests",
-    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public",
     "typecheck": "tsc -b"
   },
   "sideEffects": false,
diff --git a/packages/data-lit-space-rock-game/package.json b/packages/data-lit-space-rock-game/package.json
index 678e90a7..b8a03648 100644
--- a/packages/data-lit-space-rock-game/package.json
+++ b/packages/data-lit-space-rock-game/package.json
@@ -11,8 +11,7 @@
     "build": "vite build",
     "dev": "vite",
     "test": "vitest --run --passWithNoTests",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "publish-public": "true"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@adobe/data": "workspace:*",
diff --git a/packages/data-lit-tictactoe/package.json b/packages/data-lit-tictactoe/package.json
index 11e0f2ef..dbc1d78f 100644
--- a/packages/data-lit-tictactoe/package.json
+++ b/packages/data-lit-tictactoe/package.json
@@ -11,8 +11,7 @@
     "build": "vite build",
     "dev": "vite",
     "test": "vitest --run --passWithNoTests",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "publish-public": "true"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@adobe/data": "workspace:*",
diff --git a/packages/data-lit-todo/package.json b/packages/data-lit-todo/package.json
index 0a645ad4..2b445de0 100644
--- a/packages/data-lit-todo/package.json
+++ b/packages/data-lit-todo/package.json
@@ -11,8 +11,7 @@
     "build": "vite build",
     "dev": "vite",
     "test": "vitest --run --passWithNoTests",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "publish-public": "true"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@adobe/data": "workspace:*",
diff --git a/packages/data-lit/package.json b/packages/data-lit/package.json
index d6411415..7cc4bfae 100644
--- a/packages/data-lit/package.json
+++ b/packages/data-lit/package.json
@@ -16,7 +16,6 @@
     "dev": "tsc -b -w",
     "link": "pnpm build && pnpm link --global",
     "test": "vitest --run --passWithNoTests",
-    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public",
     "typecheck": "tsc -b"
   },
   "dependencies": {
diff --git a/packages/data-react-hello/package.json b/packages/data-react-hello/package.json
index 9a6157a5..dcdd01f7 100644
--- a/packages/data-react-hello/package.json
+++ b/packages/data-react-hello/package.json
@@ -7,8 +7,7 @@
   "scripts": {
     "build": "vite build",
     "dev": "vite",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "publish-public": "true"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@adobe/data": "workspace:*",
diff --git a/packages/data-react-pixie/package.json b/packages/data-react-pixie/package.json
index 45e54fc4..05607522 100644
--- a/packages/data-react-pixie/package.json
+++ b/packages/data-react-pixie/package.json
@@ -7,8 +7,7 @@
   "scripts": {
     "build": "vite build",
     "dev": "vite",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "publish-public": "true"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@adobe/data": "workspace:*",
diff --git a/packages/data-react/package.json b/packages/data-react/package.json
index eeef9606..3c7273a9 100644
--- a/packages/data-react/package.json
+++ b/packages/data-react/package.json
@@ -13,7 +13,6 @@
     "dev": "tsc -b -w",
     "link": "pnpm build && pnpm link --global",
     "test": "vitest --run --passWithNoTests",
-    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public",
     "typecheck": "tsc -b"
   },
   "dependencies": {
diff --git a/packages/data-solid-dashboard/package.json b/packages/data-solid-dashboard/package.json
index 89a03ddf..4057a037 100644
--- a/packages/data-solid-dashboard/package.json
+++ b/packages/data-solid-dashboard/package.json
@@ -7,8 +7,7 @@
   "scripts": {
     "build": "vite build",
     "dev": "vite",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "publish-public": "true"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "@adobe/data": "workspace:*",
diff --git a/packages/data-solid/package.json b/packages/data-solid/package.json
index ad39b29b..a9be58ad 100644
--- a/packages/data-solid/package.json
+++ b/packages/data-solid/package.json
@@ -13,7 +13,6 @@
     "dev": "tsc -b -w",
     "link": "pnpm build && pnpm link --global",
     "test": "vitest --run --passWithNoTests",
-    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public",
     "typecheck": "tsc -b"
   },
   "dependencies": {
diff --git a/packages/data/package.json b/packages/data/package.json
index f3e9fb49..54be5d24 100644
--- a/packages/data/package.json
+++ b/packages/data/package.json
@@ -36,11 +36,10 @@
     "link": "pnpm build && pnpm link --global",
     "pre-commit": "lint-staged",
     "prepublishOnly": "node scripts/copy-references.js",
-    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public",
     "perftest": "node dist/perftest/index.js",
     "check:emit": "node scripts/emit-stripinternal/check.mjs",
-    "test": "vitest --run",
-    "test:ci": "SKIP_PERF=1 vitest --run",
+    "test": "SKIP_PERF=1 vitest --run",
+    "test:perf": "vitest --run",
     "asbuild:debug": "asc assembly/index.ts -o dist/assembly/index.wasm --target debug --enable simd && echo built dist/assembly/index.wasm",
     "asbuild:release": "asc assembly/index.ts -o dist/assembly/index.wasm --target release --enable simd --optimize && echo built dist/assembly/index.wasm",
     "start": "npx serve ."
diff --git a/scripts/check-workspace-conventions.mjs b/scripts/check-workspace-conventions.mjs
new file mode 100644
index 00000000..211caa93
--- /dev/null
+++ b/scripts/check-workspace-conventions.mjs
@@ -0,0 +1,44 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Enforces the workspace script conventions so the build/test/publish pipeline
+// never forks on package identity. Root and CI invoke uniform recursive scripts
+// (`pnpm -r run <script>`); each package owns HOW it builds/tests/publishes.
+// This guard keeps every package honest so a new package "just works" without
+// editing any central list.
+//
+// Rules:
+//   1. Every package declares `private` explicitly (true|false). npm treats an
+//      absent `private` as publishable, so we require an explicit decision —
+//      absent must never silently mean "publish".
+//   2. Publishing is governed solely by `private` + `pnpm -r publish`. A
+//      per-package `publish-public` script would reintroduce identity-specific
+//      publish logic, so it is forbidden.
+
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const packagesDir = join(root, "packages");
+
+const errors = [];
+for (const name of readdirSync(packagesDir)) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(join(packagesDir, name, "package.json"), "utf8"));
+  } catch {
+    continue; // not a package directory
+  }
+  if (typeof pkg.private !== "boolean") {
+    errors.push(`${name}: must set "private": true or false explicitly (absent must not mean publishable)`);
+  }
+  if (pkg.scripts?.["publish-public"]) {
+    errors.push(`${name}: remove the "publish-public" script — publishing is governed by the "private" field and \`pnpm -r publish\``);
+  }
+}
+
+if (errors.length > 0) {
+  console.error("Workspace convention violations:\n  " + errors.join("\n  "));
+  process.exit(1);
+}
+console.log("workspace conventions OK");