From 4ac4b82d6287e374900ff70f958d9d548f4560a2 Mon Sep 17 00:00:00 2001 From: akadeepesh Date: Sun, 24 May 2026 01:57:38 +0530 Subject: [PATCH] feat: add AI-powered file selection with --prompt flag and onboarding flow --- CHANGELOG.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2433276..25c72ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -173,4 +173,61 @@ This project uses [Semantic Versioning](https://semver.org/). ### Fixed * Prevented `.contextzip/` contents from recursively packaging previous generated archives -* Improved fallback behaviour when workspace creation fails due to filesystem permissions or read-only directories \ No newline at end of file +* Improved fallback behaviour when workspace creation fails due to filesystem permissions or read-only directories + +## [0.3.0] — 2026-05-24 + +### Added + +* `--prompt` / `-p` flag for AI-powered file selection — describe your task in + plain English and contextzip automatically selects the minimum relevant files + (e.g. `contextzip --prompt "Change toast color on failed login"`) +* Gemini 2.5 Flash Lite integration via a thin `httpx` client — no Google SDK + required; a single lightweight POST call to the Gemini API +* First-run onboarding flow for users without an API key: + * Displays a guided panel with a link to [Google AI Studio](https://aistudio.google.com/apikey) (free, no credit card) + * Optionally opens the browser automatically + * Saves the key persistently on confirmation +* Persistent API key storage in the platform-appropriate config directory: + * `~/.config/contextzip/config.json` on Linux / macOS + * `%APPDATA%\contextzip\config.json` on Windows + * `GEMINI_API_KEY` environment variable always takes precedence +* `contextzip config` subcommand for key management: + * `contextzip config` — show current key status and source + * `contextzip config --reset-key` — clear stored key and re-run onboarding + * `contextzip config --show-key-path` — print config file location +* `prompt.txt` is written as the first entry in every AI-generated ZIP, + containing the task description, detected framework, and selected file list — + so any AI tool receiving the archive immediately knows the context +* Keyword-based heuristic file scorer as a rate-limit fallback: + * Activates only on confirmed HTTP 429 from Gemini + * Scores files by token overlap with the prompt, directory semantics, and + extension type + * User is warned clearly that heuristic was used and Gemini results are + preferred +* `--prompt --dry-run` combination — preview AI-selected files without + creating a ZIP +* API key validation on load — keys not starting with `AIza` are treated as + unconfigured and trigger onboarding rather than a cryptic API error +* `diagnose_api_key()` surfaces a human-readable explanation when a key exists + but fails validation, before any API call is attempted + +### Changed + +* `create_zip()` in `packager.py` now accepts an optional `prompt_txt` + parameter; when provided, `prompt.txt` is written as the first ZIP entry +* xdg-open on Linux now runs with stdout and stderr suppressed to prevent + KDE / DBus / MIME warnings from appearing over the API key prompt + +### Developer Notes + +* Introduced `contextzip.config` module for cross-platform config path + resolution and key read / write / delete operations +* Introduced `contextzip.ai` package with three modules: + * `gemini.py` — Gemini API client with typed exception hierarchy + (`GeminiError`, `GeminiRateLimitError`, `GeminiUnavailable`) + * `heuristic.py` — keyword + directory scoring fallback scorer + * `selector.py` — project map builder, AI orchestration, `prompt.txt` + generation; returns `(paths, prompt_txt, method)` so callers know + which selection path was taken +* Added `httpx` as a required runtime dependency