@zintrust/core 0.1.28 → 0.1.29

package/src/time/DateTime.d.ts

@@ -0,0 +1,181 @@
+/**
+ * DateTime - Immutable Date/Time Utilities
+ * Provides chainable, type-safe date/time operations with multiple format support
+ */
+/**
+ * DateTime interface defining all available operations
+ */
+export interface IDateTime {
+    /**
+     * Get the underlying Date object
+     */
+    toDate(): Date;
+    /**
+     * Format the date using pattern tokens
+     * Supported tokens: YYYY, YY, MMMM, MMM, MM, M, DD, D, HH, H, mm, ss, SSS
+     */
+    format(pattern: string): string;
+    /**
+     * Convert to ISO 8601 string (YYYY-MM-DDTHH:mm:ss.sssZ)
+     */
+    toISO(): string;
+    /**
+     * Convert to RFC 3339 string (same as ISO 8601)
+     */
+    toRFC3339(): string;
+    /**
+     * Get human-readable relative time (e.g., "2 hours ago", "in 3 days")
+     */
+    ago(): string;
+    /**
+     * Get relative time from a specific date
+     */
+    relative(other: Date | IDateTime): string;
+    /**
+     * Add days to the date (returns new IDateTime)
+     */
+    addDays(days: number): IDateTime;
+    /**
+     * Add hours to the date (returns new IDateTime)
+     */
+    addHours(hours: number): IDateTime;
+    /**
+     * Add minutes to the date (returns new IDateTime)
+     */
+    addMinutes(minutes: number): IDateTime;
+    /**
+     * Add seconds to the date (returns new IDateTime)
+     */
+    addSeconds(seconds: number): IDateTime;
+    /**
+     * Add months to the date (returns new IDateTime)
+     */
+    addMonths(months: number): IDateTime;
+    /**
+     * Add years to the date (returns new IDateTime)
+     */
+    addYears(years: number): IDateTime;
+    /**
+     * Check if this date is before another date
+     */
+    isBefore(other: Date | IDateTime): boolean;
+    /**
+     * Check if this date is after another date
+     */
+    isAfter(other: Date | IDateTime): boolean;
+    /**
+     * Check if this date is the same as another date (ignoring time)
+     */
+    isSame(other: Date | IDateTime): boolean;
+    /**
+     * Check if this date is between two dates (inclusive)
+     */
+    isBetween(start: Date | IDateTime, end: Date | IDateTime): boolean;
+    /**
+     * Get difference in milliseconds from another date
+     */
+    diffMs(other: Date | IDateTime): number;
+    /**
+     * Get difference in seconds from another date
+     */
+    diffSeconds(other: Date | IDateTime): number;
+    /**
+     * Get difference in minutes from another date
+     */
+    diffMinutes(other: Date | IDateTime): number;
+    /**
+     * Get difference in hours from another date
+     */
+    diffHours(other: Date | IDateTime): number;
+    /**
+     * Get difference in days from another date
+     */
+    diffDays(other: Date | IDateTime): number;
+    /**
+     * Start of day (00:00:00)
+     */
+    startOfDay(): IDateTime;
+    /**
+     * End of day (23:59:59)
+     */
+    endOfDay(): IDateTime;
+    /**
+     * Start of month
+     */
+    startOfMonth(): IDateTime;
+    /**
+     * End of month
+     */
+    endOfMonth(): IDateTime;
+    /**
+     * Clone this datetime
+     */
+    clone(): IDateTime;
+    /**
+     * Get Unix timestamp (milliseconds since epoch)
+     */
+    getTime(): number;
+    /**
+     * Get year
+     */
+    getYear(): number;
+    /**
+     * Get month (0-11)
+     */
+    getMonth(): number;
+    /**
+     * Get day of month (1-31)
+     */
+    getDate(): number;
+    /**
+     * Get hours (0-23)
+     */
+    getHours(): number;
+    /**
+     * Get minutes (0-59)
+     */
+    getMinutes(): number;
+    /**
+     * Get seconds (0-59)
+     */
+    getSeconds(): number;
+    /**
+     * Get milliseconds (0-999)
+     */
+    getMilliseconds(): number;
+    /**
+     * Get day of week (0=Sunday, 6=Saturday)
+     */
+    getDayOfWeek(): number;
+    /**
+     * Get day of year (1-366)
+     */
+    getDayOfYear(): number;
+}
+/**
+ * DateTime namespace - sealed namespace object grouping all DateTime operations
+ * Immutable by design - all operations return new IDateTime instances
+ */
+export declare const DateTime: Readonly<{
+    /**
+     * Create a DateTime from a Date object
+     */
+    create(date?: Date): IDateTime;
+    /**
+     * Get current DateTime
+     */
+    now(): IDateTime;
+    /**
+     * Parse a date string
+     */
+    parse(dateString: string): IDateTime;
+    /**
+     * Create DateTime from timestamp (milliseconds since epoch)
+     */
+    fromTimestamp(timestamp: number): IDateTime;
+    /**
+     * Create DateTime from components
+     */
+    fromComponents(year: number, month: number, day?: number, hours?: number, minutes?: number, seconds?: number): IDateTime;
+}>;
+//# sourceMappingURL=DateTime.d.ts.map

