Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ labels: bug

> **Is this a Terminal.Gui core bug?**
> If the issue is in rendering, a driver, a built-in View, or keybindings, it belongs in
> [`gui-cs/Terminal.Gui`](https://github.com/gui-cs/Terminal.Gui/issues).
> [`tui-cs/Terminal.Gui`](https://github.com/tui-cs/Terminal.Gui/issues).
> Not sure? File here first. The clet maintainer will reproduce, isolate, and escalate
> upstream if the root cause turns out to be in TG core (spec §2.1).

Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ resolve-version → build (3 RIDs) → tag → publish-nuget

**NuGet:** Main publishes to package id `clet` (see [D-024](../../specs/decisions.md)). Prerelease versions (`-rc`) are hidden from default `dotnet tool install -g clet`; consumers opt in with `--prerelease`.

**Homebrew / WinGet:** Only on stable main releases (version has no `-` suffix). Both are placeholders until `gui-cs/homebrew-tap` exists and WinGet tooling is wired (D-012).
**Homebrew / WinGet:** Only on stable main releases (version has no `-` suffix). Both are placeholders until `tui-cs/homebrew-tap` exists and WinGet tooling is wired (D-012).

## Terminal.Gui versions

Expand All @@ -77,7 +77,7 @@ Release builds reject Terminal.Gui or Terminal.Gui.Editor versions older than th
| Name | Type | Used by | Purpose |
|------|------|---------|---------|
| `NUGET_API_KEY` | Secret | `publish-nuget` | Push packages to nuget.org |
| `HOMEBREW_TAP_TOKEN` | Secret | `publish-homebrew` | Push to `gui-cs/homebrew-tap` |
| `HOMEBREW_TAP_TOKEN` | Secret | `publish-homebrew` | Push to `tui-cs/homebrew-tap` |
| `HOMEBREW_TAP_ENABLED` | Variable | `publish-homebrew` | Set to `true` to enable |
| `WINGET_ENABLED` | Variable | `publish-winget` | Set to `true` to enable |

Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ name: Release
#
# Triggers:
# 1. Push to main that changes code
# 2. repository_dispatch from gui-cs/Terminal.Gui (any main-branch publish: rc, beta, stable)
# 3. repository_dispatch from gui-cs/Editor (any main-branch publish)
# 2. repository_dispatch from tui-cs/Terminal.Gui (any main-branch publish: rc, beta, stable)
# 3. repository_dispatch from tui-cs/Editor (any main-branch publish)
# 4. Manual workflow_dispatch
on:
push:
Expand Down Expand Up @@ -465,7 +465,7 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
repository: gui-cs/homebrew-tap
repository: tui-cs/homebrew-tap
token: ${{ secrets.HOMEBREW_TAP_TOKEN }}

- name: Download macOS artifacts
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ The repo intentionally splits "design intent" from "current code" from "queued c
- **`specs/clet-spec.md`** — authoritative design document. Planned clets, exit code semantics, JSON schema (§4.3 + §4.3.1 versioning + §4.3.2 per-clet shapes), milestone roadmap (§7), risks (§8), open questions (§9), auto-discovery exploration (§11). Where the spec and current code diverge, the decisions log says why. **§6 (Testing) is a thin pointer** to `tests/SPEC.md`.
- **`tests/SPEC.md`** — authoritative testing strategy. Nine test layers, tier matrix (which layers run when), per-layer cases, harness shapes, golden-file conventions. Lives next to the test projects so it stays in sync. The main spec defers to it for everything in `tests/`.
- **`specs/decisions.md`** — historical log of cross-cutting decisions. **Read-only reference** — do not append new entries. New design rationale goes in the PR description instead. Existing entries are still useful context for understanding *why* something was built a certain way (e.g. D-006 for the hand-rolled parser, D-007 for deferred TUIcast).
- **[Bar-raise backlog issue #11](https://github.com/gui-cs/clet/issues/11)** (label `bar-raise`) — critique that's been raised, considered, and *not yet* acted on. Before claiming a section is "done," check the backlog for queued items in that area. New design pushback goes there, not into a side conversation.
- **[Bar-raise backlog issue #11](https://github.com/tui-cs/clet/issues/11)** (label `bar-raise`) — critique that's been raised, considered, and *not yet* acted on. Before claiming a section is "done," check the backlog for queued items in that area. New design pushback goes there, not into a side conversation.
- **`docs/runbooks/release-rollback.md`** — operational runbook for withdrawing a bad release across Homebrew/WinGet/NuGet. Draft until exercised at v0.9.

### Doc-update gate for every PR
Expand Down
6 changes: 3 additions & 3 deletions Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>

<Authors>gui-cs</Authors>
<Company>gui-cs</Company>
<Copyright>Copyright (c) gui-cs and contributors</Copyright>
<Authors>tui-cs</Authors>
<Company>tui-cs</Company>
<Copyright>Copyright (c) tui-cs and contributors</Copyright>

<!-- Pinned Terminal.Gui version. CI / release workflows can override via -p:TerminalGuiVersion=<x>. -->
<TerminalGuiVersion Condition="'$(TerminalGuiVersion)' == ''">2.4.5</TerminalGuiVersion>
Expand Down
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ Works for humans and AI agents alike.
### Release (not available until v1.0 is released)

```sh
brew install gui-cs/tap/clet # macOS / Linux
winget install gui-cs.clet # Windows 10/11
brew install tui-cs/tap/clet # macOS / Linux
winget install tui-cs.clet # Windows 10/11
dotnet tool install -g clet # any platform with .NET SDK
```

Expand Down Expand Up @@ -143,7 +143,7 @@ Exit codes:

## RC feedback

clet is in **release candidate** status ([milestone tracker](https://github.com/gui-cs/clet/issues/33)). If something doesn't work, looks wrong, or is just confusing, **[file an issue](https://github.com/gui-cs/clet/issues/new)**. Include:
clet is in **release candidate** status ([milestone tracker](https://github.com/tui-cs/clet/issues/33)). If something doesn't work, looks wrong, or is just confusing, **[file an issue](https://github.com/tui-cs/clet/issues/new)**. Include:

- `clet --version` output (e.g. `1.0.0-rc.3 (Terminal.Gui 2.0.2-develop.37)`).
- Your terminal + OS (e.g. "Windows Terminal on Windows 11", "iTerm2 on macOS 15").
Expand Down Expand Up @@ -228,7 +228,7 @@ Here's `clet color` with the Anders theme applied:

![clet color with Anders theme](./docs/images/clet-color.gif)

All clets render with the `Base` color scheme, so customizing `Base` controls every clet's appearance. See the [Terminal.Gui Configuration docs](https://gui-cs.github.io/Terminal.Gui/docs/configuration.html) for the full schema.
All clets render with the `Base` color scheme, so customizing `Base` controls every clet's appearance. See the [Terminal.Gui Configuration docs](https://tui-cs.github.io/Terminal.Gui/docs/configuration.html) for the full schema.

### Q: Key bindings?

Expand Down Expand Up @@ -256,11 +256,11 @@ Releases from `main` publish prerelease packages to NuGet (versioned `1.x.y-rc.N

### Q: How do I report a bug or give feedback?

[File an issue](https://github.com/gui-cs/clet/issues/new). That's the only feedback channel — no Discussions, no forum. See the [RC feedback](#rc-feedback) section above for what to include.
[File an issue](https://github.com/tui-cs/clet/issues/new). That's the only feedback channel — no Discussions, no forum. See the [RC feedback](#rc-feedback) section above for what to include.

## Native binaries install

Every [GitHub release](https://github.com/gui-cs/clet/releases) ships standalone NativeAOT binaries for the three primary platforms. **No .NET runtime required** — single-file executable, ~20 MB, cold-start in tens of milliseconds.
Every [GitHub release](https://github.com/tui-cs/clet/releases) ships standalone NativeAOT binaries for the three primary platforms. **No .NET runtime required** — single-file executable, ~20 MB, cold-start in tens of milliseconds.

| Platform | Asset |
|---|---|
Expand All @@ -273,7 +273,7 @@ Every [GitHub release](https://github.com/gui-cs/clet/releases) ships standalone
**macOS (Apple Silicon):**
```sh
# Replace <version> with the release tag, e.g. 1.0.0-develop.41
curl -LO https://github.com/gui-cs/clet/releases/latest/download/clet-<version>-osx-arm64.tar.gz
curl -LO https://github.com/tui-cs/clet/releases/latest/download/clet-<version>-osx-arm64.tar.gz
tar -xzf clet-<version>-osx-arm64.tar.gz
xattr -d com.apple.quarantine ./clet # clear Gatekeeper quarantine
sudo mv clet /usr/local/bin/
Expand All @@ -282,7 +282,7 @@ clet --version

**Linux x64:**
```sh
curl -LO https://github.com/gui-cs/clet/releases/latest/download/clet-<version>-linux-x64.tar.gz
curl -LO https://github.com/tui-cs/clet/releases/latest/download/clet-<version>-linux-x64.tar.gz
tar -xzf clet-<version>-linux-x64.tar.gz
chmod +x ./clet
sudo mv clet /usr/local/bin/
Expand All @@ -292,7 +292,7 @@ clet --version
**Windows x64 (PowerShell):**
```powershell
# Replace <version> with the release tag
Invoke-WebRequest -Uri "https://github.com/gui-cs/clet/releases/latest/download/clet-<version>-win-x64.zip" -OutFile clet.zip
Invoke-WebRequest -Uri "https://github.com/tui-cs/clet/releases/latest/download/clet-<version>-win-x64.zip" -OutFile clet.zip
Expand-Archive clet.zip -DestinationPath $env:USERPROFILE\bin\clet
# Add $env:USERPROFILE\bin\clet to your PATH, then:
clet --version
Expand Down
22 changes: 11 additions & 11 deletions docs/runbooks/release-rollback.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

> **Status:** DRAFT — exercised once before v0.9 RC per `specs/clet-spec.md` §7. Until that exercise has happened, treat every step here as "best guess; verify before executing."

> **Audience:** the maintainer paged at 3am for a `clet` release that escaped the §5.3 smoke gate. Assume you did not ship the bad release. Assume you have repo-admin on `gui-cs/clet`, push access to `gui-cs/homebrew-tap`, the WinGet PR-author cred, and the NuGet API key in a known location.
> **Audience:** the maintainer paged at 3am for a `clet` release that escaped the §5.3 smoke gate. Assume you did not ship the bad release. Assume you have repo-admin on `tui-cs/clet`, push access to `tui-cs/homebrew-tap`, the WinGet PR-author cred, and the NuGet API key in a known location.

`clet` auto-publishes from the `main` release workflow:

- **Prerelease phase** (`-rc` suffix from `src/Clet/Clet.csproj`): NuGet `clet` prerelease only (off `latest`; opt-in via `--prerelease`). See [D-024](../../specs/decisions.md) for the package id.
- **Stable phase** (no `-` suffix in version): NuGet `clet` (latest), Homebrew (gui-cs tap), WinGet (`microsoft/winget-pkgs`).
- **Stable phase** (no `-` suffix in version): NuGet `clet` (latest), Homebrew (tui-cs tap), WinGet (`microsoft/winget-pkgs`).

When the §5.3 smoke gate fails, the workflow halts and nothing reaches users — that case is an *aborted* release, not a *bad* release, and is out of scope for this runbook. This runbook covers the case where the gate let something through (a regression it didn't cover, a manifest bug, a signing failure mid-publish) and one or more channels carry a broken `clet`.

Expand All @@ -28,17 +28,17 @@ If you are not sure, rollback. Re-publishing later is cheap; pulling back a bad

> Run withdrawals **in parallel** if you have help. Each channel is independent; nothing here serializes.

### 2.1 Homebrew tap (`gui-cs/homebrew-tap`)
### 2.1 Homebrew tap (`tui-cs/homebrew-tap`)

**What happens to users:** Already-installed bad version stays on the user's machine until they `brew upgrade`. After withdrawal, `brew upgrade clet` resolves to the prior-known-good version.

**Steps:**

1. `git clone https://github.com/gui-cs/homebrew-tap`
1. `git clone https://github.com/tui-cs/homebrew-tap`
2. Identify the commit that bumped `clet.rb` to the bad version.
3. **`git revert <sha>`** — never `--force` push, never `reset --hard`. The revert preserves the audit trail and re-pins to the prior version's bottle URLs and SHA256s.
4. `git push origin main` (or whatever the tap's default branch is).
5. Verify: on a fresh runner, `brew update && brew info gui-cs/tap/clet` should report the prior version.
5. Verify: on a fresh runner, `brew update && brew info tui-cs/tap/clet` should report the prior version.
6. Optional: post a one-liner to the tap repo's Discussions explaining the revert.

**Caveat:** Homebrew bottles are immutable on GitHub Releases by URL. The bad bottle URL still resolves; it's just no longer pointed to. If you need the bad bottle file *gone* (license/security reason), delete the asset from the GitHub Release manually — but `brew install` will then 404 for anyone who has the old formula in cache.
Expand All @@ -50,20 +50,20 @@ If you are not sure, rollback. Re-publishing later is cheap; pulling back a bad
**Steps:**

1. Fork `microsoft/winget-pkgs` if you don't already have a fork.
2. Delete the directory `manifests/g/gui-cs/clet/<bad-version>/` from the fork.
3. Open a PR titled `Remove gui-cs.clet <bad-version> (broken release)` with a one-paragraph explanation.
2. Delete the directory `manifests/g/tui-cs/clet/<bad-version>/` from the fork.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Use the t-prefixed WinGet manifest path

When rolling back a Windows release after the package id has been renamed to tui-cs.clet, this directory will not exist: WinGet stores manifests as manifests/<lowercase first publisher letter>/<publisher>/<app>/<version>, so the manifest to remove is under manifests/t/tui-cs/clet/.... Leaving the old g prefix here sends the maintainer to the wrong folder and can delay the removal PR for a bad release.

Useful? React with 👍 / 👎.

3. Open a PR titled `Remove tui-cs.clet <bad-version> (broken release)` with a one-paragraph explanation.
4. Microsoft's bot validates and merges if the manifest removal is clean. **Typical SLA: 2–24 hours.** There is no faster path; WinGet does not have an emergency-yank API.
5. Verify post-merge: `winget search clet` should no longer list the bad version.

**While the PR is pending,** consider posting a GitHub Release note on `gui-cs/clet` warning Windows users not to upgrade.
**While the PR is pending,** consider posting a GitHub Release note on `tui-cs/clet` warning Windows users not to upgrade.

### 2.3 NuGet (`clet`)

**What happens to users:** Existing installs continue to work. New installs of the unlisted version still resolve **if the user pins the version explicitly** — unlist hides from search/default-resolve, it does not hard-delete. New `dotnet tool install -g clet` (no version pin) resolves to the next-newest *listed* version.

**Steps:**

1. Sign in to `https://www.nuget.org` with the gui-cs account.
1. Sign in to `https://www.nuget.org` with the tui-cs account.
2. Navigate to `Manage Packages → clet → <bad-version>`.
3. Click **Unlist** and confirm. (`dotnet nuget delete` is a list-only op, equivalent — use the web UI for the audit trail.)
4. Verify: `dotnet tool search clet` should not surface the bad version.
Expand All @@ -87,7 +87,7 @@ Once channels are withdrawn (or while the WinGet PR is pending):

Within 48 hours of stabilization:

1. File an issue in `gui-cs/clet` titled `Incident: <TG_VERSION> rollback`. Tag `incident`. Include: timeline (UTC), trigger, blast radius (channels affected, estimated user count if available), root cause, fix.
1. File an issue in `tui-cs/clet` titled `Incident: <TG_VERSION> rollback`. Tag `incident`. Include: timeline (UTC), trigger, blast radius (channels affected, estimated user count if available), root cause, fix.
2. Add the failure mode as a new case to `tests/Clet.SmokeTests` (so a future regression of the same shape is caught) and to the §6.8 release-pipeline dry-run cases (so a future pipeline regression of the same shape is caught).
3. If a runbook step here was wrong or missing, **edit this file** in the same PR. The runbook must end the incident better than it started it.

Expand All @@ -102,7 +102,7 @@ Within 48 hours of stabilization:
## Open questions (resolve before v0.9)

- **Tag scheme for rollback patches** (see §3 step 3 above).
- **On-call rotation.** Who carries the pager during release weeks? `gui-cs` does not currently have a rotation; until it does, "the person who tagged the TG release" is the de facto owner.
- **On-call rotation.** Who carries the pager during release weeks? `tui-cs` does not currently have a rotation; until it does, "the person who tagged the TG release" is the de facto owner.
- **Paging channel.** GitHub release-issue auto-comment is not a pager. Matrix? Discord? Email-to-SMS? Decide and document here.
- **WinGet emergency contact.** Is there a faster path for Microsoft-bot-merged manifest removal in a security incident? Investigate before v0.9.
- **Asciinema artifact retention.** TUIcast captures a `.cast` per smoke run (§5.3). Retention policy? Indefinitely is cheap; document explicitly so post-incident replays are guaranteed available.
2 changes: 1 addition & 1 deletion scripts/CLET-COLOR-GIF.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Produces `docs/images/clet-color.gif` — an animated GIF demonstrating clet's c

## Prerequisites

- [tuirec](https://github.com/gui-cs/tuirec) v0.3.4+ on PATH (`go install github.com/gui-cs/tuirec/cmd/tuirec@latest`)
- [tuirec](https://github.com/tui-cs/tuirec) v0.3.4+ on PATH (`go install github.com/tui-cs/tuirec/cmd/tuirec@latest`)
- .NET 10 SDK (for building clet)
- `agg` is auto-downloaded by tuirec on first use

Expand Down
4 changes: 2 additions & 2 deletions scripts/CLET-HELP-GIF.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Produces `docs/images/clet-help.gif` — a high-quality animated GIF demonstrati

## Prerequisites

- [tuirec](https://github.com/gui-cs/tuirec) v0.3.4+ on PATH (`go install github.com/gui-cs/tuirec/cmd/tuirec@latest`)
- [tuirec](https://github.com/tui-cs/tuirec) v0.3.4+ on PATH (`go install github.com/tui-cs/tuirec/cmd/tuirec@latest`)
- .NET 10 SDK (for building clet)
- `agg` is auto-downloaded by tuirec on first use

Expand Down Expand Up @@ -79,4 +79,4 @@ Copy-Item recording.gif ./docs/images/clet-help.gif -Force
3. **Viewport not scrolling**: Use PageDown/PageUp. CursorDown does NOT scroll — it cycles focus between links.
4. **Recording too long**: Reduce `wait:` values. The demo should be ~9s at keystroke-delay 80.
5. **GIF too large**: At 100×30, expect ~0.3-0.5 MB. Reduce `--cols` to 80 for a smaller file.
6. **Viewport starts at bottom**: Known TG bug (gui-cs/Terminal.Gui#5365). The workaround in HelpClet resets viewport on initial render.
6. **Viewport starts at bottom**: Known TG bug (tui-cs/Terminal.Gui#5365). The workaround in HelpClet resets viewport on initial render.
6 changes: 3 additions & 3 deletions scripts/CLET-PICK-FILE-GIF.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Produces `docs/images/clet-pick-file.gif` — an animated GIF demonstrating clet

## Prerequisites

- [tuirec](https://github.com/gui-cs/tuirec) v0.3.4+ on PATH (`go install github.com/gui-cs/tuirec/cmd/tuirec@latest`)
- [tuirec](https://github.com/tui-cs/tuirec) v0.3.4+ on PATH (`go install github.com/tui-cs/tuirec/cmd/tuirec@latest`)
- .NET 10 SDK (for building clet)
- `agg` is auto-downloaded by tuirec on first use

Expand All @@ -31,7 +31,7 @@ $binary = "./src/Clet/bin/Debug/net10.0/Clet.exe"
$ks = 'wait:1500,Tab,Tab,Tab,wait:300,`r`,wait:250,`e`,wait:250,`a`,wait:600,Shift+Tab,wait:400,`r`,wait:400,Enter'

# Use 80×20 for a compact look (closer to inline feel).
# True inline rendering requires tuirec support — see gui-cs/tuirec#49.
# True inline rendering requires tuirec support — see tui-cs/tuirec#49.
tuirec record `
--binary $binary `
--args "pick-file" `
Expand Down Expand Up @@ -64,7 +64,7 @@ Copy-Item recording.gif ./docs/images/clet-pick-file.gif -Force
- **Tab order**: The pick-file view has multiple focusable areas. Tab×3 reaches the filter field from the initial table focus.
- **Filter field**: Typing in the filter field narrows the file list in real-time.
- **Jump-select**: In the table, typing a character jumps to the first entry starting with that character.
- **Terminal size**: 80×20 for a compact look that's closer to inline rendering. True inline support depends on gui-cs/tuirec#49.
- **Terminal size**: 80×20 for a compact look that's closer to inline rendering. True inline support depends on tui-cs/tuirec#49.
- **Drain**: Use `--drain 1500` to capture the command-line output after the app exits.

## Troubleshooting
Expand Down
Loading
Loading