@playdrop/playdrop-cli 0.18.8 → 0.19.0

package/README.md

@@ -153,3 +153,30 @@ For direct first-party server uploads from this checkout, start `npm run dev:age
 playdrop documentation browse
 playdrop documentation read runtime
 ```
+
+## Localized game listings
+
+An app in `catalogue.json` can declare a BCP47 `sourceLocale` (including languages such as Italian or Arabic) and an inline `listingLocalizations` object keyed by a supported PlayDrop locale. The original app fields remain the source listing. Each localization is a complete presentation: `displayName`, optional `subtitle`, `description`, `controls`, `makingOf`, `releaseNotes`, and its own `listing` media paths and captions. Omitted optional fields and arrays stay empty; they do not inherit source values. Explicitly reuse a source path when the same artwork should appear in both languages. Social artwork accepts PNG or JPEG, other images use PNG, and trailers use MP4.
+
+Run `playdrop project validate .` to obtain `listingSourceHash`. Each localization records that value as `sourceHash`. Source text or media changes make older localizations stale; runtime version changes do not. Stale localizations remain inspectable but are excluded from public presentation. Uploads replace the complete localization set, so omitting an entry removes that locale from the new version.
+
+```json
+{
+  "sourceLocale": "en",
+  "listingLocalizations": {
+    "fr": {
+      "sourceHash": "<64-character listingSourceHash from validation>",
+      "displayName": "Mon jeu",
+      "description": "Description du jeu.",
+      "listing": {
+        "heroLandscape": "listing/hero-landscape.png",
+        "screenshotsLandscape": [
+          { "path": "listing/fr/screenshot.png", "alt": "Une partie en cours" }
+        ]
+      }
+    }
+  }
+}
+```
+
+Cloud task checkout, upload, and publish preserve this contract and include localized listing files in the source sync and listing locks.

package/config/client-meta.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.18.8",
+  "version": "0.19.0",
   "build": 1,
