@portel/photon-core 2.25.0 → 2.27.0

package/src/env.ts

@@ -0,0 +1,28 @@
+/**
+ * CloudflareEnv — raw Cloudflare Worker `env`, surfaced as an explicit
+ * constructor injection so the import line itself signals that the
+ * importing photon depends on a Cloudflare deploy target.
+ *
+ * @example
+ * ```ts
+ * import type { CloudflareEnv } from "@portel/photon";
+ *
+ * interface MyBindings {
+ *   WEATHER_KV: KVNamespace;
+ *   PHOTOS: R2Bucket;
+ * }
+ *
+ * export class Weather {
+ *   constructor(private env: CloudflareEnv<MyBindings>) {}
+ *   async forecast() {
+ *     await this.env.WEATHER_KV.put("k", "v");
+ *   }
+ * }
+ * ```
+ *
+ * The default loose type (`Record<string, unknown>`) keeps the no-types
+ * path working. Authors who want strict binding shapes pass their own
+ * type parameter; future codegen from `protected cfBindings` can fill
+ * this in automatically.
+ */
+export type CloudflareEnv<T = Record<string, unknown>> = T;

package/src/index.ts

@@ -154,6 +154,33 @@ export {
 // Core base class with lifecycle hooks
 export { Photon, Photon as PhotonMCP } from './base.js';
 
+// Cloudflare deploy-target injections (constructor-injected, not on Photon)
+export {
+  type Cloudflare,
+  type ScopedBindingCategory,
+  bindingNameFor,
+  notConfiguredCloudflare,
+  createCloudflareFromEnv,
+  SHARED_AI_BINDING,
+  SHARED_IMAGES_BINDING,
+  SHARED_BROWSER_BINDING,
+} from './cloudflare.js';
+export { type CloudflareEnv } from './env.js';
+// Structural CF binding types — published so hosts can type their own
+// CF adapters against the same shape `Cloudflare` exposes (e.g. unit
+// tests that mock `cf.kv()` returns).
+export {
+  type R2BucketLike,
+  type KVNamespaceLike,
+  type D1DatabaseLike,
+  type D1PreparedStatementLike,
+  type QueueLike,
+  type VectorizeIndexLike,
+  type AiLike,
+  type ImagesBindingLike,
+  type FetcherLike,
+} from './cf.js';
+
 // Mixin for capability injection without requiring inheritance
 export { withPhotonCapabilities } from './mixins.js';
 

package/src/mixins.ts

@@ -84,6 +84,18 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
      */
     private _schedule?: ScheduleProvider;
 
+    /**
+     * Cloudflare Worker env when deployed; undefined on local hosts.
+     * See Photon.env for the full contract.
+     */
+    readonly env?: Record<string, unknown>;
+
+    /**
+     * True when the active /mcp request passed the PHOTON_MCP_BEARER
+     * gate. See Photon.mcpAuthed for the full contract.
+     */
+    readonly mcpAuthed?: boolean;
+
     /**
      * Cross-photon call handler - injected by runtime
      * @internal

package/src/photon-loader-lite.ts

@@ -38,6 +38,12 @@ import { withPhotonCapabilities } from './mixins.js';
 import { MemoryProvider } from './memory.js';
 import { ScheduleProvider } from './schedule.js';
 import { toEnvVarName, parseEnvValue, type MissingParamInfo } from './env-utils.js';
+import { Photon as PhotonBase } from './base.js';
+import {
+  type Cloudflare,
+  notConfiguredCloudflare,
+  createCloudflareFromEnv,
+} from './cloudflare.js';
 import type { ExtractedSchema } from './types.js';
 import type { MCPClientFactory } from '@portel/mcp';
 import { getCacheDir } from './data-paths.js';
@@ -59,6 +65,22 @@ export interface PhotonOptions {
   sessionId?: string;
   /** Namespace for data path resolution (marketplace owner). Defaults to 'local'. */
   namespace?: string;
+  /**
+   * Build a `Cloudflare` runtime for a given photon. Hosts that bring CF
+   * support (local miniflare, deployed Worker) supply a factory; the
+   * loader calls it whenever a photon's constructor needs `Cloudflare`
+   * (or whenever `this.cf.*` is detected on a plain class). When the
+   * factory is absent the loader injects a throwing-Proxy fallback so
+   * the diagnostic remains clear.
+   */
+  cloudflareFactory?: (photonName: string) => Cloudflare;
+  /**
+   * Raw Cloudflare Worker `env`. Wired through to constructor params
+   * typed `CloudflareEnv` / `CloudflareEnv<T>`. Only present when the
+   * loader is being driven by the deployed Worker template (or by a
+   * test that wants to simulate it).
+   */
+  cloudflareEnv?: Record<string, unknown>;
 }
 
 export interface PhotonEvent {
@@ -263,6 +285,24 @@ async function loadPhotonInternal(
     // 9. Instantiate
     const instance = new EnhancedClass(...constructorArgs) as Record<string, any>;
 
+    // 9a. Forgiving auto-inject: classes that reference `this.cf.*` or
+    // `this.cfEnv.*` without declaring the matching constructor param
+    // still get the field populated, so authoring stays loose. The
+    // explicit-injection path (a typed constructor param) takes
+    // precedence; this only fills gaps. Mirrors how the classic loader
+    // injects `_callHandler` etc. for plain classes.
+    const detected = detectCapabilities(source);
+    const hasExplicitCloudflare = injections.some(i => i.injectionType === 'cloudflare');
+    const hasExplicitCloudflareEnv = injections.some(i => i.injectionType === 'cloudflareEnv');
+    if (detected.has('cloudflare') && !hasExplicitCloudflare && instance.cf === undefined) {
+      instance.cf = options.cloudflareFactory
+        ? options.cloudflareFactory(photonName)
+        : notConfiguredCloudflare();
+    }
+    if (detected.has('cloudflareEnv') && !hasExplicitCloudflareEnv && instance.cfEnv === undefined) {
+      instance.cfEnv = options.cloudflareEnv ?? makeThrowingCloudflareEnv();
+    }
+
     // 10. Set photon identity. Namespace mirrors the file's position under
     // baseDir (same rule the classic loader applies). Falls back to 'local'
     // when no baseDir context is available. See
@@ -450,6 +490,38 @@ async function resolveConstructorArgs(
         break;
       }
 
+      case 'photonRuntime': {
+        // `private photon: Photon` — inject a Photon instance configured
+        // identically to the host so `this.photon.memory.set(...)`,
+        // `this.photon.emit(...)`, etc. resolve to the same scope as
+        // the equivalent `extends Photon` calls would. Identity-stable
+        // per host load.
+        const runtime = createPhotonRuntimeForHost(photonName, currentPath, options);
+        values.push(runtime);
+        break;
+      }
+
+      case 'cloudflare': {
+        // `private cf: Cloudflare` — wrapped, auto-named CF surface.
+        const cf = options.cloudflareFactory
+          ? options.cloudflareFactory(photonName)
+          : notConfiguredCloudflare();
+        values.push(cf);
+        break;
+      }
+
+      case 'cloudflareEnv': {
+        // `private cfEnv: CloudflareEnv` — raw Worker env. On hosts
+        // without a CF runtime, hand back a throwing Proxy so the
+        // diagnostic names the imported symbol clearly.
+        if (options.cloudflareEnv) {
+          values.push(options.cloudflareEnv);
+        } else {
+          values.push(makeThrowingCloudflareEnv());
+        }
+        break;
+      }
+
       default:
         values.push(undefined);
     }
@@ -466,6 +538,119 @@ async function resolveConstructorArgs(
   return values;
 }
 
+// ═══════════════════════════════════════════════════════════════════
+// Photon-as-injection helpers
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Build the `Photon` instance handed to `private photon: Photon` ctor
+ * params. We instantiate the real base class and configure it with the
+ * host photon's identity so every capability (`memory`, `schedule`,
+ * `emit`, `call`, `mcp`, `caller`, `confirm`, `elicit`, `sample`,
+ * `photon.use`, ...) resolves to the same scope an equivalent
+ * `extends Photon` consumer would see. The result is shape-equivalent
+ * to a normal Photon, so authors can swap between `extends Photon` and
+ * constructor injection without touching any call site beyond the
+ * access path (`this.memory` vs `this.photon.memory`).
+ *
+ * The `_callHandler` and `setMCPFactory` wiring is deferred to the
+ * caller (see step 14 of `loadPhotonInternal`), which assigns the
+ * resolver after constructor args are built. Constructor-time access
+ * to `photon.memory` works because MemoryProvider is lazy-resolved on
+ * first use and the photon name / baseDir are set up here directly.
+ */
+function createPhotonRuntimeForHost(
+  photonName: string,
+  currentPath: string,
+  options: PhotonOptions,
+): InstanceType<typeof PhotonBase> {
+  const runtime = new PhotonBase() as PhotonBase & Record<string, unknown>;
+  runtime._photonName = photonName;
+  runtime._photonNamespace =
+    options.namespace ?? deriveNamespace(currentPath, options.baseDir);
+  runtime._baseDir = options.baseDir;
+  runtime._photonFilePath = currentPath;
+  if (options.sessionId) {
+    runtime._sessionId = options.sessionId;
+  }
+  const setMCPFactory = (runtime as { setMCPFactory?: (f: MCPClientFactory) => void }).setMCPFactory;
+  if (options.mcpFactory && typeof setMCPFactory === 'function') {
+    setMCPFactory.call(runtime, options.mcpFactory);
+  }
+  // Cross-photon calls flow through the same in-process resolver the
+  // host instance uses. `loadPhotonInternal` re-assigns `_callHandler`
+  // on the host instance below; the runtime facade gets its own copy
+  // pointed at the same target resolver so injected callers and
+  // extends-Photon callers see identical behaviour.
+  runtime._callHandler = async (
+    targetPhotonName: string,
+    method: string,
+    params: Record<string, unknown>,
+  ) => {
+    const targetPath = resolvePhotonPath(targetPhotonName, currentPath, options.baseDir);
+    const target = await photon(targetPath, {
+      baseDir: options.baseDir,
+      mcpFactory: options.mcpFactory,
+      sessionId: options.sessionId,
+    });
+    return (target as Record<string, (p: Record<string, unknown>) => Promise<unknown>>)[method](params);
+  };
+  // `this.photon.photon.use()` parity: `extends Photon` instances get
+  // `_photonResolver` set by the host loader; the injected runtime
+  // needs the same resolver so dynamic photon access works identically
+  // through both consumption modes.
+  runtime._photonResolver = async (name: string, instanceName?: string) => {
+    const targetPath = resolvePhotonPath(name, currentPath, options.baseDir);
+    return photon(targetPath, {
+      baseDir: options.baseDir,
+      mcpFactory: options.mcpFactory,
+      sessionId: options.sessionId,
+      instanceName,
+    });
+  };
+  return runtime;
+}
+
+const CFENV_HINT =
+  'This photon imports `CloudflareEnv` from "@portel/photon" but no CF ' +
+  'env was attached. Run via `photon host run` (miniflare-backed) or ' +
+  'deploy with `photon host deploy cloudflare`. Outside CF, this ' +
+  'photon\'s CF-dependent methods cannot execute.';
+
+function makeThrowingCloudflareEnv(): Record<string, unknown> {
+  // Engine-internal property accesses (constructor lookup, async-iterator
+  // probing, `await` thenable check, JSON.stringify) must not throw —
+  // otherwise, harmless reflection from runtime utilities like
+  // `wireReactiveCollections` blows up the photon load before any user
+  // code runs. We satisfy those safely and only throw when actual
+  // user code reads a binding name.
+  const safePassthrough = new Set<string | symbol>([
+    'constructor',
+    'then',
+    'toJSON',
+    'toString',
+    'valueOf',
+    Symbol.toPrimitive,
+    Symbol.toStringTag,
+    Symbol.iterator,
+    Symbol.asyncIterator,
+  ]);
+  return new Proxy(Object.create(null), {
+    get(_target, prop) {
+      if (safePassthrough.has(prop)) {
+        if (prop === 'toString' || prop === Symbol.toPrimitive) {
+          return () => '[unconfigured CloudflareEnv]';
+        }
+        return undefined;
+      }
+      throw new Error(`CloudflareEnv.${String(prop)} accessed but ${CFENV_HINT}`);
+    },
+    has(_target, prop) {
+      return !safePassthrough.has(prop);
+    },
+  });
+}
+
 // ═══════════════════════════════════════════════════════════════════
 // Reactive collection wiring
 // ═══════════════════════════════════════════════════════════════════

