tracker-boot-git-hooks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BeKind Labs, Inc.
+
+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,433 @@
+# tracker-boot-git-hooks
+
+コミットにストーリーIDが含まれているとき、プッシュ時にTracker Bootのストーリーへ自動でコメントを投稿します。  
+커밋에 스토리 ID가 포함된 경우, 푸시 시 Tracker Boot 스토리에 자동으로 댓글을 게시합니다。  
+Automatically posts a comment on a Tracker Boot story when you push a commit that references it.
+
+[日本語](#ja) · [한국어](#ko) · [English](#en)
+
+---
+
+<a id="ja"></a>
+## 日本語
+
+**必要環境:** Node.js ≥ 18、Git
+
+---
+
+### インストール
+
+```sh
+npm install -g tracker-boot-git-hooks
+```
+
+トラッキングしたいリポジトリ内で一度実行してください:
+
+```sh
+tracker-boot-git-hooks install
+```
+
+初回プッシュ時にTracker Boot APIキーの入力を求められます。グローバルgit設定（`~/.gitconfig`）に保存され、以降は聞かれません。
+
+新しいリポジトリからの初回プッシュ時には、そのリポジトリのプロジェクトIDの入力も求められます。そのリポジトリの`.git/config`にローカル保存されます。
+
+---
+
+### アップデート
+
+プッシュのたびに、フックはnpmレジストリを確認し、新しいバージョンが利用可能な場合はstderrに通知を表示します:
+
+```
+tracker-boot: アップデートがあります 1.2.0 (現在: 1.1.0)。実行: npm install -g tracker-boot-git-hooks
+```
+
+アップデートするには、2つのコマンドを実行します:
+
+```sh
+npm install -g tracker-boot-git-hooks
+tracker-boot-git-hooks install
+```
+
+`npm install -g`でCLIを更新し、`tracker-boot-git-hooks install`で各リポジトリのフックファイルを新しいバージョンに書き換えます。
+
+---
+
+### コミットでストーリーを参照する
+
+コミットメッセージの件名の任意の位置に、ストーリーID（9桁）を角括弧で囲んで記述します:
+
+```
+[#200022323] F-198B: ダンスのアニメーションを追加
+[finishes #200022323] fix redirect after login
+[fixes #200022323] typo
+[#200022323 delivered] ship feature
+```
+
+対応キーワード: `fixes`、`fixed`、`finish`、`finishes`、`finished`、`completes`、`completed`、`delivers`、`delivered` — またはキーワードなしでも使用可能です。キーワードはIDの前後どちらに置いても構いません。
+
+> **注意:** キーワードはコメントに含まれますが、現時点ではストーリーの状態を変更しません。
+
+1つのコミットで複数のストーリーを参照できます。それぞれのストーリーに個別のコメントが投稿されます。
+
+---
+
+### すでにpre-pushフックがある場合
+
+他のツールが`.git/hooks/pre-push`（または`.husky/pre-push`）を使用している場合、インストールは中断されます。対処法は2つあります:
+
+**方法A** — 置き換える。既存のフックを削除してから`install`を再実行します。
+
+**方法B** — 追記する。既存のフックの末尾に以下の行を追加します:
+
+```sh
+tracker-boot-git-hooks hook "$@"
+```
+
+---
+
+### デバッグ
+
+```sh
+TRACKER_DEBUG=1 git push
+```
+
+各ステップをstderrに出力します: プッシュ入力の生データ、検出されたコミット、抽出されたストーリーID、APIコールの内容。
+
+すでにプッシュ済みのコミットに対してフックを再実行するには:
+
+```sh
+echo "refs/heads/main $(git rev-parse HEAD) refs/heads/main $(git rev-parse HEAD~)" \
+  | TRACKER_DEBUG=1 sh .git/hooks/pre-push
+```
+
+---
+
+### 非標準のTracker Bootインスタンス
+
+ローカルまたはステージングインスタンスを使用している場合は、プッシュ前に`TRACKER_BASE_URL`を設定してください:
+
+```sh
+TRACKER_BASE_URL=https://trackerboot.staging.example.com git push
+```
+
+ベースURLに`/graphql`を自動的に付加します。
+
+フックを非標準インスタンスに恒久的に向けるには:
+
+```sh
+tracker-boot-git-hooks install --base-url https://trackerboot.staging.example.com
+```
+
+---
+
+### 既知の制限事項
+
+**コミットリンクはGitHubのみ対応。** リモートがGitHub URL（HTTPSまたはSSH）の場合のみ、コメントにハイパーリンク付きのコミットSHAが含まれます。その他のホスト（GitLab、Bitbucketなど）ではプレーンテキストで表示されます。
+
+**フックマネージャーはHuskyのみ検出。** lefthook、simple-git-hooks、その他のマネージャーを使用している場合、`install`では検出されません — 上記のセクションで紹介した`tracker-boot-git-hooks hook`アプローチを使用してください。
+
+**`tracker-boot-git-hooks hook`使用時はstdinが利用可能である必要があります。** 既存のフックでフック行の前にstdinを読み取るコマンドがある場合、gitのrefデータがすでに消費されてしまい、コミットが検出されません。ほとんどのフック（リンター、フォーマッターなど）はstdinを読み取らないため、実際にはほとんど問題になりません。
+
+**1コミットで複数のストーリーIDを参照した場合。** コミットが複数のストーリーを参照している場合、各ストーリーに同一のコメントが投稿されます — 他のストーリーIDを含む完全なコミット件名がそのまま引用されます。
+
+**キーワードはストーリーの状態を変更しません。** 上記のコミット書式セクションの注意を参照してください。
+
+---
+
+### 仕組み
+
+1. Gitはpre-pushフックを呼び出し、プッシュされるrefの範囲をstdin経由で渡します
+2. フックは新しいコミットに対して`git log`を実行し、各コミットメッセージからストーリーIDを抽出します
+3. 各ストーリーIDに対して、GraphQL APIを通じてTracker Bootにコミットへのリンクを含むコメントを投稿します
+
+フックはプッシュをブロックしません — APIに到達できない場合やエラーが返された場合でも、プッシュは続行され、エラーはstderrに出力されます。
+
+### TODO
+
+- [ ] 世界へのリリース 🌍
+- [ ] キーワードに基づくストーリー状態変更のサポート
+- [ ] より多くのGitホスティングプロバイダーのサポート（GitLab、Bitbucketなど）
+
+---
+
+<a id="ko"></a>
+## 한국어
+
+**필요 환경:** Node.js ≥ 18、Git
+
+---
+
+### 설치
+
+```sh
+npm install -g tracker-boot-git-hooks
+```
+
+추적하려는 저장소 안에서 한 번 실행하세요:
+
+```sh
+tracker-boot-git-hooks install
+```
+
+저장소에서 처음 푸시할 때 Tracker Boot API 키를 입력하라는 메시지가 표시됩니다。전역 git 설정（`~/.gitconfig`）에 저장되며 이후에는 묻지 않습니다。
+
+새로운 저장소에서 처음 푸시할 때는 해당 저장소의 프로젝트 ID도 입력하라는 메시지가 표시됩니다。해당 저장소의 `.git/config`에 로컬로 저장됩니다。
+
+---
+
+### 업데이트
+
+푸시할 때마다 훅이 npm 레지스트리를 확인하고, 새 버전이 있으면 stderr에 알림을 표시합니다:
+
+```
+tracker-boot: 업데이트 가능 1.2.0 (현재: 1.1.0). 실행: npm install -g tracker-boot-git-hooks
+```
+
+업데이트하려면 두 명령을 실행하세요:
+
+```sh
+npm install -g tracker-boot-git-hooks
+tracker-boot-git-hooks install
+```
+
+`npm install -g`로 CLI를 업데이트하고, `tracker-boot-git-hooks install`로 각 저장소의 훅 파일을 새 버전으로 다시 작성합니다。
+
+---
+
+### 커밋에서 스토리 참조하기
+
+커밋 제목의 어느 위치에나 스토리 ID（9자리）를 대괄호로 감싸서 작성합니다:
+
+```
+[#200022323] F-198B: ダンスのアニメーションを追加
+[finishes #200022323] fix redirect after login
+[fixes #200022323] typo
+[#200022323 delivered] ship feature
+```
+
+지원 키워드: `fixes`、`fixed`、`finish`、`finishes`、`finished`、`completes`、`completed`、`delivers`、`delivered` — 또는 키워드 없이도 사용 가능합니다。키워드는 ID 앞뒤 어디에나 올 수 있습니다。
+
+> **참고:** 키워드는 댓글에 포함되지만 현재는 스토리 상태를 변경하지 않습니다。
+
+하나의 커밋에서 여러 스토리를 참조할 수 있습니다。각 스토리에 개별 댓글이 게시됩니다。
+
+---
+
+### 이미 pre-push 훅이 있는 경우
+
+다른 도구가 `.git/hooks/pre-push`（또는 `.husky/pre-push`）를 사용 중이면 설치가 중단됩니다。두 가지 방법이 있습니다:
+
+**방법 A** — 교체하기。기존 훅을 삭제하고 `install`을 다시 실행합니다。
+
+**방법 B** — 추가하기。기존 훅의 맨 아래에 다음 줄을 추가합니다:
+
+```sh
+tracker-boot-git-hooks hook "$@"
+```
+
+---
+
+### 디버깅
+
+```sh
+TRACKER_DEBUG=1 git push
+```
+
+각 단계를 stderr에 출력합니다: 원시 푸시 입력、감지된 커밋、추출된 스토리 ID、수행된 API 호출。
+
+이미 푸시된 커밋에 대해 훅을 재실행하려면:
+
+```sh
+echo "refs/heads/main $(git rev-parse HEAD) refs/heads/main $(git rev-parse HEAD~)" \
+  | TRACKER_DEBUG=1 sh .git/hooks/pre-push
+```
+
+---
+
+### 비표준 Tracker Boot 인스턴스
+
+로컬 또는 스테이징 인스턴스를 사용하는 경우 푸시 전에 `TRACKER_BASE_URL`을 설정하세요:
+
+```sh
+TRACKER_BASE_URL=https://trackerboot.staging.example.com git push
+```
+
+베이스 URL에 `/graphql`을 자동으로 추가합니다。
+
+비표준 인스턴스를 영구적으로 가리키는 훅을 설치하려면:
+
+```sh
+tracker-boot-git-hooks install --base-url https://trackerboot.staging.example.com
+```
+
+---
+
+### 알려진 제한 사항
+
+**커밋 링크는 GitHub 전용입니다。** 리모트가 GitHub URL（HTTPS 또는 SSH）인 경우에만 댓글에 하이퍼링크된 커밋 SHA가 포함됩니다。다른 호스트（GitLab、Bitbucket 등）에서는 일반 텍스트로 표시됩니다。
+
+**훅 매니저는 Husky만 감지합니다。** lefthook、simple-git-hooks 또는 다른 매니저를 사용하는 경우 `install`이 감지하지 못합니다 — 위 섹션의 `tracker-boot-git-hooks hook` 방식을 사용하세요。
+
+**`tracker-boot-git-hooks hook` 사용 시 stdin이 사용 가능해야 합니다。** 기존 훅에서 훅 줄 이전에 stdin을 읽는 명령이 있으면 git의 ref 데이터가 이미 소비되어 커밋을 찾을 수 없습니다。대부분의 훅（린터、포매터 등）은 stdin을 읽지 않으므로 실제로는 거의 문제가 없습니다。
+
+**하나의 커밋에 여러 스토리 ID가 있는 경우。** 커밋이 여러 스토리를 참조하면 각 스토리에 동일한 댓글이 게시됩니다 — 다른 스토리 ID를 포함한 전체 커밋 제목이 그대로 인용됩니다。
+
+**키워드는 스토리 상태를 변경하지 않습니다。** 위의 커밋 형식 섹션의 참고 사항을 확인하세요。
+
+---
+
+### 작동 방식
+
+1. Git이 pre-push 훅을 호출하고 stdin을 통해 푸시되는 ref 범위를 전달합니다
+2. 훅이 새 커밋에 대해 `git log`를 실행하고 각 커밋 메시지에서 스토리 ID를 추출합니다
+3. 각 스토리 ID에 대해 GraphQL API를 통해 Tracker Boot에 커밋 링크가 포함된 댓글을 게시합니다
+
+훅은 절대 푸시를 차단하지 않습니다 — API에 연결할 수 없거나 오류가 반환되더라도 푸시는 진행되고 오류는 stderr에 출력됩니다。
+
+### TODO
+
+- [ ] 세상에 출시하기 🌍
+- [ ] 키워드를 기반으로 한 스토리 상태 변경 지원
+- [ ] 더 많은 Git 호스팅 제공업체 지원（GitLab、Bitbucket 등）
+
+---
+
+<a id="en"></a>
+## English
+
+**Requires:** Node.js ≥ 18, Git
+
+---
+
+### Installation
+
+```sh
+npm install -g tracker-boot-git-hooks
+```
+
+Then run this once inside any repo you want to track:
+
+```sh
+tracker-boot-git-hooks install
+```
+
+The first time you push from any repo, you'll be prompted for your Tracker Boot API key. It's saved to your global git config (`~/.gitconfig`) and never asked again.
+
+The first time you push from a *new* repo, you'll also be prompted for that repo's project ID. It's saved locally to that repo's `.git/config`.
+
+---
+
+### Updating
+
+Every push, the hook checks npm for a newer version. If one is available, it prints a nudge to stderr after posting comments:
+
+```
+tracker-boot: update available 1.2.0 (current: 1.1.0). Run: npm install -g tracker-boot-git-hooks
+```
+
+To update, run both commands:
+
+```sh
+npm install -g tracker-boot-git-hooks
+tracker-boot-git-hooks install
+```
+
+`npm install -g` updates the CLI, and `tracker-boot-git-hooks install` rewrites the hook file in each repo to pick up any changes to the hook template.
+
+---
+
+### Referencing a story in a commit
+
+Include the story ID (9 digits) in square brackets anywhere in your commit subject:
+
+```
+[#200022323] F-198B: ダンスのアニメーションを追加
+[finishes #200022323] fix redirect after login
+[fixes #200022323] typo
+[#200022323 delivered] ship feature
+```
+
+Supported keywords: `fixes`, `fixed`, `finish`, `finishes`, `finished`, `completes`, `completed`, `delivers`, `delivered` — or no keyword at all. The keyword may appear before or after the ID.
+
+> **Note:** Keywords are recognized but don't change story state yet. For now they're just included in the comment for context.
+
+A commit can reference multiple stories. Each gets its own comment.
+
+---
+
+### If you already have a pre-push hook
+
+If another tool already owns `.git/hooks/pre-push` (or `.husky/pre-push`), installation will stop and tell you. You have two options:
+
+**Option A** — Replace it. Remove the existing hook and re-run `install`.
+
+**Option B** — Append to it. Add this line to the bottom of your existing hook:
+
+```sh
+tracker-boot-git-hooks hook "$@"
+```
+
+---
+
+### Debugging
+
+```sh
+TRACKER_DEBUG=1 git push
+```
+
+Prints each step to stderr: the raw push input, commits found, story IDs extracted, and which API calls are made.
+
+To replay the hook against a commit you've already pushed:
+
+```sh
+echo "refs/heads/main $(git rev-parse HEAD) refs/heads/main $(git rev-parse HEAD~)" \
+  | TRACKER_DEBUG=1 sh .git/hooks/pre-push
+```
+
+---
+
+### Non-standard Tracker Boot instance
+
+If you're running a local or staging instance, set `TRACKER_BASE_URL` before pushing:
+
+```sh
+TRACKER_BASE_URL=https://trackerboot.staging.example.com git push
+```
+
+The hook appends `/graphql` to the base URL automatically.
+
+To install a hook permanently pointed at a non-standard instance:
+
+```sh
+tracker-boot-git-hooks install --base-url https://trackerboot.staging.example.com
+```
+
+---
+
+### Known limitations
+
+**Commit links are GitHub-only.** The comment includes a hyperlinked commit SHA when the remote is a GitHub URL (HTTPS or SSH). For other hosts (GitLab, Bitbucket, etc.) the SHA appears as plain text.
+
+**Hook manager detection is Husky-only.** If you use lefthook, simple-git-hooks, or another manager, `install` won't detect it — use the `tracker-boot-git-hooks hook` approach from the section above instead.
+
+**Stdin must be available when using `tracker-boot-git-hooks hook`.** If another command in your existing hook reads stdin before the hook line, git's ref data will already be consumed and no commits will be found. Most hooks (linters, formatters) don't read stdin, so this is rarely an issue in practice.
+
+**Multiple story IDs in one commit.** When a commit references more than one story, each story gets an identical comment — the full commit subject, including the other story IDs, quoted verbatim.
+
+**Keywords don't change story state.** See the note in the commit format section above.
+
+---
+
+### How it works
+
+1. Git calls the pre-push hook and passes the ref ranges being pushed via stdin
+2. The hook runs `git log` over the new commits and extracts story IDs from each commit message
+3. For each story ID, it posts a comment to Tracker Boot via the GraphQL API with a link to the commit
+
+The hook never blocks a push — if the API is unreachable or returns an error, the push goes through and the error is printed to stderr.
+
+### TODO
+
+- [ ] Release to the world 🌍
+- [ ] Support story state changes based on keywords
+- [ ] Support more Git hosting providers (GitLab, Bitbucket, etc.)

package/bin/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { readFileSync } from 'fs'
+import { spawnSync } from 'child_process'
+import { install } from '../src/installer.js'
+import { buildHookScript } from '../src/hookTemplate.js'
+import { detectLang, t } from '../src/i18n.js'
+import { runHook } from '../src/hook.js'
+import { resolveUrls, DEFAULT_BASE_URL } from '../src/urls.js'
+import boxen from 'boxen'
+
+const args = process.argv.slice(2)
+const subcommand = args[0]
+
+if (subcommand === 'hook') {
+  if (process.stdin.isTTY) {
+    process.stderr.write('tracker-boot-git-hooks: "hook" must be called by git (stdin must be a pipe).\n')
+    process.exit(1)
+  }
+  const stdin = readFileSync('/dev/stdin', 'utf8')
+  const baseUrl = process.env.TRACKER_BASE_URL ?? DEFAULT_BASE_URL
+  // Git passes the remote name as $1 and remote URL as $2 to the pre-push hook
+  const remoteName = args[1] ?? null
+  const remoteUrl = args[2] ?? null
+
+  runHook({
+    stdin,
+    ...resolveUrls(baseUrl),
+    remoteName,
+    remoteUrl,
+  }).catch((err) => {
+    process.stderr.write(`tracker-boot-git-hooks: unexpected error: ${err.message}\n`)
+  })
+} else if (subcommand === 'install') {
+  const baseFlagIndex = args.indexOf('--base-url')
+  const baseUrl = baseFlagIndex !== -1 ? args[baseFlagIndex + 1] : DEFAULT_BASE_URL
+
+  if (!baseUrl) {
+    process.stderr.write('Error: --base-url requires a value.\n')
+    process.exit(1)
+  }
+
+  function getRepoRoot() {
+    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' })
+    if (result.status !== 0) return null
+    return result.stdout.trim()
+  }
+
+  const lang = detectLang(process.env.LANG)
+  const repoRoot = getRepoRoot()
+  if (!repoRoot) {
+    process.stderr.write('Error: not inside a git repository.\n')
+    process.exit(1)
+  }
+  const hookScript = buildHookScript({ baseUrl })
+
+  let result
+  try {
+    result = install({ repoRoot, hookScript })
+  } catch (err) {
+    if (err.code === 'HOOK_EXISTS') {
+      const [title, ...bodyLines] = t('hookExistsError', lang, { path: err.path }).split('\n')
+      process.stderr.write('\n' + boxen(bodyLines.join('\n').trim(), {
+        title,
+        titleAlignment: 'center',
+        padding: 1,
+        borderStyle: 'double',
+        borderColor: 'red',
+      }) + '\n\n')
+      process.exit(1)
+    }
+    process.stderr.write(`Error: ${err.message}\n`)
+    process.exit(1)
+  }
+
+  if (result.warning) {
+    process.stdout.write(`\nWarning: ${result.warning}\n`)
+  }
+
+  if (result.method === 'direct') {
+    process.stdout.write(`\nhook installed\n`)
+  } else if (result.method === 'husky') {
+    process.stdout.write(`\nhook installed at .husky/pre-push\n`)
+    process.stdout.write(`Next: ${result.reminder}\n`)
+  }
+} else {
+  process.stderr.write(`Usage: tracker-boot-git-hooks <install [--base-url <url>] | hook>\n`)
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "tracker-boot-git-hooks",
+  "version": "0.1.0",
+  "description": "Git hooks for Tracker Boot — automatically comments on stories when commits are pushed",
+  "type": "module",
+  "bin": {
+    "tracker-boot-git-hooks": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Bekind-Labs/tracker-boot-git-hooks.git"
+  },
+  "homepage": "https://github.com/Bekind-Labs/tracker-boot-git-hooks#readme",
+  "keywords": [
+    "git",
+    "hooks",
+    "pre-push",
+    "tracker",
+    "tracker-boot"
+  ],
+  "author": "BeKind Labs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": ["darwin", "linux"],
+  "dependencies": {
+    "boxen": "^8.0.1"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0"
+  }
+}

package/src/apiClient.js

@@ -0,0 +1,78 @@
+import { randomUUID } from 'crypto'
+
+const CREATE_COMMENT_MUTATION = `
+mutation ExecuteCommentCreate(
+  $projectId: ID!
+  $commandId: ID!
+  $storyId: ID!
+  $content: String!
+) {
+  executeCommand(
+    input: {
+      projectId: $projectId
+      version: 1
+      commandId: $commandId
+      type: COMMENT_CREATE
+      parameters: { storyId: $storyId, content: $content, attachments: [] }
+    }
+  ) {
+    version
+    type
+    data {
+      __typename
+      ... on Comment {
+        id
+        storyId
+        content
+        user { id name avatarUrl }
+        createdAt
+        updatedAt
+      }
+    }
+  }
+}
+`.trim()
+
+function assertNoErrors(json) {
+  if (json.errors?.length) throw new Error(json.errors[0].message)
+}
+
+async function graphqlPost(url, headers, body, timeoutMs = 5000) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  let res
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { ...headers, 'Content-Type': 'application/json' },
+      body,
+      signal: controller.signal,
+    })
+  } catch (err) {
+    throw new Error(err.name === 'AbortError' ? 'request timed out after 5s' : err.message)
+  } finally {
+    clearTimeout(timer)
+  }
+  if (!res.ok) {
+    const preview = await res.text().catch(() => '')
+    throw new Error(`HTTP ${res.status}${preview ? ': ' + preview.slice(0, 120) : ''}`)
+  }
+  const text = await res.text()
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`HTTP ${res.status}: non-JSON response`)
+  }
+}
+
+export async function createComment({ mutationUrl, apiKey, projectId, storyId, content, timeoutMs }) {
+  const variables = { projectId, commandId: randomUUID(), storyId, content }
+  const json = await graphqlPost(
+    mutationUrl,
+    { 'Authorization': `Bearer ${apiKey}` },
+    JSON.stringify({ query: CREATE_COMMENT_MUTATION, variables }),
+    timeoutMs
+  )
+  assertNoErrors(json)
+  return json.data
+}

