@gamedevland/vite 0.0.4 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Add the `gamedevland poki pack` and `gamedevland poki upload` CLI commands.
+- Configure game ID, build directory, npm checks/build task and archive path in `poki.json`.
+- Package deterministic ZIPs without platform-specific shell utilities or game-specific asset assumptions.
+- Use the official pinned Poki CLI, per-game private credentials or `POKI_UPLOAD_TOKEN`, and verified upload receipts.
+- Keep authentication out of check/build subprocesses and reject source maps, private files, symlinks and leaked upload tokens in build output.
+- Preserve existing Vite configuration exports and browser SDK injection.

package/README.md

@@ -25,6 +25,66 @@ export default ({ mode }: { readonly mode: string }) =>
 The package provides the shared Gamedev Land platform configuration, development proxy setup,
 environment resolution, and platform SDK injection used by engine-based game projects.
 
+## Shared Poki tools (Node.js 20.19+)
+
+The package also installs the `gamedevland` executable. No game-local upload or ZIP script is needed.
+The CLI uses the project's `poki.json`; it never assumes a particular game name, asset format, font or directory layout.
+
+```json
+{
+  "game_id": "your-poki-game-uuid",
+  "build_dir": "dist/poki",
+  "tooling": {
+    "checks": ["typecheck", "lint", "test:poki"],
+    "buildScript": "compile:poki",
+    "archive": "dist/my-game-poki.zip"
+  }
+}
+```
+
+```json
+{
+  "scripts": {
+    "compile:poki": "VITE_PLATFORM=poki vite build --outDir ../dist/poki",
+    "build:poki": "npm run compile:poki && gamedevland poki pack",
+    "poki:upload": "gamedevland poki upload"
+  }
+}
+```
+
+```bash
+npm run build:poki
+npm run poki:upload -- --name "Production v1" --notes "Release notes"
+npx gamedevland poki pack --root /path/to/another-game
+```
+
+`pack` validates an existing build and creates a ZIP with `index.html` at the root. It checks the
+official SDK script and local HTML dependencies. Hidden/private files, source maps, TypeScript sources,
+symlinks and nested archives are rejected. PNG, WAV, SVG, WebP and other game asset formats are allowed.
+Game-specific asset/license budgets remain project tests. ZIP metadata uses a fixed timestamp for reproducibility.
+
+`upload` validates all configured npm scripts, resolves authentication, runs checks followed by a fresh build,
+packages it, and invokes `@poki/cli`. It preserves optimized images and does not request public release/review.
+Only a confirmed success response for the configured game and matching Preview/Inspector version counts as success;
+the official CLI's zero exit code alone is insufficient. Temporary upload archives are kept outside the project and cleaned.
+A receipt `poki-upload.json` next to the local ZIP records game/version IDs, URLs, source revision/dirty state and local ZIP SHA-256.
+
+Defaults: `checks` is `["typecheck", "lint"]`, `buildScript` is `build:poki`, and `archive` is
+`artifacts/poki/<package-name>.zip`. Add the output directory to `.gitignore`. For projects without these checks,
+explicitly configure the appropriate list (including `[]` when intentional). Paths must stay inside the project,
+and the ZIP must be outside `build_dir` to prevent recursive uploads. `--root` defaults to the current directory.
+Version names default to the git revision plus UTC timestamp; git is optional.
+
+### Authentication
+
+CI can set `POKI_UPLOAD_TOKEN`. For local repeated uploads, store the game's token (plain text, no shell command)
+in `$XDG_CONFIG_HOME/poki/game-upload-tokens/<game_id>` or `~/.config/poki/game-upload-tokens/<game_id>`.
+On POSIX systems, the token file must have permissions `0600`.
+Never put credentials in `poki.json`, package metadata or the build. Tokens are passed only to the upload process,
+removed from check/build environments, masked in CLI output and checked against all files being packaged.
+
+See the [official Poki CLI](https://github.com/poki/poki-cli). The browser runtime SDK remains separate from these Node.js tools.
+
 ## License
 
 This package is public but not open source. See [LICENSE](./LICENSE).

package/dist/cli/GamedevlandCli.d.ts

@@ -0,0 +1,4 @@
+/** Public command-line interface; no dependency on a particular game layout. */
+export declare class GamedevlandCli {
+    static run(argv: string[], cwd: string): Promise<void>;
+}

package/dist/cli/GamedevlandCli.js

@@ -0,0 +1,29 @@
+import { parseArgs } from 'node:util';
+import { PokiArchive } from '../poki/PokiArchive.js';
+import { PokiProject } from '../poki/PokiProject.js';
+import { PokiUpload } from '../poki/PokiUpload.js';
+/** Public command-line interface; no dependency on a particular game layout. */
+export class GamedevlandCli {
+    static async run(argv, cwd) {
+        const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
+                help: { type: 'boolean', short: 'h' }, root: { type: 'string' },
+                name: { type: 'string' }, notes: { type: 'string' },
+            } });
+        if (values.help || positionals.length === 0) {
+            process.stdout.write('Usage: gamedevland poki <pack|upload> [--root <project>] [--name <version>] [--notes <text>]\npack validates/packages an existing build; upload runs configured checks and a fresh build before uploading.\n');
+            return;
+        }
+        if (positionals.length !== 2 || positionals[0] !== 'poki' || !['pack', 'upload'].includes(positionals[1] ?? '')) {
+            throw new Error('[gamedevland] Expected poki pack or poki upload; use --help');
+        }
+        const project = PokiProject.load(values.root ?? cwd);
+        if (positionals[1] === 'pack') {
+            const archive = await PokiArchive.pack(project, process.env.POKI_UPLOAD_TOKEN);
+            process.stdout.write(`[poki] ${project.archive}: ${archive.files} files, ${(archive.bytes / 1048576).toFixed(2)} MiB\n`);
+        }
+        else {
+            await PokiUpload.run(project, { ...(values.name === undefined ? {} : { name: values.name }),
+                ...(values.notes === undefined ? {} : { notes: values.notes }) });
+        }
+    }
+}

