@alagoni97/cli 0.72.1

package/dist/telemetry/sender.d.ts

@@ -0,0 +1,14 @@
+import { TelemetryEvent } from './events';
+import { ProjectTelemetryConfig } from '../codegen/types';
+/**
+ * Send telemetry event to tracking endpoint.
+ *
+ * **CRITICAL**: This function is designed to NEVER throw or reject.
+ * All errors are handled internally and logged only in debug mode.
+ * It is safe to call without .catch() or try/catch.
+ *
+ * @param event - The telemetry event to send
+ * @param projectConfig - Optional project-level telemetry config
+ * @returns Promise that always resolves (never rejects)
+ */
+export declare function sendEvent(event: TelemetryEvent, projectConfig?: ProjectTelemetryConfig): Promise<void>;

package/dist/telemetry/sender.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendEvent = void 0;
+/* eslint-disable no-undef */
+/* eslint-disable no-console */
+const https_1 = __importDefault(require("https"));
+const config_1 = require("./config");
+const LoggingInterface_1 = require("../LoggingInterface");
+/**
+ * Send telemetry event to tracking endpoint.
+ *
+ * **CRITICAL**: This function is designed to NEVER throw or reject.
+ * All errors are handled internally and logged only in debug mode.
+ * It is safe to call without .catch() or try/catch.
+ *
+ * @param event - The telemetry event to send
+ * @param projectConfig - Optional project-level telemetry config
+ * @returns Promise that always resolves (never rejects)
+ */
+async function sendEvent(event, projectConfig) {
+    try {
+        const config = await (0, config_1.getTelemetryConfig)(projectConfig);
+        // Don't send if telemetry is disabled
+        if (config.enabled === false) {
+            if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+                LoggingInterface_1.Logger.info(`[Telemetry Debug] Telemetry is disabled (${JSON.stringify(config)}), skipping send`);
+            }
+            return;
+        }
+        // Don't send if required config is missing
+        if (!config.endpoint || !config.trackingId || !config.anonymousId) {
+            if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+                LoggingInterface_1.Logger.info(`[Telemetry Debug] Missing required config (${JSON.stringify(config)}), skipping send`);
+            }
+            return;
+        }
+        // Build GA4 Measurement Protocol payload
+        const payload = {
+            client_id: config.anonymousId,
+            events: [
+                {
+                    name: event.event,
+                    params: {
+                        ...Object.fromEntries(Object.entries(event).filter(([key]) => key !== 'event')),
+                        // Use provided engagement time or duration, fallback to 100ms minimum
+                        engagement_time_msec: String(event.duration || 100)
+                    }
+                }
+            ]
+        };
+        // Debug mode: log event without sending
+        if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+            LoggingInterface_1.Logger.info('[Telemetry Debug] Prepared event:', JSON.stringify(payload, null, 2));
+        }
+        // Build URL with query parameters
+        const url = new URL(config.endpoint);
+        url.searchParams.set('measurement_id', config.trackingId);
+        if (config.apiSecret) {
+            url.searchParams.set('api_secret', config.apiSecret);
+        }
+        // Send to endpoint
+        await sendHttpRequest({ url: url.toString(), payload });
+    }
+    catch (error) {
+        // Catch any unexpected errors (config issues, JSON stringify errors, etc.)
+        if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+            LoggingInterface_1.Logger.error('[Telemetry Debug] Error:', error);
+        }
+        // Always resolve, never reject
+    }
+}
+exports.sendEvent = sendEvent;
+/**
+ * Send HTTP POST request.
+ * This function never throws - all errors are handled internally.
+ *
+ * @param params - Request parameters
+ * @returns Promise that always resolves
+ */
+async function sendHttpRequest(params) {
+    const { url, payload } = params;
+    return new Promise((resolve) => {
+        try {
+            const data = JSON.stringify(payload);
+            const req = https_1.default.request(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(data)
+                },
+                timeout: 1000 // Fail fast
+            }, (res) => {
+                // Log success in debug mode
+                if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+                    LoggingInterface_1.Logger.info(`[Telemetry Debug] Send succeeded with status: ${res.statusCode}`);
+                }
+                // Don't wait for response body, resolve immediately
+                resolve();
+            });
+            req.on('error', (err) => {
+                // Fail silently, don't break CLI
+                if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+                    LoggingInterface_1.Logger.error(`[Telemetry Debug] Send failed: ${err.message}`);
+                }
+                resolve();
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                resolve();
+            });
+            req.write(data);
+            req.end();
+        }
+        catch (error) {
+            // Catch any unexpected errors
+            if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+                LoggingInterface_1.Logger.error('[Telemetry Debug] Request error:', error);
+            }
+            resolve();
+        }
+    });
+}

package/dist/utils/gitignore.d.ts

@@ -0,0 +1,66 @@
+export interface GitignoreUpdateOptions {
+    /**
+     * The base directory where .gitignore is located (defaults to process.cwd())
+     */
+    baseDirectory?: string;
+    /**
+     * Custom comment header to add before the gitignore entries
+     */
+    commentHeader?: string;
+}
+export interface GitignoreUpdateResult {
+    /**
+     * Whether the operation was successful
+     */
+    success: boolean;
+    /**
+     * The action that was performed
+     */
+    action: 'created' | 'updated' | 'skipped' | 'error';
+    /**
+     * A message describing what happened
+     */
+    message: string;
+    /**
+     * The paths that were added (if any)
+     */
+    addedPaths?: string[];
+    /**
+     * Error details if the operation failed
+     */
+    error?: string;
+}
+/**
+ * Updates or creates a .gitignore file with the specified output paths
+ *
+ * @param outputPaths - Array of paths to add to .gitignore
+ * @param options - Optional configuration for the gitignore update
+ * @returns Result object with operation details
+ *
+ * @example
+ * ```typescript
+ * const result = await updateGitignore(['src/__gen__/payloads', 'src/__gen__/channels']);
+ * if (result.success) {
+ *   console.log(result.message);
+ * }
+ * ```
+ */
+export declare function updateGitignore(outputPaths: string[], options?: GitignoreUpdateOptions): Promise<GitignoreUpdateResult>;
+/**
+ * Collects output paths from generator flags
+ *
+ * @param generatorConfigs - Map of generator names to their configurations
+ * @returns Array of output paths
+ *
+ * @example
+ * ```typescript
+ * const paths = collectOutputPaths({
+ *   payloads: { outputPath: 'src/__gen__/payloads' },
+ *   channels: { outputPath: 'src/__gen__/channels' }
+ * });
+ * // Returns: ['src/__gen__/payloads', 'src/__gen__/channels']
+ * ```
+ */
+export declare function collectOutputPaths(generatorConfigs: Record<string, {
+    outputPath: string;
+} | undefined>): string[];

package/dist/utils/gitignore.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectOutputPaths = exports.updateGitignore = void 0;
+const promises_1 = require("node:fs/promises");
+const path_1 = __importDefault(require("path"));
+/**
+ * Updates or creates a .gitignore file with the specified output paths
+ *
+ * @param outputPaths - Array of paths to add to .gitignore
+ * @param options - Optional configuration for the gitignore update
+ * @returns Result object with operation details
+ *
+ * @example
+ * ```typescript
+ * const result = await updateGitignore(['src/__gen__/payloads', 'src/__gen__/channels']);
+ * if (result.success) {
+ *   console.log(result.message);
+ * }
+ * ```
+ */
+async function updateGitignore(outputPaths, options = {}) {
+    // eslint-disable-next-line no-undef
+    const baseDirectory = options.baseDirectory || process.cwd();
+    const commentHeader = options.commentHeader || '# The Codegen Project - generated files';
+    const gitignorePath = path_1.default.join(baseDirectory, '.gitignore');
+    try {
+        // Check if .gitignore exists
+        await (0, promises_1.access)(gitignorePath);
+        // Read existing content
+        const existingContent = await (0, promises_1.readFile)(gitignorePath, 'utf-8');
+        // Filter out paths that already exist in .gitignore
+        const newPaths = outputPaths.filter((outputPath) => !existingContent.includes(outputPath));
+        if (newPaths.length === 0) {
+            return {
+                success: true,
+                action: 'skipped',
+                message: 'All output directories already present in .gitignore, skipping',
+                addedPaths: []
+            };
+        }
+        // Ensure file ends with newline before adding new entries
+        const separator = existingContent.endsWith('\n') ? '' : '\n';
+        const gitignoreEntry = `${separator}\n${commentHeader}\n${newPaths.join('\n')}\n`;
+        await (0, promises_1.appendFile)(gitignorePath, gitignoreEntry);
+        return {
+            success: true,
+            action: 'updated',
+            message: `Added ${newPaths.length} output director${newPaths.length === 1 ? 'y' : 'ies'} to .gitignore`,
+            addedPaths: newPaths
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            // .gitignore doesn't exist, try to create it
+            try {
+                const gitignoreContent = `${commentHeader}\n${outputPaths.join('\n')}\n`;
+                await (0, promises_1.writeFile)(gitignorePath, gitignoreContent);
+                return {
+                    success: true,
+                    action: 'created',
+                    message: 'Created .gitignore with generated output directories',
+                    addedPaths: outputPaths
+                };
+            }
+            catch (writeError) {
+                // Failed to create .gitignore (e.g., directory doesn't exist)
+                return {
+                    success: false,
+                    action: 'error',
+                    message: `Could not create .gitignore: ${writeError.message}`,
+                    error: writeError.message
+                };
+            }
+        }
+        return {
+            success: false,
+            action: 'error',
+            message: `Could not update .gitignore: ${error.message}`,
+            error: error.message
+        };
+    }
+}
+exports.updateGitignore = updateGitignore;
+/**
+ * Collects output paths from generator flags
+ *
+ * @param generatorConfigs - Map of generator names to their configurations
+ * @returns Array of output paths
+ *
+ * @example
+ * ```typescript
+ * const paths = collectOutputPaths({
+ *   payloads: { outputPath: 'src/__gen__/payloads' },
+ *   channels: { outputPath: 'src/__gen__/channels' }
+ * });
+ * // Returns: ['src/__gen__/payloads', 'src/__gen__/channels']
+ * ```
+ */
+function collectOutputPaths(generatorConfigs) {
+    const outputPaths = [];
+    for (const config of Object.values(generatorConfigs)) {
+        if (config?.outputPath) {
+            outputPaths.push(config.outputPath);
+        }
+    }
+    return outputPaths;
+}
+exports.collectOutputPaths = collectOutputPaths;

