@gaunt-sloth/core 2.0.0-alpha.2 → 2.0.0-alpha.20

package/.gsloth.code.md

@@ -16,6 +16,16 @@ You have access to the entire project directory and can:
 - Create new files and directories as needed
 - Execute commands to run tests, build the project or run static analysis (lint)
 
+## File paths
+
+- Paths are real absolute filesystem paths — there is no virtual root. The current
+  working directory is provided to you separately; do NOT assume it is `/`.
+- The filesystem tools (`ls`/`glob`/`read_file`/`write_file`/`edit_file`/`grep`) and
+  `run_shell_command` share the same real paths. A path that works in the shell works
+  in the filesystem tools and vice versa.
+- Relative paths resolve against the working directory. Check the current directory
+  before filesystem operations and prefer absolute paths when unsure.
+
 Focus on writing clean, maintainable code that follows the project's established patterns and conventions. Always test your changes when possible and explain what you're doing and why.
 
 ## Running tests

package/README.md

@@ -11,7 +11,7 @@ Core utilities and types for Gaunt Sloth.
 - State and artifact storage: `artifactStore`
 - Shared constants and types
 
-AI vendor packages are not direct dependencies. Each vendor package is an optional peer dependency, resolved at runtime by whichever consumer (e.g. `gaunt-sloth-assistant`) pulls them in.
+AI vendor packages are not direct dependencies. Each vendor package is an optional peer dependency, resolved at runtime by whichever consumer (e.g. `gaunt-sloth`) pulls them in.
 
 ## Dependencies
 
@@ -28,8 +28,8 @@ import { display } from '@gaunt-sloth/core/utils/consoleUtils.js';
 
 ## Related packages
 
