@cisco_open/linting-orchestrator 1.0.0-rc.4

package/build/formatters/sarif-builder.js

@@ -0,0 +1,276 @@
+/**
+ * SARIF 2.1.0 Builder
+ *
+ * Transforms LintJobResult into SARIF (Static Analysis Results Interchange Format)
+ * Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+ *
+ * @module formatters/sarif-builder
+ */
+import crypto from 'crypto';
+/**
+ * SarifBuilder - Converts lint results to SARIF 2.1.0 format
+ */
+export class SarifBuilder {
+    /**
+     * Build a complete SARIF report from lint job result
+     */
+    buildSarif(result, options) {
+        return {
+            $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+            version: '2.1.0',
+            runs: [this.buildRun(result, options)],
+        };
+    }
+    /**
+     * Build a SARIF run from lint result
+     */
+    buildRun(result, options) {
+        return {
+            tool: this.buildTool(result),
+            artifacts: this.buildArtifacts(result),
+            results: this.buildResults(result, options),
+            properties: this.buildRunProperties(result),
+        };
+    }
+    /**
+     * Build tool metadata
+     */
+    buildTool(result) {
+        // Use a simple version string or parse from result
+        const version = '0.7.0'; // Updated when server version changes
+        return {
+            driver: {
+                name: 'cisco-linting-orchestrator',
+                version: version,
+                informationUri: 'https://github.com/cisco-open/linting-orchestrator',
+                rules: this.buildRules(result),
+            },
+        };
+    }
+    /**
+     * Build rule catalog from lint issues
+     * Creates unique rule entries from all issues
+     */
+    buildRules(result) {
+        const rulesMap = new Map();
+        for (const issue of result.results) {
+            if (!rulesMap.has(issue.code)) {
+                rulesMap.set(issue.code, {
+                    id: issue.code,
+                    shortDescription: {
+                        text: this.extractShortDescription(issue.message),
+                    },
+                    fullDescription: {
+                        text: issue.message,
+                    },
+                    defaultConfiguration: {
+                        level: this.mapSeverityToSarifLevel(issue.severity),
+                    },
+                    helpUri: this.buildHelpUri(result, issue),
+                    properties: {
+                        category: this.extractCategory(issue),
+                        tags: this.extractTags(issue),
+                    },
+                });
+            }
+        }
+        return Array.from(rulesMap.values());
+    }
+    /**
+     * Extract short description from message (first sentence or up to 80 chars)
+     */
+    extractShortDescription(message) {
+        // Try to find first sentence
+        const firstSentence = message.match(/^[^.!?]+[.!?]/);
+        if (firstSentence) {
+            return firstSentence[0];
+        }
+        // Fallback: truncate at 80 chars
+        if (message.length > 80) {
+            return message.substring(0, 77) + '...';
+        }
+        return message;
+    }
+    /**
+     * Build help URI for a rule
+     */
+    buildHelpUri(result, issue) {
+        // For PubHub ruleset, use PubHub docs
+        if (result.rulesetName === 'pubhub') {
+            return `https://pubhub.cisco.com/docs/spectify/rules/${issue.code}`;
+        }
+        // Generic orchestrator docs
+        return `https://github.com/cisco-open/spectify/docs/rules/${issue.code}`;
+    }
+    /**
+     * Extract category from issue (if available in path or code)
+     */
+    extractCategory(issue) {
+        // Try to extract from code (e.g., "devx-publishing-001" → "publishing")
+        const categoryMatch = issue.code.match(/^[a-z]+-([a-z]+)-/);
+        if (categoryMatch) {
+            return categoryMatch[1];
+        }
+        return 'general';
+    }
+    /**
+     * Extract tags from issue
+     */
+    extractTags(issue) {
+        const tags = [];
+        // Add severity as tag (map number to string)
+        const severityNames = ['error', 'warning', 'info', 'hint'];
+        tags.push(severityNames[issue.severity] || 'warning');
+        // Add category
+        const category = this.extractCategory(issue);
+        if (category !== 'general') {
+            tags.push(category);
+        }
+        return tags;
+    }
+    /**
+     * Map severity to SARIF level
+     */
+    mapSeverityToSarifLevel(severity) {
+        // 0=error, 1=warn, 2=info, 3=hint
+        switch (severity) {
+            case 0:
+                return 'error';
+            case 1:
+                return 'warning';
+            case 2:
+            case 3:
+                return 'note';
+            default:
+                return 'warning';
+        }
+    }
+    /**
+     * Build artifact metadata (document being analyzed)
+     */
+    buildArtifacts(result) {
+        return [
+            {
+                location: {
+                    uri: `file://${result.documentId}`,
+                },
+                properties: {
+                    documentId: result.documentId,
+                    documentName: result.documentId, // Could be enriched with actual name
+                },
+            },
+        ];
+    }
+    /**
+     * Build SARIF results from lint issues
+     */
+    buildResults(result, options) {
+        return result.results.map((issue) => this.buildResult(result, issue, options));
+    }
+    /**
+     * Build a single SARIF result from a lint issue
+     */
+    buildResult(result, issue, options) {
+        // Map numeric severity to string for properties
+        const severityNames = ['error', 'warning', 'info', 'hint'];
+        const severityString = severityNames[issue.severity] || 'warning';
+        return {
+            ruleId: issue.code,
+            level: this.mapSeverityToSarifLevel(issue.severity),
+            message: {
+                text: issue.message,
+            },
+            locations: this.buildLocations(result, issue, options),
+            fingerprints: this.generateFingerprints(result, issue),
+            properties: {
+                severity: severityString,
+                path: issue.path,
+                rulesetName: result.rulesetName,
+                rulesetVersion: result.rulesetVersion,
+            },
+        };
+    }
+    /**
+     * Build locations for an issue
+     */
+    buildLocations(result, issue, options) {
+        const location = {
+            physicalLocation: {
+                artifactLocation: {
+                    uri: `file://${result.documentId}`,
+                },
+                region: this.buildRegion(issue, options),
+            },
+        };
+        return [location];
+    }
+    /**
+     * Build region (line/column range) for an issue
+     */
+    buildRegion(issue, _options) {
+        if (!issue.range) {
+            return undefined;
+        }
+        const region = {
+            startLine: issue.range.start.line,
+            startColumn: issue.range.start.character,
+        };
+        if (issue.range.end) {
+            region.endLine = issue.range.end.line;
+            region.endColumn = issue.range.end.character;
+        }
+        // Note: the orchestrator's LintIssue doesn't have snippet field currently
+        // This can be added in future if needed
+        return region;
+    }
+    /**
+     * Generate fingerprints for deduplication
+     * Uses primaryLocationLineHash scheme (path + line + rule)
+     */
+    generateFingerprints(result, issue) {
+        const fingerprints = {};
+        // Primary location line hash (standard scheme)
+        const primaryLocation = this.buildPrimaryLocationHash(result, issue);
+        fingerprints.primaryLocationLineHash = primaryLocation;
+        return fingerprints;
+    }
+    /**
+     * Build primary location hash for fingerprinting
+     * Format: hash(documentId + path + line + ruleId)
+     */
+    buildPrimaryLocationHash(result, issue) {
+        const components = [
+            result.documentId,
+            issue.path.map(String).join('/'),
+            issue.range?.start.line ?? 0,
+            issue.code,
+        ];
+        const input = components.join(':');
+        return crypto.createHash('sha256').update(input).digest('hex').substring(0, 16);
+    }
+    /**
+     * Build run properties (orchestrator-specific metadata)
+     */
+    buildRunProperties(result) {
+        return {
+            spectify: {
+                jobId: result.jobId,
+                documentId: result.documentId,
+                rulesetName: result.rulesetName,
+                rulesetVersion: result.rulesetVersion,
+                executionTime: result.totalExecutionTime,
+                timestamp: result.timestamp.toISOString(),
+                summary: {
+                    totalIssues: result.summary.totalIssues,
+                    bySeverity: {
+                        error: result.summary.errorCount,
+                        warning: result.summary.warningCount,
+                        info: result.summary.infoCount,
+                        hint: result.summary.hintCount,
+                    },
+                },
+            },
+        };
+    }
+}
+//# sourceMappingURL=sarif-builder.js.map

