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,200 @@
1
+ """``fm meeting`` - meeting-bot client operations: refresh a transcript, join now.
2
+
3
+ ``fm meeting transcript-refresh <task-id> --space <id>`` refreshes one
4
+ task's transcript through ``GET /projects/{id}/meetings/{task_id}/transcript``,
5
+ which already best-effort re-ingests before answering, so this command is
6
+ a bare client, not a re-implementation of the ingest logic. ``--all``
7
+ sweeps every task with a recording by listing meetings first
8
+ (``GET /projects/{id}/meetings``) and refreshing each one whose
9
+ ``has_recording`` is true.
10
+
11
+ ``fm meeting join <url> --space <id>`` classifies a pasted join URL
12
+ (Teams/Zoom/Meet) and dispatches an Attendee bot into it, through
13
+ ``POST /projects/{id}/meetings/join-now``. This can dispatch a real bot
14
+ into a live meeting, so it follows `fm`'s write convention: dry run by
15
+ default, ``--apply`` to actually do it.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import argparse
21
+ import json
22
+ import sys
23
+
24
+ from formist_cli import api, context
25
+ from formist_cli.cli_support import build_standalone_parser as _build_standalone_parser
26
+
27
+ SUBJECTS = ("transcript-refresh", "join")
28
+
29
+ #: Meetings the server considers "with a recording" carry no `bot_id` in the
30
+ #: list payload, only a `has_recording` flag; this is the field `--all`
31
+ #: filters on.
32
+ _LIST_PAGE_SIZE = 200
33
+
34
+
35
+ class MeetingsError(Exception):
36
+ """A refusal about the meeting surface, written for an operator."""
37
+
38
+
39
+ def _subject_error(subject: object) -> MeetingsError:
40
+ return MeetingsError(
41
+ f"unknown subcommand {subject!r}. Valid: {', '.join(SUBJECTS)}.\n"
42
+ " transcript-refresh <task-id> refresh + print one meeting's transcript\n"
43
+ " join <url> dispatch a bot into a join URL (WRITE)"
44
+ )
45
+
46
+
47
+ _DESCRIPTION = """Meeting-bot client operations.
48
+
49
+ fm meeting transcript-refresh <task-id> --space <id> refresh + print one transcript
50
+ fm meeting transcript-refresh --all --space <id> refresh every task with a bot
51
+ fm meeting join <url> --space <id> [--apply] dispatch a bot (WRITE; dry-run by default)
52
+ """
53
+
54
+
55
+ def add_parser(subparsers) -> argparse.ArgumentParser:
56
+ parser = subparsers.add_parser(
57
+ "meeting",
58
+ help="meeting-bot ops: refresh a transcript, join now (join is a WRITE)",
59
+ description=_DESCRIPTION,
60
+ formatter_class=argparse.RawDescriptionHelpFormatter,
61
+ )
62
+ _add_arguments(parser)
63
+ return parser
64
+
65
+
66
+ def _add_arguments(parser: argparse.ArgumentParser) -> None:
67
+ from formist_cli.cli import _add_env, _add_space
68
+
69
+ _add_env(parser, for_write=True)
70
+ _add_space(parser)
71
+ parser.add_argument("subject", help=f"one of: {', '.join(SUBJECTS)}")
72
+ parser.add_argument(
73
+ "arg", nargs="?", default=None,
74
+ help="transcript-refresh: a task id (UUID). join: the meeting URL.",
75
+ )
76
+ parser.add_argument(
77
+ "--all", action="store_true",
78
+ help="transcript-refresh: refresh every meeting with a recording, not just one",
79
+ )
80
+ parser.add_argument("--bot-name", dest="bot_name", default=None, help="join: override the bot's display name")
81
+ parser.add_argument(
82
+ "--summary-skill-id", dest="summary_skill_id", default=None,
83
+ help="join: skill id used to summarize the meeting afterwards",
84
+ )
85
+ parser.add_argument("--apply", action="store_true", help="join: perform the write (default: dry run)")
86
+ parser.add_argument("--json", action="store_true", help="raw JSON instead of a report")
87
+
88
+
89
+ def build_standalone_parser() -> argparse.ArgumentParser:
90
+ return _build_standalone_parser(add_parser)
91
+
92
+
93
+ # ===========================================================================
94
+ # transcript-refresh
95
+ # ===========================================================================
96
+ def _render_transcript(payload: dict) -> str:
97
+ lines = [f"file_id {payload.get('file_id')}", f"path {payload.get('path')}"]
98
+ text = payload.get("markdown") or ""
99
+ lines.append(f"markdown {len(text)} chars")
100
+ return "\n".join(lines)
101
+
102
+
103
+ def _refresh_one(ctx: context.Context, task_id: str) -> dict:
104
+ payload = api.get(ctx.target, f"/projects/{ctx.space}/meetings/{task_id}/transcript", token=ctx.token)
105
+ if not isinstance(payload, dict):
106
+ raise MeetingsError(
107
+ f"expected a JSON object from /meetings/{{id}}/transcript, got {type(payload).__name__}."
108
+ )
109
+ return payload
110
+
111
+
112
+ def _run_transcript_refresh(ctx: context.Context, args) -> int:
113
+ if args.all:
114
+ payload = api.get(
115
+ ctx.target, f"/projects/{ctx.space}/meetings", token=ctx.token,
116
+ params={"limit": str(_LIST_PAGE_SIZE)},
117
+ )
118
+ items = payload.get("items") if isinstance(payload, dict) else None
119
+ items = [i for i in (items or []) if isinstance(i, dict) and i.get("has_recording")]
120
+ if not items:
121
+ print("0 meeting(s) with a recording, nothing to refresh.")
122
+ return 0
123
+ print(f"refreshing {len(items)} meeting(s) with a recording:")
124
+ for item in items:
125
+ task_id = str(item["id"])
126
+ try:
127
+ refreshed = _refresh_one(ctx, task_id)
128
+ except api.ApiError as exc:
129
+ print(f"- {item.get('subject')} ({task_id}): FAILED: {exc}")
130
+ continue
131
+ print(f"- {item.get('subject')} ({task_id}): file_id={refreshed.get('file_id')}")
132
+ return 0
133
+
134
+ if not args.arg:
135
+ raise MeetingsError(
136
+ "`fm meeting transcript-refresh` needs a task id, or --all.\n"
137
+ "-> fm meeting transcript-refresh <task-id> --space <id>"
138
+ )
139
+ payload = _refresh_one(ctx, args.arg)
140
+ if args.json:
141
+ print(json.dumps(payload, indent=2, ensure_ascii=False))
142
+ else:
143
+ print(_render_transcript(payload))
144
+ return 0
145
+
146
+
147
+ # ===========================================================================
148
+ # join
149
+ # ===========================================================================
150
+ def _run_join(ctx: context.Context, args) -> int:
151
+ if not args.arg:
152
+ raise MeetingsError(
153
+ "`fm meeting join` needs a URL.\n-> fm meeting join <url> --space <id> [--apply]"
154
+ )
155
+ url = args.arg
156
+ body: dict = {"url": url}
157
+ if args.bot_name:
158
+ body["bot_name"] = args.bot_name
159
+ if args.summary_skill_id:
160
+ body["summary_skill_id"] = args.summary_skill_id
161
+
162
+ if not args.apply:
163
+ bot_name_note = f", bot_name={args.bot_name!r}" if args.bot_name else ""
164
+ print(
165
+ f"DRY RUN: nothing was changed.\n"
166
+ f"Would dispatch a bot into {url!r} in space {ctx.space} ({ctx.target.name})"
167
+ f"{bot_name_note}.\n"
168
+ f"To apply: re-run with --apply.",
169
+ file=sys.stderr,
170
+ )
171
+ return 0
172
+
173
+ payload = api.post(ctx.target, f"/projects/{ctx.space}/meetings/join-now", body, token=ctx.token)
174
+ if not isinstance(payload, dict):
175
+ raise MeetingsError(
176
+ f"expected a JSON object from /meetings/join-now, got {type(payload).__name__}."
177
+ )
178
+ if args.json:
179
+ print(json.dumps(payload, indent=2, ensure_ascii=False))
180
+ else:
181
+ task = payload.get("task") or {}
182
+ print(f"platform={payload.get('platform')} task_id={task.get('id')} subject={task.get('subject')}")
183
+ if payload.get("already_joined"):
184
+ print("bot already live for this meeting (no second bot dispatched)")
185
+ else:
186
+ print(f"bot_id={payload.get('bot_id')}")
187
+ if payload.get("dispatch_error"):
188
+ print(f"DISPATCH FAILED (task IS saved, fix and retry): {payload['dispatch_error']}")
189
+ return 2
190
+ return 0
191
+
192
+
193
+ def run(args) -> int:
194
+ subject = (getattr(args, "subject", None) or "").strip().lower()
195
+ if subject not in SUBJECTS:
196
+ raise _subject_error(getattr(args, "subject", None))
197
+ ctx = context.resolve(args, for_write=(subject == "join"), need_space=True, need_token=True)
198
+ if subject == "transcript-refresh":
199
+ return _run_transcript_refresh(ctx, args)
200
+ return _run_join(ctx, args)
@@ -0,0 +1,414 @@
1
+ """``fm messages`` - the group-mailbox message surface: duplicate cleanup
2
+ (``dedupe-scan`` / ``dedupe``) and the inline-image backfill
3
+ (``refresh-inline-images``).
4
+
5
+ GET /admin/messages/dedupe-scan read-only census, every OUTLOOK connection
6
+ POST /admin/messages/dedupe dry run unless --apply
7
+ POST /admin/spaces/{space_id}/messages/refresh-inline-images dry run unless --apply
8
+
9
+ What the duplicates are (dedupe-scan / dedupe): a race in the mailbox sync
10
+ could insert two rows for the same conversation when two scheduler runs
11
+ checked for an existing row concurrently. Every later sync pass then
12
+ updated whichever row came back first, and the other row froze where it
13
+ was. The race itself is fixed; `dedupe`/`dedupe-scan` is the cleanup for
14
+ what it already wrote.
15
+
16
+ `dedupe` writes when given --apply. It soft-deletes (`deleted_at` +
17
+ `deleted_by`), never hard-deletes, so clearing those two columns restores
18
+ every retired row, but it hides rows a user can see, and it leaves a
19
+ `platform_audit_log` entry either way.
20
+
21
+ Read first, then act. `dedupe-scan` is read-only and reports across every
22
+ connection, since the defect is architectural and applies to any project
23
+ with a group mailbox. Run it before authorising a write anywhere.
24
+
25
+ Region (dedupe/dedupe-scan): `message` and `connection` are region-local,
26
+ so `--env ae` for a real AE-region space. `--host evane` would read the
27
+ control plane's own database and honestly report zero.
28
+
29
+ What the inline-image backfill is (refresh-inline-images): Outlook
30
+ group-conversation posts reference inline images (a company logo,
31
+ social-media icons in a signature) as ``<img src="cid:...">``, a scheme a
32
+ browser cannot resolve on its own. The sync now rewrites those references
33
+ to ``data:`` URIs at sync time, but that only reaches a conversation the
34
+ next time it is actually re-synced. This backfill re-syncs already-stored
35
+ messages by their own remote_id, never by listing conversations, so it
36
+ also reaches a conversation the list endpoint has since gone quiet on.
37
+
38
+ Dry run by default for `refresh-inline-images` too; ``--apply`` flips it,
39
+ same convention as `dedupe`. Idempotent: a message whose body_html was
40
+ already rewritten (no more ``cid:``) is not a candidate on the next dry run.
41
+
42
+ ``api.admin_post``/``api.admin_get``, not the plain ``api`` client: this is
43
+ the Global-only ``/admin`` surface, same rule as ``fm i18n-backfill`` /
44
+ ``fm space-plan``.
45
+ """
46
+
47
+ from __future__ import annotations
48
+
49
+ import argparse
50
+ import json
51
+
52
+ from formist_cli import api, context
53
+ from formist_cli.cli_support import PLATFORM_ADMIN_GATE_NOTE, add_admin_flag
54
+ from formist_cli.cli_support import build_standalone_parser as _build_standalone_parser
55
+ from formist_cli.targets import require_space_id
56
+
57
+ SUBJECTS = ("dedupe-scan", "dedupe", "refresh-inline-images")
58
+ DEFAULT_SUBJECT = "dedupe-scan"
59
+
60
+ SCAN_ENDPOINT = "/admin/messages/dedupe-scan"
61
+ DEDUPE_ENDPOINT = "/admin/messages/dedupe"
62
+ REFRESH_INLINE_IMAGES_ENDPOINT = "/admin/spaces/{space}/messages/refresh-inline-images"
63
+
64
+
65
+ class MessagesError(Exception):
66
+ """A refusal about this surface, written for an operator."""
67
+
68
+
69
+ def canonical_subject(subject: str | None) -> str:
70
+ if subject is None:
71
+ return DEFAULT_SUBJECT
72
+ value = subject.strip().lower()
73
+ if value not in SUBJECTS:
74
+ raise MessagesError(
75
+ f"unknown subcommand {subject!r}. Valid: {', '.join(SUBJECTS)}."
76
+ )
77
+ return value
78
+
79
+
80
+ # ===========================================================================
81
+ # Rendering - dedupe-scan / dedupe
82
+ # ===========================================================================
83
+ def render_scan(payload: dict) -> str:
84
+ lines = [
85
+ f"OUTLOOK connections: {payload.get('connections', 0)}"
86
+ f" with duplicates: {payload.get('connections_with_duplicates', 0)}",
87
+ f"duplicate groups: {payload.get('groups', 0)}"
88
+ f" rows a dedupe would retire: {payload.get('rows_to_soft_delete', 0)}",
89
+ "",
90
+ ]
91
+ rows = payload.get("detail") or []
92
+ if not rows:
93
+ return "\n".join(lines) + "no OUTLOOK connections on this instance."
94
+ lines.append(f"{'connection':38s} {'groups':>7s} {'in groups':>10s} {'retire':>7s}")
95
+ for row in rows:
96
+ lines.append(
97
+ f"{row.get('connection_id', ''):38s} {row.get('groups', 0):7d} "
98
+ f"{row.get('rows_in_groups', 0):10d} {row.get('rows_to_soft_delete', 0):7d}"
99
+ )
100
+ return "\n".join(lines)
101
+
102
+
103
+ def render_dedupe(payload: dict) -> str:
104
+ applied = bool(payload.get("applied"))
105
+ head = "APPLIED" if applied else "DRY RUN: nothing was written"
106
+ lines = [
107
+ f"{head} connection={payload.get('connection_id')}",
108
+ f"groups={payload.get('groups', 0)} rows in groups={payload.get('rows_in_groups', 0)}"
109
+ f" rows to retire={payload.get('rows_to_soft_delete', 0)}",
110
+ "",
111
+ "dependents of the rows that would be retired:",
112
+ ]
113
+ for key, value in (payload.get("dependents") or {}).items():
114
+ lines.append(f" {key:28s} {value}")
115
+ lines.append("")
116
+ for group in payload.get("detail") or []:
117
+ lines.append(f" {group.get('remote_id')}")
118
+ lines.append(
119
+ f" KEEP {group.get('keep')} last_synced={group.get('keep_last_synced_at')}"
120
+ )
121
+ # strict=True on purpose: the two lists are built from the same loop
122
+ # server-side, and a length mismatch would mean the plan is describing
123
+ # a row it did not measure. Better a traceback than a report that
124
+ # silently drops the last dropped row.
125
+ for row_id, synced in zip(
126
+ group.get("drop") or [],
127
+ group.get("drop_last_synced_at") or [],
128
+ strict=True,
129
+ ):
130
+ lines.append(f" drop {row_id} last_synced={synced}")
131
+ if not applied and payload.get("plan_token"):
132
+ lines.append("")
133
+ lines.append(
134
+ f"plan token: {payload['plan_token']} (quote it back: "
135
+ f"--plan-token {payload['plan_token']})"
136
+ )
137
+ lines.append(
138
+ " it fingerprints the keep/drop of the group(s) you "
139
+ "named. A sync tick"
140
+ )
141
+ lines.append(
142
+ " that makes a DIFFERENT row the keeper changes it, and "
143
+ "the apply is refused 409."
144
+ )
145
+ if applied:
146
+ lines.append("")
147
+ lines.append(f"reason: {payload.get('reason')!r}")
148
+ lines.append(f"groups applied: {payload.get('groups_applied')}")
149
+ if payload.get("groups_skipped"):
150
+ lines.append(
151
+ f"groups NOT named (left alone, pass --group to include): "
152
+ f"{payload.get('groups_skipped')}"
153
+ )
154
+ if payload.get("unknown_groups"):
155
+ lines.append(
156
+ f"requested groups that are not currently duplicates (already "
157
+ f"merged, or a mistyped remote_id): {payload.get('unknown_groups')}"
158
+ )
159
+ lines.append(f"soft-deleted: {payload.get('soft_deleted', 0)}")
160
+ lines.append(f"re-pointed: {payload.get('repointed')}")
161
+ conflicts = payload.get("status_point_conflicts") or 0
162
+ if conflicts:
163
+ lines.append(
164
+ f"status points NOT re-pointed (the keeper already has one at that "
165
+ f"stage): {conflicts}"
166
+ )
167
+ return "\n".join(lines)
168
+
169
+
170
+ # ===========================================================================
171
+ # Rendering - refresh-inline-images
172
+ # ===========================================================================
173
+ def render_refresh_inline_images(payload: dict) -> str:
174
+ """The report. Target and mode first, then whatever this run's shape carries."""
175
+ target = payload.get("target") or {}
176
+ lines = [
177
+ f"space {target.get('space_name') or '?'} ({target.get('space_id')})",
178
+ f"project {target.get('project_name') or '?'} ({target.get('project_id')})",
179
+ f"region {target.get('region')} (resolved by the server from the "
180
+ "Global space registry, not from --env)",
181
+ "",
182
+ f"mode {'DRY RUN (writes nothing)' if payload.get('dry_run') else 'APPLIED'}",
183
+ f"connections {payload.get('connections', 0)} OUTLOOK connection(s) in this space",
184
+ f"candidates {payload.get('candidates', 0)} message(s) with a dangling cid:",
185
+ ]
186
+
187
+ if payload.get("dry_run"):
188
+ samples = payload.get("sample_remote_ids") or []
189
+ if samples:
190
+ lines += ["", "sample remote_ids (up to 20):"]
191
+ lines += [f" {rid}" for rid in samples]
192
+ lines += ["", "NOTHING WAS WRITTEN. To run exactly this:",
193
+ " " + next_command(payload)]
194
+ else:
195
+ lines += [
196
+ "",
197
+ f"refreshed {payload.get('refreshed', 0)}",
198
+ f"unchanged {payload.get('unchanged', 0)}",
199
+ f"gone {payload.get('gone', 0)} "
200
+ "(conversation no longer resolves by id)",
201
+ f"errors {payload.get('errors', 0)}",
202
+ ]
203
+ return "\n".join(lines)
204
+
205
+
206
+ def next_command(payload: dict) -> str:
207
+ """The exact command that applies what a dry run just showed."""
208
+ target = payload.get("target") or {}
209
+ return (
210
+ f"fm messages refresh-inline-images --env <env> "
211
+ f"--space {target.get('space_id')} --apply"
212
+ )
213
+
214
+
215
+ # ===========================================================================
216
+ # CLI
217
+ # ===========================================================================
218
+ def _add_arguments(parser: argparse.ArgumentParser) -> None:
219
+ parser.add_argument(
220
+ "subject",
221
+ nargs="?",
222
+ help=f"one of: {', '.join(SUBJECTS)} (default: {DEFAULT_SUBJECT})",
223
+ )
224
+ parser.add_argument(
225
+ "--host",
226
+ default=argparse.SUPPRESS,
227
+ metavar="HOST",
228
+ help="deployment name or API origin (default: formist, or `fm use` for reads); "
229
+ "a write never inherits it",
230
+ )
231
+ parser.add_argument(
232
+ "--connection",
233
+ default=None,
234
+ help="the OUTLOOK connection id to dedupe (required for `dedupe`)",
235
+ )
236
+ parser.add_argument(
237
+ "--space",
238
+ default=None,
239
+ help="space UUID, never a name (required for `refresh-inline-images`)",
240
+ )
241
+ parser.add_argument(
242
+ "--limit",
243
+ type=int,
244
+ default=None,
245
+ help="`refresh-inline-images` only: cap how many candidate messages a "
246
+ "REAL run re-syncs in one call",
247
+ )
248
+ parser.add_argument(
249
+ "--group",
250
+ action="append",
251
+ default=None,
252
+ metavar="REMOTE_ID",
253
+ help="`dedupe` only: a duplicate group's remote_id (as printed by the "
254
+ "dry run), repeatable. REQUIRED under --apply, no whole-connection "
255
+ "apply. Ignored on a dry run",
256
+ )
257
+ parser.add_argument(
258
+ "--reason",
259
+ default=None,
260
+ metavar="TEXT",
261
+ help="`dedupe` only: REQUIRED under --apply, one sentence saying why "
262
+ "the named group(s) are the same duplicate cluster. Becomes the audit "
263
+ "row's explanation",
264
+ )
265
+ parser.add_argument(
266
+ "--plan-token",
267
+ default=None,
268
+ metavar="TOKEN",
269
+ help="`dedupe` only: REQUIRED under --apply, the `plan token` the dry "
270
+ "run printed for the SAME --group keys. The server recomputes it from "
271
+ "live rows and refuses (409) if a sync tick has changed which row would "
272
+ "be kept. Ignored on a dry run",
273
+ )
274
+ parser.add_argument(
275
+ "--apply",
276
+ action="store_true",
277
+ help="actually write (retire duplicate rows / re-sync candidates); "
278
+ "without it this is a dry run",
279
+ )
280
+ parser.add_argument("--json", action="store_true", help="raw JSON instead of a report")
281
+
282
+
283
+ _HELP = "group-mailbox messages: duplicate cleanup + the inline-image backfill (admin)"
284
+
285
+ _DESCRIPTION = """Two admin surfaces over the group-mailbox `message` table:
286
+
287
+ fm messages dedupe-scan --env ae read-only, every connection
288
+ fm messages dedupe --env ae --connection <id> dry run for one connection
289
+ fm messages dedupe --env ae --connection <id> \\
290
+ --group <remote_id> [--group <remote_id> ...] \\
291
+ --reason "<why these are the same conversation>" \\
292
+ --plan-token <token from the dry run> --apply merge exactly those groups
293
+
294
+ fm messages refresh-inline-images --env ae --space <uuid> dry run
295
+ fm messages refresh-inline-images --env ae --space <uuid> --apply the real run
296
+
297
+ dedupe / dedupe-scan: find and collapse the duplicate `message` rows a
298
+ mailbox sync race produced. Keep rule: per (connection, remote
299
+ conversation) the row with the newest last_synced_at survives (ties break
300
+ on the lowest id), the same rule the sync itself now uses to pick which
301
+ row to update, so the two cannot disagree. Losers are SOFT-deleted
302
+ (deleted_at + deleted_by). Clearing those two columns restores them.
303
+ Proposal/comment/status-point rows that named a retired row are
304
+ re-pointed at the survivor; audit and metering rows are deliberately left
305
+ alone. Region-local data: use --env ae for a real AE-region space, not
306
+ --host evane.
307
+
308
+ NO WHOLE-CONNECTION APPLY. --apply merges only the groups named by --group
309
+ (repeatable, the remote_id the dry run printed), and needs --reason: one
310
+ sentence saying why the named group(s) are the same duplicate cluster.
311
+ `--apply` with no --group, an empty list, or a wildcard is refused 422.
312
+ The dry run still describes every group in the connection regardless,
313
+ only the write is scoped.
314
+
315
+ refresh-inline-images: re-embed inline images (company logo, social
316
+ icons) in already-synced messages whose body_html still carries a
317
+ dangling `cid:`, by re-syncing each one by its own remote_id (never by
318
+ listing conversations), through the same idempotent upsert path a normal
319
+ sync uses.
320
+ """
321
+
322
+
323
+ def add_parser(subparsers) -> argparse.ArgumentParser:
324
+ parser = subparsers.add_parser(
325
+ "messages",
326
+ help=_HELP,
327
+ description=_DESCRIPTION,
328
+ epilog=PLATFORM_ADMIN_GATE_NOTE,
329
+ formatter_class=argparse.RawDescriptionHelpFormatter,
330
+ )
331
+ _add_arguments(parser)
332
+ add_admin_flag(parser)
333
+ return parser
334
+
335
+
336
+ def build_standalone_parser() -> argparse.ArgumentParser:
337
+ return _build_standalone_parser(add_parser)
338
+
339
+
340
+ def _run_dedupe_scan(args) -> int:
341
+ ctx = context.resolve(args, need_token=True)
342
+ payload = api.admin_get(ctx.target, SCAN_ENDPOINT, token=ctx.token)
343
+ if not isinstance(payload, dict):
344
+ raise MessagesError(f"{SCAN_ENDPOINT} returned a non-object response: {payload!r}")
345
+ print(json.dumps(payload, indent=2, ensure_ascii=False) if args.json else render_scan(payload))
346
+ return 0
347
+
348
+
349
+ def _run_dedupe(args) -> int:
350
+ connection = (getattr(args, "connection", None) or "").strip()
351
+ if not connection:
352
+ raise MessagesError(
353
+ "`fm messages dedupe` needs --connection <id>. There is deliberately no "
354
+ "all-connections apply: run `fm messages dedupe-scan` first and act on "
355
+ "one measured blast radius at a time."
356
+ )
357
+ # for_write=True even for the dry run. `context.resolve(for_write=True)` is
358
+ # what refuses to inherit the target from `fm use`, and a command that can
359
+ # write must never pick its environment from a remembered preference, not
360
+ # even on the run that happens not to write. One flag decides whether this
361
+ # is production.
362
+ ctx = context.resolve(args, for_write=True, need_token=True)
363
+ body: dict = {"connection_id": connection, "apply": bool(args.apply)}
364
+ if args.apply:
365
+ # Forwarded as-given, including None/empty: the server is the one
366
+ # place that refuses (422) a missing/empty/wildcard `groups` or a
367
+ # blank `reason`. Duplicating that check here would be a second
368
+ # copy of a rule the server already owns.
369
+ body["groups"] = getattr(args, "group", None)
370
+ body["reason"] = getattr(args, "reason", None)
371
+ # Forwarded as-given for the same reason as the two above: the server
372
+ # recomputes the token from live rows and is the one place that refuses
373
+ # (409 `plan-stale`). A client-side "did you pass one?" check here would
374
+ # be a second copy of a rule the server already owns, and the client
375
+ # cannot compute the token anyway, which is the whole point of it.
376
+ body["plan_token"] = getattr(args, "plan_token", None)
377
+ payload = api.admin_post(ctx.target, DEDUPE_ENDPOINT, body, token=ctx.token)
378
+ if not isinstance(payload, dict):
379
+ raise MessagesError(f"{DEDUPE_ENDPOINT} returned a non-object response: {payload!r}")
380
+ print(json.dumps(payload, indent=2, ensure_ascii=False) if args.json else render_dedupe(payload))
381
+ return 0
382
+
383
+
384
+ def _run_refresh_inline_images(args) -> int:
385
+ # for_write on BOTH paths, same rule as `fm i18n-backfill` / `fm messages
386
+ # dedupe`: a dry run of a command whose whole subject is a prod write
387
+ # should resolve its environment the same way --apply will.
388
+ ctx = context.resolve(args, for_write=True, need_space=True, need_token=True)
389
+ space = require_space_id(str(ctx.space))
390
+ path = REFRESH_INLINE_IMAGES_ENDPOINT.format(space=space)
391
+
392
+ body: dict = {"dry_run": not bool(args.apply)}
393
+ if getattr(args, "limit", None) is not None:
394
+ body["limit"] = args.limit
395
+
396
+ payload = api.admin_post(ctx.target, path, body, token=ctx.token)
397
+ if not isinstance(payload, dict):
398
+ raise MessagesError(
399
+ f"{REFRESH_INLINE_IMAGES_ENDPOINT} returned a non-object response: {payload!r}"
400
+ )
401
+ if args.json:
402
+ print(json.dumps(payload, indent=2, ensure_ascii=False))
403
+ return 0
404
+ print(render_refresh_inline_images(payload))
405
+ return 0
406
+
407
+
408
+ def run(args) -> int:
409
+ subject = canonical_subject(getattr(args, "subject", None))
410
+ if subject == "dedupe-scan":
411
+ return _run_dedupe_scan(args)
412
+ if subject == "dedupe":
413
+ return _run_dedupe(args)
414
+ return _run_refresh_inline_images(args)