sequant 2.1.1 → 2.1.2

package/dist/src/commands/status.js

@@ -9,6 +9,7 @@ import { readdir } from "fs/promises";
 import { StateManager } from "../lib/workflow/state-manager.js";
 import { rebuildStateFromLogs, cleanupStaleEntries, } from "../lib/workflow/state-utils.js";
 import { reconcileState, getNextActionHint, formatRelativeTime, } from "../lib/workflow/reconcile.js";
+import { getSettingsWithWarnings } from "../lib/settings.js";
 /**
  * Run reconciliation and display warnings.
  * Returns the reconcile result for use in display.
@@ -254,6 +255,14 @@ export async function statusCommand(options = {}) {
     if (manifest.updatedAt) {
         console.log(chalk.gray(`Last updated: ${manifest.updatedAt}`));
     }
+    // Show settings validation warnings (AC-3)
+    const { warnings: settingsWarnings } = await getSettingsWithWarnings();
+    if (settingsWarnings.length > 0) {
+        console.log(chalk.yellow("\n  Settings Warnings:"));
+        for (const w of settingsWarnings) {
+            console.log(chalk.yellow(`    ${w.message}`));
+        }
+    }
     // Count skills
     const skillsDir = ".claude/skills";
     if (await fileExists(skillsDir)) {

package/dist/src/index.d.ts

@@ -30,3 +30,14 @@ export { mergePhaseSignals, signalFromLabel, signalsFromLabels, formatMergedPhas
 export type { SignalSource, SignalConfidence, PhaseSignal, MergedPhaseResult, } from "./lib/phase-signal.js";
 export { isAssessComment, findAssessComment, parseAssessMarkers, parseAssessWorkflow, assessWorkflowToSignals, assessCoversIssue, isSolveComment, findSolveComment, parseSolveMarkers, parseSolveWorkflow, solveWorkflowToSignals, solveCoversIssue, } from "./lib/assess-comment-parser.js";
 export type { AssessWorkflowResult, AssessMarkers, AssessAction, SolveWorkflowResult, SolveMarkers, IssueComment, } from "./lib/assess-comment-parser.js";
+export { SettingsSchema, validateSettings, getSettingsWithWarnings, generateSettingsReference, generateSettingsJsonc, stripJsoncComments, } from "./lib/settings.js";
+export type { SequantSettings, RunSettings, AgentSettings, ValidationResult, SettingsWarning, } from "./lib/settings.js";
+export { SequantError, ContextOverflowError, ApiError, HookFailureError, BuildError, TimeoutError, SubprocessError, ERROR_TYPE_MAP, } from "./lib/errors.js";
+export type { ContextOverflowMetadata, ApiErrorMetadata, HookFailureMetadata, BuildErrorMetadata, TimeoutErrorMetadata, SubprocessErrorMetadata, } from "./lib/errors.js";
+export { classifyError, errorTypeToCategory, ERROR_CATEGORIES, } from "./lib/workflow/error-classifier.js";
+export type { ErrorCategory } from "./lib/workflow/error-classifier.js";
+export { RunOrchestrator } from "./lib/workflow/run-orchestrator.js";
+export type { OrchestratorConfig, OrchestratorServices, RunInit, RunResult, } from "./lib/workflow/run-orchestrator.js";
+export { ConfigResolver, resolveRunOptions, buildExecutionConfig, normalizeCommanderOptions, } from "./lib/workflow/config-resolver.js";
+export type { ConfigLayers } from "./lib/workflow/config-resolver.js";
+export type { ExecutionConfig, RunOptions, IssueResult, PhaseResult, ProgressCallback, } from "./lib/workflow/types.js";

package/dist/src/index.js

@@ -25,3 +25,12 @@ export { mergePhaseSignals, signalFromLabel, signalsFromLabels, formatMergedPhas
 export { isAssessComment, findAssessComment, parseAssessMarkers, parseAssessWorkflow, assessWorkflowToSignals, assessCoversIssue, 
 // Backward-compatible aliases (deprecated)
 isSolveComment, findSolveComment, parseSolveMarkers, parseSolveWorkflow, solveWorkflowToSignals, solveCoversIssue, } from "./lib/assess-comment-parser.js";
+// Settings schema exports (AC-5)
+export { SettingsSchema, validateSettings, getSettingsWithWarnings, generateSettingsReference, generateSettingsJsonc, stripJsoncComments, } from "./lib/settings.js";
+// Structured error types (AC-10)
+export { SequantError, ContextOverflowError, ApiError, HookFailureError, BuildError, TimeoutError, SubprocessError, ERROR_TYPE_MAP, } from "./lib/errors.js";
+// Error classifier (AC-7)
+export { classifyError, errorTypeToCategory, ERROR_CATEGORIES, } from "./lib/workflow/error-classifier.js";
+// Run orchestrator exports (AC-4: importable without CLI context)
+export { RunOrchestrator } from "./lib/workflow/run-orchestrator.js";
+export { ConfigResolver, resolveRunOptions, buildExecutionConfig, normalizeCommanderOptions, } from "./lib/workflow/config-resolver.js";

package/dist/src/lib/errors.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Structured error types for Sequant workflow failures (AC-6, AC-10).
+ *
+ * Provides typed error subclasses with metadata instead of string categories,
+ * enabling `instanceof` checks and `isRetryable` property for retry decisions.
+ */
+/**
+ * Base error class for all Sequant errors.
+ *
+ * Subclasses set `isRetryable` to indicate whether the error is generally
+ * recoverable. The executor still decides based on config + attempt count.
+ */
+export declare class SequantError extends Error {
+    /** Whether this error type is generally retryable */
+    readonly isRetryable: boolean;
+    /** Structured metadata for diagnostics */
+    readonly metadata: Record<string, unknown>;
+    constructor(message: string, options?: {
+        isRetryable?: boolean;
+        metadata?: Record<string, unknown>;
+        cause?: Error;
+    });
+    /** Serialize to a plain object for JSON logging */
+    toJSON(): Record<string, unknown>;
+}
+export interface ContextOverflowMetadata {
+    [key: string]: unknown;
+    maxTokens?: number;
+    usedTokens?: number;
+}
+/** Token/context limit exceeded */
+export declare class ContextOverflowError extends SequantError {
+    readonly metadata: ContextOverflowMetadata;
+    constructor(message: string, metadata?: ContextOverflowMetadata, cause?: Error);
+}
+export interface ApiErrorMetadata {
+    [key: string]: unknown;
+    statusCode?: number;
+    endpoint?: string;
+}
+/** Rate limits, 503, auth failures (with HTTP status code if available) */
+export declare class ApiError extends SequantError {
+    readonly metadata: ApiErrorMetadata;
+    constructor(message: string, metadata?: ApiErrorMetadata, cause?: Error);
+}
+export interface HookFailureMetadata {
+    [key: string]: unknown;
+    hook?: string;
+    reason?: string;
+}
+/** Pre-commit hook failure (with hook name) */
+export declare class HookFailureError extends SequantError {
+    readonly metadata: HookFailureMetadata;
+    constructor(message: string, metadata?: HookFailureMetadata, cause?: Error);
+}
+export interface BuildErrorMetadata {
+    [key: string]: unknown;
+    toolchain?: string;
+    errorCode?: string;
+    file?: string;
+    line?: number;
+}
+/** TypeScript, ESLint, npm errors (with file/line if parseable) */
+export declare class BuildError extends SequantError {
+    readonly metadata: BuildErrorMetadata;
+    constructor(message: string, metadata?: BuildErrorMetadata, cause?: Error);
+}
+export interface TimeoutErrorMetadata {
+    [key: string]: unknown;
+    timeoutMs?: number;
+    phase?: string;
+}
+/** Phase exceeded time limit (with configured timeout value) */
+export declare class TimeoutError extends SequantError {
+    readonly metadata: TimeoutErrorMetadata;
+    constructor(message: string, metadata?: TimeoutErrorMetadata, cause?: Error);
+}
+export interface SubprocessErrorMetadata {
+    [key: string]: unknown;
+    command?: string;
+    exitCode?: number;
+    stderr?: string;
+}
+/** git/gh command failed (with command, exit code, stderr) */
+export declare class SubprocessError extends SequantError {
+    readonly metadata: SubprocessErrorMetadata;
+    constructor(message: string, metadata?: SubprocessErrorMetadata, cause?: Error);
+}
+/**
+ * Map of error type names to their constructors.
+ * Used for deserialization from logs.
+ */
+export declare const ERROR_TYPE_MAP: Record<string, new (message: string, metadata?: Record<string, unknown>, cause?: Error) => SequantError>;

