fix: document backwards-compatibility expectations for `litra-devices…

…` CLI command

dist/commonjs/cli/litra-devices.js

@@ -5,8 +5,8 @@ const commander_1 = require("commander");
 const driver_1 = require("../driver");
 commander_1.program
     .name('litra-devices')
-    .description('Lists Litra devices connected to your computer. Defaults to human-readable plain text.')
-    .option('--json', 'output the list of devices in structured JSON format');
+    .description('Lists Litra devices connected to your computer. Defaults to human-readable plain text. The structure and content of the plain text output may change in future versions. If you need a machine-readable output with consistency guarantees, use the `--json` option.')
+    .option('--json', 'output the list of devices in structured JSON format. New attributes may be added to the JSON output in future versions. Existing attributes will only be removed or changed in a backwards-incompatible way in major versions.');
 commander_1.program.parse();
 const { json } = commander_1.program.opts();
 const devices = (0, driver_1.findDevices)();

dist/esm/cli/litra-devices.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { program } from 'commander';
-import { findDevices, getBrightnessInLumen, getNameForDevice, getTemperatureInKelvin, isOn } from '../driver';
+import { findDevices, getBrightnessInLumen, getNameForDevice, getTemperatureInKelvin, isOn, } from '../driver';
 program
     .name('litra-devices')
-    .description('Lists Litra devices connected to your computer. Defaults to human-readable plain text.')
-    .option('--json', 'output the list of devices in structured JSON format');
+    .description('Lists Litra devices connected to your computer. Defaults to human-readable plain text. The structure and content of the plain text output may change in future versions. If you need a machine-readable output with consistency guarantees, use the `--json` option.')
+    .option('--json', 'output the list of devices in structured JSON format. New attributes may be added to the JSON output in future versions. Existing attributes will only be removed or changed in a backwards-incompatible way in major versions.');
 program.parse();
 const { json } = program.opts();
 const devices = findDevices();

src/cli/litra-devices.ts

@@ -12,10 +12,12 @@ import {
 program
   .name('litra-devices')
   .description(
-    'Lists Litra devices connected to your computer. Defaults to human-readable plain text.',
+    'Lists Litra devices connected to your computer. Defaults to human-readable plain text. The structure and content of the plain text output may change in future versions. If you need a machine-readable output with consistency guarantees, use the `--json` option.',
   )
-  .option('--json', 'output the list of devices in structured JSON format');
-
+  .option(
+    '--json',
+    'output the list of devices in structured JSON format. New attributes may be added to the JSON output in future versions. Existing attributes will only be removed or changed in a backwards-incompatible way in major versions.',
+  );
 program.parse();
 const { json } = program.opts();