loreli 0.0.0 → 2.0.0

package/packages/log/src/index.js

@@ -0,0 +1,252 @@
+import winston from 'winston';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/**
+ * Module-level state for the logging subsystem.
+ * `home` is the base directory for log files (~/.loreli/ by default).
+ * `session` is the active session ID (set via bind()).
+ * `loggers` caches loggers by package name.
+ */
+let home = process.env.LORELI_HOME ?? join(homedir(), '.loreli');
+let session = null;
+let bound = false;
+
+/** @type {object|null} loreli/config instance, set via bind(). */
+let cfg = null;
+
+const loggers = new Map();
+const agentLoggers = new Map();
+
+/**
+ * Resolve the effective max file size in bytes.
+ * Delegates to loreli/config if bound, else hardcoded default.
+ *
+ * @returns {number}
+ */
+function effectiveMaxSize() {
+  return cfg?.get?.('log.maxSize') ?? 10 * 1024 * 1024;
+}
+
+/**
+ * Resolve the effective max files count.
+ * Delegates to loreli/config if bound, else hardcoded default.
+ *
+ * @returns {number}
+ */
+function effectiveMaxFiles() {
+  return cfg?.get?.('log.maxFiles') ?? 3;
+}
+
+/**
+ * Resolve the effective log level for file transports.
+ * Delegates to loreli/config if bound, else env > hardcoded default.
+ *
+ * @returns {string}
+ */
+function effectiveLevel() {
+  return cfg?.get?.('log.level') ?? process.env.LORELI_LOG_LEVEL ?? 'debug';
+}
+
+/**
+ * Create the JSON format used for file transports.
+ *
+ * @returns {winston.Logform.Format} JSON format with timestamp.
+ */
+function fileFormat() {
+  return winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json()
+  );
+}
+
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ *
+ * @param {string} dir - Directory path.
+ */
+function ensure(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Get the logs directory path for the current session.
+ *
+ * @returns {string|null} Logs directory or null if no session is bound.
+ */
+function logsDir() {
+  if (!session) return null;
+  return join(home, 'sessions', session, 'logs');
+}
+
+/**
+ * Create the pre-session fallback file transport.
+ * Writes to `~/.loreli/loreli.log` before a session is bound.
+ *
+ * @returns {winston.transports.FileTransportInstance} File transport.
+ */
+function fallbackTransport() {
+  ensure(home);
+  return new winston.transports.File({
+    filename: join(home, 'loreli.log'),
+    format: fileFormat(),
+    level: effectiveLevel(),
+    maxsize: effectiveMaxSize(),
+    maxFiles: effectiveMaxFiles()
+  });
+}
+
+/**
+ * Add the appropriate file transport to a logger after bind().
+ * When a session is active, writes to the session's orchestrator log.
+ * Otherwise falls back to `home/loreli.log`.
+ *
+ * @param {winston.Logger} log - The winston logger to augment.
+ */
+function addBoundTransport(log) {
+  const dir = logsDir();
+  if (!dir) {
+    // No session — add fallback transport at current home
+    ensure(home);
+    log.add(new winston.transports.File({
+      filename: join(home, 'loreli.log'),
+      format: fileFormat(),
+      level: effectiveLevel(),
+      maxsize: effectiveMaxSize(),
+      maxFiles: effectiveMaxFiles()
+    }));
+    return;
+  }
+
+  ensure(dir);
+  log.add(new winston.transports.File({
+    filename: join(dir, 'orchestrator.log'),
+    format: fileFormat(),
+    level: effectiveLevel(),
+    maxsize: effectiveMaxSize(),
+    maxFiles: effectiveMaxFiles()
+  }));
+}
+
+/**
+ * Create a per-agent file-only logger that writes to a dedicated log file.
+ *
+ * @param {string} name - Agent identity name (e.g. 'optimus-0').
+ * @param {string} pkg - Package name for the logger's defaultMeta.
+ * @returns {winston.Logger} A logger writing to the agent's log file.
+ */
+function createAgentLogger(name, pkg) {
+  const dir = logsDir();
+  const transports = [fallbackTransport()];
+
+  if (dir) {
+    ensure(dir);
+    transports.push(new winston.transports.File({
+      filename: join(dir, `${name}.log`),
+      format: fileFormat(),
+      level: effectiveLevel(),
+      maxsize: effectiveMaxSize(),
+      maxFiles: effectiveMaxFiles()
+    }));
+  }
+
+  return winston.createLogger({
+    level: effectiveLevel(),
+    defaultMeta: { package: pkg, agent: name },
+    transports
+  });
+}
+
+/**
+ * Create or retrieve a logger scoped to a package name.
+ *
+ * All output goes to file only — no console transports — so stdout
+ * and stderr stay clean for protocols like MCP stdio.
+ *
+ * Before `bind()`, logs write to `~/.loreli/loreli.log`.
+ * After `bind()`, a session-scoped transport is added that writes to
+ * `~/.loreli/sessions/<session>/logs/orchestrator.log`.
+ *
+ * @param {string} pkg - The package name (e.g. 'agent', 'hub', 'mcp').
+ * @returns {object} A logger with info/warn/error/debug methods and an agent() factory.
+ */
+export function logger(pkg) {
+  if (loggers.has(pkg)) return loggers.get(pkg);
+
+  const log = winston.createLogger({
+    level: effectiveLevel(),
+    defaultMeta: { package: pkg },
+    transports: [fallbackTransport()]
+  });
+
+  // Attach bound transport if already bound
+  if (bound) addBoundTransport(log);
+
+  /**
+   * Create a per-agent sub-logger that writes to a dedicated log file.
+   *
+   * @param {string} name - Agent identity name (e.g. 'optimus-0').
+   * @returns {object} A logger with info/warn/error/debug methods.
+   */
+  log.agent = function agent(name) {
+    const key = `${pkg}:${name}`;
+    if (agentLoggers.has(key)) return agentLoggers.get(key);
+
+    const agentLog = createAgentLogger(name, pkg);
+    agentLoggers.set(key, agentLog);
+    return agentLog;
+  };
+
+  loggers.set(pkg, log);
+  return log;
+}
+
+/**
+ * Bind the logging subsystem to a session, home directory, and/or config.
+ *
+ * After binding, all existing loggers gain an additional file transport.
+ * When a session is provided, it writes to the session's logs directory.
+ * Without a session, it writes to `home/loreli.log`. New loggers created
+ * after bind() also receive the bound transport automatically.
+ *
+ * Log settings (level, maxSize, maxFiles) are resolved through the config
+ * instance's full resolution chain: overrides > loreli.yml > env > defaults.
+ *
+ * @param {object} opts - Bind options.
+ * @param {string} [opts.session] - Session ID for log file path.
+ * @param {string} [opts.home] - Override the base directory (~/.loreli/).
+ * @param {object} [opts.config] - loreli/config instance with a get() method.
+ */
+export function bind(opts = {}) {
+  if (opts.home) home = opts.home;
+  if (opts.session) session = opts.session;
+  if (opts.config) cfg = opts.config;
+  bound = true;
+
+  // Add file transports to all existing loggers
+  for (const log of loggers.values()) {
+    addBoundTransport(log);
+  }
+}
+
+/**
+ * Reset the logging subsystem. Clears all cached loggers and state.
+ * Primarily used in tests to ensure a clean slate between runs.
+ */
+export function reset() {
+  // Close all transports to prevent file handle leaks
+  for (const log of loggers.values()) {
+    log.close();
+  }
+  for (const log of agentLoggers.values()) {
+    log.close();
+  }
+
+  loggers.clear();
+  agentLoggers.clear();
+  session = null;
+  bound = false;
+  cfg = null;
+  home = process.env.LORELI_HOME ?? join(homedir(), '.loreli');
+}

package/packages/marker/README.md

@@ -0,0 +1,200 @@
+# loreli/marker
+
+Machine-readable HTML comment markers for GitHub content. Decouples workflow-state detection from human-visible text so themed messages can change freely without breaking parsing logic.
+
+## Why
+
+Loreli embeds metadata in GitHub comments, PR bodies, and discussion posts. Previously, parsing relied on human-visible strings like `"Claimed by"` or `"| Agent |"`, which broke when text was themed or reformatted. This package standardizes a single marker format across all packages.
+
+## Marker Format
+
+```
+<!-- loreli:TYPE key="value" key="value" -->
+```
+
+Markers are HTML comments — invisible to GitHub readers but reliably parseable. The `loreli:` prefix namespaces them to avoid collisions with other tooling.
+
+## Installation
+
+Already available as a workspace export:
+
+```js
+import { mark, has, parse, strip, stripLast, excise } from 'loreli/marker';
+```
+
+## API Reference
+
+### `mark(type, data?)`
+
+Produces a marker string.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | `string` | yes | Marker type (e.g. `'claim'`, `'signature'`, `'agent'`). |
+| `data` | `Object<string, string>` | no | Key-value pairs to embed in the marker. |
+
+**Returns:** `string` — an HTML comment marker.
+
+**Throws:** `Error` — if `type` is falsy or empty.
+
+The following example creates a claim marker with an agent identifier, which is the most common pattern used by the action package to tag issue claims:
+
+```js
+mark('claim', { agent: 'optimus-0' });
+// → '<!-- loreli:claim agent="optimus-0" -->'
+```
+
+Type-only markers (no data) are used for structural markers like signatures, where presence is all that matters:
+
+```js
+mark('signature');
+// → '<!-- loreli:signature -->'
+```
+
+### `has(body, type)`
+
+Checks whether a body contains a marker of the given type.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to look for. |
+
+**Returns:** `boolean` — `true` if the marker type is present.
+
+This is the primary detection function. Use it to branch on workflow state without inspecting visible text. Safe to call on null or empty bodies — always returns `false`:
+
+```js
+has(body, 'claim');    // true if body contains a loreli:claim marker
+has(null, 'claim');    // false
+```
+
+### `parse(body, type)`
+
+Extracts the key-value data from the first marker of the given type.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to extract. |
+
+**Returns:** `Object<string, string> | null` — parsed key-value data, or `null` if not found. Returns an empty object `{}` for type-only markers.
+
+Use `parse` when you need the embedded data, not just presence. For example, extracting which agent claimed an issue:
+
+```js
+parse(body, 'claim');
+// → { agent: 'optimus-0' }
+
+parse(body, 'signature');
+// → {} (type-only marker — present but no data)
+
+parse('no markers', 'claim');
+// → null
+```
+
+### `strip(body, type)`
+
+Removes the first marker of the given type and everything after it, trimming trailing whitespace.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to strip from. |
+
+**Returns:** `string | null | undefined` — body with the marker and all trailing content removed. Returns the input unchanged if the marker is not found or the input is null/empty.
+
+This is designed for signature stripping — removing the agent signature block that appears at the end of every stamped comment:
+
+```js
+const body = 'Review feedback here\n<!-- loreli:signature -->\n***\n| Agent | Model | ...';
+strip(body, 'signature');
+// → 'Review feedback here'
+```
+
+### `stripLast(body, type)`
+
+Removes the **last** marker of the given type and everything after it, trimming trailing whitespace. Use when multiple markers exist and only the trailing one should be removed (e.g. duplicate signatures at end of body).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to strip from. |
+
+**Returns:** `string | null | undefined` — body with the last marker and all trailing content removed. Returns the input unchanged if the marker is not found or the input is null/empty.
+
+```js
+const body = '## Content\n<!-- loreli:signature -->\n***\n...\n<!-- loreli:signature -->\n***\n...';
+stripLast(body, 'signature');
+// → '## Content\n<!-- loreli:signature -->\n***\n...' (one signature remains)
+```
+
+### `excise(body, type)`
+
+Removes content between paired markers of the given type. Finds the opening `<!-- loreli:TYPE ... -->` and closing `<!-- loreli:TYPE-end -->`, removes both markers and everything between them, and collapses extra blank lines at the join point.
+
+Unlike `strip()`, which removes a marker and everything after it, `excise()` removes only the delimited section and preserves content on both sides. Designed for trace blocks and other self-contained sections embedded within larger bodies.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to excise (matches TYPE and TYPE-end). |
+
+**Returns:** `string | null | undefined` — body with the marker-delimited section removed. Returns input unchanged if start or end marker is missing.
+
+Use `excise` to remove trace blocks from PR bodies before passing content to reviewer prompts or returning it through the `read` MCP tool:
+
+```js
+const body = 'Closes #42\n\n<!-- loreli:trace agent="bee-0" -->\n<details>...</details>\n<!-- loreli:trace-end -->\n\nMore content';
+excise(body, 'trace');
+// → 'Closes #42\nMore content'
+```
+
+When the end marker is missing, the body is returned unchanged to avoid accidental content loss:
+
+```js
+excise('text<!-- loreli:trace -->orphaned', 'trace');
+// → 'text<!-- loreli:trace -->orphaned'
+```
+
+## Error Behavior
+
+| Scenario | Function | Behavior |
+|----------|----------|----------|
+| Falsy/empty `type` | `mark()` | Throws `Error: type is required` |
+| Null/undefined/empty `body` | `has()` | Returns `false` |
+| Null/undefined/empty `body` | `parse()` | Returns `null` |
+| Null/undefined `body` | `strip()` | Returns input unchanged |
+| Null/undefined `body` | `excise()` | Returns input unchanged |
+| Marker not found | `has()` | Returns `false` |
+| Marker not found | `parse()` | Returns `null` |
+| Marker not found | `strip()` | Returns body unchanged |
+| Start marker not found | `excise()` | Returns body unchanged |
+| End marker not found | `excise()` | Returns body unchanged |
+
+## Marker Types in Use
+
+| Type | Emitted By | Consumed By | Purpose |
+|------|-----------|-------------|---------|
+| `claim` | action `claim()` | action `claimant()` | Issue claim detection |
+| `signoff` | review `signoff()` | review tests | Approval detection |
+| `release` | action `reassign()` | — | Release tracking (consistency) |
+| `gate` | review `gate()` | — | HITL state tracking (consistency) |
+| `agent` | hub `_stamp()` | gate tool | Agent comment filtering |
+| `signature` | `Identity.signature()` | `Identity.strip()` | Signature block detection/removal |
+| `review-event` | hub `_stamp()` | hub review patching | Review event type embedding |
+| `parent` | planner `link()` | planner `link()` | Parent tracking issue detection for sub-issue linking |
+| `trace` | agent trace `format()` | `excise(body, 'trace')` | Agent reasoning/output block (paired with `trace-end`) |
+| `trace-end` | agent trace `format()` | `excise(body, 'trace')` | Closing marker for trace block |

package/packages/marker/src/index.js

@@ -0,0 +1,184 @@
+/**
+ * Loreli marker system — machine-readable HTML comment metadata for GitHub content.
+ *
+ * Marker format: `<!-- loreli:TYPE key="value" key="value" -->`
+ *
+ * Decouples workflow-state detection from human-visible text so themed
+ * messages can change freely without breaking parsing logic.
+ *
+ * @module loreli/marker
+ */
+
+const PREFIX = 'loreli';
+
+/**
+ * HTML-entity-encode a marker value so `"`, `&`, `<`, and `>` are safe
+ * inside the `key="value"` format within an HTML comment.
+ *
+ * @param {string} value - Raw value string.
+ * @returns {string} Encoded value (no literal `"`, `&`, `<`, or `>`).
+ */
+function encode(value) {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+/**
+ * Decode HTML entities produced by {@link encode} back to raw characters.
+ *
+ * @param {string} value - Encoded value string.
+ * @returns {string} Original value with entities resolved.
+ */
+function decode(value) {
+  return value
+    .replaceAll('&quot;', '"')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+}
+
+/**
+ * Matches a loreli marker with a specific type.
+ * Capture group 1: the key-value payload (may be empty).
+ *
+ * @param {string} type - Marker type to target.
+ * @returns {RegExp}
+ */
+function regex(type) {
+  return new RegExp(`<!-- ${PREFIX}:${type}((?:\\s+\\w+="[^"]*")*) -->`);
+}
+
+/**
+ * Parses `key="value"` pairs from the raw payload string captured by {@link regex}.
+ * Values are HTML-entity-decoded so callers receive the original strings.
+ *
+ * @param {string} raw - Space-separated key="value" string.
+ * @returns {Object<string, string>}
+ */
+function pairs(raw) {
+  const data = {};
+  const re = /(\w+)="([^"]*)"/g;
+  let m;
+  while ((m = re.exec(raw)) !== null) data[m[1]] = decode(m[2]);
+  return data;
+}
+
+/**
+ * Produces a loreli marker string. Values are HTML-entity-encoded so
+ * special characters (`"`, `&`, `<`, `>`) do not break the marker format
+ * or prematurely close the HTML comment.
+ *
+ * @param {string} type - Marker type (e.g. 'claim', 'signature', 'agent').
+ * @param {Object<string, string>} [data] - Key-value pairs to embed.
+ * @returns {string} An HTML comment marker.
+ * @throws {Error} If type is falsy or empty.
+ */
+export function mark(type, data) {
+  if (!type) throw new Error('type is required');
+
+  const entries = Object.entries(data ?? {});
+  const payload = entries.length
+    ? ' ' + entries.map(function pair([k, v]) { return `${k}="${encode(v)}"`; }).join(' ')
+    : '';
+
+  return `<!-- ${PREFIX}:${type}${payload} -->`;
+}
+
+/**
+ * Checks whether a body contains a marker of the given type.
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to look for.
+ * @returns {boolean}
+ */
+export function has(body, type) {
+  if (!body) return false;
+  return regex(type).test(body);
+}
+
+/**
+ * Extracts the key-value data from the first marker of the given type.
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to extract.
+ * @returns {Object<string, string> | null} Parsed data, or null if not found.
+ */
+export function parse(body, type) {
+  if (!body) return null;
+  const m = body.match(regex(type));
+  if (!m) return null;
+  return pairs(m[1]);
+}
+
+/**
+ * Removes the first marker of the given type and everything after it,
+ * trimming trailing whitespace from the remaining content.
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to strip from.
+ * @returns {string | null | undefined} Body with marker and trailing content removed.
+ */
+export function strip(body, type) {
+  if (body == null || body === '') return body;
+  const idx = body.search(regex(type));
+  if (idx === -1) return body;
+  return body.slice(0, idx).trimEnd();
+}
+
+/**
+ * Removes the last marker of the given type and everything after it,
+ * trimming trailing whitespace from the remaining content.
+ *
+ * Use when multiple markers exist and only the trailing one should be
+ * removed (e.g. duplicate signatures at end of body).
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to strip from.
+ * @returns {string | null | undefined} Body with last marker and trailing content removed.
+ */
+export function stripLast(body, type) {
+  if (body == null || body === '') return body;
+  const re = new RegExp(regex(type).source, 'g');
+  let lastIdx = -1;
+  let m;
+  while ((m = re.exec(body)) !== null) lastIdx = m.index;
+  if (lastIdx === -1) return body;
+  return body.slice(0, lastIdx).trimEnd();
+}
+
+/**
+ * Removes content between paired markers of the given type.
+ *
+ * Finds the opening `<!-- loreli:TYPE ... -->` and the closing
+ * `<!-- loreli:TYPE-end -->`, removes both markers and everything
+ * between them, and collapses extra blank lines at the join point.
+ *
+ * Unlike {@link strip}, which removes a marker and everything after it,
+ * `excise` removes only the delimited section and preserves content on
+ * both sides. Designed for trace blocks and other self-contained sections
+ * embedded within larger bodies.
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to excise (matches TYPE and TYPE-end).
+ * @returns {string | null | undefined} Body with the marker-delimited section removed.
+ */
+export function excise(body, type) {
+  if (body == null || body === '') return body;
+  const startIdx = body.search(regex(type));
+  if (startIdx === -1) return body;
+
+  const endMarker = new RegExp(`<!-- ${PREFIX}:${type}-end -->`);
+  const after = body.slice(startIdx);
+  const endMatch = endMarker.exec(after);
+  if (!endMatch) return body;
+
+  const endIdx = startIdx + endMatch.index + endMatch[0].length;
+  const before = body.slice(0, startIdx);
+  const rest = body.slice(endIdx);
+
+  // Collapse extra blank lines at the join point
+  return (before.replace(/\n+$/, '') + rest.replace(/^\n+/, '\n')).trim();
+}