@zeyos/cli 0.4.0 → 0.6.0

package/commands/sum.mjs

@@ -0,0 +1,112 @@
+/**
+ * zeyos sum <resource> <field>
+ *
+ * Page through records and sum one numeric field client-side.
+ */
+
+import { normalizeListResult } from '@zeyos/client';
+import {
+  buildCliClient,
+  callApi,
+  fail,
+  maybeDryRun,
+  normalizeFilterOperators,
+  parseJsonOptionOrFile,
+  requireResource
+} from '../lib/command.mjs';
+import { outputMode, printJson, printYaml } from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos sum <resource> <field> [options]
+
+Sum a numeric field across all records matching an optional filter.
+The CLI pages internally so agents do not need to list rows and write ad hoc scripts.
+
+Arguments:
+  resource            Resource name (e.g. actionsteps, transactions, payments)
+  field               Numeric field to sum (e.g. effort, amount, netamount)
+
+Options:
+  --filter <json>     JSON filter object  e.g. '{"status":[1,3]}'
+                      Arrays normalize to IN; $lt/$lte/$gt/$gte/$ne/$in/$nin and suffix
+                      keys like field__startswith/field__gt normalize to native operators
+  --filter-file <path>
+                      Read JSON filter object from a file
+  --page-size <n>     Records per API page (default: 50)
+  --limit <n>         Maximum records to inspect
+  --offset <n>        Initial offset (default: 0)
+  --json              Output as JSON ({ "sum": N, "count": N })
+  --yaml              Output as YAML
+  --query             Print the first page request without sending it
+  -h, --help          Show this help
+
+Examples:
+  zeyos sum actionsteps effort --filter '{"status":[1,3]}'
+  zeyos sum transactions netamount --filter '{"type":3}' --json
+`;
+
+export async function run(values, positional) {
+  const resourceName = positional[0];
+  const field = positional[1];
+  const res = requireResource(resourceName, 'zeyos sum <resource> <field>');
+  if (!field) fail('Missing field name.  Usage: zeyos sum <resource> <field>');
+
+  const pageSize = parsePositiveInt(values['page-size'] ?? '50', '--page-size');
+  const maxRows = values.limit == null ? Infinity : parsePositiveInt(values.limit, '--limit');
+  let offset = values.offset == null ? 0 : parseNonNegativeInt(values.offset, '--offset');
+
+  const body = { fields: [field], limit: Math.min(pageSize, maxRows), offset };
+  const filters = parseJsonOptionOrFile(values, 'filter', 'filter-file');
+  if (filters !== undefined) body.filters = normalizeFilterOperators(filters, { fieldAliases: res.filterAliases });
+
+  const clientState = buildCliClient(values);
+  if (await maybeDryRun(clientState, res.list, body, values)) return;
+
+  let sum = 0;
+  let count = 0;
+
+  while (count < maxRows) {
+    const remaining = maxRows - count;
+    const limit = Math.min(pageSize, remaining);
+    const pageBody = { ...body, limit, offset };
+    const result = await callApi(clientState, res.list, pageBody);
+    const rows = normalizeListResult(result).data;
+
+    for (const row of rows) {
+      sum += numericValue(row[field], field);
+      count += 1;
+      if (count >= maxRows) break;
+    }
+
+    if (rows.length < limit || rows.length === 0) break;
+    offset += rows.length;
+  }
+
+  const mode = outputMode(values);
+  if (mode === 'json') {
+    printJson({ sum, count, field });
+  } else if (mode === 'yaml') {
+    printYaml({ sum, count, field });
+  } else {
+    process.stdout.write(`${sum}\n`);
+  }
+}
+
+function numericValue(value, field) {
+  if (value == null || value === '') return 0;
+  const n = Number(value);
+  if (!Number.isFinite(n)) fail(`Field "${field}" contains a non-numeric value: ${JSON.stringify(value)}`);
+  return n;
+}
+
+function parsePositiveInt(value, flag) {
+  const n = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(n) || n <= 0) fail(`${flag} must be a positive integer.`);
+  return n;
+}
+
+function parseNonNegativeInt(value, flag) {
+  const n = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(n) || n < 0) fail(`${flag} must be a non-negative integer.`);
+  return n;
+}

package/commands/whoami.mjs

@@ -9,8 +9,11 @@
  *   --show-token Include the current access token in output
  */
 
+import { createInterface } from 'node:readline';
 import { buildClient, syncTokens } from '../lib/client.mjs';
+import { globalConfigPath, profilesConfigPath } from '../lib/config.mjs';
 import { outputMode, printJson, printYaml, printRecord, formatDate, error } from '../lib/output.mjs';
+import { run as runLogin } from './login.mjs';
 
 export const USAGE = `\
 Usage: zeyos whoami [options]
