@vtex/faststore-catalog 0.0.0-bootstrap.0 → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VTEX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @vtex/faststore-catalog
+
+The Catalog Build for a FastStore package. It scans the package's `defineComponent` and
+`defineActions` declarations in source `.tsx`, closes every GraphQL fragment they spread against the
+package's codegen output, and writes `dist/catalog.json`, the file a store compiler reads to know
+which components exist, what props they take, and what data they need. The scan reads `src/` and
+never `dist/`, so it and `tsc` can run in either order.
+
+```bash
+npm install --save-dev @vtex/faststore-catalog
+```
+
+## Usage
+
+```js
+import { buildPackageCatalog } from '@vtex/faststore-catalog';
+
+const result = buildPackageCatalog({ packageDir: process.cwd() });
+console.log(`catalog.json: ${result.catalogEntries} entries`);
+```
+
+`buildPackageCatalog(options)` is the only export. The call is synchronous. A scanner hard error,
+such as a duplicate component name or a fragment that does not resolve, throws.
+
+### Options
+
+| Option | Required | Meaning |
+| --- | --- | --- |
+| `packageDir` | yes | The package root. The scanner reads source from `<packageDir>/src`. |
+| `outDir` | no | Where the artifacts land. Defaults to `<packageDir>/dist`. |
+| `fragmentMapPath` | no | A UI extension's codegen `graphql.ts`, absolute or relative to `packageDir` (never the process cwd). Without it the fragment map is empty, so any fragment spread hard-errors. Throws for `@vtex/faststore`, which keeps its own default. |
+
+The layout follows the package kind, derived from `package.json#name`. `@vtex/faststore` scans
+`src/particles` and `src/matter` and keys entries by bare name. A `(@<vendor>/)?fs-extension-<name>`
+UI extension scans `src/components`, keys entries `<packageName>:<ComponentName>`, and may not
+declare actions. Any other name throws.
+
+### Result
+
+```ts
+{
+  catalogPath: string
+  actionsPath: string | null        // null unless the package declares actions
+  contentTypesPath: string | null   // null unless the package declares content models
+  catalogEntries: number
+  actionNamespaces: number
+  contentTypes: number
+  diagnostics: []             // catalog build failures throw
+}
+```
+
+## Platform packages
+
+The scanner is a Rust native addon. This package ships no binary itself. It declares one
+`@vtex/faststore-catalog-<target>` package per supported target as an optional dependency, and the
+loader picks the one matching the host:
+
+`darwin-arm64`, `darwin-x64`, `linux-x64-gnu`, `linux-arm64-gnu`, `win32-x64`
+
+The two linux prebuilds link glibc. On musl (Alpine) neither resolves, and the loader says so rather
+than pointing at a package that could not work; use a glibc base image instead.
+
+## Links
+
+- [FastStore documentation](https://developers.vtex.com/docs/guides/faststore)
+- Source and issues: [vtex/faststore-ai-native](https://github.com/vtex/faststore-ai-native), private
+  for the pre-1.0 line

package/index.d.ts

@@ -0,0 +1,40 @@
+export type BuildPackageCatalogOptions = {
+  /** The package root; the scanner reads source `.tsx` under `<packageDir>/src`, never `dist/`. */
+  packageDir: string;
+  /** Artifact destination (default: `<packageDir>/dist`). */
+  outDir?: string;
+  /**
+   * A UI extension's fragment-map path (its codegen `graphql.ts`), absolute or relative to
+   * `packageDir` — never the process cwd. Throws for the core package (`@vtex/faststore`),
+   * which keeps its `src/sdk/generated/graphql.ts` default and so could not honor one. Without it
+   * the fragment map is empty, so any fragment spread hard-errors; a path that is not a file throws,
+   * naming the resolved path.
+   */
+  fragmentMapPath?: string;
+};
+
+export type BuildPackageCatalogResult = {
+  /** The emitted `catalog.json`. */
+  catalogPath: string;
+  /** The emitted `actions.json`, or `null` when the package declares no actions. */
+  actionsPath: string | null;
+  /** The emitted `content-types.json`, or `null` when the package declares no content models. */
+  contentTypesPath: string | null;
+  catalogEntries: number;
+  actionNamespaces: number;
+  contentTypes: number;
+  /** Catalog build failures throw; this addon does not emit non-fatal diagnostics. */
+  diagnostics: [];
+};
+
+/**
+ * The per-package catalog build: scans `defineComponent` / `defineActions` declarations in source,
+ * closes GraphQL fragments transitively against the package's codegen output, and emits
+ * `dist/catalog.json` (+ `dist/actions.json`, + `dist/content-types.json`).
+ *
+ * The layout follows the package kind, derived from `package.json#name`: `@vtex/faststore` scans
+ * `src/particles`/`src/matter` and keys entries by bare name; a `(@<vendor>/)?fs-extension-<name>` UI
+ * extension scans `src/components`, keys them `<packageName>:<ComponentName>`, and may not declare
+ * actions. Any other package name throws.
+ */
+export function buildPackageCatalog(options: BuildPackageCatalogOptions): BuildPackageCatalogResult;

package/index.js

@@ -0,0 +1,71 @@
+// The JS surface of the Catalog Build napi addon: loads the platform-matched cdylib (built + renamed
+// by scripts/build-node-addon.mjs) and wraps its string-in/string-out native export in the
+// JSON-object surface a package's build script consumes. The native call is synchronous.
+
+const { existsSync } = require('node:fs');
+const { join } = require('node:path');
+
+const NATIVE_BY_PLATFORM = {
+  'darwin-arm64': 'faststore-catalog.darwin-arm64.node',
+  'darwin-x64': 'faststore-catalog.darwin-x64.node',
+  'linux-x64': 'faststore-catalog.linux-x64-gnu.node',
+  'linux-arm64': 'faststore-catalog.linux-arm64-gnu.node',
+  'win32-x64': 'faststore-catalog.win32-x64.node',
+};
+
+// The per-platform binary packages installed as optionalDependencies of the published package
+// (napi-rs prebuild pattern). Inside the workspace the crate-local .node file wins instead.
+const PACKAGE_BY_PLATFORM = {
+  'darwin-arm64': '@vtex/faststore-catalog-darwin-arm64',
+  'darwin-x64': '@vtex/faststore-catalog-darwin-x64',
+  'linux-x64': '@vtex/faststore-catalog-linux-x64-gnu',
+  'linux-arm64': '@vtex/faststore-catalog-linux-arm64-gnu',
+  'win32-x64': '@vtex/faststore-catalog-win32-x64',
+};
+
+// The prebuilt linux binaries link glibc; on musl (Alpine) the gnu platform package either won't
+// resolve or won't load, so name the real problem instead of suggesting a package that can't work.
+function isMusl() {
+  return process.platform === 'linux' && !process.report?.getReport?.()?.header?.glibcVersionRuntime;
+}
+
+function loadNative() {
+  const key = `${process.platform}-${process.arch}`;
+  const file = NATIVE_BY_PLATFORM[key];
+  if (!file) {
+    throw new Error(`@vtex/faststore-catalog: unsupported platform '${key}'`);
+  }
+  const local = join(__dirname, file);
+  if (existsSync(local)) {
+    return require(local);
+  }
+  if (isMusl()) {
+    throw new Error(
+      `@vtex/faststore-catalog: musl libc is not supported — the '${key}' prebuilds are glibc-only (use a glibc base image instead of Alpine)`,
+    );
+  }
+  try {
+    return require(PACKAGE_BY_PLATFORM[key]);
+  } catch (error) {
+    const detail = error instanceof Error && error.message ? ` (${error.message})` : '';
+    throw new Error(
+      `@vtex/faststore-catalog: native addon '${file}' is missing — in the workspace, build it with ` +
+        `'node scripts/build-node-addon.mjs'; in an installed package, ensure the platform package ` +
+        `'${PACKAGE_BY_PLATFORM[key]}' installed (it ships as an optionalDependency)${detail}`,
+      { cause: error },
+    );
+  }
+}
+
+const native = loadNative();
+
+// The per-package catalog build: scans defineComponent/defineActions in source, closes GraphQL
+// fragments, emits dist/catalog.json (+ dist/actions.json, + dist/content-types.json). Scanner
+// hard errors throw.
+function buildPackageCatalog(options) {
+  return JSON.parse(native.buildPackageCatalog(JSON.stringify(options)));
+}
+
+module.exports = {
+  buildPackageCatalog,
+};

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@vtex/faststore-catalog",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder that reserves the name for trusted publishing. Do not install.",
+  "version": "0.0.4",
+  "description": "Build a FastStore package's component catalog: scans its defineComponent declarations, closes their GraphQL fragments, and emits dist/catalog.json.",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/vtex/faststore-ai-native.git" }
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
+  "optionalDependencies": {
+    "@vtex/faststore-catalog-darwin-arm64": "0.0.4",
+    "@vtex/faststore-catalog-darwin-x64": "0.0.4",
+    "@vtex/faststore-catalog-linux-x64-gnu": "0.0.4",
+    "@vtex/faststore-catalog-linux-arm64-gnu": "0.0.4",
+    "@vtex/faststore-catalog-win32-x64": "0.0.4"
+  }
 }