@zeyos/cli 0.1.1

package/commands/get.mjs

@@ -0,0 +1,127 @@
+/**
+ * zeyos get <resource> <id>
+ * zeyos show <resource> <id>
+ *
+ * Fetch and display a single record by ID.
+ *
+ * Options:
+ *   --fields <list>    Fields to display (comma-separated or JSON)
+ *   --extdata          Include extended data fields
+ *   --tags             Include tags
+ *   --expand <list>    Expand JSON/binary columns  e.g. 'binfile'
+ *   --all              Fetch all data (extdata, tags, all fields)
+ *   --json             Output as JSON
+ *   --yaml             Output as YAML
+ */
+
+import { loadConfig }                    from '../lib/config.mjs';
+import { canonicalName }                 from '../lib/resources.mjs';
+import { getGetFields, getGetParams }    from '../lib/resource-config.mjs';
+import { outputMode, printJson, printYaml, printRecord, buildDateFormatters } from '../lib/output.mjs';
+import {
+  buildCliClient,
+  callApi,
+  fail,
+  requireRecordId,
+  requireResource
+} from '../lib/command.mjs';
+
+export const USAGE = `\
+Usage: zeyos get <resource> <id> [options]
+       zeyos show <resource> <id> [options]
+
+Fetch and display a single record.
+
+Arguments:
+  resource            Resource name (e.g. ticket, account)
+  id                  Record ID
+
+Options:
+  --fields <list>     Fields to display
+  --extdata           Include extended data fields
+  --tags              Include tags
+  --expand <list>     Expand JSON/binary columns (e.g. binfile, items)
+  --all               Fetch all data (extdata + tags + all fields)
+  --json              Output as JSON
+  --yaml              Output as YAML
+  -h, --help          Show this help
+
+Fields format:
+  Comma-separated:    --fields ID,name,status,duedate
+  JSON object:        --fields '{"Id": "ID", "Name": "name"}'
+
+Examples:
+  zeyos get ticket 42
+  zeyos get ticket 42 --extdata
+  zeyos get ticket 42 --extdata --tags
+  zeyos get ticket 42 --all
+  zeyos show account 7 --json
+`;
+
+export async function run(values, positional) {
+  const resourceName = positional[0];
+  const id           = positional[1];
+
+  const res = requireResource(resourceName, 'zeyos get <resource> <id>', 'get', 'single-record fetch');
+  requireRecordId(id, 'zeyos get <resource> <id>');
+
+  const resName = canonicalName(resourceName);
+  const clientState = buildCliClient();
+
+  // ── Build params ───────────────────────────────────────────────────────────
+  // GET endpoints use query parameters like ?extdata=1&tags=1 to include
+  // additional data.  The `expand` parameter is only for JSON/binary columns.
+  const params = { ID: id };
+
+  // Collect query params from CLI flags, config defaults, and --all
+  const query = getGetParams(resName);
+
+  // Explicit CLI flags always win
+  if (values.extdata) query.extdata = 1;
+  if (values.tags)    query.tags = 1;
+
+  // --all includes everything
+  if (values.all) {
+    query.extdata   = 1;
+    query.tags      = 1;
+    query.positions = 1;
+  }
+
+  // --expand is for JSON/binary column expansion (e.g. binfile, items, data)
+  if (values.expand) {
+    const expandCols = values.expand.split(',').map(s => s.trim()).filter(Boolean);
+    for (const col of expandCols) query[col] = 1;
+  }
+
+  if (Object.keys(query).length > 0) {
+    params.query = query;
+  }
+
+  // ── Call API ───────────────────────────────────────────────────────────────
+  const record = await callApi(clientState, res.get, params, {
+    notFoundMessage: `${resourceName} #${id} not found.`
+  });
+
+  if (!record) {
+    fail(`${resourceName} #${id} not found.`);
+  }
+
+  // ── Determine display fields ───────────────────────────────────────────────
+  const fieldConfig = values.all ? undefined : getGetFields(resName, values.fields);
+  const fields = fieldConfig?.keys;
+  const fieldLabels = fieldConfig?.labels ?? {};
+
+  const mode = outputMode(values);
+
+  if (mode === 'json') {
+    printJson(record);
+  } else if (mode === 'yaml') {
+    printYaml(record);
+  } else {
+    const cfg = loadConfig();
+    const dateFormat = cfg.dateFormat ?? 'YYYY-MM-DD';
+    const displayKeys = fields ?? Object.keys(record);
+    const formatters = buildDateFormatters(displayKeys, dateFormat);
+    printRecord(record, displayKeys, fieldLabels, formatters);
+  }
+}

