PIE + pieUI — Guide complet des compétences agent

Référence complète pour les agents IA et les développeurs construisant des projets avec le framework PIE. Couvre les deux CLIs, toutes les commandes, les recettes de workflow, la politique d'enveloppe et les cas particuliers.

Table des matières

Architecture
Règles strictes — Ne jamais faire manuellement
CLI pieui — Toutes les commandes
CLI pie — Toutes les commandes
Politique d'enveloppe
Recettes de workflow
Cas particuliers
Configuration du projet & .gitignore
Guide des résultats check-sync
Aperçu et rendu des cartes
Points de terminaison Ajax, stored et la migration pieui 3.0.0
Backend Express — @swarm.ing/pieui/server
Temps réel — Récupération, statut du lien, partage d'abonnement

1. Architecture

PIE est un framework fullstack. Le frontend et le backend sont strictement séparés, chacun avec son propre CLI.

┌─────────────────────────────────────────────┐
│              Plateforme (pieui.swarm.ing)       │
│  username/my-project/MyCard                  │
│   ├── python/  ← poussé par le CLI pie       │
│   └── typescript/  ← poussé par le CLI pieui |
└─────────────────────────────────────────────┘
         ↑ push/pull          ↑ push/pull
┌────────────────┐   ┌────────────────────────┐
│  Backend        │   │  Frontend               │
│  Python/FastAPI │   │  TypeScript/Next.js     │
│  CLI pie        │   │  CLI pieui              │
│  pages/         │   │  piecomponents/         │
│  components/    │   │  app/                   │
└────────────────┘   └────────────────────────┘

Couche	Langage	CLI	Répertoires clés
Frontend	TypeScript / Next.js	`pieui`	`piecomponents/`, `app/`
Backend	Python / FastAPI	`pie`	`pages/`, `pages/components/`

Invocation du CLI :

node /path/to/pieui/dist/cli.js <cmd>
/path/to/pie/.venv/bin/pie <cmd>

2. Règles strictes — Ne jamais faire manuellement

Ces actions doivent passer par le CLI. Les faire manuellement casse le registre ou les métadonnées de la plateforme.

❌ Ne jamais faire manuellement	✅ Utiliser plutôt
Créer un fichier dans `piecomponents/`	`pieui card add ...`
Créer `app/<path>/page.tsx`	`pieui page add <path>`
Modifier `piecomponents/registry.ts`	Mis à jour automatiquement par `pieui card add/remove`
Créer `pages/components/*.py`	`pie card add ...`
Créer `pages/*.py`	`pie page add ...`
Ajouter une clé methods/event à `<PieCard methods={...}>`	`pieui add-event <Card> <event>`
Ajouter un événement IO à une carte Python	`pie card add-event <Card> <event>`
Supprimer un répertoire piecomponent	`pieui remove <ComponentName>`

Autres règles strictes :

"use client" — requis en haut de chaque fichier TSX de carte PIE.
<button type="button"> — toujours défini ; sans cela, le navigateur soumet vers /api/process/.
is_typed=False — requis dans chaque sous-classe AsyncPage qui ne redéfinit pas get_content.
Python snake_case → camelCase sur le frontend. send_label devient sendLabel. Correspondre à la fois dans les types TS et le code du composant.
Après avoir modifié web.py (en ajoutant une nouvelle route) — redémarrer le processus backend.
Ne jamais commiter .env, .pie/, .claude/, node_modules/, .next/, __pycache__/, .venv/.

3. CLI pieui — Toutes les commandes

3.1 Authentification

pieui login

Ouvre une URL de navigateur pour l'OAuth. En cas de succès, écrit { user_id, api_key, project } dans .pie/config.json et ajoute les variables à .env.

Quand : Avant toute opération card remote ou lors de la première configuration du projet. Remarque : Exécuter depuis la racine du projet pour que la configuration soit sauvegardée dans le bon .pie/config.json.

3.2 Init

pieui init [--out-dir <dir>]

Crée piecomponents/registry.ts. Requis une fois par nouveau projet frontend.

Drapeau	Défaut	Description
`--out-dir`, `-o`	`.`	Répertoire de base pour piecomponents

