@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.1

package/dist/settings/manager.js

@@ -4,10 +4,12 @@
  * Priority: CLI flags > local > project > user > managed
  */
 import { readFileSync, existsSync, mkdirSync, writeFileSync, renameSync, copyFileSync, } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, extname } from "node:path";
 import { homedir } from "node:os";
+import { parse as parseYaml } from "yaml";
 import { validateSettings } from "./schema.js";
 import { migrateModels } from "../migrate-models.js";
+import { migrateConfig, CONFIG_VERSION_KEY } from "./migrate-config.js";
 /**
  * Resolve the user's home directory. Prefers `process.env.HOME` so that
  * runtime env overrides (set after process start, e.g. in tests) actually
@@ -18,14 +20,92 @@ import { migrateModels } from "../migrate-models.js";
 export function userHome() {
     return process.env.HOME ?? homedir();
 }
+/**
+ * Settings keys that form the trust/permission root and therefore must NOT be
+ * writable through the generic `config_set` / provider-agnostic write path.
+ * A protocol peer (external driver, paired phone, or a compromised renderer)
+ * can send arbitrary config writes; letting it set these would be equivalent to
+ * remotely disabling the workspace-trust / permission model:
+ *   - permissions      → self-authorize any tool (permissions.rules / defaultMode)
+ *   - env / localEnvironment → inject BASH_ENV / NODE_OPTIONS / LD_PRELOAD / PATH
+ *   - hooks            → run arbitrary commands on tool events
+ *   - mcpServers / mcpServerOverrides → point tools at attacker-controlled servers
+ * These are only meant to be changed by the local settings UI (a trusted write
+ * path) or by hand-editing the file, never by a generic remote config write.
+ */
+const PROTECTED_SETTING_ROOTS = new Set([
+    "permissions",
+    "env",
+    "localEnvironment",
+    "hooks",
+    "mcpServers",
+    "mcpServerOverrides",
+]);
+/**
+ * True if `key` (a dotted path like "permissions.rules" or just "env") targets a
+ * protected trust-root field. Matches on the FIRST segment so nested writes
+ * ("permissions.defaultMode", "env.FOO") are caught too.
+ */
+export function isProtectedSettingKey(key) {
+    const root = key.split(".")[0] ?? "";
+    return PROTECTED_SETTING_ROOTS.has(root);
+}
+/**
+ * The fixed cwd used for "no-repo" pure-chat conversations (a chat not bound to
+ * any code project). Same location as desktop's `resolveNoRepoCwd`
+ * (`join(homedir(), ".code-shell", "no-repo")`), but built from {@link userHome}
+ * so tests can isolate it by overriding `$HOME`. The engine compares
+ * `config.cwd === noRepoDir()` to flip skill/plugin filtering to whitelist mode.
+ */
+export function noRepoDir() {
+    return join(userHome(), ".code-shell", "no-repo");
+}
+/**
+ * Top-level settings fields that can influence code execution and are therefore
+ * stripped from an UNTRUSTED project's disk layers (project + local) before
+ * merge. A repo commits these into its `.code-shell/settings.json`, so an
+ * untrusted clone must not have them take effect:
+ *   - permissions  — `rules` can self-authorize (allow Bash …); `defaultMode`
+ *                     can set bypassPermissions.
+ *   - env          — injected into Bash child env unfiltered (BASH_ENV,
+ *                     LD_PRELOAD, PATH → arbitrary code on next command).
+ *   - localEnvironment — same, as the env floor.
+ *   - hooks        — arbitrary commands on lifecycle events.
+ *   - mcpServers   — auto-connect to attacker-controlled MCP servers.
+ * Only project-scoped layers are filtered; user/managed/flag are trusted.
+ * Mirrors Claude Code's TRUSTED_SETTING_SOURCES model (project sources excluded
+ * from dangerous env application until trust is granted).
+ */
+export const DANGEROUS_PROJECT_FIELDS = [
+    "permissions",
+    "env",
+    "localEnvironment",
+    "hooks",
+    "mcpServers",
+];
 export class SettingsManager {
     cwd;
     scope;
+    projectTrusted;
     sources = [];
     merged = null;
-    constructor(cwd = process.cwd(), scope = "project") {
+    constructor(cwd = process.cwd(), scope = "project", 
+    /**
+     * Workspace trust for the project directory. When false, dangerous fields
+     * committed into the project's own `.code-shell/settings.{json,local.json}`
+     * ({@link DANGEROUS_PROJECT_FIELDS}) are stripped before merge, so a cloned
+     * malicious repo can't self-authorize permission rules, inject `env`
+     * (BASH_ENV/LD_PRELOAD/…), register hooks, or connect MCP servers. Safe
+     * fields (model choice, UI prefs, …) still merge. The user/managed/flag
+     * layers are never gated — the user put those there deliberately.
+     *
+     * Defaults to `true` so existing embedders/tests keep their behavior; the
+     * host (desktop) passes the real trust decision from its trust-store.
+     */
+    projectTrusted = true) {
         this.cwd = cwd;
         this.scope = scope;
+        this.projectTrusted = projectTrusted;
     }
     /**
      * Load settings from all sources.
@@ -59,6 +139,33 @@ export class SettingsManager {
         }
         // Sort by priority ascending (merge in order, later wins)
         this.sources.sort((a, b) => a.priority - b.priority);
+        // Version-based config migration (migrate-config.ts), applied per physical
+        // file (user + project settings.json) so the write-back lands in the file
+        // the data came from. A file is only rewritten (with a .bak) when a step
+        // actually changed its content — a version-stamp-only diff isn't worth
+        // dirtying the user's (or a repo-tracked project) file for; steps are
+        // idempotent, so re-running on unstamped files each load is fine.
+        if (readUser) {
+            this.applyConfigMigration(join(userHome(), ".code-shell", "settings.json"), "user");
+        }
+        if (readProject) {
+            this.applyConfigMigration(join(this.cwd, ".code-shell", "settings.json"), "project");
+        }
+        // Workspace-trust gate: an untrusted project must not influence execution
+        // through dangerous fields committed into its own .code-shell/settings.*.
+        // Strip them from the project/local layers (after migration re-read the
+        // files, so we filter the final data) before merge. See
+        // DANGEROUS_PROJECT_FIELDS and the `projectTrusted` ctor arg.
+        if (!this.projectTrusted) {
+            for (const source of this.sources) {
+                if (source.name !== "project" && source.name !== "local")
+                    continue;
+                for (const field of DANGEROUS_PROJECT_FIELDS) {
+                    if (field in source.data)
+                        delete source.data[field];
+                }
+            }
+        }
         // Deep merge
         const raw = this.deepMerge();
         // Auto-migrate legacy models[] in the user settings file. Runs directly
@@ -81,7 +188,9 @@ export class SettingsManager {
                         providers: result.providers,
                         models: result.models,
                     };
-                    writeFileSync(userPath, JSON.stringify(migrated, null, 2), "utf-8");
+                    // Atomic write (tmp+rename) — a concurrent load must not see a
+                    // half-written file. File exists here (existsSync guard above).
+                    this.atomicWriteJson(userPath, migrated);
                     // Re-deep-merge with the migrated user data so the validate
                     // call sees the new shape rather than the legacy one.
                     const userSource = this.sources.find((s) => s.name === "user");
@@ -99,6 +208,47 @@ export class SettingsManager {
         this.merged = validateSettings(raw);
         return this.merged;
     }
+    /**
+     * Run the version-based migrations (migrate-config.ts MIGRATIONS) against a
+     * single physical settings file. Best-effort: any read/parse/write error
+     * falls through silently and the original source data is used as-is.
+     * Writes back (with a .bak, like the models[] migration above) ONLY when a
+     * step changed actual content — the configVersion stamp alone doesn't
+     * justify touching the file. On write-back the in-memory source is updated
+     * so this load() already sees the migrated shape.
+     */
+    applyConfigMigration(path, sourceName) {
+        if (!existsSync(path))
+            return;
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return;
+            const raw = parsed;
+            const result = migrateConfig(raw);
+            if (!result.changed)
+                return;
+            // Compare content with the version stamp normalized away — stamp-only
+            // changes are not persisted.
+            const stripStamp = (c) => {
+                const { [CONFIG_VERSION_KEY]: _v, ...rest } = c;
+                return rest;
+            };
+            if (JSON.stringify(stripStamp(raw)) === JSON.stringify(stripStamp(result.config)))
+                return;
+            copyFileSync(path, `${path}.bak`);
+            // Atomic write (tmp+rename) so a concurrent load can't read a half-written
+            // migrated file — matches the normal save path (atomicWriteJson). The file
+            // exists here (existsSync guard above), so the recursive mkdir is a no-op.
+            this.atomicWriteJson(path, result.config);
+            const source = this.sources.find((s) => s.name === sourceName);
+            if (source)
+                source.data = result.config;
+        }
+        catch {
+            // Best-effort — fall through to normal merge/validate.
+        }
+    }
     /**
      * Get current effective settings.
      */
@@ -149,9 +299,11 @@ export class SettingsManager {
         target[parts[parts.length - 1]] = value;
         mkdirSync(dirname(path), { recursive: true });
         // Atomic write: stage to .tmp, then rename, so a concurrent read can't
-        // catch a half-written file.
+        // catch a half-written file. mode 0o600 — settings.json can hold plaintext
+        // API keys, so it must be owner-only like credentials.json (store.ts:56),
+        // not world-readable (default umask leaves 0o644 otherwise).
         const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
-        writeFileSync(tmp, JSON.stringify(current, null, 2), "utf-8");
+        writeFileSync(tmp, JSON.stringify(current, null, 2), { encoding: "utf-8", mode: 0o600 });
         renameSync(tmp, path);
         this.invalidate();
     }
@@ -162,7 +314,14 @@ export class SettingsManager {
      * cache invalidation mirror saveUserSetting.
      */
     saveProjectSetting(key, value, cwd) {
+        // projectSettingsPath throws on an empty cwd (boundary guard) — keep that.
         const path = this.projectSettingsPath(cwd);
+        // Don't resurrect a deleted project root: atomicWriteJson's recursive mkdir
+        // of <cwd>/.code-shell recreates `cwd` itself as an empty shell when cwd is
+        // gone. A non-empty cwd that no longer exists means the project was deleted
+        // — skip the write rather than recreate it.
+        if (!existsSync(cwd))
+            return;
         const current = this.readJsonObject(path);
         const parts = key.split(".");
         let target = current;
@@ -185,7 +344,13 @@ export class SettingsManager {
      */
     deleteProjectSetting(key, cwd) {
         const path = this.projectSettingsPath(cwd);
-        if (!existsSync(path))
+        // Must be YAML-aware, symmetric with saveProjectSetting: a project with only
+        // settings.yaml has no .json, so the old `existsSync(path)` guard returned
+        // here and the override survived (read/merge ARE yaml-aware → UI shows
+        // "inherited" but the key still applies). readJsonObject resolves the sibling
+        // YAML; the cleaned object is written back as JSON (JSON is the write-back
+        // format and wins over YAML, exactly as save does).
+        if (!resolveConfigPath(path))
             return;
         const current = this.readJsonObject(path);
         const parts = key.split(".");
@@ -220,6 +385,14 @@ export class SettingsManager {
         const out = {};
         for (const k of Object.keys(raw))
             out[k] = validated[k];
+        // Same workspace-trust gate as load(): getForScope("project") is a direct
+        // file read that bypasses the merge, so an untrusted project's dangerous
+        // fields (e.g. localEnvironment.setupScripts — shell run at worktree setup)
+        // must be stripped here too. See DANGEROUS_PROJECT_FIELDS.
+        if (scope === "project" && !this.projectTrusted) {
+            for (const field of DANGEROUS_PROJECT_FIELDS)
+                delete out[field];
+        }
         return out;
     }
     projectSettingsPath(cwd) {
@@ -229,47 +402,111 @@ export class SettingsManager {
         return join(cwd, ".code-shell", "settings.json");
     }
     readJsonObject(path) {
-        if (!existsSync(path))
+        // Resolve to a sibling .yaml/.yml when the .json layer is absent so
+        // scope views (getForScope) see hand-written YAML too. JSON still wins.
+        const resolved = resolveConfigPath(path);
+        if (!resolved)
             return {};
-        try {
-            const parsed = JSON.parse(readFileSync(path, "utf-8"));
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                return parsed;
-            }
-        }
-        catch {
-            // Corrupt file — overwrite rather than crash.
-        }
-        return {};
+        return parseConfigFile(resolved) ?? {};
     }
     atomicWriteJson(path, data) {
         mkdirSync(dirname(path), { recursive: true });
+        // mode 0o600: settings.json may hold plaintext API keys — owner-only, see
+        // saveUserSetting above and credentials/store.ts.
         const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
-        writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+        writeFileSync(tmp, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 0o600 });
         renameSync(tmp, path);
     }
     loadJsonFile(path, name, priority) {
-        if (!existsSync(path))
+        // `path` is the canonical .json path for this layer. When it's absent but
+        // a sibling settings.yaml/.yml exists, read the YAML instead (JSON wins
+        // when both exist — JSON is the write-back format, YAML is hand-written).
+        const resolved = resolveConfigPath(path);
+        if (!resolved)
             return;
-        try {
-            const content = readFileSync(path, "utf-8");
-            const data = JSON.parse(content);
-            if (typeof data === "object" && data !== null) {
-                this.sources.push({ name, priority, data });
-            }
-        }
-        catch {
-            // Skip invalid files
-        }
+        const data = parseConfigFile(resolved);
+        if (data)
+            this.sources.push({ name, priority, data });
     }
     deepMerge() {
         let result = {};
         for (const source of this.sources) {
             result = merge(result, source.data);
         }
+        // Top-level `hooks` is the one array that CONCATENATES across layers
+        // instead of being replaced wholesale: a user-level (global) hook and a
+        // project-level hook should BOTH run, mirroring how Claude Code merges
+        // hooks from all settings files. Order follows layer priority (user
+        // first, project after). An explicit `"hooks": null` in a layer still
+        // resets everything below it (the escape hatch merge() already gives
+        // every other key); per-entry opt-out is the `disabled` field.
+        let hooks;
+        let sawHooks = false;
+        for (const source of this.sources) {
+            if (!("hooks" in source.data))
+                continue;
+            const v = source.data.hooks;
+            if (v === null) {
+                hooks = undefined;
+                sawHooks = true;
+            }
+            else if (Array.isArray(v)) {
+                hooks = [...(hooks ?? []), ...v];
+                sawHooks = true;
+            }
+            // Non-array garbage is left to merge()'s wholesale result so
+            // validateSettings still sees (and rejects) it unchanged.
+        }
+        if (sawHooks) {
+            if (hooks !== undefined)
+                result.hooks = hooks;
+            else
+                delete result.hooks;
+        }
         return result;
     }
 }
+/**
+ * Parse a config file by extension: .yaml/.yml go through the YAML parser,
+ * everything else through JSON.parse. Mirrors the loader's existing
+ * "corrupt file never crashes — silently skip" contract: on any read/parse
+ * error, or a non-object top-level value, returns null. The caller decides
+ * what an absent/empty layer means.
+ */
+function parseConfigFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const content = readFileSync(path, "utf-8");
+        const ext = extname(path).toLowerCase();
+        const parsed = ext === ".yaml" || ext === ".yml" ? parseYaml(content) : JSON.parse(content);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Corrupt file — skip rather than crash.
+    }
+    return null;
+}
+/**
+ * Given the JSON path for a settings layer (e.g. .../settings.json or
+ * .../settings.local.json), return the path that should actually be read:
+ * the .json file if it exists, otherwise a sibling .yaml/.yml if present.
+ * JSON is the write-back format and wins when both exist; YAML is a
+ * hand-written read-only alternative. Returns null when no layer file exists.
+ */
+function resolveConfigPath(jsonPath) {
+    if (existsSync(jsonPath))
+        return jsonPath;
+    const base = jsonPath.replace(/\.json$/, "");
+    for (const ext of [".yaml", ".yml"]) {
+        const candidate = `${base}${ext}`;
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
 function merge(base, override) {
     const result = { ...base };
     for (const [key, value] of Object.entries(override)) {

package/dist/settings/migrate-config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Version-based settings migration (TODO 8.5).
+ *
+ * A settings file carries an optional `configVersion` number. As the schema
+ * evolves, breaking shape changes register a migration step here; on load we
+ * apply every step whose `from` is >= the file's current version, in order,
+ * bringing the object up to CURRENT_CONFIG_VERSION. Pure + ordered so it's
+ * deterministic and unit-testable; the SettingsManager wires the result to a
+ * write-back (with a .bak) the same way the existing models[] migration does.
+ *
+ * Files with no `configVersion` are treated as version 0 (pre-versioning).
+ * A file already at CURRENT is a no-op (changed:false).
+ */
+export declare const CONFIG_VERSION_KEY = "configVersion";
+export interface MigrationStep {
+    /** Apply this step to a config at exactly this version. */
+    from: number;
+    /** Version the config is at after this step runs. */
+    to: number;
+    /** Transform the raw config object (must not mutate the input). */
+    migrate: (config: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Registered migrations, in ascending `from` order. New breaking changes
+ * append a step here; CURRENT_CONFIG_VERSION follows automatically.
+ */
+export declare const MIGRATIONS: readonly MigrationStep[];
+/** The version a freshly-written config is stamped with. */
+export declare const CURRENT_CONFIG_VERSION: number;
+/** Read the config's version, defaulting to 0 for pre-versioning files. */
+export declare function configVersionOf(config: Record<string, unknown>): number;
+export interface MigrateResult {
+    config: Record<string, unknown>;
+    changed: boolean;
+    fromVersion: number;
+    toVersion: number;
+}
+/**
+ * Bring a raw config up to CURRENT_CONFIG_VERSION by applying each registered
+ * step whose `from` matches the running version, in order. Always stamps the
+ * resulting (and an already-current) config with the current version key.
+ * `changed` is true when any step ran OR the version stamp was added/updated.
+ * Never mutates the input.
+ */
+export declare function migrateConfig(input: Record<string, unknown>, migrations?: readonly MigrationStep[]): MigrateResult;

package/dist/settings/migrate-config.js

@@ -0,0 +1,125 @@
+/**
+ * Version-based settings migration (TODO 8.5).
+ *
+ * A settings file carries an optional `configVersion` number. As the schema
+ * evolves, breaking shape changes register a migration step here; on load we
+ * apply every step whose `from` is >= the file's current version, in order,
+ * bringing the object up to CURRENT_CONFIG_VERSION. Pure + ordered so it's
+ * deterministic and unit-testable; the SettingsManager wires the result to a
+ * write-back (with a .bak) the same way the existing models[] migration does.
+ *
+ * Files with no `configVersion` are treated as version 0 (pre-versioning).
+ * A file already at CURRENT is a no-op (changed:false).
+ */
+import { BUILTIN_CATALOG } from "../model-catalog/builtin.js";
+export const CONFIG_VERSION_KEY = "configVersion";
+/**
+ * v0 → v1: backfill `catalogId` on imageGen/videoGen `providers[]` entries
+ * written before the model catalog existed (Catalog v1). Legacy entries only
+ * carry `kind`; the connections UI resolves its template by `catalogId`, so
+ * without it the model-preset dropdown degrades to an empty text box. The
+ * match mirrors the renderer's legacy fallback: builtin entry whose
+ * `adapterKind === kind` within the section's tag. Unmatched entries are left
+ * untouched (the UI shows a manual-input hint for those).
+ */
+function backfillGenCatalogIds(config) {
+    const next = { ...config };
+    for (const [key, tag] of [
+        ["imageGen", "image"],
+        ["videoGen", "video"],
+    ]) {
+        const gen = next[key];
+        if (!gen || typeof gen !== "object" || Array.isArray(gen))
+            continue;
+        const providers = gen.providers;
+        if (!Array.isArray(providers))
+            continue;
+        let touched = false;
+        const out = providers.map((p) => {
+            if (!p || typeof p !== "object" || Array.isArray(p))
+                return p;
+            const rec = p;
+            if (typeof rec.catalogId === "string")
+                return p;
+            const entry = BUILTIN_CATALOG.find((e) => e.adapterKind === rec.kind && e.tag === tag);
+            if (!entry)
+                return p;
+            touched = true;
+            return { ...rec, catalogId: entry.id };
+        });
+        if (touched)
+            next[key] = { ...gen, providers: out };
+    }
+    return next;
+}
+/**
+ * v1 → v2: drop the sandbox config the 设置页 mis-wrote. The local-env page
+ * used to write `sandbox:{mode:"auto", network:"allow", writableRoots:[],
+ * deniedReads:[]}` (its display default) on every save — opting users into a
+ * sandbox they never chose. That exact fingerprint = not a real choice, so we
+ * remove the whole sandbox field (→ follow/off). A user who actually configured
+ * it (changed mode/network or set roots/reads) is left untouched.
+ */
+function clearMisWrittenSandboxAuto(config) {
+    const sb = config.sandbox;
+    if (!sb || typeof sb !== "object" || Array.isArray(sb))
+        return config;
+    const s = sb;
+    const isMisWritten = s.mode === "auto" &&
+        s.network === "allow" &&
+        Array.isArray(s.writableRoots) && s.writableRoots.length === 0 &&
+        Array.isArray(s.deniedReads) && s.deniedReads.length === 0;
+    if (!isMisWritten)
+        return config;
+    const next = { ...config };
+    delete next.sandbox;
+    return next;
+}
+/**
+ * Registered migrations, in ascending `from` order. New breaking changes
+ * append a step here; CURRENT_CONFIG_VERSION follows automatically.
+ */
+export const MIGRATIONS = [
+    { from: 0, to: 1, migrate: backfillGenCatalogIds },
+    { from: 1, to: 2, migrate: clearMisWrittenSandboxAuto },
+];
+/** The version a freshly-written config is stamped with. */
+export const CURRENT_CONFIG_VERSION = MIGRATIONS.reduce((max, m) => Math.max(max, m.to), 0);
+/** Read the config's version, defaulting to 0 for pre-versioning files. */
+export function configVersionOf(config) {
+    const v = config[CONFIG_VERSION_KEY];
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
+}
+/**
+ * Bring a raw config up to CURRENT_CONFIG_VERSION by applying each registered
+ * step whose `from` matches the running version, in order. Always stamps the
+ * resulting (and an already-current) config with the current version key.
+ * `changed` is true when any step ran OR the version stamp was added/updated.
+ * Never mutates the input.
+ */
+export function migrateConfig(input, migrations = MIGRATIONS) {
+    const target = migrations.reduce((max, m) => Math.max(max, m.to), 0);
+    const fromVersion = configVersionOf(input);
+    let config = { ...input };
+    let v = fromVersion;
+    let stepsRan = false;
+    // Apply steps deterministically: for the current version, find the matching
+    // step, run it, advance. A migration list with gaps simply stops when no
+    // step matches the running version.
+    for (;;) {
+        const step = migrations.find((m) => m.from === v);
+        if (!step)
+            break;
+        config = { ...step.migrate(config) };
+        v = step.to;
+        stepsRan = true;
+    }
+    const alreadyStamped = input[CONFIG_VERSION_KEY] === target;
+    config[CONFIG_VERSION_KEY] = target;
+    return {
+        config,
+        changed: stepsRan || !alreadyStamped,
+        fromVersion,
+        toVersion: target,
+    };
+}

package/dist/settings/schema-export.d.ts

@@ -0,0 +1,25 @@
+/**
+ * JSON Schema export for the settings file.
+ *
+ * Editors (VS Code et al.) can point a `$schema` at the emitted
+ * `settings.schema.json` to get autocomplete + validation when hand-editing
+ * `~/.code-shell/settings.json` or `<project>/.code-shell/settings.json`.
+ *
+ * This module is side-effect free: it only EXPOSES the generator and a writer.
+ * `manager.load()` deliberately does NOT call these — emitting a file during
+ * load would pollute test HOMEs and add disk I/O to every boot. A host that
+ * wants the file on disk should call `writeSettingsSchemaFile()` explicitly
+ * (wiring TBD — see the task return note).
+ */
+/**
+ * Generate the JSON Schema for the settings object. The `name` option makes
+ * the root a `$ref` into `definitions.CodeShellSettings`, which is the shape
+ * editors expect when wiring up `$schema`.
+ */
+export declare function settingsJsonSchema(): Record<string, unknown>;
+/**
+ * Write the schema to `<dir>/settings.schema.json` using the same atomic
+ * tmp-file + rename dance as SettingsManager.atomicWriteJson, so a concurrent
+ * reader never sees a half-written file. Returns the absolute output path.
+ */
+export declare function writeSettingsSchemaFile(dir: string): string;

package/dist/settings/schema-export.js

@@ -0,0 +1,38 @@
+/**
+ * JSON Schema export for the settings file.
+ *
+ * Editors (VS Code et al.) can point a `$schema` at the emitted
+ * `settings.schema.json` to get autocomplete + validation when hand-editing
+ * `~/.code-shell/settings.json` or `<project>/.code-shell/settings.json`.
+ *
+ * This module is side-effect free: it only EXPOSES the generator and a writer.
+ * `manager.load()` deliberately does NOT call these — emitting a file during
+ * load would pollute test HOMEs and add disk I/O to every boot. A host that
+ * wants the file on disk should call `writeSettingsSchemaFile()` explicitly
+ * (wiring TBD — see the task return note).
+ */
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { SettingsSchema } from "./schema.js";
+/**
+ * Generate the JSON Schema for the settings object. The `name` option makes
+ * the root a `$ref` into `definitions.CodeShellSettings`, which is the shape
+ * editors expect when wiring up `$schema`.
+ */
+export function settingsJsonSchema() {
+    return zodToJsonSchema(SettingsSchema, { name: "CodeShellSettings" });
+}
+/**
+ * Write the schema to `<dir>/settings.schema.json` using the same atomic
+ * tmp-file + rename dance as SettingsManager.atomicWriteJson, so a concurrent
+ * reader never sees a half-written file. Returns the absolute output path.
+ */
+export function writeSettingsSchemaFile(dir) {
+    const out = join(dir, "settings.schema.json");
+    mkdirSync(dirname(out), { recursive: true });
+    const tmp = `${out}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(settingsJsonSchema(), null, 2), "utf-8");
+    renameSync(tmp, out);
+    return out;
+}