@spawndotfamily/sdk 0.2.7

package/dist/cli/index.js

@@ -0,0 +1,503 @@
+import { readBoundedFile } from "./files.js";
+import { PublishCliError, PROJECT_ID_PATTERN, normalizeApiUrl, validatePublishConfig, isRecord, redact, requestJson } from "./api.js";
+export { PublishCliError, PUBLISH_REQUEST_TIMEOUT_MS } from "./api.js";
+import { parseListingCommand, runListingCommand, LISTING_USAGE } from "./listing.js";
+import { inspectBrowserBuild, publishBrowserDirectory } from "./upload-client.js";
+// @ts-ignore Node's runtime modules are available to the CLI without adding a runtime dependency.
+import { lstat, opendir, realpath } from 'node:fs/promises';
+// @ts-ignore Node's runtime modules are available to the CLI without adding a runtime dependency.
+import { basename, join, relative, resolve, sep } from 'node:path';
+export const MAX_TOTAL_BYTES = 25_000_000;
+export const MAX_FILE_BYTES = 25_000_000;
+export const MAX_FILES = 1_000;
+export const MAX_TRAVERSED_ENTRIES = 10_000;
+export const MAX_DIRECTORY_DEPTH = 64;
+const BROWSER_ASSET_EXTENSIONS = new Set([
+    'html',
+    'js',
+    'mjs',
+    'css',
+    'json',
+    'wasm',
+    'data',
+    'pck',
+    'unityweb',
+    'bundle',
+    'png',
+    'jpg',
+    'jpeg',
+    'webp',
+    'gif',
+    'svg',
+    'ico',
+    'avif',
+    'mp3',
+    'ogg',
+    'wav',
+    'mp4',
+    'webm',
+    'woff',
+    'woff2',
+    'ttf',
+    'otf',
+    'txt',
+    'atlas',
+    'bin',
+    'glb',
+    'gltf',
+    'ktx2',
+]);
+const SECRET_NAME = /(^|[._-])(secret|secrets|credential|credentials|private[_-]?key|api[_-]?key|access[_-]?token|auth[_-]?token|password|passwd|token)([._-]|$)/i;
+const SECRET_SUFFIX = /\.(pem|key|p12|pfx|jks|keystore|crt)$/i;
+const PRIVATE_KEY_MARKER = /-----BEGIN(?: [A-Z]+)? PRIVATE KEY-----/;
+const SOURCE_SECRET_MARKER = /(?:["']?(?:publish[_-]?key|private[_-]?key|client[_-]?secret|api[_-]?key|access[_-]?token)["']?\s*[:=]|sp_pub_[A-Za-z0-9_-]{20,})/i;
+export const CLI_USAGE = `Usage:
+  spawn-publish check <browser-build-directory>
+  spawn-publish publish <browser-build-directory> [--credentials <file>] [--source-commit <40-hex-commit>]
+  spawn-publish status <release-id> [--credentials <file>]
+${LISTING_USAGE}
+`;
+function runtimeProcess() {
+    const processValue = globalThis.process;
+    if (!processValue)
+        throw new PublishCliError('The publishing CLI requires Node.js.');
+    return processValue;
+}
+function nodeBuffer() {
+    const bufferValue = globalThis.Buffer;
+    if (!bufferValue)
+        throw new PublishCliError('The publishing CLI requires Node.js.');
+    return bufferValue;
+}
+function formatLimit(value) {
+    return value.toLocaleString('en-US');
+}
+function validateSegment(segment) {
+    if (!segment || segment === '.' || segment === '..') {
+        throw new PublishCliError('Build paths cannot contain dot segments.');
+    }
+    if (segment.startsWith('.')) {
+        throw new PublishCliError('Hidden files and directories are not allowed in browser builds.');
+    }
+    if (segment.toLowerCase() === 'node_modules') {
+        throw new PublishCliError('node_modules cannot be uploaded in a browser build.');
+    }
+    if (SECRET_NAME.test(segment) || SECRET_SUFFIX.test(segment)) {
+        throw new PublishCliError('Source secret files are not allowed in browser builds.');
+    }
+}
+function extensionOf(filePath) {
+    const name = basename(filePath);
+    const dot = name.lastIndexOf('.');
+    return dot > 0 && dot < name.length - 1 ? name.slice(dot + 1).toLowerCase() : '';
+}
+function validateBrowserAsset(filePath) {
+    const extension = extensionOf(filePath);
+    if (extension === 'map') {
+        throw new PublishCliError('Source maps (.map) are not accepted in browser builds.');
+    }
+    if (!BROWSER_ASSET_EXTENSIONS.has(extension)) {
+        throw new PublishCliError(`Unsupported browser asset extension for ${extension || 'file'}.`);
+    }
+}
+function assertRelativePayloadPath(filePath) {
+    if (filePath.startsWith('/') || filePath.includes('\\')) {
+        throw new PublishCliError('Browser bundle paths must be relative POSIX paths.');
+    }
+    const segments = filePath.split('/');
+    if (segments.some((segment) => segment === '.' || segment === '..' || segment === '')) {
+        throw new PublishCliError('Browser bundle paths cannot contain dot segments.');
+    }
+}
+async function readRegularFile(filePath, stat) {
+    if (stat.size > MAX_FILE_BYTES) {
+        throw new PublishCliError(`A browser asset exceeds the ${formatLimit(MAX_FILE_BYTES)} byte file limit.`);
+    }
+    let contents;
+    try {
+        contents = await readBoundedFile(filePath, MAX_FILE_BYTES, stat);
+    }
+    catch {
+        throw new PublishCliError('Unable to read a browser build file.');
+    }
+    if (contents.byteLength > MAX_FILE_BYTES) {
+        throw new PublishCliError(`A browser asset exceeds the ${formatLimit(MAX_FILE_BYTES)} byte file limit.`);
+    }
+    const text = new TextDecoder().decode(contents);
+    if (PRIVATE_KEY_MARKER.test(text) || SOURCE_SECRET_MARKER.test(text)) {
+        throw new PublishCliError('Private key material is not allowed in browser builds.');
+    }
+    return contents;
+}
+export async function buildBrowserBundle(directory) {
+    if (typeof directory !== 'string' || directory.trim() === '') {
+        throw new PublishCliError('A prebuilt browser directory is required.');
+    }
+    let root = resolve(directory);
+    let rootStat;
+    try {
+        rootStat = await lstat(root);
+    }
+    catch {
+        throw new PublishCliError('Unable to inspect the browser build directory.');
+    }
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new PublishCliError('The browser build path must be an existing directory.');
+    }
+    root = await realpath(root);
+    const rootNow = await lstat(root);
+    if (rootNow.ino !== rootStat.ino || rootNow.dev !== rootStat.dev)
+        throw new PublishCliError('Build directory changed; stop the build watcher and try again.');
+    const files = [];
+    let totalBytes = 0;
+    let entryText;
+    let traversedEntries = 0;
+    async function visit(currentDirectory, depth) {
+        if (depth > MAX_DIRECTORY_DEPTH) {
+            throw new PublishCliError(`Browser build directory nesting exceeds the ${formatLimit(MAX_DIRECTORY_DEPTH)} level limit.`);
+        }
+        let directoryHandle;
+        try {
+            directoryHandle = await opendir(currentDirectory);
+        }
+        catch {
+            throw new PublishCliError('Unable to inspect the browser build directory.');
+        }
+        const entries = [];
+        try {
+            for await (const entry of directoryHandle) {
+                traversedEntries += 1;
+                if (traversedEntries > MAX_TRAVERSED_ENTRIES) {
+                    throw new PublishCliError(`Browser builds may contain at most ${formatLimit(MAX_TRAVERSED_ENTRIES)} traversed entries.`);
+                }
+                entries.push(entry);
+            }
+        }
+        catch (error) {
+            if (error instanceof PublishCliError)
+                throw error;
+            throw new PublishCliError('Unable to inspect the browser build directory.');
+        }
+        finally {
+            try {
+                await directoryHandle.close();
+            }
+            catch {
+                // The directory is already closed when iteration finishes.
+            }
+        }
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            validateSegment(entry.name);
+            const absolutePath = join(currentDirectory, entry.name);
+            let stat;
+            try {
+                stat = await lstat(absolutePath);
+            }
+            catch {
+                throw new PublishCliError('Unable to inspect the browser build directory.');
+            }
+            if (entry.isSymbolicLink() || stat.isSymbolicLink()) {
+                throw new PublishCliError('Symlinks are not allowed in browser builds.');
+            }
+            if (stat.isDirectory()) {
+                await visit(absolutePath, depth + 1);
+                continue;
+            }
+            if (!stat.isFile()) {
+                throw new PublishCliError('Browser builds may contain only regular files.');
+            }
+            if (files.length >= MAX_FILES) {
+                throw new PublishCliError(`Browser builds may contain at most ${formatLimit(MAX_FILES)} files.`);
+            }
+            const relativePath = relative(root, absolutePath).split(sep).join('/');
+            assertRelativePayloadPath(relativePath);
+            validateBrowserAsset(relativePath);
+            if (await realpath(absolutePath) !== absolutePath)
+                throw new PublishCliError('Symlinked build directories are not accepted.');
+            const contents = await readRegularFile(absolutePath, stat);
+            if (await realpath(absolutePath) !== absolutePath)
+                throw new PublishCliError('Build directory changed; stop the build watcher and try again.');
+            totalBytes += contents.byteLength;
+            if (totalBytes > MAX_TOTAL_BYTES) {
+                throw new PublishCliError(`The browser build exceeds the ${formatLimit(MAX_TOTAL_BYTES)} byte decoded size limit.`);
+            }
+            files.push({ path: relativePath, data: nodeBuffer().from(contents).toString('base64') });
+            if (relativePath === 'index.html')
+                entryText = new TextDecoder().decode(contents);
+        }
+    }
+    await visit(root, 0);
+    if (!files.some((file) => file.path === 'index.html')) {
+        throw new PublishCliError('Browser builds must contain a root index.html entry file.');
+    }
+    if (!entryText || !/<(?:html|body|canvas|script|div|button)\b/i.test(entryText)) {
+        throw new PublishCliError('The index.html entry must contain a browser page.');
+    }
+    return { entry: 'index.html', files };
+}
+function requiredEnv(env, name) {
+    const value = env[name]?.trim();
+    if (!value)
+        throw new PublishCliError(`Missing required environment variable ${name}.`);
+    return value;
+}
+export function readConfig(env = runtimeProcess().env) {
+    const apiUrl = normalizeApiUrl(requiredEnv(env, 'SPAWN_API_URL'));
+    const projectId = requiredEnv(env, 'SPAWN_PROJECT_ID');
+    if (!PROJECT_ID_PATTERN.test(projectId)) {
+        throw new PublishCliError('SPAWN_PROJECT_ID must be a UUID.');
+    }
+    const publishKey = requiredEnv(env, 'SPAWN_PUBLISH_KEY');
+    const uploadOrigin = env.SPAWN_UPLOAD_ORIGIN?.trim();
+    return validatePublishConfig({ apiUrl, projectId, publishKey, ...(uploadOrigin ? { uploadOrigin } : {}) });
+}
+export async function readCredentialsFile(credentialsPath, now = Date.now()) {
+    if (typeof credentialsPath !== 'string' || credentialsPath.trim() === '') {
+        throw new PublishCliError('A credentials file path is required.');
+    }
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(await readBoundedFile(credentialsPath, 65_536));
+    }
+    catch {
+        throw new PublishCliError('Unable to read the credentials file.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new PublishCliError('The credentials file must contain valid JSON.');
+    }
+    if (!isRecord(parsed))
+        throw new PublishCliError('The credentials file must contain one JSON object.');
+    const required = ['platformOrigin', 'projectId', 'publishKey', 'expiresAt'];
+    const allowed = new Set([...required, 'uploadOrigin', 'scopes']);
+    const keys = Object.keys(parsed);
+    if (keys.some((key) => !allowed.has(key))) {
+        throw new PublishCliError('The credentials file contains unknown fields.');
+    }
+    if (required.some(key => !keys.includes(key))) {
+        throw new PublishCliError('The credentials file is missing required fields.');
+    }
+    if (typeof parsed.platformOrigin !== 'string' ||
+        (parsed.uploadOrigin !== undefined && typeof parsed.uploadOrigin !== 'string') ||
+        typeof parsed.projectId !== 'string' ||
+        typeof parsed.publishKey !== 'string' ||
+        (typeof parsed.expiresAt !== 'string' && typeof parsed.expiresAt !== 'number')) {
+        throw new PublishCliError('The credentials file has invalid fields.');
+    }
+    const expiresAt = typeof parsed.expiresAt === 'number'
+        ? (Number.isSafeInteger(parsed.expiresAt) ? parsed.expiresAt : NaN)
+        : Date.parse(parsed.expiresAt);
+    if (!Number.isFinite(expiresAt))
+        throw new PublishCliError('The credentials file has an invalid expiry.');
+    if (expiresAt <= now)
+        throw new PublishCliError('The credentials file has expired.');
+    if (parsed.scopes !== undefined && (!Array.isArray(parsed.scopes) || parsed.scopes.length > 3 || parsed.scopes.some(scope => typeof scope !== 'string' || !['build:read', 'build:upload', 'listing:write'].includes(scope)) || new Set(parsed.scopes).size !== parsed.scopes.length)) {
+        throw new PublishCliError('The credentials file has invalid scopes.');
+    }
+    const config = {
+        ...(parsed.scopes === undefined ? {} : { scopes: parsed.scopes }),
+        apiUrl: normalizeApiUrl(parsed.platformOrigin.trim()),
+        ...(parsed.uploadOrigin === undefined ? {} : { uploadOrigin: normalizeApiUrl(parsed.uploadOrigin.trim()) }),
+        projectId: parsed.projectId.trim(),
+        publishKey: parsed.publishKey.trim(),
+    };
+    if (!config.projectId || !PROJECT_ID_PATTERN.test(config.projectId)) {
+        throw new PublishCliError('The credentials file has an invalid project ID.');
+    }
+    if (!config.publishKey)
+        throw new PublishCliError('The credentials file has an invalid publish key.');
+    return config;
+}
+function validateSourceCommit(value) {
+    if (!/^[0-9a-f]{40}$/i.test(value)) {
+        throw new PublishCliError('sourceCommit must contain exactly 40 hexadecimal characters.');
+    }
+    return value;
+}
+export function parseCommand(argv) {
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h')
+        return { kind: 'help' };
+    if (argv[0] === 'check') {
+        if (argv.length !== 2 || argv[1].startsWith('-'))
+            throw new PublishCliError('check requires one browser-build directory.');
+        return { kind: 'check', directory: argv[1] };
+    }
+    let credentialsPath;
+    const positional = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--credentials') {
+            const value = argv[index + 1];
+            if (credentialsPath)
+                throw new PublishCliError('Duplicate credentials option.');
+            if (!value)
+                throw new PublishCliError('--credentials requires a file path.');
+            credentialsPath = value;
+            index += 1;
+        }
+        else if (argument.startsWith('--credentials=')) {
+            if (credentialsPath)
+                throw new PublishCliError('Duplicate credentials option.');
+            const value = argument.slice('--credentials='.length);
+            if (!value)
+                throw new PublishCliError('--credentials requires a file path.');
+            credentialsPath = value;
+        }
+        else {
+            positional.push(argument);
+        }
+    }
+    if (positional[0] === 'listing' || positional[0] === 'image') {
+        return parseListingCommand(positional, credentialsPath);
+    }
+    if (positional[0] === 'status') {
+        if (positional.length !== 2 || !/^[A-Za-z0-9_-]{1,128}$/.test(positional[1])) {
+            throw new PublishCliError('status requires one safe release ID.');
+        }
+        return { kind: 'status', releaseId: positional[1], credentialsPath };
+    }
+    let directory;
+    let sourceCommit;
+    const args = positional[0] === 'publish' ? positional.slice(1) : positional;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--source-commit') {
+            const value = args[index + 1];
+            if (!value)
+                throw new PublishCliError('--source-commit requires a 40-character commit.');
+            sourceCommit = validateSourceCommit(value);
+            index += 1;
+        }
+        else if (argument.startsWith('--source-commit=')) {
+            sourceCommit = validateSourceCommit(argument.slice('--source-commit='.length));
+        }
+        else if (argument.startsWith('-')) {
+            throw new PublishCliError('Unknown CLI option.');
+        }
+        else if (!directory) {
+            directory = argument;
+        }
+        else {
+            throw new PublishCliError('publish accepts one browser-build directory.');
+        }
+    }
+    if (!directory)
+        throw new PublishCliError(CLI_USAGE.trim());
+    return { kind: 'publish', directory, sourceCommit, credentialsPath };
+}
+function releaseCollectionUrl(config) {
+    return `${config.apiUrl.replace(/\/+$/, '')}/api/v1/publish/${encodeURIComponent(config.projectId)}/releases`;
+}
+function releaseStatusUrl(config, releaseId) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(releaseId)) {
+        throw new PublishCliError('releaseId must be a safe release identifier.');
+    }
+    return `${releaseCollectionUrl(config)}/${encodeURIComponent(releaseId)}`;
+}
+export async function uploadRelease(config, payload, fetchImplementation = globalThis.fetch) {
+    const validatedConfig = validatePublishConfig(config);
+    const body = {
+        entry: 'index.html',
+        files: payload.files,
+    };
+    if (payload.sourceCommit !== undefined)
+        body.sourceCommit = validateSourceCommit(payload.sourceCommit);
+    return requestJson(validatedConfig, releaseCollectionUrl(validatedConfig), {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${validatedConfig.publishKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    }, fetchImplementation);
+}
+export async function getReleaseStatus(config, releaseId, fetchImplementation = globalThis.fetch) {
+    const validatedConfig = validatePublishConfig(config);
+    return requestJson(validatedConfig, releaseStatusUrl(validatedConfig, releaseId), {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${validatedConfig.publishKey}` },
+    }, fetchImplementation);
+}
+function displayPreviewUrl(value, baseUrl) {
+    if (typeof value !== 'string' || !baseUrl)
+        return value;
+    try {
+        const resolved = new URL(value, `${baseUrl}/`);
+        if (!['http:', 'https:'].includes(resolved.protocol))
+            return value;
+        return resolved.toString();
+    }
+    catch {
+        return value;
+    }
+}
+function isExactLoopbackOrigin(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' &&
+            (url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]');
+    }
+    catch {
+        return false;
+    }
+}
+function useExplicitLocalLegacyPublisher(config) {
+    // The old 25 MB simulator is retained only for local reference installations.
+    // Every remote origin, and every local origin with an explicit worker, uses the
+    // negotiated streaming protocol and never falls back after a request fails.
+    return isExactLoopbackOrigin(config.apiUrl) && config.uploadOrigin === undefined;
+}
+export function formatReleaseSummary(response, secret, baseUrl) {
+    const value = isRecord(response) ? response : {};
+    const summary = {
+        id: value.id,
+        status: value.status,
+        previewUrl: displayPreviewUrl(value.previewUrl, baseUrl),
+        checks: value.checks,
+    };
+    return redact(JSON.stringify(summary), secret);
+}
+export async function main(argv = runtimeProcess().argv.slice(2), env = runtimeProcess().env, fetchImplementation = globalThis.fetch, output = { log: (message) => console.log(message), error: (message) => console.error(message) }) {
+    let publishKey;
+    try {
+        const command = parseCommand(argv);
+        if (command.kind === 'help') {
+            output.log(CLI_USAGE.trimEnd());
+            return 0;
+        }
+        if (command.kind === 'check') {
+            const bundle = await inspectBrowserBuild(command.directory);
+            output.log(JSON.stringify({ format: 'spawn-browser-v1', entry: bundle.entry, files: bundle.files.length, bytes: bundle.bytes, playableVerified: false, next: 'Run spawn-dev on this directory, then upload a private preview with spawn-publish publish.' }));
+            return 0;
+        }
+        const config = command.credentialsPath
+            ? await readCredentialsFile(command.credentialsPath)
+            : readConfig(env);
+        publishKey = config.publishKey;
+        if (command.kind === 'status') {
+            const response = await getReleaseStatus(config, command.releaseId, fetchImplementation);
+            output.log(formatReleaseSummary(response, publishKey, config.apiUrl));
+            return 0;
+        }
+        if (command.kind === 'listing') {
+            const response = await runListingCommand(config, command, fetchImplementation);
+            output.log(redact(JSON.stringify(response), publishKey));
+            return 0;
+        }
+        const sourceCommit = command.sourceCommit ?? env.SPAWN_SOURCE_COMMIT?.trim();
+        const response = useExplicitLocalLegacyPublisher(config)
+            ? await uploadRelease(config, Object.assign(await buildBrowserBundle(command.directory), sourceCommit ? { sourceCommit: validateSourceCommit(sourceCommit) } : {}), fetchImplementation)
+            : await publishBrowserDirectory(config, command.directory, sourceCommit, fetchImplementation);
+        output.log(formatReleaseSummary(response, publishKey, config.apiUrl));
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Spawn publish failed.';
+        output.error(redact(message, publishKey ?? env.SPAWN_PUBLISH_KEY));
+        return 1;
+    }
+}

package/dist/cli/listing.d.ts

@@ -0,0 +1,14 @@
+import type { PublishConfig, FetchLike } from './api.ts';
+export declare const MAX_IMAGE_BYTES = 1048576;
+export declare const LISTING_USAGE = "  spawn-publish listing get --credentials <file>\n  spawn-publish listing update <patch.json> --credentials <file>\n  spawn-publish image add <image-file> --expected-version <integer> --alt <text> --credentials <file>\n  spawn-publish image replace <image-id> <image-file> --expected-version <integer> --alt <text> --credentials <file>\n  spawn-publish image remove <image-id> --expected-version <integer> --credentials <file>\nListing commands require platform endpoint availability. Metadata edits do not publish a game.";
+export type ListingCommand = {
+    kind: 'listing';
+    action: 'get' | 'update' | 'add' | 'replace' | 'remove';
+    credentialsPath: string;
+    file?: string;
+    imageId?: string;
+    expectedVersion?: number;
+    alt?: string;
+};
+export declare function parseListingCommand(argv: string[], credentialsPath?: string): ListingCommand;
+export declare function runListingCommand(inputConfig: PublishConfig, command: ListingCommand, fetchImplementation: FetchLike): Promise<Record<string, unknown>>;

package/dist/cli/listing.js

@@ -0,0 +1,155 @@
+import { readBoundedFile } from "./files.js";
+import { PublishCliError, PROJECT_ID_PATTERN, isRecord, requestJson, validatePublishConfig } from "./api.js";
+export const MAX_IMAGE_BYTES = 1_048_576;
+const MAX_PATCH_BYTES = 32_768;
+const FIELDS = {
+    name: [1, 60], description: [0, 500], genre: [0, 32], controls: [0, 120], instructions: [0, 1500],
+};
+export const LISTING_USAGE = `  spawn-publish listing get --credentials <file>
+  spawn-publish listing update <patch.json> --credentials <file>
+  spawn-publish image add <image-file> --expected-version <integer> --alt <text> --credentials <file>
+  spawn-publish image replace <image-id> <image-file> --expected-version <integer> --alt <text> --credentials <file>
+  spawn-publish image remove <image-id> --expected-version <integer> --credentials <file>
+Listing commands require platform endpoint availability. Metadata edits do not publish a game.`;
+function fail(message) { throw new PublishCliError(message); }
+function version(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        fail('expectedVersion must be a nonnegative safe integer.');
+    return value;
+}
+function uuid(value) {
+    if (typeof value !== 'string' || !PROJECT_ID_PATTERN.test(value))
+        fail('An image ID must be a UUID.');
+    return value;
+}
+function textField(value, name, min, max) {
+    if (typeof value !== 'string' || value.length < min || value.length > max || (min > 0 && !value.trim())) {
+        fail(`${name} must contain ${min}–${max} characters.`);
+    }
+    return value;
+}
+export function parseListingCommand(argv, credentialsPath) {
+    if (!credentialsPath)
+        fail('Listing commands require --credentials with the downloaded creator file.');
+    const [group, action, ...args] = argv;
+    if (group === 'listing') {
+        if (action === 'get' && args.length === 0)
+            return { kind: 'listing', action, credentialsPath };
+        if (action === 'update' && args.length === 1 && !args[0].startsWith('-')) {
+            return { kind: 'listing', action, credentialsPath, file: args[0] };
+        }
+        fail('Use listing get or listing update <patch.json>.');
+    }
+    if (group !== 'image' || !['add', 'replace', 'remove'].includes(action))
+        fail('Use image add, replace or remove.');
+    const positional = [], flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('-')) {
+            if (!['--expected-version', '--alt'].includes(arg) || flags.has(arg) || args[i + 1] === undefined)
+                fail('Invalid or duplicate image option.');
+            flags.set(arg, args[++i]);
+        }
+        else
+            positional.push(arg);
+    }
+    const expected = flags.get('--expected-version');
+    if (!expected || !/^(0|[1-9][0-9]*)$/.test(expected))
+        fail('--expected-version requires a nonnegative integer from listing get.');
+    const expectedVersion = version(Number(expected));
+    const count = action === 'replace' ? 2 : 1;
+    if (positional.length !== count)
+        fail('Incorrect number of image arguments.');
+    const imageId = action === 'add' ? undefined : uuid(positional[0]);
+    if (action === 'remove') {
+        if (flags.has('--alt'))
+            fail('image remove does not accept --alt.');
+        return { kind: 'listing', action, credentialsPath, imageId, expectedVersion };
+    }
+    const alt = textField(flags.get('--alt'), 'alt', 0, 160);
+    return { kind: 'listing', action: action, credentialsPath, imageId,
+        expectedVersion, alt, file: positional[action === 'replace' ? 1 : 0] };
+}
+function validatePatch(value) {
+    if (!isRecord(value) || Array.isArray(value))
+        fail('The listing patch must be a JSON object.');
+    const allowed = new Set(['expectedVersion', ...Object.keys(FIELDS), 'modes', 'coverImageId']);
+    if (Object.keys(value).some(key => !allowed.has(key)))
+        fail('The listing patch contains an unsupported field.');
+    const patch = { expectedVersion: version(value.expectedVersion) };
+    for (const [name, [min, max]] of Object.entries(FIELDS)) {
+        if (Object.hasOwn(value, name))
+            patch[name] = textField(value[name], name, min, max);
+    }
+    if (Object.hasOwn(value, 'modes')) {
+        if (!Array.isArray(value.modes) || value.modes.length > 8)
+            fail('modes must be an array of at most 8 strings.');
+        patch.modes = value.modes.map(mode => textField(mode, 'mode', 1, 40));
+    }
+    if (Object.hasOwn(value, 'coverImageId'))
+        patch.coverImageId = value.coverImageId === null ? null : uuid(value.coverImageId);
+    if (Object.keys(patch).length === 1)
+        fail('The listing patch must include at least one editable field.');
+    return patch;
+}
+async function imageData(file) {
+    const bytes = await readBoundedFile(file, MAX_IMAGE_BYTES);
+    const starts = (...signature) => signature.every((byte, i) => bytes[i] === byte);
+    const ascii = (from, to) => new TextDecoder().decode(bytes.slice(from, to));
+    const png = starts(137, 80, 78, 71, 13, 10, 26, 10);
+    const jpeg = starts(255, 216, 255);
+    const webp = ascii(0, 4) === 'RIFF' && ascii(8, 12) === 'WEBP';
+    if (!png && !jpeg && !webp)
+        fail('Images must be JPEG, PNG or WebP. The platform validates and normalizes image contents.');
+    const buffer = globalThis.Buffer;
+    return buffer.from(bytes).toString('base64');
+}
+function publicListing(value) {
+    if (!Number.isSafeInteger(value.version) || Number(value.version) < 0 || !Array.isArray(value.images) || value.images.length > 8)
+        fail('Spawn returned an invalid listing response.');
+    const { expectedVersion: _, ...fields } = validatePatch({ expectedVersion: value.version,
+        ...Object.fromEntries([...Object.keys(FIELDS), 'modes', 'coverImageId'].map(key => [key, value[key]])) });
+    const images = value.images.map(image => {
+        if (!isRecord(image))
+            fail('Spawn returned an invalid listing image.');
+        return { id: uuid(image.id), url: textField(image.url, 'image URL', 1, 2048), alt: textField(image.alt, 'alt', 0, 160) };
+    });
+    return { version: value.version, ...fields, images };
+}
+export async function runListingCommand(inputConfig, command, fetchImplementation) {
+    const config = validatePublishConfig(inputConfig);
+    const mutation = command.action !== 'get';
+    if (mutation && !config.scopes?.includes('listing:write'))
+        fail('This credential file does not grant listing:write. Download new scoped credentials from Spawn.');
+    if (!mutation && config.scopes && !config.scopes.includes('build:read'))
+        fail('Listing reads require build:read.');
+    const base = `${config.apiUrl}/api/v1/publish/${config.projectId}`;
+    let method = 'GET', path = '/listing', body;
+    if (command.action === 'update') {
+        let patch;
+        try {
+            patch = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await readBoundedFile(command.file, MAX_PATCH_BYTES)));
+        }
+        catch (error) {
+            if (error instanceof PublishCliError)
+                throw error;
+            fail('The listing patch must contain valid UTF-8 JSON.');
+        }
+        body = validatePatch(patch);
+        method = 'PATCH';
+    }
+    else if (mutation) {
+        path = '/media' + (command.imageId ? `/${uuid(command.imageId)}` : '');
+        method = command.action === 'add' ? 'POST' : command.action === 'replace' ? 'PUT' : 'DELETE';
+        body = { expectedVersion: version(command.expectedVersion) };
+        if (command.action !== 'remove') {
+            body.data = await imageData(command.file);
+            body.alt = textField(command.alt, 'alt', 0, 160);
+        }
+    }
+    const response = await requestJson(config, base + path, {
+        method, headers: { Authorization: `Bearer ${config.publishKey}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    }, fetchImplementation, true);
+    return publicListing(response);
+}

package/dist/cli/run.d.ts

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