@txco/vite-plugin 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @txco/vite-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Vite](https://vite.dev) plugin for [Thanks, Computer](https://www.thanks.computer)
+(txco). It's for plain Vite apps: React, Vue, Solid, Preact or vanilla, with no
+meta-framework. After `vite build`, it writes a **Web ABI build** beside your
+`dist/`:
+
+- a copy of `dist/` as `public/`;
+- the ops a browser-routed app needs, as `ops/`;
+- a `txco-web.json` manifest.
+
+`txco apply` installs the build into a stack.
+
+```sh
+npm install -D @txco/vite-plugin
+```
+
+Vite 6, 7 or 8.
+
+## Usage
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import txco from "@txco/vite-plugin";
+
+export default defineConfig({
+  plugins: [react(), txco()],
+});
+```
+
+Bind the build to a stack in your workspace's `txco.yaml`. The path is
+relative to the workspace root, and must lie outside `OPS/`:
+
+```yaml
+stacks:
+  web:
+    abi: txco-web
+```
+
+Then build, check and deploy:
+
+```sh
+vite build                     # writes dist/ as usual, and txco-web/
+txco web check txco-web        # installs it on a scratch chassis and probes it
+txco apply                     # or: txco push web
+```
+
+Gitignore `txco-web/`. It's all build output, and the fallback op embeds
+`index.html`, asset hashes included, so it changes on every build.
+
+## What it writes
+
+```
+txco-web/
+  txco-web.json                  { "abi": 1, "immutable": ["assets/"], … }
+  public/                        a copy of dist/
+  ops/900000/spa-fallback.txcl   200 + index.html, for any page navigation
+  ops/900900/not-found.txcl      a plain 404 for everything else (an asset miss, a POST)
+```
+
+`dist/` is left as Vite wrote it, so `vite preview` and anything else that
+reads it still works.
+
+**A single-page app** (one `index.html`) routes in the browser. Every page
+path that no file or op of yours answers gets `index.html` with status 200.
+The client router renders its own not-found view for a path it doesn't know.
+There's no route table to check, so this is the Web ABI's plain fallback.
+
+**A multi-page app** (several HTML inputs in `build.rollupOptions.input`)
+writes `ops/900000/page-404.txcl` instead. A path with no page gets
+`404.html` with status 404 if the build has one, from `public/404.html` or an
+input page, and a plain 404 page if not.
+
+**`base`.** With `base: "/app/"` the site lands under `public/app/`, and is
+served at `/app/`. A full-URL `base` (a CDN) loads its assets from there; the
+plugin warns.
+
+**Caching.** Vite's hashed output under `assets/` is cached for a year. A
+file you put in `public/assets/` yourself isn't hashed, and the plugin warns
+about it.
+
+**Dot paths** (`public/.well-known/…`) never deploy; the plugin warns and
+leaves them out. Library and SSR builds write nothing.
+
+## Options
+
+| Option      | Default        | Meaning |
+| ----------- | -------------- | ------- |
+| `out`       | `"txco-web"`   | The Web ABI directory to write, relative to the project root. It must be a directory of its own, outside `OPS/` and `dist/`. |
+| `spa`       | detected       | `true` answers every unknown page path with `index.html` and 200; `false` with the 404 page. |
+| `immutable` | `["assets/"]`  | The `public/` prefixes cached for a year. |
+| `scope`     | `900000`       | The navigation op's scope. The catch-all goes 900 above it. |
+
+## Safety
+
+The plugin wipes and rewrites `out` on every build. Before the build starts,
+it refuses an `out` that:
+
+- is inside `OPS/`;
+- is inside `dist/`;
+- holds anything that isn't part of a Web ABI build;
+- holds your project.
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,14 @@
+/**
+ * How a page navigation nothing else answered is handled:
+ *
+ *  - "spa": one page (index.html), which routes in the browser: every page
+ *    path gets the shell with 200;
+ *  - "mpa": several pages, each a file: a path with no page gets 404.html
+ *    (or a built-in 404 page) with 404.
+ */
+export type Mode = "spa" | "mpa";
+/** The mode for a build's HTML pages, unless the `spa` option forces it. */
+export declare function chooseMode(pages: readonly string[], spa?: boolean): Mode;
+/** The page an spa build's fallback serves: index.html, or its only page. */
+export declare function shellPage(pages: readonly string[]): string | null;
+export { isDotPath, publicPrefix } from "@txco/web-abi/producer";

package/dist/build.js

@@ -0,0 +1,16 @@
+// The plugin's decisions about a finished build. Pure, so they're unit-tested.
+/** The mode for a build's HTML pages, unless the `spa` option forces it. */
+export function chooseMode(pages, spa) {
+    if (typeof spa === "boolean")
+        return spa ? "spa" : "mpa";
+    return pages.length > 1 ? "mpa" : "spa";
+}
+/** The page an spa build's fallback serves: index.html, or its only page. */
+export function shellPage(pages) {
+    if (pages.includes("index.html"))
+        return "index.html";
+    return pages.length === 1 ? pages[0] : null;
+}
+// Where the build lands under public/, from `base`, and which paths never
+// deploy: shared with every producer.
+export { isDotPath, publicPrefix } from "@txco/web-abi/producer";

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from "vite";
+export declare const NAME = "@txco/vite-plugin";
+export declare const VERSION = "0.1.0";
+export interface TxcoOptions {
+    /** The Web ABI directory to write, relative to the project root. Default "txco-web". */
+    out?: string;
+    /**
+     * Answer every unknown page path with the shell (index.html) and 200. The
+     * default: on for a one-page build, off for a multi-page one.
+     */
+    spa?: boolean;
+    /** The public/ prefixes cached for a year. Default: Vite's assetsDir (`assets/`). */
+    immutable?: string[];
+    /** The navigation op's scope; the catch-all goes 900 above it. Default 900000. */
+    scope?: number;
+}
+export default function txco(options?: TxcoOptions): Plugin;
+export { chooseMode, publicPrefix } from "./build.js";

package/dist/index.js

@@ -0,0 +1,124 @@
+// @txco/vite-plugin: after `vite build`, writes a Web ABI build for Thanks,
+// Computer (txco) beside your dist/:
+//
+//   txco-web/
+//     txco-web.json   the manifest
+//     public/         a copy of dist/
+//     ops/            the navigation op and the catch-all
+//
+//   // vite.config.ts
+//   import txco from "@txco/vite-plugin";
+//   export default defineConfig({ plugins: [txco()] });
+//
+// `txco apply` installs it into the stack txco.yaml binds it to.
+import { readdir, readFile, rm } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { checkOutDir, copyPublic, listFiles, looksHashed, publicPrefix, renderOps, writeManifest, writeOps, } from "@txco/web-abi/producer";
+import { chooseMode, shellPage } from "./build.js";
+export const NAME = "@txco/vite-plugin";
+export const VERSION = "0.1.0";
+/** An op answer is capped at 4 MiB (--op-payload-max), base64 included. */
+const PAGE_WARN_BYTES = 1 << 20;
+export default function txco(options = {}) {
+    let config;
+    let out = "";
+    let skip = false;
+    return {
+        name: "txco",
+        apply: "build",
+        enforce: "post",
+        // One Web ABI build, from the client build (Vite ≥ 6 asks per environment).
+        applyToEnvironment: (env) => env.name === "client",
+        async configResolved(c) {
+            config = c;
+            if (c.build.lib || c.build.ssr) {
+                skip = true;
+                return;
+            }
+            out = resolve(c.root, options.out ?? "txco-web");
+            const outDir = resolve(c.root, c.build.outDir);
+            // Before anything is written: the build wipes and rewrites `out`.
+            const problems = checkOutDir({
+                dir: out,
+                protect: [c.root, outDir, c.publicDir].filter(Boolean),
+                notInside: [outDir],
+                entries: await readdir(out).catch(() => null),
+            });
+            if (problems.length > 0)
+                throw new Error(`[txco] ${problems.join("\n")}`);
+        },
+        writeBundle: {
+            order: "post",
+            sequential: true,
+            async handler(_output, bundle) {
+                if (skip)
+                    return;
+                const log = config.logger;
+                const warn = (msg) => log.warn(`[txco] ${msg}`);
+                const outDir = resolve(config.root, config.build.outDir);
+                const pages = Object.values(bundle)
+                    .filter((o) => o.type === "asset" && o.fileName.endsWith(".html"))
+                    .map((o) => o.fileName)
+                    .sort();
+                const mode = chooseMode(pages, options.spa);
+                const { prefix, external } = publicPrefix(config.base);
+                if (external)
+                    warn(`base is ${config.base}: the assets load from there, and the pages are deployed at the root`);
+                // dist/ as public/, without what never deploys: .vite/ (build
+                // metadata) quietly, any other dot path with a warning.
+                await rm(out, { recursive: true, force: true });
+                const { skipped: dots } = await copyPublic(outDir, out, prefix);
+                if (dots.length > 0)
+                    warn(`dist/ has ${dots.length} dot path(s) (${dots.slice(0, 3).join(", ")}); they never deploy`);
+                const readPage = async (name) => {
+                    const html = await readFile(join(outDir, name), "utf8").catch(() => null);
+                    return html === null ? null : { name, html };
+                };
+                let page;
+                if (mode === "spa") {
+                    const name = shellPage(pages);
+                    page = name ? await readPage(name) : null;
+                    if (!page)
+                        throw new Error(`[txco] a single-page build needs its shell (index.html), and ${outDir} has none`);
+                }
+                else {
+                    page = await readPage("404.html");
+                }
+                if (page && Buffer.byteLength(page.html) > PAGE_WARN_BYTES) {
+                    warn(`${page.name} is ${Buffer.byteLength(page.html)} bytes; the op that serves it is capped at 4 MiB, base64 included`);
+                }
+                const ops = renderOps({
+                    mode: mode === "spa" ? "spa" : "404",
+                    scope: options.scope,
+                    producer: NAME,
+                    page,
+                    notes: [
+                        mode === "spa"
+                            ? "A Vite app routes in the browser and has no route table to check."
+                            : `This build has ${pages.length} pages, each a file in public/.`,
+                    ],
+                });
+                await writeOps(out, ops);
+                const files = await listFiles(join(out, "public"));
+                const assets = config.build.assetsDir.replace(/^\/+|\/+$/g, "");
+                const immutable = options.immutable ?? (assets && files.some((f) => f.startsWith(`${prefix}${assets}/`)) ? [`${prefix}${assets}/`] : []);
+                for (const p of immutable) {
+                    const unhashed = files.filter((f) => f.startsWith(p) && !looksHashed(f.split("/").pop()));
+                    if (unhashed.length > 0) {
+                        warn(`${unhashed.length} file(s) under the immutable prefix ${p} carry no content hash (${unhashed.slice(0, 3).join(", ")}), so a change to them wouldn't reach a browser for a year`);
+                    }
+                }
+                await writeManifest(out, {
+                    abi: 1,
+                    ...(immutable.length > 0 ? { immutable } : {}),
+                    "x-producer": { name: NAME, version: VERSION },
+                    "x-vite": { version: this.meta.viteVersion, mode, pages: pages.length },
+                });
+                const shown = relative(process.cwd(), out) || ".";
+                log.info(`[txco] Web ABI build (${mode}) at ${shown}: ${files.length} public file(s), ${Object.keys(ops).length} op(s). ` +
+                    `Next: \`txco web check ${shown}\`, bind it in txco.yaml (stacks: <name>: abi: ${shown}), then \`txco apply\`.`);
+            },
+        },
+    };
+}
+export { chooseMode, publicPrefix } from "./build.js";

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@txco/vite-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Vite plugin for Thanks, Computer (txco): after `vite build`, writes a Web ABI build — your dist/ as public/, the ops a browser-routed app needs as ops/, and txco-web.json — for `txco apply` to install.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "spa",
+    "txco",
+    "thanks-computer",
+    "static",
+    "web-abi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoremLabs/thanks-computer.git",
+    "directory": "sdk/vite-plugin"
+  },
+  "homepage": "https://github.com/LoremLabs/thanks-computer/tree/master/sdk/vite-plugin#readme",
+  "bugs": "https://github.com/LoremLabs/thanks-computer/issues",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@txco/web-abi": "^0.2.0"
+  },
+  "peerDependencies": {
+    "vite": "^6.1.0 || ^7.0.0 || ^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^8.3.0"
+  }
+}

