@neosh/api 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neosh/api",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "The neosh plugin API. Types are generated from the Rust side and drift-checked in CI.",
   "license": "MIT",
   "type": "module",

package/src/generated/ApiCall.ts

@@ -32,6 +32,7 @@ import type { ProjectKey } from "./ProjectKey";
 import type { ProviderEvent } from "./ProviderEvent";
 import type { QuotaSnapshot } from "./QuotaSnapshot";
 import type { Rect } from "./Rect";
+import type { ScrollAmount } from "./ScrollAmount";
 import type { SelectShape } from "./SelectShape";
 import type { SessionId } from "./SessionId";
 import type { StatusSegment } from "./StatusSegment";
@@ -113,6 +114,7 @@ export type ApiCall =
   | { "call": "win_set_cursor"; win: WindowId; row: number; col: number }
   | { "call": "win_get_viewport"; win: WindowId }
   | { "call": "win_scroll_to"; win: WindowId; top_line: number | null }
+  | { "call": "win_scroll"; win: WindowId; amount: ScrollAmount }
   | { "call": "win_list" }
   | {
     "call": "pane_split";
@@ -139,7 +141,18 @@ export type ApiCall =
      * work somewhere is not, for the same reason `SessionNew { activate: false }` exists.
      */
     activate: boolean;
+    /**
+     * Which strip to open it on. See [`TabInfo::group`].
+     *
+     * `None` inherits the tab you are on, which is what a new tab almost always wants: opened
+     * while reading a conversation, it is that conversation's. Saying one is for a caller
+     * putting a tab somewhere *else* — and a group nothing is currently showing is a tab that
+     * is made and is off the bar, which is a legitimate thing to want and a surprising thing
+     * to do by accident.
+     */
+    group?: string | null;
   }
+  | { "call": "tab_group"; tab: TabId; group: string | null }
   | { "call": "tab_close"; tab: TabId }
   | { "call": "tab_select"; tab: TabId }
   | { "call": "tab_step"; view?: ViewId | null; delta: number }
@@ -478,12 +491,37 @@ export type ApiCall =
   | { "call": "git_stage"; paths: Array<string> }
   | { "call": "git_unstage"; paths: Array<string> }
   | { "call": "git_commit"; message: string }
+  | {
+    "call": "git_fetch";
+    /**
+     * The repository to fetch in. The conversation's own when absent.
+     */
+    cwd?: string | null;
+  }
   | {
     "call": "git_pull";
     /**
      * The repository to pull in. The conversation's own when absent.
      */
     cwd?: string | null;
+    /**
+     * Replay this branch's own commits on top of what arrived, rather than merging.
+     *
+     * A flag rather than a call of its own because it is one argument to one command, and the
+     * caller that needs it is the one that has just been told the branch diverged — at which
+     * point "rebase or merge" is the question being answered, and two entry points for the two
+     * answers would be two things to keep in step for no gain.
+     *
+     * It rewrites local commits, which is why nothing sets it without asking first.
+     */
+    rebase: boolean;
+  }
+  | {
+    "call": "forge_pulls";
+    /**
+     * The repository to ask about. The conversation's own when absent.
+     */
+    cwd?: string | null;
   }
   | {
     "call": "git_add_worktree";
@@ -507,6 +545,32 @@ export type ApiCall =
      */
     cwd?: string | null;
   }