package/src/commentBuilder.js

@@ -0,0 +1,29 @@
+const GITHUB_HTTPS = /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/
+const GITHUB_SSH = /^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/
+
+function parseGitHubCommitUrl(remoteUrl, sha) {
+  if (!remoteUrl) return null
+  const m = remoteUrl.match(GITHUB_HTTPS) ?? remoteUrl.match(GITHUB_SSH)
+  if (!m) return null
+  return `https://github.com/${m[1]}/${m[2]}/commit/${sha}`
+}
+
+export function buildCommentContent(commit) {
+  const shortSha = commit.sha.slice(0, 7)
+  const commitUrl = parseGitHubCommitUrl(commit.remoteUrl, commit.sha)
+
+  const firstLine = commitUrl
+    ? `[${shortSha}](${commitUrl})`
+    : shortSha
+
+  const parts = [`${firstLine}\n\`${commit.subject}\``]
+
+  if (commit.body) {
+    const trimmedBody = commit.body.trimEnd()
+    if (trimmedBody) parts.push(trimmedBody)
+  }
+
+  parts.push('\n*posted via [Tracker Boot Git Hook](https://github.com/Bekind-Labs/tracker-boot-git-hooks)*')
+
+  return parts.join('\n')
+}

package/src/configManager.js

@@ -0,0 +1,22 @@
+import { spawnSync } from 'child_process'
+
+const SPAWN_OPTS = { encoding: 'utf8' }
+
+export function getConfig(key, { global: isGlobal = false, local: isLocal = false } = {}) {
+  let args
+  if (isGlobal) args = ['config', '--global', key]
+  else if (isLocal) args = ['config', '--local', key]
+  else args = ['config', key]
+  const result = spawnSync('git', args, SPAWN_OPTS)
+  return result.status === 0 ? result.stdout.trimEnd() : null
+}
+
+export function setGlobalConfig(key, value) {
+  const r = spawnSync('git', ['config', '--global', key, value], SPAWN_OPTS)
+  if (r.status !== 0) throw new Error(`git config --global ${key}: ${(r.stderr ?? '').trim()}`)
+}
+
+export function setLocalConfig(key, value) {
+  const r = spawnSync('git', ['config', key, value], SPAWN_OPTS)
+  if (r.status !== 0) throw new Error(`git config ${key}: ${(r.stderr ?? '').trim()}`)
+}

