@syntax-syllogism/warden-core 0.2.0

package/lib/relatedRecords/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/relatedRecords/types.ts"],"names":[],"mappings":""}

package/lib/shared/csv.d.ts

@@ -0,0 +1,26 @@
+import type { UserFieldMeta } from '../matching/index.js';
+import { DefinitionError } from '../provisioning/errors.js';
+export type InputFormat = 'json' | 'csv';
+/** The format a path's extension settles on its own, or undefined when it does not settle one. */
+export declare const inputFormatFromExtension: (path: string) => InputFormat | undefined;
+export declare const detectInputFormat: (path: string, override?: InputFormat) => InputFormat;
+export type CsvRowInfo = {
+    path: string;
+    line: number;
+};
+export declare const getCsvRowInfo: (value: unknown) => CsvRowInfo | undefined;
+export declare class CsvReadError extends DefinitionError {
+    constructor(path: string, line: number, detail: string);
+}
+export type ParsedCsvRow = {
+    cells: string[];
+    line: number;
+};
+export declare const readCsvRows: (source: string, path: string, delimiter: string) => ParsedCsvRow[];
+export declare const readCsvUsers: (path: string, fieldMap: Map<string, UserFieldMeta>, listDelimiter?: string) => Promise<{
+    users: Array<Record<string, unknown>>;
+}>;
+export declare const neutralizeCsvFormula: (value: string) => string;
+export declare const restoreCsvFormula: (value: string) => string;
+export declare const csvEscape: (value: unknown) => string;
+export declare const serializeCsv: (rows: Array<Record<string, unknown>>, columns: string[]) => string;

package/lib/shared/csv.js

