sqlpush 0.5.1__tar.gz → 0.7.0__tar.gz

{sqlpush-0.5.1 → sqlpush-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlpush
-Version: 0.5.1
+Version: 0.7.0
 Summary: Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models
 Keywords: sqlalchemy,sqlmodel,fastapi,alembic,postgresql,timescaledb,prisma,schema,migrations,database,drift,cli
 Author: Juan Miguel Contreras
@@ -196,6 +196,66 @@ run under `psql`. Schema change and data backfill ship as one file.
 The [chain guide](docs/the-chain.md) covers the format, the gates and
 the workflows.
 
+## Project hook
+
+Drop a `sqlpush.py` where sqlpush can find it (the alembic `env.py` /
+pytest `conftest.py` pattern) and the CLI stops needing flags, specs
+and env vars. Two discovered locations, first match wins — or name
+any file explicitly with `--hook`/`$SQLPUSH_HOOK`:
+
+1. `migrations/sqlpush.py` — preferred: it lives next to the chain,
+   no repo-root clutter.
+2. `sqlpush.py` — repo root, kept as the backwards-compat fallback.
+
+```python
+# migrations/sqlpush.py — the preferred location
+def get_metadata():  # REQUIRED for diff/check/push/revision
+    from myapp.models import metadata
+
+    return metadata  # -> a populated MetaData
+
+
+def get_dsn() -> str:  # REQUIRED for every verb
+    from myapp.settings import DATABASE_URL
+
+    return DATABASE_URL  # -> a full psycopg DSN
+
+
+CHAIN_DIR = "migrations/chain"  # OPTIONAL — default for --dir
+```
+
+With that file in place, `uv run sqlpush revision -m "change"` just
+works: no `--dsn`, no `module:attribute`, no credentials on the
+command line, no PYTHONPATH. Inputs resolve with a fixed precedence:
+
+| input | explicit flag | hook | fallback |
+| --- | --- | --- | --- |
+| `--dsn` / `--ref-dsn` | wins | `get_dsn()` | `$DATABASE_URL`, only without a hook and never for `--ref-dsn` |
+| `module:attribute` (diff/check/push/revision) | wins | `get_metadata()` | usage error |
+| `--dir` (revision/migrate/stamp) | wins | `CHAIN_DIR` | `migrations/versions` |
+| which file is the hook | `--hook PATH` | — | `$SQLPUSH_HOOK`, else first match: `migrations/sqlpush.py`, then root `sqlpush.py` |
+
+The hook's location is the alembic `-c` equivalent: `--hook` >
+`$SQLPUSH_HOOK` > discovery, any location you want (relative paths
+resolve against the CWD) — and the explicit forms fail loud, with an
+error naming that path (`custom/hook.py: file not found`)
+instead of falling back to the discovered candidates.
+
+A hook that is missing a member a verb needs — or whose
+`get_dsn()`/`get_metadata()` raises — fails with a typed error naming
+the file that actually loaded and the member
+(`migrations/sqlpush.py: missing get_dsn()`), never a traceback.
+Without a hook, every verb behaves exactly as before.
+
+One deliberate detail: on discovering the hook, sqlpush **appends**
+your CWD to `sys.path` instead of prepending it — whatever location
+the hook loaded from, never the hook's own directory. A root
+`sqlpush.py` would otherwise shadow the installed package the moment
+you ran the CLI from your repo root; appending guarantees the real
+package always wins, and the hook itself is loaded by path only (the
+`migrations/` candidate has no shadowing concern but loads the same
+way).
+
 ## Exit codes
 
 | verb | 0 | 1 | 2 | 3 |
@@ -223,13 +283,16 @@ The knobs, per verb:
 | verb | flags |
 | --- | --- |
 | `push` | `--allow-destructive` `--safe-only` `--no-lock` `--lock-timeout` `--advisory-wait` `--no-concurrently` `--statement-timeout` |
-| `revision` | `--ref-dsn` (required) `-m/--message` `--no-concurrently` `--dir` |
+| `revision` | `--ref-dsn` (required without a hook) `-m/--message` `--no-concurrently` `--dir` |
 | `migrate` | `--allow-destructive` `--advisory-wait` `--lock-timeout` `--statement-timeout` `--dir` |
 | `stamp` | `--force` `--dir` |
 
-Every verb except `revision` takes `--dsn` (or `$DATABASE_URL`).
-`revision` requires `--ref-dsn`, with no env fallback: the reference
-DB is a different database from the push target. `diff`, `check`,
+Every verb takes `--hook PATH` (or `$SQLPUSH_HOOK`) to name the hook
+file explicitly. Every verb except `revision` takes `--dsn` (or
+`$DATABASE_URL`, or the project hook's `get_dsn()`). `revision`
+takes `--ref-dsn` — or
+the hook — with no env fallback: the reference DB is a different
+database from the push target. `diff`, `check`,
 `push` and `revision` also take repeatable `--schema` / `--exclude`.
 Timeouts are seconds; a `lock_timeout` bounds how long a statement
 waits on a lock before failing, `statement_timeout` bounds each

{sqlpush-0.5.1 → sqlpush-0.7.0}/README.md

@@ -167,6 +167,66 @@ run under `psql`. Schema change and data backfill ship as one file.
 The [chain guide](docs/the-chain.md) covers the format, the gates and
 the workflows.
 
+## Project hook
+
+Drop a `sqlpush.py` where sqlpush can find it (the alembic `env.py` /
+pytest `conftest.py` pattern) and the CLI stops needing flags, specs
+and env vars. Two discovered locations, first match wins — or name
+any file explicitly with `--hook`/`$SQLPUSH_HOOK`:
+
+1. `migrations/sqlpush.py` — preferred: it lives next to the chain,
+   no repo-root clutter.
+2. `sqlpush.py` — repo root, kept as the backwards-compat fallback.
+
+```python
+# migrations/sqlpush.py — the preferred location
+def get_metadata():  # REQUIRED for diff/check/push/revision
+    from myapp.models import metadata
+
+    return metadata  # -> a populated MetaData
+
+
+def get_dsn() -> str:  # REQUIRED for every verb
+    from myapp.settings import DATABASE_URL
+
+    return DATABASE_URL  # -> a full psycopg DSN
+
+
+CHAIN_DIR = "migrations/chain"  # OPTIONAL — default for --dir
+```
+
+With that file in place, `uv run sqlpush revision -m "change"` just
+works: no `--dsn`, no `module:attribute`, no credentials on the
+command line, no PYTHONPATH. Inputs resolve with a fixed precedence:
+
+| input | explicit flag | hook | fallback |
+| --- | --- | --- | --- |
+| `--dsn` / `--ref-dsn` | wins | `get_dsn()` | `$DATABASE_URL`, only without a hook and never for `--ref-dsn` |
+| `module:attribute` (diff/check/push/revision) | wins | `get_metadata()` | usage error |
+| `--dir` (revision/migrate/stamp) | wins | `CHAIN_DIR` | `migrations/versions` |
+| which file is the hook | `--hook PATH` | — | `$SQLPUSH_HOOK`, else first match: `migrations/sqlpush.py`, then root `sqlpush.py` |
+
+The hook's location is the alembic `-c` equivalent: `--hook` >
+`$SQLPUSH_HOOK` > discovery, any location you want (relative paths
+resolve against the CWD) — and the explicit forms fail loud, with an
+error naming that path (`custom/hook.py: file not found`)
+instead of falling back to the discovered candidates.
+
+A hook that is missing a member a verb needs — or whose
+`get_dsn()`/`get_metadata()` raises — fails with a typed error naming
+the file that actually loaded and the member
+(`migrations/sqlpush.py: missing get_dsn()`), never a traceback.
+Without a hook, every verb behaves exactly as before.
+
+One deliberate detail: on discovering the hook, sqlpush **appends**
+your CWD to `sys.path` instead of prepending it — whatever location
+the hook loaded from, never the hook's own directory. A root
+`sqlpush.py` would otherwise shadow the installed package the moment
+you ran the CLI from your repo root; appending guarantees the real
+package always wins, and the hook itself is loaded by path only (the
+`migrations/` candidate has no shadowing concern but loads the same
+way).
+
 ## Exit codes
 
 | verb | 0 | 1 | 2 | 3 |
@@ -194,13 +254,16 @@ The knobs, per verb:
 | verb | flags |
 | --- | --- |
 | `push` | `--allow-destructive` `--safe-only` `--no-lock` `--lock-timeout` `--advisory-wait` `--no-concurrently` `--statement-timeout` |
-| `revision` | `--ref-dsn` (required) `-m/--message` `--no-concurrently` `--dir` |
+| `revision` | `--ref-dsn` (required without a hook) `-m/--message` `--no-concurrently` `--dir` |
 | `migrate` | `--allow-destructive` `--advisory-wait` `--lock-timeout` `--statement-timeout` `--dir` |
 | `stamp` | `--force` `--dir` |
 
-Every verb except `revision` takes `--dsn` (or `$DATABASE_URL`).
-`revision` requires `--ref-dsn`, with no env fallback: the reference
-DB is a different database from the push target. `diff`, `check`,
+Every verb takes `--hook PATH` (or `$SQLPUSH_HOOK`) to name the hook
+file explicitly. Every verb except `revision` takes `--dsn` (or
+`$DATABASE_URL`, or the project hook's `get_dsn()`). `revision`
+takes `--ref-dsn` — or
+the hook — with no env fallback: the reference DB is a different
+database from the push target. `diff`, `check`,
 `push` and `revision` also take repeatable `--schema` / `--exclude`.
 Timeouts are seconds; a `lock_timeout` bounds how long a statement
 waits on a lock before failing, `statement_timeout` bounds each

{sqlpush-0.5.1 → sqlpush-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.5.1"
+version = "0.7.0"
 description = "Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models"
 readme = "README.md"
 requires-python = ">=3.10"

{sqlpush-0.5.1 → sqlpush-0.7.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.5.1"
+version = "0.7.0"
 description = "Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models"
 readme = "README.md"
 authors = [

{sqlpush-0.5.1 → sqlpush-0.7.0}/src/sqlpush/cli.py

@@ -24,6 +24,7 @@ from sqlalchemy.pool import NullPool
 
 from sqlpush import api
 from sqlpush.core.render import render
+from sqlpush.hook import hook_chain_dir, hook_dsn, hook_metadata, load_project_hook
 from sqlpush.types import (
     CheckResult,
     MetadataImportError,
@@ -38,8 +39,14 @@ app = typer.Typer(add_completion=False, help=__doc__ or "")
 SchemaOpt = Annotated[list[str] | None, typer.Option("--schema")]
 ExcludeOpt = Annotated[list[str] | None, typer.Option("--exclude")]
 # Path-typed options need the Annotated form: B008 (call in default) only
-# exempts typer.Option for non-Path annotations
-DirOpt = Annotated[Path, typer.Option("--dir")]
+# exempts typer.Option for non-Path annotations. None default: lets the
+# verb tell "user passed --dir" apart from "use hook/default" resolution.
+DirOpt = Annotated[Path | None, typer.Option("--dir")]
+# Hook-location override, on EVERY verb (hook loading is shared
+# machinery like --dsn): flag > $SQLPUSH_HOOK > candidates, and an
+# explicit path that does not exist fails loud in the loader.
+HookOpt = Annotated[Path | None, typer.Option("--hook")]
+DEFAULT_CHAIN_DIR = Path("migrations/versions")
 
 
 def _load_metadata(spec: str):
@@ -53,7 +60,28 @@ def _load_metadata(spec: str):
         raise MetadataImportError(f"cannot import {spec!r}: {exc}") from exc
 
 
-def _engine(dsn: str | None):
+def _metadata(metadata_spec: str | None, hook):
+    """Resolve the metadata source: flag > hook.get_metadata() > usage error.
+
+    The hook path returns the OBJECT itself (no module:attribute import
+    happens); the positional path is untouched.
+    """
+    if metadata_spec is not None:
+        return _load_metadata(metadata_spec)
+    if hook is not None:
+        return hook_metadata(hook)
+    typer.secho(
+        "metadata spec required: pass module:attribute or add get_metadata() to ./sqlpush.py",
+        fg="red",
+        err=True,
+    )
+    raise typer.Exit(code=2)
+
+
+def _engine(dsn: str | None, hook=None):
+    # precedence: explicit flag > hook.get_dsn() > $DATABASE_URL > error
+    if dsn is None and hook is not None:
+        dsn = hook_dsn(hook)
     dsn = dsn or os.environ.get("DATABASE_URL")
     if not dsn:
         typer.secho("no --dsn and no DATABASE_URL set", fg="red", err=True)
@@ -66,6 +94,13 @@ def _engine(dsn: str | None):
         raise typer.Exit(code=1) from exc
 
 
+def _resolve_dir(out_dir: Path | None, hook) -> Path:
+    """Resolve --dir: explicit flag > hook.CHAIN_DIR > current default."""
+    if out_dir is not None:
+        return out_dir
+    return Path(hook_chain_dir(hook, str(DEFAULT_CHAIN_DIR)))
+
+
 def _emit_json(plan) -> None:
     typer.echo(json.dumps(plan.to_json_dict(), indent=2))
 
@@ -81,16 +116,18 @@ def _risk_summary(p) -> None:
 
 @app.command()
 def diff(
-    metadata_spec: str = typer.Argument(..., help="module:metadata"),
+    metadata_spec: str | None = typer.Argument(None, help="module:metadata"),
     dsn: str | None = typer.Option(None),
     json_output: bool = typer.Option(False, "--json"),
     verbose: bool = typer.Option(False, "--verbose"),
     quiet: bool = typer.Option(False, "--quiet"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
+    hook_path: HookOpt = None,
 ):
-    md = _load_metadata(metadata_spec)
-    engine = _engine(dsn)
+    hook = load_project_hook(hook_path)
+    md = _metadata(metadata_spec, hook)
+    engine = _engine(dsn, hook)
     try:
         p = api.plan(md, engine, schemas=schema, exclude=exclude or ())
         if json_output:
@@ -106,16 +143,18 @@ def diff(
 
 @app.command()
 def check(
-    metadata_spec: str = typer.Argument(...),
+    metadata_spec: str | None = typer.Argument(None),
     dsn: str | None = typer.Option(None),
     json_output: bool = typer.Option(False, "--json"),
     verbose: bool = typer.Option(False, "--verbose"),
     quiet: bool = typer.Option(False, "--quiet"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
+    hook_path: HookOpt = None,
 ):
-    md = _load_metadata(metadata_spec)
-    engine = _engine(dsn)
+    hook = load_project_hook(hook_path)
+    md = _metadata(metadata_spec, hook)
+    engine = _engine(dsn, hook)
     try:
         # plan ONCE and derive everything from that single object: a
         # second plan could observe a different DB state than the one
@@ -140,7 +179,7 @@ def check(
 
 @app.command()
 def push(
-    metadata_spec: str = typer.Argument(...),
+    metadata_spec: str | None = typer.Argument(None),
     dsn: str | None = typer.Option(None),
     json_output: bool = typer.Option(False, "--json"),
     allow_destructive: bool = typer.Option(False, "--allow-destructive"),
@@ -154,9 +193,11 @@ def push(
     quiet: bool = typer.Option(False, "--quiet"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
+    hook_path: HookOpt = None,
 ):
-    md = _load_metadata(metadata_spec)
-    engine = _engine(dsn)
+    hook = load_project_hook(hook_path)
+    md = _metadata(metadata_spec, hook)
+    engine = _engine(dsn, hook)
     try:
         try:
             report = api.push(
@@ -223,25 +264,36 @@ def push(
 
 @app.command()
 def revision(
-    metadata_spec: str = typer.Argument(..., help="module:metadata"),
-    ref_dsn: str = typer.Option(..., "--ref-dsn"),
+    metadata_spec: str | None = typer.Argument(None, help="module:metadata"),
+    ref_dsn: str | None = typer.Option(None, "--ref-dsn"),
     message: str | None = typer.Option(None, "--message", "-m"),
-    out_dir: DirOpt = Path("migrations/versions"),
+    out_dir: DirOpt = None,
     no_concurrently: bool = typer.Option(False, "--no-concurrently"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
+    hook_path: HookOpt = None,
 ):
     """Generate the next migration file from models vs the reference DB."""
-    md = _load_metadata(metadata_spec)
-    # required --ref-dsn (no DATABASE_URL fallback): the reference DB is a
-    # different database from the push target — conflating them silently
-    # would chain against the wrong head
+    hook = load_project_hook(hook_path)
+    md = _metadata(metadata_spec, hook)
+    # --ref-dsn: flag > hook.get_dsn(); NO DATABASE_URL fallback (the
+    # reference DB is a different database from the push target —
+    # conflating them silently would chain against the wrong head)
+    if ref_dsn is None and hook is not None:
+        ref_dsn = hook_dsn(hook)
+    if ref_dsn is None:
+        typer.secho(
+            "--ref-dsn is required (or add get_dsn() to ./sqlpush.py)",
+            fg="red",
+            err=True,
+        )
+        raise typer.Exit(code=2)
     engine = _engine(ref_dsn)
     try:
         path = api.revision(
             md,
             engine,
-            out_dir=out_dir,
+            out_dir=_resolve_dir(out_dir, hook),
             message=message,
             concurrently=not no_concurrently,
             schemas=schema,
@@ -260,14 +312,16 @@ def migrate(
     advisory_wait: float = typer.Option(30.0, "--advisory-wait"),
     lock_timeout: float = typer.Option(5.0, "--lock-timeout"),
     statement_timeout: float | None = typer.Option(None, "--statement-timeout"),
-    out_dir: DirOpt = Path("migrations/versions"),
+    out_dir: DirOpt = None,
+    hook_path: HookOpt = None,
 ):
     """Replay pending migration files (gates + checksum bookkeeping)."""
-    engine = _engine(dsn)
+    hook = load_project_hook(hook_path)
+    engine = _engine(dsn, hook)
     try:
         report = api.migrate(
             engine,
-            chain_dir=out_dir,
+            chain_dir=_resolve_dir(out_dir, hook),
             allow_destructive=allow_destructive,
             advisory_wait=advisory_wait,
             lock_timeout=lock_timeout,
@@ -290,12 +344,14 @@ def migrate(
 def stamp(
     dsn: str | None = typer.Option(None),
     force: bool = typer.Option(False, "--force"),
-    out_dir: DirOpt = Path("migrations/versions"),
+    out_dir: DirOpt = None,
+    hook_path: HookOpt = None,
 ):
     """Adopt an existing DB: register chain files without executing SQL."""
-    engine = _engine(dsn)
+    hook = load_project_hook(hook_path)
+    engine = _engine(dsn, hook)
     try:
-        report = api.stamp(engine, chain_dir=out_dir, force=force)
+        report = api.stamp(engine, chain_dir=_resolve_dir(out_dir, hook), force=force)
     finally:
         engine.dispose()
     typer.echo(

sqlpush-0.7.0/src/sqlpush/hook.py

@@ -0,0 +1,147 @@
+# src/sqlpush/hook.py
+"""Project hook: ``migrations/sqlpush.py`` first, then ``sqlpush.py``.
+
+The alembic ``env.py`` / pytest ``conftest.py`` pattern: a hook file
+next to where the user runs the CLI becomes the source of defaults for
+metadata, DSN and chain dir. Explicit flags always win (flag > hook >
+env/default); without the hook every verb behaves exactly as before.
+
+Discovery checks ``migrations/sqlpush.py`` first (the preferred
+location — it lives next to the chain, no root clutter) and falls
+back to the repo-root ``sqlpush.py`` (backwards compat); first match
+wins. An explicit override — the ``--hook`` flag or the
+``SQLPUSH_HOOK`` env var (the alembic ``-c`` equivalent) — names any
+file instead, and is fail-loud: a path that does not exist raises a
+:class:`HookError` naming that path, never a silent fallback to
+the candidates. Precedence: flag > env > candidates.
+
+Loading is BY PATH (``spec_from_file_location``), never by module
+name: a file named ``sqlpush.py`` in the CWD would shadow the
+installed package if the CWD came first on ``sys.path`` — so the CWD
+is APPENDED (never ``insert(0)``), and always the CWD, never the
+loaded file's own directory (the append exists so the consumer's
+package imports resolve). This guarantees the package wins for
+normal imports while the hook itself is only ever loaded explicitly.
+
+Only typed :class:`SqlpushError`-family errors escape this module,
+always naming the file that actually loaded and the member involved.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from sqlpush.types import SqlpushError
+
+HOOK_FILENAME = "sqlpush.py"
+HOOK_ENV_VAR = "SQLPUSH_HOOK"
+# first match wins: migrations/ (next to the chain) preferred, the
+# repo root kept as the backwards-compat fallback
+CANDIDATES = (Path("migrations") / HOOK_FILENAME, Path(HOOK_FILENAME))
+# resolved loaded path -> the spelling it was named with (candidate or
+# override path): _hook_label uses it so override-loaded hooks error in
+# the GIVEN spelling, matching the candidate message contract
+_LOADED_LABELS: dict[Path, str] = {}
+
+
+class HookError(SqlpushError):
+    """The project hook is broken or incomplete — names file + member."""
+
+
+def load_project_hook(hook_path: Path | str | None = None) -> ModuleType | None:
+    """Load the project hook; ``None`` when nothing resolves.
+
+    Precedence: ``hook_path`` (the ``--hook`` flag) > ``$SQLPUSH_HOOK``
+    > the first existing candidate (``migrations/sqlpush.py``, then the
+    repo root). An explicit path (flag or env) is fail-loud: when it
+    does not exist a :class:`HookError` names that path — an
+    explicit instruction must not silently fall back to discovery.
+    Relative paths resolve against the CWD. On success the CWD is
+    appended to ``sys.path`` (never inserted at the front, and never
+    the loaded file's own directory — see the module docstring). Any
+    import-time failure is re-typed as :class:`HookError` naming the
+    file that failed, in the spelling it was named with.
+    """
+    explicit: Path | None = None
+    if hook_path is not None:
+        explicit = Path(hook_path)
+    else:
+        env_value = os.environ.get(HOOK_ENV_VAR)
+        if env_value:  # empty string ≡ unset
+            explicit = Path(env_value)
+    if explicit is not None:
+        if not explicit.is_file():
+            raise HookError(f"{explicit.as_posix()}: file not found")
+        return _load_hook_file(explicit)
+    hook_file = next((p for p in CANDIDATES if p.is_file()), None)
+    if hook_file is None:
+        return None
+    return _load_hook_file(hook_file)
+
+
+def _load_hook_file(hook_file: Path) -> ModuleType:
+    sys.path.append(os.getcwd())
+    spec = importlib.util.spec_from_file_location("sqlpush_project_hook", hook_file)
+    if spec is None or spec.loader is None:
+        raise HookError(f"{hook_file.as_posix()}: cannot load (invalid module spec)")
+    module = importlib.util.module_from_spec(spec)
+    _LOADED_LABELS[hook_file.resolve()] = hook_file.as_posix()
+    try:
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        raise HookError(f"{hook_file.as_posix()}: import raised: {exc}") from exc
+    return module
+
+
+def _hook_label(hook: ModuleType) -> str:
+    """The spelling the loaded hook file was named with (posix, portable).
+
+    Errors must name the file that actually loaded: map the loaded
+    module's ``__file__`` back to its load-time spelling (candidate or
+    override path); unknown provenance degrades to the bare filename.
+    """
+    loaded_file = getattr(hook, "__file__", None)
+    if not loaded_file:
+        return HOOK_FILENAME
+    loaded = Path(loaded_file).resolve()
+    label = _LOADED_LABELS.get(loaded)
+    if label is not None:
+        return label
+    for candidate in CANDIDATES:
+        if (Path.cwd() / candidate).resolve() == loaded:
+            return candidate.as_posix()
+    return HOOK_FILENAME
+
+
+def hook_dsn(hook: ModuleType) -> str:
+    """Call ``get_dsn()`` LAZILY — only when a verb actually needs it."""
+    label = _hook_label(hook)
+    getter = getattr(hook, "get_dsn", None)
+    if getter is None:
+        raise HookError(f"{label}: missing get_dsn()")
+    try:
+        return getter()
+    except Exception as exc:
+        raise HookError(f"{label}: get_dsn() raised: {exc}") from exc
+
+
+def hook_metadata(hook: ModuleType):
+    """Call ``get_metadata()`` LAZILY — returns the populated MetaData object."""
+    label = _hook_label(hook)
+    getter = getattr(hook, "get_metadata", None)
+    if getter is None:
+        raise HookError(f"{label}: missing get_metadata()")
+    try:
+        return getter()
+    except Exception as exc:
+        raise HookError(f"{label}: get_metadata() raised: {exc}") from exc
+
+
+def hook_chain_dir(hook: ModuleType | None, default: str) -> str:
+    """Read ``CHAIN_DIR`` as a module attribute; ``default`` when unset."""
+    value = getattr(hook, "CHAIN_DIR", None) if hook is not None else None
+    return default if value is None else value