@coignite/directus-extension-flows-manager 1.6.0 → 1.9.1

package/README.md

@@ -0,0 +1,96 @@
+# Flows Manager (`@coignite/directus-extension-flows-manager`)
+
+A module for administrators that files Directus flows in folders, keeps the last 20 versions of
+every flow, restores a version or a deleted flow, exports and imports flows as JSON, and — with a
+source instance configured — shows and applies the differences between this instance's flows and
+the source's.
+
+## What it installs
+
+| Entry | Type | What it does |
+|---|---|---|
+| `fm-module` | module | The Flows Manager screen. Administrators only (`preRegisterCheck`). |
+| `fm-bootstrap` | hook | At `app.after`, creates and converges every table below through `ensureSchema` (`src/libs/directus-schema`), then runs the one-shot below. The only place the bundle makes schema. |
+| `fm-fence` | hook | Refuses every `items.query/create/update/delete` on the tables below to anyone but Directus itself and administrators: 403 `FLOWS_MANAGER_OWNED_TABLE`. |
+| `fm-backup` | hook | Writes a backup row on every flow create, update and delete; drops a deleted flow's folder assignment. Creates nothing. Its `routes.before` middleware reads the operation links of a flow a REST delete names, before Directus nulls them (below). |
+| `fm-endpoints` | endpoint | `/flows-manager/*`: the diff against the source, create/apply/duplicate/delete flows, operations by flow. Runs Directus' services with the caller's own accountability; only the source instance is reached over HTTP. |
+
+Settings, read from the environment: `SOURCE_DIRECTUS_URL` and `SOURCE_ACCESS_TOKEN` (the instance to
+compare with; without them the diff views are empty), `ENV`, and Directus' own `PUBLIC_URL`.
+
+## Tables
+
+All under the data-model folder `dx_flows_manager`, all hidden from the Content module, all
+declared in `src/lib/collections.ts`:
+
+| Table | What it holds |
+|---|---|
+| `backup_flows` | The last 20 versions of every flow (the flow with its operations, as JSON), who changed it and how; `flow_deleted` marks the version taken just before a delete. |
+| `flows_manager_folders` | The folder tree: `name`, and `parent` — the id of the folder it sits in. |
+| `dx_flows_manager_flow_folders` | Which folder a flow is in: `flow` (the flow id, primary key) → `folder`. No row means the root. Deleting a folder sets `folder` to null (`ON DELETE SET NULL`). |
+| `dx_flows_manager_settings` | A singleton: `flow_folders_migrated_at`, the marker of the 1.8.0 one-shot. |
+
+`backup_flows` and `flows_manager_folders` keep the names 1.7.0 gave them; renaming a live table is
+an operator step no release has carried yet.
+
+## Installation / opgradering
+
+Install the bundle and restart. The tables are created at boot; the module creates nothing.
+
+### From 1.7.0 or earlier
+
+Until 1.8.0 a flow's folder was stored in a column the module added to the system table
+`directus_flows` (`flows_manager_folder`). At the first boot of 1.8.0 a one-shot copies every value
+that points at an existing folder into `dx_flows_manager_flow_folders` and logs
+
+```
+[bundle:flows-manager:bootstrap] copied N flow folder assignment(s) out of directus_flows.flows_manager_folder into dx_flows_manager_flow_folders …
+```
+
+It runs once (the marker above), holds the settings row `FOR UPDATE` so two nodes booting together
+copy once, and writes nothing to `directus_flows`. A value pointing at a folder that no longer exists
+is not copied — that flow shows at the root, where 1.7.0 showed it nowhere.
+
+The old column is not read any more and the bundle never drops it (a bundle does not change a system
+table's columns). Once the module shows the folders it should, an administrator may remove it in
+Settings → Data Model → Directus Flows, or with
+
+```sql
+ALTER TABLE directus_flows DROP COLUMN flows_manager_folder;
+DELETE FROM directus_fields WHERE collection = 'directus_flows' AND field = 'flows_manager_folder';
+```
+
+Rolling back to 1.7.0 shows the folders as they were at the upgrade: 1.7.0 reads the old column,
+and 1.8.0 never writes it. Moves made after the upgrade are not seen by 1.7.0, and moves made while
+rolled back are not seen by 1.8.0 when it returns (the copy runs once). Drop the column only once a
+rollback is off the table — 1.7.0 recreates it empty and shows every flow at the root.
+
+### A deleted flow's backup
+
+Directus sets every operation's `resolve`/`reject` to null before `flows.delete` fires, so the
+backup hook cannot read the chain there. The links are read just before: by the endpoint for its own
+deletes, and by `fm-backup`'s middleware for `DELETE /flows` and `DELETE /flows/:pk`. A delete
+neither sees (GraphQL, another extension's service call) takes them from the newest earlier backup
+of the flow, and the delete backup says so in `flows_manager_links` (`{ from: 'backup', backup_id,
+backup_timestamp }`, or `{ from: 'none' }` when no earlier backup exists).
+
+## Access
+
+The module and its tables are for administrators. A role with an "all collections" policy reaches
+none of the tables through `/items`, GraphQL or imports: `fm-fence` answers 403
+`FLOWS_MANAGER_OWNED_TABLE`. A Flow operation with Emit Events off (Directus' default) runs no
+hooks, so it is not fenced: since 1.9.0 the start-up log names each one on these tables, and again
+when one is created or changed (`[bundle:flows-manager] Flow "…" … Tick "Emit Events" on the
+operation.`). The bundle ships no policies. The endpoints do what the caller may do:
+they run Directus' services with the request's accountability, whatever the session cookie is
+called (`SESSION_COOKIE_NAME`); a request with no accountability is refused 401. `fm-backup`, the bootstrap and the one-shot
+write with the database connection and are not fenced.
+
+## Verifying a release
+
+- `npm run flows-manager:gate` — typecheck, the unit suite, this README naming every table, the
+  CHANGELOG heading.
+- On a stack, fresh and upgraded from the previous release:
+  `npm run schema:audit -- --url <stack> --prefix backup_,flows_manager_,dx_flows_manager` → 0 errors;
+  the boot log shows the tables created or grouped and hidden, and the second restart is silent.
+- A non-administrator with an "all collections" policy gets 403 on every table above.