@vsceasy/cli 0.1.0

package/templates/react/src/shared/vsceasy/codiconNames.ts

@@ -0,0 +1,196 @@
+/**
+ * AUTO-GENERATED by scripts/genCodiconTypes.ts — do not edit.
+ *
+ * Curated subset of VS Code codicon names that the CLI's icon picker offers.
+ * Used by `MenuIcon` for editor autocomplete. Any string is still accepted at
+ * runtime via the `(string & {})` fallback in define.ts.
+ *
+ * Full list: https://microsoft.github.io/vscode-codicons/dist/codicon.html
+ */
+export type CodiconName =
+  | 'account'
+  | 'add'
+  | 'archive'
+  | 'beaker'
+  | 'bell'
+  | 'bell-dot'
+  | 'book'
+  | 'bookmark'
+  | 'broadcast'
+  | 'browser'
+  | 'bug'
+  | 'calendar'
+  | 'check'
+  | 'clock'
+  | 'close'
+  | 'cloud'
+  | 'cloud-download'
+  | 'cloud-upload'
+  | 'code'
+  | 'comment'
+  | 'comment-discussion'
+  | 'compass'
+  | 'console'
+  | 'dashboard'
+  | 'database'
+  | 'debug'
+  | 'debug-alt'
+  | 'debug-breakpoint'
+  | 'debug-console'
+  | 'debug-continue'
+  | 'debug-disconnect'
+  | 'debug-pause'
+  | 'debug-restart'
+  | 'debug-start'
+  | 'debug-step-into'
+  | 'debug-step-out'
+  | 'debug-step-over'
+  | 'debug-stop'
+  | 'desktop-download'
+  | 'edit'
+  | 'error'
+  | 'export'
+  | 'extensions'
+  | 'eye'
+  | 'eye-closed'
+  | 'file'
+  | 'file-binary'
+  | 'file-code'
+  | 'file-media'
+  | 'file-pdf'
+  | 'file-symlink-directory'
+  | 'file-symlink-file'
+  | 'file-text'
+  | 'file-zip'
+  | 'files'
+  | 'filter'
+  | 'flag'
+  | 'flame'
+  | 'folder'
+  | 'folder-active'
+  | 'folder-library'
+  | 'folder-opened'
+  | 'gear'
+  | 'git-branch'
+  | 'git-commit'
+  | 'git-compare'
+  | 'git-fork'
+  | 'git-merge'
+  | 'git-pull-request'
+  | 'github'
+  | 'github-alt'
+  | 'github-inverted'
+  | 'globe'
+  | 'graph'
+  | 'heart'
+  | 'history'
+  | 'home'
+  | 'image'
+  | 'inbox'
+  | 'info'
+  | 'json'
+  | 'key'
+  | 'layout'
+  | 'layout-panel'
+  | 'layout-sidebar-left'
+  | 'layout-sidebar-right'
+  | 'lightbulb'
+  | 'link'
+  | 'link-external'
+  | 'list-flat'
+  | 'list-ordered'
+  | 'list-selection'
+  | 'list-tree'
+  | 'list-unordered'
+  | 'location'
+  | 'lock'
+  | 'mail'
+  | 'markdown'
+  | 'megaphone'
+  | 'mortar-board'
+  | 'mute'
+  | 'new-file'
+  | 'new-folder'
+  | 'note'
+  | 'notebook'
+  | 'organization'
+  | 'output'
+  | 'package'
+  | 'pencil'
+  | 'person'
+  | 'pin'
+  | 'pinned'
+  | 'play'
+  | 'play-circle'
+  | 'plug'
+  | 'preferences'
+  | 'preview'
+  | 'pulse'
+  | 'question'
+  | 'record'
+  | 'refresh'
+  | 'remove'
+  | 'replace'
+  | 'repo'
+  | 'repo-clone'
+  | 'repo-forked'
+  | 'repo-pull'
+  | 'repo-push'
+  | 'rocket'
+  | 'save'
+  | 'save-all'
+  | 'search'
+  | 'server'
+  | 'server-environment'
+  | 'server-process'
+  | 'settings'
+  | 'settings-gear'
+  | 'shield'
+  | 'source-control'
+  | 'sparkle'
+  | 'split-horizontal'
+  | 'split-vertical'
+  | 'star'
+  | 'star-empty'
+  | 'star-full'
+  | 'stop'
+  | 'stop-circle'
+  | 'symbol-array'
+  | 'symbol-boolean'
+  | 'symbol-class'
+  | 'symbol-color'
+  | 'symbol-constant'
+  | 'symbol-enum'
+  | 'symbol-event'
+  | 'symbol-field'
+  | 'symbol-function'
+  | 'symbol-interface'
+  | 'symbol-key'
+  | 'symbol-method'
+  | 'symbol-misc'
+  | 'symbol-module'
+  | 'symbol-namespace'
+  | 'symbol-numeric'
+  | 'symbol-parameter'
+  | 'symbol-property'
+  | 'symbol-snippet'
+  | 'symbol-string'
+  | 'symbol-variable'
+  | 'sync'
+  | 'tag'
+  | 'terminal'
+  | 'terminal-bash'
+  | 'terminal-cmd'
+  | 'terminal-linux'
+  | 'terminal-powershell'
+  | 'tools'
+  | 'trash'
+  | 'unlock'
+  | 'unmute'
+  | 'verified'
+  | 'video'
+  | 'wand'
+  | 'warning'
+  | 'watch'
+  | 'window'
+  | 'zap';

