chore: ESLint 설정 추가 및 AGENTS.md 업데이트

SOIV · claude · SOIV · commit a564100d198d · 2026-04-14T04:18:09.000+09:00
- ESLint 설정 구성 (@typescript-eslint/recommended, react-hooks/recommended)
- no-explicit-any error, consistent-type-imports warn, no-console warn 규칙 적용
- stories 파일 ESLint 오버라이드 추가 (Storybook render 함수 패턴 허용)
- 각 패키지에 lint 스크립트 추가
- foundation.ts 인덱스 시그니처 → Record 타입으로 수정
- main.tsx FormEvent를 type import로 수정
- HomeView 빈 onClick 핸들러를 Marketplace 이동으로 수정
- AGENTS.md: P0/P0.5 구현 완료 상태 반영, pnpm lint 커맨드 추가

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -5,6 +5,33 @@ module.exports = {
     node: true,
     browser: true,
   },
-  extends: [],
-  ignorePatterns: ["dist", "node_modules"],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+    ecmaFeatures: { jsx: true },
+  },
+  plugins: ['@typescript-eslint', 'react-hooks'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/stylistic',
+    'plugin:react-hooks/recommended',
+  ],
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/consistent-type-imports': 'warn',
+    'no-console': ['warn', { allow: ['warn', 'error'] }],
+  },
+  ignorePatterns: ['dist', 'node_modules', '*.js', '*.cjs'],
+  overrides: [
+    {
+      files: ['**/*.stories.tsx'],
+      rules: {
+        'react-hooks/rules-of-hooks': 'off',
+        '@typescript-eslint/no-empty-function': 'off',
+      },
+    },
+  ],
 };
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,201 +1,55 @@
 # AGENTS.md - Fieldstack Agent Guide
 
