py-serverless-kit 0.1.0__py3-none-any.whl

py_serverless_kit/local/runner.py

@@ -0,0 +1,234 @@
+"""Run handlers and workflows on your machine, exactly as the cloud adapters would."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import sys
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional
+from urllib.parse import parse_qsl, urlsplit
+
+from ..core.project import Project
+from ..runtime import dispatch
+from ..runtime.context import Context
+from ..runtime.event import Event, EventType, Headers, HttpRequest, Record
+from ..runtime.manifest import BundleManifest, set_manifest
+from ..runtime.workflow import WorkflowEngine, in_process_runner
+from ..workflows import definition_dict
+
+
+def load_dotenv(path: Path) -> Dict[str, str]:
+    """Minimal ``.env`` parser (KEY=VALUE, comments, optional quotes)."""
+    values: Dict[str, str] = {}
+    if not path.is_file():
+        return values
+    for line in path.read_text("utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if key.startswith("export "):
+            key = key[len("export ") :].strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+            value = value[1:-1]
+        values[key] = value
+    return values
+
+
+class LocalRunner:
+    """Executes a project's functions in-process with the real dispatcher."""
+
+    def __init__(self, project: Project, env_file: Optional[str] = ".env") -> None:
+        self.project = project
+        self.source = (project.root / project.config.package.source).resolve()
+        self.env_file = project.root / env_file if env_file else None
+        manifest = project.bundle_manifest()
+        # Every workflow is runnable locally, whatever engine the cloud uses.
+        manifest["workflows"] = {
+            name: {"orchestrator": f"{name}-orchestrator", "definition": definition_dict(wf)}
+            for name, wf in project.config.workflows.items()
+        }
+        self.manifest = BundleManifest.from_dict(manifest)
+        self._purge_foreign_modules()
+
+    def _purge_foreign_modules(self) -> None:
+        """Drop cached modules that shadow this project's packages (e.g. another
+        project's ``app.handlers`` imported earlier in the same process)."""
+        try:
+            top_level = {p.stem if p.suffix == ".py" else p.name for p in self.source.iterdir()}
+        except OSError:
+            return
+        src = str(self.source)
+        for name, module in list(sys.modules.items()):
+            if name.split(".")[0] not in top_level:
+                continue
+            path = getattr(module, "__file__", None) or ""
+            if not path.startswith(src):
+                del sys.modules[name]
+        dispatch._HANDLERS.clear()
+
+    # ---------------------------------------------------------------- env
+    @contextmanager
+    def environment(self, function: Optional[str] = None) -> Iterator[None]:
+        cfg = self.project.config
+        env: Dict[str, str] = {
+            "PSKIT_PROVIDER": "local",
+            "PSKIT_SERVICE": cfg.service,
+            "PSKIT_STAGE": cfg.provider.stage,
+            "PSKIT_REGION": "local",
+            "PSKIT_LOG_FORMAT": os.environ.get("PSKIT_LOG_FORMAT", "text"),
+        }
+        env.update(cfg.provider.environment)
+        if function and function in cfg.functions:
+            env.update(cfg.functions[function].environment)
+            env["PSKIT_FUNCTION"] = function
+            env["PSKIT_HANDLER"] = cfg.functions[function].handler
+        if self.env_file is not None:
+            env.update(load_dotenv(self.env_file))
+        saved = {k: os.environ.get(k) for k in env}
+        os.environ.update(env)
+        added_path = str(self.source)
+        sys.path.insert(0, added_path)
+        set_manifest(self.manifest)
+        try:
+            yield
+        finally:
+            for key, old in saved.items():
+                if old is None:
+                    os.environ.pop(key, None)
+                else:
+                    os.environ[key] = old
+            if added_path in sys.path:
+                sys.path.remove(added_path)
+
+    # ---------------------------------------------------------------- invoke
+    def invoke(self, function: str, event: Event) -> Any:
+        if function not in self.project.config.functions:
+            known = ", ".join(sorted(self.project.config.functions))
+            raise KeyError(f"unknown function {function!r}; known: {known}")
+        event.function = function
+        event.provider = "local"
+        with self.environment(function):
+            return dispatch.execute(event, Context(function=function, provider="local"), function)
+
+    def run_workflow(self, name: str, data: Any, *, sleep: bool = False) -> Dict[str, Any]:
+        wf = self.project.config.workflows.get(name)
+        if wf is None:
+            known = ", ".join(sorted(self.project.config.workflows)) or "<none>"
+            raise KeyError(f"unknown workflow {name!r}; known: {known}")
+        engine = WorkflowEngine(
+            definition_dict(wf),
+            in_process_runner("local"),
+            sleep=time.sleep if sleep else (lambda _seconds: None),
+        )
+        with self.environment():
+            output = engine.run(data)
+        return {"output": output, "history": engine.history}
+
+    def reload(self) -> None:
+        """Forget imported user modules so edited code is picked up (dev server)."""
+        src = str(self.source)
+        for name, module in list(sys.modules.items()):
+            path = getattr(module, "__file__", None) or ""
+            if path.startswith(src) and "py_serverless_kit" not in path:
+                del sys.modules[name]
+        dispatch._HANDLERS.clear()
+
+
+# -------------------------------------------------------------------- event builders
+
+
+def http_event(
+    method: str = "GET",
+    path: str = "/",
+    body: Any = None,
+    headers: Optional[Dict[str, str]] = None,
+    query: Optional[Dict[str, str]] = None,
+) -> Event:
+    parts = urlsplit(path)
+    q = dict(parse_qsl(parts.query, keep_blank_values=True))
+    q.update(query or {})
+    hdrs = dict(headers or {})
+    if isinstance(body, (dict, list)):
+        body = json.dumps(body)
+        hdrs.setdefault("content-type", "application/json")
+    return Event(
+        type=EventType.HTTP,
+        http=HttpRequest(
+            method=method,
+            path=parts.path or "/",
+            headers=Headers(hdrs),
+            query=q,
+            body=body or b"",
+            source_ip="127.0.0.1",
+        ),
+    )
+
+
+def build_event(kind: str, data: Any = None, **http: Any) -> Event:
+    """Create a synthetic event for ``pskit invoke``."""
+    if kind == EventType.HTTP:
+        return http_event(
+            http.get("method", "GET"), http.get("path", "/"), data, http.get("headers"), http.get("query")
+        )
+    if kind in (EventType.QUEUE, EventType.TOPIC):
+        items: List[Any] = data if isinstance(data, list) else [data]
+        records = [
+            Record(id=f"local-{i}", body=json.dumps(item) if isinstance(item, (dict, list)) else item, source="local")
+            for i, item in enumerate(items)
+        ]
+        return Event(type=kind, records=records, source="local")
+    if kind == EventType.STORAGE:
+        items = data if isinstance(data, list) else [data or {}]
+        records = [
+            Record(
+                id=f"local-{i}",
+                bucket=(item or {}).get("bucket", "local-bucket"),
+                key=(item or {}).get("key", "example.txt"),
+                size=(item or {}).get("size", 0),
+                action=(item or {}).get("action", "created"),
+                source="local",
+            )
+            for i, item in enumerate(items)
+        ]
+        return Event(type=kind, records=records, source="local")
+    if kind not in EventType.ALL:
+        raise ValueError(f"unknown event type {kind!r}; one of {', '.join(EventType.ALL)}")
+    return Event(type=kind, data=data)
+
+
+def parse_data(value: Optional[str]) -> Any:
+    """``--data '{"a":1}'`` or ``--data @event.json`` (or plain text)."""
+    if value is None:
+        return None
+    if value.startswith("@"):
+        value = Path(value[1:]).read_text("utf-8")
+    try:
+        return json.loads(value)
+    except ValueError:
+        return value
+
+
+def response_to_dict(result: Any) -> Any:
+    from ..runtime.batch import BatchResult
+    from ..runtime.response import Response
+
+    if isinstance(result, BatchResult):
+        return {"batchItemFailures": [{"itemIdentifier": rid} for rid in result.failed]}
+    if isinstance(result, Response):
+        status, headers, raw = result.render()
+        try:
+            body: Any = json.loads(raw) if raw else None
+        except ValueError:
+            try:
+                body = raw.decode("utf-8")
+            except UnicodeDecodeError:
+                body = {"base64": base64.b64encode(raw).decode("ascii")}
+        return {"status": status, "headers": headers, "body": body}
+    return result

