fundus 0.25.0 → 0.26.0

package/dist/core/figma-tag-script.js

@@ -0,0 +1,236 @@
+/**
+ * Plugin-API code that reads and writes Fundus tags inside a Figma document.
+ * Two runtimes execute it: the Fundus Figma plugin imports these functions
+ * directly, and the CLI serializes them (via `Function.prototype.toString`)
+ * into a script an agent runs through Figma's MCP `use_figma` tool. The Figma
+ * REST API cannot write plugin data, so a script is the only headless write
+ * path.
+ *
+ * Serialization constrains every function listed in `SCRIPT_FUNCTIONS`: it
+ * may reference only its parameters, the other listed functions, and the
+ * constants in `SCRIPT_CONSTANTS` — never imports or other module scope. The
+ * `figma` global is passed in as a parameter so tests can drive the same code
+ * against a fake document.
+ */
+/** Shared-plugin-data namespace; the REST API returns it under `sharedPluginData`. */
+export const FIGMA_TAG_NAMESPACE = 'fundus';
+/** Key holding the node's Fundus asset id (the tag). */
+export const FIGMA_TAG_KEY = 'assetId';
+/**
+ * Key holding the exact label of the annotation Fundus owns on the node; empty
+ * when it owns none. Tracking ownership out-of-band keeps the visible label
+ * exactly equal to the tag and leaves the user's own annotations untouched.
+ */
+export const FIGMA_ANNOTATION_LABEL_KEY = 'annotationLabel';
+/**
+ * Visible prefix earlier plugin builds used as the ownership marker. Still
+ * recognized so those annotations are migrated or stripped instead of
+ * duplicated.
+ */
+export const LEGACY_ANNOTATION_PREFIX = 'Fundus asset: ';
+/**
+ * Whether the id names a node inside an instance (`I<instance>;<source>`).
+ * Such nodes inherit the shared plugin data of the main component's node, so
+ * they report its tag without being a separate taggable node.
+ */
+export function isInstanceSublayerId(id) {
+    return id.startsWith('I');
+}
+export function supportsAnnotations(node) {
+    return 'annotations' in node;
+}
+/**
+ * The annotation's shown text. Figma reports a plain-label annotation with
+ * `labelMarkdown: ""`, so an empty markdown field falls back to `label`.
+ */
+export function annotationText(annotation) {
+    return annotation.labelMarkdown || annotation.label || '';
+}
+/**
+ * Figma returns BOTH `label` and `labelMarkdown` when reading annotations, but
+ * the setter rejects an annotation that carries both. Re-emit a single-field
+ * copy (non-empty markdown first), preserving `properties`/`categoryId`, so
+ * preserved annotations can be written back without failing validation.
+ */
+export function writableAnnotation(annotation) {
+    const copy = {};
+    if (annotation.labelMarkdown)
+        copy.labelMarkdown = annotation.labelMarkdown;
+    else if (annotation.label !== undefined)
+        copy.label = annotation.label;
+    if (annotation.properties)
+        copy.properties = annotation.properties;
+    if (annotation.categoryId)
+        copy.categoryId = annotation.categoryId;
+    return copy;
+}
+/** Whether this annotation is one Fundus owns — by the stored label or the legacy prefix. */
+export function isFundusAnnotation(annotation, ownedLabel) {
+    const text = annotationText(annotation);
+    return (ownedLabel !== '' && text === ownedLabel) || text.startsWith(LEGACY_ANNOTATION_PREFIX);
+}
+/**
+ * Ensure the node carries exactly one Fundus annotation whose label is the tag,
+ * preserving all others. Writes only when not already in sync, so a steady
+ * state neither dirties the file nor adds undo steps.
+ */
+export function writeFundusAnnotation(node, tag) {
+    const owned = node.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY);
+    const current = node.annotations;
+    const ours = current.filter((annotation) => isFundusAnnotation(annotation, owned));
+    const inSync = owned === tag && ours.length === 1 && annotationText(ours[0]) === tag;
+    if (inSync)
+        return;
+    const kept = current
+        .filter((annotation) => !isFundusAnnotation(annotation, owned) && annotationText(annotation) !== tag)
+        .map(writableAnnotation);
+    node.annotations = [...kept, { label: tag }];
+    if (owned !== tag) {
+        node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY, tag);
+    }
+}
+/** Remove the Fundus annotation (incl. legacy), preserving all others. */
+export function stripFundusAnnotation(node) {
+    const owned = node.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY);
+    const current = node.annotations;
+    const kept = current
+        .filter((annotation) => !isFundusAnnotation(annotation, owned))
+        .map(writableAnnotation);
+    if (kept.length !== current.length)
+        node.annotations = kept;
+    if (owned !== '')
+        node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY, '');
+}
+export function pageOfNode(node) {
+    let current = node;
+    while (current && current.type !== 'PAGE')
+        current = current.parent;
+    return current ? current : null;
+}
+/**
+ * Resolve a scene node and load its page. `loadAsync` loads without
+ * navigating, so running a script never moves anyone's canvas.
+ */
+export async function loadTaggableNode(figma, nodeId) {
+    const node = await figma.getNodeByIdAsync(nodeId);
+    const page = node ? pageOfNode(node) : null;
+    if (!node || !page || node.type === 'PAGE') {
+        throw new Error(`Figma node "${nodeId}" does not exist in this file.`);
+    }
+    await page.loadAsync();
+    return node;
+}
+/**
+ * The first other node carrying `tag`, across every page. Scripts start with
+ * only the first page loaded, and `findAll` on an unloaded page silently
+ * misses content, so each page is loaded first.
+ */
+export async function findTagHolder(figma, tag, exceptNodeId) {
+    for (const page of figma.root.children) {
+        await page.loadAsync();
+        const [holder] = page.findAll((candidate) => candidate.id !== exceptNodeId &&
+            !isInstanceSublayerId(candidate.id) &&
+            candidate.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY) === tag);
+        if (holder)
+            return { node: holder, page };
+    }
+    return null;
+}
+/**
+ * Tag a node, re-checking the live document right before writing: the CLI's
+ * REST snapshot can lag behind edits made since it ran.
+ */
+export async function setFundusTag(figma, input) {
+    const node = await loadTaggableNode(figma, input.nodeId);
+    const previous = node.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY);
+    if (!input.force && previous === input.tag) {
+        throw new Error(`Node "${node.name}" (${node.id}) already carries tag "${input.tag}"; rerun prepare-set-tag with --force to rewrite it.`);
+    }
+    if (!input.force && previous !== '') {
+        throw new Error(`Node "${node.name}" (${node.id}) already carries tag "${previous}"; rerun prepare-set-tag with --force to replace it.`);
+    }
+    const holder = await findTagHolder(figma, input.tag, node.id);
+    if (holder) {
+        throw new Error(`Tag "${input.tag}" is already used by "${holder.node.name}" (${holder.node.id}) on page "${holder.page.name}"; choose another tag.`);
+    }
+    node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY, input.tag);
+    const annotated = supportsAnnotations(node);
+    if (annotated)
+        writeFundusAnnotation(node, input.tag);
+    return {
+        ok: true,
+        nodeId: node.id,
+        nodeName: node.name,
+        tag: input.tag,
+        previousTag: previous === '' ? null : previous,
+        annotated
+    };
+}
+export async function deleteFundusTag(figma, input) {
+    const node = await loadTaggableNode(figma, input.nodeId);
+    const current = node.getSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY);
+    if (current !== input.tag) {
+        throw new Error(current === ''
+            ? `Node "${node.name}" (${node.id}) carries no Fundus tag.`
+            : `Node "${node.name}" (${node.id}) carries tag "${current}", not "${input.tag}"; rerun prepare-delete-tag.`);
+    }
+    node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_TAG_KEY, '');
+    let annotationRemoved = false;
+    if (supportsAnnotations(node)) {
+        const before = node.annotations.length;
+        stripFundusAnnotation(node);
+        annotationRemoved = node.annotations.length < before;
+    }
+    else {
+        node.setSharedPluginData(FIGMA_TAG_NAMESPACE, FIGMA_ANNOTATION_LABEL_KEY, '');
+    }
+    return {
+        ok: true,
+        nodeId: node.id,
+        nodeName: node.name,
+        removedTag: input.tag,
+        annotationRemoved
+    };
+}
+const SCRIPT_CONSTANTS = {
+    FIGMA_TAG_NAMESPACE,
+    FIGMA_TAG_KEY,
+    FIGMA_ANNOTATION_LABEL_KEY,
+    LEGACY_ANNOTATION_PREFIX
+};
+const SCRIPT_FUNCTIONS = [
+    isInstanceSublayerId,
+    supportsAnnotations,
+    annotationText,
+    writableAnnotation,
+    isFundusAnnotation,
+    writeFundusAnnotation,
+    stripFundusAnnotation,
+    pageOfNode,
+    loadTaggableNode,
+    findTagHolder,
+    setFundusTag,
+    deleteFundusTag
+];
+/**
+ * A self-contained `use_figma` script body: top-level `await` and `return`,
+ * with the `figma` global in scope. It returns the operation's JSON result
+ * and throws, before mutating anything, when the live document disagrees.
+ */
+function buildScript(summary, call) {
+    const constants = Object.entries(SCRIPT_CONSTANTS).map(([name, value]) => `const ${name} = ${JSON.stringify(value)};`);
+    return [
+        `// ${summary}`,
+        '// Generated by the fundus CLI — run it unchanged with the Figma MCP `use_figma` tool.',
+        ...constants,
+        ...SCRIPT_FUNCTIONS.map(String),
+        `return await ${call};`,
+        ''
+    ].join('\n\n');
+}
+export function buildSetTagScript(input) {
+    return buildScript(`Set Fundus tag ${JSON.stringify(input.tag)} on Figma node ${JSON.stringify(input.nodeId)}.`, `setFundusTag(figma, ${JSON.stringify(input)})`);
+}
+export function buildDeleteTagScript(input) {
+    return buildScript(`Delete Fundus tag ${JSON.stringify(input.tag)} from Figma node ${JSON.stringify(input.nodeId)}.`, `deleteFundusTag(figma, ${JSON.stringify(input)})`);
+}

