@playdrop/playdrop-cli 0.3.1-build.1 → 0.3.5-build.1

package/README.md

@@ -1,24 +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).
-- `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.1",
+  "version": "0.3.5",
   "build": 1,
   "platforms": {
     "ios": {
@@ -26,19 +26,19 @@
   },
   "clients": {
     "web": {
-      "minimumVersion": "0.3.1",
+      "minimumVersion": "0.3.5",
       "minimumBuild": 1
     },
     "admin": {
-      "minimumVersion": "0.3.1",
+      "minimumVersion": "0.3.5",
       "minimumBuild": 1
     },
     "apple": {
-      "minimumVersion": "0.3.1",
+      "minimumVersion": "0.3.5",
       "minimumBuild": 1
     },
     "cli": {
-      "minimumVersion": "0.3.1",
+      "minimumVersion": "0.3.5",
       "minimumBuild": 1
     }
   }

package/dist/apps/build.js

@@ -173,9 +173,21 @@ function normalizeRelativePath(root, target) {
     const rel = (0, node_path_1.relative)(root, target).split(node_path_1.sep).join('/');
     return rel.replace(/^\/+/, '');
 }
-function collectProjectFiles(projectDir, rules) {
+function isPathWithinRoot(rootDir, targetPath) {
+    const normalizedRoot = (0, node_path_1.resolve)(rootDir);
+    const normalizedTarget = (0, node_path_1.resolve)(targetPath);
+    if (normalizedTarget === normalizedRoot) {
+        return true;
+    }
+    const rootPrefix = normalizedRoot.endsWith(node_path_1.sep) ? normalizedRoot : `${normalizedRoot}${node_path_1.sep}`;
+    return normalizedTarget.startsWith(rootPrefix);
+}
+function collectProjectFiles(rootDir, rules, options) {
+    const includeRelativeFiles = options?.includeRelativeFiles ?? [];
+    const enforceReservedBundleNames = options?.enforceReservedBundleNames ?? false;
     const results = [];
-    const stack = [projectDir];
+    const fileByRelativePath = new Map();
+    const stack = [rootDir];
     const visited = new Set();
     while (stack.length > 0) {
         const current = stack.pop();
@@ -191,10 +203,13 @@ function collectProjectFiles(projectDir, rules) {
         }
         for (const entry of dirEntries) {
             const absolutePath = (0, node_path_1.join)(current, entry.name);
-            const relativePath = normalizeRelativePath(projectDir, absolutePath);
+            const relativePath = normalizeRelativePath(rootDir, absolutePath);
             if (!relativePath)
                 continue;
             const isDir = entry.isDirectory();
+            if (!isDir && enforceReservedBundleNames && isReservedBundlePath(relativePath)) {
+                throw new Error(`[apps][build] Reserved bundle filename "${relativePath}" is not allowed. Use dedicated source/ecs/server upload fields.`);
+            }
             const ignoreTarget = isDir ? `${relativePath}/` : relativePath;
             if (shouldIgnore(ignoreTarget, isDir, rules))
                 continue;
@@ -213,127 +228,87 @@ function collectProjectFiles(projectDir, rules) {
             }
             if (!stats.isFile())
                 continue;
-            results.push({
+            const record = {
                 absolutePath,
                 relativePath: relativePath.split('/').join('/'),
                 mtime: stats.mtime,
-            });
+            };
+            results.push(record);
+            fileByRelativePath.set(record.relativePath, record);
         }
     }
+    for (const includePath of includeRelativeFiles) {
+        const normalizedIncludePath = (0, node_path_1.normalize)(includePath).split(node_path_1.sep).join('/');
+        if (!normalizedIncludePath || normalizedIncludePath === '.') {
+            continue;
+        }
+        if (normalizedIncludePath.startsWith('..')) {
+            throw new Error(`[apps][build] Invalid include file path "${includePath}".`);
+        }
+        if (fileByRelativePath.has(normalizedIncludePath)) {
+            continue;
+        }
+        const absolutePath = (0, node_path_1.resolve)(rootDir, normalizedIncludePath);
+        if (!isPathWithinRoot(rootDir, absolutePath)) {
+            throw new Error(`[apps][build] Included file "${includePath}" escapes the project root.`);
+        }
+        if (!(0, node_fs_1.existsSync)(absolutePath)) {
+            continue;
+        }
+        const stats = (0, node_fs_1.statSync)(absolutePath);
+        if (!stats.isFile()) {
+            continue;
+        }
+        if (enforceReservedBundleNames && isReservedBundlePath(normalizedIncludePath)) {
+            throw new Error(`[apps][build] Reserved bundle filename "${normalizedIncludePath}" is not allowed. Use dedicated source/ecs/server upload fields.`);
+        }
+        const record = {
+            absolutePath,
+            relativePath: normalizedIncludePath,
+            mtime: stats.mtime,
+        };
+        results.push(record);
+        fileByRelativePath.set(record.relativePath, record);
+    }
     results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
     return results;
 }
-function collectHtmlSourceFiles(task) {
-    const files = [];
-    const htmlStats = (0, node_fs_1.statSync)(task.filePath);
-    files.push({
-        absolutePath: task.filePath,
-        relativePath: (0, node_path_1.basename)(task.filePath),
-        mtime: htmlStats.mtime,
-    });
-    const readmePath = (0, node_path_1.join)(task.projectDir, 'README.md');
-    if ((0, node_fs_1.existsSync)(readmePath)) {
-        const stats = (0, node_fs_1.statSync)(readmePath);
-        files.push({ absolutePath: readmePath, relativePath: 'README.md', mtime: stats.mtime });
-    }
-    const agentsPath = (0, node_path_1.join)(task.projectDir, 'AGENTS.md');
-    if ((0, node_fs_1.existsSync)(agentsPath)) {
-        const stats = (0, node_fs_1.statSync)(agentsPath);
-        files.push({ absolutePath: agentsPath, relativePath: 'AGENTS.md', mtime: stats.mtime });
-    }
-    if (task.catalogueAbsolutePath && (0, node_fs_1.existsSync)(task.catalogueAbsolutePath)) {
-        const stats = (0, node_fs_1.statSync)(task.catalogueAbsolutePath);
-        const relativePath = normalizeRelativePath(task.projectDir, task.catalogueAbsolutePath) || 'catalogue.json';
-        files.push({ absolutePath: task.catalogueAbsolutePath, relativePath, mtime: stats.mtime });
+// Files that are uploaded separately and should not be included in the bundle zip.
+const RESERVED_BUNDLE_FILES = new Set(['source.zip', 'ecs.json', 'server.js']);
+function isReservedBundlePath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/');
+    const basenameValue = normalized.split('/').pop()?.toLowerCase() || '';
+    return RESERVED_BUNDLE_FILES.has(basenameValue);
+}
+function resolveRuntimeRoot(task) {
+    return (0, node_path_1.resolve)((0, node_path_1.dirname)(task.filePath));
+}
+function resolveBundleEntryPoint(task, runtimeRoot) {
+    const entryPoint = normalizeRelativePath(runtimeRoot, task.filePath);
+    if (!entryPoint || entryPoint.startsWith('..')) {
+        throw new Error(`[apps][build] App entry file for ${task.name} must remain inside runtime root ${runtimeRoot}.`);
     }
-    files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-    return files;
+    return entryPoint;
 }
-// Files that are uploaded separately and should not be included in the bundle zip
-const RESERVED_BUNDLE_FILES = new Set(['ecs.json', 'server.js']);
 /**
  * Collect files for the bundle zip.
- * - For TypeScript projects: all files in the dist folder (excluding reserved files)
- * - For HTML projects: just the single HTML file (renamed to entry point)
+ * Collect files for the bundle zip from the runtime root (dirname(entry file)).
  */
 function collectBundleFiles(task) {
-    if (task.isTypescriptProject) {
-        const projectDir = (0, node_path_1.resolve)(task.projectDir);
-        const outputDir = (0, node_path_1.resolve)((0, node_path_1.dirname)(task.filePath));
-        if (outputDir === projectDir) {
-            // If the app output is at project root, avoid zipping the whole project tree.
-            // Bundle only the declared app entry file.
-            const htmlStats = (0, node_fs_1.statSync)(task.filePath);
-            const entryPoint = task.relativeFile || (0, node_path_1.basename)(task.filePath);
-            return [{
-                    absolutePath: task.filePath,
-                    relativePath: entryPoint,
-                    mtime: htmlStats.mtime,
-                }];
-        }
-        // For TypeScript projects with a dedicated output folder, zip that folder.
-        const distDir = outputDir;
-        const results = [];
-        const stack = [distDir];
-        const visited = new Set();
-        while (stack.length > 0) {
-            const current = stack.pop();
-            if (visited.has(current))
-                continue;
-            visited.add(current);
-            let dirEntries = [];
-            try {
-                dirEntries = (0, node_fs_1.readdirSync)(current, { withFileTypes: true });
-            }
-            catch {
-                continue;
-            }
-            for (const entry of dirEntries) {
-                const absolutePath = (0, node_path_1.join)(current, entry.name);
-                const relativePath = normalizeRelativePath(distDir, absolutePath);
-                if (!relativePath)
-                    continue;
-                if (entry.isDirectory()) {
-                    stack.push(absolutePath);
-                    continue;
-                }
-                if (!entry.isFile())
-                    continue;
-                // Skip reserved files - they are uploaded separately
-                if (RESERVED_BUNDLE_FILES.has(entry.name)) {
-                    continue;
-                }
-                let stats;
-                try {
-                    stats = (0, node_fs_1.statSync)(absolutePath);
-                }
-                catch {
-                    continue;
-                }
-                results.push({
-                    absolutePath,
-                    relativePath,
-                    mtime: stats.mtime,
-                });
-            }
-        }
-        results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-        return results;
-    }
-    // For HTML projects, zip just the single HTML file
-    const htmlStats = (0, node_fs_1.statSync)(task.filePath);
-    const entryPoint = task.relativeFile || (0, node_path_1.basename)(task.filePath);
-    return [{
-            absolutePath: task.filePath,
-            relativePath: entryPoint,
-            mtime: htmlStats.mtime,
-        }];
+    const runtimeRoot = resolveRuntimeRoot(task);
+    const entryPoint = resolveBundleEntryPoint(task, runtimeRoot);
+    const rules = buildIgnoreRules(task.projectDir);
+    const entries = collectProjectFiles(runtimeRoot, rules, {
+        includeRelativeFiles: [entryPoint],
+        enforceReservedBundleNames: true,
+    });
+    return { entries, entryPoint };
 }
 function createBundleArchive(task) {
-    const entries = collectBundleFiles(task);
+    const { entries, entryPoint } = collectBundleFiles(task);
     const buffer = createZipArchive(entries);
     const hash = (0, node_crypto_1.createHash)('sha256').update(buffer).digest('hex');
-    return { buffer, hash };
+    return { buffer, hash, entryPoint };
 }
 const CRC32_TABLE = (() => {
     const table = new Uint32Array(256);
@@ -468,20 +443,25 @@ function createZipArchive(entries) {
     return Buffer.concat(chunks);
 }
 function createSourceArchive(task) {
+    const rules = buildIgnoreRules(task.projectDir);
+    const includeFiles = ['README.md', 'AGENTS.md'];
+    if (task.catalogueAbsolutePath && (0, node_fs_1.existsSync)(task.catalogueAbsolutePath)) {
+        const relativeCataloguePath = normalizeRelativePath(task.projectDir, task.catalogueAbsolutePath) || 'catalogue.json';
+        includeFiles.push(relativeCataloguePath);
+    }
     if (task.isTypescriptProject) {
         const cached = typescriptSourceCache.get(task.projectDir);
         if (cached) {
             return cached;
         }
-        const rules = buildIgnoreRules(task.projectDir);
-        const entries = collectProjectFiles(task.projectDir, rules);
+        const entries = collectProjectFiles(task.projectDir, rules, { includeRelativeFiles: includeFiles });
         const buffer = createZipArchive(entries);
         const hash = (0, node_crypto_1.createHash)('sha256').update(buffer).digest('hex');
         const record = { buffer, hash };
         typescriptSourceCache.set(task.projectDir, record);
         return record;
     }
-    const entries = collectHtmlSourceFiles(task);
+    const entries = collectProjectFiles(task.projectDir, rules, { includeRelativeFiles: includeFiles });
     const buffer = createZipArchive(entries);
     const hash = (0, node_crypto_1.createHash)('sha256').update(buffer).digest('hex');
     return { buffer, hash };
@@ -524,11 +504,7 @@ async function buildApp(task) {
     if (task.surfaceTargets && task.surfaceTargets.length > 0) {
         metadata.surfaceTargets = task.surfaceTargets;
     }
-    // For TypeScript projects, files are stored relative to dist directory,
-    // so entryPoint should be the filename, not the full catalogue path
-    metadata.entryPoint = task.isTypescriptProject
-        ? (0, node_path_1.basename)(task.relativeFile)
-        : task.relativeFile;
+    metadata.entryPoint = bundleArchive.entryPoint;
     // Build ecs file if path is defined
     let ecsFile;
     let ecsHash;

package/dist/apps/upload.js

@@ -5,11 +5,33 @@ const types_1 = require("@playdrop/types");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const http_1 = require("../http");
+function isPngSignature(content) {
+    if (content.length < 8) {
+        return false;
+    }
+    return (content[0] === 0x89
+        && content[1] === 0x50
+        && content[2] === 0x4e
+        && content[3] === 0x47
+        && content[4] === 0x0d
+        && content[5] === 0x0a
+        && content[6] === 0x1a
+        && content[7] === 0x0a);
+}
+function isMp4Signature(content) {
+    if (content.length < 12) {
+        return false;
+    }
+    return content.toString('ascii', 4, 8) === 'ftyp';
+}
 /**
  * Create a File object from a file path with specified MIME type.
  */
-function createFileFromPath(filePath, mimeType) {
+function createFileFromPath(filePath, mimeType, validator) {
     const content = (0, node_fs_1.readFileSync)(filePath);
+    if (validator && !validator(content)) {
+        throw new Error(`Invalid listing file signature for ${filePath}. Expected ${mimeType}.`);
+    }
     const name = (0, node_path_1.basename)(filePath);
     return new File([content], name, { type: mimeType });
 }
@@ -25,6 +47,10 @@ 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,
@@ -37,8 +63,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') {
@@ -61,29 +85,29 @@ async function uploadAppVersion(client, task, artifacts, options) {
     // Add listing assets if provided
     if (task.listing) {
         if (task.listing.iconPath) {
-            versionOptions.icon = createFileFromPath(task.listing.iconPath, 'image/png');
+            versionOptions.icon = createFileFromPath(task.listing.iconPath, 'image/png', isPngSignature);
         }
         if (task.listing.heroPortraitPath) {
-            versionOptions.heroPortrait = createFileFromPath(task.listing.heroPortraitPath, 'image/png');
+            versionOptions.heroPortrait = createFileFromPath(task.listing.heroPortraitPath, 'image/png', isPngSignature);
         }
         if (task.listing.heroLandscapePath) {
-            versionOptions.heroLandscape = createFileFromPath(task.listing.heroLandscapePath, 'image/png');
+            versionOptions.heroLandscape = createFileFromPath(task.listing.heroLandscapePath, 'image/png', isPngSignature);
         }
         if (task.listing.screenshotPortraitPaths.length > 0) {
-            versionOptions.screenshotsPortrait = task.listing.screenshotPortraitPaths.map((p) => createFileFromPath(p, 'image/png'));
+            versionOptions.screenshotsPortrait = task.listing.screenshotPortraitPaths.map((p) => createFileFromPath(p, 'image/png', isPngSignature));
         }
         if (task.listing.screenshotLandscapePaths.length > 0) {
-            versionOptions.screenshotsLandscape = task.listing.screenshotLandscapePaths.map((p) => createFileFromPath(p, 'image/png'));
+            versionOptions.screenshotsLandscape = task.listing.screenshotLandscapePaths.map((p) => createFileFromPath(p, 'image/png', isPngSignature));
         }
         if (task.listing.videoPortraitPaths.length > 0) {
-            versionOptions.videosPortrait = task.listing.videoPortraitPaths.map((p) => createFileFromPath(p, 'video/mp4'));
+            versionOptions.videosPortrait = task.listing.videoPortraitPaths.map((p) => createFileFromPath(p, 'video/mp4', isMp4Signature));
         }
         if (task.listing.videoLandscapePaths.length > 0) {
-            versionOptions.videosLandscape = task.listing.videoLandscapePaths.map((p) => createFileFromPath(p, 'video/mp4'));
+            versionOptions.videosLandscape = task.listing.videoLandscapePaths.map((p) => createFileFromPath(p, 'video/mp4', isMp4Signature));
         }
     }
     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/apps/validate.js

@@ -7,6 +7,15 @@ const node_path_1 = require("node:path");
 const build_1 = require("./build");
 const projectValidateCache = new Map();
 const projectFormatCache = new Map();
+const LEGACY_SCAN_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.html']);
+const LEGACY_SCAN_IGNORED_DIRS = new Set(['node_modules', '.git', 'dist-test', 'coverage']);
+const LEGACY_SDK_SYMBOL_PATTERNS = [
+    { symbol: 'selectedAvatarKey', pattern: /\bselectedAvatarKey\b/g },
+    { symbol: 'sdk.entities', pattern: /\bsdk\s*\.\s*entities\b/g },
+    { symbol: 'sdk.assets.avatar', pattern: /\bsdk\s*\.\s*assets\s*\.\s*avatar\b/g },
+    { symbol: 'sdk.assets.block', pattern: /\bsdk\s*\.\s*assets\s*\.\s*block\b/g },
+    { symbol: 'loadEntity(', pattern: /\.\s*loadEntity\s*\(/g },
+];
 function ensureWithinProject(task) {
     const relativePath = (0, node_path_1.relative)(task.projectDir, task.filePath);
     const segments = relativePath.split(/[/\\]+/);
@@ -24,6 +33,54 @@ async function ensureValidateScript(task) {
     }
     await projectValidateCache.get(task.projectDir);
 }
+function scanForLegacySdkSymbols(task) {
+    const findings = [];
+    const scanFile = (filePath) => {
+        const extension = (0, node_path_1.extname)(filePath).toLowerCase();
+        if (!LEGACY_SCAN_EXTENSIONS.has(extension)) {
+            return;
+        }
+        const source = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+        for (const { symbol, pattern } of LEGACY_SDK_SYMBOL_PATTERNS) {
+            pattern.lastIndex = 0;
+            const hit = pattern.exec(source);
+            if (!hit) {
+                continue;
+            }
+            const index = typeof hit.index === 'number' ? hit.index : 0;
+            const line = source.slice(0, index).split('\n').length;
+            findings.push({
+                file: (0, node_path_1.relative)(task.projectDir, filePath),
+                line,
+                symbol,
+            });
+        }
+    };
+    const walk = (directory) => {
+        const entries = (0, node_fs_1.readdirSync)(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            if (LEGACY_SCAN_IGNORED_DIRS.has(entry.name)) {
+                continue;
+            }
+            const nextPath = (0, node_path_1.join)(directory, entry.name);
+            if (entry.isDirectory()) {
+                walk(nextPath);
+            }
+            else if (entry.isFile()) {
+                scanFile(nextPath);
+            }
+        }
+    };
+    walk(task.projectDir);
+    if (findings.length > 0) {
+        const details = findings
+            .slice(0, 10)
+            .map((entry) => `${entry.file}:${entry.line} (${entry.symbol})`)
+            .join(', ');
+        const suffix = findings.length > 10 ? ` (+${findings.length - 10} more)` : '';
+        throw new Error(`[apps][validate] legacy SDK symbols detected for ${task.name}: ${details}${suffix}. Remove entity-era APIs before publishing.`);
+    }
+}
 async function runFormatScript(task) {
     if (!task.packageJsonPath || !task.hasFormatScript) {
         return false;
@@ -53,6 +110,9 @@ async function validateAppTask(task) {
     if (!task.relativeFile) {
         throw new Error(`[apps][validate] ${task.name} is missing a "file" field in ${task.cataloguePath}.`);
     }
+    if (task.isTypescriptProject && !task.hasValidateScript) {
+        throw new Error(`[apps][validate] ${task.name} is missing a required "validate" script in package.json. Define a validate command (for example "validate": "npm run build").`);
+    }
     ensureWithinProject(task);
     if (!task.isTypescriptProject) {
         if (!(0, node_fs_1.existsSync)(task.filePath)) {
@@ -72,4 +132,5 @@ async function validateAppTask(task) {
             throw new Error(`[apps][validate] npm run validate failed for ${task.name}: ${message}`);
         }
     }
+    scanForLegacySdkSymbols(task);
 }

package/dist/assets/model-artifacts.d.ts

@@ -0,0 +1,8 @@
+import type { AssetTask, EmbeddedAssetTask } from '../catalogue';
+type ModelAssetTask = AssetTask | EmbeddedAssetTask;
+export declare function isGeneratedModel3DAssetTask(task: ModelAssetTask, format?: string): boolean;
+export declare function assertGeneratedModel3DAssetRoles(task: ModelAssetTask, format?: string): void;
+export declare function prepareModel3DAssetArtifacts(task: ModelAssetTask, options?: {
+    dryRun?: boolean;
+}): Promise<boolean>;
+export {};