@vzn/vx-ci 0.0.644 → 0.0.646

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vx contributors
+Copyright (c) 2026 VZN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,7 +8,7 @@ page and names the run's cache scope; `gitlab()` names the run's cache
 scope on GitLab CI ([below](#gitlab-ci)).
 
 ```sh
-npm install -D @vzn/vx @vzn/vx-ci   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
+bun add -d @vzn/vx @vzn/vx-ci
 ```
 
 ```ts
@@ -50,7 +50,7 @@ github({
   title: 'build & test', // default: 'vx run'
   checks: true, // default: on with GITHUB_TOKEN; true warns when it is missing, false opts out
   checkName: 'ci', // default: 'vx', the check run's name
-  cacheScope: false, // default: on; scope remote cache writes by ref
+  cacheScope: false, // default: on; scope plugin cache entries by ref
 })
 ```
 
@@ -59,26 +59,19 @@ github({
 On Actions (`GITHUB_ACTIONS=true`) the plugin's `config` stage names the
 run's branch through `ctx.setBranch`, from the ref (`GITHUB_REF`,
 `GITHUB_REF_NAME`, `GITHUB_HEAD_REF`, `GITHUB_REPOSITORY`) and the
-`GITHUB_EVENT_PATH` payload. A push to the default branch names no scope (reads and writes
-the default keys). A push to, or a pull request from, a branch names
+`GITHUB_EVENT_PATH` payload. A push to the default branch names no scope.
+A push to, or a pull request from, a branch names
 `<owner>/<repo>:<branch>` of the repository the branch lives in, so a
 fork's pull request names the fork; so does a `pull_request_target` or
 `workflow_run` run on a PR's behalf (by `GITHUB_EVENT_NAME`, though its
 ref is main's), and an `issue_comment` on a PR, which names no branch,
 `pr-<n>`. A merge queue's run (`merge_group`) is trusted: no scope,
-whatever its `gh-readonly-queue/...` branch, so it reads and writes only
-the default keys (`x-vx-cache-scope: trusted`), compared with
+whatever its `gh-readonly-queue/...` branch, compared with
 `merge_group.base_sha`. A pull request also names its base commit
-(`pull_request.base.sha`), so vx diffs the merge checkout from it with
-no git call. A scoped run's changed tasks read the scope's remote entry,
-the rest the default keys, and every task it builds is saved to the
-remote under the scope; the local cache never knows a scope. A
-PR never writes what main reads, and a laptop on the branch derives the
-same scope. Whether a run writes at all is `cache.policy`'s call.
-`VX_CACHE_SCOPE` 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 default keys (`docs/security.md` § Cache
-poisoning).
+(`pull_request.base.sha`), the base of a bare `--affected`. The scope
+keys only what plugins store themselves (`ctx.cache`, run records):
+task keys never carry it, and the cache server decides from the CI OIDC
+token where a task's entry lands. `VX_CACHE_SCOPE` overrides it.
 
 ## GitLab CI
 
@@ -99,10 +92,10 @@ subgroup's project is `group/sub/app:feat-x`, the scope a laptop on
 `feat-x` derives. A merge request pipeline names its source branch
 (`CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`) in the project it lives in (a
 fork's `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and its diff base
-(`CI_MERGE_REQUEST_DIFF_BASE_SHA`), so vx diffs from it with no git
-call. A merge train's pipeline (`CI_MERGE_REQUEST_EVENT_TYPE=merge_train`)
-builds what lands on the target, so it is trusted: no scope, only the
-default keys. `gitlab({ cacheScope: false })` (`GitlabPluginOptions`) turns it off;
+(`CI_MERGE_REQUEST_DIFF_BASE_SHA`), the base of a bare `--affected`.
+A merge train's pipeline (`CI_MERGE_REQUEST_EVENT_TYPE=merge_train`)
+builds what lands on the target, so it is trusted: no scope. As on
+Actions, the scope keys only plugin entries. `gitlab({ cacheScope: false })` (`GitlabPluginOptions`) turns it off;
 `VX_CACHE_SCOPE` overrides it. Anywhere else `gitlab()` returns
 `undefined`, so declaring both plugins is safe. Merge request comments
 and reports are not part of it yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.644",
+  "version": "0.0.646",
   "license": "MIT",
   "description": "GitHub Actions and GitLab CI integration for vx — a job summary on Actions and the branch cache scope on both.",
   "keywords": [
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.644"
+    "@vzn/vx": "^0.0.646"
   },
   "repository": {
     "type": "git",

package/src/cache-scope.ts

@@ -1,6 +1,6 @@
 // The cache scope and base commit a GitHub Actions run names through
-// `setBranch`: the default branch writes the default keys, a branch its own
-// scope, the one a laptop on that branch reads (owner, 2026-10-17).
+// `setBranch`: none on the default branch, a branch its own scope, the one
+// a laptop on that branch derives (owner, 2026-10-17).
 import { readFile } from 'node:fs/promises'
 import { type BranchFacts, branchCacheScope } from '@vzn/vx'
 
@@ -13,10 +13,10 @@ import { type BranchFacts, branchCacheScope } from '@vzn/vx'
  * derives. 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
- * default keys. `issue_comment` names no branch, so it writes `pr-<n>`.
+ * workflow that checks out the PR's head there would otherwise share main's
+ * scope. `issue_comment` names no branch, so it writes `pr-<n>`.
  * A merge queue's run (`merge_group`) is trusted (owner, 2026-10-18): no
- * scope, only the default keys, compared with `merge_group.base_sha`.
+ * scope, compared with `merge_group.base_sha`.
  * `base`: a pull request's base commit (`pull_request.base.sha`), what its
  * merge checkout is compared with, no git call needed.
  */

package/src/gitlab.ts

@@ -14,9 +14,9 @@ import {
 export interface GitlabPluginOptions {
   /**
    * Name the run's cache scope and base commit from GitLab's predefined
-   * variables: the default branch and a merge train read and write the
-   * default keys, any other branch `<project path>:<branch>`, and a merge
-   * request is compared with its diff base. `VX_CACHE_SCOPE` beats it.
+   * variables: none on the default branch or a merge train, else
+   * `<project path>:<branch>`; a merge request is compared with its diff
+   * base. The scope keys plugin entries only. `VX_CACHE_SCOPE` beats it.
    * Default: on; `false` opts out.
    */
   cacheScope?: boolean

package/src/index.ts

@@ -8,9 +8,32 @@
 // On a GitHub Actions runner (GITHUB_STEP_SUMMARY set) every `vx run`
 // appends a job summary: verdict, stats, failures, and the per-task table.
 // Anywhere else the plugin declines and costs nothing.
-export { github, type GithubPluginOptions } from './plugin.js'
-export { gitlab, type GitlabPluginOptions } from './gitlab.js'
-export { renderJobSummary } from './summary.js'
+import { createRequire } from 'node:module'
+import type { RunSummaryRecord, VxPlugin } from '@vzn/vx'
+import type { GithubPluginOptions } from './plugin.js'
+import type { GitlabPluginOptions } from './gitlab.js'
+
+export type { GithubPluginOptions, GitlabPluginOptions }
+
+// Every run evaluates `.vx/workspace.ts`, and off CI both factories
+// decline: this file is all a laptop loads (five files were ~1.1 ms of
+// every run). Each module loads on its own CI, by `require` as the
+// factories are synchronous.
+const load = createRequire(import.meta.url)
+
+export function github(options?: GithubPluginOptions): VxPlugin | undefined {
+  if (process.env['GITHUB_ACTIONS'] !== 'true') return undefined
+  return (load('./plugin.js') as typeof import('./plugin.js')).github(options)
+}
+
+export function gitlab(options?: GitlabPluginOptions): VxPlugin | undefined {
+  if (process.env['GITLAB_CI'] !== 'true') return undefined
+  return (load('./gitlab.js') as typeof import('./gitlab.js')).gitlab(options)
+}
+
+export function renderJobSummary(summary: RunSummaryRecord, title?: string): string {
+  return (load('./summary.js') as typeof import('./summary.js')).renderJobSummary(summary, title)
+}
 
 // The Checks API helpers are the plugin's own; only the transport type
 // the options name is public (1.0 freezes what this file exports).

package/src/plugin.ts

@@ -40,11 +40,11 @@ export interface GithubPluginOptions {
   /** Check-run name. Default: `'vx'`. */
   checkName?: string
   /**
-   * Name the run's cache scope and base commit from the Actions event: a
-   * push to the default branch keeps the default keys, a branch or its pull
-   * request writes to `<owner>/<repo>:<branch>` (a fork's names the fork),
-   * and a pull request is compared with its base commit. `VX_CACHE_SCOPE`
-   * beats it. Default: on; `false` opts out.
+   * Name the run's cache scope and base commit from the Actions event: none
+   * on the default branch, else `<owner>/<repo>:<branch>` (a fork's names
+   * the fork); a pull request is compared with its base commit. The scope
+   * keys plugin entries only. `VX_CACHE_SCOPE` beats it. Default: on;
+   * `false` opts out.
    */
   cacheScope?: boolean
   /** Test seam — inject the append. Defaults to fs appendFile. */