AKIS - Appwrite CLI Tool

AKIS est un outil CLI qui synchronise automatiquement vos collections Appwrite avec vos types TypeScript. Définissez vos types une seule fois, et AKIS crée/met à jour vos collections et génère le schéma correspondant.

Fonctionnalités

• Génération automatique : Crée les collections Appwrite depuis vos types TypeScript
• Synchronisation : Détecte les différences entre vos types et Appwrite
• Schema auto-généré : Le fichier schema.ts est généré automatiquement lors de la migration
• Indexes automatiques : Crée les indexes pour les champs courants (storeId, email, etc.)
• Mode dry-run : Prévisualisez les changements avant de les appliquer

Installation

Avec npm

npm install @akis05/akis

Avec pnpm

pnpm add @akis05/akis

Installation globale (optionnel)

npm install -g @akis05/akis

Configuration

1. Variables d'environnement

Créez un fichier .env à la racine de votre projet:

# Endpoint Appwrite (Cloud ou Self-hosted)
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1

# ID de votre projet Appwrite
APPWRITE_PROJECT_ID=votre_project_id

# ID de votre base de données
APPWRITE_DATABASE_ID=votre_database_id

# Clé API avec permissions Database (Create, Read, Update, Delete)
APPWRITE_API_KEY=votre_api_key

2. Obtenir les identifiants Appwrite

1. Connectez-vous à Appwrite Console
2. Project ID : Settings → Project ID
3. Database ID : Databases → Cliquez sur votre DB → Settings
4. API Key : Settings → API Keys → Create API Key (cochez Database permissions)

Démarrage rapide

Étape 1 : Initialiser le projet

npx akis init

Cette commande crée la structure suivante:

core/
└── appwrite-model/
    ├── types.ts              # Vos définitions TypeScript
    ├── schema.ts             # Schéma généré (ne pas modifier manuellement)
    ├── client.ts             # Client Appwrite configuré
    └── setup-collections.ts  # Fonctions utilitaires

Étape 2 : Définir vos types

Éditez core/appwrite-model/types.ts:

export type Client = {
  _id: string;              // ID Appwrite (obligatoire)
  _creationTime: number;    // Timestamp création (obligatoire)
  nom: string;              // Champ requis
  email?: string;           // Champ optionnel (?)
  telephone?: string;
  statut: "actif" | "inactif";  // Enum
  tags?: string[];          // Array de strings
  storeId: string;
  createdAt: number;
  deletedAt?: number;
};

export type Produit = {
  _id: string;
  _creationTime: number;
  nom: string;
  prix: number;
  quantite: number;
  categorie: "electronique" | "vetement" | "alimentaire";
  storeId: string;
  createdAt: number;
};

Étape 3 : Migrer vers Appwrite

# Prévisualiser les changements (recommandé)
npx akis migrate --dry-run

# Créer les collections
npx akis migrate

Résultat :

• Collections créées dans Appwrite
• Fichier schema.ts généré automatiquement

Étape 4 : Vérifier le statut

npx akis status

Commandes

akis init

Initialise la structure du projet.

npx akis init           # Créer les fichiers
npx akis init --force   # Écraser les fichiers existants

Options:

akis migrate

Crée les collections manquantes dans Appwrite et génère schema.ts.

npx akis migrate                    # Migrer toutes les collections
npx akis migrate --name clients     # Migrer une collection spécifique
npx akis migrate --dry-run          # Prévisualiser sans exécuter

Options:

Exemple de sortie:

🚀 AKIS Migrate - Création des collections manquantes

📖 Lecture de types.ts...
   2 collection(s) à traiter

📡 Connexion à Appwrite...

📦 Création de clients...
   ✓ nom
   ✓ email
   ✓ telephone
   ✓ statut
   ✓ storeId
   🔑 idx_storeId
   🔑 idx_email
   ✅ clients créée

📝 schema.ts généré avec 2 collections

✨ Migration terminée: 1 créées, 1 ignorées

akis update

Ajoute les nouveaux attributs aux collections existantes.

npx akis update                    # Mettre à jour toutes les collections
npx akis update --name clients     # Mettre à jour une collection spécifique
npx akis update --dry-run          # Prévisualiser sans exécuter

Options:

Cas d'utilisation:

• Vous avez ajouté un nouveau champ dans types.ts
• Vous voulez synchroniser sans recréer la collection

