@vzn/vx-ci 0.0.636 → 0.0.637

package/README.md

@@ -11,7 +11,7 @@ npm install -D @vzn/vx @vzn/vx-ci   # or: pnpm add -D -w · yarn add -D (-W on Y
 ```
 
 ```ts
-// vx.workspace.ts
+// .vx/workspace.ts
 import { defineWorkspace } from '@vzn/vx/config'
 import { github } from '@vzn/vx-ci'
 
@@ -55,16 +55,16 @@ github({
 
 ## Cache scope
 
-On Actions (`GITHUB_ACTIONS=true`), when `vx.workspace.ts` sets no `cacheScope`, the plugin's
+On Actions (`GITHUB_ACTIONS=true`), when `.vx/workspace.ts` sets no `cache.scope`, the plugin's
 `config` stage sets it from the ref (`GITHUB_REF`, `GITHUB_REF_NAME`, and
-the default branch from the `GITHUB_EVENT_PATH` payload): a push to the default branch stays
-trusted (reads and writes the task keys), a pull request becomes
+the default branch from the `GITHUB_EVENT_PATH` payload): a push to the default branch sets
+none (reads and writes the default keys), a pull request becomes
 `pr-<n>` (so is a `pull_request_target`, `issue_comment` or `workflow_run`
-run on a PR's behalf, by `GITHUB_EVENT_NAME`, though its ref is main's) and any other branch or tag `ref-<name>`, which read their
-own keys, then the trusted ones, and write only their own. A PR never writes what main
-reads. `VX_CACHE_SCOPE` or a `cacheScope` in `vx.workspace.ts` overrides it. This is a client-side convention: the real boundary is a cache
+run on a PR's behalf, by `GITHUB_EVENT_NAME`, though its ref is main's) and any other branch or tag `ref-<name>`, which read the
+default keys, then their own, and write only their own. A PR never writes what main
+reads. Whether a run writes at all is `cache.policy`'s call. `VX_CACHE_SCOPE` or a `cache.scope` in `.vx/workspace.ts` overrides it. This is a client-side convention: the real boundary is a cache
 token the server limits, so give PR jobs one that cannot write the
-trusted keys (`docs/security.md` § Cache poisoning).
+default keys (`docs/security.md` § Cache poisoning).
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.636",
+  "version": "0.0.637",
   "license": "MIT",
   "description": "GitHub Actions integration for vx — a telemetry plugin that writes the run as a GitHub Actions job summary.",
   "keywords": [
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.636"
+    "@vzn/vx": "^0.0.637"
   },
   "repository": {
     "type": "git",

package/src/cache-scope.ts

@@ -1,15 +1,15 @@
 // The cache scope a GitHub Actions run gets when the workspace names none:
-// the default branch is trusted, anything else writes to its own scope.
+// the default branch writes the default keys, anything else its own scope.
 import { readFile } from 'node:fs/promises'
 
 /**
- * `undefined` (leave the workspace's default, trusted) on a push to the
+ * `undefined` (the default keys) on a push to the
  * default branch, outside Actions, or when the ref is unknown; else
  * `pr-<n>` for a pull request and `ref-<name>` for any other branch or tag.
  * An event that runs in the default branch's context on a pull request's
  * behalf (`pull_request_target`, `issue_comment` on a PR, a `workflow_run`
  * a PR started) is the PR's, whatever `GITHUB_REF` says: a workflow that
- * checks out the PR's head there would otherwise write the trusted keys.
+ * checks out the PR's head there would otherwise write the default keys.
  */
 export async function githubCacheScope(
   env: Readonly<Record<string, string | undefined>>,
@@ -26,7 +26,7 @@ export async function githubCacheScope(
   const branch = event?.repository?.default_branch
   if (typeof branch === 'string' && branch !== '' && ref === `refs/heads/${branch}`)
     return undefined
-  // `cacheScope` takes letters, digits and . _ - / @; a ref may hold more.
+  // `cache.scope` takes letters, digits and . _ - / @; a ref may hold more.
   return `ref-${name.replace(/[^\w.@/-]/g, '_').slice(0, 124)}`
 }
 

package/src/index.ts

@@ -1,6 +1,6 @@
 // Public API for @vzn/vx-ci — the GitHub Actions integration plugin.
 //
-// Usage in vx.workspace.ts:
+// Usage in .vx/workspace.ts:
 //   import { defineWorkspace } from '@vzn/vx'
 //   import { github } from '@vzn/vx-ci'
 //   export default defineWorkspace({ plugins: [github()] })

package/src/plugin.ts

@@ -15,7 +15,7 @@ import {
 import type { FetchFn } from './checks.js'
 import { githubCacheScope } from './cache-scope.js'
 
-// Every run evaluates `vx.workspace.ts`; the sink, the summary renderer
+// Every run evaluates `.vx/workspace.ts`; the sink, the summary renderer
 // and the Checks API client load only where a summary file is set. The
 // telemetry hook is synchronous, so the module loads by `require`.
 const loadSink = (): typeof import('./sink.js') => createRequire(import.meta.url)('./sink.js')
@@ -40,8 +40,8 @@ export interface GithubPluginOptions {
   /** Check-run name. Default: `'vx'`. */
   checkName?: string
   /**
-   * Set the workspace's `cacheScope` from the run's ref when it names none:
-   * a push to the default branch stays trusted, a pull request writes to
+   * Set the workspace's `cache.scope` from the run's ref when it names none:
+   * a push to the default branch keeps the default keys, a pull request writes to
    * `pr-<n>`, any other ref to `ref-<name>`. Default: on; `false` opts out.
    */
   cacheScope?: boolean
@@ -95,9 +95,9 @@ export function github(options: GithubPluginOptions = {}): VxPlugin | undefined
   }
   return definePlugin(import.meta, {
     async config(workspace) {
-      if (options.cacheScope === false || workspace.cacheScope !== undefined) return
+      if (options.cacheScope === false || workspace.cache?.scope !== undefined) return
       const scope = await githubCacheScope(process.env)
-      if (scope !== undefined) workspace.cacheScope = scope
+      if (scope !== undefined) workspace.cache = { ...workspace.cache, scope }
     },
     telemetry(ctx) {
       const file = options.summaryFile ?? process.env['GITHUB_STEP_SUMMARY']