@stim-cli/cache-s3 0.0.0 → 1.21.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

@@ -1,3 +1,65 @@
 # @stim-cli/cache-s3
 
-Placeholder used to configure npm trusted publishing. Install a version published with the other Stim packages.
+This opt-in provider owns the AWS SDK and archive dependencies. Installing
+Stim or `@stim-cli/cache` alone does not install it.
+
+If Stim is not installed globally, replace `stim` with `npx stim`.
+
+Install the provider in the project:
+
+```bash
+npm install @stim-cli/cache-s3
+```
+
+Then select it in `.stim.json`:
+
+```json
+{
+  "cache": {
+    "provider": "@stim-cli/cache-s3",
+    "options": {
+      "bucket": "stim-cache",
+      "endpoint": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
+      "region": "auto",
+      "prefix": "team/cache-v1"
+    }
+  }
+}
+```
+
+For AWS S3, omit `endpoint` and use the bucket's region. Other S3-compatible
+services can set `forcePathStyle: true` when required. Credentials use the AWS
+SDK's standard credential chain. For a named profile in `~/.aws/credentials`,
+set `cache.options.profile` to `stim-r2`, or run commands with
+`AWS_PROFILE=stim-r2`, for example `AWS_PROFILE=stim-r2 stim ios`. An explicit
+cache profile overrides the ambient AWS profile. Credentials never belong in `.stim.json`.
+
+Create a private R2 bucket and an R2 API token with Object Read & Write access
+scoped to that bucket. Copy the S3 endpoint shown by Cloudflare; jurisdiction
+specific buckets use their own endpoint. See the
+[R2 S3 setup guide](https://developers.cloudflare.com/r2/get-started/s3/).
+
+The provider shares completed native `.app`/`.apk` artifacts and Metro values
+through one file transport. Stim checks its local tier first and promotes build
+hits locally. Build archives preserve file modes and contained framework links;
+downloads verify SHA-256 before becoming reusable. Conditional writes preserve
+existing build entries unless overwrite was requested. Use matching native
+toolchains for the initial test; the provider does not add toolchain information
+to Stim's existing build key.
+
+The file transport is also exported as `createS3FileCache()` from
+`@stim-cli/cache-s3`, with the `FileCacheCapability` interface exported from
+`@stim-cli/cache`. A cache adapter supplies a compatible key and a completed
+file, then owns the downloaded file inside its destination directory. This
+also lets native Gradle artifact caching share the completed APK and verification
+receipt through this transport when `android.artifactInputs` is declared. Private
+input files and environment values stay local. Other Stim home directories are
+not automatically synchronized.
+
+Objects use `<prefix>/builds/<platform>/<key>` and
+`<prefix>/metro/<cacheName>/<hex-key>`. Native Gradle APKs use
+`<prefix>/native-android/v1/<key>`. A prefix defaults to `stim/v1`. Keep
+incompatible snapshot formats in separate key namespaces. Retention belongs to
+the bucket lifecycle configuration; local GC never removes shared objects.
+Uploads use a single S3 PUT, so entries larger than S3's 5 GiB limit are not
+supported by this initial provider.

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+import { CACHE_PROVIDER_API_VERSION, CacheProvider, FileCacheCapability } from "@stim-cli/cache";
+//#region index.d.ts
+declare const apiVersion: typeof CACHE_PROVIDER_API_VERSION;
+interface S3FileCacheOptions {
+  bucket: string;
+  prefix?: string | undefined;
+  endpoint?: string | undefined;
+  region?: string | undefined;
+  profile?: string | undefined;
+  forcePathStyle?: boolean | undefined;
+}
+/** Stores opaque files; each cache adapter owns its key and serialization. Credentials use the AWS SDK chain. */
+declare function createS3FileCache(options: S3FileCacheOptions): FileCacheCapability & Required<Pick<FileCacheCapability, "stat">>;
+declare function createCacheProvider({ options }: {
+  projectRoot: string;
+  options: Record<string, unknown>;
+}): CacheProvider;
+//#endregion
+export { S3FileCacheOptions, apiVersion, createCacheProvider, createS3FileCache };

package/dist/index.mjs

@@ -0,0 +1,238 @@
+import { GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { deserialize, serialize } from "node:v8";
+import { create, extract } from "tar";
+import { CACHE_PROVIDER_API_VERSION } from "@stim-cli/cache";
+//#region index.ts
+const apiVersion = CACHE_PROVIDER_API_VERSION;
+async function fileDigests(path, signal) {
+	const sha256 = createHash("sha256");
+	const md5 = createHash("md5");
+	for await (const chunk of createReadStream(path, { signal })) {
+		sha256.update(chunk);
+		md5.update(chunk);
+	}
+	return {
+		sha256: sha256.digest("hex"),
+		md5: md5.digest("base64")
+	};
+}
+function status(error) {
+	if (!error || typeof error !== "object" || !("$metadata" in error)) return void 0;
+	const metadata = error.$metadata;
+	if (!metadata || typeof metadata !== "object" || !("httpStatusCode" in metadata)) return void 0;
+	return typeof metadata.httpStatusCode === "number" ? metadata.httpStatusCode : void 0;
+}
+/** Stores opaque files; each cache adapter owns its key and serialization. Credentials use the AWS SDK chain. */
+function createS3FileCache(options) {
+	if (!options.bucket) throw new Error("The S3 cache needs a bucket.");
+	const config = {
+		...options.endpoint !== void 0 ? { endpoint: options.endpoint } : {},
+		region: options.region ?? "us-east-1",
+		...options.profile !== void 0 ? { profile: options.profile } : {},
+		...options.forcePathStyle !== void 0 ? { forcePathStyle: options.forcePathStyle } : {},
+		requestChecksumCalculation: "WHEN_REQUIRED",
+		responseChecksumValidation: "WHEN_REQUIRED",
+		logger: {
+			debug() {},
+			info() {},
+			warn() {},
+			error() {}
+		}
+	};
+	const client = new S3Client(config);
+	const prefix = (options.prefix ?? "stim/v1").replace(/^\/+|\/+$/g, "");
+	const objectKey = (key) => `${prefix}/${key}`;
+	return {
+		async stat({ key, signal }) {
+			signal.throwIfAborted();
+			try {
+				const object = await client.send(new HeadObjectCommand({
+					Bucket: options.bucket,
+					Key: objectKey(key)
+				}), { abortSignal: signal });
+				return typeof object.ContentLength === "number" ? { size: object.ContentLength } : null;
+			} catch (error) {
+				if (status(error) === 404) return null;
+				throw error;
+			}
+		},
+		async resolve({ key, destinationDir, signal }) {
+			signal.throwIfAborted();
+			let object;
+			try {
+				object = await client.send(new GetObjectCommand({
+					Bucket: options.bucket,
+					Key: objectKey(key)
+				}), { abortSignal: signal });
+			} catch (error) {
+				if (status(error) === 404) return null;
+				throw error;
+			}
+			const expected = object.Metadata?.sha256;
+			if (!(object.Body instanceof Readable) || !expected || !/^[a-f0-9]{64}$/.test(expected)) {
+				if (object.Body instanceof Readable) object.Body.destroy();
+				throw new Error("The S3 cache entry has no SHA-256 metadata.");
+			}
+			const temporary = join(destinationDir, `${randomUUID()}.partial`);
+			const complete = join(destinationDir, `${randomUUID()}.cache`);
+			const digest = createHash("sha256");
+			try {
+				await mkdir(destinationDir, { recursive: true });
+				await pipeline(object.Body, new Transform({ transform(chunk, _encoding, callback) {
+					digest.update(chunk);
+					callback(null, chunk);
+				} }), createWriteStream(temporary, { flags: "wx" }), { signal });
+				if (digest.digest("hex") !== expected) throw new Error("The S3 cache entry failed SHA-256 verification.");
+				signal.throwIfAborted();
+				await rename(temporary, complete);
+				return complete;
+			} finally {
+				object.Body.destroy();
+				await rm(temporary, { force: true });
+			}
+		},
+		async store({ key, sourcePath, overwrite, signal }) {
+			signal.throwIfAborted();
+			const digests = await fileDigests(sourcePath, signal);
+			const body = createReadStream(sourcePath, { signal });
+			try {
+				await client.send(new PutObjectCommand({
+					Bucket: options.bucket,
+					Key: objectKey(key),
+					Body: body,
+					ContentLength: (await stat(sourcePath)).size,
+					ContentMD5: digests.md5,
+					Metadata: { sha256: digests.sha256 },
+					IfNoneMatch: overwrite ? void 0 : "*"
+				}), { abortSignal: signal });
+			} catch (error) {
+				if (overwrite || status(error) !== 412) throw error;
+			} finally {
+				body.destroy();
+			}
+		}
+	};
+}
+async function scratch(run) {
+	const dir = await mkdtemp(join(tmpdir(), "stim-s3-cache-"));
+	try {
+		return await run(dir);
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function createCacheProvider({ options }) {
+	const files = createS3FileCache({
+		bucket: typeof options.bucket === "string" ? options.bucket : "",
+		prefix: typeof options.prefix === "string" ? options.prefix : void 0,
+		endpoint: typeof options.endpoint === "string" ? options.endpoint : void 0,
+		region: typeof options.region === "string" ? options.region : void 0,
+		profile: typeof options.profile === "string" ? options.profile : void 0,
+		forcePathStyle: typeof options.forcePathStyle === "boolean" ? options.forcePathStyle : void 0
+	});
+	return {
+		files,
+		builds: {
+			async resolve({ platform, key, destinationDir, signal }) {
+				return scratch(async (dir) => {
+					const archive = await files.resolve({
+						key: `builds/${platform}/${key}`,
+						destinationDir: dir,
+						signal
+					});
+					if (!archive) return null;
+					const staging = await mkdtemp(join(destinationDir, "s3-"));
+					try {
+						let invalidLink = false;
+						await pipeline(createReadStream(archive), extract({
+							cwd: staging,
+							strict: true,
+							filter(path, entry) {
+								if (!("type" in entry)) return true;
+								if (entry.type !== "SymbolicLink" && entry.type !== "Link") return true;
+								const link = entry.linkpath ?? "";
+								const target = resolve(staging, entry.type === "SymbolicLink" ? dirname(path) : "", link);
+								const root = relative(staging, resolve(staging, path)).split(sep)[0];
+								const outside = relative(resolve(staging, root ?? ""), target);
+								if (isAbsolute(link) || outside === ".." || outside.startsWith(`..${sep}`)) {
+									invalidLink = true;
+									return false;
+								}
+								return true;
+							}
+						}), { signal });
+						if (invalidLink) throw new Error("The S3 build entry contains a link outside the artifact.");
+						signal.throwIfAborted();
+						const entries = await readdir(staging);
+						const [entry] = entries;
+						if (entries.length !== 1 || entry === void 0) throw new Error("The S3 build entry must contain one artifact.");
+						const path = join(staging, entry);
+						const info = await lstat(path);
+						if (platform === "ios" ? !info.isDirectory() || !path.endsWith(".app") : !info.isFile() || !path.endsWith(".apk")) throw new Error("The S3 build entry has the wrong artifact type.");
+						return path;
+					} catch (error) {
+						await rm(staging, {
+							recursive: true,
+							force: true
+						});
+						throw error;
+					}
+				});
+			},
+			async store({ platform, key, sourcePath, overwrite, signal }) {
+				await scratch(async (dir) => {
+					signal.throwIfAborted();
+					const archive = join(dir, "artifact.tar");
+					await pipeline(create({
+						cwd: dirname(sourcePath),
+						portable: true
+					}, [basename(sourcePath)]), createWriteStream(archive, { flags: "wx" }), { signal });
+					signal.throwIfAborted();
+					await files.store({
+						key: `builds/${platform}/${key}`,
+						sourcePath: archive,
+						overwrite,
+						signal
+					});
+				});
+			}
+		},
+		metro: {
+			async get({ cacheName, key, signal }) {
+				return scratch(async (dir) => {
+					const path = await files.resolve({
+						key: `metro/${encodeURIComponent(cacheName)}/${key.toString("hex")}`,
+						destinationDir: dir,
+						signal
+					});
+					if (!path) return null;
+					return deserialize(await readFile(path, { signal }));
+				});
+			},
+			async set({ cacheName, key, value, signal }) {
+				await scratch(async (dir) => {
+					const path = join(dir, "transform");
+					await writeFile(path, serialize(value), { signal });
+					await files.store({
+						key: `metro/${encodeURIComponent(cacheName)}/${key.toString("hex")}`,
+						sourcePath: path,
+						overwrite: true,
+						signal
+					});
+				});
+			}
+		}
+	};
+}
+//#endregion
+export { apiVersion, createCacheProvider, createS3FileCache };

package/package.json

@@ -1,11 +1,37 @@
 {
   "name": "@stim-cli/cache-s3",
-  "version": "0.0.0",
-  "description": "Placeholder. The first real version is published by the Stim release workflow.",
+  "version": "1.21.0",
+  "description": "Optional S3-compatible file, native artifact and Metro cache provider for Stim.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/appandflow/stim.git",
     "directory": "packages/cache-s3"
+  },
+  "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": {
+    "@aws-sdk/client-s3": "^3.1149.0",
+    "@stim-cli/cache": "^1.21.0",
+    "tar": "^7.5.22"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown"
   }
-}
+}