loreli 0.0.0 → 2.0.0

package/packages/session/src/index.js

@@ -0,0 +1,215 @@
+import { mkdir, writeFile, readFile, readdir, rename, rm, unlink, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/**
+ * Persistent session storage for detached agents.
+ *
+ * Writes session and agent state to ~/.loreli/ (or LORELI_HOME)
+ * so agents survive orchestrator shutdown and can be reconnected.
+ *
+ * Directory layout:
+ * ```
+ * ~/.loreli/sessions/<id>/
+ *   config.json
+ *   agents/
+ *     optimus-0.json
+ *     megatron-0.json
+ *   registry.json
+ * ```
+ */
+export class Storage {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.home] - Override the base directory.
+   */
+  constructor(opts = {}) {
+    /** @type {string} Base storage directory. */
+    this.home = opts.home ?? process.env.LORELI_HOME ?? join(homedir(), '.loreli');
+  }
+
+  /**
+   * Initialize a session directory.
+   *
+   * @param {string} id - Session ID.
+   * @param {object} [config] - Session config to persist.
+   * @returns {Promise<string>} The session ID.
+   */
+  async init(id, config = {}) {
+    const dir = this.sessionDir(id);
+    await mkdir(join(dir, 'agents'), { recursive: true });
+    await mkdir(join(dir, 'logs'), { recursive: true });
+
+    const safe = { ...config };
+    if (safe.github) {
+      safe.github = { ...safe.github };
+      delete safe.github.token;
+    }
+
+    const configPath = join(dir, 'config.json');
+    await this.atomic(configPath, JSON.stringify({
+      id,
+      created: new Date().toISOString(),
+      ...safe
+    }, null, 2));
+
+    return id;
+  }
+
+  /**
+   * Save agent state to disk.
+   *
+   * @param {string} sessionId - Session ID.
+   * @param {string} agentName - Agent identity name.
+   * @param {object} data - Agent state data.
+   * @returns {Promise<void>}
+   */
+  async save(sessionId, agentName, data) {
+    const filePath = join(this.sessionDir(sessionId), 'agents', `${agentName}.json`);
+    await this.atomic(filePath, JSON.stringify(data, null, 2));
+  }
+
+  /**
+   * Load agent state from disk.
+   *
+   * @param {string} sessionId - Session ID.
+   * @param {string} agentName - Agent identity name.
+   * @returns {Promise<object>} Parsed agent state data.
+   */
+  async load(sessionId, agentName) {
+    const filePath = join(this.sessionDir(sessionId), 'agents', `${agentName}.json`);
+    try {
+      const content = await readFile(filePath, 'utf8');
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * List all agent files in a session.
+   *
+   * @param {string} sessionId - Session ID.
+   * @returns {Promise<string[]>} Array of agent names.
+   */
+  async agents(sessionId) {
+    const dir = join(this.sessionDir(sessionId), 'agents');
+    try {
+      const files = await readdir(dir);
+      return files.filter(function isJson(f) { return f.endsWith('.json'); })
+        .map(function stripExt(f) { return f.replace('.json', ''); });
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * List all session IDs.
+   *
+   * @returns {Promise<string[]>} Array of session ID strings.
+   */
+  async sessions() {
+    const dir = join(this.home, 'sessions');
+    try {
+      return await readdir(dir);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Get the directory path for a session.
+   *
+   * @param {string} id - Session ID.
+   * @returns {string} Absolute path to the session directory.
+   */
+  sessionDir(id) {
+    return join(this.home, 'sessions', id);
+  }
+
+  /**
+   * Remove a single session and all its contents.
+   *
+   * @param {string} id - Session ID to remove.
+   * @returns {Promise<void>}
+   */
+  async remove(id) {
+    await rm(this.sessionDir(id), { recursive: true, force: true });
+  }
+
+  /**
+   * Prune sessions older than a given age.
+   *
+   * Reads each session's `config.json` for the `created` timestamp.
+   * Sessions older than `maxAge` milliseconds are removed. Sessions
+   * with missing or unparseable config are treated as stale and pruned.
+   *
+   * @param {number} maxAge - Maximum age in milliseconds.
+   * @returns {Promise<string[]>} IDs of pruned sessions.
+   */
+  async prune(maxAge) {
+    const ids = await this.sessions();
+    const now = Date.now();
+    const pruned = [];
+
+    for (const id of ids) {
+      let created = 0;
+      try {
+        const raw = await readFile(join(this.sessionDir(id), 'config.json'), 'utf8');
+        const config = JSON.parse(raw);
+        created = new Date(config.created).getTime();
+      } catch {
+        // Missing or invalid config — treat as infinitely old
+      }
+
+      if (now - created > maxAge) {
+        await this.remove(id);
+        pruned.push(id);
+      }
+    }
+
+    return pruned;
+  }
+
+  /**
+   * Remove known stray files from the loreli home root.
+   *
+   * Files like `mcp-ready` can end up at the home root level when
+   * the MCP server's cwd happens to be `~/.loreli`. This sweeps
+   * only files from a known allowlist — directories and unknown
+   * files are left untouched.
+   *
+   * @returns {Promise<string[]>} Names of removed files.
+   */
+  async sweep() {
+    const STRAYS = ['mcp-ready'];
+    const removed = [];
+
+    for (const name of STRAYS) {
+      const path = join(this.home, name);
+      try {
+        const s = await stat(path);
+        if (!s.isFile()) continue;
+        await unlink(path);
+        removed.push(name);
+      } catch {
+        // File doesn't exist — nothing to sweep
+      }
+    }
+
+    return removed;
+  }
+
+  /**
+   * Write a file atomically (temp file + rename).
+   *
+   * @param {string} filePath - Target file path.
+   * @param {string} content - File content.
+   * @returns {Promise<void>}
+   */
+  async atomic(filePath, content) {
+    const tmp = `${filePath}.tmp`;
+    await writeFile(tmp, content, 'utf8');
+    await rename(tmp, filePath);
+  }
+}

package/packages/test-utils/README.md

@@ -0,0 +1,96 @@
+# loreli/test-utils
+
+Shared test infrastructure for Loreli integration tests. Consolidates helpers from `hub/test/helpers.js` and `mcp/test/helpers.js` into a single canonical location.
+
+## API Reference
+
+### Constants
+
+| Name | Description |
+|------|-------------|
+| `TEST_REPO` | Test repository — set via `LORELI_TEST_REPO` env var (no default; tests skip when unset) |
+| `TEST_SESSION` | Tmux session name for test agents (`loreli-test-<pid>`) |
+
+## Test Modes
+
+Set `LORELI_TEST_MODE=unit` to disable agentic tests that require real CLI backends. This matters for CI environments where LLM CLIs are unavailable or expensive, and you should expect backend-dependent suites to skip with a clear reason when this mode is active.
+
+### Functions
+
+#### `testIdentity()` → Identity
+
+Create a stable test identity for integration tests. All automated test interactions use this identity.
+
+#### `ensureTestLabels(hub, repo)` → Promise\<void\>
+
+Ensure the test identity's labels exist in the test repository. Must be called once before scoped hub operations.
+
+#### `agenticSkipReason()` → string | false
+
+Return a skip reason when agentic tests are disabled.
+
+#### `skipWithoutToken(t)` → boolean
+
+Skip guard for tests requiring `GITHUB_TOKEN`.
+
+#### `skipWithoutTestRepo(t)` → boolean
+
+Skip guard for tests requiring `LORELI_TEST_REPO`.
+
+#### `skipWithoutBackends(t, backends)` → Promise\<boolean\>
+
+Skip guard for tests requiring real CLI backends (claude, codex, etc.) on PATH and a working tmux install. This guard skips immediately when `LORELI_TEST_MODE=unit`.
+
+#### `createHub()` → GitHubHub
+
+Create a real GitHubHub instance from the environment token.
+
+#### `createConfig(hub?, overrides?)` → Promise\<Config\>
+
+Create a real Config instance, optionally loading from the test repo.
+
+#### `createAgent(backends, registry, role, provider?, opts?)` → Promise\<object\>
+
+Discover real backends and create a real agent for the given provider and role. Agents are assigned to the `loreli-test` tmux session.
+
+#### `createTmpDir(prefix?)` → Promise\<string\>
+
+Create a temporary directory for test artifacts.
+
+#### `resetTestSession()` → Promise\<void\>
+
+Kill and recreate the test tmux session with retry logic.
+
+#### `killTestSession()` → Promise\<void\>
+
+Kill the test tmux session entirely.
+
+### Classes
+
+#### `Cleanup`
+
+Tracks GitHub resources (issues, PRs, branches, discussions) created during tests and provides `flush()` for best-effort cleanup.
+
+The example below demonstrates tracking a created issue for cleanup. This matters because integration tests create real GitHub resources, and you should expect `flush()` to close or delete tracked items without throwing even if some were already removed.
+
+```js
+const cleanup = new Cleanup(hub, TEST_REPO);
+cleanup.issues.push(issue.number);
+await cleanup.flush();
+```
+
+### Re-exports
+
+This package re-exports core classes used frequently in integration tests so test files can import from one place:
+
+- `GitHubHub` (from `loreli/hub`)
+- `Config` (from `loreli/config`)
+- `Identity`, `Registry` (from `loreli/identity`)
+- `BackendRegistry` (from `loreli/agent`)
+- `Storage` (from `loreli/session`)
+
+## Scope Boundary
+
+**In scope**: Test skip guards, GitHub resource cleanup, agent creation helpers, tmux session management, test identity.
+
+**Out of scope**: Test framework configuration, assertions, test runner setup.

package/packages/test-utils/src/index.js

@@ -0,0 +1,354 @@
+/**
+ * Consolidated test infrastructure for loreli integration tests.
+ *
+ * Combines helpers from hub/test/helpers.js and mcp/test/helpers.js
+ * into a single canonical location. Uses real backends, real GitHub,
+ * and real agents — no stubs, no mocks.
+ */
+import { mkdtemp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { GitHubHub, definitions } from 'loreli/hub';
+import { Config } from 'loreli/config';
+import { Identity, Registry } from 'loreli/identity';
+import { BackendRegistry } from 'loreli/agent';
+import { Storage } from 'loreli/session';
+import { Tmux } from 'loreli/tmux';
+
+/**
+ * Test repository — set via LORELI_TEST_REPO env var.
+ * No default is provided to avoid leaking org-specific names.
+ *
+ * @type {string|undefined}
+ */
+export const TEST_REPO = process.env.LORELI_TEST_REPO;
+
+/**
+ * Tmux session name used by all test agents. Isolated from the
+ * production `loreli` session to prevent cross-contamination.
+ *
+ * Appends process.pid so parallel test processes get their own
+ * tmux sessions — prevents "can't find pane" and "duplicate session"
+ * errors when multiple test files share the same name.
+ *
+ * @type {string}
+ */
+export const TEST_SESSION = `loreli-test-${process.pid}`;
+
+// ── Identity & Labels ───────────────────────────────────
+
+/**
+ * Create a stable test identity for integration tests.
+ * All automated test interactions use this identity so every
+ * issue, PR, comment, and review carries a signature and labels.
+ *
+ * @returns {Identity} A test-runner identity.
+ */
+export function testIdentity() {
+  return new Identity({
+    name: 'test-runner', instance: 0, faction: 'autobots',
+    provider: 'loreli', model: 'integration-test', theme: 'transformers'
+  });
+}
+
+/**
+ * Ensure the test identity's labels exist in the test repository.
+ * Must be called once before any scoped hub operations in tests.
+ *
+ * @param {GitHubHub} hub - Real hub instance.
+ * @param {string} repo - "owner/name" repository string.
+ * @returns {Promise<void>}
+ */
+export async function ensureTestLabels(hub, repo) {
+  const id = testIdentity();
+  await hub.ensure(repo, definitions(id.labels('action')));
+}
+
+// ── Skip Guards ─────────────────────────────────────────
+
+/**
+ * Resolve the current test mode from the environment.
+ *
+ * @returns {string} Normalized test mode string.
+ */
+function testMode() {
+  const raw = process.env.LORELI_TEST_MODE ?? 'full';
+  const normalized = raw.trim().toLowerCase();
+  return normalized.length ? normalized : 'full';
+}
+
+/**
+ * Return a skip reason when agentic tests are disabled.
+ *
+ * @returns {string|false} Skip reason string or false when enabled.
+ */
+export function agenticSkipReason() {
+  if (testMode() !== 'unit') return false;
+  return 'Agentic tests disabled (LORELI_TEST_MODE=unit)';
+}
+
+/**
+ * Skip guard — call at the start of tests that need GitHub.
+ *
+ * @param {object} t - Test context with skip().
+ * @returns {boolean} True if the test should be skipped.
+ */
+export function skipWithoutToken(t) {
+  if (!process.env.GITHUB_TOKEN) {
+    t.skip('GITHUB_TOKEN not set');
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Skip guard — call at the start of tests that need a test repo.
+ *
+ * @param {object} t - Test context with skip().
+ * @returns {boolean} True if the test should be skipped.
+ */
+export function skipWithoutTestRepo(t) {
+  if (!TEST_REPO) {
+    t.skip('LORELI_TEST_REPO not set');
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Skip guard for tests that need real backends (claude, codex, etc.)
+ * on PATH and a working tmux install. Discovers backends and returns
+ * true if none are found or tmux is missing.
+ *
+ * @param {object} t - Test context with skip().
+ * @param {BackendRegistry} backends - Backend registry instance.
+ * @returns {Promise<boolean>} True if the test should be skipped.
+ */
+export async function skipWithoutBackends(t, backends) {
+  const reason = agenticSkipReason();
+  if (reason) {
+    t.skip(reason);
+    return true;
+  }
+  if (!Tmux.available()) {
+    t.skip('tmux not available');
+    return true;
+  }
+
+  await backends.discover();
+  if (!backends.available().length) {
+    t.skip('No CLI backends available (install claude or codex)');
+    return true;
+  }
+  return false;
+}
+
+// ── Factory Helpers ─────────────────────────────────────
+
+/**
+ * Create a real GitHubHub instance from the environment token.
+ *
+ * @returns {GitHubHub}
+ */
+export function createHub() {
+  return new GitHubHub({ token: process.env.GITHUB_TOKEN });
+}
+
+/**
+ * Create a real Config instance, optionally loading from the test repo.
+ *
+ * @param {GitHubHub} [hub] - Hub to load loreli.yml from.
+ * @param {object} [overrides] - Overrides to merge.
+ * @returns {Promise<Config>}
+ */
+export async function createConfig(hub, overrides) {
+  const config = new Config();
+  if (hub) await config.load(hub, TEST_REPO);
+  if (overrides) config.merge(overrides);
+  return config;
+}
+
+/**
+ * Discover real backends and create a real agent for the given provider
+ * and role. Uses BackendRegistry.discover() to find what's on PATH,
+ * then creates a real agent via backendRegistry.create().
+ *
+ * Agents are assigned to the per-PID `loreli-test-<pid>` tmux
+ * session to keep test panes isolated from both production
+ * sessions and other parallel test processes.
+ *
+ * By default, `readyTimeout` is set to 0, which skips the CLI
+ * readiness poll (60s for Claude/Cursor). State-management tests
+ * don't need the CLI to initialize — they only need entries in the
+ * orchestrator's agent map. Tests that exercise real prompt delivery
+ * should pass `readyTimeout: 60000` (or omit 0) to restore the wait.
+ *
+ * @param {BackendRegistry} backends - Backend registry instance.
+ * @param {Registry} registry - Identity registry instance.
+ * @param {string} role - Agent role ('action', 'reviewer', 'planner').
+ * @param {string} [provider='openai'] - Provider for identity.
+ * @param {object} [opts] - Additional options.
+ * @param {string} [opts.backend] - Force a specific backend name.
+ * @param {string} [opts.prompt] - Override prompt text.
+ * @param {number} [opts.readyTimeout=0] - Max ms to wait for CLI readiness.
+ * @returns {Promise<object>} Real agent instance.
+ */
+export async function createAgent(backends, registry, role, provider = 'openai', opts = {}) {
+  await backends.discover();
+
+  const identity = registry.acquire('transformers', provider);
+  const cwd = await mkdtemp(join(tmpdir(), `loreli-test-${identity.name}-`));
+  const name = opts.backend ?? backends.defaultBackend();
+  const config = new Config();
+
+  return backends.create(name, {
+    identity,
+    role,
+    cwd,
+    model: 'balanced',
+    session: TEST_SESSION,
+    prompt: opts.prompt,
+    readyTimeout: opts.readyTimeout ?? 0,
+    config
+  });
+}
+
+/**
+ * Create a temporary directory for test artifacts.
+ *
+ * @param {string} [prefix='loreli-test-'] - Directory name prefix.
+ * @returns {Promise<string>} Path to the temporary directory.
+ */
+export async function createTmpDir(prefix = 'loreli-test-') {
+  return mkdtemp(join(tmpdir(), prefix));
+}
+
+// ── Tmux Session Management ─────────────────────────────
+
+/**
+ * Reset the test tmux session. Kills an existing session and creates
+ * a fresh one with generous dimensions so split-window has enough
+ * space for multiple agent panes.
+ *
+ * Test sessions are created without a command (bare session) since
+ * tests explicitly call killTestSession() in teardown — no need for
+ * tmux auto-destruction here.
+ *
+ * Uses retry logic because tmux's kill-session is asynchronous —
+ * the session name may not be fully released by the time new-session
+ * runs, causing a "duplicate session" error.
+ *
+ * @returns {Promise<void>}
+ */
+export async function resetTestSession() {
+  const { Tmux } = await import('loreli/tmux');
+  const tmux = new Tmux();
+
+  try { await tmux.kill(TEST_SESSION); } catch { /* may not exist */ }
+
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      await tmux.create(TEST_SESSION, { width: 200, height: 50 });
+      return;
+    } catch (err) {
+      // tmux reports both "duplicate session" and "already exists" depending
+      // on version — match either. Without this, fast tests outrun tmux's
+      // async session teardown and the retry logic never fires.
+      if (!err.message?.includes('duplicate session') && !err.message?.includes('already exists')) throw err;
+      try { await tmux.kill(TEST_SESSION); } catch { /* ignore */ }
+      await new Promise(function wait(r) { setTimeout(r, 100 * (attempt + 1)); });
+    }
+  }
+}
+
+/**
+ * Kill the test tmux session entirely. Call in suite-level after() hooks.
+ *
+ * @returns {Promise<void>}
+ */
+export async function killTestSession() {
+  const { Tmux } = await import('loreli/tmux');
+  const tmux = new Tmux();
+  try {
+    if (await tmux.has(TEST_SESSION)) {
+      await tmux.kill(TEST_SESSION);
+    }
+  } catch { /* session may not exist */ }
+}
+
+// ── Cleanup ─────────────────────────────────────────────
+
+/**
+ * Tracks GitHub resources created during integration tests and
+ * provides a flush() method to clean them all up.
+ */
+export class Cleanup {
+  /**
+   * @param {GitHubHub} hub - Real hub instance.
+   * @param {string} repo - "owner/name" repository string.
+   */
+  constructor(hub, repo) {
+    this.hub = hub;
+    this.repo = repo;
+
+    /** @type {number[]} Issue numbers to close. */
+    this.issues = [];
+
+    /** @type {number[]} PR numbers to close. */
+    this.prs = [];
+
+    /** @type {string[]} Branch names to delete. */
+    this.branches = [];
+
+    /** @type {string[]} Discussion node IDs to delete. */
+    this.discussions = [];
+
+    /** @type {string[]} Label names to delete. */
+    this.labels = [];
+  }
+
+  /**
+   * Clean up all tracked resources. Errors are swallowed — best-effort
+   * cleanup should not cause test failures.
+   */
+  async flush() {
+    const [owner, name] = this.repo.split('/');
+
+    for (const num of this.prs) {
+      try {
+        await this.hub.client.pulls.update({ owner, repo: name, pull_number: num, state: 'closed' });
+      } catch { /* best-effort */ }
+    }
+
+    for (const num of this.issues) {
+      try {
+        await this.hub.client.issues.update({ owner, repo: name, issue_number: num, state: 'closed' });
+      } catch { /* best-effort */ }
+    }
+
+    for (const ref of this.branches) {
+      try {
+        await this.hub.client.git.deleteRef({ owner, repo: name, ref: `heads/${ref}` });
+      } catch { /* best-effort */ }
+    }
+
+    for (const discId of this.discussions) {
+      try { await this.hub.deleteDiscussion(discId); } catch { /* best-effort */ }
+    }
+
+    for (const label of this.labels) {
+      try {
+        await this.hub.client.issues.deleteLabel({ owner, repo: name, name: label });
+      } catch { /* best-effort */ }
+    }
+
+    this.issues.length = 0;
+    this.prs.length = 0;
+    this.branches.length = 0;
+    this.discussions.length = 0;
+    this.labels.length = 0;
+  }
+}
+
+// Re-export dependencies for convenience
+export { GitHubHub, Config, Identity, Registry, BackendRegistry, Storage };