Add cmake-file-api package, implementing a TypeScript wrapper of the CMake file-based API

.github/copilot-instructions.md

@@ -0,0 +1,77 @@
+# Copilot Instructions for React Native Node-API
+
+This is a **monorepo** that brings Node-API support to React Native, enabling native addons written in C/C++/Rust to run on React Native across iOS and Android.
+
+## Package-Specific Instructions
+
+**IMPORTANT**: Before working on any package, always check for and read package-specific `copilot-instructions.md` files in the package directory. These contain critical preferences and patterns for that specific package.
+
+## Architecture Overview
+
+**Core Flow**: JS `require("./addon.node")` → Babel transform → `requireNodeAddon()` TurboModule call → native library loading → Node-API module initialization
+
+### Package Architecture
+
+See the [README.md](../README.md#packages) for detailed descriptions of each package and their roles in the system. Key packages include:
+
+- `packages/host` - Core Node-API runtime and Babel plugin
+- `packages/cmake-rn` - CMake wrapper for native builds
+- `packages/cmake-file-api` - TypeScript wrapper for CMake File API with Zod validation
+- `packages/ferric` - Rust/Cargo wrapper with napi-rs integration
+- `packages/gyp-to-cmake` - Legacy binding.gyp compatibility
+- `apps/test-app` - Integration testing harness
+
+## Critical Build Dependencies
+
+- **Custom Hermes**: Currently depends on a patched Hermes with Node-API support (see [facebook/hermes#1377](https://github.com/facebook/hermes/pull/1377))
+- **Prebuilt Binary Spec**: All tools must output to the exact naming scheme:
+  - Android: `*.android.node/` with jniLibs structure + `react-native-node-api-module` marker file
+  - iOS: `*.apple.node` (XCFramework renamed) + marker file
+
+## Essential Workflows
+
+### Development Setup
+
+```bash
+npm ci && npm run build      # Install deps and build all packages
+npm run bootstrap           # Build native components (weak-node-api, examples)
+```
+
+### Package Development
+
+- **TypeScript project references**: Use `tsc --build` for incremental compilation
+- **Workspace scripts**: Most build/test commands use npm workspaces (`--workspace` flag)
+- **Focus on Node.js packages**: AI development primarily targets the Node.js tooling packages rather than native mobile code
+- **No TypeScript type asserts**: You have to ask explicitly and justify if you want to add `as` type assertions.
+
+## Key Patterns
+
+### Babel Transformation
+
+The core magic happens in `packages/host/src/node/babel-plugin/plugin.ts`:
+
+```js
+// Input:  require("./addon.node")
+// Output: require("react-native-node-api").requireNodeAddon("pkg-name--addon")
+```
+
+### CMake Integration
+
+For linking against Node-API in CMakeLists.txt:
+
+```cmake
+include(${WEAK_NODE_API_CONFIG})
+target_link_libraries(addon PRIVATE weak-node-api)
+```
+
+### Cross-Platform Naming
+
+Library names use double-dash separation: `package-name--path-component--addon-name`
+
+### Testing
+
+- **Individual packages**: Some packages have VS Code test tasks and others have their own `npm test` scripts for focused iteration (e.g., `npm test --workspace cmake-rn`). Use the latter only if the former is missing.
+- **Cross-package**: Use root-level `npm test` for cross-package testing once individual package tests pass
+- **Mobile integration**: Available but not the primary AI development focus - ask the developer to run those tests as needed
+
+**Documentation**: Integration details, platform setup, and toolchain configuration are covered in existing repo documentation files.

.vscode/tasks.json

@@ -0,0 +1,14 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Test cmake-file-api",
+      "command": "node",
+      "args": ["--run", "test"],
+      "options": {
+        "cwd": "${workspaceFolder}/packages/cmake-file-api"
+      },
+      "group": "test"
+    }
+  ]
+}

configs/tsconfig.node-tests.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.node.json",
+  "compilerOptions": {
+    "composite": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": false
+  },
+  "include": ["${configDir}/src/**/*.test.ts"],
+  "exclude": []
+  /*
+  "references": [
+    {
+      "path": "./tsconfig.json"
+    }
+  ]
+  */
+}

configs/tsconfig.cli.json → configs/tsconfig.node.json

@@ -7,6 +7,6 @@
     "rootDir": "${configDir}/src",
     "types": ["node"]
   },
-  "include": ["${configDir}/src/*.ts"],
-  "exclude": ["${configDir}/**.test.ts"]
+  "include": ["${configDir}/src/"],
+  "exclude": ["${configDir}/**/*.test.ts"]
 }

package.json

@@ -4,15 +4,16 @@
   "type": "module",
   "private": true,
   "workspaces": [
-    "apps/test-app",
     "packages/cli-utils",
-    "packages/gyp-to-cmake",
+    "packages/cmake-file-api",
     "packages/cmake-rn",
     "packages/ferric",
+    "packages/gyp-to-cmake",
     "packages/host",
     "packages/node-addon-examples",
     "packages/node-tests",
-    "packages/ferric-example"
+    "packages/ferric-example",
+    "apps/test-app"
   ],
   "homepage": "https://github.com/callstackincubator/react-native-node-api#readme",
   "scripts": {

packages/cli-utils/tsconfig.json

@@ -1,3 +1,3 @@
 {
-  "extends": "../../configs/tsconfig.cli.json"
+  "extends": "../../configs/tsconfig.node.json"
 }

packages/cmake-file-api/README.md

@@ -0,0 +1,7 @@
+# CMake File API (unofficial)
+
+The CMake File API provides an interface for querying CMake's configuration and project information.
+
+The API is based on files, where queries are written by client tools and read by CMake and replies are then written by CMake and read by client tools. The API is versioned, and the current version is v1 and these files are located in a directory named `.cmake/api/v1` in the build directory.
+
+This package provides a TypeScript interface to create query files and read replies and is intended to serve the same purpose to the TypeScript community that the [`cmake-file-api` crate](https://crates.io/crates/cmake-file-api), serves to the Rust community.