package/src/build.ts

@@ -0,0 +1,27 @@
+// The plugin's decisions about a finished build. Pure, so they're unit-tested.
+
+/**
+ * How a page navigation nothing else answered is handled:
+ *
+ *  - "spa": one page (index.html), which routes in the browser: every page
+ *    path gets the shell with 200;
+ *  - "mpa": several pages, each a file: a path with no page gets 404.html
+ *    (or a built-in 404 page) with 404.
+ */
+export type Mode = "spa" | "mpa";
+
+/** The mode for a build's HTML pages, unless the `spa` option forces it. */
+export function chooseMode(pages: readonly string[], spa?: boolean): Mode {
+  if (typeof spa === "boolean") return spa ? "spa" : "mpa";
+  return pages.length > 1 ? "mpa" : "spa";
+}
+
+/** The page an spa build's fallback serves: index.html, or its only page. */
+export function shellPage(pages: readonly string[]): string | null {
+  if (pages.includes("index.html")) return "index.html";
+  return pages.length === 1 ? pages[0] : null;
+}
+
+// Where the build lands under public/, from `base`, and which paths never
+// deploy: shared with every producer.
+export { isDotPath, publicPrefix } from "@txco/web-abi/producer";

package/src/index.ts

@@ -0,0 +1,159 @@
+// @txco/vite-plugin: after `vite build`, writes a Web ABI build for Thanks,
+// Computer (txco) beside your dist/:
+//
+//   txco-web/
+//     txco-web.json   the manifest
+//     public/         a copy of dist/
+//     ops/            the navigation op and the catch-all
+//
+//   // vite.config.ts
+//   import txco from "@txco/vite-plugin";
+//   export default defineConfig({ plugins: [txco()] });
+//
+// `txco apply` installs it into the stack txco.yaml binds it to.
+import { readdir, readFile, rm } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+
+import {
+  checkOutDir,
+  copyPublic,
+  listFiles,
+  looksHashed,
+  publicPrefix,
+  renderOps,
+  writeManifest,
+  writeOps,
+} from "@txco/web-abi/producer";
+import type { Plugin, ResolvedConfig } from "vite";
+
+import { chooseMode, shellPage } from "./build.js";
+
+export const NAME = "@txco/vite-plugin";
+export const VERSION = "0.1.0";
+/** An op answer is capped at 4 MiB (--op-payload-max), base64 included. */
+const PAGE_WARN_BYTES = 1 << 20;
+
+export interface TxcoOptions {
+  /** The Web ABI directory to write, relative to the project root. Default "txco-web". */
+  out?: string;
+  /**
+   * Answer every unknown page path with the shell (index.html) and 200. The
+   * default: on for a one-page build, off for a multi-page one.
+   */
+  spa?: boolean;
+  /** The public/ prefixes cached for a year. Default: Vite's assetsDir (`assets/`). */
+  immutable?: string[];
+  /** The navigation op's scope; the catch-all goes 900 above it. Default 900000. */
+  scope?: number;
+}
+
+export default function txco(options: TxcoOptions = {}): Plugin {
+  let config: ResolvedConfig;
+  let out = "";
+  let skip = false;
+
+  return {
+    name: "txco",
+    apply: "build",
+    enforce: "post",
+    // One Web ABI build, from the client build (Vite ≥ 6 asks per environment).
+    applyToEnvironment: (env) => env.name === "client",
+
+    async configResolved(c) {
+      config = c;
+      if (c.build.lib || c.build.ssr) {
+        skip = true;
+        return;
+      }
+      out = resolve(c.root, options.out ?? "txco-web");
+      const outDir = resolve(c.root, c.build.outDir);
+      // Before anything is written: the build wipes and rewrites `out`.
+      const problems = checkOutDir({
+        dir: out,
+        protect: [c.root, outDir, c.publicDir].filter(Boolean),
+        notInside: [outDir],
+        entries: await readdir(out).catch(() => null),
+      });
+      if (problems.length > 0) throw new Error(`[txco] ${problems.join("\n")}`);
+    },
+
+    writeBundle: {
+      order: "post",
+      sequential: true,
+      async handler(_output, bundle) {
+        if (skip) return;
+        const log = config.logger;
+        const warn = (msg: string) => log.warn(`[txco] ${msg}`);
+        const outDir = resolve(config.root, config.build.outDir);
+
+        const pages = Object.values(bundle)
+          .filter((o) => o.type === "asset" && o.fileName.endsWith(".html"))
+          .map((o) => o.fileName)
+          .sort();
+        const mode = chooseMode(pages, options.spa);
+        const { prefix, external } = publicPrefix(config.base);
+        if (external) warn(`base is ${config.base}: the assets load from there, and the pages are deployed at the root`);
+
+        // dist/ as public/, without what never deploys: .vite/ (build
+        // metadata) quietly, any other dot path with a warning.
+        await rm(out, { recursive: true, force: true });
+        const { skipped: dots } = await copyPublic(outDir, out, prefix);
+        if (dots.length > 0) warn(`dist/ has ${dots.length} dot path(s) (${dots.slice(0, 3).join(", ")}); they never deploy`);
+
+        const readPage = async (name: string) => {
+          const html = await readFile(join(outDir, name), "utf8").catch(() => null);
+          return html === null ? null : { name, html };
+        };
+        let page;
+        if (mode === "spa") {
+          const name = shellPage(pages);
+          page = name ? await readPage(name) : null;
+          if (!page) throw new Error(`[txco] a single-page build needs its shell (index.html), and ${outDir} has none`);
+        } else {
+          page = await readPage("404.html");
+        }
+        if (page && Buffer.byteLength(page.html) > PAGE_WARN_BYTES) {
+          warn(`${page.name} is ${Buffer.byteLength(page.html)} bytes; the op that serves it is capped at 4 MiB, base64 included`);
+        }
+
+        const ops = renderOps({
+          mode: mode === "spa" ? "spa" : "404",
+          scope: options.scope,
+          producer: NAME,
+          page,
+          notes: [
+            mode === "spa"
+              ? "A Vite app routes in the browser and has no route table to check."
+              : `This build has ${pages.length} pages, each a file in public/.`,
+          ],
+        });
+        await writeOps(out, ops);
+
+        const files = await listFiles(join(out, "public"));
+        const assets = config.build.assetsDir.replace(/^\/+|\/+$/g, "");
+        const immutable = options.immutable ?? (assets && files.some((f) => f.startsWith(`${prefix}${assets}/`)) ? [`${prefix}${assets}/`] : []);
+        for (const p of immutable) {
+          const unhashed = files.filter((f) => f.startsWith(p) && !looksHashed(f.split("/").pop()!));
+          if (unhashed.length > 0) {
+            warn(`${unhashed.length} file(s) under the immutable prefix ${p} carry no content hash (${unhashed.slice(0, 3).join(", ")}), so a change to them wouldn't reach a browser for a year`);
+          }
+        }
+
+        await writeManifest(out, {
+          abi: 1,
+          ...(immutable.length > 0 ? { immutable } : {}),
+          "x-producer": { name: NAME, version: VERSION },
+          "x-vite": { version: this.meta.viteVersion, mode, pages: pages.length },
+        });
+
+        const shown = relative(process.cwd(), out) || ".";
+        log.info(
+          `[txco] Web ABI build (${mode}) at ${shown}: ${files.length} public file(s), ${Object.keys(ops).length} op(s). ` +
+            `Next: \`txco web check ${shown}\`, bind it in txco.yaml (stacks: <name>: abi: ${shown}), then \`txco apply\`.`,
+        );
+      },
+    },
+  };
+}
+
+export { chooseMode, publicPrefix } from "./build.js";