@zeyos/cli 0.1.1

package/lib/client.mjs

@@ -0,0 +1,69 @@
+/**
+ * Create a configured ZeyOS client from the loaded config.
+ * Also provides a helper that persists refreshed tokens back to the config file.
+ */
+import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
+import { loadConfigWithSource, saveConfig, requireConfig } from './config.mjs';
+
+/** @typedef {import('./types.mjs').CliConfig} CliConfig */
+
+/**
+ * Build a ready-to-use ZeyOS API client.
+ * Throws a friendly error if required config keys are missing.
+ *
+ * @param {CliConfig} [overrides]  Extra config values (e.g. from CLI flags)
+ * @returns {{ client: ReturnType<typeof createZeyosClient>, config: CliConfig, tokenStore: MemoryTokenStore, configSource: 'local'|'global'|null }}
+ */
+export function buildClient(overrides = {}) {
+  const loaded = loadConfigWithSource();
+  const config = { ...loaded.config, ...overrides };
+  requireConfig(['baseUrl', 'clientId', 'clientSecret', 'accessToken'], config);
+
+  const tokenStore = new MemoryTokenStore({
+    accessToken:           config.accessToken,
+    refreshToken:          config.refreshToken,
+    expiresAt:             config.expiresAt,
+    refreshTokenExpiresAt: config.refreshTokenExpiresAt,
+  });
+
+  const client = createZeyosClient({
+    platform: config.baseUrl,
+    auth: {
+      mode: 'oauth',
+      oauth: {
+        clientId:     config.clientId,
+        clientSecret: config.clientSecret,
+        tokenStore,
+        autoRefresh:  true,
+      },
+    },
+  });
+
+  return { client, config, tokenStore, configSource: loaded.source };
+}
+
+/**
+ * Persist any refreshed tokens back to the credential store.
+ * Call this after API operations to keep tokens up-to-date.
+ *
+ * @param {MemoryTokenStore} tokenStore
+ * @param {'local'|'global'|null} scope
+ */
+export async function syncTokens(tokenStore, scope = 'local') {
+  if (!scope) {
+    return;
+  }
+  try {
+    const ts = await tokenStore.get();
+    if (ts?.accessToken) {
+      saveConfig({
+        accessToken:           ts.accessToken,
+        refreshToken:          ts.refreshToken,
+        expiresAt:             ts.expiresAt,
+        refreshTokenExpiresAt: ts.refreshTokenExpiresAt,
+      }, scope);
+    }
+  } catch {
+    // non-critical
+  }
+}

package/lib/command.mjs

