chore(packaging): every published package declares a files whitelist (#4248) (#4262)

20 of the 49 publishable packages declared no `files` field, so npm fell back
to packing the whole package directory. `npm pack --dry-run` on
@objectstack/plugin-webhooks listed 21 files -- 15 under src/, three of them
unit tests, plus the build-time scripts/i18n-extract.config.ts. dist/ lands on
top of that at publish time rather than instead of it.

Each now declares ["dist", "README.md"], matching the 29 packages that already
did. Nothing a consumer imports moves: every main / types / exports target in
all 20 already resolved inside dist/.

The other half is the gate. check:published-files (wired into the
always-required lint job) holds every non-private workspace package to four
invariants: DECLARED, SUFFICIENT (covers every entry point, so tightening a
whitelist cannot ship a package that fails to resolve), MINIMAL (admits no
test, test-harness config or build script), and REGISTERED (anything beyond
dist + README.md carries a reason, reconciled in both directions).

MINIMAL also closes an assumption #4206 rested on: that no package publishes
scripts/ as runtime code held, but it held by hand-checking three packages.
It is now checked on every PR.

Author: os-zhuang

.changeset/published-files-whitelist.md

@@ -0,0 +1,57 @@
+---
+"@objectstack/formula": patch
+"@objectstack/sdui-parser": patch
+"@objectstack/connector-mcp": patch
+"@objectstack/connector-openapi": patch
+"@objectstack/connector-rest": patch
+"@objectstack/connector-slack": patch
+"@objectstack/embedder-openai": patch
+"@objectstack/knowledge-memory": patch
+"@objectstack/knowledge-ragflow": patch
+"@objectstack/plugin-approvals": patch
+"@objectstack/plugin-email": patch
+"@objectstack/plugin-pinyin-search": patch
+"@objectstack/plugin-reports": patch
+"@objectstack/plugin-sharing": patch
+"@objectstack/plugin-webhooks": patch
+"@objectstack/service-cluster": patch
+"@objectstack/service-cluster-redis": patch
+"@objectstack/service-datasource": patch
+"@objectstack/service-sms": patch
+"@objectstack/trigger-api": patch
+---
+
+chore(packaging): 20 packages stop publishing their sources, tests and build tooling (#4248)
+
+These 20 packages declared no `files` field, so npm fell back to packing the
+whole package directory. `npm pack --dry-run` on `@objectstack/plugin-webhooks`
+listed **21 files** — 15 under `src/`, three of them unit tests
+(`auto-enqueuer.test.ts`, `bootstrap-declared-webhooks.test.ts`, …), plus the
+build-time `scripts/i18n-extract.config.ts`. `dist/` lands on top of that at
+publish time rather than instead of it, so consumers were installing the
+TypeScript sources and the test suite alongside the artifact they asked for.
+
+Each now declares `"files": ["dist", "README.md"]`, matching the 29 packages
+that already did. Nothing a consumer imports moves: every `main` / `types` /
+`exports` target in all 20 already resolved inside `dist/`, which the new
+`check:published-files` guard verifies rather than assumes. The visible change
+is a smaller install and a smaller dependency-scanning surface — `npm pack` on
+`@objectstack/plugin-webhooks` now yields 2 files plus `dist/`.
+
+The other half of the fix is the gate. Half the packages declaring `files` and
+half not was the #3786 shape — a hand-copied convention with nothing enforcing
+it, where whoever forgets the line gets no signal at all. `check:published-files`
+(new, wired into the always-required `lint` job) holds every non-private
+workspace package to four invariants: `files` is **declared**; it is
+**sufficient** (covers every entry point, so tightening a whitelist cannot ship
+a package that fails to resolve); it is **minimal** (admits no test, test-harness
+config or build script); and anything beyond `dist` + `README.md` is
+**registered** with a reason, reconciled in both directions so a stale exemption
+is an error rather than dead text. `@objectstack/spec` is the one package with
+registered extras — its `.zod.ts` sources, JSON Schemas, liveness ledgers and
+`CHANGELOG.md` are product, not build input.
+
+This also closes an assumption #4206 was resting on. Excluding `<pkg>/scripts/**`
+from the docs-drift implementation test is sound only while no package publishes
+`scripts/` as runtime code; that held, but it held because someone read all three
+offenders by hand. It is now checked on every PR.

.github/workflows/lint.yml

@@ -166,6 +166,22 @@ jobs:
       - name: Node-version drift guard
         run: pnpm check:node-version
 
+      # #4248 packaging-hygiene guard. Without a `files` whitelist npm packs the
+      # whole package directory, and 20 of the 49 publishable packages declared
+      # none — so consumers installed TypeScript sources, unit tests and build
+      # tooling, with dist/ landing on top of them rather than instead of them
+      # (@objectstack/plugin-webhooks: 21 files, three of them unit tests). The
+      # other 29 did declare it, so this was a hand-copied line with no gate —
+      # the #3786 shape, where whoever forgets it gets no signal at all. Also
+      # checks the whitelist is SUFFICIENT (covers every entry point, so
+      # tightening one cannot ship a package that fails to resolve) and MINIMAL
+      # (admits no test or build script), which keeps #4206's "`<pkg>/scripts/**`
+      # is never runtime code" assumption continuously verified instead of
+      # hand-checked. Runs its own --self-test first: the pattern semantics can
+      # be wrong while every package is right.
+      - name: Published-files whitelist guard
+        run: pnpm check:published-files
+
   typecheck:
     name: TypeScript Type Check
     runs-on: ubuntu-latest

package.json

@@ -40,7 +40,8 @@
     "check:wildcard-fallthrough": "node scripts/check-wildcard-fallthrough.mjs --self-test && node scripts/check-wildcard-fallthrough.mjs",
     "check:console-sha": "node scripts/check-console-sha.mjs",
     "check:release-notes": "node scripts/check-release-notes.mjs",
-    "check:node-version": "node scripts/check-node-version.mjs"
+    "check:node-version": "node scripts/check-node-version.mjs",
+    "check:published-files": "node scripts/check-published-files.mjs --self-test && node scripts/check-published-files.mjs"
   },
   "keywords": [
     "objectstack",

packages/connectors/connector-mcp/package.json

@@ -35,5 +35,9 @@
     "integration",
     "ai",
     "tools"
+  ],
+  "files": [
+    "dist",
+    "README.md"
   ]
 }

packages/connectors/connector-openapi/package.json

@@ -33,5 +33,9 @@
         "swagger",
         "integration",
         "api"
-    ]
+    ],
+  "files": [
+    "dist",
+    "README.md"
+  ]
 }

packages/connectors/connector-rest/package.json

@@ -32,5 +32,9 @@
     "rest",
     "integration",
     "http"
+  ],
+  "files": [
+    "dist",
+    "README.md"
   ]
 }

packages/connectors/connector-slack/package.json

@@ -32,5 +32,9 @@
     "slack",
     "integration",
     "messaging"
+  ],
+  "files": [
+    "dist",
+    "README.md"
   ]
 }

packages/formula/package.json

@@ -41,5 +41,9 @@
   "bugs": "https://github.com/objectstack-ai/objectstack/issues",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
 }

packages/plugins/embedder-openai/package.json

@@ -36,5 +36,9 @@
     "zhipu",
     "siliconflow",
     "ollama"
+  ],
+  "files": [
+    "dist",
+    "README.md"
   ]
 }

packages/plugins/knowledge-memory/package.json

@@ -33,5 +33,9 @@
     "rag",
     "memory",
     "in-memory"
+  ],
+  "files": [
+    "dist",
+    "README.md"
   ]
 }