@jagilber-org/index-server 1.22.1 → 1.26.4

package/dist/lib/mcpStdioLogging.js

@@ -0,0 +1,287 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * mcpStdioLogging — Generic MCP stdio transport logging solution.
+ *
+ * Drop-in module for ANY MCP server using stdio transport that wants proper
+ * log-level display in VS Code (or any MCP client that reads stderr).
+ *
+ * ## Problem
+ *
+ * VS Code's MCP host (`extHostMcpNode.ts`) hardcodes ALL stderr output as
+ * `LogLevel.Warning` with prefix `[server stderr]`. There is no configuration,
+ * no level detection, no opt-out. Every byte on stderr becomes a warning.
+ *
+ * The MCP protocol provides `notifications/message` with a `level` field.
+ * VS Code's `translateMcpLogMessage()` correctly maps those levels to proper
+ * log output (debug, info, warning, error). Other clients (Claude Desktop,
+ * Cursor, etc.) also respect `notifications/message` levels.
+ *
+ * ## Solution
+ *
+ * 1. Intercept `process.stderr.write` at module import time (before any other
+ *    module can write to stderr).
+ * 2. Buffer all pre-handshake stderr lines in memory.
+ * 3. After the MCP handshake completes, replay the buffer through
+ *    `server.sendLoggingMessage()` and route all future stderr the same way.
+ * 4. Infer severity from content (NDJSON level field, keyword patterns).
+ * 5. On transport failure, deactivate and restore original stderr.
+ *
+ * ## Usage (3 steps)
+ *
+ * ```typescript
+ * // 1. Import FIRST — before any module that writes to stderr
+ * import { McpStdioLogger } from './lib/mcpStdioLogging';
+ * const logger = new McpStdioLogger({ serverName: 'my-server' });
+ *
+ * // 2. After creating the MCP SDK server, register it
+ * const server = new Server({ name: 'my-server', version }, { capabilities: { logging: {} } });
+ * logger.registerServer(server);
+ *
+ * // 3. After the handshake completes (initialize response sent), activate
+ * logger.activate();
+ * ```
+ *
+ * ## Requirements
+ *
+ * - Server must declare `logging: {}` in capabilities so clients know to
+ *   accept `notifications/message`.
+ * - Server object must have `sendLoggingMessage({ level, logger?, data })`.
+ * - Module must be imported before `logPrefix` or any other stderr-producing module.
+ *
+ * @module mcpStdioLogging
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpStdioLogger = void 0;
+exports.defaultInferLevel = defaultInferLevel;
+// ---------------------------------------------------------------------------
+// Built-in level inference heuristic
+// ---------------------------------------------------------------------------
+/**
+ * Infer MCP logging level from a raw stderr line.
+ *
+ * Priority:
+ * 1. NDJSON with `"level"` field → map to MCP level
+ * 2. Keyword patterns (ERROR, WARN, DEBUG, trace) → corresponding level
+ * 3. Default → 'info'
+ */
+function defaultInferLevel(line) {
+    // Check for NDJSON with "level" field
+    if (line.startsWith('{')) {
+        const m = /"level"\s*:\s*"(TRACE|DEBUG|INFO|WARN|WARNING|ERROR|FATAL|info|warning|error|debug|notice|critical|alert|emergency)"/i.exec(line);
+        if (m) {
+            const l = m[1].toUpperCase();
+            if (l === 'TRACE' || l === 'DEBUG')
+                return 'debug';
+            if (l === 'INFO' || l === 'NOTICE')
+                return 'info';
+            if (l === 'WARN' || l === 'WARNING')
+                return 'warning';
+            if (l === 'ERROR')
+                return 'error';
+            if (l === 'FATAL' || l === 'CRITICAL')
+                return 'critical';
+            if (l === 'ALERT')
+                return 'alert';
+            if (l === 'EMERGENCY')
+                return 'emergency';
+        }
+    }
+    // Keyword patterns in plain text
+    if (/\bERROR\b|\bFATAL\b/i.test(line))
+        return 'error';
+    if (/\bWARN\b/i.test(line))
+        return 'warning';
+    if (/\bDEBUG\b|\btrace\b/i.test(line))
+        return 'debug';
+    return 'info';
+}
+// ---------------------------------------------------------------------------
+// McpStdioLogger class
+// ---------------------------------------------------------------------------
+/**
+ * Manages stderr interception, buffering, and MCP protocol log routing
+ * for any MCP server using stdio transport.
+ *
+ * Designed to be instantiated once, as early as possible in the server's
+ * entry point, before any module writes to stderr.
+ */
+class McpStdioLogger {
+    _server = null;
+    _active = false;
+    _intercepting = false;
+    _buffer = [];
+    _originalStderrWrite;
+    _serverName;
+    _maxBufferSize;
+    _inferLevel;
+    constructor(options = {}) {
+        this._serverName = options.serverName ?? 'mcp-server';
+        this._maxBufferSize = options.maxBufferSize ?? 500;
+        this._inferLevel = options.inferLevel ?? defaultInferLevel;
+        this._originalStderrWrite = process.stderr.write.bind(process.stderr);
+        if (options.interceptImmediately !== false) {
+            this.interceptStderr();
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Start intercepting process.stderr.write.
+     * Called automatically on construction unless `interceptImmediately: false`.
+     * Safe to call multiple times (idempotent).
+     */
+    interceptStderr() {
+        if (this._intercepting)
+            return;
+        this._intercepting = true;
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        process.stderr.write = ((chunk, encodingOrCb, cb) => {
+            const text = typeof chunk === 'string'
+                ? chunk
+                : Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+            const lines = text.split(/\r?\n/);
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                if (self._active && self._server) {
+                    // Bridge is live — send directly via MCP protocol
+                    try {
+                        self._server.sendLoggingMessage({
+                            level: self._inferLevel(trimmed),
+                            logger: self._serverName,
+                            data: trimmed,
+                        });
+                    }
+                    catch {
+                        // Transport failed — deactivate and fall back to real stderr
+                        self._active = false;
+                        self._intercepting = false;
+                        process.stderr.write = self._originalStderrWrite;
+                        return self._originalStderrWrite(chunk, encodingOrCb, cb);
+                    }
+                }
+                else {
+                    // Pre-handshake — buffer the line (don't write to stderr)
+                    self._buffer.push({ level: self._inferLevel(trimmed), data: trimmed });
+                    // Enforce buffer size limit
+                    if (self._buffer.length > self._maxBufferSize) {
+                        self._buffer.shift();
+                    }
+                }
+            }
+            // Invoke callback if provided
+            const callback = typeof encodingOrCb === 'function' ? encodingOrCb : cb;
+            if (typeof callback === 'function')
+                callback();
+            return true;
+        });
+    }
+    /**
+     * Register the MCP SDK server instance.
+     * Must be called after server creation but before activation.
+     * The server must have a `sendLoggingMessage()` method.
+     */
+    registerServer(server) {
+        this._server = server;
+    }
+    /**
+     * Activate the bridge: replay buffered stderr and route all future
+     * output through `server.sendLoggingMessage()`.
+     *
+     * Call this after the MCP handshake completes (initialize response sent).
+     * No-op if server is not registered or lacks sendLoggingMessage.
+     */
+    activate() {
+        if (!this._server || typeof this._server.sendLoggingMessage !== 'function')
+            return;
+        this._active = true;
+        this._replayBuffer();
+    }
+    /**
+     * Returns true when the bridge is active and logs route through MCP protocol.
+     */
+    get isActive() {
+        return this._active;
+    }
+    /**
+     * Send a structured log message through the MCP protocol.
+     * Use this from your application logger instead of console.error/stderr.
+     * No-op if the bridge is not active.
+     *
+     * @param level - MCP logging level
+     * @param data  - Log payload (string or object)
+     */
+    log(level, data) {
+        if (!this._active || !this._server)
+            return;
+        try {
+            this._server.sendLoggingMessage({
+                level,
+                logger: this._serverName,
+                data,
+            });
+        }
+        catch {
+            // Transport failed — deactivate to avoid repeated failures
+            this._active = false;
+        }
+    }
+    /**
+     * Write directly to the ORIGINAL process.stderr, bypassing the interceptor.
+     * Use this when you need stderr output visible to VS Code's Output panel
+     * without triggering the MCP routing/buffering pipeline.
+     */
+    writeOriginalStderr(data) {
+        try {
+            this._originalStderrWrite(data.endsWith('\n') ? data : data + '\n');
+        }
+        catch { /* ignore */ }
+    }
+    /**
+     * Restore original stderr and deactivate the bridge.
+     * Useful for testing cleanup or graceful shutdown.
+     */
+    restore() {
+        process.stderr.write = this._originalStderrWrite;
+        this._active = false;
+        this._intercepting = false;
+        this._buffer.length = 0;
+    }
+    /**
+     * Get the number of currently buffered lines (pre-handshake).
+     */
+    get bufferSize() {
+        return this._buffer.length;
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    _replayBuffer() {
+        while (this._buffer.length > 0) {
+            const entry = this._buffer.shift();
+            try {
+                this._server.sendLoggingMessage({
+                    level: entry.level,
+                    logger: this._serverName,
+                    data: entry.data,
+                });
+            }
+            catch {
+                // Transport failed during replay — stop and dump remaining to real stderr
+                this._active = false;
+                this._intercepting = false;
+                process.stderr.write = this._originalStderrWrite;
+                for (const remaining of this._buffer) {
+                    this._originalStderrWrite(remaining.data + '\n');
+                }
+                this._buffer.length = 0;
+                return;
+            }
+        }
+    }
+}
+exports.McpStdioLogger = McpStdioLogger;

package/dist/schemas/index.d.ts

@@ -1,7 +1,28 @@
 export declare const instructionEntry: {
     readonly type: "object";
     readonly additionalProperties: false;
-    readonly required: readonly ["id", "title", "body", "priority", "audience", "requirement", "categories", "sourceHash", "schemaVersion", "createdAt", "updatedAt", "version", "status", "owner", "priorityTier", "classification", "lastReviewedAt", "nextReviewDue", "changeLog", "semanticSummary"];
+    readonly $defs: {
+        readonly extensionValue: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "number";
+            }, {
+                readonly type: "boolean";
+            }, {
+                readonly type: "array";
+                readonly items: {
+                    readonly $ref: "#/$defs/extensionValue";
+                };
+            }, {
+                readonly type: "object";
+                readonly additionalProperties: {
+                    readonly $ref: "#/$defs/extensionValue";
+                };
+            }];
+        };
+    };
+    readonly required: readonly ["id", "title", "body", "priority", "audience", "requirement", "categories", "sourceHash", "schemaVersion", "createdAt", "updatedAt", "version", "status", "owner", "priorityTier", "classification", "lastReviewedAt", "nextReviewDue", "changeLog", "semanticSummary", "contentType"];
     readonly properties: {
         readonly id: {
             readonly type: "string";
@@ -31,6 +52,9 @@ export declare const instructionEntry: {
                 readonly type: "string";
             };
         };
+        readonly primaryCategory: {
+            readonly type: "string";
+        };
         readonly sourceHash: {
             readonly type: "string";
         };
@@ -58,6 +82,9 @@ export declare const instructionEntry: {
         readonly riskScore: {
             readonly type: "number";
         };
+        readonly reviewIntervalDays: {
+            readonly type: "number";
+        };
         readonly workspaceId: {
             readonly type: "string";
         };
@@ -70,6 +97,9 @@ export declare const instructionEntry: {
                 readonly type: "string";
             };
         };
+        readonly contentType: {
+            readonly enum: readonly ["instruction", "template", "chat-session", "reference", "example", "agent"];
+        };
         readonly version: {
             readonly type: "string";
         };
@@ -113,6 +143,9 @@ export declare const instructionEntry: {
         readonly supersedes: {
             readonly type: "string";
         };
+        readonly archivedAt: {
+            readonly type: "string";
+        };
         readonly semanticSummary: {
             readonly type: "string";
         };
@@ -124,7 +157,9 @@ export declare const instructionEntry: {
         };
         readonly extensions: {
             readonly type: "object";
-            readonly additionalProperties: true;
+            readonly additionalProperties: {
+                readonly $ref: "#/$defs/extensionValue";
+            };
         };
     };
 };