package/build/formatters/sarif-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif-builder.js","sourceRoot":"","sources":["../../src/formatters/sarif-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAgB5B;;GAEG;AACH,MAAM,OAAO,YAAY;IACvB;;OAEG;IACH,UAAU,CAAC,MAAqB,EAAE,OAAiC;QACjE,OAAO;YACL,OAAO,EAAE,+CAA+C;YACxD,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACvC,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,QAAQ,CAAC,MAAqB,EAAE,OAAiC;QACvE,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;YAC5B,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;YACtC,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC;YAC3C,UAAU,EAAE,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC;SAC5C,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,MAAqB;QACrC,mDAAmD;QACnD,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,sCAAsC;QAE/D,OAAO;YACL,MAAM,EAAE;gBACN,IAAI,EAAE,4BAA4B;gBAClC,OAAO,EAAE,OAAO;gBAChB,cAAc,EAAE,oDAAoD;gBACpE,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;aAC/B;SACF,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,UAAU,CAAC,MAAqB;QACtC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;QAE9C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE;oBACvB,EAAE,EAAE,KAAK,CAAC,IAAI;oBACd,gBAAgB,EAAE;wBAChB,IAAI,EAAE,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC,OAAO,CAAC;qBAClD;oBACD,eAAe,EAAE;wBACf,IAAI,EAAE,KAAK,CAAC,OAAO;qBACpB;oBACD,oBAAoB,EAAE;wBACpB,KAAK,EAAE,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC,QAAQ,CAAC;qBACpD;oBACD,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC;oBACzC,UAAU,EAAE;wBACV,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC;wBACrC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;qBAC9B;iBACF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACK,uBAAuB,CAAC,OAAe;QAC7C,6BAA6B;QAC7B,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QACrD,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;QAED,iCAAiC;QACjC,IAAI,OAAO,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC;QAC1C,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,MAAqB,EAAE,KAAgB;QAC1D,sCAAsC;QACtC,IAAI,MAAM,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO,gDAAgD,KAAK,CAAC,IAAI,EAAE,CAAC;QACtE,CAAC;QAED,4BAA4B;QAC5B,OAAO,qDAAqD,KAAK,CAAC,IAAI,EAAE,CAAC;IAC3E,CAAC;IAED;;OAEG;IACK,eAAe,CAAC,KAAgB;QACtC,wEAAwE;QACxE,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAC5D,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,KAAgB;QAClC,MAAM,IAAI,GAAa,EAAE,CAAC;QAE1B,6CAA6C;QAC7C,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC,CAAC;QAEtD,eAAe;QACf,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtB,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACK,uBAAuB,CAAC,QAAuB;QACrD,kCAAkC;QAClC,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,CAAC;gBACJ,OAAO,OAAO,CAAC;YACjB,KAAK,CAAC;gBACJ,OAAO,SAAS,CAAC;YACnB,KAAK,CAAC,CAAC;YACP,KAAK,CAAC;gBACJ,OAAO,MAAM,CAAC;YAChB;gBACE,OAAO,SAAS,CAAC;QACrB,CAAC;IACH,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,MAAqB;QAC1C,OAAO;YACL;gBACE,QAAQ,EAAE;oBACR,GAAG,EAAE,UAAU,MAAM,CAAC,UAAU,EAAE;iBACnC;gBACD,UAAU,EAAE;oBACV,UAAU,EAAE,MAAM,CAAC,UAAU;oBAC7B,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,qCAAqC;iBACvE;aACF;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,MAAqB,EAAE,OAAiC;QAC3E,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;IACjF,CAAC;IAED;;OAEG;IACK,WAAW,CACjB,MAAqB,EACrB,KAAgB,EAChB,OAAiC;QAEjC,gDAAgD;QAChD,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC3D,MAAM,cAAc,GAAG,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC;QAElE,OAAO;YACL,MAAM,EAAE,KAAK,CAAC,IAAI;YAClB,KAAK,EAAE,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC,QAAQ,CAAC;YACnD,OAAO,EAAE;gBACP,IAAI,EAAE,KAAK,CAAC,OAAO;aACpB;YACD,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC;YACtD,YAAY,EAAE,IAAI,CAAC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC;YACtD,UAAU,EAAE;gBACV,QAAQ,EAAE,cAAc;gBACxB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,cAAc,EAAE,MAAM,CAAC,cAAc;aACtC;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,cAAc,CACpB,MAAqB,EACrB,KAAgB,EAChB,OAAiC;QAEjC,MAAM,QAAQ,GAAkB;YAC9B,gBAAgB,EAAE;gBAChB,gBAAgB,EAAE;oBAChB,GAAG,EAAE,UAAU,MAAM,CAAC,UAAU,EAAE;iBACnC;gBACD,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC;aACzC;SACF,CAAC;QAEF,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpB,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,KAAgB,EAAE,QAAkC;QACtE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,MAAM,GAAgB;YAC1B,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;YACjC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS;SACzC,CAAC;QAEF,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YACpB,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;YACtC,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;QAC/C,CAAC;QAED,0EAA0E;QAC1E,wCAAwC;QAExC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACK,oBAAoB,CAAC,MAAqB,EAAE,KAAgB;QAClE,MAAM,YAAY,GAA2B,EAAE,CAAC;QAEhD,+CAA+C;QAC/C,MAAM,eAAe,GAAG,IAAI,CAAC,wBAAwB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACrE,YAAY,CAAC,uBAAuB,GAAG,eAAe,CAAC;QAEvD,OAAO,YAAY,CAAC;IACtB,CAAC;IAED;;;OAGG;IACK,wBAAwB,CAAC,MAAqB,EAAE,KAAgB;QACtE,MAAM,UAAU,GAAG;YACjB,MAAM,CAAC,UAAU;YACjB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;YAChC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC;YAC5B,KAAK,CAAC,IAAI;SACX,CAAC;QAEF,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAClF,CAAC;IAED;;OAEG;IACK,kBAAkB,CAAC,MAAqB;QAC9C,OAAO;YACL,QAAQ,EAAE;gBACR,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,cAAc,EAAE,MAAM,CAAC,cAAc;gBACrC,aAAa,EAAE,MAAM,CAAC,kBAAkB;gBACxC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE;gBACzC,OAAO,EAAE;oBACP,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,WAAW;oBACvC,UAAU,EAAE;wBACV,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,UAAU;wBAChC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,YAAY;wBACpC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS;wBAC9B,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS;qBAC/B;iBACF;aACF;SACF,CAAC;IACJ,CAAC;CACF"}

