@nmakarov/cli-toolkit 0.16.0 → 0.21.0

package/dist/utils.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/utils.ts","../src/utils/date-utils.ts","../src/utils/fs-utils.ts","../src/utils/os-utils.ts","../src/utils/format-utils.ts","../src/utils/crypto-utils.ts"],"sourcesContent":["// Re-export everything from the utils module directory\nexport * from \"./utils/index.js\";\n\n","/**\n * Date/time utility functions for timestamp formatting and timezone conversions\n */\n\nexport interface DateFormatOptions {\n    timezone?: \"UTC\" | \"user\";\n    format?: \"iso\" | \"iso-date\" | \"iso-time\" | \"human\";\n}\n\n/**\n * Format a date string or Date object to ISO8601 format in specified timezone\n * Always returns UTC-based ISO strings (YYYY-MM-DDTHH:mm:ssZ) as internal representation\n * \n * @param value - Date object, ISO string, or timestamp\n * @param options - Formatting options\n * @returns ISO8601 formatted string\n */\nexport function formatDate(value: Date | string | number | undefined, options: DateFormatOptions = {}): string {\n    if (value === undefined || value === null) {\n        return \"\";\n    }\n\n    const { timezone = \"UTC\", format = \"iso\" } = options;\n    \n    let date: Date;\n    if (value instanceof Date) {\n        date = value;\n    } else if (typeof value === \"string\") {\n        date = new Date(value);\n    } else if (typeof value === \"number\") {\n        date = new Date(value);\n    } else {\n        return \"\";\n    }\n\n    if (isNaN(date.getTime())) {\n        return \"\";\n    }\n\n    // Format based on requested format\n    switch (format) {\n        case \"iso\":\n            // Full ISO8601: 2025-01-01T01:01:01Z\n            return date.toISOString();\n        \n        case \"iso-date\":\n            // Date only: 2025-01-01\n            return date.toISOString().split(\"T\")[0];\n        \n        case \"iso-time\":\n            // Time only: 01:01:01Z\n            return date.toISOString().split(\"T\")[1];\n        \n        case \"human\":\n            // Human-readable: Jan 1, 2025 01:01:01 UTC\n            if (timezone === \"user\") {\n                return date.toLocaleString();\n            }\n            return date.toUTCString();\n        \n        default:\n            return date.toISOString();\n    }\n}\n\n/**\n * Parse a date value and return ISO8601 string in UTC\n * This is the canonical format for internal storage\n * \n * @param value - Date object or string\n * @returns ISO8601 string in UTC timezone\n */\nexport function toISOString(value: Date | string | number | undefined): string {\n    return formatDate(value, { timezone: \"UTC\", format: \"iso\" });\n}\n\n/**\n * Get current timestamp as ISO8601 string in UTC\n * @returns Current time as ISO8601 string\n */\nexport function nowISO(): string {\n    return new Date().toISOString();\n}\n\n/**\n * Parse ISO8601 string to Date object\n * @param isoString - ISO8601 formatted string\n * @returns Date object\n */\nexport function fromISOString(isoString: string): Date {\n    return new Date(isoString);\n}\n\n/**\n * Calculate difference between two dates in various units\n * @param start - Start date (ISO string or Date)\n * @param end - End date (ISO string or Date)\n * @returns Object with duration in multiple units\n */\nexport function dateDiff(\n    start: Date | string,\n    end: Date | string\n): {\n    milliseconds: number;\n    seconds: number;\n    minutes: number;\n    hours: number;\n    days: number;\n} {\n    const startDate = start instanceof Date ? start : new Date(start);\n    const endDate = end instanceof Date ? end : new Date(end);\n    \n    const diffMs = endDate.getTime() - startDate.getTime();\n    \n    return {\n        milliseconds: diffMs,\n        seconds: Math.floor(diffMs / 1000),\n        minutes: Math.floor(diffMs / (1000 * 60)),\n        hours: Math.floor(diffMs / (1000 * 60 * 60)),\n        days: Math.floor(diffMs / (1000 * 60 * 60 * 24))\n    };\n}\n\n/**\n * Check if a folder name looks like an ISO8601 timestamp\n * Used to identify version folders vs regular folders\n * @param folderName - Folder name to check\n * @returns true if the folder name is a valid ISO8601 timestamp\n */\nexport function isTimestampFolder(folderName: string): boolean {\n    // Match ISO8601 format: YYYY-MM-DDTHH:mm:ssZ\n    const isoRegex = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|\\.\\d{3}Z)$/;\n    \n    if (!isoRegex.test(folderName)) {\n        return false;\n    }\n    \n    const date = new Date(folderName);\n    return !isNaN(date.getTime()) && date.getTime() > 0;\n}\n\n/**\n * Generate a new version name (ISO8601 timestamp)\n * If existingVersions provided, ensures the new version is later than all existing ones\n * @param existingVersions - Array of existing version timestamps\n * @returns New version timestamp that is unique and later than existing ones\n */\nexport function generateVersionName(existingVersions: string[] = []): string {\n    if (existingVersions.length === 0) {\n        // No existing versions, use current timestamp\n        const now = new Date();\n        return now.toISOString().split(\".\")[0] + \"Z\";\n    }\n    \n    // Find the maximum timestamp among all existing versions\n    const maxTimestamp = existingVersions.reduce((max, version) => {\n        const versionDate = new Date(version);\n        const maxDate = new Date(max);\n        return versionDate > maxDate ? version : max;\n    });\n    \n    // Increment by 1 second to ensure uniqueness\n    const maxDate = new Date(maxTimestamp);\n    const nextDate = new Date(maxDate.getTime() + 1000);\n    \n    return nextDate.toISOString().split(\".\")[0] + \"Z\";\n}\n\n","/**\n * File System Utilities\n * \n * Helper functions for file system operations like path management,\n * directory creation, and file type detection\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\nimport { fileURLToPath } from \"url\";\n\n/**\n * Ensure a directory path exists, creating it if necessary\n * Returns the absolute path\n */\nexport async function ensurePath(...pathParts: string[]): Promise<string> {\n    const fullPath = path.resolve(...pathParts);\n    \n    if (!fs.existsSync(fullPath)) {\n        await fs.promises.mkdir(fullPath, { recursive: true });\n    }\n    \n    return fullPath;\n}\n\n/**\n * Synchronous version of ensurePath\n */\nexport function ensurePathSync(...pathParts: string[]): string {\n    const fullPath = path.resolve(...pathParts);\n    \n    if (!fs.existsSync(fullPath)) {\n        fs.mkdirSync(fullPath, { recursive: true });\n    }\n    \n    return fullPath;\n}\n\n/**\n * Get file extension for a given data type\n */\nexport function getFileExtension(dataType: string): string {\n    switch (dataType) {\n        case \"json-array\":\n        case \"json-object\":\n            return \"json\";\n        case \"text\":\n            return \"txt\";\n        case \"xml\":\n            return \"xml\";\n        default:\n            return \"json\";\n    }\n}\n\n/**\n * Get __dirname equivalent for ES modules\n * \n * Returns the directory path of the module file\n * Useful for resolving relative paths in ES modules where __dirname is not available\n * \n * @param metaUrl - The import.meta.url from the calling module (must be passed from calling module)\n * @returns The directory path of the module\n * \n * @example\n * ```typescript\n * import { getDirname } from \"@nmakarov/cli-toolkit/utils\";\n * const __dirname = getDirname(import.meta.url);\n * ```\n */\nexport function getDirname(metaUrl: string | URL): string {\n    return path.dirname(fileURLToPath(metaUrl));\n}\n\n","/**\n * Operating System Utilities\n * \n * Helper functions for interacting with the operating system\n * to get system statistics and information\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\nimport { execSync } from \"child_process\";\n\n/**\n * Get free disk space for a given path (in bytes)\n * Returns null if unable to determine\n * Uses `df` command on Unix-like systems\n */\nexport function getFreeDiskSpace(targetPath: string): number | null {\n    try {\n        // If the target path doesn't exist, use its parent directory\n        let pathToCheck = targetPath;\n        if (!fs.existsSync(targetPath)) {\n            const parentDir = path.dirname(targetPath);\n            if (fs.existsSync(parentDir)) {\n                pathToCheck = parentDir;\n            } else {\n                // If parent doesn't exist either, use the root directory\n                pathToCheck = process.platform === \"win32\" ? \"C:\\\\\" : \"/\";\n            }\n        }\n\n        if (process.platform === \"win32\") {\n            // Windows: use wmic command\n            // Note: This is a simplified implementation, may need adjustments\n            return null; // TODO: Implement robust Windows support\n        } else {\n            // Unix-like systems: use df command\n            const stdout = execSync(`df -k \"${pathToCheck}\"`, { encoding: \"utf8\" });\n            const lines = stdout.trim().split(\"\\n\");\n            const parts = lines[1].split(/\\s+/); // second line, split on whitespace\n            const freeKb = parseInt(parts[3], 10); // 4th column is \"Available\"\n            return freeKb * 1024; // Convert to bytes\n        }\n    } catch (error) {\n        // Silently fail and return null\n        return null;\n    }\n}\n\n","/**\n * Formatting Utilities\n * \n * Helper functions for converting between different data formats\n * and human-readable representations\n */\n\n/**\n * Convert bytes to human-readable format (e.g., \"1.5 MB\")\n */\nexport function bytesToHumanReadable(bytes: number): string {\n    if (bytes === 0) return \"0 B\";\n    \n    const k = 1024;\n    const sizes = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\", \"PB\"];\n    const i = Math.floor(Math.log(bytes) / Math.log(k));\n    \n    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + \" \" + sizes[i];\n}\n\n/**\n * Convert human-readable format to bytes (e.g., \"1.5 MB\" -> 1572864)\n */\nexport function humanReadableToBytes(humanString: string): number {\n    const units: Record<string, number> = {\n        \"B\": 1,\n        \"KB\": 1024,\n        \"MB\": 1024 * 1024,\n        \"GB\": 1024 * 1024 * 1024,\n        \"TB\": 1024 * 1024 * 1024 * 1024,\n        \"PB\": 1024 * 1024 * 1024 * 1024 * 1024,\n    };\n    \n    const match = humanString.trim().match(/^([\\d.]+)\\s*([A-Z]+)$/i);\n    if (!match) {\n        throw new Error(`Invalid format: ${humanString}. Expected format like \"2MB\" or \"1.5 GB\"`);\n    }\n    \n    const value = parseFloat(match[1]);\n    const unit = match[2].toUpperCase();\n    \n    if (!units[unit]) {\n        throw new Error(`Unknown unit: ${unit}. Supported units: ${Object.keys(units).join(\", \")}`);\n    }\n    \n    return Math.round(value * units[unit]);\n}\n\n","/**\n * Cryptography Utilities\n * \n * Helper functions for hashing, encryption, and data masking\n */\n\nimport crypto from \"crypto\";\n\n/**\n * Calculate MD5 hash of a string (useful for content fingerprinting)\n */\nexport function md5(value: string): string {\n    return crypto.createHash(\"md5\").update(value).digest(\"hex\");\n}\n\n/**\n * Sanitize sensitive data by replacing with MD5 hash\n * Useful for logging sensitive information while maintaining traceability\n */\nexport function maskValue(value: string): string {\n    return `[md5:${md5(value)}]`;\n}\n\n"],"mappings":"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","names":["maxDate","path","fs","import_fs","import_path","fs","path","crypto"]}
+{"version":3,"sources":["../src/utils.ts","../src/utils/date-utils.ts","../src/utils/fs-utils.ts","../src/utils/os-utils.ts","../src/utils/format-utils.ts","../src/utils/crypto-utils.ts","../src/utils/core-utils.ts"],"sourcesContent":["// Re-export everything from the utils module directory\nexport * from \"./utils/index.js\";\n\n","/**\n * Date/time utility functions for timestamp formatting and timezone conversions\n */\n\nexport interface DateFormatOptions {\n    timezone?: \"UTC\" | \"user\";\n    format?: \"iso\" | \"iso-date\" | \"iso-time\" | \"human\";\n}\n\n/**\n * Format a date string or Date object to ISO8601 format in specified timezone\n * Always returns UTC-based ISO strings (YYYY-MM-DDTHH:mm:ssZ) as internal representation\n * \n * @param value - Date object, ISO string, or timestamp\n * @param options - Formatting options\n * @returns ISO8601 formatted string\n */\nexport function formatDate(value: Date | string | number | undefined, options: DateFormatOptions = {}): string {\n    if (value === undefined || value === null) {\n        return \"\";\n    }\n\n    const { timezone = \"UTC\", format = \"iso\" } = options;\n    \n    let date: Date;\n    if (value instanceof Date) {\n        date = value;\n    } else if (typeof value === \"string\") {\n        date = new Date(value);\n    } else if (typeof value === \"number\") {\n        date = new Date(value);\n    } else {\n        return \"\";\n    }\n\n    if (isNaN(date.getTime())) {\n        return \"\";\n    }\n\n    // Format based on requested format\n    switch (format) {\n        case \"iso\":\n            // Full ISO8601: 2025-01-01T01:01:01Z\n            return date.toISOString();\n        \n        case \"iso-date\":\n            // Date only: 2025-01-01\n            return date.toISOString().split(\"T\")[0];\n        \n        case \"iso-time\":\n            // Time only: 01:01:01Z\n            return date.toISOString().split(\"T\")[1];\n        \n        case \"human\":\n            // Human-readable: Jan 1, 2025 01:01:01 UTC\n            if (timezone === \"user\") {\n                return date.toLocaleString();\n            }\n            return date.toUTCString();\n        \n        default:\n            return date.toISOString();\n    }\n}\n\n/**\n * Parse a date value and return ISO8601 string in UTC\n * This is the canonical format for internal storage\n * \n * @param value - Date object or string\n * @returns ISO8601 string in UTC timezone\n */\nexport function toISOString(value: Date | string | number | undefined): string {\n    return formatDate(value, { timezone: \"UTC\", format: \"iso\" });\n}\n\n/**\n * Get current timestamp as ISO8601 string in UTC\n * @returns Current time as ISO8601 string\n */\nexport function nowISO(): string {\n    return new Date().toISOString();\n}\n\n/**\n * Parse ISO8601 string to Date object\n * @param isoString - ISO8601 formatted string\n * @returns Date object\n */\nexport function fromISOString(isoString: string): Date {\n    return new Date(isoString);\n}\n\n/**\n * Calculate difference between two dates in various units\n * @param start - Start date (ISO string or Date)\n * @param end - End date (ISO string or Date)\n * @returns Object with duration in multiple units\n */\nexport function dateDiff(\n    start: Date | string,\n    end: Date | string\n): {\n    milliseconds: number;\n    seconds: number;\n    minutes: number;\n    hours: number;\n    days: number;\n} {\n    const startDate = start instanceof Date ? start : new Date(start);\n    const endDate = end instanceof Date ? end : new Date(end);\n    \n    const diffMs = endDate.getTime() - startDate.getTime();\n    \n    return {\n        milliseconds: diffMs,\n        seconds: Math.floor(diffMs / 1000),\n        minutes: Math.floor(diffMs / (1000 * 60)),\n        hours: Math.floor(diffMs / (1000 * 60 * 60)),\n        days: Math.floor(diffMs / (1000 * 60 * 60 * 24))\n    };\n}\n\n/**\n * Check if a folder name looks like an ISO8601 timestamp\n * Used to identify version folders vs regular folders\n * @param folderName - Folder name to check\n * @returns true if the folder name is a valid ISO8601 timestamp\n */\nexport function isTimestampFolder(folderName: string): boolean {\n    // Match ISO8601 format: YYYY-MM-DDTHH:mm:ssZ\n    const isoRegex = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|\\.\\d{3}Z)$/;\n    \n    if (!isoRegex.test(folderName)) {\n        return false;\n    }\n    \n    const date = new Date(folderName);\n    return !isNaN(date.getTime()) && date.getTime() > 0;\n}\n\n/**\n * Generate a new version name (ISO8601 timestamp)\n * If existingVersions provided, ensures the new version is later than all existing ones\n * @param existingVersions - Array of existing version timestamps\n * @returns New version timestamp that is unique and later than existing ones\n */\nexport function generateVersionName(existingVersions: string[] = []): string {\n    if (existingVersions.length === 0) {\n        // No existing versions, use current timestamp\n        const now = new Date();\n        return now.toISOString().split(\".\")[0] + \"Z\";\n    }\n    \n    // Find the maximum timestamp among all existing versions\n    const maxTimestamp = existingVersions.reduce((max, version) => {\n        const versionDate = new Date(version);\n        const maxDate = new Date(max);\n        return versionDate > maxDate ? version : max;\n    });\n    \n    // Increment by 1 second to ensure uniqueness\n    const maxDate = new Date(maxTimestamp);\n    const nextDate = new Date(maxDate.getTime() + 1000);\n    \n    return nextDate.toISOString().split(\".\")[0] + \"Z\";\n}\n\n","/**\n * File System Utilities\n * \n * Helper functions for file system operations like path management,\n * directory creation, and file type detection\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\nimport { fileURLToPath } from \"url\";\n\n/**\n * Ensure a directory path exists, creating it if necessary\n * Returns the absolute path\n */\nexport async function ensurePath(...pathParts: string[]): Promise<string> {\n    const fullPath = path.resolve(...pathParts);\n    \n    if (!fs.existsSync(fullPath)) {\n        await fs.promises.mkdir(fullPath, { recursive: true });\n    }\n    \n    return fullPath;\n}\n\n/**\n * Synchronous version of ensurePath\n */\nexport function ensurePathSync(...pathParts: string[]): string {\n    const fullPath = path.resolve(...pathParts);\n    \n    if (!fs.existsSync(fullPath)) {\n        fs.mkdirSync(fullPath, { recursive: true });\n    }\n    \n    return fullPath;\n}\n\n/**\n * Get file extension for a given data type\n */\nexport function getFileExtension(dataType: string): string {\n    switch (dataType) {\n        case \"json-array\":\n        case \"json-object\":\n            return \"json\";\n        case \"text\":\n            return \"txt\";\n        case \"xml\":\n            return \"xml\";\n        default:\n            return \"json\";\n    }\n}\n\n/**\n * Get __dirname equivalent for ES modules\n * \n * Returns the directory path of the module file\n * Useful for resolving relative paths in ES modules where __dirname is not available\n * \n * @param metaUrl - The import.meta.url from the calling module (must be passed from calling module)\n * @returns The directory path of the module\n * \n * @example\n * ```typescript\n * import { getDirname } from \"@nmakarov/cli-toolkit/utils\";\n * const __dirname = getDirname(import.meta.url);\n * ```\n */\nexport function getDirname(metaUrl: string | URL): string {\n    return path.dirname(fileURLToPath(metaUrl));\n}\n\n","/**\n * Operating System Utilities\n * \n * Helper functions for interacting with the operating system\n * to get system statistics and information\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\nimport { execSync } from \"child_process\";\n\n/**\n * Get free disk space for a given path (in bytes)\n * Returns null if unable to determine\n * Uses `df` command on Unix-like systems\n */\nexport function getFreeDiskSpace(targetPath: string): number | null {\n    try {\n        // If the target path doesn't exist, use its parent directory\n        let pathToCheck = targetPath;\n        if (!fs.existsSync(targetPath)) {\n            const parentDir = path.dirname(targetPath);\n            if (fs.existsSync(parentDir)) {\n                pathToCheck = parentDir;\n            } else {\n                // If parent doesn't exist either, use the root directory\n                pathToCheck = process.platform === \"win32\" ? \"C:\\\\\" : \"/\";\n            }\n        }\n\n        if (process.platform === \"win32\") {\n            // Windows: use wmic command\n            // Note: This is a simplified implementation, may need adjustments\n            return null; // TODO: Implement robust Windows support\n        } else {\n            // Unix-like systems: use df command\n            const stdout = execSync(`df -k \"${pathToCheck}\"`, { encoding: \"utf8\" });\n            const lines = stdout.trim().split(\"\\n\");\n            const parts = lines[1].split(/\\s+/); // second line, split on whitespace\n            const freeKb = parseInt(parts[3], 10); // 4th column is \"Available\"\n            return freeKb * 1024; // Convert to bytes\n        }\n    } catch (error) {\n        // Silently fail and return null\n        return null;\n    }\n}\n\n","/**\n * Formatting Utilities\n * \n * Helper functions for converting between different data formats\n * and human-readable representations\n */\n\n/**\n * Convert bytes to human-readable format (e.g., \"1.5 MB\")\n */\nexport function bytesToHumanReadable(bytes: number): string {\n    if (bytes === 0) return \"0 B\";\n    \n    const k = 1024;\n    const sizes = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\", \"PB\"];\n    const i = Math.floor(Math.log(bytes) / Math.log(k));\n    \n    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + \" \" + sizes[i];\n}\n\n/**\n * Convert human-readable format to bytes (e.g., \"1.5 MB\" -> 1572864)\n */\nexport function humanReadableToBytes(humanString: string): number {\n    const units: Record<string, number> = {\n        \"B\": 1,\n        \"KB\": 1024,\n        \"MB\": 1024 * 1024,\n        \"GB\": 1024 * 1024 * 1024,\n        \"TB\": 1024 * 1024 * 1024 * 1024,\n        \"PB\": 1024 * 1024 * 1024 * 1024 * 1024,\n    };\n    \n    const match = humanString.trim().match(/^([\\d.]+)\\s*([A-Z]+)$/i);\n    if (!match) {\n        throw new Error(`Invalid format: ${humanString}. Expected format like \"2MB\" or \"1.5 GB\"`);\n    }\n    \n    const value = parseFloat(match[1]);\n    const unit = match[2].toUpperCase();\n    \n    if (!units[unit]) {\n        throw new Error(`Unknown unit: ${unit}. Supported units: ${Object.keys(units).join(\", \")}`);\n    }\n    \n    return Math.round(value * units[unit]);\n}\n\n","/**\n * Cryptography Utilities\n * \n * Helper functions for hashing, encryption, and data masking\n */\n\nimport crypto from \"crypto\";\n\n/**\n * Calculate MD5 hash of a string (useful for content fingerprinting)\n */\nexport function md5(value: string): string {\n    return crypto.createHash(\"md5\").update(value).digest(\"hex\");\n}\n\n/**\n * Sanitize sensitive data by replacing with MD5 hash\n * Useful for logging sensitive information while maintaining traceability\n */\nexport function maskValue(value: string): string {\n    return `[md5:${md5(value)}]`;\n}\n\n","/**\n * Core lightweight utilities\n */\n\nexport function sleepMs(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nexport function toJsonColumn(value: any): string | null {\n    if (value === undefined || value === null) return null;\n    return JSON.stringify(value);\n}\n"],"mappings":"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","names":["maxDate","path","fs","import_fs","import_path","fs","path","crypto"]}

