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/__init__.py +1 -0
- formist_cli/__main__.py +3 -0
- formist_cli/airtable.py +238 -0
- formist_cli/alerts.py +207 -0
- formist_cli/api.py +1027 -0
- formist_cli/chat.py +618 -0
- formist_cli/chats.py +517 -0
- formist_cli/cli.py +1367 -0
- formist_cli/cli_support.py +221 -0
- formist_cli/connectors.py +358 -0
- formist_cli/context.py +164 -0
- formist_cli/diff.py +943 -0
- formist_cli/doctor.py +128 -0
- formist_cli/export.py +427 -0
- formist_cli/files.py +670 -0
- formist_cli/importer.py +425 -0
- formist_cli/kb.py +185 -0
- formist_cli/login.py +615 -0
- formist_cli/logs.py +781 -0
- formist_cli/meetings.py +200 -0
- formist_cli/messages.py +414 -0
- formist_cli/participants.py +402 -0
- formist_cli/prefs.py +328 -0
- formist_cli/privileges.py +375 -0
- formist_cli/projects.py +127 -0
- formist_cli/resolve.py +443 -0
- formist_cli/settings.py +199 -0
- formist_cli/skill_library.py +246 -0
- formist_cli/skills.py +308 -0
- formist_cli/space_plan.py +411 -0
- formist_cli/spaces.py +693 -0
- formist_cli/targets.py +153 -0
- formist_cli/textnorm.py +26 -0
- formist_cli/tokens.py +339 -0
- formist_cli/update.py +433 -0
- formist_cli/uploads.py +928 -0
- formist_cli/usage_tokens.py +152 -0
- formist_cli/users.py +384 -0
- formist_cli/whatsapp.py +451 -0
- formist_cli-0.1.0.dist-info/METADATA +176 -0
- formist_cli-0.1.0.dist-info/RECORD +44 -0
- formist_cli-0.1.0.dist-info/WHEEL +4 -0
- formist_cli-0.1.0.dist-info/entry_points.txt +2 -0
- formist_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
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
|