npm package: @jvittechs/jai1-client
Description: Unified CLI for Jai1 Framework Management and Redmine Context Sync
Author: JVIT
Latest version: 0.1.50

# @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

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

## Quick Start

```bash
# 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

### Apply Components (Install/Update)

The `apply` command is the main entry point for installing or updating components. It supports interactive mode, packages, or specific files.

```bash
# Interactive mode (Browse packages/components)
jai1 apply

# Apply a specific package (e.g., 'core')
jai1 apply package core

# Apply specific components by path
jai1 apply workflows/commit-it.md
jai1 apply skills/gen-commit-message
```

**Features:**
- **Dependency Resolution**: Automatically installs required dependencies.
- **Search**: Interactive search for components.
- **Backup**: Automatically backs up modified files to `.jai1_backup/`.

### Check for Updates

Check if any installed components have newer versions available in the store.

```bash
jai1 check
```

**Output:**
```
Checking 5 components...
📦 workflows/commit-it.md: v1.0.0 (Latest)
📦 skills/gen-commit-message: v1.0.0 -> v1.1.0 ⚠️ Update available
```

### Update All Components

Update all currently installed components to their latest versions.

```bash
jai1 update
```

**Output:**
```
✅ Updated workflows/commit-it.md (v1.0.1)
✅ Updated skills/gen-commit-message (v1.1.0)
Backup created at .jai1_backup/2023-12-10T10-00-00/
```

### Manage Backups

Clear old backups to free up space.

```bash
# Clear all backups
jai1 clear-backups

# Clear backups older than 7 days
jai1 clear-backups --older-than 7d
```

### Show Info

Display configuration and environment information.

```bash
jai1 info
```

---

## Redmine Commands

### Check Connectivity

```bash
jai1 redmine check
```

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

### Sync Single Issue

```bash
# 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

```bash
# 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/
```

---

## VSCode Commands

Manage VSCode settings for optimal IDE performance with modular optimization groups.

### Quick Start

```bash
# Interactive mode
jai1 vscode

# Max performance (enable all optimizations)
jai1 vscode max-performance

# List available groups
jai1 vscode list
```

### Available Commands

| Command | Description |
|---------|-------------|
| `jai1 vscode` | Interactive mode to select groups |
| `jai1 vscode enable [groups...]` | Enable specific optimization groups |
| `jai1 vscode disable [groups...]` | Disable specific optimization groups |
| `jai1 vscode max-performance` | Enable all optimizations |
| `jai1 vscode reset [groups...]` | Reset to default settings |
| `jai1 vscode list` | List all available groups |

### Performance Groups

| Group | Description | Impact |
|-------|-------------|--------|
| `telemetry` | Disable all telemetry and data collection | 🟢 Low |
| `languageServers` | Disable/reduce language servers (tsserver, eslint...) | 🔴 High |
| `git` | Disable Git integration | 🟡 Medium |
| `fileWatcher` | Exclude directories from file watcher | 🟡 Medium |
| `search` | Exclude directories from search | 🟢 Low |
| `extensions` | Disable auto-update extensions | 🟢 Low |
| `editorRendering` | Optimize rendering (minimap, whitespace...) | 🟡 Medium |
| `uiElements` | Hide unnecessary UI elements | 🟢 Low |

### Common Scenarios

**Large Project (Node.js/React):**
```bash
jai1 vscode enable fileWatcher search extensions
```

**Low-spec Machine:**
```bash
jai1 vscode max-performance
```

**Privacy (Disable Telemetry):**
```bash
jai1 vscode enable telemetry
```

**Minimal UI:**
```bash
jai1 vscode enable uiElements editorRendering
```

**Restore Features:**
```bash
# Restore specific group
jai1 vscode disable languageServers

# Restore all
jai1 vscode reset
```

### Documentation

- [Full Documentation](./docs/VSCODE_COMMAND.md) - Detailed guide with all settings
- [Quick Reference](./docs/VSCODE_QUICK_REF.md) - Quick reference for common use cases
- [Refactoring Summary](./docs/REFACTOR_VSCODE_COMMAND.md) - Technical details of the refactoring

---

## Configuration

### Global Config: `~/.jai1/config.json`

Created by `jai1 init`:

```json
{
  "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:

```yaml
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:

```markdown
---
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

```bash
# 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)](./docs/PRD-jai1-client.md)

---

## License

MIT