package/dist/core/index.d.ts

@@ -3,6 +3,8 @@ export { createEmptyLibrary, parseLibrary, serializeLibrary } from './library.js
 export { rawFileNameError, rawFilePathError, portableRawPathKey, isFundusTransactionName } from './raw-path.js';
 export { ROOT_FOLDER, FOLDER_SENTINEL, folderNameError, folderPathError, normalizeFolderPath, portableFolderPathKey, parentFolderPath, folderNameOf, joinFolderPath, folderOfRawPath, rawFileNameOfPath, isFolderOrDescendant, replaceFolderPrefix } from './folder-path.js';
 export { RESERVED_ASSET_IDS, isValidAssetId, assetIdError, manifestNameError } from './asset-id.js';
+export type { SetFigmaTagInput, SetFigmaTagResult, DeleteFigmaTagInput, DeleteFigmaTagResult } from './figma-tag-script.js';
+export { buildSetTagScript, buildDeleteTagScript, isInstanceSublayerId } from './figma-tag-script.js';
 export type { ManifestColor } from './manifest-appearance.js';
 export { MANIFEST_COLORS, MANIFEST_EMOJIS, isManifestColor, isManifestEmoji, resolveManifestColor, manifestColorError, manifestEmojiError } from './manifest-appearance.js';
 export { acceptedExtensions, acceptedExtensionsForType, typesForFileName, proposeAssetId } from './ingest.js';

