From 08b3d8719d5cc06a7ec51d7526a73c665d3c08cc Mon Sep 17 00:00:00 2001 From: Farhodjon Date: Tue, 16 Jun 2026 13:04:31 -0500 Subject: [PATCH] docs: Add AGENTS.md and CLAUDE.md symlink --- AGENTS.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 131 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8efd9de --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,130 @@ +# Agents Guide + +> Guide for AI coding agents working on this codebase. +> `CLAUDE.md` is a symlink to this file. + +--- + +## 0. Navigation Contract + +Agents MUST traverse context in this order: + +1. **This file** (`AGENTS.md`) — workflow, structure, key rules +2. **Source files in `src/`** — read the existing module nearest to your change before writing code + +--- + +## 1. Project Overview + +`@superdispatch/sdk` — a published TypeScript SDK (`main: src/index.ts`) that +provides shared Super Dispatch domain types, constants, validators, and +formatters (payment methods/terms, customer types, vehicle types, date types). +Each module exports a string union type plus helper functions; everything is +re-exported from `src/index.ts`. + +### Prerequisites + +| Tool | Version | Source | +|------|---------|--------| +| Node.js | `>=24` | `package.json` `engines` | +| pnpm | `10.25` (CI) | `.github/workflows/main.yml` | +| TypeScript | `5.9.x` | `devDependencies` | + +### Key Commands + +```bash +pnpm run tsc # Type-check (tsc, no emit config beyond tsconfig) +pnpm run lint # Lint via @superdispatch/js-tools (js-tools lint) +pnpm run test # Run Jest with coverage +pnpm run tdd # Jest in watch mode +pnpm run build # Pika build, then scripts/fix-package-json.js +``` + +CI (`.github/workflows/main.yml`) runs, in order: `tsc`, `lint`, `test`, +Codecov upload, `build`. + +### Directory Structure + +``` +src/ +├── index.ts # Barrel — re-exports every public module +├── CustomerType.ts # Domain type + helpers +├── DateType.ts +├── LoadPaymentMethod.ts +├── LoadPaymentTerm.ts +├── PaymentMethod.ts +├── PaymentTerm.ts +├── VehicleType.ts +├── internal/ # Private helpers (not part of public surface) +│ └── toStartCase.ts +└── __tests__/ # Jest specs, one per module (*.spec.ts) +scripts/ +└── fix-package-json.js # Post-build package.json fixup +``` + +--- + +## 2. Code Conventions (Key Rules) + +Documented from the existing source — follow the patterns already in `src/`. + +| Rule | Evidence | +|------|----------| +| Domain values are **string union `type`s**, not enums | `PaymentMethod`, `VehicleType`, etc. | +| **Named exports only** — no default exports | every module + `src/index.ts` | +| Constant arrays are `UPPER_SNAKE_CASE` and typed | `ALL_PAYMENT_METHODS: PaymentMethod[]` | +| Validators are **type guards** named `isValid` | `isValidPaymentMethod(input): input is PaymentMethod` | +| Formatters named `format`, accept `unknown`, take a `{ fallback }` option | `formatPaymentMethod(input, { fallback = 'Unknown' })` | +| Deprecations use `@deprecated` JSDoc / comment pointing at the replacement | `PAYMENT_METHODS`, `listPaymentMethods()` | +| Shared internal helpers live in `src/internal/` | `toStartCase.ts` | +| New public modules are re-exported from `src/index.ts` | barrel file | +| Formatting/lint | Prettier (`@superdispatch/prettier-config`) + ESLint (`@superdispatch/eslint-plugin`), enforced on commit via `lint-staged` | + +--- + +## 3. Testing Rules (Key Rules) + +| Rule | Evidence | +|------|----------| +| Framework | Jest 28 (`@types/jest`), run with `--coverage` | +| Test match | `**/__tests__/**/*.spec.ts` (`package.json` jest config) | +| Location | One spec per module in `src/__tests__/` | +| Style | `it('...')` blocks, snapshot assertions via `toMatchInlineSnapshot` | +| Ignored paths | `/pkg/`, `/node_modules/` | + +Run a single file: `pnpm run test -- PaymentMethod`. + +--- + +## 4. Build & Publish (Key Rules) + +- **Build pipeline:** Pika (`@pika/pack`) — standard pkg + node + web + types + builds, excluding `__tests__/**` and `__testutils__/**` (see `@pika/pack` + config in `package.json`). +- **Post-build:** `scripts/fix-package-json.js` adjusts the generated package. +- **Release:** `pnpm run release` publishes `./pkg` to the npm registry + (`publishConfig.registry`). `prerelease` reinstalls, lints, type-checks, builds. +- Package is MIT-licensed and public (`private: false`). + +--- + +## 5. Agent Workflow + +1. **Create a branch** — never commit directly to `master`; one branch per logical change. +2. **Read context** — this file first, then the existing module closest to your change. +3. **Find similar code** — mirror an existing module (e.g. `PaymentMethod.ts`) for type + guard + formatter shape; add the matching `*.spec.ts`. +4. **Generate** — follow the conventions in Section 2; re-export new public modules from `src/index.ts`. +5. **Test & type-check** — run `pnpm run test` and `pnpm run tsc`; verify output before claiming done. +6. **Lint** — run `pnpm run lint` (auto-fixed on commit via `lint-staged`); fix all errors. +7. **Self-review & submit** — review `git diff`, commit (never `--no-verify`), open a pull request. + +--- + +## 6. Git Conventions + +The repo does not document a commit-message format. Use a clear branch-and-PR flow: + +- **Never commit directly to `master`** — work on a dedicated branch. +- **PRs required** — all changes merge through pull requests; CI must pass. +- **`.husky/pre-commit`** runs `pnpm lint-staged`; do not bypass with `--no-verify`. +- **Code ownership:** `@superdispatch/web` (see `.github/CODEOWNERS`). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file