package/src/gitClient.js

@@ -0,0 +1,30 @@
+import { spawnSync } from 'child_process'
+
+export function getCommitsInRange(remoteSha, localSha, { remote } = {}) {
+  // When remoteSha is null the branch has no upstream yet — only walk commits
+  // not already reachable from the remote to avoid re-commenting on history.
+  const rangeArgs = remoteSha
+    ? [`${remoteSha}..${localSha}`]
+    : [localSha, '--not', remote ? `--remotes=${remote}` : '--remotes']
+  const result = spawnSync(
+    'git',
+    // --format= (tformat:) appends \n after each entry; the parser's .trim() calls rely on this
+    ['log', ...rangeArgs, '--format=%H%x00%s%x00%b%x00'],
+    { encoding: 'utf8' }
+  )
+  if (result.status !== 0) {
+    throw new Error(`git log failed: ${(result.stderr ?? '').trim()}`)
+  }
+  const raw = result.stdout ?? ''
+  if (!raw.trim()) return []
+
+  const tokens = raw.split('\x00')
+  const commits = []
+  for (let i = 0; i + 2 < tokens.length; i += 3) {
+    const sha = tokens[i].trim()
+    const subject = tokens[i + 1].trim()
+    const body = tokens[i + 2].trim()
+    if (sha) commits.push({ sha, subject, body })
+  }
+  return commits
+}

