loreli 0.0.0 → 2.0.0

package/packages/config/src/defaults.js

@@ -0,0 +1,145 @@
+import ms from 'ms';
+
+/**
+ * Built-in defaults for every configurable value in Loreli.
+ * This is the lowest-priority layer in the resolution chain.
+ *
+ * Duration values use human-readable strings converted via `ms()`
+ * at module load time. All exported values are milliseconds.
+ *
+ * @type {object}
+ */
+export default {
+  repo: undefined,
+  theme: 'transformers',
+  reviewers: [],
+  model: 'balanced',
+  merge: {
+    method: 'squash',
+    hitl: false,
+    base: 'main'
+  },
+  pr: {
+    validation: {
+      command: 'npm test'
+    },
+    selfReview: {
+      enabled: true
+    }
+  },
+  hitl: {
+    timeout: ms('3d')
+  },
+  timeouts: {
+    stall: ms('10m'),
+    shutdown: ms('1m'),
+    poll: ms('2s'),
+    rapidDeath: ms('15s'),
+    proxyDiscovery: ms('5s'),
+    nudge: true
+  },
+  log: {
+    level: 'info',
+    maxSize: 10 * 1024 * 1024,
+    maxFiles: 3
+  },
+  labels: {
+    track: true,
+    extra: []
+  },
+  watch: {
+    interval: ms('1m'),
+    maxRounds: 7,
+    maxClaims: 3
+  },
+  scaling: {
+    maxAgents: 8,
+    maxPerTick: 2,
+    cooldown: ms('30s')
+  },
+  tmux: {
+    session: 'loreli',
+    capture: 500
+  },
+  backends: {
+    claude: {
+      env: {
+        CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: '1'
+      },
+      models: {
+        fast: { anthropic: 'claude-haiku-4-5-20251001' },
+        balanced: { anthropic: 'claude-sonnet-4-5-20250929' },
+        powerful: { anthropic: 'claude-opus-4-5-20251101' }
+      }
+    },
+    codex: {
+      models: {
+        fast: { openai: 'gpt-5-mini' },
+        balanced: { openai: 'gpt-5.1-codex' },
+        powerful: { openai: 'gpt-5.2-pro' }
+      }
+    },
+    cursor: {
+      models: {
+        fast: { anthropic: 'sonnet-4.5', openai: 'gpt-5.3-codex-low' },
+        balanced: { anthropic: 'sonnet-4.5-thinking', openai: 'gpt-5.3-codex' },
+        powerful: { anthropic: 'opus-4.6-thinking', openai: 'gpt-5.1-codex-max' }
+      }
+    }
+  },
+  classify: {
+    model: 'fast',
+    maxLines: 100,
+    timeout: ms('30s'),
+    maxRetries: 5
+  },
+  trace: {
+    enabled: true,
+    includeOutput: true,
+    maxOutputChars: 8000
+  },
+  agents: {
+    disallowedTools: ['gh', 'curl']
+  },
+  proofOfLife: {
+    timeout: ms('5m')
+  },
+  workspace: {
+    cleanup: false
+  },
+  cleanup: {
+    retention: ms('12h'),
+    autoprune: true
+  },
+  workflows: {
+    action: {
+      model: 'balanced',
+      maxAgents: 3
+    },
+    reviewer: {
+      model: 'balanced',
+      maxAgents: 2,
+      trace: { enabled: true, maxOutputChars: 4000 }
+    },
+    risk: {
+      model: 'fast',
+      maxAgents: 3,
+      skip: false,
+      trace: { enabled: true, maxOutputChars: 2000 }
+    },
+    planner: {
+      model: 'powerful',
+      maxAgents: 1,
+      trace: { enabled: true, maxOutputChars: 4000 }
+    }
+  },
+  feedback: {
+    enabled: true,
+    threshold: 5,
+    categories: ['naming', 'architecture', 'testing', 'documentation', 'performance', 'security'],
+    hitl: false
+  },
+  github: {
+    token: undefined
+  }
+};

package/packages/config/src/index.js

