Figma Shared Component Deletion Drift Gate

id: figma-shared-component-deletion-drift-gate
namespace: company.team

description: |
  Watch a Figma file for changes and, on every real edit, diff its current set of components
  against the set this flow last saw. Deleting a shared component in Figma does not warn anyone;
  every instance of it across every file that uses it silently detaches from the source the next
  time that file is opened. This catches the deletion the moment it happens, names exactly which
  component disappeared, and keeps a running baseline so the next edit is diffed against this one.

inputs:
  - id: file_key
    type: STRING
    displayName: Figma file key
    description: The file key segment from the file's URL (figma.com/file/<file_key>/...).
    defaults: "abc123XYZ"

tasks:
  - id: fetch_current_components
    type: io.kestra.plugin.figma.files.GetFile
    description: Pulls the file's current document, which includes its top-level
      components map (node id, stable key, name, description per component)
      alongside the full canvas tree.
    accessToken: "{{ secret('FIGMA_ACCESS_TOKEN') }}"
    fileKey: "{{ inputs.file_key }}"
    fetchType: FETCH_ONE

  - id: load_known_components
    type: io.kestra.plugin.core.kv.Get
    description: Reads back the component key list this flow saved after the
      previous edit. Missing on the very first run for this file, which
      load_known_components.value defaults around below.
    key: "figma_known_component_keys_{{ inputs.file_key }}"
    errorOnMissing: false

  - id: diff_components
    type: io.kestra.plugin.core.output.OutputValues
    description: Diffs the file's current component keys (the stable identifier
      instances reference, not the volatile node id) against the previously
      saved set, in both directions.
    values:
      current_keys: >-
        {{ ({'components': outputs.fetch_current_components.row.components} |
        jq('[(.components // {})[]?.key] | unique')) | first }}
      previous_keys: "{{ outputs.load_known_components.value is defined and
        outputs.load_known_components.value is not null ?
        (outputs.load_known_components.value | fromJson) : [] }}"
      deleted_keys: >-
        {{ ({'current': (({'components':
        outputs.fetch_current_components.row.components} | jq('[(.components //
        {})[]?.key] | unique')) | first), 'previous':
        (outputs.load_known_components.value is defined and
        outputs.load_known_components.value is not null ?
        (outputs.load_known_components.value | fromJson) : [])} | jq('.previous
        - .current')) | first }}
      added_keys: >-
        {{ ({'current': (({'components':
        outputs.fetch_current_components.row.components} | jq('[(.components //
        {})[]?.key] | unique')) | first), 'previous':
        (outputs.load_known_components.value is defined and
        outputs.load_known_components.value is not null ?
        (outputs.load_known_components.value | fromJson) : [])} | jq('.current -
        .previous')) | first }}
      deleted_names: >-
        {{ ({'components': outputs.fetch_current_components.row.components,
        'deleted': (({'current': (({'components':
        outputs.fetch_current_components.row.components} | jq('[(.components //
        {})[]?.key] | unique')) | first), 'previous':
        (outputs.load_known_components.value is defined and
        outputs.load_known_components.value is not null ?
        (outputs.load_known_components.value | fromJson) : [])} | jq('.previous
        - .current')) | first)} | jq('.deleted as $d | [(.components // {})[] |
        select(.key as $k | $d | index($k))] | [.[].name] | join(", ")')) |
        first }}
      severity: >-
        {{ ((({'current': (({'components':
        outputs.fetch_current_components.row.components} | jq('[(.components //
        {})[]?.key] | unique')) | first), 'previous':
        (outputs.load_known_components.value is defined and
        outputs.load_known_components.value is not null ?
        (outputs.load_known_components.value | fromJson) : [])} | jq('.previous
        - .current')) | first) | length) > 0 ? 'COMPONENTS_DELETED' : 'HEALTHY'
        }}

  - id: route
    type: io.kestra.plugin.core.flow.Switch
    description: COMPONENTS_DELETED names every component key (and, where it could
      still be resolved from the current response, its last known name) that
      existed on the previous edit and is gone now. There is no safe
      auto-remediation here (Figma has no undo-delete through this API), so this
      only ever alerts.
    value: "{{ outputs.diff_components.values.severity }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "Figma file {{ inputs.file_key }}: {{
            outputs.diff_components.values.current_keys | length }}
            component(s), none deleted since the last edit this flow saw. {{
            outputs.diff_components.values.added_keys | length }} new since
            then."
      "COMPONENTS_DELETED":
        - id: alert_components_deleted
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {{ {'text': 'COMPONENTS_DELETED in Figma file ' ~ inputs.file_key ~ ': ' ~ (outputs.diff_components.values.deleted_keys | length) ~ ' component(s) present on the last edit this flow saw no longer exist: ' ~ (outputs.diff_components.values.deleted_names != '' ? outputs.diff_components.values.deleted_names : (outputs.diff_components.values.deleted_keys | join(", "))) ~ ". Every file with an instance of these components just had it silently detach. Execution " ~ execution.id ~ "."} | toJson }}

  - id: save_current_components
    type: io.kestra.plugin.core.kv.Set
    description: Always runs regardless of severity, so the next edit is diffed
      against this one rather than re-alerting on the same deletion forever.
    key: "figma_known_component_keys_{{ inputs.file_key }}"
    kvType: JSON
    value: "{{ outputs.diff_components.values.current_keys | toJson }}"

  - id: summary
    type: io.kestra.plugin.core.log.Log
    message: "Figma component drift check for {{ inputs.file_key }} complete:
      severity {{ outputs.diff_components.values.severity }}, {{
      outputs.diff_components.values.current_keys | length }} current / {{
      outputs.diff_components.values.deleted_keys | length }} deleted / {{
      outputs.diff_components.values.added_keys | length }} added."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {{ {'text': 'Figma shared component deletion drift gate failed (execution ' ~ execution.id ~ '). Check the logs.'} | toJson }}

triggers:
  - id: on_file_updated
    type: io.kestra.plugin.figma.triggers.FileUpdated
    description: Polls the file's lastModified timestamp and fires only when it
      advances, using Figma's own watermark semantics; the first evaluation
      after enabling never fires, it only records the baseline timestamp.
    accessToken: "{{ secret('FIGMA_ACCESS_TOKEN') }}"
    fileKey: "{{ inputs.file_key }}"
    interval: PT5M