fundus 0.28.1 → 0.29.0

package/dist/server/cli-commands.d.ts

@@ -6,7 +6,7 @@ export declare const ASSET_HELP = "fundus asset \u2014 inspect and mutate assets
 export declare const ASSET_LIST_HELP: string;
 export declare const ASSET_SHOW_HELP = "fundus asset show \u2014 one asset in detail\n\nUsage: fundus asset show <id> [--json]\n\nPrints the asset's raw file, content hash, parameters, explicit +\npassive manifest memberships, proxy status, reference edges (outgoing\nand incoming), and warnings.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>}\n  --help   this help\n\nRead-only: nothing is processed or written.\n\nExample:\n  fundus asset show navigationPanel --json\n";
 export declare const ASSET_INGEST_HELP: string;
-export declare const ASSET_REIMPORT_HELP = "fundus asset reimport \u2014 refresh an asset from its saved source\n\nUsage: fundus asset reimport <id> [--json]\n       fundus asset reimport <id> --figma-link <selection-link> [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --figma-tag <newTag> [--figma-file <key|link>] [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --figma-file <key|link> [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --scale <1|2|3|4> [--json]\n\nWithout overrides, re-materializes the persisted importer source (a Figma tag\nasset re-scans its file for the tagged node, self-healing after node moves).\nA Figma override may update the source or scale; omitted values are preserved.\nAsset type, parameters, folder, and manifests remain unchanged. Raw-file drift\nor concurrent changes abort without overwriting local edits.\n\nNode vs tag assets accept different overrides. A node asset takes --figma-link\n(and --scale); --figma-tag and --figma-file are rejected. A tag asset takes\n--figma-tag to change its tag, --figma-file to re-point in place to another\ndocument, and --scale; --figma-link is rejected. Because the tag IS the asset\nid, changing it with --figma-tag renames the asset to the new tag (the new id\nmust be valid and unused).\n\nFlags:\n  --figma-link <link>  node asset only: replace the persisted file/node selection\n  --figma-tag <newTag> tag asset only: change the tag, renaming the asset to the\n                       new tag (the tag is the asset id)\n  --figma-file <key|link>\n                       tag asset only: re-point in place to another file (raw\n                       key or a Figma link)\n  --scale <1|2|3|4>    replace the persisted Figma export scale\n  --json               print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help               this help\n\nExample:\n  fundus asset reimport navigationPanel\n  fundus asset reimport navigationPanel --figma-link '<new-selection-link>'\n  fundus asset reimport navigationPanel --figma-tag mainNavigationPanel\n  fundus asset reimport navigationPanel --figma-file def456\n  fundus asset reimport navigationPanel --scale 4\n  fundus asset reimport navigationPanel --figma-link '<new-selection-link>' --scale 4 --json\n";
+export declare const ASSET_REIMPORT_HELP = "fundus asset reimport \u2014 refresh an asset from its saved source\n\nUsage: fundus asset reimport <id> [--json]\n       fundus asset reimport <id> --figma-link <selection-link> [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --figma-tag <newTag> [--figma-file <key|link>] [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --figma-file <key|link> [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --scale <1|2|3|4> [--json]\n\nWithout overrides, re-materializes the persisted importer source (a Figma tag\nasset looks up the node carrying the tag again, self-healing after node moves).\nA Figma override may update the source or scale; omitted values are preserved.\nAsset type, parameters, folder, and manifests remain unchanged. Raw-file drift\nor concurrent changes abort without overwriting local edits.\n\nNode vs tag assets accept different overrides. A node asset takes --figma-link\n(and --scale); --figma-tag and --figma-file are rejected. A tag asset takes\n--figma-tag to change its tag, --figma-file to re-point in place to another\ndocument, and --scale; --figma-link is rejected. Because the tag IS the asset\nid, changing it with --figma-tag renames the asset to the new tag (the new id\nmust be valid and unused).\n\nFlags:\n  --figma-link <link>  node asset only: replace the persisted file/node selection\n  --figma-tag <newTag> tag asset only: change the tag, renaming the asset to the\n                       new tag (the tag is the asset id)\n  --figma-file <key|link>\n                       tag asset only: re-point in place to another file (raw\n                       key or a Figma link)\n  --scale <1|2|3|4>    replace the persisted Figma export scale\n  --json               print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help               this help\n\nExample:\n  fundus asset reimport navigationPanel\n  fundus asset reimport navigationPanel --figma-link '<new-selection-link>'\n  fundus asset reimport navigationPanel --figma-tag mainNavigationPanel\n  fundus asset reimport navigationPanel --figma-file def456\n  fundus asset reimport navigationPanel --scale 4\n  fundus asset reimport navigationPanel --figma-link '<new-selection-link>' --scale 4 --json\n";
 export declare const ASSET_REPLACE_HELP = "fundus asset replace \u2014 replace an asset's raw file\n\nUsage: fundus asset replace <id> <file|figma-selection-link>\n                            [--from <file|figma>] [--scale <1|2|3|4>] [--json]\n       fundus asset replace <id> --from figma --figma-tag <tag>\n                            [--figma-file <key|link>] [--scale <1|2|3|4>] [--json]\n\nReplaces the stored raw file and content hash while preserving the asset's\nid, type, folder, parameters, references, and manifest memberships. The new\nsource must be accepted by the existing asset type. File replacement remains\nthe default and disconnects any saved source. Figma replacement stores the new\nselection (node mode) or tag (tag mode) as a repeatable source. A tag\nreplacement must resolve to the asset's own id, so it can only re-point the\nsame asset's own tag. Runs the full autosave chain, so delivered assets are\nreprocessed and manifests regenerated.\n\nFlags:\n  --from <file|figma> replacement source; default: file\n  --figma-tag <tag>   Figma tag mode: replace from the node tagged with this\n                       Fundus asset id (takes no positional link)\n  --figma-file <key|link>\n                       fileKey for tag mode as a raw key or a Figma link;\n                       defaults to import.figma.defaultFileKey from\n                       fundus.config.ts\n  --scale <1|2|3|4>   Figma export scale; default:\n                      import.figma.defaults.scale from fundus.config.ts\n  --json              print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help              this help\n\nExample:\n  fundus asset replace navigationPanel ./exports/navigation_panel_v2.png --json\n  fundus asset replace navigationPanel \\\n    'https://www.figma.com/design/abc/UI?node-id=12-34' --from figma --scale 3 --json\n  fundus asset replace navigationPanel --from figma \\\n    --figma-tag navigationPanel --figma-file abc --scale 3 --json\n";
 export declare const ASSET_SET_HELP = "fundus asset set \u2014 update an asset's parameters and/or memberships\n\nUsage: fundus asset set <id> [--parameters <json>] [--manifests <a,b>]\n                             [--compression-x <0-100>] [--compression-y <0-100>] [--json]\n\nAt least one change flag is required. Runs the full autosave chain\n(write library \u2192 process \u2192 regenerate manifest modules).\n\nFlags:\n  --parameters <json>  SHALLOW MERGE at the top level onto the current\n                       parameters, then plugin validation:\n                         {\"preset\": \"webp-hq\"}        sets one field,\n                                                      keeps the others\n                         {\"chromaKey\": {\u2026}}           replaces the whole\n                                                      chromaKey object\n                         {\"mask\": null}               clears an optional\n                                                      field\n                         {\"mask\": {\"$asset\": \"someImage\"}}\n                                                      sets an asset\n                                                      reference\n  --manifests <a,b>    REPLACES the explicit membership set (declarative,\n                       idempotent); --manifests \"\" clears it\n  --compression-x <0-100>\n  --compression-y <0-100>\n                       set one Slice stretch-compression axis while preserving\n                       the omitted axis; setting both axes to 0 removes\n                       compression. These values override compression supplied\n                       through --parameters in the same invocation\n  --json               print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help               this help\n\nThe mutation is validated first and rejected (exit 1, nothing written)\nif it would leave the library invalid \u2014 e.g. a reference to a missing\nasset, a reference cycle, or an unknown manifest name. Ingest reference\ntargets before pointing at them.\n\nExample:\n  fundus asset set navigationPanel --compression-x 75 --compression-y 25 --json\n  fundus asset set characterIdle \\\n    --parameters '{\"mask\": {\"$asset\": \"characterIdleMask\"}}' --json\n";
 export declare const ASSET_RENAME_HELP = "fundus asset rename \u2014 rename an asset id\n\nUsage: fundus asset rename <id> <newId> [--json]\n\nRenames the asset's id (the raw file keeps its name \u2014 ids are the\nstable key) and re-hashes its proxy under the new id via the autosave\nchain. Fails if another asset references <id> \u2014 update the referrers\nfirst \u2014 or if <newId> is taken or invalid.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset rename sidebarPanel navigationPanel --json\n";

