@fnndsc/chili 3.2.5

package/dist/path/pathMapper.d.ts

@@ -0,0 +1,189 @@
+/**
+ * @file Singleton path mapper for logical-to-physical ChRIS path resolution.
+ *
+ * Maintains a cached mapping of logical paths to physical locations,
+ * enabling incremental resolution by reusing cached path prefixes.
+ *
+ * Example:
+ *   - First call: '/home/user/public/feed_4' → Full resolution, cache prefix
+ *   - Second call: '/home/user/public/feed_5' → Reuse '/home/user/public', resolve only 'feed_5'
+ *
+ * This eliminates redundant tree walking and API calls for paths with common prefixes.
+ *
+ * @module
+ */
+import { Result } from '@fnndsc/cumin';
+/**
+ * Statistics for cache performance monitoring.
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    size: number;
+    hitRate: number;
+}
+/**
+ * Singleton PathMapper class for logical-to-physical path resolution.
+ *
+ * Maintains hierarchical cache of path mappings to minimize repeated
+ * link resolution operations.
+ *
+ * @example
+ * ```typescript
+ * const mapper = PathMapper.instance_get();
+ *
+ * // First resolution
+ * const result1 = await mapper.logical_toPhysical('/home/user/public/feed_4');
+ * // → Resolves /home/user/public → /SHARED, then feed_4
+ * // → Caches intermediate mappings
+ *
+ * // Second resolution - prefix reuse
+ * const result2 = await mapper.logical_toPhysical('/home/user/public/feed_5');
+ * // → Reuses cached '/home/user/public' → '/SHARED'
+ * // → Resolves only 'feed_5'
+ * ```
+ */
+export declare class PathMapper {
+    private static instance;
+    private cache;
+    private readonly defaultTTL;
+    private stats;
+    /**
+     * Private constructor enforces singleton pattern.
+     */
+    private constructor();
+    /**
+     * Gets the singleton PathMapper instance.
+     *
+     * @returns The singleton PathMapper instance.
+     */
+    static instance_get(): PathMapper;
+    /**
+     * Resets the singleton instance (for testing).
+     *
+     * @internal
+     */
+    static instance_reset(): void;
+    /**
+     * Resolves a logical path to its physical location.
+     *
+     * Uses cached path prefixes when available, resolving only the
+     * uncached suffix to minimize API calls.
+     *
+     * @param logicalPath - The logical path to resolve.
+     * @returns Result containing the physical path, or Err on failure.
+     *
+     * @example
+     * ```typescript
+     * const mapper = PathMapper.instance_get();
+     *
+     * // First call: full resolution
+     * const result1 = await mapper.logical_toPhysical('/home/user/public/feed_4');
+     * // → Resolves /home/user/public → /SHARED, then feed_4
+     * // → Caches: '/home/user/public' → '/SHARED'
+     * // → Caches: '/home/user/public/feed_4' → '/SHARED/feed_4'
+     *
+     * // Second call: prefix reuse
+     * const result2 = await mapper.logical_toPhysical('/home/user/public/feed_5');
+     * // → Reuses cached '/home/user/public' → '/SHARED'
+     * // → Resolves only 'feed_5'
+     * ```
+     */
+    logical_toPhysical(logicalPath: string): Promise<Result<string>>;
+    /**
+     * Finds the longest cached prefix of a logical path.
+     *
+     * Walks up the path hierarchy to find the deepest cached mapping,
+     * returning the cached physical prefix and remaining suffix.
+     *
+     * @param logicalPath - The full logical path.
+     * @returns Object with cached prefix and remaining suffix.
+     *
+     * @example
+     * ```typescript
+     * // Cache contains: '/home/user/public' → '/SHARED'
+     * const result = mapper.longestCachedPrefix_find('/home/user/public/feed_4/files');
+     * // Returns:
+     * // {
+     * //   prefixLogical: '/home/user/public',
+     * //   prefixPhysical: '/SHARED',
+     * //   suffix: 'feed_4/files'
+     * // }
+     * ```
+     */
+    private longestCachedPrefix_find;
+    /**
+     * Resolves a path suffix by checking each component for links.
+     *
+     * Walks the suffix path, checking each component to see if it's a link.
+     * Caches intermediate mappings along the way for future prefix reuse.
+     *
+     * @param suffix - The path suffix to resolve (e.g., 'feed_4/files').
+     * @param physicalBase - The physical base path to build upon.
+     * @param logicalBase - The logical base path (for caching intermediate results).
+     * @returns Result containing the resolved physical path.
+     */
+    private suffix_resolve;
+    /**
+     * Checks if a path is a link and returns its target.
+     *
+     * Optimizes resolution by checking ListCache first. If the parent directory
+     * is cached, we can determine if the candidate is a link without an API call.
+     * Falls back to API (fetching all links in parent) if not cached.
+     *
+     * @param candidatePhysical - The physical path to check.
+     * @param candidateLogical - The logical path (used for cache lookup).
+     * @returns The link target if it's a link, null otherwise.
+     */
+    private link_checkAndResolve;
+    /**
+     * Gets a cached mapping if it exists and hasn't expired.
+     *
+     * @param logicalPath - The logical path to look up.
+     * @returns The cached physical path, or null if not cached or expired.
+     */
+    private cache_get;
+    /**
+     * Caches a logical-to-physical path mapping.
+     *
+     * @param logicalPath - The logical path.
+     * @param physicalPath - The corresponding physical path.
+     * @param ttl - Optional TTL in milliseconds (defaults to 30s).
+     */
+    private cache_set;
+    /**
+     * Invalidates all cached mappings with a given logical path prefix.
+     *
+     * Call this when links are created/deleted/modified.
+     *
+     * @param logicalPathPrefix - The logical path prefix to invalidate.
+     *
+     * @example
+     * ```typescript
+     * // Link changed: /home/user/public → /SHARED becomes → /PUBLIC
+     * mapper.cache_invalidate('/home/user/public');
+     * // Invalidates:
+     * //   - /home/user/public
+     * //   - /home/user/public/feed_4
+     * //   - /home/user/public/feed_5
+     * //   - ... etc
+     * ```
+     */
+    cache_invalidate(logicalPathPrefix: string): void;
+    /**
+     * Clears all cached mappings.
+     */
+    cache_clear(): void;
+    /**
+     * Gets cache statistics.
+     *
+     * @returns Cache statistics including hit rate and size.
+     */
+    stats_get(): CacheStats;
+}
+/**
+ * Convenience function to get the singleton PathMapper instance.
+ *
+ * @returns The singleton PathMapper instance.
+ */
+export declare function pathMapper_get(): PathMapper;

