@playporter/cli 0.3.0

package/src/index.ts

@@ -0,0 +1,723 @@
+#!/usr/bin/env node
+import { createHash, generateKeyPairSync, sign as signDetached } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import process from "node:process";
+import archiver from "archiver";
+import { Command } from "commander";
+import fs from "fs-extra";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import type { ArtifactFileEntry, ArtifactManifest, ArtifactSignature, PlayPorterConfig, PublicPlatform, ValidationReportData } from "@playporter/core";
+import { validateBundle } from "@playporter/validator";
+
+const program = new Command();
+program.name("playporter").description("Build locally. Launch socially. Operate everywhere.").version("0.2.0");
+
+program.command("init")
+  .description("Create playporter.yml and an SDK bootstrap example")
+  .option("--force", "overwrite existing files")
+  .option("--json", "emit playporter.config.json instead of playporter.yml")
+  .action(async ({ force, json }: { force?: boolean; json?: boolean }) => {
+    const useYaml = !json;
+    const configPath = path.resolve(useYaml ? "playporter.yml" : "playporter.config.json");
+    if (await fs.pathExists(configPath) && !force) throw new Error(`${path.basename(configPath)} already exists; use --force to replace it.`);
+    const packageJson = await readPackageJson();
+    const slug = slugify(packageJson.name ?? path.basename(process.cwd()));
+    const config: PlayPorterConfig = {
+      schemaVersion: 1,
+      game: { slug, name: packageJson.name ?? slug, version: packageJson.version ?? "0.2.0" },
+      build: { command: "npm run build", output: "dist" },
+      api: { baseUrl: "http://localhost:3000", projectKeyEnv: "PLAYPORTER_PROJECT_KEY" },
+      platforms: {
+        discord: { enabled: true, clientId: "", urlMappings: [] },
+        telegram: { enabled: true, botUsername: "" },
+        reddit: { enabled: true, appName: redditName(slug), subreddit: `${slug}_dev`, postTitle: packageJson.name ?? "PlayPorter Game" },
+      },
+      services: {
+        auth: { primary: "playporter" },
+        saves: { primary: "playporter" },
+        payments: { primary: "playporter" },
+        analytics: { primary: "playporter" },
+      },
+    };
+    if (useYaml) {
+      await writeFile(configPath, yamlHeader() + stringifyYaml(config, { indent: 2 }), "utf8");
+    } else {
+      await writeJson(configPath, config);
+    }
+    const samplePath = path.resolve("playporter.bootstrap.example.ts");
+    if (!(await fs.pathExists(samplePath)) || force) await writeFile(samplePath, bootstrapExample(), "utf8");
+    console.log(`Created ${path.relative(process.cwd(), configPath)} and ${path.basename(samplePath)}.`);
+  });
+
+program.command("build")
+  .description("Run the configured local build without uploading source code")
+  .option("-c, --config <path>", "config file (default: playporter.yml or playporter.config.json)")
+  .option("--skip-validate", "do not validate after build")
+  .action(async ({ config: configPath, skipValidate }: { config?: string; skipValidate?: boolean }) => {
+    const config = await loadConfig(configPath);
+    console.log(`Running locally: ${config.build.command}`);
+    await runShell(config.build.command);
+    if (!skipValidate) {
+      const report = await validateBundle({ bundlePath: config.build.output, config });
+      printReport(report);
+      if (!report.passed) process.exitCode = 2;
+    }
+  });
+
+program.command("validate")
+  .description("Validate the compiled bundle for Discord, Telegram and Reddit")
+  .option("-c, --config <path>", "config file (default: playporter.yml or playporter.config.json)")
+  .option("--upload", "send only the validation report to PlayPorter Studio")
+  .action(async ({ config: configPath, upload }: { config?: string; upload?: boolean }) => {
+    const config = await loadConfig(configPath);
+    const report = await validateBundle({ bundlePath: config.build.output, config });
+    printReport(report);
+    await fs.ensureDir(".playporter");
+    await writeJson(path.resolve(".playporter/validation-report.json"), report);
+    if (upload) await uploadReport(config, report);
+    if (!report.passed) process.exitCode = 2;
+  });
+
+program.command("artifact")
+  .description("Generate a signed .playporter artifact from the compiled bundle")
+  .option("-c, --config <path>", "config file (default: playporter.yml or playporter.config.json)")
+  .option("-o, --output <path>", "artifact path")
+  .action(async ({ config: configPath, output }: { config?: string; output?: string }) => {
+    const config = await loadConfig(configPath);
+    const report = await validateBundle({ bundlePath: config.build.output, config });
+    printReport(report);
+    if (!report.passed) throw new Error("Artifact generation stopped because validation contains errors.");
+    const artifactPath = path.resolve(output ?? `${config.game.slug}-${config.game.version}.playporter`);
+    const artifact = await createSignedArtifact(config, report, artifactPath);
+    console.log(`Signed artifact created: ${artifactPath}`);
+    console.log(`Manifest SHA-256: ${artifact.signature.manifestSha256}`);
+    console.log("PlayPorter can validate and distribute this artifact without access to your source code.");
+  });
+
+program.command("package")
+  .description("Generate platform-specific deployable packages from the compiled bundle")
+  .option("-c, --config <path>", "config file (default: playporter.yml or playporter.config.json)")
+  .option("-p, --platform <name>", "discord, telegram, reddit or all", "all")
+  .option("-o, --output <path>", "output directory", "playporter-output")
+  .option("--zip", "also create zip archives")
+  .action(async (options: { config?: string; platform: string; output: string; zip?: boolean }) => {
+    const config = await loadConfig(options.config);
+    const report = await validateBundle({ bundlePath: config.build.output, config });
+    printReport(report);
+    if (!report.passed) throw new Error("Packaging stopped because validation contains errors.");
+    const platforms = resolvePlatforms(options.platform, config);
+    const root = path.resolve(options.output, `${config.game.slug}-${config.game.version}`);
+    await fs.emptyDir(root);
+    const artifact = await createSignedArtifact(config, report, path.join(root, `${config.game.slug}-${config.game.version}.playporter`));
+    for (const platform of platforms) {
+      const destination = path.join(root, platform);
+      if (platform === "reddit") await generateRedditPackage(config, destination, report);
+      else await generateHostedPackage(platform, config, destination, report);
+      await writeJson(path.join(destination, "playporter-artifact.json"), {
+        artifactId: artifact.manifest.artifactId,
+        manifestSha256: artifact.signature.manifestSha256,
+        publicKeyPem: artifact.signature.publicKeyPem,
+        sourceCodeIncluded: false,
+      });
+      if (options.zip) await zipDirectory(destination, `${destination}.zip`);
+      console.log(`Generated ${platform}: ${destination}`);
+    }
+    console.log("Only compiled assets and deployment metadata were packaged; source files were not copied.");
+  });
+
+// ─── playporter login ─────────────────────────────────────────────────────────
+
+program.command("login")
+  .description("Authenticate the CLI with PlayPorter Studio")
+  .option("-c, --config <path>", "config file (default: playporter.yml)")
+  .option("--url <studio-url>", "Studio base URL (overrides config)")
+  .action(async (options: { config?: string; url?: string }) => {
+    const config = await loadConfig(options.config).catch(() => null);
+    const studioUrl = (options.url ?? config?.api.baseUrl ?? "https://studio.playporter.net").replace(/\/$/, "");
+
+    const readline = await import("node:readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q: string) => new Promise<string>((resolve) => rl.question(q, resolve));
+
+    console.log(`\nLogging in to ${studioUrl}\n`);
+    const email    = await ask("Email: ");
+    const password = await ask("Password: ");
+    rl.close();
+
+    const res = await fetch(`${studioUrl}/api/v1/admin/cli/auth`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: email.trim(), password }),
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({})) as { error?: string };
+      throw new Error(`Login failed: ${err.error ?? res.statusText}`);
+    }
+
+    const data = await res.json() as { token: string; email: string; name: string };
+    const credDir  = path.join(homedir(), ".config", "playporter");
+    const credPath = path.join(credDir, "credentials.json");
+    await mkdir(credDir, { recursive: true });
+    await writeFile(credPath, JSON.stringify({ studioUrl, token: data.token, email: data.email, name: data.name }, null, 2), "utf8");
+
+    console.log(`\n✓ Logged in as ${data.name ?? data.email}`);
+    console.log(`  Credentials saved to ${credPath}`);
+    console.log(`  Run \`playporter deploy\` to deploy your game.\n`);
+  });
+
+// ─── playporter deploy ────────────────────────────────────────────────────────
+
+program.command("deploy")
+  .description("Build, package and auto-deploy to all configured platforms via PlayPorter Studio")
+  .option("-c, --config <path>", "config file")
+  .option("--skip-build", "skip the build step (use existing output directory)")
+  .option("-p, --platforms <list>", "comma-separated platform list (default: all enabled + web)")
+  .action(async (options: { config?: string; skipBuild?: boolean; platforms?: string }) => {
+    const config  = await loadConfig(options.config);
+    const apiBase = config.api.baseUrl.replace(/\/$/, "");
+
+    // Load credentials from ~/.config/playporter/credentials.json
+    const credPath = path.join(homedir(), ".config", "playporter", "credentials.json");
+    let adminToken: string | null = null;
+    try {
+      const creds = JSON.parse(await readFile(credPath, "utf8")) as { token?: string; studioUrl?: string };
+      if (creds.studioUrl && creds.studioUrl !== apiBase) {
+        console.warn(`Warning: credentials were created for ${creds.studioUrl} but config uses ${apiBase}.`);
+      }
+      adminToken = creds.token ?? null;
+    } catch {
+      throw new Error("Not logged in. Run `playporter login` first.");
+    }
+
+    const headers: Record<string, string> = { Authorization: `Bearer ${adminToken}` };
+
+    // 1. Build
+    if (!options.skipBuild && config.build.command) {
+      console.log(`\n▸ Building: ${config.build.command}`);
+      await runShell(config.build.command);
+    }
+
+    // 2. Validate + upload
+    console.log("▸ Validating bundle...");
+    const report = await validateBundle({ bundlePath: config.build.output, config });
+    printReport(report);
+    if (!report.passed) throw new Error("Validation failed. Fix the issues above before deploying.");
+
+    const projectKey = process.env[config.api.projectKeyEnv];
+    if (projectKey) await uploadReport(config, report);
+
+    // 3. Package into temp ZIPs
+    const tmpDir = `/tmp/pp-deploy-${Date.now()}`;
+    await fs.ensureDir(tmpDir);
+
+    const allPlatforms: string[] = options.platforms
+      ? options.platforms.split(",").map((p) => p.trim()).filter(Boolean)
+      : [...resolvePlatforms("all", config), "web"];
+
+    console.log(`\n▸ Packaging: ${allPlatforms.join(", ")}`);
+
+    const artifactIds: Record<string, string> = {};
+
+    for (const platform of allPlatforms) {
+      const dest = path.join(tmpDir, platform);
+      if (platform === "web") {
+        await zipDirectory(path.resolve(config.build.output), `${dest}.zip`);
+      } else if (platform === "reddit") {
+        await generateRedditPackage(config, dest, report);
+        await zipDirectory(dest, `${dest}.zip`);
+      } else {
+        await generateHostedPackage(platform as "discord" | "telegram", config, dest, report);
+        await zipDirectory(dest, `${dest}.zip`);
+      }
+      artifactIds[platform] = await uploadArtifactFile(`${dest}.zip`, apiBase, headers);
+      console.log(`  ✓ ${platform} packaged and uploaded`);
+    }
+
+    // 4. Execute deploy via SSE
+    const params = new URLSearchParams({ platforms: allPlatforms.join(",") });
+    for (const [plat, id] of Object.entries(artifactIds)) params.set(plat, id);
+
+    console.log("\n▸ Deploying to all platforms...\n");
+    await streamDeployProgress(`${apiBase}/api/v1/deploy/execute?${params}`, headers);
+
+    // Cleanup
+    await fs.remove(tmpDir).catch(() => null);
+  });
+
+async function uploadArtifactFile(
+  zipPath: string,
+  apiBase: string,
+  headers: Record<string, string>
+): Promise<string> {
+  const fileBytes = await readFile(zipPath);
+  const form = new FormData();
+  form.append("file", new Blob([fileBytes], { type: "application/zip" }), path.basename(zipPath));
+  const res = await fetch(`${apiBase}/api/v1/deploy/artifact`, {
+    method: "POST",
+    headers,
+    body: form,
+  });
+  if (!res.ok) throw new Error(`Artifact upload failed (${res.status}): ${await res.text()}`);
+  const data = await res.json() as { artifactId: string };
+  return data.artifactId;
+}
+
+async function streamDeployProgress(url: string, headers: Record<string, string>): Promise<void> {
+  const res = await fetch(url, { headers: { ...headers, Accept: "text/event-stream" } });
+  if (!res.ok || !res.body) throw new Error(`Deploy request failed (${res.status}): ${await res.text()}`);
+
+  const decoder = new TextDecoder();
+  const reader  = res.body.getReader();
+  let buf = "";
+  let allOk = false;
+
+  const PLATFORM_ICON: Record<string, string> = {
+    web: "🌐", discord: "💬", telegram: "📱", reddit: "🔴",
+  };
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.split("\n");
+    buf = lines.pop() ?? "";
+    let event = "";
+    for (const line of lines) {
+      if (line.startsWith("event: ")) { event = line.slice(7).trim(); continue; }
+      if (!line.startsWith("data: "))  continue;
+      const data = JSON.parse(line.slice(6)) as Record<string, unknown>;
+      if (event.includes(":started")) {
+        const plat = event.split(":")[1];
+        const icon = PLATFORM_ICON[plat] ?? "▸";
+        process.stdout.write(`  ${icon} Deploying ${plat}...`);
+      } else if (event.includes(":success")) {
+        const plat = event.split(":")[1];
+        const u    = (data as { url?: string }).url;
+        process.stdout.write(`\r  ✓ ${plat} deployed${u ? ` → ${u}` : ""}\n`);
+      } else if (event.includes(":error")) {
+        const plat = event.split(":")[1];
+        process.stdout.write(`\r  ✗ ${plat} failed: ${(data as { error?: string }).error ?? "unknown error"}\n`);
+      } else if (event === "deploy:complete") {
+        allOk = (data as { success?: boolean }).success === true;
+      }
+    }
+  }
+
+  console.log(allOk ? "\n✓ Deployment complete." : "\n⚠ Deployment finished with errors.");
+}
+
+program.parseAsync().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});
+
+async function loadConfig(configPath?: string): Promise<PlayPorterConfig> {
+  const resolved = await resolveConfigPath(configPath);
+  const raw = await readFile(resolved, "utf8");
+  const config = /\.(yml|yaml)$/i.test(resolved)
+    ? (parseYaml(raw) as PlayPorterConfig)
+    : (JSON.parse(raw) as PlayPorterConfig);
+  if (config.schemaVersion !== 1) throw new Error(`Unsupported schemaVersion in ${path.basename(resolved)}.`);
+  return config;
+}
+
+async function resolveConfigPath(explicit?: string): Promise<string> {
+  if (explicit) return path.resolve(explicit);
+  for (const candidate of ["playporter.yml", "playporter.yaml", "playporter.config.json"]) {
+    const abs = path.resolve(candidate);
+    if (await fs.pathExists(abs)) return abs;
+  }
+  throw new Error("No config file found. Run `playporter init` to create one.");
+}
+
+async function readPackageJson(): Promise<{ name?: string; version?: string; scripts?: Record<string, string> }> {
+  try { return JSON.parse(await readFile(path.resolve("package.json"), "utf8")); }
+  catch { return {}; }
+}
+
+async function runShell(command: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(command, { shell: true, stdio: "inherit", env: process.env });
+    child.on("error", reject);
+    child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`Build command exited with code ${code}`)));
+  });
+}
+
+function resolvePlatforms(value: string, config: PlayPorterConfig): PublicPlatform[] {
+  const enabled = (["discord", "telegram", "reddit"] as const).filter((platform) => config.platforms[platform]?.enabled);
+  if (value === "all") return enabled;
+  if (!enabled.includes(value as PublicPlatform)) throw new Error(`Platform '${value}' is not enabled.`);
+  return [value as PublicPlatform];
+}
+
+async function generateHostedPackage(
+  platform: "discord" | "telegram",
+  config: PlayPorterConfig,
+  destination: string,
+  report: ValidationReportData,
+): Promise<void> {
+  const appDir = path.join(destination, "app");
+  await fs.copy(path.resolve(config.build.output), appDir, { filter: sourceFilter });
+  await injectRuntime(appDir, platform, config);
+  await writeJson(path.join(destination, "playporter.deployment.json"), {
+    schemaVersion: 1,
+    platform,
+    game: config.game,
+    bundleHash: report.bundleHash,
+    generatedAt: new Date().toISOString(),
+    sourceCodeIncluded: false,
+  });
+  if (platform === "discord") {
+    await writeJson(path.join(destination, "discord.activity.json"), {
+      clientId: config.platforms.discord?.clientId,
+      root: "app/index.html",
+      urlMappings: config.platforms.discord?.urlMappings ?? [],
+      requiredScopes: ["identify"],
+    });
+    await writeFile(path.join(destination, "README_DEPLOY.md"), discordReadme(config), "utf8");
+  } else {
+    await writeJson(path.join(destination, "telegram.mini-app.json"), {
+      botUsername: config.platforms.telegram?.botUsername,
+      root: "app/index.html",
+    });
+    await writeFile(path.join(destination, "README_DEPLOY.md"), telegramReadme(config), "utf8");
+  }
+}
+
+async function generateRedditPackage(config: PlayPorterConfig, destination: string, report: ValidationReportData): Promise<void> {
+  const clientDir = path.join(destination, "src/client");
+  const serverDir = path.join(destination, "src/server");
+  await fs.ensureDir(serverDir);
+  await fs.copy(path.resolve(config.build.output), clientDir, { filter: sourceFilter });
+  await injectRuntime(clientDir, "reddit", config);
+  const apiHost = new URL(config.api.baseUrl).hostname;
+  const devvitJson = {
+    $schema: "https://developers.reddit.com/schema/config-file.v1.json",
+    name: config.platforms.reddit?.appName ?? redditName(config.game.slug),
+    post: { dir: "dist/client", entrypoints: { default: { entry: "index.html", height: "tall" } } },
+    server: { dir: "dist/server", entry: "index.cjs" },
+    permissions: {
+      reddit: { enable: true },
+      http: { enable: true, domains: [apiHost] },
+    },
+    settings: {
+      global: {
+        playporterDeploySecret: { type: "string", label: "PlayPorter deploy secret", isSecret: true },
+      },
+    },
+    menu: {
+      items: [{
+        label: "Create PlayPorter game post",
+        description: `Create a ${config.game.name} interactive post`,
+        location: "subreddit",
+        forUserType: "moderator",
+        endpoint: "/internal/menu/create-post",
+      }],
+    },
+    scripts: { dev: "vite build --watch", build: "vite build" },
+    dev: config.platforms.reddit?.subreddit ? { subreddit: config.platforms.reddit.subreddit } : undefined,
+  };
+  await writeJson(path.join(destination, "devvit.json"), devvitJson);
+  await writeJson(path.join(destination, "package.json"), {
+    name: `${config.game.slug}-reddit`,
+    version: config.game.version,
+    private: true,
+    type: "module",
+    scripts: {
+      build: "vite build",
+      dev: "devvit playtest",
+      launch: "devvit upload",
+      "settings:set": "devvit settings set playporterDeploySecret",
+    },
+    dependencies: { "@devvit/web": "^0.13.4", express: "^5.1.0" },
+    devDependencies: {
+      "@devvit/start": "^0.13.4",
+      "@types/express": "^5.0.3",
+      devvit: "^0.13.4",
+      typescript: "^5.9.3",
+      vite: "^7.1.12",
+    },
+  });
+  await writeFile(path.join(destination, "vite.config.ts"), `import { defineConfig } from "vite";\nimport { devvit } from "@devvit/start/vite";\nexport default defineConfig({ plugins: [devvit()] });\n`, "utf8");
+  await writeFile(path.join(serverDir, "index.ts"), redditServerSource(config), "utf8");
+  await writeJson(path.join(destination, "playporter.deployment.json"), {
+    schemaVersion: 1,
+    platform: "reddit",
+    game: config.game,
+    bundleHash: report.bundleHash,
+    generatedAt: new Date().toISOString(),
+    sourceCodeIncluded: false,
+  });
+  await writeFile(path.join(destination, "README_DEPLOY.md"), redditReadme(config), "utf8");
+}
+
+async function injectRuntime(appDir: string, platform: PublicPlatform, config: PlayPorterConfig): Promise<void> {
+  const indexPath = path.join(appDir, "index.html");
+  if (!(await fs.pathExists(indexPath))) throw new Error(`Missing ${indexPath}`);
+  const runtime = `window.__PLAYPORTER_RUNTIME__=${JSON.stringify({
+    platform,
+    apiBaseUrl: config.api.baseUrl,
+    environment: "production",
+    gameSlug: config.game.slug,
+    gameVersion: config.game.version,
+    discordClientId: config.platforms.discord?.clientId ?? null,
+  })};\n`;
+  await writeFile(path.join(appDir, "playporter-runtime.js"), runtime, "utf8");
+  let html = await readFile(indexPath, "utf8");
+  if (!html.includes("playporter-runtime.js")) {
+    const tag = '<script src="./playporter-runtime.js"></script>';
+    html = html.includes("</head>") ? html.replace("</head>", `${tag}\n</head>`) : `${tag}\n${html}`;
+    await writeFile(indexPath, html, "utf8");
+  }
+}
+
+async function uploadReport(config: PlayPorterConfig, report: ValidationReportData): Promise<void> {
+  const projectKey = process.env[config.api.projectKeyEnv];
+  if (!projectKey) throw new Error(`Environment variable ${config.api.projectKeyEnv} is required for --upload.`);
+  const response = await fetch(`${config.api.baseUrl.replace(/\/$/, "")}/api/v1/validator/reports`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-playporter-game-key": projectKey },
+    body: JSON.stringify({
+      bundleHash: report.bundleHash,
+      version: config.game.version,
+      passed: report.passed,
+      totalBytes: report.totalBytes,
+      fileCount: report.fileCount,
+      platforms: report.platforms,
+      issues: report.issues,
+    }),
+  });
+  if (!response.ok) throw new Error(`Report upload failed (${response.status}): ${await response.text()}`);
+  console.log("Validation report uploaded to PlayPorter Studio.");
+}
+
+async function createSignedArtifact(
+  config: PlayPorterConfig,
+  report: ValidationReportData,
+  artifactPath: string,
+): Promise<{ manifest: ArtifactManifest; signature: ArtifactSignature }> {
+  const bundleRoot = path.resolve(config.build.output);
+  const files = await collectArtifactFiles(bundleRoot);
+  const manifest: ArtifactManifest = {
+    schemaVersion: 1,
+    artifactId: createHash("sha256").update(`${config.game.slug}:${config.game.version}:${report.bundleHash}`).digest("hex").slice(0, 24),
+    game: config.game,
+    createdAt: new Date().toISOString(),
+    builder: {
+      cliVersion: program.version() ?? "0.2.0",
+      nodeVersion: process.version,
+      platform: process.platform,
+    },
+    bundle: {
+      root: "build",
+      entry: "build/index.html",
+      totalBytes: report.totalBytes,
+      fileCount: report.fileCount,
+      sha256: report.bundleHash,
+    },
+    validation: {
+      passed: report.passed,
+      platforms: report.platforms,
+      issueCount: report.issues.length,
+    },
+    claims: {
+      sourceCodeIncluded: false,
+      localCompilation: true,
+      studioControlledRelease: true,
+    },
+    files,
+  };
+  const manifestJson = `${JSON.stringify(manifest, null, 2)}\n`;
+  const manifestSha256 = createHash("sha256").update(manifestJson).digest("hex");
+  const { privateKeyPem, publicKeyPem } = await ensureArtifactKeyPair(config.game.slug);
+  const signature: ArtifactSignature = {
+    algorithm: "ed25519",
+    publicKeyPem,
+    signatureBase64: signDetached(null, Buffer.from(manifestJson, "utf8"), privateKeyPem).toString("base64"),
+    signedAt: new Date().toISOString(),
+    manifestSha256,
+  };
+
+  await fs.ensureDir(path.dirname(artifactPath));
+  await new Promise<void>((resolve, reject) => {
+    const output = createWriteStream(artifactPath);
+    const archive = archiver("zip", { zlib: { level: 9 } });
+    output.on("close", resolve);
+    output.on("error", reject);
+    archive.on("error", reject);
+    archive.pipe(output);
+    archive.directory(bundleRoot, "build");
+    archive.append(manifestJson, { name: "playporter-manifest.json" });
+    archive.append(`${JSON.stringify(signature, null, 2)}\n`, { name: "integrity-signature.json" });
+    archive.append(`${JSON.stringify({ generatedAt: new Date().toISOString(), sourceCodeIncluded: false }, null, 2)}\n`, { name: "assets/release-metadata.json" });
+    void archive.finalize();
+  });
+
+  await fs.ensureDir(".playporter");
+  await writeJson(path.resolve(".playporter/latest-artifact-manifest.json"), manifest);
+  await writeJson(path.resolve(".playporter/latest-artifact-signature.json"), signature);
+  return { manifest, signature };
+}
+
+async function collectArtifactFiles(bundleRoot: string): Promise<ArtifactFileEntry[]> {
+  const entries = await fs.readdir(bundleRoot, { recursive: true } as any) as string[];
+  const files: ArtifactFileEntry[] = [];
+  for (const entry of entries) {
+    const relative = String(entry).replaceAll(path.sep, "/");
+    const absolute = path.join(bundleRoot, relative);
+    if (!(await fs.stat(absolute)).isFile()) continue;
+    const content = await readFile(absolute);
+    files.push({
+      path: `build/${relative}`,
+      bytes: content.byteLength,
+      sha256: createHash("sha256").update(content).digest("hex"),
+      role: relative === "index.html" ? "entry" : relative.startsWith("assets/") ? "asset" : "runtime",
+    });
+  }
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+async function ensureArtifactKeyPair(slug: string): Promise<{ privateKeyPem: string; publicKeyPem: string }> {
+  const keyDir = path.resolve(".playporter/keys");
+  const privateKeyPath = path.join(keyDir, `${slug}.private.pem`);
+  const publicKeyPath = path.join(keyDir, `${slug}.public.pem`);
+  if (await fs.pathExists(privateKeyPath) && await fs.pathExists(publicKeyPath)) {
+    return {
+      privateKeyPem: await readFile(privateKeyPath, "utf8"),
+      publicKeyPem: await readFile(publicKeyPath, "utf8"),
+    };
+  }
+  await fs.ensureDir(keyDir);
+  const generated = generateKeyPairSync("ed25519");
+  const privateKeyPem = generated.privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+  const publicKeyPem = generated.publicKey.export({ format: "pem", type: "spki" }).toString();
+  await writeFile(privateKeyPath, privateKeyPem, "utf8");
+  await writeFile(publicKeyPath, publicKeyPem, "utf8");
+  return { privateKeyPem, publicKeyPem };
+}
+
+function printReport(report: ValidationReportData): void {
+  console.log(`\nValidation ${report.passed ? "PASSED" : "FAILED"} · ${report.fileCount} files · ${formatBytes(report.totalBytes)}`);
+  if (report.bundleHash) console.log(`Bundle SHA-256: ${report.bundleHash}`);
+  for (const item of report.issues) {
+    console.log(`[${item.severity.toUpperCase()}] ${item.platform}/${item.code}: ${item.message}${item.file ? ` (${item.file})` : ""}`);
+    if (item.remediation) console.log(`  Fix: ${item.remediation}`);
+  }
+  if (report.issues.length === 0) console.log("No compatibility issues detected.");
+  console.log("");
+}
+
+async function zipDirectory(source: string, destination: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const output = createWriteStream(destination);
+    const archive = archiver("zip", { zlib: { level: 9 } });
+    output.on("close", resolve);
+    output.on("error", reject);
+    archive.on("error", reject);
+    archive.pipe(output);
+    archive.directory(source, false);
+    void archive.finalize();
+  });
+}
+
+function redditServerSource(config: PlayPorterConfig): string {
+  return `import { createHmac, randomUUID } from "node:crypto";
+import express from "express";
+import { createServer, context, getServerPort, reddit, settings } from "@devvit/web/server";
+
+const app = express();
+app.use(express.json());
+
+app.get("/api/playporter-session", async (req, res) => {
+  const secret = await settings.get<string>("playporterDeploySecret");
+  if (!secret) return res.status(503).json({ error: "PlayPorter deploy secret is not configured" });
+  const cookies = Object.fromEntries(String(req.headers.cookie ?? "").split(";").map((part) => part.trim().split("=")).filter(([key]) => key));
+  const isGuest = !context.userId;
+  const guestId = cookies.pp_guest || randomUUID();
+  if (isGuest && !cookies.pp_guest) res.setHeader("set-cookie", "pp_guest=" + guestId + "; Path=/; HttpOnly; SameSite=Lax; Max-Age=2592000");
+  const payload = {
+    userId: context.userId || "reddit_guest_" + guestId,
+    subreddit: context.subredditName,
+    postId: context.postId,
+    issuedAt: Date.now(),
+    isGuest,
+  };
+  const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const signature = createHmac("sha256", secret).update(encoded).digest("base64url");
+  return res.json({ assertion: encoded + "." + signature, context: { subreddit: context.subredditName, postId: context.postId, isGuest } });
+});
+
+app.post("/internal/menu/create-post", async (_req, res) => {
+  try {
+    const post = await reddit.submitCustomPost({
+      title: ${JSON.stringify(config.platforms.reddit?.postTitle ?? config.game.name)},
+      entry: "default",
+      textFallback: { text: ${JSON.stringify(`Play ${config.game.name}. Open this post in the current Reddit app or website for the interactive version.`)} },
+    });
+    return res.json({ showToast: "Created " + post.id });
+  } catch (error) {
+    console.error(error);
+    return res.status(400).json({ showToast: "Failed to create the PlayPorter post" });
+  }
+});
+
+const server = createServer(app);
+server.on("error", (error) => console.error(error));
+server.listen(getServerPort());
+`;
+}
+
+function bootstrapExample(): string {
+  return `import { PlayPorterClient } from "playporter";
+
+declare global {
+  interface Window {
+    __PLAYPORTER_RUNTIME__?: {
+      apiBaseUrl: string;
+      platform: "discord" | "telegram" | "reddit" | "web";
+      gameVersion: string;
+      discordClientId?: string | null;
+    };
+  }
+}
+
+const runtime = window.__PLAYPORTER_RUNTIME__;
+export const playporter = await PlayPorterClient.initialize({
+  apiBaseUrl: runtime?.apiBaseUrl ?? import.meta.env.VITE_PLAYPORTER_URL,
+  projectKey: import.meta.env.VITE_PLAYPORTER_PROJECT_KEY,
+  platform: runtime?.platform ?? "auto",
+  appVersion: runtime?.gameVersion ?? "0.1.0",
+  discordClientId: runtime?.discordClientId ?? import.meta.env.VITE_DISCORD_CLIENT_ID,
+});
+
+const player = await playporter.identity.getPlayer();
+const config = await playporter.liveops.getConfig();
+await playporter.passport.unlockAchievement("first_session");
+playporter.analytics.track("game_loaded", { playerId: player.id, revision: config.revision });
+`;
+}
+
+function discordReadme(config: PlayPorterConfig): string {
+  return `# Discord Activity package\n\n1. Host the \`app/\` directory on HTTPS.\n2. In Discord Developer Portal, enable Activities.\n3. Map \`/\` to the hosted app and map the PlayPorter API domain.\n4. Configure Client ID and Client Secret in PlayPorter Studio.\n5. Test desktop, mobile and web.\n\nGame: ${config.game.name} ${config.game.version}\n`;
+}
+function telegramReadme(config: PlayPorterConfig): string {
+  return `# Telegram Mini App package\n\n1. Host the \`app/\` directory on HTTPS.\n2. Configure the Mini App URL with BotFather.\n3. Store the bot token in PlayPorter Studio.\n4. Launch only from Telegram so initData can be validated server-side.\n\nGame: ${config.game.name} ${config.game.version}\n`;
+}
+function redditReadme(config: PlayPorterConfig): string {
+  return `# Reddit Devvit Web package\n\nRequires Node.js 22.2+.\n\n\`npm install\`\n\`npm run settings:set\`  # use the same deploy secret stored in PlayPorter Studio\n\`npm run dev\`\n\nUse the subreddit moderator menu item **Create PlayPorter game post**. When ready, run \`npm run launch\`.\n\nGame: ${config.game.name} ${config.game.version}\n`;
+}
+
+function sourceFilter(source: string): boolean {
+  const base = path.basename(source);
+  return ![".git", "node_modules", ".env", ".env.local", "src"].includes(base) && !source.endsWith(".ts") && !source.endsWith(".tsx");
+}
+function slugify(value: string): string { return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "my-game"; }
+function redditName(value: string): string { const slug = slugify(value).slice(0, 16); return /^[a-z]/.test(slug) ? slug.padEnd(3, "x") : `g-${slug}`.slice(0, 16); }
+function formatBytes(bytes: number): string { return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KiB` : `${(bytes / 1024 / 1024).toFixed(1)} MiB`; }
+async function writeJson(file: string, data: unknown): Promise<void> { await fs.ensureDir(path.dirname(file)); await writeFile(file, `${JSON.stringify(data, null, 2)}\n`, "utf8"); }
+function yamlHeader(): string { return "# PlayPorter vendor-neutral control plane config\n# https://playporter.dev/docs/config\n\n"; }