@@ -0,0 +1,237 @@
+import { readFile } from 'node:fs/promises';
+import { DefinitionError } from '../provisioning/errors.js';
+const FORMULA_PREFIX = /^[=+\-@\t\r]/;
+/** The format a path's extension settles on its own, or undefined when it does not settle one. */
+export const inputFormatFromExtension = (path) => {
+    if (/\.(csv|tsv)$/i.test(path))
+        return 'csv';
+    if (/\.json$/i.test(path))
+        return 'json';
+    return undefined;
+};
+export const detectInputFormat = (path, override) => override ?? inputFormatFromExtension(path) ?? 'json';
+const csvRowInfo = Symbol('csvRowInfo');
+export const getCsvRowInfo = (value) => value && typeof value === 'object' ? value[csvRowInfo] : undefined;
+export class CsvReadError extends DefinitionError {
+    constructor(path, line, detail) {
+        super('errorInvalidCsv', `${path}:${line} — ${detail}`, { path, line, detail });
+        this.name = 'CsvReadError';
+    }
+}
+// CSV quoting has several mutually exclusive parser states; keeping them together makes line tracking auditable.
+// eslint-disable-next-line complexity
+export const readCsvRows = (source, path, delimiter) => {
+    const text = source.charCodeAt(0) === 0xfeff ? source.slice(1) : source;
+    const rows = [];
+    let cells = [];
+    let cell = '';
+    let cellStarted = false;
+    let quoteClosed = false;
+    let inQuotes = false;
+    let rowTouched = false;
+    let rowLine = 1;
+    let line = 1;
+    const finishRow = () => {
+        rows.push({ cells: [...cells, cell], line: rowLine });
+        cells = [];
+        cell = '';
+        cellStarted = false;
+        quoteClosed = false;
+        rowTouched = false;
+        rowLine = line;
+    };
+    for (let index = 0; index < text.length; index += 1) {
+        const character = text[index];
+        if (inQuotes) {
+            if (character === '"') {
+                if (text[index + 1] === '"') {
+                    cell += '"';
+                    index += 1;
+                }
+                else {
+                    inQuotes = false;
+                    quoteClosed = true;
+                }
+            }
+            else {
+                cell += character;
+                if (character === '\r') {
+                    if (text[index + 1] === '\n') {
+                        cell += '\n';
+                        index += 1;
+                    }
+                    line += 1;
+                }
+                else if (character === '\n') {
+                    line += 1;
+                }
+            }
+            continue;
+        }
+        if (quoteClosed) {
+            if (character === delimiter) {
+                cells.push(cell);
+                cell = '';
+                cellStarted = false;
+                quoteClosed = false;
+                rowTouched = true;
+                continue;
+            }
+            if (character === '\r' || character === '\n') {
+                if (character === '\r' && text[index + 1] === '\n')
+                    index += 1;
+                line += 1;
+                finishRow();
+                continue;
+            }
+            throw new CsvReadError(path, line, 'Unexpected character after a closing quote.');
+        }
+        if (character === '"') {
+            if (cellStarted)
+                throw new CsvReadError(path, line, 'Unexpected quote in an unquoted cell.');
+            inQuotes = true;
+            cellStarted = true;
+            rowTouched = true;
+        }
+        else if (character === delimiter) {
+            cells.push(cell);
+            cell = '';
+            cellStarted = false;
+            rowTouched = true;
+        }
+        else if (character === '\r' || character === '\n') {
+            if (character === '\r' && text[index + 1] === '\n')
+                index += 1;
+            line += 1;
+            finishRow();
+        }
+        else {
+            cell += character;
+            cellStarted = true;
+            rowTouched = true;
+        }
+    }
+    if (inQuotes)
+        throw new CsvReadError(path, line, 'Unterminated quoted cell.');
+    if (rowTouched || cells.length > 0 || cell.length > 0)
+        finishRow();
+    if (/[\r\n]$/.test(text) && rows.at(-1)?.cells.length === 1 && rows.at(-1)?.cells[0] === '')
+        rows.pop();
+    return rows;
+};
+const levenshtein = (left, right) => {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= left.length; row += 1) {
+        let diagonal = previous[0];
+        previous[0] = row;
+        for (let column = 1; column <= right.length; column += 1) {
+            const above = previous[column];
+            previous[column] = Math.min(previous[column] + 1, previous[column - 1] + 1, diagonal + (left[row - 1] === right[column - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return previous[right.length];
+};
+const suggestedHeader = (header, validHeaders) => {
+    const lowerHeader = header.toLowerCase();
+    const suggestion = validHeaders
+        .map((candidate) => ({ candidate, distance: levenshtein(lowerHeader, candidate.toLowerCase()) }))
+        .filter(({ distance }) => distance <= 2)
+        .sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate))[0];
+    return suggestion?.candidate;
+};
+const parseBoolean = (value) => {
+    switch (value.toLowerCase()) {
+        case 'true':
+        case '1':
+        case 'yes':
+            return true;
+        case 'false':
+        case '0':
+        case 'no':
+            return false;
+        default:
+            return undefined;
+    }
+};
+const splitList = (value, delimiter) => value
+    .split(delimiter)
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+export const readCsvUsers = async (path, fieldMap, listDelimiter = ';') => {
+    if (listDelimiter.length === 0)
+        throw new CsvReadError(path, 1, '--csv-list-delimiter must not be empty.');
+    const delimiter = /\.tsv$/i.test(path) ? '\t' : ',';
+    const rows = readCsvRows(await readFile(path, 'utf8'), path, delimiter);
+    if (rows.length === 0)
+        throw new CsvReadError(path, 1, 'CSV must contain a header row.');
+    const headerRow = rows[0];
+    const metaHeaders = new Map([
+        ['personas', 'personas'],
+        ['match', 'match'],
+        ['fuzzyusername', 'fuzzyUsername'],
+    ]);
+    const validHeaders = [...metaHeaders.values(), ...[...fieldMap.values()].map((field) => field.name)];
+    const seen = new Set();
+    const headers = headerRow.cells.map((rawHeader) => {
+        const header = rawHeader.trim();
+        const key = header.toLowerCase();
+        if (seen.has(key))
+            throw new CsvReadError(path, headerRow.line, `Duplicate column "${rawHeader}".`);
+        seen.add(key);
+        const metaHeader = metaHeaders.get(key);
+        const field = fieldMap.get(key);
+        if (!metaHeader && !field) {
+            const suggestion = suggestedHeader(header, validHeaders);
+            const suffix = suggestion ? `; did you mean "${suggestion}"?` : '';
+            throw new CsvReadError(path, headerRow.line, `Unknown column "${rawHeader}"${suffix}`);
+        }
+        return { raw: rawHeader, key, name: metaHeader ?? field?.name, field };
+    });
+    const users = [];
+    for (const row of rows.slice(1)) {
+        if (row.cells.length !== headers.length) {
+            throw new CsvReadError(path, row.line, `Expected ${headers.length} cells but found ${row.cells.length}.`);
+        }
+        const user = {};
+        headers.forEach((header, index) => {
+            const value = row.cells[index];
+            if (value.length === 0)
+                return;
+            if (header.name === 'personas') {
+                user.personas = splitList(value, listDelimiter);
+                return;
+            }
+            if (header.name === 'fuzzyUsername' || header.field?.isBoolean) {
+                const parsed = parseBoolean(value);
+                if (parsed === undefined) {
+                    throw new CsvReadError(path, row.line, `${header.raw} must be a boolean; got "${value}".`);
+                }
+                user[header.name] = parsed;
+                return;
+            }
+            user[header.name] = value;
+        });
+        Object.defineProperty(user, csvRowInfo, { value: { path, line: row.line }, enumerable: false });
+        users.push(user);
+    }
+    return { users };
+};
+export const neutralizeCsvFormula = (value) => {
+    if (value.startsWith("'") && FORMULA_PREFIX.test(value.slice(1)))
+        return value;
+    return FORMULA_PREFIX.test(value) ? `'${value}` : value;
+};
+export const restoreCsvFormula = (value) => value.startsWith("'") && FORMULA_PREFIX.test(value.slice(1)) ? value.slice(1) : value;
+export const csvEscape = (value) => {
+    const text = value === null || value === undefined ? '' : String(value);
+    const escaped = neutralizeCsvFormula(text).replaceAll('"', '""');
+    return /[,"\n\r]/.test(escaped) ? `"${escaped}"` : escaped;
+};
+export const serializeCsv = (rows, columns) => {
+    const lines = [columns.join(',')];
+    for (const row of rows)
+        lines.push(columns.map((column) => csvEscape(row[column])).join(','));
+    return lines.join('\n');
+};
+//# sourceMappingURL=csv.js.map

package/lib/shared/csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.js","sourceRoot":"","sources":["../../src/shared/csv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,MAAM,cAAc,GAAG,cAAc,CAAC;AAItC,kGAAkG;AAClG,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,IAAY,EAA2B,EAAE;IAChF,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IACzC,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAY,EAAE,QAAsB,EAAe,EAAE,CACrF,QAAQ,IAAI,wBAAwB,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;AAIvD,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;AAExC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAc,EAA0B,EAAE,CACtE,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,KAAuC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAExG,MAAM,OAAO,YAAa,SAAQ,eAAe;IAC/C,YAAmB,IAAY,EAAE,IAAY,EAAE,MAAc;QAC3D,KAAK,CAAC,iBAAiB,EAAE,GAAG,IAAI,IAAI,IAAI,MAAM,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAID,iHAAiH;AACjH,sCAAsC;AACtC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAc,EAAE,IAAY,EAAE,SAAiB,EAAkB,EAAE;IAC7F,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACxE,MAAM,IAAI,GAAmB,EAAE,CAAC;IAChC,IAAI,KAAK,GAAa,EAAE,CAAC;IACzB,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,MAAM,SAAS,GAAG,GAAS,EAAE;QAC3B,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACtD,KAAK,GAAG,EAAE,CAAC;QACX,IAAI,GAAG,EAAE,CAAC;QACV,WAAW,GAAG,KAAK,CAAC;QACpB,WAAW,GAAG,KAAK,CAAC;QACpB,UAAU,GAAG,KAAK,CAAC;QACnB,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC,CAAC;IAEF,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;gBACtB,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;oBAC5B,IAAI,IAAI,GAAG,CAAC;oBACZ,KAAK,IAAI,CAAC,CAAC;gBACb,CAAC;qBAAM,CAAC;oBACN,QAAQ,GAAG,KAAK,CAAC;oBACjB,WAAW,GAAG,IAAI,CAAC;gBACrB,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,IAAI,IAAI,SAAS,CAAC;gBAClB,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;oBACvB,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;wBAC7B,IAAI,IAAI,IAAI,CAAC;wBACb,KAAK,IAAI,CAAC,CAAC;oBACb,CAAC;oBACD,IAAI,IAAI,CAAC,CAAC;gBACZ,CAAC;qBAAM,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;oBAC9B,IAAI,IAAI,CAAC,CAAC;gBACZ,CAAC;YACH,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,WAAW,EAAE,CAAC;YAChB,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjB,IAAI,GAAG,EAAE,CAAC;gBACV,WAAW,GAAG,KAAK,CAAC;gBACpB,WAAW,GAAG,KAAK,CAAC;gBACpB,UAAU,GAAG,IAAI,CAAC;gBAClB,SAAS;YACX,CAAC;YACD,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;gBAC7C,IAAI,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI;oBAAE,KAAK,IAAI,CAAC,CAAC;gBAC/D,IAAI,IAAI,CAAC,CAAC;gBACV,SAAS,EAAE,CAAC;gBACZ,SAAS;YACX,CAAC;YACD,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,6CAA6C,CAAC,CAAC;QACpF,CAAC;QAED,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;YACtB,IAAI,WAAW;gBAAE,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,uCAAuC,CAAC,CAAC;YAC7F,QAAQ,GAAG,IAAI,CAAC;YAChB,WAAW,GAAG,IAAI,CAAC;YACnB,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;aAAM,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,IAAI,GAAG,EAAE,CAAC;YACV,WAAW,GAAG,KAAK,CAAC;YACpB,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;aAAM,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACpD,IAAI,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI;gBAAE,KAAK,IAAI,CAAC,CAAC;YAC/D,IAAI,IAAI,CAAC,CAAC;YACV,SAAS,EAAE,CAAC;QACd,CAAC;aAAM,CAAC;YACN,IAAI,IAAI,SAAS,CAAC;YAClB,WAAW,GAAG,IAAI,CAAC;YACnB,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,QAAQ;QAAE,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,2BAA2B,CAAC,CAAC;IAC9E,IAAI,UAAU,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,SAAS,EAAE,CAAC;IACnE,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IACxG,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE;IAC1D,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IAC/E,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAC/C,IAAI,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC3B,QAAQ,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;QAClB,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,EAAE,CAAC;YACzD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC/B,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CACzB,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EACpB,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EACxB,QAAQ,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACzD,CAAC;YACF,QAAQ,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,YAAsB,EAAsB,EAAE;IACrF,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACzC,MAAM,UAAU,GAAG,YAAY;SAC5B,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,WAAW,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;SAChG,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,QAAQ,IAAI,CAAC,CAAC;SACvC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7G,OAAO,UAAU,EAAE,SAAS,CAAC;AAC/B,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,KAAa,EAAuB,EAAE;IAC1D,QAAQ,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC;QACZ,KAAK,GAAG,CAAC;QACT,KAAK,KAAK;YACR,OAAO,IAAI,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,GAAG,CAAC;QACT,KAAK,IAAI;YACP,OAAO,KAAK,CAAC;QACf;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,SAAiB,EAAY,EAAE,CAC/D,KAAK;KACF,KAAK,CAAC,SAAS,CAAC;KAChB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;KAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAEvC,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,IAAY,EACZ,QAAoC,EACpC,aAAa,GAAG,GAAG,EACiC,EAAE;IACtD,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,yCAAyC,CAAC,CAAC;IAC3G,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;IACpD,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACxE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,gCAAgC,CAAC,CAAC;IAEzF,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;QAC1B,CAAC,UAAU,EAAE,UAAU,CAAC;QACxB,CAAC,OAAO,EAAE,OAAO,CAAC;QAClB,CAAC,eAAe,EAAE,eAAe,CAAC;KACnC,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACrG,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;QAChD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,qBAAqB,SAAS,IAAI,CAAC,CAAC;QACpG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC;YAC1B,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YACzD,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,mBAAmB,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,mBAAmB,SAAS,IAAI,MAAM,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,IAAI,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAmC,EAAE,CAAC;IACjD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAChC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;YACxC,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,YAAY,OAAO,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5G,CAAC;QACD,MAAM,IAAI,GAA4B,EAAE,CAAC;QACzC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YAChC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAC/B,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC/B,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;gBAChD,OAAO;YACT,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe,IAAI,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC;gBAC/D,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,GAAG,4BAA4B,KAAK,IAAI,CAAC,CAAC;gBAC7F,CAAC;gBACD,IAAI,CAAC,MAAM,CAAC,IAAc,CAAC,GAAG,MAAM,CAAC;gBACrC,OAAO;YACT,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,IAAc,CAAC,GAAG,KAAK,CAAC;QACtC,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;QAChG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAa,EAAU,EAAE;IAC5D,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/E,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAC1D,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAa,EAAU,EAAE,CACzD,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAExF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAU,EAAE;IAClD,MAAM,IAAI,GAAG,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACjE,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7D,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAoC,EAAE,OAAiB,EAAU,EAAE;IAC9F,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9F,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC,CAAC"}

package/lib/shared/output.d.ts

@@ -0,0 +1,25 @@
+import type { LifecycleResult } from '../lifecycle/types.js';
+export declare const renderSnapshotCsv: (result: LifecycleResult) => string;
+export declare const renderLifecycleCsv: (result: LifecycleResult) => string;
+export declare const renderRestoreCsv: (result: LifecycleResult) => string;
+export declare const renderStripCsv: (result: LifecycleResult) => string;
+export declare const renderProvisionCsv: (result: {
+    users: Array<{
+        key: string;
+        id?: string;
+        userName?: string;
+        username?: string;
+        personas: string[];
+        matchedBy: string | null;
+        status: string;
+        actions: string[];
+        errors: string[];
+        relatedRecords?: Array<{
+            relationship: string;
+            phase: string;
+            sobject: string;
+            action: string;
+            error?: string;
+        }>;
+    }>;
+}) => string;

package/lib/shared/output.js

@@ -0,0 +1,74 @@
+import { lifecycleToCsvRows } from '../lifecycle/output.js';
+import { serializeCsv } from './csv.js';
+const lifecycleColumns = ['key', 'id', 'status', 'actions', 'skipped', 'warnings', 'errors'];
+const joinValues = (values) => values.map(String).join('; ');
+export const renderSnapshotCsv = (result) => serializeCsv(result.users.map((user) => ({
+    key: user.key,
+    id: user.id ?? '',
+    status: user.status,
+    actions: joinValues(user.actions.map((action) => action.key)),
+    skipped: joinValues(user.skipped.map((action) => action.key)),
+    warnings: joinValues(user.warnings),
+    errors: joinValues(user.errors),
+})), lifecycleColumns);
+const lifecycleRows = (result) => lifecycleToCsvRows(result);
+export const renderLifecycleCsv = (result) => serializeCsv(lifecycleRows(result), [
+    'userKey',
+    'userId',
+    'userName',
+    'username',
+    'wasFrozen',
+    'status',
+    'action',
+    'error',
+]);
+export const renderRestoreCsv = (result) => serializeCsv(lifecycleRows(result), [
+    'userKey',
+    'userId',
+    'userName',
+    'username',
+    'status',
+    'action',
+    'category',
+    'name',
+    'error',
+]);
+export const renderStripCsv = (result) => serializeCsv(lifecycleRows(result), [
+    'userKey',
+    'userId',
+    'userName',
+    'username',
+    'status',
+    'action',
+    'category',
+    'itemId',
+    'itemApiName',
+    'error',
+]);
+export const renderProvisionCsv = (result) => serializeCsv(result.users.flatMap((user) => {
+    const base = {
+        userKey: user.key,
+        userId: user.id ?? '',
+        userName: user.userName ?? '',
+        username: user.username ?? '',
+        personas: joinValues(user.personas),
+        matchedBy: user.matchedBy ?? '',
+        status: user.status,
+    };
+    const actionRows = user.actions.map((action) => ({ ...base, action, detail: '', error: '' }));
+    // Related records reuse the existing ten columns: `action=related` plus a composed detail.
+    const relatedRows = (user.relatedRecords ?? []).map((related) => ({
+        ...base,
+        action: 'related',
+        detail: `${related.relationship} ${related.phase} ${related.sobject} ${related.action}`,
+        error: related.error ?? '',
+    }));
+    const errorRows = user.errors.map((error) => ({ ...base, action: '', detail: '', error }));
+    const populatedRows = actionRows.concat(relatedRows);
+    return populatedRows.concat(errorRows.length > 0
+        ? errorRows
+        : populatedRows.length > 0
+            ? []
+            : [{ ...base, action: '', detail: '', error: '' }]);
+}), ['userKey', 'userId', 'userName', 'username', 'personas', 'matchedBy', 'status', 'action', 'detail', 'error']);
+//# sourceMappingURL=output.js.map

package/lib/shared/output.js.map

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

package/lib/shared/prompt.d.ts

@@ -0,0 +1,4 @@
+export declare const confirmWithTimeout: (confirm: (message: string) => Promise<boolean>, message: string, timeoutMs?: number) => Promise<{
+    confirmed: boolean;
+    timedOut: boolean;
+}>;

package/lib/shared/prompt.js

@@ -0,0 +1,15 @@
+export const confirmWithTimeout = async (confirm, message, timeoutMs = 10_000) => {
+    let timer;
+    try {
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ confirmed: false, timedOut: true }), timeoutMs);
+            timer.unref();
+        });
+        return await Promise.race([confirm(message).then((confirmed) => ({ confirmed, timedOut: false })), timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+};
+//# sourceMappingURL=prompt.js.map

package/lib/shared/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/shared/prompt.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,OAA8C,EAC9C,OAAe,EACf,SAAS,GAAG,MAAM,EACkC,EAAE;IACtD,IAAI,KAAiC,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,IAAI,OAAO,CAA4C,CAAC,OAAO,EAAE,EAAE;YACxF,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;YACnF,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;IACtH,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC,CAAC"}

package/lib/shared/sfUtils.d.ts

@@ -0,0 +1,19 @@
+export type SaveError = {
+    message: string;
+    statusCode?: string;
+    fields?: string[];
+};
+export type SaveResult = {
+    success: boolean;
+    id?: string;
+    errors: SaveError[];
+};
+export declare const asArray: <T>(value: T | T[]) => T[];
+export declare const readJson: (path: string) => Promise<unknown>;
+export declare const readJsonOrThrow: (path: string, message: (path: string, error: string) => string) => Promise<unknown>;
+export declare const formatSaveError: (error: SaveError) => string;
+export declare const pushErrors: (errors: string[], saveResults: SaveResult | SaveResult[] | undefined) => void;
+export declare const esc: (value: string) => string;
+export declare const soqlIn: (values: string[]) => string;
+export declare const batch: <T>(items: T[], size: number) => T[][];
+export declare const runBatches: <T, R>(items: T[], size: number, fn: (item: T) => Promise<R>) => Promise<R[]>;

package/lib/shared/sfUtils.js

@@ -0,0 +1,42 @@
+import { readFile } from 'node:fs/promises';
+import { DefinitionError } from '../provisioning/errors.js';
+export const asArray = (value) => (Array.isArray(value) ? value : [value]);
+export const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));
+export const readJsonOrThrow = async (path, message) => {
+    try {
+        return await readJson(path);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new DefinitionError('errorInvalidJson', message(path, detail), { path, detail });
+    }
+};
+export const formatSaveError = (error) => {
+    const fieldSuffix = error.fields && error.fields.length > 0 ? ` (fields: ${error.fields.join(', ')})` : '';
+    return error.statusCode ? `${error.statusCode}: ${error.message}${fieldSuffix}` : error.message;
+};
+export const pushErrors = (errors, saveResults) => {
+    if (!saveResults)
+        return;
+    for (const result of asArray(saveResults)) {
+        if (!result.success)
+            errors.push(...result.errors.map((err) => formatSaveError(err)));
+    }
+};
+export const esc = (value) => value.replaceAll('\\', '\\\\').replaceAll("'", "\\'");
+export const soqlIn = (values) => values.map((value) => `'${esc(value)}'`).join(',');
+export const batch = (items, size) => items.reduce((groups, item, index) => {
+    if (index % size === 0)
+        groups.push([]);
+    groups[groups.length - 1].push(item);
+    return groups;
+}, []);
+export const runBatches = async (items, size, fn) => {
+    const itemBatches = batch(items, size);
+    return itemBatches.reduce(async (accPromise, itemBatch) => {
+        const acc = await accPromise;
+        const next = await Promise.all(itemBatch.map(fn));
+        return acc.concat(next);
+    }, Promise.resolve([]));
+};
+//# sourceMappingURL=sfUtils.js.map

