@backtickjs/builds 0.0.0-stage → 0.1.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean-François Bisson
+
+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

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @backtickjs/builds
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Keeps a [Backtick](https://backtickjs.com) server drawing for every build of its React Native app that's still in users' hands. A store build carries the modules it was built with, at their versions, for as long as it's installed. Your server moves on. Each build sends an id that names its modules, and the server bundles its screens for exactly those modules, or refuses a build it can't serve.
+
+## Install
+
+```sh
+npm install @backtickjs/builds
+```
+
+## How it works
+
+1. **The app declares what it offers to screens** in a module map, one per platform as Metro picks files: `moduleMap.ts` for iOS and Android, and `moduleMap.web.ts` for the web. A module map is a table and nothing else, so it can be read without running it:
+
+   ```ts
+   // moduleMap.ts
+   import type { ModuleMap } from "@backtickjs/react-native-client";
+
+   export const moduleMap = {
+     react: () => require("react"),
+     "react/jsx-runtime": () => require("react/jsx-runtime"),
+     "react-native": () => require("react-native"),
+     "react-native-fbsdk-next": () => require("react-native-fbsdk-next"),
+   } satisfies ModuleMap;
+   ```
+
+   An entry that decides at runtime, like `native() ? require("…") : {}`, is an error. What a platform lacks, its map leaves out.
+
+2. **Each build gets an id:** a hash of the modules its platform's map offers, each at the installed version of its package. `app.config.ts` puts the ids in the app config:
+
+   ```ts
+   // app.config.ts
+   import { buildIds } from "@backtickjs/builds";
+   import type { ConfigContext, ExpoConfig } from "expo/config";
+
+   export default ({ config, projectRoot }: ConfigContext): ExpoConfig =>
+     ({
+       ...config,
+       extra: { ...config.extra, buildIds: buildIds(projectRoot) },
+     }) as ExpoConfig;
+   ```
+
+3. **The app sends its id** however it reaches its server: a header, a GraphQL variable. `buildIdFrom` from [`@backtickjs/react-native-client`](https://github.com/backtickjs/backtick/tree/main/packages/react-native-client) reads it:
+
+   ```ts
+   const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+   ```
+
+4. **The server bundles for that build's modules:**
+
+   ```ts
+   import { createBuilds } from "@backtickjs/builds";
+   import { bundler } from "@backtickjs/bundler";
+
+   const builds = createBuilds({ projectRoot });
+
+   const modules = builds.modulesOf(buildId);
+   const bundle = await bundler.build({ input, modules });
+   ```
+
+   To draw differently for builds that lack a module, ask with `supports` from [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler), the same check the bundler makes: `supports(modules, "react-native-fbsdk-next", "^13")`.
+
+5. **Every build is registered before it ships,** in `builds/`, one file per id, committed with the code:
+
+   ```sh
+   npx backtick-builds register
+   ```
+
+   ```json
+   {
+     "createdAt": "2026-10-12T00:00:00.000Z",
+     "deprecated": false,
+     "modules": {
+       "react": "19.2.3",
+       "react/jsx-runtime": "19.2.3",
+       "react-native": "0.86.3"
+     }
+   }
+   ```
+
+   Run `backtick-builds check` in your tests, or let EAS run it: as `eas-build-post-install` in `package.json`, it fails a build that isn't registered, checking the platform being built and letting development builds through.
+
+   ```json
+   "scripts": {
+     "eas-build-post-install": "backtick-builds check"
+   }
+   ```
+
+## Unknown and deprecated builds
+
+`modulesOf` throws for a build its server can't draw for:
+
+- **`UnknownBuild`**: no id, or one that isn't registered. Every build is registered before it ships, so this means the server or the build was deployed wrong, as when a server is rolled back past a build in users' hands. Answer it as a server error.
+- **`DeprecatedBuild`**: a build you retired by setting `"deprecated": true` in its file. Answer it with something your app shell recognises and turns into "update the app", such as HTTP 426. The shell has to know that answer before the build is retired, so ship it in your first build.
+
+## API
+
+- `buildIds(projectRoot)`: the id of the build the app at `projectRoot` now makes, on `ios`, `android` and `web`.
+- `createBuilds({ projectRoot })`: the app's builds for its server. `modulesOf(buildId)` resolves a build, `installed(platform)` is what this code's build carries, and `unregistered(platform)` says why this code's build couldn't ship, or null. Registered builds are read once. Module maps are only read for an id that isn't registered, as in development after a package change.
+- `register(projectRoot)`: what `backtick-builds register` runs. A build already registered keeps its `createdAt` and `deprecated`.
+- `readModuleMap(file)`, `moduleMapFile(projectRoot, platform)`, `installedModules(projectRoot, platform)`, `buildIdOf(modules)`, `readBuilds(directory)`: the steps, for tools of your own.
+
+## Related
+
+- [`@backtickjs/react-native-client`](https://github.com/backtickjs/backtick/tree/main/packages/react-native-client): `evaluate` and `buildIdFrom`, in the app
+- [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler): bundles a screen for a build's modules, and `supports`
+
+## License
+
+MIT

package/dist/builds.d.ts

@@ -0,0 +1,64 @@
+import { type Platform } from "./moduleMap.js";
+import type { Modules } from "@backtickjs/bundler";
+/** A registered build: the modules it carries, and what's known of it. */
+export type Build = {
+    createdAt: string;
+    deprecated: boolean;
+    modules: Modules;
+};
+/**
+ * A build its server can't draw for: it doesn't know the modules it
+ * carries. Fatal: every build is registered before it ships, so one a server
+ * doesn't know means it, or the build, was deployed wrong.
+ */
+export declare class UnknownBuild extends Error {
+    readonly buildId: string | null;
+    constructor(buildId: string | null);
+}
+/** A build its server no longer draws for, on purpose: its users are asked to update. */
+export declare class DeprecatedBuild extends Error {
+    readonly buildId: string;
+    constructor(buildId: string);
+}
+/** Where an app keeps its registered builds, one file each: `builds/`. */
+export declare function buildsDirectory(projectRoot: string): string;
+/** The builds registered in `directory`, by id. */
+export declare function readBuilds(directory: string): Map<string, Build>;
+/** The id of the build the app at `projectRoot` now makes, on each platform. */
+export declare function buildIds(projectRoot: string): Record<Platform, string>;
+/** The builds of the app at `projectRoot`, as its server resolves them. */
+export type Builds = {
+    /**
+     * The modules of the build with id `buildId`, however it was sent: a
+     * registered build's, or one this code makes. Throws `DeprecatedBuild` for
+     * one marked deprecated, and `UnknownBuild` for one this server doesn't
+     * know, or none.
+     */
+    modulesOf(buildId: string | null): Modules;
+    /** The modules the build this code makes for `platform` carries. */
+    installed(platform: Platform): Modules;
+    /**
+     * Why the build this code makes for `platform` can't ship, or null: its
+     * server wouldn't know it once the code moves on, or it's deprecated.
+     */
+    unregistered(platform: Platform): string | null;
+};
+/**
+ * The builds of the app at `projectRoot`, for its server: the registered
+ * ones, read once, and the ones this code makes, worked out only when an id
+ * isn't registered, as in development after a package change.
+ */
+export declare function createBuilds({ projectRoot }: {
+    projectRoot: string;
+}): Builds;
+/**
+ * Registers the builds the app at `projectRoot` now makes, one file per id
+ * in its `builds/`, for its server to keep drawing for them once the code
+ * moves on. A build already registered keeps when it was, and whether it's
+ * deprecated. Answers each platform's id and file.
+ */
+export declare function register(projectRoot: string): {
+    platform: Platform;
+    id: string;
+    file: string;
+}[];

package/dist/builds.js

@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { platforms } from "./moduleMap.js";
+import { buildIdOf, installedModules } from "./modules.js";
+/**
+ * A build its server can't draw for: it doesn't know the modules it
+ * carries. Fatal: every build is registered before it ships, so one a server
+ * doesn't know means it, or the build, was deployed wrong.
+ */
+export class UnknownBuild extends Error {
+    buildId;
+    constructor(buildId) {
+        super(buildId === null
+            ? "No build id was sent: the app's code predates build ids, or doesn't send its own."
+            : `No modules for build ${JSON.stringify(buildId)}: it isn't registered here.`);
+        this.buildId = buildId;
+    }
+}
+/** A build its server no longer draws for, on purpose: its users are asked to update. */
+export class DeprecatedBuild extends Error {
+    buildId;
+    constructor(buildId) {
+        super(`Build ${JSON.stringify(buildId)} is deprecated.`);
+        this.buildId = buildId;
+    }
+}
+/** Where an app keeps its registered builds, one file each: `builds/`. */
+export function buildsDirectory(projectRoot) {
+    return join(projectRoot, "builds");
+}
+/** The builds registered in `directory`, by id. */
+export function readBuilds(directory) {
+    if (!existsSync(directory))
+        return new Map();
+    return new Map(readdirSync(directory)
+        .filter((file) => file.endsWith(".json"))
+        .map((file) => [
+        file.slice(0, -".json".length),
+        JSON.parse(readFileSync(join(directory, file), "utf8")),
+    ]));
+}
+/** The id of the build the app at `projectRoot` now makes, on each platform. */
+export function buildIds(projectRoot) {
+    return Object.fromEntries(platforms.map((platform) => [
+        platform,
+        buildIdOf(installedModules(projectRoot, platform)),
+    ]));
+}
+/**
+ * The builds of the app at `projectRoot`, for its server: the registered
+ * ones, read once, and the ones this code makes, worked out only when an id
+ * isn't registered, as in development after a package change.
+ */
+export function createBuilds({ projectRoot }) {
+    const registered = readBuilds(buildsDirectory(projectRoot));
+    const installed = new Map();
+    const installedOn = (platform) => {
+        let modules = installed.get(platform);
+        if (modules === undefined) {
+            modules = installedModules(projectRoot, platform);
+            installed.set(platform, modules);
+        }
+        return modules;
+    };
+    return {
+        modulesOf(buildId) {
+            const build = buildId === null ? undefined : registered.get(buildId);
+            if (build?.deprecated)
+                throw new DeprecatedBuild(buildId);
+            if (build !== undefined)
+                return build.modules;
+            const current = platforms
+                .map(installedOn)
+                .find((modules) => buildIdOf(modules) === buildId);
+            if (current === undefined)
+                throw new UnknownBuild(buildId);
+            return current;
+        },
+        installed: installedOn,
+        unregistered(platform) {
+            const modules = installedOn(platform);
+            const id = buildIdOf(modules);
+            const build = registered.get(id);
+            if (build === undefined) {
+                return `No builds/${id}.json for ${platform}: run backtick-builds register and commit what it writes.`;
+            }
+            if (build.deprecated) {
+                return `builds/${id}.json, ${platform}'s build, is deprecated: its users would only be asked to update.`;
+            }
+            if (!isDeepStrictEqual(build.modules, modules)) {
+                return `builds/${id}.json isn't ${platform}'s modules: run backtick-builds register.`;
+            }
+            return null;
+        },
+    };
+}
+/**
+ * Registers the builds the app at `projectRoot` now makes, one file per id
+ * in its `builds/`, for its server to keep drawing for them once the code
+ * moves on. A build already registered keeps when it was, and whether it's
+ * deprecated. Answers each platform's id and file.
+ */
+export function register(projectRoot) {
+    const directory = buildsDirectory(projectRoot);
+    mkdirSync(directory, { recursive: true });
+    return platforms.map((platform) => {
+        const modules = installedModules(projectRoot, platform);
+        const id = buildIdOf(modules);
+        const file = join(directory, `${id}.json`);
+        const recorded = existsSync(file)
+            ? JSON.parse(readFileSync(file, "utf8"))
+            : {};
+        const build = {
+            createdAt: recorded.createdAt ?? new Date().toISOString(),
+            deprecated: recorded.deprecated ?? false,
+            modules,
+        };
+        writeFileSync(file, JSON.stringify(build, null, 2) + "\n");
+        return { platform, id, file };
+    });
+}
+//# sourceMappingURL=builds.js.map

package/dist/builds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builds.js","sourceRoot":"","sources":["../src/builds.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { relative } from "node:path";
+import { createBuilds, register } from "./builds.js";
+import { platforms } from "./moduleMap.js";
+// `backtick-builds register`: records the builds the app in this directory
+// now makes, to commit. `backtick-builds check`: fails unless they're all
+// registered, as an EAS build's `eas-build-post-install` runs it, checking
+// the platform it builds and letting a development build through.
+const [command] = process.argv.slice(2);
+const projectRoot = process.cwd();
+if (command === "register") {
+    for (const { platform, file } of register(projectRoot)) {
+        console.log(`Registered ${platform}: ${relative(projectRoot, file)}`);
+    }
+}
+else if (command === "check") {
+    if (process.env.EAS_BUILD_PROFILE === "development") {
+        console.log("A development build: its server is this code's.");
+        process.exit(0);
+    }
+    const building = process.env.EAS_BUILD_PLATFORM;
+    const builds = createBuilds({ projectRoot });
+    const problems = (building ? [building] : platforms)
+        .map((platform) => builds.unregistered(platform))
+        .filter((problem) => problem !== null);
+    for (const problem of problems)
+        console.error(problem);
+    if (problems.length > 0)
+        process.exit(1);
+    console.log("Every build this code makes is registered.");
+}
+else {
+    console.error("Usage: backtick-builds register | check");
+    process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAiB,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE1D,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,kEAAkE;AAClE,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACxC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;AAElC,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;IAC3B,KAAK,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACvD,OAAO,CAAC,GAAG,CAAC,cAAc,QAAQ,KAAK,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;KAAM,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;IAC/B,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,aAAa,EAAE,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,iDAAiD,CAAC,CAAC;QAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kBAA0C,CAAC;IACxE,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;SACjD,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;SAChD,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;IACzC,KAAK,MAAM,OAAO,IAAI,QAAQ;QAAE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzC,OAAO,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;AAC5D,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;IACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { type Build, type Builds, buildIds, buildsDirectory, createBuilds, DeprecatedBuild, readBuilds, register, UnknownBuild, } from "./builds.js";
+export { moduleMapFile, type Platform, platforms, readModuleMap, } from "./moduleMap.js";
+export { buildIdOf, installedModules } from "./modules.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { buildIds, buildsDirectory, createBuilds, DeprecatedBuild, readBuilds, register, UnknownBuild, } from "./builds.js";
+export { moduleMapFile, platforms, readModuleMap, } from "./moduleMap.js";
+export { buildIdOf, installedModules } from "./modules.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,eAAe,EACf,UAAU,EACV,QAAQ,EACR,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,EAEb,SAAS,EACT,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/moduleMap.d.ts

@@ -0,0 +1,17 @@
+/** The platforms an app is built for, each with its own module map. */
+export declare const platforms: readonly ["ios", "android", "web"];
+export type Platform = (typeof platforms)[number];
+/**
+ * The specifiers a module map offers, read from its source without running
+ * it: `export const moduleMap = { … }`, each entry `() => require("…")`, and
+ * nothing else but type imports. Anything more, as a check of the platform,
+ * would make what a build offers something only the device knows, so it
+ * throws, naming the line.
+ */
+export declare function readModuleMap(file: string): string[];
+/**
+ * The module map Metro picks for `platform` in the app at `projectRoot`, as
+ * it picks any file: `moduleMap.ios.ts` (or `.android`, `.web`), then
+ * `moduleMap.native.ts` off the web, then `moduleMap.ts`.
+ */
+export declare function moduleMapFile(projectRoot: string, platform: Platform): string;

package/dist/moduleMap.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+/** The platforms an app is built for, each with its own module map. */
+export const platforms = ["ios", "android", "web"];
+// TypeScript, loaded only to read a module map: a server reading registered
+// builds never needs it.
+const require = createRequire(import.meta.url);
+/**
+ * The specifiers a module map offers, read from its source without running
+ * it: `export const moduleMap = { … }`, each entry `() => require("…")`, and
+ * nothing else but type imports. Anything more, as a check of the platform,
+ * would make what a build offers something only the device knows, so it
+ * throws, naming the line.
+ */
+export function readModuleMap(file) {
+    const ts = require("typescript");
+    const source = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest);
+    const wrong = (node, what) => {
+        const { line } = source.getLineAndCharacterOfPosition(node.getStart(source));
+        return new Error(`${file}:${line + 1}: ${what}`);
+    };
+    let map;
+    for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement) &&
+            statement.importClause?.isTypeOnly) {
+            continue;
+        }
+        const declaration = ts.isVariableStatement(statement)
+            ? statement.declarationList.declarations[0]
+            : undefined;
+        let value = declaration?.initializer;
+        if (value !== undefined && ts.isSatisfiesExpression(value)) {
+            value = value.expression;
+        }
+        if (map === undefined &&
+            declaration?.name.getText(source) === "moduleMap" &&
+            value !== undefined &&
+            ts.isObjectLiteralExpression(value)) {
+            map = value;
+            continue;
+        }
+        throw wrong(statement, "a module map holds `export const moduleMap = { … }` and type imports only");
+    }
+    if (map === undefined) {
+        throw new Error(`${file}: no \`export const moduleMap = { … }\``);
+    }
+    return map.properties.map((property) => {
+        const entry = ts.isPropertyAssignment(property) &&
+            (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+            ts.isArrowFunction(property.initializer) &&
+            property.initializer.parameters.length === 0 &&
+            ts.isCallExpression(property.initializer.body) &&
+            property.initializer.body.expression.getText(source) === "require" &&
+            property.initializer.body.arguments.length === 1 &&
+            ts.isStringLiteral(property.initializer.body.arguments[0])
+            ? property.name
+            : undefined;
+        if (entry === undefined) {
+            throw wrong(property, 'each entry is `"specifier": () => require("…")`');
+        }
+        return entry.text;
+    });
+}
+/**
+ * The module map Metro picks for `platform` in the app at `projectRoot`, as
+ * it picks any file: `moduleMap.ios.ts` (or `.android`, `.web`), then
+ * `moduleMap.native.ts` off the web, then `moduleMap.ts`.
+ */
+export function moduleMapFile(projectRoot, platform) {
+    const extensions = [platform, ...(platform === "web" ? [] : ["native"])];
+    for (const extension of [...extensions.map((each) => `.${each}`), ""]) {
+        const file = join(projectRoot, `moduleMap${extension}.ts`);
+        if (existsSync(file))
+            return file;
+    }
+    throw new Error(`${projectRoot}: no moduleMap.ts`);
+}
+//# sourceMappingURL=moduleMap.js.map

package/dist/moduleMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleMap.js","sourceRoot":"","sources":["../src/moduleMap.ts"],"names":[],"mappings":"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"}

package/dist/modules.d.ts

@@ -0,0 +1,14 @@
+import type { Modules } from "@backtickjs/bundler";
+import { type Platform } from "./moduleMap.js";
+/**
+ * The modules the module map for `platform` offers, each at the installed
+ * version of the package it comes from, in the app at `projectRoot`: what a
+ * build made from it now carries there.
+ */
+export declare function installedModules(projectRoot: string, platform: Platform): Modules;
+/**
+ * The id of a build that carries `modules`: a hash of them, so two builds
+ * that carry the same share it, and a build always names exactly what it
+ * has.
+ */
+export declare function buildIdOf(modules: Modules): string;

package/dist/modules.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { moduleMapFile, readModuleMap } from "./moduleMap.js";
+// The package a module specifier is in: `react` for `react/jsx-runtime`.
+function packageOf(specifier) {
+    const segments = specifier.split("/");
+    return segments.slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
+}
+// Where a package is installed for the app at `projectRoot`, as Node finds
+// it: in its node_modules, or the nearest above, as a workspace hoists it.
+function installed(projectRoot, name) {
+    for (let directory = projectRoot;; directory = dirname(directory)) {
+        const file = join(directory, "node_modules", name, "package.json");
+        if (existsSync(file))
+            return file;
+        if (dirname(directory) === directory) {
+            throw new Error(`${projectRoot}: ${name} isn't installed`);
+        }
+    }
+}
+/**
+ * The modules the module map for `platform` offers, each at the installed
+ * version of the package it comes from, in the app at `projectRoot`: what a
+ * build made from it now carries there.
+ */
+export function installedModules(projectRoot, platform) {
+    const specifiers = readModuleMap(moduleMapFile(projectRoot, platform));
+    const versions = new Map();
+    const versionOf = (name) => {
+        let version = versions.get(name);
+        if (version === undefined) {
+            const file = installed(projectRoot, name);
+            version = JSON.parse(readFileSync(file, "utf8"))
+                .version;
+            versions.set(name, version);
+        }
+        return version;
+    };
+    return Object.fromEntries([...specifiers]
+        .sort()
+        .map((specifier) => [specifier, versionOf(packageOf(specifier))]));
+}
+/**
+ * The id of a build that carries `modules`: a hash of them, so two builds
+ * that carry the same share it, and a build always names exactly what it
+ * has.
+ */
+export function buildIdOf(modules) {
+    const sorted = Object.keys(modules)
+        .sort()
+        .map((specifier) => [specifier, modules[specifier]]);
+    return createHash("sha256")
+        .update(JSON.stringify(sorted))
+        .digest("hex")
+        .slice(0, 16);
+}
+//# sourceMappingURL=modules.js.map

package/dist/modules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modules.js","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAiB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE7E,yEAAyE;AACzE,SAAS,SAAS,CAAC,SAAiB;IAClC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxE,CAAC;AAED,2EAA2E;AAC3E,2EAA2E;AAC3E,SAAS,SAAS,CAAC,WAAmB,EAAE,IAAY;IAClD,KAAK,IAAI,SAAS,GAAG,WAAW,GAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACnE,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAClC,IAAI,OAAO,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,GAAG,WAAW,KAAK,IAAI,kBAAkB,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,WAAmB,EACnB,QAAkB;IAElB,MAAM,UAAU,GAAG,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,EAAE;QACjC,IAAI,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;YAC1C,OAAO,GAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAyB;iBACtE,OAAO,CAAC;YACX,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IACF,OAAO,MAAM,CAAC,WAAW,CACvB,CAAC,GAAG,UAAU,CAAC;SACZ,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAgB;IACxC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;SAChC,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACvD,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;SAC9B,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@backtickjs/builds",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.9",
+  "description": "Keeps a Backtick server drawing for every build of its app in users' hands: build ids, a registry of what each build carries, and a check for EAS builds",
+  "keywords": [
+    "backtick",
+    "react-native",
+    "expo",
+    "server-driven-ui",
+    "builds",
+    "versioning"
+  ],
+  "homepage": "https://backtickjs.com",
+  "bugs": {
+    "url": "https://github.com/backtickjs/backtick/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/backtickjs/backtick.git",
+    "directory": "packages/builds"
+  },
+  "license": "MIT",
+  "author": "Jean-François Bisson <jf@backtickjs.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "backtick-builds": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/._cache",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@backtickjs/bundler": "^0.1.9",
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "prettier": "^3.6.2"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "format": "prettier --write --ignore-unknown .",
+    "format:check": "prettier --check --ignore-unknown .",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "clean": "rm -rf node_modules dist .turbo"
+  }
 }

