103 lines
5.2 KiB
Python
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}."
|