-> Project Status: Planning/Documentation phase (implementation planned 2026-2027)
-> This repo currently contains specifications and design docs. No source code yet.
-
----
-
-## Repository Orientation
-
-- Primary docs: `docs/v2_FINANCIAL-LEDGER/` (mostly Korean).
-- Public overview: `README.md`.
-- Treat commands and conventions as planned until implementation lands.
-
----
-
-## Build / Lint / Test Commands
-
-**Current State**: No build system implemented yet. Commands below are planned.
-
-**Planned Dev/Build/Test/Lint (from docs)**:
-
-```bash
-# Development (when implemented)
-pnpm dev            # Run dev workflow (see 98-build-process.md)
-pnpm dev:web        # Vite dev server (port 5173)
-pnpm dev:api        # Express backend (port 3000)
-
-# Production build
-pnpm build          # Build all packages (integrated mode)
-pnpm build:web      # Frontend only
-pnpm build:api      # Backend only
-pnpm start          # Start production server
-
-# Testing (planned: Vitest + React Testing Library)
-pnpm test           # Run all tests
-pnpm test:unit      # Unit tests only
-pnpm test:e2e       # E2E tests (Playwright)
-pnpm test:watch     # Watch mode
-
-# Linting (planned: ESLint + Prettier)
-pnpm lint           # Lint all code
-pnpm lint:fix       # Auto-fix issues
-pnpm format         # Format with Prettier
-
-# Type checking
-pnpm typecheck      # TypeScript type checking
-```
-
-**Single Test Runs**:
-- No single-test command is documented yet.
-- Once scripts exist, prefer project-defined commands in `package.json`.
-
----
-
-## Build Process Details (Docs)
-
-Reference: `docs/v2_FINANCIAL-LEDGER/deployment/98-build-process.md`
-
-**Root scripts (planned)**:
-
-```json
-{
-  "scripts": {
-    "dev": "pnpm --parallel dev",
-    "dev:api": "pnpm --filter api dev",
-    "dev:web": "pnpm --filter web dev",
-    "build": "pnpm build:web && pnpm build:api && pnpm postbuild",
-    "build:web": "pnpm --filter web build",
-    "build:api": "pnpm --filter api build",
-    "postbuild": "node scripts/copy-frontend.js",
-    "start": "cd apps/api && node dist/index.js",
-    "test": "pnpm --recursive test",
-    "lint": "pnpm --recursive lint"
-  }
-}
-```
-
-**Build verification (planned)**:
-
-```bash
-ls -la apps/web/dist
-ls -la apps/api/dist
-ls -la apps/api/public
-du -sh apps/web/dist
-du -sh apps/api/dist
-du -sh apps/api/public
-cd apps/api
-node dist/index.js
-```
-
----
-
-## Code Style & Conventions (Planned)
-
-### TypeScript Strictness
-
-- Use strict TS settings (planned in `tsconfig.json`).
-- Never use `any`, `@ts-ignore`, or `@ts-expect-error`.
-
-### Type Definitions
-
-- Prefer `interface` for object shapes.
-- Use `type` for unions, intersections, utilities.
-- Define module types in `types/index.ts`.
-
-### Imports
-
-Order (planned ESLint rule):
-1. External libraries (`react`, `express`)
-2. Internal packages (`@fieldstack/core`, `@fieldstack/controls`)
-3. Relative imports (`./`, `../`)
-
-Use `import type` for types.
-
-### Naming Conventions
-
-| Item | Convention | Example |
-| --- | --- | --- |
-| Components | PascalCase | `MyComponent.tsx` |
-| Hooks | `use` + camelCase | `useLedger.ts` |
-| Services | camelCase | `ledgerService.ts` |
-| Types/Interfaces | PascalCase | `LedgerItem` |
-| Constants | UPPER_SNAKE_CASE | `MAX_FILE_SIZE` |
-| Files | kebab-case or PascalCase | `ledger-list.tsx` |
-| API routes | kebab-case | `/api/ledger-items` |
-
-### Error Handling
-
-- Backend: explicit try/catch with meaningful status + message.
-- Frontend: user-friendly error messages; rethrow when caller needs it.
-- Never leave empty catch blocks.
-- Never log sensitive data (tokens, passwords).
-
-### Validation
-
-- Zod is preferred for input validation.
-- Yup is listed as an alternative, but use Zod unless module docs require otherwise.
-
----
-
-## UI/UX Guidelines (Planned)
-
-- UI is fully separated from core/module business logic.
-- Prefer `@fieldstack/controls` components for consistency.
-- Tailwind CSS is the planned styling approach.
-- Users can override UI with `apps/web/src/custom-ui/`.
-
-Design tokens (from `docs/v2_FINANCIAL-LEDGER/ui/design-system.md`):
-- Primary color: blue scale (500 = `#3B82F6`).
-- Semantic colors: success `#10B981`, warning `#F59E0B`, danger `#EF4444`.
-- Fonts: Inter (text), JetBrains Mono (code).
-- Breakpoints: `sm <= 640`, `md >= 768`, `lg >= 1024`.
-
----
-
-## Module Rules (Planned)
-
-- Modules are self-contained (no cross-module imports).
-- Keep `frontend/`, `backend/`, `types/` within each module.
-- Use Event Bus for inter-module communication.
-- Core only forwards file uploads; modules validate/parse/process.
-- Privacy-first: no telemetry, no SaaS, no data collection.
-
----
-
-## Testing Guidelines (Planned)
-
-- Backend: Vitest
-- Frontend: React Testing Library
-- E2E: Playwright (optional)
-- Write tests for critical paths
-
----
-
-## Tooling & Infra (Planned)
-
-- Package manager: pnpm (workspace)
-- Node.js: >= 20
-- TypeScript: >= 5
-- React: >= 18
-- Backend: Express (or Fastify)
-
----
-
-## Cursor / Copilot Rules
-
-- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found.
-
----
-
-## Key References
-
-- `docs/v2_FINANCIAL-LEDGER/technical/tech-stack.md`
-- `docs/v2_FINANCIAL-LEDGER/deployment/98-build-process.md`
-- `docs/v2_FINANCIAL-LEDGER/ui/design-system.md`
-- `docs/v2_FINANCIAL-LEDGER/ui/core-components.md`
-- `README.md`
-
----
-
-Last Updated: 2026-02-03
+This file provides high-signal, repo-specific guidance for AI agents working in the Fieldstack repository. Read this before taking action to avoid architectural mistakes.
+
+## Project Status & Environment
+- **Current Phase**: Phase 1.5 in progress. Core UI Shell is running but mostly mocked. Backend API endpoints are largely unimplemented.
+- **Workspace**: `pnpm` workspace with `node-linker=hoisted`.
+- **References**: Check `CLAUDE.md` and `docs/v2_FINANCIAL-LEDGER/` for phase-specific checklists and design tokens.
+
+## Developer Commands
+
+### Development Servers
+- `pnpm dev` — Runs web + api in parallel (includes setup wizard).
+- `pnpm dev:bypass` — **(Crucial)** Runs web + api but skips the installation wizard via `INSTALL_MODE=bypass`. Use this to test core UI directly.
+- `pnpm dev:web` / `pnpm dev:api` — Run frontend or backend individually.
+- `pnpm storybook` — Runs Storybook for `@fieldstack/controls` on **port 6007**.
+
+### Testing & Verification
+- `pnpm test` — Runs all tests recursively using Vitest.
+- `pnpm --filter <package> test` — Run tests for a specific workspace package (e.g., `api`, `core`).
+- `pnpm exec vitest run <path/to/test.ts>` — Run a single test file.
+- `pnpm lint` — Run ESLint across all workspace packages.
+- `pnpm typecheck` — Run TypeScript compiler checks.
+- `pnpm build` — Builds web, builds api, then copies web build to `apps/api/public` via `scripts/copy-frontend.js`.
+
+## Architecture Quirks
+
+### Frontend (`apps/web`)
+- **Hash Routing**: Uses Hash-based routing (`#login`, `#home`, `#admin`) managed by a custom state machine in `apps/web/src/main.tsx` (`effectiveRoute`).
+- **Auth State**: Authentication and session state are persisted in `sessionStorage` using the `fs_` prefix (e.g., `fs_auth`, `fs_admin`).
+- **Dev Mocks**: When testing auth UI locally, use `otp1234` for the OTP flow and `temp1234` for the force-password-change flow.
+
+### Backend (`apps/api`)
+- **Dynamic Module Loading**: Backend modules are dynamically scanned and loaded via `apps/api/src/loader/index.ts`.
+- **Module Requirements**: A backend module will only be loaded if it has a valid `module.json` manifest with `"enabled": true`.
+
+### Shared & UI Packages
+- **`packages/controls`**: All P0/P0.5 components are fully implemented (`ready: true`). Styled with `fs-` prefixed CSS classes and design tokens. Use `@fieldstack/controls` in `apps/web` — do not write inline component styles in views.
+- **Inter-module Communication**: Direct module-to-module imports are strictly forbidden. All cross-module communication must use the Event Bus.
+
+## Strict Code Rules
+
+- **TypeScript Strictness**: **NEVER** use `any`, `@ts-ignore`, or `@ts-expect-error`. If types are wrong, fix the types.
+- **Imports**: 
+  1. External libraries (`react`, `express`)
+  2. Internal workspace packages (`@fieldstack/core`, `@fieldstack/controls`)
+  3. Relative imports (`./`, `../`)
+  - Always use `import type` when importing types/interfaces.
+- **Naming Conventions**:
+  - Components / Types / Interfaces: `PascalCase`
+  - Hooks: `useCamelCase`
+  - Constants: `UPPER_SNAKE_CASE`
+  - Files / API Routes: `kebab-case`
+- **Validation**: Use Zod for schema and input validation.
+- **Error Handling**: Never leave empty `catch` blocks. Frontend should present user-friendly errors; backend should throw explicit HTTP statuses. Never log sensitive tokens.
diff --git a/apps/api/package.json b/apps/api/package.json
@@ -9,7 +9,8 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
   },
   "devDependencies": {
     "tsx": "^4.21.0",
diff --git a/apps/web/package.json b/apps/web/package.json
@@ -8,7 +8,8 @@
     "build": "tsc && vite build",
     "preview": "vite preview",
     "test": "vitest run --passWithNoTests",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx"
   },
   "devDependencies": {
     "@types/react": "^19.2.14",
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
@@ -1,4 +1,4 @@
-import { FormEvent, useEffect, useMemo, useState } from "react";
+import { type FormEvent, useEffect, useMemo, useState } from "react";
 import { createRoot } from "react-dom/client";
 
 import "./styles/global.css";
diff --git a/apps/web/src/views/HomeView.tsx b/apps/web/src/views/HomeView.tsx
@@ -125,7 +125,7 @@ export function HomeView({ onOpenSettings }: HomeViewProps) {
               icon="⬡"
               title="No modules installed yet"
               description="첫 모듈을 설치하면 메인 허브에 즉시 표시됩니다."
-              action={{ label: "Browse Marketplace", onClick: () => {} }}
+              action={{ label: "Browse Marketplace", onClick: () => { window.location.hash = '#marketplace'; } }}
             />
           )}
         </section>
