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

package/dist/commands/create.js

@@ -166,15 +166,6 @@ const DEFAULT_SURFACE_TARGETS = {
     mobilePortrait: app_1.DEFAULT_APP_SURFACE_TARGETS.includes('MOBILE_PORTRAIT'),
 };
 const DEFAULT_APP_VERSION = '1.0.0';
-const APP_TYPE_SLUGS = {
-    game: 'GAME',
-    template: 'TEMPLATE',
-    templates: 'TEMPLATE',
-    tool: 'TOOL',
-    tools: 'TOOL',
-    demo: 'DEMO',
-    demos: 'DEMO',
-};
 function makeDefaultAppEntry(name, filePath) {
     return {
         name,
@@ -192,8 +183,8 @@ function buildCatalogueEntry(name, metadata, sourceInfo, relativeFilePath) {
         if (sourceInfo.templateSlug) {
             entry.templateSource = sourceInfo.templateSlug;
         }
-        if (sourceInfo.remixSlug) {
-            entry.remixSource = sourceInfo.remixSlug;
+        if (sourceInfo.remixRef) {
+            entry.remix = sourceInfo.remixRef;
         }
         return entry;
     }
@@ -260,14 +251,14 @@ function buildCatalogueEntry(name, metadata, sourceInfo, relativeFilePath) {
     else if (sourceInfo.templateSlug) {
         entry.templateSource = sourceInfo.templateSlug;
     }
-    if (Object.prototype.hasOwnProperty.call(metadata, 'remixSource')) {
-        const remixSource = metadata.remixSource;
-        if (remixSource === null || typeof remixSource === 'string') {
-            entry.remixSource = remixSource;
+    if (Object.prototype.hasOwnProperty.call(metadata, 'remix')) {
+        const remix = metadata.remix;
+        if (remix === null || typeof remix === 'string') {
+            entry.remix = remix;
         }
     }
-    else if (sourceInfo.remixSlug) {
-        entry.remixSource = sourceInfo.remixSlug;
+    else if (sourceInfo.remixRef) {
+        entry.remix = sourceInfo.remixRef;
     }
     return entry;
 }
@@ -321,20 +312,20 @@ function logCatalogueOutcome(result, name) {
     const label = (0, node_path_1.relative)(process.cwd(), result.path) || CATALOGUE_FILENAME;
     if (result.error === 'invalid_json') {
         (0, messages_1.printErrorWithHelp)(`Could not update ${label} because it contains invalid JSON.`, [
-            `Fix the JSON in ${label} and add ${name} to the apps list, then rerun "playdrop-cli create ${name}" if needed.`
-        ], { command: 'create' });
+            `Fix the JSON in ${label} and add ${name} to the apps list, then rerun "playdrop project create app ${name}" if needed.`
+        ], { command: 'project create app' });
         process.exitCode = process.exitCode || 1;
         return false;
     }
     if (result.error === 'legacy_games_property') {
         (0, messages_1.printErrorWithHelp)(`${label} still uses the legacy "games" catalogue field.`, [
-            'Rename the top-level "games" array to "apps" and rerun `playdrop-cli create`. This rename removes the old terminology.'
-        ], { command: 'create' });
+            'Rename the top-level "games" array to "apps" and rerun `playdrop project create app`. This rename removes the old terminology.'
+        ], { command: 'project create app' });
         process.exitCode = process.exitCode || 1;
         return false;
     }
     if (result.error === 'invalid_schema_version') {
-        (0, messages_1.printErrorWithHelp)(`${label} must set "schemaVersion": 2.`, ['Update the file to schema v2 and rerun `playdrop-cli create`.'], { command: 'create' });
+        (0, messages_1.printErrorWithHelp)(`${label} must set "schemaVersion": 2.`, ['Update the file to schema v2 and rerun `playdrop project create app`.'], { command: 'project create app' });
         process.exitCode = process.exitCode || 1;
         return false;
     }
@@ -419,8 +410,8 @@ function updateExtractedProjectCatalogue(name, metadata, projectCataloguePath, s
         if (sourceInfo.templateSlug) {
             existing.templateSource = sourceInfo.templateSlug;
         }
-        if (sourceInfo.remixSlug) {
-            existing.remixSource = sourceInfo.remixSlug;
+        if (sourceInfo.remixRef) {
+            existing.remix = sourceInfo.remixRef;
         }
         apps[targetIndex] = existing;
     }
@@ -432,20 +423,20 @@ function logProjectCatalogueOutcome(result, name) {
     const label = (0, node_path_1.relative)(process.cwd(), result.path) || CATALOGUE_FILENAME;
     if (result.error === 'invalid_json') {
         (0, messages_1.printErrorWithHelp)(`Could not update ${label} because it contains invalid JSON.`, [
-            `Fix the JSON in ${label} and add ${name} to the apps list, then rerun "playdrop-cli create ${name}" if needed.`
-        ], { command: 'create' });
+            `Fix the JSON in ${label} and add ${name} to the apps list, then rerun "playdrop project create app ${name}" if needed.`
+        ], { command: 'project create app' });
         process.exitCode = process.exitCode || 1;
         return false;
     }
     if (result.error === 'legacy_games_property') {
         (0, messages_1.printErrorWithHelp)(`${label} still uses the legacy "games" catalogue field.`, [
-            'Rename the top-level "games" array to "apps" and rerun `playdrop-cli create`. This rename removes the old terminology.'
-        ], { command: 'create' });
+            'Rename the top-level "games" array to "apps" and rerun `playdrop project create app`. This rename removes the old terminology.'
+        ], { command: 'project create app' });
         process.exitCode = process.exitCode || 1;
         return false;
     }
     if (result.error === 'invalid_schema_version') {
-        (0, messages_1.printErrorWithHelp)(`${label} must set "schemaVersion": 2.`, ['Update the file to schema v2 and rerun `playdrop-cli create`.'], { command: 'create' });
+        (0, messages_1.printErrorWithHelp)(`${label} must set "schemaVersion": 2.`, ['Update the file to schema v2 and rerun `playdrop project create app`.'], { command: 'project create app' });
         process.exitCode = process.exitCode || 1;
         return false;
     }
@@ -454,13 +445,47 @@ function logProjectCatalogueOutcome(result, name) {
     }
     return true;
 }
