@neosh/api 0.4.0 → 0.4.2

package/src/index.ts

@@ -36,6 +36,7 @@ import type { CredentialSource } from "./generated/CredentialSource";
 import type { CursorMotion } from "./generated/CursorMotion";
 import type { CursorShape } from "./generated/CursorShape";
 import type { SelectShape } from "./generated/SelectShape";
+import type { ScrollAmount } from "./generated/ScrollAmount";
 import type { DiffTarget } from "./generated/DiffTarget";
 import type { Dock } from "./generated/Dock";
 import type { Gravity } from "./generated/Gravity";
@@ -136,6 +137,9 @@ import type { Viewport } from "./generated/Viewport";
 import type { WindowId } from "./generated/WindowId";
 import type { WindowInfo } from "./generated/WindowInfo";
 import type { WindowLayout } from "./generated/WindowLayout";
+import type { ChecksState } from "./generated/ChecksState";
+import type { PullRequest } from "./generated/PullRequest";
+import type { PullState } from "./generated/PullState";
 import type { WorktreeInfo } from "./generated/WorktreeInfo";
 
 export type {
@@ -153,12 +157,15 @@ export type {
   CostBasis, QuotaCredits, QuotaSample, QuotaSeverity, QuotaSnapshot, QuotaSource, QuotaWindow,
   InstallMethod, UpdateOutcome, UpdateStatus,
   UsageBucket, UsageHistory, UsageResolution, UsageScanSource,
-  Rect, RepoInfo, RepoStatus, SelectShape, SessionId, SessionInfo, StatusAlign, StatusSegment, StopReason,
+  Rect, RepoInfo, RepoStatus, ScrollAmount, SelectShape, SessionId, SessionInfo, StatusAlign, StatusSegment, StopReason,
   SurfaceCell, SurfaceId, TextEdit, ToolCall, ToolDef, ToolResult, TurnRequest, Usage,
   NodeCapabilities, NodeId, NodeInfo, ProjectKey, RemoteProject, StreamEvent,
   SwarmAgent, SwarmNode, SwarmStranger,
   VarScope, ViewId, ViewInfo, Viewport,
   WindowId, WindowInfo, WindowLayout,
+  ChecksState,
+  PullRequest,
+  PullState,
   WorktreeInfo,
 };
 
@@ -368,6 +375,16 @@ export interface FloatOptions {
   border?: FloatConfig["border"];
   borderHl?: string;
   title?: string;
+  /**
+   * 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. It costs no content row and cannot be scrolled off.
+   *
+   * Clipped to the border's width like the title, so it is for a legend and not for prose.
+   */
+  footer?: string;
   closeOnBlur?: boolean;
   focusable?: boolean;
   /**
@@ -384,6 +401,24 @@ export interface FloatOptions {
    * control sheet. Not for a hint or a hover card.
    */
   modal?: boolean;
+  /**
+   * This panel is a place you can move in when it does not fit.
+   *
+   * You ask for a height and get whatever there is: `{ kind: "max", n: 30 }` on a twenty-row
+   * terminal is ten rows of panel and twenty rows of content drawn nowhere, with no key pointed at
+   * them and nothing on screen to say they exist. Set this and the workspace's scroll keys resolve
+   * here — `j`/`k`, `^D`/`^U`, `^F`/`^B`, `gg`/`G`, the arrows and the paging keys — along with the
+   * mouse wheel, and a bar appears down the right border while anything is hidden.
+   *
+   * They are ordinary bindings on `{ kind: "buf_kind", name: "neosh.scroll" }`, so `^Z` lists them
+   * and `init.ts` moves them. That scope sits *below* your buffer's own kind, so a key you bind on
+   * your panel is still yours — and above `global`, so it works under `modal` too.
+   *
+   * For a panel of rows you read: a key sheet, a diff, a status, a help screen. **Not** for one with
+   * a cursor of its own — a picker, a list — which already scrolls to keep the cursor on screen and
+   * whose filter would lose `j` and `G` to this.
+   */
+  scroll?: boolean;
 }
 
 export interface Neosh {
@@ -415,6 +450,8 @@ export interface Neosh {
   readonly opt: OptionApi;
   readonly state: StateApi;
   readonly vars: VarApi;
+  /** The directories somebody works in. See {@link ProjectApi}. */
+  readonly project: ProjectApi;
   readonly ext: ExtensionApi;
   readonly event: EventApi;
   readonly swarm: SwarmApi;
@@ -625,21 +662,63 @@ export interface PaneApi {
   equalize(view?: ViewId): Promise<void>;
 }
 
-/** The tabs of one terminal. Each is a title and a tree of panes. */
+/**
+ * The tabs of one terminal. Each is a title, a tree of panes, and the conversation it belongs to.
+ *
+ * **A tab belongs to a conversation, and the bar shows one conversation's tabs** — that is
+ * {@link TabInfo.group}, and it is why a shell opened while reading one conversation is not still
+ * on the bar after you have switched to another. 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 splits these calls in two. {@link TabApi.list} answers with *every* tab of a terminal,
+ * whatever bar it is on, because "what is open here" is a real question — and {@link TabApi.step},
+ * {@link TabApi.move} and the numbers on the strip all count the tabs of one conversation, because
+ * a key about where you are looking must not change what you are working on.
+ */
 export interface TabApi {
-  /** Every tab of a terminal, its panes, and which one is on screen. */
+  /**
+   * Every tab of a terminal, its panes, and which one is on screen.
+   *
+   * All of them, including the ones on other conversations' bars: filter by {@link TabInfo.group}
+   * for what is drawn, which is the tabs sharing the active tab's group.
+   */
   list(view?: ViewId): Promise<{ tabs: TabInfo[]; active: TabId }>;
   /**
    * Open a tab with one empty pane. `activate` goes to it — `false` is for putting work somewhere
    * without moving the screen out from under whoever is reading it.
+   *
+   * On the bar you are looking at unless `group` says otherwise: a tab opened while reading a
+   * conversation is that conversation's, which is what a new tab almost always wants.
+   */
+  create(opts?: {
+    title?: string;
+    activate?: boolean;
+    view?: ViewId;
+    group?: string;
+  }): Promise<TabId>;
+  /**
+   * Move a tab to another conversation's bar, or to nobody's with `null`. See
+   * {@link TabInfo.group}.
+   *
+   * It keeps its panes, its windows and anything running in them — this says which bar it is on
+   * and nothing else, so moving the tab you are *in* changes which other tabs are beside it.
    */
-  create(opts?: { title?: string; activate?: boolean; view?: ViewId }): Promise<TabId>;
-  /** Close a tab and every pane in it. Rejects on a terminal's last tab. */
+  group(tab: TabId, group: string | null): Promise<void>;
+  /** Close a tab and every pane in it. Rejects on a conversation's last tab. */
   close(tab: TabId): Promise<void>;
   select(tab: TabId): Promise<void>;
-  /** Go `delta` tabs along, wrapping — a tab bar is a list you can see all of. */
+  /**
+   * Go `delta` tabs along, wrapping — a tab bar is a list you can see all of. Along *this
+   * conversation's* tabs: stepping into another one's would be a key that changes what you are
+   * working on.
+   */
   step(delta: number, view?: ViewId): Promise<void>;
-  /** Move a tab along the bar, clamped at the ends. This is a drag; a drag that teleports is a bug. */
+  /**
+   * Move a tab along the bar, clamped at the ends. This is a drag; a drag that teleports is a bug.
+   *
+   * `to` counts the tabs on the bar, which is the number printed on the strip — the tabs of other
+   * conversations sit between these and are not places a drag can land.
+   */
   move(tab: TabId, to: number): Promise<void>;
   /** Name a tab, or pass `null` to give it back its derived name. */
   rename(tab: TabId, title: string | null): Promise<void>;
@@ -689,6 +768,19 @@ export interface WindowApi {
    * its first row at `0`. Anything else shows the same thing either way.
    */
   scrollTo(win: WindowId, topLine: number | null): Promise<void>;
+  /**
+   * Move a window's scroll by a line, a half screen, a screen, or all the way to an end.
+   *
+   * What {@link scrollTo} cannot express, because the arithmetic is not yours to do: "half a screen"
+   * is counted in the buffer rows the frontend actually drew — which on a wrapping window is fewer
+   * than its height — and the floor is the last screenful rather than the last line, so the bottom
+   * is a full panel and not one row above an empty one. Both numbers are a frame old by the time
+   * {@link viewport} hands them to you; this reads them where they live.
+   *
+   * The keys bound on `neosh.scroll` run exactly this. Call it directly for a scroll a key did not
+   * ask for — following output, or a button on a panel of your own.
+   */
+  scroll(win: WindowId, amount: ScrollAmount): Promise<void>;
   /**
    * How big this window actually is, in cells.
    *
@@ -1152,12 +1244,52 @@ export interface GitApi {
   stage(paths?: string[]): Promise<void>;
   unstage(paths?: string[]): Promise<void>;
   commit(message: string): Promise<CommitInfo>;
+  /**
+   * `git fetch --prune`, answering with where the tree stands *after* it.
+   *
+   * **The one call that makes `ahead` and `behind` mean anything.** `status()` reads them off
+   * `git status --branch`, which compares HEAD with the remote-tracking ref sitting on this disk —
+   * so a panel drawing `↓0` from it is reporting the state of the world as of whenever this
+   * checkout last spoke to a remote. Call this first and the number is news; do not, and it is
+   * archaeology.
+   *
+   * It answers with the fresh {@link RepoStatus} rather than nothing, so "fetch and see where I am"
+   * is one round trip. Prunes, because a picker offering six branches that were deleted when their
+   * pull requests merged is worse than one that is a fetch behind.
+   *
+   * A write, and the reason is the network rather than the working tree, which does not move:
+   * this contacts a remote and writes refs. It fails rather than hangs when there are no
+   * credentials — stdin is closed and every askpass unset — which is what makes it safe to put on
+   * a timer. Expect it to reject routinely: no remote, no network, a key the host will not take.
+   */
+  fetch(opts?: { cwd?: string }): Promise<RepoStatus>;
+  /**
+   * Every pull request the forge knows about for this repository, open and closed.
+   *
+   * **One call answers for every checkout.** They come back keyed by
+   * {@link PullRequest.branch}, so a repository with six worktrees is one request and six lookups
+   * — which is the difference between a panel that costs a round trip every few minutes and one
+   * that costs six.
+   *
+   * Answered by `gh`, the CLI the user has already signed into, so tokens, enterprise hosts, SSO
+   * and rate limits are already handled and the answer is the one they get in their own terminal.
+   *
+   * **Rejects rather than answering empty** when it cannot know — no `gh`, not signed in, no
+   * remote on a forge. An empty list is the claim "this repository has no pull requests", and
+   * three of the four ways this fails would be making it falsely. Catch it, say it once, and do
+   * not say it again every tick.
+   */
+  pulls(opts?: { cwd?: string }): Promise<PullRequest[]>;
   /**
    * `git pull`, answering with git's own summary — "Already up to date.", the fast-forward range —
    * because those are different answers and a caller showing neither is a caller nobody trusts.
    * `cwd` picks the repository, as everywhere; absent means the conversation's own.
+   *
+   * `rebase` replays this branch's commits on top of what arrived instead of merging them. It is
+   * the answer to a diverged branch and it rewrites local commits, so ask before you set it — the
+   * caller this exists for is a panel that has just said "diverged" and offered the choice.
    */
-  pull(opts?: { cwd?: string }): Promise<string>;
+  pull(opts?: { cwd?: string; rebase?: boolean }): Promise<string>;
   addWorktree(
     path: string,
     branch: string,
@@ -1169,6 +1301,60 @@ export interface GitApi {
    * exactly that one.
    */
   removeWorktree(path: string, opts?: { force?: boolean; cwd?: string }): Promise<void>;
+  /**
+   * Move a worktree to `dest` — `git worktree move`, and everything that has to follow it.
+   *
+   * A worktree's path is an identity here, not a coordinate: it is the key of the project facts
+   * every list draws, of the conversations living in it, of the project vars holding a pin and a
+   * fold state, and of the working directory each vendor CLI was started in. This call moves all
+   * of them, which is why it is a call rather than a `git worktree move` you could have run
+   * yourself — the git part is the part that was never hard.
+   *
+   * `dest` is the full path it lands at. Its parent is created; the leaf must not exist.
+   *
+   * Refused while a turn is running anywhere in the tree, because a CLI holds its working
+   * directory from the moment it is spawned and would otherwise write the file it is editing into
+   * the place the tree used to be. Interrupt it and ask again.
+   *
+   * `cwd` names the repository, as everywhere.
+   */
+  moveWorktree(path: string, dest: string, opts?: { cwd?: string }): Promise<void>;
+  /**
+   * Clone `url` into `path`, resolving to the path once it is there.
+   *
+   * The one call here with no `cwd`: everything else asks a repository a question, and this one
+   * arrives before there is a repository to ask. `path` is absolute and its parent need not
+   * exist — cloning into a location you have just invented is the ordinary case.
+   *
+   * **It reports progress while it runs**, on the bus as {@link CLONE_EVENT}, so a caller that
+   * wants to draw a clone rather than block on one subscribes before awaiting this. Keyed by
+   * `path`, because a workspace may be cloning two things at once.
+   *
+   * Needs `vcs_write` in the manifest, like every other call here that changes a disk.
+   */
+  clone(url: string, path: string): Promise<string>;
+}
+
+/**
+ * What {@link GitApi.clone} says about itself while it runs, on {@link EventsApi.on}.
+ *
+ * `phase` is git's own word for what it is doing — `Receiving objects`, `Resolving deltas` — and
+ * `percent` is absent for the phases that have no total, which draw as a spinner rather than as a
+ * bar. `done` arrives exactly once per clone, on success and on failure alike, because a panel
+ * drawing itself from these has no other way to learn it may stop.
+ */
+export const CLONE_EVENT = "neosh.git.clone";
+
+/** One {@link CLONE_EVENT} payload. */
+export interface CloneProgress {
+  /** Which clone this is about. The key, since two may be running. */
+  path: string;
+  url: string;
+  phase: string;
+  percent?: number | null;
+  done?: boolean;
+  /** Present, with git's own last word in it, only when the clone failed. */
+  error?: string;
 }
 
 /**
@@ -1190,6 +1376,32 @@ export interface GenApi {
    * do not each reimplement that. Rejects if there is no JSON in the response at all.
    */
   json<T = unknown>(prompt: string, opts?: { system?: string; selection?: ModelSelection }): Promise<T>;
+  /**
+   * One value, asked for as JSON and accepted however it comes back.
+   *
+   * The shape almost every generating plugin actually wants: a branch name, a thread title, a PR
+   * subject — one string, asked for as `{"branch": …}` because that is how you pin a model down,
+   * and answered as a bare `fix/composer-paste` often enough to matter. Both are the same answer,
+   * and {@link GenApi.json} rejects the second one — which is a correct name thrown away, with
+   * nothing on screen to say so.
+   *
+   * So the key is passed down and a bare reply is read as its value. Everything
+   * {@link GenApi.json} tolerates is tolerated first and unchanged; this is only what happens when
+   * there is no JSON at all. Rejects on an empty answer, or on prose it will not guess at.
+   *
+   * For one value only. A commit message is a subject and a body, and there is no answering the
+   * question of which one a lone paragraph is — that stays {@link GenApi.json}.
+   *
+   * And only for a value you would know was wrong on sight. A branch name is that, and a wrong one
+   * is one rename away; a thread title is any short line, and so is a refusal or a driver's own
+   * error message — where nothing distinguishes an answer from a remark, the envelope is the
+   * evidence, and {@link GenApi.json} is the call.
+   */
+  field(
+    prompt: string,
+    key: string,
+    opts?: { system?: string; selection?: ModelSelection },
+  ): Promise<string>;
 }
 
 /**
@@ -1449,6 +1661,27 @@ export interface VarApi {
   ): Disposable;
 }
 
+/**
+ * The directories somebody works in, and the one thing that can happen to one.
+ *
+ * A project *is* its path everywhere else in this API — `projectScope` keys vars by it, a panel's
+ * list is a list of them, `SessionInfo.cwd` names one. Which is exactly why a path that changes
+ * needs saying out loud rather than inferring: from the outside, a worktree that moved and a
+ * project that was deleted while another was added are the same two facts in the same order.
+ */
+export interface ProjectApi {
+  /**
+   * A project's directory is now somewhere else — a worktree that was relocated.
+   *
+   * The host has already moved everything it owns by the time this arrives: the conversations, the
+   * project vars, the names and branches every list draws. What is left is whatever *you* keyed by
+   * the old path — a list of directories, a cache, a decoration target — and the point of getting
+   * both ends in one event is that you can re-key in place instead of dropping a row and gaining a
+   * stranger.
+   */
+  onMove(cb: (e: { from: string; to: string }) => void): Disposable;
+}
+
 /** Sugar for the two scopes anything with a panel spends its time in. */
 export function projectScope(cwd: string): VarScope {
   return { scope: "project", cwd };
@@ -1600,6 +1833,17 @@ export interface UpdateApi {
    * {@link UpdateStatus.error} when it is there.
    */
   check(force?: boolean): Promise<UpdateStatus>;
+  /**
+   * The same answer, from this machine alone, never touching the network.
+   *
+   * Which is enough for the half that matters most often. {@link UpdateStatus.restart_pending} is a
+   * `stat` of one file — *is the binary on disk the binary this workspace is running* — and it goes
+   * true when somebody runs `brew upgrade neosh` in another terminal, which is how most installs
+   * are actually updated and the moment nothing used to say anything. Cheap enough to poll on a
+   * tick; {@link check} is not, and a panel that used it for this would be a workspace making an
+   * HTTP request every thirty seconds.
+   */
+  local(): Promise<UpdateStatus>;
   /**
    * Update, by whichever route this install takes.
    *
@@ -1876,6 +2120,7 @@ interface Registered {
   composerListeners: Array<(e: { text: string }) => void>;
   activityListeners: Array<(e: { session: SessionId; turn: string; activity: Activity }) => void>;
   varListeners: Array<(e: { scope: VarScope; key: string; value: unknown }) => void>;
+  projectMovedListeners: Array<(e: { from: string; to: string }) => void>;
   swarmListeners: Array<() => void>;
   quotaListeners: Array<(snapshot: QuotaSnapshot) => void>;
   swarmStreamListeners: Array<
@@ -1922,6 +2167,7 @@ function reg(plugin: string): Registered {
       composerListeners: [],
       activityListeners: [],
       varListeners: [],
+      projectMovedListeners: [],
       swarmListeners: [],
       quotaListeners: [],
       swarmStreamListeners: [],
@@ -1973,9 +2219,11 @@ function floatConfig(o: FloatOptions = {}): FloatConfig {
     border: o.border ?? "rounded",
     border_hl: o.borderHl ?? null,
     title: o.title ?? null,
+    footer: o.footer ?? null,
     close_on_blur: o.closeOnBlur ?? false,
     focusable: o.focusable ?? true,
     modal: o.modal ?? false,
+    scroll: o.scroll ?? false,
   };
 }
 
@@ -2134,6 +2382,11 @@ function build(
         return listener(r.varListeners, cb);
       },
     },
+    project: {
+      onMove(cb) {
+        return listener(r.projectMovedListeners, cb);
+      },
+    },
     ext: {
       async contribute(point, id, item, opts) {
         await c({ call: "ext_contribute", point, id, item, priority: opts?.priority ?? 0 });
@@ -2225,7 +2478,16 @@ function build(
     },
     update: {
       async check(force) {
-        return expect(await c({ call: "update_check", force: force ?? false }), "update").update;
+        return expect(
+          await c({ call: "update_check", force: force ?? false, local: false }),
+          "update",
+        ).update;
+      },
+      async local() {
+        return expect(
+          await c({ call: "update_check", force: false, local: true }),
+          "update",
+        ).update;
       },
       async apply() {
         return expect(await c({ call: "update_apply" }), "update_applied").outcome;
@@ -2448,10 +2710,14 @@ function build(
             view: opts?.view,
             title: opts?.title,
             activate: opts?.activate ?? true,
+            group: opts?.group,
           }),
           "tab",
         ).tab;
       },
+      async group(tab, group) {
+        await c({ call: "tab_group", tab, group });
+      },
       async close(tab) {
         await c({ call: "tab_close", tab });
       },
@@ -2499,6 +2765,9 @@ function build(
       async scrollTo(win, topLine) {
         await c({ call: "win_scroll_to", win, top_line: topLine });
       },
+      async scroll(win, amount) {
+        await c({ call: "win_scroll", win, amount });
+      },
       async viewport(win) {
         return expect(await c({ call: "win_get_viewport", win }), "viewport").viewport ?? null;
       },
@@ -2817,8 +3086,16 @@ function build(
           cwd: opts?.cwd ?? null,
         });
       },
+      async fetch(opts) {
+        const v = await c({ call: "git_fetch", cwd: opts?.cwd ?? null });
+        return expect(v, "status").status;
+      },
+      async pulls(opts) {
+        const v = await c({ call: "forge_pulls", cwd: opts?.cwd ?? null });
+        return expect(v, "pulls").pulls;
+      },
       async pull(opts) {
-        const v = await c({ call: "git_pull", cwd: opts?.cwd ?? null });
+        const v = await c({ call: "git_pull", cwd: opts?.cwd ?? null, rebase: opts?.rebase ?? false });
         return expect(v, "text").text;
       },
       async removeWorktree(path, opts) {
@@ -2829,6 +3106,13 @@ function build(
           cwd: opts?.cwd ?? null,
         });
       },
+      async moveWorktree(path, dest, opts) {
+        await c({ call: "git_move_worktree", path, dest, cwd: opts?.cwd ?? null });
+      },
+      async clone(url, path) {
+        const v = await c({ call: "git_clone", url, path });
+        return expect(v, "text").text;
+      },
     },
     gen: {
       async complete(prompt, opts) {
@@ -2851,6 +3135,23 @@ function build(
         });
         return expect(v, "json").value as never;
       },
+      async field(prompt, key, opts) {
+        const v = await c({
+          call: "gen_complete",
+          prompt,
+          system: opts?.system ?? null,
+          json: true,
+          field: key,
+          selection: opts?.selection ?? null,
+        });
+        const value = (expect(v, "json").value as Record<string, unknown>)?.[key];
+        // A key that came back as something other than a non-empty string is an answer to a
+        // different question, and the caller is about to name a branch after it.
+        if (typeof value !== "string" || value.trim() === "") {
+          throw new Error(`the model returned no ${key}`);
+        }
+        return value.trim();
+      },
     },
     view: {
       async list() {
@@ -3166,6 +3467,9 @@ async function dispatchEvent(
         for (const cb of r.varListeners)
           cb({ scope: ev.scope, key: ev.key, value: ev.value });
         break;
+      case "project_moved":
+        for (const cb of r.projectMovedListeners) cb({ from: ev.from, to: ev.to });
+        break;
       case "quota":
         for (const cb of [...r.quotaListeners]) cb(ev.snapshot);
         break;