@gaunt-sloth/core 2.0.0-alpha.0 → 2.0.0-alpha.10

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/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025-present Andrew Kondratev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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
 
@@ -29,7 +29,6 @@ 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/agent`](../agent) — Agent runtime: built-in tools, filesystem toolkit, middleware registry, 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`](../app) — Main CLI application

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,101 @@
+/**
+ * @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) is on by
+    // default across commands; a user `builtInTools` setting replaces this set entirely.
+    // Cast keeps it a mutable `string[]` under the surrounding `as const`.
+    builtInTools: ['gth_checklist'],
+    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,yFAAyF;IACzF,qFAAqF;IACrF,uEAAuE;IACvE,YAAY,EAAE,CAAC,eAAe,CAAa;IAC3C,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,109 @@
+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).
+ *
+ * @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;
+/**
+ * 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;
+/**
+ * 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.
+ */
+export interface ConfigValidationReport extends RawConfigValidationResult {
+    /** False when no project or global config exists within the discovery boundary. */
+    found: boolean;
+    /** The resolved config path (or `"<name> (global)"`) when one was found. */
+    sourceLabel?: string;
+}
+/**
+ * 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).
+ */
+export declare function validateConfig(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<ConfigValidationReport>;