@fzgame/cli 0.0.0-stage → 0.1.0

package/src/dev.ts

@@ -0,0 +1,311 @@
+import { createReadStream } from 'node:fs'
+import { readFile, stat } from 'node:fs/promises'
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import { extname, join, resolve, sep } from 'node:path'
+import { KIT_HINT, resolveKitFile } from './kit-path'
+import type { FzGameManifest } from './manifest'
+import { loadManifest } from './pack'
+
+const DEFAULT_HOST = '127.0.0.1'
+
+function applyCors(res: ServerResponse) {
+  res.setHeader('access-control-allow-origin', '*')
+  res.setHeader('access-control-allow-headers', '*')
+  res.setHeader('access-control-allow-methods', 'GET,POST,PUT,OPTIONS')
+}
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+}
+
+type Session = {
+  id: string
+  token: string
+  status: string
+  score: number | null
+  result: unknown
+  metadata: { snapshot?: unknown }
+  gameInstanceId: string
+}
+
+export type DevServerOptions = {
+  /** Bind address. Defaults to loopback: the mock runtime has no auth. */
+  host?: string
+}
+
+export async function startDevServer(
+  root: string,
+  port: number,
+  options: DevServerOptions = {},
+) {
+  const host = options.host || DEFAULT_HOST
+  const manifest = await loadManifest(root)
+  const sessions = new Map<string, Session>()
+
+  const server = createServer(async (req, res) => {
+    applyCors(res)
+    applySecurityHeaders(res)
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204)
+      res.end()
+      return
+    }
+    try {
+      const url = new URL(req.url || '/', `http://127.0.0.1:${port}`)
+      if (url.pathname === '/health') {
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ ok: true, name: manifest.name, port }))
+        return
+      }
+      if (
+        url.pathname.startsWith('/games/runtime') ||
+        url.pathname.startsWith('/pub/game-instances')
+      ) {
+        await handleRuntime(req, res, url, sessions, manifest)
+        return
+      }
+      if (url.pathname === '/@fzgame/kit.js') {
+        await serveKit(res)
+        return
+      }
+      if (url.pathname === '/' || url.pathname === '/index.html') {
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
+        res.end(launcherHtml(requestOrigin(req, host, port), manifest.name))
+        return
+      }
+      await serveStatic(root, url.pathname, res)
+    } catch (error) {
+      res.writeHead(500, { 'content-type': 'application/json' })
+      res.end(JSON.stringify({ message: (error as Error).message }))
+    }
+  })
+
+  await new Promise<void>((resolveReady, reject) => {
+    server.once('error', (error: NodeJS.ErrnoException) => {
+      reject(
+        error.code === 'EADDRINUSE'
+          ? new Error(`Port ${port} is already in use. Pass --port to pick another one.`)
+          : new Error(`Cannot serve on ${host}:${port} (${error.code || error.message}).`),
+      )
+    })
+    server.listen(port, host, () => resolveReady())
+  })
+  const address = server.address()
+  return {
+    server,
+    host,
+    port: typeof address === 'object' && address ? address.port : port,
+    manifest,
+  }
+}
+
+function applySecurityHeaders(res: ServerResponse) {
+  // Allow cross-origin requests
+  res.setHeader('Access-Control-Allow-Origin', '*')
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS, PUT, PATCH, DELETE')
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With')
+
+  // Any parent may embed the game, so the portal origin works without a proxy.
+  res.setHeader('Content-Security-Policy', 'frame-ancestors *')
+
+  // Remove restrictive framing header if set by default
+  res.removeHeader('X-Frame-Options')
+}
+
+async function serveKit(res: ServerResponse) {
+  try {
+    const body = await readFile(resolveKitFile())
+    res.writeHead(200, { 'content-type': 'application/javascript; charset=utf-8' })
+    res.end(body)
+  } catch (error) {
+    res.writeHead(404, { 'content-type': 'text/plain' })
+    res.end(`Cannot serve @fzgame/kit: ${(error as Error).message}\n${KIT_HINT}`)
+  }
+}
+
+async function serveStatic(root: string, pathname: string, res: ServerResponse) {
+  const rel = decodeURIComponent(pathname).replace(/^\//, '') || 'index.html'
+  const abs = resolve(root, rel)
+  const rootAbs = resolve(root)
+  if (abs !== rootAbs && !abs.startsWith(rootAbs + sep)) {
+    res.writeHead(403)
+    res.end('Forbidden')
+    return
+  }
+  try {
+    const info = await stat(abs)
+    const file = info.isDirectory() ? join(abs, 'index.html') : abs
+    res.writeHead(200, {
+      'content-type': MIME[extname(file)] || 'application/octet-stream',
+    })
+    createReadStream(file).pipe(res)
+  } catch {
+    res.writeHead(404)
+    res.end('Not found')
+  }
+}
+
+async function handleRuntime(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  sessions: Map<string, Session>,
+  manifest: FzGameManifest,
+) {
+  res.setHeader('content-type', 'application/json')
+  res.setHeader('access-control-allow-origin', '*')
+  res.setHeader('access-control-allow-headers', 'content-type')
+  res.setHeader('access-control-allow-methods', 'GET,POST,PUT,OPTIONS')
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204)
+    res.end()
+    return
+  }
+
+  if (
+    req.method === 'GET' &&
+    (url.pathname.startsWith('/pub/game-instances/') ||
+      url.pathname.startsWith('/games/runtime/instances/'))
+  ) {
+    res.end(
+      JSON.stringify({
+        id: url.pathname.split('/').pop(),
+        name: manifest.name,
+        status: 'PUBLISHED',
+        overrides: {},
+        game: { name: manifest.name, configSchema: manifest.configSchema ?? {} },
+      }),
+    )
+    return
+  }
+
+  if (req.method === 'POST' && url.pathname === '/games/runtime/sessions') {
+    const body = await readJson(req)
+    const existing = [...sessions.values()].find(
+      (s) => s.gameInstanceId === body.gameInstanceId && s.status !== 'FINISHED',
+    )
+    if (existing) {
+      res.end(JSON.stringify(existing))
+      return
+    }
+    const session: Session = {
+      id: `dev-${sessions.size + 1}`,
+      token: `dev-token-${sessions.size + 1}`,
+      status: 'CREATED',
+      score: null,
+      result: null,
+      metadata: { snapshot: {} },
+      gameInstanceId: String(body.gameInstanceId || 'dev-instance'),
+    }
+    sessions.set(session.token, session)
+    res.end(JSON.stringify(session))
+    return
+  }
+
+  const emitMatch = url.pathname.match(/^\/games\/runtime\/sessions\/([^/]+)\/emit$/)
+  if (req.method === 'POST' && emitMatch) {
+    const session = sessions.get(emitMatch[1]!)
+    if (!session) {
+      res.writeHead(404)
+      res.end(JSON.stringify({ message: 'Session not found' }))
+      return
+    }
+    const body = await readJson(req)
+    applyDevEmit(
+      session,
+      String(body.type || ''),
+      body.payload as Record<string, unknown> | undefined,
+    )
+    res.end(JSON.stringify(session))
+    return
+  }
+
+  const snapMatch = url.pathname.match(/^\/games\/runtime\/sessions\/([^/]+)\/snapshot$/)
+  if (req.method === 'PUT' && snapMatch) {
+    const session = sessions.get(snapMatch[1]!)
+    if (!session) {
+      res.writeHead(404)
+      res.end(JSON.stringify({ message: 'Session not found' }))
+      return
+    }
+    const body = await readJson(req)
+    session.metadata.snapshot = body.state ?? body
+    res.end(JSON.stringify(session))
+    return
+  }
+
+  const getMatch = url.pathname.match(/^\/games\/runtime\/sessions\/([^/]+)$/)
+  if (req.method === 'GET' && getMatch) {
+    const session = sessions.get(getMatch[1]!)
+    if (!session) {
+      res.writeHead(404)
+      res.end(JSON.stringify({ message: 'Session not found' }))
+      return
+    }
+    res.end(JSON.stringify(session))
+    return
+  }
+
+  res.writeHead(404)
+  res.end(JSON.stringify({ message: 'Not found' }))
+}
+
+function applyDevEmit(session: Session, type: string, payload?: Record<string, unknown>) {
+  if (type === 'ready') session.status = 'READY'
+  if (type === 'start') session.status = 'PLAYING'
+  if (type === 'pause') session.status = 'PAUSED'
+  if (type === 'finish') {
+    session.status = 'FINISHED'
+    if (typeof payload?.score === 'number') session.score = payload.score
+    if (payload?.result) session.result = payload.result
+  }
+  if (type === 'abort') session.status = 'ABORTED'
+  if (type === 'score' && typeof payload?.score === 'number') session.score = payload.score
+  if (type === 'snapshot') session.metadata.snapshot = payload?.state ?? payload
+}
+
+function readJson(req: IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((resolveJson, reject) => {
+    const chunks: Buffer[] = []
+    req.on('data', (c) => chunks.push(c as Buffer))
+    req.on('end', () => {
+      if (chunks.length === 0) return resolveJson({})
+      try {
+        resolveJson(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+      } catch (error) {
+        reject(error)
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+function requestOrigin(req: IncomingMessage, host: string, port: number) {
+  if (req.headers.host) return `http://${req.headers.host}`
+  const shown = host === '0.0.0.0' || host === '::' ? DEFAULT_HOST : host
+  return `http://${shown}:${port}`
+}
+
+function launcherHtml(origin: string, name: string) {
+  const kit = `kit=${encodeURIComponent('/@fzgame/kit.js')}`
+  const play = `/game/index.html?gameInstanceId=dev-instance&playerToken=dev-player&apiUrl=${encodeURIComponent(origin)}&${kit}`
+  const preview = `/game/index.html?preview=true&${kit}`
+  const editor = `/editor/index.html?gameInstanceId=dev-instance&apiUrl=${encodeURIComponent(origin)}&${kit}`
+  return `<!doctype html>
+<html>
+  <head><meta charset="utf-8"><title>${name} — fzgame dev</title></head>
+  <body style="font-family:system-ui;padding:24px">
+    <h1>${name}</h1>
+    <p>Local game developer mode.</p>
+    <p><a href="${play}">Open game</a></p>
+    <p><a href="${preview}">Open preview</a> (no play session; pass <code>gameSetting</code> JSON to try config)</p>
+    <p><a href="${editor}">Open editor</a></p>
+  </body>
+</html>`
+}

package/src/env.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Load KEY=VALUE pairs from `<dir>/.env` into process.env.
+ *
+ * Variables already set in the environment win, so a shell export or a CI
+ * secret is never overridden by a checked-in file. Missing file is not an error.
+ */
+export function loadEnvFile(dir: string = process.cwd()): boolean {
+  let raw: string
+  try {
+    raw = readFileSync(join(dir, '.env'), 'utf8')
+  } catch {
+    return false
+  }
+
+  for (const line of raw.split('\n')) {
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line)
+    if (!match) continue
+    const key = match[1]!
+    let value = match[2]!
+    const quoted =
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    if (quoted) value = value.slice(1, -1)
+    if (process.env[key] === undefined) process.env[key] = value
+  }
+  return true
+}

package/src/fetch.ts

@@ -0,0 +1,37 @@
+const DEFAULT_TIMEOUT_MS = 30_000
+
+export type RequestOptions = RequestInit & { timeoutMs?: number }
+
+/**
+ * fetch with a hard deadline and an error message that names the URL.
+ *
+ * undici's defaults bound connection and idle time, so a wedged API or proxy
+ * can otherwise hold a CLI or a runner forever with nothing printed.
+ */
+export async function request(url: string, options: RequestOptions = {}): Promise<Response> {
+  const { timeoutMs = DEFAULT_TIMEOUT_MS, ...init } = options
+  try {
+    return await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) })
+  } catch (error) {
+    throw new Error(`${url} ${describeFailure(error, timeoutMs)}`)
+  }
+}
+
+function describeFailure(error: unknown, timeoutMs: number) {
+  const name = (error as Error)?.name
+  if (name === 'TimeoutError' || name === 'AbortError') {
+    return `did not respond within ${Math.round(timeoutMs / 1000)}s`
+  }
+  // fetch reports every transport problem as "fetch failed"; the reason is on the cause.
+  const cause = (error as { cause?: unknown })?.cause
+  const detail =
+    cause instanceof AggregateError
+      ? cause.errors.map(codeOf).join(', ')
+      : codeOf(cause) ?? (error as Error)?.message ?? String(error)
+  return `failed: ${detail}`
+}
+
+function codeOf(error: unknown) {
+  if (error instanceof Error) return (error as NodeJS.ErrnoException).code ?? error.message
+  return String(error)
+}

package/src/fzgame.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fzgame.dev/schema/fzgame.json",
+  "title": "FZGame pack manifest",
+  "type": "object",
+  "required": ["info", "formSchema", "resultSchema", "snapshotSchema", "gameDataSchema"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "info": {
+      "type": "object",
+      "description": "Catalog identity for the game pack",
+      "required": ["name", "slug"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 2 },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "version": { "type": "integer", "minimum": 1, "default": 1 },
+        "image": {
+          "type": "string",
+          "description": "Cover image URL or pack-relative path"
+        },
+        "description": { "type": "string" },
+        "author": { "type": "string" },
+        "git_url": { "type": "string", "format": "uri" }
+      }
+    },
+    "formSchema": {
+      "type": "object",
+      "description": "JSON Schema for the create/edit form (instance config). Optional JSON Forms uiSchema lives in formUiSchema."
+    },
+    "formUiSchema": {
+      "type": "object",
+      "description": "Optional JSON Forms / RJSF uiSchema for formSchema"
+    },
+    "resultSchema": {
+      "type": "object",
+      "description": "JSON Schema for the value the handler/finish event stores on the play session result"
+    },
+    "snapshotSchema": {
+      "type": "object",
+      "description": "JSON Schema for mid-play session snapshot (kit.setState / metadata.snapshot)"
+    },
+    "gameDataSchema": {
+      "type": "object",
+      "description": "JSON Schema for persistent game data on the instance (levels, content, save payload)"
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "game": { "type": "string" },
+        "editor": { "type": "string" },
+        "handler": { "type": "string" }
+      }
+    },
+    "name": { "type": "string", "description": "Legacy alias for info.name" },
+    "slug": { "type": "string", "description": "Legacy alias for info.slug" },
+    "version": { "type": "integer", "description": "Legacy alias for info.version" },
+    "description": { "type": "string" },
+    "configSchema": {
+      "type": "object",
+      "description": "Legacy alias for formSchema"
+    }
+  }
+}

