@inwink-mcp/backoffice-extension-helpers 1.0.12 → 1.0.14

package/README.md

@@ -75,7 +75,21 @@ Contrôles effectués :
 - `extension.manifest.json` présent, `name` (slug) et `version` (semver) valides ;
 - `dist/` contient `index.html` + `extension.manifest.json` à la racine + `assets/` ;
 - le zip contient `index.html` et `extension.manifest.json` à la racine, sans `node_modules/`, `src/` ni `dist/` ;
-- avertissements : `base: './'` absent de `vite.config.ts`, usage de `BrowserRouter`.
+- avertissements : `base: './'` absent de `vite.config.ts`, usage de `BrowserRouter`, `docs/inwink-api/` différent de la doc de cette version de la CLI.
+
+### `update-docs`
+
+Met à jour la doc API d'une extension **déjà générée** : `docs/inwink-api/` est remplacé en miroir par celui de cette version (fichiers ajoutés, modifiés, et supprimés s'ils ont disparu du template). Rien d'autre n'est touché, la commande peut être relancée sans risque.
+
+```bash
+npx @inwink-mcp/backoffice-extension-helpers@latest update-docs
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dir <path>` | Dossier du projet (défaut : dossier courant) |
+
+Ce dossier appartient à la CLI : une modification locale est écrasée au prochain `update-docs`. `AGENTS.md` et le code du squelette ne sont pas mis à jour.
 
 ## Templates
 

package/dist/cli.js

@@ -340,12 +340,70 @@ function bootstrap(opts) {
 }
 
 // src/commands/pack.ts
-import path7 from "path";
+import path8 from "path";
 
 // src/lib/verify.ts
+import fs5 from "fs";
+import path6 from "path";
+import AdmZip from "adm-zip";
+
+// src/lib/docs.ts
 import fs4 from "fs";
 import path5 from "path";
