diff --git a/.claude/skills/prepare-regen.md b/.claude/skills/prepare-regen.md new file mode 100644 index 0000000..ce581bb --- /dev/null +++ b/.claude/skills/prepare-regen.md @@ -0,0 +1,20 @@ +# Prepare Repo for Fern SDK Regeneration + +Triggers: prepare regen, prepare for regeneration, prep for fern, new sdk gen, prepare sdk gen + +## Steps + +Read AGENTS.md for full context on the regeneration workflow and freeze classification rules. + +1. Fetch latest `main` and create a new branch: `/sdk-gen-` (use today's date). +2. Push the branch to origin. +3. Create an empty commit (`chore: initialize SDK regeneration branch`) if needed, then create a PR titled `chore: SDK regeneration `. +4. Read `.fernignore` and classify each entry using the rules in AGENTS.md: + - **Permanently frozen**: entirely hand-written, no Fern equivalent. NEVER touch these. + - **Temporarily frozen**: Fern-generated with manual patches. These get swapped. +5. For each **temporarily frozen** file only: + - Copy the file to `.bak` alongside the original. + - In `.fernignore`, replace the original path with the `.bak` path (protects our patch, lets Fern overwrite the original). +6. Stage the updated `.fernignore` and all `.bak` files. +7. Commit as `chore: unfreeze files pending regen` and push. +8. Report the PR URL and confirm the branch is ready for generator output. diff --git a/.claude/skills/review-regen.md b/.claude/skills/review-regen.md new file mode 100644 index 0000000..af9c8c4 --- /dev/null +++ b/.claude/skills/review-regen.md @@ -0,0 +1,22 @@ +# Review Fern SDK Regeneration + +Triggers: review regen, review regeneration, diff regen, compare regen, post regen review + +## Steps + +Read AGENTS.md for full context on the regeneration workflow and freeze classification rules. + +1. Find all `.bak` files in the repo — these are our pre-regen manually-patched versions (protected by `.fernignore`). +2. For each `.bak` file, diff it against the corresponding newly generated file to show what changed. +3. Identify which manual patches are still needed (the `.bak` has changes the generator doesn't produce). +4. Present a summary of findings to the user, grouped by category: + - Patches no longer needed (generator now handles it) + - Patches still needed (must be re-applied) + - New changes from the generator worth noting +5. Wait for user direction on which patches to re-apply. +6. Re-apply confirmed patches to the generated files. +7. In `.fernignore`, replace each `.bak` path back to the original path for files that still need patches. +8. Remove `.fernignore` entries entirely for files where patches are no longer needed. +9. Delete all `.bak` files. +10. Run `make build && make test && make lint` to verify. +11. Commit as `chore: re-apply manual patches after regen` and push. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..00ce830 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ +# Agents + +## Fern SDK Regeneration + +### Overview + +This SDK is generated by [Fern](https://buildwithfern.com/). Most files under `src/main/java/com/deepgram/` are auto-generated and should not be edited directly. Some files are hand-written or carry manual patches and are listed in `.fernignore` to prevent the generator from overwriting them. + +When a new Fern generator release is available, we prepare the repo so the generator can overwrite previously frozen files, then re-apply manual patches after reviewing the diff. + +### Freeze classification rules + +Every entry in `.fernignore` falls into one of two categories. The comment above each entry in `.fernignore` indicates which category it belongs to, but when in doubt, apply these rules: + +#### Never unfreeze (permanently frozen) + +These files are entirely hand-written or are maintained independently from Fern. The generator would delete or replace them with something unrelated. They must stay in `.fernignore` at all times. + +How to identify: + +- The file was created by us, not by Fern, such as custom client wrappers or transport abstractions +- The file is a doc, config, build, or CI artifact we maintain independently +- The file lives outside the generated Java package tree or is a manually maintained test/example + +Current permanently frozen files: + +- `src/main/java/com/deepgram/DeepgramClient.java`, `src/main/java/com/deepgram/AsyncDeepgramClient.java`, `src/main/java/com/deepgram/DeepgramClientBuilder.java`, `src/main/java/com/deepgram/AsyncDeepgramClientBuilder.java` - custom wrapper entrypoints that add Bearer auth, session ID support, and custom transport behavior on top of Fern's generated API client +- `src/main/java/com/deepgram/core/transport/` - hand-written transport abstraction +- `build.gradle`, `settings.gradle`, `gradle/`, `gradlew`, `gradlew.bat`, `pom.xml`, `Makefile` - build and project configuration +- `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `LICENSE` - docs +- `src/test/` - manually maintained tests +- `examples/` - manually maintained examples +- `.editorconfig`, `.githooks/`, `.github/`, `.gitignore` - repo and CI configuration +- `target/` - build output +- `CLAUDE.md`, `AGENTS.md`, `.claude/` - agent files + +Note: `.fernignore` also includes flat-path variants such as `src/main/java/DeepgramClient.java` as defensive entries for alternate local generation layouts. Those files do not currently exist in this repo checkout and should not be treated as current maintained source files. + +#### Unfreeze for regen (temporarily frozen) + +These files are Fern-generated but carry manual patches to fix issues in the generator output. We freeze them to protect our patches between regenerations, but unfreeze them before a regen so we can compare the new output against our patches. + +How to identify: + +- The file exists in Fern's output - if you removed it from `.fernignore` and ran the generator, Fern would produce a version of it +- Our version is a modified copy of what Fern generates + +Current temporarily frozen files: + +- `src/main/java/com/deepgram/core/ClientOptions.java` - preserves release-please version markers and correct SDK header constants that Fern currently overwrites + +### Prepare repo for regeneration + +1. Create a new branch off `main` named `lo/sdk-gen-`. +2. Push the branch and create a PR titled `chore: SDK regeneration ` (empty commit if needed). +3. Read `.fernignore` and classify each entry using the rules above. +4. For each temporarily frozen file only: + - Copy the file to `.bak` alongside the original. + - In `.fernignore`, replace the original path with the `.bak` path. This protects our patched version from the generator while allowing Fern to overwrite the original. +5. Never touch permanently frozen entries. Leave them in `.fernignore` as-is. +6. Commit as `chore: unfreeze files pending regen` and push. +7. The branch is now ready for the Fern generator to push changes. + +### After regeneration + +The `.bak` files are our manually patched versions protected by `.fernignore`. The original paths now contain the freshly generated versions. By comparing the two, we can see what the generator now produces versus what we had patched. + +1. Diff each `.bak` file against the new generated version to understand what changed and whether our patches are still needed. +2. Re-apply any patches that are still necessary to the newly generated files. +3. In `.fernignore`, replace each `.bak` path back to the original path for files that still need patches. +4. Remove `.fernignore` entries entirely for any files where the generator now produces correct output. +5. Delete all `.bak` files once review is complete. +6. Run checks (`./gradlew test`) to verify. +7. Commit as `chore: re-apply manual patches after regen` and push.