package/lib/shared/sfUtils.js.map

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

package/lib/shared/userFields.d.ts

@@ -0,0 +1,23 @@
+import type { Connection } from '@salesforce/core';
+import { type UserFieldMeta } from '../provisioning/planner.js';
+export type SobjectRecordTypeInfo = {
+    available: boolean;
+    isPersonType: boolean;
+};
+export type SobjectDescribeInfo = {
+    name: string;
+    queryable: boolean;
+    fields: Map<string, UserFieldMeta>;
+    recordTypeInfos: Map<string, SobjectRecordTypeInfo>;
+};
+/**
+ * Per-run describe cache. Owned by the caller (the provisioning use case) rather than
+ * this module so it cannot leak between orgs or between tests in the same process.
+ */
+export type SobjectDescribeCache = Map<string, SobjectDescribeInfo>;
+/** Describe any sObject, reusing the per-run cache when one is supplied. */
+export declare const describeSobject: (conn: Connection, sobject: string, cache?: SobjectDescribeCache) => Promise<SobjectDescribeInfo>;
+/** Describe an sObject and project it into the field map callers need. */
+export declare const describeSobjectFields: (conn: Connection, sobject: string, cache?: SobjectDescribeCache) => Promise<Map<string, UserFieldMeta>>;
+/** Describe the User sObject and project it into the field map callers need. */
+export declare const describeUserFields: (conn: Connection, cache?: SobjectDescribeCache) => Promise<Map<string, UserFieldMeta>>;