package/src/builds.ts

@@ -0,0 +1,163 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { type Platform, platforms } from "./moduleMap.js";
+import type { Modules } from "@backtickjs/bundler";
+import { buildIdOf, installedModules } from "./modules.js";
+
+/** A registered build: the modules it carries, and what's known of it. */
+export type Build = {
+  // when it was first registered, as an ISO date
+  createdAt: string;
+  // set to true by hand to stop drawing for it: its users are asked to update
+  deprecated: boolean;
+  modules: Modules;
+};
+
+/**
+ * A build its server can't draw for: it doesn't know the modules it
+ * carries. Fatal: every build is registered before it ships, so one a server
+ * doesn't know means it, or the build, was deployed wrong.
+ */
+export class UnknownBuild extends Error {
+  constructor(readonly buildId: string | null) {
+    super(
+      buildId === null
+        ? "No build id was sent: the app's code predates build ids, or doesn't send its own."
+        : `No modules for build ${JSON.stringify(buildId)}: it isn't registered here.`,
+    );
+  }
+}
+
+/** A build its server no longer draws for, on purpose: its users are asked to update. */
+export class DeprecatedBuild extends Error {
+  constructor(readonly buildId: string) {
+    super(`Build ${JSON.stringify(buildId)} is deprecated.`);
+  }
+}
+
+/** Where an app keeps its registered builds, one file each: `builds/`. */
+export function buildsDirectory(projectRoot: string): string {
+  return join(projectRoot, "builds");
+}
+
+/** The builds registered in `directory`, by id. */
+export function readBuilds(directory: string): Map<string, Build> {
+  if (!existsSync(directory)) return new Map();
+  return new Map(
+    readdirSync(directory)
+      .filter((file) => file.endsWith(".json"))
+      .map((file) => [
+        file.slice(0, -".json".length),
+        JSON.parse(readFileSync(join(directory, file), "utf8")) as Build,
+      ]),
+  );
+}
+
+/** The id of the build the app at `projectRoot` now makes, on each platform. */
+export function buildIds(projectRoot: string): Record<Platform, string> {
+  return Object.fromEntries(
+    platforms.map((platform) => [
+      platform,
+      buildIdOf(installedModules(projectRoot, platform)),
+    ]),
+  ) as Record<Platform, string>;
+}
+
+/** The builds of the app at `projectRoot`, as its server resolves them. */
+export type Builds = {
+  /**
+   * The modules of the build with id `buildId`, however it was sent: a
+   * registered build's, or one this code makes. Throws `DeprecatedBuild` for
+   * one marked deprecated, and `UnknownBuild` for one this server doesn't
+   * know, or none.
+   */
+  modulesOf(buildId: string | null): Modules;
+  /** The modules the build this code makes for `platform` carries. */
+  installed(platform: Platform): Modules;
+  /**
+   * Why the build this code makes for `platform` can't ship, or null: its
+   * server wouldn't know it once the code moves on, or it's deprecated.
+   */
+  unregistered(platform: Platform): string | null;
+};
+
+/**
+ * The builds of the app at `projectRoot`, for its server: the registered
+ * ones, read once, and the ones this code makes, worked out only when an id
+ * isn't registered, as in development after a package change.
+ */
+export function createBuilds({ projectRoot }: { projectRoot: string }): Builds {
+  const registered = readBuilds(buildsDirectory(projectRoot));
+  const installed = new Map<Platform, Modules>();
+  const installedOn = (platform: Platform) => {
+    let modules = installed.get(platform);
+    if (modules === undefined) {
+      modules = installedModules(projectRoot, platform);
+      installed.set(platform, modules);
+    }
+    return modules;
+  };
+  return {
+    modulesOf(buildId) {
+      const build = buildId === null ? undefined : registered.get(buildId);
+      if (build?.deprecated) throw new DeprecatedBuild(buildId!);
+      if (build !== undefined) return build.modules;
+      const current = platforms
+        .map(installedOn)
+        .find((modules) => buildIdOf(modules) === buildId);
+      if (current === undefined) throw new UnknownBuild(buildId);
+      return current;
+    },
+    installed: installedOn,
+    unregistered(platform) {
+      const modules = installedOn(platform);
+      const id = buildIdOf(modules);
+      const build = registered.get(id);
+      if (build === undefined) {
+        return `No builds/${id}.json for ${platform}: run backtick-builds register and commit what it writes.`;
+      }
+      if (build.deprecated) {
+        return `builds/${id}.json, ${platform}'s build, is deprecated: its users would only be asked to update.`;
+      }
+      if (!isDeepStrictEqual(build.modules, modules)) {
+        return `builds/${id}.json isn't ${platform}'s modules: run backtick-builds register.`;
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * Registers the builds the app at `projectRoot` now makes, one file per id
+ * in its `builds/`, for its server to keep drawing for them once the code
+ * moves on. A build already registered keeps when it was, and whether it's
+ * deprecated. Answers each platform's id and file.
+ */
+export function register(
+  projectRoot: string,
+): { platform: Platform; id: string; file: string }[] {
+  const directory = buildsDirectory(projectRoot);
+  mkdirSync(directory, { recursive: true });
+  return platforms.map((platform) => {
+    const modules = installedModules(projectRoot, platform);
+    const id = buildIdOf(modules);
+    const file = join(directory, `${id}.json`);
+    const recorded: Partial<Build> = existsSync(file)
+      ? JSON.parse(readFileSync(file, "utf8"))
+      : {};
+    const build: Build = {
+      createdAt: recorded.createdAt ?? new Date().toISOString(),
+      deprecated: recorded.deprecated ?? false,
+      modules,
+    };
+    writeFileSync(file, JSON.stringify(build, null, 2) + "\n");
+    return { platform, id, file };
+  });
+}

package/src/cli.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { relative } from "node:path";
+import { createBuilds, register } from "./builds.js";
+import { type Platform, platforms } from "./moduleMap.js";
+
+// `backtick-builds register`: records the builds the app in this directory
+// now makes, to commit. `backtick-builds check`: fails unless they're all
+// registered, as an EAS build's `eas-build-post-install` runs it, checking
+// the platform it builds and letting a development build through.
+const [command] = process.argv.slice(2);
+const projectRoot = process.cwd();
+
+if (command === "register") {
+  for (const { platform, file } of register(projectRoot)) {
+    console.log(`Registered ${platform}: ${relative(projectRoot, file)}`);
+  }
+} else if (command === "check") {
+  if (process.env.EAS_BUILD_PROFILE === "development") {
+    console.log("A development build: its server is this code's.");
+    process.exit(0);
+  }
+  const building = process.env.EAS_BUILD_PLATFORM as Platform | undefined;
+  const builds = createBuilds({ projectRoot });
+  const problems = (building ? [building] : platforms)
+    .map((platform) => builds.unregistered(platform))
+    .filter((problem) => problem !== null);
+  for (const problem of problems) console.error(problem);
+  if (problems.length > 0) process.exit(1);
+  console.log("Every build this code makes is registered.");
+} else {
+  console.error("Usage: backtick-builds register | check");
+  process.exit(1);
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export {
+  type Build,
+  type Builds,
+  buildIds,
+  buildsDirectory,
+  createBuilds,
+  DeprecatedBuild,
+  readBuilds,
+  register,
+  UnknownBuild,
+} from "./builds.js";
+export {
+  moduleMapFile,
+  type Platform,
+  platforms,
+  readModuleMap,
+} from "./moduleMap.js";
+export { buildIdOf, installedModules } from "./modules.js";

package/src/moduleMap.ts

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+/** The platforms an app is built for, each with its own module map. */
+export const platforms = ["ios", "android", "web"] as const;
+export type Platform = (typeof platforms)[number];
+
+// TypeScript, loaded only to read a module map: a server reading registered
+// builds never needs it.
+const require = createRequire(import.meta.url);
+
+/**
+ * The specifiers a module map offers, read from its source without running
+ * it: `export const moduleMap = { … }`, each entry `() => require("…")`, and
+ * nothing else but type imports. Anything more, as a check of the platform,
+ * would make what a build offers something only the device knows, so it
+ * throws, naming the line.
+ */
+export function readModuleMap(file: string): string[] {
+  const ts = require("typescript") as typeof import("typescript");
+  const source = ts.createSourceFile(
+    file,
+    readFileSync(file, "utf8"),
+    ts.ScriptTarget.Latest,
+  );
+  const wrong = (node: import("typescript").Node, what: string) => {
+    const { line } = source.getLineAndCharacterOfPosition(
+      node.getStart(source),
+    );
+    return new Error(`${file}:${line + 1}: ${what}`);
+  };
+  let map: import("typescript").ObjectLiteralExpression | undefined;
+  for (const statement of source.statements) {
+    if (
+      ts.isImportDeclaration(statement) &&
+      statement.importClause?.isTypeOnly
+    ) {
+      continue;
+    }
+    const declaration = ts.isVariableStatement(statement)
+      ? statement.declarationList.declarations[0]
+      : undefined;
+    let value = declaration?.initializer;
+    if (value !== undefined && ts.isSatisfiesExpression(value)) {
+      value = value.expression;
+    }
+    if (
+      map === undefined &&
+      declaration?.name.getText(source) === "moduleMap" &&
+      value !== undefined &&
+      ts.isObjectLiteralExpression(value)
+    ) {
+      map = value;
+      continue;
+    }
+    throw wrong(
+      statement,
+      "a module map holds `export const moduleMap = { … }` and type imports only",
+    );
+  }
+  if (map === undefined) {
+    throw new Error(`${file}: no \`export const moduleMap = { … }\``);
+  }
+  return map.properties.map((property) => {
+    const entry =
+      ts.isPropertyAssignment(property) &&
+      (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+      ts.isArrowFunction(property.initializer) &&
+      property.initializer.parameters.length === 0 &&
+      ts.isCallExpression(property.initializer.body) &&
+      property.initializer.body.expression.getText(source) === "require" &&
+      property.initializer.body.arguments.length === 1 &&
+      ts.isStringLiteral(property.initializer.body.arguments[0]!)
+        ? property.name
+        : undefined;
+    if (entry === undefined) {
+      throw wrong(property, 'each entry is `"specifier": () => require("…")`');
+    }
+    return entry.text;
+  });
+}
+
+/**
+ * The module map Metro picks for `platform` in the app at `projectRoot`, as
+ * it picks any file: `moduleMap.ios.ts` (or `.android`, `.web`), then
+ * `moduleMap.native.ts` off the web, then `moduleMap.ts`.
+ */
+export function moduleMapFile(projectRoot: string, platform: Platform): string {
+  const extensions = [platform, ...(platform === "web" ? [] : ["native"])];
+  for (const extension of [...extensions.map((each) => `.${each}`), ""]) {
+    const file = join(projectRoot, `moduleMap${extension}.ts`);
+    if (existsSync(file)) return file;
+  }
+  throw new Error(`${projectRoot}: no moduleMap.ts`);
+}

package/src/modules.ts

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Modules } from "@backtickjs/bundler";
+import { moduleMapFile, type Platform, readModuleMap } from "./moduleMap.js";
+
+// The package a module specifier is in: `react` for `react/jsx-runtime`.
+function packageOf(specifier: string): string {
+  const segments = specifier.split("/");
+  return segments.slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
+}
+
+// Where a package is installed for the app at `projectRoot`, as Node finds
+// it: in its node_modules, or the nearest above, as a workspace hoists it.
+function installed(projectRoot: string, name: string): string {
+  for (let directory = projectRoot; ; directory = dirname(directory)) {
+    const file = join(directory, "node_modules", name, "package.json");
+    if (existsSync(file)) return file;
+    if (dirname(directory) === directory) {
+      throw new Error(`${projectRoot}: ${name} isn't installed`);
+    }
+  }
+}
+
+/**
+ * The modules the module map for `platform` offers, each at the installed
+ * version of the package it comes from, in the app at `projectRoot`: what a
+ * build made from it now carries there.
+ */
+export function installedModules(
+  projectRoot: string,
+  platform: Platform,
+): Modules {
+  const specifiers = readModuleMap(moduleMapFile(projectRoot, platform));
+  const versions = new Map<string, string>();
+  const versionOf = (name: string) => {
+    let version = versions.get(name);
+    if (version === undefined) {
+      const file = installed(projectRoot, name);
+      version = (JSON.parse(readFileSync(file, "utf8")) as { version: string })
+        .version;
+      versions.set(name, version);
+    }
+    return version;
+  };
+  return Object.fromEntries(
+    [...specifiers]
+      .sort()
+      .map((specifier) => [specifier, versionOf(packageOf(specifier))]),
+  );
+}
+
+/**
+ * The id of a build that carries `modules`: a hash of them, so two builds
+ * that carry the same share it, and a build always names exactly what it
+ * has.
+ */
+export function buildIdOf(modules: Modules): string {
+  const sorted = Object.keys(modules)
+    .sort()
+    .map((specifier) => [specifier, modules[specifier]]);
+  return createHash("sha256")
+    .update(JSON.stringify(sorted))
+    .digest("hex")
+    .slice(0, 16);
+}