datagrok-tools 6.1.8 → 6.1.10

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Datagrok-tools changelog
 
+## 6.1.10 (2026-04-17)
+
+* `grok s connections save` — create/update a connection from a JSON file (`--save-credentials` optional)
+* `grok s connections test` — test connectivity by JSON body or by existing id/name
+* `grok s users save` — create/update a user from a JSON file
+* `grok s groups save` — create/update a group from a JSON file (`--save-relations` optional)
+* `grok s shares add` — share an entity with one or more groups (`--access View|Edit`)
+* `grok s shares list` — list who an entity is shared with
+* Tools: Normalize package name to lowercase in grok create, preserve original as friendlyName
+
 ## 5.1.3 (2026-02-03)
 
 * GROK-19407:

package/CLAUDE.md

@@ -28,6 +28,7 @@ The CLI uses a modular command pattern. Each command is a separate module that:
 - `test-all.ts` - Run tests across multiple packages
 - `stress-tests.ts` - Run stress tests (must be run from ApiTests package)
 - `api.ts` - Auto-generate TypeScript wrappers for scripts/queries
+- `server.ts` - Manage and inspect a running Datagrok server (`grok server` / `grok s`)
 - `link.ts` - Link libraries for plugin development
 - `claude.ts` - Launch a Dockerized dev environment with Datagrok + Claude Code
 - `migrate.ts` - Update legacy packages
@@ -220,6 +221,73 @@ Based on `node:22-bookworm-slim`. Pre-installed:
 
 See `.devcontainer/PACKAGES_DEV.md` for detailed usage docs, architecture diagram, MCP plugin setup (Jira/GitHub), and troubleshooting.
 
+### `grok server` / `grok s` Command
+
+Use `grok s` to inspect and debug a running Datagrok server from the CLI — list entities,
+call functions, browse files, or hit any API endpoint. Reads config from `~/.grok/config.yaml`
+(same as `grok publish`). Use `--host <alias|url>` to target a specific server.
+
+```bash
+# Create / update entities (from JSON file — supports both create and update)
+grok s users save --json user.json
+grok s groups save --json group.json --save-relations
+
+# Share entities
+grok s shares add "JohnDoe:MyConnection" Chemists,Admins --access Edit
+grok s shares list <entity-uuid>
+
+# List / inspect entities
+grok s users list
+grok s packages list --filter "MyPlugin"       # check if a plugin is published
+grok s connections list --output json
+grok s functions list --filter "Chem"          # find registered functions
+grok s connections get <id>
+grok s connections delete <id>
+grok s connections save --json conn.json --save-credentials   # create or update
+grok s connections test "JohnDoe:MyConnection"                # test by id or name
+grok s connections test --json conn.json                      # test a connection defined in JSON
+
+# Call a server function
+grok s functions run 'Chem:smilesToMw("ccc")'
+grok s functions run 'Pkg:fn({a:5,b:22})'
+
+# Browse file storage
+grok s files list "System:AppData" -r          # list files recursively
+grok s files list "System:AppData/MyPlugin"
+
+# Manage group membership
+grok s groups add-members Admins alice bob              # add two users (non-admin)
+grok s groups add-members Admins alice --admin          # add as admin (flips if already member)
+grok s groups add-members Admins alice --user           # force personal-group lookup
+grok s groups remove-members Admins alice bob           # remove members
+grok s groups list-members Admins                       # all members
+grok s groups list-members Admins --admin               # admin members only
+grok s groups list-members Admins --no-admin            # non-admin members only
+grok s groups list-memberships alice                    # groups alice belongs to
+
+# Hit any API endpoint directly
+grok s raw GET /api/users/current
+grok s raw GET /api/packages/dev/MyPlugin
+
+# Describe entity JSON schema
+grok s describe connections
+
+# Target a specific server
+grok s users list --host dev
+grok s users list --host "https://my.datagrok.ai/api"
+
+# Output formats: table (default), json, csv, quiet (IDs only)
+grok s packages list --output json
+grok s users list --output quiet | xargs ...   # pipe IDs
+```
+
+**Windows Git Bash:** prefix raw paths with `MSYS_NO_PATHCONV=1` to prevent POSIX→Windows
+path conversion: `MSYS_NO_PATHCONV=1 grok s raw GET /api/users/current`
+
+**Implementation:** `bin/commands/server.ts`, `bin/utils/node-dapi.ts` (Node.js REST client),
+`bin/utils/server-output.ts` (formatters). The Node.js dapi bypasses the Dart interop layer
+and calls `/public/v1/` endpoints directly — same approach as the Python CLI.
+
 ## Key Patterns and Conventions
 
 ### Naming Conventions

