ventilatepro-cli 0.1.0__tar.gz

ventilatepro_cli-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: ventilatepro-cli
+Version: 0.1.0
+Summary: VentilatePro CLI
+Project-URL: Homepage, https://ventilatepro.com/exam/cli/
+Project-URL: Documentation, https://ventilatepro.com/exam/cli/
+Project-URL: Support, https://ventilatepro.com/exam/support/
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.16.0
+Requires-Dist: requests>=2.32.0
+Requires-Dist: keyring>=25.6.0
+Requires-Dist: platformdirs>=4.3.0
+
+# VentilatePro CLI
+
+VentilatePro CLI is a local command-line client for authenticating to VentilatePro and creating or syncing notes through the scoped CLI API.
+
+## Install
+
+Published releases install from PyPI:
+
+```bash
+pipx install ventilatepro-cli
+```
+
+Upgrade an existing install:
+
+```bash
+pipx upgrade ventilatepro-cli
+```
+
+Local development install:
+
+```bash
+cd ventilatepro-cli
+pip install -e .
+```
+
+## Commands
+
+```bash
+ventilatepro auth login --url http://localhost:8000
+ventilatepro projects list
+ventilatepro notes create --project 1 --body "Captured from terminal"
+ventilatepro notes sync
+```
+
+See the hosted install guide at `https://ventilatepro.com/exam/cli/`, plus [docs/commands.md](./docs/commands.md), [docs/auth.md](./docs/auth.md), [docs/api.md](./docs/api.md), and [docs/releasing.md](./docs/releasing.md) in this repo.

ventilatepro_cli-0.1.0/README.md

@@ -0,0 +1,35 @@
+# VentilatePro CLI
+
+VentilatePro CLI is a local command-line client for authenticating to VentilatePro and creating or syncing notes through the scoped CLI API.
+
+## Install
+
+Published releases install from PyPI:
+
+```bash
+pipx install ventilatepro-cli
+```
+
+Upgrade an existing install:
+
+```bash
+pipx upgrade ventilatepro-cli
+```
+
+Local development install:
+
+```bash
+cd ventilatepro-cli
+pip install -e .
+```
+
+## Commands
+
+```bash
+ventilatepro auth login --url http://localhost:8000
+ventilatepro projects list
+ventilatepro notes create --project 1 --body "Captured from terminal"
+ventilatepro notes sync
+```
+
+See the hosted install guide at `https://ventilatepro.com/exam/cli/`, plus [docs/commands.md](./docs/commands.md), [docs/auth.md](./docs/auth.md), [docs/api.md](./docs/api.md), and [docs/releasing.md](./docs/releasing.md) in this repo.

ventilatepro_cli-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ventilatepro-cli"
+dynamic = ["version"]
+description = "VentilatePro CLI"
+requires-python = ">=3.9"
+readme = "README.md"
+dependencies = [
+  "typer>=0.16.0",
+  "requests>=2.32.0",
+  "keyring>=25.6.0",
+  "platformdirs>=4.3.0",
+]
+
+[project.urls]
+Homepage = "https://ventilatepro.com/exam/cli/"
+Documentation = "https://ventilatepro.com/exam/cli/"
+Support = "https://ventilatepro.com/exam/support/"
+
+[project.scripts]
+ventilatepro = "ventilatepro.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["ventilatepro*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "ventilatepro.__version__"}

