@agenticmail/enterprise 0.5.326 → 0.5.328

package/src/engine/cli-submit-skill.ts

@@ -1,200 +0,0 @@
-/**
- * CLI: npx @agenticmail/enterprise submit-skill <path>
- *
- * Automates the GitHub PR submission flow for a community skill.
- * Uses the `gh` CLI to fork, branch, commit, push, and open a PR.
- */
-
-import { validateSkillManifest } from './skill-validator.js';
-
-const UPSTREAM_REPO = 'agenticmail/enterprise';
-
-export async function runSubmitSkill(args: string[]) {
-  const chalk = (await import('chalk')).default;
-  const ora = (await import('ora')).default;
-  const { execSync } = await import('child_process');
-  const fs = await import('fs/promises');
-  const path = await import('path');
-
-  const target = args.filter(a => !a.startsWith('--'))[0];
-  if (!target) {
-    console.log(`${chalk.bold('Usage:')} npx @agenticmail/enterprise submit-skill <path-to-skill-dir>`);
-    process.exit(1);
-    return;
-  }
-
-  const skillDir = path.resolve(target);
-
-  console.log('');
-  console.log(chalk.bold('\uD83D\uDE80 Submit Community Skill'));
-  console.log('');
-
-  // ── Step 1: Check gh CLI ──────────────────────────
-
-  const spinner = ora('Checking prerequisites...').start();
-  try {
-    execSync('gh --version', { stdio: 'pipe' });
-  } catch {
-    spinner.fail('GitHub CLI (gh) is not installed');
-    console.log('');
-    console.log(chalk.dim('  Install it from: https://cli.github.com/'));
-    console.log(chalk.dim('  Then run: gh auth login'));
-    process.exit(1);
-    return;
-  }
-
-  // Check gh auth
-  try {
-    execSync('gh auth status', { stdio: 'pipe' });
-  } catch {
-    spinner.fail('Not authenticated with GitHub CLI');
-    console.log(chalk.dim('  Run: gh auth login'));
-    process.exit(1);
-    return;
-  }
-  spinner.succeed('GitHub CLI authenticated');
-
-  // ── Step 2: Validate the skill ────────────────────
-
-  const validateSpinner = ora('Validating skill manifest...').start();
-  const manifestPath = path.join(skillDir, 'agenticmail-skill.json');
-
-  let manifest: any;
-  try {
-    const raw = await fs.readFile(manifestPath, 'utf-8');
-    manifest = JSON.parse(raw);
-  } catch (err: any) {
-    validateSpinner.fail(`Cannot read manifest: ${err.message}`);
-    process.exit(1);
-    return;
-  }
-
-  const validation = validateSkillManifest(manifest);
-  if (!validation.valid) {
-    validateSpinner.fail('Manifest validation failed');
-    for (const err of validation.errors) {
-      console.log(chalk.red('  \u2502 ' + err));
-    }
-    console.log(chalk.dim('\n  Fix the errors above and try again.'));
-    process.exit(1);
-    return;
-  }
-  validateSpinner.succeed(`Manifest valid: ${manifest.name} v${manifest.version}`);
-
-  const skillId = manifest.id;
-  const branchName = `community/add-${skillId}`;
-
-  // ── Step 3: Fork the repo ─────────────────────────
-
-  const forkSpinner = ora('Forking repository...').start();
-  try {
-    execSync(`gh repo fork ${UPSTREAM_REPO} --clone=false 2>&1 || true`, { stdio: 'pipe' });
-    forkSpinner.succeed('Repository forked (or already exists)');
-  } catch {
-    forkSpinner.succeed('Fork exists');
-  }
-
-  // Get the fork URL
-  let forkUrl: string;
-  try {
-    const ghUser = execSync('gh api user --jq .login', { encoding: 'utf-8' }).trim();
-    forkUrl = `https://github.com/${ghUser}/enterprise.git`;
-  } catch {
-    forkSpinner.fail('Cannot determine GitHub username');
-    process.exit(1);
-    return;
-  }
-
-  // ── Step 4: Clone, branch, copy, commit, push ─────
-
-  const tmpDir = path.join(process.env.TMPDIR || '/tmp', `agenticmail-submit-${Date.now()}`);
-  const pushSpinner = ora('Cloning fork...').start();
-
-  try {
-    execSync(`git clone --depth 1 ${forkUrl} "${tmpDir}"`, { stdio: 'pipe' });
-    pushSpinner.text = 'Creating branch...';
-
-    const run = (cmd: string) => execSync(cmd, { cwd: tmpDir, stdio: 'pipe', encoding: 'utf-8' });
-
-    // Add upstream remote and fetch
-    run(`git remote add upstream https://github.com/${UPSTREAM_REPO}.git`);
-    run('git fetch upstream main --depth 1');
-    run(`git checkout -b ${branchName} upstream/main`);
-
-    // Copy skill directory
-    pushSpinner.text = 'Copying skill files...';
-    const destDir = path.join(tmpDir, 'community-skills', skillId);
-    await fs.mkdir(destDir, { recursive: true });
-    const files = await fs.readdir(skillDir);
-    for (const file of files) {
-      await fs.copyFile(path.join(skillDir, file), path.join(destDir, file));
-    }
-
-    // Commit
-    pushSpinner.text = 'Committing...';
-    run(`git add community-skills/${skillId}/`);
-    run(`git commit -m "Add community skill: ${manifest.name}"`);
-
-    // Push
-    pushSpinner.text = 'Pushing to fork...';
-    run(`git push origin ${branchName} --force`);
-    pushSpinner.succeed('Pushed to fork');
-  } catch (err: any) {
-    pushSpinner.fail(`Git operation failed: ${err.message}`);
-    process.exit(1);
-    return;
-  }
-
-  // ── Step 5: Open PR ───────────────────────────────
-
-  const prSpinner = ora('Opening pull request...').start();
-
-  const toolsList = (manifest.tools || []).map((t: any) =>
-    `- \`${t.id}\` — ${t.name}: ${t.description}`
-  ).join('\n');
-
-  const prBody = `## Community Skill Submission
-
-**Skill ID:** \`${manifest.id}\`
-**Application:** ${manifest.name}
-**Category:** ${manifest.category}
-**Risk Level:** ${manifest.risk}
-**Author:** @${manifest.author}
-**License:** ${manifest.license}
-
-### Description
-
-${manifest.description}
-
-### Tools Provided
-
-${toolsList}
-
-### Validation
-
-- [x] Manifest passes \`npx @agenticmail/enterprise validate\`
-- [x] All required fields present
-- [x] No duplicate tool IDs
-${manifest.tags ? `\n**Tags:** ${manifest.tags.join(', ')}` : ''}`;
-
-  try {
-    const prUrl = execSync(
-      `gh pr create --repo ${UPSTREAM_REPO} --head ${branchName} --title "Add community skill: ${manifest.name}" --body "${prBody.replace(/"/g, '\\"')}"`,
-      { cwd: tmpDir, encoding: 'utf-8', stdio: 'pipe' },
-    ).trim();
-    prSpinner.succeed('Pull request opened!');
-    console.log(chalk.green(`\n  ${prUrl}\n`));
-  } catch (err: any) {
-    // PR might already exist
-    if (err.stderr?.includes('already exists')) {
-      prSpinner.warn('A PR for this skill already exists');
-    } else {
-      prSpinner.fail(`Could not open PR: ${err.message}`);
-    }
-  }
-
-  // Cleanup
-  try {
-    await fs.rm(tmpDir, { recursive: true, force: true });
-  } catch { /* ignore */ }
-}