package/src/schema-extractor.ts

@@ -33,6 +33,12 @@ function warnHandlePrefixOnce(methodName: string): void {
   );
 }
 
+export interface HttpRoute {
+  method: 'GET' | 'POST';
+  path: string;
+  handler: string;
+}
+
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
   templates: TemplateInfo[];
@@ -48,8 +54,11 @@ export interface ExtractedMetadata {
    * - 'required': all methods require authenticated caller
    * - 'optional': caller populated if token present, anonymous allowed
    * - string URL: OIDC provider URL (implies required)
+   * - 'cf-access': use Cloudflare Access JWT to identify caller
    */
-  auth?: 'required' | 'optional' | string;
+  auth?: 'required' | 'optional' | 'cf-access' | string;
+  /** HTTP routes declared with @get or @post on individual methods */
+  httpRoutes?: HttpRoute[];
 }
 
 /**
@@ -93,6 +102,9 @@ export class SchemaExtractor {
     // MCP OAuth auth requirement (from @auth tag)
     let auth: 'required' | 'optional' | string | undefined;
 
+    // HTTP routes from @get / @post method-level tags
+    const httpRoutes: HttpRoute[] = [];
+
     try {
       // If source doesn't contain a class declaration, wrap it in one
       let sourceToParse = source;
@@ -156,6 +168,18 @@ export class SchemaExtractor {
           return;
         }
 
+        // @get /path or @post /path — HTTP-only route, not an MCP tool
+        const getMatch = jsdoc.match(/@get\s+(\/\S*)/i);
+        const postMatch = jsdoc.match(/@post\s+(\/\S*)/i);
+        if (getMatch || postMatch) {
+          httpRoutes.push({
+            method: getMatch ? 'GET' : 'POST',
+            path: (getMatch ?? postMatch)![1],
+            handler: methodName,
+          });
+          return;
+        }
+
         // Check if this is an async generator method (has asterisk token)
         const isGenerator = member.asteriskToken !== undefined;
 
@@ -562,6 +586,11 @@ export class SchemaExtractor {
       result.auth = auth;
     }
 
+    // Include HTTP routes if any
+    if (httpRoutes.length > 0) {
+      result.httpRoutes = httpRoutes;
+    }
+
     return result;
   }
 
@@ -1980,17 +2009,24 @@ export class SchemaExtractor {
   }
 
   /**
-   * Check if JSDoc contains @Template tag
+   * Check if a method's JSDoc marks it as an MCP prompt template.
+   * Canonical form: `@prompt`. Legacy form `@Template` still accepted
+   * for backward compatibility with photons authored before the rename.
    */
   private hasTemplateTag(jsdocContent: string): boolean {
-    return /@Template/i.test(jsdocContent);
+    return /@(?:Template|prompt)\b/i.test(jsdocContent);
   }
 
   /**
-   * Check if JSDoc contains @Static tag
+   * Check if a method's JSDoc marks it as a dynamic MCP resource resolver.
+   * Canonical form: `@resource <uri-template>`. Legacy form `@Static`
+   * still accepted. Disambiguation from the class-level static-file form
+   * (`@resource <id> <path>`) is by argument shape: the class-level form
+   * requires `<id>` followed by a path starting with `./` or `/`, which
+   * the URI-template form never matches.
    */
   private hasStaticTag(jsdocContent: string): boolean {
-    return /@Static/i.test(jsdocContent);
+    return /@(?:Static|resource)\b/i.test(jsdocContent);
   }
 
   /**
@@ -2448,11 +2484,12 @@ export class SchemaExtractor {
   }
 
   /**
-   * Extract URI pattern from @Static tag
-   * Example: @Static github://repos/{owner}/{repo}/readme
+   * Extract URI pattern from a method's resource annotation.
+   * Canonical: `@resource github://repos/{owner}/{repo}/readme`
+   * Legacy: `@Static github://repos/{owner}/{repo}/readme`
    */
   private extractStaticURI(jsdocContent: string): string | null {
-    const match = jsdocContent.match(/@Static\s+([\w:\/\{\}\-_.]+)/i);
+    const match = jsdocContent.match(/@(?:Static|resource)\s+([\w:\/\{\}\-_.]+)/i);
     return match ? match[1].trim() : null;
   }
 