pieui init
pieui init --out-dir packages/app   # sous-paquet monorepo

3.3 Créer un projet

pieui create <AppName>          # génère l'application Next.js + exécute pieui init
pieui create-pie-app <AppName>  # modèle Next.js vierge uniquement
pieui create-pieui <AppName>    # alias pour create-pie-app

Quand : Démarrer un nouveau projet frontend à partir de zéro.

3.4 `page add`

pieui page add <path>

Génère app/<path>/page.tsx avec le wrapper Suspense standard PIE.

pieui page add dashboard
pieui page add wallet/send
pieui page add chat/room

Quand : Chaque nouvelle route. Une commande par page. Pas de drapeaux.

3.5 `card add`

pieui card add [type] <ComponentName> [--io] [--ajax]

Génère piecomponents/<ComponentName>/ avec index.ts, types/index.ts, ui/<ComponentName>.tsx. Met à jour piecomponents/registry.ts automatiquement.

Types :

Type	Signature des props	Quand l'utiliser
`simple`	`{ data }`	La carte affiche des données, sans enfants
`complex`	`{ data, children }`	La carte encapsule d'autres composants
`simple-container`	`{ data, content }`	La carte a un seul emplacement de contenu
`complex-container`	`{ data, content[] }`	La carte a plusieurs emplacements de contenu (défaut)

Drapeaux :

Drapeau	Ce qu'il ajoute
`--ajax`	Champs `pathname`, `depsNames`, `kwargs` à l'interface de données
`--io`	Champs de support temps réel / websocket

pieui card add simple ProfileCard
pieui card add complex-container LayoutCard
pieui card add simple LiveTickerCard --io
pieui card add simple ContactFormCard --ajax
pieui card add simple ChatCard --io --ajax

3.6 `card remove`

pieui remove <ComponentName>

Supprime piecomponents/<ComponentName>/ et retire l'entrée de registry.ts.

Quand : Supprimer un composant. Ne jamais supprimer manuellement.

3.7 `list`

pieui list [filter] [--src-dir <dir>]

Affiche un tableau de tous les composants enregistrés : Nom, Type, Type de données, Lazy, Fichier.

Filtre	Affiche
(aucun)	Tous
`simple`	Simples uniquement
`complex`	Complexes uniquement
`simple-container`	Conteneurs simples
`complex-container`	Conteneurs complexes

pieui list
pieui list simple
pieui list complex-container --src-dir app

3.8 `list-events`

pieui list-events <ComponentName> [--src-dir <dir>]

Affiche toutes les clés methods déclarées dans <PieCard card="X" methods={...} /> pour le composant.

Quand : Avant d'ajouter un nouvel événement (pour éviter les doublons) ; pour auditer la surface d'événements d'une carte.

3.9 `add-event`

pieui add-event <ComponentName> <event> [--src-dir <dir>]

Ajoute une nouvelle clé avec un gestionnaire par défaut à <PieCard ... methods={{ <event>: handler }}> dans le TSX.

pieui add-event ContactFormCard submit
pieui add-event ChatCard message

Quand : Ajouter des gestionnaires d'événements à une carte existante. Toujours utiliser ceci — ne jamais modifier methods manuellement.

3.10 `postbuild`

pieui postbuild [--out-dir <dir>] [--src-dir <dir>] [--append]

Scanne piecomponents et génère un manifeste JSON pour les builds SSR / production.

Drapeau	Défaut	Description
`--out-dir`, `-o`	`public`	Répertoire de sortie pour le manifeste
`--src-dir`, `-s`	`src`	Répertoire source à scanner
`--append`	désactivé	Inclure les composants pieui intégrés dans le manifeste

Quand : Fait partie de l'étape de build de production (next build).

3.11 `card remote push`

pieui card remote push <ComponentName>

Téléverse piecomponents/<ComponentName>/ vers la plateforme sous l'enveloppe typescript/. Assigne une nouvelle révision @N.

Quand : Après avoir implémenté ou mis à jour une carte. Remarque : Chaque push crée une nouvelle révision immuable. Les anciennes révisions restent téléchargeables avec @N.