package/src/hook.js

@@ -0,0 +1,120 @@
+import readline from 'readline'
+import { createReadStream } from 'fs'
+import { getConfig, setGlobalConfig, setLocalConfig } from './configManager.js'
+import { createComment } from './apiClient.js'
+import { parsePushInput } from './pushInputParser.js'
+import { getCommitsInRange } from './gitClient.js'
+import { buildCommentContent } from './commentBuilder.js'
+import { extractStoryIds } from './storyIdExtractor.js'
+import { detectLang, t } from './i18n.js'
+import { checkForUpdate } from './updateChecker.js'
+
+function debug(msg) {
+  if (process.env.TRACKER_DEBUG) {
+    process.stderr.write(`[tracker-boot debug] ${msg}\n`)
+  }
+}
+
+function openTtyPrompt(question) {
+  return new Promise((resolve, reject) => {
+    const tty = createReadStream('/dev/tty')
+    tty.on('error', (err) => {
+      reject(new Error(`Interactive setup required — run git push from a terminal first (${err.message})`))
+    })
+    const rl = readline.createInterface({ input: tty, output: process.stderr })
+    rl.question(question, (answer) => {
+      rl.close()
+      tty.destroy()
+      resolve(answer.trim())
+    })
+  })
+}
+
+async function ensureCredentials({ lang, deps }) {
+  let apiKey = deps.getConfig('tracker.apiKey', { global: true })
+  let projectId = deps.getConfig('tracker.projectId', { local: true })
+
+  if (!apiKey) {
+    apiKey = await deps.prompt(t('promptApiKey', lang))
+    deps.setGlobalConfig('tracker.apiKey', apiKey)
+    process.stderr.write(t('apiKeyStored', lang) + '\n')
+  }
+
+  if (!projectId) {
+    projectId = await deps.prompt(t('promptProjectId', lang))
+    deps.setLocalConfig('tracker.projectId', projectId)
+    process.stderr.write(t('projectIdStored', lang) + '\n')
+  }
+
+  return { apiKey, projectId }
+}
+
+export async function runHook({ stdin, mutationUrl, remoteName, remoteUrl }, inject = {}) {
+  const lang = detectLang(process.env.LANG)
+  const deps = {
+    getConfig,
+    setGlobalConfig,
+    setLocalConfig,
+    createComment,
+    getCommitsInRange,
+    prompt: openTtyPrompt,
+    checkForUpdate,
+    ...inject,
+  }
+
+  const updateCheck = deps.checkForUpdate()
+
+  debug(`stdin: ${JSON.stringify(stdin)}`)
+  debug(`mutationUrl: ${mutationUrl}`)
+
+  const ranges = parsePushInput(stdin)
+  debug(`parsed ${ranges.length} ref range(s): ${JSON.stringify(ranges)}`)
+
+  const work = []
+  for (const { localSha, remoteSha } of ranges) {
+    let commits
+    try {
+      commits = deps.getCommitsInRange(remoteSha, localSha, { remote: remoteName })
+    } catch (err) {
+      process.stderr.write(`tracker-boot-git-hooks: ${err.message}\n`)
+      continue
+    }
+    debug(`found ${commits.length} commit(s) in ${remoteSha}..${localSha}`)
+    for (const commit of commits) {
+      const text = commit.body ? `${commit.subject}\n${commit.body}` : commit.subject
+      const storyIds = extractStoryIds(text)
+      debug(`commit ${commit.sha}: subject="${commit.subject}" storyIds=${JSON.stringify(storyIds)}`)
+      for (const storyId of storyIds) {
+        work.push({ commit, storyId })
+      }
+    }
+  }
+
+  if (work.length === 0) return
+
+  let credentials
+  try {
+    credentials = await ensureCredentials({ lang, deps })
+  } catch (err) {
+    process.stderr.write(`tracker-boot-git-hooks: setup failed: ${err.message}\n`)
+    return
+  }
+  const { apiKey, projectId } = credentials
+  debug(`projectId: ${projectId}`)
+
+  for (const { commit, storyId } of work) {
+    const content = buildCommentContent({ ...commit, remoteUrl })
+    debug(`posting comment for story ${storyId}`)
+    try {
+      await deps.createComment({ mutationUrl, apiKey, projectId, storyId, content })
+      process.stderr.write(t('commentPosted', lang, { storyId }) + '\n')
+    } catch (err) {
+      process.stderr.write(t('apiError', lang, { storyId, message: err.message }) + '\n')
+    }
+  }
+
+  const update = await updateCheck
+  if (update) {
+    process.stderr.write(t('updateAvailable', lang, { latest: update.latest, current: update.current }) + '\n')
+  }
+}