@@ -2851,6 +2888,30 @@ export class SchemaExtractor {
     const photonMap = new Map(photonDeps.map(d => [d.name, d]));
 
     return params.map(param => {
+      // Framework-recognized typed injections (matched on the parameter
+      // type, not the parameter name). Win ahead of every other rule
+      // because they are unambiguous: a user importing `Photon` /
+      // `Cloudflare` / `CloudflareEnv` and typing a constructor param
+      // with one of those names is asking the loader to wire it.
+      if (isPhotonRuntimeType(param.type)) {
+        return {
+          param,
+          injectionType: 'photonRuntime' as const,
+        };
+      }
+      if (isCloudflareType(param.type)) {
+        return {
+          param,
+          injectionType: 'cloudflare' as const,
+        };
+      }
+      if (isCloudflareEnvType(param.type)) {
+        return {
+          param,
+          injectionType: 'cloudflareEnv' as const,
+        };
+      }
+
       // Primitives → env var
       if (param.isPrimitive) {
         const envVarName = this.toEnvVarName(mcpName, param.name);
@@ -3127,7 +3188,23 @@ export class SchemaExtractor {
 /**
  * Capability types that can be auto-detected from source code
  */
-export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'instanceMeta' | 'allInstances' | 'caller';
+export type PhotonCapability =
+  | 'emit'
+  | 'memory'
+  | 'call'
+  | 'mcp'
+  | 'lock'
+  | 'instanceMeta'
+  | 'allInstances'
+  | 'caller'
+  // Forgiving auto-inject: when these are detected on a class that
+  // didn't declare a constructor param of the matching type, the loader
+  // assigns the matching field on the instance after construction so
+  // `this.cf.kv()` / `this.cfEnv.MY_KV.put(...)` work without the user
+  // having to wire the import + ctor param themselves. The diagnostic
+  // remains clear when the matching CF runtime isn't actually attached.
+  | 'cloudflare'
+  | 'cloudflareEnv';
 
 /**
  * Match a `this`-like base in source code. Covers:
@@ -3157,6 +3234,34 @@ function memberAccess(name: string, trailing: '\\(' | '\\b'): RegExp {
   return new RegExp(`${THIS_BASE}\\s*\\.\\s*${name}\\s*${trailing}`);
 }
 
+/**
+ * Constructor-param type matchers for the framework-injected types.
+ * The schema extractor sees parameter types as raw text (e.g. `"Photon"`,
+ * `"Cloudflare"`, `"CloudflareEnv<MyBindings>"`), so we match by string.
+ *
+ * Optional modifiers / unions like `Photon | undefined` are accepted so
+ * authors who write `private photon?: Photon` get the same injection.
+ */
+function stripNullish(type: string): string {
+  return type
+    .trim()
+    .replace(/\|\s*undefined\b/g, '')
+    .replace(/\|\s*null\b/g, '')
+    .trim();
+}
+
+export function isPhotonRuntimeType(type: string): boolean {
+  return /^Photon$/.test(stripNullish(type));
+}
+
+export function isCloudflareType(type: string): boolean {
+  return /^Cloudflare$/.test(stripNullish(type));
+}
+
+export function isCloudflareEnvType(type: string): boolean {
+  return /^CloudflareEnv(\s*<[\s\S]+>)?$/.test(stripNullish(type));
+}
+
 /**
  * Detect capabilities used by a Photon from its source code.
  *
@@ -3178,5 +3283,10 @@ export function detectCapabilities(source: string): Set<PhotonCapability> {
   if (memberAccess('instanceMeta', '\\b').test(source)) caps.add('instanceMeta');
   if (memberAccess('allInstances', '\\(').test(source)) caps.add('allInstances');
   if (memberAccess('caller', '\\b').test(source)) caps.add('caller');
+  // Forgiving auto-inject signals — surface as separate capabilities so
+  // the loader can populate `instance.cf` / `instance.cfEnv` for plain
+  // classes that reference them without the explicit constructor param.
+  if (memberAccess('cf', '\\b').test(source)) caps.add('cloudflare');
+  if (memberAccess('cfEnv', '\\b').test(source)) caps.add('cloudflareEnv');
   return caps;
 }

package/src/types.ts

@@ -313,7 +313,22 @@ export interface ConstructorParam {
 /**
  * Injection type for constructor parameters
  */
-export type InjectionType = 'env' | 'mcp' | 'photon' | 'state';
+export type InjectionType =
+  | 'env'
+  | 'mcp'
+  | 'photon'
+  | 'state'
+  // Constructor param typed `Photon` from @portel/photon — loader injects
+  // a Photon instance configured identically to the host photon.
+  | 'photonRuntime'
+  // Constructor param typed `Cloudflare` — loader injects a wrapped CF
+  // surface (auto-named bindings) backed by miniflare locally or by the
+  // deployed Worker `env`.
+  | 'cloudflare'
+  // Constructor param typed `CloudflareEnv` / `CloudflareEnv<T>` — loader
+  // injects the raw Worker `env`. Escape hatch for service bindings
+  // and exotic features the wrapped surface doesn't cover.
+  | 'cloudflareEnv';
 
 /**
  * Resolved injection info for a constructor parameter