framework-py 0.1.0.dev1__py3-none-any.whl → 0.1.0.dev3__py3-none-any.whl

framework/__main__.py

@@ -37,7 +37,12 @@ def _parser() -> argparse.ArgumentParser:
     create.add_argument(
         "--interactive",
         action="store_true",
-        help="prompt for missing answers, initialize git, and register the project",
+        help=(
+            "with --name, ask for the type when --type is missing (the project is "
+            "registered and gets a git repository either way, unless your defaults turn "
+            "git off); with --from-layers, initialize git and register the project "
+            "instead of running headless"
+        ),
     )
 
     bootstrap = commands.add_parser("bootstrap", help="prepare a cloned project")

framework/_assets/hooks/pre-commit

@@ -12,23 +12,31 @@ set -u
 
 cd "$(git rev-parse --show-toplevel)" || exit 1
 
+# Each runner returns 127 when its runtime or the framework package is
+# missing, so the next runtime gets a turn and the message below can say why
+
 run_r() {
   command -v Rscript >/dev/null 2>&1 || return 127
+  # framework 1.x from CRAN has no shared hook entry point
+  probe='ok <- requireNamespace("framework", quietly = TRUE) && exists(".hook_run", envir = asNamespace("framework"))'
+  Rscript -e "$probe; quit(status = if (ok) 0 else 127)" >/dev/null 2>&1 || return 127
   Rscript -e 'quit(status = framework:::.hook_run("pre-commit"))'
 }
 
 run_python() {
   if [ -x .venv/bin/python ]; then
-    .venv/bin/python -m framework hook pre-commit
+    set -- .venv/bin/python
   elif [ -x .venv/Scripts/python.exe ]; then
-    .venv/Scripts/python.exe -m framework hook pre-commit
+    set -- .venv/Scripts/python.exe
   elif [ -f uv.lock ] && command -v uv >/dev/null 2>&1; then
-    uv run --frozen python -m framework hook pre-commit
+    set -- uv run --frozen python
   elif command -v python3 >/dev/null 2>&1; then
-    python3 -m framework hook pre-commit
+    set -- python3
   else
     return 127
   fi
+  "$@" -c 'import framework' >/dev/null 2>&1 || return 127
+  "$@" -m framework hook pre-commit
 }
 
 has_rproj() {
@@ -52,8 +60,8 @@ if [ "$status" -eq 127 ] && { [ -f pyproject.toml ] || [ -f uv.lock ] || [ -d .v
 fi
 
 if [ "$status" -eq 127 ]; then
-  echo "Framework hook: no R or Python runtime with framework installed was found." >&2
-  echo "Install one, or run 'git commit --no-verify' if you are sure this commit is safe." >&2
+  echo "Framework hook: found neither R with framework 2.0 or later nor Python with framework-py." >&2
+  echo "Install one of them, or run 'git commit --no-verify' if you are sure this commit is safe." >&2
   exit 1
 fi
 exit "$status"

framework/_assets/schema/docs-reference.v1.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://framework.pub/schema/docs-reference.v1.json",
+  "title": "Framework docs reference",
+  "description": "The generated function or command reference for one product's docs site (docs/site/reference.json). Text fields hold CommonMark with GFM tables.",
+  "type": "object",
+  "required": ["schema", "product", "version", "categories", "entries"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "docs-reference.v1" },
+    "product": { "enum": ["r", "py", "cli"] },
+    "version": { "type": "string", "minLength": 1, "description": "The release this reference was built from, such as 2.0.0 or 0.1.0.dev1." },
+    "categories": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/category" }
+    },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/entry" }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$",
+      "description": "URL-safe and unique within the product: /reference/{id}."
+    },
+    "markdown": { "type": "string" },
+    "category": {
+      "type": "object",
+      "required": ["id", "title", "position"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "description": "One line, shown under the title in the Reference dropdown." },
+        "position": { "type": "integer" },
+        "common": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Entry names listed first, under a Common heading."
+        }
+      }
+    },
+    "titled": {
+      "type": "object",
+      "required": ["title", "content"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "content": { "$ref": "#/$defs/markdown" }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "required": ["id", "name", "kind", "category", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string", "minLength": 1, "description": "As users write it: data_read, AuditResult, or \"project bootstrap\"." },
+        "kind": { "enum": ["function", "class", "command"] },
+        "category": { "type": "string", "description": "A category id." },
+        "title": { "type": "string", "description": "A short heading. Defaults to name." },
+        "summary": { "type": "string", "minLength": 1, "description": "One line, used in lists and search results." },
+        "usage": { "type": "string", "description": "The signature or command line, shown as code." },
+        "description": { "$ref": "#/$defs/markdown", "description": "A paragraph or two (roxygen @description, a docstring's opening paragraphs)." },
+        "details": { "$ref": "#/$defs/markdown", "description": "The long body (roxygen @details)." },
+        "parameters": {
+          "type": "array",
+          "description": "Arguments, flags, or a class's fields, in signature order.",
+          "items": {
+            "type": "object",
+            "required": ["name", "description"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "minLength": 1, "description": "x, *, --path, or -p, --path." },
+              "type": { "type": "string" },
+              "default": { "type": "string", "description": "As code, such as NULL, None, or \".\"." },
+              "required": { "type": "boolean" },
+              "env": { "type": "string", "description": "An environment variable that sets it (commands)." },
+              "description": { "$ref": "#/$defs/markdown" }
+            }
+          }
+        },
+        "returns": { "$ref": "#/$defs/markdown" },
+        "note": { "$ref": "#/$defs/markdown" },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["title", "content"],
+            "additionalProperties": false,
+            "properties": {
+              "title": { "type": "string", "minLength": 1 },
+              "content": { "$ref": "#/$defs/markdown" },
+              "subsections": { "type": "array", "items": { "$ref": "#/$defs/titled" } }
+            }
+          }
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["code"],
+            "additionalProperties": false,
+            "properties": {
+              "title": { "type": "string" },
+              "code": { "type": "string", "minLength": 1 },
+              "runnable": { "type": "boolean", "default": true, "description": "False for R's \\dontrun and for examples that need a server or credentials." }
+            }
+          }
+        },
+        "see_also": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1, "description": "An entry name in this product, or a link target such as py:ref:data_read." },
+              {
+                "type": "object",
+                "required": ["title", "url"],
+                "additionalProperties": false,
+                "properties": {
+                  "title": { "type": "string", "minLength": 1 },
+                  "url": { "type": "string", "pattern": "^https://" }
+                }
+              }
+            ]
+          }
+        },
+        "aliases": { "type": "array", "items": { "type": "string" } },
+        "lifecycle": { "enum": ["stable", "deprecated", "experimental"], "default": "stable" },
+        "replaced_by": { "type": "string", "description": "The entry name to use instead, for deprecated entries." },
+        "since": { "type": "string", "description": "The version that added it." }
+      }
+    }
+  }
+}

