@portel/photon 1.11.0 → 1.13.0

package/dist/cli/commands/build.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerBuildCommand(program: Command): void;
+//# sourceMappingURL=build.d.ts.map

package/dist/cli/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuGpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA8TpD"}

package/dist/cli/commands/build.js

@@ -0,0 +1,339 @@
+import path from 'path';
+import fs from 'fs';
+import { spawn } from 'child_process';
+import ora from 'ora';
+import chalk from 'chalk';
+import { printError } from '../../cli-formatter.js';
+import { fileURLToPath } from 'url';
+import { SchemaExtractor } from '@portel/photon-core';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Recursively resolve all @photon dependencies starting from a root source file.
+ * Returns a flat list of unique dependencies (by file path).
+ */
+function resolvePhotonDeps(sourceCode, sourceFilePath, baseDir, visited = new Set()) {
+    const extractor = new SchemaExtractor();
+    const deps = extractor.extractPhotonDependencies(sourceCode);
+    const result = [];
+    for (const dep of deps) {
+        // Resolve the file path based on source type
+        let resolvedPath = null;
+        if (dep.sourceType === 'local') {
+            // Relative or absolute path
+            if (dep.source.startsWith('./') || dep.source.startsWith('../')) {
+                resolvedPath = path.resolve(path.dirname(sourceFilePath), dep.source);
+            }
+            else {
+                resolvedPath = path.resolve(dep.source);
+            }
+            // Ensure .photon.ts extension
+            if (!resolvedPath.endsWith('.photon.ts') && !resolvedPath.endsWith('.ts')) {
+                resolvedPath += '.photon.ts';
+            }
+        }
+        else if (dep.sourceType === 'marketplace') {
+            // Search common locations for marketplace photons
+            const slug = dep.source
+                .replace(/\.photon\.ts$/, '')
+                .replace(/\.photon$/, '')
+                .replace(/\.ts$/, '');
+            const fileName = `${slug}.photon.ts`;
+            const candidates = [
+                path.resolve(path.dirname(sourceFilePath), fileName),
+                path.resolve(path.dirname(sourceFilePath), 'photons', fileName),
+                path.join(baseDir, fileName),
+                path.join(baseDir, 'photons', fileName),
+                path.join(baseDir, 'marketplace', fileName),
+            ];
+            for (const candidate of candidates) {
+                if (fs.existsSync(candidate)) {
+                    resolvedPath = candidate;
+                    break;
+                }
+            }
+        }
+        if (!resolvedPath || !fs.existsSync(resolvedPath)) {
+            // Can't resolve — will be warned about separately
+            continue;
+        }
+        resolvedPath = fs.realpathSync(resolvedPath);
+        if (visited.has(resolvedPath)) {
+            continue; // Already processed (circular dep protection)
+        }
+        visited.add(resolvedPath);
+        const depSource = fs.readFileSync(resolvedPath, 'utf-8');
+        result.push({
+            name: dep.name,
+            source: dep.source,
+            filePath: resolvedPath,
+            sourceCode: depSource,
+        });
+        // Recurse into transitive dependencies
+        const transitive = resolvePhotonDeps(depSource, resolvedPath, baseDir, visited);
+        result.push(...transitive);
+    }
+    return result;
+}
+export function registerBuildCommand(program) {
+    program
+        .command('build')
+        .description('Compile a photon into a standalone executable binary')
+        .argument('<file>', 'Path to the .photon.ts file')
+        .option('-o, --outfile <name>', 'Name of the output binary')
+        .option('-t, --target <target>', 'Bun compilation target (e.g. bun-linux-x64, bun-darwin-arm64, bun-windows-x64)')
+        .action(async (file, options) => {
+        const spinner = ora(`Preparing standalone build for ${file}...`).start();
+        const workingDir = process.cwd();
+        const photonPath = path.resolve(workingDir, file);
+        if (!fs.existsSync(photonPath)) {
+            spinner.fail(`File not found: ${photonPath}`);
+            process.exit(1);
+        }
+        // Check that bun is available
+        try {
+            const { execSync } = await import('child_process');
+            execSync('bun --version', { stdio: 'ignore' });
+        }
+        catch {
+            spinner.fail('Bun is required for compilation. Install it: https://bun.sh');
+            process.exit(1);
+        }
+        // Read the source code to embed in the binary
+        const sourceCode = fs.readFileSync(photonPath, 'utf-8');
+        // Resolve @photon dependencies recursively
+        const baseDir = path.join(process.env.HOME || '~', '.photon');
+        const photonDeps = resolvePhotonDeps(sourceCode, photonPath, baseDir);
+        if (photonDeps.length > 0) {
+            spinner.info(`Bundling ${photonDeps.length} @photon dependenc${photonDeps.length === 1 ? 'y' : 'ies'}:`);
+            for (const dep of photonDeps) {
+                console.log(chalk.cyan(`  📦 ${dep.name} → ${path.basename(dep.filePath)}`));
+            }
+            console.log();
+            spinner.start('Continuing build...');
+        }
+        // Detect unbundleable dependencies and warn
+        const warnings = [];
+        // Check all sources (main + deps) for @mcp and @cli tags
+        const allSources = [sourceCode, ...photonDeps.map((d) => d.sourceCode)];
+        for (const src of allSources) {
+            for (const match of src.matchAll(/@mcp\s+(\S+)/g)) {
+                warnings.push(`@mcp dependency "${match[1]}" — external MCP server, must be installed separately`);
+            }
+            for (const match of src.matchAll(/@cli\s+(\S+)/g)) {
+                warnings.push(`@cli dependency "${match[1]}" — external CLI tool, must be available on target system`);
+            }
+        }
+        // Check for unresolved @photon deps (ones we couldn't find on disk)
+        const extractor = new SchemaExtractor();
+        const declaredDeps = extractor.extractPhotonDependencies(sourceCode);
+        for (const dep of declaredDeps) {
+            const resolved = photonDeps.find((d) => d.name === dep.name);
+            if (!resolved) {
+                warnings.push(`@photon dependency "${dep.name}" (from ${dep.source}) — could not be resolved, must be available at runtime`);
+            }
+        }
+        if (warnings.length > 0) {
+            spinner.warn('External dependencies detected (not bundled):');
+            for (const w of warnings) {
+                console.log(chalk.yellow(`  ⚠ ${w}`));
+            }
+            console.log();
+            spinner.start('Continuing build...');
+        }
+        // Generate a unique temporary entrypoint file
+        const tempEntrypointName = `.photon-build-${Date.now()}.ts`;
+        const tempEntrypointPath = path.join(workingDir, tempEntrypointName);
+        // Determine outfile name
+        let outfile = options.outfile;
+        if (!outfile) {
+            const basename = path.basename(file, '.photon.ts');
+            outfile = basename.endsWith('.photon.js') ? path.basename(file, '.photon.js') : basename;
+        }
+        try {
+            // Relative import path for the photon module
+            let relativePhotonPath = path.relative(workingDir, photonPath);
+            if (!relativePhotonPath.startsWith('.')) {
+                relativePhotonPath = `./${relativePhotonPath}`;
+            }
+            // Escape source for embedding as a template literal
+            const escapeForTemplateLiteral = (src) => src.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+            const escapedSource = escapeForTemplateLiteral(sourceCode);
+            // Resolve the photon runtime package path for the entrypoint import.
+            const photonPkgDir = path.resolve(__dirname, '..', '..'); // dist/ -> package root
+            let photonImportPath = path.relative(workingDir, path.join(photonPkgDir, 'index.js'));
+            if (!photonImportPath.startsWith('.')) {
+                photonImportPath = `./${photonImportPath}`;
+            }
+            // Generate import statements for each @photon dependency
+            const depImports = [];
+            const depMapEntries = [];
+            for (let i = 0; i < photonDeps.length; i++) {
+                const dep = photonDeps[i];
+                const varName = `__dep${i}`;
+                let depImportPath = path.relative(workingDir, dep.filePath);
+                if (!depImportPath.startsWith('.')) {
+                    depImportPath = `./${depImportPath}`;
+                }
+                depImports.push(`import * as ${varName} from '${depImportPath}';`);
+                const escapedDepSource = escapeForTemplateLiteral(dep.sourceCode);
+                depMapEntries.push(`  deps.set('${dep.name}', { module: ${varName}, source: \`${escapedDepSource}\`, filePath: ${JSON.stringify(dep.filePath)} });`);
+                // Also register by source name for fallback matching
+                if (dep.source !== dep.name) {
+                    depMapEntries.push(`  deps.set('${dep.source}', { module: ${varName}, source: \`${escapedDepSource}\`, filePath: ${JSON.stringify(dep.filePath)} });`);
+                }
+            }
+            const depImportsBlock = depImports.length > 0 ? depImports.join('\n') + '\n' : '';
+            const depMapBlock = depMapEntries.length > 0
+                ? `\nfunction buildDependencyMap() {\n  const deps = new Map();\n${depMapEntries.join('\n')}\n  return deps;\n}\n`
+                : '';
+            const depMapArg = depMapEntries.length > 0 ? `\n    preloadedDependencies: buildDependencyMap(),` : '';
+            // Build a symlink routing map for the entrypoint:
+            // When invoked via a symlink named after a bundled dep, serve that dep instead.
+            const symlinkEntries = [];
+            for (let i = 0; i < photonDeps.length; i++) {
+                const dep = photonDeps[i];
+                const varName = `__dep${i}`;
+                const escapedDepSource = escapeForTemplateLiteral(dep.sourceCode);
+                // Extract the photon name from the file (e.g., "whatsapp" from "whatsapp.photon.ts")
+                const depPhotonName = path.basename(dep.filePath, '.photon.ts').replace('.photon', '');
+                symlinkEntries.push(`  '${depPhotonName}': { module: ${varName}, source: \`${escapedDepSource}\`, filePath: ${JSON.stringify(dep.filePath)} },`);
+                // Also map by the dependency variable name if different
+                if (dep.name !== depPhotonName) {
+                    symlinkEntries.push(`  '${dep.name}': { module: ${varName}, source: \`${escapedDepSource}\`, filePath: ${JSON.stringify(dep.filePath)} },`);
+                }
+            }
+            const symlinkMapBlock = symlinkEntries.length > 0
+                ? `\nconst BUNDLED_PHOTONS: Record<string, { module: any; source: string; filePath: string }> = {\n${symlinkEntries.join('\n')}\n};\n`
+                : '\nconst BUNDLED_PHOTONS: Record<string, { module: any; source: string; filePath: string }> = {};\n';
+            // Symlink routing logic: detect which photon to serve based on executable name
+            const symlinkRoutingCode = `
+  // Detect if invoked via a symlink to serve a bundled dependency.
+  // Bun compiled binaries don't preserve argv[0] for symlinks, but
+  // $_ (set by shells) contains the actual invocation path including symlink name.
+  const __path = await import('path');
+  const invokedAs = __path.default.basename(process.env._ || process.execPath);
+  const bundled = BUNDLED_PHOTONS[invokedAs];
+  const activeModule = bundled ? bundled.module : photonModule;
+  const activeSource = bundled ? bundled.source : EMBEDDED_SOURCE;
+  const activeFilePath = bundled ? bundled.filePath : ${JSON.stringify(photonPath)};
+`;
+            const entrypointCode = `import { PhotonServer, EmbeddedRuntime } from '${photonImportPath}';
+import * as photonModule from '${relativePhotonPath}';
+${depImportsBlock}
+const EMBEDDED_SOURCE = \`${escapedSource}\`;
+${depMapBlock}${symlinkMapBlock}
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'mcp';
+
+  let port: number | undefined;
+  if (command === 'sse') {
+    port = args[1] ? parseInt(args[1], 10) : undefined;
+  }
+${symlinkRoutingCode}
+  // Start embedded runtime (in-process broker + scheduler)
+  const runtime = new EmbeddedRuntime();
+  runtime.start();
+
+  const server = new PhotonServer({
+    filePath: activeFilePath,
+    transport: command === 'sse' ? 'sse' : 'stdio',
+    port,
+    preloadedModule: activeModule,
+    embeddedSource: activeSource,${depMapArg}
+  });
+
+  await server.start();
+
+  // Register @scheduled/@cron jobs from the loaded photon
+  if (server.getLoadedPhoton()) {
+    runtime.registerScheduledJobs(server.getLoadedPhoton()!, server.getLoader());
+  }
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err.message || err);
+  process.exit(1);
+});
+`;
+            fs.writeFileSync(tempEntrypointPath, entrypointCode, 'utf-8');
+            spinner.text = 'Compiling executable with Bun...';
+            // Prepare bun build arguments
+            const buildArgs = ['build', tempEntrypointPath, '--compile', '--outfile', outfile];
+            if (options.target) {
+                buildArgs.push('--target', options.target);
+            }
+            const buildProcess = spawn('bun', buildArgs, {
+                cwd: workingDir,
+                stdio: 'pipe',
+            });
+            let stdoutData = '';
+            let stderrData = '';
+            buildProcess.stdout.on('data', (data) => {
+                stdoutData += data.toString();
+            });
+            buildProcess.stderr.on('data', (data) => {
+                stderrData += data.toString();
+            });
+            await new Promise((resolve, reject) => {
+                buildProcess.on('close', (code) => {
+                    if (code === 0) {
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`Bun compilation failed with exit code ${code}\n\n${stderrData || stdoutData}`));
+                    }
+                });
+                buildProcess.on('error', reject);
+            });
+            // Get file size for display
+            const stat = fs.statSync(outfile);
+            const sizeMB = (stat.size / 1024 / 1024).toFixed(1);
+            spinner.succeed(`Compiled: ${chalk.green(chalk.bold(outfile))} (${sizeMB} MB)`);
+            // Create symlinks for bundled @photon dependencies
+            if (photonDeps.length > 0) {
+                const outDir = path.dirname(path.resolve(outfile));
+                const outBase = path.resolve(outfile);
+                const createdLinks = [];
+                const seenNames = new Set();
+                for (const dep of photonDeps) {
+                    const depName = path.basename(dep.filePath, '.photon.ts').replace('.photon', '');
+                    if (seenNames.has(depName) || depName === path.basename(outfile))
+                        continue;
+                    seenNames.add(depName);
+                    const linkPath = path.join(outDir, depName);
+                    try {
+                        if (fs.existsSync(linkPath))
+                            fs.unlinkSync(linkPath);
+                        fs.symlinkSync(outBase, linkPath);
+                        createdLinks.push(depName);
+                    }
+                    catch {
+                        // Symlink creation may fail on some filesystems — non-fatal
+                    }
+                }
+                if (createdLinks.length > 0) {
+                    console.log(`\n${chalk.dim('Symlinks (each serves the bundled photon as its own MCP server):')}`);
+                    for (const name of createdLinks) {
+                        console.log(`  ${chalk.cyan(name)} → ${outfile}`);
+                    }
+                }
+            }
+            console.log(`\nUsage:`);
+            console.log(`  ./${outfile}         MCP server (stdio)`);
+            console.log(`  ./${outfile} sse     MCP server (HTTP/SSE)`);
+        }
+        catch (err) {
+            spinner.fail('Build failed');
+            printError(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        finally {
+            // Clean up the temporary entrypoint file
+            if (fs.existsSync(tempEntrypointPath)) {
+                fs.unlinkSync(tempEntrypointPath);
+            }
+        }
+    });
+}
+//# sourceMappingURL=build.js.map