package/templates/react/src/shared/vsceasy/define.ts

@@ -0,0 +1,269 @@
+import type * as vscode from 'vscode';
+import type { Handlers } from './rpc';
+import type { CodiconName } from './codiconNames';
+
+export interface PanelDef<H extends Handlers = Handlers> {
+  /** Stable id. Default: file basename. Used as command suffix and webview key. */
+  id?: string;
+  /** Tab title. */
+  title: string;
+  /** Webview bundle name under dist/webview/<ui>/. Default: same as id. */
+  ui?: string;
+  /** Where to open. Default: 'active'. */
+  column?: 'active' | 'beside' | 'one' | 'two' | 'three';
+  /** Keep DOM alive when hidden. Default: true. */
+  retainContext?: boolean;
+  /** RPC handlers — receives vscode namespace + extension context. */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+  /** Optional command palette entry that opens this panel. Default: true. */
+  command?:
+    | boolean
+    | { title?: string; category?: string };
+}
+
+export interface CommandDef {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Command palette title. */
+  title: string;
+  /** Optional category prefix (default: extension displayName). */
+  category?: string;
+  /** Handler. Receives vscode + extension context. */
+  run: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, ...args: unknown[]) => unknown | Promise<unknown>;
+  /**
+   * Keyboard shortcut. String shorthand uses the same key on every platform.
+   * Object form supports `mac` override and a VS Code `when` clause.
+   * Written to package.json#contributes.keybindings by `bun run gen`.
+   */
+  keybinding?: string | KeybindingDef | (string | KeybindingDef)[];
+  /**
+   * VS Code `when` clause that controls visibility/enablement of this command
+   * in the command palette and auto-generated menu entries. Written to
+   * `contributes.commands[].enablement` and used as the default `when` on
+   * the palette menu entry by `bun run gen`.
+   *
+   * Examples: `'editorTextFocus'`, `'resourceLangId == typescript'`,
+   * `'explorerResourceIsFolder && !virtualWorkspace'`.
+   * Reference: https://code.visualstudio.com/api/references/when-clause-contexts
+   */
+  when?: string;
+}
+
+export interface KeybindingDef {
+  /** Default key combo (e.g. 'ctrl+shift+h'). */
+  key: string;
+  /** Override combo on macOS (e.g. 'cmd+shift+h'). */
+  mac?: string;
+  /** VS Code context `when` clause (e.g. 'editorTextFocus'). */
+  when?: string;
+}
+
+export function definePanel<H extends Handlers = Handlers>(def: PanelDef<H>): PanelDef<H> {
+  return def;
+}
+
+export function defineCommand(def: CommandDef): CommandDef {
+  return def;
+}
+
+// --- Menus (Activity Bar + Tree View) ---
+
+export type MenuIcon =
+  | CodiconName                                // known codicon (autocompletes)
+  | (string & {})                              // any codicon name (escape hatch, keeps autocomplete)
+  | { path: string }                           // single SVG path relative to project root
+  | { light: string; dark: string };           // theme-aware SVG paths
+
+export type { CodiconName };
+
+export interface MenuItem {
+  /** Display label. */
+  label: string;
+  /** Optional icon (codicon name or asset path). */
+  icon?: MenuIcon;
+  /** Optional tooltip / hover description. */
+  description?: string;
+  /** Open a panel by id (file basename in src/panels/). */
+  panel?: string;
+  /** Execute a command by id (file basename in src/commands/). */
+  command?: string;
+  /** Open an external URL in the user's browser. */
+  url?: string;
+  /** Run an arbitrary handler (full vscode access). */
+  run?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => unknown | Promise<unknown>;
+  /** Nested items — renders as a collapsible group. */
+  children?: MenuItem[];
+  /** Initial collapsed state for groups. Default: 'expanded'. */
+  collapsed?: 'expanded' | 'collapsed';
+}
+
+export interface MenuDef {
+  /** Stable id. Default: file basename. Becomes the view container id. */
+  id?: string;
+  /** Title shown at the top of the sidebar panel and as the activity bar tooltip. */
+  title: string;
+  /** Activity bar icon. Codicon string OR SVG path(s). */
+  icon: MenuIcon;
+  /** Items shown in the tree view. */
+  items: MenuItem[];
+}
+
+export function defineMenu(def: MenuDef): MenuDef {
+  return def;
+}
+
+// --- Webview Views (inline sidebar sections) ---
+
+export interface SubpanelDef<H extends Handlers = Handlers> {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Section header shown in the sidebar. */
+  title: string;
+  /** Menu (activity bar container) this view lives in — basename in src/menus/. */
+  menu: string;
+  /** Webview bundle name under dist/webview/<ui>/. Default: same as id. */
+  ui?: string;
+  /** Keep DOM alive when hidden. Default: true. */
+  retainContext?: boolean;
+  /** RPC handlers — receives vscode namespace + extension context. */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => H;
+}
+
+export function defineSubpanel<H extends Handlers = Handlers>(def: SubpanelDef<H>): SubpanelDef<H> {
+  return def;
+}
+
+// --- Status Bar items ---
+
+export interface StatusBarDef {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Display text. May include `$(codicon)` syntax. */
+  text: string;
+  /** Tooltip on hover. */
+  tooltip?: string;
+  /** Optional codicon, prepended as `$(icon) text` when both present. */
+  icon?: CodiconName | (string & {});
+  /** Bar side. Default: 'left'. */
+  alignment?: 'left' | 'right';
+  /** Higher = leftmost on its side. Default: 100. */
+  priority?: number;
+  /** Command id to run on click (basename in src/commands/, or full vscode command id). */
+  command?: string;
+  /** Open a panel by id (basename in src/panels/). Takes precedence over `command` when set. */
+  panel?: string;
+  /** Background color theme key (e.g. 'statusBarItem.warningBackground'). */
+  backgroundColor?: string;
+  /**
+   * Rich markdown tooltip (overrides `tooltip`). Supports command links
+   * (`[text](command:ext.foo)`), codicons (`$(rocket)`), and HTML.
+   * Rendered on hover. Mimics Copilot/GitLens popup style.
+   */
+  tooltipMarkdown?: string;
+  /**
+   * Open a popup menu on click instead of running a single command/panel.
+   * Each item runs its `command`, opens its `panel`, or opens its `url`.
+   */
+  menu?: StatusBarMenuItem[];
+}
+
+export interface StatusBarMenuItem {
+  /** Display label. May include `$(codicon)`. */
+  label: string;
+  /** Inline secondary text. */
+  description?: string;
+  /** Detail line (smaller, below). */
+  detail?: string;
+  /** Command id (basename in src/commands/) or full vscode command id. */
+  command?: string;
+  /** Panel id (basename in src/panels/). */
+  panel?: string;
+  /** External URL. */
+  url?: string;
+}
+
+export function defineStatusBar(def: StatusBarDef): StatusBarDef {
+  return def;
+}
+
+// --- Tree Views (data-driven) ---
+
+export interface TreeNode {
+  /** Display label. */
+  label: string;
+  /** Stable id, defaults to label. Used for reveal/select. */
+  id?: string;
+  /** Optional icon. */
+  icon?: MenuIcon;
+  /** Tooltip on hover. */
+  tooltip?: string;
+  /** Right-aligned description text. */
+  description?: string;
+  /** Context value used by `view/item/context` menu entries. */
+  contextValue?: string;
+  /** Initial state when this node has children. Default: 'collapsed'. */
+  collapsed?: 'expanded' | 'collapsed';
+  /** Eagerly provided children. If omitted, getChildren(this) is called lazily. */
+  children?: TreeNode[];
+  /** Click handler — run an arbitrary callback when the node is selected. */
+  run?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => unknown | Promise<unknown>;
+  /** Click → open a panel by id. */
+  panel?: string;
+  /** Click → run a command by id. */
+  command?: string;
+}
+
+export interface TreeViewDef {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Sidebar section header. */
+  title: string;
+  /** Activity bar container id (menu basename in src/menus/). */
+  menu: string;
+  /** Show "Collapse All" button. Default: true. */
+  showCollapseAll?: boolean;
+  /** Initial / refreshed nodes. Called on mount and whenever the view is refreshed. */
+  getChildren: (
+    parent: TreeNode | undefined,
+    vscode: typeof import('vscode'),
+    ctx: vscode.ExtensionContext,
+  ) => TreeNode[] | Promise<TreeNode[]>;
+}
+
+export function defineTreeView(def: TreeViewDef): TreeViewDef {
+  return def;
+}
+
+// --- Jobs (recurring / event-triggered tasks) ---
+
+export type JobSchedule =
+  /** Run every <interval>. Accepts ms number or duration string: "30s", "5m", "2h", "1d". */
+  | { every: string | number; runOnStart?: boolean }
+  /** Run at HH:MM local time, every day. */
+  | { dailyAt: string }
+  /** Run on a VS Code lifecycle event. */
+  | { on: 'startup' | 'saveDocument' | 'openDocument' | 'changeActiveEditor' | 'changeConfig' }
+  /** Run on filesystem changes matching a glob (relative to workspace). */
+  | { onFile: string };
+
+export interface JobDef {
+  /** Stable id. Default: file basename. */
+  id?: string;
+  /** Display label (used in logs + opt. status bar). */
+  title: string;
+  /** When to run. */
+  schedule: JobSchedule;
+  /**
+   * Skip if last successful run was less than this many ms ago. Stored in
+   * `context.globalState` under `vsceasy.job.<id>.lastRun`. Useful for jobs
+   * that should at most run every N hours regardless of how often the
+   * trigger fires.
+   */
+  minIntervalMs?: number;
+  /** The actual work. Errors are caught and logged — they never crash the host. */
+  run: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext) => unknown | Promise<unknown>;
+}
+
+export function defineJob(def: JobDef): JobDef {
+  return def;
+}

