The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { dotAlchemyDirectory } from "alchemy/AlchemyContext"; |
| 2 | import { isPathWithin } from "alchemy/Util/isPathWithin"; |
| 3 | import * as Data from "effect/Data"; |
| 4 | import * as Effect from "effect/Effect"; |
| 5 | import * as FileSystem from "effect/FileSystem"; |
| 6 | import * as Path from "effect/Path"; |
| 7 | import type { PlatformError } from "effect/PlatformError"; |
| 8 | import { |
| 9 | isArchivedRegularFile, |
| 10 | readDirectoryEntriesSecure, |
| 11 | writeCompressedArchiveSecure, |
| 12 | type ArchiveTarEntry, |
| 13 | } from "./internal/ArchivePlatform.ts"; |
| 14 | import { |
| 15 | inspectArtifactFile, |
| 16 | inspectVerifiedFile, |
| 17 | readArtifactFile, |
| 18 | type ArtifactFile, |
| 19 | } from "./internal/ArtifactFile.ts"; |
| 20 | |
| 21 | export class ComputeArchiveInvalidProps extends Data.TaggedError("ComputeArchiveInvalidProps")<{ |
| 22 | readonly message: string; |
| 23 | readonly cause?: unknown; |
| 24 | }> {} |
| 25 | |
| 26 | export class ComputeArchiveOperationFailed extends Data.TaggedError( |
| 27 | "ComputeArchiveOperationFailed", |
| 28 | )<{ |
| 29 | readonly message: string; |
| 30 | readonly cause?: unknown; |
| 31 | }> {} |
| 32 | |
| 33 | export const COMPUTE_MANIFEST_VERSION = "1"; |
| 34 | |
| 35 | const MAX_UNCOMPRESSED_BYTES = 768 * 1024 * 1024; |
| 36 | const MAX_FILE_BYTES = 128 * 1024 * 1024; |
| 37 | const MAX_ENTRIES = 50_000; |
| 38 | const MAX_COMPRESSED_BYTES = 768 * 1024 * 1024; |
| 39 | |
| 40 | export interface ComputeArchiveOptions { |
| 41 | /** |
| 42 | * Directory whose files should be uploaded as the compute bundle. |
| 43 | */ |
| 44 | directory: string; |
| 45 | /** |
| 46 | * Entrypoint relative to `directory`. |
| 47 | */ |
| 48 | entrypoint: string; |
| 49 | /** |
| 50 | * Additional artifact-relative paths to exclude. Patterns support `*` and |
| 51 | * `**`; directory matches exclude their complete subtree. Absolute paths, |
| 52 | * parent (`..`) segments, and negated patterns are rejected. Sensitive |
| 53 | * Alchemy, Git, and dotenv files are always excluded. |
| 54 | */ |
| 55 | ignore?: readonly string[]; |
| 56 | /** |
| 57 | * Artifact-relative prefix applied to custom ignore patterns after they are |
| 58 | * validated. |
| 59 | */ |
| 60 | ignorePrefix?: string; |
| 61 | /** |
| 62 | * Artifact-relative files that must remain present after exclusions. |
| 63 | */ |
| 64 | requiredFiles?: readonly string[]; |
| 65 | /** |
| 66 | * Maximum uncompressed bytes accepted across all archived files. Values |
| 67 | * above the provider's 768 MiB hard ceiling are rejected. |
| 68 | * |
| 69 | * @default 805306368 (768 MiB) |
| 70 | */ |
| 71 | maxUncompressedBytes?: number; |
| 72 | /** |
| 73 | * Maximum bytes accepted for one archived file. Values above the provider's |
| 74 | * 128 MiB hard ceiling are rejected. |
| 75 | * |
| 76 | * @default 134217728 (128 MiB) |
| 77 | */ |
| 78 | maxFileBytes?: number; |
| 79 | /** |
| 80 | * Maximum number of filesystem entries accepted in an artifact. Values |
| 81 | * above the provider's 50,000-entry hard ceiling are rejected. |
| 82 | * |
| 83 | * @default 50000 |
| 84 | */ |
| 85 | maxEntries?: number; |
| 86 | /** |
| 87 | * Return a verified, file-backed archive instead of materializing the final |
| 88 | * compressed bytes. The caller must run the returned `cleanup` Effect. |
| 89 | * |
| 90 | * @default "bytes" |
| 91 | */ |
| 92 | output?: "bytes" | "file"; |
| 93 | } |
| 94 | |
| 95 | const ALWAYS_IGNORED_PATTERNS = [ |
| 96 | ".git", |
| 97 | "**/.git", |
| 98 | ".alchemy", |
| 99 | "**/.alchemy", |
| 100 | ".env", |
| 101 | "**/.env", |
| 102 | ".env.*", |
| 103 | "**/.env.*", |
| 104 | ".envrc", |
| 105 | "**/.envrc", |
| 106 | ".npmrc", |
| 107 | "**/.npmrc", |
| 108 | ".yarnrc*", |
| 109 | "**/.yarnrc*", |
| 110 | ".netrc", |
| 111 | "**/.netrc", |
| 112 | ".pypirc", |
| 113 | "**/.pypirc", |
| 114 | ".aws", |
| 115 | "**/.aws", |
| 116 | ".ssh", |
| 117 | "**/.ssh", |
| 118 | ] as const; |
| 119 | |
| 120 | interface ArchiveBudget { |
| 121 | readonly ignore: readonly RegExp[]; |
| 122 | readonly maxUncompressedBytes: number; |
| 123 | readonly maxFileBytes: number; |
| 124 | readonly maxEntries: number; |
| 125 | bytes: number; |
| 126 | entries: number; |
| 127 | } |
| 128 | |
| 129 | export class ComputeArchiveOptionsError extends Data.TaggedError("ComputeArchiveOptionsError")<{ |
| 130 | readonly message: string; |
| 131 | readonly cause?: unknown; |
| 132 | }> {} |
| 133 | |
| 134 | type ArchiveError = PlatformError | Error; |
| 135 | type ArchiveRequirements = FileSystem.FileSystem | Path.Path; |
| 136 | |
| 137 | export function createComputeArchive( |
| 138 | options: ComputeArchiveOptions & { readonly output: "file" }, |
| 139 | ): Effect.Effect<ArtifactFile, ArchiveError, ArchiveRequirements>; |
| 140 | export function createComputeArchive( |
| 141 | options: ComputeArchiveOptions & { readonly output?: "bytes" }, |
| 142 | ): Effect.Effect<Uint8Array, ArchiveError, ArchiveRequirements>; |
| 143 | export function createComputeArchive( |
| 144 | options: ComputeArchiveOptions, |
| 145 | ): Effect.Effect<Uint8Array | ArtifactFile, ArchiveError, ArchiveRequirements>; |
| 146 | /** |
| 147 | * Create the `tar.gz` artifact consumed by Prisma Compute. |
| 148 | * |
| 149 | * Files are added under the `bundle/` prefix, with a synthetic |
| 150 | * `compute.manifest.json` at the archive root. Tar construction and gzip |
| 151 | * compression stream through a private temporary file, so the uncompressed |
| 152 | * artifact is never retained in memory. |
| 153 | */ |
| 154 | export function createComputeArchive( |
| 155 | options: ComputeArchiveOptions, |
| 156 | ): Effect.Effect<Uint8Array | ArtifactFile, ArchiveError, ArchiveRequirements> { |
| 157 | const effect = createComputeArchiveFile(options); |
| 158 | if (options.output === "file") return effect; |
| 159 | return Effect.flatMap(effect, (artifact) => |
| 160 | readArtifactFile(artifact).pipe(Effect.ensuring(artifact.cleanup)), |
| 161 | ); |
| 162 | } |
| 163 | |
| 164 | const createComputeArchiveFile = Effect.fn(function* ( |
| 165 | options: ComputeArchiveOptions, |
| 166 | ): Effect.fn.Return<ArtifactFile, ArchiveError, ArchiveRequirements> { |
| 167 | const { |
| 168 | directory, |
| 169 | entrypoint, |
| 170 | ignore = [], |
| 171 | ignorePrefix, |
| 172 | requiredFiles = [], |
| 173 | maxUncompressedBytes = MAX_UNCOMPRESSED_BYTES, |
| 174 | maxFileBytes = MAX_FILE_BYTES, |
| 175 | maxEntries = MAX_ENTRIES, |
| 176 | } = options; |
| 177 | const fs = yield* FileSystem.FileSystem; |
| 178 | const path = yield* Path.Path; |
| 179 | const runtimeBase = process.cwd(); |
| 180 | const root = path.resolve(runtimeBase, directory); |
| 181 | const realRoot = yield* fs.realPath(root); |
| 182 | const dotAlchemy = yield* dotAlchemyDirectory; |
| 183 | const runtimeRelative = path |
| 184 | .relative(root, path.resolve(runtimeBase, dotAlchemy)) |
| 185 | .replaceAll("\\", "/"); |
| 186 | const normalizedEntrypoint = yield* normalizeEntrypoint(entrypoint); |
| 187 | const validated = yield* Effect.try({ |
| 188 | try: () => ({ |
| 189 | ignore: [ |
| 190 | ...(isPathWithin(root, dotAlchemy, runtimeBase) |
| 191 | ? [ |
| 192 | // Keep runtime state out of the archive. Escape regex characters |
| 193 | // in the literal directory name (e.g. "cache[private]"); the |
| 194 | // suffix matches that directory and its descendants, not siblings |
| 195 | // whose names merely share its prefix (e.g. "cache-backup"). |
| 196 | new RegExp(`^${runtimeRelative.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:/.*)?$`), |
| 197 | ] |
| 198 | : []), |
| 199 | ...ALWAYS_IGNORED_PATTERNS.map((pattern) => compileIgnorePattern(pattern)), |
| 200 | ...ignore.map((pattern) => compileIgnorePattern(pattern, ignorePrefix)), |
| 201 | ], |
| 202 | maxUncompressedBytes: boundedLimit( |
| 203 | "maxUncompressedBytes", |
| 204 | maxUncompressedBytes, |
| 205 | MAX_UNCOMPRESSED_BYTES, |
| 206 | ), |
| 207 | maxFileBytes: boundedLimit("maxFileBytes", maxFileBytes, MAX_FILE_BYTES), |
| 208 | maxEntries: boundedLimit("maxEntries", maxEntries, MAX_ENTRIES), |
| 209 | }), |
| 210 | catch: (error) => |
| 211 | new ComputeArchiveOptionsError({ |
| 212 | message: error instanceof Error ? error.message : String(error), |
| 213 | cause: error, |
| 214 | }), |
| 215 | }); |
| 216 | const budget: ArchiveBudget = { |
| 217 | ...validated, |
| 218 | bytes: 0, |
| 219 | entries: 0, |
| 220 | }; |
| 221 | if (budget.maxFileBytes > budget.maxUncompressedBytes) { |
| 222 | return yield* new ComputeArchiveInvalidProps({ |
| 223 | message: "maxFileBytes must not exceed maxUncompressedBytes", |
| 224 | }); |
| 225 | } |
| 226 | if (isIgnored(normalizedEntrypoint, budget.ignore)) { |
| 227 | return yield* new ComputeArchiveInvalidProps({ |
| 228 | message: `Entrypoint is excluded from the compute artifact: ${normalizedEntrypoint}`, |
| 229 | }); |
| 230 | } |
| 231 | const resolvedEntrypoint = yield* resolvePathWithinRoot( |
| 232 | realRoot, |
| 233 | path.join(realRoot, normalizedEntrypoint), |
| 234 | ); |
| 235 | const entrypointStat = yield* fs.stat(resolvedEntrypoint); |
| 236 | if (entrypointStat.type !== "File") { |
| 237 | return yield* new ComputeArchiveInvalidProps({ |
| 238 | message: `Entrypoint must be a file in compute artifact: ${normalizedEntrypoint}`, |
| 239 | }); |
| 240 | } |
| 241 | |
| 242 | const entries: ArchiveTarEntry[] = []; |
| 243 | yield* addDirectoryEntries(entries, realRoot, realRoot, "bundle", "", budget); |
| 244 | const entrypointArchiveName = `bundle/${normalizedEntrypoint}`; |
| 245 | if (!isArchivedRegularFile(entries, entrypointArchiveName)) { |
| 246 | return yield* new ComputeArchiveOperationFailed({ |
| 247 | message: `Entrypoint not found in compute artifact: ${normalizedEntrypoint}`, |
| 248 | }); |
| 249 | } |
| 250 | |
| 251 | for (const file of requiredFiles) { |
| 252 | const normalized = yield* normalizeEntrypoint(file); |
| 253 | if (!isArchivedRegularFile(entries, `bundle/${normalized}`)) { |
| 254 | return yield* new ComputeArchiveOperationFailed({ |
| 255 | message: `Required file not found in compute artifact: ${normalized}`, |
| 256 | }); |
| 257 | } |
| 258 | } |
| 259 | |
| 260 | const manifest = new TextEncoder().encode( |
| 261 | JSON.stringify( |
| 262 | { |
| 263 | manifestVersion: COMPUTE_MANIFEST_VERSION, |
| 264 | entrypoint: entrypointArchiveName, |
| 265 | }, |
| 266 | null, |
| 267 | 2, |
| 268 | ), |
| 269 | ); |
| 270 | const archivePath = yield* fs.makeTempFile({ |
| 271 | prefix: "alchemy-prisma-compute-", |
| 272 | suffix: ".tar.gz", |
| 273 | }); |
| 274 | const cleanup = fs.remove(archivePath, { force: true }).pipe(Effect.ignore); |
| 275 | |
| 276 | yield* writeCompressedArchiveSecure(archivePath, entries, manifest, MAX_COMPRESSED_BYTES).pipe( |
| 277 | Effect.tapError(() => cleanup), |
| 278 | ); |
| 279 | return yield* inspectArtifactFile(archivePath, MAX_COMPRESSED_BYTES, { |
| 280 | cleanup, |
| 281 | description: "Prisma compute archive", |
| 282 | }).pipe(Effect.tapError(() => cleanup)); |
| 283 | }); |
| 284 | |
| 285 | const addDirectoryEntries: ( |
| 286 | entries: ArchiveTarEntry[], |
| 287 | realRoot: string, |
| 288 | directory: string, |
| 289 | tarPrefix: string, |
| 290 | relativePrefix: string, |
| 291 | budget: ArchiveBudget, |
| 292 | ) => Effect.Effect<void, ArchiveError, ArchiveRequirements> = Effect.fn( |
| 293 | function* (entries, realRoot, directory, tarPrefix, relativePrefix, budget) { |
| 294 | const fs = yield* FileSystem.FileSystem; |
| 295 | const path = yield* Path.Path; |
| 296 | const directoryResult = yield* readDirectoryEntriesSecure({ |
| 297 | directory, |
| 298 | relativePrefix, |
| 299 | ignore: budget.ignore, |
| 300 | entriesAlreadyObserved: budget.entries, |
| 301 | maxEntries: budget.maxEntries, |
| 302 | }); |
| 303 | budget.entries += directoryResult.observedEntries; |
| 304 | |
| 305 | for (const entry of directoryResult.entries) { |
| 306 | const name = entry.name; |
| 307 | const relativeName = relativePrefix ? `${relativePrefix}/${name}` : name; |
| 308 | |
| 309 | const filePath = path.join(directory, name); |
| 310 | const tarName = `${tarPrefix}/${name}`; |
| 311 | if (entry.type === "SymbolicLink") { |
| 312 | const symlinkTarget = yield* fs.readLink(filePath); |
| 313 | const linkname = yield* resolveArchiveSymlinkTarget(realRoot, filePath, symlinkTarget); |
| 314 | entries.push({ |
| 315 | name: tarName, |
| 316 | mode: 0o777, |
| 317 | type: "symlink", |
| 318 | linkname, |
| 319 | }); |
| 320 | continue; |
| 321 | } |
| 322 | |
| 323 | if (entry.type === "Directory") { |
| 324 | const realDirectory = yield* resolvePathWithinRoot(realRoot, filePath); |
| 325 | yield* addDirectoryEntries(entries, realRoot, realDirectory, tarName, relativeName, budget); |
| 326 | continue; |
| 327 | } |
| 328 | |
| 329 | if (entry.type !== "File") { |
| 330 | return yield* new ComputeArchiveOperationFailed({ |
| 331 | message: `Unsupported filesystem entry in compute artifact: ${relativeName}`, |
| 332 | }); |
| 333 | } |
| 334 | |
| 335 | const verified = yield* inspectVerifiedFile(filePath, budget.maxFileBytes, { |
| 336 | allowEmpty: true, |
| 337 | description: `Compute artifact file '${relativeName}'`, |
| 338 | }); |
| 339 | yield* ensureResolvedPathWithinRoot(realRoot, verified.path); |
| 340 | if (budget.bytes + verified.size > budget.maxUncompressedBytes) { |
| 341 | return yield* new ComputeArchiveOperationFailed({ |
| 342 | message: `Compute artifact exceeds the ${budget.maxUncompressedBytes} byte uncompressed safety limit. Narrow the artifact directory or add ignore patterns.`, |
| 343 | }); |
| 344 | } |
| 345 | budget.bytes += verified.size; |
| 346 | entries.push({ |
| 347 | name: tarName, |
| 348 | mode: verified.mode & 0o777, |
| 349 | type: "file", |
| 350 | file: verified, |
| 351 | }); |
| 352 | } |
| 353 | }, |
| 354 | ); |
| 355 | |
| 356 | export const normalizeEntrypoint = (entrypoint: string) => |
| 357 | Effect.gen(function* () { |
| 358 | const normalized = entrypoint.replaceAll("\\", "/"); |
| 359 | if (normalized.trim().length === 0) { |
| 360 | return yield* new ComputeArchiveInvalidProps({ message: "entrypoint must be non-empty" }); |
| 361 | } |
| 362 | if (normalized.startsWith("/") || /^[a-zA-Z]:\//.test(normalized)) { |
| 363 | return yield* new ComputeArchiveInvalidProps({ message: "entrypoint must be relative" }); |
| 364 | } |
| 365 | const parts = normalized.split("/").filter((part) => part !== "."); |
| 366 | if (parts.some((part) => part === ".." || part.length === 0)) { |
| 367 | return yield* new ComputeArchiveInvalidProps({ |
| 368 | message: "entrypoint must not contain empty or parent segments", |
| 369 | }); |
| 370 | } |
| 371 | return parts.join("/"); |
| 372 | }); |
| 373 | |
| 374 | const resolvePathWithinRoot = Effect.fn(function* (realRoot: string, candidate: string) { |
| 375 | const fs = yield* FileSystem.FileSystem; |
| 376 | const realCandidate = yield* fs.realPath(candidate); |
| 377 | yield* ensureResolvedPathWithinRoot(realRoot, realCandidate); |
| 378 | return realCandidate; |
| 379 | }); |
| 380 | |
| 381 | const ensureResolvedPathWithinRoot = Effect.fn(function* ( |
| 382 | realRoot: string, |
| 383 | resolvedCandidate: string, |
| 384 | ) { |
| 385 | const path = yield* Path.Path; |
| 386 | const relative = path.relative(realRoot, resolvedCandidate); |
| 387 | if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) { |
| 388 | return yield* new ComputeArchiveOperationFailed({ |
| 389 | message: `Archive path escapes compute artifact root: ${resolvedCandidate}`, |
| 390 | }); |
| 391 | } |
| 392 | }); |
| 393 | |
| 394 | const resolveArchiveSymlinkTarget = Effect.fn(function* ( |
| 395 | realRoot: string, |
| 396 | symlinkPath: string, |
| 397 | target: string, |
| 398 | ) { |
| 399 | const path = yield* Path.Path; |
| 400 | if (path.sep === "/" && target.includes("\\")) { |
| 401 | return yield* new ComputeArchiveOperationFailed({ |
| 402 | message: `Archive symlink target contains an unsupported backslash: ${target}`, |
| 403 | }); |
| 404 | } |
| 405 | const symlinkDir = path.dirname(symlinkPath); |
| 406 | const targetPath = path.isAbsolute(target) ? target : path.resolve(symlinkDir, target); |
| 407 | const realTarget = yield* resolvePathWithinRoot(realRoot, targetPath); |
| 408 | |
| 409 | if (!path.isAbsolute(target)) return target.replaceAll("\\", "/"); |
| 410 | const realSymlinkDir = yield* resolvePathWithinRoot(realRoot, symlinkDir); |
| 411 | const relative = path.relative(realSymlinkDir, realTarget); |
| 412 | return (relative.length === 0 ? "." : relative).replaceAll("\\", "/"); |
| 413 | }); |
| 414 | |
| 415 | const boundedLimit = (name: string, value: number, hardLimit: number) => { |
| 416 | if (!Number.isSafeInteger(value) || value <= 0) { |
| 417 | throw new Error(`${name} must be a positive safe integer`); |
| 418 | } |
| 419 | if (value > hardLimit) { |
| 420 | throw new Error(`${name} must not exceed the hard limit of ${hardLimit}`); |
| 421 | } |
| 422 | return value; |
| 423 | }; |
| 424 | |
| 425 | const compileIgnorePattern = (input: string, prefix?: string) => { |
| 426 | const normalized = input.replaceAll("\\", "/").replace(/^\.\//, ""); |
| 427 | if ( |
| 428 | normalized.length === 0 || |
| 429 | normalized.startsWith("!") || |
| 430 | normalized.startsWith("/") || |
| 431 | /^[a-zA-Z]:\//.test(normalized) || |
| 432 | normalized.split("/").some((segment) => segment === "..") |
| 433 | ) { |
| 434 | throw new Error(`Invalid compute archive ignore pattern: ${input}`); |
| 435 | } |
| 436 | const scoped = prefix === undefined ? normalized : `${prefix}/${normalized}`; |
| 437 | const escaped = scoped |
| 438 | .replace(/[.+^${}()|[\]\\]/g, "\\$&") |
| 439 | .replaceAll("**", "\0") |
| 440 | .replaceAll("*", "[^/]*") |
| 441 | .replaceAll("\0", ".*"); |
| 442 | return new RegExp(`^${escaped}(?:/.*)?$`); |
| 443 | }; |
| 444 | |
| 445 | const isIgnored = (relativeName: string, patterns: readonly RegExp[]) => |
| 446 | patterns.some((pattern) => pattern.test(relativeName)); |