fundus 0.16.0 → 0.17.0

package/dist/server/library-store.d.ts

@@ -92,6 +92,15 @@ export declare class LibraryStore {
     replaceRawFileFromSource(id: string, options: ReplaceRawFromSourceOptions): Promise<Library>;
     /** CAS-protected replacement used only by a repeatable import source. */
     replaceRawFromImportSource(id: string, bytes: Uint8Array, expected: ImportSourceExpectation, nextSource?: ImportSourceRecord, updateParameters?: (parameters: unknown) => unknown): Promise<Library>;
+    /**
+     * CAS-protected raw swap for a Figma tag source that may also rename the
+     * asset. In tag mode the tag IS the id, so changing the tag moves the library
+     * key. The raw swap and the (optional) key move happen in ONE queued critical
+     * section and ONE `write`, so no inconsistent intermediate state is ever
+     * persisted; on any error the record and raw file are rolled back and the key
+     * move (in-memory only until `write`) is discarded.
+     */
+    repointTagAsset(oldId: string, newId: string, bytes: Uint8Array, expected: ImportSourceExpectation, nextSource?: ImportSourceRecord, updateParameters?: (parameters: unknown) => unknown): Promise<Library>;
     /** Replace an asset's parameters (validated by the owning plugin). */
     updateParameters(id: string, parameters: unknown): Promise<Library>;
     /** Replace an asset's manifest membership (every name must exist). */

package/dist/server/library-store.js

@@ -348,6 +348,85 @@ export class LibraryStore {
             return library;
         });
     }
+    /**
+     * CAS-protected raw swap for a Figma tag source that may also rename the
+     * asset. In tag mode the tag IS the id, so changing the tag moves the library
+     * key. The raw swap and the (optional) key move happen in ONE queued critical
+     * section and ONE `write`, so no inconsistent intermediate state is ever
+     * persisted; on any error the record and raw file are rolled back and the key
+     * move (in-memory only until `write`) is discarded.
+     */
+    async repointTagAsset(oldId, newId, bytes, expected, nextSource, updateParameters) {
+        return this.#enqueue(async () => {
+            const library = await this.read();
+            const record = this.#requireAsset(library, oldId);
+            if (record.raw !== expected.raw ||
+                record.rawHash !== expected.rawHash ||
+                record.type !== expected.type ||
+                !record.importSource ||
+                canonicalizeParameters(record.importSource) !== expected.canonicalSource) {
+                throw new Error('stale-import');
+            }
+            const renamed = newId !== oldId;
+            if (renamed && Object.hasOwn(library.assets, newId)) {
+                throw new Error(`An asset with id "${newId}" already exists.`);
+            }
+            const absolutePath = join(this.#config.rawDir, record.raw);
+            const { verifyStableRawFile } = await import('./raw-reconciliation.js');
+            try {
+                await verifyStableRawFile(absolutePath, expected.rawHash);
+            }
+            catch {
+                throw new Error('stale-import');
+            }
+            const token = crypto.randomUUID();
+            const temporaryPath = `${absolutePath}.fundus-retag-${token}.tmp`;
+            const backupPath = `${absolutePath}.fundus-retag-${token}`;
+            const previousHash = record.rawHash;
+            const previousSource = structuredClone(record.importSource);
+            const previousParameters = structuredClone(record.parameters);
+            let staged = false;
+            let installed = false;
+            try {
+                await writeFile(temporaryPath, bytes);
+                await rename(absolutePath, backupPath);
+                staged = true;
+                await rename(temporaryPath, absolutePath);
+                installed = true;
+                record.rawHash = sha256Hex(bytes);
+                if (nextSource)
+                    record.importSource = structuredClone(nextSource);
+                if (updateParameters)
+                    record.parameters = updateParameters(record.parameters);
+                if (renamed) {
+                    delete library.assets[oldId];
+                    library.assets[newId] = record;
+                }
+                await this.write(library);
+            }
+            catch (cause) {
+                record.rawHash = previousHash;
+                record.importSource = previousSource;
+                record.parameters = previousParameters;
+                if (renamed) {
+                    delete library.assets[newId];
+                    library.assets[oldId] = record;
+                }
+                if (installed)
+                    await unlink(absolutePath).catch(() => { });
+                if (staged)
+                    await rename(backupPath, absolutePath);
+                await unlink(temporaryPath).catch(() => { });
+                throw cause;
+            }
+            if (staged)
+                await unlink(backupPath).catch(() => { });
+            // The old id's proxies are orphans after a rename (pruning also covers it).
+            if (renamed)
+                await this.#deleteProxiesOf(oldId);
+            return library;
+        });
+    }
     /** Replace an asset's parameters (validated by the owning plugin). */
     async updateParameters(id, parameters) {
         return this.#enqueue(() => this.#updateParameters(id, parameters));

package/dist/server/operations.d.ts

@@ -66,6 +66,18 @@ export declare class FundusOperations {
     reimportAsset(id: string, input?: unknown): Promise<FundusStateDto>;
     /** Materialize a new source, then atomically replace an existing asset's raw file. */
     replaceRawFromSource(id: string, options: ReplaceRawFromSourceOptions): Promise<FundusStateDto>;
+    /**
+     * Edit a Figma tag asset's tag, fileKey, and/or scale in place. Because in tag
+     * mode the tag IS the asset id, changing the tag renames the asset (moves the
+     * library key); changing only fileKey/scale is an in-place re-point. Mirrors
+     * `reimportAsset`'s three phases: preflight in the queue, materialize outside
+     * it, then commit atomically through `store.repointTagAsset`.
+     */
+    retagFigmaAsset(id: string, input: {
+        tag?: string;
+        fileKey?: string;
+        scale?: 1 | 2 | 3 | 4;
+    }): Promise<FundusStateDto>;
     /** Apply a PATCH body: parameters and/or manifests and/or a rename — in that order. */
     patchAsset(id: string, body: PatchAssetRequestDto): Promise<FundusStateDto>;
     moveAsset(id: string, folder: string): Promise<FundusStateDto>;

package/dist/server/operations.js

@@ -53,6 +53,18 @@ function figmaSlicePixelRatio(raw, type) {
         return undefined;
     return validateFigmaSourceParameters(raw.importSource.parameters).scale;
 }
+/**
+ * The Fundus tag of a Figma tag-mode import source, else null. In tag mode the
+ * tag IS the asset id, so this is the single seam that ties provenance to
+ * identity — used to assert id equality on import/reimport and to forbid
+ * renaming a tag-referenced asset. Only Figma sources are inspected.
+ */
+function figmaTagOf(importSource) {
+    if (importSource?.importer !== 'figma')
+        return null;
+    const params = validateFigmaSourceParameters(importSource.parameters);
+    return params.mode === 'tag' ? params.fundusTag : null;
+}
 export class FundusOperations {
     #config;
     #registry;
@@ -359,6 +371,10 @@ export class FundusOperations {
         });
         return this.#enqueueOperation(async () => {
             this.#validateImportedRaw(raw, options.importer);
+            const tag = figmaTagOf(raw.importSource);
+            if (tag !== null && tag !== options.id) {
+                throw new SourceImportError('invalid-input', `A Figma tag import must use its tag as the asset id: the tag is "${tag}", not "${options.id}".`);
+            }
             return this.#createImportedAsset(raw, options);
         });
     }
