framework-py 0.1.0.dev2__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/_pages.py +228 -0
- framework/_paths.py +19 -9
- framework/_private.py +69 -0
- framework/adopt.py +365 -0
- framework/ai.py +13 -20
- framework/cloud.py +139 -14
- 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/storage.py +96 -50
- framework/templates/defaults.yml +0 -1
- framework/templates/skills/framework-outputs/SKILL.md +5 -5
- framework/templates/skills/framework-sensitive-data/SKILL.md +3 -2
- {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/METADATA +1 -1
- framework_py-0.1.0.dev4.dist-info/RECORD +84 -0
- framework_py-0.1.0.dev2.dist-info/RECORD +0 -64
- {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/WHEEL +0 -0
- {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/licenses/LICENSE +0 -0
framework/_paths.py
CHANGED
|
@@ -41,15 +41,25 @@ def directory(config: dict[str, Any], key: str, default: str, root: Path | None
|
|
|
41
41
|
return in_root(value if isinstance(value, str) and value else default, root)
|
|
42
42
|
|
|
43
43
|
|
|
44
|
-
def output_directory(
|
|
44
|
+
def output_directory(
|
|
45
|
+
config: dict[str, Any], kind: str, public: bool, root: Path | None = None
|
|
46
|
+
) -> Path:
|
|
45
47
|
"""Where outputs of one kind (tables, figures, ...) go.
|
|
46
48
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
+
A project with private and public output folders (sensitive data on, or
|
|
50
|
+
``outputs_private_*`` or ``outputs_public_*`` directories) splits by
|
|
51
|
+
``public``. Any other project has one folder per kind. This follows R's
|
|
52
|
+
``save_*()`` functions.
|
|
49
53
|
"""
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
54
|
+
directories = config.get("directories")
|
|
55
|
+
directories = directories if isinstance(directories, dict) else {}
|
|
56
|
+
security = config.get("security")
|
|
57
|
+
split = (
|
|
58
|
+
(isinstance(security, dict) and security.get("sensitive") is True)
|
|
59
|
+
or f"outputs_private_{kind}" in directories
|
|
60
|
+
or f"outputs_public_{kind}" in directories
|
|
61
|
+
)
|
|
62
|
+
if not split:
|
|
63
|
+
return directory(config, f"outputs_{kind}", f"outputs/{kind}", root)
|
|
64
|
+
side = "public" if public else "private"
|
|
65
|
+
return directory(config, f"outputs_{side}_{kind}", f"outputs/{side}/{kind}", root)
|
framework/_private.py
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
"""The check before an upload: a path with "private" in it needs confirmation.
|
|
2
|
+
|
|
3
|
+
Uploads are always the user's explicit choice, so the check never refuses
|
|
4
|
+
outright. Any source whose full path contains "private", in any letter case,
|
|
5
|
+
is listed with a warning. An interactive session asks before uploading. A
|
|
6
|
+
session with no terminal (scripts, CI, notebooks run by agents) raises an
|
|
7
|
+
error unless ``include_private=True`` is passed.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import sys
|
|
13
|
+
import warnings
|
|
14
|
+
from collections.abc import Iterable
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
|
|
17
|
+
from framework.errors import FrameworkError
|
|
18
|
+
|
|
19
|
+
# macOS resolves /tmp, /var, and /etc to /private/..., which the user did not name
|
|
20
|
+
_SYSTEM_PREFIX = "/private/"
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def is_private_path(path: Path) -> bool:
|
|
24
|
+
"""Whether the full absolute path contains "private", ignoring the system prefix."""
|
|
25
|
+
full = path.expanduser().resolve().as_posix()
|
|
26
|
+
if full.startswith(_SYSTEM_PREFIX):
|
|
27
|
+
full = full[len(_SYSTEM_PREFIX) - 1 :]
|
|
28
|
+
return "private" in full.lower()
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def include_private_arg(include_private: bool, allow_private: bool | None) -> bool:
|
|
32
|
+
"""``include_private``, honoring the deprecated ``allow_private`` name."""
|
|
33
|
+
if allow_private is None:
|
|
34
|
+
return include_private
|
|
35
|
+
warnings.warn(
|
|
36
|
+
"allow_private is deprecated; use include_private instead.",
|
|
37
|
+
DeprecationWarning,
|
|
38
|
+
stacklevel=3,
|
|
39
|
+
)
|
|
40
|
+
return include_private or allow_private
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def confirm_private_upload(paths: Iterable[Path], include_private: bool) -> None:
|
|
44
|
+
"""Warn about private paths among ``paths`` and ask before uploading them.
|
|
45
|
+
|
|
46
|
+
Raises:
|
|
47
|
+
FrameworkError: When there is no terminal to ask on and ``include_private`` is
|
|
48
|
+
False, or when the user declines.
|
|
49
|
+
"""
|
|
50
|
+
if include_private:
|
|
51
|
+
return
|
|
52
|
+
flagged = [p for p in paths if is_private_path(p)]
|
|
53
|
+
if not flagged:
|
|
54
|
+
return
|
|
55
|
+
shown = "".join(f"\n {p}" for p in flagged[:5])
|
|
56
|
+
if len(flagged) > 5:
|
|
57
|
+
shown += f"\n ... and {len(flagged) - 5} more"
|
|
58
|
+
print(
|
|
59
|
+
f"Warning: {len(flagged)} file(s) to upload have 'private' in their path:{shown}",
|
|
60
|
+
file=sys.stderr,
|
|
61
|
+
)
|
|
62
|
+
if not sys.stdin.isatty():
|
|
63
|
+
raise FrameworkError(
|
|
64
|
+
"Not uploading files with 'private' in their path without confirmation. "
|
|
65
|
+
"Review them, then pass include_private=True to upload them."
|
|
66
|
+
)
|
|
67
|
+
answer = input("Upload them anyway? [y/N] ").strip().lower()
|
|
68
|
+
if answer not in ("y", "yes"):
|
|
69
|
+
raise FrameworkError("Cancelled. Nothing was uploaded.")
|
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"]))
|