Skip to content

v0.1.0: Storefront Foundation and Agent Ecosystem

Pre-release
Pre-release

Choose a tag to compare

@raouf-b-dev raouf-b-dev released this 07 Sep 12:34
· 461 commits to master since this release
67e58a7

Release v0.1.0: Storefront Foundation and Agent Ecosystem

This cut establishes the Next.js 16 storefront foundation and locks the repository agent ecosystem, development conventions, and architecture decisions.

The application runs as a clean App Router shell on port 3100 using React 19, Tailwind CSS v4, strict TypeScript, and a pre-generated OpenAPI schema. Shopper authentication, catalog data fetching, cart management, and checkout flows remain intentionally out of scope for this milestone.

Scope

In this release Not in this release
Next.js 16 App Router shell, React 19, React Compiler, Cache Components Shopper authentication, session context, token refresh
Tailwind CSS v4 setup, base shadcn primitives, Sonner Catalog browsing, category filters, product detail pages
Vitest unit suite, Playwright smoke spec, ESLint flat config Persistent cart state and line item mutations
Pre-generated OpenAPI TypeScript definitions (committed) Checkout command, idempotency handling, order polling
Parallel CI workflow (lint, typecheck, unit, build, audit) and Dependabot Customer profile and order history views
Canonical AGENT.md, project context, conventions, quality gates, six ADRs Standalone MSW mock preview server
Port 3100 configuration and API CORS origin companion alignment Full end-to-end multi-process CI test suites

Core Application and Shell

  • Scaffolded with Next.js 16.3.4 App Router, React 19, and Tailwind CSS v4 without modifying existing repository licenses or documentation.
  • Configuration in next.config.ts enables cacheComponents, reactCompiler, and typedRoutes.
  • Baseline HTTP security headers configured in next.config.ts: X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, X-Frame-Options: DENY, and Content-Security-Policy: frame-ancestors 'none'.
  • Strict script-src CSP is omitted for now to prevent breaking upcoming theme hydration scripts.
  • Base shadcn UI components installed (button, input, card, alert, sonner) using the official compiled cn utility with @/lib/utils re-export.
  • Standard document scrolling preserved. Fixed viewport overflow layouts are explicitly avoided.

Tooling, Quality Gates, and CI

  • Node.js runtime set to 24 with matching .nvmrc and package engines.
  • Strict TypeScript configuration with noUncheckedIndexedAccess and path alias @/* mapping to src/*.
  • ESLint flat configuration mirroring the admin dashboard standard: typescript-eslint, react-hooks (React 19), jsx-a11y, and consistent-type-imports.
  • Vitest unit testing configured with jsdom, Testing Library, and an explicit path alias resolver.
  • Playwright smoke test configured for port 3100 to verify that the home shell loads.
  • GitHub Actions CI pipeline executing parallel jobs for lint, typecheck, unit-tests, build, and audit, reporting to a unified ci aggregator.
  • Dependabot configuration for automated weekly npm and GitHub Actions dependency updates.

API Integration and Contract

  • OpenAPI generator script ported from the admin dashboard to scripts/generate-api-client.js.
  • Generated schema.d.ts committed directly to the repository so continuous integration builds offline without requiring a live backend.
  • Companion update applied to ecommerce-store-api: http://localhost:3100 added to CORS_ALLOWED_ORIGINS across environment templates.
  • Environment bootstrap script in scripts/generate-env.js targeting .env.local and .secrets.

Agent Ecosystem and Governance

  • AGENT.md establishes canonical governance, order of authority, and the six non-negotiable project rules.
  • Thin adapter files (AGENTS.md, CLAUDE.md, .cursor/rules/agent-rules.mdc) point directly to AGENT.md without duplicating policy.
  • Comprehensive AI guidance committed under docs/ai/: CONVENTIONS.md, GOVERNANCE-AND-QUALITY-GATES.md, and WORKFLOW-PLAYBOOK.md.
  • Six architectural decision records documented under docs/architecture/adr/:
    • ADR-0001: RSC catalog, browser session client, and no BFF (Accepted).
    • ADR-0002: In-memory access token with HttpOnly refresh cookie (Proposed).
    • ADR-0003: Single-flight silent refresh (Proposed).
    • ADR-0004: No guest cart (Proposed).
    • ADR-0005: Checkout order polling (Proposed).
    • ADR-0006: No proxy for auth or headers (Accepted).
  • Delivery roadmap updated: Phase 0 and Phase 1 marked complete in docs/ROADMAP.md.