codevira 1.7.0__tar.gz → 1.8.0__tar.gz

{codevira-1.7.0 → codevira-1.8.0}/CHANGELOG.md

@@ -13,6 +13,258 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
+## [1.8.0] — 2026-04-23 — Memory Sharpening + Config UX
+
+Three internal improvements that make the memory we already capture **sharper**,
+without making it heavier. Zero new MCP tools. Zero new tables. The public API
+shape changes only one thing: `get_session_context()` gains a `focus_source`
+field (~10 tokens, additive, backwards-compatible).
+
+The problem this release solves:
+- `get_session_context()` returned the 3 newest decisions by timestamp —
+  regardless of whether they had anything to do with the current task.
+- `search_decisions()` ordered purely by recency — a `file_path` match
+  was no better than a match buried in an unrelated session summary.
+- `log_session()` inserted every decision unconditionally — a day of
+  iterative agent work logged the same intent 5+ times.
+
+### Fixed
+
+- **MCP `serverInfo.version` reported the MCP library version, not codevira's**
+  (pre-existing bug, surfaced during v1.8 install verification on Python
+  3.13). `Server("codevira")` was constructed without a `version=` argument,
+  so the framework defaulted to its own pip-package version (e.g. `1.27.0`)
+  in the JSON-RPC `initialize` handshake response. Clients use this field
+  for telemetry and version gating, so the wrong value misled them.
+  One-line fix: `Server("codevira", version=__version__)`.
+- **`get_session_context()` read the wrong dict key** (pre-existing bug).
+  `list_open_changesets()` returns `{"open_changesets": [...], ...}`, but
+  `get_session_context` looked for `"changesets"`. The `open_changesets`
+  field in the session-context response was **always empty** in production.
+  Tests didn't catch it because mocks used the same wrong key.
+
+- **`GlobalDB` concurrent-open race condition** (pre-existing bug — latent
+  since v1.6's centralized storage introduced shared `~/.codevira/global.db`).
+  `PRAGMA journal_mode=WAL` requires an exclusive lock and — unlike normal
+  SQL — does NOT honour `sqlite3`'s `busy_timeout`. When multiple processes
+  or threads opened the same fresh database concurrently (e.g. several
+  projects' first-ever `codevira register` running in parallel, or the
+  `global_sync` background export racing the MCP server thread), one or
+  more would raise `OperationalError('database is locked')` and silently
+  fail to register. The test `test_concurrent_access_from_threads` was
+  flaky at 60% failure rate, hinting at the real issue. Fixed with WAL-
+  enable retry loop + short-circuit when WAL is already active. Stability
+  verified at 20/20 passes across 20 test runs.
+
+### Changed
+
+- **Focus-weighted `recent_decisions` in `get_session_context()`**. Instead
+  of chronological "newest 3", decisions are now ranked by what the agent
+  is currently focused on:
+  1. Open changeset with `files_pending` → focus = first file path of the
+     most-recently-created changeset.
+  2. Strong `current_phase.next_action` signal → focus = extracted keywords
+     (rejects short or stop-list-only actions like "continue work").
+  3. Otherwise → chronological fallback (unchanged behaviour).
+  If focus returns fewer than 3, the list pads with `get_recent_decisions()`.
+  New response field `focus_source` (`"open_changeset:<id>"`, `"next_action"`,
+  or `null`) lets the agent see *why* it got these decisions.
+
+- **Smarter `search_decisions()` ranking**. SQL now adds `file_path` to both
+  the WHERE clause and a CASE-based ORDER BY:
+  `file_path match (0) > decision text (1) > context (2) > summary-only (3)`,
+  then newest first within each tier. Searching for `"src/auth.py"` now
+  surfaces file-path matches even when the decision text doesn't mention
+  the path.
+
+- **Decision dedup on write**. `log_session()` now skips a new decision
+  if it has a `file_path` and its token-set overlaps ≥ 80% with any of
+  the 5 most recent decisions for that same file. The session row is
+  always created; only redundant *decisions* are dropped. Short
+  decisions (< 3 tokens) and decisions without `file_path` are always
+  inserted.
+
+### Added
+
+- `focus_source` field on `get_session_context()` response (≈10 tokens).
+- `mcp_server.tools.learning._infer_focus()` — pure helper, module-private.
+- `indexer.sqlite_graph._is_duplicate()` — pure token-overlap helper,
+  module-private, independently testable.
+- **`codevira configure`** — new CLI subcommand. Scans your project
+  (gitignore-aware via existing `discover_source_files()`), shows discovered
+  directories and file extensions with counts, lets you pick via a numbered-
+  list prompt, writes the choices back to `.codevira/config.yaml`, and offers
+  to rebuild the index. Non-interactive:
+  `codevira configure --dirs src,lib --extensions .py,.ts --no-reindex`.
+  Solves the AgentStore-style "0 chunks indexed" case where
+  `auto_detect_project()` mis-guesses a monorepo layout.
+  When `config.yaml` is missing (normal state after `codevira register` but
+  before the first MCP tool call), `configure` auto-bootstraps it in full
+  parity with `auto_init`'s first-init path: writes `metadata.json` (rename-
+  resilient lookup via `git_remote`) and registers the project in
+  `~/.codevira/global.db` for cross-project intelligence. Missing these on
+  earlier drafts would have left the project invisible to rename-resilient
+  path lookup and absent from global memory until the first session log.
+- **Zero-chunks safety hint at index time.** When `codevira index --full` or
+  `codevira index` (incremental, project-wide) matches no files against your
+  `watched_dirs` + `file_extensions`, the indexer now prints a one-line
+  remedy pointing at `codevira configure`. Output goes to **stderr** (not
+  stdout) so the hint never leaks into the MCP JSON-RPC wire when
+  `start_background_full_index` runs during auto_init inside the MCP server
+  process. Also logged at WARNING level so background invocations
+  (auto-init, launchd watcher) leave a trace regardless of terminal
+  capture. Does NOT fire for caller-scoped incremental runs (e.g. the
+  `refresh_index` MCP tool targeting a specific file) — zero matches there
+  is the caller's choice, not a misconfiguration.
+- `codevira register` success banner now nudges toward `codevira configure`.
+
+### Internal
+
+- 87 new tests:
+  - 34 for v1.8 memory sharpening (focus inference priority rules, ranking
+    tier ordering, dedup threshold behaviour, session-row-always-created
+    invariant, NULL file_path fallback, session_id filtering + new ranking SQL)
+  - 43 for `codevira configure` (scan_project with centralized-mode
+    decoupling + skip_dirs honoring, multi-select prompt incl. non-TTY
+    fallback + Ctrl+C clean-abort, config writer preserve/dedupe/idempotency,
+    orchestrator edge cases incl. bootstrap on missing config, dry-run disk
+    safety, corrupt-YAML handling, empty-extensions safety, PermissionError
+    friendly wrapper, `--dirs`/`--extensions` normalization)
+  - 10 for the zero-chunks hint (unit tests of the helper proving it writes
+    to stderr not stdout + integration tests proving it fires ONLY for full
+    or project-wide-incremental scans, not caller-scoped or normal "no files
+    changed")
+- Full test suite: **1,398 passing, 0 deterministic failures** (up from
+  1,306 at v1.7.1 → +92). The two "pre-existing watchdog failures" that
+  haunted earlier drafts of this CHANGELOG turned out to be an environment
+  issue in a single dev machine (system Python 3.9 without `watchdog`);
+  the pipx-installed v1.8.0 environment has all required deps. The one
+  pre-existing flaky test (`test_concurrent_access_from_threads`) is now
+  fixed by the `GlobalDB` WAL-enable retry loop described above.
+
+### Verified environments
+
+- **macOS (APFS)** + Python 3.9 system + Python 3.11 pipx: full regression
+  passes; all interactive + non-interactive flows manually verified on three
+  real projects (AgentStore, UDAP, ToolsConnector).
+- **Cross-process + thread concurrency**: stress-tested (12 threads × 20
+  writes, 8 subprocesses × 25 writes, 100 concurrent-read/write cycles) —
+  0 errors, 0 data loss.
+
+### Unverified environments / known gaps (candidates for v1.8.1 or v1.9)
+
+- **Windows**: `os.replace` atomicity weakens when the destination is open
+  by another process. If a Windows user has Claude Code reading
+  `config.yaml` at the moment `codevira configure` writes it, the write
+  may fail with `PermissionError`. Pre-existing risk; v1.8 does not fix
+  and does not regress. Windows smoke-testing is a v1.9 scope item.
+- **Network filesystems (NFS, SMB)**: atomic-replace guarantees are weaker
+  on network FS. Unlikely in solo-dev environments (codevira's target);
+  possible in enterprise setups.
+- **Python 3.10, 3.12**: The APIs `codevira configure` uses are stable
+  across 3.10+. Syntax-verified against 3.10+. **Python 3.13.7
+  empirically verified** during v1.8 install validation (full pipx
+  install + MCP handshake working). 3.10 and 3.12 are syntax-verified
+  only. CI on all Python versions is a v1.8.x task.
+- **Case-insensitive filesystem slugs**: On macOS APFS (default), paths
+  differing only in case (`~/Documents` vs `~/documents`) produce
+  different slugs for the same physical directory, creating split state.
+  Pre-existing since v1.5 — fixing requires a migration step for existing
+  users and is scoped to v1.9.
+- **Interactive TTY automated coverage**: The interactive prompt flow is
+  tested via mocked stdin + `sys.stdin.isatty`. A real terminal session
+  was manually verified during development; automated TTY testing (via
+  pexpect or similar) is a v1.8.x nice-to-have.
+- **MCP client post-upgrade reload**: `codevira register` writes config;
+  each MCP client (Claude Code, Cursor, Windsurf, Antigravity, Claude
+  Desktop) needs to reload to see changes. Verified for Claude Code.
+  Other clients may have edge cases that surface post-release.
+
+### Known test flake (NOT v1.8; pre-existing)
+
+- `test_chunk_error_continues_to_next_file` fails ~3/10 times in the full
+  suite on Python 3.9 (system) due to a chromadb+pydantic version
+  incompatibility raising `TypeError` during `import chromadb`, which
+  `_check_search_deps()` doesn't catch (it only catches `ImportError`).
+  **Not introduced by v1.8 and not touched by v1.8 code paths** — verified
+  by measuring the same 3/10 flake rate on clean v1.7.1. v1.8 deliberately
+  does not widen the exception catch because it would silently mask real
+  dep issues; a proper fix belongs in a targeted follow-up PR with its own
+  test coverage. Does not affect production users — the condition requires
+  a specific dev environment (Py 3.9 + mismatched chromadb/pydantic).
+- Regression guards added by the binocular review pass:
+  - `test_centralized_mode_data_dir_and_project_root_decoupled` — catches
+    the production bug where `data_dir.parent` was used where
+    `get_project_root()` was required (centralized mode v1.6+).
+  - `test_bootstraps_config_when_missing` — catches the workflow where
+    `codevira register` was run but config.yaml hasn't been written yet
+    (auto_init hadn't fired because no MCP tool call had happened).
+  - `test_bootstrap_respects_dry_run` — catches bootstrap writing disk
+    during `--dry-run`.
+  - `test_fires_on_stderr_when_not_quiet` — catches zero-chunks hint
+    leaking to stdout, which would corrupt the MCP JSON-RPC wire in stdio
+    mode.
+  - `test_empty_extensions_non_interactive_errors_exit_2` — catches
+    `--extensions ""` being silently accepted, which would write an empty
+    `file_extensions: []` and re-create the zero-chunks bug.
+  - `test_ctrl_c_in_prompt_returns_exit_0` — catches KeyboardInterrupt
+    propagating a traceback to the user.
+  - `test_permission_error_on_write_exits_1` — catches PermissionError /
+    OSError propagating a traceback when config.yaml isn't writable.
+  - `test_honors_user_skip_dirs_from_config` — catches scan_project
+    ignoring the user's explicit skip_dirs in config.yaml.
+
+### Known limitations
+
+- A running file-watcher or live MCP server session won't pick up config
+  changes until it restarts (the watcher snapshots `watched_dirs` at boot).
+  Restart your AI tool after `codevira configure` to apply changes.
+- `yaml.safe_dump` doesn't preserve comments in `config.yaml`. First-time
+  configs are auto-generated and have no comments; users who hand-edited
+  may see formatting normalized after `codevira configure` rewrites the file.
+
+### Unchanged (intentionally)
+
+- No new MCP tools. No new tables. No schema migration.
+- `search_decisions()` method signature unchanged.
+- `log_session()` method signature unchanged.
+- `get_session_context()` keys are additive — no removals.
+- `auto_init.py`, `detect.py`, `gitignore.py`, and `metadata.json` writer
+  untouched; `codevira configure` reuses all existing detection machinery.
+
+---
+
+## [1.7.1] — 2026-04-22 — Search Timeout Fix & Version Display
+
+Two small but user-visible fixes on top of v1.7.0.
+
+### Fixed
+
+- **`search_codebase` timeout on first call** (reported by a user testing
+  on Antigravity). The embedding model (`all-MiniLM-L6-v2`) was being
+  instantiated fresh on every MCP tool call, which triggered a ~90MB
+  download + PyTorch init on first ever use (30-60s on slow networks)
+  and 1-3s of re-init overhead on every subsequent call. Antigravity's
+  ~30s MCP tool timeout killed the query before the model finished loading.
+
+  Three-layer fix:
+  1. Module-level cache for the chroma client + embedding function,
+     keyed by `db_dir`. Subsequent calls are now instant.
+  2. Background `prewarm_embedding_model()` spawned at server startup
+     (both stdio and HTTP transports). Model loads in parallel with
+     the MCP handshake window.
+  3. Cold-path timeout guard: if a query arrives while warmup is still
+     in progress, returns `{"status": "warming", ...}` within 10 seconds
+     instead of blocking until the MCP timeout fires. The agent gets a
+     clean retryable response.
+
+- **`codevira register` banner showed hardcoded `v1.6`** after upgrading
+  to v1.7.0. Now reads `mcp_server.__version__` dynamically. Same fix
+  applied to `metadata.json` version field written during auto-init and
+  migration.
+
+---
+
 ## [1.7.0] — 2026-04-18 — Token Efficiency & AI-First Tool Design
 
 **The biggest release since v1.0.** We realized Codevira was dumping 15k-60k

{codevira-1.7.0/codevira.egg-info → codevira-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 1.7.0
+Version: 1.8.0
 Summary: Persistent adaptive memory for AI coding agents — MCP server with context graph, semantic search, adaptive learning, roadmap tracking, and cross-tool continuity.
 Author-email: Sachin Shelke <sachin.worldnet@gmail.com>
 License: MIT
@@ -44,7 +44,7 @@ Provides-Extra: all
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-1.7.0-orange)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.8.0-orange)](CHANGELOG.md)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
 
 **Built for solo developers** working on local projects with AI agents. Codevira gives every AI tool you use access to the same persistent project memory — so you stop re-explaining your codebase every session, stop losing carefully-made decisions, and stop burning tokens on re-discovery.
@@ -142,6 +142,24 @@ Ask your AI agent to call `get_roadmap()` — it should return your current phas
 
 > **Note:** Restart your AI tool after running `codevira register` to pick up the new MCP config.
 
+### Customizing what's indexed
+
+Codevira tries to auto-detect your project's source layout, but monorepo or non-standard layouts sometimes slip through — you'll notice when `codevira index --full` reports `0 chunks indexed` and prints a hint pointing you here.
+
+```bash
+cd your-project
+codevira configure
+```
+
+Scans your project (gitignore-aware), shows discovered directories and extensions with file counts, and lets you pick which to watch via a numbered-list prompt. It writes your choices back to `.codevira/config.yaml` and offers to rebuild the index.
+
+**Non-interactive** (useful in scripts or CI):
+```bash
+codevira configure --dirs src,packages,apps --extensions .py,.ts,.tsx --no-reindex
+```
+
+After changing watched directories, **restart your AI tool** — running watchers snapshot the dir set at boot.
+
 ### Manual config (only if auto-inject didn't detect your tool)
 
 Codevira supports two transports. Use the right one for your client:
@@ -570,6 +588,8 @@ Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full
 **Requesting a feature?** [Open a feature request](https://github.com/sachinshelke/codevira/issues/new?template=feature_request.md)
 **Found a security issue?** Read [SECURITY.md](SECURITY.md) — please don't use public issues for vulnerabilities.
 
+**Testing a release candidate locally?** See [docs/local-pypi-https.md](docs/local-pypi-https.md) for setting up a Docker-based HTTPS PyPI registry that mirrors the real PyPI install flow without touching public PyPI.
+
 ---
 
 ## FAQ

{codevira-1.7.0 → codevira-1.8.0}/README.md

@@ -5,7 +5,7 @@
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-1.7.0-orange)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.8.0-orange)](CHANGELOG.md)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
 
 **Built for solo developers** working on local projects with AI agents. Codevira gives every AI tool you use access to the same persistent project memory — so you stop re-explaining your codebase every session, stop losing carefully-made decisions, and stop burning tokens on re-discovery.
