@stim-cli/metro 1.0.0-rc.2 → 1.0.0-rc.20

package/README.md

@@ -1,91 +1,59 @@
 # @stim-cli/metro
 
-> Commands use `stim`. If it is not installed globally, replace `stim` with
-> `npx stim-cli`.
+Optional Metro integration for Stim. It exports a transform cache shared across
+worktrees and an NDJSON reporter for structured Metro and client logs.
 
-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.
+If Stim is not installed globally, replace `stim` with `npx stim-cli`.
 
 ```bash
-npm i -D @stim-cli/metro
+npm install --save-dev @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.
+## Shared transforms
 
 ```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
+config.cacheStores = sharedCacheStores('my-app');
 ```
 
-Entries are trimmed individually — one file per cache key — so trimming costs
-only the entries nothing has touched, not the whole cache.
+Set `STIM_METRO_CACHE` to override the shared cache location.
 
-stim-cli is an optional peer. Without it the cache works exactly the same; it is
-just invisible to housekeeping.
+## Optional second tier
 
-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.
+The filesystem cache above is always the first tier. When the project selects a
+cache provider, the exported store reads it after a local miss, writes provider
+hits back to the filesystem, and queues new transforms for the provider without
+blocking Metro. Provider failures are misses.
 
-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.
+```json
+{
+  "cache": {
+    "provider": "./tools/cache-provider.cjs",
+    "options": { "bucket": "mobile-cache" }
+  }
+}
+```
 
-## The NDJSON log reporter
+Under `stim start` the supervisor passes the resolved selection to Metro. A
+Metro process outside Stim reads the nearest committed `.stim.json`. See
+[`@stim-cli/cache`](https://www.npmjs.com/package/@stim-cli/cache) for the
+provider contract. `clear()` only clears the local tier.
 
-`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`.
+## Log reporter
 
 ```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 });