package/dist/utils/inputSource.d.ts

@@ -0,0 +1,3 @@
+export type InputSourceType = 'remote_url' | 'local_relative' | 'local_absolute';
+export declare function isRemoteUrl(inputPath: string): boolean;
+export declare function getInputSourceType(inputPath: string): InputSourceType;

package/dist/utils/inputSource.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInputSourceType = exports.isRemoteUrl = void 0;
+/**
+ * Helpers for classifying an input path as a remote URL or a local
+ * filesystem path. Used at the configuration layer to decide whether to
+ * pass the path through `path.resolve` (local) or untouched (remote).
+ */
+const path_1 = __importDefault(require("path"));
+function isRemoteUrl(inputPath) {
+    return inputPath.startsWith('http://') || inputPath.startsWith('https://');
+}
+exports.isRemoteUrl = isRemoteUrl;
+function getInputSourceType(inputPath) {
+    if (isRemoteUrl(inputPath)) {
+        return 'remote_url';
+    }
+    if (path_1.default.isAbsolute(inputPath)) {
+        return 'local_absolute';
+    }
+    return 'local_relative';
+}
+exports.getInputSourceType = getInputSourceType;

package/dist/utils/refResolvers.d.ts

@@ -0,0 +1,29 @@
+import { InputAuthConfig } from '../codegen/types';
+export interface RefResolverContext {
+    /** The URL of the root input document — used to detect cross-host fetches. */
+    rootUrl: string;
+}
+interface OpenapiHttpResolver {
+    order: number;
+    canRead: (file: {
+        url: string;
+    }) => boolean;
+    read: (file: {
+        url: string;
+    }) => Promise<string>;
+    /**
+     * v14 of @apidevtools/json-schema-ref-parser blocks loopback / internal
+     * URLs (127.0.0.1, localhost, etc.) by default. We trust the user's
+     * inputPath, so disable the safe-url check.
+     */
+    safeUrlResolver: false;
+}
+interface AsyncapiResolver {
+    schema: 'http' | 'https';
+    read: (uri: {
+        toString(): string;
+    }) => Promise<string>;
+}
+export declare function createOpenapiRefParserResolver(auth: InputAuthConfig | undefined, context: RefResolverContext): OpenapiHttpResolver;
+export declare function createAsyncapiResolvers(auth: InputAuthConfig | undefined, context: RefResolverContext): AsyncapiResolver[];
+export {};

