@fzgame/cli 0.0.0-stage → 0.1.0

package/src/manifest.ts

@@ -0,0 +1,182 @@
+export type FzGameEntry = {
+  game: string
+  editor: string
+  handler: string
+}
+
+export type FzGameInfo = {
+  name: string
+  slug: string
+  version: number
+  image?: string
+  description?: string
+  author?: string
+  gitUrl?: string
+}
+
+export type FzGameManifest = {
+  info: FzGameInfo
+  entry: FzGameEntry
+  formSchema?: Record<string, unknown>
+  formUiSchema?: Record<string, unknown>
+  resultSchema?: Record<string, unknown>
+  snapshotSchema?: Record<string, unknown>
+  gameDataSchema?: Record<string, unknown>
+  name: string
+  slug: string
+  version: number
+  description?: string
+  configSchema?: Record<string, unknown>
+}
+
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export const DEFAULT_ENTRY: FzGameEntry = {
+  game: 'game/index.html',
+  editor: 'editor/index.html',
+  handler: 'handler/index.js',
+}
+
+export function readFormSchema(
+  schema: Record<string, unknown> | null | undefined,
+): Record<string, unknown> {
+  if (!schema) return {}
+  const form = schema.formSchema
+  if (form && typeof form === 'object' && !Array.isArray(form)) {
+    return form as Record<string, unknown>
+  }
+  return schema
+}
+
+export function toStoredConfigSchema(
+  manifest: Pick<
+    FzGameManifest,
+    | 'formSchema'
+    | 'formUiSchema'
+    | 'resultSchema'
+    | 'snapshotSchema'
+    | 'gameDataSchema'
+    | 'info'
+  >,
+): Record<string, unknown> {
+  return {
+    formSchema: manifest.formSchema ?? { type: 'object', properties: {} },
+    ...(manifest.formUiSchema ? { formUiSchema: manifest.formUiSchema } : {}),
+    ...(manifest.resultSchema ? { resultSchema: manifest.resultSchema } : {}),
+    ...(manifest.snapshotSchema ? { snapshotSchema: manifest.snapshotSchema } : {}),
+    ...(manifest.gameDataSchema ? { gameDataSchema: manifest.gameDataSchema } : {}),
+    ...(manifest.info.author ? { author: manifest.info.author } : {}),
+    ...(manifest.info.gitUrl ? { git_url: manifest.info.gitUrl } : {}),
+    ...(manifest.info.image ? { image: manifest.info.image } : {}),
+  }
+}
+
+export function parseFzGameManifest(input: unknown): FzGameManifest {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('fzgame.json must be an object')
+  }
+  const raw = input as Record<string, unknown>
+  const info = parseInfo(raw)
+  const formSchema =
+    readObject(raw.formSchema, 'formSchema') ??
+    readObject(raw.configSchema, 'configSchema')
+  const manifest: FzGameManifest = {
+    info,
+    entry: parseEntry(raw.entry),
+    formSchema,
+    formUiSchema: readObject(raw.formUiSchema, 'formUiSchema'),
+    resultSchema: readObject(raw.resultSchema, 'resultSchema'),
+    snapshotSchema: readObject(raw.snapshotSchema, 'snapshotSchema'),
+    gameDataSchema: readObject(raw.gameDataSchema, 'gameDataSchema'),
+    name: info.name,
+    slug: info.slug,
+    version: info.version,
+    description: info.description,
+  }
+  manifest.configSchema = toStoredConfigSchema(manifest)
+  return manifest
+}
+
+function parseInfo(raw: Record<string, unknown>): FzGameInfo {
+  const nested =
+    raw.info && typeof raw.info === 'object' && !Array.isArray(raw.info)
+      ? (raw.info as Record<string, unknown>)
+      : {}
+  const name = pickString(nested.name, raw.name)
+  const slug = pickString(nested.slug, raw.slug)
+  if (!name || name.trim().length < 2) {
+    throw new Error('fzgame.json must include a name (min 2 characters)')
+  }
+  if (!slug || !SLUG_RE.test(slug)) {
+    throw new Error(
+      'fzgame.json slug must be kebab-case (lowercase letters, digits, hyphens)',
+    )
+  }
+  const versionRaw = nested.version ?? raw.version
+  const version =
+    versionRaw === undefined || versionRaw === null ? 1 : versionRaw
+  if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
+    throw new Error('fzgame.json version must be a positive integer')
+  }
+  const gitUrl = optionalString(nested.git_url ?? nested.gitUrl)
+  if (gitUrl && !/^https?:\/\//i.test(gitUrl)) {
+    throw new Error('fzgame.json info.git_url must be an http(s) URL')
+  }
+  const image = optionalString(nested.image)
+  const description = optionalString(nested.description ?? raw.description)
+  const author = optionalString(nested.author)
+  return {
+    name: name.trim(),
+    slug,
+    version,
+    ...(image ? { image } : {}),
+    ...(description ? { description } : {}),
+    ...(author ? { author } : {}),
+    ...(gitUrl ? { gitUrl } : {}),
+  }
+}
+
+function parseEntry(input: unknown): FzGameEntry {
+  if (input === undefined || input === null) return { ...DEFAULT_ENTRY }
+  if (typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('fzgame.json entry must be an object')
+  }
+  const raw = input as Record<string, unknown>
+  return {
+    game: readPath(raw.game, DEFAULT_ENTRY.game),
+    editor: readPath(raw.editor, DEFAULT_ENTRY.editor),
+    handler: readPath(raw.handler, DEFAULT_ENTRY.handler),
+  }
+}
+
+function readPath(value: unknown, fallback: string): string {
+  if (value === undefined || value === null) return fallback
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error('fzgame.json entry paths must be relative')
+  }
+  const path = value.replace(/\\/g, '/').replace(/^\.\//, '')
+  if (path.startsWith('/') || path.includes('..')) {
+    throw new Error('fzgame.json entry paths must be relative without ..')
+  }
+  return path
+}
+
+function readObject(value: unknown, field: string): Record<string, unknown> | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`fzgame.json ${field} must be a JSON Schema object`)
+  }
+  return value as Record<string, unknown>
+}
+
+function pickString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value
+  }
+  return undefined
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === '') return undefined
+  return String(value)
+}

