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.
Files changed (46) 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/_pages.py +228 -0
  23. framework/_paths.py +19 -9
  24. framework/_private.py +69 -0
  25. framework/adopt.py +365 -0
  26. framework/ai.py +13 -20
  27. framework/cloud.py +139 -14
  28. framework/create.py +395 -18
  29. framework/features.py +195 -0
  30. framework/hooks.py +69 -7
  31. framework/notebooks.py +9 -1
  32. framework/outputs.py +6 -1
  33. framework/quarto.py +77 -25
  34. framework/scaffold.py +50 -3
  35. framework/spec/check.py +31 -7
  36. framework/spec/merge.py +1 -0
  37. framework/spec/resolve.py +80 -6
  38. framework/storage.py +96 -50
  39. framework/templates/defaults.yml +0 -1
  40. framework/templates/skills/framework-outputs/SKILL.md +5 -5
  41. framework/templates/skills/framework-sensitive-data/SKILL.md +3 -2
  42. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/METADATA +1 -1
  43. framework_py-0.1.0.dev4.dist-info/RECORD +84 -0
  44. framework_py-0.1.0.dev2.dist-info/RECORD +0 -64
  45. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/WHEEL +0 -0
  46. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/licenses/LICENSE +0 -0
@@ -0,0 +1,17 @@
1
+ {
2
+ "id": "uv",
3
+ "name": "uv",
4
+ "description": "Manages the project's Python environment with uv: pyproject.toml and uv.lock.",
5
+ "category": "reproducibility",
6
+ "language": [
7
+ "python"
8
+ ],
9
+ "requires": [],
10
+ "conflicts": [],
11
+ "layer": {
12
+ "tools": {
13
+ "uv": true
14
+ }
15
+ },
16
+ "language_layers": {}
17
+ }
@@ -13,14 +13,38 @@
13
13
  "minLength": 1
14
14
  },
15
15
  "type": {
16
+ "type": "string",
17
+ "pattern": "^[a-z][a-z0-9_]*$",
18
+ "description": "A label for the blueprint the project came from. Framework's own are project, project_sensitive, course, presentation, and bare. Behavior follows settings, tools, and core_files, not this label."
19
+ },
20
+ "core_files": {
21
+ "type": "boolean",
22
+ "description": "Whether the structure writes Framework's core files (starter scripts and .env). false for bare structures. Missing means true."
23
+ },
24
+ "settings_layout": {
16
25
  "type": "string",
17
26
  "enum": [
18
- "project",
19
- "project_sensitive",
20
- "course",
21
- "presentation",
22
- "bare"
23
- ]
27
+ "split",
28
+ "flat"
29
+ ],
30
+ "description": "split: connections, packages, and data in settings/*.yml. flat: everything in settings.yml. Missing means split for Framework's project and project_sensitive structures and flat for the rest."
31
+ },
32
+ "tools": {
33
+ "type": "object",
34
+ "additionalProperties": {
35
+ "anyOf": [
36
+ {
37
+ "type": "boolean"
38
+ },
39
+ {
40
+ "type": "null"
41
+ }
42
+ ]
43
+ },
44
+ "description": "Tool id -> on. Missing means off. Framework's tools are defined in inst/features/<id>.json. In a layer, later layers override earlier ones key by key.",
45
+ "propertyNames": {
46
+ "pattern": "^[a-z][a-z0-9_]*$"
47
+ }
24
48
  },
25
49
  "language": {
26
50
  "type": "string",
@@ -238,9 +262,19 @@
238
262
  "enum": [
239
263
  "quarto",
240
264
  "rmarkdown",
241
- "jupyter"
265
+ "jupyter",
266
+ "script"
242
267
  ]
243
268
  },
269
+ "workflow": {
270
+ "type": "string",
271
+ "enum": [
272
+ "quarto",
273
+ "jupyter",
274
+ "scripts"
275
+ ],
276
+ "description": "How notebooks are written. quarto allows notebook_format quarto (or rmarkdown in R), jupyter allows jupyter, and scripts allows script."
277
+ },
244
278
  "ide": {
245
279
  "type": "string",
246
280
  "enum": [
@@ -451,6 +485,10 @@
451
485
  },
452
486
  "additionalProperties": false
453
487
  },
488
+ "adopted": {
489
+ "type": "boolean",
490
+ "description": "True when adopt() made an existing folder a project, mapping its folders in place"
491
+ },
454
492
  "framework_version": {
455
493
  "type": "string",
456
494
  "description": "Version of the R or Python package that created the project"
@@ -164,6 +164,10 @@
164
164
  "id"
165
165
  ]
