@eldrforge/kodrdriv 0.0.1

package/.gitcarve/config.yaml

@@ -0,0 +1,11 @@
+verbose: false
+model: gpt-4o
+contextDirectories:
+  - .kodrdriv/context/people
+  - .kodrdriv/context/projects
+commit:
+  cached: true
+  sendit: true
+release:
+  from: main
+  to: HEAD

package/.gitcarve/context/people/context.md

@@ -0,0 +1,5 @@
+## People
+
+The following sections contain information about people who have contributed to this project.
+
+Calen Varek is the creator of this project.

package/.gitcarve/context/projects/context.md

@@ -0,0 +1,3 @@
+## Projects
+
+The following sections contain information about projects that are related to KodrDriv

package/.gitcarve/instructions/INACTIVE-release-pre.md

@@ -0,0 +1 @@
+Everything in a release note should be in pirate speak.

package/LICENSE

@@ -0,0 +1,190 @@
+                                 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
+
+   Copyright 2025 Calen Varek
+
+   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.

package/README.md

@@ -0,0 +1,337 @@
+# KodrDriv
+
+KodrDriv is a powerful utility designed to automatically generate intelligent release notes and change logs from your Git repository. It analyzes commit history, pull requests, and related metadata to create comprehensive, well-structured documentation of your project's evolution. By leveraging advanced parsing and analysis techniques, it helps teams maintain clear visibility into their codebase's development history while reducing the manual effort typically required for changelog maintenance.
+
+## Installation
+
+Install KodrDriv globally using npm:
+
+```bash
+npm install -g @eldrforge/kodrdriv
+```
+
+This will make the `kodrdriv` command available globally on your system.
+
+## Commands
+
+KodrDriv provides two main commands:
+
+### Commit Command
+
+Generate intelligent commit messages:
+
+```bash
+kodrdriv commit
+```
+
+> [!TIP]
+> ### Working with Staged Changes
+> 
+> When you have staged changes using `git add`, the `kodrdriv commit` command will automatically analyze the diff of your staged changes. This allows you to selectively stage files and generate a commit message that specifically addresses those changes, rather than all uncommitted changes in your working directory.
+
+> [!TIP]
+> ### Quick Commit with --sendit
+> 
+> If you trust the quality of the generated commit messages, you can use the `--sendit` flag to automatically commit your changes with the generated message without review. This is useful for quick, routine changes where you want to streamline your workflow.
+
+
+### Release Command
+
+Generate comprehensive release notes based on changes since the last release:
+
+```bash
+kodrdriv release
+```
+
+> [!TIP]
+> ### Custom Release Range
+> 
+> The `kodrdriv release` command supports customizing the range of commits to analyze using the `--from` and `--to` options. By default, it compares changes between the `main` branch and `HEAD`, but you can specify any valid Git reference (branch, tag, or commit hash) for either endpoint. This flexibility allows you to generate release notes for specific version ranges or between different branches.
+
+> [!TIP]
+> ### Comparing Releases
+> 
+> You can use the `--from` and `--to` options to generate release notes comparing two different releases. For example, to see what changed between v1.0.0 and v1.1.0, you could use `kodrdriv release --from v1.0.0 --to v1.1.0`. This is particularly useful for creating detailed changelogs when preparing release documentation.
+
+## Command Line Options
+
+KodrDriv provides several command line options to customize its behavior:
+
+### Basic Options
+
+- `--dry-run`: Perform a dry run without saving files (default: false)
+- `--verbose`: Enable verbose logging (default: false)
+- `--debug`: Enable debug logging (default: false)
+- `--version`: Display version information
+
+### Commit Command Options
+
+- `--cached`: Use cached diff for generating commit messages
+- `--sendit`: Commit with the generated message without review (default: false)
+
+### OpenAI Configuration
+
+- `--openai-api-key <key>`: OpenAI API key (can also be set via OPENAI_API_KEY environment variable)
+- `--model <model>`: OpenAI model to use (default: 'gpt-4o-mini')
+
+> [!NOTE]
+> ### Security Considerations
+> 
+> The OpenAI API key should be handled securely. While the `--openai-api-key` option is available, it's recommended to use environment variables instead. Git Intelligent Change automatically loads environment variables from a `.env` file in your current working directory.
+> 
+> While environment variables are a common approach for configuration, they can still pose security risks if not properly managed. We strongly encourage users to utilize secure credential management solutions like 1Password, HashiCorp Vault, or other keystores to protect sensitive information. This helps prevent accidental exposure of API keys and other credentials in logs, process listings, or environment dumps.
+
+### Content Configuration
+
+- `-c, --content-types [types...]`: Content types to include in the summary (default: ['diff'])
+  - Available types: 'log', 'diff'
+  - Can specify multiple types: `--content-types log diff`
+
+### Instructions
+
+- `-i, --instructions <file>`: Path to custom instructions file for the AI (default: './.kodrdriv/instructions.md')
+
+### Examples
+
+Basic usage with default settings:
+```bash
+kodrdriv commit
+```
+
+Generate a commit message and automatically commit it:
+```bash
+kodrdriv commit --sendit
+```
+
+Generate release notes:
+```bash
+kodrdriv release
+```
+
+Generate a summary including both git log and diff information:
+```bash
+kodrdriv release --content-types log diff
+```
+
+Run in verbose mode with a custom OpenAI model:
+```bash
+kodrdriv commit --verbose --model gpt-4
+```
+
+Use custom instructions from a file:
+```bash
+kodrdriv release --instructions ./my-custom-instructions.md
+```
+
+### Configuration Directory
+
+KodrDriv uses a configuration directory to store custom settings, instructions, and other configuration files. You can specify a custom location using the `--config-dir` option:
+
+```bash
+kodrdriv --config-dir ~/custom-kodrdriv-config
+```
+
+By default, the configuration directory is set to `.kodrdriv` in your current working directory. This directory is created automatically if it doesn't exist.
+
+The configuration directory structure is as follows:
+
+```
+.kodrdriv/
+├── instructions/
+│   ├── commit.md         # Override for commit instructions
+│   ├── commit-pre.md     # Content prepended to default commit instructions
+│   ├── commit-post.md    # Content appended to default commit instructions
+│   ├── release.md        # Override for release instructions
+│   ├── release-pre.md    # Content prepended to default release instructions
+│   └── release-post.md   # Content appended to default release instructions
+└── ...                   # Other configuration files
+```
+
+## Default Instructions
+
+KodrDriv comes with default instructions that guide the AI in generating release notes or change logs. These instructions are defined in the source code:
+
+- **Commit Instructions**: The default instructions for commit message generation are defined in [src/prompt/instructions/commit.ts](https://github.com/eldrforge/kodrdriv/blob/main/src/prompt/instructions/commit.ts).
+
+- **Release Instructions**: The default instructions for release notes generation are defined in [src/prompt/instructions/release.ts](https://github.com/eldrforge/kodrdriv/blob/main/src/prompt/instructions/release.ts).
+
+These instruction files contain detailed guidelines for the AI on how to format and structure the output, including examples and specific requirements for different types of changes.
+
+### Customizing Instructions
+
+You can override these default instructions in several ways:
+
+1. **Command Line Option**: Use the `--instructions` flag to specify a custom instructions file:
+   ```bash
+   kodrdriv --instructions ./my-custom-instructions.txt
+   ```
+
+2. **Default Location**: Even without specifying a command line option, Git Intelligent Change will automatically look for an instructions file at `./.kodrdriv/instructions.md` in your current working directory.
+
+3. **File Format**: While the default file is named `instructions.md`, you can use any text file with any extension. The content doesn't have to be in Markdown format - any plain text content will work. This gives you flexibility to use your preferred text editor or format for writing instructions.
+
+## Prompt Structure
+
+When KodrDriv sends a request to the LLM, it structures the prompt using XML-like tags to organize different components of the input. The prompt is composed of three main sections:
+
+```
+<instructions>
+[Your custom instructions or the default instructions]
+</instructions>
+
+<log>
+[Git log output if --content-types includes 'log']
+</log>
+
+<diff>
+[Git diff output if --content-types includes 'diff']
+</diff>
+```
+
+Each section serves a specific purpose:
+- `<instructions>`: Contains the guidance for the LLM on how to format and structure the output
+- `<log>`: Contains the git log output, providing commit history and messages
+- `<diff>`: Contains the git diff output, showing the actual code changes
+
+## Context
+
+KodrDriv can use contextual information about your project to generate more meaningful commit messages and release notes. Context is provided through Markdown files stored in a dedicated directory.
+
+### Context Directory Structure
+
+The structure of your context directory is entirely up to you. There are no strict requirements for how you organize your context files - you can structure them in whatever way makes the most sense for your project and team.
+
+Here are two example approaches to organizing context files:
+
+#### Hierarchical Structure Example
+
+You can organize context in a hierarchical structure with subdirectories for different categories:
+
+```
+.kodrdriv/context/
+├── context.md                # Main context file describing sections
+├── people/                   # Directory for information about people
+│   ├── context.md            # Description of the people section
+│   ├── team-members.md       # Information about team members
+│   └── contributors.md       # Information about contributors
+├── projects/                 # Directory for project information
+│   ├── context.md            # Description of the projects section
+│   └── project-details.md    # Details about various projects
+└── technologies/             # Directory for technical information
+    ├── context.md            # Description of the technologies section
+    ├── frameworks.md         # Information about frameworks used
+    └── libraries.md          # Information about libraries used
+```
+
+#### Individual Records Example
+
+Alternatively, you can use a flatter structure with individual files for each entity:
+
+```
+.kodrdriv/context/
+├── context.md                # Main context file describing sections
+├── people/                   # Directory for individual people information
+│   ├── context.md            # Description of the people section
+│   ├── john-doe.md           # Information specific to John Doe
+│   ├── jane-smith.md         # Information specific to Jane Smith
+│   └── alex-johnson.md       # Information specific to Alex Johnson
+```
+
+Choose the organization that works best for your needs. The system will process the context files regardless of the structure, as long as they follow the basic Markdown formatting guidelines.
+
+### Main Context File
+
+The `context.md` file in each directory serves as an introduction to that section. The system loads this file first to understand the structure of the information. For example, a `context.md` file in the people directory might look like:
+
+```markdown
+## People
+
+This section contains subsections that have information about people.
+```
+
+### Context Files
+
+After loading the `context.md` file, the system reads all other Markdown files in the directory. It uses the first header in each file as the name of the section or subsection. For example:
+
+```markdown
+## Team Members
+
+- John Doe: Lead Developer, focuses on backend systems
+- Jane Smith: UX Designer, specializes in responsive interfaces
+- Alex Johnson: DevOps Engineer, manages deployment pipelines
+```
+
+### Context Location
+
+You can specify where to store your context files in two recommended ways:
+
+1. **Project Directory**: Store context files in your project repository at `.kodrdriv/context/`. This is useful when the context is specific to the project and should be versioned with the code.
+
+2. **gitignore Directory**: Alternatively, you can store context in your `.gitignore` directory if you want to keep it separate from your project files or if the context contains sensitive information that shouldn't be committed to the repository.
+
+To specify a custom context directory, use the `--context-dir` option:
+
+```bash
+kodrdriv commit --context-dir ~/my-custom-context
+```
+
+By default, KodrDriv looks for context in the `.kodrdriv/context` directory within your project.
+
+## Configuration Directory
+
+The configuration directory (configDir) allows you to further customize both commit and release instructions by adding pre and post content to the default instructions. This is done by creating additional files in your `.kodrdriv/instructions` directory:
+
+### Release Instructions
+1. **Pre-Content**: Create a file named `release-pre.md` to add content that will be prepended to the default release instructions.
+2. **Post-Content**: Create a file named `release-post.md` to add content that should be appended to the default release instructions.
+
+### Commit Instructions
+1. **Pre-Content**: Create a file named `commit-pre.md` to add content that will be prepended to the default commit instructions.
+2. **Post-Content**: Create a file named `commit-post.md` to add content that should be appended to the default commit instructions.
+
+For example, if you want to add specific formatting requirements before the default release instructions, you could create `.kodrdriv/instructions/release-pre.md`, and if you want to add instructions to the end of the commit instrucitons, you would have a file in `.kodrdriv/instructions/commit-post.md`.
+
+### Overriding Default Instructions
+
+While the pre and post content files provide a way to extend the default instructions, you can also completely replace them by creating either `commit.md` or `release.md` in your `.kodrdriv/instructions` directory. This gives you full control over the instruction content.
+
+However, please note that completely replacing the default instructions should be done with caution. The default instructions are carefully crafted to:
+- Ensure consistent formatting
+- Maintain proper context awareness
+- Follow best practices for commit messages and release notes
+- Handle edge cases and special scenarios
+
+By replacing these instructions entirely, you may lose these benefits and potentially create inconsistencies in your documentation. It's recommended to use the pre and post content files to extend the default instructions rather than replacing them entirely, unless you have a specific need to do so.
+
+To enable instruction overrides, you'll need to use the `--overrides` flag when running the command.
+
+## About the Name
+
+Ski carving and efficient software development have a lot in common. Carving uses edge control to follow a smooth, energy-efficient arc — just like automation uses clean, repeatable scripts to replace manual work. Both are about flow: linking turns or commits without hesitation. As carving unlocks speed and control, automation unlocks scalability and momentum. The result is clean tracks — razor-thin arcs on snow, or tidy diffs in code. And when you’ve mastered your craft, you don’t stop to think about your last move. Your code leaves a clean trail — and your commit message can be automated straight from the diff.  And — snowboarders carve too. Different board, same beauty. We won’t hold it against you if you’re dropping clean edges on a single plank.
+
+## Origin Story: kodrdriv
+
+It always happened at the same moment.
+
+You’ve just spent the entire day in a flow state — the kind that only comes when everything clicks. Whether it was writing code for a critical feature or hammering out chapters of a Markdown or AsciiDoc book, you were locked in. Maybe you were racing the clock to hit a deadline. Maybe you were just up late trying to carve something beautiful out of nothing. Either way, you went right up to the wire, focused, dialed in, exhausted but satisfied.
+
+And then… Git hits you with the meta-question:
+“What did you do?”
+
+That one prompt — to sum it all up in a commit message — feels totally out of place. It asks you to stop, zoom out, and articulate everything you’ve just done, right when your brain is at its least reflective. You’re not in summary mode. You’re still in it. Still shaping. Still carving.
+
+And that’s the thing: it sounds silly, like it shouldn’t be a real problem. But every developer, every writer who lives in Git knows that exact moment. The friction is real. The context switch is jarring. It’s like being asked to narrate your entire ski run after you’ve blasted through powder, dodged trees, hit the cliff drop — and now you’re out of breath, standing at the bottom, being asked to give a PowerPoint.
+
+That’s why I built kodrdriv.
+
+It’s not just a tool — it’s a mindset shift. The idea is simple: you’ve already carved your line in the snow. Your code is there. Your diffs are real. Instead of making you explain it, kodrdriv uses an LLM to read the trail you left behind and generate a clean, meaningful commit message. One that actually reflects your work — without breaking your flow or making you guess what mattered most.
+
+Whether you’re merging branches or writing books, kodrdriv is built for that end-of-day moment when you want to commit and move on — not pause for existential reflection. It reads the line you’ve drawn, and it helps you push it forward.
+
+
+
+
+
+
+
+