@@ -0,0 +1,148 @@
+import { buildClient, syncTokens } from './client.mjs';
+import { collectFieldFlags } from './flags.mjs';
+import { resolveResource } from './resources.mjs';
+import { error, info, warn } from './output.mjs';
+
+export function fail(message) {
+  error(message);
+  process.exit(1);
+}
+
+export function requireResource(resourceName, usage, capability, unsupportedAction) {
+  if (!resourceName) {
+    fail(`Missing resource name.  Usage: ${usage}`);
+  }
+
+  const resource = resolveResource(resourceName);
+  if (!resource) {
+    fail(`Unknown resource: "${resourceName}".  Run 'zeyos resources' to see available types.`);
+  }
+
+  if (capability && !resource[capability]) {
+    fail(`Resource "${resourceName}" does not support ${unsupportedAction}.`);
+  }
+
+  return resource;
+}
+
+export function requireRecordId(id, usage) {
+  if (!id) {
+    fail(`Missing record ID.  Usage: ${usage}`);
+  }
+}
+
+export function buildCliClient() {
+  try {
+    return buildClient();
+  } catch (err) {
+    fail(err.message);
+  }
+}
+
+export function parseJsonOption(value, flagName) {
+  if (!value) return undefined;
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    fail(`--${flagName} must be valid JSON.  Got: ${value}`);
+  }
+}
+
+/** Cheap structural check: does this string look like an intended JSON object? */
+function looksLikeJsonObject(value) {
+  return typeof value === 'string' && value.trim().startsWith('{');
+}
+
+/**
+ * Parse a string as a JSON object.
+ *
+ * @param {string} [value]
+ * @returns {Record<string, unknown> | undefined} the object, or `undefined` if
+ *   the value is absent, malformed, or not a plain (non-array) object.
+ */
+function tryParseJsonObject(value) {
+  if (!looksLikeJsonObject(value)) return undefined;
+  try {
+    const parsed = JSON.parse(value);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    // not valid JSON — fall through
+  }
+  return undefined;
+}
+
+/**
+ * Build a record payload for `create`/`update` from `--data`, individual
+ * `--<field>` flags, or — as a fallback — a JSON object passed positionally.
+ *
+ * Coding agents frequently run `zeyos create tickets '{"name":"x"}'`, passing
+ * the body positionally (often alongside the `--json` output flag). When no
+ * `--data`/`--<field>` values were given and that positional argument parses as
+ * a JSON object, adopt it as the payload instead of failing. If it only *looks*
+ * like JSON (e.g. malformed), point the caller at `--data` explicitly rather
+ * than emitting the generic "No fields provided" error.
+ *
+ * @param {Record<string, string|boolean>} values - parsed CLI flag values
+ * @param {string} [positionalData] - candidate positional JSON body
+ * @returns {Record<string, unknown>}
+ */
+export function buildRecordPayload(values, positionalData) {
+  const parsed = parseJsonOption(values.data, 'data');
+  const data = parsed === undefined ? {} : parsed;
+
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    fail(`--data must be a JSON object.  Got: ${values.data}`);
+  }
+
+  Object.assign(data, collectFieldFlags(values));
+
+  if (Object.keys(data).length > 0) {
+    // Explicit --data / --<field> values win; surface an ignored positional
+    // JSON body so it isn't silently dropped.
+    if (looksLikeJsonObject(positionalData)) {
+      warn('Ignoring positional JSON argument; using --data / --<field> values instead.');
+    }
+    return data;
+  }
+
+  // No --data and no --<field> flags. A JSON object passed positionally is a
+  // common agent mistake — adopt it rather than rejecting the command.
+  if (looksLikeJsonObject(positionalData)) {
+    const positionalObject = tryParseJsonObject(positionalData);
+    if (positionalObject && Object.keys(positionalObject).length > 0) {
+      info("Treating positional JSON argument as --data.  Tip: pass it as --data '<json>'.");
+      return positionalObject;
+    }
+    if (!positionalObject) {
+      fail("It looks like you passed a malformed JSON object positionally; use --data '<json>' with valid JSON.");
+    }
+    // Parsed to an empty object — genuinely no fields.
+  }
+
+  fail('No fields provided.  Use --data or individual --<field> flags.');
+}
+
+export function requireApiMethod(clientState, operationId) {
+  const fn = clientState.client.api[operationId];
+  if (typeof fn !== 'function') {
+    fail(`Operation "${operationId}" is not available on this client.`);
+  }
+  return fn;
+}
+
+export async function callApi(clientState, operationId, input, options = {}) {
+  const fn = requireApiMethod(clientState, operationId);
+  try {
+    const result = await fn(input);
+    await syncTokens(clientState.tokenStore, clientState.configSource);
+    return result;
+  } catch (err) {
+    if (err.status === 404 && options.notFoundMessage) {
+      fail(options.notFoundMessage);
+    }
+    fail(`${options.errorPrefix ?? 'API error'}: ${err.message}`);
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,164 @@
+/**
+ * Credential configuration — cascade:
+ *   1. Environment variables  (ZEYOS_BASE_URL, ZEYOS_TOKEN, …)
+ *   2. .zeyos/auth.json       (walk up from CWD, like .gitconfig)
+ *   3. ~/.config/zeyos/credentials.json
+ *
+ * The auth file stores connection params AND tokens.
+ * Add .zeyos/auth.json to .gitignore.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+/** @typedef {import('./types.mjs').CliConfig} CliConfig */
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const LOCAL_DIR   = '.zeyos';
+const LOCAL_FILE  = 'auth.json';
+const GLOBAL_DIR  = join(homedir(), '.config', 'zeyos');
+const GLOBAL_FILE = join(GLOBAL_DIR, 'credentials.json');
+
+// ── Load ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Load the full config object using the cascade.
+ * Returns a merged object; env vars always win over file values.
+ */
+export function loadConfig() {
+  return loadConfigWithSource().config;
+}
+
+/**
+ * Load config and identify the credential file scope that should receive
+ * refreshed tokens. Local config overrides global config field-by-field, so a
+ * partial local file cannot shadow global connection parameters.
+ */
+export function loadConfigWithSource() {
+  const localPath = _findLocalPath();
+  const globalFile = _readGlobal();
+  const localFile = localPath ? _readJson(localPath) : {};
+  const env = _fromEnv();
+
+  return {
+    config: { ...globalFile, ...localFile, ...env },
+    source: localPath ? 'local' : (existsSync(GLOBAL_FILE) ? 'global' : null)
+  };
+}
+
+/**
+ * Require specific keys to be present; throws a human-friendly error if not.
+ * @param {string[]} keys
+ * @param {CliConfig} config
+ */
+export function requireConfig(keys, config) {
+  const missing = keys.filter(k => config[k] == null || config[k] === '');
+  if (missing.length === 0) return;
+
+  const hints = {
+    baseUrl:      'Set ZEYOS_BASE_URL or run: zeyos login --base-url <url>',
+    clientId:     'Set ZEYOS_CLIENT_ID or run: zeyos login --client-id <id>',
+    clientSecret: 'Set ZEYOS_CLIENT_SECRET or run: zeyos login --secret <secret>',
+    accessToken:  'Run: zeyos login',
+  };
+
+  const messages = missing.map(k => `  • ${k}: ${hints[k] ?? 'not set'}`);
+  throw new Error(`Missing required configuration:\n${messages.join('\n')}`);
+}
+
+// ── Save ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Save (merge) config values into the nearest .zeyos/auth.json found while
+ * walking up, or create one in the current directory.  Falls back to the
+ * global file when `scope === 'global'`.
+ *
+ * @param {CliConfig} updates
+ * @param {'local'|'global'} scope
+ */
+export function saveConfig(updates, scope = 'local') {
+  if (scope === 'global') {
+    _writeGlobal({ ..._readGlobal(), ...updates });
+    return;
+  }
+  const existing = _findLocalPath();
+  const path = existing ?? join(process.cwd(), LOCAL_DIR, LOCAL_FILE);
+  const current = existing ? _readJson(path) : {};
+  _writeJson(path, { ...current, ...updates });
+}
+
+/** Remove the stored tokens (leave connection params intact). */
+export function clearTokens(scope = 'local') {
+  const strip = o => {
+    const { accessToken, refreshToken, expiresAt, refreshTokenExpiresAt, ...rest } = o;
+    return rest;
+  };
+  if (scope === 'global') {
+    _writeGlobal(strip(_readGlobal()));
+    return;
+  }
+  const path = _findLocalPath();
+  if (path) _writeJson(path, strip(_readJson(path)));
+}
+
+/** Return the path of the active local .zeyos/auth.json (if any). */
+export function localConfigPath() {
+  return _findLocalPath();
+}
+
+/** Return the global credentials file path. */
+export function globalConfigPath() {
+  return GLOBAL_FILE;
+}
+
+// ── Internals ────────────────────────────────────────────────────────────────
+
+function _fromEnv() {
+  const e = process.env;
+  const out = {};
+  if (e.ZEYOS_BASE_URL)              out.baseUrl             = e.ZEYOS_BASE_URL;
+  if (e.ZEYOS_INSTANCE)              out.instance            = e.ZEYOS_INSTANCE;
+  if (e.ZEYOS_CLIENT_ID)             out.clientId            = e.ZEYOS_CLIENT_ID;
+  if (e.ZEYOS_CLIENT_SECRET)         out.clientSecret        = e.ZEYOS_CLIENT_SECRET;
+  if (e.ZEYOS_TOKEN)                 out.accessToken         = e.ZEYOS_TOKEN;
+  if (e.ZEYOS_REFRESH_TOKEN)         out.refreshToken        = e.ZEYOS_REFRESH_TOKEN;
+  return out;
+}
+
+function _findLocalPath() {
+  let dir = process.cwd();
+  for (let i = 0; i < 20; i++) {
+    const candidate = join(dir, LOCAL_DIR, LOCAL_FILE);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function _readGlobal() {
+  return existsSync(GLOBAL_FILE) ? _readJson(GLOBAL_FILE) : {};
+}
+
+function _writeGlobal(data) {
+  mkdirSync(GLOBAL_DIR, { recursive: true });
+  _writeJson(GLOBAL_FILE, data);
+}
+
+function _readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      return {};
+    }
+    throw new Error(`Failed to read ${path}: ${err.message || err}`);
+  }
+}
+
+function _writeJson(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+}

package/lib/flags.mjs

@@ -0,0 +1,44 @@
+/**
+ * Helpers for turning loose `--<field> <value>` CLI flags into a record payload
+ * for the create/update commands.
+ */
+
+// Global CLI flags that are never record fields. Any other --flag on
+// create/update is treated as a field on the record being written.
+const RESERVED_FLAGS = new Set([
+  'data', 'json', 'yaml', 'help', 'h',
+  'no-color', 'force', 'fields', 'filter', 'sort',
+  'limit', 'offset', 'expand', 'base-url', 'client-id',
+  'secret', 'scope', 'global', 'port', 'manual', 'show-token',
+  'extdata', 'tags', 'all', 'clean',
+]);
+
+/**
+ * Coerce a raw string flag value to its natural JS type
+ * (boolean, null, or number) where it unambiguously looks like one.
+ *
+ * @param {string|boolean} value
+ * @returns {string|number|boolean|null}
+ */
+function coerceFlagValue(value) {
+  if (value === 'true')  return true;
+  if (value === 'false') return false;
+  if (value === 'null')  return null;
+  if (typeof value === 'string' && value !== '' && !isNaN(Number(value))) return Number(value);
+  return value;
+}
+
+/**
+ * Collect non-reserved `--<field> <value>` flags into a record-field object,
+ * coercing each value to its natural JS type.
+ *
+ * @param {Record<string, string|boolean>} values - parsed CLI flag values
+ * @returns {Record<string, string|number|boolean|null>}
+ */
+export function collectFieldFlags(values) {
+  const data = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (!RESERVED_FLAGS.has(key)) data[key] = coerceFlagValue(value);
+  }
+  return data;
+}

