ctheme 0.1.0 → 0.1.1

package/DEVELOPMENT.md

@@ -0,0 +1,245 @@
+# Development
+
+## Purpose
+
+`ctheme` is a terminal theming CLI.
+
+Scope:
+
+- terminal color themes
+- terminal font selection
+- live Apple Terminal profile switching
+- config snippet generation for Ghostty, Kitty, and WezTerm
+- custom theme authoring
+- Google Fonts discovery and install helpers
+
+Out of scope:
+
+- editor themes
+- app chrome theming
+- IDE plugins
+- Codex-specific config behavior
+
+## Repository Layout
+
+```text
+bin/ctheme.js       Main CLI entrypoint and all runtime logic
+README.md           User-facing docs
+DEVELOPMENT.md      Contributor docs
+package.json        npm package metadata
+```
+
+This project is intentionally small. Most behavior lives in one file so it stays easy to ship and debug.
+
+## Runtime State
+
+`ctheme` keeps its own state under:
+
+```text
+~/.ctheme/themes
+~/.ctheme/snippets
+~/.ctheme/snippets/.ctheme-state.json
+~/Library/Fonts/pretty-code
+```
+
+What each path is for:
+
+- `~/.ctheme/themes`: saved custom theme JSON palettes
+- `~/.ctheme/snippets`: generated terminal config snippets and AppleScript files
+- `~/.ctheme/snippets/.ctheme-state.json`: restore state for `ctheme reset`
+- `~/Library/Fonts/pretty-code`: Google Fonts installed by the CLI
+
+Relevant env vars:
+
+```text
+CTHEME_HOME
+CTHEME_THEME_DIR
+CTHEME_SNIPPET_DIR
+```
+
+## Command Map
+
+Main commands:
+
+- `ctheme use <theme>`: apply a theme live to the current terminal when supported
+- `ctheme reset`: restore the original terminal state
+- `ctheme list`: list bundled and saved themes
+- `ctheme preview <theme>`: inspect palette colors in the current shell
+- `ctheme make`: create a theme from flags or launch the wizard
+- `ctheme wizard`: force the interactive onboarding flow
+- `ctheme init <name>`: create a starter theme file
+- `ctheme term <target>`: generate or apply terminal-target snippets
+- `ctheme font ...`: search, install, and list fonts
+
+## Internal Architecture
+
+### 1. Presets
+
+Bundled presets are plain palette objects in `PRESETS`.
+
+Each preset should carry:
+
+- colors
+- terminal font
+- UI font
+- code font
+
+The bundled presets should feel visibly distinct. Avoid making every theme share the same font pairing.
+
+### 2. Theme Building
+
+`buildTheme()` turns a palette into the normalized theme object used by preview and terminal rendering.
+
+Important rule:
+
+- readability wins over palette purity
+
+Light themes in particular are normalized through contrast helpers so accents and syntax colors remain readable.
+
+### 3. Terminal Writers
+
+Target-specific renderers:
+
+- `renderAppleTerminalProfile()`
+- `renderGhosttySnippet()`
+- `renderKittySnippet()`
+- `renderWeztermSnippet()`
+
+Target-specific application:
+
+- Apple Terminal applies live through AppleScript
+- Ghostty and Kitty get include lines appended
+- WezTerm writes a standalone file when safe
+
+### 4. Wizard Flow
+
+The wizard is implemented in `runMakeWizard()`.
+
+Current flow:
+
+1. pick a base preset
+2. name the theme
+3. adjust colors
+4. choose fonts
+5. review summary
+6. save
+7. optionally install fonts
+8. optionally apply live
+
+When changing the wizard:
+
+- keep prompts short
+- always show a default
+- keep blank input as “accept default”
+- prefer a summary/confirmation before writing files
+
+### 5. Font Helpers
+
+Font listing uses macOS AppKit through JXA.
+
+Google Fonts install flow:
+
+1. search metadata from `fonts.google.com`
+2. resolve family path from `google/fonts`
+3. download font files into `~/Library/Fonts/pretty-code`
+
+Do not bundle font files in the repo.
+
+## Local Development
+
+Install the CLI locally:
+
+```bash
+npm install -g . --force
+```
+
+Basic smoke checks:
+
+```bash
+ctheme --help
+ctheme list
+ctheme preview solarized
+ctheme font list
+ctheme status
+```
+
+## Manual Test Matrix
+
+### Apple Terminal
+
+```bash
+ctheme use solarized
+ctheme use harbor --default
+ctheme reset
+```
+
+Verify:
+
+- theme applies immediately
+- `--default` changes startup/default profile
+- `reset` restores the saved profile or `Basic`
+
+### Wizard
+
+```bash
+ctheme wizard
+ctheme make
+ctheme make mytheme --preset harbor --terminal-font "Space Mono"
+```
+
+Verify:
+
+- defaults are shown
+- summary appears before writing
+- saved JSON lands in `~/.ctheme/themes`
+- `ctheme use mytheme` picks up the saved terminal font
+
+### Fonts
+
+```bash
+ctheme font search "mono"
+ctheme font install "IBM Plex Mono"
+ctheme font list
+```
+
+Verify:
+
+- search returns real families
+- install downloads files into `~/Library/Fonts/pretty-code`
+- list prints real family names, not ObjC bridge values
+
+### Pack/Publish
+
+```bash
+npm test
+npm pack --dry-run
+npm publish --dry-run
+```
+
+## Release Process
+
+1. update version in `package.json`
+2. run smoke tests
+3. run `npm pack --dry-run`
+4. run `npm publish --dry-run`
+5. commit
+6. push `main`
+7. publish for real with `npm publish`
+
+## Contribution Rules
+
+- Keep the product terminal-focused.
+- Prefer short commands over complicated command trees.
+- Preserve live-apply behavior wherever possible.
+- When a target cannot reload live, say that clearly.
+- Avoid growing the tool into a general desktop-theme manager.
+- Do not reintroduce Codex/editor/app-specific behavior.
+- Do not add hidden state outside `~/.ctheme` and the managed fonts directory.
+
+## Git Hygiene
+
+This repo should stay self-contained.
+
+- commit from `/Users/arjunkshah21/Downloads/pretty-code`
+- push to `origin main`
+- do not mix unrelated parent-directory changes into this repo

