@portel/photon-core 2.22.0 → 2.24.0

package/dist/schema-extractor.js

@@ -11,6 +11,21 @@ import * as fs from 'fs/promises';
 import * as ts from 'typescript';
 import { parseDuration, parseRate } from './utils/duration.js';
 import { builtinRegistry } from './middleware.js';
+import { sanitizeDescription } from './description-sanitizer.js';
+// Warn once per unique (method, rule) pair so poisoned photons don't spam.
+const sanitizeWarnings = new Set();
+// Track which `handle*` method names have already emitted a deprecation
+// warning this process so large photons don't spam the console.
+const handlePrefixWarned = new Set();
+function warnHandlePrefixOnce(methodName) {
+    if (handlePrefixWarned.has(methodName))
+        return;
+    handlePrefixWarned.add(methodName);
+    // eslint-disable-next-line no-console
+    console.error(`[photon] deprecation: method "${methodName}" is being auto-registered as a ` +
+        `webhook via the legacy handle* prefix. Add an explicit "@webhook" JSDoc ` +
+        `tag; the prefix convention will be removed in the next minor release.`);
+}
 /**
  * Extract schemas from a Photon MCP class file
  */
@@ -309,6 +324,31 @@ export class SchemaExtractor {
                     propertyDocs.set(propMatch[1], propMatch[2].trim());
                 }
                 const properties = [];
