@imenam/mcp-design 1.0.10 → 1.0.12

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

@@ -2,21 +2,12 @@ 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";
-/** Au-delà de ce délai, un verrou est réputé abandonné (processus tué en cours d'écriture). */
-const LOCK_STALE_MS = 10_000;
-const LOCK_RETRY_MS = 25;
-const LOCK_TIMEOUT_MS = 5_000;
-/**
- * Pause bloquante. Le store est entièrement synchrone — le rendre asynchrone
- * pour l'attente d'un verrou contaminerait tous les appelants.
- */
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
+import { ImageStore } from "./image-store.js";
 /**
  * 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
@@ -25,6 +16,8 @@ function sleepSync(ms) {
 export class DesignStore {
     dataDir;
     designsDir;
+    /** Images posées sur les planches, partagées par tous les designs du dossier de données. */
+    images;
     /**
      * Cache mémoire : la GUI sauvegarde à chaque geste, relire le disque à chaque
      * fois serait inutile. Chaque entrée retient la signature du fichier au moment
@@ -39,6 +32,7 @@ export class DesignStore {
         this.dataDir = configured ? path.resolve(configured) : path.join(rootDir, ".design-data");
         this.designsDir = path.join(this.dataDir, "designs");
         fs.mkdirSync(this.designsDir, { recursive: true });
+        this.images = new ImageStore(this.dataDir);
     }
     getDataDir() {
         return this.dataDir;
@@ -75,52 +69,9 @@ export class DesignStore {
         // prendrait notre propre écriture pour une modification externe.
         this.remember(design);
     }
-    /**
-     * Sérialise le cycle lire-modifier-écrire entre processus. `wx` échoue si le
-     * fichier existe déjà : c'est l'opération atomique qui départage deux
-     * écrivains concurrents. Non réentrant — ne jamais appeler depuis `fn`.
-     */
+    /** Verrou inter-processus du fichier d'un design. Non réentrant — ne jamais appeler depuis `fn`. */
     withLock(id, fn) {
-        const lockPath = `${this.filePath(id)}.lock`;
-        const deadline = Date.now() + LOCK_TIMEOUT_MS;
-        let fd;
-        for (;;) {
-            try {
-                fd = fs.openSync(lockPath, "wx");
-                break;
-            }
-            catch (err) {
-                if (err.code !== "EEXIST")
-                    throw err;
-                try {
-                    // Un processus tué laisse son verrou derrière lui : passé le délai
-                    // d'obsolescence on le casse, sinon le design serait bloqué à vie.
-                    if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
-                        fs.unlinkSync(lockPath);
-                        continue;
-                    }
-                }
-                catch {
-                    continue; // Verrou disparu entre le open et le stat : on retente aussitôt.
-                }
-                if (Date.now() > deadline) {
-                    throw new DesignError(`Design "${id}" is being written by another editor and did not free up in ${LOCK_TIMEOUT_MS} ms. Try again in a moment.`);
-                }
-                sleepSync(LOCK_RETRY_MS);
-            }
-        }
-        try {
-            return fn();
-        }
-        finally {
-            fs.closeSync(fd);
-            try {
-                fs.unlinkSync(lockPath);
-            }
-            catch {
-                // Verrou déjà cassé pour obsolescence par un autre processus.
-            }
-        }
+        return withFileLock(`${this.filePath(id)}.lock`, `Design "${id}"`, fn);
     }
     /** Identifiant lisible dérivé du nom, suffixé seulement en cas de collision. */
     allocateId(name) {

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

@@ -1,6 +1,7 @@
 import type { Design } from "../../shared/schemas/design.schema.js";
+import type { ImageStore } from "./image-store.js";
 export declare const EXPORT_FORMATS: readonly ["svg", "html", "jsx", "json", "summary"];
 export type ExportFormat = (typeof EXPORT_FORMATS)[number];
 /** Inventaire textuel : ce que l'agent lit quand il veut comprendre sans parser du JSON. */
 export declare function toSummary(design: Design): string;
-export declare function exportDesign(design: Design, format: ExportFormat): string;
+export declare function exportDesign(design: Design, format: ExportFormat, images?: ImageStore): string;

package/dist/src/core/export.js

@@ -1,4 +1,4 @@
-import { DEFAULT_FONT_FAMILY, documentToSvg, escapeXml, iconElementToSvg, iconElementsOf, iconStyle, normalizedBox, textLines, textMetrics, } from "../../shared/render.js";
+import { DEFAULT_FONT_FAMILY, documentToSvg, escapeXml, iconElementToSvg, iconElementsOf, iconStyle, imageSource, normalizedBox, textLines, textMetrics, } from "../../shared/render.js";
 import { ICON_GRID } from "../../shared/icons/index.js";
 import { boundsOf, childrenByParent, computeLayout } from "../../shared/tree.js";
 import { expandInstances } from "../../shared/instances.js";
@@ -131,7 +131,19 @@ function contextOf(design) {
     const nodes = toExpandedNodes(design);
     return { layout: computeLayout(nodes), children: childrenByParent(nodes) };
 }
-function toHtml(design) {
+/**
+ * Résolution des images en data URI : un export se suffit à lui-même, il
+ * s'ouvre tel quel sans la médiathèque du serveur.
+ */
+function renderOptions(images) {
+    return images ? { imageHref: (name) => images.dataUri(name) } : {};
+}
+/** Source et cadrage d'une image pour les exports HTML et JSX. */
+function imageTag(node, images) {
+    const render = node;
+    return { src: imageSource(render, renderOptions(images)), fit: render.fit ?? "cover" };
+}
+function toHtml(design, images) {
     const { layout, children } = contextOf(design);
     const rules = [];
     const walk = (nodes, parentBox, depth) => {
@@ -150,6 +162,12 @@ function toHtml(design) {
                 return [`${pad}<div class="${cls}">${escapeXml(node.text ?? "")}</div>`];
             if (node.type === "icon")
                 return [`${pad}<div class="${cls}">${iconSvg(node, identity)}</div>`];
+            if (node.type === "image") {
+                const image = imageTag(node, images);
+                return [
+                    `${pad}<img class="${cls}" src="${escapeXml(image.src)}" alt="${escapeXml(node.name)}" style="object-fit: ${image.fit}" />`,
+                ];
+            }
             return [`${pad}<div class="${cls}"></div>`];
         });
     };
@@ -189,7 +207,7 @@ function toComponentName(name) {
         .replace(/^[a-z]/, (letter) => letter.toUpperCase());
     return /^[A-Za-z]/.test(pascal) ? pascal : "Design";
 }
-function toJsx(design) {
+function toJsx(design, images) {
     const { layout, children } = contextOf(design);
     const styleOf = (node, parentBox) => nodeCss(node, layout, parentBox)
         .map((declaration) => {
@@ -218,6 +236,13 @@ function toJsx(design) {
             if (node.type === "icon") {
                 return [comment, `${pad}<div style={{ ${style} }}>${iconSvg(node, toCamelCase)}</div>`];
             }
+            if (node.type === "image") {
+                const image = imageTag(node, images);
+                return [
+                    comment,
+                    `${pad}<img src=${JSON.stringify(image.src)} alt=${JSON.stringify(node.name)} style={{ ${style}, objectFit: ${JSON.stringify(image.fit)} }} />`,
+                ];
+            }
             return [comment, `${pad}<div style={{ ${style} }} />`];
         });
     };
@@ -273,6 +298,9 @@ export function toSummary(design) {
                 lines.push(`${indent}- ${node.id} icon "${node.name}" @ ${geometry} — ${node.icon ?? "?"}, ` +
                     `stroke ${node.stroke ?? "none"} ${node.strokeWidth ?? 2}/24${node.fill && node.fill !== "none" ? `, fill ${node.fill}` : ""}`);
             }
+            else if (node.type === "image") {
+                lines.push(`${indent}- ${node.id} image "${node.name}" @ ${geometry} — ${node.image ?? "?"}, fit ${node.fit ?? "cover"}`);
+            }
             else if (node.type === "line") {
                 lines.push(`${indent}- ${node.id} line "${node.name}" @ ${geometry} — ${node.strokeWidth}px ${node.stroke}`);
             }
@@ -285,7 +313,7 @@ export function toSummary(design) {
     walk(children.get(null) ?? [], 0);
     return lines.join("\n");
 }
-export function exportDesign(design, format) {
+export function exportDesign(design, format, images) {
     switch (format) {
         case "svg":
             // `documentToSvg` resout les instances lui-meme : le canvas de la GUI
@@ -296,11 +324,11 @@ export function exportDesign(design, format) {
                 height: design.height,
                 background: design.background,
                 nodes: toRenderNodes(design),
-            });
+            }, renderOptions(images));
         case "html":
-            return toHtml(design);
+            return toHtml(design, images);
         case "jsx":
-            return toJsx(design);
+            return toJsx(design, images);
         case "json":
             return JSON.stringify({
                 id: design.id,

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

@@ -0,0 +1,73 @@
+import { type FeedbackRound, type Remark } from "../../shared/feedback.js";
+import { type FeedbackFile } from "../../shared/schemas/feedback.schema.js";
+import type { Box } from "../../shared/tree.js";
+import type { DesignStore } from "./design-store.js";
+/** Cible demandée par la GUI ; le serveur la complète d'après le design. */
+export type RemarkTargetInput = {
+    kind: "page";
+} | {
+    kind: "node";
+    nodeId: string;
+} | {
+    kind: "area";
+    box: Box;
+    elementIds: string[];
+};
+export interface AddRemarkInput {
+    designId: string;
+    target: RemarkTargetInput;
+    text: string;
+    /** Joindre une capture de l'élément ou de la zone. Sans effet sur une remarque de page. */
+    capture: boolean;
+}
+export interface SetProcessedInput {
+    round: number;
+    /** Remarques visées ; toutes celles du retour quand omis. */
+    remarkIds?: string[];
+    processed: boolean;
+    by: "agent" | "user";
+    note?: string | null;
+}
+/**
+ * Remarques de l'utilisateur et retours transmis à l'agent, dans
+ * `<dataDir>/feedback/remarks.json`, captures dans `<dataDir>/feedback/captures`.
+ *
+ * Un seul fichier pour tout le projet : un retour peut couvrir plusieurs pages.
+ */
+export declare class FeedbackStore {
+    private readonly designs;
+    private readonly dir;
+    private readonly capturesDir;
+    private readonly file;
+    constructor(designs: DesignStore);
+    getFilePath(): string;
+    read(): FeedbackFile;
+    private mutate;
+    remarks(designId?: string): Remark[];
+    rounds(): FeedbackRound[];
+    capturePath(name: string): string;
+    readCapture(name: string): Buffer;
+    /** Complète la cible d'après l'état courant du design. */
+    private resolveTarget;
+    private renderCapture;
+    add(input: AddRemarkInput): Remark;
+    private draftOf;
+    updateText(id: string, text: string): Remark;
+    /**
+     * Retire une remarque de la liste. La capture d'un brouillon part avec lui ;
+     * celle d'une remarque transmise reste, le retour qui la contient la cite.
+     */
+    delete(id: string): void;
+    /** Retire les remarques d'un design supprimé, selon la même règle que `delete`. */
+    deleteDesign(designId: string): void;
+    /** Fige les brouillons choisis dans un nouveau retour nommé, et les marque transmis. */
+    submit(remarkIds: string[], title: string): FeedbackRound;
+    private roundOf;
+    rename(number: number, title: string): FeedbackRound;
+    /**
+     * Déclare des remarques d'un retour traitées, ou les rouvre. Une remarque
+     * déjà traitée reste inchangée ; une nouvelle note remplace l'ancienne et
+     * son auteur, en gardant la date d'origine.
+     */
+    setProcessed(input: SetProcessedInput): FeedbackRound;
+}

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

@@ -0,0 +1,308 @@
+import fs from "fs";
+import path from "path";
+import { defaultRoundTitle, elementsInArea, nodeTarget, orderRemarks, roundBox, } from "../../shared/feedback.js";
+import { FeedbackFileSchema, migrateFeedbackFile } from "../../shared/schemas/feedback.schema.js";
+import { withFileLock } from "./file-lock.js";
+import { shortId } from "./ids.js";
+import { DesignError } from "./node-factory.js";
+import { screenshotDesign } from "./screenshot.js";
+/** Marge autour d'un élément capturé, comme `screenshot_design`. */
+const NODE_CAPTURE_PADDING = 16;
+function emptyFile() {
+    return { version: 2, remarks: [], rounds: [], lastNumbers: {} };
+}
+function requireText(text) {
+    const value = typeof text === "string" ? text.trim() : "";
+    if (value === "")
+        throw new DesignError("A remark needs some text.");
+    return value;
+}
+function requireTitle(title) {
+    const value = typeof title === "string" ? title.trim() : "";
+    if (value === "")
+        throw new DesignError("A feedback round needs a name.");
+    return value;
+}
+/**
+ * Remarques de l'utilisateur et retours transmis à l'agent, dans
+ * `<dataDir>/feedback/remarks.json`, captures dans `<dataDir>/feedback/captures`.
+ *
+ * Un seul fichier pour tout le projet : un retour peut couvrir plusieurs pages.
+ */
+export class FeedbackStore {
+    designs;
+    dir;
+    capturesDir;
+    file;
+    constructor(designs) {
+        this.designs = designs;
+        this.dir = path.join(designs.getDataDir(), "feedback");
+        this.capturesDir = path.join(this.dir, "captures");
+        this.file = path.join(this.dir, "remarks.json");
+        fs.mkdirSync(this.capturesDir, { recursive: true });
+    }
+    getFilePath() {
+        return this.file;
+    }
+    read() {
+        if (!fs.existsSync(this.file))
+            return emptyFile();
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(this.file, "utf-8"));
+        }
+        catch (err) {
+            throw new DesignError(`The remarks file ${this.file} is not readable: ${err.message}`);
+        }
+        // Un fichier d'une version antérieure est lu au format courant ; il n'est
+        // réécrit qu'à la prochaine modification.
+        const parsed = FeedbackFileSchema.safeParse(migrateFeedbackFile(raw, defaultRoundTitle) ?? raw);
+        if (!parsed.success) {
+            throw new DesignError(`The remarks file ${this.file} does not match the expected schema: ${parsed.error.issues
+                .map((issue) => `${issue.path.join(".")} ${issue.message}`)
+                .join("; ")}`);
+        }
+        return parsed.data;
+    }
+    mutate(fn) {
+        return withFileLock(`${this.file}.lock`, "The remarks file", () => {
+            const draft = structuredClone(this.read());
+            const result = fn(draft);
+            const parsed = FeedbackFileSchema.safeParse(draft);
+            if (!parsed.success) {
+                throw new DesignError(`Resulting remarks file is invalid: ${parsed.error.issues
+                    .map((issue) => `${issue.path.join(".")} ${issue.message}`)
+                    .join("; ")}`);
+            }
+            const tmp = `${this.file}.tmp`;
+            fs.writeFileSync(tmp, JSON.stringify(parsed.data, null, 2), "utf-8");
+            fs.renameSync(tmp, this.file);
+            return result;
+        });
+    }
+    remarks(designId) {
+        const remarks = this.read().remarks;
+        return designId === undefined ? remarks : remarks.filter((remark) => remark.designId === designId);
+    }
+    rounds() {
+        return this.read().rounds;
+    }
+    capturePath(name) {
+        if (name !== path.basename(name))
+            throw new DesignError(`Invalid capture name "${name}".`);
+        return path.join(this.capturesDir, name);
+    }
+    readCapture(name) {
+        const file = this.capturePath(name);
+        if (!fs.existsSync(file))
+            throw new DesignError(`Capture "${name}" not found in ${this.capturesDir}.`);
+        return fs.readFileSync(file);
+    }
+    /** Complète la cible d'après l'état courant du design. */
+    resolveTarget(designId, input) {
+        const design = this.designs.get(designId);
+        if (input.kind === "page")
+            return { kind: "page" };
+        if (input.kind === "node") {
+            if (!design.nodes.some((node) => node.id === input.nodeId)) {
+                throw new DesignError(`Node "${input.nodeId}" not found in design "${design.name}" (${design.id}).`);
+            }
+            return nodeTarget(design.nodes, input.nodeId);
+        }
+        const box = roundBox(input.box);
+        if (!(box.width >= 1 && box.height >= 1))
+            throw new DesignError("A remark area must be at least 1 px wide and high.");
+        if (box.x < 0 || box.y < 0 || box.x + box.width > design.width || box.y + box.height > design.height) {
+            throw new DesignError(`A remark area must lie within the ${design.width}x${design.height} artboard.`);
+        }
+        const hits = new Map(elementsInArea(design.nodes, box).map((hit) => [hit.id, hit]));
+        const elements = input.elementIds.map((id) => {
+            const hit = hits.get(id);
+            if (!hit)
+                throw new DesignError(`Node "${id}" is not inside the remark area.`);
+            return { id: hit.id, name: hit.name, type: hit.type };
+        });
+        return { kind: "area", box, elements };
+    }
+    renderCapture(designId, target) {
+        const design = this.designs.get(designId);
+        if (target.kind === "node") {
+            return screenshotDesign(design, { nodeId: target.element.id, padding: NODE_CAPTURE_PADDING, images: this.designs.images }).png;
+        }
+        if (target.kind === "area")
+            return screenshotDesign(design, { region: target.box, images: this.designs.images }).png;
+        throw new DesignError("A page remark has no capture.");
+    }
+    add(input) {
+        const text = requireText(input.text);
+        const target = this.resolveTarget(input.designId, input.target);
+        const id = shortId("rm");
+        const capture = input.capture && target.kind !== "page" ? `${id}.png` : null;
+        // Rendue hors verrou : la capture ne dépend que du design, et resvg peut
+        // prendre plus de temps qu'un autre écrivain n'en accepte d'attendre.
+        const png = capture ? this.renderCapture(input.designId, target) : null;
+        return this.mutate((draft) => {
+            if (target.kind === "page" &&
+                draft.remarks.some((remark) => remark.designId === input.designId && remark.status === "draft" && remark.target.kind === "page")) {
+                throw new DesignError("This page already has a remark on the whole page: edit it instead of adding another one.");
+            }
+            let number = null;
+            if (target.kind !== "page") {
+                number = (draft.lastNumbers[input.designId] ?? 0) + 1;
+                draft.lastNumbers[input.designId] = number;
+            }
+            if (capture && png)
+                fs.writeFileSync(this.capturePath(capture), png);
+            const now = new Date().toISOString();
+            const remark = {
+                id,
+                designId: input.designId,
+                number,
+                target,
+                text,
+                capture,
+                status: "draft",
+                round: null,
+                createdAt: now,
+                updatedAt: now,
+            };
+            draft.remarks.push(remark);
+            return remark;
+        });
+    }
+    draftOf(file, id) {
+        const remark = file.remarks.find((candidate) => candidate.id === id);
+        if (!remark)
+            throw new DesignError(`Remark "${id}" not found.`);
+        if (remark.status !== "draft") {
+            throw new DesignError(`Remark "${id}" was sent with feedback round ${remark.round}: it can no longer be edited.`);
+        }
+        return remark;
+    }
+    updateText(id, text) {
+        const value = requireText(text);
+        return this.mutate((draft) => {
+            const remark = this.draftOf(draft, id);
+            remark.text = value;
+            remark.updatedAt = new Date().toISOString();
+            return remark;
+        });
+    }
+    /**
+     * Retire une remarque de la liste. La capture d'un brouillon part avec lui ;
+     * celle d'une remarque transmise reste, le retour qui la contient la cite.
+     */
+    delete(id) {
+        const removed = this.mutate((draft) => {
+            const remark = draft.remarks.find((candidate) => candidate.id === id);
+            if (!remark)
+                throw new DesignError(`Remark "${id}" not found.`);
+            draft.remarks = draft.remarks.filter((candidate) => candidate.id !== id);
+            return remark;
+        });
+        if (removed.status === "draft" && removed.capture)
+            fs.rmSync(this.capturePath(removed.capture), { force: true });
+    }
+    /** Retire les remarques d'un design supprimé, selon la même règle que `delete`. */
+    deleteDesign(designId) {
+        const removed = this.mutate((draft) => {
+            const gone = draft.remarks.filter((remark) => remark.designId === designId);
+            draft.remarks = draft.remarks.filter((remark) => remark.designId !== designId);
+            delete draft.lastNumbers[designId];
+            return gone;
+        });
+        for (const remark of removed) {
+            if (remark.status === "draft" && remark.capture)
+                fs.rmSync(this.capturePath(remark.capture), { force: true });
+        }
+    }
+    /** Fige les brouillons choisis dans un nouveau retour nommé, et les marque transmis. */
+    submit(remarkIds, title) {
+        if (remarkIds.length === 0)
+            throw new DesignError("Select at least one remark to send.");
+        const name = requireTitle(title);
+        const names = new Map(this.designs.list().map((design) => [design.id, design.name]));
+        return this.mutate((draft) => {
+            const number = draft.rounds.length + 1;
+            const submittedAt = new Date().toISOString();
+            const selected = new Set(remarkIds);
+            const remarks = orderRemarks(draft.remarks.filter((remark) => selected.has(remark.id)));
+            for (const id of selected)
+                this.draftOf(draft, id);
+            const round = {
+                number,
+                title: name,
+                submittedAt,
+                remarks: remarks.map((remark) => {
+                    const designName = names.get(remark.designId);
+                    if (designName === undefined)
+                        throw new DesignError(`Design "${remark.designId}" of remark "${remark.id}" no longer exists.`);
+                    return {
+                        id: remark.id,
+                        designId: remark.designId,
+                        designName,
+                        number: remark.number,
+                        target: remark.target,
+                        text: remark.text,
+                        capture: remark.capture,
+                        processed: null,
+                    };
+                }),
+            };
+            for (const remark of remarks) {
+                remark.status = "sent";
+                remark.round = number;
+                remark.updatedAt = submittedAt;
+            }
+            draft.rounds.push(round);
+            return round;
+        });
+    }
+    roundOf(file, number) {
+        const round = file.rounds.find((candidate) => candidate.number === number);
+        if (!round)
+            throw new DesignError(`Feedback round ${number} not found. Rounds 1 to ${file.rounds.length} exist.`);
+        return round;
+    }
+    rename(number, title) {
+        const name = requireTitle(title);
+        return this.mutate((draft) => {
+            const round = this.roundOf(draft, number);
+            round.title = name;
+            return round;
+        });
+    }
+    /**
+     * Déclare des remarques d'un retour traitées, ou les rouvre. Une remarque
+     * déjà traitée reste inchangée ; une nouvelle note remplace l'ancienne et
+     * son auteur, en gardant la date d'origine.
+     */
+    setProcessed(input) {
+        const note = typeof input.note === "string" && input.note.trim() !== "" ? input.note.trim() : null;
+        return this.mutate((draft) => {
+            const round = this.roundOf(draft, input.round);
+            const ids = input.remarkIds ?? round.remarks.map((remark) => remark.id);
+            if (ids.length === 0)
+                throw new DesignError("Name at least one remark of the round.");
+            const targets = ids.map((id) => {
+                const remark = round.remarks.find((candidate) => candidate.id === id);
+                if (!remark)
+                    throw new DesignError(`Remark "${id}" is not part of feedback round ${round.number}.`);
+                return remark;
+            });
+            const at = new Date().toISOString();
+            for (const remark of targets) {
+                if (!input.processed) {
+                    remark.processed = null;
+                    continue;
+                }
+                // Une remarque déjà traitée le reste telle quelle, sauf nouvelle note :
+                // tout marquer d'un coup ne réattribue pas le travail de l'agent.
+                if (remark.processed && note === null)
+                    continue;
+                remark.processed = { at: remark.processed?.at ?? at, by: input.by, note };
+            }
+            return round;
+        });
+    }
+}

package/dist/src/core/file-lock.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sérialise un cycle lire-modifier-écrire entre processus. `wx` échoue si le
+ * fichier de verrou existe déjà : c'est l'opération atomique qui départage deux
+ * écrivains concurrents. Non réentrant — ne jamais appeler depuis `fn`.
+ *
+ * `subject` nomme la ressource dans le message d'erreur, p.ex. `Design "landing"`.
+ */
+export declare function withFileLock<T>(lockPath: string, subject: string, fn: () => T): T;

package/dist/src/core/file-lock.js

@@ -0,0 +1,61 @@
+import fs from "fs";
+import { DesignError } from "./node-factory.js";
+/** Au-delà de ce délai, un verrou est réputé abandonné (processus tué en cours d'écriture). */
+const LOCK_STALE_MS = 10_000;
+const LOCK_RETRY_MS = 25;
+const LOCK_TIMEOUT_MS = 5_000;
+/**
+ * Pause bloquante. Les stores sont entièrement synchrones — les rendre
+ * asynchrones pour l'attente d'un verrou contaminerait tous les appelants.
+ */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Sérialise un cycle lire-modifier-écrire entre processus. `wx` échoue si le
+ * fichier de verrou existe déjà : c'est l'opération atomique qui départage deux
+ * écrivains concurrents. Non réentrant — ne jamais appeler depuis `fn`.
+ *
+ * `subject` nomme la ressource dans le message d'erreur, p.ex. `Design "landing"`.
+ */
+export function withFileLock(lockPath, subject, fn) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let fd;
+    for (;;) {
+        try {
+            fd = fs.openSync(lockPath, "wx");
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                // Un processus tué laisse son verrou derrière lui : passé le délai
+                // d'obsolescence on le casse, sinon la ressource serait bloquée à vie.
+                if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+                    fs.unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch {
+                continue; // Verrou disparu entre le open et le stat : on retente aussitôt.
+            }
+            if (Date.now() > deadline) {
+                throw new DesignError(`${subject} is being written by another editor and did not free up in ${LOCK_TIMEOUT_MS} ms. Try again in a moment.`);
+            }
+            sleepSync(LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.closeSync(fd);
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch {
+            // Verrou déjà cassé pour obsolescence par un autre processus.
+        }
+    }
+}