openstock: Instructions file for Codex

AGENTS.md

Guidelines for AI coding agents working in the OpenStock codebase.

Project Overview

Self-hosted inventory and stock management system:

• Framework: Nuxt 4 with Vue 3 Composition API
• Database: Cloudflare D1 (SQLite) with Drizzle ORM
• Styling: TailwindCSS
• Hosting: Cloudflare Pages via NuxtHub

Build/Lint/Test Commands

# Development
npm run dev              # Start dev server on http://localhost:3000

# Build
npm run build            # Production build
npm run preview          # Preview production build locally

# Database
npm run db:generate      # Generate migrations from schema changes
npm run db:populate      # Populate database with sample data
npm run db:export        # Export database
npm run db:sync          # Export and push to remote

# Deployment
npm run deploy:cf        # Build and deploy to Cloudflare Pages
npm run postinstall      # nuxt prepare (run after npm install)

Note: No test framework or linter is currently configured.

Project Structure

├── app/                    # Frontend (Nuxt 4 app directory)
│   ├── components/         # Vue components (ui/, charts/)
│   ├── composables/        # Vue composables (useAuth, useToast, useSettings)
│   ├── layouts/            # Page layouts
│   ├── pages/              # File-based routing
│   └── middleware/         # Route middleware
├── server/                 # Backend (Nitro)
│   ├── api/                # API endpoints (file-based routing)
│   ├── database/           # Drizzle schema (schema.ts)
│   ├── middleware/         # Server middleware (auth.ts)
│   └── utils/              # Server utilities (db.ts, id.ts)
├── migrations/             # SQL migration files
└── nuxt.config.ts          # Nuxt configuration

Code Style Guidelines

Imports

// 1. External packages first
import { eq, desc } from 'drizzle-orm';

// 2. Server schema imports using the ~ alias
import { products } from '~~/server/database/schema';
import type { Product, Category } from '~~/server/database/schema';

// Nuxt auto-imports (no explicit import needed): useDB, tables, defineEventHandler, ref, reactive, computed, useFetch