@nikcli-ai/plugin 1.340.0 → 1.348.0

package/dist/tui.d.ts

@@ -85,8 +85,10 @@ export type TuiKeybindSet = {
     match: (name: string, evt: ParsedKey) => boolean;
     print: (name: string) => string;
 };
+/** Mirrors the host's `DialogSize` in `@nikcli-ai/tui/ui/dialog`. */
+export type TuiDialogSize = "small" | "medium" | "large" | "xlarge" | "full";
 export type TuiDialogProps = {
-    size?: "medium" | "large" | "xlarge" | "full";
+    size?: TuiDialogSize;
     onClose: () => void;
     children?: JSX.Element;
 };
@@ -123,8 +125,8 @@ export type TuiTabsApi = {
 export type TuiDialogStack = {
     replace: (render: () => JSX.Element, onClose?: () => void) => void;
     clear: () => void;
-    setSize: (size: "medium" | "large" | "xlarge" | "full") => void;
-    readonly size: "medium" | "large" | "xlarge" | "full";
+    setSize: (size: TuiDialogSize) => void;
+    readonly size: TuiDialogSize;
     readonly depth: number;
     readonly open: boolean;
 };

package/dist/v2/manifest.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The v2 plugin manifest: what a plugin is, what it may do, and what host it
+ * needs.
+ *
+ * `specs/effect-tui/14-plugin-v2-architecture.md` requirements 2, 6 and 11. The
+ * manifest is also the **discriminator**: a module carrying one is a v2 plugin,
+ * a module without one is not. That is why it lives in the contract package
+ * rather than in a runtime — both the TUI runtime and the server-side loader
+ * have to agree on the shape without importing each other.
+ *
+ * Declaring a capability does not grant it. The host decides what it can
+ * supply; the manifest only says what the plugin will ask for. A plugin that
+ * calls a capability it did not declare fails with `CapabilityDenied` rather
+ * than silently receiving a stub — a stub would make the plugin look like it
+ * worked.
+ */
+import { Schema } from "effect";
+/**
+ * What a plugin may reach for.
+ *
+ * The TUI runtime can supply `routes`, `storage` and `http` today. The rest are
+ * declared here because the manifest is the stable contract: a plugin written
+ * against a future host should not need a new manifest version to say what it
+ * wants, and a host that cannot supply a capability refuses at load rather than
+ * failing at the first call.
+ */
+export declare const Capability: Schema.Literals<readonly ["tools", "commands", "routes", "keymap", "scheduler", "storage", "http"]>;
+export type Capability = typeof Capability.Type;
+/**
+ * Where a plugin came from.
+ *
+ * `remote-disabled` is a real state, not a placeholder: remote loading is out
+ * of scope for v2, so a manifest that claims it is accepted and refused, which
+ * is more useful than an unknown-kind error.
+ */
+export declare const Kind: Schema.Literals<readonly ["internal", "user", "remote-disabled"]>;
+export type Kind = typeof Kind.Type;
+/** Semver ranges the host must satisfy. An absent field is "no requirement". */
+export declare const HostRequirements: Schema.Struct<{
+    readonly nikcli: Schema.optional<Schema.String>;
+    readonly effect: Schema.optional<Schema.String>;
+    readonly opentui: Schema.optional<Schema.String>;
+    readonly node: Schema.optional<Schema.String>;
+}>;
+export type HostRequirements = typeof HostRequirements.Type;
+/**
+ * What the plugin intends to touch outside its own process state.
+ *
+ * Recorded, not yet enforced — enforcement is EOT-17's permission evaluator,
+ * and wiring it here before that exists would mean two evaluators. Present in
+ * the manifest now so a plugin does not have to change its manifest to become
+ * enforceable later.
+ */
+export declare const Permissions: Schema.Struct<{
+    readonly filesystem: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly network: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly command: Schema.optional<Schema.$Array<Schema.String>>;
+}>;
+export type Permissions = typeof Permissions.Type;
+export declare const ManifestSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly version: Schema.String;
+    readonly kind: Schema.Literals<readonly ["internal", "user", "remote-disabled"]>;
+    readonly capabilities: Schema.$Array<Schema.Literals<readonly ["tools", "commands", "routes", "keymap", "scheduler", "storage", "http"]>>;
+    readonly hostRequirements: Schema.optional<Schema.Struct<{
+        readonly nikcli: Schema.optional<Schema.String>;
+        readonly effect: Schema.optional<Schema.String>;
+        readonly opentui: Schema.optional<Schema.String>;
+        readonly node: Schema.optional<Schema.String>;
+    }>>;
+    readonly permissions: Schema.optional<Schema.Struct<{
+        readonly filesystem: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly network: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly command: Schema.optional<Schema.$Array<Schema.String>>;
+    }>>;
+}>;
+export type Manifest = typeof ManifestSchema.Type;
+declare const ManifestInvalid_base: Schema.Class<ManifestInvalid, Schema.TaggedStruct<"PluginV2ManifestInvalid", {
+    readonly spec: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Each error renders its own `message`.
+ *
+ * `Schema.TaggedError` carries the structured fields but leaves `message`
+ * empty, and these surface through a plugin loader whose output a human reads
+ * in a terminal. An empty message there is a loader that says a plugin failed
+ * and not why.
+ */
+export declare class ManifestInvalid extends ManifestInvalid_base {
+    get message(): string;
+}
+declare const Incompatible_base: Schema.Class<Incompatible, Schema.TaggedStruct<"PluginV2Incompatible", {
+    readonly pluginID: Schema.String;
+    readonly requirement: Schema.String;
+    readonly required: Schema.String;
+    readonly actual: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class Incompatible extends Incompatible_base {
+    get message(): string;
+}
+declare const CapabilityDenied_base: Schema.Class<CapabilityDenied, Schema.TaggedStruct<"PluginV2CapabilityDenied", {
+    readonly pluginID: Schema.String;
+    readonly capability: Schema.Literals<readonly ["tools", "commands", "routes", "keymap", "scheduler", "storage", "http"]>;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class CapabilityDenied extends CapabilityDenied_base {
+    get message(): string;
+}
+/**
+ * Validate a candidate manifest.
+ *
+ * Throws `ManifestInvalid` rather than returning an option: a malformed
+ * manifest is a load failure the operator has to see, and the alternative —
+ * treating it as "not a v2 plugin" — would silently fall back to the v1 path
+ * and report a confusing shape error from there instead.
+ */
+export declare function parseManifest(value: unknown, spec: string): Manifest;
+/** Whether a module looks like a v2 plugin. Requirement 11's discriminator. */
+export declare function hasManifest(value: unknown): boolean;
+export {};

package/dist/v2/manifest.js

@@ -0,0 +1,168 @@
+/**
+ * The v2 plugin manifest: what a plugin is, what it may do, and what host it
+ * needs.
+ *
+ * `specs/effect-tui/14-plugin-v2-architecture.md` requirements 2, 6 and 11. The
+ * manifest is also the **discriminator**: a module carrying one is a v2 plugin,
+ * a module without one is not. That is why it lives in the contract package
+ * rather than in a runtime — both the TUI runtime and the server-side loader
+ * have to agree on the shape without importing each other.
+ *
+ * Declaring a capability does not grant it. The host decides what it can
+ * supply; the manifest only says what the plugin will ask for. A plugin that
+ * calls a capability it did not declare fails with `CapabilityDenied` rather
+ * than silently receiving a stub — a stub would make the plugin look like it
+ * worked.
+ */
+import { Schema } from "effect";
+/**
+ * What a plugin may reach for.
+ *
+ * The TUI runtime can supply `routes`, `storage` and `http` today. The rest are
+ * declared here because the manifest is the stable contract: a plugin written
+ * against a future host should not need a new manifest version to say what it
+ * wants, and a host that cannot supply a capability refuses at load rather than
+ * failing at the first call.
+ */
+export const Capability = Schema.Literals(["tools", "commands", "routes", "keymap", "scheduler", "storage", "http"]);
+/**
+ * Where a plugin came from.
+ *
+ * `remote-disabled` is a real state, not a placeholder: remote loading is out
+ * of scope for v2, so a manifest that claims it is accepted and refused, which
+ * is more useful than an unknown-kind error.
+ */
+export const Kind = Schema.Literals(["internal", "user", "remote-disabled"]);
+/** Semver ranges the host must satisfy. An absent field is "no requirement". */
+export const HostRequirements = Schema.Struct({
+    nikcli: Schema.optional(Schema.String),
+    effect: Schema.optional(Schema.String),
+    opentui: Schema.optional(Schema.String),
+    node: Schema.optional(Schema.String),
+});
+/**
+ * What the plugin intends to touch outside its own process state.
+ *
+ * Recorded, not yet enforced — enforcement is EOT-17's permission evaluator,
+ * and wiring it here before that exists would mean two evaluators. Present in
+ * the manifest now so a plugin does not have to change its manifest to become
+ * enforceable later.
+ */
+export const Permissions = Schema.Struct({
+    filesystem: Schema.optional(Schema.Array(Schema.String)),
+    network: Schema.optional(Schema.Array(Schema.String)),
+    command: Schema.optional(Schema.Array(Schema.String)),
+});
+/**
+ * Plugin ids are scoped — `org:plugin` — so two authors can ship a `git`
+ * plugin. The scope is also what namespaces route names, slot ids and storage
+ * keys, which is why the separator is fixed rather than a convention.
+ */
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9._-]*$/;
+export const ManifestSchema = Schema.Struct({
+    id: Schema.String,
+    version: Schema.String,
+    kind: Kind,
+    capabilities: Schema.Array(Capability),
+    hostRequirements: Schema.optional(HostRequirements),
+    permissions: Schema.optional(Permissions),
+}).annotate({ identifier: "PluginV2Manifest" });
+/**
+ * Each error renders its own `message`.
+ *
+ * `Schema.TaggedError` carries the structured fields but leaves `message`
+ * empty, and these surface through a plugin loader whose output a human reads
+ * in a terminal. An empty message there is a loader that says a plugin failed
+ * and not why.
+ */
+export class ManifestInvalid extends Schema.TaggedError()("PluginV2ManifestInvalid", {
+    spec: Schema.String,
+    reason: Schema.String,
+}) {
+    get message() {
+        return `Invalid v2 plugin manifest in ${this.spec}: ${this.reason}`;
+    }
+}
+export class Incompatible extends Schema.TaggedError()("PluginV2Incompatible", {
+    pluginID: Schema.String,
+    requirement: Schema.String,
+    required: Schema.String,
+    actual: Schema.String,
+}) {
+    get message() {
+        return `Plugin ${this.pluginID} requires ${this.requirement} ${this.required} but the host is ${this.actual}`;
+    }
+}
+export class CapabilityDenied extends Schema.TaggedError()("PluginV2CapabilityDenied", {
+    pluginID: Schema.String,
+    capability: Capability,
+    reason: Schema.String,
+}) {
+    get message() {
+        return `Plugin ${this.pluginID} was denied capability "${this.capability}": ${this.reason}`;
+    }
+}
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * Validate a candidate manifest.
+ *
+ * Throws `ManifestInvalid` rather than returning an option: a malformed
+ * manifest is a load failure the operator has to see, and the alternative —
+ * treating it as "not a v2 plugin" — would silently fall back to the v1 path
+ * and report a confusing shape error from there instead.
+ */
+export function parseManifest(value, spec) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ManifestInvalid({ spec, reason: "manifest must be an object" });
+    }
+    const raw = value;
+    if (typeof raw.id !== "string" || !ID_PATTERN.test(raw.id)) {
+        throw new ManifestInvalid({
+            spec,
+            reason: `manifest.id must be a scoped lowercase id like "org:plugin", got ${JSON.stringify(raw.id)}`,
+        });
+    }
+    if (typeof raw.version !== "string" || !SEMVER_PATTERN.test(raw.version)) {
+        throw new ManifestInvalid({
+            spec,
+            reason: `manifest.version must be semver, got ${JSON.stringify(raw.version)}`,
+        });
+    }
+    if (raw.kind !== "internal" && raw.kind !== "user" && raw.kind !== "remote-disabled") {
+        throw new ManifestInvalid({
+            spec,
+            reason: `manifest.kind must be "internal", "user" or "remote-disabled", got ${JSON.stringify(raw.kind)}`,
+        });
+    }
+    if (!Array.isArray(raw.capabilities)) {
+        throw new ManifestInvalid({ spec, reason: "manifest.capabilities must be an array" });
+    }
+    const allowed = new Set(Capability.literals);
+    for (const capability of raw.capabilities) {
+        if (typeof capability !== "string" || !allowed.has(capability)) {
+            throw new ManifestInvalid({
+                spec,
+                reason: `unknown capability ${JSON.stringify(capability)}; expected one of ${Capability.literals.join(", ")}`,
+            });
+        }
+    }
+    // An empty module is a compatibility failure per requirement 1, and a plugin
+    // that asks for nothing is the same thing one step earlier: it cannot do
+    // anything the host would notice, so loading it only produces a lifetime to
+    // manage.
+    if (raw.capabilities.length === 0) {
+        throw new ManifestInvalid({ spec, reason: "manifest.capabilities must declare at least one capability" });
+    }
+    return {
+        id: raw.id,
+        version: raw.version,
+        kind: raw.kind,
+        capabilities: raw.capabilities,
+        hostRequirements: (raw.hostRequirements ?? undefined),
+        permissions: (raw.permissions ?? undefined),
+    };
+}
+/** Whether a module looks like a v2 plugin. Requirement 11's discriminator. */
+export function hasManifest(value) {
+    return typeof value === "object" && value !== null && "manifest" in value;
+}

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

