fundus 0.28.1 → 0.29.0

package/dist/server/figma-tags.js

@@ -1,13 +1,12 @@
 /**
- * Planning for the `fundus figma prepare-*-tag` commands. The Figma REST API
- * can read shared plugin data but not write it, so Fundus validates against a
- * REST snapshot of the file plus the local library, then hands back a
- * `use_figma` script (figma-tag-script.ts) that performs the write inside
- * Figma and re-checks the live document first.
+ * Planning and REST writes for `fundus figma set-tag` / `delete-tag`. Fundus
+ * confirms the file's tag links against the nodes that still exist (one link
+ * list plus one `/nodes` call), plans purely on that snapshot and the library,
+ * then writes the links in an order where an interruption can at worst leave
+ * a tag on two nodes (`ambiguous-tag`), never lose it.
  */
-import { assetIdError, buildDeleteTagScript, buildSetTagScript } from '../core/index.js';
-import { fetchFigmaDocument, figmaDocumentNodes, validateFigmaSourceParameters } from './importers/figma.js';
-import { LibraryStore } from './library-store.js';
+import { assetIdError } from '../core/index.js';
+import { createFigmaTagLink, deleteFigmaDevResource, fetchFigmaNodeSummaries, listFigmaTagEntries, validateFigmaSourceParameters } from './importers/figma.js';
 /** An expected refusal that carries the file's current tags so the caller can pick another. */
 export class FigmaTagConflictError extends Error {
     existingTags;
@@ -16,26 +15,24 @@ export class FigmaTagConflictError extends Error {
         this.existingTags = existingTags;
     }
 }
-/** Normalize a `12:34` / `12-34` node id; Fundus imports only this id form. */
+/** Normalize a `12:34` / `12-34` node id; Fundus tags only this id form. */
 export function parseFigmaNodeId(value) {
     if (!/^\d+[-:]\d+$/.test(value)) {
-        throw new Error(`"${value}" is not a taggable Figma node id — use the form 12:34 (or 12-34 as in a node-id link parameter). Nodes inside instances (ids starting with "I") inherit their tag from the main component; tag the node there.`);
+        throw new Error(`"${value}" is not a taggable Figma node id — use the form 12:34 (or 12-34 as in a node-id link parameter). Layers inside instances (ids starting with "I") cannot be tagged.`);
     }
     return value.replace('-', ':');
 }
