한선씨 모듈 배포 체계 설계 — pkg.crowny.org 재정의 (P5)

개요

게이트웨이 한선씨화 P5. pkg.crowny.org를 npm(Verdaccio) 레지스트리에서 한선씨 모듈 배포 체계로 재정의하는 설계 + 프로토타입.

핵심 인식: 한선씨 모듈은 가져오기 파일기반(libs/, CROWNY_STD)이라 npm 레지스트리가 본질적으로 불필요하다. 현 pkg.crowny.org = Verdaccio(127.0.0.1:4873)는 레거시이고 인증이 차단된 상태(토큰 무효 · htpasswd 빈 파일 · @crowny 패키지 0개. 참조: 2026-06-09-pkg-crowny-publish-blocker.md).

관련 파일:

• 프로토타입: /Users/ef/crowny-gateway/한선게이트웨이/배포.한선 (hanseonc_high 컴파일 통과)
• 설계: 본 문서

---

① 한선씨 모듈 배포의 두 안

안 A — 파일기반 CROWNY_STD 동기화 (레지스트리 폐기) ★ 추천

한선씨 런타임은 가져오기 "X.한선" 시 다음 경로를 탐색한다:

1. 현재 디렉토리
2. libs/ (컴파일러 인접)
3. $CROWNY_STD (현재 /Users/ef/Downloads/CrownyTVM/std)

즉 모듈 "설치" = 파일을 CROWNY_STD(또는 libs/)에 두는 것이 전부다. npm install/registry 계층은 한선씨에게 잉여 레이어다.

배포 단위 = 디렉토리(모듈 세트) + 매니페스트(파일 목록 + SHA256 해시 + 바이트수).

배포 흐름:
  [생성] 배포.한선 매니페스트생성(디렉토리, 패키지명, 버전) → manifest.json
  [전송] crowny-hub 가 디렉토리 + manifest.json 을 peer(mac-studio/macbook-intel)로 복사
  [검증] peer 에서 배포.한선 매니페스트검증(디렉토리, manifest.json) → Ti/Om/Ta
  [설치] 검증 통과(Ti) 시 CROWNY_STD/libs 로 파일 반영

장점:

• 레지스트리 인프라(Verdaccio/htpasswd/토큰) 전부 불필요 → 현재 차단 문제 자체가 소멸
• 무결성은 SHA256 해시 매니페스트로 보장 (npm tarball sha와 동급, 단 한선씨 네이티브)
• crowny-hub(= GitHub 대체)와 자연 연동 — 이미 커밋/버전추적/인수인계 인프라 존재
• 4상균형3진 검증 결과(Ti/Om/Ta)로 게이트웨이 헬스 체계와 동일 의미론

단점:

• 버전 범위 해석(semver range ^1.2.0)·의존성 그래프 해소가 npm만큼 자동화되어 있지 않음 → 매니페스트에 requires 필드 추가로 보강 가능(후속)
• 외부(비-크라우니) 소비자는 npm 기대 → 안 B 이행기 병행 필요

안 B — 한선씨 패키지 레지스트리 (.toau/.한선 + 매니페스트 해시)

pkg.crowny.org를 한선씨 전용 레지스트리로 신규 구현: .한선 소스 + .toau 컴파일본 + 매니페스트(해시) 를 한 단위로 게시/조회. crowny-hub이 백엔드 스토리지·버전 인덱스 담당.

장점:

• 중앙 조회 가능(배포 목록, 배포 받기 <패키지>@<버전>), 버전 히스토리 보존
• .toau 동봉 시 peer가 재컴파일 없이 즉시 실행
• 외부 노출 API를 한선씨 네이티브로 설계 → npm 의존 완전 탈피

단점:

• 서버(레지스트리 데몬)를 새로 만들어야 함 — 한선씨 HTTP 서버로 구현 필요(웹서버v2.한선 기반)
• 안 A 대비 인프라 비용↑. 한선씨 import 가 파일기반인 한 "조회 서버"의 한계효용이 낮음

추천

안 A를 1차 채택, 안 B는 안 A의 매니페스트 포맷을 그대로 재사용하는 상위 호환으로 후속 구현.

이유: 한선씨의 import 가 파일기반인 이상 레지스트리 데몬은 잉여 레이어다. 먼저 매니페스트 표준(해시 무결성)을 확정하고 crowny-hub 동기화로 "배포"를 실현한다. 중앙 조회/버전 히스토리가 실제로 필요해지면, 같은 매니페스트 포맷을 노출하는 한선씨 HTTP 레지스트리(안 B)를 pkg.crowny.org 뒤에 붙인다 — 포맷이 동일하므로 클라이언트(배포.한선) 무수정 확장.

---

② 이행기 레거시 JS 패키지 게시 — 인증 복구 절차

@crowny/gateway 5.0.2 등 기존 JS 패키지는 이행기 동안 Verdaccio 게시가 여전히 필요할 수 있다(peer mac 소비자용). 현재 차단 원인: htpasswd 빈 파일 → 인증 사용자 0명, 토큰 무효.

복구 = 사용자 액션 필요 (대화형 npm adduser는 세션 비대화 컨텍스트에서 실행 불가):

bash# 1) Verdaccio 사용자 생성 (대화형 — 사용자가 직접)
npm adduser --registry http://127.0.0.1:4873
#   → username/password/email 입력 → ~/.npmrc 에 //127.0.0.1:4873/:_authToken 기록

# 2) publishConfig 우회 주의: package.json 의 publishConfig.registry 가
#    --registry 플래그를 덮어쓴다. 토큰이 4873용만 유효하면 임시로
#    publishConfig.registry 를 http://127.0.0.1:4873 로 변경 후 publish.

