@flame0510/project-aether 1.1.9

package/app/api/system-health/route.ts

@@ -0,0 +1,233 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { openDb } from '@/lib/db';
+import { maybeSendAlert } from '@/lib/alerts';
+import { summarizeBilling } from '@/lib/billing';
+import { listOpenClawCronJobs } from '@/lib/openclaw-cron';
+import type { ModelCost } from '@/lib/types';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+export const dynamic = 'force-dynamic';
+
+type Health = 'ok' | 'warning' | 'error';
+type Severity = 'info' | 'warning' | 'critical';
+
+interface SystemCheck {
+  id: string;
+  label: string;
+  health: Health;
+  value: string | number;
+  details?: string;
+  source: 'runtime' | 'cron' | 'cost' | 'trello';
+}
+
+interface Recommendation {
+  id: string;
+  severity: Severity;
+  source: SystemCheck['source'];
+  title: string;
+  details: string;
+  actionHref?: string;
+  dismissible: boolean;
+  createdAt: string;
+  trelloCardId?: string;
+}
+
+function topHealth(values: Health[]): Health {
+  if (values.includes('error')) return 'error';
+  if (values.includes('warning')) return 'warning';
+  return 'ok';
+}
+
+function getSeconds(value: unknown): number {
+  const n = Number(value ?? 0);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return n > 10_000_000_000 ? Math.floor(n / 1000) : n;
+}
+
+function getEnvNumber(name: string, fallback: number): number {
+  const value = Number(process.env[name] ?? fallback);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function tableExists(db: ReturnType<typeof openDb>, tableName: string): boolean {
+  const row = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(tableName);
+  return Boolean(row);
+}
+
+function columnExists(db: ReturnType<typeof openDb>, tableName: string, columnName: string): boolean {
+  return (db.prepare(`PRAGMA table_info(${tableName})`).all() as { name: string }[]).some((column) => column.name === columnName);
+}
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+
+  const now = new Date();
+  const createdAt = now.toISOString();
+  const checks: SystemCheck[] = [];
+  const recommendations: Recommendation[] = [];
+
+  try {
+    const db = openDb();
+    const sessionCount = (db.prepare('SELECT COUNT(*) AS total FROM sessions').get() as { total: number }).total;
+    const latestSessionRow = db.prepare('SELECT MAX(COALESCE(updated_at, started_at, 0)) AS latest FROM sessions').get() as { latest: number | null };
+    const latestSessionTs = getSeconds(latestSessionRow.latest);
+    const latestSessionAgeSeconds = latestSessionTs ? Math.floor(Date.now() / 1000) - latestSessionTs : null;
+    const staleThresholdSeconds = getEnvNumber('REV4A_ALERT_STALE_SECONDS', 120);
+
+    checks.push({
+      id: 'runtime.sessions',
+      label: 'Runtime sessions',
+      health: 'ok',
+      value: sessionCount,
+      details: latestSessionAgeSeconds === null ? 'No session detected' : `last session activity ${Math.round(latestSessionAgeSeconds / 60)}m ago`,
+      source: 'runtime',
+    });
+
+    const hasSystemMetrics = tableExists(db, 'system_metrics');
+    const latestMetricRow = hasSystemMetrics
+      ? (db.prepare('SELECT MAX(ts) AS latest FROM system_metrics').get() as { latest: number | null })
+      : null;
+    const latestMetricTs = getSeconds(latestMetricRow?.latest);
+    const latestMetricAgeSeconds = latestMetricTs ? Math.floor(Date.now() / 1000) - latestMetricTs : null;
+    const runtimeFreshnessHealth: Health = !hasSystemMetrics
+      ? 'ok'
+      : latestMetricAgeSeconds === null
+        ? 'warning'
+        : latestMetricAgeSeconds > staleThresholdSeconds
+          ? 'warning'
+          : 'ok';
+
+    checks.push({
+      id: 'runtime.ingestion',
+      label: 'Runtime ingestion',
+      health: runtimeFreshnessHealth,
+      value: hasSystemMetrics ? (latestMetricTs ? 'fresh' : 'missing') : 'n/d',
+      details: !hasSystemMetrics
+        ? 'Heartbeat metrics unavailable in this DB'
+        : latestMetricAgeSeconds === null
+          ? 'No heartbeat metrics detected'
+          : `ultimo heartbeat metrics ${latestMetricAgeSeconds}s fa`,
+      source: 'runtime',
+    });
+
+    if (hasSystemMetrics && runtimeFreshnessHealth !== 'ok') {
+      recommendations.push({
+        id: 'runtime.check-freshness',
+        severity: 'warning',
+        source: 'runtime',
+        title: 'Check Rev4a runtime heartbeat',
+        details: latestMetricAgeSeconds === null
+          ? 'No heartbeat metrics available from runtime.'
+          : `Heartbeat metrics stuck for ${latestMetricAgeSeconds}s (soglia ${staleThresholdSeconds}s).`,
+        actionHref: '/lineage',
+        dismissible: false,
+        createdAt,
+      });
+    }
+
+    await maybeSendAlert({
+      key: 'system-health.db-freshness',
+      kind: 'db-freshness',
+      title: 'Rev4a DB freshness',
+      message: !hasSystemMetrics
+        ? 'system_metrics table unavailable: freshness runtime not verifiable.'
+        : latestMetricAgeSeconds === null
+          ? 'No heartbeat metrics detected.'
+          : `Last heartbeat metrics ${latestMetricAgeSeconds}s fa (soglia ${staleThresholdSeconds}s).`,
+      resolvedMessage: 'DB Rev4a fresh again.',
+      stale: hasSystemMetrics ? (latestMetricAgeSeconds === null ? true : latestMetricAgeSeconds > staleThresholdSeconds) : false,
+    });
+
+    const eventExpr = tableExists(db, 'events')
+      ? [columnExists(db, 'events', 'type') ? 'type' : null, columnExists(db, 'events', 'event') ? 'event' : null].filter(Boolean).join(", ''), COALESCE(")
+      : '';
+    const eventErrorCount = eventExpr
+      ? (db.prepare(`SELECT COUNT(*) AS total FROM events WHERE LOWER(COALESCE(${eventExpr}, '')) LIKE '%error%' AND ts >= ?`).get(Math.floor(Date.now() / 1000) - 86400) as { total: number }).total
+      : 0;
+    checks.push({
+      id: 'runtime.errors24h',
+      label: 'Errors last 24h',
+      health: eventErrorCount > 0 ? 'warning' : 'ok',
+      value: eventErrorCount,
+      source: 'runtime',
+    });
+    if (eventErrorCount > 0) {
+      recommendations.push({
+        id: 'runtime.review-errors',
+        severity: 'warning',
+        source: 'runtime',
+        title: 'Review recent errors',
+        details: `${eventErrorCount} error events nelle ultime 24h.`,
+        actionHref: '/lineage',
+        dismissible: true,
+        createdAt,
+      });
+    }
+
+    const startOfDay = new Date();
+    startOfDay.setHours(0, 0, 0, 0);
+    const todayModels = db.prepare(
+      `SELECT model,
+        COALESCE(SUM(cost_usd), 0) AS cost_usd,
+        COALESCE(SUM(tokens_in), 0) AS tokens_in,
+        COALESCE(SUM(tokens_out), 0) AS tokens_out,
+        COUNT(*) AS sessions
+       FROM sessions WHERE started_at >= ?
+       GROUP BY model ORDER BY cost_usd DESC`,
+    ).all(Math.floor(startOfDay.getTime() / 1000)) as ModelCost[];
+    const billing = summarizeBilling(todayModels);
+    checks.push({
+      id: 'cost.usageBasedToday',
+      label: 'Usage-based cost today',
+      health: billing.usageBasedCost > 10 ? 'warning' : 'ok',
+      value: `$${billing.usageBasedCost.toFixed(2)}`,
+      details: `DB estimate $${billing.dbEstimatedCost.toFixed(2)}; fixed ${billing.buckets.fixed.sessions} sessioni; credits ${billing.buckets.credits.sessions} sessioni`,
+      source: 'cost',
+    });
+    if (billing.usageBasedCost > 10) {
+      recommendations.push({
+        id: 'cost.review-usage-based',
+        severity: 'warning',
+        source: 'cost',
+        title: 'High usage-based cost',
+        details: `Provider usage-based today: $${billing.usageBasedCost.toFixed(2)}. Include OpenRouter e altri provider pay-per-use, non i piani fissi.`,
+        actionHref: '/gateway',
+        dismissible: true,
+        createdAt,
+      });
+    }
+    if (billing.unknownModels.length > 0 && billing.buckets.unknown.cost_usd > 1) {
+      recommendations.push({
+        id: 'cost.classify-unknown-models',
+        severity: 'warning',
+        source: 'cost',
+        title: 'Unclassified models in billing',
+        details: `${billing.unknownModels.length} unclassified models have DB estimate $${billing.buckets.unknown.cost_usd.toFixed(2)}.`,
+        actionHref: '/gateway',
+        dismissible: true,
+        createdAt,
+      });
+    }
+    db.close();
+  } catch (error) {
+    checks.push({ id: 'runtime.db', label: 'Rev4a DB', health: 'error', value: 'error', details: (error as Error).message, source: 'runtime' });
+    recommendations.push({ id: 'runtime.db-error', severity: 'critical', source: 'runtime', title: 'Rev4a DB unreadable', details: (error as Error).message, dismissible: false, createdAt });
+  }
+
+  try {
+    const cron = await listOpenClawCronJobs();
+    const enabled = cron.jobs.filter((job) => job.enabled !== false).length;
+    const hostCount = cron.jobs.filter((j) => j.source === 'host').length;
+    const containerCount = cron.jobs.filter((j) => j.source === 'container').length;
+    checks.push({ id: 'cron.jobs', label: 'Cron jobs', health: enabled > 0 ? 'ok' : 'warning', value: enabled, details: `${hostCount} host · ${containerCount} container`, source: 'cron' });
+    if (enabled === 0) {
+      recommendations.push({ id: 'cron.enable-watchdog', severity: 'warning', source: 'cron', title: 'No enabled cron detected', details: 'No cron jobs are enabled on the host or any agent container.', actionHref: '/crons', dismissible: false, createdAt });
+    }
+  } catch (error) {
+    checks.push({ id: 'cron.openclaw', label: 'Cron jobs', health: 'warning', value: 'warning', details: (error as Error).message, source: 'cron' });
+    recommendations.push({ id: 'cron.openclaw-unavailable', severity: 'warning', source: 'cron', title: 'Cron list unavailable', details: 'Failed to list cron jobs.', actionHref: '/crons', dismissible: false, createdAt });
+  }
+
+  const health = topHealth(checks.map((check) => check.health));
+  return NextResponse.json({ health, checks, recommendations, generatedAt: createdAt });
+}

