freelang-editor 11.7.4

package/docs/LANGUAGE_IMPROVEMENT_REQUESTS.md

@@ -0,0 +1,187 @@
+# FreeLang v11 언어 개선 요청 (LIR)
+
+**작성일:** 2026-05-07  
+**근거:** akl-* 서비스 실사용 중 발견한 언어 표준 공백  
+**대상 버전:** v11.5.1 → v11.6  
+**우선순위:** P1(긴급) > P2(중간) > P3(장기)
+
+---
+
+## LIR-001 — str-slice 시맨틱 명문화 [P1]
+
+### 문제
+
+`str-slice`의 2, 3번째 인자가 `(start, end)` 인지 `(start, length)` 인지 STDLIB_REFERENCE에 명시 없음.
+
+**발견 코드 (akl-iam/app/server.fl)**:
+```lisp
+(str-slice (auth-sha256 ...) 0 16)      ;; end=16? length=16?
+(str-slice $auth 7 (length $auth))      ;; end 방식으로 추정
+```
+
+**혼동 위험:**
+- `(str-slice "hello" 1 3)` → `"el"` (end 방식) 또는 `"ell"` (length 방식)?
+
+### 요청
+
+1. STDLIB_REFERENCE에 `str-slice` 시맨틱 명확화:
+   ```
+   (str-slice str start end)  ;; str[start..end] (end 미포함)
+   ```
+2. length 방식이 필요한 경우를 위해 `str-substr` 별칭 추가:
+   ```
+   (str-substr str start length)  ;; str[start..start+length]
+   ```
+
+---
+
+## LIR-002 — map 키 자동 정규화 [P1]
+
+### 문제
+
+FreeLang에서 키워드(`:key`)와 문자열(`"key"`)이 **다른 키**로 처리됨. 이로 인해 생성 시 키워드 키를 쓰고 접근 시 문자열 키를 쓰면 항상 `nil` 반환.
+
+**발견 코드 (akl-aws/app/server.fl — 수정 전)**:
+```lisp
+;; 생성: 키워드 키
+{:access-key (get $r "access_key") :secret ...}
+
+;; 접근: 문자열 키 → nil 반환!
+(get $raw "access-key")
+```
+
+**실제 영향:** IAM exchange 로직이 nil cfg 반환 → Lambda 호출 전체 실패.
+
+### 요청
+
+**옵션 A (권장):** `get` 함수가 키워드/문자열 양방향 접근 허용:
+```lisp
+(get {:access-key "val"} "access-key")   ;; → "val" (현재 nil)
+(get {"access-key" "val"} :access-key)   ;; → "val" (현재 nil)
+```
+
+**옵션 B:** map 리터럴 생성 시 키워드를 문자열로 자동 정규화:
+```lisp
+{:key "val"}  ≡  {"key" "val"}  ;; 내부적으로 동일 처리
+```
+
+**옵션 C (최소):** 정책 문서화만 — "키워드와 문자열은 다름, 일관성 필수" + MISTAKES-100.md 추가.
+
+---
+
+## LIR-003 — auth-sha256 / auth-hmac alias 보장 [P2]
+
+### 문제
+
+`auth_sha256`, `auth_hmac`가 실제 동작은 하지만:
+1. `_aliases.json`에 snake/kebab 양방향 alias 미등록
+2. STDLIB_REFERENCE의 인증 섹션에 반환 타입 미명시
+3. `auth-hmac`의 key 인자가 raw string인지 hex string인지 불명확
+
+**발견 코드 (akl-aws/lib/sigv4.fl — SigV4 구현)**:
+```lisp
+;; make-signing-key: HMAC 출력을 다음 HMAC의 key로 재사용
+(let [[$k1 (auth-hmac $date (str "AWS4" $secret))]
+      [$k2 (auth-hmac $region $k1)]  ;; k1이 key로 재사용됨
+      ...])
+```
+→ `auth-hmac`가 hex string 반환 시 key로 재사용하면 SigV4 서명 오류.
+
+### 요청
+
+1. `_aliases.json`에 `auth_sha256` ↔ `auth-sha256`, `auth_hmac` ↔ `auth-hmac` 양방향 등록
+2. STDLIB_REFERENCE에 반환 타입 명시:
+   ```
+   auth-sha256 str → hex-string (소문자 hex 64자)
+   auth-hmac   data key → raw-bytes | hex-string  ← 명확화 필요
+   ```
+3. SigV4 구현에서 HMAC key 재사용 패턴 허용 여부 문서화
+
+---
+
+## LIR-004 — http-get-bearer stdlib 표준화 [P2]
+
+### 문제
+
+Bearer 토큰 인증 HTTP 요청이 모든 서비스에서 반복 구현됨:
+
+```lisp
+;; akl-account, akl-bigwash, akl-iam — 모두 동일한 패턴 직접 구현
+(http_request "GET" USERINFO_URL
+  {"Authorization" (str "Bearer " $token)} "")
+```
+
+`akl-lib/auth.fl`에서 래핑하고 있으나 이를 stdlib 표준 함수로 제공하면 중복 제거 가능.
+
+### 요청
+
+다음 함수를 `stdlib-http.ts`에 추가:
+
+```typescript
+// http-get-bearer url token → {:status 200 :body "..."}
+"http-get-bearer": (url: string, token: string): any => {
+  return http_request("GET", url, { Authorization: `Bearer ${token}` }, "");
+}
+
+// http-post-bearer url body token → {:status 200 :body "..."}
+"http-post-bearer": (url: string, body: string, token: string): any => {
+  return http_request("POST", url,
+    { "Authorization": `Bearer ${token}`, "Content-Type": "application/json" },
+    body);
+}
+```
+
+**사용 예시:**
+```lisp
+;; Before (각 서비스에서 직접 구현)
+(http_request "GET" USERINFO_URL {"Authorization" (str "Bearer " $token)} "")
+
+;; After
+(http-get-bearer USERINFO_URL $token)
+```
+
+---
+
+## LIR-005 — now_ms deprecated 경고 오류 [P3]
+
+### 문제
+
+`_aliases.json`에서 `now-ms` → `now_ms` (kebab이 deprecated, snake가 canonical)로 등록됨.
+그러나 런타임 v11.5.1에서는 반대로 `now_ms`가 deprecated 경고를 내보냄.
+
+```
+⚠️  [FreeLang v11.5.1] now_ms은 deprecated입니다. now-ms을 사용하세요.
+```
+
+→ `_aliases.json`과 실제 런타임 경고가 **반대 방향**으로 불일치.
+
+### 요청
+
+1. `_aliases.json`과 런타임 deprecation 경고를 일치시킴
+2. 공식 canonical 형태를 하나로 결정하고 CHANGELOG에 명시:
+   - **안 A:** `now_ms` canonical, `now-ms` alias (현재 _aliases.json 기준)
+   - **안 B:** `now-ms` canonical, `now_ms` deprecated (현재 런타임 기준)
+
+---
+
+## 요약 테이블
+
+| ID | 제목 | 우선순위 | 영향 서비스 | 예상 작업 |
+|----|------|----------|-------------|-----------|
+| LIR-001 | str-slice 시맨틱 명문화 | P1 | akl-iam, akl-aws, akl-account | 문서 1시간 |
+| LIR-002 | map 키 자동 정규화 | P1 | 전체 | 인터프리터 2-4시간 |
+| LIR-003 | auth-hmac alias 보장 | P2 | akl-iam, akl-aws | 문서+코드 2시간 |
+| LIR-004 | http-get-bearer 표준화 | P2 | 전체 | stdlib 1시간 |
+| LIR-005 | now_ms deprecated 불일치 | P3 | 전체 | 정책 결정 30분 |
+
+---
+
+## 참고: 이미 해결된 문제
+
+| 항목 | 해결 방법 | 날짜 |
+|------|-----------|------|
+| `[FUNC]` deprecated | akl-api 전체 `defn` 전환 | 2026-05-07 |
+| `now-ms` 혼용 | 5개 서비스 `now_ms` 통일 | 2026-05-07 |
+| `http_post` 헤더 미지원 | `http_request` 4-arg 전환 | 2026-05-07 |
+| map 키 불일치 버그 | akl-aws 문자열 키 통일 | 2026-05-07 |
+| snake_case → kebab-case | akl-api 전면 전환 | 2026-05-07 |

