@gaunt-sloth/core 2.0.0-alpha.23 → 2.0.0-alpha.25

package/dist/config/mouse.d.ts

@@ -0,0 +1,50 @@
+/**
+ * TUI-C37 — the single place that decides whether the Ink TUI turns on terminal mouse reporting.
+ *
+ * Shaped exactly like the colour decision in `colour.ts`: everything the answer depends on arrives
+ * as an argument, so the ladder is testable rung by rung without touching process globals.
+ *
+ * Mouse reporting is ON by default, which is what makes the TUI's clickable affordances
+ * discoverable at all. The cost is real and is why the off-ramps below exist: while tracking is on
+ * the terminal hands drag events to the application, so its own text selection needs a modifier
+ * (Shift, or Option on macOS terminals). {@link MOUSE_SELECTION_HINT} is the one wording for that,
+ * so `/help` and the `/mouse` feedback cannot drift apart.
+ */
+/** Everything the mouse decision depends on. See {@link resolveUseMouse}. */
+export interface UseMouseInput {
+    /**
+     * Raw `GTH_NO_MOUSE` environment value; `undefined` when the variable is not set at all. Set and
+     * non-empty means mouse OFF. This rung outranks config because it is the escape hatch that works
+     * WITHOUT editing a config file — the state someone is in when their terminal mishandles tracking
+     * and the session is already unpleasant to use.
+     */
+    noMouse?: string;
+    /**
+     * `useMouse` as the user actually wrote it — read from the RAW config, BEFORE `DEFAULT_CONFIG` is
+     * merged in. `undefined` means the user set nothing. After the default merge an explicit `true` is
+     * indistinguishable from the default `true`, so this must be captured pre-merge or the rung
+     * collapses (the same trap `explicitUseColour` documents).
+     */
+    explicitUseMouse?: boolean;
+    /** Raw `TERM`; `dumb`, empty or unset describes a terminal that cannot be expected to track. */
+    term?: string;
+    /** Whether stdout is a terminal. */
+    stdoutIsTTY: boolean;
+    /** Whether stdin is a terminal — mouse REPORTS arrive on stdin, so both ends must be a TTY. */
+    stdinIsTTY: boolean;
+}
+/**
+ * The user-facing sentence explaining how to select text while tracking is on. Terminals disagree
+ * about which modifier restores native selection, so this names both rather than promising one.
+ */
+export declare const MOUSE_SELECTION_HINT = "To select text while the mouse is on, hold Shift (Option in some macOS terminals) while dragging.";
+/**
+ * Resolve mouse reporting from the four-rung precedence ladder, highest wins:
+ *
+ *   1. `GTH_NO_MOUSE` is set and non-empty — mouse OFF, no config file needed.
+ *   2. `useMouse` was set explicitly in config — use it verbatim.
+ *   3. `TERM` is unset, empty or `dumb` — mouse OFF; nothing useful can be reported.
+ *   4. Otherwise — ON when BOTH stdout and stdin are terminals. A piped, redirected or captured run
+ *      never enables tracking, so its bytes are identical to a run with mouse compiled out.
+ */
+export declare function resolveUseMouse(input: UseMouseInput): boolean;

package/dist/config/mouse.js

