datagrok-tools 6.5.4 → 6.5.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Datagrok-tools changelog
 
+## 6.5.5 (WIP)
+
+* GROK-20298: `grok api --ui` — a relation-bearing table's `<Table>Ui` handle carries `<Table>Update` as its fifth generic too (`<Table>Ui.client`, `.table()` and the `<Schema>UiDb` property), so `<table>Ui.client.update(id, {labels: [...]})` compiles instead of failing the excess-property check.
+* GROK-20298: `grok api` — typed many-to-many relations: a table's `relations` block is validated with the server's rules (via/target declared in the same manifest, junction distinct from both sides, self-referential relations explicit, FK sides unique-or-explicit, junction `businessKey` covering both) and emitted as an expand-map entry `'<name>': {<name>?: {id: string; name: string}[]}`, a `<name>?: string[]` link set on `<Table>Insert`, and a new `<Table>Update` type (`Partial<<Table>Row>` plus the link sets) used by the transaction op union and passed as the client's fifth generic, so `update()` takes the link sets directly. Manifests without relations generate byte-identically.
+* GROK-20298: `grok api --ui` — also emits the typed SCHEMA handle: `export function <schema>UiDb(): Promise<<Schema>UiDb>` (a typed `domains.db(...)`), and the `<Schema>UiDb` interface types each table property (`const db = await gritUiDb(); db.issues.form({values: {...}})` is compile-checked).
+* GROK-20298: **BREAKING** — `grok api` schema clients name their table properties with the camelCase PLURAL of the table name (`<schema>Db.issues`, `.issueLabels`; same rule as domain-ui's `DomainDb`), and no longer pass `datetimeColumns` config — datetime materialization is registry-driven in `DomainTableClient` itself. Regenerate and rename call sites (`<schema>Db.issue` → `<schema>Db.issues`); transaction op `table:` values keep the declared singular names.
+* GROK-20298: `grok add app --domain <schema>[.<table>]` — scaffolds a working browse/CRUD app over an entity-mapped domain table into an existing package: a one-expression `#app` function per table (`return (await domains.table('<schema>.<table>')).app();`, giving list/search/entity page/editing/permissions/deep links from the `@datagrok-libraries/domain-ui` defaults), the domain-ui dependency, and the typed clients for manifests the package declares. `--domain <schema>` covers every table of a schema the package declares; `--domain <path to schema.json>` copies the manifest into `databases/<schema>/` first. A fresh app package is `grok create <Name>` + this command.
+* GROK-20298: `grok api --ui` — emits `src/generated/db-ui.ts` next to `db.ts`: a `<table>Ui` wrapper per domain table over the reflective `@datagrok-libraries/domain-ui` components, with this table's columns, expand keys and insert payloads checked at compile time. `<Table>Ui.table()` resolves the TYPED `DomainTable` handle (all four client generics), and `form`, `formDialog`, `grid`, `list`, `listView`, `app` and `entityView` are built on it; `edit`, `pick`, `row`, `query` and the typed `client` are unchanged, and the address moved from `<Table>Ui.table` to `<Table>Ui.address` to free the name for the handle. Opt-in and separate on purpose — data-only consumers keep `db.ts` free of any UI dependency; once the file exists, plain `grok api` keeps it up to date (delete it to opt out).
+* GROK-20603: `grok api` — the generated `<schema>Db.transaction` signature is now mapped-tuple generic (`<T extends <Schema>TransactionOp[]>(ops: [...T])` with per-op result types); regenerating produces a different file, and positional `as DG.DomainUpdateResult`-style casts on transaction results become unnecessary.
+* GROK-20602: **BREAKING** — `grok api` domain codegen v2: **datetime columns (including `created_on`/`updated_on`) are now typed as dayjs `Dayjs`** in `<Table>Row` (`Dayjs | string` on inserts) and generated clients pass `datetimeColumns` so JSON reads materialize dayjs objects — code that treated these fields as strings no longer compiles (untyped `table('s.t')` clients are unchanged). Also: `choices` columns emit named literal-union aliases used in Row/Insert; `<Table>Column` unions and NEW `<Table>Expand` maps are threaded through the client generics (filters/columns/expand keys compile-checked); a typed `<Schema>TransactionOp` union powers `<schema>Db.transaction`; the client map now uses LAZY getters — importing db.ts no longer touches `grok.dapi` at import time. Regenerate with `grok api` and fix datetime call sites. Migration note: choices-alias names are derived as `<Table><Column>`; when two tables' aliases collide with different value sets, the LATER table (manifest order) gets a `<Table>`-suffixed name — reordering manifest tables can therefore rename such aliases; keep table order stable or update imports after reordering.
+* GROK-20319: `grok api` — generated domain clients now pass the `<Table>Insert` interface as the second `DG.DomainTableClient` generic, so `insert()` enforces required columns at compile time (e.g. `insert({})` no longer compiles); over-long client lines wrap before the type.
+* GROK-20317: `grok api` — typed domain-table clients: for packages that declare `databases/<schema>/schema.json` manifests, generates `src/generated/db.ts` with per-table `<Table>Row`/`<Table>Insert` interfaces, `<Table>Column` name unions, and a per-schema `<schema>Db` client map over `grok.dapi.domains` (manifests are validated against `domain-schema.schema.json` first; packages without manifests are untouched).
 ## 6.5.4 (2026-08-07)
 
 * func-gen-plugin — `#meta.comparison` in an `.ivp` model now lands as the `comparison` option on the generated dataframe output (run comparison reads index/split/mode/units defaults from there) instead of function-level meta.
@@ -16,7 +28,7 @@
 
 * `grok test` — the Node-pass report now merges into the browser report by column name. The line-wise merge assumed identical column order, so node rows landed misaligned (string values in the integer `ms` column) and the CI test-report upload failed with `invalid input syntax for type integer`.
 
-## 6.5.0 (WIP)
+## 6.5.5 (WIP)
 
 * `grok test` — added a Node (browserless) pass: tests annotated `{node: true}` run headless under the js-api Node runtime before the browser launches; the browser pass excludes them and is skipped entirely when nothing browser-only matches. New flags: `--skip-node`, `--node-only`. Packages opt in by exporting `testNode()` from `package-test.ts`; others keep the previous behavior.
 

package/bin/commands/add.js

@@ -10,12 +10,17 @@ var _path = _interopRequireDefault(require("path"));
 var _entHelpers = require("../utils/ent-helpers");
 var utils = _interopRequireWildcard(require("../utils/utils"));
 var color = _interopRequireWildcard(require("../utils/color-utils"));
+var _api = require("./api");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/** The domain-ui library version a scaffolded domain app depends on. */
+const domainUiDependency = '^0.1.0';
 function add(args) {
-  const nOptions = Object.keys(args).length - 1;
+  // `--domain` is the only option any `add` entity takes (`grok add app --domain`).
+  const nOptions = Object.keys(args).length - 1 - (args.domain === undefined ? 0 : 1);
   const nArgs = args['_'].length;
   if (nArgs < 2 || nArgs > 5 || nOptions > 0) return false;
   const entity = args['_'][1];
+  if (args.domain !== undefined && entity !== 'app') return color.error('`--domain` applies to `grok add app` only');
   const curDir = process.cwd();
   const curFolder = _path.default.basename(curDir);
   const srcDir = _path.default.join(curDir, 'src');
@@ -60,6 +65,112 @@ function add(args) {
       _fs.default.writeFileSync(packageEntry, contents, 'utf8');
     }
   }
+
+  /** The manifest at [manifestPath], or null when it is missing or unreadable. */
+  function readManifest(manifestPath) {
+    if (!_fs.default.existsSync(manifestPath)) return null;
+    try {
+      const manifest = JSON.parse(_fs.default.readFileSync(manifestPath, 'utf8'));
+      if (typeof manifest?.name !== 'string' || manifest?.tables == null) {
+        color.error(`${manifestPath} is not a domain schema manifest (no \`name\` / \`tables\`)`);
+        return null;
+      }
+      return manifest;
+    } catch (error) {
+      color.error(`Error while reading ${manifestPath}:`);
+      console.error(error);
+      return null;
+    }
+  }
+
+  /** Copies a schema manifest into `databases/<schema>/` (where `grok api` and the
+   * publisher look for it); returns its schema name and table names. */
+  function copyManifest(manifestPath) {
+    const manifest = readManifest(_path.default.resolve(curDir, manifestPath));
+    if (manifest == null) return null;
+    const target = _path.default.join(curDir, 'databases', manifest.name, 'schema.json');
+    if (_path.default.resolve(curDir, manifestPath) !== target) {
+      _fs.default.mkdirSync(_path.default.dirname(target), {
+        recursive: true
+      });
+      _fs.default.copyFileSync(_path.default.resolve(curDir, manifestPath), target);
+      console.log(`Copied the schema manifest to databases/${manifest.name}/schema.json`);
+    }
+    return [manifest.name, Object.keys(manifest.tables)];
+  }
+
+  /** Adds `import {domains} from '@datagrok-libraries/domain-ui';` to the package
+   * entry file, after its existing imports (which webpack's externals depend on). */
+  function addDomainUiImport() {
+    const contents = _fs.default.readFileSync(packageEntry, 'utf8');
+    if (contents.includes('@datagrok-libraries/domain-ui')) return;
+    const eol = contents.includes('\r\n') ? '\r\n' : '\n';
+    const line = `import {domains} from '@datagrok-libraries/domain-ui';`;
+    const lines = contents.split(/\r?\n/);
+    let last = -1;
+    for (let i = 0; i < lines.length; i++) if (/^(import .*|export .* from .*);\s*$/.test(lines[i])) last = i;
+    lines.splice(last + 1, 0, line);
+    _fs.default.writeFileSync(packageEntry, lines.join(eol), 'utf8');
+  }
+
+  /** `grok add app [name] --domain <schema>[.<table>] | <schema.json path>` — a working
+   * browse/CRUD app per table, from the `domain-ui` defaults alone. */
+  function addDomainApp(domainArg, appName) {
+    if (typeof domainArg !== 'string' || domainArg === '') return color.error('`--domain` needs `<schema>` or `<schema>.<table>`, ' + 'or a path to a schema.json manifest');
+    let schema;
+    let tables;
+    if (/\.json$/i.test(domainArg)) {
+      const copied = copyManifest(domainArg);
+      if (copied == null) return false;
+      [schema, tables] = copied;
+    } else {
+      if (!/^[A-Za-z_]\w*(\.[A-Za-z_]\w*)?$/.test(domainArg)) return color.error(`Malformed domain address: ${domainArg}. ` + 'Use `<schema>`, `<schema>.<table>`, or a path to a schema.json manifest');
+      const dot = domainArg.indexOf('.');
+      schema = dot === -1 ? domainArg : domainArg.slice(0, dot);
+      if (dot !== -1) tables = [domainArg.slice(dot + 1)];else {
+        // Table names of a whole schema are only known offline from its manifest.
+        const manifest = readManifest(_path.default.join(curDir, 'databases', schema, 'schema.json'));
+        if (manifest == null) return color.error(`No \`databases/${schema}/schema.json\` in this package: name a table ` + `(\`--domain ${schema}.<table>\`) or pass the path to the schema manifest`);
+        tables = Object.keys(manifest.tables);
+      }
+    }
+    if (tables.length === 0) return color.error(`Schema \`${schema}\` declares no tables`);
+    if (appName != null && tables.length > 1) return color.error(`\`--domain ${domainArg}\` covers ${tables.length} tables — ` + 'name a single table to name its app');
+    createPackageEntryFile();
+    const template = _fs.default.readFileSync(_path.default.join(templateDir, 'entity-template', 'domain-app' + ext), 'utf8');
+    const entry = _fs.default.readFileSync(packageEntry, 'utf8');
+    const added = [];
+    const addedTables = [];
+    for (const table of tables) {
+      // No 'App' postfix — `grok check` asks apps to drop it (check.ts:350-356).
+      const funcName = appName ?? utils.snakeToCamelCase(table);
+      if (!validateName(funcName)) return false;
+      if (new RegExp(`function\\s+${funcName}\\s*\\(`).test(entry)) {
+        color.warn(`${funcName} is already declared in ${_path.default.relative(curDir, packageEntry)} — skipped`);
+        continue;
+      }
+      _fs.default.appendFileSync(packageEntry, utils.replacers['DOMAIN_TABLE'](insertName(funcName, template), `${schema}.${table}`));
+      added.push(funcName);
+      addedTables.push(`${schema}.${table}`);
+    }
+    if (added.length === 0) return true;
+    addDomainUiImport();
+    const packageObj = JSON.parse(_fs.default.readFileSync(packagePath, 'utf8'));
+    packageObj.dependencies = packageObj.dependencies ?? {};
+    if (packageObj.dependencies['@datagrok-libraries/domain-ui'] === undefined) {
+      packageObj.dependencies['@datagrok-libraries/domain-ui'] = domainUiDependency;
+      _fs.default.writeFileSync(packagePath, JSON.stringify(packageObj, null, 2), 'utf8');
+    }
+
+    // Manifests in the package get typed clients AND the typed UI wrappers the app
+    // code can switch to; a schema deployed by another package has none, and the
+    // reflective app above needs none.
+    if (!(0, _api.generateDomainClients)(curDir, {
+      ui: true
+    })) return false;
+    console.log(_entHelpers.help.domainApp(added, addedTables));
+    return true;
+  }
   let name;
   let tag;
   let contents;
@@ -104,6 +215,10 @@ function add(args) {
       console.log(_entHelpers.help.script(name, curFolder));
       break;
     case 'app':
+      if (args.domain !== undefined) {
+        if (nArgs > 3) return false;
+        return addDomainApp(args.domain, nArgs === 3 ? args['_'][2] : null);
+      }
       if (nArgs !== 3) return false;
 
       // App name check

package/bin/commands/api.js

@@ -5,16 +5,56 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.api = api;
+exports.generateDomainClients = generateDomainClients;
 var _fs = _interopRequireDefault(require("fs"));
 var _path = _interopRequireDefault(require("path"));
 var _ignoreWalk = _interopRequireDefault(require("ignore-walk"));
+var _ajv = _interopRequireDefault(require("ajv"));
 var utils = _interopRequireWildcard(require("../utils/utils"));
 var color = _interopRequireWildcard(require("../utils/color-utils"));
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 const annotationForApiFile = `/**\nThis file is auto-generated by the grok api command.\nIf you notice any changes, please push them to the repository.\nDo not edit this file manually.\n*/\n`;
+const annotationForDbFile = `/**\nThis file is auto-generated by the grok api command from databases/<schema>/schema.json manifests.\nIf you notice any changes, please push them to the repository.\nDo not edit this file manually.\n*/\n`;
+const annotationForDbUiFile = `/**\nThis file is auto-generated by the grok api command (--ui) from databases/<schema>/schema.json manifests.\nIt is regenerated on every \`grok api\` run as long as it exists; delete it to opt out.\nIf you notice any changes, please push them to the repository.\nDo not edit this file manually.\n*/\n`;
 const sep = '\n';
 const packageFuncDirs = ['package.ts', 'package.g.ts'];
 const apiFile = 'package-api.ts';
+const dbFile = 'db.ts';
+const dbUiFile = 'db-ui.ts';
+/** What `db-ui.ts` imports from `@datagrok-libraries/domain-ui`. */
+const domainUiImports = ['domainHandler', 'domains', 'DomainAppView', 'DomainAppViewOptions', 'DomainDb', 'DomainDialogOptions', 'DomainEntityAppView', 'DomainEntityAppViewOptions', 'DomainForm', 'DomainFormOptions', 'DomainGrid', 'DomainGridOptions', 'DomainTable', 'EntityListOptions', 'EntityListWidget'];
+/** {@link DomainDb} members a table's camelCase property name must not shadow. */
+const domainDbReservedProps = ['name', 'tables', 'table', 'acquire'];
+
+/** Naive English plural of a (snake_case) table name — `issue` → `issues`, `box` →
+ * `boxes`, `category` → `categories`. MUST match domain-ui's `pluralizeTableName`:
+ * the runtime `DomainDb` assigns its per-table properties with the same rule, so the
+ * generated typed interfaces bind to it. */
+function pluralizeTableName(name) {
+  if (/(s|x|z|ch|sh)$/.test(name)) return name + 'es';
+  if (/[^aeiou_]y$/.test(name)) return name.slice(0, -1) + 'ies';
+  return name + 's';
+}
+
+/** The camelCase plural property name a table gets on the schema client and the
+ * schema UI handle (`issue_label` → `issueLabels`). */
+function tableProp(tableName) {
+  return utils.snakeToCamelCase(pluralizeTableName(tableName), false);
+}
+const domainSchemaPath = _path.default.join(_path.default.dirname(_path.default.dirname(__dirname)), 'domain-schema.schema.json');
+const domainSystemColumns = [['id', 'string'], ['version', 'number'], ['created_on', 'Dayjs'], ['updated_on', 'Dayjs'], ['author_id', 'string']];
+const domainTypeMap = {
+  string: 'string',
+  int: 'number',
+  float: 'number',
+  bool: 'boolean',
+  datetime: 'Dayjs',
+  string_list: 'string[]',
+  ref: 'string',
+  user: 'string',
+  group: 'string',
+  file: 'string'
+};
 function normEol(s) {
   return s.replace(/\r\n/g, '\n');
 }
@@ -130,13 +170,350 @@ function checkNameColision(name) {
   if (names.has(name)) console.log('There is collision in name ' + name);
   names.add(name);
 }
+
+/** Generates `src/generated/db.ts` with typed clients for the package's domain schemas
+ * (`databases/<schema>/schema.json` manifests), and — with [options].ui, or whenever the
+ * file is already there — `src/generated/db-ui.ts` with the typed UI sugar over
+ * `@datagrok-libraries/domain-ui`. No-op for packages without manifests. */
+function generateDomainClients(packageDir = curDir, options) {
+  const databasesDir = _path.default.join(packageDir, 'databases');
+  if (!_fs.default.existsSync(databasesDir)) return true;
+  const manifestPaths = _fs.default.readdirSync(databasesDir).map(dir => _path.default.join(databasesDir, dir, 'schema.json')).filter(p => _fs.default.existsSync(p));
+  if (manifestPaths.length === 0) return true;
+  const validateManifest = new _ajv.default().compile(JSON.parse(_fs.default.readFileSync(domainSchemaPath, 'utf8')));
+  const genDir = _path.default.join(packageDir, 'src', 'generated');
+  // The `--ui` opt-in persists by presence: once emitted, the file is kept up to date by
+  // every plain `grok api` run, so a package's build script needs no extra flag.
+  const ui = (options?.ui ?? false) || _fs.default.existsSync(_path.default.join(genDir, dbUiFile));
+  const parts = [];
+  const uiParts = [];
+  const dbImports = [];
+  const emittedTypes = new Set();
+  for (const manifestPath of manifestPaths) {
+    const relPath = _path.default.relative(packageDir, manifestPath);
+    let manifest;
+    try {
+      manifest = JSON.parse(_fs.default.readFileSync(manifestPath, 'utf8'));
+    } catch (x) {
+      color.error(`Failed to parse ${relPath}: ${x.message}`);
+      return false;
+    }
+    if (!validateManifest(manifest)) {
+      for (const err of validateManifest.errors ?? []) color.error(`${relPath}: ${err.instancePath || '/'} ${err.message}`);
+      return false;
+    }
+    const code = generateDomainSchemaCode(manifest, relPath, emittedTypes);
+    if (code == null) return false;
+    parts.push(code);
+    if (ui) uiParts.push(generateDomainUiCode(manifest, dbImports));
+  }
+  _fs.default.mkdirSync(genDir, {
+    recursive: true
+  });
+  const content = annotationForDbFile + utils.dgImports + `import type {Dayjs} from 'dayjs';${sep}` + sep + parts.join(sep);
+  _fs.default.writeFileSync(_path.default.join(genDir, dbFile), normEol(content).replace(/\n/g, '\r\n'), 'utf8');
+  color.log(`Successfully generated file src/generated/${dbFile}${sep}`, 'success');
+  if (ui) {
+    const uiContent = annotationForDbUiFile + `import * as DG from 'datagrok-api/dg';${sep}` + wrapTokens(`import {`, domainUiImports, ', ', `} from '@datagrok-libraries/domain-ui';`) + sep + wrapTokens(`import {`, dbImports, ', ', `} from './${dbFile.replace(/\.ts$/, '')}';`) + sep + sep + uiParts.join(sep);
+    _fs.default.writeFileSync(_path.default.join(genDir, dbUiFile), normEol(uiContent).replace(/\n/g, '\r\n'), 'utf8');
+    color.log(`Successfully generated file src/generated/${dbUiFile}${sep}`, 'success');
+  }
+  return true;
+}
+
+/** A resolved many-to-many relation of one table: the expand key and the target
+ * table whose row ids its write-side link set carries. */
+
+/** Emits choices aliases, row/insert interfaces, column-name unions, expand maps, the
+ * `<Schema>TransactionOp` union, and the lazy `<schema>Db` clients for one manifest.
+ * Returns null on a semantic error (reported to the console). */
+function generateDomainSchemaCode(manifest, manifestPath, emittedTypes) {
+  const decls = [];
+  const systemColumnNames = new Set(domainSystemColumns.map(([name]) => name));
+  const tableNames = Object.keys(manifest.tables);
+  const tableColumns = {};
+  // Choices aliases are deduplicated by name: identical value sets share the first alias,
+  // different sets fall back to a `<alias><PascalTable>` name (deterministic).
+  const choicesAliases = {};
+  const choicesAlias = (tableName, columnName, values) => {
+    const valueSet = values.map(v => `'${v}'`).join(' | ');
+    let alias = utils.snakeToCamelCase(tableName) + utils.snakeToCamelCase(columnName);
+    if (choicesAliases[alias] !== undefined && choicesAliases[alias] !== valueSet) alias += utils.snakeToCamelCase(tableName);
+    if (choicesAliases[alias] !== undefined && choicesAliases[alias] !== valueSet) {
+      color.error(`${manifestPath}: cannot derive a unique choices alias for '${tableName}.${columnName}'`);
+      return null;
+    }
+    if (choicesAliases[alias] === undefined) {
+      choicesAliases[alias] = valueSet;
+      decls.push(wrapTokens(`export type ${alias} = `, values.map(v => `'${v}'`), ' | ', ';'));
+    }
+    return alias;
+  };
+
+  // Pass 1: resolve every table's full column list (relational + property-schema columns).
+  for (const tableName of tableNames) {
+    const table = manifest.tables[tableName];
+    const typeName = utils.snakeToCamelCase(tableName);
+    if (emittedTypes.has(typeName)) {
+      color.error(`${manifestPath}: table '${tableName}' emits interface '${typeName}Row' ` + `already generated for another table (table names must be unique across the package's manifests)`);
+      return null;
+    }
+    emittedTypes.add(typeName);
+    const columns = [];
+    const columnNames = new Set(systemColumnNames);
+    const addColumn = (name, column) => {
+      if (columnNames.has(name)) {
+        color.error(systemColumnNames.has(name) ? `${manifestPath}: table '${tableName}' column '${name}' collides with a generated system column` : `${manifestPath}: table '${tableName}' declares duplicate column '${name}'`);
+        return false;
+      }
+      columnNames.add(name);
+      let tsType = domainTypeMap[column.type];
+      if (Array.isArray(column.choices) && column.choices.length > 0) {
+        const alias = choicesAlias(tableName, name, column.choices);
+        if (alias == null) return false;
+        tsType = alias;
+      }
+      columns.push({
+        name: name,
+        rawType: column.type,
+        tsType: tsType,
+        insertType: column.type === 'datetime' ? 'Dayjs | string' : tsType,
+        required: column.required === true,
+        ref: column.type === 'ref' && manifest.tables[column.ref] != null ? column.ref : undefined
+      });
+      return true;
+    };
+    for (const columnName of Object.keys(table.columns)) if (!addColumn(columnName, table.columns[columnName])) return null;
+    for (const schemaName of table.schemas ?? []) {
+      const props = manifest.propertySchemas?.[schemaName];
+      if (props == null) {
+        color.error(`${manifestPath}: table '${tableName}' references unknown property schema '${schemaName}'`);
+        return null;
+      }
+      for (const propName of Object.keys(props)) if (!addColumn(propName, props[propName])) return null;
+    }
+    tableColumns[tableName] = columns;
+  }
+
+  // Pass 1.5: resolve declared many-to-many relations. Same rules the server's
+  // manifest parser applies (manifest.dart 'relations'), so a manifest that
+  // generates here is one that deploys: via/target declared in this manifest,
+  // via distinct from owner and target, self-referential relations explicit,
+  // FK sides unique-or-explicit, and a junction business key covering both —
+  // that key is what keeps re-linking the same pair idempotent.
+  const tableRelations = {};
+  for (const tableName of tableNames) {
+    const relations = [];
+    tableRelations[tableName] = relations;
+    const declared = manifest.tables[tableName].relations;
+    if (declared == null) continue;
+    const ownColumns = new Set(tableColumns[tableName].map(c => c.name));
+    for (const name of Object.keys(declared)) {
+      const r = declared[name];
+      const where = `${manifestPath}: relation '${tableName}.${name}'`;
+      if (ownColumns.has(name) || systemColumnNames.has(name)) {
+        color.error(`${where} collides with a column of '${tableName}' — relations and columns ` + `share one expand/filter namespace`);
+        return null;
+      }
+      if (manifest.tables[r.via] == null) {
+        color.error(`${where}: junction table '${r.via}' is not declared in this manifest`);
+        return null;
+      }
+      if (manifest.tables[r.target] == null) {
+        color.error(`${where}: target table '${r.target}' is not declared in this manifest`);
+        return null;
+      }
+      if (r.via === tableName || r.via === r.target) {
+        color.error(`${where}: junction table '${r.via}' must differ from the owner and the target table`);
+        return null;
+      }
+      if (r.target === tableName && (r.viaSelf == null || r.viaTarget == null)) {
+        color.error(`${where}: a self-referential relation must name both 'viaSelf' and 'viaTarget'`);
+        return null;
+      }
+      // One side of the junction: the declared column when explicit, otherwise
+      // the single ref column of `via` pointing at `to`.
+      const resolveSide = (key, explicit, to) => {
+        const candidates = tableColumns[r.via].filter(c => c.ref === to).map(c => c.name);
+        if (explicit != null) {
+          if (candidates.includes(explicit)) return explicit;
+          color.error(`${where}: '${explicit}' is not a ref column of junction table '${r.via}' ` + `targeting '${to}'`);
+          return null;
+        }
+        if (candidates.length === 0) {
+          color.error(`${where}: junction table '${r.via}' has no ref column targeting '${to}'`);
+          return null;
+        }
+        if (candidates.length > 1) {
+          color.error(`${where}: junction table '${r.via}' has more than one ref column targeting ` + `'${to}' (${candidates.join(', ')}) — declare '${key}' explicitly`);
+          return null;
+        }
+        return candidates[0];
+      };
+      const viaSelf = resolveSide('viaSelf', r.viaSelf, tableName);
+      const viaTarget = resolveSide('viaTarget', r.viaTarget, r.target);
+      if (viaSelf == null || viaTarget == null) return null;
+      if (viaSelf === viaTarget) {
+        color.error(`${where}: 'viaSelf' and 'viaTarget' must be different columns of '${r.via}'`);
+        return null;
+      }
+      const businessKey = manifest.tables[r.via].businessKey ?? [];
+      if (!businessKey.includes(viaSelf) || !businessKey.includes(viaTarget)) {
+        color.error(`${where}: junction table '${r.via}' must declare a 'businessKey' containing ` + `both '${viaSelf}' and '${viaTarget}', so linking the same pair twice stays idempotent`);
+        return null;
+      }
+      relations.push({
+        name: name,
+        target: r.target
+      });
+    }
+  }
+
+  // Pass 2: emit per-table declarations.
+  const clients = [];
+  const txArms = [];
+  for (const tableName of tableNames) {
+    const table = manifest.tables[tableName];
+    const typeName = utils.snakeToCamelCase(tableName);
+    const columns = tableColumns[tableName];
+    const relations = tableRelations[tableName];
+    const rowLines = [`/** Row of \`${manifest.name}.${tableName}\`. */`, `export interface ${typeName}Row {`];
+    for (const [name, tsType] of domainSystemColumns) rowLines.push(`  ${name}: ${tsType};`);
+    for (const c of columns) rowLines.push(`  ${c.name}${c.required ? '' : '?'}: ${c.tsType};`);
+    rowLines.push('}');
+    decls.push(rowLines.join(sep));
+    const insertLines = [`/** Insert payload for \`${manifest.name}.${tableName}\`. */`, `export interface ${typeName}Insert {`];
+    for (const c of columns) insertLines.push(`  ${c.name}${c.required ? '' : '?'}: ${c.insertType};`);
+    for (const r of relations) insertLines.push(`  /** Link set: \`${r.target}\` row ids. */`, `  ${r.name}?: string[];`);
+    if (table.idempotency === true) insertLines.push('  idempotencyKey?: string;');
+    insertLines.push('}');
+    decls.push(insertLines.join(sep));
+
+    // Relations are write-side values, not columns: a patch takes them alongside
+    // the declared ones (set-replace over the links the caller can see), while
+    // reads surface them through the expand map below.
+    if (relations.length > 0) {
+      const updateLines = [`/** Update payload for \`${manifest.name}.${tableName}\`: declared ` + `columns plus relation link sets (each REPLACES the links you can see). */`, `export type ${typeName}Update = Partial<${typeName}Row> & {`];
+      for (const r of relations) updateLines.push(`  ${r.name}?: string[];`);
+      updateLines.push('};');
+      decls.push(updateLines.join(sep));
+    }
+    decls.push(formatColumnUnion(`${typeName}Column`, [...domainSystemColumns.map(([name]) => name), ...columns.map(c => c.name)]));
+
+    // Expand map: MUST stay a `type` alias — object-type literals carry the implicit
+    // index signature the `TExpand extends {[key: string]: {}}` constraint needs
+    // (an interface would fail it).
+    const expandEntries = [];
+    for (const c of columns) {
+      if (c.ref == null) continue;
+      const fields = tableColumns[c.ref].map(tc => `'${c.name}.${tc.name}'?: ${tc.tsType}`);
+      expandEntries.push(wrapTokens(`  '${c.name}': {`, fields, '; ', '};', '    '));
+    }
+    // A relation expands to the capped, display-name-ordered link array; the d42
+    // form (queryDf) flattens it into a chips column plus its '~<name>.id' companion.
+    // The link shape stays INLINE (structurally DG.DomainRelationLink): generated
+    // files must compile against the datagrok-api the package depends on, which may
+    // predate that interface.
+    for (const r of relations) expandEntries.push(`  '${r.name}': {${r.name}?: {id: string; name: string}[]};`);
+    for (const childName of tableNames) {
+      const fks = tableColumns[childName].filter(c => c.ref === tableName);
+      if (fks.length === 0) continue;
+      const childType = utils.snakeToCamelCase(childName);
+      if (fks.length === 1) expandEntries.push(`  'details:${childName}': {${childName}?: ${childType}Row[]};`);else for (const fk of fks) expandEntries.push(`  'details:${childName}.${fk.name}': {${childName}?: ${childType}Row[]};`);
+    }
+    decls.push(expandEntries.length === 0 ? `export type ${typeName}Expand = {};` : [`/** Expand keys of \`${manifest.name}.${tableName}\` → fields each adds to the row ` + `(consumed by query()/builder). */`, `export type ${typeName}Expand = {`, ...expandEntries, '};'].join(sep));
+    txArms.push(`  {op: 'insert'; table: '${tableName}'; ref?: string; values: DG.DomainTxValues<${typeName}Insert>} |`, `  {op: 'update'; table: '${tableName}'; id: string; ` + `values: DG.DomainTxValues<${relations.length > 0 ? `${typeName}Update` : `Partial<${typeName}Row>`}>; ` + `expectedVersion?: number} |`, `  {op: 'delete'; table: '${tableName}'; id: string} |`);
+
+    // No datetime config: the client resolves datetime columns from the domain
+    // registry itself (the Dayjs typing in <Table>Row stays true for every client).
+    // The fifth generic is the update payload — only a relation-bearing table has
+    // one of its own; without relations the client's `Partial<Row>` default is it.
+    clients.push(`  get ${tableProp(tableName)}() {`, `    return grok.dapi.domains.table<${typeName}Row, ${typeName}Insert, ` + `${typeName}Column, ${typeName}Expand` + `${relations.length > 0 ? `, ${typeName}Update` : ''}>('${manifest.name}.${tableName}');`, '  },');
+  }
+  const schemaType = utils.snakeToCamelCase(manifest.name);
+  const lastArm = txArms.pop();
+  txArms.push(lastArm.replace(/ \|$/, ';'));
+  decls.push([`export type ${schemaType}TransactionOp =`, ...txArms].join(sep));
+  decls.push([`/** Typed clients for the \`${manifest.name}\` domain schema tables ` + `(lazy — no import-time side effects). */`, `export const ${utils.snakeToCamelCase(manifest.name, false)}Db = {`, ...clients, `  transaction<T extends ${schemaType}TransactionOp[]>(ops: [...T]):`, `      Promise<{[K in keyof T]: DG.DomainOpResultFor<T[K]>}> {`, `    return grok.dapi.domains.transaction('${manifest.name}', ops) as`, `      Promise<{[K in keyof T]: DG.DomainOpResultFor<T[K]>}>;`, '  },', '};'].join(sep));
+  return decls.join(sep.repeat(2)) + sep;
+}
+
+/** Emits the typed UI sugar of one manifest: per-table option types and a `<table>Ui`
+ * wrapper over the reflective `@datagrok-libraries/domain-ui` components, so app code gets
+ * this table's columns and row type checked. Collects the names it needs from `db.ts` into
+ * [dbImports]. Nothing here is imported by `db.ts` — data-only consumers gain no UI
+ * dependency. */
+function generateDomainUiCode(manifest, dbImports) {
+  const decls = [];
+  const schemaClient = `${utils.snakeToCamelCase(manifest.name, false)}Db`;
+  dbImports.push(schemaClient);
+  for (const tableName of Object.keys(manifest.tables)) {
+    const type = utils.snakeToCamelCase(tableName);
+    const address = `${manifest.name}.${tableName}`;
+    // The generics of the client and the handle, in DomainTableClient's order. The
+    // fifth — the update payload — exists only for a relation-bearing table, whose
+    // update() also takes the link sets; without relations the `Partial<Row>`
+    // default is it. Emitting four there would make `update(id, {labels: [...]})`
+    // an excess-property error against a payload that has no `labels`.
+    const hasRelations = Object.keys(manifest.tables[tableName].relations ?? {}).length > 0;
+    const generics = `${type}Row, ${type}Insert, ${type}Column, ${type}Expand` + (hasRelations ? `, ${type}Update` : '');
+    const handle = `DomainTable<${generics}>`;
+    dbImports.push(`${type}Column`, `${type}Expand`, `${type}Insert`, `${type}Row`);
+    if (hasRelations) dbImports.push(`${type}Update`);
+    decls.push([`/** Query spec of \`${address}\` — columns and expand keys are compile-checked. */`, `export type ${type}QuerySpec = DG.DomainQuerySpec<${type}Column, keyof ${type}Expand & string>;`].join(sep), [`/** {@link DG.DomainQuery} parameters of \`${address}\` (schema and table are implied). */`, `export interface ${type}QueryParams extends`, `    Omit<DG.DomainQueryParams, 'schema' | 'table' | 'columns'> {`, `  columns?: ${type}Column[];`, '}'].join(sep), [`/** Options of {@link ${type}Ui.form} / {@link ${type}Ui.formDialog}. */`, `export interface ${type}FormOptions extends Omit<DomainFormOptions, 'values'> {`, `  values?: Partial<${type}Insert>;`, '}'].join(sep), [`/** Options of {@link ${type}Ui.grid}. */`, `export interface ${type}GridOptions extends Omit<DomainGridOptions, 'query' | 'defaults'> {`, `  query?: ${type}QuerySpec;`, `  defaults?: Partial<${type}Insert>;`, '}'].join(sep), [`/** Options of {@link ${type}Ui.list}. */`, `export interface ${type}ListOptions extends Omit<EntityListOptions, 'query'> {`, `  query?: ${type}QuerySpec;`, '}'].join(sep), [`/** Options of {@link ${type}Ui.listView} / {@link ${type}Ui.app}. */`, `export interface ${type}AppViewOptions extends Omit<DomainAppViewOptions, 'query'> {`, `  query?: ${type}QuerySpec;`, '}'].join(sep), ['/**', ` * Typed UI over \`${address}\`: the reflective components of`, ' * `@datagrok-libraries/domain-ui`, with this table\'s columns and row type checked at', ` * compile time. Reach it through {@link ${utils.snakeToCamelCase(tableName, false)}Ui}.`, ' */', `export class ${type}Ui {`, `  /** The table address, \`'<schema>.<table>'\`. */`, `  readonly address: string = '${address}';`, '', `  /** The typed client — the same one \`${schemaClient}.${tableProp(tableName)}\` returns. */`, `  get client(): DG.DomainTableClient<${generics}> {`, `    return ${schemaClient}.${tableProp(tableName)};`, '  }', '', `  /** The prefetched handle on \`${address}\` — THE async boundary, typed. Every`, '   * widget factory on it is synchronous, so acquire it ONCE when a page builds', '   * more than one widget; the shortcuts below acquire one of their own. */', `  table(): Promise<${handle}> {`, `    return domains.table<${generics}>(this.client);`, '  }', '', '  /** The handler registered for the table (the reflective default when none is). */', '  handler(): DG.DomainObjectHandler {', '    return domainHandler(this.address);', '  }', '', '  /** The property form of ONE row — a new one by default, an existing one with', '   * `{row}` or `{id}`; the values are this table\'s. */', `  async form(options?: ${type}FormOptions): Promise<DomainForm> {`, '    return (await this.table()).form(options);', '  }', '', '  /** {@link form} in a dialog; resolves to whether a row was saved. */', `  async formDialog(options?: ${type}FormOptions & DomainDialogOptions): Promise<boolean> {`, '    return (await this.table()).formDialog(options);', '  }', '', '  /** The browse/CRUD page: list, search, New, and a deep-linkable query. */', `  async listView(options?: ${type}AppViewOptions): Promise<DomainAppView> {`, '    return (await this.table()).listView(options);', '  }', '', '  /** THE app — {@link listView} under the name that says what it is. */', `  app(options?: ${type}AppViewOptions): Promise<DomainAppView> {`, '    return this.listView(options);', '  }', '', '  /** The row page: form, detail tabs, history. Takes the row or its id. */', '  async entityView(row: string | DG.DomainRow,', '    options?: DomainEntityAppViewOptions): Promise<DomainEntityAppView> {', '    return (await this.table()).entityView(row, options);', '  }', '', '  /** An editable grid: batch editing, one-transaction save. */', `  async grid(options?: ${type}GridOptions): Promise<DomainGrid> {`, '    return (await this.table()).grid(options);', '  }', '', '  /** A list of rows (cards / brief / grid). */', `  async list(options?: ${type}ListOptions): Promise<EntityListWidget> {`, '    return (await this.table()).list(options);', '  }', '', '  /** Opens the platform\'s create dialog, or the edit dialog for [row]. */', '  edit(row?: DG.DomainRow): Promise<boolean> {', '    return this.handler().editRow(row);', '  }', '', '  /** Opens the platform\'s row picker. */', '  pick(): Promise<DG.DomainRow | null> {', '    return this.handler().pickRow();', '  }', '', '  /** Wraps one `query()` row as a {@link DG.DomainRow} — locally, no round trip. */', `  row(values: Partial<${type}Row> | null): DG.DomainRow {`, '    return this.handler().rowFrom(values);', '  }', '', '  /** A serializable query over the table: deep links, saved filters, Open in Table View. */', `  query(params?: ${type}QueryParams): DG.DomainQuery {`, `    return new DG.DomainQuery({...params, schema: '${manifest.name}', table: '${tableName}'});`, '  }', '}'].join(sep), [`/** Typed UI over \`${address}\` (see {@link ${type}Ui}). */`, `export const ${utils.snakeToCamelCase(tableName, false)}Ui = new ${type}Ui();`].join(sep));
+  }
+
+  // The schema-level handle: every table's DomainTable under ONE await, typed
+  // (`const db = await <schema>UiDb(); db.<plural>.form(...)`).
+  const schemaType = utils.snakeToCamelCase(manifest.name);
+  const tableProps = Object.keys(manifest.tables).filter(t => !domainDbReservedProps.includes(tableProp(t)));
+  decls.push(['/**', ` * The typed schema handle over \`${manifest.name}\`: one prefetched {@link DomainTable}`, ' * per table, resolved together by {@link ' + utils.snakeToCamelCase(manifest.name, false) + 'UiDb} —', ' * the schema-level async boundary (see `domains.db`).', ' */', `export interface ${schemaType}UiDb extends DomainDb {`, ...tableProps.map(t => {
+    const type = utils.snakeToCamelCase(t);
+    const update = Object.keys(manifest.tables[t].relations ?? {}).length > 0 ? `, ${type}Update` : '';
+    return `  readonly ${tableProp(t)}: ` + `DomainTable<${type}Row, ${type}Insert, ${type}Column, ${type}Expand${update}>;`;
+  }), '}'].join(sep), [`/** Acquires the {@link ${schemaType}UiDb} handle — every table of`, ` * \`${manifest.name}\`, prefetched together (see \`domains.db\`). */`, `export function ${utils.snakeToCamelCase(manifest.name, false)}UiDb(): Promise<${schemaType}UiDb> {`, `  return domains.db('${manifest.name}') as Promise<${schemaType}UiDb>;`, '}'].join(sep));
+  return decls.join(sep.repeat(2)) + sep;
+}
+
+/** Joins [tokens] into `<prefix>t1<sepToken>t2...<suffix>` lines wrapped at the 120-char
+ * limit with a hanging [indent]. */
+function wrapTokens(prefix, tokens, sepToken, suffix, indent = '  ') {
+  const lines = [];
+  let line = prefix;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i] + (i < tokens.length - 1 ? sepToken : suffix);
+    if (line.length + token.length > 118 && line.trim().length > 0) {
+      lines.push(line.trimEnd());
+      line = indent;
+    }
+    line += token;
+  }
+  lines.push(line);
+  return lines.join(sep);
+}
+
+/** Formats `export type <name> = 'a' | 'b' | ...;` wrapped to the 120-char line limit. */
+function formatColumnUnion(name, values) {
+  const lines = [];
+  let line = `export type ${name} = `;
+  for (let i = 0; i < values.length; i++) {
+    const token = `'${values[i]}'` + (i < values.length - 1 ? ' | ' : ';');
+    if (line.length + token.length > 118) {
+      lines.push(line.trimEnd());
+      line = '  ';
+    }
+    line += token;
+  }
+  lines.push(line);
+  return lines.join(sep);
+}
 function api(args) {
   color.setVerbose(args.verbose || args.v || false);
   _package = JSON.parse(_fs.default.readFileSync(packagePath, {
     encoding: 'utf-8'
   }));
   if (_package.friendlyName) _package.friendlyName = _package.friendlyName.replaceAll(' ', '');
-  const nOptions = Object.keys(args).length - 1 - (args.verbose ? 1 : 0) - (args.v ? 1 : 0);
+  const nOptions = Object.keys(args).length - 1 - (args.verbose ? 1 : 0) - (args.v ? 1 : 0) - (args.ui ? 1 : 0);
   if (args['_'].length !== 1 || nOptions > 0) return false;
   if (!utils.isPackageDir(process.cwd())) {
     color.error('File `package.json` not found. Run the command from the package directory');
@@ -146,5 +523,7 @@ function api(args) {
   generateScriptWrappers();
   generateQueryWrappers();
   generateFunctionWrappers();
-  return true;
+  return generateDomainClients(curDir, {
+    ui: args.ui ?? false
+  });
 }

package/bin/commands/help.js

@@ -78,6 +78,8 @@ Usage: grok add <entity> <name>
 Add an object template to your package:
 
 grok add app <name>
+grok add app [name] --domain <schema>[.<table>]
+grok add app [name] --domain <path to schema.json>
 grok add connection <name>
 grok add detector <semantic-type-name>
 grok add function [tag] <name>
@@ -89,6 +91,15 @@ grok add tests
 
 Please note that entity names may only include letters and numbers
 
+--domain scaffolds a working browse/CRUD app over an entity-mapped domain table
+(\`grok.dapi.domains\`) from the \`@datagrok-libraries/domain-ui\` defaults. Give it
+one table (\`--domain grit.issue\`), a whole schema the package declares in
+\`databases/<schema>/schema.json\` (one app per table), or the path to a schema
+manifest to copy into the package. A fresh app package is two commands:
+
+grok create MyTracker
+cd MyTracker && grok add app --domain grit.issue
+
 Supported languages for scripts:
 javascript, julia, node, octave, python, r
 
@@ -113,12 +124,18 @@ Options:
 const HELP_API = `
 Usage: grok api
 
-Create wrapper functions for package scripts and queries
+Create wrapper functions for package scripts and queries.
+Packages with \`databases/<schema>/schema.json\` manifests also get typed domain
+clients in \`src/generated/db.ts\`.
 
 Options:
-[-v | --verbose]
+[-v | --verbose] [--ui]
 
 --verbose         Print detailed output
+--ui              Also generate \`src/generated/db-ui.ts\` — typed UI wrappers over
+                  \`@datagrok-libraries/domain-ui\` for every domain table. Once the
+                  file exists, plain \`grok api\` keeps it up to date; delete it to
+                  opt out again
 `;
 const HELP_CONFIG = `
 Usage: grok config