package/dist/cli/commands/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/package-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-app.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/package-app.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8LpC,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwChE"}
+{"version":3,"file":"package-app.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/package-app.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuOpC,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiGhE"}

package/dist/cli/commands/package-app.js

@@ -14,44 +14,56 @@ function toClassName(name) {
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
         .join('');
 }
-function generateBashLauncherScript(name, photonDir, startPort, openCmd) {
+function generateBashLauncherScript(name, version, startPort, openCmd) {
     const endPort = startPort + 9;
     return `#!/usr/bin/env bash
-# Launcher for ${name} — auto-starts beam and opens PWA
+# Launcher for ${name} — auto-starts beam and opens as PWA
 set -e
 
-PHOTON_DIR="${photonDir}"
+PHOTON="${name}"
+VERSION="${version}"
 START_PORT=${startPort}
 END_PORT=${endPort}
 OPEN_CMD="${openCmd}"
 
-# Scan ports for an existing beam serving this directory
+# Detect package runner: bunx > pnpx > npx
+if command -v bunx &>/dev/null; then
+  RUNNER="bunx @portel/photon@$VERSION"
+elif command -v pnpx &>/dev/null; then
+  RUNNER="pnpx @portel/photon@$VERSION"
+elif command -v npx &>/dev/null; then
+  RUNNER="npx -y @portel/photon@$VERSION"
+else
+  echo "Error: no package runner found (npx, pnpx, or bunx required)"
+  exit 1
+fi
+
+# Scan ports for an existing beam already serving this photon
 for port in $(seq $START_PORT $END_PORT); do
   RESP=$(curl -s --max-time 2 "http://localhost:\${port}/api/diagnostics" 2>/dev/null || true)
   if [ -n "$RESP" ]; then
-    DIR=$(echo "$RESP" | grep -o '"workingDir":"[^"]*"' | cut -d'"' -f4)
-    if [ "$DIR" = "$PHOTON_DIR" ]; then
-      $OPEN_CMD "http://localhost:\${port}"
+    # Check if this beam has our photon loaded
+    echo "$RESP" | grep -q "\\"name\\":\\"$PHOTON\\"" 2>/dev/null && {
+      # Beam already running with this photon — skip browser open (client likely connected)
       exit 0
-    fi
+    }
   fi
 done
 
-# No existing beam found — start one
-npx @portel/photon beam --port=$START_PORT &
+# No existing beam found — start one (--no-open: we handle browser launch ourselves)
+$RUNNER $PHOTON --no-open --port=$START_PORT &
 BEAM_PID=$!
 
-# Poll until beam is ready (up to 30s)
+# Poll until beam is ready (up to 30s), then open browser
 WAITED=0
 while [ $WAITED -lt 30 ]; do
   for port in $(seq $START_PORT $END_PORT); do
     RESP=$(curl -s --max-time 1 "http://localhost:\${port}/api/diagnostics" 2>/dev/null || true)
     if [ -n "$RESP" ]; then
-      DIR=$(echo "$RESP" | grep -o '"workingDir":"[^"]*"' | cut -d'"' -f4)
-      if [ "$DIR" = "$PHOTON_DIR" ]; then
-        $OPEN_CMD "http://localhost:\${port}"
+      echo "$RESP" | grep -q "\\"name\\":\\"$PHOTON\\"" 2>/dev/null && {
+        $OPEN_CMD "http://localhost:\${port}/#$PHOTON?focus=1"
         exit 0
-      fi
+      }
     fi
   done
   sleep 1
@@ -84,31 +96,40 @@ function generateInfoPlist(name, className) {
 </dict>
 </plist>`;
 }
-function generateWindowsBat(name, photonDir, startPort) {
+function generateWindowsBat(name, version, startPort) {
     const endPort = startPort + 9;
     return `@echo off
-REM Launcher for ${name} — auto-starts beam and opens PWA
+REM Launcher for ${name} — auto-starts beam and opens as PWA
 setlocal enabledelayedexpansion
 
-set "PHOTON_DIR=${photonDir}"
+set "PHOTON=${name}"
+set "VERSION=${version}"
 set START_PORT=${startPort}
 set END_PORT=${endPort}
 
-REM Scan ports for an existing beam serving this directory
+REM Detect package runner: bunx > pnpx > npx
+where bunx >nul 2>&1 && set "RUNNER=bunx @portel/photon@%VERSION%" && goto :found_runner
+where pnpx >nul 2>&1 && set "RUNNER=pnpx @portel/photon@%VERSION%" && goto :found_runner
+where npx >nul 2>&1 && set "RUNNER=npx -y @portel/photon@%VERSION%" && goto :found_runner
+echo Error: no package runner found (npx, pnpx, or bunx required)
+exit /b 1
+:found_runner
+
+REM Scan ports for an existing beam serving this photon
 for /L %%p in (%START_PORT%,1,%END_PORT%) do (
   for /f "delims=" %%r in ('curl -s --max-time 2 "http://localhost:%%p/api/diagnostics" 2^>nul') do (
-    echo %%r | findstr /c:"%PHOTON_DIR%" >nul 2>&1
+    echo %%r | findstr /c:"%PHOTON%" >nul 2>&1
     if !errorlevel! equ 0 (
-      start "" "http://localhost:%%p"
+      REM Beam already running with this photon — skip browser open
       exit /b 0
     )
   )
 )
 
 REM No existing beam found — start one
-start /b npx @portel/photon beam --port=%START_PORT%
+start /b %RUNNER% %PHOTON% --no-open --port=%START_PORT%
 
-REM Poll until beam is ready (up to 30s)
+REM Poll until beam is ready (up to 30s), then open browser
 set WAITED=0
 :poll
 if %WAITED% geq 30 (
@@ -117,9 +138,9 @@ if %WAITED% geq 30 (
 )
 for /L %%p in (%START_PORT%,1,%END_PORT%) do (
   for /f "delims=" %%r in ('curl -s --max-time 1 "http://localhost:%%p/api/diagnostics" 2^>nul') do (
-    echo %%r | findstr /c:"%PHOTON_DIR%" >nul 2>&1
+    echo %%r | findstr /c:"%PHOTON%" >nul 2>&1
     if !errorlevel! equ 0 (
-      start "" "http://localhost:%%p"
+      start "" "http://localhost:%%p/#%PHOTON%?focus=1"
       exit /b 0
     )
   )
@@ -129,20 +150,20 @@ set /a WAITED+=1
 goto poll
 `;
 }
-async function generateMacOSApp(name, className, photonDir, startPort, outputDir) {
+async function generateMacOSApp(name, className, version, startPort, outputDir) {
     const appDir = path.join(outputDir, `${className}.app`);
     const contentsDir = path.join(appDir, 'Contents');
     const macosDir = path.join(contentsDir, 'MacOS');
     await fs.mkdir(macosDir, { recursive: true });
     await fs.writeFile(path.join(contentsDir, 'Info.plist'), generateInfoPlist(name, className));
-    const script = generateBashLauncherScript(name, photonDir, startPort, 'open');
+    const script = generateBashLauncherScript(name, version, startPort, 'open');
     await fs.writeFile(path.join(macosDir, 'launch'), script, { mode: 0o755 });
     return appDir;
 }
-async function generateLinuxLauncher(name, photonDir, startPort, outputDir) {
+async function generateLinuxLauncher(name, version, startPort, outputDir) {
     const shPath = path.join(outputDir, `${name}.sh`);
     const desktopPath = path.join(outputDir, `${name}.desktop`);
-    const script = generateBashLauncherScript(name, photonDir, startPort, 'xdg-open');
+    const script = generateBashLauncherScript(name, version, startPort, 'xdg-open');
     await fs.writeFile(shPath, script, { mode: 0o755 });
     const desktop = `[Desktop Entry]
 Type=Application
@@ -154,11 +175,30 @@ Categories=Utility;
     await fs.writeFile(desktopPath, desktop);
     return [shPath, desktopPath];
 }
-async function generateWindowsLauncher(name, photonDir, startPort, outputDir) {
+async function generateWindowsLauncher(name, version, startPort, outputDir) {
     const batPath = path.join(outputDir, `${name}.bat`);
-    await fs.writeFile(batPath, generateWindowsBat(name, photonDir, startPort));
+    await fs.writeFile(batPath, generateWindowsBat(name, version, startPort));
     return batPath;
 }
+/**
+ * Check if a photon directory contains an app photon (main() + @ui).
+ * Reads .ts/.js source files and looks for class-level @ui asset declaration
+ * and a main() method linked to that UI.
+ */
+async function checkIsAppPhoton(photonDir) {
+    const entries = await fs.readdir(photonDir);
+    const sourceFiles = entries.filter((f) => /\.(ts|js)$/.test(f) && !f.endsWith('.d.ts'));
+    for (const file of sourceFiles) {
+        const content = await fs.readFile(path.join(photonDir, file), 'utf-8');
+        // Check for class-level @ui asset declaration (e.g. @ui my-view ./ui/view.html)
+        const hasClassUi = /@ui\s+\S+\s+\S+/.test(content);
+        // Check for a main method
+        const hasMain = /(?:async\s+)?main\s*\(/.test(content);
+        if (hasClassUi && hasMain)
+            return true;
+    }
+    return false;
+}
 export function registerPackageAppCommand(program) {
     program
         .command('package')
@@ -176,16 +216,57 @@ export function registerPackageAppCommand(program) {
             console.error(`Error: photon directory not found: ${photonDir}`);
             process.exit(1);
         }
+        // Validate that the photon is an app (has main() method + @ui)
+        const isApp = await checkIsAppPhoton(photonDir);
+        if (!isApp) {
+            console.error(`Error: "${name}" is not an app photon.\n` +
+                `Only photons with a main() method and a linked @ui can be packaged as PWA apps.`);
+            process.exit(1);
+        }
+        // Get the current photon runtime version to pin in launchers
+        const { PHOTON_VERSION } = await import('../../version.js');
         const className = toClassName(name);
-        console.log(`\n📦 Packaging ${name}...\n`);
+        console.log(`\n📦 Packaging ${name} (runtime v${PHOTON_VERSION})...\n`);
         await fs.mkdir(outputDir, { recursive: true });
         // Generate all platform launchers
-        const macAppPath = await generateMacOSApp(name, className, photonDir, startPort, outputDir);
-        const [linuxShPath, linuxDesktopPath] = await generateLinuxLauncher(name, photonDir, startPort, outputDir);
-        const winBatPath = await generateWindowsLauncher(name, photonDir, startPort, outputDir);
+        const macAppPath = await generateMacOSApp(name, className, PHOTON_VERSION, startPort, outputDir);
+        const [linuxShPath, linuxDesktopPath] = await generateLinuxLauncher(name, PHOTON_VERSION, startPort, outputDir);
+        const winBatPath = await generateWindowsLauncher(name, PHOTON_VERSION, startPort, outputDir);
         console.log(`   ✓ macOS    ${macAppPath}`);
         console.log(`   ✓ Linux    ${linuxShPath}, ${path.basename(linuxDesktopPath)}`);
         console.log(`   ✓ Windows  ${winBatPath}`);
+        // Write pwa.json to record this PWA instance configuration
+        try {
+            const pwaConfigPath = path.join(workingDir, 'pwa.json');
+            let config = { instances: [] };
+            try {
+                const raw = await fs.readFile(pwaConfigPath, 'utf-8');
+                config = JSON.parse(raw);
+                if (!Array.isArray(config.instances))
+                    config.instances = [];
+            }
+            catch {
+                // File doesn't exist yet — use default
+            }
+            // Deduplicate by port + photon name
+            const exists = config.instances.some((i) => i.port === startPort && i.photon === name);
+            if (!exists) {
+                config.instances.push({
+                    port: startPort,
+                    photon: name,
+                    version: PHOTON_VERSION,
+                    createdAt: new Date().toISOString(),
+                });
+                await fs.writeFile(pwaConfigPath, JSON.stringify(config, null, 2));
+                console.log(`   ✓ pwa.json  PWA configured (port ${startPort})`);
+            }
+            else {
+                console.log(`   ✓ pwa.json  Already configured`);
+            }
+        }
+        catch (err) {
+            console.error(`   ⚠ pwa.json  ${err.message || 'Failed to write'}`);
+        }
         console.log();
     });
 }