@aopslabs/aops 0.2.0

package/dist/lib/community-diagnostic.js

@@ -0,0 +1,237 @@
+const SAFE_CODE = /^[a-z][a-z0-9_]{2,127}$/;
+const SAFE_SQLSTATE = /^[0-9A-Z]{5}$/;
+const MAX_TEXT_LENGTH = 1_000;
+function redacted(value) {
+    return value
+        .replace(/postgres(?:ql)?:\/\/[^\s"'`]+/gi, 'postgresql://[REDACTED]')
+        .replace(/((?:password|passwd|secret|token|api[_-]?key|authorization)\s*[=:]\s*)[^\s,;]+/gi, '$1[REDACTED]')
+        .replace(/(--(?:password|passwd|secret|token|api[_-]?key)\s+)[^\s]+/gi, '$1[REDACTED]')
+        .replace(/(\bBearer\s+)[A-Za-z0-9._~+/-]+/gi, '$1[REDACTED]')
+        .replace(/("(?:password|passwd|secret|token|apiKey|authorization)"\s*:\s*")[^"]*(")/gi, '$1[REDACTED]$2')
+        .slice(0, MAX_TEXT_LENGTH);
+}
+function errorRecord(error) {
+    return error && typeof error === 'object' && !Array.isArray(error)
+        ? error
+        : {};
+}
+function messageCode(error) {
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    const matched = /\b(?:aops|community|postgres|setup)_[a-z0-9_]+\b/i.exec(message)?.[0]?.toLowerCase();
+    return matched && SAFE_CODE.test(matched) ? matched : undefined;
+}
+function safeCauseCode(error, fallback) {
+    const record = errorRecord(error);
+    const explicit = String(record.code ?? '').toUpperCase();
+    if (SAFE_SQLSTATE.test(explicit))
+        return explicit;
+    return messageCode(error) ?? fallback;
+}
+function categoryFor(code) {
+    if (SAFE_SQLSTATE.test(code) || /postgres|pg_|database|sql/.test(code))
+        return 'postgresql';
+    if (/history_receipt|receipt_identity|intent_not_reconciled|local_state|journal/.test(code))
+        return 'local-state';
+    if (/migration|schema|lineage|receipt/.test(code))
+        return 'migration';
+    if (/config|policy|env|tls/.test(code))
+        return 'configuration';
+    if (/runtime|server|process|health|source_drift|build(?:_identity)?_drift/.test(code))
+        return 'runtime';
+    return 'unknown';
+}
+function inferredPhase(code, fallback) {
+    if (/connection|connect|auth|unreachable|tls/.test(code) || SAFE_SQLSTATE.test(code))
+        return 'connect';
+    if (/history_receipt|receipt_identity|intent_not_reconciled|state_missing/.test(code))
+        return 'persist-local-state';
+    if (/lineage|schema|catalog|receipt_(?:count|mismatch|missing)/.test(code))
+        return 'inspect-schema';
+    if (/plan/.test(code))
+        return 'plan';
+    if (/snapshot|backup/.test(code))
+        return 'snapshot';
+    if (/post_commit|final_|verification|verify/.test(code))
+        return 'verify';
+    if (/source_drift|build(?:_identity)?_drift/.test(code))
+        return 'verify';
+    if (/migration|apply/.test(code))
+        return 'apply';
+    if (/start|health|process/.test(code))
+        return 'start-server';
+    return fallback;
+}
+function guidance(code) {
+    if (/community_native_(?:prior_application_)?(?:source|build(?:_identity)?)_drift/.test(code)) {
+        return {
+            summary: 'The installed npm server package no longer matches the source or build fingerprint AOPS previously verified.',
+            nextActions: Object.freeze([
+                'Reinstall the matching public `@aopslabs/aops` and `@aopslabs/aops-server` packages separately.',
+                'Re-run `aops setup init` for the selected path after the verified package bytes have been restored.',
+            ]),
+        };
+    }
+    if (/history_receipt|receipt_identity|intent_not_reconciled/.test(code)) {
+        return {
+            summary: 'Local migration bookkeeping disagrees with the current installation, not necessarily with PostgreSQL.',
+            nextActions: Object.freeze([
+                'Re-run `aops setup init` for the selected path so AOPS can inspect the connected database again.',
+                'Do not reset the operator-owned PostgreSQL database for a local receipt or identity mismatch.',
+            ]),
+        };
+    }
+    if (/lineage_unknown|schema_mismatch|receipt_(?:count|mismatch|missing)|tables_partial/.test(code)) {
+        return {
+            summary: 'The connected PostgreSQL schema could not be matched to the expected AOPS-owned structure.',
+            nextActions: Object.freeze([
+                'Inspect the reported AOPS-owned table, column, key, index, or constraint differences.',
+                'Correct only the reported structural conflict, then re-run `aops setup init`; do not delete operator-owned data.',
+            ]),
+        };
+    }
+    if (/connection|connect|auth|unreachable|tls/.test(code) || SAFE_SQLSTATE.test(code)) {
+        return {
+            summary: 'AOPS could not complete the PostgreSQL connection step.',
+            nextActions: Object.freeze([
+                'Verify the selected private PostgreSQL configuration and TLS policy, then retry setup.',
+            ]),
+        };
+    }
+    return {
+        summary: 'AOPS could not complete the current setup step.',
+        nextActions: Object.freeze([
+            'Review the diagnostic phase and cause code, then retry the same setup path after correcting that condition.',
+        ]),
+    };
+}
+function safeDetails(details, error) {
+    const output = {};
+    for (const [key, raw] of Object.entries(details ?? {})) {
+        if (!/^[a-z][a-zA-Z0-9]{0,63}$/.test(key))
+            continue;
+        if (typeof raw === 'string')
+            output[key] = redacted(raw);
+        else if (typeof raw === 'number' && Number.isFinite(raw))
+            output[key] = raw;
+        else if (typeof raw === 'boolean' || raw === null)
+            output[key] = raw;
+        else if (Array.isArray(raw) && raw.every((entry) => typeof entry === 'string')) {
+            output[key] = Object.freeze(raw.slice(0, 100).map((entry) => redacted(entry)));
+        }
+    }
+    const sqlState = String(errorRecord(error).code ?? '').toUpperCase();
+    if (SAFE_SQLSTATE.test(sqlState))
+        output.sqlState = sqlState;
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    const semanticPrefix = 'community_strict_semantic_schema_mismatch:';
+    if (message.startsWith(semanticPrefix)) {
+        try {
+            const parsed = JSON.parse(message.slice(semanticPrefix.length));
+            if (Number.isSafeInteger(parsed.differenceCount) && Number(parsed.differenceCount) >= 0) {
+                output.differenceCount = Number(parsed.differenceCount);
+            }
+            if (typeof parsed.truncated === 'boolean')
+                output.differencesTruncated = parsed.truncated;
+            if (Array.isArray(parsed.differences)) {
+                const schemaDifferences = parsed.differences.slice(0, 64).flatMap((candidate) => {
+                    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
+                        return [];
+                    const row = candidate;
+                    const section = String(row.section ?? '');
+                    const kind = String(row.kind ?? '');
+                    const key = String(row.key ?? '');
+                    const fields = Array.isArray(row.changedFields) &&
+                        row.changedFields.every((field) => typeof field === 'string')
+                        ? row.changedFields.join(',')
+                        : '';
+                    if (!['relations', 'columns', 'constraints', 'indexes'].includes(section) ||
+                        !['missing', 'unexpected', 'changed'].includes(kind) || key.length < 1)
+                        return [];
+                    return [redacted(`${section} ${kind} ${key}${fields ? ` fields=${fields}` : ''}`)];
+                });
+                if (schemaDifferences.length > 0)
+                    output.schemaDifferences = Object.freeze(schemaDifferences);
+            }
+        }
+        catch {
+        }
+    }
+    return Object.freeze(output);
+}
+export function createCommunityDiagnostic(error, defaults = {}) {
+    if (error instanceof CommunityDiagnosticError)
+        return error.diagnostic;
+    const fallbackCode = defaults.code && SAFE_CODE.test(defaults.code)
+        ? defaults.code
+        : 'community_operation_failed';
+    const causeCode = safeCauseCode(error, fallbackCode);
+    const inferred = guidance(causeCode);
+    return Object.freeze({
+        schemaVersion: 1,
+        code: fallbackCode === 'community_operation_failed' ? causeCode : fallbackCode,
+        phase: inferredPhase(causeCode, defaults.phase ?? 'unknown'),
+        summary: redacted(defaults.summary ?? inferred.summary),
+        cause: Object.freeze({ code: causeCode, category: categoryFor(causeCode) }),
+        nextActions: Object.freeze((defaults.nextActions ?? inferred.nextActions).map((action) => redacted(action))),
+        details: safeDetails(defaults.details, error),
+    });
+}
+export function formatCommunityDiagnostic(diagnostic) {
+    const lines = [
+        diagnostic.code,
+        `Stage: ${diagnostic.phase}`,
+        `Cause: ${diagnostic.cause.code}`,
+        `Reason: ${diagnostic.summary}`,
+    ];
+    for (const [key, value] of Object.entries(diagnostic.details)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                lines.push(`Detail: ${key}: ${item}`);
+        }
+        else {
+            lines.push(`Detail: ${key}: ${String(value)}`);
+        }
+    }
+    for (const action of diagnostic.nextActions)
+        lines.push(`Next: ${action}`);
+    return lines.join('\n');
+}
+export class CommunityDiagnosticError extends Error {
+    diagnostic;
+    constructor(diagnostic, options) {
+        super(formatCommunityDiagnostic(diagnostic), options);
+        this.name = 'CommunityDiagnosticError';
+        this.diagnostic = diagnostic;
+    }
+}
+export function isCommunityDiagnosticV1(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const candidate = value;
+    const causeCategories = ['configuration', 'postgresql', 'migration', 'local-state', 'runtime', 'unknown'];
+    const safeText = (text) => typeof text === 'string' && text.length > 0 &&
+        text.length <= MAX_TEXT_LENGTH && redacted(text) === text;
+    const details = candidate.details && typeof candidate.details === 'object' && !Array.isArray(candidate.details)
+        ? Object.entries(candidate.details)
+        : null;
+    return candidate.schemaVersion === 1 && typeof candidate.code === 'string' && SAFE_CODE.test(candidate.code) &&
+        typeof candidate.phase === 'string' &&
+        ['configuration', 'connect', 'inspect-schema', 'plan', 'snapshot', 'apply', 'verify',
+            'persist-local-state', 'start-server', 'readiness', 'operation', 'unknown'].includes(candidate.phase) &&
+        safeText(candidate.summary) && Boolean(candidate.cause) && typeof candidate.cause?.code === 'string' &&
+        (SAFE_CODE.test(candidate.cause.code) || SAFE_SQLSTATE.test(candidate.cause.code)) &&
+        typeof candidate.cause?.category === 'string' && causeCategories.includes(candidate.cause.category) &&
+        Array.isArray(candidate.nextActions) && candidate.nextActions.length > 0 && candidate.nextActions.length <= 8 &&
+        candidate.nextActions.every(safeText) && details !== null && details.length <= 64 &&
+        details.every(([key, detail]) => /^[a-z][a-zA-Z0-9]{0,63}$/.test(key) && (detail === null || typeof detail === 'boolean' ||
+            (typeof detail === 'number' && Number.isFinite(detail)) || safeText(detail) ||
+            (Array.isArray(detail) && detail.length <= 100 && detail.every(safeText))));
+}
+export function asCommunityDiagnosticError(error, defaults = {}) {
+    if (error instanceof CommunityDiagnosticError)
+        return error;
+    return new CommunityDiagnosticError(createCommunityDiagnostic(error, defaults), { cause: error });
+}
+export function redactCommunityDiagnosticText(value) {
+    return redacted(String(value ?? ''));
+}