@fate-app/mod-build 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stanislav Sonder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @fate-app/mod-build
+
+Vite build preset + dev-mode server for authoring [Assistant for Fate](https://github.com/Stanislavsonder/fate)
+mods — externalizes host-shared libraries (`vue`, `vue-i18n`, `@ionic/vue`,
+`ionicons`) against `window.FateSDK` instead of bundling them, inlines CSS,
+and enforces bundle size limits.
+
+```ts
+// vite.config.ts
+import { defineModConfig } from '@fate-app/mod-build'
+
+export default defineModConfig()
+```
+
+`./testing` exposes `stubFateSDK()`/`smokeLoad()` for headlessly verifying a
+built bundle's shape outside a real app (used by the registry's CI).
+
+Full author-facing documentation lives in the app repo's
+[`docs/MOD_API.md`](https://github.com/Stanislavsonder/fate/blob/main/docs/MOD_API.md).
+Scaffold a new mod project with `pnpm create fate-mod` rather than hand-rolling
+this config.
+
+## Version discipline
+
+This package's version tracks `SDK_VERSION` (the `FateSDK` ABI, defined in
+the app's `src/mods/sdk.ts`) — same major.minor, patch is free. Don't pin a
+version here that doesn't correspond to a real `SDK_VERSION` the app has
+shipped.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { startDevServer } from "./dev.js";
+/**
+ * Published as the `fate-mod-build` binary (package.json `bin`). A real mod
+ * project (outside this monorepo, e.g. one scaffolded by `create-fate-mod`)
+ * runs this via its own `package.json` scripts: `"dev": "fate-mod-build dev"`,
+ * `"build": "fate-mod-build build"`. Inside this monorepo, `example-mod`
+ * still invokes `dev.ts`'s `startDevServer` directly via `devCli.ts` — kept
+ * as-is rather than migrated, since it predates this bin and works fine.
+ */
+async function main() {
+    const [, , command] = process.argv;
+    const root = process.cwd();
+    if (command === 'dev') {
+        const port = Number(process.env.PORT) || 5199;
+        await startDevServer({ root, port });
+        return;
+    }
+    if (command === 'build') {
+        await runBuild(root);
+        return;
+    }
+    console.error(`Unknown command "${command ?? ''}". Usage: fate-mod-build <dev|build>`);
+    process.exit(1);
+}
+/**
+ * Shells `vite build` (no --watch) once. See dev.ts's startDevServer for why
+ * this spawns the CLI (shell:true, a fixed non-interpolated command string)
+ * rather than Vite's programmatic build() API or an argv array.
+ */
+function runBuild(root) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('npx vite build', { cwd: root, stdio: 'inherit', shell: true });
+        child.on('exit', code => (code === 0 ? resolve() : reject(new Error(`vite build exited with code ${code}`))));
+        child.on('error', reject);
+    });
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/dev.d.ts

@@ -0,0 +1,22 @@
+export interface DevServerOptions {
+    /** The mod project root (where manifest.json / translations/ / vite.config.ts live). */
+    root: string;
+    /** Where the watched build writes bundle.mjs — defaults to <root>/dist. */
+    distDir?: string;
+    port?: number;
+}
+export interface DevServerHandle {
+    close(): Promise<void>;
+}
+/**
+ * The author-side half of Developer Mode live reload (see src/mods/devMode.ts
+ * for the app-side client). Spawns `vite build --watch` as a child process —
+ * deliberately NOT Vite's programmatic build() API: at the time this was
+ * written (Vite 8 / rolldown-vite), build({ watch: {} }) produced a
+ * corrupted/incomplete build (dropped modules, SFC parse errors) that the
+ * plain CLI command does not, in this exact project. Spawning the CLI
+ * reuses the code path that's actually proven to work, and decouples "run
+ * the watched build" from "serve files + notify" — a plain fs.watch on the
+ * output directory drives the SSE `/events` endpoint the app subscribes to.
+ */
+export declare function startDevServer(options: DevServerOptions): Promise<DevServerHandle>;

package/dist/dev.js

