opencode-plugin-kit 1.0.0-alpha.1

package/src/schemas.ts

@@ -0,0 +1,70 @@
+// Zod schemas for the untrusted shapes crossing the OpenCode boundary.
+//
+// These are the shapes that silently change under us: the service's
+// integration list (connected-provider gating) and the usage endpoint's
+// quota windows. Parse, degrade to last-known-good on failure — never cast.
+// See docs/opencode2-api.md for where each shape comes from.
+import { z } from "zod"
+
+/** One window of plan quota: server-reported percent + reset time. */
+export const windowSchema = z.object({
+  status: z.string().optional(),
+  percent: z.number().optional(),
+  resetsAt: z.string().optional(),
+})
+export type Window = z.infer<typeof windowSchema>
+
+/** The usage endpoint (`https://opencode.ai/zen/go/v1/usage`): workspace
+ * plan quota over rolling 5h / weekly / monthly windows. */
+export const usageResponseSchema = z.object({
+  usage: z
+    .object({
+      rolling: windowSchema.optional(),
+      weekly: windowSchema.optional(),
+      monthly: windowSchema.optional(),
+    })
+    .optional(),
+})
+export type UsageResponse = z.infer<typeof usageResponseSchema>
+
+/** One credential added via /connect (key or OAuth). */
+export const connectionSchema = z.object({
+  type: z.string().optional(),
+  id: z.string().optional(),
+  label: z.string().optional(),
+})
+
+/** An entry of `GET /api/integration` (same source /connect reads). An
+ * entry is "connected" iff its `connections` array is non-empty. */
+export const integrationSchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  connections: z.array(connectionSchema).optional(),
+})
+export type Integration = z.infer<typeof integrationSchema>
+
+/** Parse a usage-endpoint payload. Returns null instead of throwing when
+ * the shape is unrecognized — callers fall back to their cache. */
+export function parseUsage(raw: unknown): UsageResponse | null {
+  const result = usageResponseSchema.safeParse(raw)
+  return result.success ? result.data : null
+}
+
+/** Parse the integration list. Accepts both the wrapped `{ data: [...] }`
+ * and bare-array responses. */
+export function parseIntegrationList(raw: unknown): Integration[] | null {
+  const result = z.union([z.object({ data: z.array(integrationSchema) }), z.array(integrationSchema)]).safeParse(raw)
+  if (!result.success) return null
+  return "data" in result.data ? result.data.data : result.data
+}
+
+/** Provider ids with at least one added connection — the eligibility set
+ * for provider-gated views. */
+export function connectedProviderIds(raw: unknown): Set<string> {
+  const list = parseIntegrationList(raw)
+  const ids = new Set<string>()
+  for (const item of list ?? []) {
+    if ((item.connections?.length ?? 0) > 0 && item.id) ids.add(item.id)
+  }
+  return ids
+}

package/src/toast.ts

@@ -0,0 +1,21 @@
+// Fire-and-forget toast helper.
+//
+// The host's toast UI is optional at the edges (beta API): every plugin
+// hand-rolled the same try/catch fallback around `ui.toast.show`.
+import type { KitContext, KitUI, ToastInput } from "./host.ts"
+
+/** Show a toast; silently no-ops when the host has no toast UI or it throws.
+ * Takes a minimal structural slice — the full host context's `ui.slot` is
+ * over-loaded in newer betas and would not assign to KitContext here. */
+export function showToast(
+  context: { readonly ui?: { readonly toast?: { readonly show?: (input: ToastInput) => void } } },
+  message: string,
+  variant: ToastInput["variant"] = "success",
+): void {
+  try {
+    const toast = (context.ui as Partial<KitUI>).toast
+    toast?.show?.({ message, variant })
+  } catch {
+    // Toast unavailable; the caller's inline UI still reflects the change.
+  }
+}

package/src/viewPicker.ts