package/dist/utils.js

@@ -178,6 +178,15 @@ function md5(value) {
 function maskValue(value) {
   return `[md5:${md5(value)}]`;
 }
+
+// src/utils/core-utils.ts
+function sleepMs(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function toJsonColumn(value) {
+  if (value === void 0 || value === null) return null;
+  return JSON.stringify(value);
+}
 export {
   bytesToHumanReadable,
   dateDiff,
@@ -194,6 +203,8 @@ export {
   maskValue,
   md5,
   nowISO,
-  toISOString
+  sleepMs,
+  toISOString,
+  toJsonColumn
 };
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/utils/date-utils.ts","../src/utils/fs-utils.ts","../src/utils/os-utils.ts","../src/utils/format-utils.ts","../src/utils/crypto-utils.ts"],"sourcesContent":["/**\n * Date/time utility functions for timestamp formatting and timezone conversions\n */\n\nexport interface DateFormatOptions {\n    timezone?: \"UTC\" | \"user\";\n    format?: \"iso\" | \"iso-date\" | \"iso-time\" | \"human\";\n}\n\n/**\n * Format a date string or Date object to ISO8601 format in specified timezone\n * Always returns UTC-based ISO strings (YYYY-MM-DDTHH:mm:ssZ) as internal representation\n * \n * @param value - Date object, ISO string, or timestamp\n * @param options - Formatting options\n * @returns ISO8601 formatted string\n */\nexport function formatDate(value: Date | string | number | undefined, options: DateFormatOptions = {}): string {\n    if (value === undefined || value === null) {\n        return \"\";\n    }\n\n    const { timezone = \"UTC\", format = \"iso\" } = options;\n    \n    let date: Date;\n    if (value instanceof Date) {\n        date = value;\n    } else if (typeof value === \"string\") {\n        date = new Date(value);\n    } else if (typeof value === \"number\") {\n        date = new Date(value);\n    } else {\n        return \"\";\n    }\n\n    if (isNaN(date.getTime())) {\n        return \"\";\n    }\n\n    // Format based on requested format\n    switch (format) {\n        case \"iso\":\n            // Full ISO8601: 2025-01-01T01:01:01Z\n            return date.toISOString();\n        \n        case \"iso-date\":\n            // Date only: 2025-01-01\n            return date.toISOString().split(\"T\")[0];\n        \n        case \"iso-time\":\n            // Time only: 01:01:01Z\n            return date.toISOString().split(\"T\")[1];\n        \n        case \"human\":\n            // Human-readable: Jan 1, 2025 01:01:01 UTC\n            if (timezone === \"user\") {\n                return date.toLocaleString();\n            }\n            return date.toUTCString();\n        \n        default:\n            return date.toISOString();\n    }\n}\n\n/**\n * Parse a date value and return ISO8601 string in UTC\n * This is the canonical format for internal storage\n * \n * @param value - Date object or string\n * @returns ISO8601 string in UTC timezone\n */\nexport function toISOString(value: Date | string | number | undefined): string {\n    return formatDate(value, { timezone: \"UTC\", format: \"iso\" });\n}\n\n/**\n * Get current timestamp as ISO8601 string in UTC\n * @returns Current time as ISO8601 string\n */\nexport function nowISO(): string {\n    return new Date().toISOString();\n}\n\n/**\n * Parse ISO8601 string to Date object\n * @param isoString - ISO8601 formatted string\n * @returns Date object\n */\nexport function fromISOString(isoString: string): Date {\n    return new Date(isoString);\n}\n\n/**\n * Calculate difference between two dates in various units\n * @param start - Start date (ISO string or Date)\n * @param end - End date (ISO string or Date)\n * @returns Object with duration in multiple units\n */\nexport function dateDiff(\n    start: Date | string,\n    end: Date | string\n): {\n    milliseconds: number;\n    seconds: number;\n    minutes: number;\n    hours: number;\n    days: number;\n} {\n    const startDate = start instanceof Date ? start : new Date(start);\n    const endDate = end instanceof Date ? end : new Date(end);\n    \n    const diffMs = endDate.getTime() - startDate.getTime();\n    \n    return {\n        milliseconds: diffMs,\n        seconds: Math.floor(diffMs / 1000),\n        minutes: Math.floor(diffMs / (1000 * 60)),\n        hours: Math.floor(diffMs / (1000 * 60 * 60)),\n        days: Math.floor(diffMs / (1000 * 60 * 60 * 24))\n    };\n}\n\n/**\n * Check if a folder name looks like an ISO8601 timestamp\n * Used to identify version folders vs regular folders\n * @param folderName - Folder name to check\n * @returns true if the folder name is a valid ISO8601 timestamp\n */\nexport function isTimestampFolder(folderName: string): boolean {\n    // Match ISO8601 format: YYYY-MM-DDTHH:mm:ssZ\n    const isoRegex = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|\\.\\d{3}Z)$/;\n    \n    if (!isoRegex.test(folderName)) {\n        return false;\n    }\n    \n    const date = new Date(folderName);\n    return !isNaN(date.getTime()) && date.getTime() > 0;\n}\n\n/**\n * Generate a new version name (ISO8601 timestamp)\n * If existingVersions provided, ensures the new version is later than all existing ones\n * @param existingVersions - Array of existing version timestamps\n * @returns New version timestamp that is unique and later than existing ones\n */\nexport function generateVersionName(existingVersions: string[] = []): string {\n    if (existingVersions.length === 0) {\n        // No existing versions, use current timestamp\n        const now = new Date();\n        return now.toISOString().split(\".\")[0] + \"Z\";\n    }\n    \n    // Find the maximum timestamp among all existing versions\n    const maxTimestamp = existingVersions.reduce((max, version) => {\n        const versionDate = new Date(version);\n        const maxDate = new Date(max);\n        return versionDate > maxDate ? version : max;\n    });\n    \n    // Increment by 1 second to ensure uniqueness\n    const maxDate = new Date(maxTimestamp);\n    const nextDate = new Date(maxDate.getTime() + 1000);\n    \n    return nextDate.toISOString().split(\".\")[0] + \"Z\";\n}\n\n","/**\n * File System Utilities\n * \n * Helper functions for file system operations like path management,\n * directory creation, and file type detection\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\nimport { fileURLToPath } from \"url\";\n\n/**\n * Ensure a directory path exists, creating it if necessary\n * Returns the absolute path\n */\nexport async function ensurePath(...pathParts: string[]): Promise<string> {\n    const fullPath = path.resolve(...pathParts);\n    \n    if (!fs.existsSync(fullPath)) {\n        await fs.promises.mkdir(fullPath, { recursive: true });\n    }\n    \n    return fullPath;\n}\n\n/**\n * Synchronous version of ensurePath\n */\nexport function ensurePathSync(...pathParts: string[]): string {\n    const fullPath = path.resolve(...pathParts);\n    \n    if (!fs.existsSync(fullPath)) {\n        fs.mkdirSync(fullPath, { recursive: true });\n    }\n    \n    return fullPath;\n}\n\n/**\n * Get file extension for a given data type\n */\nexport function getFileExtension(dataType: string): string {\n    switch (dataType) {\n        case \"json-array\":\n        case \"json-object\":\n            return \"json\";\n        case \"text\":\n            return \"txt\";\n        case \"xml\":\n            return \"xml\";\n        default:\n            return \"json\";\n    }\n}\n\n/**\n * Get __dirname equivalent for ES modules\n * \n * Returns the directory path of the module file\n * Useful for resolving relative paths in ES modules where __dirname is not available\n * \n * @param metaUrl - The import.meta.url from the calling module (must be passed from calling module)\n * @returns The directory path of the module\n * \n * @example\n * ```typescript\n * import { getDirname } from \"@nmakarov/cli-toolkit/utils\";\n * const __dirname = getDirname(import.meta.url);\n * ```\n */\nexport function getDirname(metaUrl: string | URL): string {\n    return path.dirname(fileURLToPath(metaUrl));\n}\n\n","/**\n * Operating System Utilities\n * \n * Helper functions for interacting with the operating system\n * to get system statistics and information\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\nimport { execSync } from \"child_process\";\n\n/**\n * Get free disk space for a given path (in bytes)\n * Returns null if unable to determine\n * Uses `df` command on Unix-like systems\n */\nexport function getFreeDiskSpace(targetPath: string): number | null {\n    try {\n        // If the target path doesn't exist, use its parent directory\n        let pathToCheck = targetPath;\n        if (!fs.existsSync(targetPath)) {\n            const parentDir = path.dirname(targetPath);\n            if (fs.existsSync(parentDir)) {\n                pathToCheck = parentDir;\n            } else {\n                // If parent doesn't exist either, use the root directory\n                pathToCheck = process.platform === \"win32\" ? \"C:\\\\\" : \"/\";\n            }\n        }\n\n        if (process.platform === \"win32\") {\n            // Windows: use wmic command\n            // Note: This is a simplified implementation, may need adjustments\n            return null; // TODO: Implement robust Windows support\n        } else {\n            // Unix-like systems: use df command\n            const stdout = execSync(`df -k \"${pathToCheck}\"`, { encoding: \"utf8\" });\n            const lines = stdout.trim().split(\"\\n\");\n            const parts = lines[1].split(/\\s+/); // second line, split on whitespace\n            const freeKb = parseInt(parts[3], 10); // 4th column is \"Available\"\n            return freeKb * 1024; // Convert to bytes\n        }\n    } catch (error) {\n        // Silently fail and return null\n        return null;\n    }\n}\n\n","/**\n * Formatting Utilities\n * \n * Helper functions for converting between different data formats\n * and human-readable representations\n */\n\n/**\n * Convert bytes to human-readable format (e.g., \"1.5 MB\")\n */\nexport function bytesToHumanReadable(bytes: number): string {\n    if (bytes === 0) return \"0 B\";\n    \n    const k = 1024;\n    const sizes = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\", \"PB\"];\n    const i = Math.floor(Math.log(bytes) / Math.log(k));\n    \n    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + \" \" + sizes[i];\n}\n\n/**\n * Convert human-readable format to bytes (e.g., \"1.5 MB\" -> 1572864)\n */\nexport function humanReadableToBytes(humanString: string): number {\n    const units: Record<string, number> = {\n        \"B\": 1,\n        \"KB\": 1024,\n        \"MB\": 1024 * 1024,\n        \"GB\": 1024 * 1024 * 1024,\n        \"TB\": 1024 * 1024 * 1024 * 1024,\n        \"PB\": 1024 * 1024 * 1024 * 1024 * 1024,\n    };\n    \n    const match = humanString.trim().match(/^([\\d.]+)\\s*([A-Z]+)$/i);\n    if (!match) {\n        throw new Error(`Invalid format: ${humanString}. Expected format like \"2MB\" or \"1.5 GB\"`);\n    }\n    \n    const value = parseFloat(match[1]);\n    const unit = match[2].toUpperCase();\n    \n    if (!units[unit]) {\n        throw new Error(`Unknown unit: ${unit}. Supported units: ${Object.keys(units).join(\", \")}`);\n    }\n    \n    return Math.round(value * units[unit]);\n}\n\n","/**\n * Cryptography Utilities\n * \n * Helper functions for hashing, encryption, and data masking\n */\n\nimport crypto from \"crypto\";\n\n/**\n * Calculate MD5 hash of a string (useful for content fingerprinting)\n */\nexport function md5(value: string): string {\n    return crypto.createHash(\"md5\").update(value).digest(\"hex\");\n}\n\n/**\n * Sanitize sensitive data by replacing with MD5 hash\n * Useful for logging sensitive information while maintaining traceability\n */\nexport function maskValue(value: string): string {\n    return `[md5:${md5(value)}]`;\n}\n\n"],"mappings":"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","names":["maxDate","fs","path"]}
+{"version":3,"sources":["../src/utils/date-utils.ts","../src/utils/fs-utils.ts","../src/utils/os-utils.ts","../src/utils/format-utils.ts","../src/utils/crypto-utils.ts","../src/utils/core-utils.ts"],"sourcesContent":["/**\n * Date/time utility functions for timestamp formatting and timezone conversions\n */\n\nexport interface DateFormatOptions {\n    timezone?: \"UTC\" | \"user\";\n    format?: \"iso\" | \"iso-date\" | \"iso-time\" | \"human\";\n}\n\n/**\n * Format a date string or Date object to ISO8601 format in specified timezone\n * Always returns UTC-based ISO strings (YYYY-MM-DDTHH:mm:ssZ) as internal representation\n * \n * @param value - Date object, ISO string, or timestamp\n * @param options - Formatting options\n * @returns ISO8601 formatted string\n */\nexport function formatDate(value: Date | string | number | undefined, options: DateFormatOptions = {}): string {\n    if (value === undefined || value === null) {\n        return \"\";\n    }\n\n    const { timezone = \"UTC\", format = \"iso\" } = options;\n    \n    let date: Date;\n    if (value instanceof Date) {\n        date = value;\n    } else if (typeof value === \"string\") {\n        date = new Date(value);\n    } else if (typeof value === \"number\") {\n        date = new Date(value);\n    } else {\n        return \"\";\n    }\n\n    if (isNaN(date.getTime())) {\n        return \"\";\n    }\n\n    // Format based on requested format\n    switch (format) {\n        case \"iso\":\n            // Full ISO8601: 2025-01-01T01:01:01Z\n            return date.toISOString();\n        \n        case \"iso-date\":\n            // Date only: 2025-01-01\n            return date.toISOString().split(\"T\")[0];\n        \n        case \"iso-time\":\n            // Time only: 01:01:01Z\n            return date.toISOString().split(\"T\")[1];\n        \n        case \"human\":\n            // Human-readable: Jan 1, 2025 01:01:01 UTC\n            if (timezone === \"user\") {\n                return date.toLocaleString();\n            }\n            return date.toUTCString();\n        \n        default:\n            return date.toISOString();\n    }\n}\n\n/**\n * Parse a date value and return ISO8601 string in UTC\n * This is the canonical format for internal storage\n * \n * @param value - Date object or string\n * @returns ISO8601 string in UTC timezone\n */\nexport function toISOString(value: Date | string | number | undefined): string {\n    return formatDate(value, { timezone: \"UTC\", format: \"iso\" });\n}\n\n/**\n * Get current timestamp as ISO8601 string in UTC\n * @returns Current time as ISO8601 string\n */\nexport function nowISO(): string {\n    return new Date().toISOString();\n}\n\n/**\n * Parse ISO8601 string to Date object\n * @param isoString - ISO8601 formatted string\n * @returns Date object\n */\nexport function fromISOString(isoString: string): Date {\n    return new Date(isoString);\n}\n\n/**\n * Calculate difference between two dates in various units\n * @param start - Start date (ISO string or Date)\n * @param end - End date (ISO string or Date)\n * @returns Object with duration in multiple units\n */\nexport function dateDiff(\n    start: Date | string,\n    end: Date | string\n): {\n    milliseconds: number;\n    seconds: number;\n    minutes: number;\n    hours: number;\n    days: number;\n} {\n    const startDate = start instanceof Date ? start : new Date(start);\n    const endDate = end instanceof Date ? end : new Date(end);\n    \n    const diffMs = endDate.getTime() - startDate.getTime();\n    \n    return {\n        milliseconds: diffMs,\n        seconds: Math.floor(diffMs / 1000),\n        minutes: Math.floor(diffMs / (1000 * 60)),\n        hours: Math.floor(diffMs / (1000 * 60 * 60)),\n        days: Math.floor(diffMs / (1000 * 60 * 60 * 24))\n    };\n}\n\n/**\n * Check if a folder name looks like an ISO8601 timestamp\n * Used to identify version folders vs regular folders\n * @param folderName - Folder name to check\n * @returns true if the folder name is a valid ISO8601 timestamp\n */\nexport function isTimestampFolder(folderName: string): boolean {\n    // Match ISO8601 format: YYYY-MM-DDTHH:mm:ssZ\n    const isoRegex = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|\\.\\d{3}Z)$/;\n    \n    if (!isoRegex.test(folderName)) {\n        return false;\n    }\n    \n    const date = new Date(folderName);\n    return !isNaN(date.getTime()) && date.getTime() > 0;\n}\n\n/**\n * Generate a new version name (ISO8601 timestamp)\n * If existingVersions provided, ensures the new version is later than all existing ones\n * @param existingVersions - Array of existing version timestamps\n * @returns New version timestamp that is unique and later than existing ones\n */\nexport function generateVersionName(existingVersions: string[] = []): string {\n    if (existingVersions.length === 0) {\n        // No existing versions, use current timestamp\n        const now = new Date();\n        return now.toISOString().split(\".\")[0] + \"Z\";\n    }\n    \n    // Find the maximum timestamp among all existing versions\n    const maxTimestamp = existingVersions.reduce((max, version) => {\n        const versionDate = new Date(version);\n        const maxDate = new Date(max);\n        return versionDate > maxDate ? version : max;\n    });\n    \n    // Increment by 1 second to ensure uniqueness\n    const maxDate = new Date(maxTimestamp);\n    const nextDate = new Date(maxDate.getTime() + 1000);\n    \n    return nextDate.toISOString().split(\".\")[0] + \"Z\";\n}\n\n","/**\n * File System Utilities\n * \n * Helper functions for file system operations like path management,\n * directory creation, and file type detection\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\nimport { fileURLToPath } from \"url\";\n\n/**\n * Ensure a directory path exists, creating it if necessary\n * Returns the absolute path\n */\nexport async function ensurePath(...pathParts: string[]): Promise<string> {\n    const fullPath = path.resolve(...pathParts);\n    \n    if (!fs.existsSync(fullPath)) {\n        await fs.promises.mkdir(fullPath, { recursive: true });\n    }\n    \n    return fullPath;\n}\n\n/**\n * Synchronous version of ensurePath\n */\nexport function ensurePathSync(...pathParts: string[]): string {\n    const fullPath = path.resolve(...pathParts);\n    \n    if (!fs.existsSync(fullPath)) {\n        fs.mkdirSync(fullPath, { recursive: true });\n    }\n    \n    return fullPath;\n}\n\n/**\n * Get file extension for a given data type\n */\nexport function getFileExtension(dataType: string): string {\n    switch (dataType) {\n        case \"json-array\":\n        case \"json-object\":\n            return \"json\";\n        case \"text\":\n            return \"txt\";\n        case \"xml\":\n            return \"xml\";\n        default:\n            return \"json\";\n    }\n}\n\n/**\n * Get __dirname equivalent for ES modules\n * \n * Returns the directory path of the module file\n * Useful for resolving relative paths in ES modules where __dirname is not available\n * \n * @param metaUrl - The import.meta.url from the calling module (must be passed from calling module)\n * @returns The directory path of the module\n * \n * @example\n * ```typescript\n * import { getDirname } from \"@nmakarov/cli-toolkit/utils\";\n * const __dirname = getDirname(import.meta.url);\n * ```\n */\nexport function getDirname(metaUrl: string | URL): string {\n    return path.dirname(fileURLToPath(metaUrl));\n}\n\n","/**\n * Operating System Utilities\n * \n * Helper functions for interacting with the operating system\n * to get system statistics and information\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\nimport { execSync } from \"child_process\";\n\n/**\n * Get free disk space for a given path (in bytes)\n * Returns null if unable to determine\n * Uses `df` command on Unix-like systems\n */\nexport function getFreeDiskSpace(targetPath: string): number | null {\n    try {\n        // If the target path doesn't exist, use its parent directory\n        let pathToCheck = targetPath;\n        if (!fs.existsSync(targetPath)) {\n            const parentDir = path.dirname(targetPath);\n            if (fs.existsSync(parentDir)) {\n                pathToCheck = parentDir;\n            } else {\n                // If parent doesn't exist either, use the root directory\n                pathToCheck = process.platform === \"win32\" ? \"C:\\\\\" : \"/\";\n            }\n        }\n\n        if (process.platform === \"win32\") {\n            // Windows: use wmic command\n            // Note: This is a simplified implementation, may need adjustments\n            return null; // TODO: Implement robust Windows support\n        } else {\n            // Unix-like systems: use df command\n            const stdout = execSync(`df -k \"${pathToCheck}\"`, { encoding: \"utf8\" });\n            const lines = stdout.trim().split(\"\\n\");\n            const parts = lines[1].split(/\\s+/); // second line, split on whitespace\n            const freeKb = parseInt(parts[3], 10); // 4th column is \"Available\"\n            return freeKb * 1024; // Convert to bytes\n        }\n    } catch (error) {\n        // Silently fail and return null\n        return null;\n    }\n}\n\n","/**\n * Formatting Utilities\n * \n * Helper functions for converting between different data formats\n * and human-readable representations\n */\n\n/**\n * Convert bytes to human-readable format (e.g., \"1.5 MB\")\n */\nexport function bytesToHumanReadable(bytes: number): string {\n    if (bytes === 0) return \"0 B\";\n    \n    const k = 1024;\n    const sizes = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\", \"PB\"];\n    const i = Math.floor(Math.log(bytes) / Math.log(k));\n    \n    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + \" \" + sizes[i];\n}\n\n/**\n * Convert human-readable format to bytes (e.g., \"1.5 MB\" -> 1572864)\n */\nexport function humanReadableToBytes(humanString: string): number {\n    const units: Record<string, number> = {\n        \"B\": 1,\n        \"KB\": 1024,\n        \"MB\": 1024 * 1024,\n        \"GB\": 1024 * 1024 * 1024,\n        \"TB\": 1024 * 1024 * 1024 * 1024,\n        \"PB\": 1024 * 1024 * 1024 * 1024 * 1024,\n    };\n    \n    const match = humanString.trim().match(/^([\\d.]+)\\s*([A-Z]+)$/i);\n    if (!match) {\n        throw new Error(`Invalid format: ${humanString}. Expected format like \"2MB\" or \"1.5 GB\"`);\n    }\n    \n    const value = parseFloat(match[1]);\n    const unit = match[2].toUpperCase();\n    \n    if (!units[unit]) {\n        throw new Error(`Unknown unit: ${unit}. Supported units: ${Object.keys(units).join(\", \")}`);\n    }\n    \n    return Math.round(value * units[unit]);\n}\n\n","/**\n * Cryptography Utilities\n * \n * Helper functions for hashing, encryption, and data masking\n */\n\nimport crypto from \"crypto\";\n\n/**\n * Calculate MD5 hash of a string (useful for content fingerprinting)\n */\nexport function md5(value: string): string {\n    return crypto.createHash(\"md5\").update(value).digest(\"hex\");\n}\n\n/**\n * Sanitize sensitive data by replacing with MD5 hash\n * Useful for logging sensitive information while maintaining traceability\n */\nexport function maskValue(value: string): string {\n    return `[md5:${md5(value)}]`;\n}\n\n","/**\n * Core lightweight utilities\n */\n\nexport function sleepMs(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nexport function toJsonColumn(value: any): string | null {\n    if (value === undefined || value === null) return null;\n    return JSON.stringify(value);\n}\n"],"mappings":"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","names":["maxDate","fs","path"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmakarov/cli-toolkit",
-  "version": "0.16.0",
+  "version": "0.21.0",
   "description": "A comprehensive toolkit for building CLI applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -67,20 +67,32 @@
       "import": "./dist/db.js",
       "require": "./dist/db.cjs"
     },
+    "./tasks": {
+      "types": "./dist/tasks.d.ts",
+      "import": "./dist/tasks.js",
+      "require": "./dist/tasks.cjs"
+    },
     "./utils": {
       "types": "./dist/utils.d.ts",
       "import": "./dist/utils.js",
       "require": "./dist/utils.cjs"
     }
   },
+  "bin": {
+    "cli-runner": "./dist/cli-runner.js"
+  },
   "scripts": {
+    "ssm:list": "tsx scripts/ssm/ssm-admin.ts list",
+    "ssm:get": "tsx scripts/ssm/ssm-admin.ts get",
+    "ssm:put": "tsx scripts/ssm/ssm-admin.ts put",
+    "ssm:pull": "tsx scripts/ssm/ssm-pull.ts",
     "build": "tsup && node scripts/fix-cjs-esm-deps.js",
     "dev": "tsup --watch",
     "test": "vitest",
     "test:watch": "vitest --watch",
     "test:coverage": "vitest --coverage",
     "test:coverage:open": "vitest --coverage && open coverage/index.html",
-    "test:ci": "vitest run src/args/tests/args.ci.test.ts src/params/tests/params.ci.test.ts src/errors/tests/errors.ci.test.ts src/screen/tests/screen.ci.test.ts src/logger/tests/logger.ci.test.ts src/filedatabase/tests/filestore.ci.test.ts src/filedatabase/tests/synopsis-functions.ci.test.ts src/http-client/tests/http-client.ci.test.ts src/http-client2/tests/http-client2.ci.test.ts src/mock-server/tests/mock-server.ci.test.ts src/db/tests/db.ci.test.ts src/utils/tests/format-utils.ci.test.ts src/utils/tests/date-utils.ci.test.ts src/utils/tests/crypto-utils.ci.test.ts src/utils/tests/fs-utils.ci.test.ts src/utils/tests/os-utils.ci.test.ts src/init/tests/init.ci.test.ts --coverage",
+    "test:ci": "vitest run src/args/tests/args.ci.test.ts src/params/tests/params.ci.test.ts src/errors/tests/errors.ci.test.ts src/screen/tests/screen.ci.test.ts src/logger/tests/logger.ci.test.ts src/filedatabase/tests/filestore.ci.test.ts src/filedatabase/tests/synopsis-functions.ci.test.ts src/http-client/tests/http-client.ci.test.ts src/http-client2/tests/http-client2.ci.test.ts src/mock-server/tests/mock-server.ci.test.ts src/mock-server/tests/mock-storage.ci.test.ts src/db/tests/db.ci.test.ts src/utils/tests/format-utils.ci.test.ts src/utils/tests/date-utils.ci.test.ts src/utils/tests/crypto-utils.ci.test.ts src/utils/tests/fs-utils.ci.test.ts src/utils/tests/os-utils.ci.test.ts src/init/tests/init.ci.test.ts --coverage",
     "test:args": "vitest run src/args/tests",
     "test:args:ci": "vitest run src/args/tests/args.ci.test.ts --coverage",
     "test:params": "vitest run src/params/tests",
@@ -101,7 +113,7 @@
     "test:http-client2": "vitest run src/http-client2/tests",
     "test:http-client2:ci": "vitest run src/http-client2/tests/http-client2.ci.test.ts --coverage",
     "test:mock-server": "vitest run src/mock-server/tests",
-    "test:mock-server:ci": "vitest run src/mock-server/tests/mock-server.ci.test.ts --coverage",
+    "test:mock-server:ci": "vitest run src/mock-server/tests/mock-server.ci.test.ts src/mock-server/tests/mock-storage.ci.test.ts --coverage",
     "test:mock-server:coverage": "vitest run src/mock-server/tests --coverage",
     "test:db": "vitest run src/db/tests",
     "test:db:ci": "vitest run src/db/tests/db.ci.test.ts --coverage",
@@ -143,6 +155,7 @@
   },
   "files": [
     "dist/",
+    "scripts/ssm/",
     "README.md",
     "LICENSE"
   ],
@@ -155,11 +168,13 @@
     "eslint": "^9.38.0",
     "prettier": "^3.6.2",
     "tsup": "^8.5.0",
+    "tsx": "^4.20.0",
     "typedoc": "^0.28.14",
     "typescript": "^5.9.3",
     "vitest": "^4.0.3"
   },
   "dependencies": {
+    "@aws-sdk/client-ssm": "^3.750.0",
     "@types/joi": "^17.2.3",
     "axios": "^1.6.0",
     "chalk": "^4.1.2",
@@ -168,7 +183,8 @@
     "joi": "^18.0.1",
     "knex": "^3.1.0",
     "morgan": "^1.10.0",
-    "mysql": "^2.18.1"
+    "mysql": "^2.18.1",
+    "pg": "^8.20.0"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -176,7 +192,6 @@
   "peerDependencies": {
     "ink": "^4.0.0",
     "mysql2": "^3.0.0",
-    "pg": "^8.16.3",
     "react": "^18.0.0"
   },
   "peerDependenciesMeta": {

package/scripts/ssm/parse-cli.ts

@@ -0,0 +1,35 @@
+/**
+ * Minimal argv parser: supports --key=value and --key value (boolean if no value).
+ */
+export function parseCli(argv: string[]): { _: string[]; flags: Record<string, string | boolean> } {
+    const flags: Record<string, string | boolean> = {};
+    const rest: string[] = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith("--")) {
+            rest.push(a);
+            continue;
+        }
+        const body = a.slice(2);
+        if (body.includes("=")) {
+            const eq = body.indexOf("=");
+            const k = body.slice(0, eq);
+            const v = body.slice(eq + 1);
+            flags[k] = v;
+            continue;
+        }
+        const k = body;
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            flags[k] = next;
+            i++;
+        } else {
+            flags[k] = true;
+        }
+    }
+    return { _: rest, flags };
+}
+
+export function getRegion(): string {
+    return process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || "ca-central-1";
+}