package/dist/core/index.js

@@ -2,6 +2,7 @@ export { createEmptyLibrary, parseLibrary, serializeLibrary } from './library.js
 export { rawFileNameError, rawFilePathError, portableRawPathKey, isFundusTransactionName } from './raw-path.js';
 export { ROOT_FOLDER, FOLDER_SENTINEL, folderNameError, folderPathError, normalizeFolderPath, portableFolderPathKey, parentFolderPath, folderNameOf, joinFolderPath, folderOfRawPath, rawFileNameOfPath, isFolderOrDescendant, replaceFolderPrefix } from './folder-path.js';
 export { RESERVED_ASSET_IDS, isValidAssetId, assetIdError, manifestNameError } from './asset-id.js';
+export { buildSetTagScript, buildDeleteTagScript, isInstanceSublayerId } from './figma-tag-script.js';
 export { MANIFEST_COLORS, MANIFEST_EMOJIS, isManifestColor, isManifestEmoji, resolveManifestColor, manifestColorError, manifestEmojiError } from './manifest-appearance.js';
 export { acceptedExtensions, acceptedExtensionsForType, typesForFileName, proposeAssetId } from './ingest.js';
 export { canonicalizeParameters, compareCodeUnits } from './canonicalize.js';

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

@@ -12,6 +12,12 @@ export declare const ASSET_SET_HELP = "fundus asset set \u2014 update an asset's
 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";
 export declare const ASSET_DELETE_HELP = "fundus asset delete \u2014 delete an asset\n\nUsage: fundus asset delete <id> [--json]\n\nDeletes the library record, its raw file, and its proxies, then\nregenerates the affected manifest modules. Fails if another asset\nreferences it \u2014 remove the references first.\n\nFlags:\n  --json   print {\"ok\": true, \"deletedAssetId\": \"<id>\", \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset delete obsoleteBanner --json\n";
 export declare const ASSET_MOVE_HELP = "fundus asset move \u2014 move an asset between folders\n\nUsage: fundus asset move <id> <folder|root> [--json]\n\nMoves the raw file and its current proxy without changing the stable asset id,\nthen runs the autosave chain. The destination folder must already exist; use\nthe literal \"root\" for the implicit root.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset move navigationPanel \"UI/Buttons\" --json\n";