package/bin/__tests__/build.test.js

@@ -0,0 +1,116 @@
+"use strict";
+
+var _vitest = require("vitest");
+var _build = require("../commands/build");
+(0, _vitest.describe)('getNestedValue', () => {
+  (0, _vitest.it)('returns value for a simple key', () => {
+    (0, _vitest.expect)((0, _build.getNestedValue)({
+      name: 'Chem'
+    }, 'name')).toBe('Chem');
+  });
+  (0, _vitest.it)('returns value for a nested path', () => {
+    (0, _vitest.expect)((0, _build.getNestedValue)({
+      a: {
+        b: {
+          c: 42
+        }
+      }
+    }, 'a.b.c')).toBe(42);
+  });
+  (0, _vitest.it)('returns undefined for a missing key', () => {
+    (0, _vitest.expect)((0, _build.getNestedValue)({
+      name: 'Chem'
+    }, 'version')).toBeUndefined();
+  });
+  (0, _vitest.it)('returns undefined when a mid-path segment is null', () => {
+    (0, _vitest.expect)((0, _build.getNestedValue)({
+      a: null
+    }, 'a.b')).toBeUndefined();
+  });
+  (0, _vitest.it)('returns undefined when a mid-path segment is missing', () => {
+    (0, _vitest.expect)((0, _build.getNestedValue)({
+      a: {}
+    }, 'a.b.c')).toBeUndefined();
+  });
+  (0, _vitest.it)('returns undefined for an empty path (splits to empty string key)', () => {
+    (0, _vitest.expect)((0, _build.getNestedValue)({
+      x: 1
+    }, '')).toBeUndefined();
+  });
+});
+const pkg = overrides => ({
+  dir: '/tmp/pkg',
+  name: overrides.name ?? 'test-pkg',
+  friendlyName: overrides.friendlyName ?? overrides.name ?? 'Test Pkg',
+  version: overrides.version ?? '1.0.0',
+  packageJson: overrides
+});
+(0, _vitest.describe)('applyFilter', () => {
+  const packages = [pkg({
+    name: 'Chem',
+    version: '1.5.0',
+    category: 'Cheminformatics'
+  }), pkg({
+    name: 'Bio',
+    version: '2.0.0',
+    category: 'Bioinformatics'
+  }), pkg({
+    name: 'PowerGrid',
+    version: '1.5.0',
+    category: 'Viewers'
+  })];
+  (0, _vitest.it)('returns all packages when filter matches all', () => {
+    (0, _vitest.expect)((0, _build.applyFilter)(packages, 'name:.')).toHaveLength(3);
+  });
+  (0, _vitest.it)('filters by exact name match', () => {
+    const result = (0, _build.applyFilter)(packages, 'name:^Chem$');
+    (0, _vitest.expect)(result).toHaveLength(1);
+    (0, _vitest.expect)(result[0].name).toBe('Chem');
+  });
+  (0, _vitest.it)('filters by partial name (regex substring)', () => {
+    const result = (0, _build.applyFilter)(packages, 'name:Bio');
+    (0, _vitest.expect)(result).toHaveLength(1);
+    (0, _vitest.expect)(result[0].name).toBe('Bio');
+  });
+  (0, _vitest.it)('returns empty array when nothing matches', () => {
+    (0, _vitest.expect)((0, _build.applyFilter)(packages, 'name:NOMATCH')).toHaveLength(0);
+  });
+  (0, _vitest.it)('filters by version', () => {
+    const result = (0, _build.applyFilter)(packages, 'version:^1\\.5');
+    (0, _vitest.expect)(result).toHaveLength(2);
+    (0, _vitest.expect)(result.map(p => p.name)).toEqual(_vitest.expect.arrayContaining(['Chem', 'PowerGrid']));
+  });
+  (0, _vitest.it)('applies && conjunction (both conditions must match)', () => {
+    const result = (0, _build.applyFilter)(packages, 'name:Chem && version:1\\.5');
+    (0, _vitest.expect)(result).toHaveLength(1);
+    (0, _vitest.expect)(result[0].name).toBe('Chem');
+  });
+  (0, _vitest.it)('returns empty when one part of && conjunction fails', () => {
+    (0, _vitest.expect)((0, _build.applyFilter)(packages, 'name:Chem && version:^2')).toHaveLength(0);
+  });
+  (0, _vitest.it)('filters by nested field', () => {
+    const withNested = [pkg({
+      name: 'A',
+      datagrok: {
+        apiVersion: '1.0'
+      }
+    }), pkg({
+      name: 'B',
+      datagrok: {
+        apiVersion: '2.0'
+      }
+    })];
+    const result = (0, _build.applyFilter)(withNested, 'datagrok.apiVersion:^1');
+    (0, _vitest.expect)(result).toHaveLength(1);
+    (0, _vitest.expect)(result[0].name).toBe('A');
+  });
+  (0, _vitest.it)('returns empty when field does not exist', () => {
+    (0, _vitest.expect)((0, _build.applyFilter)(packages, 'nonexistent:anything')).toHaveLength(0);
+  });
+  (0, _vitest.it)('treats filter with no colon as field name with match-all pattern', () => {
+    // No colon → field = whole string, pattern = /./  (matches any value)
+    // The function returns packages where the field exists and is non-empty
+    const result = (0, _build.applyFilter)(packages, 'name');
+    (0, _vitest.expect)(result).toHaveLength(3);
+  });
+});

package/bin/__tests__/build.test.ts

@@ -0,0 +1,101 @@
+import {describe, it, expect} from 'vitest';
+import {getNestedValue, applyFilter} from '../commands/build';
+
+describe('getNestedValue', () => {
+  it('returns value for a simple key', () => {
+    expect(getNestedValue({name: 'Chem'}, 'name')).toBe('Chem');
+  });
+
+  it('returns value for a nested path', () => {
+    expect(getNestedValue({a: {b: {c: 42}}}, 'a.b.c')).toBe(42);
+  });
+
+  it('returns undefined for a missing key', () => {
+    expect(getNestedValue({name: 'Chem'}, 'version')).toBeUndefined();
+  });
+
+  it('returns undefined when a mid-path segment is null', () => {
+    expect(getNestedValue({a: null}, 'a.b')).toBeUndefined();
+  });
+
+  it('returns undefined when a mid-path segment is missing', () => {
+    expect(getNestedValue({a: {}}, 'a.b.c')).toBeUndefined();
+  });
+
+  it('returns undefined for an empty path (splits to empty string key)', () => {
+    expect(getNestedValue({x: 1}, '')).toBeUndefined();
+  });
+});
+
+const pkg = (overrides: Record<string, any>) => ({
+  dir: '/tmp/pkg',
+  name: overrides.name ?? 'test-pkg',
+  friendlyName: overrides.friendlyName ?? overrides.name ?? 'Test Pkg',
+  version: overrides.version ?? '1.0.0',
+  packageJson: overrides,
+});
+
+describe('applyFilter', () => {
+  const packages = [
+    pkg({name: 'Chem', version: '1.5.0', category: 'Cheminformatics'}),
+    pkg({name: 'Bio', version: '2.0.0', category: 'Bioinformatics'}),
+    pkg({name: 'PowerGrid', version: '1.5.0', category: 'Viewers'}),
+  ];
+
+  it('returns all packages when filter matches all', () => {
+    expect(applyFilter(packages, 'name:.')).toHaveLength(3);
+  });
+
+  it('filters by exact name match', () => {
+    const result = applyFilter(packages, 'name:^Chem$');
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe('Chem');
+  });
+
+  it('filters by partial name (regex substring)', () => {
+    const result = applyFilter(packages, 'name:Bio');
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe('Bio');
+  });
+
+  it('returns empty array when nothing matches', () => {
+    expect(applyFilter(packages, 'name:NOMATCH')).toHaveLength(0);
+  });
+
+  it('filters by version', () => {
+    const result = applyFilter(packages, 'version:^1\\.5');
+    expect(result).toHaveLength(2);
+    expect(result.map((p) => p.name)).toEqual(expect.arrayContaining(['Chem', 'PowerGrid']));
+  });
+
+  it('applies && conjunction (both conditions must match)', () => {
+    const result = applyFilter(packages, 'name:Chem && version:1\\.5');
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe('Chem');
+  });
+
+  it('returns empty when one part of && conjunction fails', () => {
+    expect(applyFilter(packages, 'name:Chem && version:^2')).toHaveLength(0);
+  });
+
+  it('filters by nested field', () => {
+    const withNested = [
+      pkg({name: 'A', datagrok: {apiVersion: '1.0'}}),
+      pkg({name: 'B', datagrok: {apiVersion: '2.0'}}),
+    ];
+    const result = applyFilter(withNested, 'datagrok.apiVersion:^1');
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe('A');
+  });
+
+  it('returns empty when field does not exist', () => {
+    expect(applyFilter(packages, 'nonexistent:anything')).toHaveLength(0);
+  });
+
+  it('treats filter with no colon as field name with match-all pattern', () => {
+    // No colon → field = whole string, pattern = /./  (matches any value)
+    // The function returns packages where the field exists and is non-empty
+    const result = applyFilter(packages, 'name');
+    expect(result).toHaveLength(3);
+  });
+});

package/bin/__tests__/node-dapi.connections.test.js

@@ -0,0 +1,120 @@
+"use strict";
+
+var _vitest = require("vitest");
+var _nodeDapi = require("../utils/node-dapi");
+function makeMock(responder) {
+  const calls = [];
+  const client = {
+    async request(method, path, body) {
+      calls.push({
+        method,
+        path,
+        body
+      });
+      return responder(method, path, body);
+    },
+    get(path) {
+      return this.request('GET', path);
+    },
+    post(path, body) {
+      return this.request('POST', path, body);
+    },
+    del(path) {
+      return this.request('DELETE', path);
+    }
+  };
+  return {
+    client,
+    calls
+  };
+}
+const CONN = {
+  name: 'TestPg',
+  dataSource: 'PostgreSQL',
+  server: 'localhost',
+  port: 5432,
+  db: 'datagrok'
+};
+(0, _vitest.describe)('NodeConnectionsDataSource.save', () => {
+  (0, _vitest.it)('POSTs to /public/v1/connections without saveCredentials by default', async () => {
+    const {
+      client,
+      calls
+    } = makeMock((method, path, body) => {
+      if (method === 'POST' && path === '/public/v1/connections') return {
+        ...body,
+        id: 'new-id'
+      };
+      throw new Error(`unexpected ${method} ${path}`);
+    });
+    const ds = new _nodeDapi.NodeConnectionsDataSource(client);
+    const saved = await ds.save(CONN);
+    (0, _vitest.expect)(saved.id).toBe('new-id');
+    (0, _vitest.expect)(calls[0].path).toBe('/public/v1/connections');
+    (0, _vitest.expect)(calls[0].body).toEqual(CONN);
+  });
+  (0, _vitest.it)('appends saveCredentials=true when requested', async () => {
+    const {
+      client,
+      calls
+    } = makeMock((method, path, body) => {
+      if (method === 'POST' && path === '/public/v1/connections?saveCredentials=true') return {
+        ...body,
+        id: 'new-id'
+      };
+      throw new Error(`unexpected ${method} ${path}`);
+    });
+    const ds = new _nodeDapi.NodeConnectionsDataSource(client);
+    await ds.save(CONN, true);
+    (0, _vitest.expect)(calls[0].path).toBe('/public/v1/connections?saveCredentials=true');
+  });
+  (0, _vitest.it)('omits saveCredentials query param when false', async () => {
+    const {
+      client,
+      calls
+    } = makeMock((method, path) => {
+      if (method === 'POST' && path === '/public/v1/connections') return {
+        id: 'new-id'
+      };
+      throw new Error(`unexpected ${method} ${path}`);
+    });
+    const ds = new _nodeDapi.NodeConnectionsDataSource(client);
+    await ds.save(CONN, false);
+    (0, _vitest.expect)(calls[0].path).toBe('/public/v1/connections');
+  });
+});
+(0, _vitest.describe)('NodeConnectionsDataSource.test', () => {
+  (0, _vitest.it)('POSTs the connection body to /public/v1/connections/test and resolves on "ok"', async () => {
+    const {
+      client,
+      calls
+    } = makeMock((method, path) => {
+      if (method === 'POST' && path === '/public/v1/connections/test') return 'ok';
+      throw new Error(`unexpected ${method} ${path}`);
+    });
+    const ds = new _nodeDapi.NodeConnectionsDataSource(client);
+    await ds.test(CONN);
+    (0, _vitest.expect)(calls[0].body).toEqual(CONN);
+  });
+  (0, _vitest.it)('strips surrounding quotes on a JSON-encoded "ok"', async () => {
+    const {
+      client
+    } = makeMock(() => '"ok"');
+    const ds = new _nodeDapi.NodeConnectionsDataSource(client);
+    await (0, _vitest.expect)(ds.test(CONN)).resolves.toBeUndefined();
+  });
+  (0, _vitest.it)('throws the server error text when the response is not ok', async () => {
+    const {
+      client
+    } = makeMock(() => 'connection refused: tcp://localhost:5432');
+    const ds = new _nodeDapi.NodeConnectionsDataSource(client);
+    await (0, _vitest.expect)(ds.test(CONN)).rejects.toThrow(/connection refused/);
+  });
+  (0, _vitest.it)('throws a generic message on empty response', async () => {
+    const {
+      client
+    } = makeMock(() => '');
+    const ds = new _nodeDapi.NodeConnectionsDataSource(client);
+    await (0, _vitest.expect)(ds.test(CONN)).rejects.toThrow(/failed/i);
+  });
+});