package/commands/list.mjs

@@ -0,0 +1,162 @@
+/**
+ * zeyos list <resource>
+ *
+ * Query a collection of records.
+ *
+ * Options:
+ *   --fields <list>        Field selection (comma-separated or JSON object)
+ *   --filter <json>        JSON filter object  e.g. '{"status":1}'
+ *   --sort <field>         Sort field, prefix with - for descending  e.g. '-lastmodified'
+ *   --limit <n>            Max records to fetch  (default: 50)
+ *   --offset <n>           Skip first N records  (default: 0)
+ *   --extdata              Include extended data fields
+ *   --expand <list>        Expand JSON/binary columns  e.g. 'binfile'
+ *   --json                 Output as JSON
+ *   --yaml                 Output as YAML
+ */
+
+import { normalizeListResult }            from '@zeyos/client';
+import { loadConfig }                    from '../lib/config.mjs';
+import { canonicalName }                 from '../lib/resources.mjs';
+import { getListFields }                 from '../lib/resource-config.mjs';
+import { outputMode, printJson, printYaml, printTable, buildDateFormatters, warn, info } from '../lib/output.mjs';
+import {
+  buildCliClient,
+  callApi,
+  fail,
+  parseJsonOption,
+  requireApiMethod,
+  requireResource
+} from '../lib/command.mjs';
+
+export const USAGE = `\
+Usage: zeyos list <resource> [options]
+
+List records of a given resource type.
+
+Arguments:
+  resource            Resource name (e.g. tickets, accounts, tasks)
+
+Options:
+  --fields <list>     Field selection (see formats below)
+  --filter <json>     JSON filter object  e.g. '{"status":1}'
+  --sort <fields>     Sort expression  e.g. '-lastmodified'
+  --limit <n>         Max records (default: 50)
+  --offset <n>        Skip first N records (default: 0)
+  --extdata           Include extended data fields
+  --expand <list>     Expand JSON/binary columns (e.g. binfile, items)
+  --json              Output as JSON
+  --yaml              Output as YAML
+  -h, --help          Show this help
+
+Fields format:
+  Comma-separated:    --fields ID,name,status,duedate
+  JSON object:        --fields '{"Id": "ID", "Name": "name", "City": "contact.city"}'
+  JSON array:         --fields '["ID", "name", "status"]'
+
+Examples:
+  zeyos list tickets
+  zeyos list tickets --filter '{"status":1}' --sort -lastmodified
+  zeyos list tickets --fields ID,name,status --limit 10
+  zeyos list accounts --fields '{"Name": "lastname", "City": "contact.city"}'
+  zeyos list tickets --extdata
+  zeyos list accounts --json
+`;
+
+export async function run(values, positional) {
+  const resourceName = positional[0];
+  const res = requireResource(resourceName, 'zeyos list <resource>');
+
+  const resName = canonicalName(resourceName);
+  const clientState = buildCliClient();
+
+  // ── Resolve field config ──────────────────────────────────────────────────
+  const { apiFields, displayColumns } = getListFields(res, resName, values.fields);
+
+  // ── Build request body ─────────────────────────────────────────────────────
+  const body = {};
+
+  // Pass configured fields to the API for server-side field selection
+  if (apiFields) body.fields = apiFields;
+
+  if (values.filter) {
+    body.filters = parseJsonOption(values.filter, 'filter');
+  }
+
+  if (values.sort) body.sort = values.sort.split(',').map(s => s.trim()).filter(Boolean);
+
+  if (values.limit != null) {
+    const n = parseInt(values.limit, 10);
+    if (isNaN(n)) fail('--limit must be a number.');
+    body.limit = n;
+  } else {
+    body.limit = 50;
+  }
+
+  if (values.offset != null) {
+    const n = parseInt(values.offset, 10);
+    if (isNaN(n)) fail('--offset must be a number.');
+    body.offset = n;
+  }
+
+  // --extdata includes extended data fields in the response
+  if (values.extdata) {
+    body.extdata = 1;
+  }
+
+  // --expand is for JSON/binary column expansion only (e.g. binfile, items, data)
+  if (values.expand) {
+    body.expand = values.expand.split(',').map(s => s.trim()).filter(Boolean);
+  }
+
+  // ── Call API ───────────────────────────────────────────────────────────────
+  const fn = requireApiMethod(clientState, res.list);
+  let records = await callApi(clientState, res.list, body);
+
+  records = normalizeListResult(records).data;
+
+  // ── Output ─────────────────────────────────────────────────────────────────
+  const mode = outputMode(values);
+  const limit  = body.limit ?? 50;
+  const offset = body.offset ?? 0;
+
+  if (mode === 'json') {
+    printJson(records);
+  } else if (mode === 'yaml') {
+    printYaml(records);
+  } else if (records.length === 0) {
+    warn(`No ${resourceName} found.`);
+    return;
+  } else {
+    const cfg = loadConfig();
+    const dateFormat = cfg.dateFormat ?? 'YYYY-MM-DD';
+    const formatters = buildDateFormatters(displayColumns, dateFormat, apiFields);
+    printTable(records, displayColumns, {}, formatters);
+  }
+
+  // ── Pagination / truncation hint ──────────────────────────────────────────
+  // Emitted to stderr in EVERY output mode (including --json), so an agent that
+  // pipes `list … --json` into a counter gets a signal that the default
+  // --limit truncated the result, instead of a silently-wrong total. For a
+  // "how many?" question, `zeyos count <resource>` returns the true total.
+  const from = offset + 1;
+  const to   = offset + records.length;
+
+  if (records.length >= limit) {
+    try {
+      const countBody = { count: true };
+      if (body.filters) countBody.filters = body.filters;
+      const countResult = await fn(countBody);
+      const total = countResult?.count ?? null;
+      if (total !== null && total > records.length) {
+        info(`Showing ${from}–${to} of ${total}  (default --limit ${limit} truncated this — pass --limit, --offset ${to} for the next page, or use \`zeyos count ${resourceName}\` for the total).`);
+      } else if (total !== null) {
+        info(`Showing ${from}–${to} of ${total}  (--offset ${to} for next page)`);
+      }
+    } catch {
+      // Non-critical — skip pagination info
+    }
+  } else if (offset > 0) {
+    info(`Showing ${from}–${to} of ${to}`);
+  }
+}

