@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/sources/adapters/mcp-resource.js

@@ -0,0 +1,41 @@
+import { truncateUtf8Text } from "../truncate-utf8.js";
+function serverOf(definition) {
+    const configured = definition.adapterConfig["server"];
+    if (typeof configured !== "string" || configured.trim() === "") {
+        throw new Error(`mcp-resource source "${definition.id}" requires adapterConfig.server`);
+    }
+    return configured.trim();
+}
+export function createMcpResourceAdapter(getManager) {
+    return {
+        kind: "mcp-resource",
+        async listScopes() {
+            return [{ id: "resources", label: "Resources" }];
+        },
+        async listResources(definition, scopeId) {
+            if (scopeId !== "resources")
+                return [];
+            const resources = await (await getManager()).listResources(serverOf(definition));
+            return resources.map((resource) => ({
+                id: resource.uri,
+                scopeId: "resources",
+                name: resource.name ?? resource.uri,
+            }));
+        },
+        async read(definition, resourceId, options) {
+            const text = await (await getManager()).readResource(serverOf(definition), resourceId, options.signal);
+            const truncated = truncateUtf8Text(text, options.maxBytes);
+            return {
+                resourceId,
+                ...truncated,
+            };
+        },
+    };
+}
+/** 生产默认：方法首次执行时才加载真 MCPManager，避免静态模块环。 */
+export function defaultMcpResourceAdapter() {
+    return createMcpResourceAdapter(async () => {
+        const { MCPManager } = await import("../../tool-system/mcp-manager.js");
+        return MCPManager.getInstance();
+    });
+}

package/dist/sources/adapters/mock.d.ts

@@ -0,0 +1,3 @@
+/** 本地 fake 源：2 scope / 3 resource，纵切 e2e 与 CI 的载体（DS-13）。 */
+import type { ConnectorAdapter } from "../adapter.js";
+export declare const mockAdapter: ConnectorAdapter;

package/dist/sources/adapters/mock.js

@@ -0,0 +1,29 @@
+import { truncateUtf8Text } from "../truncate-utf8.js";
+const RESOURCES = [
+    { id: "alpha/doc-1", scopeId: "alpha", name: "doc-1", text: "alpha doc one 内容" },
+    { id: "alpha/doc-2", scopeId: "alpha", name: "doc-2", text: "alpha doc two content" },
+    { id: "beta/note-1", scopeId: "beta", name: "note-1", text: "beta note one content" },
+];
+export const mockAdapter = {
+    kind: "mock",
+    async listScopes() {
+        return [
+            { id: "alpha", label: "Alpha" },
+            { id: "beta", label: "Beta" },
+        ];
+    },
+    async listResources(_definition, scopeId) {
+        return RESOURCES.filter((resource) => resource.scopeId === scopeId).map(({ text: _text, ...metadata }) => metadata);
+    },
+    async read(_definition, resourceId, options) {
+        const resource = RESOURCES.find((candidate) => candidate.id === resourceId);
+        if (!resource) {
+            throw new Error(`mock resource not found: ${resourceId}`);
+        }
+        const truncated = truncateUtf8Text(resource.text, options.maxBytes);
+        return {
+            resourceId,
+            ...truncated,
+        };
+    },
+};

package/dist/sources/binding.d.ts

@@ -0,0 +1,6 @@
+/** WorkspaceSourceBinding 的项目 settings 读写（原子，经 SettingsManager）。 */
+import type { SettingsManager } from "../settings/manager.js";
+import { type WorkspaceSourceBinding } from "./types.js";
+export declare function listBindings(sm: SettingsManager, cwd: string): WorkspaceSourceBinding[];
+export declare function bindSource(sm: SettingsManager, cwd: string, binding: WorkspaceSourceBinding): void;
+export declare function unbindSource(sm: SettingsManager, cwd: string, sourceId: string): void;

package/dist/sources/binding.js