@@ -25,35 +28,23 @@ Options:
 `;
 
 export async function run(values) {
-  let client, config, tokenStore, configSource;
-  try {
-    ({ client, config, tokenStore, configSource } = buildClient({}, { profile: values.profile }));
-  } catch (err) {
-    error(err.message);
-    process.exit(1);
-  }
+  let state = _buildClientState(values);
 
   let userInfo;
   try {
-    userInfo = await client.oauth2.getUserInfo();
-    await syncTokens(tokenStore, configSource);
+    userInfo = await _fetchUserInfo(state);
   } catch (err) {
-    const status = err?.status;
-    if (status === 502 || status === 503 || status === 504) {
-      error(`ZeyOS instance is temporarily unavailable (HTTP ${status}). The server at ${config.baseUrl} may be down or restarting — this is server-side, not your credentials.`);
-    } else if (status === 401) {
-      error('Your session has expired or is invalid. Re-authenticate with: zeyos login --force');
-    } else {
-      error(`Failed to fetch user info: ${err.message}`);
-    }
-    process.exit(1);
+    const handled = await _handleFetchError(err, state, values);
+    if (!handled) process.exit(1);
+    state = handled.state;
+    userInfo = handled.userInfo;
   }
 
   const mode = outputMode(values);
 
   const output = { ...userInfo };
   if (values['show-token']) {
-    const tokenSet = await tokenStore.get();
+    const tokenSet = await state.tokenStore.get();
     if (tokenSet?.accessToken) output.accessToken = tokenSet.accessToken;
   }
 
@@ -63,7 +54,7 @@ export async function run(values) {
     printYaml(output);
   } else {
     // Pretty key-value record with custom formatters
-    const dateFormat = config.dateFormat ?? 'YYYY-MM-DD HH:mm';
+    const dateFormat = state.config.dateFormat ?? 'YYYY-MM-DD HH:mm';
     const keys = Object.keys(output);
     const formatters = {};
 
@@ -86,6 +77,56 @@ export async function run(values) {
   }
 }
 
+function _buildClientState(values) {
+  try {
+    const state = buildClient({}, { profile: values.profile });
+    return {
+      client: state.client,
+      config: state.config,
+      tokenStore: state.tokenStore,
+      configSource: state.configSource
+    };
+  } catch (err) {
+    error(err.message);
+    process.exit(1);
+  }
+}
+
+async function _fetchUserInfo(state) {
+  const userInfo = await state.client.oauth2.getUserInfo();
+  await syncTokens(state.tokenStore, state.configSource);
+  return userInfo;
+}
+
+async function _handleFetchError(err, state, values) {
+  const status = err?.status;
+  if (status === 502 || status === 503 || status === 504) {
+    error(`ZeyOS instance is temporarily unavailable (HTTP ${status}). The server at ${state.config.baseUrl} may be down or restarting — this is server-side, not your credentials.`);
+    return null;
+  }
+
+  const authFailure = _authFailureSummary(err);
+  if (!authFailure) {
+    error(`Failed to fetch user info: ${err.message}`);
+    return null;
+  }
+
+  error(_formatAuthFailure(authFailure, err, state.config, state.configSource, values));
+  const reauthenticated = await _maybeReauthenticate(state.configSource, values);
+  if (!reauthenticated) return null;
+
+  const nextState = _buildClientState(values);
+  try {
+    return {
+      state: nextState,
+      userInfo: await _fetchUserInfo(nextState)
+    };
+  } catch (retryErr) {
+    error(`Re-authentication completed, but fetching user info still failed: ${retryErr.message}`);
+    return null;
+  }
+}
+
 /**
  * Format an array of objects as a multi-line list.
  * Each item is shown as "name (rw)" or "name (ro)" on its own line.
@@ -105,3 +146,145 @@ function _formatObjectList(items, nameKey, writableKey) {
     })
     .join('\n');
 }
+
+function _isInvalidRefreshTokenError(err) {
+  const detail = `${err?.message ?? ''}\n${_stringifyErrorBody(err?.body)}`;
+  return [400, 401, 403].includes(err?.status) &&
+    /refresh[_ -]?token|invalid_grant/i.test(detail) &&
+    /invalid|expired|forbidden|invalid_grant/i.test(detail);
+}
+
+function _authFailureSummary(err) {
+  if (_isInvalidRefreshTokenError(err)) {
+    return 'Your stored refresh token is invalid or expired.';
+  }
+  if (err?.status === 401) {
+    return 'Your session has expired or is invalid.';
+  }
+  return null;
+}
+
+function _formatAuthFailure(summary, err, config, source, values) {
+  const lines = [
+    summary,
+    `Platform URL: ${config.baseUrl ?? '(not configured)'}`,
+    `Credential source: ${_describeConfigSource(source)}`
+  ];
+
+  if (err?.url) {
+    lines.push(`OAuth endpoint: ${err.url}`);
+  }
+  if (err?.status) {
+    lines.push(`HTTP status: ${err.status}${err.statusText ? ` ${err.statusText}` : ''}`);
+  }
+
+  const detail = _authErrorDetail(err);
+  if (detail) {
+    lines.push(`OAuth error: ${detail}`);
+  }
+
+  lines.push(`Next step: ${_loginCommand(source, values)}`);
+  if (process.env.ZEYOS_TOKEN || process.env.ZEYOS_REFRESH_TOKEN) {
+    lines.push('Note: ZEYOS_TOKEN or ZEYOS_REFRESH_TOKEN is set and overrides stored credentials; update or unset it before retrying.');
+  }
+  return lines.join('\n');
+}
+
+function _describeConfigSource(source) {
+  if (!source) {
+    return 'environment variables';
+  }
+  if (source.kind === 'profile') {
+    return `profile "${source.name}" (${profilesConfigPath()})`;
+  }
+  if (source.kind === 'global') {
+    return `global credentials (${globalConfigPath()})`;
+  }
+  if (source.kind === 'local') {
+    return `local file ${source.path ?? '.zeyos/auth.json'}`;
+  }
+  return source.kind ?? 'unknown';
+}
+
+function _loginCommand(source, values) {
+  const profile = values.profile ?? (source?.kind === 'profile' ? source.name : null);
+  if (profile) {
+    return `zeyos login --profile ${_quoteArg(profile)} --force`;
+  }
+  if (source?.kind === 'global') {
+    return 'zeyos login --global --force';
+  }
+  return 'zeyos login --force';
+}
+
+async function _maybeReauthenticate(source, values) {
+  if (!_canPromptForReauthentication(source, values)) {
+    return false;
+  }
+
+  const command = _loginCommand(source, values);
+  const confirmed = await _confirm(`Re-authenticate now (${command})? [y/N] `);
+  if (!confirmed) return false;
+
+  await runLogin(_loginValues(source, values));
+  return true;
+}
+
+function _canPromptForReauthentication(source, values) {
+  return Boolean(source) &&
+    !values.json &&
+    !values.yaml &&
+    process.stdin.isTTY &&
+    process.stderr.isTTY &&
+    !process.env.ZEYOS_TOKEN &&
+    !process.env.ZEYOS_REFRESH_TOKEN;
+}
+
+function _loginValues(source, values) {
+  return {
+    ...values,
+    force: true,
+    profile: values.profile ?? (source?.kind === 'profile' ? source.name : undefined),
+    global: source?.kind === 'global' ? true : values.global
+  };
+}
+
+function _confirm(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise(resolve => {
+    rl.question(prompt, answer => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+function _authErrorDetail(err) {
+  const body = _stringifyErrorBody(err?.body).trim();
+  if (body) {
+    return body;
+  }
+  return String(err?.message ?? '').trim();
+}
+
+function _stringifyErrorBody(body) {
+  if (body == null) {
+    return '';
+  }
+  if (typeof body === 'string') {
+    return body;
+  }
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return String(body);
+  }
+}
+
+function _quoteArg(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) {
+    return text;
+  }
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}

package/lib/client.mjs

@@ -23,29 +23,47 @@ export function buildClient(overrides = {}, opts = {}) {
     throw new Error(`Profile "${loaded.profile.name}" not found (selected via ${loaded.profile.origin}). ${known}`);
   }
   const config = { ...loaded.config, ...overrides };
-  requireConfig(['baseUrl', 'clientId', 'clientSecret', 'accessToken'], config);
+  const tokenOnly = isTokenOnlyMode(config);
+  requireConfig(tokenOnly ? ['baseUrl', 'accessToken'] : ['baseUrl', 'clientId', 'clientSecret', 'accessToken'], config);
 
-  const tokenStore = new MemoryTokenStore({
-    accessToken:           config.accessToken,
-    refreshToken:          config.refreshToken,
-    expiresAt:             config.expiresAt,
-    refreshTokenExpiresAt: config.refreshTokenExpiresAt,
-  });
+  const tokenStore = new MemoryTokenStore(tokenOnly
+    ? { accessToken: config.accessToken }
+    : {
+        accessToken:           config.accessToken,
+        refreshToken:          config.refreshToken,
+        expiresAt:             config.expiresAt,
+        refreshTokenExpiresAt: config.refreshTokenExpiresAt,
+      });
 
-  const client = createZeyosClient({
-    platform: config.baseUrl,
-    auth: {
-      mode: 'oauth',
-      oauth: {
+  const oauth = tokenOnly
+    ? {
+        tokenStore,
+        autoRefresh: false,
+      }
+    : {
         clientId:     config.clientId,
         clientSecret: config.clientSecret,
         tokenStore,
         autoRefresh:  true,
-      },
+      };
+
+  const client = createZeyosClient({
+    platform: config.baseUrl,
+    auth: {
+      mode: 'oauth',
+      oauth,
     },
   });
 
-  return { client, config, tokenStore, configSource: loaded.source };
+  return { client, config, tokenStore, configSource: tokenOnly ? null : loaded.source, tokenOnly };
+}
+
+function isTruthyEnv(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function isTokenOnlyMode(config) {
+  return Boolean(process.env.ZEYOS_TOKEN) || (isTruthyEnv(process.env.ZEYOS_NO_REFRESH) && Boolean(config.accessToken));
 }
 
 /**

package/lib/command.mjs

@@ -99,6 +99,134 @@ export function parseJsonOptionOrFile(values, flagName, fileFlagName = `${flagNa
   return undefined;
 }
 
