@koda-sl/baker-cli 0.315.0 → 0.316.1

package/README.md

@@ -3351,7 +3351,7 @@ Read and shape this workspace's Forms (flows). Operates on the local `_data.json
 
 ```bash
 baker flows list                                   # every Form + how many confidential fields still need setup
-baker flows show contact                           # one Form's confidential fields and their status
+baker flows show contact                           # confidential fields + whether the destination changed under this Form
 baker flows show contact --full                    # include the full flow tree (secret values redacted)
 
 baker flows schema                                 # both vocabularies + the customForm field types
@@ -3363,7 +3363,8 @@ baker flows add-side-effect contact --node <nodeId> --type googleSpreadsheet   #
 baker flows map contact --from map.json --write     # a whole mapping at once — past ~3 fields, use this
 baker flows map contact --map A=nombre --write      # one or two fields
 baker flows map contact --hubspot-form <guid> --from map.json --write   # HubSpot: field types read off the form
-baker flows map contact --from map.json --replace --write   # the slot becomes exactly this; use it to REMOVE a mapping
+baker flows map contact --side-effect <id> --hubspot-form <guid> --prune-missing --write   # drop dead mappings
+baker flows map contact --from map.json --replace --write   # the slot becomes exactly this; drops everything not named
 baker flows normalize contact --write              # repairs a nulled optional; runs pre-commit anyway
 ```
 
@@ -3376,7 +3377,9 @@ Notes:
 - **Most CRM fields are not fed by a form field.** The value grammar is a bare form field (`nombre`), `field:Step.name` when two steps share a name, `tracking:utm_source`, `global:Name`, `code:exposed_value`, a `"literal"`, or any of those joined with `+`. Tracking names are validated against the engine's own `TRACKING_FIELD_IDS`, read out of the workspace rather than copied — attribution columns are the most common CRM mapping there is, and they were unexpressible before.
 - **A CRM mapping's field type is derived from the destination, never defaulted.** Every CRM record types `fieldType` as required, and it is the account's answer, not the agent's — HubSpot builds its submission key as `<objectTypeId>.<fieldType>.<fieldName>`, so a wrong type on a date property skips the `YYYY-MM-DD` coercion and the value is dropped. `--hubspot-form <formGuid>` (or `"hubspotForm"` in the mapping file) reads every property's type and object type off the form, so nothing has to state one. Where a destination cannot be read, put the type on the LEFT — `c0ffee:varchar=email` — which leaves `:` on the right for the value kinds. A mapping with no type from either route is refused, never written without one.
 - **`email` maps like anything else**, into `body.fields`, while `body.format` is `"json"`. A `"body"`-format email is one written message with no keys to address, and `map` refuses it rather than reshaping the body.
