2026-02-28 19:12:45 +01:00
|
|
|
/**
|
|
|
|
|
* @fileoverview Shared helper functions for route modules.
|
|
|
|
|
*
|
|
|
|
|
* Contains pure functions extracted from server.ts and a session lookup helper
|
|
|
|
|
* that replaces ~43 inline not-found checks across route handlers.
|
|
|
|
|
*/
|
|
|
|
|
|
2026-03-11 19:13:49 +01:00
|
|
|
import { join, resolve, relative, isAbsolute } from 'node:path';
|
2026-03-25 23:32:28 +01:00
|
|
|
import { realpathSync } from 'node:fs';
|
|
|
|
|
import fs from 'node:fs/promises';
|
2026-03-01 03:26:08 +01:00
|
|
|
import { homedir } from 'node:os';
|
2026-03-22 23:55:39 +01:00
|
|
|
import type { z } from 'zod';
|
2026-07-20 03:26:21 +02:00
|
|
|
import type { FastifyReply, FastifyRequest } from 'fastify';
|
2026-02-28 19:12:45 +01:00
|
|
|
import { Session } from '../session.js';
|
2026-07-20 03:26:21 +02:00
|
|
|
import { ApiErrorCode, createErrorResponse, type AuthUser } from '../types.js';
|
2026-02-28 19:12:45 +01:00
|
|
|
import { parseRalphLoopConfig, extractCompletionPhrase } from '../ralph-config.js';
|
2026-03-03 22:40:18 +01:00
|
|
|
import { SseEvent } from './sse-events.js';
|
2026-02-28 19:12:45 +01:00
|
|
|
import type { SessionPort } from './ports/session-port.js';
|
|
|
|
|
import type { EventPort } from './ports/event-port.js';
|
2026-07-20 03:26:21 +02:00
|
|
|
import type { AuthSessionRecord } from './ports/auth-port.js';
|
|
|
|
|
import type { StaleExpirationMap } from '../utils/index.js';
|
2026-06-06 03:53:54 +02:00
|
|
|
import { dataPath } from '../config/instance.js';
|
2026-07-20 03:26:21 +02:00
|
|
|
import { isMultiUserMode } from '../config/multiuser.js';
|
|
|
|
|
import { SYNTHETIC_ADMIN } from '../user-store.js';
|
2026-02-28 19:12:45 +01:00
|
|
|
|
2026-06-06 03:53:54 +02:00
|
|
|
// Shared path constants used across route modules. CASES_DIR (project folders)
|
|
|
|
|
// stays shared across instances; SETTINGS_PATH is per-instance runtime state.
|
2026-03-01 03:26:08 +01:00
|
|
|
export const CASES_DIR = join(homedir(), 'codeman-cases');
|
2026-06-06 03:53:54 +02:00
|
|
|
export const SETTINGS_PATH = dataPath('settings.json');
|
2026-03-01 03:26:08 +01:00
|
|
|
|
2026-03-11 19:13:49 +01:00
|
|
|
/**
|
|
|
|
|
* Validates that a path component doesn't escape the base directory.
|
|
|
|
|
* Returns the resolved full path, or null if the path is a traversal attempt.
|
|
|
|
|
*/
|
|
|
|
|
export function validatePathWithinBase(name: string, baseDir: string): string | null {
|
|
|
|
|
const fullPath = resolve(join(baseDir, name));
|
|
|
|
|
const resolvedBase = resolve(baseDir);
|
|
|
|
|
const relPath = relative(resolvedBase, fullPath);
|
|
|
|
|
if (relPath.startsWith('..') || isAbsolute(relPath)) {
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
return fullPath;
|
|
|
|
|
}
|
|
|
|
|
|
2026-03-25 23:32:28 +01:00
|
|
|
/**
|
|
|
|
|
* Reads and parses a JSON config file, returning a default value on ENOENT.
|
|
|
|
|
* Logs an error for any I/O failure other than a missing file.
|
|
|
|
|
*/
|
|
|
|
|
export async function readJsonConfig<T>(filePath: string, logLabel: string, defaultValue: T): Promise<T> {
|
|
|
|
|
try {
|
|
|
|
|
const content = await fs.readFile(filePath, 'utf-8');
|
|
|
|
|
return JSON.parse(content) as T;
|
|
|
|
|
} catch (err) {
|
|
|
|
|
if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
|
|
|
|
|
console.error(`Failed to read ${logLabel}:`, err);
|
|
|
|
|
}
|
|
|
|
|
return defaultValue;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Validates that a file path (possibly containing symlinks) resolves to a location
|
|
|
|
|
* within the given session working directory. Returns the resolved and relative paths,
|
|
|
|
|
* or null if the path escapes the directory or doesn't exist.
|
|
|
|
|
*/
|
|
|
|
|
export function validateSessionFilePath(
|
|
|
|
|
sessionWorkingDir: string,
|
|
|
|
|
filePath: string
|
|
|
|
|
): { resolvedPath: string; relativePath: string } | null {
|
|
|
|
|
const fullPath = resolve(sessionWorkingDir, filePath);
|
|
|
|
|
let resolvedPath: string;
|
|
|
|
|
try {
|
|
|
|
|
resolvedPath = realpathSync(fullPath);
|
|
|
|
|
} catch {
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
const relativePath = relative(sessionWorkingDir, resolvedPath);
|
|
|
|
|
if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
return { resolvedPath, relativePath };
|
|
|
|
|
}
|
|
|
|
|
|
2026-02-28 19:12:45 +01:00
|
|
|
// Maximum hook data size (prevents oversized SSE broadcasts)
|
|
|
|
|
const MAX_HOOK_DATA_SIZE = 8 * 1024;
|
|
|
|
|
|
2026-07-20 03:26:21 +02:00
|
|
|
/**
|
|
|
|
|
* Effective identity for a request. In multi-user mode this is the auth-decorated
|
|
|
|
|
* user; in single-user mode (or when unset) it defaults to a synthetic admin so
|
|
|
|
|
* downstream ownership checks are no-ops and there is ONE code path.
|
|
|
|
|
*/
|
|
|
|
|
export function getAuthUser(req: FastifyRequest): AuthUser {
|
|
|
|
|
return req.authUser ?? SYNTHETIC_ADMIN;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Whether an identity may see/act on a resource with the given owner. Always true
|
|
|
|
|
* in single-user mode; in multi-user, admins see everything and regular users only
|
|
|
|
|
* their own (an absent owner is legacy/unassigned = admin-only).
|
|
|
|
|
*/
|
|
|
|
|
export function canAccessOwned(user: AuthUser, owner: string | undefined): boolean {
|
|
|
|
|
if (!isMultiUserMode()) return true;
|
|
|
|
|
if (user.role === 'admin') return true;
|
|
|
|
|
return !!owner && owner === user.username;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* First line of admin-only handlers: 403 FORBIDDEN + returns false when the caller
|
|
|
|
|
* is not an admin. Always true in single-user mode (the sole user is the admin).
|
|
|
|
|
*/
|
|
|
|
|
export function requireAdmin(req: FastifyRequest, reply: FastifyReply): boolean {
|
|
|
|
|
if (!isMultiUserMode()) return true;
|
|
|
|
|
if (getAuthUser(req).role === 'admin') return true;
|
|
|
|
|
reply.code(403).send(createErrorResponse(ApiErrorCode.FORBIDDEN));
|
|
|
|
|
return false;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Revoke every cookie session belonging to a user (optionally keeping one token,
|
|
|
|
|
* e.g. the caller's own during a self-service password change). Returns the count.
|
|
|
|
|
*/
|
|
|
|
|
export function revokeUserSessions(
|
|
|
|
|
authSessions: StaleExpirationMap<string, AuthSessionRecord> | null,
|
|
|
|
|
username: string,
|
|
|
|
|
exceptToken?: string
|
|
|
|
|
): number {
|
|
|
|
|
if (!authSessions) return 0;
|
|
|
|
|
const norm = username.trim().toLowerCase();
|
|
|
|
|
let removed = 0;
|
|
|
|
|
for (const [token, record] of authSessions) {
|
|
|
|
|
if (record.username === norm && token !== exceptToken) {
|
|
|
|
|
authSessions.delete(token);
|
|
|
|
|
removed++;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
return removed;
|
|
|
|
|
}
|
|
|
|
|
|
2026-02-28 19:12:45 +01:00
|
|
|
/**
|
|
|
|
|
* Look up a session by ID or throw a structured error.
|
|
|
|
|
* Replaces the pattern: `const session = sessions.get(id); if (!session) return createErrorResponse(...)`.
|
2026-07-20 03:26:21 +02:00
|
|
|
*
|
|
|
|
|
* When `req` is passed in multi-user mode, a session the caller does not own is
|
|
|
|
|
* reported as NOT_FOUND (never 403), so existence of other users' sessions is not
|
|
|
|
|
* leaked. Single-user / admin callers are unaffected.
|
2026-02-28 19:12:45 +01:00
|
|
|
*/
|
2026-07-20 03:26:21 +02:00
|
|
|
export function findSessionOrFail(ctx: SessionPort, sessionId: string, req?: FastifyRequest): Session {
|
2026-02-28 19:12:45 +01:00
|
|
|
const session = ctx.sessions.get(sessionId);
|
2026-07-20 03:26:21 +02:00
|
|
|
if (!session || (req && !canAccessOwned(getAuthUser(req), session.owner))) {
|
2026-02-28 19:12:45 +01:00
|
|
|
throw Object.assign(new Error(`Session ${sessionId} not found`), {
|
|
|
|
|
statusCode: 404,
|
|
|
|
|
body: createErrorResponse(ApiErrorCode.NOT_FOUND, `Session ${sessionId} not found`),
|
|
|
|
|
});
|
|
|
|
|
}
|
|
|
|
|
return session;
|
|
|
|
|
}
|
|
|
|
|
|
2026-03-22 23:55:39 +01:00
|
|
|
/**
|
|
|
|
|
* Parse and validate a request body against a Zod schema, or throw a structured 400 error.
|
|
|
|
|
* Replaces the repeated pattern: `const r = Schema.safeParse(body); if (!r.success) return createErrorResponse(...)`.
|
|
|
|
|
*/
|
|
|
|
|
export function parseBody<T>(schema: z.ZodType<T>, body: unknown, errorMessage?: string): T {
|
|
|
|
|
const result = schema.safeParse(body);
|
|
|
|
|
if (!result.success) {
|
|
|
|
|
const msg = errorMessage ?? result.error.issues[0]?.message ?? 'Validation failed';
|
|
|
|
|
throw Object.assign(new Error(msg), {
|
|
|
|
|
statusCode: 400,
|
|
|
|
|
body: createErrorResponse(ApiErrorCode.INVALID_INPUT, msg),
|
|
|
|
|
});
|
|
|
|
|
}
|
|
|
|
|
return result.data;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Persist session state and broadcast a SessionUpdated event.
|
|
|
|
|
* Replaces the repeated two-line pattern across route handlers.
|
|
|
|
|
*/
|
|
|
|
|
export function persistAndBroadcastSession(ctx: SessionPort & EventPort, session: Session): void {
|
|
|
|
|
ctx.persistSessionState(session);
|
|
|
|
|
ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
|
|
|
|
|
}
|
|
|
|
|
|
2026-02-28 19:12:45 +01:00
|
|
|
/**
|
|
|
|
|
* Formats uptime in seconds to a human-readable string (e.g., "1d 2h 30m 15s").
|
|
|
|
|
*/
|
|
|
|
|
export function formatUptime(seconds: number): string {
|
|
|
|
|
const days = Math.floor(seconds / 86400);
|
|
|
|
|
const hours = Math.floor((seconds % 86400) / 3600);
|
|
|
|
|
const minutes = Math.floor((seconds % 3600) / 60);
|
|
|
|
|
const secs = Math.floor(seconds % 60);
|
|
|
|
|
|
|
|
|
|
const parts: string[] = [];
|
|
|
|
|
if (days > 0) parts.push(`${days}d`);
|
|
|
|
|
if (hours > 0) parts.push(`${hours}h`);
|
|
|
|
|
if (minutes > 0) parts.push(`${minutes}m`);
|
|
|
|
|
if (secs > 0 || parts.length === 0) parts.push(`${secs}s`);
|
|
|
|
|
|
|
|
|
|
return parts.join(' ');
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Sanitizes hook event data before broadcasting via SSE.
|
|
|
|
|
* Extracts only relevant fields and limits total size to prevent
|
|
|
|
|
* oversized payloads from being broadcast to all connected clients.
|
|
|
|
|
*/
|
|
|
|
|
export function sanitizeHookData(data: Record<string, unknown> | null | undefined): Record<string, unknown> {
|
|
|
|
|
if (!data || typeof data !== 'object') return {};
|
|
|
|
|
|
|
|
|
|
// Only forward known safe fields from Claude Code hook stdin
|
|
|
|
|
const safeFields: Record<string, unknown> = {};
|
|
|
|
|
const allowedKeys = [
|
|
|
|
|
'hook_event_name',
|
|
|
|
|
'tool_name',
|
|
|
|
|
'tool_input',
|
|
|
|
|
'session_id',
|
|
|
|
|
'cwd',
|
|
|
|
|
'permission_mode',
|
|
|
|
|
'stop_hook_active',
|
|
|
|
|
'transcript_path',
|
|
|
|
|
];
|
|
|
|
|
|
|
|
|
|
for (const key of allowedKeys) {
|
|
|
|
|
if (key in data && data[key] !== undefined) {
|
|
|
|
|
safeFields[key] = data[key];
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// For tool_input, extract only summary fields (not full file content)
|
|
|
|
|
if (safeFields.tool_input && typeof safeFields.tool_input === 'object') {
|
|
|
|
|
const input = safeFields.tool_input as Record<string, unknown>;
|
|
|
|
|
const summary: Record<string, unknown> = {};
|
|
|
|
|
if (input.command) summary.command = String(input.command).slice(0, 500);
|
|
|
|
|
if (input.file_path) summary.file_path = String(input.file_path).slice(0, 500);
|
|
|
|
|
if (input.description) summary.description = String(input.description).slice(0, 200);
|
|
|
|
|
if (input.query) summary.query = String(input.query).slice(0, 200);
|
|
|
|
|
if (input.url) summary.url = String(input.url).slice(0, 500);
|
|
|
|
|
if (input.pattern) summary.pattern = String(input.pattern).slice(0, 200);
|
|
|
|
|
if (input.prompt) summary.prompt = String(input.prompt).slice(0, 200);
|
|
|
|
|
safeFields.tool_input = summary;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Final size check - drop if serialized data exceeds limit
|
|
|
|
|
const serialized = JSON.stringify(safeFields);
|
|
|
|
|
if (serialized.length > MAX_HOOK_DATA_SIZE) {
|
|
|
|
|
return { tool_name: safeFields.tool_name, _truncated: true };
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return safeFields;
|
|
|
|
|
}
|
|
|
|
|
|
2026-03-26 22:50:25 +01:00
|
|
|
/**
|
|
|
|
|
* Toggles a service (watcher/manager) on or off based on an enabled flag.
|
|
|
|
|
* Logs start/stop to console with the given label. Runs an optional callback after starting.
|
|
|
|
|
*/
|
|
|
|
|
export function toggleService(
|
|
|
|
|
enabled: boolean,
|
|
|
|
|
service: { isRunning(): boolean; start(): void; stop(): void },
|
|
|
|
|
label: string,
|
|
|
|
|
onStart?: () => void
|
|
|
|
|
): void {
|
|
|
|
|
if (enabled && !service.isRunning()) {
|
|
|
|
|
service.start();
|
|
|
|
|
onStart?.();
|
|
|
|
|
console.log(`${label} started via settings change`);
|
|
|
|
|
} else if (!enabled && service.isRunning()) {
|
|
|
|
|
service.stop();
|
|
|
|
|
console.log(`${label} stopped via settings change`);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2026-02-28 19:12:45 +01:00
|
|
|
/**
|
|
|
|
|
* Auto-configure Ralph tracker for a session.
|
|
|
|
|
*
|
|
|
|
|
* Priority order:
|
|
|
|
|
* 1. .claude/ralph-loop.local.md (official Ralph Wiggum plugin state)
|
|
|
|
|
* 2. CLAUDE.md <promise> tags (fallback)
|
|
|
|
|
*
|
|
|
|
|
* The ralph-loop.local.md file has priority because it contains
|
|
|
|
|
* the exact configuration from an active Ralph loop session.
|
|
|
|
|
*/
|
|
|
|
|
export function autoConfigureRalph(session: Session, workingDir: string, ctx: EventPort): void {
|
|
|
|
|
// First, try to read the official Ralph Wiggum plugin state file
|
|
|
|
|
const ralphConfig = parseRalphLoopConfig(workingDir);
|
|
|
|
|
|
|
|
|
|
if (ralphConfig && ralphConfig.completionPromise) {
|
|
|
|
|
session.ralphTracker.enable();
|
|
|
|
|
session.ralphTracker.startLoop(ralphConfig.completionPromise, ralphConfig.maxIterations ?? undefined);
|
|
|
|
|
|
|
|
|
|
// Restore iteration count if available
|
|
|
|
|
if (ralphConfig.iteration > 0) {
|
|
|
|
|
// The tracker's cycleCount will be updated when we detect iteration patterns
|
|
|
|
|
// in the terminal output, but we can set maxIterations now
|
|
|
|
|
console.log(`[auto-detect] Ralph loop at iteration ${ralphConfig.iteration}/${ralphConfig.maxIterations ?? '∞'}`);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
console.log(
|
|
|
|
|
`[auto-detect] Configured Ralph loop for session ${session.id} from ralph-loop.local.md: ${ralphConfig.completionPromise}`
|
|
|
|
|
);
|
2026-03-03 22:40:18 +01:00
|
|
|
ctx.broadcast(SseEvent.SessionRalphLoopUpdate, {
|
2026-02-28 19:12:45 +01:00
|
|
|
sessionId: session.id,
|
|
|
|
|
state: session.ralphTracker.loopState,
|
|
|
|
|
});
|
|
|
|
|
return;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Fallback: try CLAUDE.md
|
|
|
|
|
const claudeMdPath = join(workingDir, 'CLAUDE.md');
|
|
|
|
|
const completionPhrase = extractCompletionPhrase(claudeMdPath);
|
|
|
|
|
|
|
|
|
|
if (completionPhrase) {
|
|
|
|
|
session.ralphTracker.enable();
|
|
|
|
|
session.ralphTracker.startLoop(completionPhrase);
|
|
|
|
|
console.log(`[auto-detect] Configured Ralph loop for session ${session.id} from CLAUDE.md: ${completionPhrase}`);
|
2026-03-03 22:40:18 +01:00
|
|
|
ctx.broadcast(SseEvent.SessionRalphLoopUpdate, {
|
2026-02-28 19:12:45 +01:00
|
|
|
sessionId: session.id,
|
|
|
|
|
state: session.ralphTracker.loopState,
|
|
|
|
|
});
|
|
|
|
|
}
|
|
|
|
|
}
|