@@ -399,6 +415,10 @@ export class FundusOperations {
         }
         return this.#enqueueOperation(async () => {
             this.#validateImportedRaw(raw, snapshot.importer.kind);
+            const tag = figmaTagOf(raw.importSource);
+            if (tag !== null && tag !== id) {
+                throw new SourceImportError('invalid-input', `A Figma tag reimport may not retarget asset "${id}" to a different tag "${tag}".`);
+            }
             const plugin = serverPluginForType(snapshot.expected.type, this.#registry);
             if (!plugin.descriptor.accepts.includes(raw.extension)) {
                 throw new SourceImportError('invalid-response', `The ${snapshot.expected.type} type does not accept ".${raw.extension}" files.`);
@@ -458,6 +478,10 @@ export class FundusOperations {
         const importSource = raw.importSource;
         return this.#enqueueOperation(async () => {
             this.#validateImportedRaw(raw, preflight.importer.kind);
+            const tag = figmaTagOf(importSource);
+            if (tag !== null && tag !== id) {
+                throw new SourceImportError('invalid-input', `A Figma tag replacement must use its own tag as the asset id: the tag is "${tag}", not "${id}".`);
+            }
             const plugin = serverPluginForType(preflight.expected.type, this.#registry);
             if (!plugin.descriptor.accepts.includes(raw.extension)) {
                 throw new SourceImportError('invalid-response', `The ${preflight.expected.type} type does not accept ".${raw.extension}" files.`);
@@ -486,6 +510,92 @@ export class FundusOperations {
             }
         });
     }
+    /**
+     * Edit a Figma tag asset's tag, fileKey, and/or scale in place. Because in tag
+     * mode the tag IS the asset id, changing the tag renames the asset (moves the
+     * library key); changing only fileKey/scale is an in-place re-point. Mirrors
+     * `reimportAsset`'s three phases: preflight in the queue, materialize outside
+     * it, then commit atomically through `store.repointTagAsset`.
+     */
+    async retagFigmaAsset(id, input) {
+        const snapshot = await this.#enqueueOperation(async () => {
+            const library = await this.#store.read();
+            this.#requireAsset(library, id);
+            const record = library.assets[id];
+            const currentTag = figmaTagOf(record.importSource);
+            if (currentTag === null || !record.importSource) {
+                throw new SourceImportError('invalid-input', `Asset "${id}" is not a Figma tag import.`);
+            }
+            const current = validateFigmaSourceParameters(record.importSource.parameters);
+            const newTag = input.tag ?? currentTag;
+            const fileKey = input.fileKey ?? current.fileKey;
+            const scale = input.scale ?? current.scale;
+            if (newTag !== id) {
+                const problem = assetIdError(newTag);
+                if (problem)
+                    throw new SourceImportError('invalid-input', problem);
+                if (Object.hasOwn(library.assets, newTag)) {
+                    throw new SourceImportError('invalid-input', `An asset with id "${newTag}" already exists.`);
+                }
+                // A tag change renames the asset; reject one that would dangle references.
+                const candidate = structuredClone(library);
+                candidate.assets[newTag] = candidate.assets[id];
+                delete candidate.assets[id];
+                await this.#assertNoIntroducedIssues(library, candidate);
+            }
+            try {
+                await verifyStableRawFile(join(this.#config.rawDir, record.raw), record.rawHash);
+            }
+            catch {
+                throw new SourceImportError('stale-import', 'The local raw file changed. Apply or discard that edit before retagging.');
+            }
+            const importer = this.#importers.require('figma');
+            return {
+                importer,
+                input: importer.validateInput({ mode: 'tag', tag: newTag, fileKey, scale, format: 'png' }),
+                newTag,
+                expected: {
+                    raw: record.raw,
+                    rawHash: record.rawHash,
+                    type: record.type,
+                    canonicalSource: canonicalizeParameters(record.importSource)
+                }
+            };
+        });
+        const raw = await snapshot.importer.importRaw(snapshot.input, {
+            config: this.#config,
+            fetch: globalThis.fetch
+        });
+        if (!raw.importSource) {
+            throw new SourceImportError('invalid-response', 'The Figma importer did not return provenance for the retagged source.');
+        }
+        const importSource = raw.importSource;
+        return this.#enqueueOperation(async () => {
+            this.#validateImportedRaw(raw, snapshot.importer.kind);
+            if (figmaTagOf(importSource) !== snapshot.newTag) {
+                throw new SourceImportError('invalid-response', `The Figma importer resolved a different tag than "${snapshot.newTag}".`);
+            }
+            const plugin = serverPluginForType(snapshot.expected.type, this.#registry);
+            if (!plugin.descriptor.accepts.includes(raw.extension)) {
+                throw new SourceImportError('invalid-response', `The ${snapshot.expected.type} type does not accept ".${raw.extension}" files.`);
+            }
+            // A retag may change the export scale, so always sync a slice's pixel ratio.
+            const pixelRatio = figmaSlicePixelRatio(raw, snapshot.expected.type);
+            let library;
+            try {
+                library = await this.#store.repointTagAsset(id, snapshot.newTag, raw.bytes, snapshot.expected, importSource, pixelRatio === undefined
+                    ? undefined
+                    : (parameters) => plugin.descriptor.validateParameters(mergeParameterPatch(parameters, { pixelRatio })));
+            }
+            catch (cause) {
+                if (cause instanceof Error && cause.message === 'stale-import') {
+                    throw new SourceImportError('stale-import', 'The asset or local raw file changed while Figma was exporting. Nothing was changed.');
+                }
+                throw cause;
+            }
+            return this.#afterMutation(library);
+        });
+    }
     async #createImportedAsset(raw, options) {
         this.#validateImportedRaw(raw);
         const fileName = raw.suggestedFileName ?? `${options.id}.${raw.extension}`;
@@ -723,6 +833,9 @@ export class FundusOperations {
     async #renameAsset(id, newId) {
         const library = await this.#store.read();
         this.#requireAsset(library, id);
+        if (figmaTagOf(library.assets[id].importSource) !== null) {
+            throw new SourceImportError('invalid-input', 'This asset is referenced by a Figma tag and cannot be renamed; re-import with a new tag instead.');
+        }
         // A collision or invalid new id is the store's own (clearer) error; the
         // candidate check covers what the store cannot see: broken references.
         if (newId !== id && !Object.hasOwn(library.assets, newId)) {
@@ -986,7 +1099,14 @@ export class FundusOperations {
             gitBranch,
             library,
             assets,
-            importDefaults: { figma: { scale: this.#config.import.figma.defaults.scale } },
+            importDefaults: {
+                figma: {
+                    scale: this.#config.import.figma.defaults.scale,
+                    ...(this.#config.import.figma.defaultFileKey !== undefined
+                        ? { defaultFileKey: this.#config.import.figma.defaultFileKey }
+                        : {})
+                }
+            },
             issues,
             presetNames,
             presetCapabilities,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "fundus",
-	"version": "0.16.0",
+	"version": "0.17.0",
 	"type": "module",
 	"repository": {
 		"type": "git",