package/src/init.ts

@@ -0,0 +1,74 @@
+import { cp, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const EXAMPLE_DIR = join(here, '..', 'example', 'click-counter')
+
+export type InitOptions = { force?: boolean }
+
+export async function initGame(targetDir: string, options: InitOptions = {}) {
+  const dest = resolve(targetDir)
+  const template = await stat(EXAMPLE_DIR).then(
+    (info) => info.isDirectory(),
+    () => false,
+  )
+  if (!template) {
+    throw new Error(
+      `Game template missing at ${EXAMPLE_DIR}. Reinstall @fzgame/cli, the "example" folder must ship with it.`,
+    )
+  }
+
+  await mkdir(dest, { recursive: true })
+  const existing = (await readdir(dest)).filter((name) => name !== '.DS_Store' && name !== '.git')
+  if (existing.length > 0 && !options.force) {
+    throw new Error(
+      `${dest} is not empty (${existing.slice(0, 5).join(', ')}${existing.length > 5 ? ', ...' : ''}). Pass --force to write into it.`,
+    )
+  }
+
+  const hasGitignore = await stat(join(dest, '.gitignore')).then(
+    () => true,
+    () => false,
+  )
+  await cp(EXAMPLE_DIR, dest, {
+    recursive: true,
+    filter: (source) => keep(source) && !(hasGitignore && source.endsWith(`${sep}.gitignore`)),
+  })
+  await ensureGitignore(dest)
+
+  const files: string[] = []
+  await walk(dest, (file) => {
+    files.push(relative(dest, file).split(sep).join('/'))
+  })
+  files.sort()
+  return { dir: dest, files }
+}
+
+/** Skip build output and installed dependencies so the scaffold stays a source tree. */
+function keep(source: string) {
+  const name = source.split(sep).pop() ?? ''
+  return name !== 'dist' && name !== 'node_modules' && name !== '.DS_Store'
+}
+
+async function ensureGitignore(dest: string) {
+  const path = join(dest, '.gitignore')
+  let current = ''
+  try {
+    current = await readFile(path, 'utf8')
+  } catch {
+    /* no .gitignore yet */
+  }
+  if (/(^|\n)\s*dist\/?\s*(\n|$)/.test(current)) return
+  const next = current && !current.endsWith('\n') ? `${current}\n` : current
+  await writeFile(path, `${next}dist/\n`)
+}
+
+async function walk(dir: string, visit: (file: string) => void) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue
+    const abs = join(dir, entry.name)
+    if (entry.isDirectory()) await walk(abs, visit)
+    else visit(abs)
+  }
+}

