vite-plugin-spiral 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# vite-plugin-spiral
+
+Vite integration for Spiral applications. It configures backend-friendly manifests, hot files, full page refresh, SRI metadata, SSR output, typed asset directories, optional asset glob processing, and optional self-hosted fonts.
+
+## Install
+
+```bash
+npm install -D vite-plugin-spiral
+```
+
+Install `fontaine` only when using metric-optimized font fallbacks:
+
+```bash
+npm install -D fontaine
+```
+
+## Usage
+
+```ts
+import { defineConfig } from 'vite'
+import spiral from 'vite-plugin-spiral'
+
+export default defineConfig({
+  plugins: [
+    spiral({
+      input: [
+        'app/resources/css/fonts.css',
+        'app/resources/css/app.css',
+        'app/resources/js/app.ts',
+      ],
+      refresh: true,
+      integrity: true,
+    }),
+  ],
+})
+```
+
+Use application scripts:
+
+```bash
+npm run dev
+npm run build
+```
+
+## Options
+
+- `input`: entry point or entry points. Shorthand is supported: `spiral('app/resources/js/app.ts')`.
+- `publicDirectory`: defaults to `public`.
+- `buildDirectory`: defaults to `build`.
+- `hotFile`: defaults to `runtime/vite.hot`.
+- `ssr`: SSR entry point; `ssrOutputDirectory` defaults to `runtime/vite-ssr`.
+- `refresh`: `true`, `false`, paths, or `{ paths, config }` for `vite-plugin-full-reload`.
+- `integrity`: `true` uses `sha384`; `sha256`, `sha384`, and `sha512` are supported.
+- `assets`: glob or globs emitted as versioned build assets.
+- `fonts`: optional local, Google, Bunny, or Fontsource font definitions.
+- `output`: custom `jsDirectory`, `cssDirectory`, `imageDirectory`, `fontDirectory`, and `assetDirectory`.
+- `detectTls`: `true`, a host string, `null`, or `false` for Herd / Valet TLS detection.
+- `valetTls`: deprecated alias for `detectTls`; `detectTls` wins when both are set.
+
+The plugin adds aliases for `@` -> `app/resources/js` and `@resources` -> `app/resources`. User aliases override defaults.
+Vite 8 `build.rolldownOptions.input` is supported, with `build.rollupOptions.input` accepted as a migration fallback.
+
+## Environment
+
+- `SPIRAL_VITE_ASSET_URL`, fallback `ASSET_URL`, prefixes production asset URLs.
+- `SPIRAL_APP_URL`, fallback `APP_URL`, is used for CORS and dev-server output.
+- `SPIRAL_VITE_PORT`, fallback `VITE_PORT`, sets the dev server port.
+- `SPIRAL_VITE_ALLOWED_ORIGINS` adds comma-separated CORS origins.
+- `SPIRAL_VITE_DEV_SERVER_KEY` and `SPIRAL_VITE_DEV_SERVER_CERT` enable HTTPS.
+- `SPIRAL_VITE_BYPASS_ENV_CHECK=1` allows running dev server in CI or production envs.
+
+## Fonts
+
+Fonts are opt-in and do not replace standalone CSS entries.
+
+```ts
+import spiral from 'vite-plugin-spiral'
+import { local, google, fontsource } from 'vite-plugin-spiral/fonts'
+
+spiral({
+  input: ['app/resources/css/fonts.css', 'app/resources/css/app.css', 'app/resources/js/app.ts'],
+  fonts: [
+    local('Chocolate Classical Sans', {
+      variants: [
+        {
+          src: 'app/resources/fonts/ChocolateClassicalSans-Regular.woff2',
+          weight: 400,
+        },
+      ],
+      fallbacks: ['Noto Sans TC', 'PingFang TC', 'Microsoft JhengHei'],
+      optimizedFallbacks: true,
+    }),
+    google('Montserrat', {
+      weights: [300, 400, 500, 600, 700],
+      subsets: ['latin'],
+    }),
+    fontsource('Inter', {
+      weights: [400, 600],
+    }),
+  ],
+})
+```
+
+Builds emit `fonts-manifest.json`; dev writes `runtime/fonts-manifest.dev.json`. `optimizedFallbacks: true` generates metric-adjusted fallback `@font-face` rules through the optional `fontaine` peer dependency and fails loudly when `fontaine` is missing.
+
+## Cleaning Orphaned Assets
+
+After repeated production builds, remove files no longer referenced by manifests:
+
+```bash
+npx spiral-vite-clean --dry-run --verbose
+npx spiral-vite-clean
+```
+
+The command scans `public/build/manifest.json`, `fonts-manifest.json`, and `ssr-manifest.json` when present. It only deletes files inside the configured build directory.