package/src/time/DateTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DateTime.d.ts","sourceRoot":"","sources":["../../../src/time/DateTime.ts"],"names":[],"mappings":"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"}

package/src/time/DateTime.js

@@ -0,0 +1,300 @@
+/**
+ * DateTime - Immutable Date/Time Utilities
+ * Provides chainable, type-safe date/time operations with multiple format support
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+/**
+ * Create a DateTime instance from a Date or string
+ */
+const monthNames = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+const monthNamesShort = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+const padZero = (num, length = 2) => {
+    return String(num).padStart(length, '0');
+};
+const getDayOfYearHelper = (date) => {
+    const start = new Date(date.getFullYear(), 0, 0);
+    const diff = date.getTime() - start.getTime();
+    const oneDay = 1000 * 60 * 60 * 24;
+    return Math.floor(diff / oneDay);
+};
+const calculateAgo = (value) => {
+    const now = new Date();
+    const diffMs = now.getTime() - value.getTime();
+    if (diffMs < 1000)
+        return 'just now';
+    if (diffMs < 60000)
+        return `${Math.floor(diffMs / 1000)} seconds ago`;
+    if (diffMs < 3600000)
+        return `${Math.floor(diffMs / 60000)} minutes ago`;
+    if (diffMs < 86400000)
+        return `${Math.floor(diffMs / 3600000)} hours ago`;
+    if (diffMs < 604800000)
+        return `${Math.floor(diffMs / 86400000)} days ago`;
+    if (diffMs < 2592000000)
+        return `${Math.floor(diffMs / 604800000)} weeks ago`;
+    if (diffMs < 31536000000)
+        return `${Math.floor(diffMs / 2592000000)} months ago`;
+    return `${Math.floor(diffMs / 31536000000)} years ago`;
+};
+const formatRelativeTime = (diffMs, isFuture) => {
+    const unit = (count, label) => isFuture ? `in ${count} ${label}` : `${count} ${label} ago`;
+    if (diffMs < 1000)
+        return 'just now';
+    if (diffMs < 60000)
+        return unit(Math.floor(diffMs / 1000), 'seconds');
+    if (diffMs < 3600000)
+        return unit(Math.floor(diffMs / 60000), 'minutes');
+    if (diffMs < 86400000)
+        return unit(Math.floor(diffMs / 3600000), 'hours');
+    if (diffMs < 604800000)
+        return unit(Math.floor(diffMs / 86400000), 'days');
+    if (diffMs < 2592000000)
+        return unit(Math.floor(diffMs / 604800000), 'weeks');
+    if (diffMs < 31536000000)
+        return unit(Math.floor(diffMs / 2592000000), 'months');
+    return unit(Math.floor(diffMs / 31536000000), 'years');
+};
+const calculateRelative = (value, other) => {
+    const otherDate = other instanceof Date ? other : other.toDate();
+    const diffMs = otherDate.getTime() - value.getTime();
+    if (diffMs < 0) {
+        return formatRelativeTime(Math.abs(diffMs), false);
+    }
+    return formatRelativeTime(diffMs, true);
+};
+const createAddMethods = (value) => {
+    return {
+        addDays: (days) => {
+            const newDate = new Date(value);
+            newDate.setDate(newDate.getDate() + days);
+            return createDateTime(newDate);
+        },
+        addHours: (hours) => {
+            const newDate = new Date(value);
+            newDate.setHours(newDate.getHours() + hours);
+            return createDateTime(newDate);
+        },
+        addMinutes: (minutes) => {
+            const newDate = new Date(value);
+            newDate.setMinutes(newDate.getMinutes() + minutes);
+            return createDateTime(newDate);
+        },
+        addSeconds: (seconds) => {
+            const newDate = new Date(value);
+            newDate.setSeconds(newDate.getSeconds() + seconds);
+            return createDateTime(newDate);
+        },
+        addMonths: (months) => {
+            const newDate = new Date(value);
+            newDate.setMonth(newDate.getMonth() + months);
+            return createDateTime(newDate);
+        },
+        addYears: (years) => {
+            const newDate = new Date(value);
+            newDate.setFullYear(newDate.getFullYear() + years);
+            return createDateTime(newDate);
+        },
+    };
+};
+const createCompareMethods = (value) => {
+    return {
+        isBefore: (other) => {
+            const otherDate = other instanceof Date ? other : other.toDate();
+            return value.getTime() < otherDate.getTime();
+        },
+        isAfter: (other) => {
+            const otherDate = other instanceof Date ? other : other.toDate();
+            return value.getTime() > otherDate.getTime();
+        },
+        isSame: (other) => {
+            const otherDate = other instanceof Date ? other : other.toDate();
+            return (value.getFullYear() === otherDate.getFullYear() &&
+                value.getMonth() === otherDate.getMonth() &&
+                value.getDate() === otherDate.getDate());
+        },
+        isBetween: (start, end) => {
+            const startDate = start instanceof Date ? start : start.toDate();
+            const endDate = end instanceof Date ? end : end.toDate();
+            return value.getTime() >= startDate.getTime() && value.getTime() <= endDate.getTime();
+        },
+    };
+};
+const createDiffMethods = (value) => {
+    const getOtherDate = (other) => other instanceof Date ? other : other.toDate();
+    return {
+        diffMs: (other) => {
+            return value.getTime() - getOtherDate(other).getTime();
+        },
+        diffSeconds: (other) => {
+            return Math.floor((value.getTime() - getOtherDate(other).getTime()) / 1000);
+        },
+        diffMinutes: (other) => {
+            return Math.floor((value.getTime() - getOtherDate(other).getTime()) / 60000);
+        },
+        diffHours: (other) => {
+            return Math.floor((value.getTime() - getOtherDate(other).getTime()) / 3600000);
+        },
+        diffDays: (other) => {
+            return Math.floor((value.getTime() - getOtherDate(other).getTime()) / 86400000);
+        },
+    };
+};
+const createBoundaryMethods = (value) => {
+    return {
+        startOfDay: () => {
+            const newDate = new Date(value);
+            newDate.setHours(0, 0, 0, 0);
+            return createDateTime(newDate);
+        },
+        endOfDay: () => {
+            const newDate = new Date(value);
+            newDate.setHours(23, 59, 59, 999);
+            return createDateTime(newDate);
+        },
+        startOfMonth: () => {
+            const newDate = new Date(value);
+            newDate.setDate(1);
+            newDate.setHours(0, 0, 0, 0);
+            return createDateTime(newDate);
+        },
+        endOfMonth: () => {
+            const newDate = new Date(value);
+            newDate.setMonth(newDate.getMonth() + 1);
+            newDate.setDate(0);
+            newDate.setHours(23, 59, 59, 999);
+            return createDateTime(newDate);
+        },
+    };
+};
+const createDateTime = (date) => {
+    // Create a copy to ensure immutability
+    const value = new Date(date);
+    const addMethods = createAddMethods(value);
+    const compareMethods = createCompareMethods(value);
+    const diffMethods = createDiffMethods(value);
+    const boundaryMethods = createBoundaryMethods(value);
+    return {
+        toDate: () => new Date(value),
+        format: (pattern) => {
+            let result = pattern;
+            const year = value.getFullYear();
+            const month = value.getMonth();
+            const day = value.getDate();
+            const hours = value.getHours();
+            const minutes = value.getMinutes();
+            const seconds = value.getSeconds();
+            const milliseconds = value.getMilliseconds();
+            // Replace tokens in the pattern
+            result = result.replaceAll('YYYY', String(year));
+            result = result.replaceAll('YY', String(year).slice(-2));
+            result = result.replaceAll('MMMM', monthNames[month] ?? '');
+            result = result.replaceAll('MMM', monthNamesShort[month] ?? '');
+            result = result.replaceAll('MM', padZero(month + 1));
+            result = result.replaceAll('M', String(month + 1));
+            result = result.replaceAll('DD', padZero(day));
+            result = result.replaceAll('D', String(day));
+            result = result.replaceAll('HH', padZero(hours));
+            result = result.replaceAll('H', String(hours));
+            result = result.replaceAll('mm', padZero(minutes));
+            result = result.replaceAll('m', String(minutes));
+            result = result.replaceAll('ss', padZero(seconds));
+            result = result.replaceAll('s', String(seconds));
+            result = result.replaceAll('SSS', padZero(milliseconds, 3));
+            result = result.replaceAll('S', String(milliseconds));
+            return result;
+        },
+        toISO: () => value.toISOString(),
+        toRFC3339: () => value.toISOString(),
+        ago: () => calculateAgo(value),
+        relative: (other) => calculateRelative(value, other),
+        ...addMethods,
+        ...compareMethods,
+        ...diffMethods,
+        ...boundaryMethods,
+        clone: () => createDateTime(new Date(value)),
+        getTime: () => value.getTime(),
+        getYear: () => value.getFullYear(),
+        getMonth: () => value.getMonth(),
+        getDate: () => value.getDate(),
+        getHours: () => value.getHours(),
+        getMinutes: () => value.getMinutes(),
+        getSeconds: () => value.getSeconds(),
+        getMilliseconds: () => value.getMilliseconds(),
+        getDayOfWeek: () => value.getDay(),
+        getDayOfYear: () => getDayOfYearHelper(value),
+    };
+};
+/**
+ * Parse a date string into a DateTime object
+ * Supports: ISO 8601, RFC 3339, common formats
+ */
+const parse = (dateString) => {
+    // Try to parse as ISO 8601 / RFC 3339
+    const parsedDate = new Date(dateString);
+    if (Number.isNaN(parsedDate.getTime())) {
+        throw ErrorFactory.createValidationError(`Invalid date string: ${dateString}`);
+    }
+    return createDateTime(parsedDate);
+};
+/**
+ * DateTime namespace - sealed namespace object grouping all DateTime operations
+ * Immutable by design - all operations return new IDateTime instances
+ */
+export const DateTime = Object.freeze({
+    /**
+     * Create a DateTime from a Date object
+     */
+    create(date = new Date()) {
+        return createDateTime(date);
+    },
+    /**
+     * Get current DateTime
+     */
+    now() {
+        return createDateTime(new Date());
+    },
+    /**
+     * Parse a date string
+     */
+    parse(dateString) {
+        return parse(dateString);
+    },
+    /**
+     * Create DateTime from timestamp (milliseconds since epoch)
+     */
+    fromTimestamp(timestamp) {
+        return createDateTime(new Date(timestamp));
+    },
+    /**
+     * Create DateTime from components
+     */
+    fromComponents(year, month, day = 1, hours = 0, minutes = 0, seconds = 0) {
+        return createDateTime(new Date(year, month - 1, day, hours, minutes, seconds));
+    },
+});