package/src/engine/cli-validate.ts

@@ -1,188 +0,0 @@
-/**
- * CLI: npx @agenticmail/enterprise validate <path>
- *
- * Validates an agenticmail-skill.json manifest against the full spec.
- * Checks for duplicate tool IDs against the builtin catalog and
- * other community skills.
- *
- * Flags:
- *   --all   Validate all skills in community-skills/
- *   --json  Machine-readable JSON output (for CI)
- */
-
-import { validateSkillManifest, collectCommunityToolIds } from './skill-validator.js';
-import { ALL_TOOLS } from './tool-catalog.js';
-
-interface ValidationReport {
-  path: string;
-  skillId: string;
-  valid: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
-export async function runValidate(args: string[]) {
-  const chalk = (await import('chalk')).default;
-  const fs = await import('fs/promises');
-  const path = await import('path');
-
-  const jsonMode = args.includes('--json');
-  const allMode = args.includes('--all');
-  const pathArgs = args.filter(a => !a.startsWith('--'));
-
-  // Build the set of builtin tool IDs
-  const builtinIds = new Set(ALL_TOOLS.map(t => t.id || t.name));
-
-  // Resolve community-skills/ directory
-  const communityDir = path.resolve(process.cwd(), 'community-skills');
-
-  const reports: ValidationReport[] = [];
-
-  if (allMode) {
-    // Validate all skills in community-skills/
-    let entries: import('fs').Dirent[];
-    try {
-      entries = await fs.readdir(communityDir, { withFileTypes: true });
-    } catch {
-      if (jsonMode) {
-        console.log(JSON.stringify({ error: 'community-skills/ directory not found' }));
-      } else {
-        console.error(chalk.red('Error: community-skills/ directory not found'));
-      }
-      process.exit(1);
-      return;
-    }
-
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
-      const skillDir = path.join(communityDir, entry.name);
-      const report = await validatePath(skillDir, builtinIds, communityDir);
-      reports.push(report);
-    }
-  } else {
-    // Validate specific path(s)
-    const target = pathArgs[0];
-    if (!target) {
-      if (jsonMode) {
-        console.log(JSON.stringify({ error: 'No path specified. Usage: npx @agenticmail/enterprise validate <path> [--all] [--json]' }));
-      } else {
-        console.log(`${chalk.bold('Usage:')} npx @agenticmail/enterprise validate <path>`);
-        console.log('');
-        console.log('  <path>    Path to a skill directory or agenticmail-skill.json file');
-        console.log('  --all     Validate all skills in community-skills/');
-        console.log('  --json    Machine-readable JSON output');
-      }
-      process.exit(1);
-      return;
-    }
-
-    const report = await validatePath(path.resolve(target), builtinIds, communityDir);
-    reports.push(report);
-  }
-
-  // Output results
-  if (jsonMode) {
-    console.log(JSON.stringify({ results: reports, totalErrors: reports.reduce((s, r) => s + r.errors.length, 0) }, null, 2));
-  } else {
-    console.log('');
-    for (const report of reports) {
-      if (report.valid) {
-        console.log(chalk.green('  \u2714') + ' ' + chalk.bold(report.skillId) + chalk.dim(` (${report.path})`));
-      } else {
-        console.log(chalk.red('  \u2718') + ' ' + chalk.bold(report.skillId) + chalk.dim(` (${report.path})`));
-        for (const err of report.errors) {
-          console.log(chalk.red('    \u2502 ') + err);
-        }
-      }
-      for (const warn of report.warnings) {
-        console.log(chalk.yellow('    \u26A0 ') + warn);
-      }
-    }
-
-    console.log('');
-    const passed = reports.filter(r => r.valid).length;
-    const failed = reports.filter(r => !r.valid).length;
-    if (failed > 0) {
-      console.log(chalk.red(`  ${failed} failed`) + chalk.dim(`, ${passed} passed, ${reports.length} total`));
-    } else {
-      console.log(chalk.green(`  ${passed} passed`) + chalk.dim(`, ${reports.length} total`));
-    }
-    console.log('');
-  }
-
-  // Exit with error code if any failed
-  if (reports.some(r => !r.valid)) {
-    process.exit(1);
-  }
-}
-
-async function validatePath(
-  targetPath: string,
-  builtinIds: Set<string>,
-  communityDir: string,
-): Promise<ValidationReport> {
-  const fs = await import('fs/promises');
-  const path = await import('path');
-
-  let manifestPath: string;
-
-  // Determine if path is a directory or a JSON file
-  try {
-    const stat = await fs.stat(targetPath);
-    if (stat.isDirectory()) {
-      manifestPath = path.join(targetPath, 'agenticmail-skill.json');
-    } else {
-      manifestPath = targetPath;
-    }
-  } catch {
-    return {
-      path: targetPath,
-      skillId: path.basename(targetPath),
-      valid: false,
-      errors: [`Path not found: ${targetPath}`],
-      warnings: [],
-    };
-  }
-
-  // Read and parse
-  let raw: string;
-  try {
-    raw = await fs.readFile(manifestPath, 'utf-8');
-  } catch {
-    return {
-      path: manifestPath,
-      skillId: path.basename(path.dirname(manifestPath)),
-      valid: false,
-      errors: [`Cannot read: ${manifestPath}`],
-      warnings: [],
-    };
-  }
-
-  let manifest: any;
-  try {
-    manifest = JSON.parse(raw);
-  } catch (err: any) {
-    return {
-      path: manifestPath,
-      skillId: path.basename(path.dirname(manifestPath)),
-      valid: false,
-      errors: [`Invalid JSON: ${err.message}`],
-      warnings: [],
-    };
-  }
-
-  // Collect community tool IDs (excluding self)
-  const communityIds = await collectCommunityToolIds(communityDir, manifest.id);
-  const allExistingIds = new Set([...builtinIds, ...communityIds]);
-
-  // Validate
-  const result = validateSkillManifest(manifest, { existingToolIds: allExistingIds });
-
-  return {
-    path: manifestPath,
-    skillId: manifest.id || path.basename(path.dirname(manifestPath)),
-    valid: result.valid,
-    errors: result.errors,
-    warnings: result.warnings,
-  };
-}

