Imported from dnieblesdev/charlybot (packages/shared/AGENTS.md). Install upstream with npx skills add dnieblesdev/charlybot --skill shared. Copyright stays with the author.

AGENTS.md — CharlyBot Shared (packages/shared)

Context for AI agents working on the shared package. Read this in full before making changes.

Scope Rule

• Used 2+ workspaces → packages/shared/ (this package)
• Used only in bot → apps/bot/src/
• Used only in api → apps/api/src/

CRITICAL RULES

ALWAYS

NEVER

TL;DR

• Purpose: Shared Prisma client, Zod schemas, observability tools, Valkey utilities.
• Stack: TypeScript (ESM), Prisma 7 (PostgreSQL adapter), ioredis (Valkey), prom-client, Winston, Zod 3.
• Entry: src/index.ts exports all modules.
• Critical constraint: Bot does NOT use Prisma directly; it talks to the API over HTTP.

Subpath Exports

{
  ".": "./src/index.ts",
  "./prisma": "./src/generated/prisma/index.js",
  "./schemas/*": "./src/schemas/*.ts"
}

Prisma Configuration

File: packages/shared/src/prisma.ts

import { prisma } from "@charlybot/shared";
// Uses PostgreSQL adapter via pg driver

• Adapter: @prisma/adapter-pg with pg
• Default DB: Set via DATABASE_URL env var (e.g. postgresql://user:pass@localhost:5432/charlybot)
• Log levels: ['query', 'error', 'warn'] in development, ['error'] in production
• Backward compatibility: Scripts support both PostgreSQL and SQLite modes via DATABASE_URL detection

Schemas

Observability Module

Logger (src/observability/logger.ts)

import { createLogger } from "@charlybot/shared/observability";

const logger = createLogger({ level: "info" });
logger.info("message", { meta });
logger.error("message", { error: err instanceof Error ? err.message : String(err) });

• Backend: Winston
• Default level: info (override with LOG_LEVEL env var)
• IncludesDiscordWinstonTransport for alert-style output

Metrics (src/observability/metrics.ts)

import { createMetricsRegistry } from "@charlybot/shared/observability";

const register = createMetricsRegistry();
// Registers: error_counter, valkey_circuit_gauge, prisma_query_duration_histogram
// Prometheus endpoint at /metrics (via prom-client)

Tracing (src/observability/tracing.ts)

import { initTracing } from "@charlybot/shared/observability";

initTracing("my-service"); // Requires OTEL_ENABLED=true

• OpenTelemetry SDK initialization (opt-in via OTEL_ENABLED=true)
• Auto-instruments Prisma queries and HTTP calls

Alert Manager (src/observability/alert-manager.ts)

import { AlertManager } from "@charlybot/shared/observability";

const alert = new AlertManager(discordWebhookUrl);
alert.send("Error summary", errorContext);

• Sends formatted alerts to Discord webhook
• Used by bot for critical error reporting

Valkey Utilities

Files in src/valkey/:

ValkeyConfig defaults (from env):

• VALKEY_HOST: localhost
• VALKEY_PORT: 6379
• VALKEY_PASSWORD: undefined
• VALKEY_PREFIX: charlybot:
• VALKEY_MAX_RETRIES: 3

Important: Valkey is Redis-compatible (ioredis under the hood). Used for music streams, XP leaderboards, distributed locks, and rate-limiting.

Error Types

All errors extend AppError(name, statusCode, code):

import { NotFoundError } from "@charlybot/shared";

throw new NotFoundError("EconomyUser", userId);

Auto-Invoke Skills

QA Checklist

• No edits to src/generated/prisma/ files
• All imports use subpath exports (no deep imports from src/schemas/*.ts directly)
• No new runtime dependencies added without checking impact on bot/API bundles
• Bot code does NOT import from @charlybot/shared/prisma directly
• Logger used via createLogger(), not console.log
• Valkey keys built via redis-keys.ts helpers, not hardcoded strings
• AppError subclasses used for typed errors in new code
• QA scripts run with pnpm exec prisma generate (not bunx)