fundus 0.2.0 → 0.4.0

package/dist/server/cli-commands.js

@@ -14,6 +14,7 @@ import { runBuild } from './build.js';
 import { formatCheckFinding, runCheck } from './check.js';
 import { loadConfig } from './config-loader.js';
 import { FundusOperations } from './operations.js';
+import { validateFigmaSourceParameters } from './importers/figma.js';
 import { pluginsByType, serverPluginForType } from './plugins.js';
 import { CliUsageError, formatBytes, parseArguments, parseJsonFlag, parseManifestList, printJsonDocument, requirePositionals } from './cli-io.js';
 const COMMON_FLAGS = {
@@ -111,6 +112,10 @@ function printHumanAssetDetail(asset) {
     console.log(`  raw:        ${asset.raw}`);
     console.log(`  folder:     ${asset.folder || 'root'}`);
     console.log(`  rawHash:    ${asset.rawHash}`);
+    if (asset.importSource?.importer === 'figma') {
+        const source = validateFigmaSourceParameters(asset.importSource.parameters);
+        console.log(`  source:     Figma node ${source.nodeId} at ${source.scale}x`);
+    }
     console.log(`  manifests:  ${asset.manifests.length > 0 ? asset.manifests.join(', ') : '(none)'}`);
     for (const membership of asset.passiveManifests) {
         console.log(`  passive:    ${membership.manifest} (via ${membership.via.join(', ')})`);
@@ -201,7 +206,8 @@ document on stdout) and --help.
 Subcommands:
   list      list assets (--manifest, --type, --warnings-only)
   show      one asset in detail
-  ingest    copy a file into the raw dir as a typed asset
+  ingest    acquire a file or Figma selection as a typed asset
+  reimport  refresh an asset from its saved source
   replace   replace an asset's raw file while preserving its metadata
   set       merge parameters and/or replace manifest membership
   rename    rename an asset id
@@ -248,43 +254,65 @@ Read-only: nothing is processed or written.
 Example:
   fundus asset show navigationPanel --json
 `;
-export const ASSET_INGEST_HELP = `fundus asset ingest — copy a file into the raw dir as a typed asset
+export const ASSET_INGEST_HELP = `fundus asset ingest — acquire a file or Figma selection as a typed asset
 
 Usage: fundus asset ingest <file> [--type <type>] [--id <id>] [--folder <path|root>]
+                           [--manifests <a,b>] [--parameters <json>] [--from file] [--json]
+       fundus asset ingest <figma-selection-link> --from figma --type <image|slice> --id <id>
+                           [--scale <1|2|3|4>] [--folder <path|root>]
                            [--manifests <a,b>] [--parameters <json>] [--json]
 
-Behaves like an editor upload: the file is copied into the raw
-directory (sanitized, non-colliding name) and content-hashed, and the
-record starts with the owning plugin's default parameters — a slice
-additionally seeds insets from the image dimensions and a pixel ratio
-from a @2x-style file-name suffix. Runs the full autosave chain
-(write library → process → regenerate manifest modules).
+File ingest remains the default and behaves like an editor upload. Figma
+ingest materializes one selection as PNG through the same importer-neutral
+operations pipeline. Both run the full autosave chain.
 
 Flags:
-  --type <type>        required when the file extension is ambiguous
-                       (.png could be image or slice, .mp4 video or
-                       chroma-key-video); optional when exactly one
-                       type accepts it (.wav → audio); known types:
+  --from <file|figma> acquisition source; default: file. URLs are never
+                       detected heuristically
+  --type <type>        required for Figma (image or slice) and when a file
+                       extension is ambiguous; known types:
                        ${Object.keys(pluginsByType).sort().join(', ')}
-  --id <id>            asset id (camelCase identifier); default:
-                       proposed from the file name
-                       (panel_button@2x.png → sidebarPanel)
+  --id <id>            required for Figma; for files defaults to a proposal
+                       from the file name
   --folder <path|root> destination folder; default: root
-  --manifests <a,b>    explicit manifest membership, applied in the
-                       same operation (comma-separated; every name
-                       must exist)
-  --parameters <json>  parameter patch merged onto the plugin defaults
-                       — same shallow-merge semantics as \`asset set\`
+  --manifests <a,b>    explicit manifest membership (every name must exist)
+  --parameters <json>  shallow parameter patch merged after ingest seeding
                        (see \`fundus asset set --help\`)
+  --scale <1|2|3|4>    Figma export scale; default:
+                       import.figma.defaults.scale from fundus.config.ts
+                       (invalid for file ingest)
   --json               print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
   --help               this help
 
-A failed ingest (invalid patch, unknown manifest, …) leaves nothing
-behind: the raw file and record are rolled back.
+A failed ingest leaves neither a raw file nor a record behind.
 
 Example:
-  fundus asset ingest ./exports/navigation_panel@2x.png --type slice \\
-    --manifests mainCatalog --json
+  fundus asset ingest ./exports/navigation_panel@2x.png --type slice --json
+  fundus asset ingest 'https://www.figma.com/design/abc/UI?node-id=12-34' \\
+    --from figma --type slice --id navigationPanel --scale 3 --json
+`;
+export const ASSET_REIMPORT_HELP = `fundus asset reimport — refresh an asset from its saved source
+
+Usage: fundus asset reimport <id> [--json]
+       fundus asset reimport <id> --figma-link <selection-link> [--scale <1|2|3|4>] [--json]
+       fundus asset reimport <id> --scale <1|2|3|4> [--json]
+
+Without overrides, re-materializes the persisted importer source. Figma
+overrides may update the link, scale, or both; omitted values are preserved.
+Asset type, parameters, folder, manifests, and id remain unchanged. Raw-file
+drift or concurrent changes abort without overwriting local edits.
+
+Flags:
+  --figma-link <link>  replace the persisted Figma file/node selection
+  --scale <1|2|3|4>    replace the persisted Figma export scale
+  --json               print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help               this help
+
+Example:
+  fundus asset reimport navigationPanel
+  fundus asset reimport navigationPanel --figma-link '<new-selection-link>'
+  fundus asset reimport navigationPanel --scale 4
+  fundus asset reimport navigationPanel --figma-link '<new-selection-link>' --scale 4 --json
 `;
 export const ASSET_REPLACE_HELP = `fundus asset replace — replace an asset's raw file
 
@@ -385,6 +413,7 @@ const ASSET_SUBCOMMAND_HELP = {
     list: ASSET_LIST_HELP,
     show: ASSET_SHOW_HELP,
     ingest: ASSET_INGEST_HELP,
+    reimport: ASSET_REIMPORT_HELP,
     replace: ASSET_REPLACE_HELP,
     set: ASSET_SET_HELP,
     rename: ASSET_RENAME_HELP,
@@ -470,9 +499,57 @@ async function runAssetIngest(argumentList) {
         id: { takesValue: true },
         manifests: { takesValue: true },
         parameters: { takesValue: true },
-        folder: { takesValue: true }
+        folder: { takesValue: true },
+        from: { takesValue: true },
+        scale: { takesValue: true }
     }, 'fundus asset ingest');
-    const [filePath] = requirePositionals(parsed, ['<file>'], 'fundus asset ingest');
+    const [source] = requirePositionals(parsed, ['<file|figma-selection-link>'], 'fundus asset ingest');
+    const from = parsed.flags.from === undefined ? 'file' : parsed.flags.from;
+    if (from !== 'file' && from !== 'figma') {
+        throw new CliUsageError('Flag "--from" must be "file" or "figma" — run `fundus asset ingest --help`.');
+    }
+    const scale = typeof parsed.flags.scale === 'string'
+        ? parseFigmaScale(parsed.flags.scale, 'fundus asset ingest')
+        : undefined;
+    if (from === 'file' && scale !== undefined) {
+        throw new CliUsageError('Flag "--scale" is only valid with `--from figma` — run `fundus asset ingest --help`.');
+    }
+    const parametersPatch = typeof parsed.flags.parameters === 'string'
+        ? parseJsonFlag('parameters', parsed.flags.parameters)
+        : undefined;
+    const manifests = typeof parsed.flags.manifests === 'string'
+        ? parseManifestList(parsed.flags.manifests)
+        : undefined;
+    const folder = typeof parsed.flags.folder === 'string' ? parseFolderToken(parsed.flags.folder) : '';
+    if (from === 'figma') {
+        if (typeof parsed.flags.id !== 'string') {
+            throw new CliUsageError('Figma ingest requires --id <id> — run `fundus asset ingest --help`.');
+        }
+        if (typeof parsed.flags.type !== 'string' ||
+            (parsed.flags.type !== 'image' && parsed.flags.type !== 'slice')) {
+            throw new CliUsageError('Figma ingest requires --type <image|slice> — run `fundus asset ingest --help`.');
+        }
+        const id = parsed.flags.id;
+        const type = parsed.flags.type;
+        const operations = await createOperations();
+        const state = await operations.importAsset({
+            importer: 'figma',
+            input: { url: source, format: 'png', ...(scale !== undefined ? { scale } : {}) },
+            type,
+            id,
+            folder,
+            parametersPatch,
+            manifests
+        });
+        const asset = assetById(state, id);
+        if (parsed.flags.json) {
+            printJsonDocument({ ok: true, asset, issues: state.issues });
+            return;
+        }
+        printMutationResult(`Imported asset "${id}" from Figma as ${type}.`, asset, state);
+        return;
+    }
+    const filePath = source;
     const absolutePath = resolve(process.cwd(), filePath);
     let bytes;
     try {
@@ -484,13 +561,6 @@ async function runAssetIngest(argumentList) {
     const fileName = basename(absolutePath);
     const type = typeof parsed.flags.type === 'string' ? parsed.flags.type : inferTypeForFileName(fileName);
     const id = typeof parsed.flags.id === 'string' ? parsed.flags.id : proposeAssetId(fileName);
-    const parametersPatch = typeof parsed.flags.parameters === 'string'
-        ? parseJsonFlag('parameters', parsed.flags.parameters)
-        : undefined;
-    const manifests = typeof parsed.flags.manifests === 'string'
-        ? parseManifestList(parsed.flags.manifests)
-        : undefined;
-    const folder = typeof parsed.flags.folder === 'string' ? parseFolderToken(parsed.flags.folder) : '';
     const operations = await createOperations();
     const state = await operations.ingest({
         fileName,
@@ -508,6 +578,55 @@ async function runAssetIngest(argumentList) {
     }
     printMutationResult(`Ingested "${fileName}" as ${type} asset "${id}".`, asset, state);
 }
+function parseFigmaScale(value, commandPath) {
+    if (value === '1' || value === '2' || value === '3' || value === '4') {
+        return Number(value);
+    }
+    throw new CliUsageError(`Flag "--scale" must be 1, 2, 3, or 4 — run \`${commandPath} --help\`.`);
+}
+function canonicalFigmaSelectionLink(source) {
+    const url = new URL(`https://www.figma.com/design/${encodeURIComponent(source.fileKey)}/fundus`);
+    url.searchParams.set('node-id', source.nodeId.replace(':', '-'));
+    return url.toString();
+}
+async function runAssetReimport(argumentList) {
+    const parsed = parseArguments(argumentList, {
+        ...COMMON_FLAGS,
+        'figma-link': { takesValue: true },
+        scale: { takesValue: true }
+    }, 'fundus asset reimport');
+    const [id] = requirePositionals(parsed, ['<id>'], 'fundus asset reimport');
+    const scale = typeof parsed.flags.scale === 'string'
+        ? parseFigmaScale(parsed.flags.scale, 'fundus asset reimport')
+        : undefined;
+    const figmaLink = typeof parsed.flags['figma-link'] === 'string' ? parsed.flags['figma-link'] : undefined;
+    const operations = await createOperations();
+    let state;
+    if (figmaLink === undefined && scale === undefined) {
+        state = await operations.reimportAsset(id);
+    }
+    else {
+        const current = await operations.state();
+        const currentAsset = assetById(current, id);
+        if (currentAsset.importSource?.importer !== 'figma') {
+            throw new Error(`Asset "${id}" does not have a Figma source.`);
+        }
+        const source = validateFigmaSourceParameters(currentAsset.importSource.parameters);
+        state = await operations.reimportAsset(id, {
+            url: figmaLink ?? canonicalFigmaSelectionLink(source),
+            format: 'png',
+            scale: scale ?? source.scale
+        });
+    }
+    const asset = assetById(state, id);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, asset, issues: state.issues });
+        return;
+    }
+    printMutationResult(figmaLink === undefined && scale === undefined
+        ? `Refreshed asset "${id}" from its saved source.`
+        : `Reimported asset "${id}" with updated Figma source.`, asset, state);
+}
 async function runAssetReplace(argumentList) {
     const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus asset replace');
     const [id, filePath] = requirePositionals(parsed, ['<id>', '<file>'], 'fundus asset replace');
@@ -593,7 +712,7 @@ export async function runAssetCommand(argumentList) {
     if (subcommand === undefined || subcommand === '--help') {
         console.log(ASSET_HELP);
         if (subcommand === undefined) {
-            throw new CliUsageError('`fundus asset` needs a subcommand: list, show, ingest, replace, set, rename, move, delete.');
+            throw new CliUsageError('`fundus asset` needs a subcommand: list, show, ingest, reimport, replace, set, rename, move, delete.');
         }
         return;
     }
@@ -609,6 +728,8 @@ export async function runAssetCommand(argumentList) {
             return runAssetShow(rest);
         case 'ingest':
             return runAssetIngest(rest);
+        case 'reimport':
+            return runAssetReimport(rest);
         case 'replace':
             return runAssetReplace(rest);
         case 'set':

package/dist/server/config-loader.d.ts

@@ -1,4 +1,4 @@
-import type { AudioPreset, ImagePreset, VideoPreset } from '../core/index.js';
+import type { AudioPreset, FigmaImportScale, ImagePreset, VideoPreset } from '../core/index.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 export interface ResolvedPresetPluginConfig {
     presets: Record<string, ImagePreset>;
@@ -28,6 +28,14 @@ export interface ResolvedFundusConfig {
         video: ResolvedVideoPluginConfig;
         audio: ResolvedAudioPluginConfig;
     };
+    import: {
+        figma: {
+            token?: string;
+            defaults: {
+                scale: FigmaImportScale;
+            };
+        };
+    };
 }
 /** Pure resolution step (testable without a config file on disk). */
 export declare function resolveConfig(projectRoot: string, value: unknown, registry?: ServerPluginRegistry): ResolvedFundusConfig;

package/dist/server/config-loader.js

@@ -51,13 +51,38 @@ export function resolveConfig(projectRoot, value, registry = serverPluginsByType
             value: plugins[definition.namespace]
         });
     }