package/dist/server/cli-commands.js

@@ -437,7 +437,7 @@ Usage: fundus asset reimport <id> [--json]
        fundus asset reimport <id> --scale <1|2|3|4> [--json]
 
 Without overrides, re-materializes the persisted importer source (a Figma tag
-asset re-scans its file for the tagged node, self-healing after node moves).
+asset looks up the node carrying the tag again, self-healing after node moves).
 A Figma override may update the source or scale; omitted values are preserved.
 Asset type, parameters, folder, and manifests remain unchanged. Raw-file drift
 or concurrent changes abort without overwriting local edits.

package/dist/server/cli-figma-tags.d.ts

@@ -1,2 +1,2 @@
-export declare const FIGMA_HELP = "fundus figma \u2014 prepare Fundus tag writes in Figma\n\nUsage: fundus figma <subcommand> \u2026 [--json]\n\nThe Figma REST API cannot write plugin data, so Fundus cannot tag nodes by\nitself. These commands check the request against the file (via REST) and the\nlibrary, then print a script. Run that script unchanged with the Figma MCP\n`use_figma` tool on the same file: it re-checks the live document (the set\nscript loads every page, which takes a few seconds on large files), writes\nthe tag and its Dev Mode annotation exactly like the Fundus Figma plugin, and\nreturns the result. It throws without writing when the document changed.\n\nSubcommands:\n  prepare-set-tag       tag a node (--node-id, --tag)\n  prepare-delete-tag    remove a node's tag (--tag or --node-id)\n\nRequires import.figma.token in fundus.config.ts.\n";
+export declare const FIGMA_HELP = "fundus figma \u2014 write Fundus tag links in Figma\n\nUsage: fundus figma <subcommand> \u2026 [--json]\n\nA Fundus tag is a Dev Resources link on the node:\nhttps://fundus.invalid/asset/<tag>, named \"Fundus: <tag>\". These commands\nread the file's links and the tagged nodes over the REST API, check the\nrequest against them and the library, then write the links directly. The\nDev Mode annotation follows once the Fundus Figma plugin opens the node's page.\n\nSubcommands:\n  set-tag       tag a node (--node-id, --tag)\n  delete-tag    remove a node's tag (--tag or --node-id)\n\nRequires import.figma.token in fundus.config.ts: a personal access token with\nthe file_content:read and file_dev_resources:read scopes, plus\nfile_dev_resources:write for these commands.\n";
 export declare function runFigmaCommand(argumentList: string[]): Promise<void>;

