Linear I/O Engine

A comprehensive Linear input/output engine for reading, writing, and managing Linear project data with backup and audit capabilities.

Overview

A full-featured Linear data management system that supports:

• Multi-project management - Handle multiple Linear projects with isolated configurations
• Bidirectional operations - Read from and write to Linear with full API coverage
• Backup & restore - Automated snapshots with configurable retention policies
• Audit trails - Complete logging of all operations with timestamps and error tracking
• Template system - Reusable project templates for common patterns
• CLI interface - Command-line tool for all operations
• Schema validation - Data integrity with JSON schemas

Architecture

linear-input/
├── src/
│   ├── core/           # Core system components
│   ├── modules/        # Feature modules (reader, writer, backup)
│   └── cli/            # Command-line interface
├── data/               # Private user data (gitignored)
│   ├── projects/       # User project-specific data and configs
│   └── templates/      # User custom templates (optional)
├── examples/           # Public examples (tracked in git)
│   ├── templates/      # Example templates for reference
│   └── projects/       # Example project structures
├── templates/          # Legacy template directory (deprecated)
├── migrations/         # Migration scripts
└── docs/              # Documentation

Quick Start

1. Setup

# Set your Linear API key
export LINEAR_API_KEY=lin_api_your_key_here

# Initialize the system
npm run setup

2. Create a Project

# Create from template
npm start create my-project --name "My Project" --template software-project

# Or create empty project
npm start create my-project --name "My Project"

3. Import Data

# Import from file
npm start write my-project --file path/to/plan.json

# Or import from template
npm start write my-project --template software-project

4. Read/Export Data

# Read project summary
npm start read my-project

# Export data
npm start export my-project json
npm start export my-project csv
npm start export my-project markdown

5. Backup & Restore

# Create backup
npm start backup my-project --description "Before major changes"

# List backups
npm start list-backups my-project

# Restore from backup
npm start restore my-project snapshot-id

CLI Commands

Project Management

• setup - Initialize global configuration
• create <id> - Create new project
• list - List all projects
• status <id> - Show project status

Data Operations

• read <id> - Read project data
• write <id> - Write/import project data
• export <id> <format> - Export data (json, csv, markdown)

Backup & Restore

• backup <id> - Create project backup
• restore <id> <snapshot> - Restore from backup
• list-backups <id> - List available backups

Configuration

Global Configuration

Located at data/global-config.json (see examples/global-config.example.json for reference):

{
  "defaultSettings": {
    "backup": {
      "enabled": true,
      "frequency": "daily",
      "retentionDays": 30
    },
    "audit": {
      "enabled": true,
      "level": "detailed"
    }
  },
  "templates": {
    "default": "./examples/templates/default.json",
    "software-project": "./examples/templates/software-project.json",
    "example-project": "./examples/templates/example-project.json"
  }
}

Project Configuration

Each project has its own data/projects/{project-id}/config.json:

{
  "projectId": "my-project",
  "name": "My Project",
  "linearProjectId": "abc123",
  "team": {
    "key": "TEAM",
    "id": "team_456"
  },
  "settings": {
    "backup": { "enabled": true },
    "audit": { "enabled": true }
  }
}

Data Structure

Each project maintains:

data/projects/{project-id}/
├── config.json         # Project configuration
├── inputs/             # Input data files
│   ├── plans/          # Project plans
│   └── projects.json   # Project definitions
├── outputs/            # Exported data
│   ├── snapshots/      # Full snapshots
│   ├── reports/        # Generated reports
│   └── exports/        # Formatted exports (CSV, JSON, MD)
├── backups/            # Point-in-time backups
│   ├── pre-operation/  # Before major changes
│   └── scheduled/      # Regular backups
└── audit/              # Operation logs
    ├── operations.log
    └── errors.log

Templates

Available Templates

• default - Basic project structure (see examples/templates/default.json)
• software-project - Comprehensive software development project
• example-project - Example project configuration

Template Resolution Order

The system looks for templates in this order:

1. examples/templates/ - Public example templates (tracked in git)
2. templates/ - Legacy location (deprecated, for backward compatibility)
3. data/templates/ - User custom templates (gitignored)

Creating Custom Templates

Create JSON files in data/templates/ for private custom templates:

{
  "name": "Custom Template",
  "description": "Description of template",
  "defaultLabels": ["feature", "bug", "improvement"],
  "milestones": [
    {
      "name": "MVP",
      "targetDate": "2025-03-01"
    }
  ],
  "issueTemplates": [
    {
      "title": "Feature Template",
      "description": "Template description",
      "labels": ["feature"],
      "subIssues": [
        { "title": "Sub-task 1" },
        { "title": "Sub-task 2" }
      ]
    }
  ]
}

Templates in data/templates/ are private (gitignored) while examples/templates/ are public examples.

Environment Variables

• LINEAR_API_KEY - Your Linear API key (required)
• LINEAR_TEAM_KEY - Default team key (optional)
• LINEAR_PROJECT_ID - Default project ID (optional)
• DEBUG - Enable debug logging (optional)

Development

Scripts

• npm start - Run CLI
• npm run setup - Initialize global configuration
• npm run backup - Quick backup command
• npm run restore - Quick restore command
• npm test - Run tests (not implemented yet)

Adding New Features

1. Create modules in src/modules/
2. Update CLI in src/cli/
3. Add example templates in examples/templates/ (public)
4. Add custom templates in data/templates/ (private)
5. Update documentation

Backup Strategy

Automatic Backups

• Pre-operation: Created before major changes
• Scheduled: Daily/weekly based on configuration
• Manual: User-initiated backups

Retention Policy

• Configurable retention (default 30 days)
• Automatic cleanup of old backups
• Migration backups preserved permanently

Audit Trail

All operations are logged with:

• Timestamp and user
• Operation type and parameters
• Success/failure status
• Execution time
• Error details (if applicable)

Logs are stored in:

• audit/operations.log - All operations
• audit/errors.log - Errors only
• audit/YYYY-MM/ - Monthly archives

Security

• API keys are never logged (redacted in audit trails)
• Sensitive data is filtered from logs
• Backup files contain full data for restore capability
• All operations require valid API authentication

Troubleshooting

Common Issues

API Key Not Set

export LINEAR_API_KEY=lin_api_your_key_here
npm run setup

Project Not Found

npm start list  # Show all projects
npm start create project-id --name "Project Name"

CLI Commands Fail

# Check your API key is set
echo $LINEAR_API_KEY

# Run with debug mode
DEBUG=1 npm start <command>

Support

For issues and feature requests, check the git history and commit messages for implementation details.

License

ISC License - See package.json for details.

---

Linear I/O Engine v1.0 - Professional Linear project management with comprehensive backup and audit capabilities