v2 (CLI-aligned) YAML format for Lightning workflows.

See test/fixtures/portability/v2/canonical_workflow.yaml for the spec-by-example. New contributors should read that file before this module.

Spec source (pinned)

This module implements the OpenFn Portability Spec as defined at:

• Project / Workflow / Step / Trigger / Job types: https://github.com/OpenFn/kit/blob/42d6b380242050c3248e2714e1e590a18bef8dbd/packages/lexicon/portability.d.ts
• condition union (literals + JS body): https://github.com/OpenFn/kit/blob/2d87928c74d74fb11c1f34d4277ccbba364578d7/packages/lexicon/lightning.d.ts#L102
• Kitchen-sink example (a project YAML exercising the spec): https://github.com/OpenFn/docs/blob/fb7fa4ae8b629e6bc4382412662bf6e376b87087/docs/deploy/portability.md#L87-L153

The links above pin specific commits so future readers can audit which version of the spec this code targets. The spec carries explicit // TODO markers (next-as-string deprecation, step.id required, condition.label vs name, credential as id-string) — those are pending upstream. Where Lightning's behavior diverges from the in-flight spec, see "Subject to upstream finalization" below.

Subject to upstream finalization

• cron_cursor — Lightning emits cron_cursor: <step-id> flat at the trigger root (stateless, by-name). The kitchen-sink example uses cron_cursor_job_id: <uuid> flat at the trigger root, which contradicts the spec's statelessness principle and isn't defined in portability.d.ts at all; we use the step-id form pending upstream resolution.
• next: form — portability.d.ts:60 carries a // TODO remove next: string (next should always be an object) note. Lightning emits verbose-only to align with the spec direction and to avoid the bare-string parsing bug in @openfn/project@0.15 where next: <step-id> gets misread as iterating over the target id's characters. Bare-string next: is no longer emitted.
• name vs label on ConditionalStepEdge — portability.d.ts has // TODO this is probably the name. Lightning emits label: today; swap when upstream lands.

Shape

Workflow portability shape:

id: <string>
name: <string>
start: <step-id>          # entry trigger's step-id (spec: WorkflowSpec.start)
steps: [<step>, ...]      # one array — both jobs and triggers

Before emission, the canonical map splits the single steps: array into two sibling keys — :triggers and :steps — so the emitter can iterate triggers and jobs separately. Both keys are always present (empty list when there are none).

A trigger step has a type discriminator (webhook / cron). All Lightning extensions land flat at the trigger root — there is no openfn: wrapper:

- id: <string>
  name: <string>
  enabled: true | false
  type: webhook | cron
  cron_expression: "0 0 * * *"          # cron only (spec: flat field)
  cron_cursor: <step-id>                # cron only (Lightning ext, flat)
  webhook_reply: <string>               # webhook only (spec: flat field)
  webhook_response_config:              # webhook only (Lightning ext)
    success_code: <int>                 #   omitted entirely when unset
    error_code: <int>
  next:
    <step-id>:
      condition: always | on_job_success | on_job_failure | <js body>

A job step has no type field:

- id: <string>
  name: <string>
  adaptor: <string>
  expression: |
    fn(state => state)
  configuration: <credential-key>      # optional
  next:
    <step-id>:
      condition: always | on_job_success | on_job_failure | <js body>
      expression: |                    # only emitted alongside js body
        <js body>
      label: <string>                  # optional
      disabled: true                    # optional, defaults to false

Condition discrimination

Per lightning.d.ts:102, condition is the union 'always' | 'on_job_success' | 'on_job_failure' | string. Lightning emits the named literals (always, on_job_success, on_job_failure) verbatim for those condition_type values; for :js_expression the field carries the user-supplied JS body string. The literal is always present (matches the kitchen-sink example), so parsers don't need to assume a default for a missing condition: field.

Field-name table