freelang-editor 11.7.4

package/docs/QUICKSTART.md

@@ -0,0 +1,160 @@
+# 빠른 시작 (5분)
+
+> FreeLang v11을 5분 안에 시작하는 가이드
+
+---
+
+## Step 1️⃣: 설치 (1분)
+
+```bash
+git clone https://gogs.dclub.kr/kim/freelang-v11.git
+cd freelang-v11
+npm install
+npm run build
+```
+
+**확인**: `dist/` 디렉토리와 `bootstrap.js`가 생성되어야 합니다.
+
+---
+
+## Step 2️⃣: 첫 번째 FL 파일 (1분)
+
+```bash
+cat > hello.fl << 'EOF'
+(println "✨ FreeLang v11에 오신 것을 환영합니다!")
+(println "한 언어로 풀스택 개발을 시작하세요.")
+EOF
+```
+
+실행:
+```bash
+node bootstrap.js run hello.fl
+```
+
+**예상 출력**:
+```
+✨ FreeLang v11에 오신 것을 환영합니다!
+한 언어로 풀스택 개발을 시작하세요.
+```
+
+---
+
+## Step 3️⃣: 웹 서버 실행 (2분)
+
+```bash
+cat > app.fl << 'EOF'
+;; 간단한 HTTP 서버
+(route-get "/"
+  (fn [req]
+    (http-response
+      :status 200
+      :body "<h1>🚀 FreeLang v11!</h1><p>서버가 정상 실행 중입니다.</p>"
+      :headers {:content-type "text/html"})))
+
+(println "✅ 서버 시작: http://localhost:3000")
+EOF
+```
+
+실행:
+```bash
+node bootstrap.js serve --port 3000
+```
+
+**브라우저에서 접속**:
+```
+http://localhost:3000
+```
+
+---
+
+## Step 4️⃣: 배포 파일 자동 생성 (1분)
+
+FreeLang은 인프라 블록을 선언형으로 정의하면 자동으로 배포 파일을 생성합니다.
+
+```bash
+cat > deploy.fl << 'EOF'
+;; Dockerfile 자동 생성
+(dockerfile
+  :from "node:20-slim"
+  :workdir "/app"
+  :copy "*.fl" "."
+  :copy "package.json" "."
+  :run "npm install"
+  :cmd "node bootstrap.js serve --port 3000")
+
+;; Kubernetes 배포 매니페스트 자동 생성
+(deployment
+  :name "freelang-app"
+  :image "freelang-app:latest"
+  :replicas 3
+  :port 3000)
+
+(println "✅ Dockerfile, deployment.yaml 생성됨")
+EOF
+```
+
+실행:
+```bash
+node bootstrap.js run deploy.fl
+```
+
+**생성 파일**:
+- `Dockerfile` — 컨테이너 이미지 빌드용
+- `deployment.yaml` — Kubernetes 배포용
+
+---
+
+## 🎯 다음 단계
+
+- **배포 가이드**: [DEPLOYMENT.md](./DEPLOYMENT.md) — Docker, Kubernetes, AWS/GCP/Azure
+- **스타일 시스템**: [STYLE_GUIDE.md](./STYLE_GUIDE.md) — STYLE + THEME 블록 사용법
+- **API 레퍼런스**: [API.md](./API.md) — 모든 stdlib 함수 목록
+- **예제**: [examples/](../self/examples/) — 더 많은 코드 샘플
+
+---
+
+## ✅ 요약
+
+| 단계 | 시간 | 내용 |
+|------|------|------|
+| 1 | 1분 | npm install + npm run build |
+| 2 | 1분 | hello.fl 작성 및 실행 |
+| 3 | 2분 | 웹 서버 실행 |
+| 4 | 1분 | 배포 파일 자동 생성 |
+
+**총 5분 안에 FreeLang v11의 모든 핵심 기능을 경험할 수 있습니다.**
+
+---
+
+## 🆘 문제 해결
+
+### `npm install` 실패
+```bash
+# Node.js v25+ 필요
+node --version
+
+# npm 캐시 초기화
+npm cache clean --force
+npm install
+```
+
+### `bootstrap.js` 찾을 수 없음
+```bash
+# 빌드 확인
+npm run build
+ls -la bootstrap.js
+```
+
+### 포트 3000 이미 사용 중
+```bash
+# 다른 포트 사용
+node bootstrap.js serve --port 8000
+```
+
+---
+
+## 💡 더 알아보기
+
+- **CLI 명령어**: `node bootstrap.js --help`
+- **테스트 실행**: `npm test`
+- **성능 측정**: `npm run benchmark`

