diff --git a/.gitignore b/.gitignore index 016b59e..7697def 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,5 @@ pnpm-debug.log* # jetbrains setting folder .idea/ + +.direnv diff --git a/.vscode/extensions.json b/.vscode/extensions.json deleted file mode 100644 index 22a1505..0000000 --- a/.vscode/extensions.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "recommendations": ["astro-build.astro-vscode"], - "unwantedRecommendations": [] -} diff --git a/.vscode/launch.json b/.vscode/launch.json deleted file mode 100644 index d642209..0000000 --- a/.vscode/launch.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "version": "0.2.0", - "configurations": [ - { - "command": "./node_modules/.bin/astro dev", - "name": "Development server", - "request": "launch", - "type": "node-terminal" - } - ] -} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6a6df8b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,215 @@ +# AGENTS.md - Agentic Coding Guidelines + +This file provides guidelines for AI coding agents working in this repository. + +## Project Overview + +- **Type**: Astro web application (static site generator) +- **Language**: TypeScript +- **Framework**: Astro 5.x +- **Package Manager**: pnpm +- **Module System**: ES Modules (`"type": "module"`) + +## Project Structure + +``` +src/ +├── assets/ # Image assets (SVGs, images) +├── components/ # Reusable Astro components (.astro files) +├── layouts/ # Layout components wrapping pages +└── pages/ # File-based routing (each file = a route) +public/ # Static assets served at root (favicons, etc.) +dist/ # Build output (gitignored) +``` + +## Build/Lint/Test Commands + +### Development + +```bash +pnpm install # Install dependencies +pnpm dev # Start dev server at localhost:4321 +pnpm build # Build production site to ./dist/ +pnpm preview # Preview production build locally +``` + +### Type Checking + +```bash +pnpm astro check # Run Astro + TypeScript type checking +``` + +### Linting & Formatting (Biome) + +```bash +biome check . # Check linting and formatting +biome check --write . # Auto-fix linting and formatting issues +biome format --write . # Format files only +biome lint . # Lint files only +biome lint --write . # Auto-fix lint issues only +``` + +### Testing + +No testing framework is currently configured. When tests are added: + +```bash +# Future: Run all tests +pnpm test + +# Future: Run a single test file +pnpm test path/to/file.test.ts + +# Future: Run tests matching a pattern +pnpm test -t "pattern" +``` + +## Code Style Guidelines + +### Formatting (Biome) + +- **Indentation**: Tabs (not spaces) +- **Quotes**: Double quotes for strings +- **Semicolons**: Required (Biome default) +- **Trailing commas**: Use trailing commas in multiline structures +- **Line width**: 80 characters (Biome default) + +### Imports + +- Imports are auto-organized by Biome +- Order: External packages first, then internal modules +- Use named imports when possible +- Prefer explicit imports over namespace imports + +```typescript +// Good +import { useState, useEffect } from "react"; +import { Button } from "../components/Button"; + +// Avoid +import * as React from "react"; +``` + +### TypeScript + +- **Strict mode enabled** via `astro/tsconfigs/strict` +- Always provide explicit types for function parameters +- Use `interface` for object shapes, `type` for unions/intersections +- Avoid `any` - use `unknown` if type is truly unknown +- Use optional chaining (`?.`) and nullish coalescing (`??`) + +```typescript +// Good +interface Props { + title: string; + description?: string; +} + +function greet(name: string): string { + return `Hello, ${name}`; +} + +// Avoid +function greet(name): any { + return "Hello, " + name; +} +``` + +### Naming Conventions + +- **Files**: kebab-case for utilities (`format-date.ts`), PascalCase for components (`Button.astro`) +- **Components**: PascalCase (`WelcomeBanner`, `NavBar`) +- **Functions/Variables**: camelCase (`getUserData`, `isLoading`) +- **Constants**: UPPER_SNAKE_CASE for true constants (`MAX_RETRIES`, `API_BASE_URL`) +- **Types/Interfaces**: PascalCase (`UserProfile`, `ApiResponse`) +- **Boolean variables**: Prefix with `is`, `has`, `should`, `can` (`isVisible`, `hasError`) + +### Astro Components + +- Use `.astro` extension for Astro components +- Frontmatter goes between `---` fences at the top +- Props interface defined in frontmatter +- Scoped styles with ` +``` + +### Error Handling + +- Use try/catch for async operations +- Provide meaningful error messages +- Log errors appropriately for debugging +- Handle edge cases explicitly + +```typescript +try { + const data = await fetchData(); + return data; +} catch (error) { + console.error("Failed to fetch data:", error); + throw new Error(`Data fetch failed: ${error.message}`); +} +``` + +### Comments + +- Use JSDoc for public functions and complex types +- Keep comments concise and meaningful +- Prefer self-documenting code over comments +- Use `// TODO:` for planned improvements +- Use `// FIXME:` for known issues + +```typescript +/** + * Formats a date for display in the UI. + * @param date - The date to format + * @param locale - Optional locale string (defaults to 'en-US') + * @returns Formatted date string + */ +function formatDate(date: Date, locale = "en-US"): string { + return date.toLocaleDateString(locale); +} +``` + +## Development Environment + +This project uses Nix Flakes for reproducible development environments: + +```bash +# If using direnv (recommended) +direnv allow + +# Or manually enter the dev shell +nix develop +``` + +The Nix shell provides: Node.js, pnpm, Biome, PostgreSQL, and language servers. + +## VS Code Integration + +Recommended extensions are configured in `.vscode/extensions.json`: +- Astro language support +- Biome for formatting/linting + +## Before Committing + +1. Run type checking: `pnpm astro check` +2. Run linting/formatting: `biome check --write .` +3. Build successfully: `pnpm build` +4. Test locally if applicable: `pnpm preview` diff --git a/astro.config.mjs b/astro.config.mjs index e762ba5..17f6a62 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -1,5 +1,5 @@ // @ts-check -import { defineConfig } from 'astro/config'; +import { defineConfig } from "astro/config"; // https://astro.build/config export default defineConfig({}); diff --git a/biome.json b/biome.json new file mode 100644 index 0000000..10a6d2f --- /dev/null +++ b/biome.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.4.1/schema.json", + "vcs": { + "enabled": true, + "clientKind": "git", + "useIgnoreFile": true + }, + "files": { + "ignoreUnknown": false, + "includes": ["**", "!**/nix/store"] + }, + "formatter": { + "enabled": true, + "indentStyle": "tab" + }, + "linter": { + "enabled": true, + "rules": { + "recommended": true + } + }, + "javascript": { + "formatter": { + "quoteStyle": "double" + } + }, + "assist": { + "enabled": true, + "actions": { + "source": { + "organizeImports": "on" + } + } + }, + "overrides": [ + { + "includes": ["**/*.svelte", "**/*.astro", "**/*.vue"], + "linter": { + "rules": { + "style": { + "useConst": "off", + "useImportType": "off" + }, + "correctness": { + "noUnusedVariables": "off", + "noUnusedImports": "off" + } + } + } + } + ] +} diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..35cbdc3 --- /dev/null +++ b/flake.lock @@ -0,0 +1,64 @@ +{ + "nodes": { + "flake-utils": { + "inputs": { + "systems": [ + "systems" + ] + }, + "locked": { + "lastModified": 1731533236, + "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", + "owner": "numtide", + "repo": "flake-utils", + "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", + "type": "github" + }, + "original": { + "owner": "numtide", + "repo": "flake-utils", + "type": "github" + } + }, + "nixpkgs": { + "locked": { + "lastModified": 1771177547, + "narHash": "sha256-trTtk3WTOHz7hSw89xIIvahkgoFJYQ0G43IlqprFoMA=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "ac055f38c798b0d87695240c7b761b82fc7e5bc2", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixpkgs-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "root": { + "inputs": { + "flake-utils": "flake-utils", + "nixpkgs": "nixpkgs", + "systems": "systems" + } + }, + "systems": { + "locked": { + "lastModified": 1681028828, + "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", + "owner": "nix-systems", + "repo": "default", + "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", + "type": "github" + }, + "original": { + "owner": "nix-systems", + "repo": "default", + "type": "github" + } + } + }, + "root": "root", + "version": 7 +} diff --git a/flake.nix b/flake.nix index a72734b..2312b9d 100644 --- a/flake.nix +++ b/flake.nix @@ -22,7 +22,6 @@ # Executables nodejs pnpm - biome postgresql # Dev Tools diff --git a/package.json b/package.json index e314887..279247a 100644 --- a/package.json +++ b/package.json @@ -1,14 +1,18 @@ { - "name": "dnsc-io", - "type": "module", - "version": "0.0.1", - "scripts": { - "dev": "astro dev", - "build": "astro build", - "preview": "astro preview", - "astro": "astro" - }, - "dependencies": { - "astro": "^5.17.1" - } -} \ No newline at end of file + "name": "dnsc-io", + "type": "module", + "version": "0.0.1", + "scripts": { + "dev": "astro dev", + "build": "astro build", + "preview": "astro preview", + "astro": "astro", + "lint": "biome check --write ." + }, + "dependencies": { + "astro": "^5.17.1" + }, + "devDependencies": { + "@biomejs/biome": "2.4.1" + } +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 580eda4..b403450 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -11,6 +11,10 @@ importers: astro: specifier: ^5.17.1 version: 5.17.2(rollup@4.57.1)(typescript@5.9.3) + devDependencies: + '@biomejs/biome': + specifier: 2.4.1 + version: 2.4.1 packages: @@ -48,6 +52,59 @@ packages: resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==} engines: {node: '>=6.9.0'} + '@biomejs/biome@2.4.1': + resolution: {integrity: sha512-8c5DZQl1hfpLRlTZ21W5Ef2R314E4UJUEtkMbo303ElTVe6fYtapwldv7tZlgwm+9YP0Mhk7dUSTkOY8nQ2/2w==} + engines: {node: '>=14.21.3'} + hasBin: true + + '@biomejs/cli-darwin-arm64@2.4.1': + resolution: {integrity: sha512-wKiX2znbgFRaivRplSbu53hiREp1ohlGRuWqOL90IPetLi5E32tkiMYu8uSLXVzDgbIVM58WsesPaczIVtJkOQ==} + engines: {node: '>=14.21.3'} + cpu: [arm64] + os: [darwin] + + '@biomejs/cli-darwin-x64@2.4.1': + resolution: {integrity: sha512-rxLYVg3skeXh9K0om7JdkKcCdvtqrF9ECZ7dsmLuYObboK7DZ1J0z6xc2NGKSXw+cEQo3ie6NQgWBcdGJ16yQg==} + engines: {node: '>=14.21.3'} + cpu: [x64] + os: [darwin] + + '@biomejs/cli-linux-arm64-musl@2.4.1': + resolution: {integrity: sha512-Brwh/QL3wfX5UyZcyEamS1Q+EF8Q7ud+MS5mq/9BWX2ArfxQlgsqlukwK92xrGpXWcspXkSG9U0CoxvCZZkTKQ==} + engines: {node: '>=14.21.3'} + cpu: [arm64] + os: [linux] + + '@biomejs/cli-linux-arm64@2.4.1': + resolution: {integrity: sha512-nlGO5KzoEKhGj2i3QXyyNCeFk8SVwyes0wo0/X9w943darnlAHfi8MYYunPf8lsz5C0JaH6pJYB6D9HnDwUPQA==} + engines: {node: '>=14.21.3'} + cpu: [arm64] + os: [linux] + + '@biomejs/cli-linux-x64-musl@2.4.1': + resolution: {integrity: sha512-kz1QpA+PXouNyWw2VzeoMlzMn99hlyOC/El2uSy+DS8gcb6tOsKEeZ5e2onnFIfZKe9AeKMFbTowDNLXwjwGjw==} + engines: {node: '>=14.21.3'} + cpu: [x64] + os: [linux] + + '@biomejs/cli-linux-x64@2.4.1': + resolution: {integrity: sha512-Rmhm/mQ/3pejy1WtWLKurV1fN6zvCrqKz/ART2ZzgqY4ozL07uys5R9jA0A+yLjA79JTkcpIe85ygXv0FnSPRg==} + engines: {node: '>=14.21.3'} + cpu: [x64] + os: [linux] + + '@biomejs/cli-win32-arm64@2.4.1': + resolution: {integrity: sha512-e+PrlbQ/tez7W9EAzzCGUH1ovq31kR5r8sfCDzasrmoADLnDafet8pA8LdXnt0GwkeOem5Hz6WHCVZPRmaXiXw==} + engines: {node: '>=14.21.3'} + cpu: [arm64] + os: [win32] + + '@biomejs/cli-win32-x64@2.4.1': + resolution: {integrity: sha512-kfjOCzvaHC7olg8pmEuSsYzHntxdipkAGzr5nFiaEU2EPDWRE/myqUBaFDl9pHqEc8yEtQFiXF945PlTSkuOTw==} + engines: {node: '>=14.21.3'} + cpu: [x64] + os: [win32] + '@capsizecss/unpack@4.0.0': resolution: {integrity: sha512-VERIM64vtTP1C4mxQ5thVT9fK0apjPFobqybMtA1UdUujWka24ERHbRHFGmpbbhp73MhV+KSsHQH9C6uOTdEQA==} engines: {node: '>=18'} @@ -1704,6 +1761,41 @@ snapshots: '@babel/helper-string-parser': 7.27.1 '@babel/helper-validator-identifier': 7.28.5 + '@biomejs/biome@2.4.1': + optionalDependencies: + '@biomejs/cli-darwin-arm64': 2.4.1 + '@biomejs/cli-darwin-x64': 2.4.1 + '@biomejs/cli-linux-arm64': 2.4.1 + '@biomejs/cli-linux-arm64-musl': 2.4.1 + '@biomejs/cli-linux-x64': 2.4.1 + '@biomejs/cli-linux-x64-musl': 2.4.1 + '@biomejs/cli-win32-arm64': 2.4.1 + '@biomejs/cli-win32-x64': 2.4.1 + + '@biomejs/cli-darwin-arm64@2.4.1': + optional: true + + '@biomejs/cli-darwin-x64@2.4.1': + optional: true + + '@biomejs/cli-linux-arm64-musl@2.4.1': + optional: true + + '@biomejs/cli-linux-arm64@2.4.1': + optional: true + + '@biomejs/cli-linux-x64-musl@2.4.1': + optional: true + + '@biomejs/cli-linux-x64@2.4.1': + optional: true + + '@biomejs/cli-win32-arm64@2.4.1': + optional: true + + '@biomejs/cli-win32-x64@2.4.1': + optional: true + '@capsizecss/unpack@4.0.0': dependencies: fontkitten: 1.0.2 diff --git a/src/components/Welcome.astro b/src/components/Welcome.astro index 52e0333..a397df7 100644 --- a/src/components/Welcome.astro +++ b/src/components/Welcome.astro @@ -1,6 +1,6 @@ --- -import astroLogo from '../assets/astro.svg'; -import background from '../assets/background.svg'; +import astroLogo from "../assets/astro.svg"; +import background from "../assets/background.svg"; ---
diff --git a/src/pages/index.astro b/src/pages/index.astro index c04f360..644ac40 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -1,6 +1,6 @@ --- -import Welcome from '../components/Welcome.astro'; -import Layout from '../layouts/Layout.astro'; +import Welcome from "../components/Welcome.astro"; +import Layout from "../layouts/Layout.astro"; // Welcome to Astro! Wondering what to do next? Check out the Astro documentation at https://docs.astro.build // Don't want to use any of this? Delete everything in this file, the `assets`, `components`, and `layouts` directories, and start fresh. diff --git a/tsconfig.json b/tsconfig.json index 8bf91d3..a9210e6 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,5 +1,5 @@ { - "extends": "astro/tsconfigs/strict", - "include": [".astro/types.d.ts", "**/*"], - "exclude": ["dist"] + "extends": "astro/tsconfigs/strict", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"] }