fundus 0.15.0 → 0.17.0

package/dist/server/config-loader.js

@@ -3,9 +3,13 @@
  * the shape, resolves all paths to
  * absolute, and merges the built-in plugin preset defaults under the host's.
  */
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { createJiti } from 'jiti';
+import { parsePackageDeclaration, validatePackageDeclaration } from '../core/index.js';
 import { serverPluginsByType } from './plugins.js';
 import { isRecord } from './plugins/config.js';
 export const USAGE_NOT_CONFIGURED_MESSAGE = 'Usage analysis is not configured; add usage.referenceProvider and usage.openLocation to fundus.config.ts.';
@@ -32,6 +36,88 @@ function configDefinitionsFor(registry) {
     }
     return [...byNamespace.values()];
 }
+/**
+ * A string `packages` entry is a *path* when it looks like one (starts with
+ * `.`/`/`, is absolute, or ends `.json`), or a bare relative path with a
+ * separator; otherwise it is a package *name*. A scoped name (`@scope/pkg`)
+ * contains a `/` but is a name.
+ */
+function classifyPackageSpec(spec) {
+    if (spec.startsWith('.') || spec.startsWith('/') || isAbsolute(spec))
+        return 'path';
+    if (DECLARATION_FILE_RE.test(spec))
+        return 'path';
+    if (spec.startsWith('@'))
+        return 'name';
+    if (spec.includes('/') || spec.includes('\\'))
+        return 'path';
+    return 'name';
+}
+/** A declaration file is JSON or a JS/TS module (the latter loaded via jiti). */
+const DECLARATION_FILE_RE = /\.(json|[mc]?[jt]s)$/;
+/**
+ * Read a package declaration from its resolved file: a JSON `fundus.package.json`
+ * (parsed as text) or a JS/TS module (`fundus.package.ts`) whose default export is
+ * the declaration — loaded through the same jiti path as `fundus.config.ts`, which
+ * keeps the resource `type`s literal for the package's `PackageAssets<…>` derivation.
+ */
+async function loadPackageDeclaration(file, origin) {
+    if (/\.[mc]?[jt]s$/.test(file)) {
+        let module;
+        try {
+            const jiti = createJiti(import.meta.url, { interopDefault: false });
+            module = await jiti.import(file);
+        }
+        catch (cause) {
+            throw new Error(`Cannot load fundus package "${origin}" (${file}): ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        const value = isRecord(module) && 'default' in module ? module.default : module;
+        return validatePackageDeclaration(value, origin);
+    }
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (cause) {
+        throw new Error(`Cannot read fundus package "${origin}" (${file}): ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    return parsePackageDeclaration(text, origin);
+}
+function normalizePackageSource(projectRoot, entry) {
+    let spec;
+    let rawDirOverride;
+    if (typeof entry === 'string') {
+        spec = entry;
+    }
+    else if (isRecord(entry) && typeof entry.package === 'string' && entry.package.length > 0) {
+        spec = entry.package;
+        if (entry.rawDir !== undefined) {
+            if (typeof entry.rawDir !== 'string' || entry.rawDir.length === 0) {
+                throw new Error('fundus.config: a "packages" entry "rawDir" must be a non-empty string.');
+            }
+            rawDirOverride = entry.rawDir;
+        }
+    }
+    else {
+        throw new Error('fundus.config: each "packages" entry must be a package name, a path string, or { package: string; rawDir?: string }.');
+    }
+    const kind = classifyPackageSpec(spec);
+    const reference = kind === 'path' ? resolve(projectRoot, spec) : spec;
+    return {
+        origin: spec,
+        kind,
+        reference,
+        ...(rawDirOverride !== undefined ? { rawDirOverride } : {})
+    };
+}
+function resolvePackageSources(projectRoot, value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new Error('fundus.config: "packages" must be an array.');
+    }
+    return value.map((entry) => normalizePackageSource(projectRoot, entry));
+}
 /** Pure resolution step (testable without a config file on disk). */
 export function resolveConfig(projectRoot, value, registry = serverPluginsByType) {
     if (!isRecord(value)) {
@@ -63,6 +149,10 @@ export function resolveConfig(projectRoot, value, registry = serverPluginsByType
     if (figma.token !== undefined && (typeof figma.token !== 'string' || figma.token.length === 0)) {
         throw new Error('fundus.config: "import.figma.token" must be a non-empty string.');
     }
+    if (figma.defaultFileKey !== undefined &&
+        (typeof figma.defaultFileKey !== 'string' || figma.defaultFileKey.length === 0)) {
+        throw new Error('fundus.config: "import.figma.defaultFileKey" must be a non-empty string.');
+    }
     const defaults = figma.defaults === undefined ? {} : figma.defaults;
     if (!isRecord(defaults)) {
         throw new Error('fundus.config: "import.figma.defaults" must be an object.');
@@ -92,12 +182,107 @@ export function resolveConfig(projectRoot, value, registry = serverPluginsByType
         import: {
             figma: {
                 ...(figma.token !== undefined ? { token: figma.token } : {}),
+                ...(figma.defaultFileKey !== undefined ? { defaultFileKey: figma.defaultFileKey } : {}),
                 defaults: { scale }
             }
         },
-        usage: usage === undefined ? null : usage
+        usage: usage === undefined ? null : usage,
+        packageSources: resolvePackageSources(projectRoot, value.packages),
+        packages: []
     };
 }
+function nearestNamedPackageJson(entryPath, name) {
+    let dir = dirname(entryPath);
+    for (;;) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+                if (isRecord(pkg) && pkg.name === name)
+                    return { dir, pkg };
+            }
+            catch {
+                // Malformed package.json — keep walking up.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`Cannot find the package.json for fundus package "${name}" (resolved to ${entryPath}).`);
+}
+/**
+ * Resolve a name-form Package to its root directory + parsed `package.json`. A
+ * declaration-only Package ships no JS entry module, so resolving the bare name
+ * would throw `MODULE_NOT_FOUND`; resolve its `package.json` subpath first and
+ * only fall back to entry resolution when an `exports` map hides it.
+ */
+function resolvePackageRoot(require, reference, origin) {
+    try {
+        const manifestPath = require.resolve(`${reference}/package.json`);
+        const pkg = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        if (isRecord(pkg))
+            return { dir: dirname(manifestPath), pkg };
+    }
+    catch {
+        // No resolvable ./package.json subpath — fall back to the entry module.
+    }
+    let entry;
+    try {
+        entry = require.resolve(reference);
+    }
+    catch {
+        throw new Error(`Cannot resolve fundus package "${origin}": no installed package declares it — is it a dependency?`);
+    }
+    return nearestNamedPackageJson(entry, reference);
+}
+/**
+ * Read and parse every declared Package from disk. Name entries resolve through
+ * the host's module resolver (respecting `exports`), then walk up to the nearest
+ * `package.json` that declares the name and read its `"fundus"` field. Path
+ * entries point directly at a `fundus.package.json`. Throws a clear,
+ * origin-tagged error on any resolution/read/parse failure — Package assembly
+ * failures are symmetric with a missing `fundus.config.ts`.
+ */
+export async function loadPackages(projectRoot, sources) {
+    const require = createRequire(pathToFileURL(join(projectRoot, 'fundus.config.ts')).href);
+    const packages = [];
+    for (const source of sources) {
+        let file;
+        let defaultRawDir;
+        if (source.kind === 'path') {
+            file = source.reference;
+            if (!existsSync(file)) {
+                throw new Error(`Fundus package file not found: ${file} (from "${source.origin}").`);
+            }
+            defaultRawDir = dirname(file);
+        }
+        else {
+            const { dir, pkg } = resolvePackageRoot(require, source.reference, source.origin);
+            const fundusField = pkg.fundus;
+            if (!isRecord(fundusField) ||
+                typeof fundusField.package !== 'string' ||
+                fundusField.package.length === 0) {
+                throw new Error(`Fundus package "${source.origin}" is missing a "fundus.package" field in its package.json.`);
+            }
+            file = resolve(dir, fundusField.package);
+            if (!existsSync(file)) {
+                throw new Error(`Fundus package "${source.origin}" declaration not found: ${file}.`);
+            }
+            defaultRawDir =
+                typeof fundusField.rawDir === 'string' && fundusField.rawDir.length > 0
+                    ? resolve(dir, fundusField.rawDir)
+                    : dir;
+        }
+        const declaration = await loadPackageDeclaration(file, source.origin);
+        const rawDir = source.rawDirOverride !== undefined
+            ? resolve(projectRoot, source.rawDirOverride)
+            : defaultRawDir;
+        packages.push({ origin: source.origin, file, rawDir, declaration });
+    }
+    return packages;
+}
 /** Load `fundus.config.ts` from the host project root. */
 export async function loadConfig(projectRoot) {
     const root = resolve(projectRoot);
@@ -113,5 +298,6 @@ export async function loadConfig(projectRoot) {
     catch (cause) {
         throw new Error(`Cannot load fundus.config.ts: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
-    return resolveConfig(root, isRecord(module) && 'default' in module ? module.default : module);
+    const config = resolveConfig(root, isRecord(module) && 'default' in module ? module.default : module);
+    return { ...config, packages: await loadPackages(root, config.packageSources) };
 }

package/dist/server/http.js

@@ -44,6 +44,7 @@ const SOURCE_ERROR_STATUS = {
     unauthorized: 401,
     forbidden: 403,
     'not-found': 404,
+    'ambiguous-tag': 409,
     'rate-limited': 429,
     'upstream-failed': 502,
     'invalid-response': 502,

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

@@ -1,21 +1,44 @@
-import { type ServerSourceImporter } from './contract.js';
+import { type ImporterContext, type ServerSourceImporter } from './contract.js';
 import { type PinnedHttpsTarget } from './pinned-https.js';
-export interface FigmaSourceParameters {
+export interface FigmaNodeSourceParameters {
+    mode?: 'node';
     fileKey: string;
     nodeId: string;
     format: 'png';
     scale: 1 | 2 | 3 | 4;
 }
-export interface FigmaImportInput {
+export interface FigmaTagSourceParameters {
+    mode: 'tag';
+    fileKey: string;
+    /** The Fundus asset id carried in Figma as `sharedPluginData.fundus.assetId`. */
+    fundusTag: string;
+    /** Resolved node id (colon-form), cached from the last tag resolution. */
+    nodeId: string;
+    format: 'png';
+    scale: 1 | 2 | 3 | 4;
+}
+export type FigmaSourceParameters = FigmaNodeSourceParameters | FigmaTagSourceParameters;
+export interface FigmaNodeImportInput {
+    mode?: 'node';
     url: string;
     format?: 'png';
     scale?: 1 | 2 | 3 | 4;
 }
+export interface FigmaTagImportInput {
+    mode: 'tag';
+    tag: string;
+    fileKey?: string;
+    format?: 'png';
+    scale?: 1 | 2 | 3 | 4;
+}
+export type FigmaImportInput = FigmaNodeImportInput | FigmaTagImportInput;
 export declare function parseFigmaSelectionUrl(value: string): {
     fileKey: string;
     nodeId: string;
 };
+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>;
+export declare function resolveTagToNode(fileKey: string, tag: string, context: ImporterContext): Promise<string>;
 export declare const figmaSourceImporter: ServerSourceImporter<FigmaImportInput, FigmaSourceParameters>;

package/dist/server/importers/figma.js

@@ -1,6 +1,7 @@
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
 import sharp from 'sharp';
+import { isValidAssetId } from '../../core/index.js';
 import { SourceImportError, invalidInput } from './contract.js';
 import { requestPinnedHttps } from './pinned-https.js';
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
@@ -36,6 +37,24 @@ export function parseFigmaSelectionUrl(value) {
     const [left, right] = nodeIds[0].split(/[-:]/);
     return { fileKey: segments[1], nodeId: `${left}:${right}` };
 }
+export function parseFigmaFileKey(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return invalidInput('Enter a valid Figma file link.');
+    }
+    if (url.protocol !== 'https:' ||
+        (url.hostname !== 'figma.com' && url.hostname !== 'www.figma.com')) {
+        return invalidInput('Figma links must use HTTPS on figma.com.');
+    }
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (!['design', 'file', 'proto'].includes(segments[0] ?? '') || !segments[1]) {
+        return invalidInput('The Figma link must point to a design, file, or prototype.');
+    }
+    return segments[1];
+}
 function validateScale(value) {
     if (value !== 1 && value !== 2 && value !== 3 && value !== 4) {
         return invalidInput('Figma export scale must be 1, 2, 3, or 4.');
@@ -44,12 +63,31 @@ function validateScale(value) {
 }
 function validateInput(value) {
     const input = record(value);
-    if (!input || typeof input.url !== 'string')
+    if (!input)
         return invalidInput('Figma import requires a URL.');
     if (input.format !== undefined && input.format !== 'png') {
         return invalidInput('Figma import currently supports PNG only.');
     }
+    if (input.mode === 'tag') {
+        if (typeof input.tag !== 'string' || !isValidAssetId(input.tag)) {
+            return invalidInput('Figma tag import requires a valid Fundus asset id as the tag.');
+        }
+        if (input.fileKey !== undefined &&
+            (typeof input.fileKey !== 'string' || input.fileKey.length === 0)) {
+            return invalidInput('Figma tag import fileKey must be a non-empty string.');
+        }
+        return {
+            mode: 'tag',
+            tag: input.tag,
+            format: 'png',
+            ...(input.fileKey !== undefined ? { fileKey: input.fileKey } : {}),
+            ...(input.scale !== undefined ? { scale: validateScale(input.scale) } : {})
+        };
+    }
+    if (typeof input.url !== 'string')
+        return invalidInput('Figma import requires a URL.');
     return {
+        mode: 'node',
         url: input.url,
         format: 'png',
         ...(input.scale !== undefined ? { scale: validateScale(input.scale) } : {})
@@ -65,6 +103,19 @@ export function validateFigmaSourceParameters(value) {
         source.format !== 'png') {
         return invalidInput('Stored Figma source parameters are invalid.');
     }
+    if (source.mode === 'tag') {
+        if (typeof source.fundusTag !== 'string' || !isValidAssetId(source.fundusTag)) {
+            return invalidInput('Stored Figma source parameters are invalid.');
+        }
+        return {
+            mode: 'tag',
+            fileKey: source.fileKey,
+            fundusTag: source.fundusTag,
+            nodeId: source.nodeId,
+            format: 'png',
+            scale: validateScale(source.scale)
+        };
+    }
     return {
         fileKey: source.fileKey,
         nodeId: source.nodeId,
@@ -332,6 +383,49 @@ async function validatePng(bytes) {
         throw new SourceImportError('image-too-large', 'Figma export exceeds the 32 megapixel limit.');
     }
 }
+function collectTaggedNodeIds(node, tag, matches) {
+    const current = record(node);
+    if (!current)
+        return;
+    const shared = record(current.sharedPluginData);
+    const fundus = shared ? record(shared.fundus) : null;
+    if (fundus && fundus.assetId === tag && typeof current.id === 'string') {
+        matches.push(current.id);
+    }
+    if (Array.isArray(current.children)) {
+        for (const child of current.children)
+            collectTaggedNodeIds(child, tag, matches);
+    }
+}
+export async function resolveTagToNode(fileKey, tag, context) {
+    const token = context.config.import.figma.token;
+    if (!token) {
+        throw new SourceImportError('not-configured', 'Figma access is not configured.');
+    }
+    const endpoint = new URL(`https://api.figma.com/v1/files/${encodeURIComponent(fileKey)}`);
+    endpoint.searchParams.set('plugin_data', 'shared');
+    const jsonBytes = await fetchWithDeadline(context.fetch, endpoint, { redirect: 'error', headers: { 'X-Figma-Token': token } }, async (response) => new Uint8Array(await response.arrayBuffer()));
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(jsonBytes));
+    }
+    catch {
+        throw new SourceImportError('invalid-response', 'Figma returned an invalid response.');
+    }
+    const body = record(payload);
+    if (!body || body.err || (typeof body.status === 'number' && body.status >= 400)) {
+        throw new SourceImportError('invalid-response', 'Figma returned an invalid response.');
+    }
+    const matches = [];
+    collectTaggedNodeIds(body.document, tag, matches);
+    if (matches.length === 0) {
+        throw new SourceImportError('not-found', `No Figma node is tagged "${tag}" in this file.`);
+    }
+    if (matches.length > 1) {
+        throw new SourceImportError('ambiguous-tag', `More than one Figma node is tagged "${tag}" in this file.`);
+    }
+    return matches[0];
+}
 async function materialize(source, context) {
     const token = context.config.import.figma.token;
     if (!token) {
@@ -371,6 +465,21 @@ export const figmaSourceImporter = {
     label: 'Figma',
     validateInput,
     async importRaw(input, context) {
+        if (input.mode === 'tag') {
+            const fileKey = input.fileKey ?? context.config.import.figma.defaultFileKey;
+            if (!fileKey) {
+                throw new SourceImportError('not-configured', 'Figma tag import needs a fileKey or import.figma.defaultFileKey in fundus.config.');
+            }
+            const nodeId = await resolveTagToNode(fileKey, input.tag, context);
+            return materialize({
+                mode: 'tag',
+                fileKey,
+                fundusTag: input.tag,
+                nodeId,
+                format: 'png',
+                scale: input.scale ?? context.config.import.figma.defaults.scale
+            }, context);
+        }
         const parsed = parseFigmaSelectionUrl(input.url);
         return materialize({
             fileKey: parsed.fileKey,
@@ -381,6 +490,10 @@ export const figmaSourceImporter = {
     },
     validateSourceParameters: validateFigmaSourceParameters,
     async reimportRaw(source, context) {
+        if (source.mode === 'tag') {
+            const nodeId = await resolveTagToNode(source.fileKey, source.fundusTag, context);
+            return materialize({ ...source, nodeId }, context);
+        }
         return materialize(source, context);
     }
 };

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

@@ -26,6 +26,14 @@ export interface IngestOptions {
 export interface CreateAssetOptions extends IngestOptions {
     manifests?: string[];
     importSource?: ImportSourceRecord;
+    /**
+     * Fill/override a Package slot: store these parameters verbatim as a host
+     * override record instead of expanding plugin defaults. Partial by design
+     * (only the overridden keys) — the merge deep-merges them over the Package
+     * base, and they are schema-validated over the effective library, not here.
+     * When set, `prepareParameters` is ignored.
+     */
+    parametersOverride?: unknown;
 }
 export interface CreateAssetStaging {
     rawPath: string;
@@ -84,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). */
@@ -124,6 +141,8 @@ export declare class LibraryStore {
      * type, dangling raw pointer, invalid parameters, unknown manifest names,
      * and reference errors (dangling target, type mismatch, cycles).
      */
-    validate(library: Library): Promise<ValidationIssueDto[]>;
+    validate(library: Library, options?: {
+        flatSpace?: boolean;
+    }): Promise<ValidationIssueDto[]>;
     syncFolders(library: Library): Promise<void>;
 }