Track the do_epic package, which the gitignore allowlist left out

This commit is contained in:
2026-11-18 09:56:02 +01:00
parent 4678ac6798
commit e2977b4946
4 changed files with 167 additions and 0 deletions
+2
View File
@@ -53,6 +53,8 @@
!bin/deploy-release
!bin/deploy_release/
!bin/deploy_release/*.py
!bin/do_epic/
!bin/do_epic/*.py
!bin/failure.py
!bin/forge/
!bin/forge/*.py
View File
+72
View File
@@ -0,0 +1,72 @@
"""do-epic's machine-wide settings: `~/.claude-projects/do-epic/config.toml`, and `repo-rule.md` beside it.
One pair per machine, the same for every epic (docs/decisions.md → `do-epic: drives one Jira epic …`). The config is TOML:
jira-url = "https://acme.atlassian.net"
env-file = "~/.secrets/acme-jira.env"
repoless-model = "claude-opus-5-5"
clone-folder = "~/code"
language = "Swedish"
`jira-url` is the Jira site's address, only https. `env-file` is the file of Jira credentials, a path that starts with / or ~/ and lies outside `~/.claude-projects` and the clone folder, so that no git remote receives them. `repoless-model` is the model that works an epic item with no repo. `clone-folder` is the folder a missing repo is cloned into; `~/code` where left out. `language` is the default language of Jira text, by its English name; English where left out. `repo-rule.md` is prose that says how to tell an item's repo."""
import dataclasses
import pathlib
import re
from failure import Failure
from project_config.settings import anywhere, CONFIG, DO_EPIC, ENV_FILE, language_fault, LANGUAGE, lies_in, parsed, PROJECTS, SITE
REPO_RULE = "repo-rule.md"
# Three readers, seated as the human who writes this config, picked these spellings from four candidates each, 3-0: `jira-url` over `site`, `clone-folder` over `repos-folder` (which reads as the folder of repos that already exist) and `repoless-model` over `no-repo-model`. `env-file` and `language` keep the names a project's config gives them.
JIRA_URL = "jira-url"
REPOLESS_MODEL = "repoless-model"
CLONE_FOLDER = "clone-folder"
SETTINGS = (JIRA_URL, ENV_FILE, REPOLESS_MODEL)
OPTIONAL = (CLONE_FOLDER, LANGUAGE)
# A model id as Claude Code takes it, such as claude-opus-5-5 or claude-sonnet-4-5-20250929.
MODEL_ID = re.compile(r"claude-[a-z]+-[0-9]+(?:-[0-9]+)*")
@dataclasses.dataclass(frozen=True)
class DoEpicConfig:
"""folder is `~/.claude-projects/do-epic`; repo_rule is `repo-rule.md`'s text."""
folder: pathlib.Path
jira_url: str
env_file: pathlib.Path
clone_folder: pathlib.Path
language: str
repoless_model: str
repo_rule: str
def load(home: pathlib.Path) -> DoEpicConfig | Failure:
"""The settings and the repo rule under home; a Failure naming each missing or misspelt one, so that do-epic refuses to start."""
folder = home / PROJECTS / DO_EPIC
values = parsed(folder / CONFIG)
if isinstance(values, Failure):
return values
try:
rule = (folder / REPO_RULE).read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"cannot read {folder / REPO_RULE}: {failure}")
clone_folder = anywhere(values.get(CLONE_FOLDER, "~/code"), home)
env_file = anywhere(values.get(ENV_FILE), home)
language = values.get(LANGUAGE, "English")
url, model = values.get(JIRA_URL), values.get(REPOLESS_MODEL)
faults = [
*(f"`{name}` is missing" for name in SETTINGS if name not in values),
*(f"`{name}` is not a setting" for name in values if name not in (*SETTINGS, *OPTIONAL)),
*([f"`{JIRA_URL}` is {url!r}, not a site's https address without a path, such as \"https://acme.atlassian.net\""] if JIRA_URL in values and not (isinstance(url, str) and re.fullmatch(SITE, url)) else []),
*([f"`{CLONE_FOLDER}` is {values[CLONE_FOLDER]!r}, not a path that starts with / or ~/"] if clone_folder is None else []),
*([f"`{ENV_FILE}` is {values[ENV_FILE]!r}, not a path that starts with / or ~/"] if ENV_FILE in values and env_file is None else []),
# lies_in resolves both sides, so a symlink can't lead the file into a place it must stay out of.
*([f"`{ENV_FILE}` is {values[ENV_FILE]!r}, inside ~/{PROJECTS} or the clone folder, which a git remote may receive"] if env_file and lies_in(env_file, home / PROJECTS, *([clone_folder] if clone_folder else [])) else []),
*([f"`{LANGUAGE}` is {language!r}, {fault}"] if LANGUAGE in values and (fault := language_fault(language)) else []),
*([f"`{REPOLESS_MODEL}` is {model!r}, not a model id such as \"claude-opus-5-5\""] if REPOLESS_MODEL in values and not (isinstance(model, str) and MODEL_ID.fullmatch(model)) else []),
*([f"`{REPO_RULE}` is blank"] if not rule.strip() else []),
]
if faults:
return Failure(f"{folder}: {'; '.join(faults)}. The settings are {', '.join(SETTINGS)}, and optionally {' and '.join(OPTIONAL)}.")
# faults names a missing or misspelt value of each type asserted here.
assert clone_folder and env_file and isinstance(url, str) and isinstance(model, str) and isinstance(language, str)
return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule)
+93
View File
@@ -0,0 +1,93 @@
import pathlib
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.config import DoEpicConfig, load
from failure import Failure
SETTINGS = """jira-url = "https://acme.atlassian.net"
env-file = "~/jira.env"
repoless-model = "claude-opus-5-5"
"""
class ConfigTest(unittest.TestCase):
def setUp(self) -> None:
made = tempfile.TemporaryDirectory()
self.addCleanup(made.cleanup)
self.home = pathlib.Path(made.name).resolve()
self.folder = self.home / ".claude-projects" / "do-epic"
self.folder.mkdir(parents=True)
def write(self, settings: str | None = SETTINGS, rule: str | None = "A label that equals a repo's name names that repo.\n") -> None:
if settings is not None:
(self.folder / "config.toml").write_text(settings, encoding="utf-8")
if rule is not None:
(self.folder / "repo-rule.md").write_text(rule, encoding="utf-8")
def failure(self) -> str:
found = load(self.home)
assert isinstance(found, Failure), found
return found.reason
def test_reads_the_settings_and_the_rule_and_defaults_the_clone_folder_and_language(self) -> None:
self.write()
self.assertEqual(load(self.home), DoEpicConfig(self.folder, "https://acme.atlassian.net", self.home / "jira.env", self.home / "code", "English", "claude-opus-5-5", "A label that equals a repo's name names that repo.\n"))
def test_reads_a_clone_folder_and_language_the_config_sets(self) -> None:
self.write(SETTINGS + 'clone-folder = "/srv/repos"\nlanguage = "Brazilian Portuguese"\n')
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual((found.clone_folder, found.language), (pathlib.Path("/srv/repos"), "Brazilian Portuguese"))
def test_refuses_while_the_config_is_missing(self) -> None:
self.write(None)
self.assertIn(f"cannot read {self.folder / 'config.toml'}", self.failure())
def test_refuses_while_the_rule_is_missing_or_blank(self) -> None:
self.write(rule=None)
self.assertIn(f"cannot read {self.folder / 'repo-rule.md'}", self.failure())
self.write(rule=" \n")
self.assertIn("`repo-rule.md` is blank", self.failure())
def test_names_each_missing_setting(self) -> None:
self.write("")
reason = self.failure()
for name in ("jira-url", "env-file", "repoless-model"):
self.assertIn(f"`{name}` is missing", reason)
def test_names_a_setting_it_does_not_know(self) -> None:
self.write(SETTINGS + 'checkout = "~/code/acme"\n')
self.assertIn("`checkout` is not a setting", self.failure())
def test_names_each_misspelt_value(self) -> None:
for line, name in (
('jira-url = "http://acme.atlassian.net"', "jira-url"),
('jira-url = "https://acme.atlassian.net/"', "jira-url"),
('env-file = "jira.env"', "env-file"),
('clone-folder = "code"', "clone-folder"),
('language = "sv_SE"', "language"),
('repoless-model = "opus"', "repoless-model"),
):
with self.subTest(line):
self.write("\n".join([ln for ln in SETTINGS.splitlines() if not ln.startswith(name)] + [line]))
self.assertIn(f"`{name}` is", self.failure())
def test_keeps_the_credentials_outside_every_config_and_every_clone(self) -> None:
for env_file in ("~/.claude-projects/do-epic/jira.env", "~/.claude-projects/acme/jira.env"):
with self.subTest(env_file):
self.write(SETTINGS.replace("~/jira.env", env_file))
self.assertIn("`env-file` is", self.failure())
self.write(SETTINGS.replace("~/jira.env", "~/code/acme/jira.env"))
self.assertIn("`env-file` is", self.failure())
self.write(SETTINGS.replace("~/jira.env", "~/clones/jira.env") + 'clone-folder = "~/clones"\n')
self.assertIn("`env-file` is", self.failure())
def test_reports_every_fault_at_once(self) -> None:
self.write('jira-url = "acme"\nrepoless-model = "x"\n')
reason = self.failure()
for part in ("`jira-url` is", "`env-file` is missing", "`repoless-model` is"):
self.assertIn(part, reason)