@mpgd/cli 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@mpgd/cli",
+  "version": "0.1.0",
+  "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imjlk/mpgd-kit.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/imjlk/mpgd-kit/issues"
+  },
+  "homepage": "https://github.com/imjlk/mpgd-kit#readme",
+  "keywords": [
+    "mpgd",
+    "phaser",
+    "vite",
+    "typescript",
+    "capacitor",
+    "apps-in-toss",
+    "devvit",
+    "game-development",
+    "game-distribution",
+    "cli"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "bin": {
+    "mpgd": "./dist/bin.js"
+  },
+  "dependencies": {
+    "@gunshi/plugin-completion": "^0.35.1",
+    "@gunshi/plugin-i18n": "^0.35.1",
+    "@gunshi/resources": "^0.35.1",
+    "gunshi": "^0.35.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "ttsc": "0.16.9",
+    "typescript": "7.0.1-rc"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "ttsc --noEmit -p tsconfig.json",
+    "lint": "ttsc --noEmit -p tsconfig.json",
+    "format": "ttsc format",
+    "fix": "ttsc fix"
+  }
+}

package/templates/phaser-game/README.md

@@ -0,0 +1,66 @@
+# __GAME_TITLE__
+
+Standalone Phaser 4 game starter generated by `@mpgd/create-game`.
+
+## Local Loop
+
+```sh
+pnpm install
+pnpm dev
+pnpm check
+pnpm build
+```
+
+The starter keeps game code behind `PlatformGateway` and demonstrates:
+
+- target-aware adapter selection through `APP_TARGET`
+- target-config/effective-config runtime snapshots
+- local translation keys
+- optional `@mpgd/game-services` client wiring
+- best-effort analytics events
+- rewarded ad smoke action
+
+## Target Builds
+
+Target builds require an `mpgd-kit` checkout because the target wrappers live in
+the kit repository. Pass that checkout with `--kit-path`:
+
+```sh
+pnpm dlx @mpgd/cli target build-all \
+  --targets-file ./mpgd.targets.json \
+  --kit-path ../mpgd-kit \
+  --targets web,ait \
+  --ait-variant wrapper
+pnpm dlx @mpgd/cli target smoke-all \
+  --targets-file ./mpgd.targets.json \
+  --kit-path ../mpgd-kit \
+  --targets web,ait
+```
+
+When developing the kit itself, the same commands work through the repository
+script:
+
+```sh
+pnpm --dir ../mpgd-kit mpgd target build-all \
+  --targets-file "$PWD/mpgd.targets.json" \
+  --kit-path ../mpgd-kit \
+  --targets web,ait \
+  --ait-variant wrapper
+```
+
+`mpgd.targets.json` contains `${MPGD_KIT_PATH}` tokens. The CLI resolves them
+into `.mpgd.targets.generated.json` before calling the kit's existing target
+build and smoke scripts.
+
+## Game Services
+
+The backend client is disabled unless a backend URL is configured:
+
+```sh
+VITE_MPGD_GAME_SERVICES_URL=http://localhost:5173
+VITE_MPGD_GAME_SERVICES_TARGET=android
+VITE_MPGD_GAME_SERVICES_TRANSPORT=http
+```
+
+Use `VITE_MPGD_GAME_SERVICES_TRANSPORT=orpc` with a `/rpc` URL to test the oRPC
+client path.

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

@@ -0,0 +1,16 @@
+# Acceptance
+
+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
+```
+
+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`.

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

@@ -0,0 +1,20 @@
+# __GAME_TITLE__ Brief
+
+Build a Phaser 4 game on top of the mpgd platform boundary.
+
+Boundaries:
+
+- Phaser scenes render and collect input only.
+- Target services go through `PlatformGateway`.
+- Purchases, rewarded ad grants, and leaderboard records should go through
+  backend ledger APIs before mutating durable game save state.
+- Platform SDK imports belong in adapters or target wrappers.
+
+Useful commands:
+
+```sh
+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
+```

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

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": 1,
+  "game": {
+    "id": "__GAME_NAME__",
+    "title": "__GAME_TITLE__",
+    "engine": "phaser-4"
+  },
+  "targets": ["web-preview", "android", "ios", "ait", "reddit"],
+  "futureTargets": ["telegram", "tauri"],
+  "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."
+  },
+  "blocks": [
+    {
+      "id": "simulation.loop.phase",
+      "owner": "src/game/state.ts"
+    },
+    {
+      "id": "runtime.platform.gateway",
+      "owner": "src/platform/installPlatform.ts"
+    },
+    {
+      "id": "services.backend.game-services",
+      "owner": "src/platform/gameServices.ts"
+    },
+    {
+      "id": "localization.messages",
+      "owner": "src/i18n/messages.ts"
+    },
+    {
+      "id": "telemetry.analytics.best-effort",
+      "owner": "src/main.ts"
+    }
+  ],
+  "acceptance": [
+    "pnpm check",
+    "pnpm build"
+  ]
+}

