amie 0.1.0__tar.gz

amie-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nk0s1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

amie-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.3
+Name: amie
+Version: 0.1.0
+Summary: Your private memory intelligence — captures thoughts from anywhere, organises them into your vault, and reflects insights back to you. Entirely local.
+Keywords: obsidian,notes,ocr,ollama,local-ai,knowledge-management
+Author: nk0s1
+Author-email: nk0s1 <nkosinathi@whakatau.com>
+License: MIT License
+         
+         Copyright (c) 2026 nk0s1
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: News/Diary
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Requires-Dist: ollama>=0.6.2
+Requires-Dist: pillow-heif>=1.3.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: typer>=0.25.1
+Requires-Dist: watchdog>=6.0.0
+Requires-Python: >=3.12
+Project-URL: Documentation, https://gitlab.com/nkosinathi1/amie/-/tree/main/docs
+Project-URL: Issues, https://gitlab.com/nkosinathi1/amie/-/issues
+Project-URL: Source, https://gitlab.com/nkosinathi1/amie
+Description-Content-Type: text/markdown
+
+# AMI — Anonymous Memory Intelligence
+
+Your private memory intelligence — captures thoughts from anywhere, organises them into your vault, and reflects insights back to you. Entirely local.
+
+**Status:** Alpha. The core CLI and domain modules are in place; ingestion, OCR, and the weekly-digest pipeline are still being built.
+
+**Hard constraints:**
+- Open-source, no paid services.
+- Local-first AI via Ollama only — your notes never leave your device.
+- Built for the user's existing Obsidian vault conventions (`KEY: value` headers, lifecycle states `#infant → #child → #developing → #adult → #on-ice → #removed`).
+
+## Install
+
+```bash
+# Prereqs: Python 3.12, uv, and Ollama. See docs/01-prerequisites.md.
+git clone git@gitlab.com:nkosinathi1/ami.git ~/source/repos/ami
+cd ~/source/repos/ami
+uv sync
+ami init        # one-time setup wizard
+ami doctor      # verify uv / Ollama / models / vault / ssh
+```
+
+## Try it
+
+```bash
+ami --help                # discover every subcommand
+ami doctor                # health-check the environment
+ami vault status          # confirm inbox folders are in place
+ami dev guard             # lint + format check + tests + security audit
+```
+
+## Documentation
+
+The build guide and operator manual live at `~/source/ubuntu/docs/ami/`:
+
+- `00-overview.md` — start here.
+- `standards.md` — engineering rules every contribution is held to.
+- `security.md` — threat model.
+- `14-cli-reference.md` — every `ami` command, what it does.
+- `15-ide-setup.md` — VS Code + WSL setup.
+- `activity-log.md` — append-only audit trail of every change.
+
+## License
+
+MIT. See `LICENSE`.

amie-0.1.0/README.md

@@ -0,0 +1,45 @@
+# AMI — Anonymous Memory Intelligence
+
+Your private memory intelligence — captures thoughts from anywhere, organises them into your vault, and reflects insights back to you. Entirely local.
+
+**Status:** Alpha. The core CLI and domain modules are in place; ingestion, OCR, and the weekly-digest pipeline are still being built.
+
+**Hard constraints:**
+- Open-source, no paid services.
+- Local-first AI via Ollama only — your notes never leave your device.
+- Built for the user's existing Obsidian vault conventions (`KEY: value` headers, lifecycle states `#infant → #child → #developing → #adult → #on-ice → #removed`).
+
+## Install
+
+```bash
+# Prereqs: Python 3.12, uv, and Ollama. See docs/01-prerequisites.md.
+git clone git@gitlab.com:nkosinathi1/ami.git ~/source/repos/ami
+cd ~/source/repos/ami
+uv sync
+ami init        # one-time setup wizard
+ami doctor      # verify uv / Ollama / models / vault / ssh
+```
+
+## Try it
+
+```bash
+ami --help                # discover every subcommand
+ami doctor                # health-check the environment
+ami vault status          # confirm inbox folders are in place
+ami dev guard             # lint + format check + tests + security audit
+```
+
+## Documentation
+
+The build guide and operator manual live at `~/source/ubuntu/docs/ami/`:
+
+- `00-overview.md` — start here.
+- `standards.md` — engineering rules every contribution is held to.
+- `security.md` — threat model.
+- `14-cli-reference.md` — every `ami` command, what it does.
+- `15-ide-setup.md` — VS Code + WSL setup.
+- `activity-log.md` — append-only audit trail of every change.
+
+## License
+
+MIT. See `LICENSE`.

