@dsh-workbench/shared 1.1.8 → 1.1.10

package/src/host/flow/__tests__/run.test.ts

@@ -0,0 +1,301 @@
+import { describe, expect, it } from 'vitest';
+import { createFlowActionRegistry, runFlow } from '../run.js';
+import type {
+  FlowAction,
+  FlowActionRegistry,
+  FlowDefinition,
+  FlowResult,
+  FlowStepEvent,
+  FlowValue,
+} from '../types.js';
+
+const ref = (path: string): FlowValue => ({ $ref: path });
+const lit = (value: unknown): FlowValue => ({ $lit: value });
+
+function actionsOf(entries: Readonly<Record<string, FlowAction>>): FlowActionRegistry {
+  const registry = createFlowActionRegistry();
+  for (const [name, action] of Object.entries(entries)) registry.register(name, action);
+  return registry;
+}
+
+interface RunExtra {
+  readonly signal?: AbortSignal | undefined;
+  readonly sleep?: ((ms: number, signal: AbortSignal) => Promise<void>) | undefined;
+  readonly now?: (() => number) | undefined;
+}
+
+async function runFlowWith(
+  flow: FlowDefinition,
+  actions: FlowActionRegistry,
+  input: unknown = {},
+  extra: RunExtra = {},
+): Promise<{ result: FlowResult; events: FlowStepEvent[] }> {
+  const events: FlowStepEvent[] = [];
+  const result = await runFlow({
+    flow,
+    input,
+    actions,
+    signal: extra.signal ?? new AbortController().signal,
+    runId: 'run-1',
+    workspace: '/w/a',
+    onStep: (event) => events.push(event),
+    ...(extra.sleep === undefined ? {} : { sleep: extra.sleep }),
+    ...(extra.now === undefined ? {} : { now: extra.now }),
+  });
+  return { result, events };
+}
+
+describe('runFlow', () => {
+  it('顺序跑三步，with 从前面步骤取值', async () => {
+    const seen: unknown[] = [];
+    const actions = actionsOf({
+      read: async () => ({ rows: [1, 2] }),
+      write: async (input) => {
+        seen.push(input);
+        return { count: 2 };
+      },
+      summary: async (input) => {
+        seen.push(input);
+        return 'ok';
+      },
+    });
+
+    const { result, events } = await runFlowWith(
+      {
+        id: 'check',
+        title: '检查',
+        target: ref('in.env'),
+        steps: [
+          { id: 'read', action: 'read' },
+          { id: 'write', action: 'write', with: { rows: ref('steps.read.rows') } },
+          { id: 'summary', action: 'summary', with: { count: ref('steps.write.count') } },
+        ],
+      },
+      actions,
+      { env: 'test' },
+    );
+
+    expect(result.status).toBe('ok');
+    expect(result.target).toBe('test');
+    expect(result.steps).toEqual({
+      read: { rows: [1, 2] },
+      write: { count: 2 },
+      summary: 'ok',
+    });
+    expect(seen).toEqual([{ rows: [1, 2] }, { count: 2 }]);
+    expect(events.filter((event) => event.status === 'ok').map((event) => event.stepId)).toEqual([
+      'read',
+      'write',
+      'summary',
+    ]);
+  });
+
+  it('重试：前两次抛错，第三次成功', async () => {
+    let calls = 0;
+    const actions = actionsOf({
+      flaky: async () => {
+        calls += 1;
+        if (calls < 3) throw new Error('boom');
+        return 'ok';
+      },
+    });
+
+    const { result, events } = await runFlowWith(
+      {
+        id: 'retry',
+        title: '重试',
+        steps: [{ id: 'flaky', action: 'flaky', retry: { attempts: 2, delayMs: 10 } }],
+      },
+      actions,
+      {},
+      { sleep: async () => {} },
+    );
+
+    expect(result.status).toBe('ok');
+    expect(calls).toBe(3);
+    expect(
+      events.filter((event) => event.status === 'running').map((event) => event.attempt),
+    ).toEqual([1, 2, 3]);
+  });
+
+  it('轮询：直到 until 为真', async () => {
+    let calls = 0;
+    let clock = 0;
+    const actions = actionsOf({
+      job: async () => {
+        calls += 1;
+        return calls < 3 ? { status: 'pending' } : { status: 'done' };
+      },
+    });
+
+    const { result, events } = await runFlowWith(
+      {
+        id: 'poll',
+        title: '轮询',
+        steps: [
+          {
+            id: 'job',
+            action: 'job',
+            poll: {
+              everyMs: 100,
+              maxMs: 1000,
+              until: { $eq: [ref('value.status'), lit('done')] },
+            },
+          },
+        ],
+      },
+      actions,
+      {},
+      {
+        now: () => clock,
+        sleep: async (ms) => {
+          clock += ms;
+        },
+      },
+    );
+
+    expect(result.status).toBe('ok');
+    expect(calls).toBe(3);
+    expect(events.filter((event) => event.status === 'running')).toHaveLength(3);
+  });
+
+  it('轮询超时判失败，并指出步骤', async () => {
+    let clock = 0;
+    const actions = actionsOf({ job: async () => ({ status: 'pending' }) });
+
+    const { result } = await runFlowWith(
+      {
+        id: 'timeout',
+        title: '超时',
+        steps: [
+          {
+            id: 'job',
+            action: 'job',
+            poll: {
+              everyMs: 100,
+              maxMs: 250,
+              until: { $eq: [ref('value.status'), lit('done')] },
+            },
+          },
+        ],
+      },
+      actions,
+      {},
+      {
+        now: () => clock,
+        sleep: async (ms) => {
+          clock += ms;
+        },
+      },
+    );
+
+    expect(result.status).toBe('failed');
+    expect(result.failedStep).toBe('job');
+    expect(result.error).toBeInstanceOf(Error);
+  });
+
+  it('取消：结果是 stopped，后面的步骤不跑', async () => {
+    const controller = new AbortController();
+    const actions = actionsOf({
+      slow: async (_input, context) => {
+        await new Promise<void>((resolve) => {
+          if (context.signal.aborted) {
+            resolve();
+            return;
+          }
+          context.signal.addEventListener('abort', () => resolve(), { once: true });
+        });
+        throw new Error('aborted');
+      },
+      after: async () => 'no',
+    });
+
+    const running = runFlowWith(
+      {
+        id: 'cancel',
+        title: '取消',
+        steps: [
+          { id: 'slow', action: 'slow' },
+          { id: 'after', action: 'after' },
+        ],
+      },
+      actions,
+      {},
+      { signal: controller.signal },
+    );
+    await Promise.resolve();
+    controller.abort();
+    const { result, events } = await running;
+
+    expect(result.status).toBe('stopped');
+    expect(result.steps).toEqual({});
+    expect(events.some((event) => event.stepId === 'after')).toBe(false);
+  });
+
+  it('when 为假：跳过，不调动作', async () => {
+    let calls = 0;
+    const actions = actionsOf({
+      only: async () => {
+        calls += 1;
+        return 'ok';
+      },
+    });
+
+    const { result, events } = await runFlowWith(
+      {
+        id: 'skip',
+        title: '跳过',
+        steps: [{ id: 'only', action: 'only', when: { $eq: [ref('in.env'), lit('prod')] } }],
+      },
+      actions,
+      { env: 'test' },
+    );
+
+    expect(result.status).toBe('ok');
+    expect(result.steps).toEqual({});
+    expect(calls).toBe(0);
+    expect(events).toEqual([{ stepId: 'only', title: 'only', status: 'skipped' }]);
+  });
+
+  it('forEach：逐项串行，with 能取 item', async () => {
+    const seen: unknown[] = [];
+    const actions = actionsOf({
+      one: async (input) => {
+        seen.push(input);
+        return (input as { id: number }).id;
+      },
+    });
+
+    const { result } = await runFlowWith(
+      {
+        id: 'each',
+        title: '逐项',
+        steps: [
+          {
+            id: 'one',
+            action: 'one',
+            forEach: { over: ref('in.items'), as: 'item', max: 3 },
+            with: { id: ref('item.id') },
+          },
+        ],
+      },
+      actions,
+      { items: [{ id: 1 }, { id: 2 }] },
+    );
+
+    expect(result.status).toBe('ok');
+    expect(result.steps['one']).toEqual([1, 2]);
+    expect(seen).toEqual([{ id: 1 }, { id: 2 }]);
+  });
+
+  it('target 缺省回落流程 id', async () => {
+    const actions = actionsOf({ noop: async () => 'ok' });
+    const { result } = await runFlowWith(
+      { id: 'fallback', title: '回落', steps: [{ id: 'noop', action: 'noop' }] },
+      actions,
+      {},
+    );
+
+    expect(result.target).toBe('fallback');
+  });
+});