package/src/hookTemplate.js

@@ -0,0 +1,24 @@
+import { createRequire } from 'module'
+import { OUR_MARKER } from './installer.js'
+
+const require = createRequire(import.meta.url)
+
+function shellQuote(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`
+}
+
+function getVersion() {
+  return require('../package.json').version
+}
+
+export function buildHookScript({ baseUrl }) {
+  const version = getVersion()
+  return [
+    '#!/bin/sh',
+    `${OUR_MARKER} pre-push hook (version: ${version})`,
+    `# To update: npm install -g tracker-boot-git-hooks && tracker-boot-git-hooks install`,
+    `# Override with TRACKER_BASE_URL env var.`,
+    `TRACKER_BASE_URL=${shellQuote(baseUrl)} \\`,
+    `  tracker-boot-git-hooks hook "$@"`,
+  ].join('\n') + '\n'
+}

package/src/i18n.js

@@ -0,0 +1,44 @@
+const MESSAGES = {
+  en: {
+    promptApiKey: 'Enter your tracker-boot API key: ',
+    promptProjectId: 'Enter your tracker-boot project ID for this repo: ',
+    apiKeyStored: 'API key saved to global git config (tracker.apiKey).',
+    projectIdStored: 'Project ID saved to local git config (tracker.projectId).',
+    apiError: 'tracker-boot: failed to post comment for story {storyId}: {message}',
+    commentPosted: 'tracker-boot: comment posted on story {storyId}.',
+    hookExistsError: '🚫  Hook conflict — installation aborted  🚫\nA pre-push hook already exists at:\n  {path}\n\nRemove it first, then re-run:\n  tracker-boot-git-hooks install\n\nOr append to your existing hook:\n  tracker-boot-git-hooks hook "$@"',
+    updateAvailable: 'tracker-boot: update available {latest} (current: {current}). Run: npm install -g tracker-boot-git-hooks',
+  },
+  ko: {
+    promptApiKey: 'tracker-boot API 키를 입력하세요: ',
+    promptProjectId: '이 저장소의 tracker-boot 프로젝트 ID를 입력하세요: ',
+    apiKeyStored: 'API 키가 전역 git 설정에 저장되었습니다 (tracker.apiKey).',
+    projectIdStored: '프로젝트 ID가 로컬 git 설정에 저장되었습니다 (tracker.projectId).',
+    apiError: 'tracker-boot: 스토리 {storyId}에 댓글을 게시하지 못했습니다: {message}',
+    commentPosted: 'tracker-boot: 스토리 {storyId}에 댓글이 게시되었습니다.',
+    hookExistsError: '🚫  훅 충돌 — 설치가 중단되었습니다  🚫\n이미 pre-push 훅이 존재합니다:\n  {path}\n\n먼저 삭제한 후 다시 실행하세요:\n  tracker-boot-git-hooks install\n\n또는 기존 훅에 다음 줄을 추가하세요:\n  tracker-boot-git-hooks hook "$@"',
+    updateAvailable: 'tracker-boot: 업데이트 가능 {latest} (현재: {current}). 실행: npm install -g tracker-boot-git-hooks',
+  },
+  ja: {
+    promptApiKey: 'tracker-boot APIキーを入力してください: ',
+    promptProjectId: 'このリポジトリのtracker-bootプロジェクトIDを入力してください: ',
+    apiKeyStored: 'APIキーがグローバルgit設定に保存されました (tracker.apiKey)。',
+    projectIdStored: 'プロジェクトIDがローカルgit設定に保存されました (tracker.projectId)。',
+    apiError: 'tracker-boot: ストーリー{storyId}へのコメント投稿に失敗しました: {message}',
+    commentPosted: 'tracker-boot: ストーリー{storyId}にコメントが投稿されました。',
+    hookExistsError: '🚫  フック競合 — インストールを中断しました  🚫\n以下のパスにpre-pushフックが既に存在します:\n  {path}\n\n先に削除してから再実行してください:\n  tracker-boot-git-hooks install\n\nまたは既存のフックに以下を追記してください:\n  tracker-boot-git-hooks hook "$@"',
+    updateAvailable: 'tracker-boot: アップデートがあります {latest} (現在: {current})。実行: npm install -g tracker-boot-git-hooks',
+  },
+}
+
+export function detectLang(langEnv) {
+  if (!langEnv) return 'en'
+  const code = langEnv.split('_')[0].toLowerCase()
+  return MESSAGES[code] ? code : 'en'
+}
+
+export function t(key, lang, vars = {}) {
+  const messages = MESSAGES[lang] ?? MESSAGES.en
+  const template = messages[key] ?? MESSAGES.en[key] ?? key
+  return template.replace(/\{(\w+)\}/g, (_, k) => vars[k] ?? `{${k}}`)
+}

