workorder 0.5.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.
- workorder/__init__.py +3 -0
- workorder/__main__.py +3 -0
- workorder/cli.py +198 -0
- workorder/gate.py +1292 -0
- workorder/store.py +1164 -0
- workorder-0.5.0.dist-info/METADATA +397 -0
- workorder-0.5.0.dist-info/RECORD +11 -0
- workorder-0.5.0.dist-info/WHEEL +5 -0
- workorder-0.5.0.dist-info/entry_points.txt +2 -0
- workorder-0.5.0.dist-info/licenses/LICENSE +21 -0
- workorder-0.5.0.dist-info/top_level.txt +1 -0
workorder/__init__.py
ADDED
workorder/__main__.py
ADDED
workorder/cli.py
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
"""The workorder command."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
import subprocess
|
|
8
|
+
import sys
|
|
9
|
+
|
|
10
|
+
from . import __version__, gate
|
|
11
|
+
from . import store as s
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def parser():
|
|
15
|
+
result = argparse.ArgumentParser(
|
|
16
|
+
prog="workorder", description="The task record for coding agents: every task recorded, a clear history, agents always go back to it.",
|
|
17
|
+
epilog="Pass a test or read-back command after --, for example: "
|
|
18
|
+
"workorder receipt test --task TASK-1 -- python -m pytest")
|
|
19
|
+
result.add_argument("--version", action="version", version=f"workorder {__version__}")
|
|
20
|
+
commands = result.add_subparsers(dest="action", required=True, metavar="command")
|
|
21
|
+
new = commands.add_parser("new", help="reserve a task id on origin and write tasks/<id>.md")
|
|
22
|
+
new.add_argument("--title", required=True)
|
|
23
|
+
new.add_argument("--owner", required=True)
|
|
24
|
+
new.add_argument("--ships", choices=["none", "repo", "live"], default="none",
|
|
25
|
+
help="what CLOSED needs beyond DONE: nothing, a merge, or also deployment"
|
|
26
|
+
" read-backs (default: none)")
|
|
27
|
+
new.add_argument("--prefix", default="TASK", help="id prefix (default: TASK)")
|
|
28
|
+
new.add_argument("--local", action="store_true",
|
|
29
|
+
help="number the id locally even with an origin remote (no tag is pushed)")
|
|
30
|
+
new.add_argument("--test", default="", metavar="COMMAND",
|
|
31
|
+
help="the task's test command; once set, only a run of exactly this command counts")
|
|
32
|
+
new.add_argument("--template", choices=["extended", "simple"], default="extended",
|
|
33
|
+
help="extended: planning fields and Context/Scope/Lanes/Acceptance/Progress sections;"
|
|
34
|
+
" simple: the seven required fields only, as in 0.1.0 (default: extended)")
|
|
35
|
+
receipt = commands.add_parser("receipt", help="record evidence: implemented, test, merged, deployed, live")
|
|
36
|
+
receipt.add_argument("kind", choices=sorted(s.KINDS))
|
|
37
|
+
receipt.add_argument("--task", required=True)
|
|
38
|
+
receipt.add_argument("--target", help="deployment name, required for deployed and live")
|
|
39
|
+
receipt.add_argument("--ref", default="refs/heads/main",
|
|
40
|
+
help="branch on origin that merged reads (default: refs/heads/main)")
|
|
41
|
+
helps = {"show": "print a task's recorded and computed status",
|
|
42
|
+
"claim": "take a task with a pushed Git tag", "release": "give up your claim on a task"}
|
|
43
|
+
for name, text in helps.items():
|
|
44
|
+
sub = commands.add_parser(name, help=text)
|
|
45
|
+
sub.add_argument("--task", required=True)
|
|
46
|
+
if name == "release":
|
|
47
|
+
sub.add_argument("--force", action="store_true",
|
|
48
|
+
help="release a claim whose clone or worktree is gone")
|
|
49
|
+
commands.add_parser("claims", help="list active claims")
|
|
50
|
+
renew = commands.add_parser("renew", help="record implemented and the task's test again on the current"
|
|
51
|
+
" commit (after a squash merge or rebase), and the merge if the task ships")
|
|
52
|
+
renew.add_argument("--task", required=True)
|
|
53
|
+
note = commands.add_parser("note", help="add a dated line under the task's Progress section")
|
|
54
|
+
note.add_argument("--task", required=True)
|
|
55
|
+
note.add_argument("text", help="what was done, or what is next")
|
|
56
|
+
repair = commands.add_parser("repair", help="convert a verified legacy append conflict to receipt files")
|
|
57
|
+
repair.add_argument("--task", required=True)
|
|
58
|
+
commands.add_parser("ready", help="list open work: free, held, blocked or awaiting delivery")
|
|
59
|
+
check = commands.add_parser(
|
|
60
|
+
"check", help="refuse DONE/CLOSED claims the evidence does not support")
|
|
61
|
+
check.add_argument("task", nargs="?",
|
|
62
|
+
help="explain one task, by id (TASK-1) or path (tasks/TASK-1.md)")
|
|
63
|
+
check.add_argument("--staged", action="store_true", help="check the staged files (pre-commit)")
|
|
64
|
+
check.add_argument("--allow", metavar="TASKS", default="",
|
|
65
|
+
help="with --base: accept task definition or test file changes, or complete removal"
|
|
66
|
+
" (comma-separated ids, for a reviewer to pass)")
|
|
67
|
+
check.add_argument("--run-tests", action="store_true",
|
|
68
|
+
help="with --base: run the declared test of every task this change claims DONE or CLOSED")
|
|
69
|
+
check.add_argument("--base", metavar="REF",
|
|
70
|
+
help="also refuse if receipts committed on REF were removed or changed"
|
|
71
|
+
" (in CI: the pull request's base branch)")
|
|
72
|
+
return result
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def task_argument(value):
|
|
76
|
+
path = Path(value)
|
|
77
|
+
if path.suffix == ".md":
|
|
78
|
+
if path.parent.as_posix() not in {"tasks", "./tasks"}:
|
|
79
|
+
raise s.Refused("task files live in tasks/ at the repository root")
|
|
80
|
+
value = path.stem
|
|
81
|
+
return s.task_id(value)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def invalid_reason(root, item):
|
|
85
|
+
if item["kind"] != "test":
|
|
86
|
+
return f"the output did not include the full commit id {item['commit']}"
|
|
87
|
+
if s.head(root) != item["commit"]:
|
|
88
|
+
return "HEAD moved while the command ran"
|
|
89
|
+
paths = s.dirty_paths(root)
|
|
90
|
+
if paths:
|
|
91
|
+
return "files changed while the command ran; " + s.describe_dirty(paths)
|
|
92
|
+
return "the code changed while the command ran"
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def main(argv=None):
|
|
96
|
+
args = list(sys.argv[1:] if argv is None else argv)
|
|
97
|
+
command = []
|
|
98
|
+
if "--" in args:
|
|
99
|
+
position = args.index("--")
|
|
100
|
+
args, command = args[:position], args[position + 1:]
|
|
101
|
+
options = parser().parse_args(args)
|
|
102
|
+
root = Path.cwd()
|
|
103
|
+
try:
|
|
104
|
+
s.repository(root)
|
|
105
|
+
if command and options.action != "renew" and (options.action != "receipt"
|
|
106
|
+
or options.kind not in {"test", "deployed", "live"}):
|
|
107
|
+
raise s.Refused("this command does not accept a command after --")
|
|
108
|
+
if options.action == "new":
|
|
109
|
+
shared = s.has_origin(root) and not options.local
|
|
110
|
+
tid = s.new(root, options.title, options.owner, options.ships, options.prefix,
|
|
111
|
+
options.template, options.test, options.local)
|
|
112
|
+
where = ("reserved on origin" if shared
|
|
113
|
+
else "local id: --local, not reserved on origin" if options.local
|
|
114
|
+
else "local id: no origin remote, so other clones could pick the same id")
|
|
115
|
+
print(f"{tid} opened: tasks/{tid}.md ({where})")
|
|
116
|
+
elif options.action == "receipt":
|
|
117
|
+
if options.kind == "test" and not command:
|
|
118
|
+
command = gate.declared_test(s.record(root, options.task)) or [] # the task's own test
|
|
119
|
+
item = s.receipt(root, options.task, options.kind, command, options.target, options.ref)
|
|
120
|
+
detail = f" exit {item['exit_code']}" if "exit_code" in item else ""
|
|
121
|
+
print(f"{options.task} {options.kind} {item['commit'][:7]}{detail} - recorded")
|
|
122
|
+
if command:
|
|
123
|
+
print("command: " + s.join_command(command))
|
|
124
|
+
record = s.record(root, options.task)
|
|
125
|
+
reason = (invalid_reason(root, item) if item.get("exit_code") == 0 and not item["valid"]
|
|
126
|
+
else gate.uncounted(root, record, s.entries(root, options.task)))
|
|
127
|
+
if reason:
|
|
128
|
+
print("recorded, but does not count: " + reason)
|
|
129
|
+
_, done, delivery = gate.verdict(root, record)
|
|
130
|
+
print(f"{options.task} still owes: {gate.owes(record, done, delivery)}")
|
|
131
|
+
failed = item.get("exit_code", 0) != 0 or not item.get("valid", True)
|
|
132
|
+
return 1 if failed or reason else 0
|
|
133
|
+
elif options.action == "show":
|
|
134
|
+
print("\n".join(gate.record_lines(root, s.task_id(options.task))))
|
|
135
|
+
elif options.action == "note":
|
|
136
|
+
print(f"{options.task}: {s.add_note(root, options.task, options.text)}")
|
|
137
|
+
elif options.action == "repair":
|
|
138
|
+
print(s.repair(root, options.task))
|
|
139
|
+
elif options.action == "renew":
|
|
140
|
+
record = s.record(root, options.task)
|
|
141
|
+
command = command or gate.declared_test(record)
|
|
142
|
+
if not command:
|
|
143
|
+
raise s.Refused(f"{options.task} declares no test; add test: to tasks/{options.task}.md,"
|
|
144
|
+
" or put the test command after --")
|
|
145
|
+
failed = False
|
|
146
|
+
# Merges are computed from Git history; renew never records one that might not count.
|
|
147
|
+
for kind in ("implemented", "test"):
|
|
148
|
+
item = s.receipt(root, options.task, kind, command if kind == "test" else ())
|
|
149
|
+
detail = f" exit {item['exit_code']}" if "exit_code" in item else ""
|
|
150
|
+
print(f"{options.task} {kind} {item['commit'][:7]}{detail} - recorded")
|
|
151
|
+
reason = gate.uncounted(root, s.record(root, options.task), s.entries(root, options.task))
|
|
152
|
+
if item.get("exit_code", 0) != 0 or not item.get("valid", True) or reason:
|
|
153
|
+
print("recorded, but does not count: " + (reason or "the test did not pass"))
|
|
154
|
+
failed = True
|
|
155
|
+
break
|
|
156
|
+
record = s.record(root, options.task)
|
|
157
|
+
_, done, delivery = gate.verdict(root, record)
|
|
158
|
+
print(f"{options.task} still owes: {gate.owes(record, done, delivery)}")
|
|
159
|
+
return int(failed)
|
|
160
|
+
elif options.action == "claim":
|
|
161
|
+
held = s.claim(root, options.task)
|
|
162
|
+
print(f"{options.task} claimed: you hold it now, as {held['who']} (since {held['at']})")
|
|
163
|
+
elif options.action == "release":
|
|
164
|
+
forced = s.release(root, options.task, options.force)
|
|
165
|
+
print(f"{options.task} released" + (" (forced: its holder's clone did not release it)" if forced else ""))
|
|
166
|
+
elif options.action == "claims":
|
|
167
|
+
held = s.active_claims(root)
|
|
168
|
+
lines = [f"{tid} held by {c['who']} since {c['at']}"
|
|
169
|
+
for tid, c in sorted(held.items()) if not c["released"]]
|
|
170
|
+
print("\n".join(lines) or "no active claims")
|
|
171
|
+
elif options.action == "ready":
|
|
172
|
+
print("\n".join(gate.ready(root)) or "no open work")
|
|
173
|
+
elif options.task:
|
|
174
|
+
if options.staged or options.base:
|
|
175
|
+
raise s.Refused("--staged and --base check every task; leave out the task")
|
|
176
|
+
lines, refused = gate.explain(root, task_argument(options.task))
|
|
177
|
+
print("\n".join(lines))
|
|
178
|
+
record = s.record(root, task_argument(options.task))
|
|
179
|
+
print(gate.check_summary(dict(tasks=1, claimed=int(record["status"] in gate.FINISHED))))
|
|
180
|
+
return int(refused)
|
|
181
|
+
else:
|
|
182
|
+
if (options.allow or options.run_tests) and not options.base:
|
|
183
|
+
raise s.Refused("--allow and --run-tests go with --base")
|
|
184
|
+
notes = []
|
|
185
|
+
counts = {}
|
|
186
|
+
allow = {item.strip() for item in options.allow.split(",") if item.strip()}
|
|
187
|
+
problems = gate.check(root, options.staged, options.base, notes, allow, options.run_tests, counts)
|
|
188
|
+
print("\n".join(problems) if problems else "check: OK")
|
|
189
|
+
if notes:
|
|
190
|
+
print("\n".join(f"Note: {note}" for note in notes))
|
|
191
|
+
if options.run_tests and counts["tests"] == 0:
|
|
192
|
+
print("no declared test ran in this check")
|
|
193
|
+
print(gate.check_summary(counts, options.run_tests))
|
|
194
|
+
return int(bool(problems))
|
|
195
|
+
return 0
|
|
196
|
+
except (s.Refused, OSError, ValueError, TypeError, KeyError, subprocess.SubprocessError) as error:
|
|
197
|
+
print(f"workorder: {error}", file=sys.stderr)
|
|
198
|
+
return 1
|