package/commands/login.mjs

@@ -0,0 +1,223 @@
+/**
+ * zeyos login
+ *
+ * Starts an OAuth 2.0 authorization-code flow.
+ *
+ * Always prints the authorization URL and callback URL so the user can
+ * copy/paste them.  Simultaneously tries to open the browser and start
+ * a local callback server to catch the redirect automatically.
+ *
+ * Options:
+ *   --base-url <url>     ZeyOS platform URL  (e.g. https://zeyos.cms-it.de/demo)
+ *   --client-id <id>     OAuth client ID
+ *   --secret <secret>    OAuth client secret
+ *   --scope <scope>      OAuth scope (default: all)
+ *   --port <port>        Local callback server port (default: 9005)
+ *   --global             Save credentials to ~/.config/zeyos/credentials.json
+ *   --force              Re-authenticate even if already logged in
+ *   --manual             Skip browser auto-open, prompt for code directly
+ */
+
+import { createInterface }                from 'node:readline';
+import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
+import { saveConfig, loadConfig }         from '../lib/config.mjs';
+import { waitForCallback, callbackUri, BrowserUnavailableError } from '../lib/login-server.mjs';
+import { success, error, info, warn }     from '../lib/output.mjs';
+
+const DEFAULT_CALLBACK_PORT = 9005;
+
+export const USAGE = `\
+Usage: zeyos login [options]
+
+Authenticate with a ZeyOS instance.
+
+Options:
+  --base-url <url>    ZeyOS platform URL  (prompted if missing)
+  --client-id <id>    OAuth client ID     (prompted if missing)
+  --secret <secret>   OAuth client secret (prompted if missing)
+  --scope <scope>     OAuth scope  (default: all)
+  --port <port>       Local callback server port  (default: 9005)
+  --global            Store credentials globally (~/.config/zeyos/credentials.json)
+  --force             Re-authenticate even if already logged in
+  --clean             Discard saved config and re-enter all parameters
+  --manual            Skip auto-browser, prompt for code paste
+  -h, --help          Show this help
+`;
+
+export async function run(values) {
+  const scope = values.global ? 'global' : 'local';
+  const port  = values.port ? Number(values.port) : DEFAULT_CALLBACK_PORT;
+  const redirectUri = callbackUri(port);
+
+  // ── Resolve connection params ──────────────────────────────────────────────
+  const existing = values.clean ? {} : loadConfig();
+  if (values.clean) values.force = true;
+
+  let baseUrl      = values['base-url']    ?? existing.baseUrl;
+  let clientId     = values['client-id']   ?? existing.clientId;
+  let clientSecret = values['secret']      ?? existing.clientSecret;
+
+  // Prompt interactively for any missing values
+  if (!baseUrl)      baseUrl      = await _prompt('ZeyOS platform URL');
+
+  // Before asking for the application ID/secret, show the callback URL so the
+  // user can register it as the redirect URI of their ZeyOS OAuth application
+  // (the ID/secret only exist once that app has been created).
+  if (!clientId || !clientSecret) {
+    console.error('');
+    info('Add this callback URL as the redirect URI of your ZeyOS OAuth app:');
+    console.error(`    ${redirectUri}`);
+    console.error('');
+  }
+
+  if (!clientId)     clientId     = await _prompt('Application ID');
+  if (!clientSecret) clientSecret = await _promptSecret('Application secret');
+
+  if (!baseUrl || !clientId || !clientSecret) {
+    error('ZeyOS URL, application ID and secret are all required.');
+    process.exit(1);
+  }
+
+  // Save connection params immediately so they are available on retries
+  saveConfig({ baseUrl, clientId, clientSecret }, scope);
+
+  // ── Check if already authenticated ────────────────────────────────────────
+  if (existing.accessToken && !values.force) {
+    warn('Already logged in.  Use --force to re-authenticate.');
+    return;
+  }
+
+  // ── Build a temporary client (no token yet) ────────────────────────────────
+  const tokenStore = new MemoryTokenStore();
+  const client = createZeyosClient({
+    platform: baseUrl,
+    auth: {
+      mode: 'oauth',
+      oauth: { clientId, clientSecret, tokenStore, autoRefresh: false },
+    },
+  });
+
+  // Generate random state for CSRF protection
+  const state = _randomHex(32);
+
+  const authUrl = client.oauth2.buildAuthorizationUrl({
+    redirectUri,
+    state,
+    scope: values.scope,
+  });
+
+  // ── Always show URLs ───────────────────────────────────────────────────────
+  console.error('');
+  info('OAuth 2.0 Authorization Code Flow');
+  console.error('');
+  console.error('  Callback URL (redirect URI):');
+  console.error(`    ${redirectUri}`);
+  console.error('');
+  console.error('  Authorization URL:');
+  console.error(`    ${authUrl}`);
+  console.error('');
+
+  // ── Get the authorization code ─────────────────────────────────────────────
+  let code;
+
+  if (values.manual) {
+    // Skip browser, prompt directly
+    code = await _promptCode();
+  } else {
+    // Try browser + callback server; fall back to manual on any failure
+    code = await _browserFlowWithFallback(authUrl, port, state);
+  }
+
+  if (!code) {
+    error('No authorization code provided.');
+    process.exit(1);
+  }
+
+  // ── Exchange code for tokens ───────────────────────────────────────────────
+  try {
+    info('Exchanging authorization code for tokens…');
+    const tokenSet = await client.oauth2.exchangeAuthorizationCode({ code, redirectUri });
+
+    saveConfig({
+      baseUrl,
+      clientId,
+      clientSecret,
+      accessToken:           tokenSet.accessToken,
+      refreshToken:          tokenSet.refreshToken          ?? undefined,
+      expiresAt:             tokenSet.expiresAt             ?? undefined,
+      refreshTokenExpiresAt: tokenSet.refreshTokenExpiresAt ?? undefined,
+    }, scope);
+
+    success('Logged in successfully.');
+  } catch (err) {
+    error(`Token exchange failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Try the browser + callback server flow.
+ * On any failure, fall back to prompting the user for the code.
+ */
+async function _browserFlowWithFallback(authUrl, port, state) {
+  try {
+    info('Starting local callback server and opening browser…');
+    const code = await waitForCallback(authUrl, port, state);
+    return code;
+  } catch (err) {
+    if (err instanceof BrowserUnavailableError) {
+      warn('Could not open browser automatically.');
+    } else {
+      warn(`Callback server error: ${err.message}`);
+    }
+    console.error('');
+    console.error('  Paste the authorization code from the browser redirect URL.');
+    console.error('  (The URL looks like:  …/callback?code=XXXXXXXX&state=…)');
+    console.error('');
+    return _promptCode();
+  }
+}
+
+function _prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise(resolve => {
+    rl.question(`${question}: `, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function _promptSecret(question) {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    return _prompt(question);
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  const originalWrite = rl._writeToOutput.bind(rl);
+  rl._writeToOutput = (value) => {
+    if (String(value).includes(question) || value === '\n' || value === '\r\n') {
+      originalWrite(value);
+    }
+  };
+
+  return new Promise(resolve => {
+    rl.question(`${question}: `, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function _promptCode() {
+  return _prompt('Paste the authorization code');
+}
+
+function _randomHex(length) {
+  return Array.from(
+    { length },
+    () => Math.floor(Math.random() * 256).toString(16).padStart(2, '0')
+  ).join('');
+}

package/commands/logout.mjs

@@ -0,0 +1,63 @@
+/**
+ * zeyos logout
+ *
+ * Revokes the current access token (best-effort) and removes stored tokens
+ * from the credential file.  Connection params (baseUrl, clientId, clientSecret)
+ * are kept so a subsequent `zeyos login` works without re-entering them.
+ *
+ * Options:
+ *   --global    Clear the global credentials file
+ */
+
+import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
+import { loadConfig, clearTokens }             from '../lib/config.mjs';
+import { success, warn, info }                 from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos logout [options]
+
+Revoke the current session and clear stored tokens.
+
+Options:
+  --global    Target the global credentials file
+  -h, --help  Show this help
+`;
+
+export async function run(values) {
+  const scope  = values.global ? 'global' : 'local';
+  const config = loadConfig();
+
+  if (!config.accessToken) {
+    warn('Not currently logged in.');
+    return;
+  }
+
+  // Best-effort token revocation
+  if (config.baseUrl && config.clientId && config.clientSecret) {
+    try {
+      const tokenStore = new MemoryTokenStore({
+        accessToken:  config.accessToken,
+        refreshToken: config.refreshToken,
+      });
+      const client = createZeyosClient({
+        platform: config.baseUrl,
+        auth: {
+          mode: 'oauth',
+          oauth: {
+            clientId:     config.clientId,
+            clientSecret: config.clientSecret,
+            tokenStore,
+            autoRefresh:  false,
+          },
+        },
+      });
+      info('Revoking token…');
+      await client.oauth2.revokeToken({ token: config.accessToken });
+    } catch {
+      // Revocation failure is non-fatal — we still clear local tokens
+    }
+  }
+
+  clearTokens(scope);
+  success('Logged out.');
+}

package/commands/resources.mjs

@@ -0,0 +1,49 @@
+/**
+ * zeyos resources
+ *
+ * List all resource types known to the CLI.
+ */
+
+import { listResources, resolveResource } from '../lib/resources.mjs';
+import { colors as c, outputMode, printJson, printYaml } from '../lib/output.mjs';
+
+export const USAGE = `\
+Usage: zeyos resources [options]
+
+List all resource types available for use with list/get/create/update/delete.
+
+Options:
+  --json              Output as JSON
+  --yaml              Output as YAML
+  -h, --help          Show this help
+`;
+
+export function run(values) {
+  const resources = listResources().map((name) => {
+    const res = resolveResource(name);
+    const operations = ['list', 'get', 'create', 'update', 'delete']
+      .filter(op => res[op]);
+
+    return { name, operations };
+  });
+
+  const mode = outputMode(values);
+  if (mode === 'json') {
+    printJson(resources);
+    return;
+  }
+  if (mode === 'yaml') {
+    printYaml(resources);
+    return;
+  }
+
+  process.stdout.write('\n');
+  process.stdout.write(`  ${c.bold('RESOURCE')}          ${c.bold('OPERATIONS')}\n`);
+  process.stdout.write(`  ${'─'.repeat(16)}  ${'─'.repeat(32)}\n`);
+
+  for (const resource of resources) {
+    process.stdout.write(`  ${resource.name.padEnd(16)}  ${c.dim(resource.operations.join(', '))}\n`);
+  }
+
+  process.stdout.write('\n');
+}