framework/_pages.py

@@ -0,0 +1,228 @@
+"""Publishing to GitHub Pages: ``publish(..., to="github")``.
+
+Framework Cloud's "Publish with GitHub Pages" commits a workflow that deploys
+the repository's ``published/`` folder from the default branch. This side
+copies a document into ``published/<slug>/``, commits only that folder, and
+pushes. Documents never pass through the cloud. R and fw behave the same way.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+
+from framework._log import inform
+from framework.errors import FrameworkError, FrameworkWarning
+
+PUBLIC_NOTICE = "GitHub Pages sites are public, even when the repository is private."
+_SLUG = re.compile(r"^[a-z0-9][a-z0-9._-]*$")
+_REMOTE = re.compile(r"github\.com[:/]+([^/]+)/([^/]+?)(?:\.git)?/?$")
+
+
+@dataclass(frozen=True)
+class _Remote:
+    name: str
+    owner: str
+    repo: str
+    has_upstream: bool
+
+
+def _git(top: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", str(top), *args], capture_output=True, text=True, check=False
+    )
+
+
+def github_remote(url: str) -> tuple[str, str] | None:
+    """The owner and repository of a GitHub remote URL (https, ssh, or scp-style)."""
+    match = _REMOTE.search(url.strip())
+    return (match[1], match[2]) if match else None
+
+
+def pages_base(owner: str, repo: str) -> str:
+    """The URL GitHub gives a repository's Pages site."""
+    host = f"{owner.lower()}.github.io"
+    if repo.lower() == host:
+        return f"https://{host}/"
+    return f"https://{host}/{repo}/"
+
+
+def pages_slug(source: Path) -> str:
+    """The file name lowercased, with each run of other characters as "-".
+
+    GitHub Pages URLs are case-sensitive. "Final Report (v2).html" becomes
+    "final-report-v2".
+    """
+    name = source.name if source.is_dir() else source.stem
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def _remote(top: Path) -> _Remote | None:
+    """The branch's upstream remote, then origin, then any GitHub remote."""
+    upstream = _git(top, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}")
+    upstream_name = upstream.stdout.strip().split("/")[0] if upstream.returncode == 0 else None
+    listed = _git(top, "remote")
+    names = listed.stdout.split() if listed.returncode == 0 else []
+    candidates = [n for n in (upstream_name, "origin", *names) if n is not None]
+    for name in dict.fromkeys(candidates):
+        if name not in names:
+            continue
+        url = _git(top, "remote", "get-url", name)
+        found = github_remote(url.stdout) if url.returncode == 0 else None
+        if found is not None:
+            return _Remote(name, found[0], found[1], name == upstream_name)
+    return None
+
+
+def _stage(source: Path, stage: Path, self_contained: bool) -> None:
+    """Copy ``source`` into ``stage`` as a folder whose front page is index.html."""
+    suffix = source.suffix.lower()
+    if source.is_dir():
+        if not (source / "index.html").is_file():
+            raise FrameworkError(
+                f"A folder published to GitHub Pages needs an index.html at its top: {source}"
+            )
+        shutil.copytree(source, stage, dirs_exist_ok=True)
+        return
+    if suffix in (".html", ".htm"):
+        shutil.copy2(source, stage / source.name)
+        assets = source.with_name(f"{source.stem}_files")
+        if assets.is_dir():
+            # The supporting folder keeps its name, so relative links still resolve
+            shutil.copytree(assets, stage / assets.name)
+    elif suffix in (".qmd", ".ipynb"):
+        quarto = shutil.which("quarto")
+        if quarto is None:
+            raise FrameworkError("Rendering requires the quarto command on your PATH.")
+        command = [quarto, "render", str(source.resolve()), "--output-dir", str(stage)]
+        command += ["--to", "html", *(["--embed-resources"] if self_contained else [])]
+        inform(f"Rendering {source.name}...")
+        result = subprocess.run(command, capture_output=True, text=True, check=False)
+        if result.returncode != 0:
+            raise FrameworkError(f"Quarto render failed:\n{result.stdout}{result.stderr}")
+    else:
+        raise FrameworkError(
+            "GitHub Pages publishing takes rendered HTML, a render folder, or a .qmd or "
+            f".ipynb to render. Got: {suffix or source.name}"
+        )
+    if not (stage / "index.html").is_file():
+        main = stage / f"{source.stem}.html"
+        if not main.is_file():
+            pages = sorted(stage.glob("*.htm*"))
+            if len(pages) != 1:
+                raise FrameworkError(f"No single HTML page found to publish from {source}")
+            main = pages[0]
+        main.rename(stage / "index.html")
+
+
+def _cloud_pages_url(root: Path) -> tuple[bool, str | None, str | None]:
+    """Whether the cloud answered, its Pages URL (None when Pages is off), and the server.
+
+    One call to ``/api/v1/me`` with the project token. Not known when there is
+    no project token or the call fails.
+    """
+    from framework.cloud import CloudError, api, cloud_server, project_token
+
+    token = project_token(root)
+    if token is None:
+        return False, None, None
+    try:
+        server = cloud_server(scope="project", project_dir=root).url
+        me = api("/api/v1/me", token, server)
+    except CloudError:
+        return False, None, None
+    if not isinstance(me, dict) or me.get("kind") != "project":
+        return False, None, None
+    pages = me.get("pages_url")
+    return True, pages if isinstance(pages, str) and pages else None, server
+
+
+def _confirm() -> None:
+    # Shown on every run, even when Framework's messages are off
+    print(PUBLIC_NOTICE, file=sys.stderr)
+    if sys.stdin.isatty():
+        answer = input("Publish it? [y/N] ").strip().lower()
+        if answer not in ("y", "yes"):
+            raise FrameworkError("Cancelled: nothing was published.")
+
+
+def github_publish(source: Path, slug: str | None = None, self_contained: bool = True) -> str:
+    """Copy ``source`` to ``published/<slug>/``, commit only that folder, and push."""
+    from framework.project import find_settings_file
+
+    if slug is None:
+        slug = pages_slug(source)
+    if not _SLUG.match(slug):
+        raise FrameworkError(
+            "slug must start with a lowercase letter or digit and use only lowercase letters, "
+            "digits, '.', '_', and '-' (GitHub Pages URLs are case-sensitive)."
+        )
+    settings_file = find_settings_file()
+    root = settings_file.parent if settings_file is not None else Path.cwd()
+    shown = _git(root, "rev-parse", "--show-toplevel")
+    if shown.returncode != 0:
+        raise FrameworkError(
+            "This project isn't a git repository. Create the project on GitHub first."
+        )
+    top = Path(shown.stdout.strip())
+    remote = _remote(top)
+    if remote is None:
+        raise FrameworkError(
+            "This project has no GitHub remote. Create the project on GitHub first, then "
+            "publish again."
+        )
+    _confirm()
+
+    # published/ sits at the top of the repository, where the workflow deploys from
+    rel = f"published/{slug}"
+    with tempfile.TemporaryDirectory(prefix="fw_pages_") as temp:
+        _stage(source, Path(temp), self_contained)
+        target = top / rel
+        if target.exists():
+            shutil.rmtree(target)
+        shutil.copytree(temp, target)
+
+    # Commit only this folder; anything else the user staged stays staged
+    _git(top, "add", "-A", "--", rel)
+    if _git(top, "diff", "--cached", "--quiet", "--", rel).returncode == 0:
+        inform(f"No change in {rel}; nothing committed or pushed.")
+    else:
+        commit = _git(top, "commit", "-m", f"Publish {slug}", "--", rel)
+        if commit.returncode != 0:
+            raise FrameworkError(f"git commit failed:\n{commit.stdout}{commit.stderr}")
+        branch = _git(top, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
+        default = _git(top, "symbolic-ref", "--short", f"refs/remotes/{remote.name}/HEAD")
+        if default.returncode == 0:
+            default_branch = default.stdout.strip().split("/", 1)[-1]
+            if branch != default_branch:
+                warnings.warn(
+                    f"You're on '{branch}'. GitHub Pages deploys only from the default branch "
+                    f"('{default_branch}'), so this won't appear until it's merged there.",
+                    FrameworkWarning,
+                    stacklevel=3,
+                )
+        push = (
+            _git(top, "push")
+            if remote.has_upstream
+            else _git(top, "push", "-u", remote.name, "HEAD")
+        )
+        if push.returncode != 0:
+            raise FrameworkError(f"Committed, but git push failed:\n{push.stdout}{push.stderr}")
+
+    known, pages_url, server = _cloud_pages_url(root)
+    if known and pages_url is None:
+        warnings.warn(
+            f"GitHub Pages is off for this project. Turn it on under Projects at {server}.",
+            FrameworkWarning,
+            stacklevel=3,
+        )
+    base = pages_url or pages_base(remote.owner, remote.repo)
+    url = f"{base.rstrip('/')}/{slug}/"
+    inform(f"Published to {url}")
+    return url

framework/_paths.py

@@ -2,11 +2,21 @@
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import Any
 
 from framework.project import project_root
 
+# A folder named like private, confidential, or sensitive (outputs_private and
+# private_raw count too), as the git security audit and R's audit match them.
+PRIVATE_SEGMENT = re.compile(r"(^|/)[^/]*(private|confidential|sensitive)[^/]*(/|$)", re.IGNORECASE)
+
+
+def has_private_segment(path: str | Path) -> bool:
+    """Whether a folder path, with ``/`` separators, has a private segment."""
+    return bool(PRIVATE_SEGMENT.search(Path(path).as_posix()))
+
 
 def relative_to_root(path: Path, root: Path) -> str:
     """``path`` relative to the project root when it is inside it, else absolute."""

framework/_private.py

@@ -0,0 +1,69 @@
+"""The check before an upload: a path with "private" in it needs confirmation.
+
+Uploads are always the user's explicit choice, so the check never refuses
+outright. Any source whose full path contains "private", in any letter case,
+is listed with a warning. An interactive session asks before uploading. A
+session with no terminal (scripts, CI, notebooks run by agents) raises an
+error unless ``include_private=True`` is passed.
+"""
+
+from __future__ import annotations
+
+import sys
+import warnings
+from collections.abc import Iterable
+from pathlib import Path
+
+from framework.errors import FrameworkError
+
+# macOS resolves /tmp, /var, and /etc to /private/..., which the user did not name
+_SYSTEM_PREFIX = "/private/"
+
+
+def is_private_path(path: Path) -> bool:
+    """Whether the full absolute path contains "private", ignoring the system prefix."""
+    full = path.expanduser().resolve().as_posix()
+    if full.startswith(_SYSTEM_PREFIX):
+        full = full[len(_SYSTEM_PREFIX) - 1 :]
+    return "private" in full.lower()
+
+
+def include_private_arg(include_private: bool, allow_private: bool | None) -> bool:
+    """``include_private``, honoring the deprecated ``allow_private`` name."""
+    if allow_private is None:
+        return include_private
+    warnings.warn(
+        "allow_private is deprecated; use include_private instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+    return include_private or allow_private
+
+
+def confirm_private_upload(paths: Iterable[Path], include_private: bool) -> None:
+    """Warn about private paths among ``paths`` and ask before uploading them.
+
+    Raises:
+        FrameworkError: When there is no terminal to ask on and ``include_private`` is
+            False, or when the user declines.
+    """
+    if include_private:
+        return
+    flagged = [p for p in paths if is_private_path(p)]
+    if not flagged:
+        return
+    shown = "".join(f"\n  {p}" for p in flagged[:5])
+    if len(flagged) > 5:
+        shown += f"\n  ... and {len(flagged) - 5} more"
+    print(
+        f"Warning: {len(flagged)} file(s) to upload have 'private' in their path:{shown}",
+        file=sys.stderr,
+    )
+    if not sys.stdin.isatty():
+        raise FrameworkError(
+            "Not uploading files with 'private' in their path without confirmation. "
+            "Review them, then pass include_private=True to upload them."
+        )
+    answer = input("Upload them anyway? [y/N] ").strip().lower()
+    if answer not in ("y", "yes"):
+        raise FrameworkError("Cancelled. Nothing was uploaded.")

framework/ai.py

@@ -179,13 +179,16 @@ def ai_skills_update(project_path: str | Path = ".") -> list[str]:
     come from ``.framework/spec.json``, or from the settings for projects
     without one.
 
+    Args:
+        project_path: The project's root directory. Default: the current directory.
+
     Returns:
         The skill folders written.
     """
     from framework._log import inform, show_messages
 
     show_messages()
-    root = Path(project_path)
+    root = Path(project_path).expanduser()
     spec = _installed_spec(root)
     folders, _ = assistant_targets(spec)
     updated = []

framework/bootstrap.py

@@ -29,7 +29,7 @@ from typing import Any
 from framework import db, dotenv
 from framework._log import inform, show_messages
 from framework._paths import in_root
-from framework.create import ensure_secrets_ignored
+from framework.create import FILE_LIKE, ensure_secrets_ignored
 from framework.errors import FrameworkError
 from framework.hooks import git_hooks_install
 from framework.project import _settings_in
@@ -111,7 +111,13 @@ def _folders(config: dict[str, Any]) -> list[str]:
     folders: list[str] = []
     directories = config.get("directories")
     if isinstance(directories, dict):
-        folders += [value for value in directories.values() if isinstance(value, str) and value]
+        # Entries that name a file, such as presentation.qmd, are skipped, as
+        # project creation skips them. R's bootstrap() creates them as folders.
+        folders += [
+            value
+            for value in directories.values()
+            if isinstance(value, str) and value and not FILE_LIKE.search(value)
+        ]
     extra = config.get("extra_directories")
     if isinstance(extra, list):
         folders += [

framework/cache.py

@@ -210,7 +210,19 @@ def _lookup(name: str, file: str | Path | None) -> Any:
 
 
 def cache_get(name: str, file: str | Path | None = None, default: Any = None) -> Any:
-    """A cached value, or ``default`` when it is missing, expired, or unreadable."""
+    """A cached value, or ``default`` when it is missing, expired, or unreadable.
+
+    An expired value is removed. A value saved by R (``.rds``) or one whose file hash no longer
+    matches its record counts as missing.
+
+    Args:
+        name: The cache name.
+        file: Read the value from this file instead of the cache folder.
+        default: The value to return when the cache has no usable value.
+
+    Returns:
+        The cached value, or ``default``.
+    """
     value = _lookup(name, file)
     return default if value is _MISSING else value
 
@@ -298,7 +310,13 @@ def cache_remember(
 
 
 def cache_forget(name: str, file: str | Path | None = None) -> None:
-    """Remove a cached value and its record, whichever language saved it."""
+    """Remove a cached value and its record, whichever language saved it.
+
+    Args:
+        name: The cache name.
+        file: Remove this file instead of the files in the cache folder and the one in the
+            cache record.
+    """
     _remove(name, file)