@playcademy/vite-plugin 0.0.1-beta.1

package/README.md

@@ -0,0 +1,102 @@
+# @playcademy/vite-plugin
+
+A Vite plugin to generate a `playcademy.manifest.json` for Playcademy games and optionally create a zip archive of the build output.
+
+## Installation
+
+```bash
+# Using bun
+bun add -D @playcademy/vite-plugin
+
+# Using pnpm
+pnpm add -D @playcademy/vite-plugin
+
+# Using yarn
+yarn add --dev @playcademy/vite-plugin
+
+# Using npm
+npm install --save-dev @playcademy/vite-plugin
+```
+
+## Usage
+
+Add the plugin to your `vite.config.ts` or `vite.config.js`:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { playcademy } from '@playcademy/vite-plugin'
+
+export default defineConfig({
+    plugins: [
+        playcademy({
+            // Optional: configure plugin options here
+            // bootMode: 'direct',
+            // entryPoint: 'my-game.html',
+            // styles: ['src/main.css'],
+            // engine: 'phaser',
+            // autoZip: true, // Set to true to enable zipping locally
+        }),
+    ],
+    // ...other Vite config
+})
+```
+
+## What it does
+
+1.  **Generates `playcademy.manifest.json`**:
+    This file is created in your Vite build's output directory (`dist` by default). It contains metadata about your game, such as its entry point, boot mode, and engine type, which is used by the Playcademy platform.
+
+2.  **Creates Output Zip Archive (Optional)**:
+    If `autoZip` is enabled, the plugin will create a zip file named `{your-project-name}.zip` inside a `.playcademy` directory at the root of your project (e.g., `my-game/.playcademy/my-game.zip`).
+    This archive contains all the contents of your build output directory and can be uploaded directly to the Playcademy platform.
+
+3.  **Sets Vite `base` Configuration (if not set by user)**:
+    The plugin defaults Vite's `base` configuration to `'./'`. This is necessary for games to correctly reference assets when deployed on the Playcademy platform. If you explicitly set a `base` path in your `vite.config.ts`, the plugin will respect your configuration and not override it.
+
+## Options (`PlaycademyPluginOptions`)
+
+The `playcademy()` plugin function accepts an optional options object:
+
+- **`bootMode`**:
+
+    - Type: `'iframe' | 'module'`
+    - Default: `'iframe'`
+    - Specifies how the game should be launched.
+
+- **`entryPoint`**:
+
+    - Type: `string`
+    - Default: `'index.html'`
+    - The main HTML file for your game.
+
+- **`styles`**:
+
+    - Type: `string[]`
+    - Default: `[]`
+    - An array of CSS file paths (relative to the project root) that should be loaded by the Playcademy platform.
+
+- **`engine`**:
+
+    - Type: `'three' | 'phaser' | 'godot' | 'unity' | 'custom'`
+    - Default: `'custom'`
+    - Specifies the game engine used.
+
+- **`autoZip`**:
+    - Type: `boolean`
+    - Default: `false`
+    - Controls whether to automatically create a zip archive of the build output.
+
+## Development
+
+To install dependencies for this package:
+
+```bash
+bun install
+```
+
+To build the plugin:
+
+```bash
+bun run build
+```

package/build.ts

@@ -0,0 +1,45 @@
+import { $ } from 'bun'
+import packageJson from './package.json' assert { type: 'json' }
+import yoctoSpinner from 'yocto-spinner'
+
+const startTime = performance.now()
+const spinner = yoctoSpinner({ text: 'Building JavaScript...' }).start()
+
+const buildDir = './dist'
+const entrypoints = ['./src/index.ts']
+
+try {
+    await $`rm -rf ${buildDir}`
+
+    await Bun.build({
+        entrypoints,
+        external: [...Object.keys(packageJson.peerDependencies)],
+        outdir: buildDir,
+        format: 'esm',
+        target: 'node',
+    })
+
+    spinner.text = 'Generating types...'
+
+    const { stderr } =
+        await $`tsc --emitDeclarationOnly --declaration --project tsconfig.types.json --outDir ${buildDir}`
+
+    if (stderr.toString().length) {
+        spinner.error(`Type generation failed:\n${stderr.toString()}`)
+        process.exit(1) // Exit with error code
+    } else {
+        const duration = ((performance.now() - startTime) / 1000).toFixed(2)
+        spinner.success(`Build complete in ${duration}s!`)
+
+        // Log built entrypoints
+        for (const entry of entrypoints) {
+            console.log(`  - ${entry}`)
+        }
+    }
+    process.exit(0)
+} catch (error) {
+    const duration = ((performance.now() - startTime) / 1000).toFixed(2)
+    console.log({ error })
+    spinner.error(`Build failed in ${duration}s: ${error}`)
+    process.exit(1) // Exit with error code
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "@playcademy/vite-plugin",
+    "type": "module",
+    "version": "0.0.1-beta.1",
+    "module": "src/index.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "bun build.ts",
+        "pub": "bun run build && bunx bumpp --no-tag --no-push && bun publish --access public"
+    },
+    "devDependencies": {
+        "@types/archiver": "^6.0.3",
+        "@types/bun": "latest"
+    },
+    "peerDependencies": {
+        "typescript": "^5"
+    },
+    "dependencies": {
+        "archiver": "^7.0.1",
+        "picocolors": "^1.1.1"
+    }
+}

package/src/index.ts

@@ -0,0 +1,231 @@
+import path from 'node:path'
+import fs from 'node:fs/promises'
+import { createWriteStream } from 'node:fs'
+import type { Plugin, ResolvedConfig } from 'vite'
+import { ManifestV1Schema, type ManifestV1 } from '@playcademy/data/schemas'
+import archiver from 'archiver'
+import pc from 'picocolors'
+
+export interface PlaycademyPluginOptions {
+    bootMode?: ManifestV1['bootMode']
+    entryPoint?: string
+    styles?: string[]
+    engine?: ManifestV1['engine']
+    autoZip?: boolean
+}
+
+const LOG_LINE_TOTAL_WIDTH = 60
+
+interface PlaycademyOutputData {
+    manifestPath?: string
+    manifestSizeKb?: string
+    zipPath?: string
+    zipSizeKb?: string
+}
+
+function formatNumberWithCommas(numStr: string): string {
+    if (!numStr) return numStr
+    const parts = numStr.split('.')
+    if (parts[0] === undefined) return numStr
+    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+    return parts.join('.')
+}
+
+async function generatePlaycademyManifest(
+    config: ResolvedConfig,
+    options: Required<Omit<PlaycademyPluginOptions, 'autoZip'>>,
+    outDir: string,
+    buildOutputs: PlaycademyOutputData,
+) {
+    const manifestData: ManifestV1 = {
+        version: '1',
+        bootMode: options.bootMode,
+        entryPoint: options.entryPoint,
+        styles: options.styles || [],
+        engine: options.engine || 'custom',
+        createdAt: new Date().toISOString(),
+    }
+
+    const validation = ManifestV1Schema.safeParse(manifestData)
+
+    if (!validation.success) {
+        console.error(
+            '[Playcademy] Error validating generated manifest data:',
+            validation.error.flatten(),
+        )
+        config.logger.error(
+            '[Playcademy] Failed to generate valid manifest file.',
+        )
+        throw new Error('[Playcademy] Manifest validation failed')
+    }
+
+    const manifestPath = path.resolve(outDir, 'playcademy.manifest.json')
+    const manifestJson = JSON.stringify(validation.data, null, 2)
+
+    await fs.writeFile(manifestPath, manifestJson)
+
+    try {
+        const stats = await fs.stat(manifestPath)
+        buildOutputs.manifestPath = path.relative(config.root, manifestPath)
+        buildOutputs.manifestSizeKb = (stats.size / 1024).toFixed(2)
+    } catch (statError) {
+        config.logger.warn(
+            `[Playcademy] Could not get stats for manifest file: ${statError}`,
+        )
+    }
+}
+
+async function createOutputZipArchive(
+    config: ResolvedConfig,
+    outDir: string,
+    buildOutputs: PlaycademyOutputData,
+) {
+    const projectRoot = path.resolve(config.root)
+    const projectName = path.basename(projectRoot)
+    const playcademyDir = path.resolve(projectRoot, '.playcademy')
+
+    await fs.mkdir(playcademyDir, { recursive: true })
+
+    const zipName = `${projectName}.zip`
+    const zipOutPath = path.resolve(playcademyDir, zipName)
+
+    const output = createWriteStream(zipOutPath)
+    const archive = archiver('zip', {
+        zlib: { level: 9 },
+    })
+
+    await new Promise<void>((resolve, reject) => {
+        output.on('close', () => {
+            buildOutputs.zipPath = path.relative(config.root, zipOutPath)
+            buildOutputs.zipSizeKb = (archive.pointer() / 1024).toFixed(2)
+            resolve()
+        })
+        output.on('error', reject)
+        archive.pipe(output)
+        archive.directory(outDir, false)
+        archive.finalize()
+    })
+}
+
+function performPlaycademyLogging(
+    config: ResolvedConfig,
+    buildOutputs: PlaycademyOutputData,
+) {
+    if (!buildOutputs.manifestPath && !buildOutputs.zipSizeKb) {
+        return
+    }
+
+    config.logger.info('') // newline
+    config.logger.info(pc.magenta('[Playcademy]'))
+
+    if (buildOutputs.manifestPath && buildOutputs.manifestSizeKb) {
+        const dir = path.dirname(buildOutputs.manifestPath)
+        const file = path.basename(buildOutputs.manifestPath)
+        const uncoloredPathLength =
+            (dir === '.' ? 0 : dir.length + 1) + file.length
+        const coloredPath = `${pc.dim(dir === '.' ? '' : dir + '/')}${pc.green(file)}`
+
+        const formattedNumber = formatNumberWithCommas(
+            buildOutputs.manifestSizeKb!,
+        )
+        const sizeString = `${formattedNumber} kB`
+        const formattedSize = pc.bold(pc.yellow(sizeString))
+
+        const paddingNeeded = Math.max(
+            2,
+            LOG_LINE_TOTAL_WIDTH - uncoloredPathLength - sizeString.length,
+        )
+        const paddingSpaces = ' '.repeat(paddingNeeded)
+
+        config.logger.info(`${coloredPath}${paddingSpaces}${formattedSize}`)
+    }
+
+    if (buildOutputs.zipPath && buildOutputs.zipSizeKb) {
+        let dir = path.dirname(buildOutputs.zipPath)
+        const file = path.basename(buildOutputs.zipPath)
+        if (dir === '.') dir = ''
+        const uncoloredPathLength = (dir ? dir.length + 1 : 0) + file.length
+        const coloredPath = `${dir ? pc.dim(dir + '/') : ''}${pc.green(file)}`
+
+        const formattedNumber = formatNumberWithCommas(buildOutputs.zipSizeKb!)
+        const sizeString = `${formattedNumber} kB`
+        const formattedSize = pc.bold(pc.yellow(sizeString))
+
+        const paddingNeeded = Math.max(
+            2,
+            LOG_LINE_TOTAL_WIDTH - uncoloredPathLength - sizeString.length,
+        )
+        const paddingSpaces = ' '.repeat(paddingNeeded)
+
+        config.logger.info(`${coloredPath}${paddingSpaces}${formattedSize}`)
+    }
+
+    config.logger.info('') // newline
+}
+
+export function playcademy(options: PlaycademyPluginOptions = {}): Plugin {
+    let viteConfig: ResolvedConfig
+    let currentBuildOutputs: PlaycademyOutputData = {}
+
+    const finalOptions = {
+        bootMode: options.bootMode ?? 'iframe',
+        entryPoint: options.entryPoint ?? 'index.html',
+        styles: options.styles ?? [],
+        engine: options.engine ?? 'custom',
+        autoZip: process.env.CI === 'true' ? false : (options.autoZip ?? false),
+    }
+
+    return {
+        name: 'vite-plugin-playcademy',
+
+        config(userConfig) {
+            if (userConfig.base === undefined) {
+                return {
+                    base: './',
+                }
+            }
+            return {}
+        },
+
+        configResolved(resolvedConfig) {
+            viteConfig = resolvedConfig
+            currentBuildOutputs = {}
+        },
+
+        async writeBundle() {
+            const outDir =
+                viteConfig.build.outDir || path.join(process.cwd(), 'dist')
+
+            try {
+                await generatePlaycademyManifest(
+                    viteConfig,
+                    finalOptions,
+                    outDir,
+                    currentBuildOutputs,
+                )
+                if (finalOptions.autoZip) {
+                    await createOutputZipArchive(
+                        viteConfig,
+                        outDir,
+                        currentBuildOutputs,
+                    )
+                }
+            } catch (error) {
+                if (
+                    error instanceof Error &&
+                    error.message.includes('[Playcademy]')
+                ) {
+                    viteConfig.logger.error(error.message)
+                } else {
+                    viteConfig.logger.error(
+                        `[Playcademy] An unexpected error occurred during writeBundle: ${error instanceof Error ? error.message : String(error)}`,
+                    )
+                }
+            }
+        },
+
+        closeBundle() {
+            performPlaycademyLogging(viteConfig, currentBuildOutputs)
+        },
+    }
+}

package/sst-env.d.ts

@@ -0,0 +1,9 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+
+/// <reference path="../../sst-env.d.ts" />
+
+import "sst"
+export {}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compilerOptions": {
+        // Environment setup & latest features
+        "lib": ["ESNext"],
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleDetection": "force",
+        "jsx": "react-jsx",
+        "allowJs": true,
+
+        // Bundler mode
+        "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "verbatimModuleSyntax": true,
+        "noEmit": true,
+
+        // Best practices
+        "strict": true,
+        "skipLibCheck": true,
+        "noFallthroughCasesInSwitch": true,
+        "noUncheckedIndexedAccess": true,
+
+        // Some stricter flags (disabled by default)
+        "noUnusedLocals": false,
+        "noUnusedParameters": false,
+        "noPropertyAccessFromIndexSignature": false
+    }
+}

package/tsconfig.types.json

@@ -0,0 +1,13 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "noEmit": false,
+        "emitDeclarationOnly": true,
+        "declaration": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "skipLibCheck": true
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["node_modules", "**/*.test.ts"]
+}