package/lib/shared/userFields.js

@@ -0,0 +1,41 @@
+import { buildFieldMap } from '../provisioning/planner.js';
+const projectFields = (fields) => buildFieldMap(fields.map((field) => ({
+    name: field.name,
+    createable: field.createable,
+    updateable: field.updateable,
+    filterable: field.filterable,
+    // Older describe responses do not include this flag; preserve that distinction
+    // so preflight can treat an explicit false as inaccessible without breaking them.
+    ...(field.readable === undefined ? {} : { readable: field.readable }),
+    externalId: field.externalId,
+    // Describes that omit `unique` must not gain an own property holding `undefined`.
+    ...(field.unique === undefined ? {} : { unique: field.unique }),
+    ...(field.caseSensitive === undefined ? {} : { caseSensitive: field.caseSensitive }),
+    isBoolean: field.type === 'boolean',
+})));
+/** Describe any sObject, reusing the per-run cache when one is supplied. */
+export const describeSobject = async (conn, sobject, cache) => {
+    const cacheKey = sobject.toLowerCase();
+    const cached = cache?.get(cacheKey);
+    if (cached)
+        return cached;
+    const described = (await conn.describe(sobject));
+    const info = {
+        name: described.name ?? sobject,
+        // Standard describes always carry `queryable`; treat an absent flag as queryable
+        // so a trimmed test fixture is not reported as an unreadable object.
+        queryable: described.queryable !== false,
+        fields: projectFields(described.fields),
+        recordTypeInfos: new Map((described.recordTypeInfos ?? []).map((recordType) => [
+            recordType.recordTypeId,
+            { available: recordType.available !== false, isPersonType: recordType.isPersonType === true },
+        ])),
+    };
+    cache?.set(cacheKey, info);
+    return info;
+};
+/** Describe an sObject and project it into the field map callers need. */
+export const describeSobjectFields = async (conn, sobject, cache) => (await describeSobject(conn, sobject, cache)).fields;
+/** Describe the User sObject and project it into the field map callers need. */
+export const describeUserFields = async (conn, cache) => describeSobjectFields(conn, 'User', cache);
+//# sourceMappingURL=userFields.js.map