+function buildPendingExternalRemixTask(name, metadata, sourceInfo, cataloguePath, htmlFilePath) {
+    const absoluteCataloguePath = (0, node_path_1.resolve)(cataloguePath);
+    const catalogueDir = (0, node_path_1.dirname)(absoluteCataloguePath);
+    const absoluteHtmlPath = (0, node_path_1.resolve)(htmlFilePath);
+    const relativeFilePath = (0, node_path_1.relative)(catalogueDir, absoluteHtmlPath) || `${name}.html`;
+    const entry = buildCatalogueEntry(name, metadata, sourceInfo, relativeFilePath.replace(/\\/g, '/'));
+    const surfaceTargets = (0, catalogue_utils_1.parseSurfaceTargets)(entry.surfaceTargets ?? DEFAULT_SURFACE_TARGETS).list;
+    return {
+        kind: 'app',
+        name,
+        cataloguePath: (0, node_path_1.relative)(process.cwd(), absoluteCataloguePath) || CATALOGUE_FILENAME,
+        catalogueAbsolutePath: absoluteCataloguePath,
+        catalogueDir,
+        filePath: absoluteHtmlPath,
+        relativeFile: entry.file ?? relativeFilePath,
+        projectDir: (0, node_path_1.dirname)(absoluteHtmlPath),
+        packageJsonPath: null,
+        isTypescriptProject: false,
+        hasValidateScript: false,
+        hasFormatScript: false,
+        displayName: entry.displayName,
+        description: entry.description,
+        type: typeof entry.type === 'string' ? ((0, app_1.parseAppType)(entry.type) ?? undefined) : undefined,
+        emoji: entry.emoji,
+        color: entry.color,
+        surfaceTargets,
+        missingMetadata: [],
+        version: entry.version,
+        remix: typeof entry.remix === 'string' ? entry.remix : undefined,
+        embeddedAssets: [],
+        uses: { assets: [], packs: [] },
+        graph: { relations: [] },
+    };
+}
 function logNextSteps(name, options) {
     console.log('\nNext steps:');
     if (options.hasCatalogue && options.catalogueLabel) {
         console.log(` - Review ${options.catalogueLabel} to set displayName, description, emoji, color, type, and surfaceTargets as needed.`);
     }
     else {
-        console.log(' - Run "playdrop-cli init ." when you are ready to add catalogue metadata and project docs.');
+        console.log(' - Run "playdrop project init ." when you are ready to add catalogue metadata and project docs.');
     }
     if (options.projectDir) {
         console.log(` - Open ${options.projectDir} to continue building your project.`);
@@ -474,15 +499,24 @@ function logNextSteps(name, options) {
         }
         console.log(` - The bundled HTML entry point is ${options.entryPointLabel}.`);
     }
+    else if (options.externalListingUrl) {
+        console.log(` - Open the external listing at ${options.externalListingUrl} and fetch the real source yourself.`);
+        console.log(` - Keep ${options.entryPointLabel} as the app entry point, or update catalogue.json if your source uses a different file.`);
+    }
     else {
         console.log(` - Build your app in ${options.entryPointLabel}.`);
     }
-    console.log(` - Test locally with "playdrop-cli dev ${name}".`);
+    if (options.externalListingUrl) {
+        console.log(` - After you add the real source for ${options.entryPointLabel}, test locally with "playdrop project dev ${name}".`);
+    }
+    else {
+        console.log(` - Test locally with "playdrop project dev ${name}".`);
+    }
     if (options.hasCatalogue) {
-        console.log(` - Deploy a single app with "playdrop-cli upload ${name}" or everything in the catalogue with "playdrop-cli upload .".`);
+        console.log(` - Publish a single app with "playdrop project publish ${name}" or everything in the catalogue with "playdrop project publish .".`);
     }
     else {
-        console.log(' - After running "playdrop-cli init", upload with "playdrop-cli upload ." to share your project.');
+        console.log(' - After running "playdrop project init", publish with "playdrop project publish ." to share your project.');
     }
 }
 async function promptInit() {
@@ -490,7 +524,7 @@ async function promptInit() {
         return false;
     }
     const rl = promises_1.default.createInterface({ input: node_process_1.stdin, output: node_process_1.stdout });
-    const answer = await rl.question('No catalogue.json found. Run "playdrop-cli init ." first? (y/N) ');
+    const answer = await rl.question('No catalogue.json found. Run "playdrop project init ." first? (y/N) ');
     rl.close();
     return /^y(es)?$/i.test(answer.trim());
 }