diff --git a/package.json b/package.json
@@ -4,7 +4,11 @@
   "version": "0.0.0",
   "devDependencies": {
     "@types/node": "^22.18.2",
+    "@typescript-eslint/eslint-plugin": "^8.35.1",
+    "@typescript-eslint/parser": "^8.35.1",
     "@vitest/coverage-v8": "^2.1.9",
+    "eslint": "^8.57.1",
+    "eslint-plugin-react-hooks": "^5.2.0",
     "typescript": "^5.9.2",
     "vitest": "^2.1.9"
   },
diff --git a/packages/controls/package.json b/packages/controls/package.json
@@ -16,6 +16,7 @@
     "build": "tsc",
     "test": "vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
     "storybook": "storybook dev -p 6006",
     "storybook:build": "storybook build"
   },
diff --git a/packages/controls/src/foundation.ts b/packages/controls/src/foundation.ts
@@ -1,6 +1,4 @@
-export interface ThemeColorScale {
-  [key: string]: string;
-}
+export type ThemeColorScale = Record<string, string>;
 
 export interface UiThemeTokens {
   primary: ThemeColorScale;
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -14,7 +14,8 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
   },
   "devDependencies": {
     "vitest": "^2.1.9"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { FormEvent, useEffect, useMemo, useState } from "react";`
	`1`	`+import { type FormEvent, useEffect, useMemo, useState } from "react";`
`2`	`2`	`import { createRoot } from "react-dom/client";`
`3`	`3`
`4`	`4`	`import "./styles/global.css";`