package/src/time/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Time Utilities Module
+ * Exports immutable DateTime utilities and related types
+ */
+export { DateTime } from './DateTime';
+export type { IDateTime } from './DateTime';
+//# sourceMappingURL=index.d.ts.map

package/src/time/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/time/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/src/time/index.js

@@ -0,0 +1,5 @@
+/**
+ * Time Utilities Module
+ * Exports immutable DateTime utilities and related types
+ */
+export { DateTime } from './DateTime.js';

package/src/toolkit/Secrets/EnvFile.d.ts

@@ -0,0 +1,15 @@
+export type EnvFileWriteMode = 'overwrite';
+export declare const EnvFile: Readonly<{
+    read(params: {
+        cwd: string;
+        path: string;
+    }): Promise<Record<string, string>>;
+    write(params: {
+        cwd: string;
+        path: string;
+        values: Record<string, string>;
+        mode: EnvFileWriteMode;
+    }): Promise<void>;
+}>;
+export default EnvFile;
+//# sourceMappingURL=EnvFile.d.ts.map

package/src/toolkit/Secrets/EnvFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvFile.d.ts","sourceRoot":"","sources":["../../../../src/toolkit/Secrets/EnvFile.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAmC3C,eAAO,MAAM,OAAO;iBACC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;kBAgB9D;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,IAAI,EAAE,gBAAgB,CAAC;KACxB,GAAG,OAAO,CAAC,IAAI,CAAC;EAgBjB,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/src/toolkit/Secrets/EnvFile.js