package/dist/path/pathMapper.js

@@ -0,0 +1,382 @@
+/**
+ * @file Singleton path mapper for logical-to-physical ChRIS path resolution.
+ *
+ * Maintains a cached mapping of logical paths to physical locations,
+ * enabling incremental resolution by reusing cached path prefixes.
+ *
+ * Example:
+ *   - First call: '/home/user/public/feed_4' → Full resolution, cache prefix
+ *   - Second call: '/home/user/public/feed_5' → Reuse '/home/user/public', resolve only 'feed_5'
+ *
+ * This eliminates redundant tree walking and API calls for paths with common prefixes.
+ *
+ * @module
+ */
+import { Ok, Err, errorStack } from '@fnndsc/cumin';
+import { files_listAll } from '@fnndsc/salsa';
+import * as path from 'path';
+import { listCache_get } from '@fnndsc/cumin';
+/**
+ * Singleton PathMapper class for logical-to-physical path resolution.
+ *
+ * Maintains hierarchical cache of path mappings to minimize repeated
+ * link resolution operations.
+ *
+ * @example
+ * ```typescript
+ * const mapper = PathMapper.instance_get();
+ *
+ * // First resolution
+ * const result1 = await mapper.logical_toPhysical('/home/user/public/feed_4');
+ * // → Resolves /home/user/public → /SHARED, then feed_4
+ * // → Caches intermediate mappings
+ *
+ * // Second resolution - prefix reuse
+ * const result2 = await mapper.logical_toPhysical('/home/user/public/feed_5');
+ * // → Reuses cached '/home/user/public' → '/SHARED'
+ * // → Resolves only 'feed_5'
+ * ```
+ */
+export class PathMapper {
+    /**
+     * Private constructor enforces singleton pattern.
+     */
+    constructor() {
+        this.cache = new Map();
+        this.defaultTTL = 30000; // 30 seconds
+        this.stats = { hits: 0, misses: 0 };
+    }
+    /**
+     * Gets the singleton PathMapper instance.
+     *
+     * @returns The singleton PathMapper instance.
+     */
+    static instance_get() {
+        if (!PathMapper.instance) {
+            PathMapper.instance = new PathMapper();
+        }
+        return PathMapper.instance;
+    }
+    /**
+     * Resets the singleton instance (for testing).
+     *
+     * @internal
+     */
+    static instance_reset() {
+        PathMapper.instance = null;
+    }
+    /**
+     * Resolves a logical path to its physical location.
+     *
+     * Uses cached path prefixes when available, resolving only the
+     * uncached suffix to minimize API calls.
+     *
+     * @param logicalPath - The logical path to resolve.
+     * @returns Result containing the physical path, or Err on failure.
+     *
+     * @example
+     * ```typescript
+     * const mapper = PathMapper.instance_get();
+     *
+     * // First call: full resolution
+     * const result1 = await mapper.logical_toPhysical('/home/user/public/feed_4');
+     * // → Resolves /home/user/public → /SHARED, then feed_4
+     * // → Caches: '/home/user/public' → '/SHARED'
+     * // → Caches: '/home/user/public/feed_4' → '/SHARED/feed_4'
+     *
+     * // Second call: prefix reuse
+     * const result2 = await mapper.logical_toPhysical('/home/user/public/feed_5');
+     * // → Reuses cached '/home/user/public' → '/SHARED'
+     * // → Resolves only 'feed_5'
+     * ```
+     */
+    async logical_toPhysical(logicalPath) {
+        // 1. Validate input
+        if (!logicalPath || typeof logicalPath !== 'string') {
+            errorStack.stack_push('error', 'Invalid path: path must be a non-empty string');
+            return Err();
+        }
+        // 2. Normalize path
+        const normalizedPath = logicalPath.startsWith('/')
+            ? logicalPath
+            : `/${logicalPath}`;
+        // 3. Check exact cache hit
+        const exactMatch = this.cache_get(normalizedPath);
+        if (exactMatch !== null) {
+            this.stats.hits++;
+            return Ok(exactMatch);
+        }
+        // 4. Find longest cached prefix
+        const prefixMatch = this.longestCachedPrefix_find(normalizedPath);
+        // 5. Resolve suffix incrementally
+        const resolvedPhysical = await this.suffix_resolve(prefixMatch.suffix, prefixMatch.prefixPhysical, prefixMatch.prefixLogical);
+        if (!resolvedPhysical.ok) {
+            this.stats.misses++;
+            return Err();
+        }
+        // 6. Cache the full resolution
+        this.cache_set(normalizedPath, resolvedPhysical.value);
+        this.stats.misses++;
+        return Ok(resolvedPhysical.value);
+    }
+    /**
+     * Finds the longest cached prefix of a logical path.
+     *
+     * Walks up the path hierarchy to find the deepest cached mapping,
+     * returning the cached physical prefix and remaining suffix.
+     *
+     * @param logicalPath - The full logical path.
+     * @returns Object with cached prefix and remaining suffix.
+     *
+     * @example
+     * ```typescript
+     * // Cache contains: '/home/user/public' → '/SHARED'
+     * const result = mapper.longestCachedPrefix_find('/home/user/public/feed_4/files');
+     * // Returns:
+     * // {
+     * //   prefixLogical: '/home/user/public',
+     * //   prefixPhysical: '/SHARED',
+     * //   suffix: 'feed_4/files'
+     * // }
+     * ```
+     */
+    longestCachedPrefix_find(logicalPath) {
+        const parts = logicalPath.split('/').filter((p) => p.length > 0);
+        // Walk down from full path to root
+        for (let i = parts.length; i >= 0; i--) {
+            const candidatePrefix = i === 0
+                ? '/'
+                : '/' + parts.slice(0, i).join('/');
+            const cached = this.cache_get(candidatePrefix);
+            if (cached !== null) {
+                const suffixParts = parts.slice(i);
+                const suffix = suffixParts.join('/');
+                return {
+                    prefixLogical: candidatePrefix,
+                    prefixPhysical: cached,
+                    suffix: suffix
+                };
+            }
+        }
+        // No cached prefix found, start from root
+        return {
+            prefixLogical: '/',
+            prefixPhysical: '/',
+            suffix: parts.join('/')
+        };
+    }
+    /**
+     * Resolves a path suffix by checking each component for links.
+     *
+     * Walks the suffix path, checking each component to see if it's a link.
+     * Caches intermediate mappings along the way for future prefix reuse.
+     *
+     * @param suffix - The path suffix to resolve (e.g., 'feed_4/files').
+     * @param physicalBase - The physical base path to build upon.
+     * @param logicalBase - The logical base path (for caching intermediate results).
+     * @returns Result containing the resolved physical path.
+     */
+    async suffix_resolve(suffix, physicalBase, logicalBase) {
+        if (!suffix || suffix.length === 0) {
+            return Ok(physicalBase);
+        }
+        const parts = suffix.split('/').filter((p) => p.length > 0);
+        let physicalCurrent = physicalBase;
+        let logicalCurrent = logicalBase;
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            const candidatePhysical = physicalCurrent === '/'
+                ? `/${part}`
+                : `${physicalCurrent}/${part}`;
+            const candidateLogical = logicalCurrent === '/'
+                ? `/${part}`
+                : `${logicalCurrent}/${part}`;
+            try {
+                const linkTarget = await this.link_checkAndResolve(candidatePhysical, candidateLogical);
+                if (linkTarget) {
+                    // It's a link! Jump to target
+                    physicalCurrent = linkTarget;
+                    logicalCurrent = candidateLogical;
+                    // Cache this intermediate mapping
+                    this.cache_set(candidateLogical, linkTarget);
+                }
+                else {
+                    // Not a link, continue building path
+                    physicalCurrent = candidatePhysical;
+                    logicalCurrent = candidateLogical;
+                    // Cache this intermediate mapping
+                    this.cache_set(candidateLogical, candidatePhysical);
+                }
+            }
+            catch (error) {
+                // Link resolution failed - log warning but continue
+                const msg = error instanceof Error ? error.message : String(error);
+                errorStack.stack_push('warning', `Failed to check if '${candidatePhysical}' is a link: ${msg}. Treating as regular path.`);
+                // Assume it's not a link and continue
+                physicalCurrent = candidatePhysical;
+                logicalCurrent = candidateLogical;
+                this.cache_set(candidateLogical, candidatePhysical);
+            }
+        }
+        return Ok(physicalCurrent);
+    }
+    /**
+     * Checks if a path is a link and returns its target.
+     *
+     * Optimizes resolution by checking ListCache first. If the parent directory
+     * is cached, we can determine if the candidate is a link without an API call.
+     * Falls back to API (fetching all links in parent) if not cached.
+     *
+     * @param candidatePhysical - The physical path to check.
+     * @param candidateLogical - The logical path (used for cache lookup).
+     * @returns The link target if it's a link, null otherwise.
+     */
+    async link_checkAndResolve(candidatePhysical, candidateLogical) {
+        // 1. Fast Path: Check ListCache using logical path
+        // If we have the parent directory cached, we can check if the item is a link there.
+        const logicalParent = path.dirname(candidateLogical);
+        const itemName = path.basename(candidateLogical);
+        const listCache = listCache_get();
+        const cached = listCache.cache_get(logicalParent);
+        if (cached && cached.data && Array.isArray(cached.data)) {
+            // Look for the item in the cached listing
+            const item = cached.data.find((i) => i.name === itemName);
+            if (item) {
+                // Item found in cache!
+                if (item.type === 'link' && item.target) {
+                    return item.target;
+                }
+                // Found but not a link (or has no target) -> return null
+                return null;
+            }
+            // Item not found in cache. 
+            // It might be hidden or newly created. Fall back to API.
+        }
+        // 2. Slow Path: Check API using physical path
+        const parts = candidatePhysical.split('/');
+        parts.pop(); // Remove filename
+        const parentDir = parts.join('/') || '/';
+        const normalizedCandidate = candidatePhysical.startsWith('/')
+            ? candidatePhysical
+            : `/${candidatePhysical}`;
+        try {
+            const fetchOpts = { limit: 1000, offset: 0 };
+            const linksResult = await files_listAll(fetchOpts, 'links', parentDir);
+            if (linksResult && linksResult.tableData) {
+                for (const linkRaw of linksResult.tableData) {
+                    const linkFname = linkRaw.fname || '';
+                    const linkPath = linkRaw.path || '';
+                    const normalizedLinkFname = linkFname.startsWith('/')
+                        ? linkFname
+                        : `/${linkFname}`;
+                    if (normalizedLinkFname.endsWith('.chrislink')) {
+                        const logicalPath = normalizedLinkFname.slice(0, -10);
+                        if (logicalPath === normalizedCandidate) {
+                            const target = linkPath.startsWith('/') ? linkPath : `/${linkPath}`;
+                            return target;
+                        }
+                    }
+                }
+            }
+            return null;
+        }
+        catch (error) {
+            // Re-throw to be handled by caller
+            throw error;
+        }
+    }
+    /**
+     * Gets a cached mapping if it exists and hasn't expired.
+     *
+     * @param logicalPath - The logical path to look up.
+     * @returns The cached physical path, or null if not cached or expired.
+     */
+    cache_get(logicalPath) {
+        const cached = this.cache.get(logicalPath);
+        if (!cached) {
+            return null;
+        }
+        const now = Date.now();
+        const age = now - cached.timestamp;
+        if (age > cached.ttl) {
+            // Expired, remove from cache
+            this.cache.delete(logicalPath);
+            return null;
+        }
+        return cached.physicalPath;
+    }
+    /**
+     * Caches a logical-to-physical path mapping.
+     *
+     * @param logicalPath - The logical path.
+     * @param physicalPath - The corresponding physical path.
+     * @param ttl - Optional TTL in milliseconds (defaults to 30s).
+     */
+    cache_set(logicalPath, physicalPath, ttl = this.defaultTTL) {
+        this.cache.set(logicalPath, {
+            physicalPath,
+            timestamp: Date.now(),
+            ttl
+        });
+    }
+    /**
+     * Invalidates all cached mappings with a given logical path prefix.
+     *
+     * Call this when links are created/deleted/modified.
+     *
+     * @param logicalPathPrefix - The logical path prefix to invalidate.
+     *
+     * @example
+     * ```typescript
+     * // Link changed: /home/user/public → /SHARED becomes → /PUBLIC
+     * mapper.cache_invalidate('/home/user/public');
+     * // Invalidates:
+     * //   - /home/user/public
+     * //   - /home/user/public/feed_4
+     * //   - /home/user/public/feed_5
+     * //   - ... etc
+     * ```
+     */
+    cache_invalidate(logicalPathPrefix) {
+        const keysToDelete = [];
+        for (const [key] of this.cache) {
+            if (key === logicalPathPrefix || key.startsWith(logicalPathPrefix + '/')) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.cache.delete(key);
+        }
+    }
+    /**
+     * Clears all cached mappings.
+     */
+    cache_clear() {
+        this.cache.clear();
+        this.stats = { hits: 0, misses: 0 };
+    }
+    /**
+     * Gets cache statistics.
+     *
+     * @returns Cache statistics including hit rate and size.
+     */
+    stats_get() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total === 0 ? 0 : this.stats.hits / total;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            size: this.cache.size,
+            hitRate
+        };
+    }
+}
+PathMapper.instance = null;
+/**
+ * Convenience function to get the singleton PathMapper instance.
+ *
+ * @returns The singleton PathMapper instance.
+ */
+export function pathMapper_get() {
+    return PathMapper.instance_get();
+}