3.12 `card remote pull`

pieui card remote pull <ComponentName>[@rev]
pieui card remote pull <project>/<ComponentName>[@rev]
pieui card remote pull r/<user>/<ComponentName>

Télécharge un composant dans piecomponents/. Écrase les fichiers locaux.

Forme	Accès
`MyCard`	Dernière version du projet actuel
`MyCard@7`	Révision spécifique du projet actuel
`other-proj/MyCard`	Un autre projet du même utilisateur
`r/username/MyCard`	Composant public de n'importe quel utilisateur

pieui card remote pull ProfileCard
pieui card remote pull ProfileCard@3
pieui card remote pull r/someuser/PriceTickerCard

3.13 `card remote list`

pieui card remote list [--user <U>] [--project <S>]

Liste les noms des composants stockés sur la plateforme.

Remarque : --user / --project fonctionne seulement si votre clé API a accès à ce projet.

3.14 `card remote history`

pieui card remote history <ComponentName> [--page N] [--per-page N] [--from R] [--to R]

Affiche l'historique des révisions avec les diffs par fichier (style git). Inclut les fichiers des enveloppes python/ et typescript/.

Drapeau	Défaut	Description
`--page`	1	Numéro de page
`--per-page`	10	Révisions par page
`--from`	—	Numéro de révision de début
`--to`	—	Numéro de révision de fin

pieui card remote history ProfileCard
pieui card remote history ProfileCard --from 3 --to 7

Quand : Auditer ce qui a changé entre les pushes ; déboguer les régressions ; vérifier que les deux enveloppes ont été poussées.

3.15 `card remote public / private`

pieui card remote public <ComponentName>   # accessible en tant que r/username/MyCard
pieui card remote private <ComponentName>  # revenir en privé

3.16 `card remote remove`

pieui card remote remove <ComponentName>

Supprime le composant de la plateforme (toutes les révisions). Ne touche pas aux fichiers locaux.

4. CLI pie — Toutes les commandes

4.1 Authentification

pie login

Même flux OAuth que pieui. Écrit dans .pie/config.json dans le répertoire de travail et ajoute au .env.

Critique : Exécuter depuis la racine du projet backend. pie lit .pie/config.json relativement au répertoire de travail. Si les variables d'environnement PIE_USER_ID, PIE_API_KEY, PIE_PROJECT sont définies, elles ont priorité sur le fichier de configuration.

4.2 `page add`

pie page add <path>

Crée pages/<slug>.py avec une sous-classe AsyncPage.

pie page add dashboard
pie page add wallet/send

Quand : Chaque nouvelle route backend. Ensuite, enregistrer la page dans web.py et redémarrer le serveur.

4.3 `card add`

pie card add <type> <ComponentName> [--io] [--ajax] [--input] [--from REF]

Crée pages/components/<snake_name>.py avec une dataclass Card.

pie card add simple ProfileCard
pie card add complex ChatCard

Le type est requis ici. Contrairement à pieui card add, l'omettre est une erreur argparse — les choix de pie sont simple, complex, container, complex-container (note container, alors que pieui dit simple-container).