package/dist/server/cli-figma-tags.js

@@ -1,98 +1,110 @@
 /**
- * The `fundus figma` command group: prepare Fundus tag writes for Figma. The
- * REST API cannot write plugin data, so these commands only validate (tag
- * grammar, uniqueness in the file, library collisions) and print a script the
- * caller runs with Figma's MCP `use_figma` tool.
+ * The `fundus figma` command group: set and delete Fundus tag links on Figma
+ * nodes over the REST API. The tag commands validate against a confirmed
+ * snapshot of the file (see figma-tags.ts) and the library before writing.
  */
 import { assetIdError } from '../core/index.js';
 import { loadConfig } from './config-loader.js';
-import { FigmaTagConflictError, loadFigmaTagPlanContext, parseFigmaNodeId, planDeleteFigmaTag, planSetFigmaTag } from './figma-tags.js';
+import { FigmaTagConflictError, applyFigmaTagWrites, loadFigmaTagSnapshot, parseFigmaNodeId, planDeleteFigmaTag, planSetFigmaTag } from './figma-tags.js';
+import { LibraryStore } from './library-store.js';
 import { resolveFigmaFileKeyFlag } from './cli-commands.js';
 import { CliUsageError, parseArguments, printJsonDocument, requirePositionals } from './cli-io.js';
-export const FIGMA_HELP = `fundus figma — prepare Fundus tag writes in Figma
+const NEXT_STEP = "The Fundus Figma plugin updates the node's annotation once it opens the node's page.";
+export const FIGMA_HELP = `fundus figma — write Fundus tag links in Figma
 
 Usage: fundus figma <subcommand> … [--json]
 