@@ -0,0 +1,63 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { fsPromises as fs } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+const isValidKey = (key) => /^[A-Z0-9_]+$/.test(key);
+const parseEnvLine = (line) => {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#'))
+        return null;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0)
+        return null;
+    const key = trimmed.slice(0, eq).trim();
+    const raw = trimmed.slice(eq + 1);
+    if (!isValidKey(key))
+        return null;
+    // Preserve value verbatim (except strip surrounding quotes if present)
+    let value = raw;
+    const v = raw.trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        value = v.slice(1, -1);
+    }
+    return { key, value };
+};
+const serializeEnv = (values) => {
+    const keys = Object.keys(values).sort((a, b) => a.localeCompare(b));
+    const lines = keys.map((key) => {
+        const value = values[key] ?? '';
+        // Write as JSON string to safely quote newlines, #, etc.
+        return `${key}=${JSON.stringify(value)}`;
+    });
+    return `${lines.join('\n')}\n`;
+};
+export const EnvFile = Object.freeze({
+    async read(params) {
+        const filePath = path.resolve(params.cwd, params.path);
+        try {
+            const raw = await fs.readFile(filePath, 'utf-8');
+            const result = {};
+            for (const line of raw.split(/\r?\n/)) {
+                const parsed = parseEnvLine(line);
+                if (parsed)
+                    result[parsed.key] = parsed.value;
+            }
+            return result;
+        }
+        catch {
+            return {};
+        }
+    },
+    async write(params) {
+        const filePath = path.resolve(params.cwd, params.path);
+        for (const key of Object.keys(params.values)) {
+            if (!isValidKey(key)) {
+                throw ErrorFactory.createCliError(`Invalid env key: ${key}`);
+            }
+        }
+        const content = serializeEnv(params.values);
+        // Ensure parent dir exists for cases like ./.zintrust/.env.pull
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, content, 'utf-8');
+    },
+});
+export default EnvFile;

