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,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)