py_serverless_kit/local/server.py

@@ -0,0 +1,200 @@
+"""``pskit dev`` - a local HTTP server that routes requests to your handlers.
+
+* Every ``http`` event in the config becomes a route (``{id}`` / ``{path+}`` supported).
+* ``POST /__pskit/invoke/<function>``        invoke any function with a JSON body
+  (``?type=queue|topic|storage|schedule|invoke``; default ``invoke``).
+* ``POST /__pskit/workflows/<workflow>``     run a workflow on the embedded engine.
+* ``GET  /__pskit/``                         the dashboard (local view of the project).
+* Code changes are picked up on the next request (no restart needed).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import parse_qsl, urlsplit
+
+from ..runtime.event import Event, EventType, Headers, HttpRequest
+from ..runtime.response import Response, dumps
+from ..runtime.routing import match_path, method_matches
+from ..runtime.workflow import WorkflowFailed
+from .runner import LocalRunner, build_event
+
+Route = Tuple[str, str, str]  # (method, path, function)
+
+
+def _routes(runner: LocalRunner) -> List[Route]:
+    routes = []
+    for name, fn in runner.project.config.functions.items():
+        for ev in fn.events_of("http"):
+            routes.append((ev.method, ev.path, name))
+    # Static segments first so /users/me wins over /users/{id}.
+    routes.sort(key=lambda r: (r[1].count("{"), -len(r[1])))
+    return routes
+
+
+class _Watcher:
+    """Detects source changes by polling mtimes on request (cheap and portable)."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.stamp = self._scan()
+        self.lock = threading.Lock()
+
+    def _scan(self) -> float:
+        latest = 0.0
+        for dirpath, dirnames, filenames in os.walk(self.root):
+            dirnames[:] = [
+                d for d in dirnames if not d.startswith(".") and d not in ("__pycache__", "venv", "node_modules")
+            ]
+            for f in filenames:
+                if f.endswith(".py"):
+                    try:
+                        latest = max(latest, os.stat(os.path.join(dirpath, f)).st_mtime)
+                    except OSError:
+                        pass
+        return latest
+
+    def changed(self) -> bool:
+        with self.lock:
+            now = self._scan()
+            if now != self.stamp:
+                self.stamp = now
+                return True
+            return False
+
+
+def make_handler(runner: LocalRunner, echo=print):  # noqa: ANN001
+    routes = _routes(runner)
+    watcher = _Watcher(runner.source)
+    lock = threading.Lock()  # handlers share os.environ; serialize invocations
+
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "pskit-dev"
+
+        def log_message(self, fmt: str, *args: Any) -> None:  # quieter default logging
+            pass
+
+        def _send(self, status: int, headers: Dict[str, str], body: bytes, cookies: Optional[List[str]] = None) -> None:
+            self.send_response(status)
+            for k, v in headers.items():
+                self.send_header(k, v)
+            for cookie in cookies or []:
+                self.send_header("set-cookie", cookie)
+            self.send_header("content-length", str(len(body)))
+            self.end_headers()
+            if self.command != "HEAD":
+                self.wfile.write(body)
+
+        def _json(self, status: int, payload: Any) -> None:
+            self._send(status, {"content-type": "application/json"}, dumps(payload).encode("utf-8"))
+
+        def _body(self) -> bytes:
+            length = int(self.headers.get("content-length") or 0)
+            return self.rfile.read(length) if length else b""
+
+        def _dispatch(self) -> None:
+            if watcher.changed():
+                runner.reload()
+                echo("  (reloaded changed source files)")
+            url = urlsplit(self.path)
+            if url.path.startswith("/__pskit"):
+                return self._internal(url.path, dict(parse_qsl(url.query)))
+            for method, pattern, fn in routes:
+                params = match_path(pattern, url.path, tolerant=False)
+                if params is None or not (method_matches(method, self.command) or self.command == "OPTIONS"):
+                    continue
+                req = HttpRequest(
+                    method=self.command,
+                    path=url.path,
+                    headers=Headers(list(self.headers.items())),
+                    query=dict(parse_qsl(url.query, keep_blank_values=True)),
+                    path_params=params,
+                    body=self._body(),
+                    source_ip=self.client_address[0],
+                )
+                with lock:
+                    resp: Response = runner.invoke(fn, Event(type=EventType.HTTP, http=req))
+                status, headers, raw = resp.render()
+                echo(f"  {self.command} {url.path} -> {fn} [{status}]")
+                return self._send(status, headers, raw, resp.cookies)
+            self._json(404, {"error": "Not Found", "status": 404, "routes": [f"{m} {p}" for m, p, _ in routes]})
+
+        def _internal(self, path: str, query: Dict[str, str]) -> None:
+            parts = [p for p in path.split("/") if p][1:]
+            if not parts or parts == ["dashboard"]:
+                from ..dashboard.generator import local_record, render_html
+
+                html = render_html([local_record(runner.project)], title=f"{runner.project.config.service} (local)")
+                return self._send(200, {"content-type": "text/html; charset=utf-8"}, html.encode("utf-8"))
+            raw = self._body()
+            try:
+                data = json.loads(raw) if raw else None
+            except ValueError:
+                data = raw.decode("utf-8", "replace")
+            if parts[0] == "invoke" and len(parts) == 2:
+                kind = query.get("type", EventType.INVOKE)
+                try:
+                    with lock:
+                        result = runner.invoke(parts[1], build_event(kind, data))
+                except KeyError as exc:
+                    return self._json(404, {"error": str(exc)})
+                except Exception as exc:  # noqa: BLE001 - surface handler errors to the caller
+                    return self._json(500, {"errorType": type(exc).__name__, "cause": str(exc)})
+                from .runner import response_to_dict
+
+                echo(f"  invoke {parts[1]} ({kind})")
+                return self._json(200, {"result": response_to_dict(result)})
+            if parts[0] == "workflows" and len(parts) == 2:
+                try:
+                    with lock:
+                        out = runner.run_workflow(parts[1], data)
+                except KeyError as exc:
+                    return self._json(404, {"error": str(exc)})
+                except WorkflowFailed as exc:
+                    return self._json(
+                        500, {"status": "FAILED", "error": exc.error, "cause": exc.cause, "history": exc.history}
+                    )
+                echo(f"  workflow {parts[1]} SUCCEEDED")
+                return self._json(200, {"status": "SUCCEEDED", **out})
+            self._json(404, {"error": f"unknown internal path {path}"})
+
+        do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = do_HEAD = do_OPTIONS = _dispatch
+
+    return Handler, routes
+
+
+def serve(runner: LocalRunner, host: str = "127.0.0.1", port: int = 3000, echo=print) -> None:  # noqa: ANN001
+    handler, routes = make_handler(runner, echo)
+    httpd = ThreadingHTTPServer((host, port), handler)
+    base = f"http://{host}:{port}"
+    echo(f"pskit dev server for '{runner.project.config.service}' on {base}")
+    for method, path, fn in routes:
+        echo(f"  {method:7} {base}{path}  -> {fn}")
+    echo(f"  POST    {base}/__pskit/invoke/<function>?type=invoke|queue|topic|storage|schedule")
+    if runner.project.config.workflows:
+        echo(f"  POST    {base}/__pskit/workflows/<workflow>")
+    echo(f"  GET     {base}/__pskit/  (dashboard)")
+    echo("Press Ctrl+C to stop.")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        echo("stopping")
+    finally:
+        httpd.server_close()
+
+
+def start_background(runner: LocalRunner, host: str = "127.0.0.1", port: int = 0) -> Tuple[ThreadingHTTPServer, str]:
+    """Start the server on a thread (used by tests). Returns ``(server, base_url)``."""
+    handler, _ = make_handler(runner, echo=lambda _m: None)
+    httpd = ThreadingHTTPServer((host, port), handler)
+    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    thread.start()
+    return httpd, f"http://{host}:{httpd.server_address[1]}"
+
+
+__all__ = ["serve", "start_background"]