@@ -0,0 +1,24 @@
+import { WorkspaceSourceBindingSchema } from "./types.js";
+export function listBindings(sm, cwd) {
+    try {
+        const raw = sm.getForScope("project", cwd).sources;
+        if (!Array.isArray(raw))
+            return [];
+        return raw
+            .map((binding) => WorkspaceSourceBindingSchema.safeParse(binding))
+            .filter((result) => result.success)
+            .map((result) => result.data);
+    }
+    catch {
+        return [];
+    }
+}
+export function bindSource(sm, cwd, binding) {
+    const parsed = WorkspaceSourceBindingSchema.parse(binding);
+    const rest = listBindings(sm, cwd).filter((item) => item.sourceId !== parsed.sourceId);
+    sm.saveProjectSetting("sources", [...rest, parsed], cwd);
+}
+export function unbindSource(sm, cwd, sourceId) {
+    const bindings = listBindings(sm, cwd).filter((binding) => binding.sourceId !== sourceId);
+    sm.saveProjectSetting("sources", bindings, cwd);
+}

package/dist/sources/catalog.d.ts

@@ -0,0 +1,6 @@
+import { type SourceDefinition } from "./types.js";
+export declare function sourceCatalogPath(): string;
+export declare function listSourceDefinitions(): SourceDefinition[];
+export declare function readSourceDefinition(id: string): SourceDefinition | undefined;
+export declare function saveSourceDefinition(definition: SourceDefinition): void;
+export declare function deleteSourceDefinition(id: string): void;

package/dist/sources/catalog.js

