@portel/photon 1.33.1 → 1.33.3

package/dist/template-manager.js

@@ -16,7 +16,7 @@ export class TemplateManager {
     templateDir;
     hashFile;
     // Current template version - increment when templates are updated
-    static TEMPLATE_VERSION = '3.0.0';
+    static TEMPLATE_VERSION = '4.0.0';
     constructor(workingDir) {
         this.marketplaceDir = path.join(workingDir, '.marketplace');
         this.templateDir = path.join(this.marketplaceDir, '_templates');
@@ -348,11 +348,11 @@ export class TemplateManager {
     getDefaultReadmeTemplate() {
         return `# \${marketplaceName}
 
-\${$if(marketplaceDescription, \`\${marketplaceDescription}\n\n\`, \`A collection of single-file TypeScript [MCP](https://modelcontextprotocol.io/introduction) servers for AI assistants.\n\n\`)}## Photons
+\${$if(marketplaceDescription, \`\${marketplaceDescription}\n\n\`, marketplaceKind === 'examples' ? \`Small examples that teach one Photon capability at a time.\n\n\` : \`Ready-to-use single-file TypeScript [MCP](https://modelcontextprotocol.io/introduction) apps and tools for AI assistants.\n\n\`)}\${$if(marketplaceKind === 'apps', \`Use these directly from Claude Desktop, ChatGPT connectors, Beam, or the Photon CLI. Each photon is one auditable TypeScript file plus optional UI assets.\n\n\`, '')}\${$if(marketplaceKind === 'examples', \`These are learning-oriented photons. For production-ready tools, use the main Photon app marketplace.\n\n\`, '')}## Gallery
 
-| Photon | Description | Tools | Type |
-|--------|-------------|-------|------|
-\${each(photons, (p) => \`| [**\${properName(p.description, p.name)}**](\${p.name}.md) | \${brief(cleanDesc(p.description))} | \${p.tools ? p.tools.length : 0} | \${p.photonType === 'workflow' ? 'Workflow' : p.photonType === 'streaming' ? 'Streaming' : 'API'}\${(p.features || []).some(f => f === 'custom-ui' || f === 'dashboard') ? ' + UI' : ''} |\n\`)}
+\${each(sections || [{ title: 'Photons', description: '', photons }], (section) => \`\${section.title ? \`### \${section.title}\n\n\` : ''}\${section.description ? \`\${section.description}\n\n\` : ''}| Photon | What it gives an agent | Tools | Shape |
+|--------|------------------------|-------|-------|
+\${each(section.photons || [], (p) => \`| [**\${p.label || properName(p.description, p.name)}**](\${p.name}.md) | \${p.summary || brief(cleanDesc(p.description))} | \${p.tools ? p.tools.length : 0} | \${p.photonType === 'workflow' ? 'Workflow' : p.photonType === 'streaming' ? 'Streaming' : 'API'}\${(p.features || []).some(f => f === 'custom-ui' || f === 'dashboard') ? ' + UI' : ''} |\n\`)}\n\`)}
 
 ## Quick Start
 
@@ -360,20 +360,20 @@ export class TemplateManager {
 # Install the CLI
 ${globalInstallCmd('@portel/photon')}
 
-# Add a photon
-photon add filesystem
+# Add a photon from this marketplace
+photon add \${quickStart.photon}
 
 # Get MCP config (paste into your client)
-photon get filesystem --mcp
+\${quickStart.command}
 \\\`\\\`\\\`
 
 Output:
 \\\`\\\`\\\`json
 {
   "mcpServers": {
-    "filesystem": {
+    "\${quickStart.photon}": {
       "command": "photon",
-      "args": ["mcp", "filesystem"]
+      "args": ["mcp", "\${quickStart.photon}"]
     }
   }
 }
@@ -383,15 +383,15 @@ Output:
 
 \\\`\\\`\\\`bash
 photon add <name>        # Install a photon
-photon get               # List installed photons
-photon get <name> --mcp  # Get MCP config for a photon
+photon list              # List local photons
+photon info <name> --mcp # Get MCP config for a photon
 photon search <keyword>  # Search available photons
 photon upgrade           # Upgrade all photons
 \\\`\\\`\\\`
-\${$if(marketplaceName === 'photons', \`
+\${$if(marketplaceName.toLowerCase().includes('photon app'), \`
 ## Contributing
 
-PRs welcome for bug fixes, enhancements, and new photons.
+PRs welcome for focused, well-tested photons. Keep the gallery small: polished apps here, teaching examples in the examples marketplace.
 \`, '')}
 ---
 

package/dist/version.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Published package version without local git build metadata.
+ *
+ * Use this for generated files that are committed to repositories, where
+ * checkout-specific SHA noise would make otherwise stable outputs churn.
+ */
+export declare const PHOTON_PACKAGE_VERSION: string;
 /**
  * Photon runtime version. When running from a git checkout, includes a
  * `+sha.<short>` build-metadata suffix (semver 2.0 legal) so `photon

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AA+FA;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,MAAgC,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,OAA8B,CAAC;AAE1D,eAAO,MAAM,mBAAmB,EAAE,MAC8B,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CAQrD"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AA+FA;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAoB,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,MAA2C,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,OAA8B,CAAC;AAE1D,eAAO,MAAM,mBAAmB,EAAE,MAC8B,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CAQrD"}

package/dist/version.js

@@ -98,12 +98,19 @@ function computeDevBuildMarker() {
     }
 }
 const devMarker = computeDevBuildMarker();
+/**
+ * Published package version without local git build metadata.
+ *
+ * Use this for generated files that are committed to repositories, where
+ * checkout-specific SHA noise would make otherwise stable outputs churn.
+ */
+export const PHOTON_PACKAGE_VERSION = pkg.version;
 /**
  * Photon runtime version. When running from a git checkout, includes a
  * `+sha.<short>` build-metadata suffix (semver 2.0 legal) so `photon
  * --version` distinguishes the dev tree from a published tarball.
  */
-export const PHOTON_VERSION = pkg.version + devMarker;
+export const PHOTON_VERSION = PHOTON_PACKAGE_VERSION + devMarker;
 /**
  * True when this process is running from a git checkout rather than an
  * installed npm tarball. Useful for guidance: agents can warn users when

package/dist/version.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon",
-  "version": "1.33.1",
+  "version": "1.33.3",
   "description": "You focus on the business logic. We'll enable the rest. Build MCP servers and CLI tools in a single TypeScript file.",
   "type": "module",
   "packageManager": "bun@1.2.20",

package/templates/cloudflare/worker.ts.template

@@ -24,6 +24,7 @@ const MCP_AUTH_MODE = __MCP_AUTH_MODE__;
 const MCP_JWT_ISSUER = __MCP_JWT_ISSUER__;
 const MCP_JWT_AUDIENCE = __MCP_JWT_AUDIENCE__;
 const MCP_JWT_JWKS = __MCP_JWT_JWKS__;
+const DEPLOY_INSTANCE_ALIASES: Record<string, string> = __INSTANCE_ALIASES__;
 
 /**
  * Photon name → Worker env binding name. Generated at deploy time from the
@@ -1743,27 +1744,44 @@ const CF_ACCESS_ENABLED = __CF_ACCESS_ENABLED__;
  * CF Access verifies the JWT at the edge before the request reaches this
  * Worker, so we trust the claim without re-verifying the signature here.
  */
-function extractInstance(request: Request): string {
+function canonicalizeInstance(instance: string, env: Env): string {
+  const key = instance.trim().toLowerCase();
+  const aliases: Record<string, string> = { ...DEPLOY_INSTANCE_ALIASES };
+  const runtimeAliases = env.PHOTON_INSTANCE_ALIASES;
+  if (typeof runtimeAliases === 'string' && runtimeAliases.trim()) {
+    try {
+      const parsed = JSON.parse(runtimeAliases) as Record<string, unknown>;
+      for (const [from, to] of Object.entries(parsed)) {
+        if (typeof to === 'string' && to.trim()) aliases[from.toLowerCase()] = to;
+      }
+    } catch (err) {
+      console.warn('canonicalizeInstance: PHOTON_INSTANCE_ALIASES parse failed', err);
+    }
+  }
+  return aliases[key] || instance;
+}
+
+function extractInstance(request: Request, env: Env): string {
+  let instance: string | null = null;
   if (CF_ACCESS_ENABLED) {
     const headerEmail = request.headers.get('Cf-Access-Authenticated-User-Email');
-    if (headerEmail) return headerEmail;
+    if (headerEmail) instance = headerEmail;
     const jwt = request.headers.get('Cf-Access-Jwt-Assertion');
-    if (jwt) {
+    if (!instance && jwt) {
       try {
         const part = jwt.split('.')[1];
         const b64 = part.replace(/-/g, '+').replace(/_/g, '/');
         const padded = b64 + '==='.slice((b64.length + 3) % 4);
         const payload = JSON.parse(atob(padded));
-        if (payload?.email) return payload.email as string;
+        if (payload?.email) instance = payload.email as string;
       } catch (err) {
         console.warn('extractInstance: JWT parse failed', err);
       }
     }
   }
   const url = new URL(request.url);
-  return (
-    url.searchParams.get('instance') ?? request.headers.get('X-Photon-Instance') ?? 'default'
-  );
+  instance ??= url.searchParams.get('instance') ?? request.headers.get('X-Photon-Instance') ?? 'default';
+  return canonicalizeInstance(instance, env);
 }
 
 export default {
@@ -1778,7 +1796,7 @@ export default {
         },
       });
     }
-    const instance = extractInstance(request);
+    const instance = extractInstance(request, env);
     const id = env.__HOST_BINDING__.idFromName(instance);
     return env.__HOST_BINDING__.get(id).fetch(request);
   },