@@ -103,6 +103,24 @@ Ask your AI agent to call `get_roadmap()` — it should return your current phas
 
 > **Note:** Restart your AI tool after running `codevira register` to pick up the new MCP config.
 
+### Customizing what's indexed
+
+Codevira tries to auto-detect your project's source layout, but monorepo or non-standard layouts sometimes slip through — you'll notice when `codevira index --full` reports `0 chunks indexed` and prints a hint pointing you here.
+
+```bash
+cd your-project
+codevira configure
+```
+
+Scans your project (gitignore-aware), shows discovered directories and extensions with file counts, and lets you pick which to watch via a numbered-list prompt. It writes your choices back to `.codevira/config.yaml` and offers to rebuild the index.
+
+**Non-interactive** (useful in scripts or CI):
+```bash
+codevira configure --dirs src,packages,apps --extensions .py,.ts,.tsx --no-reindex
+```
+
+After changing watched directories, **restart your AI tool** — running watchers snapshot the dir set at boot.
+
 ### Manual config (only if auto-inject didn't detect your tool)
 
 Codevira supports two transports. Use the right one for your client:
@@ -531,6 +549,8 @@ Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full
 **Requesting a feature?** [Open a feature request](https://github.com/sachinshelke/codevira/issues/new?template=feature_request.md)
 **Found a security issue?** Read [SECURITY.md](SECURITY.md) — please don't use public issues for vulnerabilities.
 
+**Testing a release candidate locally?** See [docs/local-pypi-https.md](docs/local-pypi-https.md) for setting up a Docker-based HTTPS PyPI registry that mirrors the real PyPI install flow without touching public PyPI.
+
 ---
 
 ## FAQ

{codevira-1.7.0 → codevira-1.8.0/codevira.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 1.7.0
+Version: 1.8.0
 Summary: Persistent adaptive memory for AI coding agents — MCP server with context graph, semantic search, adaptive learning, roadmap tracking, and cross-tool continuity.
 Author-email: Sachin Shelke <sachin.worldnet@gmail.com>
 License: MIT
@@ -44,7 +44,7 @@ Provides-Extra: all
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-1.7.0-orange)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.8.0-orange)](CHANGELOG.md)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
 
 **Built for solo developers** working on local projects with AI agents. Codevira gives every AI tool you use access to the same persistent project memory — so you stop re-explaining your codebase every session, stop losing carefully-made decisions, and stop burning tokens on re-discovery.