package/dist/utils/refResolvers.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAsyncapiResolvers = exports.createOpenapiRefParserResolver = void 0;
+/* eslint-disable no-undef */
+/**
+ * Custom http/https resolver factories for cross-spec `$ref`
+ * dereferencing. Both factories delegate to `fetchRemoteDocument` so the
+ * same auth headers are attached to every resolved reference.
+ *
+ * - `createOpenapiRefParserResolver` returns the `resolve.http` shape
+ *   expected by `@apidevtools/json-schema-ref-parser`.
+ * - `createAsyncapiResolvers` returns the resolver array expected by
+ *   `@asyncapi/parser`'s `__unstable.resolver` option (Spectral resolver
+ *   shape, `read(uri): string | undefined | Promise<string | undefined>`).
+ *
+ * Both factories emit a debug log per fetched URL, and an info-level
+ * warning the first time auth headers are sent to a host that differs
+ * from the root document's host.
+ */
+const remoteFetch_1 = require("./remoteFetch");
+const LoggingInterface_1 = require("../LoggingInterface");
+function rootHost(rootUrl) {
+    try {
+        return new URL(rootUrl).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+function createCrossHostWarner(rootUrl, hasAuth) {
+    const root = rootHost(rootUrl);
+    const warnedHosts = new Set();
+    return (refUrl) => {
+        if (!hasAuth || !root) {
+            return;
+        }
+        let refUrlHost;
+        try {
+            refUrlHost = new URL(refUrl).host;
+        }
+        catch {
+            return;
+        }
+        if (!refUrlHost || refUrlHost === root) {
+            return;
+        }
+        if (warnedHosts.has(refUrlHost)) {
+            return;
+        }
+        warnedHosts.add(refUrlHost);
+        LoggingInterface_1.Logger.info(`[remote-fetch] auth headers sent to '${refUrlHost}' while resolving $ref from '${root}'. If this is unexpected, review the spec.`);
+    };
+}
+function createOpenapiRefParserResolver(auth, context) {
+    const warn = createCrossHostWarner(context.rootUrl, Boolean(auth));
+    return {
+        order: 1,
+        safeUrlResolver: false,
+        canRead: (file) => file.url.startsWith('http://') || file.url.startsWith('https://'),
+        read: async (file) => {
+            LoggingInterface_1.Logger.debug(`[remote-fetch] $ref ${file.url}`);
+            warn(file.url);
+            const { content } = await (0, remoteFetch_1.fetchRemoteDocument)(file.url, auth);
+            return content;
+        }
+    };
+}
+exports.createOpenapiRefParserResolver = createOpenapiRefParserResolver;
+function createAsyncapiResolvers(auth, context) {
+    const warn = createCrossHostWarner(context.rootUrl, Boolean(auth));
+    const read = async (uri) => {
+        const url = uri.toString();
+        LoggingInterface_1.Logger.debug(`[remote-fetch] $ref ${url}`);
+        warn(url);
+        const { content } = await (0, remoteFetch_1.fetchRemoteDocument)(url, auth);
+        return content;
+    };
+    return [
+        { schema: 'http', read },
+        { schema: 'https', read }
+    ];
+}
+exports.createAsyncapiResolvers = createAsyncapiResolvers;

package/dist/utils/remoteFetch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fetches a remote document over http(s) with optional auth headers,
+ * a timeout, and typed errors. Used by every input parser when
+ * `inputPath` is a URL.
+ *
+ * SECURITY NOTE: When `auth` is configured, the headers are sent to
+ * **every** URL fetched through this helper, including external `$ref`
+ * targets on other hosts. See docs/configurations#auth-scope for details.
+ */
+import { InputAuthConfig } from '../codegen/types';
+export interface FetchedDocument {
+    content: string;
+    contentType: string | null;
+    finalUrl: string;
+}
+export declare function fetchRemoteDocument(url: string, auth?: InputAuthConfig, options?: {
+    timeoutMs?: number;
+}): Promise<FetchedDocument>;

package/dist/utils/remoteFetch.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchRemoteDocument = void 0;
+const errors_1 = require("../codegen/errors");
+const LoggingInterface_1 = require("../LoggingInterface");
+const DEFAULT_TIMEOUT_MS = 30_000;
+async function fetchRemoteDocument(url, auth, options = {}) {
+    LoggingInterface_1.Logger.debug(`[remote-fetch] GET ${url}`);
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: buildAuthHeaders(auth),
+            signal: controller.signal,
+            redirect: 'follow'
+        });
+        if (!response.ok) {
+            throw (0, errors_1.createRemoteFetchError)({
+                url,
+                status: response.status,
+                statusText: response.statusText,
+                reason: 'http'
+            });
+        }
+        const content = await response.text();
+        return {
+            content,
+            contentType: response.headers.get('content-type'),
+            finalUrl: response.url || url
+        };
+    }
+    catch (cause) {
+        if (cause instanceof errors_1.CodegenError) {
+            throw cause;
+        }
+        if (cause instanceof Error &&
+            (cause.name === 'AbortError' ||
+                cause.message?.toLowerCase().includes('aborted'))) {
+            throw (0, errors_1.createRemoteFetchError)({ url, reason: 'timeout', cause });
+        }
+        throw (0, errors_1.createRemoteFetchError)({ url, reason: 'network', cause });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+exports.fetchRemoteDocument = fetchRemoteDocument;
+function buildAuthHeaders(auth) {
+    if (!auth) {
+        return {};
+    }
+    switch (auth.type) {
+        case 'bearer':
+            return { Authorization: `Bearer ${auth.token}` };
+        case 'apiKey':
+            return { [auth.header]: auth.value };
+        case 'custom':
+            return { ...auth.headers };
+        default:
+            return {};
+    }
+}