@tenex-chat/backend 0.9.1

package/src/utils/git/worktree.ts

@@ -0,0 +1,260 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { exec } from "node:child_process";
+import { logger } from "@/utils/logger";
+import { ensureWorktreesGitignore } from "./gitignore";
+
+const execAsync = promisify(exec);
+
+/** Directory name for worktrees (relative to project root) */
+export const WORKTREES_DIR = ".worktrees";
+
+/**
+ * Sanitize a branch name for use as a directory name.
+ * Replaces forward slashes with underscores to avoid nested directories.
+ * @example sanitizeBranchName("feature/whatever") => "feature_whatever"
+ */
+export function sanitizeBranchName(branch: string): string {
+    return branch.replace(/\//g, "_");
+}
+
+/**
+ * Metadata for a git worktree
+ */
+export interface WorktreeMetadata {
+  path: string;
+  branch: string;
+  createdBy: string; // Agent pubkey
+  conversationId: string;
+  parentBranch: string;
+  createdAt: number;
+  mergedAt?: number;
+  deletedAt?: number;
+}
+
+// ============================================================================
+// Core Worktree Operations
+// ============================================================================
+
+/**
+ * List all git worktrees for a project.
+ * The main repository is always included as the first entry.
+ * Additional worktrees are located in .worktrees/ subdirectory.
+ *
+ * @param projectPath - Root project directory (normal git repo)
+ * @returns Array of worktrees with branch name and path
+ */
+export async function listWorktrees(projectPath: string): Promise<Array<{ branch: string; path: string }>> {
+    try {
+        const { stdout } = await execAsync("git worktree list --porcelain", { cwd: projectPath });
+
+        const worktrees: Array<{ branch: string; path: string }> = [];
+        const lines = stdout.trim().split("\n");
+
+        let currentWorktree: { path?: string; branch?: string } = {};
+
+        for (const line of lines) {
+            if (line.startsWith("worktree ")) {
+                currentWorktree.path = line.substring(9);
+            } else if (line.startsWith("branch ")) {
+                currentWorktree.branch = line.substring(7).replace("refs/heads/", "");
+            } else if (line === "") {
+                // Empty line marks end of worktree entry
+                if (currentWorktree.path && currentWorktree.branch) {
+                    worktrees.push({
+                        path: currentWorktree.path,
+                        branch: currentWorktree.branch,
+                    });
+                }
+                currentWorktree = {};
+            }
+        }
+
+        // Handle last entry if no trailing newline
+        if (currentWorktree.path && currentWorktree.branch) {
+            worktrees.push({
+                path: currentWorktree.path,
+                branch: currentWorktree.branch,
+            });
+        }
+
+        return worktrees;
+    } catch (error) {
+        logger.error("Failed to list worktrees", { projectPath, error });
+        return [];
+    }
+}
+
+/**
+ * Create a new git worktree in the .worktrees/ directory.
+ * Branch names are sanitized (slashes replaced with underscores) for directory names.
+ * Also ensures .worktrees is added to .gitignore.
+ *
+ * @param projectPath - Root project directory (normal git repo)
+ * @param branchName - Name for the new branch (can contain slashes)
+ * @param baseBranch - Branch to create from (typically current branch)
+ * @returns Path to the new worktree
+ *
+ * @example
+ * // Creates worktree at ~/tenex/project/.worktrees/feature_auth/
+ * await createWorktree("~/tenex/project", "feature/auth", "main");
+ */
+export async function createWorktree(
+    projectPath: string,
+    branchName: string,
+    baseBranch: string
+): Promise<string> {
+    try {
+        // Ensure .worktrees is in .gitignore before creating any worktrees
+        await ensureWorktreesGitignore(projectPath);
+
+        // Create .worktrees directory if it doesn't exist
+        const worktreesDir = path.join(projectPath, WORKTREES_DIR);
+        await fs.mkdir(worktreesDir, { recursive: true });
+
+        // Sanitize branch name for directory (feature/whatever -> feature_whatever)
+        const sanitizedName = sanitizeBranchName(branchName);
+        const worktreePath = path.join(worktreesDir, sanitizedName);
+
+        // Check if worktree already exists
+        const existingWorktrees = await listWorktrees(projectPath);
+        if (existingWorktrees.some((wt) => wt.branch === branchName)) {
+            logger.info("Worktree already exists", { branchName, path: worktreePath });
+            return worktreePath;
+        }
+
+        // Check if path exists on filesystem
+        try {
+            await fs.access(worktreePath);
+            // Path exists but not in worktree list - this is an error state
+            throw new Error(
+                `Directory "${worktreePath}" exists but is not a registered git worktree. ` +
+                "Remove it manually or use a different branch name."
+            );
+        } catch (err: unknown) {
+            if (err instanceof Error && "code" in err && err.code !== "ENOENT") throw err;
+            // Path doesn't exist - safe to create
+        }
+
+        // Create worktree from repository
+        // Wrap in try-catch to handle race conditions where another process creates the worktree
+        try {
+            await execAsync(
+                `git worktree add -b ${JSON.stringify(branchName)} ${JSON.stringify(worktreePath)} ${JSON.stringify(baseBranch)}`,
+                { cwd: projectPath }
+            );
+        } catch (createError: unknown) {
+            // Check if worktree was created by another process (race condition)
+            const refreshedWorktrees = await listWorktrees(projectPath);
+            if (refreshedWorktrees.some((wt) => wt.branch === branchName)) {
+                logger.info("Worktree was created by another process", { branchName, path: worktreePath });
+                return worktreePath;
+            }
+            // Re-throw if it's a different error
+            throw createError;
+        }
+
+        logger.info("Created worktree", {
+            branchName,
+            sanitizedName,
+            path: worktreePath,
+            baseBranch
+        });
+        return worktreePath;
+    } catch (error) {
+        logger.error("Failed to create worktree", { projectPath, branchName, baseBranch, error });
+        throw error;
+    }
+}
+
+// ============================================================================
+// Worktree Metadata Management
+// ============================================================================
+
+/**
+ * Get the path to the worktree metadata file for a project
+ * @param projectPath - The base project directory
+ * @param projectsConfigPath - The base path for project configs (e.g., ~/.tenex/projects)
+ * @returns Path to the worktree metadata JSON file
+ */
+export async function getWorktreeMetadataPath(projectPath: string, projectsConfigPath: string): Promise<string> {
+  // Extract dTag from project path (last segment of path)
+  const dTag = path.basename(projectPath);
+  const metadataDir = path.join(projectsConfigPath, dTag);
+
+  // Ensure the metadata directory exists
+  await fs.mkdir(metadataDir, { recursive: true });
+
+  return path.join(metadataDir, "worktrees.json");
+}
+
+/**
+ * Load worktree metadata for a project
+ * @param projectPath - The base project directory
+ * @param projectsConfigPath - The base path for project configs (e.g., ~/.tenex/projects)
+ * @returns Map of branch names to metadata
+ */
+export async function loadWorktreeMetadata(
+  projectPath: string,
+  projectsConfigPath: string
+): Promise<Record<string, WorktreeMetadata>> {
+  try {
+    const metadataPath = await getWorktreeMetadataPath(projectPath, projectsConfigPath);
+    const content = await fs.readFile(metadataPath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    // File doesn't exist or invalid JSON - return empty object
+    if (error && typeof error === "object" && "code" in error && error.code !== "ENOENT") {
+      logger.warn("Failed to load worktree metadata", {
+        projectPath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    return {};
+  }
+}
+
+/**
+ * Save worktree metadata for a project
+ * @param projectPath - The base project directory
+ * @param projectsConfigPath - The base path for project configs
+ * @param metadata - Map of branch names to metadata
+ */
+async function saveWorktreeMetadata(
+  projectPath: string,
+  projectsConfigPath: string,
+  metadata: Record<string, WorktreeMetadata>
+): Promise<void> {
+  const metadataPath = await getWorktreeMetadataPath(projectPath, projectsConfigPath);
+  await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+}
+
+/**
+ * Track the creation of a new worktree
+ * @param projectPath - The base project directory
+ * @param projectsConfigPath - The base path for project configs
+ * @param metadata - The worktree metadata
+ */
+export async function trackWorktreeCreation(
+  projectPath: string,
+  projectsConfigPath: string,
+  metadata: Omit<WorktreeMetadata, "createdAt">
+): Promise<void> {
+  const allMetadata = await loadWorktreeMetadata(projectPath, projectsConfigPath);
+
+  // Add timestamp and save
+  allMetadata[metadata.branch] = {
+    ...metadata,
+    createdAt: Date.now()
+  };
+
+  await saveWorktreeMetadata(projectPath, projectsConfigPath, allMetadata);
+
+  logger.info("Tracked worktree creation", {
+    branch: metadata.branch,
+    createdBy: metadata.createdBy.substring(0, 8),
+    conversationId: metadata.conversationId.substring(0, 8)
+  });
+}
+

package/src/utils/lessonFormatter.ts

@@ -0,0 +1,70 @@
+import type { NDKAgentLesson } from "@/events/NDKAgentLesson";
+import { logger } from "@/utils/logger";
+
+/**
+ * Format agent lessons into a concise string without using LLM
+ * This is a simple concatenation with minimal formatting
+ */
+export function formatLessonsForAgent(lessons: NDKAgentLesson[]): string {
+    if (lessons.length === 0) {
+        return "";
+    }
+
+    logger.debug("Formatting lessons for agent", {
+        lessonsCount: lessons.length,
+    });
+
+    // Format each lesson concisely - ALL OF THEM!
+    const formattedLessons = lessons
+        .map((lesson, index) => {
+            const title = lesson.title || "Untitled Lesson";
+            const content = lesson.lesson;
+            const category = lesson.category;
+            const hashtags = lesson.hashtags;
+            const hasDetailed = !!lesson.detailed;
+            // Get 12-char prefix for convenient lookup (lesson_get accepts prefixes)
+            const idPrefix = lesson.id ? lesson.id.substring(0, 12) : null;
+
+            // Build metadata line
+            let metadata = "";
+            if (category) metadata += ` [${category}]`;
+            if (hasDetailed) metadata += " [detailed available]";
+            if (hashtags && hashtags.length > 0) metadata += ` #${hashtags.join(" #")}`;
+
+            // Create a concise format for each lesson
+            // Show ID prefix for lesson_get if detailed version available
+            const detailedHint = hasDetailed && idPrefix
+                ? `\n↳ Use lesson_get("${idPrefix}") for detailed version`
+                : "";
+            return `#${index + 1}: ${title} ${metadata}\n${content}${detailedHint}`;
+        })
+        .join("\n\n");
+
+    // Add header for context
+    const header = `## Lessons Learned (${lessons.length} total)\n\n`;
+
+    return header + formattedLessons;
+}
+
+/**
+ * The standard lesson_learn tool reminder to encourage agents to continue learning.
+ */
+export const LESSON_LEARN_REMINDER =
+    "Remember to use the `lesson_learn` tool when you discover new insights or patterns.";
+
+/**
+ * Format lessons for inclusion in a system prompt.
+ * Includes the formatted lessons + the lesson_learn tool reminder.
+ * This is the single source of truth for lesson prompt formatting.
+ *
+ * @param lessons The agent's lessons
+ * @returns Formatted lessons with reminder, or empty string if no lessons
+ */
+export function formatLessonsWithReminder(lessons: NDKAgentLesson[]): string {
+    if (lessons.length === 0) {
+        return "";
+    }
+
+    const formattedLessons = formatLessonsForAgent(lessons);
+    return `${formattedLessons}\n\n${LESSON_LEARN_REMINDER}`;
+}

package/src/utils/lessonTrust.ts

@@ -0,0 +1,24 @@
+import type { NDKAgentLesson } from "@/events/NDKAgentLesson";
+import type { Hexpubkey } from "@nostr-dev-kit/ndk";
+
+/**
+ * Assess whether to trust a pubkey publishing a lesson event.
+ *
+ * This function determines if a lesson should be accepted and stored based on:
+ * - The pubkey that published the lesson
+ * - The lesson content and metadata
+ * - The agent definition the lesson is for
+ *
+ * @param _lesson The lesson event to assess (currently unused)
+ * @param _publisherPubkey The pubkey that published the lesson (currently unused)
+ * @returns true if the lesson should be trusted and stored, false otherwise
+ */
+export function shouldTrustLesson(_lesson: NDKAgentLesson, _publisherPubkey: Hexpubkey): boolean {
+    // For now, trust all lessons
+    // Future implementations may add:
+    // - Whitelist/blacklist checks
+    // - Reputation scoring
+    // - Cryptographic verification
+    // - Content validation
+    return true;
+}

package/src/utils/lockfile.ts

@@ -0,0 +1,123 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import { logger } from "./logger";
+
+/**
+ * Lockfile information
+ */
+interface LockInfo {
+    pid: number;
+    hostname: string;
+    startedAt: number;
+}
+
+/**
+ * Lockfile manager for preventing multiple daemon instances
+ */
+export class Lockfile {
+    private lockfilePath: string;
+    private currentPid: number;
+
+    constructor(lockfilePath: string) {
+        this.lockfilePath = lockfilePath;
+        this.currentPid = process.pid;
+    }
+
+    /**
+     * Acquire the lock. Throws if lock cannot be acquired.
+     */
+    async acquire(): Promise<void> {
+        // Check if lockfile exists using fs.stat
+        let lockfileExists = false;
+        try {
+            await fs.stat(this.lockfilePath);
+            lockfileExists = true;
+        } catch (error) {
+            const err = error as NodeJS.ErrnoException;
+            if (err.code !== "ENOENT") {
+                // Unexpected error accessing lockfile
+                throw error;
+            }
+            // File doesn't exist - we can proceed to create it
+        }
+
+        // If lockfile exists, check if the process is still running
+        if (lockfileExists) {
+            const content = await fs.readFile(this.lockfilePath, "utf-8");
+            const lockInfo: LockInfo = JSON.parse(content);
+
+            if (this.isProcessRunning(lockInfo.pid)) {
+                // Process is running - cannot acquire lock
+                throw new Error(
+                    `Daemon is already running (PID: ${lockInfo.pid}, started at: ${new Date(lockInfo.startedAt).toISOString()})`
+                );
+            }
+
+            // Stale lockfile - previous process crashed or was killed
+            logger.warn("Found stale lockfile, removing it", {
+                stalePid: lockInfo.pid,
+                startedAt: new Date(lockInfo.startedAt).toISOString(),
+            });
+            await this.release();
+        }
+
+        // Create new lockfile
+        const lockInfo: LockInfo = {
+            pid: this.currentPid,
+            hostname: os.hostname(),
+            startedAt: Date.now(),
+        };
+
+        await fs.writeFile(this.lockfilePath, JSON.stringify(lockInfo, null, 2), "utf-8");
+
+        logger.debug("Lockfile acquired", {
+            lockfilePath: this.lockfilePath,
+            pid: this.currentPid,
+        });
+    }
+
+    /**
+     * Release the lock
+     */
+    async release(): Promise<void> {
+        try {
+            await fs.unlink(this.lockfilePath);
+            logger.debug("Lockfile released", { lockfilePath: this.lockfilePath });
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+                logger.warn("Failed to remove lockfile", {
+                    lockfilePath: this.lockfilePath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+
+    /**
+     * Check if a process is running by PID
+     */
+    private isProcessRunning(pid: number): boolean {
+        try {
+            // Sending signal 0 doesn't actually send a signal,
+            // it just checks if the process exists
+            process.kill(pid, 0);
+            return true;
+        } catch (error) {
+            const err = error as NodeJS.ErrnoException;
+
+            // ESRCH means process doesn't exist
+            if (err.code === "ESRCH") {
+                return false;
+            }
+
+            // EPERM means process exists but we lack permission to signal it
+            if (err.code === "EPERM") {
+                return true;
+            }
+
+            // Unexpected error - re-throw
+            throw error;
+        }
+    }
+
+}

package/src/utils/logger.ts

@@ -0,0 +1,149 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+
+const levels: Record<string, number> = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+
+// Helper to get current log level dynamically
+function getCurrentLevel(): number {
+    const LOG_LEVEL = process.env.LOG_LEVEL || "info";
+    return levels[LOG_LEVEL] || levels.info;
+}
+
+// Helper to check if debug is enabled
+function isDebugEnabled(): boolean {
+    return process.env.DEBUG === "true";
+}
+
+// Color configuration for consistent output
+const colors = {
+    error: chalk.red,
+    warn: chalk.yellow,
+    info: chalk.blue,
+    success: chalk.green,
+    debug: chalk.gray,
+};
+
+const emojis = {
+    error: "❌",
+    warn: "⚠️",
+    info: "ℹ️",
+    success: "✅",
+    debug: "🔍",
+};
+
+// File logging state
+let logFilePath: string | null = null;
+
+// Helper to format timestamp for file output
+function formatTimestamp(): string {
+    const now = new Date();
+    return now.toISOString().replace("T", " ").split(".")[0];
+}
+
+// Helper to write to log file
+function writeToFile(level: string, message: string, args: unknown[]): void {
+    if (!logFilePath) return;
+
+    const timestamp = formatTimestamp();
+    const argsStr =
+        args.length > 0
+            ? ` ${args
+                  .map((arg) => (typeof arg === "object" ? JSON.stringify(arg) : String(arg)))
+                  .join(" ")}`
+            : "";
+
+    const logLine = `[${timestamp}] ${level.toUpperCase()}: ${message}${argsStr}\n`;
+
+    fs.appendFileSync(logFilePath, logLine);
+}
+
+// Initialize daemon logging
+async function initDaemonLogging(): Promise<void> {
+    // Lazy-load config to avoid circular dependency
+    const { config } = await import("@/services/ConfigService");
+
+    const tenexConfig = config.getConfig();
+    const defaultLogPath = path.join(config.getConfigPath("daemon"), "daemon.log");
+    logFilePath = tenexConfig.logging?.logFile || defaultLogPath;
+
+    // Ensure directory exists
+    const logDir = path.dirname(logFilePath);
+    fs.mkdirSync(logDir, { recursive: true });
+}
+
+// Main logger object
+export const logger = {
+    initDaemonLogging,
+
+    /**
+     * Check if a specific log level is enabled
+     * Useful for conditional expensive operations (e.g., stack traces)
+     */
+    isLevelEnabled: (level: "error" | "warn" | "info" | "debug"): boolean => {
+        if (level === "debug") {
+            return isDebugEnabled() && getCurrentLevel() >= levels.debug;
+        }
+        return getCurrentLevel() >= levels[level];
+    },
+
+    error: (message: string, error?: unknown) => {
+        if (getCurrentLevel() >= levels.error) {
+            if (logFilePath) {
+                writeToFile("error", message, error ? [error] : []);
+            } else {
+                console.error(colors.error(`${emojis.error} ${message}`), error || "");
+            }
+        }
+    },
+
+    warn: (message: string, ...args: unknown[]) => {
+        if (getCurrentLevel() >= levels.warn) {
+            if (logFilePath) {
+                writeToFile("warn", message, args);
+            } else {
+                console.warn(colors.warn(`${emojis.warn} ${message}`), ...args);
+            }
+        }
+    },
+
+    warning: (message: string, ...args: unknown[]) => {
+        logger.warn(message, ...args);
+    },
+
+    info: (message: string, ...args: unknown[]) => {
+        if (getCurrentLevel() >= levels.info) {
+            if (logFilePath) {
+                writeToFile("info", message, args);
+            } else {
+                console.log(colors.info(`${emojis.info} ${message}`), ...args);
+            }
+        }
+    },
+
+    success: (message: string, ...args: unknown[]) => {
+        if (getCurrentLevel() >= levels.info) {
+            if (logFilePath) {
+                writeToFile("success", message, args);
+            } else {
+                console.log(colors.success(`${emojis.success} ${message}`), ...args);
+            }
+        }
+    },
+
+    debug: (message: string, ...args: unknown[]) => {
+        if (isDebugEnabled() && getCurrentLevel() >= levels.debug) {
+            if (logFilePath) {
+                writeToFile("debug", message, args);
+            } else {
+                console.log(colors.debug(`${emojis.debug} ${message}`), ...args);
+            }
+        }
+    },
+};