formist-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,402 @@
1
+ """``fm participants dedupe`` - merge duplicate people in a space.
2
+
3
+ The decision lives on the server; this module is a client and holds no
4
+ copy of it. That split is not stylistic: two answers to "are these the
5
+ same person" is precisely how the duplicates this repairs were created,
6
+ one row at a time.
7
+
8
+ This talks to ``/projects/{space}/admin/...`` and not the plain admin
9
+ helpers, because those refuse a non-Global prod target before a socket
10
+ opens, which is correct for the literal ``/admin`` tier (that tier is
11
+ Global-only). Participants are region-local, so this endpoint is
12
+ project-scoped and must reach ``ae``; sending it through the admin
13
+ helpers would refuse the only target that has the data.
14
+
15
+ The safety choreography:
16
+
17
+ A dry run always runs, including under ``--apply``. It is printed first,
18
+ and what is submitted is the ``plan_token`` of the plan that was printed.
19
+
20
+ ``--apply`` takes the token, not a bare flag. The connector that produced
21
+ these duplicates runs every 30 minutes, so "merge what is duplicated now"
22
+ is a different set from "merge what you just showed me". A stale token is
23
+ a 409 and nothing is written.
24
+
25
+ ``--apply`` never inherits an environment from ``fm use``. A remembered
26
+ environment is one somebody forgets they set.
27
+
28
+ No whole-plan apply, enforced server-side and refused with 422 if this CLI
29
+ is bypassed: ``--apply`` merges only the groups named by ``--group``
30
+ (repeatable), and needs ``--reason``, one sentence saying why the named
31
+ group(s) are one person. There is no "merge everything" shape. Naming a
32
+ group is what makes it mergeable, record-id or same-name alike; a shared
33
+ name is still never auto-merged, a human still has to name it.
34
+
35
+ ``--review`` prints the describe data, not a decision: every row's id,
36
+ created_at and provenance, every identity field side by side across the
37
+ group's rows with conflicts marked, the tool's keeper suggestion and why,
38
+ and the evidence (session participations, audit history) a human weighs
39
+ before naming a group. Nothing in it is a command to run.
40
+ """
41
+
42
+ from __future__ import annotations
43
+
44
+ import json
45
+ import sys
46
+ from typing import Any
47
+
48
+ from formist_cli.cli_support import PLATFORM_ADMIN_GATE_NOTE, add_admin_flag, require_object
49
+
50
+ #: Deliberately not named `ENDPOINT`: other modules each own a constant by
51
+ #: that name with nothing comparing them, and a third copy of that name
52
+ #: would make the collision worse. Same decision `skill_library.py` took
53
+ #: (`SKILL_LIBRARY_SYNC_ENDPOINT`).
54
+ DEDUPE_PATH = "/projects/{space}/admin/participants/dedupe"
55
+
56
+ SUBJECTS = ("dedupe",)
57
+
58
+
59
+ class ParticipantsError(Exception):
60
+ """A refusal or a malformed answer, phrased for whoever has to fix it."""
61
+
62
+
63
+ def add_parser(sub) -> None:
64
+ import argparse
65
+
66
+ from formist_cli.cli import _add_env, _add_space
67
+
68
+ p = sub.add_parser(
69
+ "participants",
70
+ help="find and merge duplicate participants in a space",
71
+ description=(
72
+ "Groups a space's participants by the SOURCE record id a connector "
73
+ "stamped on them (data.<connector>.record_id) and, advisory only, by "
74
+ "normalised name. DESCRIBES ONLY: nothing here is a decision.\n\n"
75
+ "DRY RUN BY DEFAULT. --apply takes the plan_token this run printed; "
76
+ "if the duplicates have changed since (the sync runs every 30 "
77
+ "minutes), the server answers 409 and writes nothing.\n\n"
78
+ "NO WHOLE-PLAN APPLY. --apply merges ONLY "
79
+ "the groups named by --group (repeatable), record-id or same-name "
80
+ "alike, and needs --reason: one sentence saying why the named "
81
+ "group(s) are one person. There is no 'merge everything' shape, a "
82
+ "request naming no group, an empty list, or a wildcard is refused "
83
+ "422 by the server.\n\n"
84
+ "Merging keeps the OLDEST row, unions every non-empty value onto it "
85
+ "(nothing is lost), re-points every live reference, and SOFT-deletes "
86
+ "the rest. Audit history is never rewritten. --review prints the full "
87
+ "describe data (per-row provenance, side-by-side identity fields with "
88
+ "conflicts marked, the keeper suggestion) as markdown."
89
+ ),
90
+ epilog=PLATFORM_ADMIN_GATE_NOTE,
91
+ formatter_class=argparse.RawDescriptionHelpFormatter,
92
+ )
93
+ _add_env(p)
94
+ _add_space(p)
95
+ p.add_argument("subject", choices=SUBJECTS, help="what to operate on (today: dedupe)")
96
+ p.add_argument(
97
+ "--group",
98
+ action="append",
99
+ default=None,
100
+ metavar="KEY",
101
+ help=(
102
+ "a group key to include ('airtable:recXXXX' or 'name:<normalised "
103
+ "name>'), repeatable. On a dry run: scopes what is described (and "
104
+ "the plan_token, to exactly these groups). Under --apply: REQUIRED, "
105
+ "the exact groups to merge, and nothing else"
106
+ ),
107
+ )
108
+ p.add_argument(
109
+ "--reason",
110
+ default=None,
111
+ metavar="TEXT",
112
+ help=(
113
+ "REQUIRED under --apply: one sentence saying why the named group(s) "
114
+ "are the same person. Becomes the audit row's explanation"
115
+ ),
116
+ )
117
+ p.add_argument(
118
+ "--apply",
119
+ metavar="PLAN_TOKEN",
120
+ default=None,
121
+ help="merge, if the duplicates still match the plan_token this run printed",
122
+ )
123
+ p.add_argument(
124
+ "--drop",
125
+ action="append",
126
+ default=None,
127
+ metavar="GROUP=data.path",
128
+ help=(
129
+ "do NOT carry one merged-in value onto the survivor, e.g. "
130
+ "--drop 'airtable:recSyn001Abc002Xy=data.airtable.contact_email'. "
131
+ "For a value you have read and judged wrong. The losing row keeps it "
132
+ "(soft delete + audit snapshot), so nothing is destroyed. Repeatable"
133
+ ),
134
+ )
135
+ p.add_argument(
136
+ "--review",
137
+ action="store_true",
138
+ help="markdown describe output: per-row provenance, side-by-side "
139
+ "identity fields with conflicts marked, the keeper suggestion, and the "
140
+ "evidence a human weighs. Nothing in it is a command to run",
141
+ )
142
+ p.add_argument("--json", action="store_true", help="machine-readable output")
143
+ add_admin_flag(p)
144
+
145
+
146
+ def parse_drops(values: list[str] | None) -> dict[str, list[str]]:
147
+ """``["group=data.a.b", ...]`` -> ``{"group": ["data.a.b"]}``.
148
+
149
+ Split on the FIRST ``=`` only: a group key is ``airtable:recXXXX`` or
150
+ ``name:<normalised name>`` and a normalised name can contain almost anything,
151
+ so splitting on every ``=`` would silently truncate a key rather than fail.
152
+ """
153
+ drops: dict[str, list[str]] = {}
154
+ for raw in values or []:
155
+ if "=" not in raw:
156
+ raise ParticipantsError(
157
+ f"--drop needs GROUP=data.path, got {raw!r}. The group key is the "
158
+ "one printed by the dry run."
159
+ )
160
+ group, path = raw.split("=", 1)
161
+ if not group or not path:
162
+ raise ParticipantsError(f"--drop needs a group AND a path, got {raw!r}")
163
+ drops.setdefault(group, []).append(path)
164
+ return drops
165
+
166
+
167
+ def _plan(body: object) -> dict:
168
+ """The dedupe plan from a response body, or a refusal naming what came back."""
169
+ envelope = require_object(body, what="the participants dedupe endpoint", error=ParticipantsError)
170
+ if "groups" not in envelope:
171
+ raise ParticipantsError(
172
+ "the participants dedupe endpoint returned an object with no `groups` "
173
+ f"key: {str(envelope)[:200]}"
174
+ )
175
+ return envelope
176
+
177
+
178
+ def fetch_plan(target, space: str, *, token: str | None, groups: list[str] | None = None, get=None) -> dict:
179
+ """The dry run. Writes nothing.
180
+
181
+ ``groups`` is repeated as ``?group=`` (a plain dict can only carry one
182
+ value per key, which is why this builds the query string itself rather
183
+ than passing ``params=``): the server treats it as a pure display
184
+ filter and scopes the returned ``plan_token`` to exactly what came back.
185
+ """
186
+ from urllib.parse import urlencode
187
+
188
+ from formist_cli import api
189
+
190
+ get = get or api.get
191
+ path = DEDUPE_PATH.format(space=space)
192
+ if groups:
193
+ path = f"{path}?{urlencode([('group', g) for g in groups])}"
194
+ return _plan(get(target, path, token=token))
195
+
196
+
197
+ def submit(
198
+ target,
199
+ space: str,
200
+ plan_token: str,
201
+ *,
202
+ token: str | None,
203
+ groups: list[str],
204
+ reason: str,
205
+ drop_data_keys: dict[str, list[str]] | None = None,
206
+ post=None,
207
+ ) -> dict:
208
+ """Merge exactly ``groups`` of the plan whose fingerprint is ``plan_token``.
209
+
210
+ Sends ``groups``/``reason`` as-is and lets the server refuse (422) an
211
+ empty list, a wildcard, or a blank reason: the server is the one place
212
+ that rule is checked, and duplicating it here would be a second copy
213
+ that can drift from it.
214
+ """
215
+ from formist_cli import api
216
+
217
+ post = post or api.post
218
+ body: dict[str, Any] = {"plan_token": plan_token, "groups": groups, "reason": reason}
219
+ if drop_data_keys:
220
+ body["drop_data_keys"] = drop_data_keys
221
+ return _plan(post(target, DEDUPE_PATH.format(space=space), body, token=token))
222
+
223
+
224
+ def render_plan(plan: dict, *, applying: bool = False, out=None) -> None:
225
+ """DESCRIBE only. Neither tier nor ``applying`` decides what merges: naming a
226
+ group with ``--group --reason --apply`` does. See :func:`render_review` for the
227
+ fuller per-row/per-field describe output.
228
+ """
229
+ out = out or sys.stdout
230
+ groups = plan.get("groups") or []
231
+ print(
232
+ f"{plan.get('live_participants')} live participant(s) | "
233
+ f"{plan.get('auto_mergeable', 0)} record-id group(s) | "
234
+ f"{plan.get('advisory', 0)} same-name group(s), advisory",
235
+ file=out,
236
+ )
237
+ for group in groups:
238
+ tier = group.get("tier")
239
+ label_tier = "record-id" if tier == "record_id" else "same-name"
240
+ print(
241
+ f" [{label_tier}] {group.get('key')} {group.get('label')!r}: "
242
+ f"suggests keeping {group.get('keep_id')}, dropping "
243
+ f"{len(group.get('drop_ids') or [])}",
244
+ file=out,
245
+ )
246
+ updates = group.get("updates") or {}
247
+ if updates:
248
+ print(f" would merge in: {', '.join(sorted(updates))}", file=out)
249
+ for conflict in group.get("conflicts") or []:
250
+ # Never folded into the summary count. A conflict is the reason a human
251
+ # is reading this, and a plan that reported "3 groups" while silently
252
+ # picking a side would be a check that cannot fail.
253
+ print(
254
+ f" CONFLICT {conflict.get('field')}: "
255
+ f"keeping {conflict.get('keeper')!r}, discarding "
256
+ f"{conflict.get('loser')!r} (from {conflict.get('loser_id')})",
257
+ file=out,
258
+ )
259
+ print(
260
+ f"\n{plan.get('rows_to_soft_delete', 0)} row(s) in a record-id group | "
261
+ f"plan_token {plan.get('plan_token')} (scoped to the groups printed above)\n"
262
+ "NOTHING HERE IS APPLIED. Pass --group <key> (repeatable) --reason "
263
+ "\"<why>\" --apply <plan_token> to merge exactly the groups you name.",
264
+ file=out,
265
+ )
266
+
267
+
268
+ def render_review(plan: dict, *, out=None) -> None:
269
+ """The full describe output, as markdown. Nothing here is a command to run:
270
+ it is what a human reads to decide which groups (if any) to name."""
271
+ out = out or sys.stdout
272
+ groups = plan.get("groups") or []
273
+ print(f"# participants dedupe, review ({len(groups)} duplicate group(s))\n", file=out)
274
+ if not groups:
275
+ print("no duplicate groups in this space (or in the --group scope given).", file=out)
276
+ return
277
+ for group in groups:
278
+ print(f"## [{group.get('tier')}] `{group.get('key')}`: {group.get('label')!r}\n", file=out)
279
+ suggestion = group.get("keeper_suggestion") or {}
280
+ print(
281
+ f"keeper SUGGESTION (not a decision): `{suggestion.get('id')}`: "
282
+ f"{suggestion.get('reason')}\n",
283
+ file=out,
284
+ )
285
+
286
+ rows = group.get("rows") or []
287
+ row_ids = [r.get("id") for r in rows]
288
+ print("| row id | created_at | created by | sessions | audit rows |", file=out)
289
+ print("|---|---|---|---|---|", file=out)
290
+ for row in rows:
291
+ by = row.get("created_by") or {}
292
+ who = by.get("source", "unknown")
293
+ actor = by.get("actor")
294
+ proposal = by.get("proposal_id")
295
+ if actor:
296
+ who = f"{who} ({actor}" + (f", proposal {proposal}" if proposal else "") + ")"
297
+ print(
298
+ f"| `{row.get('id')}` | {row.get('created_at')} | {who} | "
299
+ f"{row.get('session_participations', 0)} | {row.get('audit_history', 0)} |",
300
+ file=out,
301
+ )
302
+ print("", file=out)
303
+
304
+ fields = group.get("fields") or []
305
+ if fields and row_ids:
306
+ print("| field | " + " | ".join(f"`{rid}`" for rid in row_ids) + " | |", file=out)
307
+ print("|" + "---|" * (len(row_ids) + 2), file=out)
308
+ for f in fields:
309
+ values = f.get("values") or {}
310
+ cells = [
311
+ "-" if values.get(rid) in (None, "", []) else str(values.get(rid))
312
+ for rid in row_ids
313
+ ]
314
+ mark = "CONFLICT" if f.get("conflict") else "agree"
315
+ print(f"| {f.get('field')} | " + " | ".join(cells) + f" | {mark} |", file=out)
316
+ print("\n", file=out)
317
+
318
+
319
+ def render_outcomes(report: dict, *, out=None) -> None:
320
+ out = out or sys.stdout
321
+ print("\napplied:", file=out)
322
+ for outcome in report.get("outcomes") or []:
323
+ if outcome.get("error"):
324
+ print(f" ERROR {outcome.get('key')}: {outcome['error']}", file=out)
325
+ elif outcome.get("skipped"):
326
+ print(f" SKIP {outcome.get('key')}: {outcome['skipped']}", file=out)
327
+ else:
328
+ for gone in outcome.get("dropped_values") or []:
329
+ print(
330
+ f" dropped {gone.get('path')} = {gone.get('value')!r} "
331
+ "(kept on the soft-deleted row and in its audit snapshot)",
332
+ file=out,
333
+ )
334
+ refs = outcome.get("references_repointed") or {}
335
+ detail = ", ".join(f"{k}={v}" for k, v in sorted(refs.items())) or "no live references"
336
+ print(
337
+ f" OK {outcome.get('key')}: merged {outcome.get('merged')} into "
338
+ f"{outcome.get('keep_id')} ({detail})",
339
+ file=out,
340
+ )
341
+ print(
342
+ f"\n{report.get('live_participants')} live participant(s) remain | "
343
+ f"{report.get('auto_mergeable', 0)} record-id group(s) still duplicated",
344
+ file=out,
345
+ )
346
+
347
+
348
+ def cmd_participants(args) -> int:
349
+ from formist_cli.cli import _effective, _token_for
350
+
351
+ eff = _effective(args, for_write=bool(args.apply))
352
+ target, space = eff.target, eff.space
353
+ token = _token_for(eff)
354
+
355
+ plan = fetch_plan(target, space, token=token, groups=args.group)
356
+ if args.review and not args.json:
357
+ render_review(plan)
358
+ elif not args.json:
359
+ render_plan(plan, applying=bool(args.apply))
360
+ if not args.apply:
361
+ if args.json:
362
+ print(json.dumps(plan, indent=2))
363
+ elif plan.get("groups"):
364
+ print(
365
+ f"\n-> re-run with --group <key> (repeat) --reason \"<why>\" "
366
+ f"--apply {plan.get('plan_token')} --host <host> to merge exactly "
367
+ "the groups you name."
368
+ )
369
+ return 0
370
+
371
+ if args.apply != plan.get("plan_token"):
372
+ raise ParticipantsError(
373
+ "REFUSING TO APPLY: this is not the plan you were shown.\n"
374
+ f" you passed : {args.apply}\n"
375
+ f" plan now : {plan.get('plan_token')}\n"
376
+ "The duplicates changed between your dry run and this call (the "
377
+ "connector syncs every 30 minutes), or the --group scope differs "
378
+ "between the two calls. Read the plan above and apply that token "
379
+ "instead, with the same --group keys."
380
+ )
381
+ if not plan.get("groups"):
382
+ print("\nnothing to merge, no request was sent.")
383
+ return 0
384
+
385
+ report = submit(
386
+ target,
387
+ space,
388
+ args.apply,
389
+ token=token,
390
+ groups=args.group,
391
+ reason=args.reason,
392
+ drop_data_keys=parse_drops(args.drop),
393
+ )
394
+ if args.json:
395
+ print(json.dumps(report, indent=2))
396
+ return 0
397
+ render_outcomes(report)
398
+ failed = [o for o in report.get("outcomes") or [] if o.get("error")]
399
+ if failed:
400
+ print(f"\n{len(failed)} group(s) were NOT merged, see above.", file=sys.stderr)
401
+ return 1
402
+ return 0