twskin 0.5.3

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this package are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.5.3] - 2026-07-26
+
+### Added
+
+- `twskin stop` now stops the watcher and restores TRAE's native appearance
+  without quitting TRAE, while preserving the selected theme and its settings.
+- The selected theme is reapplied automatically after TRAE restarts while the
+  watcher remains active.
+
+### Changed
+
+- The watcher now remains available while TRAE is closed and reconnects on a later
+  launch.
+- JSONC comments, unrelated settings and any existing `remote-debugging-port`
+  value are preserved when enabling automatic reconnection, then restored on
+  stop, restore or uninstall.
+
+### Removed
+
+- The misspelled `twskin unisntall` compatibility alias is no longer accepted.
+
+### Fixed
+
+- The restore control now returns from `取消 / 确认恢复` to `恢复默认` after the
+  user confirms restoration.
+- Publish the CLI under its internal registry name, `@byted-relic/twskin`.
+
+## [0.5.2] - 2026-07-24
+
+### Changed
+
+- Ask users to save their work and confirm before `twskin start` restarts a
+  running TRAE process to enable CDP. Non-interactive callers must pass `--yes`.
+
+## [0.5.1] - 2026-07-24
+
+### Changed
+
+- Download the latest fixed-name theme assets directly from GitHub Release
+  redirects instead of consuming anonymous GitHub API quota.
+
+## [0.5.0] - 2026-07-24
+
+### Added
+
+- `twskin theme download [id]` for verified official GitHub Release theme packs.
+- `twskin theme load <directory>` for atomic local theme installation.
+- Independent, checksummed theme-pack build and Release upload automation.
+- Per-theme background brightness and main-workspace overlay controls in Theme
+  Manager, with values persisted in each theme's settings.
+- A V3 bridge for VS Code core color variables so IM Channel and legacy
+  workbench surfaces follow the active theme palette.
+
+### Changed
+
+- Renamed the unpublished package and command to `twskin`; the default data
+  directory is now `~/.trae-work-skin` and public environment variables use the
+  `TWSKIN_` prefix.
+- Rebuilt the command layer in strict TypeScript and moved the executable to the
+  compiled `dist/` entrypoint.
+- Adopted Clack for first-start confirmation, download progress, cancellation,
+  and completion guidance while preserving clean `--json` output.
+- Standardized installation on the npm CLI and its external theme download
+  flow.
+- Consolidated the injection engine into the tracked `runtime/` directory;
+  manifest generation no longer copies a second runtime tree.
+- Split shared and Theme Manager CSS out of `skin.js`, and moved EVA/Xianzhou
+  component styling into each theme's dynamically loaded `theme.css`.
+- Resolve runtime, data and theme paths consistently from
+  `~/.trae-work-skin`, including global and internal-registry installations.
+- Theme Manager configuration now exposes only controls supported by the
+  selected theme.
+
+### Fixed
+
+- Allow authenticated GitHub Release downloads when anonymous API quota is
+  unavailable, without forwarding credentials to configured mirrors.
+- Clear stale theme artwork variables when switching between themes.
+- Keep the generated runtime manifest limited to the canonical payload files.
+- Restore and startup scripts now use the same data directory as the CLI.
+
+## [0.4.0] - 2026-07-22
+
+### Added
+
+- First npm-ready `twskin` CLI package.
+- Commands for start, status, themes, theme selection, doctor, restore,
+  uninstall, version and help.
+- External theme-directory loading with `TWSKIN_THEMES_DIR` support.
+- Integrity-manifested injection runtime with no bundled theme assets.
+- Structured JSON output for status, themes and doctor.
+- Concurrency lock and stale-lock recovery for mutating commands.