-The Figma REST API cannot write plugin data, so Fundus cannot tag nodes by
-itself. These commands check the request against the file (via REST) and the
-library, then print a script. Run that script unchanged with the Figma MCP
-\`use_figma\` tool on the same file: it re-checks the live document (the set
-script loads every page, which takes a few seconds on large files), writes
-the tag and its Dev Mode annotation exactly like the Fundus Figma plugin, and
-returns the result. It throws without writing when the document changed.
+A Fundus tag is a Dev Resources link on the node:
+https://fundus.invalid/asset/<tag>, named "Fundus: <tag>". These commands
+read the file's links and the tagged nodes over the REST API, check the
+request against them and the library, then write the links directly. The
+Dev Mode annotation follows once the Fundus Figma plugin opens the node's page.
 
 Subcommands:
-  prepare-set-tag       tag a node (--node-id, --tag)
-  prepare-delete-tag    remove a node's tag (--tag or --node-id)
+  set-tag       tag a node (--node-id, --tag)
+  delete-tag    remove a node's tag (--tag or --node-id)
 
-Requires import.figma.token in fundus.config.ts.
+Requires import.figma.token in fundus.config.ts: a personal access token with
+the file_content:read and file_dev_resources:read scopes, plus
+file_dev_resources:write for these commands.
 `;
-const PREPARE_SET_TAG_HELP = `fundus figma prepare-set-tag — prepare a use_figma script that tags a node
+const SET_TAG_HELP = `fundus figma set-tag — tag a Figma node with a Fundus asset id
 
-Usage: fundus figma prepare-set-tag --node-id <id> --tag <tag>
-                                    [--file <key|link>] [--force] [--json]
+Usage: fundus figma set-tag --node-id <id> --tag <tag>
+                            [--file <key|link>] [--force] [--json]
 
-Refuses unless --force, listing the file's existing tags, when another node
-already carries the tag; --force moves the tag (and its annotation) from those
-nodes to this one, so it stays unique. Also refuses unless --force when the
-node already carries a tag (the same one or another) or a Fundus asset with
-that id exists from another source. An asset imported from this very node by
-node id is not a conflict: tagging prepares its move to the tag
-(\`fundus asset replace <tag> --from figma --figma-tag <tag>\` afterwards keeps
-its id, parameters, and manifests).
+Adds the tag link to the node. A node that already carries the tag is left as
+is. Refuses unless --force, listing the file's existing tags, when another node
+carries the tag, when the node carries another tag, or when a Fundus asset
+with that id exists from another source. An asset imported from this very
+node by node id is not a conflict: afterwards
+\`fundus asset replace <tag> --from figma --figma-tag <tag>\` moves it to the
+tag and keeps its id, parameters, and manifests.
+
+The new link is written first, then --force deletes the node's other tag
+links and the tag's links on other nodes. A failed step stops the rest, so an
+interruption at worst leaves the tag on two nodes (\`ambiguous-tag\` on
+import), never loses it. Links on deleted nodes and non-Fundus links are
+never touched.
 
 Flags:
   --node-id <id>      the node to tag: 12:34 or 12-34
-  --tag <tag>         the Fundus asset id to store on the node (camelCase)
+  --tag <tag>         the Fundus asset id to link to the node (camelCase)
   --file <key|link>   Figma file key or link; default:
                       import.figma.defaultFileKey from fundus.config.ts
-  --force             always set the tag: replace the node's current tag,
-                      rewrite the same tag, move it from other nodes, or tag
-                      despite a Fundus asset from another source
+  --force             replace the node's other tags, move the tag away from
+                      other nodes (this also resolves \`ambiguous-tag\`), or
+                      tag despite a Fundus asset from another source
   --json              print {"ok": true, "fileKey", "nodeId", "tag",
-                      "previousTag", "warnings", "next", "code"}; a refusal
-                      prints {"ok": false, "error": {"message"}, "existingTags"}
-                      when the file's tags help choose another
+                      "previousTag", "movedFrom": [{"nodeId", "nodeName"}],
+                      "warnings", "next"}; a refusal prints {"ok": false,
+                      "error": {"message"}, "existingTags": [{"tag", "nodeId",
+                      "nodeName"}]}; a failed write prints {"ok": false,
+                      "error": {"message"}, "written": [{"action":
+                      "create"|"delete", "nodeId", "nodeName", "tag"}],
+                      "notWritten": [same]} and exits 1
   --help              this help
 
-Without --json the script goes to stdout, everything else to stderr.
-The script returns {"ok": true, "nodeId", "nodeName", "tag", "previousTag",
-"annotated", "movedFrom": [{"nodeId", "nodeName", "page"}]}. Afterwards: \`fundus asset ingest --from figma --figma-tag <tag>\`.
+Needs a token with file_content:read, file_dev_resources:read, and
+file_dev_resources:write. The Dev Mode annotation appears once the Fundus
+Figma plugin opens the node's page. Afterwards:
+\`fundus asset ingest --from figma --figma-tag <tag>\`.
 
 Example:
-  fundus figma prepare-set-tag --file 'https://www.figma.com/design/abc/UI' \\
+  fundus figma set-tag --file 'https://www.figma.com/design/abc/UI' \\
     --node-id 12-34 --tag navigationPanel --json
 `;
-const PREPARE_DELETE_TAG_HELP = `fundus figma prepare-delete-tag — prepare a use_figma script that removes a tag
+const DELETE_TAG_HELP = `fundus figma delete-tag — remove a Fundus tag from a Figma node
 
-Usage: fundus figma prepare-delete-tag (--tag <tag> | --node-id <id>)
-                                       [--file <key|link>] [--force] [--json]
+Usage: fundus figma delete-tag (--tag <tag> | --node-id <id>)
+                               [--file <key|link>] [--force] [--json]
 
-Removes the tag and its Dev Mode annotation; other annotations stay. Refuses
-unless --force when a Fundus asset is imported from the tag (its reimport
-would fail afterwards).
+Deletes the node's tag link. The node must exist: a link left on a deleted
+node is ignored, not cleaned up. Refuses unless --force when a Fundus asset is
+imported from the tag (its reimport would fail afterwards).
 
 Flags:
   --tag <tag>         the tag to remove (must be on exactly one node)
   --node-id <id>      the node whose tag to remove: 12:34 or 12-34; with --tag,
-                      both must match
+                      both must match; a node with several tags needs --tag
   --file <key|link>   Figma file key or link; default:
                       import.figma.defaultFileKey from fundus.config.ts
   --force             delete even when a Fundus asset is imported from the tag
   --json              print {"ok": true, "fileKey", "nodeId", "tag",
-                      "warnings", "next", "code"}; refusals as for
-                      prepare-set-tag
+                      "warnings", "next"}; refusals and failed writes as for
+                      set-tag
   --help              this help
 
