npm package: @sylphx/coding
Description: This CLI tool is designed to download official Sylphx mode configurations from a specified URL and intelligently synchronize them with a local `custom_modes.yaml` file used by applications like Roo Cline.
Latest version: 1.5.0

# Instruction Updater CLI (@sylphx/instruction-updater)

This CLI tool is designed to download official Sylphx mode configurations from a specified URL and intelligently synchronize them with a local `custom_modes.yaml` file used by applications like Roo Cline.

## Features

- Fetches a complete list of official Sylphx mode objects (including `slug`, `name`, `roleDefinition`, `customInstructions`, `groups`) from a dedicated API endpoint.
- Reads the local `custom_modes.yaml` file.
- **Intelligently synchronizes official modes**:
    - Updates existing official modes (slug `sylphx` or starting with `sylphx_`) if their content (`roleDefinition` or `customInstructions`) differs from the remote version.
    - Adds new official modes from the remote source if they don't exist locally.
    - Removes local official modes that are no longer present in the remote source (considered obsolete).
    - Preserves all user-defined custom modes (those with slugs not matching the official pattern).
- Writes the synchronized list of modes back to the local `custom_modes.yaml` file.
- Provides a `check` command to list local modes and display their synchronization status against the official source.
- CLI output is enhanced with colors and formatting for better readability.

## Prerequisites

- Node.js (version 18 or higher recommended for built-in `fetch`).
- pnpm (for package management within this monorepo).

## Installation (within Monorepo)

This package is part of a pnpm monorepo. Dependencies are typically managed from the monorepo root.

To build the tool:
```bash
# From monorepo root
pnpm --filter @sylphx/instruction-updater build
```
This will use `tsup` to compile the TypeScript source code into the `packages/instruction-updater/dist` directory.

## Usage

The CLI provides two main commands: `update` and `check`.

### `update` Command

Synchronizes local `custom_modes.yaml` with the official Sylphx modes.

**Local execution from monorepo root:**
```bash
# Ensure the tool is built first
pnpm --filter @sylphx/instruction-updater build

# Run the update command
node packages/instruction-updater/dist/cli.js update
```

**Using pnpm script (from `packages/instruction-updater` directory):**
```bash
pnpm start:cli update 
```
(Note: `start:cli` in `package.json` is `node ./dist/cli.js`, so `update` is the subcommand)

**Using pnpm exec (from monorepo root, after `pnpm install`):**
```bash
pnpm --filter @sylphx/instruction-updater exec instruction-updater update
```

**Options for `update`:**
-   `-u, --url <url>`: Specify a custom URL to download the official modes configuration from.
    Defaults to: `https://playbook.sylphx.com/api/get-sylphx-modes-config`
-   `-o, --output <path>`: Specify a custom local path for the `custom_modes.yaml` file.
    Defaults to: `C:\Users\<YourUser>\AppData\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\custom_modes.yaml`

### `check` Command

Lists local custom modes and displays their synchronization status with official Sylphx modes.

**Local execution from monorepo root:**
```bash
# Ensure the tool is built first
pnpm --filter @sylphx/instruction-updater build

# Run the check command
node packages/instruction-updater/dist/cli.js check
```

**Using pnpm script (from `packages/instruction-updater` directory):**
```bash
pnpm start:cli check
```

**Using pnpm exec (from monorepo root, after `pnpm install`):**
```bash
pnpm --filter @sylphx/instruction-updater exec instruction-updater check
```

**Options for `check`:**
-   `-u, --url <url>`: Specify a custom URL to fetch the official modes configuration for comparison.
-   `-l, --local-path <path>`: Specify a custom local path for the `custom_modes.yaml` file to check.


## Development

-   Source code is located in `packages/instruction-updater/src`.
-   Build the package using `pnpm build` within the `packages/instruction-updater` directory, or `pnpm --filter @sylphx/instruction-updater build` from the monorepo root.

## Testing (Future Work)

Unit tests should be implemented using Vitest to cover:
-   `downloader.ts`: Mock HTTP requests and test fetching/parsing of the modes configuration.
-   `file-handler.ts`: Test reading, writing, and the core `synchronizeModes` logic with various scenarios (new modes, updated modes, removed modes, user-defined modes).
-   `cli.ts`: Test command parsing and option handling.

Integration tests could also be added to test the end-to-end flow.

To run tests (once implemented):
```bash
# From packages/instruction-updater directory
pnpm test

# Or from monorepo root
pnpm --filter @sylphx/instruction-updater test