@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/themes/installer.d.ts

@@ -0,0 +1,50 @@
+type PetState = "idle" | "running" | "alert";
+type WallpaperMode = "light" | "dark";
+export interface ThemePreview {
+    id: string;
+    name: string;
+    version: string;
+    hasColors: boolean;
+    petStates: PetState[];
+    wallpaperModes: WallpaperMode[];
+    /** The pack's primary color (for the picker swatch), if it overrides one. */
+    swatch?: string;
+    /** Content digest bound to a subsequent install to detect mid-review changes. */
+    reviewToken: string;
+    warnings: string[];
+}
+/** An installed theme as the host exposes it to the renderer. */
+export interface InstalledTheme {
+    id: string;
+    name: string;
+    version: string;
+    colors: {
+        light: Record<string, string>;
+        dark: Record<string, string>;
+    };
+    pet: Partial<Record<PetState, string>> & {
+        walk?: string[];
+    };
+    wallpaper?: {
+        light?: string;
+        dark?: string;
+        opacity?: number;
+    };
+}
+/**
+ * Validate a theme pack directory and return a preview + review-token. Does not
+ * write anything. `sourceDir` is a directory (a zip is extracted to a temp dir
+ * by the caller before calling this).
+ */
+export declare function previewLocalTheme(sourceDir: string): Promise<ThemePreview>;
+/**
+ * Install a previously previewed theme. Re-validates and re-checks the token
+ * (rejecting mid-review changes), then atomically writes the theme to
+ * ~/.code-shell/themes/<id>/ and records it in the registry.
+ */
+export declare function installReviewedLocalTheme(sourceDir: string, reviewToken: string): Promise<InstalledTheme>;
+/** Read all installed themes (manifest re-read from disk), skipping broken ones. */
+export declare function listInstalledThemes(): Promise<InstalledTheme[]>;
+/** Remove an installed theme and its registry entry. */
+export declare function uninstallTheme(id: string): Promise<void>;
+export {};

package/dist/themes/installer.js