-The script returns {"ok": true, "nodeId", "nodeName", "removedTag",
-"annotationRemoved"}.
+Needs a token with file_content:read, file_dev_resources:read, and
+file_dev_resources:write. The Fundus Figma plugin removes the node's
+annotation once it opens the node's page.
 
 Example:
-  fundus figma prepare-delete-tag --tag navigationPanel --json
+  fundus figma delete-tag --tag navigationPanel --json
 `;
 const FIGMA_SUBCOMMAND_HELP = {
-    'prepare-set-tag': PREPARE_SET_TAG_HELP,
-    'prepare-delete-tag': PREPARE_DELETE_TAG_HELP
+    'set-tag': SET_TAG_HELP,
+    'delete-tag': DELETE_TAG_HELP
 };
 const TAG_FLAGS = {
     json: { takesValue: false },
@@ -112,17 +124,17 @@ function stringFlag(parsed, name) {
     const value = parsed.flags[name];
     return typeof value === 'string' ? value : undefined;
 }
-async function resolvePlanInputs(parsed, commandPath) {
+async function resolvePlanInputs(parsed, commandPath, targetNodeId) {
     const config = await loadConfig(process.cwd());
     const fileFlag = stringFlag(parsed, 'file');
     const fileKey = fileFlag !== undefined ? resolveFigmaFileKeyFlag(fileFlag) : config.import.figma.defaultFileKey;
     if (!fileKey) {
         throw new CliUsageError(`\`${commandPath}\` needs --file <key|link> or import.figma.defaultFileKey in fundus.config.ts.`);
     }
