@ryuhq/sdk 0.1.13 → 0.2.0

package/dist/builder.d.cts

@@ -0,0 +1,212 @@
+import { RunnableMeta, Surface, PluginManifest, CompanionSurface } from './manifest.cjs';
+import { A as AppToolSpec } from './app-DNaGmLVf.cjs';
+import 'zod';
+
+/**
+ * Ryu SDK typed builders — one builder per RunnableKind plus a PluginBuilder that
+ * assembles a complete, validated `manifest.json` manifest.
+ *
+ * Each builder follows a fluent interface: construct, chain setter calls, then
+ * call `.build()` to get a validated result. Invalid manifests throw a
+ * descriptive `Error` — never a silent fallback.
+ *
+ * Engine/model fields are typed as `string` throughout.  No provider union is
+ * used so adding a new provider never requires an SDK change.
+ */
+
+/** Base builder shared by all Runnable kinds. */
+declare class RunnableBuilder {
+    protected _id: string;
+    protected _name: string;
+    id(value: string): this;
+    name(value: string): this;
+}
+/** Builds an Agent `RunnableMeta` entry. */
+declare class AgentBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Workflow `RunnableMeta` entry. */
+declare class WorkflowBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Tool `RunnableMeta` entry. */
+declare class ToolBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Skill `RunnableMeta` entry. */
+declare class SkillBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Create an AgentBuilder. */
+declare const agent: () => AgentBuilder;
+/** Create a WorkflowBuilder. */
+declare const workflow: () => WorkflowBuilder;
+/** Create a ToolBuilder. */
+declare const tool: () => ToolBuilder;
+/** Create a SkillBuilder. */
+declare const skill: () => SkillBuilder;
+/**
+ * Fluent builder for a complete `manifest.json` Plugin manifest. Produces a
+ * validated `PluginManifest` on `.build()` or throws a descriptive `Error`
+ * naming the first invalid field.
+ *
+ * @example
+ * ```ts
+ * import { PluginBuilder, agent, tool } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = new PluginBuilder()
+ *   .id("com.example.my-plugin")
+ *   .name("My Plugin")
+ *   .version("1.0.0")
+ *   .runnable(agent().id("agent-main").name("Main Agent").build())
+ *   .runnable(tool().id("tool-search").name("Web Search").build())
+ *   .grant("mcp:web_search")
+ *   .companion({ label: "My Plugin", icon: "sparkles", shortcut: "ctrl+shift+m" })
+ *   .build()
+ * ```
+ */
+declare class PluginBuilder {
+    private _id;
+    private _name;
+    private _version;
+    private readonly _runnables;
+    private readonly _grants;
+    private _companion;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.my-app"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    name(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Append a pre-built `RunnableMeta` (from any per-kind builder). */
+    runnable(meta: RunnableMeta): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Set an optional Companion surface descriptor. */
+    companion(surface: CompanionSurface): this;
+    /**
+     * Declare a **plugin-to-plugin dependency**: `id` must be installed and is
+     * auto-enabled (in dependency order) before this plugin enables.
+     *
+     * `minVersion` is a MINIMUM — a bare `"1.2.0"` means `">=1.2.0"`, so an
+     * installed `2.0.0` satisfies it (comparator syntax like `">=1.2, <2"` is
+     * honoured verbatim).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /**
+     * Declare a permission grant implied by this plugin's dependencies
+     * (`requires.grants`). Declaration only — the Gateway remains the sole
+     * authority on what a grant allows. Use {@link PluginBuilder.grant} for the
+     * grants this plugin needs in its own right.
+     */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /**
+     * Restrict this plugin to a host surface (`"desktop"`, `"island"`, …).
+     * Declaring NO target is the default and means **every** surface.
+     */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` with
+     * the failing field name and message when validation fails.
+     */
+    build(): PluginManifest;
+}
+/**
+ * Fluent builder for a Ryu App — a `manifest.json` whose tools render interactive
+ * widgets inline in chat. Delegates to {@link defineApp} on `.build()`, so it
+ * derives the render-vs-companion split and validates through
+ * `PluginManifestSchema` (throwing a descriptive `Error` on bad input) exactly
+ * like the factory.
+ *
+ * @example
+ * ```ts
+ * import { app } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = app()
+ *   .id("com.example.checklist")
+ *   .title("Checklist")
+ *   .version("1.0.0")
+ *   .slug("checklist")
+ *   .uiEntry("src/checklist.tsx")
+ *   .tool({ name: "render", description: "Render a checklist", invoking: "Building…" })
+ *   .tool({ name: "toggle", description: "Toggle an item", accessible: true })
+ *   .build()
+ * ```
+ */
+declare class AppBuilder {
+    private _id;
+    private _title;
+    private _version;
+    private _slug;
+    private _server;
+    private _displayMode;
+    private _mime;
+    private _uiEntry;
+    private readonly _grants;
+    private readonly _activationEvents;
+    private readonly _tools;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    title(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Set the app slug (drives `ui://widget/<slug>.html` and the server default). */
+    slug(value: string): this;
+    /** Override the MCP server namespace for tool ids (defaults to the slug). */
+    server(value: string): this;
+    /** Set the default widget display mode (`inline` | `fullscreen` | `pip`). */
+    displayMode(value: string): this;
+    /** Override the widget MIME dialect (defaults to `text/html+skybridge`). */
+    mime(value: string): this;
+    /** Set the widget UI source entry `ryu pack` bundles into `ui_code`. */
+    uiEntry(value: string): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Add a VS-Code-style activation event (empty = eager `["*"]`). */
+    activationEvent(event: string): this;
+    /** Append a tool spec (render tool unless `accessible:true`). */
+    tool(spec: AppToolSpec): this;
+    /**
+     * Declare a **plugin-to-plugin dependency** (auto-enabled, in dependency order,
+     * before this app). `minVersion` is a MINIMUM (`"1.2.0"` = `">=1.2.0"`).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /** Declare a grant implied by this app's dependencies (`requires.grants`). */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /** Restrict this app to a host surface. No target = every surface. */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` naming
+     * the failing field when validation fails.
+     */
+    build(): PluginManifest;
+}
+/** Create an AppBuilder. */
+declare const app: () => AppBuilder;
+
+export { AgentBuilder, AppBuilder, PluginBuilder, SkillBuilder, ToolBuilder, WorkflowBuilder, agent, app, skill, tool, workflow };

package/dist/builder.d.ts

@@ -0,0 +1,212 @@
+import { RunnableMeta, Surface, PluginManifest, CompanionSurface } from './manifest.js';
+import { A as AppToolSpec } from './app-Bkw7LlCK.js';
+import 'zod';
+
+/**
+ * Ryu SDK typed builders — one builder per RunnableKind plus a PluginBuilder that
+ * assembles a complete, validated `manifest.json` manifest.
+ *
+ * Each builder follows a fluent interface: construct, chain setter calls, then
+ * call `.build()` to get a validated result. Invalid manifests throw a
+ * descriptive `Error` — never a silent fallback.
+ *
+ * Engine/model fields are typed as `string` throughout.  No provider union is
+ * used so adding a new provider never requires an SDK change.
+ */
+
+/** Base builder shared by all Runnable kinds. */
+declare class RunnableBuilder {
+    protected _id: string;
+    protected _name: string;
+    id(value: string): this;
+    name(value: string): this;
+}
+/** Builds an Agent `RunnableMeta` entry. */
+declare class AgentBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Workflow `RunnableMeta` entry. */
+declare class WorkflowBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Tool `RunnableMeta` entry. */
+declare class ToolBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Builds a Skill `RunnableMeta` entry. */
+declare class SkillBuilder extends RunnableBuilder {
+    build(): RunnableMeta;
+}
+/** Create an AgentBuilder. */
+declare const agent: () => AgentBuilder;
+/** Create a WorkflowBuilder. */
+declare const workflow: () => WorkflowBuilder;
+/** Create a ToolBuilder. */
+declare const tool: () => ToolBuilder;
+/** Create a SkillBuilder. */
+declare const skill: () => SkillBuilder;
+/**
+ * Fluent builder for a complete `manifest.json` Plugin manifest. Produces a
+ * validated `PluginManifest` on `.build()` or throws a descriptive `Error`
+ * naming the first invalid field.
+ *
+ * @example
+ * ```ts
+ * import { PluginBuilder, agent, tool } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = new PluginBuilder()
+ *   .id("com.example.my-plugin")
+ *   .name("My Plugin")
+ *   .version("1.0.0")
+ *   .runnable(agent().id("agent-main").name("Main Agent").build())
+ *   .runnable(tool().id("tool-search").name("Web Search").build())
+ *   .grant("mcp:web_search")
+ *   .companion({ label: "My Plugin", icon: "sparkles", shortcut: "ctrl+shift+m" })
+ *   .build()
+ * ```
+ */
+declare class PluginBuilder {
+    private _id;
+    private _name;
+    private _version;
+    private readonly _runnables;
+    private readonly _grants;
+    private _companion;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.my-app"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    name(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Append a pre-built `RunnableMeta` (from any per-kind builder). */
+    runnable(meta: RunnableMeta): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Set an optional Companion surface descriptor. */
+    companion(surface: CompanionSurface): this;
+    /**
+     * Declare a **plugin-to-plugin dependency**: `id` must be installed and is
+     * auto-enabled (in dependency order) before this plugin enables.
+     *
+     * `minVersion` is a MINIMUM — a bare `"1.2.0"` means `">=1.2.0"`, so an
+     * installed `2.0.0` satisfies it (comparator syntax like `">=1.2, <2"` is
+     * honoured verbatim).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /**
+     * Declare a permission grant implied by this plugin's dependencies
+     * (`requires.grants`). Declaration only — the Gateway remains the sole
+     * authority on what a grant allows. Use {@link PluginBuilder.grant} for the
+     * grants this plugin needs in its own right.
+     */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /**
+     * Restrict this plugin to a host surface (`"desktop"`, `"island"`, …).
+     * Declaring NO target is the default and means **every** surface.
+     */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` with
+     * the failing field name and message when validation fails.
+     */
+    build(): PluginManifest;
+}
+/**
+ * Fluent builder for a Ryu App — a `manifest.json` whose tools render interactive
+ * widgets inline in chat. Delegates to {@link defineApp} on `.build()`, so it
+ * derives the render-vs-companion split and validates through
+ * `PluginManifestSchema` (throwing a descriptive `Error` on bad input) exactly
+ * like the factory.
+ *
+ * @example
+ * ```ts
+ * import { app } from "@ryuhq/sdk/builder"
+ *
+ * const manifest = app()
+ *   .id("com.example.checklist")
+ *   .title("Checklist")
+ *   .version("1.0.0")
+ *   .slug("checklist")
+ *   .uiEntry("src/checklist.tsx")
+ *   .tool({ name: "render", description: "Render a checklist", invoking: "Building…" })
+ *   .tool({ name: "toggle", description: "Toggle an item", accessible: true })
+ *   .build()
+ * ```
+ */
+declare class AppBuilder {
+    private _id;
+    private _title;
+    private _version;
+    private _slug;
+    private _server;
+    private _displayMode;
+    private _mime;
+    private _uiEntry;
+    private readonly _grants;
+    private readonly _activationEvents;
+    private readonly _tools;
+    private readonly _dependencies;
+    private readonly _requiredCapabilities;
+    private readonly _requiredGrants;
+    private readonly _targets;
+    /** Set the reverse-domain app id (e.g. `"com.example.checklist"`). */
+    id(value: string): this;
+    /** Set the human-readable display name. */
+    title(value: string): this;
+    /** Set the semver version string (e.g. `"1.0.0"`). */
+    version(value: string): this;
+    /** Set the app slug (drives `ui://widget/<slug>.html` and the server default). */
+    slug(value: string): this;
+    /** Override the MCP server namespace for tool ids (defaults to the slug). */
+    server(value: string): this;
+    /** Set the default widget display mode (`inline` | `fullscreen` | `pip`). */
+    displayMode(value: string): this;
+    /** Override the widget MIME dialect (defaults to `text/html+skybridge`). */
+    mime(value: string): this;
+    /** Set the widget UI source entry `ryu pack` bundles into `ui_code`. */
+    uiEntry(value: string): this;
+    /** Declare a permission grant (e.g. `"mcp:web_search"`). */
+    grant(permission: string): this;
+    /** Add a VS-Code-style activation event (empty = eager `["*"]`). */
+    activationEvent(event: string): this;
+    /** Append a tool spec (render tool unless `accessible:true`). */
+    tool(spec: AppToolSpec): this;
+    /**
+     * Declare a **plugin-to-plugin dependency** (auto-enabled, in dependency order,
+     * before this app). `minVersion` is a MINIMUM (`"1.2.0"` = `">=1.2.0"`).
+     */
+    dependsOn(id: string, minVersion?: string): this;
+    /** Declare a grant implied by this app's dependencies (`requires.grants`). */
+    requiredGrant(permission: string): this;
+    /**
+     * Declare an abstract **capability** edge (`requires.capabilities`) the broker
+     * resolves to a bound provider at enable time — e.g. `requiresCapability("rag")`.
+     * Distinct from a specific-plugin dependency: a capability edge lets the
+     * binding registry choose the provider. `minVersion` is a MINIMUM (`"1.2.0"`
+     * = `">=1.2.0"`).
+     */
+    requiresCapability(capability: string, minVersion?: string): this;
+    /** Restrict this app to a host surface. No target = every surface. */
+    target(surface: Surface): this;
+    /**
+     * Validate and return the assembled `PluginManifest`. Throws an `Error` naming
+     * the failing field when validation fails.
+     */
+    build(): PluginManifest;
+}
+/** Create an AppBuilder. */
+declare const app: () => AppBuilder;
+
+export { AgentBuilder, AppBuilder, PluginBuilder, SkillBuilder, ToolBuilder, WorkflowBuilder, agent, app, skill, tool, workflow };

package/dist/builder.js

@@ -0,0 +1,28 @@
+import {
+  AgentBuilder,
+  AppBuilder,
+  PluginBuilder,
+  SkillBuilder,
+  ToolBuilder,
+  WorkflowBuilder,
+  agent,
+  app,
+  skill,
+  tool,
+  workflow
+} from "./chunk-IOLP5FFE.js";
+import "./chunk-W3KPP4WN.js";
+import "./chunk-IEUQ3CDG.js";
+export {
+  AgentBuilder,
+  AppBuilder,
+  PluginBuilder,
+  SkillBuilder,
+  ToolBuilder,
+  WorkflowBuilder,
+  agent,
+  app,
+  skill,
+  tool,
+  workflow
+};