package/dist/schemas/index.js

@@ -6,9 +6,20 @@ exports.schemas = exports.instructionEntry = void 0;
 exports.instructionEntry = {
     type: 'object',
     additionalProperties: false,
+    $defs: {
+        extensionValue: {
+            anyOf: [
+                { type: 'string' },
+                { type: 'number' },
+                { type: 'boolean' },
+                { type: 'array', items: { $ref: '#/$defs/extensionValue' } },
+                { type: 'object', additionalProperties: { $ref: '#/$defs/extensionValue' } }
+            ]
+        }
+    },
     required: [
         'id', 'title', 'body', 'priority', 'audience', 'requirement', 'categories', 'sourceHash', 'schemaVersion', 'createdAt', 'updatedAt',
-        'version', 'status', 'owner', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'changeLog', 'semanticSummary'
+        'version', 'status', 'owner', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'changeLog', 'semanticSummary', 'contentType'
     ],
     properties: {
         id: { type: 'string', minLength: 1 },
@@ -19,6 +30,7 @@ exports.instructionEntry = {
         audience: { enum: ['individual', 'group', 'all'] },
         requirement: { enum: ['mandatory', 'critical', 'recommended', 'optional', 'deprecated'] },
         categories: { type: 'array', items: { type: 'string' } },
+        primaryCategory: { type: 'string' },
         sourceHash: { type: 'string' },
         schemaVersion: { type: 'string' },
         deprecatedBy: { type: 'string' },
@@ -28,9 +40,11 @@ exports.instructionEntry = {
         firstSeenTs: { type: 'string' },
         lastUsedAt: { type: 'string' },
         riskScore: { type: 'number' },
+        reviewIntervalDays: { type: 'number' },
         workspaceId: { type: 'string' },
         userId: { type: 'string' },
         teamIds: { type: 'array', items: { type: 'string' } },
+        contentType: { enum: ['instruction', 'template', 'chat-session', 'reference', 'example', 'agent'] },
         version: { type: 'string' },
         status: { enum: ['draft', 'review', 'approved', 'deprecated'] },
         owner: { type: 'string' },
@@ -40,10 +54,11 @@ exports.instructionEntry = {
         nextReviewDue: { type: 'string' },
         changeLog: { type: 'array', items: { type: 'object', required: ['version', 'changedAt', 'summary'], additionalProperties: false, properties: { version: { type: 'string' }, changedAt: { type: 'string' }, summary: { type: 'string' } } } },
         supersedes: { type: 'string' },
+        archivedAt: { type: 'string' },
         semanticSummary: { type: 'string' },
         createdByAgent: { type: 'string' },
         sourceWorkspace: { type: 'string' },
-        extensions: { type: 'object', additionalProperties: true }
+        extensions: { type: 'object', additionalProperties: { $ref: '#/$defs/extensionValue' } }
     }
 };
 // (listLike schema removed after dispatcher consolidation of read-only instruction methods)
@@ -307,7 +322,16 @@ exports.schemas = {
         } },
     'index_add': {
         anyOf: [
-            { type: 'object', required: ['error'], properties: { error: { type: 'string' }, id: { type: 'string' } }, additionalProperties: true },
+            { type: 'object', required: ['error'], properties: {
+                    error: { type: 'string' },
+                    id: { type: 'string' },
+                    success: { const: false },
+                    message: { type: 'string' },
+                    validationErrors: { type: 'array', items: { type: 'string' } },
+                    hints: { type: 'array', items: { type: 'string' } },
+                    schemaRef: { type: 'string' },
+                    inputSchema: { type: 'object' }
+                }, additionalProperties: true },
             { type: 'object', required: ['id', 'hash', 'skipped', 'created', 'overwritten'], additionalProperties: false, properties: {
                     id: { type: 'string' }, hash: { type: 'string' }, skipped: { type: 'boolean' }, created: { type: 'boolean' }, overwritten: { type: 'boolean' }
                 } }

package/dist/server/backgroundServicesStartup.d.ts

@@ -1,3 +1,9 @@
 import type { RuntimeConfig } from '../config/runtimeConfig';
 export declare function startOptionalMemoryMonitoring(_runtime: RuntimeConfig): void;
-export declare function startDeferredBackgroundServices(runtime: RuntimeConfig): void;
+export declare function startDeferredBackgroundServices(runtime: RuntimeConfig): {
+    started: string[];
+    errors: {
+        service: string;
+        error: string;
+    }[];
+};

package/dist/server/backgroundServicesStartup.js

@@ -6,6 +6,7 @@ const envUtils_1 = require("../utils/envUtils");
 const indexContext_1 = require("../services/indexContext");
 const autoBackup_1 = require("../services/autoBackup");
 const memoryMonitor_1 = require("../utils/memoryMonitor");
+const logger_1 = require("../services/logger");
 function startOptionalMemoryMonitoring(_runtime) {
     if ((0, envUtils_1.getBooleanEnv)('INDEX_SERVER_DEBUG') || (0, envUtils_1.getBooleanEnv)('INDEX_SERVER_MEMORY_MONITOR')) {
         try {
@@ -20,32 +21,48 @@ function startOptionalMemoryMonitoring(_runtime) {
     }
 }
 function startDeferredBackgroundServices(runtime) {
+    const started = [];
+    const errors = [];
     try {
         if (runtime.server.indexPolling.enabled) {
             (0, indexContext_1.startIndexVersionPoller)({
                 proactive: runtime.server.indexPolling.proactive,
                 intervalMs: runtime.server.indexPolling.intervalMs,
             });
+            started.push('indexVersionPoller');
             if (runtime.logging.diagnostics) {
                 try {
                     process.stderr.write(`[startup] index version poller started proactive=${runtime.server.indexPolling.proactive}\n`);
                 }
-                catch { /* ignore */ }
+                catch (err) {
+                    (0, logger_1.log)('WARN', `[startup] diagnostics write failed: ${err.message}`);
+                }
             }
         }
         else if (runtime.logging.diagnostics) {
             try {
                 process.stderr.write('[startup] index version poller not enabled (set INDEX_SERVER_ENABLE_INDEX_SERVER_POLLER=1)\n');
             }
-            catch { /* ignore */ }
+            catch (err) {
+                (0, logger_1.log)('WARN', `[startup] diagnostics write failed: ${err.message}`);
+            }
         }
     }
-    catch { /* ignore */ }
-    try {
-        setImmediate(() => { try {
+    catch (err) {
+        const detail = err.message;
+        (0, logger_1.log)('ERROR', `[startup] index version poller failed to start: ${detail}`, { detail: err.stack });
+        errors.push({ service: 'indexVersionPoller', error: detail });
+    }
+    setImmediate(() => {
+        try {
             (0, autoBackup_1.startAutoBackup)();
+            started.push('autoBackup');
         }
-        catch { /* ignore */ } });
-    }
-    catch { /* ignore */ }
+        catch (err) {
+            const detail = err.message;
+            (0, logger_1.log)('ERROR', `[startup] autoBackup failed to start: ${detail}`, { detail: err.stack });
+            errors.push({ service: 'autoBackup', error: detail });
+        }
+    });
+    return { started, errors };
 }

package/dist/server/certInit.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Certificate bootstrap module for the `--init-cert` CLI switch.
+ *
+ * Public surface (all exports carry JSDoc per CQ-7):
+ * - {@link validateOptions} : merge defaults, validate, resolve absolute paths
+ * - {@link parseSan}        : split + validate SAN entries
+ * - {@link buildOpenSslArgs}: build argv for `openssl req -x509`
+ * - {@link preflightOpenssl}: verify openssl is callable on PATH
+ * - {@link formatPrintEnv}  : produce env-var lines for the operator
+ * - {@link runCertInit}     : end-to-end pipeline
+ *
+ * Constitution refs:
+ * - SH-4 : every output path is `path.resolve`d and asserted to live under
+ *          the resolved `certDir`.
+ * - SH-6 : this module never disables TLS verification anywhere.
+ * - CQ-1 : lives in its own file so `index-server.ts` stays under budget.
+ * - CQ-6 : every catch surfaces a typed error; no swallowed exceptions.
+ * - OB-3 : failures throw {@link CertInitError} with a stable `code`.
+ * - OB-5 : success and skip paths log at INFO; failures log at ERROR.
+ */
+import type { CertInitOptions, CertInitResult, PrintEnvFormat } from './certInit.types';
+/**
+ * Validate a partial options bag and return a fully-resolved
+ * {@link CertInitOptions} suitable for {@link runCertInit}.
+ *
+ * Defaults are applied for any field omitted by the caller. All paths are
+ * `path.resolve`d. The function rejects values that violate the v1 contract:
+ * days out of `[MIN_DAYS, MAX_DAYS]`, key-bits not in `{2048, 4096}`, SAN
+ * entries without `DNS:` or `IP:` prefix, empty CN, or output paths that
+ * escape `certDir` (SH-4).
+ *
+ * @param input  Partial options as parsed from the CLI.
+ * @returns      Fully-resolved {@link CertInitOptions}.
+ * @throws       {@link CertInitError} with codes `INVALID_DAYS`,
+ *               `INVALID_KEY_BITS`, `INVALID_SAN`, `INVALID_CN`, or
+ *               `PATH_OUTSIDE_CERT_DIR`.
+ */
+export declare function validateOptions(input: Partial<CertInitOptions>): CertInitOptions;
+/**
+ * Parse a comma-separated SAN string into individual entries, validating that
+ * each entry has a recognized `DNS:` or `IP:` prefix.
+ *
+ * @param raw  Raw SAN string from the CLI (e.g. `"DNS:host,IP:127.0.0.1"`).
+ * @returns    Array of validated SAN entries with surrounding whitespace
+ *             trimmed.
+ * @throws     {@link CertInitError} `INVALID_SAN` for empty input, trailing
+ *             commas, or entries missing a recognized prefix.
+ */
+export declare function parseSan(raw: string): string[];
+/**
+ * Build the argument array for the OpenSSL `req -x509` invocation that
+ * generates a self-signed certificate. The returned array is suitable for
+ * `child_process.execFile('openssl', args)` — no shell metacharacters are
+ * inserted, and inputs are not interpolated into a command string.
+ *
+ * @param opts  Fully-resolved cert-init options (use {@link validateOptions}
+ *              to produce these).
+ * @returns     Argument array for `openssl`.
+ */
+export declare function buildOpenSslArgs(opts: CertInitOptions): string[];
+/**
+ * Verify that `openssl` is callable on PATH. Used as a preflight before any
+ * generation work so that the failure surfaces with a stable
+ * `OPENSSL_NOT_FOUND` code rather than a downstream spawn error.
+ *
+ * @returns The reported version string when openssl is callable.
+ * @throws  {@link CertInitError} `OPENSSL_NOT_FOUND` otherwise.
+ */
+export declare function preflightOpenssl(): string;
+/**
+ * Format the env-var lines an operator can paste into their shell after a
+ * successful generation, pointing the dashboard at the new cert/key.
+ *
+ * @param opts    Resolved cert-init options.
+ * @param format  Output format. `'auto'` picks `'powershell'` on Win32,
+ *                `'posix'` elsewhere.
+ * @returns       Multi-line string ending with a trailing newline.
+ */
+export declare function formatPrintEnv(opts: CertInitOptions, format?: PrintEnvFormat): string;
+/**
+ * Execute the full cert-init pipeline: validate options, preflight openssl,
+ * create `certDir` if missing, run openssl, set restrictive permissions on
+ * POSIX, and emit a structured log line via the existing logger.
+ *
+ * Idempotency: if `certFile` OR `keyFile` already exists and `force` is false,
+ * no openssl invocation is made and a `kind: 'skipped'` result is returned.
+ * Treating only the both-exist case as "skip" would clobber a surviving cert
+ * when the operator deleted/rotated only the key (or vice versa) — `--force`
+ * is required to overwrite *any* existing file.
+ *
+ * @param input  Caller options (typically from the CLI parser). Re-validated
+ *               internally so direct callers do not need to pre-validate.
+ * @returns      A {@link CertInitResult} indicating generated vs skipped.
+ * @throws       {@link CertInitError} for any validation, preflight, or
+ *               execution failure (codes documented on each helper above).
+ */
+export declare function runCertInit(input: Partial<CertInitOptions>): Promise<CertInitResult>;