loreli 0.0.0 → 2.0.0

package/packages/hub/README.md

@@ -0,0 +1,338 @@
+# loreli/hub
+
+Provider-agnostic git hosting abstraction for Loreli. Encapsulates all interactions with GitHub (and future GitLab, Gitea) behind a consistent API.
+
+## API Reference
+
+### Factory
+
+```js
+import { hub } from 'loreli/hub';
+
+// Auto-detect from GITHUB_TOKEN
+const h = hub();
+
+// Explicit provider and token
+const h = hub({ provider: 'github', token: process.env.GITHUB_TOKEN });
+
+// Token resolution: explicit param > config.get('github.token') > process.env.GITHUB_TOKEN
+```
+
+### `BaseHub` (Abstract Interface)
+
+All methods accept `repo` as an `"owner/name"` string.
+
+#### Issues
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `issues` | `(repo, { state?, labels? })` | List issues |
+| `issue` | `(repo, number)` | Get single issue |
+| `open` | `(repo, { title, body, labels? })` | Create issue |
+| `comment` | `(repo, number, body)` | Add comment |
+| `comments` | `(repo, number)` | List comments |
+| `sub` | `(repo, parent, childId)` | Add sub-issue (childId is database `id`, not `number`) |
+| `subs` | `(repo, number)` | List sub-issues of a parent |
+
+#### Pull Requests
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `pulls` | `(repo, { state? })` | List PRs |
+| `pull` | `(repo, number)` | Get single PR |
+| `propose` | `(repo, { title, body, head, base?, labels? })` | Create PR (applies labels when provided) |
+| `merge` | `(repo, number, { method? })` | Merge PR |
+| `closePull` | `(repo, number)` | Close PR without merging |
+| `files` | `(repo, number)` | List changed files |
+
+#### Reviews
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `review` | `(repo, number, { body, event?, comments? })` | Create review |
+| `reviews` | `(repo, number)` | List reviews |
+| `annotate` | `(repo, number, { body, path, line, commit })` | Line comment |
+
+#### Contents
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `read` | `(repo, path, { ref? })` | Get file/directory |
+| `write` | `(repo, path, { content, message?, branch? })` | Create/update file |
+| `tree` | `(repo, { path? })` | List directory tree |
+
+#### Repository
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `repo` | `(repo)` | Get repository info |
+| `branch` | `(repo, name)` | Get branch info |
+| `fork` | `(repo, { name, from? })` | Create branch |
+
+#### Labels
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `labels` | `(repo)` | List all labels in a repository |
+| `ensure` | `(repo, definitions[])` | Idempotent: create labels that don't exist, skip existing |
+| `label` | `(repo, number, labels[])` | Add labels to an issue or PR |
+| `unlabel` | `(repo, number, name)` | Remove a label from an issue or PR (idempotent — 404 swallowed) |
+
+The `ensure` method is the primary label management API. It accepts an array of `{ name, color, description }` objects and creates only the labels that are missing. Existing labels are left unchanged.
+
+The following example shows how start uses `ensure` to create agent tracking labels:
+
+```js
+import { definitions } from 'loreli/hub';
+
+// Build label definitions with deterministic text-hex colors
+const defs = definitions(['loreli', 'loreli:anthropic', 'loreli:planner']);
+await h.ensure('owner/repo', defs);
+
+// Apply labels to a PR
+await h.label('owner/repo', 42, ['loreli', 'loreli:anthropic', 'loreli:planner']);
+```
+
+#### Label Definitions Helper
+
+The `definitions()` function from `loreli/hub/labels` generates label objects with deterministic hex colors via [text-hex](https://www.npmjs.com/package/text-hex):
+
+```js
+import { definitions } from 'loreli/hub';
+
+definitions(['loreli:anthropic', 'loreli:planner', 'loreli:approved']);
+// [
+//   { name: 'loreli:anthropic', color: '5d3ea8', description: 'AI provider: anthropic' },
+//   { name: 'loreli:planner', color: '8f4c2a', description: 'Agent role: planner' },
+//   { name: 'loreli:approved', color: 'a3b84c', description: 'Plan discussion approved for promotion to issue' }
+// ]
+```
+
+All Loreli-managed labels are namespaced with a `loreli:` prefix to avoid collisions with existing repository labels:
+
+| Label | Description |
+|-------|-------------|
+| `loreli` | Managed by Loreli agent orchestration |
+| `loreli:planner` | Agent role: planner |
+| `loreli:action` | Agent role: action |
+| `loreli:reviewer` | Agent role: reviewer |
+| `loreli:approved` | Plan discussion approved for promotion to issue |
+| `loreli:changes-requested` | Plan discussion needs revision |
+| `loreli:needs-attention` | Escalated — requires human attention |
+| `loreli:<provider>` | AI provider (e.g. `loreli:openai`, `loreli:anthropic`) |
+| `loreli:<model>` | AI model (e.g. `loreli:claude-sonnet-4`) |
+
+#### Discussions (GitHub Discussions via GraphQL)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `category` | `(repo, name)` | Find a discussion category by name |
+| `discuss` | `(repo, { title, body, categoryId, repositoryId })` | Create a discussion |
+| `discussions` | `(repo, categoryId)` | List discussions in a category |
+| `discussion` | `(repo, number)` | Get a single discussion with labels and comments |
+| `discussionComments` | `(discussionId)` | List comments on a discussion |
+| `discussionComment` | `(discussionId, body)` | Add a comment to a discussion |
+| `updateDiscussion` | `(discussionId, { title?, body? })` | Update discussion title/body |
+| `closeDiscussion` | `(discussionId)` | Close a discussion |
+| `deleteDiscussion` | `(discussionId)` | Delete a discussion |
+| `_applyDiscussionLabels` | `(repo, discussionId, labelNames)` | Apply labels to a discussion |
+| `removeDiscussionLabels` | `(repo, discussionId, labelNames)` | Remove labels from a discussion |
+
+Discussions are used as the planning primitive. The "Loreli" category must be created manually via GitHub repository settings (the API does not support programmatic category creation). All content-producing methods (`discuss`, `discussionComment`, `updateDiscussion`) automatically stamp the body with the agent's identity signature.
+
+The following diagram shows the discussion lifecycle during planning:
+
+```mermaid
+sequenceDiagram
+    participant P as Planner Agent
+    participant R as Reviewer Agent
+    participant O as Orchestrator
+    participant Hub as loreli/hub
+    participant GH as GitHub Discussions
+
+    O->>Hub: category(repo, 'Loreli')
+    Hub->>GH: GraphQL: discussionCategories
+    GH-->>Hub: category id
+    P->>Hub: discuss(repo, { title, body, categoryId })
+    Hub->>GH: createDiscussion
+    GH-->>Hub: discussion
+    R->>Hub: _applyDiscussionLabels(repo, id, ['loreli:approved'])
+    Hub->>GH: addLabelsToLabelable
+    Note over P,GH: After approval
+    O->>Hub: open(repo, { title, body })
+    Hub->>GH: issues.create
+    GH-->>Hub: issue
+    O->>Hub: closeDiscussion(id)
+    Hub->>GH: closeDiscussion
+```
+
+#### Human In The Loop (HITL)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `assign` | `(repo, number, usernames)` | Assign users to an issue or PR |
+| `request` | `(repo, number, usernames)` | Request review from users on a PR |
+
+### Hub Method Flow
+
+The following diagram shows how the orchestrator interacts with the hub and GitHub API during key operations:
+
+```mermaid
+sequenceDiagram
+    participant Orch as Orchestrator
+    participant Hub as loreli/hub
+    participant GH as GitHub API
+
+    Orch->>Hub: ensure(repo, labels)
+    Hub->>GH: listLabelsForRepo + createLabel
+    GH-->>Hub: labels created
+
+    Orch->>Hub: propose(repo, opts)
+    Hub->>GH: pulls.create + addLabels
+    GH-->>Hub: PR data
+
+    Orch->>Hub: request(repo, pr, users)
+    Hub->>GH: pulls.requestReviewers
+    GH-->>Hub: ok
+
+    Orch->>Hub: assign(repo, pr, users)
+    Hub->>GH: issues.addAssignees
+    GH-->>Hub: ok
+```
+
+### Rate Limit Tracking
+
+`GitHubHub` automatically tracks GitHub API rate limits by extracting `X-RateLimit-*` headers from every response. The system provides three capabilities:
+
+#### Automatic Header Extraction
+
+Every REST and GraphQL call updates internal rate limit state:
+
+```js
+const h = new GitHubHub({ token });
+await h.issues('owner/repo');
+
+// Rate limit state is now populated
+console.log(h.rateLimit);
+// { remaining: 4950, limit: 5000, used: 50, reset: 1700000000 }
+```
+
+#### `rates()` — Formatted Rate Limit Info
+
+Returns the current rate limit state in a display-friendly format with a computed ratio.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `remaining` | `number\|null` | Requests remaining in the current window |
+| `limit` | `number\|null` | Total requests allowed in the current window |
+| `used` | `number\|null` | Requests already consumed |
+| `reset` | `string\|null` | ISO 8601 timestamp when the window resets |
+| `ratio` | `number\|null` | Fraction remaining (e.g. `0.84` = 84%) |
+
+```js
+const rl = h.rates();
+console.log(`${rl.remaining}/${rl.limit} (${Math.round(rl.ratio * 100)}%) resets ${rl.reset}`);
+// 4200/5000 (84%) resets 2026-02-13T12:00:00.000Z
+```
+
+The `team_status` MCP tool automatically includes rate limit info in its dashboard output.
+
+#### Low-Limit Warning Callback
+
+Register a callback to receive warnings when remaining requests drop below 20% of the limit:
+
+```js
+h.onRateLimitWarning = function warn({ remaining, limit, reset, ratio }) {
+  console.warn(`Rate limit low: ${remaining}/${limit} (${Math.round(ratio * 100)}%), resets ${reset}`);
+};
+```
+
+#### Exponential Backoff on 429
+
+When GitHub returns a `429 Too Many Requests` response (secondary rate limit), the hub automatically retries with exponential backoff and jitter:
+
+- Up to 3 retry attempts
+- Respects the `Retry-After` header when present
+- Falls back to exponential backoff (1s, 2s, 4s base + random jitter)
+- Non-429 errors are thrown immediately
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant Hub as GitHubHub
+    participant GH as GitHub API
+
+    App->>Hub: issues(repo)
+    Hub->>GH: GET /repos/{owner}/{repo}/issues
+    GH-->>Hub: 429 + Retry-After: 2
+    Note over Hub: Wait 2 seconds
+    Hub->>GH: GET /repos/{owner}/{repo}/issues (retry 1)
+    GH-->>Hub: 200 + X-RateLimit-Remaining: 4500
+    Hub-->>App: [issues]
+```
+
+### Eventual Consistency (`_settle`)
+
+GitHub's API exhibits eventual consistency — newly created resources may not appear in list endpoints immediately after creation. Without handling this, callers that create a resource and then query for it risk getting stale results.
+
+`GitHubHub` addresses this transparently via an internal `_settle` mechanism. Every mutation method (`open`, `comment`, `write`, `propose`, `discuss`, `fork`) verifies the created resource is visible in the corresponding list or get endpoint before returning. This uses exponential backoff with a configurable retry count and delay cap:
+
+```js
+// Internal method — not part of the public API
+async _settle(verify, label, { retries = 5, base = 300, cap = 5000 } = {})
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `verify` | `() => Promise<boolean>` | — | Returns `true` when the resource is visible |
+| `label` | `string` | — | Descriptive label for debug logging |
+| `retries` | `number` | `5` | Maximum verification attempts |
+| `base` | `number` | `300` | Base delay in ms (doubles each attempt) |
+| `cap` | `number` | `5000` | Maximum delay per attempt in ms |
+
+If all retries are exhausted without the resource becoming visible, a warning is logged but no error is thrown — the resource was created successfully, only the index is stale.
+
+Discussion mutations use direct GraphQL node queries by ID instead of relying on list endpoints, as list queries can have especially severe eventual consistency delays.
+
+**Impact on callers**: No action needed. All hub methods return only after their resource is settled. Tests and orchestrator code do not need `setTimeout` delays after hub calls.
+
+### Pagination
+
+All list methods (`issues`, `pulls`, `comments`, `reviews`, `files`) use Octokit's `paginate()` helper with `per_page: 100` to fetch all pages automatically. Callers always receive the complete result set, regardless of how many items exist.
+
+Without pagination, GitHub's default page size of 30 items silently truncates results, which can cause agents to miss issues, PRs, or review comments.
+
+### Pretest Cleanup
+
+Integration tests create real GitHub resources (issues, PRs, branches, discussions). To ensure a clean starting state, the repository includes a `scripts/clean-test-repo.js` script wired as a `pretest` hook in `package.json`:
+
+```json
+{
+  "scripts": {
+    "pretest": "node scripts/clean-test-repo.js",
+    "test": "node --test ..."
+  }
+}
+```
+
+The script uses `GitHubHub` with `paginate()` to:
+1. Close all open issues and PRs
+2. Delete all non-default branches
+3. Delete all discussions in the "Loreli" category
+
+This prevents leftover test data from causing false claims, stale label collisions, or flaky assertions in subsequent runs. Individual tests also track their resources via the `Cleanup` helper class in `packages/hub/test/helpers.js`.
+
+### Normalized Return Shapes
+
+All responses are normalized to provider-agnostic objects:
+
+- **Issue**: `{ id, number, title, body, state, author, url, labels, created, updated }` (`id` is the GitHub database ID, needed for the sub-issues API)
+- **Pull**: `{ number, title, body, state, head, base, author, url, labels, merged, created, updated }`
+- **Comment**: `{ id, body, author, created }`
+- **Review**: `{ id, body, state, author, submitted }`
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub personal access token (required for GitHubHub) |

package/packages/hub/src/base.js

@@ -0,0 +1,154 @@
+/**
+ * Abstract base class defining all git-hosting operations Loreli needs.
+ *
+ * Subclasses (GitHubHub, future GitLabHub) implement each method
+ * using their provider's API client. Methods are organized by domain:
+ * Issues, Pull Requests, Reviews, Contents, Repository, Labels, Projects.
+ *
+ * Convention: `repo` is always an "owner/name" string.
+ *
+ * Identity scoping: call `hub.as(identity, role)` to get a scoped
+ * instance that auto-appends agent signatures to all written content.
+ */
+export class BaseHub {
+  /**
+   * @param {string} _repo
+   * @param {object} [_opts]
+   * @throws {Error} Always — subclass must override.
+   */
+  async issues(_repo, _opts) { throw new Error('issues: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number */
+  async issue(_repo, _number) { throw new Error('issue: not implemented'); }
+
+  /** @param {string} _repo @param {object} _opts */
+  async open(_repo, _opts) { throw new Error('open: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number @param {object} _fields */
+  async update(_repo, _number, _fields) { throw new Error('update: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number @param {string} _body */
+  async comment(_repo, _number, _body) { throw new Error('comment: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number */
+  async comments(_repo, _number) { throw new Error('comments: not implemented'); }
+
+  // Pull Requests
+  /** @param {string} _repo @param {object} [_opts] */
+  async pulls(_repo, _opts) { throw new Error('pulls: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number */
+  async pull(_repo, _number) { throw new Error('pull: not implemented'); }
+
+  /** @param {string} _repo @param {object} _opts */
+  async propose(_repo, _opts) { throw new Error('propose: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number @param {object} [_opts] */
+  async merge(_repo, _number, _opts) { throw new Error('merge: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number */
+  async closePull(_repo, _number) { throw new Error('closePull: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number */
+  async files(_repo, _number) { throw new Error('files: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number @param {number} [_maxBytes] */
+  async diff(_repo, _number, _maxBytes) { throw new Error('diff: not implemented'); }
+
+  // Reviews
+  /** @param {string} _repo @param {number} _number @param {object} _opts */
+  async review(_repo, _number, _opts) { throw new Error('review: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number */
+  async reviews(_repo, _number) { throw new Error('reviews: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number @param {object} _opts */
+  async annotate(_repo, _number, _opts) { throw new Error('annotate: not implemented'); }
+
+  // Contents
+  /** @param {string} _repo @param {string} _path @param {object} [_opts] */
+  async read(_repo, _path, _opts) { throw new Error('read: not implemented'); }
+
+  /** @param {string} _repo @param {string} _path @param {object} _opts */
+  async write(_repo, _path, _opts) { throw new Error('write: not implemented'); }
+
+  /** @param {string} _repo @param {object} [_opts] */
+  async tree(_repo, _opts) { throw new Error('tree: not implemented'); }
+
+  // Repository
+  /** @param {string} _repo */
+  async repo(_repo) { throw new Error('repo: not implemented'); }
+
+  /** @param {string} _repo @param {string} _name */
+  async branch(_repo, _name) { throw new Error('branch: not implemented'); }
+
+  /** @param {string} _repo @param {object} _opts */
+  async fork(_repo, _opts) { throw new Error('fork: not implemented'); }
+
+  // Rate Limits
+  /**
+   * Get current rate limit information.
+   *
+   * @returns {{remaining: number|null, limit: number|null, reset: string|null, used: number|null, ratio: number|null}}
+   */
+  rates() { return { remaining: null, limit: null, used: null, reset: null, ratio: null }; }
+
+  // Labels
+  /** @param {string} _repo @param {number} _number @param {string[]} _labels */
+  async label(_repo, _number, _labels) { throw new Error('label: not implemented'); }
+
+  /** @param {string} _repo */
+  async labels(_repo) { throw new Error('labels: not implemented'); }
+
+  /** @param {string} _repo @param {Array<{name: string, color: string, description?: string}>} _labels */
+  async ensure(_repo, _labels) { throw new Error('ensure: not implemented'); }
+
+  // Discussions (planning)
+  /** @param {string} _repo @param {string} _name */
+  async category(_repo, _name) { throw new Error('category: not implemented'); }
+
+  /** @param {string} _repo @param {object} _opts */
+  async discuss(_repo, _opts) { throw new Error('discuss: not implemented'); }
+
+  /** @param {string} _repo @param {string} _categoryId */
+  async discussions(_repo, _categoryId) { throw new Error('discussions: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number */
+  async discussion(_repo, _number) { throw new Error('discussion: not implemented'); }
+
+  /** @param {string} _discussionId */
+  async discussionComments(_discussionId) { throw new Error('discussionComments: not implemented'); }
+
+  /** @param {string} _discussionId @param {string} _body */
+  async discussionComment(_discussionId, _body) { throw new Error('discussionComment: not implemented'); }
+
+  /** @param {string} _discussionId @param {object} _opts */
+  async updateDiscussion(_discussionId, _opts) { throw new Error('updateDiscussion: not implemented'); }
+
+  /** @param {string} _discussionId */
+  async closeDiscussion(_discussionId) { throw new Error('closeDiscussion: not implemented'); }
+
+  /** @param {string} _discussionId */
+  async deleteDiscussion(_discussionId) { throw new Error('deleteDiscussion: not implemented'); }
+
+  // Search & Commits
+  /** @param {string} _repo @param {string} _sha */
+  async associatedPulls(_repo, _sha) { throw new Error('associatedPulls: not implemented'); }
+
+  /** @param {string} _repo @param {string} _query */
+  async searchIssues(_repo, _query) { throw new Error('searchIssues: not implemented'); }
+
+  // Sub-issues
+  /** @param {string} _repo @param {number} _parent @param {number} _childId */
+  async sub(_repo, _parent, _childId) { throw new Error('sub: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number */
+  async subs(_repo, _number) { throw new Error('subs: not implemented'); }
+
+  // Human In The Loop (HITL)
+  /** @param {string} _repo @param {number} _number @param {string[]} _usernames */
+  async assign(_repo, _number, _usernames) { throw new Error('assign: not implemented'); }
+
+  /** @param {string} _repo @param {number} _number @param {string[]} _usernames */
+  async request(_repo, _number, _usernames) { throw new Error('request: not implemented'); }
+}