diff --git a/.github/commands/start-dev.md b/.github/commands/start-dev.md new file mode 100644 index 0000000..18bb987 --- /dev/null +++ b/.github/commands/start-dev.md @@ -0,0 +1,18 @@ +# start-dev + +Custom command for local development startup in GitHub Copilot environment. + +## Steps + +```zsh +yarn install +yarn start +``` + +Docs site only: + +```zsh +cd dev-docs +yarn install +yarn start +``` diff --git a/.github/commands/test-watch.md b/.github/commands/test-watch.md new file mode 100644 index 0000000..2c2c99a --- /dev/null +++ b/.github/commands/test-watch.md @@ -0,0 +1,15 @@ +# test-watch + +Custom command to run app tests in watch mode. + +## Steps + +```zsh +yarn test:app +``` + +Single pass mode: + +```zsh +yarn test:app --watch=false +``` diff --git a/.github/commands/verify-ci.md b/.github/commands/verify-ci.md new file mode 100644 index 0000000..9d29d2f --- /dev/null +++ b/.github/commands/verify-ci.md @@ -0,0 +1,19 @@ +# verify-ci + +Custom command to run local checks closest to CI gates. + +## Steps + +```zsh +yarn test:typecheck +yarn test:code +yarn test:app --watch=false +``` + +If docs were changed: + +```zsh +cd dev-docs +yarn install +yarn build +``` diff --git a/.github/rules/conventions.md b/.github/rules/conventions.md new file mode 100644 index 0000000..47120da --- /dev/null +++ b/.github/rules/conventions.md @@ -0,0 +1,15 @@ +# conventions + +- Keep changes small and scoped to the requested behavior. +- Follow existing folder and naming patterns before introducing new abstractions. +- Prefer TypeScript with immutable values (`const`, `readonly`). +- Use optional chaining (`?.`) and nullish coalescing (`??`) where it reduces branching. + +## How to verify + +```zsh +yarn test:code +``` + +- Confirm no new lint violations. +- Confirm changed files follow existing naming conventions. diff --git a/.github/rules/data-restore.md b/.github/rules/data-restore.md new file mode 100644 index 0000000..8f9609c --- /dev/null +++ b/.github/rules/data-restore.md @@ -0,0 +1,14 @@ +# data-restore + +- Do not change persisted data shape without a migration plan. +- Keep backward compatibility for scene/app restore paths. +- Add regression coverage when import/export or restore logic changes. + +## How to verify + +```zsh +yarn test:app --watch=false +``` + +- Open an older scene JSON and confirm it loads without runtime errors. +- Re-export and re-import the same scene; confirm element count and bindings stay stable. diff --git a/.github/rules/do-not-touch.md b/.github/rules/do-not-touch.md new file mode 100644 index 0000000..f0a4c74 --- /dev/null +++ b/.github/rules/do-not-touch.md @@ -0,0 +1,16 @@ +# do-not-touch + +Sensitive paths require explicit approval before edits: + +- `.github/workflows/` +- `firebase-project/` +- release/build automation under `scripts/` +- secret management or environment configuration flows + +## How to verify + +- Run a diff scoped to sensitive paths and confirm no accidental edits. + +```zsh +git --no-pager diff -- .github/workflows firebase-project scripts +``` diff --git a/.github/rules/excalidraw-app.md b/.github/rules/excalidraw-app.md new file mode 100644 index 0000000..ecb3c5f --- /dev/null +++ b/.github/rules/excalidraw-app.md @@ -0,0 +1,13 @@ +# excalidraw-app + +- Keep UI/product behavior changes isolated inside `excalidraw-app/` when possible. +- Use functional components and hooks; do not break hook rules. +- Prefer existing state patterns already used in the app. + +## How to verify + +```zsh +yarn test:app --watch=false +``` + +- Smoke-test the changed flow in local app start. diff --git a/.github/rules/i18n-locales.md b/.github/rules/i18n-locales.md new file mode 100644 index 0000000..b3d1652 --- /dev/null +++ b/.github/rules/i18n-locales.md @@ -0,0 +1,13 @@ +# i18n-locales + +- Do not hardcode user-facing strings if localization keys are expected. +- Keep translation keys stable; avoid unnecessary renames. +- When adding UI text, update related locale entries. + +## How to verify + +```zsh +yarn locales-coverage +``` + +- Check that newly added keys exist in required locale files. diff --git a/.github/rules/packages-element-math.md b/.github/rules/packages-element-math.md new file mode 100644 index 0000000..69bb361 --- /dev/null +++ b/.github/rules/packages-element-math.md @@ -0,0 +1,15 @@ +# packages-element-math + +- Keep `packages/element` and `packages/math` changes bounded and benchmark-aware. +- Prefer low-allocation implementations in geometry/math hotspots. +- Use shared types from `packages/math/src/types.ts` (`Point` for coordinates). +- Add tests for edge cases and precision-sensitive operations. + +## How to verify + +```zsh +yarn --cwd ./packages/math test +yarn --cwd ./packages/element test +``` + +- Run targeted tests for changed geometry paths if available. diff --git a/.github/rules/project-architecture.md b/.github/rules/project-architecture.md new file mode 100644 index 0000000..5ba481f --- /dev/null +++ b/.github/rules/project-architecture.md @@ -0,0 +1,14 @@ +# project-architecture + +- Preserve package boundaries under `packages/`. +- Avoid circular dependencies between packages and app layers. +- Keep public APIs stable unless a breaking change is explicitly requested. + +## How to verify + +```zsh +yarn test:typecheck +yarn test:code +``` + +- Confirm imports remain one-directional according to existing boundaries. diff --git a/.github/rules/security.md b/.github/rules/security.md new file mode 100644 index 0000000..a5475d0 --- /dev/null +++ b/.github/rules/security.md @@ -0,0 +1,14 @@ +# security + +- Never commit secrets, tokens, or credentials. +- Treat all external input as untrusted and validate/sanitize it. +- Prefer least-privilege settings for config changes. +- Upgrade vulnerable dependencies with minimal blast radius. + +## How to verify + +```zsh +git --no-pager grep -nE "(api[_-]?key|secret|token|password)" -- ':!yarn.lock' +``` + +- Ensure no new sensitive literals were introduced. diff --git a/.github/rules/testing.md b/.github/rules/testing.md new file mode 100644 index 0000000..1e53cbe --- /dev/null +++ b/.github/rules/testing.md @@ -0,0 +1,15 @@ +# testing + +- Every behavior change must include updated or new tests. +- Bug fixes require at least one regression test when feasible. +- Keep tests deterministic and independent. + +## How to verify + +```zsh +yarn test:app --watch=false +yarn test:typecheck +yarn test:code +``` + +- Confirm changed code paths are covered by at least one automated test. diff --git a/dev-docs/ab-validation-rules.md b/dev-docs/ab-validation-rules.md new file mode 100644 index 0000000..e2b2979 --- /dev/null +++ b/dev-docs/ab-validation-rules.md @@ -0,0 +1,35 @@ +# A/B validation rules + +## Goal + +Validate whether the repository guidance format is usable for GitHub Copilot workflows (A) versus Cursor-oriented layout assumptions (B). + +## Test scenario + +- Scope: docs-only setup for agent rules and commands. +- Inputs: command docs, rule docs, onboarding docs. +- Success criteria: + - At least 6 rule files with `How to verify` section. + - At least 2 custom command docs. + - Onboarding docs clearly describe project context and conventions. + +## Variant A (GitHub Copilot structure) + +- Paths used: `.github/commands/`, `.github/rules/`, `onboarding-docs/`. +- Result: + - 9 rule files present, each with `How to verify`. + - 3 command docs present. + - `AGENTS.md` and `CLOUDE.MD` present. +- Status: PASS. + +## Variant B (Cursor-only path expectation) + +- Paths expected: `.cursor/commands/`, `.cursor/rules/`. +- Result: + - Not applied in this repository by design. + - Would duplicate the source of truth and diverge from Copilot instructions. +- Status: FAIL (intended). + +## Conclusion + +Use Variant A as the canonical setup for this repository because the active tooling is GitHub Copilot, not Cursor. diff --git a/excalidraw-app/package.json b/excalidraw-app/package.json index 0c8446b..80c2fe7 100644 --- a/excalidraw-app/package.json +++ b/excalidraw-app/package.json @@ -52,6 +52,7 @@ "build:preview": "yarn build && vite preview --port 5000" }, "devDependencies": { + "cross-env": "7.0.3", "vite-plugin-sitemap": "0.7.1" } } diff --git a/onboarding-docs/AGENTS.md b/onboarding-docs/AGENTS.md new file mode 100644 index 0000000..69714b4 --- /dev/null +++ b/onboarding-docs/AGENTS.md @@ -0,0 +1,64 @@ +# AGENTS + +## Project context + +- Repository: Excalidraw monorepo. +- Main areas: + - `excalidraw-app/` - main web app. + - `packages/` - shared libraries (`common`, `math`, `element`, `excalidraw`, `utils`). + - `examples/` - integration and usage examples. + - `dev-docs/` - documentation site and internal docs. + +## Active assistant environment + +- Primary assistant: GitHub Copilot (JetBrains workspace). +- Canonical AI guidance file: `.github/copilot-instructions.md`. +- Command docs: `.github/commands/`. +- Rule docs: `.github/rules/`. + +## Common commands + +```zsh +yarn start +yarn build +yarn test:app --watch=false +yarn test:typecheck +yarn test:code +``` + +Docs workflow: + +```zsh +cd dev-docs +yarn install +yarn start +``` + +## Architecture notes + +- Keep package boundaries explicit; avoid circular dependencies. +- Prefer local changes near feature ownership (avoid broad cross-cutting edits). +- Treat serialized/imported scene data compatibility as a stability contract. + +## Coding conventions + +- TypeScript-first for new code. +- Favor immutable data (`const`, `readonly`) and small focused components. +- Use optional chaining (`?.`) and nullish coalescing (`??`) where helpful. +- For math-related changes, use shared types from `packages/math/src/types.ts` and prefer `Point`. + +## Quality gates + +- Minimum local verification before PR: + +```zsh +yarn test:typecheck +yarn test:code +yarn test:app --watch=false +``` + +- Build gate: + +```zsh +yarn build +``` diff --git a/onboarding-docs/CLOUDE.MD b/onboarding-docs/CLOUDE.MD new file mode 100644 index 0000000..b2c7ffa --- /dev/null +++ b/onboarding-docs/CLOUDE.MD @@ -0,0 +1,17 @@ +# CLOUDE + +## Purpose + +Compatibility onboarding note for teams that previously used `CLAUDE.md`-style files. + +## Source of truth in this repository + +- `.github/copilot-instructions.md` +- `.github/commands/` +- `.github/rules/` +- `dev-docs/ab-validation-rules.md` +- `onboarding-docs/AGENTS.md` + +## Important + +Do not create parallel Cursor-only rule trees for this repo unless explicitly required. This repository is configured for GitHub Copilot-first workflows.