Merge remote-tracking branch 'origin/main' into docs-update-main-page

Author: mdong1909

.github/scripts/packed-consumer.mjs

@@ -176,6 +176,10 @@ try {
           [join(root, '.github/scripts/packed-init.mjs'), fixture, framework, manager, version],
           work,
         );
+        const agentInstructions = readFileSync(join(fixture, 'AGENTS.md'), 'utf8');
+        assert.equal(agentInstructions.match(/^- /gm)?.length, 2);
+        assert(agentInstructions.includes('node_modules/void/docs/'));
+        assert(existsSync(join(fixture, 'node_modules/void/docs/guide/quickstart.md')));
         assert(
           existsSync(join(fixture, '.git')),
           'Init should initialize the accepted Git repository',

.github/scripts/packed-registry.mjs

@@ -12,6 +12,21 @@ export function inspectPackage(tarball) {
   const files = new Set(
     execFileSync('tar', ['-tf', tarball], { encoding: 'utf8' }).trim().split(/\r?\n/),
   );
+  if (manifest.name === 'void') {
+    for (const file of [
+      'docs/guide/quickstart.md',
+      'docs/reference/cli.md',
+      'skills/void/SKILL.md',
+      'skills/migrate-vite-cloudflare-to-void/SKILL.md',
+      'AGENTS_TEMPLATE.md',
+    ]) {
+      assert(files.has(`package/${file}`), `void: missing bundled ${file}`);
+    }
+    assert(
+      ![...files].some((file) => file.startsWith('package/skills/void/docs/')),
+      'void: docs must be bundled at the package root',
+    );
+  }
   for (const field of [
     'dependencies',
     'optionalDependencies',

.github/scripts/postgres-concurrency-tests.ts

@@ -0,0 +1,67 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+// eslint-disable-next-line no-restricted-imports -- Native filesystem paths are never embedded in source.
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseSync } from 'vite';
+import { isRecord } from '../../packages/deploy-core/src/is-record.ts';
+import { compatibilityTestFiles } from './schema-compat-tests.ts';
+
+function memberName(node: unknown): string | undefined {
+  if (!isRecord(node) || node.type !== 'MemberExpression' || !isRecord(node.property)) {
+    return undefined;
+  }
+  if (!node.computed && node.property.type === 'Identifier') {
+    return typeof node.property.name === 'string' ? node.property.name : undefined;
+  }
+  return node.computed && typeof node.property.value === 'string' ? node.property.value : undefined;
+}
+
+function usesPostgresEnvironment(node: unknown): boolean {
+  if (Array.isArray(node)) {
+    return node.some(usesPostgresEnvironment);
+  }
+  if (!isRecord(node)) {
+    return false;
+  }
+  if (
+    memberName(node) === 'VOID_TEST_DATABASE_URL' &&
+    isRecord(node.object) &&
+    memberName(node.object) === 'env' &&
+    isRecord(node.object.object) &&
+    node.object.object.type === 'Identifier' &&
+    node.object.object.name === 'process'
+  ) {
+    return true;
+  }
+  return Object.values(node).some(usesPostgresEnvironment);
+}
+
+/** Select real PostgreSQL cases without repeating the whole in-memory API suite. */
+export function postgresConcurrencyTestFiles(root: string): Array<string> {
+  const files = compatibilityTestFiles(root).filter((file) => {
+    const parsed = parseSync(file, readFileSync(join(root, file), 'utf8'));
+    if (parsed.errors.length > 0) {
+      throw new Error(`Cannot inspect PostgreSQL test coverage in ${file}.`);
+    }
+    return usesPostgresEnvironment(parsed.program);
+  });
+  if (files.length === 0) {
+    throw new Error('No PostgreSQL concurrency test files were found.');
+  }
+  return files;
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  const files = postgresConcurrencyTestFiles(process.cwd());
+  // Reuse the bounded runner's independent database clones and cleanup for every file.
+  const result = spawnSync(
+    process.execPath,
+    [fileURLToPath(new URL('./schema-compat-tests.ts', import.meta.url)), ...files],
+    { stdio: 'inherit' },
+  );
+  if (result.error) {
+    throw result.error;
+  }
+  process.exitCode = result.status ?? 1;
+}

.github/workflows/platform-ci.yml

@@ -14,6 +14,7 @@ on:
       - '.github/scripts/production-baseline.ts'
       - '.github/scripts/schema-fixture.mjs'
       - '.github/scripts/schema-compat-tests.ts'
+      - '.github/scripts/postgres-concurrency-tests.ts'
   workflow_call:
     inputs:
       require-schema-compat:
@@ -89,6 +90,48 @@ jobs:
       - run: vp run --filter './platform/packages/**' build
       - run: vp test run --project '${{ matrix.project }}*'
 
+  postgres-concurrency:
+    runs-on: ${{ github.repository == 'voidzero-dev/void' && 'blacksmith-4vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    env:
+      POSTGRES_USER: void_ci
+      POSTGRES_PASSWORD: void_ci_pass
+      POSTGRES_DB: void_schema_compat
+      COMPAT_DATABASE_URL: postgresql://void_ci:void_ci_pass@localhost:5432/void_schema_compat
+      TZ: UTC
+    services:
+      postgres:
+        image: postgres:18
+        env:
+          POSTGRES_USER: ${{ env.POSTGRES_USER }}
+          POSTGRES_PASSWORD: ${{ env.POSTGRES_PASSWORD }}
+          POSTGRES_DB: ${{ env.POSTGRES_DB }}
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U $POSTGRES_USER"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0
+        with:
+          cache: true
+          node-version-file: .node-version
+      - run: vp run build
+      - run: vp run --filter './platform/packages/**' build
+      - name: Create the candidate PostgreSQL schema
+        run: vp run --filter @voidcloud/api migrate
+        env:
+          DATABASE_URL: ${{ env.COMPAT_DATABASE_URL }}
+      - name: Run candidate PostgreSQL concurrency tests
+        run: node .github/scripts/postgres-concurrency-tests.ts
+
   # Upgrade a populated previous schema, then run that immutable runtime's tests.
   # The prod branch can already be the candidate, so never use it as the baseline.
   schema-compat:

AGENTS.md

@@ -88,7 +88,7 @@ own README under `packages/{react,vue,svelte,solid}`.
 The [API reference](./docs/reference/api.md) and
 [CLI reference](./docs/reference/cli.md) describe the supported public surface.
 
-`packages/void/skills/void/docs` is ignored by Git and copied from `docs/`
+`packages/void/docs` is ignored by Git and copied from `docs/`
 during the build. Edit the source documentation instead.
 
 ## Tooling

README.md

@@ -1,8 +1,14 @@
 # Void
 
-Full-stack apps with [Vite](https://vite.dev), running on Cloudflare Workers.
+Build and deploy full-stack apps with [Vite](https://vite.dev), running on Cloudflare Workers.
 
-Build APIs and server-rendered pages with typed access to databases, storage, and AI. Void detects the resources your app uses and provisions them when you deploy. Use React, Vue, Svelte, Solid, or a [supported framework](https://void.cloud/integrations/frameworks/overview).
+Void brings together three open-source tools for you and your coding agents:
+
+- **Void SDK:** Build your server and client together with file-based API routes, server-rendered pages, and typed APIs for databases, storage, and AI. Carry types from database queries to the UI.
+- **Void CLI:** Build your app, provision the Cloudflare resources it uses, apply migrations, and deploy with one command. Manage resources, inspect logs, and roll back through the same CLI.
+- **Void Platform:** Install a shared deployment environment in your Cloudflare account for your team or customers, with access controls, resource limits, and usage reporting.
+
+The SDK's features are optional and composable. Use React, Vue, Svelte, or Solid for Void pages, or keep a [supported application framework](https://void.cloud/integrations/frameworks/overview) for routing and rendering while Void handles resource APIs, migrations, and deployment.
 
 ## Getting Started
 
@@ -20,19 +26,23 @@ Choose your UI framework and starter, then select Cloudflare to deploy to your a
 npx void deploy
 ```
 
-Void builds the app, provisions resources, applies database migrations, and prints your deployed URL. Follow the [Quickstart](https://void.cloud/guide/quickstart) to explore your app or add Void to an existing Vite project.
+Void builds the app, provisions resources, applies database migrations, and prints your deployed URL. Follow the [Quickstart](https://void.cloud/guide/quickstart) for your first app or to add Void to an existing Vite project.
+
+To deploy to a team platform, run `npx void connect <url>` first, then use the same deploy command. See [Install a Void Platform](https://void.cloud/guide/self-hosted-platform) to host one in your Cloudflare account or customize its open-source runtime.
 
 ## Documentation
 
-- [How Void works](https://void.cloud/guide/)
+Read the [Void documentation](https://void.cloud) online or use the Markdown guides and references in `node_modules/void/docs/`, included with the `void` package.
+
+`void init` adds a minimal `AGENTS.md` in new projects and asks before changing instructions in existing projects. It also links bundled skills for detected coding agents.
+
 - [Server routes](https://void.cloud/guide/server-routing) and [pages](https://void.cloud/guide/pages-routing/overview)
 - [Database](https://void.cloud/guide/database) and [type safety](https://void.cloud/guide/type-safety)
 - [Deployment](https://void.cloud/guide/deployment)
 - [Framework integrations](https://void.cloud/integrations/frameworks/overview)
+- [API](https://void.cloud/reference/api) and [CLI](https://void.cloud/reference/cli) reference
 - [Coding agents](https://void.cloud/integrations/agents)
 
-Teams can [install a Void platform](https://void.cloud/guide/self-hosted-platform) in a shared Cloudflare account. The framework, CLI, and platform source are included in this repository.
-
 ## Contributing
 
 ```sh

TESTING.md

@@ -166,6 +166,14 @@ API integration fixtures reset their tables with one ordered SQL block. Use `cle
 than repeating per-table cleanup; it keeps foreign-key delete behavior and migration history
 intact in PGlite and PostgreSQL.
 
+Platform CI runs the candidate's PostgreSQL concurrency cases in a separate job. The selector
+finds API integration files that read `process.env.VOID_TEST_DATABASE_URL`, excluding mentions
+in comments or strings. Each selected file runs against its own database clone, with two files
+in flight, using the same bounded runner as schema compatibility. This exercises real locks
+without repeating the entire API suite. To run it locally, migrate a disposable loopback
+`void_schema_compat` database as `void_ci`, then set `COMPAT_DATABASE_URL` and run
+`node .github/scripts/postgres-concurrency-tests.ts`.
+
 Staging CI on main also runs the production schema-compatibility gate, so its failures are caught
 before tagging a release. The job copies the candidate's `.github/scripts/schema-compat-tests.ts` runner
 before checking out the deployed revision. It runs every deployed API test file against its own
@@ -221,6 +229,14 @@ utility and Bash; it has no Python or native npm dependency.
 
 ## Browser readiness and Windows CI
 
+Pages scroll regressions run in Chromium by default. On a machine with Playwright WebKit support,
+run the same document navigation, reload, SPA navigation, and suspended-render cases in WebKit:
+
+```sh
+vp exec playwright install webkit
+VOID_TEST_BROWSER=webkit vp test run packages/react/test/integration packages/vue/test/integration packages/svelte/test/integration packages/solid/test/integration -t 'restores.*scroll'
+```
+
 Use `waitForIslandsHydrated` from `test/browser-helpers.ts` before asserting island state or
 interacting with islands. Pass the expected minimum count when checking a multi-island fixture.
 Each island imports and hydrates independently, so a selector matching one hydrated island does
@@ -308,7 +324,7 @@ Use the intended test account rather than an account name embedded in a script.
 - setting `CLOUDFLARE_ACCOUNT_ID` in the current shell.
 
 When a version has no preview URL, also set `CLOUDFLARE_WORKERS_SUBDOMAIN` to the account's
-workers.dev subdomain. For `https://my-worker.my-team.workers.dev`, the value is `my-team`. The
+workers.dev subdomain. For [`https://my-worker.my-team.workers.dev`](https://my-worker.my-team.workers.dev), the value is `my-team`. The
 account name shown in the dashboard is not necessarily the workers.dev subdomain.
 
 Never commit account IDs, resource IDs, API tokens, or Access credentials. CI should receive them

docs/.vitepress/redirects/reference-cli.json

@@ -110,6 +110,6 @@
   "void-email-domain-remove": "/reference/cli/email#void-email-domain-remove",
   "void-email-status": "/reference/cli/email#void-email-status",
   "void-email-setup": "/reference/cli/email#void-email-setup",
-  "agent": "/reference/cli/setup#agent",
-  "void-init-agents": "/reference/cli/setup#void-init-agents"
+  "agent": "/reference/cli/setup#void-init",
+  "void-init-agents": "/reference/cli/setup#void-init"
 }

docs/.vitepress/theme/FileTree.vue

@@ -365,7 +365,6 @@ const TreeNode = defineComponent({
   color: var(--vp-c-brand-1);
 }
 
-/* Adapter tabs */
 /* Adapter tabs */
 .adapter-tabs {
   display: flex;