reef-cli 1.0.0__tar.gz → 2.0.0__tar.gz
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.
- {reef_cli-1.0.0 → reef_cli-2.0.0}/PKG-INFO +1 -1
- {reef_cli-1.0.0 → reef_cli-2.0.0}/pyproject.toml +1 -1
- {reef_cli-1.0.0 → reef_cli-2.0.0}/pyproject.toml.orig +1 -1
- {reef_cli-1.0.0 → reef_cli-2.0.0}/src/reef_cli/cli.py +185 -211
- {reef_cli-1.0.0 → reef_cli-2.0.0}/LICENSE +0 -0
- {reef_cli-1.0.0 → reef_cli-2.0.0}/README.md +0 -0
- {reef_cli-1.0.0 → reef_cli-2.0.0}/src/reef_cli/__init__.py +0 -0
|
@@ -251,254 +251,228 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
251
251
|
help="JSON object, @file, or '-' for stdin (default: {})",
|
|
252
252
|
)
|
|
253
253
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
read_pages.add_argument("cove")
|
|
257
|
-
read_pages.add_argument("paths", nargs="+")
|
|
258
|
-
search = _tool_parser(sub, "search_pages", "full-text search across your pages")
|
|
259
|
-
search.add_argument("query")
|
|
260
|
-
search.add_argument("--cove", help="restrict to one cove")
|
|
261
|
-
search.add_argument("--limit", type=int, default=10)
|
|
262
|
-
# The two-tool connector shape, carried here for parity with the MCP
|
|
263
|
-
# surface. A person at a terminal wants search-pages and read-page --
|
|
264
|
-
# these exist because some clients can only ever call two tools.
|
|
265
|
-
connector_search = _tool_parser(sub, "search", "search, in the connector shape")
|
|
266
|
-
connector_search.add_argument("query")
|
|
267
|
-
connector_fetch = _tool_parser(sub, "fetch", "fetch one result from search")
|
|
268
|
-
connector_fetch.add_argument("id")
|
|
269
|
-
_tool_parser(sub, "load_all_context", "load all page bodies for maintenance")
|
|
270
|
-
_tool_parser(sub, "get_operating_protocol", "load the protocol and persona")
|
|
271
|
-
read_page = _tool_parser(sub, "read_page", "read one page")
|
|
272
|
-
read_page.add_argument("cove")
|
|
273
|
-
read_page.add_argument("path")
|
|
274
|
-
read_page.add_argument("--as-of", help="ISO-8601 moment to read the page as of")
|
|
275
|
-
whats_new = _tool_parser(sub, "whats_new", "list recent changes across coves")
|
|
276
|
-
whats_new.add_argument("--since", help="ISO-8601 moment to report changes after")
|
|
277
|
-
_tool_parser(sub, "list_coves", "list coves, members, ownership, and versions")
|
|
278
|
-
create_cove = _tool_parser(sub, "create_cove", "create a shared cove")
|
|
279
|
-
create_cove.add_argument("slug")
|
|
280
|
-
invite = _tool_parser(sub, "invite", "invite a person into a shared cove")
|
|
281
|
-
invite.add_argument("cove")
|
|
282
|
-
invite.add_argument("email")
|
|
283
|
-
invite.add_argument("--display-name")
|
|
284
|
-
invite.add_argument(
|
|
285
|
-
"--role",
|
|
286
|
-
choices=["member", "viewer"],
|
|
287
|
-
default="member",
|
|
288
|
-
help="viewer reads everything and writes nothing",
|
|
289
|
-
)
|
|
290
|
-
invite_reef = _tool_parser(
|
|
291
|
-
sub, "invite_to_reef", "invite someone to Reef without sharing a cove"
|
|
292
|
-
)
|
|
293
|
-
invite_reef.add_argument("email")
|
|
294
|
-
invite_reef.add_argument("--display-name")
|
|
295
|
-
remove = _tool_parser(sub, "remove_member", "remove a shared-cove member")
|
|
296
|
-
remove.add_argument("cove")
|
|
297
|
-
remove.add_argument("email")
|
|
298
|
-
rename = _tool_parser(sub, "rename_cove", "change what you call a shared cove")
|
|
299
|
-
rename.add_argument("cove")
|
|
300
|
-
rename.add_argument("new_name")
|
|
301
|
-
leave = _tool_parser(sub, "leave_cove", "leave a shared cove, handing it on")
|
|
302
|
-
leave.add_argument("cove")
|
|
303
|
-
delete = _tool_parser(sub, "delete_cove", "destroy a shared cove you are alone in")
|
|
304
|
-
delete.add_argument("cove")
|
|
305
|
-
remember = _tool_parser(sub, "remember", "append a fact to a cove inbox")
|
|
306
|
-
remember.add_argument("fact", help="fact text; '-' reads stdin")
|
|
307
|
-
remember.add_argument("--cove", default="personal")
|
|
254
|
+
_build_tool_parsers(sub)
|
|
255
|
+
return parser
|
|
308
256
|
|
|
309
|
-
write = _tool_parser(sub, "write_page", "create or replace one Markdown page")
|
|
310
|
-
write.add_argument("cove")
|
|
311
|
-
write.add_argument("path")
|
|
312
|
-
_add_text_source(write, "body")
|
|
313
|
-
write.add_argument("--message", required=True)
|
|
314
|
-
write.add_argument("--title")
|
|
315
|
-
write.add_argument("--tag", dest="tags", action="append")
|
|
316
|
-
write.add_argument("--expected-version", type=int)
|
|
317
257
|
|
|
318
|
-
|
|
319
|
-
|
|
258
|
+
def _reasoned(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
|
|
259
|
+
"""Give a tool's parser the optional ``--reason`` every tool but two takes.
|
|
260
|
+
|
|
261
|
+
:param parser: the tool's parser
|
|
262
|
+
:returns: the same parser
|
|
263
|
+
"""
|
|
264
|
+
parser.add_argument(
|
|
265
|
+
"--reason",
|
|
266
|
+
default="",
|
|
267
|
+
help="why you make this call, in a few words; Reef logs it privately "
|
|
268
|
+
"for the person, to improve Reef",
|
|
320
269
|
)
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
edit.add_argument("cove")
|
|
331
|
-
edit.add_argument("path")
|
|
332
|
-
_add_text_source(edit, "old-text")
|
|
333
|
-
_add_text_source(edit, "new-text")
|
|
334
|
-
edit.add_argument("--message", required=True)
|
|
335
|
-
edit.add_argument("--expected-version", type=int)
|
|
336
|
-
|
|
337
|
-
meta = _tool_parser(sub, "update_meta_page", "replace the personal persona page")
|
|
338
|
-
_add_text_source(meta, "body")
|
|
339
|
-
meta.add_argument("--message", required=True)
|
|
340
|
-
meta.add_argument(
|
|
270
|
+
return parser
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
def _confirmable(parser: argparse.ArgumentParser) -> None:
|
|
274
|
+
"""Give a staged tool's parser the ``--confirm`` of its second call.
|
|
275
|
+
|
|
276
|
+
:param parser: the parser of ``share``, ``forget`` or ``instruct``
|
|
277
|
+
"""
|
|
278
|
+
parser.add_argument(
|
|
341
279
|
"--confirm",
|
|
342
|
-
|
|
343
|
-
help="
|
|
280
|
+
metavar="TOKEN",
|
|
281
|
+
help="the token the first call returned, once the person said yes; "
|
|
282
|
+
"leave out for the first call",
|
|
344
283
|
)
|
|
345
284
|
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
)
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
)
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
285
|
+
|
|
286
|
+
def _build_tool_parsers(sub: argparse._SubParsersAction) -> None:
|
|
287
|
+
"""Add one subcommand for each of the sixteen tools.
|
|
288
|
+
|
|
289
|
+
:param sub: the subparsers of the main parser
|
|
290
|
+
"""
|
|
291
|
+
|
|
292
|
+
def tool(name: str, help: str, *, reason: bool = True) -> argparse.ArgumentParser:
|
|
293
|
+
parser = _tool_parser(sub, name, help)
|
|
294
|
+
return _reasoned(parser) if reason else parser
|
|
295
|
+
|
|
296
|
+
tool("load_index", "start here: protocol, persona and the index of every space")
|
|
297
|
+
recall = tool("recall", "answer a question from memory")
|
|
298
|
+
recall.add_argument("question")
|
|
299
|
+
recall.add_argument("--space", help="search one space only")
|
|
300
|
+
recall.add_argument("--limit", type=int, default=5)
|
|
301
|
+
brief = tool("brief", "get ready to advise or prepare on a topic")
|
|
302
|
+
brief.add_argument("topic")
|
|
303
|
+
brief.add_argument("--space", help="look in one space only")
|
|
304
|
+
brief.add_argument("--entries", type=int, default=10)
|
|
305
|
+
open_ = tool("open", "read whole engrams and stored files by ref")
|
|
306
|
+
open_.add_argument("refs", nargs="+", help="<space>/<path> or <space>/file/<key>")
|
|
307
|
+
open_.add_argument("--as-of", help="ISO-8601 moment to read engrams as of")
|
|
308
|
+
catch_up = tool("catch_up", "list what changed in your spaces")
|
|
309
|
+
catch_up.add_argument("--since", help="ISO-8601 moment; default: last 7 days")
|
|
310
|
+
remember = tool("remember", "keep one quick fact in a space's inbox")
|
|
311
|
+
remember.add_argument("fact", help="fact text; '-' reads stdin")
|
|
312
|
+
remember.add_argument("--space", default="personal")
|
|
313
|
+
log = tool("log", "add one entry at the end of a log")
|
|
314
|
+
log.add_argument("space")
|
|
315
|
+
log.add_argument("engram", help="the log's path")
|
|
316
|
+
log.add_argument("--heading", required=True)
|
|
317
|
+
_add_text_source(log, "entry")
|
|
318
|
+
write = tool("write", "create or replace up to 20 whole engrams, atomically")
|
|
319
|
+
write.add_argument("space")
|
|
320
|
+
write.add_argument("engrams", help="JSON array, @file, or '-' for stdin")
|
|
321
|
+
write.add_argument("--message", required=True)
|
|
322
|
+
store = tool("store_file", "keep a document or an image with a description")
|
|
323
|
+
store.add_argument("space")
|
|
324
|
+
store.add_argument("file", type=Path)
|
|
325
|
+
store.add_argument("--mime")
|
|
326
|
+
store.add_argument("--description", required=True)
|
|
327
|
+
store.add_argument("--engram", help="path of the engram the file belongs to")
|
|
328
|
+
correct = tool("correct", "replace one exact passage of an engram")
|
|
329
|
+
correct.add_argument("space")
|
|
330
|
+
correct.add_argument("engram")
|
|
331
|
+
_add_text_source(correct, "old-text")
|
|
332
|
+
_add_text_source(correct, "new-text")
|
|
333
|
+
correct.add_argument("--message", required=True)
|
|
334
|
+
correct.add_argument("--expected-version", type=int)
|
|
335
|
+
undo = tool("undo", "restore an earlier version of an engram")
|
|
336
|
+
undo.add_argument("space")
|
|
337
|
+
undo.add_argument("engram")
|
|
338
|
+
undo.add_argument("--version", type=int)
|
|
339
|
+
forget = tool("forget", "delete an engram or a file for good, in two calls")
|
|
340
|
+
forget.add_argument("space")
|
|
341
|
+
target = forget.add_mutually_exclusive_group(required=True)
|
|
342
|
+
target.add_argument("--engram", help="path of the engram to forget")
|
|
343
|
+
target.add_argument("--file", help="key of the file to forget")
|
|
344
|
+
_confirmable(forget)
|
|
345
|
+
share = tool("share", "move a personal engram into a shared space, in two calls")
|
|
346
|
+
share.add_argument("engram")
|
|
347
|
+
share.add_argument("to_space")
|
|
348
|
+
share.add_argument("--section", help="exact text to share; '-' reads stdin")
|
|
349
|
+
share.add_argument("--section-file", metavar="PATH")
|
|
350
|
+
share.add_argument(
|
|
351
|
+
"--to-path", help="path of the shared engram; needed with a section"
|
|
385
352
|
)
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
353
|
+
_confirmable(share)
|
|
354
|
+
instruct = tool("instruct", "replace the persona, in two calls")
|
|
355
|
+
_add_text_source(instruct, "body")
|
|
356
|
+
_confirmable(instruct)
|
|
357
|
+
# The two-tool connector shape, carried here for parity with the MCP
|
|
358
|
+
# surface. They take no reason: some clients can only ever call these two.
|
|
359
|
+
search = tool("search", "search, in the connector shape", reason=False)
|
|
360
|
+
search.add_argument("query")
|
|
361
|
+
fetch = tool("fetch", "fetch one result from search", reason=False)
|
|
362
|
+
fetch.add_argument("id")
|
|
363
|
+
|
|
389
364
|
|
|
365
|
+
def _file_arguments(args: argparse.Namespace) -> dict[str, Any]:
|
|
366
|
+
"""Read a file for ``store_file``: its bytes, name and content type.
|
|
390
367
|
|
|
391
|
-
|
|
368
|
+
:param args: the parsed ``store-file`` command
|
|
369
|
+
:returns: the arguments of the tool
|
|
370
|
+
:raises CLIError: when the file cannot be read
|
|
371
|
+
"""
|
|
392
372
|
try:
|
|
393
373
|
data = args.file.read_bytes()
|
|
394
374
|
except OSError as exc:
|
|
395
375
|
raise CLIError(f"could not read file {args.file}: {exc}") from exc
|
|
396
376
|
mime = args.mime or mimetypes.guess_type(args.file.name)[0]
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
"cove": args.cove,
|
|
377
|
+
return {
|
|
378
|
+
"space": args.space,
|
|
379
|
+
"filename": args.file.name,
|
|
401
380
|
"data_base64": base64.b64encode(data).decode("ascii"),
|
|
402
|
-
"mime": mime,
|
|
381
|
+
"mime": mime or "application/octet-stream",
|
|
403
382
|
"description": args.description,
|
|
404
|
-
"
|
|
383
|
+
"engram": args.engram,
|
|
405
384
|
}
|
|
406
|
-
if not image:
|
|
407
|
-
result["filename"] = args.file.name
|
|
408
|
-
return result
|
|
409
385
|
|
|
410
386
|
|
|
411
|
-
def
|
|
412
|
-
"""
|
|
387
|
+
def _arguments(args: argparse.Namespace) -> dict[str, Any]:
|
|
388
|
+
"""Turn a parsed tool command into the tool's arguments, without ``reason``.
|
|
389
|
+
|
|
390
|
+
:param args: the parsed command
|
|
391
|
+
:returns: the arguments; optional ones that were not given are left out
|
|
392
|
+
:raises CLIError: when an argument cannot be used
|
|
393
|
+
"""
|
|
413
394
|
tool = args.tool
|
|
414
|
-
if tool
|
|
415
|
-
"
|
|
416
|
-
|
|
417
|
-
"
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
return tool, {"cove": args.cove, "paths": args.paths}
|
|
423
|
-
if tool == "search_pages":
|
|
424
|
-
return tool, {"query": args.query, "cove": args.cove, "limit": args.limit}
|
|
425
|
-
if tool == "read_page":
|
|
426
|
-
payload = {"cove": args.cove, "path": args.path}
|
|
427
|
-
if args.as_of is not None:
|
|
428
|
-
payload["as_of"] = args.as_of
|
|
429
|
-
return tool, payload
|
|
430
|
-
if tool == "whats_new":
|
|
431
|
-
return tool, {"since": args.since} if args.since is not None else {}
|
|
432
|
-
if tool == "create_cove":
|
|
433
|
-
return tool, {"slug": args.slug}
|
|
434
|
-
if tool in {"invite", "invite_to_reef"}:
|
|
435
|
-
payload = {"email": args.email, "display_name": args.display_name}
|
|
436
|
-
if tool == "invite":
|
|
437
|
-
payload["cove"] = args.cove
|
|
438
|
-
payload["role"] = args.role
|
|
439
|
-
return tool, payload
|
|
440
|
-
if tool == "remove_member":
|
|
441
|
-
return tool, {"cove": args.cove, "email": args.email}
|
|
442
|
-
if tool == "rename_cove":
|
|
443
|
-
return tool, {"cove": args.cove, "new_name": args.new_name}
|
|
444
|
-
if tool in {"leave_cove", "delete_cove"}:
|
|
445
|
-
return tool, {"cove": args.cove}
|
|
395
|
+
if tool == "recall":
|
|
396
|
+
return {"question": args.question, "space": args.space, "limit": args.limit}
|
|
397
|
+
if tool == "brief":
|
|
398
|
+
return {"topic": args.topic, "space": args.space, "entries": args.entries}
|
|
399
|
+
if tool == "open":
|
|
400
|
+
return {"refs": args.refs, "as_of": args.as_of}
|
|
401
|
+
if tool == "catch_up":
|
|
402
|
+
return {"since": args.since}
|
|
446
403
|
if tool == "remember":
|
|
447
404
|
fact = sys.stdin.read() if args.fact == "-" else args.fact
|
|
448
|
-
return
|
|
449
|
-
if tool == "
|
|
450
|
-
return
|
|
451
|
-
"
|
|
452
|
-
"
|
|
453
|
-
"
|
|
454
|
-
"
|
|
455
|
-
"title": args.title,
|
|
456
|
-
"tags": args.tags,
|
|
457
|
-
"expected_version": args.expected_version,
|
|
405
|
+
return {"fact": fact, "space": args.space}
|
|
406
|
+
if tool == "log":
|
|
407
|
+
return {
|
|
408
|
+
"space": args.space,
|
|
409
|
+
"engram": args.engram,
|
|
410
|
+
"heading": args.heading,
|
|
411
|
+
"entry": _text_source(args.entry, args.entry_file, "entry"),
|
|
458
412
|
}
|
|
459
|
-
if tool == "
|
|
460
|
-
|
|
461
|
-
if not isinstance(
|
|
462
|
-
raise CLIError("write
|
|
463
|
-
return
|
|
464
|
-
if tool == "
|
|
465
|
-
return
|
|
466
|
-
|
|
467
|
-
|
|
413
|
+
if tool == "write":
|
|
414
|
+
engrams = _json_source(args.engrams)
|
|
415
|
+
if not isinstance(engrams, list):
|
|
416
|
+
raise CLIError("write input must be a JSON array")
|
|
417
|
+
return {"space": args.space, "engrams": engrams, "message": args.message}
|
|
418
|
+
if tool == "store_file":
|
|
419
|
+
return _file_arguments(args)
|
|
420
|
+
if tool == "correct":
|
|
421
|
+
return {
|
|
422
|
+
"space": args.space,
|
|
423
|
+
"engram": args.engram,
|
|
468
424
|
"old_text": _text_source(args.old_text, args.old_text_file, "old-text"),
|
|
469
425
|
"new_text": _text_source(args.new_text, args.new_text_file, "new-text"),
|
|
470
426
|
"message": args.message,
|
|
471
427
|
"expected_version": args.expected_version,
|
|
472
428
|
}
|
|
473
|
-
if tool == "
|
|
474
|
-
return
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
"
|
|
478
|
-
"
|
|
429
|
+
if tool == "undo":
|
|
430
|
+
return {"space": args.space, "engram": args.engram, "version": args.version}
|
|
431
|
+
if tool == "forget":
|
|
432
|
+
return {
|
|
433
|
+
"space": args.space,
|
|
434
|
+
"engram": args.engram,
|
|
435
|
+
"file": args.file,
|
|
479
436
|
"confirm": args.confirm,
|
|
480
437
|
}
|
|
481
|
-
if tool == "
|
|
438
|
+
if tool == "share":
|
|
482
439
|
if args.section is not None and args.section_file is not None:
|
|
483
440
|
raise CLIError("use only one of --section and --section-file")
|
|
484
441
|
section = None
|
|
485
442
|
if args.section is not None or args.section_file is not None:
|
|
486
443
|
section = _text_source(args.section, args.section_file, "section")
|
|
487
|
-
return
|
|
488
|
-
"
|
|
489
|
-
"
|
|
444
|
+
return {
|
|
445
|
+
"engram": args.engram,
|
|
446
|
+
"to_space": args.to_space,
|
|
490
447
|
"section": section,
|
|
491
|
-
"
|
|
448
|
+
"to_path": args.to_path,
|
|
449
|
+
"confirm": args.confirm,
|
|
450
|
+
}
|
|
451
|
+
if tool == "instruct":
|
|
452
|
+
return {
|
|
453
|
+
"body": _text_source(args.body, args.body_file, "body"),
|
|
454
|
+
"confirm": args.confirm,
|
|
492
455
|
}
|
|
493
|
-
if tool == "
|
|
494
|
-
return
|
|
495
|
-
if tool == "
|
|
496
|
-
return
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
456
|
+
if tool == "search":
|
|
457
|
+
return {"query": args.query}
|
|
458
|
+
if tool == "fetch":
|
|
459
|
+
return {"id": args.id}
|
|
460
|
+
return {}
|
|
461
|
+
|
|
462
|
+
|
|
463
|
+
def tool_call(args: argparse.Namespace) -> tuple[str, dict[str, Any]]:
|
|
464
|
+
"""Translate one parsed named command into its exact MCP call.
|
|
465
|
+
|
|
466
|
+
:param args: the parsed command
|
|
467
|
+
:returns: the tool's name and its arguments: ``reason`` first, when the
|
|
468
|
+
tool takes one, then every argument that was given
|
|
469
|
+
:raises CLIError: when an argument cannot be used
|
|
470
|
+
"""
|
|
471
|
+
tool = args.tool
|
|
472
|
+
arguments = {k: v for k, v in _arguments(args).items() if v is not None}
|
|
473
|
+
if tool not in {"search", "fetch"}:
|
|
474
|
+
arguments = {"reason": args.reason, **arguments}
|
|
475
|
+
return tool, arguments
|
|
502
476
|
|
|
503
477
|
|
|
504
478
|
def _jsonable(value: Any) -> Any:
|
|
File without changes
|
|
File without changes
|
|
File without changes
|