package/dist/plugins/pluginGroupHandler.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Handler for the plugin context command group.
+ *
+ * @module
+ */
+import { Command } from "commander";
+import { CLIoptions } from "../utils/cli.js";
+/**
+ * Handles commands related to groups of plugin contexts (computes, instances, parameters).
+ */
+export declare class PluginContextGroupHandler {
+    private baseGroupHandler;
+    private controller;
+    readonly assetName: string;
+    private constructor();
+    /**
+     * Factory method to create a new PluginContextGroupHandler instance.
+     *
+     * @param assetName - The type of plugin context to handle ('computesofplugin', 'instancesofplugin', 'parametersofplugin').
+     * @param id - Optional plugin ID. Defaults to current ChRIS plugin context.
+     * @returns A Promise resolving to a new PluginContextGroupHandler instance.
+     * @throws InitializationError if an unsupported asset type is provided.
+     */
+    static handler_create(assetName: string, id?: number | null): Promise<PluginContextGroupHandler>;
+    /**
+     * Lists plugin parameters in a "man page" style format.
+     * This is a specialized view for parameters that differs from the standard table view.
+     *
+     * @param options - CLI options for filtering.
+     */
+    parameters_listMan(options: CLIoptions): Promise<void>;
+    /**
+     * Lists available fields for the current plugin context resource.
+     */
+    parameters_fieldsList(): Promise<void>;
+    /**
+     * Sets up the Commander.js commands for plugin context group operations.
+     *
+     * @param program - The Commander.js program instance.
+     */
+    pluginContextGroupCommand_setup(program: Command): void;
+}