@@ -0,0 +1,64 @@
+/** 全局数据源目录：codeShellHome()/sources.json。损坏条目隔离，原子写。 */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { logger } from "../logging/logger.js";
+import { codeShellHome } from "../session/session-manager.js";
+import { SourceDefinitionSchema } from "./types.js";
+export function sourceCatalogPath() {
+    return join(codeShellHome(), "sources.json");
+}
+function load() {
+    const path = sourceCatalogPath();
+    if (!existsSync(path))
+        return [];
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        if (raw.version !== 1 || !Array.isArray(raw.sources))
+            return [];
+        const sources = [];
+        for (const entry of raw.sources) {
+            const parsed = SourceDefinitionSchema.safeParse(entry);
+            if (parsed.success) {
+                sources.push(parsed.data);
+            }
+            else {
+                logger.warn("sources.catalog_entry_invalid", {
+                    cat: "sources",
+                    entry: JSON.stringify(entry).slice(0, 200),
+                });
+            }
+        }
+        return sources;
+    }
+    catch (error) {
+        logger.warn("sources.catalog_unreadable", {
+            cat: "sources",
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return [];
+    }
+}
+function persist(sources) {
+    const path = sourceCatalogPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify({ version: 1, sources }, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    renameSync(tmp, path);
+}
+export function listSourceDefinitions() {
+    return load().sort((a, b) => a.id.localeCompare(b.id));
+}
+export function readSourceDefinition(id) {
+    return load().find((source) => source.id === id);
+}
+export function saveSourceDefinition(definition) {
+    const parsed = SourceDefinitionSchema.parse(definition);
+    const rest = load().filter((source) => source.id !== parsed.id);
+    persist([...rest, parsed]);
+}
+export function deleteSourceDefinition(id) {
+    persist(load().filter((source) => source.id !== id));
+}

package/dist/sources/context-summary.d.ts

@@ -0,0 +1,8 @@
+import type { SettingsManager } from "../settings/manager.js";
+import { type CredentialStatusFn } from "./resolve.js";
+export interface BuildSourcesContextSummaryInput {
+    cwd: string;
+    settings: SettingsManager;
+    credentialStatus?: CredentialStatusFn;
+}
+export declare function buildSourcesContextSummary(input: BuildSourcesContextSummaryInput): string;

package/dist/sources/context-summary.js

@@ -0,0 +1,13 @@
+import { defaultCredentialStatus } from "./credential-status.js";
+import { resolveEffectiveSourceAccess } from "./resolve.js";
+export function buildSourcesContextSummary(input) {
+    const sources = resolveEffectiveSourceAccess({
+        cwd: input.cwd,
+        settings: input.settings,
+        credentialStatus: input.credentialStatus ?? defaultCredentialStatus,
+    });
+    if (sources.length === 0)
+        return "";
+    const lines = sources.map(({ label, kind, status, scopes }) => `- ${label} (${kind}, ${status}): ${scopes.join(", ") || "(no scopes)"}`);
+    return `## Bound data sources\n${lines.join("\n")}`;
+}

package/dist/sources/credential-status.d.ts

@@ -0,0 +1,2 @@
+/** Probe global credential availability through renderer-safe metadata only. */
+export declare function defaultCredentialStatus(ref: string): "ok" | "missing" | "expired";

package/dist/sources/credential-status.js

@@ -0,0 +1,13 @@
+import { getCredentialAccess } from "../credentials/access.js";
+/** Probe global credential availability through renderer-safe metadata only. */
+export function defaultCredentialStatus(ref) {
+    const credential = getCredentialAccess().resolveMeta(undefined, ref, "full");
+    if (!credential)
+        return "missing";
+    if (credential.type === "oauth" &&
+        credential.oauthStatus?.state === "expired" &&
+        !credential.oauthStatus.hasRefreshToken) {
+        return "expired";
+    }
+    return "ok";
+}

package/dist/sources/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./catalog.js";
+export * from "./adapter.js";
+export * from "./adapters/mock.js";
+export * from "./adapters/local-files.js";
+export * from "./adapters/mcp-resource.js";
+export * from "./binding.js";
+export * from "./resolve.js";
+export * from "./credential-status.js";
+export * from "./context-summary.js";

package/dist/sources/index.js

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./catalog.js";
+export * from "./adapter.js";
+export * from "./adapters/mock.js";
+export * from "./adapters/local-files.js";
+export * from "./adapters/mcp-resource.js";
+export * from "./binding.js";
+export * from "./resolve.js";
+export * from "./credential-status.js";
+export * from "./context-summary.js";

package/dist/sources/resolve.d.ts

@@ -0,0 +1,28 @@
+/**
+ * EffectiveSourceAccess：binding × source.enabled × credential 状态求交，
+ * 默认 deny（ADR §1.3/§3）。`profile` 参数为 Profile 求交预留（ADR §6），
+ * 本期恒不传；接线时 effective = binding ∩ profile 声明，只能收窄。
+ */
+import type { SettingsManager } from "../settings/manager.js";
+import type { SourceDefinition } from "./types.js";
+export type SourceAccessStatus = "ok" | "dangling" | "unavailable";
+export type CredentialStatusFn = (ref: string) => "ok" | "missing" | "expired";
+export interface EffectiveSourceAccess {
+    sourceId: string;
+    label: string;
+    kind: string;
+    scopes: string[];
+    readPolicy: "ask" | "deny";
+    status: SourceAccessStatus;
+    definition?: SourceDefinition;
+}
+export interface ResolveSourceAccessInput {
+    cwd: string;
+    settings: SettingsManager;
+    credentialStatus: CredentialStatusFn;
+    /** Profile 求交预留（ADR §6）；本期不实现。 */
+    profile?: {
+        requiredSources?: string[];
+    };
+}
+export declare function resolveEffectiveSourceAccess(input: ResolveSourceAccessInput): EffectiveSourceAccess[];

package/dist/sources/resolve.js

@@ -0,0 +1,47 @@
+import { LOCAL_FILES_SOURCE_ID, listLocalFiles, localFilesSourceFor, } from "./adapters/local-files.js";
+import { listBindings } from "./binding.js";
+import { readSourceDefinition } from "./catalog.js";
+function statusOf(definition, credentialStatus) {
+    if (!definition)
+        return "dangling";
+    if (!definition.enabled)
+        return "unavailable";
+    if (definition.credentialRef && credentialStatus(definition.credentialRef) !== "ok") {
+        return "unavailable";
+    }
+    return "ok";
+}
+function definitionFor(binding, cwd) {
+    return binding.sourceId === LOCAL_FILES_SOURCE_ID
+        ? localFilesSourceFor(cwd)
+        : readSourceDefinition(binding.sourceId);
+}
+export function resolveEffectiveSourceAccess(input) {
+    const bindings = listBindings(input.settings, input.cwd);
+    const access = bindings.map((binding) => {
+        const definition = definitionFor(binding, input.cwd);
+        return {
+            sourceId: binding.sourceId,
+            label: definition?.label ?? binding.sourceId,
+            kind: definition?.kind ?? "unknown",
+            scopes: binding.scopes,
+            readPolicy: binding.readPolicy,
+            status: statusOf(definition, input.credentialStatus),
+            ...(definition ? { definition } : {}),
+        };
+    });
+    const hasImplicitLocalFiles = bindings.length > 0 || listLocalFiles(input.cwd).length > 0;
+    if (hasImplicitLocalFiles && !access.some((item) => item.sourceId === LOCAL_FILES_SOURCE_ID)) {
+        const definition = localFilesSourceFor(input.cwd);
+        access.push({
+            sourceId: definition.id,
+            label: definition.label,
+            kind: definition.kind,
+            scopes: ["uploads"],
+            readPolicy: "ask",
+            status: "ok",
+            definition,
+        });
+    }
+    return access;
+}

package/dist/sources/truncate-utf8.d.ts

@@ -0,0 +1,7 @@
+/** UTF-8-safe byte truncation shared by source adapters and the source tool boundary. */
+export interface TruncatedText {
+    text: string;
+    truncated: boolean;
+}
+export declare function truncateUtf8Bytes(buffer: Buffer, maxBytes: number): TruncatedText;
+export declare function truncateUtf8Text(text: string, maxBytes: number): TruncatedText;

package/dist/sources/truncate-utf8.js

@@ -0,0 +1,18 @@
+function normalizeByteLimit(maxBytes, byteLength) {
+    if (!Number.isFinite(maxBytes))
+        return 0;
+    return Math.max(0, Math.min(Math.trunc(maxBytes), byteLength));
+}
+export function truncateUtf8Bytes(buffer, maxBytes) {
+    const limit = normalizeByteLimit(maxBytes, buffer.byteLength);
+    if (buffer.byteLength <= limit) {
+        return { text: buffer.toString("utf8"), truncated: false };
+    }
+    let end = limit;
+    while (end > 0 && (buffer[end] & 0xc0) === 0x80)
+        end -= 1;
+    return { text: buffer.subarray(0, end).toString("utf8"), truncated: true };
+}
+export function truncateUtf8Text(text, maxBytes) {
+    return truncateUtf8Bytes(Buffer.from(text, "utf8"), maxBytes);
+}

package/dist/sources/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Workspace 数据源三层模型的数据定义。语义决策见
+ * docs/todo/workspace-datasource-binding-adr.md（ADR-1/2/4）。
+ * project settings 只存 binding（ref/scope/readPolicy），绝不存 secret。
+ */
+import { z } from "zod";
+export declare const SOURCE_ID_RE: RegExp;
+export declare const SOURCE_KINDS: readonly ["mock", "mcp-resource", "local-files"];
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+export declare const SourceDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<["mock", "mcp-resource", "local-files"]>;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    /** 按 kind 的 adapter 配置（如 mcp-resource: { server }）。 */
+    adapterConfig: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** 指向全局 CredentialStore 的 id；local-files/mock 不需要。 */
+    credentialRef: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    enabled: boolean;
+    kind: "mock" | "mcp-resource" | "local-files";
+    label: string;
+    adapterConfig: Record<string, unknown>;
+    description?: string | undefined;
+    credentialRef?: string | undefined;
+}, {
+    id: string;
+    kind: "mock" | "mcp-resource" | "local-files";
+    label: string;
+    enabled?: boolean | undefined;
+    description?: string | undefined;
+    adapterConfig?: Record<string, unknown> | undefined;
+    credentialRef?: string | undefined;
+}>;
+export type SourceDefinition = z.infer<typeof SourceDefinitionSchema>;
+export declare const WorkspaceSourceBindingSchema: z.ZodObject<{
+    sourceId: z.ZodString;
+    /** 显式勾选的 scope id；空数组 = 什么都不可见（不是"全部"）。 */
+    scopes: z.ZodArray<z.ZodString, "many">;
+    /** ask（默认，ReadSource 每次审批）| deny（只许 list metadata，禁读内容）。无 allow 档（ADR §1.2）。 */
+    readPolicy: z.ZodDefault<z.ZodEnum<["ask", "deny"]>>;
+}, "strip", z.ZodTypeAny, {
+    sourceId: string;
+    scopes: string[];
+    readPolicy: "deny" | "ask";
+}, {
+    sourceId: string;
+    scopes: string[];
+    readPolicy?: "deny" | "ask" | undefined;
+}>;
+export type WorkspaceSourceBinding = z.infer<typeof WorkspaceSourceBindingSchema>;
+/** adapter 返回的 scope/resource/content 形状（运行时对象，不落盘）。 */
+export interface SourceScope {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface SourceResourceMeta {
+    id: string;
+    scopeId: string;
+    name: string;
+    sizeBytes?: number;
+    mimeType?: string;
+}
+export interface SourceContent {
+    resourceId: string;
+    text: string;
+    truncated: boolean;
+}

package/dist/sources/types.js

@@ -0,0 +1,26 @@
+/**
+ * Workspace 数据源三层模型的数据定义。语义决策见
+ * docs/todo/workspace-datasource-binding-adr.md（ADR-1/2/4）。
+ * project settings 只存 binding（ref/scope/readPolicy），绝不存 secret。
+ */
+import { z } from "zod";
+export const SOURCE_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const SOURCE_KINDS = ["mock", "mcp-resource", "local-files"];
+export const SourceDefinitionSchema = z.object({
+    id: z.string().regex(SOURCE_ID_RE),
+    kind: z.enum(SOURCE_KINDS),
+    label: z.string().min(1),
+    description: z.string().optional(),
+    /** 按 kind 的 adapter 配置（如 mcp-resource: { server }）。 */
+    adapterConfig: z.record(z.unknown()).default({}),
+    /** 指向全局 CredentialStore 的 id；local-files/mock 不需要。 */
+    credentialRef: z.string().optional(),
+    enabled: z.boolean().default(true),
+});
+export const WorkspaceSourceBindingSchema = z.object({
+    sourceId: z.string().regex(SOURCE_ID_RE),
+    /** 显式勾选的 scope id；空数组 = 什么都不可见（不是"全部"）。 */
+    scopes: z.array(z.string()),
+    /** ask（默认，ReadSource 每次审批）| deny（只许 list metadata，禁读内容）。无 allow 档（ADR §1.2）。 */
+    readPolicy: z.enum(["ask", "deny"]).default("ask"),
+});

package/dist/testing/fetch-stub.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Test helper: build a stub that satisfies the FULL `typeof globalThis.fetch`.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Assigning a plain `async () => new Response(...)` to `globalThis.fetch` used
+ * to typecheck. Bun 1.3 added a static `fetch.preconnect(url)`, so the global's
+ * type now carries that property and every bare-function stub fails with:
+ *   Property 'preconnect' is missing in type '() => Promise<Response>'
+ *   but required in type 'typeof fetch'.
+ *
+ * The runtime behavior never changed — only the static surface. Rather than
+ * sprinkling `as unknown as typeof fetch` (which silences real mismatches too)
+ * at each site, attach the missing statics once, here. When a future runtime
+ * adds another property to `fetch`, this is the single place to update.
+ *
+ * Prefer narrowing the PRODUCTION type instead when the code under test only
+ * ever *calls* fetch — see `PanelAppArchiveFetch` in ../panel-apps/github-archive.ts.
+ * Use this helper only where the real global genuinely has to be replaced.
+ */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * Wrap a call-only fetch implementation so it is assignable to
+ * `globalThis.fetch`.
+ *
+ * ```ts
+ * const previous = globalThis.fetch;
+ * globalThis.fetch = asGlobalFetch(async () => new Response("ok"));
+ * try { … } finally { globalThis.fetch = previous; }
+ * ```
+ */
+export declare function asGlobalFetch(impl: FetchLike): typeof globalThis.fetch;

package/dist/testing/fetch-stub.js

@@ -0,0 +1,24 @@
+/**
+ * Wrap a call-only fetch implementation so it is assignable to
+ * `globalThis.fetch`.
+ *
+ * ```ts
+ * const previous = globalThis.fetch;
+ * globalThis.fetch = asGlobalFetch(async () => new Response("ok"));
+ * try { … } finally { globalThis.fetch = previous; }
+ * ```
+ */
+export function asGlobalFetch(impl) {
+    const stub = impl;
+    // `preconnect` is a no-op hint even in production; tests never assert on it.
+    if (typeof stub.preconnect !== "function") {
+        Object.defineProperty(stub, "preconnect", {
+            value: (_url) => {
+                /* no-op: connection warm-up is unobservable in tests */
+            },
+            configurable: true,
+            writable: true,
+        });
+    }
+    return stub;
+}

package/dist/themes/image.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Magic-number image validation for theme-pack assets. Mirrors the desktop
+ * plugin-media detector (PNG IHDR / JPEG SOF / WebP dimensions) and adds GIF so
+ * theme sprites can be animated: a theme pack's "motion" comes from the image
+ * format itself (APNG / animated WebP / GIF), never from executable content.
+ *
+ * We validate the true format by bytes (not by extension), enforce sane bounds,
+ * and return the canonical media type + extension the installer renames to.
+ */
+export type ThemeImageType = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+export interface ThemeImageInfo {
+    mediaType: ThemeImageType;
+    ext: "png" | "jpg" | "webp" | "gif";
+    width: number;
+    height: number;
+}
+/** Detect the true image type + dimensions from the first bytes, or null. */
+export declare function detectThemeImage(bytes: Buffer): ThemeImageInfo | null;

package/dist/themes/image.js

@@ -0,0 +1,117 @@
+/**
+ * Magic-number image validation for theme-pack assets. Mirrors the desktop
+ * plugin-media detector (PNG IHDR / JPEG SOF / WebP dimensions) and adds GIF so
+ * theme sprites can be animated: a theme pack's "motion" comes from the image
+ * format itself (APNG / animated WebP / GIF), never from executable content.
+ *
+ * We validate the true format by bytes (not by extension), enforce sane bounds,
+ * and return the canonical media type + extension the installer renames to.
+ */
+const MAX_DIMENSION = 8192;
+const MAX_PIXELS = 40_000_000;
+const EXT_BY_TYPE = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/webp": "webp",
+    "image/gif": "gif",
+};
+function jpegDimensions(bytes) {
+    if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return null;
+    let offset = 2;
+    while (offset + 4 <= bytes.length) {
+        while (offset < bytes.length && bytes[offset] === 0xff)
+            offset += 1;
+        if (offset >= bytes.length)
+            break;
+        const marker = bytes[offset];
+        offset += 1;
+        if (marker === 0xd8 ||
+            marker === 0xd9 ||
+            marker === 0x01 ||
+            (marker >= 0xd0 && marker <= 0xd7)) {
+            continue;
+        }
+        if (offset + 2 > bytes.length)
+            return null;
+        const length = bytes.readUInt16BE(offset);
+        if (length < 2 || offset + length > bytes.length)
+            return null;
+        const isStartOfFrame = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+        if (isStartOfFrame) {
+            if (length < 7)
+                return null;
+            return { width: bytes.readUInt16BE(offset + 5), height: bytes.readUInt16BE(offset + 3) };
+        }
+        offset += length;
+    }
+    return null;
+}
+function readUInt24LE(bytes, offset) {
+    return bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16);
+}
+function webpDimensions(bytes) {
+    if (bytes.length < 30 ||
+        bytes.toString("ascii", 0, 4) !== "RIFF" ||
+        bytes.toString("ascii", 8, 12) !== "WEBP" ||
+        bytes.readUInt32LE(4) + 8 > bytes.length) {
+        return null;
+    }
+    const chunk = bytes.toString("ascii", 12, 16);
+    if (chunk === "VP8X")
+        return { width: readUInt24LE(bytes, 24) + 1, height: readUInt24LE(bytes, 27) + 1 };
+    if (chunk === "VP8L" && bytes[20] === 0x2f) {
+        return {
+            width: 1 + (((bytes[22] & 0x3f) << 8) | bytes[21]),
+            height: 1 + (((bytes[24] & 0x0f) << 10) | (bytes[23] << 2) | (bytes[22] >> 6)),
+        };
+    }
+    if (chunk === "VP8 " && bytes[23] === 0x9d && bytes[24] === 0x01 && bytes[25] === 0x2a) {
+        return { width: bytes.readUInt16LE(26) & 0x3fff, height: bytes.readUInt16LE(28) & 0x3fff };
+    }
+    return null;
+}
+/** Detect the true image type + dimensions from the first bytes, or null. */
+export function detectThemeImage(bytes) {
+    let type = null;
+    let dims = null;
+    if (bytes.length >= 24 &&
+        bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) &&
+        bytes.readUInt32BE(8) === 13 &&
+        bytes.toString("ascii", 12, 16) === "IHDR") {
+        // PNG (and APNG, which shares the PNG signature — its acTL chunk just adds
+        // animation; we accept it as a valid PNG without needing to parse frames).
+        type = "image/png";
+        dims = { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+    }
+    else if (bytes.length >= 10 &&
+        (bytes.toString("ascii", 0, 6) === "GIF87a" || bytes.toString("ascii", 0, 6) === "GIF89a")) {
+        // GIF (may be animated) — logical screen dimensions are LE at offset 6.
+        type = "image/gif";
+        dims = { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+    }
+    else {
+        const jpeg = jpegDimensions(bytes);
+        if (jpeg) {
+            type = "image/jpeg";
+            dims = jpeg;
+        }
+        else {
+            const webp = webpDimensions(bytes);
+            if (webp) {
+                type = "image/webp";
+                dims = webp;
+            }
+        }
+    }
+    if (!type || !dims)
+        return null;
+    if (dims.width <= 0 ||
+        dims.height <= 0 ||
+        dims.width > MAX_DIMENSION ||
+        dims.height > MAX_DIMENSION ||
+        dims.width * dims.height > MAX_PIXELS) {
+        return null;
+    }
+    return { mediaType: type, ext: EXT_BY_TYPE[type], width: dims.width, height: dims.height };
+}

package/dist/themes/index.d.ts

@@ -0,0 +1,4 @@
+export { previewLocalTheme, installReviewedLocalTheme, listInstalledThemes, uninstallTheme, type ThemePreview, type InstalledTheme, } from "./installer.js";
+export { THEME_ASSET_DIR, ThemeInstallError, ThemeReviewChangedError, assertSafeThemeName, themeInstallDir, themesRoot, } from "./paths.js";
+export { THEME_VAR_NAMES, THEME_ID, parseThemeManifest, type ThemeManifest } from "./manifest.js";
+export { detectThemeImage, type ThemeImageInfo } from "./image.js";

package/dist/themes/index.js

@@ -0,0 +1,4 @@
+export { previewLocalTheme, installReviewedLocalTheme, listInstalledThemes, uninstallTheme, } from "./installer.js";
+export { THEME_ASSET_DIR, ThemeInstallError, ThemeReviewChangedError, assertSafeThemeName, themeInstallDir, themesRoot, } from "./paths.js";
+export { THEME_VAR_NAMES, THEME_ID, parseThemeManifest } from "./manifest.js";
+export { detectThemeImage } from "./image.js";