datagrok-tools 6.7.8 → 6.7.9

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> datagrok-tools@6.7.8 build /home/runner/work/public/public/tools
+> datagrok-tools@6.7.9 build /home/runner/work/public/public/tools
 > node build.js
 
-Successfully compiled 51 files with Babel.
+Successfully compiled 52 files with Babel.

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Datagrok-tools changelog
 
+## v.next
+
+* Upgraded Puppeteer to v25, which drops the vulnerable `extract-zip` and `basic-ftp` transitive dependencies; Node.js 22.12+ is now required
+* `grok add app --domain`, `grok api --ui`: scaffold against `@datagrok-libraries/ems`
+* GROK-20884: Added `grok s o errors get <signature|problem>`: each occurrence of an error with its time, user, function and session, so an error incident leads to its calls
+* GROK-20884: Added `grok s o logs container [<name|id>]`: a docker container's log lines cut by `--since`/`--from`/`--to` and `--grep`; no name lists the containers
+* GROK-20884: `grok s o problems get` prints one field per line with every detail in full, and `errors top --limit` returns that many rows instead of the top of every source
+* GROK-20884: Added `grok s observe` (alias `grok s o`): problems and their alerts, problem rules, logger settings with expiring user and group entries, errors, the timeline and cloud logs (CloudWatch and the log archive)
+* GROK-20884: Added `grok s o logs capture <login|group> [--for 30m]`: saves every API request of a user or a group until the entry expires (a `logger set` of `saveHttpRequests`; an entry that expires later keeps its time); `logs capture stop` removes an expiring entry that holds only the capture, `logs capture` lists the active ones
+* GROK-20298: `grok s domains apply` sends the manifest JSON's `version` as the now-required `ifVersion` of a user-managed schema, accepts `--if-version current` to take the registered one, refuses such an apply without either, and forwards `friendlyName`, `description` and `storage` from the JSON for a user-managed schema (a package schema keeps its key set)
+* GROK-20298: `domain-schema.schema.json` accepts the root `storage` key (`{kind: external, connection, schema?, catalog?}`) and the remote-name keys `table`/`column`; `grok api` types an external table's rows with `id` only, an empty expand map, and emits no `<Schema>TransactionOp`/`transaction` for an external schema
+
 ## 6.7.8 (2026-10-13)
 
 * Fixed `grok api` (and every command other than `grok s`) exiting with code 1 and its usage text in 6.7.7: the new `--send-email` flag reached every command as `send-email: false`, which `grok api` rejected as an unknown option

package/CLAUDE.md

@@ -121,6 +121,18 @@ When a package has a `dockerfiles/` directory, `grok publish` automatically mana
 
 **Practical implication:** editing any file inside `dockerfiles/<name>/` will cause `grok publish` to rebuild that container image on the next publish, without needing `--rebuild-docker`.
 
+**Publish traps:**
+- `grok publish` runs `npm run build` / `pnpm run build` itself (`buildPackage`); `--skip-check`
+  only skips checks, and `--rebuild` skips the local build rather than forcing one.
+- With no local image and a transient error on the fallback lookup, CLI <= 6.5.10 published
+  `image: null` and the container went to `error`; 6.5.11+ builds instead.
+- A republish renames a package's containers to `<name>_1`.
+- Outside the pnpm workspace, a fresh `npm install` in a package may pull ts-loader 9.6.x /
+  webpack 5.109, which cannot resolve `datagrok-api/*` (tsc can); reuse a known-good
+  `node_modules` (ts-loader 9.5.7 / webpack 5.106) and junction `node_modules/datagrok-api` to a
+  built js-api (`cmd /c mklink /J`).
+- Long publishes outlive a 10-minute agent tool limit; run them detached and poll a log.
+
 ### Testing Framework
 
 Tests use Puppeteer for headless browser automation:

package/GROK_S.md

@@ -36,6 +36,7 @@ browser or a logged-in session.
 | See what fields an entity type has                          | `grok s describe connections`                          |
 | Hit any undocumented endpoint                               | `grok s raw GET /users/current` / `raw POST <path> --data '{...}'` |
 | Check server + per-module health                            | `grok s healthcheck [--module <name>]`                 |
+| Problems, alerts, problem rules, logger settings, errors, cloud logs | `grok s observe problems list --alert-status open` (alias `grok s o`) |
 | Bulk operations in one round-trip                           | `grok s batch <entity> <verb> --json items.json`       |
 | Move entities dev to prod (bundle, or instance to instance) | `grok s pull ... --out ./bundle` / `grok s migrate ... --from dev --to prod` |
 | Browse / query / edit domain-table rows                    | `grok s domains query grit.issue --filter 'status = "open"'` / `domains insert` / `domains upload` |
@@ -136,6 +137,18 @@ grok s connections test --json conn.json              # test before saving
 
 See `public/packages/Chembl/connections/` for connection JSON examples.
 
