@yahyahammad/venastine 0.2.0 → 0.3.9

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 (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -0,0 +1,749 @@
1
+ """config_update.py -- keeping an edited `config.yaml` across an npm update.
2
+
3
+ THE PROBLEM, STATED PRECISELY. `config.yaml` ships INSIDE the package --
4
+ `config_schema.HARNESS_ROOT` resolves from `__file__`, and `package.json`'s
5
+ `files` list carries the file into the tarball. npm replaces a package
6
+ directory wholesale on update: it does not merge, and it has no notion of a
7
+ file the user was meant to edit. So `npm update -g` silently discarded every
8
+ value the user had set and handed them the new version's defaults.
9
+
10
+ WHY THE FIX IS A MERGE AND NOT A MOVE. CONFIG_ARCHITECTURE.md's *One
11
+ location, and no override variable* locks one path with no user tier, no
12
+ project tier and no redirect variable, and the security argument behind that
13
+ lock is untouched by this problem: a `settings.json` key can be set by a
14
+ directory you cloned, a file inside the harness cannot. Moving the live file
15
+ to the home directory would trade a packaging annoyance for that property.
16
+ So the live file stays exactly where it was, and this module puts the user's
17
+ values back into it after npm has overwritten it.
18
+
19
+ WHY NOT A JOURNAL OF `/config` WRITES, which would be half the code. Because
20
+ `/config` cannot write containers at all -- they are view-only by design --
21
+ while README.md sends people to the file BY HAND for exactly those:
22
+ `ensemble_models`, `domain_authority_classes`, `similarity_calibration`,
23
+ `persist_source_text`. A record of what `/config` did would lose the keys the
24
+ documentation tells people to edit by hand. The merge has to work from the
25
+ file's whole content, which is why a pristine copy is kept to diff against.
26
+
27
+ THE THREE-WAY MERGE. `~/.config/venastine/config-state/` holds `version`,
28
+ `shipped.yaml` (the pristine `config.yaml` of that version) and `yours.yaml`
29
+ (the user's, mirrored at each launch and each exit). Deviations are `yours`
30
+ against `shipped`, and they are re-applied onto the newly shipped file. Keys
31
+ the user never touched therefore adopt the new version's defaults, and keys
32
+ the new version ADDS are simply already present -- that half needs no code at
33
+ all, which is what makes this the right shape.
34
+
35
+ FOUR RULES, all of them load-bearing.
36
+
37
+ 1. THE MIRROR IS REFRESHED ONLY WHEN THE VERSION STILL MATCHES. Copying
38
+ `config.yaml` over `yours.yaml` before the version check would overwrite
39
+ the mirror with the file npm just replaced, destroying the very edits this
40
+ exists to preserve. `_reconcile` checks the version first, always, and the
41
+ launcher's post-session copy runs only after this module has re-recorded
42
+ it.
43
+
44
+ 2. THE LAUNCH NEVER FAILS BECAUSE OF THIS. An unwritable `config.yaml` in a
45
+ root-owned global prefix, a corrupt state directory, a `yours.yaml` that
46
+ no longer parses: `reconcile()` catches everything and reports it.
47
+ `main()` returns 0 whatever happened. A configuration-history feature must
48
+ not be able to stop the harness from starting.
49
+
50
+ 3. THE CHEAP PATH IMPORTS NOTHING FIRST-PARTY. Measured: a bare interpreter
51
+ starts in 79ms on this machine and `import config_schema` takes 373ms,
52
+ because it pulls pydantic and ruamel. This module runs on EVERY launch and
53
+ does nothing on almost all of them, so the version check and the byte
54
+ comparison are stdlib only, and `config_edit` is imported inside the merge
55
+ branch. `LIVE` is derived here rather than read from `config_schema` for
56
+ that reason alone, and `test_the_two_modules_agree_about_where_the_file_is`
57
+ pins the two expressions together.
58
+
59
+ 4. A CHECKOUT IS A NO-OP. A contributor running `node bin/venastine.mjs` to
60
+ test the launcher must not have the tracked `config.yaml` rewritten from a
61
+ mirror of their own edits. A `.git` beside the live file means git is
62
+ already managing this file and nothing here should.
63
+ """
64
+
65
+ from __future__ import annotations
66
+
67
+ import dataclasses
68
+ import hashlib
69
+ import json
70
+ import os
71
+ import shutil
72
+ import sys
73
+ from typing import Any, Optional
74
+
75
+ # ---------------------------------------------------------------------------
76
+ # ---- Where things are -----------------------------------------------------
77
+ # ---------------------------------------------------------------------------
78
+
79
+ #: The live document. The same expression `config_schema` uses, restated here
80
+ #: rather than imported -- see rule 3. A test holds the two together.
81
+ LIVE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "config.yaml")
82
+
83
+ #: `~/.config/venastine` ON EVERY PLATFORM, Windows included. Not %APPDATA%:
84
+ #: `core/config_loader.py`, `mcp_client/config.py`, `core/workspace_trust.py`
85
+ #: and `bin/venastine.mjs` all resolve the user tier this way, and splitting
86
+ #: one configuration directory across two locations by platform is the bug
87
+ #: that convention exists to avoid.
88
+ CONFIG_HOME = os.path.join(os.path.expanduser("~"), ".config", "venastine")
89
+
90
+ #: The base under `CONFIG_HOME`. Every install gets a SUBDIRECTORY of it.
91
+ STATE_DIRNAME = "config-state"
92
+
93
+ VERSION_FILE = "version"
94
+ SHIPPED_FILE = "shipped.yaml"
95
+ YOURS_FILE = "yours.yaml"
96
+ REPORT_FILE = "last-update.txt"
97
+ SEEN_FILE = "last-update.seen"
98
+ INSTALLS_FILE = "installs.json"
99
+
100
+
101
+ def state_base() -> str:
102
+ """`~/.config/venastine/config-state`, beside `runtime/` and `app.db`."""
103
+ return os.path.join(CONFIG_HOME, STATE_DIRNAME)
104
+
105
+
106
+ def install_slug(live: Optional[str] = None) -> str:
107
+ """A short, stable name for the install the live document belongs to.
108
+
109
+ KEYED BY THE INSTALL, the way `runtimePaths()` in the launcher is already
110
+ keyed by version and requirements hash. The state directory is global
111
+ while `config.yaml` is not, so one flat directory made a global npm
112
+ install, a local one and a checkout share a single mirror -- and
113
+ whichever ran last overwrote the others' saved settings with its own
114
+ file.
115
+
116
+ Computed HERE AND NOWHERE ELSE. The launcher used to spell these paths
117
+ itself, and two languages agreeing about a hash by inspection is a bug
118
+ waiting for a path separator to change: a mismatch would not raise, it
119
+ would silently write the mirror somewhere the merge never reads.
120
+ `installs.json` is how the launcher finds this without recomputing it.
121
+ """
122
+ root = os.path.realpath(os.path.dirname(live or LIVE))
123
+ return hashlib.sha256(root.encode("utf-8")).hexdigest()[:12]
124
+
125
+
126
+ def state_dir(live: Optional[str] = None) -> str:
127
+ """This install's own state directory."""
128
+ return os.path.join(state_base(), install_slug(live))
129
+
130
+
131
+ def _record_install(live: str) -> None:
132
+ """Note which install a slug belongs to, for the launcher and for humans.
133
+
134
+ `--venastine-doctor` returns before `ensureRuntime()`, so there may be no
135
+ interpreter to ask which directory is in force; and a directory of hashes
136
+ is unreadable to whoever opens it wondering what is stored about them.
137
+ """
138
+ base = state_base()
139
+ path = os.path.join(base, INSTALLS_FILE)
140
+ try:
141
+ with open(path, encoding="utf-8") as handle:
142
+ known = json.load(handle)
143
+ if not isinstance(known, dict):
144
+ known = {}
145
+ except (OSError, ValueError):
146
+ known = {}
147
+ known[os.path.realpath(os.path.dirname(live))] = install_slug(live)
148
+ os.makedirs(base, exist_ok=True)
149
+ with open(path, "w", encoding="utf-8") as handle:
150
+ json.dump(known, handle, indent=2, sort_keys=True)
151
+
152
+
153
+ def package_version(live: Optional[str] = None) -> str:
154
+ """The npm version beside the live document, or `""` if there is none.
155
+
156
+ Derived from the live file rather than from `__file__` so that a test can
157
+ plant a `package.json` next to a redirected `config.yaml` and drive a
158
+ version bump without touching the repository's own.
159
+ """
160
+ path = os.path.join(os.path.dirname(live or LIVE), "package.json")
161
+ try:
162
+ with open(path, encoding="utf-8") as handle:
163
+ return str(json.load(handle).get("version", ""))
164
+ except (OSError, ValueError):
165
+ return ""
166
+
167
+
168
+ # ---------------------------------------------------------------------------
169
+ # ---- What happened --------------------------------------------------------
170
+ # ---------------------------------------------------------------------------
171
+
172
+ #: `action` values. `mirrored` and `skipped` are the silent ones.
173
+ ACTIONS = ("adopted", "updated", "reinstalled", "mirrored", "skipped", "failed")
174
+
175
+
176
+ @dataclasses.dataclass
177
+ class Report:
178
+ """What `reconcile()` did, for the console and for `last-update.txt`.
179
+
180
+ Carries the KEYS, not a rendered blob, because two consumers want
181
+ different amounts of it: the console gets a summary that must survive a
182
+ cp1252 terminal, and the file gets everything in UTF-8.
183
+ """
184
+
185
+ action: str
186
+ detail: str = ""
187
+ #: `(name, value, authority)` for each value put back.
188
+ restored: list = dataclasses.field(default_factory=list)
189
+ #: `(name, value, why)` for each value that could not be.
190
+ dropped: list = dataclasses.field(default_factory=list)
191
+ #: Names whose shipped default ALSO changed in this version.
192
+ overridden: list = dataclasses.field(default_factory=list)
193
+ #: Names this version adds, which arrive at their own defaults.
194
+ added: list = dataclasses.field(default_factory=list)
195
+ note: str = ""
196
+
197
+ @property
198
+ def quiet(self) -> bool:
199
+ """True when there is nothing a person needs to be told.
200
+
201
+ An update that carried nothing is the ORDINARY case -- most people
202
+ never change a setting -- and announcing "your settings were merged
203
+ back in, 0 of them" at every launch after every update is noise that
204
+ teaches people to ignore the one time it matters.
205
+ """
206
+ if self.action in ("mirrored", "skipped"):
207
+ return True
208
+ if self.action in ("updated", "reinstalled"):
209
+ return not (self.restored or self.dropped)
210
+ return False
211
+
212
+ def lines(self) -> list[str]:
213
+ """The report, one line per fact. ASCII only -- see `_say`."""
214
+ if self.quiet:
215
+ return []
216
+ if self.action == "failed":
217
+ return [f"venastine: could not restore your config.yaml settings "
218
+ f"({self.note}). config.yaml was left as the update "
219
+ f"shipped it."]
220
+ if self.action == "adopted":
221
+ return [f"venastine: now tracking your config.yaml so an update "
222
+ f"cannot overwrite it ({self.note})."] if self.note else []
223
+
224
+ head = ("venastine: this update replaced config.yaml; your settings "
225
+ "were merged back in.")
226
+ if self.action == "reinstalled":
227
+ head = ("venastine: config.yaml was back at its shipped defaults; "
228
+ "your settings were put back.")
229
+ out = [head, f" version : {self.detail}"]
230
+ authority = [name for name, _, marked in self.restored if marked]
231
+ out.append(f" kept : {len(self.restored)} of your settings"
232
+ + (f", {len(authority)} of them AUTHORITY"
233
+ if authority else ""))
234
+ for name, value, marked in self.restored:
235
+ out.append(f" {name} = {_short(value)}"
236
+ + (" [AUTHORITY]" if marked else "")
237
+ + (" (this version changed its default too)"
238
+ if name in self.overridden else ""))
239
+ if self.dropped:
240
+ out.append(f" dropped : {len(self.dropped)}")
241
+ for name, value, why in self.dropped:
242
+ out.append(f" {name} = {_short(value)} ({why})")
243
+ if self.added:
244
+ out.append(f" new : {len(self.added)} setting(s) this "
245
+ f"version adds, at their shipped defaults")
246
+ if self.action == "reinstalled":
247
+ # A re-extracted package and a deliberate revert to the defaults
248
+ # look identical from here -- both leave config.yaml matching the
249
+ # recorded pristine while the mirror still holds the edits. The
250
+ # ambiguity cannot be resolved, so it is named instead of hidden.
251
+ out.append(" If you reset config.yaml on purpose, set the values "
252
+ "again with /config, or delete the yours.yaml named "
253
+ "by --venastine-doctor.")
254
+ return out
255
+
256
+
257
+ def _short(value: Any, cap: int = 60) -> str:
258
+ """A value for one report line, never wider than `cap`.
259
+
260
+ `config_edit.shown` is the richer version and is not reachable here: this
261
+ runs on the failure paths too, where importing it may be exactly what
262
+ went wrong.
263
+ """
264
+ if isinstance(value, (list, tuple, set, frozenset)):
265
+ return f"{len(value)} entries"
266
+ if isinstance(value, dict):
267
+ return f"{len(value)} entries"
268
+ text = repr(value) if isinstance(value, str) else str(value)
269
+ return text if len(text) <= cap else text[:cap - 3] + "..."
270
+
271
+
272
+ # ---------------------------------------------------------------------------
273
+ # ---- The diff -------------------------------------------------------------
274
+ # ---------------------------------------------------------------------------
275
+
276
+ def _tables() -> tuple:
277
+ """`config_edit.TABLES`, imported late. See rule 3."""
278
+ import config_edit
279
+ return config_edit.TABLES
280
+
281
+
282
+ def leaves(document: dict, tables: Optional[tuple] = None) -> dict:
283
+ """Every addressable name in a raw document, dotted for the two tables.
284
+
285
+ The same address space `config_edit.catalogue()` builds and
286
+ `config_edit.file_value()` reads, so a name produced here can be handed
287
+ straight to the writer. `tool_permissions` and `tool_approvals` are
288
+ expanded because their leaves are what a person sets; every other mapping
289
+ -- `compaction_target_ratios`, `similarity_calibration` -- is ONE value,
290
+ for the reason the container decision gives: entry-by-entry merging
291
+ cannot tell a deletion the user made from an entry the new version added.
292
+ """
293
+ tables = _tables() if tables is None else tables
294
+ flat = {}
295
+ for name, value in document.items():
296
+ if name in tables and isinstance(value, dict):
297
+ for leaf, inner in value.items():
298
+ flat[f"{name}.{leaf}"] = inner
299
+ else:
300
+ flat[name] = value
301
+ return flat
302
+
303
+
304
+ def deviations(yours: dict, shipped: Optional[dict],
305
+ tables: Optional[tuple] = None) -> dict:
306
+ """What the user changed: `{dotted name: value}`.
307
+
308
+ `shipped=None` IS THE ADOPTION FALLBACK, and it is a different question
309
+ rather than a missing answer. An install that was already running before
310
+ this module existed has no pristine copy on record, so nothing can say
311
+ which of its values were chosen and which were shipped. Returning the
312
+ whole file keeps every one of them, which is the right trade against
313
+ losing a setting somebody deliberately made.
314
+
315
+ STATE THE COST PROPERLY, because "one update where a changed default
316
+ does not reach you" understates it. Every default that changed during
317
+ that one update is captured here as a deviation, so it is re-applied by
318
+ EVERY later merge too -- the user is pinned to their pre-adoption
319
+ defaults for those keys until they set them again. What self-heals is
320
+ the baseline, not the values: the merge records a real `shipped.yaml` on
321
+ its way out, so no FURTHER keys are captured this way.
322
+ """
323
+ mine = leaves(yours, tables)
324
+ if shipped is None:
325
+ return dict(mine)
326
+ theirs = leaves(shipped, tables)
327
+ return {name: value for name, value in mine.items()
328
+ if name not in theirs or theirs[name] != value}
329
+
330
+
331
+ # ---------------------------------------------------------------------------
332
+ # ---- The merge ------------------------------------------------------------
333
+ # ---------------------------------------------------------------------------
334
+
335
+ def _set(tree, name: str, value: Any) -> None:
336
+ """Set a dotted name on a round-trip tree. `propose()`'s own two lines."""
337
+ if "." in name:
338
+ table, leaf = name.split(".", 1)
339
+ tree[table][leaf] = value
340
+ else:
341
+ tree[name] = value
342
+
343
+
344
+ def _place(tree, name: str, value: Any) -> None:
345
+ """`config_edit.place`, which is where this logic now lives.
346
+
347
+ It started here, for the container half; then `propose()` turned out to
348
+ need the same thing for the shape half, and two writers with one rule
349
+ between them is how a rule drifts. `config_edit` owns the round trip, so
350
+ it owns this.
351
+ """
352
+ import config_edit
353
+ config_edit.place(tree, name, value)
354
+
355
+
356
+ def _get(tree, name: str):
357
+ if "." in name:
358
+ table, leaf = name.split(".", 1)
359
+ return tree[table][leaf]
360
+ return tree[name]
361
+
362
+
363
+ def _validates(text: str, live: str) -> Optional[str]:
364
+ """None if `text` would start the harness, else why it would not.
365
+
366
+ THE BYTES, not the tree, for `config_edit`'s rule 1: the round-trip
367
+ parser hands back its own scalar types and what the next launch reads is
368
+ a file. Validated with no environment overlay, because `load(path=...)`
369
+ is the seam that judges a candidate on its own -- the environment the
370
+ next launch runs under is not knowable now.
371
+ """
372
+ import tempfile
373
+
374
+ import config_schema
375
+
376
+ # BESIDE `config.yaml` when that is possible, for the reason
377
+ # `config_edit._validate_candidate` gives: the same filesystem as the
378
+ # write that may follow, and no environment variable can redirect it.
379
+ # FALLING BACK when it is not, which that caller never has to do. A
380
+ # global npm prefix owned by root is an ordinary install, and there every
381
+ # candidate would fail to be WRITTEN and come back reported as rejected
382
+ # by the schema -- a lie, with the honest failure (the write) never
383
+ # reached.
384
+ try:
385
+ handle = tempfile.NamedTemporaryFile(
386
+ "w", suffix=".yaml", delete=False, encoding="utf-8",
387
+ dir=os.path.dirname(live) or None)
388
+ except OSError:
389
+ handle = tempfile.NamedTemporaryFile(
390
+ "w", suffix=".yaml", delete=False, encoding="utf-8")
391
+ try:
392
+ handle.write(text)
393
+ handle.close()
394
+ config_schema.load(path=handle.name)
395
+ return None
396
+ except Exception as exc: # noqa: BLE001 -- reported
397
+ return str(exc).split("\n")[0]
398
+ finally:
399
+ try:
400
+ os.unlink(handle.name)
401
+ except OSError:
402
+ pass
403
+
404
+
405
+ def merge(wanted: dict, live: str) -> tuple[str, str, list, list]:
406
+ """Apply `wanted` to the live document. `(text, newline, kept, dropped)`.
407
+
408
+ BATCHED, THEN WALKED. The common case is that every value still fits the
409
+ new schema, and that costs ONE validation. Only when the batch fails does
410
+ this re-apply them one at a time, keeping what validates and dropping
411
+ what does not -- which is how a single key whose `Literal` lost an option
412
+ costs the user that key rather than every edit they ever made.
413
+
414
+ The walk restores the PRISTINE NODE rather than a plain Python value when
415
+ it backs a key out. ruamel hands back its own scalar types, and putting
416
+ an equal `str` where a `SingleQuotedScalarString` was would re-quote the
417
+ line -- a write that silently reformats a line it was not asked to touch.
418
+ """
419
+ import config_edit
420
+ import config_schema
421
+
422
+ if os.path.abspath(config_schema.CONFIG_PATH) != os.path.abspath(live):
423
+ # The writer reads `config_schema.CONFIG_PATH`; a test that redirects
424
+ # only one of the two would otherwise merge one file and write
425
+ # another, with nothing raising.
426
+ raise ValueError(
427
+ f"config_schema.CONFIG_PATH ({config_schema.CONFIG_PATH}) and the "
428
+ f"file being merged ({live}) disagree. Redirect both.")
429
+
430
+ text, newline = config_edit.read_text()
431
+ tree = config_edit.document(fresh=True)
432
+ present = leaves(config_schema.read_document(live))
433
+
434
+ kept, dropped = [], []
435
+ candidates = {}
436
+ for name, value in wanted.items():
437
+ if name not in present:
438
+ dropped.append((name, value, "not a setting in this version"))
439
+ elif present[name] != value:
440
+ candidates[name] = value
441
+
442
+ if not candidates:
443
+ return text, newline, kept, dropped
444
+
445
+ pristine = {name: _get(tree, name) for name in candidates}
446
+ for name, value in candidates.items():
447
+ _place(tree, name, value)
448
+ candidate_text = config_edit._dump(tree)
449
+
450
+ if _validates(candidate_text, live) is not None:
451
+ for name, node in pristine.items():
452
+ _set(tree, name, node)
453
+ for name, value in candidates.items():
454
+ _place(tree, name, value)
455
+ trial = config_edit._dump(tree)
456
+ problem = _validates(trial, live)
457
+ if problem is None:
458
+ continue
459
+ _set(tree, name, pristine[name])
460
+ dropped.append((name, value, "rejected by this version"))
461
+ candidate_text = config_edit._dump(tree)
462
+
463
+ # `tool_permissions.shell` is an authority key because `tool_permissions`
464
+ # is one: the nine name whole settings, and a table's leaf carries its
465
+ # table's standing.
466
+ authority = config_schema.HARNESS_AUTHORITY_KEYS
467
+ dropped_names = {name for name, _, _ in dropped}
468
+ for name, value in candidates.items():
469
+ if name not in dropped_names:
470
+ kept.append((name, value, name.split(".")[0] in authority))
471
+ return candidate_text, newline, kept, dropped
472
+
473
+
474
+ # ---------------------------------------------------------------------------
475
+ # ---- The launch-time decision ---------------------------------------------
476
+ # ---------------------------------------------------------------------------
477
+
478
+ def _read(path: str) -> Optional[str]:
479
+ try:
480
+ with open(path, encoding="utf-8") as handle:
481
+ return handle.read()
482
+ except OSError:
483
+ return None
484
+
485
+
486
+ def _write(path: str, text: str) -> None:
487
+ os.makedirs(os.path.dirname(path), exist_ok=True)
488
+ with open(path, "w", encoding="utf-8") as handle:
489
+ handle.write(text)
490
+
491
+
492
+ def _same_bytes(one: str, two: str) -> bool:
493
+ try:
494
+ if os.path.getsize(one) != os.path.getsize(two):
495
+ return False
496
+ with open(one, "rb") as a, open(two, "rb") as b:
497
+ return a.read() == b.read()
498
+ except OSError:
499
+ return False
500
+
501
+
502
+ def reconcile(state: Optional[str] = None, first_run: bool = False,
503
+ live: Optional[str] = None) -> Report:
504
+ """Decide what the launch needs and do it. Never raises -- see rule 2."""
505
+ live = live or LIVE
506
+ state = state or state_dir(live)
507
+ try:
508
+ return _reconcile(state, first_run, live)
509
+ except Exception as exc: # noqa: BLE001 -- rule 2
510
+ return Report(action="failed", note=f"{type(exc).__name__}: {exc}")
511
+
512
+
513
+ def _is_checkout(live: str) -> bool:
514
+ """True when git is already managing the live document.
515
+
516
+ `exists`, NOT `isdir`. A linked worktree (`git worktree add`) and a
517
+ submodule both carry a `.git` FILE holding `gitdir: ...`, so the
518
+ directory test read False in exactly the setup a contributor uses to
519
+ test the launcher -- and rule 4 then did not fire, leaving the
520
+ reconciler free to rewrite a tracked file from a mirror.
521
+ """
522
+ return os.path.exists(os.path.join(os.path.dirname(live), ".git"))
523
+
524
+
525
+ def mirror(state: Optional[str] = None,
526
+ live: Optional[str] = None) -> Report:
527
+ """Copy the live document into the mirror. The POST-SESSION half.
528
+
529
+ `bin/venastine.mjs` used to do this itself, in four lines that looked
530
+ too small to be wrong, and it was the one writer not subject to rule 1:
531
+ it copied whenever a `version` file existed. So a merge that FAILED --
532
+ which correctly leaves the version and the mirror untouched so the next
533
+ launch can retry -- was followed at session end by the new pristine file
534
+ being copied over the mirror. The user's settings were then gone from
535
+ every copy, and the retry found nothing to restore.
536
+
537
+ Here instead, behind the same guards as the launch path, in the language
538
+ that has tests. It costs an interpreter start at session EXIT, where
539
+ nothing is waiting on it.
540
+ """
541
+ live = live or LIVE
542
+ state = state or state_dir(live)
543
+ try:
544
+ if _is_checkout(live) or not os.path.exists(live):
545
+ return Report(action="skipped", note="nothing to mirror")
546
+ recorded = _read(os.path.join(state, VERSION_FILE))
547
+ if recorded is None or recorded != package_version(live):
548
+ # RULE 1. An unrecorded or stale version means the file in front
549
+ # of us may be one npm has just written, and mirroring it would
550
+ # destroy the very edits the mirror exists to carry.
551
+ return Report(action="skipped", note="version is not current")
552
+ shutil.copyfile(live, os.path.join(state, YOURS_FILE))
553
+ return Report(action="mirrored", detail=recorded)
554
+ except Exception as exc: # noqa: BLE001 -- rule 2
555
+ return Report(action="failed", note=f"{type(exc).__name__}: {exc}")
556
+
557
+
558
+ def _reconcile(state: str, first_run: bool, live: str) -> Report:
559
+ if _is_checkout(live):
560
+ return Report(action="skipped", note="a checkout manages its own file")
561
+ if not os.path.exists(live):
562
+ return Report(action="skipped", note="no config.yaml to track")
563
+
564
+ version = package_version(live)
565
+ shipped = os.path.join(state, SHIPPED_FILE)
566
+ yours = os.path.join(state, YOURS_FILE)
567
+ recorded = _read(os.path.join(state, VERSION_FILE))
568
+
569
+ if recorded is None:
570
+ # FIRST ADOPTION. `shipped.yaml` is only honest when the launcher
571
+ # says this install has never been run -- otherwise the file in front
572
+ # of us may already carry edits, and recording it as pristine would
573
+ # make those edits the baseline and lose them at the next update.
574
+ os.makedirs(state, exist_ok=True)
575
+ shutil.copyfile(live, yours)
576
+ if first_run:
577
+ shutil.copyfile(live, shipped)
578
+ elif os.path.exists(shipped):
579
+ os.unlink(shipped)
580
+ _write(os.path.join(state, VERSION_FILE), version)
581
+ _record_install(live)
582
+ return Report(action="adopted", detail=version,
583
+ note="" if first_run else
584
+ "existing settings will be kept whole at the next "
585
+ "update")
586
+
587
+ if recorded == version:
588
+ reinstalled = (os.path.exists(shipped) and os.path.exists(yours)
589
+ and _same_bytes(live, shipped)
590
+ and not _same_bytes(yours, shipped))
591
+ if not reinstalled:
592
+ # THE ORDINARY LAUNCH. Mirror and nothing else -- and only here,
593
+ # after the version has been confirmed unchanged. See rule 1.
594
+ shutil.copyfile(live, yours)
595
+ return Report(action="mirrored", detail=version)
596
+ return _merge_into(state, live, version, version, "reinstalled")
597
+
598
+ return _merge_into(state, live, recorded, version, "updated")
599
+
600
+
601
+ def _merge_into(state: str, live: str, was: str, now: str,
602
+ action: str) -> Report:
603
+ """Put the user's values back into the file npm just wrote."""
604
+ import config_schema
605
+
606
+ yours_path = os.path.join(state, YOURS_FILE)
607
+ shipped_path = os.path.join(state, SHIPPED_FILE)
608
+
609
+ mine = config_schema.read_document(yours_path)
610
+ theirs = config_schema.read_document(live)
611
+ was_shipped = (config_schema.read_document(shipped_path)
612
+ if os.path.exists(shipped_path) else None)
613
+
614
+ wanted = deviations(mine, was_shipped)
615
+ text, newline, kept, dropped = merge(wanted, live)
616
+
617
+ old_leaves = leaves(was_shipped) if was_shipped is not None else {}
618
+ new_leaves = leaves(theirs)
619
+ overridden = [name for name, _, _ in kept
620
+ if name in old_leaves and old_leaves[name] != new_leaves.get(name)]
621
+ added = [name for name in new_leaves if name not in old_leaves] \
622
+ if was_shipped is not None else []
623
+
624
+ report = Report(action=action, detail=f"{was} -> {now}" if was != now
625
+ else now, restored=kept, dropped=dropped,
626
+ overridden=overridden, added=added)
627
+
628
+ # THE PRISTINE BYTES ARE HELD, NOT COMMITTED YET. They are what the next
629
+ # update diffs against, and the live file stops being pristine the moment
630
+ # the write lands -- but committing them BEFORE the write meant a write
631
+ # that raised left the baseline advanced while `version` still named the
632
+ # old release. The retry then diffed `yours` against the NEW pristine,
633
+ # read every default that changed between the two as a user edit, and
634
+ # pinned them forever on top of the original failure. Nothing is recorded
635
+ # until the write it describes has actually happened.
636
+ with open(live, "rb") as handle:
637
+ pristine = handle.read()
638
+
639
+ if kept:
640
+ import config_edit
641
+ config_edit.write(text, newline)
642
+
643
+ with open(shipped_path, "wb") as handle:
644
+ handle.write(pristine)
645
+ shutil.copyfile(live, yours_path)
646
+ _write(os.path.join(state, VERSION_FILE), now)
647
+ if not report.quiet:
648
+ # A quiet report used to leave a file holding one newline, which the
649
+ # launcher's doctor line then read as "last merged at <date>".
650
+ _write(os.path.join(state, REPORT_FILE),
651
+ "\n".join(report.lines()) + "\n")
652
+ _forget(os.path.join(state, SEEN_FILE))
653
+ _record_install(live)
654
+ return report
655
+
656
+
657
+ def _forget(path: str) -> None:
658
+ """Drop a marker file. Missing is the state it is being put into."""
659
+ try:
660
+ os.unlink(path)
661
+ except OSError:
662
+ pass # already missing, which is the state wanted
663
+
664
+
665
+ # ---------------------------------------------------------------------------
666
+ # ---- What the launcher runs -----------------------------------------------
667
+ # ---------------------------------------------------------------------------
668
+
669
+ def unseen_report(live: Optional[str] = None,
670
+ state: Optional[str] = None) -> list:
671
+ """The last merge report, if nothing has shown it to a person yet.
672
+
673
+ THE LAUNCHER'S PRINT DOES NOT REACH A TUI USER. `syncConfig` writes to
674
+ stdout immediately before `main.py` is spawned, and main.py's own #138
675
+ note states the rule it falls foul of: anything on stdout before Textual
676
+ takes the screen vanishes the moment it renders. The lines that vanish
677
+ are the ones that matter most -- a setting the user chose was dropped
678
+ because this version no longer accepts it.
679
+
680
+ So the report is also a file, and the session shows it where the user is
681
+ actually looking. `_merge_into` clears the seen marker when it writes a
682
+ new one; nothing else creates it, so "unseen" is simply its absence.
683
+ """
684
+ live = live or LIVE
685
+ state = state or state_dir(live)
686
+ try:
687
+ # Rule 4 again, and here it also keeps the SUITE out of the user's
688
+ # real state directory: `on_mount` calls this in every TUI test, and
689
+ # a checkout has no merge reports because the reconciler never ran
690
+ # for it.
691
+ if _is_checkout(live):
692
+ return []
693
+ if os.path.exists(os.path.join(state, SEEN_FILE)):
694
+ return []
695
+ text = _read(os.path.join(state, REPORT_FILE))
696
+ return text.rstrip("\n").split("\n") if text and text.strip() else []
697
+ except OSError:
698
+ return []
699
+
700
+
701
+ def mark_report_seen(live: Optional[str] = None,
702
+ state: Optional[str] = None) -> None:
703
+ """Record that a person has been shown the last merge report."""
704
+ live = live or LIVE
705
+ state = state or state_dir(live)
706
+ try:
707
+ if not _is_checkout(live) and os.path.isdir(state):
708
+ _write(os.path.join(state, SEEN_FILE), "")
709
+ except OSError:
710
+ # Nothing here may fail a launch -- rule 2. The cost of losing this
711
+ # is one report shown twice.
712
+ pass
713
+
714
+
715
+ def _say(line: str) -> None:
716
+ """Print a report line on a console that may not be UTF-8.
717
+
718
+ A Windows console is cp1252 here, and a report names VALUES the user
719
+ wrote -- a URL, a domain, a model name. An unencodable character would
720
+ raise `UnicodeEncodeError` out of `print`, which under rule 2 must not be
721
+ how a launch ends.
722
+ """
723
+ try:
724
+ print(line)
725
+ except UnicodeEncodeError:
726
+ print(line.encode("ascii", "replace").decode("ascii"))
727
+
728
+
729
+ def main(argv: Optional[list] = None) -> int:
730
+ """Always 0. The launcher ignores the status; this says why it may.
731
+
732
+ Two modes, both spawned by `bin/venastine.mjs`: the default runs before
733
+ the harness and merges, `--mirror` runs after the session and records
734
+ what it left behind. The launcher owns neither decision -- it used to
735
+ own the second one in four lines of its own, which is how the mirror
736
+ came to be written without the version check rule 1 requires.
737
+ """
738
+ argv = sys.argv[1:] if argv is None else argv
739
+ if "--mirror" in argv:
740
+ report = mirror()
741
+ else:
742
+ report = reconcile(first_run="--first-run" in argv)
743
+ for line in report.lines():
744
+ _say(line)
745
+ return 0
746
+
747
+
748
+ if __name__ == "__main__": # pragma: no cover
749
+ sys.exit(main())