@yahyahammad/venastine 0.3.8 → 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.
- package/.env.example +19 -19
- package/CONFIG_ARCHITECTURE.md +2030 -2002
- package/LICENSE +201 -201
- package/README.md +1034 -1034
- package/agents/builtin/compactor.md +75 -75
- package/agents/builtin/explore.md +77 -77
- package/agents/builtin/pipeline-reviewer.md +100 -100
- package/agents/builtin/plan.md +106 -106
- package/agents/builtin/review.md +74 -74
- package/agents/manager.py +261 -261
- package/agents/subagent_tool.py +472 -472
- package/agents/tui_commands.py +238 -146
- package/bin/venastine.mjs +528 -528
- package/bin/venastine.py +71 -71
- package/cli_commands.py +838 -835
- package/config.yaml +13 -0
- package/config_edit.py +1301 -1301
- package/config_schema.py +971 -966
- package/config_update.py +749 -749
- package/core/agent_activity.py +256 -256
- package/core/ansi.py +452 -452
- package/core/approval.py +137 -137
- package/core/call_view.py +364 -364
- package/core/cancel.py +121 -121
- package/core/chatgpt_auth.py +747 -747
- package/core/claims_view.py +107 -107
- package/core/client.py +2715 -2715
- package/core/commands.py +460 -454
- package/core/compaction.py +1735 -1735
- package/core/config_loader.py +1982 -1982
- package/core/connect.py +686 -686
- package/core/events.py +123 -123
- package/core/file_mentions.py +280 -280
- package/core/interaction.py +411 -411
- package/core/loop.py +2566 -2566
- package/core/memory.py +482 -482
- package/core/pipeline_models.py +190 -190
- package/core/provider_errors.py +234 -234
- package/core/reasoning/authorization.py +130 -130
- package/core/reasoning/base.py +219 -219
- package/core/reasoning/confidence_scoring.py +484 -484
- package/core/reasoning/events.py +149 -149
- package/core/reasoning/orchestrator.py +1561 -1561
- package/core/reasoning/output_writer.py +345 -345
- package/core/reasoning/payload_validation.py +524 -524
- package/core/reasoning/pipeline_storage.py +427 -427
- package/core/reasoning/scholar.py +458 -458
- package/core/reasoning/source_corpus.py +433 -433
- package/core/reasoning/source_scoring.py +855 -855
- package/core/replay.py +315 -315
- package/core/shell_sessions.py +1553 -1553
- package/credentials.py +307 -307
- package/database.py +333 -333
- package/docs/PRIVACY.md +78 -78
- package/docs/SECURITY.md +108 -108
- package/docs/THIRD_PARTY_NOTICES.md +148 -148
- package/env_secrets.py +118 -118
- package/json_store.py +343 -343
- package/logging_setup.py +295 -295
- package/main.py +3433 -3433
- package/mcp_client/client.py +733 -733
- package/mcp_client/config.py +484 -484
- package/mcp_client/registration.py +343 -343
- package/memories/manager.py +147 -147
- package/memories/tui_commands.py +319 -239
- package/package.json +303 -303
- package/project_init/config_files.py +282 -282
- package/project_init/generator.py +728 -728
- package/project_init/manifest.py +418 -418
- package/project_init/tui_commands.py +147 -147
- package/prompts/critic_pass.md +24 -24
- package/prompts/revalidate.md +25 -25
- package/prompts/revise.md +17 -17
- package/prompts/source_grounding.md +66 -66
- package/prompts/system_prompts.py +316 -316
- package/providers.json.example +94 -94
- package/pyproject.toml +149 -149
- package/requirements.txt +295 -295
- package/safety/policy_enforcement.py +1082 -1082
- package/security/askpass.py +419 -419
- package/security/capability.py +207 -207
- package/security/confine.py +484 -484
- package/security/hosted.py +182 -182
- package/security/permissions.py +237 -237
- package/security/protected_paths.py +501 -501
- package/security/sandbox.py +4108 -4108
- package/skills/builtin/math/formal-specification.md +67 -67
- package/skills/builtin/math/numerical-methods.md +66 -66
- package/skills/builtin/research/experiment-design.md +62 -62
- package/skills/builtin/research/reproducibility.md +55 -55
- package/skills/builtin/research/source-evaluation.md +70 -70
- package/skills/builtin/research/statistical-inference.md +63 -63
- package/skills/builtin/research/technical-writing.md +59 -59
- package/skills/builtin/software/code-review.md +61 -61
- package/skills/builtin/software/debugging.md +61 -61
- package/skills/builtin/software/test-design.md +67 -67
- package/skills/tui_commands.py +110 -110
- package/storage.py +1338 -1338
- package/tools/base.py +465 -465
- package/tools/builtin/_math_common.py +667 -667
- package/tools/builtin/_net_common.py +267 -267
- package/tools/builtin/arxiv.py +681 -681
- package/tools/builtin/fetch_url.py +371 -371
- package/tools/builtin/file_ops.py +720 -720
- package/tools/builtin/geometry.py +184 -184
- package/tools/builtin/load_skill.py +76 -76
- package/tools/builtin/pin.py +227 -227
- package/tools/builtin/probability_stats.py +224 -224
- package/tools/builtin/project_docs.py +464 -464
- package/tools/builtin/remember.py +175 -175
- package/tools/builtin/shell.py +980 -980
- package/tools/builtin/todo.py +149 -149
- package/tools/builtin/web_search.py +328 -328
- package/tools/context.py +159 -159
- package/tools/isolation.py +387 -387
- package/tools/registry.py +1242 -1242
- package/tui/app.py +8318 -8307
- package/tui/app.tcss +747 -739
- package/tui/commands.py +26 -26
- package/tui/diffs.py +286 -286
- package/tui/history.py +128 -128
- package/tui/hosted_driver.py +102 -102
- package/tui/markdown.py +1329 -1329
- package/tui/meters.py +364 -364
- package/tui/ravens.py +146 -146
- package/tui/screens.py +1255 -1197
- package/tui/themes.py +599 -599
- package/tui/widgets.py +3813 -3796
package/config_update.py
CHANGED
|
@@ -1,749 +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())
|
|
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())
|