@@ -0,0 +1,290 @@
+/**
+ * Theme-pack installer: validate → normalize → atomically install a local theme
+ * pack into ~/.code-shell/themes/<id>/, and read/uninstall installed packs.
+ *
+ * Mirrors the plugin installer's discipline (safe names, canonical asset paths,
+ * review-token double-check, temp-dir + rename atomicity) but is deliberately
+ * self-contained and static-only: a theme pack is a manifest + images, never
+ * executable content, so there are no hooks/mcp/skills to approve.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { detectThemeImage } from "./image.js";
+import { parseThemeManifest } from "./manifest.js";
+import { THEME_ASSET_DIR, ThemeInstallError, ThemeReviewChangedError, assertSafeThemeName, themeInstallDir, themesRegistryPath, themesRoot, } from "./paths.js";
+const MANIFEST_FILE = ".cs-theme.json";
+const MAX_ASSET_BYTES = 8 * 1024 * 1024;
+async function readImageAsset(sourceDir, rel) {
+    const abs = resolve(sourceDir, rel);
+    if (!abs.startsWith(resolve(sourceDir) + "/") && abs !== resolve(sourceDir)) {
+        throw new ThemeInstallError(`asset escapes theme root: ${rel}`);
+    }
+    // The string check above stops literal traversal, but not a symlink INSIDE
+    // the pack pointing at an arbitrary file outside it. Resolve real paths and
+    // require the asset to physically live under the pack root, or a malicious
+    // pack could exfiltrate any readable file that happens to be a valid image.
+    let realRoot;
+    let realAbs;
+    try {
+        realRoot = await realpath(sourceDir);
+        realAbs = await realpath(abs);
+    }
+    catch {
+        throw new ThemeInstallError(`asset not found: ${rel}`);
+    }
+    if (realAbs !== realRoot && !realAbs.startsWith(realRoot + "/")) {
+        throw new ThemeInstallError(`asset escapes theme root via symlink: ${rel}`);
+    }
+    let info;
+    try {
+        info = await stat(realAbs);
+    }
+    catch {
+        throw new ThemeInstallError(`asset not found: ${rel}`);
+    }
+    if (!info.isFile())
+        throw new ThemeInstallError(`asset is not a file: ${rel}`);
+    if (info.size > MAX_ASSET_BYTES)
+        throw new ThemeInstallError(`asset too large: ${rel}`);
+    const bytes = await readFile(realAbs);
+    const detected = detectThemeImage(bytes);
+    if (!detected)
+        throw new ThemeInstallError(`asset is not a supported image: ${rel}`);
+    return { bytes, ext: detected.ext };
+}
+/** Collect the declared assets, validating each, into canonical-name mappings. */
+async function resolveAssets(sourceDir, manifest) {
+    const assets = [];
+    const bytesByName = new Map();
+    const add = async (rel, base) => {
+        if (!rel)
+            return;
+        const { bytes, ext } = await readImageAsset(sourceDir, rel);
+        const canonicalName = `${base}.${ext}`;
+        assets.push({ sourceRel: rel, canonicalName });
+        bytesByName.set(canonicalName, bytes);
+    };
+    await add(manifest.pet?.idle, "pet-idle");
+    await add(manifest.pet?.running, "pet-running");
+    await add(manifest.pet?.alert, "pet-alert");
+    for (let i = 0; i < (manifest.pet?.walk?.length ?? 0); i += 1) {
+        await add(manifest.pet.walk[i], `pet-walk-${i + 1}`);
+    }
+    await add(manifest.wallpaper?.light, "wallpaper-light");
+    await add(manifest.wallpaper?.dark, "wallpaper-dark");
+    return { assets, bytesByName };
+}
+/** Deterministic digest over manifest + every canonical asset's bytes. */
+function digestProjection(manifest, bytesByName) {
+    const hash = createHash("sha256");
+    hash.update(JSON.stringify(manifest));
+    for (const name of [...bytesByName.keys()].sort()) {
+        hash.update(name);
+        hash.update(bytesByName.get(name));
+    }
+    return hash.digest("hex");
+}
+async function loadManifest(sourceDir) {
+    let raw;
+    try {
+        raw = await readFile(join(sourceDir, MANIFEST_FILE), "utf-8");
+    }
+    catch {
+        throw new ThemeInstallError(`missing ${MANIFEST_FILE}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new ThemeInstallError(`${MANIFEST_FILE} is not valid JSON`);
+    }
+    return parseThemeManifest(json);
+}
+function previewOf(manifest, bytesByName, warnings) {
+    const petStates = ["idle", "running", "alert"].filter((s) => manifest.pet?.[s]);
+    const wallpaperModes = ["light", "dark"].filter((m) => manifest.wallpaper?.[m]);
+    return {
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        hasColors: Boolean((manifest.colors?.light && Object.keys(manifest.colors.light).length) ||
+            (manifest.colors?.dark && Object.keys(manifest.colors.dark).length)),
+        petStates: [...petStates],
+        wallpaperModes: [...wallpaperModes],
+        ...((manifest.colors?.light?.["--cs-primary"] ?? manifest.colors?.dark?.["--cs-primary"])
+            ? {
+                swatch: (manifest.colors?.light?.["--cs-primary"] ??
+                    manifest.colors?.dark?.["--cs-primary"]),
+            }
+            : {}),
+        reviewToken: digestProjection(manifest, bytesByName),
+        warnings,
+    };
+}
+/**
+ * Validate a theme pack directory and return a preview + review-token. Does not
+ * write anything. `sourceDir` is a directory (a zip is extracted to a temp dir
+ * by the caller before calling this).
+ */
+export async function previewLocalTheme(sourceDir) {
+    const manifest = await loadManifest(sourceDir);
+    assertSafeThemeName(manifest.id);
+    const warnings = [];
+    if (!manifest.colors && !manifest.pet && !manifest.wallpaper) {
+        warnings.push("theme declares no colors, pet sprites, or wallpaper");
+    }
+    const { bytesByName } = await resolveAssets(sourceDir, manifest);
+    return previewOf(manifest, bytesByName, warnings);
+}
+/**
+ * Install a previously previewed theme. Re-validates and re-checks the token
+ * (rejecting mid-review changes), then atomically writes the theme to
+ * ~/.code-shell/themes/<id>/ and records it in the registry.
+ */
+export async function installReviewedLocalTheme(sourceDir, reviewToken) {
+    const manifest = await loadManifest(sourceDir);
+    assertSafeThemeName(manifest.id);
+    const { assets, bytesByName } = await resolveAssets(sourceDir, manifest);
+    if (digestProjection(manifest, bytesByName) !== reviewToken)
+        throw new ThemeReviewChangedError();
+    const finalDir = themeInstallDir(manifest.id);
+    await mkdir(themesRoot(), { recursive: true, mode: 0o700 });
+    const staging = await mkdtemp(join(themesRoot(), `.tmp-${manifest.id}-`));
+    try {
+        // Rewrite the manifest to canonical asset paths, then stage assets.
+        const canonical = canonicalManifestFor(manifest, assets);
+        await writeFile(join(staging, MANIFEST_FILE), `${JSON.stringify(canonical, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        await mkdir(join(staging, THEME_ASSET_DIR), { recursive: true, mode: 0o700 });
+        for (const asset of assets) {
+            await writeFile(join(staging, THEME_ASSET_DIR, asset.canonicalName), bytesByName.get(asset.canonicalName), {
+                mode: 0o600,
+            });
+        }
+        await rm(finalDir, { recursive: true, force: true });
+        await rename(staging, finalDir);
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+    await appendRegistryEntry({
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        installedAt: Date.now(),
+    });
+    return toInstalledTheme(canonicalManifestFor(manifest, assets));
+}
+/** Canonical manifest stored on disk: asset fields point at THEME_ASSET_DIR/*. */
+function canonicalManifestFor(manifest, assets) {
+    const nameFor = (base) => assets.find((a) => a.canonicalName.startsWith(`${base}.`))?.canonicalName;
+    const rel = (base) => {
+        const n = nameFor(base);
+        return n ? `${THEME_ASSET_DIR}/${n}` : undefined;
+    };
+    const walk = (manifest.pet?.walk ?? [])
+        .map((_, i) => rel(`pet-walk-${i + 1}`))
+        .filter((p) => Boolean(p));
+    const pet = manifest.pet
+        ? {
+            ...(rel("pet-idle") ? { idle: rel("pet-idle") } : {}),
+            ...(rel("pet-running") ? { running: rel("pet-running") } : {}),
+            ...(rel("pet-alert") ? { alert: rel("pet-alert") } : {}),
+            ...(walk.length ? { walk } : {}),
+        }
+        : undefined;
+    const wallpaper = manifest.wallpaper
+        ? {
+            ...(rel("wallpaper-light") ? { light: rel("wallpaper-light") } : {}),
+            ...(rel("wallpaper-dark") ? { dark: rel("wallpaper-dark") } : {}),
+            ...(manifest.wallpaper.opacity !== undefined
+                ? { opacity: manifest.wallpaper.opacity }
+                : {}),
+        }
+        : undefined;
+    return {
+        schemaVersion: 1,
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        ...(manifest.colors ? { colors: manifest.colors } : {}),
+        ...(pet && Object.keys(pet).length ? { pet } : {}),
+        ...(wallpaper && Object.keys(wallpaper).length ? { wallpaper } : {}),
+    };
+}
+function toInstalledTheme(manifest) {
+    return {
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        colors: { light: manifest.colors?.light ?? {}, dark: manifest.colors?.dark ?? {} },
+        pet: {
+            ...(manifest.pet?.idle ? { idle: manifest.pet.idle } : {}),
+            ...(manifest.pet?.running ? { running: manifest.pet.running } : {}),
+            ...(manifest.pet?.alert ? { alert: manifest.pet.alert } : {}),
+            ...(manifest.pet?.walk?.length ? { walk: manifest.pet.walk } : {}),
+        },
+        ...(manifest.wallpaper ? { wallpaper: manifest.wallpaper } : {}),
+    };
+}
+async function readRegistry() {
+    try {
+        const raw = await readFile(themesRegistryPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.version === 1 && Array.isArray(parsed.themes))
+            return parsed;
+    }
+    catch {
+        /* missing/corrupt → empty */
+    }
+    return { version: 1, themes: [] };
+}
+async function writeRegistry(registry) {
+    await mkdir(dirname(themesRegistryPath()), { recursive: true, mode: 0o700 });
+    const tmp = `${themesRegistryPath()}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(registry, null, 2)}\n`, { mode: 0o600 });
+    await rename(tmp, themesRegistryPath());
+}
+async function appendRegistryEntry(entry) {
+    const registry = await readRegistry();
+    registry.themes = registry.themes.filter((t) => t.id !== entry.id);
+    registry.themes.push(entry);
+    await writeRegistry(registry);
+}
+/** Read all installed themes (manifest re-read from disk), skipping broken ones. */
+export async function listInstalledThemes() {
+    let ids;
+    try {
+        const entries = await readdir(themesRoot(), { withFileTypes: true });
+        ids = entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const themes = [];
+    for (const id of ids) {
+        try {
+            assertSafeThemeName(id);
+            const manifest = await loadManifest(themeInstallDir(id));
+            if (manifest.id !== id)
+                continue; // dir name must match manifest id
+            themes.push(toInstalledTheme(manifest));
+        }
+        catch {
+            /* skip a corrupt/foreign directory */
+        }
+    }
+    return themes;
+}
+/** Remove an installed theme and its registry entry. */
+export async function uninstallTheme(id) {
+    assertSafeThemeName(id);
+    await rm(themeInstallDir(id), { recursive: true, force: true });
+    const registry = await readRegistry();
+    registry.themes = registry.themes.filter((t) => t.id !== id);
+    await writeRegistry(registry);
+}

package/dist/themes/manifest.d.ts

@@ -0,0 +1,102 @@
+import { z } from "zod";
+/**
+ * Theme-pack manifest (`.cs-theme.json`) schema and validation.
+ *
+ * A pack may override app colors (a whitelisted subset of `--cs-*`, unitless
+ * HSL), supply per-state pet sprites, and a light/dark wallpaper. All three are
+ * optional — a pack can recolor only, reskin the pet only, etc. Image fields
+ * declare author-relative paths that the installer validates and renames to a
+ * canonical layout; the manifest here only checks shape, not the image bytes.
+ */
+/** Overridable CSS variables — must stay in sync with the renderer whitelist. */
+export declare const THEME_VAR_NAMES: readonly ["--cs-background", "--cs-foreground", "--cs-card", "--cs-card-foreground", "--cs-popover", "--cs-popover-foreground", "--cs-primary", "--cs-primary-foreground", "--cs-secondary", "--cs-secondary-foreground", "--cs-muted", "--cs-muted-foreground", "--cs-accent", "--cs-accent-foreground", "--cs-destructive", "--cs-destructive-foreground", "--cs-border", "--cs-input", "--cs-ring", "--cs-status-running", "--cs-status-ok", "--cs-status-warn", "--cs-status-err", "--cs-status-idle"];
+export declare const THEME_ID: RegExp;
+export declare const ThemeManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    colors: z.ZodOptional<z.ZodObject<{
+        light: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodString>, Record<string, string>, Record<string, string>>, Record<string, string>, Record<string, string>>>;
+        dark: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodString>, Record<string, string>, Record<string, string>>, Record<string, string>, Record<string, string>>>;
+    }, "strip", z.ZodTypeAny, {
+        light?: Record<string, string> | undefined;
+        dark?: Record<string, string> | undefined;
+    }, {
+        light?: Record<string, string> | undefined;
+        dark?: Record<string, string> | undefined;
+    }>>;
+    pet: z.ZodOptional<z.ZodObject<{
+        idle: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        running: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        alert: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        /** Ordered frames cycled while the widget is dragged (a "run" loop). */
+        walk: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        running?: string | undefined;
+        idle?: string | undefined;
+        alert?: string | undefined;
+        walk?: string[] | undefined;
+    }, {
+        running?: string | undefined;
+        idle?: string | undefined;
+        alert?: string | undefined;
+        walk?: string[] | undefined;
+    }>>;
+    wallpaper: z.ZodOptional<z.ZodObject<{
+        light: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        dark: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        light?: string | undefined;
+        dark?: string | undefined;
+        opacity?: number | undefined;
+    }, {
+        light?: string | undefined;
+        dark?: string | undefined;
+        opacity?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    version: string;
+    name: string;
+    schemaVersion: 1;
+    pet?: {
+        running?: string | undefined;
+        idle?: string | undefined;
+        alert?: string | undefined;
+        walk?: string[] | undefined;
+    } | undefined;
+    colors?: {
+        light?: Record<string, string> | undefined;
+        dark?: Record<string, string> | undefined;
+    } | undefined;
+    wallpaper?: {
+        light?: string | undefined;
+        dark?: string | undefined;
+        opacity?: number | undefined;
+    } | undefined;
+}, {
+    id: string;
+    version: string;
+    name: string;
+    schemaVersion: 1;
+    pet?: {
+        running?: string | undefined;
+        idle?: string | undefined;
+        alert?: string | undefined;
+        walk?: string[] | undefined;
+    } | undefined;
+    colors?: {
+        light?: Record<string, string> | undefined;
+        dark?: Record<string, string> | undefined;
+    } | undefined;
+    wallpaper?: {
+        light?: string | undefined;
+        dark?: string | undefined;
+        opacity?: number | undefined;
+    } | undefined;
+}>;
+export type ThemeManifest = z.infer<typeof ThemeManifestSchema>;
+/** Parse + validate a raw `.cs-theme.json` object. Throws ZodError on invalid input. */
+export declare function parseThemeManifest(raw: unknown): ThemeManifest;

package/dist/themes/manifest.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+/**
+ * Theme-pack manifest (`.cs-theme.json`) schema and validation.
+ *
+ * A pack may override app colors (a whitelisted subset of `--cs-*`, unitless
+ * HSL), supply per-state pet sprites, and a light/dark wallpaper. All three are
+ * optional — a pack can recolor only, reskin the pet only, etc. Image fields
+ * declare author-relative paths that the installer validates and renames to a
+ * canonical layout; the manifest here only checks shape, not the image bytes.
+ */
+/** Overridable CSS variables — must stay in sync with the renderer whitelist. */
+export const THEME_VAR_NAMES = [
+    "--cs-background",
+    "--cs-foreground",
+    "--cs-card",
+    "--cs-card-foreground",
+    "--cs-popover",
+    "--cs-popover-foreground",
+    "--cs-primary",
+    "--cs-primary-foreground",
+    "--cs-secondary",
+    "--cs-secondary-foreground",
+    "--cs-muted",
+    "--cs-muted-foreground",
+    "--cs-accent",
+    "--cs-accent-foreground",
+    "--cs-destructive",
+    "--cs-destructive-foreground",
+    "--cs-border",
+    "--cs-input",
+    "--cs-ring",
+    "--cs-status-running",
+    "--cs-status-ok",
+    "--cs-status-warn",
+    "--cs-status-err",
+    "--cs-status-idle",
+];
+const VAR_SET = new Set(THEME_VAR_NAMES);
+/** Unitless HSL triple, e.g. "19 63% 45%". */
+const HSL = /^\d+(?:\.\d+)?\s+\d+(?:\.\d+)?%\s+\d+(?:\.\d+)?%$/;
+const ThemeVarsSchema = z
+    .record(z.string())
+    .refine((vars) => Object.keys(vars).every((name) => VAR_SET.has(name)), {
+    message: "unknown --cs-* variable (not in the theme whitelist)",
+})
+    .refine((vars) => Object.values(vars).every((value) => HSL.test(value)), {
+    message: "color values must be unitless HSL triples like '19 63% 45%'",
+});
+/** A single safe path segment — no traversal, separators, or NUL. */
+const RELATIVE_ASSET = z
+    .string()
+    .min(1)
+    .refine((p) => !p.includes("\0") &&
+    !p.includes("\\") &&
+    !p.startsWith("/") &&
+    !p.split("/").some((seg) => seg === "" || seg === "." || seg === ".."), { message: "asset path must be a relative path with no traversal" });
+export const THEME_ID = /^[a-z0-9][a-z0-9-]{1,63}$/;
+export const ThemeManifestSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().regex(THEME_ID, "id must match ^[a-z0-9][a-z0-9-]{1,63}$"),
+    name: z.string().min(1).max(80),
+    version: z.string().min(1).max(32),
+    colors: z
+        .object({ light: ThemeVarsSchema.optional(), dark: ThemeVarsSchema.optional() })
+        .optional(),
+    pet: z
+        .object({
+        idle: RELATIVE_ASSET.optional(),
+        running: RELATIVE_ASSET.optional(),
+        alert: RELATIVE_ASSET.optional(),
+        /** Ordered frames cycled while the widget is dragged (a "run" loop). */
+        walk: z.array(RELATIVE_ASSET).max(16).optional(),
+    })
+        .optional(),
+    wallpaper: z
+        .object({
+        light: RELATIVE_ASSET.optional(),
+        dark: RELATIVE_ASSET.optional(),
+        opacity: z.number().min(0).max(1).optional(),
+    })
+        .optional(),
+});
+/** Parse + validate a raw `.cs-theme.json` object. Throws ZodError on invalid input. */
+export function parseThemeManifest(raw) {
+    return ThemeManifestSchema.parse(raw);
+}

package/dist/themes/paths.d.ts

@@ -0,0 +1,14 @@
+export declare class ThemeInstallError extends Error {
+}
+/** A review token changed between preview and install (content was modified). */
+export declare class ThemeReviewChangedError extends ThemeInstallError {
+    constructor();
+}
+/** A theme id must be a single safe path segment matching the manifest pattern. */
+export declare function assertSafeThemeName(id: string): void;
+export declare function themesRoot(): string;
+export declare function themeInstallDir(id: string): string;
+/** Canonical asset subdirectory inside an installed theme. */
+export declare const THEME_ASSET_DIR = ".cs-theme-assets";
+/** Registry of installed themes. */
+export declare function themesRegistryPath(): string;

package/dist/themes/paths.js

@@ -0,0 +1,33 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { THEME_ID } from "./manifest.js";
+export class ThemeInstallError extends Error {
+}
+/** A review token changed between preview and install (content was modified). */
+export class ThemeReviewChangedError extends ThemeInstallError {
+    constructor() {
+        super("theme content changed since preview");
+    }
+}
+function userHome() {
+    return process.env.CODE_SHELL_HOME ?? process.env.HOME ?? homedir();
+}
+/** A theme id must be a single safe path segment matching the manifest pattern. */
+export function assertSafeThemeName(id) {
+    if (!THEME_ID.test(id) || id === "." || id === "..") {
+        throw new ThemeInstallError(`invalid theme id: ${JSON.stringify(id)}`);
+    }
+}
+export function themesRoot() {
+    return join(userHome(), ".code-shell", "themes");
+}
+export function themeInstallDir(id) {
+    assertSafeThemeName(id);
+    return join(themesRoot(), id);
+}
+/** Canonical asset subdirectory inside an installed theme. */
+export const THEME_ASSET_DIR = ".cs-theme-assets";
+/** Registry of installed themes. */
+export function themesRegistryPath() {
+    return join(themesRoot(), "installed.json");
+}