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/importer.py
ADDED
|
@@ -0,0 +1,425 @@
|
|
|
1
|
+
"""``fm import`` - load a workspace bundle into a space. The most destructive
|
|
2
|
+
command in this tool, so it is dry-run by default.
|
|
3
|
+
|
|
4
|
+
Three exclusions are properties of the server, not of this command, and all
|
|
5
|
+
three routinely surprise people trying to mirror one space into another:
|
|
6
|
+
|
|
7
|
+
1. SharePoint-sourced files do not travel, the rows, not just the bytes.
|
|
8
|
+
A mirror built this way can have a knowledge base that looks present
|
|
9
|
+
(the space opens, the counts are non-zero) while being mostly absent.
|
|
10
|
+
2. Connector credentials do not travel, and connection foreign keys are
|
|
11
|
+
NULLed on the way in. So ``fm import`` can never configure the target
|
|
12
|
+
with the same connectors as the source: that is not a gap to work
|
|
13
|
+
around, it is the boundary that keeps a copied workspace from holding
|
|
14
|
+
live credentials for somebody else's tenant.
|
|
15
|
+
3. Users resolve by email and accounts are never created. A member of the
|
|
16
|
+
source who has no account on the target lands in ``unresolved_users``,
|
|
17
|
+
which is why that list is printed rather than summarised away.
|
|
18
|
+
|
|
19
|
+
Why dry run is the default and ``--apply`` is the flag: the server computes
|
|
20
|
+
the full two-pass resolution under ``dry_run=true`` and returns the same
|
|
21
|
+
report it would return for real, writing nothing. So the safe call is also
|
|
22
|
+
the informative one, and there is no reason for the operator's first
|
|
23
|
+
attempt to be the write. This mirrors ``fm airtable direction``, and for
|
|
24
|
+
the same reason: the plan the operator authorizes should be a plan they
|
|
25
|
+
have seen.
|
|
26
|
+
|
|
27
|
+
The dry run and the apply are two separate uploads of the same archive,
|
|
28
|
+
and the space can move between them. A report is only true of the state
|
|
29
|
+
it ran against. So ``--apply`` re-runs the dry run itself, prints it,
|
|
30
|
+
applies, and then :func:`divergences` compares what was predicted with
|
|
31
|
+
what the server says happened, printed whether or not they agree, because
|
|
32
|
+
a comparison that is only shown when it fails is indistinguishable from
|
|
33
|
+
one that never ran. This is not a theoretical concern: the import takes
|
|
34
|
+
an advisory lock per project precisely because concurrent imports into one
|
|
35
|
+
space are expected.
|
|
36
|
+
|
|
37
|
+
Stdlib only: `fm` must add no runtime dependency.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
from __future__ import annotations
|
|
41
|
+
|
|
42
|
+
import sys
|
|
43
|
+
import zipfile
|
|
44
|
+
from dataclasses import dataclass
|
|
45
|
+
from pathlib import Path
|
|
46
|
+
|
|
47
|
+
from formist_cli import api
|
|
48
|
+
|
|
49
|
+
#: The server's compressed-upload cap, mirrored client-side so a huge
|
|
50
|
+
#: upload is flagged before it is sent rather than after. This is a copied
|
|
51
|
+
#: constant and is used only to warn, never to refuse: if the deployment
|
|
52
|
+
#: raises its limit, a client-side refusal would block an upload the
|
|
53
|
+
#: server would have accepted. The server's own check is the one that
|
|
54
|
+
#: counts; this only predicts.
|
|
55
|
+
SERVER_ZIP_CAP_HINT = 200 * 1024 * 1024
|
|
56
|
+
|
|
57
|
+
#: Merge policies the server accepts. ``append`` is restricted to one kind
|
|
58
|
+
#: of row there; it is offered here because the server owns that
|
|
59
|
+
#: restriction and will say so better than a second copy of the rule here.
|
|
60
|
+
MERGE_POLICIES = ("skip-if-older", "overwrite", "skip-existing", "append")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
class ImportRefused(Exception):
|
|
64
|
+
"""A refusal about an import, written for an operator.
|
|
65
|
+
|
|
66
|
+
Named ``ImportRefused`` and not ``ImportError``: the builtin of that
|
|
67
|
+
name is raised by the interpreter itself, and a module shadowing it
|
|
68
|
+
would turn "your bundle is bad" and "a module failed to load" into one
|
|
69
|
+
``except`` clause.
|
|
70
|
+
"""
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
@dataclass(frozen=True)
|
|
74
|
+
class Bundle:
|
|
75
|
+
"""A bundle that has been read off disk and looks like a bundle."""
|
|
76
|
+
|
|
77
|
+
path: Path
|
|
78
|
+
data: bytes
|
|
79
|
+
|
|
80
|
+
@property
|
|
81
|
+
def size(self) -> int:
|
|
82
|
+
return len(self.data)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def read_bundle(raw_path: str) -> Bundle:
|
|
86
|
+
"""Read the ZIP at ``raw_path``, refusing the ways an upload silently does nothing.
|
|
87
|
+
|
|
88
|
+
Every check here is about a failure that would otherwise be reported as a
|
|
89
|
+
successful import of an empty or wrong archive:
|
|
90
|
+
|
|
91
|
+
* missing: the obvious one, and the only one that fails loudly anyway.
|
|
92
|
+
* a directory: ``read_bytes`` raises ``IsADirectoryError``, whose message
|
|
93
|
+
does not mention the bundle.
|
|
94
|
+
* empty: zero bytes uploads fine and the server answers ``empty-bundle``;
|
|
95
|
+
catching it here says which file, which the server cannot know.
|
|
96
|
+
* not a ZIP: the common miss is passing the GDPR JSON from a plain
|
|
97
|
+
``fm export``, which is a perfectly good file and the wrong one entirely.
|
|
98
|
+
The refusal names that case because it is the one that actually happens.
|
|
99
|
+
* no manifest: a ZIP without ``manifest.json`` is not a bundle. The server
|
|
100
|
+
rejects it after the whole upload; this rejects it before.
|
|
101
|
+
"""
|
|
102
|
+
path = Path(raw_path).expanduser()
|
|
103
|
+
if not path.exists():
|
|
104
|
+
raise ImportRefused(f"no such file: {path}")
|
|
105
|
+
if path.is_dir():
|
|
106
|
+
raise ImportRefused(
|
|
107
|
+
f"{path} is a directory.\n"
|
|
108
|
+
"-> Pass the bundle ZIP itself, not the folder holding it."
|
|
109
|
+
)
|
|
110
|
+
data = path.read_bytes()
|
|
111
|
+
if not data:
|
|
112
|
+
raise ImportRefused(
|
|
113
|
+
f"{path} is 0 bytes.\n"
|
|
114
|
+
"An empty file uploads perfectly well and the server would answer "
|
|
115
|
+
"`empty-bundle` without naming it, so this is refused here where the "
|
|
116
|
+
"filename is still known."
|
|
117
|
+
)
|
|
118
|
+
if not zipfile.is_zipfile(path):
|
|
119
|
+
head = data[:1].decode("utf-8", "replace")
|
|
120
|
+
hint = (
|
|
121
|
+
"\nIt starts with `{`, this looks like the GDPR JSON from a plain "
|
|
122
|
+
"`fm export`. The importable archive is the one built by "
|
|
123
|
+
"`fm export --bundle`."
|
|
124
|
+
if head == "{"
|
|
125
|
+
else ""
|
|
126
|
+
)
|
|
127
|
+
raise ImportRefused(f"{path} is not a zip archive.{hint}")
|
|
128
|
+
try:
|
|
129
|
+
with zipfile.ZipFile(path) as zf:
|
|
130
|
+
names = set(zf.namelist())
|
|
131
|
+
except zipfile.BadZipFile as exc:
|
|
132
|
+
raise ImportRefused(f"{path} is a corrupt zip archive: {exc}") from None
|
|
133
|
+
if "manifest.json" not in names:
|
|
134
|
+
raise ImportRefused(
|
|
135
|
+
f"{path} is a zip but carries no manifest.json, so it is not a "
|
|
136
|
+
"workspace bundle.\n"
|
|
137
|
+
"-> Build one with `fm export --bundle --host <host> --space <uuid>`."
|
|
138
|
+
)
|
|
139
|
+
return Bundle(path=path, data=data)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _counts(section: object) -> list[tuple[str, int]]:
|
|
143
|
+
"""``{class: count}`` as sorted pairs, skipping zeros. ``[]`` for any other shape.
|
|
144
|
+
|
|
145
|
+
Shape-tolerant on purpose: a report renderer written against a guessed
|
|
146
|
+
shape, with a unit test encoding the same guess, is how the test and the
|
|
147
|
+
code can agree with each other and not with the server.
|
|
148
|
+
``inserted``/``merged``/``skipped``/``dropped_rows`` are dicts on the
|
|
149
|
+
wire; anything else is reported as unrecognised rather than silently
|
|
150
|
+
rendering as empty.
|
|
151
|
+
"""
|
|
152
|
+
if not isinstance(section, dict):
|
|
153
|
+
return []
|
|
154
|
+
out = []
|
|
155
|
+
for name, value in section.items():
|
|
156
|
+
if isinstance(value, int) and value:
|
|
157
|
+
out.append((str(name), value))
|
|
158
|
+
return sorted(out)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _total(section: object) -> int:
|
|
162
|
+
return sum(count for _, count in _counts(section))
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def render_report(response: object) -> str:
|
|
166
|
+
"""Describe what the server said it did. Takes only the response.
|
|
167
|
+
|
|
168
|
+
The request is deliberately not a parameter, so nothing here can echo
|
|
169
|
+
what was asked for: a report assembled partly from the local payload
|
|
170
|
+
confirms the request rather than the result, which is how a
|
|
171
|
+
confirmation line can "confirm" whatever landed instead of what the
|
|
172
|
+
server actually reported.
|
|
173
|
+
"""
|
|
174
|
+
if not isinstance(response, dict):
|
|
175
|
+
return str(response)
|
|
176
|
+
|
|
177
|
+
lines: list[str] = []
|
|
178
|
+
mode = "DRY RUN (nothing was written)" if response.get("dry_run") else "APPLIED"
|
|
179
|
+
lines.append(f"mode {mode}")
|
|
180
|
+
for key, label in (
|
|
181
|
+
("source_project_id", "source"),
|
|
182
|
+
("bundle_id", "bundle_id"),
|
|
183
|
+
("merge", "merge"),
|
|
184
|
+
):
|
|
185
|
+
if response.get(key) is not None:
|
|
186
|
+
lines.append(f"{label:<10} {response[key]}")
|
|
187
|
+
|
|
188
|
+
for key, label in (
|
|
189
|
+
("inserted", "inserted"),
|
|
190
|
+
("merged", "merged"),
|
|
191
|
+
("skipped", "skipped"),
|
|
192
|
+
("dropped_rows", "dropped"),
|
|
193
|
+
):
|
|
194
|
+
section = response.get(key)
|
|
195
|
+
pairs = _counts(section)
|
|
196
|
+
if pairs:
|
|
197
|
+
lines.append(f"{label:<10} {_total(section)}")
|
|
198
|
+
for name, count in pairs:
|
|
199
|
+
lines.append(f" {name:<28} {count}")
|
|
200
|
+
elif isinstance(section, dict):
|
|
201
|
+
lines.append(f"{label:<10} 0")
|
|
202
|
+
elif section is not None:
|
|
203
|
+
lines.append(
|
|
204
|
+
f"{label:<10} (unrecognised shape: {type(section).__name__}, "
|
|
205
|
+
"this report cannot summarise it; read the JSON with --json)"
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
subs = response.get("user_substitutions")
|
|
209
|
+
if subs:
|
|
210
|
+
lines.append(f"user_subs {subs}")
|
|
211
|
+
|
|
212
|
+
# The four unflattering lists, always printed when non-empty. A bundle that
|
|
213
|
+
# dropped references or could not fetch blobs imported INCOMPLETELY, and a
|
|
214
|
+
# summary that prints the counts while omitting the holes describes a partial
|
|
215
|
+
# import as a whole one.
|
|
216
|
+
for key, label, note in (
|
|
217
|
+
(
|
|
218
|
+
"unresolved_users",
|
|
219
|
+
"UNRESOLVED USERS",
|
|
220
|
+
"no account on this target; accounts are never created by an import",
|
|
221
|
+
),
|
|
222
|
+
(
|
|
223
|
+
"missing_blobs",
|
|
224
|
+
"MISSING BLOBS",
|
|
225
|
+
"rows landed whose file bytes did not, they will 404 when opened",
|
|
226
|
+
),
|
|
227
|
+
("conflicts", "CONFLICTS", "the merge policy chose; check it was the one you wanted"),
|
|
228
|
+
("dropped_refs", "DROPPED REFS", "references that pointed at rows not in the bundle"),
|
|
229
|
+
):
|
|
230
|
+
items = response.get(key)
|
|
231
|
+
if isinstance(items, list) and items:
|
|
232
|
+
lines.append(f"{len(items)} {label}: {note}:")
|
|
233
|
+
for item in items[:20]:
|
|
234
|
+
lines.append(f" {item}")
|
|
235
|
+
if len(items) > 20:
|
|
236
|
+
lines.append(f" ... and {len(items) - 20} more (use --json for all)")
|
|
237
|
+
return "\n".join(lines)
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
def divergences(dry: object, applied: object) -> list[str]:
|
|
241
|
+
"""Where the applied report disagrees with the dry run that authorized it.
|
|
242
|
+
|
|
243
|
+
Returns a list of human sentences; empty means they agreed. Compared per class
|
|
244
|
+
and per bucket rather than as whole dicts, so the message can name WHICH class
|
|
245
|
+
moved, since "something changed" sends an operator to read two JSON blobs by eye.
|
|
246
|
+
|
|
247
|
+
``dry_run`` itself is expected to differ and is excluded; so are the free-text
|
|
248
|
+
lists, which legitimately differ in ORDER without differing in content.
|
|
249
|
+
"""
|
|
250
|
+
out: list[str] = []
|
|
251
|
+
if not isinstance(dry, dict) or not isinstance(applied, dict):
|
|
252
|
+
return ["the two reports were not both objects, so they cannot be compared."]
|
|
253
|
+
for bucket in ("inserted", "merged", "skipped", "dropped_rows"):
|
|
254
|
+
before = dict(_counts(dry.get(bucket)))
|
|
255
|
+
after = dict(_counts(applied.get(bucket)))
|
|
256
|
+
for name in sorted(set(before) | set(after)):
|
|
257
|
+
if before.get(name, 0) != after.get(name, 0):
|
|
258
|
+
out.append(
|
|
259
|
+
f"{bucket}.{name}: dry run predicted {before.get(name, 0)}, "
|
|
260
|
+
f"the apply reported {after.get(name, 0)}"
|
|
261
|
+
)
|
|
262
|
+
for bucket in ("unresolved_users", "missing_blobs", "conflicts", "dropped_refs"):
|
|
263
|
+
b = dry.get(bucket)
|
|
264
|
+
a = applied.get(bucket)
|
|
265
|
+
if isinstance(b, list) and isinstance(a, list) and len(b) != len(a):
|
|
266
|
+
out.append(f"{bucket}: dry run had {len(b)}, the apply reported {len(a)}")
|
|
267
|
+
return out
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
# ===========================================================================
|
|
271
|
+
# CLI surface. Per-module `add_parser`: adding a command costs the top-level
|
|
272
|
+
# parser one line instead of a block two branches both land in.
|
|
273
|
+
# ===========================================================================
|
|
274
|
+
def add_parser(sub) -> None:
|
|
275
|
+
import argparse
|
|
276
|
+
|
|
277
|
+
from formist_cli.cli import _add_env, _add_space
|
|
278
|
+
|
|
279
|
+
p = sub.add_parser(
|
|
280
|
+
"import",
|
|
281
|
+
help="load a workspace bundle into a space (DRY RUN by default)",
|
|
282
|
+
description=(
|
|
283
|
+
"POST /projects/{id}/import, owner/admin only.\n\n"
|
|
284
|
+
"DRY RUN BY DEFAULT. The server runs the full two-pass resolution and "
|
|
285
|
+
"returns the real report without writing, so your first attempt is "
|
|
286
|
+
"never the write. --apply re-runs the dry run, prints it, applies, and "
|
|
287
|
+
"then compares what was predicted against what happened.\n\n"
|
|
288
|
+
"--apply never inherits the environment from `fm use`. If one is "
|
|
289
|
+
"remembered, the write is refused until you name --env on the command "
|
|
290
|
+
"line; with nothing remembered it targets the built-in default "
|
|
291
|
+
"(local). An import rewrites a workspace, and an environment is one "
|
|
292
|
+
"word that decides whether this is production, so it comes from the "
|
|
293
|
+
"command you just ran, never from a setting made earlier.\n\n"
|
|
294
|
+
"Three things a bundle cannot carry, all server-side, all surprising:\n"
|
|
295
|
+
" - SharePoint-sourced files, rows included, not just the bytes. A "
|
|
296
|
+
"mirror built from a bundle can look present and be mostly empty.\n"
|
|
297
|
+
" - connector credentials; connection FKs are NULLed on import. This "
|
|
298
|
+
"command cannot give the target the source's connectors, by design.\n"
|
|
299
|
+
" - users. They resolve by email and accounts are never created; the "
|
|
300
|
+
"rest land in `unresolved_users`, which is printed."
|
|
301
|
+
),
|
|
302
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
303
|
+
)
|
|
304
|
+
_add_env(p)
|
|
305
|
+
_add_space(p)
|
|
306
|
+
p.add_argument("bundle", help="path to the bundle ZIP from `fm export --bundle`")
|
|
307
|
+
p.add_argument(
|
|
308
|
+
"--apply",
|
|
309
|
+
action="store_true",
|
|
310
|
+
help=(
|
|
311
|
+
"actually write (the dry run still runs first). Refuses a remembered "
|
|
312
|
+
"`fm use` environment: pass --env to write anywhere but local"
|
|
313
|
+
),
|
|
314
|
+
)
|
|
315
|
+
p.add_argument(
|
|
316
|
+
"--merge",
|
|
317
|
+
default="skip-if-older",
|
|
318
|
+
choices=MERGE_POLICIES,
|
|
319
|
+
help="how an existing row is treated (default: skip-if-older)",
|
|
320
|
+
)
|
|
321
|
+
p.add_argument(
|
|
322
|
+
"--include-history",
|
|
323
|
+
dest="include_history",
|
|
324
|
+
action="store_true",
|
|
325
|
+
help="also import chats/proposals/audit/notifications, if the bundle has them",
|
|
326
|
+
)
|
|
327
|
+
p.add_argument(
|
|
328
|
+
"--include-document-index",
|
|
329
|
+
dest="include_document_index",
|
|
330
|
+
action="store_true",
|
|
331
|
+
help="also import converted document text (the agent's retrieval surface)",
|
|
332
|
+
)
|
|
333
|
+
p.add_argument("--json", action="store_true", help="print the raw server report")
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
def _send(eff, token, bundle: Bundle, args, *, dry: bool) -> object:
|
|
337
|
+
return api.post_multipart(
|
|
338
|
+
eff.target,
|
|
339
|
+
f"/projects/{eff.space}/import"
|
|
340
|
+
f"?dry_run={'true' if dry else 'false'}"
|
|
341
|
+
f"&merge={args.merge}"
|
|
342
|
+
f"&include_history={'true' if args.include_history else 'false'}"
|
|
343
|
+
f"&include_document_index="
|
|
344
|
+
f"{'true' if args.include_document_index else 'false'}",
|
|
345
|
+
fields={},
|
|
346
|
+
files={"file": (bundle.path.name, bundle.data)},
|
|
347
|
+
token=token,
|
|
348
|
+
)
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
def cmd_import(args) -> int:
|
|
352
|
+
"""Import a bundle, showing the plan before it can become a write."""
|
|
353
|
+
# Lazy: `cli` imports this module, so a module-level import would be a cycle.
|
|
354
|
+
import json as _json
|
|
355
|
+
|
|
356
|
+
from formist_cli.cli import _effective, _token_for
|
|
357
|
+
|
|
358
|
+
# Read the file before resolving the target: a refusal about the bundle is
|
|
359
|
+
# about the bundle, and making the operator fix an --env to be told their
|
|
360
|
+
# path is wrong wastes the round trip that was going to fail anyway.
|
|
361
|
+
bundle = read_bundle(args.bundle)
|
|
362
|
+
if bundle.size > SERVER_ZIP_CAP_HINT:
|
|
363
|
+
print(
|
|
364
|
+
f" note: {bundle.size} bytes is above the {SERVER_ZIP_CAP_HINT}-byte "
|
|
365
|
+
"cap this client last knew about. Sending anyway, the server owns "
|
|
366
|
+
"that limit and will refuse if it still applies.",
|
|
367
|
+
file=sys.stderr,
|
|
368
|
+
)
|
|
369
|
+
|
|
370
|
+
# for_write is the --apply flag itself: a dry run writes nothing and may
|
|
371
|
+
# inherit an environment; the write may not.
|
|
372
|
+
eff = _effective(args, for_write=bool(args.apply))
|
|
373
|
+
token = _token_for(eff)
|
|
374
|
+
|
|
375
|
+
print(
|
|
376
|
+
f" bundle {bundle.path} ({bundle.size} bytes)",
|
|
377
|
+
file=sys.stderr,
|
|
378
|
+
)
|
|
379
|
+
|
|
380
|
+
dry = _send(eff, token, bundle, args, dry=True)
|
|
381
|
+
if args.json and not args.apply:
|
|
382
|
+
print(_json.dumps(dry, indent=2))
|
|
383
|
+
else:
|
|
384
|
+
print(render_report(dry))
|
|
385
|
+
|
|
386
|
+
if not args.apply:
|
|
387
|
+
print(
|
|
388
|
+
"\n-> nothing was written. Re-run with `--apply --host <host>` to "
|
|
389
|
+
"persist this.",
|
|
390
|
+
file=sys.stderr,
|
|
391
|
+
)
|
|
392
|
+
return 0
|
|
393
|
+
|
|
394
|
+
print("\n applying...", file=sys.stderr)
|
|
395
|
+
applied = _send(eff, token, bundle, args, dry=False)
|
|
396
|
+
print("\n" + render_report(applied))
|
|
397
|
+
if args.json:
|
|
398
|
+
print(_json.dumps(applied, indent=2))
|
|
399
|
+
|
|
400
|
+
# Printed whether or not they agree: a comparison shown only on failure is
|
|
401
|
+
# indistinguishable from one that never ran.
|
|
402
|
+
diffs = divergences(dry, applied)
|
|
403
|
+
if diffs:
|
|
404
|
+
print(
|
|
405
|
+
"\nTHE APPLY DID NOT MATCH THE DRY RUN THAT AUTHORIZED IT:",
|
|
406
|
+
file=sys.stderr,
|
|
407
|
+
)
|
|
408
|
+
for line in diffs:
|
|
409
|
+
print(f" {line}", file=sys.stderr)
|
|
410
|
+
print(
|
|
411
|
+
" The space changed between the two calls, or the merge policy hit "
|
|
412
|
+
"rows the dry run did not see. The import has been applied; this is a "
|
|
413
|
+
"report, not a rollback.",
|
|
414
|
+
file=sys.stderr,
|
|
415
|
+
)
|
|
416
|
+
return 1
|
|
417
|
+
print(
|
|
418
|
+
"\n the apply matched the dry run that authorized it "
|
|
419
|
+
f"({_total(applied.get('inserted') if isinstance(applied, dict) else None)} "
|
|
420
|
+
"inserted, "
|
|
421
|
+
f"{_total(applied.get('merged') if isinstance(applied, dict) else None)} "
|
|
422
|
+
"merged).",
|
|
423
|
+
file=sys.stderr,
|
|
424
|
+
)
|
|
425
|
+
return 0
|
formist_cli/kb.py
ADDED
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
"""``fm kb`` - ad-hoc knowledge-base search and read, from the operator's terminal.
|
|
2
|
+
|
|
3
|
+
A thin client over the same member-gated routes the product itself uses:
|
|
4
|
+
|
|
5
|
+
* ``fm kb search <term>... --space <id>`` -> ``GET /projects/{id}/search?q=...``.
|
|
6
|
+
The terms are joined with spaces into one query string, not sent one call
|
|
7
|
+
per term, since ranking is already per-term server-side (a hit matching
|
|
8
|
+
more of the terms scores higher), so client-side aggregation across
|
|
9
|
+
separate calls would just be redundant network round-trips for an answer
|
|
10
|
+
the server already computes in one.
|
|
11
|
+
* ``fm kb read <needle> --space <id>`` -> the same search, then
|
|
12
|
+
``GET /projects/{id}/files/{file_id}/content`` for the first hit that
|
|
13
|
+
actually carries a ``file_id`` (a message or SharePoint-native hit does
|
|
14
|
+
not, and is skipped rather than sent as a bogus UUID path param). The
|
|
15
|
+
content route is blob-backed and reachable from anywhere `fm` runs. A
|
|
16
|
+
needle that names a file (e.g. a filename fragment) still resolves it:
|
|
17
|
+
filename hits are boosted server-side.
|
|
18
|
+
|
|
19
|
+
Read-only. There is no flag that makes either subject write.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import argparse
|
|
25
|
+
import json
|
|
26
|
+
|
|
27
|
+
from formist_cli import api, context
|
|
28
|
+
from formist_cli.cli_support import build_standalone_parser as _build_standalone_parser
|
|
29
|
+
|
|
30
|
+
SUBJECTS = ("search", "read")
|
|
31
|
+
|
|
32
|
+
#: Default truncation length for a printed file body.
|
|
33
|
+
DEFAULT_MAX_CHARS = 4000
|
|
34
|
+
|
|
35
|
+
#: Mirrors the search route's own default page size.
|
|
36
|
+
DEFAULT_SEARCH_LIMIT = 20
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class KbError(Exception):
|
|
40
|
+
"""A refusal about the knowledge-base surface, written for an operator."""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _subject_error(subject: object) -> KbError:
|
|
44
|
+
return KbError(
|
|
45
|
+
f"unknown subcommand {subject!r}. Valid: {', '.join(SUBJECTS)}.\n"
|
|
46
|
+
" search <term>... rank the project's KB by these terms (space-joined)\n"
|
|
47
|
+
" read <needle> search for needle, then print the top file's content"
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
_DESCRIPTION = """Ad-hoc knowledge-base search / read, over the SAME routes the
|
|
52
|
+
product's own search box and file viewer use, never a local disk or DB read.
|
|
53
|
+
|
|
54
|
+
fm kb search <term>... --space <id> rank the KB by these terms
|
|
55
|
+
fm kb read <needle> --space <id> search, then print the top file's content
|
|
56
|
+
|
|
57
|
+
Read-only. There is no flag that makes either subject write.
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def add_parser(subparsers) -> argparse.ArgumentParser:
|
|
62
|
+
parser = subparsers.add_parser(
|
|
63
|
+
"kb",
|
|
64
|
+
help="ad-hoc knowledge-base search / read (read-only)",
|
|
65
|
+
description=_DESCRIPTION,
|
|
66
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
67
|
+
)
|
|
68
|
+
_add_arguments(parser)
|
|
69
|
+
return parser
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _add_arguments(parser: argparse.ArgumentParser) -> None:
|
|
73
|
+
from formist_cli.cli import _add_env, _add_space
|
|
74
|
+
|
|
75
|
+
_add_env(parser)
|
|
76
|
+
_add_space(parser)
|
|
77
|
+
parser.add_argument("subject", help=f"one of: {', '.join(SUBJECTS)}")
|
|
78
|
+
parser.add_argument(
|
|
79
|
+
"query", nargs="+",
|
|
80
|
+
help="search: one or more terms (space-joined into one query). "
|
|
81
|
+
"read: a single needle (extra words are folded into the query too).",
|
|
82
|
+
)
|
|
83
|
+
parser.add_argument(
|
|
84
|
+
"--max-chars", dest="max_chars", type=int, default=DEFAULT_MAX_CHARS,
|
|
85
|
+
help=f"read: truncate the printed body to this many chars (default {DEFAULT_MAX_CHARS})",
|
|
86
|
+
)
|
|
87
|
+
parser.add_argument(
|
|
88
|
+
"--limit", type=int, default=None,
|
|
89
|
+
help="search: cap the number of hits requested from the server",
|
|
90
|
+
)
|
|
91
|
+
parser.add_argument("--json", action="store_true", help="raw JSON instead of a report")
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def build_standalone_parser() -> argparse.ArgumentParser:
|
|
95
|
+
return _build_standalone_parser(add_parser)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
# ===========================================================================
|
|
99
|
+
# search
|
|
100
|
+
# ===========================================================================
|
|
101
|
+
def render_search(payload: dict) -> str:
|
|
102
|
+
items = payload.get("items") or []
|
|
103
|
+
if not items:
|
|
104
|
+
return "(no hits)"
|
|
105
|
+
lines = [f"=== {len(items)} hit(s) (of {payload.get('total', len(items))}) ==="]
|
|
106
|
+
for item in items:
|
|
107
|
+
label = item.get("path") or item.get("subject") or item.get("name") or "?"
|
|
108
|
+
lines.append(f"[{item.get('source', '?')}] {label}")
|
|
109
|
+
if item.get("snippet"):
|
|
110
|
+
lines.append(f" ...{item['snippet']}...")
|
|
111
|
+
return "\n".join(lines)
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def _search(ctx: context.Context, query: str, *, limit: int | None) -> dict:
|
|
115
|
+
params: dict[str, str] = {"q": query}
|
|
116
|
+
if limit is not None:
|
|
117
|
+
params["limit"] = str(limit)
|
|
118
|
+
payload = api.get(ctx.target, f"/projects/{ctx.space}/search", token=ctx.token, params=params)
|
|
119
|
+
if not isinstance(payload, dict):
|
|
120
|
+
raise KbError(
|
|
121
|
+
f"expected a JSON object from /projects/{{id}}/search, got "
|
|
122
|
+
f"{type(payload).__name__}. That is a server contract change, not an empty result."
|
|
123
|
+
)
|
|
124
|
+
return payload
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def _run_search(ctx: context.Context, args) -> int:
|
|
128
|
+
query = " ".join(args.query)
|
|
129
|
+
payload = _search(ctx, query, limit=args.limit)
|
|
130
|
+
if args.json:
|
|
131
|
+
print(json.dumps(payload, indent=2, ensure_ascii=False))
|
|
132
|
+
else:
|
|
133
|
+
print(render_search(payload))
|
|
134
|
+
return 0
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
# ===========================================================================
|
|
138
|
+
# read
|
|
139
|
+
# ===========================================================================
|
|
140
|
+
def _top_file_hit(items: list) -> dict | None:
|
|
141
|
+
"""The first hit that actually names a ``file_id``: a message or
|
|
142
|
+
SharePoint-native hit does not, and cannot be read through
|
|
143
|
+
``/files/{id}/content`` (that path param is a UUID; sending anything else
|
|
144
|
+
422s instead of cleanly not-found)."""
|
|
145
|
+
for item in items:
|
|
146
|
+
if isinstance(item, dict) and item.get("file_id"):
|
|
147
|
+
return item
|
|
148
|
+
return None
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _run_read(ctx: context.Context, args) -> int:
|
|
152
|
+
needle = " ".join(args.query)
|
|
153
|
+
payload = _search(ctx, needle, limit=args.limit)
|
|
154
|
+
hit = _top_file_hit(payload.get("items") or [])
|
|
155
|
+
if hit is None:
|
|
156
|
+
raise KbError(f"no file hit for {needle!r}, nothing to read.")
|
|
157
|
+
file_id = str(hit["file_id"])
|
|
158
|
+
content = api.get(
|
|
159
|
+
ctx.target, f"/projects/{ctx.space}/files/{file_id}/content", token=ctx.token
|
|
160
|
+
)
|
|
161
|
+
if not isinstance(content, dict):
|
|
162
|
+
raise KbError(
|
|
163
|
+
f"expected a JSON object from /files/{{id}}/content, got "
|
|
164
|
+
f"{type(content).__name__}."
|
|
165
|
+
)
|
|
166
|
+
if args.json:
|
|
167
|
+
print(json.dumps(content, indent=2, ensure_ascii=False))
|
|
168
|
+
return 0
|
|
169
|
+
text = content.get("markdown") or ""
|
|
170
|
+
path = content.get("path") or content.get("name") or file_id
|
|
171
|
+
print(f"### {path} ({len(text)} chars)\n")
|
|
172
|
+
print(text[: args.max_chars])
|
|
173
|
+
if len(text) > args.max_chars:
|
|
174
|
+
print(f"\n...[truncated, {len(text) - args.max_chars} more chars]")
|
|
175
|
+
return 0
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def run(args) -> int:
|
|
179
|
+
subject = (getattr(args, "subject", None) or "").strip().lower()
|
|
180
|
+
if subject not in SUBJECTS:
|
|
181
|
+
raise _subject_error(getattr(args, "subject", None))
|
|
182
|
+
ctx = context.resolve(args, need_space=True, need_token=True)
|
|
183
|
+
if subject == "search":
|
|
184
|
+
return _run_search(ctx, args)
|
|
185
|
+
return _run_read(ctx, args)
|