package/templates/phaser-game/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__GAME_TITLE__</title>
+  </head>
+  <body>
+    <div id="game"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

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

@@ -0,0 +1,42 @@
+{
+  "targets": {
+    "web-preview": {
+      "kind": "web",
+      "gameApp": ".",
+      "adapter": "browser",
+      "output": "artifacts/web-preview"
+    },
+    "android": {
+      "kind": "capacitor-android",
+      "gameApp": ".",
+      "shellApp": "${MPGD_KIT_PATH}/apps/mobile-capacitor",
+      "adapter": "capacitor",
+      "webDir": "${MPGD_KIT_PATH}/apps/mobile-capacitor/www",
+      "artifact": "aab"
+    },
+    "ios": {
+      "kind": "capacitor-ios",
+      "gameApp": ".",
+      "shellApp": "${MPGD_KIT_PATH}/apps/mobile-capacitor",
+      "adapter": "capacitor",
+      "webDir": "${MPGD_KIT_PATH}/apps/mobile-capacitor/www",
+      "artifact": "ipa"
+    },
+    "ait": {
+      "kind": "apps-in-toss",
+      "gameApp": ".",
+      "wrapperApp": "${MPGD_KIT_PATH}/apps/target-ait",
+      "adapter": "ait",
+      "webDir": "${MPGD_KIT_PATH}/apps/target-ait/public/game",
+      "artifact": ".ait"
+    },
+    "reddit": {
+      "kind": "devvit-web",
+      "gameApp": ".",
+      "wrapperApp": "${MPGD_KIT_PATH}/apps/target-devvit",
+      "adapter": "devvit",
+      "webDir": "${MPGD_KIT_PATH}/apps/target-devvit/dist/client",
+      "artifact": "devvit"
+    }
+  }
+}

package/templates/phaser-game/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "private": true,
+  "version": "0.0.0",
+  "description": "__GAME_TITLE__ mpgd Phaser game.",
+  "type": "module",
+  "scripts": {
+    "dev": "__WORKSPACE_I18N_BUILD_PREFIX__vite --host 0.0.0.0",
+    "build": "__WORKSPACE_I18N_BUILD_PREFIX__vite build",
+    "check": "ttsc --noEmit -p tsconfig.json",
+    "lint": "ttsc --noEmit -p tsconfig.json",
+    "format": "ttsc format",
+    "fix": "ttsc fix"
+  },
+  "dependencies": {
+    "@mpgd/adapter-ait": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/adapter-browser": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/adapter-capacitor": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/adapter-devvit": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/analytics": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/catalog": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/game-services": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/i18n": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/platform": "__MPGD_DEPENDENCY_VERSION__",
+    "@mpgd/target-config": "__MPGD_DEPENDENCY_VERSION__",
+    "phaser": "4.2.0"
+  },
+  "devDependencies": {
+    "@ttsc/unplugin": "0.16.9",
+    "@types/node": "^24.0.0",
+    "ttsc": "0.16.9",
+    "typescript": "7.0.1-rc",
+    "vite": "^8.1.3"
+  }
+}

package/templates/phaser-game/src/env.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="vite/client" />
+
+declare const __APP_TARGET__: string;
+declare const __APP_VERSION__: string;
+declare const __BUILD_ID__: string;
+declare const __DEBUG_BUILD__: boolean;
+
+interface ImportMetaEnv {
+  readonly VITE_MPGD_GAME_SERVICES_URL?: string;
+  readonly VITE_MPGD_GAME_SERVICES_TARGET?: string;
+  readonly VITE_MPGD_GAME_SERVICES_TRANSPORT?: string;
+}

