ultracode-shared 1.3.0

package/dist/logger.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Logging contract for UltraCode.
+ *
+ * Components receive a {@link Logger} via their context (e.g. {@link ToolContext})
+ * rather than reaching for a global. Two reference implementations are provided:
+ * {@link ConsoleLogger} (level-filtered, optionally silent) and {@link NoopLogger}
+ * (discards everything — ideal for tests and library embedding).
+ */
+/** Structured metadata attached to a log line. JSON-safe by convention. */
+export type LogMeta = Record<string, unknown>;
+/** Ordered log severities, lowest to highest. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Minimal structured logger. All methods are non-throwing and fire-and-forget;
+ * a logger MUST NOT propagate I/O errors to its callers.
+ */
+export interface Logger {
+    debug(msg: string, meta?: LogMeta): void;
+    info(msg: string, meta?: LogMeta): void;
+    warn(msg: string, meta?: LogMeta): void;
+    error(msg: string, meta?: LogMeta): void;
+}
+/** Sink abstraction so {@link ConsoleLogger} stays testable without stubbing globals. */
+export interface LogSink {
+    debug(msg: string, meta?: LogMeta): void;
+    info(msg: string, meta?: LogMeta): void;
+    warn(msg: string, meta?: LogMeta): void;
+    error(msg: string, meta?: LogMeta): void;
+}
+/** Options for {@link ConsoleLogger}. */
+export interface ConsoleLoggerOptions {
+    /** Minimum level to emit. Lines below this are dropped. Defaults to `"info"`. */
+    level?: LogLevel;
+    /** When `true`, suppresses all output regardless of level. Defaults to `false`. */
+    silent?: boolean;
+    /** Output sink. Defaults to the global `console`. */
+    sink?: LogSink;
+}
+/**
+ * Level-filtered logger writing to a {@link LogSink} (the global `console` by
+ * default). Honours a `silent` flag for fully suppressed output.
+ */
+export declare class ConsoleLogger implements Logger {
+    private level;
+    private silent;
+    private readonly sink;
+    constructor(options?: ConsoleLoggerOptions);
+    /** Change the minimum emitted level at runtime. */
+    setLevel(level: LogLevel): void;
+    /** Toggle silent mode at runtime. */
+    setSilent(silent: boolean): void;
+    private enabled;
+    debug(msg: string, meta?: LogMeta): void;
+    info(msg: string, meta?: LogMeta): void;
+    warn(msg: string, meta?: LogMeta): void;
+    error(msg: string, meta?: LogMeta): void;
+}
+/** A {@link Logger} that discards every message. */
+export declare class NoopLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,iDAAiD;AACjD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAUD,yFAAyF;AACzF,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;gBAEnB,OAAO,GAAE,oBAAyB;IAM9C,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B,qCAAqC;IACrC,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAIhC,OAAO,CAAC,OAAO;IAKf,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAIxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAIvC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAIvC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;CAGzC;AAED,oDAAoD;AACpD,qBAAa,UAAW,YAAW,MAAM;IACvC,KAAK,IAAI,IAAI;IAGb,IAAI,IAAI,IAAI;IAGZ,IAAI,IAAI,IAAI;IAGZ,KAAK,IAAI,IAAI;CAGd"}

package/dist/logger.js