package/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Thank you for improving TRAE Work Skin.
+
+## Development setup
+
+Use a supported Node.js LTS release (22 or 24):
+
+```bash
+cd packages/cli
+npm run prepare:runtime
+npm run check
+npm test
+```
+
+Before opening a pull request, also inspect the exact npm payload:
+
+```bash
+npm pack --dry-run
+```
+
+## Pull requests
+
+- Keep CLI behavior backward compatible unless the change is explicitly marked
+  as breaking.
+- Add tests for successful behavior and failure atomicity.
+- Do not add network downloads without integrity verification and rollback.
+- Do not add runtime dependencies without explaining the security and package
+  size trade-off.
+- Never include source artwork, credentials, local state or CDP logs in the npm
+  tarball.
+
+## Releases
+
+Versions follow Semantic Versioning. Publishing is performed from CI with npm
+trusted publishing/provenance; maintainers should not publish ad hoc local
+tarballs to the public registry.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fullstop000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# TRAE Work Skin CLI
+
+`twskin` provides the `twskin` command for installing, diagnosing,
+switching and restoring local themes in TRAE Work on macOS.
+
+> **Unofficial:** TRAE Work Skin is an unofficial community theme manager for TRAE
+> Work. It is not affiliated with, endorsed by, or sponsored by TRAE or
+> ByteDance.
+
+## Requirements
+
+- macOS
+- Node.js 22 or newer
+- TRAE Work CN installed locally
+
+## Install
+
+```bash
+npm install --global twskin
+twskin start
+```
+
+The command layer is written in strict TypeScript and uses Clack for interactive
+prompts and progress feedback. It only connects to the local TRAE process
+through CDP on `127.0.0.1`; it does not modify the TRAE application bundle or
+its code signature.
+
+On first start, an empty theme directory prompts before downloading from the
+latest official GitHub Release. Use `twskin start --yes` for explicit consent in
+automation. If TRAE is already running without CDP, the CLI asks the user to
+save their work and confirm before restarting it; `--yes` also explicitly
+confirms that restart. After a successful start, the CLI persists the loopback
+CDP port in TRAE's user-level `argv.json`. While the watcher remains active,
+quitting and reopening TRAE automatically reconnects and reapplies the selected
+theme. Later starts use the local themes without downloading.
+
+## Commands
+
+```text
+twskin start [--yes]         Initialize and start Theme Manager and its watcher
+twskin stop                  Stop Skin and restore native appearance without quitting TRAE
+twskin status [--json]       Show App, CDP, watcher and active-theme status
+twskin themes [--json]       List locally installed themes
+twskin theme <id>            Select a theme
+twskin theme download [id]   Download all or one theme from the latest GitHub Release
+twskin theme load <directory> Install one theme, or immediate child theme directories
+twskin doctor [--json]       Validate Node, TRAE, port and package integrity
+twskin restore               Restore the native TRAE appearance
+twskin uninstall [--yes]     Restore TRAE and remove TRAE Work Skin data
+twskin version               Print the CLI version
+twskin help                  Print command help
+```
+
+`twskin theme <id>` applies immediately while Theme Manager is active. Otherwise
+the selection is saved and applied by the next `twskin start`. `twskin stop`
+preserves the selected theme and its settings, so a later `twskin start` can
+restore them. It also restores the pre-existing `remote-debugging-port` value
+instead of leaving twskin's persistent CDP configuration behind.
+
+## Theme directory
+
+The CLI package does not contain themes. It loads them from:
+
+```text
+~/.trae-work-skin/themes
+```
+
+Set `TWSKIN_THEMES_DIR` to use another absolute directory.
+
+In a source checkout, the default is the repository's top-level `themes/`
+directory. `theme load` copies only the canonical theme payload and installs it
+atomically. `theme download` reads the latest official GitHub Release, verifies
+the attached SHA-256 file and archive structure, then installs into the same
+directory. See
+[docs/theme-distribution.md](docs/theme-distribution.md).
+
+The canonical payload may include `theme.css` for theme-specific component
+styling and motion. The injector replaces this stylesheet atomically whenever
+the active theme changes; declarative colors and component roles remain in
+`theme.json`.
+
+## Development
+
+```bash
+cd packages/cli
+npm install
+npm run prepare:runtime
+npm run check
+npm test
+npm pack --dry-run
+```
+
+TypeScript compiles to `dist/`. The tracked `runtime/` directory is the single
+source of truth for the injection engine; `prepare:runtime` only generates its
+SHA-256 manifest. npm publishes both outputs, while themes remain external.
+
+## Security
+
+Please read [SECURITY.md](SECURITY.md). Do not report vulnerabilities in public
+issues before a fix is available.
+
+## License
+
+MIT © Fullstop000

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest minor release.
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting for this repository. Include
+the affected version, macOS and TRAE versions, reproduction steps and expected
+impact. Do not include access tokens, personal data or unrelated application
+content.
+
+## Security boundaries
+
+- CDP binds to `127.0.0.1` only.
+- The CLI verifies that the configured CDP port belongs to TRAE before using it.
+- The CLI changes only `remote-debugging-port` in TRAE's user-level `argv.json`,
+  preserves JSONC comments and unrelated settings, and restores the previous
+  value on stop, restore or uninstall.
+- The TRAE application bundle and code signature are never modified.
+- Packaged engine files are covered by a SHA-256 manifest checked by
+  `twskin doctor`.
+- Themes are loaded from a user-controlled data directory, never `node_modules`.
+- Remote theme packs are size-limited, SHA-256 verified, checked for unsafe tar
+  paths and link/special-file entries, then installed atomically outside the npm
+  package directory.
+- Local theme loading rejects symlinks and copies only canonical theme assets.