package/src/kit-path.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+export const KIT_HINT = 'Run `pnpm --filter @fzgame/kit build` (monorepo) or `npm install` (installed CLI)'
+
+type ExportTarget = string | { import?: ExportTarget; require?: ExportTarget; default?: ExportTarget }
+
+type KitManifest = {
+  module?: string
+  main?: string
+  exports?: Record<string, ExportTarget>
+}
+
+/**
+ * The ESM file behind an export condition, which may be a bare path or a tree
+ * of conditions (`{ import: { types, default } }`).
+ */
+function resolveTarget(target: ExportTarget | undefined): string | undefined {
+  if (typeof target === 'string') return target
+  if (!target) return undefined
+  return resolveTarget(target.import) ?? resolveTarget(target.default)
+}
+
+/**
+ * Absolute path of the kit's browser (ESM) bundle, the file the game loads as
+ * `/@fzgame/kit.js` in dev and as `game/vendor/kit.js` in a packed zip.
+ *
+ * The kit's own manifest decides the filename, so changing its build layout
+ * cannot silently ship a zip with no vendor script.
+ */
+export function resolveKitFile(): string {
+  const manifestPath = require.resolve('@fzgame/kit/package.json')
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as KitManifest
+  const entry =
+    manifest.module ?? resolveTarget(manifest.exports?.['.']) ?? manifest.main ?? './dist/index.js'
+  return join(dirname(manifestPath), entry)
+}