+    const importConfig = value.import === undefined ? {} : value.import;
+    if (!isRecord(importConfig)) {
+        throw new Error('fundus.config: "import" must be an object.');
+    }
+    const figma = importConfig.figma === undefined ? {} : importConfig.figma;
+    if (!isRecord(figma)) {
+        throw new Error('fundus.config: "import.figma" must be an object.');
+    }
+    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.');
+    }
+    const defaults = figma.defaults === undefined ? {} : figma.defaults;
+    if (!isRecord(defaults)) {
+        throw new Error('fundus.config: "import.figma.defaults" must be an object.');
+    }
+    const scale = defaults.scale === undefined ? 2 : defaults.scale;
+    if (scale !== 1 && scale !== 2 && scale !== 3 && scale !== 4) {
+        throw new Error('fundus.config: "import.figma.defaults.scale" must be 1, 2, 3, or 4.');
+    }
     return {
         rawDir: resolvePath(projectRoot, requiredString(value, 'rawDir')),
         proxyDir: resolvePath(projectRoot, requiredString(value, 'proxyDir')),
         library: resolvePath(projectRoot, requiredString(value, 'library')),
         manifestsDir: resolvePath(projectRoot, requiredString(value, 'manifestsDir')),
         proxyBasePath,
-        plugins: resolvedPlugins
+        plugins: resolvedPlugins,
+        import: {
+            figma: {
+                ...(figma.token !== undefined ? { token: figma.token } : {}),
+                defaults: { scale }
+            }
+        }
     };
 }
 /** Load `fundus.config.ts` from the host project root. */