@@ -0,0 +1,44 @@
+/**
+ * TUI-C37 — the single place that decides whether the Ink TUI turns on terminal mouse reporting.
+ *
+ * Shaped exactly like the colour decision in `colour.ts`: everything the answer depends on arrives
+ * as an argument, so the ladder is testable rung by rung without touching process globals.
+ *
+ * Mouse reporting is ON by default, which is what makes the TUI's clickable affordances
+ * discoverable at all. The cost is real and is why the off-ramps below exist: while tracking is on
+ * the terminal hands drag events to the application, so its own text selection needs a modifier
+ * (Shift, or Option on macOS terminals). {@link MOUSE_SELECTION_HINT} is the one wording for that,
+ * so `/help` and the `/mouse` feedback cannot drift apart.
+ */
+/**
+ * The user-facing sentence explaining how to select text while tracking is on. Terminals disagree
+ * about which modifier restores native selection, so this names both rather than promising one.
+ */
+export const MOUSE_SELECTION_HINT = 'To select text while the mouse is on, hold Shift (Option in some macOS terminals) while dragging.';
+/**
+ * Resolve mouse reporting from the four-rung precedence ladder, highest wins:
+ *
+ *   1. `GTH_NO_MOUSE` is set and non-empty — mouse OFF, no config file needed.
+ *   2. `useMouse` was set explicitly in config — use it verbatim.
+ *   3. `TERM` is unset, empty or `dumb` — mouse OFF; nothing useful can be reported.
+ *   4. Otherwise — ON when BOTH stdout and stdin are terminals. A piped, redirected or captured run
+ *      never enables tracking, so its bytes are identical to a run with mouse compiled out.
+ */
+export function resolveUseMouse(input) {
+    // Rung 1 — the no-config escape hatch.
+    if (input.noMouse !== undefined && input.noMouse !== '') {
+        return false;
+    }
+    // Rung 2 — the user's own config. Only reachable with an explicit value, never the default.
+    if (input.explicitUseMouse !== undefined) {
+        return input.explicitUseMouse;
+    }
+    // Rung 3 — a terminal that cannot track. Checked below config so someone on an unusual TERM that
+    // does support tracking can still force it on.
+    if (input.term === undefined || input.term === '' || input.term === 'dumb') {
+        return false;
+    }
+    // Rung 4 — default on, but only for a genuine interactive terminal at both ends.
+    return input.stdoutIsTTY && input.stdinIsTTY;
+}
+//# sourceMappingURL=mouse.js.map

package/dist/config/mouse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mouse.js","sourceRoot":"","sources":["../../src/config/mouse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,mGAAmG,CAAC;AAEtG;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB;IAClD,uCAAuC;IACvC,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACxD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4FAA4F;IAC5F,IAAI,KAAK,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC,gBAAgB,CAAC;IAChC,CAAC;IAED,iGAAiG;IACjG,+CAA+C;IAC/C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iFAAiF;IACjF,OAAO,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,UAAU,CAAC;AAC/C,CAAC"}

package/dist/config/profiles.d.ts