package/build/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/build/index.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// Copyright 2026 Cisco Systems, Inc. and its affiliates
+//
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Orchestrator server CLI
+ *
+ * Primary entrypoint for running orchestrator as a server.
+ * Supports two modes:
+ * - standalone: Independent server with own document store (~/.spectify/uploads)
+ * - companion: Integrates with MCP, requires --document-store path
+ *
+ * Used when running:
+ * - `npm start`
+ * - `node build/index.js`
+ * - `spectifyd` (global binary)
+ *
+ * @module index
+ */
+import { Command } from 'commander';
+import { startServer } from './server.js';
+import { API_VERSION } from './utils/version.js';
+import { createStandaloneModeConfig, createCompanionModeConfig, spectifyHome } from './config.js';
+import * as path from 'path';
+import chalk from 'chalk';
+const program = new Command();
+program
+    .name('spectifyd')
+    .description('Linting orchestrator daemon (spectifyd)')
+    .option('-p, --port <port>', 'server port (local: 3003, passthrough: 3004)', (val) => parseInt(val, 10))
+    .option('-H, --host <host>', 'server host', '0.0.0.0')
+    .option('-d, --store-directory <path>', 'directory where documents are stored')
+    .option('-t, --store-type <type>', 'document store type: local or passthrough', 'local')
+    .option('-r, --rulesets-directory <path>', 'directory containing rulesets (or set SPECTIFYD_RULESETS_DIR)')
+    .option('--max-workers <count>', 'maximum total workers', (val) => parseInt(val, 10))
+    .option('--log-level <level>', 'log level: error, warn, info, debug, trace', 'info')
+    .version(API_VERSION, '-V, --version', 'output the API server version')
+    .helpOption('-h, --help', 'display help for command')
+    .addHelpText('after', `
+Examples:
+  ${chalk.cyan('Standalone')} (local document storage, default):
+    $ spectifyd
+    $ spectifyd --store-type local --store-directory $HOME/.spectify/uploads
+
+  ${chalk.cyan('Companion')} (passthrough store of an MCP server):
+    $ spectifyd --store-type passthrough --store-directory /path/to/mcp/documents
+`);
+program.parse(process.argv);
+const options = program.opts();
+/**
+ * Main function - starts server with graceful shutdown
+ */
+async function main() {
+    try {
+        // Validate store type
+        const storeType = options.storeType;
+        if (storeType !== 'local' && storeType !== 'passthrough') {
+            console.error(chalk.red(`Error: Invalid store type '${storeType}'. Must be 'local' or 'passthrough'`));
+            process.exit(1);
+        }
+        // Determine port (default based on store type)
+        const defaultPort = storeType === 'passthrough' ? 3004 : 3003;
+        const port = options.port || parseInt(process.env.SPECTIFYD_PORT || '', 10) || defaultPort;
+        // Determine store directory
+        let storeDirectory;
+        if (storeType === 'passthrough') {
+            // Passthrough: require explicit directory
+            storeDirectory = options.storeDirectory || process.env.SPECTIFYD_DOCUMENT_STORE_DIR || '';
+            if (!storeDirectory) {
+                console.error(chalk.red('\nError: --store-directory is required for passthrough type'));
+                console.log(chalk.yellow('\nPassthrough storage integrates with external systems like MCP.'));
+                console.log(chalk.yellow('You must specify the path to the external document directory:\n'));
+                console.log(chalk.gray('  spectifyd --store-type passthrough --store-directory /path/to/documents\n'));
+                process.exit(1);
+            }
+        }
+        else {
+            // Local: default to $SPECTIFY_HOME/uploads
+            const defaultDir = path.join(spectifyHome(), 'uploads');
+            storeDirectory = options.storeDirectory || process.env.SPECTIFYD_DOCUMENT_STORE_DIR || defaultDir;
+        }
+        // Build configuration (use companion/standalone configs for convenience)
+        let config;
+        if (storeType === 'passthrough') {
+            config = createCompanionModeConfig();
+        }
+        else {
+            config = createStandaloneModeConfig();
+        }
+        // Apply CLI overrides
+        config.server.port = port;
+        config.server.host = options.host || config.server.host;
+        if (config.documentStore) {
+            config.documentStore.baseDir = storeDirectory;
+            config.documentStore.type = storeType;
+        }
+        const rulesetsDir = options.rulesetsDirectory || process.env.SPECTIFYD_RULESETS_DIR;
+        if (rulesetsDir) {
+            config.rulesets.directory = rulesetsDir;
+        }
+        if (options.logLevel) {
+            config.logging.level = options.logLevel;
+        }
+        if (options.maxWorkers) {
+            config.workerPool.totalMaxWorkers = options.maxWorkers;
+        }
+        // Validate Report Service availability (if enabled and required)
+        if (config.reportService?.enabled && config.reportService?.stopIfUnavailable) {
+            try {
+                console.log(chalk.gray('Checking Report Service availability...'));
+                const response = await fetch(`${config.reportService.url}/health`, {
+                    method: 'GET',
+                    signal: AbortSignal.timeout(5000) // 5 second timeout
+                });
+                if (!response.ok) {
+                    throw new Error(`Report Service returned status ${response.status}`);
+                }
+                console.log(chalk.green('✓ Report Service available'));
+            }
+            catch (error) {
+                const mode = storeType === 'passthrough' ? 'Companion' : 'Standalone';
+                console.error(chalk.red(`\nError: ${mode} mode requires Report Service to be running.`));
+                console.error(chalk.yellow('\nReport Service is not available at:'), config.reportService.url);
+                console.error(chalk.yellow('\nPlease start the Report Service:'));
+                console.error(chalk.gray('  spectifyr'));
+                console.error(chalk.yellow('\nOr disable report integration in .env:'));
+                console.error(chalk.gray('  SPECTIFYD_REPORTS_ENABLED=false\n'));
+                process.exit(1);
+            }
+        }
+        else if (config.reportService?.enabled && !config.reportService?.stopIfUnavailable) {
+            // Light mode: just log warning if unavailable
+            try {
+                const response = await fetch(`${config.reportService.url}/health`, {
+                    method: 'GET',
+                    signal: AbortSignal.timeout(2000) // Shorter timeout for non-critical check
+                });
+                if (response.ok) {
+                    console.log(chalk.green('✓ Report Service available'));
+                }
+                else {
+                    console.log(chalk.yellow('⚠ Report Service unavailable - notifications will be queued'));
+                }
+            }
+            catch {
+                console.log(chalk.yellow('⚠ Report Service unavailable - notifications will be queued'));
+            }
+        }
+        // Start server
+        const instance = await startServer(config);
+        // Setup graceful shutdown handlers
+        const shutdownHandler = async (signal) => {
+            console.log(chalk.yellow(`\n\nReceived ${signal}, shutting down gracefully...`));
+            try {
+                await instance.shutdown();
+                console.log(chalk.green('✅ Server stopped'));
+                process.exit(0);
+            }
+            catch (error) {
+                console.error(chalk.red('Error during shutdown:'), error);
+                process.exit(1);
+            }
+        };
+        process.on('SIGINT', () => shutdownHandler('SIGINT'));
+        process.on('SIGTERM', () => shutdownHandler('SIGTERM'));
+    }
+    catch (error) {
+        console.error(chalk.red('Fatal error:'), error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+// Start the server
+main();
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/logger.d.ts

@@ -0,0 +1,38 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogContext {
+    correlationId?: string;
+    jobId?: string;
+    documentId?: string;
+    rulesetName?: string;
+    workerId?: string;
+    [key: string]: any;
+}
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    context?: LogContext;
+    error?: {
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+}
+declare class Logger {
+    private level;
+    private format;
+    configure(level: LogLevel, format?: 'json' | 'text'): void;
+    private shouldLog;
+    private formatLog;
+    private log;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext, error?: Error): void;
+    error(message: string, context?: LogContext, error?: Error): void;
+}
+export declare const logger: Logger;
+export declare function generateCorrelationId(): string;
+export declare function createRequestContext(correlationId?: string): LogContext;
+export declare function withContext(baseContext: LogContext, additionalContext: Partial<LogContext>): LogContext;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/build/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,cAAM,MAAM;IACV,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,MAAM,CAA2B;IAEzC,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAE,MAAM,GAAG,MAAe;IAK3D,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,SAAS;IA8BjB,OAAO,CAAC,GAAG;IA+BX,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU;IAI3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU;IAI1C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,KAAK;IAIzD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,KAAK;CAG3D;AAGD,eAAO,MAAM,MAAM,QAAe,CAAC;AAMnC,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,wBAAgB,oBAAoB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,UAAU,CAIvE;AAMD,wBAAgB,WAAW,CAAC,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAEvG"}

package/build/logger.js

@@ -0,0 +1,105 @@
+// Copyright 2026 Cisco Systems, Inc. and its affiliates
+//
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Structured Logging with Correlation IDs
+ *
+ * Provides consistent logging format with request correlation
+ */
+import { randomUUID } from 'crypto';
+class Logger {
+    level = 'info';
+    format = 'json';
+    configure(level, format = 'json') {
+        this.level = level;
+        this.format = format;
+    }
+    shouldLog(level) {
+        const levels = ['debug', 'info', 'warn', 'error'];
+        return levels.indexOf(level) >= levels.indexOf(this.level);
+    }
+    formatLog(entry) {
+        if (this.format === 'json') {
+            return JSON.stringify(entry);
+        }
+        // Text format
+        const timestamp = entry.timestamp;
+        const level = entry.level.toUpperCase().padEnd(5);
+        const correlationId = entry.context?.correlationId
+            ? `[${entry.context.correlationId.substring(0, 8)}]`
+            : '';
+        let message = `${timestamp} ${level} ${correlationId} ${entry.message}`;
+        if (entry.context && Object.keys(entry.context).length > 1) {
+            const ctx = { ...entry.context };
+            delete ctx.correlationId;
+            message += ` ${JSON.stringify(ctx)}`;
+        }
+        if (entry.error) {
+            message += `\n  Error: ${entry.error.message}`;
+            if (entry.error.stack) {
+                message += `\n${entry.error.stack}`;
+            }
+        }
+        return message;
+    }
+    log(level, message, context, error) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            context
+        };
+        if (error) {
+            entry.error = {
+                message: error.message,
+                stack: error.stack,
+                code: error.code
+            };
+        }
+        const formatted = this.formatLog(entry);
+        if (level === 'error') {
+            console.error(formatted);
+        }
+        else if (level === 'warn') {
+            console.warn(formatted);
+        }
+        else {
+            console.log(formatted);
+        }
+    }
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    warn(message, context, error) {
+        this.log('warn', message, context, error);
+    }
+    error(message, context, error) {
+        this.log('error', message, context, error);
+    }
+}
+// Singleton instance
+export const logger = new Logger();
+// ============================================
+// Correlation ID Management
+// ============================================
+export function generateCorrelationId() {
+    return randomUUID();
+}
+export function createRequestContext(correlationId) {
+    return {
+        correlationId: correlationId || generateCorrelationId()
+    };
+}
+// ============================================
+// Helper Functions
+// ============================================
+export function withContext(baseContext, additionalContext) {
+    return { ...baseContext, ...additionalContext };
+}
+//# sourceMappingURL=logger.js.map

package/build/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/build/mock-server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mock-server.d.ts.map

package/build/mock-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-server.d.ts","sourceRoot":"","sources":["../src/mock-server.ts"],"names":[],"mappings":""}