@gaunt-sloth/core 2.0.0-alpha.4 → 2.0.0-alpha.40

package/dist/config/jsonc.js

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ * JSONC (JSON-with-comments) parsing for on-disk `.gsloth.config.json` files.
+ *
+ * The loader historically `JSON.parse`d config files, which rejects the two things
+ * hand-edited config files most want: `//` / `/* … *​/` comments and trailing commas.
+ * This wraps Microsoft's zero-dependency `jsonc-parser` so a plain `.json` config may
+ * carry both, while a genuinely malformed file still fails with a clear, located error
+ * (rather than silently returning `undefined`).
+ *
+ * `jsonc-parser` is used over a hand-rolled comment-stripper because stripping comments
+ * with a regex mishandles `//` / `/*` sequences that appear *inside* string values and
+ * escaped quotes; the tokenizer here respects string boundaries correctly. It has no
+ * transitive dependencies and is the same parser VS Code uses for its settings files.
+ */
+import { parse as parseJsoncTree, printParseErrorCode } from 'jsonc-parser';
+/**
+ * Parse a JSONC string (JSON + comments + trailing commas) into a value.
+ *
+ * On success returns the parsed value. On a structural error (anything `JSON.parse`
+ * would also reject, e.g. a missing brace or a dangling property) it throws a `SyntaxError`
+ * whose message names the first problem and its 0-based character offset, so the loader's
+ * existing "Failed to read config …" diagnostics stay actionable.
+ *
+ * @param text The file contents.
+ * @param sourceLabel Optional human-readable source name, included in the error message.
+ */
+export function parseJsonc(text, sourceLabel) {
+    const errors = [];
+    const value = parseJsoncTree(text, errors, {
+        allowTrailingComma: true,
+        disallowComments: false,
+    });
+    if (errors.length > 0) {
+        const first = errors[0];
+        const where = sourceLabel ? ` in ${sourceLabel}` : '';
+        throw new SyntaxError(`Invalid JSON/JSONC${where}: ${printParseErrorCode(first.error)} at offset ${first.offset}.`);
+    }
+    return value;
+}
+//# sourceMappingURL=jsonc.js.map

package/dist/config/jsonc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonc.js","sourceRoot":"","sources":["../../src/config/jsonc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,KAAK,IAAI,cAAc,EAAmB,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAE7F;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,WAAoB;IAC3D,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE;QACzC,kBAAkB,EAAE,IAAI;QACxB,gBAAgB,EAAE,KAAK;KACxB,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,OAAO,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,WAAW,CACnB,qBAAqB,KAAK,KAAK,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,KAAK,CAAC,MAAM,GAAG,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/config/loader.d.ts

@@ -1,3 +1,4 @@
+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
@@ -11,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.
  */
@@ -18,6 +25,30 @@ 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.
+ * @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.
  *
@@ -26,7 +57,7 @@ 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.
  *
@@ -36,6 +67,40 @@ export declare function findProjectConfigPath(commandLineConfigOverrides: Comman
  * @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
@@ -47,7 +112,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.
  *
@@ -57,12 +122,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
@@ -77,12 +172,76 @@ 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;
+/**
+ * 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>;