@vsceasy/cli 0.1.0

package/dist/lib/upgrade.d.ts

@@ -0,0 +1,22 @@
+export type UpgradeStatus = 'in-sync' | 'would-create' | 'would-update' | 'created' | 'updated' | 'missing-source';
+export interface FileChange {
+    path: string;
+    status: UpgradeStatus;
+}
+export interface UpgradeOptions {
+    projectRoot: string;
+    /** Bundled templates root (output of findTemplatesRoot). */
+    templatesRoot: string;
+    /** UI variant subfolder. Default 'react'. */
+    ui?: string;
+    /** Apply changes. Default false (dry-run). */
+    apply?: boolean;
+    /** Run `bun run gen` after apply. Default true when apply, ignored on dry-run. */
+    runGen?: boolean;
+}
+export interface UpgradeResult {
+    changes: FileChange[];
+    applied: boolean;
+    genRan: boolean;
+}
+export declare function upgrade(opts: UpgradeOptions): UpgradeResult;

package/dist/lib/validate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validate a generator identifier — camelCase, starts with a letter.
+ * Throws with a clear message naming the field that failed.
+ */
+export declare function assertId(field: string, value: string): string;
+/**
+ * Throw a friendly error if `target` already exists. Quotes the project-relative path.
+ */
+export declare function assertNoOverwrite(projectRoot: string, target: string, kind: string): void;
+/**
+ * Throw if a referenced sibling resource (panel, menu, command) is missing on disk.
+ * Error message lists the existing siblings so the user can pick one without re-running.
+ */
+export declare function assertSiblingExists(projectRoot: string, kind: 'panel' | 'menu' | 'command' | 'subpanel', id: string): string;

package/dist/lib/wizard/run.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Interactive wizard. Detects whether the cwd is inside a vsceasy project:
+ * outside → guides `create`; inside → menus the common generators and delegates
+ * to the same lib functions the CLI commands use. Anything not wired here is
+ * surfaced as the exact `vsceasy …` command to run.
+ *
+ * Designed for `findTemplatesRoot(__dirname)` to resolve the bundled templates
+ * whether running from src/ or dist/.
+ */
+export declare function runWizard(opts?: {
+    templatesRoot?: string;
+    cwd?: string;
+}): Promise<void>;

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@vsceasy/cli",
+  "version": "0.1.0",
+  "description": "Build VS Code extensions fast — React UI + typed RPC bridge between extension and webview + file-based routing for panels, commands, menus, tree views, and subpanels.",
+  "main": "dist/index.js",
+  "scripts": {
+    "test": "bun test ./src/tests",
+    "gen:types": "bun scripts/genCodiconTypes.ts",
+    "sync:runtime": "bun scripts/syncRuntime.ts",
+    "build:runtime": "cd packages/vsceasy-runtime && bun install && bunx tsc",
+    "build": "bun run gen:types && bun run sync:runtime && bun run build:runtime && tsc --emitDeclarationOnly && bun build ./src/index.ts ./src/bin/cli.ts --target=node --outdir ./dist --format cjs",
+    "build:test": "bun build ./src/tests/*.ts --target=node --outdir dist/tests --format cjs",
+    "prepublishOnly": "bun run build",
+    "start": "bun run src/cli.ts",
+    "lint": "eslint 'src/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' --fix",
+    "format": "prettier --write 'src/**/*.{ts,tsx,json,md}' '*.md'",
+    "format:check": "prettier --check 'src/**/*.{ts,tsx,json,md}' '*.md'",
+    "release:patch": "npm version patch -m 'chore(release): %s'",
+    "release:minor": "npm version minor -m 'chore(release): %s'",
+    "release:major": "npm version major -m 'chore(release): %s'"
+  },
+  "keywords": [
+    "vscode",
+    "vscode-extension",
+    "framework",
+    "scaffold",
+    "cli",
+    "react",
+    "webview",
+    "rpc"
+  ],
+  "author": "Jairo <jairofg12@gmail.com>",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "vsceasy": "dist/bin/cli.js"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "templates/**/*",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "!src/tests/**/*"
+  ],
+  "engines": {
+    "node": ">=24.11.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/vscode": "^1.43.2",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.3.0",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@ideascol/cli-maker": "^2.2.2"
+  }
+}

package/templates/_generators/command/command.ts.tpl

@@ -0,0 +1,8 @@
+import { defineCommand } from '../shared/vsceasy';
+
+export default defineCommand({
+  title: '{{title}}',{{categoryLine}}{{keybindingLine}}{{whenLine}}
+  run: (vscode) => {
+    vscode.window.showInformationMessage('{{title}} ran');
+  },
+});