package/app/api/tool-calls/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { openDb } from '@/lib/db';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  const { searchParams } = new URL(request.url);
+  const limit = Math.min(Number.parseInt(searchParams.get('limit') ?? '50', 10), 200);
+  const sessionId = searchParams.get('session_id');
+  try {
+    const db = openDb();
+    const rows = sessionId
+      ? db
+          .prepare('SELECT * FROM tool_calls WHERE session_id = ? ORDER BY ts DESC LIMIT ?')
+          .all(sessionId, limit)
+      : db.prepare('SELECT * FROM tool_calls ORDER BY ts DESC LIMIT ?').all(limit);
+    db.close();
+    return NextResponse.json(rows);
+  } catch {
+    return NextResponse.json([], { status: 200 });
+  }
+}

package/app/api/tools-config/route.ts

@@ -0,0 +1,163 @@
+import fs from 'fs';
+import path from 'path';
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+export const dynamic = 'force-dynamic';
+
+const CONFIG_PATH = '/data/.openclaw/openclaw.json';
+const REV4A_SETTINGS_PATH = '/data/rev4a/settings.json';
+
+type JsonObject = Record<string, unknown>;
+
+function readConfig(): JsonObject {
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as JsonObject;
+}
+
+function formatBackupTimestamp(date: Date): string {
+  const pad = (v: number) => String(v).padStart(2, '0');
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds()),
+  ].join('');
+}
+
+function writeConfig(config: JsonObject): void {
+  const dir = path.dirname(CONFIG_PATH);
+  const base = path.basename(CONFIG_PATH);
+  const backup = path.join(dir, `${base}.bak-${formatBackupTimestamp(new Date())}`);
+  const tmp = path.join(dir, `${base}.tmp-${process.pid}-${Date.now()}`);
+  const data = `${JSON.stringify(config, null, 2)}\n`;
+
+  fs.copyFileSync(CONFIG_PATH, backup);
+
+  let fd: number | undefined;
+  let dfd: number | undefined;
+  try {
+    fd = fs.openSync(tmp, 'w', 0o600);
+    fs.writeFileSync(fd, data, 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(tmp, CONFIG_PATH);
+    dfd = fs.openSync(dir, 'r');
+    fs.fsyncSync(dfd);
+    fs.closeSync(dfd);
+    dfd = undefined;
+  } catch (e) {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (dfd !== undefined) fs.closeSync(dfd);
+    if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    throw e;
+  }
+}
+
+function getAudio(config: JsonObject): JsonObject {
+  const tools = (config.tools ?? {}) as JsonObject;
+  const media = (tools.media ?? {}) as JsonObject;
+  return (media.audio ?? {}) as JsonObject;
+}
+
+function readRev4aSettings(): JsonObject {
+  try {
+    return JSON.parse(fs.readFileSync(REV4A_SETTINGS_PATH, 'utf8')) as JsonObject;
+  } catch {
+    return {};
+  }
+}
+
+function writeRev4aSettings(settings: JsonObject): void {
+  const dir = path.dirname(REV4A_SETTINGS_PATH);
+  const tmp = path.join(dir, `.settings.json.tmp-${process.pid}-${Date.now()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, REV4A_SETTINGS_PATH);
+}
+
+function getTimezone(): string {
+  const settings = readRev4aSettings();
+  const tz = settings.timezone;
+  return typeof tz === 'string' && tz ? tz : 'Europe/Rome';
+}
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  try {
+    const config = readConfig();
+    const audio = getAudio(config);
+    const timezone = getTimezone();
+    return NextResponse.json({ audio, timezone });
+  } catch (e: unknown) {
+    return NextResponse.json({ error: (e as Error).message }, { status: 500 });
+  }
+}
+
+interface AudioInput {
+  enabled?: boolean;
+  timeoutSeconds?: number;
+  maxBytes?: number;
+  models?: JsonObject[];
+}
+
+const VALID_TIMEZONES = [
+  'Europe/Rome', 'UTC', 'Europe/London', 'Europe/Berlin', 'Europe/Paris',
+  'America/New_York', 'America/Chicago', 'America/Denver', 'America/Los_Angeles',
+  'Asia/Tokyo', 'Asia/Shanghai', 'Asia/Dubai', 'Asia/Kolkata',
+  'Australia/Sydney', 'Pacific/Auckland',
+];
+
+export async function PUT(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  try {
+    const body = (await request.json()) as { audio?: AudioInput; timezone?: string };
+
+    const config = readConfig();
+    if (!config.tools) config.tools = {};
+    const tools = config.tools as JsonObject;
+    let timezone = getTimezone();
+
+    if (body.timezone !== undefined) {
+      if (typeof body.timezone !== 'string' || !body.timezone)
+        throw new Error('timezone must be a non-empty string');
+      if (!VALID_TIMEZONES.includes(body.timezone))
+        throw new Error('timezone is not supported');
+      timezone = body.timezone;
+      writeRev4aSettings({ ...readRev4aSettings(), timezone });
+    }
+
+    const input = body?.audio;
+    if (input) {
+      if (typeof input !== 'object') throw new Error('audio must be an object');
+      if (input.enabled !== undefined && typeof input.enabled !== 'boolean')
+        throw new Error('enabled must be boolean');
+      if (input.timeoutSeconds !== undefined && (typeof input.timeoutSeconds !== 'number' || !Number.isFinite(input.timeoutSeconds)))
+        throw new Error('timeoutSeconds must be a number');
+      if (input.maxBytes !== undefined && (typeof input.maxBytes !== 'number' || !Number.isFinite(input.maxBytes)))
+        throw new Error('maxBytes must be a number');
+      if (input.models !== undefined && !Array.isArray(input.models))
+        throw new Error('models must be an array');
+
+      if (!tools.media) tools.media = {};
+      const media = tools.media as JsonObject;
+      const existing = (media.audio ?? {}) as JsonObject;
+
+      const next: JsonObject = { ...existing };
+      if (input.enabled !== undefined) next.enabled = input.enabled;
+      if (input.timeoutSeconds !== undefined) next.timeoutSeconds = input.timeoutSeconds;
+      if (input.maxBytes !== undefined) next.maxBytes = input.maxBytes;
+      if (input.models !== undefined) next.models = input.models;
+
+      media.audio = next;
+    }
+
+    writeConfig(config);
+
+    return NextResponse.json({ ok: true, timezone, audio: config.tools && (config.tools as JsonObject).media ? ((config.tools as JsonObject).media as JsonObject).audio : {} });
+  } catch (e: unknown) {
+    return NextResponse.json({ error: (e as Error).message }, { status: 400 });
+  }
+}

package/app/api/update-check/route.ts

@@ -0,0 +1,127 @@
+import { NextResponse } from 'next/server';
+import { jwtVerify } from 'jose';
+import { execSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+function getPackageInfo() {
+  try {
+    // Resolve relative to the project root (two levels above .next)
+    const pkgPath = join(process.cwd(), 'package.json');
+    const raw = readFileSync(pkgPath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return { version: '0.0.0', name: '@flame0510/project-aether' };
+  }
+}
+
+interface CachedResult {
+  latest: string | null;
+  updateAvailable: boolean;
+  checkedAt: number;
+}
+
+let cache: CachedResult | null = null;
+const CACHE_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * GET /api/update-check
+ */
+export async function GET(request: Request): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  const url = new URL(request.url);
+  const check = url.searchParams.get('check') === '1';
+
+  const pkg = getPackageInfo();
+  const installed = pkg.version || '0.0.0';
+  let latest: string | null = null;
+  let updateAvailable = false;
+
+  if (check) {
+    const now = Date.now();
+    if (cache && now - cache.checkedAt < CACHE_TTL_MS) {
+      latest = cache.latest;
+      updateAvailable = cache.updateAvailable;
+    } else {
+      try {
+        const pkgName = pkg.name || '@flame0510/project-aether';
+        latest = execSync(
+          `npm view ${pkgName} version --registry https://registry.npmjs.org 2>/dev/null`,
+          { stdio: 'pipe', timeout: 10_000 },
+        ).toString().trim();
+
+        if (latest && latest !== installed) {
+          updateAvailable = true;
+        }
+        cache = { latest, updateAvailable, checkedAt: now };
+      } catch {
+        if (cache) {
+          latest = cache.latest;
+          updateAvailable = cache.updateAvailable;
+        }
+      }
+    }
+  }
+
+  return NextResponse.json({ installed, latest, updateAvailable, package: getPackageInfo().name });
+}
+
+async function verifyAuth(request: Request): Promise<boolean> {
+  const raw = request.headers.get('cookie') || '';
+  const match = raw.split(';').map(c => c.trim()).find(c => c.startsWith('rev4a_token='));
+  if (!match) return false;
+
+  const cookieToken = decodeURIComponent(match.split('=')[1]);
+  try {
+    const secret = new TextEncoder().encode(
+      process.env.REV4A_JWT_SECRET || (() => { throw new Error('REV4A_JWT_SECRET not set'); })(),
+    );
+    await jwtVerify(cookieToken, secret);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * POST /api/update-check
+ *
+ * Spawns rev4a update as a detached background process.
+ * rev4a update installs the latest version and writes .restart-flag,
+ * which rev4a serve detects and exits with code 42, then auto-restarts
+ * with the newly installed binary. No systemd required.
+ */
+export async function POST(request: Request): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  if (!(await verifyAuth(request))) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  // Spawn rev4a update in background, then write restart flag directly
+  // from this process so rev4a serve detects it and restarts.
+  const { spawn } = require('child_process');
+  const { join } = require('path');
+  const { writeFileSync } = require('fs');
+
+  const dataDir = process.env.REV4A_DATA_DIR ||
+    join(process.env.HOME || '/root', '.config', 'rev4a', 'data');
+
+  const child = spawn('rev4a', ['update'], {
+    stdio: 'ignore',
+    detached: true,
+  });
+
+  // When rev4a update finishes, write the restart flag so rev4a serve
+  // picks it up and exits with code 42, triggering the auto-restart loop.
+  child.on('exit', () => {
+    try { writeFileSync(join(dataDir, '.restart-flag'), ''); } catch {}
+  });
+
+  child.unref();
+
+  return NextResponse.json({
+    success: true,
+    message: 'Update started. The dashboard will restart once complete.',
+  });
+}

package/app/api/version/route.ts

@@ -0,0 +1,25 @@
+import { type NextRequest } from "next/server";
+import { NextResponse } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+let pkg: { version: string } = { version: '0.0.0' };
+try {
+  pkg = require('../../../package.json');
+} catch {
+  /* fallback */
+}
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * GET /api/version
+ *
+ * Returns the installed Rev4a version from package.json.
+ * No auth required.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  return NextResponse.json({
+    version: pkg.version,
+  });
+}

