ZFile/AGENTS.md

AGENTS.md

This file is for coding agents working in this repository. Follow it as the default playbook for changes.

Scope

• Applies to the entire repository rooted at filez/.
• If a deeper-scoped AGENTS.md is added later, the deeper file wins for that subtree.

Rules Discovery

• Checked for Cursor rules: no .cursorrules and no .cursor/rules/* found.
• Checked for Copilot instructions: no .github/copilot-instructions.md found.
• Therefore, use this file + existing code conventions.

Repository Layout

• backend/ — Go API server (single-module Go app).
• frontend/ — Bun + Vite + React + TypeScript UI.
• dist/ — built single binary output (generated).
• Root Makefile — primary task entrypoints.
• Root .env — runtime config (do not commit secrets).

Core Commands

Run from repo root unless noted.

Setup

• Frontend deps: cd frontend && bun install --frozen-lockfile
• Backend deps: cd backend && go mod tidy

Build

• Full local build pipeline: make build-all
• Backend only: cd backend && go build ./...
• Frontend only: cd frontend && bun run build

Run

• Local full stack (binary + frontend dev): make run-local
• Backend only: make run-backend
• Frontend only: make run-frontend
• Docker detached: make up
• Docker foreground: make run-all
• Stop docker stack: make down

Lint / Format

• Frontend lint: cd frontend && bun run lint
• Backend format: cd backend && gofmt -w main.go
  • If touching more files, format all changed Go files.
• Backend sanity check: cd backend && go vet ./... (optional but recommended for larger changes)

Test

• Current state: no test files are present (*_test.go not found; no frontend test runner configured).
• Default verification:
  • cd backend && go build ./...
  • cd frontend && bun run build

Single Test (when tests are added)

• Go single test by name:
  • cd backend && go test -run TestName ./...
• Go single test in one package:
  • cd backend && go test -run TestName ./path/to/pkg
• Frontend single test is not applicable until a test framework is introduced.

Code Style: Global

• Keep changes minimal and focused.
• Prefer existing patterns over introducing new abstractions.
• Do not add dependencies unless required.
• Do not add comments for obvious code.
• Keep paths normalized and security-conscious (especially file paths).

Backend (Go) Style

• Use gofmt formatting.
• Group imports in standard Go style.
• Use camelCase for private names, PascalCase for exported types.
• Handler naming convention: handleXxx methods on *Server.
• Prefer small input structs for JSON payloads near handler usage.
• Parse/validate input early and return fast on errors.
• Use helper response functions (writeJSON, writeErr) consistently.
• Use explicit HTTP status codes (400/401/403/404/429/500 as appropriate).
• Keep errors user-safe; avoid leaking internals in API responses.
• Log security-relevant actions with user/path context.
• Use normalizePath and existing guard helpers for all path operations.
• Preserve auth/session middleware boundaries; do not bypass them.
• DB changes:
  • Add migrations in existing startup migration flow.
  • Keep indexes aligned with query patterns.

Frontend (React/TS) Style

• TypeScript strict mode is enabled; satisfy strict typing.
• noUnusedLocals/noUnusedParameters are enabled — remove dead code.
• Use functional components and hooks only.
• Keep naming explicit: loadFiles, movePathsTo, openMarkdownEditor, etc.
• Reuse UI primitives from src/components/ui/*.
• Keep className composition via existing utilities/patterns (cn where used).
• Preserve current no-semicolon style and existing quote style.
• Avoid introducing global state libraries; stay with local hook state unless needed.
• Keep RU/EN dictionary entries in sync when adding UI text.
• Prefer derived state via useMemo for computed lists/maps.
• Keep keyboard/mouse interaction behavior consistent with current UX patterns.

Error Handling Conventions

• Backend:
  • Validate request payloads and query params first.
  • Return JSON errors via writeErr.
  • Avoid panics; rely on recovery middleware as safety net only.
• Frontend:
  • Use api<T>() helper for HTTP.
  • Surface actionable errors via existing error state/UI.
  • Keep optimistic UI limited; refresh server state after mutating actions.

API / Data Conventions

• Auth is cookie-based JWT + refresh flow; keep that contract intact.
• User identity is username-based in API/UI.
• File entries use normalized absolute-style paths (/foo/bar).
• For multi-item operations, use batch endpoints when available.

Security / Secrets

• Never commit .env secrets.
• JWT_SECRET must be strong random in real deployments.
• Respect host/CORS checks driven by env.
• Keep upload/path handling resistant to traversal and invalid paths.

Agent Workflow Expectations

• Before finishing, run relevant build/lint commands.
• If tests are absent, explicitly report that and provide build verification.
• Update docs when behavior/config changes.
• Do not assume Docker-only workflows; local run paths are supported.

Quick Verification Checklist

• Backend builds: cd backend && go build ./...
• Frontend builds: cd frontend && bun run build
• Frontend lint (if UI touched): cd frontend && bun run lint
• Ensure no accidental secret/config leakage in diffs.