package/README.md

@@ -71,6 +71,7 @@ The wizard walks through:
 - terminal font
 - UI font
 - code font
+- theme summary before save
 - optional Google Fonts install
 - optional live apply
 

package/bin/ctheme.js

@@ -406,179 +406,6 @@ const PRESETS = {
   }
 };
 
-const APP_PRESETS = {
-  evergreen: {
-    codeThemeId: "everforest",
-    theme: {
-      accent: "#93b259",
-      contrast: 45,
-      fonts: { code: "IBM Plex Mono", ui: "Manrope" },
-      ink: "#5c6a72",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#8da101",
-        diffRemoved: "#f85552",
-        skill: "#df69ba"
-      },
-      surface: "#fdf6e3"
-    },
-    variant: "light"
-  },
-  "evergreen-dark": {
-    codeThemeId: "everforest",
-    theme: {
-      accent: "#a7c080",
-      contrast: 60,
-      fonts: { code: "IBM Plex Mono", ui: "Manrope" },
-      ink: "#d3c6aa",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#a7c080",
-        diffRemoved: "#e67e80",
-        skill: "#d699b6"
-      },
-      surface: "#2d353b"
-    },
-    variant: "dark"
-  },
-  solarized: {
-    codeThemeId: "solarized",
-    theme: {
-      accent: "#268bd2",
-      contrast: 45,
-      fonts: { code: "Source Code Pro", ui: "Manrope" },
-      ink: "#586e75",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#859900",
-        diffRemoved: "#dc322f",
-        skill: "#d33682"
-      },
-      surface: "#fdf6e3"
-    },
-    variant: "light"
-  },
-  "solarized-dark": {
-    codeThemeId: "solarized",
-    theme: {
-      accent: "#268bd2",
-      contrast: 60,
-      fonts: { code: "Source Code Pro", ui: "Manrope" },
-      ink: "#839496",
-      opaqueWindows: false,
-      semanticColors: {
-        diffAdded: "#859900",
-        diffRemoved: "#dc322f",
-        skill: "#d33682"
-      },
-      surface: "#002b36"
-    },
-    variant: "dark"
-  },
-  nord: {
-    codeThemeId: "nord",
-    theme: {
-      accent: "#5e81ac",
-      contrast: 48,
-      fonts: { code: "Space Mono", ui: "Manrope" },
-      ink: "#4c566a",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#a3be8c",
-        diffRemoved: "#bf616a",
-        skill: "#b48ead"
-      },
-      surface: "#eceff4"
-    },
-    variant: "light"
-  },
-  "nord-dark": {
-    codeThemeId: "nord",
-    theme: {
-      accent: "#88c0d0",
-      contrast: 60,
-      fonts: { code: "Space Mono", ui: "Manrope" },
-      ink: "#e5e9f0",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#a3be8c",
-        diffRemoved: "#bf616a",
-        skill: "#b48ead"
-      },
-      surface: "#2e3440"
-    },
-    variant: "dark"
-  },
-  rosepine: {
-    codeThemeId: "rose-pine-dawn",
-    theme: {
-      accent: "#56949f",
-      contrast: 44,
-      fonts: { code: "DM Mono", ui: "Manrope" },
-      ink: "#575279",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#286983",
-        diffRemoved: "#b4637a",
-        skill: "#907aa9"
-      },
-      surface: "#faf4ed"
-    },
-    variant: "light"
-  },
-  "rosepine-dark": {
-    codeThemeId: "rose-pine",
-    theme: {
-      accent: "#9ccfd8",
-      contrast: 58,
-      fonts: { code: "DM Mono", ui: "Manrope" },
-      ink: "#e0def4",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#31748f",
-        diffRemoved: "#eb6f92",
-        skill: "#c4a7e7"
-      },
-      surface: "#191724"
-    },
-    variant: "dark"
-  },
-  graphite: {
-    codeThemeId: "github",
-    theme: {
-      accent: "#586069",
-      contrast: 42,
-      fonts: { code: "IBM Plex Mono", ui: "Manrope" },
-      ink: "#24292f",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#1a7f37",
-        diffRemoved: "#cf222e",
-        skill: "#8250df"
-      },
-      surface: "#f6f8fa"
-    },
-    variant: "light"
-  },
-  "graphite-dark": {
-    codeThemeId: "github",
-    theme: {
-      accent: "#7d8590",
-      contrast: 58,
-      fonts: { code: "IBM Plex Mono", ui: "Manrope" },
-      ink: "#c9d1d9",
-      opaqueWindows: true,
-      semanticColors: {
-        diffAdded: "#3fb950",
-        diffRemoved: "#f85149",
-        skill: "#d2a8ff"
-      },
-      surface: "#0d1117"
-    },
-    variant: "dark"
-  }
-};
-
 async function main() {
   try {
     const args = process.argv.slice(2);
@@ -862,11 +689,13 @@ async function runMakeWizard(initialName, flags) {
 
   try {
     const availablePresets = Object.keys(PRESETS).sort();
-    console.log(`Theme wizard`);
+    console.log("Theme wizard");
+    console.log("Press Enter to keep the default shown in brackets.");
     console.log(`Presets: ${availablePresets.join(", ")}`);
     console.log(`UI font ideas: ${FONT_CHOICES.ui.join(", ")}`);
     console.log(`Code/terminal font ideas: ${FONT_CHOICES.code.join(", ")}`);
 
+    console.log("\nStep 1: Base");
     const basePresetName = await promptWithDefault(
       rl,
       "Base preset",
@@ -876,6 +705,7 @@ async function runMakeWizard(initialName, flags) {
     const defaultName = initialName || `${basePresetName}-custom`;
     const themeName = await promptWithDefault(rl, "Theme name", defaultName);
 
+    console.log("\nStep 2: Colors");
     const accent = await promptWithDefault(rl, "Accent color", flags.accent || preset.accent);
     const bg = await promptWithDefault(rl, "Background color", flags.bg || preset.bg);
     const surface = await promptWithDefault(rl, "Surface color", flags.surface || preset.surface);
@@ -888,6 +718,7 @@ async function runMakeWizard(initialName, flags) {
     const muted = await promptWithDefault(rl, "Muted color", flags.muted || preset.muted);
     const dim = await promptWithDefault(rl, "Dim color", flags.dim || preset.dim);
 
+    console.log("\nStep 3: Fonts");
     const fonts = {
       terminal: await promptWithDefault(
         rl,
@@ -906,6 +737,26 @@ async function runMakeWizard(initialName, flags) {
       )
     };
 
+    console.log("\nTheme summary:");
+    printThemeSummary({
+      name: themeName,
+      preset: basePresetName,
+      accent,
+      bg,
+      surface,
+      surfaceAlt,
+      fg,
+      muted,
+      dim,
+      fonts
+    });
+
+    const shouldWrite = await promptYesNo(rl, "Save this theme?", true);
+    if (!shouldWrite) {
+      console.log("Cancelled.");
+      return;
+    }
+
     const autoInstallFonts = await promptYesNo(rl, "Install any missing Google fonts automatically?", true);
     if (autoInstallFonts) {
       installFontsBestEffort([fonts.terminal, fonts.ui, fonts.code]);
@@ -1367,6 +1218,21 @@ function installFontsBestEffort(fonts) {
   }
 }
 
+function printThemeSummary(theme) {
+  console.log(`  name: ${theme.name}`);
+  console.log(`  preset: ${theme.preset}`);
+  console.log(`  accent: ${theme.accent}`);
+  console.log(`  bg: ${theme.bg}`);
+  console.log(`  surface: ${theme.surface}`);
+  console.log(`  surface alt: ${theme.surfaceAlt}`);
+  console.log(`  text: ${theme.fg}`);
+  console.log(`  muted: ${theme.muted}`);
+  console.log(`  dim: ${theme.dim}`);
+  console.log(`  terminal font: ${theme.fonts.terminal}`);
+  console.log(`  ui font: ${theme.fonts.ui}`);
+  console.log(`  code font: ${theme.fonts.code}`);
+}
+
 function writeThemeAssets(paths, name, palette) {
   ensureDir(paths.paletteDir);
   fs.writeFileSync(path.join(paths.paletteDir, `${name}.json`), `${JSON.stringify(palette, null, 2)}\n`, "utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctheme",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Theme manager for making terminals look better with colors, fonts, and live profile switching",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,7 @@
   ],
   "files": [
     "bin",
+    "DEVELOPMENT.md",
     "README.md"
   ],
   "bin": {