package/templates/react/src/shared/vsceasy/index.ts

@@ -0,0 +1,13 @@
+export { definePanel, defineCommand, defineMenu, defineStatusBar, defineSubpanel, defineTreeView, defineJob } from './define';
+export type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName } from './define';
+export { bootstrap } from './bootstrap';
+export type { Registry, BootstrapOptions, ActivateHook } from './bootstrap';
+export {
+  createRpcClient,
+  createRpcServer,
+  webviewTransport,
+  vscodeApiTransport,
+  connectWebview,
+  webviewState,
+} from './rpc';
+export type { Transport, RpcClient, Handlers, RpcClientOptions, WebviewApi } from './rpc';

package/templates/react/src/shared/vsceasy/rpc.ts

@@ -0,0 +1,214 @@
+// Typed RPC bridge — webview <-> extension.
+// Used by both sides. Transport-agnostic core + thin adapters.
+
+export type RpcMessage =
+  | { id: string; kind: 'call'; method: string; args: unknown[] }
+  | { id: string; kind: 'result'; ok: true; value: unknown }
+  | { id: string; kind: 'result'; ok: false; error: { message: string; stack?: string } }
+  | { kind: 'event'; topic: string; payload: unknown };
+
+export interface Transport {
+  send(msg: RpcMessage): void;
+  onMessage(handler: (msg: RpcMessage) => void): () => void;
+}
+
+// --- Server (extension side) ---
+
+/**
+ * Loose constraint: an interface with method members. Using `object` (instead
+ * of a Record with index signature) lets user-declared interfaces satisfy the
+ * constraint without forcing them to declare `[k: string]: any`.
+ */
+export type Handlers = object;
+
+export function createRpcServer<H extends Handlers>(transport: Transport, handlers: H) {
+  const off = transport.onMessage(async (msg) => {
+    if (msg.kind !== 'call') return;
+    const fn = (handlers as Record<string, (...args: any[]) => any>)[msg.method];
+    if (!fn) {
+      transport.send({
+        id: msg.id,
+        kind: 'result',
+        ok: false,
+        error: { message: `Unknown RPC method: ${msg.method}` },
+      });
+      return;
+    }
+    try {
+      const value = await fn(...msg.args);
+      transport.send({ id: msg.id, kind: 'result', ok: true, value });
+    } catch (err: any) {
+      transport.send({
+        id: msg.id,
+        kind: 'result',
+        ok: false,
+        error: { message: String(err?.message ?? err), stack: err?.stack },
+      });
+    }
+  });
+
+  return {
+    emit(topic: string, payload: unknown) {
+      transport.send({ kind: 'event', topic, payload });
+    },
+    dispose: off,
+  };
+}
+
+// --- Client (webview side) ---
+
+export type RpcClient<H extends Handlers> = {
+  [K in keyof H]: H[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<Awaited<R>>
+    : never;
+} & {
+  on(topic: string, handler: (payload: any) => void): () => void;
+};
+
+export interface RpcClientOptions {
+  /**
+   * Max wait (ms) for a call's reply before rejecting with a timeout error.
+   * Prevents hangs when the extension host reloads mid-flight during `bun run dev`.
+   * Default: 15000. Set to 0 to disable.
+   */
+  callTimeoutMs?: number;
+}
+
+export function createRpcClient<H extends Handlers>(
+  transport: Transport,
+  opts: RpcClientOptions = {},
+): RpcClient<H> {
+  const callTimeoutMs = opts.callTimeoutMs ?? 15000;
+  const pending = new Map<string, { resolve: (v: any) => void; reject: (e: any) => void; timer?: ReturnType<typeof setTimeout> }>();
+  const listeners = new Map<string, Set<(p: any) => void>>();
+
+  transport.onMessage((msg) => {
+    if (msg.kind === 'result') {
+      const p = pending.get(msg.id);
+      if (!p) return;
+      pending.delete(msg.id);
+      if (p.timer) clearTimeout(p.timer);
+      if (msg.ok) p.resolve(msg.value);
+      else p.reject(Object.assign(new Error(msg.error.message), { stack: msg.error.stack }));
+    } else if (msg.kind === 'event') {
+      listeners.get(msg.topic)?.forEach((l) => l(msg.payload));
+    }
+  });
+
+  let counter = 0;
+  const newId = () => `r${++counter}_${Date.now()}`;
+
+  const proxy = new Proxy({} as any, {
+    get(_t, prop: string) {
+      if (prop === 'on') {
+        return (topic: string, handler: (p: any) => void) => {
+          let set = listeners.get(topic);
+          if (!set) listeners.set(topic, (set = new Set()));
+          set.add(handler);
+          return () => set!.delete(handler);
+        };
+      }
+      return (...args: unknown[]) =>
+        new Promise((resolve, reject) => {
+          const id = newId();
+          const entry: { resolve: (v: any) => void; reject: (e: any) => void; timer?: ReturnType<typeof setTimeout> } = { resolve, reject };
+          if (callTimeoutMs > 0) {
+            entry.timer = setTimeout(() => {
+              if (pending.delete(id)) {
+                reject(new Error(`RPC \`${prop}\` timed out after ${callTimeoutMs}ms (extension host reloaded?)`));
+              }
+            }, callTimeoutMs);
+          }
+          pending.set(id, entry);
+          try {
+            transport.send({ id, kind: 'call', method: prop, args });
+          } catch (err) {
+            pending.delete(id);
+            if (entry.timer) clearTimeout(entry.timer);
+            reject(err);
+          }
+        });
+    },
+  });
+
+  return proxy as RpcClient<H>;
+}
+
+// --- Transports ---
+
+export function webviewTransport(webview: { postMessage(m: any): any; onDidReceiveMessage: any }): Transport {
+  return {
+    send: (m) => webview.postMessage(m),
+    onMessage: (h) => {
+      const sub = webview.onDidReceiveMessage((m: RpcMessage) => h(m));
+      return () => sub.dispose();
+    },
+  };
+}
+
+export function vscodeApiTransport(vscode: { postMessage(m: any): void }): Transport {
+  return {
+    send: (m) => vscode.postMessage(m),
+    onMessage: (h) => {
+      const listener = (e: MessageEvent) => h(e.data as RpcMessage);
+      window.addEventListener('message', listener);
+      return () => window.removeEventListener('message', listener);
+    },
+  };
+}
+
+declare global {
+  function acquireVsCodeApi(): WebviewApi;
+}
+
+export interface WebviewApi {
+  postMessage(m: any): void;
+  getState(): unknown;
+  setState<T>(s: T): T;
+}
+
+let _cachedVscode: WebviewApi | null = null;
+function vscodeApi(): WebviewApi {
+  // acquireVsCodeApi() may only be called once per webview lifetime.
+  if (_cachedVscode) return _cachedVscode;
+  return (_cachedVscode = acquireVsCodeApi());
+}
+
+/** One-liner for webview: returns a typed RPC client. */
+export function connectWebview<H extends Handlers>(opts?: RpcClientOptions): RpcClient<H> {
+  return createRpcClient<H>(vscodeApiTransport(vscodeApi()), opts);
+}
+
+/**
+ * Typed `vscode.getState() / setState()` wrapper for webviews. State survives
+ * panel hide/show, host reloads triggered by `retainContextWhenHidden`, and
+ * is the recommended way to persist scroll positions, form data, and selection.
+ *
+ * Usage:
+ *   const state = webviewState<{ query: string }>({ query: '' });
+ *   state.set({ query: 'foo' });
+ *   const { query } = state.get();
+ */
+export function webviewState<T>(defaults: T): {
+  get(): T;
+  set(next: T | ((prev: T) => T)): T;
+  patch(partial: Partial<T>): T;
+} {
+  const api = vscodeApi();
+  const init = (): T => ({ ...defaults, ...((api.getState() as T | undefined) ?? {}) });
+  return {
+    get: init,
+    set(next) {
+      const current = init();
+      const value = typeof next === 'function' ? (next as (p: T) => T)(current) : next;
+      api.setState(value);
+      return value;
+    },
+    patch(partial) {
+      const current = init();
+      const value = { ...current, ...partial };
+      api.setState(value);
+      return value;
+    },
+  };
+}