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.
formist_cli/doctor.py ADDED
@@ -0,0 +1,128 @@
1
+ """``fm doctor``: one readable answer to "is the deployment all right".
2
+
3
+ ``fm health`` answers about one environment and is the machine-shaped
4
+ command. ``doctor`` answers across all of them, so it has to survive
5
+ the ones that do not answer at all.
6
+
7
+ "could not reach ae" and "reached ae and it is unhealthy" are
8
+ different facts with different next actions, so :class:`Status` keeps
9
+ UNREACHABLE, DEGRADED and FAILED separate, and an unexpected payload
10
+ shape is its own status rather than a pass: a legacy deployment can
11
+ still answer ``200`` with an older health schema (``{"status": "ok"}``
12
+ and no ``checks``), and treating that as OK would hide a stale
13
+ deployment behind a green tick.
14
+
15
+ Stdlib only.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from dataclasses import dataclass
21
+ from enum import IntEnum
22
+
23
+
24
+ class Status(IntEnum):
25
+ """Ordered worst-last, so :meth:`worst` is a max."""
26
+
27
+ OK = 0
28
+ UNKNOWN = 1
29
+ DEGRADED = 2
30
+ FAILED = 3
31
+ UNREACHABLE = 4
32
+
33
+ @classmethod
34
+ def worst(cls, statuses) -> Status:
35
+ return max(statuses, default=cls.OK)
36
+
37
+ @property
38
+ def glyph(self) -> str:
39
+ return {
40
+ Status.OK: "ok",
41
+ Status.UNKNOWN: "??",
42
+ Status.DEGRADED: "!!",
43
+ Status.FAILED: "XX",
44
+ Status.UNREACHABLE: "--",
45
+ }[self]
46
+
47
+
48
+ @dataclass(frozen=True)
49
+ class EnvReport:
50
+ """One environment's answer, and why it is what it is."""
51
+
52
+ env: str
53
+ status: Status
54
+ detail: str
55
+ #: Alembic identity, when ``/admin/instance`` was reachable and authorised.
56
+ migrations: str | None = None
57
+ #: Whether a usable credential is stored for this environment.
58
+ credential: str | None = None
59
+
60
+ @classmethod
61
+ def unreachable(cls, env: str, reason: str) -> EnvReport:
62
+ return cls(env=env, status=Status.UNREACHABLE, detail=reason)
63
+
64
+ @classmethod
65
+ def from_health(cls, env: str, payload: object) -> EnvReport:
66
+ """Read a ``/health`` body.
67
+
68
+ A payload that is not the current schema is UNKNOWN, never OK:
69
+ a familiar-looking 200 is not evidence by itself.
70
+ """
71
+ if not isinstance(payload, dict):
72
+ return cls(
73
+ env=env,
74
+ status=Status.UNKNOWN,
75
+ detail=(
76
+ f"/health returned {type(payload).__name__}, not the current "
77
+ "schema (expected an object with checked_at + checks)."
78
+ ),
79
+ )
80
+
81
+ checks = payload.get("checks")
82
+ if not isinstance(checks, list):
83
+ return cls(
84
+ env=env,
85
+ status=Status.UNKNOWN,
86
+ detail=(
87
+ "/health has no `checks` list, which is the legacy schema. "
88
+ "The current build returns checked_at + checks, so this is "
89
+ "an older deployment."
90
+ ),
91
+ )
92
+
93
+ bad = [c for c in checks if isinstance(c, dict) and c.get("status") != "ok"]
94
+ if not bad:
95
+ return cls(
96
+ env=env,
97
+ status=Status.OK,
98
+ detail=f"{len(checks)} check{'s' if len(checks) != 1 else ''} ok",
99
+ )
100
+
101
+ fatal = [c for c in bad if c.get("fatal")]
102
+ named = ", ".join(
103
+ f"{c.get('name')}={c.get('status')}"
104
+ + (f" ({c.get('detail')})" if c.get("detail") else "")
105
+ for c in bad
106
+ )
107
+ return cls(
108
+ env=env,
109
+ status=Status.FAILED if fatal else Status.DEGRADED,
110
+ detail=named,
111
+ )
112
+
113
+
114
+ def rollup(reports) -> str:
115
+ """Render every report, including the ones that failed.
116
+
117
+ Every environment appears. A rollup that stops at the first failure answers a
118
+ different question than the one asked, and one region being down is exactly
119
+ when the others matter most.
120
+ """
121
+ lines = []
122
+ for report in reports:
123
+ lines.append(f" [{report.status.glyph}] {report.env:<8} {report.detail}")
124
+ if report.migrations:
125
+ lines.append(f" migrations: {report.migrations}")
126
+ if report.credential:
127
+ lines.append(f" credential: {report.credential}")
128
+ return "\n".join(lines)
formist_cli/export.py ADDED
@@ -0,0 +1,427 @@
1
+ """``fm export`` - two different exports, one of which is a write.
2
+
3
+ The two routes are not the same kind of thing. ``GET /projects/{id}/export``
4
+ is a read: one JSON bundle, open to any member regardless of role, so a
5
+ viewer reaches it.
6
+
7
+ ``POST /projects/{id}/export/bundle`` is a write. It inserts a File row
8
+ under Files > Exports, writes blob bytes into storage, and emits an
9
+ export event. Every member sees the artefact afterwards. It is
10
+ owner/admin only, and the download shares that tier, because gating the
11
+ build while leaving the download open would let a viewer exfiltrate the
12
+ entire workspace with nothing but the file id.
13
+
14
+ A command called "export" reads as a read on both halves, which is
15
+ exactly how the second one gets run against the wrong environment. So the
16
+ bundle half goes through ``for_write=True`` in the CLI and can never
17
+ inherit ``fm use``'s environment.
18
+
19
+ What the GDPR bundle contains, and the scoping caveat, is stated here and
20
+ in ``--help`` because ``--help`` is the only place an operator looks
21
+ before running it.
22
+
23
+ The bundle carries every project-scoped table plus a members roster with
24
+ email addresses and a files manifest (names, paths, web_urls). Secrets
25
+ are scrubbed: connection credentials redacted, API-token hashes dropped.
26
+
27
+ On some deployments the per-member scoping of four of those tables (chat
28
+ transcripts, personal notifications, audit before/after snapshots, and
29
+ document_index.markdown_text) is wider than the per-member access the
30
+ rest of the product enforces: any member, viewer included, can reach all
31
+ four through this route, which never mentions them. The operator who ran
32
+ this needs to know what they just downloaded; a file on disk outlives
33
+ the release note, so :data:`SCOPING_NOTE` is printed every time.
34
+
35
+ A file-writing command can lie in three ways. It can overwrite something
36
+ (unrecoverable, and looks like success). It can write nothing and print a
37
+ path, and an empty export file is that failure with a different noun. Or
38
+ it can write somewhere else, because the filename came from the server's
39
+ ``Content-Disposition`` and a path separator in it is a path nobody chose.
40
+
41
+ All three are refusals below rather than cautions. Nothing else in `fm`
42
+ takes a filename out of a response, so nothing else is watching that
43
+ last one.
44
+
45
+ Stdlib only: `fm` must add no runtime dependency.
46
+ """
47
+
48
+ from __future__ import annotations
49
+
50
+ import re
51
+ import sys
52
+ from dataclasses import dataclass
53
+ from pathlib import Path
54
+ from urllib.parse import unquote
55
+
56
+ from formist_cli import api, context
57
+
58
+ #: What the GDPR bundle carries, for `--help`. Kept as data rather than prose in
59
+ #: one f-string so the list cannot drift out of the help text silently.
60
+ BUNDLE_CONTENTS = (
61
+ "every project-scoped table (stakeholders, sessions, tasks, files, entities...)",
62
+ "a MEMBERS ROSTER including email addresses",
63
+ "a files manifest: names, paths, web_urls",
64
+ "chat transcripts, notifications, audit snapshots, document text",
65
+ )
66
+
67
+ SCOPING_NOTE = (
68
+ "PERSONAL DATA. The per-member scoping of chats, notifications, audit "
69
+ "before/after snapshots and document_index.markdown_text can be wider than "
70
+ "the rest of the product enforces: any member, VIEWER included, may be able "
71
+ "to export all four on some deployments. The file you just wrote may "
72
+ "contain other people's private data and the full text of restricted "
73
+ "documents. Check what you are about to share it with."
74
+ )
75
+
76
+
77
+ class ExportError(Exception):
78
+ """A refusal about an export, written for an operator."""
79
+
80
+
81
+ @dataclass(frozen=True)
82
+ class Written:
83
+ """Where the bytes actually landed. Reported instead of where they were aimed."""
84
+
85
+ path: Path
86
+ bytes_written: int
87
+
88
+
89
+ def filename_from_disposition(header: str | None) -> str | None:
90
+ """The filename out of a ``Content-Disposition``, or ``None``.
91
+
92
+ ``None`` rather than a guess: a caller that cannot tell what the server called
93
+ the file should fall back deliberately, not be handed an invention that looks
94
+ like it came from the response.
95
+ """
96
+ if not header:
97
+ return None
98
+ # RFC 5987 `filename*=UTF-8''%E5%90%88...` wins: it is the only form that can
99
+ # carry a Chinese or Arabic name, and read as a plain value it came out as the
100
+ # literal "UTF-8''%E5%90%88..." on disk.
101
+ extended = re.search(r"filename\*\s*=\s*([^';]+)'[^']*'([^;]+)", header, re.IGNORECASE)
102
+ if extended:
103
+ charset, encoded = extended.group(1).strip(), extended.group(2).strip()
104
+ try:
105
+ name = unquote(encoded, encoding=charset or "utf-8", errors="strict").strip()
106
+ except (LookupError, UnicodeDecodeError):
107
+ name = ""
108
+ if name:
109
+ return name
110
+ match = re.search(r'(?<![*\w])filename\s*=\s*(?:"([^"]+)"|([^;]+))', header, re.IGNORECASE)
111
+ if not match:
112
+ return None
113
+ name = (match.group(1) or match.group(2) or "").strip()
114
+ return name or None
115
+
116
+
117
+ def safe_filename(name: str | None) -> str:
118
+ """The bare filename, with any path the server supplied stripped off.
119
+
120
+ ``Content-Disposition`` names a file. It never names a path, and a server
121
+ that puts one there (compromised, buggy, or proxied) must not be able to
122
+ choose where an operator's bytes land. ``os.path.basename`` semantics,
123
+ applied to both separators because a response is not necessarily produced
124
+ on this platform.
125
+ """
126
+ if not name:
127
+ raise ExportError("the server supplied no usable filename.")
128
+ bare = name.replace("\\", "/").rsplit("/", 1)[-1].strip()
129
+ # `..` survives basename(): it is a valid final segment, so it is rejected
130
+ # explicitly rather than assumed away.
131
+ if not bare or bare in {".", ".."}:
132
+ raise ExportError(
133
+ f"refusing the server-supplied filename {name!r}: it names a path, "
134
+ "not a file.\n-> Pass `-o <path>` to choose the destination yourself."
135
+ )
136
+ return bare
137
+
138
+
139
+ def write_export(path: Path, data: bytes) -> Written:
140
+ """Write ``data`` to ``path``, refusing to overwrite and refusing to write nothing.
141
+
142
+ The empty check comes first, so a zero-byte response cannot leave a file
143
+ behind. If it did, the refusal would create the very file the next run
144
+ then refuses to overwrite, a failed export that permanently blocks the
145
+ retry.
146
+ """
147
+ path = Path(path)
148
+ if not data:
149
+ raise ExportError(
150
+ f"the server returned 0 bytes, nothing was written to {path}.\n"
151
+ "An empty export file is indistinguishable from a successful one on "
152
+ "disk, so this is a refusal rather than a warning.\n"
153
+ "-> Check `fm health` and that the space id is right."
154
+ )
155
+ if path.exists():
156
+ raise ExportError(
157
+ f"refusing to overwrite {path}.\n"
158
+ "An export is a point-in-time copy and replacing one silently is not "
159
+ "recoverable.\n"
160
+ "-> Move or delete it, or pass `-o <other path>`."
161
+ )
162
+ path.parent.mkdir(parents=True, exist_ok=True)
163
+ path.write_bytes(data)
164
+ return Written(path=path, bytes_written=len(data))
165
+
166
+
167
+ def destination(out: str | None, server_filename: str | None, fallback: str) -> Path:
168
+ """Where to write: ``-o`` wins, then the server's name, then ``fallback``.
169
+
170
+ ``-o`` pointing at a DIRECTORY keeps the server's filename inside it, because
171
+ ``fm export -o ~/exports`` obviously means "put it there", and silently
172
+ creating a file literally named ``exports`` would be a surprising reading of an
173
+ unambiguous instruction.
174
+ """
175
+ name = safe_filename(server_filename) if server_filename else fallback
176
+ if out is None:
177
+ return Path(name)
178
+ chosen = Path(out).expanduser()
179
+ if chosen.is_dir():
180
+ return chosen / name
181
+ return chosen
182
+
183
+
184
+ def precheck_out(out: str | None) -> None:
185
+ """Refuse an occupied ``-o`` destination before anything is built server-side.
186
+
187
+ ``write_export`` already refuses to overwrite, but it runs at the end,
188
+ and for ``--bundle`` the end is after a POST that has already inserted
189
+ a File row, written blob bytes and emitted an export event. So a
190
+ mistyped ``-o`` would leave a real artefact in the space that the
191
+ operator then cannot receive, and the only way to "fix" it is another
192
+ build, i.e. another row.
193
+
194
+ Only possible when ``-o`` names a file: with no ``-o``, or with a
195
+ directory, the destination is not known until the server says what it
196
+ called the bundle. That is why this is a pre-check in addition to, and
197
+ not instead of, the one in :func:`write_export`.
198
+ """
199
+ if out is None:
200
+ return
201
+ chosen = Path(out).expanduser()
202
+ if chosen.is_dir():
203
+ return
204
+ if chosen.exists():
205
+ raise ExportError(
206
+ f"refusing to overwrite {chosen}.\n"
207
+ "Checked BEFORE building: --bundle creates a File row in the space, "
208
+ "so failing after the build would leave an artefact behind that you "
209
+ "could not download.\n"
210
+ "-> Move or delete it, or pass a different `-o`."
211
+ )
212
+
213
+
214
+ def render_bundle_report(response: object) -> str:
215
+ """Describe what the server said it built. Takes only the response.
216
+
217
+ The request is not a parameter, so it cannot be echoed: a report
218
+ assembled from the options that were requested would confirm whatever
219
+ was asked for rather than whatever happened.
220
+
221
+ ``missing_blobs`` is reported even though it is the unflattering number. A
222
+ bundle with blobs it could not fetch is incomplete, and printing the counts
223
+ while omitting the holes describes an incomplete export as a whole one.
224
+ """
225
+ if not isinstance(response, dict):
226
+ return str(response)
227
+
228
+ lines: list[str] = []
229
+ if response.get("filename"):
230
+ lines.append(f"filename {response['filename']}")
231
+ if response.get("file_id"):
232
+ lines.append(f"file_id {response['file_id']}")
233
+
234
+ manifest = response.get("manifest")
235
+ if isinstance(manifest, dict):
236
+ if manifest.get("source_project_name"):
237
+ lines.append(f"space {manifest['source_project_name']}")
238
+ if manifest.get("bundle_id"):
239
+ lines.append(f"bundle_id {manifest['bundle_id']}")
240
+ options = manifest.get("options")
241
+ if isinstance(options, dict):
242
+ enabled = sorted(k for k, v in options.items() if v)
243
+ lines.append(f"options {', '.join(enabled) if enabled else '(defaults)'}")
244
+ # `classes` is a list of {name, file, count} dicts on the wire, not a
245
+ # dict of name->count: treating it as the latter silently skips the
246
+ # most useful part of the report, the per-class row counts.
247
+ classes = manifest.get("classes")
248
+ if isinstance(classes, list) and classes:
249
+ lines.append(f"classes {len(classes)}")
250
+ for entry in classes:
251
+ if isinstance(entry, dict):
252
+ lines.append(
253
+ f" {str(entry.get('name', '?')):<28} {entry.get('count')}"
254
+ )
255
+ elif classes is not None:
256
+ # Present but not the shape we know. Saying so beats skipping: a
257
+ # silently omitted section reads as "the bundle had none of that",
258
+ # which is how the wrong shape stayed invisible the first time.
259
+ lines.append(
260
+ f"classes (unrecognised shape: {type(classes).__name__}, "
261
+ "the report cannot summarise it; read manifest.json in the zip)"
262
+ )
263
+ blobs = manifest.get("blobs")
264
+ if isinstance(blobs, dict):
265
+ lines.append(
266
+ f"blobs {blobs.get('count')} "
267
+ f"({blobs.get('total_bytes')} bytes)"
268
+ )
269
+ missing = manifest.get("missing_blobs")
270
+ if missing:
271
+ lines.append(
272
+ f"{len(missing)} MISSING blob(s): this bundle is incomplete "
273
+ "and will not round-trip:"
274
+ )
275
+ for item in missing:
276
+ lines.append(f" {item}")
277
+ return "\n".join(lines)
278
+
279
+
280
+ # ===========================================================================
281
+ # The CLI surface. Per-module `add_parser`: adding a command costs the
282
+ # top-level parser one line instead of a block two branches both land in.
283
+ # ===========================================================================
284
+ def add_parser(sub) -> None:
285
+ import argparse
286
+
287
+ from formist_cli.cli import _add_env, _add_space
288
+ p = sub.add_parser(
289
+ "export",
290
+ help="download a space's data bundle to a file",
291
+ description=(
292
+ "TWO different exports, and only the first is a read.\n\n"
293
+ " (default) GET /projects/{id}/export, the GDPR Article 20 JSON "
294
+ "bundle. Any MEMBER may run it, VIEWER included.\n"
295
+ " --bundle POST /projects/{id}/export/bundle, the round-trip ZIP "
296
+ "with blob bytes. OWNER/ADMIN.\n\n"
297
+ "--bundle is a WRITE. It inserts a File row, writes blob bytes "
298
+ "into the space's storage and emits an export event; every "
299
+ "member sees the artefact afterwards. So it never inherits the "
300
+ "environment from `fm use`: with one remembered the write is REFUSED "
301
+ "until you pass --env, and with nothing remembered it targets the "
302
+ "built-in default (local).\n\n"
303
+ "The bundle contains:\n"
304
+ + "\n".join(f" - {line}" for line in BUNDLE_CONTENTS)
305
+ + "\n\n"
306
+ + SCOPING_NOTE
307
+ + "\n\nThe file is never overwritten and never written empty; the "
308
+ "path printed at the end is the path that was actually written."
309
+ ),
310
+ formatter_class=argparse.RawDescriptionHelpFormatter,
311
+ )
312
+ _add_env(p)
313
+ _add_space(p)
314
+ p.add_argument(
315
+ "--bundle",
316
+ action="store_true",
317
+ help="the round-trip ZIP instead of the JSON bundle (a write; OWNER/ADMIN)",
318
+ )
319
+ p.add_argument(
320
+ "--include-history",
321
+ dest="include_history",
322
+ action="store_true",
323
+ help="--bundle only: include chats/proposals/audit/notifications",
324
+ )
325
+ p.add_argument(
326
+ "--include-document-index",
327
+ dest="include_document_index",
328
+ action="store_true",
329
+ help="--bundle only: include converted document text",
330
+ )
331
+ p.add_argument("-o", "--out", help="destination file, or a directory to write into")
332
+
333
+
334
+ def cmd_export(args) -> int:
335
+ """Download a space's data to a file, saying what is in it before it lands.
336
+
337
+ The two halves differ in the one way that matters: the JSON bundle is a read
338
+ and may inherit `fm use`'s environment, while --bundle is a write and cannot.
339
+ That is not a stylistic split: POST /export/bundle creates a File row every
340
+ member can see and emits an event, so running it against the wrong space is
341
+ visible to that space's members.
342
+ """
343
+ if args.bundle:
344
+ return _export_bundle(args)
345
+ return _export_gdpr(args)
346
+
347
+
348
+ def _export_gdpr(args) -> int:
349
+ # Lazy: `cli` imports this module, so a module-level import here
350
+ # would be a cycle.
351
+ eff = context.resolve(args, need_space=True, need_token=True)
352
+ token = eff.token
353
+ precheck_out(args.out)
354
+
355
+ body, disposition = api.download(
356
+ eff.target, f"/projects/{eff.space}/export", token=token
357
+ )
358
+ path = destination(
359
+ args.out,
360
+ filename_from_disposition(disposition),
361
+ f"space-{eff.space}.json",
362
+ )
363
+ written = write_export(path, body)
364
+ print(f"wrote {written.path} ({written.bytes_written} bytes)")
365
+ print(SCOPING_NOTE, file=sys.stderr)
366
+ return 0
367
+
368
+
369
+ def _export_bundle(args) -> int:
370
+ # Lazy: `cli` imports this module, so a module-level import here
371
+ # would be a cycle.
372
+ eff = context.resolve(args, for_write=True, need_space=True, need_token=True)
373
+ token = eff.token
374
+
375
+ # BEFORE the POST: the build inserts a File row and emits an event, so a
376
+ # destination that will be refused must be refused now, not after the space
377
+ # has an artefact in it that this run cannot deliver.
378
+ precheck_out(args.out)
379
+
380
+ # Said BEFORE the call, not after. This is the half an operator does not expect
381
+ # from a command called "export", and afterwards is too late to decline.
382
+ print(
383
+ " --bundle BUILDS the archive on the server: it adds a File row and "
384
+ "emits an export event. Every member of this space will see it.",
385
+ file=sys.stderr,
386
+ )
387
+
388
+ response = api.post(
389
+ eff.target,
390
+ f"/projects/{eff.space}/export/bundle",
391
+ {
392
+ "include_history": args.include_history,
393
+ "include_document_index": args.include_document_index,
394
+ },
395
+ token=token,
396
+ )
397
+ print(render_bundle_report(response))
398
+
399
+ if not isinstance(response, dict) or not response.get("file_id"):
400
+ raise ExportError(
401
+ "the server accepted the build but returned no file_id, so there is "
402
+ "nothing to download.\n"
403
+ "The archive may still exist among the space's files, check there "
404
+ "before rebuilding, or a second run adds a second copy."
405
+ )
406
+
407
+ file_id = response["file_id"]
408
+ body, disposition = api.download(
409
+ eff.target,
410
+ f"/projects/{eff.space}/export/bundle/{file_id}",
411
+ token=token,
412
+ )
413
+ # The POST's `filename` wins over Content-Disposition: the download
414
+ # route hardcodes a generic filename, while the POST returns the
415
+ # timestamped, space-slugged name the server actually filed the
416
+ # artefact under. Preferring the header would make every bundle from
417
+ # every space land on disk under the same generic filename, which the
418
+ # no-overwrite rule then turns into a refusal on the second export.
419
+ path = destination(
420
+ args.out,
421
+ response.get("filename") or filename_from_disposition(disposition),
422
+ f"evane-export-{eff.space}.zip",
423
+ )
424
+ written = write_export(path, body)
425
+ print(f"\nwrote {written.path} ({written.bytes_written} bytes)")
426
+ print(SCOPING_NOTE, file=sys.stderr)
427
+ return 0