package/src/installer.js

@@ -0,0 +1,63 @@
+import fs from 'fs'
+import path from 'path'
+import { spawnSync } from 'child_process'
+
+export function detectHusky(repoRoot) {
+  return fs.existsSync(path.join(repoRoot, '.husky'))
+}
+
+export const OUR_MARKER = '# tracker-boot-git-hooks'
+
+function resolveGitPath(repoRoot, p) {
+  return path.isAbsolute(p) ? p : path.resolve(repoRoot, p)
+}
+
+function getGitCommonDir(repoRoot) {
+  const result = spawnSync('git', ['-C', repoRoot, 'rev-parse', '--git-common-dir'], { encoding: 'utf8' })
+  if (result.status !== 0) return path.join(repoRoot, '.git')
+  return resolveGitPath(repoRoot, result.stdout.trim())
+}
+
+function getHooksDir(repoRoot) {
+  const result = spawnSync('git', ['-C', repoRoot, 'config', 'core.hooksPath'], { encoding: 'utf8' })
+  if (result.status === 0 && result.stdout.trim()) {
+    return resolveGitPath(repoRoot, result.stdout.trim())
+  }
+  return path.join(getGitCommonDir(repoRoot), 'hooks')
+}
+
+function installHookFile(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, 'utf8')
+    if (!existing.includes(OUR_MARKER)) {
+      const err = new Error(`pre-push hook already exists at ${filePath}`)
+      err.code = 'HOOK_EXISTS'
+      err.path = filePath
+      throw err
+    }
+  }
+  fs.writeFileSync(filePath, content)
+  fs.chmodSync(filePath, '755')
+}
+
+export function install({ repoRoot, hookScript }) {
+  if (detectHusky(repoRoot)) {
+    const hookPath = path.join(repoRoot, '.husky', 'pre-push')
+    installHookFile(hookPath, hookScript)
+    return { method: 'husky', reminder: 'Run: git add .husky/pre-push' }
+  }
+
+  const hooksDir = getHooksDir(repoRoot)
+  installHookFile(path.join(hooksDir, 'pre-push'), hookScript)
+
+  if (fs.existsSync(path.join(repoRoot, '.pre-commit-config.yaml'))) {
+    return {
+      method: 'direct',
+      warning:
+        'pre-commit runs hooks in isolated Python virtualenvs and cannot run Node scripts directly. ' +
+        'The hook has been installed directly to .git/hooks/pre-push instead.',
+    }
+  }
+
+  return { method: 'direct' }
+}

