kbforge 0.2.0__tar.gz → 0.3.0__tar.gz

{kbforge-0.2.0 → kbforge-0.3.0}/.github/workflows/ci.yml

@@ -84,4 +84,4 @@ jobs:
           enable-cache: true
       - run: uv python install 3.13
       - run: uv build --no-sources
-      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1

{kbforge-0.2.0 → kbforge-0.3.0}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.21
+    rev: v0.15.22
     hooks:
       - id: ruff-check
         args: [--fix]
@@ -10,6 +10,6 @@ repos:
   # `uv check` under the hood, so kbforge's own dependencies resolve for ty --
   # a local `entry: ty check` hook cannot see them.
   - repo: https://github.com/astral-sh/ty-pre-commit
-    rev: v0.0.59
+    rev: v0.0.61
     hooks:
       - id: ty

{kbforge-0.2.0 → kbforge-0.3.0}/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-25
+
+### Added
+
+- `examples/github-issues-connector/` — a complete worked example of a credentialed
+  connector (GitHub issues → OKF concepts) with token auth, pagination, and a real
+  incremental cursor, plus a walkthrough README for writing your own connector.
+- GitHub (`--publisher github`) and GitLab (`--publisher gitlab`) publishers that
+  open or update a real pull/merge request from a `ProposedChange`. No new
+  runtime dependencies — both run on stdlib `urllib`. Tokens are read from
+  `GITHUB_TOKEN` / `GITLAB_TOKEN` (configurable via `token_env`), never the CLI.
+  Both send `Authorization: Bearer`, so either forge accepts a personal,
+  project or group access token as well as an OAuth token from `gh`/`glab`.
+- `tests/test_forge_live.py` — an opt-in (`--run-live`) suite that publishes to
+  real GitHub and GitLab scratch repos and reads the result back through `gh`
+  and `glab`, so no assertion depends on the code that wrote the state. Covers
+  the sequence offline tests structurally cannot: publish, republish, human
+  merge, publish again.
+- `--publisher NAME` and `--publish-set KEY=VALUE` CLI flags; `kbforge list` now
+  lists publishers.
+- `kbforge_validate_publish_config` hookspec so publisher config is checked
+  before the pipeline runs.
+
+### Changed
+
+- Publishers are now resolved by name. Previously the first registered plugin
+  implementing `kbforge_publish` won, which became order-dependent with more
+  than one publisher installed.
+- The core design stance is now "zero credentialed *connectors*" — publishing is
+  delivery, not a system-of-record integration.
+
+### Fixed
+
+- `kbforge.__version__` reported `0.1.0` for the whole of the 0.2.0 release. It
+  is now derived from installed package metadata, so `pyproject.toml` is the
+  single source of truth and the two cannot drift again.
+
 ## [0.2.0] - 2026-07-19
 
 ### Added