amie-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "amie"
+version = "0.1.0"
+description = "Your private memory intelligence — captures thoughts from anywhere, organises them into your vault, and reflects insights back to you. Entirely local."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "nk0s1", email = "nkosinathi@whakatau.com" },
+]
+keywords = ["obsidian", "notes", "ocr", "ollama", "local-ai", "knowledge-management"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Office/Business :: News/Diary",
+    "Topic :: Text Processing :: Markup",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "ollama>=0.6.2",
+    "pillow-heif>=1.3.0",
+    "python-dotenv>=1.2.2",
+    "python-frontmatter>=1.1.0",
+    "typer>=0.25.1",
+    "watchdog>=6.0.0",
+]
+
+[project.urls]
+Documentation = "https://gitlab.com/nkosinathi1/amie/-/tree/main/docs"
+Issues = "https://gitlab.com/nkosinathi1/amie/-/issues"
+Source = "https://gitlab.com/nkosinathi1/amie"
+
+[project.scripts]
+amie = "amie.cli:app"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "RUF"]
+
+[tool.ruff.lint.flake8-bugbear]
+# Typer's normal pattern is `typer.Option(...)` / `typer.Argument(...)` in
+# function defaults — these calls return immutable descriptors, not mutable
+# objects, so B008 is a false positive here.
+extend-immutable-calls = ["typer.Option", "typer.Argument"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = [
+    "--cov=amie",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=90",
+]
+
+[tool.coverage.run]
+source = ["src/amie"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pip-audit>=2.7",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.12",
+]

amie-0.1.0/src/amie/__init__.py

@@ -0,0 +1,3 @@
+"""AMI — Anonymous Memory Intelligence."""
+
+__version__ = "0.0.1"

amie-0.1.0/src/amie/cli.py

@@ -0,0 +1,410 @@
+"""Typer CLI entry point for AMI.
+
+This module is deliberately thin — it only wires Typer to domain modules.
+All logic lives in `amie.dev`, `amie.vault`, `ami.doctor`, `amie.init`,
+`amie.security`. The CLI's job is two things:
+
+1. Wire Typer subcommands to the domain.
+2. Translate domain exceptions into friendly messages with exact next steps.
+
+CLI tests exercise real subprocess and real filesystem; no internal mocking.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+
+import typer
+from dotenv import load_dotenv
+
+from amie import dev, security, vault
+from amie.config import Config, ConfigError, user_config_path
+from amie.doctor import CheckResult, run_all_checks
+from amie.init import InitOutcome, SshSetupResult, run_init, setup_ssh_server
+
+# Load `.env` from the working directory at CLI startup. Domain modules read
+# only `os.environ`; this is the one place we touch the file system for env.
+load_dotenv(override=False)
+
+app = typer.Typer(help="AMI — Anonymous Memory Intelligence")
+dev_app = typer.Typer(help="Developer tooling: tests, lint, format, sync.")
+vault_app = typer.Typer(help="Manage AMI's folders inside the Obsidian vault.")
+app.add_typer(dev_app, name="dev")
+app.add_typer(vault_app, name="vault")
+
+
+# ---------------------------------------------------------------------------
+# Friendly error wrapper
+# ---------------------------------------------------------------------------
+
+
+def friendly(func: Callable[..., None]) -> Callable[..., None]:
+    """Decorator: catch domain exceptions and print plain-English messages.
+
+    Domain code is allowed to be strict (raise). The CLI translates every
+    expected exception into a clear, actionable message for the user. Stack
+    traces only appear if AMIE_DEBUG=1 is set.
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except ConfigError as err:
+            typer.echo("\n  Hold on — AMI hasn't been set up yet on this machine.\n", err=True)
+            typer.echo(f"  Reason: {err}\n", err=True)
+            typer.echo("  Run this once to fix it:", err=True)
+            typer.echo("\n      amie init\n", err=True)
+            raise typer.Exit(code=1) from err
+        except FileNotFoundError as err:
+            typer.echo("\n  Couldn't find a file or folder AMI needs:\n", err=True)
+            typer.echo(f"  {err}\n", err=True)
+            typer.echo("  Try `amie doctor` to see what's missing.\n", err=True)
+            raise typer.Exit(code=1) from err
+
+    return wrapper
+
+
+# ---------------------------------------------------------------------------
+# Top-level commands
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def install(
+    vault_path: Path | None = typer.Option(
+        None,
+        "--vault-path",
+        help="Path to your Obsidian vault. If omitted you'll be asked.",
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Accept all defaults; create the vault if missing."
+    ),
+) -> None:
+    """Bootstrap AMI on this machine: install the binary and run first-time setup."""
+    import subprocess
+
+    project_root = Path(__file__).resolve().parent.parent.parent
+    rc = subprocess.run(
+        ["uv", "tool", "install", "--editable", str(project_root)],
+        check=False,
+    ).returncode
+    if rc != 0:
+        typer.echo(
+            "\n  Binary install failed. Make sure uv is on PATH, then run:\n"
+            f"\n      uv tool install --editable {project_root}\n",
+            err=True,
+        )
+        raise typer.Exit(code=rc)
+
+    typer.echo("\n  Binary installed. Running first-time setup...\n")
+    init(vault_path=vault_path, yes=yes)
+
+
+@app.command()
+def init(
+    vault_path: Path | None = typer.Option(
+        None,
+        "--vault-path",
+        help="Path to your Obsidian vault. If omitted you'll be asked.",
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Accept all defaults; create the vault if missing."
+    ),
+) -> None:
+    """Set up AMI on this machine: write the config file and create inbox folders."""
+    chosen_path = _ask_for_vault_path(vault_path)
+    create_if_missing = _ask_to_create_vault(chosen_path, auto_yes=yes)
+
+    try:
+        outcome = run_init(
+            vault_path=chosen_path,
+            config_path=user_config_path(),
+            create_vault_if_missing=create_if_missing,
+        )
+    except FileNotFoundError:
+        typer.echo("\n  Cancelled — your vault wasn't created.", err=True)
+        typer.echo(
+            f"  When you're ready, run `amie init` again or create {chosen_path} manually.\n",
+            err=True,
+        )
+        raise typer.Exit(code=1) from None
+
+    ssh = setup_ssh_server(sshd_drop_in=Config.sshd_drop_in_from_env())
+    _display_init_outcome(outcome, ssh)
+
+
+@app.command()
+@friendly
+def watch() -> None:
+    """Watch the inbox folders and normalize incoming notes."""
+    import signal
+
+    from amie.watcher import Watcher
+
+    cfg = Config.from_env()
+    _scaffold_with_notice(cfg)
+    watcher = Watcher(cfg)
+
+    def _stop(signum, frame):
+        watcher.stop()
+
+    signal.signal(signal.SIGINT, _stop)
+    signal.signal(signal.SIGTERM, _stop)
+
+    watcher.start()
+    watcher._observer.join()
+
+
+@app.command()
+@friendly
+def digest() -> None:
+    """Generate the weekly digest."""
+    cfg = Config.from_env()
+    _scaffold_with_notice(cfg)
+    typer.echo("digest: not yet implemented (see docs/amie/11-weekly-digest.md)")
+
+
+@app.command()
+@friendly
+def ocr(path: str) -> None:
+    """Run OCR on a single image and print the transcript."""
+    cfg = Config.from_env()
+    _scaffold_with_notice(cfg)
+    typer.echo(f"ocr {path}: not yet implemented (see docs/amie/09-photo-ocr.md)")
+
+
+@app.command()
+@friendly
+def doctor() -> None:
+    """Run all health checks and report status."""
+    cfg = Config.from_env()
+    results: list[CheckResult] = run_all_checks(cfg)
+    for result in results:
+        marker = "OK" if result.ok else "FAIL"
+        typer.echo(f"  [{marker}] {result.name}: {result.message}")
+    if any(not r.ok for r in results):
+        raise typer.Exit(code=1)
+
+
+# ---------------------------------------------------------------------------
+# dev sub-app
+# ---------------------------------------------------------------------------
+
+
+@dev_app.command("test")
+def dev_test(no_cov: bool = typer.Option(False, "--no-cov", help="Skip coverage gate.")) -> None:
+    """Run the test suite under uv. Coverage gate is enforced by default."""
+    rc = dev.run(dev.build_test_command(no_cov=no_cov))
+    raise typer.Exit(code=rc)
+
+
+@dev_app.command("lint")
+def dev_lint(fix: bool = typer.Option(False, "--fix", help="Auto-fix lint issues.")) -> None:
+    """Run ruff check across the project."""
+    rc = dev.run(dev.build_lint_command(fix=fix))
+    raise typer.Exit(code=rc)
+
+
+@dev_app.command("fmt")
+def dev_fmt() -> None:
+    """Format the codebase with ruff."""
+    rc = dev.run(dev.build_fmt_command())
+    raise typer.Exit(code=rc)
+
+
+@dev_app.command("sync")
+def dev_sync() -> None:
+    """Sync project dependencies (uv sync)."""
+    rc = dev.run(dev.build_sync_command())
+    raise typer.Exit(code=rc)
+
+
+@dev_app.command("guard")
+def dev_guard(
+    skip_audit: bool = typer.Option(
+        False,
+        "--skip-audit",
+        help="Skip the security-audit step (which makes a network call). Use for fast iteration.",
+    ),
+) -> None:
+    """Run lint + format-check + tests-with-coverage + security audit + docs check.
+
+    Run before AND after every code change. With `--skip-audit`, the network
+    call is skipped — useful for tight inner loops, but full guard must pass
+    before declaring work done.
+
+    The docs-check step runs automatically when AMIE_DOCS_PATH is set.
+    """
+    results = dev.run_guards(skip_audit=skip_audit, docs_dir=Config.docs_path_from_env())
+    for result in results:
+        marker = "OK" if result.passed else "FAIL"
+        typer.echo(f"  [{marker}] {result.name}")
+    if results and not results[-1].passed:
+        raise typer.Exit(code=results[-1].exit_code)
+
+
+@dev_app.command("audit")
+def dev_audit() -> None:
+    """Run a security audit on the project's dependencies (pip-audit)."""
+    rc = dev.run(security.build_audit_command())
+    raise typer.Exit(code=rc)
+
+
+@dev_app.command("docs")
+@friendly
+def dev_docs(
+    docs_dir: str = typer.Option(
+        "",
+        "--docs-dir",
+        help="Path to the docs folder. Defaults to AMIE_DOCS_PATH env var.",
+    ),
+) -> None:
+    """Check that the docs folder is not stale.
+
+    Verifies that vault-structure.md mentions every top-level vault section
+    and that 14-cli-reference.md mentions every CLI command. Exits non-zero
+    and lists gaps if anything is out of date.
+
+    Set AMIE_DOCS_PATH in your .env or environment to run this automatically
+    as part of `amie dev guard`.
+    """
+    from amie.docs import run_docs_check
+    from amie.vault import VAULT_SKELETON
+
+    resolved = Path(docs_dir) if docs_dir else Config.docs_path_from_env()
+    if resolved is None:
+        typer.echo(
+            "  docs check skipped — set AMIE_DOCS_PATH to enable.\n"
+            "  Example: AMIE_DOCS_PATH=~/source/ubuntu/docs/amie"
+        )
+        return
+
+    commands = _collect_all_commands()
+    issues = run_docs_check(resolved, skeleton=VAULT_SKELETON, commands=commands)
+
+    if not issues:
+        typer.echo(f"  OK — docs are current ({resolved})")
+        return
+
+    typer.echo(f"  FAIL — {len(issues)} doc gap(s) found:\n", err=True)
+    for issue in issues:
+        typer.echo(f"    [{issue.doc}] {issue.missing}", err=True)
+    raise typer.Exit(code=1)
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _display_init_outcome(
+    outcome: InitOutcome,
+    ssh: SshSetupResult,
+    *,
+    file: object = None,
+) -> None:
+    vault_state = "created" if outcome.vault_created else "already existed"
+    sshd_state = "installed" if ssh.sshd_was_installed else "already present"
+    user_state = "created" if ssh.user_was_created else "already present"
+    kwargs = {"file": file} if file is not None else {}
+    typer.echo("", **kwargs)
+    typer.echo("  All set!", **kwargs)
+    typer.echo(f"    config:        {outcome.config_path}", **kwargs)
+    typer.echo(f"    vault:         {outcome.vault_path} ({vault_state})", **kwargs)
+    typer.echo(f"    vault folders: {outcome.folders_created} created or verified", **kwargs)
+    typer.echo(f"    openssh-server: {sshd_state}", **kwargs)
+    typer.echo(f"    amie-sync user:  {user_state}", **kwargs)
+    typer.echo("\n  Next: run `amie doctor` to confirm Ollama and SSH are ready.\n", **kwargs)
+
+
+def _scaffold_with_notice(cfg: Config) -> None:
+    """Create any missing vault folders, printing a notice if any were added."""
+    created = vault.scaffold_vault(cfg)
+    if created:
+        typer.echo(
+            f"Notice: created {len(created)} missing vault folder(s)"
+            " — run `amie vault status` for details."
+        )
+
+
+def _collect_all_commands() -> list[str]:
+    """Return every CLI command name as it appears in the reference doc."""
+
+    def _name(cmd_info) -> str:
+        if cmd_info.name:
+            return cmd_info.name
+        if cmd_info.callback:
+            return cmd_info.callback.__name__.replace("_", "-")
+        return ""
+
+    commands = [f"amie {_name(c)}" for c in app.registered_commands if _name(c)]
+    commands += [f"amie dev {_name(c)}" for c in dev_app.registered_commands if _name(c)]
+    commands += [f"amie vault {_name(c)}" for c in vault_app.registered_commands if _name(c)]
+    return [c for c in commands if c.strip()]
+
+
+# ---------------------------------------------------------------------------
+# vault sub-app
+# ---------------------------------------------------------------------------
+
+
+@vault_app.command("init")
+@friendly
+def vault_init() -> None:
+    """Create the full vault folder structure inside the Obsidian vault."""
+    cfg = Config.from_env()
+    created = vault.scaffold_vault(cfg)
+    if created:
+        typer.echo(f"OK — created {len(created)} folders under {cfg.vault_path}")
+    else:
+        typer.echo(f"OK — all vault folders already present under {cfg.vault_path}")
+
+
+@vault_app.command("status")
+@friendly
+def vault_status_cmd() -> None:
+    """Report whether AMI's folders exist inside the vault."""
+    cfg = Config.from_env()
+    status = vault.vault_status(cfg)
+    if not status.vault_exists:
+        typer.echo(f"vault: not ready — root missing at {cfg.vault_path}")
+        raise typer.Exit(code=1)
+    if status.missing:
+        names = "\n  - ".join(p.relative_to(cfg.vault_path).as_posix() for p in status.missing)
+        typer.echo(f"vault: not ready — missing dirs:\n  - {names}")
+        raise typer.Exit(code=1)
+    typer.echo(f"vault: ready — all inbox directories present at {cfg.vault_path}")
+
+
+# ---------------------------------------------------------------------------
+# Private helpers (CLI-side prompts)
+# ---------------------------------------------------------------------------
+
+
+def _ask_for_vault_path(provided: Path | None) -> Path:
+    """If the user supplied --vault-path, use it. Otherwise prompt with a default."""
+    if provided is not None:
+        return provided
+    default = Path.home() / "Obsidian"
+    answer: str = typer.prompt(
+        "Where is (or should be) your Obsidian vault?",
+        default=str(default),
+    )
+    return Path(answer).expanduser()
+
+
+def _ask_to_create_vault(vault_path: Path, *, auto_yes: bool) -> bool:
+    """If the vault doesn't exist, ask whether to create it. Default yes."""
+    if vault_path.expanduser().is_dir():
+        return False
+    if auto_yes:
+        return True
+    return typer.confirm(f"  {vault_path} doesn't exist yet. Create it now?", default=True)
+
+
+if __name__ == "__main__":
+    sys.exit(app())