@imenam/mcp-design 1.0.13 → 1.0.15

package/dist/shared/feedback.d.ts

@@ -123,6 +123,7 @@ export declare const PATH_SEPARATOR = " \u203A ";
  * La GUI l'affiche en aperçu avant l'enregistrement : c'est la même fonction,
  * donc le même texte. Chaque remarque porte son identifiant, que l'agent passe
  * à `mark_feedback_processed`. Les captures sont numérotées dans l'ordre des
- * remarques ; `get_feedback` joint les images dans cet ordre.
+ * remarques ; `get_feedback` joint les images dans cet ordre. `coordinatesSource`
+ * nomme ce qui, chez le lecteur, exprime les coordonnées dans le même repère.
  */
-export declare function formatFeedbackRound(round: Pick<FeedbackRound, "number" | "title" | "submittedAt" | "remarks">): string;
+export declare function formatFeedbackRound(round: Pick<FeedbackRound, "number" | "title" | "submittedAt" | "remarks">, coordinatesSource?: string): string;

package/dist/shared/feedback.js

@@ -118,9 +118,10 @@ function indent(text, prefix) {
  * La GUI l'affiche en aperçu avant l'enregistrement : c'est la même fonction,
  * donc le même texte. Chaque remarque porte son identifiant, que l'agent passe
  * à `mark_feedback_processed`. Les captures sont numérotées dans l'ordre des
- * remarques ; `get_feedback` joint les images dans cet ordre.
+ * remarques ; `get_feedback` joint les images dans cet ordre. `coordinatesSource`
+ * nomme ce qui, chez le lecteur, exprime les coordonnées dans le même repère.
  */
-export function formatFeedbackRound(round) {
+export function formatFeedbackRound(round, coordinatesSource = "get_design") {
     const pages = new Map();
     for (const remark of round.remarks) {
         const list = pages.get(remark.designId);
@@ -133,7 +134,7 @@ export function formatFeedbackRound(round) {
     const lines = [
         `Feedback round ${round.number} "${round.title}" — submitted ${round.submittedAt} — ` +
             `${round.remarks.length} remark(s) on ${pages.size} page(s), ${progress.done} processed.`,
-        "Coordinates are design pixels in the artboard's space, as in get_design.",
+        `Coordinates are design pixels in the artboard's space, as in ${coordinatesSource}.`,
     ];
     let image = 0;
     for (const [designId, remarks] of pages) {

package/dist/src/core/design-model.d.ts

@@ -0,0 +1,54 @@
+import { type Design, type DesignSummary } from "../../shared/schemas/design.schema.js";
+/**
+ * Règles d'un design indépendantes de son stockage : création, copie,
+ * mutation validée, synchronisation. Le `DesignStore` du serveur les applique à
+ * des fichiers JSON, la version autonome de la GUI à son projet en mémoire.
+ */
+export interface CreateDesignInput {
+    name: string;
+    width?: number;
+    height?: number;
+    background?: string;
+    /** Groupe de pages, chemin "Parent/Enfant". Null ou omis : a la racine. */
+    group?: string | null;
+}
+export interface MutateOptions {
+    /**
+     * Révision sur laquelle l'édition est basée. Quand elle est fournie et que le
+     * design a avancé entre-temps, l'écriture est refusée : sans cette garde, un
+     * éditeur parti d'un état périmé réécrit le document entier et efface le
+     * travail de l'autre.
+     */
+    baseRevision?: number;
+}
+/** Identifiant lisible dérivé du nom, suffixé seulement en cas de collision. */
+export declare function allocateDesignId(name: string, exists: (id: string) => boolean): string;
+/**
+ * Lit un design brut, après mise à niveau de son format. `migrated` indique
+ * qu'il diffère de ce qui a été lu et mérite d'être réécrit.
+ */
+export declare function parseDesign(raw: unknown, label: string): {
+    design: Design;
+    migrated: boolean;
+};
+export declare function newDesign(id: string, input: CreateDesignInput, now: string): Design;
+/**
+ * Nouveau design reprenant la planche et tous les éléments d'un design
+ * existant, identifiants compris. La copie part synchronisée : sa référence
+ * de comparaison est son propre contenu.
+ */
+export declare function duplicatedDesign(source: Design, id: string, input: {
+    name?: string;
+    group?: string | null;
+}, now: string): Design;
+/**
+ * Applique une mutation à une copie du design et incrémente la révision.
+ * `editor` distingue une modification de l'agent d'une modification faite à la
+ * main dans la GUI — c'est ce qui permet à get_changes de rester lisible.
+ */
+export declare function mutatedDesign(current: Design, editor: "agent" | "user", fn: (design: Design) => void, options?: MutateOptions): Design;
+/** Le design avec son état courant comme nouvelle référence de comparaison. */
+export declare function syncedDesign(current: Design, now: string): Design;
+export declare function summaryOf(design: Design): DesignSummary;
+/** Plus récemment modifiés d'abord, comme la liste des pages de la GUI. */
+export declare function sortSummaries(summaries: DesignSummary[]): DesignSummary[];

package/dist/src/core/design-model.js

@@ -0,0 +1,129 @@
+import { DesignSchema, normalizeDesignGroup, } from "../../shared/schemas/design.schema.js";
+import { DesignError } from "./node-factory.js";
+import { normalizeHierarchy } from "./hierarchy.js";
+import { migrateDesign } from "./migrate.js";
+import { shortId, slugify } from "./ids.js";
+import { countChanges } from "./diff.js";
+function issuesOf(error) {
+    return error.issues.map((issue) => `${issue.path.map(String).join(".")} ${issue.message}`).join("; ");
+}
+/** Identifiant lisible dérivé du nom, suffixé seulement en cas de collision. */
+export function allocateDesignId(name, exists) {
+    const base = slugify(name);
+    if (!exists(base))
+        return base;
+    for (let i = 2; i < 100; i++) {
+        const candidate = `${base}-${i}`;
+        if (!exists(candidate))
+            return candidate;
+    }
+    return `${base}-${shortId("x", 4)}`;
+}
+/**
+ * Lit un design brut, après mise à niveau de son format. `migrated` indique
+ * qu'il diffère de ce qui a été lu et mérite d'être réécrit.
+ */
+export function parseDesign(raw, label) {
+    const migrated = migrateDesign(raw);
+    const parsed = DesignSchema.safeParse(migrated ?? raw);
+    if (!parsed.success) {
+        throw new DesignError(`Design ${label} does not match the expected schema: ${issuesOf(parsed.error)}`);
+    }
+    return { design: parsed.data, migrated: migrated !== null };
+}
+export function newDesign(id, input, now) {
+    const name = input.name?.trim();
+    if (!name)
+        throw new DesignError(`"name" is required to create a design.`);
+    const width = input.width ?? 1440;
+    const height = input.height ?? 900;
+    if (!Number.isFinite(width) || width <= 0)
+        throw new DesignError(`"width" must be a positive number.`);
+    if (!Number.isFinite(height) || height <= 0)
+        throw new DesignError(`"height" must be a positive number.`);
+    return {
+        id,
+        name,
+        group: normalizeDesignGroup(input.group),
+        width,
+        height,
+        background: input.background ?? "#ffffff",
+        nodes: [],
+        createdAt: now,
+        updatedAt: now,
+        revision: 0,
+        lastEditor: "agent",
+        baseline: { revision: 0, at: now, nodes: [] },
+    };
+}
+/**
+ * Nouveau design reprenant la planche et tous les éléments d'un design
+ * existant, identifiants compris. La copie part synchronisée : sa référence
+ * de comparaison est son propre contenu.
+ */
+export function duplicatedDesign(source, id, input, now) {
+    const name = input.name?.trim() || `${source.name} (copy)`;
+    return {
+        id,
+        name,
+        group: input.group === undefined ? source.group : normalizeDesignGroup(input.group),
+        width: source.width,
+        height: source.height,
+        background: source.background,
+        nodes: structuredClone(source.nodes),
+        createdAt: now,
+        updatedAt: now,
+        revision: 0,
+        lastEditor: "agent",
+        baseline: { revision: 0, at: now, nodes: structuredClone(source.nodes) },
+    };
+}
+/**
+ * Applique une mutation à une copie du design et incrémente la révision.
+ * `editor` distingue une modification de l'agent d'une modification faite à la
+ * main dans la GUI — c'est ce qui permet à get_changes de rester lisible.
+ */
+export function mutatedDesign(current, editor, fn, options = {}) {
+    if (options.baseRevision !== undefined && options.baseRevision !== current.revision) {
+        throw new DesignError(`Design "${current.id}" has changed since it was loaded: your edit is based on revision ${options.baseRevision}, ` +
+            `the stored design is at revision ${current.revision}. Reload it with get_design and reapply your change — ` +
+            `writing now would discard the other editor's work.`);
+    }
+    const draft = structuredClone(current);
+    fn(draft);
+    // Les invariants de hiérarchie sont vérifiés ici, une seule fois : aucun
+    // appelant — outil MCP ou sauvegarde depuis la GUI — ne peut les contourner.
+    draft.nodes = normalizeHierarchy(draft.nodes);
+    draft.revision = current.revision + 1;
+    draft.updatedAt = new Date().toISOString();
+    draft.lastEditor = editor;
+    const parsed = DesignSchema.safeParse(draft);
+    if (!parsed.success)
+        throw new DesignError(`Resulting design is invalid: ${issuesOf(parsed.error)}`);
+    return parsed.data;
+}
+/** Le design avec son état courant comme nouvelle référence de comparaison. */
+export function syncedDesign(current, now) {
+    return {
+        ...structuredClone(current),
+        baseline: { revision: current.revision, at: now, nodes: structuredClone(current.nodes) },
+    };
+}
+export function summaryOf(design) {
+    return {
+        id: design.id,
+        name: design.name,
+        group: design.group,
+        width: design.width,
+        height: design.height,
+        nodeCount: design.nodes.length,
+        updatedAt: design.updatedAt,
+        revision: design.revision,
+        lastEditor: design.lastEditor,
+        pendingChanges: countChanges(design.baseline.nodes, design.nodes),
+    };
+}
+/** Plus récemment modifiés d'abord, comme la liste des pages de la GUI. */
+export function sortSummaries(summaries) {
+    return summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}

package/dist/src/core/design-store.d.ts

@@ -1,22 +1,7 @@
-import { type Design, type DesignSummary } from "../../shared/schemas/design.schema.js";
+import type { Design, DesignSummary } from "../../shared/schemas/design.schema.js";
+import { type CreateDesignInput, type MutateOptions } from "./design-model.js";
 import { ImageStore } from "./image-store.js";
-export interface CreateDesignInput {
-    name: string;
-    width?: number;
-    height?: number;
-    background?: string;
-    /** Groupe de pages, chemin "Parent/Enfant". Null ou omis : a la racine. */
-    group?: string | null;
-}
-export interface MutateOptions {
-    /**
-     * Révision sur laquelle l'édition est basée. Quand elle est fournie et que le
-     * fichier a avancé entre-temps, l'écriture est refusée : sans cette garde, un
-     * éditeur parti d'un état périmé réécrit le document entier et efface le
-     * travail de l'autre.
-     */
-    baseRevision?: number;
-}
+export type { CreateDesignInput, MutateOptions };
 /**
  * Persistance des designs : un fichier JSON par design dans <dataDir>/designs.
  * Pas de base de données — un design tient dans quelques dizaines de Ko et le

package/dist/src/core/design-store.js

@@ -1,12 +1,8 @@
 import fs from "fs";
 import path from "path";
-import { DesignSchema, normalizeDesignGroup, } from "../../shared/schemas/design.schema.js";
 import { DesignError } from "./node-factory.js";
 import { withFileLock } from "./file-lock.js";
-import { normalizeHierarchy } from "./hierarchy.js";
-import { migrateDesign } from "./migrate.js";
-import { shortId, slugify } from "./ids.js";
-import { countChanges } from "./diff.js";
+import { allocateDesignId, duplicatedDesign, mutatedDesign, newDesign, parseDesign, sortSummaries, summaryOf, syncedDesign, } from "./design-model.js";
 import { ImageStore } from "./image-store.js";
 /**
  * Persistance des designs : un fichier JSON par design dans <dataDir>/designs.
@@ -75,15 +71,7 @@ export class DesignStore {
     }
     /** Identifiant lisible dérivé du nom, suffixé seulement en cas de collision. */
     allocateId(name) {
-        const base = slugify(name);
-        if (!fs.existsSync(this.filePath(base)))
-            return base;
-        for (let i = 2; i < 100; i++) {
-            const candidate = `${base}-${i}`;
-            if (!fs.existsSync(this.filePath(candidate)))
-                return candidate;
-        }
-        return `${base}-${shortId("x", 4)}`;
+        return allocateDesignId(name, (id) => fs.existsSync(this.filePath(id)));
     }
     list() {
         const files = fs.existsSync(this.designsDir)
@@ -99,20 +87,9 @@ export class DesignStore {
             catch {
                 continue; // Fichier corrompu ou hors schéma : il ne doit pas casser la liste.
             }
-            summaries.push({
-                id: design.id,
-                name: design.name,
-                group: design.group,
-                width: design.width,
-                height: design.height,
-                nodeCount: design.nodes.length,
-                updatedAt: design.updatedAt,
-                revision: design.revision,
-                lastEditor: design.lastEditor,
-                pendingChanges: countChanges(design.baseline.nodes, design.nodes),
-            });
+            summaries.push(summaryOf(design));
         }
-        return summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return sortSummaries(summaries);
     }
     has(id) {
         return fs.existsSync(this.filePath(id));
@@ -138,13 +115,7 @@ export class DesignStore {
         }
         // Mise à niveau du format avant validation : un fichier écrit par une
         // version antérieure reste lisible, et n'est réécrit qu'en cas de changement.
-        const migrated = migrateDesign(raw);
-        const parsed = DesignSchema.safeParse(migrated ?? raw);
-        if (!parsed.success) {
-            throw new DesignError(`Design "${id}" does not match the expected schema: ${parsed.error.issues
-                .map((i) => `${i.path.join(".")} ${i.message}`)
-                .join("; ")}`);
-        }
+        const { design, migrated } = parseDesign(raw, `"${id}"`);
         if (migrated) {
             // Best effort : un répertoire de données en lecture seule ne doit pas
             // empêcher de lire le design, la migration reste appliquée en mémoire.
@@ -152,42 +123,19 @@ export class DesignStore {
             // de `withLock`, et le verrou n'est pas réentrant. Le contenu écrit est
             // celui qu'on vient de lire, la mise à niveau ne perd donc rien.
             try {
-                this.write(parsed.data);
+                this.write(design);
             }
             catch {
                 this.cache.delete(id);
             }
-            return parsed.data;
+            return design;
         }
         if (stamp)
-            this.cache.set(id, { design: parsed.data, stamp });
-        return parsed.data;
+            this.cache.set(id, { design, stamp });
+        return design;
     }
     create(input) {
-        const name = input.name?.trim();
-        if (!name)
-            throw new DesignError(`"name" is required to create a design.`);
-        const width = input.width ?? 1440;
-        const height = input.height ?? 900;
-        if (!Number.isFinite(width) || width <= 0)
-            throw new DesignError(`"width" must be a positive number.`);
-        if (!Number.isFinite(height) || height <= 0)
-            throw new DesignError(`"height" must be a positive number.`);
-        const now = new Date().toISOString();
-        const design = {
-            id: this.allocateId(name),
-            name,
-            group: normalizeDesignGroup(input.group),
-            width,
-            height,
-            background: input.background ?? "#ffffff",
-            nodes: [],
-            createdAt: now,
-            updatedAt: now,
-            revision: 0,
-            lastEditor: "agent",
-            baseline: { revision: 0, at: now, nodes: [] },
-        };
+        const design = newDesign(this.allocateId(input.name?.trim() ?? ""), input, new Date().toISOString());
         this.write(design);
         return design;
     }
@@ -199,21 +147,7 @@ export class DesignStore {
     duplicate(sourceId, input = {}) {
         const source = this.get(sourceId);
         const name = input.name?.trim() || `${source.name} (copy)`;
-        const now = new Date().toISOString();
-        const design = {
-            id: this.allocateId(name),
-            name,
-            group: input.group === undefined ? source.group : normalizeDesignGroup(input.group),
-            width: source.width,
-            height: source.height,
-            background: source.background,
-            nodes: structuredClone(source.nodes),
-            createdAt: now,
-            updatedAt: now,
-            revision: 0,
-            lastEditor: "agent",
-            baseline: { revision: 0, at: now, nodes: structuredClone(source.nodes) },
-        };
+        const design = duplicatedDesign(source, this.allocateId(name), { ...input, name }, new Date().toISOString());
         this.write(design);
         return design;
     }
@@ -228,36 +162,14 @@ export class DesignStore {
         return this.withLock(id, () => this.mutateLocked(id, editor, fn, options));
     }
     mutateLocked(id, editor, fn, options) {
-        const current = this.get(id);
-        if (options.baseRevision !== undefined && options.baseRevision !== current.revision) {
-            throw new DesignError(`Design "${id}" has changed since it was loaded: your edit is based on revision ${options.baseRevision}, ` +
-                `the stored design is at revision ${current.revision}. Reload it with get_design and reapply your change — ` +
-                `writing now would discard the other editor's work.`);
-        }
-        const draft = structuredClone(current);
-        fn(draft);
-        // Les invariants de hiérarchie sont vérifiés ici, une seule fois : aucun
-        // appelant — outil MCP ou sauvegarde depuis la GUI — ne peut les contourner.
-        draft.nodes = normalizeHierarchy(draft.nodes);
-        draft.revision = current.revision + 1;
-        draft.updatedAt = new Date().toISOString();
-        draft.lastEditor = editor;
-        const parsed = DesignSchema.safeParse(draft);
-        if (!parsed.success) {
-            throw new DesignError(`Resulting design is invalid: ${parsed.error.issues.map((i) => `${i.path.join(".")} ${i.message}`).join("; ")}`);
-        }
-        this.write(parsed.data);
-        return parsed.data;
+        const next = mutatedDesign(this.get(id), editor, fn, options);
+        this.write(next);
+        return next;
     }
     /** Fige l'état courant comme nouvelle référence de comparaison. */
     markSynced(id) {
         return this.withLock(id, () => {
-            const current = this.get(id);
-            const now = new Date().toISOString();
-            const next = {
-                ...structuredClone(current),
-                baseline: { revision: current.revision, at: now, nodes: structuredClone(current.nodes) },
-            };
+            const next = syncedDesign(this.get(id), new Date().toISOString());
             this.write(next);
             return next;
         });

package/dist/src/core/exchange.d.ts

@@ -0,0 +1,86 @@
+import { type FeedbackRound } from "../../shared/feedback.js";
+import { type Design } from "../../shared/schemas/design.schema.js";
+import type { FeedbackFile } from "../../shared/schemas/feedback.schema.js";
+import { DesignError } from "./node-factory.js";
+/**
+ * Échanges de la version autonome avec un assistant conversationnel :
+ *
+ * - le prompt qui lui décrit le format d'une page ;
+ * - la lecture stricte d'une page qu'il renvoie, refusée en bloc à la moindre
+ *   erreur avec un message qu'on peut lui recoller tel quel ;
+ * - le récap d'un retour, qui lui transmet les remarques et l'état courant des
+ *   pages concernées ;
+ * - l'export et la relecture du projet complet.
+ */
+export declare const PAGE_FORMAT = "mcp-design-page";
+export declare const PROJECT_FORMAT = "mcp-design-project";
+export declare const EXCHANGE_VERSION = 1;
+/** Pages, remarques et captures (data URI PNG par nom de fichier) d'un projet autonome. */
+export interface ProjectData {
+    designs: Design[];
+    feedback: FeedbackFile;
+    captures: Record<string, string>;
+}
+/** Refus d'un fichier importé. `issues` liste chaque problème, `message` s'adresse à l'assistant. */
+export declare class ExchangeError extends DesignError {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+/** Une page lue et validée, prête à remplacer ou rejoindre celles du projet. */
+export interface PageImport {
+    /** La page telle qu'elle sera enregistrée, synchronisée sur son nouveau contenu. */
+    design: Design;
+    /** Page existante que l'import remplace, ou null pour une nouvelle page. */
+    replaces: Design | null;
+    /** Remarques déclarées traitées, avec le retour qui les contient. */
+    processed: {
+        round: number;
+        remarkId: string;
+        note: string | null;
+    }[];
+}
+/**
+ * Lit une page renvoyée par l'assistant. Rien n'est appliqué ici : le résultat
+ * dit ce que l'import ferait, `applyPageImport` l'exécute.
+ */
+export declare function parsePageReply(text: string, project: Pick<ProjectData, "designs" | "feedback">): PageImport;
+/** Enregistre une page lue par `parsePageReply` et note les remarques traitées. */
+export declare function applyPageImport(project: ProjectData, plan: PageImport): void;
+interface PageFile {
+    format: string;
+    version: number;
+    page: {
+        id: string;
+        name: string;
+        group: string | null;
+        width: number;
+        height: number;
+        background: string;
+        nodes: object[];
+    };
+    processed: {
+        remark: string;
+        note?: string;
+    }[];
+}
+/** La page au format d'échange. La taille des groupes et des instances, dérivée, n'y figure pas. */
+export declare function pageFileOf(design: Design): PageFile;
+/** JSON d'une page, un élément par ligne : lisible et bien plus court qu'une indentation complète. */
+export declare function pageJson(file: PageFile): string;
+export declare function projectFileOf(project: ProjectData, exportedAt: string): object;
+/** Relit un export complet ; refusé en bloc à la moindre incohérence. */
+export declare function parseProjectFile(text: string): ProjectData;
+/** Ce que l'utilisateur colle en tête de conversation, suivi de sa demande. */
+export declare function creationPrompt(): string;
+/** Ce qui, pour l'assistant, exprime les coordonnées des remarques. */
+export declare const COORDINATES_SOURCE = "the page JSON";
+/** Fichiers joints au récap : une vue de chaque page, et une image par capture. */
+export interface RecapFiles {
+    /** Vue d'ensemble de chaque page concernée, par id de page. */
+    pages: Map<string, string>;
+    /** Fichier de chaque capture, dans l'ordre où le texte du retour les numérote. */
+    captures: string[];
+}
+/** Texte du récap d'un retour, à transmettre à l'assistant avec les fichiers joints. */
+export declare function recapText(round: FeedbackRound, designs: Design[], files: RecapFiles): string;
+export {};