@@ -0,0 +1,68 @@
+import type { RawGthConfig } from '#src/config/types.js';
+/**
+ * A profile name maps to a single directory segment under `.gsloth-settings/`, so it must be one
+ * safe path component: letters, digits, `.`, `_`, `-` only, and never `.`/`..` (which would escape
+ * or self-reference the settings dir). This is a create-time guard so a traversal-shaped name
+ * (`../evil`, `a/b`) can never write outside the profile tree.
+ */
+export declare const PROFILE_NAME_RE: RegExp;
+/** Fallback provider/model for a scaffold seeded from neither a current config nor `--model`. */
+export declare const DEFAULT_SCAFFOLD_PROVIDER = "anthropic";
+export declare const DEFAULT_SCAFFOLD_MODEL = "claude-sonnet-4-5";
+/**
+ * Reject a profile name that is empty, `.`/`..`, or contains anything other than
+ * `[A-Za-z0-9._-]` (so it can never traverse out of `.gsloth-settings/`). Throws a clear error;
+ * returns the trimmed name on success.
+ */
+export declare function validateProfileName(nameRaw: string): string;
+/**
+ * The on-disk path a named profile's config is written to / discovered at:
+ * `<projectDir>/.gsloth/.gsloth-settings/<name>/.gsloth.config.json`. Resolved against
+ * {@link getProjectDir} so it matches the loader's read-side resolution.
+ */
+export declare function resolveProfileConfigPath(name: string): string;
+/**
+ * Options for seeding a scaffold. `seedType`/`seedModel` come from the current effective config
+ * (`modelProviderType` / `modelDisplayName`) when one resolves — present for JSON configs, absent
+ * for module (JS/MJS/TS) configs, which hand back an already-built LLM with no raw `type`. When
+ * neither seed nor {@link modelOverride} is available the scaffold falls back to the template
+ * defaults ({@link DEFAULT_SCAFFOLD_PROVIDER} / {@link DEFAULT_SCAFFOLD_MODEL}) so the written
+ * profile is always a valid, editable starting point.
+ */
+export interface ProfileScaffoldSeed {
+    /** Provider `type` of the current config (`modelProviderType`), when resolvable. */
+    seedType?: string;
+    /** Model id of the current config (`modelDisplayName`), when resolvable. */
+    seedModel?: string;
+    /** `--model <id>` override — wins over the seeded/template model. */
+    modelOverride?: string;
+}
+/**
+ * Build a complete, standalone raw profile config: `{ llm: { type, model } }`. The provider `type`
+ * comes from the current config's provider when known, else the template default; the model comes
+ * from `--model`, else the current config's model, else the template default. Shape-only — the
+ * caller validates it against the schema before writing.
+ */
+export declare function buildProfileScaffold(seed: ProfileScaffoldSeed): RawGthConfig;
+/** Outcome of {@link createNamedProfile}: the resolved path the profile config was written to. */
+export interface CreateProfileResult {
+    /** Absolute path of the written profile config. */
+    path: string;
+    /** The provider:model the scaffold was seeded with, for a confirmation message. */
+    llm: {
+        type: string;
+        model: string;
+    };
+}
+/**
+ * Scaffold a new named profile at {@link resolveProfileConfigPath}. Validates the name (no
+ * traversal), builds the scaffold ({@link buildProfileScaffold}), validates it against the GS2-1
+ * schema BEFORE writing (never writes an invalid profile), and refuses to clobber an existing
+ * profile unless `force`. Creates the `.gsloth/.gsloth-settings/<name>/` tree as needed so the
+ * loader's profile-discovery convention resolves it afterwards.
+ *
+ * @throws Error on an invalid name, an invalid scaffold, or an existing file without `force`.
+ */
+export declare function createNamedProfile(nameRaw: string, seed: ProfileScaffoldSeed & {
+    force?: boolean;
+}): CreateProfileResult;

package/dist/config/profiles.js

