@codextheme/cli 0.1.1 → 0.2.0

package/README.md

@@ -1,25 +1,26 @@
 # @codextheme/cli
 
-Fixed-version, one-command curated themes for Codex Desktop on macOS.
+Fixed-version, one-command curated and private custom skins for Codex Desktop on macOS.
+
+Apply a catalog skin:
 
 ```sh
-npx --yes @codextheme/cli@0.1.1 apply cathedral-nocturne
+npx --yes @codextheme/cli@0.2.0 apply cathedral-nocturne
 ```
 
-Version 0.1.1 bundles three new original Gothic Worlds themes and keeps the three 0.1.0 theme slugs for backward compatibility. It does not download themes, run install scripts, use `sudo`, or modify the Codex application bundle.
-
-After restarting Codex, reapply the active theme with:
+The custom skin studio at [codextheme.tech](https://codextheme.tech) creates an expiring private command:
 
 ```sh
-npx --yes @codextheme/cli@0.1.1 reapply
+npx --yes @codextheme/cli@0.2.0 apply-private <private-id>
 ```
 
-Restore the official appearance with:
+Private packages are downloaded only from the fixed `https://codextheme.tech` origin, bounded, integrity-checked, schema-validated, safety-linted, and cached locally with owner-only permissions. The temporary server link expires after 24 hours; `reapply` uses the validated local cache and works after that link expires.
 
 ```sh
-npx --yes @codextheme/cli@0.1.1 restore
+npx --yes @codextheme/cli@0.2.0 reapply
+npx --yes @codextheme/cli@0.2.0 restore
 ```
 
-Requirements: macOS, Node.js 22.4+, and Codex Desktop. A running Codex process is never closed or reopened without an explicit `y` confirmation.
+The CLI has no install scripts, does not use `sudo`, and does not modify the Codex application bundle. Requirements: macOS, Node.js 22.4+, and Codex Desktop. A running Codex process is never closed or reopened without an explicit `y` confirmation.
 
 CodexTheme is an independent project and is not affiliated with or endorsed by OpenAI.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codextheme/cli",
-  "version": "0.1.1",
-  "description": "One-command curated themes for Codex Desktop on macOS.",
+  "version": "0.2.0",
+  "description": "One-command curated and private custom skins for Codex Desktop on macOS.",
   "type": "module",
   "license": "Apache-2.0",
   "bin": {

package/src/cache.mjs

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const SAFE_KEY = /^[a-f0-9]{64}$/;
+
+function cacheError() {
+  return Object.assign(new Error("无法安全读写本地私有主题缓存。"), { code: "E_PRIVATE_CACHE" });
+}
+
+export function createPrivateCache({ home = os.homedir(), fsApi = fs } = {}) {
+  const directory = path.join(home, "Library", "Application Support", "codextheme", "private");
+  const filename = (key) => {
+    if (typeof key !== "string" || !SAFE_KEY.test(key)) throw cacheError();
+    return path.join(directory, `${key}.codextheme-theme`);
+  };
+
+  return {
+    directory,
+    filename,
+
+    async write(serialized) {
+      if (typeof serialized !== "string" || !serialized) throw cacheError();
+      const key = createHash("sha256").update(serialized).digest("hex");
+      const target = filename(key);
+      await fsApi.mkdir(directory, { recursive: true, mode: 0o700 });
+      await fsApi.chmod(directory, 0o700);
+      try {
+        const existing = await fsApi.readFile(target, "utf8");
+        if (createHash("sha256").update(existing).digest("hex") !== key) throw cacheError();
+        return key;
+      } catch (error) {
+        if (error?.code !== "ENOENT") throw error?.code === "E_PRIVATE_CACHE" ? error : cacheError();
+      }
+
+      const temporary = path.join(directory, `.private.${process.pid}.${Date.now()}.tmp`);
+      try {
+        await fsApi.writeFile(temporary, serialized, { encoding: "utf8", mode: 0o600 });
+        await fsApi.rename(temporary, target);
+        await fsApi.chmod(target, 0o600);
+        return key;
+      } catch {
+        await fsApi.rm(temporary, { force: true }).catch(() => {});
+        throw cacheError();
+      }
+    },
+
+    async read(key) {
+      let serialized;
+      try {
+        serialized = await fsApi.readFile(filename(key), "utf8");
+      } catch {
+        throw cacheError();
+      }
+      if (createHash("sha256").update(serialized).digest("hex") !== key) throw cacheError();
+      return serialized;
+    },
+
+    async remove(key) {
+      try {
+        await fsApi.rm(filename(key), { force: true });
+      } catch {
+        throw cacheError();
+      }
+    },
+  };
+}

package/src/lifecycle.mjs

@@ -32,11 +32,9 @@ async function requireRestartConsent(promptRestart) {
   }
 }
 
-export async function applyTheme({ slug, runtime, stateStore, promptRestart, now = () => new Date() }) {
-  let theme;
+async function applyResolvedTheme({ theme, nextState, runtime, stateStore, promptRestart, now }) {
   let detection;
   try {
-    theme = await runtime.loadTheme(slug);
     detection = await runtime.detect();
   } catch (error) {
     throw mappedError(error);
@@ -73,14 +71,61 @@ export async function applyTheme({ slug, runtime, stateStore, promptRestart, now
   }
 
   const appliedAt = now().toISOString();
-  await stateStore.write({ schemaVersion: 1, themeSlug: slug, appliedAt });
+  await stateStore.write({ ...nextState, appliedAt });
   return { theme, result, appliedAt };
 }
 
+export async function applyTheme({ slug, runtime, stateStore, promptRestart, now = () => new Date() }) {
+  let theme;
+  try {
+    theme = await runtime.loadTheme(slug);
+  } catch (error) {
+    throw mappedError(error);
+  }
+  return applyResolvedTheme({
+    theme,
+    nextState: { schemaVersion: 2, source: "catalog", themeSlug: slug },
+    runtime,
+    stateStore,
+    promptRestart,
+    now,
+  });
+}
+
+export async function applyPrivateTheme({ bundle, cacheKey, runtime, stateStore, promptRestart, now = () => new Date() }) {
+  let theme;
+  try {
+    theme = await runtime.loadThemeBundle(bundle);
+  } catch (error) {
+    throw mappedError(error);
+  }
+  return applyResolvedTheme({
+    theme,
+    nextState: { schemaVersion: 2, source: "private", cacheKey },
+    runtime,
+    stateStore,
+    promptRestart,
+    now,
+  });
+}
+
 export async function reapplyTheme(options) {
   const state = await options.stateStore.read();
   if (!state) throw new CliError("E_USAGE", "没有可重新应用的活动主题，请先从主题页复制 apply 命令。");
-  return applyTheme({ ...options, slug: state.themeSlug });
+  if (state.schemaVersion === 1 || state.source === "catalog") {
+    return applyTheme({ ...options, slug: state.themeSlug });
+  }
+  if (state.schemaVersion !== 2 || state.source !== "private" || !options.cache) {
+    throw new CliError("E_USAGE", "活动主题状态无效，请重新创建或应用主题。");
+  }
+  let bundle;
+  try {
+    bundle = JSON.parse(await options.cache.read(state.cacheKey));
+  } catch (error) {
+    if (String(error?.code ?? "").startsWith("E_")) throw error;
+    throw new CliError("E_PRIVATE_CACHE", "无法安全读取本地私有主题缓存。");
+  }
+  return applyPrivateTheme({ ...options, bundle, cacheKey: state.cacheKey });
 }
 
 const RENDERER_ABSENT_CODES = new Set([

package/src/main.mjs

@@ -1,17 +1,20 @@
 import { CATALOG, getCatalogEntry } from "./catalog.mjs";
-import { applyTheme, CliError, reapplyTheme, restoreTheme } from "./lifecycle.mjs";
+import { createPrivateCache } from "./cache.mjs";
+import { applyPrivateTheme, applyTheme, CliError, reapplyTheme, restoreTheme } from "./lifecycle.mjs";
+import { privateThemeSource } from "./private-source.mjs";
 import { confirmRestart } from "./prompt.mjs";
 import { runtime as productionRuntime } from "./runtime.mjs";
 import { createStateStore } from "./state.mjs";
 
-export const VERSION = "0.1.1";
-const REAPPLY = "npx --yes @codextheme/cli@0.1.1 reapply";
-const RESTORE = "npx --yes @codextheme/cli@0.1.1 restore";
+export const VERSION = "0.2.0";
+const REAPPLY = "npx --yes @codextheme/cli@0.2.0 reapply";
+const RESTORE = "npx --yes @codextheme/cli@0.2.0 restore";
 
 const HELP = `CodexTheme ${VERSION}
 
 用法：
   codextheme apply <theme>
+  codextheme apply-private <private-id>
   codextheme reapply
   codextheme restore
 
@@ -32,6 +35,11 @@ function safePublicError(error) {
     "E_DOM_INCOMPATIBLE",
     "E_CORE_VERIFY",
     "E_RESTORE_FAILED",
+    "E_PRIVATE_NOT_FOUND",
+    "E_PRIVATE_EXPIRED",
+    "E_PRIVATE_DOWNLOAD",
+    "E_PRIVATE_INVALID",
+    "E_PRIVATE_CACHE",
   ]);
   if (allowed.has(error?.code)) return { code: error.code, message: error.message, exitCode: 1 };
   return { code: "E_DOM_INCOMPATIBLE", message: "CodexTheme 未能完成本次操作。", exitCode: 1 };
@@ -43,6 +51,9 @@ function validateCommand(argv) {
     if (!theme) throw usage("未知主题。请从 codextheme.tech 复制完整命令。");
     return { command: "apply", slug: theme.slug };
   }
+  if (argv.length === 2 && argv[0] === "apply-private") {
+    return { command: "apply-private", privateId: argv[1] };
+  }
   if (argv.length === 1 && argv[0] === "reapply") return { command: "reapply" };
   if (argv.length === 1 && argv[0] === "restore") return { command: "restore" };
   throw usage("参数无效。运行 codextheme --help 查看用法。");
@@ -64,19 +75,27 @@ export async function run(argv, dependencies = {}) {
   try {
     const parsed = validateCommand(argv);
     if ((dependencies.platform ?? process.platform) !== "darwin") {
-      throw new CliError("E_PLATFORM", "0.1.1 首发版仅支持 macOS 上的 Codex Desktop。");
+      throw new CliError("E_PLATFORM", "0.2.0 版本仅支持 macOS 上的 Codex Desktop。");
     }
     const services = {
       runtime: dependencies.runtime ?? productionRuntime,
       stateStore: dependencies.stateStore ?? createStateStore(),
       promptRestart: dependencies.promptRestart ?? (() => confirmRestart()),
       now: dependencies.now ?? (() => new Date()),
+      cache: dependencies.privateCache ?? createPrivateCache(),
     };
+    const privateSource = dependencies.privateSource ?? privateThemeSource;
 
     if (parsed.command === "apply") {
       const result = await applyTheme({ ...services, slug: parsed.slug });
       const name = result.theme.theme?.displayName?.split(" / ")[0] ?? getCatalogEntry(parsed.slug).name;
       stdout.write(`✓ ${name} 主题已应用并通过验证\n重开 Codex 后运行：${REAPPLY}\n恢复官方外观：${RESTORE}\n`);
+    } else if (parsed.command === "apply-private") {
+      const downloaded = await privateSource.download(parsed.privateId);
+      const cacheKey = await services.cache.write(downloaded.serialized);
+      const result = await applyPrivateTheme({ ...services, bundle: downloaded.bundle, cacheKey });
+      const name = result.theme.theme?.displayName ?? "Private Custom Skin";
+      stdout.write(`✓ ${name} 已应用并通过验证\n重开 Codex 后运行：${REAPPLY}\n恢复官方外观：${RESTORE}\n`);
     } else if (parsed.command === "reapply") {
       const result = await reapplyTheme(services);
       const name = result.theme.theme?.displayName?.split(" / ")[0] ?? "当前";

package/src/private-source.mjs

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { lintThemePackage, validateThemePackage } from "@codextheme/runtime";
+
+const PRODUCTION_ORIGIN = "https://codextheme.tech";
+const SAFE_ID = /^[a-z0-9]+\.[A-Za-z0-9_-]{32}$/;
+const SAFE_HASH = /^[a-f0-9]{64}$/;
+const MAX_BYTES = 3_800_000;
+const MEDIA_TYPE = "application/vnd.codextheme.theme+json";
+
+function sourceError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function exactKeys(value, expected) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).sort().join("\0") === [...expected].sort().join("\0");
+}
+
+function assertPrivateShape(bundle) {
+  if (!exactKeys(bundle, ["format", "schemaVersion", "exportedAt", "theme", "targets", "assets"])) throw new Error("root");
+  if (!exactKeys(bundle.theme, ["id", "displayName", "version", "copy"])) throw new Error("theme");
+  if (!exactKeys(bundle.theme.copy, ["brandTitle", "brandSubtitle", "signature", "tagline", "projectPrefix", "projectLabel", "ribbon"])) throw new Error("copy");
+  if (!exactKeys(bundle.targets, ["codex"])) throw new Error("targets");
+  const target = bundle.targets.codex;
+  if (!exactKeys(target, ["css", "options", "verification"])) throw new Error("target");
+  if (!exactKeys(target.options, ["rendererProfile", "baseTheme"])) throw new Error("options");
+  if (!exactKeys(target.options.baseTheme, ["mode", "codeTheme", "accent", "contrast", "ink", "surface", "opaqueWindows"])) throw new Error("base theme");
+  if (!exactKeys(target.verification, ["recommended"]) || !Array.isArray(target.verification.recommended)) throw new Error("verification");
+  for (const requirement of target.verification.recommended) {
+    if (!exactKeys(requirement, ["name", "any"])) throw new Error("requirement");
+  }
+  if (!exactKeys(bundle.assets, ["images"]) || !exactKeys(bundle.assets.images, ["hero", "session-bg"])) throw new Error("images");
+  for (const image of Object.values(bundle.assets.images)) {
+    if (!exactKeys(image, ["filename", "mimeType", "base64"]) || image.mimeType !== "image/webp" || image.filename !== "custom-skin.webp") {
+      throw new Error("image");
+    }
+  }
+}
+
+async function readBounded(response) {
+  if (!response.body) throw sourceError("E_PRIVATE_INVALID", "下载的私有主题无效。");
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_BYTES) {
+      void reader.cancel().catch(() => {});
+      throw sourceError("E_PRIVATE_INVALID", "下载的私有主题超过安全大小限制。");
+    }
+    chunks.push(value);
+  }
+  const combined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    combined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(combined);
+}
+
+export function createPrivateThemeSource({ origin = PRODUCTION_ORIGIN, fetchImpl = globalThis.fetch } = {}) {
+  return {
+    async download(id) {
+      if (typeof id !== "string" || !SAFE_ID.test(id)) {
+        throw sourceError("E_PRIVATE_NOT_FOUND", "没有找到该私有主题。");
+      }
+      let response;
+      try {
+        response = await fetchImpl(`${origin}/api/private-skins/${id}`, {
+          method: "GET",
+          redirect: "error",
+          signal: AbortSignal.timeout(15_000),
+          headers: { Accept: MEDIA_TYPE },
+        });
+      } catch {
+        throw sourceError("E_PRIVATE_DOWNLOAD", "暂时无法下载私有主题。");
+      }
+      if (response.status === 404) throw sourceError("E_PRIVATE_NOT_FOUND", "没有找到该私有主题。");
+      if (response.status === 410) throw sourceError("E_PRIVATE_EXPIRED", "该私有主题链接已过期。");
+      if (!response.ok) throw sourceError("E_PRIVATE_DOWNLOAD", "暂时无法下载私有主题。");
+      if (response.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase() !== MEDIA_TYPE) {
+        throw sourceError("E_PRIVATE_INVALID", "下载的私有主题类型无效。");
+      }
+
+      let serialized;
+      try {
+        serialized = await readBounded(response);
+      } catch (error) {
+        if (error?.code === "E_PRIVATE_INVALID") throw error;
+        throw sourceError("E_PRIVATE_INVALID", "下载的私有主题编码无效。");
+      }
+      const sha256 = createHash("sha256").update(serialized).digest("hex");
+      const expectedHash = response.headers.get("x-codextheme-sha256") ?? "";
+      if (!SAFE_HASH.test(expectedHash) || expectedHash !== sha256) {
+        throw sourceError("E_PRIVATE_INVALID", "私有主题完整性验证失败。");
+      }
+
+      let bundle;
+      try {
+        bundle = JSON.parse(serialized);
+        assertPrivateShape(bundle);
+        validateThemePackage(bundle);
+        if (lintThemePackage(bundle).length) throw new Error("lint");
+      } catch {
+        throw sourceError("E_PRIVATE_INVALID", "私有主题安全验证失败。");
+      }
+      return { serialized, sha256, bundle };
+    },
+  };
+}
+
+export const privateThemeSource = createPrivateThemeSource();

package/src/runtime.mjs

@@ -8,21 +8,32 @@ import {
   readThemePackage,
   resolveThemeTarget,
   restoreSkin,
+  validateThemePackage,
 } from "@codextheme/runtime";
 import { themeFilename } from "./catalog.mjs";
 
 const adapter = getAdapter("codex");
 
+function resolveSafeTheme(bundle) {
+  try {
+    validateThemePackage(bundle);
+    if (lintThemePackage(bundle).length) throw new Error("lint");
+    return resolveThemeTarget(bundle, adapter.id);
+  } catch {
+    throw Object.assign(new Error("Theme failed safety validation."), { code: "E_DOM_INCOMPATIBLE" });
+  }
+}
+
 export const runtime = {
   async loadTheme(slug) {
     const filename = themeFilename(slug);
     if (!filename) throw Object.assign(new Error("Unknown theme."), { code: "E_USAGE" });
     const bundle = await readThemePackage(filename);
-    const warnings = lintThemePackage(bundle);
-    if (warnings.length) {
-      throw Object.assign(new Error("Bundled theme failed safety lint."), { code: "E_DOM_INCOMPATIBLE" });
-    }
-    return resolveThemeTarget(bundle, adapter.id);
+    return resolveSafeTheme(bundle);
+  },
+
+  async loadThemeBundle(bundle) {
+    return resolveSafeTheme(bundle);
   },
 
   async detect() {

package/src/state.mjs

@@ -2,21 +2,45 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
+const SAFE_CACHE_KEY = /^[a-f0-9]{64}$/;
+
+function invalidState() {
+  return Object.assign(new Error("Invalid CodexTheme state."), { code: "E_USAGE" });
+}
+
 function cleanState(value) {
-  if (
-    value?.schemaVersion !== 1
-    || typeof value.themeSlug !== "string"
-    || !value.themeSlug
-    || typeof value.appliedAt !== "string"
-    || !value.appliedAt
-  ) {
-    throw Object.assign(new Error("Invalid CodexTheme state."), { code: "E_USAGE" });
+  if (typeof value?.appliedAt !== "string" || !value.appliedAt) throw invalidState();
+
+  if (value.schemaVersion === 1) {
+    if (typeof value.themeSlug !== "string" || !value.themeSlug) throw invalidState();
+    return {
+      schemaVersion: 1,
+      themeSlug: value.themeSlug,
+      appliedAt: value.appliedAt,
+    };
   }
-  return {
-    schemaVersion: 1,
-    themeSlug: value.themeSlug,
-    appliedAt: value.appliedAt,
-  };
+
+  if (value.schemaVersion === 2 && value.source === "catalog") {
+    if (typeof value.themeSlug !== "string" || !value.themeSlug) throw invalidState();
+    return {
+      schemaVersion: 2,
+      source: "catalog",
+      themeSlug: value.themeSlug,
+      appliedAt: value.appliedAt,
+    };
+  }
+
+  if (value.schemaVersion === 2 && value.source === "private") {
+    if (typeof value.cacheKey !== "string" || !SAFE_CACHE_KEY.test(value.cacheKey)) throw invalidState();
+    return {
+      schemaVersion: 2,
+      source: "private",
+      cacheKey: value.cacheKey,
+      appliedAt: value.appliedAt,
+    };
+  }
+
+  throw invalidState();
 }
 
 export function createStateStore({ home = os.homedir(), fsApi = fs } = {}) {