roadkeep 0.2.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.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- roadkeep-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,974 @@
|
|
|
1
|
+
"""The verbs run once per project, and those whose subject is this tool (RK494).
|
|
2
|
+
|
|
3
|
+
`init` scaffolds, `declare` retrofits a role, `adopt` estimates what an existing backlog
|
|
4
|
+
would cost to bring under the schema, `install` wires the skill, the tools and the guard
|
|
5
|
+
into a checkout, `uninstall` is the way back out, and `engines` says whether the copies
|
|
6
|
+
that can be in play agree. `mcp` serves the same surface over stdio (RK24).
|
|
7
|
+
|
|
8
|
+
`report`, `replay` and the `capture` group belong by the same rule and not by exception:
|
|
9
|
+
their subject is a defect in this tool, captured as facts a replay re-runs (RK85-89) —
|
|
10
|
+
something done to an installation rather than to a backlog.
|
|
11
|
+
|
|
12
|
+
**Neither list is counted here** (RK1397). This opened with *the two whose subject is this
|
|
13
|
+
tool* and named `report` and `replay`, while the module declared four: `capture filed`
|
|
14
|
+
arrived with RK1142 and `capture sweep` with RK1394, both by that same rule, and the first
|
|
15
|
+
paragraph had lost `declare` (RK1264) the same way. Each drift was one line an author did
|
|
16
|
+
not think to touch — the only count in this package that was prose confronted with nothing,
|
|
17
|
+
where every other census here is a table held against the population it is a set of. So the
|
|
18
|
+
two lists are :data:`ABOUT_THIS_TOOL` and :data:`ABOUT_THE_WIRING`, and `test_surfaces`
|
|
19
|
+
holds them against what :func:`declare_wiring` actually declares.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import argparse
|
|
25
|
+
import json
|
|
26
|
+
import sys
|
|
27
|
+
import tempfile
|
|
28
|
+
|
|
29
|
+
from roadkeep.adopting import (
|
|
30
|
+
OPT_IN,
|
|
31
|
+
NoSuchTable,
|
|
32
|
+
declare_table,
|
|
33
|
+
DEFERRED_ROLE,
|
|
34
|
+
SCAFFOLD_ROLES,
|
|
35
|
+
STRATEGY_ROLE,
|
|
36
|
+
adopt,
|
|
37
|
+
declare,
|
|
38
|
+
init,
|
|
39
|
+
)
|
|
40
|
+
from roadkeep.capturing import (
|
|
41
|
+
Filed,
|
|
42
|
+
REPORTS,
|
|
43
|
+
STOPPED_NOTICE,
|
|
44
|
+
body,
|
|
45
|
+
capture,
|
|
46
|
+
captures,
|
|
47
|
+
check,
|
|
48
|
+
delivered,
|
|
49
|
+
handoff,
|
|
50
|
+
keep,
|
|
51
|
+
replay,
|
|
52
|
+
stamp,
|
|
53
|
+
sweep,
|
|
54
|
+
)
|
|
55
|
+
from roadkeep.backlog import Backlog
|
|
56
|
+
from roadkeep.config import ROLES, Config
|
|
57
|
+
from roadkeep.installing import (
|
|
58
|
+
engines,
|
|
59
|
+
install,
|
|
60
|
+
plan,
|
|
61
|
+
removal,
|
|
62
|
+
uninstall,
|
|
63
|
+
vendor,
|
|
64
|
+
)
|
|
65
|
+
from roadkeep.rendering import _estimate_json, _print_estimate
|
|
66
|
+
from roadkeep.serving import serve
|
|
67
|
+
from roadkeep.capturing import PARTS
|
|
68
|
+
from roadkeep.verbs.declaring import _JSON_HELP
|
|
69
|
+
from roadkeep.verbs.refusing import EXIT_GATE, EXIT_OK, EXIT_USAGE, _refused
|
|
70
|
+
|
|
71
|
+
#: The subcommands here whose subject is a defect in **this tool** rather than a backlog
|
|
72
|
+
#: (RK85-89, RK1142, RK1394). Spelled by the full path a caller types, because `capture` is a
|
|
73
|
+
#: group and the two verbs under it are what have the subject — a list of top-level words could
|
|
74
|
+
#: not say that, and saying it wrongly is what RK1397 was.
|
|
75
|
+
ABOUT_THIS_TOOL = ("report", "replay", "capture filed", "capture sweep")
|
|
76
|
+
|
|
77
|
+
#: And those whose subject is the project's own wiring: which files exist, which copies write,
|
|
78
|
+
#: and how the surface is reached. The other half of a partition, so a verb added to this module
|
|
79
|
+
#: belongs to one of them and the test says which is missing rather than that a number moved.
|
|
80
|
+
ABOUT_THE_WIRING = (
|
|
81
|
+
"init",
|
|
82
|
+
"declare",
|
|
83
|
+
"adopt",
|
|
84
|
+
"install",
|
|
85
|
+
"uninstall",
|
|
86
|
+
"engines",
|
|
87
|
+
"mcp",
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _init(config: Config, args: argparse.Namespace) -> int:
|
|
92
|
+
# `config` is deliberately unused: `init` is the one command that runs *before* a
|
|
93
|
+
# project is configured, so it takes the directory it was pointed at. A discovered
|
|
94
|
+
# config would be an ancestor's, and scaffolding under someone else's paths is how a
|
|
95
|
+
# subproject ends up writing into its parent's roadmap.
|
|
96
|
+
del config
|
|
97
|
+
families = tuple(args.prefix or ("RK",))
|
|
98
|
+
try:
|
|
99
|
+
created = init(
|
|
100
|
+
args.directory,
|
|
101
|
+
prefix=families,
|
|
102
|
+
blocks=args.blocks or ("A",),
|
|
103
|
+
# Named at the door and never derived (RK1186): which prose files a project wants
|
|
104
|
+
# is the author's decision, and a scaffold that guessed would create a file
|
|
105
|
+
# somebody has to notice is empty before they can delete it.
|
|
106
|
+
roles=(
|
|
107
|
+
*SCAFFOLD_ROLES,
|
|
108
|
+
*((STRATEGY_ROLE,) if args.strategy else ()),
|
|
109
|
+
*((DEFERRED_ROLE,) if args.deferred else ()),
|
|
110
|
+
),
|
|
111
|
+
)
|
|
112
|
+
except (ValueError, OSError) as error:
|
|
113
|
+
return _refused(error)
|
|
114
|
+
|
|
115
|
+
if args.json:
|
|
116
|
+
print(json.dumps(created.payload(args.directory, families), indent=2))
|
|
117
|
+
else:
|
|
118
|
+
print(created.stated(families))
|
|
119
|
+
return EXIT_OK
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _declare(config: Config, args: argparse.Namespace) -> int:
|
|
123
|
+
"""`init`'s door for a project that is already configured (RK1264).
|
|
124
|
+
|
|
125
|
+
Unlike `_init` this one **wants** the discovered config: the role is added to the project
|
|
126
|
+
the caller is standing in, and the headings it mirrors are that project's own.
|
|
127
|
+
"""
|
|
128
|
+
try:
|
|
129
|
+
# One argument, two vocabularies (RK1328): a **role** retrofits a file and its
|
|
130
|
+
# `[files]` key, and an opt-in **table** opens a list this project may then govern.
|
|
131
|
+
# Both are *this file, one key, refused where it is already declared*, which is why
|
|
132
|
+
# the argument widens rather than the verb list — a third served tool costs about 800
|
|
133
|
+
# characters against 87 of headroom, and the ceiling is not what should give.
|
|
134
|
+
if args.role in OPT_IN:
|
|
135
|
+
written = declare_table(config, args.role)
|
|
136
|
+
elif args.role in ROLES:
|
|
137
|
+
written = declare(config, args.role, args.path)
|
|
138
|
+
else:
|
|
139
|
+
# The word is in neither, and the refusal names both: one argument now carries two
|
|
140
|
+
# vocabularies, and a caller who typed into the wrong one learns nothing from a
|
|
141
|
+
# message about the other. `declare` keeps `NoSuchRole` for its own contract.
|
|
142
|
+
raise NoSuchTable(args.role, OPT_IN)
|
|
143
|
+
except (ValueError, OSError) as error:
|
|
144
|
+
return _refused(error)
|
|
145
|
+
|
|
146
|
+
if args.json:
|
|
147
|
+
print(json.dumps(written.payload(config), indent=2))
|
|
148
|
+
else:
|
|
149
|
+
print(written.stated(config))
|
|
150
|
+
return EXIT_OK
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def _better_read(config: Config, args: argparse.Namespace, estimate):
|
|
154
|
+
"""The reading that fits, where the caller named no role (RK1346).
|
|
155
|
+
|
|
156
|
+
Measured on an ungoverned `CHANGELOG.md`: the backlog grammar reported 0 parsed and *361
|
|
157
|
+
would change*, and `--ledger` reported 361 conform and none changing. The file was already
|
|
158
|
+
conforming, the report said it was 361 lines of work, and the word `ledger` appeared
|
|
159
|
+
nowhere in it. The diagnosis was accurate under the grammar it applied — *no marker where
|
|
160
|
+
the status goes* is exactly true of a ledger entry read as a task line — which is what made
|
|
161
|
+
it convincing.
|
|
162
|
+
|
|
163
|
+
Not a guess: the two grammars separate by an order of magnitude on real files. Measured on
|
|
164
|
+
this repository, `docs/CHANGELOG.md` reads 843 conform as a ledger and 0 as a backlog,
|
|
165
|
+
while `docs/ROADMAP.md` reads 1 and 0 the other way. So the better reading is the one with
|
|
166
|
+
more conforming lines, and a tie keeps what was asked for.
|
|
167
|
+
|
|
168
|
+
Only where nothing was asked. `--ledger` is honoured as typed, for the reason `--prefix`
|
|
169
|
+
is: an override the tool second-guesses is not an override — and the header now names the
|
|
170
|
+
role either way, so a reader can see which grammar answered and pass the other.
|
|
171
|
+
"""
|
|
172
|
+
if args.ledger or args.sections or estimate.conforming:
|
|
173
|
+
return estimate
|
|
174
|
+
best = estimate
|
|
175
|
+
# Both other roles and not one (RK1347): a rationale file read as a backlog reported
|
|
176
|
+
# *nothing in 837 line(s) was read in any shape*, where `--sections` read 51 conforming
|
|
177
|
+
# sections and 19 paragraphs over a limit. Tried separately because the two flags are
|
|
178
|
+
# refused together, and the estimator is what declines the pair.
|
|
179
|
+
for role in ({"ledger": True}, {"sections": True}):
|
|
180
|
+
try:
|
|
181
|
+
other = adopt(
|
|
182
|
+
config,
|
|
183
|
+
args.path,
|
|
184
|
+
prefix=args.prefix,
|
|
185
|
+
ref_scheme=args.ref_scheme,
|
|
186
|
+
alongside=args.alongside,
|
|
187
|
+
**role,
|
|
188
|
+
)
|
|
189
|
+
except (ValueError, OSError):
|
|
190
|
+
# A role this file's arguments refuse is not a finding here: what was asked for
|
|
191
|
+
# still answers, and a retry that cannot be taken says nothing about the file.
|
|
192
|
+
continue
|
|
193
|
+
if other.conforming > best.conforming:
|
|
194
|
+
best = other
|
|
195
|
+
return best
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def _adopt(config: Config, args: argparse.Namespace) -> int:
|
|
199
|
+
try:
|
|
200
|
+
estimate = adopt(
|
|
201
|
+
config,
|
|
202
|
+
args.path,
|
|
203
|
+
prefix=args.prefix,
|
|
204
|
+
ref_scheme=args.ref_scheme,
|
|
205
|
+
ledger=args.ledger,
|
|
206
|
+
sections=args.sections,
|
|
207
|
+
alongside=args.alongside,
|
|
208
|
+
)
|
|
209
|
+
except (ValueError, OSError) as error:
|
|
210
|
+
return _refused(error)
|
|
211
|
+
|
|
212
|
+
estimate = _better_read(config, args, estimate)
|
|
213
|
+
if args.json:
|
|
214
|
+
print(json.dumps(_estimate_json(estimate), indent=2))
|
|
215
|
+
return EXIT_OK
|
|
216
|
+
_print_estimate(estimate)
|
|
217
|
+
# Always 0: this reports on a file the project has not adopted, so there is no
|
|
218
|
+
# contract for it to have broken. `lint` is the command with an exit code.
|
|
219
|
+
return EXIT_OK
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def _engines(config: Config, args: argparse.Namespace) -> int:
|
|
223
|
+
"""The three copies this project runs, and whether the two versions agree (RK415).
|
|
224
|
+
|
|
225
|
+
`config` is read for its root alone — the registry is keyed by project path, so the
|
|
226
|
+
question is about the tree and not about the governed files in it.
|
|
227
|
+
|
|
228
|
+
The exit code is the answer, the way `install --check`'s is: a session that has to grep a
|
|
229
|
+
sentence to learn the pen and the judge are 133 versions apart is one that will not ask.
|
|
230
|
+
"""
|
|
231
|
+
found = engines(config.root)
|
|
232
|
+
if args.invoke:
|
|
233
|
+
# One line and no verdict (RK1230): this answers *which copy to call*, which is a
|
|
234
|
+
# question a caller has before they know whether the copies agree — and an exit code
|
|
235
|
+
# about agreement would make a shell substitution fail on a project that is merely
|
|
236
|
+
# behind. `engines` bare is where the disagreement is read.
|
|
237
|
+
# `--json` is honoured rather than refused, because the served surface appends it to
|
|
238
|
+
# every call (RK319): a flag that only worked on a terminal would be one this project's
|
|
239
|
+
# own agent could not use, which is the caller the whole task is about.
|
|
240
|
+
print(json.dumps({"invoke": found.invoke()}, indent=2) if args.json else found.invoke())
|
|
241
|
+
return EXIT_OK
|
|
242
|
+
# Both registers off the record (RK1170), the exit code included: whether the pen and the
|
|
243
|
+
# judge are the same copy is a property of the reading and not a second decision here.
|
|
244
|
+
if args.json:
|
|
245
|
+
print(json.dumps(found.payload(), indent=2))
|
|
246
|
+
else:
|
|
247
|
+
print(found.stated())
|
|
248
|
+
return EXIT_OK if found.agree else EXIT_GATE
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def _install(config: Config, args: argparse.Namespace) -> int:
|
|
252
|
+
"""Wire the harness for a project the plugin did not install (RK100).
|
|
253
|
+
|
|
254
|
+
`config` is unused for `init`'s reason one step further along: this writes the surfaces
|
|
255
|
+
that decide *which* engine a session reaches, and none of it is read out of the governed
|
|
256
|
+
files. The exit code carries `--check`'s answer — 1 for a surface that would change,
|
|
257
|
+
because a copy held in step by a gate is the whole point of there being a check.
|
|
258
|
+
"""
|
|
259
|
+
del config
|
|
260
|
+
try:
|
|
261
|
+
intent = (
|
|
262
|
+
# `--check` writes nothing, so it reports the driver as unwritten either way: a
|
|
263
|
+
# check that registered one would be a check that changed the repository (RK148).
|
|
264
|
+
plan(args.directory, source=args.source, committed=args.committed)
|
|
265
|
+
if args.check
|
|
266
|
+
else install(
|
|
267
|
+
args.directory,
|
|
268
|
+
source=args.source,
|
|
269
|
+
register_merge=args.register_merge,
|
|
270
|
+
committed=args.committed,
|
|
271
|
+
)
|
|
272
|
+
)
|
|
273
|
+
# After the surfaces and never instead of them (RK1193): the engine is what those
|
|
274
|
+
# declarations *point at*, so a run that vendored one and failed to wire it would
|
|
275
|
+
# leave a copy nothing reaches. Inside the same try, so a machine with no engine to
|
|
276
|
+
# copy refuses in the words every other bad input gets.
|
|
277
|
+
pinned = vendor(args.directory, checked=args.check) if args.vendor else None
|
|
278
|
+
except (ValueError, OSError) as error:
|
|
279
|
+
return _refused(error)
|
|
280
|
+
|
|
281
|
+
if args.json:
|
|
282
|
+
payload = intent.payload(args.check)
|
|
283
|
+
if pinned is not None:
|
|
284
|
+
payload["vendored"] = pinned.payload()
|
|
285
|
+
print(json.dumps(payload, indent=2))
|
|
286
|
+
else:
|
|
287
|
+
print(intent.stated(args.check))
|
|
288
|
+
if pinned is not None:
|
|
289
|
+
print(pinned.stated(args.check))
|
|
290
|
+
if args.check:
|
|
291
|
+
for line in intent.verdict():
|
|
292
|
+
print(line, file=sys.stderr)
|
|
293
|
+
if args.check and intent.changing:
|
|
294
|
+
return EXIT_GATE
|
|
295
|
+
return EXIT_OK
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
def _capture_filed(config: Config, args: argparse.Namespace) -> int:
|
|
299
|
+
"""Record which task a capture already on disk was filed as (RK1142).
|
|
300
|
+
|
|
301
|
+
`add --capture` closes the row by the act that closes it, and covered every capture filed
|
|
302
|
+
from then on and none of the ones already held: clearing this repository's own row took a
|
|
303
|
+
`python -c`, which is the shape L5 exists against — every question this tool answers is a
|
|
304
|
+
command, and the maintainer reached past the tool.
|
|
305
|
+
|
|
306
|
+
Two refusals, both at the door (L1). An **id no governed file holds** is a link to nothing,
|
|
307
|
+
which is the reading `stats` already makes and the reason it does not clear a row. A **path
|
|
308
|
+
that is not a capture** is somebody's file, and a verb that stamped it would be writing a
|
|
309
|
+
key into an artefact this tool did not produce.
|
|
310
|
+
"""
|
|
311
|
+
# Against the project `-C` named and not the process's directory (RK1396): the paths this
|
|
312
|
+
# verb is given are the ones `stats` and `capture sweep` print, and those are spelled
|
|
313
|
+
# project-relative — so reading them from wherever the process happens to be refused the
|
|
314
|
+
# tool's own doors, with a message naming the directory the file was in.
|
|
315
|
+
path = config.locate(args.path)
|
|
316
|
+
held = {one.path.resolve(): one for one in captures(config.root)}
|
|
317
|
+
known = held.get(path.resolve())
|
|
318
|
+
if known is None:
|
|
319
|
+
print(
|
|
320
|
+
f"roadkeep: {args.path} is not a capture this project holds: `stats` names the "
|
|
321
|
+
f"ones it does, under {config.relative(config.root / REPORTS)}",
|
|
322
|
+
file=sys.stderr,
|
|
323
|
+
)
|
|
324
|
+
return EXIT_USAGE
|
|
325
|
+
# A stamp naming another repository is not this backlog's to verify (RK1160): a capture of a
|
|
326
|
+
# defect in *this tool* is filed in this tool's backlog — which is what `report --to
|
|
327
|
+
# OWNER/REPO` says — so the id is one no governed file here holds, and the lookup below would
|
|
328
|
+
# refuse the one delivery a capture taken here can have. What is checked is the shape.
|
|
329
|
+
elsewhere = delivered(args.task_id)
|
|
330
|
+
backlog = Backlog.load(config)
|
|
331
|
+
# And a **bare** id the capture's own destination explains (RK1161): `--to` or `[report]
|
|
332
|
+
# upstream` is where a defect in roadkeep was aimed, the capture records it, so asking the
|
|
333
|
+
# author to spell it again is the asymmetry RK1149 took out of the refusals. Only where this
|
|
334
|
+
# backlog does not hold the id — a local id that resolves is a local filing, whatever the
|
|
335
|
+
# capture was aimed at, and a typo stays the refusal below.
|
|
336
|
+
ids = {
|
|
337
|
+
entry.task.id
|
|
338
|
+
for document in (backlog.roadmap, backlog.ledger, backlog.store)
|
|
339
|
+
if document is not None
|
|
340
|
+
for entry in document.entries
|
|
341
|
+
}
|
|
342
|
+
written = args.task_id
|
|
343
|
+
if not elsewhere and args.task_id not in ids and known.upstream:
|
|
344
|
+
written = f"{known.upstream}#{args.task_id}"
|
|
345
|
+
elsewhere = delivered(written)
|
|
346
|
+
if not elsewhere and args.task_id not in ids:
|
|
347
|
+
print(
|
|
348
|
+
f"roadkeep: no governed file holds {args.task_id}, so stamping it would be a "
|
|
349
|
+
f"link to nothing — file the capture first, and `add --capture {args.path}` "
|
|
350
|
+
f"stamps it as it mints the id; a defect in roadkeep itself belongs in roadkeep's "
|
|
351
|
+
f"backlog, and `--as owner/repo#{args.task_id}` records that delivery",
|
|
352
|
+
file=sys.stderr,
|
|
353
|
+
)
|
|
354
|
+
return EXIT_USAGE
|
|
355
|
+
if not stamp(known.path, written):
|
|
356
|
+
print(f"roadkeep: {args.path} could not be written", file=sys.stderr)
|
|
357
|
+
return EXIT_USAGE
|
|
358
|
+
# No staging line: the report directory is git-ignored, so there is nothing to stage —
|
|
359
|
+
# which is the exemption `test_every_write_command_is_either_wired_or_exempted` carries.
|
|
360
|
+
answer = Filed(
|
|
361
|
+
where=config.relative(known.path),
|
|
362
|
+
filed=written,
|
|
363
|
+
elsewhere=elsewhere,
|
|
364
|
+
asked=args.task_id,
|
|
365
|
+
)
|
|
366
|
+
|
|
367
|
+
if args.json:
|
|
368
|
+
print(json.dumps(answer.payload(), indent=2))
|
|
369
|
+
else:
|
|
370
|
+
print(answer.stated())
|
|
371
|
+
return EXIT_OK
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
def _capture_sweep(config: Config, args: argparse.Namespace) -> int:
|
|
375
|
+
"""Delete the captures the ledger proves are answered, and name the ones it cannot (RK1394).
|
|
376
|
+
|
|
377
|
+
The retention `keep` parks, and the reading is the whole verb: `--check` and the delete print
|
|
378
|
+
the same table, because what a reader needs from a sweep is why four files survived and not
|
|
379
|
+
which three went. Nothing is refused at the door — an empty directory and a directory where
|
|
380
|
+
every capture is still open are both legitimate answers, and a non-zero exit would make a
|
|
381
|
+
project with nothing to sweep fail a hook that ran this.
|
|
382
|
+
"""
|
|
383
|
+
found = sweep(config, delete=not args.check)
|
|
384
|
+
if args.json:
|
|
385
|
+
print(json.dumps(found.payload(config), indent=2))
|
|
386
|
+
else:
|
|
387
|
+
print(found.stated(config))
|
|
388
|
+
# A file the reading proved spent and the filesystem would not remove: the directory did not
|
|
389
|
+
# reach the state this reported, which is the one outcome a caller has to be able to branch
|
|
390
|
+
# on. `EXIT_USAGE` because that is where an `OSError` lands in `_refused`, and this is the
|
|
391
|
+
# same class of failure caught one layer earlier so the verdict about the others survives it.
|
|
392
|
+
return EXIT_USAGE if found.refused else EXIT_OK
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
def _uninstall(config: Config, args: argparse.Namespace) -> int:
|
|
396
|
+
"""Take the harness back out of a project that was wired to a checkout (RK138).
|
|
397
|
+
|
|
398
|
+
`config` is unused for `_install`'s reason, and no `--source` is taken for the reason the
|
|
399
|
+
module states: the wiring is recognised by this project's own entries, so un-wiring works
|
|
400
|
+
after the checkout it named is gone — which is when it is usually wanted.
|
|
401
|
+
"""
|
|
402
|
+
del config
|
|
403
|
+
try:
|
|
404
|
+
intent = removal(args.directory) if args.check else uninstall(args.directory)
|
|
405
|
+
except (ValueError, OSError) as error:
|
|
406
|
+
return _refused(error)
|
|
407
|
+
|
|
408
|
+
if args.json:
|
|
409
|
+
print(json.dumps(intent.payload(args.check), indent=2))
|
|
410
|
+
else:
|
|
411
|
+
print(intent.stated(args.check))
|
|
412
|
+
if args.check:
|
|
413
|
+
for line in intent.verdict():
|
|
414
|
+
print(line, file=sys.stderr)
|
|
415
|
+
if args.check and intent.changing:
|
|
416
|
+
return EXIT_GATE
|
|
417
|
+
return EXIT_OK
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
def _report(config: Config, args: argparse.Namespace) -> int:
|
|
421
|
+
"""Capture one defect in this tool (RK85). Exit 2 refuses the claim, never the capture.
|
|
422
|
+
|
|
423
|
+
The refusal is the point: a report is a task line for a backlog that holds a limit, so
|
|
424
|
+
the sentence is judged in the session that made the claim rather than in the review of
|
|
425
|
+
an issue. What the observed command exits with is a *fact of the capture* and never this
|
|
426
|
+
command's own code — the whole reason to run it is that it failed.
|
|
427
|
+
"""
|
|
428
|
+
argv = list(args.command_argv)
|
|
429
|
+
if argv and argv[0] == "--":
|
|
430
|
+
argv = argv[1:]
|
|
431
|
+
if not argv:
|
|
432
|
+
print("roadkeep: name the command that failed, after a bare --", file=sys.stderr)
|
|
433
|
+
return EXIT_USAGE
|
|
434
|
+
violations = check(args.symptom, args.why, args.block)
|
|
435
|
+
if violations:
|
|
436
|
+
print("roadkeep: refused, nothing captured:", file=sys.stderr)
|
|
437
|
+
for violation in violations:
|
|
438
|
+
print(f" {violation}", file=sys.stderr)
|
|
439
|
+
return EXIT_USAGE
|
|
440
|
+
# Resolved before the capture is composed and not in the `--issue` branch where it used to
|
|
441
|
+
# be read (RK1161): where this went is a fact of the capture, so the artefact records it and
|
|
442
|
+
# `capture filed` can qualify a bare id from the file instead of asking for it again.
|
|
443
|
+
aimed = args.to or config.upstream
|
|
444
|
+
found = capture(
|
|
445
|
+
args.symptom, args.why, args.block, argv, config.root, embed=args.embed, upstream=aimed
|
|
446
|
+
).without(*args.without)
|
|
447
|
+
# Written before it is printed (RK89): what only exists on a stdout depends on the
|
|
448
|
+
# caller taking a second step, and this block's own RK86 is the record of second steps
|
|
449
|
+
# not being taken. On stderr, so `--json` and `--issue` stay pipeable.
|
|
450
|
+
kept = keep(found, config.root)
|
|
451
|
+
# The clause on the line that was misread (RK1139): a session ran this twice, read `kept
|
|
452
|
+
# …json` as "filed" and reported the work done — and `stats` answered `total 2` and was
|
|
453
|
+
# right, so nothing disagreed. "File it:" was already printed, at the end of the dump
|
|
454
|
+
# below; what was missing is the **negative**, said where the path is.
|
|
455
|
+
print(f"kept {kept.path} (a capture, not a backlog line)", file=sys.stderr)
|
|
456
|
+
# With the flag that closes the row filled in (RK1141): the path is decided here, by
|
|
457
|
+
# `keep`, so the capture cannot name itself — and a command a caller has to complete is a
|
|
458
|
+
# second step, which is what RK86 is this block's own record of.
|
|
459
|
+
print(f"file {found.filing} --capture {kept.path}", file=sys.stderr)
|
|
460
|
+
if kept.complaint:
|
|
461
|
+
print(f"roadkeep: {kept.complaint}", file=sys.stderr)
|
|
462
|
+
# Which of the two forms this is, said here because this is the only moment anybody can
|
|
463
|
+
# choose (RK481). `replay` refuses a capture that carries no governed files, and by the
|
|
464
|
+
# time it does the reporting session is over — so the flag is named to the one caller who
|
|
465
|
+
# could still pass it. Not the default, and that stays: `--embed` is this project's text
|
|
466
|
+
# leaving it, and a tool that published a private repository's roadmap by being helpful
|
|
467
|
+
# is the worse failure. The silence is what was wrong.
|
|
468
|
+
print(
|
|
469
|
+
"replay runs it anywhere: the governed files ride along"
|
|
470
|
+
if args.embed
|
|
471
|
+
else "replay refuses it: no governed files ride along — `--embed` writes the "
|
|
472
|
+
"capture that runs, and sends this project's text with it",
|
|
473
|
+
file=sys.stderr,
|
|
474
|
+
)
|
|
475
|
+
# RK440: the capture carries the annotation for whoever triages it, and this is the same
|
|
476
|
+
# fact said to the session that can still act on it. On stderr with the rest of the
|
|
477
|
+
# narration, so `--json` and `--issue` stay pipeable.
|
|
478
|
+
if found.failure.stopped:
|
|
479
|
+
print(f"roadkeep: {STOPPED_NOTICE}", file=sys.stderr)
|
|
480
|
+
if args.json:
|
|
481
|
+
print(json.dumps(found.as_dict(), indent=2, ensure_ascii=False))
|
|
482
|
+
return EXIT_OK
|
|
483
|
+
if not args.issue:
|
|
484
|
+
print(found)
|
|
485
|
+
return EXIT_OK
|
|
486
|
+
if aimed is None:
|
|
487
|
+
# Guessed, this publishes a private repository's contents in a stranger's tracker.
|
|
488
|
+
print(
|
|
489
|
+
"roadkeep: no upstream to file against: declare [report] upstream = "
|
|
490
|
+
"'owner/repo' in roadkeep.toml, or pass --to",
|
|
491
|
+
file=sys.stderr,
|
|
492
|
+
)
|
|
493
|
+
return EXIT_USAGE
|
|
494
|
+
print(body(found))
|
|
495
|
+
sys.stdout.flush()
|
|
496
|
+
print(handoff(found, aimed), file=sys.stderr)
|
|
497
|
+
return EXIT_OK
|
|
498
|
+
|
|
499
|
+
|
|
500
|
+
def _replay(config: Config, args: argparse.Namespace) -> int:
|
|
501
|
+
"""Re-run one stored capture (RK88). Exit 1 when the verdict is not the recorded one.
|
|
502
|
+
|
|
503
|
+
A scratch directory and never the working tree: the capture carries a `roadkeep.toml`
|
|
504
|
+
and a governed file, and staging those over somebody's project would be the one write
|
|
505
|
+
this tool makes that nobody asked for.
|
|
506
|
+
"""
|
|
507
|
+
try:
|
|
508
|
+
# `locate` for `_capture_filed`'s reason (RK1396): a capture is a file of the project,
|
|
509
|
+
# and the address a reader has is the one `stats` printed. `tolerates_config_error` does
|
|
510
|
+
# not weaken it — a default config still knows the root `-C` named, which is the whole
|
|
511
|
+
# of what this needs.
|
|
512
|
+
recorded = json.loads(config.locate(args.path).read_text(encoding="utf-8"))
|
|
513
|
+
except (OSError, ValueError) as error:
|
|
514
|
+
print(f"roadkeep: {error}", file=sys.stderr)
|
|
515
|
+
return EXIT_USAGE
|
|
516
|
+
with tempfile.TemporaryDirectory(prefix="roadkeep-replay-") as scratch:
|
|
517
|
+
outcome = replay(recorded, scratch)
|
|
518
|
+
expected = bool(recorded.get("reproduces", True))
|
|
519
|
+
|
|
520
|
+
if args.json:
|
|
521
|
+
print(json.dumps(outcome.payload(args.path, expected), indent=2))
|
|
522
|
+
else:
|
|
523
|
+
print(outcome.stated(args.path, expected))
|
|
524
|
+
return EXIT_OK if outcome.agrees(expected) else EXIT_GATE
|
|
525
|
+
|
|
526
|
+
|
|
527
|
+
def _mcp(config: Config, args: argparse.Namespace) -> int:
|
|
528
|
+
"""Hand stdin and stdout to the protocol loop (RK24).
|
|
529
|
+
|
|
530
|
+
The directory and not the `Config`: the server re-discovers it per message, so a
|
|
531
|
+
`roadkeep.toml` edited during the session is the one the next `tools/list` describes.
|
|
532
|
+
"""
|
|
533
|
+
return serve(sys.stdin, sys.stdout, args.directory)
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
def declare_wiring(subcommands: argparse._SubParsersAction) -> None:
|
|
537
|
+
"""This module's verbs, declared where their handlers are (RK1171).
|
|
538
|
+
|
|
539
|
+
`build_parser` called forty-nine blocks like these in a row; what it calls now is an index
|
|
540
|
+
over the modules that own them. The move is what RK1169 and RK1170 bought: the flags a verb
|
|
541
|
+
declares, the reasons it withholds and the record it answers with are one file's, so a
|
|
542
|
+
change to any of them is one file's too.
|
|
543
|
+
|
|
544
|
+
The order inside is `build_parser`'s own, which is where these blocks sat.
|
|
545
|
+
"""
|
|
546
|
+
report_parser = subcommands.add_parser(
|
|
547
|
+
"report",
|
|
548
|
+
help="capture a defect in this tool, with what the failing session knew",
|
|
549
|
+
description=(
|
|
550
|
+
"Re-run the command that failed, in this process, and emit what identifies the "
|
|
551
|
+
"defect: the argv, the exit code, the engine that answered, this project's "
|
|
552
|
+
"roadkeep.toml, the line the engine objected to and any traceback. The two "
|
|
553
|
+
"facts a machine cannot supply are arguments and are refused here against this "
|
|
554
|
+
"tool's own schema, so a report arrives inside the limits the backlog it is "
|
|
555
|
+
"destined for enforces. Nothing is sent: the capture is printed, and delivery "
|
|
556
|
+
"is a separate decision."
|
|
557
|
+
),
|
|
558
|
+
)
|
|
559
|
+
report_parser.add_argument(
|
|
560
|
+
"--symptom", required=True, help="what does not work — a phrase, never a fix"
|
|
561
|
+
)
|
|
562
|
+
report_parser.add_argument(
|
|
563
|
+
"--why", required=True, help="one sentence, ending in a stop: why it matters"
|
|
564
|
+
)
|
|
565
|
+
report_parser.add_argument(
|
|
566
|
+
"--block",
|
|
567
|
+
default="F",
|
|
568
|
+
help="the block of roadkeep's own backlog this belongs under (default: F)",
|
|
569
|
+
)
|
|
570
|
+
report_parser.add_argument(
|
|
571
|
+
"--without",
|
|
572
|
+
dest="without",
|
|
573
|
+
action="append",
|
|
574
|
+
default=[],
|
|
575
|
+
metavar="PART",
|
|
576
|
+
choices=PARTS,
|
|
577
|
+
help=(
|
|
578
|
+
"drop one part of the capture, repeatable: what a private repository must not "
|
|
579
|
+
"publish is deleted by name, never scrubbed by a filter"
|
|
580
|
+
),
|
|
581
|
+
)
|
|
582
|
+
report_parser.add_argument(
|
|
583
|
+
"--issue",
|
|
584
|
+
action="store_true",
|
|
585
|
+
help=(
|
|
586
|
+
"print the tracker body on stdout and the command that files it on stderr; "
|
|
587
|
+
"nothing is sent, and the destination is [report] upstream"
|
|
588
|
+
),
|
|
589
|
+
)
|
|
590
|
+
report_parser.add_argument(
|
|
591
|
+
"--to",
|
|
592
|
+
metavar="OWNER/REPO",
|
|
593
|
+
help="file against this repository instead of the configured upstream",
|
|
594
|
+
)
|
|
595
|
+
report_parser.add_argument(
|
|
596
|
+
"--embed",
|
|
597
|
+
action="store_true",
|
|
598
|
+
help=(
|
|
599
|
+
"carry the governed files this project declares, so the capture can be replayed "
|
|
600
|
+
"without this repository — a test somewhere else, and files leaving here"
|
|
601
|
+
),
|
|
602
|
+
)
|
|
603
|
+
report_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
604
|
+
report_parser.add_argument(
|
|
605
|
+
"command_argv",
|
|
606
|
+
nargs=argparse.REMAINDER,
|
|
607
|
+
metavar="-- COMMAND",
|
|
608
|
+
help="the roadkeep command that failed, after a bare --, without the program name",
|
|
609
|
+
)
|
|
610
|
+
report_parser.set_defaults(handler=_report, tolerates_config_error=True, reads_only=True)
|
|
611
|
+
|
|
612
|
+
replay_parser = subcommands.add_parser(
|
|
613
|
+
"replay",
|
|
614
|
+
help="re-run a stored capture against the tree that is here now",
|
|
615
|
+
description=(
|
|
616
|
+
"Stage the capture's own configuration and file in a scratch directory, run "
|
|
617
|
+
"the argv it recorded, and answer whether the defect still reproduces. Nothing "
|
|
618
|
+
"from the reporting project is needed: a capture that was never made replayable "
|
|
619
|
+
"says which part it lacks instead of being staged from a guess. Exits 1 when "
|
|
620
|
+
"the answer differs from the `reproduces` the file records — which is what "
|
|
621
|
+
"makes a corpus of field reports a gate rather than a folder."
|
|
622
|
+
),
|
|
623
|
+
)
|
|
624
|
+
replay_parser.add_argument("path", help="a capture written by `report --json`")
|
|
625
|
+
replay_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
626
|
+
replay_parser.set_defaults(handler=_replay, tolerates_config_error=True, reads_only=True)
|
|
627
|
+
|
|
628
|
+
capture_parser = subcommands.add_parser(
|
|
629
|
+
"capture",
|
|
630
|
+
help="what became of a capture already on disk",
|
|
631
|
+
description=(
|
|
632
|
+
"The third of the capture pair's family (RK1142). `report` writes one and "
|
|
633
|
+
"`replay` re-runs it; this says what happened to one that is already there — "
|
|
634
|
+
"which task it was filed as, and whether that answer makes it spent. The "
|
|
635
|
+
"retention `keep` parked arrives here as `sweep` (RK1394), in its exact half "
|
|
636
|
+
"only: rotation, an age limit and a dedup by argv are still open, and they are "
|
|
637
|
+
"what a capture that never gets a stamp waits for."
|
|
638
|
+
),
|
|
639
|
+
)
|
|
640
|
+
capture_actions = capture_parser.add_subparsers(dest="action", required=True)
|
|
641
|
+
capture_filed = capture_actions.add_parser(
|
|
642
|
+
"filed",
|
|
643
|
+
help="record which task a kept capture was filed as",
|
|
644
|
+
description=(
|
|
645
|
+
"Write into the capture the id it was filed as, so the row `stats` counts is "
|
|
646
|
+
"cleared by a fact in the artefact rather than by a symptom that matches "
|
|
647
|
+
"(RK1141). `add --capture` does this for a capture being filed now; this is the "
|
|
648
|
+
"door for one already on disk, and it is the whole of what RK1142 was: clearing "
|
|
649
|
+
"this repository's own row took a `python -c`, which is what L5 exists against. "
|
|
650
|
+
"Refused where no governed file holds the id — a stamp naming nothing is a link "
|
|
651
|
+
"to nothing — and where the path is not a capture this tool wrote. An id "
|
|
652
|
+
"**qualified by a repository** is the exception (RK1160): a defect in roadkeep is "
|
|
653
|
+
"filed in roadkeep's backlog, so no local file will ever hold that id, and both "
|
|
654
|
+
"readers left a row nothing could clear."
|
|
655
|
+
),
|
|
656
|
+
)
|
|
657
|
+
capture_filed.add_argument("path", help="a capture under .roadkeep/reports/")
|
|
658
|
+
capture_filed.add_argument(
|
|
659
|
+
"--as",
|
|
660
|
+
dest="task_id",
|
|
661
|
+
required=True,
|
|
662
|
+
metavar="ID",
|
|
663
|
+
help=(
|
|
664
|
+
"the task it was filed as, e.g. RK1138 — refused unless a governed file holds it, "
|
|
665
|
+
"or `owner/repo#ID` for one filed in another backlog this project cannot read"
|
|
666
|
+
),
|
|
667
|
+
)
|
|
668
|
+
capture_filed.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
669
|
+
capture_filed.set_defaults(handler=_capture_filed, wiring=True)
|
|
670
|
+
|
|
671
|
+
capture_sweep = capture_actions.add_parser(
|
|
672
|
+
"sweep",
|
|
673
|
+
help="delete the captures the ledger records as shipped",
|
|
674
|
+
description=(
|
|
675
|
+
"The retention `keep` parks, keyed on the fact the artefact already carries "
|
|
676
|
+
"(RK1394). A capture whose `filed` id the ledger records as shipped is answered "
|
|
677
|
+
"by this repository's own record, so it is deleted; every other state is named "
|
|
678
|
+
"and left. An age limit would be the weaker key — it says time passed where a "
|
|
679
|
+
"stamp says the work landed — and it deletes exactly the captures an exact "
|
|
680
|
+
"reading protects: one never filed, one open, and one delivered to a backlog "
|
|
681
|
+
"this project cannot read. `--check` prints the same table and removes nothing."
|
|
682
|
+
),
|
|
683
|
+
)
|
|
684
|
+
capture_sweep.add_argument(
|
|
685
|
+
"--check",
|
|
686
|
+
action="store_true",
|
|
687
|
+
help="say what would go and leave the directory alone",
|
|
688
|
+
)
|
|
689
|
+
capture_sweep.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
690
|
+
# `reads_only` for `report`'s and `replay`'s reason and not as a claim about the filesystem
|
|
691
|
+
# (RK167): what it declares is that no **governed** file is written, which is what decides
|
|
692
|
+
# whether the lock is taken — the ledger is read here and nothing else is, and the files that
|
|
693
|
+
# go are in a directory git was taught to ignore.
|
|
694
|
+
#
|
|
695
|
+
# And deliberately no `wiring=True`, unlike its sibling. That exemption exists so a pin has a
|
|
696
|
+
# way to be satisfied and a defect a way to be filed (see `cli._enforced`); neither is what
|
|
697
|
+
# this does — it *deletes* evidence, which is the one write a copy the project has pinned
|
|
698
|
+
# away from should be refused, and a sweep postponed until the right copy runs costs
|
|
699
|
+
# kilobytes.
|
|
700
|
+
capture_sweep.set_defaults(handler=_capture_sweep, reads_only=True)
|
|
701
|
+
|
|
702
|
+
init_parser = subcommands.add_parser(
|
|
703
|
+
"init",
|
|
704
|
+
help="scaffold roadkeep.toml and the files it declares",
|
|
705
|
+
description=(
|
|
706
|
+
"Write the configuration and the three governed files, or write nothing. The "
|
|
707
|
+
"config is rendered from the schema's own defaults, so a scaffold cannot "
|
|
708
|
+
"declare a format the tool does not implement. No starter task and no prose: "
|
|
709
|
+
"a title, the blocks you name, and where the non-goals go."
|
|
710
|
+
),
|
|
711
|
+
)
|
|
712
|
+
init_parser.add_argument(
|
|
713
|
+
"--prefix",
|
|
714
|
+
action="append",
|
|
715
|
+
help=(
|
|
716
|
+
"the id prefix, uppercase alphanumeric (default: RK). Repeatable for a "
|
|
717
|
+
"backlog numbered by track; the first is what `add` mints under"
|
|
718
|
+
),
|
|
719
|
+
)
|
|
720
|
+
init_parser.add_argument(
|
|
721
|
+
"--block",
|
|
722
|
+
action="append",
|
|
723
|
+
dest="blocks",
|
|
724
|
+
metavar="LABEL",
|
|
725
|
+
help=(
|
|
726
|
+
"a block heading, repeatable: 'A' or 'A — The model'. A task is filed "
|
|
727
|
+
"under a heading and a write never invents one (default: A)"
|
|
728
|
+
),
|
|
729
|
+
)
|
|
730
|
+
init_parser.add_argument(
|
|
731
|
+
"--strategy",
|
|
732
|
+
action="store_true",
|
|
733
|
+
help=(
|
|
734
|
+
"scaffold the strategy file too: a prose role for a document that outlives "
|
|
735
|
+
"every task filed under it, where an improvements section is one task's "
|
|
736
|
+
"rationale and goes when the line ships"
|
|
737
|
+
),
|
|
738
|
+
)
|
|
739
|
+
init_parser.add_argument(
|
|
740
|
+
"--deferred",
|
|
741
|
+
action="store_true",
|
|
742
|
+
help=(
|
|
743
|
+
"scaffold the deferred store too: the file `defer` moves a line to, which "
|
|
744
|
+
"keeps the id, the deps and the section a retirement deletes. Without it that "
|
|
745
|
+
"verb refuses, and the remedy is a toml key and a skeleton written by hand"
|
|
746
|
+
),
|
|
747
|
+
)
|
|
748
|
+
init_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
749
|
+
init_parser.set_defaults(handler=_init, wiring=True)
|
|
750
|
+
|
|
751
|
+
declare_parser = subcommands.add_parser(
|
|
752
|
+
"declare",
|
|
753
|
+
help="add one governed role or open one opt-in table, past `init`",
|
|
754
|
+
description=(
|
|
755
|
+
"Write one role's file and the `[files]` key governing it, or open an opt-in "
|
|
756
|
+
"table, on a project past `init`. Reach for it when a verb refuses over an "
|
|
757
|
+
"undeclared role or table: `init` writes both once and refuses to run twice, so "
|
|
758
|
+
"either declined at scaffold time was otherwise a hand edit. A role's file "
|
|
759
|
+
"arrives with the block headings the roadmap carries, spelled as that file spells "
|
|
760
|
+
"one; a table arrives empty, which is what opting in means, and `govern` tunes "
|
|
761
|
+
"what is in it. The config keeps every other byte. Refused where it is already "
|
|
762
|
+
"declared."
|
|
763
|
+
),
|
|
764
|
+
)
|
|
765
|
+
# Not argparse `choices`, for `--role`'s own reason (RK304) read one step further: what is
|
|
766
|
+
# answerable here is the roles this *project* has not declared, which a parser built once
|
|
767
|
+
# per process cannot say — so the closed set is published per project in the tool schema and
|
|
768
|
+
# refused by name in the command.
|
|
769
|
+
declare_parser.add_argument(
|
|
770
|
+
"role",
|
|
771
|
+
help=(
|
|
772
|
+
f"which governed file to declare, one of {', '.join(ROLES)} — or an opt-in "
|
|
773
|
+
f"table to open, one of {', '.join(OPT_IN)}"
|
|
774
|
+
),
|
|
775
|
+
)
|
|
776
|
+
declare_parser.add_argument(
|
|
777
|
+
"--path",
|
|
778
|
+
help="where it goes, project-relative (default: this role's own docs/ path)",
|
|
779
|
+
)
|
|
780
|
+
declare_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
781
|
+
declare_parser.set_defaults(handler=_declare)
|
|
782
|
+
|
|
783
|
+
adopt_parser = subcommands.add_parser(
|
|
784
|
+
"adopt",
|
|
785
|
+
help="what an existing backlog would have to change to pass",
|
|
786
|
+
description=(
|
|
787
|
+
"Run the schema over a backlog this tool does not own yet and report the "
|
|
788
|
+
"delta: what parses, what conforms, the longest field against its limit, the "
|
|
789
|
+
"markers to declare. Writes nothing and never fails — an estimate that "
|
|
790
|
+
"exits 1 is a gate, and the point is to take it before the commitment."
|
|
791
|
+
),
|
|
792
|
+
)
|
|
793
|
+
adopt_parser.add_argument("path", help="the file to measure, e.g. docs/ROADMAP.md")
|
|
794
|
+
adopt_parser.add_argument(
|
|
795
|
+
"--prefix",
|
|
796
|
+
action="append",
|
|
797
|
+
help=(
|
|
798
|
+
"read the ids under this prefix, repeatable for a backlog numbered by "
|
|
799
|
+
"track; without it the project's own is used, or the one the file's ids "
|
|
800
|
+
"already spell — never all of them, which is a judgement and not a count"
|
|
801
|
+
),
|
|
802
|
+
)
|
|
803
|
+
adopt_parser.add_argument(
|
|
804
|
+
"--ref-scheme",
|
|
805
|
+
dest="ref_scheme",
|
|
806
|
+
choices=("id", "outline"),
|
|
807
|
+
help=(
|
|
808
|
+
"measure the pointers under this scheme: 'outline' asks what adopting the "
|
|
809
|
+
"tool costs, 'id' what adopting it and renumbering the outline costs"
|
|
810
|
+
),
|
|
811
|
+
)
|
|
812
|
+
adopt_parser.add_argument(
|
|
813
|
+
"--ledger",
|
|
814
|
+
action="store_true",
|
|
815
|
+
help="measure it as a changelog: shipped marker, no deps field, no pointer",
|
|
816
|
+
)
|
|
817
|
+
adopt_parser.add_argument(
|
|
818
|
+
"--sections",
|
|
819
|
+
action="store_true",
|
|
820
|
+
help=(
|
|
821
|
+
"measure it as a rationale file: sections against `section`, and the width "
|
|
822
|
+
"its prose is already wrapped to — the two limits an adopter has to declare"
|
|
823
|
+
),
|
|
824
|
+
)
|
|
825
|
+
adopt_parser.add_argument(
|
|
826
|
+
"--with",
|
|
827
|
+
dest="alongside",
|
|
828
|
+
metavar="PATH",
|
|
829
|
+
action="append",
|
|
830
|
+
default=[],
|
|
831
|
+
help=(
|
|
832
|
+
"another prose file an address could be doubled across, repeatable — the one "
|
|
833
|
+
"measure here that is about a set of files rather than this one; requires "
|
|
834
|
+
"--sections, and never inferred from the directory"
|
|
835
|
+
),
|
|
836
|
+
)
|
|
837
|
+
adopt_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
838
|
+
# Read-only, which RK18 has been true of since this verb existed and nothing declared:
|
|
839
|
+
# `adopt` measures a file and exits 0, writing nothing anywhere. Undeclared it took the
|
|
840
|
+
# write lock for a run that cannot conflict with one, and — since RK1147 published a door
|
|
841
|
+
# that reruns it — said `writes: true` in a payload about a command that writes nothing.
|
|
842
|
+
adopt_parser.set_defaults(handler=_adopt, reads_only=True)
|
|
843
|
+
|
|
844
|
+
install_parser = subcommands.add_parser(
|
|
845
|
+
"install",
|
|
846
|
+
help="wire this project to the checkout answering, the way the plugin would",
|
|
847
|
+
description=(
|
|
848
|
+
"Write the surfaces the plugin ships, for a project that runs roadkeep from a "
|
|
849
|
+
"checkout instead: the server, the guard on its three hook events, and the "
|
|
850
|
+
"skill that says which command to call — plus the CI workflow when the "
|
|
851
|
+
"repository already has one. Every byte is translated from what the plugin "
|
|
852
|
+
"carries, the launcher's path being the only substituted fact, so the skill "
|
|
853
|
+
"cannot drift from the file it was copied from. The skill is refreshed on "
|
|
854
|
+
"every run; the declarations keep everything they hold that is not this "
|
|
855
|
+
"project's entry; the workflow is written once and then yours."
|
|
856
|
+
),
|
|
857
|
+
)
|
|
858
|
+
install_parser.add_argument(
|
|
859
|
+
"--check",
|
|
860
|
+
action="store_true",
|
|
861
|
+
help=(
|
|
862
|
+
"write nothing and exit 1 on anything that would change: the gate that keeps "
|
|
863
|
+
"the copied skill in step, for a CI job or a pre-commit hook"
|
|
864
|
+
),
|
|
865
|
+
)
|
|
866
|
+
install_parser.add_argument(
|
|
867
|
+
"--source",
|
|
868
|
+
metavar="PATH",
|
|
869
|
+
help=(
|
|
870
|
+
"the roadkeep checkout to wire in (default: the one this command is running "
|
|
871
|
+
"from, which is the one whose hook and tools the project would get)"
|
|
872
|
+
),
|
|
873
|
+
)
|
|
874
|
+
install_parser.add_argument(
|
|
875
|
+
"--register-merge",
|
|
876
|
+
action="store_true",
|
|
877
|
+
help=(
|
|
878
|
+
"wire the merge driver too — the `.gitattributes` half of `merge --register`, "
|
|
879
|
+
"with the `git config` line printed for you to run: a flag and not a default, "
|
|
880
|
+
"because it is configuration and the other half is outside these files"
|
|
881
|
+
),
|
|
882
|
+
)
|
|
883
|
+
install_parser.add_argument(
|
|
884
|
+
"--committed",
|
|
885
|
+
action="store_true",
|
|
886
|
+
help=(
|
|
887
|
+
"wire a launcher committed to this repository instead of a path to the checkout, "
|
|
888
|
+
"so the guard reaches an environment that installs no plugin and clones no "
|
|
889
|
+
"checkout — Claude Code on the web. It defers where the harness has the plugin "
|
|
890
|
+
"wired for this project, and never blocks a turn"
|
|
891
|
+
),
|
|
892
|
+
)
|
|
893
|
+
install_parser.add_argument(
|
|
894
|
+
"--vendor",
|
|
895
|
+
action="store_true",
|
|
896
|
+
help=(
|
|
897
|
+
"copy the highest-versioned roadkeep this machine can reach into .roadkeep/, so "
|
|
898
|
+
"the project runs a pinned engine instead of whichever copy a search order "
|
|
899
|
+
"reaches first; ROADKEEP_SRC names a working checkout, which is otherwise skipped"
|
|
900
|
+
),
|
|
901
|
+
)
|
|
902
|
+
install_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
903
|
+
install_parser.set_defaults(handler=_install, wiring=True)
|
|
904
|
+
|
|
905
|
+
engines_parser = subcommands.add_parser(
|
|
906
|
+
"engines",
|
|
907
|
+
help="which copies of roadkeep write, judge and gate this project",
|
|
908
|
+
description=(
|
|
909
|
+
"An adopting project wires three: the plugin its hook and skill run, the action "
|
|
910
|
+
"its workflow gates on, and whatever `roadkeep` the caller invokes. They are "
|
|
911
|
+
"allowed to differ — a cache may lag a checkout — and what is not survivable is "
|
|
912
|
+
"not being able to say which one answered. A fourth is read and never judged: "
|
|
913
|
+
"the merge driver git would run, a command rather than a version. Exits 1 where "
|
|
914
|
+
"the two that state a version state different ones."
|
|
915
|
+
),
|
|
916
|
+
)
|
|
917
|
+
# The one line a caller pastes (RK1230). Its own flag rather than a row in the table:
|
|
918
|
+
# what a shell needs is a value it can read into a variable, and the table is exactly the
|
|
919
|
+
# thing a session was reduced to grepping — or, worse, to finding by listing a cache.
|
|
920
|
+
engines_parser.add_argument(
|
|
921
|
+
"--invoke",
|
|
922
|
+
action="store_true",
|
|
923
|
+
help=(
|
|
924
|
+
"print only the command that reaches the copy wired to this project, so a shell "
|
|
925
|
+
"invocation needs no directory listing to find it"
|
|
926
|
+
),
|
|
927
|
+
)
|
|
928
|
+
engines_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
929
|
+
# A read, and the exit code is its verdict rather than a fault (RK271): the three lines
|
|
930
|
+
# above it have already said everything, and `/plugin update` is the move.
|
|
931
|
+
engines_parser.set_defaults(handler=_engines, reads_only=True)
|
|
932
|
+
|
|
933
|
+
uninstall_parser = subcommands.add_parser(
|
|
934
|
+
"uninstall",
|
|
935
|
+
help="take this project's entries back out of the four surfaces install wrote",
|
|
936
|
+
description=(
|
|
937
|
+
"Un-wire a project that ran roadkeep from a checkout — moving to the plugin, or "
|
|
938
|
+
"off the tool entirely (RK138). The inverse of `install` under the same two "
|
|
939
|
+
"rules: the declarations keep every entry that is not this project's, and a "
|
|
940
|
+
"file that is not a JSON object is refused rather than rewritten. A file left "
|
|
941
|
+
"holding nothing but what `install` wrote is deleted, because that is the state "
|
|
942
|
+
"it was created from. It reads no checkout — the wiring is recognised by the "
|
|
943
|
+
"server's name and the launcher a hook runs — so a project can be un-wired "
|
|
944
|
+
"after the tree it pointed at is gone. The CI workflow stays: that gate calls "
|
|
945
|
+
"the published action and not the checkout."
|
|
946
|
+
),
|
|
947
|
+
)
|
|
948
|
+
uninstall_parser.add_argument(
|
|
949
|
+
"--check",
|
|
950
|
+
action="store_true",
|
|
951
|
+
help=(
|
|
952
|
+
"take nothing out and exit 1 while anything is still wired: the same tense "
|
|
953
|
+
"`install --check` reports in, on the other direction"
|
|
954
|
+
),
|
|
955
|
+
)
|
|
956
|
+
uninstall_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
957
|
+
uninstall_parser.set_defaults(handler=_uninstall, wiring=True)
|
|
958
|
+
|
|
959
|
+
mcp_parser = subcommands.add_parser(
|
|
960
|
+
"mcp",
|
|
961
|
+
help="serve add, ship, pick and lint as MCP tools over stdio",
|
|
962
|
+
description=(
|
|
963
|
+
"Speak JSON-RPC on stdin and stdout so the fields arrive as a schema the "
|
|
964
|
+
"client validates instead of flag names an agent types from memory (RK24). "
|
|
965
|
+
"Every tool is dispatched through this same parser, so the refusal is the one "
|
|
966
|
+
"a terminal prints. Not for a human to call: a session's client starts it."
|
|
967
|
+
),
|
|
968
|
+
)
|
|
969
|
+
# Same reason as `guard`: the process is started once for a whole session, so refusing
|
|
970
|
+
# to start on a broken `roadkeep.toml` would take the tools away exactly when the gate
|
|
971
|
+
# is what the project needs. `tools/list` describes the defaults and the first call
|
|
972
|
+
# reports the error.
|
|
973
|
+
mcp_parser.set_defaults(handler=_mcp, tolerates_config_error=True, reads_only=True)
|
|
974
|
+
|