Skip to content

feat: plan 034 PR A — Extension API v1: registrar, yaymatik_fire, Run, data fields and facts, missing plugin - #41

Merged
jack9x merged 12 commits into
developfrom
jack/feature/034a-extension-api
Nov 17, 2026
Merged

jack9x merged 12 commits into
developfrom
jack/feature/034a-extension-api

Conversation

@jack9x

@jack9x jack9x commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Summary

Other plugins can now add triggers, actions, data fields and data items to YayMatik through one hook, with arrays, without extending a YayMatik class (docs/extension-api.md, agreed Nov 13; public surface simplified 11:47).

  • Declare: add_action( 'yaymatik_register', fn( $r ) => $r->module( [...] )->trigger( … ) ). Fields and types are arrays and type names; callbacks are any PHP callable.
  • Fire: do_action( 'yaymatik_fire', $trigger_id, [ 'user_id' => …, 'points' => … ] ). Payload ids become the run's data and subject (order → cart → review → user → the module's item), declared facts become trigger.<key>. The event takes the core path: Dispatcher, claims, run ceiling, loop guard.
  • Run: an action's run( $config, $run ) returns $run->done() / skip() / fail(); $run reads order(), user(), customer_email(), cart(), item(), get(), render().
  • Isolation: every plugin callback runs in a guard: a throw becomes a diagnostic in Settings › Health check › Extensions, never an error in core. A deleted entity still skips the step as in core ("Order no longer exists.").
  • Plugin turned off: its steps stay in the workflow (greyed, read-only), the workflow saves but can't be activated (missing_plugin), an active one keeps running and skips those steps ("Acme Rewards isn't active."), and Health check lists it.

Base: develop 6be688a. No schema change (two options: yaymatik_extension_errors, yaymatik_extension_steps, both autoloaded). Core behaviour for 1.0 workflows is unchanged; every core edit is listed under "Core changes".

Checkpoints

  • CP0 Contract and docs (7ea8599): docs/extension-api.md, design and decision log § EX, roadmap, 033 tester steps in phases.
  • CP1 Diagnostics (e00a3a8): Extension\Diagnostics (last 50, one write per module and callback per 10 minutes, count is a lower bound), a second id claim recorded, Health check › Extensions.
  • CP2 Public API (e762602): Api\Registrar, Api\Module, Api\Run; Declaration (id rules, field arrays → core fields, type names → core types); Fire (yaymatik_fire, waits for init); ExtensionTrigger / ExtensionAction / RunAdapter; Step::setup_issue() / setup_issue_code() / context_error(); open picker categories.
  • CP3 Data and facts (a1f98cd): data_fields() on core items, data_item() with load, CustomerView / CartView, trigger facts (Insert variable, conditions, run detail, previews).
  • CP4 Missing plugin (32c495d): step index, saved nodes kept, missing_plugin issue, Skipped steps, Health check row, greyed cards.
  • CP5 Privacy, snapshots, PR text (CP5_HASH): privacy_subjects, SurfaceTest (public classes), CoreStepsTest + docs/extension-api-core.md (./run.sh extension-core).

Tests

  • PHPUnit 923 → 1010 on 6be688a → this branch; Vitest 492 → 501.
  • Reference consumer: the YayWholesale integration class, as written, registers and runs "approved → Set wholesale role" (ReferenceConsumerTest).
  • Loop guard: an action that fires its own workflow's trigger through yaymatik_fire starts one run, with or without emits (DispatcherWorkerTest).
  • Core unchanged: an order deleted while a run waits still gives Skipped "Order no longer exists." for core and extension steps (ExecutorTest).
  • wp-cli: check-late-module (19 checks: registrar module on plugins_loaded 20, yaymatik_fire starts a run, refused declaration, plugin off → saves, activate 400 missing_plugin), check-privacy-index (module subjects found by export). check-all on wp-env and wp-env-min, e2e 11/11.