+  | {
+    "call": "git_clone";
+    /**
+     * Anything `git clone` takes: an `https://` or `git@` URL, or a local path.
+     */
+    url: string;
+    /**
+     * Where the working tree lands, in full. The caller resolved the root and the name, so
+     * that a picker can *show* the destination on the row before anything is written.
+     */
+    path: string;
+  }
+  | {
+    "call": "git_move_worktree";
+    path: string;
+    /**
+     * Where it lands, in full. The leaf must not exist; the parent is created.
+     */
+    dest: string;
+    /**
+     * The repository it belongs to. `git worktree move` runs from a checkout, and the
+     * conversation the caller is in may be standing in the one being moved — the same reason
+     * [`Self::GitRemoveWorktree`] takes one.
+     */
+    cwd?: string | null;
+  }
   | {
     "call": "gen_complete";
     prompt: string;
@@ -515,6 +579,30 @@ export type ApiCall =
      * Ask for JSON and parse it host-side, tolerating the code fences models wrap it in.
      */
     json: boolean;
+    /**
+     * The one key the answer is *about*, when the whole answer is one value.
+     *
+     * A prompt that says "return `{"branch": …}`" is answered with the object most of the
+     * time and with a bare `fix/composer-paste` the rest of it — the model did the work and
+     * skipped the envelope, and a caller that only accepts the envelope throws a correct
+     * answer away. Measured on this workspace's own history it was two runs in twenty-two:
+     * twice a branch was never named, silently, and both times the name was sitting in the
+     * reply.
+     *
+     * So: extraction first, exactly as before, and this is what a *bare* answer means. Named
+     * rather than inferred, because only the caller knows which key one value belongs under
+     * — and absent, nothing changes, which is what every existing caller wants.
+     *
+     * Only for a one-value answer. A commit message is a subject *and* a body, and guessing
+     * which half a bare paragraph is would be inventing the other one.
+     *
+     * And only for a value a *wrong* answer is recognisable in. A branch name is checkable
+     * and one `git branch -m` from being fixed; a thread title is any short line, which is
+     * also what a refusal and a driver's own error message look like — there the envelope is
+     * the only evidence the question was answered rather than commented on, and it is worth
+     * the one reply in ten that arrives without it.
+     */
+    field?: string | null;
     /**
      * Defaults to `gen.model` if set, else the session's own selection.
      */
@@ -562,6 +650,16 @@ export type ApiCall =
      * Ask the network again rather than answering from the last check.
      */
     force: boolean;
+    /**
+     * Answer from what this machine already knows, and never reach the network.
+     *
+     * The two are not opposites and are never both set: `local` is checked first and wins.
+     * It exists because half of an update status is not about a registry at all —
+     * [`UpdateStatus::restart_pending`] is a `stat` of one file — and a caller that wants
+     * only that half should not be the reason a workspace makes an HTTP request. Which is
+     * what a panel polling for "has something replaced my binary" would otherwise be.
+     */
+    local: boolean;
   }
   | { "call": "update_apply" }
   | {

package/src/generated/ApiOk.ts

@@ -25,6 +25,7 @@ import type { PermissionDecision } from "./PermissionDecision";
 import type { PermissionMode } from "./PermissionMode";
 import type { PluginInfo } from "./PluginInfo";
 import type { PointInfo } from "./PointInfo";
+import type { PullRequest } from "./PullRequest";
 import type { QuestionAnswer } from "./QuestionAnswer";
 import type { QuotaSample } from "./QuotaSample";
 import type { QuotaSnapshot } from "./QuotaSnapshot";
@@ -92,6 +93,7 @@ export type ApiOk =
   | { "ok": "status"; status: RepoStatus }
   | { "ok": "branches"; branches: Array<BranchInfo> }
   | { "ok": "worktrees"; worktrees: Array<WorktreeInfo> }
+  | { "ok": "pulls"; pulls: Array<PullRequest> }
   | { "ok": "commits"; commits: Array<CommitInfo> }
   | { "ok": "commit"; commit: CommitInfo }
   | { "ok": "text"; text: string }

package/src/generated/ChecksState.ts

@@ -0,0 +1,14 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * What the forge's checks say, folded to the one thing a row has room for.
+ *
+ * Folded here rather than on the wire as a list, because the question a project row answers is
+ * "is anything wrong" and the answer is one glyph. The counts travel beside it for whoever wants
+ * to say `✗2`; the full list of check names is a panel's job and a different call.
+ *
+ * `Pending` and `None` are deliberately different. Nothing has run yet is a state that resolves on
+ * its own in a few minutes; there are no checks configured at all is permanent, and drawing a
+ * spinner over it for ever is the failure this distinction avoids.
+ */
+export type ChecksState = "none" | "pending" | "passing" | "failing";

package/src/generated/FloatConfig.ts

@@ -23,6 +23,17 @@ export type FloatConfig = {
    */
   border_hl?: string | null;
   title?: string | null;
+  /**
+   * A strip on the bottom border: what the keys here do.
+   *
+   * On the border rather than in the buffer, because a key strip written as a row of content is
+   * one that scrolls away exactly when it is wanted, and is the first thing clipped on a terminal
+   * too short for the panel. Both of those happened: the picker's strip is the row that says how
+   * to get out, and on a sixteen-row screen it was the row that did not fit.
+   *
+   * Clipped to the border's width like the title, so it is for a legend and not for prose.
+   */
+  footer?: string | null;
   /**
    * Close automatically when focus moves elsewhere. The right default for pickers and hovers.
    */
@@ -60,4 +71,26 @@ export type FloatConfig = {
    * characters through to the composer would be typing into a field you cannot see.
    */
   modal: boolean;
+  /**
+   * This panel is a place you can move in when it does not fit.
+   *
+   * A float asks for a height and the frontend gives it what there is — so on a short terminal
+   * every row past the bottom edge is content that exists, is drawn nowhere, and has no key
+   * pointed at it. `height: Max { n: 30 }` on a twenty-row screen is not thirty rows of panel, it
+   * is ten rows of panel and twenty rows nobody can reach.
+   *
+   * Setting this adds one scope to the keymap chain while this float has focus —
+   * `BufKind { name: "neosh.scroll" }` — which is where the workspace binds the reader's motions:
+   * `j`/`k`, `<C-d>`/`<C-u>`, `<C-f>`/`<C-b>`, `gg`/`G`, the arrows and the paging keys. A scope
+   * rather than a capture, so all three of the usual rules hold: `^Z` lists the keys, `init.ts`
+   * moves them, and a panel that wants `j` for something of its own binds it on *its* kind, which
+   * is nearer and wins. It sits below the panel's own kind and above `Global`, so it is a default
+   * that never takes a key away from the thing it is scrolling.
+   *
+   * Off by default, and not for want of ambition: a picker whose filter takes printable
+   * characters through a capture would have `j` and `G` resolved out from under it by a scope, so
+   * typing a model's name would scroll instead of filtering. A panel that already moves in itself
+   * says so by staying quiet here.
+   */
+  scroll: boolean;
 };

package/src/generated/ModelInfo.ts

@@ -27,4 +27,20 @@ export type ModelInfo = {
    * numbers are already columns.
    */
   tagline?: string | null;
+  /**
+   * Why this one cannot be chosen here, in a sentence, or nothing when it can.
+   *
+   * A model a driver lists but will not run — the vendor CLI on this machine is too old for it,
+   * most often. Said rather than filtered out, for the reason a missing provider is listed
+   * rather than dropped: nothing there and not allowed are the same empty list, and only one of
+   * them is fixed by doing something. A model that silently vanishes from the picker is a
+   * question with nowhere to ask it — you go looking for the release notes, or for our bug
+   * tracker, and the answer was one `claude update` away the whole time.
+   *
+   * The sentence carries the fix, not just the diagnosis: "needs claude 2.1.251 — run `claude
+   * update`" is actionable and "unsupported model" is not. Anything reading a catalogue to
+   * *choose* — the startup default, `model.upgrade`, `model.line` — skips these; only a picker
+   * draws them, and draws them disabled.
+   */
+  unavailable?: string | null;
 };

package/src/generated/PluginEvent.ts

@@ -63,6 +63,7 @@ export type PluginEvent =
   | { "type": "composer_changed"; text: string }
   | { "type": "event"; name: string; data?: unknown; from: string }
   | { "type": "var_changed"; scope: VarScope; key: string; value?: unknown }
+  | { "type": "project_moved"; from: string; to: string }
   | { "type": "highlight_changed"; names: Array<string> }
   | { "type": "contributions_changed"; point: string }
   | { "type": "swarm_changed" }

package/src/generated/PullRequest.ts

@@ -0,0 +1,30 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ChecksState } from "./ChecksState";
+import type { PullState } from "./PullState";
+
+/**
+ * One pull request, as much of it as a row can use.
+ *
+ * **Keyed by `branch`**, which is what makes one call answer for every worktree at once: a
+ * repository's pull requests come back together and each checkout finds its own by the branch it
+ * has out. Asking per branch would be one network round trip per row in the panel.
+ */
+export type PullRequest = {
+  number: number;
+  title: string;
+  /**
+   * For opening it. The forge's own URL, so nothing here has to know how to build one.
+   */
+  url: string;
+  /**
+   * The head branch. What a checkout matches itself against.
+   */
+  branch: string;
+  state: PullState;
+  checks: ChecksState;
+  /**
+   * How many checks have failed, for a row that wants to say `✗2` rather than `✗`.
+   */
+  checks_failed: number;
+  checks_total: number;
+};

package/src/generated/PullState.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Where a pull request has got to.
+ *
+ * Four states because that is what a person means by "what happened to it": one is a review you
+ * are waiting for, one is a review you have not asked for yet, one is done, and one is not going
+ * to happen. Draft is its own state rather than a flag on `Open` because on a row it is the whole
+ * difference between "somebody should look at this" and "I am still writing it".
+ */
+export type PullState = "open" | "draft" | "merged" | "closed";

package/src/generated/ScrollAmount.ts

@@ -0,0 +1,16 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * How far to move a window's scroll. See [`crate::ApiCall::WinScroll`].
+ *
+ * Verbs rather than a row number, for the reason [`CursorMotion`] is: only the core knows how many
+ * buffer rows the frontend last drew, so "half a screen" is a question the caller cannot answer and
+ * a caller that tried would answer it with a height. Signed, so one variant covers both directions
+ * and a binding for `<C-d>` is the binding for `<C-u>` with the sign flipped.
+ */
+export type ScrollAmount =
+  | { "kind": "lines"; n: number }
+  | { "kind": "half"; n: number }
+  | { "kind": "page"; n: number }
+  | { "kind": "top" }
+  | { "kind": "bottom" };

package/src/generated/TabInfo.ts

@@ -24,4 +24,20 @@ export type TabInfo = {
    * rather than in whichever pane happens to be first.
    */
   active_pane: PaneId;
+  /**
+   * Which strip this tab is on — the conversation it belongs to.
+   *
+   * **A tab belongs to a conversation, and the bar shows one conversation's tabs.** A shell
+   * opened while reading one is *that* conversation's shell: it was started in its directory,
+   * about its work, and a bar that goes on showing it after you have switched is a bar about
+   * the terminal rather than about what you are doing. The tabs of the conversations you are
+   * not in are not closed, and nothing in them stops — they are off the strip until you go
+   * back, which is what makes leaving a build running and returning to it work.
+   *
+   * Opaque here and in the editor, which only ever asks whether two of them are equal: the host
+   * fills it with a [`crate::SessionId`], and a plugin that grouped its tabs by project would be
+   * using it exactly as intended. `None` is a group of its own — where a tab nobody has filed
+   * sits, and what every tab was before this existed.
+   */
+  group?: string | null;
 };

package/src/generated/UiEvent.ts

@@ -81,4 +81,21 @@ export type UiEvent =
   }
   | { "type": "clipboard"; text: string }
   | { "type": "flush" }
