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.
Files changed (40) hide show
  1. framework/__init__.py +5 -0
  2. framework/__main__.py +64 -5
  3. framework/_agents_md.py +210 -0
  4. framework/_assets/adopt/rules.json +161 -0
  5. framework/_assets/features/jupyter.json +39 -0
  6. framework/_assets/features/quarto.json +18 -0
  7. framework/_assets/features/quarto_manuscript.json +35 -0
  8. framework/_assets/features/quarto_slides.json +29 -0
  9. framework/_assets/features/renv.json +20 -0
  10. framework/_assets/features/targets.json +34 -0
  11. framework/_assets/features/uv.json +17 -0
  12. framework/_assets/schema/layer.v1.json +45 -7
  13. framework/_assets/schema/layers.v1.json +49 -7
  14. framework/_assets/schema/spec.v1.json +38 -7
  15. framework/_assets/sets/packages/tidyverse-analysis.json +42 -0
  16. framework/_assets/sets/skills/framework.json +25 -0
  17. framework/_assets/sets/skills/ggplot2.json +26 -0
  18. framework/_assets/workflows/jupyter.json +14 -0
  19. framework/_assets/workflows/quarto.json +14 -0
  20. framework/_assets/workflows/scripts.json +18 -0
  21. framework/_defaults_cache.py +47 -0
  22. framework/_paths.py +19 -9
  23. framework/adopt.py +365 -0
  24. framework/ai.py +13 -20
  25. framework/cloud.py +128 -13
  26. framework/create.py +395 -18
  27. framework/features.py +195 -0
  28. framework/hooks.py +69 -7
  29. framework/notebooks.py +9 -1
  30. framework/outputs.py +6 -1
  31. framework/quarto.py +77 -25
  32. framework/scaffold.py +50 -3
  33. framework/spec/check.py +31 -7
  34. framework/spec/merge.py +1 -0
  35. framework/spec/resolve.py +80 -6
  36. framework/templates/defaults.yml +0 -1
  37. {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/METADATA +1 -1
  38. {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/RECORD +40 -22
  39. {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/WHEEL +0 -0
  40. {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 agents_md_stub(spec: dict[str, Any]) -> str:
51
- lines = [
52
- f"# {spec['name']}",
53
- "",
54
- "This is a Framework project (Python). Framework skills for this project are "
55
- "installed for your AI assistant.",
56
- "",
57
- "Start every notebook and script with `import framework as fw` and `fw.scaffold()`. "
58
- "It loads the project's settings, environment, and functions.",
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
- _write(root, "AGENTS.md", agents_md_stub(spec))
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
- message = response.json().get("message")
317
+ body = response.json()
307
318
  except Exception:
308
- message = None
309
- return CloudError(message or f"{what} failed (HTTP {response.status_code})")
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 CloudError(f"Could not reach {host(url)}: {error}") from error
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.json()
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 register_project(project_dir: Path, name: str, type: str) -> Any:
947
- """Register a new local project on the cloud when logged in. Never fails creation."""
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
- result = api("/api/v1/projects", token, server, method="POST", body=body)
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)}: {result['project']['slug']}")
959
- write_project_token(project_dir, result["pull_token"], server)
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