@@ -142,6 +142,24 @@ Ask your AI agent to call `get_roadmap()` — it should return your current phas
 
 > **Note:** Restart your AI tool after running `codevira register` to pick up the new MCP config.
 
+### Customizing what's indexed
+
+Codevira tries to auto-detect your project's source layout, but monorepo or non-standard layouts sometimes slip through — you'll notice when `codevira index --full` reports `0 chunks indexed` and prints a hint pointing you here.
+
+```bash
+cd your-project
+codevira configure
+```
+
+Scans your project (gitignore-aware), shows discovered directories and extensions with file counts, and lets you pick which to watch via a numbered-list prompt. It writes your choices back to `.codevira/config.yaml` and offers to rebuild the index.
+
+**Non-interactive** (useful in scripts or CI):
+```bash
+codevira configure --dirs src,packages,apps --extensions .py,.ts,.tsx --no-reindex
+```
+
+After changing watched directories, **restart your AI tool** — running watchers snapshot the dir set at boot.
+
 ### Manual config (only if auto-inject didn't detect your tool)
 
 Codevira supports two transports. Use the right one for your client:
@@ -570,6 +588,8 @@ Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full
 **Requesting a feature?** [Open a feature request](https://github.com/sachinshelke/codevira/issues/new?template=feature_request.md)
 **Found a security issue?** Read [SECURITY.md](SECURITY.md) — please don't use public issues for vulnerabilities.
 
+**Testing a release candidate locally?** See [docs/local-pypi-https.md](docs/local-pypi-https.md) for setting up a Docker-based HTTPS PyPI registry that mirrors the real PyPI install flow without touching public PyPI.
+
 ---
 
 ## FAQ

{codevira-1.7.0 → codevira-1.8.0}/codevira.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ codevira.egg-info/top_level.txt
 docs/how-i-built-persistent-memory-for-ai-agents.md
 docs/linkedin-article-ai-agent-memory.md
 docs/linkedin-post-ai-agent-memory.md
+docs/local-pypi-https.md
 docs/medium-your-ai-coding-agent-has-amnesia.md
 docs/roadmap.md
 graph/_schema.yaml
@@ -36,6 +37,7 @@ mcp_server/__init__.py
 mcp_server/__main__.py
 mcp_server/auto_init.py
 mcp_server/cli.py
+mcp_server/cli_configure.py
 mcp_server/crash_logger.py
 mcp_server/detect.py
 mcp_server/gitignore.py
@@ -89,6 +91,7 @@ rules/testing-standards.md
 tests/test_auto_init.py
 tests/test_chunker.py
 tests/test_cli.py
+tests/test_cli_configure.py
 tests/test_crash_logger.py
 tests/test_detect.py
 tests/test_gitignore.py

codevira-1.8.0/docs/local-pypi-https.md

@@ -0,0 +1,184 @@
+# Local PyPI with HTTPS — for private-registry testing and IDE integration
+
+This guide sets up a **local HTTPS-secured PyPI registry** using Docker, so
+you can:
+
+- Smoke-test a release candidate by uploading to a private registry and
+  reinstalling `pipx install codevira` from it (exactly the flow a real
+  user will hit, just scoped to your machine).
+- Serve `codevira` packages to team machines or CI over HTTPS.
+- Test HTTPS-aware install flows before pushing to public PyPI.
+
+The stack is two containers on a shared docker network:
+
+```
+┌──────────────────────────┐      ┌────────────────────────────┐
+│  nginx:alpine            │      │  pypiserver/pypiserver     │
+│  :8443  (HTTPS, self-sig)│ ───▶ │  :8080  (plain HTTP)       │
+│  reverse proxy           │      │  htpasswd auth on uploads  │
+└──────────────────────────┘      └────────────────────────────┘
+```
+
+The self-signed cert is fine for local testing. For LAN/team use, replace
+it with a real cert from your own CA or Let's Encrypt via DNS-01.
+
+---
+
+## One-time setup
+
+```bash
+BASE=~/.codevira-local-pypi
+mkdir -p "$BASE/packages" "$BASE/certs"
+
+# 1. Create test credentials (replace 'testuser/testpass' for real use)
+htpasswd -cb "$BASE/htpasswd" testuser testpass
+
+# 2. Generate a self-signed cert for localhost
+openssl req -x509 -newkey rsa:4096 -nodes \
+  -keyout "$BASE/certs/key.pem" -out "$BASE/certs/cert.pem" \
+  -days 365 \
+  -subj "/CN=localhost" \
+  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
+
+# 3. Write an nginx config that reverse-proxies HTTPS:8443 → pypi:8080
+cat > "$BASE/nginx.conf" <<'CONF'
+events { worker_connections 1024; }
+http {
+  server {
+    listen 443 ssl;
+    server_name localhost;
+    ssl_certificate     /etc/nginx/certs/cert.pem;
+    ssl_certificate_key /etc/nginx/certs/key.pem;
+    client_max_body_size 50M;
+
+    location / {
+      proxy_pass http://pypi:8080;
+      proxy_set_header Host $host;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto https;
+    }
+  }
+}
+CONF
+
+# 4. Create a shared network so nginx can resolve 'pypi' by name
+docker network create codevira-pypi-net
+```
+
+## Start the stack
+
+```bash
+BASE=~/.codevira-local-pypi
+
+# pypiserver (name it 'pypi' so nginx can resolve it)
+docker run -d \
+  --name pypi \
+  --network codevira-pypi-net \
+  -p 8080:8080 \
+  -v "$BASE/packages:/data/packages" \
+  -v "$BASE/htpasswd:/data/.htpasswd:ro" \
+  pypiserver/pypiserver:latest \
+  run \
+    --passwords /data/.htpasswd \
+    --authenticate update \
+    --overwrite \
+    /data/packages
+
+# nginx HTTPS reverse proxy on 8443
+docker run -d \
+  --name codevira-pypi-nginx \
+  --network codevira-pypi-net \
+  -p 8443:443 \
+  -v "$BASE/certs:/etc/nginx/certs:ro" \
+  -v "$BASE/nginx.conf:/etc/nginx/nginx.conf:ro" \
+  nginx:alpine
+
+# Health check (the -k is OK — we know the cert is self-signed)
+curl -sk https://localhost:8443/ | head -3
+```
+
+## Publish a release to your local registry
+
+```bash
+cd /path/to/agent-mcp
+
+# 1. Build the distribution artifacts
+rm -rf dist/ build/ *.egg-info
+python3 -m build
+
+# 2. Upload via HTTPS
+TWINE_USERNAME=testuser TWINE_PASSWORD=testpass twine upload \
+  --repository-url https://localhost:8443 \
+  --cert ~/.codevira-local-pypi/certs/cert.pem \
+  dist/codevira-1.8.0-py3-none-any.whl \
+  dist/codevira-1.8.0.tar.gz
+```
+
+## Install from the local registry
+
+```bash
+pipx uninstall codevira  # remove any previous install
+
+pipx install codevira==1.8.0 \
+  --python python3.11 \
+  --index-url "https://testuser:testpass@localhost:8443/simple/" \
+  --pip-args="--trusted-host localhost --cert $HOME/.codevira-local-pypi/certs/cert.pem"
+
+# Verify
+codevira --help
+python3 -c "import mcp_server; print(mcp_server.__version__)"
+```
+
+## Cleanup
+
+Stop and remove containers + network when done:
+
+```bash
+docker rm -f codevira-pypi-nginx pypi
+docker network rm codevira-pypi-net
+# Optional — delete everything:
+rm -rf ~/.codevira-local-pypi
+```
+
+---
+
+## Common gotchas
+
+- **`--skip-existing` not supported.** `pypiserver` doesn't implement this
+  twine flag. Either delete the old wheel from `~/.codevira-local-pypi/
+  packages/` or set `--overwrite` at container start (as above) so
+  re-uploads of the same version replace the existing file.
+
+- **Self-signed cert trust.** Every client that hits the registry needs to
+  trust `~/.codevira-local-pypi/certs/cert.pem`. `twine` takes
+  `--cert <path>`, `pip` takes `--cert <path>` plus `--trusted-host
+  localhost`. For system-wide trust on macOS you can add it to the
+  Keychain, but for per-command flags it's simpler to pass `--cert` each
+  time.
+
+- **Port 8443 already in use.** Change the host port in the `-p
+  8443:443` mapping. The container-side port stays `443` (inside nginx).
+
+- **Adding `codevira` to an IDE/app that requires HTTPS.** Most MCP clients
+  (Claude Code, Cursor, Windsurf, Antigravity) use **stdio transport by
+  default**, not HTTPS — stdio needs no URL at all, just the `codevira`
+  binary path. `codevira register` sets this up for you. HTTPS transport
+  is only needed for the preview `codevira serve --https` multi-project
+  server mode (see v1.7 HTTPS-preview docs). If your client is asking for
+  an HTTPS URL, that's the serve path — different from this local-PyPI
+  guide, which covers **package distribution**.
+
+---
+
+## Why HTTP isn't enough for team/CI use
+
+Local HTTP works fine for solo smoke-testing on a single machine, but:
+
+- `pip` in modern versions warns on `--index-url http://...` and some
+  environments block plain-HTTP index URLs entirely.
+- When team members on other machines `pipx install codevira` from your
+  registry, they expect HTTPS.
+- Corporate proxies often block plain-HTTP traffic.
+
+The self-signed-cert setup above is a one-command step up from HTTP and
+gives you a realistic distribution flow without touching public PyPI.

{codevira-1.7.0 → codevira-1.8.0}/indexer/global_db.py

@@ -21,12 +21,53 @@ class GlobalDB:
     def __init__(self, db_path: str | Path):
         self.db_path = Path(db_path)
         self.db_path.parent.mkdir(parents=True, exist_ok=True)
-        self.conn = sqlite3.connect(str(self.db_path), timeout=5)
+        # 30s timeout (up from 5s): handles later-write contention under load.
+        self.conn = sqlite3.connect(str(self.db_path), timeout=30)
         self.conn.row_factory = sqlite3.Row
-        self.conn.execute("PRAGMA journal_mode=WAL")
+        # Enable WAL with retries. `PRAGMA journal_mode=WAL` requires an
+        # exclusive lock and — unlike normal SQL — does NOT honour the
+        # `busy_timeout`. When multiple threads/processes open the same fresh
+        # database file concurrently, they all race to flip the journal mode
+        # and some raise `OperationalError('database is locked')`. Skip the
+        # PRAGMA if WAL is already the effective mode, otherwise retry with
+        # short backoff. After ~1s we give up and fall through — the DB still
+        # works in the default rollback-journal mode.
+        self._enable_wal_with_retry()
         self.conn.execute("PRAGMA foreign_keys=ON")
+        # SQLite-level busy timeout for subsequent writes (complements the
+        # `timeout=30` on the connect — matters for later transactions).
+        self.conn.execute("PRAGMA busy_timeout=30000")
         self._init_schema()
 
+    def _enable_wal_with_retry(self, attempts: int = 10, initial_delay: float = 0.02) -> None:
+        """Best-effort enable of WAL journal mode.
+
+        Survives concurrent-open races by short-backoff retry and by
+        short-circuiting when WAL is already active (in which case every
+        other connection sees it too — no PRAGMA needed).
+        """
+        import time as _time
+        try:
+            mode = self.conn.execute("PRAGMA journal_mode").fetchone()[0]
+            if str(mode).lower() == "wal":
+                return  # already WAL — nothing to do
+        except sqlite3.OperationalError:
+            pass  # fall through to the retry loop
+        delay = initial_delay
+        for _ in range(attempts):
+            try:
+                self.conn.execute("PRAGMA journal_mode=WAL")
+                return
+            except sqlite3.OperationalError as e:
+                if "locked" not in str(e).lower():
+                    raise
+                _time.sleep(delay)
+                delay = min(delay * 1.5, 0.2)
+        # Last-resort: continue in the default journal mode. Non-fatal —
+        # concurrent writers are still serialized, just without WAL's
+        # reader-during-writer benefit.
+        logger.warning("Could not enable WAL on %s after retries; continuing in default mode", self.db_path)
+
     def _init_schema(self) -> None:
         self.conn.executescript("""
             CREATE TABLE IF NOT EXISTS projects (