Standalone Redmine Toolkit (TypeScript / Node.js CLI)

Redmine Toolkit เป็น CLI สำหรับให้ทีมและ AI/Agent ใช้งาน Redmine ได้อย่างเป็นระบบ: ค้นหาและอ่าน issue, project, wiki, time entry และ metadata ที่จำเป็น รวมถึงช่วยสร้าง comment, แนบไฟล์, ปิดงาน และลงเวลาโดยมี guard ลดความเสี่ยงก่อนเขียนข้อมูลจริง

เป้าหมายของ project นี้คือทำให้การทำงานกับ Redmine ทำซ้ำได้ ตรวจสอบได้ Zero-Setup ผ่าน npx และปลอดภัยสำหรับ automation โดยคำสั่งอ่านข้อมูลใช้ได้ทันที ส่วนคำสั่งที่แก้ข้อมูลต้องยืนยันด้วย --yes

🚀 Setup & Installation

🌟 วิธีที่ 1: One-Click Setup Wizard (แนะนำ)

เปิด Terminal ในโฟลเดอร์โปรเจกต์ที่ต้องการใช้งาน แล้วสั่งรัน:

npx redmine-toolkit init
# หรือหาก build ในเครื่อง:
node dist/bin/rtk.js init

ระบบจะมี Interactive Wizard ถาม Redmine Server URL และ API Key พร้อมสร้างไฟล์ .env และทดสอบเชื่อมต่อ rtk me ให้โดยอัตโนมัติ

📦 วิธีที่ 2: ติดตั้งเป็น Global CLI Tool บนเครื่อง

npm run build
npm link

หลังจากนี้สามารถสั่งใช้คำสั่ง rtk ได้จากทุก directory:

rtk me
rtk backlog
rtk issue 12096

⚙️ Environment Configuration (.env)

REDMINE_URL=https://mobileapp.nstda.or.th/redmine/
REDMINE_API_KEY=your_api_key_here
REDMINE_OUTPUT_DIR=redmine_exports
REDMINE_CLOSED_STATUS_ID=
REDMINE_DEFAULT_ACTIVITY_ID=

🔒 หลักความปลอดภัย

1. คำสั่งที่แก้ข้อมูล Redmine ต้องใส่ --yes ทุกครั้ง เช่น create, comment, close, upload, sync-desc และ time-add
2. คำสั่งที่แก้ issue จะเช็กก่อนว่า user ปัจจุบันเป็น author หรือ assignee ของ issue นั้น ยกเว้นสั่ง --allow-non-assigned เพื่อให้ Redmine permission ตัดสินแทน
3. ห้ามใส่ icon หรือ emoji ในข้อความที่เขียนลง Redmine (ระบบมีตัวตรวจจับและปฏิเสธคำสั่งอัตโนมัติ)
4. Spent time comment ต้องไม่เกิน 200 ตัวอักษร

📋 คำสั่งที่ใช้งานบ่อย (Commands Reference)

1. ข้อมูลผู้ใช้ & Master Data

# ตรวจสอบ API Key และข้อมูลผู้ใช้ปัจจุบัน
rtk me

# ดึงและแคช Master Data ลงไฟล์ JSON
rtk master-data --cache

# ดูรายการ Trackers, Statuses, Priorities, Activities, Projects
rtk trackers
rtk statuses
rtk priorities
rtk activities
rtk projects [query]

2. ค้นหาและอ่าน Issue

# ดูงานค้างของตัวเอง (Backlog)
rtk backlog

# เลือกงานถัดไปที่มีความสำคัญสูงสุด
rtk next

# ค้นหา Issue ด้วย Thai NLP Keywords
rtk search "bug ระบบ login"
rtk search --ask "ช่วยค้นหางานเกี่ยวกับ odoo"

# อ่านรายละเอียด Issue พร้อม Journals และ Attachments
rtk issue 12096
rtk issue 12096 --json

# Export Issue เป็น JSON และดาวน์โหลด Attachments ทั้งหมด
rtk get 12096

3. สร้างและแก้ไข Issue (ต้องใส่ --yes)

# สร้าง Issue ใหม่
rtk create --project <PROJECT_ID> --subject "หัวข้องาน" --description "รายละเอียดงาน" --yes

# เพิ่ม Comment / Journal Note
rtk comment 12096 "บันทึกความคืบหน้างาน" --yes

# ปิดงาน (Close) พร้อมลงเวลา Spent Time
rtk close 12096 --note "ดำเนินการเสร็จสิ้น" --hours 2 --comment "แก้ไขและทดสอบระบบ" --yes

# แนบไฟล์ขึ้น Issue
rtk upload 12096 "path/to/document.pdf" --description "เอกสารแนบ" --yes

# Sync คำอธิบายจากไฟล์ Markdown/Textile
rtk sync-desc 12096 "path/to/spec.md" --yes

4. บันทึกและตรวจสอบเวลาทำงาน (Time Tracking)

# ดูรายการลงเวลาของตัวเอง
rtk time-entries --from 2026-09-01 --to 2026-09-15

# บันทึกเวลาทำงาน
rtk time-add 12096 1.5 --activity 9 --comment "แก้ไขบั๊กในส่วน validate token" --yes

🧪 Testing & Development

# Run Unit Tests (Vitest)
npm test

# Run Typecheck & Tests
npm run check

# Build Distribution
npm run build