waymark-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. waymark/__init__.py +3 -0
  2. waymark/__main__.py +8 -0
  3. waymark/adapters/__init__.py +102 -0
  4. waymark/adapters/claude_code.py +238 -0
  5. waymark/assets/__init__.py +43 -0
  6. waymark/assets/agents/wm-implementer.md +45 -0
  7. waymark/assets/agents/wm-reviewer.md +43 -0
  8. waymark/assets/skills/wm-apply/SKILL.md +58 -0
  9. waymark/assets/skills/wm-archive/SKILL.md +32 -0
  10. waymark/assets/skills/wm-explore/SKILL.md +34 -0
  11. waymark/assets/skills/wm-kickoff/SKILL.md +34 -0
  12. waymark/assets/skills/wm-onboard/SKILL.md +27 -0
  13. waymark/assets/skills/wm-pr/SKILL.md +24 -0
  14. waymark/assets/skills/wm-propose/SKILL.md +32 -0
  15. waymark/assets/skills/wm-update/SKILL.md +31 -0
  16. waymark/cli.py +537 -0
  17. waymark/hooks/__init__.py +6 -0
  18. waymark/hooks/commands.py +190 -0
  19. waymark/hooks/decide.py +314 -0
  20. waymark/hooks/events.py +79 -0
  21. waymark/py.typed +0 -0
  22. waymark/record/__init__.py +5 -0
  23. waymark/record/atlas.py +156 -0
  24. waymark/record/changes.py +202 -0
  25. waymark/record/charter.py +75 -0
  26. waymark/record/commits.py +78 -0
  27. waymark/record/config.py +215 -0
  28. waymark/record/deltas.py +318 -0
  29. waymark/record/design.py +80 -0
  30. waymark/record/edits.py +95 -0
  31. waymark/record/evidence.py +58 -0
  32. waymark/record/explorations.py +66 -0
  33. waymark/record/files.py +75 -0
  34. waymark/record/fingerprint.py +73 -0
  35. waymark/record/git.py +167 -0
  36. waymark/record/githooks.py +106 -0
  37. waymark/record/links.py +104 -0
  38. waymark/record/milestones.py +84 -0
  39. waymark/record/moves.py +60 -0
  40. waymark/record/names.py +39 -0
  41. waymark/record/outline.py +144 -0
  42. waymark/record/pointer.py +56 -0
  43. waymark/record/problems.py +20 -0
  44. waymark/record/project.py +118 -0
  45. waymark/record/proposal.py +171 -0
  46. waymark/record/record.py +340 -0
  47. waymark/record/registry.py +158 -0
  48. waymark/record/specs.py +227 -0
  49. waymark/record/state.py +472 -0
  50. waymark/record/store.py +88 -0
  51. waymark/record/tasks.py +415 -0
  52. waymark/record/templates/charter.md +45 -0
  53. waymark/record/templates/ci-workflow.yml +29 -0
  54. waymark/record/templates/config-atlas.toml +8 -0
  55. waymark/record/templates/config.toml +19 -0
  56. waymark/record/templates/delta.md +29 -0
  57. waymark/record/templates/design.md +20 -0
  58. waymark/record/templates/exploration.md +22 -0
  59. waymark/record/templates/goal.md +13 -0
  60. waymark/record/templates/hook-commit-msg +8 -0
  61. waymark/record/templates/hook-pre-commit +8 -0
  62. waymark/record/templates/proposal.md +18 -0
  63. waymark/record/templates/roadmap.md +4 -0
  64. waymark/record/templates/tasks.md +10 -0
  65. waymark/record/templates.py +30 -0
  66. waymark/record/terms.py +51 -0
  67. waymark/record/text.py +197 -0
  68. waymark/services/__init__.py +1 -0
  69. waymark/services/atlas.py +162 -0
  70. waymark/services/check.py +129 -0
  71. waymark/services/ci.py +44 -0
  72. waymark/services/common.py +154 -0
  73. waymark/services/context.py +296 -0
  74. waymark/services/doctor.py +367 -0
  75. waymark/services/githooks.py +132 -0
  76. waymark/services/instructions.py +304 -0
  77. waymark/services/integration.py +170 -0
  78. waymark/services/lifecycle.py +454 -0
  79. waymark/services/migrations.py +90 -0
  80. waymark/services/pr.py +177 -0
  81. waymark/services/references.py +27 -0
  82. waymark/services/setup.py +127 -0
  83. waymark/views/__init__.py +5 -0
  84. waymark/views/payloads.py +568 -0
  85. waymark/views/render.py +506 -0
  86. waymark/views/schemas.py +413 -0
  87. waymark/views/style.py +102 -0
  88. waymark_cli-0.1.0.dist-info/METADATA +313 -0
  89. waymark_cli-0.1.0.dist-info/RECORD +92 -0
  90. waymark_cli-0.1.0.dist-info/WHEEL +4 -0
  91. waymark_cli-0.1.0.dist-info/entry_points.txt +2 -0
  92. waymark_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
