@playdrop/playdrop-cli 0.3.1-build.1

package/dist/index.js

@@ -0,0 +1,700 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const proxyFetch_1 = require("./proxyFetch");
+(0, proxyFetch_1.installProxyFetch)();
+const commander_1 = require("commander");
+const node_fs_1 = require("node:fs");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = require("node:path");
+const login_1 = require("./commands/login");
+const whoami_1 = require("./commands/whoami");
+const logout_1 = require("./commands/logout");
+const create_1 = require("./commands/create");
+const detail_1 = require("./commands/detail");
+const list_1 = require("./commands/list");
+const generation_1 = require("./commands/generation");
+const assets_1 = require("./commands/assets");
+const asset_packs_1 = require("./commands/asset-packs");
+const dev_1 = require("./commands/dev");
+const capture_1 = require("./commands/capture");
+const upload_1 = require("./commands/upload");
+const validate_1 = require("./commands/validate");
+const build_1 = require("./commands/build");
+const format_1 = require("./commands/format");
+const migrateCatalogueV2_1 = require("./commands/migrateCatalogueV2");
+const clientInfo_1 = require("./clientInfo");
+const upgrade_1 = require("./commands/upgrade");
+const init_1 = require("./commands/init");
+const messages_1 = require("./messages");
+const documentation_1 = require("./commands/documentation");
+const feedback_1 = require("./commands/feedback");
+const versions_1 = require("./commands/versions");
+function resolveInitTarget(pathArg) {
+    if (typeof pathArg === 'string' && pathArg.trim().length > 0) {
+        return pathArg.trim();
+    }
+    const cwdCatalogue = (0, node_path_1.join)(process.cwd(), 'catalogue.json');
+    if ((0, node_fs_1.existsSync)(cwdCatalogue)) {
+        return '.';
+    }
+    const homeDir = node_os_1.default.homedir();
+    const documentsDir = (0, node_path_1.join)(homeDir, 'Documents');
+    const baseDir = (0, node_fs_1.existsSync)(documentsDir) ? documentsDir : homeDir;
+    return (0, node_path_1.join)(baseDir, 'playdrop');
+}
+const program = new commander_1.Command();
+program
+    .name('playdrop-cli')
+    .description('Build, preview, and ship apps to the Playdrop platform.')
+    .usage('<command> [options]')
+    .version((0, clientInfo_1.getCliVersionLabel)(), '-v, --cli-version', 'Output CLI version information');
+program.showHelpAfterError();
+program.showSuggestionAfterError();
+program.addHelpText('afterAll', '\nFor command-specific flags, run `playdrop-cli <command> --help`.\n');
+const defaultHelp = program.createHelp();
+program.configureHelp({
+    formatHelp(cmd, helper) {
+        if (cmd === program) {
+            const defaultText = defaultHelp.formatHelp(cmd, helper);
+            const lines = defaultText.split('\n');
+            const remaining = lines.length > 4 ? lines.slice(4) : [];
+            const curated = [
+                'Usage: playdrop-cli <command> [options]',
+                '',
+                'Playdrop CLI - build, preview, and ship apps to the Playdrop platform.',
+                'Use it to authenticate, scaffold projects, run local previews, and publish updates.',
+                '',
+                'Getting Started',
+                '  login                            Sign in and store credentials.',
+                '  whoami                           Confirm the account tied to this machine.',
+                '  init <path>                      Bootstrap docs and catalogue.json for a project.',
+                '  create <name> --template <key>   Scaffold from a template key.',
+                '         <name> --remix <key>      Remix an existing app key.',
+                '  dev <name>                      Serve your app locally with Playdrop headers applied.',
+                '  capture [name]                 Run the app headlessly, capture logs, and take screenshots.',
+                '  validate <pathOrName>          Validate catalogue v2 entries without uploading.',
+                '  build <pathOrName>             Validate then regenerate assets without uploading.',
+                '  format <pathOrName>            Run formatters for apps, assets, and packs.',
+                '  migrate-catalogue-v2 [path]    Convert legacy catalogue keys into strict schema v2.',
+                '  upload <pathOrName>            Publish a single app or every entry in catalogue.json.',
+                '  feedback --title <title> [--comment ...|--file ...]  Send feedback with CLI metadata.',
+                '',
+                'More Commands',
+                '  list [--type ...]              List apps, assets, and packs.',
+                '  detail <key> [--format ...]     Show detailed metadata for an app, asset, or pack.',
+                '  generate <type> <prompt>        Generate an AI asset directly to your account.',
+                '  generations [--type ...]        List persisted AI generations.',
+                '  assets download-file <key>      Download a single asset file (role-scoped).',
+                '  assets download-source <key>    Download full source bundle ZIP for an asset revision.',
+                '  assets categories              List canonical asset categories and format constraints.',
+                '  assets versions <subcommand>   Manage asset revisions (list, publish, set-current, delete).',
+                '  asset-packs <subcommand>       Manage asset pack metadata and versions.',
+                '  asset-packs download-source <key>  Download full source bundle ZIP for a pack version.',
+                '  versions <subcommand>          Manage app versions (list, set-current, publish, etc.).',
+                '  documentation [path]            List CDN docs or print a specific entry.',
+                '  logout                           Clear saved credentials.',
+                '  upgrade [--dry-run]              Update the Playdrop CLI to the latest release.',
+                '',
+                'Next Steps',
+                '  1. Run `playdrop-cli login` to authenticate.',
+                '  2. Use `playdrop-cli init` (once per repo) and `playdrop-cli create` to spin up an app file.',
+                '  3. Preview with `playdrop-cli dev`, iterate, then ship with `playdrop-cli upload`.',
+                ''
+            ];
+            if (remaining.length > 0) {
+                curated.push(...remaining);
+            }
+            return curated.join('\n');
+        }
+        return defaultHelp.formatHelp(cmd, helper);
+    },
+    visibleOptions(cmd) {
+        if (cmd === program) {
+            return [];
+        }
+        return defaultHelp.visibleOptions(cmd);
+    },
+    visibleCommands(cmd) {
+        if (cmd === program) {
+            return [];
+        }
+        return defaultHelp.visibleCommands(cmd);
+    }
+});
+program.on('command:*', (unknownCommands) => {
+    const [unknownCommand] = unknownCommands;
+    if (unknownCommand === 'download') {
+        console.error('`playdrop-cli download` is not available. Use `playdrop-cli assets download-file <asset-key>` or `download-source` instead.');
+    }
+    else if (unknownCommand === 'ai') {
+        console.error('`playdrop-cli ai` is not available. Use `playdrop-cli generate <type> "<prompt>"` or `playdrop-cli generations`.');
+    }
+    else if (unknownCommand) {
+        console.error(`Unknown command "${unknownCommand}". Run "playdrop-cli help" for the full list of commands.`);
+    }
+    process.exitCode = 1;
+});
+const envOption = new commander_1.Option('--env <env>', 'Environment (dev|local|prod)');
+envOption.default?.('prod');
+envOption.hideHelp?.();
+const loginCommand = program
+    .command('login')
+    .description('Sign in to Playdrop')
+    .addOption(envOption)
+    .option('--username <username>', 'Username for non-interactive login')
+    .option('--password <password>', 'Password for non-interactive login');
+loginCommand.addHelpText('beforeAll', () => [
+    '',
+    'Authenticate this machine with Playdrop. Accounts are created on https://playdrop.ai, and every CLI command requires an active login before it will run.',
+    '',
+    'Examples:',
+    '  playdrop-cli login',
+    '  playdrop-cli login --username bot --password ********',
+    '  playdrop-cli login --env dev',
+    ''
+].join('\n'));
+loginCommand.addHelpText('afterAll', '\nVerify your session with `playdrop-cli whoami`, then run `playdrop-cli init` in the workspace where you plan to build your first app if you haven\'t bootstrapped it yet.\n');
+loginCommand.action(async (opts) => {
+    await (0, login_1.login)(opts.env, opts.username, opts.password);
+});
+program
+    .command('whoami')
+    .description('Show current user')
+    .action(async () => {
+    await (0, whoami_1.whoami)();
+});
+program
+    .command('logout')
+    .description('Logout of Playdrop')
+    .action(() => {
+    (0, logout_1.logout)();
+});
+const createCommand = program
+    .command('create <name>')
+    .description('Register and scaffold a Playdrop app')
+    .option('--template <key>', 'Template key in {creator}/template/{name} format (short names assume playdrop)')
+    .option('--remix <key>', 'Remix key in {creator}/{type}/{name} format');
+createCommand.addHelpText('beforeAll', () => [
+    '',
+    'Register a new app under your Playdrop account using either a template key or a remix key. The command downloads the scaffold assets, writes the HTML file, and adds the entry to catalogue.json, creating the catalogue if it does not exist yet.',
+    '',
+    'Examples:',
+    '  playdrop-cli create jumper --template playdrop/template/html_template',
+    '  playdrop-cli create remix-demo --remix playdrop/game/hangingout',
+    '',
+    'Key formats:',
+    '  --template expects {creator}/template/{name}; a bare name defaults to playdrop/template/<name>.',
+    '  --remix expects {creator}/{type}/{name} (e.g. playdrop/game/fly-remix).',
+    '',
+    'What happens:',
+    '  - Downloads the chosen template or remix and writes <name>.html.',
+    '  - Ensures catalogue.json exists and records the new app metadata.',
+    '  - Prints next steps so you can edit, preview, and upload.',
+    ''
+].join('\n'));
+createCommand.addHelpText('afterAll', '\nOnce the file is ready, iterate locally with `playdrop-cli dev <name>` and ship updates with `playdrop-cli upload`.\n');
+createCommand.action(async (name, opts) => {
+    await (0, create_1.create)(name, { template: opts.template, remix: opts.remix });
+});
+const listCommandInstance = program
+    .command('list')
+    .description('List apps, assets, and packs')
+    .option('--type <type>', 'Filter by type (default: all)')
+    .option('--creator <creator>', 'Filter by creator (default: me; accepts "me", "all", or a creator slug)')
+    .option('--max <number>', 'Maximum number of results to display (1-100, default: 10)')
+    .action(async (opts, cmd) => {
+    const rawArgs = Array.isArray(cmd.args) ? cmd.args : [];
+    const unexpectedArgs = rawArgs.filter((arg) => typeof arg === 'string' && arg.trim().length > 0);
+    if (unexpectedArgs.length > 0) {
+        const formatted = unexpectedArgs.length === 1
+            ? `Unexpected argument "${unexpectedArgs[0]}".`
+            : `Unexpected arguments: ${unexpectedArgs.map(arg => `"${arg}"`).join(', ')}.`;
+        (0, messages_1.printErrorWithHelp)(formatted, ['Use --type <value> to filter by type.', 'Example: playdrop-cli list --type templates.'], { command: 'list' });
+        process.exitCode = 1;
+        return;
+    }
+    await (0, list_1.list)({ type: opts.type, creator: opts.creator, max: opts.max });
+});
+listCommandInstance.addHelpText('beforeAll', () => [
+    '',
+    'List apps, assets, and packs available through your account.',
+    '',
+    'Examples:',
+    '  playdrop-cli list',
+    '  playdrop-cli list --type app',
+    '  playdrop-cli list --creator playdrop --type asset',
+    '  playdrop-cli list --max 25',
+    '',
+    'Supported type filters:',
+    '  all, app(s), game(s), template(s), tool(s), demo(s), asset(s), pack(s)',
+    '',
+    'Supported creator filters:',
+    '  all (default), me, <creator slug>',
+    '',
+].join('\n'));
+program
+    .command('capture [target]')
+    .description('Launch the Playdrop dev frame in Playwright, stream console logs, and exit on error.')
+    .option('--timeout <seconds>', 'Seconds to wait before shutting down (default: 5, max: 600)', value => parseFloat(value))
+    .option('--app <name>', 'Select an app when catalogue.json lists multiple entries')
+    .option('--log-level <level>', 'Minimum log level to display (debug|info|warn|error, default: info)')
+    .option('--screenshot <path>', 'Save a PNG screenshot to the provided relative path before exiting')
+    .option('--surface <target>', 'Surface target to emulate (desktop|mobile-landscape|mobile-portrait)')
+    .option('--username <username>', 'Override the saved login with a username for this capture run')
+    .option('--password <password>', 'Override the saved login with a password for this capture run')
+    .action(async (target, opts) => {
+    try {
+        await (0, capture_1.capture)(target, {
+            timeoutSeconds: opts.timeout,
+            appName: opts.app,
+            logLevel: opts.logLevel,
+            screenshotPath: opts.screenshot,
+            surfaceTarget: opts.surface,
+            username: opts.username,
+            password: opts.password,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            (error.message === 'Timeout must be a positive number of seconds.' ||
+                error.message === 'Timeout cannot exceed 600 seconds (10 minutes).')) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+});
+const documentationCommandInstance = program
+    .command('documentation [path]')
+    .description('List documentation entries or print a specific file from the CDN')
+    .action(async (targetPath) => {
+    await (0, documentation_1.documentation)(targetPath);
+});
+documentationCommandInstance.addHelpText('beforeAll', () => [
+    '',
+    'Read the latest Playdrop documentation directly from the CDN.',
+    'Without a path it prints every available entry.',
+    'Provide a relative path (such as "sdk/getting-started.md") to output the file contents.',
+    '',
+    'Examples:',
+    '  playdrop-cli documentation',
+    '  playdrop-cli documentation getting-started.md',
+    ''
+].join('\n'));
+const detailCommandInstance = program
+    .command('detail <key>')
+    .description('Show detailed metadata for an app, asset, or pack')
+    .option('--format <format>', 'Output format (text|json, default: text)')
+    .action(async (key, opts) => {
+    await (0, detail_1.detail)(key, { format: opts.format });
+});
+detailCommandInstance.addHelpText('beforeAll', () => [
+    '',
+    'Display complete information for a specific app, asset, or pack. Keys follow creator/type/name.',
+    '',
+    'Examples:',
+    '  playdrop-cli detail playdrop/game/jumper',
+    '  playdrop-cli detail playdrop/asset/astro --format json',
+    '  playdrop-cli detail playdrop/pack/starter-kit --format json',
+    '',
+    'Supported type segments include: game, template, tool, demo, asset, pack.',
+    '',
+].join('\n'));
+const generateCommandInstance = program
+    .command('generate <type> <prompt>')
+    .description('Generate an AI asset and save it to your account')
+    .option('--asset-name <name>', 'Optional asset slug override')
+    .option('--asset-display-name <name>', 'Optional asset display name override')
+    .option('--asset-description <description>', 'Optional asset description')
+    .option('--subcategory <subcategory>', 'Asset subcategory slug (example: music)')
+    .option('--visibility <visibility>', 'Asset visibility (private|public)')
+    .option('--input-assets <ids>', 'Comma-separated input asset version IDs')
+    .option('--attach-app-version-id <id>', 'Attach generated asset to an app version ID')
+    .option('--image1 <url>', 'Reference image URL 1 (image/video/model_3d)')
+    .option('--image2 <url>', 'Reference image URL 2 (image/video/model_3d)')
+    .option('--duration <value>', 'Duration (music defaults to ms; sfx/video defaults to seconds; supports 20s or 20000ms)')
+    .option('--instrumental', 'Force instrumental music output')
+    .option('--loop', 'Loop SFX output')
+    .option('--cover-prompt <prompt>', 'Cover image prompt for music or sfx')
+    .option('--ratio <ratio>', 'Aspect ratio (image: 1:1|3:4|9:16|4:3|16:9, video: 16:9|9:16)')
+    .option('--resolution <resolution>', 'Video resolution (720p)')
+    .option('--source-mode <mode>', 'Model 3D source mode (TEXT|IMAGE)')
+    .option('--topology <topology>', 'Model 3D topology (triangle|quad)')
+    .option('--polycount <count>', 'Model 3D target polycount')
+    .option('--remesh', 'Enable model 3D remeshing')
+    .option('--texture', 'Enable model 3D texturing')
+    .option('--timeout-seconds <seconds>', 'Timeout while waiting for a generation job to finish (default: 900)')
+    .option('--poll-interval-ms <ms>', 'Polling interval for generation job status (default: 1000)')
+    .action(async (type, prompt, opts) => {
+    await (0, generation_1.generate)(type, prompt, opts);
+});
+generateCommandInstance.addHelpText('beforeAll', () => [
+    '',
+    'Generate assets from text prompts in one command.',
+    '',
+    'Examples:',
+    '  playdrop-cli generate image "Pixel art hero portrait"',
+    '  playdrop-cli generate music "Boss battle intro" --duration 20s',
+    '  playdrop-cli generate sfx "Coin pickup blip" --duration 2s',
+    '  playdrop-cli generate video "Neon city flyover" --duration 4s --ratio 16:9',
+    '  playdrop-cli generate model_3d "Low poly treasure chest" --polycount 20000',
+    '',
+    'Modality values:',
+    '  image, music, sfx, video, model_3d',
+    '',
+].join('\n'));
+const generationsCommandInstance = program
+    .command('generations')
+    .description('List persisted AI generations')
+    .option('--type <type>', 'Filter by type (text|json|image|music|sfx|video|model_3d)')
+    .option('--limit <number>', 'Page size')
+    .option('--offset <number>', 'Offset')
+    .option('--format <format>', 'Output format (text|json, default: text)')
+    .action(async (opts) => {
+    await (0, generation_1.generations)(opts);
+});
+generationsCommandInstance.addHelpText('beforeAll', () => [
+    '',
+    'List your AI generation history and generated asset refs.',
+    '',
+    'Examples:',
+    '  playdrop-cli generations',
+    '  playdrop-cli generations --type image --limit 20',
+    '  playdrop-cli generations --type music --format json',
+    '',
+].join('\n'));
+const assetsCommand = program
+    .command('assets')
+    .description('Asset utility commands');
+assetsCommand
+    .command('categories')
+    .description('List canonical asset categories')
+    .option('--format <format>', 'Output format (text|json, default: text)')
+    .action(async (opts) => {
+    await (0, assets_1.listCategories)(opts);
+});
+assetsCommand
+    .command('download-file <assetRefOrKey>')
+    .description('Download a single role-scoped asset file')
+    .option('--revision <revision>', 'Specific revision (rN or N)')
+    .option('--role <role>', 'Manifest role to download (default: primary)')
+    .option('--out <path>', 'Output file path or directory (default: ./downloads)')
+    .action(async (assetRefOrKey, opts) => {
+    await (0, assets_1.downloadFile)(assetRefOrKey, opts);
+});
+assetsCommand
+    .command('download-source <assetRefOrKey>')
+    .description('Download canonical source ZIP for an asset revision')
+    .option('--revision <revision>', 'Specific revision (rN or N)')
+    .option('--out <path>', 'Output file path or directory (default: ./downloads)')
+    .action(async (assetRefOrKey, opts) => {
+    await (0, assets_1.downloadSource)(assetRefOrKey, opts);
+});
+assetsCommand
+    .command('update <assetRefOrKey>')
+    .description('Update asset metadata')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .option('--name <name>', 'Rename asset slug')
+    .option('--display-name <displayName>', 'Set display name')
+    .option('--description <description>', 'Set description text')
+    .option('--clear-description', 'Clear description')
+    .action(async (assetRefOrKey, opts) => {
+    await (0, assets_1.updateAssetByKey)(assetRefOrKey, opts);
+});
+const assetVersionsCommand = assetsCommand
+    .command('versions')
+    .description('Manage asset revisions');
+assetVersionsCommand
+    .command('list <assetRefOrKey>')
+    .description('List versions for an asset')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .option('--format <format>', 'Output format (text|json, default: text)')
+    .action(async (assetRefOrKey, opts) => {
+    await (0, assets_1.listAssetVersionsByKey)(assetRefOrKey, opts);
+});
+assetVersionsCommand
+    .command('set-current <assetRefOrKey> <revision>')
+    .description('Set an asset revision as current')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (assetRefOrKey, revision, opts) => {
+    await (0, assets_1.setCurrentAssetVersion)(assetRefOrKey, revision, opts);
+});
+assetVersionsCommand
+    .command('publish <assetRefOrKey> <revision>')
+    .description('Set asset version visibility to PUBLIC')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (assetRefOrKey, revision, opts) => {
+    await (0, assets_1.publishAssetVersion)(assetRefOrKey, revision, opts);
+});
+assetVersionsCommand
+    .command('unpublish <assetRefOrKey> <revision>')
+    .description('Set asset version visibility to PRIVATE')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (assetRefOrKey, revision, opts) => {
+    await (0, assets_1.unpublishAssetVersion)(assetRefOrKey, revision, opts);
+});
+assetVersionsCommand
+    .command('delete <assetRefOrKey> <revision>')
+    .description('Delete an asset version')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (assetRefOrKey, revision, opts) => {
+    await (0, assets_1.deleteAssetVersionByKey)(assetRefOrKey, revision, opts);
+});
+assetsCommand
+    .command('delete <assetRefOrKey>')
+    .description('Delete an asset')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (assetRefOrKey, opts) => {
+    await (0, assets_1.deleteAssetByKey)(assetRefOrKey, opts);
+});
+const assetPacksCommand = program
+    .command('asset-packs')
+    .description('Manage asset packs');
+assetPacksCommand
+    .command('download-source <packRefOrKey>')
+    .description('Download canonical source ZIP for an asset pack version')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .option('--version <version>', 'Specific semantic version (for example 1.0.0)')
+    .option('--out <path>', 'Output file path or directory (default: ./downloads)')
+    .action(async (packRefOrKey, opts) => {
+    await (0, asset_packs_1.downloadSource)(packRefOrKey, opts);
+});
+assetPacksCommand
+    .command('update <packRefOrKey>')
+    .description('Update asset pack metadata')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .option('--name <name>', 'Rename pack slug')
+    .option('--display-name <displayName>', 'Set display name')
+    .option('--description <description>', 'Set description text')
+    .option('--clear-description', 'Clear description')
+    .option('--preview-app-version-id <id>', 'Set preview app version id')
+    .option('--clear-preview-app-version-id', 'Clear preview app version id')
+    .action(async (packRefOrKey, opts) => {
+    await (0, asset_packs_1.updateAssetPackByKey)(packRefOrKey, opts);
+});
+const assetPackVersionsCommand = assetPacksCommand
+    .command('versions')
+    .description('Manage asset pack versions');
+assetPackVersionsCommand
+    .command('list <packRefOrKey>')
+    .description('List versions for an asset pack')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .option('--format <format>', 'Output format (text|json, default: text)')
+    .action(async (packRefOrKey, opts) => {
+    await (0, asset_packs_1.listAssetPackVersionsByKey)(packRefOrKey, opts);
+});
+assetPackVersionsCommand
+    .command('set-current <packRefOrKey> <version>')
+    .description('Set an asset pack version as current')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (packRefOrKey, version, opts) => {
+    await (0, asset_packs_1.setCurrentAssetPackVersion)(packRefOrKey, version, opts);
+});
+assetPackVersionsCommand
+    .command('publish <packRefOrKey> <version>')
+    .description('Set asset pack version visibility to PUBLIC')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (packRefOrKey, version, opts) => {
+    await (0, asset_packs_1.publishAssetPackVersion)(packRefOrKey, version, opts);
+});
+assetPackVersionsCommand
+    .command('unpublish <packRefOrKey> <version>')
+    .description('Set asset pack version visibility to PRIVATE')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (packRefOrKey, version, opts) => {
+    await (0, asset_packs_1.unpublishAssetPackVersion)(packRefOrKey, version, opts);
+});
+assetPackVersionsCommand
+    .command('delete <packRefOrKey> <version>')
+    .description('Delete an asset pack version')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (packRefOrKey, version, opts) => {
+    await (0, asset_packs_1.deleteAssetPackVersionByKey)(packRefOrKey, version, opts);
+});
+assetPacksCommand
+    .command('delete <packRefOrKey>')
+    .description('Delete an asset pack')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (packRefOrKey, opts) => {
+    await (0, asset_packs_1.deleteAssetPackByKey)(packRefOrKey, opts);
+});
+program
+    .command('dev [target]')
+    .description('Serve an app locally')
+    .option('--app <name>', 'Select an app name when multiple entries are present')
+    .action(async (target, opts) => {
+    await (0, dev_1.dev)(target, undefined, opts.app);
+});
+program
+    .command('validate <pathOrName>')
+    .description('Validate apps, assets, and packs without building or uploading')
+    .action(async (pathOrName) => {
+    await (0, validate_1.validate)(pathOrName);
+});
+program
+    .command('build <pathOrName>')
+    .description('Validate and regenerate assets without uploading')
+    .action(async (pathOrName) => {
+    await (0, build_1.build)(pathOrName);
+});
+program
+    .command('format <pathOrName>')
+    .description('Run formatters for apps, assets, and packs')
+    .action(async (pathOrName) => {
+    await (0, format_1.format)(pathOrName);
+});
+program
+    .command('migrate-catalogue-v2 [target]')
+    .description('Migrate legacy catalogue keys to strict schemaVersion 2')
+    .action(async (target) => {
+    await (0, migrateCatalogueV2_1.migrateCatalogueV2)(target || '.');
+});
+program
+    .command('upload <pathOrName>')
+    .description('Upload an app HTML file or a directory with a catalogue.json')
+    .option('--skip-ecs', 'Exclude ecs.json and server.js from the upload even if defined in catalogue.json')
+    .action(async (pathOrName, opts) => {
+    await (0, upload_1.upload)(pathOrName, { skipEcs: opts.skipEcs });
+});
+const feedbackCommand = program
+    .command('feedback')
+    .description('Submit feedback to the Playdrop team')
+    .option('--title <title>', 'Feedback title (max 70 characters)')
+    .option('--comment <comment>', 'Feedback comment text')
+    .option('--file <path>', 'Load comment text from a file')
+    .action(async (opts) => {
+    await (0, feedback_1.submitFeedback)(opts);
+});
+feedbackCommand
+    .command('list', { hidden: true })
+    .option('--limit <number>', 'Maximum number of entries to display (1-100)')
+    .option('--offset <number>', 'Result offset')
+    .option('--source <source>', 'Filter by source label')
+    .option('--user-id <id>', 'Filter by numeric user id')
+    .option('--format <format>', 'Output format (text|json, default: text)')
+    .action(async (opts) => {
+    await (0, feedback_1.listFeedback)(opts);
+});
+feedbackCommand
+    .command('delete <id>', { hidden: true })
+    .action(async (id) => {
+    await (0, feedback_1.deleteFeedback)(id);
+});
+const initCommandInstance = program
+    .command('init <path>')
+    .description('Prepare a Playdrop project folder');
+initCommandInstance.addHelpText('beforeAll', () => [
+    '',
+    'Bootstrap a folder so it is ready to create and publish Playdrop apps. The command adds the required scaffolding: catalogue.json plus starter README and AGENTS files, so you can get moving quickly.',
+    '',
+    'Examples:',
+    '  playdrop-cli init ~/Documents/playdrop',
+    '  playdrop-cli init .',
+    '  playdrop-cli init apps/dev',
+    '  playdrop-cli init apps/dev',
+    '',
+    'Behavior:',
+    '  - Ensures the target directory exists (creating it if needed).',
+    '  - Downloads the latest README and AGENTS templates for your environment.',
+    '  - Writes an empty catalogue.json that `playdrop-cli create` will populate.',
+    ''
+].join('\n'));
+initCommandInstance.exitOverride((err) => {
+    if (err && err.code === 'commander.missingArgument') {
+        (0, messages_1.printErrorWithHelp)('A target directory is required for init.', [
+            'Try "playdrop-cli init ~/Documents/playdrop" to create a workspace in Documents.',
+            'Or run "playdrop-cli init ." to bootstrap the current folder.',
+        ], { command: 'init' });
+        process.exitCode = 1;
+        return;
+    }
+    throw err;
+});
+initCommandInstance.addHelpText('afterAll', '\nAfter init, run `playdrop-cli create` to register apps, `playdrop-cli dev` to preview, and `playdrop-cli upload` to publish.\n');
+initCommandInstance.action(async (pathArg) => {
+    if (!pathArg || typeof pathArg !== 'string' || pathArg.trim().length === 0) {
+        (0, messages_1.printErrorWithHelp)('A target directory is required for init.', [
+            'Try "playdrop-cli init ~/Documents/playdrop" to create a workspace in Documents.',
+            'Or run "playdrop-cli init ." to bootstrap the current folder.',
+        ], { command: 'init' });
+        process.exitCode = 1;
+        return;
+    }
+    const target = resolveInitTarget(pathArg);
+    await (0, init_1.init)(target);
+});
+program
+    .command('upgrade')
+    .description('Update the Playdrop CLI to the latest version')
+    .option('--dry-run', 'Show the command without executing it')
+    .action(async (opts) => {
+    await (0, upgrade_1.upgrade)(!!opts.dryRun);
+});
+// ============================================================================
+// Versions Command Group
+// ============================================================================
+const versionsCommand = program
+    .command('versions')
+    .description('Manage app versions');
+versionsCommand
+    .command('list <app>')
+    .description('List all versions for an app')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .option('--format <format>', 'Output format (text|json, default: text)')
+    .action(async (app, opts) => {
+    await (0, versions_1.listVersions)(app, { format: opts.format, creator: opts.creator });
+});
+versionsCommand
+    .command('set-current <app> <version>')
+    .description('Set a version as the current (live) version')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (app, version, opts) => {
+    await (0, versions_1.setCurrentVersion)(app, version, { creator: opts.creator });
+});
+versionsCommand
+    .command('publish <app> <version>')
+    .description('Make a version publicly visible')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (app, version, opts) => {
+    await (0, versions_1.publishVersion)(app, version, { creator: opts.creator });
+});
+versionsCommand
+    .command('unpublish <app> <version>')
+    .description('Make a version private (hidden from public)')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (app, version, opts) => {
+    await (0, versions_1.unpublishVersion)(app, version, { creator: opts.creator });
+});
+versionsCommand
+    .command('delete <app> <version>')
+    .description('Delete a version permanently')
+    .option('--creator <creator>', 'Creator username override (supports "me")')
+    .action(async (app, version, opts) => {
+    await (0, versions_1.deleteVersion)(app, version, { creator: opts.creator });
+});
+versionsCommand.addHelpText('beforeAll', () => [
+    '',
+    'Manage versions for your Playdrop apps. Versions allow you to maintain multiple releases',
+    'of an app and control which version is live.',
+    '',
+    'Examples:',
+    '  playdrop-cli versions list myapp',
+    '  playdrop-cli versions list creator/game/myapp --format json',
+    '  playdrop-cli versions set-current myapp 1.2.0',
+    '  playdrop-cli versions publish myapp 1.2.0',
+    '  playdrop-cli versions unpublish myapp 1.1.0',
+    '  playdrop-cli versions delete myapp 1.0.0',
+    '',
+    'Workflow:',
+    '  1. Add "version" to catalogue.json and run `playdrop-cli upload` to create versions.',
+    '  2. Use `versions list` to see all versions for an app.',
+    '  3. Use `versions publish` to make a version publicly visible.',
+    '  4. Use `versions set-current` to make a public version live.',
+    '',
+].join('\n'));
+program.parseAsync(process.argv);