twskin 0.5.3

package/docs/publishing.md

@@ -0,0 +1,45 @@
+# Publishing `twskin`
+
+The public npm package is unscoped: `twskin`.
+
+## First release
+
+Run these commands locally after signing in to the public npm registry. Keep your npm password and one-time code private.
+
+```bash
+npm login --registry=https://registry.npmjs.org
+cd packages/cli
+npm ci --ignore-scripts
+npm run prepare:runtime
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+This creates the current `twskin` version on npm. Verify it with:
+
+```bash
+npm view twskin version --registry=https://registry.npmjs.org
+npm install --global twskin
+```
+
+## Trusted publishing
+
+After the first release, configure npm Trusted Publishing for `twskin`:
+
+- GitHub owner: `Fullstop000`
+- Repository: `trae-work-dream-skin`
+- Workflow: `npm-publish.yml`
+- Environment: `npm`
+- Allowed action: `npm publish`
+
+The workflow publishes automatically when a `v*` tag is pushed. It can also be run manually with an existing tag. The package version must match the tag without its `v` prefix.
+
+Use the GitHub `npm` environment to require release approval. Do not add a long-lived npm publish token to repository secrets.
+
+## Later releases
+
+1. Update `packages/cli/package.json` and `package-lock.json` to the next version.
+2. Commit the version change and create a matching `v<version>` tag.
+3. Push the commit and tag. The npm workflow publishes the CLI.
+4. Create a GitHub Release from the same tag. The theme-release workflow publishes the matching theme pack.

package/docs/theme-distribution.md

@@ -0,0 +1,62 @@
+# Theme distribution decision
+
+## Current decision
+
+Themes are data, not CLI implementation. The `twskin` npm package
+therefore contains no theme manifests or images.
+
+The CLI loads themes from the user data directory:
+
+```text
+~/.trae-work-skin/themes/<theme-id>/
+```
+
+`TWSKIN_THEMES_DIR` can override this location for development, managed desktops
+or portable installations. The npm-installed CLI asks before downloading the
+official theme pack on first start; the package itself contains no themes.
+
+This boundary allows CLI and themes to have independent release cadences and
+keeps large visual assets out of normal CLI upgrades.
+
+## Official GitHub Release protocol
+
+Every CLI release attaches these independently downloadable assets:
+
+```text
+twskin-themes.tar.gz
+twskin-themes.sha256
+twskin-themes-v<version>.tar.gz
+twskin-themes-v<version>.sha256
+```
+
+`twskin theme download [id]` downloads the fixed-name assets through GitHub's
+`releases/latest/download` redirect, without calling the rate-limited Releases
+API. The versioned copies remain available for archival and manual downloads.
+With no ID, all themes are installed; with an ID, only that theme is installed.
+The archive root contains `theme-pack.json` and `themes/<id>/` directories.
+
+The command limits metadata and archive sizes, uses a network timeout, verifies
+SHA-256 before extraction, rejects absolute/traversal paths and link/special file
+types, validates every theme manifest and performs an atomic directory swap with
+rollback. It never changes the active theme implicitly.
+
+For testing or an enterprise mirror, `TWSKIN_RELEASE_ASSET_BASE_URL` may point
+to a directory containing the fixed-name assets. The legacy
+`TWSKIN_RELEASE_API_URL` override remains available for a GitHub-compatible
+latest-release JSON endpoint.
+
+When GitHub's anonymous API quota is unavailable, set `TWSKIN_GITHUB_TOKEN`,
+`GH_TOKEN`, or `GITHUB_TOKEN`. The CLI only sends that token to HTTPS requests
+for `api.github.com` and `github.com`; it is never forwarded to a configured
+mirror.
+
+## Local loading
+
+`twskin theme load <directory>` accepts either a directory containing `theme.json`
+or a parent whose immediate children are theme directories. Only `theme.json`,
+optional `theme.css`, canonical backgrounds and side-panel assets, and supported
+files below `icons/` are copied. Symlinks and oversized themes are rejected.
+
+Publishing a second npm package is not preferred: it would place mutable theme
+data under `node_modules` and make selective updates awkward. Package signatures
+or a signed catalog should be added before third-party registries are enabled.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "twskin",
+  "version": "0.5.3",
+  "description": "An unofficial community theme manager and CLI for TRAE Work on macOS.",
+  "type": "module",
+  "bin": {
+    "twskin": "dist/bin/twskin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "runtime/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "prepare:runtime": "node ./scripts/prepare-runtime.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run clean && tsc",
+    "check": "npm run typecheck && node ./scripts/check-package.mjs",
+    "test": "npm run build && node --test \"test/*.test.mjs\"",
+    "build:themes": "npm run build && node ../../scripts/build-theme-pack.mjs",
+    "prepack": "npm run prepare:runtime && npm run check && npm test",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "keywords": [
+    "trae",
+    "theme",
+    "theme-manager",
+    "cli",
+    "macos",
+    "electron",
+    "cdp"
+  ],
+  "author": "Fullstop000",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fullstop000/trae-work-dream-skin.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Fullstop000/trae-work-dream-skin/issues"
+  },
+  "homepage": "https://github.com/Fullstop000/trae-work-dream-skin#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "jsonc-parser": "^3.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^7.0.2"
+  }
+}

package/runtime/component-map.mjs

@@ -0,0 +1,200 @@
+// TRAE Work Skin — V3 组件槽位规范化（纯函数，无 DOM 依赖）
+// 页面载荷由 injector 嵌入 skin.js；单测可直接加载本文件。
+// 前置条件：roles 必须是 TOKEN_MAP.deriveRoles 的完整输出。
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  root.DREAM_SKIN_COMPONENT_MAP = api;
+})(typeof self !== "undefined" ? self : globalThis, function () {
+  "use strict";
+
+  const BANNER_VARIANTS = new Set(["default", "system-plate"]);
+  const MODE_TAB_VARIANTS = new Set(["default", "launch-rail"]);
+  const ICON_POLICIES = new Set(["active", "always", "never"]);
+  const MODES = ["work", "code", "design"];
+  const DEFAULT_BANNER_MODES = {
+    work: { code: "01", label: "WORK" },
+    code: { code: "02", label: "CODE" },
+    design: { code: "03", label: "DESIGN" },
+  };
+  const DEFAULT_TAB_MODES = {
+    work: { code: "01" },
+    code: { code: "02" },
+    design: { code: "03" },
+  };
+
+  const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const number = (value, fallback, min, max) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? Math.min(max, Math.max(min, parsed)) : fallback;
+  };
+  const choice = (value, values, fallback) => values.has(value) ? value : fallback;
+  const text = (value, fallback, maxLength = 32) => {
+    if (value == null || !["string", "number"].includes(typeof value)) return fallback;
+    const normalized = String(value)
+      .replace(/[\u0000-\u001f\u007f]/g, " ")
+      .replace(/\s+/g, " ")
+      .trim();
+    return normalized ? normalized.slice(0, maxLength) : fallback;
+  };
+
+  // 主题输入只接受可审计的封闭颜色语法；fallback 来自 deriveRoles，属于可信内部值。
+  const isThemeColor = (value) => {
+    if (typeof value !== "string") return false;
+    const color = value.trim();
+    if (color.toLowerCase() === "transparent") return true;
+    if (/^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(color)) return true;
+    const match = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+))?\s*\)$/i.exec(color);
+    if (!match) return false;
+    const channels = match.slice(1, 4).map(Number);
+    const alpha = match[4] == null ? 1 : Number(match[4]);
+    return channels.every((channel) => Number.isFinite(channel) && channel >= 0 && channel <= 255)
+      && Number.isFinite(alpha) && alpha >= 0 && alpha <= 1;
+  };
+  const safeColor = (value, fallback) => isThemeColor(value) ? value.trim() : fallback;
+
+  const splitTopLevel = (value, separator) => {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < value.length; i += 1) {
+      if (value[i] === "(") depth += 1;
+      else if (value[i] === ")") depth -= 1;
+      else if (value[i] === separator && depth === 0) {
+        parts.push(value.slice(start, i).trim());
+        start = i + 1;
+      }
+      if (depth < 0) return [];
+    }
+    if (depth !== 0) return [];
+    parts.push(value.slice(start).trim());
+    return parts;
+  };
+  const SHADOW_LENGTH = /^(?:0|[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em))$/i;
+  const isShadowLayer = (value) => {
+    let layer = value.trim();
+    if (!layer) return false;
+    if (/^inset\s+/i.test(layer)) layer = layer.replace(/^inset\s+/i, "");
+    let color = null;
+    const colorMatch = /(?:#[0-9a-f]{3}|#[0-9a-f]{6}|#[0-9a-f]{8}|rgba?\([^)]*\)|transparent)$/i.exec(layer);
+    if (colorMatch) {
+      color = colorMatch[0];
+      layer = layer.slice(0, colorMatch.index).trim();
+    }
+    if (color != null && !isThemeColor(color)) return false;
+    const lengths = layer.split(/\s+/);
+    return lengths.length >= 2 && lengths.length <= 4 && lengths.every((part) => SHADOW_LENGTH.test(part));
+  };
+  const safeShadow = (value, fallback = "none") => {
+    if (typeof value !== "string") return fallback;
+    const shadow = value.trim();
+    if (!shadow) return fallback;
+    if (shadow.toLowerCase() === "none") return "none";
+    if (/(?:url|var|attr|expression)\s*\(|[;{}]|\/\*|\*\//i.test(shadow)) return fallback;
+    const layers = splitTopLevel(shadow, ",");
+    return layers.length && layers.every(isShadowLayer) ? shadow : fallback;
+  };
+
+  const modeContent = (value, fallback, includeLabel) => {
+    const modes = object(value);
+    return Object.fromEntries(MODES.map((mode) => {
+      const source = object(modes[mode]);
+      const normalized = { code: text(source.code, fallback[mode].code, 24) };
+      if (includeLabel) normalized.label = text(source.label, fallback[mode].label, 24);
+      return [mode, normalized];
+    }));
+  };
+
+  function deriveComponents(components, roles) {
+    const c = object(components);
+    const r = object(roles);
+    const accent = object(r.accent);
+    const surface = object(r.surface);
+    const textRole = object(r.text);
+    const border = object(r.border);
+    const state = object(r.state);
+    const banner = object(object(c.landing).banner);
+    const bannerColors = object(banner.colors);
+    const bannerMetrics = object(banner.metrics);
+    const bannerEffects = object(banner.effects);
+    const bannerContent = object(banner.content);
+    const tabs = object(object(c.navigation).modeTabs);
+    const tabColors = object(tabs.colors);
+    const tabMetrics = object(tabs.metrics);
+    const tabEffects = object(tabs.effects);
+    const tabContent = object(tabs.content);
+
+    return {
+      banner: {
+        variant: choice(banner.variant, BANNER_VARIANTS, "default"),
+        colors: {
+          surface: safeColor(bannerColors.surface, surface.card),
+          border: safeColor(bannerColors.border, border.default),
+          accent: safeColor(bannerColors.accent, accent.base),
+          text: safeColor(bannerColors.text, textRole.primary),
+          muted: safeColor(bannerColors.muted, textRole.tertiary),
+          status: safeColor(bannerColors.status, state.success || accent.base),
+        },
+        metrics: {
+          cornerCutPx: number(bannerMetrics.cornerCutPx, 12, 0, 40),
+          maxWidthPx: number(bannerMetrics.maxWidthPx, 620, 320, 960),
+          iconSizePx: number(bannerMetrics.iconSizePx, 48, 24, 80),
+        },
+        effects: { shadow: safeShadow(bannerEffects.shadow, "none") },
+        content: {
+          statusText: text(bannerContent.statusText, "ONLINE", 20),
+          modes: modeContent(bannerContent.modes, DEFAULT_BANNER_MODES, true),
+        },
+      },
+      modeTabs: {
+        variant: choice(tabs.variant, MODE_TAB_VARIANTS, "default"),
+        colors: {
+          track: safeColor(tabColors.track, surface.secondary),
+          border: safeColor(tabColors.border, border.default),
+          indicator: safeColor(tabColors.indicator, accent.subtle || surface.card),
+          accent: safeColor(tabColors.accent, accent.base),
+          activeText: safeColor(tabColors.activeText, accent.base || textRole.primary),
+          inactiveText: safeColor(tabColors.inactiveText, textRole.secondary),
+          hover: safeColor(tabColors.hover, surface.cardHover || surface.tertiary),
+        },
+        metrics: {
+          heightPx: number(tabMetrics.heightPx, 40, 32, 56),
+          tabWidthPx: number(tabMetrics.tabWidthPx, 84, 64, 120),
+          gapPx: number(tabMetrics.gapPx, 3, 0, 12),
+          cornerCutPx: number(tabMetrics.cornerCutPx, 8, 0, 18),
+        },
+        effects: { shadow: safeShadow(tabEffects.shadow, "none") },
+        content: {
+          iconPolicy: choice(tabContent.iconPolicy, ICON_POLICIES, "active"),
+          showModeCode: tabContent.showModeCode === true,
+          modes: modeContent(tabContent.modes, DEFAULT_TAB_MODES, false),
+        },
+      },
+    };
+  }
+
+  function getContrastPairs(components) {
+    const c = object(components);
+    const banner = object(c.banner);
+    const bannerColors = object(banner.colors);
+    const modeTabs = object(c.modeTabs);
+    const tabColors = object(modeTabs.colors);
+    const pairs = [];
+    if (banner.variant === "system-plate") {
+      pairs.push(
+        { fg: "components.landing.banner.colors.text", fgValue: bannerColors.text, bg: "components.landing.banner.colors.surface", bgValue: bannerColors.surface, minRatio: 4 },
+        { fg: "components.landing.banner.colors.muted", fgValue: bannerColors.muted, bg: "components.landing.banner.colors.surface", bgValue: bannerColors.surface, minRatio: 3 },
+        { fg: "components.landing.banner.colors.status", fgValue: bannerColors.status, bg: "components.landing.banner.colors.surface", bgValue: bannerColors.surface, minRatio: 4 },
+      );
+    }
+    if (modeTabs.variant === "launch-rail") {
+      pairs.push(
+        { fg: "components.navigation.modeTabs.colors.activeText", fgValue: tabColors.activeText, bg: "components.navigation.modeTabs.colors.indicator", bgValue: tabColors.indicator, minRatio: 4 },
+        { fg: "components.navigation.modeTabs.colors.inactiveText", fgValue: tabColors.inactiveText, bg: "components.navigation.modeTabs.colors.track", bgValue: tabColors.track, minRatio: 4 },
+      );
+    }
+    return pairs;
+  }
+
+  return { deriveComponents, getContrastPairs, safeColor, safeShadow, MODES };
+});