@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
@@ -1,564 +1,728 @@
1
- """
2
- project_init/generator.py
3
-
4
- ROADMAP_v2 §24: the one place that decides what `/init` does.
5
-
6
- BOTH SHELLS CALL THIS. §26's L6 and §27's T5 again: a per-shell
7
- implementation is how the CLI and the TUI come to disagree about whether an
8
- existing document is overwritten, which is a policy question and not a
9
- painting one. The shells supply consent and rendering as callbacks; every
10
- decision about what happens lives here.
11
-
12
- THE AGENT PRODUCES TEXT; THIS MODULE WRITES (I8). The initializer gets
13
- `read_project_doc` and nothing else, and returns the hub document's prose as its
14
- final answer. Diffing, asking and dispatching `write_project_doc` happen
15
- here, because consent belongs to the shell (§20's V3) and a tool writing
16
- from inside the loop could not show a human a diff first.
17
-
18
- ONE CONSENT, A NAMED LIST. `write_project_doc` is approval-gated, so a naive
19
- implementation would prompt eight times for one command -- which is the
20
- shape of consent that gets clicked through. The user is asked once, shown
21
- the hub's diff and the exact list of files that will be created, and
22
- that answer is then passed as `approval_callback` to each dispatch. Same
23
- move core/loop.py makes after a channel approval, and for the same reason.
24
- """
25
-
26
- from __future__ import annotations
27
-
28
- import difflib
29
- import logging
30
- import os
31
- from typing import Callable, Optional
32
-
33
- import config
34
- from core import config_loader, workspace_trust
35
- from project_init import (config_files, doc_sets,
36
- manifest as manifest_mod)
37
-
38
- logger = logging.getLogger(__name__)
39
-
40
-
41
- class InitError(Exception):
42
- """Something /init cannot proceed past. Carries a message meant for a
43
- human, not a traceback; both shells print it verbatim.
44
-
45
- It may be several lines. A write that fails partway through has to say
46
- what it already did (#95), and one line cannot carry "this failed" and
47
- "these eight files exist now" without losing one of them.
48
- """
49
-
50
-
51
- def propose_kind(project_path: str) -> tuple:
52
- """(kind, reason) for an established project (I13).
53
-
54
- A PYTHON HEURISTIC, NOT A MODEL CALL, and confirmed by the user either
55
- way. A code manifest is a strong, checkable signal; the alternative --
56
- an extra round trip so a model can read the same filename this function
57
- reads -- spends a call to reach the same place with less certainty
58
- about how it got there. The reason is returned so the confirmation
59
- prompt can show its working.
60
-
61
- IT BRANCHES ON THE MANIFEST SET, NOT ON THE STACK (#96). Those are two
62
- questions -- "is this a codebase" and "what is it written in" -- and
63
- answering the first with the second is what made a Java, Ruby, Gradle,
64
- C or container project `research` with "no code manifests found"
65
- printed as the reason, while the manifest shown to the agent listed the
66
- manifest. `Makefile` and `Dockerfile` still carry no stack, which is
67
- the point: they answer the first question and not the second.
68
-
69
- The reason now names the files it found, because I13 asked for working
70
- that can be shown and a filename is the whole of the evidence.
71
- """
72
- facts = manifest_mod.detect_facts(project_path)
73
- found = facts.get("code_manifests")
74
- if not found:
75
- return (doc_sets.RESEARCH,
76
- "no code manifests found, so this looks like written work "
77
- "rather than a codebase")
78
- named = ", ".join(found)
79
- if facts.get("stack"):
80
- return (doc_sets.SOFTWARE,
81
- f"{facts['stack']} project files are present ({named})")
82
- return doc_sets.SOFTWARE, f"code manifests are present ({named})"
83
-
84
-
85
- def _existing_documents(project_path: str, kind: str) -> set:
86
- """Which documents in the set the project ALREADY has (I12)."""
87
- from tools.builtin.project_docs import doc_path
88
- return {name for name in doc_sets.document_set(kind)
89
- if os.path.exists(doc_path(project_path, name))}
90
-
91
-
92
- def _config_plan(project_path: str) -> dict:
93
- """What `--config` would create here: `{"files", "dirs", "existing"}`.
94
-
95
- AN EXISTING FILE IS NEVER OVERWRITTEN (I12, applied to the file it was
96
- written for). The document rule -- only the hub is diffed and asked
97
- about, because it is the only file /init claims to author -- reads
98
- even harder here: settings.json and mcp.json are configuration
99
- somebody tuned, and a scaffold of defaults landing on top of a tuned
100
- file would be this command destroying the thing it exists to help you
101
- start. Left alone and reported, per file, so a project with a
102
- settings.json and no mcp.json still gets the mcp.json.
103
-
104
- Directories are listed separately because creating one is not writing
105
- anything: they carry nothing into the D17 hash (`content_files()`
106
- walks files) and git does not track an empty directory, so they are a
107
- hint on this machine and never part of what a clone receives.
108
- """
109
- root = workspace_trust.venastine_dir(project_path)
110
- names = (config_files.SETTINGS_FILENAME, config_files.MCP_FILENAME)
111
- return {
112
- "files": [name for name in names
113
- if not os.path.exists(os.path.join(root, name))],
114
- "existing": [name for name in names
115
- if os.path.exists(os.path.join(root, name))],
116
- "dirs": [name for name in config_files.TIER_DIRS
117
- if not os.path.isdir(os.path.join(root, name))],
118
- }
119
-
120
-
121
- def _write_config(project_path: str, name: str) -> None:
122
- """One configuration file, written DIRECTLY (I14).
123
-
124
- Not through `write_project_doc`, which denies `.venastine/` by path
125
- segment and names these two files as the reason. Extending that
126
- allowlist was the alternative and is rejected in the record: it would
127
- advertise, to every run and all ten research passes, a tool that can
128
- author a file naming a local command to execute. What replaces the
129
- tool's approval gate is the same single consent that already covers
130
- the document set -- the shape `_settle_trust` already uses to write
131
- the trust store from here.
132
-
133
- OSError becomes InitError, so a full disk or a read-only mount takes
134
- the same reporting path as a failed document write (#95) rather than
135
- escaping as a traceback.
136
- """
137
- from json_store import write_json_atomic
138
-
139
- payload = (config_files.render_settings()
140
- if name == config_files.SETTINGS_FILENAME
141
- else config_files.render_mcp())
142
- path = os.path.join(workspace_trust.venastine_dir(project_path), name)
143
- try:
144
- write_json_atomic(path, payload, trailing_newline=True)
145
- except OSError as e:
146
- raise InitError(f"Could not write {path}: {e}")
147
-
148
-
149
- def _shadow_lines() -> list:
150
- """What the scaffolded settings.json takes over from the user's own.
151
-
152
- A project settings.json beats the user's (D29) by PRESENCE and not by
153
- difference, so even a file of pure defaults starts deciding every key
154
- it names. Said BEFORE the consent, where it can still change the
155
- answer, rather than in the report afterwards.
156
- """
157
- shadowed = config_files.shadowed(config_loader.user_settings())
158
- if not shadowed:
159
- return []
160
- lines = ["This project's settings.json will now decide "
161
- f"{len(shadowed)} key{'' if len(shadowed) == 1 else 's'} your "
162
- f"own settings.json was deciding:"]
163
- lines += [f" {path}: {theirs!r} -> {ours!r}"
164
- for path, theirs, ours in shadowed]
165
- lines.append("Delete those lines from the new file to go back to "
166
- "yours.")
167
- return lines
168
-
169
-
170
- def _read_existing_context(project_path: str) -> Optional[str]:
171
- from tools.builtin.project_docs import HUB_FILENAME, doc_path
172
- path = doc_path(project_path, HUB_FILENAME)
173
- if not os.path.exists(path):
174
- return None
175
- try:
176
- with open(path, "r", encoding="utf-8-sig") as f:
177
- return f.read()
178
- except (OSError, UnicodeDecodeError) as e:
179
- # Degrade like config_loader does with an unreadable hub document.
180
- # An undecodable existing file must not stop /init from writing a
181
- # good one -- but it is also not something to revise, so the run
182
- # proceeds as if there were none.
183
- logger.warning("Could not read the existing %s at %s; "
184
- "generating a fresh one: %s", HUB_FILENAME, path, e)
185
- return None
186
-
187
-
188
- def _task(manifest_text: str, existing: Optional[str], kind: str) -> str:
189
- """The user message: the manifest, plus the current file if there is
190
- one (I4). Both go HERE and not in the system prompt -- see
191
- project_init/manifest.py on why that distinction is load-bearing.
192
-
193
- THE HUB'S NAME IS INTERPOLATED, NEVER SPELLED (§44 WS8). This function
194
- said "Write CONTEXT.md" for two batches after the hub became the root
195
- AGENTS.md: the shell wrote to the right path, and the model drafted a
196
- document that called itself by the old name. Reading the constant means
197
- the next relocation cannot leave the prompt behind again.
198
- """
199
- from tools.builtin.project_docs import HUB_FILENAME
200
-
201
- parts = [
202
- f"Write {HUB_FILENAME} for this {kind} project.",
203
- "",
204
- manifest_text,
205
- ]
206
- if existing:
207
- parts += [
208
- f"## The current {HUB_FILENAME}",
209
- "",
210
- "This already exists and may contain hand edits. Revise it: keep "
211
- "everything still true, correct what the project has outgrown, "
212
- "add what is missing. Do not reword something merely to phrase "
213
- "it your way.",
214
- "",
215
- existing,
216
- "",
217
- ]
218
- return "\n".join(parts)
219
-
220
-
221
- def _run_initializer(project_path: str, kind: str, existing: Optional[str],
222
- model: str, provider_name: str) -> str:
223
- from agents.manager import manager
224
- from core.loop import RunAgentLoop, DEFAULT_SYSTEM_PROMPT
225
- from storage import THREAD_KIND_SUBAGENT
226
-
227
- agent = manager.get(config.INITIALIZER_AGENT)
228
- if agent is None:
229
- raise InitError(
230
- f"The {config.INITIALIZER_AGENT!r} agent is not available, so "
231
- f"there is nothing to generate the hub document with.")
232
-
233
- context = manager.active_context(agent)
234
- system_prompt = manager.system_prompt_for(
235
- agent, DEFAULT_SYSTEM_PROMPT, context=context)
236
-
237
- response = RunAgentLoop.run_agent_conversation(
238
- user_goal=_task(manifest_mod.build_manifest(project_path),
239
- existing, kind),
240
- model=agent.model or model,
241
- provider_name=agent.provider or provider_name,
242
- max_steps=agent.max_steps or config.INIT_MAX_STEPS,
243
- # #4: no separate /init ceiling any more -- the wrapper resolves the
244
- # configured spend cap, same as every other path.
245
- context=context,
246
- system_prompt=system_prompt,
247
- # §27: the initializer is a SIXTH thread source. Left unlabelled it
248
- # clutters the picker with a thread nobody will ever resume.
249
- thread_kind=THREAD_KIND_SUBAGENT,
250
- )
251
- body = (response.text or "").strip()
252
- if not body:
253
- raise InitError(
254
- "The initializer returned nothing, so there is no hub document "
255
- "to write. Nothing has been changed.")
256
- return body
257
-
258
-
259
- def build_diff(old: Optional[str], new: str, path: str) -> str:
260
- """Unified diff of what /init would change (I5). Empty string when the
261
- file would be identical, which the caller reports rather than writing."""
262
- old_lines = (old or "").splitlines(keepends=True)
263
- new_lines = new.splitlines(keepends=True)
264
- label = os.path.basename(path)
265
- return "".join(difflib.unified_diff(
266
- old_lines, new_lines,
267
- fromfile=f"{label} (current)" if old else "/dev/null",
268
- tofile=f"{label} (proposed)"))
269
-
270
-
271
- def generate(
272
- project_path: Optional[str] = None,
273
- model: Optional[str] = None,
274
- provider_name: Optional[str] = None,
275
- *,
276
- kind: Optional[str] = None,
277
- confirm: Optional[Callable] = None,
278
- notify: Optional[Callable] = None,
279
- choose_kind: Optional[Callable] = None,
280
- scaffold_docs: bool = True,
281
- scaffold_config: bool = False,
282
- ) -> dict:
283
- """Scaffold this project's documentation set, its configuration, or both.
284
-
285
- confirm(summary) -> bool the one consent (I5). None means there is no
286
- way to ask, and therefore nothing is written.
287
- notify(text) -> None progress and the diff, rendered by the shell.
288
- choose_kind(proposal, reason, blank) -> str | None
289
- resolves the project kind. Called with
290
- blank=True when there is nothing to infer
291
- from (I13), in which case `proposal` is None.
292
- scaffold_docs the AGENTS.md hub and the stubs it links.
293
- scaffold_config `.venastine/settings.json`, `mcp.json` and
294
- the two tier directories (§24 I17).
295
-
296
- TWO FLAGS RATHER THAN TWO FUNCTIONS. `--config` on its own is a
297
- different OPERATION -- no kind question, no initializer, no spend --
298
- but it is not a different set of decisions, and the decisions are
299
- what this module exists to hold in one place. A config-only entry
300
- point beside this one would be a second answer to "is an existing
301
- file overwritten" and a second place to forget the trust settle.
302
-
303
- Returns a notice dict in the {"kind", "text"} shape both shells render.
304
- """
305
- from tools.builtin.project_docs import HUB_FILENAME, doc_path
306
- from tools.registry import registry, ToolCallDenied
307
-
308
- root = project_path or config_loader.get_project_path()
309
- if root is None:
310
- raise InitError("No project directory has been resolved.")
311
- root = os.path.realpath(root)
312
- say = notify or (lambda _text: None)
313
- if not scaffold_docs and not scaffold_config:
314
- raise InitError("/init was asked to scaffold nothing.")
315
-
316
- body = None
317
- diff = ""
318
- to_create = []
319
- already_there = set()
320
- context_path = doc_path(root, HUB_FILENAME)
321
-
322
- # ---- 1. Which set --------------------------------------------------
323
- # Only when there is a set. `--config` alone asks nothing and spends
324
- # nothing, which is the whole of why it is a separate flag rather
325
- # than an addition to a run that always costs a model call.
326
- if scaffold_docs:
327
- if kind is None:
328
- blank = manifest_mod.is_blank(root)
329
- proposal, reason = (None, "") if blank else propose_kind(root)
330
- if choose_kind is None:
331
- # No way to ask. Refusing beats scaffolding seven files of
332
- # the wrong kind into someone's project -- V6's rule, and
333
- # the wrong answer here is expensive to undo by hand.
334
- raise InitError(
335
- "The project type could not be determined and there is "
336
- "no way to ask. Re-run with --software or --research.")
337
- kind = choose_kind(proposal, reason, blank)
338
- if kind is None:
339
- return {"kind": "init",
340
- "text": "Cancelled — nothing was written."}
341
- if kind not in doc_sets.PROJECT_KINDS:
342
- raise InitError(f"Unknown project type {kind!r}; expected one of "
343
- f"{', '.join(doc_sets.PROJECT_KINDS)}.")
344
-
345
- # ---- 2. Generate -----------------------------------------------
346
- existing_context = _read_existing_context(root)
347
- say(f"Reading the project and drafting {HUB_FILENAME}…")
348
- body = _run_initializer(root, kind, existing_context, model,
349
- provider_name)
350
-
351
- already_there = _existing_documents(root, kind)
352
- body = f"{body.rstrip()}\n\n{doc_sets.render_index(kind)}"
353
-
354
- to_create = [name for name in doc_sets.document_set(kind)
355
- if name not in already_there]
356
- diff = build_diff(existing_context, body, context_path)
357
-
358
- # ---- 3. Show, then ask once ----------------------------------------
359
- plan = _config_plan(root) if scaffold_config else {"files": [],
360
- "existing": [],
361
- "dirs": []}
362
- if not diff and not to_create and not plan["files"] and not plan["dirs"]:
363
- return {"kind": "init", "text": _nothing_to_do(kind, scaffold_docs,
364
- scaffold_config)}
365
-
366
- if scaffold_docs:
367
- if diff:
368
- say(diff)
369
- else:
370
- say(f"{HUB_FILENAME} is unchanged.")
371
- if to_create:
372
- say("Will also create, as stubs: " + ", ".join(to_create))
373
- if already_there:
374
- say("Leaving existing documents untouched: "
375
- + ", ".join(sorted(already_there)))
376
- if plan["files"]:
377
- say("Will create, with default values: "
378
- + ", ".join(".venastine/" + name for name in plan["files"]))
379
- if config_files.SETTINGS_FILENAME in plan["files"]:
380
- for line in _shadow_lines():
381
- say(line)
382
- if plan["existing"]:
383
- say("Leaving existing configuration untouched: "
384
- + ", ".join(".venastine/" + name for name in plan["existing"]))
385
-
386
- if confirm is None:
387
- # §25's V6, and the same rule §20 applies to review corrections: the
388
- # inability to ask is not permission to proceed. A piped `--init`
389
- # reports what it would do and writes nothing.
390
- return {"kind": "init",
391
- "text": "Nothing was written: there is no way to confirm "
392
- "these changes here. Re-run on a terminal."}
393
- if not confirm(_consent_summary(context_path, to_create, bool(diff),
394
- plan)):
395
- return {"kind": "init", "text": "Declined — nothing was written."}
396
-
397
- # ---- 4. Write ------------------------------------------------------
398
- # Captured BEFORE the write (I6). Afterwards the content hash has moved
399
- # and is_trusted() answers False for a project that WAS trusted, which
400
- # is exactly the state this distinction exists to tell apart.
401
- was_trusted = workspace_trust.is_trusted(root)
402
-
403
- granted = lambda _name, _params: True # noqa: E731 -- consent is above
404
- written = []
405
- made = []
406
-
407
- failure = None
408
- try:
409
- if scaffold_docs:
410
- facts = manifest_mod.detect_facts(root)
411
- if diff:
412
- _write(registry, granted, HUB_FILENAME, body)
413
- written.append(HUB_FILENAME)
414
- for name in to_create:
415
- _write(registry, granted, name,
416
- doc_sets.render_stub(name, facts))
417
- written.append(name)
418
- # The directories first, so a failure to write settings.json still
419
- # leaves a `.venastine/` whose shape says where the rest goes.
420
- for name in plan["dirs"]:
421
- os.makedirs(
422
- os.path.join(workspace_trust.venastine_dir(root), name),
423
- exist_ok=True)
424
- made.append(".venastine/" + name + "/")
425
- for name in plan["files"]:
426
- _write_config(root, name)
427
- written.append(".venastine/" + name)
428
- except OSError as e:
429
- failure = f"Could not create a directory under .venastine/: {e}"
430
- except ToolCallDenied as e:
431
- failure = f"The write was denied: {e}"
432
- except InitError as e:
433
- # THE REACHABLE FAILURE, and the one that had no handler (#95).
434
- # `ToolCallDenied` cannot arrive here -- consent is granted a few
435
- # lines up -- while `_write` raises `InitError` for every error
436
- # dict `write_run` returns, and `write_run` turns ANY OSError into
437
- # one. Disk full, permissions, a read-only mount: all of them took
438
- # this path, and this path did not exist.
439
- failure = str(e)
440
-
441
- # ---- 5. Trust ------------------------------------------------------
442
- # ON BOTH PATHS (#95). The partial write has already moved the D17
443
- # content hash, so a project the user trusted a moment ago is untrusted
444
- # now -- exactly the state I6 exists to prevent, reached by the route
445
- # I6 was not looking at. Its precondition is unchanged by the failure:
446
- # they just authored this content, and that is as true after five of
447
- # eight writes as after eight. Skipping this made the failure wrong
448
- # about two things instead of one, and silent about the second.
449
- trust_note = _settle_trust(root, was_trusted)
450
-
451
- if failure is not None:
452
- # NAME WHAT WAS CREATED. The success path reports the files so the
453
- # user knows what changed; the failure path reported the single
454
- # file that did NOT change -- the one thing they could already see
455
- # -- and discarded the list of the ones that did. "Could not write
456
- # TECHNICAL_DEBT.md" left no way to tell whether nothing had
457
- # happened or most of it had.
458
- #
459
- # NOTHING IS ROLLED BACK, deliberately. The hub's previous
460
- # content was overwritten at the first step and cannot be restored,
461
- # so "rolled back" would be true of the stubs and false of the one
462
- # file that mattered -- and deleting documents out of someone's
463
- # project on an error path is a worse failure than the one being
464
- # reported.
465
- lines = [failure]
466
- if written:
467
- lines.append(f"Wrote {len(written)} file"
468
- f"{'' if len(written) == 1 else 's'} before that: "
469
- + ", ".join(written))
470
- else:
471
- lines.append("Nothing was written.")
472
- lines.append(trust_note)
473
- raise InitError("\n".join(line for line in lines if line))
474
-
475
- lines = [f"Wrote {len(written)} file{'' if len(written) == 1 else 's'}: "
476
- + ", ".join(written)]
477
- if made:
478
- lines.append("Created: " + ", ".join(made))
479
- if already_there:
480
- lines.append("Left alone: " + ", ".join(sorted(already_there)))
481
- if plan["existing"]:
482
- lines.append("Left alone: "
483
- + ", ".join(".venastine/" + name
484
- for name in plan["existing"]))
485
- lines.append(trust_note)
486
- return {"kind": "init", "text": "\n".join(line for line in lines if line)}
487
-
488
-
489
- def _nothing_to_do(kind, scaffold_docs: bool, scaffold_config: bool) -> str:
490
- """The message for a run that found everything already in place.
491
-
492
- Assembled from the halves that actually ran, so a `--config` run in a
493
- configured project does not report on a document set it never looked
494
- at -- which is the same complaint #95 makes about a failure naming
495
- the one file that did NOT change.
496
- """
497
- from tools.builtin.project_docs import HUB_FILENAME
498
-
499
- parts = []
500
- if scaffold_docs:
501
- parts.append(f"{HUB_FILENAME} is already up to date and every "
502
- f"document in the {kind} set exists")
503
- if scaffold_config:
504
- parts.append(".venastine/ already has its settings.json and "
505
- "mcp.json")
506
- return " and ".join(parts) + ". Nothing to do."
507
-
508
-
509
- def _consent_summary(context_path: str, to_create: list, changing: bool,
510
- plan: Optional[dict] = None) -> str:
511
- """ONE consent covering everything the run will touch (I5).
512
-
513
- The configuration files are named in it rather than asked about
514
- separately: eight prompts for one command is the shape of consent that
515
- gets clicked through, which is the reason this summary exists at all.
516
- """
517
- plan = plan or {"files": [], "dirs": []}
518
- parts = []
519
- if changing:
520
- parts.append(f"write {context_path}")
521
- if to_create:
522
- parts.append(f"create {len(to_create)} stub document"
523
- f"{'' if len(to_create) == 1 else 's'} "
524
- f"({', '.join(to_create)})")
525
- if plan["files"]:
526
- parts.append("create " + ", ".join(".venastine/" + name
527
- for name in plan["files"])
528
- + " with default values")
529
- if plan["dirs"]:
530
- parts.append("create " + ", ".join(".venastine/" + name + "/"
531
- for name in plan["dirs"]))
532
- return "/init will " + " and ".join(parts) + ". Proceed?"
533
-
534
-
535
- def _write(registry, granted, name: str, content: str) -> None:
536
- result = registry.dispatch(
537
- "write_project_doc", {"name": name, "content": content},
538
- approval_callback=granted)
539
- if isinstance(result, dict) and result.get("error"):
540
- raise InitError(result["error"])
541
-
542
-
543
- def _settle_trust(project_path: str, was_trusted: bool) -> str:
544
- """I6. Re-grant only for a project that was ALREADY trusted.
545
-
546
- Writing the hub changes the D17 content hash, so a project the user
547
- had approved becomes untrusted purely because they ran this command --
548
- the trust system working as designed, producing a bad outcome. Since
549
- they just authored the content, re-granting is unambiguous.
550
-
551
- But ONLY then. In an untrusted project, `.venastine/` may already hold
552
- agents, skills and an mcp.json that arrived with a repo someone cloned.
553
- Granting trust as a side effect of /init would launder all of it in --
554
- a hole in D17 opened from a direction the trust prompt never sees.
555
- The hub is never special-cased out of the hash either; that would be
556
- the same hole with a smaller mouth.
557
- """
558
- if not was_trusted:
559
- return ("This project is not trusted, so nothing here has changed "
560
- "that. You will be asked about its .venastine/ content on "
561
- "the next launch.")
562
- workspace_trust.grant_trust(project_path)
563
- return ("Workspace trust re-granted for the updated .venastine/ content, "
564
- "so the next launch will not re-ask.")
1
+ """
2
+ project_init/generator.py
3
+
4
+ ROADMAP_v2 §24: the one place that decides what `/init` does.
5
+
6
+ BOTH SHELLS CALL THIS. §26's L6 and §27's T5 again: a per-shell
7
+ implementation is how the CLI and the TUI come to disagree about whether an
8
+ existing document is overwritten, which is a policy question and not a
9
+ painting one. The shells supply consent and rendering as callbacks; every
10
+ decision about what happens lives here.
11
+
12
+ THE AGENT PRODUCES TEXT; THIS MODULE WRITES (I8). The initializer gets
13
+ `read_project_doc` and nothing else, and returns the hub document's prose as its
14
+ final answer. Diffing, asking and dispatching `write_project_doc` happen
15
+ here, because consent belongs to the shell (§20's V3) and a tool writing
16
+ from inside the loop could not show a human a diff first.
17
+
18
+ ONE CONSENT, A NAMED LIST. `write_project_doc` is approval-gated, so a naive
19
+ implementation would prompt eight times for one command -- which is the
20
+ shape of consent that gets clicked through. The user is asked once, shown
21
+ the hub's diff and the exact list of files that will be created, and
22
+ that answer is then passed as `approval_callback` to each dispatch. Same
23
+ move core/loop.py makes after a channel approval, and for the same reason.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import difflib
29
+ import logging
30
+ import os
31
+ from collections.abc import Callable
32
+ from typing import Optional
33
+
34
+ import config
35
+ from core import config_loader, workspace_trust
36
+ from json_store import read_regular_text
37
+ from project_init import config_files, doc_sets
38
+ from project_init import manifest as manifest_mod
39
+
40
+ logger = logging.getLogger(__name__)
41
+
42
+
43
+ class InitError(Exception):
44
+ """Something /init cannot proceed past. Carries a message meant for a
45
+ human, not a traceback; both shells print it verbatim.
46
+
47
+ It may be several lines. A write that fails partway through has to say
48
+ what it already did (#95), and one line cannot carry "this failed" and
49
+ "these eight files exist now" without losing one of them.
50
+ """
51
+
52
+
53
+ def propose_kind(project_path: str) -> tuple:
54
+ """(kind, reason) for an established project (I13).
55
+
56
+ A PYTHON HEURISTIC, NOT A MODEL CALL, and confirmed by the user either
57
+ way. A code manifest is a strong, checkable signal; the alternative --
58
+ an extra round trip so a model can read the same filename this function
59
+ reads -- spends a call to reach the same place with less certainty
60
+ about how it got there. The reason is returned so the confirmation
61
+ prompt can show its working.
62
+
63
+ IT BRANCHES ON THE MANIFEST SET, NOT ON THE STACK (#96). Those are two
64
+ questions -- "is this a codebase" and "what is it written in" -- and
65
+ answering the first with the second is what made a Java, Ruby, Gradle,
66
+ C or container project `research` with "no code manifests found"
67
+ printed as the reason, while the manifest shown to the agent listed the
68
+ manifest. `Makefile` and `Dockerfile` still carry no stack, which is
69
+ the point: they answer the first question and not the second.
70
+
71
+ The reason now names the files it found, because I13 asked for working
72
+ that can be shown and a filename is the whole of the evidence.
73
+ """
74
+ facts = manifest_mod.detect_facts(project_path)
75
+ found = facts.get("code_manifests")
76
+ if not found:
77
+ return (doc_sets.RESEARCH,
78
+ "no code manifests found, so this looks like written work "
79
+ "rather than a codebase")
80
+ named = ", ".join(found)
81
+ if facts.get("stack"):
82
+ return (doc_sets.SOFTWARE,
83
+ f"{facts['stack']} project files are present ({named})")
84
+ return doc_sets.SOFTWARE, f"code manifests are present ({named})"
85
+
86
+
87
+ def _existing_documents(project_path: str, kind: str) -> set:
88
+ """Which documents in the set the project ALREADY has (I12)."""
89
+ from tools.builtin.project_docs import doc_path
90
+ return {name for name in doc_sets.document_set(kind)
91
+ if os.path.exists(doc_path(project_path, name))}
92
+
93
+
94
+ def _config_plan(project_path: str) -> dict:
95
+ """What `--config` would create here: `{"files", "dirs", "existing"}`.
96
+
97
+ AN EXISTING FILE IS NEVER OVERWRITTEN (I12, applied to the file it was
98
+ written for). The document rule -- only the hub is diffed and asked
99
+ about, because it is the only file /init claims to author -- reads
100
+ even harder here: settings.json and mcp.json are configuration
101
+ somebody tuned, and a scaffold of defaults landing on top of a tuned
102
+ file would be this command destroying the thing it exists to help you
103
+ start. Left alone and reported, per file, so a project with a
104
+ settings.json and no mcp.json still gets the mcp.json.
105
+
106
+ Directories are listed separately because creating one is not writing
107
+ anything: they carry nothing into the D17 hash (`content_files()`
108
+ walks files) and git does not track an empty directory, so they are a
109
+ hint on this machine and never part of what a clone receives.
110
+ """
111
+ root = workspace_trust.venastine_dir(project_path)
112
+ names = (config_files.SETTINGS_FILENAME, config_files.MCP_FILENAME)
113
+ return {
114
+ "files": [name for name in names
115
+ if not os.path.exists(os.path.join(root, name))],
116
+ "existing": [name for name in names
117
+ if os.path.exists(os.path.join(root, name))],
118
+ "dirs": [name for name in config_files.TIER_DIRS
119
+ if not os.path.isdir(os.path.join(root, name))],
120
+ }
121
+
122
+
123
+ def _write_config(project_path: str, name: str) -> None:
124
+ """One configuration file, written DIRECTLY (I14).
125
+
126
+ Not through `write_project_doc`, which denies `.venastine/` by path
127
+ segment and names these two files as the reason. Extending that
128
+ allowlist was the alternative and is rejected in the record: it would
129
+ advertise, to every run and all ten research passes, a tool that can
130
+ author a file naming a local command to execute. What replaces the
131
+ tool's approval gate is the same single consent that already covers
132
+ the document set -- the shape `_settle_trust` already uses to write
133
+ the trust store from here.
134
+
135
+ OSError becomes InitError, so a full disk or a read-only mount takes
136
+ the same reporting path as a failed document write (#95) rather than
137
+ escaping as a traceback.
138
+ """
139
+ from json_store import write_json_atomic
140
+
141
+ payload = (config_files.render_settings()
142
+ if name == config_files.SETTINGS_FILENAME
143
+ else config_files.render_mcp())
144
+ path = os.path.join(workspace_trust.venastine_dir(project_path), name)
145
+ try:
146
+ write_json_atomic(path, payload, trailing_newline=True)
147
+ except OSError as e:
148
+ raise InitError(f"Could not write {path}: {e}")
149
+
150
+
151
+ def _shadow_lines() -> list:
152
+ """What the scaffolded settings.json takes over from the user's own.
153
+
154
+ A project settings.json beats the user's (D29) by PRESENCE and not by
155
+ difference, so even a file of pure defaults starts deciding every key
156
+ it names. Said BEFORE the consent, where it can still change the
157
+ answer, rather than in the report afterwards.
158
+ """
159
+ shadowed = config_files.shadowed(config_loader.user_settings())
160
+ if not shadowed:
161
+ return []
162
+ lines = ["This project's settings.json will now decide "
163
+ f"{len(shadowed)} key{'' if len(shadowed) == 1 else 's'} your "
164
+ f"own settings.json was deciding:"]
165
+ lines += [f" {path}: {theirs!r} -> {ours!r}"
166
+ for path, theirs, ours in shadowed]
167
+ lines.append("Delete those lines from the new file to go back to "
168
+ "yours.")
169
+ return lines
170
+
171
+
172
+ def _read_existing_context(project_path: str) -> Optional[str]:
173
+ """The current hub, or None to generate a fresh one.
174
+
175
+ BOUNDED SINCE BATCH 221 (#226). It was read, diffed, embedded in the
176
+ model's task and printed whole: measured, a 5.4 MB hub went into a
177
+ 5.4 MB task and a 5.4 MB diff. Head-plus-a-notice was the other shape,
178
+ and it is wrong here: the initializer's reply BECOMES the whole hub, so
179
+ a model shown the head would rewrite the file without its tail. So a
180
+ hub past `init_max_hub_chars` is refused with nothing sent anywhere,
181
+ and the owner sized that at about three times this repository's own
182
+ 347 KB hub. The size is checked before the read, in bytes, where four
183
+ bytes per character makes the comparison safe; the count is checked
184
+ after it. And the read itself is regular-files-only (batch 219).
185
+ """
186
+ from tools.builtin.project_docs import HUB_FILENAME, doc_path
187
+ path = doc_path(project_path, HUB_FILENAME)
188
+ if not os.path.exists(path):
189
+ return None
190
+ cap = config.INIT_MAX_HUB_CHARS
191
+ try:
192
+ if os.path.getsize(path) > 4 * cap:
193
+ raise InitError(_too_large(HUB_FILENAME, os.path.getsize(path),
194
+ "bytes", cap))
195
+ text = read_regular_text(path)
196
+ except (OSError, UnicodeDecodeError) as e:
197
+ # Degrade like config_loader does with an unreadable hub document.
198
+ # An undecodable existing file must not stop /init from writing a
199
+ # good one -- but it is also not something to revise, so the run
200
+ # proceeds as if there were none.
201
+ logger.warning("Could not read the existing %s at %s; "
202
+ "generating a fresh one: %s", HUB_FILENAME, path, e)
203
+ return None
204
+ if len(text) > cap:
205
+ raise InitError(_too_large(HUB_FILENAME, len(text), "characters",
206
+ cap))
207
+ return text
208
+
209
+
210
+ def _too_large(name: str, size: int, unit: str, cap: int) -> str:
211
+ return (f"{name} is {size:,} {unit}, more than /init revises "
212
+ f"({cap:,} characters, init_max_hub_chars in config.yaml). "
213
+ f"Nothing has been changed: trim it, or edit it by hand.")
214
+
215
+
216
+ def _shown(diff: str) -> str:
217
+ """The diff as the shell shows it: at most `init_diff_shown_lines`
218
+ lines, and a line saying how many more there are (#226). The whole
219
+ diff still decides whether anything changed; only the print is cut,
220
+ because a megabyte-scale row freezes the transcript it is printed to."""
221
+ lines = diff.splitlines(keepends=True)
222
+ cap = config.INIT_DIFF_SHOWN_LINES
223
+ if len(lines) <= cap:
224
+ return diff
225
+ return ("".join(lines[:cap]).rstrip("\n")
226
+ + f"\n... {len(lines) - cap:,} more line(s) of the diff are not "
227
+ f"shown ({cap:,} of {len(lines):,}; init_diff_shown_lines in "
228
+ f"config.yaml).")
229
+
230
+
231
+ def _task(manifest_text: str, existing: Optional[str], kind: str) -> str:
232
+ """The user message: the manifest, plus the current file if there is
233
+ one (I4). Both go HERE and not in the system prompt -- see
234
+ project_init/manifest.py on why that distinction is load-bearing.
235
+
236
+ THE HUB'S NAME IS INTERPOLATED, NEVER SPELLED (§44 WS8). This function
237
+ said "Write CONTEXT.md" for two batches after the hub became the root
238
+ AGENTS.md: the shell wrote to the right path, and the model drafted a
239
+ document that called itself by the old name. Reading the constant means
240
+ the next relocation cannot leave the prompt behind again.
241
+ """
242
+ from tools.builtin.project_docs import HUB_FILENAME
243
+
244
+ parts = [
245
+ f"Write {HUB_FILENAME} for this {kind} project.",
246
+ "",
247
+ manifest_text,
248
+ ]
249
+ if existing:
250
+ parts += [
251
+ f"## The current {HUB_FILENAME}",
252
+ "",
253
+ "This already exists and may contain hand edits. Revise it: keep "
254
+ "everything still true, correct what the project has outgrown, "
255
+ "add what is missing. Do not reword something merely to phrase "
256
+ "it your way.",
257
+ "",
258
+ existing,
259
+ "",
260
+ ]
261
+ return "\n".join(parts)
262
+
263
+
264
+ def _run_initializer(project_path: str, kind: str, existing: Optional[str],
265
+ model: str, provider_name: str, activity=None) -> str:
266
+ from agents.manager import manager
267
+ from core import agent_activity
268
+ from core.loop import DEFAULT_SYSTEM_PROMPT, RunAgentLoop, advertisement_facts
269
+ from storage import THREAD_KIND_SUBAGENT
270
+
271
+ agent = manager.get(config.INITIALIZER_AGENT)
272
+ if agent is None:
273
+ raise InitError(
274
+ f"The {config.INITIALIZER_AGENT!r} agent is not available, so "
275
+ f"there is nothing to generate the hub document with.")
276
+
277
+ context = manager.active_context(agent)
278
+ # #228: the run below is given no authorization, so it is HEADLESS --
279
+ # nothing can answer an approval -- and the prompt says what THAT run
280
+ # can call, the reviewer's rule (core/reasoning/review.py). With
281
+ # system_prompt_for's attended defaults this was right only while
282
+ # initializer.md's allowed_tools kept both catalog tools out.
283
+ callable_only, granted = advertisement_facts()
284
+ system_prompt = manager.system_prompt_for(
285
+ agent, DEFAULT_SYSTEM_PROMPT, context=context,
286
+ callable_only=callable_only, granted=granted)
287
+
288
+ # §47, the span batch 59 named as a follow-on and did not build. /init
289
+ # is a long agent-shaped run -- it reads the project and drafts a
290
+ # document -- and until now a shell watching the agent stack saw
291
+ # nothing at all while it happened.
292
+ #
293
+ # `context.subagent_depth + 1` rather than a literal 1, which is
294
+ # core/loop._compactor_depth's rule one command over: the number is
295
+ # derived from the depth the run actually starts at, so a second
296
+ # count cannot disagree with the first.
297
+ with agent_activity.span(activity, agent.name,
298
+ context.subagent_depth + 1):
299
+ response = RunAgentLoop.run_agent_conversation(
300
+ user_goal=_task(manifest_mod.build_manifest(project_path),
301
+ existing, kind),
302
+ model=agent.model or model,
303
+ provider_name=agent.provider or provider_name,
304
+ max_steps=agent.max_steps or config.INIT_MAX_STEPS,
305
+ # #4: no separate /init ceiling any more -- the wrapper
306
+ # resolves the configured spend cap, same as every other path.
307
+ context=context,
308
+ system_prompt=system_prompt,
309
+ # §27: the initializer is a SIXTH thread source. Left
310
+ # unlabelled it clutters the picker with a thread nobody
311
+ # will ever resume.
312
+ thread_kind=THREAD_KIND_SUBAGENT,
313
+ # §47. NO parent thread, deliberately: /init scaffolds a
314
+ # project, it is not a child of the conversation the command
315
+ # was typed in -- and `generate()` is shell-agnostic and has
316
+ # no conversation to name anyway. Reachable from the panel
317
+ # while it runs, which is what the span is for.
318
+ thread_agent=agent.name,
319
+ )
320
+ body = (response.text or "").strip()
321
+ if not body:
322
+ raise InitError(
323
+ "The initializer returned nothing, so there is no hub document "
324
+ "to write. Nothing has been changed.")
325
+ return body
326
+
327
+
328
+ def build_diff(old: Optional[str], new: str, path: str) -> str:
329
+ """Unified diff of what /init would change (I5). Empty string when the
330
+ file would be identical, which the caller reports rather than writing."""
331
+ old_lines = (old or "").splitlines(keepends=True)
332
+ new_lines = new.splitlines(keepends=True)
333
+ label = os.path.basename(path)
334
+ return "".join(difflib.unified_diff(
335
+ old_lines, new_lines,
336
+ fromfile=f"{label} (current)" if old else "/dev/null",
337
+ tofile=f"{label} (proposed)"))
338
+
339
+
340
+ def generate(
341
+ project_path: Optional[str] = None,
342
+ model: Optional[str] = None,
343
+ provider_name: Optional[str] = None,
344
+ *,
345
+ kind: Optional[str] = None,
346
+ confirm: Optional[Callable] = None,
347
+ notify: Optional[Callable] = None,
348
+ choose_kind: Optional[Callable] = None,
349
+ scaffold_docs: bool = True,
350
+ scaffold_config: bool = False,
351
+ activity=None,
352
+ ) -> dict:
353
+ """Scaffold this project's documentation set, its configuration, or both.
354
+
355
+ confirm(summary) -> bool the one consent (I5). None means there is no
356
+ way to ask, and therefore nothing is written.
357
+ notify(text) -> None progress and the diff, rendered by the shell.
358
+ choose_kind(proposal, reason, blank) -> str | None
359
+ resolves the project kind. Called with
360
+ blank=True when there is nothing to infer
361
+ from (I13), in which case `proposal` is None.
362
+ scaffold_docs the AGENTS.md hub and the stubs it links.
363
+ scaffold_config `.venastine/settings.json`, `mcp.json` and
364
+ the two tier directories (§24 I17).
365
+
366
+ TWO FLAGS RATHER THAN TWO FUNCTIONS. `--config` on its own is a
367
+ different OPERATION -- no kind question, no initializer, no spend --
368
+ but it is not a different set of decisions, and the decisions are
369
+ what this module exists to hold in one place. A config-only entry
370
+ point beside this one would be a second answer to "is an existing
371
+ file overwritten" and a second place to forget the trust settle.
372
+
373
+ Returns a notice dict in the {"kind", "text"} shape both shells render.
374
+ """
375
+ from tools.builtin.project_docs import HUB_FILENAME, doc_path
376
+ from tools.registry import ToolCallDenied, registry
377
+
378
+ root = project_path or config_loader.get_project_path()
379
+ if root is None:
380
+ raise InitError("No project directory has been resolved.")
381
+ root = os.path.realpath(root)
382
+ say = notify or (lambda _text: None)
383
+ if not scaffold_docs and not scaffold_config:
384
+ raise InitError("/init was asked to scaffold nothing.")
385
+
386
+ body = None
387
+ diff = ""
388
+ to_create = []
389
+ already_there = set()
390
+ context_path = doc_path(root, HUB_FILENAME)
391
+
392
+ # ---- 1. Which set --------------------------------------------------
393
+ # Only when there is a set. `--config` alone asks nothing and spends
394
+ # nothing, which is the whole of why it is a separate flag rather
395
+ # than an addition to a run that always costs a model call.
396
+ if scaffold_docs:
397
+ if kind is None:
398
+ # Both walk the project (#255, batch 213). An OSError here --
399
+ # a directory nobody may list, a path that stopped being one --
400
+ # left as itself, and the CLI catches InitError only, so it was
401
+ # a traceback there and an error line in the TUI.
402
+ try:
403
+ blank = manifest_mod.is_blank(root)
404
+ proposal, reason = ((None, "") if blank
405
+ else propose_kind(root))
406
+ except OSError as e:
407
+ raise InitError(
408
+ f"Could not read the project directory to work out its "
409
+ f"type ({e}). Re-run with --software or --research, or "
410
+ f"fix the directory's permissions.") from e
411
+ if choose_kind is None:
412
+ # No way to ask. Refusing beats scaffolding seven files of
413
+ # the wrong kind into someone's project -- V6's rule, and
414
+ # the wrong answer here is expensive to undo by hand.
415
+ raise InitError(
416
+ "The project type could not be determined and there is "
417
+ "no way to ask. Re-run with --software or --research.")
418
+ kind = choose_kind(proposal, reason, blank)
419
+ if kind is None:
420
+ return {"kind": "init",
421
+ "text": "Cancelled — nothing was written."}
422
+ if kind not in doc_sets.PROJECT_KINDS:
423
+ raise InitError(f"Unknown project type {kind!r}; expected one of "
424
+ f"{', '.join(doc_sets.PROJECT_KINDS)}.")
425
+
426
+ # ---- 2. Generate -----------------------------------------------
427
+ existing_context = _read_existing_context(root)
428
+ say(f"Reading the project and drafting {HUB_FILENAME}…")
429
+ body = _run_initializer(root, kind, existing_context, model,
430
+ provider_name, activity)
431
+
432
+ already_there = _existing_documents(root, kind)
433
+ body = f"{body.rstrip()}\n\n{doc_sets.render_index(kind)}"
434
+
435
+ to_create = [name for name in doc_sets.document_set(kind)
436
+ if name not in already_there]
437
+ diff = build_diff(existing_context, body, context_path)
438
+
439
+ # ---- 3. Show, then ask once ----------------------------------------
440
+ plan = _config_plan(root) if scaffold_config else {"files": [],
441
+ "existing": [],
442
+ "dirs": []}
443
+ if not diff and not to_create and not plan["files"] and not plan["dirs"]:
444
+ return {"kind": "init", "text": _nothing_to_do(kind, scaffold_docs,
445
+ scaffold_config)}
446
+
447
+ if scaffold_docs:
448
+ if diff:
449
+ say(_shown(diff))
450
+ else:
451
+ say(f"{HUB_FILENAME} is unchanged.")
452
+ if to_create:
453
+ say("Will also create, as stubs: " + ", ".join(to_create))
454
+ if already_there:
455
+ say("Leaving existing documents untouched: "
456
+ + ", ".join(sorted(already_there)))
457
+ if plan["files"]:
458
+ say("Will create, with default values: "
459
+ + ", ".join(".venastine/" + name for name in plan["files"]))
460
+ if config_files.SETTINGS_FILENAME in plan["files"]:
461
+ for line in _shadow_lines():
462
+ say(line)
463
+ if plan["existing"]:
464
+ say("Leaving existing configuration untouched: "
465
+ + ", ".join(".venastine/" + name for name in plan["existing"]))
466
+
467
+ if confirm is None:
468
+ # §25's V6, and the same rule §20 applies to review corrections: the
469
+ # inability to ask is not permission to proceed. A piped `--init`
470
+ # reports what it would do and writes nothing.
471
+ return {"kind": "init",
472
+ "text": "Nothing was written: there is no way to confirm "
473
+ "these changes here. Re-run on a terminal."}
474
+ if not confirm(_consent_summary(context_path, to_create, bool(diff),
475
+ plan)):
476
+ return {"kind": "init", "text": "Declined — nothing was written."}
477
+
478
+ # ---- 4. Write ------------------------------------------------------
479
+ # Captured BEFORE the write (I6). Afterwards the content hash has moved
480
+ # and is_trusted() answers False for a project that WAS trusted, which
481
+ # is exactly the state this distinction exists to tell apart.
482
+ #
483
+ # TOTAL SINCE BATCH 153, because the capture itself reads files (A47).
484
+ was_trusted, trust_problem = _trust_before(root)
485
+
486
+ granted = lambda _name, _params: True # noqa: E731 -- consent is above
487
+ written = []
488
+ made = []
489
+
490
+ failure = None
491
+ try:
492
+ if scaffold_docs:
493
+ facts = manifest_mod.detect_facts(root)
494
+ if diff:
495
+ _write(registry, granted, HUB_FILENAME, body)
496
+ written.append(HUB_FILENAME)
497
+ for name in to_create:
498
+ _write(registry, granted, name,
499
+ doc_sets.render_stub(name, facts))
500
+ written.append(name)
501
+ # The directories first, so a failure to write settings.json still
502
+ # leaves a `.venastine/` whose shape says where the rest goes.
503
+ for name in plan["dirs"]:
504
+ os.makedirs(
505
+ os.path.join(workspace_trust.venastine_dir(root), name),
506
+ exist_ok=True)
507
+ made.append(".venastine/" + name + "/")
508
+ for name in plan["files"]:
509
+ _write_config(root, name)
510
+ written.append(".venastine/" + name)
511
+ except OSError as e:
512
+ failure = f"Could not create a directory under .venastine/: {e}"
513
+ except ToolCallDenied as e:
514
+ failure = f"The write was denied: {e}"
515
+ except InitError as e:
516
+ # THE REACHABLE FAILURE, and the one that had no handler (#95).
517
+ # `ToolCallDenied` cannot arrive here -- consent is granted a few
518
+ # lines up -- while `_write` raises `InitError` for every error
519
+ # dict `write_run` returns, and `write_run` turns ANY OSError into
520
+ # one. Disk full, permissions, a read-only mount: all of them took
521
+ # this path, and this path did not exist.
522
+ failure = str(e)
523
+
524
+ # ---- 5. Trust ------------------------------------------------------
525
+ # ON BOTH PATHS (#95). The partial write has already moved the D17
526
+ # content hash, so a project the user trusted a moment ago is untrusted
527
+ # now -- exactly the state I6 exists to prevent, reached by the route
528
+ # I6 was not looking at. Its precondition is unchanged by the failure:
529
+ # they just authored this content, and that is as true after five of
530
+ # eight writes as after eight. Skipping this made the failure wrong
531
+ # about two things instead of one, and silent about the second.
532
+ trust_note, trust_ok = _settle_trust(root, was_trusted, trust_problem)
533
+
534
+ if failure is not None:
535
+ # NAME WHAT WAS CREATED. The success path reports the files so the
536
+ # user knows what changed; the failure path reported the single
537
+ # file that did NOT change -- the one thing they could already see
538
+ # -- and discarded the list of the ones that did. "Could not write
539
+ # TECHNICAL_DEBT.md" left no way to tell whether nothing had
540
+ # happened or most of it had.
541
+ #
542
+ # NOTHING IS ROLLED BACK, deliberately. The hub's previous
543
+ # content was overwritten at the first step and cannot be restored,
544
+ # so "rolled back" would be true of the stubs and false of the one
545
+ # file that mattered -- and deleting documents out of someone's
546
+ # project on an error path is a worse failure than the one being
547
+ # reported.
548
+ lines = [failure]
549
+ if written:
550
+ lines.append(f"Wrote {len(written)} file"
551
+ f"{'' if len(written) == 1 else 's'} before that: "
552
+ + ", ".join(written))
553
+ else:
554
+ lines.append("Nothing was written.")
555
+ lines.append(trust_note)
556
+ raise InitError("\n".join(line for line in lines if line))
557
+
558
+ # THE WARNING LEADS, when there is one (A46). The files are on disk and
559
+ # the user can see them; what they cannot see is that the next launch
560
+ # will ask about this project again, so the half that did NOT happen is
561
+ # the half that goes first. A run whose trust settled as intended keeps
562
+ # the note where it has always been -- last, as the footnote it is.
563
+ lines = [] if trust_ok else [trust_note]
564
+ lines.append(f"Wrote {len(written)} file"
565
+ f"{'' if len(written) == 1 else 's'}: " + ", ".join(written))
566
+ if made:
567
+ lines.append("Created: " + ", ".join(made))
568
+ if already_there:
569
+ lines.append("Left alone: " + ", ".join(sorted(already_there)))
570
+ if plan["existing"]:
571
+ lines.append("Left alone: "
572
+ + ", ".join(".venastine/" + name
573
+ for name in plan["existing"]))
574
+ if trust_ok:
575
+ lines.append(trust_note)
576
+ return {"kind": "init", "text": "\n".join(line for line in lines if line)}
577
+
578
+
579
+ def _nothing_to_do(kind, scaffold_docs: bool, scaffold_config: bool) -> str:
580
+ """The message for a run that found everything already in place.
581
+
582
+ Assembled from the halves that actually ran, so a `--config` run in a
583
+ configured project does not report on a document set it never looked
584
+ at -- which is the same complaint #95 makes about a failure naming
585
+ the one file that did NOT change.
586
+ """
587
+ from tools.builtin.project_docs import HUB_FILENAME
588
+
589
+ parts = []
590
+ if scaffold_docs:
591
+ parts.append(f"{HUB_FILENAME} is already up to date and every "
592
+ f"document in the {kind} set exists")
593
+ if scaffold_config:
594
+ parts.append(".venastine/ already has its settings.json and "
595
+ "mcp.json")
596
+ return " and ".join(parts) + ". Nothing to do."
597
+
598
+
599
+ def _consent_summary(context_path: str, to_create: list, changing: bool,
600
+ plan: Optional[dict] = None) -> str:
601
+ """ONE consent covering everything the run will touch (I5).
602
+
603
+ The configuration files are named in it rather than asked about
604
+ separately: eight prompts for one command is the shape of consent that
605
+ gets clicked through, which is the reason this summary exists at all.
606
+ """
607
+ plan = plan or {"files": [], "dirs": []}
608
+ parts = []
609
+ if changing:
610
+ parts.append(f"write {context_path}")
611
+ if to_create:
612
+ parts.append(f"create {len(to_create)} stub document"
613
+ f"{'' if len(to_create) == 1 else 's'} "
614
+ f"({', '.join(to_create)})")
615
+ if plan["files"]:
616
+ parts.append("create " + ", ".join(".venastine/" + name
617
+ for name in plan["files"])
618
+ + " with default values")
619
+ if plan["dirs"]:
620
+ parts.append("create " + ", ".join(".venastine/" + name + "/"
621
+ for name in plan["dirs"]))
622
+ return "/init will " + " and ".join(parts) + ". Proceed?"
623
+
624
+
625
+ def _write(registry, granted, name: str, content: str) -> None:
626
+ result = registry.dispatch(
627
+ "write_project_doc", {"name": name, "content": content},
628
+ approval_callback=granted)
629
+ if isinstance(result, dict) and result.get("error"):
630
+ raise InitError(result["error"])
631
+
632
+
633
+ def _trust_before(project_path: str) -> tuple:
634
+ """`is_trusted()`, made total. Returns (was_trusted, problem).
635
+
636
+ THE CAPTURE READS FILES, which is the half of I6 nobody was looking at
637
+ (batch 153). `is_trusted` hashes every path `content_files()`
638
+ lists -- the root `AGENTS.md` and everything under `.venastine/` -- and
639
+ `open` on any one of them can fail: a file an editor holds, a sync
640
+ client mid-write, a mode the user changed by hand. That read sits
641
+ before the `try`, so a single unreadable file killed `/init` as a raw
642
+ `PermissionError` before it wrote anything, and on the CLI
643
+ (`except InitError` only) as a traceback.
644
+
645
+ DEGRADES, and the precedent is three functions up in this same module:
646
+ `_read_existing_context` catches `OSError` on the SAME file for the
647
+ SAME reason and says "Degrade like config_loader does with an
648
+ unreadable hub document". One function answering one error two ways is
649
+ what this closes (A47).
650
+
651
+ `False` rather than `True` for an unanswerable question, which is
652
+ `core/workspace_trust.py`'s own posture -- `_load_trust_store` returns
653
+ `{}` for anything unreadable and says it fails CLOSED in both senses.
654
+ Read as untrusted, `_settle_trust` attempts no re-grant, and the
655
+ problem is REPORTED rather than inferred from a trust prompt arriving
656
+ on the next launch.
657
+
658
+ NOT fixed in `is_trusted` itself, deliberately (A48). Its other callers
659
+ are contained -- `main.load_project_config` catches `OSError` and exits
660
+ 1 with one clean line -- and making a security control answer "not
661
+ trusted" where it currently refuses to start is a change to D17's
662
+ posture, not to this command's. `docs/TECHNICAL_DEBT.md` carries it.
663
+ """
664
+ try:
665
+ return workspace_trust.is_trusted(project_path), ""
666
+ except OSError as e:
667
+ logger.warning("Could not read the trust state of %s; proceeding as "
668
+ "untrusted: %s", project_path, e)
669
+ return False, (
670
+ f"This project's trust state could not be read ({e}), so the run "
671
+ f"proceeded as if it were untrusted and no re-grant was "
672
+ f"attempted. You will be asked about its .venastine/ content on "
673
+ f"the next launch.")
674
+
675
+
676
+ def _settle_trust(project_path: str, was_trusted: bool,
677
+ problem: str = "") -> tuple:
678
+ """I6. Re-grant only for a project that was ALREADY trusted.
679
+
680
+ Writing the hub changes the D17 content hash, so a project the user
681
+ had approved becomes untrusted purely because they ran this command --
682
+ the trust system working as designed, producing a bad outcome. Since
683
+ they just authored the content, re-granting is unambiguous.
684
+
685
+ But ONLY then. In an untrusted project, `.venastine/` may already hold
686
+ agents, skills and an mcp.json that arrived with a repo someone cloned.
687
+ Granting trust as a side effect of /init would launder all of it in --
688
+ a hole in D17 opened from a direction the trust prompt never sees.
689
+ The hub is never special-cased out of the hash either; that would be
690
+ the same hole with a smaller mouth.
691
+
692
+ TOTAL SINCE BATCH 153. Returns (note, settled_as_intended),
693
+ and the note is the whole of what the user is told about trust -- so
694
+ this function raising discarded it, along with everything `generate`
695
+ had assembled around it. #95 put the settle on both paths; the settle
696
+ then sat outside every handler on both of them, so a trust-store I/O
697
+ failure took the success path's notice and the failure path's "wrote N
698
+ files before that" accounting down with it. Measured: both config
699
+ files on disk, `is_trusted` True -> False, and a raw `OSError` out.
700
+
701
+ `grant_trust` raises from either half -- `_content_hash` re-reads the
702
+ files just written, `_save_trust_store` writes the store -- and
703
+ `OSError` is both. `json_store` argues that a trust grant which
704
+ silently did not persist is worse than a crash, and that argument is
705
+ about SILENCE: the grant still either persists or is named, and the
706
+ naming now reaches the user instead of the traceback handler.
707
+
708
+ `False` is returned for the grant failure and for an unreadable
709
+ pre-write state, and `True` for a project that was untrusted and
710
+ stayed that way -- nothing went wrong there, and that note is a
711
+ footnote rather than a warning.
712
+ """
713
+ if problem:
714
+ return problem, False
715
+ if not was_trusted:
716
+ return ("This project is not trusted, so nothing here has changed "
717
+ "that. You will be asked about its .venastine/ content on "
718
+ "the next launch."), True
719
+ try:
720
+ workspace_trust.grant_trust(project_path)
721
+ except OSError as e:
722
+ logger.warning("Could not re-grant workspace trust for %s: %s",
723
+ project_path, e)
724
+ return (f"Workspace trust could NOT be re-granted ({e}), so the next "
725
+ f"launch will ask about this project's .venastine/ content "
726
+ f"again."), False
727
+ return ("Workspace trust re-granted for the updated .venastine/ content, "
728
+ "so the next launch will not re-ask."), True