|
1 | | -# AGENTS.md |
| 1 | +# Repository Guidelines |
2 | 2 |
|
3 | | -This file is the persistent working log for Codex sessions in this repo. Append dated notes as work happens, especially commands run, results, breakages, and decisions. |
| 3 | +## Project Structure & Module Organization |
| 4 | +This repo is a `pnpm` monorepo managed with Turborepo. Main packages live in `packages/`: `api` for the Express/Vite Node backend, `web` for the React/Vite frontend, `components` for shared UI, `shared` for cross-package schemas/types, and `configs` for shared ESLint/TypeScript config. The published CLI is in `srcbook/`. Source files live under `src/`, tests under `packages/api/test/`, static assets in `packages/web/public` and `srcbook/public`. Treat `dist/` directories as generated output. |
4 | 5 |
|
5 | | -## Repo Notes |
| 6 | +## Build, Test, and Development Commands |
| 7 | +Use the repo Node version from `.nvmrc` (`22.7.0`). In this shell, prefer `corepack pnpm ...`. |
6 | 8 |
|
7 | | -- Workspace manager: `pnpm` via Corepack. In this shell, `pnpm` is not on `PATH`; use `corepack pnpm ...`. |
8 | | -- Repo `.nvmrc`: `22.7.0` |
9 | | -- Current shell when this file was created on 2026-04-06: Node `v24.14.1`, npm `11.11.0`, Corepack pnpm `9.12.1` |
10 | | -- Monorepo packages: |
11 | | - - root workspace |
12 | | - - `packages/api` |
13 | | - - `packages/web` |
14 | | - - `packages/components` |
15 | | - - `packages/shared` |
16 | | - - `packages/configs` |
17 | | - - `srcbook` |
18 | | -- Dependency upgrade tracker: `dependency-upgrades.md` |
| 9 | +- `corepack pnpm install`: install workspace dependencies. |
| 10 | +- `corepack pnpm dev`: start Turbo dev tasks for the app stack. |
| 11 | +- `corepack pnpm build`: build every package. |
| 12 | +- `corepack pnpm lint`: run workspace ESLint checks. |
| 13 | +- `corepack pnpm check-format`: verify Prettier formatting. |
| 14 | +- `corepack pnpm test`: run workspace tests; today this is primarily the API Vitest suite. |
| 15 | +- `corepack pnpm --filter @srcbook/web check-types`: run package-level TypeScript checks. Use the same pattern for other packages. |
19 | 16 |
|
20 | | -## Working Conventions |
| 17 | +## Coding Style & Naming Conventions |
| 18 | +TypeScript uses ESM throughout, with `.mts` common in Node packages and `.tsx` in React packages. Prettier enforces 2-space indentation, single quotes, semicolons, and a 100-character line width. ESLint config comes from `@srcbook/configs`. Use PascalCase for React component files such as `LayoutNavbar.tsx`; use lowercase or descriptive module names for route and utility files such as `routes/home.tsx` or `utils.mts`. |
21 | 19 |
|
22 | | -- Prefer one dependency upgrade focus at a time. |
23 | | -- After each dependency change: |
24 | | - - run install/update |
25 | | - - run targeted typechecks/tests for affected packages |
26 | | - - record results here |
27 | | - - update `dependency-upgrades.md` |
28 | | -- Do not assume `pnpm outdated -r` returning exit code `1` means failure; it returns `1` when outdated packages are found. |
| 20 | +## Testing Guidelines |
| 21 | +Vitest is configured in `packages/api`; keep tests in `packages/api/test/` and name them `*.test.mts`. Store reusable fixtures near the suite, for example `packages/api/test/srcmd_files/`. No coverage threshold is configured, so add focused tests for behavior changes and run lint plus type checks for touched packages before opening a PR. |
29 | 22 |
|
30 | | -## Work Log |
| 23 | +## Commit & Pull Request Guidelines |
| 24 | +Recent history favors short, imperative commit subjects like `Remove noisy logs` or `Update README.md`. Release commits are automated as `chore: release package(s)`. Before large changes, open or confirm an issue with maintainers. PRs should include a clear description, note affected packages, pass `build`, `lint`, `check-format`, and relevant tests, and include a changeset via `corepack pnpm changeset` for user-facing changes. |
31 | 25 |
|
32 | | -### 2026-04-06 |
33 | | - |
34 | | -- Initial dependency inventory: |
35 | | - - read workspace manifests: root `package.json`, `pnpm-workspace.yaml`, `packages/*/package.json`, `srcbook/package.json` |
36 | | - - confirmed there was no existing `AGENTS.md` or upgrade-tracker file |
37 | | -- Commands run: |
38 | | - - `corepack pnpm -v` |
39 | | - - result: `9.12.1` |
40 | | - - `corepack pnpm outdated -r` |
41 | | - - result: succeeded, returned the workspace outdated report |
42 | | - - `corepack pnpm outdated -r --format json` |
43 | | - - result: succeeded, used for risk classification |
44 | | - - `corepack pnpm --filter @srcbook/shared check-types` |
45 | | - - result: passed |
46 | | - - `corepack pnpm --filter @srcbook/api check-types` |
47 | | - - result: passed |
48 | | - - `corepack pnpm --filter @srcbook/web check-types` |
49 | | - - result: passed |
50 | | -- AI SDK scope findings: |
51 | | - - current AI SDK usage is concentrated in: |
52 | | - - `packages/api/ai/config.mts` |
53 | | - - `packages/api/ai/generate.mts` |
54 | | - - current code already uses `createOpenAI`, `createAnthropic`, `createGoogleGenerativeAI`, and `generateText` |
55 | | - - there are no local `streamText`, `streamObject`, or AI SDK UI hooks to migrate |
56 | | -- Current AI SDK registry snapshot checked on 2026-04-06: |
57 | | - - `ai` latest dist-tag: `6.0.149` |
58 | | - - `@ai-sdk/openai` latest dist-tag: `3.0.51` |
59 | | - - `@ai-sdk/anthropic` latest dist-tag: `3.0.67` |
60 | | - - `@ai-sdk/google` latest dist-tag: `3.0.59` |
61 | | - - `@ai-sdk/provider` latest dist-tag: `3.0.8` |
62 | | -- AI SDK migration notes from official docs checked on 2026-04-06: |
63 | | - - official migration guides exist for `3.4 -> 4.0`, `4.x -> 5.0`, and `5.x -> 6.0` |
64 | | - - current OpenAI provider docs still support `createOpenAI({ baseURL })` |
65 | | - - since AI SDK 5, the OpenAI provider uses the Responses API by default unless `openai.chat(...)` or `openai.completion(...)` is selected explicitly |
66 | | -- Zod constraint: |
67 | | - - repo catalog is currently `zod@3.23.8` |
68 | | - - npm peer deps for `ai@5.0.168` and `ai@6.0.149` allow `zod ^3.25.76 || ^4.1.8` |
69 | | - - minimum low-disruption prerequisite for AI SDK is likely bumping the workspace to `zod@3.25.76` or later `3.x` |
70 | | -- Initial judgment: |
71 | | - - there is a real batch of easy same-major bumps available |
72 | | - - AI SDK is behind by multiple majors, but the local code surface is small enough that it does not look like the gnarliest upgrade in the repo |
73 | | - - likely gnarlier later items: React 19, Tailwind 4, Express 5, Vite/Vitest major jumps, broader Zod 4 migration |
74 | | -- Additional inspection before changing code: |
75 | | - - unpacked `@ai-sdk/openai@3.0.51` and `ai@6.0.149` into `/tmp` to inspect current types and provider behavior |
76 | | - - confirmed `createOpenAI` no longer accepts a `compatibility` option |
77 | | - - confirmed `createOpenAI(model)` now creates a Responses API model by default |
78 | | - - conclusion: OpenRouter, xAI, and custom `baseURL` paths should explicitly use `.chat(model)` after the upgrade to preserve OpenAI-compatible chat-completions behavior |
79 | | -- AI SDK upgrade implemented on 2026-04-06: |
80 | | - - updated workspace catalog: |
81 | | - - `zod` -> `^3.25.76` |
82 | | - - `ai` -> `^6.0.149` |
83 | | - - `@ai-sdk/anthropic` -> `^3.0.67` |
84 | | - - `@ai-sdk/google` -> `^3.0.59` |
85 | | - - `@ai-sdk/openai` -> `^3.0.51` |
86 | | - - `@ai-sdk/provider` -> `^3.0.8` |
87 | | - - aligned `packages/api`, `packages/shared`, and `srcbook` to the catalog versions |
88 | | - - updated `packages/api/ai/config.mts`: |
89 | | - - removed the old `compatibility` option |
90 | | - - switched OpenAI-family providers to explicit `.chat(model)` calls |
91 | | - - updated `packages/api/ai/generate.mts`: |
92 | | - - `generateSrcbook` now returns plain text instead of leaking the raw `GenerateTextResult` type |
93 | | - - updated `packages/api/server/http.mts` to match the narrower `generateSrcbook` return type |
94 | | -- Commands run after the AI SDK edit: |
95 | | - - `corepack pnpm install` |
96 | | - - result: passed, lockfile updated |
97 | | - - `corepack pnpm --filter @srcbook/shared check-types` |
98 | | - - result: passed |
99 | | - - `corepack pnpm --filter @srcbook/api check-types` |
100 | | - - first result: failed with `TS4058` because an exported function returned an AI SDK generic type that `tsc` could not name in declarations |
101 | | - - fix: narrowed `generateSrcbook` to `Promise<string>` |
102 | | - - second result: passed |
103 | | - - `corepack pnpm --filter @srcbook/web check-types` |
104 | | - - result: passed |
105 | | - - `corepack pnpm --filter @srcbook/api build` |
106 | | - - result: passed |
107 | | - - `corepack pnpm --filter srcbook build` |
108 | | - - result: passed |
109 | | - - `corepack pnpm --filter @srcbook/api test -- --run` |
110 | | - - result: passed, `3` test files and `11` tests |
111 | | -- Remaining AI SDK follow-up: |
112 | | - - compile/build/test verification is green |
113 | | - - live provider smoke tests still need real API keys/config to verify OpenAI, Anthropic, Gemini, OpenRouter, xAI, and custom `baseURL` paths end-to-end |
| 26 | +## Session Notes |
| 27 | +- 2026-04-06: Created this guide after reviewing root/package `package.json` files, `CONTRIBUTING.md`, `README.md`, and CI workflows to align commands and conventions with the current monorepo. |
0 commit comments