# 3) 게시
cd /Users/ef/crowny-gateway
npm publish --access public

# 4) 원복
npm config set @crowny:registry https://pkg.crowny.org

대안: htpasswd 백업이 있으면 복원(B), 또는 신규 사용자를 htpasswd에 직접 추가(C, 보안상 사용자 결정). 게이트웨이는 이 소스에서 직접 구동(node bin/cli.js)되므로 5.0.2 수정은 이미 라이브에 반영됨 — publish 차단이 기능을 막지 않는다.

---

③ pkg.crowny.org 도메인 — 한선씨 배포 호스트 전환 라우팅 변경안

현재 gateway.yaml: pkg.crowny.org → upstream http://127.0.0.1:4873(Verdaccio).

전환 단계 (무중단 · 라이브 :8080/:8443 비건드림)

단계 0 (현재 유지): Verdaccio 4873 그대로. 이행기 JS 게시 경로 보존.

단계 1 (병행 마운트): 한선씨 배포 API를 별도 포트(예: 한선씨 HTTP 서버 미래 안 B)로 띄우고, gateway.yaml 에 경로 분기 추가:

yaml- name: pkg
  domain: pkg.crowny.org
  upstream: http://127.0.0.1:4873        # 기본: 레거시 npm/Verdaccio
  routes:                                 # (게이트웨이 path 라우팅 지원 시)
    "/han/*": http://127.0.0.1:<한선포트>  # 한선씨 배포 매니페스트 API

경로 라우팅 미지원이면 별도 서브도메인 han-pkg.crowny.org 로 한선씨 호스트 신설 후 포트 등록:

bash~/.claude/scripts/crowny-ports.sh check <후보포트>
~/.claude/scripts/crowny-ports.sh set han-pkg.crowny.org <포트>

단계 2 (주체 전환): 한선씨 배포가 안정화되면 pkg.crowny.org 의 upstream 을 한선씨 배포 호스트로 교체, Verdaccio 는 legacy-pkg.crowny.org 로 강등(이행기 JS 소비자만).

단계 3 (폐기): @crowny/* JS 패키지가 모두 한선씨로 이행되면 Verdaccio 종료, pkg.crowny.org = 순수 한선씨 배포 호스트.

모든 포트 변경은 crowny-ports.sh set 으로 gateway.yaml(SSOT) 갱신. server.js 하드코딩 전 check 충돌 확인 필수. 라이브 :8080/:8443/9878/9907 프로세스 절대 종료 금지.

---

프로토타입 — 배포.한선

/Users/ef/crowny-gateway/한선게이트웨이/배포.한선 (hanseonc_high 컴파일 + 실행 검증 완료).

추천안(A)의 최소 단위 = 매니페스트 생성/쓰기/검증.

인터페이스:

함수 매니페스트생성(디렉토리, 패키지명, 버전) -> JSON 문자열
함수 매니페스트쓰기(디렉토리, 패키지명, 버전, 출력경로) -> Ti(1)/Ta(-1)
함수 매니페스트검증(디렉토리, 매니페스트경로) -> Ti(1 전부일치)/Om(0 불일치)/Ta(-1 읽기실패)

매니페스트 JSON 형식:

json{
  "package": "@crowny/gateway-hanseon",
  "version": "0.1.0",
  "kind": "hanseon-module-set",
  "host": "pkg.crowny.org",
  "dir": "/Users/ef/crowny-gateway/한선게이트웨이",
  "files": [
    {"name": "TLS_SNI.한선", "sha256": "0036e25d...", "bytes": 5036},
    {"name": "설정.한선", "sha256": "e36d294f...", "bytes": 3284}
  ],
  "count": 5
}

구현 메모:

• 파일 목록 = 내장 파일목록(경로) (opcode 255, ls 줄바꿈 문자열 반환) → 줄분리 → 끝나는가(줄,".한선") 필터
• 해시 = 내장 SHA256(내용) (opcode 291, 64자 hex). 라이브러리 불필요
• JSON 은 수동 문자열 조립(JSON.한선 미임포트 — 경량). _제이슨이스케이프 로 따옴표/역슬래시 처리
• 검증은 매니페스트 줄에서 name/sha256 추출 후 디스크 재해시 비교 → 변조/누락 = Om

검증 결과:

쓰기: Ti(성공) -> /tmp/배포_매니페스트.json
검증: Ti(전부 해시 일치)
탐지결과: Om(불일치) PASS   # 파일 변조/누락 시 정상 탐지

한선씨 함정 회피:

• 글로벌 배열 인덱스 대입 불가 → append-only(추가)만 사용
• 파일존재() 항상 -1 → 매니페스트쓰기 검증은 재읽기 글자수 비교로 우회
• 설정() 쓰기전용 → 읽기는 꺼내
• 인라인 ; 다단어 주석 금지 → // 사용

---

잔여 이슈

• 의존성 그래프(requires)·semver range 해석 미구현 — 안 A 매니페스트에 필드 추가 후속
• 안 B(한선씨 HTTP 레지스트리 데몬)는 미구현 — 실제 중앙 조회 필요 시 웹서버v2.한선 기반 구현
• crowny-hub ↔ 매니페스트 연동(peer 자동 동기화) 훅 미구현 — 본 프로토타입은 생성/검증까지
• pkg.crowny.org 경로 라우팅(/han/*) 가능 여부는 게이트웨이 path 라우팅 지원에 의존 — 미지원 시 서브도메인 신설
• 레거시 JS 게시 인증 복구는 사용자 대화형 npm adduser 액션 필요 (자동화 불가)