@vzn/vx 0.0.18 → 0.0.22

package/src/workspace/workspace.ts

@@ -1,7 +1,9 @@
+import type { Dirent } from 'node:fs'
 import { readdir, stat } from 'node:fs/promises'
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
-import { relPosix, UserError } from '../util/index.js'
+import { BUN_GLOB_WILDCARDS, relPosix, UserError, normalizeBunGlob } from '../util/index.js'
+import { type LoadReads, readOnce } from './load-reads.js'
 
 export interface PackageJson {
   name: string
@@ -37,7 +39,14 @@ export interface ProjectEntry {
   config: ProjectConfig
 }
 
-const CONFIG_FILENAMES = ['vx.config.ts', 'vx.config.mts', 'vx.config.js', 'vx.config.mjs']
+export const PROJECT_CONFIG_FILENAMES = [
+  'vx.config.ts',
+  'vx.config.mts',
+  'vx.config.js',
+  'vx.config.mjs',
+]
+
+const decoder = new TextDecoder()
 
 /**
  * Walk up from `start` to find the workspace root. A directory is a root
@@ -55,15 +64,20 @@ const CONFIG_FILENAMES = ['vx.config.ts', 'vx.config.mts', 'vx.config.js', 'vx.c
  * When no candidate claims `start` — a standalone package, or a subdirectory
  * of a single-project repo — the nearest candidate wins (the root itself IS
  * the project). Throws a `UserError` when there is no candidate before `/`.
+ * A load that goes on to `loadWorkspace` passes its `reads`, so the
+ * root's manifest is read once for both.
  */
-export async function findWorkspaceRoot(start: string): Promise<string> {
+export async function findWorkspaceRoot(
+  start: string,
+  reads: LoadReads = new Map(),
+): Promise<string> {
   let dir = path.resolve(start)
   const below: string[] = []
   let nearest: string | null = null
   while (true) {
     let globs: string[] | null
     try {
-      globs = await readPackageGlobs(dir)
+      globs = await readPackageGlobs(dir, reads)
     } catch {
       // An unparseable manifest is still a root SIGNAL (the pre-existing
       // behaviour probed only for existence); it just can't claim members.
@@ -73,10 +87,19 @@ export async function findWorkspaceRoot(start: string): Promise<string> {
     if (globs !== null) {
       nearest ??= dir
       if (claimsMember(dir, below, globs)) return dir
+      // pnpm takes the nearest `pnpm-workspace.yaml` as the root, listed or
+      // not. Walking past it, `apps/inner` resolved to the outer workspace
+      // while `apps/inner/pkgs/x` resolved to the inner one: two roots and
+      // two caches for one tree (item 990). Already read: `reads` holds it.
+      if ((await readOnce(reads, path.join(dir, 'pnpm-workspace.yaml'))) !== null) return dir
     }
     const parent = path.dirname(dir)
     if (parent === dir) break
-    below.push(dir)
+    // Only a directory holding a manifest can be a member: a glob that
+    // matched `packages/tools`, which has none, claimed the standalone
+    // package below it, and `packages/tools/standalone` ran as a stranger
+    // in a workspace that does not list it (item 989).
+    if (globs !== null) below.push(dir)
     dir = parent
   }
   if (nearest !== null) return nearest
@@ -89,8 +112,9 @@ export async function findWorkspaceRoot(start: string): Promise<string> {
 /** True when one of `below` (dirs under `root`, toward `start`) is a member. */
 function claimsMember(root: string, below: readonly string[], globs: readonly string[]): boolean {
   if (below.length === 0 || globs.length === 0) return false
-  const rels = below.map((d) => relPosix(root, d))
-  for (const pattern of globs) {
+  const { positive, negative } = splitPackageGlobs(globs)
+  const rels = below.map((d) => relPosix(root, d)).filter((rel) => !excludedBy(rel, negative))
+  for (const pattern of positive) {
     const normalized = pattern.replace(/\/+$/, '')
     // `.` means the root itself is the project — never a directory below it.
     if (normalized === '' || normalized === '.') continue
@@ -100,21 +124,75 @@ function claimsMember(root: string, below: readonly string[], globs: readonly st
   return false
 }
 
+/**
+ * pnpm, npm, yarn and Bun all take `!packages/fixtures` in the package
+ * list. Handed to `Bun.Glob` raw, a leading `!` negates the WHOLE pattern,
+ * so `!packages/fixtures/package.json` matched every manifest in the tree
+ * and every directory holding one became a project — the excluded package
+ * ran under `--all`, and a fixture repeating a name killed the run with
+ * "Duplicate package name". Negations subtract from what the positive
+ * globs found; a literal one excludes its tree.
+ */
+function splitPackageGlobs(globs: readonly string[]): { positive: string[]; negative: string[] } {
+  const positive: string[] = []
+  const negative: string[] = []
+  // `!./packages/legacy` and `!packages//legacy` excluded nothing, silently
+  // (2026-09-10): the same spellings the input globs normalize.
+  for (const raw of globs) {
+    // A member glob names directories, so a trailing slash says nothing:
+    // npm and pnpm read `packages/*/` as `packages/*`. `normalizeBunGlob`
+    // gives it a task glob's meaning, `/**`, and `packages/*/` found every
+    // example and fixture package at any depth below the members (item 985).
+    const g = normalizeBunGlob(raw.replace(/(.)\/+$/, '$1'))
+    if (g.startsWith('!')) negative.push(g.slice(1).replace(/\/+$/, ''))
+    else positive.push(g)
+  }
+  return { positive, negative }
+}
+
+function excludedBy(rel: string, negative: readonly string[]): boolean {
+  for (const neg of negative) {
+    if (neg.length === 0) continue
+    if (rel === neg || rel.startsWith(`${neg}/`)) return true
+    if (!BUN_GLOB_WILDCARDS.test(neg)) continue
+    if (new Bun.Glob(neg).match(rel)) return true
+    // pnpm matches the MANIFEST (`<pattern>/package.json`), so its documented
+    // `!**/test/**` excludes `packages/test` itself; matched against the
+    // directory, `**/test/**` needs something below `test` and the package
+    // stayed a member (item 986).
+    if (new Bun.Glob(`${neg}/package.json`).match(`${rel}/package.json`)) return true
+  }
+  return false
+}
+
 /**
  * Package globs declared by `dir`, or `null` when `dir` is not a root
  * candidate. A bare `package.json` (no `workspaces`) is single-project mode:
  * the root itself is the only project, hence `['.']`.
  */
-async function readPackageGlobs(dir: string): Promise<string[] | null> {
+async function readPackageGlobs(dir: string, reads?: LoadReads): Promise<string[] | null> {
   const yamlPath = path.join(dir, 'pnpm-workspace.yaml')
-  if (await Bun.file(yamlPath).exists()) {
-    const parsed = (parseManifest(await Bun.file(yamlPath).text(), yamlPath, Bun.YAML.parse) ??
-      {}) as { packages?: unknown }
-    return assertGlobList(parsed.packages ?? [], yamlPath, 'packages')
+  const yaml = await readOnce(reads, yamlPath)
+  let yamlWithoutPackages = false
+  if (yaml !== null) {
+    const parsed = parseManifest(decoder.decode(yaml), yamlPath, Bun.YAML.parse)
+    if (parsed !== null && parsed !== undefined) {
+      if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new UserError(`${yamlPath}: must be a mapping (\`packages:\` and pnpm's settings)`)
+      }
+      const packages = (parsed as { packages?: unknown }).packages
+      if (packages !== undefined) return assertGlobList(packages, yamlPath, 'packages')
+    }
+    // No `packages:`: pnpm 10 keeps its settings and catalogs in this file
+    // for a single-package repo too. The root's package.json decides, as it
+    // would without the file; read as an empty list, the root found zero
+    // projects and every verb ran nothing and exited 0 (item 984).
+    yamlWithoutPackages = true
   }
   const pkgPath = path.join(dir, 'package.json')
-  if (!(await Bun.file(pkgPath).exists())) return null
-  const pkg = parseManifest(await Bun.file(pkgPath).text(), pkgPath, JSON.parse) as PackageJson
+  const pkgBytes = await readOnce(reads, pkgPath)
+  if (pkgBytes === null) return yamlWithoutPackages ? [] : null
+  const pkg = parsePackageJson(decoder.decode(pkgBytes), pkgPath)
   const ws = pkg.workspaces as unknown
   if (ws === undefined || ws === null) return ['.']
   if (ws && typeof ws === 'object' && !Array.isArray(ws) && 'packages' in ws) {
@@ -127,6 +205,49 @@ async function readPackageGlobs(dir: string): Promise<string[] | null> {
   return assertGlobList(ws, pkgPath, 'workspaces')
 }
 
+/**
+ * Package manifests the globs never reach, in single-project mode only: a
+ * root `package.json` with no `workspaces` field makes the root the one
+ * project, and a `packages/app/package.json` full of scripts beside it is
+ * then invisible — `vx init` said "no package.json scripts" and `vx run`
+ * said "run vx init" (2026-09-16). One shallow scan, two levels, on the
+ * failure path only; `node_modules` and dot directories are skipped.
+ */
+export async function unreachedPackages(workspace: Workspace): Promise<string[]> {
+  if (workspace.packageGlobs.length !== 1 || workspace.packageGlobs[0] !== '.') return []
+  const found: string[] = []
+  // Two scans: Bun.Glob does not expand a brace whose alternatives hold a
+  // slash (`{*,*/*}/package.json` matched nothing, measured 2026-09-16).
+  for (const pattern of ['*/package.json', '*/*/package.json']) {
+    for await (const rel of new Bun.Glob(pattern).scan({
+      cwd: workspace.root,
+      onlyFiles: true,
+      dot: false,
+    })) {
+      const posix = rel.split(path.sep).join('/')
+      if (posix.startsWith('node_modules/') || posix.includes('/node_modules/')) continue
+      found.push(posix.slice(0, -'/package.json'.length))
+    }
+  }
+  return found.sort()
+}
+
+/** The line for `unreachedPackages`' finding: the cause, the packages, the glob to add. */
+export function unreachedHint(unreached: readonly string[]): string {
+  const n = unreached.length
+  const shown = unreached.slice(0, 3).join(', ') + (n > 3 ? ` and ${n - 3} more` : '')
+  const globs = [
+    ...new Set(unreached.map((d) => (d.includes('/') ? `${path.posix.dirname(d)}/*` : d))),
+  ]
+    .map((g) => `"${g}"`)
+    .join(', ')
+  return (
+    `package.json declares no \`workspaces\` (and there is no pnpm-workspace.yaml), so the root is the only project ` +
+    `and ${n} package.json below it ${n === 1 ? 'is' : 'are'} not: ${shown}. ` +
+    `Add \`"workspaces": [${globs}]\` to package.json and re-run.`
+  )
+}
+
 /**
  * Parse a workspace manifest, naming the FILE on failure. The raw parser
  * errors (`Failed to parse JSON`) carry no path, so in a 1000-package
@@ -141,6 +262,25 @@ function parseManifest(text: string, file: string, parse: (t: string) => unknown
   }
 }
 
+/**
+ * A `package.json` as discovery reads it: a JSON object whose `name`, when
+ * present, is a string with no surrounding whitespace (npm refuses one).
+ * Parsed and cast unchecked, `null` crashed with a TypeError and a stack,
+ * `{"name":123}` planned `123#build`, and `" a"` beside `"a"` made two
+ * projects (item 988).
+ */
+function parsePackageJson(text: string, file: string): PackageJson {
+  const pkg = parseManifest(text, file, JSON.parse)
+  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
+    throw new UserError(`${file}: must be a JSON object`)
+  }
+  const name = (pkg as { name?: unknown }).name
+  if (name !== undefined && (typeof name !== 'string' || name.trim() !== name)) {
+    throw new UserError(`${file}: "name" must be a string with no surrounding whitespace`)
+  }
+  return pkg as PackageJson
+}
+
 /**
  * A glob list is user input from a manifest: `packages: "packages/*"`
  * (a bare string instead of a list) is an easy YAML slip, and without
@@ -150,9 +290,46 @@ function assertGlobList(value: unknown, file: string, field: string): string[] {
   if (!Array.isArray(value) || value.some((p) => typeof p !== 'string')) {
     throw new UserError(`${file}: \`${field}\` must be an array of glob strings`)
   }
+  for (const pattern of value as string[]) {
+    if (EXTGLOB.test(pattern)) throw extglobRefusal(pattern, file, field)
+  }
   return value as string[]
 }
 
+/**
+ * An extglob group: `!(…)`, `@(…)`, `+(…)`, `*(…)`, `?(…)`. npm (minimatch)
+ * and yarn (micromatch) read `packages/!(x)` as "every directory in
+ * packages/ but x"; `Bun.Glob` has no extglob, and its scan read the
+ * segment as a wildcard, so the excluded package became a project
+ * (turborepo#3766) while its match read the same text literally. vx cannot
+ * honour the pattern, so it refuses it rather than read it either way.
+ */
+const EXTGLOB = /[!@+*?]\(/
+
+function extglobRefusal(pattern: string, file: string, field: string): UserError {
+  const head = `${file}: \`${field}\` entry "${pattern}" is an extglob, which vx's glob engine does not read`
+  // The common shape, a whole segment excluding plain names, has an exact
+  // rewrite in the `!` entries every package manager takes.
+  const segments = pattern.split('/')
+  const at = segments.findIndex((s) => /^!\([^()]*\)$/.test(s))
+  const names = at === -1 ? [] : segments[at]!.slice(2, -1).split('|')
+  const plain = names.every((n) => n !== '' && !BUN_GLOB_WILDCARDS.test(n) && !/[()!@+]/.test(n))
+  const rest = segments.filter((_s, i) => i !== at).join('/')
+  if (at === -1 || !plain || EXTGLOB.test(rest)) {
+    return new UserError(
+      `${head}. List the members with \`*\`, braces or \`!\` exclusions instead.`,
+    )
+  }
+  const before = segments.slice(0, at)
+  const rewrite = [
+    [...before, '*', ...segments.slice(at + 1)].join('/'),
+    ...names.map((n) => `!${[...before, n].join('/')}`),
+  ]
+  return new UserError(
+    `${head} (npm and yarn read \`!(…)\` as an exclusion). List the exclusion as its own entry: [${rewrite.map((r) => JSON.stringify(r)).join(', ')}].`,
+  )
+}
+
 /**
  * Resolve the cache directory for a workspace. Respects the user's
  * `defineWorkspace({ cacheDir })` override (relative to the workspace
@@ -173,8 +350,8 @@ export function resolveCacheDir(root: string, config: WorkspaceConfig | null): s
  * If a `package.json` exists with no `workspaces` field, the root
  * itself is treated as a single-project workspace.
  */
-export async function loadWorkspace(root: string): Promise<Workspace> {
-  const packageGlobs = await readPackageGlobs(root)
+export async function loadWorkspace(root: string, reads?: LoadReads): Promise<Workspace> {
+  const packageGlobs = await readPackageGlobs(root, reads)
   if (packageGlobs === null) {
     // Should be unreachable: findWorkspaceRoot only returns dirs that
     // pass at least one of the two existence checks.
@@ -188,12 +365,30 @@ export async function loadWorkspace(root: string): Promise<Workspace> {
 // path.
 const SIMPLE_STAR_RE = /^[^*?{}[\]!]+\/\*$/
 
+/**
+ * The directory each `<dir>/*` package glob names — where a member comes
+ * and goes as one directory entry, so `vx watch` can hear a package added
+ * or removed without walking anything. A glob of another shape (`apps/**`)
+ * has no such directory and contributes none.
+ */
+export function memberBaseDirs(workspace: Workspace): string[] {
+  const bases = new Set<string>()
+  for (const pattern of splitPackageGlobs(workspace.packageGlobs).positive) {
+    const normalized = pattern === '.' ? '' : pattern.replace(/\/$/, '')
+    if (SIMPLE_STAR_RE.test(normalized)) {
+      bases.add(path.resolve(workspace.root, normalized.slice(0, -2)))
+    }
+  }
+  return [...bases]
+}
+
 /**
  * The directories a workspace glob names. For the `<dir>/*` shape this is
  * one readdir of `<dir>` — the same answer `Bun.Glob` gives, at a third of
  * the cost (measured 2026-09-02: 25 ms → ~2 ms for 1000 members). A
- * symlinked member is followed when it points at a directory, as the glob
- * did. Dot-directories are skipped (`dot: false`), so are `node_modules`.
+ * symlinked member is followed when it points at a directory, and so is
+ * it by the scan any other shape takes, unless the glob holds `**` (item
+ * 987). Dot-directories are skipped (`dot: false`), so are `node_modules`.
  */
 async function memberDirs(root: string, pattern: string): Promise<string[]> {
   // Normalize: `"."` -> the root itself; `"foo/"` -> `"foo"`.
@@ -224,7 +419,12 @@ async function memberDirs(root: string, pattern: string): Promise<string[]> {
   const globPattern = normalized === '' ? 'package.json' : `${normalized}/package.json`
   const glob = new Bun.Glob(globPattern)
   const dirs: string[] = []
-  for await (const rel of glob.scan({ cwd: root, onlyFiles: true, dot: false })) {
+  // A linked member is a member, as the readdir path above has it:
+  // `packages/*` found `packages/b -> ../ext/b` while `packages/{a,b}` and
+  // `pack*/*` did not (item 987). Followed only where the depth is bounded:
+  // under `**` the scan would walk every pnpm `node_modules` link.
+  const followSymlinks = !normalized.includes('**')
+  for await (const rel of glob.scan({ cwd: root, onlyFiles: true, dot: false, followSymlinks })) {
     // Skip nested node_modules — workspace package globs shouldn't
     // ever reach into them, but a pathological pattern like `**`
     // would. Avoid splitting the path on the hot loop.
@@ -236,32 +436,67 @@ async function memberDirs(root: string, pattern: string): Promise<string[]> {
 }
 
 /**
- * The project's config file, by `CONFIG_FILENAMES` precedence, or null.
- * Stats the candidates in order rather than listing the directory: across
- * 1000 projects a readdir each cost 9.6 ms against 6.3 ms of stats even
- * with the config at the LAST name (measured 2026-09-03), and a `.ts`
- * config — the first name — pays one stat.
+ * The project's config file, by `PROJECT_CONFIG_FILENAMES` precedence, or null.
+ *
+ * Two shapes, one per platform, each the measured winner there across
+ * 1,000 projects with the manifest read in flight alongside:
+ *   - macOS stats the candidates in order: a readdir each cost 9.6 ms
+ *     against 6.3 ms of stats even with the config at the LAST name
+ *     (2026-09-03), and a `.ts` config — the first name — pays one stat.
+ *   - Linux lists the directory once: a readdir each is 12 ms against
+ *     43 ms of stats at the last name and ties the one-stat case
+ *     (2026-09-09, a `vx.config.mjs` workspace; stats there cost a
+ *     thread-pool round trip apiece).
+ * Both answer identically: a directory or dangling link under a config
+ * name is skipped for the next name, a symlink to a file counts.
  */
 async function findConfigFile(dir: string): Promise<string | null> {
-  for (const name of CONFIG_FILENAMES) {
-    const candidate = path.join(dir, name)
+  if (process.platform === 'linux') {
+    let entries: Dirent[]
     try {
-      if ((await stat(candidate)).isFile()) return candidate
+      entries = await readdir(dir, { withFileTypes: true })
     } catch {
-      // not this name
+      return null
     }
+    const byName = new Map(entries.map((e) => [e.name, e]))
+    for (const name of PROJECT_CONFIG_FILENAMES) {
+      const entry = byName.get(name)
+      if (entry === undefined) continue
+      const candidate = path.join(dir, name)
+      if (entry.isFile()) return candidate
+      if (entry.isSymbolicLink() && (await isFile(candidate))) return candidate
+    }
+    return null
+  }
+  for (const name of PROJECT_CONFIG_FILENAMES) {
+    const candidate = path.join(dir, name)
+    if (await isFile(candidate)) return candidate
   }
   return null
 }
 
+async function isFile(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isFile()
+  } catch {
+    return false
+  }
+}
+
 export async function listProjects(workspace: Workspace): Promise<ProjectMeta[]> {
   // Run all package globs concurrently. Disk-bound walks parallelize
   // well; serializing them just stretches the discovery phase by N×.
+  const { positive, negative } = splitPackageGlobs(workspace.packageGlobs)
   const perPattern = await Promise.all(
-    workspace.packageGlobs.map((pattern) => memberDirs(workspace.root, pattern)),
+    positive.map((pattern) => memberDirs(workspace.root, pattern)),
   )
   const matches = new Set<string>()
-  for (const arr of perPattern) for (const m of arr) matches.add(m)
+  for (const arr of perPattern) {
+    for (const m of arr) {
+      if (negative.length > 0 && excludedBy(relPosix(workspace.root, m), negative)) continue
+      matches.add(m)
+    }
+  }
 
   // Per-project discovery: the manifest read answers "is there a
   // package.json" (an ENOENT is the "not a member" answer, at the cost of
@@ -279,7 +514,7 @@ export async function listProjects(workspace: Workspace): Promise<ProjectMeta[]>
           .catch(() => null),
       ])
       if (text === null) return null
-      const pkg = parseManifest(text, pkgJsonPath, JSON.parse) as PackageJson
+      const pkg = parsePackageJson(text, pkgJsonPath)
       return { dir, pkg, configPath }
     }),
   )

package/plugins/local-cache/index.ts

@@ -1,2 +0,0 @@
-// Subpath shim for Bun's compiled binaries — see ../../index.ts.
-export * from '../../src/plugins/local-cache/index.js'

package/plugins/local-executor/index.ts

@@ -1,2 +0,0 @@
-// Subpath shim for Bun's compiled binaries — see ../../index.ts.
-export * from '../../src/plugins/local-executor/index.js'

package/plugins/schedule-history/index.ts

@@ -1,2 +0,0 @@
-// Subpath shim for Bun's compiled binaries — see ../../index.ts.
-export * from '../../src/plugins/schedule-history/index.js'

package/src/cache/cas-backend.ts

@@ -1,115 +0,0 @@
-// CASBackend — pluggable content-addressed storage beneath the cache.
-//
-// Today's Cache + LayeredCache both bundle "where do the bytes live"
-// with "how do we look up entries metadata + key derivation."
-// CASBackend separates the former so a future R2/S3 backend
-// or REAPI CAS bridge can drop in without touching the
-// orchestrator or the SQL entries index.
-//
-// Two reference implementations in this file:
-//   - MemoryCASBackend — testing + in-memory builds. Holds raw bytes.
-//   - FsCASBackend     — writes bytes to a directory; mirrors what
-//                        Cache.save does today. Bun-native using Bun.file
-//                        for the read path so big artifacts stream
-//                        without slurping into memory.
-//
-// Cache.ts has NOT yet been rewired to use a CASBackend — that's a
-// follow-up (Phase 1b). This file ships the abstraction + the two
-// reference impls so downstream work (R2, otel-bridge, distributed-ci)
-// can rely on the type. Byte-identical behaviour today.
-
-import { mkdir, rename, rm } from 'node:fs/promises'
-import path from 'node:path'
-import type { Digest } from './digest.js'
-
-/** Per-process counter for put() temp names; uniqueness only. */
-let casTmpSeq = 0
-
-export interface CASBackend {
-  /** Write bytes under `digest`. Idempotent — putting the same digest twice is a no-op. */
-  put(digest: Digest, bytes: Uint8Array): Promise<void>
-  /** Read bytes under `digest`, or null if absent. */
-  get(digest: Digest): Promise<Uint8Array | null>
-  /** Cheap existence probe — no bytes round-tripped if possible. */
-  has(digest: Digest): Promise<boolean>
-  /** Drop one entry (eviction). No-op if absent. */
-  remove(digest: Digest): Promise<void>
-}
-
-/** In-memory backend, useful for tests and ephemeral runs. */
-export class MemoryCASBackend implements CASBackend {
-  private readonly store = new Map<string, Uint8Array>()
-
-  async put(digest: Digest, bytes: Uint8Array): Promise<void> {
-    if (bytes.byteLength !== digest.sizeBytes) {
-      throw new Error(
-        `MemoryCASBackend.put: sizeBytes mismatch (digest=${digest.sizeBytes}, actual=${bytes.byteLength})`,
-      )
-    }
-    this.store.set(digest.hash, bytes)
-  }
-
-  async get(digest: Digest): Promise<Uint8Array | null> {
-    return this.store.get(digest.hash) ?? null
-  }
-
-  async has(digest: Digest): Promise<boolean> {
-    return this.store.has(digest.hash)
-  }
-
-  async remove(digest: Digest): Promise<void> {
-    this.store.delete(digest.hash)
-  }
-
-  /** Test-only: how many entries are held. */
-  size(): number {
-    return this.store.size
-  }
-}
-
-/** Filesystem-backed backend writing `<rootDir>/<hash>.tar.zst` files. */
-export class FsCASBackend implements CASBackend {
-  constructor(private readonly rootDir: string) {}
-
-  private pathFor(digest: Digest): string {
-    return path.join(this.rootDir, `${digest.hash}.tar.zst`)
-  }
-
-  async put(digest: Digest, bytes: Uint8Array): Promise<void> {
-    if (bytes.byteLength !== digest.sizeBytes) {
-      throw new Error(
-        `FsCASBackend.put: sizeBytes mismatch (digest=${digest.sizeBytes}, actual=${bytes.byteLength})`,
-      )
-    }
-    // Temp + rename, the same shape `Cache.writeArtifactAndIndex` and the
-    // archive extractor use: two writers of the SAME content-addressed
-    // blob are expected (that is what content-addressing invites), and a
-    // plain write lets a reader observe a half-written file under a name
-    // that promises complete bytes. rename(2) is atomic, so a concurrent
-    // reader sees either the old file or the whole new one.
-    const final = this.pathFor(digest)
-    const tmp = `${final}.tmp-${process.pid.toString(36)}-${(casTmpSeq++).toString(36)}`
-    await mkdir(this.rootDir, { recursive: true })
-    try {
-      await Bun.write(tmp, bytes)
-      await rename(tmp, final)
-    } catch (err) {
-      await rm(tmp, { force: true })
-      throw err
-    }
-  }
-
-  async get(digest: Digest): Promise<Uint8Array | null> {
-    const file = Bun.file(this.pathFor(digest))
-    if (!(await file.exists())) return null
-    return new Uint8Array(await file.arrayBuffer())
-  }
-
-  async has(digest: Digest): Promise<boolean> {
-    return Bun.file(this.pathFor(digest)).exists()
-  }
-
-  async remove(digest: Digest): Promise<void> {
-    await rm(this.pathFor(digest), { force: true })
-  }
-}

package/src/cache/digest.ts

@@ -1,32 +0,0 @@
-// Digest — the explicit content-address used by every cache layer.
-//
-// Lifted as a first-class type (architecture-review-2026-06.md §4.3)
-// so storage backends become pluggable beneath CacheLayer: local FS,
-// R2, S3, or a future REAPI CAS bridge all speak (hash, sizeBytes).
-//
-// Two practical wins from making this explicit:
-//   1. sizeBytes is the truncation check at transport boundaries (HTTP
-//      Content-Length, R2 ETag-by-size). Free correctness, free corrupt-
-//      artifact-early-fail.
-//   2. CASBackend.has(digest) can answer with just the metadata, no
-//      bytes round-trip — what existence probes want.
-//
-// Why sizeBytes is `number` and not `bigint`: Bun.file().size returns
-// number; JS Number safely represents integers to 2^53-1 (~9 PB); no
-// real cache artifact gets there. Bigint would create the same
-// JSON.stringify-throws nuisance we already navigated for ns timestamps.
-
-export interface Digest {
-  readonly hash: string
-  readonly sizeBytes: number
-}
-
-export function makeDigest(hash: string, sizeBytes: number): Digest {
-  if (!/^[0-9a-f]+$/i.test(hash)) {
-    throw new Error(`invalid digest hash: ${JSON.stringify(hash)}`)
-  }
-  if (!Number.isInteger(sizeBytes) || sizeBytes < 0) {
-    throw new Error(`invalid digest sizeBytes: ${sizeBytes}`)
-  }
-  return { hash, sizeBytes }
-}

package/src/cli/migrate-emit.ts

@@ -1,21 +0,0 @@
-// Shared TS-literal emission helper for the migrate mappers. Lives in its own
-// leaf module so both migrate.ts (the config emitter) and migrate-turbo.ts (the
-// preset renderer) can escape strings identically without a dependency cycle
-// (migrate.ts already imports the turbo/nx mappers, so a back-import of a value
-// from migrate.ts would close a runtime cycle).
-
-/**
- * Escape an arbitrary string into a single-quoted TS literal. Escapes
- * backslash + quote AND raw newlines/CR — a value with an embedded newline
- * (legal JSON, e.g. a script `"echo a\necho b"`, or a glob with a `'`) would
- * otherwise splice into a single-quoted literal as an unterminated / malformed
- * string that fails to load (generated files must round-trip through the
- * loader).
- */
-export function quote(s: string): string {
-  return `'${s
-    .replaceAll('\\', '\\\\')
-    .replaceAll("'", "\\'")
-    .replaceAll('\n', '\\n')
-    .replaceAll('\r', '\\r')}'`
-}