package/dist/src/lib/errors.js

@@ -0,0 +1,97 @@
+/**
+ * Structured error types for Sequant workflow failures (AC-6, AC-10).
+ *
+ * Provides typed error subclasses with metadata instead of string categories,
+ * enabling `instanceof` checks and `isRetryable` property for retry decisions.
+ */
+/**
+ * Base error class for all Sequant errors.
+ *
+ * Subclasses set `isRetryable` to indicate whether the error is generally
+ * recoverable. The executor still decides based on config + attempt count.
+ */
+export class SequantError extends Error {
+    /** Whether this error type is generally retryable */
+    isRetryable;
+    /** Structured metadata for diagnostics */
+    metadata;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.name = "SequantError";
+        this.isRetryable = options?.isRetryable ?? false;
+        this.metadata = options?.metadata ?? {};
+    }
+    /** Serialize to a plain object for JSON logging */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            isRetryable: this.isRetryable,
+            metadata: this.metadata,
+            stack: this.stack,
+        };
+    }
+}
+/** Token/context limit exceeded */
+export class ContextOverflowError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        super(message, { isRetryable: true, metadata, cause });
+        this.name = "ContextOverflowError";
+    }
+}
+/** Rate limits, 503, auth failures (with HTTP status code if available) */
+export class ApiError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        // Retryable for transient errors (429, 502, 503), not for auth (401, 403)
+        const retryableStatuses = new Set([429, 502, 503]);
+        const isRetryable = metadata.statusCode
+            ? retryableStatuses.has(metadata.statusCode)
+            : false;
+        super(message, { isRetryable, metadata, cause });
+        this.name = "ApiError";
+    }
+}
+/** Pre-commit hook failure (with hook name) */
+export class HookFailureError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        super(message, { isRetryable: false, metadata, cause });
+        this.name = "HookFailureError";
+    }
+}
+/** TypeScript, ESLint, npm errors (with file/line if parseable) */
+export class BuildError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        super(message, { isRetryable: false, metadata, cause });
+        this.name = "BuildError";
+    }
+}
+/** Phase exceeded time limit (with configured timeout value) */
+export class TimeoutError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        super(message, { isRetryable: false, metadata, cause });
+        this.name = "TimeoutError";
+    }
+}
+/** git/gh command failed (with command, exit code, stderr) */
+export class SubprocessError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        // Signal-based exits (128+signal) are generally retryable (e.g., 143 = SIGTERM)
+        const exitCode = metadata.exitCode;
+        const isRetryable = exitCode !== undefined && exitCode >= 128 && exitCode <= 192;
+        super(message, { isRetryable, metadata, cause });
+        this.name = "SubprocessError";
+    }
+}
+/**
+ * Map of error type names to their constructors.
+ * Used for deserialization from logs.
+ */
+export const ERROR_TYPE_MAP = {
+    SequantError: SequantError,
+    ContextOverflowError: ContextOverflowError,
+    ApiError: ApiError,
+    HookFailureError: HookFailureError,
+    BuildError: BuildError,
+    TimeoutError: TimeoutError,
+    SubprocessError: SubprocessError,
+};

