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

package/dist/settings/disk-defaults.d.ts

@@ -0,0 +1,42 @@
+import type { ValidatedSettings } from "./schema.js";
+import type { EngineConfig } from "../engine/types.js";
+/**
+ * The subset of EngineConfig the config hot-reload ("layer 2") pushes onto an
+ * already-running session's `this.config`. These are the "disk-default" fields:
+ * read from settings.json at construction, otherwise frozen for the session's
+ * life. Request-override fields (permissionMode / goal / maxTurns /
+ * maxContextTokens / cwd) are intentionally excluded — those are per-request
+ * and handled by handleConfigure / run() options, not by disk hot-push.
+ *
+ * Reload semantics per field (see Engine.refreshRuntimeConfig):
+ *   - preset: system-prompt / behavior hot-reloads (next-turn PromptComposer
+ *     re-resolves it); the builtin TOOL SET it implies needs a session restart
+ *     (registry is ctor-frozen, possibly shared via runtime).
+ *   - customSystemPrompt / appendSystemPrompt / responseLanguage / userProfile:
+ *     hot — re-read by the next-turn PromptComposer.
+ *
+ * IMPORTANT (#8): every field here is pushed as a PURE DISK value and will
+ * OVERRIDE any per-request slice override of the same field on the running
+ * session. Safe for the desktop host today (its slice carries only
+ * permissionMode+cwd, both excluded above). A future host that sets any of
+ * these per-request MUST exclude that field from the reload patch — or track
+ * per-request overrides separately — to avoid the reload clobbering it.
+ */
+export type DiskDefaultPatch = Pick<EngineConfig, "preset" | "customSystemPrompt" | "appendSystemPrompt" | "responseLanguage" | "userProfile" | "instructions" | "mcpServers">;
+/**
+ * Derive the disk-default config patch from freshly-read settings.
+ *
+ * This MUST mirror how `agent-server-stdio.ts`'s engineFactory builds these
+ * same fields from `settings.agent` + `mergePluginMcpServers(...)`, so a
+ * reloaded running session and a newly-created session converge on identical
+ * config (no divergence). It reuses `personalizationFrom` for the three
+ * personalization fields rather than duplicating the mapping.
+ */
+export declare function diskDefaultsFrom(settings: ValidatedSettings, 
+/**
+ * EFFECTIVE disabled plugins for the target session — the caller should
+ * pass `engine.getEffectiveDisabledLists().disabledPlugins` so the merge
+ * honors project capabilityOverrides (能力总览 project "on" overrides the
+ * global list). Omitted → falls back to the raw global list (legacy).
+ */
+effectiveDisabledPlugins?: string[]): DiskDefaultPatch;

package/dist/settings/disk-defaults.js

@@ -0,0 +1,33 @@
+import { personalizationFrom } from "./personalization.js";
+import { mergePluginMcpServers } from "../plugins/installer/loadPluginMcp.js";
+/**
+ * Derive the disk-default config patch from freshly-read settings.
+ *
+ * This MUST mirror how `agent-server-stdio.ts`'s engineFactory builds these
+ * same fields from `settings.agent` + `mergePluginMcpServers(...)`, so a
+ * reloaded running session and a newly-created session converge on identical
+ * config (no divergence). It reuses `personalizationFrom` for the three
+ * personalization fields rather than duplicating the mapping.
+ */
+export function diskDefaultsFrom(settings, 
+/**
+ * EFFECTIVE disabled plugins for the target session — the caller should
+ * pass `engine.getEffectiveDisabledLists().disabledPlugins` so the merge
+ * honors project capabilityOverrides (能力总览 project "on" overrides the
+ * global list). Omitted → falls back to the raw global list (legacy).
+ */
+effectiveDisabledPlugins) {
+    const agent = settings.agent ?? {};
+    return {
+        preset: agent.preset,
+        customSystemPrompt: agent.customSystemPrompt,
+        appendSystemPrompt: agent.appendSystemPrompt,
+        ...personalizationFrom(agent),
+        // Same merge engineFactory uses: user-configured servers + enabled
+        // plugins' servers. Plugin servers a disabled plugin would contribute are
+        // skipped, matching new-session construction.
+        mcpServers: mergePluginMcpServers(settings.mcpServers ?? {}, effectiveDisabledPlugins ??
+            settings.disabledPlugins ??
+            [], settings.mcpServerOverrides ?? {}),
+    };
+}

