Metadata-Version: 2.5
Name: rankapp-cli
Version: 0.0.1.post1
Summary: Personnalisez et prévisualisez votre site RankApp avec votre éditeur, votre assistant IA et Git.
Project-URL: Homepage, https://rankapp.io
Project-URL: Documentation, https://pypi.org/project/rankapp-cli/#description
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Requires-Python: >=3.12
Requires-Dist: babel<3,>=2.17
Requires-Dist: keyring<26,>=25.6
Description-Content-Type: text/markdown

# RankApp CLI

**Personnalisez le thème de votre site RankApp depuis votre éditeur ou avec
votre assistant IA.** Récupérez le thème et les données de votre catalogue,
modifiez les fichiers en local, puis envoyez votre travail avec Git pour le
vérifier dans un aperçu RankApp.

La CLI donne accès à **un site précis, pour une durée limitée**, avec les droits
accordés par son propriétaire. L'envoi du thème met à jour le brouillon ; la
mise en ligne fait l'objet d'une commande distincte.

[Premiers pas](#premiers-pas) · [Modifier le thème](#modifier-le-thème) ·
[Pages et menus](#pages-et-menus) · [Commandes](#commandes) ·
[Dépannage](#dépannage) · [Accès et sécurité](#accès-et-sécurité)

## Avant de commencer

- Un site RankApp et un **jeton d'accès à ce site**, généré dans RankApp.
- [Git](https://git-scm.com/downloads) et
  [uv](https://docs.astral.sh/uv/getting-started/installation/) installés.
- Python **3.12 ou plus récent** pour exécuter la CLI.
- Un trousseau de mots de passe accessible à la session : Trousseau sur macOS,
  gestionnaire d'identifiants sur Windows, ou un service compatible avec
  [keyring](https://keyring.readthedocs.io/en/latest/) sur Linux.

Un compte PyPI n'est pas nécessaire pour installer ou utiliser RankApp CLI.
Le jeton demandé par `rankapp site login` provient de **RankApp**, pas de PyPI.

## Premiers pas

### 1. Installer la CLI

```sh
uv tool install --upgrade rankapp-cli
rankapp --version
```

L'installation fournit deux exécutables : `rankapp` et `git-remote-rankapp`.
Le second permet à Git de communiquer avec votre site ; Git l'appelle pour vous.

Si le terminal ne trouve pas `rankapp`, exécutez `uv tool update-shell`, puis
ouvrez un nouveau terminal. Les deux exécutables doivent être dans le `PATH`.

### 2. Connecter votre site

Dans la personnalisation de votre site dans RankApp, générez le prompt d'accès
destiné à votre assistant. Il contient la commande de connexion, les droits
accordés et la date d'expiration. Utilisez la commande fournie ou remplacez la
valeur ci-dessous par votre jeton :

```sh
rankapp site login "VOTRE_JETON_RANKAPP"
```

La CLI valide l'accès auprès de RankApp et conserve le jeton dans le trousseau
du système. Ne l'ajoutez pas aux fichiers de votre site.

### 3. Récupérer le thème et le catalogue

Placez-vous dans le dossier qui accueillera votre projet, puis lancez :

```sh
rankapp site pull
```

La commande crée un dossier portant le nom de votre site, avec le thème, un
dépôt Git sur la branche `main`, le remote `rankapp`, un export du catalogue
pour l'aperçu local et un fichier **`AGENTS.md`**.

Entrez dans le dossier créé — `ma-boutique` est un exemple — et ouvrez
`AGENTS.md` dans votre éditeur avant toute modification :

```sh
cd ma-boutique
rankapp site check
```

`AGENTS.md` décrit les règles du site, la syntaxe des champs, les langues et
les budgets. Un contrôle réussi renvoie un objet JSON avec `"valid": true`.

Pour choisir le dossier de destination, utilisez `rankapp site pull mon-dossier`.
Ce dossier doit être absent ou vide.

### 4. Modifier et voir le résultat

Depuis le dossier du site :

```sh
rankapp site dev
```

Ouvrez **[http://127.0.0.1:4600](http://127.0.0.1:4600)**. Modifiez le thème dans
votre éditeur, puis actualisez la page : les fichiers sont relus à chaque
requête. Aucun serveur Node.js n'est nécessaire.

Cette commande reste active. Gardez ce terminal ouvert et utilisez-en un
second dans le même dossier pour les commandes suivantes, ou arrêtez le
serveur avec **Ctrl+C**.

L'aperçu utilise les données récupérées lors du `pull`. Il permet de vérifier
les pages et leur présentation ; les comptes clients, le panier et le paiement
dépendent des services en ligne. Certains médias distants nécessitent également
une connexion. L'aperçu RankApp permet de vérifier les interactions disponibles,
comme la recherche et le panier ; **le paiement y est désactivé**.

### 5. Envoyer le brouillon et obtenir un aperçu

Après vos modifications, vérifiez le thème et relisez votre diff avant de
créer un commit :

```sh
rankapp site check
git diff
git status --short
git add -A
git diff --cached
git commit -m "Personnaliser le thème de la boutique"
git push rankapp main
rankapp site preview
```

Le push envoie les fichiers de thème modifiés et les suppressions. RankApp
valide et compile le brouillon. `preview` renvoie un **lien temporaire** et sa
date d'expiration ; ouvrez ce lien complet pour vérifier le résultat ou le
faire valider au propriétaire du site.

### 6. Publier après validation

**Cette commande demande la mise en ligne du brouillon.** Exécutez-la uniquement
après validation explicite du propriétaire, avec un jeton autorisant
`site:publish` et un abonnement Site autorisant la publication :

```sh
rankapp site publish
```

La réponse contient l'identifiant et l'état de la compilation. La CLI n'attend
pas sa réussite : suivez son état dans RankApp, puis ouvrez le site public
pour confirmer que la mise en ligne est terminée.

| Action | Résultat |
| --- | --- |
| `rankapp site check` | Contrôle les fichiers locaux. |
| `rankapp site dev` | Affiche le thème local avec le catalogue récupéré. |
| `git push rankapp main` | Met à jour le brouillon sur RankApp. |
| `rankapp site preview` | Crée un lien temporaire vers l'aperçu du brouillon. |
| `rankapp site publish` | Lance la publication du brouillon, à suivre dans RankApp. |

## Modifier le thème

La structure exacte dépend du thème récupéré. Les dossiers reconnus sont :

```text
ma-boutique/
├── AGENTS.md       Règles et syntaxe propres au site
├── assets/         CSS, JavaScript, SVG et images
├── blocks/         Blocs du thème
├── config/         Configuration et réglages du thème
├── layout/         Structure générale des pages
├── locales/        Textes traduits du thème
├── sections/       Sections réutilisables
├── snippets/       Fragments Liquid réutilisables
└── templates/      Modèles de pages, en Liquid ou JSON selon le thème
```

### Déclarer un champ éditable

Dans un template Liquid, le tag `field` déclare un champ et affiche sa valeur :

```liquid
<h1>{% field title | input, required %}</h1>
<p>{% field introduction | textarea %}</p>
```

Les contrôles disponibles sont `input`, `textarea`, `richtext`, `image` et
`post`. Les modificateurs `required` et `shared` rendent respectivement un
champ obligatoire ou commun aux langues. **`text` n'est pas un contrôle valide.**

Les pages proposées par le thème utilisent les déclarations Liquid `page` et
`field_default`. Leur syntaxe, leurs contenus par défaut et les règles de
traduction figurent dans `AGENTS.md`. Préservez les chemins de templates et
les noms des champs pour conserver leur association aux contenus enregistrés.

### Formats et budgets

| Limite | Valeur |
| --- | --- |
| Nombre de fichiers de thème | 2 000 maximum |
| Taille d'un fichier | 1 Mio maximum, soit 1 048 576 octets |
| Taille totale du thème | 25 Mio maximum, soit 26 214 400 octets |
| Fichiers texte | `.liquid`, `.json`, `.css`, `.js`, `.svg`, `.txt` |
| Images dans `assets/` | `.avif`, `.gif`, `.jpeg`, `.jpg`, `.png`, `.webp` |

Les images comptent dans les budgets. Les liens symboliques sont refusés.
`check` valide les fichiers, la syntaxe et les champs localement ; le serveur
effectue aussi ses contrôles lors du push, notamment sur les références des
pages. Consultez les pages existantes avant de supprimer ou renommer un modèle.

## Pages et menus

Les fichiers du thème définissent la présentation. Les **contenus des pages**
sont enregistrés dans RankApp et se consultent depuis le dossier du site :

```sh
rankapp site pages list
rankapp site pages get "IDENTIFIANT_DE_PAGE"
```

`list` renvoie les pages et les schémas des templates ; `get` permet de retrouver
une page précise. Les sorties sont au format JSON.

Pour créer, modifier ou supprimer des pages personnalisées, utilisez
**l'application RankApp**. Les commandes `pages save` et `pages delete` sont
présentes dans l'aide, mais les jetons temporaires de site décrits dans ce guide
ne sont actuellement pas autorisés à les utiliser par l'API.

Les pages proposées par le thème se déclarent dans les templates avec `page`
et `field_default` ; consultez `AGENTS.md` pour ce parcours. Les menus se gèrent
également dans l'application RankApp.

## Commandes

Exécutez les commandes de travail depuis le dossier du site, sauf `login`,
`logout` et le premier `pull`.

| Commande | Usage |
| --- | --- |
| `rankapp --version` | Affiche les versions de la CLI et du moteur de rendu. |
| `rankapp site login "JETON"` | Valide et enregistre l'accès au site. |
| `rankapp site logout` | Retire l'accès du trousseau et la configuration locale active. |
| `rankapp site pull [dossier]` | Crée un nouveau dépôt local avec le thème et le catalogue. |
| `rankapp site check` | Vérifie le thème local. |
| `rankapp site dev` | Démarre l'aperçu sur le port 4600. |
| `rankapp site preview` | Crée un lien d'aperçu temporaire. |
| `rankapp site publish` | Lance la publication, si le droit a été accordé. |
| `rankapp site pages list` | Consulte les pages et les templates. |
| `rankapp site pages get "ID"` | Consulte une page par son identifiant. |

L'aide est disponible à chaque niveau :

```sh
rankapp --help
rankapp site --help
rankapp site pages get --help
```

## Dépannage

### La commande `rankapp` ou `git-remote-rankapp` est introuvable

Exécutez `uv tool update-shell`, puis ouvrez un nouveau terminal. Vérifiez
l'installation avec `rankapp --version` et `uv tool list`.

### Le dossier existe déjà — `WORKSPACE_NOT_EMPTY`

`rankapp site pull` crée un nouveau dépôt ; il ne met pas à jour un dossier
existant. Pour reprendre un thème déjà récupéré, entrez dans son dossier et
utilisez Git.

Pour obtenir un **catalogue local actualisé**, récupérez le site dans un nouveau
dossier. `git pull rankapp main` synchronise le thème, sans rafraîchir l'export
du catalogue. Conservez vos modifications locales avant de changer de dossier.

### Le push est refusé parce que le brouillon a changé

Committez d'abord vos modifications locales, puis récupérez le thème distant :

```sh
git pull --no-rebase rankapp main
```

Si Git signale des conflits, résolvez-les, vérifiez le résultat, puis terminez
la fusion avec `git add` et `git commit`. Relancez ensuite :

```sh
rankapp site check
git push rankapp main
```

Le remote accepte uniquement `main` et refuse les pushes forcés.

### Un fichier hors thème bloque le push — `THEME_PATH_INVALID`

En plus d'`AGENTS.md` et de `.gitignore`, seuls les fichiers des dossiers de
thème sont acceptés dans le commit envoyé. Placez vos notes, exports et
fichiers de travail locaux dans `.rankapp/`, déjà ignoré par Git, et vérifiez
`git diff --cached` avant de committer.

### Le jeton a expiré, a été révoqué ou n'a pas le droit nécessaire

Générez un nouvel accès dans RankApp et relancez `rankapp site login`.
Une connexion à un autre site remplace le profil actif : reconnectez le bon
site en cas de `SITE_MISMATCH`. Un accès autorisant le brouillon ou l'aperçu
n'autorise pas nécessairement la publication.

### Le trousseau n'est pas disponible — `KEYRING_UNAVAILABLE`

Déverrouillez le trousseau de votre session. Sur Linux, vérifiez qu'un service
de secrets compatible est disponible. Un conteneur ou une session distante
sans trousseau demande une configuration adaptée ; la CLI ne se rabat pas sur
un stockage du jeton en clair.

### Le port est occupé — `DEV_PORT_IN_USE`

Le port de l'aperçu est **4600**. Réutilisez le serveur s'il correspond à votre
projet, ou arrêtez l'instance que vous avez lancée avec Ctrl+C. Un autre port
n'est pas pris en charge par cette version.

### Le format du catalogue n'est pas reconnu — `SNAPSHOT_VERSION_UNSUPPORTED`

Mettez à jour la CLI avec `uv tool install --upgrade rankapp-cli`, puis récupérez
le site dans un nouveau dossier. Pour remplacer une ancienne installation de
développement locale, utilisez `uv tool install --reinstall rankapp-cli`.

## Accès et sécurité

- Le jeton est limité à un site, aux droits accordés et à sa date d'expiration.
- Le jeton est conservé dans le trousseau ; ne le copiez ni dans un dépôt Git,
  ni dans un fichier partagé, ni dans une documentation publique.
- Le dépôt contient un export local du catalogue. Traitez ce dossier comme
  des données de votre site et ne le publiez pas dans un dépôt public.
- Aucun identifiant AWS n'est nécessaire. Les transferts de fichiers utilisent
  des autorisations temporaires fournies par RankApp.
- Un assistant IA doit respecter le périmètre donné par le propriétaire et
  demander sa validation avant `rankapp site publish`.
- `logout` supprime l'accès de cette machine. Il n'efface pas les fichiers
  récupérés et ne révoque pas le jeton côté RankApp.

Lorsque vous avez terminé :

```sh
rankapp site logout
```

## Liens utiles

- [RankApp](https://rankapp.io)
- [Versions et fichiers du paquet sur PyPI](https://pypi.org/project/rankapp-cli/)
- [Installer uv](https://docs.astral.sh/uv/getting-started/installation/)
- [Configurer le trousseau système avec keyring](https://keyring.readthedocs.io/en/latest/)

Licence : MIT.