package/dist/bin/clean.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+interface CleanOptions {
+    cwd?: string;
+    publicDirectory?: string;
+    buildDirectory?: string;
+    manifest?: string;
+    fontsManifest?: string;
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+interface CleanResult {
+    buildRoot: string;
+    deleted: string[];
+    kept: string[];
+    manifests: string[];
+}
+declare function cleanOrphanedAssets(options?: CleanOptions): Promise<CleanResult>;
+declare function runCleanAssetsCli(argv?: string[], cwd?: string): Promise<number>;
+
+export { type CleanOptions, type CleanResult, cleanOrphanedAssets, runCleanAssetsCli };

package/dist/bin/clean.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+// src/bin/clean.ts
+import { promises as fs } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+async function cleanOrphanedAssets(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const publicDirectory = trimSlashes(options.publicDirectory ?? "public");
+  const buildDirectory = trimSlashes(options.buildDirectory ?? "build");
+  const manifest = options.manifest ?? "manifest.json";
+  const fontsManifest = options.fontsManifest ?? "fonts-manifest.json";
+  const buildRoot = path.resolve(cwd, publicDirectory, buildDirectory);
+  const referenced = /* @__PURE__ */ new Set();
+  const manifests = [];
+  if (!await isDirectory(buildRoot)) {
+    return { buildRoot, deleted: [], kept: [], manifests: [] };
+  }
+  for (const name of [manifest, fontsManifest, "ssr-manifest.json"]) {
+    const relative = normalizeRelative(name);
+    if (relative === null) {
+      throw new Error(`vite-plugin-spiral: Manifest path "${name}" must be relative.`);
+    }
+    const file = path.join(buildRoot, relative);
+    if (!await isFile(file)) {
+      continue;
+    }
+    referenced.add(relative);
+    manifests.push(relative);
+    collectReferences(JSON.parse(await fs.readFile(file, "utf8")), referenced, buildDirectory);
+  }
+  if (manifests.length === 0) {
+    throw new Error(`vite-plugin-spiral: No manifest files were found in "${buildRoot}". Refusing to clean without a live asset list.`);
+  }
+  const files = await listFiles(buildRoot);
+  const deleted = [];
+  const kept = [];
+  for (const file of files) {
+    if (referenced.has(file) || path.basename(file) === "vite.hot") {
+      kept.push(file);
+      continue;
+    }
+    deleted.push(file);
+    if (!options.dryRun) {
+      await fs.rm(safeJoin(buildRoot, file), { force: true });
+    }
+  }
+  if (!options.dryRun) {
+    await removeEmptyDirectories(buildRoot);
+  }
+  return { buildRoot, deleted, kept, manifests };
+}
+async function runCleanAssetsCli(argv = process.argv.slice(2), cwd = process.cwd()) {
+  const options = parseArgs(argv);
+  const result = await cleanOrphanedAssets({ ...options, cwd });
+  if (options.verbose || options.dryRun) {
+    const action = options.dryRun ? "Would delete" : "Deleted";
+    for (const file of result.deleted) {
+      console.log(`${action}: ${file}`);
+    }
+  }
+  if (options.verbose) {
+    console.log(`Build directory: ${result.buildRoot}`);
+    console.log(`Manifests: ${result.manifests.length === 0 ? "(none)" : result.manifests.join(", ")}`);
+    console.log(`Kept: ${result.kept.length}`);
+    console.log(`${options.dryRun ? "Matched orphans" : "Deleted orphans"}: ${result.deleted.length}`);
+  }
+  return 0;
+}
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      options.verbose = true;
+      continue;
+    }
+    const [name, inlineValue] = arg.split("=", 2);
+    if (!name.startsWith("--")) {
+      throw new Error(`vite-plugin-spiral: Unknown argument "${arg}".`);
+    }
+    const value = inlineValue ?? argv[++index];
+    if (value === void 0 || value.startsWith("--")) {
+      throw new Error(`vite-plugin-spiral: Option "${name}" requires a value.`);
+    }
+    if (name === "--public-directory") {
+      options.publicDirectory = value;
+    } else if (name === "--build-directory") {
+      options.buildDirectory = value;
+    } else if (name === "--manifest") {
+      options.manifest = value;
+    } else if (name === "--fonts-manifest") {
+      options.fontsManifest = value;
+    } else {
+      throw new Error(`vite-plugin-spiral: Unknown argument "${arg}".`);
+    }
+  }
+  return options;
+}
+function collectReferences(value, references, buildDirectory) {
+  if (typeof value === "string") {
+    const reference = normalizeManifestReference(value, buildDirectory);
+    if (reference !== null) {
+      references.add(reference);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectReferences(item, references, buildDirectory);
+    }
+    return;
+  }
+  if (typeof value === "object" && value !== null) {
+    for (const item of Object.values(value)) {
+      collectReferences(item, references, buildDirectory);
+    }
+  }
+}
+function normalizeManifestReference(value, buildDirectory) {
+  if (value === "" || /^[a-z][a-z\d+.-]*:/i.test(value) || value.startsWith("//")) {
+    return null;
+  }
+  const cleaned = value.split("#", 1)[0].split("?", 1)[0];
+  let relative = cleaned.replace(/^\/+/, "").replace(/\\/g, "/");
+  const buildPrefix = `${trimSlashes(buildDirectory)}/`;
+  if (relative.startsWith(buildPrefix)) {
+    relative = relative.slice(buildPrefix.length);
+  }
+  return normalizeRelative(relative);
+}
+async function listFiles(root, prefix = "") {
+  const entries = await fs.readdir(path.join(root, prefix), { withFileTypes: true });
+  const files = await Promise.all(entries.map(async (entry) => {
+    const relative = path.posix.join(prefix, entry.name);
+    if (entry.isDirectory()) {
+      return listFiles(root, relative);
+    }
+    return [relative];
+  }));
+  return files.flat().sort();
+}
+async function removeEmptyDirectories(root, prefix = "") {
+  const absolute = path.join(root, prefix);
+  const entries = await fs.readdir(absolute, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      await removeEmptyDirectories(root, path.posix.join(prefix, entry.name));
+    }
+  }
+  if (prefix !== "" && (await fs.readdir(absolute)).length === 0) {
+    await fs.rmdir(absolute);
+  }
+}
+async function isFile(file) {
+  try {
+    return (await fs.stat(file)).isFile();
+  } catch {
+    return false;
+  }
+}
+async function isDirectory(directory) {
+  try {
+    return (await fs.stat(directory)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function safeJoin(root, relative) {
+  const resolved = path.resolve(root, relative);
+  const normalizedRoot = path.resolve(root);
+  if (resolved !== normalizedRoot && !resolved.startsWith(`${normalizedRoot}${path.sep}`)) {
+    throw new Error(`vite-plugin-spiral: Refusing to delete path outside build directory: ${relative}`);
+  }
+  return resolved;
+}
+function normalizeRelative(value) {
+  const relative = value.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (relative === "" || relative.split("/").includes("..")) {
+    return null;
+  }
+  return relative;
+}
+function trimSlashes(value) {
+  return value.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+}
+var currentFile = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) {
+  runCleanAssetsCli().then((code) => {
+    process.exitCode = code;
+  }).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}
+export {
+  cleanOrphanedAssets,
+  runCleanAssetsCli
+};

package/dist/chunk-VHEBKNM2.js

@@ -0,0 +1,49 @@
+// src/fonts/providers.ts
+function google(family, options) {
+  return buildFontDefinition(family, "google", options);
+}
+function bunny(family, options) {
+  return buildFontDefinition(family, "bunny", options);
+}
+function fontsource(family, options) {
+  return buildFontDefinition(family, "fontsource", options, {
+    _fontsource: { package: options?.package }
+  });
+}
+function local(family, options) {
+  const localOptions = "src" in options && options.src !== void 0 ? { src: options.src } : { variants: options.variants };
+  return buildFontDefinition(family, "local", options, {
+    weights: [],
+    styles: [],
+    subsets: [],
+    _local: localOptions
+  });
+}
+function buildFontDefinition(family, provider, options, extra = {}) {
+  const alias = options?.alias ?? familyToSlug(family);
+  return {
+    family,
+    alias,
+    provider,
+    variable: options?.variable ?? `--font-${alias}`,
+    weights: options?.weights ? [...options.weights] : [400],
+    styles: options?.styles ?? ["normal"],
+    subsets: options?.subsets ?? ["latin"],
+    display: options?.display ?? "swap",
+    preload: options?.preload ?? true,
+    fallbacks: options?.fallbacks ?? [],
+    optimizedFallbacks: options?.optimizedFallbacks ?? false,
+    ...extra
+  };
+}
+function familyToSlug(family) {
+  return family.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+
+export {
+  google,
+  bunny,
+  fontsource,
+  local,
+  familyToSlug
+};

package/dist/fonts/index.d.ts

@@ -0,0 +1,9 @@
+import { j as FontWeight, R as RemoteFontOptions, F as FontDefinition, k as FontsourceFontOptions, L as LocalFontOptions } from '../types-B2Q2BHEj.js';
+export { B as BaseFontOptions, a as FontDisplay, b as FontFormat, c as FontManifest, d as FontManifestFamily, e as FontManifestPreload, f as FontManifestVariant, g as FontManifestVariantFile, h as FontProviderType, i as FontStyle, l as LocalVariantDefinition, P as ParsedFontFace, m as ParsedFontSrc, n as PreloadSelector, o as RemoteFontStyle, p as ResolvedFontFamily, q as ResolvedFontFile, r as ResolvedFontVariant } from '../types-B2Q2BHEj.js';
+
+declare function google<const W extends FontWeight = FontWeight>(family: string, options?: RemoteFontOptions<W>): FontDefinition;
+declare function bunny<const W extends FontWeight = FontWeight>(family: string, options?: RemoteFontOptions<W>): FontDefinition;
+declare function fontsource<const W extends FontWeight = FontWeight>(family: string, options?: FontsourceFontOptions<W>): FontDefinition;
+declare function local(family: string, options: LocalFontOptions): FontDefinition;
+
+export { FontDefinition, FontWeight, FontsourceFontOptions, LocalFontOptions, RemoteFontOptions, bunny, fontsource, google, local };

package/dist/fonts/index.js

@@ -0,0 +1,12 @@
+import {
+  bunny,
+  fontsource,
+  google,
+  local
+} from "../chunk-VHEBKNM2.js";
+export {
+  bunny,
+  fontsource,
+  google,
+  local
+};

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { PluginOption } from 'vite';
+import { Config } from 'vite-plugin-full-reload';
+import { F as FontDefinition } from './types-B2Q2BHEj.js';
+
+type SpiralInput = string | string[] | Record<string, string>;
+type SpiralPluginConfig = SpiralInput | SpiralPluginOptions;
+type SpiralRefreshConfig = {
+    paths: string[];
+    config?: Config;
+};
+type SpiralRefreshOption = boolean | string | string[] | SpiralRefreshConfig | SpiralRefreshConfig[];
+type SpiralIntegrityAlgorithm = 'sha256' | 'sha384' | 'sha512';
+interface SpiralOutputOptions {
+    jsDirectory?: string;
+    cssDirectory?: string;
+    imageDirectory?: string;
+    fontDirectory?: string;
+    assetDirectory?: string;
+}
+interface SpiralPluginOptions {
+    input: SpiralInput;
+    publicDirectory?: string;
+    buildDirectory?: string;
+    hotFile?: string;
+    refresh?: SpiralRefreshOption;
+    ssr?: SpiralInput;
+    ssrOutputDirectory?: string;
+    integrity?: boolean | SpiralIntegrityAlgorithm;
+    assetUrl?: string;
+    detectTls?: string | boolean | null;
+    /** @deprecated Use detectTls instead. */
+    valetTls?: string | boolean | null;
+    assets?: string | string[];
+    fonts?: FontDefinition[];
+    transformOnServe?: (code: string, devServerUrl: string) => string;
+    server?: {
+        origin?: string;
+        corsOrigin?: string | string[];
+    };
+    output?: SpiralOutputOptions;
+}
+declare function spiral(config: SpiralPluginConfig): PluginOption[];
+
+export { type SpiralInput, type SpiralIntegrityAlgorithm, type SpiralOutputOptions, type SpiralPluginConfig, type SpiralPluginOptions, type SpiralRefreshConfig, type SpiralRefreshOption, spiral as default, spiral };