@cisco_open/linting-orchestrator 1.0.0-rc.4

package/build/cli/utils/embedded-server.js

@@ -0,0 +1,61 @@
+/**
+ * Embedded Server Lifecycle Management
+ *
+ * Handles auto-start/stop of embedded server for CLI commands
+ */
+import { startServer } from '../../server.js';
+import { createEmbeddedModeConfig } from '../../config.js';
+import { getConfigManager } from '../config-manager.js';
+/**
+ * Start embedded server if needed based on CLI config
+ * Returns shutdown function to be called in finally block
+ *
+ * @param apiUrl Optional API URL override (if provided, don't start embedded server)
+ * @returns Shutdown function or null if server not started
+ */
+export async function maybeStartEmbeddedServer(apiUrl) {
+    // If explicit API URL provided, assume external server
+    if (apiUrl) {
+        return null;
+    }
+    // Check CLI config for mode
+    const configManager = getConfigManager();
+    const config = await configManager.get();
+    // Only auto-start if in embedded mode
+    if (config.defaultMode !== 'embedded') {
+        return null;
+    }
+    // Start embedded server (TODO: add quiet flag to startServer())
+    const serverConfig = createEmbeddedModeConfig();
+    const server = await startServer(serverConfig);
+    // Return shutdown function
+    return async () => {
+        // Forcefully close server
+        try {
+            await server.shutdown();
+        }
+        catch (error) {
+            // Ignore shutdown errors in embedded mode
+        }
+        // Force exit after brief delay if still hanging
+        setTimeout(() => {
+            process.exit(0);
+        }, 1000).unref();
+    };
+}
+/**
+ * Get API URL based on current CLI configuration
+ *
+ * @param explicitUrl Optional explicit URL override
+ * @returns API URL to use
+ */
+export async function getApiUrl(explicitUrl) {
+    if (explicitUrl) {
+        return explicitUrl;
+    }
+    const configManager = getConfigManager();
+    const config = await configManager.get();
+    const port = config.ports[config.defaultMode];
+    return `http://localhost:${port}`;
+}
+//# sourceMappingURL=embedded-server.js.map

package/build/cli/utils/embedded-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded-server.js","sourceRoot":"","sources":["../../../src/cli/utils/embedded-server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAe;IAEf,uDAAuD;IACvD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4BAA4B;IAC5B,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC;IAEzC,sCAAsC;IACtC,IAAI,MAAM,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gEAAgE;IAChE,MAAM,YAAY,GAAG,wBAAwB,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,YAAY,CAAC,CAAC;IAE/C,2BAA2B;IAC3B,OAAO,KAAK,IAAI,EAAE;QAChB,0BAA0B;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,0CAA0C;QAC5C,CAAC;QAED,gDAAgD;QAChD,UAAU,CAAC,GAAG,EAAE;YACd,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,WAAoB;IAClD,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAE9C,OAAO,oBAAoB,IAAI,EAAE,CAAC;AACpC,CAAC"}

package/build/cli/utils/mode-validator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mode-specific command validation
+ *
+ * Ensures commands are only used in appropriate modes
+ */
+/**
+ * Check if command is allowed in current mode
+ * Exits with helpful error message if not allowed
+ *
+ * @param commandName Name of the command being run
+ */
+export declare function requireServerMode(commandName: string): Promise<void>;
+//# sourceMappingURL=mode-validator.d.ts.map

package/build/cli/utils/mode-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-validator.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/mode-validator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB1E"}

package/build/cli/utils/mode-validator.js