package/docs/LEARNING.md

@@ -0,0 +1,257 @@
+# FreeLang v11 — 학습 자료 (정상 동작)
+
+> 다른 언어와 다른 동작이지만 **FreeLang에서 정상**. 25개.
+> 실수가 아닌 *학습 사항*. JS/Python 출신이 헷갈리는 패턴.
+
+관련 문서:
+- `MISTAKES.md` — 진짜 실수
+- `LANGUAGE-FAULTS.md` — 언어 결함 (다음 메이저에서 수정)
+
+---
+
+## 📚 Lisp/함수형 표준 동작
+
+### #22 — v11 let 정상 문법
+
+```lisp
+;; #22 — v11 let 정상 문법
+(let [[$x 1] [$y 2]] (+ $x $y))    ;; ✅
+```
+
+### #24 — let body 마지막 식 반환
+
+```lisp
+;; #24 — let body는 마지막 식이 반환값
+(let [[$x 1]]
+  (println "debug")
+  (+ $x 1))                        ;; ✅ — (+ $x 1) 반환
+```
+
+### #25 — let 안에서 이전 바인딩 참조
+
+```lisp
+;; #25 — let 안에서 이전 바인딩 참조
+(let [[$x 1] [$y (+ $x 1)]] $y)   ;; ✅ — 순서대로 평가됨
+```
+
+### #27 — v11 defn 표준
+
+```lisp
+;; #27 — v11 defn 표준
+(defn add [$a $b] (+ $a $b))       ;; ✅
+```
+
+### #30 — 재귀: 함수명 직접 호출
+
+```lisp
+;; #30 — 재귀: 함수명으로 직접 호출
+(defn fact [$n]
+  (if (<= $n 1) 1 (* $n (fact (- $n 1)))))  ;; ✅
+```
+
+### #58 — (= x true) — 권장 안 함
+
+```lisp
+;; #58 — 불린 값
+(= x true) (= x false)              ;; ✅ 일반적으로 OK
+(not x)                              ;; ✅ nil/false 이외 모두 truthy
+```
+
+### #59 — 0/"" truthy (Lisp 표준)
+
+```lisp
+;; #59 — 0과 빈 문자열은 truthy (Lisp 표준)
+(if 0 "yes" "no")   ;; → "yes" (JS와 다름!)
+(if "" "yes" "no")  ;; → "yes"
+(if nil "yes" "no") ;; → "no"
+(if false "yes" "no") ;; → "no"
+```
+
+### #60 — 0-based 인덱스
+
+```lisp
+;; #60 — 배열 인덱스: 0-based
+(get arr 1)   ;; 두 번째 요소 (첫 번째 아님)
+(get arr 0)   ;; ✅ 첫 번째 요소
+```
+
+### #61 — if 단일 식만
+
+```lisp
+;; #61 — if는 단일 식만
+(if cond
+  (do-a)
+  (do-b))      ;; ❌ — else 없이 두 식 나열
+(if cond (do-a) (do-b))  ;; ✅
+```
+
+### #62 — 다중 분기 cond 권장
+
+```lisp
+;; #62 — 다중 분기: cond 사용
+(if (= x 1) "하나"
+  (if (= x 2) "둘" "기타"))        ;; △ 중첩 if (가독성 낮음)
+(cond
+  [(= x 1) "하나"]
+  [(= x 2) "둘"]
+  [true "기타"])                    ;; ✅
+```
+
+### #64 — and/or 마지막 truthy 반환
+
+```lisp
+;; #64 — and/or 반환값
+(and true "hello")  ;; → "hello" (마지막 truthy 값 반환)
+(or  nil  "default") ;; → "default"
+(or  nil  0)         ;; → 0 (0은 truthy!)
+```
+
+### #65 — if + do 블록
+
+```lisp
+;; #65 — 중첩 조건에서 do 블록
+(if cond
+  (stmt-a)
+  (stmt-b)
+  (stmt-c))                         ;; ❌ — if는 then/else 2개만
+(if cond
+  (do (stmt-a) (stmt-b))
+  (stmt-c))                         ;; ✅
+```
+
+### #73 — file_mkdir 재귀 생성
+
+```lisp
+;; #73 — file_mkdir: 중간 디렉토리 자동 생성
+(file_mkdir "a/b/c")              ;; ✅ — recursive 생성
+```
+
+### #76 — str 임의 타입 변환
+
+```lisp
+;; #76 — str은 임의 타입 이어붙임
+(str "hello" 42 true)             ;; ✅ → "hello42true"
+```
+
+### #83 — append 불변
+
+```lisp
+;; #83 — append는 불변 (새 배열 반환)
+(append arr x)                    ;; ✅ — 원본 불변, 새 배열 반환
+(do (append arr x) arr)           ;; ❌ — 결과를 버림
+(define arr2 (append arr x))      ;; ✅
+```
+
+### #85 — slice end 미포함
+
+```lisp
+;; #85 — slice: start, end (end 미포함)
+(slice arr 0 3)                   ;; → 인덱스 0,1,2 (3 미포함)
+```
+
+### #86 — flatten 동작
+
+```lisp
+;; #86 — flatten: 중첩 배열 평탄화
+(flatten [[1 2] [3 4]])           ;; → [1 2 3 4] ✅
+```
+
+### #87 — zip 동작
+
+```lisp
+;; #87 — zip: 두 배열 짝 맞추기
+(zip [1 2 3] ["a" "b" "c"])       ;; → [[1 "a"] [2 "b"] [3 "c"]]
+```
+
+### #88 — range end 미포함
+
+```lisp
+;; #88 — range: 끝 미포함
+(range 0 5)                       ;; → [0 1 2 3 4] (5 미포함) ✅
+```
+
+### #92 — workflow on_error 동작
+
+```lisp
+;; #92 — workflow 에러: on_error 반환값이 context에 반영
+(workflow_step "s" fn {:on_error (fn [$e] {:fallback true})})
+;; fallback true가 context에 병합됨
+```
+
+### #93 — load 경로
+
+```lisp
+;; #93 — load 경로: 실행 위치 기준
+(load "src/express.fl")           ;; bootstrap.js 위치 기준 ✅
+```
+
+### #95 — do 마지막 식 반환
+
+```lisp
+;; #95 — do 블록의 반환값
+(do (+ 1 2) (+ 3 4))             ;; → 7 (마지막 식)
+```
+
+### #96 — 심볼 vs 문자열
+
+```lisp
+;; #96 — 심볼 vs 문자열
+(define name "kim")
+(println name)                    ;; → "kim" ✅
+(println "name")                  ;; → "name" (변수 접근 아님)
+```
+
+### #98 — 재귀 깊이 제한
+
+```lisp
+;; #98 — 재귀 깊이: 스택 오버플로우 주의
+;; 큰 데이터는 reduce/loop 사용, 재귀 깊이 100 이하 권장
+```
+
+### #100 — (or nil 0) → 0 (Lisp 표준)
+
+```lisp
+;; #100 — (or nil 0)은 0 반환 (0이 falsy 아님)
+(or nil 0)    ;; → 0  (nil만 falsy)
+(or nil false) ;; → false
+(or nil nil)  ;; → nil
+;; JS와 다름: JS에서 (0 || "default") → "default"
+;; FL에서 (or 0 "default") → 0
+```
+
+---
+
+## 📝 문서 오류 (3개)
+
+MISTAKES-100에서 *틀린 코드*라고 표시했지만 **실제로는 작동**하는 경우.
+문서가 outdated. 정정 예정.
+
+### #36 — json_keys ALIAS, 실제로 작동도 함
+
+```lisp
+;; #36 — 맵 키 목록
+(json_keys m) / (object_keys m)     ;; ❌
+(keys m)                             ;; ✅
+```
+
+**Fix**: 문서 정정
+
+### #70 — KimDB URL 형식
+
+```lisp
+;; #70 — KimDB URL 형식
+(http_get "http://localhost:40000/api/v1/collections/col/docs")  ;; ❌
+(http_get "http://localhost:40000/api/c/col")                     ;; ✅
+```
+
+**Fix**: 문서 명시
+
+### #77 — length는 string에도 작동 (문서 거짓)
+
+```lisp
+;; #77 — str-length vs length
+(length "hello")                  ;; ❌ — 배열 전용
+(str-length "hello")              ;; ✅ → 5
+```
+
+**Fix**: 문서 정정

