AGENTS.md

Guidance for coding agents working on nk304 packages/shared. This package is a shared vocabulary layer for apps and packages, not a dumping ground for arbitrary utilities.

Project Overview

packages/shared exports shared constants, types, agent enums, transport-crypto types, Open Chat types, assistant action types, inventory types, and utilities. Web, mobile, and package code consume it to avoid divergent event names, error codes, API key scopes, language constants, and product payload types.

Because shared constants spread quickly, every change here has a larger blast radius than a local app change. Confirm consumers before renaming, removing, or changing semantics.

Project Map

• src/index.ts is the package root export.
• src/constants/index.ts exposes colors, auth constants, password policy, API paging/rate constants, chat constants, WebSocket event names, transport crypto header names, language constants, API key scopes, scope labels, error codes, and agent enum exports.
• src/constants/agent-enums.ts contains assistant and agent enum values.
• src/types/ contains transport crypto, Open Chat, assistant action, inventory, and root shared types.
• src/utils/ contains reusable shared utilities.
• package.json exposes root, ./types, ./constants, and ./utils subpaths.

Setup Commands

bashpnpm --filter @nk304/shared run build
pnpm --filter @nk304/shared run typecheck
pnpm --filter @nk304/shared run lint

Inspect consumers before changing exports:

bashrg "@nk304/shared" apps packages
rg "WS_EVENTS|ERROR_CODES|API_KEY_SCOPES" apps packages

Change Rules For Agents

• Treat exported constants and types as shared contracts.
• Avoid adding app-local values that only one component needs.
• Keep WebSocket event names aligned with backend emit/receive behavior and generated socket types.
• Keep API key scopes synchronized with backend authorization checks, labels, and tests.
• Reconcile language default differences deliberately; the web runtime currently owns user-facing locale fallback behavior.
• Do not duplicate generated OpenAPI types here. Use the contracts package for generated route schemas.
• Run consumer tests when changing anything imported by web, mobile, API SDK, or app-core.

Verification

Run package checks:

bashpnpm --filter @nk304/shared run lint
pnpm --filter @nk304/shared run typecheck
pnpm --filter @nk304/shared run build

Then run focused consumer checks. Event, scope, or transport changes usually require backend and frontend tests, not just this package build.

Security Notes

Shared constants can accidentally normalize unsafe behavior across the stack. Be cautious around API key scopes, transport headers, auth lifetimes, error codes, and file access names. Do not publish real credentials or internal hostnames in examples.

PR Checklist

• Consumer search was performed for changed exports.
• Backend, web, and mobile semantics remain aligned.
• Generated contracts are not duplicated manually.
• Security-sensitive constants have focused tests at the consumer boundary.