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/store.py ADDED
@@ -0,0 +1,1164 @@
1
+ """Local files and immutable remote reservations. No hosting-service API needed."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import datetime as dt
6
+ from contextlib import contextmanager
7
+ from contextvars import ContextVar
8
+ from functools import wraps
9
+ import hashlib
10
+ import hmac
11
+ import heapq
12
+ import json
13
+ import os
14
+ from pathlib import Path
15
+ import re
16
+ import shlex
17
+ import subprocess
18
+ import uuid
19
+
20
+
21
+ class Refused(ValueError):
22
+ pass
23
+
24
+
25
+ _READS = ContextVar("workorder_reads", default=None)
26
+
27
+
28
+ @contextmanager
29
+ def read_session():
30
+ """Share reads within one command, never across commands in an embedding process."""
31
+ if _READS.get() is not None:
32
+ yield
33
+ return
34
+ token = _READS.set({})
35
+ try:
36
+ yield
37
+ finally:
38
+ _READS.reset(token)
39
+
40
+
41
+ def invalidate_reads():
42
+ cache = _READS.get()
43
+ if cache is not None:
44
+ cache.clear()
45
+
46
+
47
+ def cached_read(function):
48
+ @wraps(function)
49
+ def read(*args, **kwargs):
50
+ cache = _READS.get()
51
+ if cache is None:
52
+ return function(*args, **kwargs)
53
+ key = (function, args, tuple(sorted(kwargs.items())))
54
+ if key not in cache:
55
+ cache[key] = function(*args, **kwargs)
56
+ return cache[key]
57
+ return read
58
+
59
+
60
+ ID = re.compile(r"[A-Z][A-Z0-9]*-[1-9][0-9]*\Z")
61
+ KINDS = {"implemented", "test", "merged", "deployed", "live"}
62
+ NAMESPACE = "refs/tags/workorder/"
63
+
64
+
65
+ def task_id(value):
66
+ if not isinstance(value, str) or not ID.fullmatch(value):
67
+ raise Refused("expected an id such as TASK-1")
68
+ return value
69
+
70
+
71
+ def packed(value):
72
+ return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
73
+
74
+
75
+ def digest(data):
76
+ return hashlib.sha256(data).hexdigest()
77
+
78
+
79
+ def now():
80
+ return dt.datetime.now(dt.timezone.utc).isoformat()
81
+
82
+
83
+ def git(root, *args, data=None, required=True):
84
+ run = (_git_read if args[0] in {"rev-parse", "symbolic-ref", "show", "log", "ls-tree",
85
+ "ls-files", "diff", "merge-base", "rev-list", "patch-id",
86
+ "check-ref-format"} else _git_run)
87
+ return run(root, *args, data=data, required=required)
88
+
89
+
90
+ @cached_read
91
+ def _git_read(root, *args, data=None, required=True):
92
+ return _git_run(root, *args, data=data, required=required)
93
+
94
+
95
+ def _git_run(root, *args, data=None, required=True):
96
+ result = subprocess.run(
97
+ ["git", *args], cwd=root, input=data, capture_output=True,
98
+ encoding="utf-8", errors="surrogateescape", timeout=30,
99
+ )
100
+ if required and result.returncode:
101
+ raise Refused(result.stderr.strip() or "Git command failed")
102
+ return result
103
+
104
+
105
+ def who(root):
106
+ # Only the Git user name: receipts and claims are pushed, and a hostname says more than needed.
107
+ name = git(root, "config", "user.name", required=False).stdout.strip()
108
+ if not name:
109
+ raise Refused("set git user.name first")
110
+ return name
111
+
112
+
113
+ @cached_read
114
+ def head(root):
115
+ return git(root, "rev-parse", "--verify", "HEAD^{commit}").stdout.strip()
116
+
117
+
118
+ def repository(root):
119
+ top = Path(git(root, "rev-parse", "--show-toplevel").stdout.strip()).resolve()
120
+ if top != root.resolve():
121
+ raise Refused("run workorder at the Git repository root")
122
+
123
+
124
+ def local_path(root, relative):
125
+ if not isinstance(relative, str) or not relative:
126
+ raise Refused("expected a relative file path")
127
+ result = root / relative
128
+ if Path(relative).is_absolute() or not result.resolve().is_relative_to(root.resolve()):
129
+ raise Refused("file path must stay inside this repository")
130
+ return result
131
+
132
+
133
+ def read_bytes(root, relative, staged=False):
134
+ local_path(root, relative)
135
+ if staged:
136
+ result = subprocess.run(["git", "show", f":{relative}"], cwd=root,
137
+ capture_output=True, timeout=30)
138
+ if result.returncode:
139
+ raise Refused(f"missing staged file: {relative}")
140
+ return result.stdout
141
+ return local_path(root, relative).read_bytes()
142
+
143
+
144
+ def read_text(root, relative, staged=False):
145
+ # Git on Windows may check text files out with CRLF; the content is the same.
146
+ if staged and (receipt_task(relative) or relative.startswith("tasks/")):
147
+ text = metadata_texts(root, None, None, True).get(relative)
148
+ if text is None:
149
+ raise Refused(f"missing staged file: {relative}")
150
+ return text
151
+ return read_bytes(root, relative, staged).decode("utf-8").removeprefix("\ufeff").replace("\r\n", "\n")
152
+
153
+
154
+ @cached_read
155
+ def files(root, directory, staged=False):
156
+ if staged:
157
+ if directory == "tasks":
158
+ return sorted(p for p in git(root, "ls-files", "-z", "--", "tasks").stdout.split("\0") if p)
159
+ paths = git(root, "ls-files", "-z", "--", directory).stdout.split("\0")
160
+ return sorted(p for p in paths if p)
161
+ base = local_path(root, directory)
162
+ return sorted(p.relative_to(root).as_posix() for p in base.rglob("*") if p.is_file())
163
+
164
+
165
+ # CANCELLED ends a task that will not be done: it needs no evidence and never counts as finished.
166
+ STATUSES = ("IN_PROGRESS", "BLOCKED", "DONE", "CLOSED", "CANCELLED")
167
+ CORE_FIELDS = ("id", "title", "owner", "status", "ships", "waits_on", "contract")
168
+ # Optional fields. Dependencies and the test add requirements; merge_ref selects delivery's target,
169
+ # and test_paths selects files guarded by a base check. Planning fields never stand in for evidence.
170
+ EXTENDED_FIELDS = ("business_owner", "priority", "created_at", "mission", "depends_on", "blocks",
171
+ "next", "summary", "test", "test_paths", "merge_ref")
172
+ EXTENDED_ORDER = ("id", "title", "owner", "business_owner", "priority", "created_at", "mission",
173
+ "depends_on", "blocks", "next", "summary", "status", "ships", "waits_on", "test",
174
+ "contract")
175
+ TASK_REF = r"[A-Z][A-Z0-9]*-[1-9][0-9]*"
176
+ FRONT_MATTER_HELP = ("front matter takes `key: value` lines: plain single-line text, a JSON string, or a"
177
+ ' list such as ["TASK-1"]; mission, next and summary may use > or | blocks, and'
178
+ " depends_on, blocks, waits_on and test_paths may use indented - item lines")
179
+ # The small YAML subset Workorder reads. Anything else is refused rather than guessed.
180
+ BLOCK_TEXT_FIELDS = ("mission", "next", "summary")
181
+ LIST_FIELDS = ("depends_on", "blocks", "waits_on", "test_paths")
182
+ BLOCK_INDICATORS = (">", "|", ">-", "|-", ">+", "|+")
183
+ PLAIN_ITEM = r"[A-Za-z0-9_./@:-]+"
184
+
185
+
186
+ def front_value(tid, key, raw):
187
+ """Parse one value: plain text, a JSON string or list, or a simple [a, b] list."""
188
+ raw = raw.strip()
189
+ if len(raw) >= 2 and raw[0] == raw[-1] == "'":
190
+ return raw[1:-1].replace("''", "'") # a single-quoted YAML scalar
191
+ if not raw.startswith(('"', '[')):
192
+ return raw
193
+ try:
194
+ return json.loads(raw)
195
+ except ValueError:
196
+ pass
197
+ inner = raw[1:-1].strip() if raw.startswith("[") and raw.endswith("]") else None
198
+ raw_items = [item.strip() for item in inner.split(",")] if inner else []
199
+ quoted = [len(item) >= 2 and item[0] == item[-1] and item[0] in "\"'" for item in raw_items]
200
+ items = [item[1:-1] if q else item for item, q in zip(raw_items, quoted)]
201
+ if inner is None or any(not (item if q else re.fullmatch(PLAIN_ITEM, item))
202
+ for item, q in zip(items, quoted)):
203
+ raise Refused(f"{tid}: cannot read {key}; {FRONT_MATTER_HELP}")
204
+ return items
205
+
206
+
207
+ def block_text(tid, key, indicator, block):
208
+ """A YAML > (folded) or | (literal) block, with optional - (strip) or + (keep) chomping."""
209
+ filled = [line for line in block if line.strip()]
210
+ if not filled:
211
+ return ""
212
+ indent = len(filled[0]) - len(filled[0].lstrip(" "))
213
+ if any(len(line) - len(line.lstrip(" ")) < indent for line in filled):
214
+ raise Refused(f"{tid}: {key}: block lines must keep the indentation of the first line")
215
+ content = [line[indent:] if line.strip() else "" for line in block]
216
+ trailing = len(content) - len("\n".join(content).rstrip("\n").split("\n"))
217
+ content = content[:len(content) - trailing]
218
+ if indicator[0] == "|":
219
+ text = "\n".join(content)
220
+ else:
221
+ # Folding joins two ordinary lines with a space; empty lines become line breaks. Lines
222
+ # indented further than the block keep their own line breaks, as in YAML.
223
+ text, previous, empty = "", None, 0
224
+ for line in content:
225
+ if not line:
226
+ empty += 1
227
+ continue
228
+ if previous is None:
229
+ text += "\n" * empty
230
+ elif previous.startswith(" ") or line.startswith(" "):
231
+ text += "\n" * (empty + 1)
232
+ else:
233
+ text += "\n" * empty if empty else " "
234
+ text += line
235
+ previous, empty = line, 0
236
+ if indicator.endswith("-"):
237
+ return text
238
+ if indicator.endswith("+"):
239
+ return text + "\n" * (1 + trailing)
240
+ return text + "\n"
241
+
242
+
243
+ def block_list(tid, key, block):
244
+ """Indented "- item" lines: plain ids or JSON strings, nothing nested."""
245
+ items = []
246
+ for line in block:
247
+ if not line.strip():
248
+ continue
249
+ match = re.fullmatch(r" *- +(.+?)\s*", line)
250
+ item = match.group(1) if match else None
251
+ if item and item.startswith('"'):
252
+ try:
253
+ item = json.loads(item)
254
+ except ValueError:
255
+ item = None
256
+ if not isinstance(item, str) or not item or (key != "test_paths" and not re.fullmatch(PLAIN_ITEM, item)):
257
+ raise Refused(f"{tid}: {key}: list lines look like \" - TASK-1\"")
258
+ items.append(item)
259
+ return items
260
+
261
+
262
+ def front_matter(tid, lines):
263
+ """Fields from front matter lines: key: value, plus the block forms above. Line 1 is ---."""
264
+ fields, index = {}, 0
265
+ while index < len(lines):
266
+ line, number = lines[index], index + 2
267
+ end = index + 1
268
+ # A list field may also carry its "- item" lines at the left margin, as YAML allows.
269
+ list_head = line.partition(":")[0] in LIST_FIELDS and not line.partition(":")[2].strip()
270
+ while end < len(lines) and (not lines[end].strip() or lines[end].startswith(" ")
271
+ or (list_head and lines[end].startswith("- "))):
272
+ end += 1
273
+ block = lines[index + 1:end]
274
+ index = end
275
+ if not line.strip():
276
+ continue
277
+ if line.startswith("#") and not any(item.strip() for item in block):
278
+ continue # a YAML comment line
279
+ key, separator, raw = line.partition(":")
280
+ if not separator or not key or key != key.strip() or line.startswith("#"):
281
+ raise Refused(f"{tid}: line {number}: {FRONT_MATTER_HELP}")
282
+ if key in fields:
283
+ raise Refused(f"{tid}: duplicate field {key}")
284
+ raw = raw.strip()
285
+ nested = any(item.strip() for item in block)
286
+ if raw in BLOCK_INDICATORS:
287
+ if key not in BLOCK_TEXT_FIELDS:
288
+ raise Refused(f"{tid}: {key} cannot be a > or | block; only {', '.join(BLOCK_TEXT_FIELDS)} can")
289
+ fields[key] = block_text(tid, key, raw, block)
290
+ elif not raw and key in LIST_FIELDS:
291
+ fields[key] = block_list(tid, key, block)
292
+ elif nested:
293
+ raise Refused(f"{tid}: line {number + 1}: indented lines belong only under a > or | block or a"
294
+ f" list field; {FRONT_MATTER_HELP}")
295
+ else:
296
+ fields[key] = front_value(tid, key, raw)
297
+ return fields
298
+
299
+
300
+ def task_refs(tid, key, value):
301
+ """A list of task ids, written as TASK-1 or task:TASK-1, returned as plain ids."""
302
+ if not isinstance(value, list) or any(not isinstance(v, str) for v in value):
303
+ raise Refused(f"{tid}: {key} must be a list of task ids")
304
+ ids = [v[5:] if v.startswith("task:") else v for v in value]
305
+ if any(not re.fullmatch(TASK_REF, i) for i in ids):
306
+ raise Refused(f"{tid}: {key} lists task ids such as TASK-2; people waits go in waits_on")
307
+ if tid in ids:
308
+ raise Refused(f"{tid}: {key} cannot name the task itself")
309
+ return list(dict.fromkeys(ids))
310
+
311
+
312
+ @cached_read
313
+ def record(root, tid, staged=False):
314
+ task_id(tid)
315
+ if not staged and not local_path(root, f"tasks/{tid}.md").is_file():
316
+ raise Refused(f"no task record tasks/{tid}.md in this checkout; pull the commit that added it")
317
+ text = read_text(root, f"tasks/{tid}.md", staged)
318
+ lines = text.splitlines()
319
+ if not lines or lines[0] != "---" or "---" not in lines[1:]:
320
+ raise Refused(f"{tid}: expected fenced front matter")
321
+ fields = front_matter(tid, lines[1:lines.index("---", 1)])
322
+ missing = [k for k in CORE_FIELDS if k not in fields]
323
+ unknown = sorted(k for k in set(fields) - set(CORE_FIELDS) - set(EXTENDED_FIELDS) if not k.startswith("x-"))
324
+ if missing or unknown:
325
+ raise Refused(f"{tid}: " + "; ".join(
326
+ ([f"missing {', '.join(missing)}"] if missing else [])
327
+ + ([f"unknown {', '.join(unknown)} (known optional fields: {', '.join(EXTENDED_FIELDS)};"
328
+ " your own fields start with x-, such as x-issue)"]
329
+ if unknown else [])))
330
+ if fields["id"] != tid:
331
+ raise Refused(f"{tid}: id must match the file name")
332
+ if any(not isinstance(fields[k], str) or not fields[k].strip()
333
+ for k in set(CORE_FIELDS) - {"waits_on"}):
334
+ raise Refused(f"{tid}: text fields must be nonempty strings")
335
+ if fields["status"] not in STATUSES:
336
+ raise Refused(f"{tid}: unknown status {fields['status']!r}; use {', '.join(STATUSES)}")
337
+ if fields["ships"] not in {"none", "repo", "live"}:
338
+ raise Refused(f"{tid}: ships must be none, repo or live")
339
+ if "merge_ref" in fields:
340
+ ref = fields["merge_ref"]
341
+ if (not isinstance(ref, str) or not ref.startswith(("refs/heads/", "refs/remotes/"))
342
+ or (ref.startswith("refs/remotes/") and len(ref.split("/")) < 4)
343
+ or git(root, "check-ref-format", ref, required=False).returncode):
344
+ raise Refused(f"{tid}: merge_ref must be a full branch ref")
345
+ waits = fields["waits_on"]
346
+ if not isinstance(waits, list) or any(
347
+ not isinstance(w, str) or not re.fullmatch(rf"(?:task:{TASK_REF}|person:[^:\s][^:]*)", w)
348
+ or w != w.strip()
349
+ for w in waits
350
+ ):
351
+ raise Refused(f"{tid}: waits_on needs task:<id> or person:<name> items")
352
+ for key in ("business_owner", "priority", "created_at", "mission", "next", "summary", "test"):
353
+ if key in fields and not isinstance(fields[key], str):
354
+ raise Refused(f"{tid}: {key} must be text")
355
+ if fields.get("test", "").strip():
356
+ split_command(fields["test"], f"{tid}: test")
357
+ if "test_paths" in fields:
358
+ paths = fields["test_paths"]
359
+ if not isinstance(paths, list) or any(not isinstance(p, str) or not p.strip() for p in paths):
360
+ raise Refused(f"{tid}: test_paths must be a list of repository paths")
361
+ for path in paths:
362
+ local_path(root, path)
363
+ if fields.get("created_at"):
364
+ try:
365
+ dt.datetime.fromisoformat(fields["created_at"].replace("Z", "+00:00"))
366
+ except ValueError:
367
+ raise Refused(f"{tid}: created_at must be an ISO date such as 2026-11-14") from None
368
+ for key in ("depends_on", "blocks"):
369
+ if key in fields:
370
+ fields[key] = task_refs(tid, key, fields[key])
371
+ needs = {w[5:] for w in waits if w.startswith("task:")} | set(fields.get("depends_on", []))
372
+ both = sorted(needs & set(fields.get("blocks", [])))
373
+ if both:
374
+ raise Refused(f"{tid}: cannot both wait for and block {', '.join(both)}")
375
+ return fields
376
+
377
+
378
+ def dependencies(record):
379
+ """One dependency list: waits_on items plus depends_on ids as task: items, without repeats."""
380
+ return list(dict.fromkeys([*record["waits_on"], *(f"task:{i}" for i in record.get("depends_on", []))]))
381
+
382
+
383
+ def has_origin(root):
384
+ return git(root, "remote", "get-url", "origin", required=False).returncode == 0
385
+
386
+
387
+ def remote_refs(root, upstream=False):
388
+ if not has_origin(root):
389
+ raise Refused("this needs an origin remote: only a shared remote can refuse a second"
390
+ " holder, so claims are never kept locally")
391
+ branches = ["refs/heads/main", "refs/heads/master"] if upstream else []
392
+ output = git(root, "ls-remote", "--refs", "origin", NAMESPACE + "*", *branches).stdout
393
+ return {ref: oid for oid, ref in (line.split() for line in output.splitlines())}
394
+
395
+
396
+ def reserve(root, ref, value):
397
+ value = {**value, "nonce": uuid.uuid4().hex}
398
+ oid = git(root, "hash-object", "-w", "--stdin", data=packed(value)).stdout.strip()
399
+ # Tags reject replacement even if one object descends from another. No force option.
400
+ result = git(root, "push", "origin", f"{oid}:{ref}", required=False)
401
+ if result.returncode:
402
+ if ref in remote_refs(root):
403
+ return None
404
+ raise Refused(result.stderr.strip() or "remote reservation failed")
405
+ return oid
406
+
407
+
408
+ def remote_value(root, ref, oid):
409
+ git(root, "fetch", "--no-tags", "origin", ref)
410
+ return json.loads(git(root, "cat-file", "blob", oid).stdout)
411
+
412
+
413
+ EXTENDED_BODY = """
414
+ ## Context
415
+
416
+ <!-- Why this task exists and what it touches. -->
417
+
418
+ ## Scope
419
+
420
+ <!-- What is in scope, and what is explicitly out. -->
421
+
422
+ ## Lanes
423
+
424
+ <!-- Parallel streams of work and who or what owns each. -->
425
+
426
+ ## Acceptance
427
+
428
+ <!-- The original ask, criterion by criterion. Evidence Workorder should check belongs in a contract. -->
429
+
430
+ ## Progress
431
+
432
+ <!-- Dated notes: workorder note adds one, workorder show prints them. Status comes from receipts, not from here. -->
433
+ """
434
+
435
+
436
+ def task_text(tid, data, template):
437
+ if template == "simple":
438
+ return ("---\n" + "".join(f"{k}: {packed(v)}\n" for k, v in data.items())
439
+ + f"---\n\n# {tid}\n\nWrite the original ask here.\n")
440
+ today = dt.datetime.now(dt.timezone.utc).date().isoformat()
441
+ extended = {**dict(business_owner="", priority="", created_at=today, mission="", depends_on=[],
442
+ blocks=[], next="", summary="", test=""), **data}
443
+ return ("---\n" + "".join(f"{k}: {packed(extended[k])}\n" for k in EXTENDED_ORDER)
444
+ + f"---\n\n# {tid}\n" + EXTENDED_BODY)
445
+
446
+
447
+ def new(root, title, owner, ships="none", prefix="TASK", template="extended", test="", local_only=False):
448
+ repository(root)
449
+ if template not in {"simple", "extended"}:
450
+ raise Refused("template must be simple or extended")
451
+ if not re.fullmatch(r"[A-Z][A-Z0-9]*", prefix) or not title.strip() or not owner.strip():
452
+ raise Refused("use an uppercase prefix, nonempty title and owner")
453
+ if test.strip():
454
+ split_command(test, "--test")
455
+ directory = local_path(root, "tasks")
456
+ directory.mkdir(exist_ok=True)
457
+ # Without an origin remote, ids are numbered locally and not coordinated with other clones.
458
+ # With one, it must answer: never guess offline.
459
+ local = local_only or not has_origin(root)
460
+ for _ in range(30):
461
+ try:
462
+ refs = {} if local else remote_refs(root)
463
+ except Refused as error:
464
+ raise Refused(f"origin could not be reached ({error}); workorder new --local numbers the task"
465
+ " from the task files without it") from None
466
+ stem = NAMESPACE + f"ids/{prefix}-"
467
+ numbers = [int(ref[len(stem):]) for ref in refs
468
+ if ref.startswith(stem) and ref[len(stem):].isdigit()]
469
+ numbers += [int(p.stem.split("-")[-1]) for p in directory.glob(f"{prefix}-*.md")
470
+ if ID.fullmatch(p.stem)]
471
+ tid = f"{prefix}-{max(numbers, default=0) + 1}"
472
+ data = dict(id=tid, title=title, owner=owner, status="IN_PROGRESS", ships=ships,
473
+ waits_on=[], contract="none", **({"test": test} if test else {}))
474
+ if local or reserve(root, NAMESPACE + f"ids/{tid}", {**data, "at": now(), "who": who(root)}):
475
+ path = directory / f"{tid}.md"
476
+ with path.open("x", encoding="utf-8", newline="\n") as stream:
477
+ stream.write(task_text(tid, data, template))
478
+ return tid
479
+ raise Refused("too much allocation contention; retry")
480
+
481
+
482
+ def active_claims(root, upstream=None):
483
+ refs = remote_refs(root, upstream=upstream is not None)
484
+ latest = {}
485
+ stem = NAMESPACE + "claims/"
486
+ for ref, oid in refs.items():
487
+ if ref.startswith(stem):
488
+ parts = ref[len(stem):].split("/")
489
+ if len(parts) != 2 or not ID.fullmatch(parts[0]) or not parts[1].isdigit():
490
+ continue # not a claim this tool wrote; ignore it rather than fail for everyone
491
+ tid, generation = parts
492
+ if int(generation) > latest.get(tid, (0, "", ""))[0]:
493
+ latest[tid] = (int(generation), ref, oid)
494
+ result = {}
495
+ # One fetch for every claim that matters, instead of one network round trip per task.
496
+ wanted = [ref for _, ref, oid in latest.values()
497
+ if git(root, "cat-file", "-e", oid, required=False).returncode]
498
+ branch = next((ref for ref in ("refs/heads/main", "refs/heads/master") if ref in refs), None)
499
+ if upstream is not None and branch:
500
+ # Refresh even when every claim tag is cached. Do not move remote-tracking branches:
501
+ # ready/claim must not make the local task files appear to have been pulled.
502
+ wanted.insert(0, f"+{branch}:refs/workorder/upstream")
503
+ for start in range(0, len(wanted), 200):
504
+ git(root, "fetch", "--no-tags", "--refmap=", "origin", *wanted[start:start + 200],
505
+ required=upstream is not None)
506
+ if upstream is not None and branch:
507
+ invalidate_reads()
508
+ snapshot = git(root, "rev-parse", "refs/workorder/upstream^{commit}").stdout.strip()
509
+ for path, text in metadata_texts(root, snapshot).items():
510
+ if not path.startswith("tasks/") or not path.endswith(".md"):
511
+ continue
512
+ tid = path[6:-3]
513
+ if not ID.fullmatch(tid):
514
+ continue
515
+ lines = text.splitlines()
516
+ try:
517
+ fields = front_matter(tid, lines[1:lines.index("---", 1)])
518
+ except (Refused, ValueError):
519
+ continue
520
+ if fields.get("status") in {"DONE", "CLOSED", "CANCELLED"}:
521
+ upstream[tid] = {"status": fields["status"], "ref": "origin/" + branch[11:],
522
+ "commit": snapshot}
523
+ for tid, (generation, ref, oid) in latest.items():
524
+ released = NAMESPACE + f"releases/{tid}/{oid}" in refs
525
+ try:
526
+ value = json.loads(git(root, "cat-file", "blob", oid).stdout)
527
+ except (Refused, ValueError):
528
+ continue
529
+ if not isinstance(value, dict):
530
+ continue
531
+ result[tid] = {**value, "generation": generation, "oid": oid, "released": released}
532
+ return result
533
+
534
+
535
+ def claim_token_path(root, tid):
536
+ relative = git(root, "rev-parse", "--git-path", f"workorder-claims/{tid}").stdout.strip()
537
+ return root / relative
538
+
539
+
540
+ def token_hash(token):
541
+ return digest(token.encode("utf-8"))
542
+
543
+
544
+ def holds(held, token):
545
+ """True when this clone's private token matches the hash stored in the claim tag."""
546
+ expected = held.get("token_sha256")
547
+ return isinstance(expected, str) and hmac.compare_digest(expected, token_hash(token))
548
+
549
+
550
+ def claim(root, tid):
551
+ repository(root)
552
+ record(root, tid)
553
+ upstream = {}
554
+ held = active_claims(root, upstream).get(tid)
555
+ if tid in upstream:
556
+ finished = upstream[tid]
557
+ author = git(root, "log", "-1", "--format=%an", finished["commit"], "--", f"tasks/{tid}.md").stdout.strip()
558
+ raise Refused(f"{tid} is already {finished['status']} on {finished['ref']} (by {author}); pull to update")
559
+ token_path = claim_token_path(root, tid)
560
+ token = token_path.read_text(encoding="utf-8") if token_path.exists() else uuid.uuid4().hex
561
+ if held and not held["released"]:
562
+ if holds(held, token):
563
+ return held
564
+ raise Refused(f"{tid} is held by {held['who']} since {held['at']} - not claimed")
565
+ generation = held["generation"] + 1 if held else 1
566
+ # Only the hash is pushed; the token itself stays in this clone's .git directory.
567
+ value = {"task": tid, "who": who(root), "at": now(), "token_sha256": token_hash(token)}
568
+ # Save before pushing: a crash can leave a recoverable claim, never a lost key.
569
+ token_path.parent.mkdir(parents=True, exist_ok=True)
570
+ token_path.write_text(token, encoding="utf-8", newline="\n")
571
+ if not reserve(root, NAMESPACE + f"claims/{tid}/{generation}", value):
572
+ winner = active_claims(root).get(tid)
573
+ raise Refused(f"{tid} was claimed by {winner['who']} first - not claimed")
574
+ return value
575
+
576
+
577
+ def release(root, tid, force=False):
578
+ """Give up a claim. Only the holding clone can, unless force: for a claim whose clone or worktree is
579
+ gone. Anyone with push access could push the release tag by hand; force does it openly and says so."""
580
+ repository(root)
581
+ task_id(tid)
582
+ held = active_claims(root).get(tid)
583
+ path = claim_token_path(root, tid)
584
+ if not held or held["released"]:
585
+ raise Refused(f"{tid} has no active claim")
586
+ holder = path.exists() and holds(held, path.read_text(encoding="utf-8"))
587
+ if not holder and not force:
588
+ raise Refused(f"{tid}: only its holder can release it; if that clone or worktree is gone, run"
589
+ f" workorder release --task {tid} --force")
590
+ value = {"at": now(), "who": who(root), **({} if holder else {"forced": True, "holder": held["who"]})}
591
+ reserve(root, NAMESPACE + f"releases/{tid}/{held['oid']}", value)
592
+ return not holder
593
+
594
+
595
+ def task_body_sections(text):
596
+ """The Markdown body after the front matter, as (heading, lines) pairs in order."""
597
+ lines = text.splitlines()
598
+ end = lines.index("---", 1) if lines and lines[0] == "---" and "---" in lines[1:] else -1
599
+ sections, heading, current = [], None, []
600
+ for line in lines[end + 1:]:
601
+ if line.startswith("## "):
602
+ sections.append((heading, current))
603
+ heading, current = line[3:].strip(), []
604
+ else:
605
+ current.append(line)
606
+ sections.append((heading, current))
607
+ return sections
608
+
609
+
610
+ def add_note(root, tid, text):
611
+ """Add "- YYYY-MM-DD: text" at the end of the task's Progress section (creating it if needed).
612
+ This is the one change Workorder makes to a task file after new; every other byte is kept."""
613
+ record(root, tid)
614
+ text = " ".join(text.split())
615
+ if not text:
616
+ raise Refused("a note needs some text")
617
+ path = local_path(root, f"tasks/{tid}.md")
618
+ lines = read_text(root, f"tasks/{tid}.md").split("\n")
619
+ line = f"- {dt.datetime.now(dt.timezone.utc).date().isoformat()}: {text}"
620
+ starts = [i for i, value in enumerate(lines) if value.strip() == "## Progress"]
621
+ if starts:
622
+ end = next((i for i in range(starts[-1] + 1, len(lines)) if lines[i].startswith("## ")), len(lines))
623
+ while end > starts[-1] + 1 and not lines[end - 1].strip():
624
+ end -= 1
625
+ lines[end:end] = [line] if lines[end - 1].strip() and not lines[end - 1].startswith("## ") else ["", line]
626
+ else:
627
+ while lines and not lines[-1].strip():
628
+ lines.pop()
629
+ lines += ["", "## Progress", "", line]
630
+ path.write_text("\n".join(lines).rstrip("\n") + "\n", encoding="utf-8", newline="\n")
631
+ return line
632
+
633
+
634
+ def ledger_path(tid):
635
+ return f".workorder/receipts/{task_id(tid)}.jsonl"
636
+
637
+
638
+ RECEIPT_DIRS = (".workorder/receipts", ".notquite/receipts")
639
+
640
+
641
+ def receipt_task(path):
642
+ """The task owning either receipt layout; ignore notes beside the ledgers."""
643
+ parts = path.split("/")
644
+ if len(parts) not in (3, 4) or "/".join(parts[:2]) not in RECEIPT_DIRS:
645
+ return None
646
+ tid = parts[2].removesuffix(".jsonl") if len(parts) == 3 else parts[2]
647
+ if ID.fullmatch(tid) and path.endswith(".jsonl" if len(parts) == 3 else ".json"):
648
+ return tid
649
+ return None
650
+
651
+
652
+ @cached_read
653
+ def metadata_texts(root, rev=None, tid=None, staged=False):
654
+ """Read task and receipt blobs in two Git calls, preserving byte-sized batch framing.
655
+
656
+ HEAD and the index are shared across tasks. Historical reads select one task;
657
+ immutable blobs already read in this session need not be read again.
658
+ """
659
+ scopes = ([f"tasks/{tid}.md", *[f"{d}/{tid}.jsonl" for d in RECEIPT_DIRS],
660
+ *[f"{d}/{tid}" for d in RECEIPT_DIRS]] if tid else ["tasks", *RECEIPT_DIRS])
661
+ args = ["ls-files", "--stage", "-z"] if staged else ["ls-tree", "-r", "-z", rev or "HEAD"]
662
+ listing = git(root, *args, "--", *scopes, required=False)
663
+ objects = {}
664
+ for entry in listing.stdout.split("\0"):
665
+ if not entry:
666
+ continue
667
+ info, path = entry.split("\t", 1)
668
+ mode, kind, oid = info.split()
669
+ if staged:
670
+ oid, stage = kind, oid
671
+ if stage != "0":
672
+ continue # unresolved paths are reported as missing staged files
673
+ elif kind != "blob":
674
+ continue
675
+ if receipt_task(path) or (path.startswith("tasks/") and path.endswith(".md")):
676
+ objects[path] = oid
677
+ blobs = read_blobs(root, objects.values())
678
+ return {path: blobs[oid] for path, oid in objects.items()}
679
+
680
+
681
+ def read_blobs(root, oids):
682
+ cache = _READS.get()
683
+ blobs = cache.setdefault(("blobs", root), {}) if cache is not None else {}
684
+ wanted = sorted(set(oids) - blobs.keys())
685
+ if wanted:
686
+ result = subprocess.run(["git", "cat-file", "--batch"], cwd=root,
687
+ input=("\n".join(wanted) + "\n").encode(),
688
+ capture_output=True, timeout=30, check=True)
689
+ offset = 0
690
+ for oid in wanted:
691
+ end = result.stdout.index(b"\n", offset)
692
+ header = result.stdout[offset:end].split()
693
+ if len(header) != 3 or header[1] != b"blob":
694
+ raise Refused("Git could not read a task or receipt blob")
695
+ size = int(header[2])
696
+ raw = result.stdout[end + 1:end + 1 + size]
697
+ blobs[oid] = raw.decode("utf-8").removeprefix("\ufeff").replace("\r\n", "\n")
698
+ offset = end + 2 + size
699
+ return blobs
700
+
701
+
702
+ @cached_read
703
+ def receipt_paths(root, staged=False, rev=None, tid=None):
704
+ """Receipt files of every task, or of one task (its legacy ledger and its folder) when tid is given."""
705
+ scopes = ([f"{d}/{tid}.jsonl" for d in RECEIPT_DIRS] + [f"{d}/{tid}" for d in RECEIPT_DIRS]
706
+ if tid else list(RECEIPT_DIRS))
707
+ if rev:
708
+ return sorted(p for p in metadata_texts(root, rev, tid if rev != "HEAD" else None, False)
709
+ if receipt_task(p) and (tid is None or receipt_task(p) == tid))
710
+ if staged:
711
+ return sorted(p for p in metadata_texts(root, None, None, True)
712
+ if receipt_task(p) and (tid is None or receipt_task(p) == tid))
713
+ found = []
714
+ for scope in scopes:
715
+ path = local_path(root, scope)
716
+ if path.is_file():
717
+ found.append(scope)
718
+ elif path.is_dir():
719
+ found += files(root, scope)
720
+ return sorted(found)
721
+
722
+
723
+ @cached_read
724
+ def receipt_texts(root, tid, staged=False, rev=None):
725
+ if rev or staged:
726
+ return {p: text for p, text in metadata_texts(
727
+ root, rev, tid if rev and rev != "HEAD" else None, staged).items() if receipt_task(p) == tid}
728
+ return {p: read_text(root, p)
729
+ for p in receipt_paths(root, staged, rev, tid) if receipt_task(p) == tid}
730
+
731
+
732
+ def verify_receipt(root, tid, value):
733
+ if not isinstance(value, dict):
734
+ raise Refused(f"{tid}: receipt must be an object")
735
+ item = dict(value)
736
+ checksum = item.pop("hash", None)
737
+ if checksum != digest(packed(item).encode()):
738
+ raise Refused(f"{tid}: receipt content does not match its hash")
739
+ if (item.get("task") != tid or item.get("kind") not in KINDS
740
+ or not isinstance(item.get("who"), str) or not item["who"].strip()
741
+ or not isinstance(item.get("at"), str)
742
+ or not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", str(item.get("commit", "")))
743
+ or not re.fullmatch(r"[0-9a-f]{64}", str(item.get("code", "")))):
744
+ raise Refused(f"{tid}: invalid receipt fields")
745
+ dt.datetime.fromisoformat(item["at"])
746
+ present = has_commit(root, item["commit"])
747
+ if present and code_digest(root, item["commit"]) != item["code"]:
748
+ raise Refused(f"{tid}: receipt code does not match its commit")
749
+ if item["kind"] in {"test", "deployed", "live"}:
750
+ if (type(item.get("exit_code")) is not int or type(item.get("valid")) is not bool
751
+ or not isinstance(item.get("command"), list) or not item["command"]
752
+ or any(not isinstance(a, str) for a in item["command"])):
753
+ raise Refused(f"{tid}: command receipt needs its arguments, exit code and validity")
754
+ return {**item, "hash": checksum, "missing": not present}
755
+
756
+
757
+ def legacy_entries(root, tid, text):
758
+ result, previous = [], ""
759
+ for line in text.splitlines():
760
+ try:
761
+ item = verify_receipt(root, tid, json.loads(line))
762
+ except (ValueError, TypeError) as error:
763
+ raise Refused(f"{tid}: broken receipt chain ({error}); conflict markers need"
764
+ f" workorder repair --task {tid}") from None
765
+ if item.get("previous") != previous:
766
+ raise Refused(f"{tid}: broken receipt chain (receipts edited or not in order)")
767
+ result.append(item)
768
+ previous = item["hash"]
769
+ return result
770
+
771
+
772
+ def receipt_name(item):
773
+ stamp = dt.datetime.fromisoformat(item["at"])
774
+ if stamp.tzinfo is None:
775
+ stamp = stamp.replace(tzinfo=dt.timezone.utc) # old receipts allowed naive ISO dates
776
+ stamp = stamp.astimezone(dt.timezone.utc).strftime("%Y%m%dT%H%M%S.%fZ")
777
+ return f"{stamp}-{item['hash'][:12]}.json"
778
+
779
+
780
+ def ordered_entries(root, tid, texts):
781
+ legacy = []
782
+ for path, text in sorted(texts.items()):
783
+ if path.endswith(".jsonl"):
784
+ chain = legacy_entries(root, tid, text)
785
+ overlap = min(len(legacy), len(chain))
786
+ if [e["hash"] for e in legacy[:overlap]] != [e["hash"] for e in chain[:overlap]]:
787
+ raise Refused(f"{tid}: legacy receipt chains disagree")
788
+ if len(chain) > len(legacy):
789
+ legacy = chain
790
+ items = {}
791
+ for path, text in sorted(texts.items()):
792
+ if not path.endswith(".json"):
793
+ continue
794
+ try:
795
+ item = verify_receipt(root, tid, json.loads(text))
796
+ except (ValueError, TypeError) as error:
797
+ raise Refused(f"{tid}: {path}: {error}") from None
798
+ if Path(path).name != receipt_name(item):
799
+ raise Refused(f"{tid}: receipt file name does not match its hash or UTC time: {path}")
800
+ parents = item.get("parents")
801
+ if (not isinstance(parents, list) or any(not isinstance(p, str) or not re.fullmatch(r"[0-9a-f]{64}", p)
802
+ for p in parents)
803
+ or len(set(parents)) != len(parents) or "previous" in item):
804
+ raise Refused(f"{tid}: receipt parents must be distinct hashes")
805
+ if item["hash"] in items:
806
+ raise Refused(f"{tid}: duplicate receipt {item['hash']}")
807
+ items[item["hash"]] = item
808
+ seen = {e["hash"] for e in legacy}
809
+ all_hashes = seen | items.keys()
810
+ converted = {}
811
+ for item in items.values():
812
+ if "legacy" in item:
813
+ original = verify_receipt(root, tid, item["legacy"])
814
+ if ("previous" not in original or "parents" in original
815
+ or any(item.get(k) != v for k, v in original.items()
816
+ if k not in {"hash", "previous", "missing"})):
817
+ raise Refused(f"{tid}: repaired receipt differs from its legacy object")
818
+ converted[original["hash"]] = item["hash"]
819
+ for item in items.values():
820
+ if "legacy" in item:
821
+ previous = item["legacy"]["previous"]
822
+ parent = previous if previous in seen else converted.get(previous)
823
+ if (previous and parent is None) or item["parents"] != ([parent] if previous else []):
824
+ raise Refused(f"{tid}: repaired receipt does not follow its legacy parent")
825
+ children, degrees, ready = {}, {}, []
826
+ for checksum, item in items.items():
827
+ if any(parent not in all_hashes for parent in item["parents"]):
828
+ raise Refused(f"{tid}: a receipt this one follows is missing: removed or not yet merged")
829
+ pending = [parent for parent in item["parents"] if parent not in seen]
830
+ degrees[checksum] = len(pending)
831
+ for parent in pending:
832
+ children.setdefault(parent, []).append(checksum)
833
+ if not pending:
834
+ heapq.heappush(ready, (item["at"], checksum))
835
+ result = list(legacy)
836
+ while ready:
837
+ _, checksum = heapq.heappop(ready)
838
+ result.append(items[checksum])
839
+ for child in children.get(checksum, []):
840
+ degrees[child] -= 1
841
+ if not degrees[child]:
842
+ heapq.heappush(ready, (items[child]["at"], child))
843
+ if len(result) != len(legacy) + len(items):
844
+ raise Refused(f"{tid}: receipt parents form a cycle")
845
+ return result
846
+
847
+
848
+ def repaired_prefix(root, tid, before, after, history):
849
+ """A repair may move a legacy tail only with an exact, verified copy of every old object.
850
+
851
+ The original objects stay inside the new receipts so HEAD and --base can verify the move.
852
+ No other legacy rewrite is allowed.
853
+ """
854
+ if not before.startswith(after):
855
+ return False
856
+ old = legacy_entries(root, tid, before)
857
+ prefix = legacy_entries(root, tid, after)
858
+ mapping = {e["hash"]: e["hash"] for e in prefix}
859
+ converted = {e["legacy"]["hash"]: e for e in history
860
+ if isinstance(e.get("legacy"), dict) and "hash" in e["legacy"]}
861
+ for entry in old[len(prefix):]:
862
+ original = {k: v for k, v in entry.items() if k != "missing"}
863
+ new = converted.get(entry["hash"])
864
+ parent = mapping.get(entry["previous"]) if entry["previous"] else None
865
+ if (new is None or new["legacy"] != original
866
+ or (entry["previous"] and parent is None)
867
+ or new["parents"] != ([parent] if parent else [])
868
+ or any(new.get(k) != v for k, v in original.items() if k not in {"hash", "previous"})):
869
+ return False
870
+ mapping[entry["hash"]] = new["hash"]
871
+ return True
872
+
873
+
874
+ def receipt_changes(root, tid, before, after, history=None):
875
+ changed = []
876
+ for path, old in before.items():
877
+ new = after.get(path)
878
+ if new is not None and (new.startswith(old) if path.endswith(".jsonl") else new == old):
879
+ continue
880
+ if path.endswith(".jsonl") and new is not None and history is not None:
881
+ if repaired_prefix(root, tid, old, new, history):
882
+ continue
883
+ changed.append(path)
884
+ return changed
885
+
886
+
887
+ @cached_read
888
+ def entries(root, tid, staged=False, rev=None):
889
+ task_id(tid)
890
+ texts = receipt_texts(root, tid, staged, rev)
891
+ old = {} if rev else receipt_texts(root, tid, rev="HEAD")
892
+ # Report immutable files before trying to parse a damaged object.
893
+ changed = receipt_changes(root, tid, old, texts)
894
+ if any(p.endswith(".json") for p in changed):
895
+ raise Refused(f"{tid}: committed receipt file removed or changed: {changed[0]}")
896
+ result = ordered_entries(root, tid, texts)
897
+ if receipt_changes(root, tid, old, texts, result):
898
+ raise Refused(f"{tid}: ledger is append-only; committed receipts were removed or changed")
899
+ return result
900
+
901
+
902
+ def write_receipt(root, tid, data):
903
+ path = local_path(root, f".workorder/receipts/{task_id(tid)}/{receipt_name(data)}")
904
+ path.parent.mkdir(parents=True, exist_ok=True)
905
+ with path.open("x", encoding="utf-8", newline="\n") as stream:
906
+ stream.write(packed(data) + "\n")
907
+ invalidate_reads()
908
+ return path
909
+
910
+
911
+ def append(root, tid, item):
912
+ history = entries(root, tid)
913
+ followed = {p for e in history for p in e.get("parents", [e.get("previous", "")])}
914
+ heads = sorted(e["hash"] for e in history if e["hash"] not in followed)
915
+ data = {**item, "task": tid, "at": now(), "who": who(root), "parents": heads}
916
+ data["hash"] = digest(packed(data).encode())
917
+ write_receipt(root, tid, data)
918
+ return data
919
+
920
+
921
+ def repair(root, tid):
922
+ """Split a verified, two-sided append conflict. Refuse ambiguous or damaged input."""
923
+ record(root, tid)
924
+ with ledger_lock(root, tid):
925
+ texts = receipt_texts(root, tid)
926
+ conflicts = [p for p, text in texts.items() if p.endswith(".jsonl") and "<<<<<<<" in text]
927
+ if len(conflicts) != 1:
928
+ raise Refused(f"{tid}: repair needs one legacy ledger with one append conflict")
929
+ path = conflicts[0]
930
+ lines = texts[path].splitlines(keepends=True)
931
+ markers = [(i, line) for i, line in enumerate(lines)
932
+ if line.startswith(("<<<<<<<", "|||||||", "=======", ">>>>>>>"))]
933
+ kinds = [line[:7] for _, line in markers]
934
+ if kinds not in (["<<<<<<<", "=======", ">>>>>>>"],
935
+ ["<<<<<<<", "|||||||", "=======", ">>>>>>>"]):
936
+ raise Refused(f"{tid}: repair needs one complete, two-sided append conflict")
937
+ start, end = markers[0][0], markers[-1][0]
938
+ split = next(i for i, line in markers if line.startswith("======="))
939
+ base_start = next((i for i, line in markers if line.startswith("|||||||")), split)
940
+ if any(line.strip() for line in lines[end + 1:]) or any(line.strip() for line in lines[base_start + 1:split]
941
+ if base_start != split):
942
+ raise Refused(f"{tid}: repair only accepts appended lines after a common prefix")
943
+ prefix = "".join(lines[:start])
944
+ common = legacy_entries(root, tid, prefix)
945
+ sides = [legacy_entries(root, tid, prefix + "".join(side))[len(common):]
946
+ for side in (lines[start + 1:base_start], lines[split + 1:end])]
947
+ converted = {}
948
+ for side in sides:
949
+ parent = common[-1]["hash"] if common else None
950
+ for entry in side:
951
+ original = {k: v for k, v in entry.items() if k != "missing"}
952
+ data = {k: v for k, v in original.items() if k not in {"hash", "previous"}}
953
+ data.update(parents=[parent] if parent else [], legacy=original)
954
+ data["hash"] = digest(packed(data).encode())
955
+ converted[data["hash"]] = data
956
+ parent = data["hash"]
957
+ proposed = {**texts, path: prefix}
958
+ for data in converted.values():
959
+ proposed[f".workorder/receipts/{tid}/{receipt_name(data)}"] = packed(data) + "\n"
960
+ history = ordered_entries(root, tid, proposed)
961
+ if receipt_changes(root, tid, receipt_texts(root, tid, rev="HEAD"), proposed, history):
962
+ raise Refused(f"{tid}: repair would lose committed receipts")
963
+ for data in converted.values():
964
+ name = f".workorder/receipts/{tid}/{receipt_name(data)}"
965
+ if name in texts and texts[name] != proposed[name]:
966
+ raise Refused(f"{tid}: repair destination already exists: {name}")
967
+ for data in converted.values():
968
+ if f".workorder/receipts/{tid}/{receipt_name(data)}" not in texts:
969
+ write_receipt(root, tid, data)
970
+ local_path(root, path).write_text(prefix, encoding="utf-8", newline="\n")
971
+ return (f"{tid}: kept {len(common)} legacy receipts in {path}; converted {len(sides[0])} and"
972
+ f" {len(sides[1])} branch receipts into {len(converted)} files; stage the repaired files")
973
+
974
+
975
+ def ledger_lock(root, tid):
976
+ """Serialise receipt writers for one task in this clone: each writer must see all current heads."""
977
+ import contextlib
978
+ import time
979
+
980
+ @contextlib.contextmanager
981
+ def held():
982
+ folder = root / git(root, "rev-parse", "--git-path", "workorder-locks").stdout.strip()
983
+ folder.mkdir(parents=True, exist_ok=True)
984
+ lock = folder / f"{task_id(tid)}.lock"
985
+ deadline = time.monotonic() + 120
986
+ while True:
987
+ try:
988
+ handle = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
989
+ break
990
+ except FileExistsError:
991
+ if time.monotonic() > deadline:
992
+ raise Refused(f"{tid}: another receipt is being written; if no workorder command is"
993
+ f" running, remove {lock}") from None
994
+ time.sleep(0.05)
995
+ try:
996
+ yield
997
+ finally:
998
+ os.close(handle)
999
+ lock.unlink(missing_ok=True)
1000
+ return held()
1001
+
1002
+
1003
+ # Releases up to 0.2.0 (named NotQuite) kept receipts in .notquite/. It stays outside the code
1004
+ # fingerprint, so a repository that moved its receipts to .workorder/ still verifies old receipts.
1005
+ LEGACY_DIR = ".notquite/"
1006
+ CODE_PATHS = (".", ":(exclude)tasks", ":(exclude).workorder", ":(exclude).notquite")
1007
+
1008
+
1009
+ # Commits never change, so their fingerprints are worked out once per run.
1010
+ _DIGESTS = {}
1011
+ _PRESENT = {}
1012
+
1013
+
1014
+ SHELL_OPERATORS = {"&&", "||", ";", "|", "&", ">", ">>", "<", "2>", "2>&1"}
1015
+
1016
+
1017
+ def split_command(value, what="test"):
1018
+ """A test command line as arguments: split on spaces, quotes group words, backslashes are kept as
1019
+ written (so Windows paths work), and no shell runs it, so shell operators are refused."""
1020
+ lexer = shlex.shlex(value, posix=True)
1021
+ lexer.whitespace_split, lexer.escape, lexer.commenters = True, "", ""
1022
+ try:
1023
+ words = list(lexer)
1024
+ except ValueError as error:
1025
+ raise Refused(f"{what} is not a valid command line ({error})") from None
1026
+ if words and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*=.*", words[0]):
1027
+ raise Refused(f"{what} starts with an environment setting ({words[0]}), which needs a shell;"
1028
+ " use env, as in: env " + " ".join(words))
1029
+ operators = sorted(set(words) & SHELL_OPERATORS)
1030
+ if operators:
1031
+ raise Refused(f"{what} runs without a shell, so {' '.join(operators)} would be passed as an argument;"
1032
+ " put the steps in a script, or use sh -c '...'")
1033
+ return words
1034
+
1035
+
1036
+ def join_command(words):
1037
+ """Show arguments the way split_command reads them: plain words as they are, others quoted."""
1038
+ shown = []
1039
+ for word in words:
1040
+ if word and not any(ch.isspace() or ch in "\"'" for ch in word):
1041
+ shown.append(word)
1042
+ else:
1043
+ shown.append(f"'{word}'" if '"' in word else f'"{word}"')
1044
+ return " ".join(shown)
1045
+
1046
+
1047
+ def has_commit(root, commit):
1048
+ key = (str(root), commit)
1049
+ if key not in _PRESENT:
1050
+ _PRESENT[key] = git(root, "cat-file", "-e", f"{commit}^{{commit}}", required=False).returncode == 0
1051
+ return _PRESENT[key]
1052
+
1053
+
1054
+ def contains(root, ancestor, commit):
1055
+ """True when commit's history includes ancestor (both must be in this clone)."""
1056
+ return (has_commit(root, ancestor) and has_commit(root, commit)
1057
+ and git(root, "merge-base", "--is-ancestor", ancestor, commit, required=False).returncode == 0)
1058
+
1059
+
1060
+ def _cache_dir(root):
1061
+ key = ("cache", str(root))
1062
+ if key not in _DIGESTS:
1063
+ found = git(root, "rev-parse", "--git-path", "workorder-digests", required=False)
1064
+ _DIGESTS[key] = (root / found.stdout.strip()) if found.returncode == 0 else None
1065
+ return _DIGESTS[key]
1066
+
1067
+
1068
+ def code_digest(root, commit):
1069
+ """The code fingerprint of a commit (or tree). Commits never change, so the result is kept for the
1070
+ run and in .git/workorder-digests/ for later runs; it is a cache, never evidence."""
1071
+ if not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", commit):
1072
+ return _code_digest(root, commit)
1073
+ key = (str(root), commit)
1074
+ if key in _DIGESTS:
1075
+ return _DIGESTS[key]
1076
+ folder = _cache_dir(root)
1077
+ cached = folder / commit if folder else None
1078
+ try:
1079
+ value = cached.read_text(encoding="ascii").strip() if cached and cached.is_file() else ""
1080
+ except OSError:
1081
+ value = ""
1082
+ if not re.fullmatch(r"[0-9a-f]{64}", value):
1083
+ value = _code_digest(root, commit)
1084
+ try:
1085
+ if cached:
1086
+ folder.mkdir(exist_ok=True)
1087
+ cached.write_text(value, encoding="ascii")
1088
+ except OSError:
1089
+ pass
1090
+ _DIGESTS[key] = value
1091
+ return value
1092
+
1093
+
1094
+ def _code_digest(root, commit):
1095
+ listing = git(root, "ls-tree", "-r", "-z", commit, required=False)
1096
+ if listing.returncode:
1097
+ raise Refused(f"commit {commit[:7]} is not in this clone; fetch the full history"
1098
+ " (in GitHub Actions: actions/checkout with fetch-depth: 0)")
1099
+ tree = listing.stdout
1100
+ code = [entry for entry in tree.split("\0") if entry
1101
+ and not entry.partition("\t")[2].startswith(("tasks/", ".workorder/", LEGACY_DIR))]
1102
+ return digest("\0".join(code).encode("utf-8", errors="surrogateescape"))
1103
+
1104
+
1105
+ def index_code(root):
1106
+ """The code fingerprint of what the next commit would contain (the index)."""
1107
+ return code_digest(root, git(root, "write-tree").stdout.strip())
1108
+
1109
+
1110
+ def dirty_paths(root):
1111
+ """Uncommitted or untracked code files; task records and receipts do not count."""
1112
+ status = git(root, "status", "--porcelain", "--untracked-files=all", "--", *CODE_PATHS).stdout
1113
+ return [line[3:] for line in status.splitlines()]
1114
+
1115
+
1116
+ def clean_code(root):
1117
+ return not dirty_paths(root)
1118
+
1119
+
1120
+ def describe_dirty(paths):
1121
+ shown = ", ".join(paths[:5]) + (f" and {len(paths) - 5} more" if len(paths) > 5 else "")
1122
+ return f"uncommitted or untracked files: {shown} (commit them, or add build output to .gitignore)"
1123
+
1124
+
1125
+ def receipt(root, tid, kind, command=(), target=None, ref="refs/heads/main"):
1126
+ repository(root)
1127
+ record(root, tid)
1128
+ commit = head(root)
1129
+ if kind not in KINDS:
1130
+ raise Refused("unknown receipt kind")
1131
+ if kind in {"implemented", "test"} and not clean_code(root):
1132
+ raise Refused("commit the code before recording implementation or tests; "
1133
+ + describe_dirty(dirty_paths(root)))
1134
+ data = {"kind": kind, "commit": commit, "code": code_digest(root, commit)}
1135
+ if kind == "merged":
1136
+ if not ref.startswith("refs/heads/"):
1137
+ raise Refused("merge ref must be a full branch ref")
1138
+ if not has_origin(root):
1139
+ raise Refused("receipt merged reads the branch from origin; add an origin remote")
1140
+ git(root, "fetch", "--no-tags", "origin", ref)
1141
+ commit = git(root, "rev-parse", "FETCH_HEAD^{commit}").stdout.strip()
1142
+ data.update(commit=commit, code=code_digest(root, commit), ref=ref)
1143
+ if kind in {"test", "deployed", "live"}:
1144
+ if not command:
1145
+ raise Refused("supply the command after --")
1146
+ if kind in {"deployed", "live"} and not target:
1147
+ raise Refused("read-backs need --target")
1148
+ try:
1149
+ run = subprocess.run(list(command), cwd=root, capture_output=kind != "test",
1150
+ encoding="utf-8", errors="replace")
1151
+ exit_code = run.returncode
1152
+ output = run.stdout or ""
1153
+ except OSError as error:
1154
+ exit_code, output = 127, str(error)
1155
+ valid = exit_code == 0
1156
+ if kind == "test":
1157
+ valid = valid and clean_code(root) and head(root) == commit
1158
+ else:
1159
+ valid = valid and bool(re.search(rf"(?<![0-9a-f]){commit}(?![0-9a-f])", output))
1160
+ data.update(command=list(command), exit_code=exit_code, valid=valid)
1161
+ if kind != "test":
1162
+ data.update(target=target, output_sha256=digest(output.encode()))
1163
+ with ledger_lock(root, tid):
1164
+ return append(root, tid, data)