@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/settings/schema.js

@@ -0,0 +1,246 @@
+/**
+ * Settings schema with Zod validation.
+ */
+import { z } from "zod";
+export const SettingsSchema = z
+    .object({
+    agent: z
+        .object({
+        // Use z.string() instead of z.enum() to allow custom presets registered via registerPreset()
+        preset: z.string().default("terminal-coding"),
+        enabledBuiltinTools: z.array(z.string()).default([]),
+        disabledBuiltinTools: z.array(z.string()).default([]),
+        customSystemPrompt: z.string().optional(),
+        appendSystemPrompt: z.string().optional(),
+    })
+        .default({}),
+    /**
+     * Primary source of truth for the active model is settings.activeKey
+     * (points at models[].key). settings.model is a derived mirror of that
+     * entry kept in sync for legacy boot paths (cli/main.ts, repl.ts, etc.)
+     * which read provider/name/apiKey/baseUrl directly. Writers must update
+     * both — appendOnboardingResult does this in one shot.
+     */
+    activeKey: z.string().optional(),
+    /**
+     * Toggle background auto-update. When true (default), code-shell checks
+     * npm for newer versions and — if the npm global prefix is writable —
+     * installs the update in the background on process exit so the next
+     * launch picks it up.
+     * Can also be disabled via env var `DISABLE_AUTOUPDATER=1`.
+     */
+    autoUpdates: z.boolean().default(true),
+    model: z
+        .object({
+        provider: z.string().default("openai"),
+        name: z.string().default("anthropic/claude-opus-4-6"),
+        apiKey: z.string().optional(),
+        baseUrl: z.string().default("https://openrouter.ai/api/v1"),
+        temperature: z.number().min(0).max(2).default(0.3),
+        maxTokens: z.number().default(8192),
+    })
+        .default({}),
+    providers: z
+        .array(z.object({
+        key: z.string(),
+        label: z.string().optional(),
+        kind: z.enum([
+            "openai",
+            "anthropic",
+            "deepseek",
+            "zai",
+            "xai",
+            "mistral",
+            "groq",
+            "google",
+            "openrouter",
+            "ollama",
+            "custom",
+        ]),
+        baseUrl: z.string(),
+        apiKey: z.string().optional(),
+        protocol: z.enum(["openai-compat", "anthropic-style"]).optional(),
+        modelsPath: z.string().optional(),
+        /**
+         * DeepSeek V4 thinking-mode default for this provider. "enabled"
+         * matches endpoint default; "disabled" makes V4 calls run in
+         * non-thinking mode (faster, cheaper). Ignored by every provider
+         * other than DeepSeek V4. Per-call overrides still win.
+         */
+        thinking: z.enum(["enabled", "disabled"]).optional(),
+    }))
+        .default([]),
+    models: z
+        .array(z
+        .object({
+        key: z.string(),
+        label: z.string().optional(),
+        providerKey: z.string().optional(),
+        model: z.string(),
+        maxOutputTokens: z.number().optional(),
+        maxContextTokens: z.number().optional(),
+        /**
+         * Which LLM client to use ("openai" or "anthropic"). New name —
+         * the legacy field is `provider`, which we still accept and
+         * fold into `protocol` below so old configs keep working.
+         * NOT the brand/vendor — that's providerKey above.
+         */
+        protocol: z.string().optional(),
+        provider: z.string().optional(),
+        baseUrl: z.string().optional(),
+        apiKey: z.string().optional(),
+        /**
+         * Per-model thinking override. Wins over the provider-level
+         * setting (settings.providers[].thinking). Use this when
+         * different models under the same provider need different
+         * defaults — e.g. DeepSeek V4 Pro off (faster) but V4 Flash on.
+         */
+        thinking: z.enum(["enabled", "disabled"]).optional(),
+    })
+        .transform((m) => {
+        // Normalize: prefer `protocol`; fall back to legacy `provider`.
+        // We keep `provider` populated as a mirror because engine code
+        // and a few downstream readers still query it directly.
+        const effective = m.protocol ?? m.provider;
+        return {
+            ...m,
+            protocol: effective,
+            provider: effective,
+        };
+    }))
+        .default([]),
+    permissions: z
+        .object({
+        defaultMode: z
+            .enum(["default", "acceptEdits", "dontAsk", "bypassPermissions", "auto", "plan"])
+            .default("default"),
+        rules: z
+            .array(z.object({
+            tool: z.string(),
+            argsPattern: z.record(z.string()).optional(),
+            decision: z.enum(["allow", "deny", "ask"]),
+            reason: z.string().optional(),
+        }))
+            .default([]),
+    })
+        .default({}),
+    context: z
+        .object({
+        maxTokens: z.number().default(200_000),
+        compactAtRatio: z.number().default(0.6),
+        summarizeAtRatio: z.number().default(0.8),
+    })
+        .default({}),
+    session: z
+        .object({
+        storageDir: z.string().optional(),
+        maxHistory: z.number().default(100),
+    })
+        .default({}),
+    mcpServers: z
+        .record(z.object({
+        name: z.string(),
+        command: z.string().optional(),
+        args: z.array(z.string()).optional(),
+        env: z.record(z.string()).optional(),
+        url: z.string().optional(),
+        transport: z.enum(["stdio", "sse", "streamable-http", "inprocess"]).optional(),
+        headers: z.record(z.string()).optional(),
+    }))
+        .default({}),
+    /**
+     * Skill names hidden from the LLM. Names include the full
+     * "<plugin>:<skill>" prefix for plugin skills. Filtered at the
+     * scanner so PromptComposer's skills listing and the skill builtin
+     * tool both see the filtered set — see scanSkills(opts).
+     */
+    disabledSkills: z.array(z.string()).default([]),
+    instructions: z
+        .object({
+        fileName: z.string().default("CODESHELL.md"),
+        scanDirs: z.array(z.string()).default([]),
+        compatFileNames: z.array(z.string()).default(["CLAUDE.md", "AGENTS.md"]),
+        ignoreGitBoundary: z.boolean().default(false),
+    })
+        .default({}),
+    arena: z
+        .object({
+        participants: z
+            .array(z.union([
+            // Short form: just a model pool key
+            z.string(),
+            // Full form: explicit config (backward compat)
+            z.object({
+                name: z.string(),
+                model: z.string(),
+                provider: z.string().optional(),
+                apiKey: z.string().optional(),
+                baseUrl: z.string().optional(),
+            }),
+        ]))
+            .default([]),
+    })
+        .default({}),
+    search: z
+        .object({
+        provider: z.enum(["serper", "tavily", "searxng"]).default("serper"),
+        apiKey: z.string().optional(),
+        baseUrl: z.string().optional(),
+        /**
+         * Per-provider credentials bag. Lets the desktop UI keep
+         * Serper/Tavily/SearXNG configured simultaneously and flip the
+         * default without losing the others. `provider/apiKey/baseUrl`
+         * remain authoritative for the *active* provider so legacy
+         * readers keep working.
+         */
+        providers: z
+            .record(z.enum(["serper", "tavily", "searxng"]), z.object({
+            apiKey: z.string().optional(),
+            baseUrl: z.string().optional(),
+        }))
+            .optional(),
+    })
+        .default({}),
+    output: z
+        .object({
+        format: z.enum(["text", "json", "jsonl", "stream-json"]).default("text"),
+    })
+        .default({}),
+    /**
+     * OS-level sandbox for shell-tool execution. "auto" picks per platform:
+     * Seatbelt on macOS, bubblewrap on Linux when installed, otherwise off.
+     * Defaults are applied per Engine run depending on headless vs REPL —
+     * see Engine.run() and run.ts.
+     */
+    sandbox: z
+        .object({
+        mode: z.enum(["off", "auto", "seatbelt", "bwrap"]).optional(),
+        writableRoots: z.array(z.string()).optional(),
+        deniedReads: z.array(z.string()).optional(),
+        network: z.enum(["allow", "deny"]).optional(),
+    })
+        .optional(),
+    /**
+     * Shell-hook configuration. Each entry binds a HookEventName to a
+     * shell command; the command receives ctx JSON on stdin and returns
+     * a HookResult JSON on stdout (or exit 2 = deny with stderr as
+     * reason). See src/hooks/shell-runner.ts for the wire protocol.
+     *
+     * The event field is loose-typed here (z.string()) because adding
+     * new lifecycle events shouldn't force a schema bump; the runner
+     * silently ignores entries whose event isn't registered.
+     */
+    hooks: z
+        .array(z.object({
+        event: z.string(),
+        command: z.string().min(1),
+        matcher: z.string().optional(),
+        timeout_ms: z.number().int().positive().optional(),
+        cwd: z.string().optional(),
+    }))
+        .optional(),
+})
+    .passthrough();
+export function validateSettings(raw) {
+    return SettingsSchema.parse(raw);
+}