-  | { "type": "shutdown" };
+  | {
+    "type": "shutdown";
+    /**
+     * Whether it is coming straight back, and this terminal should follow it.
+     *
+     * `neosh stop` and a restart are the same shutdown — conversations flushed, plugins torn
+     * down — and they differ entirely in what the *terminal* should do next. Stopping is
+     * somebody finishing; a restart is the second half of an update, and a terminal that
+     * exits to the shell there has turned "finish updating" into "and now type `neosh`
+     * again", which is the step nobody knows is owed. It cannot be worked out at the far end
+     * either: from a closed socket, a workspace that stopped and a workspace that is
+     * restarting look identical.
+     *
+     * `#[serde(default)]` so an older terminal reads it as an ordinary stop, which is the
+     * behaviour it already has.
+     */
+    restarting: boolean;
+  };

package/src/generated/UpdateStatus.ts

@@ -33,7 +33,27 @@ export type UpdateStatus = {
    */
   error?: string | null;
   /**
-   * Whether an update has been downloaded and is waiting for a restart.
+   * Whether the binary on disk is not the one this process is running.
+   *
+   * Not "whether neosh downloaded something": most installs are updated by somebody else's
+   * package manager, in another terminal, and the workspace goes on executing the inode it
+   * started with — which is the whole failure this field exists to name. `brew upgrade neosh`
+   * finishes, says so, and leaves a workspace running the old code with nothing on screen to
+   * say why the thing you just installed is not there. So this is a `stat` of the running
+   * executable against the stamp taken at startup, and it is true for a self-update, a
+   * `brew upgrade`, an `npm install -g` and a re-run of `install.sh` alike.
+   *
+   * Never set when there is no binary left to restart onto: a promise of a restart that cannot
+   * come back is worse than saying nothing.
    */
   restart_pending: boolean;
+  /**
+   * What is waiting on disk, when it could be read.
+   *
+   * Asked of the binary itself (`neosh --version`) rather than assumed to be
+   * [`latest`](UpdateStatus::latest): somebody who ran `brew upgrade` got whatever Homebrew had,
+   * which is not always the newest release, and a row naming the wrong number is a row that
+   * teaches you not to read it. `None` means *something* changed and it would not say what.
+   */
+  restart_version?: string | null;
 };