-- **Mapping twice adds; it does not start over.** Every slot merges with what is already in it, addressed by destination name — re-mapping a name overwrites it in place, a new name is appended, and a name the call did not mention is left alone. That is the default because a mapping is built in stages (configure the destination, read the real names back, map, come back for the rest), and replacing on every call turned "add the ninth field" into "delete the other eight". `--replace` (or `"replace": true` in the mapping file) writes the slot exactly as passed, and is the only way to remove a mapping. The response says how many were kept either way.
+- **A Form can look finished and be losing every lead.** HubSpot refuses a submission that names a property it does not have — the whole submission, not the field — and the visitor still reaches the thank-you screen. Baker re-checks each Form's destination and `baker flows show <slug>` reports what it found: `data.drift[]` carries **one entry per drifted destination** — a Form with two HubSpot side effects has two mappings, two form ids and two repairs — each with the severity, a sentence naming the fields, the side-effect id and that destination's HubSpot form id; the hints carry one repair command per entry. `drift: null` means the check could not be made and is not the same answer as `[]`.
+- **`--prune-missing` is the repair; `--replace` is not.** With `--side-effect <id>` and `--hubspot-form <guid>`, `--prune-missing` drops exactly the mappings whose destination field is absent from that form's live field list, names each one in `dropped`, and leaves every other mapping alone. It needs no `--map` and runs on its own. `--replace` drops everything the call does not name, so using it to remove three dead mappings means first restating the ten good ones correctly.
+- **Mapping twice adds; it does not start over.** Every slot merges with what is already in it, addressed by destination name — re-mapping a name overwrites it in place, a new name is appended, and a name the call did not mention is left alone. That is the default because a mapping is built in stages (configure the destination, read the real names back, map, come back for the rest), and replacing on every call turned "add the ninth field" into "delete the other eight". `--replace` (or `"replace": true` in the mapping file) writes the slot exactly as passed; to remove a mapping the destination has deleted, reach for `--prune-missing` instead. The response says how many were kept either way.
 - **`triggerId` is set from the step, not from the side-effect type.** A side effect runs only when its trigger is the id its own step raises: a `customForm` step raises `customForm.onFormSubmitted`, a Calendly step `calendlyEvent.eventScheduled`, a HubSpot widget `hubspotForm.onFormSubmitted`, a `text` step one of two depending on `allowNextNode`, and an `iframe` step one per declared event. A mismatch is the quietest failure in the engine — the file is valid, verify is green, and the side effect never runs — so `add-side-effect` derives it and refuses an id the step cannot raise. `--trigger` is for the non-completion moments (a HubSpot form's `onFormReady`, a Calendly page view). **A SavvyCal step raises no trigger at all**, so a side effect there is refused outright; put it on the following step, which the booking still advances to. `baker flows schema node <type>` lists a step's ids, and `baker flows show <slug>` names any side effect already wired to a moment its step never raises.
 - **A step's name becomes a constant, so `add-node` judges it as one.** The Form's generated code carries `export const <NAME> = "<node id>"` per step, keyed by upper-casing the name and splitting camelCase — so `contactInfo` and `Contact Info` are the same constant, and `1. Your details` or `Thanks!` are not valid ones at all. Both are refused when the step is created, where the message can name the step; left to the generator they surface as a duplicate-constant error or a syntax error in a file nobody wrote.
 - **`normalize` exists so authoring a Form does not require remembering an exception.** `oauthProviderId` is an optional `string`, so a `null` there fails typecheck one build later — it is repaired and staged instead of rejected.
@@ -6133,6 +6136,8 @@ This CLI is designed for AI agent consumption. Key patterns:
 
 ## Internal Notes
 
+- **0.316.0**: `baker flows show <slug>` reports **destination drift** — what the HubSpot form a Form submits to has changed under it — as `data.drift[]` plus a `DESTINATION DRIFT` hint carrying the repair as a ready-to-run command. It is the first time a Runtime can see this at all: the findings live in Baker and the HubSpot form id the repair needs is inside an encrypted config, so a Company Workspace could read neither. The classification is the one the dashboard badge reads (`classifyDrift` in `@baker/api`), so the two surfaces cannot disagree about whether a Form is healthy; a failed check answers `drift: null`, which is "unknown", never "clean". `baker flows map <slug> --side-effect <id> --hubspot-form <guid> --prune-missing [--write]` is the repair: it drops only the mappings whose destination field is absent from the form's live field list, names each in `dropped`, needs no `--map`, and refuses to run without a readable destination rather than guessing. Reach for it instead of `--replace`, which drops every mapping the call does not name.
+
 - **0.103.0**: `baker actions ...` commands now type their `/api/actions/...` request/response payloads from the shared `@baker/api` contract package (also consumed by the backend) instead of hand-written local interfaces. No command, flag, or output-shape changes.
 - **0.104.0**: `baker actions tags ...` commands now type their `/api/actions/tags...` request/response payloads from the shared `@baker/api` contract package instead of hand-written local interfaces. No command, flag, or output-shape changes.
 - **0.105.0**: `baker images ...`, `baker videos ...`, and `baker testimonials ...` commands now type their `/api/{images,videos,testimonials}/...` request/response payloads from the shared `@baker/api` contract package instead of hand-written local interfaces. No command, flag, or output-shape changes.