Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
49 commits
Select commit Hold shift + click to select a range
3cc44d3
Migration(docs): Explain the version order and strict parse
tony Oct 17, 2026
9883761
Docs(fix): Remove the remaining 3.2a floor claims
tony Oct 17, 2026
3685f98
Server(feat): Capture a server's graph as one view and reserve releas…
tony Oct 17, 2026
ee63241
Clojure(chore[build]): Wire the Clojure modules into the build
tony Oct 17, 2026
3ca88e3
Clojure(feat[facade]): Add native Clojure facade
tony Sep 20, 2026
27b2eb1
Clojure(fix[fixtures]): Await worker termination
tony Sep 20, 2026
5afb411
Clojure(fix[fixtures]): Match socket aliases
tony Sep 20, 2026
2a9161d
Clojure(docs[lifecycle]): Explain lazy scopes
tony Sep 20, 2026
3703763
Clojure(test[async]): Await cancelled completion
tony Sep 20, 2026
25322ea
Clojure(fix[fixture]): Identify the tmux daemon
tony Sep 20, 2026
333fe57
Clojure(test[clients]): Cover switch and detach
tony Sep 20, 2026
08b917c
Clojure(fix[async]): Await callback cancellation
tony Sep 20, 2026
119a402
Clojure(ci[matrix]): Cover runtime grid
tony Sep 20, 2026
c81c26f
Clojure(fix[api]): Follow master's exceptions, capture view and admis…
tony Oct 17, 2026
f246430
Clojure(feat[control]): Build control on stable 3.7 and master's subs…
tony Oct 17, 2026
58b10b1
Clojure(ci): Run on JDK 25 and the 3.3a tmux matrix, pinned
tony Oct 17, 2026
e0ce01e
Clojure(test): Count one admission probe for a capture
tony Oct 17, 2026
6b75e96
Clojure(ci): Run Gradle on JDK 25 and the Clojure on the lane's JDK
tony Oct 17, 2026
11d64c7
clojure(docs[readme]) Document façade boundary
tony Nov 7, 2026
a245b6b
control(test[capacity]) Scope retained-event assertion
tony Nov 7, 2026
114ec11
ci(fix[apt]) Use the bounded package installer
tony Nov 7, 2026
846154c
ci(fix[clojure]) Test current Clojure at edges
tony Nov 7, 2026
1b45ee7
capture(fix[rebase]) Align generated contracts
tony Nov 7, 2026
9f4a150
build(fix[guard]) Read JDK 27 class files
tony Nov 7, 2026
884e30c
ci(fix[tmux]) Export the selected lane on PATH
tony Nov 7, 2026
59344d2
clojure(docs[readme]) Link native namespaces
tony Nov 7, 2026
c05c080
ci(fix[macos]) Supply tmux's allocator
tony Nov 7, 2026
c4ecef0
control(fix[stream]) Bound subscriber state
tony Nov 7, 2026
98c530e
clojure(fix[stream]) Decode after subscriber gaps
tony Nov 7, 2026
c3d89b8
control(fix[close]) Release ended buffers
tony Nov 7, 2026
76e84cf
clojure(fix[async]) Preserve stopped stream loss
tony Nov 7, 2026
8601d0c
clojure(fix[async]) Guard consumer close in STM
tony Nov 7, 2026
1b7b046
clojure(feat[docs]) Generate API references
tony Nov 7, 2026
7a45ab8
clojure(docs[examples]) Run complete API programs
tony Nov 7, 2026
d0b04b7
clojure(docs[examples]) Cover owned capabilities
tony Nov 7, 2026
1f7fc7a
clojure(fix[docs]) Isolate the native catalog
tony Nov 7, 2026
b302037
clojure(fix[docs]) Package native API references
tony Nov 7, 2026
83ad866
clojure(test[cli]) Retain failure details
tony Nov 7, 2026
6c0c6a1
clojure(docs[api]) Link native contracts
tony Nov 7, 2026
61d450b
clojure(docs[links]) Link the core.async namespace reference
tony Nov 7, 2026
1a25f70
clojure(fix[examples]) Retain default upstream stream bounds
tony Nov 7, 2026
39618f7
integration(test[split]) Control pane loss before read-back
tony Nov 7, 2026
0f4eeb9
ci(fix[clojure]) Keep live checks in endpoint compatibility jobs
tony Nov 7, 2026
c45c3a4
integration(style) Format split read-back test
tony Nov 7, 2026
92e945a
clojure(fix) Preserve lifecycle boundaries
tony Nov 8, 2026
dd1b309
Docs(branding): Add Clojure module logos
tony Nov 7, 2026
539d44d
clojure(docs): Add module logos (#139)
tony Nov 8, 2026
2e9b6d9
clojure(test): Reuse the guard probe JVM
tony Nov 8, 2026
941f216
changelog(docs): Summarize Clojure APIs (#20)
tony Nov 8, 2026
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
9 changes: 8 additions & 1 deletion .github/WRITING.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,13 @@ release — it buries the lede.

## API documentation

Clojure docstrings use minimal Markdown. Put arguments and keyword options in
backticks. Link related public vars with `[[same-namespace-var]]` or
`[[fully.qualified.namespace/var]]`; link namespaces the same way, and never
use an import alias in a link. Explain why a reader would follow the link.
The native reference resolves these links in Markdown and offline HTML and
rejects unknown targets. Its freshness check runs with the module checks.

Javadoc on public API is a specification, not a programming guide. It states
what a caller may rely on, which is the part the signature cannot state on its
own.
Expand Down Expand Up @@ -357,7 +364,7 @@ Bad (Delete):
Good (Keep):

```java
// tmux < 3.2 reports the pane ID only after the command completes,
// Some releases report the pane ID only after the command completes,
// so this query must stay separate.
```

Expand Down
4 changes: 3 additions & 1 deletion .github/scripts/tmux_build.py
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,9 @@ def _probe(binary: pathlib.Path, version: str) -> None:
raise ValueError(msg)
env = {k: v for k, v in os.environ.items() if k not in {"TMUX", "TMUX_PANE"}}
env.update({"SHELL": "/bin/sh", "TERM": "xterm-256color", "LC_ALL": "C.UTF-8"})
with tempfile.TemporaryDirectory(prefix="lt-ci-") as temporary:
scratch = pathlib.Path("/tmp/libtmux-java-test")
scratch.mkdir(parents=True, exist_ok=True)
with tempfile.TemporaryDirectory(prefix="ci-cache-", dir=scratch) as temporary:
socket = pathlib.Path(temporary) / "socket"
command = [str(binary), "-f", "/dev/null", "-S", str(socket)]
try:
Expand Down
8 changes: 6 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,12 @@ jobs:
echo "PYTHONPATH=$RUNNER_TEMP/python-libtmux-core/src" >> "$GITHUB_ENV"
echo "TMUX_WORKSPACE_TEST_PYTHON=$RUNNER_TEMP/workspace-python/bin/python" >> "$GITHUB_ENV"

# Runs every check task instead of stopping at the first failure, so one run names them all.
- run: ./gradlew :libtmux-mcp:test check --stacktrace --continue -Plibtmux.testJdk=${{ matrix.java }}
# Continue past failures so one run names each failed check.
# Clojure's live suite runs in its endpoint-only compatibility workflow.
- run: >-
./gradlew :libtmux-mcp:test check --stacktrace --continue
-Plibtmux.testJdk=${{ matrix.java }}
-x :integration-tests:clojureIntegrationTest

# A real-tmux suite that leaves servers running would be invisible here and expensive on a
# developer's machine. The runner is discarded either way, so this is the only place the
Expand Down
243 changes: 243 additions & 0 deletions .github/workflows/clojure-compatibility.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,243 @@
name: Clojure compatibility

on:
push:
branches: [master]
pull_request:
workflow_dispatch:

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
contents: read

jobs:
check:
name: Clojure checks (JDK ${{ matrix.java }})
runs-on: ubuntu-latest
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
java: ['25', '27']
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7

- uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6
with:
distribution: temurin
# Gradle runs on 25 in every lane (last entry is JAVA_HOME); the lane's JDK runs the Clojure.
java-version: |
${{ matrix.java }}
25

- uses: gradle/actions/setup-gradle@3f5f9adaf7d9fecd50b5935e54106014257a94e6 # v6.4.0
with:
validate-wrappers: true

- name: Run Clojure module and metadata checks
run: >-
./gradlew :libtmux-clojure:check :libtmux-clojure-core-async:check
clojureDependencyMetadata platformCoversEveryPublishedModule
--rerun-tasks --stacktrace
-PlibtmuxJavaVersion=${{ matrix.java }}

- name: No tmux server outlived the suite
if: always()
run: |
left="$(pgrep -c tmux || true)"
if [ "${left:-0}" -ne 0 ]; then
echo "::error::$left tmux server(s) survived the suite"
for p in $(pgrep tmux); do tr '\0' ' ' < "/proc/$p/cmdline"; echo; done
exit 1
fi
echo "no tmux server survived the suite"

- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
if: failure()
with:
name: reports-clojure-jdk${{ matrix.java }}
path: '**/build/reports/**'
retention-days: 7

tmux:
name: Clojure tmux ${{ matrix.tmux }} (JDK ${{ matrix.java }})
runs-on: ubuntu-latest
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
java: ['25', '27']
tmux: ['3.3a', '3.7c']
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7

- name: Build tmux dependencies
run: |
./tools/apt-get.sh update
./tools/apt-get.sh install --no-install-recommends -y \
autoconf automake bison build-essential libevent-dev libncurses-dev \
libutempter-dev pkg-config

- name: Identify tmux ${{ matrix.tmux }} and its build environment
id: tmux-build
env:
LANE: ${{ matrix.tmux }}
run: python3 -B .github/scripts/tmux_build.py plan "$LANE" --prefix "$HOME/tmux-builds/$LANE"

- name: Restore tmux ${{ matrix.tmux }}
id: tmux-cache
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: ~/tmux-builds/${{ matrix.tmux }}
key: ${{ steps.tmux-build.outputs.key }}

- name: Validate or rebuild tmux ${{ matrix.tmux }}
env:
LANE: ${{ matrix.tmux }}
CACHE_HIT: ${{ steps.tmux-cache.outputs.cache-hit }}
run: python3 -B .github/scripts/tmux_build.py prepare "$LANE" --prefix "$HOME/tmux-builds/$LANE"

- name: Save validated tmux ${{ matrix.tmux }}
if: steps.tmux-cache.outputs.cache-hit != 'true'
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: ~/tmux-builds/${{ matrix.tmux }}
key: ${{ steps.tmux-build.outputs.key }}

- name: The lane runs the tmux it is named after
env:
LANE: ${{ matrix.tmux }}
run: |
"$HOME/tmux-builds/$LANE/bin/tmux" -V
echo "$HOME/tmux-builds/$LANE/bin" >> "$GITHUB_PATH"

- uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6
with:
distribution: temurin
# Gradle runs on 25 in every lane (last entry is JAVA_HOME); the lane's JDK runs the Clojure.
java-version: |
${{ matrix.java }}
25

- uses: gradle/actions/setup-gradle@3f5f9adaf7d9fecd50b5935e54106014257a94e6 # v6.4.0
with:
validate-wrappers: true

- name: Run the native Clojure real-tmux suite
env:
LANE: ${{ matrix.tmux }}
run: |
./gradlew :integration-tests:clojureIntegrationTest --rerun-tasks --stacktrace \
-PlibtmuxJavaVersion=${{ matrix.java }} \
"-PlibtmuxTmuxBinary=$HOME/tmux-builds/$LANE/bin/tmux" \
"-PlibtmuxTmuxExpected=$LANE"

- name: No tmux server outlived the suite
if: always()
run: |
left="$(pgrep -c tmux || true)"
if [ "${left:-0}" -ne 0 ]; then
echo "::error::$left tmux server(s) survived the suite"
for p in $(pgrep tmux); do tr '\0' ' ' < "/proc/$p/cmdline"; echo; done
exit 1
fi
echo "no tmux server survived the suite"

- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
if: failure()
with:
name: reports-clojure-tmux-${{ matrix.tmux }}-jdk${{ matrix.java }}
path: '**/build/reports/**'
retention-days: 7

macos:
name: Clojure macOS tmux ${{ matrix.tmux }} (JDK ${{ matrix.java }})
runs-on: macos-latest
timeout-minutes: 25
strategy:
fail-fast: false
matrix:
java: ['25', '27']
tmux: ['3.3a', '3.7c']
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7

- name: Build tmux dependencies
run: brew install libevent ncurses jemalloc bison pkg-config

- name: Restore tmux ${{ matrix.tmux }}
id: tmux-cache
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
with:
path: ~/tmux-builds/${{ matrix.tmux }}
key: clojure-tmux-${{ matrix.tmux }}-${{ runner.os }}-${{ runner.arch }}-jemalloc

- name: Build tmux ${{ matrix.tmux }}
if: steps.tmux-cache.outputs.cache-hit != 'true'
env:
LANE: ${{ matrix.tmux }}
run: |
set -eux
work="$(mktemp -d)"
curl -fsSL -o "$work/tmux.tar.gz" \
"https://github.com/tmux/tmux/releases/download/$LANE/tmux-$LANE.tar.gz"
tar -xzf "$work/tmux.tar.gz" -C "$work"
cd "$work/tmux-$LANE"
libevent_prefix="$(brew --prefix libevent)"
ncurses_prefix="$(brew --prefix ncurses)"
jemalloc_prefix="$(brew --prefix jemalloc)"
export PKG_CONFIG_PATH="$libevent_prefix/lib/pkgconfig:$ncurses_prefix/lib/pkgconfig:$jemalloc_prefix/lib/pkgconfig"
export CPPFLAGS="-I$ncurses_prefix/include"
export LDFLAGS="-L$ncurses_prefix/lib"
./configure --prefix="$HOME/tmux-builds/$LANE" --disable-utf8proc
make -j"$(sysctl -n hw.logicalcpu)"
make install

- name: The lane runs the tmux it is named after
env:
LANE: ${{ matrix.tmux }}
run: |
"$HOME/tmux-builds/$LANE/bin/tmux" -V
echo "$HOME/tmux-builds/$LANE/bin" >> "$GITHUB_PATH"

- uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6
with:
distribution: temurin
# Gradle runs on 25 in every lane (last entry is JAVA_HOME); the lane's JDK runs the Clojure.
java-version: |
${{ matrix.java }}
25

- uses: gradle/actions/setup-gradle@3f5f9adaf7d9fecd50b5935e54106014257a94e6 # v6.4.0
with:
validate-wrappers: true

- name: Run the native Clojure smoke and lifecycle suite
env:
LANE: ${{ matrix.tmux }}
run: |
./gradlew :integration-tests:clojureIntegrationTest --rerun-tasks --stacktrace \
-PlibtmuxJavaVersion=${{ matrix.java }} \
"-PlibtmuxTmuxBinary=$HOME/tmux-builds/$LANE/bin/tmux" \
"-PlibtmuxTmuxExpected=$LANE"

- name: No tmux server outlived the suite
if: always()
run: |
left="$(pgrep -c tmux || true)"
if [ "${left:-0}" -ne 0 ]; then
echo "::error::$left tmux server(s) survived the suite"
for p in $(pgrep tmux); do ps -o command= -p "$p"; done
exit 1
fi
echo "no tmux server survived the suite"

- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
if: failure()
with:
name: reports-clojure-macos-${{ matrix.tmux }}-jdk${{ matrix.java }}
path: '**/build/reports/**'
retention-days: 7
2 changes: 2 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,8 @@ jobs:
libtmux-jackson/build/libs/*.jar
libtmux-junit5/build/libs/*.jar
libtmux-kotlin/build/libs/*.jar
libtmux-clojure/build/libs/*.jar
libtmux-clojure-core-async/build/libs/*.jar
libtmux-mcp/build/libs/*.jar
libtmux-workspace/build/libs/*.jar
libtmux-workspace-cli/build/libs/*.jar
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ whole release. A change to one module is in that module's changelog:
- [`libtmux-workspace`](libtmux-workspace/CHANGELOG.md)
- [`libtmux-workspace-cli`](libtmux-workspace-cli/CHANGELOG.md)
- [`libtmux-kotlin`](libtmux-kotlin/CHANGELOG.md)
- [`libtmux-clojure`](libtmux-clojure/CHANGELOG.md)
- [`libtmux-clojure-core-async`](libtmux-clojure-core-async/CHANGELOG.md)
- [`libtmux-scala`](libtmux-scala/CHANGELOG.md)
- [`libtmux-scala-cats`](libtmux-scala-cats/CHANGELOG.md)
- [`libtmux-scala-ox`](libtmux-scala-ox/CHANGELOG.md)
Expand All @@ -24,8 +26,19 @@ release that first shipped the module.

## Unreleased

### Documented

- **Clojure has native API references and runnable examples.** The module
READMEs and guides cover captured data, tmux operations, cancellation and
streaming, with source links and examples checked against real tmux. (#20)

### Development

- **Clojure uses the existing Gradle build and publication workflow.** The
core and optional adapter join the BOM and release checks. Compatibility
jobs cover the newest Clojure and the oldest and newest supported tmux on
Linux and macOS. (#20)

- **CI rebuilds incompatible cached tmux installations before running
tests.** The tmux matrix restored a build made on another runner image and
failed at `tmux -V` on Ubuntu 26.04 with `NCURSES6_TINFO_6.4.current` missing
Expand Down
38 changes: 38 additions & 0 deletions MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,35 @@ full change history.
A breaking type is named on its own `api-break:` line. Mentioning the type in
the prose is not that line.

### Create Clojure resources through ownership APIs

The unreleased Clojure façade keeps raw task, runtime, adapter, and events-port
constructor vars private. Use `libtmux.async/runtime!`, `submit!`, and
`libtmux.core-async/observe!`; these establish bounded workers and cleanup.
Returned resource classes remain usable in type hints and `with-open`.

### Output subscriptions bound payload bytes

`ControlClient.subscribeOutput(int)` now bounds queued unescaped payload at
16 MiB as well as the requested event count. Use
`ControlClient.subscribeOutput(int, long)` to choose another byte limit.
Oldest events are discarded until both limits fit; a chunk larger than the
byte limit discards the buffered prefix and itself. Read `Delivery.Gap`
before processing the retained suffix. `droppedBytes()` counts payload loss,
while `retainedBytes()` excludes JVM object overhead and bytes already read.

For text that follows one subscriber's observed bytes, pass each `PaneOutput`
to a `PaneOutputDecoder`, call `reset()` after every gap, and call `finish()`
at termination. This prevents bytes on opposite sides of a subscriber gap
from forming a character. Decoder capacity eviction increments `resetCount()`.
The existing `PaneOutput.data()` remains the client's predecoded view.

`EventSubscription.termination()` records the first end classification and
original cause. A control exit describes that client, not daemon death;
bare EOF remains unknown. Later close does not replace that record.
Explicitly closing a subscription discards its queued payload even after a
remote end; it preserves the recorded cause and loss counts.

### With no socket chosen, tmux picks the server

The core, `tmux-workspace` and `libtmux-mcp` now take the same steps to find a
Expand Down Expand Up @@ -215,6 +244,15 @@ round. Gate a behaviour on the release that ships it, such as
`IllegalArgumentException` for anything else, such as `3.3a garbage`,
`next-3.9a` or `3.8-rc0`.

### Version ordering and parsing

`TmuxVersion.compareTo` now orders `next-X.Y < X.Y-rc < X.Y-rcN < X.Y < X.Ya`,
so it agrees with `equals`; a candidate no longer compares equal to its release.
Use `atLeast` for a feature gate, which counts a candidate as its release, and
`sameRelease` for a gate on one release's own defect. `TmuxVersion.parse` accepts
only what tmux has reported (`3.3a`, `3.8-rc2`, `next-3.9`) and throws
`IllegalArgumentException` for anything else, such as `3.3a garbage`.

## 0.0.1-alpha.16

### `CommandResult.stdout()` keeps carriage returns
Expand Down
Loading
Loading