@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/domains/mux/types.ts

@@ -0,0 +1,265 @@
+/**
+ * Clio-owned vocabulary for the pane layer.
+ *
+ * Nothing in this file names a herdr wire shape. `socket-client.ts` is the only
+ * module that reads the newline-delimited JSON coming off the socket, and it
+ * maps every response into the types declared here before anything else in the
+ * process sees it. That keeps the blast radius of a herdr protocol bump inside
+ * one file and keeps `npm run lint`'s boundary check honest about what the mux
+ * domain exports to the rest of Clio.
+ */
+
+/** Which capability ladder rung the mux resolved to at interactive boot. */
+export type MuxMode = "embedded" | "guest" | "none";
+
+/** Locates one pane inside a herdr session. */
+export interface MuxPaneRef {
+	paneId: string;
+	tabId: string;
+	workspaceId: string;
+}
+
+/**
+ * Semantic agent state as the pane layer reports and reads it.
+ *
+ * `done` and `unknown` only ever arrive from the server; Clio reports the three
+ * states in {@link MuxReportableAgentState}.
+ */
+export type MuxAgentState = "idle" | "working" | "blocked" | "done" | "unknown";
+
+/** The subset of {@link MuxAgentState} Clio is allowed to assert about a pane. */
+export type MuxReportableAgentState = "idle" | "working" | "blocked";
+
+/** One pane, projected from the server's pane record. */
+export interface MuxPane {
+	paneId: string;
+	tabId: string;
+	workspaceId: string;
+	focused: boolean;
+	agentState: MuxAgentState;
+	revision: number;
+	label: string | null;
+	title: string | null;
+	cwd: string | null;
+	agent: string | null;
+	tokens: Readonly<Record<string, string>>;
+}
+
+/** One tab, projected from the server's tab record. */
+export interface MuxTab {
+	tabId: string;
+	workspaceId: string;
+	number: number;
+	label: string;
+	focused: boolean;
+	paneCount: number;
+	agentState: MuxAgentState;
+}
+
+/** Git worktree metadata projected from herdr's worktree API. */
+export interface MuxWorktree {
+	path: string;
+	branch: string | null;
+	isBare: boolean;
+	isDetached: boolean;
+	isPrunable: boolean;
+	isLinkedWorktree: boolean;
+	openWorkspaceId: string | null;
+	label: string;
+}
+
+/** Repository identity accompanying a `worktree.list` result. */
+export interface MuxWorktreeSource {
+	repoKey: string;
+	repoName: string;
+	repoRoot: string;
+	sourceCheckoutPath: string;
+	sourceWorkspaceId: string | null;
+}
+
+/** Identity and capability facts recorded from the `ping` handshake. */
+export interface MuxServerInfo {
+	version: string;
+	protocol: number;
+}
+
+/**
+ * Bootstrap state. The documented herdr pattern is to take one snapshot and
+ * then trust the event stream, so the client refetches this after every
+ * reconnect rather than trying to replay missed events.
+ */
+export interface MuxSnapshot {
+	server: MuxServerInfo;
+	focusedPaneId: string | null;
+	focusedTabId: string | null;
+	focusedWorkspaceId: string | null;
+	panes: ReadonlyArray<MuxPane>;
+	tabs: ReadonlyArray<MuxTab>;
+}
+
+/** Lifecycle event kinds the pane layer can subscribe to. */
+export type MuxEventKind = "pane.closed" | "pane.exited" | "pane.moved" | "layout.updated";
+
+/**
+ * One pushed lifecycle event. A discriminated union because the payloads
+ * differ: pane leave events carry the pane, a move carries the id rewrite
+ * herdr performs, and a layout update carries the whole tab geometry so a
+ * consumer does not have to turn around and fetch what the push already said.
+ */
+export type MuxEvent =
+	| { kind: "pane.closed" | "pane.exited"; paneId: string; workspaceId: string }
+	| { kind: "pane.moved"; paneId: string; previousPaneId: string; tabId: string; workspaceId: string }
+	| { kind: "layout.updated"; geometry: MuxTabGeometry };
+
+/** One rectangle in terminal cells, as herdr's layout snapshots report them. */
+export interface MuxRect {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+
+/**
+ * Cell-precise geometry of one tab: the outer area, every pane's rect, and
+ * every split with its live ratio. This is what dock sizing converges on.
+ */
+export interface MuxTabGeometry {
+	workspaceId: string;
+	tabId: string;
+	zoomed: boolean;
+	area: MuxRect;
+	focusedPaneId: string | null;
+	panes: ReadonlyArray<{ paneId: string; focused: boolean; rect: MuxRect }>;
+	splits: ReadonlyArray<{ direction: "right" | "down"; ratio: number; rect: MuxRect }>;
+}
+
+/**
+ * One node of a portable tab layout tree, as `layout.export` describes it.
+ * Split ratio is the share of the axis the `first` child keeps.
+ */
+export type MuxLayoutNode =
+	| { type: "pane"; paneId: string | null; label: string | null }
+	| { type: "split"; direction: "right" | "down"; ratio: number; first: MuxLayoutNode; second: MuxLayoutNode };
+
+/** A whole tab's portable layout tree. */
+export interface MuxLayoutTree {
+	workspaceId: string;
+	tabId: string;
+	zoomed: boolean;
+	focusedPaneId: string | null;
+	root: MuxLayoutNode;
+}
+
+/** Where Clio's own pane lives, read from the herdr environment. */
+export interface MuxSelfLocation {
+	workspaceId: string | null;
+	tabId: string | null;
+	paneId: string | null;
+}
+
+/**
+ * Typed failure classes. `unknown` carries the server's own code through
+ * untouched so a herdr version that grows a new code is legible in logs
+ * without a Clio release.
+ */
+export type MuxErrorKind =
+	| "not_found"
+	| "invalid_params"
+	| "agent_blocked"
+	| "feature_disabled"
+	| "agent_prompt_stalled"
+	| "timeout"
+	| "transport"
+	| "protocol"
+	| "unknown";
+
+/** Every failure the mux domain raises. */
+export class MuxError extends Error {
+	readonly kind: MuxErrorKind;
+	/** The server's raw error code, when the failure came back over the wire. */
+	readonly wireCode: string | null;
+	readonly method: string | null;
+
+	constructor(kind: MuxErrorKind, message: string, options: { wireCode?: string; method?: string } = {}) {
+		super(message);
+		this.name = "MuxError";
+		this.kind = kind;
+		this.wireCode = options.wireCode ?? null;
+		this.method = options.method ?? null;
+	}
+}
+
+/** A request that never got a response line inside its budget. */
+export class MuxRequestTimeout extends MuxError {
+	readonly timeoutMs: number;
+
+	constructor(method: string, timeoutMs: number) {
+		super("timeout", `mux request ${method} timed out after ${timeoutMs}ms`, { method });
+		this.name = "MuxRequestTimeout";
+		this.timeoutMs = timeoutMs;
+	}
+}
+
+/**
+ * Codes herdr returns today that mean the same thing as one of our kinds.
+ * Anything absent falls through the suffix and prefix rules in
+ * {@link muxErrorKind}, and anything those miss stays `unknown`.
+ */
+const ERROR_KIND_BY_WIRE_CODE: Readonly<Record<string, MuxErrorKind>> = {
+	agent_blocked: "agent_blocked",
+	agent_prompt_stalled: "agent_prompt_stalled",
+	feature_disabled: "feature_disabled",
+	invalid_params: "invalid_params",
+	invalid_request: "invalid_params",
+	not_found: "not_found",
+};
+
+/** Classify one server error code into a Clio failure kind. */
+export function muxErrorKind(wireCode: string): MuxErrorKind {
+	const mapped = ERROR_KIND_BY_WIRE_CODE[wireCode];
+	if (mapped) return mapped;
+	if (wireCode.endsWith("_not_found")) return "not_found";
+	if (wireCode.startsWith("invalid_")) return "invalid_params";
+	return "unknown";
+}
+
+/** Diagnostic sink. The mux never throws at its callers, so this is how failures surface. */
+export type MuxLog = (level: "debug" | "info" | "warning", message: string) => void;
+
+/** The three sounds `notification.show` accepts, per protocol 17's schema. */
+export type MuxNotificationSound = "none" | "done" | "request";
+
+/** What Clio reports about its own hosting pane in guest mode (SA-3). */
+export interface MuxSelfReport {
+	state: MuxReportableAgentState;
+	/** Short human line herdr may show beside the state. */
+	message?: string;
+	/** Presentation tokens; a null value clears that token. */
+	tokens?: Readonly<Record<string, string | null>>;
+	/** Per-state sidebar label overrides, e.g. `{ blocked: "needs approval" }`. */
+	stateLabels?: Readonly<Record<string, string>>;
+	/** Expiry for this report's tokens, 1..86400000 ms. */
+	ttlMs?: number;
+}
+
+/**
+ * Why Clio created a pane. `watch` is the workers-view watch pane; everything
+ * else (presets, operator argv, the yazi companion) is `utility`. The purpose
+ * doubles as the pane's `role` metadata token so a restarted session can adopt
+ * a surviving watch pane by scanning one snapshot.
+ */
+export type MuxPanePurpose = "watch" | "utility";
+
+/** One pane Clio created and therefore may act on. */
+export interface MuxPaneRecord {
+	ref: MuxPaneRef;
+	purpose: MuxPanePurpose;
+	label: string;
+	openedAt: number;
+	/**
+	 * True when the record was adopted from a snapshot at boot rather than
+	 * created in this process, so a resumed session reuses the pane it found
+	 * instead of opening a second one.
+	 */
+	adopted?: boolean;
+}

package/src/domains/mux/viewer-command.ts

@@ -0,0 +1,59 @@
+/**
+ * What the workers-view watch pane runs.
+ *
+ * The argv is `node <this install's dist CLI> fleet view --watch <file>`
+ * rather than the `clio-coder` bin name. Resolving through PATH would run
+ * whatever copy of Clio the operator's PATH points at, which in a worktree or a
+ * multi-install machine is routinely not the one that opened the pane, and the
+ * viewer would then read a different install's state root. This is the same
+ * self-invocation shape `worker-spawn.ts:589` uses for the same reason.
+ *
+ * A per-run viewer command (`fleet view <runId> --follow`) used to live here
+ * for the per-dispatch viewer panes; those panes are gone, and the one pane
+ * that renders runs now follows a selection file so the TUI can retarget it
+ * without respawning anything.
+ */
+
+import { join } from "node:path";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import type { ClioDirs } from "../../core/xdg.js";
+
+/** Built CLI entry point, matching the `bin` field in `package.json`. */
+export function clioCliEntryPath(): string {
+	return join(resolvePackageRoot(), "dist/cli/index.js");
+}
+
+export interface ViewerCommandOptions {
+	/** Override for tests and for a caller that already resolved the entry. */
+	entryPath?: string;
+	/** Node binary to run it with; defaults to the one running this process. */
+	execPath?: string;
+	/** Exact parent-process layout; pinned on argv so a new pane cannot re-resolve it. */
+	dirs?: Readonly<ClioDirs>;
+}
+
+/** The argv the watch pane executes: one viewer process following a selection file. */
+export function watchViewerCommand(selectionPath: string, options: ViewerCommandOptions = {}): ReadonlyArray<string> {
+	const layout =
+		options.dirs === undefined
+			? []
+			: [
+					"--config-dir",
+					options.dirs.config,
+					"--data-dir",
+					options.dirs.data,
+					"--state-dir",
+					options.dirs.state,
+					"--cache-dir",
+					options.dirs.cache,
+				];
+	return [
+		options.execPath ?? process.execPath,
+		options.entryPath ?? clioCliEntryPath(),
+		"fleet",
+		"view",
+		...layout,
+		"--watch",
+		selectionPath,
+	];
+}

package/src/domains/mux/yazi/assets/init.lua

@@ -0,0 +1,2 @@
+-- Yazi init for orchestration TUI
+require("git"):setup()

package/src/domains/mux/yazi/assets/plugins/git.yazi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 yazi-rs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/domains/mux/yazi/assets/plugins/git.yazi/README.md

@@ -0,0 +1,78 @@
+# git.yazi
+
+Show the status of Git file changes as linemode in the file list.
+
+https://github.com/user-attachments/assets/34976be9-a871-4ffe-9d5a-c4cdd0bf4576
+
+## Installation
+
+```sh
+ya pkg add yazi-rs/plugins:git
+```
+
+## Setup
+
+Add the following to your `~/.config/yazi/init.lua`:
+
+```lua
+require("git"):setup()
+```
+
+And register it as fetchers in your `~/.config/yazi/yazi.toml`:
+
+```toml
+[[plugin.prepend_fetchers]]
+id  = "git"
+url = "*"
+run = "git"
+
+[[plugin.prepend_fetchers]]
+id  = "git"
+url = "*/"
+run = "git"
+```
+
+## Advanced
+
+> [!NOTE]
+> The following configuration must be put before `require("git"):setup()`
+
+You can customize the [Style](https://yazi-rs.github.io/docs/plugins/layout#style) of the status sign with:
+
+- `th.git.modified`
+- `th.git.added`
+- `th.git.untracked`
+- `th.git.ignored`
+- `th.git.deleted`
+- `th.git.updated`
+
+For example:
+
+```lua
+-- ~/.config/yazi/init.lua
+th.git = th.git or {}
+th.git.modified = ui.Style():fg("blue")
+th.git.deleted = ui.Style():fg("red"):bold()
+```
+
+You can also customize the text of the status sign with:
+
+- `th.git.modified_sign`
+- `th.git.added_sign`
+- `th.git.untracked_sign`
+- `th.git.ignored_sign`
+- `th.git.deleted_sign`
+- `th.git.updated_sign`
+
+For example:
+
+```lua
+-- ~/.config/yazi/init.lua
+th.git = th.git or {}
+th.git.modified_sign = "M"
+th.git.deleted_sign = "D"
+```
+
+## License
+
+This plugin is MIT-licensed. For more information check the [LICENSE](LICENSE) file.

package/src/domains/mux/yazi/assets/plugins/git.yazi/main.lua

@@ -0,0 +1,255 @@
+--- @since 25.12.29
+
+local WINDOWS = ya.target_family() == "windows"
+
+-- The code of supported git status,
+-- also used to determine which status to show for directories when they contain different statuses
+-- see `bubble_up`
+---@enum CODES
+local CODES = {
+	excluded = 100, -- ignored directory
+	ignored = 6, -- ignored file
+	untracked = 5,
+	modified = 4,
+	added = 3,
+	deleted = 2,
+	updated = 1,
+	unknown = 0,
+}
+
+local PATTERNS = {
+	{ "!$", CODES.ignored },
+	{ "?$", CODES.untracked },
+	{ "[MT]", CODES.modified },
+	{ "[AC]", CODES.added },
+	{ "D", CODES.deleted },
+	{ "U", CODES.updated },
+	{ "[AD][AD]", CODES.updated },
+}
+
+---@param line string
+---@return CODES, string
+local function match(line)
+	local signs = line:sub(1, 2)
+	for _, p in ipairs(PATTERNS) do
+		local path, pattern, code = nil, p[1], p[2]
+		if signs:find(pattern) then
+			path = line:sub(4, 4) == '"' and line:sub(5, -2) or line:sub(4)
+			path = WINDOWS and path:gsub("/", "\\") or path
+		end
+		if not path then
+		elseif path:find("[/\\]$") then
+			-- Mark the ignored directory as `excluded`, so we can process it further within `propagate_down`
+			return code == CODES.ignored and CODES.excluded or code, path:sub(1, -2)
+		else
+			return code, path
+		end
+		---@diagnostic disable-next-line: missing-return
+	end
+end
+
+---@param cwd Url
+---@return string?
+local function root(cwd)
+	local is_worktree = function(url)
+		local file, head = io.open(tostring(url)), nil
+		if file then
+			head = file:read(8)
+			file:close()
+		end
+		return head == "gitdir: "
+	end
+
+	repeat
+		local next = cwd:join(".git")
+		local cha = fs.cha(next)
+		if cha and (cha.is_dir or is_worktree(next)) then
+			return tostring(cwd)
+		end
+		cwd = cwd.parent
+	until not cwd
+end
+
+---@param changed Changes
+---@return Changes
+local function bubble_up(changed)
+	local new, empty = {}, Url("")
+	for path, code in pairs(changed) do
+		if code ~= CODES.ignored then
+			local url = Url(path).parent
+			while url and url ~= empty do
+				local s = tostring(url)
+				new[s] = (new[s] or CODES.unknown) > code and new[s] or code
+				url = url.parent
+			end
+		end
+	end
+	return new
+end
+
+---@param excluded string[]
+---@param cwd Url
+---@param repo Url
+---@return Changes
+local function propagate_down(excluded, cwd, repo)
+	local new, rel = {}, cwd:strip_prefix(repo)
+	for _, path in ipairs(excluded) do
+		if rel:starts_with(path) then
+			-- If `cwd` is a subdirectory of an excluded directory, also mark it as `excluded`
+			new[tostring(cwd)] = CODES.excluded
+		elseif cwd == repo:join(path).parent then
+			-- If `path` is a direct subdirectory of `cwd`, mark it as `ignored`
+			new[path] = CODES.ignored
+		else
+			-- Skipping, we only care about `cwd` itself and its direct subdirectories for maximum performance
+		end
+	end
+	return new
+end
+
+---@param cwd string
+---@param repo string
+---@param changed Changes
+local add = ya.sync(function(st, cwd, repo, changed)
+	---@cast st State
+
+	st.dirs[cwd] = repo
+	st.repos[repo] = st.repos[repo] or {}
+	for path, code in pairs(changed) do
+		if code == CODES.unknown then
+			st.repos[repo][path] = nil
+		elseif code == CODES.excluded then
+			-- Mark the directory with a special value `excluded` so that it can be distinguished during UI rendering
+			st.dirs[path] = CODES.excluded
+		else
+			st.repos[repo][path] = code
+		end
+	end
+	ui.render()
+end)
+
+---@param cwd string
+local remove = ya.sync(function(st, cwd)
+	---@cast st State
+
+	local repo = st.dirs[cwd]
+	if not repo then
+		return
+	end
+
+	ui.render()
+	st.dirs[cwd] = nil
+	if not st.repos[repo] then
+		return
+	end
+
+	for _, r in pairs(st.dirs) do
+		if r == repo then
+			return
+		end
+	end
+	st.repos[repo] = nil
+end)
+
+---@param st State
+---@param opts Options
+local function setup(st, opts)
+	st.dirs = {}
+	st.repos = {}
+
+	opts = opts or {}
+	opts.order = opts.order or 1500
+
+	local t = th.git or {}
+	local styles = {
+		[CODES.ignored] = t.ignored and ui.Style(t.ignored) or ui.Style():fg("darkgray"),
+		[CODES.untracked] = t.untracked and ui.Style(t.untracked) or ui.Style():fg("magenta"),
+		[CODES.modified] = t.modified and ui.Style(t.modified) or ui.Style():fg("yellow"),
+		[CODES.added] = t.added and ui.Style(t.added) or ui.Style():fg("green"),
+		[CODES.deleted] = t.deleted and ui.Style(t.deleted) or ui.Style():fg("red"),
+		[CODES.updated] = t.updated and ui.Style(t.updated) or ui.Style():fg("yellow"),
+	}
+	local signs = {
+		[CODES.ignored] = t.ignored_sign or " ",
+		[CODES.untracked] = t.untracked_sign or "? ",
+		[CODES.modified] = t.modified_sign or " ",
+		[CODES.added] = t.added_sign or " ",
+		[CODES.deleted] = t.deleted_sign or " ",
+		[CODES.updated] = t.updated_sign or " ",
+	}
+
+	Linemode:children_add(function(self)
+		if not self._file.in_current then
+			return ""
+		end
+
+		local url = self._file.url
+		local repo = st.dirs[tostring(url.base or url.parent)]
+		local code
+		if repo then
+			code = repo == CODES.excluded and CODES.ignored or st.repos[repo][tostring(url):sub(#repo + 2)]
+		end
+
+		if not code or signs[code] == "" then
+			return ""
+		elseif self._file.is_hovered then
+			return ui.Line { " ", signs[code] }
+		else
+			return ui.Line { " ", ui.Span(signs[code]):style(styles[code]) }
+		end
+	end, opts.order)
+end
+
+---@type UnstableFetcher
+local function fetch(_, job)
+	local cwd = job.files[1].url.base or job.files[1].url.parent
+	local repo = root(cwd)
+	if not repo then
+		remove(tostring(cwd))
+		return true
+	end
+
+	local paths = {}
+	for _, file in ipairs(job.files) do
+		paths[#paths + 1] = tostring(file.url)
+	end
+
+	-- stylua: ignore
+	local output, err = Command("git")
+		:cwd(tostring(cwd))
+		:arg({ "--no-optional-locks", "-c", "core.quotePath=", "status", "--porcelain", "-unormal", "--no-renames", "--ignored=matching" })
+		:arg(paths)
+		:stdout(Command.PIPED)
+		:output()
+	if not output then
+		return true, Err("Cannot spawn `git` command, error: %s", err)
+	end
+
+	local changed, excluded = {}, {}
+	for line in output.stdout:gmatch("[^\r\n]+") do
+		local code, path = match(line)
+		if code == CODES.excluded then
+			excluded[#excluded + 1] = path
+		else
+			changed[path] = code
+		end
+	end
+
+	if job.files[1].cha.is_dir then
+		ya.dict_merge(changed, bubble_up(changed))
+	end
+	ya.dict_merge(changed, propagate_down(excluded, cwd, Url(repo)))
+
+	-- Reset the status of any files that don't appear in the output of `git status` to `unknown`,
+	-- so that cleaning up outdated statuses from `st.repos`
+	for _, path in ipairs(paths) do
+		local s = path:sub(#repo + 2)
+		changed[s] = changed[s] or CODES.unknown
+	end
+
+	add(tostring(cwd), repo, changed)
+
+	return false
+end
+
+return { setup = setup, fetch = fetch }

package/src/domains/mux/yazi/assets/plugins/git.yazi/types.lua

@@ -0,0 +1,12 @@
+---@class State
+---@field dirs table<string, string|CODES> Mapping between a directory and its corresponding repository
+---@field repos table<string, Changes> Mapping between a repository and the status of each of its files
+
+---@class Options
+---@field order number The order in which the status is displayed
+---@field renamed boolean Whether to include renamed files in the status (or treat them as modified)
+
+-- TODO: move this to `types.yazi` once it's get stable
+---@alias UnstableFetcher fun(self: unknown, job: { files: File[] }): boolean, Error?
+
+---@alias Changes table<string, CODES>