package/templates/_generators/components/Button.tsx.tpl

@@ -0,0 +1,12 @@
+import React from 'react';
+
+type Variant = 'primary' | 'secondary';
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: Variant;
+}
+
+/** Theme-aware button using VS Code button tokens. */
+export function Button({ variant = 'primary', className = '', ...rest }: ButtonProps) {
+  return <button className={`vx-btn vx-btn--${variant} ${className}`.trim()} {...rest} />;
+}

package/templates/_generators/components/Card.tsx.tpl

@@ -0,0 +1,22 @@
+import React from 'react';
+
+export interface CardProps {
+  title?: string;
+  actions?: React.ReactNode;
+  children: React.ReactNode;
+}
+
+/** Bordered surface for grouping content, with an optional title + actions row. */
+export function Card({ title, actions, children }: CardProps) {
+  return (
+    <section className="vx-card">
+      {(title || actions) && (
+        <header className="vx-card__head">
+          {title ? <h2 className="vx-card__title">{title}</h2> : <span />}
+          {actions ? <div className="vx-card__actions">{actions}</div> : null}
+        </header>
+      )}
+      <div className="vx-card__body">{children}</div>
+    </section>
+  );
+}

package/templates/_generators/components/Field.tsx.tpl

@@ -0,0 +1,20 @@
+import React from 'react';
+
+export interface FieldProps {
+  label: string;
+  htmlFor?: string;
+  hint?: string;
+  error?: string;
+  children: React.ReactNode;
+}
+
+/** Labeled form field wrapper with optional hint / error text. */
+export function Field({ label, htmlFor, hint, error, children }: FieldProps) {
+  return (
+    <div className="vx-field">
+      <label className="vx-field__label" htmlFor={htmlFor}>{label}</label>
+      {children}
+      {error ? <span className="vx-field__error">{error}</span> : hint ? <span className="vx-field__hint">{hint}</span> : null}
+    </div>
+  );
+}

package/templates/_generators/components/Input.tsx.tpl

@@ -0,0 +1,10 @@
+import React from 'react';
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {}
+
+/** Theme-aware text input using VS Code input tokens. */
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  function Input({ className = '', ...rest }, ref) {
+    return <input ref={ref} className={`vx-input ${className}`.trim()} {...rest} />;
+  },
+);

package/templates/_generators/components/List.tsx.tpl

@@ -0,0 +1,29 @@
+import React from 'react';
+
+export interface ListProps<T> {
+  items: T[];
+  getKey: (item: T, index: number) => string | number;
+  renderItem: (item: T, index: number) => React.ReactNode;
+  onSelect?: (item: T, index: number) => void;
+  empty?: React.ReactNode;
+}
+
+/** Selectable, theme-aware list. Rows highlight on hover and on selection. */
+export function List<T>({ items, getKey, renderItem, onSelect, empty }: ListProps<T>) {
+  if (items.length === 0) {
+    return <div className="vx-list__empty">{empty ?? 'Nothing here yet.'}</div>;
+  }
+  return (
+    <ul className="vx-list" role="list">
+      {items.map((item, i) => (
+        <li
+          key={getKey(item, i)}
+          className={`vx-list__row${onSelect ? ' vx-list__row--clickable' : ''}`}
+          onClick={onSelect ? () => onSelect(item, i) : undefined}
+        >
+          {renderItem(item, i)}
+        </li>
+      ))}
+    </ul>
+  );
+}

package/templates/_generators/components/components.css.tpl

