framework-py 0.1.0.dev0__py3-none-any.whl

framework/_secretservice.py

@@ -0,0 +1,69 @@
+"""Linux Secret Service entries in the format R's keyring package uses.
+
+R's keyring package looks up items by the libsecret schema
+``com.rstudio.keyring.password`` (the ``xdg:schema`` attribute) and the
+``service`` and ``username`` attributes. Python's keyring package writes
+items without ``xdg:schema`` and with an extra ``application`` attribute, so
+R and ``fw`` cannot see them, and its replace adds a second item beside
+theirs. Framework writes and deletes these items directly, the same way
+``fw`` does, so each token has exactly one item that every client reads.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+SCHEMA = "com.rstudio.keyring.password"
+
+
+def _attributes(service: str, username: str) -> dict[str, str]:
+    return {"service": service, "username": username}
+
+
+@contextmanager
+def _collection() -> Iterator[Any]:
+    import secretstorage
+
+    connection = secretstorage.dbus_init()
+    try:
+        collection = secretstorage.get_default_collection(connection)
+        if collection.is_locked():
+            collection.unlock()
+        yield collection
+    finally:
+        connection.close()
+
+
+def get(service: str, username: str) -> str | None:
+    """The secret, preferring the item in R's schema when there are several."""
+    with _collection() as collection:
+        items = list(collection.search_items(_attributes(service, username)))
+        if not items:
+            return None
+        items.sort(key=lambda item: item.get_attributes().get("xdg:schema") != SCHEMA)
+        secret = items[0].get_secret()
+    return bytes(secret).decode("utf-8") or None
+
+
+def set(service: str, username: str, secret: str) -> None:
+    """Replace every matching item with one item in R's schema."""
+    attributes = _attributes(service, username)
+    with _collection() as collection:
+        for item in collection.search_items(attributes):
+            item.delete()
+        collection.create_item(
+            f"{service}:{username}",
+            {**attributes, "xdg:schema": SCHEMA},
+            secret.encode("utf-8"),
+        )
+
+
+def delete(service: str, username: str) -> bool:
+    """Delete every matching item. Returns whether there was one."""
+    with _collection() as collection:
+        items = list(collection.search_items(_attributes(service, username)))
+        for item in items:
+            item.delete()
+    return bool(items)

framework/_time.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+
+def now() -> str:
+    """The current local time as an ISO 8601 string, such as ``2026-10-30T14:05:09-0400``.
+
+    The format matches R's ``framework::now()``.
+    """
+    return datetime.now().astimezone().strftime("%Y-%m-%dT%H:%M:%S%z")

framework/_wincred.py