-import AdmZip from "adm-zip";
+var DOCS_REL_DIR = "docs/inwink-api";
+var DOCS_TEMPLATE = "vite-extension";
+var UPDATE_DOCS_COMMAND = "npx @inwink-mcp/backoffice-extension-helpers@latest update-docs";
+function templateDocsDir() {
+  return path5.join(templatesRoot, DOCS_TEMPLATE, DOCS_REL_DIR);
+}
+function listFiles(root, current = root) {
+  if (!fs4.existsSync(current)) return [];
+  const files = [];
+  for (const entry of fs4.readdirSync(current, { withFileTypes: true })) {
+    const full = path5.join(current, entry.name);
+    if (entry.isDirectory()) files.push(...listFiles(root, full));
+    else files.push(path5.relative(root, full).split(path5.sep).join("/"));
+  }
+  return files.sort();
+}
+function readNormalized(file) {
+  return fs4.readFileSync(file, "utf8").replaceAll("\r\n", "\n");
+}
+function diffDocs(projectDir) {
+  const src = templateDocsDir();
+  const dest = path5.join(projectDir, DOCS_REL_DIR);
+  const srcFiles = listFiles(src);
+  const destFiles = new Set(listFiles(dest));
+  const diff = { added: [], changed: [], removed: [] };
+  for (const rel of srcFiles) {
+    if (!destFiles.has(rel)) diff.added.push(rel);
+    else if (readNormalized(path5.join(src, rel)) !== readNormalized(path5.join(dest, rel))) {
+      diff.changed.push(rel);
+    }
+    destFiles.delete(rel);
+  }
+  diff.removed = [...destFiles];
+  return diff;
+}
+function isDocsUpToDate(diff) {
+  return diff.added.length + diff.changed.length + diff.removed.length === 0;
+}
+function syncDocs(projectDir) {
+  const diff = diffDocs(projectDir);
+  const src = templateDocsDir();
+  const dest = path5.join(projectDir, DOCS_REL_DIR);
+  for (const rel of [...diff.added, ...diff.changed]) {
+    const target = path5.join(dest, rel);
+    fs4.mkdirSync(path5.dirname(target), { recursive: true });
+    fs4.copyFileSync(path5.join(src, rel), target);
+  }
+  for (const rel of diff.removed) {
+    fs4.rmSync(path5.join(dest, rel));
+  }
+  return diff;
+}
+
+// src/lib/verify.ts
 function verifyExtension(options) {
   const { projectDir, requireDist = false } = options;
   const errors = [];
@@ -366,40 +424,49 @@ function verifyExtension(options) {
   } catch (err) {
     errors.push(err.message);
   }
-  const distDir = path5.join(projectDir, "dist");
-  if (!fs4.existsSync(distDir)) {
+  const distDir = path6.join(projectDir, "dist");
+  if (!fs5.existsSync(distDir)) {
     if (requireDist) {
       errors.push("Dossier dist/ introuvable apr\xE8s le build.");
     }
   } else {
-    if (!fs4.existsSync(path5.join(distDir, "index.html"))) {
+    if (!fs5.existsSync(path6.join(distDir, "index.html"))) {
       errors.push("dist/index.html manquant.");
     }
-    if (!fs4.existsSync(path5.join(distDir, "extension.manifest.json"))) {
+    if (!fs5.existsSync(path6.join(distDir, "extension.manifest.json"))) {
       errors.push("dist/extension.manifest.json manquant (le plugin Vite doit le copier).");
     }
-    const assetsDir = path5.join(distDir, "assets");
-    if (!fs4.existsSync(assetsDir) || !fs4.statSync(assetsDir).isDirectory()) {
+    const assetsDir = path6.join(distDir, "assets");
+    if (!fs5.existsSync(assetsDir) || !fs5.statSync(assetsDir).isDirectory()) {
       warnings.push("dist/assets/ introuvable \u2014 build Vite incomplet ?");
     }
   }
   const zipPath = resolveZipPath(options, projectDir, name, version);
-  if (zipPath && fs4.existsSync(zipPath)) {
+  if (zipPath && fs5.existsSync(zipPath)) {
     verifyZip(zipPath, errors);
   } else if (options.zipPath) {
     errors.push(`Zip introuvable : ${options.zipPath}`);
   }
   checkViteBase(projectDir, warnings);
   checkRouter(projectDir, warnings);
+  checkDocs(projectDir, warnings);
   return { errors, warnings };
 }
+function checkDocs(projectDir, warnings) {
+  const diff = diffDocs(projectDir);
+  if (isDocsUpToDate(diff)) return;
+  const count = diff.added.length + diff.changed.length + diff.removed.length;
+  warnings.push(
+    `${DOCS_REL_DIR}/ diff\xE8re de la doc API actuelle (${count} fichier(s)). Mettez-la \xE0 jour avec : ${UPDATE_DOCS_COMMAND}`
+  );
+}
 function resolveZipPath(options, projectDir, name, version) {
   if (options.zipPath) {
-    return path5.isAbsolute(options.zipPath) ? options.zipPath : path5.join(projectDir, options.zipPath);
+    return path6.isAbsolute(options.zipPath) ? options.zipPath : path6.join(projectDir, options.zipPath);
   }
   if (name && version) {
-    const candidate = path5.join(projectDir, `${name}-${version}.zip`);
-    return fs4.existsSync(candidate) ? candidate : void 0;
+    const candidate = path6.join(projectDir, `${name}-${version}.zip`);
+    return fs5.existsSync(candidate) ? candidate : void 0;
   }
   return void 0;
 }
@@ -408,7 +475,7 @@ function verifyZip(zipPath, errors) {
   try {
     entries = new AdmZip(zipPath).getEntries();
   } catch (err) {
-    errors.push(`Impossible de lire le zip ${path5.basename(zipPath)} : ${err.message}`);
+    errors.push(`Impossible de lire le zip ${path6.basename(zipPath)} : ${err.message}`);
     return;
   }
   const names = entries.map((e) => e.entryName.split("\\").join("/"));
@@ -429,60 +496,60 @@ function verifyZip(zipPath, errors) {
   }
 }
 function checkViteBase(projectDir, warnings) {
-  const file = path5.join(projectDir, "vite.config.ts");
-  if (!fs4.existsSync(file)) return;
-  const content = fs4.readFileSync(file, "utf8");
+  const file = path6.join(projectDir, "vite.config.ts");
+  if (!fs5.existsSync(file)) return;
+  const content = fs5.readFileSync(file, "utf8");
   if (!/base:\s*['"]\.\/['"]/.test(content)) {
     warnings.push("vite.config.ts : `base: './'` introuvable \u2014 les assets risquent de casser apr\xE8s d\xE9ploiement.");
   }
 }
 function checkRouter(projectDir, warnings) {
-  const srcDir = path5.join(projectDir, "src");
-  if (!fs4.existsSync(srcDir)) return;
+  const srcDir = path6.join(projectDir, "src");
+  if (!fs5.existsSync(srcDir)) return;
   if (sourceUsesBrowserRouter(srcDir)) {
     warnings.push("Usage de BrowserRouter d\xE9tect\xE9 \u2014 utilisez HashRouter pour l'h\xE9bergement versionn\xE9.");
   }
 }
 function sourceUsesBrowserRouter(dir) {
-  for (const entry of fs4.readdirSync(dir, { withFileTypes: true })) {
-    const full = path5.join(dir, entry.name);
+  for (const entry of fs5.readdirSync(dir, { withFileTypes: true })) {
+    const full = path6.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (sourceUsesBrowserRouter(full)) return true;
     } else if (/\.(tsx?|jsx?)$/.test(entry.name)) {
-      if (/\bBrowserRouter\b/.test(fs4.readFileSync(full, "utf8"))) return true;
+      if (/\bBrowserRouter\b/.test(fs5.readFileSync(full, "utf8"))) return true;
     }
   }
   return false;
 }
 
 // src/lib/zip.ts
-import fs5 from "fs";
-import path6 from "path";
+import fs6 from "fs";
+import path7 from "path";
 import AdmZip2 from "adm-zip";
 function createSourceZip(projectDir) {
   const sourceZip = new AdmZip2();
-  const rootFiles = fs5.readdirSync(projectDir);
+  const rootFiles = fs6.readdirSync(projectDir);
   for (const file of rootFiles) {
     if (file === "node_modules" || file === "dist" || file.endsWith(".zip")) {
       continue;
     }
-    const filePath = path6.join(projectDir, file);
-    const stat = fs5.statSync(filePath);
+    const filePath = path7.join(projectDir, file);
+    const stat = fs6.statSync(filePath);
     if (stat.isDirectory()) {
       sourceZip.addLocalFolder(filePath, file);
     } else {
-      sourceZip.addFile(file, fs5.readFileSync(filePath));
+      sourceZip.addFile(file, fs6.readFileSync(filePath));
     }
   }
   return sourceZip.toBuffer();
 }
 function zipDist(projectDir, name, version) {
-  const distDir = path6.join(projectDir, "dist");
-  if (!fs5.existsSync(distDir)) {
+  const distDir = path7.join(projectDir, "dist");
+  if (!fs6.existsSync(distDir)) {
     throw new Error("Dossier dist/ introuvable. Lancez le build avant de zipper.");
   }
   const zipFileName = `${name}-${version}.zip`;
-  const zipFilePath = path6.join(projectDir, zipFileName);
+  const zipFilePath = path7.join(projectDir, zipFileName);
   const zip = new AdmZip2();
   zip.addLocalFolder(distDir);
   const sourceZipBuffer = createSourceZip(projectDir);
@@ -493,7 +560,7 @@ function zipDist(projectDir, name, version) {
 
 // src/commands/pack.ts
 function pack(opts) {
-  const projectDir = path7.resolve(opts.dir ?? process.cwd());
+  const projectDir = path8.resolve(opts.dir ?? process.cwd());
   let name;
   let version;
   try {
@@ -515,7 +582,7 @@ function pack(opts) {
     error(err.message);
     return 1;
   }
-  success(`Zip cr\xE9\xE9 : ${path7.basename(zipPath)}`);
+  success(`Zip cr\xE9\xE9 : ${path8.basename(zipPath)}`);
   info(`Version : ${version}`);
   info("Mise \xE0 jour de la version avec la date du jour\u2026");
   try {
@@ -531,10 +598,39 @@ function pack(opts) {
   return ok ? 0 : 1;
 }
 
+// src/commands/update-docs.ts
+import path9 from "path";
+import pc4 from "picocolors";
+function updateDocs(opts) {
+  const projectDir = path9.resolve(opts.dir ?? process.cwd());
+  try {
+    readManifest(projectDir);
+  } catch (err) {
+    error(`Projet cible invalide : ${err.message}`);
+    return 1;
+  }
+  let diff;
+  try {
+    diff = syncDocs(projectDir);
+  } catch (err) {
+    error(`\xC9chec de la mise \xE0 jour : ${err.message}`);
+    return 1;
+  }
+  if (isDocsUpToDate(diff)) {
+    success(`${DOCS_REL_DIR}/ est d\xE9j\xE0 \xE0 jour.`);
+    return 0;
+  }
+  success(`${DOCS_REL_DIR}/ mis \xE0 jour :`);
+  for (const file of diff.added) info(`  ${pc4.green("+")} ${file}`);
+  for (const file of diff.changed) info(`  ${pc4.dim("~")} ${file}`);
+  for (const file of diff.removed) info(`  ${pc4.red("-")} ${file}`);
+  return 0;
+}
+
 // src/commands/verify.ts
-import path8 from "path";
+import path10 from "path";
 function verify(opts) {
-  const projectDir = path8.resolve(opts.dir ?? process.cwd());
+  const projectDir = path10.resolve(opts.dir ?? process.cwd());
   info("V\xE9rification de conformit\xE9\u2026");
   const result = verifyExtension({ projectDir, zipPath: opts.zip });
   const ok = printVerifyResult(result);
@@ -550,6 +646,9 @@ program.command("bootstrap").description("G\xE9n\xE8re le squelette d'une extens
 program.command("apply").description("Applique un template par-dessus un projet existant (overlay).").argument("<template>", "template \xE0 appliquer (sous-dossier de templates/)").option("--dir <path>", "dossier du projet (d\xE9faut : dossier courant)").action((template, options) => {
   process.exitCode = apply(template, options);
 });
+program.command("update-docs").description("Remplace la doc API (docs/inwink-api/) d'une extension existante par celle de cette version.").option("--dir <path>", "dossier du projet (d\xE9faut : dossier courant)").action((options) => {
+  process.exitCode = updateDocs(options);
+});
 program.command("package").description("Build + zip + v\xE9rification de conformit\xE9 de l'extension.").option("--dir <path>", "dossier du projet (d\xE9faut : dossier courant)").action((options) => {
   process.exitCode = pack(options);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inwink-mcp/backoffice-extension-helpers",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "author": "inwink",
   "license": "ISC",
   "description": "CLI pour bootstrapper, packager et vérifier les extensions backoffice inwink.",

package/templates/vite-extension/AGENTS.md.tpl

@@ -56,7 +56,7 @@ Avant d'écrire **tout** appel API, utilise les outils MCP inwink pour découvri
 
 ### Référence des patterns d'API (`docs/inwink-api/`)
 
-Les outils MCP donnent les endpoints/champs **exacts** ; la doc statique dans `docs/inwink-api/` décrit les **patterns d'appel** (verbes, forme des payloads, langage de requête). Lis uniquement le fichier correspondant à ta tâche :
+Les outils MCP donnent les endpoints/champs **exacts** ; la doc statique dans `docs/inwink-api/` décrit les **patterns d'appel** (verbes, forme des payloads, langage de requête). Ce dossier est une copie de la CLI helper, figée à la génération : mets-le à jour une fois par session de travail (pas avant chaque lecture) avec `npx @inwink-mcp/backoffice-extension-helpers@latest update-docs` (ne réécrit que `docs/inwink-api/`), et ne le modifie pas à la main. Lis uniquement le fichier correspondant à ta tâche :
 
 | Tâche | Fichier |
 |-------|---------|
@@ -223,6 +223,7 @@ Packaging et vérification via la CLI helper :
 ```powershell
 npx @inwink-mcp/backoffice-extension-helpers@latest package   # build + zip + vérification de conformité
 npx @inwink-mcp/backoffice-extension-helpers@latest verify    # vérification de conformité seule
+npx @inwink-mcp/backoffice-extension-helpers@latest update-docs   # met à jour docs/inwink-api/
 ```
 
 ## Conventions de code

package/templates/vite-extension/docs/inwink-api/README.md

@@ -2,6 +2,8 @@
 
 Reference for consuming the inwink APIs from the extension. Calls always go through the `useInwink*Api` hooks, which set the Bearer token and the base URL: the paths below are relative to that base.
 
+> **Keep this folder current.** It is a snapshot of the helper CLI taken when the extension was generated, and it is never edited by hand. Refresh it once per working session, not before each read, with `npx @inwink-mcp/backoffice-extension-helpers@latest update-docs` (rewrites `docs/inwink-api/` only).
+
 > **Dynamic discovery first.** This documentation describes call *patterns* (verbs, payload shapes, query language). The **exact endpoints, fields and entities** are discovered with the MCP tools (`inwink_mcp_find_api_endpoint`, `inwink_mcp_get_entity_description`) — never guess a route or a schema.
 
 ## Contents

package/templates/vite-extension/docs/inwink-api/delete.md

@@ -20,4 +20,6 @@ POST {api}/{shardId}/{entity}/massdelete
 
 Bulk DELETE, like `DELETE … WHERE` in SQL. Relies on a filter (see [query-language.md](./query-language.md#filters)).
 
+Body `{ "filters": … }`. With `?direct=true`: runs in the call and returns `{ "deleted": n }`; without: returns `{ "taskId" }` (queued). Count first with the same filter (`count`).
+
 > A deleted "With History" entity remains readable through `history/removed/query` (see [history.md](./history.md)).

package/templates/vite-extension/docs/inwink-api/entities.md

@@ -30,3 +30,10 @@
 | Massdelete | `POST {api}/{shardId}/{entity}/massdelete` | Bulk DELETE, like `DELETE … WHERE` in SQL — see [delete.md](./delete.md) |
 | Export | | Returns entities as an Excel file |
 | File | | File upload — see [files.md](./files.md) |
+
+## Emails and push notifications (dedicated routes)
+
+Email templates (`mailtemplate` on events, `communitymailtemplate` on communities) and scheduled email sends (`mailschedule` / `mailschedulecommunity`) are ordinary entities (create, update, delete, query). Sending and push notifications use dedicated routes. Filters (`expression`) have the same shape as `filters` in `query`. Sending reaches real people and cannot be undone: count first.
+
+| Purpose | Pattern | Notes |
+|

package/templates/vite-extension/docs/inwink-api/import.md

@@ -20,5 +20,36 @@ POST {api}/{shardId}/{entity}/import
 ```
 
 - If an entity includes `id`, it is treated as an **update**.
-- Without `id`, the `identifiers` map acts as a uniqueness constraint to decide create vs. update. Above, `mail` is used to match existing records.
-- Much faster than individual create/edit calls.
+- Without `id`, the `identifiers` map acts as a uniqueness constraint to decide create vs. update. Above, `mail` is used to match existing records (case-insensitive). Several matches → nothing is done for that row.
+- Much faster than individual create/edit calls. Send batches of **200** rows (what the back-office does).
+- `arrayMergeKeys` (optional, e.g. `["kinds"]`): array fields to **merge** with the existing values instead of replacing them.
+- Synchronous: the response has one entry per input row, in the same order:
+
+```json
+{
+  "entities": [
+    { "entityId": "uuid", "modelErrors": [], "modelWarnings": [], "validationErrors": [] },
+    { "entityIds": ["uuid1", "uuid2"], "modelErrors": [ { "property": "mail", "code": "required" } ] }
+  ],
+  "exceptionMessage": null
+}
+```
+
+A row without `entityId` was **not** written. `exceptionMessage` (top level or per row) reports a database error.
+
+## Import preview (check without writing)
+
+```
+POST {api}/{shardId}/{entity}/import/preview
+```
+
+Same body as the import (`selects` projects the matched record). Nothing is written. One entry per row:
+
+```json
+{ "entities": [ { "entity": { "id": "uuid", "mail": "…" }, "entities": null, "modelErrors": [], "modelWarnings": [], "validationErrors": [] } ] }
+```
+
+- `entity` = the existing record that would be **updated**; `null` = the row would be **created**.
+- `entities` with several items = ambiguous match (nothing would be done).
+- Errors on fields the row did not send are only warnings on an update; on a create every mandatory field must be present.
+- Run the preview, show the result to the user, then send the **same** body to `/import`.

package/templates/vite-extension/docs/inwink-api/update.md

@@ -33,4 +33,6 @@ POST {api}/{shardId}/{entity}/massupdate
 
 Bulk EDIT, like `UPDATE … WHERE` in SQL. Relies on a filter (see [query-language.md](./query-language.md#filters)).
 
+Body `{ "query": { "filters": … }, "input": { field: value } }`. With `?direct=true`: runs in the call and returns `{ "updated": n }`; without: returns `{ "taskId" }` (queued). Count first with the same filter (`count`).
+
 > To update a batch of entities identified one by one, see also [import.md](./import.md).