optimal-cli 0.1.0 → 1.0.0

package/lib/config.ts

@@ -0,0 +1,247 @@
+import { createClient, SupabaseClient } from '@supabase/supabase-js'
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const CONFIG_DIR = join(homedir(), '.optimal')
+const LOCAL_CONFIG_PATH = join(CONFIG_DIR, 'config.json')
+const OPENCLAW_CONFIG_PATH = join(homedir(), '.openclaw', 'openclaw.json')
+
+// Get Supabase client for OptimalOS instance (stores CLI configs)
+function getOptimalSupabase(): SupabaseClient {
+  const url = process.env.OPTIMAL_SUPABASE_URL
+  const key = process.env.OPTIMAL_SUPABASE_SERVICE_KEY
+  if (!url || !key) {
+    throw new Error('OPTIMAL_SUPABASE_URL and OPTIMAL_SUPABASE_SERVICE_KEY must be set')
+  }
+  return createClient(url, key)
+}
+
+interface ConfigRecord {
+  id: string
+  agent_name: string
+  config_json: Record<string, unknown>
+  version: string
+  created_at: string
+  updated_at: string
+}
+
+/**
+ * Initialize local config directory
+ */
+export function initConfigDir(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    import('node:fs').then(fs => fs.mkdirSync(CONFIG_DIR, { recursive: true }))
+  }
+}
+
+/**
+ * Load local openclaw.json
+ */
+export function loadLocalConfig(): Record<string, unknown> | null {
+  if (!existsSync(OPENCLAW_CONFIG_PATH)) {
+    return null
+  }
+  try {
+    const raw = readFileSync(OPENCLAW_CONFIG_PATH, 'utf-8')
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Save config to local openclaw.json
+ */
+export function saveLocalConfig(config: Record<string, unknown>): void {
+  writeFileSync(OPENCLAW_CONFIG_PATH, JSON.stringify(config, null, 2))
+}
+
+/**
+ * Push current openclaw.json to Supabase
+ */
+export async function pushConfig(agentName: string): Promise<{ id: string; version: string }> {
+  const supabase = getOptimalSupabase()
+  const config = loadLocalConfig()
+  
+  if (!config) {
+    throw new Error(`No config found at ${OPENCLAW_CONFIG_PATH}`)
+  }
+
+  // Generate version timestamp
+  const version = new Date().toISOString()
+
+  // Check if config exists for this agent
+  const { data: existing } = await supabase
+    .from('agent_configs')
+    .select('id')
+    .eq('agent_name', agentName)
+    .single()
+
+  let result
+  if (existing) {
+    // Update existing
+    const { data, error } = await supabase
+      .from('agent_configs')
+      .update({
+        config_json: config,
+        version,
+        updated_at: version,
+      })
+      .eq('id', existing.id)
+      .select()
+      .single()
+    
+    if (error) throw error
+    result = data
+  } else {
+    // Insert new
+    const { data, error } = await supabase
+      .from('agent_configs')
+      .insert({
+        agent_name: agentName,
+        config_json: config,
+        version,
+      })
+      .select()
+      .single()
+    
+    if (error) throw error
+    result = data
+  }
+
+  return { id: result.id, version }
+}
+
+/**
+ * Pull config from Supabase and save to local openclaw.json
+ */
+export async function pullConfig(agentName: string): Promise<ConfigRecord> {
+  const supabase = getOptimalSupabase()
+
+  const { data, error } = await supabase
+    .from('agent_configs')
+    .select('*')
+    .eq('agent_name', agentName)
+    .order('updated_at', { ascending: false })
+    .limit(1)
+    .single()
+
+  if (error) {
+    throw new Error(`No config found for agent: ${agentName}`)
+  }
+
+  // Save to local
+  saveLocalConfig(data.config_json)
+  
+  return data as ConfigRecord
+}
+
+/**
+ * List all saved agent configs
+ */
+export async function listConfigs(): Promise<Array<{ agent_name: string; version: string; updated_at: string }>> {
+  const supabase = getOptimalSupabase()
+
+  const { data, error } = await supabase
+    .from('agent_configs')
+    .select('agent_name, version, updated_at')
+    .order('updated_at', { ascending: false })
+
+  if (error) {
+    throw new Error(`Failed to list configs: ${error.message}`)
+  }
+
+  return data || []
+}
+
+/**
+ * Compare local config with cloud version
+ */
+export async function diffConfig(agentName: string): Promise<{
+  local: Record<string, unknown> | null
+  cloud: ConfigRecord | null
+  differences: string[]
+}> {
+  const local = loadLocalConfig()
+  let cloud: ConfigRecord | null = null
+  
+  try {
+    const supabase = getOptimalSupabase()
+    const { data } = await supabase
+      .from('agent_configs')
+      .select('*')
+      .eq('agent_name', agentName)
+      .single()
+    cloud = data as ConfigRecord
+  } catch {
+    // Cloud config doesn't exist
+  }
+
+  const differences: string[] = []
+  
+  if (!local && !cloud) {
+    differences.push('No local or cloud config found')
+  } else if (!local) {
+    differences.push('No local config (cloud exists)')
+  } else if (!cloud) {
+    differences.push('No cloud config (local exists)')
+  } else {
+    // Simple diff on top-level keys
+    const localKeys = Object.keys(local).sort()
+    const cloudKeys = Object.keys(cloud.config_json).sort()
+    
+    if (JSON.stringify(localKeys) !== JSON.stringify(cloudKeys)) {
+      differences.push('Top-level keys differ')
+    }
+    
+    // Check version
+    const localMeta = (local as any).meta
+    if (localMeta?.lastTouchedVersion !== cloud.version) {
+      differences.push(`Version mismatch: local=${localMeta?.lastTouchedVersion}, cloud=${cloud.version}`)
+    }
+  }
+
+  return { local, cloud, differences }
+}
+
+/**
+ * Sync config (two-way merge)
+ */
+export async function syncConfig(agentName: string): Promise<{
+  action: 'pushed' | 'pulled' | 'merged' | 'none'
+  message: string
+}> {
+  const { local, cloud, differences } = await diffConfig(agentName)
+
+  if (!local && !cloud) {
+    return { action: 'none', message: 'No configs to sync' }
+  }
+
+  if (!cloud) {
+    // Only local exists - push
+    const result = await pushConfig(agentName)
+    return { action: 'pushed', message: `Pushed to cloud (version ${result.version})` }
+  }
+
+  if (!local) {
+    // Only cloud exists - pull
+    await pullConfig(agentName)
+    return { action: 'pulled', message: `Pulled from cloud (version ${cloud.version})` }
+  }
+
+  // Both exist - compare timestamps
+  const localTime = (local as any).meta?.lastTouchedAt || '1970-01-01'
+  const localVersion = (local as any).meta?.lastTouchedVersion || 'unknown'
+  const cloudTime = cloud.updated_at
+
+  if (localTime > cloudTime) {
+    const result = await pushConfig(agentName)
+    return { action: 'pushed', message: `Local is newer - pushed to cloud (version ${result.version})` }
+  } else if (cloudTime > localTime) {
+    await pullConfig(agentName)
+    return { action: 'pulled', message: `Cloud is newer - pulled from cloud (version ${cloud.version})` }
+  } else {
+    return { action: 'none', message: 'Configs are in sync' }
+  }
+}

package/lib/errors.ts

@@ -0,0 +1,129 @@
+/**
+ * Centralized error handling for the Optimal CLI.
+ *
+ * Provides a typed CliError class, a user-friendly formatter,
+ * and a wrapCommand helper for Commander action handlers.
+ */
+
+// ── Error codes ──────────────────────────────────────────────────────────────
+
+export type ErrorCode =
+  | 'MISSING_ENV'
+  | 'NOT_FOUND'
+  | 'SUPABASE_ERROR'
+  | 'VALIDATION_ERROR'
+  | 'AUTH_ERROR'
+  | 'NETWORK_ERROR'
+  | 'FILE_ERROR'
+  | 'UNKNOWN'
+
+// ── CliError ─────────────────────────────────────────────────────────────────
+
+export class CliError extends Error {
+  constructor(
+    message: string,
+    public code: ErrorCode,
+    public suggestion?: string,
+  ) {
+    super(message)
+    this.name = 'CliError'
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const SUGGESTIONS: Record<string, string> = {
+  MISSING_ENV:
+    'Ensure the required environment variables are set in your .env file or shell.',
+  NOT_FOUND: 'Double-check the identifier (slug, ID, or name) and try again.',
+  SUPABASE_ERROR:
+    'Verify your Supabase URL and service key are correct and the database is reachable.',
+  VALIDATION_ERROR: 'Review the command options with --help.',
+  AUTH_ERROR:
+    'Check your API token or credentials and make sure they have not expired.',
+  NETWORK_ERROR:
+    'Check your internet connection and verify the remote service is available.',
+  FILE_ERROR: 'Verify the file path exists and you have read/write permissions.',
+}
+
+function classifyError(err: unknown): { code: ErrorCode; message: string } {
+  if (err instanceof CliError) {
+    return { code: err.code, message: err.message }
+  }
+
+  if (err instanceof Error) {
+    const msg = err.message
+
+    // Supabase / fetch errors
+    if (msg.includes('PGRST') || msg.includes('supabase') || msg.includes('relation')) {
+      return { code: 'SUPABASE_ERROR', message: msg }
+    }
+    if (msg.includes('ENOENT') || msg.includes('no such file')) {
+      return { code: 'FILE_ERROR', message: msg }
+    }
+    if (msg.includes('ECONNREFUSED') || msg.includes('fetch failed') || msg.includes('ETIMEDOUT')) {
+      return { code: 'NETWORK_ERROR', message: msg }
+    }
+    if (
+      msg.includes('OPTIMAL_SUPABASE_URL') ||
+      msg.includes('OPTIMAL_SUPABASE_SERVICE_KEY') ||
+      msg.includes('env')
+    ) {
+      return { code: 'MISSING_ENV', message: msg }
+    }
+
+    return { code: 'UNKNOWN', message: msg }
+  }
+
+  return { code: 'UNKNOWN', message: String(err) }
+}
+
+// ── handleError ──────────────────────────────────────────────────────────────
+
+/**
+ * Format an error for CLI output, print it to stderr, and exit with code 1.
+ */
+export function handleError(err: unknown): never {
+  const { code, message } = classifyError(err)
+
+  const suggestion =
+    err instanceof CliError && err.suggestion
+      ? err.suggestion
+      : SUGGESTIONS[code] ?? ''
+
+  const lines: string[] = [
+    '',
+    `  Error [${code}]: ${message}`,
+  ]
+
+  if (suggestion) {
+    lines.push(`  Suggestion: ${suggestion}`)
+  }
+
+  lines.push('')
+
+  process.stderr.write(lines.join('\n'))
+  process.exit(1)
+}
+
+// ── wrapCommand ──────────────────────────────────────────────────────────────
+
+/**
+ * Wrap a Commander action handler so any thrown error is routed through
+ * handleError, giving the user a consistent, friendly message instead of
+ * an unhandled-rejection stack trace.
+ *
+ * Usage:
+ *   .action(wrapCommand(async (opts) => { ... }))
+ */
+export function wrapCommand<A extends unknown[]>(
+  fn: (...args: A) => Promise<void>,
+): (...args: A) => Promise<void> {
+  return async (...args: A) => {
+    try {
+      await fn(...args)
+    } catch (err) {
+      handleError(err)
+    }
+  }
+}

package/lib/format.ts

@@ -0,0 +1,120 @@
+/**
+ * Lightweight CLI output formatting — ANSI colors, tables, badges.
+ * Zero external dependencies. Respects NO_COLOR env var.
+ */
+
+// ── ANSI escape codes ───────────────────────────────────────────────
+
+const CODES: Record<string, [number, number]> = {
+  red:    [31, 39],
+  green:  [32, 39],
+  yellow: [33, 39],
+  blue:   [34, 39],
+  cyan:   [36, 39],
+  gray:   [90, 39],
+  bold:   [1,  22],
+  dim:    [2,  22],
+}
+
+type Color = 'red' | 'green' | 'yellow' | 'blue' | 'cyan' | 'gray' | 'bold' | 'dim'
+
+/**
+ * Wrap text in ANSI escape codes for the given color/style.
+ * Returns plain text when NO_COLOR env var is set.
+ */
+export function colorize(text: string, color: Color): string {
+  if (process.env.NO_COLOR !== undefined) return text
+  const [open, close] = CODES[color]
+  return `\x1b[${open}m${text}\x1b[${close}m`
+}
+
+// ── Table rendering ─────────────────────────────────────────────────
+
+/** Strip ANSI escape sequences to measure visible string width. */
+function stripAnsi(s: string): string {
+  return s.replace(/\x1b\[\d+m/g, '')
+}
+
+/**
+ * Render a bordered ASCII table with auto-sized columns.
+ * Headers are rendered in bold.
+ */
+export function table(headers: string[], rows: string[][]): string {
+  // Compute column widths from headers and all rows
+  const colWidths = headers.map((h, i) => {
+    let max = stripAnsi(h).length
+    for (const row of rows) {
+      const cell = row[i] ?? ''
+      const len = stripAnsi(cell).length
+      if (len > max) max = len
+    }
+    return max
+  })
+
+  function padCell(cell: string, width: number): string {
+    const visible = stripAnsi(cell).length
+    return cell + ' '.repeat(Math.max(0, width - visible))
+  }
+
+  const sep = '+-' + colWidths.map(w => '-'.repeat(w)).join('-+-') + '-+'
+  const headerRow = '| ' + headers.map((h, i) => padCell(colorize(h, 'bold'), colWidths[i])).join(' | ') + ' |'
+
+  const bodyRows = rows.map(row =>
+    '| ' + row.map((cell, i) => padCell(cell ?? '', colWidths[i])).join(' | ') + ' |'
+  )
+
+  return [sep, headerRow, sep, ...bodyRows, sep].join('\n')
+}
+
+// ── Status & priority badges ────────────────────────────────────────
+
+const STATUS_COLORS: Record<string, Color> = {
+  done:        'green',
+  in_progress: 'blue',
+  blocked:     'red',
+  ready:       'cyan',
+  backlog:     'gray',
+  cancelled:   'dim',
+  review:      'yellow',
+}
+
+/** Return a colored status string (e.g. "done" in green). */
+export function statusBadge(status: string): string {
+  const color = STATUS_COLORS[status] ?? 'dim'
+  return colorize(status, color)
+}
+
+const PRIORITY_COLORS: Record<number, Color> = {
+  1: 'red',
+  2: 'yellow',
+  3: 'blue',
+  4: 'gray',
+}
+
+/** Return a colored priority label (e.g. "P1" in red). */
+export function priorityBadge(p: number): string {
+  const color = PRIORITY_COLORS[p] ?? 'gray'
+  return colorize(`P${p}`, color)
+}
+
+// ── Logging helpers ─────────────────────────────────────────────────
+
+/** Print a green success message with a check mark prefix. */
+export function success(msg: string): void {
+  console.log(`${colorize('\u2713', 'green')} ${msg}`)
+}
+
+/** Print a red error message with an X prefix. */
+export function error(msg: string): void {
+  console.error(`${colorize('\u2717', 'red')} ${msg}`)
+}
+
+/** Print a yellow warning message with a warning prefix. */
+export function warn(msg: string): void {
+  console.warn(`${colorize('\u26a0', 'yellow')} ${msg}`)
+}
+
+/** Print a blue info message with an info prefix. */
+export function info(msg: string): void {
+  console.log(`${colorize('\u2139', 'blue')} ${msg}`)
+}

package/lib/infra/deploy.ts

@@ -0,0 +1,70 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const run = promisify(execFile)
+
+/** Map of short app names to absolute filesystem paths. */
+const APP_PATHS: Record<string, string> = {
+  'dashboard-returnpro': '/home/optimal/dashboard-returnpro',
+  'optimalos': '/home/optimal/optimalos',
+  'portfolio': '/home/optimal/portfolio-2026',
+  'newsletter-preview': '/home/optimal/projects/newsletter-preview',
+  'wes': '/home/optimal/wes-dashboard',
+}
+
+/**
+ * List all available app names that can be deployed.
+ */
+export function listApps(): string[] {
+  return Object.keys(APP_PATHS)
+}
+
+/**
+ * Resolve an app name to its absolute filesystem path.
+ * Throws if the app name is unknown.
+ */
+export function getAppPath(appName: string): string {
+  const appPath = APP_PATHS[appName]
+  if (!appPath) {
+    throw new Error(
+      `Unknown app: ${appName}. Available: ${Object.keys(APP_PATHS).join(', ')}`
+    )
+  }
+  return appPath
+}
+
+/**
+ * Deploy an app to Vercel using the `vercel` CLI.
+ *
+ * Uses `execFile` (not `exec`) to avoid shell injection.
+ * The `--cwd` flag tells Vercel which project directory to deploy.
+ *
+ * @param appName - Short name from APP_PATHS (e.g. 'portfolio', 'dashboard-returnpro')
+ * @param prod - If true, deploys to production (--prod flag). Otherwise preview.
+ * @returns The deployment URL printed by Vercel CLI.
+ */
+export async function deploy(appName: string, prod = false): Promise<string> {
+  const appPath = getAppPath(appName)
+  const args = prod
+    ? ['--prod', '--cwd', appPath]
+    : ['--cwd', appPath]
+  const { stdout } = await run('vercel', args, { timeout: 120_000 })
+  return stdout.trim()
+}
+
+/**
+ * Run the Optimal workstation health check script.
+ *
+ * Checks: n8n, Affine (Docker + HTTP), Strapi CMS (systemd + HTTP),
+ * Git repo sync status, Docker containers, and OptimalOS dev server.
+ *
+ * @returns The full text output of the health check script.
+ */
+export async function healthCheck(): Promise<string> {
+  const { stdout } = await run(
+    'bash',
+    ['/home/optimal/scripts/health-check.sh'],
+    { timeout: 30_000 }
+  )
+  return stdout.trim()
+}

package/lib/infra/migrate.ts

@@ -0,0 +1,141 @@
+import 'dotenv/config'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { readdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const run = promisify(execFile)
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface MigrateOptions {
+  target: 'returnpro' | 'optimalos'
+  dryRun?: boolean // if true, just show what would be pushed
+}
+
+export interface MigrateResult {
+  success: boolean
+  target: string
+  output: string
+  errors: string
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Hardcoded project directories — these live on Carlos's machine. */
+const PROJECT_DIRS: Record<'returnpro' | 'optimalos', string> = {
+  returnpro: '/home/optimal/dashboard-returnpro',
+  optimalos: '/home/optimal/optimalos',
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getProjectDir(target: 'returnpro' | 'optimalos'): string {
+  return PROJECT_DIRS[target]
+}
+
+function migrationsDir(target: 'returnpro' | 'optimalos'): string {
+  return join(getProjectDir(target), 'supabase', 'migrations')
+}
+
+/**
+ * Generate a timestamp string in YYYYMMDDHHMMSS format (UTC).
+ */
+function timestamp(): string {
+  const now = new Date()
+  const pad = (n: number, len = 2) => String(n).padStart(len, '0')
+  return [
+    now.getUTCFullYear(),
+    pad(now.getUTCMonth() + 1),
+    pad(now.getUTCDate()),
+    pad(now.getUTCHours()),
+    pad(now.getUTCMinutes()),
+    pad(now.getUTCSeconds()),
+  ].join('')
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `supabase db push --linked` (or `--dry-run` if requested) against the
+ * given target project directory.
+ *
+ * Uses `execFile` (not `exec`) to avoid shell injection.
+ * The `cwd` option switches the Supabase CLI into the correct project.
+ */
+export async function migrateDb(opts: MigrateOptions): Promise<MigrateResult> {
+  const { target, dryRun = false } = opts
+  const projectDir = getProjectDir(target)
+
+  const args: string[] = ['db', 'push', '--linked']
+  if (dryRun) args.push('--dry-run')
+
+  try {
+    const { stdout, stderr } = await run('supabase', args, {
+      cwd: projectDir,
+      timeout: 120_000,
+    })
+    return {
+      success: true,
+      target,
+      output: stdout.trim(),
+      errors: stderr.trim(),
+    }
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; stderr?: string; message?: string }
+    return {
+      success: false,
+      target,
+      output: (e.stdout ?? '').trim(),
+      errors: (e.stderr ?? e.message ?? String(err)).trim(),
+    }
+  }
+}
+
+/**
+ * List migration `.sql` files in the target's `supabase/migrations/` directory,
+ * sorted chronologically (by filename, which starts with a YYYYMMDDHHMMSS prefix).
+ *
+ * Returns only filenames, not full paths.
+ */
+export async function listPendingMigrations(
+  target: 'returnpro' | 'optimalos'
+): Promise<string[]> {
+  const dir = migrationsDir(target)
+  const entries = await readdir(dir)
+  return entries
+    .filter((f) => f.endsWith('.sql'))
+    .sort() // lexicographic == chronological given the YYYYMMDDHHMMSS prefix
+}
+
+/**
+ * Create a new empty migration file in the target's `supabase/migrations/`
+ * directory.
+ *
+ * The filename format is `{YYYYMMDDHHMMSS}_{name}.sql` (UTC timestamp).
+ * Returns the full absolute path of the created file.
+ */
+export async function createMigration(
+  target: 'returnpro' | 'optimalos',
+  name: string
+): Promise<string> {
+  const sanitized = name.replace(/\s+/g, '_').replace(/[^a-zA-Z0-9_]/g, '')
+  const filename = `${timestamp()}_${sanitized}.sql`
+  const fullPath = join(migrationsDir(target), filename)
+
+  await writeFile(
+    fullPath,
+    `-- Migration: ${sanitized}\n-- Target: ${target}\n-- Created: ${new Date().toISOString()}\n\n`,
+    { encoding: 'utf8' }
+  )
+
+  return fullPath
+}