@portel/photon 1.14.0 → 1.16.1

package/dist/meta.js

@@ -0,0 +1,320 @@
+/**
+ * _meta — Transport-agnostic system parameter namespace
+ *
+ * Clients attach `_meta` to tool call arguments for system-level hints.
+ * The runtime strips it before method invocation — methods never see it.
+ *
+ * Supported keys:
+ *   format   — Output format: csv, json, yaml, markdown, html
+ *   viewport — Container size hint: { width, height? }
+ *   fields   — Field projection: { include?: [], exclude?: [] }
+ *   locale   — Localization: { language?, timezone? }
+ */
+// Default formats available for all methods (trivial serialization)
+const DEFAULT_EXPORT_FORMATS = ['json', 'yaml'];
+// ═══════════════════════════════════════════════════════════════════════════════
+// STRIP & APPLY
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Extract `_meta` from tool call arguments.
+ * Returns clean args (without _meta) and the extracted meta params.
+ */
+export function stripMeta(args) {
+    if (!args || typeof args !== 'object' || !('_meta' in args)) {
+        return { cleanArgs: args };
+    }
+    const { _meta, ...cleanArgs } = args;
+    return { cleanArgs, meta: _meta };
+}
+/**
+ * Apply _meta transformations to a tool result.
+ * Pipeline: field selection → format transformation.
+ *
+ * @param result - Raw method return value
+ * @param meta - Extracted _meta params
+ * @param exportFormats - Allowed formats from @export tag (undefined = defaults)
+ * @returns Transformed result, or MetaFormattedResult wrapper for text formats
+ */
+export function applyMeta(result, meta, exportFormats) {
+    let processed = result;
+    // 1. Field selection (before format, so format works on filtered data)
+    if (meta.fields) {
+        processed = applyFieldSelection(processed, meta.fields);
+    }
+    // 2. Format transformation
+    if (meta.format) {
+        return applyFormatTransformation(processed, meta.format, exportFormats);
+    }
+    return processed;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// FIELD SELECTION
+// ═══════════════════════════════════════════════════════════════════════════════
+function applyFieldSelection(data, fields) {
+    if (Array.isArray(data)) {
+        return data.map((item) => applyFieldSelection(item, fields));
+    }
+    if (typeof data !== 'object' || data === null) {
+        return data;
+    }
+    const obj = data;
+    if (fields.include && fields.include.length > 0) {
+        const filtered = {};
+        for (const key of fields.include) {
+            if (key in obj)
+                filtered[key] = obj[key];
+        }
+        return filtered;
+    }
+    if (fields.exclude && fields.exclude.length > 0) {
+        const filtered = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (!fields.exclude.includes(key))
+                filtered[key] = value;
+        }
+        return filtered;
+    }
+    return data;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// FORMAT TRANSFORMATION
+// ═══════════════════════════════════════════════════════════════════════════════
+function applyFormatTransformation(data, format, exportFormats) {
+    const allowed = exportFormats ?? DEFAULT_EXPORT_FORMATS;
+    if (!allowed.includes(format)) {
+        // Return error as a formatted result so the client gets a clear message
+        return {
+            _metaFormatted: true,
+            text: `Format '${format}' not supported. Supported: ${allowed.join(', ')}`,
+            mimeType: 'text/plain',
+        };
+    }
+    switch (format) {
+        case 'json':
+            return {
+                _metaFormatted: true,
+                text: toJson(data),
+                mimeType: 'application/json',
+            };
+        case 'yaml':
+            return {
+                _metaFormatted: true,
+                text: toYaml(data),
+                mimeType: 'text/yaml',
+            };
+        case 'csv':
+            return {
+                _metaFormatted: true,
+                text: toCsv(data),
+                mimeType: 'text/csv',
+            };
+        case 'markdown':
+            return {
+                _metaFormatted: true,
+                text: toMarkdownTable(data),
+                mimeType: 'text/markdown',
+            };
+        case 'html':
+            return {
+                _metaFormatted: true,
+                text: toHtmlTable(data),
+                mimeType: 'text/html',
+            };
+        default:
+            return {
+                _metaFormatted: true,
+                text: `Format '${format}' is not yet implemented`,
+                mimeType: 'text/plain',
+            };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// SERIALIZERS
+// ═══════════════════════════════════════════════════════════════════════════════
+function toJson(data) {
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * Minimal YAML serializer — no external dependency.
+ * Handles primitives, arrays, and nested objects.
+ */
+function toYaml(data, indent = 0) {
+    const pad = '  '.repeat(indent);
+    if (data === null || data === undefined)
+        return `${pad}null`;
+    if (typeof data === 'boolean')
+        return `${pad}${data}`;
+    if (typeof data === 'number')
+        return `${pad}${data}`;
+    if (typeof data === 'string') {
+        // Quote strings that could be ambiguous
+        if (data === '' ||
+            data === 'true' ||
+            data === 'false' ||
+            data === 'null' ||
+            data.includes('\n') ||
+            data.includes(':') ||
+            data.includes('#') ||
+            /^\d/.test(data)) {
+            return `${pad}${JSON.stringify(data)}`;
+        }
+        return `${pad}${data}`;
+    }
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return `${pad}[]`;
+        return data
+            .map((item) => {
+            if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+                const entries = Object.entries(item);
+                if (entries.length === 0)
+                    return `${pad}- {}`;
+                const [firstKey, firstVal] = entries[0];
+                const firstLine = `${pad}- ${firstKey}: ${yamlValue(firstVal)}`;
+                const rest = entries
+                    .slice(1)
+                    .map(([k, v]) => `${pad}  ${k}: ${yamlValue(v)}`)
+                    .join('\n');
+                return rest ? `${firstLine}\n${rest}` : firstLine;
+            }
+            return `${pad}- ${yamlValue(item)}`;
+        })
+            .join('\n');
+    }
+    if (typeof data === 'object') {
+        const entries = Object.entries(data);
+        if (entries.length === 0)
+            return `${pad}{}`;
+        return entries
+            .map(([key, value]) => {
+            if (typeof value === 'object' && value !== null) {
+                return `${pad}${key}:\n${toYaml(value, indent + 1)}`;
+            }
+            return `${pad}${key}: ${yamlValue(value)}`;
+        })
+            .join('\n');
+    }
+    return `${pad}${typeof data === 'object' ? JSON.stringify(data) : String(data)}`;
+}
+function yamlValue(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return String(value);
+    if (typeof value === 'string') {
+        if (value === '' ||
+            value === 'true' ||
+            value === 'false' ||
+            value === 'null' ||
+            value.includes('\n') ||
+            value.includes(':') ||
+            value.includes('#') ||
+            /^\d/.test(value)) {
+            return JSON.stringify(value);
+        }
+        return value;
+    }
+    if (Array.isArray(value))
+        return JSON.stringify(value);
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/**
+ * CSV serializer — RFC 4180 compliant.
+ * Handles arrays of objects (tabular data) and single objects.
+ */
+function toCsv(data) {
+    const rows = normalizeToRows(data);
+    if (rows.length === 0)
+        return '';
+    const columns = Object.keys(rows[0]);
+    const header = columns.map(csvEscape).join(',');
+    const body = rows.map((row) => columns.map((col) => csvEscape(row[col])).join(',')).join('\n');
+    return `${header}\n${body}`;
+}
+function csvEscape(value) {
+    if (value === null || value === undefined)
+        return '';
+    const str = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    // RFC 4180: quote fields containing comma, newline, or double-quote
+    if (str.includes(',') || str.includes('\n') || str.includes('"')) {
+        return `"${str.replace(/"/g, '""')}"`;
+    }
+    return str;
+}
+/**
+ * Markdown table serializer.
+ */
+function toMarkdownTable(data) {
+    const rows = normalizeToRows(data);
+    if (rows.length === 0)
+        return '_No data_';
+    const columns = Object.keys(rows[0]);
+    const header = `| ${columns.join(' | ')} |`;
+    const separator = `| ${columns.map(() => '---').join(' | ')} |`;
+    const body = rows
+        .map((row) => `| ${columns.map((col) => mdEscape(row[col])).join(' | ')} |`)
+        .join('\n');
+    return `${header}\n${separator}\n${body}`;
+}
+function mdEscape(value) {
+    if (value === null || value === undefined)
+        return '';
+    const str = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    return str.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+/**
+ * HTML table serializer.
+ */
+function toHtmlTable(data) {
+    const rows = normalizeToRows(data);
+    if (rows.length === 0)
+        return '<p>No data</p>';
+    const columns = Object.keys(rows[0]);
+    const headerCells = columns.map((col) => `<th>${htmlEscape(col)}</th>`).join('');
+    const bodyRows = rows
+        .map((row) => {
+        const cells = columns.map((col) => `<td>${htmlEscape(row[col])}</td>`).join('');
+        return `<tr>${cells}</tr>`;
+    })
+        .join('\n');
+    return `<table>\n<thead><tr>${headerCells}</tr></thead>\n<tbody>\n${bodyRows}\n</tbody>\n</table>`;
+}
+function htmlEscape(value) {
+    if (value === null || value === undefined)
+        return '';
+    const str = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Normalize data to an array of flat objects for tabular serializers.
+ * Single objects become a one-row table. Primitives become [{ value: x }].
+ */
+function normalizeToRows(data) {
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return [];
+        // Array of objects → use directly
+        if (typeof data[0] === 'object' && data[0] !== null) {
+            return data;
+        }
+        // Array of primitives → wrap each
+        return data.map((v) => ({ value: v }));
+    }
+    if (typeof data === 'object' && data !== null) {
+        return [data];
+    }
+    if (data !== null && data !== undefined) {
+        return [{ value: data }];
+    }
+    return [];
+}
+//# sourceMappingURL=meta.js.map

package/dist/meta.js.map

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

package/dist/photon-cli-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"photon-cli-runner.d.ts","sourceRoot":"","sources":["../src/photon-cli-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH,OAAO,EAGL,YAAY,EAEb,MAAM,oBAAoB,CAAC;AAiC5B,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,EAAE,CAAC;IACJ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA8fD;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA2E9F;AA2yBD;;GAEG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+FnE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAiRf"}
+{"version":3,"file":"photon-cli-runner.d.ts","sourceRoot":"","sources":["../src/photon-cli-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH,OAAO,EAGL,YAAY,EAEb,MAAM,oBAAoB,CAAC;AAiC5B,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,EAAE,CAAC;IACJ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAogBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA2E9F;AA2yBD;;GAEG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+FnE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAwSf"}

package/dist/photon-cli-runner.js

@@ -210,10 +210,15 @@ function formatOutput(result, formatHint) {
         return true;
     }
     // Handle @format qr — render QR code in terminal
-    if (hint === 'qr' && result && typeof result === 'object') {
-        const qrValue = result.qr || result.value || result.url || result.link;
+    if (hint === 'qr' && result) {
+        // Support both plain string results and object results with qr/value/url/link keys
+        const qrValue = typeof result === 'string'
+            ? result
+            : typeof result === 'object'
+                ? result.qr || result.value || result.url || result.link
+                : null;
         if (qrValue && typeof qrValue === 'string') {
-            if (result.message) {
+            if (typeof result === 'object' && result.message) {
                 console.log(result.message);
             }
             import('qrcode')
@@ -225,7 +230,7 @@ function formatOutput(result, formatHint) {
                 .catch(() => console.log(`[QR] ${qrValue}`));
             return true;
         }
-        if (result.message) {
+        if (typeof result === 'object' && result.message) {
             console.log(result.message);
             return true;
         }
@@ -1424,6 +1429,12 @@ export async function runMethod(photonName, methodName, args, workingDir) {
         const jsonOutput = args.includes('--json');
         // Check for -y flag (non-interactive mode, for agents/scripts)
         const nonInteractive = args.includes('-y');
+        // Check for --format <type> flag (maps to _meta.format)
+        let cliFormat;
+        const formatIndex = args.indexOf('--format');
+        if (formatIndex !== -1 && args[formatIndex + 1]) {
+            cliFormat = args[formatIndex + 1];
+        }
         // Check for --resume <runId> flag
         let resumeRunId;
         const resumeIndex = args.indexOf('--resume');
@@ -1434,9 +1445,18 @@ export async function runMethod(photonName, methodName, args, workingDir) {
         const filteredArgs = args.filter((arg, i) => arg !== '--json' &&
             arg !== '-y' &&
             arg !== '--resume' &&
-            (resumeIndex === -1 || i !== resumeIndex + 1));
+            arg !== '--format' &&
+            (resumeIndex === -1 || i !== resumeIndex + 1) &&
+            (formatIndex === -1 || i !== formatIndex + 1));
         // Parse arguments
         const parsedArgs = parseCliArgs(filteredArgs, method.params);
+        // Inject _meta from CLI flags (--format maps to _meta.format)
+        if (cliFormat) {
+            parsedArgs._meta = {
+                ...(parsedArgs._meta || {}),
+                format: cliFormat,
+            };
+        }
         // Validate required parameters
         const missing = [];
         for (const param of method.params) {
@@ -1562,6 +1582,11 @@ export async function runMethod(photonName, methodName, args, workingDir) {
         const actualResult = isStateful ? result.result : result;
         // Clear any intermediate render output before displaying final result
         clearRenderZone();
+        // _meta format transformation: pre-formatted text outputs directly
+        if (actualResult && typeof actualResult === 'object' && actualResult._metaFormatted === true) {
+            console.log(actualResult.text);
+            process.exit(0);
+        }
         // Display result
         if (jsonOutput) {
             // For JSON output, include workflow metadata if stateful