@nikcli-ai/plugin 1.364.0 → 1.368.0

package/dist/v2/ade/context.d.ts

@@ -0,0 +1,165 @@
+/**
+ * What a v2 plugin is handed when it runs inside ADE.
+ *
+ * Why this is a second context and not `v2/tui/context.ts`
+ * -------------------------------------------------------
+ * The two halves of the v2 contract that are genuinely portable — `define`,
+ * the `Cleanup` protocol, the shape of `Storage` — are mirrored here on
+ * purpose. Everything else in the TUI context is terminal-shaped in ways that
+ * do not survive the move:
+ *
+ *  - Its `JSX` comes from `@opentui/solid`. That is the *terminal* renderer's
+ *    element type: a `<box>` is not a `<div>`, and the two namespaces are not
+ *    assignable. A plugin written against the TUI context and mounted in ADE
+ *    would typecheck and then render nothing. Getting this wrong is silent, so
+ *    the type has to say which surface it is for.
+ *  - Its `Data` is the nikcli HTTP client's world — messages, parts, permission
+ *    requests, MCP servers, providers. ADE has no SDK client wired up at all;
+ *    it drives agent CLIs through a pty and knows about a project and a list of
+ *    panes. Handing a plugin a `Data` whose every method returns `undefined`
+ *    here would be worse than not offering it.
+ *  - Its `UI` is a router plus named string slots. ADE has no router: a pane is
+ *    a tile in a grid, several of the same kind can be open at once, and each
+ *    one is closed individually. `navigate` has no meaning when the answer to
+ *    "where am I" is "in six places".
+ *
+ * The mapping the ADE adapter implements, stated once so nobody has to infer
+ * it from the code: a TUI **page** is an ADE **pane**, a TUI **slot** is an ADE
+ * **sidebar section**. Commands are new — the TUI reserves them for v1
+ * plugins, but the palette is how ADE is driven, so a v2 plugin that cannot put
+ * anything in it is a plugin nobody can reach.
+ */
+import type { JSX } from "solid-js";
+import type { Store } from "solid-js/store";
+export type SessionStatus = "idle" | "provisioning" | "working" | "waiting" | "done" | "error";
+export interface ProjectInfo {
+    readonly name: string;
+    readonly root: string;
+    readonly branch?: string;
+}
+export interface SessionInfo {
+    readonly id: string;
+    readonly title: string;
+    readonly status: SessionStatus;
+    /** The agent CLI behind this session, when it was started from the catalogue. */
+    readonly agent?: string;
+    readonly model: string;
+    readonly cwd?: string;
+    /** The project this session is filed under, by name. */
+    readonly projectName: string;
+}
+/**
+ * ADE's live state, read-only.
+ *
+ * Every accessor is a function rather than a value because these are read from
+ * Solid signals: called inside a reactive scope they subscribe, called outside
+ * they are a snapshot. Returning the value would freeze a plugin's view of the
+ * workbench at setup time.
+ */
+export interface Data {
+    /** The project currently open, or `undefined` in the browser harness. */
+    project(): ProjectInfo | undefined;
+    readonly session: {
+        /** Every session ADE knows about, across projects. */
+        list(): SessionInfo[];
+        get(id: string): SessionInfo | undefined;
+        /** The pane the user is in, when it holds a session. */
+        focused(): SessionInfo | undefined;
+    };
+}
+export interface CommandDefinition {
+    /**
+     * Unique within the plugin. The host namespaces it before it reaches the
+     * palette, so a plugin cannot claim `pane.close` — see the adapter.
+     */
+    readonly id: string;
+    /** Shown in the palette. Italian, like the rest of ADE's chrome. */
+    readonly title: string;
+    /** The palette section to file it under. Defaults to the plugin's own id. */
+    readonly group?: string;
+    /** Searchable synonyms that are not in the title. */
+    readonly keywords?: readonly string[];
+    readonly run: () => Promise<void> | void;
+}
+/** A pane a plugin can open in the grid. The ADE analogue of a TUI page. */
+export interface PaneDefinition {
+    /** Unique within the plugin; identifies the kind, not one open instance. */
+    readonly name: string;
+    /** The pane's header. Defaults to `name`. */
+    readonly title?: string;
+    readonly render: (input: {
+        readonly data?: Record<string, unknown>;
+    }) => JSX.Element;
+}
+/** A sidebar section. The ADE analogue of a TUI slot. */
+export type SectionRender = (props: Record<string, unknown>) => JSX.Element;
+export interface SectionDefinition {
+    /** Unique within the plugin. Reaches the DOM, so the host validates it. */
+    readonly name: string;
+    /** The section header. Defaults to `name`. */
+    readonly title?: string;
+    readonly render: SectionRender;
+}
+/** An open instance of a plugin pane, as the plugin sees it. */
+export interface OpenPane {
+    /** The workbench pane id. What `close` takes. */
+    readonly id: string;
+    readonly name: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface UI {
+    readonly command: {
+        register(command: CommandDefinition): () => void;
+        /** Runs one of this plugin's own commands by its unqualified id. */
+        run(id: string): void;
+        /** Opens the palette, as Ctrl+Shift+P does. */
+        palette(): void;
+    };
+    readonly pane: {
+        register(pane: PaneDefinition): () => void;
+        /**
+         * Opens a tile for a registered pane and returns its workbench id.
+         *
+         * Returns `undefined` when the name is not registered, rather than
+         * throwing: opening is usually a reaction to a click, and a plugin
+         * mid-teardown should not take the surface down with it.
+         */
+        open(input: {
+            readonly name: string;
+            readonly data?: Record<string, unknown>;
+        }): string | undefined;
+        close(paneId: string): void;
+        /** This plugin's open tiles. Reactive, like everything on `data`. */
+        list(): OpenPane[];
+    };
+    readonly section: {
+        register(section: SectionDefinition): () => void;
+    };
+}
+/**
+ * Durable and ephemeral plugin state.
+ *
+ * Structurally the same as the TUI's `Storage` and deliberately so — a plugin
+ * that only keeps state should port between the two surfaces unchanged. It is
+ * restated rather than imported because importing the TUI context would drag
+ * `@opentui/*` into a webview build that has no terminal in it.
+ *
+ * The backing differs: ADE persists to `localStorage`, which is per-window and
+ * per-origin. So "survives a restart" holds, "stays in sync across running
+ * instances" does not — there is one ADE window.
+ */
+export interface Storage {
+    store<Value extends object>(key: string, options: {
+        readonly initial: Value;
+    }): readonly [Store<Value>, (mutation: (draft: Value) => void) => Promise<void>];
+    /** In-memory only. Survives a plugin reload, gone when the window closes. */
+    memory<Value extends object>(key: string, options: {
+        readonly initial: Value;
+    }): readonly [Store<Value>, (mutation: (draft: Value) => void) => void];
+}
+export interface Context {
+    readonly options: Readonly<Record<string, unknown>>;
+    readonly data: Data;
+    readonly storage: Storage;
+    readonly ui: UI;
+}

package/dist/v2/ade/index.d.ts

@@ -0,0 +1 @@
+export * as Plugin from "./plugin.js";

package/dist/v2/ade/index.js

@@ -0,0 +1 @@
+export * as Plugin from "./plugin.js";

package/dist/v2/ade/plugin.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from "./context.js";
+export type { Context };
+export type Cleanup = () => Promise<void> | void;
+/**
+ * Identical in shape to `v2/tui/plugin.ts`, and that is the point: the entry
+ * form a plugin author writes does not change between surfaces, only the
+ * context they are handed does. A module can export both by re-reading
+ * `context.ui` — what it cannot do is assume which one it got.
+ */
+export interface Definition {
+    readonly id: string;
+    readonly setup: (context: Context) => Promise<Cleanup | void> | Cleanup | void;
+}
+export declare function define(plugin: Definition): Definition;

package/dist/v2/ade/plugin.js

@@ -0,0 +1,3 @@
+export function define(plugin) {
+    return plugin;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@nikcli-ai/plugin",
-  "version": "1.364.0",
+  "version": "1.368.0",
   "type": "module",
   "license": "MIT",
   "scripts": {
@@ -35,6 +35,14 @@
       "import": "./src/v2/tui/*.ts",
       "types": "./src/v2/tui/*.ts"
     },
+    "./v2/ade": {
+      "import": "./src/v2/ade/index.ts",
+      "types": "./src/v2/ade/index.ts"
+    },
+    "./v2/ade/*": {
+      "import": "./src/v2/ade/*.ts",
+      "types": "./src/v2/ade/*.ts"
+    },
     "./v2/effect": {
       "import": "./src/v2/effect/index.ts",
       "types": "./src/v2/effect/index.ts"
@@ -62,6 +70,8 @@
       "./tui": "./dist/tui.js",
       "./v2/tui": "./dist/v2/tui/index.js",
       "./v2/tui/*": "./dist/v2/tui/*.js",
+      "./v2/ade": "./dist/v2/ade/index.js",
+      "./v2/ade/*": "./dist/v2/ade/*.js",
       "./v2/effect": "./dist/v2/effect/index.js",
       "./v2/effect/tool": "./dist/v2/effect/tool.js",
       "./v2/promise": "./dist/v2/promise/index.js",
@@ -69,7 +79,7 @@
     }
   },
   "dependencies": {
-    "@nikcli-ai/sdk": "1.364.0",
+    "@nikcli-ai/sdk": "1.368.0",
     "@opentui/core": "0.5.11",
     "@opentui/solid": "0.5.11",
     "effect": "4.0.0-rc.112",