@pragma-sh/plugin 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @pragma-sh/plugin
+
+Build a Pragma plugin in TypeScript. Part of [Pragma](https://github.com/pragma-sh/pragma) — a desktop workspace for
+running persistent, worktree-scoped coding agents.
+
+Sidebar tabs, cards, commands, themes, web views and launchable agents, plus the
+React runtime the host provides. Scaffold a project with
+[`create-pragma-plugin`](https://www.npmjs.com/package/create-pragma-plugin)
+rather than wiring this up by hand.
+
+```sh
+bun create pragma-plugin my-plugin
+```
+
+```ts
+import { definePlugin, defineSidebarTab } from "@pragma-sh/plugin";
+```
+
+React, React DOM and the JSX runtime are re-exported under
+`@pragma-sh/plugin/react`, `/react-dom` and `/jsx-runtime` — alias them in your
+bundler so your plugin shares the host's single React instance.
+
+Docs: <https://pragma-app.sh/docs/plugins/getting-started>
+
+## License
+
+AGPL-3.0-only. See [LICENSE](https://github.com/pragma-sh/pragma/blob/main/LICENSE).

package/dist/catalog.cjs

@@ -0,0 +1,77 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/catalog.ts
+var exports_catalog = {};
+__export(exports_catalog, {
+  runProviderCommand: () => runProviderCommand,
+  defineUsageLimitProvider: () => defineUsageLimitProvider,
+  definePlugin: () => definePlugin,
+  defineAgent: () => defineAgent,
+  CLI_MISSING_STATUS: () => CLI_MISSING_STATUS
+});
+module.exports = __toCommonJS(exports_catalog);
+
+// src/agent.ts
+function defineAgent(input) {
+  return input;
+}
+// src/generated/version.ts
+var PLUGIN_API_VERSION = "0.1.0";
+
+// src/plugin.ts
+function definePlugin(input) {
+  return { ...input, __apiVersion: PLUGIN_API_VERSION };
+}
+// src/usage-limits.ts
+var CLI_MISSING_STATUS = 20;
+async function runProviderCommand(ctx, command, missingStatus = CLI_MISSING_STATUS) {
+  const [result] = await ctx.sdk.exec.run({
+    cwd: ctx.project?.path ?? "/tmp",
+    commands: [command]
+  });
+  if (result?.status === missingStatus)
+    return { kind: "missing" };
+  if (!result || result.status !== 0) {
+    return { kind: "failed", stderr: result?.stderr.trim() ?? "" };
+  }
+  return { kind: "ok", stdout: result.stdout };
+}
+function defineUsageLimitProvider(input) {
+  return input;
+}

package/dist/catalog.d.cts

@@ -0,0 +1,363 @@
+import { AgentFeature as SharedAgentFeature } from "@pragma-sh/constants";
+import { ComponentType, ReactNode } from "react";
+import { PragmaClient } from "@pragma-sh/sdk";
+/** Imperative durable JSON storage bound by the host to one plugin. */
+interface PluginStorage {
+	get<T>(key: string, initialValue: T): Promise<T>;
+	set<T>(key: string, value: T): Promise<void>;
+	delete(key: string): Promise<void>;
+}
+/** The active project a plugin is rendered against, or `null` when none is selected. */
+interface PluginProject {
+	id: string;
+	name: string;
+	path: string;
+}
+/** Options for {@link PluginContext.notify} / `useNotify()`. */
+interface PluginNotifyOptions {
+	variant?: "info" | "success" | "warning" | "error";
+	description?: string;
+	/** Also send a native OS notification through Pragma's notification bridge. */
+	native?: boolean;
+}
+/**
+* Context passed to every plugin callback: contribution `when` guards, command
+* `run` handlers, agent event handlers, and `activate`.
+*/
+interface PluginContext<TConfig = unknown> {
+	/** This plugin's stable id, derived from its `package.json` name. */
+	pluginId: string;
+	/** Absolute plugin package directory when available in this runtime. */
+	pluginDir?: string;
+	/** This plugin's user-supplied config, already validated against its `config` schema. */
+	config: TConfig;
+	/** The active project, or `null` when no project is selected. */
+	project: PluginProject | null;
+	/** Typed SDK client for talking to the local Pragma gateway. */
+	sdk: PragmaClient;
+	/** Shows an in-app notification. */
+	notify: (message: string, options?: PluginNotifyOptions) => void;
+	/** Durable storage scoped to this plugin. Available in desktop-hosted callbacks. */
+	storage?: PluginStorage;
+}
+/** Payload emitted for `pragma://plugin/<pluginId>/<path>` deep links. */
+interface PluginDeepLinkEvent {
+	pluginId: string;
+	path: string;
+	url: string;
+	params: Record<string, string[]>;
+}
+/** An icon contributed alongside a sidebar tab, command, or agent. */
+type PluginIcon = ComponentType<{
+	className?: string;
+}>;
+/** Values passed directly to every host-rendered plugin component. */
+interface PluginComponentProps<TWebViewPayload = unknown> {
+	/** Payload supplied when this component renders as a plugin web view. */
+	webViewPayload?: TWebViewPayload;
+}
+/** A host-rendered plugin component. Hooks remain available for reactive host state. */
+type PluginComponent<TWebViewPayload = unknown> = {
+	bivarianceHack(props: PluginComponentProps<TWebViewPayload>): ReactNode;
+}["bivarianceHack"];
+/** A guard evaluated by the host to decide whether a contribution should render. */
+type PluginWhen<TConfig = unknown> = (ctx: PluginContext<TConfig>) => boolean;
+/** A tab contributed to the project sidebar. */
+interface SidebarTabDefinition<TConfig = unknown> {
+	id: string;
+	title: string;
+	icon?: PluginIcon;
+	component: PluginComponent;
+	when?: PluginWhen<TConfig>;
+}
+/** A page contributed to Pragma Settings. */
+interface SettingsPageDefinition<TConfig = unknown> {
+	id: string;
+	title: string;
+	icon?: PluginIcon;
+	component: PluginComponent;
+	when?: PluginWhen<TConfig>;
+}
+/** Options used when opening a plugin web view tab. */
+interface OpenWebViewOptions<TPayload = unknown> {
+	/** Overrides the tab title; falls back to the web view title, then id. */
+	title?: string;
+	/** JSON-serializable data made available through `useWebViewPayload`. */
+	payload?: TPayload;
+	/** Stable key used by the host to focus an existing matching web view tab. */
+	dedupeKey?: string;
+}
+/** A plugin-defined React view that renders inside a workspace tab web view. */
+interface WebViewDefinition<TPayload = unknown> {
+	id: string;
+	title?: string;
+	component: PluginComponent<TPayload>;
+	/** Opens this web view as a workspace tab. */
+	open(options?: OpenWebViewOptions<TPayload>): Promise<void>;
+}
+/** An item contributed to the workspace topper bar. */
+interface TopperItemDefinition<TConfig = unknown> {
+	align: "left" | "right";
+	component: PluginComponent;
+	when?: PluginWhen<TConfig>;
+}
+/** A card contributed to the project sidebar. */
+interface SidebarCardDefinition<TConfig = unknown> {
+	title: string;
+	component: PluginComponent;
+	when?: PluginWhen<TConfig>;
+}
+/** A command contributed to the command palette / keybindings surface. */
+interface CommandDefinition<TConfig = unknown> {
+	id: string;
+	title: string;
+	icon?: PluginIcon;
+	defaultBinding?: string;
+	hidden?: boolean;
+	run: (ctx: PluginContext<TConfig>, args?: unknown) => void | Promise<void>;
+}
+/**
+* Timed input sent to the agent's terminal after launch and before an
+* optional prompt prefill. Field names mirror the host's existing
+* the old `~/.pragma/agents/<id>/config.json` shape (`startupInput`) exactly, so
+* plugin-contributed agents carry over unchanged.
+*/
+interface AgentStartupInput {
+	delayMs: number;
+	data: string;
+}
+/** One selectable reasoning-effort level for a model. */
+interface AgentReasoning {
+	id: string;
+	name: string;
+}
+/** One selectable model for an agent. */
+interface AgentModelEntry {
+	id: string;
+	name: string;
+	reasoning?: AgentReasoning[];
+}
+/** One selectable permission mode for an agent. */
+interface AgentPermissionMode {
+	id: string;
+	name: string;
+}
+/** Builds the launch command-line arguments for a selected model/reasoning/permission mode. */
+interface AgentArgsBuilder {
+	model: (modelId: string) => string[];
+	reasoning: (reasoningId: string) => string[];
+	modelReasoning?: (modelId: string, reasoningId: string) => string[];
+	permissionMode: (permissionModeId: string) => string[];
+}
+/** Optional agent capabilities that can be excluded from `pragma-cli agent verify`. */
+type AgentFeature = SharedAgentFeature;
+/**
+* Declares an agent a plugin makes launchable from Pragma. Field names below
+* `launch`/`models`/`permissionModes`/`args` are new, JS-only additions;
+* `startupInput`/`prefillDelayMs`/`prefillMode`/`prefillSubmit`/
+* `prefillSubmitDelayMs` carry over the existing agent-launcher config shape
+* exactly (see `src-tauri/src/agents.rs`).
+*/
+interface AgentDefinition<TConfig = unknown> {
+	id: string;
+	name: string;
+	icon: PluginIcon;
+	/** Browser URL, absolute filesystem path, or plugin-dir-relative asset path for the agent icon. */
+	iconPath?: string;
+	launch: {
+		command: string[];
+	};
+	models: AgentModelEntry[] | ((ctx: PluginContext<TConfig>) => Promise<AgentModelEntry[]>);
+	permissionModes: AgentPermissionMode[];
+	args: AgentArgsBuilder;
+	/** Capabilities this agent does not support; matching verification scenarios are skipped. */
+	excludeFeatures?: AgentFeature[];
+	startupInput?: AgentStartupInput[];
+	prefillDelayMs?: number;
+	prefillMode?: "bracketed" | "plain";
+	prefillSubmit?: string;
+	prefillSubmitDelayMs?: number;
+}
+/** Declares an agent contribution. */
+declare function defineAgent<TConfig = unknown>(input: AgentDefinition<TConfig>): AgentDefinition<TConfig>;
+import { AgentReportPayload } from "@pragma-sh/constants";
+import { ZodType, ZodTypeAny } from "zod";
+import { AgentMessage, PragmaClient as PragmaClient2 } from "@pragma-sh/sdk";
+/** Declares a watcher a plugin attaches to one of its agents' sessions. */
+interface WatcherDefinition<TConfig = unknown> {
+	/** The `defineAgent` id this watcher attaches to. */
+	agent: string;
+	/** Runs once per launched session; lives until the session exits. */
+	watch: (ctx: WatcherContext<TConfig>) => void | Promise<void>;
+}
+/** Host-side context passed to a running watcher instance. */
+interface WatcherContext<TConfig = unknown> {
+	/** Typed gateway SDK. */
+	sdk: PragmaClient2;
+	/** Full agent id this watcher instance is bound to (plugin-qualified). */
+	agentId: string;
+	/** This plugin's validated config. */
+	config: TConfig;
+	/** Session this watcher is attached to. */
+	session: {
+		id: string;
+		tabId: string;
+		worktreeId: string;
+	};
+	/** Decoded terminal output chunks for this session. */
+	output: AsyncIterable<string>;
+	/** Writes bytes into the live terminal session. */
+	sendKeys: (data: string) => Promise<void>;
+	/** Reports a rich message for this watcher-owned agent. */
+	reportMessage: (msg: Omit<AgentMessage, "agent" | "tabId" | "worktreeId">) => Promise<void>;
+	/** Aborts when the session exits or the watcher is stopped. */
+	signal: AbortSignal;
+}
+/** One finite or unlimited usage category reported by a provider. */
+interface UsageLimit {
+	id: string;
+	title: string;
+	used: number;
+	/** A null limit represents unlimited usage. */
+	limit: number | null;
+	/** Milliseconds until this category resets, measured from `observedAt`. */
+	resetsInMs?: number;
+}
+/** A successful provider snapshot. */
+interface UsageLimitsReady {
+	status: "ready";
+	/** Unix time in milliseconds when the provider observed these values. */
+	observedAt: number;
+	/** Optional collapsed-row metric derived separately from the detailed limits. */
+	summary?: UsageLimit;
+	limits: UsageLimit[];
+}
+/** Why a provider cannot currently report usage limits. */
+type UsageLimitsUnavailableReason = "not-configured" | "authentication-required" | "unsupported" | "error";
+/** A provider state that requires user or platform action before loading. */
+interface UsageLimitsUnavailable {
+	status: "unavailable";
+	reason: UsageLimitsUnavailableReason;
+	message: string;
+}
+/** Result returned by a usage-limit provider. Unexpected failures should throw. */
+type UsageLimitsResult = UsageLimitsReady | UsageLimitsUnavailable;
+/**
+* Exit status a provider's shell wrapper uses to report that the agent CLI is
+* not on PATH, distinguishing "not installed" from a genuine command failure.
+*/
+declare const CLI_MISSING_STATUS = 20;
+/** Outcome of one provider CLI invocation. */
+type ProviderCommandOutcome = {
+	kind: "missing";
+} | {
+	kind: "failed";
+	stderr: string;
+} | {
+	kind: "ok";
+	stdout: string;
+};
+/**
+* Runs a single provider command in the active project and classifies its exit
+* status. Callers map `missing`/`failed` onto their own messages, since the
+* wording and the reasons worth special-casing differ per agent.
+*/
+declare function runProviderCommand<TConfig>(ctx: PluginContext<TConfig>, command: string, missingStatus?: number): Promise<ProviderCommandOutcome>;
+/** A plugin-owned usage source rendered by Pragma's shared usage-limits UI. */
+interface UsageLimitProviderDefinition<TConfig = unknown> {
+	id: string;
+	title: string;
+	/** Absolute URL for viewing this provider's usage in its dashboard. */
+	dashboardUrl: string;
+	icon?: PluginIcon;
+	/** Browser URL, absolute path, or plugin-directory-relative asset path. */
+	iconPath?: string;
+	/** Category rendered in the provider's collapsed summary row. */
+	primaryLimitId: string;
+	/** Requested refresh cadence. The host may enforce a larger minimum. */
+	refreshIntervalMs?: number;
+	load: (ctx: PluginContext<TConfig>) => Promise<UsageLimitsResult>;
+}
+/** Declares a provider for Pragma's shared usage-limits UI. */
+declare function defineUsageLimitProvider<TConfig = unknown>(input: UsageLimitProviderDefinition<TConfig>): UsageLimitProviderDefinition<TConfig>;
+/** Color schemes supported by Pragma themes. */
+type ThemeMode = "light" | "dark";
+/** Theme token overrides for one color scheme, keyed without the `--` prefix. */
+type ThemeColors = Record<ThemeMode, Record<string, string>>;
+/** A selectable theme contributed to Pragma's Theme settings. */
+interface ThemeDefinition {
+	/** Stable id within this plugin. */
+	id: string;
+	/** Human-readable name shown in Theme settings. */
+	name: string;
+	/** Optional detail shown under the theme name. */
+	description?: string;
+	/** Light and dark Pragma theme-token overrides. */
+	colors: ThemeColors;
+}
+/** Infers a config schema's parsed output type, defaulting to `unknown` when no schema is given. */
+type InferConfig<TConfigSchema extends ZodTypeAny> = TConfigSchema extends ZodType<infer Output> ? Output : unknown;
+/** UI surfaces a plugin can contribute to. */
+interface PluginUiContributions<TConfig = unknown> {
+	sidebarTabs?: SidebarTabDefinition<TConfig>[];
+	settingsPages?: SettingsPageDefinition<TConfig>[];
+	topper?: TopperItemDefinition<TConfig>[];
+	sidebarCards?: SidebarCardDefinition<TConfig>[];
+	webViews?: WebViewDefinition[];
+}
+/** Whether a plugin's declared values are merged with or replace host defaults. */
+type PluginContributionStrategy = "merge" | "replace";
+/** Default settings values a plugin contributes. */
+interface PluginSettingsContributions {
+	strategy?: PluginContributionStrategy;
+	values: Record<string, unknown>;
+}
+/** Default keybindings a plugin contributes. */
+interface PluginKeybindingsContributions {
+	strategy?: PluginContributionStrategy;
+	bindings: Record<string, string>;
+}
+/** Daemon-forwarded events a plugin can subscribe to declaratively. */
+interface PluginEventHandlers<TConfig = unknown> {
+	"agent.report"?: (event: AgentReportPayload, ctx: PluginContext<TConfig>) => void;
+	deepLink?: (event: PluginDeepLinkEvent, ctx: PluginContext<TConfig>) => void;
+}
+/** The object shape passed to `definePlugin`. */
+interface PluginDefinitionInput<TConfigSchema extends ZodTypeAny = ZodTypeAny> {
+	name: string;
+	description?: string;
+	icon?: PluginIcon;
+	config?: TConfigSchema;
+	ui?: PluginUiContributions<InferConfig<TConfigSchema>>;
+	agents?: AgentDefinition<InferConfig<TConfigSchema>>[];
+	watchers?: WatcherDefinition<InferConfig<TConfigSchema>>[];
+	commands?: CommandDefinition<InferConfig<TConfigSchema>>[];
+	settings?: PluginSettingsContributions;
+	keybindings?: PluginKeybindingsContributions;
+	events?: PluginEventHandlers<InferConfig<TConfigSchema>>;
+	usageLimits?: UsageLimitProviderDefinition<InferConfig<TConfigSchema>>[];
+	themes?: ThemeDefinition[];
+	css?: string;
+	/** Runs once when Pragma first discovers this plugin installation. */
+	onInstall?: (ctx: PluginContext<InferConfig<TConfigSchema>>) => void | Promise<void>;
+	/** Runs once during every Pragma server boot. */
+	onPragmaLoad?: (ctx: PluginContext<InferConfig<TConfigSchema>>) => void | Promise<void>;
+	activate?: (ctx: PluginContext<InferConfig<TConfigSchema>>) => void | (() => void);
+}
+/**
+* A fully-declared plugin, as returned by `definePlugin`. `__apiVersion` is
+* stamped automatically — plugin authors never set it themselves, and it
+* lives under a deliberately internal-looking name so it doesn't show up as
+* something to configure.
+*/
+interface PluginDefinition<TConfigSchema extends ZodTypeAny = ZodTypeAny> extends PluginDefinitionInput<TConfigSchema> {
+	/** @internal The `@pragma-sh/plugin` version this plugin was compiled against. */
+	readonly __apiVersion: string;
+}
+/**
+* Declares a Pragma plugin. This is the single entry point a plugin's bundle
+* must default-export. Stamps the compiled-against `@pragma-sh/plugin` version
+* onto the result so the host can check compatibility before loading it.
+*/
+declare function definePlugin<TConfigSchema extends ZodTypeAny = ZodTypeAny>(input: PluginDefinitionInput<TConfigSchema>): PluginDefinition<TConfigSchema>;
+export { runProviderCommand, defineUsageLimitProvider, definePlugin, defineAgent, UsageLimitsResult, UsageLimitProviderDefinition, UsageLimit, ProviderCommandOutcome, PluginDefinition, PluginContext, CLI_MISSING_STATUS, AgentModelEntry, AgentFeature, AgentDefinition };