| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200 |
- """Board metadata (``board.json``) and board lifecycle management for the Kanban DB:
- read/write of per-board display metadata, board creation/discovery/archival, and the
- ``board.json``-as-identity-marker rule.
- Split out of ``hermes_cli.kanban_db``; origin-resident helpers are reached
- late-bound via ``_kb`` (import-cycle breaking) so monkeypatching
- ``kanban_db.<name>`` keeps working.
- """
- from __future__ import annotations
- import json
- import time
- from typing import Any
- from typing import Optional
- from pathlib import Path
- def _dir_holds_board(d: Path) -> bool:
- # ``board.json`` is the identity marker: archive/hard-delete both leave the
- # directory without it, and a stale ``connect(board=slug)`` used to leave a
- # ``kanban.db``-only stub that resurfaced in the board list as an empty
- # active board (#43243). Discovery must therefore require the metadata
- # file; a DB-only directory is a stub to ignore, never a board.
- return (d / "board.json").exists()
- def board_metadata_path(board: Optional[str] = None) -> Path:
- """``board.json`` path — display metadata only; the directory slug is the identity."""
- return _kb.board_dir(_kb._slug_or_default(board)) / "board.json"
- def _default_board_display_name(slug: str) -> str:
- """``atm10-server`` -> ``Atm10 Server``."""
- return " ".join(part.capitalize() for part in slug.replace("_", "-").split("-") if part) or slug
- def read_board_metadata(board: Optional[str] = None) -> dict:
- """``board.json`` merged over defaults, plus ``slug`` and ``db_path``. Never
- raises — a missing/malformed file yields the synthesized entry."""
- slug = _kb._slug_or_default(board)
- meta: dict[str, Any] = {
- "slug": slug,
- "name": _default_board_display_name(slug),
- "description": "",
- "icon": "",
- "color": "",
- "default_workdir": None,
- # Project scope: new tasks inherit it (deterministic worktree + branch).
- "project_id": None,
- "created_at": None,
- "archived": False,
- }
- try:
- p = board_metadata_path(slug)
- if p.exists():
- raw = json.loads(p.read_text(encoding="utf-8-sig"))
- if isinstance(raw, dict):
- # Never let the metadata file claim a different slug than
- # its directory — trust the filesystem.
- raw["slug"] = slug
- meta.update(raw)
- except (OSError, json.JSONDecodeError):
- pass
- meta["db_path"] = str(_kb.kanban_db_path(slug))
- return meta
- def write_board_metadata(
- board: Optional[str], *, name: Optional[str] = None, description: Optional[str] = None,
- icon: Optional[str] = None, color: Optional[str] = None, archived: Optional[bool] = None,
- default_workdir: Optional[str] = None, project_id: Optional[str] = None,
- ) -> dict:
- """Create/update ``board.json``; unmentioned fields are preserved, ``created_at``
- set on first write. ``project_id``/``default_workdir``: ``None`` = unchanged,
- "" = clear (``project_id`` is not validated here)."""
- _kb._assert_not_delegated_child_mutation()
- slug = _kb._slug_or_default(board)
- meta = read_board_metadata(slug)
- # db_path is derived on every read; never persist it into board.json.
- meta.pop("db_path", None)
- if name is not None:
- meta["name"] = str(name).strip() or _default_board_display_name(slug)
- for key, value in (("description", description), ("icon", icon), ("color", color)):
- if value is not None:
- meta[key] = str(value)
- if archived is not None:
- meta["archived"] = bool(archived)
- for key, value in (("default_workdir", default_workdir), ("project_id", project_id)):
- if value is not None:
- meta[key] = str(value) if value else None
- if not meta.get("created_at"):
- meta["created_at"] = int(time.time())
- path = board_metadata_path(slug)
- path.parent.mkdir(parents=True, exist_ok=True)
- path.write_text(
- json.dumps(meta, indent=2, ensure_ascii=False) + "\n", encoding="utf-8",
- )
- meta["db_path"] = str(_kb.kanban_db_path(slug))
- return meta
- def create_board(
- slug: str, *, name: Optional[str] = None, description: Optional[str] = None,
- icon: Optional[str] = None, color: Optional[str] = None, default_workdir: Optional[str] = None,
- project_id: Optional[str] = None,
- ) -> dict:
- """Create board dir + DB + metadata (``mkdir -p`` semantics: existing board returns its metadata)."""
- normed = _kb._require_slug(slug)
- # Explicit creation clears any archived tombstone at this slug (left by
- # remove_board(archive=True)) — otherwise _kb.init_db() below would rightly
- # refuse to recreate the archived board's DB (#43243).
- meta = write_board_metadata(
- normed, name=name, description=description, icon=icon, color=color,
- default_workdir=default_workdir, project_id=project_id, archived=False,
- )
- # Touch the DB so list_boards() sees it immediately.
- _kb.init_db(board=normed)
- return meta
- def list_boards(*, include_archived: bool = True) -> list[dict]:
- """Metadata for every board: ``default`` first (always present), then
- ``boards/<slug>/`` dirs holding a ``kanban.db`` or ``board.json``, sorted."""
- entries = [read_board_metadata(_kb.DEFAULT_BOARD)]
- seen = {_kb.DEFAULT_BOARD}
- root = _kb.boards_root()
- if root.is_dir():
- for child in sorted(root.iterdir(), key=lambda p: p.name.lower()):
- if not child.is_dir():
- continue
- try:
- normed = _kb._normalize_board_slug(child.name) # skip junk dirs, don't raise
- except ValueError:
- continue
- if not normed or normed in seen or not _dir_holds_board(child):
- continue
- meta = read_board_metadata(normed)
- if meta.get("archived") and not include_archived:
- continue
- entries.append(meta)
- seen.add(normed)
- return entries
- def remove_board(slug: str, *, archive: bool = True) -> dict:
- """Archive (to ``boards/_archived/<slug>-<ts>/``) or delete a board;
- ``default`` cannot be removed. Returns ``{"slug", "action", "new_path"}``."""
- _kb._assert_not_delegated_child_mutation()
- normed = _kb._require_slug(slug)
- if normed == _kb.DEFAULT_BOARD:
- raise ValueError("the 'default' board cannot be removed")
- d = _kb.board_dir(normed)
- if not d.exists():
- raise ValueError(f"board {normed!r} does not exist")
- # If the user removed the currently-active board, revert to default.
- if _kb.get_current_board() == normed:
- _kb.clear_current_board()
- # A concurrent connect() after the rename recreates an empty DB file; drop
- # the init cache first so the schema pass re-runs on it.
- _kb._INITIALIZED_PATHS.discard(str((d / "kanban.db").resolve()))
- if archive:
- # Capture display metadata before the move so the tombstone below keeps
- # the user's board name instead of falling back to a title-cased slug.
- prior_meta = read_board_metadata(normed)
- archive_root = _kb.boards_root() / "_archived"
- archive_root.mkdir(parents=True, exist_ok=True)
- ts = int(time.time())
- target = archive_root / f"{normed}-{ts}"
- suffix = 1
- while target.exists(): # rapid double-archive
- target = archive_root / f"{normed}-{ts}-{suffix}"
- suffix += 1
- d.rename(target)
- # Leave an ``archived`` tombstone at the original slug. Stale dashboard
- # tabs / gateway pollers can keep calling connect(board=slug) after the
- # archive; without a marker the resurrect-guard cannot tell an archived
- # slug from a brand-new one and an empty board would reappear (#43243).
- write_board_metadata(
- normed,
- name=prior_meta.get("name"),
- description=prior_meta.get("description"),
- icon=prior_meta.get("icon"),
- color=prior_meta.get("color"),
- default_workdir=prior_meta.get("default_workdir"),
- project_id=prior_meta.get("project_id"),
- archived=True,
- )
- return {"slug": normed, "action": "archived", "new_path": str(target)}
- import shutil
- shutil.rmtree(d)
- return {"slug": normed, "action": "deleted", "new_path": ""}
- # Late-bound origin namespace (see module docstring); imported LAST so this
- # module is fully populated before ``kanban_db`` imports from it.
- from hermes_cli import kanban_db as _kb
|