quilchoom 0.1.0__tar.gz

quilchoom-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Janitha Manatunga
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

quilchoom-0.1.0/PKG-INFO

@@ -0,0 +1,395 @@
+Metadata-Version: 2.4
+Name: quilchoom
+Version: 0.1.0
+Summary: Turn development history into traceable project knowledge and documentation.
+Keywords: developer-tools,documentation,git,knowledge-management,llm,project-documentation
+Author: Janitha Manatunga
+Author-email: Janitha Manatunga <janithamanatunga@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Dist: alembic>=1.20.0
+Requires-Dist: openai>=3.24.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: rich>=15.0.0
+Requires-Dist: sqlalchemy>=2.1.1
+Requires-Dist: typer>=0.27.2
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/manatunga/quilchoom
+Project-URL: Repository, https://github.com/manatunga/quilchoom
+Project-URL: Issues, https://github.com/manatunga/quilchoom/issues
+Description-Content-Type: text/markdown
+
+# Quilchoom
+
+**THE STORY BEHIND YOUR CODE**
+
+Quilchoom is an open-source developer tool that turns your development history into traceable project knowledge and useful documentation.
+
+[![PyPI](https://img.shields.io/pypi/v/quilchoom)](https://pypi.org/project/quilchoom/)
+[![Python](https://img.shields.io/pypi/pyversions/quilchoom)](https://pypi.org/project/quilchoom/)
+[![CI](https://github.com/manatunga/quilchoom/actions/workflows/ci.yml/badge.svg)](https://github.com/manatunga/quilchoom/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/manatunga/quilchoom/graph/badge.svg)](https://codecov.io/gh/manatunga/quilchoom)
+[![License](https://img.shields.io/github/license/manatunga/quilchoom)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+![Quilchoom CLI demonstrating the capture, distill, and scribe workflow](docs/assets/quilchoom-demo.png)
+
+## Highlights
+
+- **Development history as evidence** — Capture Git activity as structured development evidence instead of treating repository history as disposable context.
+- **Traceable project knowledge** — Distill development evidence into knowledge claims that remain connected to the evidence behind them.
+- **Evidence-backed documentation** — Generate documentation from accumulated project knowledge rather than relying on the current source tree alone.
+- **Versioned and stale-aware** — Preserve generated document versions and identify when their underlying knowledge is no longer current.
+- **Local-first** — Keep Quilchoom's project state and development knowledge in a local `.quilchoom/` workspace.
+- **Bring your own API key** — Use your own AI-provider credentials without storing API keys in project configuration.
+
+<br>
+
+## How it works
+
+Quilchoom builds documentation through a traceable pipeline from development activity to generated artifacts:
+
+```
+Development activity
+        │
+        ▼
+      Capture
+        │
+        ▼
+Evidence ──► Reconstructed history
+        │
+        ▼
+      Distill
+        │
+        ▼
+ Project knowledge
+        │
+        ▼
+      Scribe
+        │
+        ▼
+   Documentation
+```
+
+**Capture** records development activity as structured evidence. In *v0.1*, that activity comes from Git commits.
+
+**History** reconstructs captured evidence into a readable view of how the project developed.
+
+**Distill** interprets new evidence into project knowledge. Knowledge claims remain linked to the evidence used to derive them, keeping interpretation traceable.
+
+**Scribe** generates documentation from active project knowledge and preserves the knowledge claims used for each generated version.
+
+In *v0.1*, Git is the first development activity source and README generation is the first supported documentation workflow.
+
+<br>
+
+## Installation
+
+Quilchoom requires **Python 3.14 or later** and **Git**.
+
+Install it as an isolated command-line tool with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install quilchoom
+```
+
+Or with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install quilchoom
+```
+
+Verify the installation:
+
+```bash
+quilchoom --version
+```
+
+Both `quilchoom` and the shorter `qlchm` command are installed:
+
+```bash
+quilchoom --help
+qlchm --help
+```
+
+AI-backed operations require an OpenAI API key. Quilchoom uses your own provider credentials; configuration is covered below.
+
+<br>
+
+## Quick start
+
+Navigate to the Git repository you want Quilchoom to track, then follow the workflow below.
+
+### 1. Initialize the workspace — `quilchoom init`
+
+Initialize Quilchoom in the current Git repository:
+
+```bash
+# Initialize Quilchoom for the current Git repository
+quilchoom init
+```
+
+This creates the local .quilchoom/ workspace, configuration, and project state.
+
+### 2. Capture development activity — `quilchoom capture`
+
+Capture Git development activity that Quilchoom has not seen yet:
+
+```bash
+# Capture new Git development activity
+quilchoom capture
+```
+
+Captured commits become development events and evidence that Quilchoom can reconstruct and interpret. Running `capture` again only captures development activity Quilchoom has not already recorded.
+
+
+### 3. Inspect the history — `quilchoom log`
+
+View the development history reconstructed from captured evidence:
+
+```bash
+# Show captured development history
+quilchoom log
+
+# Show at most 10 history entries (-n/--limit)
+quilchoom log --limit 10
+```
+
+Inspecting the history is optional, but it lets you see what Quilchoom has captured before interpretation.
+
+### 4. Configure your API key
+
+AI-backed operations use your own OpenAI API credentials.
+
+**Linux / macOS**
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+```
+
+**Windows PowerShell**
+
+```powershell
+$env:OPENAI_API_KEY="your-api-key"
+```
+
+The API key is read from the environment and is not stored in `.quilchoom/config.toml`.
+
+### 5. Distill project knowledge — `quilchoom distill`
+
+Interpret new development evidence into traceable project knowledge:
+
+```bash
+# Distill newly captured evidence
+quilchoom distill
+```
+
+Knowledge claims remain connected to the evidence used to derive them. Running `distill` again processes new evidence rather than reinterpreting development activity that has already been distilled.
+
+### 6. Generate documentation — `quilchoom scribe generate readme`
+
+Generate a README from the project's active knowledge:
+
+```bash
+# Generate a README from active project knowledge
+quilchoom scribe generate readme
+```
+
+Quilchoom stores the generated README as a version rather than immediately overwriting your repository's `README.md`. Generating again creates a new document version.
+
+### 7. View generated documentation — `quilchoom scribe show readme`
+
+Print the latest generated README directly to the terminal:
+
+```bash
+# Show the latest generated README
+quilchoom scribe show readme
+
+# Show a specific generated version (-V/--version)
+quilchoom scribe show readme --version 1
+```
+
+### 8. Export generated documentation — `quilchoom scribe export readme`
+
+Export a generated README to the filesystem:
+
+```bash
+# Export the latest version
+quilchoom scribe export readme README.md
+
+# Export a specific version (-V/--version)
+quilchoom scribe export readme README.md --version 1
+
+# Overwrite an existing destination without prompting (-f/--force)
+quilchoom scribe export readme README.md --force
+```
+
+Without `--force`, Quilchoom prompts before overwriting an existing destination when running interactively.
+
+### 9. Check project status — `quilchoom status`
+
+Inspect the current state of the Quilchoom workflow:
+
+```bash
+# Show the current project workflow status
+quilchoom status
+```
+
+`status` summarizes captured and pending development activity, project knowledge, and generated documentation so you can see what needs attention next.
+
+### Debugging
+
+Quilchoom handles expected errors with concise CLI messages by default. When diagnosing an unexpected failure, enable debug mode globally:
+
+```bash
+# Show the underlying exception and traceback
+quilchoom --debug distill
+
+# Debug document generation
+quilchoom --debug scribe generate readme
+```
+
+`--debug` is a global option and must appear before the command.
+
+<br>
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `quilchoom init` | Initialize Quilchoom for the current Git repository. |
+| `quilchoom capture` | Capture new Git development activity. |
+| `quilchoom log` | Show reconstructed development history. |
+| `quilchoom distill` | Distill new evidence into traceable project knowledge. |
+| `quilchoom status` | Show the current project workflow status. |
+| `quilchoom scribe generate readme` | Generate a README from active project knowledge. |
+| `quilchoom scribe show readme` | Print a generated README to the terminal. |
+| `quilchoom scribe export readme PATH` | Export a generated README to a filesystem path. |
+
+`qlchm` is available as a shorthand for `quilchoom`, so any command can also be written using the shorter form:
+
+```bash
+qlchm capture
+qlchm distill
+qlchm scribe generate readme
+```
+
+For the complete command interface:
+
+```bash
+# Show all commands and global options
+quilchoom --help
+
+# Show options for a specific command
+quilchoom log --help
+
+# Show options for a nested command
+quilchoom scribe export readme --help
+```
+
+<br>
+
+## Traceability by design
+
+Quilchoom is built around a simple principle: generated documentation should have a traceable basis in the development activity that produced the project.
+
+### Evidence before interpretation
+
+Development activity is captured as evidence before it becomes project knowledge. Quilchoom keeps the original evidence separate from the interpretations derived from it.
+
+### Knowledge linked to its sources
+
+Knowledge claims retain references to the evidence used to derive them. Quilchoom distinguishes observations from inferences rather than treating inferred developer intent as established fact.
+
+### Documentation linked to knowledge
+
+Generated document versions retain the knowledge claims used to produce them, creating a traceable path:
+
+```text
+Development activity → Evidence → Project knowledge → Documentation
+```
+
+### Versioned and stale-aware
+
+Generated documentation is versioned rather than silently replaced. If knowledge referenced by a generated document is later corrected or invalidated, Quilchoom can identify that document as stale.
+
+### Local-first
+
+Quilchoom stores project state locally in `.quilchoom/`. Project knowledge, evidence, document history, and configuration remain part of the local Quilchoom workspace.
+
+API credentials are kept outside that workspace and supplied through the environment.
+
+<br>
+
+## Configuration
+
+Quilchoom stores project configuration in `.quilchoom/config.toml`.
+
+Quilchoom v0.1 supports OpenAI for knowledge interpretation and document generation. A default configuration looks like:
+
+```toml
+[ai]
+provider = "openai"
+model = "gpt-5.4-mini"
+```
+
+The model can be changed by editing the `model` value.
+
+### API credentials
+
+Credentials are supplied through the environment rather than stored in project configuration.
+
+**Linux / macOS**
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+```
+
+**Windows PowerShell**
+
+```powershell
+$env:OPENAI_API_KEY="your-api-key"
+```
+
+Quilchoom does not write your OpenAI API key to `.quilchoom/config.toml` or its local database.
+
+### Bring your own API key
+
+Quilchoom Core does not impose its own AI generation quota. AI requests use your configured provider credentials, so usage and associated costs are determined by your provider and selected model.
+
+<br>
+
+## Project status
+
+Quilchoom is currently in **Alpha**. Version **0.1.0** is the first public release and establishes the complete core workflow from Git development activity to traceable project knowledge and generated README documentation.
+
+### Where Quilchoom is heading
+
+README generation is the starting point, not the boundary of Quilchoom's documentation model.
+
+The broader direction for Quilchoom Core is to turn accumulated project knowledge into more forms of repository documentation, such as ADRs, changelogs, contributing guides, and architecture documentation, while preserving the same evidence and traceability principles.
+
+Quilchoom is early-stage software. Commands, configuration, interfaces, and internal architecture may evolve as the project gains real-world usage and feedback.
+
+<br>
+
+## Contributing
+
+Quilchoom is open source and early in its development. Contributions, bug reports, feature ideas, and documentation improvements are welcome.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.
+
+<br>
+
+## License
+
+Quilchoom Core is licensed under the [Apache License 2.0](LICENSE).