AriWeb-Suite/Ariweb-Suitle_Dev-Order_v0.4.0.md

Ariweb Suite 개발 지시 — 작성자: Oz · v0.4.0

작성자: Oz 작성일: 2026-10-29 이전 버전: v0.3.17(HawkEye·통합 배포, Oz) · v0.3.10 · v0.3.9 · v0.3.2 · v0.3.1 · v0.3.0 · v0.2.1 · v0.2.0 · v0.1.4 · v0.1.1 이번 개정: 도입 모듈 관리 콘솔의 서버 단위 설정 권한을 HAL 로 이전(통합 설정 관제). HAL 0.3.17 → 0.4.0. Webmaker 1.8.0 → 1.9.0, AriMail 1.0.11 → 1.1.0(각각 "HAL 0.4.0 대응" 명시). 이전 지시의 모든 기준은 그대로다.

1. 사용자 요구(Oz 원문, 약화 금지)

1. Webmaker 관리 콘솔의 권한 이전. HAL 에서 각 Webmaker 의 시스템 콘솔 주요 기능을 통합 관제한다: API 키 관리 · 마진·가격 정책 관리 · 모델 등 주요 설정 관리 · 기타 전체 적용 서비스 · 개별 서버 설정. 통합 인터페이스를 새로 만들고, HAL 에서 배포된 모든 서버를 관리할 수 있게 한다.
2. AriMail 관리 콘솔의 통합 관리. 도메인별 관리를 제외한 서버 단위 관리는 HAL 에서 통합 관리한다. 개별 메일 서버(도메인) 관리는 메일 서버 사용자가 직접 한다.
3. 기타 서비스 서버의 설정 통합 관리. 그 밖의 서버(Node Agent·백업·HawkEye 등) 설정도 HAL 에서 통합 관리한다.
4. 필요한 모듈(Arimail·Webmaker·backup 등)을 모두 업그레이드한다. 각 모듈의 중간 버전을 1 올리고, 각 모듈이 HAL 0.4.0 대응 버전임을 명시한다. 이번 릴리스는 HAL 0.4.0.

2. 필수 동작(계약)

