framework-py 0.1.0.dev30__py3-none-any.whl → 0.1.0.dev32__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 CHANGED
@@ -129,7 +129,7 @@ from framework.scaffold import project_info, scaffold, status
129
129
  from framework.scratch import scratch_capture, scratch_clean
130
130
  from framework.security import AuditResult, git_security_audit
131
131
  from framework.settings import settings, settings_read, settings_write
132
- from framework.skill_pull import pull_skills, push_skills, skills_copy
132
+ from framework.skill_pull import pull_skills, push_skills, skills_copy, skills_move
133
133
  from framework.skill_sync import skills_sync
134
134
  from framework.snippets import load_ipython_extension as load_ipython_extension
135
135
  from framework.snippets import snippet
@@ -276,6 +276,7 @@ __all__ = [
276
276
  "settings_write",
277
277
  "show_table",
278
278
  "skills_copy",
279
+ "skills_move",
279
280
  "skills_sync",
280
281
  "snippet",
281
282
  "spec_check",
framework/_agents_md.py CHANGED
@@ -7,10 +7,15 @@ user's to edit.
7
7
 
8
8
  from __future__ import annotations
9
9
 
10
+ import base64
11
+ import binascii
10
12
  import re
13
+ from collections.abc import Mapping
11
14
  from pathlib import Path
12
15
  from typing import Any
13
16
 
17
+ from framework.spec.resolve import is_app_type
18
+
14
19
  REGENERATE = "<!-- @framework:regenerate -->"
15
20
  PACKAGES_HEADING = "Installed Packages"
16
21
 
@@ -61,12 +66,33 @@ def _header(name: str) -> str:
61
66
  def skill_description(folder: Path) -> str:
62
67
  """A skill's own description, from its SKILL.md front matter, on one line with pipes
63
68
  escaped, for skills Framework has no line for. R: ``.skill_description()``."""
64
- from framework import _yaml
65
-
66
69
  try:
67
70
  text = (folder / "SKILL.md").read_text(encoding="utf-8")
68
71
  except OSError:
69
72
  return ""
73
+ return _front_description(text)
74
+
75
+
76
+ def _entry_skill_md(entry: object) -> str | None:
77
+ """A spec skill entry's SKILL.md text: its ``content``, else the file in its Cloud
78
+ ``bundle`` (base64). None for a package skill, which ships its own."""
79
+ if not isinstance(entry, Mapping):
80
+ return None
81
+ content = entry.get("content")
82
+ if isinstance(content, str) and content:
83
+ return content
84
+ for item in entry.get("bundle") or []:
85
+ if isinstance(item, Mapping) and item.get("path") == "SKILL.md":
86
+ try:
87
+ return base64.b64decode(str(item.get("content") or "")).decode("utf-8")
88
+ except (binascii.Error, ValueError):
89
+ return None
90
+ return None
91
+
92
+
93
+ def _front_description(text: str) -> str:
94
+ from framework import _yaml
95
+
70
96
  found = re.match(r"---\r?\n(.*?)\r?\n---", text, re.DOTALL)
71
97
  try:
72
98
  meta = _yaml.load(found.group(1)) if found else None
@@ -78,12 +104,25 @@ def skill_description(folder: Path) -> str:
78
104
  return " ".join(value.split()).replace("|", "\\|")
79
105
 
80
106
 
81
- def _skills(skills: list[str], skills_dir: str, root: Path | None = None) -> str:
107
+ def _skills(
108
+ skills: list[str],
109
+ skills_dir: str,
110
+ root: Path | None = None,
111
+ entries: Mapping[str, Any] | None = None,
112
+ ) -> str:
113
+ """The Skills section. A skill Framework has no line for is described by its SKILL.md
114
+ front matter: from the spec's entry when there is one, else the copy in the project."""
115
+
82
116
  def covers(skill: str) -> str:
83
117
  known = SKILL_DESCRIPTIONS.get(skill)
84
- if known is not None or root is None:
85
- return known or ""
86
- return skill_description(root / skills_dir / skill)
118
+ if known is not None:
119
+ return known
120
+ text = _entry_skill_md((entries or {}).get(skill))
121
+ if text is not None:
122
+ described = _front_description(text)
123
+ if described:
124
+ return described
125
+ return skill_description(root / skills_dir / skill) if root is not None else ""
87
126
 
88
127
  rows = [
89
128
  f"| `{skill}` | {covers(skill)} | `{skills_dir}/{skill}/SKILL.md` |" for skill in skills
@@ -103,7 +142,61 @@ def _skills(skills: list[str], skills_dir: str, root: Path | None = None) -> str
103
142
  )
104
143
 
105
144
 
145
+ def _folder(spec: Mapping[str, Any], key: str) -> str:
146
+ """A folder's name from the spec's directories, else its usual name."""
147
+ value = (spec.get("directories") or {}).get(key)
148
+ return str(value).strip("/") if isinstance(value, str) and value else key
149
+
150
+
151
+ def _app_environment(spec: dict[str, Any]) -> str | None:
152
+ """The Framework Environment section of an app, which doesn't call ``fw.scaffold()``.
153
+ None for other project types."""
154
+ www, data, tests = (_folder(spec, key) for key in ("www", "data", "tests"))
155
+ publish = (
156
+ "- Ask before publishing anything public. GitHub Pages is public even from a "
157
+ "private repository."
158
+ )
159
+ package = '- Add packages with `fw.package_add("name")`. It records them in pyproject.toml.'
160
+ if spec.get("type") == "shiny_python":
161
+ kind = "a Shiny for Python app"
162
+ lines = [
163
+ f"- The interface and server are in `app.py`. Static files go in `{www}/`, data "
164
+ f"files in `{data}/`, and tests in `{tests}/`.",
165
+ "- Run it with `uv run shiny run --reload app.py`.",
166
+ package,
167
+ publish,
168
+ ]
169
+ elif spec.get("type") == "fastapi":
170
+ app = _folder(spec, "app")
171
+ module = app.replace("/", ".")
172
+ kind = "a FastAPI app"
173
+ lines = [
174
+ f"- The endpoints are in `{app}/main.py`. Tests in `{tests}/` use FastAPI's test "
175
+ f"client. Data files go in `{data}/`.",
176
+ f"- Run it with `uv run uvicorn {module}.main:app --reload`. The API docs are at "
177
+ "`/docs`.",
178
+ "- Run the tests with `uv run pytest`.",
179
+ package,
180
+ publish,
181
+ ]
182
+ else:
183
+ return None
184
+ return "\n".join(
185
+ [
186
+ f"## Framework Environment {REGENERATE}",
187
+ "",
188
+ f"This is {kind}. Framework manages its packages, skills, and settings. The app "
189
+ "doesn't call `fw.scaffold()`.",
190
+ "",
191
+ *lines,
192
+ ]
193
+ )
194
+
195
+
106
196
  def _environment(spec: dict[str, Any]) -> str:
197
+ app = _app_environment(spec)
198
+ if app is not None:
199
+ return app
107
200
  scaffold = spec.get("scaffold") or {}
108
201
  functions = (spec.get("directories") or {}).get("functions") or "functions"
109
202
  steps = [
@@ -247,7 +340,7 @@ def _data(spec: dict[str, Any]) -> str:
247
340
  )
248
341
 
249
342
 
250
- def _type_section(spec: dict[str, Any]) -> str:
343
+ def _type_section(spec: dict[str, Any]) -> str | None:
251
344
  # Sensitive data is a setting, whatever structure the project uses
252
345
  from framework._private import spec_sensitive
253
346
 
@@ -278,6 +371,9 @@ def _type_section(spec: dict[str, Any]) -> str:
278
371
  'fw.make_revealjs("backup-slides")\n'
279
372
  "```"
280
373
  )