package/lib/shared/userFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userFields.js","sourceRoot":"","sources":["../../src/shared/userFields.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAsB,MAAM,4BAA4B,CAAC;AA0C/E,MAAM,aAAa,GAAG,CAAC,MAA2B,EAA8B,EAAE,CAChF,aAAa,CACX,MAAM,CAAC,GAAG,CACR,CAAC,KAAK,EAAiB,EAAE,CAAC,CAAC;IACzB,IAAI,EAAE,KAAK,CAAC,IAAI;IAChB,UAAU,EAAE,KAAK,CAAC,UAAU;IAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;IAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;IAC5B,+EAA+E;IAC/E,kFAAkF;IAClF,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IACrE,UAAU,EAAE,KAAK,CAAC,UAAU;IAC5B,kFAAkF;IAClF,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAC/D,GAAG,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC;IACpF,SAAS,EAAE,KAAK,CAAC,IAAI,KAAK,SAAS;CACpC,CAAC,CACH,CACF,CAAC;AAEJ,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,IAAgB,EAChB,OAAe,EACf,KAA4B,EACE,EAAE;IAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACvC,MAAM,MAAM,GAAG,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,SAAS,GAAG,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAK9C,CAAC;IACF,MAAM,IAAI,GAAwB;QAChC,IAAI,EAAE,SAAS,CAAC,IAAI,IAAI,OAAO;QAC/B,iFAAiF;QACjF,qEAAqE;QACrE,SAAS,EAAE,SAAS,CAAC,SAAS,KAAK,KAAK;QACxC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC;QACvC,eAAe,EAAE,IAAI,GAAG,CACtB,CAAC,SAAS,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC;YACpD,UAAU,CAAC,YAAY;YACvB,EAAE,SAAS,EAAE,UAAU,CAAC,SAAS,KAAK,KAAK,EAAE,YAAY,EAAE,UAAU,CAAC,YAAY,KAAK,IAAI,EAAE;SAC9F,CAAC,CACH;KACF,CAAC;IACF,KAAK,EAAE,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3B,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,EACxC,IAAgB,EAChB,OAAe,EACf,KAA4B,EACS,EAAE,CAAC,CAAC,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AAE/F,gFAAgF;AAChF,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,IAAgB,EAChB,KAA4B,EACS,EAAE,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC"}

