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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: reef-cli
3
- Version: 1.0.0
3
+ Version: 2.0.0
4
4
  Summary: Command-line client for reef — shared, living memory for people and their AI assistants
5
5
  Keywords: mcp,memory,cli,reef
6
6
  Author: WOUTER DURNEZ
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "reef-cli"
3
- version = "1.0.0"
3
+ version = "2.0.0"
4
4
  description = "Command-line client for reef — shared, living memory for people and their AI assistants"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "reef-cli"
3
- version = "1.0.0"
3
+ version = "2.0.0"
4
4
  description = "Command-line client for reef — shared, living memory for people and their AI assistants"
5
5
  readme = "README.md"
6
6
  authors = [
@@ -251,254 +251,228 @@ def build_parser() -> argparse.ArgumentParser:
251
251
  help="JSON object, @file, or '-' for stdin (default: {})",
252
252
  )
253
253
 
254
- _tool_parser(sub, "load_index", "load the body-free memory index")
255
- read_pages = _tool_parser(sub, "read_pages", "read several pages from one cove")
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
- delete_page = _tool_parser(
319
- sub, "delete_page", "permanently delete a page and its history"
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
- delete_page.add_argument("cove")
322
- delete_page.add_argument("path")
323
-
324
- writes = _tool_parser(sub, "write_pages", "atomically write up to 20 pages")
325
- writes.add_argument("cove")
326
- writes.add_argument("pages", help="JSON array, @file, or '-' for stdin")
327
- writes.add_argument("--message", default="")
328
-
329
- edit = _tool_parser(sub, "edit_page_section", "replace one exact page span")
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
- action="store_true",
343
- help="confirm that the user agreed to this persona change",
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
- prepare = _tool_parser(
347
- sub, "prepare_to_share", "stage personal content for sharing"
348
- )
349
- prepare.add_argument("path")
350
- prepare.add_argument("dest_cove")
351
- prepare.add_argument("--section")
352
- prepare.add_argument("--section-file")
353
- prepare.add_argument("--dest-path")
354
- confirm = _tool_parser(sub, "confirm_share", "execute a staged share")
355
- confirm.add_argument("nonce")
356
-
357
- add_file = _tool_parser(
358
- sub, "add_file", "upload a file with a searchable description"
359
- )
360
- add_file.add_argument("cove")
361
- add_file.add_argument("file", type=Path)
362
- add_file.add_argument("--mime")
363
- add_file.add_argument("--description", required=True)
364
- add_file.add_argument("--page-path")
365
- read_file = _tool_parser(sub, "read_file", "get file metadata and a signed URL")
366
- read_file.add_argument("cove")
367
- read_file.add_argument("key")
368
- delete_file = _tool_parser(sub, "delete_file", "permanently delete a stored file")
369
- delete_file.add_argument("cove")
370
- delete_file.add_argument("key")
371
-
372
- add_image = _tool_parser(
373
- sub, "add_image", "compatibility alias for uploading an image"
374
- )
375
- add_image.add_argument("cove")
376
- add_image.add_argument("file", type=Path)
377
- add_image.add_argument("--mime")
378
- add_image.add_argument("--description", required=True)
379
- add_image.add_argument("--page-path")
380
- read_image = _tool_parser(sub, "read_image", "compatibility alias for read-file")
381
- read_image.add_argument("cove")
382
- read_image.add_argument("key")
383
- delete_image = _tool_parser(
384
- sub, "delete_image", "compatibility alias for delete-file"
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
- delete_image.add_argument("cove")
387
- delete_image.add_argument("key")
388
- return parser
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
- def _file_arguments(args: argparse.Namespace, *, image: bool = False) -> dict[str, Any]:
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
- if mime is None:
398
- mime = "application/octet-stream"
399
- result = {
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
- "page_path": args.page_path,
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 tool_call(args: argparse.Namespace) -> tuple[str, dict[str, Any]]:
412
- """Translate one parsed named command into its exact MCP call."""
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 in {
415
- "load_index",
416
- "load_all_context",
417
- "get_operating_protocol",
418
- "list_coves",
419
- }:
420
- return tool, {}
421
- if tool == "read_pages":
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 tool, {"fact": fact, "cove": args.cove}
449
- if tool == "write_page":
450
- return tool, {
451
- "cove": args.cove,
452
- "path": args.path,
453
- "body": _text_source(args.body, args.body_file, "body"),
454
- "message": args.message,
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 == "write_pages":
460
- pages = _json_source(args.pages)
461
- if not isinstance(pages, list):
462
- raise CLIError("write-pages input must be a JSON array")
463
- return tool, {"cove": args.cove, "pages": pages, "message": args.message}
464
- if tool == "edit_page_section":
465
- return tool, {
466
- "cove": args.cove,
467
- "path": args.path,
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 == "update_meta_page":
474
- return tool, {
475
- "cove": "personal",
476
- "path": "meta/persona.md",
477
- "body": _text_source(args.body, args.body_file, "body"),
478
- "message": args.message,
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 == "prepare_to_share":
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 tool, {
488
- "path": args.path,
489
- "dest_cove": args.dest_cove,
444
+ return {
445
+ "engram": args.engram,
446
+ "to_space": args.to_space,
490
447
  "section": section,
491
- "dest_path": args.dest_path,
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 == "confirm_share":
494
- return tool, {"nonce": args.nonce}
495
- if tool == "add_file":
496
- return tool, _file_arguments(args)
497
- if tool == "add_image":
498
- return tool, _file_arguments(args, image=True)
499
- if tool in {"read_file", "delete_file", "read_image", "delete_image"}:
500
- return tool, {"cove": args.cove, "key": args.key}
501
- raise CLIError(f"unsupported command: {tool}")
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