package/app/api/wizard/complete/route.ts

@@ -0,0 +1,32 @@
+/**
+ * POST /api/wizard/complete
+ *
+ * Sets wizard as complete in a persistent file (cross-browser).
+ * Also sets the httpOnly cookie for backwards compatibility.
+ */
+import { NextResponse } from 'next/server';
+import * as fs from 'fs';
+import * as path from 'path';
+import { REV4A_DATA } from '@/lib/rev4a-paths';
+
+export const dynamic = 'force-dynamic';
+
+const WIZARD_FILE = REV4A_DATA + '/data/wizard.json';
+
+export function POST(): NextResponse {
+  // Write persistent marker
+  const dir = path.dirname(WIZARD_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(WIZARD_FILE, JSON.stringify({ done: true }, null, 2));
+
+  const response = NextResponse.json({ done: true });
+  // Also set cookie for backwards compat / existing clients
+  response.cookies.set('wizard_done', '1', {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: 60 * 60 * 24 * 365,
+    path: '/',
+  });
+  return response;
+}

package/app/api/wizard/reset/route.ts

@@ -0,0 +1,28 @@
+/**
+ * POST /api/wizard/reset
+ *
+ * Clears the wizard marker so the wizard runs again.
+ * Removes both the persistent file and the cookie.
+ */
+import { NextResponse } from 'next/server';
+import * as fs from 'fs';
+import { REV4A_DATA } from '@/lib/rev4a-paths';
+
+export const dynamic = 'force-dynamic';
+
+const WIZARD_FILE = REV4A_DATA + '/data/wizard.json';
+
+export function POST(): NextResponse {
+  // Remove persistent marker
+  try { fs.unlinkSync(WIZARD_FILE); } catch { /* ignore */ }
+
+  const response = NextResponse.json({ done: false });
+  response.cookies.set('wizard_done', '', {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    maxAge: 0,
+    path: '/',
+  });
+  return response;
+}

package/app/api/wizard/status/route.ts

@@ -0,0 +1,28 @@
+/**
+ * GET /api/wizard/status
+ *
+ * Returns whether the wizard is complete.
+ * Checks a persistent file so it survives browser changes and cache clears.
+ */
+import { NextResponse } from 'next/server';
+import * as fs from 'fs';
+import { REV4A_DATA } from '@/lib/rev4a-paths';
+
+export const dynamic = 'force-dynamic';
+
+const WIZARD_FILE = REV4A_DATA + '/data/wizard.json';
+
+function readWizardFile(): boolean {
+  try {
+    const raw = fs.readFileSync(WIZARD_FILE, 'utf-8');
+    const data = JSON.parse(raw);
+    return data.done === true;
+  } catch {
+    return false;
+  }
+}
+
+export function GET(): NextResponse {
+  const done = readWizardFile();
+  return NextResponse.json({ done });
+}