waymark/services/pr.py ADDED
@@ -0,0 +1,177 @@
1
+ """Pull request text described from a change.
2
+
3
+ wm only writes the text. The links come from each repository's git remote as
4
+ this clone has it: nothing is fetched, and the pull request is opened by the
5
+ git host's own command-line tool, when the human asks. Links are built for
6
+ GitHub; on another host the text names the files and branches instead.
7
+ """
8
+
9
+ import re
10
+ from pathlib import Path
11
+ from typing import Any
12
+ from urllib.parse import quote
13
+
14
+ from waymark.record import git
15
+ from waymark.record.changes import Change
16
+ from waymark.record.config import RECORD_DIR
17
+ from waymark.record.proposal import WHAT_CHANGES, WHY
18
+ from waymark.record.record import CHANGES, Record
19
+ from waymark.record.state import ChangeState, ItemState
20
+ from waymark.record.tasks import Item, RecordKind
21
+ from waymark.record.terms import Layout, ReviewLevel
22
+ from waymark.services.common import Refusal, find_change, repo_locations, state_of
23
+
24
+ PR_VERSION = 1
25
+
26
+ _REMOTES = (
27
+ re.compile(r"^git@(?P<host>[^:]+):(?P<path>.+?)(?:\.git)?/?$"),
28
+ re.compile(r"^ssh://(?:[^@/]+@)?(?P<host>[^/:]+)(?::\d+)?/(?P<path>.+?)(?:\.git)?/?$"),
29
+ re.compile(r"^https?://(?:[^@/]+@)?(?P<host>[^/]+)/(?P<path>.+?)(?:\.git)?/?$"),
30
+ )
31
+ _HOSTS = frozenset({"github.com", "www.github.com"})
32
+
33
+
34
+ def web_url(remote: str | None) -> str | None:
35
+ """A GitHub repository's web address from a remote URL; None for any other host."""
36
+ for pattern in _REMOTES:
37
+ match = pattern.match(remote or "")
38
+ if match and match["host"].lower() in _HOSTS:
39
+ return f"https://github.com/{match['path']}"
40
+ return None
41
+
42
+
43
+ def _web(folder: Path | None) -> str | None:
44
+ return web_url(git.remote_url(folder)) if folder is not None else None
45
+
46
+
47
+ def _review(item: Item, state: ItemState) -> str:
48
+ if not item.ticked:
49
+ return "not built yet"
50
+ if state.level is ReviewLevel.NONE:
51
+ return "no review needed"
52
+ if not state.reviewed:
53
+ return "not reviewed yet"
54
+ verdicts = [r for r in item.records if r.kind is RecordKind.REVIEW and r.verdict]
55
+ if verdicts:
56
+ return f"independent review: {verdicts[-1].verdict.value if verdicts[-1].verdict else ''}"
57
+ return "self-reviewed"
58
+
59
+
60
+ def _spec_lines(change: Change) -> list[str]:
61
+ lines = []
62
+ for domain, delta in sorted(change.deltas.items()):
63
+ parts = [
64
+ f"{label} {', '.join(r.name for r in requirements)}"
65
+ for label, requirements in (
66
+ ("adds", delta.added),
67
+ ("modifies", delta.modified),
68
+ ("removes", delta.removed),
69
+ )
70
+ if requirements
71
+ ]
72
+ lines.append(f"- {domain}: {'; '.join(parts) or 'its purpose or repos'}")
73
+ return lines or ["No spec changes."]
74
+
75
+
76
+ def _places(record: Record, change: Change) -> dict[str, Path | None]:
77
+ """The atlas and every code repo the change's items name, with their folders here."""
78
+ config = record.config
79
+ assert config is not None
80
+ assert config.atlas_name is not None
81
+ locations = repo_locations(record)
82
+ touched = sorted(
83
+ {item.repo for item in change.tasks.items if item.repo} if change.tasks else ()
84
+ )
85
+ places: dict[str, Path | None] = {config.atlas_name: record.project.root}
86
+ for name in touched:
87
+ location = locations.get(name)
88
+ places[name] = location.folder if location else None
89
+ return places
90
+
91
+
92
+ def _links(
93
+ record: Record, name: str, places: dict[str, Path | None], here: str | None
94
+ ) -> list[dict[str, str]]:
95
+ """The change's proposal on its branch, and the other repos' pull requests from it."""
96
+ record_web = _web(record.project.root)
97
+ home = next(iter(places), None)
98
+ links: list[dict[str, str]] = []
99
+ if record_web:
100
+ proposal = f"{RECORD_DIR}/{CHANGES}/{name}/proposal.md"
101
+ links.append({"name": "change", "url": f"{record_web}/blob/{quote(name)}/{proposal}"})
102
+ for other, folder in places.items():
103
+ web = record_web if other == home else _web(folder)
104
+ if other != here and web:
105
+ query = quote(f"is:pr head:{name}", safe=":")
106
+ links.append({"name": other, "url": f"{web}/pulls?q={query}"})
107
+ return links
108
+
109
+
110
+ def _item_lines(change: Change, state: ChangeState, repo: str | None) -> list[str]:
111
+ states = {item_state.number: item_state for item_state in state.items}
112
+ lines = []
113
+ for item in change.tasks.items if change.tasks else ():
114
+ if repo is not None and item.repo != repo:
115
+ continue
116
+ mark = "x" if item.ticked else " "
117
+ where = f", in {item.repo}" if item.repo and repo is None else ""
118
+ review = _review(item, states[item.number])
119
+ lines.append(f"- [{mark}] {item.number} {item.title} ({review}{where})")
120
+ if not lines:
121
+ return []
122
+ return ["", f"## Items in {repo}" if repo else "## Items", "", *lines]
123
+
124
+
125
+ def _link_lines(
126
+ name: str, places: dict[str, Path | None], here: str | None, links: list[dict[str, str]]
127
+ ) -> list[str]:
128
+ urls = {link["name"]: link["url"] for link in links}
129
+ proposal = f"{RECORD_DIR}/{CHANGES}/{name}/proposal.md"
130
+ home = next(iter(places), None)
131
+ if "change" in urls:
132
+ lines = [f"- The change: [{proposal}]({urls['change']})"]
133
+ else:
134
+ where = f' in the atlas "{home}"' if home else ""
135
+ lines = [f"- The change: {proposal}{where}, on the branch {name}"]
136
+ for other in places:
137
+ if other != here:
138
+ target = f"[{other}]({urls[other]})" if other in urls else other
139
+ lines.append(f"- The pull request in {target}, from the branch {name}")
140
+ return ["", "## Links", "", *lines]
141
+
142
+
143
+ def describe(record: Record, name: str, repo: str | None = None) -> dict[str, Any]:
144
+ """The title and description of the pull request for a change, in one repository.
145
+
146
+ In an atlas, ``repo`` names the code repo; without it the pull request is
147
+ the atlas's own, which carries the record.
148
+ """
149
+ change = find_change(record, name)
150
+ proposal = change.proposal
151
+ if proposal is None:
152
+ raise Refusal(f'The change "{name}" has no proposal yet, so there is nothing to describe.')
153
+ atlas = record.layout is Layout.ATLAS
154
+ if repo is not None and not atlas:
155
+ raise Refusal("--repo names a code repo of an atlas; this project keeps everything in one.")
156
+ places = _places(record, change) if atlas else {}
157
+ code_repos = list(places)[1:]
158
+ if repo is not None and repo not in code_repos:
159
+ touched = ", ".join(code_repos) or "none"
160
+ raise Refusal(f'The change "{name}" has no items in the repo "{repo}" (repos: {touched}).')
161
+ here = repo or next(iter(places), None)
162
+ links = _links(record, name, places, here)
163
+ body = [proposal.sections.get(WHY, "").strip()]
164
+ body += ["", f"## {WHAT_CHANGES}", "", proposal.sections.get(WHAT_CHANGES, "").strip()]
165
+ body += ["", "## Specs", "", *_spec_lines(change)]
166
+ body += _item_lines(change, state_of(record, change), repo)
167
+ body += _link_lines(name, places, here, links)
168
+ return {
169
+ "schema": "wm.pr",
170
+ "version": PR_VERSION,
171
+ "change": name,
172
+ "repo": repo,
173
+ "branch": name,
174
+ "title": proposal.title,
175
+ "body": "\n".join(body).strip() + "\n",
176
+ "links": links,
177
+ }
@@ -0,0 +1,27 @@
1
+ """Reading another atlas's specs, read only, where the atlas sits on this machine."""
2
+
3
+ from waymark.record.atlas import Found, locate_atlas
4
+ from waymark.record.config import CONFIG_FILE, RECORD_DIR
5
+ from waymark.record.project import Project
6
+ from waymark.record.record import Record, load_record
7
+ from waymark.record.registry import load_registry
8
+ from waymark.services.common import Refusal, notice
9
+
10
+
11
+ def reference_record(record: Record, atlas: str) -> Record:
12
+ """Another atlas's record, read where it sits on this machine. It is only read."""
13
+ references = {ref.atlas: ref for ref in record.config.references} if record.config else {}
14
+ if atlas not in references:
15
+ listed = ", ".join(sorted(references)) or "none"
16
+ raise Refusal(
17
+ f'This project references no atlas "{atlas}" (references: {listed}). Add a '
18
+ f'"[references.{atlas}]" table to {RECORD_DIR}/{CONFIG_FILE} to read its specs.'
19
+ )
20
+ location = locate_atlas(
21
+ atlas, load_registry(), record.project.root, references[atlas].path_hint
22
+ )
23
+ if location.folder is None:
24
+ raise Refusal(location.detail)
25
+ if location.found is Found.HINT:
26
+ notice(f"{location.detail} ({location.folder})")
27
+ return load_record(Project(location.folder))
@@ -0,0 +1,127 @@
1
+ """Setting up a project, and creating changes, milestones and explorations from templates."""
2
+
3
+ import re
4
+ from pathlib import Path
5
+
6
+ from waymark import __version__, adapters
7
+ from waymark.record import git, templates
8
+ from waymark.record.changes import PROPOSAL_FILE
9
+ from waymark.record.charter import CHARTER_FILE
10
+ from waymark.record.config import CONFIG_FILE, RECORD_FORMAT
11
+ from waymark.record.files import RecordFiles
12
+ from waymark.record.milestones import GOAL_FILE, ROADMAP_FILE
13
+ from waymark.record.names import NAME_RULE, is_valid_name
14
+ from waymark.record.project import RECORD_DIR
15
+ from waymark.record.proposal import OWNER, PATH, SHORT
16
+ from waymark.record.record import CHANGES, EXPLORATIONS, MILESTONES
17
+ from waymark.record.store import Transaction
18
+ from waymark.services import githooks, integration
19
+ from waymark.services.atlas import register_new_atlas
20
+ from waymark.services.common import Done, Refusal, commit, open_record
21
+
22
+ _ATLAS_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
23
+
24
+
25
+ def init_project(
26
+ start: Path, atlas: str | None = None, tools: tuple[str, ...] | None = None
27
+ ) -> Done:
28
+ """Create the record at the top of the git repository around a folder.
29
+
30
+ Also installs the skills, agent definitions and hooks for the project's
31
+ agent tools: every tool wm knows, unless ``tools`` names them.
32
+ """
33
+ root = git.repository_root(start)
34
+ if root is None:
35
+ raise Refusal(
36
+ 'wm needs a git repository, and this folder is not in one. Run "git init" first.'
37
+ )
38
+ files = RecordFiles(root)
39
+ if files.is_file(f"{RECORD_DIR}/{CONFIG_FILE}"):
40
+ raise Refusal(
41
+ f"This repository already has a record ({RECORD_DIR}/{CONFIG_FILE}). "
42
+ 'Run "wm check" to see how it stands.'
43
+ )
44
+ if atlas is not None and not _ATLAS_NAME.fullmatch(atlas):
45
+ raise Refusal(
46
+ f'"{atlas}" can\'t be an atlas name. Use letters, digits, dots, hyphens or '
47
+ "underscores, starting with a letter or digit."
48
+ )
49
+ chosen = adapters.names() if tools is None else tools
50
+ integration.require_tools(chosen)
51
+ config = templates.render(
52
+ templates.CONFIG,
53
+ wm_version=__version__,
54
+ record_format=str(RECORD_FORMAT),
55
+ agent_tools=", ".join(f'"{tool}"' for tool in chosen),
56
+ )
57
+ if atlas is not None:
58
+ config += templates.render(templates.ATLAS_CONFIG, atlas_name=atlas)
59
+ transaction = Transaction(files)
60
+ transaction.write(f"{RECORD_DIR}/{CONFIG_FILE}", config)
61
+ transaction.write(
62
+ f"{RECORD_DIR}/{CHARTER_FILE}", templates.render(templates.CHARTER, title=root.name)
63
+ )
64
+ integration.stage(transaction, files, chosen)
65
+ paths = commit(transaction)
66
+ kind = f'the atlas "{atlas}"' if atlas is not None else "a project"
67
+ titles = ", ".join(adapters.get(tool).title for tool in chosen) or "no agent tool"
68
+ registered = f" {register_new_atlas(root, atlas)}" if atlas is not None else ""
69
+ hooks = "\n".join(githooks.install(root))
70
+ return Done(
71
+ f"Initialized {kind} in {RECORD_DIR}/, with skills, agents and hooks for {titles}."
72
+ f"{registered}\n{hooks}\n"
73
+ 'To run "wm check" in GitHub Actions too, run "wm ci".\n'
74
+ "Next: run the wm-kickoff skill in your agent tool to draft the charter.",
75
+ paths,
76
+ )
77
+
78
+
79
+ def _require_new_name(name: str, kind: str, taken: bool) -> None:
80
+ article = "an" if kind[0] in "aeiou" else "a"
81
+ if not is_valid_name(name):
82
+ raise Refusal(f'"{name}" can\'t be {article} {kind} name. Use {NAME_RULE}.')
83
+ if taken:
84
+ raise Refusal(f'There already is {article} {kind} named "{name}". Pick another name.')
85
+
86
+
87
+ def create_change(start: Path, name: str, *, short: bool = False, owner: str | None = None) -> Done:
88
+ """Create a change folder with a proposal skeleton."""
89
+ record = open_record(start, writing=True)
90
+ folder = f"{CHANGES}/{name}"
91
+ _require_new_name(name, "change", bool(record.files.entries(folder)))
92
+ who = owner or git.user_name(record.project.root)
93
+ if not who:
94
+ raise Refusal(
95
+ "Every change has one owner. Pass --owner <name>, or set your name in git: "
96
+ 'git config user.name "<name>".'
97
+ )
98
+ facts = f"{OWNER}: {who}\n" + (f"{PATH}: {SHORT}\n" if short else "")
99
+ text = templates.render(templates.PROPOSAL, title=templates.title_from_name(name), facts=facts)
100
+ transaction = Transaction(record.files)
101
+ transaction.write(f"{folder}/{PROPOSAL_FILE}", text)
102
+ path = "on the short path " if short else ""
103
+ return Done(f'Created the change "{name}" {path}with a proposal to draft.', commit(transaction))
104
+
105
+
106
+ def create_milestone(start: Path, name: str) -> Done:
107
+ """Create a milestone folder with goal and roadmap skeletons."""
108
+ record = open_record(start, writing=True)
109
+ folder = f"{MILESTONES}/{name}"
110
+ _require_new_name(name, "milestone", bool(record.files.entries(folder)))
111
+ title = templates.title_from_name(name)
112
+ transaction = Transaction(record.files)
113
+ transaction.write(f"{folder}/{GOAL_FILE}", templates.render(templates.GOAL, title=title))
114
+ transaction.write(f"{folder}/{ROADMAP_FILE}", templates.render(templates.ROADMAP, title=title))
115
+ return Done(f'Created the milestone "{name}" with a goal to draft.', commit(transaction))
116
+
117
+
118
+ def create_exploration(start: Path, name: str) -> Done:
119
+ """Create an exploration skeleton."""
120
+ record = open_record(start, writing=True)
121
+ path = f"{EXPLORATIONS}/{name}.md"
122
+ _require_new_name(name, "exploration", record.files.is_file(path))
123
+ transaction = Transaction(record.files)
124
+ transaction.write(
125
+ path, templates.render(templates.EXPLORATION, title=templates.title_from_name(name))
126
+ )
127
+ return Done(f'Created the exploration "{name}".', commit(transaction))
@@ -0,0 +1,5 @@
1
+ """Views: what the read commands show.
2
+
3
+ Each view is built once, as a plain payload. The styled text and the JSON are
4
+ two renderings of that one payload, so people and agents read the same data.
5
+ """