edify-agents-cli 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- edify/__init__.py +19 -0
- edify/__main__.py +6 -0
- edify/_toml.py +286 -0
- edify/agents.py +261 -0
- edify/anim.py +499 -0
- edify/assets/commands/build.md +64 -0
- edify/assets/commands/plan.md +68 -0
- edify/assets/commands/spec.md +63 -0
- edify/assets/commands/tasks.md +65 -0
- edify/assets/commands/verify.md +67 -0
- edify/assets/formats/plan.example.md +455 -0
- edify/assets/formats/plan.format.md +128 -0
- edify/assets/formats/spec.example.md +483 -0
- edify/assets/formats/spec.format.md +116 -0
- edify/assets/formats/tasks.example.md +712 -0
- edify/assets/formats/tasks.format.md +199 -0
- edify/assets/harvest/harvest.md +91 -0
- edify/assets/harvest/sources.md +295 -0
- edify/assets/harvest/vocab.md +52 -0
- edify/assets/manifest.md +30 -0
- edify/assets/mcp/default-registry.md +66 -0
- edify/assets/skills/adversary.md +61 -0
- edify/assets/skills/debugger.md +64 -0
- edify/assets/skills/implementer-general.md +53 -0
- edify/assets/skills/implementer-go.md +63 -0
- edify/assets/skills/implementer-node.md +61 -0
- edify/assets/skills/implementer-postgres.md +63 -0
- edify/assets/skills/implementer-python.md +65 -0
- edify/assets/skills/implementer-react.md +65 -0
- edify/assets/skills/planner.md +58 -0
- edify/assets/skills/test-writer-node.md +64 -0
- edify/assets/skills/test-writer-python.md +60 -0
- edify/assets/skills/verifier.md +67 -0
- edify/assets/templates/CLAUDE.md +18 -0
- edify/assets.py +77 -0
- edify/cli.py +681 -0
- edify/commands/__init__.py +1 -0
- edify/commands/check_cmd.py +72 -0
- edify/commands/doctor_cmd.py +206 -0
- edify/commands/feedback_cmd.py +90 -0
- edify/commands/governance_cmd.py +65 -0
- edify/commands/graph_cmd.py +156 -0
- edify/commands/harvest_cmd.py +538 -0
- edify/commands/init_cmd.py +333 -0
- edify/commands/init_new_cmd.py +151 -0
- edify/commands/license_cmd.py +80 -0
- edify/commands/mcp_cmd.py +159 -0
- edify/commands/self_cmd.py +185 -0
- edify/commands/setup_cmd.py +79 -0
- edify/commands/skills_cmd.py +177 -0
- edify/commands/upgrade_cmd.py +178 -0
- edify/context.py +57 -0
- edify/conventions.py +275 -0
- edify/detect.py +313 -0
- edify/distribution.py +40 -0
- edify/errors.py +66 -0
- edify/feedback.py +207 -0
- edify/formats/__init__.py +11 -0
- edify/formats/check.py +573 -0
- edify/formats/document.py +238 -0
- edify/formats/finding.py +50 -0
- edify/formats/fix.py +114 -0
- edify/formats/mcp.py +126 -0
- edify/formats/plan.py +151 -0
- edify/formats/skill.py +139 -0
- edify/formats/spec.py +164 -0
- edify/formats/tasks.py +321 -0
- edify/governance.py +316 -0
- edify/graph/__init__.py +11 -0
- edify/graph/extract.py +351 -0
- edify/graph/ignore.py +107 -0
- edify/graph/langs/__init__.py +93 -0
- edify/graph/langs/ctags.py +145 -0
- edify/graph/langs/markdown.py +41 -0
- edify/graph/langs/patterns.py +361 -0
- edify/graph/langs/python_ast.py +154 -0
- edify/graph/langs/sqlish.py +86 -0
- edify/graph/model.py +102 -0
- edify/graph/queries.py +211 -0
- edify/graph/store.py +157 -0
- edify/harvest/__init__.py +28 -0
- edify/harvest/ledger.py +191 -0
- edify/harvest/screen.py +236 -0
- edify/harvest/sources.py +298 -0
- edify/host.py +345 -0
- edify/interview.py +354 -0
- edify/library.py +176 -0
- edify/licensing/__init__.py +30 -0
- edify/licensing/ed25519.py +154 -0
- edify/licensing/projects.py +223 -0
- edify/licensing/tier.py +172 -0
- edify/licensing/token.py +149 -0
- edify/paths.py +282 -0
- edify/selfinstall.py +244 -0
- edify/skills.py +108 -0
- edify/tsv.py +109 -0
- edify/ui.py +334 -0
- edify_agents_cli-0.2.0.dist-info/METADATA +408 -0
- edify_agents_cli-0.2.0.dist-info/RECORD +102 -0
- edify_agents_cli-0.2.0.dist-info/WHEEL +4 -0
- edify_agents_cli-0.2.0.dist-info/entry_points.txt +2 -0
- edify_agents_cli-0.2.0.dist-info/licenses/LICENSE +21 -0
edify/anim.py
ADDED
|
@@ -0,0 +1,499 @@
|
|
|
1
|
+
"""An infinity, drawn while the install works.
|
|
2
|
+
|
|
3
|
+
`edify init` and `edify setup` do real work — extraction, skill install, host
|
|
4
|
+
mirroring — and until now printed nothing while doing it. This is the face of that
|
|
5
|
+
wait, and it is held to the same rules as every other line this CLI writes.
|
|
6
|
+
|
|
7
|
+
**Precomputed frames, not a live plotter** (plan D-3). `dependencies = []` is a hard
|
|
8
|
+
constraint, so there is no curses and no progress-bar library. The frames are a
|
|
9
|
+
tuple of strings built once at import, which also makes the animation *testable* —
|
|
10
|
+
frame count, uniform width, ASCII-safety — rather than something only a human can
|
|
11
|
+
check by squinting at a terminal.
|
|
12
|
+
|
|
13
|
+
**A lemniscate of Gerono** (D-4), `x = cos t`, `y = sin(2t)/2`. It is bounded and
|
|
14
|
+
evenly parameterised, so a head moving at constant `t` moves at roughly constant
|
|
15
|
+
speed on screen. The Bernoulli lemniscate crowds at the origin and reads as a
|
|
16
|
+
stutter, and a rotating unicode spinner is not an infinity at all.
|
|
17
|
+
|
|
18
|
+
**Two glyph sets, chosen by probing the stream** (D-5). `ui.py` already documents
|
|
19
|
+
that a cp1252 Windows console kills a `·`; a command that did its work and then
|
|
20
|
+
died printing its own decoration is the worst of both outcomes.
|
|
21
|
+
|
|
22
|
+
**Decoration is never load-bearing.** Any exception inside the painter disables the
|
|
23
|
+
animation and the command carries on, which is the rule `_invite` already follows
|
|
24
|
+
in `cli.py`. The cursor is restored in a `finally` and again at `atexit`, so a
|
|
25
|
+
Ctrl-C never leaves a headless terminal behind.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from __future__ import annotations
|
|
29
|
+
|
|
30
|
+
import atexit
|
|
31
|
+
import math
|
|
32
|
+
import os
|
|
33
|
+
import sys
|
|
34
|
+
import threading
|
|
35
|
+
import time
|
|
36
|
+
from typing import Any
|
|
37
|
+
|
|
38
|
+
from . import ui
|
|
39
|
+
|
|
40
|
+
# -- geometry ---------------------------------------------------------------
|
|
41
|
+
|
|
42
|
+
WIDTH = 31
|
|
43
|
+
HEIGHT = 7
|
|
44
|
+
FRAMES = 48
|
|
45
|
+
#: Samples along the curve. Dense enough that the drawn line has no gaps at this
|
|
46
|
+
#: resolution, which is a property of the grid rather than a number to tune.
|
|
47
|
+
SAMPLES = 480
|
|
48
|
+
#: How many samples behind the head still get the warm glyph. The trail is what
|
|
49
|
+
#: makes the motion readable; without it the head is a dot that appears to
|
|
50
|
+
#: teleport from one arm of the curve to the other.
|
|
51
|
+
TRAIL = 34
|
|
52
|
+
|
|
53
|
+
#: Head, trail, curve. Two sets: what a UTF-8 terminal renders, and what survives
|
|
54
|
+
#: a code page that has never heard of U+00B7.
|
|
55
|
+
UNICODE_GLYPHS = ("●", "○", "·")
|
|
56
|
+
ASCII_GLYPHS = ("O", "o", ".")
|
|
57
|
+
|
|
58
|
+
FPS = 14.0
|
|
59
|
+
|
|
60
|
+
#: How much of a spinner's label is shown. The label says what the wait is for;
|
|
61
|
+
#: past this it is a paragraph, and a terminal narrower than it wraps and breaks
|
|
62
|
+
#: the repaint.
|
|
63
|
+
LABEL = 60
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _point(t: float) -> tuple[float, float]:
|
|
67
|
+
"""Gerono at parameter `t`, in [-1, 1] x [-0.5, 0.5]."""
|
|
68
|
+
return math.cos(t), math.sin(2.0 * t) / 2.0
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _cell(t: float) -> tuple[int, int]:
|
|
72
|
+
"""One curve point as a grid cell.
|
|
73
|
+
|
|
74
|
+
x spans 2 units across WIDTH columns, y spans 1 unit across HEIGHT rows. The
|
|
75
|
+
halved y in `_point` is the 2:1 aspect correction: a character is about twice
|
|
76
|
+
as tall as it is wide, so an uncorrected plot of a symmetric curve comes out
|
|
77
|
+
as a tall thin bow tie rather than an infinity.
|
|
78
|
+
"""
|
|
79
|
+
x, y = _point(t)
|
|
80
|
+
col = int(round((x + 1.0) / 2.0 * (WIDTH - 1)))
|
|
81
|
+
row = int(round((0.5 - y) * (HEIGHT - 1)))
|
|
82
|
+
return max(0, min(HEIGHT - 1, row)), max(0, min(WIDTH - 1, col))
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _build(glyphs: tuple[str, str, str]) -> tuple[str, ...]:
|
|
86
|
+
"""The whole animation, as `FRAMES` blocks of `HEIGHT` lines each `WIDTH` wide.
|
|
87
|
+
|
|
88
|
+
Every frame draws the same static curve and moves a bright head along it, so
|
|
89
|
+
the shape never flickers and only the highlight travels.
|
|
90
|
+
"""
|
|
91
|
+
head_glyph, warm_glyph, curve_glyph = glyphs
|
|
92
|
+
|
|
93
|
+
curve: list[tuple[int, int]] = []
|
|
94
|
+
seen: set[tuple[int, int]] = set()
|
|
95
|
+
for i in range(SAMPLES):
|
|
96
|
+
t = 2.0 * math.pi * i / SAMPLES
|
|
97
|
+
cell = _cell(t)
|
|
98
|
+
if cell not in seen:
|
|
99
|
+
seen.add(cell)
|
|
100
|
+
curve.append(cell)
|
|
101
|
+
|
|
102
|
+
frames: list[str] = []
|
|
103
|
+
for f in range(FRAMES):
|
|
104
|
+
grid = [[" "] * WIDTH for _ in range(HEIGHT)]
|
|
105
|
+
for row, col in curve:
|
|
106
|
+
grid[row][col] = curve_glyph
|
|
107
|
+
|
|
108
|
+
# Painted tail first, so the head always wins its cell.
|
|
109
|
+
lead = int(SAMPLES * f / FRAMES)
|
|
110
|
+
for back in range(TRAIL, 0, -1):
|
|
111
|
+
row, col = _cell(2.0 * math.pi * ((lead - back) % SAMPLES) / SAMPLES)
|
|
112
|
+
grid[row][col] = warm_glyph
|
|
113
|
+
row, col = _cell(2.0 * math.pi * lead / SAMPLES)
|
|
114
|
+
grid[row][col] = head_glyph
|
|
115
|
+
frames.append("\n".join("".join(row) for row in grid))
|
|
116
|
+
return tuple(frames)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _tones() -> tuple[dict[tuple[int, int], int], ...]:
|
|
120
|
+
"""For every frame, each lit cell's age: 0 is the head, `TRAIL` the oldest.
|
|
121
|
+
|
|
122
|
+
The same walk `_build` makes, kept apart from the glyphs so a frame's text is
|
|
123
|
+
unchanged by colour. The painter reads the age to shade the trail from the
|
|
124
|
+
bright head into the deeper ink, the way a drop thins as it spreads.
|
|
125
|
+
"""
|
|
126
|
+
table = []
|
|
127
|
+
for f in range(FRAMES):
|
|
128
|
+
lead = int(SAMPLES * f / FRAMES)
|
|
129
|
+
ages: dict[tuple[int, int], int] = {}
|
|
130
|
+
for back in range(TRAIL, -1, -1):
|
|
131
|
+
ages[_cell(2.0 * math.pi * ((lead - back) % SAMPLES) / SAMPLES)] = back
|
|
132
|
+
table.append(ages)
|
|
133
|
+
return tuple(table)
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
#: Built once, at import. Two tuples of `FRAMES` strings — deterministic, and so
|
|
137
|
+
#: assertable in a test rather than only visible to a person.
|
|
138
|
+
UNICODE_FRAMES: tuple[str, ...] = _build(UNICODE_GLYPHS)
|
|
139
|
+
ASCII_FRAMES: tuple[str, ...] = _build(ASCII_GLYPHS)
|
|
140
|
+
TONES = _tones()
|
|
141
|
+
|
|
142
|
+
#: The wordmark. Pure ASCII by construction, because it survives a pipe, a CI log,
|
|
143
|
+
#: and a code page — it is printed even when the animation is not.
|
|
144
|
+
BANNER = (
|
|
145
|
+
" ___ ___ ___ ___ __ __",
|
|
146
|
+
" | __| \\_ _| __|\\ \\ / / the infinite loop, made finite",
|
|
147
|
+
" | _|| |) | || _| \\ V / three documents and a map",
|
|
148
|
+
" |___|___/___|_| |_|",
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
#: The wordmark a person at a terminal sees: the site's heavy sans, in half blocks.
|
|
152
|
+
#: Three rows, so it is a mark and not a poster.
|
|
153
|
+
WORDMARK = (
|
|
154
|
+
"█▀▀▀ █▀▀▄ █ █▀▀▀ █ █",
|
|
155
|
+
"█▀▀ █ █ █ █▀▀ ▀█▀ ",
|
|
156
|
+
"▀▀▀▀ ▀▀▀ ▀ ▀ ▀ ",
|
|
157
|
+
)
|
|
158
|
+
|
|
159
|
+
#: The readout under the wordmark, as wide as the clips' corner readouts sit apart.
|
|
160
|
+
READOUT_WIDTH = 46
|
|
161
|
+
|
|
162
|
+
#: The ink pool. Where it comes to rest (a column of the wordmark), how wide it is
|
|
163
|
+
#: on each row — uneven, so it reads as liquid and not as a highlighter — and how
|
|
164
|
+
#: long it takes to arrive: `--d-el`, the site's single-element entrance.
|
|
165
|
+
POOL_REST = 9.0
|
|
166
|
+
POOL_HALF = (4.5, 5.5, 3.5)
|
|
167
|
+
POOL_MS = 420
|
|
168
|
+
POOL_FRAMES = 12
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
# -- glyph selection --------------------------------------------------------
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def frames_for(stream: Any = None) -> tuple[str, ...]:
|
|
175
|
+
"""The frame table this stream can actually print.
|
|
176
|
+
|
|
177
|
+
Probes `stream.encoding` rather than assuming, mirroring the degradation
|
|
178
|
+
`ui._emit` already performs. A stream with no encoding, or one that cannot
|
|
179
|
+
round-trip the glyphs, gets the ASCII table.
|
|
180
|
+
"""
|
|
181
|
+
stream = stream if stream is not None else sys.stderr
|
|
182
|
+
encoding = getattr(stream, "encoding", None)
|
|
183
|
+
if not encoding:
|
|
184
|
+
return ASCII_FRAMES
|
|
185
|
+
try:
|
|
186
|
+
"".join(UNICODE_GLYPHS).encode(encoding)
|
|
187
|
+
except (UnicodeEncodeError, LookupError, TypeError):
|
|
188
|
+
return ASCII_FRAMES
|
|
189
|
+
return UNICODE_FRAMES
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
# -- terminal control -------------------------------------------------------
|
|
193
|
+
|
|
194
|
+
_HIDE = "\033[?25l"
|
|
195
|
+
_SHOW = "\033[?25h"
|
|
196
|
+
_UP = "\033[F"
|
|
197
|
+
_CLEAR_LINE = "\033[2K"
|
|
198
|
+
|
|
199
|
+
#: Set the first time a painter hides the cursor. The `atexit` backstop checks it,
|
|
200
|
+
#: so a run that never animated — every test, every pipe, every CI job — does not
|
|
201
|
+
#: emit a stray escape sequence into somebody's captured output.
|
|
202
|
+
_hid_cursor = False
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def _restore_cursor() -> None:
|
|
206
|
+
"""The backstop. Registered at `atexit` so a hard exit still shows a cursor."""
|
|
207
|
+
global _hid_cursor
|
|
208
|
+
if not _hid_cursor:
|
|
209
|
+
return
|
|
210
|
+
_hid_cursor = False
|
|
211
|
+
try:
|
|
212
|
+
sys.stderr.write(_SHOW)
|
|
213
|
+
sys.stderr.flush()
|
|
214
|
+
except (OSError, ValueError):
|
|
215
|
+
pass
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
atexit.register(_restore_cursor)
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
# -- the spinner ------------------------------------------------------------
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
class Spinner:
|
|
225
|
+
"""Paint the infinity to stderr while the block runs. A context manager.
|
|
226
|
+
|
|
227
|
+
stderr, not stdout: `--json` output and every piped answer stay clean by
|
|
228
|
+
construction rather than by remembering. The thread is a daemon, so an
|
|
229
|
+
interpreter that is shutting down is never held open by decoration.
|
|
230
|
+
|
|
231
|
+
Whether it paints at all is `Out.animated` — the one place tty, `--json`,
|
|
232
|
+
`--quiet`, `--no-anim`, `EDIFY_NO_ANIM`, `CI` and `TERM=dumb` are decided,
|
|
233
|
+
next to the existing `Out.interactive`. When it does not paint, the label is
|
|
234
|
+
still printed as one static line, so a pipe and a CI log say what happened.
|
|
235
|
+
"""
|
|
236
|
+
|
|
237
|
+
def __init__(self, out: Any, label: str = "", stream: Any = None) -> None:
|
|
238
|
+
self.out = out
|
|
239
|
+
self.label = label
|
|
240
|
+
self.stream = stream if stream is not None else sys.stderr
|
|
241
|
+
self._thread: threading.Thread | None = None
|
|
242
|
+
self._stop = threading.Event()
|
|
243
|
+
self._painted = False
|
|
244
|
+
self._start = time.monotonic()
|
|
245
|
+
self._lines = HEIGHT + (1 if label else 0)
|
|
246
|
+
|
|
247
|
+
# -- lifecycle ---------------------------------------------------
|
|
248
|
+
|
|
249
|
+
def __enter__(self) -> "Spinner":
|
|
250
|
+
self._start = time.monotonic()
|
|
251
|
+
if not self._enabled():
|
|
252
|
+
if self.label:
|
|
253
|
+
self.out.note(self.label)
|
|
254
|
+
return self
|
|
255
|
+
try:
|
|
256
|
+
self._thread = threading.Thread(target=self._paint, daemon=True)
|
|
257
|
+
self._thread.start()
|
|
258
|
+
except RuntimeError:
|
|
259
|
+
# No threads available. Not a reason for the command to fail.
|
|
260
|
+
self._thread = None
|
|
261
|
+
if self.label:
|
|
262
|
+
self.out.note(self.label)
|
|
263
|
+
return self
|
|
264
|
+
|
|
265
|
+
def __exit__(self, *exc: Any) -> bool:
|
|
266
|
+
self._stop.set()
|
|
267
|
+
thread, self._thread = self._thread, None
|
|
268
|
+
if thread is not None:
|
|
269
|
+
thread.join(timeout=1.0)
|
|
270
|
+
self._erase()
|
|
271
|
+
return False # never swallow the block's exception
|
|
272
|
+
|
|
273
|
+
# -- internals ---------------------------------------------------
|
|
274
|
+
|
|
275
|
+
def _enabled(self) -> bool:
|
|
276
|
+
return bool(getattr(self.out, "animated", False))
|
|
277
|
+
|
|
278
|
+
def _paint(self) -> None:
|
|
279
|
+
"""The painter. Every failure here disables the animation, silently."""
|
|
280
|
+
global _hid_cursor
|
|
281
|
+
frames = frames_for(self.stream)
|
|
282
|
+
try:
|
|
283
|
+
# The `atexit` backstop writes to the real stderr, so it only arms when
|
|
284
|
+
# that is the stream being painted. A spinner pointed somewhere else
|
|
285
|
+
# cleans up in its own `finally` and leaves the real terminal alone.
|
|
286
|
+
if self.stream is sys.stderr:
|
|
287
|
+
_hid_cursor = True
|
|
288
|
+
self.stream.write(_HIDE)
|
|
289
|
+
index = 0
|
|
290
|
+
while not self._stop.is_set():
|
|
291
|
+
self._write_frame(frames[index % len(frames)], index % len(frames))
|
|
292
|
+
index += 1
|
|
293
|
+
self._stop.wait(1.0 / FPS)
|
|
294
|
+
except Exception: # noqa: BLE001 — decoration is never load-bearing
|
|
295
|
+
self._stop.set()
|
|
296
|
+
finally:
|
|
297
|
+
try:
|
|
298
|
+
self.stream.write(_SHOW)
|
|
299
|
+
self.stream.flush()
|
|
300
|
+
except Exception: # noqa: BLE001
|
|
301
|
+
pass
|
|
302
|
+
|
|
303
|
+
def _write_frame(self, frame: str, index: int = 0) -> None:
|
|
304
|
+
colour = bool(getattr(self.out, "color_err", False))
|
|
305
|
+
body = "\n".join(" " + row for row in inked(frame, index, colour).split("\n"))
|
|
306
|
+
if self.label:
|
|
307
|
+
# The clips carry a readout in their corners; the wait carries one too.
|
|
308
|
+
took = f"{time.monotonic() - self._start:4.1f}s"
|
|
309
|
+
said = f" {self.label[:LABEL]} {took}"
|
|
310
|
+
if colour:
|
|
311
|
+
said = f" {ui.sgr('muted')}{self.label[:LABEL]}{ui.RESET} {ui.sgr('faint')}{took}{ui.RESET}"
|
|
312
|
+
body = body + "\n" + said
|
|
313
|
+
if self._painted:
|
|
314
|
+
self.stream.write(_UP * self._lines)
|
|
315
|
+
chunks = []
|
|
316
|
+
for line in body.split("\n"):
|
|
317
|
+
chunks.append(_CLEAR_LINE + line + "\n")
|
|
318
|
+
self.stream.write("".join(chunks))
|
|
319
|
+
self.stream.flush()
|
|
320
|
+
self._painted = True
|
|
321
|
+
|
|
322
|
+
def _erase(self) -> None:
|
|
323
|
+
"""Take the region back off the screen and restore the cursor.
|
|
324
|
+
|
|
325
|
+
In a `finally` on purpose: an exception in the wrapped block must not be
|
|
326
|
+
the reason somebody's terminal has no cursor for the rest of the day.
|
|
327
|
+
"""
|
|
328
|
+
if not self._painted:
|
|
329
|
+
return
|
|
330
|
+
self._painted = False
|
|
331
|
+
try:
|
|
332
|
+
self.stream.write(_UP * self._lines)
|
|
333
|
+
for _ in range(self._lines):
|
|
334
|
+
self.stream.write(_CLEAR_LINE + "\n")
|
|
335
|
+
self.stream.write(_UP * self._lines)
|
|
336
|
+
self.stream.write(_SHOW)
|
|
337
|
+
self.stream.flush()
|
|
338
|
+
except Exception: # noqa: BLE001
|
|
339
|
+
pass
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
class NullSpinner:
|
|
343
|
+
"""What a caller gets when it wants the shape without the animation."""
|
|
344
|
+
|
|
345
|
+
def __enter__(self) -> "NullSpinner":
|
|
346
|
+
return self
|
|
347
|
+
|
|
348
|
+
def __exit__(self, *exc: Any) -> bool:
|
|
349
|
+
return False
|
|
350
|
+
|
|
351
|
+
|
|
352
|
+
def spinner(out: Any, label: str = "") -> Any:
|
|
353
|
+
"""The one call site every command uses. Always safe, always a context manager."""
|
|
354
|
+
try:
|
|
355
|
+
return Spinner(out, label)
|
|
356
|
+
except Exception: # noqa: BLE001 — decoration is never load-bearing
|
|
357
|
+
return NullSpinner()
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
# -- the banner -------------------------------------------------------------
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def banner(out: Any, verb: str = "init") -> None:
|
|
364
|
+
"""The wordmark, once, as the install opens.
|
|
365
|
+
|
|
366
|
+
Suppressed only by `--json` and `--quiet` — not by the absence of a tty. Off a
|
|
367
|
+
terminal it is the static ASCII `BANNER`, so it survives a pipe and reads fine
|
|
368
|
+
in a CI log, and a build log that says which tool wrote it is more useful than
|
|
369
|
+
one that does not. At a terminal it is the site's wordmark, and the ink pours
|
|
370
|
+
into it once.
|
|
371
|
+
"""
|
|
372
|
+
if getattr(out, "json_mode", False) or getattr(out, "quiet", False):
|
|
373
|
+
return
|
|
374
|
+
if os.environ.get("EDIFY_NO_ANIM"):
|
|
375
|
+
return
|
|
376
|
+
if getattr(out, "no_anim", False):
|
|
377
|
+
return
|
|
378
|
+
try:
|
|
379
|
+
if getattr(out, "animated", False) and ui.encodes("█▀▄─", sys.stderr):
|
|
380
|
+
_wordmark(out, verb)
|
|
381
|
+
return
|
|
382
|
+
for line in BANNER:
|
|
383
|
+
out.note(line)
|
|
384
|
+
out.note("")
|
|
385
|
+
except Exception: # noqa: BLE001
|
|
386
|
+
pass
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
def _ease(t: float) -> float:
|
|
390
|
+
"""`--e-edify`, cubic-bezier(.2,.8,.2,1), closely enough for twelve frames."""
|
|
391
|
+
return 1.0 - (1.0 - t) ** 3
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
def _mix(a: tuple[int, int, int], b: tuple[int, int, int], t: float) -> tuple[int, int, int]:
|
|
395
|
+
return tuple(round(a[i] + (b[i] - a[i]) * t) for i in range(3)) # type: ignore[return-value]
|
|
396
|
+
|
|
397
|
+
|
|
398
|
+
def ink(row: int, line: str, centre: float, colour: bool) -> str:
|
|
399
|
+
"""One row of the wordmark with the pool at `centre`.
|
|
400
|
+
|
|
401
|
+
Inside the pool a glyph takes the ink: bright at the heart, the deeper edge
|
|
402
|
+
blue at the rim. Outside it keeps the terminal's own foreground — flat is the
|
|
403
|
+
agent alone, the ink is EDIFY. A 16-colour terminal gets one blue.
|
|
404
|
+
"""
|
|
405
|
+
if not colour:
|
|
406
|
+
return line
|
|
407
|
+
palette = ui.PALETTES[ui.theme()]
|
|
408
|
+
bright, edge = ui.rgb(palette["signal"]), ui.rgb(palette["edge"])
|
|
409
|
+
bits = ui.depth()
|
|
410
|
+
half = POOL_HALF[row % len(POOL_HALF)]
|
|
411
|
+
cells = []
|
|
412
|
+
for col, glyph in enumerate(line):
|
|
413
|
+
reach = abs(col - centre) / half
|
|
414
|
+
if glyph == " " or reach > 1.0:
|
|
415
|
+
cells.append(glyph)
|
|
416
|
+
continue
|
|
417
|
+
start = "\033[94m" if bits == 16 else ui.fg(_mix(bright, edge, reach ** 1.6), bits)
|
|
418
|
+
cells.append(start + glyph + ui.RESET)
|
|
419
|
+
return "".join(cells)
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
def inked(frame: str, index: int, colour: bool) -> str:
|
|
423
|
+
"""A frame of the infinity in ink: the head bright, the trail thinning into the
|
|
424
|
+
deeper blue, the curve at rest in the faint tone. Text unchanged without colour."""
|
|
425
|
+
if not colour:
|
|
426
|
+
return frame
|
|
427
|
+
palette = ui.PALETTES[ui.theme()]
|
|
428
|
+
bright, edge = ui.rgb(palette["signal"]), ui.rgb(palette["edge"])
|
|
429
|
+
faint, bits = ui.sgr("faint"), ui.depth()
|
|
430
|
+
ages = TONES[index % len(TONES)]
|
|
431
|
+
rows = []
|
|
432
|
+
for r, row in enumerate(frame.split("\n")):
|
|
433
|
+
cells = []
|
|
434
|
+
for c, glyph in enumerate(row):
|
|
435
|
+
if glyph == " ":
|
|
436
|
+
cells.append(glyph)
|
|
437
|
+
continue
|
|
438
|
+
age = ages.get((r, c))
|
|
439
|
+
if age is None:
|
|
440
|
+
start = faint
|
|
441
|
+
elif bits == 16:
|
|
442
|
+
start = "\033[94m" if age == 0 else "\033[34m"
|
|
443
|
+
else:
|
|
444
|
+
start = ui.fg(_mix(bright, edge, age / TRAIL), bits)
|
|
445
|
+
cells.append(start + glyph + ui.RESET)
|
|
446
|
+
rows.append("".join(cells))
|
|
447
|
+
return "\n".join(rows)
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
def readout(verb: str, colour: bool, width: int = READOUT_WIDTH) -> str:
|
|
451
|
+
"""`EDIFY / INIT ──────── 0.2.0` — the clips' corner readout, as one line."""
|
|
452
|
+
from . import __version__
|
|
453
|
+
|
|
454
|
+
left, right = f"EDIFY / {verb.upper()}", __version__
|
|
455
|
+
rule = "─" * max(3, width - len(left) - len(right) - 2)
|
|
456
|
+
if not colour:
|
|
457
|
+
return f"{left} {rule} {right}"
|
|
458
|
+
muted, faint = ui.sgr("muted"), ui.sgr("faint")
|
|
459
|
+
return f"{muted}{left}{ui.RESET} {faint}{rule}{ui.RESET} {muted}{right}{ui.RESET}"
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
def _wordmark(out: Any, verb: str) -> None:
|
|
463
|
+
"""Paint the wordmark to stderr, pour the ink once, and leave it standing."""
|
|
464
|
+
stream = sys.stderr
|
|
465
|
+
colour = bool(getattr(out, "color_err", False))
|
|
466
|
+
pad = " "
|
|
467
|
+
rows = len(WORDMARK)
|
|
468
|
+
tail = [readout(verb, colour), ui.sgr("muted") + "three documents and a map" + ui.RESET if colour
|
|
469
|
+
else "three documents and a map", ""]
|
|
470
|
+
|
|
471
|
+
def paint(centre: float, first: bool) -> None:
|
|
472
|
+
if not first:
|
|
473
|
+
stream.write(_UP * rows)
|
|
474
|
+
stream.write("".join(
|
|
475
|
+
_CLEAR_LINE + pad + ink(r, WORDMARK[r], centre, colour) + "\n" for r in range(rows)
|
|
476
|
+
))
|
|
477
|
+
stream.flush()
|
|
478
|
+
|
|
479
|
+
if colour:
|
|
480
|
+
start = -max(POOL_HALF) - 1.0
|
|
481
|
+
stream.write(_HIDE)
|
|
482
|
+
try:
|
|
483
|
+
for f in range(POOL_FRAMES + 1):
|
|
484
|
+
centre = start + (POOL_REST - start) * _ease(f / POOL_FRAMES)
|
|
485
|
+
paint(centre, first=f == 0)
|
|
486
|
+
if f < POOL_FRAMES:
|
|
487
|
+
time.sleep(POOL_MS / 1000.0 / POOL_FRAMES)
|
|
488
|
+
finally:
|
|
489
|
+
stream.write(_SHOW)
|
|
490
|
+
else:
|
|
491
|
+
paint(POOL_REST, first=True)
|
|
492
|
+
for line in tail:
|
|
493
|
+
stream.write(pad + line + "\n" if line else "\n")
|
|
494
|
+
stream.flush()
|
|
495
|
+
|
|
496
|
+
|
|
497
|
+
def elapsed(start: float) -> str:
|
|
498
|
+
"""`2.4s` — what a spinner was covering for, said once after it stops."""
|
|
499
|
+
return f"{max(0.0, time.monotonic() - start):.1f}s"
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: build
|
|
3
|
+
description: A plan becomes working software.
|
|
4
|
+
model: cheapest that follows written instructions
|
|
5
|
+
ends-at: a diff and a green suite
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# /build
|
|
9
|
+
|
|
10
|
+
Execute the whole task list in one run, phases in order. This command does not
|
|
11
|
+
plan, does not choose, does not research, and does not improvise.
|
|
12
|
+
|
|
13
|
+
## What you read
|
|
14
|
+
|
|
15
|
+
The approved `tasks.md`. That is the only input. The spec and the plan are
|
|
16
|
+
deliberately withheld: a builder with access to the reasoning behind the plan has
|
|
17
|
+
judgment again, and judgment at build time is the one thing the executor is defined
|
|
18
|
+
by not having.
|
|
19
|
+
|
|
20
|
+
## What you write
|
|
21
|
+
|
|
22
|
+
Code, and the `## Decisions` section of `tasks.md`.
|
|
23
|
+
|
|
24
|
+
## The run
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
for each phase in order:
|
|
28
|
+
for each parallel-safe group in the phase:
|
|
29
|
+
spawn one agent per task
|
|
30
|
+
payload: skill file + task block + ## Decisions
|
|
31
|
+
servers: edify mcp for <role> <phase> # usually zero or one
|
|
32
|
+
run the phase exit check
|
|
33
|
+
edify graph update <the directories that changed>
|
|
34
|
+
append any forced decision to ## Decisions
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Resolve the skill with `edify skills resolve <role> <phase>` — one lookup, one
|
|
38
|
+
line, one file path. Never browse the skills directory to decide.
|
|
39
|
+
|
|
40
|
+
Phase 2 ends with the suite entirely red. That is the correct state and the target
|
|
41
|
+
every later phase is measured against. Phase 7 is `/verify` in a fresh agent that
|
|
42
|
+
wrote none of the code.
|
|
43
|
+
|
|
44
|
+
## The three rules that define this executor
|
|
45
|
+
|
|
46
|
+
- **It does not plan.** No restructuring, no "while I'm here", no better idea.
|
|
47
|
+
- **It does not explore.** The task says where; the graph answers structure; the
|
|
48
|
+
docs server answers library questions. If none of the three has the answer, the
|
|
49
|
+
plan was incomplete and that is a finding, not a gap to fill with judgment.
|
|
50
|
+
- **It does not adapt.** A task that cannot be done as written stops, writes one
|
|
51
|
+
blocker line, and the run continues with independent tasks.
|
|
52
|
+
|
|
53
|
+
## On failure
|
|
54
|
+
|
|
55
|
+
A failed done-check is retried once. On the second failure the debugger runs with
|
|
56
|
+
the accumulated evidence. On the third the task is marked blocked and the run
|
|
57
|
+
continues on tasks that do not depend on it. A blocked task at the end of a run is
|
|
58
|
+
a `/tasks` amendment — a normal Tuesday, not a crisis.
|
|
59
|
+
|
|
60
|
+
## What this command refuses
|
|
61
|
+
|
|
62
|
+
Running against an unapproved plan. Running phases out of order. Editing a contract
|
|
63
|
+
frozen at the end of phase 1. Making a design decision the plan left open without
|
|
64
|
+
recording it in `## Decisions`. Declaring a task done without its check passing.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: plan
|
|
3
|
+
description: A specification becomes technical decisions and a sequence.
|
|
4
|
+
model: strongest
|
|
5
|
+
ends-at: a human
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# /plan
|
|
9
|
+
|
|
10
|
+
Make every decision that binds more than one task, once, so that no task has to
|
|
11
|
+
make one. Skipped for most features, and skipping it is the normal case.
|
|
12
|
+
|
|
13
|
+
## When this runs at all
|
|
14
|
+
|
|
15
|
+
Write a plan when any of these is true: the feature introduces a technology,
|
|
16
|
+
library, or external service this repository does not already use; it spans more
|
|
17
|
+
than one milestone or shippable stage; it needs cross-cutting strategy — a
|
|
18
|
+
migration sequence, a build variant, a bundled asset, a shared component, a config
|
|
19
|
+
surface; or more than one person will build parts of it.
|
|
20
|
+
|
|
21
|
+
Otherwise go straight from `/spec` to `/tasks`. A one-page plan is ceremony, and a
|
|
22
|
+
repository whose plans are all one page should stop writing them.
|
|
23
|
+
|
|
24
|
+
## What you read
|
|
25
|
+
|
|
26
|
+
The approved `spec.md`, and the graph. Nothing else.
|
|
27
|
+
|
|
28
|
+
## What you write
|
|
29
|
+
|
|
30
|
+
`specs/<feature>/plan.md`, in the format at `.edify/formats/plan.format.md`.
|
|
31
|
+
|
|
32
|
+
## The passes
|
|
33
|
+
|
|
34
|
+
1. **Cut into milestones** by dependency, and write each dependency rule with its
|
|
35
|
+
reason. `/tasks` relaxes rules when a plan is amended and cannot do that safely
|
|
36
|
+
without knowing why each one exists.
|
|
37
|
+
2. **Decide the technology.** Each row names the alternative it beat and an exact
|
|
38
|
+
version — `2.3`, not `^2.3` and not `latest`. A row with no alternative is a
|
|
39
|
+
default, and should say so rather than being dressed as a decision; a default is
|
|
40
|
+
much cheaper to revisit six months later.
|
|
41
|
+
3. **Write the cross-cutting strategy.** Migration numbers allocated once here so
|
|
42
|
+
two tasks never claim the same one. Build variants. Bundled assets with a size
|
|
43
|
+
budget stated rather than discovered. Shared components named so three later
|
|
44
|
+
milestones do not each build their own. And the verification budget for any
|
|
45
|
+
assertion the spec marks above `property` on the ladder.
|
|
46
|
+
4. **Resolve the context seeds** — per milestone, `(file, line-start, line-end,
|
|
47
|
+
why)` resolved against the graph, so `/tasks` inherits them instead of
|
|
48
|
+
re-deriving them. A seed without a line range transfers its cost downstream,
|
|
49
|
+
which is the whole thing this document exists to prevent.
|
|
50
|
+
5. **Map the risks**, each to the milestone that mitigates it. A risk with no
|
|
51
|
+
mitigation has been noticed rather than handled, and the row should say that
|
|
52
|
+
rather than looking handled.
|
|
53
|
+
|
|
54
|
+
Run `edify check` before the gate.
|
|
55
|
+
|
|
56
|
+
## What this command refuses
|
|
57
|
+
|
|
58
|
+
Specifying function signatures or data structures beyond the contracts — that is
|
|
59
|
+
`/tasks`, which has the graph queries to make them accurate. A technology row with
|
|
60
|
+
no exact version. A context seed with no line range. Carrying dates: sizes and
|
|
61
|
+
sequences, never a schedule.
|
|
62
|
+
|
|
63
|
+
## The gate
|
|
64
|
+
|
|
65
|
+
Show the human the milestone sequence, the decisions with their alternatives, and
|
|
66
|
+
the risks. This is where an architectural disagreement is cheap.
|
|
67
|
+
|
|
68
|
+
Format: `.edify/formats/plan.format.md` · Example: `.edify/formats/plan.example.md`
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec
|
|
3
|
+
description: A brief becomes a specification.
|
|
4
|
+
model: strongest
|
|
5
|
+
ends-at: a human
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# /spec
|
|
9
|
+
|
|
10
|
+
Turn a couple of sentences into a specification a non-engineer can read and a
|
|
11
|
+
planner can build from. A mistake here is paid for again on every task downstream,
|
|
12
|
+
so this is the slow, expensive command and it is meant to be.
|
|
13
|
+
|
|
14
|
+
## What you read
|
|
15
|
+
|
|
16
|
+
The brief — whatever the person typed, or the file they pointed at. The graph, for
|
|
17
|
+
every claim about this codebase. The existing `specs/<feature>/spec.md` if you are
|
|
18
|
+
amending one. Not the codebase directly: `edify graph where`, `edify graph
|
|
19
|
+
dependents`, and `edify graph defines` answer structural questions exactly, and
|
|
20
|
+
exploring produces a slightly different answer every session.
|
|
21
|
+
|
|
22
|
+
## What you write
|
|
23
|
+
|
|
24
|
+
`specs/<feature>/spec.md`, in the format at `.edify/formats/spec.format.md`. The
|
|
25
|
+
worked example beside it is the calibration — read it before writing the first one.
|
|
26
|
+
|
|
27
|
+
## The loop, bounded at three passes
|
|
28
|
+
|
|
29
|
+
1. Capture the brief verbatim into `## Brief`. Never edit it afterwards. It is the
|
|
30
|
+
only uncontaminated statement of intent in the system, and both the adversary
|
|
31
|
+
and the final review check the result against it rather than against the draft
|
|
32
|
+
that grew out of it.
|
|
33
|
+
2. Draft the intent clauses, the constraints, the requirements, the assertions, and
|
|
34
|
+
the non-goals. Every claim about the codebase comes from a graph query.
|
|
35
|
+
3. Launch one adversary — a separate agent given only the brief and the finished
|
|
36
|
+
draft, never your reasoning. Its question is: what does this feature entail that
|
|
37
|
+
nobody asked for and the draft did not catch? Its findings append to
|
|
38
|
+
`## What this entails` and `## Open questions`, marked adversary-found.
|
|
39
|
+
4. Re-read the draft against the brief. Every intent clause served by at least one
|
|
40
|
+
requirement, every requirement by at least one assertion, every assertion
|
|
41
|
+
carrying a verification kind from the ladder.
|
|
42
|
+
5. Stop when a pass finds nothing new, or at three passes. Hitting the bound is
|
|
43
|
+
information: the brief is genuinely ambiguous, and the residue goes into
|
|
44
|
+
`## Open questions` where a human sees it rather than into more token spend.
|
|
45
|
+
|
|
46
|
+
Run `edify check` before showing anyone the result.
|
|
47
|
+
|
|
48
|
+
## What this command refuses
|
|
49
|
+
|
|
50
|
+
Writing application code. A requirement with no assertion. An assertion that cannot
|
|
51
|
+
fail, or that carries no verification kind. Skipping the adversary because the
|
|
52
|
+
feature looks simple. A citation that is a bare filename rather than `file:line` or
|
|
53
|
+
the literal `new`. Naming a specific library or version — that is a decision, and
|
|
54
|
+
decisions belong to `/plan`.
|
|
55
|
+
|
|
56
|
+
## The gate
|
|
57
|
+
|
|
58
|
+
Show the human: the intent, the requirements, the closure checklist with open rows
|
|
59
|
+
highlighted, the open questions, and a rough cost band. They resolve the questions
|
|
60
|
+
or accept the defaults on the record, and approve. Five minutes, once per feature,
|
|
61
|
+
and it is the step that stops a beautifully built wrong thing.
|
|
62
|
+
|
|
63
|
+
Format: `.edify/formats/spec.format.md` · Example: `.edify/formats/spec.example.md`
|