From 23f0c9ee111b1ba53070f60c360e4ad96092a9ad Mon Sep 17 00:00:00 2001 From: flamboh Date: Tue, 29 Sep 2026 13:03:20 -0700 Subject: [PATCH 1/2] docs: trim agent guidance --- .cursor/rules/svelte.mdc | 243 +-------------------------------------- AGENTS.md | 16 +-- 2 files changed, 11 insertions(+), 248 deletions(-) diff --git a/.cursor/rules/svelte.mdc b/.cursor/rules/svelte.mdc index 9304b187..a810f22b 100644 --- a/.cursor/rules/svelte.mdc +++ b/.cursor/rules/svelte.mdc @@ -3,241 +3,10 @@ globs: apps/web/src/**/* alwaysApply: false --- -You are an expert in Svelte 5, SvelteKit, TypeScript, and modern web development. +Follow the Svelte state and chart contracts in `AGENTS.md`. -Key Principles - -- Write concise, technical code with accurate Svelte 5 and SvelteKit examples. -- Leverage SvelteKit's server-side rendering (SSR) and static site generation (SSG) capabilities. -- Prioritize performance optimization and minimal JavaScript for optimal user experience. -- Use descriptive variable names and follow Svelte and SvelteKit conventions. -- Organize files using SvelteKit's file-based routing system. - -Code Style and Structure - -- Write concise, technical TypeScript or JavaScript code with accurate examples. -- Use functional and declarative programming patterns; avoid unnecessary classes except for state machines. -- Prefer iteration and modularization over code duplication. -- Structure files: component logic, markup, styles, helpers, types. -- Follow Svelte's official documentation for setup and configuration: https://svelte.dev/docs - -Naming Conventions - -- Use lowercase with hyphens for component files (e.g., `components/auth-form.svelte`). -- Use PascalCase for component names in imports and usage. -- Use camelCase for variables, functions, and props. - -TypeScript Usage - -- Use TypeScript for all code; prefer interfaces over types. -- Avoid enums; use const objects instead. -- Use functional components with TypeScript interfaces for props. -- Enable strict mode in TypeScript for better type safety. - -Svelte Runes - -- `$state`: Declare reactive state - ```typescript - let count = $state(0); - ``` -- `$derived`: Compute derived values - ```typescript - let doubled = $derived(count * 2); - ``` -- `$effect`: Manage side effects and lifecycle - ```typescript - $effect(() => { - console.log(`Count is now ${count}`); - }); - ``` -- `$props`: Declare component props - ```typescript - let { optionalProp = 42, requiredProp } = $props(); - ``` -- `$bindable`: Create two-way bindable props - ```typescript - let { bindableProp = $bindable() } = $props(); - ``` -- `$inspect`: Debug reactive state (development only) - ```typescript - $inspect(count); - ``` - -UI and Styling - -- Use Tailwind CSS for utility-first styling approach. -- Leverage Shadcn components for pre-built, customizable UI elements. -- Import Shadcn components from `#lib/components/ui//index.ts`. -- Organize Tailwind classes using the `cn()` utility from `#lib/utils.ts`. -- Use Svelte's built-in transition and animation features. - -Shadcn Color Conventions - -- Use `background` and `foreground` convention for colors. -- Define CSS variables without color space function: - ```css - --primary: 222.2 47.4% 11.2%; - --primary-foreground: 210 40% 98%; - ``` -- Usage example: - ```svelte -
Hello
- ``` -- Key color variables: - - `--background`, `--foreground`: Default body colors - - `--muted`, `--muted-foreground`: Muted backgrounds - - `--card`, `--card-foreground`: Card backgrounds - - `--popover`, `--popover-foreground`: Popover backgrounds - - `--border`: Default border color - - `--input`: Input border color - - `--primary`, `--primary-foreground`: Primary button colors - - `--secondary`, `--secondary-foreground`: Secondary button colors - - `--accent`, `--accent-foreground`: Accent colors - - `--destructive`, `--destructive-foreground`: Destructive action colors - - `--ring`: Focus ring color - - `--radius`: Border radius for components - -SvelteKit Project Structure - -- Use the recommended SvelteKit project structure: - ``` - - src/ - - lib/ - - routes/ - - app.html - - static/ - - vite.config.ts - ``` - -Component Development - -- Create .svelte files for Svelte components. -- Use .svelte.ts files for component logic and state machines. -- Implement proper component composition and reusability. -- Use Svelte's props for data passing. -- Leverage Svelte's reactive declarations for local state management. - -State Management - -- Use classes for complex state management (state machines): - - ```typescript - // counter.svelte.ts - class Counter { - count = $state(0); - incrementor = $state(1); - - increment() { - this.count += this.incrementor; - } - - resetCount() { - this.count = 0; - } - - resetIncrementor() { - this.incrementor = 1; - } - } - - export const counter = new Counter(); - ``` - -- Use in components: - - ```svelte - - - - ``` - -Routing and Pages - -- Utilize SvelteKit's file-based routing system in the src/routes/ directory. -- Implement dynamic routes using [slug] syntax. -- Use load functions for server-side data fetching and pre-rendering. -- Implement proper error handling with +error.svelte pages. - -Server-Side Rendering (SSR) and Static Site Generation (SSG) - -- Leverage SvelteKit's SSR capabilities for dynamic content. -- Implement SSG for static pages using prerender option. -- Use the adapter-auto for automatic deployment configuration. - -Performance Optimization - -- Leverage Svelte's compile-time optimizations. -- Use `{#key}` blocks to force re-rendering of components when needed. -- Implement code splitting using dynamic imports for large applications. -- Profile and monitor performance using browser developer tools. -- Use `$effect.tracking()` to optimize effect dependencies. -- Minimize use of client-side JavaScript; leverage SvelteKit's SSR and SSG. -- Implement proper lazy loading for images and other assets. - -Data Fetching and API Routes - -- Use load functions for server-side data fetching. -- Implement proper error handling for data fetching operations. -- Create API routes in the src/routes/api/ directory. -- Implement proper request handling and response formatting in API routes. -- Use SvelteKit's hooks for global API middleware. - -SEO and Meta Tags - -- Use Svelte:head component for adding meta information. -- Implement canonical URLs for proper SEO. -- Create reusable SEO components for consistent meta tag management. - -Forms and Actions - -- Utilize SvelteKit's form actions for server-side form handling. -- Implement proper client-side form validation using Svelte's reactive declarations. -- Use progressive enhancement for JavaScript-optional form submissions. - -Internationalization (i18n) with Paraglide.js - -- Use Paraglide.js for internationalization: https://inlang.com/m/gerre34r/library-inlang-paraglideJs -- Install Paraglide.js: `bun add @inlang/paraglide-js` -- Set up language files in the `languages` directory. -- Use the `t` function to translate strings: - - ```svelte - - -

