seokang-sk 0.13.7 → 0.13.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.MD +10 -0
- package/docs/automations/local-db-snapshot-publish.md +8 -0
- package/docs/changes/2026-10-09-git-post-merge-local-runtime.md +46 -0
- package/docs/changes/2026-10-23-deploy-completion.md +50 -0
- package/docs/changes/2026-10-23-deploy-db-preflight.md +66 -0
- package/docs/changes/2026-10-25-deploy-snapshot-and-git-only-update.md +38 -0
- package/docs/playbooks/README.md +1 -0
- package/docs/playbooks/deploy-completion.md +85 -0
- package/docs/playbooks/deploy-db-preflight.md +81 -0
- package/docs/playbooks/git-post-merge.md +49 -0
- package/docs/playbooks/server-readiness.md +72 -0
- package/docs/policies/core-safety.md +1 -0
- package/docs/templates/README.md +1 -0
- package/docs/templates/pr-test-guide.md +37 -0
- package/package.json +7 -3
- package/scripts/check_deploy_actor_guard.mjs +2 -2
- package/scripts/check_deploy_db_preflight.mjs +142 -0
- package/scripts/check_deploy_release.mjs +101 -0
- package/scripts/check_deploy_snapshot.mjs +104 -0
- package/scripts/check_deploy_transactions.mjs +140 -0
- package/scripts/check_fork_contribution.mjs +1 -1
- package/scripts/check_local_db_workflow.mjs +14 -2
- package/scripts/check_sk_cli_smoke.mjs +26 -0
- package/scripts/deploy_db_preflight.mjs +254 -0
- package/scripts/deploy_release.mjs +229 -0
- package/scripts/deploy_snapshot.mjs +118 -0
- package/scripts/local_db.mjs +32 -7
- package/scripts/local_db_snapshot_publish.mjs +10 -2
- package/scripts/sk.mjs +9 -1
package/README.MD
CHANGED
|
@@ -437,6 +437,8 @@ sk search "reviewer"
|
|
|
437
437
|
|
|
438
438
|
PR 처리는 예약 Inbox 자동화 없이 `$sk-git`에서 끝냅니다. OWNER가 canonical product repository에서 plain `$sk-git`을 호출하면 local 변경 유무보다 먼저 `sk git preflight --cwd "$PWD" --json`을 실행하고 현재 저장소의 허용된 contributor PR을 자동 발견해 remote diff를 검토한 뒤 순차 squash merge합니다. 결과에는 `PR 처리: 0건 | merged | held | pending` receipt가 반드시 남습니다. repository 이전 전 `Seokang/<repo>` remote도 GitHub canonical `full_name`이 정확히 `selink-lab/<허용 repo>`일 때만 같은 원본으로 인정합니다. 특정 PR 하나만 처리하려면 `$sk-git PR #<number> 병합`을 사용합니다. 친구는 personal fork에서 commit/push/PR까지만 수행합니다. `$seokang-update`는 PR을 처리하지 않고 clean default branch의 원본 fast-forward와 applicable local DB 갱신만 수행합니다.
|
|
439
439
|
|
|
440
|
+
PR 병합에 성공하면 원래 checkout을 맞추고, 필요한 managed local DB SQL과 관련 로컬 API 기동·재시작까지 이어갑니다. DB 상태를 확인해 미적용 SQL만 실행하며 운영 DB는 자동 변경하지 않습니다. 운영 API 배포는 해당 환경의 명시 승인이 있을 때 기존 `$sk-deploy`로 연결합니다. 결과에는 **무엇을 개발했는지, 어디까지 반영됐는지, 어느 화면에서 무엇을 입력하고 어떤 결과를 확인할지**를 텍스트로 함께 출력합니다. `병합만`·`DB 제외`·`서버 제외` 요청을 우선하며 단계가 막히면 병합 성공과 미반영 부분을 구분합니다. [상세 실행 순서](docs/playbooks/git-post-merge.md) · [결과 양식](docs/templates/pr-test-guide.md)
|
|
441
|
+
|
|
440
442
|
완료 branch는 `$sk-git` 종료 단계에서 `sk git cleanup`으로 정리합니다. default 반영, SHA 일치, 비보호, active worktree 없음이 증명된 자기 `origin`/local branch만 삭제하며 모호한 branch는 `HELD`로 보존합니다. 친구는 merge된 PR의 정확한 head SHA를 확인한 뒤 자기 fork branch를 정리하고, OWNER가 여러 제품 저장소를 정리할 때는 `sk git cleanup --workspace --cwd <workspace> --apply --json`을 사용합니다.
|
|
441
443
|
|
|
442
444
|
`$sk-git`과 `$sk-deploy`를 함께 호출하면 PR scan과 candidate별 merged/held 결과를 먼저 확정하고 canonical main을 fast-forward한 뒤 배포합니다. `$sk-deploy`만 호출한 경우에는 PR 또는 GitHub 사용자 확인을 배포 gate로 추가하지 않습니다.
|
|
@@ -588,3 +590,11 @@ sk init --cwd /path/to/project
|
|
|
588
590
|
SeoKang 작성
|
|
589
591
|
|
|
590
592
|
Git/배포 마무리는 [원래 checkout 동기화](docs/setup/git-checkout-sync.md)의 시작/완료 receipt를 확인한다.
|
|
593
|
+
|
|
594
|
+
서비스 배포는 API와 프론트를 모두 대상 목록에 적고 `scripts/deploy_release.mjs run --plan <file> --receipt <new-file>`로 실행합니다. 완료 보고 전 같은 plan/receipt로 `verify`가 통과해야 합니다. Office API만 성공하고 필수 프론트를 배포하지 않았으면 **부분 배포**이며 전체 완료가 아닙니다. config가 없는 대상은 blocked로 남기고, Frame처럼 첫 배포 전이라 제외하는 서비스는 근거를 따로 적습니다. [배포 계획·결과 집계 절차](docs/playbooks/deploy-completion.md)
|
|
595
|
+
|
|
596
|
+
서버/프론트는 추가로 **배포할 버전 전체의 누적 DB 구조**를 build 전과 upload 직전에 실제 대상에서 읽기 전용으로 확인합니다. 서버는 `DEPLOY_DB_IMPACT_STATUS=none`이어도 생략할 수 없습니다. `deploy.db-contract.json`에 현재 소스 fingerprint와 요구 테이블/컬럼/인덱스/FK·기대 DB identity를 고정하고, local config의 `DEPLOY_DB_TARGETS_FILE`로 SELECT-only 접속을 연결합니다. 계약 부재·누락·조회 불가·unknown이면 배포를 차단합니다. 기존 설정도 계약 준비가 필요합니다. HTTP 200은 DB 반영 증거가 아니며 미적용 SQL은 OWNER 수동 적용 후 다시 조회합니다. [준비와 검증 절차](docs/playbooks/deploy-db-preflight.md)
|
|
597
|
+
|
|
598
|
+
Git-only 스킬 변경도 npm 버전과 무관하게 `sk update`가 canonical Git을 fetch/ff-only하여 받습니다. npm exact-version 확인이 뒤에서 실패하면 이미 반영된 공용 skill Git/설정과 미실행 제품 Git/local DB 단계를 구분해 보고합니다.
|
|
599
|
+
|
|
600
|
+
운영 배포는 [완료 판정 및 snapshot 절차](docs/playbooks/deploy-completion.md)에 따라 모든 필수 API/프론트 성공 뒤 readiness·DB를 재확인하고 새 snapshot 두 채널을 발급합니다. 배포 실패/부분 배포/rollback/비운영에서는 발급하지 않으며 기존 예약 발급은 유지합니다.
|
|
@@ -35,3 +35,11 @@
|
|
|
35
35
|
- project별 최근 정상 release 수는 `retentionCount`를 따른다.
|
|
36
36
|
- release 삭제는 새 snapshot 게시가 성공한 뒤에만 수행한다.
|
|
37
37
|
- snapshot asset는 Git commit, PR, Notion, 공개 URL에 기록하지 않는다.
|
|
38
|
+
|
|
39
|
+
## Freshness 옵션 검증
|
|
40
|
+
|
|
41
|
+
`--freshness-hours <1..168 정수>`는 wrapper와 `sk db local publish` 모두 동일한 `freshnessHours` 옵션으로 해석한다. 두 snapshot channel에 같은 값을 전달하며 잘못된 값은 publish 전에 실패한다. 하위 publish는 `check_local_db_workflow.mjs`의 가짜 Docker/GitHub로 검증한다.
|
|
42
|
+
|
|
43
|
+
## 운영 배포 후 추가 발급
|
|
44
|
+
|
|
45
|
+
새벽 예약은 유지한다. 운영 서비스 배포는 [배포 전체 완료 절차](../playbooks/deploy-completion.md)에 따라 coordinator의 전체 성공·readiness·DB 재검증 뒤에만 같은 publisher를 `--force --expected-source <검증 identity>`로 호출한다. 두 채널은 기존 private 목적지와 권한을 유지한다. `--expected-source`는 배포 후 내부 전달용이며 하위 `publish --force`에서만 허용한다. 조회와 dump가 같은 DB endpoint/identity에 묶이며 mismatch는 dump 전에 차단한다. 이 feature 수정 작업 자체는 snapshot을 실행하는 지시가 아니다.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# PR 병합 후 로컬 DB·API 반영과 테스트 안내 — 2026-10-09
|
|
2
|
+
|
|
3
|
+
## 요청과 결과
|
|
4
|
+
|
|
5
|
+
- 요청 1: `sk-git`에서 PR 병합 후 로컬 DB와 API까지 반영. API 대상은 사용자가 **로컬 API 서버 재시작**으로 확정했다.
|
|
6
|
+
- 요청 2: 무엇을 개발했으며 사용자가 어떻게 테스트해야 하는지 채팅 텍스트로 제공.
|
|
7
|
+
- 기존 Git 검토 단계의 DB 무실행 규칙을 유지하면서, 성공적으로 병합한 canonical 코드의 후속 실행 단계를 분리했다. 기존 local DB/guard/helper를 연결하고 별도 자동 SQL runner는 만들지 않았다.
|
|
8
|
+
- 실제 스키마로 미적용 SQL을 확인하고 파일별 사후 검증을 요구한다. API는 정확한 프로젝트 프로세스만 재시작하고 사용자 테스트를 위해 유지한다. 실패한 단계는 병합 성공과 분리 보고한다.
|
|
9
|
+
|
|
10
|
+
## 작업 계약과 범위
|
|
11
|
+
|
|
12
|
+
- Mode: Implementation. Project Type: Backend(개발 도구), Track: seokang-skill.
|
|
13
|
+
- 대상: skill/workflow, docs/spec. 기준: Reference-based reinterpretation.
|
|
14
|
+
- 구현 전에 `/tmp/sk-git-post-merge-contract.md`에 작업 계약·impact map·검증 계획을 고정했다. API 환경은 질의 후 local로 확정했다.
|
|
15
|
+
- 허용 차이: 병합-only 완료에서 원래 checkout → 필요한 managed local SQL → 관련 local API → 개발 내용·사용자 테스트 안내로 확장.
|
|
16
|
+
- 변경: `skills/sk-git/SKILL.md`, `skills/sk-git/agents/openai.yaml`, `docs/playbooks/git-post-merge.md`, `docs/templates/pr-test-guide.md`, 문서 인덱스, `README.MD`, `AGENTS.md`, `docs/policies/core-safety.md`.
|
|
17
|
+
- 참조만: Git merge/checkout helper, `scripts/local_db.mjs`, DB execution guard, sk-local-db/sk-deploy와 기존 배포 helper.
|
|
18
|
+
- 제외: 제품 코드, 실제 PR 병합/배포/DB/API 실행, 생성 홈 설정과 기존 사용자 변경. UI/반응형/config/default/DDL/CLI 수정 없음.
|
|
19
|
+
- DB 영향은 워크플로에만 있다. Production mutation 없음; 운영 SQL 수동 실행과 credential/ACL/secret/managed identity 경계를 유지한다.
|
|
20
|
+
|
|
21
|
+
## 검증
|
|
22
|
+
|
|
23
|
+
- `check_docs_integrity.mjs`: 수정 문서/스킬의 링크·정책 검사 통과.
|
|
24
|
+
- `check_fork_contribution.mjs`: 기존 Git 권한·fork 계약 검사 통과.
|
|
25
|
+
- `quick_validate.py skills/sk-git`: 통과. 기본 Python에 PyYAML이 없어 `/tmp`에만 검증 의존성을 설치했고 사용자 Python/config는 변경하지 않았다.
|
|
26
|
+
- `git diff --check`: 통과.
|
|
27
|
+
- `check_npm_release_scope.mjs --file ... --json`: 이번 변경만은 `NOT_REQUIRED`. 전체 worktree 판정의 `REQUIRED`는 기존 `package.json`, `scripts/local_db.mjs`, `scripts/sk.mjs` 변경에 기인하며 이번 작업으로 publish하지 않았다.
|
|
28
|
+
- 실제 DB/API/Git mutation은 실행하지 않았다. 스킬 지침과 연결 계약 검증이며 실제 PR 병합 후 runtime 검증 결과를 뜻하지 않는다.
|
|
29
|
+
|
|
30
|
+
## 작업 이력과 후속 조치
|
|
31
|
+
|
|
32
|
+
- 독립 read-only 분석: 기존 local SQL helper에 migration ledger가 없고 무조건 sync하면 fixture를 교체할 수 있음을 확인했다. 현재 DB 우선 보존과 SQL별 사전·사후 검증으로 반영했다.
|
|
33
|
+
- 독립 시나리오 리뷰: 정상 병합/이미 적용된 SQL, 여러 PR 중 conflict, dirty checkout, PR 0건/contributor, 운영 DB 선행조건, 병합만 요청을 검토했다. P1 없음. P2 두 건(병합만 범위 모호, 복합 PR/contributor 상태 누락)을 수정했다. `병합만`은 원격 검토·병합만 실행하고 checkout/DB/API/cleanup은 제외하며, PR별 merged/blocked 결과와 contributor 상태를 함께 출력한다.
|
|
34
|
+
- 독립 재검토에서 두 P2 해결 및 남은 P1/P2 없음 확인. 수정 뒤 문서·스킬 형식·fork 계약·diff 검사를 다시 통과했다.
|
|
35
|
+
- 요청 1: 완료(스킬 후속 로컬 반영 절차). 요청 2: 완료(채팅 텍스트 개발 내용·테스트 안내). 실제 제품 runtime 실행 증거는 다음 병합 호출에서 확보한다.
|
|
36
|
+
- 기존 미커밋 변경을 보존한 채 공용 원본에 반영했다. Git commit/push와 다른 PC 배포는 이번 요청 범위 밖이다.
|
|
37
|
+
- 다음 OWNER 제품 PR 병합에서 실제 local schema, 프로세스, API smoke와 사용자 테스트 안내를 확인한다. 운영 API 자동 배포는 이번 요청에 포함하지 않는다.
|
|
38
|
+
|
|
39
|
+
## Git 배포 준비
|
|
40
|
+
|
|
41
|
+
- 후속 `$sk-git`·`$sk-deploy` 요청에서 현재 canonical 저장소의 열린 PR 0건을 확인했다.
|
|
42
|
+
- 작업 시작 전 snapshot과 대조해 이번 변경분만 분리한다. 기존 Notion/배포/CLI 미커밋 변경은 포함하지 않는다.
|
|
43
|
+
- 배포본이 기존 미배포 문서/배포 기능에 의존하지 않도록 후속 단계의 로컬 기록 위치를 직접 명시하고 운영 검증은 해당 helper의 실제 계약을 따른다.
|
|
44
|
+
- clean HEAD 기반 분리 검증에서 fork 검사 스크립트가 이미 바뀐 production DB 경계의 옛 문구를 요구해 실패했다. 기존 로컬 수정 중 해당 검사 문구 한 줄만 함께 반영하여 현행 정책과 일치시켰고 재검사를 통과했다. 나머지 기존 변경은 보존한다.
|
|
45
|
+
- 분리본 문서 검사·스킬 형식·Git 권한/secret 검사 통과. npm release scope는 `NOT_REQUIRED`이며 Git 배포 대상으로 판정했다.
|
|
46
|
+
- 최종 push/원래 checkout 상태는 `.sk/git-post-merge-release-20261009.json` receipt와 채팅 결과로 확인한다.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# 배포 대상 누락과 전체 완료 오보고 차단 — 2026-10-23
|
|
2
|
+
|
|
3
|
+
## 구현 전 작업 계약
|
|
4
|
+
|
|
5
|
+
- 요청: Office API만 실행하고 프론트를 빠뜨린 상태에서 전체 배포 완료를 보고하는 문제 수정.
|
|
6
|
+
- Mode: Implementation. Project Type: Backend(배포 도구), Track: seokang-skill. 대상: skill/workflow.
|
|
7
|
+
- 기준: Reference-based reinterpretation. 기존 artifact별 DB/credential/transaction 검증은 보존하고, 요청 전체의 실행 계획과 결과 집계를 추가한다.
|
|
8
|
+
- 근거: deploy-server/front wrapper가 별개이고 기존 완료 메시지는 해당 artifact만 증명한다. 두 artifact가 모두 실행됐는지 확인하는 집계 기능이 없다.
|
|
9
|
+
- 범위: 공용 deploy coordinator/결과 marker/fixture, deploy skill/playbook, README/AGENTS/package harness. 기존 다른 미커밋 변경 보존.
|
|
10
|
+
- 제외: 실제 Office/Frame 코드·배포·DB·credential, Git push/npm publish. Frame은 사용자 설명대로 첫 배포 전 제외 가능하며 이번 작업에서 신규 배포하지 않는다.
|
|
11
|
+
- 완료 조건: API만 성공/프론트 미실행·실패·설정 없음·증거 없음이면 전체 성공 금지. 두 필수 artifact가 같은 실행에서 검증 완료한 경우만 전체 성공. 명시 제외는 대상별 근거와 함께 유지.
|
|
12
|
+
- default/fallback: 모든 서비스의 server/frontend를 계획에 명시하고 임의 제외하지 않는다. UI/반응형/Figma/DDL 영향 없음. production DB 실행 없음.
|
|
13
|
+
|
|
14
|
+
## 영향 맵과 검증 계획
|
|
15
|
+
|
|
16
|
+
| 레이어 | 구분 | 검증 |
|
|
17
|
+
| --- | --- | --- |
|
|
18
|
+
| 배포 workflow/완료 결과 | 수정 | 필수 대상 목록과 실제 실행 결과 일치 fixture |
|
|
19
|
+
| wrapper | 수정 | 성공 지점에서만 현재 실행에 결합된 marker 출력 |
|
|
20
|
+
| DB preflight/transaction | 참조만 | 기존 DB·복구 회귀 검사 |
|
|
21
|
+
| 제품 UI/API/schema/설정 | 제외 | 실제 외부 실행 없음 |
|
|
22
|
+
| skill/docs/config | 수정 | docs integrity, npm release scope |
|
|
23
|
+
|
|
24
|
+
- deterministic checks: 신규 coordinator fixture, deploy actor guard, DB preflight fixture, reliability harness, docs integrity, Bash 문법, diff whitespace, npm release scope. CLI/operator guard 구현은 변경하지 않는다.
|
|
25
|
+
- 보안: 임의 command/hook 금지, 고정된 공용 wrapper만 실행, raw log/credential을 receipt에 저장하지 않음, source/config/실행 식별자에 결과 결합.
|
|
26
|
+
- 독립 reviewer에 read-only 회귀 검토를 맡기고 최종 수정과 검증은 메인 agent가 수행한다.
|
|
27
|
+
|
|
28
|
+
## 결과
|
|
29
|
+
|
|
30
|
+
- 요청 1(Office 프론트를 누락하고 전체 완료라고 보고하는 경로 수정): 완료.
|
|
31
|
+
- `scripts/deploy_release.mjs`: 서비스별 server/frontend와 명시 제외 근거를 고정하고, 모든 필수 config/source/key 존재를 확인한 뒤 기존 고정 wrapper를 순차 실행한다. 상세 DB/readiness/runtime 검증은 wrapper가 수행한다. 새 receipt를 실행 전에 만들고 결과를 원자 갱신한다.
|
|
32
|
+
- 각 wrapper는 성공 지점에서만 artifact 결과를 출력하고 coordinator 전용 임시 파일에 기록한다. private 결과 파일·exit 0·같은 run/target/environment/source/config/destination·프론트 env·timestamp를 대조하며 stdout의 DONE이나 과거 결과는 인정하지 않는다. raw credential/log는 receipt에 저장하지 않는다.
|
|
33
|
+
- 필수 프론트가 실패/미실행/설정 없음이면 전체 성공 금지. 동일 원격 destination을 서로 다른 서비스로 중복 선언해 덮어쓰는 경로도 사전에 차단한다. 중간 실패 시 후속 대상은 pending으로 남는다.
|
|
34
|
+
- `DEPLOY_COMPLETE`는 모든 required 대상이 이번 실행에서 성공한 경우만 가능하며 완료 보고 직전 `verify`를 다시 요구한다. direct wrapper는 `RELEASE_COMPLETION_UNVERIFIED`와 artifact-only 상태를 표시한다.
|
|
35
|
+
- `skills/sk-deploy/SKILL.md`, `docs/playbooks/deploy-completion.md`, README/AGENTS에 새 진입점·대상 확정·부분 배포 보고를 연결하고 package harness에 신규 검사를 등록했다.
|
|
36
|
+
- 독립 reviewer read-only 검토에서 발견한 중복 원격 대상 문제를 수정했고 최종 차단급 false-COMPLETE finding 없음으로 검토했다. 추가 제안인 3개 대상 중간 실패/후속 미실행 fixture도 반영했다.
|
|
37
|
+
|
|
38
|
+
## 검증
|
|
39
|
+
|
|
40
|
+
- 신규 deploy release 검사: **19 시나리오 통과**. 필수 프론트 생략/설정 없음/키 없음/실패/성공 marker 없음/이전 run/다른 target·환경·destination/오래된 timestamp/계획 변경/이전 대상 source 변경/receipt 재사용/중복 원격 대상/중간 실패 후 pending을 검증했다.
|
|
41
|
+
- 기존 DB preflight **69 fixture commands**, reliability **74 fixture commands**, deploy actor guard: 통과. 실제 DB/SSH/배포 대신 임시 fixture만 사용했다.
|
|
42
|
+
- docs integrity, Node/Bash 문법, `git diff --check`: 통과.
|
|
43
|
+
- npm release scope: 현재 전체 dirty 작업 기준 REQUIRED. 기존 변경도 포함하며 이번 작업에서 version/tag/publish하지 않았다.
|
|
44
|
+
|
|
45
|
+
## 남은 한계와 반영 범위
|
|
46
|
+
|
|
47
|
+
- 최초 요청 범위의 모든 서비스를 목록에 넣고 제외 근거를 사실대로 확인하는 책임은 Codex에게 있다. 프로그램이 대화에 없던 제품을 자동 발견하거나 모든 주변 저장소를 배포하지 않는다.
|
|
48
|
+
- 여러 artifact를 하나의 원자적 transaction으로 배포하지 않는다. 프론트 실패 시 앞선 API 성공을 보존한 채 부분 배포로 보고하며 자동 전체 rollback하지 않는다.
|
|
49
|
+
- `verify`는 이번 실행의 기록과 현재 입력 정합성 검사다. 이후 원격 상태가 바뀌지 않았다는 지속 증명이나 브라우저 업무 smoke를 대신하지 않는다.
|
|
50
|
+
- 현재 PC 공용 원본 수정 완료. Office/Frame 운영 배포, production DB 변경, Git commit/push, npm publish는 실행하지 않았다. 기존 다른 미커밋 작업과 DB gate를 보존했다.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# 배포 전 운영 DB 구조 검증 — 2026-10-23
|
|
2
|
+
|
|
3
|
+
## 작업 계약과 계획
|
|
4
|
+
|
|
5
|
+
- 요청: 마지막 변경만 보고 DB 영향이 없다고 판단하여 누적 SQL이 미적용된 API를 배포하는 재발을 방지한다.
|
|
6
|
+
- 대상 아티팩트: skill/workflow. Track: seokang-skill, Project Type: Backend(배포 도구).
|
|
7
|
+
- 작업 기준: Reference-based reinterpretation. 기존 credential/DB 무실행/transaction/readiness는 보존하고 배포 전 실제 DB 구조 확인을 필수로 추가한다.
|
|
8
|
+
- 근거: `guard-deploy.sh`는 자동 migration 실행 여부만 검사하며 `DEPLOY_DB_IMPACT_STATUS=none`의 근거나 실제 구조를 조회하지 않는다. 사용자 캡처는 누적 테이블/컬럼 누락 이후에도 HTTP 200으로 완료한 사례다.
|
|
9
|
+
- 변경 허용: deploy skill/wrapper/config template, 구조 검증기와 fixture 검사, README/AGENTS 및 전문 playbook, 본 기록.
|
|
10
|
+
- 제외: 제품 코드/실제 로컬 credential, 운영 DB 변경, Git push와 실제 서비스 배포/npm publish, 다른 미커밋 작업.
|
|
11
|
+
- 허용 차이: server/frontend는 기존 config만으로 배포할 수 없고 현재 소스에 결합된 누적 DB 계약이 필요하다. DB 미사용은 명시적 근거가 있는 계약으로만 허용한다. unknown은 차단한다.
|
|
12
|
+
- default/fallback: DB target/alias/schema/기대 구조는 추정하지 않는다. 명시한 설정만 사용한다.
|
|
13
|
+
- UI/반응형/Figma: 해당 없음. 보안 점검: 필수(SELECT-only, SQL 생성 제한, secret 출력 금지).
|
|
14
|
+
- DB 영향: 운영 schema/data 변경 없음. 구조 safe-read 경로 추가. 필요한 SQL 실행은 OWNER의 별도 DB 도구 수동 실행이며 이번 턴에는 실제 DB에 연결하지 않는다.
|
|
15
|
+
|
|
16
|
+
## 영향 맵
|
|
17
|
+
|
|
18
|
+
| 레이어 | 구분 | 변경/검증 |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| deploy workflow/config | 수정 | 누적 계약 필수, build 전과 upload 전 fresh 검증 |
|
|
21
|
+
| DB metadata query | 수정 | 고정 SELECT/SHOW만 생성, target identity와 read-only grant 검증 |
|
|
22
|
+
| docs/skill/README | 수정 | 계약 준비/미적용 handoff/완료 기준 |
|
|
23
|
+
| startup/transaction | 참조만 | 기존 migration 금지와 복구 경로 보존 |
|
|
24
|
+
| 제품 UI/API/schema/데이터 | 제외 | 실제 DB/배포 실행 없음 |
|
|
25
|
+
|
|
26
|
+
## 검증 계획과 완료 조건
|
|
27
|
+
|
|
28
|
+
- 새 fixture 검사: 누적 테이블/컬럼/타입/null/index/FK 누락, none/unknown 오판, 오래된 계약, 대상 불일치, 쓰기 grant, 조회 실패/빈 응답, 업로드 전 재확인 실패 시 build/upload 차단.
|
|
29
|
+
- 기존 필수 검사: deploy actor guard, operator guard, CLI smoke, DB boundary smoke, reliability harness, docs integrity, config defaults, npm release scope.
|
|
30
|
+
- 모델/DDL/UI 검사는 해당 없음. 실제 서비스 startup은 도구 작업에 해당하지 않으며 fake DB/SSH/build fixture로 wrapper 연결을 확인한다.
|
|
31
|
+
- 완료: 필수 검사가 통과하고 누락/미확인에서 배포가 중단됨을 증명한다. 실제 운영 DB 적용이나 서비스 배포 완료로 보고하지 않는다.
|
|
32
|
+
|
|
33
|
+
## 실행 결과
|
|
34
|
+
|
|
35
|
+
- 요청 1(누적 DB 미적용을 놓치는 배포 스킬 수정): 완료. 현재 PC 공용 원본에 반영했으며 Git push/npm publish/운영 배포는 수행하지 않았다.
|
|
36
|
+
- `scripts/deploy_db_preflight.mjs`: Git tracked 누적 contract, 전체 실제 소스 fingerprint, 기대 DB identity, SELECT-only 권한, BASE TABLE/컬럼/type/null/default/extra/index 순서·unique/FK 순서·동작을 검증한다. 임의 SQL과 실행 파일 config를 받지 않는다.
|
|
37
|
+
- server/frontend wrapper는 build 전과 첫 원격 staging/upload 전에 검사기를 실행한다. 서버 none은 차단하고 프론트 none은 독립 정적 화면의 명시 근거가 있어야 한다. unknown/미조회/미적용은 exit 2다.
|
|
38
|
+
- 원격 app.env 등 검토한 설정의 hash는 실행 binding에만 포함하고 raw hash/내용을 저장·출력하지 않는다. ignored 프론트 환경파일도 binding에 포함하여 build 도중 변경을 감지한다.
|
|
39
|
+
- skill/README/AGENTS/config templates 및 `docs/playbooks/deploy-db-preflight.md`에 준비·실패·OWNER 수동 적용 후 재조회·완료 증거를 연결했다.
|
|
40
|
+
- 독립 reviewer subagent가 read-only 검토했다. tracked identity, 계약 추적, 임의 clientBinary 금지, BASE TABLE 확인, unknown-field 차단, runtime/env 변경 검증을 보강했고 최종 차단급 결함 없음으로 검토했다. 실제 DB target/credential은 읽지 않았다.
|
|
41
|
+
|
|
42
|
+
## 검증 결과
|
|
43
|
+
|
|
44
|
+
- DB preflight fixture: **69 commands 통과**. 누적 컬럼 누락, 잘못된 table/type/null/default/index/FK, 다른 DB, write grant/role, 조회 실패, none/unknown, 오래된 소스/계약, 설정 변경을 포함한다. build 중 source/schema 변경 시 SCP/staging 0회를 확인했다.
|
|
45
|
+
- `npm run check:harness:reliability`: **74 fixture commands 통과**. 기존 startup/readiness/transaction/복구 동작을 유지했다.
|
|
46
|
+
- deploy actor guard, operator guard, CLI smoke, DB execution boundary smoke, docs integrity, unauthorized defaults, Bash 문법, `git diff --check`: 통과.
|
|
47
|
+
- npm release scope 및 smoke: 통과. 현재 전체 dirty 작업 기준 REQUIRED이며 기존 CLI 변경도 포함한 결과다. 이번 턴에는 버전 변경/tag/publish를 하지 않았다.
|
|
48
|
+
- 추가 skill-creator Python 형식 검사기는 bundled Python의 PyYAML 부재로 실행하지 못했다. 임시 디렉터리 설치도 제공된 패키지 인덱스에서 배포본을 찾지 못해 실패했다. SKILL frontmatter는 변경하지 않았으며 저장소 docs integrity 검사는 통과했다. 이 제한은 DB 회귀 검사 결과와 구분한다.
|
|
49
|
+
|
|
50
|
+
## 남은 한계와 첫 적용
|
|
51
|
+
|
|
52
|
+
- 운영 MariaDB에 실제로 연결한 검증/제품 계약 작성/서비스 배포는 이번 스킬 수정 범위 밖이며 수행하지 않았다. 다음 제품 배포에서 기존 config만으로는 진행되지 않고 해당 제품의 누적 계약과 SELECT-only target 준비가 필요하다.
|
|
53
|
+
- 최초 계약의 완전성과 runtime datasource→기대 DB 대응은 코드/활성 profile/원격 설정의 근거 검토 책임이다. 동적 query를 전부 자동 추론한다고 주장하지 않는다. 서버 원격 app.env는 필수로 확인하며 외부 참조 설정도 runtimeFiles에 포함한다.
|
|
54
|
+
- 두 번째 read-only 확인 후 동시 DBA/schema/config 변경을 잠그지는 않는다. seed/backfill, view/procedure/trigger/CHECK 등 형식이 지원하지 않는 필수 선행조건은 별도 safe-read 확인 없이는 배포하지 않는다.
|
|
55
|
+
- 복구 시 이번 작업의 DB preflight 호출·검사기·문서만 검토하여 되돌린다. 기존 미커밋 변경과 transaction 개선을 통째로 되돌리지 않는다.
|
|
56
|
+
|
|
57
|
+
## 후속 확인: 프론트 배포 누락 — Planning
|
|
58
|
+
|
|
59
|
+
- Project Type: seokang-skill. 대상: skill/workflow. 사용자 질문은 이전 수정에 프론트 누락 방지가 포함됐는지 확인하는 요청이다. 이번 후속에서는 실행 코드/운영을 변경하지 않았다.
|
|
60
|
+
- 근거: 사용자 캡처와 현재 deploy skill/server/front wrapper. Frame은 첫 배포 전이라 제외가 맞다는 사용자 설명을 반영한다. Office 프론트 누락과 Frame 제외는 별개다. 해당 운영 서버의 현재 배포 상태는 조회하지 않았다.
|
|
61
|
+
- 확인 결과: DB preflight만 추가했으며 server/front는 각각 실행된다. 요청 전체의 필수 배포 대상과 실제 실행 증거를 집계하는 완료 검사가 없어 Office API만 배포하고 전체 완료로 보고하는 문제는 **미수정**이다. 독립 reviewer도 같은 결론을 확인했다.
|
|
62
|
+
- 의도적 차이 제안: 기존 운영 중인 서비스에서 이번 요청에 필요한 API/프론트를 배포 전에 명시하고, 신규/명시 제외 대상을 별도로 고정한다. 설정 없음은 자동 제외 근거가 아니라 필수 대상의 차단 상태다.
|
|
63
|
+
- 옵션: 완료 문구 규칙만 보강하거나, 대상 목록과 실제 배포 증거를 연결하는 실행형 집계 검사를 추가할 수 있다. 추천은 후자이며 하나라도 미배포/실패/미확인이면 부분 배포로만 보고한다. API 성공을 프론트 성공으로 대체하지 않는다.
|
|
64
|
+
- 다음 구현 범위: deploy skill의 대상 확정 → artifact별 실제 결과 수집 → 전체 완료 판정 → 프론트 미실행/설정 없음/명시 제외 fixture 검증. 기존 DB gate와 서버/프론트 transaction을 보존하는 workflow 기능 변경이며 refactor가 아니다. 모든 주변 저장소를 무조건 배포하는 규칙으로 확대하지 않는다.
|
|
65
|
+
- 요청 2(수정 여부 확인): 완료. 프론트 누락 방지 구현: 미완료(앞선 DB 검증 수정에 포함되지 않음). 이번 후속은 소스/독립 리뷰와 문서 링크 검증만 수행한다.
|
|
66
|
+
- 이후 사용자가 명시적으로 구현을 요청하여 [프론트 누락과 전체 완료 오보고 차단](2026-10-23-deploy-completion.md)을 구현·검증했다. 위 미완료는 질문 당시의 상태이며 후속 결과는 해당 기록을 따른다.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# 운영 배포 후 snapshot과 Git-only 스킬 갱신 — 2026-10-25
|
|
2
|
+
|
|
3
|
+
## 요청과 결과
|
|
4
|
+
|
|
5
|
+
1. npm 버전과 무관하게 `sk update`는 canonical Git을 fetch/ff-only하고 최신 스크립트로 setup한다. 같은 npm 버전이면 registry 조회/재설치를 하지 않는다. Git/setup 뒤 exact npm 버전 확인이 실패할 때 `공용 skill Git/설정 반영 완료 / npm bootstrap 중단 / 제품 Git·local DB 미실행`을 구분하도록 보완했다. 2026-10-25 registry에서 exact 0.13.8 조회는 E404였다. 친구 PC의 실제 실행 로그는 확인하지 않았다.
|
|
6
|
+
2. production 배포 계획에 DB별 snapshot source를 명시한다. 모든 필수 API/프론트 배포 성공과 server HTTP readiness를 확인하고 모든 대상의 DB 구조/runtime을 새로 조회한 뒤 기존 두 private channel publisher를 force 실행한다. 실패·부분·rollback·비운영·verify-only에서는 게시하지 않는다. 새벽 예약은 변경하지 않았다.
|
|
7
|
+
3. 기존 server/frontend wrapper의 build 전·upload 전 schema guard 두 번 호출을 재확인했다. contract와 실제 tables/columns/type/null/default/index/FK 및 DB identity를 대조하며 unknown/누락/조회불가가 차단된다. 이번에는 snapshot 전후 재검증과 dump 직전 source identity도 추가했다. 실제 운영 DB의 현재 반영 상태를 조회한 작업은 아니다.
|
|
8
|
+
|
|
9
|
+
## 영향 범위
|
|
10
|
+
|
|
11
|
+
- `scripts/deploy_release.mjs`, 신규 `scripts/deploy_snapshot.mjs`: snapshot source coverage/배포 증거/고정 publisher/상태 기록.
|
|
12
|
+
- `scripts/local_db_snapshot_publish.mjs`, `scripts/local_db.mjs`: force 및 expected source 전달, SELECT-only와 grant-option 차단, DB 주소·port·database·server-id·version·current-user 검증, 조회와 dump endpoint 고정.
|
|
13
|
+
- `scripts/sk.mjs`, update/deploy skill과 관련 문서: Git과 npm 단계 결과 분리, 운영 snapshot 계약.
|
|
14
|
+
- 기존 무관한 미커밋 변경을 유지했다. 구현 검증에서는 실제 운영 배포/DB 접근/snapshot 게시와 예약 자동화 변경을 수행하지 않았다. Git/npm release는 별도 사용자 호출로 진행한다.
|
|
15
|
+
- 이전 세션의 로컬 release backup은 검사 대상 소스로 오인되지 않도록 내용을 바이트 대조한 0600 압축 백업으로 보존했다.
|
|
16
|
+
|
|
17
|
+
## 검증
|
|
18
|
+
|
|
19
|
+
- 신규 postdeploy fixture 27개: 전체 성공, API/프론트 실패·누락·rollback, process-only, DB drift/binding 오류, 잘못된 계획/대상/정책/coverage, 비운영, DB 없는 frontend, publisher 실패/빈 출력/fresh no-op/잘못된 저장소·policy, 발급 중 소스/공유 DB의 다른 대상 schema drift, receipt 재사용과 verify의 비게시. wrapper의 두 channel force/identity 전달과 예약 호환도 검사했다.
|
|
20
|
+
- 기존 누적 DB preflight 69개 및 배포 집계 19개 통과. DB execution boundary strict/smoke와 deploy credential guard 통과.
|
|
21
|
+
- CLI smoke: 같은 npm 버전에서 새 SKILL Git commit을 받으면서 npm view/install 0회, exact npm 버전 부재 시 Git/setup 보존과 부분 완료 메시지 검증.
|
|
22
|
+
- local DB workflow smoke: source identity 불일치 시 dump 전 차단, 명시 endpoint dump 연결, 기존 snapshot publish/sync 경로 검사. 추가 grant-option/잘못된 expected-source/force 누락 검사까지 통과했다.
|
|
23
|
+
- docs integrity, npm release scope smoke, syntax/diff 검사. npm release scope는 REQUIRED: CLI runtime 변경을 배포하려면 별도 Git/npm 반영이 필요하다.
|
|
24
|
+
- 기본 no-db command checker는 임의 Node harness 명령을 지원하지 않아 ALLOW로 보고하지 않았다. 전체 배포 DB boundary 정적 검사와 전용 fake-only harness로 독립 검증했다. 첫 전체 검사는 이전 백업의 fixture 문자열을 잡았고 백업 압축 보존 후 실제 소스 전체 strict 검사가 통과했다.
|
|
25
|
+
- 독립 read-only agent가 updater 흐름을 확인하고 deploy reviewer가 source 계정·grant-option·발급 후 전체 DB 재검증을 검토했다.
|
|
26
|
+
|
|
27
|
+
## 한계와 후속
|
|
28
|
+
|
|
29
|
+
- production plan에는 `snapshots` 배열이 새로 필요하다. 누적 DB를 가진 프로젝트는 기존 versioned local DB policy/mask/verification과 approved-plain 설정을 준비해야 한다. 설정을 임의로 생성하거나 DB가 없다고 우회하지 않는다.
|
|
30
|
+
- process-only 배포는 계속 가능하지만 snapshot 완료를 증명하지 못하므로 보류한다. 준비된 readiness URL만 사용한다.
|
|
31
|
+
- 배포와 두 channel 게시를 하나의 원자적 transaction으로 만들지는 않는다. 발급 도중 외부 DDL/배포·프로세스 중단이 발생하면 이미 일부 channel이 게시됐을 수 있다. 전체 snapshot 성공으로 보고하지 않고 private Release/receipt를 확인하며 무조건 재게시하지 않는다.
|
|
32
|
+
- HTTP/hash/metadata 검증은 로그인 후 업무 저장·재조회 proof와 별개다. 실제 운영 배포와 snapshot 발급 검증은 수행하지 않았다.
|
|
33
|
+
|
|
34
|
+
## 0.13.9 릴리스 사전 확인
|
|
35
|
+
|
|
36
|
+
- 사용자 `$sk-git $sk-deploy` 호출로 이번 변경 17개 경로만 격리했다. 열린 canonical PR 0건을 확인했다.
|
|
37
|
+
- `seokang-sk@0.13.9`의 registry 조회는 E404이고 `npm pack --dry-run`은 통과했다. 기존 v0.13.8 태그는 변경하지 않는다.
|
|
38
|
+
- 이 PC의 기존 npm 인증은 E401이므로 `HANDOFF_CONFIGURED_DEPLOY_HOST` 대상이다. Git 반영과 npm 게시를 분리하고, 인증이 준비된 배포 환경에서 같은 commit/version으로 이어간다. 토큰 복사나 재로그인은 수행하지 않는다.
|
package/docs/playbooks/README.md
CHANGED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# 배포 대상 전체의 완료 판정
|
|
2
|
+
|
|
3
|
+
## 대상 확정
|
|
4
|
+
|
|
5
|
+
`배포`라는 요청은 현재 대화에서 승인한 서비스 범위로 해석한다. Office처럼 운영 API와 프론트가 함께 있는 서비스는 두 대상을 모두 목록에 올린다. 마지막 변경이 API라는 이유나 config 파일이 없다는 이유로 프론트를 지우지 않는다. 사용자가 `API만` 등으로 제외했거나 기존 운영 대상이 아님을 확인한 경우에만 근거를 기록해 제외한다. 주변 저장소 전부를 자동 배포하지 않는다.
|
|
6
|
+
|
|
7
|
+
- 사용자의 이번 사례: Office API와 Office 프론트는 필수. Frame은 아직 첫 배포 전이므로 이번 배포에서 제외. 이를 다른 제품에 하드코딩하지 않는다.
|
|
8
|
+
- config/credential 부재는 `blocked`이며 제외 사유가 아니다. 최초 배포가 필요한 새 서비스는 별도 승인된 범위에서 준비한다.
|
|
9
|
+
- 먼저 요청·현재 프로젝트 연결·운영 이력으로 scope를 확인하고 `scopeEvidence`에 근거를 남긴다. 모든 service에는 `server`와 `frontend` 항목이 필요하다. 프로그램은 알려주지 않은 서비스 자체를 자동 발견하지 못하므로, 성공을 만들기 위해 서비스를 계획에서 삭제하거나 제외로 바꾸지 않는다.
|
|
10
|
+
|
|
11
|
+
## 실행 계획
|
|
12
|
+
|
|
13
|
+
Codex가 workspace의 Git-ignored 배포 기록 경로에 JSON 계획을 작성한다. 대상은 실행 전에 확정하며 실행 중 변경을 금지한다. 계획과 receipt는 source fingerprint에 포함되지 않도록 각 제품 저장소 밖 또는 확인된 ignored 경로에 둔다. credential 값은 포함하지 않는다.
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"version": 1,
|
|
18
|
+
"environment": "production",
|
|
19
|
+
"snapshots": [{"targetId": "office/server", "databaseId": "primary"}],
|
|
20
|
+
"scopeEvidence": "이번 Office 배포 요청과 기존 운영 API/프론트 확인. Frame 첫 배포는 제외한다는 사용자 설명.",
|
|
21
|
+
"services": [{
|
|
22
|
+
"id": "office",
|
|
23
|
+
"server": {
|
|
24
|
+
"status": "required",
|
|
25
|
+
"cwd": "/확인한/office-api",
|
|
26
|
+
"config": "deploy.local.conf.server",
|
|
27
|
+
"sourceSha256": "현재 API 소스 SHA-256"
|
|
28
|
+
},
|
|
29
|
+
"frontend": {
|
|
30
|
+
"status": "required",
|
|
31
|
+
"cwd": "/확인한/office-web",
|
|
32
|
+
"config": "deploy.local.conf.front",
|
|
33
|
+
"sourceSha256": "현재 프론트 소스 SHA-256"
|
|
34
|
+
}
|
|
35
|
+
}, {
|
|
36
|
+
"id": "frame",
|
|
37
|
+
"server": {"status": "excluded", "reason": "not-live", "evidence": "첫 배포 전이며 이번 배포에서 제외한다는 사용자 설명"},
|
|
38
|
+
"frontend": {"status": "excluded", "reason": "not-live", "evidence": "동일한 미운영 서비스이며 이번 요청 제외"}
|
|
39
|
+
}]
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`sourceSha256`은 각 cwd에서 `node "$HOME/.agents/skills/scripts/deploy_db_preflight.mjs" --fingerprint`로 확인한다. DB 계약 등 변경을 마친 후에 계산한다. 제외 사유는 `user-excluded`, `not-live`, `not-applicable`이며 각각 실제 근거가 필요하다. 설정 없음·실행 실패·미확인은 제외로 처리할 수 없다.
|
|
44
|
+
|
|
45
|
+
## 실행과 검증
|
|
46
|
+
|
|
47
|
+
사용자가 해당 환경의 배포를 승인한 경우에만 실행한다. 이 도구는 승인 gate를 생략하지 않는다. npm publish는 서비스 API/프론트 집계 대상이 아니다.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
node "$HOME/.agents/skills/scripts/deploy_release.mjs" run --plan /확인한/배포-plan.json --receipt /확인한/새-run-receipt.json
|
|
51
|
+
node "$HOME/.agents/skills/scripts/deploy_release.mjs" verify --plan /확인한/배포-plan.json --receipt /확인한/새-run-receipt.json
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
- 모든 필수 config/source/SSH key 파일의 존재와 소스·환경·대상 식별을 먼저 확인한다. 누락이면 첫 wrapper 실행 전 차단한다. 상세 DB/readiness/runtime 검증은 기존 wrapper에서 유지한다.
|
|
55
|
+
- 실행 시작 전에 0600 receipt를 독점 생성한다. 기존 receipt 덮어쓰기와 과거 결과 재사용을 금지하며, 매 실행은 새로운 runId/receipt를 사용한다.
|
|
56
|
+
- 고정된 `deploy-server.sh`, `deploy-front.sh`만 순차 실행한다. manifest에 임의 command/hook/script를 넣을 수 없다. 중간 실패 시 이후 대상은 pending으로 남긴다.
|
|
57
|
+
- wrapper가 원격 transaction 성공까지 마친 뒤에만 고유 임시 경로에 0600 결과를 기록한다. coordinator는 exit 0과 이 결과의 runId/targetId/environment/source/config/destination/DB binding/artifact hash/검증 수준을 확인한다. build stdout의 DONE 문구나 과거 JSON만으로 성공 처리하지 않는다.
|
|
58
|
+
- 원격 hash/process/health 검증의 책임은 고정 wrapper에 있다. coordinator는 wrapper가 증명한 개별 결과를 집계하며 네트워크 검증을 중복 실행하지 않는다. fixture runner는 테스트 함수 주입만 지원하고 CLI override는 없다.
|
|
59
|
+
- 프론트 `.env.prod`의 실제 내용도 결과에 결합한다. 전체 실행 후 앞서 배포한 대상의 source/config/env도 재검사한다. 실행 도중 계획을 고치거나 동일 config를 다른 대상 결과에 대입하면 통과하지 않는다.
|
|
60
|
+
- 실패 로그 원문에는 credential이 있을 수 있어 receipt에 저장하지 않는다. 기록된 target/reason을 확인한 뒤 해당 wrapper의 원래 실패를 안전하게 조사한다. 조사 목적으로 운영 배포를 무작정 재실행하지 않는다.
|
|
61
|
+
|
|
62
|
+
## 결과 보고 계약
|
|
63
|
+
|
|
64
|
+
| 결과 | 의미 | 사용자 보고 |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| `DEPLOY_COMPLETE` + verify 통과 | 이번 실행의 모든 required 대상이 검증됨 | 대상별 성공과 명시 제외를 함께 보고 |
|
|
67
|
+
| `DEPLOY_PARTIAL` | 일부 배포했고 나머지는 실패/미실행/미확인 | `Office API 완료, Office 프론트 미배포/실패 — 부분 배포` |
|
|
68
|
+
| `DEPLOY_INCOMPLETE` | 성공 집계 불가 또는 선검사 차단 | 차단 대상/남은 대상과 사유 보고 |
|
|
69
|
+
| wrapper의 `RELEASE_COMPLETION_UNVERIFIED` | 개별 artifact 결과만 있음 | `API만 배포 완료, 전체 배포 미확인` |
|
|
70
|
+
|
|
71
|
+
완료 보고 직전에 같은 plan/receipt로 verify가 통과해야 한다. 필수 항목 하나라도 pending/running/blocked/failed/unverified이면 `전체 배포 완료`를 쓰지 않는다. receipt의 대상 목록을 생략하고 단일 API 결과를 전체 결과로 표현하지 않는다. HTTP/로그인 업무 검증은 별도로 표시하며 프론트 파일 health를 브라우저 smoke로 표현하지 않는다.
|
|
72
|
+
|
|
73
|
+
여러 서비스를 하나의 원자적 transaction으로 배포하는 도구는 아니다. 프론트 실패 시 이미 성공한 API를 자동으로 되돌리지 않으며, 부분 상태와 복구 필요성을 보고한다. 두 번째 DB 검증 뒤 동시 운영 변경, 최초 scope 누락, 악의적인 로컬 파일 변조까지 자동 방어한다고 주장하지 않는다. `verify`는 해당 실행의 기록과 입력 정합성을 검증하며 이후 원격 배포 상태가 계속 유지됨을 증명하지 않는다.
|
|
74
|
+
|
|
75
|
+
## 운영 배포 뒤 DB snapshot
|
|
76
|
+
|
|
77
|
+
- production plan에는 `snapshots` 배열이 필수다. 각 항목은 `targetId`(필수 배포 대상의 id)와 `databaseId`(해당 deploy DB 계약의 id)만 받는다. 임의 cwd, command, repository hook은 받지 않는다.
|
|
78
|
+
- 모든 필수 대상의 누적 DB 계약을 이 목록으로 덮어야 한다. API와 프론트가 동일 DB를 공유하면 하나의 source만 지정한다. source target의 `db/local/local-db-policy.json`, mask/verification SQL과 approved-plain opt-in이 준비돼 있어야 한다. 정책 부재/대상 불일치/누락은 첫 배포 전에 차단하며 임의로 policy를 생성하지 않는다. DB 없는 정적 frontend만 `snapshots: []`를 허용한다. 비운영에는 생략하거나 빈 배열만 허용한다.
|
|
79
|
+
- 순서: 모든 필수 wrapper 성공 → 현재 plan/receipt 검증 → 모든 server의 `process_and_http` 확인 → 모든 DB 관련 대상의 fresh schema/runtime 재조회 → 고정 `local_db_snapshot_publish.mjs --cwd <source target> --force --expected-source <검증 identity>` 실행 → 입력/DB 재확인.
|
|
80
|
+
- process-only 배포 자체는 기존대로 가능하지만 snapshot은 `DEPLOY_SNAPSHOT_READINESS_UNVERIFIED`로 보류한다. HTTP URL을 추정하지 않는다. HTTP/process/file 증거는 로그인 후 업무 저장·재조회 smoke를 대신하지 않는다.
|
|
81
|
+
- publisher의 두 private channel/OWNER/SELECT-only/masking/draft 검증은 유지한다. 각 channel의 실제 dump 직전에 같은 login-path와 명시 endpoint의 DB hostname/port/server-id/database/version/current-user를 대조하고 dump도 같은 endpoint로 고정한다. 정상 배포 시점의 새 snapshot을 위해 freshness no-op을 허용하지 않는다.
|
|
82
|
+
- 실패·부분 배포·rollback·누락·오래된 결과·환경/소스 불일치에서는 publisher를 호출하지 않는다. snapshot은 CLI `run` 안에서만 수행하며 `verify`는 재게시하지 않는다. 같은 receipt 재실행도 금지한다.
|
|
83
|
+
- 배포 상태와 `snapshots.status`를 분리한다. `DEPLOY_COMPLETE + PUBLISHED`가 배포 후 snapshot까지 완료된 상태다. 게시 실패는 `DEPLOY_COMPLETE + FAILED`이며 종료 코드 2를 반환하고 운영 artifact를 자동 rollback하지 않는다. 이미 발급된 channel이 있을 수 있으므로 실패 후 무조건 재시도하지 않고 receipt와 private Release 상태를 확인한다. 비운영은 `NOT_PRODUCTION`, DB 없는 frontend는 `NOT_APPLICABLE`이다.
|
|
84
|
+
- 기존 새벽 예약 publisher는 그대로 유지한다. 이 단계는 기존 자동화의 두 exact private Release channel에 추가되는 배포 후 발급이며 다른 목적지나 수동 plain 파일 전달을 허용하지 않는다.
|
|
85
|
+
- 배포·DB·두 channel은 하나의 원자적 transaction이 아니다. 발급 도중 외부 DDL/배포가 발생하면 사후 재조회로 완료를 차단해도 이미 게시된 channel이 있을 수 있다. 이 경우 결과를 확인해 복구하며 production lock/DDL이나 자동 artifact rollback으로 해결하지 않는다.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# 배포 전 누적 DB 구조 확인
|
|
2
|
+
|
|
3
|
+
## 막아야 하는 실패
|
|
4
|
+
|
|
5
|
+
마지막 IP 정책 커밋에 DDL이 없더라도 새 JAR가 사용하는 이전 기능의 테이블·컬럼이 운영 DB에 없으면 배포할 수 없다. `DEPLOY_DB_IMPACT_STATUS=none`, SQL 파일 존재, migration 이력, local DB 성공, JAR 기동, HTTP 200은 운영 DB 반영 증거가 아니다.
|
|
6
|
+
|
|
7
|
+
서버/프론트 wrapper는 build 전에 검사하고, build 후 최초 SSH staging/upload 직전에 **새로 조회**한다. 누락·권한·연결·응답 해석 실패는 exit 2이며 upload/restart로 진행하지 않는다. 과거 receipt를 입력받아 DB 조회를 생략하는 옵션은 없다. npm package publish에는 이 서비스 구조 검사를 적용하지 않는다.
|
|
8
|
+
|
|
9
|
+
## Codex가 준비하는 순서
|
|
10
|
+
|
|
11
|
+
1. 배포 대상 소스 전체의 ORM mapping, repository/raw query, SQL/migration과 관련 API를 읽고 **현재 runtime이 요구하는 누적 구조**를 작성한다. 마지막 커밋 diff만 조사하지 않는다. 삭제/대체된 과거 DDL은 그대로 요구하지 않고 현재 요구사항으로 정리한다. 서버는 DB 영향 설정이 none이어도 구조 확인이 필수다.
|
|
12
|
+
2. 실제 배포 profile, 원격 app.env의 datasource override, secret 참조를 읽기 전용으로 확인하여 어떤 DB를 사용하는지 확정한다. 접속 host/port와 read-only current user는 아래 local target에, 기대 schema/server hostname/id/version은 버전 관리되는 계약에 기록한다. 검토한 원격 app.env와 datasource를 결정하는 외부 설정 파일의 경로를 `runtimeFiles`에 고정한다. wrapper가 두 번 모두 SSH read-only hash 조회로 실행 중 설정 변경을 탐지하며 설정 내용이나 raw hash는 출력/저장하지 않는다. 비밀 파일의 hash를 Git 계약에 넣지 않는다. app.env는 필수이고 파일 부재/변경은 차단한다. SSH host와 DB host는 다를 수 있다. local/옛 DB, 다른 환경의 동명 schema를 대신 조회하지 않는다. JDBC multi-host/proxy routing이나 복수 datasource 중 하나라도 대응을 확정하지 못하면 배포를 보류한다. 값은 추정하지 않는다.
|
|
13
|
+
3. 제품 루트의 `deploy.db-contract.json`을 작성/갱신한다. 기존 계약도 소스 전체 기준으로 누락을 검토한다. `runtimeEvidence`에 확인한 runtime 설정 위치/확인 근거를 적고, 비밀값은 넣지 않는다. 지원하지 않는 DB 엔진, 구조, 업무용 seed/backfill 검증이 있으면 `확인 불가`로 멈춘다. contract를 통과시키려고 요구항목을 삭제하거나 해시만 새로 채우지 않는다.
|
|
14
|
+
4. 아래 fingerprint 명령으로 현재 소스에 계약을 결합한다. fingerprint는 계약 파일 자체를 제외한 모든 tracked + untracked/non-ignored 파일 내용에 기반한다. 계약 내용과 config/target 내용 및 runtime 설정 hash는 별도 binding에 포함한다. 프론트는 ignored 상태인 `FRONT_DIR_ENV_FILE` 내용도 hash로 결합한다. Git 루트에서만 실행하며 symlink/submodule은 차단한다. build 입력을 ignored 디렉터리에 숨기지 않고, ignored 환경설정이 구조 요구를 바꾸면 계약에 반영한다. 계약은 Git tracked여야 하며(신규 파일은 Git index 등록 포함), 제품 코드와 계약은 함께 버전 관리하고 credential/target 파일은 ignored 상태로 둔다.
|
|
15
|
+
5. 기존 deploy wrapper를 실행한다. 누락이면 정확한 객체·SQL 파일·선행 순서·확인 SQL을 정리해 OWNER 수동 실행으로 넘긴다. Codex가 production DDL/DML을 실행하지 않는다. 사용자가 실행했다고 말해도 다시 live 구조를 확인해야 배포를 재개한다.
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
node "$HOME/.agents/skills/scripts/deploy_db_preflight.mjs" --cwd "$PWD" --fingerprint
|
|
19
|
+
node "$HOME/.agents/skills/scripts/deploy_db_preflight.mjs" --cwd "$PWD" --config ./deploy.local.conf.server --artifact server
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
확인되지 않은 필수 정보를 사용자에게 대신 명령을 치도록 넘기지 않는다. Codex가 기존 읽기 전용 credential/설정을 먼저 탐색하고 확인한다. 다만 SELECT-only 권한이나 실제 대상의 근거를 확보하지 못하면 안전하게 멈추며, 확인 실패를 DB 영향 없음으로 바꾸지 않는다.
|
|
23
|
+
|
|
24
|
+
## 계약 형식
|
|
25
|
+
|
|
26
|
+
아래는 형식 설명용이다. 이름/타입/default를 제품의 실제 소스와 metadata로 바꾼다. `sourceSha256`에 위 명령 결과를 넣는다. 모든 table에 `columns`, `indexes`, `foreignKeys` 배열이 필요하다. 배열은 **현재 전체 runtime에서 필요한 항목**을 담는다. 실제 DB의 추가 객체는 허용한다.
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"version": 1,
|
|
31
|
+
"artifact": "server",
|
|
32
|
+
"environment": "production",
|
|
33
|
+
"sourceSha256": "현재 소스의 SHA-256",
|
|
34
|
+
"mode": "required",
|
|
35
|
+
"review": {"scope": "cumulative-runtime", "evidence": "전체 repository/query/mapping/SQL 검토 근거"},
|
|
36
|
+
"deployment": {"host": "확인된-배포-host", "port": 22, "directory": "/opt/확인된-api"},
|
|
37
|
+
"runtimeFiles": [{"path": "/opt/확인된-api/app.env"}],
|
|
38
|
+
"databases": [{
|
|
39
|
+
"id": "primary",
|
|
40
|
+
"expectedTarget": {"database": "확인된_schema", "serverHostname": "확인된-db-hostname", "serverPort": 3306, "serverId": 1, "engineVersionPrefix": "확인된-버전-prefix"},
|
|
41
|
+
"runtimeEvidence": "실제 활성 profile 및 app.env datasource와 target의 대응을 확인한 근거",
|
|
42
|
+
"tables": [{
|
|
43
|
+
"name": "example_table",
|
|
44
|
+
"columns": [{"name": "id", "type": "bigint(20)", "nullable": false, "default": null, "extra": "auto_increment"}],
|
|
45
|
+
"indexes": [{"name": "PRIMARY", "unique": true, "columns": ["id"]}],
|
|
46
|
+
"foreignKeys": []
|
|
47
|
+
}]
|
|
48
|
+
}]
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
- 컬럼은 `COLUMN_TYPE`, `IS_NULLABLE`, `COLUMN_DEFAULT`, `EXTRA`를 정확히 비교한다. MariaDB의 문자열 `"NULL"`과 SQL NULL(`null`) 등 엔진별 표현도 추정 변환하지 않는다.
|
|
53
|
+
- BASE TABLE 존재를 확인하고 인덱스는 이름·unique·컬럼 순서·전체 컬럼 인덱스(`SUB_PART=null`)·오름차순(`COLLATION=A`)을 비교한다. prefix/expression/descending 등 이 형식으로 표현하지 못하는 필수 구조는 이 버전에서 지원하지 않으므로 누락시켜 통과하지 않는다.
|
|
54
|
+
- 외래키 항목은 `name`, `columns`, `referencedTable`, `referencedColumns`, `updateRule`, `deleteRule`을 사용한다. 참조 schema는 같은 DB로 제한하며 순서와 update/delete 동작을 비교한다.
|
|
55
|
+
- 데이터 seed/backfill, trigger/procedure/view 정의, CHECK 제약, 문자셋/collation 등의 전체 동등성을 증명하는 검사가 아니다. 필요한 별도 safe-read 확인이 남아 있으면 배포 완료로 처리하지 않는다.
|
|
56
|
+
- 프론트도 연결 API가 필요로 하는 DB 구조를 계약에 포함한다. DB/API 의존이 실제 없는 독립 정적 프론트만 `artifact: "frontend"`, `mode: "none"`, `noDatabaseReason`, `databases: []`와 누적 검토 근거를 사용한다. deployment는 NAS host/port/web root다. 서버에서 none은 차단한다.
|
|
57
|
+
|
|
58
|
+
## 로컬 대상 설정
|
|
59
|
+
|
|
60
|
+
서버/프론트 deploy config에 `DEPLOY_DB_TARGETS_FILE="./db-targets.local.json"`을 추가한다. JSON 배열은 계약의 모든 database id와 1:1로 대응해야 한다. 이 파일은 `.gitignore`에 추가한다. 사용자 비밀번호를 적지 않고 기존 MySQL login-path를 사용한다. 여기 값은 예시이며 실제 환경으로 자동 채우지 않는다.
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
[{
|
|
64
|
+
"id": "primary",
|
|
65
|
+
"loginPath": "codex-db-확인된-track",
|
|
66
|
+
"host": "확인된-db-host",
|
|
67
|
+
"port": 3306,
|
|
68
|
+
"currentUser": "확인된-reader@host"
|
|
69
|
+
}]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
mysql client는 PATH와 macOS 표준 mysql-client 경로에서 탐색한다. local JSON으로 임의 실행 파일을 지정할 수 없다. arbitrary shell command/SQL 파일/verification hook은 받지 않는다. SELECT-only 확인은 USAGE/SELECT/SHOW VIEW 외 privilege, grant option, 해석 불가 role grant를 거부한다. CLI에는 password를 넣지 않고 client stderr나 raw grants를 출력하지 않는다. 고정 metadata SELECT와 SHOW만 사용하며 client timeout/결과 제한이 있다. 타깃은 DATABASE(), @@hostname, @@port, CURRENT_USER(), @@server_id, VERSION()으로 확인한다.
|
|
73
|
+
|
|
74
|
+
## 결과와 한계
|
|
75
|
+
|
|
76
|
+
- `DB_SCHEMA_VERIFIED`: 계약의 구조를 해당 시점 실제 target에서 확인했다. sourceSha256/binding/checkedAt/database id를 보관한다. 이것만으로 전체 업무 동작을 보장하지 않는다.
|
|
77
|
+
- `DB_NOT_APPLICABLE_REVIEWED`: 독립 프론트의 DB 미사용 근거와 현재 소스 결합을 확인했다.
|
|
78
|
+
- `DB_SCHEMA_NOT_APPLIED`: 누락/불일치 객체 목록. OWNER 수동 SQL 적용 후 **동일 대상에서 새 조회**가 필요하다.
|
|
79
|
+
- `DB_PREFLIGHT_*`: 계약/소스/target/credential/조회 미확인. 배포 중단이며 운영 정상/DB 영향 없음으로 축소하지 않는다.
|
|
80
|
+
|
|
81
|
+
SQL 정적 해석으로 모든 동적 query를 자동 추론할 수 없으므로 **계약의 완전성과 실제 runtime 대상 연결은 Codex의 근거 검토 책임**이다. 검증기는 그 계약에 대한 실제 구조와 입력 신선도를 강제한다. 두 번째 조회 이후 동시 DBA 변경을 잠그지 않으므로 배포 중 schema 변경은 운영 절차에서 조정한다. HTTP 200·process/JAR hash와 DB 구조·업무 smoke 결과를 각각 보고한다.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# PR 병합 후 반영
|
|
2
|
+
|
|
3
|
+
`$sk-git`에서 OWNER가 현재 canonical 저장소 PR을 실제 병합한 뒤 수행한다. merge helper에 SQL이나 서버 실행을 넣지 않고, 검토한 canonical 코드에서 기존 DB/runtime/deploy 도구를 연결한다.
|
|
4
|
+
|
|
5
|
+
## 대상과 승인
|
|
6
|
+
|
|
7
|
+
- 기본 반영 대상은 병합된 변경에 필요한 managed local DB와 관련 로컬 API다. `병합만`/`원격 병합만`은 PR 검토·원격 병합만 수행하고 local add/commit/push, checkout 동기화, DB/API와 cleanup을 모두 제외한다. 이 경우 아래 실행 단계 없이 원격 결과와 제외 상태를 보고한다. `DB 제외`, `서버 제외`는 해당 단계만 제외하며 환경 지정 등 사용자의 명시 범위를 우선한다. 같은 local 작업을 재승인받지 않는다.
|
|
8
|
+
- 운영 API는 사용자가 운영 배포를 명시했거나 현재 세션에 그 승인이 있을 때만 [sk-deploy](../../skills/sk-deploy/SKILL.md)를 읽고 연결한다. `sk-git`만으로 운영 배포, tag/release/npm publish 권한을 만들지 않는다.
|
|
9
|
+
- PR 0건, held/pending만 있는 결과, contributor PR 생성, 일반 commit/push에는 이 단계를 자동 실행하지 않는다. 재개 요청은 이전 병합 receipt/미완료 단계와 현재 SHA를 재확인한다.
|
|
10
|
+
- Web/문서 전용 PR이면 DB/API 영향이 실제 있는지 확인한다. 관련 없으면 `해당 없음`으로 보고한다. 다른 저장소가 필요하면 manifest/문서로 관계와 checkout을 확인하되 다른 저장소의 PR 병합·코드 갱신·배포까지 확대하지 않는다. 의존 코드가 없으면 정확한 선행조건을 남긴다.
|
|
11
|
+
|
|
12
|
+
## 1. 반영할 코드 확정
|
|
13
|
+
|
|
14
|
+
1. PR별 diff, merge SHA, SQL/설정/API 변경, 선행 의존성을 확인한다. 여러 PR은 처리 결과를 확정한 뒤 최종 canonical SHA에서 후속 반영을 한 번 수행한다. 충돌 등으로 전체 Git 흐름이 blocked/pending이면 이전 PR이 일부 병합됐어도 후속 실행은 보류한다.
|
|
15
|
+
2. [원래 checkout 동기화](../setup/git-checkout-sync.md)의 시작 receipt를 재사용해 `--finish --published-sha <full-sha> --apply`를 수행한다. `sync_status=synced`, `local_head`, `remaining_paths=[]`를 확인한다. 파일 경로 기준으로 기존 작업을 보존하며 동기화 미완료이면 그 checkout의 SQL/API 실행을 보류한다.
|
|
16
|
+
3. 대상 API/DB의 project root, local profile, 실행 명령, SQL 순서와 검증 쿼리를 실제 프로젝트에서 확인한다. URL/포트/서비스명/SQL 적용 여부를 추정하지 않는다. 다른 작업의 dirty 코드가 섞인 상태로 병합 SHA가 실행됐다고 보고하지 않는다.
|
|
17
|
+
|
|
18
|
+
## 2. 필요한 managed local DB 반영
|
|
19
|
+
|
|
20
|
+
- [sk-local-db](../../skills/sk-local-db/SKILL.md)와 [DB 검증 실행](db-verification.md)을 읽는다. 명령은 Codex가 실행하며 사용자에게 터미널 작업을 넘기지 않는다.
|
|
21
|
+
- `sk db local status --cwd <제품 checkout> --json`으로 managed identity와 현재 상태를 확인한다. DB 사용 프로젝트에서 아직 준비되지 않았으면 `sk db local sync --cwd <제품 checkout> --json`의 setup-or-sync 경로로 준비한다. 정책이 없으면 임의로 만들지 않고 `LOCAL_DB_POLICY_MISSING`으로 보고한다.
|
|
22
|
+
- 이미 검증된 DB는 보존한다. PR 병합마다 snapshot을 교체하지 않는다. policy mismatch/recovery marker는 기존 local-db 복구 절차로 처리하며 compatible snapshot 부재, 인증/네트워크 실패를 성공으로 간주하지 않는다. 기존 fixture를 잃는 reset/restore를 임의로 수행하지 않는다.
|
|
23
|
+
- 최종 코드에 필요한 SQL과 그 선행조건을 현재 schema/data·프로젝트 검증 쿼리로 대조해 `이미 충족 / 적용 필요 / 판단 불가`로 나눈다. PR SQL뿐 아니라 누락된 선행 migration도 확인한다. `apply` helper에는 migration 이력/중복 실행 방지가 없으므로 파일 존재나 과거 성공 로그만으로 결정하지 않는다.
|
|
24
|
+
- `적용 필요`인 검토된 repo SQL만 의존 순서대로 `sk db local apply --cwd <제품 checkout> --file <repo SQL>`로 실행하고 각 파일 직후 검증 쿼리로 결과를 확인한다. rollback/verification SQL을 migration처럼 일괄 실행하지 않는다. backfill 등 비멱등 DML의 적용 여부가 불명확하면 재실행하지 않고 보류한다.
|
|
25
|
+
- 실패하면 dependent SQL/API 단계는 멈춘다. DDL 일부 적용 가능성을 남기고 현재 상태를 조회한 뒤 검토된 복구 경로로만 복구한다. 무조건 재시도/reset하지 않는다. 적용 파일과 사후 검증 결과를 기록한다.
|
|
26
|
+
- Production DB schema/data는 변경하지 않는다. 운영 반영에 선행 SQL이 필요하면 [sk-db](../../skills/sk-db/SKILL.md)에 따라 실행 파일·검증·위험·rollback을 준비해 OWNER 수동 실행으로 넘긴다. Local 적용 성공은 운영 DB 적용 증거가 아니다.
|
|
27
|
+
|
|
28
|
+
## 3. 로컬 API 반영과 사용자 테스트 준비
|
|
29
|
+
|
|
30
|
+
- 관련 API 변경 또는 DB 변경이 있고 로컬 API가 대상이면, 프로젝트에 있는 실제 local 실행 명령과 생성된 DB 설정을 사용한다. 공용 임의 restart 명령이나 startup migration을 만들지 않는다.
|
|
31
|
+
- [DB 검증 실행](db-verification.md)에 따라 정확한 실행 명령을 `managed-local` guard로 검사한 뒤 동일 cwd/profile/env에서 수행한다. DB를 사용하지 않는 API는 해당 프로젝트의 DB 없는 실행 근거를 확인한다. guard 미지원/실패를 다른 모드로 우회하지 않는다.
|
|
32
|
+
- 기존 프로세스는 PID/cwd/실행 파일/profile/포트가 이 checkout과 일치할 때만 기존 정상 종료 방식으로 재시작한다. 포트만 보고 다른 서버를 종료하거나 광범위한 `pkill`을 사용하지 않는다.
|
|
33
|
+
- 서버가 없으면 프로젝트의 기존 실행 방식으로 기동한다. 사용자 테스트용 서버는 smoke 뒤 종료하지 않고 유지하며 프로세스/세션과 접속 주소를 남긴다. 이는 sk-local-db의 일시적 smoke 후 종료 절차와 구분한다. 지속 실행을 지원하지 못하면 `기동 검증 성공, 테스트 서버 유지 미완료`로 보고한다.
|
|
34
|
+
- 실제 새 프로세스의 코드 경로/빌드 SHA 근거, local DB 연결, 확인된 health 또는 대표 read API 응답을 검증한다. health 성공을 기능 저장/재조회 성공으로 대체하지 않는다. DB 없는 빌드/단위 검증은 DB 준비 실패와 독립적으로 진행할 수 있다.
|
|
35
|
+
- 로컬 DB·API가 준비되면 사용자가 접속할 확인된 URL, 필요 권한/선행 데이터와 기능 테스트 순서를 안내한다. URL이나 로그인 흐름이 미확인이면 그 항목을 명시한다.
|
|
36
|
+
|
|
37
|
+
## 4. 승인된 운영 API 배포
|
|
38
|
+
|
|
39
|
+
- 운영이 대상일 때만 최종 canonical SHA와 대상 설정을 고정하고 기존 `deploy-server.sh` 경로로 한 번 배포한다. `$sk-git`+`$sk-deploy` 복합 호출에서도 같은 SHA를 두 번 배포하지 않는다.
|
|
40
|
+
- 로컬 단계 실패가 운영 배포의 DB/코드 선행조건을 대신 판정하지 않는다. 운영 배포는 별도 승인과 선행조건을 충족하면 진행할 수 있으며 실패한 로컬 단계는 결과에 남긴다.
|
|
41
|
+
- 운영 schema 의존성이 있으면 공통 safe-read 조건에서 실제 충족 여부를 확인한다. 미충족/미확인 상태에서는 새 API 배포를 보류하고 수동 SQL handoff를 제공한다. 운영 테스트 DML이나 deploy/startup migration은 실행하지 않는다.
|
|
42
|
+
- config/credential 누락은 `HANDOFF_CONFIGURED_DEPLOY_HOST`로 남긴다. 현재 배포 helper가 실제 제공한 artifact·재시작·검증 결과를 기록한다. 기동·HTTP·기능 검증을 구분하고 실행하지 않은 검증을 성공으로 보고하지 않는다.
|
|
43
|
+
|
|
44
|
+
## 5. 결과와 재개
|
|
45
|
+
|
|
46
|
+
- 원래 checkout 동기화 뒤 기존 cleanup 조건을 만족할 때만 완료 branch를 정리한다.
|
|
47
|
+
- [개발 내용과 테스트 안내](../templates/pr-test-guide.md)를 채팅 텍스트로 출력하고 실제 결과는 프로젝트의 `docs/changes`에 남긴다. 이 후속 단계의 완료 조건은 로컬 기록이며 별도 외부 게시를 요구하지 않는다.
|
|
48
|
+
- PR merge, checkout, local DB, local API, 운영 배포를 각각 `완료 / 이미 충족 / 해당 없음 / 사용자 제외 / 미완료(사유)`로 구분한다. 아직 수행하지 않은 단계는 미완료다. 요청 범위 중 미완료가 있으면 전체 완료라고 보고하지 않는다.
|
|
49
|
+
- 재개할 때 성공한 merge/SQL/deploy를 무조건 반복하지 않는다. SHA와 현재 DB/API 상태를 다시 확인해 남은 단계부터 진행한다.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# 서버 readiness 연결
|
|
2
|
+
|
|
3
|
+
## 기존 호출에 연결하는 위치
|
|
4
|
+
|
|
5
|
+
`deploy-server.sh`는 첫 positional 인자를 설정 파일 경로로 사용한다. 생략 시 cwd의 `./deploy.local.conf.server`다. guard/build/JAR glob도 대상 프로젝트 cwd를 사용하므로 config만 절대 경로로 넘기고 다른 cwd에서 실행하지 않는다.
|
|
6
|
+
|
|
7
|
+
다음은 **향후 승인된 배포 시의 기존 호출 형식**이며, 이 문서 확인 작업에서는 실행하지 않았다.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
cd <대상-프로젝트-루트>
|
|
11
|
+
bash "$HOME/.agents/skills/skills/sk-deploy/deploy-server.sh" ./deploy.local.conf.server
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
HTTP 검증을 추가할 때만 값을 같은 config 파일에 입력한다. `--readiness-url` 같은 CLI 옵션은 없으며, config parser가 변수 값을 다시 읽으므로 환경변수 prefix만으로 전달하지 않는다. 예를 들어 현재 확인한 두 파일의 위치는 `~/IdeaProjects/km-admin-api/deploy.local.conf.server`, `~/Documents/Codex/selink/slk-office-api/deploy.local.conf.server`다. 두 파일 모두 아직 readiness 값이 없으며 이번 조사에서 수정하지 않았다.
|
|
15
|
+
|
|
16
|
+
| 선택 HTTP 검증 설정 | 의미 |
|
|
17
|
+
|---|---|
|
|
18
|
+
| `SERVER_READINESS_URL` | 원격 서버 자신이 GET하는 전체 HTTP(S) URL. localhost 기준 HTTP 포트와 context path 포함. 인증정보를 URL에 넣지 않음 |
|
|
19
|
+
| `SERVER_READINESS_STATUS` | 기대하는 정확한 HTTP 상태. 현재 parser는 200~299만 허용하며 프로젝트의 정상 응답 근거로 지정 |
|
|
20
|
+
| `SERVER_READINESS_TIMEOUT_SECONDS` | 확인 제한 시간, 1~300 정수 초 |
|
|
21
|
+
| `SERVER_READINESS_INTERVAL_SECONDS` | 재확인 간격, 1~300 정수 초이고 timeout 이하 |
|
|
22
|
+
|
|
23
|
+
[템플릿](../../skills/sk-deploy/deploy.local.conf.template.server)의 200/60/2는 설정 예시다. 운영 URL이나 성공 기준으로 자동 확정하지 않는다. local deploy config의 `SERVER_PORT`는 SSH 포트이며 HTTP 포트로 재사용하면 안 된다.
|
|
24
|
+
|
|
25
|
+
## health 경로가 없는 서버
|
|
26
|
+
|
|
27
|
+
`SERVER_READINESS_URL`이 없거나 명시적으로 빈 값이면 기존 config 그대로 process-only 배포를 사용한다. 새 API·인증 변경·가짜 URL은 필요하지 않다. 이때 상태/timeout/interval 값은 사용하지 않으며 원격 curl도 필요하지 않다.
|
|
28
|
+
|
|
29
|
+
- JAR SHA-256, staging, 백업, lock, guarded restart, rollback은 그대로 수행한다.
|
|
30
|
+
- generated start가 2초 뒤 조기 종료를 확인하고, transaction은 정확한 Java 실행 파일 + `-jar <전체 JAR 경로>`와 PID 파일의 일치·생존을 확인한 뒤 2초 후 재확인한다.
|
|
31
|
+
- 성공 출력은 `DEPLOY_PROCESS_VERIFIED`, `readiness: APP_READINESS_UNVERIFIED`다. 포트·API·DB·업무 기능은 미확인이다.
|
|
32
|
+
- URL이 있으면 나머지 세 값이 필수다. malformed URL, 302/401 같은 상태, curl 실패, PID 소실/교체는 성공으로 처리하지 않는다. HTTP 응답 직후에도 같은 프로세스를 확인하며 실패 시 process-only로 내려가지 않는다.
|
|
33
|
+
- rollback도 같은 모드로 검증한다. 복구 성공은 원래 배포 실패를 바꾸지 않으며 process-only 복구도 앱 readiness 미확인을 함께 출력한다.
|
|
34
|
+
|
|
35
|
+
## 2026-10-05 로컬 코드 조사
|
|
36
|
+
|
|
37
|
+
### slk-office-api
|
|
38
|
+
|
|
39
|
+
확인 경로는 `~/Documents/Codex/selink/slk-office-api`다.
|
|
40
|
+
|
|
41
|
+
- `src/main/kotlin/kr/selink/skl/api/project/system/controller/SystemController.kt`: `@RequestMapping("/api/v1/system")` + `@GetMapping("/health")`. 정상 반환은 `status="UP"`, app/profile 값이며 예상 HTTP 상태는 200이다. 별도의 DB 조회나 의존 서비스 상태 검사는 없다.
|
|
42
|
+
- `base/config/SecurityConfig.kt`: 모든 요청 permitAll, HTTP Basic/form login 비활성화.
|
|
43
|
+
- `base/aop/SessionKeyAop.kt`: `/api/v1/system/health`는 제외 목록이며 health 메서드에 세션/역할 검사 annotation도 없다.
|
|
44
|
+
- `base/config/web/HeaderInterceptor.kt` 및 `base/vo/HeaderValue.kt`: 인증을 강제하지 않는다. `Km-User-Agent`가 없으면 UNKNOWN으로, 세션 헤더는 빈 값으로 처리한다.
|
|
45
|
+
- `src/main/resources/application.properties`: `server.port=${SERVER_PORT:5391}`. `application-local.properties`도 같다. 저장소의 main 설정에서 별도 servlet context path, server SSL, management port 설정은 발견하지 못했다.
|
|
46
|
+
|
|
47
|
+
따라서 **기본 설정 그대로 실행할 경우의 코드 기반 예시**는 다음과 같다. 실제 운영 주소 검증 결과가 아니다.
|
|
48
|
+
|
|
49
|
+
```env
|
|
50
|
+
# 운영 SERVER_PORT/context path/SSL override 확인 후에만 채택
|
|
51
|
+
SERVER_READINESS_URL=http://127.0.0.1:5391/api/v1/system/health
|
|
52
|
+
SERVER_READINESS_STATUS=200
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
현재 배포의 원격 디렉터리는 `/opt/skl-api`이며 generated start는 그곳의 `app.env`를 읽는다. 원격 `SERVER_PORT`, servlet context path, SSL 등 runtime override는 이번 로컬 조사로 확인할 수 없다. 이 health는 HTTP 응답 생존 확인에 해당하며 DB·업무 준비 완료를 증명하지 않는다. 배포 checker도 PID와 HTTP 상태만 검사하고 응답 body/DB 상태는 검사하지 않는다.
|
|
56
|
+
|
|
57
|
+
### km-admin-api
|
|
58
|
+
|
|
59
|
+
확인 경로는 `~/IdeaProjects/km-admin-api`다.
|
|
60
|
+
|
|
61
|
+
- `src/main/resources/application.properties`와 `application-local.properties`: `server.port=5390`.
|
|
62
|
+
- main controller·상수·README·start/restart 및 build manifest에서 health/readiness/liveness/ping 전용 경로와 Actuator 의존성을 찾지 못했다.
|
|
63
|
+
- SecurityConfig의 permitAll만으로 무인증 health가 있다고 판단할 수 없다. 전역 `HeaderInterceptor`가 `HeaderValue.from`을 호출하고 `Km-User-Agent`가 없거나 형식이 맞지 않으면 `unknown url` 예외를 던진다. 현재 GET metadata 메서드에도 세션 검사 annotation이 있다.
|
|
64
|
+
- 현재 원격 디렉터리는 `/opt/km-admin-api`다. 원격 `app.env`와 실제 운영 override는 확인하지 않았다.
|
|
65
|
+
|
|
66
|
+
`http://127.0.0.1:5390/actuator/health` 또는 로그인·업무 API를 대신 지정하지 않는다. health 경로 없이 process-only 모드를 사용하면 되며, 향후 HTTP 검증을 추가하려는 경우에만 적합한 endpoint를 별도로 확인한다. 이번 작업은 제품 API·인증 정책을 변경하지 않는다.
|
|
67
|
+
|
|
68
|
+
## 향후 HTTP 검증을 추가할 경우
|
|
69
|
+
|
|
70
|
+
두 프로젝트 모두 readiness URL 없는 기존 config로 process-only 배포를 사용할 수 있다. URL을 추가하려는 경우에만 원격 서버 내부에서 접근 가능한 실제 scheme·HTTP 포트·prefix와 정상 2xx 상태를 확인한다. 소스 예시는 운영 주소 검증 결과가 아니다.
|
|
71
|
+
|
|
72
|
+
비밀번호·토큰·SSH key·전체 app.env 내용은 필요하지 않다. 로컬 설정·코드만 읽었고 원격/외부 호출, 앱 실행, 배포를 하지 않았다. 두 제품 API와 인증·DB 계약, 실제 deploy config도 수정하지 않았다.
|
|
@@ -123,6 +123,7 @@
|
|
|
123
123
|
- PR merge는 OWNER가 현재 canonical repository에서 plain `$sk-git` 또는 `$sk-git PR #<number> 병합`을 호출한 턴에만 실행한다. plain 호출은 현재 저장소의 허용된 contributor PR을 발견·검토·순차 squash merge하고, 번호 지정 호출은 해당 PR 하나만 처리한다. 예약 자동 병합, 다른 저장소 일괄 조회/병합, NON_OWNER merge는 금지하며 GitHub OWNER credential과 ACL을 다시 확인한다.
|
|
124
124
|
- plain `$sk-git`은 local 변경 유무를 보기 전에 `sk git preflight --cwd "$PWD" --json`을 실행하고 PR scan receipt를 남긴다. 이전 개인 주소가 GitHub repository transfer redirect로 정확히 `selink-lab/<허용 repo>`에 resolve될 때만 canonical origin으로 인정하며 local remote URL은 자동 변경하지 않는다.
|
|
125
125
|
- `$sk-git`과 `$sk-deploy`가 같은 요청에 있으면 PR scan과 candidate별 merged/held 결과를 먼저 확정하고 canonical main을 fast-forward한 뒤 deploy를 시작한다. deploy 단독 호출에는 GitHub PR/identity gate를 추가하지 않는다.
|
|
126
|
+
- OWNER의 PR 병합 호출은 병합된 범위의 managed local DB 적용과 local API 기동·재시작을 포함한다. 구체적인 순서·사용자 제외·운영 배포 승인·부분 완료 처리는 [PR 병합 후 반영](../playbooks/git-post-merge.md)을 따른다. Production DB 수동 실행과 contributor 권한 경계는 유지한다.
|
|
126
127
|
- NON_OWNER의 `$sk-git`은 clean 상태에서만 개인 fork `origin` + `selink-lab` `upstream` topology를 확인하고, 병합 완료된 작업 branch 또는 local default branch를 `upstream/<default>`에 `--ff-only`로 맞춘다. reset/rebase/force push와 fork default push는 하지 않는다.
|
|
127
128
|
- 성공한 Git 흐름 뒤 `sk git cleanup`은 default 포함 여부와 exact SHA를 다시 증명한 non-default branch만 자기 `origin`과 local에서 정리한다. default/current/protected/active-worktree/SHA-mismatch/증거 불충분 branch는 `HELD`하며, OWNER는 contributor의 외부 fork branch를 삭제하지 않는다.
|
|
128
129
|
- `$sk-git`과 `sk guard git`은 로컬 `gh` session으로 OWNER를 재판정하지 않는다. canonical `main`/`master` push는 GitHub ACL이 OWNER credential만 승인하고, NON_OWNER는 개인 fork PR로 요청한다.
|