Review notes

  • /code-review high on CP1–CP5; every finding fixed in its checkpoint (listed in the plan's Deviations).
  • Review fix: trigger fact keys are per trigger, resolved against the workflow's own trigger in PHP and the editor, so one plugin's fact type can't remove another's trigger.
  • Core changes are additive: each new path runs only for an extension module, an extension step, a fact, or a step in the index. Core triggers have no facts, no setup_issue_code other than the cart's own, no context_error.

Core changes

  • ModuleRegistry: runs yaymatik_register once when it first builds; accepts module, step and data item objects; refreshes the step index.
  • StepRegistry / DataRegistry: don't cache while yaymatik_register runs; DataRegistry::field( 'trigger.<key>', $trigger ) reads that trigger's facts.
  • Step / Trigger: setup_issue(), setup_issue_code(), context_error(), facts(), sample_facts(); defaults change nothing.
  • Validator: per-node setup issue, context_error, facts, missing_plugin. Executor: context_error, Skipped for an inactive step. GraphSchema::prepare() keeps saved inactive nodes. Criteria: rule keys keep digits; a fact rule is checked against the trigger. Scope::timestamp() reads a date fact. RefResolver: loaders for extension data items. SampleValues: a field's own sample. EmailPreview: fact samples; inactive nodes kept. RunPresenter: facts. HealthCheck: missing_plugin, extensions. PersonSubjects: module subjects. Runtime: hooks yaymatik_fire. Catalog: categories, inactiveSteps.

Browser steps (Jack)

0 Understand

Another plugin (the "Acme Rewards" example) adds a trigger, an action, a customer field and a fact. Its trigger starts when the plugin calls yaymatik_fire. When the plugin is turned off, its steps stay but can't run.

1 Prepare

  • Local site on this branch's zip, or pnpm dev.
  • Copy .claude/local/034-example-acme.php to wp-content/plugins/acme-rewards/acme-rewards.php. Delete its section 5 (email action) and section 6 (template): they come in PR B. Add any one-colour 24×24 logo.svg beside it. Activate "Acme Rewards for YayMatik (example)".
  • Two customer accounts (A, B), each with an order you can set to Completed. Cash on delivery enabled.

2 Steps

  • E1 Goal: Extensions block on a clean site. Do: before activating Acme, Settings › Health check › Check again. Pass when: an "Extensions" block says no other plugin adds to YayMatik. Why: core modules aren't listed.
  • E2a Goal: trigger in the picker. Do: Workflows › Create › Choose trigger, search "points". Pass when: "Customer earned points" shows under Customers with the Acme logo; its form has "Only when at least" (default 1). Why: registrar trigger and server-drawn fields.
  • E2b Goal: trigger and action end to end. Do: build "Customer earned points" → "Add reward points" (Points 10), Activate. In WooCommerce › Orders open customer A's order (total e.g. 25.40) and set it to Completed. Reload the workflow's Workflow runs a few times over a minute or two. Pass when: 1 Completed run; its trigger line reads "Points earned: 25"; the Add reward points step is Completed; no second run. The editor shows "This step can set off this workflow's own trigger. The workflow won't start again from it." — expected, not a failure. Why: a yaymatik_fire trigger and an array-declared action run like core steps (the action's own yaymatik_fire is stopped by Acme's hourly limit).
  • E3a Goal: field in a condition. Do: in a workflow on "Order paid", add a condition, pick a field. Pass when: Customer › "Points balance" is listed with number comparisons. Why: data_fields( 'customer' ).
  • E3b Goal: fact as a variable. Do: workflow on "Customer earned points", add Send email, open Insert variable. Pass when: "Points earned" is listed first, under Trigger; saving the email with it shows no issue. Why: facts reach the editor and the server check.
  • E3c Goal: fact in run detail. Do: complete customer B's order (total e.g. 42.90) in WooCommerce › Orders; reload Workflow runs and open the new run. Pass when: the trigger line reads "Points earned: 42". Why: facts in run detail.
  • E4a Goal: open and save with the plugin off. Do: create W1 and W2 = "Customer earned points → Add reward points"; activate W1 only. Plugins › deactivate Acme. Open W2, rename it, Save. Pass when: W2 is "Draft" (never activated); both Acme cards are greyed with "Needs Acme Rewards — the plugin isn't active."; the save succeeds; clicking a card shows "You can edit and save this workflow, but you can't turn it on until Acme Rewards is active. If it's already on, it keeps running and skips this step." Why: saved nodes are kept.
  • E4b Goal: Activate blocked. Do: click Activate on W2. Pass when: Activate is refused; a banner reads "This workflow uses Acme Rewards, which isn't active. Activate Acme Rewards to turn the workflow on." with Show step 1/2; both Acme cards have an Error badge; Activate is disabled. Why: missing_plugin.
  • E4c Goal: Health check. Do: Settings › Health check › Check again. Pass when: "Active workflows use a plugin that isn't active: 1" (only active workflows with an Acme step count; inactive and draft ones don't) with a link reading "Workflow #" to W1 and a Plugins link. Why: new check.
  • E4d Goal: reactivate. Do: activate Acme; reload W2; Activate. Pass when: cards look normal and W2 activates. Why: nothing was rewritten.
  • E4e Goal: an active workflow keeps running and skips the missing step. Do: with Acme active, create W3 "Order paid → Add reward points (10) → Add order note ('W3 ran')" and Activate it. Deactivate Acme. Place a Cash on delivery order as a customer, then set it to Processing in WooCommerce › Orders. Reload W3's Workflow runs a few times. Pass when: 1 Completed run; run detail shows "Add reward points" with "Acme Rewards isn't active." (no separate "Skipped" word, same as core steps); the order has the note "W3 ran". Why: an already active workflow keeps running and skips that step.
  • E4f Goal: editor header stays in view. Do: with Query Monitor active (or any admin menu taller than the window), open a workflow editor and click a step card; repeat in a template preview. Pass when: the editor's header row (name, More actions, Activate, ×) stays visible below the plugin header; the page doesn't scroll. Why: the editor locks page scroll while open.

…ymatik_fire, Run, extension triggers and actions
Steps and the trigger resolve through stepOf, so a step of a plugin that is off shows its label and a greyed tile like its canvas card. "Removed step" stays for ids neither the registry nor the inactive steps know. The missing_plugin health check test now covers 2 active, 1 inactive and 1 draft workflow.
Cause, measured on the editor route (viewport 773px, admin bar 32px):
#wpbody-content and #yaymatik are exactly 741px, no admin notices, no
padding, and Query Monitor's container is 0px tall. The page scrolls
because the WP admin menu (#adminmenuwrap) is 787px, taller than the
741px below the admin bar, so WP unpins it (position: relative) and it
sets #wpbody/#wpwrap to 787px: document 819px vs viewport 773px, 46px
of scroll. Clicking a step card then scrolls the window and the
editor's header row slides under the sticky plugin header.

While EditorLayout is mounted, <html> gets yaymatik-editor-open
(overflow: hidden) and the window scrolls to the top; the class goes
on unmount. Only <html>: overflow on <body> makes body the sticky
header's scroller and pushes the header down by the admin bar.
Checked in the editor and in template preview.
@jack9x
jack9x merged commit 06f2857 into develop Nov 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant