@dsh-workbench/shared 1.1.8 → 1.1.10

package/dist/host/flow/check.js

@@ -0,0 +1,179 @@
+function checkValue(value, path, context, add) {
+    if ('$lit' in value)
+        return;
+    if ('$default' in value) {
+        checkValue(value.$default[0], `${path}.$default[0]`, context, add);
+        checkValue(value.$default[1], `${path}.$default[1]`, context, add);
+        return;
+    }
+    if (!('$ref' in value)) {
+        add(path, '不是合法的取值表达式');
+        return;
+    }
+    const ref = value.$ref.trim();
+    if (ref === '') {
+        add(path, '$ref 不能为空');
+        return;
+    }
+    const parts = ref.split('.').filter((part) => part !== '');
+    const root = parts[0];
+    if (root === undefined) {
+        add(path, '$ref 不能为空');
+        return;
+    }
+    if (root === 'in')
+        return;
+    if (root === 'steps') {
+        const id = parts[1];
+        if (id === undefined) {
+            add(path, '$ref 指向 steps 时要写到步骤 id');
+            return;
+        }
+        if (!context.seen.has(id))
+            add(path, `$ref 引用了还没出现的步骤：${id}`);
+        return;
+    }
+    if (root === 'item') {
+        if (!context.item)
+            add(path, '$ref 的 item 只在 forEach 步骤里可用');
+        return;
+    }
+    if (root === 'value') {
+        if (!context.value)
+            add(path, '$ref 的 value 只在 poll.until 里可用');
+        return;
+    }
+    add(path, `$ref 只能从 in / steps / item / value 起头：${ref}`);
+}
+function checkPredicate(predicate, path, context, add) {
+    if ('$eq' in predicate) {
+        checkValue(predicate.$eq[0], `${path}.$eq[0]`, context, add);
+        checkValue(predicate.$eq[1], `${path}.$eq[1]`, context, add);
+        return;
+    }
+    if ('$in' in predicate) {
+        checkValue(predicate.$in[0], `${path}.$in[0]`, context, add);
+        return;
+    }
+    if ('$exists' in predicate) {
+        checkValue(predicate.$exists, `${path}.$exists`, context, add);
+        return;
+    }
+    if ('$and' in predicate) {
+        predicate.$and.forEach((item, index) => {
+            checkPredicate(item, `${path}.$and[${index}]`, context, add);
+        });
+        return;
+    }
+    if ('$not' in predicate) {
+        checkPredicate(predicate.$not, `${path}.$not`, context, add);
+        return;
+    }
+    add(path, '不是合法的谓词');
+}
+function checkFlowAt(flow, actions, prefix, add) {
+    if (flow.id.trim() === '')
+        add(`${prefix}id`, '流程 id 不能为空');
+    if (flow.title.trim() === '')
+        add(`${prefix}title`, '流程标题不能为空');
+    if (flow.steps.length === 0)
+        add(`${prefix}steps`, '至少要有一步');
+    if (flow.target !== undefined) {
+        checkValue(flow.target, `${prefix}target`, { seen: new Set(), item: false, value: false }, add);
+    }
+    if (flow.stopWhen !== undefined) {
+        const all = new Set(flow.steps.map((step) => step.id));
+        checkPredicate(flow.stopWhen, `${prefix}stopWhen`, { seen: all, item: false, value: false }, add);
+    }
+    const seen = new Set();
+    flow.steps.forEach((step, index) => {
+        const at = `${prefix}steps[${index}]`;
+        if (step.id.trim() === '')
+            add(`${at}.id`, '步骤 id 不能为空');
+        if (seen.has(step.id))
+            add(`${at}.id`, `步骤 id 重复：${step.id}`);
+        if ('flow' in step) {
+            if (step.when !== undefined) {
+                checkPredicate(step.when, `${at}.when`, { seen, item: false, value: false }, add);
+            }
+            if (step.with !== undefined) {
+                for (const [key, value] of Object.entries(step.with)) {
+                    checkValue(value, `${at}.with.${key}`, { seen, item: false, value: false }, add);
+                }
+            }
+            checkFlowAt(step.flow, actions, `${at}.flow.`, add);
+            seen.add(step.id);
+            return;
+        }
+        if (step.action.trim() === '')
+            add(`${at}.action`, '动作名不能为空');
+        else if (!actions.has(step.action))
+            add(`${at}.action`, `注册表里没有这个动作：${step.action}`);
+        const item = step.forEach !== undefined;
+        if (step.when !== undefined) {
+            checkPredicate(step.when, `${at}.when`, { seen, item: false, value: false }, add);
+        }
+        if (step.with !== undefined) {
+            for (const [key, value] of Object.entries(step.with)) {
+                checkValue(value, `${at}.with.${key}`, { seen, item, value: false }, add);
+            }
+        }
+        if (step.forEach !== undefined) {
+            checkValue(step.forEach.over, `${at}.forEach.over`, { seen, item: false, value: false }, add);
+            if (step.forEach.as.trim() === '')
+                add(`${at}.forEach.as`, 'forEach.as 不能为空');
+            if (!Number.isInteger(step.forEach.max) || step.forEach.max < 1 || step.forEach.max > 50) {
+                add(`${at}.forEach.max`, 'forEach.max 要在 1..50');
+            }
+        }
+        if (step.retry !== undefined) {
+            if (!Number.isInteger(step.retry.attempts) ||
+                step.retry.attempts < 0 ||
+                step.retry.attempts > 5) {
+                add(`${at}.retry.attempts`, 'retry.attempts 要在 0..5');
+            }
+            if (step.retry.delayMs !== undefined &&
+                (!Number.isInteger(step.retry.delayMs) ||
+                    step.retry.delayMs < 0 ||
+                    step.retry.delayMs > 60_000)) {
+                add(`${at}.retry.delayMs`, 'retry.delayMs 要在 0..60000');
+            }
+        }
+        if (step.poll !== undefined) {
+            if (!Number.isInteger(step.poll.everyMs) ||
+                step.poll.everyMs < 100 ||
+                step.poll.everyMs > 60_000) {
+                add(`${at}.poll.everyMs`, 'poll.everyMs 要在 100..60000');
+            }
+            if (!Number.isInteger(step.poll.maxMs) ||
+                step.poll.maxMs < 0 ||
+                step.poll.maxMs > 1_800_000) {
+                add(`${at}.poll.maxMs`, 'poll.maxMs 要在 0..1800000');
+            }
+            else if (step.poll.maxMs !== 0 && step.poll.maxMs < step.poll.everyMs) {
+                add(`${at}.poll.maxMs`, 'poll.maxMs 不能小于 everyMs');
+            }
+            if (step.poll.onTimeout !== undefined &&
+                step.poll.onTimeout !== 'fail' &&
+                step.poll.onTimeout !== 'continue') {
+                add(`${at}.poll.onTimeout`, 'poll.onTimeout 只能是 fail 或 continue');
+            }
+            checkPredicate(step.poll.until, `${at}.poll.until`, { seen, item, value: true }, add);
+        }
+        seen.add(step.id);
+    });
+}
+/**
+ * 校验一条流程：id / 步骤、动作存在、引用只指前面、重试与轮询在边界内、子流程也照查。
+ * 只做静态检查，不碰平台、不跑动作。
+ * @param flow 流程定义。
+ * @param actions 动作表（只问 `has`）。
+ * @returns 逐条问题；`ok` 为真表示没有。
+ */
+export function checkFlow(flow, actions) {
+    const problems = [];
+    checkFlowAt(flow, actions, '', (path, problem) => {
+        problems.push({ path, problem });
+    });
+    return { ok: problems.length === 0, problems };
+}

