Fix #3075: accept named colors in cmux.json and degrade gracefully on parse errors

[austinywang]

Summary

Fixes #3075. Before this PR, a single command in cmux.json with a named color (e.g. "color": "Indigo") caused the entire config file to be silently rejected — no commands loaded, cmux reload-config returned OK, and the sidebar showed no error. The decoder only accepted #RRGGBB hex strings, and one rejected command failed the whole top-level JSONDecoder().decode(CmuxConfigFile.self, ...) call.

Two-part fix:

• Accept named palette colors. CmuxWorkspaceDefinition now resolves the color field via a new resolveColor(_:) helper that accepts either a 6-digit hex (with/without #) or a case-insensitive match against WorkspaceTabColorSettings.defaultPalette (Red, Navy, Indigo, Purple, Charcoal, ...). "Indigo" now resolves to #283593.
• Degrade gracefully on parse errors. New CmuxConfigFile.parseLenient(_:) decodes each command independently. One malformed command (bad color, bad layout, missing fields, etc.) no longer poisons its siblings — it is returned as a warning alongside the commands that did load. CmuxConfigStore.parseConfig now uses this path and logs each warning via NSLog so misconfigured entries are visible.

This matches the issue's expected behavior: "Both commands appear, or at minimum Echo still appears and a parse warning is logged."

Two-commit structure (per project policy)

1. First commit adds failing regression tests only (named-color resolution + lenient parsing). CI should be red.
2. Second commit adds the fix. CI should be green.

Repro (from the issue)

{
  "commands": [
    {
      "name": "Indigo Workspace",
      "workspace": { "name": "Indigo", "color": "Indigo" }
    },
    { "name": "Echo", "command": "echo hi" }
  ]
}

• Before: neither command appeared; no error shown.
• After: both commands appear; the Indigo workspace uses #283593. If the color were a typo like "Indigoo", only that command is skipped (with a logged warning), and Echo still appears.

Test plan

• CI: unit tests in cmuxTests/CmuxConfigTests.swift pass on the fix commit.
• CI: the first commit fails the new tests (proves the tests exercise the bug).
• Manual: place the repro cmux.json in the project root, cmux reload-config, confirm both commands appear in the command palette with the Indigo color on the workspace.
• Manual: swap "Indigo" for "NotARealColor" and confirm Echo still appears in the palette and the system log shows a [CmuxConfig] Skipped command warning.

---

Note

Medium Risk
Changes config decoding behavior and error handling, which can affect which commands load from user cmux.json files. Risk is mitigated by added unit tests covering named colors and partial-failure parsing.

Overview
Fixes cmux.json regressions by accepting named palette colors (e.g. "Indigo", case-insensitive) for workspace color, resolving them to normalized hex.

Updates config loading to degrade gracefully on per-command decode failures via CmuxConfigFile.parseLenient, so malformed commands are skipped with logged warnings while valid sibling commands still load, instead of rejecting the entire file.

^{Reviewed by Cursor Bugbot for commit 62b8741. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Added support for named workspace colors (e.g., "Indigo", "Navy") with case-insensitive matching.

• Bug Fixes

  • Configuration parsing is now more resilient; invalid individual commands no longer prevent the entire configuration from loading, with warnings logged for skipped items.

• Tests

  • Added test coverage for named color resolution and lenient parsing behavior.

---

Summary by cubic

Fix #3075 by accepting named palette colors in cmux.json and making config loading tolerant. A bad command no longer drops the whole file; valid commands still load and a warning is logged.

• Bug Fixes
  • Color resolution: CmuxWorkspaceDefinition.resolveColor accepts 6-digit hex (with/without #) and case-insensitive names from WorkspaceTabColorSettings.defaultPalette (e.g. "Indigo" -> #283593).
  • Lenient loading: CmuxConfigFile.parseLenient decodes commands independently and returns warnings; CmuxConfigStore.parseConfig uses it and logs each warning via NSLog.

^{Written for commit 62b8741. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cmux	Ready	Preview, Comment	Apr 22, 2026 5:44am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7db3201a-180a-44ec-a0b1-5ed14f3614c4

📥 Commits

Reviewing files that changed from the base of the PR and between 3e84c16 and 62b8741.

📒 Files selected for processing (2)

• Sources/CmuxConfig.swift
• cmuxTests/CmuxConfigTests.swift

---

📝 Walkthrough

Walkthrough

The changes implement lenient JSON configuration parsing that preserves successfully decoded commands while capturing per-command failures as warnings. Additionally, a new color resolution helper is added to support both normalized hex values and case-insensitive named palette colors in workspace definitions.

Changes

Cohort / File(s)	Summary
Lenient Config Parsing Sources/CmuxConfig.swift	Added custom CodingKeys, init(commands:), init(from:), and encode(to:) methods to CmuxConfigFile. Introduced parseLenient(_:) static method that decodes the top-level structure, attempts per-command deserialization, and returns both successfully decoded commands and a warnings list. Updated CmuxConfigStore.parseConfig(at:) to use lenient parsing and log skip warnings.
Color Resolution Sources/CmuxConfig.swift	Added resolveColor(_:) helper to CmuxWorkspaceDefinition for flexible color validation accepting normalized 6-digit hex (with or without #) or case-insensitive named palette entries.
Test Coverage cmuxTests/CmuxConfigTests.swift	Added test cases verifying named color string resolution to palette hex values with case-insensitive matching, and comprehensive tests for parseLenient(_:) behavior including valid configurations with no warnings and individual command failures being isolated without affecting sibling commands.

Sequence Diagram

sequenceDiagram
    participant ConfigStore as CmuxConfigStore
    participant File as CmuxConfigFile
    participant Decoder as JSONDecoder
    participant Command as CmuxCommandDefinition
    participant Results as Result Buffer

    ConfigStore->>File: parseLenient(data)
    File->>Decoder: decode top-level structure
    Decoder-->>File: commands array
    File->>Results: initialize warnings list
    loop For each command
        File->>Decoder: decode CmuxCommandDefinition
        alt Success
            Decoder-->>Command: valid command
            Command-->>Results: add to successful commands
        else Failure
            Decoder-->>Results: capture error as warning
        end
    end
    File-->>ConfigStore: (file: CmuxConfigFile?, warnings: [String])
    ConfigStore->>ConfigStore: log warnings & parse result

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Lenient parsing hops with grace,
Commands fail, yet keep their place,
Colors named in palette true,
Warnings whisper, warnings brew,
Invalid friends aren't turned away,
Just logged as warnings of the day! 🌈

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly references issue #3075 and summarizes both main changes: accepting named colors and graceful error degradation on parse failures.
Description check	✅ Passed	The description covers all required template sections: a detailed summary explaining the problem and two-part fix, testing instructions with CI/manual steps, and a complete checklist with all items addressed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-3075-config-named-color-rejects

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR fixes #3075 by (1) teaching CmuxWorkspaceDefinition to resolve named palette colors (e.g. \"Indigo\" → #283593) via the new resolveColor helper, and (2) replacing the all-or-nothing JSONDecoder call in CmuxConfigStore.parseConfig with CmuxConfigFile.parseLenient, which decodes each command independently so a single malformed entry no longer silently rejects the entire config file. The two-commit structure and regression tests follow the project's policy.

Confidence Score: 5/5

Safe to merge; all remaining feedback is non-blocking style.

The core logic is correct: lenient decoding properly isolates per-command failures, named-color resolution is case-insensitive and falls back gracefully, and the existing strict init(from:) path is preserved for callers that need it. The only finding is a minor duplicate log line on catastrophic JSON failure (P2). Tests exercise the bug regression end-to-end and follow the project's test quality policy.

No files require special attention.

Important Files Changed

Filename	Overview
Sources/CmuxConfig.swift	Adds parseLenient for per-command fault isolation and resolveColor for named-palette color support; one minor logging redundancy on top-level failure, no correctness issues.
cmuxTests/CmuxConfigTests.swift	Adds regression tests for named-color decoding (Indigo, Navy, case-insensitive) and lenient parsing (bad color, bad layout, end-to-end named color); tests verify runtime behaviour, consistent with test quality policy.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[parseConfig at path] --> B{File exists & non-empty?}
    B -- No --> Z[return nil]
    B -- Yes --> C[parseLenient data]
    C --> D{Top-level JSON valid?}
    D -- No --> E[return nil + error warning]
    E --> F[log warning AND log generic message]
    F --> Z
    D -- Yes --> G[Decode each command independently]
    G --> H{Command decode OK?}
    H -- Yes --> I[append to commands]
    H -- No --> J[append to warnings with fallback name]
    I & J --> K[CmuxConfigFile with valid commands]
    K --> L{warnings empty?}
    L -- No --> M[NSLog each warning]
    L -- Yes --> N[return CmuxConfigFile]
    M --> N

    subgraph resolveColor
        RC1[raw string] --> RC2{normalizedHex succeeds?}
        RC2 -- Yes --> RC3[return hex]
        RC2 -- No --> RC4[trim whitespace]
        RC4 --> RC5{palette name match case-insensitive?}
        RC5 -- Yes --> RC6[return entry.hex]
        RC5 -- No --> RC7[return nil → DecodingError thrown]
    end

Loading

_{Reviews (1): Last reviewed commit: "Fix #3075: accept named colors in cmux.j..." | Re-trigger Greptile}

[greptile-apps]

Redundant log on top-level decode failure

When parseLenient cannot parse the top-level JSON structure, it returns (nil, [String(describing: error)]). The warnings loop on lines 477–479 already logs that error with the full description. The if file == nil block then emits a second, less-informative message ("top-level JSON could not be decoded") for the same event, producing two log lines where the second adds no new information.

Consider either dropping the if file == nil block (the warning already contains the error), or — if you want a dedicated "top-level failure" message — skip logging the generic error string in the warnings loop when file is nil:

let (file, warnings) = CmuxConfigFile.parseLenient(data)
if file == nil {
    // Top-level failure: parseLenient already put the error in warnings[0]
    NSLog("[CmuxConfig] parse error at %@: %@", path, warnings.first ?? "unknown error")
} else {
    for warning in warnings {
        NSLog("[CmuxConfig] Skipped command in %@: %@", path, warning)
    }
}
return file

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="Sources/CmuxConfig.swift">

<violation number="1" location="Sources/CmuxConfig.swift:480">
P3: Remove the extra top-level parse-error log here; top-level decode failures are already logged via `warnings`, so this produces duplicate entries and the second message is less informative.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P3: Remove the extra top-level parse-error log here; top-level decode failures are already logged via warnings, so this produces duplicate entries and the second message is less informative.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At Sources/CmuxConfig.swift, line 480:

<comment>Remove the extra top-level parse-error log here; top-level decode failures are already logged via `warnings`, so this produces duplicate entries and the second message is less informative.</comment>

<file context>
@@ -391,12 +473,14 @@ final class CmuxConfigStore: ObservableObject {
+        for warning in warnings {
+            NSLog("[CmuxConfig] %@: %@", path, warning)
+        }
+        if file == nil {
+            NSLog("[CmuxConfig] parse error at %@: top-level JSON could not be decoded", path)
         }
</file context>