@ryuhq/sdk 0.0.5

package/dist/cli.cjs

@@ -0,0 +1,858 @@
+#!/usr/bin/env bun
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/cli/dev.ts
+var import_node_readline = require("readline");
+
+// src/model/client.ts
+var native = __toESM(require("@ryuhq/sdk-native"), 1);
+var ModelClient2 = class {
+  model;
+  baseUrl;
+  native;
+  constructor(model, options = {}) {
+    this.native = new native.ModelClient(
+      model,
+      options.baseUrl ?? null,
+      options.token ?? null
+    );
+    this.model = model;
+    this.baseUrl = options.baseUrl ?? native.resolveGatewayUrl();
+  }
+  /** Send a non-streaming chat completion request to the gateway. */
+  async chat(messages) {
+    const res = await this.native.chat(messages);
+    const usage = res.promptTokens === void 0 && res.completionTokens === void 0 && res.totalTokens === void 0 ? void 0 : {
+      promptTokens: res.promptTokens ?? 0,
+      completionTokens: res.completionTokens ?? 0,
+      totalTokens: res.totalTokens ?? 0
+    };
+    return {
+      content: res.content,
+      finishReason: res.finishReason ?? null,
+      usage
+    };
+  }
+  /** Send a streaming chat completion request, yielding deltas as they arrive. */
+  async *stream(messages) {
+    const queue = [];
+    let done = false;
+    let failure = null;
+    let wake = null;
+    const notify = () => {
+      if (wake) {
+        const w = wake;
+        wake = null;
+        w();
+      }
+    };
+    this.native.stream(messages, (err, delta) => {
+      if (err) {
+        failure = err;
+        done = true;
+      } else if (delta === null || delta === void 0) {
+        done = true;
+      } else {
+        queue.push({
+          content: delta.content ?? null,
+          finishReason: delta.finishReason ?? null
+        });
+      }
+      notify();
+    });
+    while (true) {
+      while (queue.length > 0) {
+        const next = queue.shift();
+        if (next) {
+          yield next;
+        }
+      }
+      if (failure) {
+        throw failure;
+      }
+      if (done) {
+        return;
+      }
+      await new Promise((resolve2) => {
+        wake = resolve2;
+      });
+    }
+  }
+};
+
+// src/model/gateway.ts
+var native2 = __toESM(require("@ryuhq/sdk-native"), 1);
+function resolveGatewayUrl3() {
+  return native2.resolveGatewayUrl();
+}
+
+// src/cli/dev.ts
+var RE_ABSOLUTE_PATH = /^[A-Za-z]:[\\/]/;
+async function probeGateway(baseUrl) {
+  try {
+    await fetch(`${baseUrl}/health`, {
+      method: "HEAD",
+      signal: AbortSignal.timeout(3e3)
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadRunnable(entryPath) {
+  const abs = entryPath.startsWith("/") || RE_ABSOLUTE_PATH.test(entryPath) ? entryPath : `${process.cwd()}/${entryPath}`;
+  const mod = await import(abs);
+  const candidate = mod.default ?? mod.runnable;
+  if (!candidate || typeof candidate.run !== "function") {
+    throw new Error(
+      `[ryu dev] Module at "${entryPath}" must export a Runnable as "default" or "runnable". A Runnable has a "run(messages, model)" generator method.`
+    );
+  }
+  return candidate;
+}
+var ANSI = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  cyan: "\x1B[36m",
+  yellow: "\x1B[33m",
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  dim: "\x1B[2m"
+};
+function printBanner(runnableName, gatewayUrl) {
+  process.stdout.write(
+    [
+      "",
+      `${ANSI.bold}${ANSI.cyan}ryu dev${ANSI.reset} \u2014 local Runnable playground`,
+      `${ANSI.dim}runnable : ${runnableName}${ANSI.reset}`,
+      `${ANSI.dim}gateway  : ${gatewayUrl}${ANSI.reset}`,
+      `${ANSI.dim}type "/quit" or Ctrl+C to exit${ANSI.reset}`,
+      ""
+    ].join("\n")
+  );
+}
+function printPrompt() {
+  process.stdout.write(`${ANSI.bold}> ${ANSI.reset}`);
+}
+function printAssistantStart() {
+  process.stdout.write(`
+${ANSI.green}assistant:${ANSI.reset} `);
+}
+function printAssistantEnd() {
+  process.stdout.write("\n");
+}
+function printToolCall(event) {
+  process.stdout.write(
+    `
+${ANSI.yellow}tool-call${ANSI.reset} [${event.id}] ${event.title} (${event.kind})`
+  );
+  if (event.input !== null && event.input !== void 0) {
+    process.stdout.write(
+      ` ${ANSI.dim}${JSON.stringify(event.input)}${ANSI.reset}`
+    );
+  }
+  process.stdout.write("\n");
+}
+function statusAnsiColor(status) {
+  if (status === "completed") {
+    return ANSI.green;
+  }
+  if (status === "failed") {
+    return ANSI.red;
+  }
+  return ANSI.dim;
+}
+function printToolResult(event) {
+  const statusColor = statusAnsiColor(event.status);
+  process.stdout.write(
+    `${ANSI.dim}tool-result${ANSI.reset} [${event.id}] ${statusColor}${event.status}${ANSI.reset}`
+  );
+  if (event.output !== null && event.output !== void 0) {
+    process.stdout.write(
+      ` ${ANSI.dim}${JSON.stringify(event.output)}${ANSI.reset}`
+    );
+  }
+  process.stdout.write("\n");
+}
+function printError(message) {
+  process.stderr.write(`
+${ANSI.red}error:${ANSI.reset} ${message}
+`);
+}
+async function runDevLoop(runnable, model) {
+  const history = [];
+  const rl = (0, import_node_readline.createInterface)({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false
+  });
+  const linePromise = () => new Promise((resolve2) => {
+    rl.once("line", resolve2);
+    rl.once("close", () => resolve2(null));
+  });
+  printPrompt();
+  while (true) {
+    const line = await linePromise();
+    if (line === null) {
+      process.stdout.write("\n");
+      break;
+    }
+    const trimmed = line.trim();
+    if (trimmed === "") {
+      printPrompt();
+      continue;
+    }
+    if (trimmed === "/quit" || trimmed === "/exit") {
+      process.stdout.write("bye\n");
+      break;
+    }
+    history.push({ role: "user", content: trimmed });
+    let assistantReply = "";
+    printAssistantStart();
+    const gen = runnable.run([...history], model);
+    for await (const event of gen) {
+      switch (event.type) {
+        case "text": {
+          process.stdout.write(event.content);
+          assistantReply += event.content;
+          break;
+        }
+        case "tool_call": {
+          printToolCall(event);
+          break;
+        }
+        case "tool_result": {
+          printToolResult(event);
+          break;
+        }
+        case "error": {
+          printAssistantEnd();
+          printError(event.message);
+          history.pop();
+          assistantReply = "";
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    printAssistantEnd();
+    if (assistantReply) {
+      history.push({ role: "assistant", content: assistantReply });
+    }
+    printPrompt();
+  }
+  rl.close();
+}
+async function commandDev(entryPath) {
+  const gatewayUrl = resolveGatewayUrl3();
+  process.stdout.write(`checking gateway at ${gatewayUrl} ...
+`);
+  const reachable = await probeGateway(gatewayUrl);
+  if (!reachable) {
+    process.stderr.write(
+      [
+        "",
+        `${ANSI.red}error:${ANSI.reset} gateway not reachable at ${gatewayUrl}`,
+        "",
+        "The ryu dev playground requires a running Ryu gateway.",
+        "Start the gateway with: ryu gateway start",
+        "Or set RYU_GATEWAY_URL to point at a remote gateway.",
+        "",
+        "No provider fallback is attempted. Fix the gateway connection and retry.",
+        ""
+      ].join("\n")
+    );
+    process.exit(1);
+  }
+  let runnable;
+  try {
+    runnable = await loadRunnable(entryPath);
+  } catch (err) {
+    process.stderr.write(`error: ${String(err)}
+`);
+    process.exit(1);
+  }
+  const model = new ModelClient2("default", { baseUrl: gatewayUrl });
+  printBanner(runnable.name, gatewayUrl);
+  await runDevLoop(runnable, model);
+}
+
+// src/manifest.ts
+var import_node_module = require("module");
+var import_zod = require("zod");
+var RunnableKindSchema = import_zod.z.enum([
+  "agent",
+  "workflow",
+  "tool",
+  "skill",
+  // A companion surface (in-desktop panel). Added so a packable plugin can
+  // declare a companion runnable that flows through Core's existing Companion
+  // handler → app_contrib → `GET /api/plugins/contributions` → the desktop
+  // `/plugin/<id>` route. Its `config.ui_entry` (see `CompanionRunnableConfigSchema`)
+  // is what `ryu pack` bundles into `ui_code`.
+  "companion"
+]);
+var RunnableMetaSchema = import_zod.z.object({
+  /** Stable unique identifier (e.g. `"agent-researcher"`). */
+  id: import_zod.z.string().min(1),
+  /** Human-readable display name. */
+  name: import_zod.z.string().min(1),
+  /** Which kind of runnable this entry describes. */
+  kind: RunnableKindSchema,
+  /**
+   * Optional per-kind config blob. Mirrors Core's `RunnableEntry.config`
+   * (`Option<serde_json::Value>`) so a manifest authored here round-trips
+   * through Core-strict validation. Left opaque (a record) at this authoring
+   * layer; the per-kind shape is enforced by Core's `validate_runnable`.
+   *
+   * For a `companion` runnable, `config.ui_entry` names the plugin's UI entry
+   * module (relative to the manifest dir). `ryu pack` bundles that entry into
+   * the emitted `ui_code`; Core's `CompanionConfig.ui_entry` is the lockstep
+   * field so a packed companion validates.
+   */
+  config: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
+});
+function labelImpersonatesSystemChrome(label) {
+  const lower = label.toLowerCase();
+  return lower.includes("ryu") || lower.includes("system");
+}
+var CompanionSurfaceSchema = import_zod.z.object({
+  /** Display label for the companion panel tab or tooltip. Anti-impersonation:
+   *  may not pose as first-party Ryu/system chrome (see
+   *  {@link labelImpersonatesSystemChrome}). */
+  label: import_zod.z.string().min(1).refine((value) => !labelImpersonatesSystemChrome(value), {
+    message: "companion label must not impersonate system chrome (must not contain 'ryu' or 'system')"
+  }),
+  /** Icon identifier resolved by the desktop shell. */
+  icon: import_zod.z.string().optional(),
+  /** Keyboard shortcut string (e.g. `"ctrl+shift+r"`). */
+  shortcut: import_zod.z.string().optional()
+});
+var TurnHookContributionSchema = import_zod.z.object({
+  /** Stable id for this hook (unique within the plugin). */
+  id: import_zod.z.string().min(1),
+  /** Turn boundary this fires on. Today only `"post_assistant_turn"`. */
+  on: import_zod.z.string().min(1).default("post_assistant_turn"),
+  /** The JS hook body executed in the sandbox (returns a directive). */
+  code: import_zod.z.string().min(1)
+});
+var DEFAULT_WIDGET_MIME = "text/html+skybridge";
+var DEFAULT_WIDGET_DISPLAY_MODE = "inline";
+var WidgetContributionSchema = import_zod.z.object({
+  /** The fully-qualified tool id whose result renders this widget. */
+  tool_id: import_zod.z.string().min(1),
+  /** `ui://widget/<slug>.html` — the widget resource uri. */
+  uri: import_zod.z.string().min(1),
+  /** Source entry (e.g. `src/apps/checklist/index.tsx`) for `ryu pack`. */
+  ui_entry: import_zod.z.string().optional(),
+  /** Widget MIME dialect (default `text/html+skybridge`). */
+  mime: import_zod.z.string().default(DEFAULT_WIDGET_MIME),
+  /** Default display mode (`inline` | `fullscreen` | `pip`). */
+  default_display_mode: import_zod.z.string().default(DEFAULT_WIDGET_DISPLAY_MODE)
+});
+var ToolAppConfigSchema = import_zod.z.object({
+  /** MCP tool slug this runnable wraps — the fully-qualified `<server>__<name>` id. */
+  slug: import_zod.z.string().min(1),
+  /** The tool description the model reads when choosing it. Carried here because a
+   *  packed app's manifest is the only channel (there is no `generated.rs`); Core's
+   *  app-tool synthesis reads it back onto the `RegistryTool`. */
+  description: import_zod.z.string(),
+  /** JSON Schema for the tool's arguments (used for validation + the LLM tool
+   *  surface). Snake_case to match `widget_accessible`. Absent = no arguments. */
+  input_schema: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  /** True when calling this tool renders the app's widget (carries the template). */
+  widget: import_zod.z.boolean().default(false),
+  /** True when a mounted widget may `callTool` this tool (a companion), or when a
+   *  render tool's widget may call any companion the app declares. */
+  widget_accessible: import_zod.z.boolean().default(false),
+  /** Optional status label shown while the render tool runs. */
+  invoking: import_zod.z.string().optional(),
+  /** Optional status label shown when the render tool finishes. */
+  invoked: import_zod.z.string().optional()
+});
+var ContributesSchema = import_zod.z.object({
+  turn_hooks: import_zod.z.array(TurnHookContributionSchema).default([]),
+  composer_controls: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
+  settings_tabs: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
+  slash_commands: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).default([]),
+  /** App widgets (Ryu Apps). Each binds a render tool id to its
+   *  `ui://widget/<slug>.html` template. Mirrors the Rust-side
+   *  `Contributes.widgets` field, without which the CLI's zod parse would strip
+   *  every widget an app authored here declares. */
+  widgets: import_zod.z.array(WidgetContributionSchema).default([])
+});
+var SetupStepSchema = import_zod.z.object({
+  /** Card heading (e.g. the companion app name). */
+  title: import_zod.z.string().optional(),
+  /** Instruction body shown under the title. */
+  description: import_zod.z.string().optional(),
+  /** Label for the optional action button. */
+  actionLabel: import_zod.z.string().optional(),
+  /** URL the action button opens (validated server-side on publish). */
+  actionUrl: import_zod.z.string().optional()
+});
+var AppDependencySchema = import_zod.z.object({
+  /** The `id` of the plugin this one depends on. */
+  id: import_zod.z.string().min(1, "dependency id is required"),
+  /** Optional MINIMUM version the dependency must satisfy (`"1.2.0"` = `">=1.2.0"`). */
+  min_version: import_zod.z.string().min(1).optional()
+});
+var CapabilityReqSchema = import_zod.z.object({
+  /** Capability name (e.g. `"rag"`, `"memory"`, `"tts"`). Matched against a
+   *  provider's `provides[].capability`. */
+  capability: import_zod.z.string().min(1, "capability name is required"),
+  /** Optional MINIMUM capability version the bound provider must satisfy
+   *  (`"1.2.0"` = `">=1.2.0"`). Absent = any version. */
+  min_version: import_zod.z.string().min(1).optional()
+});
+var RequiresSchema = import_zod.z.object({
+  /** Other plugins that must be installed + enabled before this one enables. */
+  apps: import_zod.z.array(AppDependencySchema).default([]),
+  /**
+   * Abstract capability edges the broker resolves to a bound provider at
+   * enable time. Mirrors `Requires::capabilities` in
+   * `crates/ryu-kernel-contracts` — an `apps` edge names a specific plugin; a
+   * `capabilities` edge names a capability and lets the binding registry choose
+   * the provider. Each is lowered to an app-id graph edge once bound, so the
+   * enable/disable/cycle machinery is shared. Empty for the common case.
+   */
+  capabilities: import_zod.z.array(CapabilityReqSchema).default([]),
+  /**
+   * Permission grants implied by the dependencies. Declaration only — the
+   * Gateway remains the sole authority on what a grant *allows*, and Core's
+   * dependency graph resolves `apps` only.
+   */
+  grants: import_zod.z.array(import_zod.z.string()).default([])
+});
+var SurfaceSchema = import_zod.z.enum([
+  /** The Ryu Gateway. */
+  "gateway",
+  /** A headless Core node (no UI). */
+  "core",
+  /** The Tauri desktop app. */
+  "desktop",
+  /** The Electron dynamic-island companion. */
+  "island",
+  /** The Expo/React-Native mobile app. */
+  "mobile",
+  /** The browser extension. */
+  "extension",
+  /** The Next.js web app. */
+  "web",
+  /** The terminal client. */
+  "cli"
+]);
+var PluginManifestSchema = import_zod.z.object({
+  /** Reverse-domain unique identifier (e.g. `"com.example.my-plugin"`). */
+  id: import_zod.z.string().min(1, "id is required"),
+  /** Human-readable display name shown in the plugin store / launcher. */
+  name: import_zod.z.string().min(1, "name is required"),
+  /**
+   * Semver version string (e.g. `"1.0.0"`). Core's loader rejects any manifest
+   * whose version is not valid semver; the regex here enforces the same rule at
+   * SDK-build time.
+   */
+  version: import_zod.z.string().regex(
+    /^\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/,
+    "version must be a valid semver string (e.g. 1.0.0)"
+  ),
+  /**
+   * Lower-case hex `sha256(utf8_bytes(ui_code))` binding the plugin's bundled
+   * sandboxed-UI code to this manifest. `ryu pack` / `ryu publish` compute it and
+   * write it here BEFORE the manifest is signed, so the hash rides INSIDE the
+   * Gateway-signed surface while the `ui_code` blob rides OUTSIDE it as payload;
+   * Core's install path recomputes the hash over the fetched code and rejects a
+   * mismatch fail-closed. Absent for a manifest-only plugin (no bundled UI).
+   * Mirrors Core's `PluginManifest.ui_code_sha256`.
+   */
+  ui_code_sha256: import_zod.z.string().nullish(),
+  /** The Runnables this plugin bundles. */
+  runnables: import_zod.z.array(RunnableMetaSchema).default([]),
+  /**
+   * Permission grants this plugin declares it needs (e.g. `"mcp:web_search"`).
+   * Declarations only — grant enforcement is the Gateway's responsibility.
+   */
+  permission_grants: import_zod.z.array(import_zod.z.string()).default([]),
+  /**
+   * Optional Companion surface (an in-desktop overlay or sidebar panel).
+   * Absent when the plugin has no Companion surface.
+   */
+  companion: CompanionSurfaceSchema.optional(),
+  /**
+   * VS-Code-style activation events (`"*"`, `"onStartup"`, `"onChat"`,
+   * `"onCommand:<id>"`). Empty = eager. Turn-hook plugins are driven by their
+   * enabled flag, so `["*"]` is the usual value.
+   */
+  activation_events: import_zod.z.array(import_zod.z.string()).default([]),
+  /**
+   * Contribution points: server-side turn hooks + declarative UI widgets.
+   * Absent for a plugin that contributes nothing here.
+   */
+  contributes: ContributesSchema.optional(),
+  /**
+   * **Plugin-to-plugin dependencies** — the other plugins this one needs. Core
+   * resolves them into a topological enable order (dependencies enable first;
+   * disabling one is refused while an enabled dependent needs it).
+   *
+   * Absent = **no dependencies**, the backward-compatible default. Kept
+   * `.optional()` (never defaulted) so a manifest that declares none serialises
+   * with no `requires` key at all, exactly like Core's
+   * `#[serde(skip_serializing_if = "Option::is_none")]`.
+   */
+  requires: RequiresSchema.optional(),
+  /**
+   * Host surfaces this plugin runs on. **Empty or absent = runs on EVERY
+   * surface** — the backward-compatible default, which must never be read as
+   * "runs nowhere". Core filters only when the list is explicitly non-empty, and
+   * only at the read boundary (`GET /api/plugins`, keyed on `x-ryu-surface`), so
+   * an unsupported-target plugin stays installable and inspectable.
+   */
+  targets: import_zod.z.array(SurfaceSchema).default([]),
+  /**
+   * Optional per-item AFFILIATE terms: the commission paid to a referrer when a
+   * referred user buys this (paid) item. `value` is basis points for `percent`
+   * (2000 = 20%) or minor units (cents) for `flat`. Absent (or `enabled:false`)
+   * falls back to the seller org owner's default affiliate terms. This is the
+   * authoring surface for the marketplace publish body's `affiliate` field (the
+   * server re-validates it); it only takes effect on a paid item.
+   */
+  affiliate: import_zod.z.object({
+    enabled: import_zod.z.boolean().default(false),
+    rule: import_zod.z.object({
+      type: import_zod.z.enum(["percent", "flat"]),
+      value: import_zod.z.number().nonnegative(),
+      recurring: import_zod.z.boolean().default(false),
+      durationMonths: import_zod.z.number().int().positive().nullish(),
+      fundedBy: import_zod.z.enum(["platform", "seller"]).default("platform")
+    }).optional()
+  }).optional(),
+  // ── Rich listing metadata (Phase 1.5) ──────────────────────────────────────
+  // Optional store-listing fields a plugin author declares so the marketplace
+  // detail dialog renders a richer App-Store-style preview. Field names align
+  // with the Claude `.claude-plugin/marketplace.json` plugin-entry standard where
+  // one exists (`author`, `homepage`, `keywords`, `category`, `license`); the
+  // rest are Ryu extensions. `ryu publish` forwards these FLAT into the publish
+  // body (not inside the signed manifest blob) so the control plane stores them.
+  // All optional + additive: a manifest omitting them still validates.
+  /** Longer plain/markdown description shown in the detail dialog. */
+  description: import_zod.z.string().optional(),
+  /** Short one-line pitch shown under the name (Ryu extension). */
+  tagline: import_zod.z.string().optional(),
+  /**
+   * Publisher identity. A bare string OR a Claude-style object; `ryu publish`
+   * resolves it to the display `developer` (`author.name` when an object).
+   */
+  author: import_zod.z.union([
+    import_zod.z.string(),
+    import_zod.z.object({
+      name: import_zod.z.string(),
+      email: import_zod.z.string().optional(),
+      url: import_zod.z.string().optional()
+    })
+  ]).optional(),
+  /** Project/marketing homepage — maps to the listing `website` (Claude field). */
+  homepage: import_zod.z.string().optional(),
+  /** Free-text search keywords (Claude field). */
+  keywords: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Taxonomy category beyond the runnable kinds (Claude field). */
+  category: import_zod.z.string().optional(),
+  /** SPDX-ish license identifier (Claude field). */
+  license: import_zod.z.string().optional(),
+  /** Square logo/icon URL for the listing card + detail header. */
+  iconUrl: import_zod.z.string().optional(),
+  /** Ordered App-Store-style screenshot gallery URLs (Ryu extension). */
+  screenshots: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Privacy policy URL surfaced on detail (Ryu extension). */
+  privacyPolicyUrl: import_zod.z.string().optional(),
+  /** Terms-of-service URL surfaced on detail (Ryu extension). */
+  termsOfServiceUrl: import_zod.z.string().optional(),
+  /**
+   * Human-readable capability strings (Ryu extension). When omitted the control
+   * plane derives a default from `permission_grants`, so declaring this is only
+   * needed to override the derived labels.
+   */
+  capabilities: import_zod.z.array(import_zod.z.string()).optional(),
+  /** Example prompt chips shown on detail (Ryu extension). */
+  examplePrompts: import_zod.z.array(import_zod.z.string()).optional(),
+  /**
+   * Optional companion/config card (Ryu extension): a single setup step or an
+   * array of steps guiding the user through post-install configuration.
+   */
+  setup: import_zod.z.union([SetupStepSchema, import_zod.z.array(SetupStepSchema)]).optional()
+});
+
+// src/cli.ts
+function uiCodeSha256(code) {
+  return (0, import_node_crypto.createHash)("sha256").update(code, "utf8").digest("hex");
+}
+function printUsage() {
+  process.stderr.write(
+    [
+      "Ryu dev SDK",
+      "",
+      "Usage:",
+      "  bunx ryu pack <dir>      Validate and bundle a plugin.json Plugin",
+      "  bunx ryu publish <dir>   Validate and publish a plugin.json Plugin to the Ryu Marketplace",
+      "  bunx ryu dev <entry>     Run a Runnable locally with an interactive chat loop",
+      ""
+    ].join("\n")
+  );
+}
+function exitError(message) {
+  process.stderr.write(`error: ${message}
+`);
+  process.exit(1);
+}
+function loadManifest(dir) {
+  const manifestPath = (0, import_node_path.join)(dir, "plugin.json");
+  if (!(0, import_node_fs.existsSync)(manifestPath)) {
+    exitError(`plugin.json not found in: ${dir}`);
+  }
+  let raw;
+  try {
+    raw = (0, import_node_fs.readFileSync)(manifestPath, "utf8");
+  } catch (err) {
+    exitError(`could not read ${manifestPath}: ${String(err)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    exitError(`plugin.json is not valid JSON: ${manifestPath}`);
+  }
+  const result = PluginManifestSchema.safeParse(parsed);
+  if (!result.success) {
+    const first = result.error.issues[0];
+    const field = first?.path.join(".") ?? "unknown";
+    const message = first?.message ?? "validation failed";
+    exitError(`plugin.json validation failed at '${field}': ${message}`);
+  }
+  return result.data;
+}
+function resolveUiEntry(manifest) {
+  for (const runnable of manifest.runnables) {
+    if (runnable.kind !== "companion") {
+      continue;
+    }
+    const entry = runnable.config?.ui_entry;
+    if (typeof entry === "string" && entry.trim().length > 0) {
+      return entry;
+    }
+  }
+  for (const widget of manifest.contributes?.widgets ?? []) {
+    const entry = widget.ui_entry;
+    if (typeof entry === "string" && entry.trim().length > 0) {
+      return entry;
+    }
+  }
+  return null;
+}
+function resolveUiFormat(manifest) {
+  for (const runnable of manifest.runnables) {
+    if (runnable.kind !== "companion") {
+      continue;
+    }
+    const fmt = runnable.config?.ui_format;
+    if (typeof fmt === "string" && fmt.trim().toLowerCase() === "html") {
+      return "html";
+    }
+  }
+  return "js";
+}
+function readUiEntryHtml(dir, uiEntry) {
+  const entryPath = (0, import_node_path.resolve)(dir, uiEntry);
+  if (!(0, import_node_fs.existsSync)(entryPath)) {
+    exitError(`companion ui_entry (html) not found: ${entryPath}`);
+  }
+  return (0, import_node_fs.readFileSync)(entryPath, "utf8");
+}
+async function bundleUiEntry(dir, uiEntry) {
+  const entryPath = (0, import_node_path.resolve)(dir, uiEntry);
+  if (!(0, import_node_fs.existsSync)(entryPath)) {
+    exitError(`companion ui_entry not found: ${entryPath}`);
+  }
+  const result = await Bun.build({
+    entrypoints: [entryPath],
+    target: "browser",
+    format: "esm",
+    minify: false
+  });
+  if (!result.success) {
+    const messages = result.logs.map((l) => String(l.message)).join("; ");
+    exitError(`failed to bundle ui_entry '${uiEntry}': ${messages}`);
+  }
+  const output = result.outputs[0];
+  if (!output) {
+    exitError(`bundling ui_entry '${uiEntry}' produced no output`);
+  }
+  return await output.text();
+}
+async function commandPack(rawDir) {
+  const dir = (0, import_node_path.resolve)(rawDir);
+  const manifest = loadManifest(dir);
+  const uiEntry = resolveUiEntry(manifest);
+  const uiCode = uiEntry ? resolveUiFormat(manifest) === "html" ? readUiEntryHtml(dir, uiEntry) : await bundleUiEntry(dir, uiEntry) : null;
+  const manifestWithHash = uiCode ? { ...manifest, ui_code_sha256: uiCodeSha256(uiCode) } : manifest;
+  const outDir = (0, import_node_path.join)(dir, "dist");
+  if (!(0, import_node_fs.existsSync)(outDir)) {
+    (0, import_node_fs.mkdirSync)(outDir, { recursive: true });
+  }
+  const outPath = (0, import_node_path.join)(outDir, "plugin.bundle.json");
+  const bundle = uiCode ? { ...manifestWithHash, ui_code: uiCode } : manifestWithHash;
+  (0, import_node_fs.writeFileSync)(outPath, JSON.stringify(bundle, null, 2), "utf8");
+  const codeNote = uiCode ? ` (+${uiCode.length}B ui_code)` : "";
+  process.stdout.write(
+    `packed ${manifest.id}@${manifest.version}${codeNote} \u2192 ${outPath}
+`
+  );
+}
+var TRAILING_SLASHES = /\/+$/;
+function publishBaseUrl() {
+  const raw = (process.env.RYU_MARKETPLACE_API_URL ?? "").trim();
+  return (raw || "http://localhost:3000").replace(TRAILING_SLASHES, "");
+}
+function authToken() {
+  const token = (process.env.RYU_AUTH_TOKEN ?? "").trim();
+  if (!token) {
+    exitError(
+      "publish requires an auth token: set RYU_AUTH_TOKEN to your Ryu access token"
+    );
+  }
+  return token;
+}
+var SDK_PUBLISH_KIND = "plugin";
+async function commandPublish(rawDir) {
+  const dir = (0, import_node_path.resolve)(rawDir);
+  const manifest = loadManifest(dir);
+  const token = authToken();
+  const kind = SDK_PUBLISH_KIND;
+  const uiEntry = resolveUiEntry(manifest);
+  const uiCode = uiEntry ? resolveUiFormat(manifest) === "html" ? readUiEntryHtml(dir, uiEntry) : await bundleUiEntry(dir, uiEntry) : null;
+  const manifestWithHash = uiCode ? { ...manifest, ui_code_sha256: uiCodeSha256(uiCode) } : manifest;
+  const developer = typeof manifest.author === "string" ? manifest.author : manifest.author?.name;
+  const runnablesForDisplay = manifest.runnables.map((r) => ({
+    id: r.id,
+    kind: r.kind,
+    name: r.name,
+    enabled: true
+  }));
+  const listingMetadata = {
+    ...manifest.description ? { description: manifest.description } : {},
+    ...manifest.tagline ? { tagline: manifest.tagline } : {},
+    ...developer ? { developer } : {},
+    ...manifest.category ? { category: manifest.category } : {},
+    ...manifest.iconUrl ? { iconUrl: manifest.iconUrl } : {},
+    ...manifest.screenshots?.length ? { screenshots: manifest.screenshots } : {},
+    ...manifest.homepage ? { website: manifest.homepage } : {},
+    ...manifest.privacyPolicyUrl ? { privacyPolicyUrl: manifest.privacyPolicyUrl } : {},
+    ...manifest.termsOfServiceUrl ? { termsOfServiceUrl: manifest.termsOfServiceUrl } : {},
+    ...manifest.capabilities?.length ? { capabilities: manifest.capabilities } : {},
+    ...manifest.examplePrompts?.length ? { examplePrompts: manifest.examplePrompts } : {},
+    ...manifest.setup ? { setup: manifest.setup } : {},
+    ...runnablesForDisplay.length ? { runnables: runnablesForDisplay } : {}
+  };
+  const url = `${publishBaseUrl()}/api/marketplace/publish`;
+  const body = {
+    id: manifest.id,
+    kind,
+    name: manifest.name,
+    version: manifest.version,
+    manifest: manifestWithHash,
+    // The descriptor is the manifest itself for a plugin/skill Plugin; Core maps
+    // it on install. Grants are read from the manifest server-side too.
+    descriptor: manifestWithHash,
+    grants: manifest.permission_grants ?? [],
+    // Rich listing metadata (Phase 1.5) forwarded flat; see above.
+    ...listingMetadata,
+    // Per-item affiliate terms (optional): the commission a referrer earns when
+    // a referred user buys this paid item. The server re-validates the rule and
+    // stores it as the item's override (else the seller default applies).
+    ...manifest.affiliate?.enabled ? { affiliate: manifest.affiliate } : {},
+    // The bundled UI code rides OUTSIDE the signed manifest as payload; the
+    // server stores it and serves it on detail. Omitted for manifest-only.
+    ...uiCode ? { ui_code: uiCode } : {}
+  };
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${token}`
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (err) {
+    exitError(`could not reach ${url}: ${String(err)}`);
+  }
+  const text = await resp.text();
+  if (!resp.ok) {
+    exitError(`publish failed (${resp.status}): ${text}`);
+  }
+  process.stdout.write(
+    `published ${manifest.id}@${manifest.version} (${kind}) \u2192 pending moderation
+${text}
+`
+  );
+}
+var [, , command, ...args] = process.argv;
+if (!command) {
+  printUsage();
+  process.exit(1);
+}
+if (command === "pack") {
+  const dir = args[0];
+  if (!dir) {
+    exitError("pack requires a directory argument: bunx ryu pack <dir>");
+  }
+  commandPack(dir).catch((err) => {
+    exitError(String(err));
+  });
+} else if (command === "publish") {
+  const dir = args[0];
+  if (!dir) {
+    exitError("publish requires a directory argument: bunx ryu publish <dir>");
+  }
+  commandPublish(dir).catch((err) => {
+    exitError(String(err));
+  });
+} else if (command === "dev") {
+  const entry = args[0];
+  if (!entry) {
+    exitError("dev requires an entry argument: bunx ryu dev <entry>");
+  }
+  commandDev(entry).catch((err) => {
+    exitError(String(err));
+  });
+} else {
+  printUsage();
+  exitError(`unknown command: ${command}`);
+}