chore: add initial CLAUDE.md for AI assistants - #24
Merged
Conversation
… assistants. Captures what was rediscovered during PR 1 and PR 2 of the 2.0 stack-modernization so future Claude Code / Cursor sessions don't relearn it: - Repo layout: two published extensions + one internal common package consumed via relative imports (no path aliasing). - Stack rules: Node 22, npm workspaces (not pnpm — localazy/release@v2 is npm-hardcoded), ESLint 10 flat config, Prettier 3, vue-tsc for typecheck, no Docker. - Dev workflow with the dev.mjs symlink trick and the SQLite credentials. - Branching model during 2.0 work: main frozen, next is integration, PRs target next. - Stage 1 vs Stage 2 scope policy — what's in bounds for tooling PRs and what's deferred to the app-logic refactor. - Known type errors and the reasons they're deferred (e.g., @directus/types duplication clears with PR 4's SDK bump). - Stage 2 hold list: sync service code, store internals, OAuth flow. Expected to be updated as more conventions surface during PR 3-7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per follow-up feedback, the file should describe what the repo is, how it works, and what commands to run -- not transition state or warnings. - Drop the "Branching model" and "Stage 1 vs Stage 2 scope" sections (specific to the in-flight 2.0 modernization, not future-contributor reference material). - Drop the "Known type errors (deferred)" section (snapshot of in-flight state). - Drop the "Gotchas" section (don't-do-X warnings rather than how-it-works content). - Drop the "When in doubt" tail (pointed at conversation-only artifacts). Remaining structure: what the repo is -> stack -> architecture -> local development -> commands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…own). Short rule that's easy to ask reviewers to apply consistently and easy for an AI to honor while writing code in this repo. The double-cast `as unknown as T` is called out specifically because it's the standard escape hatch when a single `as T` doesn't satisfy the type system, and it almost always indicates the test (or call site) should use a narrower type instead. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
elisiondan
added a commit
that referenced
this pull request
May 12, 2026
…casts. Inspired by the community test suite in #21 (DonkeyOatie). Adapted the test ideas, kept our own structure, and tightened typing so no test file uses `as unknown as` or `as any` (per the new CLAUDE.md coding-conventions rule on PR #24). Changes: - `localazy-payment-status.test.ts`: build full Project + Organization mocks via typed helpers using the actual `@localazy/api-client` types, no casts. Replace the `as unknown as Project` double-cast and the missing-organization edge case (`organization` is required by the Project type). - `enabled-fields-service.test.ts`: fix the wrong fixture shape (the type is `{ fields: string[] }`, not `{ field: string }`). Add cases for empty JSON array, malformed JSON, empty string, plain-object input via a parametrised non-array table. Add the round-trip test (prepare -> parse) for data-integrity guarantee. - `merge-with-arrays.test.ts`: add cases for null source, undefined source, empty target object, arrays of objects, deep nesting, and order preservation. Organise into `array values` / `object values` / `edge cases` describe blocks. - `localazy-api-throttle-service.test.ts` (new): `vi.hoisted` + `vi.mock` for the underlying `@localazy/api-client` and the `sleep` utility, with each delegation method tested using its real request type (`ImportJsonRequest`, `FileListKeysRequest`, etc.) — no `as any` on the option arguments. Adds coverage for token refresh (a new client is constructed each call) and for queue ordering / per-call error isolation. Total goes from 24 to 49 tests across 6 files. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a top-level
CLAUDE.mdthat captures conventions, architecture, and gotchas surfaced during PR 1 and PR 2 of the 2.0 stack-modernization. This is the codebase context file that Claude Code, Cursor, and similar AI assistants read on session startup.It's a starting point, not a finished doc — expected to grow as more conventions become explicit during PR 3-7 and Stage 2.
What's in scope
localazy/release@v2is npm-hardcoded), Node 22, ESLint 10 flat config, Prettier 3,vue-tscfor typechecking, no Docker.dev.mjssymlink trick (whyEXTENSIONS_PATHpoints atdevelopment/extensions/and notextensions/) and the local credentials.mainis frozen at 1.0.x,nextis the 2.0 integration branch, PRs targetnext.@directus/typesduplication clears with PR 4's SDK bump).directus:extensionto common, don't dropMARKETPLACE_TRUSTfrom dev.mjs, don't bump Pinia major without thinking, etc.What's deliberately out of scope right now
checkscript + husky — slot in PR 7.Test plan
nextstate?🤖 Generated with Claude Code