package/dist/cli/entry.d.ts

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

package/dist/cli/entry.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { GamedevlandCli } from './GamedevlandCli.js';
+class GamedevlandCliEntry {
+    static async main() {
+        try {
+            await GamedevlandCli.run(process.argv.slice(2), process.cwd());
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : '[gamedevland] Command failed'}\n`);
+            process.exitCode = 1;
+        }
+    }
+}
+void GamedevlandCliEntry.main();

package/dist/poki/PokiArchive.d.ts

@@ -0,0 +1,10 @@
+import type { PokiProject } from './PokiProject.js';
+/** Validates and packages a platform build, preserving arbitrary game asset formats. */
+export declare class PokiArchive {
+    static pack(project: PokiProject, secret?: string): Promise<{
+        readonly sha256: string;
+        readonly bytes: number;
+        readonly files: number;
+    }>;
+    private static collect;
+}

package/dist/poki/PokiArchive.js

@@ -0,0 +1,64 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { zipSync } from 'fflate';
+import { BuildPlatformSdkCatalog } from '../BuildPlatformSdkCatalog.js';
+/** Validates and packages a platform build, preserving arbitrary game asset formats. */
+export class PokiArchive {
+    static async pack(project, secret) {
+        if (await realpath(project.buildDir) !== project.buildDir)
+            throw new Error('[poki] Symlinked build directory is not supported');
+        const files = await PokiArchive.collect(project.buildDir);
+        if (!files.includes('index.html'))
+            throw new Error('[poki] index.html must be at the archive root');
+        const zip = {};
+        for (const file of files) {
+            const content = await readFile(path.join(project.buildDir, file));
+            if (secret && content.includes(Buffer.from(secret)))
+                throw new Error('[poki] Upload token found in build output');
+            Object.defineProperty(zip, file, { value: [content, { mtime: new Date(2000, 0, 1) }], enumerable: true });
+        }
+        const html = await readFile(path.join(project.buildDir, 'index.html'), 'utf8');
+        const sdkUrl = BuildPlatformSdkCatalog.resolveHeadTags('poki')[0]?.attrs?.src;
+        const sources = [...html.matchAll(/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi)].map(match => match[1]);
+        if (typeof sdkUrl !== 'string' || sources.filter(src => src === sdkUrl).length !== 1) {
+            throw new Error('[poki] Expected exactly one official Poki SDK script');
+        }
+        for (const match of html.matchAll(/\b(?:src|href)\s*=\s*["']([^"']+)["']/gi)) {
+            const url = match[1];
+            if (!url || url.startsWith('#') || /^(?:https?:|data:|blob:|\/\/)/i.test(url))
+                continue;
+            if (url.startsWith('/'))
+                throw new Error(`[poki] Root-relative HTML dependency: ${url}`);
+            const file = path.posix.normalize(decodeURIComponent(url.split(/[?#]/)[0] ?? ''));
+            if (!files.includes(file))
+                throw new Error(`[poki] Missing HTML dependency: ${url}`);
+        }
+        if (/https?:\/\/(?:localhost|127\.0\.0\.1)(?=[:/"'])|\/src\/main\.ts/i.test(html)) {
+            throw new Error('[poki] Development entry or localhost URL in HTML');
+        }
+        const archive = zipSync(zip, { level: 9 });
+        await mkdir(path.dirname(project.archive), { recursive: true });
+        await writeFile(project.archive, archive);
+        return { sha256: createHash('sha256').update(archive).digest('hex'), bytes: archive.length, files: files.length };
+    }
+    static async collect(root, prefix = '') {
+        const result = [];
+        for (const name of (await readdir(path.join(root, prefix))).sort()) {
+            const file = prefix ? `${prefix}/${name}` : name;
+            if (name.startsWith('.') || /\.(?:map|ts|tsx|tgz|pem|key|zip)$/i.test(name)) {
+                throw new Error(`[poki] Source, private or nested archive file in build: ${file}`);
+            }
+            const stat = await lstat(path.join(root, file));
+            if (stat.isSymbolicLink())
+                throw new Error(`[poki] Symlink in build: ${file}`);
+            if (stat.isDirectory())
+                result.push(...await PokiArchive.collect(root, file));
+            else if (stat.isFile())
+                result.push(file);
+            else
+                throw new Error(`[poki] Unsupported build entry: ${file}`);
+        }
+        return result;
+    }
+}

package/dist/poki/PokiCredentials.d.ts

@@ -0,0 +1,5 @@
+/** Resolves a per-game secret outside the project or from the CI environment. */
+export declare class PokiCredentials {
+    static resolve(gameId: string): string;
+    static withoutSecrets(): NodeJS.ProcessEnv;
+}

package/dist/poki/PokiCredentials.js

@@ -0,0 +1,34 @@
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+/** Resolves a per-game secret outside the project or from the CI environment. */
+export class PokiCredentials {
+    static resolve(gameId) {
+        const envToken = process.env.POKI_UPLOAD_TOKEN;
+        if (envToken !== undefined) {
+            if (!envToken.trim())
+                throw new Error('[poki] POKI_UPLOAD_TOKEN must not be empty');
+            return envToken.trim();
+        }
+        const file = path.join(process.env.XDG_CONFIG_HOME ?? path.join(homedir(), '.config'), 'poki', 'game-upload-tokens', gameId);
+        try {
+            if (process.platform !== 'win32' && (statSync(file).mode & 0o777) !== 0o600) {
+                throw new Error('permissions');
+            }
+            const token = readFileSync(file, 'utf8').trim();
+            if (!token)
+                throw new Error('empty');
+            return token;
+        }
+        catch {
+            throw new Error(`[poki] Set POKI_UPLOAD_TOKEN or create a private (0600) token file: ${file}`);
+        }
+    }
+    static withoutSecrets() {
+        const env = { ...process.env };
+        delete env.POKI_UPLOAD_TOKEN;
+        delete env.POKI_ACCESS_TOKEN;
+        delete env.API_PATH;
+        return env;
+    }
+}

package/dist/poki/PokiProcess.d.ts

@@ -0,0 +1,5 @@
+/** Runs npm tasks and captures CLI output without shell-interpolated arguments. */
+export declare class PokiProcess {
+    static script(root: string, name: string): Promise<void>;
+    static capture(command: string, args: readonly string[], cwd: string, env: NodeJS.ProcessEnv, inherit?: boolean, secret?: string): Promise<string>;
+}

package/dist/poki/PokiProcess.js

@@ -0,0 +1,35 @@
+import { spawn } from 'node:child_process';
+import { PokiCredentials } from './PokiCredentials.js';
+/** Runs npm tasks and captures CLI output without shell-interpolated arguments. */
+export class PokiProcess {
+    static async script(root, name) {
+        const npmEntry = process.env.npm_execpath;
+        const command = npmEntry ? process.execPath : 'npm';
+        const args = npmEntry ? [npmEntry, 'run', name] : ['run', name];
+        await PokiProcess.capture(command, args, root, PokiCredentials.withoutSecrets(), true);
+    }
+    static capture(command, args, cwd, env, inherit = false, secret) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(command, [...args], { cwd, env, stdio: inherit ? 'inherit' : 'pipe',
+                shell: process.platform === 'win32' && command === 'npm' });
+            let output = '';
+            const timer = inherit ? undefined : setTimeout(() => child.kill('SIGKILL'), 180000);
+            const capture = (data) => { output += data.toString('utf8'); };
+            child.stdout?.on('data', capture);
+            child.stderr?.on('data', capture);
+            child.once('error', () => { if (timer)
+                clearTimeout(timer); reject(new Error('[poki] Could not start required tool')); });
+            child.once('close', code => {
+                if (timer)
+                    clearTimeout(timer);
+                const safe = secret ? output.replaceAll(secret, '[REDACTED]') : output;
+                if (!inherit)
+                    process.stdout.write(safe);
+                if (code !== 0)
+                    reject(new Error(`[poki] Tool exited with status ${code ?? 'signal'}`));
+                else
+                    resolve(safe);
+            });
+        });
+    }
+}

package/dist/poki/PokiProject.d.ts

@@ -0,0 +1,18 @@
+/** Decodes project-local configuration without game-specific defaults. */
+export declare class PokiProject {
+    readonly root: string;
+    readonly gameId: string;
+    readonly buildDir: string;
+    readonly archive: string;
+    readonly buildScript: string;
+    readonly checks: readonly string[];
+    private readonly scripts;
+    private static readonly TOOLING;
+    private static readonly CONFIG;
+    private static readonly PACKAGE;
+    private constructor();
+    static load(root: string): PokiProject;
+    validateScripts(): void;
+    private static json;
+    private static projectPath;
+}

package/dist/poki/PokiProject.js

@@ -0,0 +1,80 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { SchemaDecoder } from '@gamedevland/engine/validation';
+/** Decodes project-local configuration without game-specific defaults. */
+export class PokiProject {
+    root;
+    gameId;
+    buildDir;
+    archive;
+    buildScript;
+    checks;
+    scripts;
+    static TOOLING = SchemaDecoder.object({
+        buildScript: SchemaDecoder.optional(SchemaDecoder.string({ nonEmpty: true })),
+        checks: SchemaDecoder.optional(SchemaDecoder.array(SchemaDecoder.string({ nonEmpty: true }))),
+        archive: SchemaDecoder.optional(SchemaDecoder.string({ nonEmpty: true })),
+    });
+    static CONFIG = SchemaDecoder.object({
+        game_id: SchemaDecoder.string({ nonEmpty: true }),
+        build_dir: SchemaDecoder.string({ nonEmpty: true }),
+        tooling: SchemaDecoder.optional(PokiProject.TOOLING),
+    });
+    static PACKAGE = SchemaDecoder.object({
+        name: SchemaDecoder.string({ nonEmpty: true }),
+        scripts: SchemaDecoder.record(),
+    });
+    constructor(root, gameId, buildDir, archive, buildScript, checks, scripts) {
+        this.root = root;
+        this.gameId = gameId;
+        this.buildDir = buildDir;
+        this.archive = archive;
+        this.buildScript = buildScript;
+        this.checks = checks;
+        this.scripts = scripts;
+    }
+    static load(root) {
+        root = realpathSync(root);
+        const config = SchemaDecoder.decode(PokiProject.json(path.join(root, 'poki.json')), PokiProject.CONFIG, 'poki.json');
+        const pkg = SchemaDecoder.decode(PokiProject.json(path.join(root, 'package.json')), PokiProject.PACKAGE, 'package.json');
+        const scripts = Object.fromEntries(Object.entries(pkg.scripts).map(([key, value]) => [key, SchemaDecoder.decode(value, SchemaDecoder.string(), 'package.json', `$.scripts.${key}`)]));
+        if (!/^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i.test(config.game_id)) {
+            throw new Error('[poki] game_id must be a UUID');
+        }
+        const buildDir = PokiProject.projectPath(root, config.build_dir);
+        const slug = pkg.name.replace(/^@/, '').replace(/[^\w.-]+/g, '-');
+        const archive = PokiProject.projectPath(root, config.tooling?.archive ?? `artifacts/poki/${slug}.zip`);
+        if (!path.relative(buildDir, archive).startsWith(`..${path.sep}`)) {
+            throw new Error('[poki] Archive must be outside build_dir');
+        }
+        if (!archive.endsWith('.zip'))
+            throw new Error('[poki] Archive must end with .zip');
+        return new PokiProject(root, config.game_id, buildDir, archive, config.tooling?.buildScript ?? 'build:poki', config.tooling?.checks ?? ['typecheck', 'lint'], scripts);
+    }
+    validateScripts() {
+        for (const name of [...this.checks, this.buildScript]) {
+            if (!/^[\w:.-]+$/.test(name) || !this.scripts[name]) {
+                throw new Error(`[poki] Missing or invalid package.json script: ${name}`);
+            }
+            if (/\bgamedevland\s+poki\s+upload\b/.test(this.scripts[name])) {
+                throw new Error(`[poki] Recursive upload script: ${name}`);
+            }
+        }
+    }
+    static json(file) {
+        try {
+            return JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            throw new Error(`[poki] Cannot read valid JSON: ${file}`);
+        }
+    }
+    static projectPath(root, input) {
+        const result = path.resolve(root, input);
+        const relative = path.relative(root, result);
+        if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new Error('[poki] Build/archive paths must stay inside the project');
+        }
+        return result;
+    }
+}

package/dist/poki/PokiUpload.d.ts

@@ -0,0 +1,9 @@
+import type { PokiProject } from './PokiProject.js';
+/** Executes a fresh checked build and accepts only an API-confirmed upload. */
+export declare class PokiUpload {
+    static run(project: PokiProject, options: {
+        readonly name?: string;
+        readonly notes?: string;
+    }): Promise<void>;
+    private static git;
+}

package/dist/poki/PokiUpload.js

@@ -0,0 +1,57 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { PokiArchive } from './PokiArchive.js';
+import { PokiCredentials } from './PokiCredentials.js';
+import { PokiProcess } from './PokiProcess.js';
+/** Executes a fresh checked build and accepts only an API-confirmed upload. */
+export class PokiUpload {
+    static async run(project, options) {
+        project.validateScripts();
+        const secret = PokiCredentials.resolve(project.gameId);
+        const revision = PokiUpload.git(project.root, ['rev-parse', '--short', 'HEAD']);
+        const dirty = PokiUpload.git(project.root, ['status', '--porcelain']);
+        const name = options.name ?? `${revision || 'build'}-${new Date().toISOString().replace(/[-:.]/g, '')}`;
+        const notes = options.notes ?? (PokiUpload.git(project.root, ['log', '-1', '--pretty=%s']) || 'Automated game build');
+        if (!name.trim())
+            throw new Error('[poki] Version name must not be empty');
+        for (const task of [...project.checks, project.buildScript])
+            await PokiProcess.script(project.root, task);
+        const archive = await PokiArchive.pack(project, secret);
+        const scratch = await mkdtemp(path.join(tmpdir(), 'gamedevland-poki-'));
+        let output;
+        try {
+            const cli = createRequire(import.meta.url).resolve('@poki/cli/bin/index.js');
+            output = await PokiProcess.capture(process.execPath, [cli, 'upload', '--game', project.gameId,
+                '--build-dir', project.buildDir, '--name', name, '--notes', notes, '--disable-image-compression'], scratch, { ...PokiCredentials.withoutSecrets(), POKI_UPLOAD_TOKEN: secret }, false, secret);
+        }
+        finally {
+            await rm(scratch, { recursive: true, force: true });
+        }
+        // @poki/cli 0.1.19 also exits 0 on API errors; require its success response.
+        if (!output.includes('Version uploaded successfully'))
+            throw new Error('[poki] Upload not confirmed by Poki');
+        const preview = output.match(/Preview: (https:\/\/poki\.com\/en\/preview\/[^\s]+)/)?.[1];
+        const inspector = output.match(/Inspector: (https:\/\/inspector\.poki\.dev\/[^\s]+)/)?.[1];
+        const prefix = `https://poki.com/en/preview/${project.gameId}/`;
+        const versionId = preview?.startsWith(prefix) ? preview.slice(prefix.length) : '';
+        if (!/^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i.test(versionId) || inspector !== `https://inspector.poki.dev/?game=poki-${versionId}`) {
+            throw new Error('[poki] Upload response does not match the configured game/version');
+        }
+        const receipt = path.join(path.dirname(project.archive), 'poki-upload.json');
+        await writeFile(receipt, JSON.stringify({ gameId: project.gameId, versionId, name, revision,
+            dirty: Boolean(dirty), uploadedAt: new Date().toISOString(), archive: project.archive,
+            archiveSha256: archive.sha256, bytes: archive.bytes, files: archive.files, preview, inspector }, null, 2) + '\n');
+        process.stdout.write(`[poki] Receipt: ${receipt}\n`);
+    }
+    static git(root, args) {
+        try {
+            return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: PokiCredentials.withoutSecrets() }).trim();
+        }
+        catch {
+            return '';
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamedevland/vite",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "type": "module",
   "description": "Vite build tooling for Gamedev Land HTML5 games.",
   "license": "SEE LICENSE IN LICENSE",
@@ -15,9 +15,16 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
+  "bin": {
+    "gamedevland": "./dist/cli/entry.js"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -30,13 +37,16 @@
     }
   },
   "scripts": {
+    "test": "node --test tests/*.test.mjs",
     "clean": "rimraf dist *.tsbuildinfo",
     "pretypecheck": "npm run build -w @gamedevland/engine",
     "typecheck": "tsc --noEmit",
     "build": "npm run clean && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths"
   },
   "dependencies": {
-    "@gamedevland/engine": "0.0.5"
+    "@gamedevland/engine": "0.0.5",
+    "@poki/cli": "0.1.19",
+    "fflate": "0.8.3"
   },
   "peerDependencies": {
     "vite": "^7.1.0 || ^8.0.0"