package/templates/phaser-game/src/game/state.ts

@@ -0,0 +1,29 @@
+const scoreIntervalMs = 100;
+const phasePeriodMs = 2400;
+
+export interface StarterRunState {
+  readonly elapsedMs: number;
+  readonly score: number;
+  readonly phase: number;
+}
+
+export function createStarterRunState(): StarterRunState {
+  return {
+    elapsedMs: 0,
+    score: 0,
+    phase: 0,
+  };
+}
+
+export function stepStarterRunState(
+  state: StarterRunState,
+  deltaMs: number,
+): StarterRunState {
+  const elapsedMs = state.elapsedMs + deltaMs;
+
+  return {
+    elapsedMs,
+    score: Math.floor(elapsedMs / scoreIntervalMs),
+    phase: (elapsedMs % phasePeriodMs) / phasePeriodMs,
+  };
+}

package/templates/phaser-game/src/i18n/messages.ts

@@ -0,0 +1,64 @@
+import type { Locale } from '@mpgd/i18n';
+
+export type GameMessageKey =
+  | 'title'
+  | 'target'
+  | 'backend'
+  | 'features'
+  | 'featuresNone'
+  | 'tapToStart'
+  | 'score'
+  | 'reward'
+  | 'rewardError'
+  | 'rewardPending'
+  | 'rewardUnavailable'
+  | 'analytics'
+  | 'bootError';
+
+const messages = {
+  en: {
+    title: '__GAME_TITLE__',
+    target: 'Target: {target}',
+    backend: 'Game Services: {mode}',
+    features: 'Features: {features}',
+    featuresNone: 'none',
+    tapToStart: 'Tap or press Enter to start',
+    score: 'Score {score}',
+    reward: 'Rewarded ad smoke: {status}',
+    rewardError: 'Rewarded ad smoke failed',
+    rewardPending: 'Press R to request a rewarded ad smoke',
+    rewardUnavailable: 'Rewarded ads unavailable on this target',
+    analytics: 'Analytics events: {count}',
+    bootError: 'Failed to start game',
+  },
+  ko: {
+    title: '__GAME_TITLE__',
+    target: '타깃: {target}',
+    backend: 'Game Services: {mode}',
+    features: '기능: {features}',
+    featuresNone: '없음',
+    tapToStart: '탭하거나 Enter를 눌러 시작',
+    score: '점수 {score}',
+    reward: '리워드 광고 스모크: {status}',
+    rewardError: '리워드 광고 스모크 실패',
+    rewardPending: 'R 키로 리워드 광고 스모크 요청',
+    rewardUnavailable: '이 타깃에서는 리워드 광고를 사용할 수 없음',
+    analytics: '애널리틱스 이벤트: {count}',
+    bootError: '게임 시작 실패',
+  },
+} satisfies Record<Locale, Record<GameMessageKey, string>>;
+
+export function t(
+  locale: Locale,
+  key: GameMessageKey,
+  values: Record<string, string | number> = {},
+): string {
+  const language = locale === 'ko' ? 'ko' : 'en';
+  let text: string = messages[language][key] ?? messages.en[key];
+
+  for (const [name, value] of Object.entries(values)) {
+    text = text.replaceAll(`{${name}}`, String(value));
+  }
+
+  return text;
+}

package/templates/phaser-game/src/main.ts

