void 0.10.7 → 0.10.10

package/skills/void/docs/integrations/cloudflare.md

@@ -285,3 +285,110 @@ That's it. The Cloudflare Vite plugin produces a complete build output with a me
 ### Local development
 
 `pnpm dev` continues to work as before -- Miniflare creates local instances of all bindings regardless of the IDs in your `wrangler.jsonc`. Your real resource IDs are only used when you run `wrangler deploy`.
+
+### AI (self-host)
+
+`void/ai` works on your own Cloudflare account, along two paths:
+
+- **Workers AI** (`ai.run`, `ai.stream`, `ai.image`) works out of the box. When your app imports `void/ai`, `vite build` infers that you need AI and adds a Workers AI binding (`env.AI`) to the generated `wrangler.json` automatically -- you do **not** add it to `wrangler.jsonc`.
+- **Provider models** (`ai.provider("openai").fetch(...)`) route through _your own_ Cloudflare AI Gateway. Set its id in `void.json` and add the provider's API key as a Worker secret.
+
+```jsonc
+// void.json
+{
+  "ai": {
+    "gateway": "my-gateway", // an AI Gateway in YOUR Cloudflare account
+  },
+}
+```
+
+```bash
+# provider API key, stored as a Worker secret (never committed)
+wrangler secret put OPENAI_API_KEY
+```
+
+```ts
+// routes/chat.ts
+import { defineHandler } from 'void';
+import { ai } from 'void/ai';
+
+export const POST = defineHandler(async (c) => {
+  // Workers AI -- uses env.AI directly
+  const summary = await ai.run('@cf/meta/llama-3.1-8b-instruct', {
+    prompt: 'Summarize the changelog.',
+  });
+
+  // Provider model -- routes through your "my-gateway" AI Gateway,
+  // authed with the OPENAI_API_KEY secret above
+  const res = await ai.provider('openai').fetch('chat/completions', {
+    method: 'POST',
+    body: JSON.stringify({ model: 'gpt-4o-mini', messages: [] }),
+  });
+
+  return c.json({ summary, provider: await res.json() });
+});
+```
+
+`ai.gateway` is required for `ai.provider().fetch()` -- without it, that call returns a `501`. No AI traffic or provider secret passes through Void's shared proxy: requests go directly to _your own_ Cloudflare AI Gateway, authenticated with provider secrets from _your_ Worker's environment. (The request and that secret are of course still sent onward to the AI Gateway and the upstream provider you call.)
+
+Notes:
+
+- **No cross-tenant usage metering.** On the Void platform, AI calls are metered and billed through a shared proxy. Self-hosted, there is no metering -- you get your own [Cloudflare AI Gateway analytics](https://developers.cloudflare.com/ai-gateway/) instead.
+- **The runtime reads the `env.AI` binding by name** -- a custom-named root AI binding is not supported.
+- **`void dev` has no local Workers AI emulation.** In development, AI still routes through Void, so `void dev` AI requires `void auth login` even when you deploy self-hosted.
+
+### ISR (self-host)
+
+[Revalidation (ISR)](../guide/edge/revalidation.md) works self-hosted, but the cache KV is **not** auto-injected (a KV binding needs a real namespace id). Create a namespace and bind it as `ISR_CACHE`:
+
+```bash
+wrangler kv namespace create ISR_CACHE
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "kv_namespaces": [
+    {
+      "binding": "ISR_CACHE",
+      "id": "<your-namespace-id>",
+    },
+  ],
+}
+```
+
+Configure revalidation exactly as on the platform -- globally or per-path in `void.json`:
+
+```jsonc
+// void.json
+{
+  "routing": {
+    "revalidate": { "/blog/*": 3600, "*": 60 },
+  },
+}
+```
+
+...or per page with an exported `revalidate` literal in a `.server.ts` companion (Pages mode):
+
+```ts
+// pages/blog/[slug].server.ts
+export const revalidate = 3600; // seconds
+```
+
+On-demand purges work through `revalidate()`:
+
+```ts
+import { revalidate } from 'void/isr';
+
+await revalidate({ paths: ['/blog/hello'] });
+// or purge every ISR page:
+await revalidate({ all: true });
+```
+
+Self-hosted, `revalidate()` purges this worker's own KV entries (global, authoritative) plus the current colo's edge cache.
+
+Limits (the single-worker cache ladder can't do everything the platform's dispatch layer does):
+
+- **No fleet-wide / cross-colo edge purge.** `revalidate()` clears KV globally and the _local_ colo's edge cache; other colos keep serving their edge copy until it expires (bounded by the response's `s-maxage`), then re-render on the next edge miss.
+- **The pages-protocol JSON variant is not served from a cold colo's KV.** A colo that hasn't rendered the HTML yet re-renders the JSON live; the JSON edge cache is warmed only as a side effect of the HTML render path.
+- **The warm cache is dropped on every redeploy.** Each `vite build` bakes a fresh deployment id into the cache keys, so cached HTML never outlives the hashed assets it references -- the first request after a deploy is a cold render.

