DevPodode

Une librairie Node.js TypeScript pour communiquer de manière programmatique avec la DevPod CLI. DevPodode vous permet de gérer vos environnements de développement DevPod directement depuis votre code Node.js.

🚀 Fonctionnalités

• ✅ Gestion complète des workspaces : créer, démarrer, arrêter, supprimer
• ✅ Gestion des providers : ajouter, supprimer, lister, mettre à jour
• ✅ Support du streaming : sortie en temps réel des commandes
• ✅ Types TypeScript : support complet des types
• ✅ Gestion d'erreurs robuste : exceptions personnalisées
• ✅ Tests unitaires : couverture complète
• ✅ Exemples d'utilisation : cas d'usage pratiques

📦 Installation

npm install devpodode

🔧 Prérequis

Assurez-vous que DevPod CLI est installé sur votre système.

🎯 Utilisation rapide

import { DevPodClient } from 'devpodode';

const devpod = new DevPodClient();

// Créer un workspace
await devpod.up('mon-workspace', {
  ide: 'vscode',
  provider: 'docker',
  ideOptions: {
    VERSION: 'latest'
  }
});

// Lister les workspaces
const workspaces = await devpod.listWorkspaces();
console.log(workspaces);

// Arrêter un workspace
await devpod.down('mon-workspace');

📚 Documentation complète

Initialisation

import { DevPodClient } from 'devpodode';

// Utilisation par défaut (devpod dans le PATH)
const devpod = new DevPodClient();

// Avec un chemin personnalisé vers DevPod
const devpod = new DevPodClient('/custom/path/to/devpod');

Gestion des Workspaces

Créer un workspace

// Workspace basique
await devpod.up('mon-workspace');

// Workspace avec options complètes
await devpod.up('mon-workspace', {
  ide: 'vscode',
  provider: 'docker',
  ideOptions: {
    VERSION: 'latest',
    EXTENSIONS: 'ms-python.python,ms-vscode.vscode-typescript-next'
  },
  providerOptions: {
    IMAGE: 'ubuntu:20.04',
    CPU: '2',
    MEMORY: '4Gi'
  },
  source: 'https://github.com/user/repo',
  workingDir: '/workspace'
});

Workspace avec streaming

await devpod.upWithStream(
  'mon-workspace',
  (data: string) => {
    console.log(`[STREAM] ${data}`);
  },
  {
    ide: 'vscode',
    provider: 'docker'
  }
);

Gestion du cycle de vie

// Vérifier le statut
const status = await devpod.getWorkspaceStatus('mon-workspace');
console.log(status); // { id: '1', name: 'mon-workspace', status: 'Running', ... }

// Lister tous les workspaces
const workspaces = await devpod.listWorkspaces();
console.log(workspaces);

// Arrêter un workspace
await devpod.down('mon-workspace');

// Supprimer un workspace
await devpod.delete('mon-workspace');

Build et logs

// Construire un workspace
await devpod.build('mon-workspace');

// Construire avec streaming
await devpod.buildWithStream('mon-workspace', (data) => {
  console.log(`[BUILD] ${data}`);
});

// Obtenir les logs
const logs = await devpod.getLogs('mon-workspace');

// Logs en streaming
await devpod.getLogsWithStream('mon-workspace', (data) => {
  console.log(`[LOG] ${data}`);
}, true); // follow = true

SSH

// SSH simple
await devpod.ssh({ workspace: 'mon-workspace' });

// SSH avec commande
await devpod.ssh({
  workspace: 'mon-workspace',
  command: 'ls -la',
  user: 'root'
});

Gestion des Providers

// Lister les providers
const providers = await devpod.listProviders();

// Ajouter un provider
await devpod.addProvider('docker');

// Ajouter un provider depuis une source
await devpod.addProvider('custom-provider', 'https://github.com/user/custom-provider');

// Obtenir les informations d'un provider
const provider = await devpod.getProvider('docker');

// Mettre à jour un provider
await devpod.updateProvider('docker');

// Utiliser un provider par défaut
await devpod.useProvider('docker');

// Supprimer un provider
await devpod.removeProvider('docker');

Utilitaires

// Vérifier la disponibilité de DevPod
const isAvailable = await devpod.isAvailable();

// Obtenir la version de DevPod
const version = await devpod.getVersion();
console.log(version); // "devpod version 0.1.0"

// Méthodes utilitaires pour les workspaces
const workspaceNames = await devpod.getWorkspaceNames();
const workspaceExists = await devpod.workspaceExists('mon-workspace');
const creationDate = await devpod.getWorkspaceCreationDate('mon-workspace');
const lastUsed = await devpod.getWorkspaceLastUsed('mon-workspace');
const ide = await devpod.getWorkspaceIDE('mon-workspace');
const provider = await devpod.getWorkspaceProvider('mon-workspace');
const source = await devpod.getWorkspaceSource('mon-workspace');

// Méthodes utilitaires pour les providers
const providerNames = await devpod.getProviderNames();
const providerExists = await devpod.providerExists('docker');

Interprétation des données JSON

DevPodode utilise automatiquement le flag --output json pour obtenir des données structurées :

// Les workspaces retournent un tableau d'objets avec toutes les propriétés
const workspaces = await devpod.listWorkspaces();
workspaces.forEach(workspace => {
  console.log(`Workspace: ${workspace.id}`);
  console.log(`Provider: ${workspace.provider.name}`);
  console.log(`IDE: ${workspace.ide.name}`);
  console.log(`Créé le: ${new Date(workspace.creationTimestamp).toLocaleString()}`);
  console.log(`Repository: ${workspace.source?.gitRepository || 'Aucun'}`);
});

