@swell/cli 2.9.2 → 2.9.3

package/dist/lib/function-source-analysis.js

@@ -0,0 +1,311 @@
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const ts = require('typescript');
+const ORDINARY_TRIGGER_KEYS = ['route', 'model', 'cron'];
+const WORKFLOW_FORBIDDEN_KEYS = [
+    'route',
+    'model',
+    'cron',
+    'extension',
+    'timeout',
+];
+export async function analyzeFunctionSource(filePath) {
+    const sourceText = await fs.promises.readFile(filePath, 'utf8');
+    return analyzeFunctionSourceText(sourceText, filePath);
+}
+export function analyzeFunctionSourceText(sourceText, filePath = 'function.ts') {
+    const sourceFile = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, filePath.endsWith('.tsx') || filePath.endsWith('.ts')
+        ? ts.ScriptKind.TS
+        : ts.ScriptKind.JS);
+    const diagnostics = [];
+    const parseDiagnostics = sourceFile
+        .parseDiagnostics ?? [];
+    diagnostics.push(...parseDiagnostics.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')));
+    const configExport = findConfigExport(sourceFile);
+    let config;
+    let kind = 'unknown';
+    if (configExport?.initializer) {
+        const initializer = unwrapExpression(configExport.initializer);
+        const kindValue = readConfigKind(initializer);
+        if (kindValue === 'dynamic') {
+            diagnostics.push('config.kind must be a static string literal.');
+        }
+        const evalResult = evaluateStatic(initializer);
+        if (evalResult.errors.length > 0) {
+            if (kindValue === 'workflow') {
+                diagnostics.push(...evalResult.errors);
+            }
+        }
+        else if (isRecord(evalResult.value)) {
+            config = evalResult.value;
+        }
+        const configKind = config?.kind ?? kindValue;
+        if (configKind === undefined) {
+            kind = config ? 'function' : 'unknown';
+        }
+        else if (configKind === 'function' || configKind === 'workflow') {
+            kind = configKind;
+        }
+        else if (typeof configKind === 'string') {
+            diagnostics.push(`Unsupported config.kind "${configKind}".`);
+        }
+    }
+    const analysis = {
+        config,
+        kind,
+        diagnostics,
+    };
+    if (kind === 'workflow') {
+        analysis.defaultExport = validateWorkflowDefaultExport(sourceFile);
+        analysis.diagnostics.push(...validateWorkflowConfig(config));
+        if (!analysis.defaultExport.validWorkflowClass) {
+            analysis.diagnostics.push(analysis.defaultExport.reason ||
+                'Workflow default export must be a same-file class with a run method.');
+        }
+    }
+    return analysis;
+}
+export function getFunctionTriggers(config) {
+    return ORDINARY_TRIGGER_KEYS.filter((key) => Boolean(config[key]));
+}
+export function hasKindDiagnostic(analysis) {
+    return analysis.diagnostics.some((diagnostic) => diagnostic === 'config.kind must be a static string literal.' ||
+        diagnostic.startsWith('Unsupported config.kind '));
+}
+export function workflowStaticConfigError() {
+    return new Error('Workflow configs must export a static object literal so the CLI can choose the workflow bundling path before compiling.');
+}
+function findConfigExport(sourceFile) {
+    const localVariables = new Map();
+    let exportedConfigLocalName;
+    let directExport;
+    for (const statement of sourceFile.statements) {
+        if (ts.isVariableStatement(statement)) {
+            const isExported = hasModifier(statement, ts.SyntaxKind.ExportKeyword);
+            for (const declaration of statement.declarationList.declarations) {
+                if (!ts.isIdentifier(declaration.name)) {
+                    continue;
+                }
+                localVariables.set(declaration.name.text, declaration.initializer);
+                if (isExported && declaration.name.text === 'config') {
+                    directExport = { initializer: declaration.initializer };
+                }
+            }
+        }
+        if (ts.isExportDeclaration(statement) &&
+            statement.exportClause &&
+            ts.isNamedExports(statement.exportClause)) {
+            for (const element of statement.exportClause.elements) {
+                const exportedName = element.name.text;
+                if (exportedName === 'config') {
+                    exportedConfigLocalName = (element.propertyName || element.name).text;
+                }
+            }
+        }
+    }
+    if (directExport) {
+        return directExport;
+    }
+    if (exportedConfigLocalName) {
+        return { initializer: localVariables.get(exportedConfigLocalName) };
+    }
+}
+function readConfigKind(expression) {
+    const unwrapped = unwrapExpression(expression);
+    if (!ts.isObjectLiteralExpression(unwrapped)) {
+        return undefined;
+    }
+    for (const property of unwrapped.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            continue;
+        }
+        const name = staticPropertyName(property.name);
+        if (name !== 'kind') {
+            continue;
+        }
+        const value = unwrapExpression(property.initializer);
+        return ts.isStringLiteral(value) ? value.text : 'dynamic';
+    }
+}
+function evaluateStatic(expression) {
+    const unwrapped = unwrapExpression(expression);
+    if (ts.isObjectLiteralExpression(unwrapped)) {
+        const value = {};
+        const errors = [];
+        for (const property of unwrapped.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                errors.push('config must not use object spreads.');
+                continue;
+            }
+            if (!ts.isPropertyAssignment(property)) {
+                errors.push('config must contain only static property assignments.');
+                continue;
+            }
+            const name = staticPropertyName(property.name);
+            if (!name) {
+                errors.push('config must not use computed property keys.');
+                continue;
+            }
+            const result = evaluateStatic(property.initializer);
+            if (result.errors.length > 0) {
+                errors.push(...result.errors.map((error) => `${name}: ${error}`));
+                continue;
+            }
+            value[name] = result.value;
+        }
+        return { errors, value };
+    }
+    if (ts.isArrayLiteralExpression(unwrapped)) {
+        const value = [];
+        const errors = [];
+        for (const element of unwrapped.elements) {
+            if (ts.isSpreadElement(element)) {
+                errors.push('arrays must not use spreads.');
+                continue;
+            }
+            const result = evaluateStatic(element);
+            if (result.errors.length > 0) {
+                errors.push(...result.errors);
+                continue;
+            }
+            value.push(result.value);
+        }
+        return { errors, value };
+    }
+    if (ts.isStringLiteral(unwrapped) ||
+        ts.isNoSubstitutionTemplateLiteral(unwrapped)) {
+        return { errors: [], value: unwrapped.text };
+    }
+    if (ts.isNumericLiteral(unwrapped)) {
+        return { errors: [], value: Number(unwrapped.text) };
+    }
+    if (unwrapped.kind === ts.SyntaxKind.TrueKeyword) {
+        return { errors: [], value: true };
+    }
+    if (unwrapped.kind === ts.SyntaxKind.FalseKeyword) {
+        return { errors: [], value: false };
+    }
+    if (unwrapped.kind === ts.SyntaxKind.NullKeyword) {
+        return { errors: [], value: null };
+    }
+    if (ts.isPrefixUnaryExpression(unwrapped) &&
+        ts.isNumericLiteral(unwrapped.operand) &&
+        (unwrapped.operator === ts.SyntaxKind.MinusToken ||
+            unwrapped.operator === ts.SyntaxKind.PlusToken)) {
+        const value = Number(unwrapped.operand.text);
+        return {
+            errors: [],
+            value: unwrapped.operator === ts.SyntaxKind.MinusToken ? -value : value,
+        };
+    }
+    return { errors: ['value must be static JSON-like metadata.'] };
+}
+function validateWorkflowConfig(config) {
+    if (!config) {
+        return ['Workflow config must be a static object literal.'];
+    }
+    const diagnostics = [];
+    for (const key of WORKFLOW_FORBIDDEN_KEYS) {
+        if (key in config) {
+            diagnostics.push(`Workflow config must not specify ${key}.`);
+        }
+    }
+    return diagnostics;
+}
+function validateWorkflowDefaultExport(sourceFile) {
+    const classes = new Map();
+    const defaultExports = [];
+    for (const statement of sourceFile.statements) {
+        if (ts.isClassDeclaration(statement) && statement.name) {
+            classes.set(statement.name.text, statement);
+        }
+        if (ts.isClassDeclaration(statement) &&
+            hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+            defaultExports.push(statement);
+        }
+        else if (ts.isFunctionDeclaration(statement) &&
+            hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+            defaultExports.push(statement);
+        }
+        else if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+            defaultExports.push(statement);
+        }
+        else if (ts.isExportDeclaration(statement) &&
+            statement.exportClause &&
+            ts.isNamedExports(statement.exportClause)) {
+            for (const element of statement.exportClause.elements) {
+                if (element.name.text === 'default') {
+                    defaultExports.push(statement);
+                }
+            }
+        }
+    }
+    if (defaultExports.length !== 1) {
+        return {
+            validWorkflowClass: false,
+            reason: 'Workflow files must have exactly one default export.',
+        };
+    }
+    const defaultExport = defaultExports[0];
+    let workflowClass;
+    if (ts.isClassDeclaration(defaultExport)) {
+        workflowClass = defaultExport;
+    }
+    else if (ts.isExportAssignment(defaultExport)) {
+        const expression = unwrapExpression(defaultExport.expression);
+        if (ts.isIdentifier(expression)) {
+            workflowClass = classes.get(expression.text);
+        }
+    }
+    if (!workflowClass) {
+        return {
+            validWorkflowClass: false,
+            reason: 'Workflow default export must resolve to a class declared in the same file.',
+        };
+    }
+    if (!hasInstanceRunMethod(workflowClass)) {
+        return {
+            validWorkflowClass: false,
+            name: workflowClass.name?.text,
+            reason: 'Workflow default export class must define an instance run method.',
+        };
+    }
+    return {
+        validWorkflowClass: true,
+        name: workflowClass.name?.text,
+    };
+}
+function hasInstanceRunMethod(classDeclaration) {
+    return classDeclaration.members.some((member) => {
+        if (!ts.isMethodDeclaration(member) ||
+            hasModifier(member, ts.SyntaxKind.StaticKeyword)) {
+            return false;
+        }
+        return staticPropertyName(member.name) === 'run';
+    });
+}
+function unwrapExpression(expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isTypeAssertionExpression(current) ||
+        ts.isSatisfiesExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+function staticPropertyName(name) {
+    if (ts.isIdentifier(name) ||
+        ts.isStringLiteral(name) ||
+        ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+}
+function hasModifier(node, kind) {
+    return Boolean(ts.canHaveModifiers(node) &&
+        ts.getModifiers(node)?.some((modifier) => modifier.kind === kind));
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}

package/dist/lib/logs/index.d.ts

@@ -19,5 +19,7 @@ export declare class LoggedItem implements LogItem {
     type: string;
     constructor(log: any);
     private prepareRequest;
+    private prepareRequestWorkflow;
     private prepareRequestFunction;
+    private prepareConsoleLines;
 }

package/dist/lib/logs/index.js

@@ -42,6 +42,10 @@ export class LoggedItem {
                 request = this.prepareRequestFunction(logMessage);
                 break;
             }
+            case 'workflow': {
+                request = this.prepareRequestWorkflow(logMessage);
+                break;
+            }
             case 'webhook': {
                 const { event } = logMessage;
                 request = `Webhook ${event.type} > ${style.logMethod('POST')} ${url}`;
@@ -61,10 +65,32 @@ export class LoggedItem {
         }
         return request;
     }
+    prepareRequestWorkflow(logMessage) {
+        const { error, logs, phase, status, step_name: stepName, workflow_instance_id: instanceId, workflow_name: workflowName, } = logMessage;
+        const parts = ['Workflow', workflowName || '-', instanceId || '-'];
+        if (phase) {
+            parts.push(phase);
+        }
+        if (stepName) {
+            parts.push(`"${stepName}"`);
+        }
+        if (status) {
+            parts.push(String(status));
+        }
+        if (error) {
+            parts.push(style.funcError(String(error)));
+        }
+        const logLines = this.prepareConsoleLines(logs);
+        return `${parts.join(' ')}${logLines ? `\n${logLines}` : ''}`;
+    }
     prepareRequestFunction(logMessage) {
         const { event } = logMessage;
         const { logs, method, name } = logMessage;
-        const logLines = logs
+        const logLines = this.prepareConsoleLines(logs);
+        return `Function ${event ? `${event.hook ? `${event.hook}:` : ''}${event.type} >` : ''} ${style.logMethod(method.toUpperCase())} /${name} ${logLines ? `\n${logLines}` : ''}`;
+    }
+    prepareConsoleLines(logs) {
+        return logs
             ?.map((l) => {
             const line = l.line?.join('\n');
             switch (l.level) {
@@ -83,6 +109,5 @@ export class LoggedItem {
             }
         })
             .join('\n');
-        return `Function ${event ? `${event.hook ? `${event.hook}:` : ''}${event.type} >` : ''} ${style.logMethod(method.toUpperCase())} /${name} ${logLines ? `\n${logLines}` : ''}`;
     }
 }

package/dist/lib/swell-function-wrapper.d.ts

@@ -48,6 +48,11 @@ declare function executeModuleHandler(req: SwellRequest, context: Event): Promis
  * @returns {boolean}
  */
 declare function isOrdinaryObject(val: any): boolean;
+declare function validateWorkflowParams(params: any): any;
+declare function validateWorkflowParamValue(value: any, seen?: WeakSet<object>): void;
+declare function validateWorkflowParamArray(value: any, seen: any): void;
+declare function validateWorkflowParamObject(value: any, seen: any): void;
+declare function createWorkflowParamsError(code: any, message: any): SwellError;
 declare namespace originalConsole {
     let log: {
         (...data: any[]): void;
@@ -70,6 +75,7 @@ declare namespace originalConsole {
         (message?: any, ...optionalParams: any[]): void;
     };
 }
+declare const WORKFLOW_PARAMS_MAX_BYTES: number;
 /**
  * Class representing a Swell request.
  */
@@ -121,6 +127,9 @@ declare class SwellAPI {
     baseUrl: any;
     basicAuth: string;
     context: any;
+    workflows: {
+        create: (name: any, params: any) => Promise<any>;
+    };
     toBase64(inputString: any): string;
     stringifyQuery(queryObject: any, prefix: any): any;
     makeRequest(method: any, url: any, data: any): Promise<any>;
@@ -129,6 +138,7 @@ declare class SwellAPI {
     post(url: any, data: any): Promise<any>;
     delete(url: any, data: any): Promise<any>;
     settings(id?: any): Promise<any>;
+    createWorkflow(name: any, params: any): Promise<any>;
     /**
      * Atomic multi-op write. Throws SwellError with a stable `error.code`
      * (transaction_conflict | transaction_timeout | transaction_throttled

package/dist/lib/swell-function-wrapper.js

@@ -6,6 +6,7 @@ const originalConsole = {
     warn: console.warn,
     error: console.error,
 };
+const WORKFLOW_PARAMS_MAX_BYTES = 128 * 1024;
 addEventListener('fetch', (event) => {
     event.respondWith(request(event.request, event.env, event));
 });
@@ -240,6 +241,9 @@ class SwellAPI {
         this.baseUrl = req.apiHost;
         this.basicAuth = `${req.storeId}:${req.accessToken}`;
         this.context = context;
+        this.workflows = {
+            create: (name, params) => this.createWorkflow(name, params),
+        };
     }
     toBase64(inputString) {
         const utf8Bytes = new TextEncoder().encode(inputString);
@@ -324,6 +328,15 @@ class SwellAPI {
     async settings(id = this.request.appId) {
         return this.makeRequest('GET', `/settings/${id}`);
     }
+    async createWorkflow(name, params) {
+        const data = {
+            workflow_name: name,
+        };
+        if (params !== undefined) {
+            data.params = validateWorkflowParams(params);
+        }
+        return this.makeRequest('POST', '/:workflows/instances', data);
+    }
     /**
      * Atomic multi-op write. Throws SwellError with a stable `error.code`
      * (transaction_conflict | transaction_timeout | transaction_throttled
@@ -499,3 +512,89 @@ function isOrdinaryObject(val) {
         val !== null &&
         Object.getPrototypeOf(val) === Object.prototype);
 }
+function validateWorkflowParams(params) {
+    validateWorkflowParamValue(params);
+    const serialized = JSON.stringify(params);
+    const size = new TextEncoder().encode(serialized).length;
+    if (size > WORKFLOW_PARAMS_MAX_BYTES) {
+        throw createWorkflowParamsError('workflow_params_too_large', 'Workflow params are too large; pass identifiers and re-fetch data inside the workflow');
+    }
+    return params;
+}
+function validateWorkflowParamValue(value, seen = new WeakSet()) {
+    if (value === null) {
+        return;
+    }
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return;
+        case 'number':
+            if (Number.isFinite(value)) {
+                return;
+            }
+            break;
+        case 'object': {
+            if (Array.isArray(value)) {
+                validateWorkflowParamArray(value, seen);
+                return;
+            }
+            const prototype = Object.getPrototypeOf(value);
+            if (prototype !== Object.prototype && prototype !== null) {
+                break;
+            }
+            validateWorkflowParamObject(value, seen);
+            return;
+        }
+        default:
+            break;
+    }
+    throw createWorkflowParamsError('workflow_params_unserializable', 'Workflow params must be JSON-safe values');
+}
+function validateWorkflowParamArray(value, seen) {
+    if (seen.has(value)) {
+        throw createWorkflowParamsError('workflow_params_unserializable', 'Workflow params must be JSON-safe values');
+    }
+    seen.add(value);
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        throw createWorkflowParamsError('workflow_params_unserializable', 'Workflow params must be JSON-safe values');
+    }
+    for (const key of Object.keys(value)) {
+        if (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length) {
+            throw createWorkflowParamsError('workflow_params_unserializable', 'Workflow params must be JSON-safe values');
+        }
+    }
+    for (let i = 0; i < value.length; i += 1) {
+        if (!Object.prototype.hasOwnProperty.call(value, i)) {
+            throw createWorkflowParamsError('workflow_params_unserializable', 'Workflow params must be JSON-safe values');
+        }
+        validateWorkflowParamValue(value[i], seen);
+    }
+    seen.delete(value);
+}
+function validateWorkflowParamObject(value, seen) {
+    if (seen.has(value)) {
+        throw createWorkflowParamsError('workflow_params_unserializable', 'Workflow params must be JSON-safe values');
+    }
+    seen.add(value);
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        throw createWorkflowParamsError('workflow_params_unserializable', 'Workflow params must be JSON-safe values');
+    }
+    for (const item of Object.values(value)) {
+        validateWorkflowParamValue(item, seen);
+    }
+    seen.delete(value);
+}
+function createWorkflowParamsError(code, message) {
+    return new SwellError({
+        error: {
+            code,
+            message,
+            status: 400,
+            retryable: false,
+        },
+    }, {
+        code,
+        status: 400,
+    });
+}

package/dist/lib/workflows/operations.d.ts

@@ -0,0 +1,68 @@
+import Api from '../api.js';
+import { InspectScope } from '../apps/inspect-scope.js';
+export declare const WORKFLOW_STATUSES: string[];
+export declare const WORKFLOW_INSTANCE_ID_PATTERN: RegExp;
+export interface WorkflowManifestRecord {
+    app_id?: string;
+    enabled?: boolean;
+    id?: string;
+    kind?: string;
+    name?: string;
+    summary?: WorkflowSummary;
+    trigger?: string;
+    workflow_name?: string;
+}
+export interface WorkflowSummary {
+    active_instances?: number;
+    completed_recent?: number;
+    failed_instances?: number;
+    last_failure?: WorkflowFailure;
+    last_create_failure?: WorkflowFailure;
+    last_runtime_failure?: WorkflowFailure;
+    terminated_recent?: number;
+}
+export interface WorkflowFailure {
+    code?: string;
+    date?: string;
+    message?: string;
+}
+export interface WorkflowRunRecord {
+    app_id?: string;
+    cf_instance_id?: string;
+    date_completed?: string;
+    date_created?: string;
+    date_failed?: string;
+    date_started?: string;
+    date_terminated?: string;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+    failure_phase?: string;
+    status?: string;
+    trigger?: string;
+    workflow_id?: string;
+    workflow_instance_id?: string;
+    workflow_name?: string;
+}
+export interface WorkflowOperationRef {
+    appId: string;
+    appSlug?: string;
+    query: {
+        workflow_id?: string;
+        workflow_name?: string;
+    };
+}
+export declare function resolveWorkflowOperationRef(api: Api, workflow: string, flags: {
+    app?: string;
+}): Promise<WorkflowOperationRef>;
+export declare function resolveWorkflowScope(api: Api, flags: {
+    app?: string;
+}): Promise<InspectScope>;
+export declare function isWorkflowInstanceIdentifier(value: string): boolean;
+export declare function workflowDisplayName(record: WorkflowManifestRecord): string;
+export declare function workflowListMeta(record: WorkflowManifestRecord): string;
+export declare function workflowRunDate(run: WorkflowRunRecord): string | undefined;
+export declare function workflowRunMeta(run: WorkflowRunRecord): string;
+export declare function formatWorkflowRelativeTime(value: string, now?: number): string;
+export declare function redactWorkflowPayload(value: unknown): unknown;