@timo972/cc-router 0.12.1 → 0.12.2-rc.0

package/dist/telemetry/runtime.js

@@ -0,0 +1,306 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { context, propagation, trace } from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import { BatchSpanProcessor, ParentBasedSampler, SamplingDecision, TraceIdRatioBasedSampler, } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { createTelemetryConsentGate, getTelemetrySnapshot, } from "../config/telemetry.js";
+import { TELEMETRY_PATH } from "../config/paths.js";
+import { getCurrentVersion } from "../utils/self-update.js";
+import { createPostHogOtlpExporters } from "./otel-exporters.js";
+import { createPostHogTelemetryClient } from "./posthog-client.js";
+import { rebuildSanitizedException, sanitizeException } from "./privacy.js";
+const TRACE_SAMPLE_RATIO = 0.1;
+const QUEUE_SIZE = 100;
+const BATCH_SIZE = 20;
+const EXPORT_DELAY_MS = 500;
+const EXPORT_TIMEOUT_MS = 2_000;
+/**
+ * Fatal exceptions cannot be sent from a crashing process (Node exits as soon
+ * as the monitor returns), so the sanitized record is written here
+ * synchronously and delivered by the next start that still holds consent.
+ */
+const MAX_PENDING_EXCEPTIONS = 20;
+// Resolved lazily (like the state path itself) so the module loads even when
+// the paths module is partially mocked; every caller runs inside a try/catch.
+function pendingExceptionsPath() {
+    return `${TELEMETRY_PATH}.pending.json`;
+}
+function readPendingExceptions() {
+    try {
+        const parsed = JSON.parse(readFileSync(pendingExceptionsPath(), "utf8"));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function persistFatalException(exception, snapshot) {
+    const { error: _error, ...record } = exception;
+    const pending = [
+        ...readPendingExceptions().slice(-(MAX_PENDING_EXCEPTIONS - 1)),
+        { installationId: snapshot.state.installId, consentGeneration: snapshot.state.consentGeneration, exception: record },
+    ];
+    const target = pendingExceptionsPath();
+    const candidate = `${target}.${process.pid}.tmp`;
+    writeFileSync(candidate, JSON.stringify(pending), { mode: 0o600 });
+    renameSync(candidate, target);
+}
+/** Deliver records left by a crash, only under the consent they were written with. */
+function deliverPendingExceptions(consent, posthog) {
+    try {
+        const records = readPendingExceptions();
+        // Remove first: a crash during delivery must never resend the same records.
+        unlinkSync(pendingExceptionsPath());
+        const current = consent.getSnapshot();
+        if (!current)
+            return;
+        for (const raw of records) {
+            if (typeof raw !== "object" || raw === null)
+                continue;
+            const record = raw;
+            if (record.installationId !== current.state.installId)
+                continue;
+            // A different generation means an explicit choice happened in between.
+            if (record.consentGeneration !== current.state.consentGeneration)
+                continue;
+            const exception = rebuildSanitizedException(record.exception);
+            if (exception)
+                posthog.captureException(exception, current.state.consentGeneration);
+        }
+    }
+    catch {
+        // Nothing pending, or an unreadable file: never affects startup.
+    }
+}
+/** Telemetry must never join or emit a distributed trace outside this process. */
+export const noopPropagator = {
+    inject() { },
+    extract(carrierContext) {
+        return carrierContext;
+    },
+    fields() {
+        return [];
+    },
+};
+let activeRuntime;
+function osFamily() {
+    switch (process.platform) {
+        case "darwin": return "macos";
+        case "linux": return "linux";
+        case "win32": return "windows";
+        default: return "other";
+    }
+}
+function cpuArchitecture() {
+    return process.arch === "arm64" || process.arch === "x64" ? process.arch : "other";
+}
+/** Loopback OTLP endpoints for the telemetry test suite; never read in production. */
+function testOtlpUrls() {
+    if (process.env["NODE_ENV"] !== "test")
+        return {};
+    return {
+        traceUrl: process.env["CC_ROUTER_TEST_OTLP_TRACE_URL"],
+        logUrl: process.env["CC_ROUTER_TEST_OTLP_LOG_URL"],
+    };
+}
+function exporterOptions(consent, options) {
+    const test = testOtlpUrls();
+    return {
+        getSnapshot: () => consent.getSnapshot(),
+        traceUrl: options.traceUrl ?? test.traceUrl,
+        logUrl: options.logUrl ?? test.logUrl,
+    };
+}
+function telemetryResource(snapshot, runtimeMode) {
+    return resourceFromAttributes({
+        "service.name": "cc-router",
+        "service.version": getCurrentVersion(),
+        "service.instance.id": snapshot.state.installId,
+        "process.runtime.version": process.versions.node,
+        "os.type": osFamily(),
+        "host.arch": cpuArchitecture(),
+        "cc_router.runtime_mode": runtimeMode,
+    });
+}
+function consentGatedSampler(consent) {
+    const delegate = new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(TRACE_SAMPLE_RATIO) });
+    return {
+        shouldSample(...args) {
+            return consent.getSnapshot()
+                ? delegate.shouldSample(...args)
+                : { decision: SamplingDecision.NOT_RECORD };
+        },
+        toString: () => `ConsentGated{${delegate.toString()}}`,
+    };
+}
+function startTracing(consent, snapshot, options) {
+    const { spanExporter } = createPostHogOtlpExporters(exporterOptions(consent, options));
+    const provider = new NodeTracerProvider({
+        resource: telemetryResource(snapshot, options.runtimeMode),
+        sampler: consentGatedSampler(consent),
+        spanProcessors: [new BatchSpanProcessor(spanExporter, {
+                maxQueueSize: QUEUE_SIZE,
+                maxExportBatchSize: BATCH_SIZE,
+                scheduledDelayMillis: EXPORT_DELAY_MS,
+                exportTimeoutMillis: EXPORT_TIMEOUT_MS,
+            })],
+    });
+    // register() installs the AsyncLocalStorage context manager together with the
+    // global tracer provider; the inert propagator keeps trace ids off the wire.
+    provider.register({ propagator: noopPropagator });
+    trace.setGlobalTracerProvider(provider);
+    return provider;
+}
+function settleWithin(operation, deadlineMs) {
+    const bounded = Number.isFinite(deadlineMs) ? Math.max(0, Math.min(10_000, Math.floor(deadlineMs))) : 0;
+    let timer;
+    return Promise.race([
+        Promise.resolve().then(operation).catch(() => undefined),
+        new Promise(resolve => {
+            timer = setTimeout(resolve, bounded);
+            timer.unref?.();
+        }),
+    ]).then(() => undefined).catch(() => undefined).finally(() => clearTimeout(timer));
+}
+/**
+ * Start (or upgrade to tracing) the one telemetry runtime of this process.
+ * Spans are created manually through the facade; no instrumentation is loaded.
+ */
+export function startTelemetryRuntime(options) {
+    try {
+        const existing = activeRuntime;
+        if (existing) {
+            if (options.tracing && !existing.tracerProvider && !existing.shuttingDown) {
+                existing.tracerProvider = startTracing(existing.consent, existing.snapshot, options);
+            }
+            return !existing.shuttingDown;
+        }
+        const snapshot = getTelemetrySnapshot();
+        if (!snapshot.enabled)
+            return false;
+        let discardQueuedTelemetry = () => undefined;
+        const consent = createTelemetryConsentGate(getTelemetrySnapshot, () => discardQueuedTelemetry());
+        const { logExporter } = createPostHogOtlpExporters(exporterOptions(consent, options));
+        const logProcessor = new BatchLogRecordProcessor({
+            exporter: logExporter,
+            maxQueueSize: QUEUE_SIZE,
+            maxExportBatchSize: BATCH_SIZE,
+            scheduledDelayMillis: EXPORT_DELAY_MS,
+            exportTimeoutMillis: EXPORT_TIMEOUT_MS,
+        });
+        const posthog = createPostHogTelemetryClient({ getSnapshot: () => consent.getSnapshot() });
+        const fatalMonitor = (error) => {
+            try {
+                const current = consent.getSnapshot();
+                if (!current)
+                    return;
+                const exception = sanitizeException(error, {
+                    category: "runtime",
+                    reason: "other",
+                    runtimeMode: options.runtimeMode,
+                }, {
+                    installationId: current.state.installId,
+                    diagnosticId: randomUUID(),
+                });
+                if (!exception)
+                    return;
+                // Node's default handler prints the Error itself; add correlation only.
+                // The process exits as soon as this monitor returns, so the record is
+                // persisted synchronously and sent by the next consenting start.
+                persistFatalException(exception, current);
+                console.error(`[cc-router] Unexpected runtime failure (diagnostic ID: ${exception.diagnosticId})`);
+            }
+            catch {
+                // The monitor observes only; it never changes Node's crash behavior.
+            }
+        };
+        const runtime = {
+            loggerProvider: new LoggerProvider({
+                resource: telemetryResource(snapshot, options.runtimeMode),
+                processors: [logProcessor],
+            }),
+            posthog,
+            consent,
+            snapshot,
+            fatalMonitor,
+            exitCleanup: () => process.removeListener("uncaughtExceptionMonitor", fatalMonitor),
+            shuttingDown: false,
+        };
+        discardQueuedTelemetry = () => {
+            posthog.discardPending();
+            void logProcessor.shutdown().catch(() => undefined);
+            void runtime.tracerProvider?.shutdown().catch(() => undefined);
+        };
+        logs.setGlobalLoggerProvider(runtime.loggerProvider);
+        if (options.tracing)
+            runtime.tracerProvider = startTracing(consent, snapshot, options);
+        process.on("uncaughtExceptionMonitor", fatalMonitor);
+        process.once("exit", runtime.exitCleanup);
+        activeRuntime = runtime;
+        deliverPendingExceptions(consent, posthog);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isTelemetryRuntimeActive() {
+    return activeRuntime !== undefined && !activeRuntime.shuttingDown;
+}
+/** True while this process runs the proxy's tracing runtime, which owns its own shutdown. */
+export function isTelemetryTracingActive() {
+    return isTelemetryRuntimeActive() && activeRuntime?.tracerProvider !== undefined;
+}
+export async function flushTelemetryRuntimeWithin(deadlineMs) {
+    const runtime = activeRuntime;
+    if (!runtime || runtime.shuttingDown)
+        return;
+    try {
+        if (!runtime.consent.getSnapshot()) {
+            runtime.posthog.discardPending();
+            return;
+        }
+    }
+    catch {
+        return;
+    }
+    await settleWithin(async () => {
+        await Promise.all([
+            runtime.loggerProvider.forceFlush(),
+            runtime.tracerProvider?.forceFlush(),
+            runtime.posthog.flushWithin(deadlineMs),
+        ]);
+    }, deadlineMs);
+}
+export async function shutdownTelemetryRuntimeWithin(deadlineMs) {
+    const runtime = activeRuntime;
+    if (!runtime || runtime.shuttingDown)
+        return;
+    runtime.shuttingDown = true;
+    process.removeListener("uncaughtExceptionMonitor", runtime.fatalMonitor);
+    process.removeListener("exit", runtime.exitCleanup);
+    try {
+        if (!runtime.consent.getSnapshot())
+            runtime.posthog.discardPending();
+    }
+    catch {
+        runtime.posthog.discardPending();
+    }
+    await settleWithin(async () => {
+        await Promise.all([
+            runtime.loggerProvider.shutdown(),
+            runtime.tracerProvider?.shutdown(),
+            runtime.posthog.shutdownWithin(deadlineMs),
+        ]);
+    }, deadlineMs);
+    logs.disable();
+    if (runtime.tracerProvider) {
+        trace.disable();
+        propagation.disable();
+        context.disable();
+    }
+    activeRuntime = undefined;
+}

package/dist/telemetry/setup-diagnostics.js

@@ -0,0 +1,239 @@
+import { randomUUID } from "node:crypto";
+import { flushTelemetryWithin, recordExpectedSetupFailure, recordSetupResult, recordSetupStage, recordSetupStageFailure, recordUnexpectedException, } from "./facade.js";
+/**
+ * A setup error keeps detailed text and its original cause local while exposing
+ * a separate, closed classification to telemetry call sites.
+ */
+export class SetupDiagnosticError extends Error {
+    classification;
+    constructor(localMessage, classification, options = {}) {
+        super(localMessage, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "SetupDiagnosticError";
+        this.classification = { ...classification };
+    }
+}
+export function classifyHttpSetupFailure(stage, status, localMessage, cause) {
+    let reason;
+    if (status === 401)
+        reason = "unauthorized";
+    else if (status === 403)
+        reason = "forbidden";
+    else if (status === 429)
+        reason = "rate_limited";
+    else if (status >= 400 && status < 500)
+        reason = "upstream_4xx";
+    else if (status >= 500 && status < 600)
+        reason = "upstream_5xx";
+    else
+        reason = "other";
+    return new SetupDiagnosticError(localMessage, {
+        stage,
+        reason,
+        expected: reason !== "other",
+        ...(Number.isInteger(status) && status >= 100 && status <= 599
+            ? { httpStatusCode: status }
+            : {}),
+    }, { cause });
+}
+function ownStringProperty(input, property) {
+    if ((typeof input !== "object" && typeof input !== "function") || input === null)
+        return undefined;
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(input, property);
+        return descriptor && "value" in descriptor && typeof descriptor.value === "string"
+            ? descriptor.value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ownCause(input) {
+    if ((typeof input !== "object" && typeof input !== "function") || input === null)
+        return undefined;
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(input, "cause");
+        return descriptor && "value" in descriptor ? descriptor.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeBuiltInErrorName(input) {
+    const ownName = ownStringProperty(input, "name");
+    if (ownName === "AbortError" || ownName === "TimeoutError")
+        return ownName;
+    if (typeof DOMException === "undefined")
+        return undefined;
+    try {
+        if (!(input instanceof DOMException))
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(DOMException.prototype, "name");
+    if (!descriptor || typeof descriptor.get !== "function")
+        return undefined;
+    try {
+        const name = descriptor.get.call(input);
+        return name === "AbortError" || name === "TimeoutError" ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const NETWORK_CODES = new Set([
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EPIPE",
+    "ETIMEDOUT",
+]);
+export function classifyNetworkSetupFailure(stage, cause, localMessage = cause instanceof Error ? cause.message : String(cause)) {
+    const name = safeBuiltInErrorName(cause);
+    let code;
+    let current = cause;
+    const seen = new Set();
+    for (let depth = 0; depth <= 2 && current !== undefined && !seen.has(current); depth++) {
+        seen.add(current);
+        const candidate = ownStringProperty(current, "code");
+        if (candidate && NETWORK_CODES.has(candidate)) {
+            code = candidate;
+            break;
+        }
+        current = ownCause(current);
+    }
+    const reason = name === "AbortError" || name === "TimeoutError" || code === "ETIMEDOUT"
+        ? "timeout"
+        : code && NETWORK_CODES.has(code)
+            ? "network_failure"
+            : "other";
+    return new SetupDiagnosticError(localMessage, {
+        stage,
+        reason,
+        expected: reason !== "other",
+    }, { cause });
+}
+function durationBucket(durationMs) {
+    if (durationMs < 1_000)
+        return "under_1s";
+    if (durationMs < 5_000)
+        return "1s_to_5s";
+    if (durationMs < 30_000)
+        return "5s_to_30s";
+    if (durationMs < 120_000)
+        return "30s_to_2m";
+    return "over_2m";
+}
+export function createSetupAttempt(input) {
+    const startedAt = Date.now();
+    const diagnosticId = randomUUID();
+    const base = { provider: input.provider, method: input.method, diagnosticId };
+    const withDuration = () => ({
+        ...base,
+        durationBucket: durationBucket(Math.max(0, Date.now() - startedAt)),
+    });
+    recordSetupStage({ ...withDuration(), stage: "attempt_start" });
+    let terminal = false;
+    const classify = (error, fallbackStage) => error instanceof SetupDiagnosticError
+        ? error.classification
+        : { stage: fallbackStage, reason: "other", expected: false };
+    const failureInput = (classification) => ({
+        ...withDuration(),
+        stage: classification.stage,
+        reason: classification.reason,
+        ...(classification.httpStatusCode === undefined
+            ? {}
+            : { httpStatusCode: classification.httpStatusCode }),
+    });
+    const recordException = (error, classification) => {
+        if (classification.expected)
+            return;
+        const exceptionCause = error instanceof SetupDiagnosticError && error.cause !== undefined
+            ? error.cause
+            : error;
+        recordUnexpectedException(exceptionCause, {
+            category: "setup",
+            provider: input.provider,
+            setupStage: classification.stage,
+            reason: classification.reason,
+        }, diagnosticId);
+    };
+    return {
+        ...base,
+        stageCompleted(stage) {
+            if (terminal)
+                return;
+            recordSetupStage({ ...withDuration(), stage });
+        },
+        stageFailed(error, fallbackStage) {
+            const classification = classify(error, fallbackStage);
+            if (!terminal) {
+                recordSetupStageFailure(failureInput(classification));
+                recordException(error, classification);
+            }
+            return { diagnosticId, unexpected: !classification.expected };
+        },
+        failed(error, fallbackStage) {
+            const classification = classify(error, fallbackStage);
+            if (!terminal) {
+                terminal = true;
+                recordExpectedSetupFailure(failureInput(classification));
+                recordException(error, classification);
+            }
+            return { diagnosticId, unexpected: !classification.expected };
+        },
+        cancelled() {
+            if (terminal)
+                return;
+            terminal = true;
+            recordSetupResult({ ...withDuration(), result: "cancelled" });
+        },
+        succeeded() {
+            if (terminal)
+                return;
+            terminal = true;
+            recordSetupResult({ ...withDuration(), result: "succeeded" });
+        },
+    };
+}
+export const SETUP_TELEMETRY_FLUSH_DEADLINE_MS = 1_500;
+/** Never let a bounded telemetry flush change or delay a command result. */
+export async function withSetupTelemetryFlush(operation) {
+    try {
+        return await operation();
+    }
+    finally {
+        await new Promise(resolve => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(finish, SETUP_TELEMETRY_FLUSH_DEADLINE_MS);
+            void Promise.resolve()
+                .then(() => flushTelemetryWithin(SETUP_TELEMETRY_FLUSH_DEADLINE_MS))
+                .then(finish, finish);
+        });
+    }
+}
+export function isPromptCancellation(error) {
+    return ownStringProperty(error, "name") === "ExitPromptError";
+}
+/**
+ * Close an attempt that ended in a thrown error: a cancelled prompt is a user
+ * decision (no outcome returned); anything else is a failure at the given stage.
+ */
+export function failAttemptFromError(attempt, error, fallbackStage) {
+    if (isPromptCancellation(error)) {
+        attempt.cancelled();
+        return undefined;
+    }
+    return attempt.failed(error, fallbackStage);
+}

package/dist/utils/token-extractor.js

@@ -3,28 +3,74 @@ import { promisify } from "util";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 import os from "os";
+import { SetupDiagnosticError } from "../telemetry/setup-diagnostics.js";
 const execFileAsync = promisify(execFile);
+function ownErrorCode(error) {
+    if ((typeof error !== "object" && typeof error !== "function") || error === null)
+        return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(error, "code");
+    return descriptor && "value" in descriptor
+        && (typeof descriptor.value === "string" || typeof descriptor.value === "number")
+        ? descriptor.value
+        : undefined;
+}
+function credentialReadError(error, source) {
+    const code = ownErrorCode(error);
+    // `security find-generic-password` exits 44 when the item does not exist.
+    const reason = code === "EACCES" || code === "EPERM"
+        ? "permission_denied"
+        : code === "ENOENT" || code === 44
+            ? "not_found"
+            : "other";
+    const detail = error instanceof Error ? error.message : String(error);
+    return new SetupDiagnosticError(`${source} read failed: ${detail}`, {
+        stage: "credential_read",
+        reason,
+        expected: reason !== "other",
+    }, { cause: error });
+}
+function credentialParseError(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return new SetupDiagnosticError(`Credential parse failed: ${detail}`, {
+        stage: "credential_parse",
+        reason: "malformed_credentials",
+        expected: true,
+    }, { cause: error });
+}
 /**
  * macOS: extract OAuth tokens from the macOS Keychain.
  * Uses execFile (not exec/execSync) — args are passed as an array,
  * preventing any shell injection.
  */
 export async function extractFromKeychain() {
+    const result = await extractFromKeychainDetailed();
+    return result.ok ? result.tokens : null;
+}
+export async function extractFromKeychainDetailed() {
+    let stdout;
     try {
-        const { stdout } = await execFileAsync("security", [
+        ({ stdout } = await execFileAsync("security", [
             "find-generic-password",
             "-s", "Claude Code-credentials",
             "-w",
-        ]);
+        ]));
+    }
+    catch (error) {
+        return { ok: false, error: credentialReadError(error, "Keychain") };
+    }
+    try {
         const raw = JSON.parse(stdout.trim());
         // Keychain JSON can be either:
         //   { claudeAiOauth: { accessToken, refreshToken, ... }, mcpOAuth: {...} }
         //   { accessToken, refreshToken, ... }  (direct, older versions)
         const oauth = raw.claudeAiOauth ?? raw;
-        return parseCredentialJson(oauth);
+        const tokens = parseCredentialJson(oauth);
+        if (!tokens)
+            throw new TypeError("Credential object is missing required OAuth token fields");
+        return { ok: true, tokens };
     }
-    catch {
-        return null;
+    catch (error) {
+        return { ok: false, error: credentialParseError(error) };
     }
 }
 /**
@@ -33,19 +79,41 @@ export async function extractFromKeychain() {
  * No shell — pure Node.js file read.
  */
 export function extractFromCredentialsFile() {
+    const result = extractFromCredentialsFileDetailed();
+    return result.ok ? result.tokens : null;
+}
+export function extractFromCredentialsFileDetailed() {
     const credPath = join(os.homedir(), ".claude", ".credentials.json");
-    if (!existsSync(credPath))
-        return null;
+    if (!existsSync(credPath)) {
+        return {
+            ok: false,
+            error: new SetupDiagnosticError("Claude credentials file was not found", {
+                stage: "credential_read",
+                reason: "not_found",
+                expected: true,
+            }),
+        };
+    }
+    let contents;
+    try {
+        contents = readFileSync(credPath, "utf-8");
+    }
+    catch (error) {
+        return { ok: false, error: credentialReadError(error, "credentials file") };
+    }
     try {
-        const raw = JSON.parse(readFileSync(credPath, "utf-8"));
+        const raw = JSON.parse(contents);
         // The file can have two shapes:
         //   { claudeAiOauth: { accessToken, refreshToken, expiresAt, scopes } }
         //   { accessToken, refreshToken, expiresAt, scopes }  (direct)
         const oauth = raw.claudeAiOauth ?? raw;
-        return parseCredentialJson(oauth);
+        const tokens = parseCredentialJson(oauth);
+        if (!tokens)
+            throw new TypeError("Credential object is missing required OAuth token fields");
+        return { ok: true, tokens };
     }
-    catch {
-        return null;
+    catch (error) {
+        return { ok: false, error: credentialParseError(error) };
     }
 }
 /** Parse and normalise either a raw JSON string or an already-parsed object. */