package/dist/bin/twskin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=twskin.d.ts.map

package/dist/bin/twskin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twskin.d.ts","sourceRoot":"","sources":["../../src/bin/twskin.ts"],"names":[],"mappings":""}

package/dist/bin/twskin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../main.js";
+await run();
+//# sourceMappingURL=twskin.js.map

package/dist/bin/twskin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twskin.js","sourceRoot":"","sources":["../../src/bin/twskin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEjC,MAAM,GAAG,EAAE,CAAC"}

package/dist/commands.d.ts

@@ -0,0 +1,41 @@
+import type { CliContext, CliOptions } from "./types.js";
+export declare function helpText(context: CliContext): string;
+export declare function getStatus(context: CliContext): Promise<{
+    app: {
+        installed: boolean;
+        running: boolean;
+        bundle: string;
+    };
+    cdp: {
+        reachable: boolean;
+        port: number;
+        browser: string | null;
+        owner: {
+            pid: number;
+            command: string;
+            expected: boolean;
+        } | null;
+    };
+    watcher: {
+        pid: number | null;
+        running: boolean;
+        pidAlive: boolean;
+    };
+    theme: {
+        id: string;
+        valid: boolean;
+    };
+    version: string;
+    distribution: string;
+}>;
+export declare function startCommand(context: CliContext, options: CliOptions): Promise<void>;
+export declare function statusCommand(context: CliContext, options: CliOptions): Promise<void>;
+export declare function stopCommand(context: CliContext, options: CliOptions): Promise<void>;
+export declare function themesCommand(context: CliContext, options: CliOptions): void;
+export declare function themeCommand(context: CliContext, id: string | undefined, options: CliOptions): Promise<void>;
+export declare function loadThemeCommand(context: CliContext, sourceDirectory: string | undefined, options: CliOptions): Promise<void>;
+export declare function downloadThemeCommand(context: CliContext, id: string | undefined, options: CliOptions): Promise<void>;
+export declare function doctorCommand(context: CliContext, options: CliOptions): Promise<void>;
+export declare function restoreCommand(context: CliContext, options: CliOptions): Promise<void>;
+export declare function uninstallCommand(context: CliContext, options: CliOptions): Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA0CzD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAiBpD;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU;;QAQxC,SAAS;QAA4B,OAAO;QAAkC,MAAM;;;;;;;;;;;;;QAOhF,GAAG;QAAe,OAAO;QAAqC,QAAQ;;;QACxE,EAAE;QAAS,KAAK;;;;GAI5B;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAiG1F;AA2CD,wBAAsB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAY3F;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCzF;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAQ5E;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAelH;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAYnI;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1H;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAoD3F;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5F;AA+CD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB9F"}