package/dist/settings/feature-flags.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Feature Flags — a small, central on/off registry for opt-in or
+ * experimental behavior.
+ *
+ * Design goals:
+ *   - One source of truth for flag NAMES + their DEFAULT state, so a flag
+ *     can't be checked under a typo (the known set is a const).
+ *   - Settings-driven: `settings.featureFlags` is a `{ [name]: boolean }`
+ *     overlay over the defaults. Project settings override user settings the
+ *     same way every other settings field does (the SettingsManager merge),
+ *     so a flag can be flipped per-workspace.
+ *   - Forgiving read: `isFeatureEnabled` falls back to the default when a
+ *     flag is absent from settings, and ignores unknown flag names from
+ *     settings (forward-compat with older binaries).
+ *
+ * This is the knob layer only — each consumer still has to CHECK its flag.
+ * The `/features` command (CLI) reads/writes this same map.
+ */
+/** Canonical flag names. Add new flags here so checks stay typo-safe. */
+export declare const FEATURE_FLAGS: {
+    /** Web search tool availability (also gated by a configured provider). */
+    readonly web_search: {
+        readonly default: true;
+        readonly description: "Enable the WebSearch tool";
+    };
+    /** The Bash/shell tool. Off → the model cannot run shell commands. */
+    readonly shell_tool: {
+        readonly default: true;
+        readonly description: "Enable the Bash/shell tool";
+    };
+    /** Fast-output mode for supported models. */
+    readonly fast_mode: {
+        readonly default: false;
+        readonly description: "Faster streaming output on supported models";
+    };
+    /** Undo system (file-operation backups + /undo). */
+    readonly undo: {
+        readonly default: false;
+        readonly description: "Per-session file undo (/undo)";
+    };
+    /** Shell snapshot: capture full stdout/stderr of commands. */
+    readonly shell_snapshot: {
+        readonly default: false;
+        readonly description: "Capture full command stdout/stderr snapshots";
+    };
+};
+export type FeatureFlagName = keyof typeof FEATURE_FLAGS;
+/** The settings overlay shape: a partial map of known flags → boolean. */
+export type FeatureFlagOverrides = Partial<Record<FeatureFlagName, boolean>>;
+/** All known flag names, for iteration (e.g. the /features listing). */
+export declare function featureFlagNames(): FeatureFlagName[];
+/** True when `name` is a recognized flag (narrows an arbitrary string). */
+export declare function isKnownFeatureFlag(name: string): name is FeatureFlagName;
+/**
+ * Resolve a flag's effective state: the settings overlay value when present
+ * and boolean, else the flag's compiled-in default. Unknown names → false
+ * (a check for a flag that doesn't exist is never "enabled").
+ */
+export declare function isFeatureEnabled(overrides: FeatureFlagOverrides | undefined, name: FeatureFlagName): boolean;
+/**
+ * Resolve the full effective flag map (defaults merged with overrides).
+ * Used by `/features` to show the current state of every flag.
+ */
+export declare function resolveFeatureFlags(overrides: FeatureFlagOverrides | undefined): Record<FeatureFlagName, boolean>;

package/dist/settings/feature-flags.js

@@ -0,0 +1,61 @@
+/**
+ * Feature Flags — a small, central on/off registry for opt-in or
+ * experimental behavior.
+ *
+ * Design goals:
+ *   - One source of truth for flag NAMES + their DEFAULT state, so a flag
+ *     can't be checked under a typo (the known set is a const).
+ *   - Settings-driven: `settings.featureFlags` is a `{ [name]: boolean }`
+ *     overlay over the defaults. Project settings override user settings the
+ *     same way every other settings field does (the SettingsManager merge),
+ *     so a flag can be flipped per-workspace.
+ *   - Forgiving read: `isFeatureEnabled` falls back to the default when a
+ *     flag is absent from settings, and ignores unknown flag names from
+ *     settings (forward-compat with older binaries).
+ *
+ * This is the knob layer only — each consumer still has to CHECK its flag.
+ * The `/features` command (CLI) reads/writes this same map.
+ */
+/** Canonical flag names. Add new flags here so checks stay typo-safe. */
+export const FEATURE_FLAGS = {
+    /** Web search tool availability (also gated by a configured provider). */
+    web_search: { default: true, description: "Enable the WebSearch tool" },
+    /** The Bash/shell tool. Off → the model cannot run shell commands. */
+    shell_tool: { default: true, description: "Enable the Bash/shell tool" },
+    /** Fast-output mode for supported models. */
+    fast_mode: { default: false, description: "Faster streaming output on supported models" },
+    /** Undo system (file-operation backups + /undo). */
+    undo: { default: false, description: "Per-session file undo (/undo)" },
+    /** Shell snapshot: capture full stdout/stderr of commands. */
+    shell_snapshot: { default: false, description: "Capture full command stdout/stderr snapshots" },
+};
+/** All known flag names, for iteration (e.g. the /features listing). */
+export function featureFlagNames() {
+    return Object.keys(FEATURE_FLAGS);
+}
+/** True when `name` is a recognized flag (narrows an arbitrary string). */
+export function isKnownFeatureFlag(name) {
+    return Object.prototype.hasOwnProperty.call(FEATURE_FLAGS, name);
+}
+/**
+ * Resolve a flag's effective state: the settings overlay value when present
+ * and boolean, else the flag's compiled-in default. Unknown names → false
+ * (a check for a flag that doesn't exist is never "enabled").
+ */
+export function isFeatureEnabled(overrides, name) {
+    const override = overrides?.[name];
+    if (typeof override === "boolean")
+        return override;
+    return FEATURE_FLAGS[name].default;
+}
+/**
+ * Resolve the full effective flag map (defaults merged with overrides).
+ * Used by `/features` to show the current state of every flag.
+ */
+export function resolveFeatureFlags(overrides) {
+    const out = {};
+    for (const name of featureFlagNames()) {
+        out[name] = isFeatureEnabled(overrides, name);
+    }
+    return out;
+}