-  "runtimeSdkVersion": "0.18.8",
+  "runtimeSdkVersion": "0.19.0",
   "runtimeSdkBuild": 1,
   "clients": {
     "all": {

package/dist/apps/upload.d.ts

@@ -1,5 +1,6 @@
 import type { ApiClient } from "@playdrop/api-client";
 import type { AgentTaskPlaytestProof, FinalizeAppUploadRequest, UserResponse } from "@playdrop/types";
+import { type AppListingLocalization } from "@playdrop/types";
 import type { AppTask } from "../catalogue";
 import type { TaskCaptureSession } from "../appUrls";
 import type { AppBuildArtifacts } from "./build";
@@ -73,6 +74,7 @@ type PreparedAppUploadFiles = {
     sessionFiles: PreparedSessionFile[];
     ownedAssets: PreparedOwnedAssetUpload[];
     gameServerBuild: GameServerBuild | null;
+    listingLocalizations: AppListingLocalization[];
 };
 export declare function prepareAppUploadFiles(task: AppTask, artifacts: AppBuildArtifacts | null, options?: {
     apiBase?: string;

package/dist/apps/upload.js

@@ -7,6 +7,8 @@ const types_1 = require("@playdrop/types");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const proxyFetch_1 = require("../proxyFetch");
+const uploadDispatchers_1 = require("../uploadDispatchers");
 const http_1 = require("../http");
 const proceduralValidation_1 = require("../proceduralValidation");
 const game_source_git_1 = require("../commands/worker/game-source-git");
@@ -178,17 +180,60 @@ function pushPreparedArtifact(task, currentTotal, file, maxBytes, code, label) {
     const bytes = ensurePreparedArtifactSize(file, maxBytes, code, label);
     return accumulateUploadBytes(task.name, currentTotal, bytes);
 }
-async function uploadSignedObject(client, creatorUsername, appName, sessionId, file, descriptor) {
+function objectUploadTransportCode(error) {
+    return error && typeof error === "object" && "code" in error &&
+        typeof error.code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code)
+        ? error.code
+        : null;
+}
+function objectUploadTransportDetail(error, signedUrl) {
+    const details = [];
+    const seen = new Set();
+    let current = error;
+    while (current && typeof current === "object" && !seen.has(current) && seen.size < 4) {
+        seen.add(current);
+        const value = current;
+        const code = objectUploadTransportCode(value);
+        // Error messages can echo the signed request. Keep the transport explanation,
+        // never its URL, authorization header or credentials, in task/operator logs.
+        const message = typeof value.message === "string" ? value.message
+            .split(signedUrl).join("[redacted-url]")
+            .replace(/\bhttps?:\/\/[^\s"'<>]+/gi, "[redacted-url]")
+            .replace(/\b(?:proxy-authorization|authorization)\s*:\s*[^\r\n]+/gi, "authorization: [redacted]")
+            .replace(/\b(?:Bearer|Basic)\s+[^\s,;]+/gi, "[redacted-authorization]")
+            .replace(/\b(?:X-Goog-(?:Signature|Credential|Security-Token)|token|signature|credential|authorization)\b["']?\s*[=:]\s*["']?[^\s"',;}]+/gi, "[redacted-credential]")
+            .replace(/[\x00-\x1f\x7f]+/g, " ").trim().slice(0, 200) : "";
+        if (message || code)
+            details.push([code, message].filter(Boolean).join(": "));
+        current = value.cause;
+    }
+    return details.join(" <- ").slice(0, 400);
+}
+async function uploadSignedObject(client, creatorUsername, appName, sessionId, file, descriptor, transport) {
     for (let attempt = 0; attempt < 2; attempt += 1) {
-        const response = await fetch(descriptor.url, {
-            method: descriptor.method,
-            headers: descriptor.headers,
-            body: file.file,
-        });
+        let response;
+        try {
+            response = await fetch(descriptor.url, {
+                method: descriptor.method,
+                headers: descriptor.headers,
+                body: file.file,
+                ...transport,
+            });
+        }
+        catch (error) {
+            const cause = error instanceof Error ? error.cause : null;
+            const code = objectUploadTransportCode(cause) ?? objectUploadTransportCode(error) ?? "UNKNOWN";
+            const detail = objectUploadTransportDetail(cause ?? error, descriptor.url);
+            const annotated = new Error(`direct_object_upload_network_failed:${file.relativePath}:${code}${detail ? `: ${detail}` : ""}`);
+            Object.defineProperty(annotated, "cause", { value: error, configurable: true, writable: true });
+            throw annotated;
+        }
         if (response.ok) {
+            await response.body?.cancel();
             return;
         }
         if ((response.status === 401 || response.status === 403) && attempt === 0) {
+            await response.body?.cancel();
             const signed = await client.signAppUploadObjects(creatorUsername, appName, sessionId, {
                 objectIds: [file.id],
             });
@@ -204,23 +249,48 @@ async function uploadSignedObject(client, creatorUsername, appName, sessionId, f
     }
 }
 async function uploadSignedObjects(client, creatorUsername, appName, sessionId, files) {
-    for (let offset = 0; offset < files.length; offset += 100) {
-        const batch = files.slice(offset, offset + 100);
-        const signed = await client.signAppUploadObjects(creatorUsername, appName, sessionId, {
-            objectIds: batch.map((file) => file.id),
-        });
-        const descriptors = new Map(signed.uploads.map((entry) => [entry.id, entry]));
-        let cursor = 0;
-        const workers = Array.from({ length: Math.min(8, batch.length) }, async () => {
-            while (cursor < batch.length) {
-                const file = batch[cursor++];
-                const descriptor = descriptors.get(file.id);
-                // A missing descriptor means the API verified this object is stored.
-                if (descriptor)
-                    await uploadSignedObject(client, creatorUsername, appName, sessionId, file, descriptor);
-            }
-        });
-        await Promise.all(workers);
+    if (files.length === 0)
+        return;
+    // Uploads run in the long-lived worker supervisor. Own this pool here so a
+    // later upload cannot inherit its connections or Node's changing H2 defaults.
+    const dispatcher = new uploadDispatchers_1.ObjectUploadAgent({
+        ...(0, proxyFetch_1.resolveProxyEnvironment)(),
+        allowH2: false,
+        requestTls: { allowH2: false },
+        proxyTls: { allowH2: false },
+    });
+    const controller = new AbortController();
+    const transport = { dispatcher, signal: controller.signal };
+    try {
+        for (let offset = 0; offset < files.length; offset += 100) {
+            const batch = files.slice(offset, offset + 100);
+            const signed = await client.signAppUploadObjects(creatorUsername, appName, sessionId, {
+                objectIds: batch.map((file) => file.id),
+            });
+            const descriptors = new Map(signed.uploads.map((entry) => [entry.id, entry]));
+            let cursor = 0;
+            const workers = Array.from({ length: Math.min(8, batch.length) }, async () => {
+                try {
+                    while (!controller.signal.aborted && cursor < batch.length) {
+                        const file = batch[cursor++];
+                        const descriptor = descriptors.get(file.id);
+                        // A missing descriptor means the API verified this object is stored.
+                        if (descriptor)
+                            await uploadSignedObject(client, creatorUsername, appName, sessionId, file, descriptor, transport);
+                    }
+                }
+                catch (error) {
+                    // Preserve the triggering failure, cancel peers and stop taking work.
+                    controller.abort(error);
+                }
+            });
+            await Promise.all(workers);
+            controller.signal.throwIfAborted();
+        }
+    }
+    finally {
+        // Finish cancellation before the caller aborts the server upload session.
+        await dispatcher.destroy();
     }
 }
 async function prepareAppUploadFiles(task, artifacts, options = {}) {
@@ -264,46 +334,59 @@ async function prepareAppUploadFiles(task, artifacts, options = {}) {
         sessionFiles.push(await buildPreparedSessionFile("SERVER", "server/bundle.mjs", bundle.file));
         sessionFiles.push(await buildPreparedSessionFile("SERVER", "server/manifest.json", manifest.file));
     }
-    if (listing?.iconPath) {
-        const prepared = createFileFromPath(listing.iconPath, "image/png", config_1.MAX_VERSION_ICON_BYTES, "icon_too_large", "invalid_icon_content_type", "Icon", isPngSignature);
-        totalUploadBytes = pushPreparedFile(task.name, totalUploadBytes, prepared);
-        sessionFiles.push(await buildPreparedSessionFile("LISTING", "listing/icon.png", prepared.file));
-    }
-    if (listing?.heroPortraitPath) {
-        const prepared = createFileFromPath(listing.heroPortraitPath, "image/png", config_1.MAX_VERSION_HERO_BYTES, "hero_portrait_too_large", "invalid_hero_portrait_content_type", "Hero portrait", isPngSignature);
-        totalUploadBytes = pushPreparedFile(task.name, totalUploadBytes, prepared);
-        sessionFiles.push(await buildPreparedSessionFile("LISTING", "listing/hero-portrait.png", prepared.file));
-    }
-    if (listing?.heroLandscapePath) {
-        const prepared = createFileFromPath(listing.heroLandscapePath, "image/png", config_1.MAX_VERSION_HERO_BYTES, "hero_landscape_too_large", "invalid_hero_landscape_content_type", "Hero landscape", isPngSignature);
-        totalUploadBytes = pushPreparedFile(task.name, totalUploadBytes, prepared);
-        sessionFiles.push(await buildPreparedSessionFile("LISTING", "listing/hero-landscape.png", prepared.file));
-    }
-    for (let index = 0; index < (listing?.screenshotPortraitPaths ?? []).length; index += 1) {
-        const filePath = listing.screenshotPortraitPaths[index];
-        const prepared = createFileFromPath(filePath, "image/png", config_1.MAX_VERSION_SCREENSHOT_BYTES, "screenshot_portrait_too_large", "invalid_screenshot_portrait_content_type", `Portrait screenshot ${index + 1}`, isPngSignature);
+    const preparedByHash = new Map();
+    const prepareListingFile = async (filePath, destination, slot, reuse) => {
+        const video = slot.startsWith("videos");
+        const socialJpeg = slot === "socialLandscapePath" && [".jpg", ".jpeg"].includes((0, node_path_1.extname)(filePath).toLowerCase());
+        if (socialJpeg)
+            destination = destination.replace(/\.png$/, ".jpg");
+        const maxBytes = video ? config_1.MAX_VERSION_VIDEO_BYTES : slot === "iconPath" ? config_1.MAX_VERSION_ICON_BYTES : slot.startsWith("screenshots") ? config_1.MAX_VERSION_SCREENSHOT_BYTES : config_1.MAX_VERSION_HERO_BYTES;
+        const prepared = createFileFromPath(filePath, video ? "video/mp4" : socialJpeg ? "image/jpeg" : "image/png", maxBytes, "listing_media_too_large", "invalid_listing_media_content_type", destination, video ? isMp4Signature : socialJpeg ? (bytes) => bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff : isPngSignature);
+        const file = await buildPreparedSessionFile("LISTING", destination, prepared.file);
+        const hashKey = `${file.contentType}:${file.sha256}`;
+        const existing = preparedByHash.get(hashKey);
+        if (reuse && existing)
+            return existing;
         totalUploadBytes = pushPreparedFile(task.name, totalUploadBytes, prepared);
-        sessionFiles.push(await buildPreparedSessionFile("LISTING", `listing/screenshots/portrait/${index}.png`, prepared.file));
-    }
-    for (let index = 0; index < (listing?.screenshotLandscapePaths ?? []).length; index += 1) {
-        const filePath = listing.screenshotLandscapePaths[index];
-        const prepared = createFileFromPath(filePath, "image/png", config_1.MAX_VERSION_SCREENSHOT_BYTES, "screenshot_landscape_too_large", "invalid_screenshot_landscape_content_type", `Landscape screenshot ${index + 1}`, isPngSignature);
-        totalUploadBytes = pushPreparedFile(task.name, totalUploadBytes, prepared);
-        sessionFiles.push(await buildPreparedSessionFile("LISTING", `listing/screenshots/landscape/${index}.png`, prepared.file));
+        sessionFiles.push(file);
+        preparedByHash.set(hashKey, destination);
+        return destination;
+    };
+    const singletonSlots = [
+        ["iconPath", "icon.png"], ["heroPortraitPath", "hero-portrait.png"],
+        ["heroLandscapePath", "hero-landscape.png"], ["socialLandscapePath", "social-landscape.png"],
+    ];
+    const arraySlots = [
+        ["screenshotsPortrait", "screenshotPortraitPaths", "screenshots/portrait", "png"],
+        ["screenshotsLandscape", "screenshotLandscapePaths", "screenshots/landscape", "png"],
+        ["videosPortrait", "videoPortraitPaths", "videos/portrait", "mp4"],
+        ["videosLandscape", "videoLandscapePaths", "videos/landscape", "mp4"],
+    ];
+    for (const [slot, filename] of singletonSlots) {
+        const file = listing?.[slot];
+        if (file)
+            await prepareListingFile(file, `listing/${filename}`, slot, false);
     }
-    for (let index = 0; index < (listing?.videoPortraitPaths ?? []).length; index += 1) {
-        const filePath = listing.videoPortraitPaths[index];
-        const prepared = createFileFromPath(filePath, "video/mp4", config_1.MAX_VERSION_VIDEO_BYTES, "video_portrait_too_large", "invalid_video_portrait_content_type", `Portrait video ${index + 1}`, isMp4Signature);
-        totalUploadBytes = pushPreparedFile(task.name, totalUploadBytes, prepared);
-        sessionFiles.push(await buildPreparedSessionFile("LISTING", `listing/videos/portrait/${index}.mp4`, prepared.file));
+    for (const [slot, field, directory, extension] of arraySlots) {
+        const files = listing?.[field] ?? [];
+        for (const [index, file] of files.entries())
+            await prepareListingFile(file, `listing/${directory}/${index}.${extension}`, slot, false);
     }
-    for (let index = 0; index < (listing?.videoLandscapePaths ?? []).length; index += 1) {
-        const filePath = listing.videoLandscapePaths[index];
-        const prepared = createFileFromPath(filePath, "video/mp4", config_1.MAX_VERSION_VIDEO_BYTES, "video_landscape_too_large", "invalid_video_landscape_content_type", `Landscape video ${index + 1}`, isMp4Signature);
-        totalUploadBytes = pushPreparedFile(task.name, totalUploadBytes, prepared);
-        sessionFiles.push(await buildPreparedSessionFile("LISTING", `listing/videos/landscape/${index}.mp4`, prepared.file));
+    const listingLocalizations = [];
+    for (const localization of task.listingLocalizations ?? []) {
+        const localized = { ...localization };
+        for (const [slot, filename] of singletonSlots) {
+            const file = localization[slot];
+            localized[slot] = file ? await prepareListingFile(file, `listing/locales/${localization.locale}/${filename}`, slot, true) : null;
+        }
+        for (const [slot, , directory, extension] of arraySlots) {
+            localized[slot] = [];
+            for (const [index, file] of localization[slot].entries())
+                localized[slot].push(await prepareListingFile(file, `listing/locales/${localization.locale}/${directory}/${index}.${extension}`, slot, true));
+        }
+        listingLocalizations.push(localized);
     }
-    return { sessionFiles, ownedAssets, gameServerBuild: gameServer };
+    return { sessionFiles, ownedAssets, gameServerBuild: gameServer, listingLocalizations };
 }
 async function uploadApp(client, task, artifacts, options) {
     // Version is required - no legacy fallback
@@ -336,7 +419,7 @@ async function uploadAppVersion(client, task, artifacts, options) {
                 "The prepared upload does not match the project; finish edits and checks before retrying.");
         }
     };
-    const { sessionFiles: preparedSessionFiles, ownedAssets: preparedOwnedAssets, gameServerBuild } = await prepareAppUploadFiles(task, artifacts, { apiBase: options?.apiBase, client });
+    const { sessionFiles: preparedSessionFiles, ownedAssets: preparedOwnedAssets, gameServerBuild, listingLocalizations } = await prepareAppUploadFiles(task, artifacts, { apiBase: options?.apiBase, client });
     await assertPublicationUnchanged(inputFingerprint, false);
     const publicationFingerprint = options?.prepareGitTransition
         ? await (0, game_source_git_1.fingerprintGameSourcePublication)(task.projectDir)
@@ -354,6 +437,9 @@ async function uploadAppVersion(client, task, artifacts, options) {
     })));
     const preparedObjects = [...preparedSessionFiles, ...preparedOwnedAssetFiles];
     const initializeRequest = {
+        sourceLocale: task.sourceLocale,
+        listingSourceHash: task.listingSourceHash,
+        listingLocalizations,
         version: task.version,
         agentTaskId: options?.agentTaskId,
         playtestProof: options?.playtestProof,

package/dist/catalogue.d.ts

@@ -1,3 +1,4 @@
+import { type AppListingContent, type AppListingLocalization } from "@playdrop/types";
 import { type AppAchievementCatalogueDefinition, type AppAuthMode, type AppControllerMode, type AppCreationMetadata, type AppHostingMode, type AppLeaderboardCatalogueDefinition, type AppListingMediaMetadata, type AppMetadataAssetSpecSupport, type AppPlaytestTapes, type AppPlayersConfig, type AppSurface, type AppType, type AppTweaksDeclaration, type AppVersionDesign, type AppVersionVisibility, type AssetSpecContract, type AssetSpecStatus, type AssetSpecValidationKind, type CatalogueTagGroupDefinition, type ContentLicense, type PlayerMetaDefinitionStatus } from "@playdrop/types";
 import { type AssetSpecSupportDeclaration } from "./assetSpecs";
 export type CatalogueJson = {
@@ -21,6 +22,7 @@ export type AppListingConfig = {
     icon?: string;
     heroPortrait?: string;
     heroLandscape?: string;
+    socialLandscape?: string;
     screenshotsPortrait?: AppListingMediaConfig[];
     screenshotsLandscape?: AppListingMediaConfig[];
     videosPortrait?: AppListingMediaConfig[];
@@ -177,6 +179,7 @@ export type ResolvedListingAssets = {
     iconPath?: string;
     heroPortraitPath?: string;
     heroLandscapePath?: string;
+    socialLandscapePath?: string;
     screenshotPortraitPaths: string[];
     screenshotLandscapePaths: string[];
     videoPortraitPaths: string[];
@@ -194,6 +197,9 @@ export type AppServerTask = {
     rooms: string[];
 };
 export type AppTask = {
+    sourceLocale?: string | null;
+    listingSourceHash?: string;
+    listingLocalizations?: AppListingLocalization[];
     kind: "app";
     name: string;
     cataloguePath: string;
@@ -437,4 +443,16 @@ export declare function findAppTaskByFile(htmlPath: string, options?: Pick<Catal
     warnings: string[];
     errors: string[];
 };
+export declare function catalogueListingContent(task: {
+    displayName?: string;
+    subtitle?: string;
+    description?: string;
+    controls?: string;
+    makingOf?: string;
+    releaseNotes?: string;
+    listing?: ResolvedListingAssets;
+}): AppListingContent;
+export declare function calculateCatalogueListingSourceHash(task: Parameters<typeof catalogueListingContent>[0] & {
+    sourceLocale?: string | null;
+}): string;
 export {};