@gaunt-sloth/core 2.0.0-alpha.3 → 2.0.0-alpha.30

package/dist/config/loader.d.ts

@@ -0,0 +1,246 @@
+import { type RawConfigValidationResult } from '#src/config/schema.js';
+import type { CommandLineConfigOverrides, ConsoleLevelInput, GthConfig, RawGthConfig } from '#src/config/types.js';
+/**
+ * Find THE project config by walking up from cwd toward a stop boundary, returning the FIRST
+ * match (first-match-win: nearest dir, then format precedence within that dir — NOT a merged
+ * stack). Detection ({@link hasProjectConfig}/{@link hasAnyConfig}) and loading ({@link initConfig})
+ * both go through this, so they can never disagree.
+ *
+ * Stop boundary — the dir is SEARCHED, then ascent stops at: a dir containing `.git` (the git
+ * root), the user's home dir, or the filesystem root — whichever comes first. So a config IN the
+ * git root (or home) is found; a config ABOVE it is not.
+ *
+ * A `customConfigPath` override wins outright (no walking).
+ *
+ * NOTE (identity profile): with an `identityProfile` set, each dir's per-format resolver
+ * ({@link resolveConfigPath}) tries the profile path `.gsloth/.gsloth-settings/<profile>/<file>`
+ * but FALLS BACK to the plain `<dir>/<file>` when the profile file is absent. So a match here does
+ * NOT prove the named profile itself has a config — it may be a plain (non-profile) config. Use
+ * {@link resolveIdentityProfileConfigPath} when you need to know a profile specifically resolved.
+ *
+ * @returns the matched `{ dir, path }`, or `undefined` when no project config exists within the
+ * boundary.
+ */
+export declare function findProjectConfigPath(commandLineConfigOverrides: CommandLineConfigOverrides): {
+    dir: string;
+    path: string;
+} | undefined;
+/**
+ * STRICT existence check for an EXPLICITLY-named identity profile: does
+ * `.gsloth/.gsloth-settings/<identityProfile>/<config>` resolve to a real config file anywhere in
+ * the same up-tree search {@link findProjectConfigPath} walks? Returns the resolved profile config
+ * path (nearest dir, then format precedence) when the profile has its OWN config, `undefined`
+ * otherwise.
+ *
+ * Unlike {@link findProjectConfigPath}, it matches ONLY the profile-specific path — it NEVER falls
+ * through to a plain `<dir>/<config>` and NEVER falls back to the global config. That strictness is
+ * the whole point: it lets a caller distinguish "this named profile really exists" from "a bare
+ * config happens to be present / a global config exists," a distinction the loader's fall-through
+ * deliberately blurs.
+ *
+ * PURE PREDICATE — never throws, never calls `exit` (contrast the loader's interactive-CLI
+ * `exit(1)` safety net in {@link initConfig}). So batch/eval code (e.g. `gth eval --judge <profile>`
+ * and BATCH-12's identity matrix) can pre-check an explicitly-requested profile and raise its OWN
+ * catchable error / graceful exit code instead of dying on an uncatchable `process.exit`. A
+ * blank/whitespace-only name counts as "no profile" → `undefined`.
+ *
+ * @param identityProfile The explicitly-requested identity profile name.
+ * @returns The resolved profile config path, or `undefined` when the profile has no config.
+ */
+export declare function resolveIdentityProfileConfigPath(identityProfile: string): string | undefined;
+/**
+ * Loads the global gsloth config (if present) from the global `~/.gsloth` folder.
+ *
+ * Precedence support: the returned raw config is intended to act as the BASE that the
+ * project config (and CLI overrides) merge on top of, so any value here is the lowest
+ * user-controlled layer (still above {@link DEFAULT_CONFIG}).
+ *
+ * Lookup order within the global folder, first match wins:
+ *   `.gsloth.config.json` -> `.gsloth.config.jsonc` -> `.gsloth.config.js` -> `.gsloth.config.mjs`
+ *
+ * Absence of every variant is a no-op: returns `undefined` so behaviour is unchanged.
+ *
+ * NOTE: secrets (API keys) may live in this file; this function must never log its
+ * contents. Only non-sensitive diagnostics (the resolved path / parse failure) are emitted.
+ *
+ * @returns The raw global config object, or `undefined` when no global config exists.
+ */
+export declare function loadGlobalRawConfig(): Promise<Partial<RawGthConfig> | undefined>;
+/**
+ * GS2-41 — resolve a named profile's `extends` inheritance into a single composed raw config,
+ * riding the SAME GS2-1 deep-merge the config LAYERS use (NO second merge engine). When the given
+ * profile config declares `extends: "<base>"`, the base profile's config resolves FIRST
+ * (recursively — a base may itself extend another, so base-of-base resolves first), then this
+ * profile's own fields merge on top with last-wins semantics: the child overrides the base, nested
+ * objects merge, arrays REPLACE except the additive-array fields (`allowDirs`, `aiignore.patterns`
+ * and the three `approvals` rule lists, see {@link isAdditiveArrayField}) which accumulate
+ * base+child. The `extends` key itself is consumed and never leaks into the composed output.
+ *
+ * A config WITHOUT `extends` is returned UNCHANGED — every non-inheriting config (the vast
+ * majority) is untouched and behaves exactly as before.
+ *
+ * Composition is CONFINED to the profile-dir layer: it produces the single raw config that then
+ * acts as the project-file layer the global config underlays and CLI flags overlay, preserving
+ * GS2-33's outer precedence `CLI flags > profile (base+child composed) > global > defaults`. It is
+ * therefore invoked in {@link initConfig} on the loaded project/profile config BEFORE
+ * {@link applyGlobalConfigBase}.
+ *
+ * The base profile is discovered with {@link resolveIdentityProfileConfigPath} (the SAME strict
+ * up-tree profile walk `--profile` uses), so `extends` names a profile exactly as a user selects
+ * one; a name with no config dir is a hard, clearly-named error.
+ *
+ * CYCLE GUARD: the chain of profile NAMES is tracked (seeded with the selected profile's own name);
+ * because `extends` is single-valued the chain is linear, so a repeated name — `A extends B extends
+ * A`, or a self-extend — is an unambiguous cycle and fails fast with a clear error NAMING the cycle,
+ * never infinite-looping / stack-overflowing. A hard {@link MAX_EXTENDS_CHAIN_DEPTH} cap backstops
+ * it regardless of how the base path was derived.
+ *
+ * @param rawConfig   the just-loaded, schema-validated raw config that MAY declare `extends`.
+ * @param profileLabel the selected profile's own name (for cycle detection + messages); undefined
+ *                     for a plain (non-profile) project config.
+ */
+export declare function resolveConfigExtends(rawConfig: Record<string, unknown>, profileLabel: string | undefined): Promise<Record<string, unknown>>;
+/**
+ * ORDERING INVARIANT (GS2-11): detection ({@link hasProjectConfig}/{@link hasAnyConfig}) MUST run
+ * before {@link initConfig} in a given process. Both resolve cwd-level candidates via
+ * `getGslothConfigReadPath`, which reads `getProjectDir()`; {@link initConfig} clears `projectDir`
+ * at the start of its run, so detection stays cwd-correct as long as it precedes initConfig (it
+ * does: startSession calls hasAnyConfig before any initConfig, and the ACP/agent path calls
+ * initConfig directly without detection). Calling detection AFTER an initConfig with a changed cwd
+ * in a long-lived process would read a stale projectDir (currently unreachable). If that call
+ * order is ever introduced, decouple discovery's cwd-branch from `getProjectDir()`.
+ */
+/**
+ * Returns true when a project-level config file (json/jsonc/js/mjs) exists for the given
+ * overrides. Honours `customConfigPath` and the active identity profile so the check
+ * matches exactly what {@link initConfig} would attempt to load.
+ *
+ * This is the project half of CFG-10's "is any config present?" detection; the global
+ * half is {@link loadGlobalRawConfig} (used by {@link hasAnyConfig}).
+ */
+export declare function hasProjectConfig(commandLineConfigOverrides: CommandLineConfigOverrides): boolean;
+/**
+ * CFG-10 — true when ANY usable configuration is present, either a project config file
+ * (json/jsonc/js/mjs) or a standalone global config (`~/.gsloth/.gsloth.config.*`). When this
+ * returns false the caller should run the first-run dialog instead of erroring.
+ *
+ * Reuses CFG-8's project + global detection so the two paths can never disagree.
+ */
+export declare function hasAnyConfig(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<boolean>;
+/**
+ * CFG-37 — the layered value of the top-level `tui` config key, read BEFORE a session picks its
+ * surface. `chat`/`code` choose between the Ink TUI and the readline session in the app's
+ * `startSession` dispatcher, and each surface then loads its own config via {@link initConfig} — so
+ * at the moment of the choice there is no resolved {@link GthConfig} to consult, and this is the
+ * seam that supplies the one key the choice needs.
+ *
+ * Layering matches a run: the discovered PROJECT layer wins over the GLOBAL one, and a layer that
+ * does not set `tui` defers to the next rather than overriding it with `undefined`. A scalar needs
+ * no deep merge, so this reads the two layers and picks — it does not fork the merge engine.
+ *
+ * QUIET and fail-soft for the layers it reads ITSELF: it does not validate them and does not
+ * `exit` on a malformed one, because the caller runs moments before {@link initConfig}, which
+ * validates every layer and reports the very same problem — warning twice about one file is worse
+ * than not warning here. A failed read resolves to `undefined`, i.e. "nobody set it", and the
+ * surface auto-detects exactly as it does for a run with no config.
+ *
+ * ONE EXCEPTION, and it is deliberate: a `tui` may be INHERITED through a GS2-41 profile `extends`
+ * chain, so this walks that chain via the SHARED {@link resolveConfigExtends} rather than forking
+ * it — and that traversal owns its own reporting. It validates each base layer (so a base's own
+ * unknown-key warning can appear here as well as from `initConfig`) and hard-`exit`s on a cycle, a
+ * missing base or a malformed base. What the user sees is unchanged — `initConfig` exits on the
+ * same chain with the same message a moment later — but it now happens EARLIER, at surface
+ * selection rather than at config load. Forking the walk to silence it would mean a second
+ * inheritance engine; ignoring `extends` would mean silently dropping an inherited `tui`.
+ *
+ * Ordering: this is DETECTION, so per the GS2-11 invariant above it must run before any
+ * {@link initConfig} in the process — as it does, alongside {@link hasAnyConfig} in `startSession`.
+ */
+export declare function loadConfiguredTui(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<boolean | undefined>;
+/**
+ * Initialize configuration by loading from available config files
+ * @returns The loaded GthConfig
+ */
+export declare function initConfig(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<GthConfig>;
+/**
+ * Process JSON LLM config by creating the appropriate LLM instance
+ * @param jsonConfig - The parsed JSON config
+ * @param commandLineConfigOverrides - command line config overrides
+ * @returns Promise<GthConfig>
+ */
+export declare function tryJsonConfig(jsonConfig: RawGthConfig, commandLineConfigOverrides: CommandLineConfigOverrides): Promise<GthConfig>;
+/**
+ * Resolve a fully-merged {@link GthConfig} from a partial config + CLI overrides WITHOUT
+ * any global side effects. It deep-merges defaults, applies CLI overrides, resolves the numeric
+ * `consoleLevel` (warning + defaulting to INFO on an invalid value), and computes
+ * `canInterruptInferenceWithEsc` and `useColour`. The process-global setters (`setUseColour` /
+ * `setConsoleLevel`) are applied separately by {@link mergeConfig}, so this function can be
+ * reasoned about and reused without touching global state.
+ *
+ * It WRITES nothing globally, but it does READ the environment: `canInterruptInferenceWithEsc`
+ * consults stdin's TTY status, and (CFG-30) `useColour` consults `FORCE_COLOR`, `NO_COLOR` and
+ * stdout's TTY status. So it is deterministic for a given environment rather than a pure function
+ * of its arguments — a test that pins a resolved config should declare the terminal and the colour
+ * environment it expects in its setup. The ladder itself is a pure helper
+ * ({@link resolveUseColour}) so it can be tested rung by rung without process globals.
+ */
+export declare function resolveConfig(partialConfig: Omit<Partial<GthConfig>, 'consoleLevel'> & {
+    consoleLevel?: ConsoleLevelInput;
+}, commandLineConfigOverrides: CommandLineConfigOverrides): GthConfig;
+/**
+ * One config LAYER's validation outcome inside a {@link ConfigValidationReport}: the pure
+ * read-side result ({@link validateRawGthConfig}) plus the source label so a consumer can name
+ * WHICH file carried a warning/error (the project path, or `"<name> (global)"`).
+ */
+export interface ConfigLayerValidationReport extends RawConfigValidationResult {
+    /** The resolved config path (project layer) or `"<name> (global)"` (global layer). */
+    sourceLabel: string;
+}
+/**
+ * The outcome of `gth config validate`: whether any config was found, and the per-layer verdict
+ * for EVERY layer a run would validate. Pure/read-side — it neither builds an LLM nor mutates
+ * process globals, so it can report a verdict without the run-path's side effects. The command
+ * layer turns this into console output + an exit code.
+ *
+ * GS2-29 — `validateConfig` mirrors the layer set `initConfig` validates: the discovered PROJECT
+ * layer (if any) AND the GLOBAL layer (if any). A run validates both and exits(1) if EITHER
+ * carries a problem, so a removed shape in the global config (with a clean project config) shows
+ * up here exactly as the run would reject it. Both layers are kept in {@link layers} (in run
+ * order) so the offending file is always identifiable.
+ */
+export interface ConfigValidationReport {
+    /** False when neither a project nor a global config exists within the discovery boundary. */
+    found: boolean;
+    /** True only when a config was found AND every present layer validates OK. */
+    ok: boolean;
+    /**
+     * Each config layer a run would load + validate, in run order: the discovered PROJECT layer
+     * (if any) first, then the GLOBAL layer (if any). Empty when `found` is false.
+     */
+    layers: ConfigLayerValidationReport[];
+}
+/**
+ * Locate and validate the effective raw config against the schema WITHOUT building the LLM
+ * or merging defaults (the read-side of GS2-1). Honours `--config`, up-tree discovery, and the
+ * identity profile via {@link findProjectConfigPath}.
+ *
+ * GS2-29 — validates the SAME layer set a real run does: the discovered PROJECT layer (if any)
+ * AND the GLOBAL layer (if any), mirroring `initConfig`'s `validateRawConfigLayer(project)` +
+ * `applyGlobalConfigBase` → `loadGlobalRawConfig(global)`. Each present layer is validated
+ * independently ({@link validateRawGthConfig}) and its outcome recorded in {@link
+ * ConfigValidationReport.layers}, so a removed shape in EITHER file is reported (labelled with
+ * its source) rather than under-reported.
+ *
+ * A PROJECT-layer JSONC/module parse failure is thrown to the caller (surfaced as a clear
+ * "invalid config" error + non-zero exit). A GLOBAL-layer parse failure is treated as an absent
+ * global (no layer added) but is surfaced with a `displayWarning` — exactly as a run does (it
+ * warns the user while ignoring the broken global's value) — see {@link
+ * loadGlobalRawConfigUnvalidated}.
+ *
+ * GS2-73 — for the PROJECT layer it also walks the GS2-41 profile `extends` chain (via the SAME
+ * {@link composeExtends}/{@link resolveExtendsChain} the run path uses), so a cycle or a missing
+ * base — which fail a real run — is reported here as a not-ok layer instead of passing OK and only
+ * failing at run time. The GLOBAL layer is NOT walked, mirroring the run (`resolveConfigExtends`
+ * runs on the project/profile layer only).
+ */
+export declare function validateConfig(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<ConfigValidationReport>;