py_serverless_kit/packaging/__init__.py

@@ -0,0 +1,3 @@
+from .builder import BuildError, build_artifact, collect_sources
+
+__all__ = ["BuildError", "build_artifact", "collect_sources"]

py_serverless_kit/packaging/builder.py

@@ -0,0 +1,252 @@
+"""Build the deployment artifact (a deterministic zip).
+
+Layout of the bundle root::
+
+    <your sources>              filtered by package.include / package.exclude
+    py_serverless_kit/          the stdlib-only runtime (vendored)
+    pskit_manifest.json         functions, routes, embedded workflows
+    <provider shim files>       e.g. pskit_entry.py, main.py, function_app.py
+    <dependencies>              pip-installed when the provider runs no remote build
+    requirements.txt            when the provider builds remotely (GCP, Azure)
+
+The zip is byte-for-byte reproducible (sorted entries, fixed timestamps), so an
+unchanged project never triggers a redeploy.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterable, List, Optional, Pattern
+
+from ..providers.base import Artifact
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..core.project import Project
+
+DEFAULT_EXCLUDES = (
+    ".git/**",
+    ".hg/**",
+    ".pskit/**",
+    ".terraform/**",
+    ".venv/**",
+    "venv/**",
+    "env/**",
+    "**/__pycache__/**",
+    "**/*.pyc",
+    "**/*.pyo",
+    ".pytest_cache/**",
+    ".mypy_cache/**",
+    ".ruff_cache/**",
+    ".idea/**",
+    ".vscode/**",
+    "node_modules/**",
+    "tests/**",
+    "dist/**",
+    "build/**",
+    "*.egg-info/**",
+    "**/.DS_Store",
+    ".env",
+    ".env.*",
+    "**/*.tfstate",
+    "**/*.tfstate.*",
+    "pskit*.yml",
+    "pskit*.yaml",
+    "serverless_kit*.yml",
+)
+_FIXED_DATE = (1980, 1, 1, 0, 0, 0)
+_RUNTIME_PKG = "py_serverless_kit"
+
+
+class BuildError(Exception):
+    pass
+
+
+def glob_to_regex(pattern: str) -> Pattern[str]:
+    """Translate a gitignore-like glob (``**`` = any depth) into a regex."""
+    pattern = pattern.replace("\\", "/")
+    if pattern.startswith("./"):
+        pattern = pattern[2:]
+    if pattern.endswith("/"):
+        pattern += "**"
+    i, out = 0, []
+    while i < len(pattern):
+        c = pattern[i]
+        if c == "*":
+            if pattern[i : i + 3] == "**/":
+                out.append("(?:.*/)?")
+                i += 3
+                continue
+            if pattern[i : i + 2] == "**":
+                out.append(".*")
+                i += 2
+                continue
+            out.append("[^/]*")
+        elif c == "?":
+            out.append("[^/]")
+        else:
+            out.append(re.escape(c))
+        i += 1
+    return re.compile("^" + "".join(out) + "$")
+
+
+def _matches(rel: str, patterns: Iterable[Pattern[str]]) -> bool:
+    return any(p.match(rel) for p in patterns)
+
+
+def collect_sources(source: Path, include: List[str], exclude: List[str]) -> List[Path]:
+    inc = [glob_to_regex(p) for p in include]
+    exc = [glob_to_regex(p) for p in list(DEFAULT_EXCLUDES) + list(exclude)]
+    files: List[Path] = []
+    for dirpath, dirnames, filenames in os.walk(source):
+        rel_dir = Path(dirpath).relative_to(source).as_posix()
+        rel_dir = "" if rel_dir == "." else rel_dir + "/"
+        # prune excluded directories early (fast on big venvs / node_modules)
+        dirnames[:] = sorted(d for d in dirnames if not _matches(f"{rel_dir}{d}/x", exc))
+        for name in sorted(filenames):
+            rel = f"{rel_dir}{name}"
+            if _matches(rel, inc) and not _matches(rel, exc):
+                files.append(Path(dirpath) / name)
+    return files
+
+
+def _copy_runtime(dest: Path) -> None:
+    pkg_root = Path(__file__).resolve().parents[1]
+    target = dest / _RUNTIME_PKG
+    if target.exists():
+        shutil.rmtree(target)
+    target.mkdir(parents=True)
+    for name in ("__init__.py", "_version.py"):
+        shutil.copy2(pkg_root / name, target / name)
+    shutil.copytree(
+        pkg_root / "runtime",
+        target / "runtime",
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+    )
+    (target / "py.typed").write_text("", "utf-8")
+
+
+def read_requirements(path: Optional[Path]) -> List[str]:
+    if path is None or not path.is_file():
+        return []
+    reqs = []
+    for line in path.read_text("utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        # The runtime is vendored; never pull the full CLI (and its deps) into a function.
+        if re.match(r"^py[-_]serverless[-_]kit\b", line, re.I):
+            continue
+        reqs.append(line)
+    return reqs
+
+
+def _pip_install(reqs_file: Path, target: Path, flags: List[str], extra: List[str]) -> None:
+    cmd = (
+        [
+            sys.executable,
+            "-m",
+            "pip",
+            "install",
+            "--disable-pip-version-check",
+            "--no-compile",
+            "--quiet",
+            "--upgrade",
+            "-r",
+            str(reqs_file),
+            "--target",
+            str(target),
+        ]
+        + flags
+        + extra
+    )
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise BuildError(
+            "pip install failed while vendoring dependencies:\n"
+            + (proc.stderr or proc.stdout)[-4000:]
+            + "\nHint: a dependency may have no Linux wheel for this runtime. "
+            "Pin a version that ships manylinux wheels, or set `package.pip_args`."
+        )
+
+
+def _write_zip(build_dir: Path, zip_path: Path) -> int:
+    count = 0
+    tmp = zip_path.with_suffix(".zip.tmp")
+    with zipfile.ZipFile(tmp, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as zf:
+        for path in sorted(p for p in build_dir.rglob("*") if p.is_file()):
+            rel = path.relative_to(build_dir).as_posix()
+            if "/__pycache__/" in f"/{rel}" or rel.endswith(".pyc"):
+                continue
+            info = zipfile.ZipInfo(rel, date_time=_FIXED_DATE)
+            mode = 0o755 if os.access(path, os.X_OK) and path.suffix in ("", ".sh") else 0o644
+            info.external_attr = (0o100000 | mode) << 16
+            info.compress_type = zipfile.ZIP_DEFLATED
+            zf.writestr(info, path.read_bytes())
+            count += 1
+    os.replace(tmp, zip_path)
+    return count
+
+
+def digest(path: Path) -> tuple[str, str]:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest(), base64.b64encode(h.digest()).decode("ascii")
+
+
+def build_artifact(project: Project, *, skip_deps: bool = False, log=print) -> Artifact:  # noqa: ANN001
+    cfg = project.config
+    provider = project.provider
+    work = project.work_dir
+    build_dir = work / "build"
+    if build_dir.exists():
+        shutil.rmtree(build_dir)
+    build_dir.mkdir(parents=True)
+
+    source = (project.root / cfg.package.source).resolve()
+    files = collect_sources(source, cfg.package.include, cfg.package.exclude)
+    for f in files:
+        dest = build_dir / f.relative_to(source)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(f, dest)
+    log(f"  collected {len(files)} source file(s) from {source}")
+
+    _copy_runtime(build_dir)
+    (build_dir / "pskit_manifest.json").write_text(
+        json.dumps(project.bundle_manifest(), indent=2, sort_keys=True), "utf-8"
+    )
+    for rel, content in provider.shim_files(cfg).items():
+        dest = build_dir / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, "utf-8", newline="\n")
+
+    req_path = (project.root / cfg.package.requirements) if cfg.package.requirements else None
+    user_reqs = read_requirements(req_path)
+    vendor = provider.vendor_dependencies if cfg.package.vendor is None else cfg.package.vendor
+    final_reqs = provider.bundle_requirements(user_reqs)
+    if vendor:
+        if final_reqs and not skip_deps:
+            req_file = work / "requirements.vendor.txt"
+            req_file.write_text("\n".join(final_reqs) + "\n", "utf-8")
+            flags = provider.pip_platform(cfg.provider.runtime, cfg.provider.architecture)
+            log(f"  vendoring {len(final_reqs)} requirement(s) for {cfg.provider.runtime}/{cfg.provider.architecture}")
+            _pip_install(req_file, build_dir, flags, cfg.package.pip_args)
+    else:
+        (build_dir / "requirements.txt").write_text("\n".join(final_reqs) + ("\n" if final_reqs else ""), "utf-8")
+
+    zip_path = work / "artifact.zip"
+    count = _write_zip(build_dir, zip_path)
+    sha_hex, sha_b64 = digest(zip_path)
+    size = zip_path.stat().st_size
+    log(f"  artifact {zip_path.name}: {count} files, {size / 1024:.1f} KiB, sha256 {sha_hex[:12]}")
+    return Artifact(path=zip_path, sha256=sha_hex, sha256_b64=sha_b64, size=size, file_count=count, build_dir=build_dir)