turjuman: Instructions file for Claude Code

Turjuman is open-source, self-hosted translation management driven primarily through an MCP server (an LLM/agent does the translating) with a thin developer CLI for deterministic locale-file work. It runs serverless on AWS (Lambda Function URLs + a single DynamoDB table). Deliberate non-goals: no web UI, no built-in machine-translation engine, no vendor marketplace (see ROADMAP.md).

Follow YAGNI principles, and one-liner solutions.

Commands

Standard scripts (build, typecheck, test, check, clean, …) live in package.json. The non-obvious invocations:

# Run one package, one file, or one test case (workspaces use plain `vitest run`):
pnpm --filter @turjuman/core run test                          # one package
pnpm --filter @turjuman/core run test -- services.test.ts      # one file (path substring)
pnpm --filter @turjuman/core run test -- -t "rejects a viewer" # one test by name

# LocalStack-backed tiers (need Docker); both self-skip when their env vars are unset:
pnpm run localstack:up && pnpm run test:integration && pnpm run localstack:down  # Tier A: repo+services vs real DynamoDB
pnpm run test:e2e                                                                # Tier B: deploy stack + black-box HTTP

# Single dev loop: deploy into LocalStack + esbuild --watch hot reload; prints Function URLs + a fresh API key:
pnpm run localstack:up && cp .env.example .env && pnpm run dev

For how to write tests (the independent-oracle rule, the L0–L5 layers, fakes, property tests, determinism, coverage) read TESTING.md. Dev-loop / LocalStack details live in scripts/dev.mjs. Gotchas worth knowing up front:

• The dev loop runs the real Lambda runtime (so the DynamoDB Streams → webhook path fires); the entrypoints are the Lambda handlers only — there is no local.ts, no :8000, no public ports (LocalStack + Function URLs are localhost-only; reach a remote box via SSH forwarding).
• One shared LocalStack on :4566 serves every session; each working copy deploys its own dev stack, named from a persisted, gitignored .turjuman-dev marker. dev:teardown deletes just this copy's stack; localstack:down wipes the whole emulator and every session — never use it to clean up one session.