package/dist/host/flow/expr.d.ts

@@ -0,0 +1,30 @@
+import type { FlowPredicate, FlowScope, FlowValue } from './types.js';
+/**
+ * 读一个引用路径：`in.env`、`steps.builds.rows.0.id`、`item.id`、`value.status`。
+ * 中间缺一段就给 `undefined`，由调用方决定这是不是错。
+ * @param path 点分路径。
+ * @param scope 求值现场。
+ * @returns 取到的值；路径不成立给 `undefined`。
+ */
+export declare function readRef(path: string, scope: FlowScope): unknown;
+/**
+ * 求一个取值表达式：字面量、引用，或二选一。
+ * @param value 表达式。
+ * @param scope 求值现场。
+ * @returns 求出来的值；引用不成立给 `undefined`。
+ */
+export declare function resolveValue(value: FlowValue, scope: FlowScope): unknown;
+/**
+ * 判一个条件表达式。只认五个操作符；未知形状给 `false`。
+ * @param predicate 条件表达式。
+ * @param scope 求值现场。
+ * @returns 真假。
+ */
+export declare function evalPredicate(predicate: FlowPredicate, scope: FlowScope): boolean;
+/**
+ * 把步骤的 `with` 映射求成动作入参。
+ * @param values 字段到表达式的映射；没给就是空对象。
+ * @param scope 求值现场。
+ * @returns 动作入参。
+ */
+export declare function resolveInput(values: Readonly<Record<string, FlowValue>> | undefined, scope: FlowScope): Readonly<Record<string, unknown>>;