+/**
+ * `--figma-file` accepts either a raw Figma file key or a full design/file link.
+ * A value that parses as a URL is treated as a link (fileKey extracted via
+ * `parseFigmaFileKey`); anything else is passed through as a raw key.
+ */
+export declare function resolveFigmaFileKeyFlag(value: string): string;
 export declare function runAssetCommand(argumentList: string[]): Promise<void>;
 export declare const FOLDER_HELP = "fundus folder \u2014 manage the mirrored raw/proxy folder tree\n\nUsage: fundus folder <subcommand> \u2026\n\nSubcommands:\n  list      list registered folders and their direct assets\n  create    create a persisted folder (fundus folder create <path>)\n  rename    rename one folder segment and its subtree\n  move      move a complete folder subtree below another folder\n  delete    recursively delete a folder subtree and its assets\n\nAll mutations update rawDir and proxyDir together, maintain .gitkeep files,\nand run the full autosave chain. All subcommands accept --json and --help.\n";
 export declare function runFolderCommand(argumentList: string[]): Promise<void>;

package/dist/server/cli-commands.js

@@ -898,7 +898,7 @@ function parseFigmaScale(value, commandPath) {
  * A value that parses as a URL is treated as a link (fileKey extracted via
  * `parseFigmaFileKey`); anything else is passed through as a raw key.
  */
-function resolveFigmaFileKeyFlag(value) {
+export function resolveFigmaFileKeyFlag(value) {
     try {
         new URL(value);
     }

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

@@ -0,0 +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 function runFigmaCommand(argumentList: string[]): Promise<void>;

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

@@ -0,0 +1,222 @@
+/**
+ * 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.
+ */
+import { assetIdError } from '../core/index.js';
+import { loadConfig } from './config-loader.js';
+import { FigmaTagConflictError, loadFigmaTagPlanContext, parseFigmaNodeId, planDeleteFigmaTag, planSetFigmaTag } from './figma-tags.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
+
+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.
+
+Subcommands:
+  prepare-set-tag       tag a node (--node-id, --tag)
+  prepare-delete-tag    remove a node's tag (--tag or --node-id)
+
+Requires import.figma.token in fundus.config.ts.
+`;
+const PREPARE_SET_TAG_HELP = `fundus figma prepare-set-tag — prepare a use_figma script that tags a node
+
+Usage: fundus figma prepare-set-tag --node-id <id> --tag <tag>
+                                    [--file <key|link>] [--force] [--json]
+
+Refuses, listing the file's existing tags, when another node already carries
+the tag or a Fundus asset with that id exists from another source. Refuses
+when the node already carries a tag (the same one or another) unless --force.
+
+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)
+  --file <key|link>   Figma file key or link; default:
+                      import.figma.defaultFileKey from fundus.config.ts
+  --force             replace the node's current tag, or rewrite the same tag
+  --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
+  --help              this help
+
+Without --json the script goes to stdout, everything else to stderr.
+The script returns {"ok": true, "nodeId", "nodeName", "tag", "previousTag",
+"annotated"}. Afterwards: \`fundus asset ingest --from figma --figma-tag <tag>\`.
+
+Example:
+  fundus figma prepare-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
+
+Usage: fundus figma prepare-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).
+
+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
+  --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
+  --help              this help
+
+The script returns {"ok": true, "nodeId", "nodeName", "removedTag",
+"annotationRemoved"}.
+
+Example:
+  fundus figma prepare-delete-tag --tag navigationPanel --json
+`;
+const FIGMA_SUBCOMMAND_HELP = {
+    'prepare-set-tag': PREPARE_SET_TAG_HELP,
+    'prepare-delete-tag': PREPARE_DELETE_TAG_HELP
+};
+const TAG_FLAGS = {
+    json: { takesValue: false },
+    help: { takesValue: false },
+    file: { takesValue: true },
+    'node-id': { takesValue: true },
+    tag: { takesValue: true },
+    force: { takesValue: false }
+};
+/** Fail on a malformed tag before any Figma request. */
+function assertTag(tag) {
+    const problem = tag === undefined ? null : assetIdError(tag);
+    if (problem)
+        throw new Error(problem);
+}
+function stringFlag(parsed, name) {
+    const value = parsed.flags[name];
+    return typeof value === 'string' ? value : undefined;
+}
+async function resolvePlanInputs(parsed, commandPath) {
+    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.`;
+}
+/** Refusals that list the file's tags get their own document; others take the standard error path. */
+function reportConflict(cause, json) {
+    if (!(cause instanceof FigmaTagConflictError))
+        return false;
+    if (json) {
+        printJsonDocument({
+            ok: false,
+            error: { message: cause.message },
+            existingTags: cause.existingTags
+        });
+    }
+    else {
+        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}")`);
+        }
+    }
+    process.exitCode = 1;
+    return true;
+}
+function printPlan(plan, document, json) {
+    if (json) {
+        printJsonDocument({ ok: true, ...document, next: nextStep(plan.fileKey), code: plan.code });
+        return;
+    }
+    for (const warning of plan.warnings)
+        console.error(`⚠ ${warning}`);
+    console.error(`${nextStep(plan.fileKey, 'the script below')}\n`);
+    process.stdout.write(plan.code);
+}
+async function runPrepareSetTag(argumentList) {
+    const commandPath = 'fundus figma prepare-set-tag';
+    const parsed = parseArguments(argumentList, TAG_FLAGS, commandPath);
+    requirePositionals(parsed, [], commandPath);
+    const nodeIdFlag = stringFlag(parsed, 'node-id');
+    const tag = stringFlag(parsed, 'tag');
+    if (nodeIdFlag === undefined || tag === undefined) {
+        throw new CliUsageError(`\`${commandPath}\` needs --node-id and --tag — run \`${commandPath} --help\`.`);
+    }
+    const nodeId = parseFigmaNodeId(nodeIdFlag);
+    assertTag(tag);
+    const json = parsed.flags.json === true;
+    const { fileKey, context } = await resolvePlanInputs(parsed, commandPath);
+    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);
+    }
+    catch (cause) {
+        if (!reportConflict(cause, json))
+            throw cause;
+    }
+}
+async function runPrepareDeleteTag(argumentList) {
+    const commandPath = 'fundus figma prepare-delete-tag';
+    const parsed = parseArguments(argumentList, TAG_FLAGS, commandPath);
+    requirePositionals(parsed, [], commandPath);
+    const nodeIdFlag = stringFlag(parsed, 'node-id');
+    const tag = stringFlag(parsed, 'tag');
+    if (nodeIdFlag === undefined && tag === undefined) {
+        throw new CliUsageError(`\`${commandPath}\` needs --tag or --node-id — run \`${commandPath} --help\`.`);
+    }
+    const nodeId = nodeIdFlag === undefined ? undefined : parseFigmaNodeId(nodeIdFlag);
+    assertTag(tag);
+    const json = parsed.flags.json === true;
+    const { fileKey, context } = await resolvePlanInputs(parsed, commandPath);
+    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);
+    }
+    catch (cause) {
+        if (!reportConflict(cause, json))
+            throw cause;
+    }
+}
+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.');
+        }
+        return;
+    }
+    if (rest.includes('--help')) {
+        console.log(FIGMA_SUBCOMMAND_HELP[subcommand] ?? FIGMA_HELP);
+        return;
+    }
+    switch (subcommand) {
+        case 'prepare-set-tag':
+            return runPrepareSetTag(rest);
+        case 'prepare-delete-tag':
+            return runPrepareDeleteTag(rest);
+        default:
+            throw new CliUsageError(`Unknown subcommand "figma ${subcommand}" — run \`fundus figma --help\`.`);
+    }
+}

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

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+import { type Library } from '../core/index.js';
+import type { ResolvedFundusConfig } from './config-loader.js';
+/** 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;
+    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;
+}
+export interface SetFigmaTagPlan extends FigmaTagPlan {
+    tag: string;
+    /** The node's tag per the REST snapshot; null when untagged or not yet visible. */
+    previousTag: string | null;
+}
+export interface DeleteFigmaTagPlan extends FigmaTagPlan {
+    tag: string;
+}
+/** Normalize a `12:34` / `12-34` node id; Fundus imports 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;
+}
+export interface SetFigmaTagRequest {
+    fileKey: string;
+    nodeId: string;
+    tag: string;
+    force: boolean;
+}
+export declare function planSetFigmaTag(request: SetFigmaTagRequest, { library, document }: FigmaTagPlanContext): SetFigmaTagPlan;
+export interface DeleteFigmaTagRequest {
+    fileKey: string;
+    /** Exactly 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>;