codex-terminal-themes 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+- Initial source-of-truth repository for Codex and Bat TextMate themes.
+- Add a publishable npm CLI for listing, previewing, installing, diagnosing, and configuring theme installs.

package/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Keep this repository focused on terminal syntax theme source files and local sync validation.
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for the full maintainer command reference.
+
+When adding, removing, renaming, or editing a file in `themes/`, regenerate the consumer manifest:
+
+```powershell
+npm run metadata:write
+npm run pages:build
+```
+
+Before submitting changes:
+
+```powershell
+npm run metadata:check
+npm run pages:check
+npm run release:verify
+Sync-TerminalThemes.ps1 -WhatIf
+```
+
+When importing themes from a web source, use raw file URLs. Do not save rendered GitHub HTML pages as `.tmTheme` files.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick2bad4u
+
+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/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick2bad4u
+
+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,169 @@
+# Codex Terminal Themes
+
+[![NPM license.](https://flat.badgen.net/npm/license/codex-terminal-themes?color=purple)](https://github.com/Nick2bad4u/codex-terminal-themes/blob/main/LICENSE) [![NPM total downloads.](https://flat.badgen.net/npm/dt/codex-terminal-themes?color=pink)](https://www.npmjs.com/package/codex-terminal-themes) [![Latest GitHub release.](https://flat.badgen.net/github/release/Nick2bad4u/codex-terminal-themes?color=cyan)](https://github.com/Nick2bad4u/codex-terminal-themes/releases) [![GitHub stars.](https://flat.badgen.net/github/stars/Nick2bad4u/codex-terminal-themes?color=yellow)](https://github.com/Nick2bad4u/codex-terminal-themes/stargazers) [![GitHub forks.](https://flat.badgen.net/github/forks/Nick2bad4u/codex-terminal-themes?color=orange)](https://github.com/Nick2bad4u/codex-terminal-themes/forks) [![GitHub open issues.](https://flat.badgen.net/github/open-issues/Nick2bad4u/codex-terminal-themes?color=red)](https://github.com/Nick2bad4u/codex-terminal-themes/issues) [![Repo Checks.](https://flat.badgen.net/github/checks/nick2bad4u/codex-terminal-themes?color=green)](https://github.com/Nick2bad4u/codex-terminal-themes/actions)
+
+High-contrast TextMate `.tmTheme` files for Codex terminal sessions, `bat`, and other tools that can read TextMate themes.
+
+Browse the theme gallery:
+
+<https://nick2bad4u.github.io/codex-terminal-themes/>
+
+## What You Get
+
+- 203 TextMate themes in `themes/`.
+- A searchable online gallery with syntax previews, theme metadata, hue filtering, and color matching.
+- A generated metadata manifest at `metadata/themes.json` for scripts and theme pickers.
+- A dependency-light npm CLI for listing, previewing, installing, and diagnosing themes.
+- Themes that can still be copied directly into Codex or Bat theme folders.
+
+## Recommended Theme
+
+For Codex terminal use, start with:
+
+```text
+themes/converted-vscode-AmoledShinyBlack6.tmTheme
+```
+
+It is the most customized AMOLED variant in this repo and has the broadest scope coverage for terminal-heavy workflows.
+
+## Install With npm
+
+Use the CLI without a global install:
+
+```powershell
+npx codex-terminal-themes list --search amoled
+npx codex-terminal-themes show converted-vscode-amoledshinyblack6
+npx codex-terminal-themes install converted-vscode-amoledshinyblack6 --target both
+```
+
+Open the interactive picker with an ANSI terminal preview:
+
+```powershell
+npx codex-terminal-themes pick
+```
+
+Install directly from the picker:
+
+```powershell
+npx codex-terminal-themes pick --install --target codex
+```
+
+Run environment checks before installing:
+
+```powershell
+npx codex-terminal-themes doctor
+```
+
+CLI config is optional and only stores CLI defaults. It does not edit theme files or mutate Codex configuration:
+
+```powershell
+npx codex-terminal-themes config set defaultTheme converted-vscode-amoledshinyblack6
+npx codex-terminal-themes config set defaultTarget both
+npx codex-terminal-themes install
+```
+
+Useful install overrides:
+
+```powershell
+npx codex-terminal-themes install converted-vscode-amoledshinyblack6 --target codex --codex-dir "$env:USERPROFILE\.codex\themes"
+npx codex-terminal-themes install converted-vscode-amoledshinyblack6 --target bat --bat-dir "$((bat --config-dir).Trim())\themes"
+npx codex-terminal-themes install converted-vscode-amoledshinyblack6 --dry-run --json
+```
+
+## Use With Codex Manually
+
+Copy the `.tmTheme` file you want into your Codex themes directory, then select it from your Codex configuration.
+
+On Windows, that folder is usually:
+
+```powershell
+$env:USERPROFILE\.codex\themes
+```
+
+Example:
+
+```powershell
+Copy-Item ".\themes\converted-vscode-AmoledShinyBlack6.tmTheme" "$env:USERPROFILE\.codex\themes\"
+```
+
+## Use With Bat Manually
+
+Find Bat's config directory:
+
+```powershell
+bat --config-dir
+```
+
+Create a `themes` folder there if it does not exist, copy the `.tmTheme` files into it, then rebuild Bat's cache:
+
+```powershell
+$batConfig = bat --config-dir
+New-Item -ItemType Directory -Force -Path "$batConfig\themes"
+Copy-Item ".\themes\converted-vscode-AmoledShinyBlack6.tmTheme" "$batConfig\themes\"
+bat cache --build
+```
+
+Use a theme once:
+
+```powershell
+bat --theme "AMOLED Dark Shiny - Codex Varied v6" README.md
+```
+
+To make a Bat theme permanent, put the theme name in Bat's config file:
+
+```text
+--theme="AMOLED Dark Shiny - Codex Varied v6"
+```
+
+## Sync Everything Locally
+
+For local source checkout workflows, this repo also works with a drop-in PowerShell sync script named:
+
+```powershell
+Sync-TerminalThemes.ps1
+```
+
+Dry run first:
+
+```powershell
+Sync-TerminalThemes.ps1 -WhatIf
+```
+
+Then sync:
+
+```powershell
+Sync-TerminalThemes.ps1
+```
+
+The sync script copies valid `.tmTheme` files to the Codex theme folder and Bat's theme folder, then rebuilds Bat's cache.
+
+## Theme Metadata
+
+Use `metadata/themes.json` when you need to inspect the collection without parsing XML plist files yourself.
+
+It includes:
+
+- theme id, display name, file name, path, UUID, author, semantic class, and color space
+- detected dark, light, or unknown appearance
+- global colors such as background, foreground, selection, caret, line highlight, and invisibles
+- setting counts, color-reference counts, scoped-setting counts, and unique scope counts
+- TextMate scopes used by each theme
+- duplicate UUID groups for imported themes that share historical UUIDs
+
+See [metadata/README.md](metadata/README.md) for the manifest field contract and a small consumption example.
+
+## Troubleshooting
+
+If Bat does not show a theme, rebuild its cache:
+
+```powershell
+bat cache --build
+```
+
+If a downloaded theme does not work, make sure it is a raw `.tmTheme` XML plist file. Saving a rendered GitHub webpage as `.tmTheme` creates an HTML file that Codex and Bat cannot consume.
+
+If a theme looks too flat, try a newer numbered AMOLED variant. The numbered `converted-vscode-AmoledShinyBlack*.tmTheme` files are intentional iterations, and the later versions usually have more language-specific scope coverage.
+
+## Maintainers
+
+Development commands, validation, generated files, and release checks live in [DEVELOPMENT.md](DEVELOPMENT.md).

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security
+
+This repository stores local theme assets and validation tooling. It should not contain secrets, credentials, tokens, or machine-private configuration.
+
+Report sensitive issues through the repository's private vulnerability reporting channel if one is enabled. Do not open public issues that disclose secrets or private local paths beyond the expected theme sync paths.

package/SUPPORT.md

@@ -0,0 +1,5 @@
+# Support
+
+Use GitHub issues for reproducible problems with theme validation, sync behavior, or Bat/Codex theme loading.
+
+Include the theme filename, validation command, and relevant error output. Do not include secrets or unrelated private repository content.

package/bin/codex-terminal-themes.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.mjs";
+
+void runCli(process.argv.slice(2), {
+    cwd: process.cwd(),
+    env: process.env,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    stdout: process.stdout,
+}).then((exitCode) => {
+    process.exitCode = exitCode;
+});