mirror of https://github.com/Ark0N/Codeman.git synced 2026-10-10 01:09:43 +02:00

Files

T

Codeman maintainer f79f530f93 fix(mobile): #432 landing fixes

Applies the review's landing list for the native-wrapper window bridge, with the verifier corrections.

detachSession now refuses before asking the host when there is no window channel (no BroadcastChannel). Without the channel there is no roll-call liveness, so a hosted tab could never re-dock and would stay detached, and excluded from tiles and split, until the session ended. The guard sits before the host call so a channel-less host never gets a native window and a window.open as well.

A single resolver, tabDetachButtonEnabled(), now lives in app.js next to hasHostWindows() and decides the host-aware pop-out default for the tab icon, App Settings and the tab action menu (which also serves the tile grid's menu). Before this the menu read the raw setting and hid "Open in a new window" under a host. The menu and both settings-ui.js sites call it optionally with a fallback, because test/session-sidebar-ux.browser.test.ts loads tab-rail-resize.js onto a bare CodemanApp without app.js, and a bare call would throw before the menu is appended.

The "Close window" button on the solo session-gone overlay goes through _closeSoloWindow(), as the re-dock button already did, so it works in a host window.

openWebviewExternal no longer falls through to window.open when the host refuses (in a WebView that can replace the dashboard page); it toasts instead, like the session and file-preview paths.

The hasHostWindows and openInHostWindow JSDoc now say what the code does: anything but false counts as opened, and a saved web tab passes its own origin.

docs/versioning-policy.md lists the window.CodemanHost bridge under experimental surfaces, so it does not read as a stable contract until the wrapper docs section lands.

test/host-window-detach.test.ts gives the harness a live window channel (Object.create leaves it undefined, which the new guard would refuse) and pins the no-channel refusal.

The per-PR changeset is removed; the release writes one consolidated changeset.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

2026-10-09 05:57:49 +02:00

4.6 KiB

Raw Blame History

Versioning & Stability Policy

Codeman follows Semantic Versioning (MAJOR.MINOR.PATCH), managed via @changesets/cli (see the COM workflow in CLAUDE.md).

This document defines what the version number actually promises — i.e. which surfaces are covered by SemVer and which are explicitly not. It exists because "1.0" is a commitment to stability, and an undocumented public surface invites incompatible client assumptions we would then be pressured to keep.

Status: finalized for the 1.0 cut. The HTTP/SSE API is part of the stable surface — served under /api/v1 with a uniform response envelope and conventional HTTP status codes. See api-reference.md.

What SemVer covers (the public, stable surface)

A MAJOR bump is required to break any of these after 1.0:

The CLI. Command names, documented flags, and their behavior for codeman <command> (published to npm as aicodeman; invoked as codeman). This is the package's actual public entry point (bin).
- The package is published to npm as aicodeman and installs both the aicodeman and codeman commands (bin aliases); codeman is the canonical command used throughout the docs. Renaming either after 1.0 is a breaking change.
The published xterm-zerolag-input library, but on its own version line — it is versioned and released independently of the Codeman app. Its 1.0 status is a separate decision; the Codeman app reaching 1.0 does not imply xterm-zerolag-input is 1.0.
Documented environment variables that configure deployment: CODEMAN_PASSWORD, CODEMAN_USERNAME, CODEMAN_HOST, CODEMAN_PORT, CODEMAN_INSTANCE, CODEMAN_ALLOWED_HOSTS, CODEMAN_DATA_DIR, CODEMAN_TMUX_SOCKET, and the --host / --port / --https CLI flags. Removing or changing the meaning of one of these is breaking.
The HTTP API and SSE event channel, served under /api/v1 with the uniform {success:true,data} / {success:false,error,errorCode} envelope and conventional HTTP status codes. Endpoint paths, the response envelope, error errorCode values, and SSE event names are stable — see api-reference.md. Additive changes (new endpoints, new optional fields, new error codes, new SSE events) are non-breaking; breaking changes ship under a new prefix (/api/v2). The unversioned /api/... alias is kept working for the bundled UI.
The dashboard's #session=<id> link. Opening the dashboard URL with a #session=<id> fragment selects that session if this client can see it. The fragment name and that meaning are stable; see Opening a session from your own page.

What SemVer does NOT cover (internal surfaces — may change in any release)

These may change in a MINOR (or even PATCH) release without a MAJOR bump:

The ~/.codeman/ state file formats (state.json, settings.json, mux-sessions.json, etc.). We make a best-effort to migrate existing data forward (and have done so across renames), but the on-disk schema is not a stable contract — do not write tooling that depends on its exact shape.
Internal TypeScript modules. The npm package is CLI-only; importing it programmatically is not supported (there is no stable library entry point).
Experimental / opt-in features, regardless of the app's version: Gesture Control (beta), Agent Teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), the native-wrapper window bridge (window.CodemanHost.openWindow / closeWindow / focusWindow), and anything labeled experimental in the UI or docs. These may change or be removed at any time.

Deprecation policy

When we need to change a covered surface:

Prefer additive changes (new flag/env var/command) over breaking ones.
A covered surface slated for removal is deprecated first — it keeps working for at least one MINOR release with a runtime warning and a CHANGELOG.md note pointing to the replacement — then removed in the next MAJOR.
Back-compat migration shims (e.g. the historical Claudeman→Codeman data/socket migration) are kept until a MAJOR boundary, then may be dropped.

Pre-1.0 (`0.x`) caveat

Until 1.0 ships, any release may contain breaking changes per SemVer's 0.x allowance. The commitments above take effect at 1.0.0.

4.6 KiB Raw Blame History