@mpgd/cli 0.2.0 → 0.3.1

package/dist/index.js

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import completion from '@gunshi/plugin-completion';
@@ -11,8 +11,8 @@ const packageRoot = resolvePackageRoot(sourceDir);
 const detectedKitRoot = resolveDefaultKitRoot();
 const gameTemplateDir = path.resolve(packageRoot, 'templates/phaser-game');
 const cliVersion = readPackageVersion(packageRoot);
-const defaultMatrixTargets = 'web,ait';
-const defaultDependencyVersion = '^0.1.0';
+const defaultMatrixTargets = 'web,ait,reddit';
+const defaultDependencyVersion = `^${cliVersion}`;
 const supportedBuildTargets = [
     'browser',
     'web',
@@ -471,7 +471,7 @@ function matrixArgResources() {
     };
 }
 function createGameApp(input) {
-    const appDir = path.resolve(process.cwd(), input.directory);
+    const appDir = resolveAppDirectory(input.directory);
     const gameName = path.basename(appDir);
     assertValidGameName(gameName);
     const packageName = input.packageName ?? gameName;
@@ -504,13 +504,14 @@ function createGameApp(input) {
     }
     console.log(`Created ${appDir}`);
     console.log('Next steps:');
-    console.log(`  pnpm --dir ${appDir} install`);
-    console.log(`  pnpm --dir ${appDir} dev`);
+    console.log(`  cd ${appDir}`);
+    console.log('  pnpm install --filter . --filter ./apps/target-devvit');
+    console.log('  pnpm dev');
     console.log('Target builds require an mpgd-kit checkout:');
     console.log([
         '  mpgd target build-all',
         `--targets-file ${path.join(appDir, 'mpgd.targets.json')}`,
-        '--targets web,ait',
+        `--targets ${defaultMatrixTargets}`,
         '--ait-variant wrapper',
         '--kit-path <path-to-mpgd-kit>',
     ].join(' '));
@@ -520,6 +521,14 @@ function assertValidGameName(name) {
         throw new Error('Game directory basename must use kebab-case, for example: puzzle-one');
     }
 }