@@ -1,7 +1,19 @@
+import type { Capability, Kind, Manifest, Permissions } from "../manifest.js";
 import type { Context } from "./context.js";
-export type { Context };
+export type { Capability, Context, Kind, Manifest, Permissions };
 export type Cleanup = () => Promise<void> | void;
 export interface Definition {
+    /**
+     * Present on a v2 plugin that declares itself
+     * (`specs/effect-tui/14-plugin-v2-architecture.md` requirement 2).
+     *
+     * Optional in the type, not in intent: the v2 shape shipped before the
+     * manifest did and every internal plugin is still written that way. A
+     * definition without one keeps the whole context surface and its own id —
+     * gating it by default, or renaming it for diagnostics, would change the
+     * identity the runtime keys slots, routes and enable state on.
+     */
+    readonly manifest?: Manifest;
     readonly id: string;
     readonly setup: (context: Context) => Promise<Cleanup | void> | Cleanup | void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@nikcli-ai/plugin",
-  "version": "1.340.0",
+  "version": "1.348.0",
   "type": "module",
   "license": "MIT",
   "scripts": {
@@ -27,6 +27,10 @@
       "import": "./src/v2/tui/index.ts",
       "types": "./src/v2/tui/index.ts"
     },
+    "./v2/manifest": {
+      "import": "./src/v2/manifest.ts",
+      "types": "./src/v2/manifest.ts"
+    },
     "./v2/tui/*": {
       "import": "./src/v2/tui/*.ts",
       "types": "./src/v2/tui/*.ts"
@@ -65,9 +69,9 @@
     }
   },
   "dependencies": {
-    "@nikcli-ai/sdk": "1.340.0",
-    "@opentui/core": "0.5.10",
-    "@opentui/solid": "0.5.10",
+    "@nikcli-ai/sdk": "1.348.0",
+    "@opentui/core": "0.5.11",
+    "@opentui/solid": "0.5.11",
     "effect": "4.0.0-rc.112",
     "solid-js": "1.9.12",
     "zod": "4.1.8"