@@ -0,0 +1,172 @@
+// Persisted view/filter picker for OpenCode sidebar widgets.
+//
+// The pattern shared by the usage-quota tracker (`/usage-view`) and the model
+// recommender (`/model-view`): a registry of views, a durable selection, a
+// slash/palette command registered through a keymap layer (which only works
+// from a rendered `app` slot), a dialog picker, and a confirmation toast.
+import type { KitContext } from "./host.ts"
+import { registerKeymapCommand } from "./commands.ts"
+import { persistedCell } from "./cache.ts"
+import { createSignal } from "solid-js"
+
+export interface PickerOption {
+  readonly id: string
+  readonly title: string
+  readonly description?: string
+}
+
+export interface PickerConfig<T extends PickerOption> {
+  /** The view registry — the single extension point. */
+  readonly registry: readonly T[]
+  /** Durable storage key (plugin-scoped) for the selection. */
+  readonly storageKey: string
+  /** Slash/palette command wiring. `title` may ignore its argument to show a
+   * session-derived effective view (the usage plugin does this). */
+  readonly command: {
+    readonly id: string
+    readonly group: string
+    /** Slash name, e.g. "usage-view". */
+    readonly name: string
+    readonly aliases?: string[]
+    readonly title: (current: T) => string
+    readonly description: string
+  }
+  /** Dialog texts for the interactive picker. */
+  readonly dialog: { readonly title: string; readonly message: string }
+  /** Toast message on switch; defaults to `${prefix}: ${entry.title} view`. */
+  readonly toastPrefix?: string
+  /** Only these entries are selectable (e.g. provider-key gating). Defaults
+   * to everything. Read at pick time, so closures see fresh state. */
+  readonly selectable?: (entry: T) => boolean
+  /** Message when an explicitly requested entry isn't selectable. */
+  readonly unavailableMessage?: (entry: T) => string
+}
+
+export interface ViewPicker<T extends PickerOption> {
+  /** Currently selected entry (persisted pick; auto-pick logic stays
+   * plugin-local and can layer on top). */
+  readonly current: () => T
+  readonly currentID: () => string
+  /** Switch without UI: persist + toast. No-op when already selected. */
+  readonly apply: (entry: T) => void
+  /** Open the picker, or select directly from an argument (`/x zen`). */
+  readonly pick: (arg?: string) => Promise<void>
+  /** Register the slash/palette command (call once from setup). */
+  readonly registerCommand: () => void
+}
+
+export function createViewPicker<T extends PickerOption>(context: KitContext, config: PickerConfig<T>): ViewPicker<T> {
+  const registry = config.registry
+  const first = registry[0]
+  if (!first) throw new Error("createViewPicker: empty registry")
+
+  const [currentID, setCurrentID] = createSignal<string>(first.id)
+
+  type StoredView = { id?: string }
+  const cell = persistedCell<StoredView>(context, config.storageKey, { id: first.id })
+
+  // Load the persisted pick, if any.
+  try {
+    const persisted = cell.read()
+    if (persisted?.id && registry.some((e) => e.id === persisted.id)) setCurrentID(persisted.id)
+  } catch {
+    // In-memory only.
+  }
+
+  const persist = (id: string) => {
+    cell.persist((s) => {
+      s.id = id
+    })
+  }
+
+  const current = () => registry.find((e) => e.id === currentID()) ?? first
+
+  const apply = (entry: T) => {
+    if (entry.id === currentID()) return
+    setCurrentID(entry.id)
+    persist(entry.id)
+    try {
+      context.ui.toast.show({
+        message: config.toastPrefix ? `${config.toastPrefix}: ${entry.title} view` : entry.title,
+        variant: "success",
+      })
+    } catch {
+      // Toast unavailable; reactivity still re-renders.
+    }
+  }
+
+  const selectable = config.selectable ?? (() => true)
+
+  const pick = async (arg?: string) => {
+    const wanted = arg?.trim().toLowerCase()
+    if (wanted) {
+      const match = registry.find((e) => e.id === wanted || e.title.toLowerCase() === wanted)
+      if (match) {
+        if (selectable(match)) return apply(match)
+        try {
+          await context.ui.dialog.alert({
+            title: config.dialog.title,
+            message: config.unavailableMessage?.(match) ?? `${match.title} is not available right now.`,
+          })
+        } catch {
+          // Dialog unavailable.
+        }
+        return
+      }
+      try {
+        await context.ui.dialog.alert({
+          title: config.dialog.title,
+          message: `Unknown view "${arg}". Available: ${
+            registry
+              .filter(selectable)
+              .map((e) => e.id)
+              .join(", ") || "none"
+          }`,
+        })
+      } catch {
+        // Dialog unavailable.
+      }
+      return
+    }
+    try {
+      const selected = await context.ui.dialog.select({
+        title: config.dialog.title,
+        message: config.dialog.message,
+        current: currentID(),
+        options: registry.filter(selectable).map((e) => ({
+          title: e.title,
+          value: e.id,
+          description: e.description ?? "",
+          disabled: false,
+        })),
+      })
+      const match = registry.find((e) => e.id === selected)
+      if (match) apply(match)
+    } catch {
+      // Dialog unavailable.
+    }
+  }
+
+  // Keymap layers are owned by the calling component, so the command is
+  // registered from a rendered `app` slot (see registerKeymapCommand). The
+  // factory form keeps the title fresh across palette renders.
+  const registerCommand = () =>
+    registerKeymapCommand(context, () => ({
+      id: config.command.id,
+      title: config.command.title(current()),
+      description: config.command.description,
+      group: config.command.group,
+      palette: true,
+      slash: {
+        name: config.command.name,
+        aliases: config.command.aliases,
+        arguments: true,
+      },
+      suggested: true,
+      run: (input?: string) => {
+        void pick(input)
+      },
+    }))
+
+  return { current, currentID, apply, pick, registerCommand }
+}

package/src/workspace.ts

@@ -0,0 +1,21 @@
+// Workspace location resolution shared by the TUI plugins.
+//
+// The client may expose the workspace location directly (`context.location`)
+// or behind `data.location.default()`, and the directory may live on
+// `.directory` or be the location value itself. The plugin-manager and the
+// skill lister each hand-rolled this dance.
+
+/**
+ * Resolve the workspace location object for a plugin context. Returns
+ * whatever the client exposes — callers that need a path should prefer
+ * `workspaceDirectory`.
+ */
+export function resolveLocation(context: any): any {
+  return context.location ?? context.data.location.default()
+}
+
+/** Resolve the workspace directory as a string ("." when nothing resolves). */
+export function workspaceDirectory(context: any): string {
+  const location = resolveLocation(context)
+  return String(location?.directory ?? location ?? ".")
+}