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.
Files changed (102) hide show
  1. edify/__init__.py +19 -0
  2. edify/__main__.py +6 -0
  3. edify/_toml.py +286 -0
  4. edify/agents.py +261 -0
  5. edify/anim.py +499 -0
  6. edify/assets/commands/build.md +64 -0
  7. edify/assets/commands/plan.md +68 -0
  8. edify/assets/commands/spec.md +63 -0
  9. edify/assets/commands/tasks.md +65 -0
  10. edify/assets/commands/verify.md +67 -0
  11. edify/assets/formats/plan.example.md +455 -0
  12. edify/assets/formats/plan.format.md +128 -0
  13. edify/assets/formats/spec.example.md +483 -0
  14. edify/assets/formats/spec.format.md +116 -0
  15. edify/assets/formats/tasks.example.md +712 -0
  16. edify/assets/formats/tasks.format.md +199 -0
  17. edify/assets/harvest/harvest.md +91 -0
  18. edify/assets/harvest/sources.md +295 -0
  19. edify/assets/harvest/vocab.md +52 -0
  20. edify/assets/manifest.md +30 -0
  21. edify/assets/mcp/default-registry.md +66 -0
  22. edify/assets/skills/adversary.md +61 -0
  23. edify/assets/skills/debugger.md +64 -0
  24. edify/assets/skills/implementer-general.md +53 -0
  25. edify/assets/skills/implementer-go.md +63 -0
  26. edify/assets/skills/implementer-node.md +61 -0
  27. edify/assets/skills/implementer-postgres.md +63 -0
  28. edify/assets/skills/implementer-python.md +65 -0
  29. edify/assets/skills/implementer-react.md +65 -0
  30. edify/assets/skills/planner.md +58 -0
  31. edify/assets/skills/test-writer-node.md +64 -0
  32. edify/assets/skills/test-writer-python.md +60 -0
  33. edify/assets/skills/verifier.md +67 -0
  34. edify/assets/templates/CLAUDE.md +18 -0
  35. edify/assets.py +77 -0
  36. edify/cli.py +681 -0
  37. edify/commands/__init__.py +1 -0
  38. edify/commands/check_cmd.py +72 -0
  39. edify/commands/doctor_cmd.py +206 -0
  40. edify/commands/feedback_cmd.py +90 -0
  41. edify/commands/governance_cmd.py +65 -0
  42. edify/commands/graph_cmd.py +156 -0
  43. edify/commands/harvest_cmd.py +538 -0
  44. edify/commands/init_cmd.py +333 -0
  45. edify/commands/init_new_cmd.py +151 -0
  46. edify/commands/license_cmd.py +80 -0
  47. edify/commands/mcp_cmd.py +159 -0
  48. edify/commands/self_cmd.py +185 -0
  49. edify/commands/setup_cmd.py +79 -0
  50. edify/commands/skills_cmd.py +177 -0
  51. edify/commands/upgrade_cmd.py +178 -0
  52. edify/context.py +57 -0
  53. edify/conventions.py +275 -0
  54. edify/detect.py +313 -0
  55. edify/distribution.py +40 -0
  56. edify/errors.py +66 -0
  57. edify/feedback.py +207 -0
  58. edify/formats/__init__.py +11 -0
  59. edify/formats/check.py +573 -0
  60. edify/formats/document.py +238 -0
  61. edify/formats/finding.py +50 -0
  62. edify/formats/fix.py +114 -0
  63. edify/formats/mcp.py +126 -0
  64. edify/formats/plan.py +151 -0
  65. edify/formats/skill.py +139 -0
  66. edify/formats/spec.py +164 -0
  67. edify/formats/tasks.py +321 -0
  68. edify/governance.py +316 -0
  69. edify/graph/__init__.py +11 -0
  70. edify/graph/extract.py +351 -0
  71. edify/graph/ignore.py +107 -0
  72. edify/graph/langs/__init__.py +93 -0
  73. edify/graph/langs/ctags.py +145 -0
  74. edify/graph/langs/markdown.py +41 -0
  75. edify/graph/langs/patterns.py +361 -0
  76. edify/graph/langs/python_ast.py +154 -0
  77. edify/graph/langs/sqlish.py +86 -0
  78. edify/graph/model.py +102 -0
  79. edify/graph/queries.py +211 -0
  80. edify/graph/store.py +157 -0
  81. edify/harvest/__init__.py +28 -0
  82. edify/harvest/ledger.py +191 -0
  83. edify/harvest/screen.py +236 -0
  84. edify/harvest/sources.py +298 -0
  85. edify/host.py +345 -0
  86. edify/interview.py +354 -0
  87. edify/library.py +176 -0
  88. edify/licensing/__init__.py +30 -0
  89. edify/licensing/ed25519.py +154 -0
  90. edify/licensing/projects.py +223 -0
  91. edify/licensing/tier.py +172 -0
  92. edify/licensing/token.py +149 -0
  93. edify/paths.py +282 -0
  94. edify/selfinstall.py +244 -0
  95. edify/skills.py +108 -0
  96. edify/tsv.py +109 -0
  97. edify/ui.py +334 -0
  98. edify_agents_cli-0.2.0.dist-info/METADATA +408 -0
  99. edify_agents_cli-0.2.0.dist-info/RECORD +102 -0
  100. edify_agents_cli-0.2.0.dist-info/WHEEL +4 -0
  101. edify_agents_cli-0.2.0.dist-info/entry_points.txt +2 -0
  102. 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"]