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/detect.py
ADDED
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
"""Stack detection, from the manifest files that are actually present.
|
|
2
|
+
|
|
3
|
+
`edify init` step 1. No model call and no guessing: a framework is detected because
|
|
4
|
+
its name is in a dependency list, not because a directory is called `api`. What is
|
|
5
|
+
not detected is simply absent, and `init` says so.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
import re
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
|
|
15
|
+
from . import _toml as tomllib
|
|
16
|
+
from .graph.ignore import IgnoreRules
|
|
17
|
+
from .graph.langs import EXTENSIONS
|
|
18
|
+
|
|
19
|
+
# dependency name → the `tech` id used in skill frontmatter. Exact match on the
|
|
20
|
+
# declared name, because a substring match calls every repo with `react-scripts`
|
|
21
|
+
# a React repo.
|
|
22
|
+
FRAMEWORK_BY_DEP = {
|
|
23
|
+
"react": "react",
|
|
24
|
+
"react-dom": "react",
|
|
25
|
+
"next": "nextjs",
|
|
26
|
+
"vue": "vue",
|
|
27
|
+
"nuxt": "vue",
|
|
28
|
+
"svelte": "svelte",
|
|
29
|
+
"@angular/core": "angular",
|
|
30
|
+
"express": "express",
|
|
31
|
+
"fastify": "fastify",
|
|
32
|
+
"@nestjs/core": "nestjs",
|
|
33
|
+
"koa": "express",
|
|
34
|
+
"hono": "express",
|
|
35
|
+
"prisma": "prisma",
|
|
36
|
+
"@prisma/client": "prisma",
|
|
37
|
+
"typeorm": "typeorm",
|
|
38
|
+
"drizzle-orm": "drizzle",
|
|
39
|
+
"pg": "postgres",
|
|
40
|
+
"postgres": "postgres",
|
|
41
|
+
"mysql2": "mysql",
|
|
42
|
+
"mongoose": "mongodb",
|
|
43
|
+
"redis": "redis",
|
|
44
|
+
"django": "django",
|
|
45
|
+
"flask": "flask",
|
|
46
|
+
"fastapi": "fastapi",
|
|
47
|
+
"sqlalchemy": "sqlalchemy",
|
|
48
|
+
"psycopg": "postgres",
|
|
49
|
+
"psycopg2": "postgres",
|
|
50
|
+
"psycopg2-binary": "postgres",
|
|
51
|
+
"asyncpg": "postgres",
|
|
52
|
+
"pydantic": "pydantic",
|
|
53
|
+
"celery": "celery",
|
|
54
|
+
"boto3": "aws",
|
|
55
|
+
"rails": "rails",
|
|
56
|
+
"sinatra": "rails",
|
|
57
|
+
"laravel/framework": "laravel",
|
|
58
|
+
"symfony/framework-bundle": "symfony",
|
|
59
|
+
"gin-gonic/gin": "gin",
|
|
60
|
+
"labstack/echo": "echo",
|
|
61
|
+
"spring-boot-starter-web": "spring",
|
|
62
|
+
"actix-web": "actix",
|
|
63
|
+
"axum": "axum",
|
|
64
|
+
"tokio": "tokio",
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
TEST_RUNNER_BY_DEP = {
|
|
68
|
+
"jest": "jest",
|
|
69
|
+
"vitest": "vitest",
|
|
70
|
+
"mocha": "mocha",
|
|
71
|
+
"@playwright/test": "playwright",
|
|
72
|
+
"cypress": "cypress",
|
|
73
|
+
"ava": "ava",
|
|
74
|
+
"pytest": "pytest",
|
|
75
|
+
"unittest2": "unittest",
|
|
76
|
+
"nose2": "nose2",
|
|
77
|
+
"rspec": "rspec",
|
|
78
|
+
"phpunit/phpunit": "phpunit",
|
|
79
|
+
"junit": "junit",
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
@dataclass
|
|
84
|
+
class Stack:
|
|
85
|
+
languages: list[str] = field(default_factory=list)
|
|
86
|
+
frameworks: list[str] = field(default_factory=list)
|
|
87
|
+
package_manager: str = "-"
|
|
88
|
+
test_runner: str = "-"
|
|
89
|
+
manifests: list[str] = field(default_factory=list)
|
|
90
|
+
file_counts: dict[str, int] = field(default_factory=dict)
|
|
91
|
+
|
|
92
|
+
@property
|
|
93
|
+
def tech(self) -> list[str]:
|
|
94
|
+
"""The ids a skill's `tech` field is matched against."""
|
|
95
|
+
return sorted(set(self.languages) | set(self.frameworks))
|
|
96
|
+
|
|
97
|
+
def as_dict(self) -> dict[str, object]:
|
|
98
|
+
return {
|
|
99
|
+
"languages": self.languages,
|
|
100
|
+
"frameworks": self.frameworks,
|
|
101
|
+
"package_manager": self.package_manager,
|
|
102
|
+
"test_runner": self.test_runner,
|
|
103
|
+
"manifests": self.manifests,
|
|
104
|
+
"file_counts": self.file_counts,
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def detect(root: Path) -> Stack:
|
|
109
|
+
stack = Stack()
|
|
110
|
+
stack.file_counts = _census(root)
|
|
111
|
+
stack.languages = _languages(stack.file_counts)
|
|
112
|
+
|
|
113
|
+
frameworks: set[str] = set()
|
|
114
|
+
for name, manifest in declared_packages(root).items():
|
|
115
|
+
if manifest not in stack.manifests:
|
|
116
|
+
stack.manifests.append(manifest)
|
|
117
|
+
tech = FRAMEWORK_BY_DEP.get(name)
|
|
118
|
+
if tech:
|
|
119
|
+
frameworks.add(tech)
|
|
120
|
+
runner = TEST_RUNNER_BY_DEP.get(name)
|
|
121
|
+
if runner and stack.test_runner == "-":
|
|
122
|
+
stack.test_runner = runner
|
|
123
|
+
stack.frameworks = sorted(frameworks)
|
|
124
|
+
stack.manifests.sort()
|
|
125
|
+
|
|
126
|
+
stack.package_manager = _package_manager(root)
|
|
127
|
+
if stack.test_runner == "-":
|
|
128
|
+
stack.test_runner = _fallback_runner(root, stack.languages)
|
|
129
|
+
return stack
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def declared_packages(root: Path) -> dict[str, str]:
|
|
133
|
+
"""Declared dependency name → the manifest that declares it.
|
|
134
|
+
|
|
135
|
+
Declared, not imported. An import of something no manifest names is a fact
|
|
136
|
+
about the code and belongs in an edge, not in a package node.
|
|
137
|
+
"""
|
|
138
|
+
out: dict[str, str] = {}
|
|
139
|
+
|
|
140
|
+
pkg = root / "package.json"
|
|
141
|
+
if pkg.is_file():
|
|
142
|
+
data = _json(pkg)
|
|
143
|
+
for section in ("dependencies", "devDependencies", "peerDependencies"):
|
|
144
|
+
for name in (data.get(section) or {}):
|
|
145
|
+
out.setdefault(str(name), "package.json")
|
|
146
|
+
|
|
147
|
+
pyproject = root / "pyproject.toml"
|
|
148
|
+
if pyproject.is_file():
|
|
149
|
+
data = _toml(pyproject)
|
|
150
|
+
project = data.get("project") or {}
|
|
151
|
+
for entry in project.get("dependencies") or []:
|
|
152
|
+
out.setdefault(_pep508_name(str(entry)), "pyproject.toml")
|
|
153
|
+
for group in (project.get("optional-dependencies") or {}).values():
|
|
154
|
+
for entry in group:
|
|
155
|
+
out.setdefault(_pep508_name(str(entry)), "pyproject.toml")
|
|
156
|
+
poetry = ((data.get("tool") or {}).get("poetry") or {}).get("dependencies") or {}
|
|
157
|
+
for name in poetry:
|
|
158
|
+
if name != "python":
|
|
159
|
+
out.setdefault(str(name).lower(), "pyproject.toml")
|
|
160
|
+
|
|
161
|
+
for req in ("requirements.txt", "requirements-dev.txt", "requirements/base.txt"):
|
|
162
|
+
path = root / req
|
|
163
|
+
if path.is_file():
|
|
164
|
+
for line in _lines(path):
|
|
165
|
+
line = line.split("#", 1)[0].strip()
|
|
166
|
+
if line and not line.startswith("-"):
|
|
167
|
+
out.setdefault(_pep508_name(line), req)
|
|
168
|
+
|
|
169
|
+
gomod = root / "go.mod"
|
|
170
|
+
if gomod.is_file():
|
|
171
|
+
for line in _lines(gomod):
|
|
172
|
+
m = re.match(r"^\s*(?:require\s+)?([a-z0-9./\-]+\.[a-z]{2,}/[\w./\-]+)\s+v", line)
|
|
173
|
+
if m:
|
|
174
|
+
path = m.group(1)
|
|
175
|
+
out.setdefault("/".join(path.split("/")[-2:]), "go.mod")
|
|
176
|
+
|
|
177
|
+
cargo = root / "Cargo.toml"
|
|
178
|
+
if cargo.is_file():
|
|
179
|
+
data = _toml(cargo)
|
|
180
|
+
for section in ("dependencies", "dev-dependencies", "build-dependencies"):
|
|
181
|
+
for name in (data.get(section) or {}):
|
|
182
|
+
out.setdefault(str(name), "Cargo.toml")
|
|
183
|
+
|
|
184
|
+
gemfile = root / "Gemfile"
|
|
185
|
+
if gemfile.is_file():
|
|
186
|
+
for line in _lines(gemfile):
|
|
187
|
+
m = re.match(r"""^\s*gem\s+['"]([^'"]+)['"]""", line)
|
|
188
|
+
if m:
|
|
189
|
+
out.setdefault(m.group(1), "Gemfile")
|
|
190
|
+
|
|
191
|
+
composer = root / "composer.json"
|
|
192
|
+
if composer.is_file():
|
|
193
|
+
data = _json(composer)
|
|
194
|
+
for section in ("require", "require-dev"):
|
|
195
|
+
for name in (data.get(section) or {}):
|
|
196
|
+
out.setdefault(str(name), "composer.json")
|
|
197
|
+
|
|
198
|
+
for gradle in ("build.gradle", "build.gradle.kts"):
|
|
199
|
+
path = root / gradle
|
|
200
|
+
if path.is_file():
|
|
201
|
+
for line in _lines(path):
|
|
202
|
+
m = re.search(r"""['"]([\w.\-]+):([\w.\-]+):[\w.\-+]+['"]""", line)
|
|
203
|
+
if m:
|
|
204
|
+
out.setdefault(m.group(2), gradle)
|
|
205
|
+
|
|
206
|
+
pom = root / "pom.xml"
|
|
207
|
+
if pom.is_file():
|
|
208
|
+
text = pom.read_text(encoding="utf-8", errors="replace")
|
|
209
|
+
for m in re.finditer(r"<artifactId>([\w.\-]+)</artifactId>", text):
|
|
210
|
+
out.setdefault(m.group(1), "pom.xml")
|
|
211
|
+
|
|
212
|
+
return out
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
# ---------------------------------------------------------------------------
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _languages(counts: dict[str, int]) -> list[str]:
|
|
219
|
+
"""Which languages this repository is actually written in.
|
|
220
|
+
|
|
221
|
+
Two files, or a fifth of the source tree. The proportional half is what keeps a
|
|
222
|
+
small repository from losing its only language; the absolute half is what keeps
|
|
223
|
+
one stray script in a large repository from adding a language — and a skill file
|
|
224
|
+
— that nobody works in.
|
|
225
|
+
"""
|
|
226
|
+
total = sum(counts.values())
|
|
227
|
+
if not total:
|
|
228
|
+
return []
|
|
229
|
+
kept = [
|
|
230
|
+
lang
|
|
231
|
+
for lang, count in counts.items()
|
|
232
|
+
if count >= 2 or count / total >= 0.2
|
|
233
|
+
]
|
|
234
|
+
return sorted(kept, key=lambda lang: (-counts[lang], lang))[:8]
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def _census(root: Path) -> dict[str, int]:
|
|
238
|
+
rules = IgnoreRules(root)
|
|
239
|
+
counts: dict[str, int] = {}
|
|
240
|
+
import os
|
|
241
|
+
|
|
242
|
+
for dirpath, dirnames, filenames in os.walk(root):
|
|
243
|
+
here = Path(dirpath)
|
|
244
|
+
rel_dir = here.relative_to(root).as_posix()
|
|
245
|
+
dirnames[:] = [
|
|
246
|
+
d for d in dirnames if not rules.skip_dir(d, d if rel_dir == "." else f"{rel_dir}/{d}")
|
|
247
|
+
]
|
|
248
|
+
for name in filenames:
|
|
249
|
+
language = EXTENSIONS.get(Path(name).suffix.lower())
|
|
250
|
+
if language and language != "markdown":
|
|
251
|
+
counts[language] = counts.get(language, 0) + 1
|
|
252
|
+
return counts
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def _package_manager(root: Path) -> str:
|
|
256
|
+
for lockfile, name in (
|
|
257
|
+
("pnpm-lock.yaml", "pnpm"),
|
|
258
|
+
("yarn.lock", "yarn"),
|
|
259
|
+
("bun.lockb", "bun"),
|
|
260
|
+
("package-lock.json", "npm"),
|
|
261
|
+
("uv.lock", "uv"),
|
|
262
|
+
("poetry.lock", "poetry"),
|
|
263
|
+
("Pipfile.lock", "pipenv"),
|
|
264
|
+
("go.sum", "go"),
|
|
265
|
+
("Cargo.lock", "cargo"),
|
|
266
|
+
("Gemfile.lock", "bundler"),
|
|
267
|
+
("composer.lock", "composer"),
|
|
268
|
+
):
|
|
269
|
+
if (root / lockfile).is_file():
|
|
270
|
+
return name
|
|
271
|
+
if (root / "requirements.txt").is_file():
|
|
272
|
+
return "pip"
|
|
273
|
+
if (root / "package.json").is_file():
|
|
274
|
+
return "npm"
|
|
275
|
+
return "-"
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
def _fallback_runner(root: Path, languages: list[str]) -> str:
|
|
279
|
+
if (root / "pytest.ini").is_file() or (root / "conftest.py").is_file():
|
|
280
|
+
return "pytest"
|
|
281
|
+
if "go" in languages:
|
|
282
|
+
return "go test"
|
|
283
|
+
if "rust" in languages:
|
|
284
|
+
return "cargo test"
|
|
285
|
+
if "python" in languages:
|
|
286
|
+
return "pytest"
|
|
287
|
+
return "-"
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def _json(path: Path) -> dict:
|
|
291
|
+
try:
|
|
292
|
+
return json.loads(path.read_text(encoding="utf-8", errors="replace")) or {}
|
|
293
|
+
except (OSError, json.JSONDecodeError):
|
|
294
|
+
return {}
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def _toml(path: Path) -> dict:
|
|
298
|
+
try:
|
|
299
|
+
with path.open("rb") as fh:
|
|
300
|
+
return tomllib.load(fh)
|
|
301
|
+
except (OSError, tomllib.TOMLDecodeError):
|
|
302
|
+
return {}
|
|
303
|
+
|
|
304
|
+
|
|
305
|
+
def _lines(path: Path) -> list[str]:
|
|
306
|
+
try:
|
|
307
|
+
return path.read_text(encoding="utf-8", errors="replace").splitlines()
|
|
308
|
+
except OSError:
|
|
309
|
+
return []
|
|
310
|
+
|
|
311
|
+
|
|
312
|
+
def _pep508_name(spec: str) -> str:
|
|
313
|
+
return re.split(r"[\[<>=!~;\s]", spec.strip(), maxsplit=1)[0].strip().lower()
|
edify/distribution.py
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""The names this package is published and found under.
|
|
2
|
+
|
|
3
|
+
Written once, so that `selfinstall`, `governance`, `feedback`, `assets` and `errors`
|
|
4
|
+
cannot disagree about them. The old third-party name is deliberately absent: it
|
|
5
|
+
belongs to another project, and a name that is not here cannot be reached by
|
|
6
|
+
`self update`.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
#: The public edition on PyPI. `pyproject.toml` spells the same string on one line,
|
|
10
|
+
#: because `selfinstall.is_source_checkout` reads it literally.
|
|
11
|
+
DIST_NAME = "edify-agents-cli"
|
|
12
|
+
|
|
13
|
+
#: The team edition, published separately and installed by licence.
|
|
14
|
+
TEAM_DIST_NAME = "edify-agents-teams"
|
|
15
|
+
|
|
16
|
+
#: The public repository, as `owner/name`.
|
|
17
|
+
PUBLIC_REPO = "EDIFY-agents/EDIFY"
|
|
18
|
+
|
|
19
|
+
#: The public repository's home page.
|
|
20
|
+
PUBLIC_URL = "https://github.com/" + PUBLIC_REPO
|
|
21
|
+
|
|
22
|
+
#: Where a new issue is opened from the command line.
|
|
23
|
+
ISSUES_URL = PUBLIC_URL + "/issues/new"
|
|
24
|
+
|
|
25
|
+
#: The address a licence request goes to.
|
|
26
|
+
CONTACT_EMAIL = "santiago92746@gmail.com"
|
|
27
|
+
|
|
28
|
+
#: Where a person asks for a team or partner licence: an email address and the
|
|
29
|
+
#: public issues page.
|
|
30
|
+
CONTACT = CONTACT_EMAIL + " or " + PUBLIC_URL + "/issues"
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"DIST_NAME",
|
|
34
|
+
"TEAM_DIST_NAME",
|
|
35
|
+
"PUBLIC_REPO",
|
|
36
|
+
"PUBLIC_URL",
|
|
37
|
+
"ISSUES_URL",
|
|
38
|
+
"CONTACT_EMAIL",
|
|
39
|
+
"CONTACT",
|
|
40
|
+
]
|
edify/errors.py
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""The two failure shapes the CLI has.
|
|
2
|
+
|
|
3
|
+
`EdifyError` is a condition the user can fix — a missing graph, an unreadable
|
|
4
|
+
registry, a licence that does not cover a command. It prints one line and exits
|
|
5
|
+
non-zero. Anything else is a bug and gets a traceback, because hiding one costs
|
|
6
|
+
more than it saves.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from .distribution import CONTACT
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class EdifyError(Exception):
|
|
15
|
+
"""A condition the person running the command can do something about."""
|
|
16
|
+
|
|
17
|
+
exit_code = 1
|
|
18
|
+
|
|
19
|
+
def __init__(self, message: str, hint: str | None = None) -> None:
|
|
20
|
+
super().__init__(message)
|
|
21
|
+
self.message = message
|
|
22
|
+
self.hint = hint
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class NotInstalled(EdifyError):
|
|
26
|
+
"""`.edify/` is absent — the repository has never been initialised."""
|
|
27
|
+
|
|
28
|
+
exit_code = 3
|
|
29
|
+
|
|
30
|
+
def __init__(self, root: str) -> None:
|
|
31
|
+
super().__init__(
|
|
32
|
+
f"no .edify/ directory under {root}",
|
|
33
|
+
hint="run `edify init` in the repository root",
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class GraphMissing(EdifyError):
|
|
38
|
+
"""The graph has not been extracted yet, or was removed."""
|
|
39
|
+
|
|
40
|
+
exit_code = 4
|
|
41
|
+
|
|
42
|
+
def __init__(self) -> None:
|
|
43
|
+
super().__init__(
|
|
44
|
+
"no graph on disk",
|
|
45
|
+
hint="run `edify graph build`",
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class TierRequired(EdifyError):
|
|
50
|
+
"""A team or partner licence is needed. Stated plainly, with both doors.
|
|
51
|
+
|
|
52
|
+
There is no price and no purchase: a licence is issued on request, and this is
|
|
53
|
+
the one sentence that says how to ask for one. Every refusal and every soft
|
|
54
|
+
cap reuses it rather than retyping it.
|
|
55
|
+
|
|
56
|
+
No new exit code: 7 still means "this needs a licence", and a second one would
|
|
57
|
+
have to be documented in three places to buy nothing.
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
exit_code = 7
|
|
61
|
+
|
|
62
|
+
def __init__(self, feature: str, plan: str = "team") -> None:
|
|
63
|
+
super().__init__(
|
|
64
|
+
f"{feature} needs a team or partner licence",
|
|
65
|
+
hint=f"have a token? edify license activate <token> · ask for one: {CONTACT}",
|
|
66
|
+
)
|
edify/feedback.py
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
"""Asking how this is going, without becoming a tool that phones home.
|
|
2
|
+
|
|
3
|
+
EDIFY commits to no telemetry — not anonymous, not aggregate, not opt-out — and
|
|
4
|
+
the reason is the person running it: frequently the one who has to explain to
|
|
5
|
+
somebody external what touched the source tree. That
|
|
6
|
+
commitment is not weakened here, so this module is built to the opposite shape from
|
|
7
|
+
the usual one:
|
|
8
|
+
|
|
9
|
+
* Nothing is ever transmitted. `edify feedback` writes a file on this machine and
|
|
10
|
+
prints where it is. Sending it is a thing the person does, with a command they can
|
|
11
|
+
read, to an address they can see.
|
|
12
|
+
* Nothing is collected in the background. There is no event, no counter of what you
|
|
13
|
+
ran, no repository name, no path, no stack. The file contains the answers typed
|
|
14
|
+
into it and three lines about the install, and you can read the whole thing before
|
|
15
|
+
deciding anybody else should.
|
|
16
|
+
* The invitation appears at most once per released version, only on a real terminal,
|
|
17
|
+
and `edify feedback off` ends it permanently.
|
|
18
|
+
|
|
19
|
+
The one piece of state is a small file in the user config directory — never inside a
|
|
20
|
+
repository — holding a run counter and which version last asked. It is written only
|
|
21
|
+
on interactive runs, so a CI job, a pipe, or a model calling the binary leaves no
|
|
22
|
+
trace at all.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import os
|
|
28
|
+
import platform
|
|
29
|
+
from dataclasses import dataclass
|
|
30
|
+
from datetime import date
|
|
31
|
+
from pathlib import Path
|
|
32
|
+
|
|
33
|
+
from . import __version__, distribution
|
|
34
|
+
from .paths import user_config_dir
|
|
35
|
+
from .tsv import read_kv, write_kv
|
|
36
|
+
from .ui import Out
|
|
37
|
+
|
|
38
|
+
# The invitation waits until somebody has actually used the tool. One run is not an
|
|
39
|
+
# opinion, and asking at that point is a pop-up rather than a question.
|
|
40
|
+
INVITE_AFTER_RUNS = 3
|
|
41
|
+
|
|
42
|
+
ISSUES_URL = distribution.ISSUES_URL
|
|
43
|
+
REPO = distribution.PUBLIC_REPO
|
|
44
|
+
|
|
45
|
+
QUESTIONS = (
|
|
46
|
+
("doing", " What were you using EDIFY for?"),
|
|
47
|
+
("worked", " What worked?"),
|
|
48
|
+
("friction", " What got in the way?"),
|
|
49
|
+
("change", " What would you change first?"),
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def state_path() -> Path:
|
|
54
|
+
return user_config_dir() / "state"
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _load() -> dict[str, str]:
|
|
58
|
+
return read_kv(state_path())
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _save(values: dict[str, str]) -> None:
|
|
62
|
+
try:
|
|
63
|
+
write_kv(state_path(), values)
|
|
64
|
+
except OSError:
|
|
65
|
+
pass # a read-only home is not a reason for a command to fail
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def disabled() -> bool:
|
|
69
|
+
if os.environ.get("EDIFY_NO_FEEDBACK"):
|
|
70
|
+
return True
|
|
71
|
+
return _load().get("feedback", "on") == "off"
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def set_enabled(on: bool) -> None:
|
|
75
|
+
values = _load()
|
|
76
|
+
values["feedback"] = "on" if on else "off"
|
|
77
|
+
_save(values)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
# -- the invitation ----------------------------------------------------------
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def maybe_invite(out: Out) -> None:
|
|
84
|
+
"""One dim line on stderr, at most once per version. Never blocks, never asks.
|
|
85
|
+
|
|
86
|
+
Called on every CLI entry, and on all but a handful of them it returns without
|
|
87
|
+
touching the disk.
|
|
88
|
+
"""
|
|
89
|
+
if not out.interactive or disabled():
|
|
90
|
+
return
|
|
91
|
+
|
|
92
|
+
values = _load()
|
|
93
|
+
runs = _int(values.get("runs", "0")) + 1
|
|
94
|
+
values["runs"] = str(runs)
|
|
95
|
+
values["version"] = __version__
|
|
96
|
+
_save(values)
|
|
97
|
+
|
|
98
|
+
if values.get("invited") == __version__ or runs < INVITE_AFTER_RUNS:
|
|
99
|
+
return
|
|
100
|
+
values["invited"] = __version__
|
|
101
|
+
_save(values)
|
|
102
|
+
|
|
103
|
+
out.prompt_line("")
|
|
104
|
+
out.prompt_line(
|
|
105
|
+
out.c(" How is EDIFY working on this codebase?", "bold")
|
|
106
|
+
+ out.c(" `edify feedback` — four questions.", "dim")
|
|
107
|
+
)
|
|
108
|
+
out.prompt_line(
|
|
109
|
+
out.c(
|
|
110
|
+
" It writes a file on this machine and sends nothing."
|
|
111
|
+
" `edify feedback off` and this line never appears again.",
|
|
112
|
+
"dim",
|
|
113
|
+
)
|
|
114
|
+
)
|
|
115
|
+
out.prompt_line("")
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def _int(value: str) -> int:
|
|
119
|
+
try:
|
|
120
|
+
return int(value)
|
|
121
|
+
except ValueError:
|
|
122
|
+
return 0
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
# -- writing one entry -------------------------------------------------------
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@dataclass
|
|
129
|
+
class Entry:
|
|
130
|
+
answers: dict[str, str]
|
|
131
|
+
contact: str = ""
|
|
132
|
+
|
|
133
|
+
def render(self) -> str:
|
|
134
|
+
lines = [
|
|
135
|
+
"# EDIFY feedback",
|
|
136
|
+
"",
|
|
137
|
+
f"- edify: {__version__}",
|
|
138
|
+
f"- python: {platform.python_version()} on {platform.system()} {platform.machine()}",
|
|
139
|
+
f"- written: {date.today().isoformat()}",
|
|
140
|
+
]
|
|
141
|
+
if self.contact:
|
|
142
|
+
lines.append(f"- contact: {self.contact}")
|
|
143
|
+
lines.append("")
|
|
144
|
+
for key, question in QUESTIONS:
|
|
145
|
+
answer = self.answers.get(key, "").strip()
|
|
146
|
+
if not answer:
|
|
147
|
+
continue
|
|
148
|
+
lines.append(f"## {question.strip()}")
|
|
149
|
+
lines.append("")
|
|
150
|
+
lines.append(answer)
|
|
151
|
+
lines.append("")
|
|
152
|
+
return "\n".join(lines).rstrip() + "\n"
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def directory() -> Path:
|
|
156
|
+
return user_config_dir() / "feedback"
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def existing() -> list[Path]:
|
|
160
|
+
folder = directory()
|
|
161
|
+
if not folder.is_dir():
|
|
162
|
+
return []
|
|
163
|
+
return sorted(folder.glob("*.md"))
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def write(entry: Entry) -> Path:
|
|
167
|
+
folder = directory()
|
|
168
|
+
folder.mkdir(parents=True, exist_ok=True)
|
|
169
|
+
path = folder / f"{len(existing()) + 1:04d}.md"
|
|
170
|
+
path.write_text(entry.render(), encoding="utf-8")
|
|
171
|
+
|
|
172
|
+
values = _load()
|
|
173
|
+
values["given"] = str(_int(values.get("given", "0")) + 1)
|
|
174
|
+
_save(values)
|
|
175
|
+
return path
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def how_to_send(path: Path) -> list[str]:
|
|
179
|
+
"""The two ways to send it, both of which the person performs themselves."""
|
|
180
|
+
return [
|
|
181
|
+
f"gh issue create --repo {REPO} --title 'feedback' --body-file \"{path}\"",
|
|
182
|
+
f"or paste it into {ISSUES_URL}",
|
|
183
|
+
]
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def interview(out: Out) -> Entry | None:
|
|
187
|
+
"""Four questions. Returns None if there is nobody to ask."""
|
|
188
|
+
if not out.interactive:
|
|
189
|
+
return None
|
|
190
|
+
|
|
191
|
+
out.prompt_line("")
|
|
192
|
+
out.prompt_line(out.c(" Four questions, all skippable with enter.", "bold"))
|
|
193
|
+
out.prompt_line(
|
|
194
|
+
out.c(
|
|
195
|
+
f" The answers go to a file under {directory()} and travel no further"
|
|
196
|
+
" until you send them.",
|
|
197
|
+
"dim",
|
|
198
|
+
)
|
|
199
|
+
)
|
|
200
|
+
out.prompt_line("")
|
|
201
|
+
|
|
202
|
+
answers: dict[str, str] = {}
|
|
203
|
+
for key, question in QUESTIONS:
|
|
204
|
+
answers[key] = out.ask(question)
|
|
205
|
+
contact = out.ask(" Your email, if you want a reply (enter to skip)")
|
|
206
|
+
out.prompt_line("")
|
|
207
|
+
return Entry(answers=answers, contact=contact)
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""The three artifact formats, plus the two registry formats.
|
|
2
|
+
|
|
3
|
+
Markdown with flat YAML frontmatter — git-native, readable on any forge, no build
|
|
4
|
+
step. Everything here parses; nothing here blocks. `edify check` reports what is
|
|
5
|
+
wrong and a person or a CI job decides what that means.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from .document import Document, Section, Table, parse_document
|
|
9
|
+
from .finding import Finding, Level
|
|
10
|
+
|
|
11
|
+
__all__ = ["Document", "Section", "Table", "parse_document", "Finding", "Level"]
|