@@ -0,0 +1,223 @@
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { parse } from 'yaml';
+import { logger } from 'loreli/log';
+import defaults from './defaults.js';
+import { validate } from './schema.js';
+
+const log = logger('config');
+
+export { defaults };
+export { validate };
+export * as check from './validate.js';
+
+/**
+ * Load a `.env` file into `process.env` using Node's built-in parser.
+ * Variables already present in `process.env` are not overwritten.
+ *
+ * @param {string} [path='.env'] - Absolute or relative path to the env file.
+ * @returns {boolean} True if the file was loaded, false if it does not exist.
+ */
+export function loadEnv(path = '.env') {
+  try {
+    process.loadEnvFile(resolve(path));
+    return true;
+  } catch (err) {
+    // ENOENT means the file simply doesn't exist — not an error worth surfacing
+    if (err?.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+/**
+ * Centralized configuration for Loreli.
+ *
+ * Resolution order (highest priority wins):
+ * 1. Start tool params (via merge())
+ * 2. loreli.yml from target repo (via load())
+ * 3. Environment variables
+ * 4. Built-in defaults
+ *
+ * @example
+ * ```js
+ * const config = new Config();
+ * await config.load(hub, 'owner/repo');
+ * config.merge({ theme: 'pokemon' });
+ * config.get('theme');           // 'pokemon'
+ * config.get('timeouts.stall');  // 600000
+ * ```
+ */
+export class Config {
+  constructor() {
+    /** @type {object} Values from loreli.yml (validated). */
+    this.file = {};
+
+    /** @type {object} Values from start params (overrides). */
+    this.overrides = {};
+
+    /** @type {boolean} Whether loreli.yml was found in the repo. */
+    this.found = false;
+  }
+
+  /**
+   * Load config from a target repo via hub.read().
+   * Returns gracefully if the file does not exist or is unparseable.
+   *
+   * @param {object} hub - Hub instance with a read() method.
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {string} [path='loreli.yml'] - File path within the repo.
+   * @returns {Promise<boolean>} True if config was found and parsed, false otherwise.
+   */
+  async load(hub, repo, path = 'loreli.yml') {
+    try {
+      const result = await hub.read(repo, path);
+      const raw = parse(result.content);
+      this.file = validate(raw);
+      this.found = true;
+    } catch (err) {
+      if (err?.status !== 404 && err?.code !== 'ENOENT') {
+        log.warn(`config load failed for ${repo}/${path}: ${err.message}`);
+      }
+      this.file = {};
+      this.found = false;
+    }
+    return this.found;
+  }
+
+  /**
+   * Load config from a local loreli.yml path.
+   * Returns gracefully if the file does not exist or is unparseable.
+   *
+   * @param {string} [path='loreli.yml'] - Absolute or relative file path.
+   * @returns {boolean} True if config was found and parsed, false otherwise.
+   */
+  loadLocal(path = 'loreli.yml') {
+    try {
+      const content = readFileSync(resolve(path), 'utf8');
+      const raw = parse(content);
+      this.file = validate(raw);
+      this.found = true;
+    } catch (err) {
+      if (err?.code !== 'ENOENT') {
+        log.warn(`config loadLocal failed for ${path}: ${err.message}`);
+      }
+      this.file = {};
+      this.found = false;
+    }
+
+    return this.found;
+  }
+
+  /**
+   * Merge start params or other overrides on top.
+   * Nested objects are shallow-merged one level deep.
+   *
+   * @param {object} overrides - Plain object of override values.
+   */
+  merge(overrides) {
+    if (!overrides || typeof overrides !== 'object') return;
+    this.overrides = validate(overrides);
+  }
+
+  /**
+   * Resolve a config value through all layers.
+   * Supports dot-notation for nested keys (e.g. 'merge.hitl').
+   *
+   * Resolution: overrides > file > env > defaults.
+   *
+   * @param {string} path - Dot-notation key path.
+   * @returns {*} The resolved value.
+   */
+  get(path) {
+    const parts = path.split('.');
+
+    // Check overrides first
+    const fromOverrides = dig(this.overrides, parts);
+    if (fromOverrides !== undefined) return fromOverrides;
+
+    // Check file layer
+    const fromFile = dig(this.file, parts);
+    if (fromFile !== undefined) return fromFile;
+
+    // Check environment variables
+    const fromEnv = env(path);
+    if (fromEnv !== undefined) return fromEnv;
+
+    // Fall through to defaults
+    return dig(defaults, parts);
+  }
+
+  /**
+   * Serialize the fully resolved config to a plain object.
+   * Walks every default key and resolves each through the layer chain.
+   *
+   * @returns {object} Fully resolved config.
+   */
+  toJSON() {
+    return walk(defaults, '', this);
+  }
+}
+
+/**
+ * Recursively resolve all keys in a template object.
+ * Uses the default object as a schema to know which keys to resolve.
+ *
+ * @param {object} template - Defaults object defining the key structure.
+ * @param {string} prefix - Dot-notation prefix for nested keys.
+ * @param {Config} config - Config instance to resolve through.
+ * @returns {object} Resolved object.
+ */
+function walk(template, prefix, config) {
+  const out = {};
+
+  for (const [key, value] of Object.entries(template)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      out[key] = walk(value, path, config);
+    } else {
+      out[key] = config.get(path);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Navigate into a nested object using an array of key segments.
+ *
+ * @param {object} obj - Object to navigate.
+ * @param {string[]} parts - Key segments.
+ * @returns {*} The value at the path, or undefined.
+ */
+function dig(obj, parts) {
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Map config paths to environment variable names.
+ * Only a subset of config values are env-overridable.
+ *
+ * @param {string} path - Config path (dot-notation).
+ * @returns {*} Parsed env value, or undefined.
+ */
+function env(path) {
+  const mapping = {
+    repo: 'LORELI_REPO',
+    'log.level': 'LORELI_LOG_LEVEL',
+    'github.token': 'GITHUB_TOKEN'
+  };
+
+  const varName = mapping[path];
+  if (!varName) return undefined;
+
+  const value = process.env[varName];
+  if (value === undefined) return undefined;
+
+  return value;
+}

package/packages/config/src/schema.js

@@ -0,0 +1,291 @@
+import ms from 'ms';
+
+/**
+ * Valid merge methods supported by GitHub.
+ * @type {Set<string>}
+ */
+const MERGE_METHODS = new Set(['merge', 'squash', 'rebase']);
+
+/**
+ * Pattern for valid "owner/name" repository format.
+ * @type {RegExp}
+ */
+const REPO_RE = /^[^/]+\/[^/]+$/;
+
+/**
+ * Validates and normalizes a raw config object parsed from loreli.yml.
+ * Ensures types are correct and unknown keys are stripped.
+ *
+ * Duration fields accept both human-readable strings ('10m', '3d')
+ * and raw millisecond numbers. All are normalized to milliseconds.
+ *
+ * @param {object} raw - Parsed YAML content.
+ * @returns {object} Normalized config object with only known keys.
+ */
+export function validate(raw) {
+  if (!raw || typeof raw !== 'object') return {};
+
+  const out = {};
+
+  if (typeof raw.repo === 'string' && REPO_RE.test(raw.repo)) out.repo = raw.repo;
+
+  if (typeof raw.theme === 'string') {
+    out.theme = raw.theme;
+  } else if (Array.isArray(raw.theme)) {
+    const valid = raw.theme.filter(function isString(t) { return typeof t === 'string'; });
+    if (valid.length) out.theme = valid.length === 1 ? valid[0] : valid;
+  }
+
+  if (typeof raw.model === 'string') out.model = raw.model;
+
+  if (Array.isArray(raw.reviewers)) {
+    out.reviewers = raw.reviewers.filter(function isString(r) {
+      return typeof r === 'string';
+    });
+  }
+
+  if (raw.merge && typeof raw.merge === 'object') {
+    out.merge = {};
+    if (typeof raw.merge.method === 'string' && MERGE_METHODS.has(raw.merge.method)) out.merge.method = raw.merge.method;
+    if (typeof raw.merge.base === 'string') out.merge.base = raw.merge.base;
+
+    if (typeof raw.merge.hitl === 'boolean') {
+      out.merge.hitl = raw.merge.hitl;
+    } else if (raw.merge.gate === 'human') {
+      out.merge.hitl = true;
+    } else if (typeof raw.merge.gate === 'string') {
+      out.merge.hitl = false;
+    }
+  }
+
+  if (raw.pr && typeof raw.pr === 'object') {
+    const pr = {};
+
+    if (raw.pr.validation && typeof raw.pr.validation === 'object') {
+      const validation = {};
+      if (typeof raw.pr.validation.command === 'string') {
+        validation.command = raw.pr.validation.command;
+      }
+      if (Object.keys(validation).length) pr.validation = validation;
+    }
+
+    if (raw.pr.selfReview && typeof raw.pr.selfReview === 'object') {
+      const selfReview = {};
+      if (typeof raw.pr.selfReview.enabled === 'boolean') {
+        selfReview.enabled = raw.pr.selfReview.enabled;
+      }
+      if (Object.keys(selfReview).length) pr.selfReview = selfReview;
+    }
+
+    if (Object.keys(pr).length) out.pr = pr;
+  }
+
+  if (raw.hitl && typeof raw.hitl === 'object') {
+    out.hitl = {};
+    if (raw.hitl.timeout === null) {
+      out.hitl.timeout = null;
+    } else {
+      const v = raw.hitl.timeout;
+      try { out.hitl.timeout = typeof v === 'number' ? v : ms(v); } catch { /* invalid — falls to default */ }
+    }
+  }
+
+  if (raw.timeouts && typeof raw.timeouts === 'object') {
+    out.timeouts = {};
+    for (const key of ['stall', 'shutdown', 'poll', 'rapidDeath', 'proxyDiscovery']) {
+      const v = raw.timeouts[key];
+      if (v == null) continue;
+      try { out.timeouts[key] = typeof v === 'number' ? v : ms(v); } catch { /* invalid — falls to default */ }
+    }
+    if (typeof raw.timeouts.nudge === 'boolean') out.timeouts.nudge = raw.timeouts.nudge;
+  }
+
+  if (raw.log && typeof raw.log === 'object') {
+    out.log = {};
+    if (typeof raw.log.level === 'string') out.log.level = raw.log.level;
+    if (typeof raw.log.maxSize === 'number') out.log.maxSize = raw.log.maxSize;
+    if (typeof raw.log.maxFiles === 'number') out.log.maxFiles = raw.log.maxFiles;
+  }
+
+  if (raw.labels && typeof raw.labels === 'object') {
+    out.labels = {};
+    if (typeof raw.labels.track === 'boolean') out.labels.track = raw.labels.track;
+    if (Array.isArray(raw.labels.extra)) {
+      out.labels.extra = raw.labels.extra.filter(function isString(l) {
+        return typeof l === 'string';
+      });
+    }
+  }
+
+  if (raw.watch && typeof raw.watch === 'object') {
+    out.watch = {};
+    const v = raw.watch.interval;
+    if (v != null) {
+      try { out.watch.interval = typeof v === 'number' ? v : ms(v); } catch { /* invalid — falls to default */ }
+    }
+    if (typeof raw.watch.maxRounds === 'number') out.watch.maxRounds = raw.watch.maxRounds;
+    if (typeof raw.watch.maxClaims === 'number' && raw.watch.maxClaims > 0) out.watch.maxClaims = raw.watch.maxClaims;
+  }
+
+  if (raw.scaling && typeof raw.scaling === 'object') {
+    out.scaling = {};
+    if (typeof raw.scaling.maxAgents === 'number') out.scaling.maxAgents = raw.scaling.maxAgents;
+    if (typeof raw.scaling.maxPerTick === 'number') out.scaling.maxPerTick = raw.scaling.maxPerTick;
+
+    const cd = raw.scaling.cooldown;
+    if (cd != null) {
+      try { out.scaling.cooldown = typeof cd === 'number' ? cd : ms(cd); } catch { /* invalid — falls to default */ }
+    }
+
+    if (!Object.keys(out.scaling).length) delete out.scaling;
+  }
+
+  if (raw.tmux && typeof raw.tmux === 'object') {
+    out.tmux = {};
+    if (typeof raw.tmux.session === 'string') out.tmux.session = raw.tmux.session;
+    if (typeof raw.tmux.capture === 'number') out.tmux.capture = raw.tmux.capture;
+  }
+
+  if (raw.backends && typeof raw.backends === 'object') {
+    out.backends = {};
+    for (const [name, backend] of Object.entries(raw.backends)) {
+      if (!backend || typeof backend !== 'object') continue;
+
+      const entry = {};
+
+      // Validate models: three-level nested object (tier → provider → string)
+      if (backend.models && typeof backend.models === 'object') {
+        const models = {};
+        for (const [tier, providers] of Object.entries(backend.models)) {
+          if (!providers || typeof providers !== 'object') continue;
+
+          const validated = {};
+          for (const [provider, modelId] of Object.entries(providers)) {
+            if (typeof modelId === 'string') validated[provider] = modelId;
+          }
+
+          if (Object.keys(validated).length) models[tier] = validated;
+        }
+
+        if (Object.keys(models).length) entry.models = models;
+      }
+
+      // Validate env: flat string-to-string map (optional, user-configured only)
+      if (backend.env && typeof backend.env === 'object') {
+        const env = {};
+        for (const [key, val] of Object.entries(backend.env)) {
+          if (typeof val === 'string') env[key] = val;
+        }
+
+        if (Object.keys(env).length) entry.env = env;
+      }
+
+      if (Object.keys(entry).length) out.backends[name] = entry;
+    }
+
+    // Strip empty backends to avoid overriding defaults with nothing
+    if (!Object.keys(out.backends).length) delete out.backends;
+  }
+
+  if (raw.classify && typeof raw.classify === 'object') {
+    out.classify = {};
+    if (typeof raw.classify.model === 'string') out.classify.model = raw.classify.model;
+    if (typeof raw.classify.maxLines === 'number' && raw.classify.maxLines > 0) out.classify.maxLines = raw.classify.maxLines;
+    if (typeof raw.classify.maxRetries === 'number' && raw.classify.maxRetries > 0) out.classify.maxRetries = raw.classify.maxRetries;
+    const t = raw.classify.timeout;
+    if (t != null) {
+      try { out.classify.timeout = typeof t === 'number' ? t : ms(t); } catch { /* invalid — falls to default */ }
+    }
+    if (!Object.keys(out.classify).length) delete out.classify;
+  }
+
+  if (raw.trace && typeof raw.trace === 'object') {
+    out.trace = {};
+    if (typeof raw.trace.enabled === 'boolean') out.trace.enabled = raw.trace.enabled;
+    if (typeof raw.trace.includeOutput === 'boolean') out.trace.includeOutput = raw.trace.includeOutput;
+    if (typeof raw.trace.maxOutputChars === 'number') out.trace.maxOutputChars = raw.trace.maxOutputChars;
+  }
+
+  if (raw.agents && typeof raw.agents === 'object') {
+    const agents = {};
+    if (Array.isArray(raw.agents.disallowedTools)) {
+      agents.disallowedTools = raw.agents.disallowedTools.filter(
+        function isString(t) { return typeof t === 'string'; }
+      );
+    }
+    if (Object.keys(agents).length) out.agents = agents;
+  }
+
+  if (raw.proofOfLife && typeof raw.proofOfLife === 'object') {
+    out.proofOfLife = {};
+    const t = raw.proofOfLife.timeout;
+    if (t != null) {
+      try { out.proofOfLife.timeout = typeof t === 'number' ? t : ms(t); } catch { /* invalid — falls to default */ }
+    }
+  }
+
+  if (raw.feedback && typeof raw.feedback === 'object') {
+    out.feedback = {};
+    if (typeof raw.feedback.enabled === 'boolean') out.feedback.enabled = raw.feedback.enabled;
+    if (typeof raw.feedback.threshold === 'number' && raw.feedback.threshold > 0) {
+      out.feedback.threshold = raw.feedback.threshold;
+    }
+    if (Array.isArray(raw.feedback.categories)) {
+      out.feedback.categories = raw.feedback.categories.filter(
+        function isString(c) { return typeof c === 'string'; }
+      );
+    }
+    if (typeof raw.feedback.hitl === 'boolean') {
+      out.feedback.hitl = raw.feedback.hitl;
+    } else if (Array.isArray(raw.feedback.hitl)) {
+      out.feedback.hitl = raw.feedback.hitl.filter(
+        function isString(c) { return typeof c === 'string'; }
+      );
+    }
+  }
+
+  if (raw.workspace && typeof raw.workspace === 'object') {
+    out.workspace = {};
+    if (typeof raw.workspace.cleanup === 'boolean') out.workspace.cleanup = raw.workspace.cleanup;
+  }
+
+  if (raw.cleanup && typeof raw.cleanup === 'object') {
+    out.cleanup = {};
+    const ret = raw.cleanup.retention;
+    if (ret != null) {
+      try { out.cleanup.retention = typeof ret === 'number' ? ret : ms(ret); } catch { /* invalid — falls to default */ }
+    }
+    if (typeof raw.cleanup.autoprune === 'boolean') out.cleanup.autoprune = raw.cleanup.autoprune;
+  }
+
+  if (raw.workflows && typeof raw.workflows === 'object') {
+    const workflows = {};
+    for (const role of ['action', 'reviewer', 'risk', 'planner']) {
+      const wf = raw.workflows[role];
+      if (!wf || typeof wf !== 'object') continue;
+
+      const entry = {};
+      if (typeof wf.model === 'string') entry.model = wf.model;
+      if (typeof wf.maxAgents === 'number') entry.maxAgents = wf.maxAgents;
+      if (typeof wf.prompt === 'string') entry.prompt = wf.prompt;
+      if (typeof wf.skip === 'boolean') entry.skip = wf.skip;
+
+      if (wf.trace && typeof wf.trace === 'object') {
+        const trace = {};
+        if (typeof wf.trace.enabled === 'boolean') trace.enabled = wf.trace.enabled;
+        if (typeof wf.trace.maxOutputChars === 'number') trace.maxOutputChars = wf.trace.maxOutputChars;
+        if (Object.keys(trace).length) entry.trace = trace;
+      }
+
+      if (Object.keys(entry).length) workflows[role] = entry;
+    }
+    if (Object.keys(workflows).length) out.workflows = workflows;
+  }
+
+  if (raw.github && typeof raw.github === 'object') {
+    out.github = {};
+    if (typeof raw.github.token === 'string' && raw.github.token.length > 0) out.github.token = raw.github.token;
+  }
+
+  return out;
+}