@stim-cli/metro 1.0.0-rc.4 → 1.0.0-rc.6

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,7 +1,18 @@
+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;
@@ -19,11 +30,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",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stim-cli/metro",
-  "version": "1.0.0-rc.4",
-  "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.6",
+  "description": "Metro integration for Stim: shared transforms across worktrees and structured logs.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,8 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "@stim-cli/core": "^1.0.0-rc.4"
+    "@stim-cli/cache": "^1.0.0-rc.6",
+    "@stim-cli/core": "^1.0.0-rc.6"
   },
   "peerDependencies": {
     "metro-cache": "*"