package/src/toolkit/Secrets/Manifest.d.ts

@@ -0,0 +1,24 @@
+export type SecretsProviderName = 'aws' | 'cloudflare';
+export type ManifestKeySpec = {
+    aws?: {
+        secretId: string;
+        jsonKey?: string;
+    };
+    cloudflare?: {
+        key: string;
+        namespaceId?: string;
+    };
+};
+export type SecretsManifest = {
+    provider: SecretsProviderName;
+    keys: Record<string, ManifestKeySpec>;
+};
+export declare const Manifest: Readonly<{
+    load(params: {
+        cwd: string;
+        path: string;
+        provider: SecretsProviderName;
+    }): Promise<SecretsManifest>;
+}>;
+export default Manifest;
+//# sourceMappingURL=Manifest.d.ts.map

package/src/toolkit/Secrets/Manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Manifest.d.ts","sourceRoot":"","sources":["../../../../src/toolkit/Secrets/Manifest.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,YAAY,CAAC;AAEvD,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,CAAC,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACvC,CAAC;AA+DF,eAAO,MAAM,QAAQ;iBACA;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,mBAAmB,CAAC;KAC/B,GAAG,OAAO,CAAC,eAAe,CAAC;EA4B5B,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/src/toolkit/Secrets/Manifest.js

