Skip to content

AGENTS.md

Latest commit

 

History

History
71 lines (58 loc) · 5.7 KB

AGENTS.md

File metadata and controls

71 lines (58 loc) · 5.7 KB

Repository Guidelines

Project Structure & Module Organization

This repo is a mixed Rust and TypeScript workspace. Core Rust crates live in crates/: ext-core holds domain logic, ext-api exposes workflows, ext is the CLI, ext-tauri is the desktop shell, and supporting crates such as ext-db, ext-calc, ext-report, ext-error, ext-render, and ext-agent* provide storage, calculation, reporting, error handling, rendering, and agent features. The desktop frontend lives in apps/desktop/src, and shared TypeScript contracts live in packages/shared/src.

Tests are mostly crate-local: Rust unit tests sit beside source files, and integration tests live under crates/*/tests. Large test fixtures are stored in paths like crates/ext-calc/tests/fixtures.

Build, Test, and Development Commands

  • pnpm dev: run the Tauri desktop app in development mode.
  • pnpm build: build the desktop app bundle through Tauri.
  • pnpm --filter desktop build: build only the Vite/React frontend.
  • pnpm gen-types: regenerate shared TS types from Rust test/type generation flows.
  • cargo test --workspace: run the standard Rust test suite.
  • cargo test -p ext: run CLI tests, including snapshot coverage.
  • cargo fmt --check --all: verify Rust formatting.
  • cargo clippy --workspace --all-targets: enforce workspace lint rules.

Coding Style & Naming Conventions

Follow rustfmt defaults for Rust and keep clippy warning-free; workspace lints treat broad Clippy findings as errors. Use snake_case for Rust modules/functions and PascalCase for Rust types.

Frontend code is TypeScript + React with 4-space indentation, PascalCase component files such as WorkspacePanel.tsx, and camelCase hooks/store helpers such as projectStore.ts. Keep shared type definitions in packages/shared/src/types aligned with Rust sources.

Testing Guidelines

Prefer focused crate tests while developing, then run cargo test --workspace before submitting. Name new integration tests by behavior, for example vcs_cycle.rs or foundation_cli.rs. Snapshot-based CLI tests live under crates/ext/tests.

Live ETABS coverage is opt-in only: crates/ext-api/tests/etabs_live.rs requires a real ETABS install plus EXT_ETABS_* environment variables from the workspace root .env.

Agent Worker Rules For Calc, Render, And Reports

For calculation, chart rendering, and Typst report work, first read docs/agent-worker-calc-render-report-guide.md. That file is the durable context for this mature API surface and should be updated when cross-crate workflow rules change.

Crate-specific specs:

  • crates/ext/CLI_WORKER_SPEC.md: CLI command surface, output modes, git-mimic commands, agent CLI entrypoint.
  • crates/ext-api/API_WORKER_SPEC.md: application workflows, state guards, sidecar orchestration, report/analyze orchestration.
  • crates/ext-core/CORE_WORKER_SPEC.md: pure domain types and deterministic domain logic.
  • crates/ext-db/CONFIG_STORAGE_WORKER_SPEC.md: shared/local config schema, persistent state schema, config validation.
  • crates/ext-calc/CALC_WORKER_SPEC.md: typed result loading, calculations, unit conversion, CalcOutput.
  • crates/ext-render/RENDER_WORKER_SPEC.md: chart builders, SVG rendering, logical image assets.
  • crates/ext-report/REPORT_WORKER_SPEC.md: report data adapters, page registry, PDF rendering, Typst templates.
  • crates/ext-error/ERROR_WORKER_SPEC.md: shared domain errors.
  • crates/ext-e2k/E2K_WORKER_SPEC.md: E2K parsing and comparison utilities.
  • crates/ext-agent/AI_AGENT_WORKER_SPEC.md: AI session loop, tool dispatch, confirmation gates, privacy boundaries.
  • crates/ext-agent-llm/LLM_PROVIDER_WORKER_SPEC.md: LLM provider adapters behind LlmClient.
  • crates/ext-tauri/DESKTOP_SHELL_WORKER_SPEC.md: Tauri desktop command/event shell.
  • crates/test-support/TEST_SUPPORT_WORKER_SPEC.md: test-only fixtures and helpers.

Strict ownership boundaries:

  • ext-db owns config schema and validation types.
  • ext-calc owns typed ETABS table loading, calculations, unit conversion, and CalcOutput.
  • ext-render owns chart/SVG asset construction from calculation output.
  • ext-report owns report JSON adapters, page registry, PDF rendering, and Typst templates.
  • ext owns CLI commands, ext init starter config, and CLI integration tests.

Strict workflow rules:

  • Do not put business calculation logic in Typst or chart builders.
  • Do not read raw ETABS exports from report templates or render code.
  • Use enums instead of strings for known domain values.
  • Filter ETABS aggregate rows before detailed aggregation unless a feature explicitly consumes aggregate rows.
  • Keep optional feature output as Option<T> in CalcOutput.
  • Add loaded summary lines for report data sections and pass/fail only for engineering checks.
  • When adding user-facing config, update ext init, fixture config, and CLI/init tests.
  • When editing .typ files, use the Typst authoring workflow, run typstyle --check, and render/inspect the affected page when layout changes.
  • Report tables should use shared table helpers and wide-data-table(theme, ...) when matching the standard report table style.

Context should be saved in repository docs rather than relying on chat history. Add a read-only context CLI only if repeated agent workflows need generated, drift-prone information; static architecture rules belong in Markdown.

Commit & Pull Request Guidelines

Recent history uses short, lower-case subjects such as update week 7 8 and fix some comment of week 5 6. Keep commits brief, imperative, and scoped to one change. For pull requests, include:

  • a short summary of affected crates/apps
  • linked issue or spec when applicable
  • exact test commands run
  • screenshots or screen recordings for apps/desktop UI changes