@zalkera/cli 0.20.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Credium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @zalkera/cli
+
+터미널에서 쓰는 길. VS Code 를 쓰지 않거나, 스크립트·CI 에서 돌릴 때를 위한 것이다.
+
+```bash
+npx @zalkera/cli pull --site <사이트코드>      # 한 번만 쓸 때
+npm i -g @zalkera/cli && zalkera pull         # 자주 쓸 때 (명령은 `zalkera`)
+```
+
+> **상태: 한 바퀴가 돈다.** 받기 → 고치기 → 올리기 → 발행 → 되돌리기·버리기가 전부 선다.
+> 미리보기와 로컬 MCP 서버는 **아직 없다**.
+
+⚠ **이것은 `import` 하는 패키지가 아니다.** 사이트 프로젝트의 의존으로 넣지 마라 — 사람이
+터미널에서 치는 명령이다. 넣으면 그 `package.json` 이 사이트와 함께 올라가 **서버가 사이트를
+지을 때 이것까지 설치한다.** 소스가 `import` 하는 쪽은 `@zalkera/client` 이고 그것은 다른
+패키지다. (`zalkera status` 가 잘못 들어온 것을 짚어 준다.)
+
+⚠ **판이 VS Code 확장과 묶여 있다.** 서버의 최소판 게이트가 하나라 두 도구가 같은 판으로 간다.
+게이트에 걸리면 `npx @zalkera/cli@latest` 나 `npm i -g @zalkera/cli@latest` 로 나간다.
+
+## 지금 되는 것
+
+```
+zalkera login                  # 브라우저로 로그인 (사이트를 안 물어본다)
+zalkera pull --site <사이트코드>  # 빈 폴더에 처음 받을 때
+zalkera status                 # 이 폴더와 사이트가 어떻게 다른지
+zalkera pull                   # 이미 받은 폴더를 지금 판에 맞춘다
+zalkera push                   # 이 폴더에서 고친 것을 사이트 쪽에 올린다
+zalkera publish                # 올린 것을 새 버전으로 만든다(그래야 손님에게 보인다)
+zalkera rollback <판번호>        # 라이브를 그 버전으로 되돌린다
+zalkera discard                # 사이트 쪽에서 편집 중인 것을 버린다(판은 안 옮긴다)
+zalkera baseline               # 기준 기록만 다시 세운다(파일은 안 건드린다)
+zalkera logout
+```
+
+`--site` 는 **폴더가 소속을 모를 때만** 필요하다. 한 번 받으면 폴더가 그것을 기억한다.
+
+옵션: `--site <사이트코드>` · `--folder <경로>` · `--revision <판번호>` · `--label <이름>` ·
+`--discard-local` · `--overwrite-unseen` · `--discard-pending` · `--yes` · `--confirm 버립니다` ·
+`--verbose` · `--version` · `--help`
+
+## 아직 없는 것
+
+`preview` · 로컬 MCP 서버. 설계는 서 있고
+(`backend/doc/design/memos/184-local-source-sync.md`) 트랜치가 T4 부터다.
+
+**발행 전에 눈으로 확인하는 자리는 아직 콘솔이다.** `push` 로 올린 것은 사이트 쪽 「편집 중인 것」에
+얹힌 상태이고, 그것을 미리 보려면 콘솔의 미리보기를 써야 한다.
+
+## 받기가 무엇을 하고 무엇을 안 하나
+
+- **서버가 지운 파일은 이 폴더에서도 지운다.** 안 지우면 다음 올리기에서 그 파일이 되살아난다.
+- **이 폴더에만 있는 파일은 안 건드린다.** 기준 기록의 판에도 받을 판에도 없던 파일이 그것이다.
+- **고쳐 둔 것이 있으면 아무것도 하지 않고 멈춘다.** 진행하려면 `--discard-local` 을 붙이는데,
+  그때도 버리지 않고 **옆 폴더**(`../<폴더이름>.zalkera-saved/`)로 옮긴다.
+- **파일을 합치지 않는다.** 병합 기계는 짓지 않는다는 것이 설계 결정이다.
+- 중간에 끊겨도 **다시 실행하면 이어받는다.** 파일시스템에 트랜잭션이 없으므로 원자성이 아니라
+  **멱등 재실행**이 계약이다.
+
+## 올리기가 무엇을 하고 무엇을 안 하나
+
+- **한 번에 보낸다.** 나눠 보내면 사이트 쪽에 의도한 변경의 **반쪽이 걸린 상태**가 생기고, 그 사이
+  누가 발행하면 그 반쪽이 판이 된다. 그래서 상한을 넘으면 나누지 않고 **거절**한다 — 그때 길은
+  콘솔에서 소스를 통째로 올리는 것이다.
+- **사이트 쪽 편집이 건드린 파일 중 그 내용을 이 폴더가 안 들고 있는 것이 있으면 멈춘다.**
+  그대로 올리면 그 편집이 사라지는데, 「내가 읽은 값 위에 얹는가」라는 검사는 그것을 **못 막는다**.
+  진행하려면 `--overwrite-unseen`.
+  - 받기는 **판**을 받지 편집을 받지 않는다. 그래서 남이 콘솔에서 고쳐 둔 파일은 이 도구로는
+    내용을 가져올 수 없고, 명시 동의 없이는 못 올린다 — 그 편집을 콘솔에서 먼저 정리해 주세요.
+  - 내가 올린 편집은 다음 회차에 안 걸린다(사이트 쪽 내용이 곧 내 폴더의 내용이다).
+- **글자로 된 파일만 올린다.** 그림·글꼴·압축 파일이 바뀌었으면 거절한다 — 이 길로 보내면 조용히
+  망가지기 때문이다. 그때도 길은 콘솔의 소스 통째 올리기다.
+- **응답을 못 받으면 「올라갔는지 모른다」고 말한다.** 「아마 올라갔을 겁니다」라고 말하지 않는다.
+  다음에 다시 실행하면 사이트 쪽과 대조해 정리한다.
+- **안 올라가는 파일이 두 종류다.**
+  - 이 도구가 애초에 안 보는 것 — `.env*`·개인키·`node_modules/`·`.next/`·`dist/`. 목록에도 안 뜨고
+    「고친 것」으로도 안 세어진다. 환경변수는 콘솔의 환경변수 화면에서 관리한다.
+  - 사이트가 받지 않는다고 답한 것 — 빌드가 만드는 자리 따위. 그것만 **빼고 다시 보내고
+    이름을 말한다.**
+
+## 발행·되돌리기·버리기가 무엇을 하고 무엇을 안 하나
+
+- **`publish` 는 편집을 새 버전으로 만든다.** 올린 것만으로는 손님에게 안 보인다 — 이 동사가
+  그 자리다. 정적 사이트는 바로 보이고, Next 사이트는 다시 지은 뒤에 보인다.
+- **`rollback <판번호>` 는 라이브만 옮긴다.** 이 폴더의 파일은 **안 건드린다** — 맞추려면 `pull`.
+  되돌린 판과 폴더가 다르면 그 사실을 말한다(그 상태로 올리면 전부 나가기 때문이다).
+- **되돌릴 대상이 지금 켜진 버전이면 받지 않는다.** 그것은 되돌리기가 아니라 **버리기**다 —
+  한 동사에 두 일을 묶으면 사람이 무엇을 잃는지 모른 채 부르게 된다.
+- **`discard` 는 편집을 버린다.** 판은 안 옮긴다. 버리기 전에 **무엇이 걸려 있는지 보여 준다**:
+  - 이 폴더에서 올린 것과 같으면 — 버려도 이 폴더의 내용은 그대로다. `y` 로 확인한다.
+  - **이 폴더에 없는 편집**이 섞여 있으면 — 되찾을 방법이 없다. 그때는 한 글자로 안 되고
+    `버립니다` 를 직접 쳐야 한다. 모르면(서버를 못 읽으면) 이쪽으로 접는다.
+- 확인은 **보안 잠금이 아니라 실수 방지**다. 터미널이 아니면 묻지 않고 멈춘다 —
+  스크립트에서 쓰려면 `--yes` 나 `--confirm 버립니다` 를 붙인다.
+- ⚠ **게시 대기 AI 변경은 다른 자산이다.** 사이트 쪽에 그것이 걸려 있으면 세 동사 모두 서버가
+  따로 동의를 묻는다. `--discard-pending` 이 그 동의이고 — **쓴 크레딧은 돌아오지 않는다.**
+  우리가 보여 주는 목록에는 그 레일이 안 뜨므로, 그 동의는 서버 문면 그대로 옮겨 온다.
+  - `discard` 는 **편집만** 걸린 회차에도 서버가 확인을 한 번 더 요구한다. 그때는 방금 주신
+    `y`/`버립니다` 를 그대로 이어 붙인다 — 크레딧이 안 걸렸으니 다시 묻지 않는다.
+  - 다만 확인하시는 사이 사이트 쪽 편집이 달라졌으면 **아무것도 안 버리고** 멈춘다.
+    보여 드린 것과 버리는 것이 갈리면 안 되기 때문이다.
+- ⚠ **되돌리기는 원장을 되감지 않는다.** 되돌릴 대상이 마지막 버전이 아니면 사이트는 그 내용으로
+  **새 버전을 세워** 켠다 — 그래서 「5판으로 되돌렸습니다」 뒤에 켜진 번호가 10일 수 있다. 그때
+  그 사실을 함께 말한다.
+- ⚠ **편집이 걸려 있으면 되돌리기가 막힌다.** 사이트가 그것을 거절한다 — 먼저 `zalkera publish`
+  로 새 버전을 만들거나 `zalkera discard` 로 버려야 한다.
+  - 그 편집이 **옛 버전 위**에 있으면(그 사이 라이브가 옮겨진 경우) `publish` 쪽도 막힌다.
+    그때 남는 출구는 `zalkera discard` 다.
+- ⚠ **Next 사이트는 발행한 버전이 바로 켜지지 않는다** — 다시 짓는 동안 라이브는 이전 버전이다.
+  그 창에서 `push` 를 하면 「짓는 중이라 아직 올릴 수 없습니다」로 멈춘다. 기다렸다 올리면 된다.
+
+## 로그인 정보가 어디 있나 — 확장보다 약하다
+
+이 도구는 로그인 정보를 **컴퓨터의 파일에 평문으로** 둔다(`~/.config/zalkera/auth.json`, 권한 0600).
+그 컴퓨터를 쓸 수 있는 사람은 이 사이트를 고치고 배포할 수 있다.
+
+VS Code 확장은 OS 키체인을 쓴다 — 그쪽이 **엄밀히 더 강하다.** 여기 담기는 것은 갱신 토큰이라
+보관의 반경도 더 넓다. 키링 우선·평문 폴백이 지향점이고, 그 자리는 아직 비어 있다.
+
+요구사항: **Node.js 20+**. (확장으로 쓰면 Node 설치가 필요 없다 — VS Code 가 이미 싣고 있는 것을 쓴다.)
+
+판정과 통신은 [`@zalkera/devtools-core`](../core) 에 있다 — 확장과 CLI 가 같은 답을 내야 하기 때문이다. 이 패키지가 맡는 것은 인자 해석·출력, 그리고 **토큰 보관**이다(그 판정은 코어에 두면 「코어는 파일을 안 쓴다」는 약속이 코어 안에서 먼저 깨진다).
+
+## 라이선스
+
+MIT © Credium