@playdrop/playdrop-cli 0.3.4-build.1 → 0.3.8-build.1

package/README.md

@@ -1,25 +1,62 @@
 # @playdrop/playdrop-cli
 
-command-line interface for creators and AI agents interacting with the Playdrop platform.
-Learn more at [https://playdrop.ai](https://playdrop.ai)
-
-## Key Commands
-- `playdrop-cli login` – authenticate
-- `playdrop-cli init <path>` – initialize a workspace directory (try `~/Documents/playdrop` or `.`)
-- `playdrop-cli create <name> (--template creator/template/name | --remix creator/type/name)` – scaffold a new project from a template or remix.
-- `playdrop-cli dev <name>` – serve an app locally.
-- `playdrop-cli capture [name] [--timeout seconds] [--log-level level] [--surface target] [--screenshot path]` – run the dev frame in Playwright, stream console logs, and fail on browser errors (timeout default: 5 seconds, max: 600; surfaces: desktop, mobile-landscape, mobile-portrait; log levels: debug, info, warn, error; screenshots saved as PNG).
-- `node packages/playdrop-cli/scripts/capture-url.mjs --url <play-url> --screenshot <path> [--timeout seconds] [--log <path>] [--username <name> --password <pass> [--login-url <url>]]` – run a Playwright smoke check against a published app URL and fail on browser errors.
-- `playdrop-cli detail <creator/type/name>` – inspect metadata for an app, asset, or pack (`--format json` for raw output).
-- `playdrop-cli list [--type ... --creator ... --max ...]` – discover apps, assets, and packs available to your account (defaults to all creators).
-- `playdrop-cli feedback --title <title> [--comment text|--file path]` – send feedback to the Playdrop team; CLI metadata is attached automatically.
-- `playdrop-cli upload <pathOrName>` – publish apps, assets, and packs from a catalogue root (`category` and `subcategory` are required for each catalogue asset entry).
-- `playdrop-cli versions <list|set-current|publish|unpublish|delete> <app> [version] [--creator <username|me>]` – manage app versions as owner or admin (`app` supports `name` or `creator/type/name`).
-- `playdrop-cli generate <image|music|sfx|video|model_3d> "<prompt>" [--duration <value>] [--ratio <ratio>]` – generate assets directly with the AI server and store them in your account (`--duration` accepts plain numbers, `s`, or `ms`; `--ratio` supports image `1:1|3:4|9:16|4:3|16:9` and video `16:9|9:16`).
-- `playdrop-cli generations [--type ... --limit ... --offset ... --format text|json]` – browse persisted AI generations and generated asset refs.
-- `playdrop-cli assets categories [--format text|json]` – list canonical category/subcategory definitions and format constraints.
-- `playdrop-cli assets download-file <asset-ref-or-key> [--revision rN] [--role primary] [--out path]` – download one runtime file for a specific role.
-- `playdrop-cli assets download-source <asset-ref-or-key> [--revision rN] [--out path]` – download the full source ZIP bundle.
-- `playdrop-cli assets versions <list|set-current|publish|unpublish|delete> <asset> [revision] [--creator <username|me>]` – manage asset version visibility/current/delete.
-- `playdrop-cli asset-packs download-source <pack-ref-or-key> [--version x.y.z] [--out path]` – download the full source ZIP bundle for an asset pack version.
-- `playdrop-cli asset-packs versions <list|set-current|publish|unpublish|delete> <pack> [version] [--creator <username|me>]` – manage asset pack versions.
+Command-line interface for creators and AI agents using Playdrop.
+
+## Main Commands
+
+```bash
+playdrop auth login
+playdrop browse
+playdrop search "city builder"
+playdrop detail playdrop/app/hangingout
+playdrop comments browse playdrop/app/hangingout
+playdrop versions browse playdrop/app/hangingout
+playdrop credits balance
+playdrop notifications browse
+playdrop creations browse
+playdrop ai create image "Pixel art hero portrait"
+playdrop project init .
+playdrop project create app my-app --template playdrop/template/html_template
+playdrop project dev my-app
+playdrop project publish .
+playdrop documentation browse
+playdrop feedback send --title "Bug report" --comment "Details here."
+playdrop getting-started
+```
+
+## Ref Format
+
+Public content refs are always:
+
+```text
+<creator>/<kind>/<name>
+```
+
+Valid kinds:
+
+- `app`
+- `asset`
+- `asset-pack`
+
+Examples:
+
+- `playdrop/app/hangingout`
+- `playdrop/asset/astro`
+- `playdrop/asset-pack/starter-kit`
+
+## Local Project Flow
+
+```bash
+playdrop auth login
+playdrop project init .
+playdrop project create app my-app --template playdrop/template/html_template
+playdrop project dev my-app
+playdrop project publish .
+```
+
+## Documentation
+
+```bash
+playdrop documentation browse
+playdrop documentation read getting-started.md
+```

package/config/client-meta.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.4",
+  "version": "0.3.8",
   "build": 1,
   "platforms": {
     "ios": {
@@ -26,19 +26,19 @@
   },
   "clients": {
     "web": {
-      "minimumVersion": "0.3.4",
+      "minimumVersion": "0.3.8",
       "minimumBuild": 1
     },
     "admin": {
-      "minimumVersion": "0.3.4",
+      "minimumVersion": "0.3.8",
       "minimumBuild": 1
     },
     "apple": {
-      "minimumVersion": "0.3.4",
+      "minimumVersion": "0.3.8",
       "minimumBuild": 1
     },
     "cli": {
-      "minimumVersion": "0.3.4",
+      "minimumVersion": "0.3.8",
       "minimumBuild": 1
     }
   }

package/dist/apps/upload.js

@@ -47,10 +47,15 @@ async function uploadApp(client, task, artifacts, options) {
  * Upload an app version using the versioned API.
  */
 async function uploadAppVersion(client, task, artifacts, options) {
+    const creatorUsername = typeof options?.creatorUsername === 'string' ? options.creatorUsername.trim() : '';
+    if (!creatorUsername) {
+        throw new Error(`Missing creator username for app "${task.name}" upload.`);
+    }
     const versionOptions = {
         version: task.version,
         releaseNotes: task.releaseNotes,
         visibility: task.versionVisibility,
+        remixRef: task.remix,
         surfaceTargets: task.surfaceTargets,
         entryPoint: artifacts?.metadata?.entryPoint ?? undefined,
         // App metadata (used when creating app if it doesn't exist)
@@ -59,8 +64,6 @@ async function uploadAppVersion(client, task, artifacts, options) {
         type: task.type,
         emoji: task.emoji ?? undefined,
         color: task.color ?? undefined,
-        // Admin-only: publish as different user
-        creatorUsername: options?.creatorUsername,
     };
     // For EXTERNAL hosting mode, use externalUrl instead of bundle
     if (task.hostingMode === 'EXTERNAL') {
@@ -105,7 +108,7 @@ async function uploadAppVersion(client, task, artifacts, options) {
         }
     }
     try {
-        const response = await client.uploadAppVersion(task.name, versionOptions);
+        const response = await client.uploadAppVersion(creatorUsername, task.name, versionOptions);
         return {
             versionCreated: true,
             version: response?.version?.version,

package/dist/assets/model-artifacts.js

@@ -93,7 +93,7 @@ const MODEL_PRESET_BY_SUBCATEGORY = {
         height: 1024,
     },
 };
-const TOOL_NAME = 'playdrop-cli';
+const TOOL_NAME = 'playdrop';
 const WORKER_ENTRY_BASENAMES = ['model-worker.ts', 'model-worker.js'];
 let workerBundlePromise = null;
 function normalizeRole(role) {

package/dist/catalogue.d.ts

@@ -30,6 +30,7 @@ export type AppCatalogueEntry = {
     color?: string | null;
     templateSource?: string | null;
     remixSource?: string | null;
+    remix?: string;
     surfaceTargets?: Record<string, unknown> | AppSurface[] | null;
     version?: string;
     releaseNotes?: string;
@@ -54,6 +55,7 @@ export type AssetCatalogueEntry = {
     category?: string;
     subcategory?: string;
     format?: string;
+    remix?: string;
     username?: string;
     files?: Record<string, string>;
     visibility?: string;
@@ -77,8 +79,12 @@ export type EmbeddedAssetCatalogueEntry = {
 export type AssetPackCatalogueEntry = {
     name: string;
     version?: string;
+    remix?: string;
     username?: string;
     assets?: string[];
+    hostingMode?: string;
+    externalUrl?: string;
+    downloadUrl?: string;
     previewApp?: string;
     visibility?: string;
     releaseNotes?: string;
@@ -135,6 +141,7 @@ export type AppTask = {
     externalUrl?: string;
     listing?: ResolvedListingAssets;
     username?: string;
+    remix?: string;
     embeddedAssets: EmbeddedAssetTask[];
     uses: {
         assets: string[];
@@ -155,6 +162,7 @@ export type AssetTask = {
     category: string;
     subcategory: string;
     username?: string;
+    remix?: string;
     format?: string;
     visibility?: string;
     shopListed?: boolean;
@@ -183,10 +191,15 @@ export type EmbeddedAssetTask = {
 export type AssetPackTask = {
     kind: 'asset-pack';
     name: string;
+    displayName?: string;
     version: string;
     cataloguePath: string;
     username?: string;
+    remix?: string;
     assets: string[];
+    hostingMode?: AppHostingMode;
+    externalUrl?: string;
+    downloadUrl?: string;
     previewApp?: string;
     visibility?: string;
     releaseNotes?: string;

package/dist/catalogue.js

@@ -111,6 +111,52 @@ function validateListingAssetExtension(relativePath, fieldName, kind) {
 function resolveListingAssetPath(baseDir, relativePath) {
     return (0, node_path_1.resolve)(baseDir, relativePath);
 }
+function normalizeCatalogueRemixRef(value, expectedKind, errors, context) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        errors.push(`${context} remix must be a canonical ${expectedKind} version ref string.`);
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed.length) {
+        errors.push(`${context} remix must be a canonical ${expectedKind} version ref string.`);
+        return undefined;
+    }
+    const parsed = (0, types_1.parseContentVersionRef)(trimmed);
+    if (!parsed) {
+        errors.push(`${context} remix must use canonical version ref format.`);
+        return undefined;
+    }
+    if (parsed.kind !== expectedKind) {
+        errors.push(`${context} remix must point to a ${expectedKind} version.`);
+        return undefined;
+    }
+    return (0, types_1.formatContentVersionRef)(parsed);
+}
+function normalizeCatalogueRelations(value, errors, context) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const rows = [];
+    for (const relation of value) {
+        if (!relation || typeof relation !== 'object') {
+            continue;
+        }
+        const type = typeof relation.type === 'string' ? relation.type.trim().toUpperCase() : '';
+        const to = typeof relation.to === 'string' ? relation.to.trim() : '';
+        if (!type || !to) {
+            continue;
+        }
+        if (type === 'REMIXES') {
+            errors.push(`${context} relations must not use REMIXES. Use the dedicated remix field instead.`);
+            continue;
+        }
+        rows.push({ type, to });
+    }
+    return rows.length > 0 ? rows : undefined;
+}
 function normalizeRelativePath(root, target) {
     const rel = (0, node_path_1.relative)(root, target).split(node_path_1.sep).join('/');
     return rel.replace(/^\/+/, '');
@@ -787,21 +833,8 @@ function buildAppTasks(rootDir, catalogues, options) {
             const usesPacks = Array.isArray(entry.uses?.packs)
                 ? entry.uses.packs.filter((value) => typeof value === 'string' && value.trim().length > 0)
                 : [];
-            const graphRelations = [];
-            if (Array.isArray(entry.relations)) {
-                for (const relation of entry.relations) {
-                    if (!relation || typeof relation !== 'object')
-                        continue;
-                    const type = typeof relation.type === 'string' ? relation.type.trim() : '';
-                    const to = typeof relation.to === 'string' ? relation.to.trim() : '';
-                    if (!type || !to)
-                        continue;
-                    graphRelations.push({
-                        type,
-                        to,
-                    });
-                }
-            }
+            const remix = normalizeCatalogueRemixRef(entry.remix, 'app', errors, `[${label}] App "${rawName}"`);
+            const graphRelations = normalizeCatalogueRelations(entry.relations, errors, `[${label}] App "${rawName}"`) ?? [];
             const embeddedAssets = [];
             const rawEmbeddedAssets = Array.isArray(entry.embeddedAssets)
                 ? entry.embeddedAssets
@@ -931,6 +964,7 @@ function buildAppTasks(rootDir, catalogues, options) {
                 listing,
                 // Admin-only field
                 username,
+                remix,
                 embeddedAssets,
                 uses: {
                     assets: usesAssets,
@@ -1045,15 +1079,8 @@ function buildAssetTasks(catalogues) {
                     continue;
                 }
             }
-            const relations = Array.isArray(entry.relations)
-                ? entry.relations
-                    .filter((row) => !!row && typeof row === 'object')
-                    .map((row) => ({
-                    type: typeof row.type === 'string' ? row.type : '',
-                    to: typeof row.to === 'string' ? row.to : '',
-                }))
-                    .filter((row) => row.type.trim().length > 0 && row.to.trim().length > 0)
-                : undefined;
+            const remix = normalizeCatalogueRemixRef(entry.remix, 'asset', errors, `[${label}] Asset "${name}"`);
+            const relations = normalizeCatalogueRelations(entry.relations, errors, `[${label}] Asset "${name}"`);
             const username = typeof entry.username === 'string' && entry.username.trim().length > 0
                 ? entry.username.trim()
                 : undefined;
@@ -1065,6 +1092,7 @@ function buildAssetTasks(catalogues) {
                 category,
                 subcategory,
                 username,
+                remix,
                 format,
                 visibility: normalizeAssetVisibilityValue(entry.visibility, errors, `${label} asset \"${name}\"`),
                 shopListed: typeof entry.shopListed === 'boolean' ? entry.shopListed : undefined,
@@ -1096,6 +1124,7 @@ function buildAssetPackTasks(catalogues) {
                 errors.push(`[${label}] assetPacks[${index}] is missing a name.`);
                 continue;
             }
+            const displayName = typeof entry.displayName === 'string' ? entry.displayName.trim() : '';
             const version = typeof entry.version === 'string' ? entry.version.trim() : '';
             if (!SEMVER_REGEX.test(version)) {
                 errors.push(`[${label}] Asset pack "${name}" must define a semver version.`);
@@ -1110,19 +1139,46 @@ function buildAssetPackTasks(catalogues) {
             const assets = Array.isArray(entry.assets)
                 ? entry.assets.filter((value) => typeof value === 'string' && value.trim().length > 0).map((value) => value.trim())
                 : [];
-            if (assets.length === 0) {
+            let hostingMode;
+            const rawHostingMode = typeof entry.hostingMode === 'string' ? entry.hostingMode.trim().toUpperCase() : '';
+            if (rawHostingMode) {
+                if (!types_1.APP_HOSTING_MODE_VALUES.includes(rawHostingMode)) {
+                    errors.push(`[${label}] Asset pack "${name}" hostingMode must be one of ${types_1.APP_HOSTING_MODE_VALUES.join(', ')}.`);
+                    continue;
+                }
+                hostingMode = rawHostingMode;
+            }
+            let externalUrl;
+            const rawExternalUrl = typeof entry.externalUrl === 'string' ? entry.externalUrl.trim() : '';
+            if (rawExternalUrl) {
+                if (!/^https:\/\//i.test(rawExternalUrl)) {
+                    errors.push(`[${label}] Asset pack "${name}" externalUrl must be an HTTPS URL.`);
+                    continue;
+                }
+                externalUrl = rawExternalUrl;
+            }
+            let downloadUrl;
+            const rawDownloadUrl = typeof entry.downloadUrl === 'string' ? entry.downloadUrl.trim() : '';
+            if (rawDownloadUrl) {
+                if (!/^https:\/\//i.test(rawDownloadUrl)) {
+                    errors.push(`[${label}] Asset pack "${name}" downloadUrl must be an HTTPS URL.`);
+                    continue;
+                }
+                downloadUrl = rawDownloadUrl;
+            }
+            if (hostingMode === 'EXTERNAL' && !externalUrl) {
+                errors.push(`[${label}] Asset pack "${name}" externalUrl is required when hostingMode is EXTERNAL.`);
+                continue;
+            }
+            if (externalUrl && hostingMode !== 'EXTERNAL') {
+                hostingMode = 'EXTERNAL';
+            }
+            if (assets.length === 0 && hostingMode !== 'EXTERNAL') {
                 errors.push(`[${label}] Asset pack "${name}" must reference at least one asset.`);
                 continue;
             }
-            const relations = Array.isArray(entry.relations)
-                ? entry.relations
-                    .filter((row) => !!row && typeof row === 'object')
-                    .map((row) => ({
-                    type: typeof row.type === 'string' ? row.type : '',
-                    to: typeof row.to === 'string' ? row.to : '',
-                }))
-                    .filter((row) => row.type.trim().length > 0 && row.to.trim().length > 0)
-                : undefined;
+            const remix = normalizeCatalogueRemixRef(entry.remix, 'pack', errors, `[${label}] Asset pack "${name}@${version}"`);
+            const relations = normalizeCatalogueRelations(entry.relations, errors, `[${label}] Asset pack "${name}@${version}"`);
             const username = typeof entry.username === 'string' && entry.username.trim().length > 0
                 ? entry.username.trim()
                 : undefined;
@@ -1285,10 +1341,15 @@ function buildAssetPackTasks(catalogues) {
             tasks.push({
                 kind: 'asset-pack',
                 name,
+                displayName: displayName || undefined,
                 version,
                 cataloguePath: label,
                 username,
+                remix,
                 assets,
+                hostingMode,
+                externalUrl,
+                downloadUrl,
                 previewApp: typeof entry.previewApp === 'string' && entry.previewApp.trim().length > 0 ? entry.previewApp.trim() : undefined,
                 visibility,
                 releaseNotes: typeof entry.releaseNotes === 'string' ? entry.releaseNotes : undefined,

package/dist/commandContext.d.ts

@@ -12,4 +12,5 @@ export type EnvironmentContext = {
 };
 type EnvironmentCallback = (ctx: EnvironmentContext) => Promise<void> | void;
 export declare function withEnvironment(command: string, actionLabel: string, callback: EnvironmentCallback): Promise<void>;
+export declare function withPublicEnvironment(command: string, callback: EnvironmentCallback): Promise<void>;
 export {};

package/dist/commandContext.js

@@ -1,40 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.withEnvironment = withEnvironment;
+exports.withPublicEnvironment = withPublicEnvironment;
 const config_1 = require("./config");
 const apiClient_1 = require("./apiClient");
 const environment_1 = require("./environment");
 const messages_1 = require("./messages");
-async function withEnvironment(command, actionLabel, callback) {
-    const cfg = (0, config_1.loadConfig)();
-    if (!cfg.env) {
+const DEFAULT_PUBLIC_ENV = 'prod';
+function resolveConfiguredEnvironment(cfg, command, options) {
+    const configuredEnv = typeof cfg.env === 'string' && cfg.env.trim().length > 0
+        ? cfg.env.trim()
+        : undefined;
+    if (!configuredEnv && options.requireAuth) {
         (0, messages_1.printConfigEnvironmentMissing)(command);
         process.exitCode = 1;
-        return;
-    }
-    if (!cfg.token) {
-        (0, messages_1.printLoginRequired)(actionLabel, command);
-        process.exitCode = 1;
-        return;
+        return null;
     }
-    const envConfig = (0, environment_1.resolveEnvironmentConfig)(cfg.env);
+    const envName = configuredEnv ?? (options.allowDefaultPublicEnv ? DEFAULT_PUBLIC_ENV : undefined);
+    const envConfig = (0, environment_1.resolveEnvironmentConfig)(envName);
     if (!envConfig) {
         const choices = (0, environment_1.formatEnvironmentList)();
-        (0, messages_1.printUnknownEnvironment)(cfg.env, choices, command);
+        (0, messages_1.printUnknownEnvironment)(envName || '', choices, command);
         process.exitCode = 1;
-        return;
+        return null;
     }
     if (envConfig.allowInsecureRequests) {
         process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
     }
+    return envConfig;
+}
+function buildContext(cfg, envConfig) {
     const client = (0, apiClient_1.createCliApiClient)({ baseUrl: envConfig.apiBase, token: cfg.token });
     const aiClient = (0, apiClient_1.createCliAiClient)({ baseUrl: envConfig.aiBase, token: cfg.token });
-    await callback({
+    return {
         client,
         aiClient,
-        env: cfg.env,
+        env: envConfig.name,
         envConfig,
-        token: cfg.token,
+        token: cfg.token || '',
         config: cfg,
+    };
+}
+async function withEnvironment(command, actionLabel, callback) {
+    const cfg = (0, config_1.loadConfig)();
+    if (!cfg.token) {
+        (0, messages_1.printLoginRequired)(actionLabel, command);
+        process.exitCode = 1;
+        return;
+    }
+    const envConfig = resolveConfiguredEnvironment(cfg, command, {
+        requireAuth: true,
+        allowDefaultPublicEnv: false,
     });
+    if (!envConfig) {
+        return;
+    }
+    await callback(buildContext(cfg, envConfig));
+}
+async function withPublicEnvironment(command, callback) {
+    const cfg = (0, config_1.loadConfig)();
+    const envConfig = resolveConfiguredEnvironment(cfg, command, {
+        requireAuth: false,
+        allowDefaultPublicEnv: true,
+    });
+    if (!envConfig) {
+        return;
+    }
+    await callback(buildContext(cfg, envConfig));
 }

package/dist/commands/browse.d.ts

@@ -0,0 +1,16 @@
+export type BrowseKind = 'app' | 'asset' | 'asset-pack' | 'all';
+export type BrowseCreator = 'all' | 'me' | string;
+export type BrowseOptions = {
+    kind?: string;
+    creator?: string;
+    appType?: string;
+    assetCategory?: string;
+    assetSubcategory?: string;
+    limit?: string | number;
+    offset?: string | number;
+    json?: boolean;
+};
+export declare function browse(options?: BrowseOptions): Promise<void>;
+export declare function browseCategories(options?: {
+    json?: boolean;
+}): Promise<void>;