-- [`@gaunt-sloth/core`](../core) — Core utilities, config, and agent infrastructure (this package)
-- [`@gaunt-sloth/tools`](../tools) — Built-in tools, filesystem toolkit, and middleware registry
-- [`@gaunt-sloth/api`](../api) — API server, AG-UI, MCP, and A2A integration
-- [`@gaunt-sloth/review`](../review) — Review and Q&A modules with standalone CLI
-- [`gaunt-sloth-assistant`](../assistant) — Main CLI application
+- [`@gaunt-sloth/core`](https://www.npmjs.com/package/@gaunt-sloth/core) — Core utilities, config, and agent infrastructure (this package) ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/core))
+- [`@gaunt-sloth/agent`](https://www.npmjs.com/package/@gaunt-sloth/agent) — Agent runtime: built-in tools, filesystem toolkit, middleware registry, API server, AG-UI, MCP, and A2A integration ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/agent))
+- [`@gaunt-sloth/review`](https://www.npmjs.com/package/@gaunt-sloth/review) — Review and Q&A modules with standalone CLI ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/review))
+- [`@gaunt-sloth/batch`](https://www.npmjs.com/package/@gaunt-sloth/batch) — Batch / eval / workflow runtime ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/batch))
+- [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) — Main CLI application ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/app))

package/dist/config/defaults.d.ts

@@ -0,0 +1,85 @@
+import { StatusLevel } from '#src/core/types.js';
+/**
+ * Default config
+ */
+export declare const DEFAULT_CONFIG: {
+    readonly contentSource: 'file';
+    readonly requirementSource: 'file';
+    /**
+     * Path to project-specific guidelines.
+     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
+     * for example, to AGENTS.md
+     */
+    readonly projectGuidelines: ".gsloth.guidelines.md";
+    /**
+     * Whether to include the current date in the project review instructions or not.
+     */
+    readonly includeCurrentDateAfterGuidelines: false;
+    readonly projectReviewInstructions: ".gsloth.review.md";
+    readonly filesystem: 'none';
+    readonly builtInTools: string[];
+    readonly debugLog: false;
+    readonly consoleLevel: StatusLevel.INFO;
+    /**
+     * Default source for both requirements and content is GitHub.
+     * It needs GitHub CLI (gh).
+     *
+     * `github` content source uses `gh pr diff NN` internally. {@link src/sources/ghPrDiffSource.ts!}
+     *
+     *
+     * `github` requirement source uses `gh issue view NN` internally
+     */
+    readonly commands: {
+        readonly pr: {
+            readonly contentSource: 'github';
+            readonly requirementSource: 'github';
+            readonly rating: {
+                readonly enabled: true;
+                readonly passThreshold: 6;
+                readonly minRating: 0;
+                readonly maxRating: 10;
+                readonly errorOnReviewFail: true;
+            };
+        };
+        readonly review: {
+            readonly rating: {
+                readonly enabled: true;
+                readonly passThreshold: 6;
+                readonly minRating: 0;
+                readonly maxRating: 10;
+                readonly errorOnReviewFail: true;
+            };
+        };
+        readonly ask: {
+            readonly filesystem: 'read';
+        };
+        readonly chat: {
+            readonly filesystem: 'read';
+        };
+        readonly code: {
+            readonly filesystem: 'all';
+        };
+        readonly exec: {
+            readonly filesystem: 'all';
+        };
+        readonly api: {
+            readonly filesystem: 'read';
+            readonly port: 3000;
+            readonly cors: {
+                readonly allowOrigin: 'http://localhost:3000';
+                readonly allowMethods: 'POST, GET, OPTIONS';
+                readonly allowHeaders: 'Content-Type, Accept';
+            };
+        };
+    };
+    readonly streamOutput: true;
+    readonly writeOutputToFile: false;
+    readonly writeBinaryOutputsToFile: true;
+    readonly useColour: true;
+    readonly streamSessionInferenceLog: true;
+    readonly canInterruptInferenceWithEsc: true;
+    readonly aiignore: {
+        readonly enabled: true;
+        readonly patterns: undefined;
+    };
+};

package/dist/config/defaults.js

@@ -0,0 +1,103 @@
+/**
+ * @packageDocumentation
+ * Default Gaunt Sloth configuration ({@link DEFAULT_CONFIG}). Extracted verbatim from
+ * the former `config.ts` god-file; values are unchanged.
+ */
+import { PROJECT_GUIDELINES, PROJECT_REVIEW_INSTRUCTIONS } from '#src/constants.js';
+import { StatusLevel } from '#src/core/types.js';
+/**
+ * Default config
+ */
+export const DEFAULT_CONFIG = {
+    contentSource: 'file',
+    requirementSource: 'file',
+    /**
+     * Path to project-specific guidelines.
+     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
+     * for example, to AGENTS.md
+     */
+    projectGuidelines: PROJECT_GUIDELINES,
+    /**
+     * Whether to include the current date in the project review instructions or not.
+     */
+    includeCurrentDateAfterGuidelines: false,
+    projectReviewInstructions: PROJECT_REVIEW_INSTRUCTIONS,
+    filesystem: 'none',
+    // Enabled built-in tools. `gth_checklist` (the lean agent's planning/todo tool) and `gth_grep`
+    // (the permission-light content-search tool, GS2-51) are on by default across commands; a user
+    // `builtInTools` setting replaces this set entirely. Both are named to coexist with the deep
+    // backend's own `write_todos`/`grep` built-ins. Cast keeps it a mutable `string[]` under the
+    // surrounding `as const`.
+    builtInTools: ['gth_checklist', 'gth_grep'],
+    debugLog: false,
+    consoleLevel: StatusLevel.INFO, // Default to INFO level, not debug
+    /**
+     * Default source for both requirements and content is GitHub.
+     * It needs GitHub CLI (gh).
+     *
+     * `github` content source uses `gh pr diff NN` internally. {@link src/sources/ghPrDiffSource.ts!}
+     *
+     *
+     * `github` requirement source uses `gh issue view NN` internally
+     */
+    commands: {
+        pr: {
+            contentSource: 'github',
+            requirementSource: 'github',
+            rating: {
+                enabled: true,
+                passThreshold: 6,
+                minRating: 0,
+                maxRating: 10,
+                errorOnReviewFail: true,
+            },
+        },
+        review: {
+            rating: {
+                enabled: true,
+                passThreshold: 6,
+                minRating: 0,
+                maxRating: 10,
+                errorOnReviewFail: true,
+            },
+        },
+        ask: {
+            filesystem: 'read',
+        },
+        chat: {
+            filesystem: 'read',
+        },
+        code: {
+            filesystem: 'all',
+        },
+        exec: {
+            filesystem: 'all',
+        },
+        api: {
+            filesystem: 'read',
+            port: 3000,
+            cors: {
+                allowOrigin: 'http://localhost:3000',
+                allowMethods: 'POST, GET, OPTIONS',
+                allowHeaders: 'Content-Type, Accept',
+            },
+        },
+    },
+    streamOutput: true,
+    writeOutputToFile: false,
+    writeBinaryOutputsToFile: true,
+    useColour: true,
+    streamSessionInferenceLog: true,
+    canInterruptInferenceWithEsc: true,
+    aiignore: {
+        enabled: true,
+        patterns: undefined,
+    },
+};
+/**
+ * Needed DEFAULT_CONFIG to be plain const to be picked up by typedoc,
+ * this cast here is just for typecheck.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+DEFAULT_CONFIG;
+//# sourceMappingURL=defaults.js.map

package/dist/config/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa,EAAE,MAAM;IACrB,iBAAiB,EAAE,MAAM;IACzB;;;;OAIG;IACH,iBAAiB,EAAE,kBAAkB;IACrC;;OAEG;IACH,iCAAiC,EAAE,KAAK;IACxC,yBAAyB,EAAE,2BAA2B;IACtD,UAAU,EAAE,MAAM;IAClB,+FAA+F;IAC/F,+FAA+F;IAC/F,6FAA6F;IAC7F,6FAA6F;IAC7F,0BAA0B;IAC1B,YAAY,EAAE,CAAC,eAAe,EAAE,UAAU,CAAa;IACvD,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,WAAW,CAAC,IAAI,EAAE,mCAAmC;IACnE;;;;;;;;OAQG;IACH,QAAQ,EAAE;QACR,EAAE,EAAE;YACF,aAAa,EAAE,QAAQ;YACvB,iBAAiB,EAAE,QAAQ;YAC3B,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,IAAI;YACV,IAAI,EAAE;gBACJ,WAAW,EAAE,uBAAuB;gBACpC,YAAY,EAAE,oBAAoB;gBAClC,YAAY,EAAE,sBAAsB;aACrC;SACF;KACF;IACD,YAAY,EAAE,IAAI;IAClB,iBAAiB,EAAE,KAAK;IACxB,wBAAwB,EAAE,IAAI;IAC9B,SAAS,EAAE,IAAI;IACf,yBAAyB,EAAE,IAAI;IAC/B,4BAA4B,EAAE,IAAI;IAClC,QAAQ,EAAE;QACR,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,SAAS;KACpB;CACO,CAAC;AAEX;;;GAGG;AACH,oEAAoE;AACpE,cAA2B,CAAC"}

package/dist/config/jsonc.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function parseJsonc(text: string, sourceLabel?: string): unknown;

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

@@ -0,0 +1,169 @@
+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.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>;
+/**
+ * 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/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/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>;
+/**
+ * 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 (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` /
+ * `setConsoleLevel`) are applied separately by {@link mergeConfig}, so this function can be
+ * reasoned about and reused without touching global state.
+ */
+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}.
+ */
+export declare function validateConfig(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<ConfigValidationReport>;