fix(cache): display server-provided skipped message (#113)

* fix(cache): display server-provided skipped message in cache step

Use the new `skipped_message` field from the StoreResponse proto when
available, falling back to the existing hardcoded message for backward
compatibility with older controllers.

* docs(cache): clarify cache write behavior with read-only tokens

Document that cache writes require read-write tokens, and that
read-only tokens on PRs are expected — cache entries are written
by main branch workflows and restored on PRs.

* docs(cache): update base-branch and cache write docs for scoped tokens

Rewrite base-branch section to reflect that PR branches typically use
read-only tokens and cannot write to cache. Consolidate with the cache
writes section to avoid duplication. Add note about using read-write
tokens on non-protected branches.

Author: llwt

workflow-steps/cache/README.md

@@ -58,21 +58,29 @@ paths: |
 
 ## `base-branch`
 
-For security reasons, this step will only write cache entries **for the current branch only**. This isolation is
-essential, for example, for open source projects, where anyone can create PRs and potentially push malicious artefacts
-to the cache.
+By default, the cache step will only attempt to restore caches written **by the current branch**. This means each
+branch's cache is isolated from other branches.
 
-So by default, if you do not pass the `base-branch`, the cache step will only attempt to restore caches written **by the
-current branch only**. This can be fine, as any subsequent pushes to your PR will re-use the cache, and all the commits
-that go into your
-`main` branch will also re-use the cache.
-
-However, for an extra optimisation, we recommend setting:
+Setting the `base-branch` input allows a branch to fall back to cache entries from another branch when no match is
+found for the current one:
 
 ```yaml
 base-branch: 'main' # or another branch
 ```
 
-This will ensure that when you first open a PR, if a cached entry isn't found for the current branch, it will try to
-look at entries
-on your default protected branch (usually `main`).
+This is especially useful when combined with
+[scoped access tokens](https://nx.dev/docs/concepts/ci-concepts/cache-security#use-scoped-tokens-in-ci) (the
+recommended setup). In this configuration, your protected branch (e.g. `main`) uses a read-write token and writes
+cache entries, while PR branches use read-only tokens and can only restore from the cache. Setting `base-branch`
+ensures PR workflows can still benefit from cache entries written by `main`.
+
+> **Note:** If you use read-write tokens on non-protected branches, each branch will also write its own cache
+> entries, enabling cache reuse across subsequent pushes to the same PR. However, this is **not recommended** as it
+> allows any PR to write to the shared cache, which is a security risk — especially for open source projects where
+> anyone can open a PR and potentially push malicious artifacts.
+
+## Cache writes and access token permissions
+
+The cache step requires a **read-write** access token to write cache entries. If your CI access token only has **read**
+permissions, cache restores will work normally but cache uploads will be skipped with a message indicating the
+token does not have write permissions.

workflow-steps/cache/generated_protos/cache_pb.ts

@@ -210,6 +210,11 @@ export class StoreResponse extends Message<StoreResponse> {
    */
   skipped = false;
 
+  /**
+   * @generated from field: string skipped_message = 3;
+   */
+  skippedMessage = '';
+
   constructor(data?: PartialMessage<StoreResponse>) {
     super();
     proto3.util.initPartial(data, this);
@@ -220,6 +225,12 @@ export class StoreResponse extends Message<StoreResponse> {
   static readonly fields: FieldList = proto3.util.newFieldList(() => [
     { no: 1, name: 'success', kind: 'scalar', T: 8 /* ScalarType.BOOL */ },
     { no: 2, name: 'skipped', kind: 'scalar', T: 8 /* ScalarType.BOOL */ },
+    {
+      no: 3,
+      name: 'skipped_message',
+      kind: 'scalar',
+      T: 9 /* ScalarType.STRING */,
+    },
   ]);
 
   static fromBinary(

workflow-steps/cache/output/main.js

@@ -3510,6 +3510,10 @@ var StoreResponse = class _StoreResponse extends Message {
    * @generated from field: bool skipped = 2;
    */
   skipped = false;
+  /**
+   * @generated from field: string skipped_message = 3;
+   */
+  skippedMessage = "";
   constructor(data) {
     super();
     proto3.util.initPartial(data, this);
@@ -3530,6 +3534,12 @@ var StoreResponse = class _StoreResponse extends Message {
       kind: "scalar",
       T: 8
       /* ScalarType.BOOL */
+    },
+    {
+      no: 3,
+      name: "skipped_message",
+      kind: "scalar",
+      T: 9
     }
   ]);
   static fromBinary(bytes, options) {

workflow-steps/cache/output/post.js

@@ -3498,6 +3498,10 @@ var StoreResponse = class _StoreResponse extends Message {
    * @generated from field: bool skipped = 2;
    */
   skipped = false;
+  /**
+   * @generated from field: string skipped_message = 3;
+   */
+  skippedMessage = "";
   constructor(data) {
     super();
     proto3.util.initPartial(data, this);
@@ -3518,6 +3522,12 @@ var StoreResponse = class _StoreResponse extends Message {
       kind: "scalar",
       T: 8
       /* ScalarType.BOOL */
+    },
+    {
+      no: 3,
+      name: "skipped_message",
+      kind: "scalar",
+      T: 9
     }
   ]);
   static fromBinary(bytes, options) {
@@ -10289,7 +10299,8 @@ if (!!cacheWasHit) {
 Successfully uploaded marked directories.`);
     if (r.skipped)
       console.log(
-        "\nSkipped storing to cache, another instance has already started the upload."
+        `
+${r.skippedMessage || "Skipped storing to cache, another instance has already started the upload."}`
       );
     process.exit(0);
   }).catch((err) => {

workflow-steps/cache/post.ts

@@ -46,7 +46,7 @@ if (!!cacheWasHit) {
       if (r.success) console.log(`\nSuccessfully uploaded marked directories.`);
       if (r.skipped)
         console.log(
-          '\nSkipped storing to cache, another instance has already started the upload.',
+          `\n${r.skippedMessage || 'Skipped storing to cache, another instance has already started the upload.'}`,
         );
       process.exit(0);
     })