Skip to main content

Phase 1: Foundation

Monorepo scaffold, core types, data layer, adapter system

Goal​

Establish the working monorepo with all packages initialized and the core data layer functional. After this phase, we can load and type-check data from a content repository.

Tasks​

1.1 Monorepo Setup​

  • Root package.json with scripts
  • pnpm-workspace.yaml declaring apps/* and packages/*
  • turbo.json with task graph
  • .gitignore, .npmrc
  • CLAUDE.md, AGENTS.md
  • Root tsconfig.json (base config in @ever-works/tsconfig)
  • .editorconfig
  • .github/ workflows (CI, deploy)

1.2 Package: @ever-works/tsconfig​

  • packages/tsconfig/base.json — strict TypeScript base
  • packages/tsconfig/astro.json — Astro-specific extends
  • packages/tsconfig/package.json

1.3 Package: @ever-works/eslint-config​

  • packages/eslint-config/index.mjs — ESLint 9 flat config
  • packages/eslint-config/package.json

1.4 Package: @ever-works/core​

  • packages/core/src/types/item.ts — ItemData
  • packages/core/src/types/category.ts — CategoryData, CategoryWithCount
  • packages/core/src/types/tag.ts — TagData, TagWithCount
  • packages/core/src/types/collection.ts — CollectionData
  • packages/core/src/types/comparison.ts — ComparisonData, ComparisonDimension
  • packages/core/src/types/config.ts — SiteConfig and sub-types
  • packages/core/src/types/index.ts — Barrel export
  • packages/core/src/content-reader.ts — Content orchestration, computes counts
  • packages/core/src/loaders/config-loader.ts — Config file loading
  • packages/core/src/loaders/item-loader.ts — Item directory traversal + parsing
  • packages/core/src/loaders/category-loader.ts — Category YAML loading
  • packages/core/src/loaders/tag-loader.ts — Tag YAML loading
  • packages/core/src/loaders/collection-loader.ts — Collection loading
  • packages/core/src/loaders/comparison-loader.ts — Comparison loading
  • packages/core/src/index.ts — Public API barrel export
  • packages/core/package.json
  • packages/core/tsconfig.json

1.5 Package: @ever-works/adapters​

  • packages/adapters/src/types.ts — DataAdapter interface, AdapterConfig
  • packages/adapters/src/git-adapter.ts — Git clone adapter
  • packages/adapters/src/filesystem-adapter.ts — Local filesystem adapter
  • packages/adapters/src/create-adapter.ts — Factory function
  • packages/adapters/src/index.ts — Barrel export
  • packages/adapters/package.json
  • packages/adapters/tsconfig.json

1.6 Package: @ever-works/plugins​

  • packages/plugins/src/types.ts — Plugin, PluginHooks, PluginContext interfaces
  • packages/plugins/src/runner.ts — PluginRunner lifecycle execution
  • packages/plugins/src/logger.ts — Scoped plugin logger
  • packages/plugins/src/define-plugins.ts — Configuration helper with dependency resolution
  • packages/plugins/src/index.ts — Barrel export
  • packages/plugins/package.json
  • packages/plugins/tsconfig.json

1.7 Build Script​

  • apps/web/scripts/clone-content.ts — Prebuild script to clone data repo
  • .env.example — Template environment variables

Dependencies​

  • yaml — YAML parsing
  • typescript — Type checking
  • astro — Framework (for web app in Phase 3)
  • @astrojs/preact — Preact integration (for Phase 2 components)
  • preact — Interactive islands
  • tailwindcss — CSS utility framework (for Phase 2)

Success Criteria​

  1. pnpm install works without errors
  2. pnpm typecheck passes for all packages
  3. packages/core can parse sample YAML data into typed objects
  4. packages/adapters can clone a git repo and read files
  5. All TypeScript interfaces match the full template's data format