@harperfast/vite 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,297 @@
+# `@harperfast/vite`
+
+## Overview
+
+A Harper application integration that runs a [Vite](https://vite.dev/) frontend inside a Harper component — with hot module replacement (HMR) for local development and a real production build when deployed (including on Harper Fabric).
+
+It runs in one of two modes, chosen automatically:
+
+| Mode                  | When                                  | Behavior                                                                                                                  |
+| --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **Development**       | `harper dev` (Harper sets `DEV_MODE`) | Vite dev server in middleware mode with **HMR**.                                                                          |
+| **Hybrid production** | `harper run` / Fabric (default)       | Builds your app with Vite (the real production build). **No HMR**, but it **recompiles automatically on source changes.** |
+
+**Serving the built output is delegated to Harper's built-in [`static`](https://docs.harperdb.io/) plugin**, configured alongside this plugin and pointed at the same Vite output directory. So the two run in parallel: this plugin **builds** (and, for SSR, **renders** the HTML document — which `static` can't do), while `static` **serves** the assets. For an SPA you don't even need a handler from this plugin in production — `static` serves everything.
+
+This separation makes for a clean deploy story: the output directory is the only contract between the two. You can build on the node, **build once and ship the output** (`static` serves it; this plugin can stay idle), or **pre-build and still edit live** (this plugin rebuilds on change → `static`'s watcher picks it up).
+
+## Usage
+
+Install the plugin in your Harper application:
+
+```bash
+npm install @harperfast/vite --save-dev
+```
+
+In your Harper application's `config.yaml`, add the plugin **and** a `static` block pointed at your Vite build output directory (the plugin builds; `static` serves). List the plugin first so its dev server takes precedence in `harper dev`:
+
+```yaml
+# Builds the app (and renders HTML in SSR mode) into the `output` directory.
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+
+# Serves the built assets from that same directory.
+static:
+  files: 'dist/**'
+```
+
+> For an **SSR** app, add `index: false` to the `static` block so it serves only assets and lets the plugin render `index.html`. For an **SPA**, leave `index` on (and optionally set `notFound: index.html` for client-side routing).
+
+Then point your `dev` script at Harper:
+
+```jsonc
+// package.json
+"scripts": {
+  "dev": "harper dev .",   // development mode (HMR)
+  "start": "harper run ."   // hybrid production mode
+}
+```
+
+Your application runs on [http://localhost:9926](http://localhost:9926/).
+
+### How it works
+
+1. Harper loads your application and calls the plugin's `handleApplication`.
+2. The plugin picks development or hybrid-production mode from the [`hmr`](#hmr) option, defaulting to `DEV_MODE` (set by `harper dev`).
+3. **Development:** a Vite dev server is created with `root` set to the application directory, `middlewareMode: true`, and HMR enabled. Your `vite.config.{js,ts,mjs,...}` is auto-resolved. The dev server handles all requests and falls through to Harper for the rest.
+4. **Hybrid production:** the plugin runs `vite build` if the output is missing and — when `files` is configured — rebuilds whenever those files change. The `static` plugin serves the built assets; for SSR, this plugin additionally renders the HTML document for `text/html` navigations (everything else falls through to Harper).
+
+## Configuration
+
+To enable autocompletion and validation, reference the bundled schema:
+
+```yaml
+# yaml-language-server: $schema=node_modules/@harperfast/vite/schema.json
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+  ssr: 'src/entry-server.tsx'
+```
+
+### `output`
+
+- **Type**: `string`
+- **Optional** (defaults to `dist`)
+
+The build output directory (relative to the app root) the plugin builds the client into. **Point your `static` block at the same directory** (e.g. `files: 'dist/**'`) — that pairing is the whole contract between the two plugins. The plugin sets Vite's build `outDir` to this value, so it takes precedence over any `outDir` in `vite.config`.
+
+### `files`
+
+- **Type**: `string | string[] | FilesOptionObject`
+- **Optional**
+
+A glob (or array of globs) of files to watch. In **hybrid production mode**, a change to any matched file triggers a rebuild. Rebuilds keep serving the previously built assets until the new build finishes, then swap atomically — so there's no downtime window. Omit it to disable rebuild-on-change (the app is built once at startup).
+
+Builds are coordinated across Harper's worker threads through a small Harper table (`harperfast_vite.vite_build_info`, defined in the plugin's `schema.graphql`): one worker claims the build while the others wait, so the app is compiled **once per instance** rather than once per thread — important when running multi-threaded (e.g. on Harper Fabric).
+
+### `ssr`
+
+- **Type**: `string`
+- **Optional**
+
+Path (relative to the application root) to your **server-side render entry**, e.g. `src/entry-server.tsx`. When set, the plugin renders HTML on the server. When omitted, the app is treated as a client-only **SPA**, fully served by the `static` plugin in production.
+
+### `hmr`
+
+- **Type**: `boolean`
+- **Optional** (defaults to `DEV_MODE`)
+
+Whether to run the Vite dev server with **hot module replacement**. When omitted, it follows Harper's dev mode (the `DEV_MODE` env, set by `harper dev`). Set `hmr: true` to force the dev server, or `hmr: false` to force the hybrid production build (build + recompile-on-change) — useful for testing the production path locally without `DEV_MODE`.
+
+> **Caching** is configured on the `static` plugin, not here — set `cacheControl`/`maxAge`/`immutable` (or `setHeaders`) on the `static` block. Content-hashed assets (under Vite's `assets` dir) are safe to cache long-term; the HTML document this plugin renders is always sent with `no-cache`.
+
+## Security
+
+This plugin compiles — and, for SSR, executes — your application **inside the Harper process at runtime** rather than shipping pre-built artifacts. That convenience has a few security implications worth understanding.
+
+### Runtime compilation: treat the app directory as trusted code
+
+In production the Harper process runs `vite build` at startup and — when [`files`](#files) is set — again on every change to a watched file. For an **SSR** app the resulting server bundle is then imported and its `render()` runs **in-process**. Consequences:
+
+- **Write access to the watched source is code execution.** Anyone who can modify the files matched by `files` (or the app source generally) gains arbitrary code execution in the Harper process on the next rebuild (SSR), or controls the JavaScript served to every visitor (SPA). Ensure nothing that handles untrusted input — file uploads especially — can write into the app directory or the build output, and restrict filesystem permissions to your deploy process.
+- **The whole build toolchain runs with Harper's privileges.** `vite.config.*`, every Vite/Rollup plugin, and any build-time dependency hook execute in the Harper process during the build. Pin and vet build-time dependencies (committed lockfile, `npm ci`); a supply-chain compromise there runs on your server, not in an isolated CI step.
+- **Build-time env can leak into client JS.** Vite inlines `import.meta.env.VITE_*` and `define` values into the **client** bundle at build time. Because the build runs on the deployed node with production env present, never expose a server-only secret through a `VITE_`-prefixed variable or `define`.
+
+If you prefer the traditional model, **build in CI and ship the output**: point `static` at the committed build directory and omit `files` so this plugin never compiles on the node (it stays idle while `static` serves the artifacts).
+
+### HMR / the dev server is gated behind super*user auth — HTTP \_and* WebSocket
+
+The Vite dev server (HMR mode) exposes powerful endpoints — on-the-fly module transforms and arbitrary file reads via `/@fs/` — and is not designed to face untrusted networks. This plugin therefore **requires Harper `super_user` credentials for the entire dev server: both its HTTP surface and its HMR WebSocket.** That gate is what lets you safely turn HMR on against a _deployed_ instance — e.g. from a cloud IDE — for a live-edit workflow when a local environment isn't an option.
+
+- **Local development is unaffected.** Harper auto-authorizes loopback requests as super_user under `authentication.authorizeLocal` (the default in `harper dev`), so `localhost` just works.
+- **Remote/exposed HTTP requests are challenged.** A request Harper did not authenticate as super_user receives a `401` with a `WWW-Authenticate: Basic` header; the browser then prompts for credentials, which are validated against Harper's user store. (This is why hitting the dev server from another device — e.g. a phone on the LAN — prompts for your admin login.)
+- **The HMR WebSocket runs on Harper's port and is gated too.** Instead of Vite's default standalone WebSocket port, the plugin routes HMR over Harper's own port on a dedicated path and authorizes every upgrade as super_user — by trusting a loopback peer under `authorizeLocal` (so local `harper dev` needs no credentials, just like the HTTP surface), or, for a remote browser, by validating the `hdb-session` cookie Harper sets when you log in (or an `Authorization` header). So once the page has authenticated, the HMR socket connects under the same identity; an unauthenticated remote upgrade is refused and the socket closed. Nothing is exposed on a second port.
+- **Host checking is relaxed by design.** Because every request is already gated, the plugin sets Vite's `server.allowedHosts: true` so HMR also works when reached at a non-localhost hostname; the super_user gate — not Vite's host allowlist — is what protects the surface.
+- **Older Harper hosts fall back to a separate port.** If the host Harper is too old to expose the WebSocket `upgrade` hook this relies on, the plugin reverts to Vite's standalone WebSocket port, which is **not** gated (the plugin logs a warning). Keep it bound to localhost.
+
+As always, only grant `super_user` to people you trust, and prefer the production build (`hmr: false`) for anything that doesn't specifically need live editing.
+
+### SSR renders before authentication
+
+The SSR HTML handler is intentionally reachable by **unauthenticated** users (a public page must render for anonymous visitors). Your `render(url)` runs with no authenticated user and receives the **raw, attacker-controllable request URL**. So:
+
+- If a rendered page contains sensitive data, enforce authorization **inside** your render path — don't assume a logged-in user.
+- Treat `url` as untrusted input: validate or encode it before using it for routing, data lookups, or reflecting it into markup (to avoid reflected XSS or unintended data access).
+
+## Server-Side Rendering (SSR)
+
+SSR follows Vite's standard [server rendering](https://vite.dev/guide/ssr) conventions. You provide two entries and an HTML template; the plugin wires them into Harper.
+
+**`index.html`** — a placeholder marks where rendered markup is injected:
+
+```html
+<div id="app"><!--ssr-outlet--></div>
+<script type="module" src="/src/entry-client.tsx"></script>
+```
+
+**`src/entry-server.tsx`** — exports `render`, returning the markup for a URL:
+
+```tsx
+import { renderToString } from 'react-dom/server';
+import { App } from './App.tsx';
+
+export function render(url: string): string {
+	// Use `url` to drive routing / per-request data loading.
+	return renderToString(<App />);
+}
+```
+
+**`src/entry-client.tsx`** — hydrates the server-rendered DOM:
+
+```tsx
+import { hydrateRoot } from 'react-dom/client';
+import { App } from './App.tsx';
+
+hydrateRoot(document.getElementById('app')!, <App />);
+```
+
+Enable it with `ssr: 'src/entry-server.tsx'`. The plugin then:
+
+- **Development:** serves assets via Vite, and for HTML navigations transforms `index.html` (`transformIndexHtml`), loads the entry with `ssrLoadModule` (so edits are reflected immediately, with HMR for client code), calls `render(url)`, and injects the result into `<!--ssr-outlet-->`.
+- **Hybrid production:** builds the client bundle and a separate SSR bundle, then for HTML navigations imports the built server entry, calls `render(url)`, and injects it into the built `index.html`.
+
+Because the plugin only renders HTML for requests that accept `text/html` (i.e. browser navigations) and falls through otherwise, your Harper resources and REST API remain reachable on the same port. Inside `render`, you can `await` data from Harper resources (e.g. `tables.Product.get(id)`) to render data-driven pages.
+
+> See `test-fixture/` for a complete, runnable SSR example.
+
+## Caching
+
+Two complementary layers:
+
+**1. HTTP caching (via the `static` plugin).** Assets are served by Harper's `static` plugin, which sets validators (`ETag`/`Last-Modified`) and supports `cacheControl`/`maxAge`/`immutable`/`setHeaders` options on its config block. Content-hashed assets (under Vite's `assets` dir) are safe to cache long-term — e.g. `static: { files: 'dist/**', cacheControl: 'public, max-age=31536000, immutable' }`. The HTML document this plugin renders for SSR is always sent with `Cache-Control: no-cache` so navigations see fresh markup.
+
+**2. Harper data/render caching.** Use a Harper table with a TTL as a cache. Define it with the `@table(expiration:)` directive, then populate it on a miss — ideal for caching expensive SSR output or upstream API responses:
+
+```graphql
+# schema.graphql — entries automatically expire after 60 seconds.
+type RenderCache @table(expiration: 60) @export {
+	path: ID @primaryKey
+	html: String
+	renderedAt: Date @createdTime
+}
+```
+
+```js
+// In your SSR render path: serve from cache, render + store on a miss.
+async function renderCached(url) {
+	const cached = await tables.RenderCache.get(url);
+	if (cached) return cached.html;
+
+	const html = await render(url);
+	await tables.RenderCache.put({ path: url, html });
+	return html;
+}
+```
+
+Call `tables.RenderCache.invalidate(path)` (or `delete`) to bust an entry when the underlying data changes. Records are evicted automatically once they pass `expiration`.
+
+## Precompute
+
+Avoid doing the same work on every request:
+
+- **Computed fields** — derive presentation- or denormalization-friendly values declaratively with `@computed`, instead of storing and maintaining them. The `from` expression is evaluated per Harper's computed-field rules (see the [Harper schema docs](https://docs.harperdb.io/)):
+
+  ```graphql
+  type Product @table @export {
+  	id: ID @primaryKey
+  	name: String
+  	priceCents: Int
+  	priceLabel: String @computed(from: "...") # derived from priceCents
+  }
+  ```
+
+- **Startup precompute** — work at module load in a `jsResource` runs once when the component starts, not per request. Use it to build manifests, warm caches, or precompute derived data, then expose it through a resource:
+
+  ```js
+  // resources.js
+  const manifest = buildExpensiveManifest(); // runs once at startup
+
+  export class Manifest extends Resource {
+  	get() {
+  		return manifest;
+  	}
+  }
+  ```
+
+- **Build-time pre-rendering (SSG)** — for fully static pages, render them during the build and let the static server serve the resulting HTML, skipping per-request rendering entirely.
+
+See [`test-fixture/resources.js`](test-fixture/resources.js) and [`test-fixture/schema.graphql`](test-fixture/schema.graphql) for working examples.
+
+## Migrating from `@harperfast/vite-plugin`
+
+This package was previously published as `@harperfast/vite-plugin` (through `0.3.0-beta.9`). Starting with `1.0.0` it is `@harperfast/vite`. The plugin's own API and behavior are unchanged — steps 1–2 are the rename; steps 3–4 are a quick check that the rest of your setup is in the shape the plugin expects.
+
+1. Swap the dependency:
+
+   ```bash
+   npm uninstall @harperfast/vite-plugin
+   npm install @harperfast/vite --save-dev
+   ```
+
+2. Update `config.yaml` — both the component key and its `package`:
+
+   ```diff
+   -'@harperfast/vite-plugin':
+   -  package: '@harperfast/vite-plugin'
+   +'@harperfast/vite':
+   +  package: '@harperfast/vite'
+      files: 'src/**/*'
+      output: 'dist'
+   ```
+
+3. Make sure you have a `static` block. This plugin **builds** (and, in SSR mode, **renders** `index.html`); Harper's built-in `static` plugin **serves** the built assets. If you don't already have one, add it after the plugin block, pointed at the same directory as `output`:
+
+   ```yaml
+   static:
+     files: 'dist/**' # same directory as the plugin's `output`
+   ```
+
+   For an **SSR** app add `index: false` (the plugin renders `index.html`); for an **SPA** leave `index` on and optionally set `notFound: index.html` for client-side routing. See [Usage](#usage).
+
+4. Review your `vite.config.ts`. Nothing is strictly required — the plugin auto-resolves it and overrides Vite's build `outDir` with its `output` when it builds — but set `build.outDir` to the same directory so a standalone `vite build` stays consistent, alongside your framework plugin(s):
+
+   ```ts
+   import { defineConfig } from 'vite';
+   import react from '@vitejs/plugin-react'; // or your framework's Vite plugin
+
+   export default defineConfig({
+   	plugins: [react()],
+   	build: {
+   		outDir: 'dist', // match the plugin's `output`
+   		emptyOutDir: true,
+   	},
+   });
+   ```
+
+`@harperfast/vite-plugin` is deprecated and will receive no further updates.
+
+## Tools Used
+
+1. [TypeScript](https://www.typescriptlang.org/) for static typing
+2. [ESLint](https://eslint.org/) for linting
+3. [Prettier](https://prettier.io/) for code formatting
+4. [Vite](https://vite.dev/) for the development server, middleware, and production build
+5. Harper's built-in `static` plugin for serving the built output in production

package/config.yaml

@@ -0,0 +1,7 @@
+# Build-coordination table (see schema.graphql). Loaded before the plugin module so the table
+# exists when the plugin runs.
+graphqlSchema:
+  files: 'schema.graphql'
+
+# Plugin entry point (required by Harper)
+pluginModule: 'dist/index.js'

package/dist/auth.d.ts

@@ -0,0 +1,49 @@
+import { type Scope, type User } from 'harper';
+import type { Middleware } from './http.ts';
+/**
+ * Harper's canonical "is this a super_user" check. Matches how Harper itself gates privileged paths
+ * (e.g. impersonation, token minting): the resolved user carries `role.permission.super_user === true`.
+ */
+export declare function isSuperUser(user: User | undefined): boolean;
+/**
+ * A Connect middleware that restricts the chain behind it (the Vite dev server) to Harper `super_user`s,
+ * authenticated via HTTP Basic auth. It runs the check itself against Harper's APIs:
+ *
+ * - A super_user Harper already resolved (`req.user`, bridged onto the node request by `registerHttp` —
+ *   e.g. an authenticated admin) passes straight through.
+ * - A loopback peer under `authorizeLocal` (the default in `harper dev`) also passes, authorized here the
+ *   same way the HMR WebSocket gate does it (`isUpgradeAuthorized`): Harper applies `authorizeLocal` to
+ *   MQTT (and its Bun HTTP inject path) but NOT the Node HTTP middleware layer this runs in, so `req.user`
+ *   is unset for a plain loopback `harper dev` request — we trust the real socket peer ourselves rather
+ *   than relying on Harper to pre-set it. So local development passes straight through with no prompt.
+ * - Otherwise we validate an `Authorization: Basic` header directly with `server.authenticateUser` and, on
+ *   failure, reply `401` with a `WWW-Authenticate: Basic` header so a browser prompts for credentials.
+ *
+ * NOTE: this guards the HTTP surface — the Vite dev server's asset, module-transform and `/@fs/`
+ * (arbitrary file read) endpoints, which is the dangerous part. Vite's HMR *WebSocket* runs on its own
+ * port and is not routed through here; keep it bound to localhost (or otherwise unexposed) in any
+ * non-local deployment.
+ */
+export declare function superUserAuth(scope: Scope, realm: string): Middleware;
+/**
+ * Whether a WebSocket upgrade request may reach the Vite dev server — i.e. whether it represents a Harper
+ * `super_user`.
+ *
+ * The HMR WebSocket is served on Harper's own port (see `setupDevelopment`), so the same super_user gate as
+ * the HTTP surface should apply. But Harper runs its auth layer on the HTTP request chain, NOT the upgrade
+ * chain — `req.user` is unset here — so we authorize the raw upgrade ourselves, from the three signals a real
+ * client carries on a same-origin upgrade, cheapest first:
+ *
+ *   1. A loopback peer under `authorizeLocal` — mirrors how Harper trusts localhost for the HTTP surface, so
+ *      plain `harper dev` works with no prompt (the upgrade carries neither a Basic header nor a cookie, and
+ *      `authorizeLocal` sets no cookie). We trust the real socket peer, not a spoofable `X-Forwarded-For`.
+ *   2. An `Authorization: Basic` header, validated exactly like the HTTP gate. Browsers seldom attach this to
+ *      a WebSocket handshake, but CLI clients (and some browsers) do.
+ *   3. The `hdb-session` cookie Harper sets after any successful login (sessions are on by default). Cookies
+ *      ARE reliably sent on a same-origin upgrade, so this is the path that carries a logged-in admin's
+ *      identity from the page to a remotely-exposed HMR socket.
+ *
+ * Best-effort and fails closed: a missing global, store, or lookup error yields `false` (the upgrade is then
+ * refused), never an unauthenticated pass.
+ */
+export declare function isUpgradeAuthorized(scope: Scope, req: any): Promise<boolean>;