velogger 0.1.0__tar.gz

velogger-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,59 @@
+name: 🐛 버그 제보
+description: 명령이 문서와 다르게 동작하거나, 결과가 잘못 나올 때
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        제보 감사합니다. 붙여 넣는 내용에서 **토큰·쿠키·이메일 같은 개인정보는 지워 주세요.**
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: 영역
+      description: 어느 부분에서 문제가 생겼나요?
+      options:
+        - 로그인·세션 (login, whoami)
+        - 조회 (trending, search, post, user 등)
+        - 작성 (publish, like, comment 등)
+        - 요청 제한 (limits, RATE_LIMITED)
+        - CLI 출력·에러 형식
+        - 기타 / 잘 모르겠음
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: 무슨 일이 있었나요?
+      description: 기대한 결과와 실제 결과를 적어 주세요.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: 재현 방법
+      description: 문제를 일으키는 가장 짧은 명령.
+      placeholder: "velogger search fastapi --limit 3"
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: output
+    attributes:
+      label: 출력 또는 에러
+      description: stdout 결과나 stderr 의 에러 JSON. `--verbose` 로그가 있으면 함께 붙여 주세요. 토큰·쿠키·이메일은 지우세요.
+      render: shell
+    validations:
+      required: false
+
+  - type: input
+    id: versions
+    attributes:
+      label: 환경
+      description: "`velogger --version` 출력, Python 버전, 실행한 날짜. 비공식 API 라 날짜가 중요합니다."
+      placeholder: "velogger 0.1.0 (커밋 a1b2c3d), Python 3.11.6, 2026-10-18"
+    validations:
+      required: false

velogger-0.1.0/.github/ISSUE_TEMPLATE/chore.yml

@@ -0,0 +1,41 @@
+name: 🧹 잡무
+description: 의존성, 도구, 설정, 정리 — 동작 변화 없음
+labels: ["chore"]
+body:
+  - type: dropdown
+    id: kind
+    attributes:
+      label: 종류
+      options:
+        - 의존성 업데이트·고정
+        - 도구·CI
+        - 설정
+        - 리팩터링·정리
+        - 기타
+    validations:
+      required: true
+
+  - type: textarea
+    id: what
+    attributes:
+      label: 무엇을 해야 하나요?
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: 왜 지금 하나요?
+      description: |
+        그대로 두면 어떤 비용이 있나요? 보안 권고, 깨진 빌드, 단순한 정리
+        모두 괜찮은 이유입니다.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: impact
+    attributes:
+      label: 영향
+      options:
+        - label: CLI 출력 형식이나 명령·옵션이 바뀐다
+          required: false

velogger-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 질문·논의
+    url: https://github.com/Rukkakka/velogger/discussions
+    about: 사용법을 묻거나, 이슈를 올리기 전에 아이디어를 논의합니다.

velogger-0.1.0/.github/ISSUE_TEMPLATE/docs.yml

@@ -0,0 +1,30 @@
+name: 📝 문서
+description: 문서에 빠졌거나, 틀렸거나, 이해하기 어려운 부분이 있을 때
+labels: ["docs"]
+body:
+  - type: input
+    id: location
+    attributes:
+      label: 어디인가요?
+      description: 파일, 섹션, 또는 docstring.
+      placeholder: "README.md — 요청 제한 표"
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: 무엇이 틀렸거나 빠졌나요?
+      description: |
+        문서가 지금 뭐라고 하는지, 그게 왜 틀렸거나 낡았거나 따라가기
+        어려운지 적어 주세요.
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: 제안 문구
+      description: 선택 — 바뀌었으면 하는 문장을 적어 주세요.
+    validations:
+      required: false