package/skills/void/docs/node_modules/void/{AGENTS.md → CLAUDE.md}

@@ -89,6 +89,14 @@ src/
 - **Drizzle-first database**: Schema is defined in `db/schema.ts` (Drizzle table definitions). `void/db` exports a Drizzle D1 instance. `@schema` is an auto-configured alias for `db/schema.ts`. Migrations live in `db/migrations/`. CLI commands: `void db push` (prototype), `void db generate` (create migration files), `void db migrate` (apply locally). `drizzle-orm` and `drizzle-kit` ship with void.
 - **Journal coherence invariant**: `db/migrations/*.sql` and `db/migrations/meta/_journal.json` must stay in sync — every `.sql` file has a matching journal entry (by `tag`) and vice versa. `assertJournalCoherence` in `src/migrations/validate.ts` is the gate, called from `deploy`, `db status`, `db migrate`, and `db reset`. The two CLI commands that mutate migration state — `void gen migration` and `void db rename-migrations` — are responsible for keeping the journal coherent themselves: the first appends a new entry when writing a file (failing loud if the journal is missing — run `drizzle-kit generate` first), the second rewrites `tag` values alongside the file renames and also renames the matching `meta/<prefix>_snapshot.json` (with byte-level rollback on failure). `gen migration` additionally copies the previous `meta/<idx:04d>_snapshot.json` forward to the new idx so drizzle-kit's drop/rollback tooling keeps working on mixed hand-written + drizzle projects; projects without prior snapshots are skipped silently. Drift will fail loudly before touching any remote DB. Motivated by [void-sdk/void#6](https://github.com/void-sdk/void/issues/6), where an orphan scaffolded `.sql` file half-applied against D1 and wedged the deploy.
 