166
166
  },
167
+ "adopted": {
168
+ "type": "boolean",
169
+ "description": "True when adopt() made an existing folder a project, mapping its folders in place"
170
+ },
167
171
  "framework_version": {
168
172
  "type": "string",
169
173
  "description": "Version of the R or Python package that created the project"
@@ -335,14 +339,38 @@
335
339
  "minLength": 1
336
340
  },
337
341
  "type": {
342
+ "type": "string",
343
+ "pattern": "^[a-z][a-z0-9_]*$",
344
+ "description": "A label for the blueprint the project came from. Framework's own are project, project_sensitive, course, presentation, and bare. Behavior follows settings, tools, and core_files, not this label."
345
+ },
346
+ "core_files": {
347
+ "type": "boolean",
348
+ "description": "Whether the structure writes Framework's core files (starter scripts and .env). false for bare structures. Missing means true."
349
+ },
350
+ "settings_layout": {
338
351
  "type": "string",
339
352
  "enum": [
340
- "project",
341
- "project_sensitive",
342
- "course",
343
- "presentation",
344
- "bare"
345
- ]
353
+ "split",
354
+ "flat"
355
+ ],
356
+ "description": "split: connections, packages, and data in settings/*.yml. flat: everything in settings.yml. Missing means split for Framework's project and project_sensitive structures and flat for the rest."
357
+ },
358
+ "tools": {
359
+ "type": "object",
360
+ "additionalProperties": {
361
+ "anyOf": [
362
+ {
363
+ "type": "boolean"
364
+ },
365
+ {
366
+ "type": "null"
367
+ }
368
+ ]
369
+ },
370
+ "description": "Tool id -> on. Missing means off. Framework's tools are defined in inst/features/<id>.json. In a layer, later layers override earlier ones key by key.",
371
+ "propertyNames": {
372
+ "pattern": "^[a-z][a-z0-9_]*$"
373
+ }
346
374
  },
347
375
  "language": {
348
376
  "type": "string",
@@ -560,9 +588,19 @@
560
588
  "enum": [
561
589
  "quarto",
562
590
  "rmarkdown",
563
- "jupyter"
591
+ "jupyter",
592
+ "script"
564
593
  ]
565
594
  },
595
+ "workflow": {
596
+ "type": "string",
597
+ "enum": [
598
+ "quarto",
599
+ "jupyter",
600
+ "scripts"
601
+ ],
602
+ "description": "How notebooks are written. quarto allows notebook_format quarto (or rmarkdown in R), jupyter allows jupyter, and scripts allows script."
603
+ },
566
604
  "ide": {
567
605
  "type": "string",
568
606
  "enum": [
@@ -773,6 +811,10 @@
773
811
  },
774
812
  "additionalProperties": false
775
813
  },
814
+ "adopted": {
815
+ "type": "boolean",
816
+ "description": "True when adopt() made an existing folder a project, mapping its folders in place"
817
+ },
776
818
  "framework_version": {
777
819
  "type": "string",
778
820
  "description": "Version of the R or Python package that created the project"
@@ -13,14 +13,31 @@
13
13
  "minLength": 1
14
14
  },
15
15
  "type": {
16
+ "type": "string",
17
+ "pattern": "^[a-z][a-z0-9_]*$",
18
+ "description": "A label for the blueprint the project came from. Framework's own are project, project_sensitive, course, presentation, and bare. Behavior follows settings, tools, and core_files, not this label."
19
+ },
20
+ "core_files": {
21
+ "type": "boolean",
22
+ "description": "Whether the structure writes Framework's core files (starter scripts and .env). false for bare structures. Missing means true."
23
+ },
24
+ "settings_layout": {
16
25
  "type": "string",
17
26
  "enum": [
18
- "project",
19
- "project_sensitive",
20
- "course",
21
- "presentation",
22
- "bare"
23
- ]
27
+ "split",
28
+ "flat"
29
+ ],
30
+ "description": "split: connections, packages, and data in settings/*.yml. flat: everything in settings.yml. Missing means split for Framework's project and project_sensitive structures and flat for the rest."
31
+ },
32
+ "tools": {
33
+ "type": "object",
34
+ "additionalProperties": {
35
+ "type": "boolean"
36
+ },
37
+ "description": "Tool id -> on. Missing means off. Framework's tools are defined in inst/features/<id>.json. In a layer, later layers override earlier ones key by key.",
38
+ "propertyNames": {
39
+ "pattern": "^[a-z][a-z0-9_]*$"
40
+ }
24
41
  },
