@monoai/nscloud-nx-cache-action 0.0.0-stage → 0.1.3

package/docs/configuration.md

@@ -0,0 +1,60 @@
+# Configuration
+
+## GitHub Action inputs
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `archive-directory` | `~/.cache/nx-namespace` | Existing archive directory; mount it before using the action. |
+| `artifact-prefix` | Required | Repository and protocol prefix in Namespace Artifact Storage. |
+| `artifact-region` | `ord` | Namespace storage region. |
+| `access` | `read-only` | `read-only` rejects all uploads; `read-write` enables them. |
+
+The action sets `NX_CACHE_FAILURE_MODE=fail-open` and exposes `nscloud-nx-cache-action`
+and `nx-namespace-token` on PATH. Override environment variables on the wrapped
+command step when needed. Node 24 must already be installed.
+
+## Environment variables
+
+These settings apply when invoking the standalone executable or action launcher.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `NX_ARCHIVE_DIRECTORY` | Required | Persistent local archive directory. |
+| `NX_ARTIFACT_PREFIX` | Unset | Enables Artifact Storage; unset means local-only. |
+| `NX_ARTIFACT_REGION` | `ord` | Artifact Storage region. |
+| `NX_NAMESPACE_TOKEN` | Unset | Explicit Namespace bearer token; otherwise use workload/default SDK credentials. |
+| `NX_CACHE_ACCESS` | `read-write` | `read-only` rejects every PUT, including local writes. The action sets `read-only` by default. |
+| `NX_CACHE_REMOTE_ACCESS` | `read-write` | `read-only` allows local writes and Artifact reads, but skips remote publication. |
+| `NX_CACHE_FAILURE_MODE` | `fail-open` | `strict` reports cache startup, request and publication failures. |
+| `NX_CACHE_DISK_BYTES` | `10737418240` (10 GiB) | Combined archive and extraction allowance. |
+| `NX_CACHE_EXTRACTION_BYTES` | `2147483648` (2 GiB) | Nx extraction-cache cleanup threshold, subtracted from the combined allowance. |
+| `NX_CACHE_ARCHIVE_BYTES` | `536870912` (512 MiB) | Maximum individual archive size. |
+| `NX_CACHE_RETENTION_HOURS` | `168` | Local archive retention. |
+| `NX_CACHE_TRACE` | Unset | Set exactly `1` to emit request-scoped diagnostic spans. |
+
+Numeric settings must be positive safe integers. The archive allowance must exceed
+the maximum individual archive size by at least 4096 bytes. Cleanup thresholds do
+not impose filesystem quotas on arbitrary build outputs.
+
+Credential discovery uses `NX_NAMESPACE_TOKEN` first, then a Namespace workload
+token at `/var/run/nsc/token.json`, then SDK defaults such as `NSC_TOKEN_FILE`.
+Tokens must remain in the process environment or credential file, outside logs.
+
+## Command behavior
+
+```sh
+NX_ARCHIVE_DIRECTORY="$HOME/.cache/nx-namespace" \
+NX_ARTIFACT_PREFIX="nx/v1/owner/repository" \
+NX_CACHE_REMOTE_ACCESS=read-only \
+  node ./nscloud-nx-cache-action.mjs pnpm exec nx run-many -t build
+```
+
+Each invocation starts an authenticated IPv4 loopback listener and sets Nx's
+`NX_SELF_HOSTED_REMOTE_CACHE_SERVER` and access token for the child. The wrapper
+disables the Nx daemon and gives the child fresh workspace metadata and extraction
+directories. It removes these directories after the child and publication drain
+finish; archives in `NX_ARCHIVE_DIRECTORY` persist.
+
+Use one connector process per archive directory. Concurrent Nx tasks within that
+command share the listener. Access flags are client policy; they do not restrict
+what the underlying Namespace identity or mounted filesystem can do.

package/docs/operations.md

