Commandes personnalisées pour acme-versioned

Aperçu

La CLI acme-versioned supporte les commandes personnalisées écrites par l'utilisateur qui sont compilées dans le binaire aux côtés des commandes API générées automatiquement. Les commandes personnalisées reçoivent un client SDK complètement câblé qui hérite de l'authentification, des retries, du TLS, de l'URL de base et des en-têtes globaux de la CLI — zéro configuration requise.

Architecture

cli/acme-versioned/custom.rs    ← Vos gestionnaires de commande (protégés par .fernignore)
cli/acme-versioned/sdk.rs       ← Pont généré : client() + block_on()
cli/acme-versioned/main.rs      ← Point d'entrée généré (appelle custom::register)
acme-versioned-sdk/             ← Caisse SDK typée co-générée
acme-versioned-types/           ← Caisse modèle typée co-générée

Ajouter une commande personnalisée

1. Éditer cli/acme-versioned/custom.rs

Ce fichier est protégé par .fernignore — fern generate ne le réécrira jamais. Enregistrez les commandes dans la fonction register() :

use acme_versioned_sdk::api::*;

pub fn register(app: CliApp) -> CliApp {
    let app = app.command(
        clap::Command::new("my-command")
            .about("Description of your command")
            .arg(clap::Arg::new("id").required(true)),
        |matches, ctx| {
            let id = matches.get_one::<String>("id").unwrap();
            let client = super::sdk::client(ctx);
            let result = super::sdk::block_on(
                client.v1.get(id),
            )?;
            println!("{}", serde_json::to_string_pretty(&result).unwrap());
            Ok(())
        },
    );
    app
}

2. Clients SDK disponibles

L'appel super::sdk::client(ctx) retourne un acme_versioned_sdk::api::Client avec les sous-clients suivants :

3. Modèles clés

Obtenir le client SDK (partage d'exécution, complètement authentifié) :

let client = super::sdk::client(ctx);

Exécuter un appel SDK asynchrone depuis un gestionnaire synchrone :

let result = super::sdk::block_on(
    client.some_resource.some_method(args),
)?;

Utiliser des modèles typés pour la sérialisation requête/réponse :

use acme_versioned_sdk::api::*;

4. Authentification

Les commandes personnalisées héritent automatiquement de l'authentification de la CLI. Les schémas d'authentification suivants sont configurés :

• bearerAuth (bearer) : env ACME_VERSIONED_TOKEN

Aucun câblage d'authentification manuel n'est nécessaire dans les gestionnaires de commandes personnalisées.

Sécurité de régénération

Après avoir exécuté fern generate, votre custom.rs est préservé. Tout le code généré (SDK, types, colle, main.rs) est mis à jour pour correspondre à la dernière spécification d'API. Si la surface SDK change (méthodes renommées, nouveaux sous-clients), mettez à jour votre custom.rs en conséquence.

Construction et test

# Construire la CLI (inclut les commandes personnalisées)
cargo build

# Exécuter votre commande personnalisée
acme-versioned <your-command> [args]

# Exécuter avec sortie détaillée pour déboguer
RUST_LOG=debug acme-versioned <your-command> [args]