@gaunt-sloth/core 2.0.0-alpha.9 → 2.0.0-beta.0

package/dist/config/loader.d.ts

@@ -12,6 +12,12 @@ import type { CommandLineConfigOverrides, ConsoleLevelInput, GthConfig, RawGthCo
  *
  * 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.
  */
@@ -19,6 +25,34 @@ export declare function findProjectConfigPath(commandLineConfigOverrides: Comman
     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`, so it can be asked the question without
+ * committing to an outcome. {@link initConfig} uses it to enforce that an explicitly-named profile
+ * really exists (raising a catchable {@link ConfigDiscoveryError} when it does not), and callers
+ * that want to CLASSIFY rather than fail — BATCH-12's identity matrix checks every declared identity
+ * up front so one message can name them all — ask it directly. A blank/whitespace-only name counts
+ * as "no profile" → `undefined`.
+ *
+ * @param identityProfile The explicitly-requested identity profile name.
+ * @param options CFG-56 — `globalOnly` searches `~/.gsloth/.gsloth-settings/<name>/` INSTEAD of
+ * the up-tree project walk, for a `--global` run.
+ * @returns The resolved profile config path, or `undefined` when the profile has no config.
+ */
+export declare function resolveIdentityProfileConfigPath(identityProfile: string, options?: {
+    globalOnly?: boolean;
+}): string | undefined;
 /**
  * Loads the global gsloth config (if present) from the global `~/.gsloth` folder.
  *
@@ -27,16 +61,58 @@ export declare function findProjectConfigPath(commandLineConfigOverrides: Comman
  * user-controlled layer (still above {@link DEFAULT_CONFIG}).
  *
  * Lookup order within the global folder, first match wins:
- *   `.gsloth.config.json` -> `.gsloth.config.js` -> `.gsloth.config.mjs`
+ *   `.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.
  *
+ * @param options CFG-56 — `identityProfile` relocates the lookup to
+ * `~/.gsloth/.gsloth-settings/<name>/` and `globalOnly` scopes the profile names this layer refers
+ * to. Both are set ONLY for a `--global` run; see {@link globalLayerProfile}.
  * @returns The raw global config object, or `undefined` when no global config exists.
  */
-export declare function loadGlobalRawConfig(): Promise<Partial<RawGthConfig> | undefined>;
+export declare function loadGlobalRawConfig(options?: {
+    identityProfile?: string;
+    globalOnly?: boolean;
+}): 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, options?: {
+    globalOnly?: boolean;
+}): 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
@@ -48,7 +124,7 @@ export declare function loadGlobalRawConfig(): Promise<Partial<RawGthConfig> | u
  * order is ever introduced, decouple discovery's cwd-branch from `getProjectDir()`.
  */
 /**
- * Returns true when a project-level config file (json/js/mjs) exists for the given
+ * 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.
  *
@@ -58,12 +134,42 @@ export declare function loadGlobalRawConfig(): Promise<Partial<RawGthConfig> | u
 export declare function hasProjectConfig(commandLineConfigOverrides: CommandLineConfigOverrides): boolean;
 /**
  * CFG-10 — true when ANY usable configuration is present, either a project config file
- * (json/js/mjs) or a standalone global config (`~/.gsloth/.gsloth.config.*`). When this
+ * (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
@@ -78,32 +184,78 @@ export declare function initConfig(commandLineConfigOverrides: CommandLineConfig
 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 (a pure transform). It deep-merges defaults, applies CLI overrides,
- * resolves the numeric `consoleLevel` (warning + defaulting to INFO on an invalid value), and
- * computes `canInterruptInferenceWithEsc`. The process-global setters (`setUseColour` /
+ * 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;
 /**
- * The outcome of `gth config validate`: whether a config was found, where, and whether it
- * validates. 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.
+ * 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 ConfigValidationReport extends RawConfigValidationResult {
-    /** False when no project or global config exists within the discovery boundary. */
+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;
-    /** The resolved config path (or `"<name> (global)"`) when one was found. */
-    sourceLabel?: string;
+    /** 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}, falling back to a standalone global
- * config (CFG-8 order) when no project config exists. A JSONC/module parse failure is thrown
- * to the caller (surfaced as a clear "invalid config" error + non-zero exit).
+ * 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 walked on exactly the branch a run walks it: when NO
+ * project layer was discovered, so the global config is what `initConfig` loads and resolves
+ * `extends` on. With a project layer present the run underlays the raw global config
+ * ({@link applyGlobalConfigBase}) and never resolves its `extends`, so neither does this.
  */
 export declare function validateConfig(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<ConfigValidationReport>;