package/docs/MISTAKES-100.md

@@ -0,0 +1,52 @@
+# FreeLang v11 — "실수 100선" 인덱스 (재분류)
+
+> 이 문서는 v11.4.2까지 100개 실수를 한 곳에 모아 관리하던 곳이었다.
+> 분석 결과 **80%는 사용자 실수가 아니라 언어 결함/학습 자료**였다.
+> 정확성을 위해 3개 문서로 분리.
+
+## 분류 결과 (재계산)
+
+| 본질 | 개수 | 문서 | Phase |
+|------|-----|-----|-------|
+| 🔧 언어 디자인 결함 | **44** | [LANGUAGE-FAULTS.md](LANGUAGE-FAULTS.md) | **X (v11.5.1)** |
+| 📚 정상 동작 (학습) | 25 | [LEARNING.md](LEARNING.md) | — |
+| 💡 학습 부족 (안내) | 20 | [MISTAKES.md](MISTAKES.md) | G+ (✅ ALIAS 완료) |
+| 🚧 언어 미구현 | 5  | [MISTAKES.md](MISTAKES.md) | Y |
+| 📝 문서 오류 | 3  | [LEARNING.md](LEARNING.md) | Z |
+| 💀 진짜 부주의 | 3  | [MISTAKES.md](MISTAKES.md) | wrapper hint |
+| **합계** | **100** | — | — |
+
+## 어디서 무엇을 봐야 하나
+
+- **AI/사용자 실수** (28개) → `MISTAKES.md`
+  - 다른 언어 습관 → ALIAS 자동 처리
+  - 미구현 → Phase Y 대기
+  - 부주의 → wrapper hint
+
+- **Lisp 학습 자료** (28개) → `LEARNING.md`
+  - 정상 동작 (실수 아님)
+  - 문서 오류 정정
+
+- **언어 결함** (44개) → `LANGUAGE-FAULTS.md`
+  - 인자 순서/작명/시그니처 비일관
+  - **v11.5.x Phase X에서 통일 + 마이그레이션 도구 제공**
+
+## 자동 카운트
+
+```bash
+node scripts/verify-mistakes-coverage.js   # 처리율
+node scripts/gen-mistakes-split.js         # 3개 문서 재생성
+```
+
+`MISTAKES-COVERAGE.json` (자동 갱신):
+- 매핑된 항목: 33/100 (Phase G+ ALIAS hint)
+- 진짜 자동 (코드 그대로): 2 (#23 let, #26 [FUNC])
+- 옵션 헬퍼 호출: 8 (smart-* / http-*-json)
+
+## 분류 변경의 의미
+
+기존 명명: *"실수 100선"* — 사용자 책임 프레임
+재분류 후: 사용자 실수 28%, 학습 자료 28%, **언어 결함 44%**
+
+→ Phase H에서 ALIAS 더 추가하는 건 응급처치.
+→ Phase X (v11.5.1) 언어 통일이 진짜 fix.

package/docs/MISTAKES.md

@@ -0,0 +1,131 @@
+# FreeLang v11 — 진짜 실수 모음
+
+> 사용자/AI가 *진짜로 잘못 쓰는* 항목. 28개.
+> v11.4.2 기준 28개 중 20개 ALIAS hint로 자동 처리됨.
+
+관련 문서:
+- `LEARNING.md` — Lisp/FreeLang 학습 (실수 아님, 25개)
+- `LANGUAGE-FAULTS.md` — 언어 디자인 결함 (44개, v11.5.x fix 대상)
+- `MISTAKES-COVERAGE.json` — 자동 처리 카운트
+
+---
+
+## 💀 진짜 부주의 (3개)
+
+코드 작성자가 명백히 실수한 경우.
+
+### #51 — 경로 :id 파라미터 누락
+
+```lisp
+;; #51 — 경로 파라미터 선언
+(server_get "/users/id" "handler")        ;; ❌ — :id 없음
+(server_get "/users/:id" "handler")       ;; ✅
+```
+
+### #75 — file_append 개행 누락
+
+```lisp
+;; #75 — file_append: 개행 수동 추가
+(file_append "log.txt" "한 줄")   ;; ❌ — 개행 없음
+(file_append "log.txt" "한 줄\n") ;; ✅
+```
+
+### #99 — server_start 블로킹
+
+```lisp
+;; #99 — server_start는 블로킹
+;; server_start 이후 코드 실행 안됨 — 항상 마지막에 호출
+(server_get "/path" "handler")
+(println "이 줄은 실행됨")
+(server_start 3000)
+(println "이 줄은 실행 안됨")    ;; ❌
+```
+
+---
+
+## 💡 다른 언어 습관 (20개)
+
+AI/사용자가 다른 언어 습관으로 잘못된 함수명을 쓰는 경우. **모두 ALIAS hint 자동 처리됨**.
+
+| # | 잘못된 호출 | 올바른 호출 | 출처 |
+|---|------------|------------|------|
+| #32 | env / get_env (다른 언어 습관) | ALIAS 처리 | ALIAS 처리됨 |
+| #33 | server_listen / server_run | ALIAS 처리 | ALIAS 처리됨 |
+| #34 | str-to-int / parseInt | ALIAS 처리 | ALIAS 처리됨 |
+| #35 | console.log / log | ALIAS 처리 | ALIAS 처리됨 |
+| #37 | now-ms / Date.now | ALIAS 처리 | ALIAS 처리됨 |
+| #38 | mariadb_all / db_query | ALIAS 처리 | ALIAS 처리됨 |
+| #40 | obj_omit / omit | ALIAS 처리 | ALIAS 처리됨 |
+| #41 | obj_pick | ALIAS 처리 | ALIAS 처리됨 |
+| #42 | count / size | ALIAS 처리 | ALIAS 처리됨 |
+| #43 | split / str_split | ALIAS 처리 | ALIAS 처리됨 |
+| #44 | JSON.parse / parse_json | ALIAS 처리 | ALIAS 처리됨 |
+| #45 | JSON.stringify | ALIAS 처리 | ALIAS 처리됨 |
+| #55 | (= x null) / null? — nil?로 통일 | ALIAS 처리 | ALIAS 처리됨 |
+| #57 | num-to-str — (str) | ALIAS 처리 | ALIAS 처리됨 |
+| #78 | trim — str-trim | ALIAS 처리 | ALIAS 처리됨 |
+| #79 | starts-with? — str-starts-with | ALIAS 처리 | ALIAS 처리됨 |
+| #80 | includes — str-contains | ALIAS 처리 | ALIAS 처리됨 |
+| #81 | to-upper — str-upper | ALIAS 처리 | ALIAS 처리됨 |
+| #82 | toString — str | ALIAS 처리 | ALIAS 처리됨 |
+| #90 | throw — error | ALIAS 처리 | ALIAS 처리됨 |
+
+→ `freelang-smart`로 실행하면 자동 hint.
+
+---
+
+## 🚧 언어 미구현 (5개)
+
+기능 자체가 미구현이라 *대안*을 알아야 하는 경우. Phase Y 대상.
+
+### #14 — http_get_key 미구현
+
+```lisp
+;; #14 — http_get_key / http_post_key (API Key 인증)
+(http_get url)                                  ;; ❌ — API Key 서버에 401
+(http_get_key url api-key)                      ;; ✅
+```
+
+**Fix**: Phase Y: API Key 인증 구현
+
+### #69 — mariadb_one nil 자동 처리 미지원
+
+```lisp
+;; #69 — mariadb_one: 결과 없으면 nil
+(get (mariadb_one db sql []) "id")  ;; ❌ — nil 처리 없음
+(let [[$row (mariadb_one db sql [])]]
+  (if $row (get $row "id") nil))     ;; ✅
+```
+
+**Fix**: Phase Y: 안전 접근자
+
+### #71 — file_read 없는 파일 → 에러
+
+```lisp
+;; #71 — 파일 읽기: 없는 파일이면 에러
+(file_read "path")                ;; 없으면 에러 발생
+(if (file_exists "path") (file_read "path") "")  ;; ✅
+```
+
+**Fix**: Phase Y: file-read-or 추가
+
+### #89 — try-catch 구문 미작동
+
+```lisp
+;; #89 — try-catch 문법
+(try
+  (risky-fn)
+  (catch $e (println (str "에러: " $e))))  ;; ✅
+```
+
+**Fix**: Phase Y: try-catch 완전 구현
+
+### #91 — 에러 객체 구조 접근
+
+```lisp
+;; #91 — error 반환값 접근
+(let [[$e (try (error "fail") (catch $e $e))]]
+  (get $e "message"))             ;; ✅
+```
+
+**Fix**: Phase Y: error 메타