@vsceasy/cli 0.1.7 → 0.1.9

package/dist/commands/groups.d.ts

@@ -14,3 +14,4 @@ export declare const DbGroup: Command;
 export declare const ModelGroup: Command;
 export declare const CrudGroup: Command;
 export declare const ComponentsGroup: Command;
+export declare const StoreGroup: Command;

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

@@ -0,0 +1,3 @@
+import { Command } from '@ideascol/cli-maker';
+declare const addStoreCommand: Command;
+export default addStoreCommand;

package/dist/index.js

@@ -2238,7 +2238,7 @@ var init_upgrade = __esm(() => {
 });
 
 // src/lib/templatesData.ts
-var TEMPLATES_VERSION = "0.1.7", TEMPLATE_FILES;
+var TEMPLATES_VERSION = "0.1.9", TEMPLATE_FILES;
 var init_templatesData = __esm(() => {
   TEMPLATE_FILES = {
     "_generators/command/command.ts.tpl": `import { defineCommand } from '../shared/vsceasy';
@@ -2450,6 +2450,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
@@ -2487,6 +2488,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 }));
@@ -2550,7 +2552,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',
@@ -2572,7 +2574,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.
     },
   }),
@@ -2950,6 +2952,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 {
@@ -3120,6 +3151,7 @@ function makeDb(provider: Provider): Db {
         }
         rows.push(row);
         await save(rows);
+        emitChange(entity.name);
         return row;
       },
       async upsert(row) {
@@ -3127,6 +3159,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) {
@@ -3135,6 +3168,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) {
@@ -3143,17 +3177,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);
       },
     };
   };
@@ -3384,7 +3420,7 @@ 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}}
 `,
     "_generators/panel/App.tsx.tpl": `import React from 'react';
 {{apiBlock}}
@@ -3578,6 +3614,30 @@ export default defineStatusBar({
   alignment: '{{alignment}}',
   priority: {{priority}},{{commandLine}}{{panelLine}}
 });
+`,
+    "_generators/store/store.ts.tpl": `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}});
 `,
     "_generators/subpanel/App.tsx.tpl": `import React from 'react';
 {{apiBlock}}
@@ -4774,6 +4834,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) => {
@@ -4850,9 +4917,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());
       }
     },
   };
@@ -5088,9 +5157,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);
@@ -5208,6 +5281,33 @@ 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);
+}
 `,
     "react/src/shared/vsceasy/codiconNames.ts": `/**
  * AUTO-GENERATED by scripts/genCodiconTypes.ts — do not edit.
@@ -5410,6 +5510,18 @@ export type CodiconName =
 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;
@@ -5421,8 +5533,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
@@ -5533,8 +5648,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> {
@@ -5636,6 +5754,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 {
@@ -5677,7 +5807,7 @@ export function defineJob(def: JobDef): JobDef {
 }
 `,
     "react/src/shared/vsceasy/index.ts": `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 {
@@ -5689,6 +5819,9 @@ 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';
 `,
     "react/src/shared/vsceasy/rpc.ts": `// Typed RPC bridge — webview <-> extension.
 // Used by both sides. Transport-agnostic core + thin adapters.
@@ -5904,6 +6037,80 @@ export function webviewState<T>(defaults: T): {
     },
   };
 }
+`,
+    "react/src/shared/vsceasy/store.ts": `/**
+ * 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());
+}
 `,
     "react/src/webview/panels/dashboard/App.tsx": `import React, { useEffect, useState } from 'react';
 import { connectWebview } from '../../../shared/vsceasy/client';
@@ -6517,7 +6724,26 @@ function parseModelFile(file) {
       indexes.push(m[1]);
   }
   const id = path22.basename(file).replace(/\.(ts|tsx)$/, "");
-  return { name, id, plural, collection, primaryKey: pk, indexes, fields, path: file };
+  const relations = parseRelations(src, name);
+  for (const f of fields) {
+    const r = relations[f.name];
+    if (r)
+      f.relation = r;
+  }
+  return { name, id, plural, collection, primaryKey: pk, indexes, fields, relations, path: file };
+}
+function parseRelations(src, name) {
+  const out = {};
+  const block = new RegExp(`export\\s+const\\s+${name}Relations\\s*=\\s*\\{([\\s\\S]*?)\\}\\s*as\\s+const`, "m").exec(src);
+  if (!block)
+    return out;
+  const body = block[1];
+  const re = /([A-Za-z_][A-Za-z0-9_]*)\s*:\s*\{\s*model\s*:\s*['"`]([^'"`]+)['"`]\s*(?:,\s*label\s*:\s*['"`]([^'"`]+)['"`]\s*)?\}/g;
+  let m;
+  while (m = re.exec(body)) {
+    out[m[1]] = { field: m[1], model: m[2], label: m[3] };
+  }
+  return out;
 }
 function parseInterfaceBody(body) {
   const fields = [];
@@ -6654,12 +6880,26 @@ function addCrud(opts) {
     formId,
     prefix
   };
+  const modelsDir = path24.dirname(modelFile);
+  const relations = visible.filter((f) => f.relation).map((f) => {
+    const r = f.relation;
+    const related = parseModelFile(path24.join(modelsDir, `${r.model}.ts`));
+    const labelField = r.label ?? firstStringField(related) ?? related.primaryKey;
+    return {
+      field: f.name,
+      model: r.model,
+      plural: related.plural,
+      pk: related.primaryKey,
+      labelField
+    };
+  });
+  const relVars = buildRelationVars(relations);
   const created = [];
   const modified = [];
   writeFromTpl(path24.join(opts.templatesRoot, "_generators", "crud", "service.ts.tpl"), servicePath, baseVars, created);
   writeFromTpl(path24.join(opts.templatesRoot, "_generators", "crud", "formNav.ts.tpl"), path24.join(opts.projectRoot, "src", "services", `${camelLower(model.name)}FormNav.ts`), baseVars, created);
   writeFromTpl(path24.join(opts.templatesRoot, "_generators", "crud", "listPanel.ts.tpl"), listPanelPath, baseVars, created);
-  writeFromTpl(path24.join(opts.templatesRoot, "_generators", "crud", "formPanel.ts.tpl"), formPanelPath, baseVars, created);
+  writeFromTpl(path24.join(opts.templatesRoot, "_generators", "crud", "formPanel.ts.tpl"), formPanelPath, { ...baseVars, ...relVars }, created);
   fs24.mkdirSync(listWebDir, { recursive: true });
   const listVars = {
     ...baseVars,
@@ -6675,10 +6915,10 @@ function addCrud(opts) {
   const formInputs = visible.filter((f) => !cfg.fields?.[f.name]?.hideInForm).map((f) => renderInput(f, cfg.fields?.[f.name])).join(`
 `);
   const emptyLit = buildEmptyFormLiteral(visible, cfg);
-  writeFromTpl(path24.join(opts.templatesRoot, "_generators", "crud", "formApp.tsx.tpl"), path24.join(formWebDir, "App.tsx"), { ...baseVars, formFieldInputs: formInputs, emptyFormLiteral: emptyLit }, created);
+  writeFromTpl(path24.join(opts.templatesRoot, "_generators", "crud", "formApp.tsx.tpl"), path24.join(formWebDir, "App.tsx"), { ...baseVars, ...relVars, formFieldInputs: formInputs, emptyFormLiteral: emptyLit }, created);
   writeFromTpl(path24.join(opts.templatesRoot, "_generators", "crud", "main.tsx.tpl"), path24.join(formWebDir, "main.tsx"), baseVars, created);
   appendApi3(apiPath, listApiName, model, created, modified);
-  appendApiForm(apiPath, formApiName, model, created, modified);
+  appendApiForm(apiPath, formApiName, model, created, modified, relations.length > 0);
   let menuInfo;
   if (opts.menu && opts.menu !== "none") {
     menuInfo = wireMenu(opts, model, cfg, listId, formId);
@@ -6732,6 +6972,14 @@ function renderInput(field, override) {
 ` + `        <span style={{ opacity: 0.8 }}>${labelText}</span>
 ` + `${input}
 ` + `      </label>`;
+  if (field.relation) {
+    return wrap(`        <select${required} value={(form.${name} as any) ?? ''} onChange={(e) => onChange('${name}', e.target.value as any)}>
+` + `          <option value=""></option>
+` + `          {(relOptions['${name}'] ?? []).map((o) => (
+` + `            <option key={o.value} value={o.value}>{o.label}</option>
+` + `          ))}
+` + `        </select>`);
+  }
   switch (spec.kind) {
     case "number":
       return wrap(`        <input type="number"${placeholderAttr}${required} value={form.${name} as any ?? ''} onChange={(e) => onChange('${name}', e.target.value === '' ? undefined : Number(e.target.value))} />`);
@@ -6782,13 +7030,15 @@ export interface ${apiName} {
   ensureImport(apiPath, model.name);
   appendIfMissing(apiPath, apiName, sig, created, modified);
 }
-function appendApiForm(apiPath, apiName, model, created, modified) {
+function appendApiForm(apiPath, apiName, model, created, modified, hasRelations) {
+  const optionsLine = hasRelations ? `  options(): Promise<Record<string, { value: string; label: string }[]>>;
+` : "";
   const sig = `
 export interface ${apiName} {
 ` + `  pendingId(): Promise<${model.name}['${model.primaryKey}'] | null>;
 ` + `  get(id: ${model.name}['${model.primaryKey}'] | null): Promise<${model.name} | null>;
 ` + `  save(row: ${model.name}): Promise<${model.name}>;
-` + `  cancel(): Promise<void>;
+` + optionsLine + `  cancel(): Promise<void>;
 ` + `}
 `;
   ensureImport(apiPath, model.name);
@@ -6876,6 +7126,30 @@ function runGen11(cwd) {
 function which11(cmd) {
   return import_child_process12.spawnSync(process.platform === "win32" ? "where" : "which", [cmd], { stdio: "ignore" }).status === 0;
 }
+function firstStringField(model) {
+  return model.fields.find((f) => f.type.trim() === "string" && f.name !== model.primaryKey)?.name;
+}
+function buildRelationVars(relations) {
+  if (relations.length === 0) {
+    return { relationImports: "", relationOptionsHandler: "", relationOptionsState: "", relationOptionsLoad: "" };
+  }
+  const uniqueRepos = [...new Map(relations.map((r) => [r.plural, r])).values()];
+  const relationImports = uniqueRepos.map((r) => `import { ${r.plural}Repo } from '../models/${r.model}';`).join(`
+`) + `
+`;
+  const handlerLines = relations.map((r) => `      ${r.field}: (await ${r.plural}Repo().findMany()).map((x) => ({ value: String(x.${r.pk}), label: String(x.${r.labelField}) })),`).join(`
+`);
+  const relationOptionsHandler = `    async options() {
+` + `      return {
+` + `${handlerLines}
+` + `      };
+` + `    },
+`;
+  const relationOptionsState = `  const [relOptions, setRelOptions] = useState<Record<string, { value: string; label: string }[]>>({});`;
+  const relationOptionsLoad = `
+  useEffect(() => { void api.options().then(setRelOptions); }, []);`;
+  return { relationImports, relationOptionsHandler, relationOptionsState, relationOptionsLoad };
+}
 var fs24, path24, import_child_process12;
 var init_add11 = __esm(() => {
   init_scaffold();
@@ -6908,11 +7182,37 @@ function addModel(opts) {
   const pkField = explicitPk[0] ?? opts.fields.find((f) => f.name === "id") ?? opts.fields[0];
   const primaryKey = pkField.name;
   const indexes = opts.fields.filter((f) => f.indexed && f.name !== primaryKey).map((f) => f.name);
-  const target = path25.join(opts.projectRoot, "src", "models", `${Name}.ts`);
+  const modelsDir = path25.join(opts.projectRoot, "src", "models");
+  for (const f of opts.fields) {
+    if (!f.relation)
+      continue;
+    if (f.relation.model === Name) {} else if (!fs25.existsSync(path25.join(modelsDir, `${f.relation.model}.ts`))) {
+      throw new Error(`Field "${f.name}" references model "${f.relation.model}", but src/models/${f.relation.model}.ts does not exist. ` + `Run \`vsceasy model add --name ${f.relation.model}\` first.`);
+    }
+  }
+  const target = path25.join(modelsDir, `${Name}.ts`);
   assertNoOverwrite(opts.projectRoot, target, "Model");
   const tpl = path25.join(opts.templatesRoot, "_generators", "model", "model.ts.tpl");
-  const fieldLines = opts.fields.map((f) => `  ${f.name}${f.optional ? "?" : ""}: ${f.type};`).join(`
+  const fkName = (f) => f.relation ? `${f.name}Id` : f.name;
+  const fieldLines = opts.fields.map((f) => {
+    const ts = f.relation ? "string" : f.type;
+    const note = f.relation ? `  // → ${f.relation.model}` : "";
+    return `  ${fkName(f)}${f.optional ? "?" : ""}: ${ts};${note}`;
+  }).join(`
 `);
+  const relFields = opts.fields.filter((f) => f.relation);
+  const relationsBlock = relFields.length ? `
+
+/** Relation metadata — used by \`vsceasy crud add\` to populate pickers. */
+` + `export const ${Name}Relations = {
+` + relFields.map((f) => {
+    const r = f.relation;
+    const lbl = r.label ? `, label: '${r.label}'` : "";
+    return `  ${fkName(f)}: { model: '${r.model}'${lbl} },`;
+  }).join(`
+`) + `
+} as const;
+` : "";
   const vars = {
     name,
     Name,
@@ -6921,11 +7221,12 @@ function addModel(opts) {
     primaryKey,
     fieldLines,
     indexesLine: indexes.length ? `
-  indexes: [${indexes.map((i) => `'${i}'`).join(", ")}],` : ""
+  indexes: [${indexes.map((i) => `'${i}'`).join(", ")}],` : "",
+    relationsBlock
   };
   fs25.mkdirSync(path25.dirname(target), { recursive: true });
   fs25.writeFileSync(target, substitute(fs25.readFileSync(tpl, "utf8"), vars));
-  return { created: [target], primaryKey, indexes };
+  return { created: [target], primaryKey, indexes, relations: relFields.map((f) => ({ field: fkName(f), ...f.relation })) };
 }
 function normalizeCamel8(s) {
   const cleaned = s.trim().replace(/[^a-zA-Z0-9]+(.)/g, (_m, c) => c.toUpperCase()).replace(/[^a-zA-Z0-9]/g, "");

package/dist/lib/crud/parseModel.d.ts

@@ -1,8 +1,18 @@
+export interface ParsedRelation {
+    /** FK field on this model (e.g. `categoryId`). */
+    field: string;
+    /** Related model name (e.g. `Category`). */
+    model: string;
+    /** Field on the related model to show in the picker. */
+    label?: string;
+}
 export interface ParsedField {
     name: string;
     /** Raw TS type as written in the interface (e.g. `string`, `number`, `'a' | 'b'`, `Date`). */
     type: string;
     optional: boolean;
+    /** Set when this field is a foreign key declared via `<Name>Relations`. */
+    relation?: ParsedRelation;
 }
 export interface ParsedModel {
     /** PascalCase interface name. */
@@ -19,6 +29,8 @@ export interface ParsedModel {
     indexes: string[];
     /** Ordered field list from the interface body. */
     fields: ParsedField[];
+    /** FK field → relation metadata, keyed by FK field name. */
+    relations: Record<string, ParsedRelation>;
     /** Absolute path the model was read from. */
     path: string;
 }

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

@@ -1,3 +1,9 @@
+export interface FieldRelation {
+    /** PascalCase name of the related model (e.g. `Category`). */
+    model: string;
+    /** Field on the related model to show in pickers. Default: first string field, else its pk. */
+    label?: string;
+}
 export interface ModelField {
     name: string;
     /** Raw TS type. e.g. `string`, `number`, `string | null`, `Date`, `'a' | 'b'`. */
@@ -8,6 +14,12 @@ export interface ModelField {
     primaryKey?: boolean;
     /** Add to entity `indexes` (speeds up findOne by this field). */
     indexed?: boolean;
+    /**
+     * ManyToOne relation. When set, the field is emitted as a `<name>Id: string`
+     * foreign key and recorded in the model's relation metadata so `crud add`
+     * renders a populated dropdown. Authored as `name:ref(Model)` in the spec.
+     */
+    relation?: FieldRelation;
 }
 export interface AddModelOptions {
     name: string;
@@ -23,5 +35,11 @@ export interface AddModelResult {
     created: string[];
     primaryKey: string;
     indexes: string[];
+    /** Foreign-key fields and the models they point at. */
+    relations: Array<{
+        field: string;
+        model: string;
+        label?: string;
+    }>;
 }
 export declare function addModel(opts: AddModelOptions): AddModelResult;