374
+ # The guidelines point at the framework-workflow skill, so they need it
375
+ if is_app_type(spec.get("type")) or "framework-workflow" not in (spec.get("skills") or {}):
376
+ return None
281
377
  return (
282
378
  "## Workflow Guidelines\n\n"
283
379
  "Follow the standard Framework workflow (see the `framework-workflow` skill):\n"
@@ -286,22 +382,31 @@ def _type_section(spec: dict[str, Any]) -> str:
286
382
  )
287
383
 
288
384
 
289
- def agents_md(spec: dict[str, Any], skills_dir: str, restricted_notice: str | None) -> str:
385
+ def agents_md(
386
+ spec: dict[str, Any],
387
+ skills_dir: str,
388
+ restricted_notice: str | None,
389
+ root: Path | None = None,
390
+ ) -> str:
290
391
  """The full AGENTS.md for a new project.
291
392
 
292
393
  ``restricted_notice`` names the folders agents must stay out of. It goes
293
- right after the header in sensitive projects.
394
+ right after the header in sensitive projects. ``root`` is the project, for the
395
+ descriptions of skills already written there. An app (Shiny for Python or FastAPI)
396
+ has no Data Management or Workflow Guidelines section.
294
397
  """
295
- sections = [_header(spec["name"])]
398
+ skills = spec.get("skills") or {}
399
+ app = is_app_type(spec.get("type"))
400
+ sections: list[str | None] = [_header(spec["name"])]
296
401
  if restricted_notice:
297
402
  sections.append(restricted_notice)
298
403
  sections += [
299
- _skills(list(spec.get("skills") or {}), skills_dir),
404
+ _skills(list(skills), skills_dir, root, skills),
300
405
  _environment(spec),
301
406
  _packages(spec),
302
- _data(spec),
407
+ None if app else _data(spec),
303
408
  _type_section(spec),
304
409
  "## Project Notes\n\n*Add your project-specific notes, conventions, and documentation "
305
410
  "here.*",
306
411
  ]
307
- return "\n\n".join(section.rstrip("\n") for section in sections) + "\n"
412
+ return "\n\n".join(section.rstrip("\n") for section in sections if section) + "\n"
@@ -743,6 +743,13 @@
743
743
  },
744
744
  "server": {
745
745
  "type": "string"
746
+ },
747
+ "known_hashes": {
748
+ "type": "array",
749
+ "items": {
750
+ "type": "string",
751
+ "pattern": "^[a-f0-9]{64}$"
752
+ }
746
753
  }
747
754
  },
748
755
  "additionalProperties": false,
@@ -366,6 +366,13 @@
366
366
  },
367
367
  "server": {
368
368
  "type": "string"
369
+ },
370
+ "known_hashes": {
371
+ "type": "array",
372
+ "items": {
373
+ "type": "string",
374
+ "pattern": "^[a-f0-9]{64}$"
375
+ }
369
376
  }
370
377
  },
371
378
  "additionalProperties": false,
@@ -724,6 +724,13 @@
724
724
  },
725
725
  "server": {
726
726
  "type": "string"
727
+ },
728
+ "known_hashes": {
729
+ "type": "array",
730
+ "items": {
731
+ "type": "string",
732
+ "pattern": "^[a-f0-9]{64}$"
733
+ }
727
734
  }
728
735
  },
729
736
  "additionalProperties": false,
framework/_pages.py CHANGED
@@ -139,10 +139,11 @@ def _cloud_pages_url(root: Path) -> tuple[bool, str | None, str | None]:
139
139
  One call to ``/api/v1/me`` with the project token. Not known when there is
140
140
  no project token or the call fails.
141
141
  """
142
- from framework.cloud import CloudError, api, cloud_server, project_token
142
+ from framework.cloud import PROJECT_NOT_LINKED, CloudError, api, cloud_server, project_token
143
143
 
144
144
  token = project_token(root)
145
145
  if token is None:
146
+ inform(f"{PROJECT_NOT_LINKED} Using the GitHub Pages address from the git remote.")
146
147
  return False, None, None
147
148
  try:
148
149
  server = cloud_server(scope="project", project_dir=root).url