flowstatemcp 2.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.
Files changed (143) hide show
  1. flowstate/__init__.py +34 -0
  2. flowstate/__main__.py +7 -0
  3. flowstate/activity.py +224 -0
  4. flowstate/agent_guide.py +251 -0
  5. flowstate/app_keys.py +141 -0
  6. flowstate/approvals.py +974 -0
  7. flowstate/approve_page.py +565 -0
  8. flowstate/ask.py +107 -0
  9. flowstate/autosession.py +480 -0
  10. flowstate/backup.py +201 -0
  11. flowstate/brief.py +420 -0
  12. flowstate/card_offer.py +208 -0
  13. flowstate/card_taps.py +165 -0
  14. flowstate/card_trust.py +127 -0
  15. flowstate/claims.py +461 -0
  16. flowstate/cleanup.py +619 -0
  17. flowstate/cli.py +728 -0
  18. flowstate/cli_data.py +434 -0
  19. flowstate/cli_more.py +302 -0
  20. flowstate/cli_review.py +459 -0
  21. flowstate/cloudflared_check.py +49 -0
  22. flowstate/conflict_card_ui.py +286 -0
  23. flowstate/conflict_cards.py +1193 -0
  24. flowstate/conflict_reopen.py +320 -0
  25. flowstate/conflicts.py +420 -0
  26. flowstate/connections.py +33 -0
  27. flowstate/database.py +2191 -0
  28. flowstate/dbconn.py +308 -0
  29. flowstate/deletes.py +860 -0
  30. flowstate/embeddings.py +354 -0
  31. flowstate/erase.py +1047 -0
  32. flowstate/extras.py +71 -0
  33. flowstate/git_capture.py +157 -0
  34. flowstate/guard.py +224 -0
  35. flowstate/handoffs.py +168 -0
  36. flowstate/history.py +755 -0
  37. flowstate/history_page.py +276 -0
  38. flowstate/http_app.py +204 -0
  39. flowstate/identity.py +387 -0
  40. flowstate/install_name.py +140 -0
  41. flowstate/ledger.py +272 -0
  42. flowstate/legacy_args.py +65 -0
  43. flowstate/links.py +609 -0
  44. flowstate/markdown_io.py +242 -0
  45. flowstate/meaning.py +398 -0
  46. flowstate/memory_import.py +92 -0
  47. flowstate/migrations/001_auto_sessions.sql +16 -0
  48. flowstate/migrations/002_review_queue.sql +33 -0
  49. flowstate/migrations/003_links.sql +47 -0
  50. flowstate/migrations/004_review_mode.sql +24 -0
  51. flowstate/migrations/005_history.sql +21 -0
  52. flowstate/migrations/006_activity.sql +26 -0
  53. flowstate/migrations/007_meaning_index.sql +16 -0
  54. flowstate/migrations/008_git_capture.sql +12 -0
  55. flowstate/migrations/009_hard_rules.sql +13 -0
  56. flowstate/migrations/010_handoffs.sql +14 -0
  57. flowstate/migrations/011_record_meta.sql +13 -0
  58. flowstate/migrations/012_accountability.sql +71 -0
  59. flowstate/migrations/013_todo_claims.sql +36 -0
  60. flowstate/migrations/014_decision_conflicts.sql +41 -0
  61. flowstate/migrations/015_session_runs.sql +17 -0
  62. flowstate/migrations/016_write_receipts.sql +35 -0
  63. flowstate/migrations/017_run_views.sql +26 -0
  64. flowstate/migrations/018_run_views_upto.sql +4 -0
  65. flowstate/migrations/019_approvals.sql +47 -0
  66. flowstate/migrations/020_source_stamps.sql +10 -0
  67. flowstate/migrations/021_review_links.sql +11 -0
  68. flowstate/migrations/022_review_start_tickets.sql +10 -0
  69. flowstate/migrations/023_conflict_cards.sql +68 -0
  70. flowstate/migrations/024_rule_confirmations.sql +7 -0
  71. flowstate/migrations/025_confirmed_hash.sql +7 -0
  72. flowstate/migrations/__init__.py +149 -0
  73. flowstate/models.py +307 -0
  74. flowstate/names.py +157 -0
  75. flowstate/offsite.py +386 -0
  76. flowstate/offsite_crypto.py +272 -0
  77. flowstate/paths.py +265 -0
  78. flowstate/popup.py +238 -0
  79. flowstate/priority.py +66 -0
  80. flowstate/privatefs.py +476 -0
  81. flowstate/project_history.py +710 -0
  82. flowstate/provenance.py +696 -0
  83. flowstate/receipts.py +377 -0
  84. flowstate/relay/__init__.py +72 -0
  85. flowstate/relay/acme.py +271 -0
  86. flowstate/relay/api.py +164 -0
  87. flowstate/relay/cli.py +344 -0
  88. flowstate/relay/crypto.py +137 -0
  89. flowstate/relay/ct.py +118 -0
  90. flowstate/relay/runner.py +177 -0
  91. flowstate/relay/store.py +191 -0
  92. flowstate/relay/tunnel.py +413 -0
  93. flowstate/release_signers +14 -0
  94. flowstate/remote_auth.py +1219 -0
  95. flowstate/review.py +320 -0
  96. flowstate/review_apply.py +140 -0
  97. flowstate/review_card_ui.py +241 -0
  98. flowstate/review_cards.py +564 -0
  99. flowstate/review_mode.py +274 -0
  100. flowstate/review_page.py +1361 -0
  101. flowstate/review_phone.py +465 -0
  102. flowstate/review_tunnel.py +338 -0
  103. flowstate/routing.py +392 -0
  104. flowstate/rules.py +418 -0
  105. flowstate/safety.py +98 -0
  106. flowstate/saves.py +83 -0
  107. flowstate/scheduler.py +160 -0
  108. flowstate/schema.sql +713 -0
  109. flowstate/search.py +355 -0
  110. flowstate/secret_store.py +271 -0
  111. flowstate/secrets_scan.py +135 -0
  112. flowstate/selfupdate.py +1020 -0
  113. flowstate/server.py +1299 -0
  114. flowstate/session_contents.py +382 -0
  115. flowstate/session_records.py +629 -0
  116. flowstate/site_style.py +46 -0
  117. flowstate/stored.py +158 -0
  118. flowstate/story.py +442 -0
  119. flowstate/surface.py +173 -0
  120. flowstate/tasks.py +231 -0
  121. flowstate/term.py +40 -0
  122. flowstate/tool_labels.py +104 -0
  123. flowstate/tooldefs.py +383 -0
  124. flowstate/tools/__init__.py +118 -0
  125. flowstate/tools/core.py +545 -0
  126. flowstate/tools/files.py +416 -0
  127. flowstate/tools/git_ops.py +1081 -0
  128. flowstate/tools/intelligence.py +376 -0
  129. flowstate/tools/learning.py +282 -0
  130. flowstate/tools/problems.py +159 -0
  131. flowstate/tools/sessions.py +266 -0
  132. flowstate/tools/story.py +48 -0
  133. flowstate/tools/todos.py +79 -0
  134. flowstate/tools/utils.py +71 -0
  135. flowstate/tools/variables.py +345 -0
  136. flowstate/updates.py +482 -0
  137. flowstate/urls.py +7 -0
  138. flowstate/waiting.py +828 -0
  139. flowstate/who.py +302 -0
  140. flowstatemcp-2.5.0.dist-info/METADATA +88 -0
  141. flowstatemcp-2.5.0.dist-info/RECORD +143 -0
  142. flowstatemcp-2.5.0.dist-info/WHEEL +4 -0
  143. flowstatemcp-2.5.0.dist-info/entry_points.txt +3 -0
