diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9725093 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,11 @@ +# Code of Conduct + +This project adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). + +The full text — including the standards we hold ourselves to, the enforcement guidelines, and the rationale — lives at the canonical URL above and is the authoritative version for this project. + +## Reporting + +If you experience or witness behavior that violates the Code of Conduct, report it privately to **thraen@gmail.com**. Reports will be reviewed promptly. The maintainers will respect the reporter's privacy and will only share details with people who need them to act on the report. + +For security-sensitive reports (vulnerabilities), use the channel in [SECURITY.md](SECURITY.md) instead. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..486ced7 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Contributing to CodeShellManager + +Thanks for considering a contribution. CodeShellManager is a small, opinionated WPF host for terminal CLIs (Claude Code, Codex, pwsh, ssh, etc.) — bug fixes and focused features are welcome. + +## Before you start + +- For bug fixes: open an issue first only if you want to confirm the diagnosis. Otherwise, just send the PR. +- For features: open an issue (or a Discussion) and get a thumbs-up before investing time. The bar for "is this in scope" is "would the maintainers use it daily?". +- Check [CLAUDE.md](../CLAUDE.md) for the architecture overview, conventions, and lifecycle invariants. It's the most useful single document for getting oriented. + +## Build and run + +Requires .NET 10 SDK and Windows 10/11 (the app uses ConPTY and WebView2). + +```bash +dotnet build src/CodeShellManager/CodeShellManager.csproj +dotnet run --project src/CodeShellManager/CodeShellManager.csproj +``` + +Or open `CodeShellManager.slnx` in Visual Studio / Rider. + +### Testing without touching real state + +The `--clean` flag boots with no restored sessions and skips writing to `state.json` for the entire run. Use it whenever you're poking at lifecycle, restore, or settings code so your real session list isn't disturbed: + +```bash +dotnet run --project src/CodeShellManager/CodeShellManager.csproj -- --clean +``` + +## Tests + +```bash +dotnet test tests/CodeShellManager.Tests/ +``` + +Unit tests cover model/service logic and run headless. UI tests live in `tests/CodeShellManager.UITests/` and require a live Windows desktop session — they're optional locally but run in CI. + +If your change touches a model, service, or anything with a clean unit boundary, add a test. UI-only tweaks don't need one. + +## Branch naming + +- `feat/` — new feature +- `fix/` — bug fix +- `chore/` — tooling, repo hygiene, dependency bumps +- `docs/` — documentation only + +## Commit messages + +Conventional-commit-ish: `type(scope): subject` in lowercase, no trailing period. + +``` +feat(sidebar): group bulk actions, empty-area quick menu, sort +fix(shutdown): guard OnClosing against re-entry during async cleanup +perf: precompute Sessions dict in RebuildSidebarOrder to drop O(n^2) +docs: document OSC 9001 shell integration +``` + +The body should explain the *why* — the diff already shows the *what*. + +## Pull requests + +- Target `main`. +- Keep the PR small and focused. If you find an unrelated bug along the way, ship it in its own PR. +- Use the PR template — it asks for a summary, motivation, and a test plan checklist. +- CI must be green. The `build` workflow compiles and runs unit + UI tests. +- Expect a code review pass from the bot reviewer (Copilot) and a maintainer. Address the substantive points; nitpicks are negotiable. +- Don't squash commits manually before merge — the maintainer will pick the right merge strategy when landing. + +## Issues and labels + +Two labels are in active use: + +- `bug` — auto-applied by the bug report template +- `enhancement` — auto-applied by the feature request template + +Dependabot PRs get `dependencies` automatically. + +Please don't open issues for usage questions — use [Discussions](https://github.com/umage-ai/CodeShellManager/discussions) instead. + +## Code style + +- Match what's already there. There's no autoformatter beyond `dotnet format` defaults. +- WPF code-behind for sidebar/terminal UI is intentional (see CLAUDE.md "Known Conventions"); don't move it to XAML templates. +- Catppuccin Mocha hex values only — no system colors. +- Comments explain *why*, not *what*. If a comment would just restate the code, leave it out. + +## License + +By contributing, you agree your contribution is licensed under the same license as the project (see [LICENSE](../LICENSE)). diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..7d00523 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,84 @@ +name: Bug report +description: Something is broken or behaving wrong +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug. The more concrete the repro, the faster it gets fixed. + + Please first check the [open issues](https://github.com/umage-ai/CodeShellManager/issues?q=is%3Aissue) to see if it's already reported. + + - type: textarea + id: description + attributes: + label: Description + description: What happened, in one paragraph. + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Minimal numbered steps that hit the bug from a clean state. If the `--clean` flag changes the outcome, please mention. + placeholder: | + 1. Launch CodeShellManager + 2. ... + 3. ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected vs actual behaviour + description: What you expected to see, and what you actually saw. + validations: + required: true + + - type: input + id: version + attributes: + label: CodeShellManager version + description: From the title bar / About dialog, or the installer file name (e.g. `v0.4.2`). + placeholder: v0.4.2 + validations: + required: true + + - type: input + id: windows + attributes: + label: Windows version + description: Run `winver` and paste the version (e.g. `Windows 11 24H2 build 26200`). + validations: + required: true + + - type: input + id: dotnet + attributes: + label: .NET runtime + description: Output of `dotnet --version` (or skip if you're running a packaged release and don't have the SDK installed). + placeholder: 10.0.100 + + - type: input + id: cli + attributes: + label: CLI tool and version + description: If the bug involves a specific CLI hosted in a session (claude, codex, pwsh, ssh, etc.), give the tool name and version. + placeholder: claude 1.0.65 + + - type: textarea + id: log + attributes: + label: crash.log excerpt + description: | + If there's anything in `%AppData%\CodeShellManager\crash.log` around the time of the bug, paste the relevant lines here. + For terminal freezes, enabling **Settings -> Diagnostics -> Trace terminal input/output timing to crash.log** before reproducing the bug captures `[DEBUG-tt]` timing lines that are very useful. + render: text + + - type: textarea + id: extra + attributes: + label: Anything else + description: Screenshots, screen recordings, sample state.json (sanitised) — whatever helps. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..b9188de --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Question or discussion + url: https://github.com/umage-ai/CodeShellManager/discussions + about: For "how do I…?", design ideas, or anything that isn't a confirmed bug or a concrete feature request. + - name: Security vulnerability + url: https://github.com/umage-ai/CodeShellManager/security/advisories/new + about: Please do not file a public issue. Use a private security advisory or see SECURITY.md. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..9e5cbd7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,48 @@ +name: Feature request +description: Suggest a new capability or a meaningful enhancement +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for proposing an idea. Please first skim the [open enhancement issues](https://github.com/umage-ai/CodeShellManager/issues?q=is%3Aissue+label%3Aenhancement) to see if it's already on the list. + + For open-ended ideas or "how should we approach X?" questions, [Discussions](https://github.com/umage-ai/CodeShellManager/discussions) is usually a better starting point than an issue. + + - type: textarea + id: problem + attributes: + label: Problem or motivation + description: What are you trying to do that CSM doesn't currently let you do (or makes hard)? Concrete user-story phrasing helps. + placeholder: | + When I have many sessions across multiple projects, I can't see at a glance which ones are still claude-active vs idle. + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed solution + description: What would you like CSM to do? UI sketch, behavior, settings — whatever you have in mind. Don't worry about whether it's implementable. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches you thought about, or workarounds you're using today. + + - type: textarea + id: mockups + attributes: + label: Mockups, screenshots, or examples + description: Drag-drop images or paste links. Examples from other tools that do this well are welcome. + + - type: checkboxes + id: scope + attributes: + label: Scope check + options: + - label: I've checked this isn't already an open issue + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..575d9fe --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ +## Summary + + + +## Why + + + +## Implementation notes + + + +## Test plan + + + +- [ ] + +## Screenshots + + diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..88d8db0 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,46 @@ +# Security Policy + +CodeShellManager is a Windows desktop application that hosts terminal CLIs locally via ConPTY and WebView2, indexes terminal output to a local SQLite database, and persists session state to `%AppData%\CodeShellManager\state.json`. The attack surface is primarily local — there is no network listener and no remote control interface. The most security-relevant areas are: + +- The PTY hosting layer (`Terminal/PseudoTerminal.cs`, `Terminal/TerminalBridge.cs`) +- The WebView2-hosted xterm.js page and its message bridge (`Assets/terminal.html`, `terminal-init.js`) +- SSH session launching (`ShellSession.BuildSshArgs`) +- Per-session run-command execution (`Services/SessionRunner.cs`) +- State and crash-log files under `%AppData%\CodeShellManager\` + +## Supported versions + +Only the latest published release is supported. See the [Releases](https://github.com/umage-ai/CodeShellManager/releases) page. + +| Version | Supported | +| ----------------- | --------- | +| Latest release | Yes | +| Older releases | No | + +If you're on an older version, please reproduce on the latest release before reporting. + +## Reporting a vulnerability + +**Please do not file a public issue for security reports.** Use one of the following private channels: + +1. **GitHub Security Advisories** (preferred): https://github.com/umage-ai/CodeShellManager/security/advisories/new +2. **Email**: thraen@gmail.com + +Include: + +- A clear description of the issue and its impact +- Steps to reproduce (or a proof-of-concept) +- The CSM version (Settings -> About, or the installer file name) +- Your Windows version and any relevant runtime info (`dotnet --info`) +- Whether you'd like credit in the advisory + +We aim to acknowledge reports within 5 business days and to ship a fix or mitigation within 30 days for high-severity issues. We will coordinate disclosure with you and credit you in the advisory unless you prefer otherwise. + +## Out of scope + +The following are not considered vulnerabilities: + +- A user with local access to the machine being able to read their own state.json or crash.log (these live in the user's `%AppData%`). +- Behavior of the third-party CLIs hosted in a session (Claude Code, Codex, ssh, etc.). +- Self-XSS or social-engineering scenarios where the user is tricked into pasting attacker-controlled content into a terminal. +- Vulnerabilities in WebView2 / Edge runtime, .NET, or other upstream components — please report those upstream. diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 0000000..961155c --- /dev/null +++ b/.github/SUPPORT.md @@ -0,0 +1,9 @@ +# Getting Help + +- **Usage questions, ideas, "how do I…?"** -> [Discussions](https://github.com/umage-ai/CodeShellManager/discussions) +- **Bugs and crashes** -> [open a bug report](https://github.com/umage-ai/CodeShellManager/issues/new?template=bug_report.yml) +- **Feature requests** -> [open a feature request](https://github.com/umage-ai/CodeShellManager/issues/new?template=feature_request.yml) +- **Security issues** -> see [SECURITY.md](SECURITY.md) — please do not file a public issue +- **Code of Conduct concerns** -> see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) + +When filing a bug, attach the relevant section of `%AppData%\CodeShellManager\crash.log` if there is one — it's the single most useful thing for diagnosing terminal/lifecycle issues. The `Trace terminal input/output timing to crash.log` setting under Settings -> Diagnostics can help capture more detail when a freeze is reproducible. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..3621800 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,23 @@ +version: 2 +updates: + - package-ecosystem: "nuget" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + open-pull-requests-limit: 5 + groups: + nuget: + patterns: + - "*" + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + open-pull-requests-limit: 5 + groups: + actions: + patterns: + - "*"