@@ -0,0 +1,168 @@
+# Operations
+
+## Storage
+
+Mount persistent archives with [Namespace Cache Volumes](https://namespace.so/docs/architecture/storage/cache-volumes).
+Volumes are forked snapshots; concurrent jobs do not merge every writer's changes.
+[Artifact Storage](https://namespace.so/docs/architecture/storage/artifact-storage)
+supplies immutable shared entries when a local snapshot misses. A successful job
+does not guarantee a later job receives that archive through its volume snapshot.
+
+Use a prefix such as `nx/v1/owner/repository` to separate repositories and protocol
+versions. Prefixes are addresses, rather than authorization boundaries. Provider
+permissions and volume commit restrictions must control which workloads can write.
+
+Local archives use `entries-v1/<task-hash>/` with size, SHA-256 digest and timestamp
+metadata. Writes flush both files before atomic directory publication; reads verify
+regular files, size and digest. Admission reserves space before writing and evicts
+least recently used archives. It inspects at most 16 inventory entries concurrently
+while serializing admission. Abandoned partials older than one hour are removed.
+
+HTTP PUT success acknowledges local admission and queued publication. The command
+drains up to ten concurrent publications before exiting. Only successful completion
+of that drain establishes shared durability. Task failure or cancellation retains
+its exit status while accepted publications drain.
+
+## Credentials and hosted builds
+
+On Namespace runners, the SDK can use the workload credential. Elsewhere, provide
+an Artifact credential through `NX_NAMESPACE_TOKEN` or the SDK's credential file.
+Local-only builds can omit `NX_ARTIFACT_PREFIX` and credentials.
+
+`token.mjs` runs a child with a one-hour Artifact-only credential and revokes it
+after the child exits:
+
+```sh
+NSC_TOKEN_FILE="$HOME/.config/ns/token.json" \
+  node ./token.mjs read-write <deploy-command> <arguments...>
+```
+
+The action exposes the same command as `nx-namespace-token`. The parent credential
+must be authorized to issue and revoke tokens. `read-only` grants Artifact resolve;
+`read-write` grants resolve and create. Grants apply across Artifact Storage in the
+workspace; repository-path grants are unavailable. No compute or IAM grants are
+added to the child token.
+
+For GitHub OIDC, configure the Namespace Cloud GitHub app and exchange the GitHub
+token with `nsc auth exchange-github-token` before running the token wrapper. For
+hosted builds, forward the issued token only to the build environment. For example,
+Vercel deployments can pass it as a build-only variable; keep it out of runtime and
+persistent project environments. Carry the reviewed bundle and license files in
+the deployed source when the build cannot download the release.
+
+See the [Vercel integration guide](vercel.md) for a complete source-deployment
+recipe, including the hosted build command, build-only token forwarding and
+waiting for the build before revocation.
+
+Cache permissions must be enforced by the provider. An HTTP read-only setting
+cannot remove write permission from a runner identity or mounted volume.
+
+## Failures and diagnostics
+
+Fail-open is the default. Startup failure runs the child once with Nx caching
+disabled; optional Artifact setup failure keeps local caching active. Failed GETs
+become misses, failed PUTs can be acknowledged without storage, and publication
+failure preserves a successful task status. A task is never rerun after it starts.
+Use `NX_CACHE_FAILURE_MODE=strict` for validation and durability-sensitive callers.
+
+Token issuance failure also defaults to fail-open, running the child with an empty
+cache token. Revocation failure preserves the child status while the credential
+expires. Strict mode reports either failure.
+
+The listener admits 32 active requests and 128 queued requests. Queue and active
+request deadlines are 120 seconds. Overload returns 503 in strict mode, or a miss
+for GET / discarded-write acknowledgment for PUT in fail-open mode. Deadlines and
+disconnects cancel incomplete input and remote reads.
+
+| Symptom | Check |
+| --- | --- |
+| No adapter events | Confirm the command is wrapped, Nx supports the HTTP protocol, and target caching is enabled. |
+| Repeated misses | Check Nx inputs/outputs, prefix, credentials, region and archive retention. |
+| Expected volume hit uses Artifact Storage | A snapshot may lack the entry; inspect the recorded tier. |
+| Corruption | The invalid local entry is removed; Artifact recovery is attempted. Repeated failure needs storage investigation. |
+| Disk admission failure | Check available space, archive/extraction allowances and maximum archive size. |
+| Successful task with publication errors | Fail-open preserves task success. Reproduce with strict mode. |
+
+Structured events on stderr identify operation, tier, hash, bytes, duration and
+sanitized error codes. The GitHub step summary reports operation counts and I/O
+totals after publication drain. These are neither Nx task counts nor workflow wall
+time. Credentials, signed URLs, archive contents and raw errors must stay out of
+logs. Optional tracing is described in [benchmarking](benchmarking.md).
+
+## Releases
+
+Build and check with the pinned toolchain described in [Contributing](../CONTRIBUTING.md).
+Commit reproducibly generated `dist/` files and qualify the commit on Namespace.
+Run the release workflow manually from main with a new `vMAJOR.MINOR.PATCH` tag
+matching `package.json`. It checks the committed distribution and prepares a draft
+release with executables, checksums and license notices.
+Publish the draft after verifying its assets and qualifying the commit on Namespace.
+Existing tags must remain immutable. Consumers pin a reviewed commit or verify a
+pinned release's checksums.
+
+Publishing a release also triggers this workflow. It checks out the tagged commit,
+requires that commit to be in main's history, verifies the version and committed
+bundles, and uploads any missing release files. Existing files must match the
+reviewed build byte for byte; retries do not replace them. Wait for the workflow
+to finish before using standalone downloads when creating a release without
+prepared assets. The GitHub Action itself uses the committed `dist/` files.
+
+Draft creation does not trigger GitHub Actions. Prefer the manual draft flow when
+all downloads must be present at publication, including when GitHub release
+immutability is enabled. The automatic workflow packages assets; it does not
+change repository visibility, move version tags or create a Marketplace listing.
+
+### First public publication
+
+Keep the source import's fresh history. Do not push refs from a private predecessor
+or copy measured workload profiles, archives or results into this repository.
+Review every exposed branch and tag, release asset, issue and workflow artifact
+before changing visibility; scan the Git history and distributed files for secrets.
+
+Prepare a new patch release from the qualified main commit when metadata or docs
+change. Verify the draft's checksums, license files and executable bytes against
+the reviewed build. Record the Namespace and separate-repository consumer checks;
+offline checks do not establish runner storage behavior. Keep existing releases
+and tags unchanged.
+
+After approval to publish, make this repository public and publish the reviewed
+draft. Public workflows can then use `monoai-labs/nscloud-nx-cache-action@<tag>`
+without private-repository sharing. Prefer a full commit SHA in usage examples.
+Check access from an unauthenticated session and a separate consumer repository.
+
+GitHub Marketplace is a separate listing step. Use the release page's **Publish
+this Action to the GitHub Marketplace** option, with **Continuous integration**
+as the primary category. The root `action.yml` supplies the name, description and
+branding. GitHub validates name availability there; do not claim a listing until
+that check passes. An organization owner must accept the Marketplace Developer
+Agreement, and publishing requires two-factor authentication. Follow
+[GitHub's publication instructions](https://docs.github.com/en/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace).
+
+The repository description should describe local archives and Namespace Artifact
+Storage; avoid latency or performance claims without published measurements.
+
+### npm publishing
+
+The CLI package is `@monoai/nscloud-nx-cache-action`. Stable release publication
+also packs and publishes that version to npm after the audit, tests, reproducible
+build and release-asset checks pass. The manual draft flow prepares the package
+without publishing it. A retry verifies the existing npm tarball integrity and
+skips publication only when the bytes match; lookup failures and conflicts fail.
+
+Configure the package's npm trusted publisher for GitHub owner `monoai-labs`,
+repository `nscloud-nx-cache-action`, workflow `release.yml`, with direct
+`npm publish` allowed. The workflow uses a GitHub-hosted runner and `id-token: write`;
+it needs no npm token secret. The pinned Node distribution includes npm 11.19.0,
+which supports OIDC. npm automatically adds provenance for the public package.
+See [npm's trusted publisher instructions](https://docs.npmjs.com/trusted-publishers/).
+
+If the package is not yet present on npm, its owner must complete the initial
+publication and publisher setup before automated release publishing can succeed.
+Configure the publisher close to the release: npm requires its first successful
+publish within two days. Keep npm versions immutable, just like release tags.
+
+Verify packaging locally with `pnpm build` and `pnpm package:pack`. The package test
+installs the actual tarball into an isolated workspace and exercises both binaries.
+Only the two executables, public guides, package metadata and license notices ship.
+TypeScript remains strictly checked; there is no importable library API or fabricated
+declaration file. Minification preserves function/class names and legal comments.

package/docs/vercel.md

@@ -0,0 +1,187 @@
+# Using the cache with Vercel
+
+For a source deployment, GitHub runs the deployment command and Vercel runs the
+application build. The cache executable must run around Nx **inside that build**.
+The GitHub Action's PATH and environment changes stay in the GitHub job.
+
+This guide uses an existing Nx/pnpm workspace, an application at `apps/web`, and
+an Nx target named `web:build`. Substitute your application's path and target.
+Use Node 24.x on Vercel; the connector is tested with Nx 23.3.0. Pin pnpm through
+your root `packageManager` field and commit its lockfile. Configure Vercel's
+[package-manager selection](https://vercel.com/docs/package-managers) to use that pin.
+
+## Put the release files in the deployed source
+
+Download the executables and notices from a reviewed
+[release](https://github.com/monoai-labs/nscloud-nx-cache-action/releases), such as
+v0.1.0. Keep the complete set together in your repository:
+
+```text
+tools/nx-cache/
+  nscloud-nx-cache-action.mjs
+  token.mjs
+  SHA256SUMS
+  LICENSE
+  NOTICE
+  THIRD_PARTY_LICENSES.txt
+  vercel-build.sh
+apps/web/vercel.json
+```
+
+Before committing the release files, verify them from `tools/nx-cache` with
+`sha256sum --check SHA256SUMS`, or `shasum -a 256 --check SHA256SUMS` on macOS.
+Copying the files also supports private releases that a hosted builder cannot
+download. Keep a record of the reviewed release and commit when updating them.
+
+Set the Vercel project's Root Directory to `apps/web` and enable
+[source files outside the Root Directory](https://vercel.com/docs/monorepos/monorepo-faq).
+Submit source from the workspace root so the lockfile, shared packages and cache
+files are included. Check `.vercelignore` and Git ignore rules: if they exclude
+your chosen bundle directory or `*.mjs`, add exceptions for these release files.
+
+## Wrap the Nx build in Vercel
+
+Create `tools/nx-cache/vercel-build.sh`:
+
+```sh
+#!/usr/bin/env sh
+set -eu
+
+cache_script_directory=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+cache_workspace_root=$(CDPATH='' cd -- "$cache_script_directory/../.." && pwd)
+cd "$cache_workspace_root"
+
+export NX_ARCHIVE_DIRECTORY="$cache_workspace_root/node_modules/.cache/nx-namespace"
+export NX_ARTIFACT_PREFIX="${NX_ARTIFACT_PREFIX:-nx/v1/your-org/your-repo}"
+
+if [ -z "${NX_NAMESPACE_TOKEN:-}" ]; then
+  unset NX_ARTIFACT_PREFIX
+fi
+
+exec node "$cache_script_directory/nscloud-nx-cache-action.mjs" \
+  corepack pnpm exec nx "$@"
+```
+
+Replace `nx/v1/your-org/your-repo` with your repository's cache prefix. Use the
+**same prefix and Artifact region** for CI and Vercel when they should share
+entries. The region defaults to `ord`; use `NX_ARTIFACT_REGION` to override it.
+Prefixes partition entries, while provider permissions enforce access.
+
+The wrapper uses a workspace-local archive directory. Vercel does not mount a
+Namespace NVMe Cache Volume; Artifact Storage supplies the shared tier. The
+tokenless branch explicitly selects local-only caching, including Git-triggered
+builds that have no issued credential.
+
+Merge these commands into `apps/web/vercel.json`, retaining your framework,
+output and other application settings:
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "installCommand": "cd ../.. && corepack pnpm install --frozen-lockfile",
+  "buildCommand": "sh ../../tools/nx-cache/vercel-build.sh run web:build"
+}
+```
+
+This wrapper calls the Nx executable directly. If your existing `pnpm nx` script
+already starts the connector, keep one wrapper rather than nesting them. Nx still
+owns dependency builds and task selection. Only cache deterministic targets with
+correct inputs and outputs; migrations and deployment side effects must execute
+normally. An application build can remain uncached while reusing package builds.
+
+## Send a short-lived credential with the source deployment
+
+Connect the Namespace Cloud GitHub app for the deploying repository. The GitHub
+OIDC identity must be allowed to issue and revoke Artifact credentials. Configure
+Vercel's token and the IDs of an existing Vercel project in GitHub; pin the Vercel
+CLI in your workspace's development dependencies.
+
+This example runs from the workspace root on trusted main pushes. It uses the
+copied token helper, so it does not require installing this GitHub Action or
+mounting a Namespace volume in the deployment job:
+
+```yaml
+name: Deploy web
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+      NX_CACHE_FAILURE_MODE: strict
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24.21.0
+          package-manager-cache: false
+      - run: corepack enable
+      - run: corepack pnpm install --frozen-lockfile
+      - uses: namespacelabs/nscloud-setup@df198f982fcecfb8264bea3f1274b56a61b6dfdc # v0.0.12
+      - run: nsc auth exchange-github-token
+      - name: Deploy source and wait for its build
+        run: |
+          NSC_TOKEN_FILE="$HOME/.config/ns/token.json" \
+            node tools/nx-cache/token.mjs read-write \
+            corepack pnpm exec vercel deploy --yes --prod \
+            --build-env NX_NAMESPACE_TOKEN \
+            --build-env NX_CACHE_FAILURE_MODE=strict
+```
+
+`--build-env NX_NAMESPACE_TOKEN` forwards the credential from the token helper's
+child environment to Vercel's build. Do not use `--env` or persist this token in
+Vercel project settings. Vercel distinguishes
+[build variables from runtime variables](https://vercel.com/docs/cli/deploy#build-env).
+The example uses strict mode for both issuance and the hosted cache, so an access
+failure cannot look like successful cache qualification. After qualification,
+choose fail-open if builds should proceed when caching is unavailable.
+
+The helper revokes the credential when its child exits, and its maximum lifetime
+is one hour. Keep that child running until the remote build finishes. Do not add
+[`--no-wait`](https://vercel.com/docs/cli/deploy#no-wait); an API-based deployment
+client must poll for build completion before returning too. Build queue time
+counts toward the credential lifetime. Do not print the token or enable shell
+tracing around credential handling.
+
+For trusted previews, remove `--prod` and deliberately choose the preview's
+publication policy. To prevent shared publication, issue a `read-only` token and
+pass `--build-env NX_CACHE_REMOTE_ACCESS=read-only`; this retains local writes.
+Setting `NX_CACHE_ACCESS=read-only` also disables local archive writes. Use your
+existing deployment admission rules for untrusted branches and forks. Choose
+which deployment system owns each environment to avoid duplicate CLI and native
+Git builds.
+
+## Validate the hosted path
+
+First qualify a non-production deployment with strict cache failure mode:
+
+1. Confirm the uploaded source contains the reviewed executable and that the
+   build log shows the wrapper invoking your intended Nx target.
+2. Check for successful Artifact publications from eligible cacheable targets.
+3. Start a fresh source deployment with unchanged task inputs. Confirm Artifact
+   hits, matching restored outputs, and no executor runs for those targets. A
+   framework build or unrelated uncached task may still run.
+4. Change a declared input and confirm the affected task executes again.
+5. Confirm the deployment request has a build-only cache credential, and that
+   the deployment client waits through the build before the helper exits.
+
+Successful deployment alone is not evidence of caching: fail-open mode can build
+everything normally after a cache failure. The connector writes structured
+events to build stderr; Vercel does not provide GitHub step summaries. Keep the
+prefix and region consistent and check that every intended task declares caching.
+
+For `vercel build` followed by `vercel deploy --prebuilt`, the build runs in your
+CI environment instead. `vercel build` executes the configured build command,
+which starts the Nx wrapper there. Give the build process its cache credential
+and hold that credential until the local build finishes; do not add another cache
+wrapper around `vercel build`. The prebuilt upload performs no remote Nx build
+and needs no cache credential. Fetch the project's settings with `vercel pull`
+before building, as described in
+[Vercel's local build documentation](https://vercel.com/docs/cli/build).

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@monoai/nscloud-nx-cache-action",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "CLI tools for Nx HTTP caching across local development, Namespace runners and hosted builds, with local archives, shared Artifact Storage and short-lived build credentials.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "nscloud-nx-cache-action": "dist/nscloud-nx-cache-action.mjs",
+    "nx-namespace-token": "dist/token.mjs"
+  },
+  "files": [
+    "dist/nscloud-nx-cache-action.mjs",
+    "dist/token.mjs",
+    "docs/configuration.md",
+    "docs/operations.md",
+    "docs/vercel.md",
+    "docs/benchmarking.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_LICENSES.txt"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/monoai-labs/nscloud-nx-cache-action.git"
+  },
+  "homepage": "https://github.com/monoai-labs/nscloud-nx-cache-action#readme",
+  "bugs": {
+    "url": "https://github.com/monoai-labs/nscloud-nx-cache-action/issues"
+  },
+  "keywords": [
+    "nx",
+    "namespace",
+    "cache",
+    "cli",
+    "github-actions"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "packageManager": "pnpm@11.22.0",
+  "engines": {
+    "node": "24.x"
+  },
+  "scripts": {
+    "check": "pnpm run config:check && pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm test",
+    "config:check": "tsx scripts/validate-config.ts",
+    "format": "oxfmt --write src scripts tests bench package.json tsconfig.json .oxlintrc.json .oxfmtrc.json",
+    "format:check": "oxfmt --check src scripts tests bench package.json tsconfig.json .oxlintrc.json .oxfmtrc.json",
+    "lint": "oxlint --deny-warnings src scripts tests bench",
+    "lint:fix": "pnpm run lint --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts",
+    "fixture": "tsx scripts/generate-fixture.ts",
+    "integration:restoration": "tsx scripts/integration-restoration.ts",
+    "integration:contracts": "tsx scripts/contract-check.ts",
+    "build": "tsx scripts/build.ts",
+    "package:pack": "npm pack --pack-destination .output/npm",
+    "publish:npm": "tsx scripts/publish-npm.ts",
+    "bench:restoration:offline": "tsx bench/restoration/offline.ts",
+    "bench:restoration:live": "tsx bench/restoration/run.ts",
+    "bench:restoration:analyze": "tsx bench/restoration/analyze.ts"
+  },
+  "devDependencies": {
+    "@bufbuild/protobuf": "2.14.1",
+    "@connectrpc/connect": "2.2.0",
+    "@namespacelabs/sdk": "1.0.0",
+    "@types/node": "^24.19.2",
+    "ajv": "8.20.0",
+    "esbuild": "0.28.2",
+    "nx": "23.3.0",
+    "oxfmt": "0.71.0",
+    "oxlint": "1.86.0",
+    "tsx": "4.23.13",
+    "typescript": "5.9.3",
+    "yaml": "2.9.0"
+  }
+}