Initial import of LogDarioSeq baseline
Establishes version control for the personal Logseq DB fork before starting the server-client architecture migration and domain features described in docs/agent-guide and the approved implementation plan. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
56
AGENTS.md
Normal file
56
AGENTS.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Repository Guidelines
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
- `bb dev:lint-and-test` runs linters and unit tests.
|
||||
- `bb dev:test -v <namespace/testcase-name>` runs a single unit test (example: `bb dev:test -v logseq.some-test/foo`).
|
||||
- App E2E tests live in `clj-e2e/`; run from that directory with `bb test` (or `bb -f clj-e2e/bb.edn test` from repo root).
|
||||
- CLI E2E tests live in `cli-e2e/`; run with `bb -f cli-e2e/bb.edn test --skip-build` (or `bb -f cli-e2e/bb.edn build` first when needed).
|
||||
- If a request says only “e2e”, clarify whether it targets `clj-e2e/` or `cli-e2e/` before planning changes.
|
||||
|
||||
## Error handling and compatibility
|
||||
- When modifying code, first consider removing compatibility layers rather than extending them.
|
||||
- Prefer fail-fast over fallback.
|
||||
- Do not add backward compatibility unless explicitly requested.
|
||||
- Do not introduce default values to mask invalid state.
|
||||
- Do not silently recover from programmer errors.
|
||||
- Keep one clear code path whenever possible.
|
||||
- Internal code may assume well-formed inputs from controlled callers.
|
||||
|
||||
## Coding Style & Naming Conventions
|
||||
- ClojureScript keywords are defined via `logseq.common.defkeywords/defkeyword`; use existing keywords and add new ones in the shared definitions.
|
||||
- Follow existing namespace and file layout; keep related workers and RTC code in their dedicated directories.
|
||||
- Prefer concise, imperative commit subjects aligned with existing history (examples: `fix: download`, `enhance(rtc): ...`).
|
||||
- Clojure map keyword name should prefer `-` instead of `_`, e.g. `:user-id` instead of `:user_id`.
|
||||
- For i18n work, use `.i18n-lint.toml` as the source of truth for lint scope and exceptions. Inside that scope, shipped UI text must use helpers from `frontend.context.i18n`; console text is exempt. Keep out-of-scope developer-only `(Dev)` labels inline in code/config, not in translation dictionaries.
|
||||
- Reuse `src/resources/dicts/en.edn` keys only on exact semantic owner + textual role match. Follow `docs/i18n-key-naming.md` for new or renamed keys. Add English source text in `en.edn`; add non-English entries only when providing real translations; keep complete sentences whole; use placeholders for plain dynamic text; run `bb lang:validate-translations`, `bb lang:lint-hardcoded`, and `bb lang:format-dicts` as needed.
|
||||
|
||||
## Testing Guidelines
|
||||
- Unit tests live in `src/test/` and should be runnable via `bb dev:lint-and-test`.
|
||||
- Name tests after their namespaces; use `-v` to target a specific test case.
|
||||
- For CLJS tests, avoid recompiling when source files have not changed since the last successful `cljs:test`; run against the existing compiled test artifact instead.
|
||||
- Run lint/tests before submitting PRs; keep changes green.
|
||||
|
||||
## *IMPORTANT*: Always respect directory-specific AGENTS.md based on file path
|
||||
- when editing code in a specific directory, you must recursively read `AGENTS.md` files up the directory tree, and `AGENTS.md` in subdirectories takes precedence over the root-level one
|
||||
|
||||
## Commit & Pull Request Guidelines
|
||||
- Commit subjects are short and imperative; optional scope prefixes appear (e.g., `fix:` or `enhance(rtc):`).
|
||||
- PRs should describe the behavior change, link relevant issues, and note any test coverage added or skipped.
|
||||
- Never include the word "Codex" or any agent name in commit subjects, commit bodies, trailers, branch names, PR titles, or PR descriptions.
|
||||
- PR titles must describe the code change only.
|
||||
- Before creating or updating commits or PRs, verify that the generated metadata does not contain "Codex" or any agent name in any casing.
|
||||
|
||||
## Agent-Specific Notes
|
||||
- Use repo-local skills discovered under `.agents/skills/`; load the matching `SKILL.md` before editing files or proposing changes.
|
||||
- **i18n (mandatory)**: Always load `.agents/skills/logseq-i18n/SKILL.md` before any change that adds, edits, or removes user-facing UI text, regardless of whether other skills also apply.
|
||||
- Review notes live in `prompts/review.md`; check them when preparing changes.
|
||||
- Runtime, sync, CLI, rendering, search, and Graph View engineering guidance is consolidated in `docs/agent-guide/implemented/architecture/2026-08-24-logseq-runtime-and-engineering-guide.md`; current source and tests remain authoritative.
|
||||
- For db-sync D1 schema changes, add or update a Cloudflare worker SQL migration under `deps/db-sync/worker/migrations/`; do not rely on ad hoc runtime-only schema migration code.
|
||||
- New properties should be added to `logseq.db.frontend.property/built-in-properties`.
|
||||
- Avoid creating new class or property unless you have to.
|
||||
- Avoid shadow var, e.g. `bytes` should be named as `payload`.
|
||||
- Avoid using `js/Buffer` in browser related code.
|
||||
- Git commits should include a concise summary.
|
||||
- When deleting properties in db migration, those properties should be added to `logseq.db-sync.tx-sanitize/migration-deleted-attrs`
|
||||
- Use spec-dev-tool to manage agent decision documents; run `spec-dev-tool --help` and follow its AGENT WORKFLOW.
|
||||
- When asked to find simplifications, run `spec-dev-tool guide find-simplifications` from inside this Git worktree and follow the emitted workflow.
|
||||
Reference in New Issue
Block a user