+### Self-Host AI + ISR
+
+Two features need extra wiring on a self-hosted `vite build && wrangler deploy` (no Void platform proxy/dispatch in front of the worker). Both are inert on managed `void deploy`.
+
+- **`ai.gateway` config + `__VOID_AI_GATEWAY` var** — `void.json`'s `ai.gateway` (validated in `config.ts` as `ai?: { gateway?: string }`; non-empty string, `additionalProperties: false`) names a Cloudflare AI Gateway in the user's own account. `mergeBindings` (`index.ts`): (1) injects `{ ai: { binding: 'AI' } }`, but only when `shouldBindWorkersAi()` is true — the app infers `needsAI`, `command === 'build'`, and neither the resolved root wrangler config nor the result already declares an `ai` binding (so it never clobbers a user's own `ai` binding); (2) emits `vars.__VOID_AI_GATEWAY = config.ai.gateway` whenever `config.ai?.gateway` is set. At runtime, `runtime/ai.ts` `resolveBackend()` selects the direct backend (Priority 3) when `env.AI` is present and no `__VOID_PROXY`/`__VOID_TOKEN` exists. `ai.run/stream/image` hit Workers AI directly; `ai.provider().fetch()` routes through the user's own gateway via `directAi.gateway(__VOID_AI_GATEWAY).getUrl(provider)` with the provider key from the user's own secret (`resolveProviderKey` → `env[PROVIDER_KEY_MAP[provider]]`), returning HTTP 501 if `__VOID_AI_GATEWAY` is unset. No cross-tenant metering on this path. The runtime reads `env.AI` **by name** — a custom-named root AI binding is not honored.
+- **Internal-binding leak check permits exactly `__VOID_AI_GATEWAY`** — the integration guard (`test/integration/kitchen-sink-build.test.ts`) that asserts no `__VOID_*` var reaches `dist/ssr/wrangler.json` explicitly excludes `__VOID_AI_GATEWAY`, because it is a legitimate, non-credential runtime var (unlike the credential keys in `INTERNAL_ENV_KEYS`, which are stripped).
+- **`ISR_CACHE` self-host requirement** — self-host ISR (`runtime/isr-cache.ts`, `runtime/isr.ts`) reads `env.ISR_CACHE` (a `KVNamespace`) + `env.__VOID_ISR_DEPLOYMENT_ID`. Unlike D1/KV/R2, `ISR_CACHE` is **not** auto-injected (a KV binding needs a real namespace id), so the user must create the namespace and declare it as `ISR_CACHE` in their root wrangler config. `routing.revalidate` (void.json) and per-page `export const revalidate` are merged by `collectRevalidate` (`isr-config.ts`) and baked as `__VOID_ISR_REVALIDATE`. On-demand `revalidate()` on self-host purges the worker's own KV (global) plus the local-colo `caches.default` edge variants only.
+
 ### Package Exports
 
 | Subpath          | What                                                                                                                                  |
@@ -203,3 +211,9 @@ Agent instructions use versioned markers (`<!--injected-by-void-v0.0.1-->` / `<!
 | `test/unit/plugin-node-target.test.ts`      | Node target plugin — binding guard, plugin creation (5 tests)  |
 | `test/integration/node-target.test.ts`      | Node app playground — dev server + production build (5 tests)  |
 | `test/integration/queue-playground.test.ts` | Queue send → consumer → KV round-trip (1 test)                 |
+
+## Pitfalls / Things That Broke
+
+- **`__VOID_ISR_DEPLOYMENT_ID` must be a compile-time literal.** `router/compile.ts` stringifies `crypto.randomUUID()` once at build time (`export const __VOID_ISR_DEPLOYMENT_ID = "..."`, exactly like `__VOID_BUILD_KEY`) so every isolate of a deployment shares one id. A bare runtime `crypto.randomUUID()` per-isolate in the emitted source would mint a fresh id per isolate, so the edge-cache key (`handleIsr`'s `deploymentId` option) and the KV key (`env.__VOID_ISR_DEPLOYMENT_ID`, also used by the `revalidate()` purge path) would disagree — breaking cache reads and on-demand purge.
+- **Self-host ISR requires a user-declared `ISR_CACHE` KV.** There is no `id: 'local'` injection for it: a placeholder id is fine for miniflare-backed dev but breaks a real `wrangler deploy`, which rejects an unknown namespace id. The user creates the namespace and binds it as `ISR_CACHE`; `readIsrCache`/`writeIsrCache` fail open to a live render when it is absent.
+- **Workers AI binding injection is `command === 'build'`-gated.** `shouldBindWorkersAi()` only injects `{ ai: { binding: 'AI' } }` on build, because dev/miniflare has no local Workers AI emulation — `void dev` AI still routes through the Void proxy (P2 `__VOID_TOKEN` path) and needs `void auth login`.

package/skills/void/docs/reference/cli.md

@@ -609,6 +609,8 @@ void github join
 
 Join the GitHub App installations your organization already has. If a teammate installed the Void GitHub App on a shared GitHub organization, run `void github join` to gain access to those installations without re-installing. Void opens your browser to authorize (a localhost + PKCE handshake, the same mechanics as `void github link`), confirms with GitHub which installations you can manage, and records your membership. Afterwards `void github installations` lists them and `void github connect` can connect your own projects to their repositories.
 
+In an interactive terminal you rarely need to run this yourself — `void github connect` runs the same join automatically when no active installations are linked to your account. Running `void github join` yourself matters mainly for non-interactive use (without a TTY, `void github connect` never opens a browser), or to link installations ahead of time.
+
 Requires an authenticated CLI (`void auth login` first) and organization-installation sharing enabled on your Void instance; when it is not enabled the command fails closed with a clear message. You can only join installations your GitHub authorization actually returns — you cannot name or join one you cannot access on GitHub.
 
 ### `void github connect`
@@ -619,6 +621,8 @@ void github connect [project] [options]
 
 Connect a GitHub repository to a Void project for automatic deploys. On every push to the configured branch, Void builds and deploys your project automatically.
 
+Interactively (TTY), if your account has no active installations linked, `void github connect` first runs the same browser authorize as `void github join` automatically — if a teammate already installed the Void GitHub App on your organization, you join it on the spot and the connect continues. Only when no shared installation is found does it ask you to run `void github install`. The same recovery runs when `--installation <id>` names an installation your account is not linked to yet. Without a TTY, connect never opens a browser: it fails closed and tells you to run `void github install`, or `void github join` if your organization already installed the App.
+
 **Options**
 
 | Flag                  | Description                                                                       |
@@ -636,7 +640,7 @@ Interactively (TTY), after resolving the repository and branch, `void github con
 
 **Non-interactive use (CI)**
 
-When stdin is not a TTY, `void github connect` never prompts — it fails closed and names any flag it needs. `--branch` is always required. `--project` must be resolvable (positional / `--project` / `VOID_PROJECT` / linked `.void/project.json`). `--installation` is required only when your account has more than one installation; otherwise the sole installation is used. `--repo` is required when the installation grants access to all repos or to more than one selected repo; when it grants exactly one repo that repo is used automatically. Use `void github installations` to discover the `installation_id`.
+When stdin is not a TTY, `void github connect` never prompts — it fails closed and names any flag it needs. `--branch` is always required. `--project` must be resolvable (positional / `--project` / `VOID_PROJECT` / linked `.void/project.json`). `--installation` is required only when your account has more than one installation; otherwise the sole installation is used. `--repo` is required when the installation grants access to all repos or to more than one selected repo; when it grants exactly one repo that repo is used automatically. `--repo` is also required when the installation does not expose a repository list to your account (shared org installations hide it). Use `void github installations` to discover the `installation_id`.
 
 ```
 void github connect my-app \
@@ -649,7 +653,7 @@ void github connect my-app \
 
 **Connecting as an organization member**
 
-If you are a member of a GitHub organization but not the person who installed the App, `void github connect` first confirms that you personally have access to the specific repository. When it detects this, it opens your browser once to authorize access to that repo on GitHub (a localhost + PKCE handshake), then completes the connection automatically — no extra flags. Run `void github join` first so the installation appears in `void github installations`. You can only connect repositories you can access on GitHub; one you cannot see is refused with a clear message.
+If you are a member of a GitHub organization but not the person who installed the App, `void github connect` first confirms that you personally have access to the specific repository. Interactively (TTY), when it detects this it opens your browser once to authorize access to that repo on GitHub (a localhost + PKCE handshake), then completes the connection automatically — no extra flags. Without a TTY, this per-repo authorization never opens a browser: connect fails closed with an error explaining that the installation requires per-repo authorization, which needs an interactive browser sign-in, and telling you to run `void github connect` locally to authorize, then retry. Interactively, connect joins the shared installation automatically when your account has no active installations linked, so running `void github join` first is optional — useful mainly to see the installation in `void github installations` beforehand. You can only connect repositories you can access on GitHub; one you cannot see is refused with a clear message.
 
 ### `void github update`
 
@@ -696,6 +700,29 @@ void github status my-app
 
 **Project resolution** follows the same order as deploy: positional / `--project`, `VOID_PROJECT`, linked project (`.void/project.json`).
 
+### `void github disconnect`
+
+```
+void github disconnect [project]
+```
+
+Disconnect a project from its GitHub repository, stopping automatic deploys. Any in-flight builds for the project are cancelled (their deploy tokens are revoked) before the connection is removed. If the project has no connection, it reports that and exits successfully. To point a project at a different repository, disconnect first, then run `void github connect`.
+
+You are asked to confirm before anything is removed. Pass `--yes` to skip the prompt; `--yes` is **required** in a non-interactive shell (CI), where there is no prompt to answer.
+
+**Options**
+
+| Flag               | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `--project <name>` | Project name (alias for the positional argument)                  |
+| `--yes`            | Skip the confirmation prompt (required in non-interactive shells) |
+
+```
+void github disconnect my-app --yes
+```
+
+**Project resolution** follows the same order as deploy: positional / `--project`, `VOID_PROJECT`, linked project (`.void/project.json`).
+
 ## Build
 
 Inspect Deploy-on-GitHub builds.

package/dist/env-raw-CoS20LHP.mjs

@@ -1,32 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-//#region src/runtime/env-raw.ts
-/**
-* Raw runtime env resolution — framework-internal only.
-*
-* This module is NOT exported in package.json, so it cannot be imported
-* via "void/..." subpaths. Only framework modules using relative imports
-* (isr.ts, ai.ts, env.ts) can access it.
-*/
-/** Prefixes for platform-internal bindings that must be hidden from user code. */
-const INTERNAL_BINDING_PREFIXES = ["__VOID_", "__PROJECT_"];
-const envContext = new AsyncLocalStorage();
-let cloudflareEnv;
-if (typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers") import("cloudflare:workers").then((mod) => {
-	cloudflareEnv = asEnv(mod.env) ?? void 0;
-}).catch(() => {});
-function asEnv(value) {
-	if (typeof value !== "object" || value === null) return null;
-	if ("then" in value && typeof value.then === "function") return null;
-	return value;
-}
-function getNuxtEnv() {
-	return asEnv(globalThis.__env__);
-}
-/** Resolve raw env from AsyncLocalStorage, Nuxt globals, or CF module env. */
-function getRawRuntimeEnv() {
-	return envContext.getStore() ?? getNuxtEnv() ?? cloudflareEnv ?? (() => {
-		throw new Error("env: Cloudflare env is unavailable. Use void runtime bindings inside Nuxt/SvelteKit/Analog server request handlers or Worker handlers.");
-	})();
-}
-//#endregion
-export { getRawRuntimeEnv as i, asEnv as n, envContext as r, INTERNAL_BINDING_PREFIXES as t };