loreli 0.0.0 → 2.0.0

package/packages/config/src/validate.js

@@ -0,0 +1,160 @@
+/**
+ * Input validation utilities for tool arguments.
+ *
+ * Provides strict validation for user-facing inputs before any side effects
+ * occur. Enforces name regex, length limits, reserved names, and enum checks.
+ *
+ * All validators throw descriptive errors on invalid input.
+ */
+
+/**
+ * Regex for valid agent/team names. Alphanumeric, hyphens, underscores only.
+ *
+ * @type {RegExp}
+ */
+const NAME_RE = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Maximum length for agent names.
+ *
+ * @type {number}
+ */
+const MAX_NAME_LENGTH = 64;
+
+/**
+ * Regex for valid repo format: "owner/name".
+ *
+ * @type {RegExp}
+ */
+const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+/**
+ * Valid agent roles.
+ *
+ * @type {Set<string>}
+ */
+const ROLES = new Set(['planner', 'action', 'reviewer']);
+
+/**
+ * Valid theme names.
+ *
+ * @type {Set<string>}
+ */
+const THEMES = new Set(['transformers', 'pokemon', 'marvel', 'digimon', 'starwars', 'lotr', 'dragonball', 'avatar', 'zelda']);
+
+/**
+ * Valid AI providers.
+ *
+ * @type {Set<string>}
+ */
+const PROVIDERS = new Set(['openai', 'anthropic', 'cursor-openai', 'cursor-anthropic']);
+
+/**
+ * Validate a repository string is in "owner/name" format.
+ *
+ * @param {string} repo - Repository identifier to validate.
+ * @returns {string} The validated repo string.
+ * @throws {Error} If the repo format is invalid.
+ */
+export function repo(repo) {
+  if (!repo || typeof repo !== 'string') {
+    throw new Error('Repository is required.');
+  }
+  if (!REPO_RE.test(repo)) {
+    throw new Error(`Invalid repository format: "${repo}". Expected "owner/name".`);
+  }
+  return repo;
+}
+
+/**
+ * Validate an agent name meets naming requirements.
+ *
+ * @param {string} name - Agent name to validate.
+ * @returns {string} The validated name.
+ * @throws {Error} If the name is invalid.
+ */
+export function name(name) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Agent name is required.');
+  }
+  if (name.length > MAX_NAME_LENGTH) {
+    throw new Error(`Agent name too long (${name.length} chars, max ${MAX_NAME_LENGTH}).`);
+  }
+  if (!NAME_RE.test(name)) {
+    throw new Error(`Invalid agent name: "${name}". Use only letters, numbers, hyphens, underscores.`);
+  }
+  return name;
+}
+
+/**
+ * Validate an agent role is one of the known roles.
+ *
+ * @param {string} role - Role to validate.
+ * @returns {string} The validated role.
+ * @throws {Error} If the role is invalid.
+ */
+export function role(role) {
+  if (!role || typeof role !== 'string') {
+    throw new Error('Role is required.');
+  }
+  if (!ROLES.has(role)) {
+    throw new Error(`Invalid role: "${role}". Valid: ${[...ROLES].join(', ')}.`);
+  }
+  return role;
+}
+
+/**
+ * Validate a theme name or list of theme names.
+ * Accepts a single string or an array of strings, each checked
+ * against the known theme set.
+ *
+ * @param {string|string[]} value - Theme or themes to validate.
+ * @returns {string|string[]} The validated value (same shape as input).
+ * @throws {Error} If any theme is invalid or the list is empty.
+ */
+export function theme(value) {
+  if (Array.isArray(value)) {
+    if (!value.length) throw new Error('Theme list must not be empty.');
+    for (const t of value) theme(t);
+    return value;
+  }
+  if (!value || typeof value !== 'string') {
+    throw new Error('Theme is required.');
+  }
+  if (!THEMES.has(value)) {
+    throw new Error(`Invalid theme: "${value}". Valid: ${[...THEMES].join(', ')}.`);
+  }
+  return value;
+}
+
+/**
+ * Validate a provider name is one of the known providers.
+ *
+ * @param {string} provider - Provider to validate.
+ * @returns {string} The validated provider.
+ * @throws {Error} If the provider is invalid.
+ */
+export function provider(provider) {
+  if (!provider || typeof provider !== 'string') {
+    throw new Error('Provider is required.');
+  }
+  if (!PROVIDERS.has(provider)) {
+    throw new Error(`Invalid provider: "${provider}". Valid: ${[...PROVIDERS].join(', ')}.`);
+  }
+  return provider;
+}
+
+/**
+ * Validate a positive number (used for timeouts, PR numbers, etc.).
+ *
+ * @param {number} value - Number to validate.
+ * @param {string} label - Label for error messages.
+ * @returns {number} The validated number.
+ * @throws {Error} If the value is not a positive number.
+ */
+export function positive(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`${label} must be a positive number, got: ${value}.`);
+  }
+  return value;
+}

