@klevar/portal-cli 0.1.0

package/dist/lib/legacy-runner.js

@@ -0,0 +1,820 @@
+#!/usr/bin/env node
+
+/**
+ * Klevar Client Portal CLI — Full admin management from the terminal.
+ * Uses X-API-Key header for authentication.
+ *
+ * Usage:
+ *   node client.js <resource> <action> [id] [--key value ...]
+ *
+ * Resources: clients, projects, tasks, updates, onboarding, dashboard, token
+ *
+ * Config:
+ *   PORTAL_API_KEY  — API key (env var or ~/.klevar/portal.env)
+ *   PORTAL_URL      — API base URL (default: http://localhost:3000)
+ *
+ * To add a new API endpoint:
+ *   1. Add an entry to COMMANDS: 'resource.action': { method, path, body? }
+ *   2. That's it. The CLI router handles arg parsing, path interpolation, and output.
+ */
+
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { COMMANDS } from '../commands/index.js';
+
+// ── Credential Loading ──────────────────────────────────────────
+
+function loadEnvFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  const vars = {};
+  for (const line of readFileSync(filePath, 'utf-8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    vars[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return vars;
+}
+
+const envFile = loadEnvFile(join(homedir(), '.klevar', 'portal.env'));
+let BASE_URL =
+  process.env.PORTAL_API_URL ||
+  process.env.PORTAL_URL ||
+  envFile.PORTAL_API_URL ||
+  envFile.PORTAL_URL ||
+  'http://127.0.0.1:3100';
+let API_KEY = process.env.PORTAL_API_KEY || envFile.PORTAL_API_KEY;
+let PORTAL_TOKEN =
+  process.env.PORTAL_TOKEN ||
+  process.env.PORTAL_PORTAL_TOKEN ||
+  envFile.PORTAL_TOKEN ||
+  envFile.PORTAL_PORTAL_TOKEN;
+
+function requireApiKey() {
+  if (!API_KEY) {
+    console.error('Error: PORTAL_API_KEY is required');
+    console.error('Set it via env var or create ~/.klevar/portal.env');
+    process.exit(2);
+  }
+}
+
+function requirePortalToken() {
+  if (!PORTAL_TOKEN) {
+    console.error('Error: PORTAL_TOKEN is required for portal commands');
+    console.error('Set it via env var, --portal-token, or ~/.klevar/portal.env');
+    process.exit(2);
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+function timeAgo(iso) {
+  const ms = Date.now() - new Date(iso).getTime();
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return 'just now';
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  return `${d}d ago`;
+}
+
+// ── API Client ──────────────────────────────────────────────────
+
+const headers = { 'Content-Type': 'application/json', 'X-API-Key': API_KEY };
+
+function withPortalToken(path) {
+  requirePortalToken();
+  const sep = path.includes('?') ? '&' : '?';
+  return `${path}${sep}token=${encodeURIComponent(PORTAL_TOKEN)}`;
+}
+
+async function api(method, path, body, auth = 'apiKey') {
+  const reqHeaders = {};
+  let requestPath = path;
+  if (auth === 'portal' || auth === 'portalToken') {
+    requestPath = withPortalToken(path);
+  } else if (auth === 'apiKey') {
+    requireApiKey();
+    reqHeaders['X-API-Key'] = API_KEY;
+  }
+  if (body) reqHeaders['Content-Type'] = 'application/json';
+  const res = await fetch(`${BASE_URL}${requestPath}`, {
+    method,
+    headers: reqHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: { message: res.statusText } }));
+    console.error(`Error ${res.status}: ${err.error?.message || 'Unknown error'}`);
+    process.exit(1);
+  }
+
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+async function apiDownload(path, outputPath, auth = 'apiKey') {
+  const headers = { Accept: 'application/pdf, application/json' };
+  let requestPath = path;
+  if (auth === 'portal' || auth === 'portalToken') {
+    requestPath = withPortalToken(path);
+  } else {
+    requireApiKey();
+    headers['X-API-Key'] = API_KEY;
+  }
+  const res = await fetch(`${BASE_URL}${requestPath}`, {
+    method: 'GET',
+    headers,
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: { message: res.statusText } }));
+    console.error(`Error ${res.status}: ${err.error?.message || 'Unknown error'}`);
+    process.exit(1);
+  }
+
+  const contentType = res.headers.get('content-type') || '';
+  if (contentType.includes('application/json')) {
+    const data = await res.json();
+    const url = data.url || data.pdf_url || data.data?.pdf_url || data.data?.url;
+    if (!url) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    if (!outputPath) {
+      console.log(url);
+      return;
+    }
+    await downloadPublicUrl(url, outputPath);
+    return;
+  }
+
+  if (!outputPath) {
+    console.error('Error: --output is required when the API returns PDF bytes');
+    process.exit(1);
+  }
+
+  const bytes = Buffer.from(await res.arrayBuffer());
+  writeFileSync(outputPath, bytes);
+  console.log(`Saved ${bytes.length} bytes to ${outputPath}`);
+}
+
+async function downloadPublicUrl(url, outputPath) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    console.error(`Error ${res.status}: failed to download signed URL`);
+    process.exit(1);
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  writeFileSync(outputPath, bytes);
+  console.log(`Saved ${bytes.length} bytes to ${outputPath}`);
+}
+
+const MIME_MAP = {
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp',
+  '.pdf': 'application/pdf', '.csv': 'text/csv',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.xls': 'application/vnd.ms-excel',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+
+async function apiMultipart(method, path, fields, filePaths) {
+  const formData = new FormData();
+  for (const [key, val] of Object.entries(fields)) {
+    if (val !== undefined) formData.append(key, val);
+  }
+  for (const fp of filePaths) {
+    const { createReadStream } = await import('node:fs');
+    const { basename, extname } = await import('node:path');
+    const name = basename(fp);
+    const ext = extname(fp).toLowerCase();
+    const mime = MIME_MAP[ext] || 'application/octet-stream';
+    const stream = createReadStream(fp);
+    const buf = await streamToBuffer(stream);
+    formData.append('attachments', new File([buf], name, { type: mime }), name);
+  }
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers: { 'X-API-Key': API_KEY },
+    body: formData,
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: { message: res.statusText } }));
+    console.error(`Error ${res.status}: ${err.error?.message || 'Unknown error'}`);
+    process.exit(1);
+  }
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+async function streamToBuffer(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+// ── Arg Parsing ─────────────────────────────────────────────────
+
+function parseArgs(args) {
+  const positional = [];
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const val = args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : 'true';
+      flags[key] = val;
+      i += val === 'true' ? 1 : 2;
+    } else {
+      positional.push(args[i]);
+      i++;
+    }
+  }
+  return { positional, flags };
+}
+
+function interpolatePath(template, id) {
+  return template.replace(':id', id);
+}
+
+// ── Output Formatting ───────────────────────────────────────────
+
+function formatOutput(data, commandKey) {
+  if (!data) { console.log('Done.'); return; }
+
+  // Special formatting for known responses
+  if (commandKey === 'dashboard') {
+    const s = data.stats;
+    console.log('\nDashboard');
+    console.log('═'.repeat(40));
+    console.log('\nClients:');
+    for (const item of s.clientsByStatus) console.log(`  ${item.status}: ${item.count}`);
+    console.log('\nProjects:');
+    for (const item of s.projectsByStatus) console.log(`  ${item.status}: ${item.count}`);
+    console.log('\nOpen Tasks:');
+    for (const item of s.openTasksByPriority) console.log(`  ${item.priority}: ${item.count}`);
+    console.log(`\nPending Onboarding: ${s.pendingOnboardingCount}`);
+    if (s.recentTasks?.length > 0) {
+      console.log('\nRecent Tasks:');
+      for (const t of s.recentTasks) {
+        const ago = timeAgo(t.createdAt);
+        console.log(`  • ${t.title} [${t.status}] by ${t.submittedBy} — ${ago}`);
+      }
+    }
+    if (s.recentUpdates?.length > 0) {
+      console.log('\nRecent Updates:');
+      for (const u of s.recentUpdates) {
+        const ago = timeAgo(u.createdAt);
+        const snippet = u.content.length > 80 ? u.content.slice(0, 80) + '...' : u.content;
+        console.log(`  • ${snippet} [${u.visibility}] by ${u.author} — ${ago}`);
+      }
+    }
+    return;
+  }
+
+  if (commandKey === 'clients.list') {
+    const items = data.data || [];
+    if (items.length === 0) { console.log('No clients found.'); return; }
+    console.log('\nClients:');
+    console.log('─'.repeat(70));
+    for (const c of items) {
+      const company = c.company ? ` (${c.company})` : '';
+      console.log(`  ${c.name}${company} — ${c.status} [${c.platform}] [${c.id}]`);
+    }
+    console.log(`\nTotal: ${items.length}`);
+    return;
+  }
+
+  if (commandKey === 'clients.get') {
+    const c = data.client;
+    console.log(`\n${c.name}${c.company ? ` — ${c.company}` : ''}`);
+    console.log(`  ID: ${c.id}`);
+    console.log(`  Status: ${c.status} | Tier: ${c.tier || '—'} | Platform: ${c.platform}`);
+    console.log(`  Email: ${c.email}${c.phone ? ` | Phone: ${c.phone}` : ''}`);
+    console.log(`  Portal: /c/${c.portalSlug}?token=${c.portalToken}`);
+    if (data.projects?.length > 0) {
+      console.log(`\n  Projects (${data.projects.length}):`);
+      for (const p of data.projects) console.log(`    • ${p.name} [${p.status}] [${p.id}]`);
+    }
+    return;
+  }
+
+  if (commandKey === 'projects.get') {
+    const p = data.project;
+    console.log(`\n${p.name} [${p.status}]`);
+    console.log(`  ID: ${p.id}`);
+    if (p.description) console.log(`  ${p.description}`);
+    if (p.startDate) console.log(`  Start: ${p.startDate} | Target: ${p.targetDate || '—'}`);
+    if (p.valueEur) console.log(`  Value: €${p.valueEur}`);
+    if (data.tasks?.length > 0) {
+      console.log(`\n  Tasks (${data.tasks.length}):`);
+      for (const t of data.tasks) {
+        const icon = t.status === 'done' ? '✓' : t.status === 'blocked' ? '!' : '○';
+        console.log(`    ${icon} ${t.title} [${t.status}] (${t.priority}) [${t.id}]`);
+      }
+    }
+    if (data.updates?.length > 0) {
+      console.log(`\n  Updates (${data.updates.length}):`);
+      for (const u of data.updates) {
+        const vis = u.visibility === 'internal' ? ' [INTERNAL]' : '';
+        console.log(`    ${u.author}: ${u.content.slice(0, 80)}${u.content.length > 80 ? '...' : ''}${vis}`);
+      }
+    }
+    return;
+  }
+
+  if (commandKey === 'tasks.all') {
+    const items = data.data || [];
+    if (items.length === 0) { console.log('No tasks found.'); return; }
+    console.log('\nAll Tasks:');
+    console.log('─'.repeat(70));
+    for (const t of items) {
+      const icon = t.status === 'done' ? '✓' : t.status === 'blocked' ? '!' : '○';
+      const phase = t.phase && t.phase !== 'current' ? ` [${t.phase}]` : '';
+      const prio = t.priority && t.priority !== 'normal' ? ` (${t.priority})` : '';
+      console.log(`  ${icon} ${t.title} [${t.status}]${prio}${phase} — ${t.projectName} / ${t.clientName} [${t.id}]`);
+    }
+    console.log(`\nTotal: ${items.length}`);
+    return;
+  }
+
+  if (commandKey === 'auth.me') {
+    const u = data.user;
+    console.log(`\n${u.name} (${u.email})`);
+    console.log(`  Role: ${u.role}`);
+    console.log(`  Tenant: ${u.tenantId}`);
+    return;
+  }
+
+  if (commandKey === 'metrics.list') {
+    const items = data.data || [];
+    if (items.length === 0) { console.log('No metrics snapshots yet.'); return; }
+    console.log(`\nMetrics History (${items.length} snapshots):`);
+    console.log('─'.repeat(60));
+    for (const m of items) {
+      const keys = Object.keys(m.metricsJson || {}).join(', ');
+      console.log(`  ${m.snapshotDate} [${m.sourceRef}] — ${keys}`);
+    }
+    if (data.baseline) console.log(`\nBaseline: ${data.baseline.snapshotDate}`);
+    return;
+  }
+
+  if (commandKey === 'metrics.latest') {
+    if (!data.metric) { console.log('No metrics data yet.'); return; }
+    const m = data.metric;
+    console.log(`\nLatest Snapshot: ${m.snapshotDate} [${m.sourceRef}]`);
+    console.log('─'.repeat(50));
+    if (data.config?.kpis) {
+      for (const kpi of data.config.kpis) {
+        const val = m.metricsJson[kpi.key];
+        const unit = kpi.unit || '';
+        const prefix = unit === '€' ? '€' : '';
+        const suffix = unit && unit !== '€' ? unit : '';
+        const baseVal = data.baseline?.metricsJson?.[kpi.key];
+        let delta = '';
+        if (baseVal != null && val != null && kpi.format !== 'text' && kpi.show_delta !== false) {
+          const diff = Number(val) - Number(baseVal);
+          const arrow = diff > 0 ? '▲' : diff < 0 ? '▼' : '=';
+          delta = ` (${arrow} ${Math.abs(diff).toLocaleString()} vs baseline)`;
+        }
+        console.log(`  ${kpi.label}: ${prefix}${val}${suffix}${delta}`);
+      }
+    }
+    if (data.items?.length > 0) {
+      console.log(`\n  Items: ${data.items.length}`);
+    }
+    return;
+  }
+
+  if (commandKey === 'metrics.items') {
+    const items = data.data || [];
+    if (items.length === 0) { console.log('No items for this snapshot.'); return; }
+    const cols = data.items_config?.columns || [];
+    console.log(`\n${data.items_config?.label || 'Items'} (${items.length}):`);
+    console.log('─'.repeat(60));
+    for (const item of items.slice(0, 25)) {
+      const parts = cols.slice(0, 4).map(c => `${c.label}: ${item.dataJson[c.key] ?? '—'}`);
+      console.log(`  ${parts.join(' | ')}`);
+    }
+    if (items.length > 25) console.log(`  ... and ${items.length - 25} more`);
+    return;
+  }
+
+  if (
+    commandKey === 'clients.docs-invoices' ||
+    commandKey === 'projects.docs-invoices'
+  ) {
+    formatDocsInvoices(data.data || []);
+    return;
+  }
+
+  if (
+    commandKey === 'clients.docs-documents' ||
+    commandKey === 'projects.docs-documents'
+  ) {
+    formatDocsDocuments(data.data || []);
+    return;
+  }
+
+  if (commandKey === 'clients.docs-sync') {
+    const sync = data.data || data;
+    console.log('Klevar Docs sync complete.');
+    if (sync.created !== undefined || sync.updated !== undefined) {
+      console.log(`  Created: ${sync.created ?? 0}`);
+      console.log(`  Updated: ${sync.updated ?? 0}`);
+    }
+    if (sync.rows?.length) {
+      console.log(`  Rows: ${sync.rows.length}`);
+    }
+    return;
+  }
+
+  if (commandKey === 'tasks.list' || commandKey === 'updates.list' || commandKey === 'projects.list' || commandKey === 'projects.all' || commandKey === 'onboarding.list') {
+    const items = data.data || [];
+    if (items.length === 0) { console.log('No items found.'); return; }
+
+    if (commandKey === 'tasks.list') {
+      console.log('\nTasks:');
+      for (const t of items) {
+        const icon = t.status === 'done' ? '✓' : t.status === 'blocked' ? '!' : '○';
+        console.log(`  ${icon} ${t.title} [${t.status}] (${t.priority}) [${t.id}]`);
+      }
+    } else if (commandKey === 'updates.list') {
+      console.log('\nUpdates:');
+      for (const u of items) {
+        const vis = u.visibility === 'internal' ? ' [INTERNAL]' : '';
+        console.log(`  ${u.author}: ${u.content.slice(0, 100)}${u.content.length > 100 ? '...' : ''}${vis} [${u.id}]`);
+      }
+    } else if (commandKey === 'projects.list' || commandKey === 'projects.all') {
+      console.log('\nProjects:');
+      for (const p of items) {
+        const client = p.clientName ? ` (${p.clientName})` : '';
+        console.log(`  • ${p.name}${client} [${p.status}] [${p.id}]`);
+      }
+    } else if (commandKey === 'onboarding.list') {
+      console.log('\nPending Submissions:');
+      for (const s of items) {
+        const fd = s.formData || {};
+        console.log(`  ${fd.name || 'Unknown'} (${fd.email || '—'}) — ${fd.platformSource || 'direct'} [${s.id}]`);
+      }
+    }
+    console.log(`\nTotal: ${items.length}`);
+    return;
+  }
+
+  // Metrics push
+  if (commandKey === 'metrics.push') {
+    console.log(`Metrics pushed: ${data.metric_id} (${data.items_count} items, upserted: ${data.upserted})`);
+    return;
+  }
+
+  // Comments
+  if (commandKey === 'comments.list') {
+    const items = data.data || [];
+    if (items.length === 0) { console.log('No comments yet.'); return; }
+    console.log(`\nComments (${items.length}):`);
+    for (const c of items) {
+      const badge = c.authorType === 'admin' ? '[admin]' : '[client]';
+      console.log(`  ${c.authorName} ${badge} — ${timeAgo(c.createdAt)}`);
+      console.log(`    ${c.content}`);
+    }
+    return;
+  }
+
+  if (commandKey === 'comments.create' && data.comment) {
+    const c = data.comment;
+    console.log(`Comment posted by ${c.authorName} [${c.authorType}] on ${c.visibility} update`);
+    return;
+  }
+
+  // Onboarding create/process/reject
+  if (commandKey === 'onboarding.create' && data.id) {
+    console.log(`Submission created: ${data.id} [${data.status}]`);
+    return;
+  }
+  if (commandKey === 'onboarding.process' && data.client) {
+    const c = data.client;
+    console.log(`Client created: ${c.name} [${c.status}] [${c.id}]`);
+    if (c.portalSlug) console.log(`  Portal: /c/${c.portalSlug}?token=${c.portalToken}`);
+    return;
+  }
+  if (commandKey === 'onboarding.reject') {
+    console.log('Submission rejected.');
+    return;
+  }
+
+  // Create responses — formatted instead of raw JSON
+  if (data.client) {
+    const c = data.client;
+    console.log(`Client created: ${c.name} [${c.status}] [${c.id}]`);
+    if (c.portalSlug) console.log(`  Portal: /c/${c.portalSlug}?token=${c.portalToken}`);
+    return;
+  }
+  if (data.project) {
+    const p = data.project;
+    console.log(`Project: ${p.name} [${p.status}] [${p.id}]`);
+    if (p.valueEur) console.log(`  Value: €${p.valueEur}`);
+    return;
+  }
+  if (data.task) {
+    const t = data.task;
+    const icon = t.status === 'done' ? '✓' : t.status === 'blocked' ? '!' : '○';
+    console.log(`Task: ${icon} ${t.title} [${t.status}] (${t.priority}) [${t.id}]`);
+    return;
+  }
+  if (data.update) {
+    const u = data.update;
+    const vis = u.visibility === 'internal' ? ' [INTERNAL]' : '';
+    console.log(`Update posted${vis}: ${u.content.slice(0, 80)}${u.content.length > 80 ? '...' : ''} [${u.id}]`);
+    return;
+  }
+  if (data.portalToken) {
+    console.log(`New token: ${data.portalToken}`);
+    return;
+  }
+  if (data.tenant) {
+    const t = data.tenant;
+    console.log(`Tenant: ${t.name} (${t.slug}) [${t.id}]`);
+    return;
+  }
+
+  // Fallback: print JSON
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function formatDocsInvoices(items) {
+  if (items.length === 0) { console.log('No Docs invoices found.'); return; }
+  console.log(`\nDocs Invoices (${items.length}):`);
+  console.log('-'.repeat(80));
+  for (const invoice of items) {
+    const number = invoice.invoiceNumber || invoice.docsInvoiceId;
+    const amount = invoice.total ? `${invoice.currency || ''} ${invoice.total}`.trim() : 'n/a';
+    const due = invoice.dueDate ? ` due ${invoice.dueDate}` : '';
+    const visibility = invoice.visibility === 'internal' ? ' [INTERNAL]' : '';
+    console.log(`  ${number} [${invoice.status}] ${amount}${due}${visibility} [${invoice.id}]`);
+  }
+}
+
+function formatDocsDocuments(items) {
+  if (items.length === 0) { console.log('No Docs documents found.'); return; }
+  console.log(`\nDocs Documents (${items.length}):`);
+  console.log('-'.repeat(80));
+  for (const doc of items) {
+    const number = doc.documentNumber || doc.docsDocumentId;
+    const type = doc.documentType || 'document';
+    const visibility = doc.visibility === 'internal' ? ' [INTERNAL]' : '';
+    console.log(`  ${number} (${type}) [${doc.status}]${visibility} [${doc.id}]`);
+  }
+}
+
+// ── Router ──────────────────────────────────────────────────────
+
+let [,, resource, action, ...rest] = process.argv;
+
+if (!resource || resource === 'help' || resource === '--help') {
+  console.log('Klevar Client Portal CLI\n');
+  console.log('Usage: node client.js <resource> <action> [id] [--key value ...]\n');
+  console.log('Commands:');
+  const grouped = {};
+  for (const [key, cmd] of Object.entries(COMMANDS)) {
+    const [res, act] = key.includes('.') ? key.split('.') : [key, ''];
+    if (!grouped[res]) grouped[res] = [];
+    grouped[res].push({ action: act, desc: (cmd.description || cmd.desc), body: cmd.body });
+  }
+  for (const [res, cmds] of Object.entries(grouped)) {
+    console.log(`\n  ${res}:`);
+    for (const c of cmds) {
+      const bodyHint = c.body ? ` [${c.body.map(b => '--' + b).join(' ')}]` : '';
+      console.log(`    ${c.action || '(default)'}  — ${c.desc}${bodyHint}`);
+    }
+  }
+  console.log(`\nConfig: PORTAL_API_KEY, PORTAL_URL (or ~/.klevar/portal.env)`);
+  console.log(`Target: ${BASE_URL}`);
+  process.exit(0);
+}
+
+// Resolve command key — handle single-word commands (e.g. "search <term>")
+let commandKey = action ? `${resource}.${action}` : resource;
+let cmd = COMMANDS[commandKey];
+if (!cmd && action && rest[0]) {
+  const nestedKey = `${resource}.${action}.${rest[0]}`;
+  if (COMMANDS[nestedKey]) {
+    commandKey = nestedKey;
+    cmd = COMMANDS[commandKey];
+    rest = rest.slice(1);
+  }
+}
+if (!cmd && COMMANDS[resource]) {
+  // "action" is actually the first positional arg, not a sub-command
+  commandKey = resource;
+  cmd = COMMANDS[commandKey];
+  rest = [action, ...rest];
+}
+
+if (!cmd) {
+  console.error(`Unknown command: ${commandKey}`);
+  console.error(`Run 'node client.js help' for available commands.`);
+  process.exit(1);
+}
+
+// Parse remaining args
+const { positional, flags } = parseArgs(rest);
+if (flags['api-url']) process.env.PORTAL_API_URL = flags['api-url'];
+if (flags['api-key']) process.env.PORTAL_API_KEY = flags['api-key'];
+if (flags['portal-token']) process.env.PORTAL_TOKEN = flags['portal-token'];
+if (flags['api-url']) BASE_URL = flags['api-url'];
+if (flags['api-key']) API_KEY = flags['api-key'];
+if (flags['portal-token']) PORTAL_TOKEN = flags['portal-token'];
+const id = positional[0];
+
+// Interpolate path
+let path = cmd.path;
+const pathParams = [...path.matchAll(/:([A-Za-z][A-Za-z0-9_]*)/g)].map((match) => match[1]);
+if (pathParams.length > 0) {
+  pathParams.forEach((paramName, index) => {
+    const value = positional[index];
+    if (!value) {
+      const ordinal = index === 0 ? 'an ID argument' : `argument ${index + 1} for :${paramName}`;
+      console.error(`Command '${commandKey}' requires ${ordinal}.`);
+      process.exit(1);
+    }
+    path = path.replace(`:${paramName}`, value);
+  });
+}
+
+// Append query parameters for GET commands with filters
+if (cmd.queryParams || cmd.fixedQuery) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(cmd.fixedQuery || {})) {
+    params.set(key, value);
+  }
+  for (const key of cmd.queryParams || []) {
+    if (flags[key]) params.set(key, flags[key]);
+  }
+  const qs = params.toString();
+  if (qs) path += (path.includes('?') ? '&' : '?') + qs;
+}
+
+// Build body from flags or fixedBody
+let body = undefined;
+if (cmd.fixedBody) {
+  body = cmd.fixedBody;
+} else if (cmd.body && Object.keys(flags).length > 0) {
+  body = {};
+  for (const key of cmd.body) {
+    if (flags[key] !== undefined) {
+      let val = flags[key];
+      // Auto-parse JSON strings (e.g. --metricsConfig '{"kpis":[...]}')
+      if (typeof val === 'string' && (val.startsWith('{') || val.startsWith('['))) {
+        try { val = JSON.parse(val); } catch { /* keep as string */ }
+      }
+      body[key] = val;
+    }
+  }
+}
+
+// For simple create commands, support positional content
+if (commandKey === 'updates.create' && !body && positional[1]) {
+  body = { content: positional.slice(1).join(' '), visibility: 'client' };
+}
+
+// ── Search Command ──
+if (commandKey === 'search') {
+  const q = [id, ...positional.slice(1)].filter(Boolean).join(' ');
+  if (!q) {
+    console.error('Usage: search <term>');
+    process.exit(1);
+  }
+  const data = await api('GET', `/api/admin/search?q=${encodeURIComponent(q)}`);
+  const hasResults = data.projects.length + data.tasks.length + data.updates.length > 0;
+
+  if (!hasResults) {
+    console.log(`No results for "${q}"`);
+    process.exit(0);
+  }
+
+  console.log(`\nSearch: "${q}"`);
+  console.log('─'.repeat(50));
+
+  if (data.projects.length > 0) {
+    console.log('\nProjects:');
+    data.projects.forEach((p) => {
+      console.log(`  • ${p.name} (${p.clientName}) [${p.status}] [${p.id}]`);
+    });
+  } else {
+    console.log('\nProjects: (none)');
+  }
+
+  if (data.tasks.length > 0) {
+    console.log('\nTasks:');
+    data.tasks.forEach((t) => {
+      const prio = t.priority && t.priority !== 'normal' ? ` (${t.priority})` : '';
+      console.log(`  • ${t.title} [${t.status}]${prio} — in: ${t.projectName} [${t.id}]`);
+    });
+  } else {
+    console.log('\nTasks: (none)');
+  }
+
+  if (data.updates.length > 0) {
+    console.log('\nUpdates:');
+    data.updates.forEach((u) => {
+      const vis = u.visibility === 'internal' ? ' [INTERNAL]' : '';
+      console.log(`  • ${u.contentPreview}${vis} — in: ${u.projectName} [${u.id}]`);
+    });
+  } else {
+    console.log('\nUpdates: (none)');
+  }
+
+  process.exit(0);
+}
+
+// ── Milestone Commands (custom logic: fetch → modify → PATCH) ──
+
+if (cmd.method === 'CUSTOM' && resource === 'milestones') {
+  const projectId = id;
+  if (!projectId) {
+    console.error('Usage: milestones <action> <projectId> [--name "..."] or [index]');
+    process.exit(1);
+  }
+
+  // Fetch current project
+  const projData = await api('GET', `/api/admin/projects/${projectId}`);
+  const milestones = projData.project.milestonesJson ?? [];
+
+  if (action === 'list') {
+    if (milestones.length === 0) {
+      console.log('No milestones defined.');
+    } else {
+      console.log(`\nMilestones for: ${projData.project.name}`);
+      console.log('─'.repeat(50));
+      milestones.forEach((m, i) => {
+        const icon = m.status === 'done' ? '✓' : m.status === 'in_progress' ? '◐' : '○';
+        console.log(`  ${i + 1}. ${icon} ${m.name} [${m.status}]`);
+      });
+    }
+    process.exit(0);
+  }
+
+  if (action === 'add') {
+    const name = flags.name || positional[1];
+    if (!name) { console.error('Usage: milestones add <projectId> --name "Milestone name"'); process.exit(1); }
+    milestones.push({ name, status: 'pending' });
+    await api('PATCH', `/api/admin/projects/${projectId}`, { milestonesJson: milestones });
+    console.log(`Added milestone: ${name} (${milestones.length} total)`);
+    process.exit(0);
+  }
+
+  if (action === 'done' || action === 'undo' || action === 'remove') {
+    const idx = parseInt(positional[1] || flags.index, 10) - 1;
+    if (isNaN(idx) || idx < 0 || idx >= milestones.length) {
+      console.error(`Invalid index. Use 1-${milestones.length}.`);
+      process.exit(1);
+    }
+    if (action === 'done') {
+      milestones[idx].status = 'done';
+      await api('PATCH', `/api/admin/projects/${projectId}`, { milestonesJson: milestones });
+      console.log(`Marked done: ${milestones[idx].name}`);
+    } else if (action === 'undo') {
+      milestones[idx].status = 'pending';
+      await api('PATCH', `/api/admin/projects/${projectId}`, { milestonesJson: milestones });
+      console.log(`Reverted to pending: ${milestones[idx].name}`);
+    } else if (action === 'remove') {
+      const removed = milestones.splice(idx, 1);
+      await api('PATCH', `/api/admin/projects/${projectId}`, { milestonesJson: milestones });
+      console.log(`Removed: ${removed[0].name} (${milestones.length} remaining)`);
+    }
+    process.exit(0);
+  }
+
+  console.error(`Unknown milestone action: ${action}`);
+  process.exit(1);
+}
+
+// ── File Upload (multipart) ──
+if (cmd.supportsFiles && flags.file) {
+  const filePaths = Array.isArray(flags.file) ? flags.file : [flags.file];
+  const fields = {};
+  if (body) Object.assign(fields, body);
+  if (!fields.content && commandKey === 'updates.create') {
+    fields.content = positional.slice(1).join(' ') || '';
+  }
+  if (!fields.visibility) fields.visibility = 'client';
+  const data = await apiMultipart(cmd.method, path, fields, filePaths);
+  formatOutput(data, commandKey);
+  process.exit(0);
+}
+
+if (cmd.method === 'DOWNLOAD') {
+  await apiDownload(path, flags.output, cmd.auth);
+  process.exit(0);
+}
+
+// Execute
+const data = await api(cmd.method, path, body, cmd.auth);
+formatOutput(data, commandKey);