25
42
  "language": {
26
43
  "type": "string",
@@ -217,9 +234,19 @@
217
234
  "enum": [
218
235
  "quarto",
219
236
  "rmarkdown",
220
- "jupyter"
237
+ "jupyter",
238
+ "script"
221
239
  ]
222
240
  },
241
+ "workflow": {
242
+ "type": "string",
243
+ "enum": [
244
+ "quarto",
245
+ "jupyter",
246
+ "scripts"
247
+ ],
248
+ "description": "How notebooks are written. quarto allows notebook_format quarto (or rmarkdown in R), jupyter allows jupyter, and scripts allows script."
249
+ },
223
250
  "ide": {
224
251
  "type": "string",
225
252
  "enum": [
@@ -409,6 +436,10 @@
409
436
  "id"
410
437
  ]
411
438
  },
439
+ "adopted": {
440
+ "type": "boolean",
441
+ "description": "True when adopt() made an existing folder a project, mapping its folders in place"
442
+ },
412
443
  "framework_version": {
413
444
  "type": "string",
414
445
  "description": "Version of the R or Python package that created the project"
@@ -0,0 +1,42 @@
1
+ {
2
+ "id": "tidyverse-analysis",
3
+ "name": "Tidyverse analysis",
4
+ "description": "The tidyverse packages most analyses use, loaded by scaffold().",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "dplyr": {
12
+ "source": "cran",
13
+ "auto_attach": true
14
+ },
15
+ "tidyr": {
16
+ "source": "cran",
17
+ "auto_attach": true
18
+ },
19
+ "ggplot2": {
20
+ "source": "cran",
21
+ "auto_attach": true
22
+ },
23
+ "purrr": {
24
+ "source": "cran",
25
+ "auto_attach": true
26
+ },
27
+ "stringr": {
28
+ "source": "cran",
29
+ "auto_attach": true
30
+ },
31
+ "forcats": {
32
+ "source": "cran",
33
+ "auto_attach": true
34
+ },
35
+ "lubridate": {
36
+ "source": "cran",
37
+ "auto_attach": true
38
+ }
39
+ }
40
+ }
41
+ }
42
+ }
@@ -0,0 +1,25 @@
1
+ {
2
+ "id": "framework",
3
+ "name": "Framework basics",
4
+ "description": "How to work in a Framework project: notebooks and scripts, reading and saving data, packages, and outputs.",
5
+ "language": [
6
+ "r",
7
+ "python"
8
+ ],
9
+ "layer": {
10
+ "skills": {
11
+ "framework-workflow": {
12
+ "package": true
13
+ },
14
+ "framework-data": {
15
+ "package": true
16
+ },
17
+ "framework-packages": {
18
+ "package": true
19
+ },
20
+ "framework-outputs": {
21
+ "package": true
22
+ }
23
+ }
24
+ }
25
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "id": "ggplot2",
3
+ "name": "Figures with ggplot2",
4
+ "description": "Exploratory and publication figures with ggplot2.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "skills": {
10
+ "ggplot2-exploring": {
11
+ "package": true
12
+ },
13
+ "ggplot2-publishing": {
14
+ "package": true
15
+ }
16
+ },
17
+ "packages": {
18
+ "default_packages": {
19
+ "ggplot2": {
20
+ "source": "cran",
21
+ "auto_attach": true
22
+ }
23
+ }
24
+ }
25
+ }
26
+ }
@@ -0,0 +1,14 @@
1
+ {
2
+ "id": "jupyter",
3
+ "name": "Jupyter",
4
+ "description": "Write notebooks in Jupyter (.ipynb) with the kernel for the project's language. Quarto stays available to render and publish them.",
5
+ "language": ["r", "python"],
6
+ "requires": ["jupyter", "quarto"],
7
+ "layer": {
8
+ "scaffold": {
9
+ "workflow": "jupyter",
10
+ "notebook_format": "jupyter"
11
+ }
12
+ },
13
+ "language_layers": {}
14
+ }
@@ -0,0 +1,14 @@
1
+ {
2
+ "id": "quarto",
3
+ "name": "Quarto",
4
+ "description": "Write notebooks as Quarto documents (.qmd), or R Markdown in R projects. Quarto renders them to HTML, PDF, and Word.",
5
+ "language": ["r", "python"],
6
+ "requires": ["quarto"],
7
+ "layer": {
8
+ "scaffold": {
9
+ "workflow": "quarto",
10
+ "notebook_format": "quarto"
11
+ }
12
+ },
13
+ "language_layers": {}
14
+ }
@@ -0,0 +1,18 @@
1
+ {
2
+ "id": "scripts",
3
+ "name": "Scripts only",
4
+ "description": "No notebooks. Analysis lives in scripts, and the blueprint supplies any starter scripts.",
5
+ "language": ["r", "python", "stata"],
6
+ "requires": [],
7
+ "layer": {
8
+ "tools": {
9
+ "quarto": false,
10
+ "jupyter": false
11
+ },
12
+ "scaffold": {
13
+ "workflow": "scripts",
14
+ "notebook_format": "script"
15
+ }
16
+ },
17
+ "language_layers": {}
18
+ }
@@ -0,0 +1,47 @@
1
+ """The cached Framework Cloud defaults, for creating projects offline.
2
+
3
+ After each successful resolve of your defaults, ``new()`` saves the envelope
4
+ here, one file per server and language, in the format R and ``fw`` share:
5
+
6
+ <config folder>/cache/defaults/<host[_port]>/<language>.json
7
+ {"fetched_at": "<RFC 3339>", "defaults_revision": "...", "envelope": {...}}
8
+
9
+ Each ":" in host[:port] becomes "_", because Windows doesn't allow ":" in
10
+ folder names.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import json
16
+ from datetime import UTC, datetime
17
+ from pathlib import Path
18
+ from typing import Any
19
+
20
+ from framework.config_home import config_dir
21
+
22
+
23
+ def cache_path(url: str, language: str) -> Path:
24
+ from framework.cloud import host
25
+
26
+ return config_dir() / "cache" / "defaults" / host(url).replace(":", "_") / f"{language}.json"
27
+
28
+
29
+ def write_cached_defaults(
30
+ url: str, language: str, envelope: dict[str, Any], revision: str | None
31
+ ) -> None:
32
+ path = cache_path(url, language)
33
+ path.parent.mkdir(parents=True, exist_ok=True)
34
+ fetched_at = datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
35
+ record = {"fetched_at": fetched_at, "defaults_revision": revision, "envelope": envelope}
36
+ path.write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8")
37
+
38
+
39
+ def read_cached_defaults(url: str, language: str) -> dict[str, Any] | None:
40
+ """The cached record, or None when there is none or it can't be read."""
41
+ try:
42
+ record = json.loads(cache_path(url, language).read_text(encoding="utf-8"))
43
+ except (OSError, ValueError):
44
+ return None
45
+ if not isinstance(record, dict) or not isinstance(record.get("envelope"), dict):
46
+ return None
47
+ return record
framework/_pages.py ADDED
@@ -0,0 +1,228 @@
1
+ """Publishing to GitHub Pages: ``publish(..., to="github")``.
2
+
3
+ Framework Cloud's "Publish with GitHub Pages" commits a workflow that deploys
4
+ the repository's ``published/`` folder from the default branch. This side
5
+ copies a document into ``published/<slug>/``, commits only that folder, and
6
+ pushes. Documents never pass through the cloud. R and fw behave the same way.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+ import shutil
13
+ import subprocess
14
+ import sys
15
+ import tempfile
16
+ import warnings
17
+ from dataclasses import dataclass
18
+ from pathlib import Path
19
+
20
+ from framework._log import inform
21
+ from framework.errors import FrameworkError, FrameworkWarning
22
+
23
+ PUBLIC_NOTICE = "GitHub Pages sites are public, even when the repository is private."
24
+ _SLUG = re.compile(r"^[a-z0-9][a-z0-9._-]*$")
25
+ _REMOTE = re.compile(r"github\.com[:/]+([^/]+)/([^/]+?)(?:\.git)?/?$")
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class _Remote:
30
+ name: str
31
+ owner: str
32
+ repo: str
33
+ has_upstream: bool
34
+
35
+
36
+ def _git(top: Path, *args: str) -> subprocess.CompletedProcess[str]:
37
+ return subprocess.run(
38
+ ["git", "-C", str(top), *args], capture_output=True, text=True, check=False
39
+ )
40
+
41
+
42
+ def github_remote(url: str) -> tuple[str, str] | None:
43
+ """The owner and repository of a GitHub remote URL (https, ssh, or scp-style)."""
44
+ match = _REMOTE.search(url.strip())
45
+ return (match[1], match[2]) if match else None
46
+
47
+
48
+ def pages_base(owner: str, repo: str) -> str:
49
+ """The URL GitHub gives a repository's Pages site."""
50
+ host = f"{owner.lower()}.github.io"
51
+ if repo.lower() == host:
52
+ return f"https://{host}/"
53
+ return f"https://{host}/{repo}/"
54
+
55
+
56
+ def pages_slug(source: Path) -> str:
57
+ """The file name lowercased, with each run of other characters as "-".
58
+
59
+ GitHub Pages URLs are case-sensitive. "Final Report (v2).html" becomes
60
+ "final-report-v2".
61
+ """
62
+ name = source.name if source.is_dir() else source.stem
63
+ return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
64
+
65
+
66
+ def _remote(top: Path) -> _Remote | None:
67
+ """The branch's upstream remote, then origin, then any GitHub remote."""
68
+ upstream = _git(top, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}")
69
+ upstream_name = upstream.stdout.strip().split("/")[0] if upstream.returncode == 0 else None
70
+ listed = _git(top, "remote")
71
+ names = listed.stdout.split() if listed.returncode == 0 else []
72
+ candidates = [n for n in (upstream_name, "origin", *names) if n is not None]
73
+ for name in dict.fromkeys(candidates):
74
+ if name not in names:
75
+ continue
76
+ url = _git(top, "remote", "get-url", name)
77
+ found = github_remote(url.stdout) if url.returncode == 0 else None
78
+ if found is not None:
79
+ return _Remote(name, found[0], found[1], name == upstream_name)
80
+ return None
81
+
82
+
83
+ def _stage(source: Path, stage: Path, self_contained: bool) -> None:
84
+ """Copy ``source`` into ``stage`` as a folder whose front page is index.html."""
85
+ suffix = source.suffix.lower()
86
+ if source.is_dir():
87
+ if not (source / "index.html").is_file():
88
+ raise FrameworkError(
89
+ f"A folder published to GitHub Pages needs an index.html at its top: {source}"
90
+ )
91
+ shutil.copytree(source, stage, dirs_exist_ok=True)
92
+ return
93
+ if suffix in (".html", ".htm"):
94
+ shutil.copy2(source, stage / source.name)
95
+ assets = source.with_name(f"{source.stem}_files")
96
+ if assets.is_dir():
97
+ # The supporting folder keeps its name, so relative links still resolve
98
+ shutil.copytree(assets, stage / assets.name)
99
+ elif suffix in (".qmd", ".ipynb"):
100
+ quarto = shutil.which("quarto")
101
+ if quarto is None:
102
+ raise FrameworkError("Rendering requires the quarto command on your PATH.")
103
+ command = [quarto, "render", str(source.resolve()), "--output-dir", str(stage)]
104
+ command += ["--to", "html", *(["--embed-resources"] if self_contained else [])]
105
+ inform(f"Rendering {source.name}...")
106
+ result = subprocess.run(command, capture_output=True, text=True, check=False)
107
+ if result.returncode != 0:
108
+ raise FrameworkError(f"Quarto render failed:\n{result.stdout}{result.stderr}")
109
+ else:
110
+ raise FrameworkError(
111
+ "GitHub Pages publishing takes rendered HTML, a render folder, or a .qmd or "
112
+ f".ipynb to render. Got: {suffix or source.name}"
113
+ )
114
+ if not (stage / "index.html").is_file():
115
+ main = stage / f"{source.stem}.html"
116
+ if not main.is_file():
117
+ pages = sorted(stage.glob("*.htm*"))
118
+ if len(pages) != 1:
119
+ raise FrameworkError(f"No single HTML page found to publish from {source}")
120
+ main = pages[0]
121
+ main.rename(stage / "index.html")
122
+
123
+
124
+ def _cloud_pages_url(root: Path) -> tuple[bool, str | None, str | None]:
125
+ """Whether the cloud answered, its Pages URL (None when Pages is off), and the server.
126
+
127
+ One call to ``/api/v1/me`` with the project token. Not known when there is
128
+ no project token or the call fails.
129
+ """
130
+ from framework.cloud import CloudError, api, cloud_server, project_token
131
+
132
+ token = project_token(root)
133
+ if token is None:
134
+ return False, None, None
135
+ try:
136
+ server = cloud_server(scope="project", project_dir=root).url
137
+ me = api("/api/v1/me", token, server)
138
+ except CloudError:
139
+ return False, None, None
140
+ if not isinstance(me, dict) or me.get("kind") != "project":
141
+ return False, None, None
142
+ pages = me.get("pages_url")
143
+ return True, pages if isinstance(pages, str) and pages else None, server
144
+
145
+
146
+ def _confirm() -> None:
147
+ # Shown on every run, even when Framework's messages are off
148
+ print(PUBLIC_NOTICE, file=sys.stderr)
149
+ if sys.stdin.isatty():
150
+ answer = input("Publish it? [y/N] ").strip().lower()
151
+ if answer not in ("y", "yes"):
152
+ raise FrameworkError("Cancelled: nothing was published.")
153
+
154
+
155
+ def github_publish(source: Path, slug: str | None = None, self_contained: bool = True) -> str:
156
+ """Copy ``source`` to ``published/<slug>/``, commit only that folder, and push."""
157
+ from framework.project import find_settings_file
158
+
159
+ if slug is None:
160
+ slug = pages_slug(source)
161
+ if not _SLUG.match(slug):
162
+ raise FrameworkError(
163
+ "slug must start with a lowercase letter or digit and use only lowercase letters, "
164
+ "digits, '.', '_', and '-' (GitHub Pages URLs are case-sensitive)."
165
+ )
166
+ settings_file = find_settings_file()
167
+ root = settings_file.parent if settings_file is not None else Path.cwd()
168
+ shown = _git(root, "rev-parse", "--show-toplevel")
169
+ if shown.returncode != 0:
170
+ raise FrameworkError(
171
+ "This project isn't a git repository. Create the project on GitHub first."
172
+ )
173
+ top = Path(shown.stdout.strip())
174
+ remote = _remote(top)
175
+ if remote is None:
176
+ raise FrameworkError(
177
+ "This project has no GitHub remote. Create the project on GitHub first, then "
178
+ "publish again."
179
+ )
180
+ _confirm()
181
+
182
+ # published/ sits at the top of the repository, where the workflow deploys from
183
+ rel = f"published/{slug}"
184
+ with tempfile.TemporaryDirectory(prefix="fw_pages_") as temp:
185
+ _stage(source, Path(temp), self_contained)
186
+ target = top / rel
187
+ if target.exists():
188
+ shutil.rmtree(target)
189
+ shutil.copytree(temp, target)
190
+
191
+ # Commit only this folder; anything else the user staged stays staged
192
+ _git(top, "add", "-A", "--", rel)
193
+ if _git(top, "diff", "--cached", "--quiet", "--", rel).returncode == 0:
194
+ inform(f"No change in {rel}; nothing committed or pushed.")
195
+ else:
196
+ commit = _git(top, "commit", "-m", f"Publish {slug}", "--", rel)
197
+ if commit.returncode != 0:
198
+ raise FrameworkError(f"git commit failed:\n{commit.stdout}{commit.stderr}")
199
+ branch = _git(top, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
200
+ default = _git(top, "symbolic-ref", "--short", f"refs/remotes/{remote.name}/HEAD")
201
+ if default.returncode == 0:
202
+ default_branch = default.stdout.strip().split("/", 1)[-1]
203
+ if branch != default_branch:
204
+ warnings.warn(
205
+ f"You're on '{branch}'. GitHub Pages deploys only from the default branch "
206
+ f"('{default_branch}'), so this won't appear until it's merged there.",
207
+ FrameworkWarning,
208
+ stacklevel=3,
209
+ )
210
+ push = (
211
+ _git(top, "push")
212
+ if remote.has_upstream
213
+ else _git(top, "push", "-u", remote.name, "HEAD")
214
+ )
215
+ if push.returncode != 0:
216
+ raise FrameworkError(f"Committed, but git push failed:\n{push.stdout}{push.stderr}")
217
+
218
+ known, pages_url, server = _cloud_pages_url(root)
219
+ if known and pages_url is None:
220
+ warnings.warn(
221
+ f"GitHub Pages is off for this project. Turn it on under Projects at {server}.",
222
+ FrameworkWarning,
223
+ stacklevel=3,
224
+ )
225
+ base = pages_url or pages_base(remote.owner, remote.repo)
226
+ url = f"{base.rstrip('/')}/{slug}/"
227
+ inform(f"Published to {url}")
228
+ return url