@happyvertical/smrt-core 0.57.20 → 0.57.21

package/agents/build-knowledge.md

@@ -94,6 +94,74 @@ so the artifact bundles them. SvelteKit
 virtual modules (`$env/*`, `$app/*`) are not available to a worker; an object
 importing one fails at worker startup. A failure fails the build.
 
+**Register imports stay Node-loadable (#4219).** `.smrt/register.js`
+(`generateRegistrationFile` in `src/consumer-plugin/index.ts`) is evaluated by
+plain Node — `smrt db:migrate`, every CLI, and the worker artifact above — as
+well as by Vite SSR, so it may only import modules Node can load. Each object
+is imported from its manifest `importPath` (the scanner's export-subpath match,
+e.g. `@happyvertical/smrt-products/models`). Each configured provider in
+`smrtDependencies` is also imported once so it is evaluated in Node's installed
+package context (#4187): the package root, unless the package declares that
+root as a Svelte entry (`isComponentBearingRoot`: a `svelte` field, or a `.`
+export with a `svelte` condition or a `.svelte`/`.css` target — e.g.
+`@happyvertical/smrt-products`, whose root re-exports its components and so
+reaches `@happyvertical/smrt-ui`'s `.svelte` files). Such a root is never
+imported and no subpath is substituted for it (`resolveProviderContextImport`
+returns `undefined`): its already-imported object entries establish the
+context, a provider contributing only nested objects needs none because the
+transitive loader uses only `import.meta.resolve(provider)`, and a substitute
+`./models` whose JS reached `.svelte` would re-create the failure. A package that publishes Svelte
+only under subpaths keeps its root import; the broader `isComponentBearingPackage`
+test (any Svelte export) only selects `ssr.noExternal` packages. A `svelte`
+condition counts even with a plain `.js` target — that is what svelte-package
+and Vite library builds emit for a root that re-exports components, and every
+Svelte root in this workspace (`smrt-products`, `smrt-ui`, `smrt-svelte`,
+`smrt-planner`) has that shape and fails under plain Node; a Node-safe root
+that declares `svelte` anyway only loses an optional context import.
+Transitive-only object modules are loaded through `importSmrtDependency()`
+from their provider's context, which needs no root import.
+
+Not covered by contract: a package whose root is a Svelte entry AND whose
+`@smrt()` objects are exported only from that root. The object loop must then
+import the root (it is the only module exporting the constructors) — statically
+when the app resolves the package, or through `importSmrtDependency()` when it
+is reached only through its provider — so Vite SSR works but plain Node can
+load the register only if that root happens to be Node-safe. Generation keeps
+the import and warns once per package (`declares a Svelte root entry`), asking
+to verify the root under plain Node or publish the objects from `./models` or
+`./objects`. The declaration is a heuristic: a Node-safe root that declares
+`svelte` only by convention gets the same warning (a false positive, harmless —
+the import is kept) and, when its objects come from subpaths, loses only its
+optional provider-context import. Regression: the `#4219` tests in
+`index.test.ts` (unit cases for `isComponentBearingRoot` /
+`resolveProviderContextImport`, a child-Node load of the generated register,
+the nested-only provider that gets no import, and the root-only and transitive
+warnings).
+
+**Gate: `pnpm check:node-roots`** (root script; run after `pnpm build`). It
+runs `scripts/survey-node-root-load.mjs --strict --allow=<packages>`, which
+spawns `node --input-type=module -e "await import('<name>')"` from every
+built workspace package whose manifest declares `@smrt()` objects and fails on
+any root plain Node cannot evaluate that is not allow-listed. The allow-list
+is explicit and lives in the root `package.json` script: currently only
+`@happyvertical/smrt-products`, whose root re-exports its Svelte components by
+documented contract. A new entry needs the same justification; a model root
+that merely starts importing `@happyvertical/smrt-ui` must be fixed, not
+allowed. `--strict` also fails when nothing was surveyed (run before
+`pnpm build`) and when an allow-listed package was not surveyed or now loads,
+so the list cannot go stale. `--all` surveys every published package,
+including those without objects, as a report.
+
+CI runs the gate in both Knowledge Freshness jobs of
+`.github/workflows/test-suite.yml`. In full mode (the merge queue, and every PR
+while `vars.CI_MERGE_QUEUE_ENABLED` is not `true`) it always runs. In affected
+mode it runs only when the `knowledge` paths filter matches, which covers
+`package.json` files and docs but not `packages/*/src/**`; a same-repo PR that
+makes a model root import smrt-ui only through source is therefore first
+caught in the merge queue, which still blocks the merge. The filter is not
+widened for this, because that would run the knowledge job on every PR. Run
+`pnpm check:node-roots` locally when changing a model package's root imports.
+
 ## Lightweight discovery
 
 Filesystem-only discovery, module-doc parsing, and graph freshness are owned by

package/dist/consumer-plugin/index.d.ts

@@ -6,6 +6,51 @@ import type { Plugin } from 'vite';
 import { type SmrtGenerationSnapshotOptions } from '../generation-snapshot.js';
 import { type SvelteKitOptions } from '../vite-plugin/sveltekit-generator.js';
 export { loadVerifiedSmrtGenerationSnapshot, type SerializeSmrtGenerationSnapshotOptions, type SmrtGenerationSnapshotArtifact, type SmrtGenerationSnapshotOptions, type SmrtGenerationSnapshotView, serializeSmrtGenerationSnapshot, sha256SmrtGenerationSnapshot, } from '../generation-snapshot.js';
+/**
+ * The package.json fields the Svelte-root rule reads. `exports` is `unknown`
+ * because npm allows a bare string target as well as a conditions map.
+ */
+interface ProviderPackageShape {
+    svelte?: unknown;
+    exports?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Whether the package declares its ROOT as a Svelte entry: a `svelte` field or
+ * a `.` export carrying a `svelte` condition (at any nesting) or a
+ * `.svelte`/`.css` target. Such a root (e.g. `@happyvertical/smrt-products`,
+ * which re-exports its components) cannot be evaluated by plain Node (#4219).
+ * A package that only publishes Svelte under a subpath keeps a Node-safe root,
+ * as the standards require.
+ *
+ * A `svelte` condition counts even when its target is plain `.js`: that is
+ * what svelte-package and Vite library builds emit for a root that re-exports
+ * components (the `.svelte` files sit one import deeper), and it is exactly
+ * the shape of every Svelte root in this workspace. Reading the condition as
+ * the package's declaration is deliberate — the trade-off is that a Node-safe
+ * root that nevertheless declares `svelte` loses its optional provider-context
+ * import, which costs nothing when its objects are imported from a subpath.
+ *
+ * A missing `exports` map, a `.` key absent from it, or an unreadable
+ * package.json (`undefined`) all answer `false`: the register then keeps the
+ * root import #4187 chose, as before.
+ *
+ * @internal Exported for tests.
+ */
+export declare function isComponentBearingRoot(packageJson: ProviderPackageShape | undefined): boolean;
+/**
+ * Pick the module the generated register imports so a configured provider is
+ * evaluated in Node's installed package context (#4187): the package root,
+ * unless the package declares that root as a Svelte entry, in which case
+ * nothing is imported for the provider (#4219). Its object entries, imported
+ * from their manifest `importPath`, already evaluate it in that context, and
+ * the transitive loader needs only `import.meta.resolve(provider)`, not an
+ * import. No substitute subpath is chosen: one that reaches `.svelte` would
+ * re-create the failure this avoids.
+ *
+ * @internal Exported for tests.
+ */
+export declare function resolveProviderContextImport(packageName: string, packageJson: ProviderPackageShape | undefined): string | undefined;
 /**
  * SvelteKit route-hosting options for dependency models. Unlike `packages`,
  * `objects` is an HTTP exposure boundary: every entry must be an exact,

package/dist/consumer-plugin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/consumer-plugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAa,MAAM,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,2BAA2B,CAAC;AAYnC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,uCAAuC,CAAC;AAqB/C,OAAO,EACL,kCAAkC,EAClC,KAAK,sCAAsC,EAC3C,KAAK,8BAA8B,EACnC,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AAsGnC;;;;GAIG;AACH,MAAM,WAAW,4BACf,SAAQ,OAAO,CACb,IAAI,CACF,gBAAgB,EACd,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,aAAa,GACb,gBAAgB,CACnB,CACF;IACD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,6BAA6B,CAAC;IACnD;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,4BAA4B,CAAC;IACnD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAmXD;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CA4lBtE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/consumer-plugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAa,MAAM,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,2BAA2B,CAAC;AAYnC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,uCAAuC,CAAC;AAqB/C,OAAO,EACL,kCAAkC,EAClC,KAAK,sCAAsC,EAC3C,KAAK,8BAA8B,EACnC,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AAiJnC;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,oBAAoB,GAAG,SAAS,GAC5C,OAAO,CAcT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,oBAAoB,GAAG,SAAS,GAC5C,MAAM,GAAG,SAAS,CAEpB;AAED;;;;GAIG;AACH,MAAM,WAAW,4BACf,SAAQ,OAAO,CACb,IAAI,CACF,gBAAgB,EACd,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,aAAa,GACb,gBAAgB,CACnB,CACF;IACD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,6BAA6B,CAAC;IACnD;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,4BAA4B,CAAC;IACnD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAmXD;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAykBtE"}

package/dist/consumer-plugin/index.js

@@ -36,6 +36,77 @@ function findInstalledPackageJson(packageName, searchFrom) {
 function sameInstalledPackage(left, right) {
 	return Boolean(left && right && fs$1.realpathSync(left) === fs$1.realpathSync(right));
 }
+function readInstalledPackageJson(packageJsonPath) {
+	if (!packageJsonPath) return void 0;
+	try {
+		return JSON.parse(fs$1.readFileSync(packageJsonPath, "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Whether an `exports` target (or any condition under it) needs Vite to
+* compile it: a `.svelte`/`.css` file or a `svelte` resolution condition.
+*/
+function exportTargetNeedsViteCompilation(value) {
+	if (typeof value === "string") return value.endsWith(".svelte") || value.endsWith(".css");
+	if (!value || typeof value !== "object") return false;
+	return Object.entries(value).some(([condition, target]) => condition === "svelte" || exportTargetNeedsViteCompilation(target));
+}
+/**
+* A component-bearing package publishes Svelte entries (a `svelte` field, a
+* `svelte` condition, or a `.svelte`/`.css` export target). Plain Node cannot
+* evaluate such a package's root: it may re-export `.svelte` files directly or
+* through another component library (#4219).
+*/
+function isComponentBearingPackage(packageJson) {
+	return typeof packageJson?.svelte === "string" || exportTargetNeedsViteCompilation(packageJson?.exports);
+}
+/**
+* Whether the package declares its ROOT as a Svelte entry: a `svelte` field or
+* a `.` export carrying a `svelte` condition (at any nesting) or a
+* `.svelte`/`.css` target. Such a root (e.g. `@happyvertical/smrt-products`,
+* which re-exports its components) cannot be evaluated by plain Node (#4219).
+* A package that only publishes Svelte under a subpath keeps a Node-safe root,
+* as the standards require.
+*
+* A `svelte` condition counts even when its target is plain `.js`: that is
+* what svelte-package and Vite library builds emit for a root that re-exports
+* components (the `.svelte` files sit one import deeper), and it is exactly
+* the shape of every Svelte root in this workspace. Reading the condition as
+* the package's declaration is deliberate — the trade-off is that a Node-safe
+* root that nevertheless declares `svelte` loses its optional provider-context
+* import, which costs nothing when its objects are imported from a subpath.
+*
+* A missing `exports` map, a `.` key absent from it, or an unreadable
+* package.json (`undefined`) all answer `false`: the register then keeps the
+* root import #4187 chose, as before.
+*
+* @internal Exported for tests.
+*/
+function isComponentBearingRoot(packageJson) {
+	if (typeof packageJson?.svelte === "string") return true;
+	const exports = packageJson?.exports;
+	if (typeof exports === "string") return exportTargetNeedsViteCompilation(exports);
+	if (!exports || typeof exports !== "object") return false;
+	const exportsMap = exports;
+	return exportTargetNeedsViteCompilation(Object.keys(exportsMap).some((key) => key.startsWith(".")) ? exportsMap["."] : exportsMap);
+}
+/**
+* Pick the module the generated register imports so a configured provider is
+* evaluated in Node's installed package context (#4187): the package root,
+* unless the package declares that root as a Svelte entry, in which case
+* nothing is imported for the provider (#4219). Its object entries, imported
+* from their manifest `importPath`, already evaluate it in that context, and
+* the transitive loader needs only `import.meta.resolve(provider)`, not an
+* import. No substitute subpath is chosen: one that reaches `.svelte` would
+* re-create the failure this avoids.
+*
+* @internal Exported for tests.
+*/
+function resolveProviderContextImport(packageName, packageJson) {
+	return isComponentBearingRoot(packageJson) ? void 0 : packageName;
+}
 var VIRTUAL_MODULES = {
 	"@smrt/routes": "smrt-consumer:routes",
 	"@smrt/client": "smrt-consumer:client",
@@ -250,11 +321,6 @@ function smrtConsumer(options = {}) {
 	* AsyncLocalStorage instance.
 	*/
 	function resolveConsumerSsrExternalPackages(providerPackages) {
-		const needsViteCompilation = (value) => {
-			if (typeof value === "string") return value.endsWith(".svelte") || value.endsWith(".css");
-			if (!value || typeof value !== "object") return false;
-			return Object.entries(value).some(([condition, target]) => condition === "svelte" || needsViteCompilation(target));
-		};
 		const external = /* @__PURE__ */ new Set();
 		const selective = /* @__PURE__ */ new Map();
 		const visited = /* @__PURE__ */ new Set();
@@ -270,11 +336,8 @@ function smrtConsumer(options = {}) {
 			const visitKey = packageJsonPath ?? `${searchFrom}\0${packageName}`;
 			if (visited.has(visitKey)) continue;
 			visited.add(visitKey);
-			let packageJson;
-			if (packageJsonPath) try {
-				packageJson = JSON.parse(fs$1.readFileSync(packageJsonPath, "utf8"));
-			} catch {}
-			const needsSvelteCompilation = typeof packageJson?.svelte === "string" || needsViteCompilation(packageJson?.exports);
+			const packageJson = readInstalledPackageJson(packageJsonPath);
+			const needsSvelteCompilation = isComponentBearingPackage(packageJson);
 			const isAppResolvable = sameInstalledPackage(packageJsonPath, findInstalledPackageJson(packageName, projectRoot));
 			if (packageName !== "@happyvertical/smrt-app-runtime" && isAppResolvable) if (needsSvelteCompilation && packageJson) selective.set(packageName, {
 				packageJson,
@@ -818,7 +881,6 @@ async function generateRegistrationFile(manifest, projectRoot) {
 		if (!providerPackageJson) return false;
 		return sameInstalledPackage(projectPackageJson, importPackageName === providerPackageName ? providerPackageJson : findInstalledPackageJson(importPackageName, path$1.dirname(providerPackageJson)));
 	};
-	for (const packageName of manifest.smrtDependencies ?? []) if (isSameProjectAndProviderImport(packageName, packageName) && !importsByPath.has(packageName)) importsByPath.set(packageName, /* @__PURE__ */ new Map());
 	const registrations = [];
 	const registrationManifests = {};
 	let importedEntryCount = 0;
@@ -837,6 +899,17 @@ async function generateRegistrationFile(manifest, projectRoot) {
 		for (const lookupKey of lookupKeys) if (lookupKey && !manifestObjectLookup.has(lookupKey)) manifestObjectLookup.set(lookupKey, candidate);
 	}
 	const collectionClassMemo = /* @__PURE__ */ new WeakMap();
+	const svelteRootImportWarnings = /* @__PURE__ */ new Set();
+	const rootImportedObjects = /* @__PURE__ */ new Map();
+	for (const [objectName, def] of Object.entries(manifestObjects)) {
+		if (!def.packageName || def.packageName === manifest.packageName) continue;
+		const objectImportPath = def.importPath || def.packageName;
+		if (objectImportPath !== packageNameFromImportPath(objectImportPath)) continue;
+		const names = rootImportedObjects.get(objectImportPath) ?? [];
+		names.push(def.className || def.exportName || objectName);
+		names.sort((left, right) => left.localeCompare(right));
+		rootImportedObjects.set(objectImportPath, names);
+	}
 	const isCollectionClass = (def, seen = /* @__PURE__ */ new Set()) => {
 		if (!def || typeof def !== "object") return false;
 		const cached = collectionClassMemo.get(def);
@@ -868,6 +941,11 @@ async function generateRegistrationFile(manifest, projectRoot) {
 		const providerPackageName = def.providerPackageName;
 		const appResolvable = isSameProjectAndProviderImport(importPath, providerPackageName);
 		if (!appResolvable && !providerPackageName) throw new Error(`[smrt:consumer] ${objectName} has no configured provider provenance for ${importPath}`);
+		if (importPath === packageNameFromImportPath(importPath) && !svelteRootImportWarnings.has(importPath)) {
+			svelteRootImportWarnings.add(importPath);
+			const providerPackageJsonPath = appResolvable ? void 0 : findInstalledPackageJson(providerPackageName, projectRoot);
+			if (isComponentBearingRoot(readInstalledPackageJson(appResolvable ? findInstalledPackageJson(importPath, projectRoot) : providerPackageJsonPath && findInstalledPackageJson(importPath, path$1.dirname(providerPackageJsonPath))))) console.warn(`[smrt:consumer] ${importPath} declares a Svelte root entry (a "svelte" field, or a "svelte" condition or a .svelte/.css target on its "." export) and exports ${(rootImportedObjects.get(importPath) ?? [objectName]).join(", ")} only from that root; .smrt/register.js keeps the root import${appResolvable ? "" : ` (loaded through ${providerPackageName})`}. Verify that root loads under plain Node (smrt db:migrate, task/schedule workers), or publish the package's @smrt() objects from a ./models or ./objects export.`);
+		}
 		const exportBinding = appResolvable ? getImportBinding(importPath, exportName) : getTransitiveBinding(importPath, providerPackageName, exportName);
 		const collectionBinding = hasCollection && collectionExportName ? appResolvable ? getImportBinding(importPath, collectionExportName) : getTransitiveBinding(importPath, providerPackageName, collectionExportName) : void 0;
 		if (!appResolvable && collectionBinding) transitiveCollectionChecks.push({
@@ -890,6 +968,12 @@ async function generateRegistrationFile(manifest, projectRoot) {
 }`);
 		registeredObjectCount++;
 	}
+	for (const packageName of manifest.smrtDependencies ?? []) {
+		if (!isSameProjectAndProviderImport(packageName, packageName)) continue;
+		const contextImport = resolveProviderContextImport(packageName, readInstalledPackageJson(findInstalledPackageJson(packageName, projectRoot)));
+		if (!contextImport || importsByPath.has(contextImport)) continue;
+		importsByPath.set(contextImport, /* @__PURE__ */ new Map());
+	}
 	if (importedEntryCount === 0) {
 		console.log("[smrt:consumer] No external entries - skipping register.js");
 		return;
@@ -1046,6 +1130,6 @@ export default manifest;
 `;
 }
 //#endregion
-export { loadVerifiedSmrtGenerationSnapshot, serializeSmrtGenerationSnapshot, sha256SmrtGenerationSnapshot, smrtConsumer };
+export { isComponentBearingRoot, loadVerifiedSmrtGenerationSnapshot, resolveProviderContextImport, serializeSmrtGenerationSnapshot, sha256SmrtGenerationSnapshot, smrtConsumer };
 
 //# sourceMappingURL=index.js.map