package/src/host/flow/check.ts

@@ -0,0 +1,216 @@
+import type {
+  FlowActionRegistry,
+  FlowCheck,
+  FlowDefinition,
+  FlowPredicate,
+  FlowProblem,
+  FlowValue,
+} from './types.js';
+
+type AddProblem = (path: string, problem: string) => void;
+
+interface CheckContext {
+  readonly seen: ReadonlySet<string>;
+  readonly item: boolean;
+  readonly value: boolean;
+}
+
+function checkValue(value: FlowValue, path: string, context: CheckContext, add: AddProblem): void {
+  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: FlowPredicate,
+  path: string,
+  context: CheckContext,
+  add: AddProblem,
+): void {
+  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: FlowDefinition,
+  actions: Pick<FlowActionRegistry, 'has'>,
+  prefix: string,
+  add: AddProblem,
+): void {
+  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<string>();
+  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: FlowDefinition,
+  actions: Pick<FlowActionRegistry, 'has'>,
+): FlowCheck {
+  const problems: FlowProblem[] = [];
+  checkFlowAt(flow, actions, '', (path, problem) => {
+    problems.push({ path, problem });
+  });
+  return { ok: problems.length === 0, problems };
+}

package/src/host/flow/expr.ts

@@ -0,0 +1,94 @@
+import { isDeepStrictEqual } from 'node:util';
+import type { FlowPredicate, FlowScope, FlowValue } from './types.js';
+
+function fieldOf(value: unknown, key: string): unknown {
+  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 as Readonly<Record<string, unknown>>)[key];
+}
+
+/**
+ * 读一个引用路径：`in.env`、`steps.builds.rows.0.id`、`item.id`、`value.status`。
+ * 中间缺一段就给 `undefined`，由调用方决定这是不是错。
+ * @param path 点分路径。
+ * @param scope 求值现场。
+ * @returns 取到的值；路径不成立给 `undefined`。
+ */
+export function readRef(path: string, scope: FlowScope): unknown {
+  const parts = path.split('.').filter((part) => part !== '');
+  const [root, ...rest] = parts;
+  if (root === undefined) return undefined;
+  let current: unknown;
+  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: FlowValue, scope: FlowScope): unknown {
+  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: unknown, right: unknown): boolean {
+  return isDeepStrictEqual(left, right);
+}
+
+/**
+ * 判一个条件表达式。只认五个操作符；未知形状给 `false`。
+ * @param predicate 条件表达式。
+ * @param scope 求值现场。
+ * @returns 真假。
+ */
+export function evalPredicate(predicate: FlowPredicate, scope: FlowScope): boolean {
+  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: Readonly<Record<string, FlowValue>> | undefined,
+  scope: FlowScope,
+): Readonly<Record<string, unknown>> {
+  if (values === undefined) return {};
+  const input: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(values)) input[key] = resolveValue(value, scope);
+  return input;
+}

package/src/host/flow/kit.ts

@@ -0,0 +1,30 @@
+import { checkFlow } from './check.js';
+import { createFlowActionRegistry, runFlow } from './run.js';
+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 function createFlowHost(): FlowHost {
+  return {
+    createActions: () => createFlowActionRegistry(),
+    check: (flow, actions) => checkFlow(flow, actions),
+    run: (options) => runFlow(options),
+  };
+}