+                // Inline-JSDoc helper: pull the description from a /** ... */ comment
+                // that immediately precedes a property assignment inside the object
+                // literal. Class-level @property tags still win when both are
+                // present (so existing photons aren't disrupted).
+                const sourceText = sourceFile.text;
+                const inlineDescriptionFor = (prop) => {
+                    const ranges = ts.getLeadingCommentRanges(sourceText, prop.pos);
+                    if (!ranges || ranges.length === 0)
+                        return undefined;
+                    // Use the last comment block before the property (closest to it).
+                    const block = ranges[ranges.length - 1];
+                    if (sourceText[block.pos] !== '/' ||
+                        sourceText[block.pos + 1] !== '*' ||
+                        sourceText[block.pos + 2] !== '*') {
+                        return undefined;
+                    }
+                    const raw = sourceText.slice(block.pos + 3, block.end - 2);
+                    // Strip leading "*" markers, trim, collapse whitespace.
+                    return raw
+                        .split('\n')
+                        .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+                        .filter(Boolean)
+                        .join(' ')
+                        .trim();
+                };
                 for (const prop of member.initializer.properties) {
                     if (!ts.isPropertyAssignment(prop))
                         continue;
@@ -374,7 +414,7 @@ export class SchemaExtractor {
                     properties.push({
                         name: propName,
                         type,
-                        description: propertyDocs.get(propName),
+                        description: propertyDocs.get(propName) ?? inlineDescriptionFor(prop),
                         default: defaultValue,
                         required,
                     });
@@ -837,10 +877,34 @@ export class SchemaExtractor {
         const params = [];
         try {
             const sourceFile = ts.createSourceFile('temp.ts', source, ts.ScriptTarget.Latest, true);
+            // Per-parameter JSDoc: prefer an inline /** ... */ block immediately
+            // before the parameter (the natural way authors write it), fall back
+            // to a constructor-level @param tag.
+            const sourceText = sourceFile.text;
+            const inlineDescriptionFor = (param) => {
+                const ranges = ts.getLeadingCommentRanges(sourceText, param.pos);
+                if (!ranges || ranges.length === 0)
+                    return undefined;
+                const block = ranges[ranges.length - 1];
+                if (sourceText[block.pos] !== '/' ||
+                    sourceText[block.pos + 1] !== '*' ||
+                    sourceText[block.pos + 2] !== '*') {
+                    return undefined;
+                }
+                const raw = sourceText.slice(block.pos + 3, block.end - 2);
+                return raw
+                    .split('\n')
+                    .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+                    .filter(Boolean)
+                    .join(' ')
+                    .trim();
+            };
             const visit = (node) => {
                 if (ts.isClassDeclaration(node)) {
                     node.members.forEach((member) => {
                         if (ts.isConstructorDeclaration(member)) {
+                            const ctorJsdoc = this.getJSDocComment(member, sourceFile);
+                            const ctorParamDocs = this.extractParamDocs(ctorJsdoc);
                             member.parameters.forEach((param) => {
                                 if (param.name && ts.isIdentifier(param.name)) {
                                     const name = param.name.getText(sourceFile);
@@ -858,6 +922,7 @@ export class SchemaExtractor {
                                         hasDefault,
                                         defaultValue,
                                         isPrimitive: this.isPrimitiveType(type),
+                                        description: inlineDescriptionFor(param) ?? ctorParamDocs.get(name),
                                     });
                                 }
                             });
@@ -1074,6 +1139,27 @@ export class SchemaExtractor {
             const def = builtinRegistry.get('locked');
             declarations.push({ name: 'locked', config: { name: lockName }, phase: def?.phase ?? 60 });
         }
+        // @mask <field1,field2,...> — redact named fields from the response.
+        // Accepts comma- or whitespace-separated field names.
+        const maskMatch = jsdocContent.match(/@mask\s+([^\n@]+)/i);
+        if (maskMatch) {
+            const def = builtinRegistry.get('mask');
+            const rawValue = maskMatch[1].trim();
+            const config = def?.parseShorthand
+                ? def.parseShorthand(rawValue)
+                : { fields: rawValue.split(/[,\s]+/).filter(Boolean), placeholder: '[REDACTED]' };
+            declarations.push({ name: 'mask', config, phase: def?.phase ?? 85 });
+        }
+        // @maxResponseBytes <N> — cap serialized response size.
+        const maxBytesMatch = jsdocContent.match(/@maxResponseBytes\s+(\d+)/i);
+        if (maxBytesMatch) {
+            const def = builtinRegistry.get('maxResponseBytes');
+            const rawValue = maxBytesMatch[1];
+            const config = def?.parseShorthand
+                ? def.parseShorthand(rawValue)
+                : { limit: parseInt(rawValue, 10) || 0 };
+            declarations.push({ name: 'maxResponseBytes', config, phase: def?.phase ?? 88 });
+        }
         // 2. Extract @use declarations
         const useDecls = this.extractUseDeclarations(jsdocContent);
         for (const { name, rawConfig } of useDecls) {
@@ -1100,7 +1186,7 @@ export class SchemaExtractor {
     extractDescription(jsdocContent) {
         // Split by @tags that appear at start of a JSDoc line (after optional * prefix)
         // This avoids matching @tag references inline in description text
-        const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility|auth)\b/)[0];
+        const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility|auth|mask|maxResponseBytes)\b/)[0];
         // Remove leading * from each line and trim
         const lines = beforeTags
             .split('\n')
@@ -1135,8 +1221,25 @@ export class SchemaExtractor {
             prevWasBlank = false;
         }
         const description = parts.join('');
-        // Clean up multiple spaces
-        return description.replace(/\s+/g, ' ').trim() || 'No description';
+        // Clean up multiple spaces, then defend against tool-description poisoning.
+        const collapsed = description.replace(/\s+/g, ' ').trim() || 'No description';
+        const { cleaned, warnings, truncated } = sanitizeDescription(collapsed);
+        if (warnings.length > 0 || truncated) {
+            for (const w of warnings) {
+                const key = `${w.rule}|${w.sample}`;
+                if (sanitizeWarnings.has(key))
+                    continue;
+                sanitizeWarnings.add(key);
+                // eslint-disable-next-line no-console
+                console.warn(`[photon] description sanitizer: redacted ${w.rule} (sample: "${w.sample}")`);
+            }
+            if (truncated && !sanitizeWarnings.has('truncated')) {
+                sanitizeWarnings.add('truncated');
+                // eslint-disable-next-line no-console
+                console.warn('[photon] description sanitizer: truncated oversized description');
+            }
+        }
+        return cleaned;
     }
     /**
      * Extract parameter descriptions from JSDoc @param tags
@@ -1790,10 +1893,15 @@ export class SchemaExtractor {
     // DAEMON FEATURE EXTRACTION
     // ═══════════════════════════════════════════════════════════════════════════════
     /**
-     * Extract webhook configuration from @webhook tag or handle* prefix
+     * Extract webhook configuration from @webhook tag or handle* prefix.
      * - @webhook → use method name as path
      * - @webhook stripe → custom path "stripe"
-     * - handle* prefix → auto-detected as webhook
+     * - handle* prefix → auto-detected as webhook (DEPRECATED)
+     *
+     * The handle* prefix is a legacy convention being removed. It still
+     * works for one release but emits a one-time stderr warning per
+     * method so users can migrate to the explicit @webhook tag before
+     * the convention is dropped.
      */
     extractWebhook(jsdocContent, methodName) {
         // Check for @webhook tag with optional path
@@ -1804,8 +1912,9 @@ export class SchemaExtractor {
             // Return custom path if specified, otherwise true for bare @webhook
             return path || true;
         }
-        // Check for handle* prefix (convention)
+        // Check for handle* prefix (legacy convention — deprecated).
         if (methodName.startsWith('handle')) {
+            warnHandlePrefixOnce(methodName);
             return true;
         }
         return undefined;
@@ -2091,6 +2200,10 @@ export class SchemaExtractor {
         if (['panels', 'tabs', 'accordion', 'stack', 'columns'].includes(format)) {
             return format;
         }
+        // Match declarative UI formats (A2UI v0.9 rides on AG-UI)
+        if (format === 'a2ui') {
+            return 'a2ui';
+        }
         return undefined;
     }
     /**
@@ -2630,34 +2743,53 @@ export class SchemaExtractor {
         return mimeTypes[ext] || 'application/octet-stream';
     }
 }
+/**
+ * Match a `this`-like base in source code. Covers:
+ *   this            — literal
+ *   (this as any)   — TS `as` cast (the most common workaround when
+ *                     TypeScript can't see a runtime-injected method)
+ *   (this as SomeClass), (this as unknown as T)
+ *   (<any>this), (<T>this) — older angle-bracket cast syntax
+ *
+ * Not covered: aliasing (`const self = this`), destructuring
+ * (`const { call } = this`), or bracket access (`this['call']`).
+ * Those require dataflow analysis which a regex can't do; the loader
+ * compensates by always-injecting the cheap convenience methods whose
+ * gating would otherwise silently fail for those patterns.
+ */
+const THIS_BASE = String.raw `(?:\bthis\b|\(\s*<[^>]+>\s*this\s*\)|\(\s*this\s+as\s+[^)]+\))`;
+function memberAccess(name, trailing) {
+    return new RegExp(`${THIS_BASE}\\s*\\.\\s*${name}\\s*${trailing}`);
+}
 /**
  * Detect capabilities used by a Photon from its source code.
  *
  * Scans for `this.emit(`, `this.memory`, `this.call(`, etc. patterns
- * and returns the set of capabilities that the runtime should inject.
+ * (including typed-access workarounds like `(this as any).call(`) and
+ * returns the set of capabilities that the runtime should inject.
  *
  * This enables plain classes (no extends Photon) to use all framework
  * features — the loader detects usage and injects automatically.
  */
 export function detectCapabilities(source) {
     const caps = new Set();
-    if (/this\.emit\s*\(/.test(source))
+    if (memberAccess('emit', '\\(').test(source))
         caps.add('emit');
-    if (/this\.render\s*\(/.test(source))
+    if (memberAccess('render', '\\(').test(source))
         caps.add('emit'); // render() needs emit injection
-    if (/this\.memory\b/.test(source))
+    if (memberAccess('memory', '\\b').test(source))
         caps.add('memory');
-    if (/this\.call\s*\(/.test(source))
+    if (memberAccess('call', '\\(').test(source))
         caps.add('call');
-    if (/this\.mcp\s*\(/.test(source))
+    if (memberAccess('mcp', '\\(').test(source))
         caps.add('mcp');
-    if (/this\.withLock\s*\(/.test(source))
+    if (memberAccess('withLock', '\\(').test(source))
         caps.add('lock');
-    if (/this\.instanceMeta\b/.test(source))
+    if (memberAccess('instanceMeta', '\\b').test(source))
         caps.add('instanceMeta');
-    if (/this\.allInstances\s*\(/.test(source))
+    if (memberAccess('allInstances', '\\(').test(source))
         caps.add('allInstances');
-    if (/this\.caller\b/.test(source))
+    if (memberAccess('caller', '\\b').test(source))
         caps.add('caller');
     return caps;
 }