vite-plus 0.2.1 → 0.2.2

package/docs/guide/docker.md

@@ -0,0 +1,175 @@
+# Docker
+
+Vite+ publishes an official Docker image with the `vp` CLI preinstalled:
+
+```bash
+ghcr.io/voidzero-dev/vite-plus
+```
+
+Use it for builds, CI, and devcontainers. It is not intended as a production
+runtime image.
+
+`vp` resolves the Node.js version from your project (`.node-version`,
+`devEngines.runtime`, or `engines.node`) and downloads that exact version during
+install/build. This means the image does not need Node-version-specific tags.
+
+For production, use a multi-stage build: build the app with the Vite+ image, then
+copy only the resolved Node.js binary, build output, and production dependencies
+into a smaller runtime image.
+
+## Image tags
+
+Tags track the `vp` version:
+
+| Tag                                                      | Meaning        |
+| -------------------------------------------------------- | -------------- |
+| `ghcr.io/voidzero-dev/vite-plus:latest`                  | Latest release |
+| `ghcr.io/voidzero-dev/vite-plus:<major>`                 | Latest major   |
+| `ghcr.io/voidzero-dev/vite-plus:<major>.<minor>`         | Latest minor   |
+| `ghcr.io/voidzero-dev/vite-plus:<major>.<minor>.<patch>` | Exact version  |
+
+The examples use `:latest` to track the newest release; pin an exact tag or a
+digest if you need reproducible builds. The image is published for `linux/amd64`
+and `linux/arm64` and runs as a non-root user by default.
+
+Browse all published versions and digests on the [GitHub package page](https://github.com/voidzero-dev/vite-plus/pkgs/container/vite-plus).
+
+## Production: SSR / Node.js server app
+
+For apps that run Node.js in production (SvelteKit, Nuxt, a custom Vite SSR
+server, and so on), build with the toolchain image and copy the resolved Node.js
+and the built app into a slim runtime stage:
+
+```dockerfile [Dockerfile]
+# syntax=docker/dockerfile:1
+
+# --- build stage: the official Vite+ toolchain image ---
+FROM ghcr.io/voidzero-dev/vite-plus:latest AS build
+WORKDIR /app
+
+# Install dependencies first so this layer is cached across source changes.
+COPY --chown=vp:vp package.json pnpm-lock.yaml .node-version* ./
+RUN vp install --frozen-lockfile
+
+# Build. vp reads .node-version and provisions that exact Node.js automatically.
+COPY --chown=vp:vp . .
+RUN vp build
+
+# Export the exact resolved Node.js binary for the runtime stage.
+RUN cp "$(vp env which node | head -1)" /tmp/node
+
+# --- deps stage: production-only dependencies ---
+# A separate, fresh `--prod` install so devDependencies (including the vite-plus
+# toolchain) are excluded. Running `--prod` over the full install above would not
+# prune the already-installed devDependencies.
+FROM ghcr.io/voidzero-dev/vite-plus:latest AS deps
+WORKDIR /app
+COPY --chown=vp:vp package.json pnpm-lock.yaml .node-version* ./
+RUN vp install --frozen-lockfile --prod
+
+# --- runtime stage: small, glibc, no vp ---
+FROM debian:bookworm-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+
+# The exact Node.js from .node-version (official, signature-verified build).
+COPY --from=build /tmp/node /usr/local/bin/node
+
+COPY --from=build /app/dist ./dist
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/package.json ./
+
+USER nobody
+EXPOSE 3000
+CMD ["node", "dist/server.js"]
+```
+
+The deployed image contains only Node.js plus your app and production
+dependencies, and matches `.node-version` exactly. It is much smaller than the
+default `node:*` image; see the distroless tip below for the smallest result.
+
+::: warning Prune production dependencies in a separate stage
+Install production dependencies in their own `deps` stage as shown. Running
+`vp install --prod` after a full `vp install` in the same stage does not remove
+the already-installed devDependencies, so the `vite-plus` toolchain would be
+copied into the runtime image. If your server bundle is fully self-contained (no
+un-bundled runtime dependencies), you can skip copying `node_modules` entirely.
+:::
+
+::: tip Smaller still
+For a shell-less, minimal-CVE runtime, swap the runtime base for distroless
+(`gcr.io/distroless/cc`) and keep an `ENTRYPOINT` in vector form. It is glibc
+based, so the copied Node.js binary remains compatible.
+:::
+
+## Production: static SPA / SSG
+
+A static site needs no Node.js at runtime; serve the build output with any static
+server:
+
+```dockerfile [Dockerfile]
+FROM ghcr.io/voidzero-dev/vite-plus:latest AS build
+WORKDIR /app
+COPY --chown=vp:vp package.json pnpm-lock.yaml .node-version* ./
+RUN vp install --frozen-lockfile
+COPY --chown=vp:vp . .
+RUN vp build
+
+FROM nginx:alpine AS runtime
+COPY --from=build /app/dist /usr/share/nginx/html
+```
+
+## Continuous integration
+
+Use the image directly in container-based CI (GitLab CI, Buildkite, CircleCI,
+Jenkins, and others):
+
+```yaml [.gitlab-ci.yml]
+build:
+  image: ghcr.io/voidzero-dev/vite-plus:latest
+  script:
+    - vp install --frozen-lockfile
+    - vp check
+    - vp test
+    - vp build
+```
+
+On GitHub Actions, prefer [`setup-vp`](./ci) instead of the image.
+
+## Devcontainers
+
+Use the image as a ready-to-go development container with the toolchain
+preinstalled:
+
+```jsonc [.devcontainer/devcontainer.json]
+{
+  "image": "ghcr.io/voidzero-dev/vite-plus:latest",
+}
+```
+
+## Ad-hoc usage
+
+Run any `vp` command against a project without installing vp on your machine:
+
+```bash
+docker run --rm -it -v "$PWD:/app" -w /app ghcr.io/voidzero-dev/vite-plus vp build
+```
+
+## Notes
+
+- **Node.js version**: provisioned from `.node-version`, `engines.node`, or
+  `devEngines.runtime` at build time, so there is no Node.js-specific image tag. The
+  dependency `COPY` uses a `.node-version*` glob so the file is optional: projects
+  that pin via `engines.node`/`devEngines.runtime` need no `.node-version`, and
+  those that use one have it available in every stage.
+- **Non-root user**: the image runs as the non-root `vp` user, so copy sources
+  with `COPY --chown=vp:vp ...` as shown. Without it, `COPY` writes root-owned
+  files that `vp install` cannot update (permission denied).
+- **Native addons**: the image includes a C/C++ build toolchain (`build-essential`,
+  `python3`), so native dependencies such as `better-sqlite3` compile during
+  `vp install`.
+- **glibc**: the image is glibc based so it uses the official, signature-verified
+  Node.js builds.
+- **Custom base image**: to add `vp` to your own base image instead, run the
+  installer: `curl -fsSL https://vite.plus | bash` (set `VP_VERSION` to pin a
+  version).

package/docs/guide/env.md

@@ -153,3 +153,15 @@ VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist vp env default lts
 # Set it permanently in your shell profile (.bashrc, .zshrc, etc.)
 echo 'export VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist' >> ~/.zshrc
 ```
+
+## Node.js Signature Verification
+
+When installing Node.js from the official `nodejs.org` distribution, Vite+ downloads the PGP-signed `SHASUMS256.txt.asc` and verifies it against the bundled Node.js release keys before trusting any checksum. This protects against a tampered `SHASUMS256.txt` paired with a matching malicious archive. The SHA-256 checksum of the downloaded archive is always verified afterward.
+
+Custom mirrors (`VP_NODE_DIST_MIRROR`) that publish only the plain `SHASUMS256.txt` fall back to checksum-only verification. A mirror that does publish a `.asc` still has its signature verified, and an invalid signature is a hard error.
+
+If a future keyring or certificate issue blocks downloads, set `VP_NODE_SKIP_SIGNATURE_VERIFY` to temporarily bypass PGP verification. The SHA-256 checksum is still verified, and Vite+ prints a warning when the signature check is skipped:
+
+```bash
+VP_NODE_SKIP_SIGNATURE_VERIFY=1 vp env install 22
+```

package/docs/guide/github-actions-cache.md

@@ -0,0 +1,165 @@
+# GitHub Actions Cache
+
+::: warning Experimental
+Reusing Vite Task's cache across GitHub Actions runs is experimental. Test and measure it in your project before relying on it in CI.
+:::
+
+Vite Task stores task results in `node_modules/.vite/task-cache` at the workspace root. Restore that directory in later GitHub Actions runs so Vite Task can reuse previous task results.
+
+GitHub Actions cache and Vite Task make separate decisions:
+
+1. `actions/cache` restores and saves the cache directory based on the key in your workflow.
+2. Vite Task uses the restored cache directory and replays only the tasks whose fingerprints still match.
+
+## Before You Start
+
+Use this workflow when all of these are true:
+
+- The command runs through [`vp run`](/guide/run).
+- An immediate second run reports a cache hit for the task.
+- The task has stable input and output tracking for CI.
+- The workflow installs dependencies before restoring `node_modules/.vite/task-cache`.
+
+If the immediate second run misses, fix the task's tracking config before adding GitHub Actions cache. Check [When To Add Manual Config](/guide/automatic-data-tracking#when-to-add-manual-config) for common causes of unstable caching and fixes.
+
+## Measure Before Caching Across Runs
+
+You may not need to restore Vite Task cache across GitHub Actions runs when:
+
+- The task is already fast enough. Restore and save steps add overhead, so short tasks can finish faster without this workflow.
+- Cache transfer takes longer than rerunning the task. Vite Task can still save time inside one workflow run when the same task runs more than once, but across runs the transfer time is part of the cost.
+
+Measure before you add a GitHub Actions cache for Vite Task. Compare workflow duration with and without the restore and save steps. Check both the GitHub cache step time and the `vp run` time.
+
+## 1. Define Cacheable CI Tasks
+
+Only commands run through `vp run` use Vite Task caching. A direct command such as `vp build` does not use the task cache. Define a task in `vite.config.ts` for each command you want to cache in CI:
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  run: {
+    tasks: {
+      build: 'vp build',
+      lint: 'vp lint',
+    },
+  },
+});
+```
+
+This guide assumes each task already hits locally. If a task misses, fix its tracking config in `vite.config.ts` before adding the GitHub Actions cache steps. See [Automatic Data Tracking](/guide/automatic-data-tracking) and [`run.tasks`](/config/run#tasks).
+
+Run each task twice:
+
+```bash
+vp run build
+vp run build # should print "cache hit"
+vp run lint
+vp run lint # should print "cache hit"
+```
+
+## 2. Restore The Cache After Install
+
+Restore `node_modules/.vite/task-cache` after `vp install`, because package installation can recreate or modify `node_modules`.
+
+```yaml [.github/workflows/ci.yml]
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: voidzero-dev/setup-vp@v1
+        with:
+          node-version: '24'
+          cache: true
+
+      - run: vp install
+
+      - name: Restore Vite Task cache
+        id: vite-task-cache
+        uses: actions/cache/restore@v6
+        with:
+          path: node_modules/.vite/task-cache
+          key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }}
+          restore-keys: |
+            vite-task-${{ runner.os }}-${{ runner.arch }}-
+
+      - run: vp run lint
+      - run: vp run build
+
+      - name: Save Vite Task cache
+        if: success()
+        uses: actions/cache/save@v6
+        with:
+          path: node_modules/.vite/task-cache
+          key: ${{ steps.vite-task-cache.outputs.cache-primary-key }}
+```
+
+The primary key includes `github.run_id` and `github.run_attempt` so each successful run can save a new immutable cache entry. The restore prefix lets GitHub restore the newest cache for the same operating system and architecture.
+
+Leave task inputs, including source files and lockfiles, out of the GitHub Actions key. Vite Task fingerprints them. If they change the Actions key, GitHub can skip useful restores before Vite Task decides which tasks still hit.
+
+For monorepos, restore the task cache from the workspace root. Then run the same `vp run` commands you use locally, such as `vp run -t @my/app#build`. Vite Task can reuse results for the requested package and the packages it depends on.
+
+## 3. Verify In The Logs
+
+On the first run, the restore step should say that no cache was found, and the save step should create one. Pull requests from forks may be restore-only because GitHub can give the cache token read-only access. In that case, the save step warns and exits successfully without writing a cache entry.
+
+On a later run, look for both layers:
+
+```text
+Cache restored from key: vite-task-Linux-X64-...
+$ vp build ◉ cache hit, replaying
+vp run: cache hit, 1.10s saved.
+```
+
+If GitHub restores a cache but Vite Task prints a cache miss, the workflow restored the cache directory, but the task fingerprint changed.
+
+## Keep Task Tracking Stable
+
+If GitHub restores a cache but `vp run` prints a cache miss, fix the task fingerprint before changing the Actions cache key. See [Automatic Data Tracking](/guide/automatic-data-tracking) and [`run.tasks`](/config/run#tasks).
+
+## Choose A Cache Key
+
+Use a rolling primary key plus a restore prefix:
+
+```yaml [.github/workflows/ci.yml]
+key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }}
+restore-keys: |
+  vite-task-${{ runner.os }}-${{ runner.arch }}-
+```
+
+The primary key is unique for each run because it contains `github.run_id` and `github.run_attempt`. GitHub then searches the restore prefix and restores the newest matching cache.
+
+Include:
+
+- `runner.os` and `runner.arch`, because outputs and native tools can be platform-specific.
+- A per-run value such as `github.run_id` and `github.run_attempt`, because GitHub cache entries are immutable.
+
+If a dependency file affects a task result, track it in the task fingerprint rather than the GitHub Actions key.
+
+## Manage Cache Eviction And Scope
+
+GitHub evicts caches based on its cache retention and repository storage rules. Cache scope is also branch-aware: workflow runs can restore caches from the current branch and the default branch, while pull request merge-ref caches have limited scope.
+
+Vite Task can clear the whole task cache, but it does not currently evict individual task entries by age or size. As new task entries and output archives are saved, `node_modules/.vite/task-cache` can keep growing.
+
+Manage size at the GitHub Actions cache layer:
+
+- Keep the cached `path` limited to the Vite Task cache directory.
+- Keep the restore prefix scoped to compatible runners, such as the same OS and architecture.
+- Delete stale GitHub Actions cache entries, save caches from fewer workflows, or adjust the repository cache limit if large caches cause frequent evictions.
+
+See [GitHub's cache reference](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching) for the current eviction and scope rules.

package/docs/guide/install.md

@@ -67,6 +67,15 @@ Use the `-g` flag for installing, updating or removing globally installed packag
 - `vp uninstall -g <pkg>` removes a global package
 - `vp update -g [pkg]` updates one global package or all of them
 - `vp list -g [pkg]` lists global packages
+- `vp outdated -g [pkg]` prints outdated packages
+
+::: warning
+These commands do **NOT** interact with the underlying package manager's global installation directory.
+
+Instead, Vite+ manages its own global packages under `~/.vite-plus/packages`, allowing them to remain available across different Node.js versions.
+
+As a result, commands such as `vp link` do not affect Vite+'s global packages and will not appear in `vp list -g`.
+:::
 
 ## Managing Dependencies
 
@@ -109,6 +118,7 @@ Use these commands when you want package-manager-managed tools available outside
 - `vp uninstall -g typescript`
 - `vp update -g`
 - `vp list -g`
+- `vp outdated -g`
 
 #### Add and Remove
 
@@ -167,8 +177,8 @@ Examples:
 
 ```bash
 vp pm config get registry
-vp pm cache clean --force
-vp pm exec tsc --version
+vp pm cache clean -- --force
+vp pm audit --json
 ```
 
 #### Staged publishing