projects_cmd.py 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241
  1. """``hermes project`` CLI — manage first-class, multi-folder Projects."""
  2. from __future__ import annotations
  3. import argparse
  4. import functools
  5. import sys
  6. from hermes_cli import projects_db as pdb
  7. def build_parser(parent_subparsers: argparse._SubParsersAction) -> argparse.ArgumentParser:
  8. """Attach the ``project`` subcommand tree. Returns the top parser."""
  9. parser = parent_subparsers.add_parser(
  10. "project",
  11. help="Manage projects (named, multi-folder workspaces)",
  12. description=(
  13. "Projects are human-named workspaces that can span multiple "
  14. "folders / repos. They anchor desktop session grouping and, when "
  15. "bound to a kanban board, give tasks a deterministic worktree + "
  16. "branch convention. State is per-profile."
  17. ),
  18. )
  19. sub = parser.add_subparsers(dest="project_action")
  20. p_create = sub.add_parser("create", help="Create a new project")
  21. p_create.add_argument("name", help="Human name, e.g. 'Hermes Agent'")
  22. p_create.add_argument("folders", nargs="*", help="Folder paths to include (first = primary)")
  23. p_create.add_argument("--slug", default=None, help="Explicit slug override")
  24. p_create.add_argument("--primary", default=None, metavar="PATH", help="Primary repo path")
  25. for opt in ("--description", "--icon", "--color"):
  26. p_create.add_argument(opt, default=None)
  27. p_create.add_argument("--board", default=None, metavar="SLUG", help="Bind a kanban board")
  28. p_create.add_argument("--use", action="store_true", help="Set as the active project")
  29. p_list = sub.add_parser("list", aliases=["ls"], help="List projects")
  30. p_list.add_argument("--all", action="store_true", dest="include_archived", help="Include archived projects")
  31. def project_sub(name: str, help: str) -> argparse.ArgumentParser:
  32. sp = sub.add_parser(name, help=help)
  33. sp.add_argument("project", help="Project id or slug")
  34. return sp
  35. project_sub("show", "Show a project's details")
  36. p_add = project_sub("add-folder", "Add a folder to a project")
  37. p_add.add_argument("path", help="Folder path")
  38. p_add.add_argument("--label", default=None)
  39. p_add.add_argument("--primary", action="store_true", help="Mark as primary repo")
  40. project_sub("remove-folder", "Remove a folder from a project").add_argument("path", help="Folder path")
  41. project_sub("rename", "Rename a project").add_argument("name", help="New name")
  42. project_sub("set-primary", "Set the primary folder").add_argument("path", help="Folder path (must already be in project)")
  43. p_use = sub.add_parser("use", help="Set the active project")
  44. p_use.add_argument("project", nargs="?", default=None, help="Project id or slug (omit to clear)")
  45. project_sub("archive", "Archive a project")
  46. project_sub("restore", "Restore an archived project")
  47. project_sub("bind-board", "Bind a kanban board to a project").add_argument(
  48. "board", nargs="?", default="", help="Board slug (omit to unbind)"
  49. )
  50. parser.set_defaults(_project_parser=parser)
  51. return parser
  52. def projects_command(args: argparse.Namespace) -> int:
  53. """Entry point from ``hermes project …`` argparse dispatch."""
  54. action = getattr(args, "project_action", None)
  55. if not action:
  56. parser = getattr(args, "_project_parser", None)
  57. if parser is not None:
  58. parser.print_help()
  59. else:
  60. print("usage: hermes project <action> [options]\nRun 'hermes project --help' for the full list.", file=sys.stderr)
  61. return 0
  62. handler = _HANDLERS.get(action)
  63. if handler is None:
  64. print(f"Unknown project action: {action}", file=sys.stderr)
  65. return 1
  66. return handler(args)
  67. def _err(message: str) -> int:
  68. print(f"project: {message}", file=sys.stderr)
  69. return 1
  70. def _resolve(conn, ident: str):
  71. proj = pdb.get_project(conn, ident)
  72. if proj is None:
  73. _err(f"no such project: {ident}")
  74. return proj
  75. def _db_command(fn):
  76. """Open the DB and run ``fn(args, conn)``; a ``str`` result is printed (rc 0), an ``int`` is the rc;
  77. a ``ValueError`` prints ``project: …`` and exits 2."""
  78. @functools.wraps(fn)
  79. def wrapper(args: argparse.Namespace) -> int:
  80. try:
  81. with pdb.connect_closing() as conn:
  82. out = fn(args, conn)
  83. except ValueError as exc:
  84. print(f"project: {exc}", file=sys.stderr)
  85. return 2
  86. if isinstance(out, str):
  87. print(out)
  88. return 0
  89. return out
  90. return wrapper
  91. def _with_project(fn):
  92. """Like ``_db_command`` but also resolves ``args.project`` into ``fn(args, conn, proj)``."""
  93. @functools.wraps(fn)
  94. def wrapper(args: argparse.Namespace, conn):
  95. proj = _resolve(conn, args.project)
  96. return 1 if proj is None else fn(args, conn, proj)
  97. return _db_command(wrapper)
  98. def _print_project(proj) -> None:
  99. print(f"{proj.slug} [{proj.id}]{' (archived)' if proj.archived else ''}")
  100. print(f" name: {proj.name}")
  101. for label, value in (("about", proj.description), ("board", proj.board_slug), ("primary", proj.primary_path)):
  102. if value:
  103. print(f" {label}:{' ' * (8 - len(label))}{value}")
  104. if proj.folders:
  105. print(" folders:")
  106. for f in proj.folders:
  107. print(f" {' *' if f.is_primary else ' '} {f.path}{f' ({f.label})' if f.label else ''}")
  108. @_db_command
  109. def _cmd_create(args, conn) -> int:
  110. pid = pdb.create_project(
  111. conn, name=args.name, slug=args.slug, folders=args.folders, primary_path=args.primary,
  112. description=args.description, icon=args.icon, color=args.color, board_slug=args.board,
  113. )
  114. if args.use:
  115. pdb.set_active(conn, pid)
  116. proj = pdb.get_project(conn, pid)
  117. if proj is None:
  118. print("project: vanished after create", file=sys.stderr)
  119. return 2
  120. print(f"Created project {proj.slug} ({pid})")
  121. _print_project(proj)
  122. return 0
  123. @_db_command
  124. def _cmd_list(args, conn):
  125. active = pdb.get_active_id(conn)
  126. projs = pdb.list_projects(conn, include_archived=getattr(args, "include_archived", False))
  127. if not projs:
  128. return "No projects yet. Create one with `hermes project create <name>`."
  129. for p in projs:
  130. flags = " (archived)" if p.archived else ""
  131. print(f"{'*' if p.id == active else ' '} {p.slug:<24} {p.name}{flags} [{len(p.folders)} folder(s)]")
  132. return 0
  133. @_with_project
  134. def _cmd_show(args, conn, proj) -> int:
  135. _print_project(proj)
  136. return 0
  137. @_with_project
  138. def _cmd_add_folder(args, conn, proj) -> str:
  139. path = pdb.add_folder(conn, proj.id, args.path, label=args.label, is_primary=args.primary)
  140. return f"Added {path} to {proj.slug}"
  141. @_with_project
  142. def _cmd_remove_folder(args, conn, proj):
  143. if not pdb.remove_folder(conn, proj.id, args.path):
  144. return _err(f"folder not in project: {args.path}")
  145. return f"Removed {args.path} from {proj.slug}"
  146. @_with_project
  147. def _cmd_rename(args, conn, proj) -> str:
  148. pdb.update_project(conn, proj.id, name=args.name)
  149. return f"Renamed {proj.slug} -> {args.name}"
  150. @_with_project
  151. def _cmd_set_primary(args, conn, proj):
  152. if not pdb.set_primary(conn, proj.id, args.path):
  153. return _err(f"'{args.path}' is not a folder of {proj.slug}; add it first with `hermes project add-folder`.")
  154. return f"Set primary of {proj.slug} -> {args.path}"
  155. @_db_command
  156. def _cmd_use(args, conn):
  157. if not args.project:
  158. pdb.set_active(conn, None)
  159. return "Cleared active project"
  160. proj = _resolve(conn, args.project)
  161. if proj is None:
  162. return 1
  163. pdb.set_active(conn, proj.id)
  164. return f"Active project: {proj.slug}"
  165. def _flag_command(op: str, verb: str):
  166. """Handler for ``pdb.<op>(conn, proj.id)`` followed by ``"<verb> <slug>"``."""
  167. return _with_project(lambda args, conn, proj: (getattr(pdb, op)(conn, proj.id), f"{verb} {proj.slug}")[1])
  168. @_with_project
  169. def _cmd_bind_board(args, conn, proj) -> str:
  170. pdb.update_project(conn, proj.id, board_slug=args.board)
  171. if not args.board.strip():
  172. return f"Unbound board from {proj.slug}"
  173. if proj.primary_path: # best-effort: point the bound board's default_workdir at the primary repo
  174. try:
  175. from hermes_cli import kanban_db as kb
  176. slug = kb._normalize_board_slug(args.board)
  177. if slug and (slug == kb.DEFAULT_BOARD or kb.board_exists(slug)):
  178. kb.write_board_metadata(slug, default_workdir=proj.primary_path)
  179. except Exception:
  180. pass
  181. return f"Bound {proj.slug} -> board {args.board}"
  182. _HANDLERS = {
  183. "create": _cmd_create,
  184. "list": _cmd_list,
  185. "ls": _cmd_list,
  186. "show": _cmd_show,
  187. "add-folder": _cmd_add_folder,
  188. "remove-folder": _cmd_remove_folder,
  189. "rename": _cmd_rename,
  190. "set-primary": _cmd_set_primary,
  191. "use": _cmd_use,
  192. "archive": _flag_command("archive_project", "Archived"),
  193. "restore": _flag_command("restore_project", "Restored"),
  194. "bind-board": _cmd_bind_board,
  195. }