@vsceasy/cli 0.1.7 → 0.1.9

package/dist/lib/model/parseFields.d.ts

@@ -1,4 +1,4 @@
-import type { ModelField } from './add';
+import type { ModelField, FieldRelation } from './add';
 /**
  * Parse a compact model field spec into `ModelField[]`.
  *
@@ -7,8 +7,14 @@ import type { ModelField } from './add';
  *   `!` after type → primaryKey
  *   `@` after type → indexed
  *
- * Example: `id:string!,name:string,email?:string@,score:number`
+ * Relations use `name:ref(Model)` or `name:ref(Model, label=field)`:
+ *   category:ref(Category)             → FK categoryId, dropdown of Category rows
+ *   category:ref(Category, label=name) → show Category.name in the dropdown
+ *
+ * Example: `id:string!,name:string,email?:string@,category:ref(Category)`
  */
 export declare function parseFieldsSpec(spec: string): ModelField[];
-/** Parse a single `name[?]:type[!][@]` line. Throws on malformed input. */
+/** Parse a single `name[?]:type[!][@]` line (or `name:ref(Model)`). Throws on malformed input. */
 export declare function parseFieldLine(raw: string): ModelField;
+/** Parse `ref(Model)` / `ref(Model, label=field)`. Returns null when not a ref. */
+export declare function parseRef(type: string): FieldRelation | null;

package/dist/lib/store/add.d.ts

@@ -0,0 +1,14 @@
+export type StoreType = 'number' | 'string' | 'boolean' | 'json';
+export interface AddStoreOptions {
+    name: string;
+    /** Value type. Default: 'number'. */
+    type?: StoreType;
+    /** Raw initial value expression. Defaults per type (0 / '' / false / null). */
+    initial?: string;
+    projectRoot: string;
+    templatesRoot: string;
+}
+export interface AddStoreResult {
+    created: string[];
+}
+export declare function addStore(opts: AddStoreOptions): AddStoreResult;

package/dist/lib/templatesData.d.ts

@@ -1,2 +1,2 @@
-export declare const TEMPLATES_VERSION = "0.1.7";
+export declare const TEMPLATES_VERSION = "0.1.9";
 export declare const TEMPLATE_FILES: Record<string, string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsceasy/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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": {

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

