From 0261dd930a31a076e4c3015707af23e48514127b Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 31 Jul 2026 12:26:15 +0800 Subject: [PATCH] chore(packaging): CHANGELOG.md ships in every npm tarball (#4261) AGENTS.md's post-task checklist requires breaking changesets to carry their FROM -> TO migration because "this text ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error." That delivery path was severed for 68 of the 69 publishable packages: npm packs package.json / README* / LICENSE* unconditionally but -- unlike older npm versions -- not CHANGELOG.md, and the canonical ["dist", "README.md"] whitelist never named it. Measured on npm 10.9.7: npm pack --dry-run on @objectstack/types shipped 3 files while its 70KB CHANGELOG.md stayed behind. Only @objectstack/spec listed it explicitly. The tombstone scenario is precisely the one where the repo is out of reach -- the upgrading agent has node_modules and nothing else -- so the migration text has to ride in the tarball (#4261's direction 1: make the convention true rather than rewrite it). Every publishable package now declares CHANGELOG.md in `files`, and check:published-files gains a fifth invariant, COMPLETE: a whitelist that fails to cover CHANGELOG.md fails the always-required lint job, so the next package cannot silently sever the path again. CHANGELOG.md joins the canonical set (["dist", "README.md", "CHANGELOG.md"]), which dissolves @objectstack/spec's per-package EXTRA_ENTRIES exemption for it. Verified: --self-test (21 pattern + 11 classification cases, three new pinning the shapes COMPLETE resolves through); the full check green over 69 packages; removing the entry from one package fails the gate with the #4261 story and the one-line fix; npm pack --dry-run on @objectstack/types now lists the 70.8KB CHANGELOG.md. Closes #4261. Co-Authored-By: Claude Fable 5 --- .changeset/changelog-ships-in-tarball.md | 100 ++++++++++++++++++ packages/adapters/hono/package.json | 3 +- packages/apps/account/package.json | 3 +- packages/apps/setup/package.json | 3 +- packages/apps/studio/package.json | 3 +- packages/cli/package.json | 3 +- packages/client-react/package.json | 3 +- packages/client/package.json | 3 +- packages/cloud-connection/package.json | 3 +- .../connectors/connector-mcp/package.json | 3 +- .../connectors/connector-openapi/package.json | 3 +- .../connectors/connector-rest/package.json | 3 +- .../connectors/connector-slack/package.json | 3 +- packages/console/package.json | 3 +- packages/core/package.json | 3 +- packages/create-objectstack/package.json | 3 +- packages/formula/package.json | 3 +- packages/lint/package.json | 3 +- packages/mcp/package.json | 3 +- packages/metadata-core/package.json | 3 +- packages/metadata-fs/package.json | 3 +- packages/metadata-protocol/package.json | 3 +- packages/metadata/package.json | 3 +- packages/objectql/package.json | 3 +- packages/observability/package.json | 3 +- packages/platform-objects/package.json | 3 +- packages/plugins/driver-memory/package.json | 3 +- packages/plugins/driver-mongodb/package.json | 3 +- packages/plugins/driver-sql/package.json | 3 +- .../plugins/driver-sqlite-wasm/package.json | 3 +- packages/plugins/embedder-openai/package.json | 3 +- .../plugins/knowledge-memory/package.json | 3 +- .../plugins/knowledge-ragflow/package.json | 3 +- .../plugins/plugin-approvals/package.json | 3 +- packages/plugins/plugin-audit/package.json | 3 +- packages/plugins/plugin-auth/package.json | 3 +- packages/plugins/plugin-dev/package.json | 3 +- packages/plugins/plugin-email/package.json | 3 +- .../plugins/plugin-hono-server/package.json | 3 +- .../plugins/plugin-pinyin-search/package.json | 3 +- packages/plugins/plugin-reports/package.json | 3 +- packages/plugins/plugin-security/package.json | 3 +- packages/plugins/plugin-sharing/package.json | 3 +- packages/plugins/plugin-webhooks/package.json | 3 +- packages/rest/package.json | 3 +- packages/runtime/package.json | 3 +- packages/sdui-parser/package.json | 3 +- .../services/service-analytics/package.json | 3 +- .../services/service-automation/package.json | 3 +- packages/services/service-cache/package.json | 3 +- .../service-cluster-redis/package.json | 3 +- .../services/service-cluster/package.json | 3 +- .../services/service-datasource/package.json | 3 +- packages/services/service-i18n/package.json | 3 +- packages/services/service-job/package.json | 3 +- .../services/service-knowledge/package.json | 3 +- .../services/service-messaging/package.json | 3 +- .../services/service-package/package.json | 3 +- packages/services/service-queue/package.json | 3 +- .../services/service-realtime/package.json | 3 +- .../services/service-settings/package.json | 3 +- packages/services/service-sms/package.json | 3 +- .../services/service-storage/package.json | 3 +- packages/triggers/trigger-api/package.json | 3 +- .../trigger-record-change/package.json | 3 +- .../triggers/trigger-schedule/package.json | 3 +- packages/types/package.json | 3 +- packages/verify/package.json | 3 +- packages/vscode-objectstack/package.json | 3 +- scripts/check-published-files.mjs | 67 +++++++++--- 70 files changed, 287 insertions(+), 84 deletions(-) create mode 100644 .changeset/changelog-ships-in-tarball.md diff --git a/.changeset/changelog-ships-in-tarball.md b/.changeset/changelog-ships-in-tarball.md new file mode 100644 index 0000000000..ab24ca87a5 --- /dev/null +++ b/.changeset/changelog-ships-in-tarball.md @@ -0,0 +1,100 @@ +--- +"@objectstack/account": patch +"@objectstack/cli": patch +"@objectstack/client": patch +"@objectstack/client-react": patch +"@objectstack/cloud-connection": patch +"@objectstack/connector-mcp": patch +"@objectstack/connector-openapi": patch +"@objectstack/connector-rest": patch +"@objectstack/connector-slack": patch +"@objectstack/console": patch +"@objectstack/core": patch +"@objectstack/driver-memory": patch +"@objectstack/driver-mongodb": patch +"@objectstack/driver-sql": patch +"@objectstack/driver-sqlite-wasm": patch +"@objectstack/embedder-openai": patch +"@objectstack/formula": patch +"@objectstack/hono": patch +"@objectstack/knowledge-memory": patch +"@objectstack/knowledge-ragflow": patch +"@objectstack/lint": patch +"@objectstack/mcp": patch +"@objectstack/metadata": patch +"@objectstack/metadata-core": patch +"@objectstack/metadata-fs": patch +"@objectstack/metadata-protocol": patch +"@objectstack/objectql": patch +"@objectstack/observability": patch +"@objectstack/platform-objects": patch +"@objectstack/plugin-approvals": patch +"@objectstack/plugin-audit": patch +"@objectstack/plugin-auth": patch +"@objectstack/plugin-dev": patch +"@objectstack/plugin-email": patch +"@objectstack/plugin-hono-server": patch +"@objectstack/plugin-pinyin-search": patch +"@objectstack/plugin-reports": patch +"@objectstack/plugin-security": patch +"@objectstack/plugin-sharing": patch +"@objectstack/plugin-webhooks": patch +"@objectstack/rest": patch +"@objectstack/runtime": patch +"@objectstack/sdui-parser": patch +"@objectstack/service-analytics": patch +"@objectstack/service-automation": patch +"@objectstack/service-cache": patch +"@objectstack/service-cluster": patch +"@objectstack/service-cluster-redis": patch +"@objectstack/service-datasource": patch +"@objectstack/service-i18n": patch +"@objectstack/service-job": patch +"@objectstack/service-knowledge": patch +"@objectstack/service-messaging": patch +"@objectstack/service-package": patch +"@objectstack/service-queue": patch +"@objectstack/service-realtime": patch +"@objectstack/service-settings": patch +"@objectstack/service-sms": patch +"@objectstack/service-storage": patch +"@objectstack/setup": patch +"@objectstack/studio": patch +"@objectstack/trigger-api": patch +"@objectstack/trigger-record-change": patch +"@objectstack/trigger-schedule": patch +"@objectstack/types": patch +"@objectstack/verify": patch +"create-objectstack": patch +"objectstack-vscode": patch +--- + +chore(packaging): CHANGELOG.md ships in every npm tarball (#4261) + +The AGENTS.md post-task checklist requires breaking changesets to carry their +FROM → TO migration because "this text ships to consumers as `CHANGELOG.md` +inside the npm package and is what an upgrading agent greps after the tombstone +error." That delivery path was severed for 68 of the 69 publishable packages: +npm packs `package.json` / `README*` / `LICENSE*` unconditionally but — unlike +older npm versions — not `CHANGELOG.md`, and the canonical +`"files": ["dist", "README.md"]` whitelist never named it. Measured on npm +10.9.7: `npm pack --dry-run` on `@objectstack/types` shipped 3 files while its +70KB `CHANGELOG.md` stayed behind. Only `@objectstack/spec` listed it +explicitly. + +The tombstone-error scenario is precisely the one where the repo is out of +reach — the upgrading agent has `node_modules` and nothing else — so the +migration text has to ride in the tarball. Every publishable package now +declares `CHANGELOG.md` in `files`, and the canonical whitelist is +`["dist", "README.md", "CHANGELOG.md"]`. + +The other half is the gate: `check:published-files` gains a fifth invariant, +COMPLETE — a whitelist that fails to cover `CHANGELOG.md` fails the +always-required lint job, so the next package cannot silently sever the path +again. `@objectstack/spec`'s per-package EXTRA_ENTRIES exemption dissolves +into the canonical set. + +Consumer-visible change: one more file per install (the package's changelog, +e.g. 70.8KB for `@objectstack/types`), and `grep -r "removed key" +node_modules/@objectstack/*/CHANGELOG.md` now finds the migration it was +promised. diff --git a/packages/adapters/hono/package.json b/packages/adapters/hono/package.json index 0150ebf950..f1e2d32ddb 100644 --- a/packages/adapters/hono/package.json +++ b/packages/adapters/hono/package.json @@ -51,7 +51,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/apps/account/package.json b/packages/apps/account/package.json index a1f7ddb83a..a3d21658ea 100644 --- a/packages/apps/account/package.json +++ b/packages/apps/account/package.json @@ -43,7 +43,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/apps/setup/package.json b/packages/apps/setup/package.json index 731b6d8b86..d883b7c3b9 100644 --- a/packages/apps/setup/package.json +++ b/packages/apps/setup/package.json @@ -43,7 +43,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/apps/studio/package.json b/packages/apps/studio/package.json index eb713903cd..2404c711e4 100644 --- a/packages/apps/studio/package.json +++ b/packages/apps/studio/package.json @@ -43,7 +43,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/cli/package.json b/packages/cli/package.json index 2a08e3ca01..7675ceaf00 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -124,7 +124,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/client-react/package.json b/packages/client-react/package.json index 367486bf24..407147c97c 100644 --- a/packages/client-react/package.json +++ b/packages/client-react/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/client/package.json b/packages/client/package.json index 3593ab06cb..095bfd6305 100644 --- a/packages/client/package.json +++ b/packages/client/package.json @@ -51,7 +51,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/cloud-connection/package.json b/packages/cloud-connection/package.json index 70fad731d4..f3eaffd547 100644 --- a/packages/cloud-connection/package.json +++ b/packages/cloud-connection/package.json @@ -49,7 +49,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/connectors/connector-mcp/package.json b/packages/connectors/connector-mcp/package.json index eca5ad311a..0787ce7cdf 100644 --- a/packages/connectors/connector-mcp/package.json +++ b/packages/connectors/connector-mcp/package.json @@ -38,6 +38,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/connectors/connector-openapi/package.json b/packages/connectors/connector-openapi/package.json index 5c22dc88cb..73fa332edb 100644 --- a/packages/connectors/connector-openapi/package.json +++ b/packages/connectors/connector-openapi/package.json @@ -36,6 +36,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/connectors/connector-rest/package.json b/packages/connectors/connector-rest/package.json index b1573c4478..02ca8059d1 100644 --- a/packages/connectors/connector-rest/package.json +++ b/packages/connectors/connector-rest/package.json @@ -35,6 +35,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/connectors/connector-slack/package.json b/packages/connectors/connector-slack/package.json index ce85c27376..47752f801a 100644 --- a/packages/connectors/connector-slack/package.json +++ b/packages/connectors/connector-slack/package.json @@ -35,6 +35,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/console/package.json b/packages/console/package.json index 333592af68..e6c686fd48 100644 --- a/packages/console/package.json +++ b/packages/console/package.json @@ -17,7 +17,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "exports": { "./package.json": "./package.json" diff --git a/packages/core/package.json b/packages/core/package.json index d565ddb9ee..18bc4b06a5 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -54,7 +54,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/create-objectstack/package.json b/packages/create-objectstack/package.json index 77ec11052e..8cb7eeac16 100644 --- a/packages/create-objectstack/package.json +++ b/packages/create-objectstack/package.json @@ -42,7 +42,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/formula/package.json b/packages/formula/package.json index ead917cb6b..78cb50a4f4 100644 --- a/packages/formula/package.json +++ b/packages/formula/package.json @@ -44,6 +44,7 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/lint/package.json b/packages/lint/package.json index d960959d6b..48e967f4e4 100644 --- a/packages/lint/package.json +++ b/packages/lint/package.json @@ -50,7 +50,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/mcp/package.json b/packages/mcp/package.json index ce0a83c615..772047cd2e 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -51,7 +51,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/metadata-core/package.json b/packages/metadata-core/package.json index 8024cfb9f6..5181fe3dfd 100644 --- a/packages/metadata-core/package.json +++ b/packages/metadata-core/package.json @@ -20,7 +20,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "scripts": { "build": "tsup", diff --git a/packages/metadata-fs/package.json b/packages/metadata-fs/package.json index 45ed65d848..b2a86dd6b1 100644 --- a/packages/metadata-fs/package.json +++ b/packages/metadata-fs/package.json @@ -15,7 +15,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "scripts": { "build": "tsup", diff --git a/packages/metadata-protocol/package.json b/packages/metadata-protocol/package.json index d85aec4acf..144a1d19cb 100644 --- a/packages/metadata-protocol/package.json +++ b/packages/metadata-protocol/package.json @@ -15,7 +15,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "scripts": { "build": "tsup", diff --git a/packages/metadata/package.json b/packages/metadata/package.json index 882efe6ec5..5f1c3d1b0b 100644 --- a/packages/metadata/package.json +++ b/packages/metadata/package.json @@ -25,7 +25,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "scripts": { "build": "tsup", diff --git a/packages/objectql/package.json b/packages/objectql/package.json index 24c591a9ee..101e9b9769 100644 --- a/packages/objectql/package.json +++ b/packages/objectql/package.json @@ -55,7 +55,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/observability/package.json b/packages/observability/package.json index 3f0435e626..c518905e29 100644 --- a/packages/observability/package.json +++ b/packages/observability/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/platform-objects/package.json b/packages/platform-objects/package.json index 603248a27c..9c5189dec8 100644 --- a/packages/platform-objects/package.json +++ b/packages/platform-objects/package.json @@ -97,7 +97,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/driver-memory/package.json b/packages/plugins/driver-memory/package.json index 1786ea7ff0..f330baaf53 100644 --- a/packages/plugins/driver-memory/package.json +++ b/packages/plugins/driver-memory/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/driver-mongodb/package.json b/packages/plugins/driver-mongodb/package.json index e60354acde..3f8b2ccbc7 100644 --- a/packages/plugins/driver-mongodb/package.json +++ b/packages/plugins/driver-mongodb/package.json @@ -50,7 +50,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/driver-sql/package.json b/packages/plugins/driver-sql/package.json index 78c9f6c315..fac695d484 100644 --- a/packages/plugins/driver-sql/package.json +++ b/packages/plugins/driver-sql/package.json @@ -71,7 +71,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/driver-sqlite-wasm/package.json b/packages/plugins/driver-sqlite-wasm/package.json index b93b4f4ebb..308ce7d0a0 100644 --- a/packages/plugins/driver-sqlite-wasm/package.json +++ b/packages/plugins/driver-sqlite-wasm/package.json @@ -54,7 +54,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/embedder-openai/package.json b/packages/plugins/embedder-openai/package.json index 0240dfc9d6..ed8f935f69 100644 --- a/packages/plugins/embedder-openai/package.json +++ b/packages/plugins/embedder-openai/package.json @@ -39,6 +39,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/plugins/knowledge-memory/package.json b/packages/plugins/knowledge-memory/package.json index 203335153d..535b1c8439 100644 --- a/packages/plugins/knowledge-memory/package.json +++ b/packages/plugins/knowledge-memory/package.json @@ -36,6 +36,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/plugins/knowledge-ragflow/package.json b/packages/plugins/knowledge-ragflow/package.json index 6d262e0114..9399103b00 100644 --- a/packages/plugins/knowledge-ragflow/package.json +++ b/packages/plugins/knowledge-ragflow/package.json @@ -35,6 +35,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/plugins/plugin-approvals/package.json b/packages/plugins/plugin-approvals/package.json index b7fb867a73..f0986ed205 100644 --- a/packages/plugins/plugin-approvals/package.json +++ b/packages/plugins/plugin-approvals/package.json @@ -40,6 +40,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/plugins/plugin-audit/package.json b/packages/plugins/plugin-audit/package.json index 8c3e30bc27..c4c1431e49 100644 --- a/packages/plugins/plugin-audit/package.json +++ b/packages/plugins/plugin-audit/package.json @@ -46,7 +46,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/plugin-auth/package.json b/packages/plugins/plugin-auth/package.json index b68552ee00..593e463a8f 100644 --- a/packages/plugins/plugin-auth/package.json +++ b/packages/plugins/plugin-auth/package.json @@ -57,7 +57,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/plugin-dev/package.json b/packages/plugins/plugin-dev/package.json index 9d4ae06ad9..94810d0e1f 100644 --- a/packages/plugins/plugin-dev/package.json +++ b/packages/plugins/plugin-dev/package.json @@ -58,7 +58,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/plugin-email/package.json b/packages/plugins/plugin-email/package.json index 993db5286a..dd30a0f7a7 100644 --- a/packages/plugins/plugin-email/package.json +++ b/packages/plugins/plugin-email/package.json @@ -35,6 +35,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/plugins/plugin-hono-server/package.json b/packages/plugins/plugin-hono-server/package.json index f2231b1f93..70c807d604 100644 --- a/packages/plugins/plugin-hono-server/package.json +++ b/packages/plugins/plugin-hono-server/package.json @@ -42,7 +42,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/plugin-pinyin-search/package.json b/packages/plugins/plugin-pinyin-search/package.json index 1254d711f9..918b6a3042 100644 --- a/packages/plugins/plugin-pinyin-search/package.json +++ b/packages/plugins/plugin-pinyin-search/package.json @@ -36,6 +36,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/plugins/plugin-reports/package.json b/packages/plugins/plugin-reports/package.json index 409e55677a..36177693b7 100644 --- a/packages/plugins/plugin-reports/package.json +++ b/packages/plugins/plugin-reports/package.json @@ -36,6 +36,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/plugins/plugin-security/package.json b/packages/plugins/plugin-security/package.json index 20b5089b1b..43509bf6cf 100644 --- a/packages/plugins/plugin-security/package.json +++ b/packages/plugins/plugin-security/package.json @@ -48,7 +48,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/plugins/plugin-sharing/package.json b/packages/plugins/plugin-sharing/package.json index dea216d894..1198b63071 100644 --- a/packages/plugins/plugin-sharing/package.json +++ b/packages/plugins/plugin-sharing/package.json @@ -38,6 +38,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/plugins/plugin-webhooks/package.json b/packages/plugins/plugin-webhooks/package.json index c4ff682d8d..6337cc14d8 100644 --- a/packages/plugins/plugin-webhooks/package.json +++ b/packages/plugins/plugin-webhooks/package.json @@ -47,6 +47,7 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/rest/package.json b/packages/rest/package.json index 9100b10546..11b5bdb3a2 100644 --- a/packages/rest/package.json +++ b/packages/rest/package.json @@ -55,7 +55,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/runtime/package.json b/packages/runtime/package.json index cc2e39d3ae..42ab1076ac 100644 --- a/packages/runtime/package.json +++ b/packages/runtime/package.json @@ -71,7 +71,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/sdui-parser/package.json b/packages/sdui-parser/package.json index 279d56a66f..5ba9319d3e 100644 --- a/packages/sdui-parser/package.json +++ b/packages/sdui-parser/package.json @@ -40,6 +40,7 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/services/service-analytics/package.json b/packages/services/service-analytics/package.json index 87bb7149dc..6204ea9a12 100644 --- a/packages/services/service-analytics/package.json +++ b/packages/services/service-analytics/package.json @@ -48,7 +48,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-automation/package.json b/packages/services/service-automation/package.json index 2238c19a55..8617c64986 100644 --- a/packages/services/service-automation/package.json +++ b/packages/services/service-automation/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-cache/package.json b/packages/services/service-cache/package.json index f7c1b0897d..80f201bbec 100644 --- a/packages/services/service-cache/package.json +++ b/packages/services/service-cache/package.json @@ -46,7 +46,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-cluster-redis/package.json b/packages/services/service-cluster-redis/package.json index 73ed070936..474679f263 100644 --- a/packages/services/service-cluster-redis/package.json +++ b/packages/services/service-cluster-redis/package.json @@ -44,6 +44,7 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/services/service-cluster/package.json b/packages/services/service-cluster/package.json index baf2036af8..a41e57aab0 100644 --- a/packages/services/service-cluster/package.json +++ b/packages/services/service-cluster/package.json @@ -47,6 +47,7 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/services/service-datasource/package.json b/packages/services/service-datasource/package.json index 08782ef72a..64360c5915 100644 --- a/packages/services/service-datasource/package.json +++ b/packages/services/service-datasource/package.json @@ -62,6 +62,7 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/services/service-i18n/package.json b/packages/services/service-i18n/package.json index 3796e7931f..963f4c66d1 100644 --- a/packages/services/service-i18n/package.json +++ b/packages/services/service-i18n/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-job/package.json b/packages/services/service-job/package.json index 8fb351b87f..2839c660b8 100644 --- a/packages/services/service-job/package.json +++ b/packages/services/service-job/package.json @@ -48,7 +48,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-knowledge/package.json b/packages/services/service-knowledge/package.json index 2b938d5ed8..5d904d148f 100644 --- a/packages/services/service-knowledge/package.json +++ b/packages/services/service-knowledge/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-messaging/package.json b/packages/services/service-messaging/package.json index c0feef5e50..23aaef503a 100644 --- a/packages/services/service-messaging/package.json +++ b/packages/services/service-messaging/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-package/package.json b/packages/services/service-package/package.json index 613fd5a1fa..1720ac4bb7 100644 --- a/packages/services/service-package/package.json +++ b/packages/services/service-package/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-queue/package.json b/packages/services/service-queue/package.json index f57d297f5e..eefaaa909e 100644 --- a/packages/services/service-queue/package.json +++ b/packages/services/service-queue/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-realtime/package.json b/packages/services/service-realtime/package.json index 7cb7b65c0a..e5dfbb4a1b 100644 --- a/packages/services/service-realtime/package.json +++ b/packages/services/service-realtime/package.json @@ -47,7 +47,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-settings/package.json b/packages/services/service-settings/package.json index 3f4f40d516..c5e42646a7 100644 --- a/packages/services/service-settings/package.json +++ b/packages/services/service-settings/package.json @@ -46,7 +46,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/services/service-sms/package.json b/packages/services/service-sms/package.json index 9df62f848b..52a62a00c1 100644 --- a/packages/services/service-sms/package.json +++ b/packages/services/service-sms/package.json @@ -34,6 +34,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/services/service-storage/package.json b/packages/services/service-storage/package.json index 099c6fda3e..ffd7b27d46 100644 --- a/packages/services/service-storage/package.json +++ b/packages/services/service-storage/package.json @@ -61,7 +61,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/triggers/trigger-api/package.json b/packages/triggers/trigger-api/package.json index cc7cfd5d4f..b72523bf54 100644 --- a/packages/triggers/trigger-api/package.json +++ b/packages/triggers/trigger-api/package.json @@ -33,6 +33,7 @@ ], "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/packages/triggers/trigger-record-change/package.json b/packages/triggers/trigger-record-change/package.json index cbe317c688..ed973daa0c 100644 --- a/packages/triggers/trigger-record-change/package.json +++ b/packages/triggers/trigger-record-change/package.json @@ -48,7 +48,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/triggers/trigger-schedule/package.json b/packages/triggers/trigger-schedule/package.json index 122b7c2606..7bccaf44dd 100644 --- a/packages/triggers/trigger-schedule/package.json +++ b/packages/triggers/trigger-schedule/package.json @@ -48,7 +48,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/types/package.json b/packages/types/package.json index eaf148b248..5209a778f6 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -42,7 +42,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/verify/package.json b/packages/verify/package.json index cb8a987774..6f44df9025 100644 --- a/packages/verify/package.json +++ b/packages/verify/package.json @@ -60,7 +60,8 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ], "engines": { "node": ">=22.0.0" diff --git a/packages/vscode-objectstack/package.json b/packages/vscode-objectstack/package.json index 6eb35662e7..6928651159 100644 --- a/packages/vscode-objectstack/package.json +++ b/packages/vscode-objectstack/package.json @@ -78,6 +78,7 @@ }, "files": [ "dist", - "README.md" + "README.md", + "CHANGELOG.md" ] } diff --git a/scripts/check-published-files.mjs b/scripts/check-published-files.mjs index a9a4ad41b1..900b72f2aa 100644 --- a/scripts/check-published-files.mjs +++ b/scripts/check-published-files.mjs @@ -27,18 +27,26 @@ // node scripts/check-published-files.mjs // node scripts/check-published-files.mjs --self-test // -// Four invariants, per non-private workspace package: +// Five invariants, per non-private workspace package: // // DECLARED `files` exists and is a non-empty array of strings. +// COMPLETE the whitelist covers `CHANGELOG.md` (#4261). AGENTS.md requires +// breaking changesets to carry their FROM -> TO migration because +// that text ships to consumers inside the npm package and is what +// an upgrading agent greps after a tombstone error -- but npm does +// not pack CHANGELOG.md unconditionally, so a whitelist that +// omits it silently severs that delivery path. 68 of 69 packages +// had it severed when #4261 measured. // SUFFICIENT every path the manifest points at (types, module, exports // subpaths) is covered by it. A whitelist that omits a real entry // point ships a package that cannot resolve -- the opposite // failure, and one this guard would otherwise encourage. // MINIMAL nothing the whitelist admits is a test, a test-harness config // or build-time tooling. -// REGISTERED any entry beyond `dist` / `README.md` carries a reason in -// EXTRA_ENTRIES, reconciled in BOTH directions so a stale -// exemption is an error rather than dead text. +// REGISTERED any entry beyond the canonical `dist` / `README.md` / +// `CHANGELOG.md` carries a reason in EXTRA_ENTRIES, reconciled in +// BOTH directions so a stale exemption is an error rather than +// dead text. // // Deliberately NOT checked: the contents of dist/. It does not exist in a fresh // checkout and the lint job does not build, so reading it would make the @@ -55,9 +63,18 @@ const ROOT = resolve(import.meta.dirname, '..'); const WORKSPACE_FILE = 'pnpm-workspace.yaml'; const SELF = 'scripts/check-published-files.mjs'; -// Entries every package may declare without justifying itself: the build output -// and the readme. Anything else is a deliberate decision and needs a reason. -const CANONICAL = new Set(['dist', 'README.md']); +// Entries every package may declare without justifying itself: the build +// output, the readme and the changelog. Anything else is a deliberate decision +// and needs a reason. +const CANONICAL = new Set(['dist', 'README.md', 'CHANGELOG.md']); + +// Entries every package MUST cover, not merely may declare. CHANGELOG.md is the +// delivery path the AGENTS.md post-task checklist promises: breaking changesets +// write their FROM -> TO migration there, and an upgrading agent with only +// node_modules on disk -- the tombstone-error scenario -- can grep nothing +// else. npm stopped packing CHANGELOG unconditionally (see ALWAYS_PACKED), so +// only an explicit `files` entry keeps that promise true (#4261). +const REQUIRED = ['CHANGELOG.md']; // Package name -> { files entry -> why it is published }. Reconciled against // the manifests on every run: an entry here for a pattern no longer declared is @@ -72,8 +89,6 @@ const EXTRA_ENTRIES = { 'llms.txt': 'Protocol summary for LLM consumers.', 'src/**/*.zod.ts': 'The Zod schemas are themselves the contract (Prime Directive #1); downstream code imports them directly, so these sources are product rather than build input. Narrowed to *.zod.ts so no test or helper rides along.', - 'CHANGELOG.md': - 'Breaking changesets carry their FROM -> TO migration here, which is what an upgrading agent greps after hitting a tombstone error (AGENTS.md post-task checklist).', 'api-surface.json': 'Export snapshot used by downstream compatibility checks.', 'spec-changes.json': 'Machine-readable spec change log driving the upgrade guide.', }, @@ -110,8 +125,9 @@ const FORBIDDEN = [ // them would flag packages that work. Measured on npm 10.9.7: packing // @objectstack/types with `["dist","README.md"]` yielded LICENSE, README.md and // package.json, and @objectstack/cli's `bin/run.js` shipped although `files` -// never names bin/. CHANGELOG.md is deliberately absent from this set -- npm -// does not pack it, which is why @objectstack/spec has to list it explicitly. +// never names bin/. CHANGELOG.md is deliberately absent from this set -- older +// npm packed it unconditionally, current npm does not -- which is exactly why +// COMPLETE demands an explicit `files` entry for it (#4261). const ALWAYS_PACKED = [ /^package\.json$/, /^readme(\.[^/]+)?$/i, @@ -242,6 +258,12 @@ function selfTest() { ['dist', 'src/index.ts', false], ['README.md', 'README.md', true], ['README.md', 'docs/README.md', false], + // The COMPLETE invariant resolves through this same matcher, so the exact + // shapes it depends on are pinned: the literal entry, a directory that + // must NOT swallow it, and the near-miss name. + ['CHANGELOG.md', 'CHANGELOG.md', true], + ['dist', 'CHANGELOG.md', false], + ['CHANGELOG.md', 'CHANGELOG.mdx', false], ['src/**/*.zod.ts', 'src/data/object.zod.ts', true], ['src/**/*.zod.ts', 'src/index.zod.ts', true], ['src/**/*.zod.ts', 'src/data/object.test.ts', false], @@ -327,7 +349,7 @@ for (const dir of workspaceDirs()) { 'declares no `files` field, so npm packs the whole directory -- src/,', 'unit tests and build tooling included, with dist/ added on top rather', 'than instead of them.', - 'Fix: add "files": ["dist", "README.md"] to its package.json.', + 'Fix: add "files": ["dist", "README.md", "CHANGELOG.md"] to its package.json.', ], }); continue; @@ -354,6 +376,17 @@ for (const dir of workspaceDirs()) { const matchers = files.map((f) => ({ pattern: f, match: matcher(f) })); + // --- COMPLETE ------------------------------------------------------------ + for (const required of REQUIRED) { + if (matchers.some((m) => m.match(required))) continue; + lines.push( + `omits "${required}" from \`files\`, and npm does not pack it unconditionally, so the`, + 'migration text breaking changesets are required to carry (AGENTS.md post-task', + 'checklist) never reaches the consumer an upgrading agent greps for it (#4261).', + `Fix: add "${required}" to \`files\`.`, + ); + } + // --- REGISTERED ---------------------------------------------------------- const registered = EXTRA_ENTRIES[name] ?? {}; const declaredExtras = new Set(); @@ -446,7 +479,9 @@ if (problems.length > 0) { console.error( 'Without a `files` whitelist npm packs the whole package directory, so consumers\n' + 'install TypeScript sources, unit tests and build-time tooling alongside dist/.\n' + - 'The canonical whitelist is ["dist", "README.md"]; anything more needs a reason.', + 'The canonical whitelist is ["dist", "README.md", "CHANGELOG.md"]; anything more\n' + + 'needs a reason, and dropping CHANGELOG.md severs the migration-text delivery\n' + + 'path AGENTS.md promises (#4261).', ); process.exit(1); } @@ -454,7 +489,7 @@ if (problems.length > 0) { const withExtras = [...declaredExtrasByPackage.values()].filter((s) => s.size > 0).length; console.log( `✓ check:published-files — ${publishable} publishable package(s) of ${members} workspace ` + - 'member(s) declare a `files` whitelist that covers every entry point and admits no test, ' + - `test-harness config or build script; ${withExtras} publish more than dist/ + README.md, ` + - 'each with a registered reason.', + 'member(s) declare a `files` whitelist that covers every entry point plus CHANGELOG.md ' + + `and admits no test, test-harness config or build script; ${withExtras} publish more ` + + 'than dist/ + README.md + CHANGELOG.md, each with a registered reason.', );