package/dist/host/flow/expr.js

@@ -0,0 +1,99 @@
+import { isDeepStrictEqual } from 'node:util';
+function fieldOf(value, key) {
+    if (Array.isArray(value)) {
+        const index = Number.parseInt(key, 10);
+        return Number.isInteger(index) && index >= 0 ? value[index] : undefined;
+    }
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    return value[key];
+}
+/**
+ * 读一个引用路径：`in.env`、`steps.builds.rows.0.id`、`item.id`、`value.status`。
+ * 中间缺一段就给 `undefined`，由调用方决定这是不是错。
+ * @param path 点分路径。
+ * @param scope 求值现场。
+ * @returns 取到的值；路径不成立给 `undefined`。
+ */
+export function readRef(path, scope) {
+    const parts = path.split('.').filter((part) => part !== '');
+    const [root, ...rest] = parts;
+    if (root === undefined)
+        return undefined;
+    let current;
+    if (root === 'in')
+        current = scope.in;
+    else if (root === 'item')
+        current = scope.item;
+    else if (root === 'value')
+        current = scope.value;
+    else if (root === 'steps') {
+        const id = rest.shift();
+        if (id === undefined)
+            return undefined;
+        current = scope.steps[id];
+    }
+    else
+        return undefined;
+    for (const part of rest)
+        current = fieldOf(current, part);
+    return current;
+}
+/**
+ * 求一个取值表达式：字面量、引用，或二选一。
+ * @param value 表达式。
+ * @param scope 求值现场。
+ * @returns 求出来的值；引用不成立给 `undefined`。
+ */
+export function resolveValue(value, scope) {
+    if ('$lit' in value)
+        return value.$lit;
+    if ('$ref' in value)
+        return readRef(value.$ref, scope);
+    if ('$default' in value) {
+        const first = resolveValue(value.$default[0], scope);
+        return first === undefined ? resolveValue(value.$default[1], scope) : first;
+    }
+    return undefined;
+}
+function sameValue(left, right) {
+    return isDeepStrictEqual(left, right);
+}
+/**
+ * 判一个条件表达式。只认五个操作符；未知形状给 `false`。
+ * @param predicate 条件表达式。
+ * @param scope 求值现场。
+ * @returns 真假。
+ */
+export function evalPredicate(predicate, scope) {
+    if ('$eq' in predicate) {
+        return sameValue(resolveValue(predicate.$eq[0], scope), resolveValue(predicate.$eq[1], scope));
+    }
+    if ('$in' in predicate) {
+        const needle = resolveValue(predicate.$in[0], scope);
+        return predicate.$in[1].some((candidate) => sameValue(candidate, needle));
+    }
+    if ('$exists' in predicate) {
+        const value = resolveValue(predicate.$exists, scope);
+        return value !== undefined && value !== null;
+    }
+    if ('$and' in predicate)
+        return predicate.$and.every((item) => evalPredicate(item, scope));
+    if ('$not' in predicate)
+        return !evalPredicate(predicate.$not, scope);
+    return false;
+}
+/**
+ * 把步骤的 `with` 映射求成动作入参。
+ * @param values 字段到表达式的映射；没给就是空对象。
+ * @param scope 求值现场。
+ * @returns 动作入参。
+ */
+export function resolveInput(values, scope) {
+    if (values === undefined)
+        return {};
+    const input = {};
+    for (const [key, value] of Object.entries(values))
+        input[key] = resolveValue(value, scope);
+    return input;
+}