akis status

Compare les types locaux avec les collections Appwrite.

npx akis status                    # Voir toutes les collections
npx akis status --name clients     # Voir une collection spécifique

Options:

Exemple de sortie:

📊 AKIS Status - État des collections

┌─────────────────────────────┬────────┬────────────┬─────────────┐
│ Collection                  │ Status │ Attributs  │ Manquants   │
├─────────────────────────────┼────────┼────────────┼─────────────┤
│ clients                     │ ✅     │ 9/9        │ 0           │
│ produits                    │ ⚠️     │ 5/7        │ 2           │
│ commandes                   │ ❌     │ -          │ -           │
└─────────────────────────────┴────────┴────────────┴─────────────┘

📈 Résumé:
   ✅ 1 synchronisées
   ⚠️  1 à mettre à jour (akis update)
   ❌ 1 manquantes (akis migrate)

akis delete

Supprime des collections dans Appwrite.

npx akis delete --name clients     # Supprimer une collection (avec confirmation)
npx akis delete --force            # Supprimer TOUTES les collections sans confirmation
npx akis delete --name clients -f  # Supprimer sans confirmation

Options:

⚠️ Attention : Cette action est irréversible !

Types TypeScript supportés

AKIS reconnaît automatiquement les types suivants:

Conventions de nommage

AKIS infère automatiquement certaines propriétés:

Champs système (ignorés)

Ces champs sont automatiquement ignorés car gérés par Appwrite:

• _id - ID du document
• _creationTime - Timestamp de création

Workflow recommandé

┌─────────────────────────────────────────────────────────────┐
│  1. Définir les types dans types.ts                        │
│     export type Client = { ... }                            │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Prévisualiser les changements                           │
│     npx akis migrate --dry-run                              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  3. Migrer vers Appwrite                                    │
│     npx akis migrate                                        │
│     → Collections créées + schema.ts généré                 │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  4. Vérifier la synchronisation                             │
│     npx akis status                                         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  5. Ajouter de nouveaux champs ? → Retour à l'étape 1       │
│     npx akis update                                         │
└─────────────────────────────────────────────────────────────┘

Utilisation avec pnpm

Si vous utilisez pnpm, ajoutez un script dans votre package.json:

{
  "scripts": {
    "akis": "akis"
  }
}

Puis utilisez:

pnpm akis status
pnpm akis migrate
pnpm akis update

Exemples

Exemple complet de types.ts

/* ═══════════════════════════════════════════════════════════
   Types pour mon application
   ═══════════════════════════════════════════════════════════ */

export type Client = {
  _id: string;
  _creationTime: number;
  nom: string;
  email?: string;
  telephone?: string;
  adresse?: string;
  statut: "actif" | "inactif" | "prospect";
  remise?: number;
  tags?: string[];
  storeId: string;
  createdAt: number;
  deletedAt?: number;
};

export type Produit = {
  _id: string;
  _creationTime: number;
  nom: string;
  description?: string;
  prix: number;
  prixAchat?: number;
  quantite: number;
  stockMin?: number;
  categorie: "electronique" | "vetement" | "alimentaire" | "autre";
  image?: string;
  storeId: string;
  createdAt: number;
};

export type Vente = {
  _id: string;
  _creationTime: number;
  numero: string;
  clientId?: string;
  lignes: string;  // JSON stringifié
  total: number;
  statut: "brouillon" | "validee" | "payee" | "annulee";
  storeId: string;
  createdAt: number;
};

// Utilitaires
export type NewDoc<T> = Omit<T, "_id" | "_creationTime">;
export type UpdateDoc<T> = Partial<Omit<T, "_id" | "_creationTime">>;

Dépannage

Erreur: APPWRITE_API_KEY non configurée

Vérifiez que votre fichier .env existe et contient la clé API:

cat .env | grep APPWRITE_API_KEY

Erreur: Collection non trouvée dans types.ts

Assurez-vous que le nom du type correspond à un nom reconnu par AKIS:

• Client → clients
• Produit → produits
• Vente → ventes

Les attributs ne sont pas créés

Appwrite a une limite de taille pour les attributs. Vérifiez:

• Taille des strings (max 16000 caractères)
• Nombre d'attributs par collection (max ~100)

License

MIT

Liens

• Appwrite Documentation
• npm Package
• GitHub Issues