// Les providers retournent un objet avec les noms comme clés
const providers = await devpod.listProviders();
Object.entries(providers).forEach(([name, provider]) => {
  console.log(`Provider: ${name}`);
  console.log(`Version: ${provider.config.version}`);
  console.log(`Description: ${provider.config.description}`);
  console.log(`Initialisé: ${provider.state.initialized}`);
  console.log(`Par défaut: ${provider.default}`);
});

🎨 Exemples d'utilisation

Exemple complet de cycle de vie

import { DevPodClient } from 'devpodode';

async function gestionWorkspace() {
  const devpod = new DevPodClient();
  const workspaceName = 'mon-projet';

  try {
    // Vérifier que DevPod est disponible
    if (!(await devpod.isAvailable())) {
      throw new Error('DevPod CLI non disponible');
    }

    // Créer le workspace
    console.log('Création du workspace...');
    await devpod.up(workspaceName, {
      ide: 'vscode',
      provider: 'docker',
      ideOptions: { VERSION: 'latest' }
    });

    // Vérifier le statut
    const status = await devpod.getWorkspaceStatus(workspaceName);
    console.log('Statut:', status?.status);

    // Construire le workspace
    console.log('Construction du workspace...');
    await devpod.build(workspaceName);

    // Exécuter une commande via SSH
    const result = await devpod.ssh({
      workspace: workspaceName,
      command: 'echo "Hello from workspace!"'
    });
    console.log('Résultat SSH:', result.output);

  } catch (error) {
    console.error('Erreur:', error.message);
  } finally {
    // Nettoyage
    try {
      await devpod.down(workspaceName);
      await devpod.delete(workspaceName);
      console.log('Workspace supprimé');
    } catch (error) {
      console.error('Erreur lors du nettoyage:', error.message);
    }
  }
}

gestionWorkspace();

Gestion des providers

import { DevPodClient } from 'devpodode';

async function gestionProviders() {
  const devpod = new DevPodClient();

  // Lister les providers existants
  const providers = await devpod.listProviders();
  console.log('Providers disponibles:', providers.map(p => p.name));

  // Ajouter Docker si pas présent
  if (!providers.find(p => p.name === 'docker')) {
    console.log('Ajout du provider Docker...');
    await devpod.addProvider('docker');
  }

  // Mettre à jour tous les providers
  for (const provider of providers) {
    try {
      await devpod.updateProvider(provider.name);
      console.log(`Provider ${provider.name} mis à jour`);
    } catch (error) {
      console.error(`Erreur lors de la mise à jour de ${provider.name}:`, error.message);
    }
  }
}

gestionProviders();

🧪 Tests

# Exécuter les tests
npm test

# Tests en mode watch
npm run test:watch

# Couverture de code
npm test -- --coverage

🔧 Développement

# Cloner le repository
git clone https://github.com/TomBedinoVT/devpodode.git
cd devpodode

# Installer les dépendances
npm install

# Compiler TypeScript
npm run build

# Linter
npm run lint

# Linter avec correction automatique
npm run lint:fix

📋 Types TypeScript

Structure des Workspaces

interface DevPodWorkspace {
  id: string;                    // Nom du workspace
  uid: string;                   // Identifiant unique
  provider: {
    name: string;                // Nom du provider (docker, kubernetes, etc.)
    options: Record<string, { value?: string }>; // Options du provider
  };
  machine: Record<string, any>;  // Informations de la machine
  ide: {
    name: string;                // IDE utilisé (vscode, cursor, etc.)
  };
  source?: {
    gitRepository?: string;      // Repository Git source
  };
  creationTimestamp: string;     // Date de création (ISO 8601)
  lastUsed: string;              // Dernière utilisation (ISO 8601)
  context: string;               // Contexte DevPod
}

Structure des Providers

interface DevPodProvider {
  config: {
    name: string;                // Nom du provider
    version: string;             // Version du provider
    description: string;         // Description
    options: Record<string, {    // Options disponibles
      description: string;
      global?: boolean;
      default?: string;
    }>;
    agent: {                     // Configuration de l'agent
      local: string;
      docker: {
        path: string;
        install: string;
        builder?: string;
        env?: Record<string, string>;
      };
      // ... autres configurations
    };
  };
  state: {
    initialized: boolean;        // État d'initialisation
    singleMachine: boolean;      // Machine unique
    options: Record<string, { value?: string }>; // Options configurées
    creationTimestamp: string;   // Date de création
  };
  default: boolean;              // Provider par défaut
}

Options de création de workspace

interface DevPodUpOptions {
  ide?: string;
  ideOptions?: Record<string, string>;
  provider?: string;
  providerOptions?: Record<string, string>;
  prebuildRepositories?: string[];
  source?: string;
  workingDir?: string;
}

🚨 Gestion des erreurs

import { DevPodClient, DevPodError } from 'devpodode';

const devpod = new DevPodClient();

try {
  await devpod.up('mon-workspace');
} catch (error) {
  if (error instanceof DevPodError) {
    console.error('Erreur DevPod:', error.message);
    console.error('Code de sortie:', error.exitCode);
    console.error('Commande:', error.command);
  } else {
    console.error('Erreur inattendue:', error);
  }
}

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

1. Fork le projet
2. Créer une branche pour votre fonctionnalité (git checkout -b feature/AmazingFeature)
3. Commit vos changements (git commit -m 'Add some AmazingFeature')
4. Push vers la branche (git push origin feature/AmazingFeature)
5. Ouvrir une Pull Request

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🔗 Liens utiles

• DevPod Documentation
• DevPod GitHub
• Issues

📞 Support

Si vous rencontrez des problèmes ou avez des questions :

1. Vérifiez les issues existantes
2. Créez une nouvelle issue avec les détails de votre problème
3. Assurez-vous que DevPod CLI est correctement installé et configuré

Fait avec ❤️ par TomBedinoVT