@zeyos/cli 0.1.1

package/lib/output.mjs

@@ -0,0 +1,284 @@
+/**
+ * Output formatters: pretty table, JSON, YAML.
+ * ANSI colors are stripped when stdout is not a TTY or --no-color is set.
+ *
+ * All public functions write to stdout; errors write to stderr.
+ */
+
+/** @typedef {import('./types.mjs').JsonValue} JsonValue */
+/** @typedef {import('./types.mjs').JsonObject} JsonObject */
+/** @typedef {import('./types.mjs').ValueFormatter} ValueFormatter */
+
+// ── Colors ────────────────────────────────────────────────────────────────────
+
+const USE_COLOR = process.stdout.isTTY && !process.argv.includes('--no-color') && !process.env.NO_COLOR;
+
+const c = {
+  bold:   s => USE_COLOR ? `\x1b[1m${s}\x1b[0m`  : s,
+  dim:    s => USE_COLOR ? `\x1b[2m${s}\x1b[0m`  : s,
+  green:  s => USE_COLOR ? `\x1b[32m${s}\x1b[0m` : s,
+  red:    s => USE_COLOR ? `\x1b[31m${s}\x1b[0m` : s,
+  yellow: s => USE_COLOR ? `\x1b[33m${s}\x1b[0m` : s,
+  cyan:   s => USE_COLOR ? `\x1b[36m${s}\x1b[0m` : s,
+};
+
+export { c as colors };
+
+// ── Output mode ───────────────────────────────────────────────────────────────
+
+/** Determine output mode from parsed CLI values. */
+export function outputMode(values) {
+  if (values.json) return 'json';
+  if (values.yaml) return 'yaml';
+  return 'table';
+}
+
+// ── JSON ──────────────────────────────────────────────────────────────────────
+
+export function printJson(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+// ── YAML ──────────────────────────────────────────────────────────────────────
+
+export function printYaml(data) {
+  process.stdout.write(toYaml(data).replace(/^\n/, '') + '\n');
+}
+
+function toYaml(value, indent = 0) {
+  const pad = '  '.repeat(indent);
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'null';
+  if (typeof value === 'string') {
+    if (value === '') return '""';
+    if (value.includes('\n')) {
+      const lines = value.split('\n').map(l => `${pad}  ${l}`);
+      return `|\n${lines.join('\n')}`;
+    }
+    // Quote strings that contain YAML-special characters, leading/trailing whitespace,
+    // look like numbers (would be parsed as number by YAML loaders), or are YAML 1.1
+    // boolean / null keywords (true, false, null, yes, no, on, off and their variants).
+    if (
+      /[:#\[\]{}&*!,|>'"@`%]/.test(value) ||
+      /^\s|\s$/.test(value) ||
+      /^-?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(value) ||
+      /^(true|false|null|yes|no|on|off|y|n)$/i.test(value)
+    ) {
+      return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    return value.map(item => {
+      const rendered = toYaml(item, indent + 1);
+      if (typeof item === 'object' && item !== null) {
+        // First key on same line as dash
+        const inner = rendered.trimStart();
+        return `\n${pad}- ${inner}`;
+      }
+      return `\n${pad}- ${rendered}`;
+    }).join('');
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    return entries.map(([k, v]) => {
+      if (typeof v === 'object' && v !== null && !Array.isArray(v) && Object.keys(v).length > 0) {
+        return `\n${pad}${k}:\n${pad}  ${toYaml(v, indent + 1).trimStart()}`;
+      }
+      const rendered = toYaml(v, indent + 1);
+      if (typeof v === 'object' && v !== null) {
+        return `\n${pad}${k}:${rendered}`;
+      }
+      return `\n${pad}${k}: ${rendered}`;
+    }).join('');
+  }
+  return String(value);
+}
+
+// ── Table ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Print a list of objects as a plain-text table.
+ *
+ * @param {JsonObject[]} rows
+ * @param {string[]} columns  - ordered list of keys to display
+ * @param {Record<string,string>} [labels] - optional column header overrides
+ * @param {Record<string,ValueFormatter>} [formatters] - optional per-key formatters
+ */
+export function printTable(rows, columns, labels = {}, formatters = {}) {
+  if (rows.length === 0) {
+    process.stdout.write(c.dim('  (no records)\n'));
+    return;
+  }
+
+  const headers = columns.map(k => labels[k] ?? k.toUpperCase());
+
+  const stringify = (key, val, row) => {
+    if (formatters[key]) return String(formatters[key](val, row));
+    if (val === null || val === undefined) return '';
+    if (typeof val === 'object') return JSON.stringify(val);
+    return String(val);
+  };
+
+  const data = rows.map(row => columns.map(k => stringify(k, row[k], row)));
+
+  const widths = columns.map((_, i) =>
+    Math.max(headers[i].length, ...data.map(row => _visibleLength(row[i])))
+  );
+
+  const headerRow = headers.map((h, i) => _pad(c.bold(h), widths[i])).join('  ');
+  const separator = widths.map(w => '─'.repeat(w)).join('  ');
+
+  process.stdout.write('\n');
+  process.stdout.write('  ' + headerRow + '\n');
+  process.stdout.write('  ' + c.dim(separator) + '\n');
+  for (const row of data) {
+    process.stdout.write('  ' + row.map((v, i) => _pad(v, widths[i])).join('  ') + '\n');
+  }
+  process.stdout.write('\n');
+}
+
+/**
+ * Print a single record as a vertical key-value list.
+ *
+ * @param {JsonObject} record
+ * @param {string[]} [keys]  - subset of keys to show (default: all)
+ * @param {Record<string,string>} [labels]
+ * @param {Record<string,ValueFormatter>} [formatters]
+ */
+export function printRecord(record, keys, labels = {}, formatters = {}) {
+  const keyList = keys ?? Object.keys(record);
+  const maxLabel = Math.max(...keyList.map(k => (labels[k] ?? k).length));
+
+  process.stdout.write('\n');
+  for (const key of keyList) {
+    const val = record[key];
+    if (val === undefined) continue;
+
+    const label = _pad(labels[key] ?? key, maxLabel);
+    let display;
+
+    if (formatters[key]) {
+      display = String(formatters[key](val, record));
+    } else if (val === null) {
+      display = c.dim('—');
+    } else if (typeof val === 'object') {
+      display = JSON.stringify(val);
+    } else {
+      display = String(val);
+    }
+
+    // Handle multi-line display values: indent continuation lines
+    // so they align with the first line (after the label column).
+    if (display.includes('\n')) {
+      const indent = ' '.repeat(maxLabel + 4); // "  label  " padding
+      const lines = display.split('\n');
+      process.stdout.write(`  ${c.dim(label)}  ${lines[0]}\n`);
+      for (let li = 1; li < lines.length; li++) {
+        process.stdout.write(`${indent}${lines[li]}\n`);
+      }
+    } else {
+      process.stdout.write(`  ${c.dim(label)}  ${display}\n`);
+    }
+  }
+  process.stdout.write('\n');
+}
+
+// ── Messages ──────────────────────────────────────────────────────────────────
+
+export function success(msg) {
+  process.stderr.write(c.green('✓') + ' ' + msg + '\n');
+}
+
+export function warn(msg) {
+  process.stderr.write(c.yellow('⚠') + ' ' + msg + '\n');
+}
+
+export function error(msg) {
+  process.stderr.write(c.red('✗') + ' ' + msg + '\n');
+}
+
+export function info(msg) {
+  process.stderr.write(c.dim('·') + ' ' + msg + '\n');
+}
+
+// ── Date formatting ──────────────────────────────────────────────────────────
+
+/**
+ * Format a Unix timestamp (seconds) to a date string.
+ * Supports tokens: YYYY, MM, DD, HH, mm, ss.
+ * Returns '' for null/undefined/0 values.
+ *
+ * @param {number|string|null|undefined} timestamp - Unix timestamp in seconds
+ * @param {string} format - e.g. 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm'
+ * @returns {string}
+ */
+export function formatDate(timestamp, format = 'YYYY-MM-DD') {
+  if (timestamp == null || timestamp === 0 || timestamp === '') return '';
+  const n = Number(timestamp);
+  if (!Number.isFinite(n)) return String(timestamp);
+  const d = new Date(n * 1000);
+  if (isNaN(d.getTime())) return String(timestamp);
+  return format
+    .replace('YYYY', String(d.getFullYear()))
+    .replace('MM',   String(d.getMonth() + 1).padStart(2, '0'))
+    .replace('DD',   String(d.getDate()).padStart(2, '0'))
+    .replace('HH',   String(d.getHours()).padStart(2, '0'))
+    .replace('mm',   String(d.getMinutes()).padStart(2, '0'))
+    .replace('ss',   String(d.getSeconds()).padStart(2, '0'));
+}
+
+/** Well-known date field names in ZeyOS. */
+const DATE_FIELDS = new Set([
+  'duedate', 'lastmodified', 'creationdate', 'created',
+  'date', 'startdate', 'enddate',
+]);
+
+/**
+ * Check whether a field name represents a date.
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isDateField(name) {
+  const lower = name.toLowerCase();
+  return DATE_FIELDS.has(lower) || lower.endsWith('date') || lower.endsWith('modified');
+}
+
+/**
+ * Build a formatters object for known date fields.
+ * For list views where alias names differ from API paths, pass the
+ * aliasToPath map so date detection works on the API path.
+ *
+ * @param {string[]} columns - display column keys
+ * @param {string}   dateFormat - format string (default 'YYYY-MM-DD')
+ * @param {Record<string,string>} [aliasToPath] - alias → API field path
+ * @returns {Record<string, ValueFormatter>}
+ */
+export function buildDateFormatters(columns, dateFormat = 'YYYY-MM-DD', aliasToPath) {
+  const formatters = {};
+  for (const col of columns) {
+    const fieldPath = aliasToPath?.[col] ?? col;
+    const leaf = fieldPath.includes('.') ? fieldPath.split('.').pop() : fieldPath;
+    if (isDateField(leaf)) {
+      formatters[col] = (val) => formatDate(val, dateFormat);
+    }
+  }
+  return formatters;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** String length ignoring ANSI escape codes. */
+function _visibleLength(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+/** Pad a string to a visible width, accounting for ANSI escape codes. */
+function _pad(str, len) {
+  const visible = _visibleLength(str);
+  if (visible >= len) return str;
+  return str + ' '.repeat(len - visible);
+}

package/lib/resource-config.mjs

@@ -0,0 +1,289 @@
+/**
+ * Per-resource field configuration loader.
+ *
+ * Resolves field configs via a cascade (first match wins):
+ *   1. .zeyos/api/<resource>.json   (project-local, walks up from CWD)
+ *   2. ~/.zeyos/api/<resource>.json  (global user overrides)
+ *   3. cli/config/<resource>.json    (shipped defaults)
+ *
+ * A user override file replaces the shipped config for that resource
+ * entirely (no field-by-field merge).
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { error } from './output.mjs';
+
+/** @typedef {import('./types.mjs').ResourceDef} ResourceDef */
+/** @typedef {import('./types.mjs').ResourceFieldConfig} ResourceFieldConfig */
+/** @typedef {import('./types.mjs').ListFieldSelection} ListFieldSelection */
+/** @typedef {import('./types.mjs').GetFieldSelection} GetFieldSelection */
+/** @typedef {import('./types.mjs').JsonValue} JsonValue */
+
+// ── Paths ────────────────────────────────────────────────────────────────────
+
+const __dir       = dirname(fileURLToPath(import.meta.url));
+const SHIPPED_DIR = join(__dir, '..', 'config');
+const GLOBAL_DIR  = join(homedir(), '.zeyos', 'api');
+const LOCAL_NAME  = '.zeyos';
+const LOCAL_SUB   = 'api';
+
+// ── Cache ────────────────────────────────────────────────────────────────────
+
+const _cache = new Map();
+
+// ── Load ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Load the field config for a resource by canonical name.
+ * Returns the parsed JSON object, or null if no config exists.
+ *
+ * @param {string} name - canonical resource name (e.g. "ticket")
+ * @returns {ResourceFieldConfig|null}
+ */
+export function loadResourceConfig(name) {
+  if (_cache.has(name)) return _cache.get(name);
+
+  const config = _resolveConfig(name);
+  _cache.set(name, config);
+  return config;
+}
+
+// ── List fields ──────────────────────────────────────────────────────────────
+
+/**
+ * Get the effective list fields for a resource.
+ *
+ * Priority:
+ *   1. --fields CLI override
+ *   2. Config file list.fields object
+ *   3. Registry res.fields array (display-only default, no API field selection)
+ *
+ * The --fields flag supports three formats:
+ *   - Comma-separated:  "ID,name,status"          → self-aliased object
+ *   - JSON object:      '{"Id":"ID","Name":"name"}'  → aliased object
+ *   - JSON array:       '["ID","name","status"]'     → self-aliased object
+ *
+ * @param {ResourceDef} res - ResourceDef from registry
+ * @param {string}   name      - canonical resource name
+ * @param {string}   [override] - raw --fields flag value
+ * @returns {ListFieldSelection}
+ */
+export function getListFields(res, name, override) {
+  // 1. CLI override
+  if (override) {
+    return _parseFieldsOverride(override);
+  }
+
+  // 2. Config file
+  const config = loadResourceConfig(name);
+  if (config?.list?.fields && typeof config.list.fields === 'object') {
+    const apiFields = _toFieldAliasMap(config.list.fields);
+    const displayColumns = Object.keys(apiFields);
+    return { apiFields, displayColumns };
+  }
+
+  // 3. Registry fallback — display-only (don't send fields to APIs that may not support it)
+  if (res?.fields) {
+    return { apiFields: undefined, displayColumns: [...res.fields] };
+  }
+
+  return { apiFields: undefined, displayColumns: [] };
+}
+
+// ── Get fields ───────────────────────────────────────────────────────────────
+
+/**
+ * Get the effective get/show display fields for a resource.
+ *
+ * Priority:
+ *   1. --fields CLI override
+ *   2. Config file get.fields array
+ *   3. undefined (show all keys — current behavior)
+ *
+ * Returns an object { keys, labels } where:
+ *   - keys: array of API field names to display from the record
+ *   - labels: mapping from API field name → display alias
+ *
+ * When --fields is a JSON object like {"Id": "ID", "Name": "name"},
+ * keys are the values (API paths) and labels map those back to the aliases.
+ *
+ * @param {string}   name       - canonical resource name
+ * @param {string}   [override] - raw --fields flag value
+ * @returns {GetFieldSelection | undefined}
+ */
+export function getGetFields(name, override) {
+  if (override) {
+    const trimmed = override.trim();
+
+    // JSON object: {"Alias": "api.field", ...}
+    if (trimmed.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+          // Keys = alias names, Values = API field paths
+          const keys = Object.values(parsed).map(String);
+          const labels = {};
+          for (const [alias, field] of Object.entries(parsed)) {
+            labels[String(field)] = alias;
+          }
+          return { keys, labels };
+        }
+      } catch {
+        // Fall through
+      }
+    }
+
+    // JSON array: ["field1", "field2"]
+    if (trimmed.startsWith('[')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) return { keys: parsed.map(String), labels: {} };
+      } catch {
+        // Fall through
+      }
+    }
+
+    // Comma-separated: "field1,field2"
+    return { keys: trimmed.split(',').map(s => s.trim()).filter(Boolean), labels: {} };
+  }
+
+  const config = loadResourceConfig(name);
+  if (config?.get?.fields && Array.isArray(config.get.fields)) {
+    return { keys: config.get.fields, labels: {} };
+  }
+
+  return undefined;
+}
+
+// ── Get params ───────────────────────────────────────────────────────────────
+
+/**
+ * Get the default query parameters for GET operations from a resource's
+ * `get.params` config (e.g. `{ extdata: 1, tags: 1 }`). These are sent as URL
+ * query parameters; explicit CLI flags override them on the caller's side.
+ *
+ * @param {string} name - canonical resource name
+ * @returns {Record<string, number|string|boolean>} query parameters for the GET request
+ */
+export function getGetParams(name) {
+  const config = loadResourceConfig(name);
+  if (config?.get?.params && typeof config.get.params === 'object') {
+    return { ...config.get.params };
+  }
+  return {};
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a --fields override string.
+ * Supports: comma-separated, JSON object, JSON array.
+ */
+function _parseFieldsOverride(raw) {
+  const trimmed = raw.trim();
+
+  // JSON object: {"Alias": "path", ...}
+  if (trimmed.startsWith('{')) {
+    try {
+      const obj = JSON.parse(trimmed);
+      if (typeof obj === 'object' && obj !== null && !Array.isArray(obj)) {
+        const apiFields = _toFieldAliasMap(obj);
+        return { apiFields, displayColumns: Object.keys(apiFields) };
+      }
+    } catch (e) {
+      error(`--fields JSON is invalid: ${e.message}\n  Got: ${trimmed}\n  Expected format: '{"Alias": "field.path", ...}'`);
+      process.exit(1);
+    }
+  }
+
+  // JSON array: ["field1", "field2", ...]
+  if (trimmed.startsWith('[')) {
+    try {
+      const arr = JSON.parse(trimmed);
+      if (Array.isArray(arr)) {
+        const paths = arr.map(String);
+        const apiFields = {};
+        for (const p of paths) apiFields[p] = p;
+        return { apiFields, displayColumns: paths };
+      }
+    } catch (e) {
+      error(`--fields JSON is invalid: ${e.message}\n  Got: ${trimmed}\n  Expected format: '["field1", "field2", ...]'`);
+      process.exit(1);
+    }
+  }
+
+  // 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;
+  return { apiFields, displayColumns: paths };
+}
+
+/**
+ * Normalize an alias-to-field-path object into the documented string map shape.
+ *
+ * @param {Record<string, JsonValue>} value
+ * @returns {Record<string,string>}
+ */
+function _toFieldAliasMap(value) {
+  const fields = {};
+  for (const [alias, field] of Object.entries(value)) {
+    fields[String(alias)] = String(field);
+  }
+  return fields;
+}
+
+// ── Internals ────────────────────────────────────────────────────────────────
+
+/**
+ * Walk the config cascade for a resource name.
+ * Returns the first matching config object, or null.
+ *
+ * @returns {ResourceFieldConfig|null}
+ */
+function _resolveConfig(name) {
+  const filename = `${name}.json`;
+
+  // 1. Project-local: walk up from CWD looking for .zeyos/api/<name>.json
+  const localPath = _findLocalConfig(filename);
+  if (localPath) return _readJson(localPath);
+
+  // 2. Global user: ~/.zeyos/api/<name>.json
+  const globalPath = join(GLOBAL_DIR, filename);
+  if (existsSync(globalPath)) return _readJson(globalPath);
+
+  // 3. Shipped defaults: cli/config/<name>.json
+  const shippedPath = join(SHIPPED_DIR, filename);
+  if (existsSync(shippedPath)) return _readJson(shippedPath);
+
+  return null;
+}
+
+/**
+ * Walk up from CWD looking for .zeyos/api/<filename>.
+ * Returns the full path if found, null otherwise.
+ */
+function _findLocalConfig(filename) {
+  let dir = process.cwd();
+  for (let i = 0; i < 20; i++) {
+    const candidate = join(dir, LOCAL_NAME, LOCAL_SUB, filename);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function _readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      return null;
+    }
+    throw new Error(`Failed to read resource config ${path}: ${err.message || err}`);
+  }
+}