@@ -0,0 +1,71 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { fsPromises as fs } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const assertString = (value, name) => {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw ErrorFactory.createCliError(`Manifest: missing/invalid ${name}`);
+    }
+    return value;
+};
+const validateKeyName = (key) => {
+    if (!/^[A-Z0-9_]+$/.test(key)) {
+        throw ErrorFactory.createCliError(`Manifest: invalid env key: ${key}`);
+    }
+};
+const parseProvider = (parsed, fallback) => {
+    const provider = 'provider' in parsed && typeof parsed['provider'] === 'string'
+        ? parsed['provider']
+        : fallback;
+    if (provider !== 'aws' && provider !== 'cloudflare') {
+        throw ErrorFactory.createCliError('Manifest: provider must be aws|cloudflare');
+    }
+    return provider;
+};
+const parseKeySpec = (envKey, specUnknown) => {
+    const spec = {};
+    const awsUnknown = specUnknown['aws'];
+    if (isRecord(awsUnknown)) {
+        spec.aws = {
+            secretId: assertString(awsUnknown['secretId'], `keys.${envKey}.aws.secretId`),
+            jsonKey: typeof awsUnknown['jsonKey'] === 'string' && awsUnknown['jsonKey'].trim() !== ''
+                ? awsUnknown['jsonKey']
+                : undefined,
+        };
+    }
+    const cloudflareUnknown = specUnknown['cloudflare'];
+    if (isRecord(cloudflareUnknown)) {
+        spec.cloudflare = {
+            key: assertString(cloudflareUnknown['key'], `keys.${envKey}.cloudflare.key`),
+            namespaceId: typeof cloudflareUnknown['namespaceId'] === 'string' &&
+                cloudflareUnknown['namespaceId'].trim() !== ''
+                ? cloudflareUnknown['namespaceId']
+                : undefined,
+        };
+    }
+    return spec;
+};
+export const Manifest = Object.freeze({
+    async load(params) {
+        const filePath = path.resolve(params.cwd, params.path);
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsedUnknown = JSON.parse(raw);
+        if (!isRecord(parsedUnknown)) {
+            throw ErrorFactory.createCliError('Manifest: expected JSON object');
+        }
+        const provider = parseProvider(parsedUnknown, params.provider);
+        const keysUnknown = parsedUnknown['keys'];
+        if (!isRecord(keysUnknown)) {
+            throw ErrorFactory.createCliError('Manifest: keys must be an object');
+        }
+        const keys = {};
+        for (const [envKey, specUnknown] of Object.entries(keysUnknown)) {
+            validateKeyName(envKey);
+            if (!isRecord(specUnknown))
+                throw ErrorFactory.createCliError(`Manifest: key ${envKey} must be an object`);
+            keys[envKey] = parseKeySpec(envKey, specUnknown);
+        }
+        return { provider, keys };
+    },
+});
+export default Manifest;