-    return { fileKey, context: await loadFigmaTagPlanContext(config, fileKey) };
-}
-function nextStep(fileKey, subject = '"code"') {
-    return `Run ${subject} unchanged with the Figma MCP use_figma tool on fileKey "${fileKey}". It returns the result as JSON, or throws without writing when the live document disagrees.`;
+    const context = { config, fetch: globalThis.fetch };
+    const library = await new LibraryStore(config).read();
+    const snapshot = await loadFigmaTagSnapshot(context, fileKey, targetNodeId);
+    return { fileKey, context, plan: { library, snapshot } };
 }
 /** Refusals that list the file's tags get their own document; others take the standard error path. */
 function reportConflict(cause, json) {
@@ -139,24 +151,63 @@ function reportConflict(cause, json) {
         console.error(`fundus: ${cause.message}`);
         console.error(cause.existingTags.length === 0 ? 'No tags in this file yet.' : 'Existing tags in this file:');
         for (const entry of cause.existingTags) {
-            console.error(`  ${entry.tag}  ${entry.nodeId}  "${entry.nodeName}" (page "${entry.page}")`);
+            console.error(`  ${entry.tag}  ${entry.nodeId}  "${entry.nodeName}"`);
         }
     }
     process.exitCode = 1;
     return true;
 }
