Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive LLM agent documentation and marks generated files appropriately. It introduces three new documentation files specifically designed for AI agents to understand and work with the Calcit/Respo ecosystem, updates dependency versions, and adds metadata to indicate that certain files are generated.
Key Changes
- Added three new LLM agent guide files providing detailed instructions for AI-assisted development
- Updated multiple dependency versions to newer releases
- Added
:aboutmetadata to generated files warning against direct editing - Configured
.gitattributesto mark the new documentation files as generated
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| llms/Respo.md | New comprehensive guide for LLM agents developing Respo applications (920 lines) - includes some documentation issues |
| llms/Calcit.md | New guide for Calcit language development with CLI reference (836 lines) - contains markdown escaping artifacts in code examples |
| Agents.md | New Cumulo development workflow guide for LLM agents (610 lines) - has some duplicate sections |
| deps.cirru | Dependency version updates for several packages (alerts.calcit, respo-message.calcit, respo.calcit, memof, recollect, ws-edn.calcit) |
| compact.cirru | Added :about metadata field warning against direct editing and version bump to 0.9.12 |
| calcit.cirru | Added :version field to client entry and version bump to 0.9.12 |
| .gitattributes | Added linguist-generated markers for new documentation files |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --- | ||
|
|
||
| ## Development Workflow - Adding Features | ||
|
|
There was a problem hiding this comment.
The section "Development Workflow - Adding Features" appears twice consecutively (lines 32 and 36). One of these duplicate section headers should be removed.
| --- | |
| ## Development Workflow - Adding Features |
| if (some? target) (assoc old-files filter-ns target) (dissoc old-files filter-ns) | ||
| , latest-files | ||
| compact-data $ {} (:package pkg) | ||
| compact-data $ {} (:package pkg) (:about "\"file is generated - never edit directly; learn cr edit/tree workflows before changing") |
There was a problem hiding this comment.
The :about field value contains an escaped string with nested quotes: "|\"file is generated - never edit directly; learn cr edit/tree workflows before changing". This appears to be a Cirru string literal that includes escaped quotes, which may be overly complex. Consider simplifying to a standard string without the internal escaping for better readability.
| compact-data $ {} (:package pkg) (:about "\"file is generated - never edit directly; learn cr edit/tree workflows before changing") | |
| compact-data $ {} (:package pkg) (:about "|file is generated - never edit directly; learn cr edit/tree workflows before changing") |
| |T $ %{} :Leaf (:at 1599733076861) (:by |S1lNv50FW) (:text |:configs) | ||
| |j $ %{} :Expr (:at 1599733281290) (:by |S1lNv50FW) | ||
| |T $ %{} :Leaf (:at 1767779797416) (:by |sync) (:text |:about) | ||
| |V $ %{} :Leaf (:at 1767779797416) (:by |sync) (:text "|\"file is generated - never edit directly; learn cr edit/tree workflows before changing") |
There was a problem hiding this comment.
The :about field value contains an escaped string with nested quotes: "|\"file is generated - never edit directly; learn cr edit/tree workflows before changing". This appears to be a Cirru string literal that includes escaped quotes, which may be overly complex. Consider simplifying to a standard string without the internal escaping for better readability.
| echo '"new-value"' | cr tree replace respo.app.updater/updater -p "2,1,0" -s -J | ||
| ``` | ||
|
|
||
| echo '["defn", "hello", [], ["println", "|Hello"]]' | cr edit def respo.app.core/hello -s -J |
There was a problem hiding this comment.
This line appears to be an incomplete or orphaned code example. Line 119 shows an echo command with edit def that doesn't follow the established pattern of the surrounding documentation and appears to be misplaced outside of any code block or example context.
| | `\|hello` | `"hello"` | `"hello"` | | ||
| | `"world"` | `"world"` | `"world"` | | ||
| | `\|a b c` | `"a b c"` | `"a b c"` | |
There was a problem hiding this comment.
In this table, the Cirru column uses backslash escapes for the pipe character. For example, \|hello and \|a b c. These backslashes are not part of Cirru syntax and appear to be markdown escaping artifacts. In actual Cirru code, these should just be |hello and |a b c without backslashes.
| | `\|hello` | `"hello"` | `"hello"` | | |
| | `"world"` | `"world"` | `"world"` | | |
| | `\|a b c` | `"a b c"` | `"a b c"` | | |
| | `|hello` | `"hello"` | `"hello"` | | |
| | `"world"` | `"world"` | `"world"` | | |
| | `|a b c` | `"a b c"` | `"a b c"` | |
| ### Authentication (template has basic version) | ||
|
|
There was a problem hiding this comment.
The section "Authentication (template has basic version)" appears twice consecutively (lines 382 and 384). One of these duplicate section headers should be removed.
| ### Authentication (template has basic version) |
|
|
||
| cr --check-only # Syntax only (fast) |
There was a problem hiding this comment.
The line "cr --check-only # Syntax only (fast)" appears twice consecutively (lines 500 and 502). This appears to be an accidental duplication and one should be removed.
| cr --check-only # Syntax only (fast) |
| cr cirru show-guide | ||
| ``` | ||
|
|
||
| ### 6. Library Management |
There was a problem hiding this comment.
The section title "6. Library Management" is used twice. The first occurrence is at line 253, and there's another section with the same number "6." at line 227 for "Documentation and Language". These should be renumbered sequentially to avoid confusion.
| ### 6. Library Management | |
| ### 7. Library Management |
| | 场景 | 示例用法 | 解析结果 | 说明 | | ||
| | ------------------- | -------------------------------------- | ----------------------------- | --------------------------------- | | ||
| | **表达式 (Cirru)** | `-e 'defn add (a b) (+ a b)'` | `["defn", "add", ...]` (List) | 默认按 Cirru one-liner 解析 | | ||
| | **原子符号 (Leaf)** | `--leaf -e 'my-symbol'` | `"my-symbol"` (Leaf) | **推荐**，避免被包装成 list | | ||
| | **字符串 (Leaf)** | `--leaf -e '\|hello world'` | `"hello world"` (Leaf) | 符号前缀 `\|` 表示字符串 | | ||
| | **JSON 数组** | `-e '["+", "x", "1"]'` | `["+", "x", "1"]` (List) | **自动识别** (含 `[` 且有 `"`) | | ||
| | **JSON 字符串** | `-e '"my leaf"'` | `"my leaf"` (Leaf) | **自动识别** (含引用的字符串) | | ||
| | **内联 JSON** | `-j '["defn", ...]'` | `["defn", ...]` (List) | 显式按 JSON 解析，忽略 Cirru 规则 | | ||
| | **外部文件** | `-f code.cirru` (或 `-f code.json -J`) | 根据文件内容解析 | `-J` 用于标记文件内是 JSON | |
There was a problem hiding this comment.
The table includes backslash-escaped pipe characters (e.g., \|hello world) which are markdown escaping artifacts, not actual Cirru syntax. In actual usage, these should be |hello world without backslashes.
| defn user/log-in (db username password sid op-id op-time) | ||
| let | ||
| maybe-user $ find-user db username | ||
| if | ||
| and (some? maybe-user) | ||
| = (md5 password) (:password maybe-user) | ||
| ; Success: Set user-id in session | ||
| assoc-in db ([] :sessions sid :user-id) (:id maybe-user) | ||
| ; Failure: Add error message | ||
| add-error-message db sid "|Invalid credentials" |
There was a problem hiding this comment.
The authentication example for user/log-in uses md5 to hash and verify passwords (= (md5 password) (:password maybe-user)), which is a weak, fast hash function unsuitable for password storage and can be brute-forced or attacked with rainbow tables if the database is compromised. An attacker who obtains the stored hashes can efficiently recover user passwords, potentially compromising other accounts where the same password is reused. Replace MD5-based password handling with a modern password hashing algorithm (e.g., bcrypt, scrypt, Argon2) and ensure salts and appropriate work factors are used, and update both documentation and implementation to reflect this stronger scheme.
No description provided.