ventilatepro_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ventilatepro_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,171 @@
+import json
+import os
+import tempfile
+import unittest
+from unittest import mock
+
+from typer.testing import CliRunner
+
+from ventilatepro import auth, config
+from ventilatepro.api_client import ApiError, NetworkError
+from ventilatepro.cli import app
+from ventilatepro.queue import QueueStore
+
+
+class CliTests(unittest.TestCase):
+    def setUp(self):
+        self.runner = CliRunner()
+
+    def test_status_json_reports_not_authenticated(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            os.environ[config.CONFIG_ENV_VAR] = tmpdir
+            os.environ[config.DATA_ENV_VAR] = tmpdir
+            try:
+                result = self.runner.invoke(app, ["auth", "status", "--json"])
+                self.assertEqual(result.exit_code, 0)
+                payload = json.loads(result.stdout)
+                self.assertFalse(payload["authenticated"])
+            finally:
+                os.environ.pop(config.CONFIG_ENV_VAR, None)
+                os.environ.pop(config.DATA_ENV_VAR, None)
+
+    def test_notes_create_queues_on_network_error(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            os.environ[config.CONFIG_ENV_VAR] = tmpdir
+            os.environ[config.DATA_ENV_VAR] = tmpdir
+            try:
+                config.set_base_url("http://localhost:8000")
+                with mock.patch.object(config, "_try_get_keyring", return_value=None):
+                    config.save_token("vpcli_demo_secret")
+
+                fake_client = mock.Mock()
+                fake_client.create_note.side_effect = NetworkError("connection dropped")
+
+                with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+                    result = self.runner.invoke(
+                        app,
+                        ["notes", "create", "--project", "1", "--body", "Captured from CLI"],
+                    )
+
+                self.assertEqual(result.exit_code, 0)
+                queue_store = QueueStore()
+                queued = queue_store.list_unsynced()
+                self.assertEqual(len(queued), 1)
+                self.assertEqual(queued[0].sync_state, "pending")
+            finally:
+                os.environ.pop(config.CONFIG_ENV_VAR, None)
+                os.environ.pop(config.DATA_ENV_VAR, None)
+
+    def test_notes_create_does_not_queue_validation_errors(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            os.environ[config.CONFIG_ENV_VAR] = tmpdir
+            os.environ[config.DATA_ENV_VAR] = tmpdir
+            try:
+                config.set_base_url("http://localhost:8000")
+                with mock.patch.object(config, "_try_get_keyring", return_value=None):
+                    config.save_token("vpcli_demo_secret")
+
+                fake_client = mock.Mock()
+                fake_client.create_note.side_effect = ApiError(400, "Validation failed")
+
+                with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+                    result = self.runner.invoke(
+                        app,
+                        ["notes", "create", "--project", "1", "--body", "Captured from CLI"],
+                    )
+
+                self.assertNotEqual(result.exit_code, 0)
+                queue_store = QueueStore()
+                self.assertEqual(queue_store.count(), 0)
+            finally:
+                os.environ.pop(config.CONFIG_ENV_VAR, None)
+                os.environ.pop(config.DATA_ENV_VAR, None)
+
+    def test_notes_create_derives_title_from_first_non_empty_body_line(self):
+        fake_client = mock.Mock()
+        fake_client.create_note.return_value = {
+            "note": {"note_ref": "general-info:1"},
+            "audit_entry_id": 12,
+        }
+
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(
+                app,
+                ["notes", "create", "--project", "1", "--body", "\n\n  First captured line  \nSecond line"],
+            )
+
+        self.assertEqual(result.exit_code, 0)
+        payload = fake_client.create_note.call_args.args[0]
+        self.assertEqual(payload["title"], "First captured line")
+        self.assertEqual(payload["body"], "\n\n  First captured line  \nSecond line")
+
+    def test_notes_sync_retries_queued_notes_and_marks_them_synced(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            os.environ[config.CONFIG_ENV_VAR] = tmpdir
+            os.environ[config.DATA_ENV_VAR] = tmpdir
+            try:
+                queue_store = QueueStore()
+                queued = queue_store.enqueue(
+                    project_id=1,
+                    title="Queued note",
+                    body="Queued body",
+                    tags=["cli"],
+                    captured_at="2026-03-10T10:00:00-07:00",
+                    idempotency_key="queued-note-1",
+                )
+
+                fake_client = mock.Mock()
+                fake_client.create_note.return_value = {
+                    "note": {"note_ref": "general-info:99"},
+                    "audit_entry_id": 25,
+                }
+
+                with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+                    result = self.runner.invoke(app, ["notes", "sync", "--project", "1", "--json"])
+
+                self.assertEqual(result.exit_code, 0)
+                payload = json.loads(result.stdout)
+                self.assertEqual(payload["total"], 1)
+                self.assertEqual(payload["synced"], 1)
+                self.assertEqual(payload["failed"], 0)
+                self.assertEqual(payload["results"][0]["note_ref"], "general-info:99")
+
+                synced = queue_store.get(queued.local_id)
+                self.assertEqual(synced.sync_state, "synced")
+                self.assertEqual(synced.server_note_ref, "general-info:99")
+                fake_client.create_note.assert_called_once_with(
+                    {
+                        "project": 1,
+                        "title": "Queued note",
+                        "body": "Queued body",
+                        "tags": ["cli"],
+                        "captured_at": "2026-03-10T10:00:00-07:00",
+                    },
+                    idempotency_key="queued-note-1",
+                )
+            finally:
+                os.environ.pop(config.CONFIG_ENV_VAR, None)
+                os.environ.pop(config.DATA_ENV_VAR, None)
+
+    def test_notes_list_json_outputs_server_payload(self):
+        fake_client = mock.Mock()
+        fake_client.list_notes.return_value = {
+            "project_id": 1,
+            "count": 1,
+            "limit": 20,
+            "offset": 0,
+            "results": [
+                {
+                    "note_ref": "general-info:1",
+                    "title": "CLI Note",
+                    "type": "general-info",
+                    "source": "cli",
+                }
+            ],
+        }
+        with mock.patch.object(auth, "get_authenticated_client", return_value=(fake_client, "http://localhost:8000")):
+            result = self.runner.invoke(app, ["notes", "list", "--project", "1", "--json"])
+
+        self.assertEqual(result.exit_code, 0)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["results"][0]["note_ref"], "general-info:1")

ventilatepro_cli-0.1.0/tests/test_config.py

@@ -0,0 +1,24 @@
+import json
+import os
+import tempfile
+import unittest
+from unittest import mock
+
+from ventilatepro import config
+
+
+class ConfigTests(unittest.TestCase):
+    def test_token_falls_back_to_file_storage_when_keyring_is_unavailable(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            os.environ[config.CONFIG_ENV_VAR] = tmpdir
+            os.environ[config.DATA_ENV_VAR] = tmpdir
+            try:
+                with mock.patch.object(config, "_try_get_keyring", return_value=None):
+                    storage = config.save_token("vpcli_demo_secret")
+                self.assertEqual(storage, "file")
+                self.assertEqual(config.get_token(), "vpcli_demo_secret")
+                payload = json.loads(config.get_config_path().read_text(encoding="utf-8"))
+                self.assertEqual(payload["token_storage"], "file")
+            finally:
+                os.environ.pop(config.CONFIG_ENV_VAR, None)
+                os.environ.pop(config.DATA_ENV_VAR, None)

ventilatepro_cli-0.1.0/ventilatepro/__init__.py

@@ -0,0 +1,5 @@
+"""VentilatePro CLI package metadata."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

ventilatepro_cli-0.1.0/ventilatepro/__main__.py

@@ -0,0 +1,5 @@
+from .cli import app
+
+
+if __name__ == "__main__":
+    app()

ventilatepro_cli-0.1.0/ventilatepro/api_client.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+
+class ApiError(Exception):
+    def __init__(self, status_code: int, message: str, payload: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+class NetworkError(Exception):
+    pass
+
+
+def extract_error_message(payload: Any, fallback: str) -> str:
+    if isinstance(payload, dict):
+        if isinstance(payload.get("detail"), str):
+            return payload["detail"]
+        error = payload.get("error")
+        if isinstance(error, dict) and isinstance(error.get("message"), str):
+            return error["message"]
+        return " ".join(str(value) for value in payload.values() if value)
+    if isinstance(payload, str) and payload.strip():
+        return payload
+    return fallback
+
+
+class ApiClient:
+    def __init__(self, base_url: str, token: Optional[str] = None, timeout: int = 15):
+        self.base_url = (base_url or "").rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    def request(self, method: str, path: str, *, json_payload: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None):
+        final_headers = {
+            "Accept": "application/json",
+        }
+        if headers:
+            final_headers.update(headers)
+        if self.token:
+            final_headers["Authorization"] = f"Bearer {self.token}"
+        try:
+            response = requests.request(
+                method=method,
+                url=f"{self.base_url}{path}",
+                json=json_payload,
+                headers=final_headers,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise NetworkError(str(exc)) from exc
+
+        payload: Any = None
+        if response.content:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = response.text
+
+        if not response.ok:
+            raise ApiError(
+                status_code=response.status_code,
+                message=extract_error_message(payload, f"Request failed with status {response.status_code}."),
+                payload=payload,
+            )
+        return payload if payload is not None else {}
+
+    def auth_me(self):
+        return self.request("GET", "/api/cli/auth/me/")
+
+    def projects_list(self):
+        return self.request("GET", "/api/cli/projects/")
+
+    def create_note(self, payload: Dict[str, Any], *, idempotency_key: str):
+        return self.request(
+            "POST",
+            "/api/cli/notes/",
+            json_payload=payload,
+            headers={"Idempotency-Key": idempotency_key},
+        )
+
+    def list_notes(self, project: int, *, limit: int = 20, offset: int = 0):
+        return self.request("GET", f"/api/cli/notes/?project={project}&limit={limit}&offset={offset}")
+
+    def show_note(self, note_ref: str, *, project: int):
+        return self.request("GET", f"/api/cli/notes/{note_ref}/?project={project}")

ventilatepro_cli-0.1.0/ventilatepro/auth.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from getpass import getpass
+from typing import Tuple
+
+from .api_client import ApiClient
+from .config import clear_auth, get_base_url, get_token, save_token, set_base_url
+
+
+def login(base_url: str | None, token: str | None):
+    normalized_url = (base_url or get_base_url() or "").strip().rstrip("/")
+    if not normalized_url:
+        raise ValueError("API base URL is required. Pass --url or log in with a saved URL.")
+
+    resolved_token = token or getpass("Personal access token: ").strip()
+    if not resolved_token:
+        raise ValueError("Personal access token is required.")
+
+    client = ApiClient(normalized_url, resolved_token)
+    identity = client.auth_me()
+    token_storage = save_token(resolved_token)
+    set_base_url(normalized_url)
+    return {
+        "status": "authenticated",
+        "base_url": normalized_url,
+        "token_storage": token_storage,
+        "user": identity,
+    }
+
+
+def status():
+    base_url = get_base_url()
+    token = get_token()
+    return {
+        "authenticated": bool(base_url and token),
+        "base_url": base_url,
+        "token_present": bool(token),
+    }
+
+
+def get_authenticated_client() -> Tuple[ApiClient, str]:
+    base_url = get_base_url()
+    token = get_token()
+    if not base_url or not token:
+        raise ValueError("Not authenticated. Run `ventilatepro auth login` first.")
+    return ApiClient(base_url, token), base_url
+
+
+def whoami():
+    client, _ = get_authenticated_client()
+    return client.auth_me()
+
+
+def logout():
+    clear_auth()
+    return {"status": "logged_out"}

ventilatepro_cli-0.1.0/ventilatepro/cli.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import json
+
+import typer
+
+from . import auth, notes
+from .api_client import ApiError, NetworkError
+from .queue import QueueStore
+
+app = typer.Typer(help="VentilatePro CLI")
+auth_app = typer.Typer(help="Authentication commands")
+projects_app = typer.Typer(help="Project commands")
+notes_app = typer.Typer(help="Notes commands")
+
+app.add_typer(auth_app, name="auth")
+app.add_typer(projects_app, name="projects")
+app.add_typer(notes_app, name="notes")
+
+
+def main():
+    app()
+
+
+def emit(payload, *, json_output: bool, lines: list[str]):
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, default=str))
+        return
+    for line in lines:
+        typer.echo(line)
+
+
+def emit_error(message: str, *, json_output: bool):
+    if json_output:
+        typer.echo(json.dumps({"error": message}))
+    else:
+        typer.echo(f"Error: {message}", err=True)
+
+
+@auth_app.command("login")
+def auth_login(
+    url: str = typer.Option(None, "--url", help="VentilatePro base URL"),
+    token: str = typer.Option(None, "--token", help="Personal access token"),
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    try:
+        result = auth.login(url, token)
+    except (ValueError, ApiError, NetworkError) as exc:
+        emit_error(str(exc), json_output=json_output)
+        raise typer.Exit(1)
+    emit(
+        result,
+        json_output=json_output,
+        lines=[
+            f"Authenticated as {result['user'].get('name') or result['user'].get('username')}.",
+            f"Base URL: {result['base_url']}",
+            f"Token storage: {result['token_storage']}",
+        ],
+    )
+
+
+@auth_app.command("status")
+def auth_status(
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    result = auth.status()
+    lines = ["Authenticated." if result["authenticated"] else "Not authenticated."]
+    if result.get("base_url"):
+        lines.append(f"Base URL: {result['base_url']}")
+    emit(result, json_output=json_output, lines=lines)
+
+
+@auth_app.command("whoami")
+def auth_whoami(
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    try:
+        result = auth.whoami()
+    except (ValueError, ApiError, NetworkError) as exc:
+        emit_error(str(exc), json_output=json_output)
+        raise typer.Exit(1)
+    emit(
+        result,
+        json_output=json_output,
+        lines=[
+            f"User: {result.get('name') or result.get('username')}",
+            f"Email: {result.get('email')}",
+        ],
+    )
+
+
+@auth_app.command("logout")
+def auth_logout(
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    result = auth.logout()
+    emit(result, json_output=json_output, lines=["Removed local credentials."])
+
+
+@projects_app.command("list")
+def projects_list(
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    try:
+        client, _ = auth.get_authenticated_client()
+        result = client.projects_list()
+    except (ValueError, ApiError, NetworkError) as exc:
+        emit_error(str(exc), json_output=json_output)
+        raise typer.Exit(1)
+
+    lines = [f"{project['id']}\t{project['name']}" for project in result]
+    if not lines:
+        lines = ["No accessible projects found."]
+    emit(result, json_output=json_output, lines=lines)
+
+
+@notes_app.command("create")
+def notes_create(
+    project: int = typer.Option(..., "--project", help="Target project ID"),
+    title: str = typer.Option(None, "--title", help="Note title"),
+    body: str = typer.Option(None, "--body", help="Note body"),
+    use_stdin: bool = typer.Option(False, "--stdin", help="Read note body from stdin"),
+    tags: str = typer.Option(None, "--tags", help="Comma-separated tags"),
+    captured_at: str = typer.Option(None, "--captured-at", help="Capture timestamp in ISO-8601 format"),
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    try:
+        client, _ = auth.get_authenticated_client()
+        queue_store = QueueStore()
+        body_text = notes.resolve_body(body, use_stdin)
+        result = notes.create_note(
+            client,
+            queue_store,
+            project=project,
+            title=title,
+            body=body_text,
+            tags=notes.parse_tags(tags),
+            captured_at=captured_at,
+        )
+    except (ValueError, ApiError, NetworkError) as exc:
+        emit_error(str(exc), json_output=json_output)
+        raise typer.Exit(1)
+
+    if result["status"] == "queued":
+        emit(
+            result,
+            json_output=json_output,
+            lines=[f"Queued note locally as #{result['local_id']} due to a retryable API failure."],
+        )
+        return
+
+    note_ref = (result.get("note") or {}).get("note_ref", "unknown")
+    emit(
+        result,
+        json_output=json_output,
+        lines=[f"Created note {note_ref} in project {project}."],
+    )
+
+
+@notes_app.command("sync")
+def notes_sync(
+    project: int = typer.Option(None, "--project", help="Only sync queued notes for this project"),
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    try:
+        client, _ = auth.get_authenticated_client()
+        result = notes.sync_notes(client, QueueStore(), project=project)
+    except (ValueError, ApiError, NetworkError) as exc:
+        emit_error(str(exc), json_output=json_output)
+        raise typer.Exit(1)
+
+    emit(
+        result,
+        json_output=json_output,
+        lines=[f"Processed {result['total']} queued notes: {result['synced']} synced, {result['failed']} failed."],
+    )
+    if result["failed"] > 0:
+        raise typer.Exit(1)
+
+
+@notes_app.command("list")
+def notes_list(
+    project: int = typer.Option(..., "--project", help="Target project ID"),
+    limit: int = typer.Option(20, "--limit", help="Maximum notes to return"),
+    offset: int = typer.Option(0, "--offset", help="Starting offset"),
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    try:
+        client, _ = auth.get_authenticated_client()
+        result = client.list_notes(project, limit=limit, offset=offset)
+    except (ValueError, ApiError, NetworkError) as exc:
+        emit_error(str(exc), json_output=json_output)
+        raise typer.Exit(1)
+
+    lines = [
+        f"{item['note_ref']}\t{item['title']}\t{item['type']}\t{item['source']}"
+        for item in result.get("results", [])
+    ]
+    if not lines:
+        lines = ["No notes found."]
+    emit(result, json_output=json_output, lines=lines)
+
+
+@notes_app.command("show")
+def notes_show(
+    note_ref: str = typer.Argument(..., help="Typed note reference, such as general-info:42"),
+    project: int = typer.Option(..., "--project", help="Target project ID"),
+    json_output: bool = typer.Option(False, "--json", help="Return JSON output"),
+):
+    try:
+        client, _ = auth.get_authenticated_client()
+        result = client.show_note(note_ref, project=project)
+    except (ValueError, ApiError, NetworkError) as exc:
+        emit_error(str(exc), json_output=json_output)
+        raise typer.Exit(1)
+
+    emit(
+        result,
+        json_output=json_output,
+        lines=[
+            f"{result['note_ref']} [{result['type']}]",
+            f"Title: {result['title']}",
+            f"Source: {result['source']}",
+            f"Tags: {', '.join(result.get('tags') or []) or 'None'}",
+            "",
+            result["body"],
+        ],
+    )

ventilatepro_cli-0.1.0/ventilatepro/config.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+APP_DIR_NAME = "ventilatepro"
+CONFIG_ENV_VAR = "VENTILATEPRO_CONFIG_DIR"
+DATA_ENV_VAR = "VENTILATEPRO_DATA_DIR"
+CONFIG_FILENAME = "config.json"
+KEYRING_SERVICE = "ventilatepro-cli"
+KEYRING_USERNAME = "default"
+
+
+def _fallback_config_dir() -> Path:
+    return Path.home() / ".config" / APP_DIR_NAME
+
+
+def _fallback_data_dir() -> Path:
+    return Path.home() / ".local" / "share" / APP_DIR_NAME
+
+
+def get_config_dir() -> Path:
+    override = os.getenv(CONFIG_ENV_VAR)
+    if override:
+        return Path(override)
+    try:
+        from platformdirs import user_config_dir
+
+        return Path(user_config_dir(APP_DIR_NAME, "VentilatePro"))
+    except Exception:
+        return _fallback_config_dir()
+
+
+def get_data_dir() -> Path:
+    override = os.getenv(DATA_ENV_VAR)
+    if override:
+        return Path(override)
+    try:
+        from platformdirs import user_data_dir
+
+        return Path(user_data_dir(APP_DIR_NAME, "VentilatePro"))
+    except Exception:
+        return _fallback_data_dir()
+
+
+def get_config_path() -> Path:
+    return get_config_dir() / CONFIG_FILENAME
+
+
+def ensure_dirs() -> None:
+    get_config_dir().mkdir(parents=True, exist_ok=True)
+    get_data_dir().mkdir(parents=True, exist_ok=True)
+
+
+def load_settings() -> Dict[str, Any]:
+    path = get_config_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def save_settings(settings: Dict[str, Any]) -> None:
+    ensure_dirs()
+    get_config_path().write_text(json.dumps(settings, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def normalize_base_url(base_url: str) -> str:
+    return (base_url or "").strip().rstrip("/")
+
+
+def set_base_url(base_url: str) -> None:
+    settings = load_settings()
+    settings["base_url"] = normalize_base_url(base_url)
+    save_settings(settings)
+
+
+def get_base_url() -> Optional[str]:
+    return normalize_base_url(load_settings().get("base_url", "")) or None
+
+
+def _try_get_keyring():
+    try:
+        import keyring
+
+        return keyring
+    except Exception:
+        return None
+
+
+def save_token(token: str) -> str:
+    settings = load_settings()
+    keyring = _try_get_keyring()
+    if keyring is not None:
+        try:
+            keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, token)
+            settings["token_storage"] = "keyring"
+            settings.pop("token", None)
+            save_settings(settings)
+            return "keyring"
+        except Exception:
+            pass
+
+    settings["token_storage"] = "file"
+    settings["token"] = token
+    save_settings(settings)
+    return "file"
+
+
+def get_token() -> Optional[str]:
+    settings = load_settings()
+    storage = settings.get("token_storage")
+    if storage == "keyring":
+        keyring = _try_get_keyring()
+        if keyring is not None:
+            try:
+                token = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME)
+                if token:
+                    return token
+            except Exception:
+                pass
+    return settings.get("token") or None
+
+
+def delete_token() -> None:
+    settings = load_settings()
+    keyring = _try_get_keyring()
+    if keyring is not None:
+        try:
+            keyring.delete_password(KEYRING_SERVICE, KEYRING_USERNAME)
+        except Exception:
+            pass
+    settings.pop("token", None)
+    settings.pop("token_storage", None)
+    save_settings(settings)
+
+
+def clear_auth() -> None:
+    settings = load_settings()
+    settings.pop("base_url", None)
+    settings.pop("token", None)
+    settings.pop("token_storage", None)
+    delete_token()
+    save_settings(settings)

ventilatepro_cli-0.1.0/ventilatepro/notes.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import sys
+import uuid
+from typing import Optional
+
+from .api_client import ApiError, NetworkError
+from .queue import QueueStore
+
+TITLE_MAX_LENGTH = 80
+
+
+def derive_title(body: str, fallback: str = "Untitled CLI Note") -> str:
+    for raw_line in (body or "").splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.startswith("# "):
+            line = line[2:].strip()
+        return line[:TITLE_MAX_LENGTH] or fallback
+    return fallback
+
+
+def parse_tags(tags_csv: Optional[str]) -> list[str]:
+    if not tags_csv:
+        return []
+    seen = set()
+    tags = []
+    for raw_tag in tags_csv.split(","):
+        tag = raw_tag.strip()
+        if not tag or tag in seen:
+            continue
+        seen.add(tag)
+        tags.append(tag)
+    return tags
+
+
+def resolve_body(body: Optional[str], use_stdin: bool) -> str:
+    if body and use_stdin:
+        raise ValueError("Use either --body or --stdin, not both.")
+    if use_stdin:
+        stdin_body = sys.stdin.read()
+        if not stdin_body.strip():
+            raise ValueError("No note body received on stdin.")
+        return stdin_body
+    if not body or not body.strip():
+        raise ValueError("Provide --body or --stdin.")
+    return body
+
+
+def build_note_payload(project: int, title: Optional[str], body: str, tags: list[str], captured_at: Optional[str]):
+    resolved_title = (title or "").strip() or derive_title(body)
+    return {
+        "project": project,
+        "title": resolved_title,
+        "body": body,
+        "tags": tags,
+        "captured_at": captured_at,
+    }
+
+
+def create_note(client, queue_store: QueueStore, *, project: int, title: Optional[str], body: str, tags: list[str], captured_at: Optional[str]):
+    payload = build_note_payload(project, title, body, tags, captured_at)
+    idempotency_key = str(uuid.uuid4())
+    try:
+        response = client.create_note(payload, idempotency_key=idempotency_key)
+        return {
+            "status": "created",
+            "idempotency_key": idempotency_key,
+            "project": project,
+            "note": response.get("note"),
+            "audit_entry_id": response.get("audit_entry_id"),
+        }
+    except NetworkError as exc:
+        queued_note = queue_store.enqueue(
+            project_id=project,
+            title=payload["title"],
+            body=payload["body"],
+            tags=payload["tags"],
+            captured_at=captured_at,
+            idempotency_key=idempotency_key,
+        )
+        return {
+            "status": "queued",
+            "project": project,
+            "local_id": queued_note.local_id,
+            "error": str(exc),
+            "idempotency_key": idempotency_key,
+        }
+    except ApiError as exc:
+        if exc.status_code >= 500:
+            queued_note = queue_store.enqueue(
+                project_id=project,
+                title=payload["title"],
+                body=payload["body"],
+                tags=payload["tags"],
+                captured_at=captured_at,
+                idempotency_key=idempotency_key,
+            )
+            return {
+                "status": "queued",
+                "project": project,
+                "local_id": queued_note.local_id,
+                "error": str(exc),
+                "idempotency_key": idempotency_key,
+            }
+        raise
+
+
+def sync_notes(client, queue_store: QueueStore, *, project: Optional[int] = None):
+    queued_notes = queue_store.list_unsynced(project)
+    results = []
+    synced_count = 0
+    failed_count = 0
+    for queued_note in queued_notes:
+        queue_store.mark_syncing(queued_note.local_id)
+        try:
+            response = client.create_note(
+                build_note_payload(
+                    queued_note.project_id,
+                    queued_note.title,
+                    queued_note.body,
+                    queued_note.tags,
+                    queued_note.captured_at,
+                ),
+                idempotency_key=queued_note.idempotency_key,
+            )
+            note_ref = response.get("note", {}).get("note_ref")
+            queue_store.mark_synced(queued_note.local_id, note_ref or "")
+            synced_count += 1
+            results.append({
+                "local_id": queued_note.local_id,
+                "status": "synced",
+                "note_ref": note_ref,
+                "project": queued_note.project_id,
+            })
+        except (NetworkError, ApiError) as exc:
+            queue_store.mark_failed(queued_note.local_id, str(exc))
+            failed_count += 1
+            results.append({
+                "local_id": queued_note.local_id,
+                "status": "failed",
+                "project": queued_note.project_id,
+                "error": str(exc),
+            })
+    return {
+        "total": len(queued_notes),
+        "synced": synced_count,
+        "failed": failed_count,
+        "results": results,
+    }

ventilatepro_cli-0.1.0/ventilatepro/queue.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+from .config import get_data_dir
+
+
+@dataclass
+class QueuedNote:
+    local_id: int
+    project_id: int
+    title: str
+    body: str
+    tags: list[str]
+    captured_at: Optional[str]
+    created_at: str
+    idempotency_key: str
+    sync_state: str
+    last_sync_attempt_at: Optional[str]
+    last_error: Optional[str]
+    server_note_ref: Optional[str]
+
+
+class QueueStore:
+    def __init__(self, db_path: Optional[Path] = None):
+        self.db_path = db_path or (get_data_dir() / "queue.sqlite3")
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._initialize()
+
+    def _connect(self):
+        return sqlite3.connect(self.db_path)
+
+    def _initialize(self) -> None:
+        with self._connect() as connection:
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS queued_notes (
+                    local_id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    project_id INTEGER NOT NULL,
+                    title TEXT NOT NULL,
+                    body TEXT NOT NULL,
+                    tags TEXT NOT NULL,
+                    captured_at TEXT NULL,
+                    created_at TEXT NOT NULL,
+                    idempotency_key TEXT NOT NULL UNIQUE,
+                    sync_state TEXT NOT NULL,
+                    last_sync_attempt_at TEXT NULL,
+                    last_error TEXT NULL,
+                    server_note_ref TEXT NULL
+                )
+                """
+            )
+            connection.execute(
+                "CREATE INDEX IF NOT EXISTS queued_notes_sync_state_idx ON queued_notes(sync_state)"
+            )
+
+    def enqueue(
+        self,
+        *,
+        project_id: int,
+        title: str,
+        body: str,
+        tags: list[str],
+        captured_at: Optional[str],
+        idempotency_key: str,
+    ) -> QueuedNote:
+        created_at = datetime.now(timezone.utc).isoformat()
+        with self._connect() as connection:
+            cursor = connection.execute(
+                """
+                INSERT INTO queued_notes (
+                    project_id, title, body, tags, captured_at, created_at, idempotency_key, sync_state
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    project_id,
+                    title,
+                    body,
+                    json.dumps(tags),
+                    captured_at,
+                    created_at,
+                    idempotency_key,
+                    "pending",
+                ),
+            )
+            local_id = cursor.lastrowid
+        return self.get(local_id)
+
+    def get(self, local_id: int) -> QueuedNote:
+        with self._connect() as connection:
+            row = connection.execute(
+                """
+                SELECT local_id, project_id, title, body, tags, captured_at, created_at,
+                       idempotency_key, sync_state, last_sync_attempt_at, last_error, server_note_ref
+                FROM queued_notes
+                WHERE local_id = ?
+                """,
+                (local_id,),
+            ).fetchone()
+        if row is None:
+            raise KeyError(f"Queued note {local_id} not found.")
+        return self._row_to_note(row)
+
+    def list_unsynced(self, project_id: Optional[int] = None) -> List[QueuedNote]:
+        query = """
+            SELECT local_id, project_id, title, body, tags, captured_at, created_at,
+                   idempotency_key, sync_state, last_sync_attempt_at, last_error, server_note_ref
+            FROM queued_notes
+            WHERE sync_state IN ('pending', 'failed')
+        """
+        params: list[object] = []
+        if project_id is not None:
+            query += " AND project_id = ?"
+            params.append(project_id)
+        query += " ORDER BY local_id ASC"
+        with self._connect() as connection:
+            rows = connection.execute(query, params).fetchall()
+        return [self._row_to_note(row) for row in rows]
+
+    def mark_syncing(self, local_id: int) -> None:
+        with self._connect() as connection:
+            connection.execute(
+                """
+                UPDATE queued_notes
+                SET sync_state = ?, last_sync_attempt_at = ?, last_error = NULL
+                WHERE local_id = ?
+                """,
+                ("syncing", datetime.now(timezone.utc).isoformat(), local_id),
+            )
+
+    def mark_synced(self, local_id: int, note_ref: str) -> None:
+        with self._connect() as connection:
+            connection.execute(
+                """
+                UPDATE queued_notes
+                SET sync_state = ?, last_sync_attempt_at = ?, last_error = NULL, server_note_ref = ?
+                WHERE local_id = ?
+                """,
+                ("synced", datetime.now(timezone.utc).isoformat(), note_ref, local_id),
+            )
+
+    def mark_failed(self, local_id: int, error_message: str) -> None:
+        with self._connect() as connection:
+            connection.execute(
+                """
+                UPDATE queued_notes
+                SET sync_state = ?, last_sync_attempt_at = ?, last_error = ?
+                WHERE local_id = ?
+                """,
+                ("failed", datetime.now(timezone.utc).isoformat(), error_message, local_id),
+            )
+
+    def count(self) -> int:
+        with self._connect() as connection:
+            row = connection.execute("SELECT COUNT(*) FROM queued_notes").fetchone()
+        return int(row[0] if row else 0)
+
+    def _row_to_note(self, row) -> QueuedNote:
+        return QueuedNote(
+            local_id=row[0],
+            project_id=row[1],
+            title=row[2],
+            body=row[3],
+            tags=json.loads(row[4] or "[]"),
+            captured_at=row[5],
+            created_at=row[6],
+            idempotency_key=row[7],
+            sync_state=row[8],
+            last_sync_attempt_at=row[9],
+            last_error=row[10],
+            server_note_ref=row[11],
+        )

ventilatepro_cli-0.1.0/ventilatepro_cli.egg-info/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: ventilatepro-cli
+Version: 0.1.0
+Summary: VentilatePro CLI
+Project-URL: Homepage, https://ventilatepro.com/exam/cli/
+Project-URL: Documentation, https://ventilatepro.com/exam/cli/
+Project-URL: Support, https://ventilatepro.com/exam/support/
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.16.0
+Requires-Dist: requests>=2.32.0
+Requires-Dist: keyring>=25.6.0
+Requires-Dist: platformdirs>=4.3.0
+
+# VentilatePro CLI
+
+VentilatePro CLI is a local command-line client for authenticating to VentilatePro and creating or syncing notes through the scoped CLI API.
+
+## Install
+
+Published releases install from PyPI:
+
+```bash
+pipx install ventilatepro-cli
+```
+
+Upgrade an existing install:
+
+```bash
+pipx upgrade ventilatepro-cli
+```
+
+Local development install:
+
+```bash
+cd ventilatepro-cli
+pip install -e .
+```
+
+## Commands
+
+```bash
+ventilatepro auth login --url http://localhost:8000
+ventilatepro projects list
+ventilatepro notes create --project 1 --body "Captured from terminal"
+ventilatepro notes sync
+```
+
+See the hosted install guide at `https://ventilatepro.com/exam/cli/`, plus [docs/commands.md](./docs/commands.md), [docs/auth.md](./docs/auth.md), [docs/api.md](./docs/api.md), and [docs/releasing.md](./docs/releasing.md) in this repo.

ventilatepro_cli-0.1.0/ventilatepro_cli.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+tests/test_cli.py
+tests/test_config.py
+ventilatepro/__init__.py
+ventilatepro/__main__.py
+ventilatepro/api_client.py
+ventilatepro/auth.py
+ventilatepro/cli.py
+ventilatepro/config.py
+ventilatepro/notes.py
+ventilatepro/queue.py
+ventilatepro_cli.egg-info/PKG-INFO
+ventilatepro_cli.egg-info/SOURCES.txt
+ventilatepro_cli.egg-info/dependency_links.txt
+ventilatepro_cli.egg-info/entry_points.txt
+ventilatepro_cli.egg-info/requires.txt
+ventilatepro_cli.egg-info/top_level.txt

ventilatepro_cli-0.1.0/ventilatepro_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ventilatepro_cli-0.1.0/ventilatepro_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ventilatepro = ventilatepro.cli:main

ventilatepro_cli-0.1.0/ventilatepro_cli.egg-info/requires.txt

@@ -0,0 +1,4 @@
+typer>=0.16.0
+requests>=2.32.0
+keyring>=25.6.0
+platformdirs>=4.3.0

ventilatepro_cli-0.1.0/ventilatepro_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+ventilatepro