package/src/engine/cluster.ts

@@ -1,278 +0,0 @@
-/**
- * Cluster Manager — Multi-Instance Agent Coordination
- *
- * Enables a single enterprise dashboard to manage agents running across
- * multiple machines (Mac Minis, VPS, cloud instances).
- *
- * Architecture:
- *   - Enterprise server = "Control Plane" (single dashboard, DB, SSE hub)
- *   - Agent instances = "Worker Nodes" (run on any machine, phone home to control plane)
- *
- * Worker nodes register via POST /cluster/register with their capabilities.
- * Control plane tracks health via heartbeats (every 30s, stale after 90s).
- * Agents deployed to remote workers communicate via ENTERPRISE_URL.
- *
- * Flow:
- *   1. Worker starts, calls POST /cluster/register { nodeId, host, port, capabilities }
- *   2. Control plane stores worker in memory + DB
- *   3. Dashboard shows all workers and their agents
- *   4. When user deploys an agent, they can pick a target worker
- *   5. Worker receives deploy command via its API
- *   6. Agent process starts on worker, reports status back to control plane
- */
-
-export interface WorkerNode {
-  nodeId: string;
-  name: string;
-  host: string;          // IP or hostname reachable from control plane
-  port: number;          // Worker API port
-  url: string;           // Full base URL (e.g., http://186.158.1.50:3101)
-  platform: string;      // darwin, linux, win32
-  arch: string;          // arm64, x64
-  cpuCount: number;
-  memoryMb: number;
-  version: string;       // @agenticmail/enterprise version
-  agents: string[];      // Agent IDs running on this worker
-  capabilities: string[];// e.g., ['gpu', 'browser', 'voice', 'docker']
-  status: 'online' | 'degraded' | 'offline';
-  registeredAt: string;
-  lastHeartbeat: string;
-  metadata?: Record<string, any>;
-}
-
-export interface ClusterStats {
-  totalNodes: number;
-  onlineNodes: number;
-  totalAgents: number;
-  totalCpus: number;
-  totalMemoryMb: number;
-}
-
-type NodeListener = (nodeId: string, node: WorkerNode, event: 'register' | 'heartbeat' | 'offline' | 'update') => void;
-
-export class ClusterManager {
-  private nodes = new Map<string, WorkerNode>();
-  private listeners = new Set<NodeListener>();
-  private staleTimer: NodeJS.Timeout | null = null;
-  private staleThresholdMs = 90_000; // 90s without heartbeat = offline
-  private db: any = null;
-
-  constructor() {
-    this.staleTimer = setInterval(() => this.checkStale(), 30_000);
-    if (this.staleTimer.unref) this.staleTimer.unref();
-  }
-
-  setDb(db: any) { this.db = db; }
-
-  /** Load persisted workers from DB on startup */
-  async loadFromDb(): Promise<void> {
-    if (!this.db) return;
-    try {
-      await this.db.execute(`CREATE TABLE IF NOT EXISTS cluster_nodes (
-        node_id TEXT PRIMARY KEY,
-        name TEXT NOT NULL,
-        host TEXT NOT NULL,
-        port INTEGER NOT NULL,
-        url TEXT NOT NULL,
-        platform TEXT,
-        arch TEXT,
-        cpu_count INTEGER DEFAULT 0,
-        memory_mb INTEGER DEFAULT 0,
-        version TEXT,
-        agents TEXT DEFAULT '[]',
-        capabilities TEXT DEFAULT '[]',
-        status TEXT DEFAULT 'offline',
-        registered_at TEXT,
-        last_heartbeat TEXT,
-        metadata TEXT
-      )`);
-      const rows = await this.db.query('SELECT * FROM cluster_nodes');
-      for (const row of rows) {
-        const node: WorkerNode = {
-          nodeId: row.node_id,
-          name: row.name || row.node_id,
-          host: row.host,
-          port: row.port,
-          url: row.url,
-          platform: row.platform || 'unknown',
-          arch: row.arch || 'unknown',
-          cpuCount: row.cpu_count || 0,
-          memoryMb: row.memory_mb || 0,
-          version: row.version || 'unknown',
-          agents: safeParse(row.agents, []),
-          capabilities: safeParse(row.capabilities, []),
-          status: 'offline', // Start as offline; heartbeat will set online
-          registeredAt: row.registered_at || new Date().toISOString(),
-          lastHeartbeat: row.last_heartbeat || '',
-          metadata: safeParse(row.metadata, {}),
-        };
-        this.nodes.set(node.nodeId, node);
-      }
-    } catch (e: any) {
-      console.warn('[cluster] Failed to load nodes from DB:', e.message);
-    }
-  }
-
-  /** Validate node ID format */
-  private validateNodeId(nodeId: string): string | null {
-    if (!nodeId || nodeId.length < 2) return 'Node ID must be at least 2 characters';
-    if (nodeId.length > 64) return 'Node ID must be at most 64 characters';
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(nodeId)) return 'Node ID must start with alphanumeric and contain only alphanumeric, dots, hyphens, underscores';
-    return null;
-  }
-
-  /** Register or re-register a worker node */
-  async register(data: {
-    nodeId: string;
-    name?: string;
-    host: string;
-    port: number;
-    platform?: string;
-    arch?: string;
-    cpuCount?: number;
-    memoryMb?: number;
-    version?: string;
-    agents?: string[];
-    capabilities?: string[];
-    metadata?: Record<string, any>;
-  }): Promise<WorkerNode> {
-    // Validate
-    const idErr = this.validateNodeId(data.nodeId);
-    if (idErr) throw new Error(idErr);
-    if (!data.host) throw new Error('host is required');
-    if (!data.port || data.port < 1 || data.port > 65535) throw new Error('port must be 1-65535');
-    const now = new Date().toISOString();
-    const existing = this.nodes.get(data.nodeId);
-    const node: WorkerNode = {
-      nodeId: data.nodeId,
-      name: data.name || data.nodeId,
-      host: data.host,
-      port: data.port,
-      url: `http://${data.host}:${data.port}`,
-      platform: data.platform || 'unknown',
-      arch: data.arch || 'unknown',
-      cpuCount: data.cpuCount || 0,
-      memoryMb: data.memoryMb || 0,
-      version: data.version || 'unknown',
-      agents: data.agents || existing?.agents || [],
-      capabilities: data.capabilities || [],
-      status: 'online',
-      registeredAt: existing?.registeredAt || now,
-      lastHeartbeat: now,
-      metadata: data.metadata || existing?.metadata || {},
-    };
-    this.nodes.set(node.nodeId, node);
-    this.emit(node.nodeId, node, 'register');
-
-    // Persist
-    if (this.db) {
-      try {
-        await this.db.execute(
-          `INSERT INTO cluster_nodes (node_id, name, host, port, url, platform, arch, cpu_count, memory_mb, version, agents, capabilities, status, registered_at, last_heartbeat, metadata)
-           VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16)
-           ON CONFLICT (node_id) DO UPDATE SET
-             name=$2, host=$3, port=$4, url=$5, platform=$6, arch=$7, cpu_count=$8, memory_mb=$9, version=$10,
-             agents=$11, capabilities=$12, status=$13, last_heartbeat=$15, metadata=$16`,
-          [node.nodeId, node.name, node.host, node.port, node.url, node.platform, node.arch,
-           node.cpuCount, node.memoryMb, node.version, JSON.stringify(node.agents),
-           JSON.stringify(node.capabilities), node.status, node.registeredAt, node.lastHeartbeat,
-           JSON.stringify(node.metadata)]
-        );
-      } catch (e: any) { console.warn('[cluster] DB persist error:', e.message); }
-    }
-
-    return node;
-  }
-
-  /** Worker sends heartbeat (every 30s) */
-  heartbeat(nodeId: string, data?: { agents?: string[]; cpuUsage?: number; memoryUsage?: number }): void {
-    const node = this.nodes.get(nodeId);
-    if (!node) return;
-    node.lastHeartbeat = new Date().toISOString();
-    node.status = 'online';
-    if (data?.agents) node.agents = data.agents;
-    if (data?.cpuUsage != null && node.metadata) node.metadata.cpuUsage = data.cpuUsage;
-    if (data?.memoryUsage != null && node.metadata) node.metadata.memoryUsage = data.memoryUsage;
-    this.emit(nodeId, node, 'heartbeat');
-  }
-
-  /** Remove a worker node */
-  async remove(nodeId: string): Promise<void> {
-    const node = this.nodes.get(nodeId);
-    this.nodes.delete(nodeId);
-    if (node) this.emit(nodeId, { ...node, status: 'offline' }, 'offline');
-    if (this.db) {
-      try { await this.db.execute('DELETE FROM cluster_nodes WHERE node_id = $1', [nodeId]); } catch {}
-    }
-  }
-
-  /** Get a specific node */
-  getNode(nodeId: string): WorkerNode | undefined { return this.nodes.get(nodeId); }
-
-  /** Get all nodes */
-  getAllNodes(): WorkerNode[] { return Array.from(this.nodes.values()); }
-
-  /** Get online nodes */
-  getOnlineNodes(): WorkerNode[] { return this.getAllNodes().filter(n => n.status === 'online'); }
-
-  /** Get cluster-wide stats */
-  getStats(): ClusterStats {
-    const nodes = this.getAllNodes();
-    const online = nodes.filter(n => n.status === 'online');
-    return {
-      totalNodes: nodes.length,
-      onlineNodes: online.length,
-      totalAgents: nodes.reduce((s, n) => s + n.agents.length, 0),
-      totalCpus: online.reduce((s, n) => s + n.cpuCount, 0),
-      totalMemoryMb: online.reduce((s, n) => s + n.memoryMb, 0),
-    };
-  }
-
-  /** Find best node for a new agent (simple: least agents on online node) */
-  findBestNode(capabilities?: string[]): WorkerNode | null {
-    let candidates = this.getOnlineNodes();
-    if (capabilities?.length) {
-      candidates = candidates.filter(n => capabilities.every(c => n.capabilities.includes(c)));
-    }
-    if (candidates.length === 0) return null;
-    return candidates.sort((a, b) => a.agents.length - b.agents.length)[0];
-  }
-
-  /** Subscribe to cluster events (for SSE) */
-  subscribe(listener: NodeListener): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  }
-
-  private emit(nodeId: string, node: WorkerNode, event: 'register' | 'heartbeat' | 'offline' | 'update'): void {
-    for (const listener of this.listeners) {
-      try { listener(nodeId, node, event); } catch {}
-    }
-  }
-
-  private checkStale(): void {
-    const now = Date.now();
-    for (const [nodeId, node] of this.nodes) {
-      if (node.status === 'offline') continue;
-      if (node.lastHeartbeat) {
-        const elapsed = now - new Date(node.lastHeartbeat).getTime();
-        if (elapsed > this.staleThresholdMs) {
-          node.status = 'offline';
-          node.agents = [];
-          this.emit(nodeId, node, 'offline');
-        }
-      }
-    }
-  }
-
-  destroy(): void {
-    if (this.staleTimer) clearInterval(this.staleTimer);
-    this.listeners.clear();
-  }
-}
-
-function safeParse(val: any, fallback: any): any {
-  if (!val) return fallback;
-  if (typeof val === 'object') return val;
-  try { return JSON.parse(val); } catch { return fallback; }
-}