AlexandrAI AGENTS.md
agents-md

DeepDive Canvas Shared Package Agent Guide

Project-specific AGENTS.md guidance for the DeepDive Canvas shared package, workspace constants, persona colors, API and chat constants, shared types, and consumer checks.

AGENTS.md

Guidance for coding agents working on DeepDive Canvas packages/shared. This package carries shared constants, types, and utilities used by API and web packages.

Project Overview

packages/shared exports workspace constants, design-system color constants, persona and presence colors, auth constants, password policy, API paging and rate constants, chat constants, dashboard constants, node sizing, upload constraints, AI constants, WebSocket events, shared types, and utilities.

Shared changes are contract changes. A small rename can break API, web, tests, and generated expectations, so verify consumers before editing exported names.

Project Map

  • src/index.ts is the package root export.
  • src/constants/index.ts exports broad platform constants and WebSocket event names.
  • src/constants/workspace.ts owns workspace-specific constants.
  • src/types/index.ts and src/types/chat.types.ts define shared domain types.
  • src/utils/index.ts contains reusable shared helpers.
  • package.json exposes root, types, constants, and utils subpaths.

Setup Commands

~bash pnpm --filter @deepdive/shared run build pnpm --filter @deepdive/shared run lint pnpm --filter @deepdive/shared run typecheck ~

Before changing exports:

~bash rg "@deepdive/shared" apps packages rg "WS_EVENTS|PERSONA_COLORS|API|UPLOAD|AI" apps packages ~

Change Rules For Agents

  • Treat exported constants as shared contracts.
  • Keep WebSocket event names synchronized with backend gateways and web socket clients.
  • Keep auth and rate-limit constants aligned with backend implementation before changing them.
  • Do not use this package for app-local component options.
  • Preserve upload and AI limits as product contracts; change consumers and tests together.
  • Keep package exports stable unless a consumer migration is included in the same change.
  • Avoid copying generated API shapes into shared types when backend DTOs own the source.

Verification

Package checks are necessary but not sufficient:

~bash pnpm --filter @deepdive/shared run lint pnpm --filter @deepdive/shared run typecheck pnpm --filter @deepdive/shared run build ~

Run focused API or web checks for any changed constant, type, event, or utility that is consumed outside the package.

Security Notes

Shared constants can normalize unsafe values across the app. Be careful with auth lifetimes, upload limits, allowed MIME types, AI model settings, event names, and error constants. Keep examples credential-free.

PR Checklist

  • Consumers were searched before export changes.
  • API and web behavior remain aligned.
  • Package checks pass.
  • Security-sensitive constants have consumer-side tests.