package/src/pushInputParser.js

@@ -0,0 +1,17 @@
+const ZERO_SHA = '0000000000000000000000000000000000000000'
+
+export function parsePushInput(stdin) {
+  return stdin
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .flatMap((line) => {
+      const parts = line.split(' ')
+      if (parts.length < 4) return []
+      // git pre-push stdin: <local-ref> <local-sha> <remote-ref> <remote-sha>
+      const [, localSha, , remoteSha] = parts
+      if (localSha === ZERO_SHA) return [] // branch deletion
+      // null remoteSha = new branch; getCommitsInRange handles it with --not --remotes
+      return [{ localSha, remoteSha: remoteSha === ZERO_SHA ? null : remoteSha }]
+    })
+}

package/src/storyIdExtractor.js

@@ -0,0 +1,11 @@
+const KEYWORDS = ['fixed', 'fixes', 'finish', 'finishes', 'finished', 'completes', 'completed', 'delivers', 'delivered']
+const KW = `(?:${KEYWORDS.join('|')})`
+const STORY_PATTERN = new RegExp(`\\[(?:${KW}\\s+)?#([0-9]{9})(?:\\s+${KW})?\\]`, 'g')
+
+export function extractStoryIds(commitMessage) {
+  const ids = new Set()
+  for (const match of commitMessage.matchAll(STORY_PATTERN)) {
+    ids.add(match[1])
+  }
+  return Array.from(ids)
+}

package/src/updateChecker.js

@@ -0,0 +1,34 @@
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/tracker-boot-git-hooks/latest'
+
+function isNewer(latest, current) {
+  const l = latest.split('.').map(Number)
+  const c = current.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    if (l[i] !== c[i]) return l[i] > c[i]
+  }
+  return false
+}
+
+export async function checkForUpdate({ timeoutMs = 2000, fetch: _fetch = fetch } = {}) {
+  const current = require('../package.json').version
+  try {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    let res
+    try {
+      res = await _fetch(NPM_REGISTRY_URL, { signal: controller.signal })
+    } finally {
+      clearTimeout(timer)
+    }
+    if (!res.ok) return null
+    const data = await res.json()
+    const latest = data?.version
+    if (typeof latest !== 'string' || !isNewer(latest, current)) return null
+    return { latest, current }
+  } catch {
+    return null
+  }
+}

package/src/urls.js

@@ -0,0 +1,6 @@
+export const DEFAULT_BASE_URL = 'https://trackerboot.com'
+
+export function resolveUrls(baseUrl = DEFAULT_BASE_URL) {
+  const base = baseUrl.replace(/\/+$/, '')
+  return { mutationUrl: `${base}/graphql` }
+}