Files
claude-config/bin/project_record/main.py
T

103 lines
5.2 KiB
Python

"""Open one of a project's records as a file to read and edit, and save the edit.
usage: project-record open <record>
project-record save <record>
Run inside a checkout, or a worktree of one. <record> is one of decisions, score-anchors,
comprehension-history, reading-cost and changelog, each kept where the project's config names it,
or goals-and-audience, the goals file. Goals kept in a Jira epic's description are only read, so
save refuses them: edit the epic in Jira.
open prints the path of a file holding the record's text, and nothing else. Read and edit that
file. Where the record is kept as a file, the path is that file. Where it is kept elsewhere, the
path is a copy under ~/.local/state/project-record/<key>/<worktree>/, a folder named for the
worktree that ran open, so two worktrees of one project don't share a copy. The copy is written
afresh with the record as it stands, so open it again before each edit. open also removes the
folders of worktrees git no longer lists. A record that doesn't exist yet has no file at the path:
create it there.
save stores the file's text in the record, and prints one line saying so. Where the record is kept
as a file, there is nothing left to store, and save says so. Run it after every edit, so the same
steps work wherever a project keeps the record.
For a record kept on a Confluence page, save refuses where someone saved the page after open read
it, and the human decides what follows. The copy keeps the unsaved edit until open runs again and
writes the copy afresh.
Exit 2 on bad arguments, and 1, saying why, on any other failure.
"""
import hashlib
import pathlib
import shutil
import sys
from failure import Failure
from record_store.stores import FileStore, goals_store, local_file, RECORDS, RecordStore, store, stored
from git_cli.git_repo import git, Git
from project_config.main import located
from project_config.settings import ProjectConfig
# Not git's verbs, such as checkout and commit: those read as acting on the repo.
COMMANDS = ("open", "save")
# Where the copy of a record kept outside files goes, under the user's home, in a folder per project and worktree.
COPIES = ".local/state/project-record"
# The goals file opens like a record, though it is a setting of its own.
GOALS = "goals-and-audience"
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if len(argv) != 2 or argv[0] not in COMMANDS or argv[1] not in (*RECORDS, GOALS):
print(f"usage: project-record {'|'.join(COMMANDS)} <record>, where <record> is one of {', '.join((*RECORDS, GOALS))}", file=sys.stderr)
return 2
home = pathlib.Path.home()
config = located(None, home)
done = config if isinstance(config, Failure) else performed(config, argv[0], argv[1], home)
if isinstance(done, Failure):
print(f"project-record: {done.reason}", file=sys.stderr)
return 1
print(done)
return 0
def performed(config: ProjectConfig, command: str, name: str, home: pathlib.Path, run: Git = git) -> str | Failure:
"""What command, one of COMMANDS, prints for the record called name. An open also prunes the copies of removed worktrees."""
if command == "open":
pruned(config, home, run)
return act(command, *opened(config, name, home))
def opened(config: ProjectConfig, name: str, home: pathlib.Path) -> tuple[RecordStore, pathlib.Path]:
"""The store of the record called name, and the copy it gets where it isn't kept as a file. `local_file` keeps the version beside the copy, for a later save."""
copy = home / COPIES / config.key / worktree_folder(config.top) / f"{name}.md"
return (goals_store(config) if name == GOALS else store(config, name)), copy
def worktree_folder(top: pathlib.Path) -> str:
"""The name of the folder that holds the copies of the worktree at top: the worktree's own name, for a reader, and a hash of its path, since two worktrees in different folders may share a name."""
return f"{top.name}-{hashlib.sha256(str(top).encode()).hexdigest()[:8]}"
def pruned(config: ProjectConfig, home: pathlib.Path, run: Git = git) -> None:
"""Remove the copies of the worktrees git no longer lists, so the folders don't pile up one per chunk. Best effort: a folder that stays only takes disk, and where git can't list the worktrees nothing is removed."""
listed = run("worktree", "list", "--porcelain")
folders = home / COPIES / config.key
if isinstance(listed, Failure) or not folders.is_dir():
return
worktrees = [config.top, *(pathlib.Path(line.removeprefix("worktree ")) for line in listed.splitlines() if line.startswith("worktree "))]
kept = {worktree_folder(worktree) for worktree in worktrees}
for stale in (folder for folder in folders.iterdir() if folder.is_dir() and folder.name not in kept):
shutil.rmtree(stale, ignore_errors=True)
def act(command: str, record: RecordStore, copy: pathlib.Path) -> str | Failure:
"""What command, one of COMMANDS, prints for record. copy is where a record kept outside files gets its file."""
if command == "open":
opened = local_file(record, copy)
return opened if isinstance(opened, Failure) else str(opened)
if unstored := stored(record, copy):
return unstored
return f"{record.path} is the record itself, so nothing is left to store." if isinstance(record, FileStore) else f"Stored {copy} in {record.label}."