@@ -0,0 +1,31 @@
+/**
+ * Mode-specific command validation
+ *
+ * Ensures commands are only used in appropriate modes
+ */
+import chalk from 'chalk';
+import { getConfigManager } from '../config-manager.js';
+/**
+ * Check if command is allowed in current mode
+ * Exits with helpful error message if not allowed
+ *
+ * @param commandName Name of the command being run
+ */
+export async function requireServerMode(commandName) {
+    const configManager = getConfigManager();
+    const config = await configManager.get();
+    if (config.defaultMode === 'embedded') {
+        console.error(chalk.red(`\n❌ Command '${commandName}' is not available in embedded mode\n`));
+        console.log('Embedded mode is for quick, self-contained linting without server management.');
+        console.log('This command is only available in standalone or companion modes.\n');
+        console.log(chalk.cyan('Available commands in embedded mode:'));
+        console.log('  • spectify lint <file>       - Lint an OpenAPI document');
+        console.log('  • spectify health            - Check service health (embedded server)');
+        console.log('  • spectify rulesets          - List available rulesets');
+        console.log('  • spectify config            - Manage CLI configuration\n');
+        console.log(chalk.cyan('To use this command, switch to standalone mode:'));
+        console.log(`  spectify config set mode standalone\n`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=mode-validator.js.map

package/build/cli/utils/mode-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-validator.js","sourceRoot":"","sources":["../../../src/cli/utils/mode-validator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,WAAmB;IACzD,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC;IAEzC,IAAI,MAAM,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QACtC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,WAAW,uCAAuC,CAAC,CAAC,CAAC;QAC7F,OAAO,CAAC,GAAG,CAAC,+EAA+E,CAAC,CAAC;QAC7F,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;QAClF,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC;QACzE,OAAO,CAAC,GAAG,CAAC,yEAAyE,CAAC,CAAC;QACvF,OAAO,CAAC,GAAG,CAAC,0DAA0D,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC;QAC3E,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC,CAAC;QAC3E,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;QACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/build/cli/utils/port-checker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Port Checker - Utility to check if a port is available
+ */
+export interface PortCheckResult {
+    available: boolean;
+    port: number;
+}
+/**
+ * Check if a port is available
+ */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/**
+ * Find the next available port starting from a given port
+ */
+export declare function findAvailablePort(startPort: number, maxAttempts?: number): Promise<number | null>;
+/**
+ * Check multiple ports and return their availability status
+ */
+export declare function checkPorts(ports: number[]): Promise<PortCheckResult[]>;
+//# sourceMappingURL=port-checker.d.ts.map

package/build/cli/utils/port-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-checker.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/port-checker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBpE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAW,GACvB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAQ5E"}

package/build/cli/utils/port-checker.js

@@ -0,0 +1,49 @@
+/**
+ * Port Checker - Utility to check if a port is available
+ */
+import net from 'net';
+/**
+ * Check if a port is available
+ */
+export async function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                resolve(false);
+            }
+            else {
+                resolve(false);
+            }
+        });
+        server.once('listening', () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port, '0.0.0.0');
+    });
+}
+/**
+ * Find the next available port starting from a given port
+ */
+export async function findAvailablePort(startPort, maxAttempts = 10) {
+    for (let i = 0; i < maxAttempts; i++) {
+        const port = startPort + i;
+        const available = await isPortAvailable(port);
+        if (available) {
+            return port;
+        }
+    }
+    return null;
+}
+/**
+ * Check multiple ports and return their availability status
+ */
+export async function checkPorts(ports) {
+    const results = await Promise.all(ports.map(async (port) => ({
+        port,
+        available: await isPortAvailable(port),
+    })));
+    return results;
+}
+//# sourceMappingURL=port-checker.js.map

package/build/cli/utils/port-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-checker.js","sourceRoot":"","sources":["../../../src/cli/utils/port-checker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,GAAG,MAAM,KAAK,CAAC;AAOtB;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IAChD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAElC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;YAClD,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC9B,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;YAC5B,MAAM,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAiB,EACjB,cAAsB,EAAE;IAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,SAAS,GAAG,CAAC,CAAC;QAC3B,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAe;IAC9C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QACzB,IAAI;QACJ,SAAS,EAAE,MAAM,eAAe,CAAC,IAAI,CAAC;KACvC,CAAC,CAAC,CACJ,CAAC;IACF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/build/config.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Configuration loader for OpenAPI Lint Orchestrator
+ *
+ * Zero-config by default with sensible defaults
+ * Optional YAML file for advanced configuration
+ * Environment variable overrides always available
+ */
+import 'dotenv/config';
+import type { OrchestratorConfig } from './types.js';
+/**
+ * Resolve a resolver module name to its absolute file path.
+ * Module lives in `{packageRoot}/resolvers/{name}.js`.
+ * Returns `undefined` if `name` is falsy (disabled).
+ */
+export declare function resolveResolverPath(name: string | undefined): string | undefined;
+/**
+ * Resolve the orchestrator home directory.
+ * SPECTIFY_HOME env var overrides the default ~/.spectify.
+ * Used as the base for all runtime data (uploads, reports, config).
+ */
+export declare function spectifyHome(): string;
+/**
+ * Load configuration from optional file or use defaults
+ */
+export declare function loadConfig(configPath?: string): Promise<OrchestratorConfig>;
+/**
+ * Validate configuration
+ */
+export declare function validateConfig(config: OrchestratorConfig): void;
+/**
+ * Get configuration summary for logging
+ */
+export declare function getConfigSummary(config: OrchestratorConfig): Record<string, any>;
+/**
+ * Create lightweight configuration for embedded mode
+ *
+ * Used by CLI when starting embedded server
+ * Optimized for single-user, developer laptop use
+ */
+export declare function createEmbeddedModeConfig(overrides?: Partial<OrchestratorConfig>): OrchestratorConfig;
+/**
+ * Create production configuration for standalone server mode
+ *
+ * Used when running spectifyd as dedicated process
+ * Optimized for production, multi-user, always-on deployments
+ * Document store defaults to ~/.spectify/uploads (user home directory)
+ */
+export declare function createStandaloneModeConfig(overrides?: Partial<OrchestratorConfig>): OrchestratorConfig;
+/**
+ * Create configuration for MCP companion mode
+ *
+ * Used when the orchestrator is started by MCP OpenAPI Analyzer
+ * Shares MCP's document store, lighter resource footprint
+ * Document store path MUST be provided explicitly (no default)
+ */
+export declare function createCompanionModeConfig(overrides?: Partial<OrchestratorConfig>): OrchestratorConfig;
+//# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,OAAO,eAAe,CAAC;AAMvB,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,YAAY,CAAC;AAOnE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIhF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAqDD;;GAEG;AACH,wBAAsB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAwBjF;AAuND;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAgC/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAchF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAyDpG;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAyDtG;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAuDrG"}