1. 설정 목록(catalog) hal/settings/catalog.mjs: 모듈별(webmaker·arimail·agent) 관리 항목을 묶음(group)으로 선언한다 — Webmaker: API 키·인증(auth.mode·auth.apiKey·auth.oauthToken·serviceApiKey·backlogKey·mail.apiKey·source.token·ariweb.secret·mail.adminPassword) · 마진·가격 정책(marginPct·fx.·signupCredit·maxEdits·defaultTier·tiers.·signupApproval) · 모델(internalRef·defaultModel·claudeModels·ai.claudeMaxTurns·ai.openaiMaxTurns·ai.maxJobMinutes·ai.maxConcurrentJobs·ai.codexSandbox) · 전체 적용 서비스(service.allowSignup·letsEncryptEmail·mail.fromName·mail.defaultDomain·ariweb.portalUrl·endpoints.·limits.) · 서버별 설정(service.publicBaseUrl·service.siteOrigin·service.trustedProxies·service.internalAllow·ai.claudeBin·ai.codexBin·source.*·mail.url·mail.apiUrl·mail.domain·mail.adminLogin·mail.nickname·mail.ip). AriMail: 서버 단위 항목(수·발신 방식, Resend, DNS 제공자, SMTP 중계, Haraka, 사이트 표시, 사용량 API, Ariweb SSO) — 도메인별 LIMIT_* 는 제외. Agent: heartbeatMs. 항목마다 형식(text·int·number·bool·enum·list·url·secret)·범위·재시작 필요 여부·범위(global/server).
2. 저장소 managed_settings(scope global | server:<id>, module, key, value_json): 비밀값은 행에 두지 않고 Vault(managed:<scope>:<module>:<key>)에만 두며 행에는 참조만. 유효값 = 기본값 ← 전체(global) ← 서버 덮어쓰기(server). managed_settings_state(server_id, module, applied_hash, applied_at, status, error, job_id)에 서버별 적용 상태.
3. 운영자 API(/ops/api/settings): 목록·조회(GET, 비밀값은 "있음/없음"만) · 저장(PUT, 재인증 필요 — 가격·키·모델은 고객 영향) · 삭제(DELETE, 재인증) · 적용(POST /:module/apply, 재인증; 대상 비우면 그 모듈이 배치된 서버 전체, 없으면 즉시 no_targets). 알 수 없는 항목·형식 오류는 400 bad_setting. 감사 기록에 값은 남기지 않고 키 이름만.
4. 적용 작업 settings.apply(부모) → settings.apply.target(서버별) → Agent 작업 module.configure: Agent 가 HAL 에서(GET /agent/v1/settings/:module, Agent HMAC 인증, 자기 서버 범위의 유효값·비밀값) 설정을 받아 모듈 데이터 디렉터리의 hal-managed.json(0600, 실행 계정이 다르면 그 계정으로)으로 쓰고, 요청 시 서비스를 재시작한 뒤 건강을 확인한다. 결과의 hash 가 HAL 이 계산한 hash 와 같아야 ok. 다른 서버의 설정은 받을 수 없다.
5. 모듈 대응: Webmaker 1.9.0 lib/hal-managed.js — 기동 때 hal-managed.json 을 읽어 settings·config·vault 에 적용하고(같은 hash 면 생략), 관리 항목은 관리자 콘솔 API 에서 409 managed_by_hal 로 잠그며 화면에 "HAL 관리" 표시. AriMail 1.1.0 server/hal-managed.mjs — 기동 때 설정 파일에 적용(hidden 항목 포함), 설정 API 에서 관리 항목 409 managed_by_hal, 화면 표시. 두 모듈 모두 package.json 에 ariwebSuite.halCompat = "0.4.0" 을 명시하고 CHANGELOG 에 적는다. Agent 0.4.0: module.configure 작업, 자기 설정(heartbeatMs)도 hal-managed.json 으로 받는다.
6. 운영자 화면 /ops/settings "통합 설정 관제": 모듈 탭 → 범위(전체 / 서버 라디오) → 묶음별 입력(비밀값은 있음/없음·새 값 입력만) → 저장 → "서버에 적용"(체크 선택·재시작 여부) → 서버별 적용 상태(hash·시각·오류). 운영 현황에 "적용 안 된 설정" 수.
7. AI 도구: hal_settings_get(읽기) · hal_settings_set(고위험, 비밀값은 받지 않음) · hal_settings_apply(고위험). 스킬 문서에 설명.
8. 도입 모듈은 참조 저장소(WebHosting_AI_agent release/1.9.0, AriMail release/1.1.0)에 같은 변경을 커밋·push 하고, scripts/import-sources.mjs 의 고정 커밋을 새 커밋으로 갱신해 다시 들여온다(Suite 전용 수정 파일은 보존).

3. TDD·검증

• test/hal-040.test.mjs 를 먼저 쓰고 RED 확인 뒤 구현(카탈로그·저장/조회/유효값/비밀값 Vault·API 권한·적용 작업→Agent→상태·Agent 설정 API 범위·화면·AI 도구·버전·문서). test/agent.test.mjs 에 module.configure. 모듈 저장소에 test/hal-managed.test.*. 기존 테스트·전체 Suite(버전 0.4.0).
• 배포 뒤 bear read-back(마이그레이션·설정 API·화면), 이어서 HAL 작업으로 agent 0.4.0 → webmaker 1.9.0 → arimail 1.1.0 을 대상 서버에 순서대로 배포하고 건강을 확인한다(실패 시 중단·되돌리기).

4. 버전·배포

• HAL 0.4.0: package.json·README·VERSION_HISTORY·개발 지시·docs. 커밋 → push → main 병합 → 깨끗한 main 빌드·verify → bear HAL 배포 → read-back → HAL 로 나머지 모듈 배포.

5. 완료 조건

변경 파일, RED/GREEN·전체 테스트, 모듈 저장소 커밋·고정 커밋, 커밋·병합 커밋, artifact sha256, 배포 read-back, 모듈 배포 결과, 운영자 조치, 알려진 제한을 보고한다.