@@ -498,11 +532,11 @@ async function ensureLocalCatalogue(cataloguePath) {
     if ((0, node_fs_1.existsSync)(cataloguePath)) {
         return { path: cataloguePath, initSummary: null, created: false };
     }
-    const shouldInit = await promptInit();
+    const shouldInit = node_process_1.stdin.isTTY && node_process_1.stdout.isTTY ? await promptInit() : true;
     if (!shouldInit) {
         (0, messages_1.printErrorWithHelp)('A local catalogue.json is required to register app metadata next to the app file.', [
-            'Run "playdrop-cli init ." in this directory to create catalogue.json and starter docs before running "playdrop-cli create".'
-        ], { command: 'create', includeGeneralHelp: false });
+            'Run "playdrop project init ." in this directory to create catalogue.json and starter docs before running "playdrop project create app".'
+        ], { command: 'project create app', includeGeneralHelp: false });
         process.exitCode = process.exitCode || 1;
         return null;
     }
@@ -535,24 +569,17 @@ function warnMissingWorkspaceReadme(cataloguePath) {
     }
     const workspaceLabel = (0, node_path_1.relative)(process.cwd(), workspaceRoot) || '.';
     const initCommandTarget = workspaceLabel === '.' ? '.' : workspaceLabel;
-    console.log(`\nWorkspace docs reminder: README.md is missing at ${workspaceLabel}. Add documentation there or run "playdrop-cli init ${initCommandTarget}" before creating apps next time to auto-populate it.`);
+    console.log(`\nWorkspace docs reminder: README.md is missing at ${workspaceLabel}. Add documentation there or run "playdrop project init ${initCommandTarget}" before creating apps next time to auto-populate it.`);
 }
 function parseTemplateKey(value) {
     const parts = value.split('/').map((part) => part.trim()).filter(Boolean);
-    if (parts.length === 1) {
-        const slug = parts[0];
-        if (!slug) {
-            return null;
-        }
-        return { namespace: 'playdrop', slug, key: `playdrop/template/${slug}` };
-    }
     if (parts.length >= 3) {
         const [creator, typeSegment, ...rest] = parts;
         if (!creator) {
             return null;
         }
         const normalizedType = typeSegment.toLowerCase();
-        if (normalizedType !== 'template' && normalizedType !== 'templates') {
+        if (normalizedType !== 'template') {
             return null;
         }
         const slug = rest.join('/');
@@ -563,49 +590,67 @@ function parseTemplateKey(value) {
     }
     return null;
 }
-function parseRemixKey(value) {
-    const parts = value.split('/').map((part) => part.trim()).filter(Boolean);
-    if (parts.length < 3) {
-        return null;
-    }
-    const [creator, typeSegment, ...rest] = parts;
-    if (!creator) {
-        return null;
-    }
-    const normalizedType = typeSegment.toLowerCase();
-    const mappedType = APP_TYPE_SLUGS[normalizedType];
-    if (!mappedType) {
-        return null;
-    }
-    const name = rest.join('/');
-    if (!name) {
+function parseRemixRef(value) {
+    const parsed = (0, types_1.parseContentVersionRef)(value);
+    if (!parsed || parsed.kind !== 'app') {
         return null;
     }
     return {
-        creator,
-        name,
-        type: mappedType,
-        typeSlug: mappedType.toLowerCase(),
+        creator: parsed.creatorUsername,
+        name: parsed.name,
+        version: parsed.version,
+        ref: (0, types_1.formatContentVersionRef)(parsed),
     };
 }
-async function fetchRemixScaffold(client, creator, app) {
+async function fetchRemixScaffold(client, creator, app, version) {
     try {
-        const response = await client.fetchRemixScaffold(creator, app);
+        const response = await client.fetchRemixScaffold(creator, app, version);
+        const remixMode = typeof response?.remixMode === 'string' ? response.remixMode : '';
         const archiveUrl = typeof response?.archiveUrl === 'string' && response.archiveUrl.trim().length > 0
             ? response.archiveUrl.trim()
             : null;
         const htmlContent = typeof response?.html === 'string' ? response.html : null;
-        if (!archiveUrl && !htmlContent) {
-            throw new Error('Remix response missing scaffold content');
-        }
+        const externalListingUrl = typeof response?.externalListingUrl === 'string' && response.externalListingUrl.trim().length > 0
+            ? response.externalListingUrl.trim()
+            : null;
         const metadata = response.metadata;
         const entryPoint = extractEntryPointFromMetadata(metadata);
-        return {
-            html: htmlContent,
-            metadata,
-            archiveUrl,
-            entryPoint,
-        };
+        if (remixMode === 'archive') {
+            if (!archiveUrl) {
+                throw new Error('Remix response missing archiveUrl');
+            }
+            return {
+                html: null,
+                metadata,
+                archiveUrl,
+                entryPoint,
+                sourceVersion: version,
+            };
+        }
+        if (remixMode === 'inline-html') {
+            if (!htmlContent) {
+                throw new Error('Remix response missing html');
+            }
+            return {
+                html: htmlContent,
+                metadata,
+                entryPoint,
+                sourceVersion: null,
+            };
+        }
+        if (remixMode === 'external-metadata-only') {
+            if (!externalListingUrl) {
+                throw new Error('Remix response missing externalListingUrl');
+            }
+            return {
+                html: null,
+                metadata,
+                externalListingUrl,
+                entryPoint,
+                sourceVersion: null,
+            };
+        }
+        throw new Error(`Unsupported remix mode: ${remixMode || 'missing'}`);
     }
     catch (unknownError) {
         if (unknownError instanceof types_1.UnsupportedClientError) {
@@ -618,6 +663,14 @@ async function fetchRemixScaffold(client, creator, app) {
         throw unknownError;
     }
 }
+async function resolveAuthenticatedCreatorUsername(client) {
+    const response = await client.me();
+    const username = typeof response?.user?.username === 'string' ? response.user.username.trim() : '';
+    if (!username) {
+        throw new Error('missing_creator_username');
+    }
+    return username;
+}
 async function fetchTemplateScaffold(client, namespace, slug) {
     try {
         const response = await client.fetchTemplateScaffold(namespace, slug);
@@ -672,8 +725,8 @@ async function create(name, options = {}) {
     const existingLookup = (0, catalogue_1.resolveCatalogueEntries)(process.cwd(), { filterName: name });
     if (existingLookup.errors.length > 0) {
         for (const error of existingLookup.errors) {
-            (0, messages_1.printErrorWithHelp)(error, ['Fix the catalogue issues noted above, then rerun "playdrop-cli create".'], {
-                command: 'create',
+            (0, messages_1.printErrorWithHelp)(error, ['Fix the catalogue issues noted above, then rerun "playdrop project create app".'], {
+                command: 'project create app',
                 includeGeneralHelp: false,
             });
         }
@@ -682,8 +735,8 @@ async function create(name, options = {}) {
     }
     if (existingLookup.apps.length > 1) {
         (0, messages_1.printErrorWithHelp)(`Multiple catalogue entries share the app name "${name}".`, [
-            'Ensure each app has a unique name across catalogue.json files before running "playdrop-cli create".'
-        ], { command: 'create' });
+            'Ensure each app has a unique name across catalogue.json files before running "playdrop project create app".'
+        ], { command: 'project create app' });
         process.exitCode = 1;
         return;
     }
@@ -691,24 +744,22 @@ async function create(name, options = {}) {
     const reuseExistingApp = existingTask !== null && !templateOptionRaw && !remixOptionRaw;
     if (!reuseExistingApp && ((0, node_fs_1.existsSync)(file) || (0, node_fs_1.existsSync)(projectDirCandidate))) {
         (0, messages_1.printErrorWithHelp)(`Cannot create ${name} because a file or directory with that name already exists.`, [
-            'Choose a different app name or remove the existing file before running "playdrop-cli create" again.'
-        ], { command: 'create' });
+            'Choose a different app name or remove the existing file before running "playdrop project create app" again.'
+        ], { command: 'project create app' });
         process.exitCode = 1;
         return;
     }
     if (templateOptionRaw && remixOptionRaw) {
-        (0, messages_1.printErrorWithHelp)('Cannot use --template and --remix at the same time.', [
-            'Choose one source: use "--remix {creator}/{type}/{name}" to remix an existing app, or "--template {creator}/template/{name}" to start from a template.'
-        ], { command: 'create' });
+        (0, messages_1.printErrorWithHelp)('Cannot use --template and --remix at the same time.', ['Choose one source: use "--remix app:creator/name@1.2.3" to remix an app version, or "--template {creator}/template/{name}" to start from a template.'], { command: 'project create app' });
         process.exitCode = 1;
         return;
     }
     if (!templateOptionRaw && !remixOptionRaw) {
         if (!reuseExistingApp) {
             (0, messages_1.printErrorWithHelp)('Specify either --template or --remix when creating an app.', [
-                'Use "playdrop-cli list --type templates" to discover available templates.',
-                'Browse https://playdrop.ai, pick an app, and pass its key with "--remix creator/type/name".'
-            ], { command: 'create' });
+                'Use "playdrop browse --kind app --app-type template" to discover available templates.',
+                'Browse https://playdrop.ai, pick an app version, and pass its canonical ref with "--remix app:creator/name@1.2.3".'
+            ], { command: 'project create app' });
             process.exitCode = 1;
             return;
         }
@@ -718,7 +769,7 @@ async function create(name, options = {}) {
     const cfg = (0, config_1.loadConfig)();
     const envName = cfg.env;
     if (!envName) {
-        (0, messages_1.printLoginRequired)('Creating an app', 'create');
+        (0, messages_1.printLoginRequired)('Creating an app', 'project create app');
         process.exitCode = 1;
         return;
     }
@@ -727,13 +778,13 @@ async function create(name, options = {}) {
         const choices = (0, environment_1.formatEnvironmentList)();
         (0, messages_1.printErrorWithHelp)(`Environment "${envName}" from your Playdrop config is not supported.`, [
             `Available environments: ${choices}.`,
-            'Run "playdrop-cli login --env <env>" to save a supported environment before creating apps.'
-        ], { command: 'create', includeGeneralHelp: false });
+            'Run "playdrop auth login --env <env>" to save a supported environment before creating apps.'
+        ], { command: 'project create app', includeGeneralHelp: false });
         process.exitCode = 1;
         return;
     }
     if (!cfg.token) {
-        (0, messages_1.printLoginRequired)('Creating an app', 'create');
+        (0, messages_1.printLoginRequired)('Creating an app', 'project create app');
         process.exitCode = 1;
         return;
     }
@@ -750,23 +801,24 @@ async function create(name, options = {}) {
     let projectCataloguePath = null;
     const client = (0, apiClient_1.createCliApiClient)({ baseUrl: envConfig.apiBase, token: cfg.token });
     const sourceInfo = {};
+    let remixSourceTarget = null;
     let scaffold = null;
     let provenanceMessage = '';
     if (!reuseExistingApp && remixOption) {
-        const parsed = parseRemixKey(remixOption);
+        const parsed = parseRemixRef(remixOption);
         if (!parsed) {
-            (0, messages_1.printErrorWithHelp)('The --remix value must use the {creator}/{type}/{name} key format.', [
-                'Example: playdrop/game/hangingout.',
-                'Use "playdrop-cli list --type app" to find remixable keys.'
-            ], { command: 'create' });
+            (0, messages_1.printErrorWithHelp)('The --remix value must use canonical app version ref format.', [
+                'Example: app:playdrop/hangingout@1.2.3.',
+                'Use "playdrop browse --kind app" or "playdrop search <query> --kind app" to find remixable apps.'
+            ], { command: 'project create app' });
             process.exitCode = 1;
             return;
         }
-        const remixKeyDisplay = `${parsed.creator}/${parsed.typeSlug}/${parsed.name}`;
-        sourceInfo.remixSlug = remixKeyDisplay;
+        remixSourceTarget = { creator: parsed.creator, name: parsed.name, version: parsed.version };
+        sourceInfo.remixRef = parsed.ref;
         try {
-            scaffold = await fetchRemixScaffold(client, parsed.creator, parsed.name);
-            provenanceMessage = `Remixed from ${remixKeyDisplay}.`;
+            scaffold = await fetchRemixScaffold(client, parsed.creator, parsed.name, parsed.version);
+            provenanceMessage = `Remixed from ${parsed.ref}.`;
         }
         catch (error) {
             if (error instanceof http_1.CLIUnsupportedClientError) {
@@ -782,7 +834,7 @@ async function create(name, options = {}) {
             (0, messages_1.printErrorWithHelp)(problem, [
                 'Confirm the key is correct and that you have access to remix the source app.',
                 'Retry once you are logged in and the Playdrop API is reachable.'
-            ], { command: 'create' });
+            ], { command: 'project create app' });
             process.exitCode = 1;
             return;
         }
@@ -796,8 +848,8 @@ async function create(name, options = {}) {
             if (!parsed) {
                 (0, messages_1.printErrorWithHelp)('The --template value must use the {creator}/template/{name} key format.', [
                     'Example: playdrop/template/typescript_template.',
-                    'You can also pass a short name like "starter" to use playdrop/template/starter.'
-                ], { command: 'create' });
+                    'Use the exact template ref shown in Playdrop.'
+                ], { command: 'project create app' });
                 process.exitCode = 1;
                 return;
             }
@@ -820,7 +872,7 @@ async function create(name, options = {}) {
                 (0, messages_1.printErrorWithHelp)(problem, [
                     'Verify the template key and ensure you are logged in.',
                     'Retry when the Playdrop API is reachable.'
-                ], { command: 'create' });
+                ], { command: 'project create app' });
                 process.exitCode = 1;
                 return;
             }
@@ -828,13 +880,16 @@ async function create(name, options = {}) {
     }
     if (!reuseExistingApp && !scaffold) {
         (0, messages_1.printErrorWithHelp)('Failed to retrieve scaffold data. Specify a valid --template or --remix key and try again.', [
-            'Use "playdrop-cli list --type templates" to discover available templates.',
-            'Browse https://playdrop.ai and copy an app key to pass with "--remix".'
-        ], { command: 'create' });
+            'Use "playdrop browse --kind app --app-type template" to discover available templates.',
+            'Browse https://playdrop.ai and copy an exact app version ref to pass with "--remix".'
+        ], { command: 'project create app' });
         process.exitCode = 1;
         return;
     }
     const hasArchive = !reuseExistingApp && typeof scaffold?.archiveUrl === 'string' && scaffold.archiveUrl?.trim().length > 0;
+    const externalRemixListingUrl = !reuseExistingApp && typeof scaffold?.externalListingUrl === 'string' && scaffold.externalListingUrl.trim().length > 0
+        ? scaffold.externalListingUrl.trim()
+        : null;
     let htmlFilePath = reuseExistingApp && existingTask ? existingTask.filePath : '';
     let projectDir = reuseExistingApp && existingTask ? existingTask.projectDir : null;
     let packageJsonPath = reuseExistingApp && existingTask ? existingTask.packageJsonPath ?? null : null;
@@ -853,13 +908,15 @@ async function create(name, options = {}) {
         }
         catch (error) {
             (0, messages_1.printErrorWithHelp)(`Cannot create ${projectDir} because it already exists.`, [
-                'Remove or rename the existing directory before running "playdrop-cli create" again.'
-            ], { command: 'create' });
+                'Remove or rename the existing directory before running "playdrop project create app" again.'
+            ], { command: 'project create app' });
             process.exitCode = 1;
             return;
         }
         try {
-            const archiveBuffer = await downloadArchive(scaffold.archiveUrl);
+            const archiveBuffer = remixSourceTarget
+                ? new Uint8Array(await (await client.downloadAppSource(remixSourceTarget.creator, remixSourceTarget.name, remixSourceTarget.version)).blob.arrayBuffer())
+                : await downloadArchive(scaffold.archiveUrl);
             const extraction = extractProjectArchive(archiveBuffer, projectDir);
             const extractedCatalogue = (0, node_path_1.resolve)(projectDir, CATALOGUE_FILENAME);
             projectCataloguePath = (0, node_fs_1.existsSync)(extractedCatalogue) ? extractedCatalogue : null;
@@ -888,7 +945,7 @@ async function create(name, options = {}) {
                 (0, node_fs_1.rmSync)(projectDir, { recursive: true, force: true });
                 (0, messages_1.printErrorWithHelp)('Extracted project archive did not include an HTML entry point.', [
                     'Check the template archive and ensure playdrop.project.json specifies a valid entryPoint before retrying.'
-                ], { command: 'create' });
+                ], { command: 'project create app' });
                 process.exitCode = 1;
                 return;
             }
@@ -901,7 +958,7 @@ async function create(name, options = {}) {
             const detailMessage = typeof error?.message === 'string' && error.message.trim()
                 ? error.message.trim()
                 : 'Failed to download or extract the project archive.';
-            (0, messages_1.printNetworkIssue)(detailMessage, 'create');
+            (0, messages_1.printNetworkIssue)(detailMessage, 'project create app');
             process.exitCode = 1;
             return;
         }
@@ -912,8 +969,8 @@ async function create(name, options = {}) {
             htmlFilePath = existingTask.filePath;
             if (!(0, node_fs_1.existsSync)(htmlFilePath) || !(0, node_fs_1.statSync)(htmlFilePath).isFile()) {
                 (0, messages_1.printErrorWithHelp)(`Could not reuse existing app because ${htmlFilePath} does not exist.`, [
-                    'Update catalogue.json or remove the entry before rerunning "playdrop-cli create".'
-                ], { command: 'create' });
+                    'Update catalogue.json or remove the entry before rerunning "playdrop project create app".'
+                ], { command: 'project create app' });
                 process.exitCode = 1;
                 return;
             }
@@ -921,12 +978,15 @@ async function create(name, options = {}) {
             packageJsonPath = existingTask.packageJsonPath ?? null;
             cataloguePathToUse = existingTask.catalogueAbsolutePath;
         }
+        else if (externalRemixListingUrl) {
+            htmlFilePath = file;
+        }
         else if (!scaffold?.html) {
-            (0, messages_1.printNetworkIssue)('Unable to retrieve template content for playdrop-cli create.', 'create');
+            (0, messages_1.printNetworkIssue)('Unable to retrieve template content for playdrop project create app.', 'project create app');
             process.exitCode = 1;
             return;
         }
-        if (!reuseExistingApp) {
+        if (!reuseExistingApp && !externalRemixListingUrl) {
             htmlFilePath = file;
             const scaffoldHtml = scaffold.html;
             (0, node_fs_1.writeFileSync)(htmlFilePath, scaffoldHtml);
@@ -966,9 +1026,9 @@ async function create(name, options = {}) {
                 ? error.message
                 : `Could not update ${fallbackLabel} because it contains invalid JSON.`;
             const suggestions = typeof error?.message === 'string' && error.message.includes('surfaceTargets')
-                ? ['Fix the catalogue entry described above, then rerun "playdrop-cli create".']
-                : [`Fix the JSON in ${fallbackLabel} and add ${name} again before rerunning "playdrop-cli create".`];
-            (0, messages_1.printErrorWithHelp)(message, suggestions, { command: 'create' });
+                ? ['Fix the catalogue entry described above, then rerun "playdrop project create app".']
+                : [`Fix the JSON in ${fallbackLabel} and add ${name} again before rerunning "playdrop project create app".`];
+            (0, messages_1.printErrorWithHelp)(message, suggestions, { command: 'project create app' });
             process.exitCode = 1;
             return;
         }
@@ -981,13 +1041,20 @@ async function create(name, options = {}) {
     if (reuseExistingApp && existingTask) {
         registrationTask = existingTask;
     }
+    else if (!reuseExistingApp && externalRemixListingUrl && !(0, node_fs_1.existsSync)(htmlFilePath)) {
+        const pendingCataloguePath = workspaceCatalogueResult?.path ?? cataloguePathToUse;
+        if (!pendingCataloguePath) {
+            throw new Error('Missing catalogue path for external remix scaffold.');
+        }
+        registrationTask = buildPendingExternalRemixTask(name, scaffold.metadata, sourceInfo, pendingCataloguePath, htmlFilePath);
+    }
     else {
         const registrationLookup = (0, catalogue_1.resolveCatalogueEntries)(process.cwd(), { filterName: name });
         if (registrationLookup.errors.length > 0) {
             const otherErrors = registrationLookup.errors.filter((error) => typeof error !== 'string' || !error.includes('Duplicate app name'));
             if (otherErrors.length > 0) {
                 for (const error of otherErrors) {
-                    (0, messages_1.printErrorWithHelp)(error, ['Fix the catalogue issues noted above, then rerun "playdrop-cli create".'], { command: 'create', includeGeneralHelp: false });
+                    (0, messages_1.printErrorWithHelp)(error, ['Fix the catalogue issues noted above, then rerun "playdrop project create app".'], { command: 'project create app', includeGeneralHelp: false });
                 }
                 process.exitCode = 1;
                 return;
@@ -995,8 +1062,8 @@ async function create(name, options = {}) {
         }
         if (registrationLookup.apps.length === 0) {
             (0, messages_1.printErrorWithHelp)(`App "${name}" was not found in any catalogue.json after scaffolding.`, [
-                'Ensure catalogue.json was updated, then rerun "playdrop-cli create".'
-            ], { command: 'create' });
+                'Ensure catalogue.json was updated, then rerun "playdrop project create app".'
+            ], { command: 'project create app' });
             process.exitCode = 1;
             return;
         }
@@ -1027,8 +1094,8 @@ async function create(name, options = {}) {
         }
         if (!selectedTask) {
             (0, messages_1.printErrorWithHelp)(`Multiple catalogue entries share the app name "${name}".`, [
-                'Ensure each app has a unique name across catalogue.json files before running "playdrop-cli create".'
-            ], { command: 'create' });
+                'Ensure each app has a unique name across catalogue.json files before running "playdrop project create app".'
+            ], { command: 'project create app' });
             process.exitCode = 1;
             return;
         }
@@ -1046,9 +1113,40 @@ async function create(name, options = {}) {
             name,
             displayName,
         };
+        let creatorUsername = '';
+        try {
+            creatorUsername = await resolveAuthenticatedCreatorUsername(client);
+        }
+        catch (error) {
+            if (error instanceof http_1.CLIUnsupportedClientError) {
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof types_1.UnsupportedClientError) {
+                (0, http_1.handleUnsupportedError)(error, 'Resolve creator account');
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof types_1.ApiError) {
+                (0, messages_1.printErrorWithHelp)(`Failed to resolve your creator account (status ${error.status}).`, ['Run "playdrop auth login" to refresh your session, then try again.'], { command: 'project create app' });
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof TypeError) {
+                (0, messages_1.printNetworkIssue)('Could not reach the Playdrop API to resolve your creator account.', 'project create app');
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof Error && error.message === 'missing_creator_username') {
+                (0, messages_1.printErrorWithHelp)('The API did not return a creator username.', ['Run "playdrop auth login" again, then retry.'], { command: 'project create app' });
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
         let createConflict = false;
         try {
-            await client.createApp(createPayload);
+            await client.createApp(creatorUsername, createPayload);
             console.log(`Registered ${displayName} with the Playdrop API.`);
         }
         catch (error) {
@@ -1069,13 +1167,13 @@ async function create(name, options = {}) {
                 else {
                     (0, messages_1.printErrorWithHelp)(`Failed to register ${name} (status ${error.status}).`, [
                         'Ensure your account has creator permissions and retry once the issue is resolved.'
-                    ], { command: 'create' });
+                    ], { command: 'project create app' });
                     process.exitCode = 1;
                     return;
                 }
             }
             else if (error instanceof TypeError) {
-                (0, messages_1.printNetworkIssue)('Could not reach the Playdrop API to register the app.', 'create');
+                (0, messages_1.printNetworkIssue)('Could not reach the Playdrop API to register the app.', 'project create app');
                 process.exitCode = 1;
                 return;
             }
@@ -1093,7 +1191,7 @@ async function create(name, options = {}) {
         }
         if (Object.keys(updatePayload).length > 0) {
             try {
-                await client.updateApp(name, updatePayload);
+                await client.updateApp(creatorUsername, name, updatePayload);
                 if (createConflict) {
                     console.log(`Updated ${name} metadata on the Playdrop API.`);
                 }
@@ -1111,12 +1209,12 @@ async function create(name, options = {}) {
                 if (error instanceof types_1.ApiError) {
                     (0, messages_1.printErrorWithHelp)(`Failed to update ${name} metadata (status ${error.status}).`, [
                         'Update the catalogue entry and retry, or contact the Playdrop team if the issue persists.'
-                    ], { command: 'create' });
+                    ], { command: 'project create app' });
                     process.exitCode = 1;
                     return;
                 }
                 if (error instanceof TypeError) {
-                    (0, messages_1.printNetworkIssue)('Could not reach the Playdrop API to update the app.', 'create');
+                    (0, messages_1.printNetworkIssue)('Could not reach the Playdrop API to update the app.', 'project create app');
                     process.exitCode = 1;
                     return;
                 }
@@ -1167,6 +1265,7 @@ async function create(name, options = {}) {
         entryPointLabel,
         hasPackageJson,
         dependenciesInstalled,
+        externalListingUrl: externalRemixListingUrl,
     });
     if (workspaceCatalogueUpdated && workspaceCatalogueResult) {
         warnMissingWorkspaceReadme(workspaceCatalogueResult.path);