+function resolveAppDirectory(directory) {
+    const resolved = path.resolve(process.cwd(), directory);
+    const parent = path.dirname(resolved);
+    if (!existsSync(parent)) {
+        return resolved;
+    }
+    return path.join(realpathSync(parent), path.basename(resolved));
+}
 function assertValidPackageName(name) {
     if (!/^(?:@[a-z][a-z0-9-]*\/)?[a-z][a-z0-9-]*$/.test(name)) {
         throw new Error('Package name must be kebab-case, optionally scoped, for example: @scope/puzzle-one');
@@ -541,7 +550,9 @@ function createTemplateContext(input) {
     const workspacePrefix = workspaceRoot;
     return {
         gameName: input.gameName,
+        devvitAppName: toDevvitAppName(input.gameName),
         gameTitle: title,
+        gameTitleTsLiteral: toJavaScriptStringLiteral(title),
         packageName: input.packageName,
         dependencyVersion: input.dependencyVersion,
         tsconfigExtendsLine: input.workspace
@@ -557,6 +568,7 @@ function createTemplateContext(input) {
         tsconfigWorkspaceExcludes: input.workspace
             ? [
                 `,\n    "${workspacePrefix}/packages/**/dist/**"`,
+                `,\n    "${workspacePrefix}/packages/cli/templates/**"`,
                 `,\n    "${workspacePrefix}/adapters/**/dist/**"`,
                 `,\n    "${workspacePrefix}/native-plugins/**/dist/**"`,
             ].join('')
@@ -564,6 +576,15 @@ function createTemplateContext(input) {
         workspaceI18nBuildPrefix: input.workspace
             ? `pnpm --dir ${workspacePrefix} i18n:build && `
             : '',
+        defaultKitPath: kitPath === undefined ? '../mpgd-kit' : workspacePrefix,
+        pnpmWorkspaceKitPackages: input.workspace
+            ? [
+                `  - '${workspacePrefix}/packages/*'`,
+                `  - '${workspacePrefix}/adapters/*'`,
+                `  - '${workspacePrefix}/native-plugins/*'`,
+                `  - '${workspacePrefix}/backend/*'`,
+            ].join('\n')
+            : '',
         pascalName: toPascalCase(input.gameName),
         camelName: toCamelCase(input.gameName),
     };
@@ -590,7 +611,7 @@ function walkTemplateDir(templateDir, relativeDir, files) {
             continue;
         }
         files.push({
-            relativePath,
+            relativePath: templateOutputPath(relativePath),
             content: readFileSync(path.join(templateDir, relativePath), 'utf8'),
         });
     }
@@ -598,6 +619,8 @@ function walkTemplateDir(templateDir, relativeDir, files) {
 function renderTemplate(content, context) {
     return content
         .replaceAll('__GAME_NAME__', context.gameName)
+        .replaceAll('__DEVVIT_APP_NAME__', context.devvitAppName)
+        .replaceAll('__GAME_TITLE_TS_LITERAL__', context.gameTitleTsLiteral)
         .replaceAll('__GAME_TITLE__', context.gameTitle)
         .replaceAll('__PACKAGE_NAME__', context.packageName)
         .replaceAll('__MPGD_DEPENDENCY_VERSION__', context.dependencyVersion)
@@ -605,9 +628,16 @@ function renderTemplate(content, context) {
         .replaceAll('__TSCONFIG_WORKSPACE_INCLUDES__', context.tsconfigWorkspaceIncludes)
         .replaceAll('__TSCONFIG_WORKSPACE_EXCLUDES__', context.tsconfigWorkspaceExcludes)
         .replaceAll('__WORKSPACE_I18N_BUILD_PREFIX__', context.workspaceI18nBuildPrefix)
+        .replaceAll('__DEFAULT_KIT_PATH__', context.defaultKitPath)
+        .replaceAll('__PNPM_WORKSPACE_KIT_PACKAGES__', context.pnpmWorkspaceKitPackages)
         .replaceAll('__PASCAL_NAME__', context.pascalName)
         .replaceAll('__CAMEL_NAME__', context.camelName);
 }
+function templateOutputPath(relativePath) {
+    return path.basename(relativePath) === 'gitignore'
+        ? path.join(path.dirname(relativePath), '.gitignore')
+        : relativePath;
+}
 function toPascalCase(value) {
     return value
         .split('-')
@@ -619,6 +649,22 @@ function toCamelCase(value) {
     const pascal = toPascalCase(value);
     return `${pascal[0]?.toLowerCase() ?? ''}${pascal.slice(1)}`;
 }
+function toDevvitAppName(gameName) {
+    let appName = gameName
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    if (appName.length < 3) {
+        appName = `${appName}-game`;
+    }
+    if (appName.length > 16) {
+        appName = appName.slice(0, 16).replace(/-+$/g, '');
+    }
+    return appName.length >= 3 ? appName : 'mpgd-game';
+}
+function toJavaScriptStringLiteral(value) {
+    return JSON.stringify(value);
+}
 function toTemplatePath(value) {
     return value.split(path.sep).join('/');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {

package/templates/phaser-game/README.md

@@ -5,7 +5,7 @@ Standalone Phaser 4 game starter generated by `@mpgd/create-game`.
 ## Local Loop
 
 ```sh
-pnpm install
+pnpm install --filter . --filter ./apps/target-devvit
 pnpm dev
 pnpm check
 pnpm build
@@ -22,19 +22,20 @@ The starter keeps game code behind `PlatformGateway` and demonstrates:
 
 ## Target Builds
 
-Target builds require an `mpgd-kit` checkout because the target wrappers live in
-the kit repository. Pass that checkout with `--kit-path`:
+Target builds use the mpgd CLI because it knows how to turn this game into
+platform-specific artifacts. Keep an `mpgd-kit` checkout nearby and pass it with
+`--kit-path`, or set `MPGD_KIT_PATH` once in your shell.
 
 ```sh
-pnpm dlx @mpgd/cli target build-all \
+pnpm exec mpgd target build-all \
   --targets-file ./mpgd.targets.json \
   --kit-path ../mpgd-kit \
-  --targets web,ait \
+  --targets web,ait,reddit \
   --ait-variant wrapper
-pnpm dlx @mpgd/cli target smoke-all \
+pnpm exec mpgd target smoke-all \
   --targets-file ./mpgd.targets.json \
   --kit-path ../mpgd-kit \
-  --targets web,ait
+  --targets web,ait,reddit
 ```
 
 When developing the kit itself, the same commands work through the repository
@@ -44,7 +45,7 @@ script:
 pnpm --dir ../mpgd-kit mpgd target build-all \
   --targets-file "$PWD/mpgd.targets.json" \
   --kit-path ../mpgd-kit \
-  --targets web,ait \
+  --targets web,ait,reddit \
   --ait-variant wrapper
 ```
 
@@ -52,6 +53,46 @@ pnpm --dir ../mpgd-kit mpgd target build-all \
 into `.mpgd.targets.generated.json` before calling the kit's existing target
 build and smoke scripts.
 
+## Reddit Devvit
+
+This starter owns its Devvit app root in `apps/target-devvit`. That directory
+contains the generated game's `devvit.json`, server bridge, menu entry, and
+Devvit CLI scripts. It intentionally does not point at the kit demo app, because
+Reddit app names, uploads, and playtests belong to each individual game.
+The generated `devvit.json` app name is a Devvit-safe slug derived from the game
+directory name; edit it before `devvit:init` if you need a different Reddit app
+name.
+
+First-time Devvit setup:
+
+```sh
+pnpm install --filter . --filter ./apps/target-devvit
+pnpm devvit:login
+pnpm devvit:whoami
+pnpm devvit:init
+pnpm build:devvit
+pnpm devvit:playtest
+```
+
+`devvit:login` authenticates your Reddit account. `devvit:init` performs the
+first App Directory upload/link step for the app name in
+`apps/target-devvit/devvit.json` using Devvit's copy-paste flow. After init, use
+`pnpm devvit:playtest`, `pnpm devvit:upload`, and `pnpm devvit:publish` from
+this game root.
+
+## Target Ownership Notes
+
+- Browser preview is fully game-owned and writes to `artifacts/web-preview`.
+- Reddit Devvit is game-owned in `apps/target-devvit`.
+- Apps in Toss currently uses the kit reference wrapper at
+  `${MPGD_KIT_PATH}/apps/target-ait` for smoke packaging. Before a real Toss
+  submission, create a game-owned wrapper/config so the app name, CLI state, and
+  review metadata are not shared with the kit demo.
+- Android and iOS currently use the kit reference Capacitor shell at
+  `${MPGD_KIT_PATH}/apps/mobile-capacitor`. That is useful for local artifact
+  checks, but production apps should own their bundle ID/package ID, signing,
+  icons, and store metadata in a game-specific shell.
+
 ## Game Services
 
 The backend client is disabled unless a backend URL is configured:

package/templates/phaser-game/agent/acceptance.md

@@ -5,12 +5,14 @@ Run these checks before handing off a generated game starter:
 ```sh
 pnpm check
 pnpm build
-pnpm --dir ../mpgd-kit mpgd target build-all --targets-file "$PWD/mpgd.targets.json" --targets web,ait --ait-variant wrapper
-pnpm --dir ../mpgd-kit mpgd target smoke-all --targets-file "$PWD/mpgd.targets.json" --targets web,ait
+pnpm --dir ../mpgd-kit mpgd target build-all --targets-file "$PWD/mpgd.targets.json" --targets web,ait,reddit --ait-variant wrapper
+pnpm --dir ../mpgd-kit mpgd target smoke-all --targets-file "$PWD/mpgd.targets.json" --targets web,ait,reddit
 ```
 
 For Apps in Toss changes, use the apps-in-toss MCP before implementation and
 keep SDK calls inside adapters or target wrappers.
 
 For Reddit Devvit changes, keep Devvit SDK calls inside the target wrapper and
-continue to expose game-facing behavior through `PlatformGateway`.
+continue to expose game-facing behavior through `PlatformGateway`. The Devvit
+app root is game-owned in `apps/target-devvit`; run `pnpm devvit:init` once
+after login before upload or playtest.

package/templates/phaser-game/agent/brief.md

@@ -16,5 +16,8 @@ Useful commands:
 pnpm dev
 pnpm check
 pnpm build
-pnpm --dir ../mpgd-kit mpgd target build-all --targets-file "$PWD/mpgd.targets.json" --targets web,ait --ait-variant wrapper
+pnpm exec mpgd target build-all --targets-file ./mpgd.targets.json --kit-path ../mpgd-kit --targets web,ait,reddit --ait-variant wrapper
+pnpm devvit:login
+pnpm devvit:init
+pnpm devvit:playtest
 ```

package/templates/phaser-game/agent/game-manifest.json

@@ -10,7 +10,7 @@
   "platformBoundary": "PlatformGateway",
   "mcpRequirements": {
     "ait": "Use apps-in-toss MCP before Apps in Toss SDK or review-flow changes.",
-    "reddit": "Use Devvit documentation/MCP before Devvit SDK or publish-flow changes."
+    "reddit": "Use Devvit documentation/MCP before Devvit SDK or publish-flow changes. Keep Reddit deployment files in apps/target-devvit."
   },
   "blocks": [
     {
@@ -21,6 +21,10 @@
       "id": "runtime.platform.gateway",
       "owner": "src/platform/installPlatform.ts"
     },
+    {
+      "id": "platform.devvit.app-root",
+      "owner": "apps/target-devvit"
+    },
     {
       "id": "services.backend.game-services",
       "owner": "src/platform/gameServices.ts"

package/templates/phaser-game/apps/target-devvit/README.md

@@ -0,0 +1,30 @@
+# __GAME_TITLE__ Devvit Target
+
+This directory is the Reddit Devvit app root for `__GAME_NAME__`.
+
+`devvit.json` belongs to the generated game, not to the mpgd-kit checkout. That keeps the
+Reddit app name, menu entry, upload history, and playtest state owned by this game.
+Its `name` is generated as a Devvit-safe slug; edit it before `pnpm devvit:init`
+if you want a different Reddit app name.
+
+## First Playtest
+
+```sh
+pnpm install --filter . --filter ./apps/target-devvit
+pnpm devvit:login
+pnpm devvit:whoami
+pnpm devvit:init
+pnpm build:devvit
+pnpm devvit:playtest
+```
+
+`devvit:init` performs the first App Directory upload/link step with Devvit's
+copy-paste flow. Login proves who you are; init uploads and links the
+Reddit-side app record for the `name` in `devvit.json`. After that, use
+`pnpm devvit:playtest`, `pnpm devvit:upload`, and `pnpm devvit:publish` from the
+game root.
+
+The client bundle is copied into `dist/client` by the mpgd target build. The server bridge is
+compiled to `dist/server/index.cjs` and keeps Devvit SDK imports out of Phaser scenes.
+The game root pins `@mpgd/cli`, so these commands use the same CLI version as the generated
+starter's other `@mpgd/*` dependencies.

package/templates/phaser-game/apps/target-devvit/devvit.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://developers.reddit.com/schema/config-file.v1.json",
+  "name": "__DEVVIT_APP_NAME__",
+  "post": {
+    "dir": "dist/client",
+    "entrypoints": {
+      "default": {
+        "entry": "index.html",
+        "height": "tall"
+      }
+    }
+  },
+  "server": {
+    "dir": "dist/server",
+    "entry": "index.cjs"
+  },
+  "permissions": {
+    "redis": true,
+    "reddit": {
+      "enable": true
+    },
+    "payments": false,
+    "realtime": false
+  },
+  "menu": {
+    "items": [
+      {
+        "label": "Create __GAME_TITLE__ post",
+        "description": "Create a playable __GAME_TITLE__ post.",
+        "forUserType": "moderator",
+        "location": "subreddit",
+        "endpoint": "/internal/menu/create-post"
+      }
+    ]
+  },
+  "scripts": {
+    "dev": "pnpm dev:prepare && pnpm dev:watch",
+    "build": "pnpm build"
+  }
+}

package/templates/phaser-game/apps/target-devvit/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "__PACKAGE_NAME__-target-devvit",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "init": "devvit upload --copy-paste --config devvit.json",
+    "dev": "devvit playtest --config devvit.json",
+    "dev:prepare": "pnpm --dir ../.. build:devvit:staging",
+    "dev:client": "APP_TARGET=reddit APP_VERSION=0.0.0-dev BUILD_ID=devvit-watch pnpm --dir ../.. exec vite build --mode staging --watch --outDir apps/target-devvit/dist/client",
+    "dev:server": "vite build --config vite.server.config.ts --watch",
+    "dev:watch": "concurrently --kill-others --success first \"pnpm run dev:client\" \"pnpm run dev:server\"",
+    "build": "pnpm --dir ../.. build:devvit",
+    "build:server": "vite build --config vite.server.config.ts",
+    "whoami": "devvit whoami",
+    "upload": "devvit upload --config devvit.json",
+    "publish": "devvit publish --config devvit.json",
+    "check": "ttsc --noEmit -p tsconfig.json",
+    "lint": "ttsc --noEmit -p tsconfig.json",
+    "format": "ttsc format",
+    "fix": "ttsc fix"
+  },
+  "dependencies": {
+    "@devvit/web": "0.13.6",
+    "@mpgd/bridge": "__MPGD_DEPENDENCY_VERSION__",
+    "express": "^5.2.1",
+    "helmet": "^8.1.0"
+  },
+  "devDependencies": {
+    "@ttsc/unplugin": "0.16.9",
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.0.0",
+    "concurrently": "10.0.3",
+    "devvit": "0.13.6",
+    "ttsc": "0.16.9",
+    "typescript": "7.0.1-rc",
+    "vite": "^8.1.3"
+  }
+}

package/templates/phaser-game/apps/target-devvit/src/server/index.ts

@@ -0,0 +1,656 @@
+import { createServer, context, getServerPort, reddit, redis } from '@devvit/web/server';
+import type { UiResponse } from '@devvit/web/shared';
+import {
+  assertBridgeRequest,
+  createBridgeError,
+  type BridgeRequest,
+  type BridgeResponse,
+} from '@mpgd/bridge';
+import {
+  createBridgeRpcFetchHandler,
+  createBridgeRpcRouter,
+  defaultBridgeRpcEndpoint,
+} from '@mpgd/bridge/orpc';
+import express, { type Request as ExpressRequest, type Response as ExpressResponse } from 'express';
+import helmet from 'helmet';
+
+const app = express();
+const redisKeyComponentPattern = /^[A-Za-z0-9:_-]{1,128}$/;
+const maxStorageKeyLength = 128;
+const maxEncodedStorageKeyLength = 384;
+const leaderboardUpdateMaxAttempts = 3;
+const leaderboardBackoffBaseMs = 25;
+const leaderboardLockTtlMs = 2_000;
+const leaderboardLockTtlSeconds = Math.ceil(leaderboardLockTtlMs / 1_000);
+const leaderboardLockRetryBudgetMs = leaderboardLockTtlSeconds * 1_000;
+const gameName = '__GAME_NAME__';
+const gameTitle = __GAME_TITLE_TS_LITERAL__;
+const expressManagedResponseHeaders = new Set([
+  'connection',
+  'content-encoding',
+  'content-length',
+  'transfer-encoding',
+]);
+
+app.disable('x-powered-by');
+app.use(helmet());
+
+const bridgeRpcFetchHandler = createBridgeRpcFetchHandler(
+  createBridgeRpcRouter(handleBridgeRequest),
+);
+
+app.use(defaultBridgeRpcEndpoint, express.raw({ type: '*/*', limit: '1mb' }), async (
+  request: ExpressRequest,
+  response: ExpressResponse,
+): Promise<void> => {
+  try {
+    const fetchResponse = await bridgeRpcFetchHandler(expressRequestToFetchRequest(request));
+    await sendFetchResponse(response, fetchResponse);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Devvit oRPC request failed.';
+    console.error(`devvit oRPC internal error: ${message}`, error);
+    response.status(500).json(
+      createBridgeError(
+        requestIdFromBody(request.body),
+        'DEVVIT_BRIDGE_INTERNAL_ERROR',
+        'Devvit bridge request failed.',
+        true,
+      ),
+    );
+  }
+});
+
+app.use(express.json({ limit: '1mb' }));
+
+app.post('/internal/menu/create-post', async (
+  _request: ExpressRequest,
+  response: ExpressResponse,
+): Promise<void> => {
+  const subredditName = currentSubredditName();
+
+  if (subredditName === undefined) {
+    response.status(200).json({
+      showToast: {
+        text: 'Could not resolve the target subreddit for this menu action.',
+        appearance: 'neutral',
+      },
+    } satisfies UiResponse);
+    return;
+  }
+
+  try {
+    const post = await reddit.submitCustomPost({
+      subredditName,
+      title: gameTitle,
+      entry: 'default',
+      textFallback: {
+        text: `Open this Reddit custom post to play ${gameTitle}.`,
+      },
+      postData: {
+        source: gameName,
+        createdBy: 'devvit-menu',
+      },
+    });
+
+    response.status(200).json({
+      showToast: {
+        text: `Created ${gameTitle} post ${post.id}.`,
+        appearance: 'success',
+      },
+    } satisfies UiResponse);
+  } catch (error) {
+    console.error(`devvit custom post creation failed: ${errorMessage(error)}`, error);
+    response.status(200).json({
+      showToast: {
+        text: `Could not create the ${gameTitle} post.`,
+        appearance: 'neutral',
+      },
+    } satisfies UiResponse);
+  }
+});
+
+app.post('/api/mpgd/bridge', async (
+  request: ExpressRequest,
+  response: ExpressResponse,
+): Promise<void> => {
+  let bridgeRequest: BridgeRequest;
+
+  try {
+    bridgeRequest = assertBridgeRequest(request.body);
+  } catch (error) {
+    response.status(400).json(
+      createBridgeError(
+        requestIdFromBody(request.body),
+        'INVALID_BRIDGE_REQUEST',
+        error instanceof Error ? error.message : 'Invalid bridge request.',
+      ),
+    );
+    return;
+  }
+
+  try {
+    const bridgeResponse = await handleBridgeRequest(bridgeRequest);
+    response.status(200).json(bridgeResponse);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Devvit bridge request failed.';
+    console.error(`devvit bridge internal error: ${message}`, error);
+
+    response.status(500).json(
+      createBridgeError(
+        bridgeRequest.id,
+        'DEVVIT_BRIDGE_INTERNAL_ERROR',
+        'Devvit bridge request failed.',
+        true,
+      ),
+    );
+  }
+});
+
+const server = createServer(app);
+const port = getServerPort();
+
+server.on('error', (error) => {
+  console.error(`devvit server error: ${error.stack}`);
+});
+
+server.listen(port, () => {
+  console.log(`devvit server listening on ${port}`);
+});
+
+async function handleBridgeRequest(input: BridgeRequest): Promise<BridgeResponse> {
+  switch (input.method) {
+    case 'runtime.getCapabilities':
+      return ok(input, {
+        nativeIap: false,
+        nativeAds: false,
+        rewardedAds: false,
+        interstitialAds: false,
+        nativeLeaderboard: true,
+        achievements: false,
+        cloudSave: true,
+        socialShare: true,
+        haptics: false,
+        localizedContent: true,
+      });
+
+    case 'identity.getPlayer': {
+      const playerId = currentPlayerId();
+
+      if (playerId === undefined) {
+        return ok(input, null);
+      }
+
+      return ok(input, {
+        playerId,
+        displayName: await currentDisplayName(playerId),
+      });
+    }
+
+    case 'commerce.getProducts':
+    case 'commerce.getEntitlements':
+      return ok(input, []);
+
+    case 'commerce.purchase':
+      return ok(input, {
+        status: 'cancelled',
+        entitlementIds: [],
+      });
+
+    case 'commerce.restore':
+      return ok(input, {
+        restoredEntitlements: [],
+      });
+
+    case 'ads.preload':
+      return ok(input, {});
+
+    case 'leaderboard.open':
+      return createBridgeError(
+        input.id,
+        'DEVVIT_LEADERBOARD_OPEN_UNAVAILABLE',
+        'Devvit leaderboard display is not implemented yet.',
+      );
+
+    case 'ads.showRewarded':
+      return ok(input, {
+        status: 'unavailable',
+        rewardGranted: false,
+      });
+
+    case 'ads.showInterstitial':
+      return ok(input, {
+        status: 'unavailable',
+      });
+
+    case 'leaderboard.submitScore':
+      return submitLeaderboardScore(input);
+
+    case 'storage.load':
+      return loadStorage(input);
+
+    case 'storage.save':
+      return saveStorage(input);
+
+    default:
+      return createBridgeError(
+        input.id,
+        'UNSUPPORTED_METHOD',
+        `Unsupported Devvit bridge method: ${input.method}`,
+      );
+  }
+}
+
+async function submitLeaderboardScore(input: BridgeRequest): Promise<BridgeResponse> {
+  const payload = optionalObjectPayload(input.payload) as {
+    readonly leaderboardId?: unknown;
+    readonly score?: unknown;
+  };
+  const leaderboardId = leaderboardIdFromPayload(input, payload.leaderboardId);
+  const playerId = currentPlayerId();
+
+  if (typeof leaderboardId !== 'string') {
+    return leaderboardId;
+  }
+
+  if (typeof payload.score !== 'number' || !Number.isFinite(payload.score)) {
+    return createBridgeError(
+      input.id,
+      'INVALID_LEADERBOARD_SCORE',
+      'Finite leaderboard score is required.',
+    );
+  }
+
+  if (playerId === undefined) {
+    return ok(input, {
+      submitted: false,
+    });
+  }
+
+  const redisKey = leaderboardKey(leaderboardId);
+  let scoreUpdate: 'updated' | 'unchanged' | 'failed';
+
+  try {
+    scoreUpdate = await submitMaxLeaderboardScore(redisKey, playerId, payload.score);
+  } catch (error) {
+    console.warn(`devvit leaderboard score submission failed: ${errorMessage(error)}`);
+    scoreUpdate = 'failed';
+  }
+
+  return ok(input, {
+    submitted: scoreUpdate !== 'failed',
+    highScoreUpdated: scoreUpdate === 'updated',
+  });
+}
+
+async function loadStorage(input: BridgeRequest): Promise<BridgeResponse> {
+  const playerId = currentPlayerId();
+
+  if (playerId === undefined) {
+    return ok(input, null);
+  }
+
+  const key = storageKey(input, playerId);
+
+  if (typeof key !== 'string') {
+    return key;
+  }
+
+  const stored = await redis.get(key);
+
+  if (stored === undefined || stored === null) {
+    return ok(input, null);
+  }
+
+  try {
+    return ok(input, JSON.parse(stored));
+  } catch {
+    return createBridgeError(input.id, 'CORRUPTED_STORAGE_VALUE', 'Stored data is not valid JSON.');
+  }
+}
+
+async function saveStorage(input: BridgeRequest): Promise<BridgeResponse> {
+  const playerId = currentPlayerId();
+
+  if (playerId === undefined) {
+    return ok(input, {
+      saved: false,
+    });
+  }
+
+  const key = storageKey(input, playerId);
+
+  if (typeof key !== 'string') {
+    return key;
+  }
+
+  const payload = optionalObjectPayload(input.payload) as { readonly value?: unknown };
+
+  try {
+    await redis.set(key, JSON.stringify(payload.value ?? null));
+  } catch (error) {
+    console.warn(`devvit storage save was not persisted for key ${key}: ${errorMessage(error)}`);
+
+    return ok(input, {
+      saved: false,
+      playerId,
+    });
+  }
+
+  return ok(input, {
+    saved: true,
+    playerId,
+  });
+}
+
+function requestIdFromBody(input: unknown): string {
+  if (typeof input !== 'object' || input === null) {
+    return 'unknown';
+  }
+
+  const candidate = input as { readonly id?: unknown };
+  return typeof candidate.id === 'string' ? candidate.id : 'unknown';
+}
+
+function ok(input: BridgeRequest, data: unknown): BridgeResponse {
+  return {
+    id: input.id,
+    ok: true,
+    data,
+  };
+}
+
+function storageKey(input: BridgeRequest, playerId: string): string | BridgeResponse {
+  const payload = optionalObjectPayload(input.payload);
+
+  if (typeof payload.key !== 'string' || payload.key.length === 0) {
+    return createBridgeError(input.id, 'INVALID_STORAGE_KEY', 'Storage key is required.');
+  }
+
+  if (payload.key.length > maxStorageKeyLength) {
+    return createBridgeError(input.id, 'INVALID_STORAGE_KEY', 'Storage key is too long.');
+  }
+
+  const encodedKey = encodeURIComponent(payload.key);
+
+  if (encodedKey.length > maxEncodedStorageKeyLength) {
+    return createBridgeError(input.id, 'INVALID_STORAGE_KEY', 'Encoded storage key is too long.');
+  }
+
+  return `${gameName}:save:${encodeURIComponent(playerId)}:${encodedKey}`;
+}
+
+function leaderboardIdFromPayload(
+  input: BridgeRequest,
+  value: unknown,
+): string | BridgeResponse {
+  if (value === undefined) {
+    return 'default';
+  }
+
+  if (typeof value !== 'string' || !isValidRedisKeyComponent(value)) {
+    return createBridgeError(
+      input.id,
+      'INVALID_LEADERBOARD_ID',
+      'Leaderboard id format is invalid.',
+    );
+  }
+
+  return value;
+}
+
+function leaderboardKey(leaderboardId: string): string {
+  return `${gameName}:leaderboard:${encodeURIComponent(leaderboardId)}`;
+}
+
+async function submitMaxLeaderboardScore(
+  redisKey: string,
+  playerId: string,
+  score: number,
+): Promise<'updated' | 'unchanged' | 'failed'> {
+  const lockKey = leaderboardLockKey(redisKey, playerId);
+  const startedAt = Date.now();
+  let attempt = 0;
+
+  while (Date.now() - startedAt <= leaderboardLockRetryBudgetMs) {
+    const lockToken = createLockToken();
+    const acquiredLock = await acquireLeaderboardLock(lockKey, lockToken);
+
+    if (!acquiredLock) {
+      await delay(nextLeaderboardRetryDelay(attempt, startedAt));
+      attempt += 1;
+      continue;
+    }
+
+    try {
+      const currentScore = await redis.zScore(redisKey, playerId);
+
+      if (currentScore !== undefined && score <= currentScore) {
+        return 'unchanged';
+      }
+
+      if (await writeLeaderboardScoreIfLockHeld(lockKey, lockToken, redisKey, playerId, score)) {
+        return 'updated';
+      }
+
+      await delay(nextLeaderboardRetryDelay(attempt, startedAt));
+      attempt += 1;
+    } finally {
+      try {
+        await releaseLeaderboardLock(lockKey, lockToken);
+      } catch (error) {
+        console.warn(`devvit leaderboard lock release failed: ${errorMessage(error)}`);
+      }
+    }
+  }
+
+  console.warn(`devvit leaderboard lock contention exceeded retry budget for key: ${lockKey}`);
+
+  return 'failed';
+}
+
+function leaderboardLockKey(redisKey: string, playerId: string): string {
+  return `${redisKey}:lock:${encodeURIComponent(playerId)}`;
+}
+
+function createLockToken(): string {
+  const cryptoImpl = globalThis.crypto;
+
+  if (typeof cryptoImpl?.randomUUID === 'function') {
+    return cryptoImpl.randomUUID();
+  }
+
+  if (typeof cryptoImpl?.getRandomValues === 'function') {
+    const values = new Uint32Array(4);
+    cryptoImpl.getRandomValues(values);
+
+    return Array.from(values, (value) => value.toString(36).padStart(7, '0')).join('');
+  }
+
+  throw new Error('Web Crypto is required to create a Devvit leaderboard lock token.');
+}
+
+async function acquireLeaderboardLock(lockKey: string, lockToken: string): Promise<boolean> {
+  const result = await redis.set(lockKey, lockToken, {
+    nx: true,
+    expiration: leaderboardLockExpirationDate(),
+  });
+
+  return result === 'OK';
+}
+
+function leaderboardLockExpirationDate(): Date {
+  // Devvit Redis SetOptions expects a Date and converts it to Redis EX seconds internally.
+  return new Date(Date.now() + leaderboardLockTtlSeconds * 1_000);
+}
+
+async function writeLeaderboardScoreIfLockHeld(
+  lockKey: string,
+  lockToken: string,
+  redisKey: string,
+  playerId: string,
+  score: number,
+): Promise<boolean> {
+  const transaction = await redis.watch(lockKey);
+  const currentToken = await redis.get(lockKey);
+
+  if (currentToken !== lockToken) {
+    await transaction.unwatch();
+    return false;
+  }
+
+  await transaction.multi();
+  await transaction.zAdd(redisKey, {
+    member: playerId,
+    score,
+  });
+
+  const results = await transaction.exec();
+
+  return Array.isArray(results) && results.length > 0;
+}
+
+async function releaseLeaderboardLock(lockKey: string, lockToken: string): Promise<void> {
+  for (let attempt = 0; attempt < leaderboardUpdateMaxAttempts; attempt += 1) {
+    const transaction = await redis.watch(lockKey);
+    const currentToken = await redis.get(lockKey);
+
+    if (currentToken !== lockToken) {
+      await transaction.unwatch();
+      return;
+    }
+
+    await transaction.multi();
+    await transaction.del(lockKey);
+
+    const results = await transaction.exec();
+
+    if (Array.isArray(results) && results.length > 0) {
+      return;
+    }
+
+    await delay(leaderboardBackoffBaseMs * (attempt + 1));
+  }
+
+  console.warn(`devvit leaderboard lock release exhausted retries for key: ${lockKey}`);
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function nextLeaderboardRetryDelay(attempt: number, startedAt: number): number {
+  const elapsed = Date.now() - startedAt;
+  const remaining = Math.max(0, leaderboardLockRetryBudgetMs - elapsed);
+  const backoff = leaderboardBackoffBaseMs * (attempt + 1);
+
+  return Math.min(backoff, remaining);
+}
+
+function isValidRedisKeyComponent(value: string): boolean {
+  return redisKeyComponentPattern.test(value);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function currentPlayerId(): string | undefined {
+  const devvitContext = context as {
+    readonly userId?: string;
+  };
+
+  return devvitContext.userId;
+}
+
+async function currentDisplayName(fallbackDisplayName: string): Promise<string> {
+  try {
+    const username = await reddit.getCurrentUsername();
+
+    if (typeof username === 'string' && username.length > 0) {
+      return username;
+    }
+  } catch (error) {
+    console.warn(`devvit username lookup failed: ${errorMessage(error)}`);
+  }
+
+  return fallbackDisplayName;
+}
+
+function currentSubredditName(): string | undefined {
+  const devvitContext = context as {
+    readonly subredditName?: string;
+  };
+
+  return typeof devvitContext.subredditName === 'string' && devvitContext.subredditName.length > 0
+    ? devvitContext.subredditName
+    : undefined;
+}
+
+function optionalObjectPayload(payload: unknown): Record<string, unknown> {
+  if (typeof payload !== 'object' || payload === null) {
+    return {};
+  }
+
+  return payload as Record<string, unknown>;
+}
+
+function expressRequestToFetchRequest(request: ExpressRequest): Request {
+  const headers = new Headers();
+
+  for (const [key, value] of Object.entries(request.headers)) {
+    if (typeof value === 'string') {
+      headers.set(key, value);
+    } else if (Array.isArray(value)) {
+      headers.set(key, value.join(', '));
+    }
+  }
+
+  const init: RequestInit = {
+    method: request.method,
+    headers,
+  };
+
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    if (!headers.has('content-type')) {
+      headers.set('content-type', 'application/json');
+    }
+
+    init.body = requestBodyToBodyInit(request.body);
+  }
+
+  return new Request(expressRequestUrl(request), init);
+}
+
+function requestBodyToBodyInit(input: unknown): BodyInit {
+  if (input instanceof Uint8Array) {
+    const body = new Uint8Array(input.byteLength);
+    body.set(input);
+
+    return body.buffer as ArrayBuffer;
+  }
+
+  return JSON.stringify(input ?? null);
+}
+
+function expressRequestUrl(request: ExpressRequest): string {
+  const host = request.get('host') ?? 'localhost';
+  const protocol = request.protocol || 'https';
+
+  return `${protocol}://${host}${request.originalUrl}`;
+}
+
+async function sendFetchResponse(
+  response: ExpressResponse,
+  fetchResponse: Response,
+): Promise<void> {
+  fetchResponse.headers.forEach((value: string, key: string) => {
+    if (!expressManagedResponseHeaders.has(key.toLowerCase())) {
+      response.setHeader(key, value);
+    }
+  });
+
+  response.status(fetchResponse.status);
+  response.send(await fetchResponse.text());
+}

package/templates/phaser-game/apps/target-devvit/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "vite.server.config.ts"]
+}

package/templates/phaser-game/apps/target-devvit/vite.server.config.ts

@@ -0,0 +1,36 @@
+import { builtinModules } from 'node:module';
+
+import ttsc from '@ttsc/unplugin/vite';
+import { defineConfig } from 'vite';
+
+const externalBuiltins = [
+  ...builtinModules,
+  ...builtinModules.map((moduleName) => `node:${moduleName}`),
+];
+
+export default defineConfig({
+  plugins: [
+    ttsc({
+      project: 'tsconfig.json',
+      plugins: false,
+    }),
+  ],
+  ssr: {
+    noExternal: true,
+  },
+  build: {
+    ssr: 'src/server/index.ts',
+    outDir: 'dist/server',
+    target: 'node22',
+    sourcemap: false,
+    emptyOutDir: true,
+    rollupOptions: {
+      external: externalBuiltins,
+      output: {
+        format: 'cjs',
+        entryFileNames: 'index.cjs',
+        inlineDynamicImports: true,
+      },
+    },
+  },
+});

package/templates/phaser-game/gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+apps/*/dist/
+artifacts/
+release-output/
+.mpgd.targets.generated.json
+.env
+.env.*
+apps/*/.env
+.DS_Store
+*.log
+*.ait

package/templates/phaser-game/mpgd.targets.json

@@ -33,9 +33,9 @@
     "reddit": {
       "kind": "devvit-web",
       "gameApp": ".",
-      "wrapperApp": "${MPGD_KIT_PATH}/apps/target-devvit",
+      "wrapperApp": "apps/target-devvit",
       "adapter": "devvit",
-      "webDir": "${MPGD_KIT_PATH}/apps/target-devvit/dist/client",
+      "webDir": "apps/target-devvit/dist/client",
       "artifact": "devvit"
     }
   }

package/templates/phaser-game/package.json

@@ -7,6 +7,16 @@
   "scripts": {
     "dev": "__WORKSPACE_I18N_BUILD_PREFIX__vite --host 0.0.0.0",
     "build": "__WORKSPACE_I18N_BUILD_PREFIX__vite build",
+    "build:devvit": "pnpm exec mpgd target build reddit production --targets-file ./mpgd.targets.json --kit-path ${MPGD_KIT_PATH:-__DEFAULT_KIT_PATH__}",
+    "build:devvit:staging": "pnpm exec mpgd target build reddit staging --targets-file ./mpgd.targets.json --kit-path ${MPGD_KIT_PATH:-__DEFAULT_KIT_PATH__}",
+    "smoke:devvit": "pnpm exec mpgd target smoke reddit --targets-file ./mpgd.targets.json --kit-path ${MPGD_KIT_PATH:-__DEFAULT_KIT_PATH__}",
+    "devvit:init": "pnpm --dir apps/target-devvit run init",
+    "devvit:login": "pnpm --dir apps/target-devvit exec devvit login",
+    "devvit:login:copy-paste": "pnpm --dir apps/target-devvit exec devvit login --copy-paste",
+    "devvit:whoami": "pnpm --dir apps/target-devvit run whoami",
+    "devvit:upload": "pnpm --dir apps/target-devvit run upload",
+    "devvit:playtest": "pnpm --dir apps/target-devvit run dev",
+    "devvit:publish": "pnpm --dir apps/target-devvit run publish",
     "check": "ttsc --noEmit -p tsconfig.json",
     "lint": "ttsc --noEmit -p tsconfig.json",
     "format": "ttsc format",
@@ -26,6 +36,7 @@
     "phaser": "4.2.0"
   },
   "devDependencies": {
+    "@mpgd/cli": "__MPGD_DEPENDENCY_VERSION__",
     "@ttsc/unplugin": "0.16.9",
     "@types/node": "^24.0.0",
     "ttsc": "0.16.9",

package/templates/phaser-game/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+packages:
+  - '.'
+  - 'apps/*'
+__PNPM_WORKSPACE_KIT_PACKAGES__
+allowBuilds:
+  esbuild: true
+  protobufjs: true

package/templates/phaser-game/src/platform/installPlatform.ts

@@ -1,6 +1,6 @@
 import type { AdPlacements, ProductCatalog } from '@mpgd/catalog';
-import adPlacementsJson from '@mpgd/catalog/placements.json';
 import productCatalogJson from '@mpgd/catalog/catalog.json';
+import adPlacementsJson from '@mpgd/catalog/placements.json';
 import type { PlatformGateway } from '@mpgd/platform';
 import {
   createEffectiveTargetConfig,