package/src/pack.ts

@@ -0,0 +1,108 @@
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
+import { dirname, join, relative } from 'node:path'
+import { KIT_HINT, resolveKitFile } from './kit-path'
+import { parseFzGameManifest, type FzGameManifest } from './manifest'
+import { buildZip } from './zip'
+
+export type PackOptions = {
+  /** Kit bundle to vendor. Defaults to the installed `@fzgame/kit`; `null` skips vendoring. */
+  kitFile?: string | null
+}
+
+export async function loadManifest(root: string): Promise<FzGameManifest> {
+  const manifestPath = join(root, 'fzgame.json')
+  let text: string
+  try {
+    text = await readFile(manifestPath, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(`No fzgame.json in ${root}. Run fzgame dev from a game root.`)
+    }
+    throw error
+  }
+  try {
+    return parseFzGameManifest(JSON.parse(text))
+  } catch (error) {
+    throw new Error(`Invalid fzgame.json in ${root}: ${(error as Error).message}`)
+  }
+}
+
+export async function collectGameFiles(
+  root: string,
+  options: PackOptions = {},
+): Promise<Record<string, Buffer>> {
+  const manifest = await loadManifest(root)
+  const files: Record<string, Buffer> = {
+    'fzgame.json': await readFile(join(root, 'fzgame.json')),
+  }
+
+  for (const dir of ['game', 'editor', 'handler']) {
+    const abs = join(root, dir)
+    if (!(await exists(abs))) {
+      throw new Error(`Missing required directory: ${dir}/`)
+    }
+    await walk(abs, async (file) => {
+      const rel = relative(root, file).replace(/\\/g, '/')
+      files[rel] = await readFile(file)
+    })
+  }
+
+  for (const path of [manifest.entry.game, manifest.entry.editor, manifest.entry.handler]) {
+    if (!files[path]) throw new Error(`Missing required entrypoint: ${path}`)
+  }
+
+  await vendorKit(files, options)
+  return files
+}
+
+export async function buildGame(root: string, outFile?: string, options: PackOptions = {}) {
+  const manifest = await loadManifest(root)
+  const files = await collectGameFiles(root, options)
+  const zip = buildZip(files)
+  const dest = outFile || join(root, 'dist', `${manifest.slug}-v${manifest.version}.zip`)
+  await mkdir(dirname(dest), { recursive: true })
+  await writeFile(dest, zip)
+  return { dest, manifest, files: Object.keys(files) }
+}
+
+async function vendorKit(files: Record<string, Buffer>, options: PackOptions) {
+  if (files['game/vendor/kit.js']) return
+  if (options.kitFile === null) return
+
+  let kitFile: string
+  if (options.kitFile) {
+    kitFile = options.kitFile
+  } else {
+    try {
+      kitFile = resolveKitFile()
+    } catch (error) {
+      throw new Error(
+        `Cannot vendor the game runtime: @fzgame/kit is not installed (${(error as Error).message}). ${KIT_HINT}`,
+      )
+    }
+  }
+
+  if (!(await exists(kitFile))) {
+    throw new Error(`Cannot vendor the game runtime: ${kitFile} does not exist. ${KIT_HINT}`)
+  }
+  files['game/vendor/kit.js'] = await readFile(kitFile)
+}
+
+async function walk(dir: string, visit: (file: string) => Promise<void>) {
+  const entries = await readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.name === '.DS_Store') continue
+    const abs = join(dir, entry.name)
+    if (entry.isDirectory()) await walk(abs, visit)
+    else await visit(abs)
+  }
+}
+
+async function exists(path: string) {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/program.ts

@@ -0,0 +1,110 @@
+import { Command } from 'commander'
+import { startDevServer } from './dev'
+import { initGame } from './init'
+import { buildGame } from './pack'
+import { publishGame } from './publish'
+import { startRunner } from './runner'
+import { VERSION } from './version'
+
+const DEFAULT_API = 'http://localhost:3020'
+
+export function buildProgram() {
+  const program = new Command()
+
+  program
+    .name('fzgame')
+    .description('Build, publish, and develop FZ games')
+    .version(VERSION)
+    .addHelpText(
+      'after',
+      `
+Environment (a .env file in the working directory is read too, shell values win):
+  FZGAME_API        GameHub API for publish and runner (default ${DEFAULT_API})
+  FZGAME_SERVER     Alias for FZGAME_API
+  FZGAME_TOKEN      Session token for publish
+  FZGAME_SPACE_ID   Space id, publishes a private game
+  FZGAME_RUNNER_KEY Runner key from the BO receipt
+  FZGAME_RUNNER_PASS Runner pass from the BO receipt`,
+    )
+
+  program
+    .command('init [dir]')
+    .description('Scaffold a game from the bundled click-counter example')
+    .option('-f, --force', 'write into a directory that already has files')
+    .action(async (dir: string | undefined, opts: { force?: boolean }) => {
+      const result = await initGame(dir || '.', { force: opts.force })
+      console.log(`Scaffolded ${result.files.length} files in ${result.dir}`)
+      for (const file of result.files) console.log(`  ${file}`)
+      console.log('Next: fzgame dev')
+    })
+
+  program
+    .command('build')
+    .description('Validate fzgame.json and pack game/editor/handler into a zip')
+    .option('--cwd <dir>', 'game root', process.cwd())
+    .option('-o, --out <file>', 'output zip path')
+    .action(async (opts: { cwd: string; out?: string }) => {
+      const result = await buildGame(opts.cwd, opts.out)
+      console.log(
+        `Built ${result.manifest.slug}@${result.manifest.version} -> ${result.dest}`,
+      )
+    })
+
+  program
+    .command('publish')
+    .description('Build and upload the zip to /games/publishing')
+    .option('--cwd <dir>', 'game root', process.cwd())
+    .option('--api <url>', 'GameHub API', process.env.FZGAME_API || DEFAULT_API)
+    .option('--token <token>', 'session token', process.env.FZGAME_TOKEN)
+    .option('--space <id>', 'space id for private games', process.env.FZGAME_SPACE_ID)
+    .action(async (opts: { cwd: string; api: string; token?: string; space?: string }) => {
+      if (!opts.token) {
+        throw new Error('Pass --token or set FZGAME_TOKEN')
+      }
+      const game = await publishGame({
+        cwd: opts.cwd,
+        api: opts.api,
+        token: opts.token,
+        spaceId: opts.space,
+      })
+      console.log(`Published ${game.slug}@${game.version} (${game.id})`)
+      if (game.entryPointUrl) console.log(game.entryPointUrl)
+    })
+
+  program
+    .command('dev')
+    .description('Serve the game locally with a mock runtime kit API')
+    .option('--cwd <dir>', 'game root', process.cwd())
+    .option('-p, --port <port>', 'port', '3400')
+    .option('--host <host>', 'bind address (use 0.0.0.0 to expose on the LAN)', '127.0.0.1')
+    .action(async (opts: { cwd: string; port: string; host: string }) => {
+      const { port, manifest } = await startDevServer(opts.cwd, Number(opts.port), {
+        host: opts.host,
+      })
+      const shown = opts.host === '0.0.0.0' || opts.host === '::' ? '127.0.0.1' : opts.host
+      console.log(`${manifest.name} dev server http://${shown}:${port}`)
+      if (shown !== opts.host) console.log(`Bound to ${opts.host}, reachable from the LAN`)
+    })
+
+  const runner = program.command('runner').description('Self-hosted GameHub CI runner')
+
+  runner
+    .command('start')
+    .description('Connect to the API and run fetch → build → test → publish jobs')
+    .option(
+      '--server <url>',
+      'GameHub API',
+      process.env.FZGAME_API || process.env.FZGAME_SERVER || DEFAULT_API,
+    )
+    .option('--key <key>', 'runner key from the BO receipt', process.env.FZGAME_RUNNER_KEY)
+    .option('--pass <pass>', 'runner pass from the BO receipt', process.env.FZGAME_RUNNER_PASS)
+    .action(async (opts: { server: string; key?: string; pass?: string }) => {
+      await startRunner({
+        server: opts.server,
+        key: opts.key || '',
+        pass: opts.pass || '',
+      })
+    })
+
+  return program
+}

package/src/publish.ts

@@ -0,0 +1,59 @@
+import { readFile } from 'node:fs/promises'
+import { buildGame } from './pack'
+import { request } from './fetch'
+
+export type PublishOptions = {
+  cwd: string
+  api: string
+  token: string
+  spaceId?: string
+}
+
+const UPLOAD_TIMEOUT_MS = 120_000
+
+export async function publishGame(options: PublishOptions) {
+  const { dest, manifest } = await buildGame(options.cwd)
+  const zip = await readFile(dest)
+  const api = options.api.replace(/\/$/, '')
+  const path = options.spaceId ? '/portal/games/publishing' : '/games/publishing'
+  const url = `${api}${path}`
+  const form = new FormData()
+  form.append(
+    'file',
+    new Blob([new Uint8Array(zip)], { type: 'application/zip' }),
+    `${manifest.slug}.zip`,
+  )
+  if (options.spaceId) form.set('spaceId', options.spaceId)
+
+  const res = await request(url, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${options.token}`,
+      cookie: `better-auth.session_token=${options.token}`,
+      ...(options.spaceId ? { 'x-space-id': options.spaceId } : {}),
+    },
+    body: form,
+    timeoutMs: UPLOAD_TIMEOUT_MS,
+  })
+
+  const text = await res.text()
+  if (!res.ok) {
+    throw new Error(`Publish failed (${res.status}): ${text.slice(0, 500)}`)
+  }
+  const contentType = res.headers.get('content-type') || ''
+  if (!contentType.includes('json')) {
+    throw new Error(
+      `Publish returned ${res.status} ${contentType || 'without a content type'} instead of JSON: ${text.slice(0, 200)}`,
+    )
+  }
+  try {
+    return JSON.parse(text) as {
+      id: string
+      slug: string
+      version: number
+      entryPointUrl?: string
+    }
+  } catch {
+    throw new Error(`Publish returned invalid JSON: ${text.slice(0, 200)}`)
+  }
+}

package/src/runner-pipeline.ts

@@ -0,0 +1,48 @@
+export type PipelineStageName = 'fetch' | 'build' | 'test' | 'publish'
+
+export function planPipeline(
+  scripts: { build?: string; test?: string } | null,
+): PipelineStageName[] {
+  const stages: PipelineStageName[] = ['fetch', 'build']
+  if (scripts?.test) stages.push('test')
+  stages.push('publish')
+  return stages
+}
+
+export function installCommand(
+  files: string[],
+): [string, string[]] | null {
+  if (!files.includes('package.json')) return null
+  if (files.includes('pnpm-lock.yaml')) {
+    return ['pnpm', ['install', '--frozen-lockfile']]
+  }
+  if (files.includes('yarn.lock')) {
+    return ['yarn', ['install', '--frozen-lockfile']]
+  }
+  if (files.includes('package-lock.json')) return ['npm', ['ci']]
+  return ['npm', ['install']]
+}
+
+export function buildCommand(
+  files: string[],
+  scripts: { build?: string } | null,
+): [string, string[]] | null {
+  if (!scripts?.build) return null
+  const [manager] = installCommand(files.includes('package.json') ? files : ['package.json', ...files]) ?? [
+    'npm',
+    [],
+  ]
+  return [manager, ['run', 'build']]
+}
+
+export function testCommand(
+  files: string[],
+  scripts: { test?: string } | null,
+): [string, string[]] | null {
+  if (!scripts?.test) return null
+  const [manager] = installCommand(files.includes('package.json') ? files : ['package.json', ...files]) ?? [
+    'npm',
+    [],
+  ]
+  return [manager, ['run', 'test']]
+}

package/src/runner-receipt.ts

@@ -0,0 +1,35 @@
+export type RunnerReceiptInput = {
+  server: string
+  key: string
+  pass?: string
+}
+
+function dockerServer(server: string) {
+  try {
+    const url = new URL(server)
+    if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
+      url.hostname = 'host.docker.internal'
+      return url.toString().replace(/\/$/, '')
+    }
+  } catch {
+    /* keep */
+  }
+  return server
+}
+
+export function formatRunnerReceipt(input: RunnerReceiptInput) {
+  const server = input.server.replace(/\/$/, '')
+  const pass = input.pass || '<pass>'
+  const flags = `--server ${server} --key ${input.key} --pass ${pass}`
+  const dockerApi = dockerServer(server)
+  const dockerFlags = `--server ${dockerApi} --key ${input.key} --pass ${pass}`
+  return {
+    server,
+    key: input.key,
+    pass,
+    cli: `fzgame runner start ${flags}`,
+    local: `node packages/fzgame-cli/dist/cli.cjs runner start ${flags}`,
+    docker: `docker compose run --rm runner ${dockerFlags}`,
+    compose: `FZGAME_API=${dockerApi} FZGAME_RUNNER_KEY=${input.key} FZGAME_RUNNER_PASS=${pass} docker compose up -d runner`,
+  }
+}