package/dist/src/lib/settings.d.ts

@@ -10,6 +10,7 @@
  * 3. Project-level (.sequant/settings.json)
  * 4. CLI flags (highest priority)
  */
+import { z } from "zod";
 /** Path to project-level settings file */
 export declare const SETTINGS_PATH = ".sequant/settings.json";
 /** Current settings schema version */
@@ -124,6 +125,16 @@ export interface RunSettings {
      * - -1: Prune immediately (resolved issues never shown)
      */
     resolvedIssueTTL: number;
+    /**
+     * Package manager run command (e.g., "npm run", "yarn", "pnpm run").
+     * Set during `sequant init` based on detected package manager.
+     */
+    pmRun?: string;
+    /**
+     * Development server URL (e.g., "http://localhost:3000").
+     * Set during `sequant init` based on detected stack.
+     */
+    devUrl?: string;
     /**
      * Agent driver for phase execution.
      * Default: "claude-code". Set to "aider" to use Aider CLI.
@@ -215,6 +226,201 @@ export interface SequantSettings {
     /** QA skill settings */
     qa: QASettings;
 }
+/** Zod schema for RotationSettings */
+export declare const RotationSettingsSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    maxSizeMB: z.ZodDefault<z.ZodNumber>;
+    maxFiles: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** Zod schema for AiderSettings */
+export declare const AiderSettingsSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    editFormat: z.ZodOptional<z.ZodString>;
+    extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Zod schema for AgentSettings */
+export declare const AgentSettingsSchema: z.ZodObject<{
+    parallel: z.ZodDefault<z.ZodBoolean>;
+    model: z.ZodDefault<z.ZodEnum<{
+        haiku: "haiku";
+        sonnet: "sonnet";
+        opus: "opus";
+    }>>;
+    isolateParallel: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Zod schema for RunSettings */
+export declare const RunSettingsSchema: z.ZodObject<{
+    logJson: z.ZodDefault<z.ZodBoolean>;
+    logPath: z.ZodDefault<z.ZodString>;
+    autoDetectPhases: z.ZodDefault<z.ZodBoolean>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    sequential: z.ZodDefault<z.ZodBoolean>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    qualityLoop: z.ZodDefault<z.ZodBoolean>;
+    maxIterations: z.ZodDefault<z.ZodNumber>;
+    smartTests: z.ZodDefault<z.ZodBoolean>;
+    rotation: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        maxSizeMB: z.ZodDefault<z.ZodNumber>;
+        maxFiles: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    defaultBase: z.ZodOptional<z.ZodString>;
+    mcp: z.ZodDefault<z.ZodBoolean>;
+    retry: z.ZodDefault<z.ZodBoolean>;
+    staleBranchThreshold: z.ZodDefault<z.ZodNumber>;
+    resolvedIssueTTL: z.ZodDefault<z.ZodNumber>;
+    pmRun: z.ZodOptional<z.ZodString>;
+    devUrl: z.ZodOptional<z.ZodString>;
+    agent: z.ZodOptional<z.ZodString>;
+    aider: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        editFormat: z.ZodOptional<z.ZodString>;
+        extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Zod schema for ScopeThreshold (base — fields required, no defaults) */
+export declare const ScopeThresholdSchema: z.ZodObject<{
+    yellow: z.ZodNumber;
+    red: z.ZodNumber;
+}, z.core.$strip>;
+/** Zod schema for TrivialThresholds */
+export declare const TrivialThresholdsSchema: z.ZodObject<{
+    maxACItems: z.ZodDefault<z.ZodNumber>;
+    maxDirectories: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** Zod schema for ScopeAssessmentSettings */
+export declare const ScopeAssessmentSettingsSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    skipIfSimple: z.ZodDefault<z.ZodBoolean>;
+    trivialThresholds: z.ZodDefault<z.ZodObject<{
+        maxACItems: z.ZodDefault<z.ZodNumber>;
+        maxDirectories: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    thresholds: z.ZodDefault<z.ZodObject<{
+        featureCount: z.ZodDefault<z.ZodObject<{
+            yellow: z.ZodDefault<z.ZodNumber>;
+            red: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        acItems: z.ZodDefault<z.ZodObject<{
+            yellow: z.ZodDefault<z.ZodNumber>;
+            red: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        fileEstimate: z.ZodDefault<z.ZodObject<{
+            yellow: z.ZodDefault<z.ZodNumber>;
+            red: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        directorySpread: z.ZodDefault<z.ZodObject<{
+            yellow: z.ZodDefault<z.ZodNumber>;
+            red: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Zod schema for QASettings */
+export declare const QASettingsSchema: z.ZodObject<{
+    smallDiffThreshold: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Zod schema for the full SequantSettings (AC-1, AC-5).
+ *
+ * Top-level uses `.passthrough()` to allow forward-compatible fields from
+ * newer Sequant versions. Unknown keys are preserved in parse output and
+ * reported as warnings via `validateSettings()`.
+ *
+ * Nested schemas don't use `.passthrough()` because unknown key detection
+ * is handled by `detectUnknownKeys()` at validation time.
+ */
+export declare const SettingsSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodString>;
+    run: z.ZodDefault<z.ZodObject<{
+        logJson: z.ZodDefault<z.ZodBoolean>;
+        logPath: z.ZodDefault<z.ZodString>;
+        autoDetectPhases: z.ZodDefault<z.ZodBoolean>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+        sequential: z.ZodDefault<z.ZodBoolean>;
+        concurrency: z.ZodDefault<z.ZodNumber>;
+        qualityLoop: z.ZodDefault<z.ZodBoolean>;
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+        smartTests: z.ZodDefault<z.ZodBoolean>;
+        rotation: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            maxSizeMB: z.ZodDefault<z.ZodNumber>;
+            maxFiles: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        defaultBase: z.ZodOptional<z.ZodString>;
+        mcp: z.ZodDefault<z.ZodBoolean>;
+        retry: z.ZodDefault<z.ZodBoolean>;
+        staleBranchThreshold: z.ZodDefault<z.ZodNumber>;
+        resolvedIssueTTL: z.ZodDefault<z.ZodNumber>;
+        pmRun: z.ZodOptional<z.ZodString>;
+        devUrl: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        aider: z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            editFormat: z.ZodOptional<z.ZodString>;
+            extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    agents: z.ZodDefault<z.ZodObject<{
+        parallel: z.ZodDefault<z.ZodBoolean>;
+        model: z.ZodDefault<z.ZodEnum<{
+            haiku: "haiku";
+            sonnet: "sonnet";
+            opus: "opus";
+        }>>;
+        isolateParallel: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    scopeAssessment: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        skipIfSimple: z.ZodDefault<z.ZodBoolean>;
+        trivialThresholds: z.ZodDefault<z.ZodObject<{
+            maxACItems: z.ZodDefault<z.ZodNumber>;
+            maxDirectories: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        thresholds: z.ZodDefault<z.ZodObject<{
+            featureCount: z.ZodDefault<z.ZodObject<{
+                yellow: z.ZodDefault<z.ZodNumber>;
+                red: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+            acItems: z.ZodDefault<z.ZodObject<{
+                yellow: z.ZodDefault<z.ZodNumber>;
+                red: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+            fileEstimate: z.ZodDefault<z.ZodObject<{
+                yellow: z.ZodDefault<z.ZodNumber>;
+                red: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+            directorySpread: z.ZodDefault<z.ZodObject<{
+                yellow: z.ZodDefault<z.ZodNumber>;
+                red: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    qa: z.ZodDefault<z.ZodObject<{
+        smallDiffThreshold: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+/** A single validation warning about an unknown or invalid setting */
+export interface SettingsWarning {
+    /** Dot-separated path to the problematic key, e.g. "run.timoeut" */
+    path: string;
+    /** Human-readable message */
+    message: string;
+}
+/** Result of settings validation */
+export interface ValidationResult {
+    /** The merged settings (always returned — invalid fields use defaults) */
+    settings: SequantSettings;
+    /** Validation warnings (unknown keys, type mismatches that were coerced) */
+    warnings: SettingsWarning[];
+}
+/**
+ * Validate a raw settings object against the Zod schema (AC-2).
+ *
+ * Returns validated settings (with defaults filled in) and any warnings.
+ * On type errors, falls back to defaults for the invalid fields and
+ * reports warnings — never throws.
+ */
+export declare function validateSettings(raw: unknown): ValidationResult;
 /**
  * Default rotation settings
  */
@@ -250,10 +456,18 @@ export declare const DEFAULT_SETTINGS: SequantSettings;
  * Throws on invalid types to catch config errors at load time.
  */
 export declare function validateAiderSettings(aider: unknown): AiderSettings | undefined;
+/**
+ * Get the current project settings with validation warnings (AC-2, AC-3).
+ *
+ * Returns settings merged with defaults and any validation warnings.
+ * Use this when you need to display warnings to the user (e.g., status command).
+ */
+export declare function getSettingsWithWarnings(): Promise<ValidationResult>;
 /**
  * Get the current project settings
  *
  * Returns default settings if no settings file exists.
+ * Validates against Zod schema (AC-2) — warnings are logged to stderr.
  */
 export declare function getSettings(): Promise<SequantSettings>;
 /**
@@ -267,4 +481,26 @@ export declare function settingsExist(): Promise<boolean>;
 /**
  * Create default settings file
  */
+/**
+ * Create default settings file with JSONC inline comments (AC-4).
+ *
+ * Generates a JSONC file (.json with // comments) documenting each field
+ * and its default value. The loadSettings path strips comments before parsing.
+ */
 export declare function createDefaultSettings(): Promise<void>;
+/**
+ * Generate JSONC content with inline comments for each settings field (AC-4).
+ */
+export declare function generateSettingsJsonc(settings: SequantSettings): string;
+/**
+ * Strip single-line // comments from JSONC content for JSON.parse compatibility.
+ * Handles comments on their own line and trailing comments after values.
+ * Preserves strings containing // (e.g., URLs).
+ */
+export declare function stripJsoncComments(content: string): string;
+/**
+ * Generate settings.reference.md companion document (AC-4).
+ *
+ * Supplements the inline JSONC comments with a structured Markdown reference.
+ */
+export declare function generateSettingsReference(): string;