-function printPlan(plan, document, json) {
+/** The printed form of a write: the link id is internal. */
+function publicWrite({ action, nodeId, nodeName, tag }) {
+    return { action, nodeId, nodeName, tag };
+}
+function describeWrite(write) {
+    return `${write.action === 'create' ? 'add' : 'remove'} tag "${write.tag}" on "${write.nodeName}" (${write.nodeId})`;
+}
+/**
+ * Applies the plan's writes and prints the outcome. Returns false after
+ * reporting a failed write, which leaves exit code 1.
+ */
+async function writeAndReport(fileKey, writes, warnings, context, json) {
+    const { written, failure, notWritten } = await applyFigmaTagWrites(fileKey, writes, context);
+    if (!failure)
+        return true;
+    // Rerunning plans only the steps still missing, and prints the plan's hints again.
+    const message = `Could not ${describeWrite(failure.write)}: ${failure.message}${written.length > 0 ? ' Rerun the same command to finish the remaining steps.' : ''}`;
     if (json) {
-        printJsonDocument({ ok: true, ...document, next: nextStep(plan.fileKey), code: plan.code });
+        printJsonDocument({
+            ok: false,
+            error: { message },
+            written: written.map(publicWrite),
+            notWritten: notWritten.map(publicWrite)
+        });
+    }
+    else {
+        for (const warning of warnings)
+            console.error(`⚠ ${warning}`);
+        console.error(`fundus: ${message}`);
+        console.error(written.length === 0 ? 'Nothing was written.' : 'Written:');
+        for (const write of written)
+            console.error(`  ${describeWrite(write)}`);
+        console.error('Not written:');
+        for (const write of notWritten)
+            console.error(`  ${describeWrite(write)}`);
+    }
+    process.exitCode = 1;
+    return false;
+}
+function printSuccess(summary, warnings, document, json) {
+    if (json) {
+        printJsonDocument({ ok: true, ...document, warnings, next: NEXT_STEP });
         return;
     }
-    for (const warning of plan.warnings)
+    for (const warning of warnings)
         console.error(`⚠ ${warning}`);
-    console.error(`${nextStep(plan.fileKey, 'the script below')}\n`);
-    process.stdout.write(plan.code);
+    console.log(summary);
+    console.log(NEXT_STEP);
 }
-async function runPrepareSetTag(argumentList) {
-    const commandPath = 'fundus figma prepare-set-tag';
+async function runSetTag(argumentList) {
+    const commandPath = 'fundus figma set-tag';
     const parsed = parseArguments(argumentList, TAG_FLAGS, commandPath);
     requirePositionals(parsed, [], commandPath);
     const nodeIdFlag = stringFlag(parsed, 'node-id');
@@ -167,24 +218,30 @@ async function runPrepareSetTag(argumentList) {
     const nodeId = parseFigmaNodeId(nodeIdFlag);
     assertTag(tag);
     const json = parsed.flags.json === true;
-    const { fileKey, context } = await resolvePlanInputs(parsed, commandPath);
+    const { fileKey, context, plan: planContext } = await resolvePlanInputs(parsed, commandPath, nodeId);
+    let plan;
     try {
-        const plan = planSetFigmaTag({ fileKey, nodeId, tag, force: parsed.flags.force === true }, context);
-        printPlan(plan, {
-            fileKey,
-            nodeId: plan.nodeId,
-            tag: plan.tag,
-            previousTag: plan.previousTag,
-            warnings: plan.warnings
-        }, json);
+        plan = planSetFigmaTag({ fileKey, nodeId, tag, force: parsed.flags.force === true }, planContext);
     }
     catch (cause) {
-        if (!reportConflict(cause, json))
-            throw cause;
+        if (reportConflict(cause, json))
+            return;
+        throw cause;
     }
+    if (!(await writeAndReport(fileKey, plan.writes, plan.warnings, context, json)))
+        return;
+    printSuccess(plan.writes.length === 0
+        ? `Node "${plan.nodeName}" (${nodeId}) already carries tag "${tag}"; nothing to write.`
+        : `Tagged "${plan.nodeName}" (${nodeId}) with "${tag}".`, plan.warnings, {
+        fileKey,
+        nodeId,
+        tag,
+        previousTag: plan.previousTag,
+        movedFrom: plan.movedFrom
+    }, json);
 }
-async function runPrepareDeleteTag(argumentList) {
-    const commandPath = 'fundus figma prepare-delete-tag';
+async function runDeleteTag(argumentList) {
+    const commandPath = 'fundus figma delete-tag';
     const parsed = parseArguments(argumentList, TAG_FLAGS, commandPath);
     requirePositionals(parsed, [], commandPath);
     const nodeIdFlag = stringFlag(parsed, 'node-id');
@@ -195,22 +252,26 @@ async function runPrepareDeleteTag(argumentList) {
     const nodeId = nodeIdFlag === undefined ? undefined : parseFigmaNodeId(nodeIdFlag);
     assertTag(tag);
     const json = parsed.flags.json === true;
-    const { fileKey, context } = await resolvePlanInputs(parsed, commandPath);
+    const { fileKey, context, plan: planContext } = await resolvePlanInputs(parsed, commandPath, nodeId);
+    let plan;
     try {
-        const plan = planDeleteFigmaTag({ fileKey, nodeId, tag, force: parsed.flags.force === true }, context);
-        printPlan(plan, { fileKey, nodeId: plan.nodeId, tag: plan.tag, warnings: plan.warnings }, json);
+        plan = planDeleteFigmaTag({ fileKey, nodeId, tag, force: parsed.flags.force === true }, planContext);
     }
     catch (cause) {
-        if (!reportConflict(cause, json))
-            throw cause;
+        if (reportConflict(cause, json))
+            return;
+        throw cause;
     }
+    if (!(await writeAndReport(fileKey, plan.writes, plan.warnings, context, json)))
+        return;
+    printSuccess(`Removed tag "${plan.tag}" from "${plan.nodeName}" (${plan.nodeId}).`, plan.warnings, { fileKey, nodeId: plan.nodeId, tag: plan.tag }, json);
 }
 export async function runFigmaCommand(argumentList) {
     const [subcommand, ...rest] = argumentList;
     if (subcommand === undefined || subcommand === '--help') {
         console.log(FIGMA_HELP);
         if (subcommand === undefined) {
-            throw new CliUsageError('`fundus figma` needs a subcommand: prepare-set-tag, prepare-delete-tag.');
+            throw new CliUsageError('`fundus figma` needs a subcommand: set-tag, delete-tag.');
         }
         return;
     }
@@ -219,10 +280,10 @@ export async function runFigmaCommand(argumentList) {
         return;
     }
     switch (subcommand) {
-        case 'prepare-set-tag':
-            return runPrepareSetTag(rest);
-        case 'prepare-delete-tag':
-            return runPrepareDeleteTag(rest);
+        case 'set-tag':
+            return runSetTag(rest);
+        case 'delete-tag':
+            return runDeleteTag(rest);
         default:
             throw new CliUsageError(`Unknown subcommand "figma ${subcommand}" — run \`fundus figma --help\`.`);
     }

package/dist/server/figma-tags.d.ts

@@ -1,46 +1,80 @@
 /**
- * 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 { type Library } from '../core/index.js';
-import type { ResolvedFundusConfig } from './config-loader.js';
+import type { ImporterContext } from './importers/contract.js';
+import { type FigmaNodeSummary } from './importers/figma.js';
+/** A tag link on a node that exists. */
+export interface ConfirmedFigmaTag {
+    tag: string;
+    nodeId: string;
+    nodeName: string;
+    nodeType: string;
+    linkId: string;
+}
+export interface FigmaTagSnapshot {
+    /** Tag links on nodes that exist (orphaned links dropped). */
+    tags: ConfirmedFigmaTag[];
+    /** The requested node when it exists, tagged or not. */
+    target: FigmaNodeSummary | null;
+}
 /** A tagged node in the file, as reported alongside conflicts. */
 export interface FigmaTagListing {
     tag: string;
     nodeId: string;
     nodeName: string;
-    page: string;
 }
 /** An expected refusal that carries the file's current tags so the caller can pick another. */
 export declare class FigmaTagConflictError extends Error {
     readonly existingTags: FigmaTagListing[];
     constructor(message: string, existingTags: FigmaTagListing[]);
 }
-export interface FigmaTagPlan {
-    fileKey: string;
+interface FigmaTagWriteBase {
     nodeId: string;
-    /** Non-fatal findings the caller should relay (e.g. a Fundus asset to reimport). */
-    warnings: string[];
-    /** The `use_figma` script body. */
-    code: string;
+    nodeName: string;
+    tag: string;
 }
-export interface SetFigmaTagPlan extends FigmaTagPlan {
+/** One REST write; a delete names the link it removes. */
+export type FigmaTagWrite = (FigmaTagWriteBase & {
+    action: 'create';
+}) | (FigmaTagWriteBase & {
+    action: 'delete';
+    linkId: string;
+});
+export interface SetFigmaTagPlan {
+    fileKey: string;
+    nodeId: string;
+    nodeName: string;
     tag: string;
-    /** The node's tag per the REST snapshot; null when untagged or not yet visible. */
+    /** Another tag the node carried, else `tag` when it already carried it, else null. */
     previousTag: string | null;
+    /** Other nodes the tag is removed from. */
+    movedFrom: Array<{
+        nodeId: string;
+        nodeName: string;
+    }>;
+    /** Ordered: the create (if any) first, then deletes. */
+    writes: FigmaTagWrite[];
+    /** Non-fatal findings the caller should relay (e.g. a Fundus asset to reimport). */
+    warnings: string[];
 }
-export interface DeleteFigmaTagPlan extends FigmaTagPlan {
+export interface DeleteFigmaTagPlan {
+    fileKey: string;
+    nodeId: string;
+    nodeName: string;
     tag: string;
+    writes: FigmaTagWrite[];
+    warnings: string[];
 }
-/** 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 declare function parseFigmaNodeId(value: string): string;
 export interface FigmaTagPlanContext {
     library: Library;
-    /** REST document tree of the file, with shared plugin data. */
-    document: unknown;
+    snapshot: FigmaTagSnapshot;
 }
 export interface SetFigmaTagRequest {
     fileKey: string;
@@ -48,14 +82,28 @@ export interface SetFigmaTagRequest {
     tag: string;
     force: boolean;
 }
-export declare function planSetFigmaTag(request: SetFigmaTagRequest, { library, document }: FigmaTagPlanContext): SetFigmaTagPlan;
+export declare function planSetFigmaTag(request: SetFigmaTagRequest, { library, snapshot }: FigmaTagPlanContext): SetFigmaTagPlan;
 export interface DeleteFigmaTagRequest {
     fileKey: string;
-    /** Exactly one of nodeId / tag identifies the node; both must agree when given. */
+    /** At least one of nodeId / tag identifies the node; both must agree when given. */
     nodeId?: string;
     tag?: string;
     force: boolean;
 }
-export declare function planDeleteFigmaTag(request: DeleteFigmaTagRequest, { library, document }: FigmaTagPlanContext): DeleteFigmaTagPlan;
-/** Load the library and the file's REST document for planning. */
-export declare function loadFigmaTagPlanContext(config: ResolvedFundusConfig, fileKey: string): Promise<FigmaTagPlanContext>;
+export declare function planDeleteFigmaTag(request: DeleteFigmaTagRequest, { library, snapshot }: FigmaTagPlanContext): DeleteFigmaTagPlan;
+/**
+ * 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 declare function loadFigmaTagSnapshot(context: ImporterContext, fileKey: string, targetNodeId?: string): Promise<FigmaTagSnapshot>;
+/** Runs the writes in order and stops at the first failure; retries live in the REST client. */
+export declare function applyFigmaTagWrites(fileKey: string, writes: readonly FigmaTagWrite[], context: ImporterContext): Promise<{
+    written: FigmaTagWrite[];
+    failure: {
+        write: FigmaTagWrite;
+        message: string;
+    } | null;
+    notWritten: FigmaTagWrite[];
+}>;
+export {};