package/packages/context/README.md

@@ -0,0 +1,165 @@
+# loreli/context
+
+Context resolution engine for Loreli's read path.
+
+This package resolves decision context from code and GitHub artifacts without using an LLM. It links file lines to commits, commits to PRs, PRs to issues, and issues to discussions so agents can understand why code exists.
+
+## API Reference
+
+### `blame(workspace, hub, repo, cwd, file, line)`
+
+Resolve a file line to commit metadata and associated pull requests.
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `workspace` | `object` | Workspace module that provides `blame(cwd, file, line)`. |
+| `hub` | `object` | Hub instance that provides `associatedPulls(repo, sha)`. |
+| `repo` | `string` | Repository in `owner/name` format. |
+| `cwd` | `string` | Local repository path used for git commands. |
+| `file` | `string` | Repository-relative file path. |
+| `line` | `number` | 1-based line number. |
+
+#### Returns
+
+`Promise<{ sha: string, author: string, date: string, summary: string, prs: Array<{ number: number, title: string, state: string }> }>`
+
+#### Errors
+
+Throws when the workspace blame operation fails (for example, file missing or invalid line).
+
+If fetching associated PRs fails, the function returns successfully with `prs: []`.
+
+### `history(workspace, hub, repo, cwd, file, opts?)`
+
+Return recent commit history for a file with PR associations.
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `workspace` | `object` | Workspace module that provides `gitlog(cwd, file, opts)`. |
+| `hub` | `object` | Hub instance that provides `associatedPulls(repo, sha)`. |
+| `repo` | `string` | Repository in `owner/name` format. |
+| `cwd` | `string` | Local repository path used for git commands. |
+| `file` | `string` | Repository-relative file path. |
+| `opts` | `object` | Optional query options. |
+| `opts.limit` | `number` | Maximum commits to return. Default is `10`. |
+
+#### Returns
+
+`Promise<Array<{ sha: string, date: string, message: string, prs: Array<{ number: number, title: string, state: string }> }>>`
+
+#### Errors
+
+Throws when the workspace log operation fails unexpectedly.
+
+If PR association lookup fails for a commit, that commit is still returned with `prs: []`.
+
+### `resolve(hub, repo, pr)`
+
+Walk from a pull request to linked issues and referenced discussions.
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hub` | `object` | Hub instance with PR, issue, comment, and discussion APIs. |
+| `repo` | `string` | Repository in `owner/name` format. |
+| `pr` | `number` | Pull request number to resolve. |
+
+#### Returns
+
+`Promise<{ pr: object, issues: Array<object>, discussions: Array<object> }>`
+
+The returned `pr` contains PR fields plus `comments`. Each returned issue/discussion includes its comments.
+
+#### Errors
+
+Throws when the root PR cannot be fetched.
+
+Linked issue/discussion fetch failures are tolerated and skipped so partial context can still be returned.
+
+### `search(hub, repo, query)`
+
+Search issues, pull requests, and discussions through the hub search API.
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hub` | `object` | Hub instance that provides `searchIssues(repo, query)`. |
+| `repo` | `string` | Repository in `owner/name` format. |
+| `query` | `string` | Search query string. |
+
+#### Returns
+
+`Promise<Array<{ number: number, title: string, type: string, url: string }>>`
+
+#### Errors
+
+Throws when the hub search call fails.
+
+### `chain(hub, repo, items)`
+
+Resolve and normalize a list of PRs, issues, and discussions into a context chain.
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hub` | `object` | Hub instance with content fetch APIs. |
+| `repo` | `string` | Repository in `owner/name` format. |
+| `items` | `Array<{ type: string, number: number }>` | Sequence of items where `type` is `pr`, `issue`, or `discussion`. |
+
+#### Returns
+
+`Promise<Array<{ type: string, number: number, title: string, body: string, comments: Array<object>, reviews?: Array<object>, trace: object | null }>>`
+
+PR and discussion entries include parsed trace marker data in `trace` when present. Issue entries return `trace: null`.
+
+#### Errors
+
+Item-level failures are tolerated and skipped. The function still resolves with successful entries.
+
+## Usage
+
+This example demonstrates how to resolve file-line context for agent prompts. This matters because reviewer and planner prompts need traceable provenance from code to prior decisions. The call returns commit metadata plus any linked pull requests.
+
+```js
+import * as workspace from 'loreli/workspace';
+import { Hub } from 'loreli/hub';
+import { blame } from 'loreli/context';
+
+const hub = new Hub({ token: process.env.GITHUB_TOKEN });
+
+const result = await blame(
+  workspace,
+  hub,
+  'owner/repo',
+  '/path/to/local/clone',
+  'src/server.js',
+  42,
+);
+
+console.log(result.sha, result.prs);
+```
+
+This example demonstrates how to assemble a mixed context chain across PRs, issues, and discussions. This matters when an agent needs complete decision history before proposing changes. The result preserves trace markers on PRs and discussions.
+
+```js
+import { Hub } from 'loreli/hub';
+import { chain } from 'loreli/context';
+
+const hub = new Hub({ token: process.env.GITHUB_TOKEN });
+
+const items = [
+  { type: 'pr', number: 123 },
+  { type: 'issue', number: 88 },
+  { type: 'discussion', number: 14 },
+];
+
+const resolved = await chain(hub, 'owner/repo', items);
+console.log(resolved.length);
+```

package/packages/context/src/index.js

@@ -0,0 +1,198 @@
+/**
+ * Context resolution engine — the read path.
+ *
+ * Traverses the decision chain from code to commits to PRs to issues
+ * to discussions, assembling the full context of why code exists.
+ * No LLM dependency — pure Git + GitHub API resolution.
+ *
+ * @module loreli/context
+ */
+
+import { parse } from 'loreli/marker';
+
+/**
+ * Regex to detect `Closes #N`, `Fixes #N`, or `Resolves #N` patterns
+ * in PR/issue bodies (GitHub auto-linking keywords).
+ *
+ * @type {RegExp}
+ */
+const CLOSE_RE = /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi;
+
+/**
+ * Resolve a file line to its originating commit and associated PRs.
+ * Runs git blame locally, then correlates the commit SHA to PRs via
+ * the GitHub API.
+ *
+ * @param {object} workspace - Workspace module with blame() function.
+ * @param {object} hub - Hub instance for GitHub API calls.
+ * @param {string} repo - "owner/name" repository.
+ * @param {string} cwd - Local clone directory.
+ * @param {string} file - Relative file path.
+ * @param {number} line - 1-based line number.
+ * @returns {Promise<{sha: string, author: string, date: string, summary: string, prs: Array<{number: number, title: string, state: string}>}>}
+ */
+export async function blame(workspace, hub, repo, cwd, file, line) {
+  const info = await workspace.blame(cwd, file, line);
+  let prs = [];
+  try {
+    prs = await hub.associatedPulls(repo, info.sha);
+  } catch { /* commit may predate the repo or have no associated PRs */ }
+  return { ...info, prs };
+}
+
+/**
+ * Retrieve recent commit history for a file with associated PRs.
+ *
+ * @param {object} workspace - Workspace module with gitlog() function.
+ * @param {object} hub - Hub instance for GitHub API calls.
+ * @param {string} repo - "owner/name" repository.
+ * @param {string} cwd - Local clone directory.
+ * @param {string} file - Relative file path.
+ * @param {object} [opts] - Options.
+ * @param {number} [opts.limit=10] - Maximum commits to return.
+ * @returns {Promise<Array<{sha: string, date: string, message: string, prs: Array<{number: number, title: string, state: string}>}>>}
+ */
+export async function history(workspace, hub, repo, cwd, file, opts = {}) {
+  const commits = await workspace.gitlog(cwd, file, opts);
+  const results = [];
+  for (const commit of commits) {
+    let prs = [];
+    try {
+      prs = await hub.associatedPulls(repo, commit.sha);
+    } catch { /* non-fatal */ }
+    results.push({ ...commit, prs });
+  }
+  return results;
+}
+
+/**
+ * Walk the decision chain from a PR number to its linked issues
+ * and discussions, collecting all comments and traces.
+ *
+ * @param {object} hub - Hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {number} pr - Pull request number.
+ * @returns {Promise<{pr: object, issues: Array<object>, discussions: Array<object>}>}
+ */
+export async function resolve(hub, repo, pr) {
+  const pull = await hub.pull(repo, pr);
+  const prComments = await hub.comments(repo, pr);
+
+  // Extract linked issue numbers from PR body
+  const linked = new Set();
+  let match;
+  while ((match = CLOSE_RE.exec(pull.body)) !== null) {
+    linked.add(parseInt(match[1], 10));
+  }
+
+  // Also check sub-issues
+  try {
+    const subs = await hub.subs(repo, pr);
+    for (const sub of subs) linked.add(sub.number);
+  } catch { /* sub-issues API may not be available */ }
+
+  const issues = [];
+  const discussions = [];
+  const seen = new Set();
+
+  for (const num of linked) {
+    if (seen.has(num)) continue;
+    seen.add(num);
+
+    try {
+      const issue = await hub.issue(repo, num);
+      const comments = await hub.comments(repo, num);
+      issues.push({ ...issue, comments });
+
+      // Look for discussion references in issue body/comments
+      const bodies = [issue.body, ...comments.map(function body(c) { return c.body; })];
+      for (const body of bodies) {
+        const discRef = body?.match(/#(\d+)/g);
+        if (!discRef) continue;
+        for (const ref of discRef) {
+          const discNum = parseInt(ref.slice(1), 10);
+          if (seen.has(discNum)) continue;
+          seen.add(discNum);
+          try {
+            const disc = await hub.discussion(repo, discNum);
+            const discComments = await hub.discussionComments(disc.id);
+            discussions.push({ ...disc, comments: discComments });
+          } catch { /* not a discussion number */ }
+        }
+      }
+    } catch { /* issue may not exist */ }
+  }
+
+  return { pr: { ...pull, comments: prComments }, issues, discussions };
+}
+
+/**
+ * Search across issues, PRs, and discussions using GitHub Search API.
+ *
+ * @param {object} hub - Hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {string} query - Search keywords.
+ * @returns {Promise<Array<{number: number, title: string, type: string, url: string}>>}
+ */
+export async function search(hub, repo, query) {
+  return hub.searchIssues(repo, query);
+}
+
+/**
+ * Build a full context chain from resolved items, including trace
+ * blocks. Unlike the `read` tool which strips traces via
+ * `excise(body, 'trace')`, this function preserves them.
+ *
+ * @param {object} hub - Hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {Array<{type: string, number: number}>} items - Items to chain.
+ * @returns {Promise<Array<{type: string, number: number, title: string, body: string, comments: Array<object>, trace: object|null}>>}
+ */
+export async function chain(hub, repo, items) {
+  const results = [];
+
+  for (const item of items) {
+    try {
+      if (item.type === 'pr') {
+        const pull = await hub.pull(repo, item.number);
+        const comments = await hub.comments(repo, item.number);
+        const reviews = await hub.reviews(repo, item.number);
+        const trace = parse(pull.body, 'trace');
+        results.push({
+          type: 'pr',
+          number: pull.number,
+          title: pull.title,
+          body: pull.body,
+          comments,
+          reviews,
+          trace
+        });
+      } else if (item.type === 'issue') {
+        const issue = await hub.issue(repo, item.number);
+        const comments = await hub.comments(repo, item.number);
+        results.push({
+          type: 'issue',
+          number: issue.number,
+          title: issue.title,
+          body: issue.body,
+          comments,
+          trace: null
+        });
+      } else if (item.type === 'discussion') {
+        const disc = await hub.discussion(repo, item.number);
+        const comments = await hub.discussionComments(disc.id);
+        const trace = parse(disc.body, 'trace');
+        results.push({
+          type: 'discussion',
+          number: disc.number,
+          title: disc.title,
+          body: disc.body,
+          comments,
+          trace
+        });
+      }
+    } catch { /* skip items that can't be resolved */ }
+  }
+
+  return results;
+}