@deckflow/deckuse 1.2.1 → 1.3.1

package/README.fr.md

@@ -0,0 +1,342 @@
+<div align="center">
+
+# Deckuse
+
+[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![pnpm 10](https://img.shields.io/badge/pnpm-10-F69220?logo=pnpm&logoColor=white)](https://pnpm.io/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![PPTX](https://img.shields.io/badge/Format-PPTX-B7472A?logo=microsoftpowerpoint&logoColor=white)](#pptx-capabilities)
+
+[English](README.md) · [简体中文](README.zh-CN.md) · [Français](README.fr.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Русский](README.ru.md) · [Español](README.es.md) · [Português](README.pt-BR.md)
+
+</div>
+
+Deckuse est un moteur local-first et piloté par schéma pour automatiser les documents Office avec des agents de code. Il ouvre un document dans un espace de travail versionné, permet à un agent d’inspecter et de cibler sa structure, applique des commandes JSON explicites, valide le résultat, puis exporte un nouveau document.
+
+PPTX et DOCX sont implémentés. Les adaptateurs XLSX, Keynote et Numbers renvoient volontairement `FORMAT_NOT_IMPLEMENTED` : ils ne sont pas encore des cibles d’édition prises en charge.
+
+Ce dépôt est l’**édition community** (`edition=community`). Voir [docs/edition.md](docs/edition.md). L’édition commerciale vit dans le dépôt séparé `deckuse-commercial`.
+
+## Agent Skill (à installer en premier)
+
+Deckuse est conçu pour les agents. **Installez le skill Deckuse avant d’utiliser le CLI** — il encode la boucle workspace-first, le `apply` par lot, les adresses sémantiques, les unités et les recettes à haute valeur.
+
+- Skill : [`skills/deckuse/SKILL.md`](skills/deckuse/SKILL.md)
+- Cursor (projet) : copier ou lier vers `.cursor/skills/deckuse/`
+- Cursor (personnel) : copier ou lier vers `~/.cursor/skills/deckuse/`
+
+Nécessite **CLI `deckuse >= 1.2.0`**. Référence rapide : [docs/agent-cookbook.md](docs/agent-cookbook.md).
+
+## Pourquoi Deckuse
+
+Deckuse permet de modifier une présentation existante sans la recréer. Sans fichier source, `deckuse new` initialise un espace de travail à partir du modèle vide fourni. Son flux de travail privilégie volontairement la structure plutôt que le rendu visuel :
+
+```text
+existing.pptx → init ─┐
+                      ├→ list / get → set / add → validate → export
+blank template → new ─┘
+```
+
+Chaque écriture réussie commit automatiquement une révision Git, met à jour `operations.jsonl` et reconstruit `package.pptx`. Utilisez `undo` pour annuler des écritures et `history` pour consulter le journal des opérations.
+
+Il préserve autant que possible le XML intact et les parties inconnues du package. Ce n’est pas un moteur de rendu PowerPoint complet : utilisez `monitor` pour un aperçu HTML en direct et `render` pour capturer une diapositive en PNG. Les `diff` / `branch` sémantiques restent différés.
+
+## Installation
+
+Prérequis : Node.js 18 ou ultérieur.
+
+```sh
+npm install -g @deckflow/deckuse
+```
+
+Cette commande installe globalement le CLI `deckuse`.
+
+```sh
+# Créer un espace de travail persistant depuis une présentation.
+deckuse init input.pptx ./workspace --json
+
+# Ou démarrer depuis le modèle vide fourni (pas besoin de input.pptx).
+deckuse new ./workspace --json
+
+# Inspecter le document indexé et interroger les éléments ciblés.
+deckuse inspect ./workspace --json
+deckuse query ./workspace 'kind=textbox text=Quarter' --json
+deckuse query ./workspace '*' --limit 500 --json
+
+# Appliquer une commande JSON, un tableau JSON ou du JSONL.
+deckuse apply ./workspace --input operations.jsonl --json
+
+# Valider l'espace de travail, consulter l'historique et annuler des écritures.
+deckuse validate ./workspace --json
+deckuse history ./workspace --json
+deckuse undo ./workspace --steps 1 --json
+```
+
+## Flux de travail CLI
+
+`apply` accepts a transaction file (`{ "operations": [...] }`), a single JSON mutation, a JSON array, or JSON Lines. One invocation can apply many write commands; multiple commands run as one atomic batch. Use `--input -` (the default) to read from standard input. Legacy ElementRef mutations remain supported. Commands passed to `apply` do not need `version`, `workspaceId`, or `transactionId`: the CLI supplies them.
+
+Les résultats sont écrits en JSON sur la sortie standard ; les erreurs d’arguments ou d’entrée sont écrites sur la sortie d’erreur. Le code `0` indique la réussite, `1` l’échec d’une commande et `2` une erreur d’usage ou d’analyse CLI.
+
+### Sélecteurs
+
+Prefer `search text` / `search shape` and `list` for Phase 1a inventory. `query` remains available for back-compat and accepts either a selector string or a structured selector in a command. Space-separated terms are combined with AND.
+
+| Syntax                                 | Meaning                                              |
+| -------------------------------------- | ---------------------------------------------------- |
+| `*` or `all`                           | Match every indexed element.                         |
+| `kind=textbox`                         | Match an element kind by case-insensitive substring. |
+| `text=Quarter`                         | Match text that contains the literal value.          |
+| `text~=pattern`                        | Match text with a Unicode regular expression.        |
+| `hasText=true`                         | Match elements that contain text.                    |
+| `slide=256`, `id=256:10`, `name=Title` | Filter by slide ID, element ID, or name.             |
+
+Query results provide stable element references. A reference includes a document ID and an element ID or structural path; array positions are not stable identifiers.
+
+## Flux de travail courants pour les agents
+
+Ces exemples utilisent uniquement les fonctionnalités PPTX actuelles. Ils décrivent des flux de travail qu’un agent peut composer à partir des primitives de Deckuse, sans prétendre que Deckuse effectue lui-même du raisonnement, de la rédaction ou une révision visuelle.
+
+### 1. Mettre à jour une année obsolète dans une présentation
+
+**Demande :** « Remplacez chaque référence à `FY2025` par `FY2026`, sans rien modifier d’autre. »
+
+Utilisez d’abord `query` pour examiner les éléments concernés, puis exécutez un `replaceText` littéral et validez avant l’exportation.
+
+```sh
+deckuse init master.pptx ./year-update --json
+deckuse query ./year-update 'text=FY2025' --limit 1000 --json
+cat > year-update.json <<'EOF'
+{
+  "type": "replaceText",
+  "find": "FY2025",
+  "replace": "FY2026"
+}
+EOF
+deckuse apply ./year-update --input year-update.json --json
+deckuse validate ./year-update --json
+```
+
+Une fois l'écriture terminée, `./year-update/package.pptx` est reconstruit automatiquement comme dernier instantané.
+
+La requête de revue limite la modification aux occurrences connues ; `replaceText` effectue la mutation groupée approuvée tout en laissant les objets sans rapport intacts. Sans selector, il met à jour les nœuds texte indexés les plus spécifiques plutôt que les conteneurs ancêtres qui agrègent le texte descendant.
+
+### 2. Renommer une entreprise ou un produit
+
+**Demande :** « Remplacez partout l’ancien nom du produit par le nouveau. »
+
+Il s’agit du même modèle sûr de revue puis remplacement. Recherchez d’abord le nom exact à remplacer, puis utilisez `replaceText` avec une valeur littérale. Pour les variantes telles que la ponctuation ou les espaces, n’utilisez un remplacement par expression régulière qu’après avoir vérifié la sortie de la requête.
+
+```json
+{
+  "type": "replaceText",
+  "find": "Legacy Platform",
+  "replace": "Unified Platform"
+}
+```
+
+Pour une modification plus restreinte, ajoutez un sélecteur dans la commande, par exemple `"selector": "slide=256"`, afin qu’une seule diapositive soit éligible.
+
+### 3. Extraire le plan d’une présentation pour un agent
+
+**Demande :** « Listez les titres des diapositives et résumez le contenu de cette présentation. »
+
+Exécutez `inspect` pour récupérer la structure indexée de la présentation, puis interrogez les objets contenant du texte. L’agent appelant peut regrouper les objets retournés par ID de diapositive, identifier les objets qui ressemblent à des titres d’après leur nom, leur position ou leur texte, puis générer un résumé à partir du texte extrait.
+
+```sh
+deckuse init briefing.pptx ./outline --json
+deckuse inspect ./outline --depth 2 --json
+deckuse query ./outline 'hasText=true' --limit 10000 --json
+```
+
+Deckuse fournit les données sources structurées. C’est l’agent, et non Deckuse, qui détermine quel texte est un titre et qui rédige le résumé.
+
+### 4. Effectuer un contrôle qualité du contenu avant livraison
+
+**Demande :** « Avant l’envoi de cette présentation, trouvez les anciens noms de clients, dates, noms de produits, URL et le texte de clause de non-responsabilité requis. »
+
+Interrogez chaque risque connu et examinez les références retournées. Les vérifications d’absence fonctionnent de la même façon : recherchez le texte requis et signalez un résultat vide. Un agent peut produire un rapport de QA sans modifier la présentation, ou préparer des commandes `setText` / `replaceText` étroitement ciblées pour des corrections approuvées.
+
+```sh
+deckuse query ./workspace 'text=Customer A' --limit 1000 --json
+deckuse query ./workspace 'text~=https?://' --limit 1000 --json
+deckuse query ./workspace 'text=Required disclaimer' --limit 1000 --json
+```
+
+Il s’agit d’une QA de contenu et de structure, non d’une QA visuelle. Utilisez `render` / `monitor` uniquement comme aide à la revue ; Deckuse ne détecte pas les chevauchements et ne juge pas la qualité de mise en page.
+
+### 5. Modifier exactement un élément sur une diapositive
+
+**Demande :** « Sur la diapositive 7, remplacez le titre par `Enterprise Strategy` ; ne modifiez rien d’autre. »
+
+Interrogez d’abord cette diapositive et le texte du titre, puis prenez le `ref` retourné et envoyez une commande `setText`. Le `ref` évite un remplacement global ambigu.
+
+```json
+{
+  "type": "setText",
+  "ref": {
+    "documentId": "./workspace",
+    "elementId": "256:10"
+  },
+  "text": "Enterprise Strategy"
+}
+```
+
+Les ID d’élément sont des exemples propres à une présentation. Utilisez toujours un ID retourné par l’espace de travail actuel au lieu de recopier cette valeur.
+
+### 6. Uniformiser la typographie des titres
+
+**Demande :** « Réglez tous les titres approuvés sur 28 pt et utilisez la police approuvée. »
+
+Utilisez une requête pour identifier les objets de titre, faites examiner ou filtrer par l’agent les références retournées, puis appliquez `setProperties` une fois pour chaque référence approuvée. `setProperties` cible une référence à la fois ; il n’accepte pas lui-même de sélecteur.
+
+```json
+{
+  "type": "setProperties",
+  "ref": {
+    "documentId": "./workspace",
+    "elementId": "256:8"
+  },
+  "properties": {
+    "fontSize": 28,
+    "fontFamily": "Approved Sans",
+    "bold": true
+  }
+}
+```
+
+La même commande peut définir `fill`, `stroke` (ainsi que `border`, `outline` ou `line`), `textColor`, `italic`, `underline`, `name` et `hidden`. Les clés de propriété inconnues échouent avec `INVALID_COMMAND`.
+
+### 7. Ajuster précisément la géométrie d’un objet
+
+**Demande :** « Déplacez légèrement vers le bas chaque titre approuvé. »
+
+Interrogez et sélectionnez les références de titre visées, inspectez leur géométrie actuelle et émettez une commande `setTransform` par objet avec des coordonnées explicites. Il s’agit d’une opération structurelle de géométrie ; ne la présentez pas comme une correction automatique de mise en page sans validation visuelle.
+
+```json
+{
+  "type": "setTransform",
+  "ref": {
+    "documentId": "./workspace",
+    "elementId": "256:8"
+  },
+  "transform": {
+    "x": 914400,
+    "y": 731520,
+    "width": 8229600,
+    "height": 685800
+  }
+}
+```
+
+Les coordonnées de transformation sont des EMU OOXML. Conservez `x`, `width` et `height` de l’objet inspecté lorsque vous ne modifiez que sa position verticale.
+
+### 8. Personnaliser une présentation commerciale approuvée
+
+**Demande :** « Créez une version pour un prospect. Mettez à jour le nom du client et le texte approuvé propre au compte, tout en préservant le design. »
+
+Créez un espace de travail distinct pour chaque résultat à partir du modèle maître approuvé. Interrogez les espaces réservés ou le texte client existant, appliquez uniquement les remplacements examinés, validez, puis utilisez le `package.pptx` mis à jour automatiquement.
+
+```sh
+deckuse init approved-master.pptx ./customer-a --json
+deckuse query ./customer-a 'text=Customer Name' --json
+# Appliquez uniquement les remplacements examinés pour ce client.
+deckuse apply ./customer-a --input customer-a.jsonl --json
+deckuse validate ./customer-a --json
+```
+
+Des espaces de travail séparés empêchent les modifications d’un client de se retrouver dans la sortie d’un autre. Ne remplacez que les objets que le processus d’approbation autorise l’agent à modifier.
+
+### 9. Produire des variantes régionales ou par audience depuis un même modèle maître
+
+**Demande :** « Générez des variantes régionales et enterprise à partir de la présentation approuvée. »
+
+Initialisez un nouvel espace de travail depuis le même modèle maître pour chaque variante. Chaque variante reçoit son propre fichier de commandes et son propre chemin de sortie.
+
+Prefer `apply` with a JSON array, JSONL, or `{ "operations": [...] }`: multiple write commands in one invocation run as one atomic batch (if one fails, none persist). The protocol `batch` command form remains supported.
+
+```json
+[
+  {
+    "type": "replaceText",
+    "find": "Default Message",
+    "replace": "Regional Message"
+  },
+  {
+    "type": "replaceText",
+    "find": "Default Offer",
+    "replace": "Enterprise Offer"
+  }
+]
+```
+
+```sh
+deckuse apply ./regional --input regional.json --json
+```
+
+Cela préserve une source unique approuvée tout en rendant chaque variante reproductible à partir d’un ensemble explicite de modifications.
+
+### 10. Permettre à un agent de code d’opérer une présentation existante
+
+**Demande :** « Inspectez cette présentation, identifiez les modifications demandées, effectuez-les et exportez un PPTX révisé. »
+
+Donnez à l’agent cette boucle : initialiser un espace de travail, inspecter ou interroger avant chaque modification ciblée, générer des commandes JSON explicites, les appliquer, valider le package et utiliser le `package.pptx` reconstruit comme export. Lorsque l’auditabilité importe, conservez le fichier de commandes et les résultats des commandes avec la tâche.
+
+Deckuse fournit à l’agent des références stables, des sélecteurs, des transactions, une validation et un chemin d’exportation déterministe. L’agent interprète la tâche et décide quelles opérations sont appropriées.
+
+### Exemple de `setProperties`
+
+```json
+{
+  "type": "setProperties",
+  "ref": { "documentId": "./workspace", "elementId": "256:8" },
+  "properties": {
+    "stroke": { "color": "0000FF", "width": 1.5 },
+    "fill": "none",
+    "textColor": "111111",
+    "fontSize": 18,
+    "fontFamily": "Approved Sans",
+    "bold": true
+  }
+}
+```
+
+`stroke` and `fill` accept a hexadecimal color string. Use `none`, `false`, or `null` for no stroke or fill. `stroke.width` is in points and defaults to `1`.
+
+## Fonctionnalités PPTX
+
+- Persistent workspaces, revision-conflict detection, dry runs, atomic batches, and an operation log.
+- `inspect`, `list`, `get`, `search`, and back-compat `query` / `getText`; stable references include slide ID, part URI, cNvPr ID, and ancestor path when available.
+- `setText` and `replaceText`, including literal or regular-expression replacement in an optional selector scope. Without a selector, `replaceText` prefers leaf text nodes over ancestor containers that aggregate descendant text. Newlines in `setText` become separate paragraphs.
+- `setTransform` for explicit object position, size, rotation, and flip changes.
+- `setProperties` for common shape and text properties, including `paragraph.align`, `paragraph.level`, `bullet`, `fill` transparency, and `hyperlink`.
+- Add, duplicate, remove, and rebind slides to another layout (`setSlideLayout` / `deckuse set slide-layout`); layout refs accept index, `layout:N`, `slide:N`, display name, or basename. Rebind updates the relationship only (does not edit layout parts). Duplicated slides clone mutable notes and chart parts while layouts and media can be shared safely.
+- Add shapes/text boxes (optional `role` writes a `p:ph` placeholder), connectors, groups, pictures (from a file path or base64), tables, charts (cache-only), and embedded video/audio; duplicate or remove elements.
+- `role` must be an OOXML placeholder type (`title`, `body`, `subTitle`, `ctrTitle`, …). Common aliases like `subtitle`→`subTitle` are normalized; non-OOXML labels (for example `card`) are rejected so PowerPoint does not prompt to repair.
+- Address placeholders with `slide:N/placeholder:<type>` (for example `title`, `body`, `subTitle`, `ctrTitle`).
+- `replacePicture` replaces a picture’s embedded media in place while retaining its element reference and layer order.
+- Table-cell addressing by table ID, row, and column; table row/column insert and delete via `setProperties`; cell `fill`; speaker-note reading and text editing (notes parts are created automatically when writing `slide:N/notes` if missing).
+- Create charts (`bar` / `column` / `line` / `pie`) and edit chart title, series-name, and cached values. When an embedded workbook exists, Deckuse emits `EMBEDDED_WORKBOOK_NOT_SYNCHRONIZED` rather than claiming that workbook data was updated. Advanced charts (other families, combo, ChartEx) are preserve-only in the community edition.
+- List and resolve master, layout, and theme parts; community edition rejects writes to those parts (`UNSUPPORTED_CAPABILITY`). Master/layout editing is available in the commercial edition repository.
+- `monitor` for live HTML preview and `render` for single-slide PNG screenshots (office2html + Playwright).
+- Preservation of unknown parts and untouched nodes. ZIP files are recompressed, so fidelity is defined by uncompressed data for untouched entries rather than ZIP byte identity.
+
+## Limites
+
+- Deckuse does not implement the full PowerPoint DrawingML surface, animation editing, SmartArt editing, OLE editing, or macro editing.
+- It is not a full PowerPoint rendering or layout engine. `monitor` and `render` provide HTML/PNG review aids only; do not rely on them to assess visual quality, detect overlap, or automatically improve slide design.
+- Chart edits update OOXML chart caches only; embedded Excel workbooks are not rewritten.
+- Duplicated slides clone notes and chart parts and reuse layouts, themes, and media. Complex custom XML extensions are retained but not edited semantically.
+- `setText` and `replaceText` collapse multi-run text in the targeted node into one run while retaining the first run’s style.
+
+## Vérifications de développement
+
+```sh
+pnpm format:check
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+For the complete canonical English documentation and command wording, see [README.md](README.md).