@agentsmd/preset-github 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 이태경
+
+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

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @agentsmd/preset-github
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[`@agentsmd/cli`](https://www.npmjs.com/package/@agentsmd/cli)의 GitHub 프리셋입니다.
+
+```bash
+npx @agentsmd/cli init --preset git,github,typescript   # Git 규칙 + GitHub + 언어 규칙
+npx @agentsmd/cli init --preset github                  # GitHub 템플릿만
+```
+
+- 이슈 템플릿(기능·버그, 빈 이슈 막기)과 PR 템플릿
+- `docs/github.md`: gh 명령, 머지 방식·룰셋 설정, CI 연결 방법
+- CI 설정 파일은 설치하지 않습니다. GitHub를 써도 CI는 GitHub Actions, Jenkins 등 무엇이든 쓸 수 있어서, 연결 방법만 문서로 안내합니다.
+- Git 작업 규칙과 PR 규칙 검사 스크립트(`.githooks/check-pr`)는 [Git 프리셋](https://www.npmjs.com/package/@agentsmd/preset-git)을 함께 고르면 더해집니다.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * GitHub 저장소용 프리셋.
+ *
+ * 이슈·PR 템플릿과 GitHub 저장소 설정 안내를 담는다. CI 설정 파일은 넣지 않는다.
+ * GitHub를 쓰면서 CI는 Jenkins 등으로 돌리는 저장소도 있어서, CI는 사용자가 고르고 문서로만 연결 방법을 안내한다.
+ * Git 작업 규칙은 Git 프리셋을 함께 고르면 더해진다.
+ */
+export declare const githubPreset: {
+    name: string;
+    description: string;
+    filesDir: string;
+    docs: {
+        path: string;
+        when: string;
+    }[];
+    rules: string[];
+    nextSteps: string[];
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;CAWP,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from "node:url";
+/**
+ * GitHub 저장소용 프리셋.
+ *
+ * 이슈·PR 템플릿과 GitHub 저장소 설정 안내를 담는다. CI 설정 파일은 넣지 않는다.
+ * GitHub를 쓰면서 CI는 Jenkins 등으로 돌리는 저장소도 있어서, CI는 사용자가 고르고 문서로만 연결 방법을 안내한다.
+ * Git 작업 규칙은 Git 프리셋을 함께 고르면 더해진다.
+ */
+export const githubPreset = {
+    name: "github",
+    description: "GitHub 이슈·PR 템플릿, 저장소 설정 안내",
+    filesDir: fileURLToPath(new URL("../files", import.meta.url)),
+    docs: [{ path: "docs/github.md", when: "이슈·PR 작성, gh 명령, 저장소 설정, CI 연결" }],
+    rules: ["이슈와 PR은 `.github/`의 템플릿을 채워 만든다."],
+    nextSteps: [
+        "GitHub 저장소 설정에서 머지 방식을 'Allow merge commits'만 허용하세요. → docs/github.md",
+        "main 브랜치 룰셋을 만들고 CI 검사를 필수 체크로 거세요. → docs/github.md",
+        "GitHub Actions를 쓰면 PR마다 문서 지도를 검사하는 xoruddl/agentsmd-kit Action을 거세요. → docs/github.md",
+    ],
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,6BAA6B;IAC1C,QAAQ,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,gCAAgC,EAAE,CAAC;IAC1E,KAAK,EAAE,CAAC,kCAAkC,CAAC;IAC3C,SAAS,EAAE;QACT,uEAAuE;QACvE,sDAAsD;QACtD,wFAAwF;KACzF;CACe,CAAC"}

package/files/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,43 @@
+name: 버그
+description: 기대와 다르게 동작하는 문제
+title: '[Fix] '
+labels: [bug]
+body:
+  - type: textarea
+    id: actual
+    attributes:
+      label: 현상
+      description: 무엇이 잘못 동작하나. 화면 캡처, 로그, 오류 메시지가 있으면 붙인다
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: 재현 방법
+      placeholder: |
+        1.
+        2.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 기대 동작
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: 기기·브라우저·OS
+      description: 화면이나 클라이언트 문제일 때 적는다
+      placeholder: 예) iPhone 15 Safari, macOS Chrome
+  - type: dropdown
+    id: env
+    attributes:
+      label: 환경
+      options:
+        - 로컬
+        - 개발 서버
+        - 운영
+    validations:
+      required: true

package/files/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/files/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,28 @@
+name: 기능
+description: 기능 추가·변경, 리팩터링, 설정 등 버그가 아닌 작업
+title: '[Feat] '
+labels: [enhancement]
+body:
+  - type: textarea
+    id: background
+    attributes:
+      label: 배경
+      description: 왜 이 작업이 필요한가
+    validations:
+      required: true
+  - type: textarea
+    id: tasks
+    attributes:
+      label: 할 일
+      description: 커밋 단위로 나눈 작업 목록
+      value: |
+        - [ ]
+    validations:
+      required: true
+  - type: textarea
+    id: done
+    attributes:
+      label: 완료 조건
+      description: 무엇이 되면 이 이슈를 닫을 수 있나 (동작, 테스트 등)
+    validations:
+      required: true

package/files/.github/pull_request_template.md

@@ -0,0 +1,30 @@
+<!--
+작성 규칙: docs/git-conventions.md, docs/writing-style.md
+- 짧게, 사실만. 빈 섹션은 지운다.
+- 변경 파일 나열 금지.
+- 이 PR로 이슈가 끝나지 않으면 `Closes #` 줄을 지운다.
+-->
+
+Closes #
+
+## 변경 내용
+
+-
+
+## 확인 방법
+
+<!-- 실행한 검증, 추가·수정한 테스트, 확인한 동작 -->
+
+## 확인할 부분
+
+<!-- 리뷰어가 꼭 봐야 할 지점. 없으면 지운다 -->
+
+## 화면
+
+<!-- 화면이 바뀌었다면 변경 전·후 캡처. 없으면 지운다 -->
+
+## 체크리스트
+
+- [ ] PR 제목이 `[<타입>] <한국어 요약>` 형식이다 (예: `[Feat] 주문 취소 사유 필드 추가`)
+- [ ] 커밋 하나에 하나의 책임만 담았다
+- [ ] CI가 통과한다

package/files/docs/github.md

@@ -0,0 +1,102 @@
+# GitHub 사용법
+
+이 저장소는 GitHub에서 이슈·PR을 관리한다. 작업 흐름 자체는 Git 작업 규칙 문서를 따르고, 이 문서는 GitHub에서만 필요한 것을 적는다.
+
+## 템플릿
+
+| 파일 | 용도 |
+| --- | --- |
+| `.github/ISSUE_TEMPLATE/feature.yml` | 기능 이슈 |
+| `.github/ISSUE_TEMPLATE/bug.yml` | 버그 이슈 |
+| `.github/ISSUE_TEMPLATE/config.yml` | 빈 이슈를 막는다 |
+| `.github/pull_request_template.md` | PR 본문 |
+
+이슈는 템플릿 중 하나를 골라 채운다. PR 본문은 템플릿을 채우고, 이 PR로 이슈가 끝나면 `Closes #<이슈번호>`를 넣어 머지 시 이슈가 닫히게 한다.
+이슈·PR 제목은 `[<타입>] <요약>` 형식이다 (예: `[Feat] 주문 취소 사유 필드 추가`). 커밋 메시지(`feat: 요약`)와 다르다.
+
+## gh 명령
+
+```sh
+gh issue create --template feature.yml
+gh pr create --base main --title "[<타입>] <요약>" --body-file <본문 파일>
+gh pr view <PR번호> --json reviews,comments
+gh api repos/{owner}/{repo}/pulls/<PR번호>/comments
+```
+
+PR 리뷰를 확인할 때는 마지막 두 명령으로 리뷰와 줄 단위 코멘트를 모두 본다.
+
+## 저장소 설정
+
+사람이 GitHub 화면에서 한 번 설정한다.
+
+- **Settings → General → Pull Requests**: `Allow merge commits`만 켠다. squash·rebase 머지는 끈다.
+- **Settings → Rules → Rulesets**: `main`에 룰셋을 만든다.
+  - 삭제와 force push를 막는다.
+  - PR을 거쳐야 머지되게 한다.
+  - CI 검사를 필수 체크로 건다. PR 규칙 검사를 CI에 연결했다면 그 검사도 넣는다.
+
+## CI 연결
+
+이 프리셋은 CI 설정 파일을 설치하지 않는다. GitHub를 써도 CI는 GitHub Actions, Jenkins 등 무엇이든 쓸 수 있기 때문이다.
+GitHub Actions를 쓴다면 아래 두 워크플로를 만든다.
+
+### 문서 지도 검사
+
+문서를 손으로 더하거나 빼거나 옮겼을 때 `AGENTS.md`가 그대로 맞는지 PR마다 검사한다. 아래 파일을 `.github/workflows/agentsmd.yml`로 만든다.
+
+```yaml
+name: agentsmd
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  agentsmd:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: xoruddl/agentsmd-kit@v0
+```
+
+`agentsmd check`와 같은 것을 검사한다. 문서 지도 파일이나 문서 디렉터리 위치가 기본값과 다르면 `with:`로 넘긴다. 입력 이름은 `agentsmd check`의 옵션과 같다.
+
+```yaml
+- uses: xoruddl/agentsmd-kit@v0
+  with:
+    root: packages/web # 검사할 저장소 루트 (기본 .)
+    docs: guides # 문서 디렉터리 (기본 docs)
+```
+
+만든 뒤 룰셋의 필수 체크에 `agentsmd`를 추가한다.
+이 Action은 Docker 이미지(`ghcr.io/xoruddl/agentsmd`)로 돌므로 Linux 러너(`ubuntu-*`)에서만 쓸 수 있다. 호출한 job의 Node 설정에는 영향을 주지 않는다.
+GitLab CI·Jenkins에서 같은 이미지를 쓰는 방법은 Git 작업 규칙 문서의 "문서 지도 검사를 CI에 연결" 절에 있다.
+
+### PR 규칙 검사
+
+Git 프리셋의 PR 규칙 검사(`.githooks/check-pr`)를 함께 설치했다면, 아래 파일을 `.github/workflows/conventions.yml`로 만든다.
+
+```yaml
+name: Conventions
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions: {}
+
+jobs:
+  conventions:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # PR 제목은 작성자가 쓴 값이라 스크립트에 직접 넣지 않고 환경변수로 넘긴다
+      - run: .githooks/check-pr
+        env:
+          BRANCH: ${{ github.head_ref }}
+          TITLE: ${{ github.event.pull_request.title }}
+```
+
+만든 뒤 룰셋의 필수 체크에 `conventions`를 추가한다.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@agentsmd/preset-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "description": "GitHub 저장소용 AI 작업 지침 프리셋 (이슈·PR 템플릿, 저장소 설정·CI 연결 안내)",
+  "keywords": [
+    "agents.md",
+    "ai-agent",
+    "github",
+    "issue-template",
+    "pull-request-template"
+  ],
+  "homepage": "https://github.com/xoruddl/agentsmd-kit#readme",
+  "bugs": "https://github.com/xoruddl/agentsmd-kit/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xoruddl/agentsmd-kit.git",
+    "directory": "packages/preset-github"
+  },
+  "license": "MIT",
+  "author": "이태경 (https://github.com/xoruddl)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "files"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentsmd/core": "0.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
 }