@@ -0,0 +1,105 @@
+"""Windows Credential Manager entries in the format R's keyring package uses.
+
+R's keyring package stores a generic credential with the target name
+``:<service>:<username>`` and the secret as UTF-8 bytes. Python's keyring
+package uses a different target and UTF-16 text, so Framework reads and
+writes these entries directly, the same way ``fw`` does.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+from typing import Any
+
+CRED_TYPE_GENERIC = 1
+CRED_PERSIST_LOCAL_MACHINE = 2
+ERROR_NOT_FOUND = 1168
+
+
+def target(service: str, username: str) -> str:
+    return f":{service}:{username}"
+
+
+def decode(blob: bytes) -> str:
+    """A secret blob as text: UTF-16LE when every second byte is zero, else UTF-8.
+
+    Tokens are ASCII, so a blob written by Python's keyring package (UTF-16)
+    has a zero in every odd position.
+    """
+    if len(blob) >= 2 and len(blob) % 2 == 0 and all(b == 0 for b in blob[1::2]):
+        return blob.decode("utf-16-le")
+    return blob.decode("utf-8")
+
+
+def _api() -> tuple[Any, Any]:  # pragma: no cover (Windows only)
+    from ctypes import wintypes
+
+    class FILETIME(ctypes.Structure):
+        _fields_ = [("dwLowDateTime", wintypes.DWORD), ("dwHighDateTime", wintypes.DWORD)]
+
+    class CREDENTIAL(ctypes.Structure):
+        _fields_ = [
+            ("Flags", wintypes.DWORD),
+            ("Type", wintypes.DWORD),
+            ("TargetName", wintypes.LPWSTR),
+            ("Comment", wintypes.LPWSTR),
+            ("LastWritten", FILETIME),
+            ("CredentialBlobSize", wintypes.DWORD),
+            ("CredentialBlob", ctypes.POINTER(ctypes.c_ubyte)),
+            ("Persist", wintypes.DWORD),
+            ("AttributeCount", wintypes.DWORD),
+            ("Attributes", ctypes.c_void_p),
+            ("TargetAlias", wintypes.LPWSTR),
+            ("UserName", wintypes.LPWSTR),
+        ]
+
+    advapi = ctypes.WinDLL("advapi32", use_last_error=True)  # type: ignore[attr-defined]
+    advapi.CredReadW.argtypes = [
+        wintypes.LPCWSTR,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        ctypes.POINTER(ctypes.POINTER(CREDENTIAL)),
+    ]
+    advapi.CredReadW.restype = wintypes.BOOL
+    advapi.CredWriteW.argtypes = [ctypes.POINTER(CREDENTIAL), wintypes.DWORD]
+    advapi.CredWriteW.restype = wintypes.BOOL
+    advapi.CredDeleteW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD]
+    advapi.CredDeleteW.restype = wintypes.BOOL
+    advapi.CredFree.argtypes = [ctypes.c_void_p]
+    return advapi, CREDENTIAL
+
+
+def get(service: str, username: str) -> str | None:  # pragma: no cover (Windows only)
+    if sys.platform != "win32":
+        return None
+    advapi, credential = _api()
+    pointer = ctypes.POINTER(credential)()
+    if not advapi.CredReadW(target(service, username), CRED_TYPE_GENERIC, 0, ctypes.byref(pointer)):
+        return None
+    try:
+        entry = pointer.contents
+        blob = ctypes.string_at(entry.CredentialBlob, entry.CredentialBlobSize)
+        return decode(blob)
+    finally:
+        advapi.CredFree(pointer)
+
+
+def set(service: str, username: str, secret: str) -> None:  # pragma: no cover (Windows only)
+    advapi, credential = _api()
+    blob = secret.encode("utf-8")
+    buffer = (ctypes.c_ubyte * len(blob)).from_buffer_copy(blob)
+    entry = credential()
+    entry.Type = CRED_TYPE_GENERIC
+    entry.TargetName = target(service, username)
+    entry.CredentialBlobSize = len(blob)
+    entry.CredentialBlob = ctypes.cast(buffer, ctypes.POINTER(ctypes.c_ubyte))
+    entry.Persist = CRED_PERSIST_LOCAL_MACHINE
+    entry.UserName = username
+    if not advapi.CredWriteW(ctypes.byref(entry), 0):
+        raise OSError(ctypes.get_last_error(), "CredWriteW failed")  # type: ignore[attr-defined]
+
+
+def delete(service: str, username: str) -> bool:  # pragma: no cover (Windows only)
+    advapi, _ = _api()
+    return bool(advapi.CredDeleteW(target(service, username), CRED_TYPE_GENERIC, 0))

framework/_yaml.py

@@ -0,0 +1,90 @@
+"""YAML reading and writing with R-compatible behavior.
+
+R's yaml package and PyYAML both follow YAML 1.1, so ``yes``/``no``,
+``on``/``off``, octal numbers, and ``~`` read the same way. Two additions
+match R:
+
+- ``y``, ``Y``, ``n``, and ``N`` are booleans, as they are in R.
+- The ``!expr`` tag is kept as the string ``"!expr <code>"`` for later
+  evaluation.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_BOOL_TAG = "tag:yaml.org,2002:bool"
+_SHORT_BOOLS = {"y": True, "n": False}
+
+
+class _Loader(yaml.SafeLoader):
+    pass
+
+
+def _expr(loader: yaml.SafeLoader, node: yaml.Node) -> str:
+    value = loader.construct_scalar(node)  # type: ignore[arg-type]
+    return f"!expr {value}"
+
+
+def _bool(loader: yaml.SafeLoader, node: yaml.Node) -> bool:
+    value = str(loader.construct_scalar(node)).lower()  # type: ignore[arg-type]
+    if value in _SHORT_BOOLS:
+        return _SHORT_BOOLS[value]
+    return bool(loader.bool_values[value])
+
+
+_Loader.add_constructor("!expr", _expr)
+_Loader.add_constructor(_BOOL_TAG, _bool)
+_Loader.add_implicit_resolver(_BOOL_TAG, re.compile(r"^(?:y|Y|n|N)$"), list("yYnN"))
+
+
+def load(text: str) -> Any:
+    return yaml.load(text, Loader=_Loader)
+
+
+def read(path: Path) -> Any:
+    return load(path.read_text(encoding="utf-8"))
+
+
+class _Dumper(yaml.SafeDumper):
+    pass
+
+
+def _none(dumper: yaml.SafeDumper, _: None) -> yaml.Node:
+    # R writes NULL as "~".
+    return dumper.represent_scalar("tag:yaml.org,2002:null", "~")
+
+
+# Plain scalars R's yaml package reads as something other than a string:
+# "." and ".na" become NA, and y/n are booleans. R quotes them when writing.
+_R_SPECIAL = re.compile(r"^(?:\.|\.na|y|Y|n|N)$")
+
+
+def _str(dumper: yaml.SafeDumper, value: str) -> yaml.Node:
+    if _R_SPECIAL.match(value):
+        return dumper.represent_scalar("tag:yaml.org,2002:str", value, style="'")
+    return dumper.represent_str(value)
+
+
+_Dumper.add_representer(type(None), _none)
+_Dumper.add_representer(str, _str)
+
+
+def dump(data: Any) -> str:
+    return yaml.dump(
+        data,
+        Dumper=_Dumper,
+        default_flow_style=False,
+        sort_keys=False,
+        allow_unicode=True,
+        width=1_000_000,
+    )
+
+
+def write(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dump(data), encoding="utf-8")

