framework-py 0.1.0.dev3__py3-none-any.whl → 0.1.0.dev4__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.
- framework/__init__.py +5 -0
- framework/__main__.py +64 -5
- framework/_agents_md.py +210 -0
- framework/_assets/adopt/rules.json +161 -0
- framework/_assets/features/jupyter.json +39 -0
- framework/_assets/features/quarto.json +18 -0
- framework/_assets/features/quarto_manuscript.json +35 -0
- framework/_assets/features/quarto_slides.json +29 -0
- framework/_assets/features/renv.json +20 -0
- framework/_assets/features/targets.json +34 -0
- framework/_assets/features/uv.json +17 -0
- framework/_assets/schema/layer.v1.json +45 -7
- framework/_assets/schema/layers.v1.json +49 -7
- framework/_assets/schema/spec.v1.json +38 -7
- framework/_assets/sets/packages/tidyverse-analysis.json +42 -0
- framework/_assets/sets/skills/framework.json +25 -0
- framework/_assets/sets/skills/ggplot2.json +26 -0
- framework/_assets/workflows/jupyter.json +14 -0
- framework/_assets/workflows/quarto.json +14 -0
- framework/_assets/workflows/scripts.json +18 -0
- framework/_defaults_cache.py +47 -0
- framework/_paths.py +19 -9
- framework/adopt.py +365 -0
- framework/ai.py +13 -20
- framework/cloud.py +128 -13
- framework/create.py +395 -18
- framework/features.py +195 -0
- framework/hooks.py +69 -7
- framework/notebooks.py +9 -1
- framework/outputs.py +6 -1
- framework/quarto.py +77 -25
- framework/scaffold.py +50 -3
- framework/spec/check.py +31 -7
- framework/spec/merge.py +1 -0
- framework/spec/resolve.py +80 -6
- framework/templates/defaults.yml +0 -1
- {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/METADATA +1 -1
- {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/RECORD +40 -22
- {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/WHEEL +0 -0
- {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/licenses/LICENSE +0 -0
framework/adopt.py
ADDED
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
"""Adopt an existing project folder, or import its layout as a structure.
|
|
2
|
+
|
|
3
|
+
``adopt()`` scans the folder's subfolders, proposes a Framework directory key
|
|
4
|
+
for each, and after your review writes ``settings.yml`` and
|
|
5
|
+
``.framework/spec.json`` for the folders that are already there. It moves and
|
|
6
|
+
creates nothing else. ``structure_import()`` sends the same layout to
|
|
7
|
+
Framework Cloud as a private structure.
|
|
8
|
+
|
|
9
|
+
The scanner looks at folder names only, never at files or their contents.
|
|
10
|
+
The mapping rules are shared with R and ``fw`` (``inst/adopt/rules.json`` in
|
|
11
|
+
the R package): the first rule whose path matches a folder wins, and
|
|
12
|
+
folders no rule matches become ``extra_directories``.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import json
|
|
18
|
+
import re
|
|
19
|
+
import sys
|
|
20
|
+
from collections.abc import Callable, Mapping
|
|
21
|
+
from dataclasses import dataclass, field
|
|
22
|
+
from functools import cache
|
|
23
|
+
from importlib import resources
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
from typing import Any
|
|
26
|
+
|
|
27
|
+
from framework._log import inform, show_messages
|
|
28
|
+
from framework.errors import FrameworkError
|
|
29
|
+
|
|
30
|
+
_KEY = re.compile(r"^[a-z][a-z0-9_]*$")
|
|
31
|
+
EXTRA = "extra"
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass
|
|
35
|
+
class AdoptPlan:
|
|
36
|
+
"""The proposed layout: folder -> role, in byte order of path.
|
|
37
|
+
|
|
38
|
+
A role is a Framework directory key, ``"extra"`` for a folder of its own,
|
|
39
|
+
or None for a folder that is left out. ``private`` lists every scanned
|
|
40
|
+
folder whose path contains "private".
|
|
41
|
+
"""
|
|
42
|
+
|
|
43
|
+
roles: dict[str, str | None] = field(default_factory=dict)
|
|
44
|
+
private: list[str] = field(default_factory=list)
|
|
45
|
+
|
|
46
|
+
@property
|
|
47
|
+
def directories(self) -> dict[str, str]:
|
|
48
|
+
return {role: path for path, role in self.roles.items() if role not in (None, EXTRA)}
|
|
49
|
+
|
|
50
|
+
@property
|
|
51
|
+
def extra_directories(self) -> dict[str, dict[str, str]]:
|
|
52
|
+
extra: dict[str, dict[str, str]] = {}
|
|
53
|
+
taken = set(self.directories)
|
|
54
|
+
for path, role in self.roles.items():
|
|
55
|
+
if role == EXTRA:
|
|
56
|
+
key = _extra_key(path, taken)
|
|
57
|
+
taken.add(key)
|
|
58
|
+
extra[key] = {"label": path.rsplit("/", 1)[-1], "path": path}
|
|
59
|
+
return extra
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
@cache
|
|
63
|
+
def adopt_rules() -> dict[str, Any]:
|
|
64
|
+
"""The shared mapping rules, as synced from the R package."""
|
|
65
|
+
path = resources.files("framework").joinpath("_assets/adopt/rules.json")
|
|
66
|
+
rules: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
|
|
67
|
+
return rules
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _kept(path: str, rules: Mapping[str, Any]) -> bool:
|
|
71
|
+
skip = {name.lower() for name in rules.get("skip") or []}
|
|
72
|
+
parts = path.split("/")
|
|
73
|
+
return len(parts) <= int(rules.get("max_depth") or 3) and not any(
|
|
74
|
+
part.startswith(".") or part.lower() in skip for part in parts
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def scan_folders(root: Path, rules: Mapping[str, Any] | None = None) -> list[str]:
|
|
79
|
+
"""Subfolders of ``root``, as relative POSIX paths in byte order.
|
|
80
|
+
|
|
81
|
+
Hidden folders, the rules' ``skip`` folders (version control,
|
|
82
|
+
environments, caches), and everything under them are left out, and so are
|
|
83
|
+
folders more than ``max_depth`` levels deep. Only folder names are read.
|
|
84
|
+
"""
|
|
85
|
+
rules = rules or adopt_rules()
|
|
86
|
+
found: list[str] = []
|
|
87
|
+
|
|
88
|
+
def walk(folder: Path) -> None:
|
|
89
|
+
for entry in folder.iterdir():
|
|
90
|
+
if entry.is_dir() and not entry.is_symlink():
|
|
91
|
+
relative = entry.relative_to(root).as_posix()
|
|
92
|
+
if _kept(relative, rules):
|
|
93
|
+
found.append(relative)
|
|
94
|
+
walk(entry)
|
|
95
|
+
|
|
96
|
+
walk(root)
|
|
97
|
+
return sorted(found, key=lambda p: p.encode("utf-8"))
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def adopt_plan(
|
|
101
|
+
folders: list[str], language: str = "python", rules: Mapping[str, Any] | None = None
|
|
102
|
+
) -> AdoptPlan:
|
|
103
|
+
"""Propose a role for each folder with the shared rules.
|
|
104
|
+
|
|
105
|
+
The algorithm is the one in the R package's ``inst/conformance/README.md``
|
|
106
|
+
(adopt/): rules apply in order, each giving its key to the first folder
|
|
107
|
+
that equals one of its patterns, ignoring case. Folders inside an
|
|
108
|
+
assigned folder are covered by it. Each other folder with no assigned
|
|
109
|
+
folder inside it gets a role of its own (``"extra"``), unless its parent
|
|
110
|
+
does too.
|
|
111
|
+
"""
|
|
112
|
+
rules = rules or adopt_rules()
|
|
113
|
+
kept = sorted((f for f in folders if _kept(f, rules)), key=lambda p: p.encode("utf-8"))
|
|
114
|
+
by_lower: dict[str, str] = {}
|
|
115
|
+
for folder in kept:
|
|
116
|
+
by_lower.setdefault(folder.lower(), folder)
|
|
117
|
+
assigned: dict[str, str] = {}
|
|
118
|
+
for rule in rules.get("rules") or []:
|
|
119
|
+
if rule.get("languages") and language not in rule["languages"]:
|
|
120
|
+
continue
|
|
121
|
+
for pattern in rule.get("patterns") or []:
|
|
122
|
+
match = by_lower.get(pattern.lower())
|
|
123
|
+
if match is not None and match not in assigned:
|
|
124
|
+
assigned[match] = rule["key"]
|
|
125
|
+
break
|
|
126
|
+
|
|
127
|
+
def qualifies(folder: str) -> bool:
|
|
128
|
+
return (
|
|
129
|
+
folder not in assigned
|
|
130
|
+
and not any(_inside(folder, a) for a in assigned)
|
|
131
|
+
and not any(_inside(a, folder) for a in assigned)
|
|
132
|
+
)
|
|
133
|
+
|
|
134
|
+
plan = AdoptPlan(private=[f for f in kept if "private" in f.lower()])
|
|
135
|
+
for folder in kept:
|
|
136
|
+
if folder in assigned:
|
|
137
|
+
plan.roles[folder] = assigned[folder]
|
|
138
|
+
elif qualifies(folder):
|
|
139
|
+
parent = folder.rsplit("/", 1)[0] if "/" in folder else None
|
|
140
|
+
if parent is None or not (parent in kept and qualifies(parent)):
|
|
141
|
+
plan.roles[folder] = EXTRA
|
|
142
|
+
return plan
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def _inside(path: str, folder: str) -> bool:
|
|
146
|
+
return path.startswith(f"{folder}/")
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _extra_key(path: str, taken: set[str]) -> str:
|
|
150
|
+
key = re.sub(r"[^a-z0-9]+", "_", path.lower()).strip("_") or "folder"
|
|
151
|
+
if not key[0].isalpha():
|
|
152
|
+
key = f"dir_{key}"
|
|
153
|
+
candidate, n = key, 2
|
|
154
|
+
while candidate in taken:
|
|
155
|
+
candidate, n = f"{key}_{n}", n + 1
|
|
156
|
+
return candidate
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
# Review --------------------------------------------------------------------------------
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _table(plan: AdoptPlan) -> str:
|
|
163
|
+
width = max((len(p) for p in plan.roles), default=0)
|
|
164
|
+
lines = []
|
|
165
|
+
for number, (path, role) in enumerate(plan.roles.items(), start=1):
|
|
166
|
+
shown = "left out" if role is None else ("a folder of its own" if role == EXTRA else role)
|
|
167
|
+
lines.append(f" {number:>2}. {path:<{width}} -> {shown}")
|
|
168
|
+
return "\n".join(lines)
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _review(plan: AdoptPlan, ask: Callable[[str], str], cancelled: str) -> AdoptPlan:
|
|
172
|
+
"""Let the person accept the plan, change a folder's role, leave a folder out, or cancel."""
|
|
173
|
+
paths = list(plan.roles)
|
|
174
|
+
while True:
|
|
175
|
+
print("Proposed folders:\n" + _table(plan), file=sys.stderr)
|
|
176
|
+
answer = ask(
|
|
177
|
+
"Press Enter to accept, type a number to change that folder's role, "
|
|
178
|
+
"-number to leave it out, or q to cancel: "
|
|
179
|
+
).strip()
|
|
180
|
+
if not answer:
|
|
181
|
+
return plan
|
|
182
|
+
if answer.lower() == "q":
|
|
183
|
+
raise FrameworkError(cancelled)
|
|
184
|
+
out = answer.startswith("-")
|
|
185
|
+
number = answer.lstrip("-")
|
|
186
|
+
if not number.isdigit() or not 1 <= int(number) <= len(paths):
|
|
187
|
+
print(f"Type a number from 1 to {len(paths)}.", file=sys.stderr)
|
|
188
|
+
continue
|
|
189
|
+
path = paths[int(number) - 1]
|
|
190
|
+
if out:
|
|
191
|
+
plan.roles[path] = None
|
|
192
|
+
continue
|
|
193
|
+
role = ask(f"Role for {path} (a directory key such as inputs_raw, or {EXTRA}): ").strip()
|
|
194
|
+
if role != EXTRA and not _KEY.match(role):
|
|
195
|
+
print(f"'{role}' isn't a directory key.", file=sys.stderr)
|
|
196
|
+
elif role != EXTRA and role in plan.directories and plan.directories[role] != path:
|
|
197
|
+
print(f"{plan.directories[role]} already has the role {role}.", file=sys.stderr)
|
|
198
|
+
else:
|
|
199
|
+
plan.roles[path] = role
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def _yes_no(ask: Callable[[str], str], question: str) -> bool:
|
|
203
|
+
return ask(f"{question} [y/N] ").strip().lower() in ("y", "yes")
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
# Public API ----------------------------------------------------------------------------
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def adopt(path: str | Path = ".", yes: bool = False) -> Path:
|
|
210
|
+
"""Make an existing folder a Framework project, in place.
|
|
211
|
+
|
|
212
|
+
The folder's subfolders are scanned (names only, at most three levels) and
|
|
213
|
+
each gets a proposed role: a Framework directory key such as
|
|
214
|
+
``inputs_raw``, a folder of its own (``extra_directories``), or none.
|
|
215
|
+
You review the proposal, then ``settings.yml`` and ``.framework/spec.json``
|
|
216
|
+
are written for the folders that are there. Nothing is moved, and nothing
|
|
217
|
+
else is created.
|
|
218
|
+
|
|
219
|
+
A folder path that contains "private" gets a warning that suggests the
|
|
220
|
+
Privacy Sensitive layout. The sensitive setting is turned on only when you
|
|
221
|
+
say yes in the review.
|
|
222
|
+
|
|
223
|
+
Args:
|
|
224
|
+
path: The project folder.
|
|
225
|
+
yes: Accept the proposal without asking, as a script must. The sensitive
|
|
226
|
+
setting stays off.
|
|
227
|
+
|
|
228
|
+
Returns:
|
|
229
|
+
The project folder.
|
|
230
|
+
|
|
231
|
+
Raises:
|
|
232
|
+
FrameworkError: When the folder doesn't exist or is already a Framework project,
|
|
233
|
+
or when the review needs a terminal and ``yes`` is False.
|
|
234
|
+
"""
|
|
235
|
+
show_messages()
|
|
236
|
+
root = Path(path).expanduser().resolve()
|
|
237
|
+
if not root.is_dir():
|
|
238
|
+
raise FrameworkError(f"Not a folder: {root}")
|
|
239
|
+
existing = [
|
|
240
|
+
n for n in ("settings.yml", "config.yml", ".framework/spec.json") if (root / n).exists()
|
|
241
|
+
]
|
|
242
|
+
if existing:
|
|
243
|
+
raise FrameworkError(
|
|
244
|
+
f"{root} is already a Framework project (it has {', '.join(existing)})."
|
|
245
|
+
)
|
|
246
|
+
if not yes and not sys.stdin.isatty():
|
|
247
|
+
raise FrameworkError("adopt() needs a terminal to review the folders. Pass yes=True.")
|
|
248
|
+
|
|
249
|
+
plan = adopt_plan(scan_folders(root))
|
|
250
|
+
sensitive = False
|
|
251
|
+
if not yes:
|
|
252
|
+
plan = _review(plan, input, "Cancelled. Nothing was written.")
|
|
253
|
+
if plan.private:
|
|
254
|
+
# The same wording as R's adopt()
|
|
255
|
+
for folder in plan.private:
|
|
256
|
+
print(
|
|
257
|
+
f"'{folder}' looks private. Keep it out of git and away from AI assistants.",
|
|
258
|
+
file=sys.stderr,
|
|
259
|
+
)
|
|
260
|
+
print(
|
|
261
|
+
"The Privacy Sensitive layout keeps private and public data in separate "
|
|
262
|
+
"folders and adds safeguards for AI assistants.",
|
|
263
|
+
file=sys.stderr,
|
|
264
|
+
)
|
|
265
|
+
if not yes:
|
|
266
|
+
sensitive = _yes_no(input, "Turn on the sensitive-data setting for this project?")
|
|
267
|
+
|
|
268
|
+
spec = adopt_spec(root.name, plan, sensitive)
|
|
269
|
+
from framework.create import _record, _write_settings
|
|
270
|
+
|
|
271
|
+
_write_settings(root, spec)
|
|
272
|
+
_record(root, spec)
|
|
273
|
+
inform(f"Adopted {root} as a Framework project")
|
|
274
|
+
if not yes:
|
|
275
|
+
_offer_cloud(root, spec, plan)
|
|
276
|
+
return root
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def adopt_spec(name: str, plan: AdoptPlan, sensitive: bool = False) -> dict[str, Any]:
|
|
280
|
+
"""The resolved spec for an adopted folder: bare, flat settings, no tools."""
|
|
281
|
+
from framework.spec.resolve import spec_resolve
|
|
282
|
+
|
|
283
|
+
layer = {
|
|
284
|
+
"type": "bare",
|
|
285
|
+
"language": "python",
|
|
286
|
+
"core_files": False,
|
|
287
|
+
"settings_layout": "flat",
|
|
288
|
+
"tools": {"quarto": False, "uv": False},
|
|
289
|
+
"directories": plan.directories,
|
|
290
|
+
"extra_directories": plan.extra_directories,
|
|
291
|
+
"security": {"sensitive": sensitive},
|
|
292
|
+
}
|
|
293
|
+
spec = spec_resolve([layer], name).spec
|
|
294
|
+
spec["source"] = {"origin": "python"}
|
|
295
|
+
return spec
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
def _offer_cloud(root: Path, spec: Mapping[str, Any], plan: AdoptPlan) -> None:
|
|
299
|
+
from framework.cloud import CloudError, cloud_server, cloud_token, host, register_project
|
|
300
|
+
|
|
301
|
+
try:
|
|
302
|
+
server = cloud_server().url
|
|
303
|
+
except CloudError:
|
|
304
|
+
return
|
|
305
|
+
if cloud_token(server) is None:
|
|
306
|
+
return
|
|
307
|
+
if _yes_no(input, f"Register this project on {host(server)}?"):
|
|
308
|
+
register_project(root, str(spec["name"]), "bare", spec)
|
|
309
|
+
if _yes_no(input, f"Save this folder layout as a structure on {host(server)}?"):
|
|
310
|
+
_send_structure(str(spec["name"]), plan)
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def structure_import(
|
|
314
|
+
path: str | Path = ".", name: str | None = None, yes: bool = False
|
|
315
|
+
) -> dict[str, Any]:
|
|
316
|
+
"""Save an existing folder's layout as a private structure on Framework Cloud.
|
|
317
|
+
|
|
318
|
+
The folders are scanned and mapped as in ``adopt()``, and you review the
|
|
319
|
+
mapping the same way. Only the confirmed folder paths are sent: never file
|
|
320
|
+
names or contents.
|
|
321
|
+
|
|
322
|
+
Args:
|
|
323
|
+
path: The project folder.
|
|
324
|
+
name: The structure's name. Default: the folder's name.
|
|
325
|
+
yes: Send the proposed mapping without asking, as a script must.
|
|
326
|
+
|
|
327
|
+
Returns:
|
|
328
|
+
The new structure: ``key`` (``"<owner>/<key>"``), ``name``, and ``url``.
|
|
329
|
+
|
|
330
|
+
Raises:
|
|
331
|
+
CloudError: When you are not logged in, or the server rejects the layout or
|
|
332
|
+
doesn't support structures.
|
|
333
|
+
FrameworkError: When the review needs a terminal and ``yes`` is False, or when
|
|
334
|
+
you cancel it.
|
|
335
|
+
"""
|
|
336
|
+
show_messages()
|
|
337
|
+
root = Path(path).expanduser().resolve()
|
|
338
|
+
if not root.is_dir():
|
|
339
|
+
raise FrameworkError(f"Not a folder: {root}")
|
|
340
|
+
if not yes and not sys.stdin.isatty():
|
|
341
|
+
raise FrameworkError(
|
|
342
|
+
"structure_import() needs a terminal to review the folders. Pass yes=True."
|
|
343
|
+
)
|
|
344
|
+
plan = adopt_plan(scan_folders(root))
|
|
345
|
+
if not yes:
|
|
346
|
+
plan = _review(plan, input, "Cancelled. Nothing was sent.")
|
|
347
|
+
return _send_structure(name or root.name, plan)
|
|
348
|
+
|
|
349
|
+
|
|
350
|
+
def _send_structure(name: str, plan: AdoptPlan) -> dict[str, Any]:
|
|
351
|
+
from framework.cloud import CloudError, _MissingEndpointError, _require_token, api, cloud_server
|
|
352
|
+
|
|
353
|
+
server = cloud_server().url
|
|
354
|
+
token = _require_token(server)
|
|
355
|
+
body: dict[str, Any] = {"name": name, "directories": plan.directories}
|
|
356
|
+
if plan.extra_directories:
|
|
357
|
+
body["extra_directories"] = plan.extra_directories
|
|
358
|
+
try:
|
|
359
|
+
created = api("/api/v2/structures", token, server, method="POST", body=body)
|
|
360
|
+
except _MissingEndpointError as error:
|
|
361
|
+
raise CloudError("This Framework Cloud server doesn't support structures yet.") from error
|
|
362
|
+
if not isinstance(created, dict):
|
|
363
|
+
raise CloudError("The server returned an unexpected structure.")
|
|
364
|
+
inform(f"[ok] Saved the structure {created.get('key')}: {created.get('url')}")
|
|
365
|
+
return created
|
framework/ai.py
CHANGED
|
@@ -8,6 +8,7 @@ from importlib.resources.abc import Traversable
|
|
|
8
8
|
from pathlib import Path
|
|
9
9
|
from typing import Any
|
|
10
10
|
|
|
11
|
+
from framework._agents_md import agents_md
|
|
11
12
|
from framework.spec.check import ASSISTANTS
|
|
12
13
|
|
|
13
14
|
AGENTS_DEFAULT = ".agents/skills"
|
|
@@ -47,25 +48,15 @@ def restricted_paths(spec: dict[str, Any]) -> list[str]:
|
|
|
47
48
|
return sorted(restricted)
|
|
48
49
|
|
|
49
50
|
|
|
50
|
-
def
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
""
|
|
57
|
-
"
|
|
58
|
-
|
|
59
|
-
]
|
|
60
|
-
if spec.get("security", {}).get("sensitive"):
|
|
61
|
-
folders = ", ".join(f"`{path}`" for path in restricted_paths(spec))
|
|
62
|
-
lines += [
|
|
63
|
-
"",
|
|
64
|
-
f"This project holds restricted data. Do not read or print files in {folders}. "
|
|
65
|
-
"Work from the data dictionary and simulated data instead.",
|
|
66
|
-
]
|
|
67
|
-
lines += ["", "## Project Notes", ""]
|
|
68
|
-
return "\n".join(lines) + "\n"
|
|
51
|
+
def restricted_notice(spec: dict[str, Any]) -> str | None:
|
|
52
|
+
"""The line naming the folders agents must stay out of, for sensitive projects."""
|
|
53
|
+
if not spec.get("security", {}).get("sensitive"):
|
|
54
|
+
return None
|
|
55
|
+
folders = ", ".join(f"`{path}`" for path in restricted_paths(spec))
|
|
56
|
+
return (
|
|
57
|
+
f"This project holds restricted data. Do not read or print files in {folders}. "
|
|
58
|
+
"Work from the data dictionary and simulated data instead."
|
|
59
|
+
)
|
|
69
60
|
|
|
70
61
|
|
|
71
62
|
def pointer_stub(name: str) -> str:
|
|
@@ -96,7 +87,9 @@ def write_ai_files(root: Path, spec: dict[str, Any]) -> list[str]:
|
|
|
96
87
|
files = spec.get("files") or {}
|
|
97
88
|
|
|
98
89
|
if spec.get("ai", {}).get("agents_md") == "stub" and "AGENTS.md" not in files:
|
|
99
|
-
|
|
90
|
+
# The full guide, as R writes it; its skills table points at the first skills folder
|
|
91
|
+
skills_dir = folders[0] if folders else ".agents/skills"
|
|
92
|
+
_write(root, "AGENTS.md", agents_md(spec, skills_dir, restricted_notice(spec)))
|
|
100
93
|
written.append("AGENTS.md")
|
|
101
94
|
for stub in stubs:
|
|
102
95
|
_write(root, stub, "@AGENTS.md\n" if stub == "CLAUDE.md" else pointer_stub(spec["name"]))
|
framework/cloud.py
CHANGED
|
@@ -30,7 +30,7 @@ import subprocess
|
|
|
30
30
|
import sys
|
|
31
31
|
import tempfile
|
|
32
32
|
import zipfile
|
|
33
|
-
from collections.abc import Mapping
|
|
33
|
+
from collections.abc import Mapping, Sequence
|
|
34
34
|
from dataclasses import dataclass
|
|
35
35
|
from datetime import UTC, datetime
|
|
36
36
|
from pathlib import Path
|
|
@@ -301,12 +301,40 @@ def _client() -> httpx.Client:
|
|
|
301
301
|
)
|
|
302
302
|
|
|
303
303
|
|
|
304
|
+
class CloudOfflineError(CloudError):
|
|
305
|
+
"""The server couldn't be reached: a network error, a timeout, or a 5xx reply.
|
|
306
|
+
|
|
307
|
+
401 and 403 are authentication errors, never offline.
|
|
308
|
+
"""
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
class _MissingEndpointError(CloudError):
|
|
312
|
+
"""HTTP 404 or 405: an older server without this endpoint."""
|
|
313
|
+
|
|
314
|
+
|
|
304
315
|
def _error(response: httpx.Response, what: str) -> CloudError:
|
|
305
316
|
try:
|
|
306
|
-
|
|
317
|
+
body = response.json()
|
|
307
318
|
except Exception:
|
|
308
|
-
|
|
309
|
-
|
|
319
|
+
body = None
|
|
320
|
+
body = body if isinstance(body, dict) else {}
|
|
321
|
+
message = body.get("message") or f"{what} failed (HTTP {response.status_code})"
|
|
322
|
+
# A 422 lists each problem by field
|
|
323
|
+
errors = body.get("errors")
|
|
324
|
+
if isinstance(errors, dict):
|
|
325
|
+
details = [
|
|
326
|
+
f" - {field}: {text}"
|
|
327
|
+
for field, texts in errors.items()
|
|
328
|
+
for text in (texts if isinstance(texts, list) else [texts])
|
|
329
|
+
if str(text) not in str(message)
|
|
330
|
+
]
|
|
331
|
+
if details:
|
|
332
|
+
message = "\n".join([str(message), *details])
|
|
333
|
+
if response.status_code in (404, 405):
|
|
334
|
+
return _MissingEndpointError(str(message))
|
|
335
|
+
if response.status_code >= 500:
|
|
336
|
+
return CloudOfflineError(str(message))
|
|
337
|
+
return CloudError(str(message))
|
|
310
338
|
|
|
311
339
|
|
|
312
340
|
def api(
|
|
@@ -317,6 +345,16 @@ def api(
|
|
|
317
345
|
body: Mapping[str, Any] | None = None,
|
|
318
346
|
) -> Any:
|
|
319
347
|
"""Call the cloud API and return the decoded JSON."""
|
|
348
|
+
return _request(path, token, url, method, body).json()
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
def _request(
|
|
352
|
+
path: str,
|
|
353
|
+
token: str,
|
|
354
|
+
url: str,
|
|
355
|
+
method: str = "GET",
|
|
356
|
+
body: Mapping[str, Any] | None = None,
|
|
357
|
+
) -> httpx.Response:
|
|
320
358
|
try:
|
|
321
359
|
with _client() as client:
|
|
322
360
|
response = client.request(
|
|
@@ -326,10 +364,26 @@ def api(
|
|
|
326
364
|
headers={"Authorization": f"Bearer {token}"},
|
|
327
365
|
)
|
|
328
366
|
except httpx.HTTPError as error:
|
|
329
|
-
raise
|
|
367
|
+
raise CloudOfflineError(f"Could not reach {host(url)}: {error}") from error
|
|
330
368
|
if response.is_error:
|
|
331
369
|
raise _error(response, "Cloud request")
|
|
332
|
-
return response
|
|
370
|
+
return response
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
def resolve_choices(
|
|
374
|
+
body: Mapping[str, Any], token: str, url: str
|
|
375
|
+
) -> tuple[dict[str, Any], str | None]:
|
|
376
|
+
"""Resolve project choices on the cloud: the envelope and the defaults revision.
|
|
377
|
+
|
|
378
|
+
Each Framework-Notice header is shown as a message.
|
|
379
|
+
"""
|
|
380
|
+
response = _request("/api/v2/resolve", token, url, method="POST", body=body)
|
|
381
|
+
for notice in response.headers.get_list("Framework-Notice"):
|
|
382
|
+
inform(notice)
|
|
383
|
+
envelope = response.json()
|
|
384
|
+
if not isinstance(envelope, dict):
|
|
385
|
+
raise CloudError("The server returned an unexpected project definition.")
|
|
386
|
+
return envelope, response.headers.get("Framework-Defaults-Revision")
|
|
333
387
|
|
|
334
388
|
|
|
335
389
|
# Logging in ---------------------------------------------------------------------------
|
|
@@ -923,7 +977,12 @@ def cloud_publish(
|
|
|
923
977
|
|
|
924
978
|
|
|
925
979
|
def write_project_token(project_dir: Path, token: str, url: str) -> list[str]:
|
|
926
|
-
"""Add the project's key and server to its ``.env`` (never to the settings).
|
|
980
|
+
"""Add the project's key and server to its ``.env`` (never to the settings).
|
|
981
|
+
|
|
982
|
+
Git is made to ignore ``.env`` first, so the token can't be committed.
|
|
983
|
+
"""
|
|
984
|
+
from framework.create import keep_env_out_of_git
|
|
985
|
+
|
|
927
986
|
env = project_dir / ".env"
|
|
928
987
|
present = dotenv.read(env)
|
|
929
988
|
missing = {
|
|
@@ -931,6 +990,7 @@ def write_project_token(project_dir: Path, token: str, url: str) -> list[str]:
|
|
|
931
990
|
}
|
|
932
991
|
if not missing:
|
|
933
992
|
return []
|
|
993
|
+
keep_env_out_of_git(project_dir)
|
|
934
994
|
text = env.read_text(encoding="utf-8") if env.exists() else ""
|
|
935
995
|
if text and not text.endswith("\n"):
|
|
936
996
|
text += "\n"
|
|
@@ -943,20 +1003,75 @@ def write_project_token(project_dir: Path, token: str, url: str) -> list[str]:
|
|
|
943
1003
|
return list(missing)
|
|
944
1004
|
|
|
945
1005
|
|
|
946
|
-
def
|
|
947
|
-
|
|
1006
|
+
def registration_body(
|
|
1007
|
+
name: str,
|
|
1008
|
+
type: str,
|
|
1009
|
+
spec: Mapping[str, Any],
|
|
1010
|
+
package_sets: Sequence[str] = (),
|
|
1011
|
+
skill_sets: Sequence[str] = (),
|
|
1012
|
+
) -> dict[str, Any]:
|
|
1013
|
+
"""The choices a project built offline was made from, for ``/api/v2/projects``.
|
|
1014
|
+
|
|
1015
|
+
Each of Framework's five types is a structure of the same name.
|
|
1016
|
+
"""
|
|
1017
|
+
ai = spec.get("ai") or {}
|
|
1018
|
+
body: dict[str, Any] = {
|
|
1019
|
+
"name": name,
|
|
1020
|
+
"language": "python",
|
|
1021
|
+
"structure": f"framework/{type}",
|
|
1022
|
+
"tools": dict(spec.get("tools") or {}),
|
|
1023
|
+
"settings": {
|
|
1024
|
+
"sensitive": (spec.get("security") or {}).get("sensitive") is True,
|
|
1025
|
+
"git": (spec.get("git") or {}).get("use_git") is not False,
|
|
1026
|
+
"ai": {
|
|
1027
|
+
"enabled": ai.get("enabled") is True,
|
|
1028
|
+
"assistants": dict(ai.get("assistants") or {}),
|
|
1029
|
+
},
|
|
1030
|
+
},
|
|
1031
|
+
}
|
|
1032
|
+
if package_sets:
|
|
1033
|
+
body["package_sets"] = [s if "/" in s else f"framework/{s}" for s in package_sets]
|
|
1034
|
+
if skill_sets:
|
|
1035
|
+
body["skill_sets"] = [s if "/" in s else f"framework/{s}" for s in skill_sets]
|
|
1036
|
+
return body
|
|
1037
|
+
|
|
1038
|
+
|
|
1039
|
+
def register_project(
|
|
1040
|
+
project_dir: Path,
|
|
1041
|
+
name: str,
|
|
1042
|
+
type: str,
|
|
1043
|
+
spec: Mapping[str, Any] | None = None,
|
|
1044
|
+
package_sets: Sequence[str] = (),
|
|
1045
|
+
skill_sets: Sequence[str] = (),
|
|
1046
|
+
) -> Any:
|
|
1047
|
+
"""Register a new local project on the cloud when logged in. Never fails creation.
|
|
1048
|
+
|
|
1049
|
+
The cloud records the structure, tools, sets, and settings the project
|
|
1050
|
+
was built from. A server without ``/api/v2/projects`` gets the older
|
|
1051
|
+
registration.
|
|
1052
|
+
"""
|
|
948
1053
|
server = cloud_server().url
|
|
949
1054
|
token = cloud_token(server)
|
|
950
1055
|
if token is None:
|
|
951
1056
|
return None
|
|
952
|
-
body = {"name": name, "project_type": type, "language": "python"}
|
|
953
1057
|
try:
|
|
954
|
-
|
|
1058
|
+
if spec is not None:
|
|
1059
|
+
body = registration_body(name, type, spec, package_sets, skill_sets)
|
|
1060
|
+
try:
|
|
1061
|
+
result = api("/api/v2/projects", token, server, method="POST", body=body)
|
|
1062
|
+
slug, project_token = result.get("slug"), result.get("token")
|
|
1063
|
+
except _MissingEndpointError:
|
|
1064
|
+
spec = None
|
|
1065
|
+
if spec is None:
|
|
1066
|
+
body = {"name": name, "project_type": type, "language": "python"}
|
|
1067
|
+
result = api("/api/v1/projects", token, server, method="POST", body=body)
|
|
1068
|
+
slug, project_token = result["project"]["slug"], result["pull_token"]
|
|
955
1069
|
except CloudError as error:
|
|
956
1070
|
inform(f"Cloud project registration skipped: {error}")
|
|
957
1071
|
return None
|
|
958
|
-
inform(f"[ok] Registered on {host(server)}: {
|
|
959
|
-
|
|
1072
|
+
inform(f"[ok] Registered on {host(server)}: {slug}")
|
|
1073
|
+
if project_token:
|
|
1074
|
+
write_project_token(project_dir, str(project_token), server)
|
|
960
1075
|
return result
|
|
961
1076
|
|
|
962
1077
|
|