@@ -60,6 +97,7 @@ production protocol.
   --set KEY=VALUE ...` resolves the connector from the registry and takes YAML-typed
   config, with no per-connector knowledge in the CLI.
 
-[Unreleased]: https://github.com/flyersworder/kbforge/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/flyersworder/kbforge/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/flyersworder/kbforge/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/flyersworder/kbforge/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/flyersworder/kbforge/releases/tag/v0.1.0

{kbforge-0.2.0 → kbforge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kbforge
-Version: 0.2.0
+Version: 0.3.0
 Summary: Agent-first knowledge bases, forged from your systems of record
 Project-URL: Homepage, https://github.com/flyersworder/kbforge
 Project-URL: Repository, https://github.com/flyersworder/kbforge
@@ -72,12 +72,13 @@ and the [artifact-contract spec](docs/design/2026-07-18-agent-facing-artifact-co
 **Alpha — a working walking skeleton.** The deterministic core runs end to end with no
 credentials: two built-in connectors (`local_files`, `git_commits`), canonicalization
 with a stability law, a replay-safe mirror and diff, the §4.4 validator gate, and a
-dry-run publisher — change detection, the no-op rule, and incremental sync via a real
-cursor all exercised by the test suite. Synthesis ships in two forms: a deterministic
-stub (the default, no LLM) and an opt-in grounded LLM synthesizer (`--synthesizer llm`,
-via the `kbforge[llm]` extra).
+dry-run publisher, plus change detection, the no-op rule, and incremental sync via a
+real cursor, all exercised by the test suite. Two credentialed publishers, GitHub and
+GitLab, are also available (opt-in via `--publisher`, token from an env var). Synthesis ships in
+two forms: a deterministic stub (the default, no LLM) and an opt-in grounded LLM
+synthesizer (`--synthesizer llm`, via the `kbforge[llm]` extra).
 
-Not built yet: a credentialed system-of-record connector, and a GitHub-PR publisher. See
+Not built yet: a credentialed system-of-record connector. See
 [`docs/architecture.md`](docs/architecture.md) for the full map.
 
 ## Quickstart
@@ -112,6 +113,34 @@ kbforge run --connector local_files --set path=./docs \
 The synthesizer reaches models through a LiteLLM provider, so OpenRouter and a
 self-hosted LiteLLM gateway share one config path.
 
+## Publishing to GitHub or GitLab
+
+The default publisher writes the proposal to a local directory. To open a real
+pull request or merge request instead, select a forge publisher and give it a
+repo. The token comes from an env var, never the CLI:
+
+```bash
+export GITHUB_TOKEN=...            # or GITLAB_TOKEN
+kbforge run --connector local_files --set path=./docs \
+  --publisher github --publish-set repo=acme/knowledge-base \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+Both publishers accept the same config: `repo` (required), `base` (default: the
+repo's default branch), `base_path` (a subdirectory, default: repo root),
+`branch` (default: `sync/<system>`), `title`, `api_base` (point it at GitHub
+Enterprise or a self-managed GitLab), and `token_env`.
+
+kbforge maintains **one long-lived sync branch and one open review request** per
+source system: a later run force-updates that branch and edits the existing
+PR/MR rather than opening a second one. Two consequences worth knowing:
+
+- Manual commits pushed onto the sync branch are discarded by the next run.
+- Concepts deleted from the source are not deleted from the target repo; files
+  absent from a run are inherited from the base branch.
+
+kbforge never merges. No publisher has a merge method.
+
 ## Design stance
 
 The core ships **zero credentialed connectors and zero CI logic.** The two built-in
@@ -126,6 +155,10 @@ repositories. The interface is the product.
 myservice = "my_package:connector"
 ```
 
+A complete worked example — a credentialed GitHub Issues connector (~160 lines) with
+token auth, pagination, and a real incremental cursor — is in
+[`examples/github-issues-connector/`](examples/github-issues-connector/).
+
 The pipeline order — fetch → normalize → mirror → diff → scope → synthesize → validate →
 publish — is deliberately **not** pluggable, and neither are the no-op rule or the
 never-auto-merge rule. Those are the trust guarantees; making them pluggable would make
@@ -166,6 +199,23 @@ prek install                 # ruff + ty on every commit
 uv run pytest
 ```
 
+The default suite never touches the network. Tests that call a real external
+service are marked `live` and skipped unless you pass `--run-live`.
+
+The forge publishers have a live suite because their offline tests can only
+assert what we *meant* to send — a real forge is the only thing that can say
+the intent was right. It needs a throwaway repo on each forge and the two CLIs
+(`gh`, `glab`) authenticated; each run writes under a fresh `live/<run-id>/`
+prefix, so nothing accumulates and no repo is ever deleted.
+
+```bash
+GITHUB_TOKEN=$(gh auth token) \
+GITLAB_TOKEN=$(glab config get token --host gitlab.com) \
+KBFORGE_LIVE_GITHUB_REPO=you/kbforge-live-test \
+KBFORGE_LIVE_GITLAB_REPO=you/kbforge-live-test \
+uv run pytest tests/test_forge_live.py --run-live
+```
+
 ## License
 
 MIT

{kbforge-0.2.0 → kbforge-0.3.0}/README.md

@@ -37,12 +37,13 @@ and the [artifact-contract spec](docs/design/2026-07-18-agent-facing-artifact-co
 **Alpha — a working walking skeleton.** The deterministic core runs end to end with no
 credentials: two built-in connectors (`local_files`, `git_commits`), canonicalization
 with a stability law, a replay-safe mirror and diff, the §4.4 validator gate, and a
-dry-run publisher — change detection, the no-op rule, and incremental sync via a real
-cursor all exercised by the test suite. Synthesis ships in two forms: a deterministic
-stub (the default, no LLM) and an opt-in grounded LLM synthesizer (`--synthesizer llm`,
-via the `kbforge[llm]` extra).
+dry-run publisher, plus change detection, the no-op rule, and incremental sync via a
+real cursor, all exercised by the test suite. Two credentialed publishers, GitHub and
+GitLab, are also available (opt-in via `--publisher`, token from an env var). Synthesis ships in
+two forms: a deterministic stub (the default, no LLM) and an opt-in grounded LLM
+synthesizer (`--synthesizer llm`, via the `kbforge[llm]` extra).
 
-Not built yet: a credentialed system-of-record connector, and a GitHub-PR publisher. See
+Not built yet: a credentialed system-of-record connector. See
 [`docs/architecture.md`](docs/architecture.md) for the full map.
 
 ## Quickstart
@@ -77,6 +78,34 @@ kbforge run --connector local_files --set path=./docs \
 The synthesizer reaches models through a LiteLLM provider, so OpenRouter and a
 self-hosted LiteLLM gateway share one config path.
 
+## Publishing to GitHub or GitLab
+
+The default publisher writes the proposal to a local directory. To open a real
+pull request or merge request instead, select a forge publisher and give it a
+repo. The token comes from an env var, never the CLI:
+
+```bash
+export GITHUB_TOKEN=...            # or GITLAB_TOKEN
+kbforge run --connector local_files --set path=./docs \
+  --publisher github --publish-set repo=acme/knowledge-base \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+Both publishers accept the same config: `repo` (required), `base` (default: the
+repo's default branch), `base_path` (a subdirectory, default: repo root),
+`branch` (default: `sync/<system>`), `title`, `api_base` (point it at GitHub
+Enterprise or a self-managed GitLab), and `token_env`.
+
+kbforge maintains **one long-lived sync branch and one open review request** per
+source system: a later run force-updates that branch and edits the existing
+PR/MR rather than opening a second one. Two consequences worth knowing:
+
+- Manual commits pushed onto the sync branch are discarded by the next run.
+- Concepts deleted from the source are not deleted from the target repo; files
+  absent from a run are inherited from the base branch.
+
+kbforge never merges. No publisher has a merge method.
+
 ## Design stance
 
 The core ships **zero credentialed connectors and zero CI logic.** The two built-in
@@ -91,6 +120,10 @@ repositories. The interface is the product.
 myservice = "my_package:connector"
 ```
 
+A complete worked example — a credentialed GitHub Issues connector (~160 lines) with
+token auth, pagination, and a real incremental cursor — is in
+[`examples/github-issues-connector/`](examples/github-issues-connector/).
+
 The pipeline order — fetch → normalize → mirror → diff → scope → synthesize → validate →
 publish — is deliberately **not** pluggable, and neither are the no-op rule or the
 never-auto-merge rule. Those are the trust guarantees; making them pluggable would make
@@ -131,6 +164,23 @@ prek install                 # ruff + ty on every commit
 uv run pytest
 ```
 
+The default suite never touches the network. Tests that call a real external
+service are marked `live` and skipped unless you pass `--run-live`.
+
+The forge publishers have a live suite because their offline tests can only
+assert what we *meant* to send — a real forge is the only thing that can say
+the intent was right. It needs a throwaway repo on each forge and the two CLIs
+(`gh`, `glab`) authenticated; each run writes under a fresh `live/<run-id>/`
+prefix, so nothing accumulates and no repo is ever deleted.
+
+```bash
+GITHUB_TOKEN=$(gh auth token) \
+GITLAB_TOKEN=$(glab config get token --host gitlab.com) \
+KBFORGE_LIVE_GITHUB_REPO=you/kbforge-live-test \
+KBFORGE_LIVE_GITLAB_REPO=you/kbforge-live-test \
+uv run pytest tests/test_forge_live.py --run-live
+```
+
 ## License
 
 MIT

{kbforge-0.2.0 → kbforge-0.3.0}/docs/architecture.md

@@ -27,9 +27,12 @@ This library is the reference implementation of that missing half:
 | **Production protocol** (connectors, canonicalization, diff, provenance, publish) | **this library** | this spec |
 | Serving protocol | MCP | exists |
 
-Design stance carried over from the main doc: **the core ships zero connectors,
-zero credentials, zero CI logic.** Connectors are plugins; deployments are separate
-repos. The interface is the product.
+Design stance carried over from the main doc: **the core ships zero credentialed
+connectors, zero CI logic.** Connectors are plugins; deployments are separate
+repos. The interface is the product. Publishers are the exception that proves
+it: publishing is the producer's own delivery mechanism, not an integration with
+someone's system of record, so `github` and `gitlab` ship in core — reading their
+credentials from the environment, never from config.
 
 ---
 
@@ -75,8 +78,8 @@ remove them. (This is the same posture as ADR-2 in the main doc.)
 
 1. **Connectors** (`ConnectorSpec`, §5.1) — bring data *in* from a system of record.
    Fully specified in this sketch; this is what we build first.
-2. **Publishers** (`PublisherSpec`, §5.2) — push proposals *out* (GitLab MR, GitHub PR,
-   local dry-run). Thin; sketched here because the pilot needs exactly one (GitLab).
+2. **Publishers** (`PublisherSpec`, §5.2) — push proposals *out*. Three ship in core:
+   `dry-run` (local), `github` (PR), `gitlab` (MR).
 
 Synthesis (the LLM step) and validation are **core stages with narrow extension
 hooks** (§5.3), not open plugin families — they carry the grounding contract and the
@@ -398,7 +401,7 @@ class ConnectorSpec:
 
 ```python
 class PublisherSpec:
-    """Where proposals go. Pilot ships gitlab-mr; dry-run ships in core."""
+    """Where proposals go. MUST NOT merge (§5.2)."""
 
     @hookspec
     def kbforge_publisher_info(self) -> ConnectorInfo: ...
@@ -410,6 +413,28 @@ class PublisherSpec:
         re-running a failed pipeline updates the same MR, never opens twins."""
 ```
 
+Three publishers ship in core: `dry-run` (default; writes to a directory),
+`github` (pull requests) and `gitlab` (merge requests). All three implement
+`kbforge_publish` and `kbforge_validate_publish_config`; none implements a merge
+method, which is how §5.2's never-merge rule is enforced structurally rather
+than by convention.
+
+The two forge publishers sit behind a `ForgeClient` protocol whose methods name
+intentions (`put_files`, `find_open_pr`) rather than REST endpoints, because the
+forges decompose "commit these files" incompatibly — GitLab in one call, GitHub
+in four. They are unconditional rather than gated behind an extra: both run on
+stdlib `urllib`, so there is no dependency for an extra to install. Deliberately
+absent, so their absence reads as a decision rather than an omission: labels,
+reviewers and draft PRs; pagination in `find_open_pr` (a branch has at most one
+open PR); rate-limit backoff (a run makes fewer than ten calls); and auto-merge,
+which is excluded permanently rather than deferred.
+
+Their offline tests inject a fake transport, which pins the request we intended
+to make but cannot judge whether the intent was right — a real forge caught two
+defects the offline suite structurally could not see. Hence `tests/test_forge_live.py`
+(`--run-live`), which asserts through `gh`/`glab` rather than through kbforge's
+own readers.
+
 ### 5.3 Core-stage extension hooks (narrow, additive-only)
 
 ```python

kbforge-0.3.0/examples/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+Worked examples of extending kbforge. Each is a self-contained package that installs
+alongside kbforge and is discovered through an entry point — no changes to kbforge
+core.
+
+- [**github-issues-connector**](github-issues-connector/) — a complete credentialed
+  connector (~160 lines) that syncs a repository's GitHub issues into OKF concepts,
+  with token auth, pagination, and a real incremental cursor. The template for
+  writing your own connector.

kbforge-0.3.0/examples/github-issues-connector/README.md

@@ -0,0 +1,119 @@
+# Example: a GitHub Issues connector
+
+A complete, credentialed kbforge connector in ~160 lines — the worked example for
+writing your own. It syncs a repository's issues into OKF concepts, and it lives in
+its **own package**, discovered by kbforge purely through an entry point. Nothing in
+kbforge core changes.
+
+This is the shape every connector follows. Copy it, rename it, swap the `fetch`
+body for your system of record.
+
+## How kbforge finds it
+
+A connector is any object that implements the connector hooks, advertised under the
+`kbforge.connectors` entry-point group in your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."kbforge.connectors"]
+github_issues = "kbforge_github_issues:connector"
+```
+
+Once your package is installed alongside kbforge, `kbforge list` shows it and
+`kbforge run --connector github_issues …` uses it. No fork, no registration call.
+
+## The four hooks (the whole contract)
+
+| hook | job |
+|---|---|
+| `kbforge_connector_info` | static self-description (name, version, source) |
+| `kbforge_validate_config` | return a list of problems (`[]` = ok); **no I/O** |
+| `kbforge_fetch(config, cursor)` | pull raw records; `cursor=None` = full backfill |
+| `kbforge_normalize(records)` | raw records → `CanonicalDocument`s; **pure & clock-free** |
+
+That's it. Everything downstream — canonicalization, the replay-safe mirror, diff,
+the no-op rule, incremental scoping, synthesis (stub or LLM), the §4.4 validators,
+and publish — you get for free. A connector only teaches kbforge how to *read* your
+source.
+
+## What this connector shows
+
+**`fetch` — the real-world work.** It reads a token from the `GITHUB_TOKEN`
+environment variable (never from config; the variable name is overridable with
+`--set token_env=MY_TOKEN` — the value still comes only from the environment), pages
+through the REST API, filters out
+pull requests (GitHub's issues endpoint returns them too), and returns each issue as
+a `RawRecord` carrying the issue JSON plus an `anchor_hint` (stable id, URL,
+timestamp). The **cursor** is the maximum `updated_at` seen, so the next run passes
+`since=<watermark>` and fetches only issues changed since — real incremental sync,
+just like the built-in `git_commits` connector.
+
+**`normalize` — deterministic by law.** It is a *pure* parse of the stored JSON into
+a `CanonicalDocument`: no network, no clock (the timestamp came from `fetch`). kbforge
+enforces this — `assert_stability` normalizes twice and rejects a connector whose
+output isn't identical. One design choice worth copying: `updated_at` and the comment
+count are deliberately kept **out** of the concept, so a comment-only edit produces an
+identical concept and stays a no-op, while a real body/label/state change is detected.
+
+**The rules a connector must respect:**
+- **Deterministic, clock-free `normalize`** (the §4.3 stability law).
+- **Retriever, not extractor** — return the source content verbatim with anchors;
+  interpretation is the synthesizer's job, not the connector's.
+- **Credentials only from the environment**, never from config values.
+- **Stable document identity** — a `doc_id` that survives across syncs, so change
+  detection works (here: `github_issues:owner/repo/issues/<number>`).
+
+## Run it
+
+```bash
+# from this directory
+uv sync --extra dev
+uv run pytest                      # 8 offline tests (deterministic, no network)
+
+export GITHUB_TOKEN=$(gh auth token)
+uv run kbforge run \
+  --connector github_issues \
+  --set repo=owner/name \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+Add `--synthesizer llm --llm-set model=deepseek/deepseek-v4-flash` (with
+`kbforge[llm]` and `OPENROUTER_API_KEY`) to turn each issue into a synthesized concept
+instead of the verbatim stub.
+
+That run stops at the dry-run publisher, which writes the bundle under `--out`.
+To close the loop and open a real merge request (needs kbforge 0.3.0+; this
+package itself only depends on 0.2.0 APIs, since publishing is a kbforge CLI
+capability rather than something a connector links against):
+
+```bash
+export GITLAB_TOKEN=$(glab config get token --host gitlab.com)
+uv run kbforge run \
+  --connector github_issues --set repo=owner/name \
+  --publisher gitlab --publish-set repo=group/knowledge-base \
+  --publish-set base_path=kb-from-issues \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+The two `repo` values are independent, and the example is deliberately
+cross-forge to make that obvious: the connector *reads* issues from GitHub, the
+publisher *writes* concepts to GitLab. Use `--publisher github` to target a
+GitHub repo instead — the connector side is unchanged either way.
+
+Both halves are credentialed, which is the one wrinkle worth knowing: this
+connector and the `github` publisher both default to `GITHUB_TOKEN`. When the
+source read and the knowledge-base write should carry different scopes, split
+them — `--set token_env=SOURCE_TOKEN` for the connector, `--publish-set
+token_env=KB_TOKEN` for the publisher.
+
+## Deliberately out of scope
+
+Kept simple so the shape stays legible — each of these is a natural enhancement if
+you extend it:
+
+- **Comments** aren't folded into the concept body (one extra API call per issue).
+- **Deletions** aren't derived from absence (a kbforge-wide gap — needs tombstones).
+- **HTTP errors** surface as a raw `httpx.HTTPStatusError` — a production connector
+  would distinguish 401 (bad token), 404 (repo not found), and 403 rate-limits
+  (honoring `X-RateLimit-Reset`) with clearer messages.
+- **Page-number pagination** with `sort=updated` can, in theory, skip or duplicate an
+  issue updated by someone else mid-fetch; it self-heals on the next incremental sync.

kbforge-0.3.0/examples/github-issues-connector/kbforge_github_issues/__init__.py

@@ -0,0 +1,158 @@
+"""A credentialed kbforge connector for GitHub issues.
+
+Lives outside kbforge core (the core ships zero credentialed connectors) and is
+discovered purely via the `kbforge.connectors` entry-point group. Each issue
+becomes one canonical document; the cursor is the max `updated_at` watermark, so a
+re-run fetches only issues changed since the last sync. `updated_at` and comment
+counts are deliberately kept OUT of the concept, so a comment-only update yields an
+identical concept — a no-op — while a real body/label/state change is detected."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Sequence
+from datetime import datetime
+
+import httpx
+
+from kbforge.canonical import content_hash
+from kbforge.hookspecs import hookimpl
+from kbforge.models import (
+    CanonicalDocument,
+    ConnectorInfo,
+    Cursor,
+    FetchResult,
+    RawRecord,
+    ResourceAnchor,
+)
+
+_SYSTEM = "github_issues"
+_API = "https://api.github.com"
+_PER_PAGE = 100
+
+
+class GitHubIssuesConnector:
+    @hookimpl
+    def kbforge_connector_info(self) -> ConnectorInfo:
+        return ConnectorInfo(
+            name=_SYSTEM,
+            version="0.1.0",
+            source_system="GitHub issues (REST API)",
+            info_types=["issue"],
+        )
+
+    @hookimpl
+    def kbforge_validate_config(self, config: dict) -> list[str]:
+        problems: list[str] = []
+        repo = config.get("repo", "")
+        if (
+            not isinstance(repo, str)
+            or repo.count("/") != 1
+            or not all(repo.split("/"))
+        ):
+            problems.append(f"config 'repo' must be 'owner/name': {repo!r}")
+        token_env = config.get("token_env", "GITHUB_TOKEN")
+        if not os.environ.get(token_env):
+            problems.append(f"env var {token_env} is not set")
+        state = config.get("state", "all")
+        if state not in ("all", "open", "closed"):
+            problems.append(f"config 'state' must be all/open/closed: {state!r}")
+        return problems
+
+    @hookimpl
+    def kbforge_fetch(self, config: dict, cursor: Cursor | None) -> FetchResult:
+        owner, repo = config["repo"].split("/", 1)
+        token = os.environ[config.get("token_env", "GITHUB_TOKEN")]
+        state = config.get("state", "all")
+        since = cursor.payload.get("since") if cursor else None
+
+        records: list[RawRecord] = []
+        max_updated = since
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        with httpx.Client(base_url=_API, headers=headers, timeout=30.0) as client:
+            page = 1
+            while True:
+                params: dict = {
+                    "state": state,
+                    "per_page": _PER_PAGE,
+                    "page": page,
+                    "sort": "updated",
+                    "direction": "asc",
+                }
+                if since:
+                    params["since"] = since
+                resp = client.get(f"/repos/{owner}/{repo}/issues", params=params)
+                resp.raise_for_status()
+                batch = resp.json()
+                if not batch:
+                    break
+                for issue in batch:
+                    if "pull_request" in issue:  # the issues endpoint also returns PRs
+                        continue
+                    updated = issue["updated_at"]
+                    native_id = f"{owner}/{repo}/issues/{issue['number']}"
+                    records.append(
+                        RawRecord(
+                            anchor_hint={
+                                "native_id": native_id,
+                                "url": issue.get("html_url"),
+                                "retrieved_at": updated,
+                            },
+                            media_type="application/vnd.github.issue+json",
+                            payload=json.dumps(issue, sort_keys=True).encode("utf-8"),
+                        )
+                    )
+                    if max_updated is None or updated > max_updated:
+                        max_updated = updated
+                if len(batch) < _PER_PAGE:
+                    break
+                page += 1
+
+        payload = {"since": max_updated} if max_updated else {}
+        return FetchResult(
+            records=records, cursor=Cursor(connector=_SYSTEM, payload=payload)
+        )
+
+    @hookimpl
+    def kbforge_normalize(
+        self, records: Sequence[RawRecord]
+    ) -> list[CanonicalDocument]:
+        docs: list[CanonicalDocument] = []
+        for rec in records:
+            issue = json.loads(rec.payload.decode("utf-8"))
+            native_id = rec.anchor_hint["native_id"]
+            anchor = ResourceAnchor(
+                system=_SYSTEM,
+                native_id=native_id,
+                url=rec.anchor_hint.get("url"),
+                retrieved_at=datetime.fromisoformat(rec.anchor_hint["retrieved_at"]),
+                content_hash="",
+            )
+            doc = CanonicalDocument(
+                anchor=anchor,
+                doc_id=f"{_SYSTEM}:{native_id}",
+                title=str(issue.get("title") or native_id),
+                text=(issue.get("body") or "").strip(),
+                # updated_at / comment count are intentionally excluded — see module
+                # docstring: a comment-only update must stay a no-op.
+                structured={
+                    "state": issue.get("state"),
+                    "author": (issue.get("user") or {}).get("login"),
+                    "labels": sorted(
+                        label["name"] for label in issue.get("labels", [])
+                    ),
+                    "created_at": issue.get("created_at"),
+                },
+                relations=[],
+            )
+            doc.anchor.content_hash = content_hash(doc)
+            docs.append(doc)
+        return docs
+
+
+connector = GitHubIssuesConnector()  # the entry point references this instance

kbforge-0.3.0/examples/github-issues-connector/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "kbforge-github-issues"
+version = "0.1.0"
+description = "A credentialed kbforge connector: GitHub issues -> OKF concepts."
+requires-python = ">=3.12"
+dependencies = ["kbforge>=0.2.0", "httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.entry-points."kbforge.connectors"]
+github_issues = "kbforge_github_issues:connector"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["kbforge_github_issues"]