@fresh-editor/fresh-editor 0.3.6 → 0.3.8

package/plugins/lib/fresh.d.ts

@@ -252,6 +252,10 @@ type ViewportInfo = {
 	*/
 	height: number;
 };
+type ScreenSize = {
+	width: number;
+	height: number;
+};
 type KeyEventPayload = {
 	/**
 	* Key name (e.g. `"a"`, `"escape"`, `"f1"`).
@@ -319,15 +323,18 @@ type ViewTokenWireKind = {
 } | "Newline" | "Space" | "Break" | {
 	"BinaryByte": number;
 };
+type TokenColor = [number, number, number] | string;
 type ViewTokenStyle = {
 	/**
-	* Foreground color as RGB tuple
+	* Foreground color. Either `[r, g, b]` or a named/theme string —
+	* see [`TokenColor`].
 	*/
-	fg: [number, number, number] | null;
+	fg: TokenColor | null;
 	/**
-	* Background color as RGB tuple
+	* Background color. Either `[r, g, b]` or a named/theme string —
+	* see [`TokenColor`].
 	*/
-	bg: [number, number, number] | null;
+	bg: TokenColor | null;
 	/**
 	* Whether to render in bold
 	*/
@@ -336,6 +343,10 @@ type ViewTokenStyle = {
 	* Whether to render in italic
 	*/
 	italic: boolean;
+	/**
+	* Whether to render with underline
+	*/
+	underline: boolean;
 };
 type PromptSuggestion = {
 	/**
@@ -445,6 +456,23 @@ type WindowInfo = {
 	* Absolute project root.
 	*/
 	root: string;
+	/**
+	* Project this session belongs to — the canonical repo
+	* root (or arbitrary directory) the user pointed the
+	* new-session form at. `null` for legacy sessions that
+	* predate the Project Path field. The Orchestrator Open
+	* dialog filters by this so the "this project's sessions"
+	* view is one keystroke away from the all-projects view.
+	*/
+	project_path?: string | null;
+	/**
+	* `true` when the session shares its working tree with
+	* other sessions (worktree-creation was off at session
+	* time, or the session lives in a non-git directory).
+	* Persistence-only field; defaults to `false` and isn't
+	* emitted when false.
+	*/
+	shared_worktree?: boolean;
 };
 type JsDiagnostic = {
 	/**
@@ -593,6 +621,50 @@ type TerminalResult = {
 	*/
 	splitId: number | null;
 };
+type CreateWindowWithTerminalOptions = {
+	/**
+	* Absolute path to the new session's worktree / project
+	* root. Relative paths are rejected (logged, no window
+	* created).
+	*/
+	root: string;
+	/**
+	* Human-readable label for the new session. When empty,
+	* defaults to the basename of `root`.
+	*/
+	label: string;
+	/**
+	* Working directory for the spawned terminal. Defaults to
+	* `root` when omitted.
+	*/
+	cwd?: string;
+	/**
+	* Argv to spawn directly inside the PTY. `None` keeps the
+	* shell-and-type behaviour; `Some([cmd, ...args])` runs the
+	* command as the PTY child (used by Orchestrator so the
+	* agent process is the PTY's direct child).
+	*/
+	command?: Array<string>;
+	/**
+	* Tab title override. Defaults to `command[0]`'s basename
+	* when `command` is set, or "Terminal N" otherwise.
+	*/
+	title?: string;
+};
+type SessionWithTerminalResult = {
+	/**
+	* The new window's id.
+	*/
+	windowId: number;
+	/**
+	* The seeded terminal's id (for `sendTerminalInput`, etc.).
+	*/
+	terminalId: number;
+	/**
+	* The seeded terminal buffer's id.
+	*/
+	bufferId: number;
+};
 type CreateTerminalOptions = {
 	/**
 	* Working directory for the terminal (defaults to editor cwd)
@@ -629,6 +701,27 @@ type CreateTerminalOptions = {
 	* target session's membership set rather than the active one's.
 	*/
 	windowId?: WindowId;
+	/**
+	* Argv to spawn directly inside the PTY instead of the host's
+	* configured shell. `None` (default) keeps the historical
+	* behaviour: spawn the user's shell and let the caller type into
+	* it via `sendTerminalInput`. `Some([cmd, ...args])` runs that
+	* exact command as the PTY child — no shell middleman, so the
+	* process exits cleanly when the agent does and the
+	* terminal-buffer's `terminal_exit` plugin hook reflects the
+	* agent's real exit status. Used by Orchestrator so a session
+	* with agent `python3` is just python3 in the PTY rather than
+	* bash-running-python3-as-a-subshell-command.
+	*/
+	command?: Array<string>;
+	/**
+	* Tab title for the terminal buffer. Defaults to `command[0]`
+	* (when `command` is set) or `"Terminal N"` (the historical
+	* auto-numbered title). If another terminal in the same window
+	* already uses the requested title, the host appends `" (k)"`
+	* to disambiguate. Empty string is treated the same as `None`.
+	*/
+	title?: string;
 };
 type CursorInfo = {
 	/**
@@ -673,6 +766,13 @@ type OverlayOptions = {
 	*/
 	extendToLineEnd: boolean;
 	/**
+	* When `true`, `fg` is applied only on cells whose existing fg
+	* matches this overlay's resolved bg — i.e. a same-colour fg/bg
+	* collision. Lets a row-wide overlay stay legible on tokens that
+	* share the bg's colour without repainting unrelated tokens.
+	*/
+	fgOnCollisionOnly: boolean;
+	/**
 	* Optional URL for OSC 8 terminal hyperlinks.
 	* When set, the overlay text becomes a clickable hyperlink in terminals
 	* that support OSC 8 escape sequences.
@@ -816,6 +916,15 @@ type WidgetSpec = {
 	focused: boolean;
 	intent: ButtonKind;
 	key?: string | null;
+	/**
+	* When true, the button renders in a muted style, is dropped
+	* from the Tab cycle, and clicks on it are ignored. Use for
+	* actions that aren't currently available against the
+	* surrounding state (e.g. "Archive" on the base session). The
+	* button still occupies its layout cell so the surrounding
+	* row doesn't reshuffle when the disabled flag flips.
+	*/
+	disabled: boolean;
 } | {
 	"kind": "spacer";
 	cols: number;
@@ -923,6 +1032,41 @@ type WidgetSpec = {
 	* `LabeledSection` or a flexible row.
 	*/
 	fullWidth: boolean;
+	/**
+	* Optional completion candidates. When non-empty AND
+	* `label` is non-empty (the chrome trigger), the
+	* renderer paints a popup directly under the input,
+	* inside a unified box: the input's normal `╰─...─╯`
+	* bottom border becomes a dimmed `┄` separator, the
+	* labeled section's side borders extend down through
+	* the candidate rows, and a single `╰─...─╯` bottom
+	* closes the whole block. Candidates render left-
+	* aligned with the input's text (the position right
+	* after `[`), with the host-managed selected index
+	* highlighted.
+	*
+	* Smart-key dispatch on a focused Text-with-completions:
+	* Up/Down moves selection (host-internal, no event),
+	* Tab fires `completion_accept` with the selected
+	* candidate, Enter / Escape fire `completion_dismiss`
+	* (the dispatcher's normal "Enter focus-advance / Esc
+	* close panel" only runs once the popup is closed).
+	*
+	* Plugins push candidates in response to the text
+	* widget's `change` event via
+	* `WidgetMutation::SetCompletions`. An empty `items`
+	* closes the popup.
+	*/
+	completions?: Array<string | CompletionItem>;
+	/**
+	* How many candidate rows the popup paints at once
+	* when it opens. Excess candidates stay reachable
+	* via Up/Down (host auto-scrolls to keep selection
+	* in view) or the mouse wheel; a thumb glyph paints
+	* in the right edge of the popup whenever there's
+	* more to scroll. `0` (default) falls back to `5`.
+	*/
+	completionsVisibleRows: number;
 	key?: string | null;
 } | {
 	"kind": "labeledSection";
@@ -967,6 +1111,10 @@ type WidgetSpec = {
 	"kind": "raw";
 	entries: Array<TextPropertyEntry>;
 	key?: string | null;
+} | {
+	"kind": "overlay";
+	child: WidgetSpec;
+	key?: string | null;
 };
 type WidgetAction = {
 	"kind": "focusAdvance";
@@ -991,6 +1139,10 @@ type WidgetMutation = {
 	widgetKey: string;
 	value: string;
 	cursorByte?: number | null;
+} | {
+	"kind": "setCompletions";
+	widgetKey: string;
+	items: Array<string | CompletionItem>;
 } | {
 	"kind": "setChecked";
 	widgetKey: string;
@@ -1013,6 +1165,18 @@ type WidgetMutation = {
 	widgetKey: string;
 	checked: boolean;
 	keys: Array<string>;
+} | {
+	"kind": "appendTreeNodes";
+	widgetKey: string;
+	newNodes: Array<TreeNode>;
+	newItemKeys: Array<string>;
+} | {
+	"kind": "setRawEntries";
+	widgetKey: string;
+	entries: Array<TextPropertyEntry>;
+} | {
+	"kind": "setFocusKey";
+	widgetKey: string;
 };
 type SearchTakeResult = {
 	/**
@@ -1442,7 +1606,9 @@ interface EditorAPI {
 	* contexts only (e.g. `"tour-active"`, `"review-mode"`), not built-in
 	* editor modes.
 	*/
-	registerCommand(name: string, description: string, handlerName: string, context?: string | null): boolean;
+	registerCommand(name: string, description: string, handlerName: string, context?: string | null, options?: {
+		terminalBypass?: boolean;
+	} | null): boolean;
 	/**
 	* Unregister a command by name
 	*/
@@ -1456,6 +1622,17 @@ interface EditorAPI {
 	*/
 	executeAction(actionName: string): boolean;
 	/**
+	* Register a custom statusbar token.
+	* Token will be named "plugin_name:token_name" where plugin_name is the current plugin.
+	* Returns true if registration succeeded, false if invalid or already registered.
+	*/
+	registerStatusBarElement(tokenName: string, title: string): boolean;
+	/**
+	* Set the value of a status-bar token for a specific buffer.
+	* The full token key sent to the editor is "plugin_name:token_name".
+	*/
+	setStatusBarValue(bufferId: number, tokenName: string, value: string): boolean;
+	/**
 	* Translate a string - reads plugin name from __pluginName__ global
 	* Args is optional - can be omitted, undefined, null, or an object
 	*/
@@ -1502,6 +1679,13 @@ interface EditorAPI {
 	*/
 	getViewport(): ViewportInfo | null;
 	/**
+	* Total terminal dimensions in cells. Unlike `getViewport()`
+	* (which reports the active split, shrunk by any vertical
+	* split layout), this reflects the full terminal — what a
+	* floating overlay sized by `heightPct` actually gets.
+	*/
+	getScreenSize(): ScreenSize;
+	/**
 	* List every split with its active buffer and viewport.
 	* 
 	* Plugins that need to operate on every visible buffer
@@ -1585,6 +1769,27 @@ interface EditorAPI {
 	*/
 	openFileInSplit(splitId: number, path: string, line: number, column: number): boolean;
 	/**
+	* Open `path` as a regular buffer in forced large-file (file-backed)
+	* mode. The file is created (empty) if missing — designed for
+	* buffers that will be filled by a concurrent `spawnProcess` with
+	* `stdoutTo`. Resolves with the new buffer's id, or `null` on
+	* failure.
+	* 
+	* Pair with `refreshBufferFromDisk` to grow the buffer as the
+	* streaming write advances.
+	*/
+	openFileStreaming(path: string): Promise<number | null>;
+	/**
+	* Re-stat the file backing `bufferId` and extend the buffer if the
+	* file has grown. Resolves with the new total byte length, or
+	* `null` if the buffer has no file path or doesn't exist.
+	* 
+	* Used to drive a streaming display: while a `spawnProcess` writes
+	* to a temp file, the plugin polls this on a timer so the buffer
+	* length tracks the file length.
+	*/
+	refreshBufferFromDisk(bufferId: number): Promise<number | null>;
+	/**
 	* Show a buffer in the current split
 	*/
 	showBuffer(bufferId: number): boolean;
@@ -1593,6 +1798,30 @@ interface EditorAPI {
 	*/
 	closeBuffer(bufferId: number): boolean;
 	/**
+	* Close other buffers in split
+	*/
+	closeOtherBuffersInSplit(bufferId: number, splitId: number): boolean;
+	/**
+	* Close all buffers in split
+	*/
+	closeAllBuffersInSplit(splitId: number): boolean;
+	/**
+	* Close buffers to right in split
+	*/
+	closeBuffersToRightInSplit(bufferId: number, splitId: number): boolean;
+	/**
+	* Close buffers to left in split
+	*/
+	closeBuffersToLeftInSplit(bufferId: number, splitId: number): boolean;
+	/**
+	* Move the active tab to the left in the active split
+	*/
+	moveTabToLeft(): boolean;
+	/**
+	* Move the active tab to the right in the active split
+	*/
+	moveTabToRight(): boolean;
+	/**
 	* Start a frame-buffer animation over an arbitrary screen region.
 	* Returns an animation id usable with `cancelAnimation`.
 	*/
@@ -1635,6 +1864,41 @@ interface EditorAPI {
 	*/
 	getAuthorityLabel(): string;
 	/**
+	* Current Workspace Trust level for the active project:
+	* `"restricted"`, `"trusted"`, or `"blocked"` (empty `""` when trust
+	* state is unavailable, e.g. the default local authority).
+	*
+	* Trust is a per-project, user-granted decision. Plugins that run
+	* repo-controlled work (env activation, project tooling, repo-local
+	* binaries) MUST gate on this and treat anything other than
+	* `"trusted"` as "do not execute".
+	*/
+	workspaceTrustLevel(): "restricted" | "trusted" | "blocked" | "";
+	/**
+	* Activate an environment by setting the live env recipe: an activation
+	* shell `snippet` (e.g. `eval "$(direnv export bash)"`,
+	* `source .venv/bin/activate`, or `""` for a pure login shell) run in
+	* `dir` (defaults to the workspace). It is re-evaluated on demand on the
+	* active backend and applied to every spawn — language servers,
+	* formatters, `spawnProcess` — so they see the project environment. No
+	* authority rebuild; the LSP is restarted to pick it up.
+	*
+	* Honored only when `workspaceTrustLevel() === "trusted"` (it runs
+	* repo-controlled code). Call `clearEnv()` to deactivate.
+	*/
+	setEnv(snippet: string, dir?: string): void;
+	/**
+	* Deactivate the environment set by `setEnv` — spawns return to the
+	* inherited environment.
+	*/
+	clearEnv(): void;
+	/**
+	* Whether an environment is currently active (a recipe was set via
+	* `setEnv`). Survives the restart `setEnv` triggers, so a plugin can
+	* re-establish its file watch and reflect activation after reloading.
+	*/
+	envActive(): boolean;
+	/**
 	* Join path components (variadic - accepts multiple string arguments)
 	* Always uses forward slashes for cross-platform consistency (like Node.js path.posix.join)
 	* 
@@ -1750,6 +2014,64 @@ interface EditorAPI {
 	*/
 	getUserConfig(): unknown;
 	/**
+	* Declare a boolean config field for the calling plugin.
+	* 
+	* Validates `options` synchronously: the JS call throws if any
+	* unknown key is present or if `default` isn't a boolean. The
+	* Settings UI grows a "Plugin Settings → <plugin>" sub-category
+	* containing a toggle for this field. Returns the current value
+	* (user-set if present, otherwise the declared `default`).
+	*/
+	defineConfigBoolean(name: string, options: {
+		default: boolean;
+		description?: string;
+	}): boolean;
+	/**
+	* Declare an integer config field for the calling plugin. Throws on
+	* invalid options or if the default falls outside `minimum/maximum`.
+	*/
+	defineConfigInteger(name: string, options: {
+		default: number;
+		description?: string;
+		minimum?: number;
+		maximum?: number;
+	}): number;
+	/**
+	* Declare a floating-point number config field. Throws on bad
+	* options or default outside `minimum/maximum`.
+	*/
+	defineConfigNumber(name: string, options: {
+		default: number;
+		description?: string;
+		minimum?: number;
+		maximum?: number;
+	}): number;
+	/**
+	* Declare a free-form string config field.
+	*/
+	defineConfigString(name: string, options: {
+		default: string;
+		description?: string;
+	}): string;
+	/**
+	* Declare an array-of-strings config field (e.g. a list of
+	* patterns). The Settings UI renders this as a list editor.
+	*/
+	defineConfigStringArray(name: string, options: {
+		default: string[];
+		description?: string;
+	}): string[];
+	/**
+	* Get the calling plugin's settings as a JS object.
+	* 
+	* Returns the merged value at `config.plugins.<plugin_name>.settings`.
+	* The shape comes from whatever the plugin declared via
+	* `editor.definePluginConfig(...)` (defaults pre-populated by the
+	* host, user overrides on top from the Settings UI). Returns `null`
+	* if the plugin hasn't declared a schema and has no user-set value.
+	*/
+	getPluginConfig(): unknown;
+	/**
 	* Reload configuration from file
 	*/
 	reloadConfig(): void;
@@ -1972,6 +2294,21 @@ interface EditorAPI {
 	*/
 	clearFolds(bufferId: number): boolean;
 	/**
+	* Publish a set of toggleable fold ranges on the buffer. Same
+	* shape an LSP `foldingRange` response would take. Unlike
+	* `addFold`, this does *not* pre-collapse anything — the
+	* standard fold-toggle keybinding finds the range under the
+	* cursor and collapses or expands it on demand. Replacing call
+	* replaces the prior set.
+	* 
+	* `ranges` is a JS array of objects shaped
+	* `{ startLine, endLine, kind? }` (lines are 0-indexed).
+	* `kind` is one of `"comment"`, `"imports"`, `"region"` per
+	* the LSP spec; omitted/unknown values are accepted as plain
+	* folds.
+	*/
+	setFoldingRanges(bufferId: number, rangesArr: Record<string, unknown>[]): boolean;
+	/**
 	* Add a soft break point for marker-based line wrapping
 	*/
 	addSoftBreak(bufferId: number, namespace: string, position: number, indent: number): boolean;
@@ -2046,6 +2383,13 @@ interface EditorAPI {
 	* theme-key string (e.g. `"editor.line_number_fg"`).  Theme keys
 	* are resolved at render time so the line follows theme changes.
 	* Both default to `null` (no foreground / transparent background).
+	* * `gutterGlyph` — optional single character (any short string)
+	* rendered in the line-number column on this virtual line's
+	* first visual row. Use to mark e.g. a deletion line with "-"
+	* so the indicator sits next to the deleted content instead
+	* of on the following source line.
+	* * `gutterColor` — color for `gutterGlyph`, same shape as
+	* `fg`/`bg`. Falls back to the theme's line-number fg.
 	*/
 	addVirtualLine(bufferId: number, position: number, text: string, options: Record<string, unknown>, above: boolean, namespace: string, priority: number): boolean;
 	/**
@@ -2409,6 +2753,15 @@ interface EditorAPI {
 	*/
 	focusBufferGroupPanel(groupId: number, panelName: string): boolean;
 	/**
+	* Re-point a buffer-group's panel at a different buffer id.
+	* 
+	* Streaming plugins (e.g. git-log) allocate one file-backed
+	* buffer per item and call this on navigation to swap which
+	* buffer the panel displays — instead of mutating a single
+	* shared buffer's contents. Resolves with `true` on success.
+	*/
+	setBufferGroupPanelBuffer(groupId: number, panelName: string, bufferId: number): Promise<boolean>;
+	/**
 	* Set virtual buffer content (takes array of entry objects)
 	* 
 	* Note: entries should be TextPropertyEntry[] - uses manual parsing for HashMap support
@@ -2474,8 +2827,13 @@ interface EditorAPI {
 	unmountFloatingWidget(panelId: number): boolean;
 	/**
 	* Spawn a process (async, returns request_id)
+	* 
+	* Optional 4th argument `stdoutTo: string` pipes the child's stdout
+	* directly into the named file instead of buffering it. The
+	* resolved `SpawnResult.stdout` is empty in that case; the bytes
+	* land on disk for `openFile` to pick up as a file-backed buffer.
 	*/
-	spawnProcess(command: string, args: string[], cwd?: string): ProcessHandle<SpawnResult>;
+	spawnProcess(command: string, args: string[], cwd?: string, stdoutTo?: string): ProcessHandle<SpawnResult>;
 	/**
 	* Spawn a process on the host regardless of the active authority.
 	* 
@@ -2527,6 +2885,19 @@ interface EditorAPI {
 	*/
 	clearRemoteIndicatorState(): void;
 	/**
+	* Fetch a URL over HTTP(S) and stream the response body into `target_path`.
+	* 
+	* Resolves with a `SpawnResult`-shaped value: `exit_code` is `0` on a
+	* 2xx response (file written), the HTTP status code on non-2xx
+	* (target file untouched), and `-1` on transport errors. `stderr`
+	* carries an error message in the non-success cases; `stdout` is
+	* always empty.
+	* 
+	* This uses the editor's built-in HTTP client (`ureq`), so plugins
+	* don't need `curl`/`wget` on PATH.
+	*/
+	httpFetch(url: string, targetPath: string): ProcessHandle<SpawnResult>;
+	/**
 	* Wait for a process to complete and get its result (async)
 	*/
 	spawnProcessWait(processId: number): Promise<SpawnResult>;
@@ -2579,6 +2950,14 @@ interface EditorAPI {
 	*/
 	createTerminal(opts?: CreateTerminalOptions): Promise<TerminalResult>;
 	/**
+	* Create a new editor window seeded with an agent terminal as
+	* its only buffer. Atomic — replaces the legacy
+	* `createWindow` + `setActiveWindow` + `createTerminal`
+	* chain that left a transient `[No Name]` tab alongside the
+	* agent terminal.
+	*/
+	createWindowWithTerminal(opts: CreateWindowWithTerminalOptions): Promise<SessionWithTerminalResult>;
+	/**
 	* Send input data to a terminal
 	*/
 	sendTerminalInput(terminalId: number, data: string): boolean;
@@ -2635,6 +3014,33 @@ interface EditorAPI {
 	getPluginApi<K extends keyof FreshPluginRegistry>(name: K): FreshPluginRegistry[K] | null;
 }
 /**
+* Typed overload of `editor.defineConfigEnum`. The macro-generated
+* signature can't express `<E extends string>` propagating from the
+* `values` array into the return type, so it's declared here. Use
+* `as const` on the `values` array to get a literal-union return:
+*
+* ```ts
+* const mode = editor.defineConfigEnum("mode", {
+*   values: ["normal", "insert"] as const,
+*   default: "normal",
+* });
+* mode; // typed as "normal" | "insert"
+* ```
+*
+* Typed overload of `editor.getPluginConfig`. Plugins that declared
+* their fields via `defineConfigX` can pass the shape type explicitly:
+* `editor.getPluginConfig<{ autoEnable: boolean; ... }>()`. Without
+* the generic, falls back to `unknown`.
+*/
+interface EditorAPI {
+	defineConfigEnum<E extends string>(name: string, options: {
+		values: readonly E[];
+		default: NoInfer<E>;
+		description?: string;
+	}): E;
+	getPluginConfig<T = unknown>(): T;
+}
+/**
 * Maps every hook event name to its payload type.
 *
 * Payloads match the flat JSON produced by `hook_args_to_json` on the Rust