package/dist/host/flow/kit.d.ts

@@ -0,0 +1,14 @@
+import type { FlowActionRegistry, FlowCheck, FlowDefinition, FlowResult, FlowRunOptions } from './types.js';
+/**
+ * 流程引擎的宿主 kit：模块从 `mount(deps).flow` 拿，不直接 import shared。
+ */
+export interface FlowHost {
+    createActions(): FlowActionRegistry;
+    check(flow: FlowDefinition, actions: Pick<FlowActionRegistry, 'has'>): FlowCheck;
+    run(options: FlowRunOptions): Promise<FlowResult>;
+}
+/**
+ * 建一份无状态的流程宿主 kit。
+ * @returns `createActions` / `check` / `run`。
+ */
+export declare function createFlowHost(): FlowHost;

package/dist/host/flow/kit.js

@@ -0,0 +1,13 @@
+import { checkFlow } from './check.js';
+import { createFlowActionRegistry, runFlow } from './run.js';
+/**
+ * 建一份无状态的流程宿主 kit。
+ * @returns `createActions` / `check` / `run`。
+ */
+export function createFlowHost() {
+    return {
+        createActions: () => createFlowActionRegistry(),
+        check: (flow, actions) => checkFlow(flow, actions),
+        run: (options) => runFlow(options),
+    };
+}

package/dist/host/flow/run.d.ts

@@ -0,0 +1,13 @@
+import type { FlowActionRegistry, FlowResult, FlowRunOptions } from './types.js';
+/**
+ * 建一个内存里的动作注册表；每个流程运行时各有一份，没有模块级状态。
+ * @returns 注册表。
+ */
+export declare function createFlowActionRegistry(): FlowActionRegistry;
+/**
+ * 顺序跑一条流程：条件跳过、重试、轮询、逐项展开、子流程、取消；失败停在具体步骤。
+ * 不碰平台、不落盘；动作怎么实现由注册表决定。
+ * @param options 流程、输入、动作表、取消信号、身份与进度回调。
+ * @returns 成功 / 失败 / 停止；失败带 `failedStep`。
+ */
+export declare function runFlow(options: FlowRunOptions): Promise<FlowResult>;

package/dist/host/flow/run.js