package/docs/README.md

@@ -0,0 +1,192 @@
+# FreeLang v9 공식 문서
+
+이 폴더는 GitHub Pages를 통해 자동으로 웹사이트로 빌드되는 FreeLang v9 공식 문서입니다.
+
+## 📚 문서 구조
+
+### [메인 페이지](./index.md) - 프로젝트 개요
+- FreeLang v9 소개
+- 핵심 기능 설명
+- 빠른 시작 가이드
+- 프로덕션 준비 상태
+
+### [가이드](./guide/) - 단계별 학습
+- **[기초](./guide/basics.md)** — S-expression 문법, 함수, 제어 흐름
+- **[AI 블록](./guide/ai-blocks.md)** — COT, TOT, REFLECT, HYPOTHESIS 등
+- **[프레임워크](./guide/frameworks.md)** — FLNext, v9-data, 마이크로서비스
+
+### [API 레퍼런스](./api/) - 기술 문서
+- **[stdlib](./api/stdlib.md)** — 30개 표준 모듈 설명
+
+### [예제](./examples/) - 실전 코드
+- **[TODO 앱](./examples/todo-app.md)** — 기본 CRUD 앱
+- 더 많은 예제 추가 예정
+
+### [설정 가이드](./SETUP.md) - 개발 환경
+- GitHub Pages 활성화 방법
+- 로컬 테스트 방법
+- 문서 추가 방법
+
+---
+
+## 🚀 빠른 시작
+
+### 읽기 순서 (권장)
+1. **[메인 페이지](./index.md)** - 프로젝트 이해
+2. **[기초](./guide/basics.md)** - 언어 학습
+3. **[AI 블록](./guide/ai-blocks.md)** - 고급 기능
+4. **[프레임워크](./guide/frameworks.md)** - 실무 개발
+5. **[예제](./examples/)** - 코드 작성
+
+### 빠른 설치
+```bash
+npm install -g freelang-v9
+v9 repl
+```
+
+---
+
+## 📝 문서 기여
+
+새로운 문서를 추가하려면:
+
+1. **Markdown 파일 생성**
+   ```
+   docs/guide/새-주제.md
+   docs/examples/새-예제.md
+   ```
+
+2. **마크다운 템플릿 사용**
+   ```markdown
+   # 제목
+   
+   ## 섹션
+   내용...
+   
+   ---
+   
+   ## 다음 단계
+   [다른 페이지](../api/stdlib.md)
+   ```
+
+3. **Git에 커밋**
+   ```bash
+   git add docs/
+   git commit -m "docs: 새 문서 추가"
+   git push github master
+   ```
+
+4. **자동 배포**
+   - GitHub Actions가 자동으로 빌드 및 배포
+   - 1-2분 내에 웹사이트 업데이트
+
+---
+
+## 🔧 로컬 개발
+
+### 요구사항
+- Ruby 2.7+
+- Bundler
+
+### 설정
+```bash
+cd docs
+bundle install
+```
+
+### 로컬 서버 실행
+```bash
+bundle exec jekyll serve
+```
+
+### 브라우저에서 확인
+```
+http://localhost:4000/freelang-v9
+```
+
+---
+
+## 📂 파일 구조
+
+```
+docs/
+├── index.md              # 메인 페이지
+├── _config.yml           # Jekyll 설정
+├── README.md             # 이 파일
+├── SETUP.md              # 설정 가이드
+├── guide/
+│   ├── basics.md         # 기초 문법
+│   ├── ai-blocks.md      # AI 블록
+│   └── frameworks.md     # 프레임워크
+├── api/
+│   └── stdlib.md         # 표준 라이브러리
+└── examples/
+    ├── index.md          # 예제 목록
+    └── todo-app.md       # TODO 앱
+```
+
+---
+
+## 🌐 GitHub Pages
+
+- **URL**: https://kimjindol2025.github.io/freelang-v9
+- **빌드 시스템**: Jekyll
+- **테마**: Minima
+- **자동 배포**: `.github/workflows/pages.yml`
+
+---
+
+## 📖 마크다운 팁
+
+### 제목
+```markdown
+# H1
+## H2
+### H3
+```
+
+### 코드
+```markdown
+\`\`\`lisp
+(print "Hello, FreeLang!")
+\`\`\`
+```
+
+### 링크
+```markdown
+[텍스트](../path/to/page.md)
+[외부 링크](https://example.com)
+```
+
+### 표
+```markdown
+| 항목 | 상태 |
+|------|------|
+| 항목1 | ✅ |
+| 항목2 | 🚀 |
+```
+
+---
+
+## ✅ 문서 작성 체크리스트
+
+- [ ] 제목과 소개 추가
+- [ ] 섹션 구분 (##, ###)
+- [ ] 코드 예제 포함 (lisp, bash)
+- [ ] 다음 단계 링크 추가
+- [ ] 메인 페이지에서 링크됨
+- [ ] 로컬에서 테스트됨
+
+---
+
+## 🎯 다음 목표
+
+- [ ] 데이터 분석 가이드 추가
+- [ ] 마이크로서비스 튜토리얼 추가
+- [ ] API 상세 문서 작성
+- [ ] 비디오 튜토리얼 추가
+- [ ] 커뮤니티 블로그 연동
+
+---
+
+[메인 페이지로 돌아가기](./index.md) | [GitHub 저장소](https://github.com/kimjindol2025/freelang-v9)

package/docs/RESERVED.md

@@ -0,0 +1,125 @@
+# FreeLang v11 예약 식별자 (Reserved Identifiers)
+
+**목적**: 사용자 정의 불가능한 특수폼/키워드 명시. defn/let에서 충돌 감지.
+
+---
+
+## 📋 예약 특수폼 (Special Forms)
+
+이 식별자들은 **사용자가 정의할 수 없습니다**.
+
+### 제어 흐름
+- `if` — 조건 분기
+- `cond` — 다중 조건
+- `do` / `begin` / `progn` — 순차 실행
+- `while` — 루프
+- `loop` — 루프 (recur 필요) ← **⚠️ 주의**: 이름만으로 충돌
+- `recur` — 루프 재귀
+
+### 함수 정의
+- `fn` — 익명 함수
+- `defn` / `defun` — 함수 정의
+- `lambda` — 람다
+
+### 로직
+- `and` / `or` — 논리 연산
+- `not` — 논리 부정
+
+### 변수 바인딩
+- `let` — 로컬 바인딩
+- `set!` — 변수 재할당
+- `define` — 전역 정의
+
+### 비동기/에러
+- `async` — 비동기 함수
+- `await` — 비동기 대기
+- `try` / `catch` / `finally` — 예외 처리
+- `throw` — 예외 발생
+
+### 메타
+- `quote` — 쿼트
+- `eval` — 평가
+- `macro` / `defmacro` — 매크로
+
+### 기타
+- `compose` — 함수 합성
+- `pipe` / `->` / `->>` / `|>` — 파이프라인
+
+---
+
+## ⚙️ 컴파일 타임 검증
+
+### defn 검증
+
+```fl
+(defn loop [n] ...)  ; ❌ 에러: loop는 예약 특수폼
+(defn fact [n] ...)  ; ✅ OK
+```
+
+**구현**: `cg-defn`에서 함수 이름 검증
+
+```fl
+[FUNC is-reserved? :params [$name]
+  :body (or (= $name "loop") (= $name "recur") ...)]
+
+[FUNC cg-defn :params [$args]
+  :body (let [[$name-n (get $args 0)]
+              [$name (extract-name $name-n)]]
+          (if (is-reserved? $name)
+            (throw (str "Error: '" $name "' is reserved"))
+            ...))]
+```
+
+### let 검증 (선택)
+
+```fl
+(let [[loop (fn ...)]] ...)  ; ⚠️ 경고 또는 에러
+```
+
+**현재**: let은 검증 안 함 (사용자 책임)
+
+---
+
+## 🔜 회피 방법
+
+**권장**: 다른 이름 사용
+
+```fl
+; ❌ 피할 것
+(defn loop [n] (if (= n 0) 0 (loop (- n 1))))
+
+; ✅ 권장
+(defn countdown [n] (if (= n 0) 0 (countdown (- n 1))))
+(defn my-loop [n] (if (= n 0) 0 (my-loop (- n 1))))
+```
+
+---
+
+## 📊 JavaScript 예약어 (추가)
+
+FreeLang은 JS로 컴파일되므로, 다음도 피하는 것이 좋습니다:
+
+- `class`, `const`, `let`, `var`, `function`, `return`
+- `if`, `else`, `switch`, `case`, `break`, `continue`
+- `for`, `while`, `do`, `try`, `catch`, `finally`
+- `new`, `delete`, `typeof`, `instanceof`, `in`, `of`
+- `this`, `super`, `null`, `true`, `false`, `undefined`
+
+**자동 회피**: codegen에서 자동으로 `_` 접미사 추가
+
+```
+class → class_
+const → const_
+```
+
+---
+
+## 🎯 설계 철학
+
+**언어 정의 단일성**: interpreter와 codegen이 같은 예약어 목록을 사용해야 함.
+
+**명확성 > 유연성**: 특수폼과 사용자 정의의 경계를 명확히 함.
+
+---
+
+**마지막 수정**: 2026-04-26 (Phase C, C3 해결)

package/docs/ROADMAP.md

@@ -0,0 +1,191 @@
+# FreeLang v11 로드맵
+
+> **언어 정의**: AI 에이전트 실행 엔진  
+> **설계 철학**: Deterministic + Self-Hosted + AI-First  
+> **업데이트**: 2026-05-08
+
+---
+
+## 완료된 것 ✅
+
+| 항목 | 완료일 |
+|------|--------|
+| L0: TypeScript bootstrap.js | 초기 |
+| L1: self/all.fl → stage1.js | 2026-04 |
+| L2: 17/17 의미 동등성 증명 | 2026-05-02 |
+| **L3: stage1 → stage2 자기 컴파일 (클로저 검증)** | **2026-05-03** |
+| AI-Native Phase 1~4 (fn-meta, effects, ^pure, property-based) | 2026-05-01 |
+| P0~P1: 에러처리, 병렬실행, 보상TX, Observability | 2026-04-29 |
+| MariaDB Pool + MongoDB Wire Protocol | 2026-04-30 |
+| REPL 디버거 강화 | 2026-04-30 |
+| npm 11.2.0 배포 | 2026-05-03 |
+| **P0: Content-Type case-insensitive 수정** | **2026-05-03** |
+| **P0: `freelang patch` 명령 추가** | **2026-05-03** |
+| **v11.6.0: LIR-002 assoc/dissoc 키 정규화** | **2026-05-08** |
+| **v11.6.0: env_get nil 반환 + env-or 헬퍼** | **2026-05-08** |
+| **v11.6.0: catch 타입 분기 — code→category 직접 매핑** | **2026-05-08** |
+
+---
+
+## 현재 진행 중 🔧
+
+### 테스트 93% → 100%
+
+현재: 831/832 (99.9%)  
+남은 실패: verify-self-host.sh tier2 PASS 82 → 86 기준
+
+---
+
+## 다음 작업 (우선순위 순)
+
+### ~~P0 — Content-Type 헤더 강제 버그 수정~~ ✅ 완료 (2026-05-03)
+
+**수정**: `bootstrap.js` `sendResponse` case-insensitive 헤더 탐색  
+**커밋**: 77c48955
+
+---
+
+### ~~P0 — `freelang patch` 명령 추가~~ ✅ 완료 (2026-05-03)
+
+**수정**: `bootstrap.js`에 `patch` 서브커맨드 구현  
+**커밋**: 77c48955  
+**사용법**:
+```bash
+freelang patch <file> --find "<text>" --replace "<text>"
+freelang patch <file> --insert-after "<anchor>" --content "<block>"
+```
+**완료 조건**: 특수문자(백틱, ${}, 한글, JSON) 포함 문자열 안전 처리
+
+---
+
+### P1 — 테스트 99.9% → 100%
+
+**남은 1개**: `verify-self-host.sh tier2` PASS 82 → 86  
+**원인**: fuzz invariant crash (file_read/write 선언 충돌 해결 중)
+
+---
+
+### P1 — `shell_env` nil 반환 수정
+
+**증상**: 미정의 환경변수가 `""` 반환 → `(or "" default)` 가 `""` 선택  
+**수정**: 미정의 시 `nil` 반환 + `(env-or key default)` 헬퍼 추가
+
+---
+
+### P1 — `mariadb_pool_query` 빈 결과 `[]` 반환
+
+**증상**: 빈 테이블 조회 시 `nil` 반환 → `(map fn nil)` 폭발  
+**수정**: 빈 결과 시 `nil` 대신 `[]` 반환
+
+---
+
+---
+
+## "언어가 편하려면" — 실사용 피드백 (2026-05-08)
+
+> Claude와 실제 개발하며 발견한 불편함. Python보다 FreeLang이 편해지려면 필요한 것들.
+
+### 현재 Python이 더 편한 이유 (솔직한 진단)
+
+| 항목 | Python | FreeLang 현재 | 목표 |
+|------|--------|---------------|------|
+| 실행 속도 | 즉시 | 1-2초 (bootstrap 로딩) | < 0.3초 |
+| 에러 위치 | 파일+줄+컨텍스트 | 줄번호만 | 파일+줄+3줄 컨텍스트 |
+| REPL | 즉시 실험 | 있지만 무거움 | 경량 즉시 REPL |
+| 파일 조작 | 내장 완전 | stdlib 있지만 인코딩 불안 | `file-replace`, `file-lines` 안정화 |
+| HTTP | async 기본 | spawnSync curl (블로킹) | Node fetch 기반 async |
+| 인코딩 | 자동 | 한글 주석 편집 도구 오작동 | UTF-8 완전 지원 |
+
+### Phase "편한 언어" — 구현 순서
+
+#### P1 — HTTP async (curl → fetch) 🔧 진행예정
+**문제**: `spawnSync("curl")` → 고부하에서 직렬 병목  
+**해결**: Node.js 내장 `fetch` API로 교체 (v18+ 기본 지원)  
+**파일**: `src/stdlib-http.ts:31` `curlGetStatusAndBody` 함수  
+**기대효과**: 동시 10 요청 기준 10배 처리량 향상
+
+#### P1 — 모듈 캐시 🔧 진행예정
+**문제**: import마다 재파싱 → 복잡한 앱에서 시작 수초 지연  
+**해결**: `moduleCache: Map<path, exports>` 추가  
+**파일**: `src/eval-module-system.ts:196`  
+**기대효과**: 10개 모듈 앱 기준 시작 시간 80% 단축
+
+#### P2 — 실행 속도 (bootstrap 로딩)
+**문제**: `node bootstrap.js` 로딩 1-2초  
+**해결**: L4 단일 바이너리 (Bun SEA) 또는 bootstrap 경량화  
+**기대효과**: `./freelang run` 즉시 실행
+
+#### P2 — 파일 조작 stdlib 안정화
+**문제**: `file_read`/`file_write` 인코딩 처리 불안정  
+**해결**: UTF-8 강제 + `file-lines`, `file-replace`, `file-append` 완성  
+**기대효과**: Python 없이 파일 편집 가능
+
+#### P3 — 타입 추론 강화
+**문제**: 사용자 정의 함수 반환형 = "any" → 런타임까지 에러 모름  
+**해결**: 함수 body에서 반환형 추론 (Hindley-Milner 경량 버전)  
+**기대효과**: 컴파일 타임 에러 30% → 60%
+
+---
+
+### P2 — Phase L4: Bun 단일 바이너리
+
+**목표**: `bun build --compile stage1.js --outfile freelang`  
+**완료 조건**: Node.js 없이 `./freelang run app.fl` 실행  
+**예상 작업량**: 1세션
+
+---
+
+### P2 — 에러 메시지에 파일명 + 컨텍스트
+
+**증상**: `"line 53 col 0"` — 어느 파일인지 모름. 디버깅 2배 소요.  
+**수정**: 에러 출력에 파일명 + 해당 줄 코드 3줄 컨텍스트 추가
+
+---
+
+### P1 — `freelang migrate` — DB 마이그레이션 관리
+
+**배경**: Supabase에서 배운 것 — 스키마 변경 추적 없으면 "이 컬럼 언제 추가했지?" 반복  
+**파일**: `bootstrap.js` CLI + `migrations/` 폴더 규칙  
+**명령**:
+```bash
+freelang migrate create "add_status_to_orders"   # 파일 생성
+freelang migrate up                               # 미적용 실행
+freelang migrate down                             # 마지막 롤백
+freelang migrate status                           # 적용 현황
+```
+**완료 조건**: MariaDB `_migrations` 테이블 + SQL 파일 기반 버전 관리
+
+---
+
+### P2 — `auto_rest` — DB 테이블 → REST API 자동 생성
+
+**배경**: Supabase PostgREST 패턴 — CRUD 핸들러 반복 제거  
+**사용법**:
+```fl
+(auto_rest "orders" {:auth :required :read :public})
+; → GET /orders, POST /orders, PATCH /orders/:id, DELETE /orders/:id 자동
+```
+**완료 조건**: akl-crm 기존 CRUD 핸들러 50% 이상 제거 가능
+
+---
+
+### P3 — WebSocket / Push API / Cron 정밀화
+
+| 기능 | 현황 | 목표 |
+|------|------|------|
+| WebSocket | community-ws 별도 구현 | stdlib 통합 |
+| Push API 서버 측 | 미구현 | Web Push protocol |
+| Cron | set_interval 60초 | "매주 월요일 9시" 수준 |
+
+---
+
+## 버전 히스토리
+
+| 버전 | 날짜 | 주요 변경 |
+|------|------|-----------|
+| 11.6.0 | 2026-05-08 | LIR-002 키정규화, env_get nil, catch 타입분기 |
+| 11.5.3 | 2026-05 | CSRF/XSS 보안 강화 |
+| 11.5.0 | 2026-05-04 | kebab alias 400개 자동 등록 |
+| 11.2.0 | 2026-05-03 | L3 자기 호스팅 완성, while codegen 수정 |
+| 11.1.0 | 2026-05 | L2 100% 완성, AI-Native Phase 1~4 |
+| 11.0.x | 2026-04 | L1 자가호스팅, P0~P1 완성, MongoDB |