package/dist/skills/frontmatter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Frontmatter parser for SKILL.md files. Byte-compatible with Claude Code's
+ * `utils/frontmatterParser.ts` so community skill repositories can be reused
+ * without modification.
+ */
+export declare const FRONTMATTER_REGEX: RegExp;
+export interface ParsedFrontmatter {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export declare function parseFrontmatter(raw: string): ParsedFrontmatter;
+export declare function quoteProblematicValues(frontmatterText: string): string;
+export declare function coerceDescription(value: unknown): string;

package/dist/skills/frontmatter.js

@@ -0,0 +1,70 @@
+/**
+ * Frontmatter parser for SKILL.md files. Byte-compatible with Claude Code's
+ * `utils/frontmatterParser.ts` so community skill repositories can be reused
+ * without modification.
+ */
+import { parse as parseYaml } from "yaml";
+export const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)---\s*\n?/;
+const YAML_SPECIAL_CHARS = /[{}[\]*&#!|>%@`]|: /;
+export function parseFrontmatter(raw) {
+    const match = raw.match(FRONTMATTER_REGEX);
+    if (!match) {
+        return { frontmatter: {}, body: raw };
+    }
+    const text = match[1] ?? "";
+    const body = raw.slice(match[0].length);
+    let parsed;
+    try {
+        parsed = parseYaml(text);
+    }
+    catch {
+        try {
+            parsed = parseYaml(quoteProblematicValues(text));
+        }
+        catch {
+            return { frontmatter: {}, body };
+        }
+    }
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return { frontmatter: parsed, body };
+    }
+    return { frontmatter: {}, body };
+}
+export function quoteProblematicValues(frontmatterText) {
+    const lines = frontmatterText.split("\n");
+    const result = [];
+    for (const line of lines) {
+        const m = line.match(/^([a-zA-Z_-]+):\s+(.+)$/);
+        if (!m) {
+            result.push(line);
+            continue;
+        }
+        const key = m[1];
+        const value = m[2];
+        if (!key || !value) {
+            result.push(line);
+            continue;
+        }
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            result.push(line);
+            continue;
+        }
+        if (YAML_SPECIAL_CHARS.test(value)) {
+            const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+            result.push(`${key}: "${escaped}"`);
+            continue;
+        }
+        result.push(line);
+    }
+    return result.join("\n");
+}
+export function coerceDescription(value) {
+    if (value == null)
+        return "";
+    if (typeof value === "string")
+        return value.trim();
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return "";
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Skills barrel. Phase A keeps the scanner only. Listing rendering lives in
+ * src/tool-system/builtin/skill-prompt.ts so the prompt-formatting layer can
+ * grow token-budget logic later without churn here.
+ */
+export { scanSkills, invalidateSkillCache } from "./scanner.js";
+export type { SkillDefinition } from "./scanner.js";

package/dist/skills/index.js

@@ -0,0 +1,6 @@
+/**
+ * Skills barrel. Phase A keeps the scanner only. Listing rendering lives in
+ * src/tool-system/builtin/skill-prompt.ts so the prompt-formatting layer can
+ * grow token-budget logic later without churn here.
+ */
+export { scanSkills, invalidateSkillCache } from "./scanner.js";

package/dist/skills/scanner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Skill scanner — discovers <base>/<name>/SKILL.md files from project + user
+ * directories AND from installed plugins. Mirrors Claude Code's
+ * `loadSkillsFromSkillsDir` (skills/loadSkillsDir.ts:407) plus plugin
+ * integration (utils/plugins/pluginLoader.ts).
+ */
+export interface SkillDefinition {
+    /** Directory name; authoritative regardless of frontmatter.name. */
+    name: string;
+    /** From frontmatter.description, coerced. Empty string if absent or invalid. */
+    description: string;
+    /** SKILL.md body with frontmatter stripped. */
+    content: string;
+    /** Absolute path to the SKILL.md file. */
+    filePath: string;
+    /** Where the skill was loaded from. */
+    source: "project" | "user" | "plugin";
+}
+/**
+ * Options accepted by scanSkills. The disabled-skill filter is applied
+ * after the memoized scan returns so the cache stays warm across
+ * different filter values — changing `settings.disabledSkills` should
+ * never force a re-scan. Names in `disabledSkills` must match the
+ * SkillDefinition.name exactly, including any "<plugin>:" prefix —
+ * see scanInstalledPlugins() at line ~168 for namespace construction.
+ */
+export interface ScanSkillsOptions {
+    disabledSkills?: string[];
+}
+export declare function scanSkills(cwd: string, opts?: ScanSkillsOptions): SkillDefinition[];
+export declare function invalidateSkillCache(): void;

package/dist/skills/scanner.js

@@ -0,0 +1,171 @@
+/**
+ * Skill scanner — discovers <base>/<name>/SKILL.md files from project + user
+ * directories AND from installed plugins. Mirrors Claude Code's
+ * `loadSkillsFromSkillsDir` (skills/loadSkillsDir.ts:407) plus plugin
+ * integration (utils/plugins/pluginLoader.ts).
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { memoize } from "../utils/memoize.js";
+import { parseFrontmatter, coerceDescription } from "./frontmatter.js";
+import { installedPluginsPath, readInstalledPlugins } from "../plugins/installedPlugins.js";
+function userHome() {
+    // Honor process.env.HOME so tests (and shell overrides) can redirect the
+    // user-skills lookup. node:os homedir() reads from getpwuid and ignores
+    // later mutations of process.env.HOME, which is what the test suite relies
+    // on. Falls back to homedir() when HOME is unset.
+    return process.env.HOME ?? homedir();
+}
+function bases(cwd) {
+    return [
+        { dir: join(cwd, ".code-shell", "skills"), source: "project" },
+        { dir: join(userHome(), ".code-shell", "skills"), source: "user" },
+    ];
+}
+function isENOENT(e) {
+    return (typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT");
+}
+function isInaccessible(e) {
+    if (typeof e !== "object" || e === null || !("code" in e))
+        return false;
+    const code = e.code;
+    return code === "EACCES" || code === "EPERM" || code === "EIO";
+}
+function readSkillFile(skillFile) {
+    try {
+        return readFileSync(skillFile, "utf-8");
+    }
+    catch (e) {
+        if (isENOENT(e))
+            return null;
+        if (isInaccessible(e)) {
+            // eslint-disable-next-line no-console
+            console.warn(`[skills] cannot read ${skillFile}: ${e.message}`);
+            return null;
+        }
+        throw e;
+    }
+}
+function buildSkillFromFile(filePath, defaultName, source, raw, namePrefix) {
+    const { frontmatter, body } = parseFrontmatter(raw);
+    const fmName = typeof frontmatter.name === "string" ? frontmatter.name : undefined;
+    if (fmName !== undefined && fmName !== defaultName) {
+        // eslint-disable-next-line no-console
+        console.warn(`[skills] frontmatter.name "${fmName}" in ${filePath} does not match directory name "${defaultName}"; using directory name`);
+    }
+    const description = coerceDescription(frontmatter.description);
+    const name = namePrefix ? `${namePrefix}:${defaultName}` : defaultName;
+    return { name, description, content: body, filePath, source };
+}
+function scanDirBases(bases, results, seen, seenBaseDirs) {
+    for (const { dir, source } of bases) {
+        if (!existsSync(dir))
+            continue;
+        let realDir;
+        try {
+            realDir = realpathSync(dir);
+        }
+        catch {
+            continue;
+        }
+        if (seenBaseDirs.has(realDir))
+            continue;
+        seenBaseDirs.add(realDir);
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch (e) {
+            if (isInaccessible(e)) {
+                // eslint-disable-next-line no-console
+                console.warn(`[skills] cannot read ${dir}: ${e.message}`);
+                continue;
+            }
+            throw e;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
+                continue;
+            if (seen.has(entry.name))
+                continue;
+            const skillFile = join(dir, entry.name, "SKILL.md");
+            const raw = readSkillFile(skillFile);
+            if (raw === null)
+                continue;
+            results.push(buildSkillFromFile(skillFile, entry.name, source, raw));
+            seen.add(entry.name);
+        }
+    }
+}
+function scanInstalledPlugins(results) {
+    const data = readInstalledPlugins();
+    const pluginSeen = new Set();
+    // Stable order so /skills output is deterministic.
+    const keys = Object.keys(data.plugins).sort();
+    for (const key of keys) {
+        const entries = data.plugins[key] ?? [];
+        // <plugin>@<marketplace>
+        const atIdx = key.lastIndexOf("@");
+        const pluginName = atIdx > 0 ? key.slice(0, atIdx) : key;
+        for (const entry of entries) {
+            const skillsDir = join(entry.installPath, "skills");
+            if (!existsSync(skillsDir))
+                continue;
+            let dirEntries;
+            try {
+                dirEntries = readdirSync(skillsDir, { withFileTypes: true });
+            }
+            catch (e) {
+                if (isInaccessible(e)) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[skills] cannot read ${skillsDir}: ${e.message}`);
+                    continue;
+                }
+                throw e;
+            }
+            for (const dirent of dirEntries) {
+                if (!dirent.isDirectory() && !dirent.isSymbolicLink())
+                    continue;
+                const namespacedName = `${pluginName}:${dirent.name}`;
+                if (pluginSeen.has(namespacedName))
+                    continue;
+                const skillFile = join(skillsDir, dirent.name, "SKILL.md");
+                const raw = readSkillFile(skillFile);
+                if (raw === null)
+                    continue;
+                results.push(buildSkillFromFile(skillFile, dirent.name, "plugin", raw, pluginName));
+                pluginSeen.add(namespacedName);
+            }
+        }
+    }
+}
+function scanOnce(cwd) {
+    const results = [];
+    const seen = new Set();
+    const seenBaseDirs = new Set();
+    scanDirBases(bases(cwd), results, seen, seenBaseDirs);
+    scanInstalledPlugins(results);
+    return results;
+}
+function installedPluginsMtime() {
+    const p = installedPluginsPath();
+    try {
+        return statSync(p).mtimeMs.toString();
+    }
+    catch {
+        return "0";
+    }
+}
+const memoized = memoize(scanOnce, (cwd) => `${cwd}\0${userHome()}\0${installedPluginsMtime()}`);
+export function scanSkills(cwd, opts) {
+    const all = memoized(cwd);
+    const disabled = opts?.disabledSkills;
+    if (!disabled || disabled.length === 0)
+        return all;
+    const set = new Set(disabled);
+    return all.filter((s) => !set.has(s.name));
+}
+export function invalidateSkillCache() {
+    memoized.cache.clear?.();
+}