@@ -0,0 +1,99 @@
+import { createServer as createHttpServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { existsSync, watch as watchFs } from 'node:fs';
+import { join, extname } from 'node:path';
+import { spawn } from 'node:child_process';
+const MIME = {
+    '.json': 'application/json',
+    '.mjs': 'text/javascript',
+    '.js': 'text/javascript'
+};
+/**
+ * The author-side half of Developer Mode live reload (see src/mods/devMode.ts
+ * for the app-side client). Spawns `vite build --watch` as a child process —
+ * deliberately NOT Vite's programmatic build() API: at the time this was
+ * written (Vite 8 / rolldown-vite), build({ watch: {} }) produced a
+ * corrupted/incomplete build (dropped modules, SFC parse errors) that the
+ * plain CLI command does not, in this exact project. Spawning the CLI
+ * reuses the code path that's actually proven to work, and decouples "run
+ * the watched build" from "serve files + notify" — a plain fs.watch on the
+ * output directory drives the SSE `/events` endpoint the app subscribes to.
+ */
+export async function startDevServer(options) {
+    const { root } = options;
+    const port = options.port ?? 5199;
+    const distDir = options.distDir ?? join(root, 'dist');
+    const clients = new Set();
+    function notifyRebuild() {
+        for (const res of clients) {
+            res.write('data: rebuild\n\n');
+        }
+    }
+    // Windows needs shell:true to run npx (a .cmd file) at all; combining shell:true
+    // with an argv array triggers Node's DEP0190 warning (args aren't escaped for
+    // the shell), so pass one fixed, non-interpolated command string instead —
+    // nothing here is ever built from user input.
+    const child = spawn('npx vite build --watch', {
+        cwd: root,
+        stdio: 'inherit',
+        shell: true
+    });
+    // Watches `root` (not distDir directly) because distDir may not exist yet at
+    // startup (e.g. right after `rm -rf dist`) — fs.watch on a not-yet-existing
+    // path never fires for anything created later, silently going dead for the
+    // whole session. `root` always exists; filter to changes under dist/.
+    // Debounced: a rebuild touches multiple files in dist/ in quick succession.
+    let debounceTimer;
+    const fsWatcher = watchFs(root, { recursive: true }, (_event, filename) => {
+        if (!filename || !filename.split(/[\\/]/).includes('dist')) {
+            return;
+        }
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(notifyRebuild, 150);
+    });
+    const server = createHttpServer(async (req, res) => {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+        if (url.pathname === '/events') {
+            res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+            res.write('\n');
+            clients.add(res);
+            req.on('close', () => clients.delete(res));
+            return;
+        }
+        const relative = decodeURIComponent(url.pathname.replace(/^\/+/, ''));
+        // dist/ (the built bundle) takes priority; everything else (manifest.json,
+        // translations/) is served straight from the project root.
+        const distPath = join(distDir, relative);
+        const filePath = existsSync(distPath) ? distPath : join(root, relative);
+        try {
+            const stats = await stat(filePath);
+            if (!stats.isFile()) {
+                throw new Error('not a file');
+            }
+            const contents = await readFile(filePath);
+            res.writeHead(200, { 'Content-Type': MIME[extname(filePath)] ?? 'application/octet-stream' });
+            res.end(contents);
+        }
+        catch {
+            res.writeHead(404);
+            res.end('Not found');
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, resolve);
+    });
+    console.log(`[mod-build dev] serving ${root} at http://localhost:${port} (SSE: /events)`);
+    return {
+        async close() {
+            for (const res of clients) {
+                res.end();
+            }
+            clients.clear();
+            fsWatcher?.close();
+            child.kill();
+            await new Promise((resolve, reject) => server.close(err => (err ? reject(err) : resolve())));
+        }
+    };
+}

package/dist/devCli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/devCli.js

@@ -0,0 +1,13 @@
+/**
+ * Minimal CLI entry for `pnpm dev` in a mod project. Not a published binary
+ * in this phase (Decision #6 in the Phase 2 plan — mod-build only needs to
+ * work from inside this monorepo). A real mod project runs this directly:
+ * `node --experimental-transform-types <path-to>/devCli.ts`.
+ */
+import { startDevServer } from "./dev.js";
+const root = process.cwd();
+const port = Number(process.env.PORT) || 5199;
+startDevServer({ root, port }).catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/fateSdkShims.d.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from 'vite';
+/**
+ * Rewrites imports of host-shared libraries (vue, vue-i18n, @ionic/vue,
+ * ionicons/icons — decision D2 in README.md) into virtual modules that
+ * re-export named bindings from `globalThis.FateSDK.*` instead of bundling
+ * the library. This is what keeps the mod using the HOST's Vue instance
+ * (required for reactivity/provide-inject to work across the bundle
+ * boundary) while still letting mod authors write plain
+ * `import { ref } from 'vue'`.
+ *
+ * Export lists come from the pinned `sdkExports.ts` (see
+ * scripts/generateSdkExports.ts), not a live `import()` at build time — the
+ * latter resolves Node's CJS-interop build of each package (via the "node"
+ * export condition) rather than the browser ESM build Vite/the app actually
+ * use, producing a polluted/incomplete export list.
+ */
+export declare function fateSdkShims(externals: Record<string, string>): Plugin;

package/dist/fateSdkShims.js

@@ -0,0 +1,39 @@
+import { SDK_EXPORTS } from "./sdkExports.js";
+const VIRTUAL_PREFIX = '\0fate-sdk-shim:';
+/**
+ * Rewrites imports of host-shared libraries (vue, vue-i18n, @ionic/vue,
+ * ionicons/icons — decision D2 in README.md) into virtual modules that
+ * re-export named bindings from `globalThis.FateSDK.*` instead of bundling
+ * the library. This is what keeps the mod using the HOST's Vue instance
+ * (required for reactivity/provide-inject to work across the bundle
+ * boundary) while still letting mod authors write plain
+ * `import { ref } from 'vue'`.
+ *
+ * Export lists come from the pinned `sdkExports.ts` (see
+ * scripts/generateSdkExports.ts), not a live `import()` at build time — the
+ * latter resolves Node's CJS-interop build of each package (via the "node"
+ * export condition) rather than the browser ESM build Vite/the app actually
+ * use, producing a polluted/incomplete export list.
+ */
+export function fateSdkShims(externals) {
+    return {
+        name: 'fate-sdk-shims',
+        enforce: 'pre',
+        resolveId(id) {
+            return id in externals ? VIRTUAL_PREFIX + id : null;
+        },
+        load(id) {
+            if (!id.startsWith(VIRTUAL_PREFIX)) {
+                return null;
+            }
+            const specifier = id.slice(VIRTUAL_PREFIX.length);
+            const globalPath = externals[specifier];
+            const names = SDK_EXPORTS[specifier];
+            if (!names) {
+                this.error(`No pinned export list for "${specifier}" — add it in sdkExports.ts (see generateSdkExports.ts).`);
+            }
+            const lines = [`const m = globalThis.${globalPath};`, ...names.map(name => `export const ${name} = m.${name};`)];
+            return lines.join('\n');
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { type UserConfig } from 'vite';
+/**
+ * Host-shared libraries a mod must not bundle its own copy of (decision D2).
+ * Keys are the import specifiers a mod author writes; values are the
+ * `globalThis.FateSDK` path the host installs before loading any mod.
+ */
+export declare const EXTERNALS: Record<string, string>;
+/**
+ * The Vite config a mod project's own vite.config.ts hands back:
+ * `export default defineModConfig()`. Produces a single-file ESM bundle
+ * (`bundle.mjs`) with CSS inlined and injected at load, and the host's
+ * shared libraries externalized via fateSdkShims instead of bundled.
+ */
+export declare function defineModConfig(overrides?: UserConfig): UserConfig;

package/dist/index.js

@@ -0,0 +1,57 @@
+import vue from '@vitejs/plugin-vue';
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js';
+import { defineConfig } from 'vite';
+import { fateSdkShims } from "./fateSdkShims.js";
+import { manifestChecks } from "./manifestChecks.js";
+/**
+ * Host-shared libraries a mod must not bundle its own copy of (decision D2).
+ * Keys are the import specifiers a mod author writes; values are the
+ * `globalThis.FateSDK` path the host installs before loading any mod.
+ */
+export const EXTERNALS = {
+    vue: 'FateSDK.vue',
+    'vue-i18n': 'FateSDK.vueI18n',
+    '@ionic/vue': 'FateSDK.ionicVue',
+    'ionicons/icons': 'FateSDK.ionicons',
+    // Experimental (dice capability) — see docs/MOD_API.md. `Dice`/`DiceMaterial`
+    // themselves are NOT externalized: import them normally from
+    // @fate-app/mod-types, they bundle directly (see that package's dice.ts).
+    three: 'FateSDK.dice.three',
+    'cannon-es': 'FateSDK.dice.cannonEs'
+};
+/**
+ * The Vite config a mod project's own vite.config.ts hands back:
+ * `export default defineModConfig()`. Produces a single-file ESM bundle
+ * (`bundle.mjs`) with CSS inlined and injected at load, and the host's
+ * shared libraries externalized via fateSdkShims instead of bundled.
+ */
+export function defineModConfig(overrides = {}) {
+    return defineConfig({
+        plugins: [vue(), fateSdkShims(EXTERNALS), cssInjectedByJsPlugin(), manifestChecks()],
+        define: {
+            'process.env.NODE_ENV': '"production"',
+            __VUE_OPTIONS_API__: 'true',
+            __VUE_PROD_DEVTOOLS__: 'false',
+            __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false'
+        },
+        build: {
+            lib: {
+                entry: 'bundle.ts',
+                formats: ['es'],
+                fileName: () => 'bundle.mjs'
+            },
+            // Deliberately NOT `rollupOptions.external`: that tells the bundler to
+            // leave `import ... from 'vue'` as a literal, unresolvable bare
+            // specifier in the output (blob-URL `import()` has no bare-specifier
+            // resolution). fateSdkShims virtualizes these specifiers into local
+            // modules instead, which get bundled normally — the opposite of external.
+            rollupOptions: {
+                output: { codeSplitting: false }
+            },
+            cssCodeSplit: false,
+            assetsInlineLimit: 1024 * 1024,
+            emptyOutDir: true
+        },
+        ...overrides
+    });
+}

package/dist/manifestChecks.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from 'vite';
+/** Validates manifest.json presence/shape and warns/errors on bundle size (README.md §4 limits). */
+export declare function manifestChecks(): Plugin;

package/dist/manifestChecks.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+const SOFT_LIMIT_BYTES = 1 * 1024 * 1024;
+const HARD_LIMIT_BYTES = 3 * 1024 * 1024;
+const RECOMMENDED_FIELDS = ['id', 'version', 'name', 'author', 'description', 'loadPriority'];
+/** Validates manifest.json presence/shape and warns/errors on bundle size (README.md §4 limits). */
+export function manifestChecks() {
+    return {
+        name: 'fate-mod-manifest-checks',
+        buildStart() {
+            const manifestPath = resolve(process.cwd(), 'manifest.json');
+            if (!existsSync(manifestPath)) {
+                this.error('manifest.json not found in the mod project root — every mod must ship one alongside its bundle.');
+            }
+            let manifest;
+            try {
+                manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            }
+            catch (e) {
+                this.error(`manifest.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+                return;
+            }
+            for (const field of RECOMMENDED_FIELDS) {
+                if (!(field in manifest)) {
+                    this.warn(`manifest.json is missing recommended field "${field}"`);
+                }
+            }
+        },
+        writeBundle(_options, bundle) {
+            for (const [fileName, output] of Object.entries(bundle)) {
+                if (!fileName.endsWith('.mjs') && !fileName.endsWith('.js')) {
+                    continue;
+                }
+                const size = 'code' in output ? Buffer.byteLength(output.code, 'utf-8') : 0;
+                if (size > HARD_LIMIT_BYTES) {
+                    this.error(`${fileName} is ${(size / 1024 / 1024).toFixed(2)}MB, over the 3MB hard limit for a mod bundle.`);
+                }
+                else if (size > SOFT_LIMIT_BYTES) {
+                    this.warn(`${fileName} is ${(size / 1024).toFixed(0)}KB, over the 1MB soft limit for a mod bundle — consider trimming assets.`);
+                }
+            }
+        }
+    };
+}

package/dist/sdkExports.d.ts

@@ -0,0 +1 @@
+export declare const SDK_EXPORTS: Record<string, string[]>;