@@ -0,0 +1,287 @@
+import { evalPredicate, resolveInput, resolveValue } from './expr.js';
+class StepFailure extends Error {
+    stepId;
+    constructor(stepId, cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.name = 'StepFailure';
+        this.stepId = stepId;
+        this.cause = cause;
+    }
+}
+function abortError() {
+    const error = new Error('流程已停止');
+    error.name = 'AbortError';
+    return error;
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve();
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function targetOf(flow, scope) {
+    if (flow.target === undefined)
+        return flow.id;
+    const value = resolveValue(flow.target, scope);
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : flow.id;
+}
+function stopped(steps, target) {
+    return { status: 'stopped', target, steps };
+}
+/**
+ * 建一个内存里的动作注册表；每个流程运行时各有一份，没有模块级状态。
+ * @returns 注册表。
+ */
+export function createFlowActionRegistry() {
+    const entries = new Map();
+    return {
+        register(name, action, meta) {
+            const trimmed = name.trim();
+            if (trimmed === '')
+                throw new Error('动作名不能为空');
+            entries.set(trimmed, { name: trimmed, action, meta: meta ?? {} });
+        },
+        get(name) {
+            return entries.get(name);
+        },
+        has(name) {
+            return entries.has(name);
+        },
+        list() {
+            return [...entries.values()];
+        },
+    };
+}
+async function callWithRetry(action, input, context, retry, sleep, signal, onAttempt) {
+    const attempts = Math.max(0, Math.min(5, Math.trunc(retry?.attempts ?? 0)));
+    const delayMs = Math.max(0, Math.min(60_000, Math.trunc(retry?.delayMs ?? 0)));
+    let last;
+    for (let attempt = 1; attempt <= attempts + 1; attempt += 1) {
+        if (signal.aborted)
+            throw abortError();
+        onAttempt?.(attempt);
+        try {
+            return await action(input, context);
+        }
+        catch (error) {
+            last = error;
+            if (signal.aborted)
+                throw abortError();
+            if (attempt > attempts)
+                break;
+            if (delayMs > 0)
+                await sleep(delayMs, signal);
+        }
+    }
+    throw last;
+}
+async function runOneInner(options) {
+    const { step, title, stepId, scope, actions, signal, runId, workspace, sleep, now, emit } = options;
+    const entry = actions.get(step.action);
+    if (entry === undefined)
+        throw new Error(`注册表里没有这个动作：${step.action}`);
+    const input = resolveInput(step.with, scope);
+    const context = {
+        signal,
+        runId,
+        workspace,
+        stepId,
+        log: (text) => {
+            emit({ stepId, title, status: 'running', message: text });
+        },
+        login: (url) => {
+            emit({ stepId, title, status: 'needs-login', loginUrl: url });
+        },
+    };
+    if (step.poll !== undefined) {
+        const everyMs = Math.max(100, Math.min(60_000, Math.trunc(step.poll.everyMs)));
+        const rawMax = Math.trunc(step.poll.maxMs);
+        const maxMs = rawMax === 0 ? 0 : Math.max(everyMs, Math.min(1_800_000, rawMax));
+        const startedAt = now();
+        let pollAttempt = 0;
+        for (;;) {
+            if (signal.aborted)
+                throw abortError();
+            pollAttempt += 1;
+            emit({
+                stepId,
+                title,
+                status: 'running',
+                attempt: pollAttempt,
+                message: `第 ${pollAttempt} 次`,
+            });
+            const value = await callWithRetry(entry.action, input, context, step.retry, sleep, signal);
+            if (evalPredicate(step.poll.until, { ...scope, value }))
+                return value;
+            if (maxMs > 0 && now() - startedAt >= maxMs) {
+                if (step.poll.onTimeout === 'continue')
+                    return undefined;
+                throw new Error(`步骤 ${step.id} 轮询超时（${maxMs}ms）`);
+            }
+            await sleep(everyMs, signal);
+        }
+    }
+    return callWithRetry(entry.action, input, context, step.retry, sleep, signal, (attempt) => {
+        emit({ stepId, title, status: 'running', attempt });
+    });
+}
+async function runOne(options) {
+    try {
+        return await runOneInner(options);
+    }
+    catch (error) {
+        if (error instanceof StepFailure || isAbortError(error))
+            throw error;
+        throw new StepFailure(options.stepId, error);
+    }
+}
+/**
+ * 顺序跑一条流程：条件跳过、重试、轮询、逐项展开、子流程、取消；失败停在具体步骤。
+ * 不碰平台、不落盘；动作怎么实现由注册表决定。
+ * @param options 流程、输入、动作表、取消信号、身份与进度回调。
+ * @returns 成功 / 失败 / 停止；失败带 `failedStep`。
+ */
+export async function runFlow(options) {
+    const { flow, input, actions, signal, runId, workspace, onStep } = options;
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? (() => Date.now());
+    const steps = {};
+    const emit = (event) => {
+        try {
+            onStep(event);
+        }
+        catch {
+        }
+    };
+    const target = targetOf(flow, { in: input, steps });
+    const shouldStop = () => flow.stopWhen !== undefined && evalPredicate(flow.stopWhen, { in: input, steps });
+    if (shouldStop())
+        return { status: 'ok', target, steps };
+    for (const step of flow.steps) {
+        if (signal.aborted)
+            return stopped(steps, target);
+        const title = step.title ?? step.id;
+        try {
+            if (shouldStop())
+                return { status: 'ok', target, steps };
+            if (step.when !== undefined && !evalPredicate(step.when, { in: input, steps })) {
+                emit({ stepId: step.id, title, status: 'skipped' });
+                if (shouldStop())
+                    return { status: 'ok', target, steps };
+                continue;
+            }
+            if ('flow' in step) {
+                emit({ stepId: step.id, title, status: 'running' });
+                const subInput = resolveInput(step.with, { in: input, steps });
+                const nested = await runFlow({
+                    flow: step.flow,
+                    input: subInput,
+                    actions,
+                    signal,
+                    runId: `${runId}/${step.id}`,
+                    workspace,
+                    onStep: (event) => {
+                        emit({
+                            ...event,
+                            stepId: `${step.id}.${event.stepId}`,
+                            title: `${title} / ${event.title}`,
+                        });
+                    },
+                    sleep,
+                    now,
+                });
+                if (nested.status === 'failed') {
+                    const failed = nested.failedStep === undefined ? step.id : `${step.id}.${nested.failedStep}`;
+                    throw new StepFailure(failed, nested.error ?? new Error(`子流程失败在 ${failed}`));
+                }
+                steps[step.id] = nested.steps;
+                if (nested.status === 'stopped')
+                    return stopped(steps, target);
+                emit({ stepId: step.id, title, status: 'ok' });
+                if (shouldStop())
+                    return { status: 'ok', target, steps };
+                continue;
+            }
+            if (step.forEach !== undefined) {
+                const over = resolveValue(step.forEach.over, { in: input, steps });
+                if (!Array.isArray(over)) {
+                    throw new Error(`步骤 ${step.id} 的 forEach.over 不是数组`);
+                }
+                const max = Math.max(1, Math.min(50, Math.trunc(step.forEach.max)));
+                if (over.length > max) {
+                    throw new Error(`步骤 ${step.id} 的 forEach 有 ${over.length} 项，超过上限 ${max}`);
+                }
+                const output = [];
+                for (const [index, item] of over.entries()) {
+                    if (signal.aborted)
+                        return stopped(steps, target);
+                    output.push(await runOne({
+                        step,
+                        title,
+                        stepId: `${step.id}[${index}]`,
+                        scope: { in: input, steps, item },
+                        actions,
+                        signal,
+                        runId,
+                        workspace,
+                        sleep,
+                        now,
+                        emit,
+                    }));
+                }
+                steps[step.id] = output;
+                emit({ stepId: step.id, title, status: 'ok' });
+                if (shouldStop())
+                    return { status: 'ok', target, steps };
+                continue;
+            }
+            steps[step.id] = await runOne({
+                step,
+                title,
+                stepId: step.id,
+                scope: { in: input, steps },
+                actions,
+                signal,
+                runId,
+                workspace,
+                sleep,
+                now,
+                emit,
+            });
+            emit({ stepId: step.id, title, status: 'ok' });
+            if (shouldStop())
+                return { status: 'ok', target, steps };
+        }
+        catch (error) {
+            if (signal.aborted || isAbortError(error))
+                return stopped(steps, target);
+            if (error instanceof StepFailure) {
+                emit({ stepId: error.stepId, title, status: 'failed', message: error.message });
+                return {
+                    status: 'failed',
+                    target,
+                    steps,
+                    failedStep: error.stepId,
+                    error: error.cause ?? error,
+                };
+            }
+            emit({ stepId: step.id, title, status: 'failed', message: String(error) });
+            return { status: 'failed', target, steps, failedStep: step.id, error };
+        }
+    }
+    return { status: 'ok', target, steps };
+}