package/dist/settings/manager.d.ts

@@ -4,7 +4,46 @@
  * Priority: CLI flags > local > project > user > managed
  */
 import { type ValidatedSettings } from "./schema.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
+ * take effect — on some runtimes (e.g. Bun on macOS) `os.homedir()` is
+ * cached from the user database at process startup and ignores later
+ * `process.env.HOME` mutations.
+ */
+export declare function userHome(): string;
+/**
+ * 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 declare function isProtectedSettingKey(key: string): boolean;
+/**
+ * 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 declare function noRepoDir(): string;
 export type SettingsSourceName = "managed" | "user" | "project" | "local" | "flag";
+/**
+ * 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 declare const DANGEROUS_PROJECT_FIELDS: readonly ["permissions", "env", "localEnvironment", "hooks", "mcpServers"];
 /**
  * Which disk layers a SettingsManager is allowed to read.
  *   'full'     — managed + user (~/.code-shell) + project + local (host terminal entrypoints)
@@ -18,13 +57,49 @@ export type SettingsScope = "isolated" | "project" | "full";
 export declare class SettingsManager {
     private readonly cwd;
     private readonly scope;
+    /**
+     * 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.
+     */
+    private readonly projectTrusted;
     private sources;
     private merged;
-    constructor(cwd?: string, scope?: SettingsScope);
+    constructor(cwd?: string, scope?: SettingsScope, 
+    /**
+     * 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?: boolean);
     /**
      * Load settings from all sources.
      */
     load(flagOverrides?: Record<string, unknown>): ValidatedSettings;
+    /**
+     * 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.
+     */
+    private applyConfigMigration;
     /**
      * Get current effective settings.
      */
@@ -42,6 +117,31 @@ export declare class SettingsManager {
      * The merged cache is invalidated so the next get() picks up the change.
      */
     saveUserSetting(key: string, value: unknown): void;
+    /**
+     * Persist a single setting (dotted key path) to the PROJECT-level config
+     * file at ${cwd}/.code-shell/settings.json. This is where capabilityOverrides
+     * live — project overlays never touch the global user file. Atomic write +
+     * cache invalidation mirror saveUserSetting.
+     */
+    saveProjectSetting(key: string, value: unknown, cwd: string): void;
+    /**
+     * Delete a single dotted key from the PROJECT-level config file. Used to
+     * express "inherit" — we don't persist the literal "inherit"; we remove the
+     * override key. No-ops if the file or any intermediate segment is absent.
+     */
+    deleteProjectSetting(key: string, cwd: string): void;
+    /**
+     * Read ONE scope's raw settings file, validated but UNMERGED. Capability
+     * overlay math needs the project overlay and the user/global baseline
+     * separately — the merged get() collapses provenance and can't express
+     * tri-state inheritance. user → ~/.code-shell/settings.json, project →
+     * ${cwd}/.code-shell/settings.json. Only keys actually present in the file
+     * are returned (defaults are not synthesized), so an absent file → {}.
+     */
+    getForScope(scope: "user" | "project", cwd?: string): Partial<ValidatedSettings>;
+    private projectSettingsPath;
+    private readJsonObject;
+    private atomicWriteJson;
     private loadJsonFile;
     private deepMerge;
 }