--from REF porte depuis le frontend : un fichier .ts/.tsx, un répertoire piecomponents, un fichier PieMetadata .json, ou un nom de carte nu résolu via frontendComponentsDir`. Omettre et il se résout automatiquement par nom lorsqu'un projet frontend est configuré.

Quand : En même temps que pieui card add — les deux côtés doivent exister.

4.4 `card list`

pie card list

Affiche un tableau : Nom, Type, Ajax, IO, Chemin du fichier.

4.5 `card view`

pie card view <ComponentName>

Affiche de manière formatée le tableau des props d'une carte (nom du champ, type Python, valeur par défaut) plus les indicateurs Ajax / IO / Événements.

pie card view ProfileCard

Quand : Inspection rapide du contrat d'une carte sans ouvrir le fichier.

4.6 `card dump-metadata`

pie card dump-metadata <ComponentName> [--out <file.json>]

Sort les métadonnées JSON complètes au format enveloppe Python :

{
  "python": {
    "name": "MyCard",
    "propsSchema": { "properties": { ... }, "type": "object" },
    "propsCode": "@dataclass\nclass MyCard...",
    "ajaxList": ["pathname"],
    "events": [],
    "eventsPropsCode": {},
    "eventsPropsSchema": {},
    "inputPropsCode": null,
    "inputPropsSchema": null,
    "files": [{ "path": "my_card.py", "content": "..." }],
    "packages": ["pie"]
  }
}

Drapeau	Défaut	Description
`--out`, `-o`	stdout	Écrire le JSON dans un fichier

pie card dump-metadata ProfileCard
pie card dump-metadata ProfileCard --out /tmp/profile_card_meta.json

Les types de prop importés depuis des modules locaux au projet sont résolus. Une prop typée avec un objet de valeur défini dans un module frère n'est plus sérialisée comme un schéma opaque — la résolution est purement parcours AST + système de fichiers sous la racine du projet, et rien n'est importé à l'exécution. Deux limites : en cas de conflit de nom, la classe du même fichier gagne, et les chaînes d'import ne sont pas suivies (seules les dépendances directes du fichier de la carte sont visibles, donc une dataclass importée par un module importé reste opaque).

4.7 `card check-sync`

pie card check-sync [ComponentName]

Compare le schéma des props Python (local) avec le schéma des props TypeScript (depuis frontendProjectDir) champ par champ.

ComponentName est optionnel — l'omettre et chaque carte dans le répertoire de composants est vérifiée. Le mode batch affiche [pie] {n}/{total} carte(s) désynchronisée(s) : <noms> ou [pie] Toutes les {n} cartes alignées ✓. Code de sortie 0 = toutes alignées, 1 = une constatation quelconque ou une carte qui a échoué à construire/dumper.

Il utilise le CLI frontend — bun $PIE_CHECK_SYNC_PIEUI_CLI (surcharge de variable d'environnement pointant vers un cli.ts/cli.js local), puis bunx pieui, puis npx pieui — et exige strictement un retour {"typescript": …} de l'enveloppe de pieui card dump-metadata. Un pieui obsolète qui ne l'émet pas fait échouer chaque carte, et sans bunx ni npx dans le PATH, vous obtenez [pie] Ni bunx ni npx trouvé dans le PATH.

Les props Python int ne signalent plus un type_mismatch erroné contre un TypeScript number.

Trouvailles :

Trouvaille	Signification	Actions correctives
`missing_field`	Le champ existe dans un schéma mais pas dans l'autre	Ajouter le champ manquant des deux côtés
`type_mismatch`	Les types diffèrent	Aligner les types pour correspondre
`default_value_mismatch`	Les valeurs par défaut diffèrent (seulement pour les props sans `required`)	Aligner les valeurs par défaut
`list: item_type_mismatch`	Un type de champ de liste diffère du côté Python ou TS	Aligner les types d'items de la liste
`dict: key_type_mismatch`	Le type de la clé du dictionnaire ne correspond pas dans la prop `dict`	Assurer que le type de la clé correspond
`dict: value_type_mismatch`	Le type de la valeur du dictionnaire ne correspond pas dans la prop `dict`	Assurer que le type de la valeur correspond
`optionality_mismatch`	Un champ est optionnel d'un côté mais pas de l'autre	Ajouter ou retirer required

Quand : Avant de pousser une mise à jour de carte ; comme vérification CI.

4.8 `card add-event`

pie card add-event <ComponentName> <event>

Ajoute une nouvelle clé d'événement à la définition du gestionnaire de la dataclass Card Python, avec la signature def handle_<event>(self, payload).

pie card add-event ProfileCard save
pie card add-event ChatCard send_message

Quand : En même temps que pieui add-event — les deux côtés doivent être synchronisés. Ne jamais ajouter un événement à une carte Python sans l'ajouter à la carte TSX en premier.

4.9 `card remove-event`

pie card remove-event <ComponentName> <event>

Supprime une clé d'événement de la dataclass Python et nettoie les gestionnaires.

4.10 `card push enveloppe`

pie card push <ComponentName>

Téléverse pages/components/<snake_name>.py vers la plateforme sous l'enveloppe python/. Assigne une nouvelle révision @N.

Quand : Après des modifications. Nécessite que la carte ait déjà été poussée depuis le frontend.

4.11 `card pull enveloppe`

pie card pull <ComponentName>[@rev]
pie card pull <project>/<ComponentName>[@rev]
pie card pull r/<username>/<ComponentName>

Télécharge la version la plus récente de l'enveloppe Python de la plateforme. Écrase les fichiers locaux.

Remarque : r/<username> pour les composants publics.

4.12 `card dump full`

pie card dump <ComponentName>

Affiche la dataclass Python complète telle que stockée dans le registre. Utile pour le débogage ou la restauration.

5. Politique d'enveloppe

Les deployments PIE utilisent deux enveloppes : python/ (backend) et typescript/ (frontend).

Règles d'enveloppe :

pie card push téléverse seulement l'enveloppe python/.
pieui card remote push téléverse seulement l'enveloppe typescript/.
Chaque push crée une nouvelle révision immuable sur la plateforme.
La première révision d'une carte doit être poussée depuis le frontend (pieui card remote push) avant que le backend puisse pousser son enveloppe.
Une carte sur la plateforme contient les deux enveloppes, chaque enveloppe ayant son propre historique de révisions.
pieui card remote history <MyCard> montre les deux enveloppes dans une chronologie unifiée, avec des entrées mélangées (par ordre de timestamp).

6. Recettes de workflow

6.1 Créer un composant

# 1. Démarrer sur le frontend
cd <projet-frontend>
pieui login
pieui card add simple MyCard --ajax
# 2. Implémenter le composant dans piecomponents/MyCard/
# 3. Pousser la carte vers la plateforme
pieui card remote push MyCard
# 4. Passer au backend
cd <projet-backend>
pie login
pie card add simple MyCard --from MyCard  # ou résolu automatiquement
# 5. Implémenter le backend dans pages/components/my_card.py
# 6. Pousser l'enveloppe backend
pie card push MyCard

6.2 Mettre à jour un composant

cd <projet-frontend>
# 1. Apporter des modifications au fichier TSX et/ou au type
# 2. Pousser la nouvelle révision frontend
pieui card remote push MyCard

cd <projet-backend>
# 3. Mettre à jour le backend (si nécessaire)
# 4. Pousser la nouvelle révision backend
pie card push MyCard

6.3 Synchronisation avant déploiement

cd <projet-backend>
pie card check-sync MyCard
# Si non aligné, corriger les différences d'un côté ou des deux

6.4 Retirer un composant (ne pas utiliser)

cd <projet-backend>
pie card remove-event MyCard <event>   # si applicable
pie card push MyCard                    # pousser l'enveloppe mise à jour (l'événement est supprimé)

cd <projet-frontend>
pieui remove MyCard                    # supprimer les fichiers locaux ET l'entrée du registre
pieui card remote remove MyCard         # supprimer de la plateforme (toutes les révisions)

7. Cas particuliers

7.1 Conflit de noms de dépôt

Si vous avez un dépôt nommé pie, le CLI peut confondre les noms des dépôts avec les commandes. Utilisez toujours des chemins absolus ou un alias.

7.2 Variables d'environnement manquantes

Si pie login échoue de manière inattendue, vérifiez que les variables d'environnement PIE_USER_ID, PIE_API_KEY, PIE_PROJECT ne sont pas définies avec des valeurs de test.

7.3 Migration des révisions

Lors du passage de pieui v1 à v2, les révisions sont réinitialisées. Poussez à nouveau toutes les cartes.

7.4 Actions CI

En CI, utilisez PIE_CHECK_SYNC_PIEUI_CLI pour pointer vers le chemin absolu du CLI pieui. Ne pas utiliser npx, car npm peut ne pas être installé.

7.5 Cartes sans implémentation backend

Une carte peut être purement frontend (sans enveloppe Python). Dans ce cas, pie card push est omis, mais pieui card remote push est toujours requis.

7.6 Défaillance de dump-metadata

Si pie card dump-metadata échoue avec une erreur de résolution AST, vérifiez que le fichier de la dataclass importe uniquement depuis des modules accessibles (pas d'imports cycliques ou manquants).

8. Configuration du projet & .gitignore

.gitignore obligatoire

.env
.pie/
.claude/
node_modules/
.next/
__pycache__/
.venv/
*.pyc
.next/

Structure du projet

Projet frontend :

mon-app/
├── .pie/config.json       # Fichier de configuration (créé par login)
├── .env                    # Variables d'environnement (créé par login)
├── piecomponents/
│   ├── registry.ts
│   └── MyCard/
│       ├── index.ts
│       ├── types/index.ts
│       └── ui/MyCard.tsx
└── app/
    └── dashboard/
        └── page.tsx

Projet backend :

mon-api/
├── .pie/config.json
├── .env
├── pages/
│   ├── dashboard.py
│   └── components/
│       └── my_card.py
└── web.py                 # Point d'entrée FastAPI avec enregistrement des routes

9. Guide des résultats check-sync

(Tel que décrit dans la section 4.7)

10. Aperçu et rendu des cartes

Pour prévisualiser une carte localement sans déploiement :

# Frontend
cd <projet-frontend>
npm run dev
# Navigateur : http://localhost:3000
# L'aperçu se trouve dans le répertoire piecomponents avec un préfixe __preview__

Rendu des cartes : Le rendu final est fait sur le serveur à l'aide du manifeste généré par pieui postbuild. En mode développement, le manifeste est généré à la volée.

11. Points de terminaison Ajax, `stored` et la migration pieui 3.0.0

Points de terminaison Ajax : Les cartes avec le drapeau --ajax reçoivent des données via des appels Ajax (GET/POST) configurés par depsNames, kwargs et pathname. Les chemins des points de terminaison Ajax sont automatiquement enregistrés par le backend.

stored : Le champ stored dans les données de la carte persiste les données sur le serveur entre les rendus. Utile pour maintenir l'état de l'interface utilisateur à travers les mises à jour.

Migration pieui 3.0.0 : Les changements clés incluent des schémas de props plus stricts, un nouveau format d'enveloppe et la dépréciation des anciens formats de point de terminaison Ajax. Utilisez pie login et pieui login pour vous réauthentifier et mettez à jour tous les fichiers de carte pour utiliser la nouvelle signature de type.

12. Backend Express — `@swarm.ing/pieui/server`

Pour les projets n'utilisant pas FastAPI, PIE fournit un serveur Express en option (@swarm.ing/pieui/server). Il sert les manifestes et gère les points de terminaison Ajax. L'API est la suivante :

import { createPieServer } from '@swarm.ing/pieui/server';

const app = createPieServer({
  // options
});

app.listen(3001);

Ce serveur est utile pour les applications monolithiques Next.js qui ont besoin de fonctionnalités backend sans configurer un backend Python séparé.

13. Temps réel — Récupération, statut du lien, partage d'abonnement

Récupération : Les canaux temps réel (websocket) peuvent être récupérés automatiquement après une brève déconnexion réseau. Configurez les délais d'attente de récupération dans la configuration du composant.

Statut du lien : Les cartes avec IO (--io) fournissent des indicateurs de statut de connexion (connecté, déconnecté, reconnexion). Utilisez-les dans l'interface utilisateur pour informer l'utilisateur de la connectivité en temps réel.

Partage d'abonnement : Plusieurs cartes ou pages peuvent partager un seul abonnement websocket pour éviter les connexions en double. Le partage d'abonnement est géré automatiquement dans le backend.

Commandes :

Gérez les événements temps réel avec pieui add-event et pie card add-event comme décrit ci-dessus.

Demander à votre IA préférée

Documentation

PIE + pieUI — Guide complet des compétences agent

Table des matières

1. Architecture

2. Règles strictes — Ne jamais faire manuellement

3. CLI pieui — Toutes les commandes

3.1 Authentification

3.2 Init

3.3 Créer un projet

3.4 page add

3.5 card add

3.6 card remove

3.7 list

3.8 list-events

3.9 add-event

3.10 postbuild

3.11 card remote push

3.12 card remote pull

3.13 card remote list

3.14 card remote history

3.15 card remote public / private

3.16 card remote remove