vite-plugin-zephyr 1.4.2 → 1.6.0

package/skills/zephyr-core/references/change-attribution.md

@@ -0,0 +1,172 @@
+# Change Attribution
+
+Use when enabling optional human/AI attribution or comparing versions built from
+uncommitted source. The Zephyr Attribution integration uses Git AI; a skill alone
+cannot reliably observe file writes.
+
+## Enable with consent
+
+The `with-zephyr` CLI offers **Enable Change Attribution** after SDK setup in an
+interactive terminal. It links to [Git AI installation](https://usegitai.com/docs/get-started)
+and separately offers **Install Agent Integrations**. Non-interactive invocation
+does not opt in; `--dry-run` and `--no-attribution` do not create configuration.
+Explicit non-interactive setup:
+
+```bash
+pnpm dlx with-zephyr . --attribution --attribution-agents codex claude grok
+```
+
+Storage defaults to **local**. The interactive offer also asks local versus
+remote; `--attribution-storage remote` selects remote explicitly. Read
+[repository storage and policy](attribution-storage.md) before enabling remote:
+free accounts include patches/changed-line text; paid/BYOC defaults omit them.
+
+This writes repository-root `.zephyr/attribution.json` and merges hooks into
+`.codex/hooks.json`, `.claude/settings.json`, and/or `.grok/hooks/zephyr-attribution.json`. Codex/Grok also install `.zephyr/attribution-hook.cjs` for metadata. It preserves existing hooks
+and settings, validates documents before writing, and does not modify global
+settings or grant hook trust. Review the Codex project hooks with `/hooks` and
+restart agent sessions. Grok requires its native project trust review (`/hooks-trust`); this grants folder trust for its other project integrations too. T3 uses the same Grok integration through ACP. Install the Git AI binary separately through its linked
+instructions; the codemod does not run a downloaded installer. Skip the agents
+flag for source capture only, or when existing Git AI hooks already cover the
+agents. The installer may also configure agent hooks globally; avoid duplicating
+the same integration at global and project scope.
+
+Known human evidence needs a Git AI editor integration, available through the
+same setup link. Agent hooks alone do not establish which remaining edits were
+human. Missing evidence always remains **unknown**.
+
+## Source records and comparisons
+
+An opted-in SDK captures repository-wide Git-eligible working-tree files,
+including unstaged and untracked files, rather than substituting HEAD or the
+index. A deterministic fingerprint covers paths, file modes, and content hashes.
+Private immutable source copies and version-to-source receipts stay under the
+worktree's Git directory, in `zephyr-attribution/`. They are never build assets.
+Comparisons require those local copies; a fresh clone cannot retrieve them from
+Zephyr or Git AI notes. They are not synchronized or pruned automatically.
+
+Install `zephyr-cli` to inspect the records without login or deployment:
+
+```bash
+pnpm exec ze-cli attribution status
+pnpm exec ze-cli attribution capture --format json
+# Use the two sourceId values returned by capture, or local Zephyr snapshot IDs.
+pnpm exec ze-cli attribution compare <before> <after> --format json
+```
+
+Use `-C <project>` to select another project. Differences report additions,
+removals, binary changes, and file modes. Attribution on a removed line describes
+its original contributor; it does not identify who deleted it. Reverted edits
+disappear from the net source difference.
+
+Local mode attaches no attribution to uploaded snapshots or build stats. Remote
+mode sends full evidence to a dedicated private endpoint and includes a small
+acknowledged record reference in snapshot/build-stat `changeAttribution`. The
+authenticated snapshot `creator` remains the deployer; contributor identities
+are self-reported Git AI evidence, not verified people. Server endpoint/policy
+persistence and a dashboard version-difference UI require control-plane support
+and are not implemented in this SDK workspace.
+
+## Harness, prompt initiator, effort, and usage
+
+`workspaceHuman` identifies the Git author associated with a capture. Hooks-off AI
+changes can appear under this identity, but their edit origin remains unknown.
+The Git author, prompting human, and authenticated snapshot creator are separate.
+Set `ZE_ATTRIBUTION_INITIATOR` in each person's launcher environment to record the
+prompt initiator, and `ZE_ATTRIBUTION_HARNESS` to identify a wrapper such as `t3`
+versus `codex-cli`. For T3, configure these in the selected project/provider's
+environment settings. These are self-reports, not verified account assertions;
+do not put a shared person's identity into team-wide hooks. Missing values stay
+absent. A skill cannot reliably prove which person typed a prompt.
+
+Codex/Grok collect a private metadata ledger under the worktree Git directory.
+Line origins join exact tool-call identities into `sessions`, keyed by agent,
+native session, and turn. Model and effort changes retain the earlier turn's
+metadata. Codex effort/provider/counters use a bounded optional rollout adapter
+tested with CLI 0.160.0; rollout parsing is not a stable API. Grok model/effort
+use its observed summary and usage files, tested with CLI 1.0.46 and T3 0.0.44.
+Unsupported/missing metadata does not invent defaults. Grok uses Git AI's public
+`agent-v1` interface; no fork is required for this bridge.
+
+Grok 1.0.46 omits prompt IDs on tool events. The bridge brackets an active prompt
+from `UserPromptSubmit` to `Stop`/cancellation and marks `turnAssociation` as
+`active-prompt`, an inferred association. Native Codex turn IDs are marked
+`native-turn-id`. Unassociated/background completions stay unknown. Concurrent
+or background Grok work needs stronger native event linkage before claiming an
+exact prompt association. Integration labels alone do not prove the harness.
+
+Usage and cost belong to sessions, not individual lines. Session-cumulative
+snapshots are **not additive**, including across model switches or versions.
+The captured cost is either unavailable or harness-reported USD ticks with an
+observation timestamp and partial flag. It is not inferred from token counts or
+presented as an invoice. [xAI defines one USD as 10 billion USD ticks](https://docs.x.ai/developers/cost-tracking).
+Hook-time Grok counters can lag a turn; only a native
+finished-turn match refreshes them, otherwise they remain incomplete/partial.
+Historical source receipts retain their observed metadata. Raw prompts,
+responses, transcript paths, and arbitrary provider fields are not published.
+
+## Coverage and correctness
+
+- Git-ignored files, common build output (`dist`, `build`, `.next`, `.nuxt`,
+  `.output`), dependency/cache folders, `.env*`, `.npmrc`, `.netrc`, and private
+  key extensions are excluded. Add repository-relative prefixes to `exclude`
+  in the configuration. This is a scoped source record, not a complete build
+  reproduction or a general secret detector.
+- Captures are limited to 20,000 files and 50 MiB. Submodules need exclusions.
+  Failures produce `unavailable` metadata rather than a partial source claim.
+- Vite and `ze-cli <build>` observe source at build start and snapshot creation.
+  `boundary-match` means those two observations match; it does not prove no
+  transient edit occurred between observations. `changed-during-build` means
+  the records differ and neither should be presented as the exact consumed
+  inputs. Other engine adapters observe their generation start and publication;
+  prebuilt deployments observe upload preparation rather than the earlier compiler
+  invocation. Each generation uses at most one start and one publication copy.
+- The Git AI working-log adapter supports `checkpoint/1.0.0` from Git AI 1.7.x,
+  tested with 1.7.5. It accepts attribution only when the checkpoint's content
+  hash matches the captured file. Stale checkpoints remain unknown. Committed
+  blame is deferred to files changed in local/remote comparisons, only for bytes
+  matching the captured commit. Captures retain working-checkpoint ranges and
+  mark matching committed bytes privately; unchanged files do not trigger blame
+  processes at build start. HEAD trees are read once and missing baseline blobs
+  in one batch. Comparison enrichment never rewrites the original receipts. Legacy untracked
+  `Human` checkpoints are not known-human evidence.
+  Since Git AI 1.7 JSON blame omits known humans, the adapter follows native Git
+  line origins into explicit `authorship/3.0.0` human attestations in local
+  `refs/notes/ai`. A commit's ordinary author is never sufficient evidence.
+- `gitAiPath` can point to a compatible fork. Keep format changes behind the
+  adapter; don't infer authorship from file style or the absence of AI marks.
+
+To disable capture, set `enabled` to `false`. Remove the installed Git AI and metadata command
+entries from project hook documents to stop those hooks, retaining other hooks.
+Existing local receipts remain available until explicitly deleted.
+
+## Maintainer verification
+
+`scripts/verify-change-attribution.mjs` builds an actual generated React/Vite app
+three times with the local SDK. It uses the real Git AI binary and replays Codex
+and editor hook fixtures, including a model field. It replaces the cloud transport
+and checks same-commit source differences containing AI, known-human, and unknown
+origins. Hook replays verify integration compatibility; they do not establish
+that a real human typed the fixture or that a live Codex session used that model.
+
+After building `create-zephyr-apps`, `with-zephyr`, `zephyr-agent`, `zephyr-cli`,
+and `vite-plugin-zephyr` locally:
+
+```bash
+node libs/create-zephyr-apps/dist/index.js /tmp/zephyr-attribution-demo --template react-vite --package-manager pnpm --git --install --json
+node libs/with-zephyr/dist/index.js /tmp/zephyr-attribution-demo --attribution --attribution-agents codex --git-ai-path /absolute/path/to/git-ai
+node scripts/verify-change-attribution.mjs /tmp/zephyr-attribution-demo /absolute/path/to/git-ai
+```
+
+Use a disposable app: the verifier edits its template source and writes a private
+`demo-report.json`. It needs Git AI's background service running. A replay failure
+or missing evidence must fail verification, not be relabeled as human or AI.
+
+For live trials, retain a source receipt after each real agent edit. The
+`scripts/verify-live-attribution.mjs <generated-app> <manifest.json>` verifier
+loads those private records, checks the expected model/effort/harness and actual
+added line, compares versions sharing a commit, then builds the final app using
+real Vite/SDK snapshot construction with cloud transport disabled. Manifest
+cases specify `name`, `sourceId`, `file`, `text`, `kind`, and optional `model`,
+`effort`, `harness`. These receipts are local observations, not cloud deployments.
+Do not substitute hook replay for a requested live model/harness trial.

package/skills/zephyr-core/references/deployment-model.md

@@ -0,0 +1,123 @@
+# Deployment Model
+
+Use this file when the user asks what Zephyr builds produce, what a snapshot is, how version URLs relate to tags/envs, what the dashboard deploy model is, or how rollback/promotion works.
+
+## Plain-English model
+
+- Build integration creates an immutable build artifact.
+- The user gets a permanent version URL for that exact build.
+- Tags and environments are mutable routing layers on top of immutable builds.
+- Rollback is fast because Zephyr changes pointers, not app artifacts.
+
+## Quick glossary
+
+| Term        | Meaning                                                        | Best use                                            |
+| ----------- | -------------------------------------------------------------- | --------------------------------------------------- |
+| Build       | The bundler/framework build that Zephyr observes and publishes | The starting action                                 |
+| Version     | Immutable deployed build state with a permanent URL            | Exact preview, debugging, rollback target           |
+| Snapshot    | Underlying stored artifact record for what was built on edge   | Internal precision when explaining architecture     |
+| Tag         | Mutable named selector, rule-based or manually pinned          | Moving channel like `main`, `beta`, `stable`        |
+| Environment | Mutable deployment target with config/domains/overrides        | Stable deploy target like `staging` or `production` |
+
+## Terms
+
+### Version
+
+- Immutable build state.
+- Has a permanent version URL.
+- Good for previewing, sharing, debugging, and exact rollback targets.
+
+### Snapshot
+
+- Edge-side record of what was built: assets + build identity.
+- In the architecture docs, snapshot and build-stats are different.
+- Snapshot is the immutable artifact record; build-stats are the metadata used by the async publish flow.
+
+Source: `https://docs.zephyr-cloud.io/reference/architecture.md`
+
+### Tag
+
+- Mutable named selector.
+- Usually resolves to the newest matching version based on rules, but can also be pinned manually to a fixed version.
+- Good for dynamic channels like `main`, `beta`, `release`, `stable`.
+
+### Environment
+
+- Mutable deployment target with its own config, domains, and optional overrides.
+- Can point to a tag or a fixed version.
+- Good for `development`, `staging`, `production`, previews, and white-label targets.
+- Can also be locked/protected in stricter production workflows.
+
+## Stage 0 vs Stage 1
+
+Use this if the user asks why a build returns before publish work is fully done.
+
+- Stage 0: upload files and snapshot fast; produce the version URL.
+- Stage 1: async publish flow computes and updates tags/envs/cnames.
+- `build-stats` acceptance does not mean every mutable target already switched.
+
+## URLs
+
+Version URL mental model:
+
+```text
+https://{username}-{buildId}-{app-name}-{project}-{hash}.{edge-domain}
+```
+
+Tag URL mental model:
+
+```text
+https://t-{tagname}-{app-uid}-{hash}.{domain}
+```
+
+Environment URL mental model:
+
+```text
+https://{env-name}-{app-uid}-{hash}.{domain}
+```
+
+Which URL to share:
+
+| URL             | Share when                                                     | Why                                 |
+| --------------- | -------------------------------------------------------------- | ----------------------------------- |
+| Version URL     | You need an exact build preview or debugging link              | Immutable                           |
+| Tag URL         | You want a moving channel like `main` or `beta`                | Follows tag resolution              |
+| Environment URL | You want the stable deployment target users or QA should visit | Carries environment behavior/config |
+
+## Dashboard workflow
+
+- Build creates versions automatically.
+- Dashboard lets users inspect versions and their metadata.
+- Users create tags with matching rules.
+- Users create environments that point to a tag or a fixed version.
+- Promotion usually means moving an environment or tag pointer to a chosen version.
+- Rollback usually means repointing back to an older known-good version.
+- Tags and environments can also be locked/protected to prevent accidental changes.
+
+## Built output notes worth calling out
+
+- Zephyr is deployment-first and build-integrated; it observes bundler output and uploads assets after build.
+- Docs describe a permanent version URL, and example/build output commonly surfaces that URL after build completes.
+- The public mental model should stay on version URL first; mention snapshot internals only when useful.
+
+## Smallest first-time path
+
+1. Identify the stack and pick the right SDK or fallback upload path.
+2. Run `with-zephyr` or add the correct Zephyr integration.
+3. Build the app.
+4. Start by using the version URL for exact preview/testing.
+5. Add tags or environments later when the user needs moving channels or stable deploy targets.
+
+## Correctness notes
+
+- Do not say tags are immutable; they are not.
+- Do not say environments are just aliases; they also carry config and custom-domain behavior.
+- Do not say snapshot is the same thing as version URL; the URL points at the immutable build, while snapshot is the stored artifact record underneath.
+
+## Best docs to link
+
+- Versions: `https://docs.zephyr-cloud.io/features/versions.md`
+- Tags & environments: `https://docs.zephyr-cloud.io/features/tags-environments.md`
+- Instant rollbacks: `https://docs.zephyr-cloud.io/features/instant-rollbacks.md`
+- Architecture: `https://docs.zephyr-cloud.io/reference/architecture.md`
+- Core concepts: `https://docs.zephyr-cloud.io/reference/concepts.md`

package/skills/zephyr-core/references/docs-map.md

@@ -0,0 +1,27 @@
+# Docs Map
+
+Use this file when you need to send the user to the right Zephyr docs quickly.
+
+## Main docs site
+
+- Site: `https://docs.zephyr-cloud.io`
+- Raw markdown path pattern: `https://docs.zephyr-cloud.io/<path>.md`
+- Up-to-date index: `https://docs.zephyr-cloud.io/llms.txt`
+- Discord help: `https://discord.gg/zephyrcloud`
+
+## Best first links
+
+- Quick start: `https://docs.zephyr-cloud.io/getting-started/quick-start.md`
+- SDK picker: `https://docs.zephyr-cloud.io/getting-started/find-your-sdk.md`
+- Core concepts: `https://docs.zephyr-cloud.io/reference/concepts.md`
+- Architecture: `https://docs.zephyr-cloud.io/reference/architecture.md`
+- Versions: `https://docs.zephyr-cloud.io/features/versions.md`
+- Tags & environments: `https://docs.zephyr-cloud.io/features/tags-environments.md`
+- Environment overrides: `https://docs.zephyr-cloud.io/features/environment-overrides.md`
+- Existing app integration: `https://docs.zephyr-cloud.io/integrations/existing-app.md`
+
+## When to route elsewhere
+
+- MF setup and remote resolution -> `../../zephyr-module-federation/SKILL.md`
+- BYOC/provider setup -> docs cloud section from `llms.txt`
+- Errors -> docs error encyclopedia

package/skills/zephyr-core/references/env-vars.md

@@ -0,0 +1,75 @@
+# Environment Variables
+
+Use this file when the user asks about `ZE_PUBLIC_*`, runtime config, build once deploy everywhere, or per-environment variable overrides.
+
+## Core rule
+
+- `ZE_PUBLIC_*` variables are public client-facing values captured at build time.
+- They are not secret storage.
+- Zephyr can override them per environment at runtime.
+- Public docs currently describe environment-level overrides as beta.
+
+## How it works
+
+1. Build-time capture: Zephyr records variables prefixed with `ZE_PUBLIC_`.
+2. Manifest generation: captured values are written into `zephyr-manifest.json`.
+3. Runtime override: an environment can inject different values without rebuilding.
+
+Why this matters: the same built artifact can run in development, staging, and production with different public config.
+
+This applies to public client-facing values. Secure server-only values are a separate concern and should not be modeled as `ZE_PUBLIC_*`.
+
+If the user asks where secrets should go instead, route them to the server-side environment variable path rather than public runtime overrides.
+
+## Example
+
+Build-time `.env`:
+
+```bash
+DATABASE_URL=postgres://localhost/myapp
+ZE_PUBLIC_API_URL=https://api.development.example.com
+ZE_PUBLIC_FEATURE_FLAGS=beta-ui,new-checkout
+ZE_PUBLIC_ANALYTICS_KEY=dev_analytics_12345
+```
+
+Application usage:
+
+```ts
+export const config = {
+  apiUrl: process.env.ZE_PUBLIC_API_URL,
+  flags: process.env.ZE_PUBLIC_FEATURE_FLAGS,
+  analyticsKey: process.env.ZE_PUBLIC_ANALYTICS_KEY,
+};
+```
+
+Environment-level overrides example:
+
+| Environment | ZE_PUBLIC_API_URL                 | ZE_PUBLIC_FEATURE_FLAGS          |
+| ----------- | --------------------------------- | -------------------------------- |
+| Development | `https://api.dev.example.com`     | `beta-ui,new-checkout,analytics` |
+| Staging     | `https://api.staging.example.com` | `new-checkout,analytics`         |
+| Production  | `https://api.example.com`         | `analytics`                      |
+
+## Remote overrides relationship
+
+The same environment-level override system also supports remote dependency overrides. If the user is asking about both env vars and remotes together, also read `../../zephyr-module-federation/references/remote-resolution.md`.
+
+## Dashboard flow
+
+- Go to the Zephyr dashboard DevOps section.
+- Select the environment.
+- Set override values for the `ZE_PUBLIC_*` entries.
+- Requests served from that environment use the environment values, not the original build-time values.
+
+## Guardrails
+
+- Keep secrets out of `ZE_PUBLIC_*`.
+- Do not tell users they need a rebuild for normal per-environment public config changes.
+- If the value is server-only or sensitive, Zephyr public env var overrides are the wrong tool.
+- If the user needs secure server-side environment variables, explain that this is a different path than public runtime overrides.
+
+## Best docs to link
+
+- Environment overrides: `https://docs.zephyr-cloud.io/features/environment-overrides.md`
+- Tags & environments: `https://docs.zephyr-cloud.io/features/tags-environments.md`
+- Architecture manifest section: `https://docs.zephyr-cloud.io/reference/architecture.md`

package/skills/zephyr-core/references/examples-resume.md

@@ -0,0 +1,81 @@
+# Examples Resume
+
+Use this file when the user wants concrete Zephyr setup examples for frontend stacks.
+
+## Fast starting points
+
+- Vite SPA: `https://github.com/ZephyrCloudIO/zephyr-examples/tree/main/bundlers/react-vite`
+- Rspack SPA: `https://github.com/ZephyrCloudIO/zephyr-examples/tree/main/bundlers/react-rspack`
+- TanStack Start: `https://github.com/ZephyrCloudIO/zephyr-examples/tree/main/frameworks/tanstack-start`
+- Astro: `https://github.com/ZephyrCloudIO/zephyr-examples/tree/main/frameworks/astro`
+- Cross-bundler MF: `https://github.com/ZephyrCloudIO/zephyr-examples/tree/main/module-federation/react-vite-rspack-webpack`
+- Monorepo MF: `https://github.com/ZephyrCloudIO/zephyr-examples/tree/main/build-systems/turborepo-rspack-mf`
+
+Repo root: `https://github.com/ZephyrCloudIO/zephyr-examples`
+
+## Core pattern
+
+- Install the Zephyr integration that matches the stack.
+- Add `withZephyr()` to the plugin list or wrap the final config with it. Placement is stack-specific, not always last; follow the installed package's dedicated skill.
+- For special frameworks, use the framework-specific Zephyr integration instead of the generic bundler plugin.
+
+## Good references
+
+### Minimal Vite
+
+File: `https://github.com/ZephyrCloudIO/zephyr-examples/blob/main/bundlers/react-vite/vite.config.ts`
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { withZephyr } from 'vite-plugin-zephyr';
+
+export default defineConfig({
+  plugins: [react(), withZephyr()],
+});
+```
+
+### Minimal Rspack
+
+File: `https://github.com/ZephyrCloudIO/zephyr-examples/blob/main/bundlers/react-rspack/rspack.config.ts`
+
+```ts
+import { defineConfig } from '@rspack/cli';
+import { withZephyr } from 'zephyr-rspack-plugin';
+
+const config = defineConfig({
+  entry: { main: './src/main.tsx' },
+});
+
+export default withZephyr()(config);
+```
+
+### TanStack Start
+
+File: `https://github.com/ZephyrCloudIO/zephyr-examples/blob/main/frameworks/tanstack-start/vite.config.ts`
+
+```ts
+import { withZephyr } from 'vite-plugin-tanstack-start-zephyr';
+
+plugins: [tanstackStart(), viteReact(), withZephyr()];
+```
+
+### Astro
+
+File: `https://github.com/ZephyrCloudIO/zephyr-examples/blob/main/frameworks/astro/astro.config.mjs`
+
+```js
+import { defineConfig } from 'astro/config';
+import { withZephyr } from 'zephyr-astro-integration';
+
+export default defineConfig({
+  integrations: [mdx(), sitemap(), withZephyr()],
+});
+```
+
+## Gotchas worth reusing
+
+- Use the framework-specific integration when one exists.
+- Build remotes before hosts in MF setups.
+- Do not assume every example uses the same remote manifest format.
+- Cross-bundler MF hosts may need explicit remote `type` values.