fix: agent hygiene P0/P1 — gitignore, DATABASE_URL, CI lint, docs#1
fix: agent hygiene P0/P1 — gitignore, DATABASE_URL, CI lint, docs#1
Conversation
- .gitignore: replace single .vercel entry with full ruleset covering node_modules, dist, .svelte-kit, .env*, *.db files, logs, OS, editor - src/main.ts: read DATABASE_URL env var for SQLite path (fallback to agentswarp.db) so the documented env var is actually respected - ci.yml: add bun lint and bun format --check before test/build steps; fix Windows CRLF line endings in the file - swarm-core.md: delete 180 KB raw code dump; replace with structured docs/phase-2-migration.md covering file inventory, memory budget, new env vars, and integration checklist - AGENTS.md: create agent guidance file (repo map, conventions, architecture constraints, tool-addition workflow, PR checklist) - AGENTS-IMPROVEMENT-SPEC.md: audit findings and remaining improvement backlog (P2/P3 items not yet implemented) Co-authored-by: Ona <no-reply@ona.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThe PR establishes agent-readiness infrastructure and improves project configuration by adding comprehensive documentation for AI coding agents, enhancing CI/CD with linting and format validation checks, expanding gitignore coverage, and updating SQLite database initialization to support environment variable configuration. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/ci.yml:
- Around line 10-11: CI invokes "bun lint" and "bun format --check" but
package.json lacks "lint" and "format" scripts; add "lint" and "format" script
entries to package.json (e.g., map "lint" to your linter command and "format" to
your formatter/check command) so "bun lint" and "bun format --check" succeed, or
alternatively remove the "run: bun lint" and "run: bun format --check" steps
from the workflow if you don't want those checks enforced; update the
package.json scripts section and ensure the commands referenced by "lint" and
"format" match your tooling.
In @.gitignore:
- Around line 11-14: Update the .gitignore to broadly ignore environment files
by adding a general pattern that covers all env variants (e.g., .env*) while
explicitly allow-listing example/sample files (e.g., .env.example, .env.sample)
so that secrets like .env.production cannot be committed but
documentation/example env files remain tracked.
In `@AGENTS-IMPROVEMENT-SPEC.md`:
- Around line 160-165: The conclusion row in AGENTS-IMPROVEMENT-SPEC.md that
states "All remaining items above are **not yet implemented**" is stale; update
the table and concluding text to reflect the current state by marking
implemented P0/P1 items now present in the repo (as reflected in AGENTS.md and
other changes) and remove or rephrase the blanket "not yet implemented" line.
Locate the table and concluding paragraph in AGENTS-IMPROVEMENT-SPEC.md, update
the "Action" column entries for the specific files/items that are implemented
(including AGENTS.md), and change the final summary sentence to accurately
indicate which items remain outstanding versus completed.
In `@AGENTS.md`:
- Around line 11-24: Update the fenced repo-tree block in AGENTS.md to include a
language hint (e.g., use ```text) so the markdown linter recognizes it; locate
the fenced block that starts with the agentswarp/ tree and change the opening
fence to include the language token (for example replace ``` with ```text) while
leaving the tree content unchanged.
- Around line 123-124: Update the CI notes in AGENTS.md to reflect the current
PR gates: change the first bullet that says "`bun install && bun test && bun run
build` — must pass on all PRs." to include lint and format-check (e.g. "`bun
install && bun test && bun run build && bun run lint && bun run format:check` —
must pass on all PRs.") and ensure the second bullet about Docker image builds
still notes "Docker image build runs on `main` only." Make the text concise and
accurate so the documented commands match the actual CI workflow.
In `@docs/phase-2-migration.md`:
- Line 79: The docs list the environment variable as SEARXNG_BASE_URL but the
code reads SEARXNG_URL, causing a mismatch; update the documentation entry to
use SEARXNG_URL (or alternatively update the implementation to accept
SEARXNG_BASE_URL) so the documented env var name matches the tool’s actual
variable name (reference the env var symbols SEARXNG_BASE_URL and SEARXNG_URL
and the docs entry in phase-2-migration).
- Line 93: The docs point to registering searxng in
packages/core/src/tool-registry.ts but the codebase expects tools to be
exported/registered through packages/tools/src/index.ts; update the migration
note to instruct contributors to add the searxng export/registration in
packages/tools/src/index.ts (and ensure the module exports the searxng symbol
and any registration side-effect used by the runtime), referencing the searxng
export name so reviewers can find and wire it properly.
In `@src/main.ts`:
- Around line 7-8: Ensure the parent directory for the SQLite file exists before
instantiating the Database: derive the directory from dbPath (use
path.dirname(dbPath)) and create it if missing (use fs.mkdirSync(dir, {
recursive: true }) or await fs.promises.mkdir(dir, { recursive: true })) prior
to calling new Database(dbPath); reference the dbPath constant and the Database
instantiation to locate where to add the directory creation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 0aa384af-f98c-4b3c-b4f0-2e6c4eec521b
📒 Files selected for processing (7)
.github/workflows/ci.yml.gitignoreAGENTS-IMPROVEMENT-SPEC.mdAGENTS.mddocs/phase-2-migration.mdsrc/main.tsswarm-core.md
| - run: bun lint | ||
| - run: bun format --check |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Confirm workflow commands and available package scripts
rg -n "bun lint|bun format --check" .github/workflows/ci.yml
jq -r '.scripts // {}' package.jsonRepository: raynr7/agentswarp
Length of output: 262
Add missing lint and format scripts to package.json before the CI workflow will pass.
The workflow at lines 10-11 invokes bun lint and bun format --check, but neither script is defined in package.json. This will cause CI to fail immediately. Either add these scripts to package.json or remove the corresponding workflow steps.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/workflows/ci.yml around lines 10 - 11, CI invokes "bun lint" and
"bun format --check" but package.json lacks "lint" and "format" scripts; add
"lint" and "format" script entries to package.json (e.g., map "lint" to your
linter command and "format" to your formatter/check command) so "bun lint" and
"bun format --check" succeed, or alternatively remove the "run: bun lint" and
"run: bun format --check" steps from the workflow if you don't want those checks
enforced; update the package.json scripts section and ensure the commands
referenced by "lint" and "format" match your tooling.
| .env | ||
| .env.local | ||
| .env.*.local | ||
|
|
There was a problem hiding this comment.
Broaden env-file ignores to avoid accidental secret commits.
Line 11–Line 14 only cover local variants; files like .env.production are still committable. Prefer a broad ignore with explicit allowlist for examples.
🔧 Suggested update
-# Environment — never commit secrets
-.env
-.env.local
-.env.*.local
+# Environment — never commit secrets
+.env*
+!.env.example🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.gitignore around lines 11 - 14, Update the .gitignore to broadly ignore
environment files by adding a general pattern that covers all env variants
(e.g., .env*) while explicitly allow-listing example/sample files (e.g.,
.env.example, .env.sample) so that secrets like .env.production cannot be
committed but documentation/example env files remain tracked.
| | File | Action | | ||
| |------|--------| | ||
| | `AGENTS.md` | Created | | ||
| | `AGENTS-IMPROVEMENT-SPEC.md` | Created (this file) | | ||
|
|
||
| All remaining items above are **not yet implemented** and require explicit follow-up. |
There was a problem hiding this comment.
Session change log is now stale against this PR.
Line 165 says remaining items are not implemented, but this PR already implements multiple P0/P1 items. Please update this table/conclusion so the spec reflects current repo state.
📝 Suggested adjustment
| File | Action |
|------|--------|
| `AGENTS.md` | Created |
| `AGENTS-IMPROVEMENT-SPEC.md` | Created (this file) |
+| `.gitignore` | Expanded with dependency/build/env/db/log/editor ignores |
+| `src/main.ts` | `DATABASE_URL` respected for SQLite path |
+| `.github/workflows/ci.yml` | Added lint + format-check steps |
+| `docs/phase-2-migration.md` | Added to replace raw `swarm-core.md` dump |
-All remaining items above are **not yet implemented** and require explicit follow-up.
+Remaining **P2/P3** items above require explicit follow-up.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS-IMPROVEMENT-SPEC.md` around lines 160 - 165, The conclusion row in
AGENTS-IMPROVEMENT-SPEC.md that states "All remaining items above are **not yet
implemented**" is stale; update the table and concluding text to reflect the
current state by marking implemented P0/P1 items now present in the repo (as
reflected in AGENTS.md and other changes) and remove or rephrase the blanket
"not yet implemented" line. Locate the table and concluding paragraph in
AGENTS-IMPROVEMENT-SPEC.md, update the "Action" column entries for the specific
files/items that are implemented (including AGENTS.md), and change the final
summary sentence to accurately indicate which items remain outstanding versus
completed.
| ``` | ||
| agentswarp/ | ||
| ├── src/main.ts Entry point (Hono server, SQLite setup) | ||
| ├── apps/ | ||
| │ ├── web/ SvelteKit frontend (port 3000) | ||
| │ └── server/ Bun + Hono API server (port 3001) | ||
| ├── packages/ | ||
| │ ├── core/ Agent runner, LLM abstraction, memory, scheduler | ||
| │ └── tools/ Built-in tool implementations (14 tools) | ||
| ├── docs/ Architecture and tool reference docs | ||
| ├── public/ Static assets served by Hono | ||
| ├── .devcontainer/ Dev container config | ||
| └── .github/ CI, PR template, issue templates | ||
| ``` |
There was a problem hiding this comment.
Add a language hint to the fenced block.
The repo tree block should declare a language (or text) to satisfy markdown linting.
🔧 Suggested update
-```
+```text
agentswarp/
├── src/main.ts Entry point (Hono server, SQLite setup)
...
└── .github/ CI, PR template, issue templates</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @AGENTS.md around lines 11 - 24, Update the fenced repo-tree block in
AGENTS.md to include a language hint (e.g., use text) so the markdown linter recognizes it; locate the fenced block that starts with the agentswarp/ tree and change the opening fence to include the language token (for example replace
with ```text) while leaving the tree content unchanged.
</details>
<!-- fingerprinting:phantom:poseidon:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| - `bun install && bun test && bun run build` — must pass on all PRs. | ||
| - Docker image build runs on `main` only. |
There was a problem hiding this comment.
CI section is outdated vs current workflow checks.
Line 123 currently documents install/test/build only, but CI now also runs lint and format-check gates.
📝 Suggested update
-- `bun install && bun test && bun run build` — must pass on all PRs.
+- `bun install && bun lint && bun format --check && bun test && bun run build` — must pass on all PRs.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 123 - 124, Update the CI notes in AGENTS.md to
reflect the current PR gates: change the first bullet that says "`bun install &&
bun test && bun run build` — must pass on all PRs." to include lint and
format-check (e.g. "`bun install && bun test && bun run build && bun run lint &&
bun run format:check` — must pass on all PRs.") and ensure the second bullet
about Docker image builds still notes "Docker image build runs on `main` only."
Make the text concise and accurate so the documented commands match the actual
CI workflow.
| |----------|---------| | ||
| | `PUBLIC_API_URL` | Frontend → API base URL (default `http://localhost:3001`) | | ||
| | `PUBLIC_WS_URL` | Frontend → WebSocket URL (default `ws://localhost:3001/ws`) | | ||
| | `SEARXNG_BASE_URL` | SearXNG instance URL (optional; falls back to DuckDuckGo) | |
There was a problem hiding this comment.
Env var name mismatches current tool implementation.
Line 79 documents SEARXNG_BASE_URL, but the tool implementation reads SEARXNG_URL. This mismatch will cause misconfiguration.
🔧 Suggested update
-| `SEARXNG_BASE_URL` | SearXNG instance URL (optional; falls back to DuckDuckGo) |
+| `SEARXNG_URL` | SearXNG instance URL (optional; falls back to DuckDuckGo) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | `SEARXNG_BASE_URL` | SearXNG instance URL (optional; falls back to DuckDuckGo) | | |
| | `SEARXNG_URL` | SearXNG instance URL (optional; falls back to DuckDuckGo) | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/phase-2-migration.md` at line 79, The docs list the environment variable
as SEARXNG_BASE_URL but the code reads SEARXNG_URL, causing a mismatch; update
the documentation entry to use SEARXNG_URL (or alternatively update the
implementation to accept SEARXNG_BASE_URL) so the documented env var name
matches the tool’s actual variable name (reference the env var symbols
SEARXNG_BASE_URL and SEARXNG_URL and the docs entry in phase-2-migration).
| - [ ] Add files marked **New** at the paths listed above. | ||
| - [ ] Update `docker-compose.yml` with the new memory-limited service definitions. | ||
| - [ ] Add Phase 2 env vars to `.env.example`. | ||
| - [ ] Register `searxng` in `packages/core/src/tool-registry.ts`. |
There was a problem hiding this comment.
Tool registration instruction points to the wrong module.
Line 93 currently directs registration in packages/core/src/tool-registry.ts, but your current wiring expects tool export/registration via packages/tools/src/index.ts path.
🔧 Suggested update
-- [ ] Register `searxng` in `packages/core/src/tool-registry.ts`.
+- [ ] Export and register `searxng` in `packages/tools/src/index.ts` (and ensure it is included in the runtime registry path used by the app).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - [ ] Register `searxng` in `packages/core/src/tool-registry.ts`. | |
| - [ ] Export and register `searxng` in `packages/tools/src/index.ts` (and ensure it is included in the runtime registry path used by the app). |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/phase-2-migration.md` at line 93, The docs point to registering searxng
in packages/core/src/tool-registry.ts but the codebase expects tools to be
exported/registered through packages/tools/src/index.ts; update the migration
note to instruct contributors to add the searxng export/registration in
packages/tools/src/index.ts (and ensure the module exports the searxng symbol
and any registration side-effect used by the runtime), referencing the searxng
export name so reviewers can find and wire it properly.
| const dbPath = process.env.DATABASE_URL ?? "agentswarp.db"; | ||
| const db = new Database(dbPath); |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify DB path conventions and whether src/main.ts ensures directory creation
rg -n "DATABASE_URL|DATABASE_PATH" .env.example docker-compose.yml src/main.ts
rg -n "new Database|mkdirSync|dirname" src/main.tsRepository: raynr7/agentswarp
Length of output: 374
Create parent directory before opening SQLite database.
The environment example at .env.example uses DATABASE_URL=./data/agentswarm.db with a nested path, but src/main.ts does not create the ./data directory before instantiating new Database(dbPath). This will fail on fresh deployments where the directory doesn't exist.
🔧 Suggested fix
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+
// SQLite setup — path from DATABASE_URL env var, fallback for local dev
const dbPath = process.env.DATABASE_URL ?? "agentswarp.db";
+try {
+ mkdirSync(dirname(dbPath), { recursive: true });
+} catch {}
const db = new Database(dbPath);📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const dbPath = process.env.DATABASE_URL ?? "agentswarp.db"; | |
| const db = new Database(dbPath); | |
| import { mkdirSync } from "fs"; | |
| import { dirname } from "path"; | |
| // SQLite setup — path from DATABASE_URL env var, fallback for local dev | |
| const dbPath = process.env.DATABASE_URL ?? "agentswarp.db"; | |
| try { | |
| mkdirSync(dirname(dbPath), { recursive: true }); | |
| } catch {} | |
| const db = new Database(dbPath); |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/main.ts` around lines 7 - 8, Ensure the parent directory for the SQLite
file exists before instantiating the Database: derive the directory from dbPath
(use path.dirname(dbPath)) and create it if missing (use fs.mkdirSync(dir, {
recursive: true }) or await fs.promises.mkdir(dir, { recursive: true })) prior
to calling new Database(dbPath); reference the dbPath constant and the Database
instantiation to locate where to add the directory creation.
1 participant
What does this PR do?
Applies the P0 and P1 fixes identified in the agent hygiene audit. Adds
AGENTS.mdas the primary orientation file for AI coding agents working in this repo.Why?
The repo had several issues that would cause silent failures for contributors and agents:
.gitignoreonly excluded.vercel, sonode_modules/,.env,*.db, and build output were unprotected.DATABASE_URLwas documented in.env.examplebut ignored in code.swarm-core.mdwas a 180 KB raw code dump with no navigational value.AGENTS.mdexisted to orient AI coding agents.Type of Change
Changes
.gitignorenode_modules/,dist/,.svelte-kit/,.env*,*.db,data/, logs, OS, editor dirssrc/main.tsDATABASE_URLenv var for SQLite path; fallback toagentswarp.db.github/workflows/ci.ymlbun lintandbun format --checkbefore test/build; fix CRLF line endingsswarm-core.mddocs/phase-2-migration.mdAGENTS.mdAGENTS-IMPROVEMENT-SPEC.mdHow to Test
git checkout fix/agent-hygiene-p0-p1node_modules/and.envare listed in.gitignoreDATABASE_URL=./test.db bun start— confirm server openstest.db, notagentswarp.dbChecklist
bun test)Note on CI lint step
bun lintandbun format --checkare now in CI, but the rootpackage.jsondoes not yet define those scripts. They will need to be added (pointing at ESLint and Prettier configs) before CI fully passes — tracked as a P2 item inAGENTS-IMPROVEMENT-SPEC.md.Summary by CodeRabbit
Bug Fixes
Documentation
Chores