convo-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{convo_cli-0.1.0 → convo_cli-0.1.1}/.gitignore

@@ -7,3 +7,8 @@ __pycache__/
 dist/
 *.egg-info/
 screenshots/
+node_modules/
+.vite/
+.vite-plus/
+.next/
+*.tsbuildinfo

convo_cli-0.1.1/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.1 — 2026-10-16
+
+- Fix Fedora/Podman startup by using the fully qualified `docker.io/pgvector/pgvector:pg16` image. This also supports systems where `docker` is a Podman compatibility wrapper.
+- Cover both Docker and Podman image creation in bootstrap regression tests.
+- Add the Convo logo and an illustrated guide to opening a project folder, signing in, selecting a file, asking questions, and resuming saved sessions.
+- Keep README images accessible when displayed on PyPI.
+- Update the standalone landing page to Next.js, React, TypeScript, Tailwind CSS, and npm, with Geist fonts, a pure black background, and the `#FFAD00` accent.
+
+### Install or update
+
+```sh
+uv tool install --python 3.12 convo-cli
+# Existing installation:
+uv tool upgrade --refresh convo-cli
+```
+
+Docker Desktop or Podman is required for Convo's managed local database. Existing conversations and local database data are preserved.

{convo_cli-0.1.0 → convo_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: convo-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: A local terminal RAG assistant for chatting with selected files.
 Project-URL: Homepage, https://github.com/madvillax/convo
 Project-URL: Repository, https://github.com/madvillax/convo
@@ -38,7 +38,11 @@ Requires-Dist: textual<9,>=8.2
 Requires-Dist: transformers>=4.51
 Description-Content-Type: text/markdown
 
-# Convo
+<div align="center">
+  <img src="https://raw.githubusercontent.com/madvillax/convo/main/apps/web/public/favicon.svg" alt="Convo logo" width="64" height="64" />
+  <h1>Convo</h1>
+  <p><strong>Your files. A quiet conversation.</strong></p>
+</div>
 
 Convo is an open-source, local-first terminal app for chatting with a selected file. Qwen3 embeddings and PostgreSQL full-text search retrieve passages together; a local cross-encoder reranks them; your connected ChatGPT account returns a structured answer with supporting quotations.
 
@@ -46,28 +50,23 @@ It is released under the [MIT License](LICENSE). Contributions are welcome—see
 
 ## Install and start
 
-The supported release install uses [uv](https://docs.astral.sh/uv/):
+Install Convo from PyPI with [uv](https://docs.astral.sh/uv/):
 
 ```sh
-uv tool install convo-cli
-convo
+uv tool install --python 3.12 convo-cli
 ```
 
-On first launch, `convo` creates a private settings file at `~/.config/convo/.env`, pulls `pgvector/pgvector:pg16`, starts a loopback-only `convo-postgres` container, and runs migrations before opening the terminal app. It generates a random database password and preserves existing data. Later launches restart Convo's local container if needed and apply pending migrations.
+To update an existing installation, run `uv tool upgrade --refresh convo-cli`.
 
-Local storage needs Docker Desktop or Podman installed. Start Docker Desktop first if you use Docker. On macOS, Convo starts or initializes a Podman machine when Podman is installed. First use downloads Python dependencies, a database image, and—when indexing your first file—the embedding/reranker models.
+Convo needs Docker Desktop or Podman for its local database. The install downloads its Python dependencies. On first launch, it creates a private settings file at `~/.config/convo/.env`, pulls `docker.io/pgvector/pgvector:pg16`, starts a loopback-only `convo-postgres` container, and runs migrations. It generates a random database password and preserves existing data. Later launches restart Convo's local container if needed and apply pending migrations.
 
-If you already use PostgreSQL, set `DATABASE_URL` to a `postgresql+psycopg://...` URL, run `convo --setup` once to migrate that database, then run `convo`. Explicit database connections are used as configured; startup only manages storage created by Convo.
+On macOS, Convo starts or initializes a Podman machine when Podman is installed. First use downloads a database image and, when indexing your first file, the embedding and reranker models.
 
-For a one-command install on macOS/Linux, inspect and then run the repository installer:
+Convo 0.1.1 fixes Fedora/Podman startup failures reporting `short-name resolution enforced but cannot prompt without a TTY`. Upgrade if you see this error on an older version. Convo now uses the full Docker Hub image name, including when the `docker` command is a Podman compatibility wrapper.
 
-```sh
-curl -LsSf https://raw.githubusercontent.com/madvillax/convo/main/scripts/install.sh | sh
-```
-
-It installs uv if needed, installs `convo-cli`, and adds uv's tool directory to your shell path. Then type `convo` to start. Open a new terminal if `convo` is not immediately found.
+If you already use PostgreSQL, set `DATABASE_URL` to a `postgresql+psycopg://...` URL, run `convo --setup` once to migrate that database, then run `convo`. Explicit database connections are used as configured; startup only manages storage created by Convo.
 
-To use an unreleased checkout while developing:
+To install from a local checkout while developing, run this from the repository root:
 
 ```sh
 uv sync --python 3.12
@@ -90,9 +89,44 @@ For a UI preview without services or backend dependencies:
 uv run convo --shell
 ```
 
-## Use
+## How to use
+
+### 1. Open the folder you want to ask about
+
+Run Convo from your project directory. It starts its file browser there.
+
+```sh
+cd ~/path/to/your/project
+convo
+```
+
+To browse another folder, pass it directly: `convo --directory ~/Documents`.
+
+### 2. Connect your ChatGPT account
 
-Type `/` for command suggestions. Filter by typing, use ↑/↓ to move, Tab to complete, Enter to run, and Esc to dismiss.
+In Convo, type `/login`, press Enter, and finish sign-in in your browser. Then type `/models` to choose an account model. You can type `/` at any time to see command suggestions; use ↑/↓ to move, Tab to complete, Enter to run, and Esc to close the list.
+
+### 3. Choose a file
+
+Type `/file` and press Enter, or use Ctrl+O. Choose a supported file from the current folder and press Enter. Convo prepares and indexes it before you ask questions.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/madvillax/convo/main/docs/images/file-picker.svg" alt="Convo file picker with README.md selected from a sample project folder." width="760" />
+</p>
+
+### 4. Ask a question
+
+Type a question in plain language and press Enter. Convo searches the selected file and answers with numbered citations and a source block showing the file and line numbers.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/madvillax/convo/main/apps/web/public/images/convo-chat.png" alt="Example Convo conversation with a cited answer about a project architecture file." width="760" />
+</p>
+
+### 5. Come back to a conversation
+
+Type `/sessions` to search and resume a saved conversation. Type `/new` to start another conversation while keeping the selected file, or `/reset` to start fresh without one.
+
+## Commands and shortcuts
 
 | Command/key | Action |
 | --- | --- |
@@ -139,6 +173,19 @@ convo/
 
 [ARCHITECTURE.md](ARCHITECTURE.md) explains the files, schema, data flow, tuning, and verification. [changes.md](changes.md) records implementation approaches and validation.
 
+## Website
+
+The Next.js, React, TypeScript, and Tailwind CSS landing page in [`apps/web`](apps/web/README.md) is an independent app with its own package manifest and lockfile.
+
+```sh
+cd apps/web
+npm install
+npm run dev     # website at http://127.0.0.1:3000
+npm run build   # Next.js production build in .next
+npm run start   # serve the production website
+npm run check   # website checks
+```
+
 ## Checks
 
 ```sh

{convo_cli-0.1.0 → convo_cli-0.1.1}/README.md

@@ -1,4 +1,8 @@
-# Convo
+<div align="center">
+  <img src="https://raw.githubusercontent.com/madvillax/convo/main/apps/web/public/favicon.svg" alt="Convo logo" width="64" height="64" />
+  <h1>Convo</h1>
+  <p><strong>Your files. A quiet conversation.</strong></p>
+</div>
 
 Convo is an open-source, local-first terminal app for chatting with a selected file. Qwen3 embeddings and PostgreSQL full-text search retrieve passages together; a local cross-encoder reranks them; your connected ChatGPT account returns a structured answer with supporting quotations.
 
@@ -6,28 +10,23 @@ It is released under the [MIT License](LICENSE). Contributions are welcome—see
 
 ## Install and start
 
-The supported release install uses [uv](https://docs.astral.sh/uv/):
+Install Convo from PyPI with [uv](https://docs.astral.sh/uv/):
 
 ```sh
-uv tool install convo-cli
-convo
+uv tool install --python 3.12 convo-cli
 ```
 
-On first launch, `convo` creates a private settings file at `~/.config/convo/.env`, pulls `pgvector/pgvector:pg16`, starts a loopback-only `convo-postgres` container, and runs migrations before opening the terminal app. It generates a random database password and preserves existing data. Later launches restart Convo's local container if needed and apply pending migrations.
+To update an existing installation, run `uv tool upgrade --refresh convo-cli`.
 
-Local storage needs Docker Desktop or Podman installed. Start Docker Desktop first if you use Docker. On macOS, Convo starts or initializes a Podman machine when Podman is installed. First use downloads Python dependencies, a database image, and—when indexing your first file—the embedding/reranker models.
+Convo needs Docker Desktop or Podman for its local database. The install downloads its Python dependencies. On first launch, it creates a private settings file at `~/.config/convo/.env`, pulls `docker.io/pgvector/pgvector:pg16`, starts a loopback-only `convo-postgres` container, and runs migrations. It generates a random database password and preserves existing data. Later launches restart Convo's local container if needed and apply pending migrations.
 
-If you already use PostgreSQL, set `DATABASE_URL` to a `postgresql+psycopg://...` URL, run `convo --setup` once to migrate that database, then run `convo`. Explicit database connections are used as configured; startup only manages storage created by Convo.
+On macOS, Convo starts or initializes a Podman machine when Podman is installed. First use downloads a database image and, when indexing your first file, the embedding and reranker models.
 
-For a one-command install on macOS/Linux, inspect and then run the repository installer:
+Convo 0.1.1 fixes Fedora/Podman startup failures reporting `short-name resolution enforced but cannot prompt without a TTY`. Upgrade if you see this error on an older version. Convo now uses the full Docker Hub image name, including when the `docker` command is a Podman compatibility wrapper.
 
-```sh
-curl -LsSf https://raw.githubusercontent.com/madvillax/convo/main/scripts/install.sh | sh
-```
-
-It installs uv if needed, installs `convo-cli`, and adds uv's tool directory to your shell path. Then type `convo` to start. Open a new terminal if `convo` is not immediately found.
+If you already use PostgreSQL, set `DATABASE_URL` to a `postgresql+psycopg://...` URL, run `convo --setup` once to migrate that database, then run `convo`. Explicit database connections are used as configured; startup only manages storage created by Convo.
 
-To use an unreleased checkout while developing:
+To install from a local checkout while developing, run this from the repository root:
 
 ```sh
 uv sync --python 3.12
@@ -50,9 +49,44 @@ For a UI preview without services or backend dependencies:
 uv run convo --shell
 ```
 
-## Use
+## How to use
+
+### 1. Open the folder you want to ask about
+
+Run Convo from your project directory. It starts its file browser there.
+
+```sh
+cd ~/path/to/your/project
+convo
+```
+
+To browse another folder, pass it directly: `convo --directory ~/Documents`.
+
+### 2. Connect your ChatGPT account
 
-Type `/` for command suggestions. Filter by typing, use ↑/↓ to move, Tab to complete, Enter to run, and Esc to dismiss.
+In Convo, type `/login`, press Enter, and finish sign-in in your browser. Then type `/models` to choose an account model. You can type `/` at any time to see command suggestions; use ↑/↓ to move, Tab to complete, Enter to run, and Esc to close the list.
+
+### 3. Choose a file
+
+Type `/file` and press Enter, or use Ctrl+O. Choose a supported file from the current folder and press Enter. Convo prepares and indexes it before you ask questions.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/madvillax/convo/main/docs/images/file-picker.svg" alt="Convo file picker with README.md selected from a sample project folder." width="760" />
+</p>
+
+### 4. Ask a question
+
+Type a question in plain language and press Enter. Convo searches the selected file and answers with numbered citations and a source block showing the file and line numbers.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/madvillax/convo/main/apps/web/public/images/convo-chat.png" alt="Example Convo conversation with a cited answer about a project architecture file." width="760" />
+</p>
+
+### 5. Come back to a conversation
+
+Type `/sessions` to search and resume a saved conversation. Type `/new` to start another conversation while keeping the selected file, or `/reset` to start fresh without one.
+
+## Commands and shortcuts
 
 | Command/key | Action |
 | --- | --- |
@@ -99,6 +133,19 @@ convo/
 
 [ARCHITECTURE.md](ARCHITECTURE.md) explains the files, schema, data flow, tuning, and verification. [changes.md](changes.md) records implementation approaches and validation.
 
+## Website
+
+The Next.js, React, TypeScript, and Tailwind CSS landing page in [`apps/web`](apps/web/README.md) is an independent app with its own package manifest and lockfile.
+
+```sh
+cd apps/web
+npm install
+npm run dev     # website at http://127.0.0.1:3000
+npm run build   # Next.js production build in .next
+npm run start   # serve the production website
+npm run check   # website checks
+```
+
 ## Checks
 
 ```sh

convo_cli-0.1.1/apps/web/README.md

@@ -0,0 +1,22 @@
+# Convo website
+
+The Convo landing page is an independent Next.js App Router app using React, TypeScript, and Tailwind CSS v4. The hero and usage guide use Vercel's Geist Sans and Geist Mono through the official `geist` package and `next/font`.
+
+Run from `apps/web` (use `cd apps/web` first when starting at the repository root):
+
+```sh
+npm install
+npm run dev       # http://127.0.0.1:3000
+npm run check     # ESLint and TypeScript checks
+npm run build     # Next.js production build in .next
+npm run start     # serve the production build on port 3000
+npm run preview   # alias for the production server
+```
+
+This folder has its own `package.json`, `package-lock.json`, and `node_modules`. Use Node.js and npm to install and run it. The Python CLI in `convo/` uses the repository's `pyproject.toml` and `uv.lock`. Run it from the repository root with `uv run convo`. No database or ChatGPT connection is needed to run the website.
+
+`src/app/page.tsx` composes the page as a Server Component. Small Client Components in `src/components` handle installation tabs, command categories, and clipboard feedback. Layout and responsive styling use Tailwind utilities; `globals.css` defines the theme and shared browser defaults. `postcss.config.mjs` runs the Tailwind PostCSS plugin.
+
+For Vercel, choose `apps/web` as the project root and the Next.js framework preset. The production build also runs on any host that supports `next start`.
+
+This site uses real CLI commands from `convo/__main__.py` and `convo/ui/commands.py`; keep its guide in sync when those change. The terminal image is a repository screenshot in tracked public assets. Fonts are bundled from the installed `geist` package, so builds do not fetch Google Fonts.

{convo_cli-0.1.0 → convo_cli-0.1.1}/convo/__init__.py

@@ -1,3 +1,3 @@
 """A local terminal RAG assistant for chatting with selected files."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{convo_cli-0.1.0 → convo_cli-0.1.1}/convo/bootstrap.py

@@ -18,7 +18,9 @@ from urllib.parse import quote
 
 CONTAINER_NAME = "convo-postgres"
 VOLUME_NAME = "convo-postgres-data"
-IMAGE = "pgvector/pgvector:pg16"
+# Podman (including Fedora's docker shim) cannot prompt for a registry when
+# startup captures subprocess output. Always use a fully qualified image name.
+IMAGE = "docker.io/pgvector/pgvector:pg16"
 DATABASE_NAME = "convo"
 DATABASE_USER = "convo"
 

{convo_cli-0.1.0 → convo_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "convo-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "A local terminal RAG assistant for chatting with selected files."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -62,6 +62,7 @@ include = [
     "tests",
     "scripts",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md",

{convo_cli-0.1.0 → convo_cli-0.1.1}/tests/test_bootstrap.py

@@ -10,7 +10,10 @@ from convo.core import config
 from convo.core.config import user_settings_path
 
 
-def test_setup_writes_private_user_settings_and_creates_loopback_container(tmp_path, monkeypatch):
+@pytest.mark.parametrize("runtime", ["docker", "podman"])
+def test_setup_writes_private_user_settings_and_creates_loopback_container(
+    tmp_path, monkeypatch, runtime
+):
     commands: list[list[str]] = []
 
     def fake_run(command, *, allow_failure=False):
@@ -21,7 +24,7 @@ def test_setup_writes_private_user_settings_and_creates_loopback_container(tmp_p
     monkeypatch.setattr(bootstrap, "_run", fake_run)
     monkeypatch.setattr(bootstrap.secrets, "token_urlsafe", lambda _size: "safe-password")
 
-    database_url = bootstrap._ensure_container("podman", None)
+    database_url = bootstrap._ensure_container(runtime, None)
 
     assert database_url == "postgresql+psycopg://convo:safe-password@localhost:5432/convo"
     assert user_settings_path().read_text(encoding="utf-8") == (
@@ -35,6 +38,10 @@ def test_setup_writes_private_user_settings_and_creates_loopback_container(tmp_p
     )
     assert user_settings_path().stat().st_mode & 0o777 == 0o600
     create_command = next(command for command in commands if command[1] == "run")
+    # Both Podman and its Docker-compatible shim must avoid interactive
+    # short-name registry resolution on distributions such as Fedora.
+    assert create_command[0] == runtime
+    assert create_command[-1] == "docker.io/pgvector/pgvector:pg16"
     assert "127.0.0.1:5432:5432" in create_command
     assert "convo-postgres-data:/var/lib/postgresql/data" in create_command
     assert "io.convo.managed=true" in create_command