-function tagListing(nodes) {
-    return nodes
-        .filter((node) => node.tag !== null)
-        .map((node) => ({
-        tag: node.tag,
-        nodeId: node.nodeId,
-        nodeName: node.nodeName,
-        page: node.page
-    }))
-        .sort((a, b) => a.tag.localeCompare(b.tag));
+function tagListing(tags) {
+    return tags.map(({ tag, nodeId, nodeName }) => ({ tag, nodeId, nodeName }));
 }
 function describeNode(node) {
-    return `"${node.nodeName}" (${node.nodeId}) on page "${node.page}"`;
+    return `"${node.nodeName}" (${node.nodeId})`;
+}
+function quotedTags(tags) {
+    return `${tags.length === 1 ? 'tag' : 'tags'} ${tags.map((entry) => `"${entry.tag}"`).join(', ')}`;
+}
+function deleteWrite({ nodeId, nodeName, tag, linkId }) {
+    return { action: 'delete', nodeId, nodeName, tag, linkId };
 }
 /** Whether `record` is a node-mode Figma import of `nodeId` in `fileKey`. */
 function isNodeImportOf(record, fileKey, nodeId) {
@@ -54,21 +51,32 @@ function tagImportedAsset(library, fileKey, tag) {
         ? tag
         : null;
 }
-export function planSetFigmaTag(request, { library, document }) {
+export function planSetFigmaTag(request, { library, snapshot }) {
     const { fileKey, nodeId, tag, force } = request;
     const problem = assetIdError(tag);
     if (problem)
         throw new Error(problem);
-    const nodes = figmaDocumentNodes(document);
-    const existingTags = tagListing(nodes);
+    const { tags, target } = snapshot;
+    if (!target)
+        throw new Error(`Node ${nodeId} does not exist in Figma file "${fileKey}".`);
+    if (target.nodeType === 'DOCUMENT' || target.nodeType === 'CANVAS') {
+        throw new Error(`Node ${describeNode(target)} is a ${target.nodeType} node and cannot be tagged — tag a layer on the page.`);
+    }
+    const existingTags = tagListing(tags);
     const warnings = [];
-    const holders = nodes.filter((node) => node.tag === tag && node.nodeId !== nodeId);
-    if (holders.length > 0) {
-        const described = holders.map(describeNode).join(', ');
+    const others = tags.filter((entry) => entry.tag === tag && entry.nodeId !== nodeId);
+    const ownOther = tags.filter((entry) => entry.nodeId === nodeId && entry.tag !== tag);
+    const carries = tags.some((entry) => entry.nodeId === nodeId && entry.tag === tag);
+    if (others.length > 0) {
+        const described = others.map(describeNode).join(', ');
         if (!force) {
-            throw new FigmaTagConflictError(`Tag "${tag}" is already used by ${described} — choose another tag, or pass --force to move it to node ${nodeId} (existing tags are listed).`, existingTags);
+            throw new FigmaTagConflictError(carries
+                ? `Tag "${tag}" is also on ${described} — pass --force to remove it there and keep it only on node ${describeNode(target)} (existing tags are listed).`
+                : `Tag "${tag}" is already used by ${described} — choose another tag, or pass --force to move it to node ${describeNode(target)} (existing tags are listed).`, existingTags);
         }
-        warnings.push(`Moves tag "${tag}" from ${described} to node ${nodeId}.`);
+        warnings.push(carries
+            ? `Removes tag "${tag}" from ${described}; it stays on node ${describeNode(target)}.`
+            : `Moves tag "${tag}" from ${described} to node ${describeNode(target)}.`);
     }
     const existing = Object.hasOwn(library.assets, tag) ? library.assets[tag] : null;
     if (existing && tagImportedAsset(library, fileKey, tag) === null) {
@@ -88,75 +96,77 @@ export function planSetFigmaTag(request, { library, document }) {
             warnings.push(`Fundus asset "${tag}" already exists from another source — afterwards run ${replace} to switch it to this tag; that replaces its current source.`);
         }
     }
-    const node = nodes.find((candidate) => candidate.nodeId === nodeId) ?? null;
-    if (!node) {
-        warnings.push(`Node ${nodeId} is not in the Figma REST snapshot yet (new or unsynced node); the script verifies it exists before writing.`);
-    }
-    const previousTag = node?.tag ?? null;
-    if (previousTag === tag) {
-        if (!force) {
-            throw new Error(`Node ${describeNode(node)} already carries tag "${tag}" — nothing to do. Pass --force to regenerate the script anyway (e.g. to repair its annotation).`);
-        }
-        warnings.push(`Node ${nodeId} already carries tag "${tag}"; the script rewrites it.`);
-    }
-    else if (previousTag !== null) {
-        const orphaned = tagImportedAsset(library, fileKey, previousTag);
-        const followUp = orphaned
-            ? ` Fundus asset "${orphaned}" is imported from that tag — afterwards run \`fundus asset reimport ${orphaned} --figma-tag ${tag}\` (renames it to "${tag}").`
-            : '';
+    if (ownOther.length > 0) {
+        const followUp = ownOther
+            .map((entry) => tagImportedAsset(library, fileKey, entry.tag))
+            .filter((orphaned) => orphaned !== null)
+            .map((orphaned) => ` Fundus asset "${orphaned}" is imported from that tag — afterwards run \`fundus asset reimport ${orphaned} --figma-tag ${tag}\` (renames it to "${tag}").`)
+            .join('');
         if (!force) {
-            throw new Error(`Node ${describeNode(node)} already carries tag "${previousTag}". Pass --force to replace it.${followUp}`);
+            throw new FigmaTagConflictError(`Node ${describeNode(target)} already carries ${quotedTags(ownOther)}. Pass --force to replace ${ownOther.length === 1 ? 'it' : 'them'}.${followUp}`, existingTags);
         }
-        warnings.push(`Replaces tag "${previousTag}" on node ${nodeId}.${followUp}`);
+        warnings.push(`Replaces ${quotedTags(ownOther)} on node ${describeNode(target)}.${followUp}`);
     }
-    if (tagImportedAsset(library, fileKey, tag) !== null && previousTag !== tag) {
+    const writes = [
+        ...(carries ? [] : [{ action: 'create', nodeId, nodeName: target.nodeName, tag }]),
+        ...ownOther.map(deleteWrite),
+        ...others.map(deleteWrite)
+    ];
+    if (tagImportedAsset(library, fileKey, tag) !== null && writes.length > 0) {
         warnings.push(`Fundus asset "${tag}" is imported from this tag; its next \`fundus asset reimport ${tag}\` resolves to this node.`);
     }
     return {
         fileKey,
         nodeId,
+        nodeName: target.nodeName,
         tag,
-        previousTag,
-        warnings,
-        code: buildSetTagScript({ nodeId, tag, force })
+        previousTag: ownOther[0]?.tag ?? (carries ? tag : null),
+        movedFrom: others.map(({ nodeId, nodeName }) => ({ nodeId, nodeName })),
+        writes,
+        warnings
     };
 }
-export function planDeleteFigmaTag(request, { library, document }) {
+export function planDeleteFigmaTag(request, { library, snapshot }) {
     const { fileKey, force } = request;
     if (request.tag !== undefined) {
         const problem = assetIdError(request.tag);
         if (problem)
             throw new Error(problem);
     }
-    const nodes = figmaDocumentNodes(document);
-    const existingTags = tagListing(nodes);
-    let node;
+    const { tags, target } = snapshot;
+    const existingTags = tagListing(tags);
+    let holders;
     if (request.nodeId !== undefined) {
-        const found = nodes.find((candidate) => candidate.nodeId === request.nodeId);
-        if (!found) {
-            throw new Error(`Node ${request.nodeId} is not in Figma file "${fileKey}".`);
+        if (!target) {
+            throw new Error(`Node ${request.nodeId} does not exist in Figma file "${fileKey}".`);
         }
-        if (found.tag === null) {
-            throw new FigmaTagConflictError(`Node ${describeNode(found)} carries no Fundus tag (existing tags are listed).`, existingTags);
+        const own = tags.filter((entry) => entry.nodeId === request.nodeId);
+        if (own.length === 0) {
+            throw new FigmaTagConflictError(`Node ${describeNode(target)} carries no Fundus tag (existing tags are listed).`, existingTags);
         }
-        if (request.tag !== undefined && found.tag !== request.tag) {
-            throw new FigmaTagConflictError(`Node ${describeNode(found)} carries tag "${found.tag}", not "${request.tag}".`, existingTags);
+        holders = request.tag === undefined ? own : own.filter((entry) => entry.tag === request.tag);
+        if (holders.length === 0) {
+            throw new FigmaTagConflictError(`Node ${describeNode(target)} carries ${quotedTags(own)}, not "${request.tag}".`, existingTags);
+        }
+        if (new Set(holders.map((entry) => entry.tag)).size > 1) {
+            throw new FigmaTagConflictError(`Node ${describeNode(target)} carries ${quotedTags(own)} — pass --tag to pick one.`, existingTags);
         }
-        node = found;
     }
     else {
-        const matches = nodes.filter((candidate) => candidate.tag === request.tag);
-        if (matches.length === 0) {
+        holders = tags.filter((entry) => entry.tag === request.tag);
+        if (holders.length === 0) {
             throw new FigmaTagConflictError(`No node carries tag "${request.tag}" in Figma file "${fileKey}" (existing tags are listed).`, existingTags);
         }
-        if (matches.length > 1) {
-            throw new FigmaTagConflictError(`Tag "${request.tag}" is on ${matches.length} nodes (${matches.map((match) => match.nodeId).join(', ')}) — pass --node-id to pick one.`, existingTags);
+        const nodeIds = [...new Set(holders.map((entry) => entry.nodeId))];
+        if (nodeIds.length > 1) {
+            throw new FigmaTagConflictError(`Tag "${request.tag}" is on ${nodeIds.length} nodes (${nodeIds.join(', ')}) — pass --node-id to pick one.`, existingTags);
         }
-        node = matches[0];
     }
-    const tag = node.tag;
+    const [holder] = holders;
     const warnings = [];
-    const imported = tagImportedAsset(library, fileKey, tag);
+    // Deleting one of several holders fixes an ambiguous tag rather than losing it.
+    const keptElsewhere = tags.some((entry) => entry.tag === holder.tag && entry.nodeId !== holder.nodeId);
+    const imported = keptElsewhere ? null : tagImportedAsset(library, fileKey, holder.tag);
     if (imported) {
         const consequence = `Fundus asset "${imported}" is imported from this tag; without it, \`fundus asset reimport ${imported}\` fails until the tag is set again.`;
         if (!force)
@@ -165,15 +175,56 @@ export function planDeleteFigmaTag(request, { library, document }) {
     }
     return {
         fileKey,
-        nodeId: node.nodeId,
-        tag,
-        warnings,
-        code: buildDeleteTagScript({ nodeId: node.nodeId, tag })
+        nodeId: holder.nodeId,
+        nodeName: holder.nodeName,
+        tag: holder.tag,
+        writes: holders.map(deleteWrite),
+        warnings
     };
 }
-/** Load the library and the file's REST document for planning. */
-export async function loadFigmaTagPlanContext(config, fileKey) {
-    const library = await new LibraryStore(config).read();
-    const document = await fetchFigmaDocument(fileKey, { config, fetch: globalThis.fetch });
-    return { library, document };
+/**
+ * The file's tag links confirmed against the nodes that exist: one link list,
+ * then one `/nodes` call over every tagged node plus the target. Links on
+ * missing nodes are orphaned and dropped, so nothing ever touches them.
+ */
+export async function loadFigmaTagSnapshot(context, fileKey, targetNodeId) {
+    const entries = await listFigmaTagEntries(fileKey, context);
+    const nodeIds = new Set(entries.map((entry) => entry.nodeId));
+    if (targetNodeId !== undefined)
+        nodeIds.add(targetNodeId);
+    const nodes = new Map((await fetchFigmaNodeSummaries(fileKey, [...nodeIds], context)).map((node) => [
+        node.nodeId,
+        node
+    ]));
+    const tags = [];
+    for (const { tag, nodeId, linkId } of entries) {
+        const node = nodes.get(nodeId);
+        if (node)
+            tags.push({ tag, nodeId, nodeName: node.nodeName, nodeType: node.nodeType, linkId });
+    }
+    return {
+        tags,
+        target: targetNodeId === undefined ? null : (nodes.get(targetNodeId) ?? null)
+    };
+}
+/** Runs the writes in order and stops at the first failure; retries live in the REST client. */
+export async function applyFigmaTagWrites(fileKey, writes, context) {
+    for (const [index, write] of writes.entries()) {
+        try {
+            if (write.action === 'create') {
+                await createFigmaTagLink(fileKey, write.nodeId, write.tag, context);
+            }
+            else {
+                await deleteFigmaDevResource(fileKey, write.linkId, context);
+            }
+        }
+        catch (cause) {
+            return {
+                written: writes.slice(0, index),
+                failure: { write, message: cause instanceof Error ? cause.message : String(cause) },
+                notWritten: writes.slice(index)
+            };
+        }
+    }
+    return { written: [...writes], failure: null, notWritten: [] };
 }

package/dist/server/importers/figma.d.ts

@@ -1,3 +1,4 @@
+import { type FigmaTagEntry } from '../../core/index.js';
 import { type ImporterContext, type ServerSourceImporter } from './contract.js';
 import { type PinnedHttpsTarget } from './pinned-https.js';
 export interface FigmaNodeSourceParameters {
@@ -10,9 +11,9 @@ export interface FigmaNodeSourceParameters {
 export interface FigmaTagSourceParameters {
     mode: 'tag';
     fileKey: string;
-    /** The Fundus asset id carried in Figma as `sharedPluginData.fundus.assetId`. */
+    /** The Fundus asset id, carried in Figma as a Fundus tag link (Dev Resource) on the node. */
     fundusTag: string;
-    /** Resolved node id (colon-form), cached from the last tag resolution. */
+    /** Node id (colon-form) of the last tag resolution; every reimport resolves the tag again. */
     nodeId: string;
     format: 'png';
     scale: 1 | 2 | 3 | 4;
@@ -40,22 +41,26 @@ export declare function parseFigmaFileKey(value: string): string;
 export declare function validateFigmaSourceParameters(value: unknown): FigmaSourceParameters;
 export declare function resolveSafeDownloadTarget(value: string | URL): Promise<PinnedHttpsTarget>;
 export declare function assertSafeDownloadUrl(value: string | URL): Promise<URL>;
-/** One node in a Figma REST document tree, as the tag commands report it. */
-export interface FigmaDocumentNode {
+/** Every Fundus tag link in the file (orphaned ones included); each entry has its `linkId`. */
+export declare function listFigmaTagEntries(fileKey: string, context: ImporterContext): Promise<Array<FigmaTagEntry & {
+    linkId: string;
+}>>;
+export interface FigmaNodeSummary {
     nodeId: string;
     nodeName: string;
-    /** Name of the page (canvas) containing the node. */
-    page: string;
-    /** The node's Fundus tag, or null when untagged. */
-    tag: string | null;
+    nodeType: string;
 }
+/** The requested nodes that exist; Figma answers deleted or unknown ids with `null` (dropped). */
+export declare function fetchFigmaNodeSummaries(fileKey: string, nodeIds: readonly string[], context: ImporterContext): Promise<FigmaNodeSummary[]>;
+export declare function createFigmaTagLink(fileKey: string, nodeId: string, tag: string, context: ImporterContext): Promise<void>;
+export declare function deleteFigmaDevResource(fileKey: string, linkId: string, context: ImporterContext): Promise<void>;
 /**
- * Every taggable node in a REST document tree (`plugin_data=shared`), in
- * document order. Nodes inside instances are skipped: they echo the main
- * component node's tag, and Fundus imports only plain `12:34` node ids.
+ * The one renderable node carrying `tag`. All candidates go into a single
+ * `/images` call, which answers deleted nodes with `null`; a live but
+ * unrenderable second candidate therefore goes unnoticed.
  */
-export declare function figmaDocumentNodes(document: unknown): FigmaDocumentNode[];
-/** The whole document tree of a Figma file, including every node's shared plugin data. */
-export declare function fetchFigmaDocument(fileKey: string, context: ImporterContext): Promise<unknown>;
-export declare function resolveTagToNode(fileKey: string, tag: string, context: ImporterContext): Promise<string>;
+export declare function resolveTaggedNode(fileKey: string, tag: string, scale: 1 | 2 | 3 | 4, context: ImporterContext): Promise<{
+    nodeId: string;
+    imageUrl: string;
+}>;
 export declare const figmaSourceImporter: ServerSourceImporter<FigmaImportInput, FigmaSourceParameters>;