@vzn/vx 0.0.187 → 0.0.189

package/README.md

@@ -32,25 +32,24 @@ Same graph, commands and concurrency: [how it is measured](https://vznjs.github.
 
 ## Try it on your repo
 
-In a Turborepo or Nx workspace, add one file (`npx @vzn/vx init` writes
-it and prints the command to run next):
-
-```ts
-// vx.workspace.ts
-import { defineWorkspace } from '@vzn/vx'
-import { turbo } from '@vzn/vx-migrate' // Nx: import { nx } and use nx()
-
-export default defineWorkspace({ plugins: [turbo()] })
-```
-
-Then:
+In a Turborepo or Nx workspace:
 
 ```sh
 npm install -D @vzn/vx @vzn/vx-migrate
+npx vx init                 # writes vx.workspace.ts, below; nothing else
 npx vx run build --all      # your turbo.json or Nx targets, run by vx
 npx vx run build --all      # again: up-to-date in milliseconds
 ```
 
+The one file `vx init` writes (in an Nx repo, `nx` for `turbo`):
+
+```ts
+import type { WorkspaceConfig } from '@vzn/vx'
+import { turbo } from '@vzn/vx-migrate'
+
+export default { plugins: [turbo()] } satisfies WorkspaceConfig
+```
+
 Nothing is rewritten. `@vzn/vx-migrate` is not on npm yet (first publish
 pending); [`examples/turbo`](examples/turbo) runs this setup, and
 `packages/vx/tests/try-it.unsafe.test.ts` runs these exact lines on a Turbo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.187",
+  "version": "0.0.189",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.187",
-    "@vzn/vx-linux-arm64": "0.0.187",
-    "@vzn/vx-darwin-x64": "0.0.187",
-    "@vzn/vx-darwin-arm64": "0.0.187"
+    "@vzn/vx-linux-x64": "0.0.189",
+    "@vzn/vx-linux-arm64": "0.0.189",
+    "@vzn/vx-darwin-x64": "0.0.189",
+    "@vzn/vx-darwin-arm64": "0.0.189"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/cache.ts

@@ -407,6 +407,7 @@ export class Cache implements CacheLayer {
 
   private readonly db: Database
   private readonly insertEntry: ReturnType<Database['prepare']>
+  private readonly deleteEntryRow: ReturnType<Database['prepare']>
   private readonly selectEntry: ReturnType<Database['prepare']>
   private readonly bumpAccessed: ReturnType<Database['prepare']>
   private readonly touched = new Set<string>()
@@ -642,6 +643,7 @@ export class Cache implements CacheLayer {
 
     createTables(this.db)
 
+    this.deleteEntryRow = this.db.prepare('DELETE FROM entries WHERE hash = ?')
     this.insertEntry = this.db.prepare(`
       INSERT INTO entries(hash, project, task, command, exit_code, duration_ms, size_bytes, stdout, created_at, accessed_at, cpu_ms, peak_rss_bytes)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
@@ -951,6 +953,39 @@ export class Cache implements CacheLayer {
     return this.outputs.outputDirsCurrent(projectDir, rows)
   }
   async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
+    try {
+      await this.restoreOutputsOnce(hash, projectDir, workspaceRoot)
+    } catch (err) {
+      if (!(err instanceof CorruptArtifactError)) throw err
+      // Bad bytes under a good key failed the task on every run until
+      // `--force`, since nothing rewrote them (J's lead, nx#30338). The
+      // entry goes, and the caller runs the task, whose save stores it
+      // again; running is always correct, only slower than a hit.
+      if (this.write) await this.dropEntry(hash)
+      throw new ArtifactVanishedError(
+        hash,
+        `${err.message}; ${this.write ? 'dropped it' : 'left it (this cache is read-only)'}`,
+        err,
+      )
+    }
+  }
+
+  /** Remove one entry: its artifact first, then its rows (as `prune` orders them). */
+  private async dropEntry(hash: string): Promise<void> {
+    await rm(this.tarPath(hash), { force: true })
+    try {
+      this.deleteEntryRow.run(hash)
+    } catch (err) {
+      if (!isIndexFull(err)) throw err
+      this.deleteEntryRow.run(hash)
+    }
+  }
+
+  private async restoreOutputsOnce(
+    hash: string,
+    projectDir: string,
+    workspaceRoot?: string,
+  ): Promise<void> {
     // In-process extraction — no fork+exec on the hot path
     // (~5-10ms reclaimed per hit vs the prior subprocess `tar -xf`).
     //

package/src/cache/layer.ts

@@ -476,11 +476,22 @@ export class CorruptArtifactError extends Error {
  * `cacheRetention` of another workspace sharing the cache directory. The
  * bytes are not wrong, they are gone, so the entry is a MISS and the task
  * runs (execute-task.ts); nothing about the cache needs throwing away.
+ * Also thrown, with its `reason`, for an artifact whose bytes ARE wrong
+ * (`CorruptArtifactError` at restore): the entry is dropped and it is a
+ * miss the same way, so the task's save stores it again (A-52).
  */
 export class ArtifactVanishedError extends Error {
-  constructor(public readonly hash: string) {
+  constructor(
+    public readonly hash: string,
+    /** Why the entry cannot be restored, when it is not gone but unreadable. */
+    reason?: string,
+    /** The `CorruptArtifactError` behind a `reason`. */
+    cause?: unknown,
+  ) {
     super(
-      `its cache artifact ${hash} vanished before the restore (a prune or another run's retention)`,
+      reason ??
+        `its cache artifact ${hash} vanished before the restore (a prune or another run's retention)`,
+      cause === undefined ? undefined : { cause },
     )
     this.name = 'ArtifactVanishedError'
   }

package/src/cache/layered-cache.ts

@@ -417,8 +417,8 @@ export class LayeredCache implements CacheLayer {
     } catch (err) {
       // The bytes came off the network — a corrupt/truncated remote
       // artifact must degrade to a cache miss (task re-executes), not
-      // crash the run. Local-layer reads outside this block still
-      // propagate: local corruption is a real fault, not a network one.
+      // crash the run. A corrupt LOCAL artifact is a miss too, one level
+      // down: `Cache.restoreOutputs` drops it (A-52).
       this.reportRemoteError('download', hash, err)
       return false
     }

package/src/cli/init.ts

@@ -149,7 +149,11 @@ async function adopt(
   args: InitArgs,
 ): Promise<number> {
   const name = `vx.workspace.${args.mjs ? 'mjs' : 'ts'}`
-  const body = `import { ${runner} } from '@vzn/vx-migrate'\n\nexport default { plugins: [${runner}()] }`
+  const remote = remoteCacheSignal(root, runner)
+  const cache = REMOTE_CACHE[runner]
+  const imports = remote === undefined ? runner : `${runner}, ${cache}`
+  const plugins = remote === undefined ? `${runner}()` : `${runner}(), ${cache}()`
+  const body = `import { ${imports} } from '@vzn/vx-migrate'\n\nexport default { plugins: [${plugins}] }`
   const text = args.mjs
     ? `${body}\n`
     : `import type { WorkspaceConfig } from '@vzn/vx'\n${body} satisfies WorkspaceConfig\n`
@@ -167,19 +171,69 @@ async function adopt(
     if (existing !== undefined && existing !== name) await unlink(path.join(root, existing))
     await Bun.write(path.join(root, name), text)
   }
-  const wrote =
-    existing !== undefined && !args.force
-      ? `${existing} already declares ${runner}().`
-      : args.dry
-        ? `would write ${name} (dry run, nothing written).`
-        : `wrote ${name}.`
+  const kept = existing !== undefined && !args.force
+  const wrote = kept
+    ? `${existing} already declares ${runner}().`
+    : args.dry
+      ? `would write ${name} (dry run, nothing written).`
+      : `wrote ${name}.`
+  const cacheLine =
+    remote === undefined
+      ? ''
+      : kept && !readFileSync(path.join(root, existing), 'utf8').includes(`${cache}(`)
+        ? `${remote}: add ${cache}() from @vzn/vx-migrate to its plugins and vx shares that remote cache.\n`
+        : kept
+          ? ''
+          : `${cache}(): ${remote}, so vx shares that remote cache (inert where the variable is unset).\n`
   process.stdout.write(
     `vx init: ${source} found — ${runner}() from @vzn/vx-migrate runs this repo as it is; nothing else written.\n` +
-      `${wrote}\n\nnext: ${adoptionNext(root, runner, source)}\n`,
+      `${wrote}\n${cacheLine}\nnext: ${adoptionNext(root, runner, source)}\n`,
   )
   return 0
 }
 
+const REMOTE_CACHE = { turbo: 'turboCache', nx: 'nxCache' } as const
+
+/** The variable each runner's self-hosted remote cache is set by, as its plugin reads it. */
+const REMOTE_CACHE_ENV = { turbo: 'TURBO_TOKEN', nx: 'NX_SELF_HOSTED_REMOTE_CACHE_SERVER' } as const
+
+const CI_FILES = ['.gitlab-ci.yml', '.circleci/config.yml']
+
+/**
+ * Where the repo shows a remote cache its runner uses, or undefined: turbo.json's
+ * enabled `remoteCache`, or a CI file that sets the runner's cache variable (a
+ * local repo holds no token; CI does).
+ */
+function remoteCacheSignal(root: string, runner: 'turbo' | 'nx'): string | undefined {
+  if (runner === 'turbo') {
+    for (const f of ['turbo.json', 'turbo.jsonc']) {
+      let rc: unknown
+      try {
+        rc = (
+          Bun.JSONC.parse(readFileSync(path.join(root, f), 'utf8')) as { remoteCache?: unknown }
+        )?.remoteCache
+      } catch {
+        continue
+      }
+      if (typeof rc === 'object' && rc !== null && (rc as { enabled?: unknown }).enabled !== false)
+        return `${f} names a remoteCache`
+    }
+  }
+  const variable = REMOTE_CACHE_ENV[runner]
+  const workflows = new Bun.Glob('.github/workflows/*.{yml,yaml}')
+  const files = [...workflows.scanSync({ cwd: root, dot: true })].sort().concat(CI_FILES)
+  for (const f of files) {
+    let text: string
+    try {
+      text = readFileSync(path.join(root, f), 'utf8')
+    } catch {
+      continue
+    }
+    if (text.includes(variable)) return `${f} sets ${variable}`
+  }
+  return undefined
+}
+
 type PackageManager = 'pnpm' | 'yarn' | 'bun' | 'npm'
 
 const LOCKFILES: ReadonlyArray<[string, PackageManager]> = [