@@ -0,0 +1,74 @@
+/**
+ * Logging contract for UltraCode.
+ *
+ * Components receive a {@link Logger} via their context (e.g. {@link ToolContext})
+ * rather than reaching for a global. Two reference implementations are provided:
+ * {@link ConsoleLogger} (level-filtered, optionally silent) and {@link NoopLogger}
+ * (discards everything — ideal for tests and library embedding).
+ */
+/** Numeric rank for each level; higher means more severe. */
+const LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+/**
+ * Level-filtered logger writing to a {@link LogSink} (the global `console` by
+ * default). Honours a `silent` flag for fully suppressed output.
+ */
+export class ConsoleLogger {
+    level;
+    silent;
+    sink;
+    constructor(options = {}) {
+        this.level = options.level ?? "info";
+        this.silent = options.silent ?? false;
+        this.sink = options.sink ?? console;
+    }
+    /** Change the minimum emitted level at runtime. */
+    setLevel(level) {
+        this.level = level;
+    }
+    /** Toggle silent mode at runtime. */
+    setSilent(silent) {
+        this.silent = silent;
+    }
+    enabled(level) {
+        if (this.silent)
+            return false;
+        return LEVEL_RANK[level] >= LEVEL_RANK[this.level];
+    }
+    debug(msg, meta) {
+        if (this.enabled("debug"))
+            this.sink.debug(msg, meta);
+    }
+    info(msg, meta) {
+        if (this.enabled("info"))
+            this.sink.info(msg, meta);
+    }
+    warn(msg, meta) {
+        if (this.enabled("warn"))
+            this.sink.warn(msg, meta);
+    }
+    error(msg, meta) {
+        if (this.enabled("error"))
+            this.sink.error(msg, meta);
+    }
+}
+/** A {@link Logger} that discards every message. */
+export class NoopLogger {
+    debug() {
+        /* intentionally empty */
+    }
+    info() {
+        /* intentionally empty */
+    }
+    warn() {
+        /* intentionally empty */
+    }
+    error() {
+        /* intentionally empty */
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,6DAA6D;AAC7D,MAAM,UAAU,GAAuC;IACrD,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAC;AAoBF;;;GAGG;AACH,MAAM,OAAO,aAAa;IAChB,KAAK,CAAW;IAChB,MAAM,CAAU;IACP,IAAI,CAAU;IAE/B,YAAY,UAAgC,EAAE;QAC5C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC;IACtC,CAAC;IAED,mDAAmD;IACnD,QAAQ,CAAC,KAAe;QACtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,qCAAqC;IACrC,SAAS,CAAC,MAAe;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAEO,OAAO,CAAC,KAAe;QAC7B,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC9B,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,IAAc;QAC/B,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,IAAc;QAC9B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,IAAc;QAC9B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,IAAc;QAC/B,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;CACF;AAED,oDAAoD;AACpD,MAAM,OAAO,UAAU;IACrB,KAAK;QACH,yBAAyB;IAC3B,CAAC;IACD,IAAI;QACF,yBAAyB;IAC3B,CAAC;IACD,IAAI;QACF,yBAAyB;IAC3B,CAAC;IACD,KAAK;QACH,yBAAyB;IAC3B,CAAC;CACF"}

package/dist/types/agent.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Agent contracts.
+ *
+ * An agent is a configured orchestration loop: it pairs a system prompt and a
+ * model/provider with a permitted tool set, and turns a user prompt into a
+ * final answer (driving the provider/tool loop internally).
+ */
+import type { ProviderId, TokenUsage } from "./provider.js";
+/** Lifecycle/role classification of an agent. */
+export type AgentType = "default" | "subagent" | "specialized" | "custom";
+/**
+ * Static definition of an agent. `enabledTools`/`disabledTools` are resolved
+ * against the global tool registry; `enabledTools` (when present) acts as an
+ * allow-list that overrides `disabledTools`.
+ */
+export interface AgentDefinition {
+    /** Unique agent name (e.g. `"build"`, `"review"`). */
+    name: string;
+    /** One-line description of the agent's purpose. */
+    description: string;
+    /** Agent classification. */
+    type: AgentType;
+    /** Model override; falls back to the active model when omitted. */
+    model?: string;
+    /** Provider override; falls back to the active provider when omitted. */
+    provider?: ProviderId;
+    /** Identifier of the system prompt to load (e.g. `"security"`). */
+    systemPromptId?: string;
+    /** Allow-list of tool names; overrides {@link AgentDefinition.disabledTools}. */
+    enabledTools?: string[];
+    /** Deny-list of tool names. */
+    disabledTools?: string[];
+}
+/** Input to a single agent run. */
+export interface AgentRunInput {
+    /** The user's prompt/instruction. */
+    prompt: string;
+    /** Existing session to continue; a new session is created when omitted. */
+    sessionId?: string;
+    /** Cancellation signal for the whole run. */
+    signal?: AbortSignal;
+}
+/** Aggregated outcome of an agent run. */
+export interface AgentRunResult {
+    /** Final assistant text presented to the user. */
+    text: string;
+    /** Number of tool executions performed across all turns. */
+    toolCallsExecuted: number;
+    /** Cumulative token usage across all model calls in the run. */
+    usage: TokenUsage;
+    /** Number of model turns taken. */
+    turns: number;
+}
+/**
+ * The implementable agent interface.
+ *
+ * Contract: `run` resolves with an {@link AgentRunResult} on success and
+ * rejects with an {@link import("../errors.js").AgentError} on unrecoverable
+ * failure. Cancellation via {@link AgentRunInput.signal} should reject with an
+ * abort-derived error.
+ */
+export interface IAgent {
+    /** Static definition of this agent. */
+    readonly definition: AgentDefinition;
+    /** Execute the agent against the given input. */
+    run(input: AgentRunInput): Promise<AgentRunResult>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/types/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE5D,iDAAiD;AACjD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,KAAK,EAAE,UAAU,CAAC;IAClB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,MAAM;IACrB,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,iDAAiD;IACjD,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACpD"}

package/dist/types/agent.js

@@ -0,0 +1,9 @@
+/**
+ * Agent contracts.
+ *
+ * An agent is a configured orchestration loop: it pairs a system prompt and a
+ * model/provider with a permitted tool set, and turns a user prompt into a
+ * final answer (driving the provider/tool loop internally).
+ */
+export {};
+//# sourceMappingURL=agent.js.map

package/dist/types/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/types/config.d.ts

@@ -0,0 +1,265 @@
+/**
+ * UltraCode configuration contract.
+ *
+ * Mirrors the TOML configuration documented in
+ * `docs/GETTING-STARTED/configuration.md` 1:1, but in camelCase (the loader is
+ * responsible for snake_case ↔ camelCase mapping). The full, resolved config is
+ * {@link UltraCodeConfig}; partial overlays (project/user layers) use
+ * {@link DeepPartial}. {@link DEFAULT_CONFIG} is the fully-populated baseline.
+ */
+import type { ProviderId } from "./provider.js";
+import type { ToolPermission } from "./tool.js";
+/**
+ * Recursively makes every property of `T` optional. Used for config overlays
+ * where each layer only specifies the keys it overrides. Arrays are treated as
+ * leaves (replaced wholesale, never deep-merged).
+ */
+export type DeepPartial<T> = T extends ReadonlyArray<unknown> ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/** `[core]` — global behaviour. */
+export interface CoreConfig {
+    /** Default agent for new sessions. */
+    defaultAgent: string;
+    /** Active model identifier. */
+    activeModel: string;
+    /** Active provider identifier. */
+    activeProvider: ProviderId;
+    /** Output language (e.g. `"de"`, `"en"`). */
+    language: string;
+    /** Max tokens per message. */
+    maxTokens: number;
+    /** Sampling temperature, `0.0`–`1.0`. */
+    temperature: number;
+    /** Debug mode. */
+    debug: boolean;
+    /** Send anonymised telemetry. */
+    enableTelemetry: boolean;
+    /** Check for updates on startup. */
+    enableUpdateChecks: boolean;
+}
+/** `[providers.proxy]` — outbound proxy settings. */
+export interface ProxyConfig {
+    /** Whether the proxy is active. */
+    enabled: boolean;
+    /** Proxy URL, when {@link ProxyConfig.enabled}. */
+    url?: string;
+}
+/** `[providers.local]` — local model backend (Ollama/LM Studio). */
+export interface LocalProviderConfig {
+    /** Whether local models are available. */
+    enabled: boolean;
+    /** Base endpoint of the local LLM server. */
+    endpoint: string;
+    /** Known local model identifiers. */
+    models: string[];
+}
+/** `[providers]` — provider-wide defaults. Keys/secrets live in `.env`, not here. */
+export interface ProvidersConfig {
+    /** Default provider identifier. */
+    default: ProviderId;
+    /** API timeout in **seconds** (TOML unit, as documented). */
+    timeout: number;
+    /** Maximum retry attempts. */
+    maxRetries: number;
+    /** Base retry delay in **seconds**. */
+    retryDelay: number;
+    /** Outbound proxy configuration. */
+    proxy: ProxyConfig;
+    /** Local backend configuration. */
+    local: LocalProviderConfig;
+}
+/** `[tools.<name>]` — per-tool overrides. Extra keys are permitted and preserved. */
+export interface PerToolConfig {
+    /** Permission override for this tool. */
+    permission?: ToolPermission;
+    /** Execution timeout in **seconds**. */
+    timeout?: number;
+    /** Tool-specific allow-listed directories. */
+    allowedDirs?: string[];
+    /** Extensions this tool must never overwrite. */
+    protectedExtensions?: string[];
+    /** Cap on returned matches (search tools). */
+    maxMatches?: number;
+    /** Max concurrent subagents (`task` tool). */
+    maxConcurrent?: number;
+    /** Open-ended escape hatch for additional, tool-specific keys. */
+    [key: string]: unknown;
+}
+/** `[tools]` — tool enablement and per-tool config. */
+export interface ToolsConfig {
+    /** Tools disabled by default. */
+    disabled: string[];
+    /** Tools force-enabled (overrides {@link ToolsConfig.disabled}). */
+    enabled: string[];
+    /** Per-tool settings keyed by tool name. */
+    perTool: Record<string, PerToolConfig>;
+}
+/** `[agents.<name>]` — a single agent override entry. */
+export interface AgentConfigEntry {
+    /** Model override. */
+    activeModel?: string;
+    /** Provider override. */
+    activeProvider?: ProviderId;
+    /** System prompt identifier. */
+    systemPromptId?: string;
+    /** Allow-listed tools. */
+    enabledTools?: string[];
+    /** Deny-listed tools. */
+    disabledTools?: string[];
+}
+/** `[agents]` — default agent plus per-agent overrides. */
+export interface AgentsConfig {
+    /** Default agent name. */
+    default: string;
+    /** Per-agent overrides keyed by agent name. */
+    agents: Record<string, AgentConfigEntry>;
+}
+/** `[ui.colors]` — custom theme palette (used when `theme = "custom"`). */
+export interface UiColors {
+    primary?: string;
+    secondary?: string;
+    background?: string;
+    text?: string;
+    error?: string;
+}
+/** `[ui]` — presentation. */
+export interface UiConfig {
+    /** Theme name (`dark`, `light`, `dracula`, …, or `custom`). */
+    theme: string;
+    /** Palette overrides for `theme = "custom"`. */
+    colors: UiColors;
+}
+/** `[session.compaction]` — long-conversation summarisation. */
+export interface SessionCompactionConfig {
+    /** Whether compaction is enabled. */
+    enabled: boolean;
+    /** Message-count threshold that triggers compaction. */
+    threshold: number;
+    /** Model used to produce the summary. */
+    model: string;
+}
+/** `[sessions]` — persistence and lifecycle. */
+export interface SessionsConfig {
+    /** Persist sessions to disk. */
+    enablePersistence: boolean;
+    /** Directory for saved sessions (`~` allowed). */
+    saveDir: string;
+    /** Idle timeout in **minutes** (`0` = never). */
+    timeout: number;
+    /** Maximum retained sessions. */
+    maxSessions: number;
+    /** Compaction settings. */
+    compaction: SessionCompactionConfig;
+}
+/** `[git.commit]` — commit-message generation. */
+export interface GitCommitConfig {
+    /** Whether AI commit messages are generated. */
+    enabled: boolean;
+    /** Model for commit-message generation. */
+    model: string;
+    /** Message template (e.g. `"conventional"`). */
+    template: string;
+}
+/** `[git.protection]` — protected-branch guard rails. */
+export interface GitProtectionConfig {
+    /** Branches on which mutating tools are restricted. */
+    protectedBranches: string[];
+    /** Tools blocked on protected branches. */
+    blockedTools: string[];
+}
+/** `[git]` — Git integration. */
+export interface GitConfig {
+    /** Show git status automatically. */
+    autoStatus: boolean;
+    /** Auto-commit before running tools. */
+    autoCommit: boolean;
+    /** Commit-message generation settings. */
+    commit: GitCommitConfig;
+    /** Branch protection settings. */
+    protection: GitProtectionConfig;
+}
+/** `[versioning.semantic]` — SemVer behaviour. */
+export interface VersioningSemanticConfig {
+    /** Automatically suggest the next version. */
+    autoSuggest: boolean;
+    /** Version tag prefix (e.g. `"v"`). */
+    prefix: string;
+}
+/** `[versioning.channels]` — channel → current version mapping. */
+export interface VersioningChannelsConfig {
+    stable: string;
+    lts: string;
+    experimental: string;
+    /** Additional custom channels. */
+    [channel: string]: string;
+}
+/** `[versioning.quality]` — release quality gates. */
+export interface VersioningQualityConfig {
+    /** Minimum test coverage percentage required for release. */
+    minCoverage: number;
+    /** Whether code review is mandatory before release. */
+    requireReview: boolean;
+}
+/** `[versioning.changelog]` — changelog generation. */
+export interface VersioningChangelogConfig {
+    /** Whether changelog generation is enabled. */
+    enabled: boolean;
+    /** Target changelog file. */
+    file: string;
+    /** Model used to draft the changelog. */
+    model: string;
+}
+/** `[versioning]` — the AI versioning system. */
+export interface VersioningConfig {
+    /** Master switch. */
+    enabled: boolean;
+    /** Strategy: `"semantic"`, `"date"`, or `"custom"`. */
+    strategy: "semantic" | "date" | "custom";
+    /** Semantic versioning settings. */
+    semantic: VersioningSemanticConfig;
+    /** Channel → version map. */
+    channels: VersioningChannelsConfig;
+    /** Quality gate thresholds. */
+    quality: VersioningQualityConfig;
+    /** Changelog settings. */
+    changelog: VersioningChangelogConfig;
+}
+/** Transport for an MCP server. */
+export type McpTransport = "http" | "stdio";
+/** `[[mcp_servers]]` — a single MCP server registration. */
+export interface McpServerConfig {
+    /** Unique server name; used to namespace its tools. */
+    name: string;
+    /** Transport type. */
+    transport: McpTransport;
+    /** For `transport: "http"`: server URL. */
+    url?: string;
+    /** For `transport: "stdio"`: executable to launch. */
+    command?: string;
+    /** For `transport: "stdio"`: arguments to {@link McpServerConfig.command}. */
+    args?: string[];
+    /** Environment variable holding the server's API key. */
+    apiKeyEnv?: string;
+}
+/** The fully-resolved UltraCode configuration. */
+export interface UltraCodeConfig {
+    core: CoreConfig;
+    providers: ProvidersConfig;
+    tools: ToolsConfig;
+    agents: AgentsConfig;
+    ui: UiConfig;
+    sessions: SessionsConfig;
+    git: GitConfig;
+    versioning: VersioningConfig;
+    /** Registered MCP servers. */
+    mcpServers: McpServerConfig[];
+}
+/**
+ * The embedded baseline configuration. Every key is populated so that a missing
+ * user/project config still yields a valid, runnable {@link UltraCodeConfig}.
+ * Defaults follow the documented reference table (note: `language` defaults to
+ * `"en"`, `theme` to `"dark"`).
+ */
+export declare const DEFAULT_CONFIG: UltraCodeConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

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

package/dist/types/config.js

@@ -0,0 +1,103 @@
+/**
+ * UltraCode configuration contract.
+ *
+ * Mirrors the TOML configuration documented in
+ * `docs/GETTING-STARTED/configuration.md` 1:1, but in camelCase (the loader is
+ * responsible for snake_case ↔ camelCase mapping). The full, resolved config is
+ * {@link UltraCodeConfig}; partial overlays (project/user layers) use
+ * {@link DeepPartial}. {@link DEFAULT_CONFIG} is the fully-populated baseline.
+ */
+/**
+ * The embedded baseline configuration. Every key is populated so that a missing
+ * user/project config still yields a valid, runnable {@link UltraCodeConfig}.
+ * Defaults follow the documented reference table (note: `language` defaults to
+ * `"en"`, `theme` to `"dark"`).
+ */
+export const DEFAULT_CONFIG = {
+    core: {
+        defaultAgent: "default",
+        activeModel: "mistral-large",
+        activeProvider: "mistral",
+        language: "en",
+        maxTokens: 32000,
+        temperature: 0.7,
+        debug: false,
+        enableTelemetry: true,
+        enableUpdateChecks: true,
+    },
+    providers: {
+        default: "mistral",
+        timeout: 60,
+        maxRetries: 3,
+        retryDelay: 1,
+        proxy: {
+            enabled: false,
+        },
+        local: {
+            enabled: false,
+            endpoint: "http://localhost:11434",
+            models: [],
+        },
+    },
+    tools: {
+        disabled: [],
+        enabled: [],
+        perTool: {},
+    },
+    agents: {
+        default: "default",
+        agents: {},
+    },
+    ui: {
+        theme: "dark",
+        colors: {},
+    },
+    sessions: {
+        enablePersistence: true,
+        saveDir: "~/.ultracode/sessions",
+        timeout: 60,
+        maxSessions: 50,
+        compaction: {
+            enabled: true,
+            threshold: 50,
+            model: "mistral-medium",
+        },
+    },
+    git: {
+        autoStatus: true,
+        autoCommit: false,
+        commit: {
+            enabled: true,
+            model: "mistral-medium",
+            template: "conventional",
+        },
+        protection: {
+            protectedBranches: ["main", "master", "develop"],
+            blockedTools: [],
+        },
+    },
+    versioning: {
+        enabled: true,
+        strategy: "semantic",
+        semantic: {
+            autoSuggest: true,
+            prefix: "v",
+        },
+        channels: {
+            stable: "0.0.0",
+            lts: "0.0.0",
+            experimental: "0.0.0",
+        },
+        quality: {
+            minCoverage: 80,
+            requireReview: true,
+        },
+        changelog: {
+            enabled: true,
+            file: "CHANGELOG.md",
+            model: "mistral-medium",
+        },
+    },
+    mcpServers: [],
+};
+//# sourceMappingURL=config.js.map

package/dist/types/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqRH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAoB;IAC7C,IAAI,EAAE;QACJ,YAAY,EAAE,SAAS;QACvB,WAAW,EAAE,eAAe;QAC5B,cAAc,EAAE,SAAS;QACzB,QAAQ,EAAE,IAAI;QACd,SAAS,EAAE,KAAK;QAChB,WAAW,EAAE,GAAG;QAChB,KAAK,EAAE,KAAK;QACZ,eAAe,EAAE,IAAI;QACrB,kBAAkB,EAAE,IAAI;KACzB;IACD,SAAS,EAAE;QACT,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,CAAC;QACb,UAAU,EAAE,CAAC;QACb,KAAK,EAAE;YACL,OAAO,EAAE,KAAK;SACf;QACD,KAAK,EAAE;YACL,OAAO,EAAE,KAAK;YACd,QAAQ,EAAE,wBAAwB;YAClC,MAAM,EAAE,EAAE;SACX;KACF;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,EAAE;KACZ;IACD,MAAM,EAAE;QACN,OAAO,EAAE,SAAS;QAClB,MAAM,EAAE,EAAE;KACX;IACD,EAAE,EAAE;QACF,KAAK,EAAE,MAAM;QACb,MAAM,EAAE,EAAE;KACX;IACD,QAAQ,EAAE;QACR,iBAAiB,EAAE,IAAI;QACvB,OAAO,EAAE,uBAAuB;QAChC,OAAO,EAAE,EAAE;QACX,WAAW,EAAE,EAAE;QACf,UAAU,EAAE;YACV,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,EAAE;YACb,KAAK,EAAE,gBAAgB;SACxB;KACF;IACD,GAAG,EAAE;QACH,UAAU,EAAE,IAAI;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;YACN,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,gBAAgB;YACvB,QAAQ,EAAE,cAAc;SACzB;QACD,UAAU,EAAE;YACV,iBAAiB,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC;YAChD,YAAY,EAAE,EAAE;SACjB;KACF;IACD,UAAU,EAAE;QACV,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,UAAU;QACpB,QAAQ,EAAE;YACR,WAAW,EAAE,IAAI;YACjB,MAAM,EAAE,GAAG;SACZ;QACD,QAAQ,EAAE;YACR,MAAM,EAAE,OAAO;YACf,GAAG,EAAE,OAAO;YACZ,YAAY,EAAE,OAAO;SACtB;QACD,OAAO,EAAE;YACP,WAAW,EAAE,EAAE;YACf,aAAa,EAAE,IAAI;SACpB;QACD,SAAS,EAAE;YACT,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,cAAc;YACpB,KAAK,EAAE,gBAAgB;SACxB;KACF;IACD,UAAU,EAAE,EAAE;CACf,CAAC"}