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

package/dist/model-catalog/index.js

@@ -0,0 +1,90 @@
+/**
+ * Model catalog assembly — merge built-in (A) + user (B) templates.
+ *
+ * - A: {@link BUILTIN_CATALOG} (ships with the app).
+ * - B: ~/.code-shell/model-catalog.user.json (user-added templates).
+ * - merge: union by `id`; same id → user B wins (so升级 doesn't clobber the
+ *   user's overrides/additions).
+ *
+ * No remote source this version (design doc §5).
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { userHome } from "../settings/manager.js";
+import { logger } from "../logging/logger.js";
+import { BUILTIN_CATALOG } from "./builtin.js";
+import { userCatalogFileSchema } from "./types.js";
+export { BUILTIN_CATALOG } from "./builtin.js";
+export { saveCatalogEntry, deleteUserCatalogEntry } from "./save-entry.js";
+/** Path to the user catalog file (source B). */
+export function userCatalogPath() {
+    return join(userHome(), ".code-shell", "model-catalog.user.json");
+}
+/**
+ * Load user-defined catalog entries (source B). Returns [] when the file is
+ * absent or invalid — a bad user file must never break the built-in catalog.
+ */
+export function loadUserCatalog() {
+    const path = userCatalogPath();
+    if (!existsSync(path))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        const result = userCatalogFileSchema.safeParse(parsed);
+        if (!result.success) {
+            logger.warn("model_catalog_user_invalid", { path, issues: result.error.issues.length });
+            return [];
+        }
+        return result.data;
+    }
+    catch (err) {
+        logger.warn("model_catalog_user_read_failed", { path, error: err.message });
+        return [];
+    }
+}
+/**
+ * Merged catalog: built-in (A) ∪ user (B), deduped by `id` with user winning.
+ * This is the single source the 连接 page renders from and the tool-description
+ * injector looks up `paramsDoc` in.
+ */
+export function getMergedCatalog() {
+    const byId = new Map();
+    for (const e of BUILTIN_CATALOG)
+        byId.set(e.id, e);
+    for (const e of loadUserCatalog())
+        byId.set(e.id, e); // user overrides built-in
+    return [...byId.values()];
+}
+/**
+ * Look up a catalog entry by id (e.g. an instance's `catalogId`), falling back
+ * to the first entry whose `adapterKind` matches `kindFallback`. Since an
+ * adapterKind (e.g. "openai") can now back both a text and an image entry,
+ * `tagFallback` disambiguates the fallback to the right group.
+ */
+export function findCatalogEntry(catalog, id, kindFallback, tagFallback) {
+    if (id) {
+        const exact = catalog.find((e) => e.id === id);
+        if (exact)
+            return exact;
+    }
+    if (kindFallback) {
+        return catalog.find((e) => e.adapterKind === kindFallback && (!tagFallback || e.tag === tagFallback));
+    }
+    return undefined;
+}
+/**
+ * Per-id provenance of the merged catalog: pure built-in, pure user-added, or a
+ * user override of a built-in. Lets the editor UI show 编辑/删除/重置 correctly
+ * (only an override can be "reset"; only a user-only entry can be truly deleted).
+ */
+export function catalogEntryOrigins() {
+    const builtinIds = new Set(BUILTIN_CATALOG.map((e) => e.id));
+    const userIds = new Set(loadUserCatalog().map((e) => e.id));
+    const out = {};
+    for (const id of builtinIds)
+        out[id] = userIds.has(id) ? "user-override-of-builtin" : "builtin";
+    for (const id of userIds)
+        if (!builtinIds.has(id))
+            out[id] = "user";
+    return out;
+}

package/dist/model-catalog/params.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Param projection — the two halves of the "one declaration drives both" goal:
+ *  - applyParams: user's chosen values → request-body fields (via wire.field).
+ *  - buildParamsDoc: the param specs → a natural-language note injected into the
+ *    tool description so the agent knows what a configured model accepts.
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §4/§6.
+ */
+import type { ParamSpec } from "./types.js";
+/**
+ * Project `values` onto a request-body fragment using each spec's wire.field
+ * (falling back to the param name). A dotted field ("thinking.budget_tokens")
+ * nests. Values with no matching spec, and specs the user didn't set, are
+ * skipped.
+ */
+export declare function applyParams(values: Record<string, unknown>, params: ParamSpec[]): Record<string, unknown>;
+/**
+ * Build a natural-language note describing the params a model accepts, for
+ * injection into the tool description. Empty string when there are no params.
+ */
+export declare function buildParamsDoc(params: ParamSpec[] | undefined): string;

package/dist/model-catalog/params.js