@@ -0,0 +1,78 @@
+import './styles.css';
+
+import { createAnalyticsReporter, createBufferedAnalyticsSink } from '@mpgd/analytics';
+import { resolveMpgdLocale, type Locale } from '@mpgd/i18n';
+
+import { t } from './i18n/messages';
+import { createClientId } from './runtime/id';
+import { createStarterGame } from './runtime/createGame';
+import { detectRuntime } from './platform/runtimeDetector';
+import { createStarterGameServices } from './platform/gameServices';
+import { installPlatform } from './platform/installPlatform';
+
+await bootstrap();
+
+async function bootstrap(): Promise<void> {
+  let locale: Locale = 'en';
+
+  try {
+    const runtimeConfig = detectRuntime();
+    const platform = await installPlatform(runtimeConfig);
+    const runtime = await platform.getTargetRuntime();
+    const player =
+      (await platform.identity.getPlayer()) ?? {
+        playerId: 'local-player',
+        displayName: 'Local Player',
+      };
+    locale = resolveMpgdLocale(runtime.capabilities);
+    const analyticsSink = createBufferedAnalyticsSink();
+    const analytics = createAnalyticsReporter({
+      target: platform.target,
+      sessionId: createClientId('session'),
+      sink: analyticsSink,
+    });
+    const gameServices = createStarterGameServices({
+      gateway: platform,
+      playerId: player.playerId,
+    });
+
+    await analytics.track({
+      name: 'game_started',
+      properties: {
+        target: platform.target,
+        configTarget: runtime.configTarget,
+      },
+    });
+
+    createStarterGame({
+      mountId: 'game',
+      context: {
+        platform,
+        runtime,
+        player,
+        locale,
+        gameServices,
+        analytics,
+        analyticsSink,
+      },
+    });
+  } catch (error) {
+    renderBootstrapError(error, locale);
+    console.error('[bootstrap]', error);
+  }
+}
+
+function renderBootstrapError(error: unknown, locale: Locale): void {
+  const message = error instanceof Error ? error.message : String(error);
+  const root = document.querySelector<HTMLDivElement>('#game');
+
+  if (root === null) {
+    return;
+  }
+
+  root.replaceChildren();
+  const panel = document.createElement('div');
+  panel.className = 'boot-error';
+  panel.textContent = `${t(locale, 'bootError')}: ${message}`;
+  root.append(panel);
+}

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

@@ -0,0 +1,70 @@
+import {
+  createGameServicesClient,
+  createGameServicesFetchBackendTransport,
+  createGameServicesHttpBackendApi,
+  createGameServicesOrpcBackendApi,
+  createGameServicesOrpcClient,
+  type GameServicesClient,
+  type GameServicesStoreTarget,
+} from '@mpgd/game-services';
+import type { PlatformGateway, PlatformTarget } from '@mpgd/platform';
+
+export type StarterBackendMode = 'disabled' | 'http' | 'orpc';
+
+export interface StarterGameServices {
+  readonly mode: StarterBackendMode;
+  readonly baseUrl?: string;
+  readonly target?: GameServicesStoreTarget;
+  readonly client?: GameServicesClient;
+}
+
+export function createStarterGameServices(input: {
+  readonly gateway: PlatformGateway;
+  readonly playerId: string;
+}): StarterGameServices {
+  const baseUrl = import.meta.env.VITE_MPGD_GAME_SERVICES_URL;
+  const requestedMode = import.meta.env.VITE_MPGD_GAME_SERVICES_TRANSPORT;
+  const storeTarget = readStoreTarget(
+    import.meta.env.VITE_MPGD_GAME_SERVICES_TARGET ?? input.gateway.target,
+  );
+
+  if (baseUrl === undefined || baseUrl.length === 0 || storeTarget === null) {
+    return {
+      mode: 'disabled',
+    };
+  }
+
+  const mode = requestedMode === 'orpc' ? 'orpc' : 'http';
+  const backend =
+    mode === 'orpc'
+      ? createGameServicesOrpcBackendApi(
+          createGameServicesOrpcClient({
+            url: baseUrl,
+          }),
+        )
+      : createGameServicesHttpBackendApi({
+          transport: createGameServicesFetchBackendTransport({
+            baseUrl,
+          }),
+        });
+
+  return {
+    mode,
+    baseUrl,
+    target: storeTarget,
+    client: createGameServicesClient({
+      gateway: input.gateway,
+      backend,
+      playerId: input.playerId,
+      target: storeTarget,
+    }),
+  };
+}
+
+function readStoreTarget(target: PlatformTarget | string): GameServicesStoreTarget | null {
+  if (target === 'android' || target === 'ios' || target === 'ait') {
+    return target;
+  }
+
+  return null;
+}

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