flowstate/cleanup.py ADDED
@@ -0,0 +1,619 @@
1
+ """Clean-up suggestions (v2 Phase D): likely duplicates, stale items, misfiled items.
2
+
3
+ Suggestions only. They go to the review queue as items of kind `cleanup`; nothing is moved,
4
+ closed or deleted until the user approves one. Approving applies just that suggestion
5
+ (move a misfiled record, cancel a duplicate or stale todo) and records it in the edit
6
+ history, so it can be undone. A suggestion the user rejected is not suggested again.
7
+ Approving is tied to the exact rows listed when it was queued (task 74, as deletes are): if
8
+ one changed, or one was added, is missing or was already removed, nothing is changed and the
9
+ suggestion is closed; running the clean-up again suggests it anew.
10
+
11
+ Misfiled: a record whose words match another project's names and components (project name,
12
+ description, component names, weighted by how rare each word is across projects) much
13
+ better than its own project's, and that clearly resembles that project's own records more
14
+ than any other's. Even then it is only suggested when the record names the target: its text
15
+ contains the target project's name or one of its components' names (not "General"; names of
16
+ 4+ characters), and not its own project's name. FlowState never asks the user to judge a
17
+ guess it isn't sure of; `withdraw_unsure` takes back unsure ones queued by older versions.
18
+ Each suggestion is one plain question ('Move learning "..." from A to B? It mentions B.').
19
+ Local word statistics only; no AI service.
20
+ """
21
+
22
+ import json
23
+ import math
24
+ import re
25
+ import sqlite3
26
+ from collections import Counter, defaultdict
27
+ from datetime import datetime, timedelta, timezone
28
+ from pathlib import Path
29
+ from typing import Optional
30
+
31
+ from . import dbconn
32
+ from . import history, links, review
33
+
34
+ STALE_TODO_DAYS = 120
35
+ DUP_JACCARD = 0.8
36
+ _STOP = set("""the and for with that this from are was were not but have has had you your all any
37
+ can will into out use used using when then than they them its our one two new also only just
38
+ more most must should would could been being after before over under such each some other via
39
+ per need needs about what which there their here where while does done make made like get set
40
+ run file files test tests data work fix fixed add added code server servers version true false
41
+ none null phase step part app apps system project projects support tool tools build client
42
+ clients general core main base layer api web docs doc page pages review user users setup
43
+ config""".split())
44
+ _OPEN_TODO = ("pending", "in_progress", "blocked")
45
+
46
+
47
+ _BASIC_STOP = set("the and for with that this from are was were not but have has had its into "
48
+ "out a an of to in on at by is be it as or".split())
49
+
50
+
51
+ def _dup_toks(s: str) -> set:
52
+ return {t for t in re.findall(r"[a-z0-9][a-z0-9_]+", (s or "").lower().replace("-", "_"))
53
+ if t not in _BASIC_STOP}
54
+
55
+
56
+ def similarity(ta: set, tb: set) -> Optional[float]:
57
+ """Jaccard similarity of two titles' words, or None when either is too short to tell."""
58
+ if len(ta) < 3 or len(tb) < 3:
59
+ return None
60
+ return len(ta & tb) / len(ta | tb)
61
+
62
+
63
+ def is_duplicate(a: str, b: str) -> bool:
64
+ """The duplicate check `suggest` uses, for two texts: the same words, or similar enough."""
65
+ ta, tb = _dup_toks(a), _dup_toks(b)
66
+ if ta and ta == tb:
67
+ return True
68
+ j = similarity(ta, tb)
69
+ return j is not None and j >= DUP_JACCARD
70
+
71
+
72
+ def _toks(s: str) -> set:
73
+ return {t for t in re.findall(r"[a-z][a-z0-9_]{2,}", (s or "").lower().replace("-", "_"))
74
+ if t not in _STOP}
75
+
76
+
77
+ def _short(s: str, n: int = 70) -> str:
78
+ return links._one_line(s, n)
79
+
80
+
81
+ TITLE_MAX = 40 # keeps the question and its reason within about 150 characters
82
+ WITHDRAWN = "Withdrawn by FlowState: it wasn't sure enough to ask you."
83
+
84
+
85
+ def _words(s: Optional[str]) -> str:
86
+ """Lowercase words joined by single spaces, padded, for whole-name matching."""
87
+ return " " + " ".join(re.findall(r"[a-z0-9]+", (s or "").lower())) + " "
88
+
89
+
90
+ def _names(text: str, name: Optional[str]) -> bool:
91
+ n = _words(name).strip()
92
+ return len(n) >= 4 and f" {n} " in text
93
+
94
+
95
+ def question(kind: str, rkind: str, title: str, project: str, target: Optional[str] = None,
96
+ reason: str = "") -> str:
97
+ """The one plain line a clean-up item asks the user: the question, then its reason."""
98
+ t = f'"{_short(title, TITLE_MAX)}"'
99
+ q = (f"Move {rkind} {t} from {project} to {target}?" if kind == "misfiled"
100
+ else f"Cancel {rkind} {t} in {project}?")
101
+ full = f"{q} {reason[:1].upper()}{reason[1:]}." if reason else q
102
+ if len(full) > 150 and kind == "misfiled":
103
+ full = f"{q} It mentions {target}."
104
+ return full
105
+
106
+
107
+ def ask(payload: dict, project: str, db_path: Optional[Path] = None) -> str:
108
+ """A clean-up item's question in verb form, for the approval pages:
109
+ 'move the learning "..." from A to B' / 'cancel the todo "..." in A'."""
110
+ recs = payload.get("records") or []
111
+ rkind, rid = recs[-1] if recs else ("record", None)
112
+ title = None
113
+ if db_path and rid is not None:
114
+ try:
115
+ conn = links.connect(db_path)
116
+ try:
117
+ title = links.label(conn, rkind, rid)
118
+ finally:
119
+ conn.close()
120
+ except Exception: # noqa: BLE001 - the question still reads without the title
121
+ title = None
122
+ what = f'the {rkind} "{_short(title, TITLE_MAX)}"' if title else f"{rkind} #{rid}"
123
+ if payload.get("type") == "misfiled":
124
+ return f"move {what} from {project} to {payload.get('target') or 'another project'}"
125
+ return f"cancel {what} in {project}"
126
+
127
+
128
+ def _records(conn) -> list[dict]:
129
+ """Every movable record: kind, id, project, text, open?"""
130
+ out = []
131
+ for r in conn.execute("SELECT id, project_id, title, description, status, created_at FROM todos"):
132
+ out.append({"kind": "todo", "id": r[0], "project_id": r[1], "title": r[2],
133
+ "text": f"{r[2]} {r[3] or ''}", "open": (r[4] or "pending") in _OPEN_TODO,
134
+ "status": r[4] or "pending", "created_at": r[5]})
135
+ for r in conn.execute("SELECT id, project_id, insight, context, created_at FROM learnings"):
136
+ out.append({"kind": "learning", "id": r[0], "project_id": r[1], "title": r[2],
137
+ "text": f"{r[2]} {r[3] or ''}", "open": True, "created_at": r[4]})
138
+ for r in conn.execute("""SELECT p.id, c.project_id, p.title, p.description, p.status, p.created_at
139
+ FROM problems p JOIN components c ON c.id = p.component_id"""):
140
+ out.append({"kind": "problem", "id": r[0], "project_id": r[1], "title": r[2],
141
+ "text": f"{r[2]} {r[3] or ''}",
142
+ "open": (r[4] or "open") not in ("solved", "wont_fix", "closed"),
143
+ "status": r[4], "created_at": r[5]})
144
+ for r in conn.execute("""SELECT ch.id, c.project_id, ch.field_name, ch.reason, ch.new_value,
145
+ ch.created_at FROM changes ch JOIN components c ON c.id = ch.component_id"""):
146
+ out.append({"kind": "change", "id": r[0], "project_id": r[1], "title": r[2],
147
+ "text": f"{r[2]} {r[3] or ''} {r[4] or ''}", "open": True, "created_at": r[5]})
148
+ return out
149
+
150
+
151
+ class _Model:
152
+ """Word statistics used to spot misfiled records."""
153
+
154
+ def __init__(self, conn, recs: list[dict]):
155
+ self.names = {r[0]: r[1] for r in conn.execute("SELECT id, name FROM projects")}
156
+ self.parts = defaultdict(list)
157
+ for pid, name in conn.execute("SELECT project_id, name FROM components ORDER BY id"):
158
+ if (name or "").strip().lower() != "general":
159
+ self.parts[pid].append(name)
160
+ sig = defaultdict(set)
161
+ for r in conn.execute("SELECT id, name, description FROM projects"):
162
+ sig[r[0]] |= _toks(f"{r[1]} {r[2] or ''}")
163
+ for r in conn.execute("SELECT project_id, name FROM components"):
164
+ sig[r[0]] |= _toks(r[1])
165
+ df = Counter(w for ws in sig.values() for w in ws)
166
+ n = max(1, len(self.names))
167
+ # a word counts as a project's signature if few projects use it (about 1 in 5 or fewer)
168
+ self.max_df = max(1, int(0.22 * n))
169
+ self.sig, self.df = sig, df
170
+ self.sig_idf = {w: math.log(1 + n / c) for w, c in df.items()}
171
+ docs = [(r["project_id"], _toks(r["text"])) for r in recs]
172
+ dfr = Counter(w for _p, ws in docs for w in ws)
173
+ self.nd, self.dfr = max(1, len(docs)), dfr
174
+ cent = defaultdict(Counter)
175
+ for p, ws in docs:
176
+ for w in ws:
177
+ cent[p][w] += math.log(self.nd / dfr[w])
178
+ self.cent = cent
179
+ self.norm = {p: math.sqrt(sum(v * v for v in c.values())) for p, c in cent.items()}
180
+
181
+ def misfiled(self, rec: dict) -> Optional[dict]:
182
+ ws = _toks(rec["text"])
183
+ own = rec["project_id"]
184
+ score, evidence = Counter(), defaultdict(list)
185
+ for q, sw in self.sig.items():
186
+ for w in ws & sw:
187
+ if self.df[w] <= self.max_df:
188
+ score[q] += self.sig_idf[w]
189
+ evidence[q].append(w)
190
+ if not score:
191
+ return None
192
+ best, bs = score.most_common(1)[0]
193
+ mine = score.get(own, 0)
194
+ second = score.most_common(2)[1][1] if len(score) > 1 else 0
195
+ if best == own or len(evidence[best]) < 2 or bs < 2 * mine + 2 or bs < 1.3 * second:
196
+ return None
197
+ vec = {w: math.log(self.nd / self.dfr[w]) for w in ws if self.dfr.get(w)}
198
+ vn = math.sqrt(sum(v * v for v in vec.values())) or 1.0
199
+ sims = Counter({q: sum(vec[w] * self.cent[q].get(w, 0) for w in vec) / (vn * self.norm[q])
200
+ for q in self.cent if q != own and self.norm.get(q)})
201
+ top = sims.most_common(2)
202
+ if not top or top[0][1] < 0.04:
203
+ return None
204
+ target, s1 = top[0]
205
+ s2 = top[1][1] if len(top) > 1 else 0.0
206
+ if s1 < 0.08 or s1 < 1.5 * s2:
207
+ return None # not sure: never asked
208
+ text, name = _words(rec["text"]), self.names.get(target)
209
+ if _names(text, self.names.get(own)):
210
+ return None # it names its own project too
211
+ if _names(text, name):
212
+ reason = f"it mentions {name}"
213
+ else:
214
+ hits = [c for c in self.parts.get(target, []) if _names(text, c)]
215
+ if not hits:
216
+ return None # it names neither the other project nor any of its parts
217
+ hit = min(hits, key=lambda c: text.index(f" {_words(c).strip()} "))
218
+ reason = f'it mentions {name}\'s "{hit}" component'
219
+ return {"target_project_id": target, "target": name, "confidence": "likely",
220
+ "reason": reason, "words": sorted(set(evidence[best]))[:6]}
221
+
222
+
223
+ def suggest(db_path: Path, project_id: Optional[int] = None,
224
+ kinds=("duplicate", "stale", "misfiled"), now: Optional[datetime] = None) -> list[dict]:
225
+ """All suggestions for one project (or every project), most useful first."""
226
+ conn = dbconn.connect(str(db_path), timeout=5.0)
227
+ conn.row_factory = sqlite3.Row
228
+ try:
229
+ recs = _records(conn)
230
+ names = {r[0]: r[1] for r in conn.execute("SELECT id, name FROM projects")}
231
+ mine = [r for r in recs if project_id is None or r["project_id"] == project_id]
232
+ out = []
233
+ if "misfiled" in kinds:
234
+ model = _Model(conn, recs)
235
+ for r in mine:
236
+ m = model.misfiled(r)
237
+ if m:
238
+ here = names[r["project_id"]]
239
+ out.append({"type": "misfiled", "project_id": r["project_id"],
240
+ "records": [[r["kind"], r["id"]]], **m,
241
+ "summary": question("misfiled", r["kind"], r["title"], here,
242
+ m["target"], m["reason"]),
243
+ "details": f"Approve moves it (undo puts it back). Reject keeps it "
244
+ f"in {here}; FlowState won't ask again."})
245
+ if "duplicate" in kinds:
246
+ groups = defaultdict(list)
247
+ for r in mine: # todos only: approving a duplicate of another kind would do nothing
248
+ if r["kind"] == "todo" and r["open"]:
249
+ groups[(r["project_id"], r["kind"])].append((r, _dup_toks(r["title"])))
250
+ for (_pid, kind), items in groups.items():
251
+ for i, (a, ta) in enumerate(items):
252
+ for b, tb in items[i + 1:]:
253
+ j = similarity(ta, tb)
254
+ if j is not None and j >= DUP_JACCARD:
255
+ old, new = sorted((a, b), key=lambda x: x["id"])
256
+ why = f'it repeats {kind} "{_short(old["title"], TITLE_MAX)}"'
257
+ out.append({"type": "duplicate", "project_id": old["project_id"],
258
+ "records": [[kind, old["id"]], [kind, new["id"]]],
259
+ "similarity": round(j, 2), "reason": why,
260
+ "summary": question("duplicate", kind, new["title"],
261
+ names[old["project_id"]], reason=why),
262
+ "details": "Approve cancels the newer todo (kept, marked "
263
+ "cancelled; undo reopens it). Reject keeps both; "
264
+ "FlowState won't ask again."})
265
+ if "stale" in kinds:
266
+ cutoff = ((now or datetime.now(timezone.utc)) - timedelta(days=STALE_TODO_DAYS)
267
+ ).strftime("%Y-%m-%d %H:%M:%S")
268
+ for r in mine:
269
+ if r["kind"] == "todo" and r["status"] == "pending" and (r["created_at"] or "9") < cutoff:
270
+ why = f"it has waited since {(r['created_at'] or '')[:10]} (over {STALE_TODO_DAYS} days)"
271
+ out.append({"type": "stale", "project_id": r["project_id"],
272
+ "records": [["todo", r["id"]]], "reason": why,
273
+ "summary": question("stale", "todo", r["title"], names[r["project_id"]],
274
+ reason=why),
275
+ "details": "Approve cancels it (kept, marked cancelled; undo reopens "
276
+ "it). Reject keeps it open; FlowState won't ask again."})
277
+ order = {"misfiled": 0, "duplicate": 1, "stale": 2}
278
+ out.sort(key=lambda s: (order[s["type"]], s["project_id"], s["records"]))
279
+ return out
280
+ finally:
281
+ conn.close()
282
+
283
+
284
+ def _fingerprint(s: dict) -> str:
285
+ return f"{s['type']}:" + ",".join(f"{k}#{i}" for k, i in s["records"])
286
+
287
+
288
+ def withdraw_unsure(db_path: Path, timeout: float = 5.0) -> int:
289
+ """Reject, as FlowState, pending misfiled suggestions an older version queued without
290
+ being sure (confidence "unsure", or neither "likely" nor a `reason`). Only review_items
291
+ rows change, never a record; the fingerprint stays, so they are not suggested again.
292
+ Returns the count."""
293
+ conn = dbconn.connect(str(db_path), timeout=timeout)
294
+ try:
295
+ if not review.available(conn):
296
+ return 0
297
+ ids = []
298
+ for iid, payload in conn.execute("SELECT id, payload FROM review_items "
299
+ "WHERE kind = 'cleanup' AND status = 'pending'"):
300
+ try:
301
+ p = json.loads(payload or "{}")
302
+ except ValueError:
303
+ continue
304
+ sure = p.get("confidence") == "likely" or (p.get("reason") and p.get("confidence") != "unsure")
305
+ if p.get("type") == "misfiled" and not sure:
306
+ ids.append(iid)
307
+ if ids:
308
+ conn.executemany("UPDATE review_items SET status = 'rejected', decided_at = ?, "
309
+ "decided_by = 'FlowState', reject_reason = ? "
310
+ "WHERE id = ? AND status = 'pending'",
311
+ [(review._now(), WITHDRAWN, i) for i in ids])
312
+ conn.commit()
313
+ return len(ids)
314
+ finally:
315
+ conn.close()
316
+
317
+
318
+ def queue(db_path: Path, suggestions: list[dict], source: str = "cleanup") -> dict:
319
+ """Add suggestions to the review queue (additive). Skips any already suggested before,
320
+ whatever its status (so rejected ones don't come back), except one FlowState closed
321
+ because its list went out of date (task 74): that one is asked again. Each item stores
322
+ the exact rows approving it would change (`bound`). A waiting item whose list no longer
323
+ matches is closed and queued again (`replaced`). First withdraws unsure ones left by
324
+ older versions (`withdrew`)."""
325
+ from . import deletes
326
+ withdrew = withdraw_unsure(db_path)
327
+ conn = dbconn.connect(str(db_path), timeout=5.0)
328
+ conn.row_factory = sqlite3.Row
329
+ try:
330
+ if not review.available(conn):
331
+ raise review.ReviewError("review_queue_unavailable", "The review queue isn't set up.")
332
+ seen, waiting = set(), {}
333
+ for r in conn.execute("SELECT id, status, decided_by, payload FROM review_items "
334
+ "WHERE kind = 'cleanup'"):
335
+ try:
336
+ p = json.loads(r["payload"] or "{}")
337
+ except ValueError:
338
+ continue
339
+ if r["status"] == "rejected" and r["decided_by"] == VOIDED_BY:
340
+ continue # closed as out of date: may be suggested again
341
+ seen.add(p.get("fingerprint"))
342
+ if r["status"] == "pending":
343
+ waiting[p.get("fingerprint")] = (r["id"], p)
344
+ added, skipped, stale = [], 0, []
345
+ for s in suggestions:
346
+ fp = _fingerprint(s)
347
+ payload = {k: v for k, v in s.items() if k not in ("summary", "details", "project_id")}
348
+ payload["fingerprint"] = fp
349
+ rows = bind(conn, payload)
350
+ if rows is not None:
351
+ payload["bound"] = rows
352
+ if fp in waiting and rows is not None and \
353
+ (waiting[fp][1].get("bound") or {}).get("digest") != rows["digest"]:
354
+ then = waiting[fp][1].get("bound") or \
355
+ (ERASED_WHY if waiting[fp][1].get("bound_erased") else None)
356
+ stale.append((waiting[fp][0], then, rows)) # its list is out of date: replaced
357
+ elif fp in seen:
358
+ skipped += 1
359
+ continue
360
+ added.append(review.add_item(db_path, s["project_id"], "cleanup", s["summary"],
361
+ s["details"], payload, source, conn=conn))
362
+ seen.add(fp)
363
+ conn.commit()
364
+ finally:
365
+ conn.close()
366
+ replaced = []
367
+ for iid, then, rows in stale:
368
+ why = (deletes._bound_diff(then, rows, _VERBS) if isinstance(then, dict)
369
+ else ERASED_WHY if then == ERASED_WHY else "queued by an older FlowState")
370
+ if deletes.void(db_path, iid, f"Replaced by a new suggestion: what it would change "
371
+ f"changed since it was suggested ({why}).", "cleanup"):
372
+ replaced.append(iid)
373
+ out = {"queued": len(added), "item_ids": added, "already_suggested": skipped,
374
+ "withdrew": withdrew}
375
+ if replaced:
376
+ out["replaced"] = replaced
377
+ return out
378
+
379
+
380
+ # ---------------------------------------------------------------- the exact list (task 74)
381
+ # Approving a clean-up that changes records is tied to the rows listed when it was queued,
382
+ # the same way a delete is (deletes.bind, task 72): a changed row, or a row added, missing or
383
+ # already removed, and approving it changes nothing and closes it (VOIDED_BY).
384
+ VOIDED_BY = "flowstate (automatic)"
385
+ # `flowstate erase` drops the list (ids, digest, hashes) of a clean-up about an erased record
386
+ # and leaves `bound_erased` (erase.py, task 75): approving it changes nothing, as for any change
387
+ ERASED_WHY = "a record on its list was erased"
388
+ _VERBS = (("rows", "lists"),)
389
+ NONE_LEFT = "none (no record on its list is still there)" # e.g. its only record was erased
390
+ _TABLE = {"todo": "todos", "learning": "learnings", "problem": "problems", "change": "changes"}
391
+
392
+
393
+ def _targets(conn, payload: dict) -> Optional[dict]:
394
+ """The rows approving this suggestion would change, as they are now ({(table, id): row});
395
+ a move also lists the record's links, a duplicate the todo it keeps. None: it changes
396
+ nothing (a duplicate of learnings queued by an older version is only noted)."""
397
+ kind, recs = payload.get("type"), payload.get("records") or []
398
+ if not recs:
399
+ return None
400
+ if kind == "misfiled":
401
+ rkind, rid = recs[0]
402
+ keys = [(_TABLE.get(rkind), rid)]
403
+ if links.available(conn):
404
+ keys += [("record_links", r[0]) for r in conn.execute(
405
+ "SELECT id FROM record_links WHERE (from_type=? AND from_id=?) OR "
406
+ "(to_type=? AND to_id=?)", (rkind, rid, rkind, rid))]
407
+ elif kind in ("duplicate", "stale"):
408
+ if recs[-1][0] != "todo":
409
+ return None
410
+ keys = [("todos", rid) for rk, rid in recs if rk == "todo"]
411
+ else:
412
+ return None
413
+ if keys[0][0] is None:
414
+ return None
415
+ out = {}
416
+ for t, k in keys:
417
+ row = history._row(conn, t, k)
418
+ if row is not None:
419
+ out[(t, k)] = row
420
+ return out
421
+
422
+
423
+ def bind(conn, payload: dict) -> Optional[dict]:
424
+ """The exact list for a suggestion (ids and hashes, no text), or None if it changes nothing."""
425
+ from . import deletes
426
+ rows = _targets(conn, payload)
427
+ return None if rows is None else deletes.bind(rows)
428
+
429
+
430
+ def _check(conn, payload: dict) -> None:
431
+ """Refuse (deletes.DeleteError, closes the item) unless the rows approving this would
432
+ change are exactly the ones listed when it was queued. A no-op clean-up passes."""
433
+ from . import deletes
434
+ now = bind(conn, payload)
435
+ if now is None:
436
+ return
437
+ then = payload.get("bound")
438
+ if payload.get("bound_erased"):
439
+ raise deletes.DeleteError(
440
+ "changed_since_request", f"What this clean-up would change is not what it was "
441
+ f"suggested with ({ERASED_WHY}). Nothing was changed and the suggestion is closed; "
442
+ "run the clean-up again (manage_memory action=\"cleanup\") to get a new one.")
443
+ if not isinstance(then, dict) or not then.get("digest"):
444
+ raise deletes.DeleteError(
445
+ "request_outdated", "This clean-up suggestion was queued by an older FlowState and "
446
+ "isn't tied to an exact list of records, so it was closed. Nothing was changed; run "
447
+ "the clean-up again (manage_memory action=\"cleanup\") to get a new suggestion.")
448
+ if now["digest"] != then["digest"]:
449
+ raise deletes.DeleteError(
450
+ "changed_since_request", "What this clean-up would change is not what it was "
451
+ f"suggested with ({deletes._bound_diff(then, now, _VERBS)}). Nothing was changed "
452
+ "and the suggestion is closed; run the clean-up again (manage_memory "
453
+ "action=\"cleanup\") to get a new one.")
454
+
455
+
456
+ def _role(kind: str, table: str, rid, recs: list) -> str:
457
+ if table == "record_links":
458
+ return "moves with it"
459
+ if kind == "misfiled":
460
+ return "moves"
461
+ if kind == "duplicate" and len(recs) > 1 and rid == recs[0][1]:
462
+ return "kept"
463
+ return "cancelled"
464
+
465
+
466
+ def preview(db_path: Path, item: dict) -> Optional[dict]:
467
+ """The exact list for the review and phone pages, from the database: each record (id, a
468
+ short title from the live record, what happens to it), and whether it still matches the
469
+ list the suggestion was made with ('text': the list and any warning; 'listed': the list
470
+ alone; 'warning': the warning alone). None for a clean-up that changes nothing. A record
471
+ that is gone (deleted or erased) is shown by id only."""
472
+ from . import deletes
473
+ try:
474
+ payload = json.loads(item.get("payload") or "{}")
475
+ except ValueError:
476
+ return None
477
+ conn = links.connect(db_path)
478
+ try:
479
+ now_rows = _targets(conn, payload)
480
+ if now_rows is None:
481
+ return None
482
+ now = deletes.bind(now_rows)
483
+ then = payload.get("bound") if isinstance(payload.get("bound"), dict) else None
484
+ keys = {(t, k) for t, ks in ((then or {}).get("rows") or {}).items() for k in ks}
485
+ keys |= set(now_rows)
486
+ recs = payload.get("records") or []
487
+ lines = []
488
+ for t, k in sorted(keys, key=lambda x: (x[0] == "record_links", x[0], str(x[1]))):
489
+ name = deletes._NAMED.get(t, t)
490
+ if (t, k) not in now_rows:
491
+ lines.append(f"{name} #{k} (no longer there)")
492
+ continue
493
+ title = None if t == "record_links" else links.label(conn, name, k)
494
+ lines.append(f"{name} #{k}" + (f' "{_short(title, TITLE_MAX)}"' if title else "")
495
+ + f": {_role(payload.get('type'), t, k, recs)}")
496
+ finally:
497
+ conn.close()
498
+ stale = then is None or then.get("digest") != now["digest"]
499
+ lines = lines or [NONE_LEFT]
500
+ listed = "Approving changes exactly these records: " + "; ".join(lines) + "."
501
+ text, warning = listed, None
502
+ if stale:
503
+ why = deletes._bound_diff(then, now, _VERBS) if then else \
504
+ ERASED_WHY if payload.get("bound_erased") else "queued by an older FlowState"
505
+ warning = (f"This list is not the one the suggestion was made with ({why}). Approving it "
506
+ "changes nothing; run the clean-up again for a new suggestion.")
507
+ text += " " + warning
508
+ return {"lines": lines, "changed_since_request": stale, "text": text, "warning": warning,
509
+ "listed": listed}
510
+
511
+
512
+ def html_for(db_path: Path, it: dict) -> str:
513
+ """The exact list as escaped HTML for the review page ('' for a no-op clean-up)."""
514
+ import html
515
+ got = preview(db_path, it)
516
+ if not got:
517
+ return ""
518
+ out = ("<p class='meta'>Approving changes exactly these records:</p><ul>"
519
+ + "".join(f"<li>{html.escape(x)}</li>" for x in got["lines"]) + "</ul>")
520
+ if got["warning"]:
521
+ out += f"<p><strong>{html.escape(got['warning'])}</strong></p>"
522
+ return out
523
+
524
+
525
+ # ---------------------------------------------------------------- apply (on approval)
526
+ def _component_in(conn, pid: int, name: Optional[str], client: str) -> int:
527
+ if name:
528
+ cid = links.find_component(conn, pid, name)
529
+ if cid:
530
+ return cid
531
+ row = conn.execute("SELECT id FROM components WHERE project_id = ? AND lower(name) = 'general'",
532
+ (pid,)).fetchone()
533
+ if row:
534
+ return row[0]
535
+ cur = conn.execute("INSERT INTO components (project_id, name, description) VALUES (?, 'General', ?)",
536
+ (pid, "Created by FlowState clean-up"))
537
+ return cur.lastrowid
538
+
539
+
540
+ _MOVE_ROWS = {
541
+ "todo": [("todos", "id")], "learning": [("learnings", "id")],
542
+ "problem": [("problems", "id")], "change": [("changes", "id")],
543
+ }
544
+
545
+
546
+ def apply(db_path: Path, item: dict, client: str, move_to: Optional[int] = None) -> tuple[str, Optional[int]]:
547
+ """Carry out one approved suggestion. Returns (table, id) of what changed."""
548
+ payload = json.loads(item.get("payload") or "{}")
549
+ kind = payload.get("type")
550
+ recs = payload.get("records") or []
551
+ if kind == "misfiled":
552
+ rkind, rid = recs[0]
553
+ target = move_to or payload.get("target_project_id")
554
+ conn = links.connect(db_path)
555
+ try:
556
+ _check(conn, payload) # the listed rows, or nothing (again inside the write)
557
+ if links.owner(conn, rkind, rid) is None:
558
+ raise review.ReviewError("record_not_found", f"{rkind} #{rid} no longer exists.")
559
+ if conn.execute("SELECT 1 FROM projects WHERE id = ?", (target,)).fetchone() is None:
560
+ raise review.ReviewError("project_not_found", f"No project with id {target}.")
561
+ link_ids = [r[0] for r in conn.execute(
562
+ """SELECT id FROM record_links WHERE (from_type=? AND from_id=?) OR (to_type=? AND to_id=?)""",
563
+ (rkind, rid, rkind, rid))] if links.available(conn) else []
564
+ finally:
565
+ conn.close()
566
+ # (a General component created in the target is not part of the undo: other records
567
+ # may use it later, and undo must never delete something they depend on)
568
+ rows = [(t, k, rid) for t, k in _MOVE_ROWS[rkind]] + [("record_links", "id", lid) for lid in link_ids]
569
+ with history.tracked(db_path, rows, "cleanup/move", client):
570
+ conn = links.connect(db_path)
571
+ try:
572
+ conn.execute("BEGIN IMMEDIATE")
573
+ _check(conn, payload)
574
+ if rkind == "todo":
575
+ conn.execute("UPDATE todos SET project_id = ?, component_id = NULL WHERE id = ?", (target, rid))
576
+ elif rkind == "learning":
577
+ conn.execute("UPDATE learnings SET project_id = ?, component_id = NULL WHERE id = ?", (target, rid))
578
+ else:
579
+ table = "problems" if rkind == "problem" else "changes"
580
+ old = conn.execute(f"SELECT c.name FROM {table} x JOIN components c ON c.id = x.component_id "
581
+ f"WHERE x.id = ?", (rid,)).fetchone()
582
+ cid = _component_in(conn, target, old[0] if old else None, client)
583
+ conn.execute(f"UPDATE {table} SET component_id = ? WHERE id = ?", (cid, rid))
584
+ for lid in link_ids:
585
+ conn.execute("""UPDATE record_links SET
586
+ from_project_id = CASE WHEN from_type=? AND from_id=? THEN ? ELSE from_project_id END,
587
+ to_project_id = CASE WHEN to_type=? AND to_id=? THEN ? ELSE to_project_id END
588
+ WHERE id = ?""", (rkind, rid, target, rkind, rid, target, lid))
589
+ conn.commit()
590
+ except Exception:
591
+ conn.rollback()
592
+ raise
593
+ finally:
594
+ conn.close()
595
+ return {"todo": "todos", "learning": "learnings", "problem": "problems", "change": "changes"}[rkind], rid
596
+ if kind in ("duplicate", "stale"):
597
+ rkind, rid = recs[-1] # the newer duplicate / the stale todo
598
+ if rkind != "todo":
599
+ return "none", None # noted only
600
+ conn = links.connect(db_path)
601
+ try:
602
+ _check(conn, payload) # the listed rows, or nothing (again inside the write)
603
+ finally:
604
+ conn.close()
605
+ with history.tracked(db_path, [("todos", "id", rid)], f"cleanup/{kind}", client):
606
+ conn = links.connect(db_path)
607
+ try:
608
+ conn.execute("BEGIN IMMEDIATE")
609
+ _check(conn, payload)
610
+ conn.execute("UPDATE todos SET status = 'cancelled' WHERE id = ? AND status IN "
611
+ "('pending', 'in_progress', 'blocked')", (rid,))
612
+ conn.commit()
613
+ except Exception:
614
+ conn.rollback()
615
+ raise
616
+ finally:
617
+ conn.close()
618
+ return "todos", rid
619
+ raise review.ReviewError("bad_kind", f"Unknown clean-up suggestion {kind!r}.")