@stim-cli/metro 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janic Duplessis
+
+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,91 @@
+# @stim-cli/metro
+
+> Commands use `stim`. If it is not installed globally, replace `stim` with
+> `npx stim-cli`.
+
+The two things [`stim-cli`](https://www.npmjs.com/package/stim-cli) wires into
+Metro: one transform cache shared by every worktree on the machine, and a
+reporter that writes the dev server's events as NDJSON.
+
+```bash
+npm i -D @stim-cli/metro
+```
+
+## The shared transform cache
+
+Metro's default cache lives under the project, so a second worktree starts cold
+and re-transforms the whole module graph — thousands of modules, every time.
+Pointing every checkout at one store means only the first one pays.
+
+```js
+// metro.config.js
+const { sharedCacheStores } = require('@stim-cli/metro');
+
+const config = getDefaultConfig(__dirname);
+config.cacheStores = sharedCacheStores('myapp');
+module.exports = config;
+```
+
+The `FileStore` itself is six lines; what this packages is the housekeeping.
+**Metro's cache has no eviction logic whatsoever**, so left alone it grows until
+the disk does. Registering it with
+[`stim-cli`](https://www.npmjs.com/package/stim-cli) makes it visible:
+
+```bash
+stim gc                            # what it has grown to (reported on every run)
+stim gc --delete --older-than 30   # drop entries unused for 30 days
+```
+
+Entries are trimmed individually — one file per cache key — so trimming costs
+only the entries nothing has touched, not the whole cache.
+
+stim-cli is an optional peer. Without it the cache works exactly the same; it is
+just invisible to housekeeping.
+
+The parent location can be overridden by `STIM_CLI_METRO_CACHE`, or
+machine-wide by `caches.metroCache` in `~/.stim-cli/config.json` (an absolute
+path; the env var wins). The sanitized name passed to `sharedCacheStores` is
+always appended below that parent, so `sharedCacheStores('@scope/app')` uses
+`<parent>/-scope-app`. The CLI and this package resolve both identically.
+
+Earlier versions wrote a named store directly into an overridden parent. A new
+registration marks the named layout and replaces an exact unmarked legacy
+parent entry. If an older package registers the parent again later, current
+`stim gc` ignores that provably legacy entry while a marked child is
+registered, so it cannot prune the child at the wrong depth. A marked named
+store that later becomes another override parent remains visible but report-only
+while its marked child exists. The old root-level cache files are left untouched
+for manual cleanup.
+
+## The NDJSON log reporter
+
+`ndjsonReporter({ dir })` is a Metro `Reporter` that writes every event the dev
+server emits as one JSON object per line: bundler events and transform failures
+into `<dir>/metro.ndjson`, forwarded in-app console logs and redboxes into
+`<dir>/client.ndjson`.
+
+```js
+const { ndjsonReporter } = require('@stim-cli/metro');
+
+config.reporter = ndjsonReporter({
+  dir: '~/.stim-cli/workspaces/my-app--<16hex-path-digest>/logs',
+});
+await Metro.runServer(config, { host, port });
+```
+
+**It only survives when you host Metro yourself.** Both the Expo CLI and the
+React Native CLI overwrite `config.reporter` after loading `metro.config.js`, so
+a reporter set there is discarded without a word. Setting it on a config you
+pass to `Metro.runServer` is the path that works, and it is how `stim start`
+captures a bare React Native project's logs.
+
+Each record is `{ ts, src, level, msg }` plus, when they apply, `event` (the
+Metro event name), `stack` (passed through as Metro gave it) and `marker: true`
+(written on a finished bundle build, which is what `stim logs --errors` counts
+errors from). When used by stim-cli, `dir` defaults to
+`$STIM_CLI_HOME/workspaces/<readable-project-slug>--<16hex-path-digest>/logs`
+(by default `~/.stim-cli/workspaces/...`), outside the working directory.
+
+A logging failure is never a server failure: an unwritable directory or an event
+shape from a Metro version this package has never seen is counted on
+`reporter.drops` and swallowed, not thrown into Metro's build pipeline.

package/dist/index.d.mts

@@ -0,0 +1,26 @@
+//#region index.d.ts
+type FileStoreCtor = new (options: {
+  root: string;
+}) => object;
+interface MetroEvent {
+  type?: string;
+  level?: unknown;
+  data?: unknown;
+  error?: unknown;
+  stack?: string;
+  buildID?: string;
+}
+interface NdjsonReporter {
+  dir: string;
+  update(event: MetroEvent): void;
+  readonly drops: number;
+}
+declare function cacheRoot(name?: string | null): string;
+declare function sharedCacheStores(name?: string, { FileStore }?: {
+  FileStore?: FileStoreCtor;
+}): object[];
+declare function ndjsonReporter({ dir }?: {
+  dir?: string;
+}): NdjsonReporter;
+//#endregion
+export { NdjsonReporter, cacheRoot, ndjsonReporter, sharedCacheStores };

package/dist/index.mjs

@@ -0,0 +1,140 @@
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { METRO_NAMED_CACHE_LAYOUT, metroCacheRoot, registerCache, tagSharedStore, workspaceLogDir } from "@stim-cli/core";
+//#region index.ts
+const requireFromHere = createRequire(import.meta.url);
+function cacheRoot(name) {
+	return metroCacheRoot(name);
+}
+function registerOnce(dir, replaces = []) {
+	registerCache({
+		dir,
+		name: "Metro transform cache",
+		prune: "entries",
+		entriesDepth: 2,
+		layout: METRO_NAMED_CACHE_LAYOUT,
+		note: "shared Metro transforms; no eviction of its own",
+		replaces
+	});
+}
+function sharedCacheStores(name = "app", { FileStore } = {}) {
+	const Store = FileStore || requireFromHere("metro-cache").FileStore;
+	const parent = cacheRoot();
+	const root = cacheRoot(name);
+	registerOnce(root, root === parent ? [] : [{
+		dir: parent,
+		name: "Metro transform cache",
+		prune: "entries",
+		entriesDepth: 2,
+		layout: null
+	}]);
+	return [tagSharedStore(new Store({ root }), root)];
+}
+const NDJSON_LEVELS = /* @__PURE__ */ new Set([
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal"
+]);
+function ndjsonLevel(level, fallback) {
+	const value = String(level === void 0 || level === null ? "" : level).toLowerCase();
+	if (NDJSON_LEVELS.has(value)) return value;
+	switch (value) {
+		case "log":
+		case "dir":
+		case "table":
+		case "group":
+		case "groupcollapsed":
+		case "groupend": return "info";
+		case "trace": return "debug";
+		case "warning": return "warn";
+		default: return fallback;
+	}
+}
+function formatValue(value) {
+	if (typeof value === "string") return value;
+	if (value instanceof Error) return value.message || String(value);
+	try {
+		const json = JSON.stringify(value);
+		if (json !== void 0) return json;
+	} catch {}
+	try {
+		return String(value);
+	} catch {
+		return "[unprintable]";
+	}
+}
+function formatData(data) {
+	if (data === void 0 || data === null) return "";
+	if (Array.isArray(data)) return data.map(formatValue).join(" ");
+	return formatValue(data);
+}
+function errorMessage(error) {
+	if (error === void 0 || error === null) return "unknown error";
+	if (typeof error === "string") return error;
+	if (typeof error.message === "string" && error.message) return error.message;
+	return formatValue(error);
+}
+function ndjsonReporter({ dir } = {}) {
+	const logDir = dir || workspaceLogDir(process.cwd());
+	let ensured = false;
+	let drops = 0;
+	function write(file, record) {
+		try {
+			if (!ensured) {
+				fs.mkdirSync(logDir, { recursive: true });
+				ensured = true;
+			}
+			fs.appendFileSync(path.join(logDir, file), JSON.stringify(record) + "\n");
+		} catch {
+			drops += 1;
+			ensured = false;
+		}
+	}
+	function update(event) {
+		try {
+			const type = event && typeof event.type === "string" ? event.type : "";
+			const record = {
+				ts: Date.now(),
+				src: "metro",
+				level: "debug",
+				msg: ""
+			};
+			if (type) record.event = type;
+			if (type === "client_log") {
+				record.src = "client";
+				record.level = ndjsonLevel(event.level, "info");
+				record.msg = formatData(event.data);
+				if (event.stack) record.stack = event.stack;
+				write("client.ndjson", record);
+				return;
+			}
+			if (type === "bundling_error" || type === "transformer_error") {
+				record.level = "error";
+				record.msg = errorMessage(event.error);
+			} else if (type === "bundle_build_done" || type === "bundle_build_failed") {
+				const what = type === "bundle_build_done" ? "bundle build done" : "bundle build failed";
+				record.level = "info";
+				record.msg = event.buildID ? `${what} (${event.buildID})` : what;
+				record.marker = true;
+			} else if (type === "unstable_server_log") {
+				record.level = ndjsonLevel(event.level, "info");
+				record.msg = formatData(event.data);
+			} else record.msg = formatData(event && event.data) || type || "metro event";
+			write("metro.ndjson", record);
+		} catch {
+			drops += 1;
+		}
+	}
+	return {
+		dir: logDir,
+		update,
+		get drops() {
+			return drops;
+		}
+	};
+}
+//#endregion
+export { cacheRoot, ndjsonReporter, sharedCacheStores };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@stim-cli/metro",
+  "version": "1.0.0-rc.0",
+  "description": "Metro integration for stim-cli: one transform cache shared by every worktree, plus an NDJSON reporter for structured logs.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appandflow/stim-cli.git",
+    "directory": "packages/metro"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "module-sync": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@stim-cli/core": "^1.0.0-rc.0"
+  },
+  "peerDependencies": {
+    "metro-cache": "*"
+  },
+  "engines": {
+    "node": "^20.19.4 || >=22.12.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "build": "tsdown"
+  }
+}