+const FILTER_OPERATOR_ALIASES = {
+  $lt: '<',
+  $lte: '<=',
+  $gt: '>',
+  $gte: '>=',
+  $ne: '!=',
+  $in: 'IN',
+  $nin: '!IN',
+  $notIn: '!IN',
+  lt: '<',
+  lte: '<=',
+  gt: '>',
+  gte: '>=',
+  ne: '!=',
+  in: 'IN',
+  nin: '!IN',
+  notIn: '!IN',
+  notin: '!IN'
+};
+
+const FILTER_SUFFIX_OPERATOR_ALIASES = {
+  lt: '<',
+  lte: '<=',
+  gt: '>',
+  gte: '>=',
+  ne: '!=',
+  in: 'IN',
+  nin: '!IN',
+  notin: '!IN'
+};
+
+const FILTER_PATTERN_SUFFIXES = new Set([
+  'startswith',
+  'istartswith',
+  'like',
+  'ilike',
+  'contains',
+  'icontains',
+  'regex',
+  'iregex'
+]);
+
+export function normalizeFilterOperators(value, options = {}) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeFilterOperators(item, options));
+  }
+  if (!value || typeof value !== 'object') return value;
+
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    const suffixFilter = parseFilterSuffix(key, child, options);
+    if (suffixFilter) {
+      mergeFieldFilter(out, suffixFilter.field, suffixFilter.operator, suffixFilter.value);
+      continue;
+    }
+
+    const normalizedKey = FILTER_OPERATOR_ALIASES[key] || key;
+    const outputKey = isFilterOperatorKey(normalizedKey)
+      ? normalizedKey
+      : normalizeFieldAlias(normalizedKey, options);
+    const normalizedChild = normalizeFilterOperators(child, options);
+    out[outputKey] = Array.isArray(normalizedChild) && !isFilterOperatorKey(outputKey)
+      ? { IN: normalizedChild }
+      : normalizedChild;
+  }
+  return out;
+}
+
+function isFilterOperatorKey(key) {
+  return ['<', '<=', '>', '>=', '!=', 'IN', '!IN', '~~*'].includes(key);
+}
+
+function normalizeFieldAlias(field, options = {}) {
+  return options.fieldAliases?.[field] || field;
+}
+
+function parseFilterSuffix(key, child, options) {
+  const separator = key.lastIndexOf('__');
+  if (separator <= 0) return null;
+
+  const rawField = key.slice(0, separator);
+  const suffix = key.slice(separator + 2).toLowerCase();
+  const field = normalizeFieldAlias(rawField, options);
+
+  if (Object.prototype.hasOwnProperty.call(FILTER_SUFFIX_OPERATOR_ALIASES, suffix)) {
+    return {
+      field,
+      operator: FILTER_SUFFIX_OPERATOR_ALIASES[suffix],
+      value: normalizeFilterOperators(child, options)
+    };
+  }
+
+  if (FILTER_PATTERN_SUFFIXES.has(suffix)) {
+    return {
+      field,
+      operator: '~~*',
+      value: patternValueForSuffix(suffix, child)
+    };
+  }
+
+  return null;
+}
+
+function patternValueForSuffix(suffix, child) {
+  const value = String(child ?? '');
+  if (suffix === 'startswith' || suffix === 'istartswith') return `${value}%`;
+  if (suffix === 'contains' || suffix === 'icontains') return `%${value}%`;
+  if (suffix === 'regex' || suffix === 'iregex') return regexLikeToSqlLike(value);
+  return value;
+}
+
+function regexLikeToSqlLike(value) {
+  return String(value)
+    .replace(/^\^/, '')
+    .replace(/\$$/, '')
+    .replace(/\\.\\*/g, '%')
+    .replace(/\.\*/g, '%');
+}
+
+function mergeFieldFilter(out, field, operator, value) {
+  const existing = out[field];
+  if (existing && typeof existing === 'object' && !Array.isArray(existing)) {
+    out[field] = { ...existing, [operator]: value };
+    return;
+  }
+  out[field] = { [operator]: value };
+}
+
 /** Cheap structural check: does this string look like an intended JSON object? */
 function looksLikeJsonObject(value) {
   return typeof value === 'string' && value.trim().startsWith('{');

package/lib/config.mjs

@@ -60,6 +60,9 @@ export function loadConfig(opts = {}) {
  */
 export function loadConfigWithSource(opts = {}) {
   const env = _fromEnv();
+  if (env.accessToken) {
+    return { config: env, source: null, profile: null };
+  }
   const selection = resolveProfileSelection({ profileFlag: opts.profile });
 
   let base = {};
@@ -187,6 +190,21 @@ export function clearTokens(scope = 'local') {
   if (path) _writeJson(path, _stripTokens(_readJson(path)));
 }
 
+/** Remove all credential/session fields from the resolved legacy local auth file. */
+export function clearLocalCredentialsForSource(source) {
+  if (!source || source.kind !== 'local') return false;
+  const path = source.path ?? _findLocalPath();
+  if (!path) return false;
+
+  const current = _readJson(path);
+  const hadCredentials = CRED_KEYS.some((key) => Object.prototype.hasOwnProperty.call(current, key));
+  if (!hadCredentials) return false;
+
+  const next = _stripCredentials(current);
+  _writeJson(path, next);
+  return true;
+}
+
 /**
  * Persist refreshed tokens back to wherever the active credentials came from.
  * @param {ConfigSource|null} source
@@ -325,6 +343,11 @@ export function localConfigPath() { return _findLocalPath(); }
 export function globalConfigPath() { return GLOBAL_FILE; }
 export function profilesConfigPath() { return PROFILES_FILE; }
 
+/** Read the legacy global credentials file directly, without applying the cascade. */
+export function loadGlobalConfig() {
+  return _readGlobal();
+}
+
 // ── Internals ────────────────────────────────────────────────────────────────
 
 function _fromEnv() {
@@ -368,6 +391,14 @@ function _stripTokens(o) {
   return rest;
 }
 
+function _stripCredentials(o) {
+  const out = { ...o };
+  for (const key of CRED_KEYS) {
+    delete out[key];
+  }
+  return out;
+}
+
 function _readGlobal() {
   return existsSync(GLOBAL_FILE) ? _readJson(GLOBAL_FILE) : {};
 }

package/lib/resource-config.mjs

@@ -73,7 +73,7 @@ export function loadResourceConfig(name) {
 export function getListFields(res, name, override) {
   // 1. CLI override
   if (override) {
-    return _parseFieldsOverride(override);
+    return _parseFieldsOverride(override, res?.fieldAliases);
   }
 
   // 2. Config file
@@ -181,7 +181,7 @@ export function getGetParams(name) {
  * Parse a --fields override string.
  * Supports: comma-separated, JSON object, JSON array.
  */
-function _parseFieldsOverride(raw) {
+function _parseFieldsOverride(raw, fieldAliases = {}) {
   const trimmed = raw.trim();
 
   // JSON object: {"Alias": "path", ...}
@@ -189,7 +189,7 @@ function _parseFieldsOverride(raw) {
     try {
       const obj = JSON.parse(trimmed);
       if (typeof obj === 'object' && obj !== null && !Array.isArray(obj)) {
-        const apiFields = _toFieldAliasMap(obj);
+        const apiFields = _toFieldAliasMap(obj, fieldAliases);
         return { apiFields, displayColumns: Object.keys(apiFields) };
       }
     } catch (e) {
@@ -205,7 +205,7 @@ function _parseFieldsOverride(raw) {
       if (Array.isArray(arr)) {
         const paths = arr.map(String);
         const apiFields = {};
-        for (const p of paths) apiFields[p] = p;
+        for (const p of paths) apiFields[p] = normalizeFieldAlias(p, fieldAliases);
         return { apiFields, displayColumns: paths };
       }
     } catch (e) {
@@ -217,7 +217,7 @@ function _parseFieldsOverride(raw) {
   // Comma-separated: "ID,name,status"
   const paths = trimmed.split(',').map(s => s.trim()).filter(Boolean);
   const apiFields = {};
-  for (const p of paths) apiFields[p] = p;
+  for (const p of paths) apiFields[p] = normalizeFieldAlias(p, fieldAliases);
   return { apiFields, displayColumns: paths };
 }
 
@@ -227,14 +227,18 @@ function _parseFieldsOverride(raw) {
  * @param {Record<string, JsonValue>} value
  * @returns {Record<string,string>}
  */
-function _toFieldAliasMap(value) {
+function _toFieldAliasMap(value, fieldAliases = {}) {
   const fields = {};
   for (const [alias, field] of Object.entries(value)) {
-    fields[String(alias)] = String(field);
+    fields[String(alias)] = normalizeFieldAlias(String(field), fieldAliases);
   }
   return fields;
 }
 
+function normalizeFieldAlias(field, fieldAliases = {}) {
+  return fieldAliases[field] || field;
+}
+
 // ── Internals ────────────────────────────────────────────────────────────────
 
 /**