@glwhappen/web-code 1.32.0

package/server/shared/claude-cli-path.ts

@@ -0,0 +1,139 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_CLAUDE_COMMAND = 'claude';
+const CLAUDE_SCRIPT_EXTENSIONS = new Set(['.cjs', '.js', '.jsx', '.mjs', '.ts', '.tsx']);
+const CLAUDE_WRAPPER_SEGMENTS = ['node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe'] as const;
+
+export type ResolveClaudeCodeExecutablePathDependencies = {
+  execFileSync?: typeof execFileSync;
+  existsSync?: typeof fs.existsSync;
+  platform?: NodeJS.Platform;
+  readFileSync?: typeof fs.readFileSync;
+};
+
+function getPathApi(platform: NodeJS.Platform) {
+  return platform === 'win32' ? path.win32 : path;
+}
+
+function stripWrappingQuotes(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function isPathLike(value: string): boolean {
+  return value.includes('/') || value.includes('\\');
+}
+
+function resolveClaudeWrapperBinary(
+  wrapperPath: string,
+  deps: Required<ResolveClaudeCodeExecutablePathDependencies>,
+): string | null {
+  const pathApi = getPathApi(deps.platform);
+  const directCandidate = pathApi.resolve(pathApi.dirname(wrapperPath), ...CLAUDE_WRAPPER_SEGMENTS);
+
+  if (deps.existsSync(directCandidate)) {
+    return directCandidate;
+  }
+
+  let content: string;
+  try {
+    content = deps.readFileSync(wrapperPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const matches = content.matchAll(/["']([^"'\\\r\n]*claude\.exe)["']/gi);
+  for (const match of matches) {
+    const rawTarget = match[1]
+      .replace(/^\$basedir[\\/]/i, '')
+      .replace(/^%dp0%[\\/]/i, '')
+      .replace(/^%~dp0[\\/]/i, '');
+    const normalizedTarget = rawTarget.replace(/[\\/]/g, pathApi.sep);
+    const candidate = pathApi.isAbsolute(normalizedTarget)
+      ? normalizedTarget
+      : pathApi.resolve(pathApi.dirname(wrapperPath), normalizedTarget);
+
+    if (deps.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function resolveWindowsClaudeExecutablePath(
+  configuredPath: string,
+  deps: Required<ResolveClaudeCodeExecutablePathDependencies>,
+): string {
+  const pathApi = getPathApi(deps.platform);
+  const extension = pathApi.extname(configuredPath).toLowerCase();
+  const explicitPath = isPathLike(configuredPath) || pathApi.isAbsolute(configuredPath);
+
+  if (CLAUDE_SCRIPT_EXTENSIONS.has(extension)) {
+    return configuredPath;
+  }
+
+  if (explicitPath && extension === '.exe') {
+    return configuredPath;
+  }
+
+  if (explicitPath) {
+    return resolveClaudeWrapperBinary(configuredPath, deps) ?? configuredPath;
+  }
+
+  try {
+    const stdout = deps.execFileSync('where.exe', [configuredPath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+    const candidates = stdout
+      .split(/\r?\n/)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+
+    for (const candidate of candidates) {
+      if (pathApi.extname(candidate).toLowerCase() === '.exe') {
+        return candidate;
+      }
+    }
+
+    for (const candidate of candidates) {
+      const resolved = resolveClaudeWrapperBinary(candidate, deps);
+      if (resolved) {
+        return resolved;
+      }
+    }
+  } catch {
+    return configuredPath;
+  }
+
+  return configuredPath;
+}
+
+export function resolveClaudeCodeExecutablePath(
+  configuredPath: string | undefined = process.env.CLAUDE_CLI_PATH,
+  dependencies: ResolveClaudeCodeExecutablePathDependencies = {},
+): string {
+  const deps: Required<ResolveClaudeCodeExecutablePathDependencies> = {
+    execFileSync: dependencies.execFileSync ?? execFileSync,
+    existsSync: dependencies.existsSync ?? fs.existsSync,
+    platform: dependencies.platform ?? process.platform,
+    readFileSync: dependencies.readFileSync ?? fs.readFileSync,
+  };
+
+  const normalizedPath = stripWrappingQuotes(configuredPath || DEFAULT_CLAUDE_COMMAND);
+  if (deps.platform !== 'win32') {
+    return normalizedPath;
+  }
+
+  return resolveWindowsClaudeExecutablePath(normalizedPath, deps);
+}

package/server/shared/default-user.ts

@@ -0,0 +1,30 @@
+/**
+ * Default-owner user resolution helper.
+ *
+ * Some background processes (filesystem watchers, session synchronizers) need
+ * a stable user id to attribute synchronized data to but have no
+ * request-scoped context. Until the application gains explicit per-user
+ * background workers, those flows fall back on the first registered active
+ * user as the canonical "owner" of system-wide synchronization output.
+ */
+
+import { userDb } from '@/modules/database/index.js';
+import { AppError } from '@/shared/utils.js';
+
+/**
+ * Returns the numeric id of the first active user in the database.
+ *
+ * Throws an `AppError` with code `DEFAULT_USER_NOT_AVAILABLE` (HTTP 500) when
+ * no users exist yet — callers in background contexts are expected to catch
+ * this and skip work gracefully until the first user registers.
+ */
+export function getDefaultOwnerUserId(): number {
+  const user = userDb.getFirstUser();
+  if (!user) {
+    throw new AppError('No active user available to act as default owner', {
+      code: 'DEFAULT_USER_NOT_AVAILABLE',
+      statusCode: 500,
+    });
+  }
+  return Number(user.id);
+}

package/server/shared/frontmatter.ts

@@ -0,0 +1,18 @@
+import matter from 'gray-matter';
+
+const disabledFrontmatterEngine = () => ({});
+
+const frontmatterOptions = {
+  language: 'yaml',
+  // Disable JS/JSON frontmatter parsing to avoid executable project content.
+  // Mirrors Gatsby's mitigation for gray-matter.
+  engines: {
+    js: disabledFrontmatterEngine,
+    javascript: disabledFrontmatterEngine,
+    json: disabledFrontmatterEngine,
+  },
+};
+
+export function parseFrontMatter(content: string) {
+  return matter(content, frontmatterOptions);
+}

package/server/shared/interfaces.ts

@@ -0,0 +1,111 @@
+import type {
+  FetchHistoryOptions,
+  FetchHistoryResult,
+  LLMProvider,
+  McpScope,
+  NormalizedMessage,
+  ProviderSkill,
+  ProviderSkillListOptions,
+  ProviderAuthStatus,
+  ProviderMcpServer,
+  UpsertProviderMcpServerInput,
+} from '@/shared/types.js';
+
+//----------------- PROVIDER CONTRACT INTERFACES ------------
+/**
+ * Main provider contract for CLI and SDK integrations.
+ *
+ * Each concrete provider owns its MCP/auth handlers plus the provider-specific
+ * logic for converting native events/history into the app's normalized shape.
+ */
+export interface IProvider {
+  readonly id: LLMProvider;
+  readonly mcp: IProviderMcp;
+  readonly auth: IProviderAuth;
+  readonly skills: IProviderSkills;
+  readonly sessions: IProviderSessions;
+  readonly sessionSynchronizer: IProviderSessionSynchronizer;
+}
+
+// ---------------------------
+//----------------- PROVIDER AUTH INTERFACE ------------
+/**
+ * Auth contract for one provider.
+ *
+ * Implementations should return a complete installation/authentication status
+ * without throwing for normal "not installed" or "not authenticated" states.
+ */
+export interface IProviderAuth {
+  /**
+   * Checks whether the provider is installed and has usable credentials.
+   */
+  getStatus(): Promise<ProviderAuthStatus>;
+}
+
+// ---------------------------
+//----------------- PROVIDER SKILLS INTERFACE ------------
+/**
+ * Skills contract for one provider.
+ *
+ * Implementations discover provider-native skill markdown locations and return
+ * normalized skill records with the exact command syntax expected by that
+ * provider. Each skill is read from a `SKILL.md` file under its skill directory.
+ */
+export interface IProviderSkills {
+  /**
+   * Lists all skills visible to this provider for the optional workspace.
+   */
+  listSkills(options?: ProviderSkillListOptions): Promise<ProviderSkill[]>;
+}
+
+// ---------------------------
+//----------------- PROVIDER MCP INTERFACE ------------
+/**
+ * MCP contract for one provider.
+ *
+ * Implementations must map provider-native MCP config formats to shared
+ * `ProviderMcpServer` records used by routes and frontend state.
+ */
+export interface IProviderMcp {
+  listServers(options?: { workspacePath?: string }): Promise<Record<McpScope, ProviderMcpServer[]>>;
+  listServersForScope(scope: McpScope, options?: { workspacePath?: string }): Promise<ProviderMcpServer[]>;
+  upsertServer(input: UpsertProviderMcpServerInput): Promise<ProviderMcpServer>;
+  removeServer(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }>;
+}
+
+// ---------------------------
+//----------------- PROVIDER SESSION INTERFACE ------------
+/**
+ * Session/history contract for one provider.
+ *
+ * Implementations normalize provider-specific events and message history into
+ * shared transport shapes consumed by API routes and realtime streams.
+ */
+export interface IProviderSessions {
+  normalizeMessage(raw: unknown, sessionId: string | null): NormalizedMessage[];
+  fetchHistory(sessionId: string, options?: FetchHistoryOptions): Promise<FetchHistoryResult>;
+}
+
+// ---------------------------
+//----------------- PROVIDER SESSION SYNCHRONIZER INTERFACE ------------
+/**
+ * Session indexing contract for one provider.
+ *
+ * Implementations scan provider-specific session artifacts on disk and upsert
+ * normalized session metadata into the database. The service layer uses this
+ * interface for both full rescans and single-file incremental sync triggered
+ * by filesystem watcher events.
+ */
+export interface IProviderSessionSynchronizer {
+  /**
+   * Scans provider session artifacts and upserts discovered sessions into DB.
+   */
+  synchronize(since: Date | undefined, ownerUserId: number): Promise<number>;
+
+  /**
+   * Parses and upserts one provider artifact file without running a full scan.
+   */
+  synchronizeFile(filePath: string, ownerUserId: number): Promise<string | null>;
+}

package/server/shared/types.ts

@@ -0,0 +1,406 @@
+import type { IncomingMessage } from 'node:http';
+
+//----------------- HTTP RESPONSE SHAPES ------------
+/**
+ * Canonical success envelope used by backend APIs that return a structured payload.
+ *
+ * Use this for route handlers that need a stable `success/data` shape so frontend
+ * consumers can parse responses consistently across endpoints.
+ */
+export type ApiSuccessShape<TData = unknown> = {
+  success: true;
+  data: TData;
+};
+
+/**
+ * Generic plain-object record used when parsing loosely typed JSON payloads.
+ *
+ * Use this only after runtime shape checks, not as a replacement for validated
+ * domain models.
+ */
+export type AnyRecord = Record<string, any>;
+
+// ---------------------------
+//----------------- WEBSOCKET TRANSPORT TYPES ------------
+/**
+ * Minimal websocket client contract used by backend broadcaster services.
+ *
+ * Any transport object added to `connectedClients` must implement these two
+ * members so shared services can safely send JSON strings and check whether the
+ * socket is still open before broadcasting.
+ */
+export type RealtimeClientConnection = {
+  readyState: number;
+  send(data: string): void;
+};
+
+/**
+ * Authenticated user payload attached to websocket upgrade requests.
+ *
+ * Platform and OSS auth flows currently use either `id` or `userId`; both are
+ * represented here so websocket handlers can resolve a stable writer user id.
+ */
+export type AuthenticatedWebSocketUser = {
+  id?: string | number;
+  userId?: string | number;
+  username?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * HTTP upgrade request shape after websocket authentication succeeds.
+ *
+ * `verifyClient` populates `request.user` with the authenticated payload, and
+ * downstream websocket handlers rely on this extended request type.
+ */
+export type AuthenticatedWebSocketRequest = IncomingMessage & {
+  user?: AuthenticatedWebSocketUser;
+};
+
+// ---------------------------
+//----------------- PROVIDER MESSAGE MODEL ------------
+/**
+ * Providers supported by the unified server runtime.
+ *
+ * Use this as the source of truth whenever a function or payload needs to identify
+ * a specific LLM integration.
+ */
+export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor';
+
+/**
+ * Message/event variants emitted by provider adapters and normalized transports.
+ *
+ * Keep this union in sync with event kinds produced by provider session adapters.
+ */
+export type MessageKind =
+  | 'text'
+  | 'tool_use'
+  | 'tool_result'
+  | 'thinking'
+  | 'stream_delta'
+  | 'stream_end'
+  | 'error'
+  | 'complete'
+  | 'status'
+  | 'permission_request'
+  | 'permission_cancelled'
+  | 'session_created'
+  | 'interactive_prompt'
+  | 'task_notification';
+
+/**
+ * Provider-neutral message envelope used in REST responses and realtime channels.
+ *
+ * Every provider-specific message must be converted into this shape before being
+ * emitted outside provider-specific modules.
+ */
+export type NormalizedMessage = {
+  id: string;
+  sessionId: string;
+  timestamp: string;
+  provider: LLMProvider;
+  kind: MessageKind;
+  role?: 'user' | 'assistant';
+  content?: string;
+  /**
+   * Optional display-oriented metadata used by providers that need to expose
+   * richer transcript artifacts without introducing a brand-new message kind.
+   *
+   * Current Claude usage:
+   * - local slash commands expose parsed command fields
+   * - compact summaries are flagged so the UI can treat them differently later
+   */
+  displayText?: string;
+  commandName?: string;
+  commandMessage?: string;
+  commandArgs?: string;
+  isLocalCommand?: boolean;
+  isLocalCommandStdout?: boolean;
+  isCompactSummary?: boolean;
+  images?: unknown;
+  toolName?: string;
+  toolInput?: unknown;
+  toolId?: string;
+  toolResult?: {
+    content?: string;
+    isError?: boolean;
+    toolUseResult?: unknown;
+  };
+  isError?: boolean;
+  text?: string;
+  tokens?: number;
+  canInterrupt?: boolean;
+  requestId?: string;
+  input?: unknown;
+  context?: unknown;
+  reason?: string;
+  newSessionId?: string;
+  status?: string;
+  summary?: string;
+  tokenBudget?: unknown;
+  subagentTools?: unknown;
+  toolUseResult?: unknown;
+  sequence?: number;
+  rowid?: number;
+  [key: string]: unknown;
+};
+
+/**
+ * Shared options used to fetch historical provider messages.
+ *
+ * Consumers should pass provider-specific lookup hints (`projectPath`) only
+ * when the selected provider requires them.
+ */
+export type FetchHistoryOptions = {
+  projectPath?: string;
+  limit?: number | null;
+  offset?: number;
+  userId?: number;
+};
+
+/**
+ * Standardized response payload returned from provider history readers.
+ *
+ * Use this as the contract for APIs that return paginated conversation history.
+ */
+export type FetchHistoryResult = {
+  messages: NormalizedMessage[];
+  total: number;
+  hasMore: boolean;
+  offset: number;
+  limit: number | null;
+  tokenUsage?: unknown;
+};
+
+// ---------------------------
+//----------------- PROVIDER SKILL TYPES ------------
+/**
+ * Scope where a provider skill definition was discovered.
+ *
+ * Provider skill adapters should use this to describe the origin of each
+ * skill markdown file without leaking provider-specific folder names into route
+ * contracts. `repo` is used for Codex repository lookup locations, while
+ * `project` is used for providers that treat workspace-local skills as project
+ * scoped.
+ */
+export type ProviderSkillScope = 'user' | 'project' | 'plugin' | 'repo' | 'admin' | 'system';
+
+/**
+ * Shared input accepted by provider skill listing operations.
+ *
+ * Routes pass `workspacePath` when a caller wants project/repository skills for
+ * a specific folder. Providers should fall back to the backend process cwd when
+ * this option is omitted.
+ */
+export type ProviderSkillListOptions = {
+  workspacePath?: string;
+};
+
+/**
+ * Normalized skill record returned by provider skill adapters.
+ *
+ * The `command` value is the exact invocation text the selected provider expects
+ * for this skill. Claude plugin skills use a namespaced command such as
+ * `/plugin-name:skill-name`, while Codex skills use the `$skill-name` form.
+ * `sourcePath` points to the skill markdown file that produced the record so
+ * callers can distinguish duplicate skill names across scopes.
+ */
+export type ProviderSkill = {
+  provider: LLMProvider;
+  name: string;
+  description: string;
+  command: string;
+  scope: ProviderSkillScope;
+  sourcePath: string;
+  pluginName?: string;
+  pluginId?: string;
+};
+
+/**
+ * Internal source descriptor consumed by shared provider skill discovery logic.
+ *
+ * Concrete provider adapters build these records from their native lookup rules.
+ * The shared skills provider then scans `rootDir` for child skill markdown files
+ * and uses `commandForSkill` or `commandPrefix` to produce the provider-specific
+ * invocation command. Set `recursive` only when a provider stores skills under
+ * arbitrary nested folders below the source root.
+ */
+export type ProviderSkillSource = {
+  scope: ProviderSkillScope;
+  rootDir: string;
+  recursive?: boolean;
+  commandPrefix?: '/' | '$';
+  commandForSkill?: (skillName: string) => string;
+  pluginName?: string;
+  pluginId?: string;
+};
+
+// ---------------------------
+//----------------- SHARED ERROR TYPES ------------
+/**
+ * Optional metadata used when constructing application-level errors.
+ *
+ * `statusCode` should reflect the HTTP response status, while `code` identifies
+ * the stable machine-readable error category.
+ */
+export type AppErrorOptions = {
+  code?: string;
+  statusCode?: number;
+  details?: unknown;
+};
+
+// ---------------------------
+//----------------- MCP TYPES ------------
+/**
+ * Scope where an MCP server definition is stored and resolved.
+ *
+ * `user` is global for a user account, `local` is provider-local, and `project`
+ * is tied to a specific project path.
+ */
+export type McpScope = 'user' | 'local' | 'project';
+
+/**
+ * Transport protocol used by an MCP server definition.
+ */
+export type McpTransport = 'stdio' | 'http' | 'sse';
+
+/**
+ * Normalized MCP server model exposed to frontend and route handlers.
+ *
+ * Provider adapters should map provider-native config to this structure before
+ * returning results.
+ */
+export type ProviderMcpServer = {
+  provider: LLMProvider;
+  name: string;
+  scope: McpScope;
+  transport: McpTransport;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  envVars?: string[];
+  bearerTokenEnvVar?: string;
+  envHttpHeaders?: Record<string, string>;
+};
+
+/**
+ * Payload for create/update MCP server operations.
+ *
+ * Routes and services should accept this type, validate it, and then persist it
+ * through provider-specific MCP repositories.
+ */
+export type UpsertProviderMcpServerInput = {
+  name: string;
+  scope?: McpScope;
+  transport: McpTransport;
+  workspacePath?: string;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  envVars?: string[];
+  bearerTokenEnvVar?: string;
+  envHttpHeaders?: Record<string, string>;
+};
+
+// ---------------------------
+//----------------- PROVIDER AUTH TYPES ------------
+/**
+ * Authentication status result returned by provider health checks.
+ *
+ * This shape is consumed by settings/status endpoints to report installation and
+ * credential state for each provider.
+ */
+export type ProviderAuthStatus = {
+  installed: boolean;
+  provider: LLMProvider;
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+// ---------------------------
+//----------------- SHARED DATABASE CREDENTIAL TYPES ------------
+/**
+ * Safe credential view returned by credential listing APIs.
+ *
+ * This intentionally excludes the raw credential secret while still exposing
+ * metadata needed for UI rendering and management operations.
+ */
+export type CredentialPublicRow = {
+  id: number;
+  credential_name: string;
+  credential_type: string;
+  description: string | null;
+  created_at: string;
+  is_active: number;
+};
+
+/**
+ * Result returned after creating a credential record.
+ *
+ * Use this return shape when callers need the created id and display metadata,
+ * but must never receive the stored secret value.
+ */
+export type CreateCredentialResult = {
+  id: number | bigint;
+  credentialName: string;
+  credentialType: string;
+};
+
+// ---------------------------
+//----------------- PROJECT PERSISTENCE TYPES ------------
+/**
+ * Canonical project row shape returned by the projects repository.
+ *
+ * Use this type whenever backend services need to pass around one database
+ * project record without leaking raw SQL row typing across modules.
+ */
+export type ProjectRepositoryRow = {
+  project_id: string;
+  project_path: string;
+  custom_project_name: string | null;
+  isStarred: number;
+  isArchived: number;
+};
+
+/**
+ * Result category returned by `projectsDb.createProjectPath`.
+ *
+ * `created` means a fresh row was inserted, `reactivated_archived` means an
+ * existing archived path was accepted and updated, and `active_conflict` means
+ * an already-active path blocked project creation.
+ */
+export type CreateProjectPathOutcome =
+  | 'created'
+  | 'reactivated_archived'
+  | 'active_conflict';
+
+/**
+ * Structured result returned by project-path upsert operations.
+ *
+ * Services should use this result to decide whether a request succeeded,
+ * should return a conflict, or needs follow-up retrieval of row metadata.
+ */
+export type CreateProjectPathResult = {
+  outcome: CreateProjectPathOutcome;
+  project: ProjectRepositoryRow | null;
+};
+
+/**
+ * Validation result for user-supplied workspace/project paths.
+ *
+ * `resolvedPath` is present only when validation succeeds. `error` is present
+ * only when validation fails and is suitable for user-facing diagnostics.
+ */
+export type WorkspacePathValidationResult = {
+  valid: boolean;
+  resolvedPath?: string;
+  error?: string;
+};