package/lib/login-server.mjs

@@ -0,0 +1,149 @@
+/**
+ * Lightweight OAuth callback server.
+ *
+ * Starts a temporary HTTP server on localhost:PORT, opens the authorization
+ * URL in the system browser, waits for the redirect, extracts `?code=`, then
+ * shuts itself down.
+ *
+ * Falls back gracefully when no browser is available (CI, SSH, headless).
+ */
+
+import { createServer } from 'node:http';
+import { exec }         from 'node:child_process';
+
+const DEFAULT_PORT    = 9005;
+const CALLBACK_PATH   = '/callback';
+const TIMEOUT_MS      = 5 * 60 * 1000; // 5 minutes
+
+// ── Browser opener ────────────────────────────────────────────────────────────
+
+/** Open a URL in the system default browser. Returns true if a command was spawned. */
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin' ? `open "${url}"` :
+    process.platform === 'win32'  ? `start "" "${url}"` :
+    /* linux/other */                `xdg-open "${url}"`;
+
+  return new Promise(resolve => {
+    exec(cmd, err => resolve(!err));
+  });
+}
+
+// ── Server ────────────────────────────────────────────────────────────────────
+
+/**
+ * Start a temporary local server, open the browser, and resolve with the
+ * authorization code once ZeyOS redirects back.
+ *
+ * @param {string} authUrl        - Full authorization URL to open
+ * @param {number} [port]         - Local port to listen on
+ * @param {string} [expectedState] - Expected OAuth state param for CSRF validation
+ * @returns {Promise<string>}     - Resolves with the `code` query param
+ */
+export async function waitForCallback(authUrl, port = DEFAULT_PORT, expectedState = undefined) {
+  return new Promise((resolve, reject) => {
+    let server;
+    let timer;
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      try { server?.close(); } catch { /* ignore */ }
+    };
+
+    server = createServer((req, res) => {
+      const u = new URL(req.url, `http://localhost:${port}`);
+
+      // Only handle the callback path; ignore favicon etc.
+      if (u.pathname !== CALLBACK_PATH) {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+
+      const code          = u.searchParams.get('code');
+      const error         = u.searchParams.get('error');
+      const returnedState = u.searchParams.get('state');
+
+      // CSRF check: validate state matches if we sent one
+      if (expectedState && returnedState !== expectedState) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(_html('State mismatch', '<p>OAuth state parameter does not match. This may be a CSRF attack.</p><p>Please try again.</p>', true));
+        cleanup();
+        reject(new Error('OAuth state mismatch — possible CSRF attack. Please retry login.'));
+        return;
+      }
+
+      if (error) {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(_html('Authorization failed', `<p>Error: <strong>${_esc(error)}</strong></p><p>You may close this tab.</p>`, true));
+        cleanup();
+        reject(new Error(`OAuth error: ${error} — ${u.searchParams.get('error_description') ?? ''}`));
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(_html('Bad request', '<p>No authorization code in callback.</p>', true));
+        cleanup();
+        reject(new Error('No authorization code received'));
+        return;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(_html('Authorized', '<p>You are now logged in. You may close this tab.</p>', false));
+      cleanup();
+      resolve(code);
+    });
+
+    server.on('error', err => {
+      cleanup();
+      reject(err);
+    });
+
+    server.listen(port, '127.0.0.1', async () => {
+      // Set a hard timeout so the process doesn't hang forever
+      timer = setTimeout(() => {
+        cleanup();
+        reject(new Error('Login timed out after 5 minutes'));
+      }, TIMEOUT_MS);
+
+      const opened = await openBrowser(authUrl);
+      if (!opened) {
+        // Can't open browser — caller should fall back to manual flow
+        cleanup();
+        reject(new BrowserUnavailableError(authUrl));
+      }
+    });
+  });
+}
+
+/** @returns {string} The redirect URI for this server. */
+export function callbackUri(port = DEFAULT_PORT) {
+  return `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+}
+
+// ── Custom error type ─────────────────────────────────────────────────────────
+
+export class BrowserUnavailableError extends Error {
+  constructor(authUrl) {
+    super('Could not open browser');
+    this.name = 'BrowserUnavailableError';
+    this.authUrl = authUrl;
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _esc(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function _html(title, body, isError) {
+  const color = isError ? '#c0392b' : '#27ae60';
+  return `<!DOCTYPE html><html><head><meta charset="utf-8">
+<title>${_esc(title)} — ZeyOS</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#f5f5f5}
+.box{background:#fff;border-radius:8px;padding:2rem 3rem;box-shadow:0 2px 8px rgba(0,0,0,.12);text-align:center;max-width:400px}
+h1{color:${color};margin-bottom:.5rem}p{color:#555;line-height:1.5}</style>
+</head><body><div class="box"><h1>${_esc(title)}</h1>${body}</div></body></html>`;
+}