@forgebook/sveltekit 0.0.0-stage → 0.2.0

package/dist/src/vite/envModules.js

@@ -0,0 +1,181 @@
+/**
+ * The modules of a SvelteKit project's environment, written for a catalogue: the public variables as SvelteKit gives
+ * them to the browser, and a module that refuses to load for every one only a server may read.
+ *
+ * @remarks
+ * SvelteKit 2 gives the variables whose name has the public prefix (`PUBLIC_`) through `$env/static/public` and
+ * `$env/dynamic/public`; SvelteKit 3 the variables `src/env.ts` declares `public`, checked by their schema, through
+ * `$app/env/public`. Nothing else of the environment reaches the page: `$env/static/private`, `$app/env/private` and
+ * `$app/server` throw as they are loaded, so a component that reads a secret fails in its frame rather than shipping it.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { codeOfJson } from "forgebook/code-literal";
+import { runnerImport } from "vite";
+/** The modules only a server may load, with what each is. */
+export const SERVER_ONLY = {
+    "$env/static/private": "the private environment",
+    "$env/dynamic/private": "the private environment",
+    "$app/env/private": "the private environment",
+    "$app/server": "the server's own functions (getRequestEvent, read, the remote functions)",
+    "$service-worker": "the service worker's own module"
+};
+/** The public environment modules, by the name a component imports. */
+export const PUBLIC_ENV = ["$env/static/public", "$env/dynamic/public", "$app/env/public"];
+/** A name JavaScript takes as an export's. */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** The words a `const` cannot be named, which a variable or an import may still be called. */
+const RESERVED = new Set("await break case catch class const continue debugger default delete do else enum export extends false finally for function if implements import in instanceof interface let new null package private protected public return static super switch this throw true try typeof var void while with yield".split(" "));
+/** The names `src/env` may have, in the order SvelteKit 3 looks for them. */
+const ENV_FILES = ["env.ts", "env.js", "env.mts", "env.mjs"];
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A value written in a module: a big integer as its literal, a value JSON writes nothing for as `undefined`.
+ *
+ * @param value - the value.
+ */
+const written = (value) => {
+    if (typeof value === "bigint")
+        return `${value}n`;
+    const json = JSON.stringify(value);
+    return typeof json === "string" ? codeOfJson(json) : "undefined";
+};
+/** The query a server-only import is rewritten with, naming what it imports (`?names=SECRET,TOKEN`). */
+const NAMES_QUERY = "?names=";
+/** An import of named exports: its names and its module. */
+const NAMED_IMPORT = /import\s*(?:[\w$]+\s*,\s*)?\{([^}]*)\}\s*from\s*(["'])([^"']+)\2/g;
+/**
+ * A module that refuses to load in a story: it declares the names its importer asked for, so the browser links it and
+ * runs it, and its error, which says why, is the one the frame shows.
+ *
+ * @param id - the module's name, with the names it is imported with (`$app/env/private?names=TOKEN`).
+ * @param reason - the error's message.
+ */
+export const refusedModule = (id, reason) => {
+    const [, names = ""] = id.split(NAMES_QUERY);
+    const declared = names.split(",").filter((item) => IDENTIFIER.test(item) && !RESERVED.has(item));
+    return [
+        `throw new Error(${written(reason)});`,
+        ...declared.map((item) => `export const ${item} = undefined;`),
+        "export default undefined;",
+        ""
+    ].join("\n");
+};
+/**
+ * A server-only module, refusing to load with why.
+ *
+ * @param id - the module's name, with the names it is imported with.
+ */
+export const serverOnlyModule = (id) => {
+    const name = kitModuleName(id) ?? id;
+    return refusedModule(id, `${name} is ${SERVER_ONLY[name] ?? "server code"}, which only a server may load: a component drawn in a catalogue cannot import it. Give the story what it reads through its args or its page's data.`);
+};
+/**
+ * A module's code with its named imports of SvelteKit's environment and server modules naming what they import, so a
+ * module that refuses to load (`refusedModule`) can declare them.
+ *
+ * @param code - the module's code.
+ * @returns the code, or none when it imports none of those modules by name.
+ */
+export const namedServerImports = (code) => {
+    let isChanged = false;
+    const rewritten = code.replace(NAMED_IMPORT, (statement, list, quote, source) => {
+        if (kitModuleName(source) === undefined)
+            return statement;
+        isChanged = true;
+        const names = list
+            .split(",")
+            .map((item) => item
+            .trim()
+            .split(/\s+as\s+/)[0]
+            ?.replace(/^type\s+/, "") ?? "")
+            .filter((item) => item !== "");
+        return statement.replace(`${quote}${source}${quote}`, `${quote}${source}${NAMES_QUERY}${names.join(",")}${quote}`);
+    });
+    return isChanged ? rewritten : undefined;
+};
+/**
+ * The environment or server module of SvelteKit a name stands for, its query left out; none for another module.
+ *
+ * @param source - an import's module.
+ */
+export const kitModuleName = (source) => {
+    const [name = source] = source.split(NAMES_QUERY);
+    return name in SERVER_ONLY || PUBLIC_ENV.some((known) => known === name) ? name : undefined;
+};
+/**
+ * Whether a name is a server-only module, its query left out.
+ *
+ * @param source - an import's module.
+ */
+export const isServerOnly = (source) => {
+    const [name = source] = source.split(NAMES_QUERY);
+    return name in SERVER_ONLY;
+};
+/**
+ * The variables SvelteKit 2 gives the browser: those with the public prefix, and not the private one.
+ *
+ * @param env - every variable, by name.
+ * @param publicPrefix - `env.publicPrefix` (`PUBLIC_`).
+ * @param privatePrefix - `env.privatePrefix` (empty by default).
+ */
+export const publicVariables = (env, publicPrefix, privatePrefix) => Object.fromEntries(Object.entries(env).filter(([name]) => name.startsWith(publicPrefix) && (privatePrefix === "" || !name.startsWith(privatePrefix))));
+/**
+ * A module of named exports, one per variable: what a name JavaScript cannot export is left out.
+ *
+ * @param values - the values, by name.
+ */
+export const namedExports = (values) => Object.entries(values)
+    .filter(([name]) => IDENTIFIER.test(name) && !RESERVED.has(name))
+    .map(([name, value]) => `export const ${name} = ${written(value)};\n`)
+    .join("");
+/**
+ * A value checked by a variable's schema: a function, or a Standard Schema (`zod`, `valibot`).
+ *
+ * @param schema - the variable's `schema`.
+ * @param value - the variable's text, or none.
+ * @param name - the variable's name, for the error.
+ */
+const checked = async (schema, value, name) => {
+    if (typeof schema === "function")
+        return Reflect.apply(schema, undefined, [value]);
+    const standard = isRecord(schema) ? schema["~standard"] : undefined;
+    if (!isRecord(standard) || typeof standard["validate"] !== "function") {
+        // SvelteKit wants a variable with no schema set, an empty text included
+        if (value === undefined)
+            throw new Error(`The public variable ${name} is missing: set it, or give it a schema that makes it optional`);
+        return value;
+    }
+    const result = await Reflect.apply(standard["validate"], standard, [value]);
+    if (isRecord(result) && Array.isArray(result["issues"]))
+        throw new Error(`The public variable ${name} is not valid: ${JSON.stringify(result["issues"])}`);
+    return isRecord(result) ? result["value"] : value;
+};
+/**
+ * The public variables a SvelteKit 3 project declares in `src/env.ts`, checked by their schemas.
+ *
+ * @param srcDir - the project's source folder (`src`).
+ * @param env - every variable, by name.
+ * @param aliases - the project's aliases.
+ * @returns the values by name, and the files read; none without an env file.
+ */
+export const declaredPublicVariables = async (srcDir, env, aliases = []) => {
+    const file = ENV_FILES.map((name) => join(srcDir, name)).find((path) => existsSync(path));
+    if (file === undefined)
+        return undefined;
+    // the project's aliases, as SvelteKit gives them to its env file (`$lib/…`)
+    const { module } = await runnerImport(file, {
+        configFile: false,
+        logLevel: "silent",
+        resolve: { alias: [...aliases] }
+    });
+    const variables = module["variables"];
+    const values = {};
+    for (const [name, declared] of Object.entries(isRecord(variables) ? variables : {}))
+        if (isRecord(declared) && declared["public"] === true)
+            values[name] = await checked(declared["schema"], env[name], name);
+    return { values, file };
+};

package/dist/src/vite/extractDocs.d.ts

@@ -0,0 +1,14 @@
+import type { ExtractFileComponent, ExtractStoryComponent, StoryFileShape } from "forgebook/vite/adapter";
+/** The module a new story file imports its types from. */
+export declare const storyTypesModule = "@forgebook/sveltekit";
+/** Reads a story file's component, as Svelte's adapter reads it. */
+export declare const extractStoryComponent: ExtractStoryComponent;
+/** Reads a component a file exports, as Svelte's adapter reads it. */
+export declare const extractFileComponent: ExtractFileComponent;
+/**
+ * How a component's stories file is written, as Svelte's adapter writes it.
+ *
+ * @param name - the component's name.
+ * @param file - the component's file, absolute.
+ */
+export declare const storyFileShape: (name: string, file: string) => StoryFileShape;

package/dist/src/vite/extractDocs.js

@@ -0,0 +1,20 @@
+/**
+ * The docs module of a SvelteKit catalogue: Svelte's, since a SvelteKit project's components are Svelte components,
+ * with the story types a new story file imports being this package's (`forgebook new` writes `@forgebook/sveltekit`).
+ *
+ * @module
+ */
+import { extractFileComponent as extractSvelteFileComponent, extractStoryComponent as extractSvelteStoryComponent, storyFileShape as svelteStoryFileShape } from "@forgebook/svelte/docs";
+/** The module a new story file imports its types from. */
+export const storyTypesModule = "@forgebook/sveltekit";
+/** Reads a story file's component, as Svelte's adapter reads it. */
+export const extractStoryComponent = (storyFile) => extractSvelteStoryComponent(storyFile);
+/** Reads a component a file exports, as Svelte's adapter reads it. */
+export const extractFileComponent = (file, exportName) => extractSvelteFileComponent(file, exportName);
+/**
+ * How a component's stories file is written, as Svelte's adapter writes it.
+ *
+ * @param name - the component's name.
+ * @param file - the component's file, absolute.
+ */
+export const storyFileShape = (name, file) => svelteStoryFileShape(name, file);

package/dist/src/vite/kitPlugin.d.ts

@@ -0,0 +1,28 @@
+import { type VitePaths } from "forgebook/vite/paths";
+import { type Alias, type Plugin } from "vite";
+import { type KitAppSettings } from "../appSettings.ts";
+import type { KitProject } from "./kitProject.ts";
+/**
+ * The aliases of SvelteKit's `alias` option and of `$lib`, as SvelteKit writes them: a name for itself and what is
+ * below it, a name ending in `/*` for what is below it. Each leads to a path in Vite's form, with forward slashes on
+ * every system: what a name leads to is written after it (`$lib/site` to `<lib>/site`), so a Windows path would come
+ * out half in backslashes.
+ *
+ * @param project - the project.
+ * @param paths - the system's path functions; the running system's by default.
+ */
+export declare const projectAliases: (project: Pick<KitProject, "kit" | "dir">, paths?: VitePaths) => Alias[];
+/**
+ * The script the frame's page runs before any module: the settings the stand-ins read. Set inline in the page, so
+ * every value is a `codeLiteral`: no text in it can close the script.
+ *
+ * @param settings - the settings.
+ */
+export declare const pageScript: (settings: KitAppSettings) => string;
+/**
+ * The plugin of a SvelteKit catalogue.
+ *
+ * @param project - the project, read.
+ * @returns the plugin.
+ */
+export declare const kitPlugin: (project: KitProject) => Plugin;

package/dist/src/vite/kitPlugin.js

@@ -0,0 +1,241 @@
+/**
+ * The Vite plugin that lets a SvelteKit project's components draw outside SvelteKit: `$app/*` resolved to stand-ins
+ * that work in a story, `$lib` and the project's aliases, the public environment, and the project's routes written in
+ * the frame's page.
+ *
+ * @remarks
+ * What a stand-in does and why is in each module of `src/app`. The settings the stand-ins read (the base path, the
+ * version, the routes) are written in the frame's page before any module runs (`appSettings.ts`), read again when a
+ * route or a static file is added or removed. The environment modules are written from the project's `.env` files and
+ * the environment as SvelteKit would give them to the browser (`envModules.ts`).
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { codeLiteral } from "forgebook/code-literal";
+import { VITE_PATHS } from "forgebook/vite/paths";
+import { loadEnv } from "vite";
+import { APP_SETTINGS_KEY, SETTINGS_CONSTANT } from "../appSettings.js";
+import { declaredPublicVariables, isServerOnly, kitModuleName, namedExports, namedServerImports, PUBLIC_ENV, publicVariables, refusedModule, serverOnlyModule } from "./envModules.js";
+import { projectRoutes, projectStaticFiles } from "./projectFiles.js";
+/** The modules a story gets Forgebook's stand-in for, by the stand-in's export of this package. */
+const STAND_INS = {
+    "$app/env": "app/env",
+    "$app/environment": "app/env",
+    "$app/forms": "app/forms",
+    "$app/manifest": "app/manifest",
+    "$app/navigation": "app/navigation",
+    "$app/paths": "app/paths",
+    "$app/state": "app/state",
+    "$app/stores": "app/stores"
+};
+/** The prefix of the modules this plugin writes. */
+const VIRTUAL = "\0forgebook-sveltekit:";
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A text of SvelteKit's options, or a default.
+ *
+ * @param options - an object of the options.
+ * @param key - its key.
+ * @param fallback - the default.
+ */
+const textOption = (options, key, fallback) => {
+    const value = isRecord(options) ? options[key] : undefined;
+    return typeof value === "string" ? value : fallback;
+};
+/**
+ * A text written as a regular expression that matches it alone.
+ *
+ * @param name - the text.
+ */
+const exactly = (name) => new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")}$`);
+/**
+ * A module this package exports, as a file.
+ *
+ * @param subpath - the export (`app/state`).
+ */
+const ownExport = (subpath) => fileURLToPath(import.meta.resolve(`@forgebook/sveltekit/${subpath}`));
+/**
+ * The aliases of SvelteKit's `alias` option and of `$lib`, as SvelteKit writes them: a name for itself and what is
+ * below it, a name ending in `/*` for what is below it. Each leads to a path in Vite's form, with forward slashes on
+ * every system: what a name leads to is written after it (`$lib/site` to `<lib>/site`), so a Windows path would come
+ * out half in backslashes.
+ *
+ * @param project - the project.
+ * @param paths - the system's path functions; the running system's by default.
+ */
+export const projectAliases = (project, paths = VITE_PATHS) => {
+    const { kit, dir } = project;
+    const files = isRecord(kit["files"]) ? kit["files"] : {};
+    const aliases = [
+        // SvelteKit 3 has no `$lib`, which a project's own `#lib` import replaces: giving it costs nothing
+        ["$lib", textOption(files, "lib", "src/lib")],
+        ...(isRecord(kit["alias"])
+            ? Object.entries(kit["alias"]).filter((entry) => typeof entry[1] === "string")
+            : [])
+    ];
+    return aliases.flatMap(([name, target]) => {
+        const path = paths.isAbsolute(target) ? paths.normalize(target) : paths.resolve(dir, target);
+        if (name.endsWith("/*")) {
+            const prefix = name.slice(0, -2);
+            return [
+                {
+                    find: new RegExp(`^${exactly(prefix).source.slice(1, -1)}/`),
+                    replacement: `${path.replace(/\/\*$/, "")}/`
+                }
+            ];
+        }
+        return [
+            { find: exactly(name), replacement: path },
+            { find: new RegExp(`^${exactly(name).source.slice(1, -1)}/`), replacement: `${path}/` }
+        ];
+    });
+};
+/**
+ * Why a public environment module is not this SvelteKit's: each has its own, and the other's does not exist, so it
+ * gives nothing (SvelteKit 3 gives no variable by its prefix alone).
+ *
+ * @param module - the module.
+ * @param version - the project's SvelteKit.
+ * @returns the reason, or none for one of this SvelteKit's.
+ */
+const otherKitsModule = (module, version) => {
+    if (module === "$app/env/public")
+        return version === 2
+            ? `${module} is SvelteKit 3's: SvelteKit 2 gives the public variables through $env/static/public and $env/dynamic/public`
+            : undefined;
+    return version === 3
+        ? `${module} is SvelteKit 2's: SvelteKit 3 gives the variables src/env.ts declares public through $app/env/public`
+        : undefined;
+};
+/**
+ * The `.env` files Vite reads for a mode that exist, so an edit to one writes the environment modules again.
+ *
+ * @param envDir - the folder they are in.
+ * @param mode - the mode.
+ */
+const envFiles = (envDir, mode) => [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`]
+    .map((name) => join(envDir, name))
+    // a missing one is not watched: Vite would take it for an import the module makes
+    .filter((file) => existsSync(file));
+/**
+ * The script the frame's page runs before any module: the settings the stand-ins read. Set inline in the page, so
+ * every value is a `codeLiteral`: no text in it can close the script.
+ *
+ * @param settings - the settings.
+ */
+export const pageScript = (settings) => `globalThis[Symbol.for(${codeLiteral(APP_SETTINGS_KEY)})] = ${codeLiteral(settings)};`;
+/**
+ * The plugin of a SvelteKit catalogue.
+ *
+ * @param project - the project, read.
+ * @returns the plugin.
+ */
+export const kitPlugin = (project) => {
+    const { kit, dir } = project;
+    const files = isRecord(kit["files"]) ? kit["files"] : {};
+    const paths = isRecord(kit["paths"]) ? kit["paths"] : {};
+    const env = isRecord(kit["env"]) ? kit["env"] : {};
+    const srcDir = resolve(dir, textOption(files, "src", "src"));
+    const routesDir = resolve(dir, textOption(files, "routes", join(textOption(files, "src", "src"), "routes")));
+    const staticDir = resolve(dir, textOption(files, "assets", "static"));
+    const { extensions, version } = project;
+    let resolved;
+    let settings;
+    const settingsNow = () => {
+        settings ??= {
+            base: textOption(paths, "base", ""),
+            assets: textOption(paths, "assets", ""),
+            version: textOption(kit["version"], "name", ""),
+            routes: projectRoutes(routesDir, extensions),
+            staticFiles: projectStaticFiles(staticDir)
+        };
+        return settings;
+    };
+    const allVariables = () => resolved === undefined ? {} : loadEnv(resolved.mode, resolve(dir, textOption(env, "dir", ".")), "");
+    /**
+     * A public environment module: the variables this SvelteKit gives the browser, or a refusal for the other's module.
+     *
+     * @param name - the module's name, with the names it is imported with.
+     * @param module - the module.
+     * @param watch - adds a file whose edit writes the module again.
+     */
+    const publicEnvModule = async (name, module, watch) => {
+        const refusal = otherKitsModule(module, version);
+        if (refusal !== undefined)
+            return refusedModule(name, refusal);
+        for (const file of envFiles(resolve(dir, textOption(env, "dir", ".")), resolved?.mode ?? "development"))
+            watch(file);
+        const variables = allVariables();
+        if (module === "$app/env/public") {
+            const declared = await declaredPublicVariables(srcDir, variables, projectAliases(project));
+            if (declared === undefined)
+                return "";
+            watch(declared.file);
+            return namedExports(declared.values);
+        }
+        const values = publicVariables(variables, textOption(env, "publicPrefix", "PUBLIC_"), textOption(env, "privatePrefix", ""));
+        return module === "$env/static/public"
+            ? namedExports(values)
+            : `export const env = ${codeLiteral(values)};\n`;
+    };
+    return {
+        name: "forgebook:sveltekit",
+        enforce: "pre",
+        config: () => ({
+            // a server render has no page to write the settings in: the code this package compiles has them instead
+            define: { [SETTINGS_CONSTANT]: codeLiteral(settingsNow()) },
+            // compiled by Vite, so the settings are in it, rather than loaded by Node as it is published
+            ssr: { noExternal: ["@forgebook/sveltekit"] },
+            resolve: {
+                alias: [
+                    ...Object.entries(STAND_INS).map(([name, subpath]) => ({
+                        find: exactly(name),
+                        replacement: ownExport(subpath)
+                    })),
+                    ...projectAliases(project)
+                ]
+            }
+        }),
+        configResolved: (config) => {
+            resolved = config;
+            if (project.problem !== undefined)
+                config.logger.warn(`[forgebook] ${project.problem}`);
+        },
+        configureServer: (server) => {
+            // a route or a static file added or removed is in the next frame's settings
+            const renew = (path) => {
+                if (path.startsWith(routesDir) || path.startsWith(staticDir))
+                    settings = undefined;
+            };
+            for (const event of ["add", "unlink", "addDir", "unlinkDir"])
+                server.watcher.on(event, renew);
+        },
+        transformIndexHtml: (_html, context) => (context.path.split("?")[0] ?? "").endsWith("frame.html")
+            ? [{ tag: "script", children: pageScript(settingsNow()), injectTo: "head-prepend" }]
+            : [],
+        // an import of a server-only module names what it imports, so the module that refuses to load can declare it
+        transform: {
+            filter: { code: /\$(app|env|service-worker)/ },
+            handler: (code) => {
+                const rewritten = namedServerImports(code);
+                return rewritten === undefined ? undefined : { code: rewritten, map: null };
+            }
+        },
+        resolveId: (source) => kitModuleName(source) === undefined ? undefined : `${VIRTUAL}${source}`,
+        async load(id) {
+            if (!id.startsWith(VIRTUAL))
+                return undefined;
+            const name = id.slice(VIRTUAL.length);
+            if (isServerOnly(name))
+                return serverOnlyModule(name);
+            const module = PUBLIC_ENV.find((known) => known === kitModuleName(name));
+            if (module === undefined)
+                return undefined;
+            return publicEnvModule(name, module, (file) => this.addWatchFile(file));
+        }
+    };
+};

package/dist/src/vite/kitProject.d.ts

@@ -0,0 +1,27 @@
+import type { Options as SveltePluginOptions } from "@sveltejs/vite-plugin-svelte";
+import { type Plugin, type PluginOption } from "vite";
+/** What the catalogue reads of a SvelteKit project. */
+export type KitProject = {
+    /** The project's folder. */
+    readonly dir: string;
+    /** SvelteKit's options, as SvelteKit 3 writes them (SvelteKit 2's `kit` key, read the same). */
+    readonly kit: Readonly<Record<string, unknown>>;
+    /** Svelte's options (`preprocess`, `compilerOptions`, `extensions`) for Svelte's Vite plugin; none to read `svelte.config.js`. */
+    readonly svelte: Partial<SveltePluginOptions> | undefined;
+    /** SvelteKit's major version, as its options say: 2 holds them under `kit`, 3 has them at the top. */
+    readonly version: 2 | 3;
+    /** The extensions of the project's Svelte components (`.svelte`, `.svx`): its routes' pages may have any. */
+    readonly extensions: readonly string[];
+    /** The project's other Vite plugins. */
+    readonly plugins: readonly PluginOption[];
+    /** Why the project's configuration could not be read; none when it was. */
+    readonly problem: string | undefined;
+};
+/**
+ * Reads a SvelteKit project.
+ *
+ * @param dir - the project's folder.
+ * @param viteConfig - its Vite configuration, from the folder; the one Vite would find by default; `false` reads none.
+ * @param keepPlugin - whether to keep one of the project's own plugins; every one by default.
+ */
+export declare const loadKitProject: (dir: string, viteConfig: string | false | undefined, keepPlugin?: (plugin: Plugin) => boolean) => Promise<KitProject>;