package/lib/spec/index.d.ts

@@ -0,0 +1,10 @@
+export { personaDefinitionsFileSchema, personaSchema } from './personaDefinitions.js';
+export { relatedCatalogSchema, relationshipDefSchema } from './relatedCatalog.js';
+export { snapshotFileSchema, userSnapshotEntrySchema } from './snapshot.js';
+export { userInputSchema, usersDefinitionFileSchema, USERS_CSV_COLUMNS } from './usersDefinition.js';
+export { parsePersonaDefinitions, parseRelatedCatalog, parseSnapshot, parseUsersDefinition, safeParsePersonaDefinitions, safeParseRelatedCatalog, safeParseSnapshot, safeParseUsersDefinition, validatePersonaDefinitionsText, validateRelatedCatalogText, validateSnapshotText, validateUsersDefinitionText, } from './parse.js';
+export type { PersonaDefinition, PersonaDefinitionsFile } from './personaDefinitions.js';
+export type { RelatedCatalog, RelationshipDef, RelationshipMode, RelationshipPhase, SourceExpr, } from './relatedCatalog.js';
+export type { UserSnapshotEntry, UserSnapshotFile } from './snapshot.js';
+export type { UserInput, UsersDefinitionFile } from './usersDefinition.js';
+export type { SchemaFailure, SchemaIssue, SchemaResult, SchemaSuccess } from './parse.js';