{t('welcome_message')}

- ``` - -- Support multiple languages and RTL layouts. -- Ensure text scaling and font adjustments for accessibility. - -Accessibility - -- Ensure proper semantic HTML structure in Svelte components. -- Implement ARIA attributes where necessary. -- Ensure keyboard navigation support for interactive elements. -- Use Svelte's bind:this for managing focus programmatically. - -Key Conventions - -1. Embrace Svelte's simplicity and avoid over-engineering solutions. -2. Use SvelteKit for full-stack applications with SSR and API routes. -3. Prioritize Web Vitals (LCP, FID, CLS) for performance optimization. -4. Use environment variables for configuration management. -5. Follow Svelte's best practices for component composition and state management. -6. Ensure cross-browser compatibility by testing on multiple platforms. -7. Keep your Svelte and SvelteKit versions up to date. - -Documentation - -- Svelte 5 Runes: https://svelte-5-preview.vercel.app/docs/runes -- Svelte Documentation: https://svelte.dev/docs -- SvelteKit Documentation: https://kit.svelte.dev/docs -- Paraglide.js Documentation: https://inlang.com/m/gerre34r/library-inlang-paraglideJs/usage - -Refer to Svelte, SvelteKit, and Paraglide.js documentation for detailed information on components, internationalization, and best practices. +- Use TypeScript and the existing shadcn-svelte components under `$lib/components/ui`. +- Combine conditional Tailwind classes with `cn` from `$lib/utils`. +- Use the semantic color tokens in `apps/web/src/app.css`. +- Keep component filenames lowercase with hyphens and imported component names PascalCase. +- Keep the deployment adapters and database-driver selection in `apps/web/vite.config.ts`. diff --git a/AGENTS.md b/AGENTS.md index d06f06b9..1d9f068d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ATLANTIS turns NetFlow captures and CSV imports into queryable aggregate databases, then visualizes them in a web dashboard. -## Repository Map +## Repository map - `tools/netflow-db`: Rust pipeline (`atlantis-netflow-db` crate) for ingestion, aggregation, verification, and analysis-window exports. Native `nfcapd` ingestion uses the pinned `nfdump` fork in `vendor/nfdump`. - `apps/web`: Svelte 5/SvelteKit 3 dashboard and API routes. It reads local SQLite during development and Cloudflare D1 in deployment. @@ -14,7 +14,7 @@ ATLANTIS turns NetFlow captures and CSV imports into queryable aggregate databas - `docs/code`: Architecture and development documentation. - `docs/agent`: Generated plans and analysis artifacts. -## Engineering Contracts +## Engineering contracts - Treat ingestion, storage, API queries, and charts as one data contract. When a stored field or dimension changes, account for every Rust writer and verifier, the local SQLite schema, the Drizzle schema and migrations, TypeScript query code, and focused tests. - A pipeline database is a product bound to its schema, flow selection, result configuration, and logical source membership. Semantic changes produce a fresh product database; never silently mix incompatible results in an existing one. @@ -30,19 +30,13 @@ Reuse the existing chart registries, chart utilities, and shared filter componen ## Verification -- Before completion, run `bun run format`, `bun run lint`, and `bun run typecheck` successfully. +- For code changes, run `bun run format`, `bun run lint`, and `bun run typecheck` successfully. For documentation-only changes, run the applicable formatter check. - Run focused tests for the changed surface: `bun run test:web` for dashboard/API behavior, `bun run test:db` for pipeline behavior, and `bun run test:e2e` for user flows that need browser coverage. - Use `bun run test`, not `bun test`; the latter invokes Bun's test runner instead of the repository's Vitest orchestration. - When editing the landing site, also run `bun run --cwd apps/landing lint` and `bun run build:landing`; the root lint script does not cover `apps/landing`. -## Pull Requests +## Pull requests Use the Conventional Commit style for PR titles. -Every PR description must give a reviewer a fast path to approval: - -- Name the flows to exercise, required setup or test data, and expected results. -- Call out important edge cases, failure states, and business-logic decisions. -- List automated verification and any remaining manual verification. - -Keep this focused on observable behavior and decisions rather than an exhaustive implementation summary. +Include a short human review guide with relevant flows, setup or test data, expected behavior, important edge cases, and decisions needing review. Distinguish automated verification from remaining manual checks. From 91bbeb66c018e06072551e4d5c09b6560499c7dd Mon Sep 17 00:00:00 2001 From: flamboh Date: Tue, 29 Sep 2026 13:15:23 -0700 Subject: [PATCH 2/2] docs: remove retired agent workflows --- .cursor/rules/svelte.mdc | 12 ------------ 1 file changed, 12 deletions(-) delete mode 100644 .cursor/rules/svelte.mdc diff --git a/.cursor/rules/svelte.mdc b/.cursor/rules/svelte.mdc deleted file mode 100644 index a810f22b..00000000 --- a/.cursor/rules/svelte.mdc +++ /dev/null @@ -1,12 +0,0 @@ ---- -globs: apps/web/src/**/* -alwaysApply: false ---- - -Follow the Svelte state and chart contracts in `AGENTS.md`. - -- Use TypeScript and the existing shadcn-svelte components under `$lib/components/ui`. -- Combine conditional Tailwind classes with `cn` from `$lib/utils`. -- Use the semantic color tokens in `apps/web/src/app.css`. -- Keep component filenames lowercase with hyphens and imported component names PascalCase. -- Keep the deployment adapters and database-driver selection in `apps/web/vite.config.ts`.