+config.reporter = ndjsonReporter({ dir: '/absolute/log/directory' });
 ```
 
-**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.
+The reporter must be attached to the config passed directly to
+`Metro.runServer`. React Native and Expo CLIs can replace a reporter declared in
+`metro.config.js`.
+
+Stim supplies this integration automatically for Stim-managed servers. Add the
+package directly only for Metro processes that run outside Stim.
+
+See the [cache package documentation](https://appandflow.github.io/stim/docs/cache-packages)
+for current usage and cleanup guidance.

package/dist/index.d.mts

@@ -1,13 +1,25 @@
+import { CacheProviderConfig, LoadCacheProviderResult, WarnOnce } from "@stim-cli/cache";
 //#region index.d.ts
 type FileStoreCtor = new (options: {
   root: string;
 }) => object;
+interface SharedCacheStoresOptions {
+  FileStore?: FileStoreCtor;
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+  loadProvider?: (input: {
+    projectRoot: string;
+    config: CacheProviderConfig;
+  }) => Promise<LoadCacheProviderResult>;
+  warn?: WarnOnce;
+}
 interface MetroEvent {
   type?: string;
   level?: unknown;
   data?: unknown;
   error?: unknown;
-  stack?: string;
+  stack?: unknown;
+  codeFrame?: unknown;
   buildID?: string;
   bundleDetails?: {
     platform?: string | null;
@@ -19,11 +31,9 @@ interface NdjsonReporter {
   readonly drops: number;
 }
 declare function cacheRoot(name?: string | null): string;
-declare function sharedCacheStores(name?: string, { FileStore }?: {
-  FileStore?: FileStoreCtor;
-}): object[];
+declare function sharedCacheStores(name?: string, { FileStore, env, cwd, loadProvider, warn }?: SharedCacheStoresOptions): object[];
 declare function ndjsonReporter({ dir }?: {
   dir?: string;
 }): NdjsonReporter;
 //#endregion
-export { NdjsonReporter, cacheRoot, ndjsonReporter, sharedCacheStores };
+export { NdjsonReporter, SharedCacheStoresOptions, cacheRoot, ndjsonReporter, sharedCacheStores };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import fs from "node:fs";
 import path from "node:path";
+import { cacheProviderConfigFromEnv, cacheProviderEnvIsSet, createTieredMetroStore, loadCacheProvider } from "@stim-cli/cache";
 import { METRO_NAMED_CACHE_LAYOUT, metroCacheRoot, registerCache, tagSharedStore, workspaceLogDir } from "@stim-cli/core";
 //#region index.ts
 const requireFromHere = createRequire(import.meta.url);
@@ -18,7 +19,45 @@ function registerOnce(dir, replaces = []) {
 		replaces
 	});
 }
-function sharedCacheStores(name = "app", { FileStore } = {}) {
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function repositoryRoot(startDir) {
+	let dir = startDir;
+	for (;;) {
+		if (fs.existsSync(path.join(dir, ".git"))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+function committedProviderConfig(startDir) {
+	const start = path.resolve(startDir);
+	const stop = repositoryRoot(start) ?? start;
+	let dir = start;
+	for (;;) {
+		let parsed;
+		try {
+			parsed = JSON.parse(fs.readFileSync(path.join(dir, ".stim.json"), "utf-8"));
+		} catch {
+			parsed = null;
+		}
+		const cache = isPlainObject(parsed) && isPlainObject(parsed.cache) ? parsed.cache : null;
+		const reference = cache?.provider;
+		if (typeof reference === "string" && reference.trim() !== "") return {
+			provider: reference.trim(),
+			options: isPlainObject(cache?.options) ? cache.options : {},
+			baseDir: dir
+		};
+		const parent = path.dirname(dir);
+		if (dir === stop || parent === dir) return null;
+		dir = parent;
+	}
+}
+function warnToStderr(_code, message) {
+	process.stderr.write(`warning: ${message}\n`);
+}
+function sharedCacheStores(name = "app", { FileStore, env = process.env, cwd = process.cwd(), loadProvider = loadCacheProvider, warn = warnToStderr } = {}) {
 	const Store = FileStore || requireFromHere("metro-cache").FileStore;
 	const parent = cacheRoot();
 	const root = cacheRoot(name);
@@ -29,7 +68,20 @@ function sharedCacheStores(name = "app", { FileStore } = {}) {
 		entriesDepth: 2,
 		layout: null
 	}]);
-	return [tagSharedStore(new Store({ root }), root)];
+	const local = tagSharedStore(new Store({ root }), root);
+	const config = cacheProviderConfigFromEnv(env) ?? (cacheProviderEnvIsSet(env) ? null : committedProviderConfig(cwd));
+	if (!config) return [local];
+	const tiered = createTieredMetroStore({
+		local,
+		projectRoot: path.resolve(cwd),
+		cacheName: name,
+		loadProvider: () => loadProvider({
+			projectRoot: path.resolve(cwd),
+			config
+		}),
+		warn
+	});
+	return [tagSharedStore(tiered, root)];
 }
 const NDJSON_LEVELS = /* @__PURE__ */ new Set([
 	"debug",
@@ -77,6 +129,23 @@ function errorMessage(error) {
 	if (typeof error.message === "string" && error.message) return error.message;
 	return formatValue(error);
 }
+function symbolicationMessage(codeFrame) {
+	if (!isPlainObject(codeFrame) || typeof codeFrame.content !== "string") return "Call Stack";
+	const fileName = typeof codeFrame.fileName === "string" ? codeFrame.fileName : "unknown source";
+	const location = isPlainObject(codeFrame.location) ? codeFrame.location : null;
+	return `Code: ${fileName}${typeof location?.row === "number" ? `:${location.row}` : ""}${typeof location?.column === "number" ? `:${location.column}` : ""}\n${codeFrame.content}\nCall Stack`;
+}
+function symbolicationStack(stack) {
+	if (!Array.isArray(stack)) return [];
+	return stack.filter((frame) => isPlainObject(frame) && frame.collapse !== true).map((frame) => {
+		const normalized = {};
+		if (typeof frame.file === "string") normalized.file = frame.file;
+		if (typeof frame.lineNumber === "number") normalized.line = frame.lineNumber;
+		if (typeof frame.column === "number") normalized.column = frame.column;
+		if (typeof frame.methodName === "string") normalized.fn = frame.methodName;
+		return normalized;
+	}).filter((frame) => Object.keys(frame).length > 0);
+}
 function ndjsonReporter({ dir } = {}) {
 	const logDir = dir || workspaceLogDir(process.cwd());
 	let ensured = false;
@@ -133,6 +202,16 @@ function ndjsonReporter({ dir } = {}) {
 				write("client.ndjson", record);
 				return;
 			}
+			if (type === "client_symbolication") {
+				const stack = symbolicationStack(event.stack);
+				if (!(isPlainObject(event.codeFrame) && typeof event.codeFrame.content === "string") && stack.length === 0) return;
+				record.src = "client";
+				record.level = "info";
+				record.msg = symbolicationMessage(event.codeFrame);
+				if (stack.length > 0) record.stack = stack;
+				write("client.ndjson", record);
+				return;
+			}
 			if (type === "bundling_error" || type === "transformer_error") {
 				record.level = "error";
 				record.msg = errorMessage(event.error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stim-cli/metro",
-  "version": "1.0.0-rc.2",
-  "description": "Metro integration for stim-cli: one transform cache shared by every worktree, plus an NDJSON reporter for structured logs.",
+  "version": "1.0.0-rc.20",
+  "description": "Metro integration for Stim: shared transforms across worktrees and structured logs.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,17 +23,18 @@
       "default": "./dist/index.mjs"
     }
   },
-  "scripts": {
-    "test": "node --test test/*.test.js",
-    "build": "tsdown"
-  },
   "dependencies": {
-    "@stim-cli/core": "^1.0.0-rc.2"
+    "@stim-cli/cache": "^1.0.0-rc.20",
+    "@stim-cli/core": "^1.0.0-rc.20"
   },
   "peerDependencies": {
     "metro-cache": "*"
   },
   "engines": {
     "node": "^20.19.4 || >=22.12.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "build": "tsdown"
   }
-}
+}