Document and expose library API for safe venfork-config consumption#42
Draft
Copilot wants to merge 2 commits into
Draft
Document and expose library API for safe venfork-config consumption#42Copilot wants to merge 2 commits into
Copilot wants to merge 2 commits into
Conversation
…nfork-config consumers Agent-Logs-Url: https://github.com/cabljac/venfork/sessions/93a5a709-c27b-4a9b-bbc2-9f61016b4c44 Co-authored-by: cabljac <32874567+cabljac@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Document force-push semantics of venfork-config for consumers
Document and expose library API for safe venfork-config consumption
May 7, 2026
There was a problem hiding this comment.
Pull request overview
This PR documents the intentional force-push/replace semantics of the venfork-config branch for downstream consumers, and introduces a small public library entry point so external tooling can read venfork config without having to manage git refspec edge-cases themselves.
Changes:
- Added
src/lib.tsas a public library API surface re-exportingreadVenforkConfigFromRepo,fetchVenforkConfig, and related config types. - Expanded the README concurrency section with guidance for consumers fetching
venfork-config, including preferred usage via the new library helpers. - Updated
package.jsonto add anexportsentry and build bothsrc/index.tsandsrc/lib.tsintodist/.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| src/lib.ts | New public library entry point re-exporting config readers/types. |
| README.md | New documentation describing consumer-facing fetch semantics and recommended helper usage. |
| package.json | Adds package export mapping and builds the new library entry. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+6
to
+9
| * `venfork-config` branch directly. Both helpers handle the | ||
| * force-push semantics of the config branch internally: they never | ||
| * update a local ref, so they are safe to call from a long-lived | ||
| * clone without ever hitting a non-fast-forward rejection. |
Comment on lines
+515
to
+530
| Because every config-mutating command replaces (rather than appends to) the `venfork-config` branch tip, **a plain refspec fetch is rejected as non-fast-forward**: | ||
|
|
||
| ```bash | ||
| # This FAILS after any venfork config update: | ||
| git fetch origin venfork-config:venfork-config | ||
| # ! [rejected] venfork-config -> venfork-config (non-fast-forward) | ||
| ``` | ||
|
|
||
| Tools that maintain a long-lived local clone and read the config branch must use a **forced refspec**: | ||
|
|
||
| ```bash | ||
| # Force-update the local ref — safe because the branch is intentionally replaced: | ||
| git fetch origin +venfork-config:venfork-config | ||
| # or equivalently: | ||
| git fetch --force origin venfork-config:venfork-config | ||
| ``` |
| git fetch --force origin venfork-config:venfork-config | ||
| ``` | ||
|
|
||
| **Preferred approach — use the venfork library helpers:** The `readVenforkConfigFromRepo` and `fetchVenforkConfig` functions exported from the `venfork` package handle this internally (they read via `FETCH_HEAD` / a fresh clone without touching any local ref), so you never hit the non-fast-forward edge case: |
Comment on lines
+9
to
14
| "exports": { | ||
| ".": "./dist/lib.js" | ||
| }, | ||
| "scripts": { | ||
| "build": "bun build ./src/index.ts --outdir ./dist --target node", | ||
| "build": "bun build ./src/index.ts ./src/lib.ts --outdir ./dist --target node", | ||
| "compile": "bun build ./src/index.ts --compile --outfile ./dist/venfork", |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every config-mutating venfork command (
stage --pr,pull-request,issue stage,issue pull,sync upstream-pr/<n>) force-pushes thevenfork-configorphan branch. This causes a plaingit fetch origin venfork-config:venfork-configto fail with non-fast-forward in any long-lived clone, silently leaving consumers with stale config state.Changes
README.md— New "Consumers readingvenfork-configdirectly" subsection under Concurrency documenting the force-push behaviour, the+refspec workaround, and the preferred library-helper approach.src/lib.ts— New public library entry point re-exportingreadVenforkConfigFromRepoandfetchVenforkConfig(both already avoid touching local refs internally) along with all config types.package.json— Adds"exports": { ".": "./dist/lib.js" }and extends the build script to compilesrc/lib.tsalongsidesrc/index.ts.Usage
Both helpers fetch via
FETCH_HEAD/ a fresh temp clone, so non-fast-forward rejections cannot occur regardless of local ref state.