@@ -0,0 +1,93 @@
+/**
+ * @packageDocumentation
+ * GS2-33 — named config profiles. A profile is a `.gsloth/.gsloth-settings/<name>/` config
+ * block: the SAME discovery convention the GS2-1 cascade resolves for `--profile` /
+ * `--identity-profile` (see `loader.ts` `resolveIdentityProfileConfigPath`). This module is the
+ * write side — scaffolding a new, schema-valid profile config — kept separate from the loader's
+ * read side so the `gth config profile create` command is a thin wrapper over a pure, testable core.
+ *
+ * A named profile is NOT a merge on top of a base project config: with a profile selected the
+ * loader's first-match walk picks the profile-dir config as THE project-file layer, so the
+ * precedence is `CLI flags > profile-dir config > global config > DEFAULT_CONFIG`. The scaffolder
+ * therefore writes a complete, standalone config (at minimum a valid `llm` spec), not a fragment.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { GSLOTH_DIR, GSLOTH_SETTINGS_DIR, USER_PROJECT_CONFIG_JSON } from '#src/constants.js';
+import { getProjectDir } from '#src/utils/systemUtils.js';
+import { validateRawGthConfig } from '#src/config/schema.js';
+/**
+ * A profile name maps to a single directory segment under `.gsloth-settings/`, so it must be one
+ * safe path component: letters, digits, `.`, `_`, `-` only, and never `.`/`..` (which would escape
+ * or self-reference the settings dir). This is a create-time guard so a traversal-shaped name
+ * (`../evil`, `a/b`) can never write outside the profile tree.
+ */
+export const PROFILE_NAME_RE = /^[A-Za-z0-9._-]+$/;
+/** Fallback provider/model for a scaffold seeded from neither a current config nor `--model`. */
+export const DEFAULT_SCAFFOLD_PROVIDER = 'anthropic';
+export const DEFAULT_SCAFFOLD_MODEL = 'claude-sonnet-4-5';
+/**
+ * Reject a profile name that is empty, `.`/`..`, or contains anything other than
+ * `[A-Za-z0-9._-]` (so it can never traverse out of `.gsloth-settings/`). Throws a clear error;
+ * returns the trimmed name on success.
+ */
+export function validateProfileName(nameRaw) {
+    const name = (nameRaw ?? '').trim();
+    if (!name) {
+        throw new Error('Profile name must not be empty.');
+    }
+    if (name === '.' || name === '..') {
+        throw new Error(`Invalid profile name "${name}".`);
+    }
+    if (!PROFILE_NAME_RE.test(name)) {
+        throw new Error(`Invalid profile name "${name}": use only letters, digits, '.', '_' or '-' ` +
+            '(a profile name is a single directory segment).');
+    }
+    return name;
+}
+/**
+ * The on-disk path a named profile's config is written to / discovered at:
+ * `<projectDir>/.gsloth/.gsloth-settings/<name>/.gsloth.config.json`. Resolved against
+ * {@link getProjectDir} so it matches the loader's read-side resolution.
+ */
+export function resolveProfileConfigPath(name) {
+    return resolve(getProjectDir(), GSLOTH_DIR, GSLOTH_SETTINGS_DIR, name, USER_PROJECT_CONFIG_JSON);
+}
+/**
+ * Build a complete, standalone raw profile config: `{ llm: { type, model } }`. The provider `type`
+ * comes from the current config's provider when known, else the template default; the model comes
+ * from `--model`, else the current config's model, else the template default. Shape-only — the
+ * caller validates it against the schema before writing.
+ */
+export function buildProfileScaffold(seed) {
+    const type = seed.seedType ?? DEFAULT_SCAFFOLD_PROVIDER;
+    const model = seed.modelOverride ?? seed.seedModel ?? DEFAULT_SCAFFOLD_MODEL;
+    return { llm: { type, model } };
+}
+/**
+ * Scaffold a new named profile at {@link resolveProfileConfigPath}. Validates the name (no
+ * traversal), builds the scaffold ({@link buildProfileScaffold}), validates it against the GS2-1
+ * schema BEFORE writing (never writes an invalid profile), and refuses to clobber an existing
+ * profile unless `force`. Creates the `.gsloth/.gsloth-settings/<name>/` tree as needed so the
+ * loader's profile-discovery convention resolves it afterwards.
+ *
+ * @throws Error on an invalid name, an invalid scaffold, or an existing file without `force`.
+ */
+export function createNamedProfile(nameRaw, seed) {
+    const name = validateProfileName(nameRaw);
+    const scaffold = buildProfileScaffold(seed);
+    // Validate BEFORE writing — a broken scaffold must fail here, never land on disk to be run later.
+    const validation = validateRawGthConfig(scaffold);
+    if (!validation.ok) {
+        throw new Error(`Refusing to write an invalid profile "${name}":\n${validation.errorMessage ?? ''}`);
+    }
+    const path = resolveProfileConfigPath(name);
+    if (existsSync(path) && !seed.force) {
+        throw new Error(`Profile "${name}" already exists at ${path}. Pass --force to overwrite it.`);
+    }
+    mkdirSync(resolve(path, '..'), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(scaffold, null, 2)}\n`, 'utf8');
+    const llm = scaffold.llm;
+    return { path, llm: { type: llm.type, model: llm.model } };
+}
+//# sourceMappingURL=profiles.js.map

package/dist/config/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/config/profiles.ts"],"names":[],"mappings":"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"}