@@ -22,6 +22,7 @@ export function App() {
   const [editingId, setEditingId] = useState<{{Name}}['{{primaryKey}}'] | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [saving, setSaving] = useState(false);
+{{relationOptionsState}}
 
   const load = useCallback(async (initial: boolean) => {
     // The list stashes a row id before revealing this panel. Pull it (the host
@@ -59,6 +60,7 @@ export function App() {
       document.removeEventListener('visibilitychange', onVisible);
     };
   }, [load]);
+{{relationOptionsLoad}}
 
   const onChange = <K extends keyof FormState>(k: K, v: FormState[K]) => {
     setForm((f) => ({ ...f, [k]: v }));

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

@@ -3,7 +3,7 @@ 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}}';
-
+{{relationImports}}
 export default definePanel<{{Name}}FormApi>({
   title: '{{title}}',
   column: 'beside',
@@ -25,7 +25,7 @@ export default definePanel<{{Name}}FormApi>({
       void vscode.commands.executeCommand('{{prefix}}.open{{Plural}}List');
       return saved;
     },
-    async cancel() {
+{{relationOptionsHandler}}    async cancel() {
       // No-op — webview closes itself.
     },
   }),

package/templates/_generators/helper/db.ts.tpl

@@ -64,6 +64,35 @@ export interface Repository<T> {
   clear(): Promise<void>;
 }
 
+// ── Change notifications (reactivity) ────────────────────────────────────────
+
+/**
+ * Per-entity change listeners. Any mutation (insert/upsert/update/delete/...) on
+ * an entity fires its listeners with the entity name. This is the host-side hook
+ * the `watch()` helper builds on to push updates to webviews.
+ */
+const entityListeners = new Map<string, Set<(entity: string) => void>>();
+
+function emitChange(entity: string): void {
+  entityListeners.get(entity)?.forEach((cb) => {
+    try { cb(entity); } catch { /* a bad listener must not break a write */ }
+  });
+}
+
+/**
+ * Subscribe to changes on an entity. Returns an unsubscribe function.
+ *
+ *   watchEntity(Todos, () => server.emit('todos:changed'));
+ *
+ * Prefer the higher-level `watch()` helper, which wires this to an RPC emit.
+ */
+export function watchEntity<T>(entity: Entity<T>, cb: (entity: string) => void): () => void {
+  let set = entityListeners.get(entity.name);
+  if (!set) entityListeners.set(entity.name, (set = new Set()));
+  set.add(cb);
+  return () => { set!.delete(cb); };
+}
+
 // ── Provider interface (future-proof for sqlite/etc.) ────────────────────────
 
 export interface Provider {
@@ -234,6 +263,7 @@ function makeDb(provider: Provider): Db {
         }
         rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async upsert(row) {
@@ -241,6 +271,7 @@ function makeDb(provider: Provider): Db {
         const i = rows.findIndex((r) => r[pk] === row[pk]);
         if (i >= 0) rows[i] = row; else rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async update(id, patch) {
@@ -249,6 +280,7 @@ function makeDb(provider: Provider): Db {
         if (i < 0) return null;
         rows[i] = { ...rows[i], ...patch };
         await save(rows);
+        emitChange(entity.name);
         return rows[i];
       },
       async delete(id) {
@@ -257,17 +289,19 @@ function makeDb(provider: Provider): Db {
         const next = rows.filter((r) => r[pk] !== id);
         if (next.length === before) return false;
         await save(next);
+        emitChange(entity.name);
         return true;
       },
       async deleteMany(where) {
         const rows = await load();
         const next = rows.filter((r) => !match(r, where));
         const removed = rows.length - next.length;
-        if (removed > 0) await save(next);
+        if (removed > 0) { await save(next); emitChange(entity.name); }
         return removed;
       },
       async clear() {
         await save([]);
+        emitChange(entity.name);
       },
     };
   };

package/templates/_generators/model/model.ts.tpl

@@ -14,4 +14,4 @@ export const {{Plural}} = defineEntity<{{Name}}>('{{collection}}', {
  *   import { {{Plural}}Repo } from '../models/{{Name}}';
  *   await {{Plural}}Repo().insert({ ... });
  */
-export const {{Plural}}Repo = () => db()({{Plural}});
+export const {{Plural}}Repo = () => db()({{Plural}});{{relationsBlock}}

package/templates/_generators/store/store.ts.tpl

@@ -0,0 +1,23 @@
+import { defineStore } from '../shared/vsceasy';
+
+/**
+ * Reactive store: a single observable value. Mutate it with `.set()` / `.update()`
+ * and anything subscribed reacts.
+ *
+ *   import { {{name}} } from '../stores/{{name}}';
+ *   {{name}}.set({{example}});
+ *   {{name}}.update((v) => v);
+ *
+ * To push changes to a webview, watch it on the host and emit over RPC:
+ *
+ *   // inside a panel/subpanel rpc():
+ *   import { watch } from '../shared/vsceasy';
+ *   import { {{name}} } from '../stores/{{name}}';
+ *   watch({{name}}, () => server.emit('{{name}}:changed', {{name}}.get()));
+ *
+ * Then listen in the webview:
+ *
+ *   import { listen } from '../shared/vsceasy/client';
+ *   listen(api, '{{name}}:changed', (v) => render(v));
+ */
+export const {{name}} = defineStore<{{type}}>({{initial}});

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

@@ -230,6 +230,13 @@ function registerTreeView(
     vscode.commands.registerCommand(refreshCmd, () => provider.refresh()),
   );
 
+  // Keep the tree live: let the def subscribe to a data source and re-run
+  // getChildren on change. The unsubscribe is disposed on deactivate.
+  if (def.watch) {
+    const off = def.watch(() => provider.refresh(), vscode, context);
+    if (off) context.subscriptions.push({ dispose: off });
+  }
+
   const dispatchCmd = `${registry.prefix}._tree.${def.id ?? id}.run`;
   context.subscriptions.push(
     vscode.commands.registerCommand(dispatchCmd, async (node: TreeNode) => {
@@ -306,9 +313,11 @@ function registerSubpanel(
       const ui = def.ui ?? `subpanels/${def.id ?? id}`;
       view.webview.html = renderHtml(view.webview, context, ui, def.title);
       if (def.rpc) {
-        const handlers = def.rpc(vscode, context);
-        const server = createRpcServer(webviewTransport(view.webview), handlers);
-        view.onDidDispose(() => server.dispose());
+        let server: ReturnType<typeof createRpcServer> | undefined;
+        const emit = (topic: string, payload?: unknown) => server?.emit(topic, payload);
+        const handlers = def.rpc(vscode, context, emit);
+        server = createRpcServer(webviewTransport(view.webview), handlers);
+        view.onDidDispose(() => server!.dispose());
       }
     },
   };
@@ -544,9 +553,13 @@ function openPanel(context: vscode.ExtensionContext, prefix: string, id: string,
   panel.webview.html = renderHtml(panel.webview, context, ui, def.title);
 
   if (def.rpc) {
-    const handlers = def.rpc(vscode, context);
-    const server = createRpcServer(webviewTransport(panel.webview), handlers);
-    panel.onDidDispose(() => server.dispose());
+    // `emit` is wired lazily: the rpc factory may call watch()/watchEntity()
+    // immediately, but the server (and thus the real emit) only exists after.
+    let server: ReturnType<typeof createRpcServer> | undefined;
+    const emit = (topic: string, payload?: unknown) => server?.emit(topic, payload);
+    const handlers = def.rpc(vscode, context, emit);
+    server = createRpcServer(webviewTransport(panel.webview), handlers);
+    panel.onDidDispose(() => server!.dispose());
   }
 
   openPanels.set(key, panel);

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

@@ -6,3 +6,30 @@ export {
   webviewState,
 } from './rpc';
 export type { RpcClient, Handlers, Transport, RpcClientOptions, WebviewApi } from './rpc';
+
+export { defineStore } from './store';
+export type { Store } from './store';
+
+import type { RpcClient, Handlers } from './rpc';
+
+/**
+ * Listen for a change pushed from the host over the RPC event channel, and run a
+ * callback when it arrives. This is the webview side of the reactivity model —
+ * the host emits with `server.emit(topic, …)` (usually wired via `watch()` /
+ * `watchEntity()`), and your visual element reacts here. Returns an unsubscribe
+ * function; call it on unmount.
+ *
+ *   const api = connectWebview<TodoStatsViewApi>();
+ *   // re-read + re-render whenever todos change on the host:
+ *   const off = listen(api, 'todos:changed', () => refresh());
+ *
+ * It's a thin, named wrapper over `api.on(topic, handler)` so the place you
+ * listen reads clearly in the UI code. The payload (if any) is passed through.
+ */
+export function listen<H extends Handlers>(
+  api: RpcClient<H>,
+  topic: string,
+  handler: (payload?: unknown) => void,
+): () => void {
+  return api.on(topic, handler);
+}

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

@@ -2,6 +2,18 @@ import type * as vscode from 'vscode';
 import type { Handlers } from './rpc';
 import type { CodiconName } from './codiconNames';
 
+/**
+ * Push a change to this webview over the RPC event channel. The webview reacts
+ * with `listen(api, topic, …)`. Wire it to a data source with `watch()` /
+ * `watchEntity()` inside `rpc()`:
+ *
+ *   rpc: (vscode, ctx, emit) => {
+ *     watchEntity(Todos, () => emit('todos:changed'));
+ *     return { stats: () => … };
+ *   }
+ */
+export type RpcEmit = (topic: string, payload?: unknown) => void;
+
 export interface PanelDef<H extends Handlers = Handlers> {
   /** Stable id. Default: file basename. Used as command suffix and webview key. */
   id?: string;
@@ -13,8 +25,11 @@ export interface PanelDef<H extends Handlers = Handlers> {
   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;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * `emit` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
   /** Optional command palette entry that opens this panel. Default: true. */
   command?:
     | boolean
@@ -125,8 +140,11 @@ export interface SubpanelDef<H extends Handlers = Handlers> {
   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;
+  /**
+   * RPC handlers — receives the vscode namespace, the extension context, and
+   * `emit` for pushing change events to this webview (see {@link RpcEmit}).
+   */
+  rpc?: (vscode: typeof import('vscode'), ctx: vscode.ExtensionContext, emit: RpcEmit) => H;
 }
 
 export function defineSubpanel<H extends Handlers = Handlers>(def: SubpanelDef<H>): SubpanelDef<H> {
@@ -228,6 +246,18 @@ export interface TreeViewDef {
     vscode: typeof import('vscode'),
     ctx: vscode.ExtensionContext,
   ) => TreeNode[] | Promise<TreeNode[]>;
+  /**
+   * Keep the tree live. Receives `refresh` — call it (directly or as a callback)
+   * to re-run `getChildren`. Subscribe to a data source here so the tree updates
+   * itself; return an unsubscribe to clean up.
+   *
+   *   watch: (refresh) => watchEntity(Todos, refresh),
+   */
+  watch?: (
+    refresh: () => void,
+    vscode: typeof import('vscode'),
+    ctx: vscode.ExtensionContext,
+  ) => (() => void) | void;
 }
 
 export function defineTreeView(def: TreeViewDef): TreeViewDef {

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

@@ -1,5 +1,5 @@
 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 type { PanelDef, CommandDef, MenuDef, MenuItem, MenuIcon, StatusBarDef, StatusBarMenuItem, KeybindingDef, SubpanelDef, TreeViewDef, TreeNode, JobDef, JobSchedule, CodiconName, RpcEmit } from './define';
 export { bootstrap } from './bootstrap';
 export type { Registry, BootstrapOptions, ActivateHook } from './bootstrap';
 export {
@@ -11,3 +11,6 @@ export {
   webviewState,
 } from './rpc';
 export type { Transport, RpcClient, Handlers, RpcClientOptions, WebviewApi } from './rpc';
+export { defineStore, watch } from './store';
+export type { Store, Watchable } from './store';
+export { listen } from './client';

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

@@ -0,0 +1,73 @@
+/**
+ * Reactive stores — a tiny, framework-agnostic observable value.
+ *
+ * A store holds one value and notifies subscribers when it changes. It's the
+ * non-ORM half of the reactivity model: use it for arbitrary state (a counter,
+ * a flag, a selection) that a visual element should track.
+ *
+ *   const counter = defineStore(0);
+ *   counter.subscribe((v) => console.log('now', v));
+ *   counter.set(1);          // logs: now 1
+ *   counter.update((n) => n + 1);
+ *
+ * Pair it with `watch()` on the host to push changes to a webview, and
+ * `listen()` on the webview to react — see those helpers below and in client.ts.
+ */
+export interface Store<T> {
+  /** Read the current value. */
+  get(): T;
+  /** Replace the value and notify subscribers (no-op if `Object.is`-equal). */
+  set(next: T): void;
+  /** Derive the next value from the current one, then `set` it. */
+  update(fn: (current: T) => T): void;
+  /** Subscribe to changes. Returns an unsubscribe function. */
+  subscribe(cb: (value: T) => void): () => void;
+}
+
+export function defineStore<T>(initial: T): Store<T> {
+  let value = initial;
+  const subs = new Set<(value: T) => void>();
+
+  return {
+    get: () => value,
+    set(next) {
+      if (Object.is(value, next)) return;
+      value = next;
+      subs.forEach((cb) => {
+        try { cb(value); } catch { /* a bad subscriber must not break a set */ }
+      });
+    },
+    update(fn) {
+      this.set(fn(value));
+    },
+    subscribe(cb) {
+      subs.add(cb);
+      return () => { subs.delete(cb); };
+    },
+  };
+}
+
+/**
+ * Anything that can be watched: it exposes a `subscribe(cb)` returning an
+ * unsubscribe function. Stores satisfy this directly. (ORM entities are watched
+ * with `watchEntity` from your generated `db.ts`, which has the same shape.)
+ */
+export interface Watchable {
+  subscribe(cb: (...args: any[]) => void): () => void;
+}
+
+/**
+ * Bridge a watchable source to a side-effect — typically an RPC emit that pushes
+ * the change to a subscribed webview. Runs `effect` on every change. Returns an
+ * unsubscribe function; register it on the panel's `ctx.subscriptions` (wrapped
+ * in `{ dispose }`) so it's cleaned up when the extension deactivates.
+ *
+ *   // host side, in a panel's rpc():
+ *   watch(badgeCount, () => server.emit('badge:changed'));
+ *
+ * For ORM entities, use `watchEntity(Todos, () => server.emit('todos:changed'))`
+ * from your generated db.ts — same idea, same return.
+ */
+export function watch(source: Watchable, effect: () => void): () => void {
+  return source.subscribe(() => effect());
+}