+Connection tags over REST: the entity JSON carries `entityTags`
+(`[{id, tag, owner: {id: <All users group id>}}]`, no `#type` on the owner), not `tags`.
+`grok s connections save --json` without `entityTags` **clears** the tags (saveTags deletes rows
+not in the list); `POST /entities/save_tags {id, entityTags}` sets them. Filter with
+`whereTag([...])` (`?tags=x`); `whereSmart('tag = "x"')` returns nothing for connections over REST.
+A `Web` connection's parameters must be wrapped (`{"url": {"value": "https://..."}}`); a bare
+string makes the test route answer 400 "Invalid argument(s): value".
+
+A connection saved over REST goes through `Project.add(uniqueName: true)` and can come back
+renamed `<name>_1` for a package's connection — see `core/docs/PROJECTS_AND_PACKAGES.MD`
+"Package connections on a stand".
+
 ## Group membership
 
 `grok s groups add-members` is idempotent — it resolves each member (by login, name,
@@ -161,6 +174,12 @@ ambiguous the command prints every matching group and exits non-zero — pass a
 disambiguate, or add `--user` (accepted by all four membership verbs) to restrict lookup to
 personal groups.
 
+> **Trap:** `grok s groups add-members <group> <users...>` without `--admin` sets `isAdmin=false`
+> on members that are already group admins (reported as `updated`, not `noop`). Before a bulk add
+> run `grok s groups list-members <group> --admin` and exclude those users, or re-add them with
+> `--admin`. Pass the group UUID — `list-members Administrators` by name has returned
+> "(no results)" while the id worked.
+
 ## User administration
 
 ```bash
@@ -411,12 +430,19 @@ grok s domains audit inventory --limit 50                        # DDL and row e
 grok s domains delete inventory --force                          # purge: data, audit, registry, grants
 ```
 
-`schema.json` may be a full manifest or a partial apply body — only `tables`, `extend`,
-`propertySchemas` and `dropTables` are sent; `name`, `version` and `description` are dropped.
-Named tables replace their definition wholesale; untouched tables stay as the registry has
-them. A plan that drops or narrows anything is refused until `--confirm-destructive` is
-passed, and the plan is printed with the refusal. `--if-version` fails the apply when the
-schema's apply counter (or `ext_version` on a package schema) has moved. Package-deployed
+`schema.json` may be a full manifest or a partial apply body — `tables`, `extend`,
+`propertySchemas`, `dropTables` and `access` are sent, plus `friendlyName`, `description` and
+`storage` when the schema is user-managed (`name` is dropped; `version` becomes `ifVersion` and
+`incarnation` becomes `ifIncarnation` unless `--if-version` says otherwise — `current` takes
+both from the schema registered right now, so a name deleted and re-created since the file was
+written is a conflict, not a fresh `1`). Named tables
+replace their definition wholesale; untouched tables stay as the registry has them. A plan
+that drops or narrows anything is refused until `--confirm-destructive` is passed, and the
+plan is printed with the refusal. `--if-version` fails the apply when the schema's apply
+counter (or `ext_version` on a package schema) has moved; a user-managed schema REQUIRES the
+token (the server answers `version-required` without it) — pass the version the edit was made
+against, or `--if-version current` to take the one registered right now. Dropping a table
+needs Delete on that table, dropping its columns Edit on it. Package-deployed
 schemas cannot be applied to or deleted here — `apply` on one is the user-extension path
 (needs `Extend`), and the manifest is owned by `grok publish`. `delete <schema>` requires
 `--force` because it takes every row with it.
@@ -471,6 +497,44 @@ module the server does not report exits 1. Requires a valid dev key (standard `g
 For an anonymous liveness probe — load balancer, k8s readiness — hit `/admin/health` directly;
 it's on the server's unauthenticated allowlist.
 
+## Problems, logging and errors (`grok s observe`, alias `grok s o`)
+
+Thin commands over the server's routes; `grok s observe` with no command prints every verb and option.
+
+```bash
+grok s o problems list --alert-status open                 # the open alerts; --status, --state, --kind, --since 7d
+grok s o problems get 'health:Jupyter@<server>'            # by id or kind:key; history <id> for its records
+grok s o problems status connection:<connection id> --data '{"status": "muted", "reason": "maintenance", "until": "2026-10-04T06:00:00Z"}'
+grok s o problems ack 'health:Jupyter@<server>' --reason x  # resolve <id> --reason ... closes the alert
+grok s o rules get > rules.json                             # Settings > Alerts problem rules; rules put --json rules.json
+grok s o rules test                                         # evaluates the saved rules once, now
+grok s o logger get exportSettings                          # the logger settings, or one path of them
+grok s o logger set --user alice --set debugFlags='["db"]' --for 30m --reason "ticket 123"   # an expiring entry, from All users
+grok s o logger set --user alice --remove                  # delete that entry
+grok s o logger history --limit 5                           # log-settings-changed audit records with their diff
+grok s o logs capture alice --for 2h --reason "ticket 123" # logger set of saveHttpRequests on an expiring entry; 30m by default
+grok s o logs capture                                       # the active captures; logs capture stop alice removes one
+grok s o errors top --since 7d --by signature --limit 20    # GET /admin/metrics errors
+grok s o errors top --since 24h --source server           # ranked by distinct users: system errors (scheduler, probes) need --source
+grok s o errors get error-incident:<key>                    # each occurrence of a problem's error: time, user, function, session
+grok s o errors get <signature> --since 1d                  # or of a signature from errors top --by signature
+grok s o timeline --session <id>                            # its events and requests of the last 15 min
+grok s o timeline --session <id> --from 2026-10-09T10:00     # 10 min from then; --to sets the end, at most 2 h later
+grok s o logs cloud --since 2h --filter ERROR                # CloudWatch, the instance's own group; --group, --from/--to
+grok s o logs archive list --prefix cw/ --since 1d           # keys in the log archive (WORM bucket); --since filters the returned page only
+grok s o logs archive read <key>                             # one archived object decoded to events
+grok s o logs container                                      # docker containers and their status
+grok s o logs container scripting-python_1 --since 1h --grep 'Kernel (started|shutdown)'   # one container's log lines
+```
+
+Problems need `ManageAlerts`, errors, another session's timeline and `logs cloud`/`logs archive` `ViewTelemetry`,
+`rules test` both, logger and rules changes and `logs capture` `EditPluginsSettings`. `capture` is an expiring
+`userGroupSettings` entry with `saveHttpRequests` on (seeded from the All Users entry, with `usage` saved); on an entry
+that already expires later it keeps that time. `capture stop` removes only an expiring entry that holds nothing but the
+capture; for any other entry use `logger set --user <login> --remove`. Read what it recorded with
+`timeline --session <id>`. `logs container` reads the container's latest `--limit` lines (20000) and only then cuts `--since`/`--from`/`--to` (UTC, matched across the container's own offset) and `--grep`, so a window older than those lines comes back empty: raise `--limit`. `logs archive list --since` filters only the page the server returned (`--limit`), so narrow
+the listing with `--prefix` first. `logs` read with the server's AWS role, or with `--connection <id>`. In durations `m` means minutes (in `grok s pull --since` it means months).
+
 ## Describing an entity type
 
 ```bash

package/bin/commands/add.js

@@ -16,8 +16,7 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * answer key): u2 is not on npm, so the dependency is the workspace link, and `u2core` is the one
  * external `@datagrok/build-config` does not know about. The css imports and the tsconfig need
  * nothing — the shared bundler config carries the loaders and the tsconfig extends the base. */
-const u2Dependency = 'workspace:^';
-const u2DgModule = '@datagrok-libraries/u2/src/dg/index.js';
+const emsDgModule = '@datagrok-libraries/ems/src/dg';
 const u2RspackExternal = `'datagrok-api/u2core': 'DG.U2'`;
 const u2RspackConfig = [`const {bundler} = require('@datagrok/build-config');`, '', `module.exports = bundler({externals: {${u2RspackExternal}}});`, ''].join('\n');
 function add(args) {
@@ -110,7 +109,7 @@ function add(args) {
    * existing imports (which webpack's externals depend on). */
   function addU2Imports() {
     const contents = _fs.default.readFileSync(packageEntry, 'utf8');
-    if (contents.includes(u2DgModule)) return;
+    if (contents.includes(emsDgModule)) return;
     const eol = contents.includes('\r\n') ? '\r\n' : '\n';
     const imports = _fs.default.readFileSync(_path.default.join(templateDir, 'entity-template', 'domain-app-imports.js'), 'utf8').trimEnd().split(/\r?\n/);
     const lines = contents.split(/\r?\n/);
@@ -125,7 +124,8 @@ function add(args) {
   function addU2Wiring() {
     const packageObj = JSON.parse(_fs.default.readFileSync(packagePath, 'utf8'));
     packageObj.dependencies = packageObj.dependencies ?? {};
-    packageObj.dependencies['@datagrok-libraries/u2'] ??= u2Dependency;
+    packageObj.dependencies['@datagrok-libraries/ems'] ??= 'workspace:^';
+    packageObj.dependencies['@datagrok-libraries/u2'] ??= 'workspace:^';
     _fs.default.writeFileSync(packagePath, JSON.stringify(packageObj, null, 2), 'utf8');
     if (!_fs.default.existsSync(rspackConfigPath)) _fs.default.writeFileSync(rspackConfigPath, u2RspackConfig, 'utf8');else if (!_fs.default.readFileSync(rspackConfigPath, 'utf8').includes('datagrok-api/u2core')) color.warn(`rspack.config.js is already there — add \`externals: {${u2RspackExternal}}\` to it by hand`);
   }

package/bin/commands/api.js

@@ -24,7 +24,7 @@ const dbFile = 'db.ts';
 const dbUiFile = 'db-ui.ts';
 /** Where `db-ui.ts` takes the u2 domain stack from — the same specifier Grit and Stockroom use
  * (u2 is a relative-path dependency without a `dg` subpath export). */
-const u2DgModule = '@datagrok-libraries/u2/src/dg/index.js';
+const emsDgModule = '@datagrok-libraries/ems/src/dg';
 
 /** Naive English plural of a (snake_case) table name — `issue` → `issues`, `box` →
  * `boxes`, `category` → `categories`. */
@@ -229,7 +229,7 @@ function generateDomainClients(packageDir = curDir, options) {
   _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 {domains, DomainTable} from '${u2DgModule}';${sep}` + wrapTokens(`import {`, dbImports, ', ', `} from './${dbFile.replace(/\.ts$/, '')}';`) + sep + sep + uiParts.join(sep);
+    const uiContent = annotationForDbUiFile + `import {domains, DomainTable} from '${emsDgModule}';${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');
   }
@@ -265,6 +265,10 @@ function findDependencyManifest(packageDir, schemaName) {
 function generateDomainSchemaCode(manifest, manifestPath, emittedTypes, packageDir) {
   const decls = [];
   const systemColumnNames = new Set(domainSystemColumns.map(([name]) => name));
+  // An external table's rows carry `id` (the encoded business key) and nothing else
+  // system-side; nothing is expanded and nothing is written (external-bindings §3).
+  const external = manifest.storage?.kind === 'external';
+  const systemColumns = external ? domainSystemColumns.filter(([name]) => name === 'id') : domainSystemColumns;
   const tableNames = Object.keys(manifest.tables);
   // Keyed by table name; a qualified ref target ('Core.queries', 'grit.issue') lands here
   // under its qualified key so the expand map can list its columns — it gets no accessor.
@@ -427,7 +431,7 @@ function generateDomainSchemaCode(manifest, manifestPath, emittedTypes, packageD
     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 [name, tsType] of systemColumns) rowLines.push(`  ${name}: ${tsType};`);
     for (const c of columns) rowLines.push(`  ${c.name}${c.required || c.autoNumber ? '' : '?'}: ${c.tsType};`);
     rowLines.push('}');
     decls.push(rowLines.join(sep));
@@ -447,13 +451,13 @@ function generateDomainSchemaCode(manifest, manifestPath, emittedTypes, packageD
       updateLines.push('};');
       decls.push(updateLines.join(sep));
     }
-    decls.push(formatColumnUnion(`${typeName}Column`, [...domainSystemColumns.map(([name]) => name), ...columns.map(c => c.name)]));
+    decls.push(formatColumnUnion(`${typeName}Column`, [...systemColumns.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) {
+    for (const c of external ? [] : 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, '; ', '};', '    '));
@@ -463,15 +467,15 @@ function generateDomainSchemaCode(manifest, manifestPath, emittedTypes, packageD
     // 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) {
+    for (const r of external ? [] : relations) expandEntries.push(`  '${r.name}': {${r.name}?: {id: string; name: string}[]};`);
+    for (const childName of external ? [] : 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>; ` + `onDuplicate?: 'error'} |`, `  {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} |`);
+    if (!external) txArms.push(`  {op: 'insert'; table: '${tableName}'; ref?: string; values: DG.DomainTxValues<${typeName}Insert>; ` + `onDuplicate?: 'error'} |`, `  {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).
@@ -480,10 +484,14 @@ function generateDomainSchemaCode(manifest, manifestPath, emittedTypes, packageD
     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));
+  const transaction = [];
+  if (!external) {
+    const lastArm = txArms.pop();
+    txArms.push(lastArm.replace(/ \|$/, ';'));
+    decls.push([`export type ${schemaType}TransactionOp =`, ...txArms].join(sep));
+    transaction.push(`  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]>}>;`, '  },');
+  }
+  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, '};'].join(sep));
   return decls.join(sep.repeat(2)) + sep;
 }
 

package/bin/commands/help.js

@@ -96,7 +96,7 @@ 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 u2 defaults (\`@datagrok-libraries/u2\`): a three-line
+(\`grok.dapi.domains\`) from the EMS defaults (\`@datagrok-libraries/ems\`): a three-line
 app function, a \`src/app.spec.json\` the designer edits, and — for a schema the package
 does not declare yet — a one-table starter \`databases/<schema>/schema.json\`. Give it
 one table (\`--domain tracker.issue\`), a whole schema the package declares in
@@ -140,7 +140,7 @@ Options:
 --verbose         Print detailed output
 --ui              Also generate \`src/generated/db-ui.ts\` — typed u2 handles
                   (\`get<Schema>Db()\` → a \`DomainTable<Row>\` per table, opened in
-                  parallel behind one await) over \`@datagrok-libraries/u2\`. Once the
+                  parallel behind one await) over \`@datagrok-libraries/ems\`. Once the
                   file exists, plain \`grok api\` keeps it up to date; delete it to
                   opt out again
 `;

package/bin/commands/server-domains.js

@@ -21,7 +21,9 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
 /// `grok s domains ...` — entity-mapped domain schemas and their rows (DomainsRouter, `/domains/`).
 /// Every verb addresses a schema as `<schema>` or a table as `<schema>.<table>`.
 
-const APPLY_KEYS = ['tables', 'extend', 'propertySchemas', 'dropTables', 'ifVersion', 'confirmDestructive'];
+const APPLY_KEYS = ['tables', 'extend', 'propertySchemas', 'dropTables', 'access', 'ifVersion', 'ifIncarnation', 'confirmDestructive'];
+/** Accepted by a user-managed schema's apply only; a package schema refuses them as unknown keys. */
+const USER_APPLY_KEYS = ['friendlyName', 'description', 'storage'];
 const PERMISSIONS = ['View', 'Edit', 'Delete', 'Share', 'Extend'];
 const USAGE = `Usage: grok s domains <verb> [args]
   list [<schema>] [--filter <text>]                      Schemas, or the tables of one schema
@@ -210,11 +212,23 @@ async function handleDomains(dapi, verb, rest, argv, output) {
       }
     case 'apply':
       {
-        if (!args[0] || !argv.json) return usage('apply <schema> --json manifest.json [--dry-run] [--confirm-destructive] [--if-version <v>]');
+        if (!args[0] || !argv.json) return usage('apply <schema> --json manifest.json [--dry-run] [--confirm-destructive] [--if-version <v>|current]');
         const a = (0, _nodeDapi.parseDomainAddress)(args[0], {
           table: false
         });
-        const body = applyBody(readJson(argv.json), argv);
+        const json = readJson(argv.json);
+        // One registry read, only when the token or the metadata keys depend on who manages the schema.
+        const s = argv['if-version'] === undefined || argv['if-version'] === 'current' || USER_APPLY_KEYS.some(k => json?.[k] !== undefined) ? await domains.schema(a.schema) : null;
+        const body = applyBody(json, argv, {
+          userManaged: s?.managedBy === 'user'
+        });
+        if (body.ifVersion === 'current') {
+          // Both halves of the token as registered now: a name deleted and re-created
+          // since the file was written must conflict, not pass as a fresh `1`.
+          const m = await domains.manifest(a.schema);
+          body.ifVersion = String(m?.version ?? s.version ?? '1');
+          if (m?.incarnation !== undefined) body.ifIncarnation = String(m.incarnation);
+        } else if (body.ifVersion === undefined && s.managedBy === 'user') return usage(`apply ${a.schema} --json manifest.json --if-version <v>|current — a user-managed schema ` + 'requires the version the edit was made against (the "version" of the manifest JSON is used when present)');
         printJson(await domains.applySchema(a.schema, body, argv['dry-run'] === true), output, r => r?.version);
         return true;
       }
@@ -305,12 +319,15 @@ function aggregateSpec(argv, filter, limit) {
   return spec;
 }
 
-/** The apply payload from a schema.json (or a partial body): only the keys the server accepts, flags folded in. */
-function applyBody(json, argv) {
+/** The apply payload from a schema.json (or a partial body): only the keys the server accepts
+ * (the schema's metadata and storage keys for a user-managed schema only), flags folded in. */
+function applyBody(json, argv, options = {}) {
   const body = {};
-  for (const k of APPLY_KEYS) if (json?.[k] !== undefined) body[k] = json[k];
+  for (const k of options.userManaged ? [...APPLY_KEYS, ...USER_APPLY_KEYS] : APPLY_KEYS) if (json?.[k] !== undefined) body[k] = json[k];
   if (argv['confirm-destructive'] === true) body.confirmDestructive = true;
-  if (argv['if-version'] !== undefined) body.ifVersion = String(argv['if-version']);
+  if (argv['if-version'] !== undefined) body.ifVersion = String(argv['if-version']);else if (json?.version !== undefined) body.ifVersion = String(json.version);
+  // The manifest's `incarnation` rides with its `version` (the server keeps it optional).
+  if (json?.incarnation !== undefined) body.ifIncarnation = String(json.incarnation);
   return body;
 }
 

package/bin/commands/server-observe.js

@@ -0,0 +1,526 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.OBSERVE_USAGE = void 0;
+exports.fieldRows = fieldRows;
+exports.handleObserve = handleObserve;
+exports.parseDuration = parseDuration;
+exports.parseTime = parseTime;
+exports.setPath = setPath;
+var fs = _interopRequireWildcard(require("fs"));
+var _nodeDapi = require("../utils/node-dapi");
+var _serverOutput = require("../utils/server-output");
+var _walker = require("../utils/migrate/walker");
+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); }
+/// `grok s observe` (alias `grok s o`): problems, problem rules, logger settings, errors, the timeline and cloud logs,
+/// over `/problems`, `/admin/plugins/<key>/settings`, `/alerts/Test_rules`, `/log`, `/admin/metrics`, `/log/timeline`,
+/// `/log/cloud/*`, `/log/archive/*` and `/docker/containers`.
+
+const OBSERVE_USAGE = exports.OBSERVE_USAGE = `Usage: grok s observe <command> <verb> [args]      (alias: grok s o)
+
+  problems list [--status <s>] [--state <s>] [--alert-status <s>] [--kind <k>] [--key <k>] [--since 7d] [--limit 100]
+                                       Comma lists or all; --alert-status open lists the open alerts
+  problems get <id|kind:key>           One field per line, details by path
+  problems history <id|kind:key> [--limit 50]
+  problems status <id|kind:key> --data '{"status": "muted", "reason": "...", "until": "<ISO>"}' | --json body.json
+  problems ack <id|kind:key> --reason <text>
+  problems resolve <id|kind:key> --reason <text>
+  rules get                            The problem rules (Settings > Alerts), as JSON
+  rules put --json rules.json          Replace them; the server checks them first
+  rules test                           Evaluate the saved rules once, now
+  logger get [<path>]                  The logger settings, or one value (exportSettings.0.types)
+  logger set --set <path>=<json> ...   Change values; with --user <login> or --group <name|id>, that
+             [--for 30m | --until <ISO>] [--reason <text>]   entry of userGroupSettings (a new one starts from
+             [--remove]                                       All users), removed when it expires; --remove deletes it
+  logger history [--limit 20]          The log-settings-changed audit records, with each change's diff
+  errors top [--since 24h | --date "this week" | --from <ISO> [--to <ISO>]] [--by message|signature]
+             [--package <name>] [--user <login>] [--source <s>] [--limit 10]
+                                       Ranked by distinct users, so errors nobody saw (scheduler, health
+                                       probes) come last: narrow those with --source server
+  errors get <signature|problem> [--since 7d] [--limit 50]
+                                       Each occurrence of an error (a signature from errors top, or the
+                                       id or kind:key of its problem): time, user, function, session
+  logs container [<name|id> [--since 1h | --from <ISO> [--to <ISO>]] [--grep <regex>] [--limit 20000]]
+                                       A docker container's log lines (its latest --limit, then the
+                                       window and --grep); no name, the containers and their status
+  timeline --session <id> [--from <ISO|-15m>] [--to <ISO>] [--limit 500]
+                                       A session's events and requests in a window: no --from, the last
+                                       15 min; --to defaults to --from + 10 min, at most 2 h
+  logs cloud [--group <g>] [--since 1h | --from <ISO> [--to <ISO>]] [--filter <pattern>] [--limit 1000]
+                                       CloudWatch events; no --group, the instance's own group;
+                                       --filter is a CloudWatch filter pattern
+  logs archive list [--prefix <p>] [--since 7d] [--limit n]
+                                       Objects in the log archive (WORM bucket), by key; --since filters
+                                       only the page the server returned, so narrow it with --prefix
+  logs archive read <key>              One archived object decoded to events
+                                       logs cloud and logs archive take [--connection <id>]; without it,
+                                       the instance's AWS role
+  logs capture [<login|group> [--for 30m] [--reason <text>]]
+                                       Save every API request of a user or a group for a while: logger set
+                                       of saveHttpRequests on their expiring entry (an entry that already
+                                       expires later keeps its time); no argument, the active captures;
+                                       read them with timeline --session <id>
+  logs capture stop <login|group>      Remove that expiring entry; one that holds other settings is left
+                                       to logger set --remove
+
+Durations are 30m (minutes), 24h, 7d, 2w; times are ISO 8601 (UTC without an offset) or
+relative, written with = (--from=-2h).`;
+const UNIT_MS = {
+  m: 60000,
+  h: 3600000,
+  d: 86400000,
+  w: 604800000
+};
+
+/** `30m`, `2h`, `7d`, `1w` in milliseconds; `m` is minutes, unlike `grok s pull --since`, where it is months. */
+function parseDuration(value, flag) {
+  const m = /^(\d+)([mhdw])$/.exec(String(value ?? '').trim());
+  if (!m || Number(m[1]) <= 0) throw new Error(`${flag} expects a duration such as 30m, 2h, 7d or 1w, got '${value}'`);
+  return Number(m[1]) * UNIT_MS[m[2]];
+}
+
+/** ISO 8601 (UTC without an offset), or relative to [now] (`-2h`). */
+function parseTime(value, flag, now = new Date()) {
+  let s = String(value ?? '').trim();
+  if (s.startsWith('-')) return new Date(now.getTime() - parseDuration(s.substring(1), flag));
+  if (/[T ].*[+-]\d{2}$/.test(s)) s = `${s}:00`;
+  const d = new Date(/^\d{4}-\d{2}-\d{2}$/.test(s) || /(Z|[+-]\d{2}:?\d{2})$/i.test(s) ? s : `${s}Z`);
+  if (!/^\d{4}-\d{2}-\d{2}/.test(s) || isNaN(d.getTime())) throw new Error(`${flag} expects an ISO time (2026-10-04T06:00) or a relative one (-2h), got '${value}'`);
+  return d;
+}
+
+/** `a.b.0.c=<json>` applied to [target]; a value that is not JSON is a string. */
+function setPath(target, assignment) {
+  const at = assignment.indexOf('=');
+  if (at <= 0) throw new Error(`--set expects <path>=<json>, got '${assignment}'`);
+  const keys = assignment.slice(0, at).split('.');
+  const text = assignment.slice(at + 1);
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    value = text;
+  }
+  let node = target;
+  for (const key of keys.slice(0, -1)) node = node[key] ??= {};
+  node[keys[keys.length - 1]] = value;
+  return keys[0];
+}
+function readBody(argv) {
+  if (argv.json) return JSON.parse(fs.readFileSync(argv.json, 'utf8'));
+  if (argv.data !== undefined) return JSON.parse(String(argv.data));
+  throw new Error('Expected a body: --data \'<json>\' or --json <file>');
+}
+const iso = (value, flag) => value === undefined ? undefined : parseTime(value, flag).toISOString();
+
+/** A record as `field, value` rows, nested objects by dotted path, so a table shows every value in full. */
+function fieldRows(record, prefix = '') {
+  const rows = [];
+  for (const [key, value] of Object.entries(record ?? {})) if (value !== null && typeof value === 'object' && !Array.isArray(value)) rows.push(...fieldRows(value, `${prefix}${key}.`));else rows.push({
+    field: `${prefix}${key}`,
+    value
+  });
+  return rows;
+}
+async function handleObserve(dapi, command, verb, rest, argv, output) {
+  // A `:` cannot pass through a route parameter behind the proxy, so kind:key is looked up by the list's filters.
+  let id;
+  const needId = async () => {
+    const given = rest[0] === undefined ? '' : String(rest[0]);
+    const colon = given.indexOf(':');
+    if (!given || colon === 0 || colon === given.length - 1) throw new Error(`Usage: grok s observe ${command} ${verb} <id|kind:key>`);
+    if (colon < 0) {
+      id = given;
+      return;
+    }
+    const found = await dapi.problems.list({
+      kind: given.substring(0, colon),
+      key: given.substring(colon + 1),
+      limit: 1
+    });
+    if (!found?.length) throw new Error(`No problem '${given}'`);
+    id = found[0].id;
+  };
+  const problemPath = () => `/problems/${encodeURIComponent(id)}`;
+  // The route answers JSON as text/plain.
+  const settings = async key => {
+    const r = await dapi.raw('GET', `/admin/plugins/${key}/settings`);
+    return (typeof r === 'string' ? JSON.parse(r) : r)?.settings ?? {};
+  };
+  // A save within 5 s of the previous one is refused (429) until that one is applied.
+  const saveSettings = async (key, body) => {
+    for (let attempt = 0;; attempt++) {
+      try {
+        return await dapi.raw('POST', `/admin/plugins/${key}/settings`, body);
+      } catch (e) {
+        if (attempt >= 2 || e?.apiError?.errorCode !== 429) throw e;
+        await new Promise(resolve => setTimeout(resolve, 5000));
+      }
+    }
+  };
+  const saveLogger = body => saveSettings('logger', body);
+  switch (`${command} ${verb}`) {
+    case 'problems list':
+      (0, _serverOutput.printOutput)(await dapi.problems.list({
+        status: argv.status,
+        state: argv.state,
+        alertStatus: argv['alert-status'],
+        kind: argv.kind,
+        key: argv.key,
+        since: argv.since,
+        limit: argv.limit
+      }), output);
+      return true;
+    case 'problems get':
+      {
+        await needId();
+        const problem = await dapi.problems.find(id);
+        if (!problem) throw new Error(`No problem '${rest[0]}'`);
+        (0, _serverOutput.printOutput)(output === 'table' ? fieldRows(problem) : problem, output);
+        return true;
+      }
+    case 'problems history':
+      await needId();
+      (0, _serverOutput.printOutput)(await dapi.raw('GET', `${problemPath()}/history${(0, _nodeDapi.buildQuery)({
+        limit: argv.limit
+      })}`), output);
+      return true;
+    case 'problems status':
+      await needId();
+      (0, _serverOutput.printOutput)(await dapi.raw('POST', `${problemPath()}/status`, readBody(argv)), output);
+      return true;
+    case 'problems ack':
+    case 'problems resolve':
+      await needId();
+      (0, _serverOutput.printOutput)(await dapi.raw('POST', `${problemPath()}/${verb}`, {
+        reason: argv.reason
+      }), output);
+      return true;
+    case 'rules get':
+      {
+        const rules = (await settings('alerts'))?.problemRules;
+        (0, _serverOutput.printOutput)(rules ? JSON.parse(rules) : [], output === 'table' ? 'json' : output);
+        return true;
+      }
+    case 'rules put':
+      {
+        const rules = readBody(argv);
+        await saveSettings('alerts', {
+          problemRules: typeof rules === 'string' ? rules : JSON.stringify(rules)
+        });
+        if (output !== 'quiet') console.log('Saved the problem rules');
+        return true;
+      }
+    case 'rules test':
+      console.log(await dapi.raw('POST', '/alerts/Test_rules'));
+      return true;
+    case 'logger get':
+      {
+        let value = await settings('logger');
+        for (const key of rest[0] ? String(rest[0]).split('.') : []) value = value?.[key];
+        (0, _serverOutput.printOutput)(value, output === 'table' ? 'json' : output);
+        return true;
+      }
+    case 'logger set':
+      return loggerSet(dapi, argv, await settings('logger'), saveLogger, output);
+    case 'logger history':
+      {
+        const text = encodeURIComponent('eventType.name = "log-settings-changed"');
+        const events = (await dapi.raw('GET', `/log?text=${text}&limit=${argv.limit ?? 20}&page=1`)) ?? [];
+        (0, _serverOutput.printOutput)(events.map(e => {
+          const params = {};
+          for (const p of e.parameters ?? []) params[p.parameter?.name] = p.value;
+          const row = {
+            time: e.eventTime,
+            user: params.user,
+            changed: params.changed
+          };
+          return output === 'table' ? row : {
+            ...row,
+            diff: params.diff ? (0, _nodeDapi.tryParseJson)(params.diff) ?? params.diff : null
+          };
+        }), output);
+        return true;
+      }
+    case 'errors top':
+      {
+        if (argv.since !== undefined && (argv.from !== undefined || argv.date !== undefined)) throw new Error('--since is not used with --from or --date');
+        if (argv.date !== undefined && argv.from !== undefined) throw new Error('--date is not used with --from');
+        const metrics = await dapi.raw('GET', `/admin/metrics${(0, _nodeDapi.buildQuery)({
+          date_start: argv.since !== undefined ? new Date(Date.now() - parseDuration(argv.since, '--since')).toISOString() : iso(argv.from, '--from'),
+          date_end: iso(argv.to, '--to'),
+          date: argv.date,
+          limit: argv.limit,
+          errors_by: argv.by,
+          package: argv.package,
+          user: argv.user,
+          source: argv.source
+        })}`);
+        // The server answers the top `limit` of every source, in the global order.
+        const top = (metrics?.errors?.top ?? []).slice(0, Number(argv.limit ?? 10));
+        (0, _serverOutput.printOutput)(output === 'json' ? {
+          ...metrics?.errors,
+          top
+        } : top, output);
+        return true;
+      }
+    case 'errors get':
+      {
+        if (rest[0] === undefined) throw new Error('Usage: grok s observe errors get <signature|problem id|kind:key> [--since 7d] [--limit 50]');
+        const given = String(rest[0]);
+        if (given.includes(':')) await needId();
+        const problem = await dapi.problems.find(id ?? given);
+        const signature = problem ? problem.details?.signatureId : given;
+        if (!signature) throw new Error(`Problem '${given}' is not about an error: it has no signatureId`);
+        // An error with a stack is grouped by its stack hash, one without by its event type (ErrorIncidentProblem).
+        const text = `(eventType.id = "${signature}" or eventType.errorStackTraceHash = "${signature}") and ` + `eventTime > "${new Date(Date.now() - parseDuration(argv.since ?? '7d', '--since')).toISOString()}"`;
+        const events = (await dapi.raw('GET', `/log${(0, _nodeDapi.buildQuery)({
+          text,
+          limit: argv.limit ?? 50,
+          page: 1
+        })}`)) ?? [];
+        const logins = new Map();
+        for (const e of events) for (const p of e.parameters ?? []) if (p.parameter?.name === 'user' && p.value && !logins.has(p.value)) logins.set(p.value, (await dapi.users.find(p.value))?.login ?? p.value);
+        (0, _serverOutput.printOutput)(events.map(e => {
+          const params = {};
+          for (const p of e.parameters ?? []) params[p.parameter?.name] = p.value;
+          const row = {
+            time: e.eventTime,
+            source: params.source,
+            user: logins.get(params.user) ?? null,
+            function: params.function ?? null,
+            session: e.session?.id ?? null,
+            message: e.description
+          };
+          return output === 'table' ? row : {
+            ...row,
+            eventId: e.id,
+            params
+          };
+        }), output);
+        return true;
+      }
+  }
+  if (command === 'logs' && verb === 'capture') return capture(dapi, rest, argv, await settings('logger'), saveLogger, output);
+  if (command === 'logs') return logs(dapi, verb, rest, argv, output);
+  if (command === 'timeline') {
+    if (argv.session === undefined) throw new Error('Usage: grok s observe timeline --session <id> [--from <ISO|-15m>] [--to <ISO>] [--limit 500]');
+    needFrom(argv);
+    const window = argv.from === undefined ? {
+      from: iso('-15m', '--from'),
+      to: new Date().toISOString()
+    } : {
+      from: iso(argv.from, '--from'),
+      to: iso(argv.to, '--to')
+    };
+    (0, _serverOutput.printOutput)(await dapi.raw('GET', `/log/timeline${(0, _nodeDapi.buildQuery)({
+      session: argv.session,
+      ...window,
+      limit: argv.limit
+    })}`), output);
+    return true;
+  }
+  throw new Error(`Unknown command '${[command, verb].filter(Boolean).join(' ')}'\n${OBSERVE_USAGE}`);
+}
+const needFrom = argv => {
+  if (argv.to !== undefined && argv.from === undefined) throw new Error('--to needs --from');
+};
+async function logs(dapi, verb, rest, argv, output) {
+  const connection = argv.connection;
+  if (verb === 'cloud') {
+    if (argv.since !== undefined && argv.from !== undefined) throw new Error('--since is not used with --from');
+    needFrom(argv);
+    const group = argv.group ?? (await dapi.raw('GET', `/log/cloud/groups${(0, _nodeDapi.buildQuery)({
+      connection
+    })}`))?.[0];
+    if (!group) throw new Error('No log group to read: pass --group');
+    const window = argv.from !== undefined ? {
+      start: iso(argv.from, '--from'),
+      end: iso(argv.to, '--to')
+    } : {
+      start: new Date(Date.now() - parseDuration(argv.since ?? '1h', '--since')).toISOString()
+    };
+    (0, _serverOutput.printOutput)(await dapi.raw('GET', `/log/cloud/events${(0, _nodeDapi.buildQuery)({
+      connection,
+      group,
+      ...window,
+      filter: argv.filter,
+      limit: argv.limit,
+      format: 'json'
+    })}`), output);
+    return true;
+  }
+  if (verb === 'container') return containerLogs(dapi, rest[0], argv, output);
+  if (verb === 'archive' && rest[0] === 'list') {
+    let objects = (await dapi.raw('GET', `/log/archive/objects${(0, _nodeDapi.buildQuery)({
+      connection,
+      prefix: argv.prefix,
+      limit: argv.limit,
+      format: 'json'
+    })}`)) ?? [];
+    if (argv.since !== undefined) {
+      const from = Date.now() - parseDuration(argv.since, '--since');
+      objects = objects.filter(o => Date.parse(o.modified) >= from);
+    }
+    (0, _serverOutput.printOutput)(objects, output);
+    return true;
+  }
+  if (verb === 'archive' && rest[0] === 'read' && rest[1] !== undefined) {
+    (0, _serverOutput.printOutput)(await dapi.raw('GET', `/log/archive/events${(0, _nodeDapi.buildQuery)({
+      connection,
+      key: rest[1],
+      format: 'json'
+    })}`), output);
+    return true;
+  }
+  throw new Error('Usage: grok s observe logs cloud [--group <g>] ... | logs container [<name|id>] | ' + 'logs archive list [--prefix <p>] | logs archive read <key> | logs capture [<login|group>] | ' + 'logs capture stop <login|group>');
+}
+
+/// `logs container`: the server only cuts a container's log by line count, so the window and --grep apply here.
+async function containerLogs(dapi, name, argv, output) {
+  if (name === undefined) {
+    const all = (await dapi.raw('GET', `/docker/containers${(0, _nodeDapi.buildQuery)({
+      limit: 1000
+    })}`)) ?? [];
+    (0, _serverOutput.printOutput)(all.map(c => ({
+      id: c.id,
+      name: c.name,
+      status: c.status
+    })), output);
+    return true;
+  }
+  if (argv.since !== undefined && argv.from !== undefined) throw new Error('--since is not used with --from');
+  needFrom(argv);
+  let id = String(name);
+  if (!_nodeDapi.UUID_RE.test(id)) {
+    const found = (await dapi.raw('GET', `/docker/containers${(0, _nodeDapi.buildQuery)({
+      text: id,
+      limit: 100
+    })}`)) ?? [];
+    const container = found.find(c => c.name === id);
+    if (!container) throw new Error(`No container '${id}'${found.length ? `; similar: ${found.map(c => c.name).join(', ')}` : ''}`);
+    id = container.id;
+  }
+  const from = argv.from !== undefined ? parseTime(argv.from, '--from').getTime() : argv.since !== undefined ? Date.now() - parseDuration(argv.since, '--since') : -Infinity;
+  const to = argv.to !== undefined ? parseTime(argv.to, '--to').getTime() : Infinity;
+  const grep = argv.grep === undefined ? null : new RegExp(String(argv.grep), 'i');
+  const text = await dapi.raw('GET', `/docker/containers/${id}/logs${(0, _nodeDapi.buildQuery)({
+    limit: argv.limit ?? 20000
+  })}`);
+  // A line without its own timestamp (a stack frame) belongs to the window of the line before it.
+  let inWindow = from === -Infinity && to === Infinity;
+  const lines = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const stamp = /^(\d{4}-\d{2}-\d{2}T[\d:]{8})(?:\.\d+)?(Z|[+-]\d{2}:\d{2})/.exec(line);
+    if (stamp) {
+      const t = Date.parse(`${stamp[1]}${stamp[2]}`);
+      inWindow = t >= from && t <= to;
+    }
+    if (inWindow && line && (!grep || grep.test(line))) lines.push(line);
+  }
+  if (output === 'json') (0, _serverOutput.printOutput)(lines, output);else for (const line of lines) console.log(line);
+  return true;
+}
+async function loggerSet(dapi, argv, current, save, output) {
+  const sets = argv.set === undefined ? [] : (Array.isArray(argv.set) ? argv.set : [argv.set]).map(String);
+  const entry = argv.user !== undefined || argv.group !== undefined || argv.target !== undefined;
+  if (!sets.length && !entry) throw new Error('Usage: grok s observe logger set --set <path>=<json> ... [--user <login> | --group <name|id>]');
+  if (!entry && (argv.for !== undefined || argv.until !== undefined || argv.reason !== undefined || argv.remove)) throw new Error('--for, --until, --reason and --remove apply to a --user or --group entry');
+  const name = argv.user ?? argv.group ?? argv.name;
+  if (!entry) {
+    const body = {};
+    for (const s of sets) {
+      const key = setPath(current, s);
+      body[key] = current[key];
+    }
+    await save(body);
+  } else {
+    const group = argv.target ?? (argv.user !== undefined ? await dapi.groups.resolve(String(argv.user), {
+      personalOnly: true
+    }) : await dapi.groups.resolve(String(argv.group)));
+    const groups = {
+      ...current.userGroupSettings
+    };
+    const existing = groups[group.id];
+    if (argv.remove) {
+      if (!existing) throw new Error(`${name} has no logger entry`);
+      delete groups[group.id];
+    } else {
+      if (existing && !existing.expiresAt && (argv.for !== undefined || argv.until !== undefined)) throw new Error(`${name} has a logger entry that does not expire; change it without --for or --until`);
+      // A user's settings come from one entry, so a new one starts from All users instead of the defaults.
+      const settings = existing ? {
+        ...existing
+      } : {
+        ...groups[_walker.ALL_USERS]
+      };
+      if (!existing) delete settings.reason;
+      for (const s of sets) setPath(settings, s);
+      if (argv.for !== undefined) settings.expiresAt = new Date(Date.now() + parseDuration(argv.for, '--for')).toISOString();else if (argv.until !== undefined) {
+        settings.expiresAt = iso(argv.until, '--until');
+        if (Date.parse(settings.expiresAt) <= Date.now()) throw new Error(`--until ${argv.until} is in the past`);
+      }
+      if (argv.reason !== undefined) settings.reason = String(argv.reason);
+      groups[group.id] = settings;
+    }
+    await save({
+      userGroupSettings: groups
+    });
+  }
+  if (output !== 'quiet') console.log(!entry ? 'Saved the logger settings' : argv.remove ? `Removed the logger entry of ${name}` : `Saved the logger settings of ${name}`);
+  return true;
+}
+
+/// `logs capture`: logger set of saveHttpRequests, and the usage level it is saved at, on an expiring entry.
+async function capture(dapi, rest, argv, current, save, output) {
+  const groups = current.userGroupSettings ?? {};
+  const stop = rest[0] === 'stop';
+  const name = stop ? rest[1] : rest[0];
+  if (name === undefined) {
+    if (stop) throw new Error('Usage: grok s observe logs capture stop <login|group>');
+    const rows = [];
+    for (const [id, s] of Object.entries(groups)) if (s?.saveHttpRequests === true && s.expiresAt) {
+      const group = await dapi.groups.find(id);
+      rows.push({
+        id,
+        name: group?.friendlyName ?? group?.name ?? id,
+        expiresAt: s.expiresAt,
+        reason: s.reason ?? ''
+      });
+    }
+    (0, _serverOutput.printOutput)(rows, output);
+    return true;
+  }
+  let group;
+  try {
+    group = await dapi.groups.resolve(String(name), {
+      personalOnly: true
+    });
+  } catch {
+    group = await dapi.groups.resolve(String(name));
+  }
+  const existing = groups[group.id];
+  if (stop) {
+    if (!existing?.saveHttpRequests) throw new Error(`No capture for ${name}`);
+    if (!existing.expiresAt) throw new Error(`The logger entry of ${name} does not expire; change it with logger set`);
+    const own = ['saveHttpRequests', 'postLevels', 'saveLevels', 'expiresAt', 'reason'];
+    const others = Object.keys(existing).filter(k => !own.includes(k) && JSON.stringify(existing[k]) !== JSON.stringify(groups[_walker.ALL_USERS]?.[k]));
+    if (others.length) throw new Error(`The logger entry of ${name} also holds ${others.join(', ')}; remove it with ` + `grok s o logger set --${group.personal ? 'user' : 'group'} ${name} --remove`);
+    return loggerSet(dapi, {
+      target: group,
+      name,
+      remove: true
+    }, current, save, output);
+  }
+  const base = existing ?? groups[_walker.ALL_USERS] ?? {};
+  const sets = ['saveHttpRequests=true', ...['postLevels', 'saveLevels'].filter(l => Array.isArray(base[l]) && !base[l].includes('usage')).map(l => `${l}=${JSON.stringify([...base[l], 'usage'])}`)];
+  const end = Math.max(Date.now() + parseDuration(argv.for ?? '30m', '--for'), Date.parse(existing?.expiresAt) || 0);
+  return loggerSet(dapi, {
+    target: group,
+    name,
+    set: sets,
+    reason: argv.reason,
+    until: new Date(end).toISOString()
+  }, current, save, output);
+}

package/bin/commands/server.js

@@ -15,6 +15,7 @@ var _serverClient = require("../utils/server-client");
 var _serverOutput = require("../utils/server-output");
 var _serverMigrate = require("./server-migrate");
 var _serverDomains = require("./server-domains");
+var _serverObserve = require("./server-observe");
 var _registry = require("../utils/migrate/registry");
 var _walker = require("../utils/migrate/walker");
 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); }
@@ -27,7 +28,7 @@ const ENTITY_TYPES = {
   reports: 'UserReport'
 };
 const ENTITIES = ['users', 'groups', 'functions', 'connections', 'queries', 'scripts', 'packages', 'reports', 'files', 'tables'];
-const COMMANDS = ['shares', 'domains', 'raw', 'batch', 'describe', 'healthcheck', 'sync', 'pull', 'push', 'migrate', 'diff', 'bundle', 'token'];
+const COMMANDS = ['shares', 'domains', 'raw', 'batch', 'describe', 'healthcheck', 'sync', 'pull', 'push', 'migrate', 'diff', 'bundle', 'token', 'observe', 'o'];
 const VERBS = ['list', 'count', 'get', 'delete'];
 async function server(argv) {
   const args = argv['_'].slice(1);
@@ -45,6 +46,10 @@ async function server(argv) {
     console.log(HELP_SERVER);
     return true;
   }
+  if ((entity === 'observe' || entity === 'o') && !verb) {
+    console.log(_serverObserve.OBSERVE_USAGE);
+    return true;
+  }
   let client;
   try {
     client = await (0, _serverClient.createClient)(host, !!argv.admin);
@@ -60,6 +65,7 @@ async function server(argv) {
     // escaping to grok.js as an unhandled rejection (stack trace + exit 255)
     if (['pull', 'push', 'migrate', 'diff', 'bundle'].includes(entity)) return await (0, _serverMigrate.handleMigrate)(dapi, entity, [verb, ...rest].filter(Boolean), argv, output);
     if (entity === 'domains') return await (0, _serverDomains.handleDomains)(dapi, verb, rest, argv, output);
+    if (entity === 'observe' || entity === 'o') return await (0, _serverObserve.handleObserve)(dapi, verb, rest[0], rest.slice(1), argv, output);
     if (entity === 'batch') return await handleBatch(dapi, argv, verb, rest, output);
     // Shell scripts that used to curl /users/login/dev get a token the same way
     // every other command does, whatever credential the config holds.
@@ -927,6 +933,7 @@ Manage a Datagrok server from the command line.
 Entities:
   users, groups, functions, connections, queries, scripts, packages, reports, files, tables
   (plus domains, shares, batch, raw, describe, healthcheck, sync, pull/push/migrate/diff/bundle below)
+  observe (alias o): problems, problem rules, logger settings, errors, timeline, cloud logs; grok s observe prints its verbs
 
 Verbs:
   list      List entities (--filter, --limit, --offset)

package/bin/utils/ent-helpers.js

@@ -12,7 +12,7 @@ const domainApp = (appNames, tables) => `
 The application${appNames.length > 1 ? 's' : ''} ${appNames.join(', ')} ` + `(over ${tables.join(', ')}) ${appNames.length > 1 ? 'have' : 'has'} been added successfully
 
 Next steps:
-  pnpm install                   link @datagrok-libraries/u2 (a workspace dependency)
+  pnpm install                   link @datagrok-libraries/ems (a workspace dependency)
   grok build && grok publish     publish the package and open the app from the browse tree
 
 The app is the u2 defaults alone — list, search, filters, entity page with children

package/bin/utils/migrate/walker.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.ALL_USERS = void 0;
 exports.collectExternals = collectExternals;
 exports.compileFilter = compileFilter;
 exports.expand = expand;
@@ -28,7 +29,7 @@ const noProgress = () => {};
 
 /** What the bundle points at but does not carry: resolvable on the source, or dead there too. */
 
-const ALL_USERS = 'a4b45840-9a50-11e6-9cc9-8546b8bf62e6';
+const ALL_USERS = exports.ALL_USERS = 'a4b45840-9a50-11e6-9cc9-8546b8bf62e6';
 
 /** One round trip per entity, tens of thousands per stand — modest, since the server is shared. */
 const WALK_CONCURRENCY = 12;

package/bin/utils/migrate/walker.ts

@@ -30,7 +30,7 @@ export interface External {id: string; type: string; nqName: string}
 /** What the bundle points at but does not carry: resolvable on the source, or dead there too. */
 export interface Outside {externals: External[]; dangling: string[]}
 
-const ALL_USERS = 'a4b45840-9a50-11e6-9cc9-8546b8bf62e6';
+export const ALL_USERS = 'a4b45840-9a50-11e6-9cc9-8546b8bf62e6';
 
 /** One round trip per entity, tens of thousands per stand — modest, since the server is shared. */
 const WALK_CONCURRENCY = 12;

package/bin/utils/node-dapi.js

@@ -3,13 +3,14 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.NodeUsersDataSource = exports.NodeTablesDataSource = exports.NodeSharesDataSource = exports.NodePackagesDataSource = exports.NodeHttpDataSource = exports.NodeGroupsDataSource = exports.NodeFuncsDataSource = exports.NodeFilesDataSource = exports.NodeDomainsDataSource = exports.NodeDapi = exports.NodeConnectionsDataSource = exports.NodeApiClient = exports.InternalDataSource = void 0;
+exports.UUID_RE = exports.NodeUsersDataSource = exports.NodeTablesDataSource = exports.NodeSharesDataSource = exports.NodePackagesDataSource = exports.NodeHttpDataSource = exports.NodeGroupsDataSource = exports.NodeFuncsDataSource = exports.NodeFilesDataSource = exports.NodeDomainsDataSource = exports.NodeDapi = exports.NodeConnectionsDataSource = exports.NodeApiClient = exports.InternalDataSource = void 0;
 exports.apiPath = apiPath;
 exports.buildQuery = buildQuery;
 exports.ensureBodyId = ensureBodyId;
 exports.mapPositionalParams = mapPositionalParams;
 exports.parseDomainAddress = parseDomainAddress;
 exports.throwIfApiError = throwIfApiError;
+exports.tryParseJson = tryParseJson;
 var _crypto = require("crypto");
 var _keypair = require("./keypair");
 /// Docs: [Grok Dapi](/docs/plans/grok-dapi/)
@@ -142,7 +143,7 @@ class NodeApiClient {
       return null;
     }
     const ct = res.headers.get('content-type') ?? '';
-    return throwIfApiError(ct.includes('application/json') ? await res.json() : await res.text());
+    return throwIfApiError(ct.includes('application/json') ? await res.json() : await res.text(), res.headers);
   }
   get(path) {
     return this.request('GET', path);
@@ -170,7 +171,7 @@ class NodeApiClient {
     }, false, BYTES_TIMEOUT_MS);
     if (!res.ok) await throwHttpError(res);
     const ct = res.headers.get('content-type') ?? '';
-    return throwIfApiError(ct.includes('application/json') ? await res.json() : await res.text());
+    return throwIfApiError(ct.includes('application/json') ? await res.json() : await res.text(), res.headers);
   }
 
   /** POST a JSON body and read the response as raw bytes (d42 query results). */
@@ -236,13 +237,15 @@ async function throwHttpError(res) {
  * a JSON string when the handler returned text. Every response passes through here so a
  * missing entity, a rejected save or an unknown function throws instead of printing as data.
  */
-function throwIfApiError(payload) {
+/** A user error answers HTTP 200 with the ApiError in the body and its status in the `api-error-code` header. */
+function throwIfApiError(payload, headers) {
   const parsed = typeof payload === 'string' ? tryParseJson(payload) : payload;
   if (parsed?.['#type'] === 'ApiError') {
+    const code = headers?.get('api-error-code');
     const err = {
       error: parsed.message ?? 'Request failed',
       source: 'Server',
-      errorCode: parsed.errorCode,
+      errorCode: parsed.errorCode ?? (code ? Number(code) : undefined),
       stackTrace: parsed.stackTrace,
       body: parsed
     };
@@ -388,7 +391,7 @@ class InternalDataSource {
   }
 }
 exports.InternalDataSource = InternalDataSource;
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_RE = exports.UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 class NodeGroupsDataSource extends NodeHttpDataSource {
   constructor(client) {
     super(client, 'groups', '/groups');
@@ -936,6 +939,10 @@ function parseDomainAddress(s, opts = {}) {
   if (opts.table === false && address.table) throw new Error(`'${str}' names a table; this command needs a schema`);
   return address;
 }
+/** Every literal a `/domains/{schema}/{table}/{id}` route registers at the id position, the dot
+ * segments a proxy folds away, and the u2 draft sentinel — the Dart `DomainRowKey.reserved` list. */
+const RESERVED_ROW_KEYS = ['access', 'aggregate', 'audit', 'batch', 'delete', 'facets', 'filters', 'query', 'update', 'version', 'watch', 'new', '.', '..'];
+
 /**
  * Client for entity-mapped domain tables (`/domains/...`, DomainsRouter). Rows are plain
  * JSON objects; the server validates, permission-checks and audits every write. Errors
@@ -950,6 +957,13 @@ class NodeDomainsDataSource {
     return `/domains/${encodeURIComponent(schema)}/${encodeURIComponent(table)}`;
   }
 
+  /** The row-id segment as the Dart `DomainRowKey` spells it (grok_shared domain_manifest_rules.dart):
+   * escaped, then percent-encoded once more so an external key's own `%2C` survives the proxy. */
+  row(schema, table, id) {
+    const escaped = RESERVED_ROW_KEYS.includes(id) || id.startsWith('~') ? `~${id}` : id;
+    return `${this.rows(schema, table)}/${encodeURIComponent(escaped)}`;
+  }
+
   /** Registered schemas with their tables (`GET /domains/schemas`); [text] is a smart filter. */
   schemas(text) {
     return this.client.get(`/domains/schemas${buildQuery({
@@ -1001,7 +1015,7 @@ class NodeDomainsDataSource {
     })}`);
   }
   rowAudit(schema, table, id) {
-    return this.client.get(`${this.rows(schema, table)}/${encodeURIComponent(id)}/audit`);
+    return this.client.get(`${this.row(schema, table, id)}/audit`);
   }
   grants(entityId) {
     return this.client.get(`/domains/grants/${encodeURIComponent(entityId)}`);
@@ -1053,7 +1067,7 @@ class NodeDomainsDataSource {
   /** One row, or null when it does not exist or is not visible (the server answers 404). */
   async getRow(schema, table, id) {
     try {
-      return await this.client.get(`${this.rows(schema, table)}/${encodeURIComponent(id)}`);
+      return await this.client.get(this.row(schema, table, id));
     } catch (err) {
       if (err?.apiError?.errorCode === 404) return null;
       throw err;
@@ -1073,10 +1087,10 @@ class NodeDomainsDataSource {
       values
     };
     if (version !== undefined) body.version = version;
-    return this.client.request('PATCH', `${this.rows(schema, table)}/${encodeURIComponent(id)}`, body);
+    return this.client.request('PATCH', this.row(schema, table, id), body);
   }
   deleteRow(schema, table, id) {
-    return this.client.del(`${this.rows(schema, table)}/${encodeURIComponent(id)}`);
+    return this.client.del(this.row(schema, table, id));
   }
 
   /** Soft-deletes up to [limit] (≤1000) matching rows in one transaction; `{deleted, hasMore}`. */
@@ -1138,6 +1152,9 @@ class NodeDapi {
   get reports() {
     return this.internal('/reports');
   }
+  get problems() {
+    return this.internal('/problems');
+  }
   get files() {
     return new NodeFilesDataSource(this.client);
   }

package/domain-schema.schema.json

@@ -16,6 +16,36 @@
       "type": "string",
       "description": "Manifest version (semver recommended). Recorded in the registry on deploy."
     },
+    "storage": {
+      "type": "object",
+      "description": "Where the rows live. Absent = domain: the platform creates and owns the tables. external: the tables already exist in the database of the named platform connection and are read through it (no row security, soft delete, audit, relations, constraints, property schemas or extensions; read-only unless 'writable'); every table then declares its remote primary key as businessKey, and 'table'/'column' carry the remote names when they differ from the declared ones.",
+      "required": ["kind"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {"enum": ["domain", "external"]},
+        "connection": {
+          "type": "string",
+          "minLength": 1,
+          "description": "external: the qualified name of the platform connection to read through ('Package:Connection'); required."
+        },
+        "schema": {
+          "$ref": "#/definitions/remoteIdentifier",
+          "description": "external: the schema inside the remote database (e.g. 'public', 'dbo'); required."
+        },
+        "catalog": {
+          "$ref": "#/definitions/remoteIdentifier",
+          "description": "external: the catalog/database, for targets that have one."
+        },
+        "writable": {
+          "type": "boolean",
+          "default": false,
+          "description": "external: rows may be inserted, patched and deleted through the connection (one remote transaction per request, keyed by businessKey; on ClickHouse, which commits every statement, a request is one multi-row INSERT and patch/delete/upsert are refused). The publisher must hold Query, AddRows, ChangeValues and RemoveRows on the connection; a table opts out with its own 'writable': false."
+        }
+      },
+      "if": {"properties": {"kind": {"const": "external"}}},
+      "then": {"required": ["connection", "schema"]},
+      "else": {"properties": {"connection": false, "schema": false, "catalog": false, "writable": false}}
+    },
     "extensible": {
       "type": "object",
       "description": "Opt-in for user extensions of this schema. Users holding the Extend permission on the schema entity may then add their own tables; per-table column extension is opted in with the table's own 'extensible' flag. User objects are retained across plugin upgrades and never appear in generated typed clients.",
@@ -64,11 +94,26 @@
         {"not": {"type": "string", "pattern": "^x_"}}
       ]
     },
+    "remoteIdentifier": {
+      "description": "A name inside the remote database, verbatim (spaces allowed, the connector quotes it); it may not contain brackets, quotes, backslashes or dots.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^[^\\[\\]\"'`\\\\.]+$"
+    },
     "table": {
       "type": "object",
       "required": ["columns"],
       "additionalProperties": false,
       "properties": {
+        "table": {
+          "$ref": "#/definitions/remoteIdentifier",
+          "description": "External storage only: the remote table's name when it differs from the declared one (e.g. 'Order Details')."
+        },
+        "writable": {
+          "type": "boolean",
+          "description": "Writable external storage only: false keeps this table read-only while the rest of the binding accepts writes."
+        },
         "securityMode": {
           "enum": ["table", "master", "row"],
           "default": "table",
@@ -263,7 +308,11 @@
       "properties": {
         "type": {
           "enum": ["string", "int", "float", "bool", "datetime", "string_list", "ref", "file", "json", "user", "group"],
-          "description": "Property type; ref = FK to another table in this manifest; user/group = aliases of ref Core.users / ref Core.groups (semantic type User / Group); file = a file://<connection>/<path> string into platform file storage (semantic type File); json = a jsonb-backed opaque object (filters, sorts, facets and aggregates refuse it)."
+          "description": "Property type; ref = FK to another table in this manifest; user/group = aliases of ref Core.users / ref Core.groups (semantic type User / Group); file = a file://<connection>/<path> string into platform file storage (semantic type File); json = a jsonb-backed opaque object (filters, sorts, facets and aggregates refuse it). An external storage admits string, int, float, bool, datetime and same-manifest ref only."
+        },
+        "column": {
+          "$ref": "#/definitions/remoteIdentifier",
+          "description": "External storage only: the remote column's name when it differs from the declared one (e.g. 'OrderID')."
         },
         "required": {"type": "boolean", "default": false},
         "unique": {

package/entity-template/domain-app-imports.js

@@ -1,4 +1,4 @@
-import {domains} from '@datagrok-libraries/u2/src/dg/index.js';
+import {domains} from '@datagrok-libraries/ems/src/dg';
 
 // the skins of everything the u2 domain stack renders
-import '@datagrok-libraries/u2/src/dg/domain/styles.js';
+import '@datagrok-libraries/ems/src/dg/styles.js';

package/package.json

@@ -4,9 +4,12 @@
     "type": "git",
     "url": "https://github.com/datagrok-ai/public.git"
   },
-  "version": "6.7.8",
+  "version": "6.7.9",
   "description": "Utility to upload and publish packages to Datagrok",
   "homepage": "https://github.com/datagrok-ai/public/tree/master/tools#readme",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "dependencies": {
     "@babel/parser": "^7.29.7",
     "@babel/runtime": "^7.29.7",
@@ -24,7 +27,7 @@
     "minimist": "^1.2.8",
     "node-fetch": "^2.7.0",
     "papaparse": "^5.5.3",
-    "puppeteer": "^24.15.0",
+    "puppeteer": "^25.14.0",
     "ts-morph": "^28.0.0",
     "@babel/generator": "^7.29.0",
     "datagrok-api": "^1.27.12"