package/scripts/ssm/ssm-admin.ts

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Local admin CLI for SSM Parameter Store (uses your workstation AWS credentials / profile).
+ *
+ * Prerequisites: IAM permission for ssm:Get*, ssm:PutParameter, ssm:DeleteParameter on your parameters
+ * (and kms:Decrypt/Encrypt if you use SecureString).
+ *
+ * Run from this package root (`subprojects/cli-toolkit`):
+ *
+ *   npx tsx scripts/ssm/ssm-admin.ts list --prefix /mlsfarm/tf3/
+ *   npm run ssm:list -- --prefix /mlsfarm/tf3/
+ *
+ * Or from a project that depends on `@nmakarov/cli-toolkit` (after a release that ships `scripts/ssm/`):
+ *
+ *   npx tsx node_modules/@nmakarov/cli-toolkit/scripts/ssm/ssm-admin.ts list --prefix /mlsfarm/tf3/
+ *
+ * Optional: AWS_REGION, AWS_PROFILE (standard SDK env).
+ */
+
+import {
+    SSMClient,
+    GetParametersByPathCommand,
+    GetParameterCommand,
+    PutParameterCommand,
+    DeleteParameterCommand,
+} from "@aws-sdk/client-ssm";
+import { parseCli, getRegion } from "./parse-cli.js";
+
+function usage(): void {
+    console.error(`Usage:
+  npx tsx scripts/ssm/ssm-admin.ts list   --prefix /path/ [--recursive false]
+  npx tsx scripts/ssm/ssm-admin.ts get    --name /path/KEY
+  npx tsx scripts/ssm/ssm-admin.ts put    --name /path/KEY --value "..." [--type String|SecureString] [--overwrite]
+  npx tsx scripts/ssm/ssm-admin.ts delete --name /path/KEY`);
+}
+
+function ensureLeadingSlash(path: string): string {
+    const p = path.trim();
+    if (!p.startsWith("/")) return `/${p}`;
+    return p;
+}
+
+async function main(): Promise<void> {
+    const { _, flags } = parseCli(process.argv.slice(2));
+    const cmd = (_[0] || "").toLowerCase();
+    if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+        usage();
+        process.exit(cmd ? 0 : 1);
+    }
+
+    const region = typeof flags.region === "string" ? flags.region : getRegion();
+    const client = new SSMClient({ region });
+
+    if (cmd === "list") {
+        const prefix = ensureLeadingSlash(String(flags.prefix || "/mlsfarm/tf3/"));
+        const recursive = flags.recursive === false || flags.recursive === "false" ? false : true;
+        let next: string | undefined;
+        const rows: { name?: string; type?: string; version?: number }[] = [];
+        do {
+            const out = await client.send(
+                new GetParametersByPathCommand({
+                    Path: prefix,
+                    Recursive: recursive,
+                    WithDecryption: true,
+                    NextToken: next,
+                })
+            );
+            for (const p of out.Parameters || []) {
+                rows.push({ name: p.Name, type: p.Type, version: p.Version });
+            }
+            next = out.NextToken;
+        } while (next);
+
+        if (rows.length === 0) {
+            console.log(`(no parameters under ${prefix})`);
+            return;
+        }
+        const w = Math.max(...rows.map((r) => (r.name || "").length), 4);
+        console.log(`${"NAME".padEnd(w)}  TYPE            VER`);
+        for (const r of rows) {
+            console.log(`${(r.name || "").padEnd(w)}  ${(r.type || "").padEnd(14)} ${r.version ?? ""}`);
+        }
+        return;
+    }
+
+    if (cmd === "get") {
+        const name = flags.name;
+        if (typeof name !== "string" || !name.trim()) {
+            console.error("get: --name is required");
+            usage();
+            process.exit(1);
+        }
+        const out = await client.send(
+            new GetParameterCommand({ Name: ensureLeadingSlash(name), WithDecryption: true })
+        );
+        const p = out.Parameter;
+        if (!p?.Name) {
+            console.error("Parameter not found");
+            process.exit(1);
+        }
+        console.log(`Name:  ${p.Name}`);
+        console.log(`Type:  ${p.Type}`);
+        console.log(`Value: ${p.Value ?? ""}`);
+        return;
+    }
+
+    if (cmd === "put") {
+        const name = flags.name;
+        const value = flags.value;
+        if (typeof name !== "string" || !name.trim()) {
+            console.error("put: --name is required");
+            process.exit(1);
+        }
+        if (typeof value !== "string") {
+            console.error("put: --value is required (string)");
+            process.exit(1);
+        }
+        const type = (flags.type as string) === "SecureString" ? "SecureString" : "String";
+        const overwrite = flags.overwrite === true || flags.overwrite === "true";
+        const ver = await client.send(
+            new PutParameterCommand({
+                Name: ensureLeadingSlash(name),
+                Value: value,
+                Type: type,
+                Overwrite: overwrite,
+            })
+        );
+        console.log(`OK Version ${ver.Version}`);
+        return;
+    }
+
+    if (cmd === "delete") {
+        const name = flags.name;
+        if (typeof name !== "string" || !name.trim()) {
+            console.error("delete: --name is required");
+            process.exit(1);
+        }
+        await client.send(new DeleteParameterCommand({ Name: ensureLeadingSlash(name) }));
+        console.log("OK deleted");
+        return;
+    }
+
+    console.error(`Unknown command: ${cmd}`);
+    usage();
+    process.exit(1);
+}
+
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/scripts/ssm/ssm-pull.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Pull all SSM parameters under a path (recursive) for use on servers or locally.
+ * Uses default credential chain (on EC2: instance profile; e.g. mlsfarm tf3 `04.4.ssm_iam.tf`).
+ *
+ * Output modes:
+ *   print   — table to stdout (default)
+ *   dotenv  — KEY=value lines (dotenv-friendly; optional --file)
+ *   shell   — export KEY='...' lines for: eval "$(npx tsx ... --output shell)"
+ *
+ * Env key = last path segment of the parameter name (e.g. /mlsfarm/tf3/DATABASE_URL → DATABASE_URL).
+ *
+ * From package root:
+ *
+ *   npx tsx scripts/ssm/ssm-pull.ts --path /mlsfarm/tf3/
+ *   npm run ssm:pull -- --path /mlsfarm/tf3/ --output dotenv --file .env.from-ssm
+ *   eval "$(npx tsx scripts/ssm/ssm-pull.ts --path /mlsfarm/tf3/ --output shell)"
+ */
+
+import { SSMClient, GetParametersByPathCommand } from "@aws-sdk/client-ssm";
+import { writeFileSync } from "fs";
+import { parseCli, getRegion } from "./parse-cli.js";
+
+function ensureLeadingSlash(path: string): string {
+    const p = path.trim();
+    if (!p.startsWith("/")) return `/${p}`;
+    return p.endsWith("/") ? p : `${p}/`;
+}
+
+function leafKey(paramName: string): string {
+    const trimmed = paramName.replace(/^\/+|\/+$/g, "");
+    const parts = trimmed.split("/");
+    const leaf = parts[parts.length - 1] || trimmed;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(leaf)) {
+        return leaf.replace(/[^A-Za-z0-9_]+/g, "_").replace(/^(\d)/, "_$1");
+    }
+    return leaf;
+}
+
+function escapeDotenvValue(value: string): string {
+    if (/[\s#'"]/u.test(value) || value.includes("\n")) {
+        const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+        return `"${escaped}"`;
+    }
+    return value;
+}
+
+function escapeShellSingleQuoted(value: string): string {
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+
+async function fetchAll(
+    client: SSMClient,
+    path: string
+): Promise<{ name: string; value: string; type?: string }[]> {
+    const outList: { name: string; value: string; type?: string }[] = [];
+    let next: string | undefined;
+    do {
+        const out = await client.send(
+            new GetParametersByPathCommand({
+                Path: path,
+                Recursive: true,
+                WithDecryption: true,
+                NextToken: next,
+            })
+        );
+        for (const p of out.Parameters || []) {
+            if (p.Name && p.Value !== undefined) {
+                outList.push({ name: p.Name, value: p.Value, type: p.Type });
+            }
+        }
+        next = out.NextToken;
+    } while (next);
+    outList.sort((a, b) => a.name.localeCompare(b.name));
+    return outList;
+}
+
+async function main(): Promise<void> {
+    const { flags } = parseCli(process.argv.slice(2));
+    const pathRaw = flags.path;
+    if (typeof pathRaw !== "string" || !pathRaw.trim()) {
+        console.error("Required: --path /your/prefix/");
+        process.exit(1);
+    }
+    const path = ensureLeadingSlash(pathRaw);
+    const output = String(flags.output || "print").toLowerCase();
+    const file = typeof flags.file === "string" ? flags.file : undefined;
+
+    const region = typeof flags.region === "string" ? flags.region : getRegion();
+    const client = new SSMClient({ region });
+
+    const params = await fetchAll(client, path);
+    if (params.length === 0) {
+        const msg = `(no parameters under ${path})`;
+        if (file) writeFileSync(file, "", "utf8");
+        else console.log(msg);
+        return;
+    }
+
+    if (output === "print") {
+        const lines = [
+            `region=${region} path=${path} count=${params.length}`,
+            "",
+            ...params.map((p) => {
+                const k = leafKey(p.name);
+                const preview =
+                    p.value.length > 120 ? `${p.value.slice(0, 117)}...` : p.value;
+                return `${p.name}  [${k}]  (${p.type})  ${preview}`;
+            }),
+        ];
+        const text = lines.join("\n");
+        if (file) writeFileSync(file, text + "\n", "utf8");
+        else console.log(text);
+        return;
+    }
+
+    if (output === "dotenv") {
+        const body = params
+            .map((p) => {
+                const k = leafKey(p.name);
+                return `${k}=${escapeDotenvValue(p.value)}`;
+            })
+            .join("\n");
+        const text = `${body}\n`;
+        if (file) writeFileSync(file, text, "utf8");
+        else process.stdout.write(text);
+        return;
+    }
+
+    if (output === "shell") {
+        const body = params
+            .map((p) => {
+                const k = leafKey(p.name);
+                return `export ${k}=${escapeShellSingleQuoted(p.value)}`;
+            })
+            .join("\n");
+        const text = `${body}\n`;
+        if (file) writeFileSync(file, text, "utf8");
+        else process.stdout.write(text);
+        return;
+    }
+
+    console.error(`Unknown --output ${output}. Use: print | dotenv | shell`);
+    process.exit(1);
+}
+
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});