Skip to content

Add a capability manifest and LIBTMUX_ test rules for Clojure #153

Open

Description

@tony

Summary

At 5f88402, the Clojure modules (libtmux-clojure and libtmux-clojure-core-async) get their tmux version behaviour from the Java engine, which keeps a capability table and publishes the root capabilities.json for the java port. The Clojure API appears in no manifest, the Clojure docs restate the version numbers by hand, the Clojure integration task bypasses the Java test quarantine, and no CI lane runs the facade against a daemon below the floor. This task asks the Clojure port to follow the conventions the older ports share for the capability manifest and test rules. The findings are read from the source, build files and workflows at that commit; no port code was run for this issue.

Motivation

The Rust, Go, Swift and TypeScript ports each keep one capability table that their gates read and that generates a root capabilities.json. Rust, Swift and TypeScript take the test tmux from LIBTMUX_TEST_TMUX and export a LIBTMUX_TEST_SANDBOX marker, and Ruby, Julia and PowerShell run CI lanes that must refuse each release below the floor. The shared capability-claims contract specifies that manifest, keyed by the documentation site's slug for the port, so the documentation can compare ports feature by feature.

The Clojure port has a documentation site section of its own, but a Clojure reader cannot see which facade functions need which tmux release, because the only manifest names Java classes. The three places that state the control floor in Clojure text can drift from the Java table. A run of the Clojure suite in a shell that exports LIBTMUX_SOCKET or LIBTMUX_SOCKET_PATH inherits both, and the suite uses the shared temporary root directly instead of a per-task subdirectory.

Evidence

  1. The only manifest names Java. The root capabilities.json is the Java port's: its control-mode entry lists Server.control and ControlClient.attach and names UnsupportedFeatureException, and its port is java. The Clojure facade surfaces the same refusal as an ex-info with :tmux/error :tmux/unsupported-feature (control.clj), which no manifest names.

  2. The Clojure module holds no version table, only text. The control floor is stated in the libtmux.control docstring ("Control needs tmux 3.7 or newer"), in the README ("control streaming requires tmux 3.7 or newer") and in the test helper control_gate.clj. The refusal itself comes from Java: the helper calls ControlAcquisition.supports, which reads Capabilities.CONTROL_MODE. Nothing compares the three statements with the Java table.

  3. The Clojure suite takes the tmux binary from a Gradle property and skips the quarantine. clojureIntegrationTest removes TMUX and TMUX_PANE, sets TMUX_TMPDIR to the fixed /tmp/libtmux-java-test, and passes -PlibtmuxTmuxBinary as the libtmux.tmux system property, which fixture.clj reads; LIBTMUX_TEST_TMUX is not read. The Java build has a quarantine convention that clears TMUX, TMUX_PANE and LIBTMUX_SOCKET*, gives each task a private owner-only directory and fails the build on a leaked server, but it applies to every Test task and only to a JavaExec task that calls quarantineTmux, and only module-tests do. The Clojure task therefore keeps LIBTMUX_SOCKET and LIBTMUX_SOCKET_PATH in its environment, uses the shared root directly, exports no LIBTMUX_TEST_SANDBOX marker and does not refuse to run without one. The workflow's final step counts surviving tmux processes on the whole runner instead.

  4. No lane refuses an older daemon through the facade. The Java matrix runs refusal lanes (tmux-matrix.yml), but the classes it runs are the Java and Scala ones in integration-tests/build.gradle.kts. The Clojure tmux job in clojure-compatibility.yml builds only the matrix releases, so nothing shows that libtmux.core refuses 3.2a or 3.3 without effect.

Proposal

Follow the older ports' conventions, as three changes that can land separately.

  1. Publish a capabilities.json for the Clojure port (schema libtmux-capabilities/1, port set to the documentation slug for Clojure) whose apis and error use the names the generated Clojure API reference spells. Generate it from the Java capability records plus a Clojure-side map from each facade var to the capability it needs, with a drift check that fails when the file differs from that data and a negative test that fails when a mapping is removed. The contract puts the manifest at the repository root, where the Java manifest already sits, so where a second manifest lives in this repository needs a decision. Have a check compare the control floor in the docstring, README and test helper with the table.
  2. Match the test rules for the Clojure suite: honour LIBTMUX_TEST_TMUX as the default for -PlibtmuxTmuxBinary; run clojureIntegrationTest under the same quarantine as the Test tasks, so TMUX, TMUX_PANE, LIBTMUX_SOCKET and LIBTMUX_SOCKET_PATH are cleared and TMUX_TMPDIR is a private, owner-only directory whose socket paths stay under 100 bytes; export LIBTMUX_TEST_SANDBOX and refuse to run without it.
  3. Add a floor-refusal lane to the Clojure workflow that builds 3.2a and 3.3, plus 3.0a and 3.1c behind a 3.3a client, and asserts the facade refuses each without effect. The 3.8 lane is already asked for in issue 151 and is not repeated here.

References

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions