datagrok-tools 6.6.0 → 6.7.1

package/bin/commands/setup.js

@@ -0,0 +1,139 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setup = setup;
+var _fs = _interopRequireDefault(require("fs"));
+var _path = _interopRequireDefault(require("path"));
+var _child_process = require("child_process");
+var color = _interopRequireWildcard(require("../utils/color-utils"));
+var _build = require("./build");
+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 setup`: one command to get (or keep) a public/ checkout ready to build.
+ *   1. Node 20+ (22 recommended); pnpm through corepack, at the version package.json pins.
+ *   2. Removes per-package node_modules left by the npm era and stray package-lock.json files.
+ *   3. `pnpm install` at the workspace root.
+ *   4. Reports a global `grok` older than the workspace one (`--global` updates it).
+ * `--check` only reports.
+ */
+async function setup(args) {
+  const root = (0, _build.findWorkspaceRoot)(process.cwd());
+  if (!root) {
+    color.error('Not inside the public/ workspace (no pnpm-workspace.yaml above the current directory).');
+    return false;
+  }
+  const check = !!args.check;
+  const rootPkg = JSON.parse(_fs.default.readFileSync(_path.default.join(root, 'package.json'), 'utf8'));
+  const pinnedPnpm = (rootPkg.packageManager || 'pnpm@10').split('@')[1];
+  let ok = true;
+
+  // 1. Node and pnpm
+  const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+  if (nodeMajor < 20) {
+    color.error(`Node ${process.versions.node}: 20 or later is required (22 recommended).`);
+    return false;
+  }
+  color.info(`Node ${process.versions.node}`);
+  let pnpmVersion = run('pnpm', ['--version']);
+  if (pnpmVersion !== pinnedPnpm) {
+    color.warn(`pnpm ${pnpmVersion || 'not found'}; the workspace pins ${pinnedPnpm}.`);
+    if (!check) {
+      if (run('corepack', ['--version']) === null) color.warn('corepack not found: `npm install -g corepack`, then rerun `grok setup`.');else {
+        (0, _child_process.spawnSync)('corepack', ['enable'], {
+          stdio: 'inherit',
+          shell: true
+        });
+        (0, _child_process.spawnSync)('corepack', ['prepare', `pnpm@${pinnedPnpm}`, '--activate'], {
+          stdio: 'inherit',
+          shell: true
+        });
+        pnpmVersion = run('pnpm', ['--version']);
+      }
+    }
+  }
+  if (pnpmVersion === pinnedPnpm) color.info(`pnpm ${pnpmVersion}`);else ok = false;
+
+  // 2. leftovers from the npm era
+  const projectDirs = ['js-api', 'tools', 'build-config'].map(d => _path.default.join(root, d));
+  for (const group of ['packages', 'libraries']) for (const d of _fs.default.readdirSync(_path.default.join(root, group))) projectDirs.push(_path.default.join(root, group, d));
+  const staleModules = projectDirs.filter(d => isLegacyNodeModules(_path.default.join(d, 'node_modules')));
+  const staleLocks = projectDirs.map(d => _path.default.join(d, 'package-lock.json')).filter(f => _fs.default.existsSync(f));
+  if (staleModules.length || staleLocks.length) {
+    color.warn(`${staleModules.length} per-package node_modules from npm and ${staleLocks.length} package-lock.json file(s)` + (check ? ' would be removed' : ': removing'));
+    if (!check) {
+      for (const d of staleModules) _fs.default.rmSync(_path.default.join(d, 'node_modules'), {
+        recursive: true,
+        force: true
+      });
+      for (const f of staleLocks) _fs.default.rmSync(f, {
+        force: true
+      });
+    }
+  } else color.info('no npm-era leftovers');
+
+  // 3. install
+  if (!check && pnpmVersion === pinnedPnpm) {
+    color.log('pnpm install ...');
+    const r = (0, _child_process.spawnSync)('pnpm', ['install', '--frozen-lockfile'], {
+      stdio: 'inherit',
+      cwd: root,
+      shell: true
+    });
+    if (r.status !== 0) {
+      color.warn('frozen install failed (lockfile out of date?): retrying without --frozen-lockfile');
+      if ((0, _child_process.spawnSync)('pnpm', ['install'], {
+        stdio: 'inherit',
+        cwd: root,
+        shell: true
+      }).status !== 0) {
+        color.error('pnpm install failed');
+        return false;
+      }
+    }
+  }
+
+  // 4. the global grok
+  const workspaceGrok = JSON.parse(_fs.default.readFileSync(_path.default.join(root, 'tools', 'package.json'), 'utf8')).version;
+  // datagrok-tools before 6.6 has no --version and prints its usage instead
+  const raw = run('grok', ['--version']);
+  const globalGrok = raw === null ? null : /^\d+\.\d+\.\d+/.test(raw) ? raw : 'older than 6.6';
+  if (globalGrok && globalGrok !== workspaceGrok) {
+    color.warn(`global grok ${globalGrok}; the workspace has ${workspaceGrok}` + (args.global && !check ? ': updating' : ' (run `npm install -g datagrok-tools@' + workspaceGrok + '`, or `grok setup --global`)'));
+    if (args.global && !check) (0, _child_process.spawnSync)('npm', ['install', '-g', `datagrok-tools@${workspaceGrok}`], {
+      stdio: 'inherit',
+      shell: true
+    });
+  } else if (globalGrok) color.info(`grok ${globalGrok}`);
+  if (ok && !check) color.success('Ready: `grok build` in any package, `grok build --all` for everything.');
+  return ok;
+}
+
+/** npm's node_modules holds real directories; pnpm's per-package one holds only symlinks (and .bin). */
+function isLegacyNodeModules(dir) {
+  if (!_fs.default.existsSync(dir)) return false;
+  for (const e of _fs.default.readdirSync(dir, {
+    withFileTypes: true
+  })) {
+    if (e.name === '.bin' || e.name === '.cache' || e.name.startsWith('.')) continue;
+    const p = _path.default.join(dir, e.name);
+    if (e.isSymbolicLink()) continue;
+    if (e.isDirectory() && e.name.startsWith('@')) {
+      if (_fs.default.readdirSync(p, {
+        withFileTypes: true
+      }).some(s => s.isDirectory() && !s.isSymbolicLink())) return true;
+      continue;
+    }
+    if (e.isDirectory()) return true;
+  }
+  return false;
+}
+function run(cmd, args) {
+  const r = (0, _child_process.spawnSync)(cmd, args, {
+    encoding: 'utf8',
+    shell: true
+  });
+  return r.status === 0 ? r.stdout.trim().split(/\r?\n/).pop() || '' : null;
+}

package/bin/commands/stress-tests.js

@@ -49,7 +49,9 @@ async function run(config, args) {
   processArgs.push('./node-test-loader/register.mjs');
   processArgs.push('src/package-test-node.ts');
   processArgs.push(`--apiUrl=${config.url}`);
-  processArgs.push(`--devKey=${config.key}`);
+  // A session token rather than the credential: it is short-lived, and with a keypair
+  // there is no reusable secret to put on a command line at all.
+  processArgs.push(`--token=${await testUtils.getToken(config.url, config.key)}`);
   // Explicit even though it's the runner default: the stress baseline must only run
   // stressTest-marked tests regardless of how the runner's default evolves.
   processArgs.push('--mode=stress');

package/bin/commands/tsc.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.tsc = tsc;
+var _child_process = require("child_process");
+var _toolchain = require("../utils/toolchain");
+/**
+ * `grok tsc ...` runs the workspace TypeScript compiler (the one `@datagrok/build-config` pins) with the
+ * given arguments, so package scripts never depend on a locally installed `tsc`. After an emitting run
+ * in a library, the assets its sources import are mirrored into dist/.
+ */
+async function tsc(args) {
+  const cwd = process.cwd();
+  const extra = process.argv.slice(process.argv.indexOf('tsc') + 1);
+  const emitting = !extra.includes('--noEmit');
+  if (emitting) (0, _toolchain.ensureLibraryExports)(cwd);
+  const r = (0, _child_process.spawnSync)(process.execPath, [(0, _toolchain.toolchain)(cwd).tsc, ...extra], {
+    stdio: 'inherit',
+    cwd
+  });
+  if (r.status !== 0) return false;
+  if (emitting) (0, _toolchain.copyLibraryAssets)(cwd);
+  return true;
+}

package/bin/grok.js

@@ -9,31 +9,45 @@ const argv = require('minimist')(process.argv.slice(2), {
 // test.ts / playwright-runner.ts never fired and `--no-retry` was silently ignored
 // (Playwright kept retrying failed specs). Normalize back to the flag the commands read.
 if (argv.retry === false) argv['no-retry'] = true;
-const help = require('./commands/help').help;
+// The help texts are a large module; load them only when one is printed.
+let _help;
+const help = new Proxy({}, {get: (_, key) => (_help ??= require('./commands/help').help)[key]});
 const runAllCommand = require('./utils/utils').runAll;
 
+// Each command module is loaded only when invoked: loading all of them (puppeteer, ts-morph,
+// archiver, inquirer) used to cost ~6 s of start-up on every `grok api` / `grok check`.
+const lazy = (file, name) => (args) => require(`./commands/${file}`)[name](args);
 const commands = {
-  add: require('./commands/add').add,
-  api: require('./commands/api').api,
-  build: require('./commands/build').build,
-  check: require('./commands/check').check,
-  claude: require('./commands/claude').claude,
-  config: require('./commands/config').config,
-  create: require('./commands/create').create,
-  'docker-gen': require('./commands/docker-gen').dockerGen,
-  init: require('./commands/init').init,
-  link: require('./commands/link').link,
-  publish: require('./commands/publish').publish,
-  report: require('./commands/report').report,
-  run: require('./commands/run').run,
-  test: require('./commands/test').test,
-  testall: require('./commands/test-all').testAll,
-  stresstest: require('./commands/stress-tests').stressTests,
-  migrate: require('./commands/migrate').migrate,
-  server: require('./commands/server').server,
-  s: require('./commands/server').server,
+  add: lazy('add', 'add'),
+  api: lazy('api', 'api'),
+  build: lazy('build', 'build'),
+  check: lazy('check', 'check'),
+  claude: lazy('claude', 'claude'),
+  config: lazy('config', 'config'),
+  create: lazy('create', 'create'),
+  'docker-gen': lazy('docker-gen', 'dockerGen'),
+  init: lazy('init', 'init'),
+  link: lazy('link', 'link'),
+  login: lazy('login', 'login'),
+  publish: lazy('publish', 'publish'),
+  report: lazy('report', 'report'),
+  run: lazy('run', 'run'),
+  test: lazy('test', 'test'),
+  tsc: lazy('tsc', 'tsc'),
+  testall: lazy('test-all', 'testAll'),
+  stresstest: lazy('stress-tests', 'stressTests'),
+  migrate: lazy('migrate', 'migrate'),
+  server: lazy('server', 'server'),
+  s: lazy('server', 'server'),
+  setup: lazy('setup', 'setup'),
 };
 
+// `--version` is a string option (grok publish --version 1.10), so a bare `grok --version` parses as ''.
+if (argv._.length === 0 && ('version' in argv && argv.version === '' || argv.v === true)) {
+  console.log(require('../package.json').version);
+  process.exit(0);
+}
+
 const onPackageCommandNames = ['api', 'check', 'link', 'publish', 'test'];
 
 // A machine-readable run prints its error as JSON on stderr (server.ts) and nothing else:

package/bin/utils/color-utils.js

@@ -5,7 +5,9 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.isVerbose = exports.info = exports.fail = exports.error = void 0;
 exports.log = log;
-exports.warn = exports.success = exports.setVerbose = void 0;
+exports.setVerbose = void 0;
+exports.step = step;
+exports.warn = exports.success = void 0;
 const error = s => console.log('\x1b[31m%s\x1b[0m', s);
 exports.error = error;
 const info = s => console.log('\x1b[32m%s\x1b[0m', s);
@@ -42,4 +44,31 @@ function log(s, type = 'plain') {
       console.log(s);
       break;
   }
+}
+
+/**
+ * One step of a multi-step command: prints its label, ticks a spinner while [action] runs, and
+ * replaces the line with the outcome. A spinner needs a terminal to erase lines, so a CI log
+ * (or a redirected stdout) gets one plain line per step instead.
+ */
+async function step(label, action) {
+  const tty = process.stdout.isTTY === true;
+  const frames = ['-', '\\', '|', '/'];
+  let frame = 0;
+  const draw = () => process.stdout.write(`\r  ${frames[frame++ % frames.length]} ${label}   `);
+  if (!tty) console.log(`  ${label}...`);
+  const timer = tty ? setInterval(draw, 120) : null;
+  if (tty) draw();
+  const finish = (mark, color, text) => {
+    if (timer) clearInterval(timer);
+    if (tty) process.stdout.write(`\r\x1b[2K  \x1b[${color}m${mark}\x1b[0m ${text}\n`);else if (mark !== '+') console.log(`  ${mark} ${text}`);
+  };
+  try {
+    const result = await action();
+    finish('+', '32', label);
+    return result;
+  } catch (e) {
+    finish('x', '31', label);
+    throw e;
+  }
 }

package/bin/utils/dev-key.js

@@ -5,6 +5,9 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.devKeyFetch = devKeyFetch;
 exports.devKeyHeaders = devKeyHeaders;
+exports.keypairToken = keypairToken;
+var keypair = _interopRequireWildcard(require("./keypair"));
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 const fetch = require('node-fetch');
 
 /** `Authorization` header carrying the developer key. */
@@ -15,13 +18,50 @@ function devKeyHeaders(key, headers = {}) {
   };
 }
 
+/** One login per API root per process: every publish step reuses the token. */
+const tokenCache = new Map();
+
+/**
+ * Bearer token obtained by signing a nonce with the server's registered keypair,
+ * or `null` when no keypair is configured for [apiRoot] and the caller should
+ * fall back to the developer key.
+ */
+async function keypairToken(apiRoot, devKey) {
+  const privateKey = keypair.keypairFor(apiRoot, devKey);
+  if (!privateKey) return null;
+  if (!tokenCache.has(apiRoot)) tokenCache.set(apiRoot, keypair.keyLogin(apiRoot, privateKey));
+  try {
+    return await tokenCache.get(apiRoot);
+  } catch (e) {
+    // A server without the keypair endpoints is a reason to use the developer key that is
+    // still configured, not to stop: one config usually names stands of both vintages.
+    if (e?.name !== 'ServerTooOldError' || !devKey) throw e;
+    tokenCache.delete(apiRoot);
+    return null;
+  }
+}
+
 /**
- * Calls [url] with the developer key in the `Authorization` header, falling back to
- * [legacyUrl] - which carries the key as a path segment - for servers that predate the
- * header form. Those answer 404 (no such route) or 401 (the route-less path is not on
- * their anonymous allow-list); a server that knows the header form answers neither.
+ * Calls [url] as the configured user. With a keypair (`grok login`) that is a
+ * session token; otherwise the developer key rides in the `Authorization`
+ * header, falling back to [legacyUrl] - which carries the key as a path segment -
+ * for servers that predate the header form. Those answer 404 (no such route) or
+ * 401 (the route-less path is not on their anonymous allow-list); a server that
+ * knows the header form answers neither.
+ *
+ * [apiRoot] enables the keypair path; without it this stays dev-key only.
  */
-async function devKeyFetch(url, legacyUrl, key, init = {}) {
+async function devKeyFetch(url, legacyUrl, key, init = {}, apiRoot) {
+  if (apiRoot != null) {
+    const token = await keypairToken(apiRoot, key);
+    if (token) return await fetch(url, {
+      ...init,
+      headers: {
+        ...init.headers,
+        'Authorization': token
+      }
+    });
+  }
   const response = await fetch(url, {
     ...init,
     headers: devKeyHeaders(key, init.headers)

package/bin/utils/keypair.js

@@ -0,0 +1,292 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ServerTooOldError = exports.MIN_SERVER_VERSION = void 0;
+exports.enrollWithCode = enrollWithCode;
+exports.fingerprint = fingerprint;
+exports.generateKeyPair = generateKeyPair;
+exports.getServerCredentials = getServerCredentials;
+exports.hasKeypair = hasKeypair;
+exports.keyFilePath = keyFilePath;
+exports.keyFromEnv = keyFromEnv;
+exports.keyLogin = keyLogin;
+exports.keypairFor = keypairFor;
+exports.publicPart = publicPart;
+exports.readConfig = readConfig;
+exports.savePrivateKey = savePrivateKey;
+exports.signNonce = signNonce;
+exports.writeConfig = writeConfig;
+var _crypto = _interopRequireDefault(require("crypto"));
+var _fs = _interopRequireDefault(require("fs"));
+var _os = _interopRequireDefault(require("os"));
+var _path = _interopRequireDefault(require("path"));
+var _jsYaml = _interopRequireDefault(require("js-yaml"));
+const grokDir = _path.default.join(_os.default.homedir(), '.grok');
+const confPath = _path.default.join(grokDir, 'config.yaml');
+const keysDir = _path.default.join(grokDir, 'keys');
+
+/** Prefix the server wraps a nonce in before checking the signature. */
+const SIGNATURE_PREFIX = 'datagrok-login:';
+/** Generates the keypair `grok login` registers: EC P-256, the JOSE ES256 curve. */
+function generateKeyPair() {
+  const {
+    publicKey,
+    privateKey
+  } = _crypto.default.generateKeyPairSync('ec', {
+    namedCurve: 'prime256v1'
+  });
+  return {
+    publicKey: publicKey.export({
+      format: 'jwk'
+    }),
+    privateKey: privateKey.export({
+      format: 'jwk'
+    })
+  };
+}
+
+/** The public half of a private JWK — what gets registered on the server. */
+function publicPart(privateKey) {
+  const {
+    d,
+    p,
+    q,
+    dp,
+    dq,
+    qi,
+    ...pub
+  } = privateKey;
+  return pub;
+}
+
+/**
+ * RFC 7638 JWK thumbprint, base64url without padding. The server computes the
+ * same value from the stored key, so this is what identifies a key at login.
+ */
+function fingerprint(jwk) {
+  const members = {
+    EC: ['crv', 'kty', 'x', 'y'],
+    RSA: ['e', 'kty', 'n']
+  };
+  const order = members[jwk.kty];
+  if (!order) throw new Error(`Unsupported key type "${jwk.kty}" - expected EC or RSA`);
+  const canonical = '{' + order.map(m => `${JSON.stringify(m)}:${JSON.stringify(jwk[m])}`).join(',') + '}';
+  return _crypto.default.createHash('sha256').update(canonical).digest('base64url');
+}
+
+/**
+ * Signs the login nonce. [audience] is the API root this client dialed: it is part of what is
+ * signed, so a server cannot relay the signature to a second stand where the same key is
+ * enrolled. ECDSA signatures go out in the raw r||s form (JOSE's, not DER's), which is what
+ * the server's verifier expects.
+ */
+function signNonce(privateKey, audience, nonce) {
+  const key = _crypto.default.createPrivateKey({
+    key: privateKey,
+    format: 'jwk'
+  });
+  const options = {
+    key
+  };
+  if (privateKey.kty === 'EC') options.dsaEncoding = 'ieee-p1363';
+  return _crypto.default.sign('sha256', Buffer.from(`${SIGNATURE_PREFIX}${audience}:${nonce}`), options).toString('base64url');
+}
+
+/** Exchanges a keypair for a session token: ask for a nonce, sign it, log in. */
+async function keyLogin(url, privateKey) {
+  const fp = fingerprint(publicPart(privateKey));
+  const challenge = await postJson(`${url}/users/login/key/challenge`, {
+    fingerprint: fp
+  });
+  const response = await postJson(`${url}/users/login/key`, {
+    fingerprint: fp,
+    audience: url,
+    nonce: challenge.nonce,
+    signature: signNonce(privateKey, url, challenge.nonce)
+  });
+  if (response.isSuccess !== true) throw new Error(response.comment ?? 'Key login failed');
+  return response.token;
+}
+
+/** Registers [publicKey] with a one-shot enrollment code from the user profile. */
+async function enrollWithCode(url, code, publicKey, name, expires) {
+  return await postJson(`${url}/users/keys/enroll`, {
+    code,
+    name,
+    expires,
+    publicKey: JSON.stringify(publicKey)
+  });
+}
+
+/** The first Datagrok that has the keypair endpoints. */
+const MIN_SERVER_VERSION = exports.MIN_SERVER_VERSION = '1.28';
+
+/**
+ * Thrown when the server has no keypair endpoints at all. Callers that still hold a developer
+ * key catch it and fall back; `grok login` reports it, since there is nothing to fall back to.
+ */
+class ServerTooOldError extends Error {
+  constructor(server) {
+    super(`${server} does not support keypair authentication — it needs Datagrok ` + `${MIN_SERVER_VERSION} or later. Use a developer key for this server ` + '(grok config add --alias <alias> --server <url> --key <key>), or ask its operator to upgrade.');
+    this.server = server;
+    this.name = 'ServerTooOldError';
+  }
+}
+exports.ServerTooOldError = ServerTooOldError;
+async function postJson(url, body) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  });
+  // These routes are anonymous on every server that has them. A server that does not answers
+  // 404 (no such route) or 401 (unknown paths are refused before routing) — either way, the
+  // keypair endpoints are simply not there.
+  if (response.status === 404 || response.status === 401) throw new ServerTooOldError(new URL(url).origin);
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Unexpected response from ${url} (status ${response.status}): ${text.slice(0, 200)}`);
+  }
+}
+function keyFilePath(alias) {
+  return _path.default.join(keysDir, `${alias}.json`);
+}
+
+/** Writes the private key readable only by its owner, the way ssh-keygen does. */
+function savePrivateKey(alias, privateKey) {
+  _fs.default.mkdirSync(keysDir, {
+    recursive: true,
+    mode: 0o700
+  });
+  const file = keyFilePath(alias);
+  _fs.default.writeFileSync(file, JSON.stringify(privateKey, null, 2), {
+    mode: 0o600
+  });
+  // mkdirSync/writeFileSync ignore `mode` when the path already exists.
+  try {
+    _fs.default.chmodSync(keysDir, 0o700);
+    _fs.default.chmodSync(file, 0o600);
+  } catch {/* Windows has no POSIX modes; ACLs already keep it in the profile. */}
+  return file;
+}
+function readConfig() {
+  if (!_fs.default.existsSync(confPath)) return {
+    servers: {},
+    default: ''
+  };
+  return _jsYaml.default.load(_fs.default.readFileSync(confPath, {
+    encoding: 'utf-8'
+  })) ?? {
+    servers: {},
+    default: ''
+  };
+}
+function writeConfig(config) {
+  _fs.default.mkdirSync(grokDir, {
+    recursive: true
+  });
+  _fs.default.writeFileSync(confPath, _jsYaml.default.dump(config));
+}
+
+/**
+ * The key at [file], or `undefined` when there is none. A config can name a key file the
+ * deployment has not filled in yet — CI writes the entry and the secret separately — and that
+ * has to mean "fall back to the developer key". A file that exists but cannot be read or parsed
+ * is a different thing, and says so.
+ */
+function tryLoadKeyFile(file) {
+  const expanded = file.startsWith('~') ? _path.default.join(_os.default.homedir(), file.slice(1)) : file;
+  let text;
+  try {
+    text = _fs.default.readFileSync(expanded, {
+      encoding: 'utf-8'
+    });
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    throw new Error(`cannot read the private key at ${expanded}: ${error?.message ?? error}`);
+  }
+  try {
+    return parseKey(text);
+  } catch (error) {
+    throw new Error(`${expanded} is not a private key in JWK form: ${error?.message ?? error}`);
+  }
+}
+
+/**
+ * The credentials for one server: its config entry, with `GROK_PRIVATE_KEY`
+ * taking precedence so a CI job can hold the key in a secret rather than on
+ * disk. [hostKey] is an alias, a URL, or empty for the default server.
+ */
+function getServerCredentials(hostKey) {
+  const config = readConfig();
+  let host = (hostKey === '' || hostKey == null ? config.default : hostKey).trim();
+  let entry;
+  let alias;
+  let url;
+  try {
+    url = new URL(host).href;
+    if (url.endsWith('/')) url = url.slice(0, -1);
+    // Several aliases can name the same server. Prefer one that has a keypair: a
+    // dev-key-only entry matching first would silently downgrade the login.
+    const matches = Object.keys(config.servers ?? {}).filter(name => config.servers[name].url === url);
+    alias = matches.find(name => config.servers[name].keyFile || _fs.default.existsSync(keyFilePath(name))) ?? matches[0];
+    entry = alias == null ? undefined : config.servers[alias];
+  } catch (error) {
+    entry = config.servers?.[host];
+    if (entry == null) throw new Error(`Unknown server alias. Please add it to ${confPath}`);
+    alias = host;
+    url = entry.url;
+  }
+  const cred = {
+    url: url,
+    alias,
+    key: entry?.key,
+    login: entry?.login
+  };
+  if (process.env.GROK_PRIVATE_KEY) {
+    cred.privateKey = parseKey(process.env.GROK_PRIVATE_KEY);
+    cred.privateKeySource = 'GROK_PRIVATE_KEY';
+  } else if (entry?.keyFile && (cred.privateKey = tryLoadKeyFile(entry.keyFile)) != null) cred.privateKeySource = entry.keyFile;else if (alias && (cred.privateKey = tryLoadKeyFile(keyFilePath(alias))) != null) cred.privateKeySource = keyFilePath(alias);
+  if (process.env.GROK_LOGIN) cred.login = process.env.GROK_LOGIN;
+  return cred;
+}
+
+/** A JWK, raw or base64-encoded — CI secret stores mangle multi-line values. */
+function parseKey(value) {
+  const text = value.trim().startsWith('{') ? value : Buffer.from(value.trim(), 'base64').toString('utf-8');
+  return JSON.parse(text);
+}
+function hasKeypair(cred) {
+  return cred.privateKey != null;
+}
+
+/** A private JWK held in an environment variable, raw or base64-encoded. */
+function keyFromEnv(name) {
+  const value = process.env[name];
+  return value ? parseKey(value) : undefined;
+}
+
+/**
+ * The private key to use for [url], or `undefined` to fall back to the developer
+ * key. An explicitly supplied [devKey] that differs from the one configured for
+ * this server means the caller wants *that* identity - a second CI user, say -
+ * so the configured keypair must not silently take over.
+ */
+function keypairFor(url, devKey) {
+  let cred;
+  try {
+    cred = getServerCredentials(url);
+  } catch {
+    return undefined;
+  }
+  if (cred.privateKey == null) return undefined;
+  if (devKey && devKey !== cred.key) return undefined;
+  return cred.privateKey;
+}