npm package: @meanmail/devshift
Description: Tool for building DevShift extensions for JetBrains IDEs
Author: meanmail.dev
Latest version: 1.0.88

# DevShift Plugin Builder

A tool for building DevShift extensions for JetBrains IDEs.

## Installation

```bash
npm install -g @meanmail/devshift
```

Or use it directly with npx:

```bash
npx @meanmail/devshift build <source-path> <output-path>
```

## Usage

1. Create a directory for your extension with the following files:
    - `extension.json`: Contains metadata about your extension
    - `extension.ts`: Contains the code for your extension (will be compiled to `extension.mjs`)

2. Run the builder:

```bash
@meanmail/devshift build <source-path> <output-path>
```

Where:

- `<source-path>` is the path to the directory containing your extension files
- `<output-path>` is the path where the plugin will be generated

## Extension Structure

### extension.json

The `extension.json` file contains metadata about your extension:

```json
{
  "id": "com.example.myplugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "A description of my plugin",
  "author": "Your Name",
  "license": "MIT",
  "url": "https://example.com"
}
```

Required fields:

- `id`: Unique identifier for the plugin
- `name`: Display name of the plugin
- `version`: Version of the plugin
- `description`: Short description of the plugin
- `author`: Author of the plugin
- `license`: License of the plugin

Optional fields:

- `url`: URL for the plugin

### extension.ts and extension.mjs

The `extension.ts` file contains the code for your extension, which will be compiled to `extension.mjs`. It should
export two functions:

```javascript
// ES module syntax - no need to import 'ide' as it's available in the global scope

export function activate() {
  // Called when the plugin is activated
  ide.showMessage('Hello!', 'Hello from the extension!')
}

export function deactivate() {
  // Called when the plugin is deactivated
  ide.showMessage('Goodbye!', 'Goodbye from the extension!')
}
```

## IDE API

The following API is available to your extension through the global `ide` object:

### showMessage(title: string, message: string): void

Shows an information message to the user.

- `title`: The title of the message
- `message`: The content of the message

Example:

```javascript
ide.showMessage('Hello!', 'Hello from the extension!')
```

## Building the Plugin

After running the builder, you'll get a directory structure that can be built using Gradle:

```bash
cd <output-path>/<plugin-name>
./gradlew buildPlugin
```

The built plugin will be available in the `build/distributions` directory.

## Type Definitions

Type definitions for the IDE API are included in the package. To use them in your TypeScript project, add a reference to
the types:

```typescript
/// <reference path="node_modules/@meanmail/devshift/dist/types/ide-api.d.ts" />
```

Or import them directly:

```typescript
import '@meanmail/devshift/dist/types/ide-api';
```

## Development Tools

### Type Checking

The project includes TypeScript for static type checking. You can run type checking without compiling the code using:

```bash
npm run type-check
```

This will help catch type errors before runtime.

### Linting

ESLint is configured for code quality and consistency. You can run the linter using:

```bash
npm run lint
```

To automatically fix linting issues:

```bash
npm run lint:fix
```

The linting rules are configured in `.eslintrc.js` and include TypeScript-specific rules to ensure code quality.