@neosh/api 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neosh/api",
-  "version": "0.4.1",
+  "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

@@ -141,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 }
@@ -639,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/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;
 };

package/src/index.ts

@@ -662,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>;
@@ -1791,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.
    *
@@ -2425,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;
@@ -2648,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 });
       },