@@ -0,0 +1,96 @@
+import type { AdPlacements, ProductCatalog } from '@mpgd/catalog';
+import adPlacementsJson from '@mpgd/catalog/placements.json';
+import productCatalogJson from '@mpgd/catalog/catalog.json';
+import type { PlatformGateway } from '@mpgd/platform';
+import {
+  createEffectiveTargetConfig,
+  getTargetConfig,
+  targetConfigKeyForPlatform,
+  withTargetAvailability,
+  type TargetConfigMatrix,
+  type TargetConfiguredGateway,
+} from '@mpgd/target-config';
+import targetConfigMatrixJson from '@mpgd/target-config/targets.json';
+
+import type { RuntimeConfig } from './runtimeDetector';
+
+const devvitSandboxBuildId = 'devvit-sandbox';
+const targetConfigMatrix = targetConfigMatrixJson as TargetConfigMatrix;
+const productCatalog = productCatalogJson as ProductCatalog;
+const adPlacements = adPlacementsJson as AdPlacements;
+const targetAdPlacements = adPlacements.placements.map((placement) => ({
+  id: placement.id,
+  type: placement.type,
+}));
+const adPlacementTypes = new Map<string, 'rewarded' | 'interstitial'>(
+  targetAdPlacements.map((placement) => [placement.id, placement.type]),
+);
+
+export async function installPlatform(runtime: RuntimeConfig): Promise<TargetConfiguredGateway> {
+  let gateway: PlatformGateway;
+
+  switch (runtime.target) {
+    case 'android':
+    case 'ios': {
+      const { createCapacitorPlatformGateway } = await import('@mpgd/adapter-capacitor');
+      gateway = createCapacitorPlatformGateway({
+        target: runtime.target,
+        appVersion: runtime.appVersion,
+        buildId: runtime.buildId,
+      });
+      break;
+    }
+
+    case 'ait': {
+      const { createAitPlatformGateway, createAitSandboxBridge } = await import(
+        '@mpgd/adapter-ait'
+      );
+      gateway = createAitPlatformGateway({
+        appVersion: runtime.appVersion,
+        buildId: runtime.buildId,
+        ...(runtime.debug ? { fallbackBridge: createAitSandboxBridge() } : {}),
+      });
+      break;
+    }
+
+    case 'reddit': {
+      const { createDevvitPlatformGateway, createDevvitSandboxBridge } = await import(
+        '@mpgd/adapter-devvit'
+      );
+      gateway = createDevvitPlatformGateway({
+        appVersion: runtime.appVersion,
+        buildId: runtime.buildId,
+        ...(shouldUseDevvitSandbox(runtime) ? { fallbackBridge: createDevvitSandboxBridge() } : {}),
+      });
+      break;
+    }
+
+    default: {
+      const { createBrowserPlatformGateway } = await import('@mpgd/adapter-browser');
+      gateway = createBrowserPlatformGateway();
+    }
+  }
+
+  const configTarget = targetConfigKeyForPlatform(runtime.target);
+  const targetConfig = getTargetConfig(targetConfigMatrix, configTarget);
+  const effectiveConfig = createEffectiveTargetConfig({
+    target: configTarget,
+    targetConfigVersion: targetConfigMatrix.version,
+    config: targetConfig,
+    catalog: productCatalog,
+    adPlacements,
+  });
+
+  return withTargetAvailability(gateway, targetConfig, {
+    configTarget,
+    effectiveConfig,
+    adPlacements: targetAdPlacements,
+    resolveAdPlacementType(placementId) {
+      return adPlacementTypes.get(placementId);
+    },
+  });
+}
+
+function shouldUseDevvitSandbox(runtime: RuntimeConfig): boolean {
+  return runtime.debug && runtime.buildId === devvitSandboxBuildId;
+}

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

@@ -0,0 +1,30 @@
+import type { PlatformTarget } from '@mpgd/platform';
+
+const validTargets = new Set<string>([
+  'android',
+  'ios',
+  'ait',
+  'reddit',
+  'telegram',
+  'tauri',
+] satisfies readonly PlatformTarget[]);
+
+export interface RuntimeConfig {
+  readonly target: PlatformTarget;
+  readonly appVersion: string;
+  readonly buildId: string;
+  readonly debug: boolean;
+}
+
+export function detectRuntime(): RuntimeConfig {
+  return {
+    target: normalizeTarget(__APP_TARGET__),
+    appVersion: __APP_VERSION__,
+    buildId: __BUILD_ID__,
+    debug: __DEBUG_BUILD__,
+  };
+}
+
+export function normalizeTarget(value: string): PlatformTarget {
+  return validTargets.has(value) ? (value as PlatformTarget) : 'browser';
+}