@jvittechs/jai1-client

A unified CLI tool for JV-IT TECHS developers to manage Jai1 Framework and sync Redmine issues as context for agentic coding workflows.

Features

Jai1 Framework Management

• 📦 Download and update Jai1 Framework from Jai1 Store
• 🔄 Sync framework to any project with one command
• 🔐 Secure access key authentication
• 📋 Version checking and auto-update support

Redmine Context Sync

• 🎯 Extract Redmine issues as structured context for AI agents
• 📝 Sync individual issues or entire projects to local Markdown files
• ⚡ Incremental updates with change detection
• 💬 Comment synchronization with tracking
• 🔧 Configurable filename patterns and slug generation
• 🚀 Concurrent processing for large projects
• 🔁 Retry logic and rate limiting
• ✅ YAML configuration with validation

Installation

npm install -g @jvittechs/jai1-client
# or
pnpm add -g @jvittechs/jai1-client

Quick Start

# 1. Initialize Jai1 CLI with your access key
jai1 init

# 2. Download and sync framework to your project
jai1 update

# 3. Setup Redmine config (create redmine.config.yaml)
# 4. Sync Redmine issues
jai1 redmine sync project

Jai1 Framework Commands

Initialize Configuration

# Interactive mode
jai1 init

# With options
jai1 init --api-url https://store.jai1.io --access-key YOUR_KEY

Check Version

jai1 check

Output:

Current version: 1.2.3
Latest version:  1.3.0
Status: Update available!

Download Framework

# Download latest
jai1 download

# Download specific version
jai1 download --version 1.2.3

Sync Framework to Project

# Sync to current project
jai1 sync

# Sync with backup
jai1 sync --backup

Update (Download + Sync)

# One command to update everything
jai1 update

# With backup
jai1 update --backup

Show Info

jai1 info

Output:

Config Location: ~/.jai1/config.json
API URL: https://store.jai1.io
Access Key: ****abcd
Current Version: 1.2.3
Framework Location: ~/.jai1/framework

Redmine Commands

Check Connectivity

jai1 redmine check

Output:

✓ Redmine API accessible
✓ Project found: my-project (ID: 123)
✓ Issues API: 45 issues available

Sync Single Issue

# By ID
jai1 redmine sync issue --id 123

# By URL
jai1 redmine sync issue --url https://redmine.example.com/issues/123

# Dry run (preview changes)
jai1 redmine sync issue --id 123 --dry-run

Sync Project

# Sync all issues
jai1 redmine sync project

# Filter by status
jai1 redmine sync project --status "open"

# Sync issues updated since date
jai1 redmine sync project --updated-since 2023-01-01

# Custom concurrency and page size
jai1 redmine sync project --concurrency 8 --page-size 50

# Dry run
jai1 redmine sync project --dry-run

Output:

Syncing project: my-project (ID: 123)
[████████████████████████████████] 45/45 issues

Summary:
  Created: 5 issues
  Updated: 12 issues
  Unchanged: 28 issues
  
Output: .jai1/redmine/

Configuration

Global Config: ~/.jai1/config.json

Created by jai1 init:

{
  "apiUrl": "https://store.jai1.io",
  "accessKey": "YOUR_ACCESS_KEY",
  "version": "1.2.3",
  "lastUpdated": "2025-12-09T00:00:00Z"
}

Redmine Config: redmine.config.yaml

Create this file in your project root:

baseUrl: https://redmine.example.com
apiAccessToken: YOUR_API_TOKEN
project:
  id: 123
  identifier: my-project
outputDir: .jai1/redmine
defaults:
  include: [journals, relations, attachments]
  status: '*'
  pageSize: 100
  concurrency: 4
  retry:
    retries: 3
    baseMs: 300
filename:
  pattern: '{issueId}-{slug}.md'
  slug:
    maxLength: 80
    dedupe: true
    lowercase: true
  renameOnTitleChange: false
comments:
  anchors:
    start: '<!-- redmine:comments:start -->'
    end: '<!-- redmine:comments:end -->'
  trackBy: journalId

Configuration Options

| Option | Type | Description | Default | |--------|------|-------------|---------| | baseUrl | string | Redmine instance URL | Required | | apiAccessToken | string | Redmine API access token | Required | | project.id | number | Project ID (numeric) | Required | | project.identifier | string | Project identifier (string) | Required | | outputDir | string | Directory to store markdown files | .jai1/redmine | | defaults.include | array | What to include (journals, relations, attachments) | [journals] | | defaults.status | string | Filter by status (* for all) | * | | defaults.pageSize | number | API page size (1-100) | 100 | | defaults.concurrency | number | Concurrent requests (1-10) | 4 | | filename.pattern | string | Filename pattern with placeholders | {issueId}-{slug}.md | | comments.trackBy | string | How to track new comments | journalId |

Global Options

| Option | Description | |--------|-------------| | -c, --config <path> | Path to configuration file | | -o, --output-dir <path> | Output directory for files | | --dry-run | Show what would be done without making changes | | --json | Output results as JSON | | --verbose | Enable verbose logging | | --version | Show CLI version | | --help | Show help |

Output Format

Redmine issues are saved as Markdown files with frontmatter:

---
id: 123
subject: 'Example Issue'
status: 'Open'
priority: 'Normal'
author: 'John Doe'
assigned_to: 'Jane Smith'
created_on: '2023-01-01T10:00:00Z'
updated_on: '2023-01-02T15:30:00Z'
project: 'My Project'
tracker: 'Bug'
lastJournalId: 456
---

# Issue Description

This is the issue description...

<!-- redmine:comments:start -->

## John Doe - 2023-01-02 15:30

This is a comment on the issue.

---

## Jane Smith - 2023-01-03 09:15

Another comment with changes.

**Changes:**

- status: Open → In Progress
- assigned_to: John Doe → Jane Smith

---

<!-- redmine:comments:end -->

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

Exit Codes

| Code | Description | |------|-------------| | 0 | Success | | 1 | General error | | 2 | Validation error (configuration, arguments) | | 3 | Authentication error (invalid access key) | | 4 | Resource not found (issue, project) | | 5 | System/network error |

Documentation

• PRD (Product Requirements Document)

License

MIT