neme-world 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NEME LIMITED
+
+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

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# neme-world
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Publish a web game to [neme.world](https://neme.world) from the command line.
+
+If your game runs in a browser tab from static files, it runs on neme.world: any engine, any framework,
+hand-written or AI-assisted. You keep your own site; neme.world is one more place people can find and play it.
+
+```sh
+npx neme-world init        # writes neme.json
+npx neme-world publish     # uploads your build and puts it live
+```
+
+## Before you publish
+
+1. Create an account at [neme.world](https://neme.world/signup) and make an API token in your dashboard.
+2. Put the token in your environment: `export NEME_TOKEN=neme_…`
+3. Build your game the way you normally do.
+
+## neme.json
+
+```json
+{
+  "slug": "my-game",
+  "title": "My Game",
+  "description": "One or two sentences players will see.",
+  "tags": ["arcade"],
+  "dir": "dist",
+  "cover": "cover.png"
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `slug` | The game's address: `neme.world/g/<slug>`. Lowercase letters, numbers, hyphens. |
+| `title` | Shown to players. |
+| `description` | Shown on the game's page and in link previews. |
+| `tags` | Up to 8, used for browsing. |
+| `dir` | Folder holding your built `index.html`, relative to `neme.json`. Default `.` |
+| `entry` | The HTML file to open, if it isn't `index.html`. |
+| `cover` | An image inside `dir`. A 16:9 PNG makes the best link previews. |
+| `aspect` | Shape of the game on its page: `16:9` (default), `4:3`, `1:1`, `3:4` or `9:16`. |
+| `license`, `sourceUrl`, `credit` | Optional, for open-source games and attribution. |
+
+## What publish does
+
+It uploads `dir` file by file as a new version, which goes live at once. Only files that changed since your last
+publish are sent, so updating a large game is quick. Hidden files (anything starting with a dot) and
+`node_modules` are never uploaded. Every version is kept, and you can make any earlier one live again from your
+dashboard.
+
+A single file can be up to 95 MB, and a game up to 1 GB. One publish per game runs at a time: starting a second
+replaces the first.
+
+## Options
+
+Installed (`npm i -D neme-world`), the command is simply `neme`.
+
+```
+neme publish [dir]      Publish the game described by dir/neme.json (default: current folder)
+neme init [dir]         Create a neme.json
+
+--token <token>         API token (default: $NEME_TOKEN)
+--api <url>             Platform address (default: $NEME_API or https://neme.world)
+```
+
+## In CI
+
+```yaml
+- run: npm run build
+- run: npx neme-world publish
+  env:
+    NEME_TOKEN: ${{ secrets.NEME_TOKEN }}
+```
+
+## Talking to the player
+
+To report load time, scores and your own events to your dashboard, see the SDK section of the
+[developer guide](https://neme.world/developers).
+
+MIT licensed.

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "neme-world",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Publish web games to neme.world from the command line",
+  "keywords": ["neme", "games", "web games", "html5 games", "publish", "deploy", "cli"],
+  "homepage": "https://neme.world/developers",
+  "license": "MIT",
+  "author": "NEME LIMITED",
+  "type": "module",
+  "bin": { "neme": "src/cli.js" },
+  "files": ["src/cli.js"],
+  "engines": { "node": ">=20" }
+}

package/src/cli.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * neme — publish web games to neme.world.
+ *
+ *   neme init [dir]       write a starter neme.json
+ *   neme publish [dir]    zip the build and publish it as a new version
+ *
+ * Plain JavaScript on purpose: it runs from a checkout or from npm with no build.
+ */
+import { createHash } from 'node:crypto'
+import { createReadStream, openAsBlob, realpathSync } from 'node:fs'
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+
+const DEFAULT_API = 'https://neme.world'
+const SKIP_DIRS = new Set(['node_modules'])
+
+/**
+ * @typedef {object} Manifest
+ * @property {string} slug
+ * @property {string} title
+ * @property {string} [description]
+ * @property {string[]} [tags]
+ * @property {string} [dir]     Folder holding the built index.html, relative to neme.json. Default ".".
+ * @property {string} [entry]   Default "index.html".
+ * @property {string} [cover]   Image inside `dir`.
+ * @property {string} [aspect]  "16:9" | "4:3" | "1:1" | "3:4" | "9:16"
+ * @property {string} [license]
+ * @property {string} [sourceUrl]
+ * @property {string} [credit]
+ */
+
+export class CliError extends Error {}
+
+/** @param {string} dir @returns {Promise<Manifest>} */
+export async function readManifest(dir) {
+  const file = path.join(dir, 'neme.json')
+  let text
+  try {
+    text = await readFile(file, 'utf8')
+  } catch {
+    throw new CliError(`No neme.json in ${dir}. Run "neme init" to create one.`)
+  }
+  let manifest
+  try {
+    manifest = JSON.parse(text)
+  } catch (err) {
+    throw new CliError(`${file} is not valid JSON: ${/** @type {Error} */ (err).message}`)
+  }
+  if (typeof manifest?.slug !== 'string' || typeof manifest?.title !== 'string') {
+    throw new CliError(`${file} needs at least "slug" and "title".`)
+  }
+  return manifest
+}
+
+/**
+ * @typedef {object} LocalFile
+ * @property {string} path    Path inside the build, with forward slashes.
+ * @property {string} file    Where it is on disk.
+ * @property {number} size
+ * @property {string} sha256
+ */
+
+/** @param {string} file @returns {Promise<string>} */
+function sha256Of(file) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash('sha256')
+    createReadStream(file).on('data', (chunk) => hash.update(chunk)).on('error', reject).on('end', () => resolve(hash.digest('hex')))
+  })
+}
+
+/**
+ * Lists every publishable file under `root`, with its size and hash. Dotfiles
+ * and node_modules are left out so secrets and dependencies don't get uploaded
+ * by accident. Files are hashed from disk, never held in memory whole.
+ * @param {string} root
+ * @returns {Promise<LocalFile[]>}
+ */
+export async function collectFiles(root) {
+  /** @type {LocalFile[]} */
+  const files = []
+  /** @param {string} rel */
+  async function walk(rel) {
+    for (const entry of await readdir(path.join(root, rel), { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue
+      const child = rel ? `${rel}/${entry.name}` : entry.name
+      const file = path.join(root, child)
+      if (entry.isDirectory()) await walk(child)
+      else if (entry.isFile() && child !== 'neme.json') files.push({ path: child, file, size: (await stat(file)).size, sha256: await sha256Of(file) })
+    }
+  }
+  await walk('')
+  return files.sort((a, b) => (a.path < b.path ? -1 : 1))
+}
+
+/**
+ * @param {string} api
+ * @param {string} token
+ * @param {string} method
+ * @param {string} route
+ * @param {{ json?: unknown, body?: Blob }} [o]
+ */
+async function call(api, token, method, route, o = {}) {
+  /** @type {Record<string, string>} */
+  const headers = { authorization: `Bearer ${token}` }
+  /** @type {BodyInit | undefined} */
+  let body
+  if (o.json !== undefined) {
+    headers['content-type'] = 'application/json'
+    body = JSON.stringify(o.json)
+  } else if (o.body) {
+    headers['content-type'] = 'application/octet-stream'
+    body = o.body
+  }
+  let res
+  try {
+    res = await fetch(`${api}/api/v1${route}`, { method, headers, body })
+  } catch (err) {
+    throw new CliError(`Could not reach ${api}: ${/** @type {Error} */ (err).cause ?? /** @type {Error} */ (err).message}`)
+  }
+  const data = /** @type {any} */ (res.status === 204 ? {} : await res.json().catch(() => ({})))
+  if (!res.ok) throw new CliError(`${data.error ?? `Request failed (${res.status})`}`)
+  return data
+}
+
+/** @param {number} n */
+const size = (n) => (n < 1048576 ? `${(n / 1024).toFixed(1)} KB` : `${(n / 1048576).toFixed(1)} MB`)
+
+/** How many files are sent at once. */
+const PARALLEL = 6
+
+/**
+ * Publishes file by file: declare everything, send only what the platform does
+ * not already have, then turn the upload into a version.
+ * @param {{ dir: string, api: string, token: string, log?: (line: string) => void }} o
+ * @returns {Promise<{ version: number, url: string, warnings: string[], uploaded: number }>}
+ */
+export async function publish({ dir, api, token, log = console.log }) {
+  const manifest = await readManifest(dir)
+  const buildDir = path.resolve(dir, manifest.dir ?? '.')
+  const entry = manifest.entry ?? 'index.html'
+
+  const info = await stat(buildDir).catch(() => null)
+  if (!info?.isDirectory()) throw new CliError(`Build folder ${buildDir} does not exist. Did you run your build?`)
+  const files = await collectFiles(buildDir)
+  if (!files.some((f) => f.path === entry)) throw new CliError(`${buildDir} has no ${entry}. Set "dir" in neme.json to your build output folder.`)
+  if (manifest.cover && !files.some((f) => f.path === manifest.cover)) throw new CliError(`Cover "${manifest.cover}" was not found in ${buildDir}.`)
+
+  const total = files.reduce((n, f) => n + f.size, 0)
+  log(`${manifest.title}: ${files.length} file${files.length === 1 ? '' : 's'}, ${size(total)}`)
+
+  const { slug, dir: _dir, entry: _entry, ...details } = manifest
+  await call(api, token, 'PUT', `/games/${slug}`, { json: details })
+  const begun = await call(api, token, 'POST', `/games/${slug}/uploads`, {
+    json: { entry, files: files.map(({ path, size, sha256 }) => ({ path, size, sha256 })) },
+  })
+
+  /** @type {{ sha256: string, size: number }[]} */
+  const missing = begun.missing
+  const byHash = new Map(files.map((f) => [f.sha256, f]))
+  const sending = missing.reduce((n, m) => n + m.size, 0)
+  if (missing.length) log(`  uploading ${missing.length} file${missing.length === 1 ? '' : 's'} (${size(sending)}); ${files.length - missing.length} already there`)
+  else log('  nothing new to upload')
+
+  const queue = [...missing]
+  const send = async () => {
+    for (let next = queue.pop(); next; next = queue.pop()) {
+      const local = /** @type {LocalFile} */ (byHash.get(next.sha256))
+      const route = `/games/${slug}/uploads/${begun.upload}/blobs/${next.sha256}`
+      try {
+        await call(api, token, 'PUT', route, { body: await openAsBlob(local.file) })
+      } catch (err) {
+        // One retry covers a dropped connection; anything else is reported with the file's name.
+        try {
+          await call(api, token, 'PUT', route, { body: await openAsBlob(local.file) })
+        } catch (again) {
+          throw new CliError(`Could not upload ${local.path}: ${/** @type {Error} */ (again).message}`)
+        }
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: PARALLEL }, send))
+
+  const out = await call(api, token, 'POST', `/games/${slug}/uploads/${begun.upload}/complete`, { json: {} })
+  for (const w of [...(begun.warnings ?? []), ...(out.warnings ?? [])]) log(`  warning: ${w}`)
+  const saved = out.transferBytes < out.bytes ? ` (${size(out.bytes)} before compression)` : ''
+  log(`  v${out.version} is live — ${size(out.transferBytes)} to download${saved}`)
+  log(`  ${out.game.url}`)
+  return { version: out.version, url: out.game.url, warnings: out.warnings ?? [], uploaded: missing.length }
+}
+
+/** @param {string} dir */
+async function init(dir) {
+  const file = path.join(dir, 'neme.json')
+  if (await stat(file).catch(() => null)) throw new CliError(`${file} already exists.`)
+  const name = path.basename(path.resolve(dir))
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'my-game'
+  const hasDist = await stat(path.join(dir, 'dist')).catch(() => null)
+  const manifest = {
+    slug,
+    title: name.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
+    description: '',
+    tags: [],
+    dir: hasDist ? 'dist' : '.',
+  }
+  await writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`)
+  console.log(`Wrote ${file}. Edit it, then run "neme publish".`)
+}
+
+const HELP = `neme — publish web games to neme.world
+
+Usage
+  neme init [dir]         Create a neme.json in dir (default: current folder)
+  neme publish [dir]      Publish the game described by dir/neme.json
+
+Options
+  --api <url>             Platform address (default: $NEME_API or ${DEFAULT_API})
+  --token <token>         API token (default: $NEME_TOKEN). Create one in your dashboard.
+  -h, --help              Show this help
+  -v, --version           Show the version
+`
+
+/** @param {string[]} argv */
+export async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      api: { type: 'string' }, token: { type: 'string' },
+      help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+    },
+  })
+  const [command, dir = '.'] = positionals
+  if (values.version) {
+    const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'))
+    return void console.log(pkg.version)
+  }
+  if (values.help || !command) return void console.log(HELP)
+
+  if (command === 'init') return init(dir)
+  if (command === 'publish') {
+    const token = values.token ?? process.env.NEME_TOKEN
+    if (!token) throw new CliError('No API token. Set NEME_TOKEN or pass --token. Create one at https://neme.world/dashboard')
+    const api = (values.api ?? process.env.NEME_API ?? DEFAULT_API).replace(/\/+$/, '')
+    await publish({ dir, api, token })
+    return
+  }
+  throw new CliError(`Unknown command "${command}". Try "neme --help".`)
+}
+
+// Run only when executed directly (including through an npm bin symlink), not when imported.
+if (process.argv[1] && import.meta.filename === realpathSync(process.argv[1])) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error(err instanceof CliError ? `neme: ${err.message}` : err)
+    process.exit(1)
+  })
+}