@@ -0,0 +1,66 @@
+.vx-btn {
+  font: inherit;
+  padding: 0.35rem 0.85rem;
+  border-radius: 2px;
+  border: 1px solid transparent;
+  cursor: pointer;
+}
+.vx-btn:focus-visible { outline: 1px solid var(--vscode-focusBorder); outline-offset: 2px; }
+.vx-btn:disabled { opacity: 0.5; cursor: default; }
+.vx-btn--primary {
+  color: var(--vscode-button-foreground);
+  background: var(--vscode-button-background);
+}
+.vx-btn--primary:hover:not(:disabled) { background: var(--vscode-button-hoverBackground); }
+.vx-btn--secondary {
+  color: var(--vscode-button-secondaryForeground, var(--vscode-foreground));
+  background: var(--vscode-button-secondaryBackground, transparent);
+  border-color: var(--vscode-button-border, var(--vscode-input-border, #555));
+}
+.vx-btn--secondary:hover:not(:disabled) { background: var(--vscode-button-secondaryHoverBackground, var(--vscode-list-hoverBackground)); }
+
+.vx-input {
+  font: inherit;
+  width: 100%;
+  box-sizing: border-box;
+  padding: 0.35rem 0.5rem;
+  border-radius: 2px;
+  color: var(--vscode-input-foreground);
+  background: var(--vscode-input-background);
+  border: 1px solid var(--vscode-input-border, #555);
+}
+.vx-input:focus-visible { outline: 1px solid var(--vscode-focusBorder); outline-offset: -1px; }
+.vx-input::placeholder { color: var(--vscode-input-placeholderForeground); }
+
+.vx-field { display: flex; flex-direction: column; gap: 0.25rem; margin-bottom: 0.75rem; }
+.vx-field__label { font-size: 0.85em; color: var(--vscode-foreground); }
+.vx-field__hint { font-size: 0.8em; color: var(--vscode-descriptionForeground); }
+.vx-field__error { font-size: 0.8em; color: var(--vscode-errorForeground); }
+
+.vx-card {
+  border: 1px solid var(--vscode-panel-border, var(--vscode-input-border, #555));
+  border-radius: 4px;
+  margin-bottom: 0.75rem;
+  background: var(--vscode-editorWidget-background, transparent);
+}
+.vx-card__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid var(--vscode-panel-border, var(--vscode-input-border, #555));
+}
+.vx-card__title { font-size: 1em; font-weight: 600; margin: 0; }
+.vx-card__actions { display: flex; gap: 0.5rem; }
+.vx-card__body { padding: 0.75rem; }
+
+.vx-list { list-style: none; margin: 0; padding: 0; }
+.vx-list__row {
+  padding: 0.4rem 0.6rem;
+  border-radius: 2px;
+  line-height: 1.5;
+}
+.vx-list__row--clickable { cursor: pointer; }
+.vx-list__row--clickable:hover { background: var(--vscode-list-hoverBackground); }
+.vx-list__empty { color: var(--vscode-descriptionForeground); padding: 0.6rem; }

package/templates/_generators/components/index.ts.tpl

@@ -0,0 +1,10 @@
+export { Button } from './Button';
+export type { ButtonProps } from './Button';
+export { Input } from './Input';
+export type { InputProps } from './Input';
+export { Field } from './Field';
+export type { FieldProps } from './Field';
+export { Card } from './Card';
+export type { CardProps } from './Card';
+export { List } from './List';
+export type { ListProps } from './List';

package/templates/_generators/crud/formApp.tsx.tpl

@@ -0,0 +1,83 @@
+import { useCallback, useEffect, useState } from 'react';
+import { connectWebview } from '../../../shared/vsceasy/client';
+import type { {{Name}}FormApi } from '../../../shared/api';
+import type { {{Name}} } from '../../../models/{{Name}}';
+
+const api = connectWebview<{{Name}}FormApi>();
+
+type FormState = Partial<{{Name}}>;
+
+const emptyForm: FormState = {{emptyFormLiteral}};
+
+export function App() {
+  const [form, setForm] = useState<FormState>(emptyForm);
+  const [editingId, setEditingId] = useState<{{Name}}['{{primaryKey}}'] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  const load = useCallback(async () => {
+    // The list stashes the row id before revealing this panel. Pull it (the host
+    // clears it after handing it over) and pre-fill the form for editing.
+    const id = await api.pendingId();
+    if (id == null || id === '') {
+      setForm(emptyForm);
+      setEditingId(null);
+      return;
+    }
+    const row = await api.get(id);
+    if (row) {
+      setForm(row);
+      setEditingId(row.{{primaryKey}});
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+    // Webviews retain state when hidden, so re-load whenever the panel is
+    // revealed — the list may have asked to edit a different row.
+    const onFocus = () => { void load(); };
+    const onVisible = () => { if (document.visibilityState === 'visible') void load(); };
+    window.addEventListener('focus', onFocus);
+    document.addEventListener('visibilitychange', onVisible);
+    return () => {
+      window.removeEventListener('focus', onFocus);
+      document.removeEventListener('visibilitychange', onVisible);
+    };
+  }, [load]);
+
+  const onChange = <K extends keyof FormState>(k: K, v: FormState[K]) => {
+    setForm((f) => ({ ...f, [k]: v }));
+  };
+
+  const onSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSaving(true);
+    setError(null);
+    try {
+      const wasNew = editingId == null;
+      await api.save(form as {{Name}});
+      // After creating a new row, reset for the next entry. After an edit, keep
+      // the row loaded so further tweaks are possible.
+      if (wasNew) {
+        setForm(emptyForm);
+        setEditingId(null);
+      }
+    } catch (err: any) {
+      setError(String(err?.message ?? err));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <form onSubmit={onSubmit} style={{ padding: 16, display: 'grid', gap: 12, color: 'var(--vscode-foreground)' }}>
+      <h2 style={{ margin: 0 }}>{editingId ? 'Edit {{title}}' : 'New {{title}}'}</h2>
+{{formFieldInputs}}
+      {error && <div style={{ color: 'var(--vscode-errorForeground)' }}>{error}</div>}
+      <div style={{ display: 'flex', gap: 8 }}>
+        <button type="submit" disabled={saving}>{saving ? 'Saving…' : 'Save'}</button>
+        <button type="button" onClick={() => { setForm(emptyForm); setEditingId(null); }}>Reset</button>
+      </div>
+    </form>
+  );
+}

package/templates/_generators/crud/formNav.ts.tpl

@@ -0,0 +1,19 @@
+/**
+ * In-memory hand-off for "open the {{Name}} form to edit row X". The list panel
+ * sets the pending id before revealing the form; the form reads (and clears) it
+ * on mount. Lives in the extension host, shared across the two panel modules.
+ */
+type {{Name}}Id = unknown;
+
+let pendingId: {{Name}}Id | null = null;
+
+export function setPending{{Name}}Id(id: {{Name}}Id | null): void {
+  pendingId = id ?? null;
+}
+
+/** Returns the pending id once, then clears it. */
+export function takePending{{Name}}Id(): {{Name}}Id | null {
+  const v = pendingId;
+  pendingId = null;
+  return v;
+}

package/templates/_generators/crud/formPanel.ts.tpl

@@ -0,0 +1,32 @@
+import { definePanel } from '../shared/vsceasy';
+import { {{Name}}Service } from '../services/{{Name}}Service';
+import { takePending{{Name}}Id } from '../services/{{name}}FormNav';
+import type { {{Name}}FormApi } from '../shared/api';
+import type { {{Name}} } from '../models/{{Name}}';
+
+export default definePanel<{{Name}}FormApi>({
+  title: '{{title}}',
+  column: 'beside',
+  command: { title: '{{title}}: New / Edit' },
+  rpc: (vscode) => ({
+    async pendingId() {
+      // Consumed once by the webview on mount to decide edit vs new.
+      return (takePending{{Name}}Id() as {{Name}}['{{primaryKey}}'] | null) ?? null;
+    },
+    async get(id) {
+      if (!id) return null;
+      return {{Name}}Service.get(id as {{Name}}['{{primaryKey}}']);
+    },
+    async save(row) {
+      const saved = await {{Name}}Service.save(row);
+      void vscode.window.showInformationMessage(`{{title}} saved (${String(saved.{{primaryKey}})})`);
+      // Reveal the list so the new/edited row shows. Revealing fires the list
+      // webview's focus/visibility listener, which reloads it.
+      void vscode.commands.executeCommand('{{prefix}}.open{{Plural}}List');
+      return saved;
+    },
+    async cancel() {
+      // No-op — webview closes itself.
+    },
+  }),
+});

package/templates/_generators/crud/listApp.tsx.tpl

@@ -0,0 +1,84 @@
+import { useEffect, useState, useCallback } from 'react';
+import { connectWebview } from '../../../shared/vsceasy/client';
+import type { {{Plural}}ListApi } from '../../../shared/api';
+import type { {{Name}} } from '../../../models/{{Name}}';
+
+const api = connectWebview<{{Plural}}ListApi>();
+
+export function App() {
+  const [rows, setRows] = useState<{{Name}}[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const reload = useCallback(async () => {
+    setLoading(true);
+    try {
+      setRows(await api.list());
+      setError(null);
+    } catch (e: any) {
+      setError(String(e?.message ?? e));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void reload();
+    // Webviews keep their state when hidden (retainContextWhenHidden), so the
+    // mount effect won't re-run when the panel is revealed again. Reload when the
+    // webview regains focus/visibility so edits made in another panel show up.
+    const onFocus = () => { void reload(); };
+    const onVisible = () => { if (document.visibilityState === 'visible') void reload(); };
+    window.addEventListener('focus', onFocus);
+    document.addEventListener('visibilitychange', onVisible);
+    return () => {
+      window.removeEventListener('focus', onFocus);
+      document.removeEventListener('visibilitychange', onVisible);
+    };
+  }, [reload]);
+
+  const onDelete = async (id: {{Name}}['{{primaryKey}}']) => {
+    // `confirm()` is disabled inside VS Code webviews — confirmation happens in
+    // the host (the `delete` RPC handler shows a modal). Just call + reload.
+    await api.delete(id);
+    await reload();
+  };
+
+  return (
+    <div style={{ padding: 16, color: 'var(--vscode-foreground)' }}>
+      <header style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 12 }}>
+        <h2 style={{ margin: 0 }}>{{title}}</h2>
+        <div style={{ display: 'flex', gap: 8 }}>
+          <button onClick={() => void reload()} disabled={loading}>{loading ? 'Loading…' : 'Refresh'}</button>
+          <button onClick={() => api.openForm()}>+ New</button>
+        </div>
+      </header>
+
+      {error && <div style={{ color: 'var(--vscode-errorForeground)', marginBottom: 8 }}>{error}</div>}
+      {loading ? <div>Loading…</div> : (
+        <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+          <thead>
+            <tr style={{ textAlign: 'left', borderBottom: '1px solid var(--vscode-panel-border)' }}>
+{{listHeaderCells}}
+              <th style={{ padding: '6px 8px' }}></th>
+            </tr>
+          </thead>
+          <tbody>
+            {rows.length === 0 && (
+              <tr><td colSpan={{{listColCount}}} style={{ padding: 16, opacity: 0.6 }}>No rows yet.</td></tr>
+            )}
+            {rows.map((r) => (
+              <tr key={String(r.{{primaryKey}})} style={{ borderBottom: '1px solid var(--vscode-panel-border)' }}>
+{{listBodyCells}}
+                <td style={{ padding: '6px 8px', whiteSpace: 'nowrap' }}>
+                  <button onClick={() => api.openForm(r.{{primaryKey}})}>Edit</button>{' '}
+                  <button onClick={() => onDelete(r.{{primaryKey}})}>Delete</button>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </div>
+  );
+}

package/templates/_generators/crud/listPanel.ts.tpl

@@ -0,0 +1,30 @@
+import { definePanel } from '../shared/vsceasy';
+import { {{Name}}Service } from '../services/{{Name}}Service';
+import { setPending{{Name}}Id } from '../services/{{name}}FormNav';
+import type { {{Plural}}ListApi } from '../shared/api';
+
+export default definePanel<{{Plural}}ListApi>({
+  title: '{{title}}',
+  column: 'active',
+  command: { title: '{{title}}: List' },
+  rpc: (vscode) => ({
+    async list() {
+      return {{Name}}Service.list();
+    },
+    async delete(id) {
+      // Confirm in the host — browser confirm() is disabled in webviews.
+      const pick = await vscode.window.showWarningMessage(
+        `Delete {{title}} "${String(id)}"?`,
+        { modal: true },
+        'Delete',
+      );
+      if (pick !== 'Delete') return false;
+      return {{Name}}Service.delete(id);
+    },
+    async openForm(id) {
+      // Stash the id so the form can pre-load it on mount, then reveal the form.
+      setPending{{Name}}Id(id ?? null);
+      await vscode.commands.executeCommand('{{prefix}}.open{{Name}}Form', id ?? null);
+    },
+  }),
+});

package/templates/_generators/crud/main.tsx.tpl

@@ -0,0 +1,6 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import '../../styles.css';
+
+createRoot(document.getElementById('root')!).render(<App />);

package/templates/_generators/crud/service.ts.tpl

@@ -0,0 +1,27 @@
+import { {{Plural}}Repo } from '../models/{{Name}}';
+import type { {{Name}} } from '../models/{{Name}}';
+
+/**
+ * {{Name}} service — business logic between RPC handlers and the repo.
+ * Put validation, derivations (e.g. timestamps), and cross-entity work here.
+ */
+export const {{Name}}Service = {
+  async list(): Promise<{{Name}}[]> {
+    return {{Plural}}Repo().findMany({ orderBy: '{{primaryKey}}:desc' });
+  },
+
+  async get(id: {{Name}}['{{primaryKey}}']): Promise<{{Name}} | null> {
+    return {{Plural}}Repo().findById(id);
+  },
+
+  async save(row: {{Name}}): Promise<{{Name}}> {
+    if (!row.{{primaryKey}}) {
+      throw new Error('{{Name}}: {{primaryKey}} is required');
+    }
+    return {{Plural}}Repo().upsert(row);
+  },
+
+  async delete(id: {{Name}}['{{primaryKey}}']): Promise<boolean> {
+    return {{Plural}}Repo().delete(id);
+  },
+};