package/bin/__tests__/node-dapi.connections.test.ts

@@ -0,0 +1,84 @@
+import {describe, it, expect} from 'vitest';
+import {NodeConnectionsDataSource} from '../utils/node-dapi';
+
+interface Call {method: string; path: string; body?: any}
+
+function makeMock(responder: (method: string, path: string, body?: any) => any) {
+  const calls: Call[] = [];
+  const client: any = {
+    async request(method: string, path: string, body?: any) {
+      calls.push({method, path, body});
+      return responder(method, path, body);
+    },
+    get(path: string) { return this.request('GET', path); },
+    post(path: string, body?: any) { return this.request('POST', path, body); },
+    del(path: string) { return this.request('DELETE', path); },
+  };
+  return {client, calls};
+}
+
+const CONN = {name: 'TestPg', dataSource: 'PostgreSQL', server: 'localhost', port: 5432, db: 'datagrok'};
+
+describe('NodeConnectionsDataSource.save', () => {
+  it('POSTs to /public/v1/connections without saveCredentials by default', async () => {
+    const {client, calls} = makeMock((method, path, body) => {
+      if (method === 'POST' && path === '/public/v1/connections') return {...body, id: 'new-id'};
+      throw new Error(`unexpected ${method} ${path}`);
+    });
+    const ds = new NodeConnectionsDataSource(client);
+    const saved = await ds.save(CONN);
+    expect(saved.id).toBe('new-id');
+    expect(calls[0].path).toBe('/public/v1/connections');
+    expect(calls[0].body).toEqual(CONN);
+  });
+
+  it('appends saveCredentials=true when requested', async () => {
+    const {client, calls} = makeMock((method, path, body) => {
+      if (method === 'POST' && path === '/public/v1/connections?saveCredentials=true') return {...body, id: 'new-id'};
+      throw new Error(`unexpected ${method} ${path}`);
+    });
+    const ds = new NodeConnectionsDataSource(client);
+    await ds.save(CONN, true);
+    expect(calls[0].path).toBe('/public/v1/connections?saveCredentials=true');
+  });
+
+  it('omits saveCredentials query param when false', async () => {
+    const {client, calls} = makeMock((method, path) => {
+      if (method === 'POST' && path === '/public/v1/connections') return {id: 'new-id'};
+      throw new Error(`unexpected ${method} ${path}`);
+    });
+    const ds = new NodeConnectionsDataSource(client);
+    await ds.save(CONN, false);
+    expect(calls[0].path).toBe('/public/v1/connections');
+  });
+});
+
+describe('NodeConnectionsDataSource.test', () => {
+  it('POSTs the connection body to /public/v1/connections/test and resolves on "ok"', async () => {
+    const {client, calls} = makeMock((method, path) => {
+      if (method === 'POST' && path === '/public/v1/connections/test') return 'ok';
+      throw new Error(`unexpected ${method} ${path}`);
+    });
+    const ds = new NodeConnectionsDataSource(client);
+    await ds.test(CONN);
+    expect(calls[0].body).toEqual(CONN);
+  });
+
+  it('strips surrounding quotes on a JSON-encoded "ok"', async () => {
+    const {client} = makeMock(() => '"ok"');
+    const ds = new NodeConnectionsDataSource(client);
+    await expect(ds.test(CONN)).resolves.toBeUndefined();
+  });
+
+  it('throws the server error text when the response is not ok', async () => {
+    const {client} = makeMock(() => 'connection refused: tcp://localhost:5432');
+    const ds = new NodeConnectionsDataSource(client);
+    await expect(ds.test(CONN)).rejects.toThrow(/connection refused/);
+  });
+
+  it('throws a generic message on empty response', async () => {
+    const {client} = makeMock(() => '');
+    const ds = new NodeConnectionsDataSource(client);
+    await expect(ds.test(CONN)).rejects.toThrow(/failed/i);
+  });
+});