package/lib/spec/index.js

@@ -0,0 +1,6 @@
+export { personaDefinitionsFileSchema, personaSchema } from './personaDefinitions.js';
+export { relatedCatalogSchema, relationshipDefSchema } from './relatedCatalog.js';
+export { snapshotFileSchema, userSnapshotEntrySchema } from './snapshot.js';
+export { userInputSchema, usersDefinitionFileSchema, USERS_CSV_COLUMNS } from './usersDefinition.js';
+export { parsePersonaDefinitions, parseRelatedCatalog, parseSnapshot, parseUsersDefinition, safeParsePersonaDefinitions, safeParseRelatedCatalog, safeParseSnapshot, safeParseUsersDefinition, validatePersonaDefinitionsText, validateRelatedCatalogText, validateSnapshotText, validateUsersDefinitionText, } from './parse.js';
+//# sourceMappingURL=index.js.map

package/lib/spec/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/spec/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACrG,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,uBAAuB,EACvB,iBAAiB,EACjB,wBAAwB,EACxB,8BAA8B,EAC9B,0BAA0B,EAC1B,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/lib/spec/parse.d.ts

@@ -0,0 +1,32 @@
+import { DefinitionError } from '../provisioning/errors.js';
+import type { PersonaDefinitionsFile } from './personaDefinitions.js';
+import type { RelatedCatalog } from './relatedCatalog.js';
+import type { UserSnapshotFile } from './snapshot.js';
+import type { UsersDefinitionFile } from './usersDefinition.js';
+export type SchemaIssue = {
+    path: Array<string | number>;
+    message: string;
+};
+export type SchemaSuccess<T> = {
+    ok: true;
+    data: T;
+    issues: [];
+};
+export type SchemaFailure = {
+    ok: false;
+    issues: SchemaIssue[];
+    error: DefinitionError;
+};
+export type SchemaResult<T> = SchemaSuccess<T> | SchemaFailure;
+export declare const safeParsePersonaDefinitions: (input: unknown) => SchemaResult<PersonaDefinitionsFile>;
+export declare const parsePersonaDefinitions: (input: unknown) => PersonaDefinitionsFile;
+export declare const validatePersonaDefinitionsText: (text: string) => SchemaResult<PersonaDefinitionsFile>;
+export declare const safeParseUsersDefinition: (input: unknown) => SchemaResult<UsersDefinitionFile>;
+export declare const parseUsersDefinition: (input: unknown) => UsersDefinitionFile;
+export declare const validateUsersDefinitionText: (text: string) => SchemaResult<UsersDefinitionFile>;
+export declare const safeParseRelatedCatalog: (input: unknown) => SchemaResult<RelatedCatalog>;
+export declare const parseRelatedCatalog: (input: unknown) => RelatedCatalog;
+export declare const validateRelatedCatalogText: (text: string) => SchemaResult<RelatedCatalog>;
+export declare const safeParseSnapshot: (input: unknown) => SchemaResult<UserSnapshotFile>;
+export declare const parseSnapshot: (input: unknown) => UserSnapshotFile;
+export declare const validateSnapshotText: (text: string) => SchemaResult<UserSnapshotFile>;