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:

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

# 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):

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):

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:

# 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):

pnpm start:cli check

Using pnpm exec (from monorepo root, after pnpm install):

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):

# From packages/instruction-updater directory
pnpm test

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