velogger-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,40 @@
+name: ✨ 기능
+description: 새 명령, 옵션, 엔드포인트 제안
+labels: ["feature"]
+body:
+  - type: textarea
+    id: proposal
+    attributes:
+      label: 무엇이 있어야 하나요?
+      description: |
+        원하는 명령, 옵션, 엔드포인트를 설명해 주세요. 새 엔드포인트라면
+        확인한 요청·응답 예시를 함께 적어 주세요.
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: 왜 필요한가요?
+      description: 지금 명령으로는 할 수 없는 일이 무엇인가요?
+    validations:
+      required: true
+
+  - type: textarea
+    id: usage
+    attributes:
+      label: 사용 예
+      description: 생기면 쓰고 싶은 명령과 기대하는 출력을 적어 주세요.
+      render: shell
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: conventions
+    attributes:
+      label: 규약
+      options:
+        - label: 새 엔드포인트라면 references/provider-conventions.md 를 읽었다
+          required: false
+        - label: 출력이 바뀐다면 references/output-contract.md 를 읽었다
+          required: false

velogger-0.1.0/.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,30 @@
+name: ✅ 작업
+description: 버그·기능·문서·잡무 어디에도 속하지 않는 계획된 작업
+labels: ["task"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: 설명
+      description: 무엇을 해야 하나요?
+    validations:
+      required: true
+
+  - type: textarea
+    id: done
+    attributes:
+      label: 완료 조건
+      description: 끝났다는 걸 어떻게 알 수 있나요?
+      placeholder: |
+        - [ ] ...
+        - [ ] ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: 맥락
+      description: 관련 이슈, PR, 링크. 선택.
+    validations:
+      required: false

velogger-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## 요약
+
+<!-- 무엇을 왜 바꾸나요? 닫는 이슈를 적어 주세요. 예: "Closes #12" -->
+
+## 변경 종류
+
+<!-- 해당하는 것을 모두 체크하세요. -->
+
+- [ ] `fix` — 버그 수정
+- [ ] `feature` — 새 명령, 옵션, 엔드포인트
+- [ ] `docs` — 문서만
+- [ ] `chore` — 의존성, 도구, 설정, 정리
+- [ ] `task` — 그 밖의 작업
+
+## 영향 범위
+
+<!-- 예: src/velogger/service/posts.py, cli 출력. 문서·도구만 바꿨다면 "없음". -->
+
+## 어떻게 테스트했나요?
+
+<!-- 실제로 실행한 것을 적어 주세요. 실제 API 로 확인한 명령(CLI 직접 조회)을 먼저, 돌린 pytest 가 있으면 그다음에.
+     테스트를 추가했다면 드문 엣지케이스인지 핵심 동작인지 적어 주세요. "테스트 안 함"도 괜찮습니다 — 그렇다고 적어 주세요. -->
+
+## 체크리스트
+
+- [ ] [references/code-style.md](https://github.com/Rukkakka/velogger/blob/main/references/code-style.md) 를 따른다
+- [ ] 새로 만들거나 바꾼 엔드포인트가 [references/provider-conventions.md](https://github.com/Rukkakka/velogger/blob/main/references/provider-conventions.md) 를 따른다
+- [ ] 명령·옵션·출력 필드·에러 코드·요청 제한이 바뀌었다면 `docs/<source>.md`·`docs/common.md` 와 [references/output-contract.md](https://github.com/Rukkakka/velogger/blob/main/references/output-contract.md) 를 고쳤다
+- [ ] 명령을 추가·삭제했거나 에이전트가 틀리기 쉬운 해석 규칙이 바뀌었다면 `docs/llm.md` 를 고쳤다
+- [ ] 명령을 추가·삭제했다면 매일 API 감시 목록(`scripts/monitor/api_check.py` 의 `STEPS`, 감시하지 않으면 `NOT_MONITORED` 에 이유)도 고쳤다
+- [ ] 사용자에게 보이는 변경이면 `CHANGELOG.md` 의 `Unreleased` 에 적었다 ([쓰는 법](https://github.com/Rukkakka/velogger/blob/main/references/release.md#changelog-쓰는-법))
+- [ ] 모듈을 추가·이름 변경·삭제했다면 `AGENTS.md` 구조 표와 해당 `references/providers/<source>.md` 를 고쳤다
+- [ ] 새 픽스처와 diff 에 토큰·쿠키·이메일 같은 개인정보가 없다

velogger-0.1.0/.github/workflows/api-monitor.yml

@@ -0,0 +1,81 @@
+# 매일 새벽 velogger 의 로그인 없는 조회 명령을 실제로 불러 비공식 API 가 깨졌는지 본다 (scripts/monitor/api_check.py,
+# references/development.md '매일 API 감시'). 고장이면 api-broken 이슈를 열고(열려 있으면 댓글) 실행을 실패로 끝내 GitHub 이 메일로 알린다.
+# 요청 제한·서버 오류는 고장이 아니라 '확인 못 함'이고, 사흘 연속 그러면 api-blocked 이슈로 알린다.
+# 로그인·쓰기(publish·like·comment)는 부작용이 있고 CI 에 세션도 없어 감시에 넣지 않는다.
+# 감시 파일을 고친 PR 에서도 돌지만 이슈는 건드리지 않는다. CI(ci.yml)는 여전히 실제 API 를 부르지 않는다.
+# 잡 이름은 main 보호 규칙의 필수 검사가 아니다 (막힌 날에도 PR 을 머지할 수 있게). jibsa 의 감시를 옮겼다.
+name: API 감시
+
+on:
+  schedule:
+    # 한국 시간 매일 04:17. 정각은 예약 실행이 몰려 늦거나 빠진다
+    - cron: '17 19 * * *'
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'scripts/monitor/**'
+      - '.github/workflows/api-monitor.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: api-monitor-${{ github.ref }}
+
+jobs:
+  check:
+    name: 조회 명령 실제 호출
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      PYTHONUTF8: '1'
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.11'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # PyPI 릴리스가 아니라 이 커밋의 코드를, 편집 가능 설치가 아니라 설치본 그대로 본다
+      - run: pip install .
+      - run: python scripts/monitor/api_check.py run --out result.json
+      - uses: actions/upload-artifact@v7
+        with:
+          name: result
+          path: result.json
+          retention-days: 7
+
+  report:
+    name: 결과 정리
+    needs: check
+    # 조회 잡이 실패해도 정리한다 (결과 파일이 없으면 고장으로 본다)
+    if: always()
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      # 앞선 실행의 결과 파일을 내려받아 연속 확인 못 함을 센다
+      actions: read
+    env:
+      PYTHONUTF8: '1'
+      GH_TOKEN: ${{ github.token }}
+      GH_REPO: ${{ github.repository }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.11'
+      - uses: actions/download-artifact@v8
+        # 조회 잡이 실패해 결과 파일이 없어도 정리 단계는 돈다
+        continue-on-error: true
+        with:
+          name: result
+          path: results
+      - name: 표 남기기·이슈 고치기
+        run: python scripts/monitor/api_check.py report results/result.json ${{ github.event_name != 'pull_request' && '--issues' || '' }}
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: report
+          path: report.json
+          retention-days: 7

velogger-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+# PR 과 main push 마다 린트·타입 검사·전체 pytest·설치본을 확인한다. 배포(release.yml)도 이 워크플로를 불러 같은 검사를
+# 통과한 빌드만 올린다. 잡 이름은 main 보호 규칙의 필수 검사라 바꾸면 보호 규칙도 같이 고친다.
+# 테스트는 가짜 응답만 쓰고 실제 API 는 부르지 않는다 (references/development.md '검증과 테스트').
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: 린트·타입 검사
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.11'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e '.[dev]'
+      - run: ruff check
+      - run: mypy
+      - name: docs/llm.md 200줄 이하
+        run: |
+          lines=$(wc -l < docs/llm.md)
+          echo "docs/llm.md: ${lines}줄"
+          if [ "$lines" -gt 200 ]; then
+            echo "::error file=docs/llm.md::${lines}줄입니다. 200줄 이하로 줄이세요 (AGENTS.md '문서 갱신')"
+            exit 1
+          fi
+
+  test:
+    name: pytest (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # 지원하는 가장 낮은 버전과 최신 안정 버전
+        python: ['3.11', '3.14']
+    env:
+      # README 의 Windows 설정(setx PYTHONUTF8 1)과 같게 한다. macOS·Linux 는 원래 UTF-8 이다
+      PYTHONUTF8: '1'
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e '.[dev]'
+      - run: pytest
+
+  package:
+    name: 설치본 확인
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.11'
+      - run: pip install build twine
+      - run: python -m build
+      # README 가 PyPI 프로젝트 페이지에서 렌더링되는지 (상대 링크는 잡지 못한다)
+      - run: twine check --strict dist/*
+      # 편집 가능 설치와 달리 docs/llm.md·소스 문서를 패키지 안 사본으로 읽으므로 사본이 빠지거나 다르면 여기서 드러난다
+      - name: 새 가상환경에 설치해 실행
+        run: |
+          python -m venv "$RUNNER_TEMP/velogger-check"
+          "$RUNNER_TEMP/velogger-check/bin/pip" install dist/*.whl
+          "$RUNNER_TEMP/velogger-check/bin/velogger" --version
+          "$RUNNER_TEMP/velogger-check/bin/velogger" guide > "$RUNNER_TEMP/guide.md"
+          diff "$RUNNER_TEMP/guide.md" docs/llm.md
+          for topic in common velogger; do
+            "$RUNNER_TEMP/velogger-check/bin/velogger" guide "$topic" > "$RUNNER_TEMP/$topic.md"
+            diff "$RUNNER_TEMP/$topic.md" "docs/$topic.md"
+          done
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/

velogger-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+# v* 태그를 push 하면 PyPI 와 GitHub Release 로 배포한다 (references/release.md '릴리스 절차').
+# PyPI 는 API 토큰 없이 신뢰 게시(Trusted Publishing)로 올린다. pypi.org 의 게시자 설정은 프로젝트 velogger,
+# 저장소 Rukkakka/velogger, 워크플로 release.yml, 환경 pypi 이고 GitHub 환경 pypi 는 v* 태그에서만 배포를 받는다.
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  tag:
+    name: 태그 확인
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # 태그 커밋이 main 에 있는지 보려고 main 기록까지 받는다
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.11'
+      - name: 태그가 main 에 있고 pyproject.toml 버전·CHANGELOG 절과 맞는지
+        run: |
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_REF_NAME 이 main 에 없는 커밋을 가리킵니다. 태그는 머지 뒤 main 에만 단다"
+            exit 1
+          fi
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::태그 $GITHUB_REF_NAME 와 pyproject.toml 버전 $version 이 다릅니다"
+            exit 1
+          fi
+          if ! grep -q "^## $version — " CHANGELOG.md; then
+            echo "::error::CHANGELOG.md 에 '## $version — 날짜' 절이 없습니다"
+            exit 1
+          fi
+
+  ci:
+    name: CI
+    needs: tag
+    uses: ./.github/workflows/ci.yml
+
+  pypi:
+    name: PyPI 에 올리기
+    needs: ci
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/velogger/
+    permissions:
+      # 신뢰 게시의 OIDC 토큰
+      id-token: write
+    steps:
+      # CI 의 설치본 확인이 빌드·확인한 파일을 그대로 올린다
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub Release
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: CHANGELOG 의 그 버전 절로 Release 만들기
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v head="## $version " 'index($0, head) == 1 {f=1; next} /^## /{if (f) exit} f' CHANGELOG.md > "$RUNNER_TEMP/notes.md"
+          gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md" dist/*