framework/ai.py

@@ -0,0 +1,204 @@
+"""AI assistant files: AGENTS.md, assistant stubs, skills, and agent guards."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Any
+
+from framework.spec.check import ASSISTANTS
+
+AGENTS_DEFAULT = ".agents/skills"
+
+
+def _write(root: Path, relative: str, content: str) -> None:
+    target = root / relative
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+
+
+def assistant_targets(spec: dict[str, Any]) -> tuple[list[str], list[str]]:
+    """Skills folders and stub files for the selected assistants.
+
+    With no assistants selected, skills go to ``.agents/skills`` only, the
+    folder more tools read.
+    """
+    selected = [name for name in spec.get("ai", {}).get("assistants", {}) if name in ASSISTANTS]
+    if not selected:
+        return [AGENTS_DEFAULT], []
+    folders = list(dict.fromkeys(ASSISTANTS[name][0] for name in selected))
+    stubs = [stub for name in selected if (stub := ASSISTANTS[name][1]) is not None]
+    return folders, stubs
+
+
+def restricted_paths(spec: dict[str, Any]) -> list[str]:
+    """Folders agents must not read: each configured path up to its ``private`` segment."""
+    paths = list((spec.get("directories") or {}).values())
+    paths += [entry.get("path") for entry in (spec.get("extra_directories") or {}).values()]
+    restricted = set()
+    for path in paths:
+        if not isinstance(path, str):
+            continue
+        parts = path.split("/")
+        if "private" in parts:
+            restricted.add("/".join(parts[: parts.index("private") + 1]) + "/")
+    return sorted(restricted)
+
+
+def agents_md_stub(spec: dict[str, Any]) -> str:
+    lines = [
+        f"# {spec['name']}",
+        "",
+        "This is a Framework project (Python). Framework skills for this project are "
+        "installed for your AI assistant.",
+        "",
+        "Start every notebook and script with `import framework as fw` and `fw.scaffold()`. "
+        "It loads the project's settings, environment, and functions.",
+    ]
+    if spec.get("security", {}).get("sensitive"):
+        folders = ", ".join(f"`{path}`" for path in restricted_paths(spec))
+        lines += [
+            "",
+            f"This project holds restricted data. Do not read or print files in {folders}. "
+            "Work from the data dictionary and simulated data instead.",
+        ]
+    lines += ["", "## Project Notes", ""]
+    return "\n".join(lines) + "\n"
+
+
+def pointer_stub(name: str) -> str:
+    return (
+        f"# {name}\n\n"
+        "Project instructions live in AGENTS.md (the canonical AI context file) and in\n"
+        "the project's skills. Read AGENTS.md before working here; do not duplicate its\n"
+        "content in this file.\n"
+    )
+
+
+def _shipped(name: str) -> Traversable:
+    return resources.files("framework").joinpath(f"templates/skills/{name}")
+
+
+def _copy_tree(source: Traversable, root: Path, target: str) -> None:
+    for entry in source.iterdir():
+        if entry.is_dir():
+            _copy_tree(entry, root, f"{target}/{entry.name}")
+        else:
+            _write(root, f"{target}/{entry.name}", entry.read_text(encoding="utf-8"))
+
+
+def write_ai_files(root: Path, spec: dict[str, Any]) -> list[str]:
+    """Write AGENTS.md, assistant stubs, skills, and (for sensitive projects) agent guards."""
+    written = []
+    folders, stubs = assistant_targets(spec)
+    files = spec.get("files") or {}
+
+    if spec.get("ai", {}).get("agents_md") == "stub" and "AGENTS.md" not in files:
+        _write(root, "AGENTS.md", agents_md_stub(spec))
+        written.append("AGENTS.md")
+    for stub in stubs:
+        _write(root, stub, "@AGENTS.md\n" if stub == "CLAUDE.md" else pointer_stub(spec["name"]))
+        written.append(stub)
+
+    for name, entry in (spec.get("skills") or {}).items():
+        for folder in folders:
+            target = f"{folder}/{name}"
+            if entry.get("package") is True:
+                _copy_tree(_shipped(name), root, target)
+            else:
+                _write(root, f"{target}/SKILL.md", entry["content"])
+                for relative, content in (entry.get("files") or {}).items():
+                    _write(root, f"{target}/{relative}", content)
+            written.append(target)
+
+    if spec.get("security", {}).get("sensitive"):
+        guard = write_agent_guards(root, spec)
+        if guard:
+            written.append(guard)
+    return written
+
+
+def write_agent_guards(root: Path, spec: dict[str, Any]) -> str | None:
+    """Keep Claude Code out of restricted folders in a sensitive project.
+
+    Read and Edit deny rules block Claude Code's file tools, and the sandbox's
+    ``denyRead`` also blocks subprocesses such as ``python``. The sandbox fails
+    closed when it is unavailable. The rules match the R package's.
+    """
+    if "claude" not in (spec.get("ai") or {}).get("assistants", {}):
+        return None
+    restricted = [path.rstrip("/") for path in restricted_paths(spec)]
+    deny = [rule for path in restricted for rule in (f"Read(/{path}/**)", f"Edit(/{path}/**)")]
+    deny.append("Read(/.env)")
+    sandbox_deny = [f"./{path}" for path in restricted] + ["./.env"]
+
+    relative = ".claude/settings.json"
+    path = root / relative
+    settings: dict[str, Any] = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+    permissions = settings.setdefault("permissions", {})
+    permissions["deny"] = list(dict.fromkeys([*permissions.get("deny", []), *deny]))
+    sandbox = settings.setdefault("sandbox", {})
+    sandbox["enabled"] = True
+    sandbox["failIfUnavailable"] = True
+    filesystem = sandbox.setdefault("filesystem", {})
+    filesystem["denyRead"] = list(dict.fromkeys([*filesystem.get("denyRead", []), *sandbox_deny]))
+    _write(root, relative, json.dumps(settings, indent=2) + "\n")
+    return relative
+
+
+def _installed_spec(root: Path) -> dict[str, Any]:
+    """The spec a project was created from, or one rebuilt from its settings."""
+    path = root / ".framework" / "spec.json"
+    if path.is_file():
+        try:
+            spec = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            spec = None
+        if isinstance(spec, dict):
+            return spec
+    from framework.settings import settings_read
+    from framework.spec.resolve import TYPES, package_defaults
+
+    config = settings_read(root / "settings.yml") if (root / "settings.yml").is_file() else {}
+    ai = config.get("ai")
+    assistants = (ai.get("assistants") if isinstance(ai, dict) else None) or []
+    type = config.get("project_type")
+    return {
+        "ai": {"assistants": {name: True for name in assistants}},
+        "skills": package_defaults(type if type in TYPES else "project")["skills"],
+    }
+
+
+def ai_skills_update(project_path: str | Path = ".") -> list[str]:
+    """Replace the project's Framework skills with the versions in this package.
+
+    Only skills that ship with Framework are updated. Skills from a blueprint
+    or facet, and skills you wrote, are left alone. The skills and assistants
+    come from ``.framework/spec.json``, or from the settings for projects
+    without one.
+
+    Returns:
+        The skill folders written.
+    """
+    from framework._log import inform, show_messages
+
+    show_messages()
+    root = Path(project_path)
+    spec = _installed_spec(root)
+    folders, _ = assistant_targets(spec)
+    updated = []
+    for name, entry in (spec.get("skills") or {}).items():
+        if not (isinstance(entry, dict) and entry.get("package") is True):
+            continue
+        if not _shipped(name).is_dir():
+            continue
+        for folder in folders:
+            _copy_tree(_shipped(name), root, f"{folder}/{name}")
+            updated.append(f"{folder}/{name}")
+    if updated:
+        inform(f"✓ Updated {len(updated)} Framework skill(s)")
+    else:
+        inform("No Framework skills to update")
+    return updated

framework/bootstrap.py

@@ -0,0 +1,206 @@
+"""``bootstrap()``: prepare a project after ``git clone``.
+
+Every step is safe to repeat and none contacts the cloud:
+
+1. Make sure ``.gitignore`` ignores ``.env``.
+2. Create ``.env`` from ``.env.example`` when it is missing, and list
+   variables that are still empty.
+3. Create the project folders, which git does not carry when they are empty
+   or ignored.
+4. Create ``framework.db``, or add tables a newer version needs.
+5. Install the packages from ``uv.lock`` (``uv sync``).
+6. Install the git hooks enabled in the settings.
+
+R's ``bootstrap()`` follows the same contract, so ``fw bootstrap`` can call
+either language.
+"""
+
+from __future__ import annotations
+
+import getpass
+import json
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+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.errors import FrameworkError
+from framework.hooks import git_hooks_install
+from framework.project import _settings_in
+from framework.settings import settings_read
+from framework.spec.check import spec_check
+
+_SECRET_NAME = re.compile(
+    r"PASSWORD|SECRET|TOKEN|ACCESS_KEY|API_KEY|PRIVATE_KEY|CREDENTIAL", re.IGNORECASE
+)
+
+
+@dataclass
+class BootstrapResult:
+    """What ``bootstrap()`` did, and what is left for you.
+
+    Attributes:
+        root: The project folder.
+        done: The steps that changed something.
+        todo: Things to do by hand, such as filling in empty secrets.
+    """
+
+    root: Path
+    done: list[str] = field(default_factory=list)
+    todo: list[str] = field(default_factory=list)
+
+
+def _check_spec(root: Path) -> None:
+    path = root / ".framework" / "spec.json"
+    if not path.is_file():
+        return
+    try:
+        spec = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        raise FrameworkError(f".framework/spec.json is not valid JSON: {error}") from error
+    problems = spec_check(spec) if isinstance(spec, dict) else ["it is not a JSON object"]
+    if problems:
+        raise FrameworkError(
+            ".framework/spec.json is invalid: " + "; ".join(str(p) for p in problems)
+        )
+
+
+def _prepare_env(root: Path, interactive: bool, result: BootstrapResult) -> None:
+    env = root / ".env"
+    example = root / ".env.example"
+    if not env.exists() and example.is_file():
+        shutil.copyfile(example, env)
+        result.done.append("Created .env from .env.example")
+    if not env.is_file():
+        return
+    empty = [key for key, value in dotenv.read(env).items() if value == ""]
+    if interactive and empty:
+        values: dict[str, str] = {}
+        for key in empty:
+            ask = getpass.getpass if _SECRET_NAME.search(key) else input
+            answer = ask(f"{key} (leave empty to skip): ").strip()
+            if answer:
+                values[key] = answer
+        if values:
+            _fill_env(env, values)
+            result.done.append(f"Filled in {', '.join(values)} in .env")
+        empty = [key for key in empty if key not in values]
+    if empty:
+        result.todo.append(f"Fill in .env: {', '.join(empty)}")
+
+
+def _fill_env(path: Path, values: dict[str, str]) -> None:
+    """Set empty ``KEY=`` lines in a .env file, keeping the other lines as they are."""
+    lines = path.read_text(encoding="utf-8").splitlines()
+    for number, line in enumerate(lines):
+        match = re.match(r"^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)\s*=\s*$", line)
+        if match and match.group(2) in values:
+            value = values[match.group(2)]
+            quoted = json.dumps(value) if re.search(r"\s|#|\"|'", value) else value
+            lines[number] = f"{match.group(1)}{match.group(2)}={quoted}"
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+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]
+    extra = config.get("extra_directories")
+    if isinstance(extra, list):
+        folders += [
+            entry["path"] for entry in extra if isinstance(entry, dict) and entry.get("path")
+        ]
+    return folders
+
+
+def _create_folders(root: Path, config: dict[str, Any], result: BootstrapResult) -> None:
+    created = []
+    for folder in _folders(config):
+        if Path(folder).expanduser().is_absolute():
+            continue  # Shared drives and other places outside the project.
+        path = in_root(folder, root)
+        if not path.exists():
+            path.mkdir(parents=True)
+            created.append(folder)
+    if created:
+        result.done.append(f"Created folders: {', '.join(created)}")
+
+
+def _restore_packages(root: Path, result: BootstrapResult) -> None:
+    if not (root / "pyproject.toml").is_file():
+        return
+    uv = shutil.which("uv")
+    if uv is None:
+        raise FrameworkError(
+            "Package restore failed: uv is not installed. "
+            "Install it from https://docs.astral.sh/uv/ and run bootstrap again."
+        )
+    args = [uv, "sync", "--frozen"] if (root / "uv.lock").is_file() else [uv, "sync"]
+    completed = subprocess.run(args, cwd=root, check=False)
+    if completed.returncode != 0:
+        raise FrameworkError(
+            f"Package restore failed: {' '.join(args[1:])} exited with status "
+            f"{completed.returncode}"
+        )
+    result.done.append("Installed packages (uv sync)")
+
+
+def bootstrap(
+    path: str | Path = ".", *, interactive: bool = False, packages: bool = True
+) -> BootstrapResult:
+    """Prepare a cloned project so it is ready to work in.
+
+    Args:
+        path: The project folder.
+        interactive: Ask for the values of empty ``.env`` variables. Without
+            it, bootstrap never prompts and lists them as to-dos instead.
+        packages: Install the packages with uv.
+
+    Returns:
+        A ``BootstrapResult`` with the steps taken and the to-dos left.
+
+    Raises:
+        FrameworkError: The project cannot be prepared: there is no settings
+            file, the project is not a Python project, its spec is invalid,
+            or the packages could not be installed.
+    """
+    show_messages()
+    root = Path(path).expanduser().resolve()
+    settings_file = _settings_in(root) if root.is_dir() else None
+    if settings_file is None:
+        raise FrameworkError(f"No settings.yml in {root}. Is this a Framework project?")
+    config = settings_read(settings_file)
+    language = config.get("language") or "r"
+    if language != "python":
+        raise FrameworkError(
+            f"This is a {language} project. Prepare it with that language's Framework "
+            "(in R: framework::bootstrap())."
+        )
+    _check_spec(root)
+    result = BootstrapResult(root=root)
+
+    if ensure_secrets_ignored(root):
+        result.done.append("Added .env to .gitignore")
+    _prepare_env(root, interactive, result)
+    _create_folders(root, config, result)
+    existed = db.db_path(root).exists()
+    db.ensure_db(root)
+    result.done.append("Updated framework.db" if existed else "Created framework.db")
+    if packages:
+        _restore_packages(root, result)
+    if (root / ".git").exists() and git_hooks_install(settings_file, verbose=False):
+        result.done.append("Installed git hooks")
+
+    for step in result.done:
+        inform(f"✓ {step}")
+    for item in result.todo:
+        inform(f"• To do: {item}")
+    inform(f"Project ready: {root}")
+    return result