readmegen-agent 0.2.0__tar.gz

readmegen_agent-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+node_modules/
+__pycache__/
+*.py[cod]
+.env
+.env.*
+!.env.example
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+src/readmegen/web/static/
+# Previous local checkout state; never include keys or imported source in releases.
+.local/
+README.generated.md
+.playwright-mcp/

readmegen_agent-0.2.0/LICENSE

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

readmegen_agent-0.2.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: readmegen-agent
+Version: 0.2.0
+Summary: Generate evidence-based project READMEs from your terminal or browser.
+Project-URL: Homepage, https://github.com/FerjaniMedAmine/ReadMeGen
+Project-URL: Repository, https://github.com/FerjaniMedAmine/ReadMeGen
+Project-URL: Issues, https://github.com/FerjaniMedAmine/ReadMeGen/issues
+Author: Amine Ferjani
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,documentation,langgraph,llm,readme
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+Requires-Dist: filelock<4,>=3.16
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: keyring<26,>=25
+Requires-Dist: langchain-anthropic<2,>=1
+Requires-Dist: langchain-google-genai<5,>=4
+Requires-Dist: langchain-openai<2,>=1
+Requires-Dist: langchain<2,>=1.0
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: pyjwt[crypto]<3,>=2.10
+Requires-Dist: typer<1,>=0.16
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=1; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.12; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Provides-Extra: web
+Requires-Dist: fastapi<1,>=0.115; extra == 'web'
+Requires-Dist: python-multipart<1,>=0.0.20; extra == 'web'
+Requires-Dist: uvicorn<1,>=0.34; extra == 'web'
+Description-Content-Type: text/markdown
+
+# ReadMeGen
+
+**Generate a useful project README from the code you already have.**
+
+ReadMeGen inspects a local directory, ZIP archive, or public Git repository and produces a Markdown draft grounded in source-file evidence. Use your terminal or launch the bundled browser interface with one command.
+
+```bash
+readmegen generate ./my-project
+readmegen ui
+```
+
+## Features
+
+- **Source-based research:** a coordinator assigns specific files to focused research agents; a separate writer turns their findings into documentation.
+- **Two interfaces, one engine:** CLI and browser share ingestion rules, generation, settings, and provider adapters.
+- **Your connection, your model:** Gemini, OpenAI, and Anthropic API keys; an experimental ChatGPT-plan connection for eligible local installations.
+- **No project `.env` editing:** hidden key prompts, OS credential storage, session-only GUI connections, or environment variables for automation.
+- **Protected outputs:** the CLI writes `README.generated.md` and refuses to replace existing files without `--force`.
+- **Local GUI:** Python serves the compiled React app and API together. End users do not need Node.js.
+
+Review the generated draft before committing it. Selected source files are sent to the chosen provider. Filename filtering cannot guarantee detection of every embedded secret.
+
+## Install from GitHub
+
+Requires Python 3.12+. Git is needed for repository imports. Node.js 22.12+ and npm are needed only to build the GUI from source.
+
+```bash
+git clone https://github.com/FerjaniMedAmine/ReadMeGen.git
+cd ReadMeGen
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[web]'
+npm ci --prefix frontend
+python scripts/build_frontend.py
+readmegen ui
+```
+
+On Windows, activate with `.venv\Scripts\Activate.ps1`. For CLI-only installation, omit the `web` extra and frontend build.
+
+### Install a release
+
+Release wheels and source distributions include the GUI. Install a downloaded wheel with:
+
+```bash
+python -m pip install './readmegen_agent-0.2.0-py3-none-any.whl[web]'
+```
+
+Install from PyPI with `pip install 'readmegen-agent[web]'` or `pipx install 'readmegen-agent[web]'`. The terminal command and Python import package are both `readmegen`.
+
+## Choose authentication and model
+
+Run `readmegen setup`, or use the connection panel in `readmegen ui`.
+
+For an API key, choose Gemini, OpenAI, or Anthropic, enter the key, and select a model with tool-calling support. A catalog can include unsuitable models; listing does not guarantee inference access.
+
+CLI setup saves credentials in the OS credential store. In the GUI, leave **Save credentials** unchecked for session-only use. ReadMeGen never silently falls back to plaintext credential files. With provider and model configured, interactive CLI generation can prompt for a session key when none is available.
+
+For automation, supply credentials through your shell or CI secret manager:
+
+| Provider | Environment variable |
+| --- | --- |
+| Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` |
+
+```bash
+readmegen generate ./project --provider gemini --model YOUR_MODEL_ID
+```
+
+Environment keys take precedence over saved/session keys. `READMEGEN_PROVIDER` and `READMEGEN_MODEL` override saved preferences; command options override those preferences for a generation run.
+
+### Sign in with ChatGPT — experimental
+
+Choose **Continue with ChatGPT**, authorize plan usage in your browser, then select an account model. Identity sign-in alone does not authorize inference. Connections for different accounts and workspaces remain separate; usage counts toward the account's plan limits.
+
+The adapter follows OpenAI's local/open-source preview contract: loopback OAuth with PKCE, ID-token verification, token refresh, account-specific catalogs, and streamed Responses requests with `store=false`. It preserves reasoning/tool history and accepts only completed responses.
+
+OAuth and transport behavior are covered by simulated tests. **Validate live sign-in and generation with an eligible account before treating this connection as stable.** Paid or remotely hosted apps require separate onboarding. See [OpenAI's integration documentation](https://developers.openai.com/siwc/token-sharing-open-source) and [preview limitations](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations).
+
+## Usage
+
+```bash
+readmegen generate .
+readmegen generate project.zip --output docs/README.draft.md
+readmegen generate https://github.com/owner/repo
+readmegen generate . --output README.md --force
+readmegen models
+readmegen logout
+readmegen ui --no-browser --port 8080
+readmegen shell
+```
+
+In the interactive shell, `/ui` launches the GUI and prints its address. `/ui --no-browser` prints it without opening a browser; repeating `/ui` reuses the shell's server. Other commands: `/setup`, `/models`, `/generate`, `/logout`, `/help`, `/exit`.
+
+The GUI binds only to `127.0.0.1`. The default port is 8765; if occupied, the launcher selects a free port. An explicitly requested occupied port fails clearly; `--port 0` chooses a free port. Keep the terminal running. Ctrl+C or shell exit stops the server.
+
+## How it works
+
+```mermaid
+flowchart LR
+    CLI[CLI / shell] --> Service[Shared generation service]
+    UI[React GUI] --> API[FastAPI]
+    API --> Service
+    Service --> Import[Import and filter]
+    Import --> Coordinator[Coordinator]
+    Coordinator --> Readers[Scoped research agents]
+    Readers --> Writer[Evidence-based writer]
+    Writer --> Output[Markdown draft]
+```
+
+The coordinator assigns up to eight specialists, each with up to twelve unique paths. Readers access only assigned files within the project and return bounded, numbered source excerpts. The writer uses their research reports; missing essential information becomes an open question.
+
+Limits include 50 MB compressed ZIPs, 300 MB retained extracted/downloaded data, 3,000 readable files, 500 KB per source file, bounded graph recursion, and a generation timeout. ZIP traversal, symlinks, duplicate paths, and encrypted files are rejected. Git imports restrict HTTPS hosts and disable redirects, hooks, helpers, and submodules. Ingestion never executes repository code. These controls bound resources, not monetary cost: one generation may make multiple model requests.
+
+## Structure
+
+```text
+src/readmegen/
+  cli.py          CLI and interactive shell
+  config.py       Validated preferences
+  auth/           OS credentials and ChatGPT OAuth
+  providers.py    Model clients and catalogs
+  sources.py      Local, ZIP, Git ingestion
+  generation/     Coordinator, readers, writer, plan adapter
+  service.py      Shared generation use case
+  web/            Local API, persistent jobs, GUI launcher
+frontend/         React interface and API client
+tests/            Workflow, CLI, security, OAuth, API tests
+scripts/          GUI build and distribution verification
+docs/             Architecture and release instructions
+```
+
+Preferences and public registration metadata use the platform's user configuration directory. Web jobs and generated documents use the user cache directory. Imported source is temporary; uploads are removed after processing. Jobs older than seven days are removed when the server next starts. `READMEGEN_HOME` overrides these locations for isolated development/testing.
+
+## Development and checks
+
+```bash
+python -m pip install -e '.[web,dev]'
+npm ci --prefix frontend
+ruff check src tests scripts
+ruff format --check src tests scripts
+pytest --cov=readmegen --cov-report=term-missing
+npm run lint --prefix frontend
+npm test --prefix frontend
+python scripts/build_frontend.py
+python -m build
+twine check dist/*
+python scripts/check_distribution.py dist
+```
+
+For frontend development, run `readmegen ui --no-browser --port 8765` and `npm run dev --prefix frontend`. Vite proxies `/api` to Python. Rebuild bundled assets after changes; end-user installations never start Vite.
+
+CI tests Python 3.12–3.14, lints both interfaces, audits npm dependencies, verifies distributions, and installs a wheel outside the checkout. Tests use simulated models and credentials and need no paid inference.
+
+Read [architecture and tradeoffs](docs/architecture.md) and [release instructions](docs/releasing.md). Licensed under [MIT](LICENSE).

readmegen_agent-0.2.0/README.md

@@ -0,0 +1,155 @@
+# ReadMeGen
+
+**Generate a useful project README from the code you already have.**
+
+ReadMeGen inspects a local directory, ZIP archive, or public Git repository and produces a Markdown draft grounded in source-file evidence. Use your terminal or launch the bundled browser interface with one command.
+
+```bash
+readmegen generate ./my-project
+readmegen ui
+```
+
+## Features
+
+- **Source-based research:** a coordinator assigns specific files to focused research agents; a separate writer turns their findings into documentation.
+- **Two interfaces, one engine:** CLI and browser share ingestion rules, generation, settings, and provider adapters.
+- **Your connection, your model:** Gemini, OpenAI, and Anthropic API keys; an experimental ChatGPT-plan connection for eligible local installations.
+- **No project `.env` editing:** hidden key prompts, OS credential storage, session-only GUI connections, or environment variables for automation.
+- **Protected outputs:** the CLI writes `README.generated.md` and refuses to replace existing files without `--force`.
+- **Local GUI:** Python serves the compiled React app and API together. End users do not need Node.js.
+
+Review the generated draft before committing it. Selected source files are sent to the chosen provider. Filename filtering cannot guarantee detection of every embedded secret.
+
+## Install from GitHub
+
+Requires Python 3.12+. Git is needed for repository imports. Node.js 22.12+ and npm are needed only to build the GUI from source.
+
+```bash
+git clone https://github.com/FerjaniMedAmine/ReadMeGen.git
+cd ReadMeGen
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[web]'
+npm ci --prefix frontend
+python scripts/build_frontend.py
+readmegen ui
+```
+
+On Windows, activate with `.venv\Scripts\Activate.ps1`. For CLI-only installation, omit the `web` extra and frontend build.
+
+### Install a release
+
+Release wheels and source distributions include the GUI. Install a downloaded wheel with:
+
+```bash
+python -m pip install './readmegen_agent-0.2.0-py3-none-any.whl[web]'
+```
+
+Install from PyPI with `pip install 'readmegen-agent[web]'` or `pipx install 'readmegen-agent[web]'`. The terminal command and Python import package are both `readmegen`.
+
+## Choose authentication and model
+
+Run `readmegen setup`, or use the connection panel in `readmegen ui`.
+
+For an API key, choose Gemini, OpenAI, or Anthropic, enter the key, and select a model with tool-calling support. A catalog can include unsuitable models; listing does not guarantee inference access.
+
+CLI setup saves credentials in the OS credential store. In the GUI, leave **Save credentials** unchecked for session-only use. ReadMeGen never silently falls back to plaintext credential files. With provider and model configured, interactive CLI generation can prompt for a session key when none is available.
+
+For automation, supply credentials through your shell or CI secret manager:
+
+| Provider | Environment variable |
+| --- | --- |
+| Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` |
+
+```bash
+readmegen generate ./project --provider gemini --model YOUR_MODEL_ID
+```
+
+Environment keys take precedence over saved/session keys. `READMEGEN_PROVIDER` and `READMEGEN_MODEL` override saved preferences; command options override those preferences for a generation run.
+
+### Sign in with ChatGPT — experimental
+
+Choose **Continue with ChatGPT**, authorize plan usage in your browser, then select an account model. Identity sign-in alone does not authorize inference. Connections for different accounts and workspaces remain separate; usage counts toward the account's plan limits.
+
+The adapter follows OpenAI's local/open-source preview contract: loopback OAuth with PKCE, ID-token verification, token refresh, account-specific catalogs, and streamed Responses requests with `store=false`. It preserves reasoning/tool history and accepts only completed responses.
+
+OAuth and transport behavior are covered by simulated tests. **Validate live sign-in and generation with an eligible account before treating this connection as stable.** Paid or remotely hosted apps require separate onboarding. See [OpenAI's integration documentation](https://developers.openai.com/siwc/token-sharing-open-source) and [preview limitations](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations).
+
+## Usage
+
+```bash
+readmegen generate .
+readmegen generate project.zip --output docs/README.draft.md
+readmegen generate https://github.com/owner/repo
+readmegen generate . --output README.md --force
+readmegen models
+readmegen logout
+readmegen ui --no-browser --port 8080
+readmegen shell
+```
+
+In the interactive shell, `/ui` launches the GUI and prints its address. `/ui --no-browser` prints it without opening a browser; repeating `/ui` reuses the shell's server. Other commands: `/setup`, `/models`, `/generate`, `/logout`, `/help`, `/exit`.
+
+The GUI binds only to `127.0.0.1`. The default port is 8765; if occupied, the launcher selects a free port. An explicitly requested occupied port fails clearly; `--port 0` chooses a free port. Keep the terminal running. Ctrl+C or shell exit stops the server.
+
+## How it works
+
+```mermaid
+flowchart LR
+    CLI[CLI / shell] --> Service[Shared generation service]
+    UI[React GUI] --> API[FastAPI]
+    API --> Service
+    Service --> Import[Import and filter]
+    Import --> Coordinator[Coordinator]
+    Coordinator --> Readers[Scoped research agents]
+    Readers --> Writer[Evidence-based writer]
+    Writer --> Output[Markdown draft]
+```
+
+The coordinator assigns up to eight specialists, each with up to twelve unique paths. Readers access only assigned files within the project and return bounded, numbered source excerpts. The writer uses their research reports; missing essential information becomes an open question.
+
+Limits include 50 MB compressed ZIPs, 300 MB retained extracted/downloaded data, 3,000 readable files, 500 KB per source file, bounded graph recursion, and a generation timeout. ZIP traversal, symlinks, duplicate paths, and encrypted files are rejected. Git imports restrict HTTPS hosts and disable redirects, hooks, helpers, and submodules. Ingestion never executes repository code. These controls bound resources, not monetary cost: one generation may make multiple model requests.
+
+## Structure
+
+```text
+src/readmegen/
+  cli.py          CLI and interactive shell
+  config.py       Validated preferences
+  auth/           OS credentials and ChatGPT OAuth
+  providers.py    Model clients and catalogs
+  sources.py      Local, ZIP, Git ingestion
+  generation/     Coordinator, readers, writer, plan adapter
+  service.py      Shared generation use case
+  web/            Local API, persistent jobs, GUI launcher
+frontend/         React interface and API client
+tests/            Workflow, CLI, security, OAuth, API tests
+scripts/          GUI build and distribution verification
+docs/             Architecture and release instructions
+```
+
+Preferences and public registration metadata use the platform's user configuration directory. Web jobs and generated documents use the user cache directory. Imported source is temporary; uploads are removed after processing. Jobs older than seven days are removed when the server next starts. `READMEGEN_HOME` overrides these locations for isolated development/testing.
+
+## Development and checks
+
+```bash
+python -m pip install -e '.[web,dev]'
+npm ci --prefix frontend
+ruff check src tests scripts
+ruff format --check src tests scripts
+pytest --cov=readmegen --cov-report=term-missing
+npm run lint --prefix frontend
+npm test --prefix frontend
+python scripts/build_frontend.py
+python -m build
+twine check dist/*
+python scripts/check_distribution.py dist
+```
+
+For frontend development, run `readmegen ui --no-browser --port 8765` and `npm run dev --prefix frontend`. Vite proxies `/api` to Python. Rebuild bundled assets after changes; end-user installations never start Vite.
+
+CI tests Python 3.12–3.14, lints both interfaces, audits npm dependencies, verifies distributions, and installs a wheel outside the checkout. Tests use simulated models and credentials and need no paid inference.
+
+Read [architecture and tradeoffs](docs/architecture.md) and [release instructions](docs/releasing.md). Licensed under [MIT](LICENSE).

readmegen_agent-0.2.0/docs/architecture.md

@@ -0,0 +1,35 @@
+# Architecture and tradeoffs
+
+ReadMeGen is a local developer tool. CLI and HTTP are adapters over `service.generate`, which owns model construction, source preparation, filtering, generation timeout, and temporary-file cleanup. Imports raise application errors; FastAPI translates them at the boundary.
+
+## Boundaries
+
+- `config` stores validated preferences; importing it creates no directories.
+- `auth` owns secrets and OAuth. Browser responses contain public connection metadata, never tokens. The OS store is optional; session credentials remain in memory.
+- `sources` reads local input without copying or executing it. ZIP and Git inputs are isolated in temporary workspaces.
+- `generation` owns prompts and scoped tools. Models are injected rather than constructed inside agents.
+- `web` owns persistent job status and the loopback server, using the same generation service as the CLI.
+
+SQLite preserves job metadata and completed results across restart. Interrupted jobs become failed jobs and are not rerun or charged automatically. One generation is accepted at a time rather than accumulating an unbounded queue. Preferences are snapshotted at submission; connection changes are blocked during generation.
+
+## Resource and trust controls
+
+ZIP entries are validated before extraction. Dependency/credential files are excluded, duplicates rejected, and bytes counted during extraction. Git runs without shell interpolation, hooks, redirects, credential helpers, or submodules. Download checks are periodic: transient disk use can exceed the threshold before termination. This is not a hardened multi-tenant importer.
+
+Traversal prunes dependencies and does not follow symlinks. Readers check containment at access and bound file size and output chunks. Source and model reports remain untrusted; prompt wording and filename filtering cannot eliminate prompt injection or embedded secrets. Review the generated document before use.
+
+Provider timeouts, retries, graph recursion, specialist/file limits, and an overall generation timeout bound work; there is no exact spending cap. Cancelled filesystem threads are joined before temporary-file cleanup. Git subprocesses are terminated and awaited.
+
+## Local HTTP interface
+
+The launcher binds to `127.0.0.1`, uses one worker, rejects untrusted Host headers and cross-site API requests, and disables proxy-header trust. Validation errors omit submitted values. Frontend and API share an origin. The content security policy restricts scripts/network access and framing. Access logs are disabled to avoid recording sensitive authorization material.
+
+Hosted user isolation, team permissions, internet-facing authentication, durable job scheduling, and billing would require separate architecture.
+
+## Provider compatibility
+
+API-key providers use their LangChain integrations and require tool-capable models. A catalog is useful for selection, not proof of access or compatibility. Reasoning-model defaults are preserved where generic sampling settings are rejected.
+
+The ChatGPT-plan adapter is separate because the preview Responses contract differs from API-key requests. It groups tools into a namespace, uses streaming with `store=false`, replays original reasoning/tool items, serializes refreshes with a cross-process lock, and rejects incomplete streams. Identity verification checks signature, issuer, audience, expiry, and nonce. Client/workspace registrations remain distinct; email is a display label.
+
+Live account eligibility, access, rotation, and usage-limit behavior must be verified before a stable release claim. Automated tests use controlled provider responses.

readmegen_agent-0.2.0/docs/release-notes-0.2.0.md

@@ -0,0 +1,28 @@
+# ReadMeGen 0.2.0 beta
+
+Generate source-based README drafts from a local directory, ZIP archive, or public Git repository using the CLI or bundled local browser interface.
+
+- Shared Python generation engine for terminal and browser use.
+- Gemini, OpenAI, and Anthropic API-key connections, with OS credential storage or session-only connections.
+- Experimental ChatGPT-plan connection.
+- Scoped research agents, protected output files, and bounded source ingestion.
+- Bundled GUI in the wheel and source distribution; Node.js is only needed when building from source.
+
+## Validation
+
+The release candidate passed 60 Python tests on Python 3.12/Linux, with 76% coverage. Python and frontend lint checks, frontend tests, GUI build, wheel and source distribution checks, and installation into a fresh environment passed. The installed GUI served its HTML, assets, and health API and shut down cleanly. Dependency audits of the development environment and frontend reported no known vulnerabilities on 2026-10-13.
+
+GitHub CI passed on Python 3.12–3.14 for commit `6f20402`. The PyPI distribution name is `readmegen-agent`; the CLI and import package remain `readmegen`. TestPyPI installation was not performed. Real provider generation, credential persistence/restart, and live ChatGPT sign-in have not been validated in this release session. ChatGPT support remains experimental. Windows and macOS were not tested in this session.
+
+## Installation
+
+After successful PyPI publication:
+
+```bash
+python -m pip install 'readmegen-agent[web]'
+readmegen setup
+readmegen generate ./my-project
+readmegen ui
+```
+
+Python 3.12 or later is required. Git is required for repository URL imports. Review generated drafts before committing them; selected source files are sent to the configured provider.

readmegen_agent-0.2.0/docs/releasing.md

@@ -0,0 +1,48 @@
+# Releasing
+
+GitHub and Python distributions share one version. Wheels and source distributions include built GUI assets; Node.js is needed to build them, not to run them.
+
+## Maintainer setup
+
+1. Use `readmegen-agent` as the PyPI distribution name. The CLI and import package remain `readmegen`; PyPI rejected `readmegen` because it is too similar to an existing project.
+2. Configure a PyPI Trusted Publisher for `FerjaniMedAmine/ReadMeGen`, workflow `publish.yml`, environment `pypi`.
+   Configure a separate pending publisher on TestPyPI using the same repository and workflow, with environment `testpypi`.
+3. Require a reviewer on GitHub's `pypi` environment so publishing has a final human approval step.
+4. Validate sign-in, model selection, generation, logout, and restart against real providers and an eligible ChatGPT account. Record tested models in release notes without credentials or private source.
+
+Production publication runs when a GitHub release is published. A manual run of the **Publish** workflow builds, tests, installs, and uploads the package to TestPyPI. Adding or pushing source does not publish a package. See [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/).
+
+## Build and review
+
+Update versions in `pyproject.toml` and `frontend/package.json`, refresh lockfiles, and run CI checks. Then:
+
+```bash
+npm ci --prefix frontend
+python scripts/build_frontend.py
+python -m build
+twine check dist/*
+python scripts/check_distribution.py dist
+```
+
+Check that neither archive includes local keys, imported projects, virtual environments, or Node modules. The GUI must include `readmegen/web/static/index.html` and its referenced assets.
+
+Install the wheel in a fresh environment, change outside the checkout, and verify help, version, and `readmegen ui --no-browser`. Verify that CLI-only installations give clear GUI dependency instructions.
+
+Create `v<project-version>` only after verification. Publication validates the tag, builds and tests before obtaining PyPI credentials, and uses OIDC rather than a long-lived PyPI token. Trial a first release against TestPyPI before production publication.
+
+## First publication
+
+1. Push the release candidate and wait for every CI job, including Python 3.12–3.14, to pass.
+2. In GitHub Actions, select **Publish**, then **Run workflow** on the verified branch. This targets TestPyPI only.
+3. In a fresh environment, install the locally built wheel with its `web` extra to obtain dependencies from PyPI, then reinstall the trial package without resolving dependencies:
+
+   ```bash
+   python -m pip install './dist/readmegen_agent-0.2.0-py3-none-any.whl[web]'
+   python -m pip install --force-reinstall --no-deps --index-url https://test.pypi.org/simple/ readmegen-agent==0.2.0
+   readmegen --version
+   readmegen ui --no-browser
+   ```
+
+4. Record live provider validation and any remaining limitations in release notes.
+5. Publish the GitHub release `v0.2.0`; select **pre-release** for the initial beta. The workflow uploads to PyPI after the `pypi` environment approval and attaches the wheel and source archive to the GitHub release.
+6. Check both publishing jobs and verify `python -m pip install 'readmegen-agent[web]'` from PyPI in a fresh environment before announcing availability. If a version was already uploaded manually, publish a new version through the workflow; PyPI does not allow reusing uploaded files.

readmegen_agent-0.2.0/frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

readmegen_agent-0.2.0/frontend/eslint.config.js

@@ -0,0 +1,38 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import react from 'eslint-plugin-react'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+
+export default [
+  { ignores: ['dist'] },
+  {
+    files: ['**/*.{js,jsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        ecmaFeatures: { jsx: true },
+        sourceType: 'module',
+      },
+    },
+    settings: { react: { version: '18.3' } },
+    plugins: {
+      react,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...react.configs.recommended.rules,
+      ...react.configs['jsx-runtime'].rules,
+      ...reactHooks.configs.recommended.rules,
+      'react/jsx-no-target-blank': 'off',
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+    },
+  },
+]

readmegen_agent-0.2.0/frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/readmegen.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ReadMeGen — Project README Generator</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>