loreli 0.0.0 → 1.0.0

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 };

package/packages/tmux/README.md

@@ -0,0 +1,261 @@
+# loreli/tmux
+
+Zero-dependency Node.js wrapper for tmux with pane-level control and automatic session lifecycle management.
+
+This package exists because no adequate Node.js tmux library provides pane-level management. It wraps the `tmux` CLI binary with a clean async API, mapping each method ~1:1 to a tmux command.
+
+## Installation
+
+```bash
+pnpm add loreli
+```
+
+Requires `tmux` to be installed on the system (`brew install tmux` on macOS, `apt install tmux` on Linux).
+
+## Session Lifecycle
+
+Sessions created via `create()` are tracked in an in-memory set. This enables batch cleanup via `cleanup()` when the orchestrator shuts down gracefully. For crash recovery where in-memory state is lost, `prune()` queries tmux directly by session-name prefix.
+
+The key design insight is **no garbage default windows**. When `create()` is called with a `command` option, that command becomes the initial window's process. tmux auto-destroys a session when its last window dies, so when all agents exit, the session disappears naturally — no orphaned sessions.
+
+The following example shows the recommended spawn pattern used by Loreli's backends. The first agent creates the session, and subsequent agents join as additional windows.
+
+```js
+import { Tmux } from 'loreli/tmux';
+
+const tmux = new Tmux();
+
+// First agent IS the session's initial window — no garbage default window
+const pane1 = await tmux.create('loreli', { cwd: '/tmp', command: './agent1.sh' });
+
+// Second agent joins as an additional window
+const pane2 = await tmux.window('loreli', { cwd: '/tmp', command: './agent2.sh' });
+
+// Both agents die → tmux auto-destroys the session. No orphans.
+```
+
+## API Reference
+
+### `Tmux.available()`
+
+Static method. Returns `true` if tmux is on PATH, `false` otherwise. Does not throw.
+
+```js
+import { Tmux } from 'loreli/tmux';
+
+if (Tmux.available()) {
+  const tmux = new Tmux();
+}
+```
+
+### `new Tmux()`
+
+Creates a new Tmux instance. All subsequent methods are called on this instance. Each instance maintains its own set of tracked sessions.
+
+### Session Management
+
+#### `tmux.create(name, opts?)` → `Promise<string|void>`
+
+Create a new detached tmux session. Throws if a session with the same name already exists.
+
+When `opts.command` is provided, it becomes the initial window's process and the pane ID is returned. When no command is provided, a bare session with an empty default window is created (useful for test sessions with specific dimensions).
+
+- `name` `{string}` — The session name.
+- `opts.width` `{number}` — Initial window width (tmux `-x` flag).
+- `opts.height` `{number}` — Initial window height (tmux `-y` flag).
+- `opts.cwd` `{string}` — Working directory for the initial window.
+- `opts.command` `{string}` — Command for the initial window.
+
+The following example shows creating a session with an agent command as its initial window. The pane ID is returned so you can capture output or set options on the pane.
+
+```js
+// Agent command IS the initial window — no garbage default window
+const paneId = await tmux.create('loreli', {
+  cwd: '/tmp/workspace',
+  command: '/path/to/launch.sh'
+});
+
+// Test session with specific dimensions (no command — bare session)
+await tmux.create('test-session', { width: 200, height: 50 });
+```
+
+#### `tmux.kill(name)` → `Promise<void>`
+
+Kill (destroy) a tmux session. Throws if the session does not exist. Removes the session from the tracked set.
+
+#### `tmux.list()` → `Promise<string[]>`
+
+List all active tmux session names. Returns an empty array when no server is running.
+
+#### `tmux.has(name)` → `Promise<boolean>`
+
+Check whether a session with the given name exists.
+
+#### `tmux.owned()` → `string[]`
+
+Return session names created by this Tmux instance. Synchronous — reads from the in-memory tracking set.
+
+```js
+const tmux = new Tmux();
+await tmux.create('session-a');
+await tmux.create('session-b');
+tmux.owned(); // ['session-a', 'session-b']
+```
+
+#### `tmux.cleanup()` → `Promise<void>`
+
+Kill all sessions created by this instance. Best-effort — errors on individual sessions are swallowed so one stuck session does not prevent others from being cleaned. Clears the tracking set.
+
+This is the recommended path for graceful orchestrator shutdown.
+
+```js
+// In graceful shutdown handler
+await tmux.cleanup();
+```
+
+#### `tmux.prune(prefix?)` → `Promise<string[]>`
+
+Kill all tmux sessions whose name starts with the given prefix (default: `'loreli'`). Queries tmux directly — does not rely on in-memory tracking. Returns the names of sessions that were killed.
+
+This is the crash-recovery / manual-reset path. It is destructive: any matching session is killed regardless of whether its agents are still doing useful work.
+
+```js
+// After a crash, clean up all loreli-prefixed sessions
+const killed = await tmux.prune('loreli');
+// ['loreli', 'loreli-debug', 'loreli-agent-test-12345']
+```
+
+### Stale Session Detection
+
+#### `tmux.stale(name)` → `Promise<boolean>`
+
+Check whether a session exists but was not created by this instance. A session is stale when it survives from a previous MCP server process — the current Tmux instance has no record of it because in-memory tracking is per-process. Stale sessions contain agent panes running with outdated environment variables (API keys, budgets, tokens).
+
+The following example shows the pattern start uses to detect leftover sessions before spawning new agents.
+
+```js
+const tmux = new Tmux();
+if (await tmux.stale('loreli')) {
+  // Session exists from a dead MCP server — agents inside have stale env
+}
+```
+
+#### `tmux.reap(name)` → `Promise<{killed: boolean, panes: number}>`
+
+Destroy a stale session and report what was killed. Only acts on sessions not owned by this instance — owned sessions are left untouched, preventing accidental self-destruction during a start re-run within the same process.
+
+Returns `{killed: true, panes: N}` when a stale session was destroyed, or `{killed: false, panes: 0}` when the session doesn't exist or belongs to this instance.
+
+The following example shows how start reaps stale tmux sessions during its cleanup phase. The pane count is logged so operators know how many ghost agents were terminated.
+
+```js
+const tmux = new Tmux();
+const result = await tmux.reap('loreli');
+if (result.killed) {
+  console.log(`reaped stale session (${result.panes} panes)`);
+}
+```
+
+### Window Management
+
+#### `tmux.window(session, opts?)` → `Promise<string>`
+
+Create a new window in an existing session and return its pane ID (e.g. `%3`). Each agent gets its own full-size window instead of splitting an existing one, avoiding the `no space for new pane` error.
+
+When `opts.command` is provided, the process runs directly without an intermediate shell, avoiding `.zshrc` initialization prompts.
+
+- `session` `{string}` — The target session name.
+- `opts.cwd` `{string}` — Working directory for the new window.
+- `opts.command` `{string}` — Shell command to run directly.
+
+```js
+const paneId = await tmux.window('loreli', {
+  cwd: '/tmp/workspace',
+  command: '/path/to/launch.sh'
+});
+```
+
+### Pane Management
+
+#### `tmux.split(session, opts?)` → `Promise<string>`
+
+Split the current window into a new pane. Returns the new pane ID (e.g. `%3`).
+
+- `opts.cwd` `{string}` — Working directory for the new pane.
+- `opts.vertical` `{boolean}` — Split vertically instead of horizontally.
+
+#### `tmux.send(target, text)` → `Promise<void>`
+
+Send keystrokes followed by Enter to a pane. The `target` is a pane ID (e.g. `%3`).
+
+#### `tmux.keys(target, ...keys)` → `Promise<void>`
+
+Send raw key sequences to a pane without appending Enter. Useful for TUI navigation (arrow keys, Escape, Tab). Each argument is a tmux key name: `Down`, `Up`, `Enter`, `Escape`, etc.
+
+The following example shows navigating a TUI dialog, which is how the Claude backend accepts its bypass-permissions confirmation.
+
+```js
+await tmux.keys(paneId, 'Down');   // Move to "Yes, I accept"
+await tmux.keys(paneId, 'Enter');  // Confirm selection
+```
+
+#### `tmux.capture(target, lines?)` → `Promise<string>`
+
+Capture the visible content of a pane. Uses `-J` to join wrapped lines. Default capture depth is 500 lines.
+
+#### `tmux.command(target)` → `Promise<string>`
+
+Query the current foreground command running in a pane. Returns the process name (e.g. `'zsh'`, `'claude'`, `'codex'`), or empty string if the pane is dead.
+
+```js
+const cmd = await tmux.command(paneId);
+if (cmd === 'claude') { /* agent is still running */ }
+```
+
+#### `tmux.panes(session)` → `Promise<Array<{id, pid, active, title}>>`
+
+List panes in a session with metadata.
+
+#### `tmux.alive(target)` → `Promise<boolean>`
+
+Check whether a specific pane still exists and its process is running. Uses `list-panes` with filtering for reliable detection.
+
+#### `tmux.killPane(target)` → `Promise<void>`
+
+Kill a specific pane by ID.
+
+#### `tmux.set(target, option, value)` → `Promise<void>`
+
+Set a pane-level option. Commonly used with `remain-on-exit` for agent backends:
+
+```js
+await tmux.set(paneId, 'remain-on-exit', 'on');
+```
+
+## Error Handling
+
+| Scenario | Error |
+|----------|-------|
+| tmux not installed | `Tmux.available()` returns `false`; instance methods throw with the underlying stderr message |
+| Session already exists | `create()` throws `Session "<name>" already exists` |
+| Session not found | `kill()` throws with tmux's error message |
+| Pane not found | `killPane()`, `send()`, `capture()` throw with tmux's error message |
+
+## Configuration via loreli/config
+
+When used through Loreli's orchestration layer, the following tmux settings are configurable via `loreli.yml`:
+
+| Config Key | Default | Description |
+|------------|---------|-------------|
+| `tmux.session` | `loreli` | Tmux session name used by `CliAgent` |
+| `tmux.capture` | `500` | Number of history lines captured by `capture()` |
+
+These values are resolved through `loreli/config`'s four-layer resolution (start params > `loreli.yml` > env vars > defaults). When using `loreli/tmux` directly without the orchestration layer, the defaults above apply.
+
+## Testing
+
+```bash
+node --test packages/tmux/test/index.test.js
+```
+
+Tests require tmux to be installed on the system.