feat(kv): introduce kv command

bin/clever.js

@@ -4,6 +4,7 @@
 import '../src/initial-setup.js';
 
 import cliparse from 'cliparse';
+import colors from 'colors/safe.js';
 import cliparseCommands from 'cliparse/src/command.js';
 import _sortBy from 'lodash/sortBy.js';
 
@@ -13,7 +14,9 @@ import * as Parsers from '../src/parsers.js';
 import { handleCommandPromise } from '../src/command-promise-handler.js';
 import * as Application from '../src/models/application.js';
 import { AVAILABLE_ZONES } from '../src/models/application.js';
+import { EXPERIMENTAL_FEATURES } from '../src/experimental-features.js';
 import { getExitOnOption, getOutputFormatOption, getSameCommitPolicyOption } from '../src/command-options.js';
+import { getFeatures } from '../src/models/configuration.js';
 
 import * as Addon from '../src/models/addon.js';
 import * as ApplicationConfiguration from '../src/models/application_configuration.js';
@@ -35,6 +38,7 @@ import * as domain from '../src/commands/domain.js';
 import * as drain from '../src/commands/drain.js';
 import * as env from '../src/commands/env.js';
 import * as features from '../src/commands/features.js';
+import * as kv from '../src/commands/kv.js';
 import * as link from '../src/commands/link.js';
 import * as login from '../src/commands/login.js';
 import * as logout from '../src/commands/logout.js';
@@ -75,10 +79,21 @@ cliparse.command = function (name, options, commandFunction) {
   });
 };
 
-function run () {
+// Add a yellow color and status tag to the description of an experimental command
+function colorizeExperimentalCommand (command, id) {
+  const status = EXPERIMENTAL_FEATURES[id].status;
+  command.description = colors.yellow(command.description + ' [' + status.toUpperCase() + ']');
+  return command;
+}
+
+async function run () {
 
   // ARGUMENTS
   const args = {
+    kvRawCommand: cliparse.argument('command', { description: 'The raw command to send to the Materia KV or Redis® add-on' }),
+    kvIdOrName: cliparse.argument('kv-id', {
+      description: 'Add-on/Real ID (or name, if unambiguous) of a Materia KV or Redis® add-on',
+    }),
     addonIdOrName: cliparse.argument('addon-id', {
       description: 'Add-on ID (or name, if unambiguous)',
       parser: Parsers.addonIdOrName,
@@ -694,6 +709,13 @@ function run () {
     commands: [enableFeatureCommand, disableFeatureCommand, listFeaturesCommand, infoFeaturesCommand],
   }, features.list);
 
+  // KV COMMAND
+  const kvRawCommand = cliparse.command('kv', {
+    description: 'Send a raw command to a Materia KV or Redis® add-on',
+    args: [args.kvIdOrName, args.kvRawCommand],
+    options: [opts.orgaIdOrName, opts.humanJsonOutputFormat],
+  }, kv.sendRawCommand);
+
   // LINK COMMAND
   const appLinkCommand = cliparse.command('link', {
     description: 'Link this repo to an existing application',
@@ -949,6 +971,13 @@ function run () {
     webhooksCommand,
   ];
 
+  // Add experimental features only if they are enabled through the configuration file
+  const featuresFromConf = await getFeatures();
+
+  if (featuresFromConf.kv) {
+    commands.push(colorizeExperimentalCommand(kvRawCommand, 'kv'));
+  }
+
   // CLI PARSER
   const cliParser = cliparse.cli({
     name: 'clever',

docs/README.md

@@ -11,6 +11,7 @@ to ask for new features, enhancements or help us to provide them to our communit
 
 You'll find below the first commands to know to connect Clever Tools to your account, get its information and manage some options. Others are developed in dedicated pages:
 
+- [Materia KV](/docs/kv.md)
 - [Applications: configuration](/docs/applications-config.md)
 - [Applications: management](/docs/applications-management.md)
 - [Applications: deployment and lifecycle](/docs/applications-deployment-lifecycle.md)

docs/kv.md

@@ -0,0 +1,47 @@
+# Clever KV
+
+If you're using [Materia KV](https://developers.clever-cloud.com/doc/addons/materia-kv/), our next generation of key-value databases, serverless, distributed, synchronously-replicated, compatible with the Redis® protocol (and later DynamoDB, GraphQL), you can easily create an add-on with Clever Tools:
+
+```
+clever addon create kv ADDON_NAME
+```
+
+And immediately use it with `clever kv` command:
+
+```bash
+clever kv ADDON_NAME_OR_ID PING          # It will answer PONG
+clever kv ADDON_NAME_OR_ID PING Hello    # It will answer Hello
+```
+
+It helps you to inspect and interact with your Materia KV. Each is provided with environment variables about its host, port, and [Biscuit-based](https://biscuitsec.org) tokens, in multiple forms (to ensure compatibility with tools such those made for Redis®).
+
+[!Tip]
+> Clever KV command is also compatible with Redis® on Clever Cloud add-ons.
+
+## Commands
+
+You can use `clever kv` to send any command supported by your add-on. Here are some examples:
+
+```bash
+clever kv ADDON_NAME_OR_ID INCR myCounter             # It will respond (integer) the incremented value
+clever kv ADDON_NAME_OR_ID SET myKey myValue          # It will respond OK
+clever kv ADDON_NAME_OR_ID GET myKey                  # It will respond myValue
+clever kv ADDON_NAME_OR_ID SET myKey myValue EX 120   # It will respond OK
+clever kv ADDON_NAME_OR_ID TTL myKey                  # It will respond (integer) the remaining time to live of the key in seconds
+```
+
+>[!Tip]
+>You can get a list of all supported commands with `clever kv ADDON_NAME_OR_ID COMMANDS`
+
+You can pass the result of JSON stringified values to tools like `jq` to query them, for example:
+
+```bash
+clever kv ADDON_NAME_OR_ID SET myJsonFormatedKey '{"key": "value"}'
+clever kv ADDON_NAME_OR_ID GET myJsonFormatedKey | jq .key
+```
+
+You can also use the `-F/--format` option to print a result in JSON format and query it with `jq`:
+
+```bash
+clever kv ADDON_NAME_OR_ID scan 0 -F json | jq '.[1][0]'
+```

package.json

@@ -33,6 +33,7 @@
     "curlconverter": "3.21.0",
     "duration-js": "4.0.0",
     "eventsource": "1.1.0",
+    "ioredis": "5.4.1",
     "iso8601-duration": "2.1.2",
     "isomorphic-git": "1.25.3",
     "linux-release-info": "3.0.0",