package/dist/server/file-manager.d.ts

@@ -0,0 +1,2 @@
+/** Reveal a file, or open a directory, in the host platform's file manager. */
+export declare function openInFileManager(target: string, kind: 'file' | 'directory'): Promise<void>;

package/dist/server/file-manager.js

@@ -0,0 +1,17 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { dirname } from 'node:path';
+import open from 'open';
+const execute = promisify(execFile);
+/** Reveal a file, or open a directory, in the host platform's file manager. */
+export async function openInFileManager(target, kind) {
+    if (kind === 'file' && process.platform === 'darwin') {
+        await execute('open', ['-R', target]);
+        return;
+    }
+    if (kind === 'file' && process.platform === 'win32') {
+        await execute('explorer.exe', [`/select,${target}`], { windowsHide: true });
+        return;
+    }
+    await open(kind === 'file' ? dirname(target) : target);
+}

package/dist/server/http.d.ts

@@ -5,6 +5,7 @@ export declare function routeNotFound(event: {
     url: URL;
 }): Response;
 export declare function apiResponse(run: () => Promise<unknown>): Promise<Response>;
+export declare function sourceImportResponse(run: () => Promise<unknown>): Promise<Response>;
 export declare function parseByteRange(rangeHeader: string | null, size: number): {
     start: number;
     end: number;

package/dist/server/http.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { lstat, readFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
 import { assertSafeRelativeFilePath } from './library-store.js';
+import { SourceImportError } from './importers/contract.js';
 const CONTENT_TYPES = {
     '.png': 'image/png',
     '.jpg': 'image/jpeg',
@@ -37,6 +38,42 @@ export async function apiResponse(run) {
         return errorResponse(cause, 400);
     }
 }
+const SOURCE_ERROR_STATUS = {
+    'invalid-input': 400,
+    'not-configured': 401,
+    unauthorized: 401,
+    forbidden: 403,
+    'not-found': 404,
+    'rate-limited': 429,
+    'upstream-failed': 502,
+    'invalid-response': 502,
+    'unsafe-download-url': 502,
+    'download-timeout': 504,
+    'download-too-large': 502,
+    'image-too-large': 502,
+    'stale-import': 409
+};
+export async function sourceImportResponse(run) {
+    try {
+        return Response.json(await run());
+    }
+    catch (cause) {
+        const error = cause instanceof SourceImportError
+            ? cause
+            : new SourceImportError('invalid-input', cause instanceof Error ? cause.message : String(cause));
+        const body = {
+            error: {
+                message: error.message,
+                code: error.code,
+                retryAfterSeconds: error.retryAfterSeconds
+            }
+        };
+        const headers = error.code === 'rate-limited' && error.retryAfterSeconds !== undefined
+            ? { 'Retry-After': String(error.retryAfterSeconds) }
+            : undefined;
+        return Response.json(body, { status: SOURCE_ERROR_STATUS[error.code], headers });
+    }
+}
 export function parseByteRange(rangeHeader, size) {
     if (!rangeHeader)
         return null;

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

@@ -0,0 +1,29 @@
+import type { ImportSourceRecord, SourceImportErrorCode } from '../../core/index.js';
+import type { ResolvedFundusConfig } from '../config-loader.js';
+import type { PinnedHttpsTransport } from './pinned-https.js';
+export interface ImportedRaw {
+    bytes: Uint8Array;
+    /** Lowercase extension without a leading dot. */
+    extension: string;
+    suggestedFileName?: string;
+    importSource?: ImportSourceRecord;
+}
+export interface ImporterContext {
+    config: ResolvedFundusConfig;
+    fetch: typeof globalThis.fetch;
+    httpsTransport?: PinnedHttpsTransport;
+}
+export interface ServerSourceImporter<TInput = unknown, TSource = unknown> {
+    kind: string;
+    label: string;
+    validateInput(value: unknown): TInput;
+    importRaw(input: TInput, context: ImporterContext): Promise<ImportedRaw>;
+    validateSourceParameters(value: unknown): TSource;
+    reimportRaw?(source: TSource, context: ImporterContext): Promise<ImportedRaw>;
+}
+export declare class SourceImportError extends Error {
+    readonly code: SourceImportErrorCode;
+    readonly retryAfterSeconds?: number;
+    constructor(code: SourceImportErrorCode, message: string, retryAfterSeconds?: number);
+}
+export declare function invalidInput(message: string): never;

package/dist/server/importers/contract.js

@@ -0,0 +1,13 @@
+export class SourceImportError extends Error {
+    code;
+    retryAfterSeconds;
+    constructor(code, message, retryAfterSeconds) {
+        super(message);
+        this.name = 'SourceImportError';
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export function invalidInput(message) {
+    throw new SourceImportError('invalid-input', message);
+}

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

@@ -0,0 +1,21 @@
+import { type ServerSourceImporter } from './contract.js';
+import { type PinnedHttpsTarget } from './pinned-https.js';
+export interface FigmaSourceParameters {
+    fileKey: string;
+    nodeId: string;
+    format: 'png';
+    scale: 1 | 2 | 3 | 4;
+}
+export interface FigmaImportInput {
+    url: string;
+    format?: 'png';
+    scale?: 1 | 2 | 3 | 4;
+}
+export declare function parseFigmaSelectionUrl(value: string): {
+    fileKey: string;
+    nodeId: 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 const figmaSourceImporter: ServerSourceImporter<FigmaImportInput, FigmaSourceParameters>;