@@ -0,0 +1,45 @@
+/**
+ * Project `values` onto a request-body fragment using each spec's wire.field
+ * (falling back to the param name). A dotted field ("thinking.budget_tokens")
+ * nests. Values with no matching spec, and specs the user didn't set, are
+ * skipped.
+ */
+export function applyParams(values, params) {
+    const body = {};
+    for (const spec of params) {
+        if (!(spec.name in values))
+            continue;
+        const value = values[spec.name];
+        if (value === undefined)
+            continue;
+        const field = spec.wire?.field ?? spec.name;
+        setDeep(body, field, value);
+    }
+    return body;
+}
+/** Set a (possibly dotted) path on an object, creating intermediate objects. */
+function setDeep(obj, path, value) {
+    const parts = path.split(".");
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        if (typeof cur[key] !== "object" || cur[key] === null)
+            cur[key] = {};
+        cur = cur[key];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+/**
+ * Build a natural-language note describing the params a model accepts, for
+ * injection into the tool description. Empty string when there are no params.
+ */
+export function buildParamsDoc(params) {
+    if (!params || params.length === 0)
+        return "";
+    const lines = params.map((p) => {
+        const opts = p.options && p.options.length > 0 ? ` (${p.options.join(" | ")})` : "";
+        const doc = p.doc ? ` — ${p.doc}` : "";
+        return `${p.name}${opts}${doc}`;
+    });
+    return lines.join("; ");
+}

package/dist/model-catalog/resolve.d.ts

@@ -0,0 +1,48 @@
+/**
+ * resolveInstance — single resolver every capability entry (chat /
+ * GenerateImage / GenerateVideo) goes through. Turns a stored ModelInstance +
+ * credentials + catalog into the runtime shape: which adapter, which key (from
+ * the referenced credential), which preset, which param values. text/image/
+ * video all share this — only adapterKind differs ("底层一套").
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §6.
+ */
+import { type CatalogEntry } from "./index.js";
+import type { ModelPreset } from "./types.js";
+/** An independent credential (mirrors settings.credentials[] entries). */
+export interface Credential {
+    id: string;
+    catalogId: string;
+    apiKey?: string;
+    baseUrl?: string;
+}
+/** A stored connection instance (mirrors settings.modelConnections[] entries). */
+export interface ModelInstance {
+    id: string;
+    catalogId: string;
+    tag: "text" | "image" | "video" | "audio";
+    model: string;
+    baseUrl?: string;
+    /** Which credential supplies the key (independent entity, shareable). */
+    credentialId?: string;
+    paramValues?: Record<string, unknown>;
+}
+export interface ResolvedInstance {
+    entry: CatalogEntry;
+    adapterKind: string;
+    baseUrl: string;
+    apiKey?: string;
+    /** Whether the catalog template requires a key (false = local/no-auth provider).
+     *  Surfaced so higher layers can tell "needs a key but has none" (a misconfig
+     *  worth a clear error) from "legitimately keyless". resolveInstance itself
+     *  still NEVER throws on a missing key — that no-crash contract is unchanged. */
+    needsKey: boolean;
+    preset?: ModelPreset;
+    model: string;
+    paramValues: Record<string, unknown>;
+}
+/**
+ * Resolve `inst` against the credential list (for its key) and `catalog`.
+ * Returns null when the instance's catalogId resolves to no entry.
+ * baseUrl precedence: connection override → credential → catalog default.
+ */
+export declare function resolveInstance(inst: ModelInstance, credentials: Credential[], catalog: CatalogEntry[]): ResolvedInstance | null;

package/dist/model-catalog/resolve.js

@@ -0,0 +1,33 @@
+/**
+ * resolveInstance — single resolver every capability entry (chat /
+ * GenerateImage / GenerateVideo) goes through. Turns a stored ModelInstance +
+ * credentials + catalog into the runtime shape: which adapter, which key (from
+ * the referenced credential), which preset, which param values. text/image/
+ * video all share this — only adapterKind differs ("底层一套").
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §6.
+ */
+import { findCatalogEntry } from "./index.js";
+/**
+ * Resolve `inst` against the credential list (for its key) and `catalog`.
+ * Returns null when the instance's catalogId resolves to no entry.
+ * baseUrl precedence: connection override → credential → catalog default.
+ */
+export function resolveInstance(inst, credentials, catalog) {
+    const entry = findCatalogEntry(catalog, inst.catalogId);
+    if (!entry)
+        return null;
+    const cred = inst.credentialId
+        ? credentials.find((c) => c.id === inst.credentialId)
+        : undefined;
+    const preset = entry.modelPresets?.find((p) => p.value === inst.model);
+    return {
+        entry,
+        adapterKind: entry.adapterKind,
+        baseUrl: inst.baseUrl ?? cred?.baseUrl ?? entry.defaultBaseUrl,
+        apiKey: cred?.apiKey,
+        needsKey: entry.needsKey !== false, // default-true: only an explicit false is keyless
+        preset,
+        model: inst.model,
+        paramValues: inst.paramValues ?? {},
+    };
+}

package/dist/model-catalog/save-entry.d.ts

@@ -0,0 +1,32 @@
+export interface SaveCatalogResult {
+    ok: boolean;
+    action?: "added" | "updated";
+    error?: string;
+    backup?: string;
+}
+/**
+ * @param stamp caller-supplied unique suffix for the backup filename. Pass a
+ *   timestamp/counter from the caller — core forbids Date.now() in some paths
+ *   and tests need determinism.
+ */
+export declare function saveCatalogEntry(entry: unknown, opts: {
+    path: string;
+    stamp: string;
+}): SaveCatalogResult;
+export interface DeleteCatalogResult {
+    ok: boolean;
+    removed: boolean;
+    error?: string;
+    backup?: string;
+}
+/**
+ * Remove the entry with `id` from the user catalog file. Mirrors saveCatalogEntry's
+ * backup + atomic-write safety. removed:false means the id wasn't in the user file
+ * (a pristine built-in entry, or simply absent). The built-in catalog is code,
+ * untouched — deleting a user override just lets getMergedCatalog fall back to the
+ * built-in version ("reset" semantics).
+ */
+export declare function deleteUserCatalogEntry(id: string, opts: {
+    path: string;
+    stamp: string;
+}): DeleteCatalogResult;

package/dist/model-catalog/save-entry.js

@@ -0,0 +1,104 @@
+/**
+ * saveCatalogEntry — backup + validate + upsert-write one CatalogEntry into a
+ * user catalog file. Safe: backs up any existing (even corrupt) file first,
+ * validates the entry against the schema, and only writes on success. The
+ * agent-facing catalog edit tool wraps this; key/credentials are NOT touched
+ * here (those go through the user's own Edit, by design).
+ * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §7.
+ */
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { catalogEntrySchema, userCatalogFileSchema } from "./types.js";
+import { upsertCatalogEntry } from "./upsert.js";
+/**
+ * @param stamp caller-supplied unique suffix for the backup filename. Pass a
+ *   timestamp/counter from the caller — core forbids Date.now() in some paths
+ *   and tests need determinism.
+ */
+export function saveCatalogEntry(entry, opts) {
+    // Validate the incoming entry first — never write a malformed catalog.
+    const parsed = catalogEntrySchema.safeParse(entry);
+    if (!parsed.success) {
+        return { ok: false, error: `invalid catalog entry: ${parsed.error.issues.map((i) => i.message).join("; ")}` };
+    }
+    const valid = parsed.data;
+    // Read + back up any existing file (even if corrupt — never silently lose it).
+    let current = [];
+    let backup;
+    if (existsSync(opts.path)) {
+        backup = `${opts.path}.bak-${opts.stamp}`;
+        try {
+            copyFileSync(opts.path, backup);
+        }
+        catch {
+            backup = undefined; // best-effort; don't abort the write on backup failure
+        }
+        try {
+            const raw = JSON.parse(readFileSync(opts.path, "utf-8"));
+            const safe = userCatalogFileSchema.safeParse(raw);
+            current = safe.success ? safe.data : [];
+        }
+        catch {
+            current = []; // corrupt → start fresh (original preserved in backup)
+        }
+    }
+    const action = current.some((e) => e.id === valid.id) ? "updated" : "added";
+    const next = upsertCatalogEntry(current, valid);
+    // Ensure the parent dir exists — a first-ever catalog write on a machine
+    // whose ~/.code-shell hasn't been created yet would otherwise throw ENOENT
+    // (the agent-facing tool wants a clean {ok:false} or a real write, not a crash).
+    try {
+        mkdirSync(dirname(opts.path), { recursive: true });
+    }
+    catch (e) {
+        return { ok: false, error: `could not create catalog directory: ${e instanceof Error ? e.message : String(e)}`, backup };
+    }
+    try {
+        writeFileSync(opts.path, JSON.stringify(next, null, 2));
+    }
+    catch (e) {
+        // IO error (perms / disk full / bad path): return a clean {ok:false} with the
+        // backup filename preserved, never let the throw escape past the tool's
+        // expected result shape (the original file is intact — we only upsert-wrote).
+        return { ok: false, error: `could not write catalog: ${e instanceof Error ? e.message : String(e)}`, backup };
+    }
+    return { ok: true, action, backup };
+}
+/**
+ * Remove the entry with `id` from the user catalog file. Mirrors saveCatalogEntry's
+ * backup + atomic-write safety. removed:false means the id wasn't in the user file
+ * (a pristine built-in entry, or simply absent). The built-in catalog is code,
+ * untouched — deleting a user override just lets getMergedCatalog fall back to the
+ * built-in version ("reset" semantics).
+ */
+export function deleteUserCatalogEntry(id, opts) {
+    if (!existsSync(opts.path))
+        return { ok: true, removed: false };
+    let backup = `${opts.path}.bak-${opts.stamp}`;
+    try {
+        copyFileSync(opts.path, backup);
+    }
+    catch {
+        backup = undefined;
+    }
+    let current = [];
+    try {
+        const raw = JSON.parse(readFileSync(opts.path, "utf-8"));
+        const safe = userCatalogFileSchema.safeParse(raw);
+        current = safe.success ? safe.data : [];
+    }
+    catch {
+        current = [];
+    }
+    const next = current.filter((e) => e.id !== id);
+    const removed = next.length !== current.length;
+    if (!removed)
+        return { ok: true, removed: false, backup };
+    try {
+        writeFileSync(opts.path, JSON.stringify(next, null, 2));
+    }
+    catch (e) {
+        return { ok: false, removed: false, error: `could not write catalog: ${e instanceof Error ? e.message : String(e)}`, backup };
+    }
+    return { ok: true, removed: true, backup };
+}