@realtimex/folio 0.1.2

package/.env.example

@@ -0,0 +1,20 @@
+# Frontend runtime
+VITE_SUPABASE_URL=
+VITE_SUPABASE_ANON_KEY=
+VITE_API_URL=http://localhost:3006
+
+# Local API runtime
+PORT=3006
+NODE_ENV=development
+DISABLE_AUTH=true
+
+# Optional .env fallback for local API (BYOK via setup UI is preferred)
+SUPABASE_URL=
+SUPABASE_ANON_KEY=
+SUPABASE_SERVICE_ROLE_KEY=
+
+# Security
+JWT_SECRET=dev-secret-change-in-production
+TOKEN_ENCRYPTION_KEY=
+
+# RealTimeX SDK settings are managed by RealTimeX Desktop

package/README.md

@@ -0,0 +1,63 @@
+# Folio
+
+Folio is an intelligent document processing and automation platform that acts as your personal AI-powered filing cabinet. Powered by advanced AI and Vision-Language Models, Folio ingests your documents, understands their content, and automatically organizes them according to your custom rules.
+
+If you deal with invoices, receipts, reports, or any unstructured documents, Folio handles the heavy lifting of reading, extracting, and routing your data where it belongs.
+
+## ✨ Key Features
+
+- **Intelligent Ingestion**: Simply drop in PDFs, images, or raw text. Folio automatically reads and extracts the context, using high-speed Vision-Language Models (VLMs) for images.
+- **Folio Policies**: Create powerful "If X, then Y" automation rules. Teach Folio to recognize specific types of documents and run actions automatically.
+- **Smart Auto-Renaming**: Say goodbye to messy file names like `scan_001.pdf`. Folio can intelligently suggest and automatically rename files based on their actual content (e.g., `2026-02-28_Amazon_Invoice.pdf`).
+- **Seamless Cloud Integrations**: 
+  - **Google Drive**: Automatically route and copy specific files into designated cloud folders.
+  - **Google Sheets**: Accurately extract tabular data (like expenses or ledger entries) and automatically append new rows directly to your spreadsheets.
+- **Semantic Search & AI Chat**: Stop hunting for files. Folio creates a dynamic semantic index (RAG) of your documents, allowing you to search by concept or chat directly with your entire document library.
+- **Transparency & Control**: Watch exactly what the AI is doing in real-time with the **LiveTerminal** trace logs. 
+
+## 🚀 Getting Started
+
+Folio is designed to be run locally on your machine while securely syncing data to your own designated cloud backend. 
+
+### Prerequisites
+- Node.js (v20+)
+- A [Supabase](https://supabase.com) account (for your dedicated database)
+
+### Installation
+
+1. **Launch the Setup Wizard:**
+   ```bash
+   npx @realtimex/folio@latest --port 5176
+   ```
+2. **Configure your Database:**
+   Follow the Setup Wizard in your browser. You can use **Zero-Config Cloud Provisioning** to automatically set up a secure Supabase project, or manually provide an existing Supabase URL and Key.
+3. **Connect your Integrations:**
+   Head to the **Configuration** tab in the Folio dashboard to connect your local LLM providers and authorize Google Drive/Sheets.
+
+## 🛠️ For Developers
+
+Folio is highly extensible and built on a robust, modern stack:
+- **Frontend**: React + Vite + Tailwind CSS
+- **Backend / API**: Local Express Runtime + RealTimeX SDK
+- **Database**: Remote Supabase (PostgreSQL + pgvector for RAG)
+- **Extensibility**: The Action Engine is modular, allowing easy creation of new plugin handlers.
+
+### Local Development
+
+To run the full stack locally for contribution:
+
+```bash
+# Install dependencies
+npm install
+
+# Start the local API backend
+npm run dev:api
+
+# Start the frontend dev server
+npm run dev
+```
+
+If you modify the database schema, apply migrations using:
+```bash
+npm run migrate
+```

package/api/server.ts

@@ -0,0 +1,130 @@
+import cors from "cors";
+import express from "express";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { config, validateConfig } from "./src/config/index.js";
+import { errorHandler } from "./src/middleware/errorHandler.js";
+import { apiRateLimit } from "./src/middleware/rateLimit.js";
+import routes from "./src/routes/index.js";
+import { SDKService } from "./src/services/SDKService.js";
+import { createLogger } from "./src/utils/logger.js";
+
+const logger = createLogger("Server");
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const configValidation = validateConfig();
+if (!configValidation.valid) {
+  logger.warn("Configuration warnings", { errors: configValidation.errors });
+}
+
+SDKService.initialize();
+
+const app = express();
+
+app.use((req, res, next) => {
+  res.setHeader("X-Content-Type-Options", "nosniff");
+  res.setHeader("X-Frame-Options", "DENY");
+  res.setHeader("X-XSS-Protection", "1; mode=block");
+  if (config.isProduction) {
+    res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+  }
+  next();
+});
+
+app.use(
+  cors({
+    origin: config.isProduction ? config.security.corsOrigins : true,
+    credentials: true,
+    methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization", "X-Supabase-Url", "X-Supabase-Anon-Key"]
+  })
+);
+
+app.use(express.json({ limit: "10mb" }));
+app.use(express.urlencoded({ extended: true, limit: "10mb" }));
+
+app.use((req, res, next) => {
+  const start = Date.now();
+  res.on("finish", () => {
+    const duration = Date.now() - start;
+    logger.debug(`${req.method} ${req.path}`, { status: res.statusCode, durationMs: duration });
+  });
+  next();
+});
+
+app.use("/api", apiRateLimit);
+app.use("/api", routes);
+
+function getDistPath() {
+  if (
+    process.env.ELECTRON_STATIC_PATH &&
+    existsSync(path.join(process.env.ELECTRON_STATIC_PATH, "index.html"))
+  ) {
+    return process.env.ELECTRON_STATIC_PATH;
+  }
+
+  const fromRoot = path.join(config.rootDir || process.cwd(), "dist");
+  if (existsSync(path.join(fromRoot, "index.html"))) {
+    return fromRoot;
+  }
+
+  let current = __dirname;
+  for (let i = 0; i < 4; i += 1) {
+    const candidate = path.join(current, "dist");
+    if (existsSync(path.join(candidate, "index.html"))) {
+      return candidate;
+    }
+    current = path.dirname(current);
+  }
+
+  return fromRoot;
+}
+
+const distUiPath = getDistPath();
+if (existsSync(path.join(distUiPath, "index.html"))) {
+  logger.info("Serving static UI", { distUiPath });
+  app.use(express.static(distUiPath));
+
+  app.get(/.*/, (req, res, next) => {
+    if (req.path.startsWith("/api")) {
+      return next();
+    }
+
+    res.sendFile(path.join(distUiPath, "index.html"), (error) => {
+      if (error) {
+        res.status(404).json({
+          success: false,
+          error: {
+            code: "NOT_FOUND",
+            message: "Frontend not built or route not found"
+          }
+        });
+      }
+    });
+  });
+} else {
+  logger.warn("No dist/index.html found. API will run without bundled UI.", { distUiPath });
+}
+
+app.use(errorHandler);
+
+const server = app.listen(config.port, () => {
+  logger.info("Folio API started", {
+    port: config.port,
+    environment: config.nodeEnv,
+    packageRoot: config.packageRoot
+  });
+});
+
+function shutdown(signal: string) {
+  logger.info(`Shutting down (${signal})`);
+  server.close(() => {
+    process.exit(0);
+  });
+}
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));

package/api/src/config/index.ts

@@ -0,0 +1,96 @@
+import dotenv from "dotenv";
+import { existsSync } from "node:fs";
+import path, { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function findPackageRoot(startDir: string): string {
+  let current = startDir;
+  while (current !== path.parse(current).root) {
+    if (existsSync(join(current, "package.json")) && existsSync(join(current, "bin"))) {
+      return current;
+    }
+    current = dirname(current);
+  }
+  return process.cwd();
+}
+
+const packageRoot = findPackageRoot(__dirname);
+
+function loadEnvironment() {
+  const cwdEnv = join(process.cwd(), ".env");
+  const rootEnv = join(packageRoot, ".env");
+
+  if (existsSync(cwdEnv)) {
+    dotenv.config({ path: cwdEnv, override: true });
+  } else if (existsSync(rootEnv)) {
+    dotenv.config({ path: rootEnv, override: true });
+  } else {
+    dotenv.config();
+  }
+}
+
+loadEnvironment();
+
+function parseArgs(args: string[]): { port: number | null; noUi: boolean } {
+  const portIndex = args.indexOf("--port");
+  let port: number | null = null;
+
+  if (portIndex !== -1 && args[portIndex + 1]) {
+    const candidate = Number.parseInt(args[portIndex + 1], 10);
+    if (!Number.isNaN(candidate) && candidate > 0 && candidate < 65536) {
+      port = candidate;
+    }
+  }
+
+  return {
+    port,
+    noUi: args.includes("--no-ui")
+  };
+}
+
+const cliArgs = parseArgs(process.argv.slice(2));
+
+export const config = {
+  packageRoot,
+  port: cliArgs.port || (process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3006),
+  noUi: cliArgs.noUi,
+  nodeEnv: process.env.NODE_ENV || "development",
+  isProduction: process.env.NODE_ENV === "production",
+  rootDir: packageRoot,
+  scriptsDir: join(packageRoot, "scripts"),
+
+  supabase: {
+    url: process.env.SUPABASE_URL || process.env.VITE_SUPABASE_URL || "",
+    anonKey: process.env.SUPABASE_ANON_KEY || process.env.VITE_SUPABASE_ANON_KEY || "",
+    serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY || ""
+  },
+
+  security: {
+    jwtSecret: process.env.JWT_SECRET || "dev-secret-change-in-production",
+    encryptionKey: process.env.TOKEN_ENCRYPTION_KEY || "",
+    corsOrigins: process.env.CORS_ORIGINS?.split(",") || ["http://localhost:5173", "http://localhost:3006"],
+    rateLimitWindowMs: 60 * 1000,
+    rateLimitMax: 60,
+    disableAuth: process.env.DISABLE_AUTH === "true"
+  }
+};
+
+export function validateConfig(): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (config.isProduction && config.security.jwtSecret === "dev-secret-change-in-production") {
+    errors.push("JWT_SECRET must be set in production");
+  }
+
+  if (config.isProduction && !config.security.encryptionKey) {
+    errors.push("TOKEN_ENCRYPTION_KEY must be set in production");
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}

package/api/src/middleware/auth.ts

@@ -0,0 +1,128 @@
+import { createClient, SupabaseClient, User } from "@supabase/supabase-js";
+import { NextFunction, Request, Response } from "express";
+
+import { config } from "../config/index.js";
+import { getServerSupabase, getSupabaseConfigFromHeaders } from "../services/supabase.js";
+import { Logger, createLogger } from "../utils/logger.js";
+import { AuthenticationError, AuthorizationError } from "./errorHandler.js";
+
+const logger = createLogger("AuthMiddleware");
+
+declare global {
+  namespace Express {
+    interface Request {
+      user?: User;
+      supabase?: SupabaseClient;
+    }
+  }
+}
+
+function resolveSupabaseConfig(req: Request): { url: string; anonKey: string } | null {
+  const headerConfig = getSupabaseConfigFromHeaders(req.headers as Record<string, unknown>);
+
+  const envUrl = config.supabase.url;
+  const envKey = config.supabase.anonKey;
+
+  const envIsValid = envUrl.startsWith("http://") || envUrl.startsWith("https://");
+  if (envIsValid && envKey) {
+    return { url: envUrl, anonKey: envKey };
+  }
+
+  return headerConfig;
+}
+
+export async function authMiddleware(req: Request, _res: Response, next: NextFunction): Promise<void> {
+  try {
+    const supabaseConfig = resolveSupabaseConfig(req);
+
+    if (!supabaseConfig) {
+      throw new AuthenticationError("Supabase not configured");
+    }
+
+    if (config.security.disableAuth && !config.isProduction) {
+      const user = {
+        id: "00000000-0000-0000-0000-000000000000",
+        email: "dev@folio.local",
+        user_metadata: {},
+        app_metadata: {},
+        aud: "authenticated",
+        created_at: new Date().toISOString()
+      } as User;
+
+      const supabase =
+        getServerSupabase() ||
+        createClient(supabaseConfig.url, supabaseConfig.anonKey, {
+          auth: {
+            autoRefreshToken: false,
+            persistSession: false
+          }
+        });
+
+      req.user = user;
+      req.supabase = supabase;
+      Logger.setPersistence(supabase, user.id);
+      return next();
+    }
+
+    const authHeader = req.headers.authorization;
+    if (!authHeader?.startsWith("Bearer ")) {
+      throw new AuthenticationError("Missing bearer token");
+    }
+
+    const token = authHeader.slice(7);
+
+    const supabase = createClient(supabaseConfig.url, supabaseConfig.anonKey, {
+      global: {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      }
+    });
+
+    const {
+      data: { user },
+      error
+    } = await supabase.auth.getUser(token);
+
+    if (error || !user) {
+      throw new AuthenticationError("Invalid or expired token");
+    }
+
+    req.user = user;
+    req.supabase = supabase;
+    Logger.setPersistence(supabase, user.id);
+    next();
+  } catch (error) {
+    logger.error("Auth middleware error", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    next(error);
+  }
+}
+
+export function optionalAuth(req: Request, res: Response, next: NextFunction): void {
+  const authHeader = req.headers.authorization;
+  if (!authHeader?.startsWith("Bearer ")) {
+    next();
+    return;
+  }
+
+  void authMiddleware(req, res, next);
+}
+
+export function requireRole(roles: string[]) {
+  return (req: Request, _res: Response, next: NextFunction) => {
+    if (!req.user) {
+      next(new AuthenticationError());
+      return;
+    }
+
+    const role = req.user.user_metadata?.role || "user";
+    if (!roles.includes(role)) {
+      next(new AuthorizationError(`Requires one of: ${roles.join(", ")}`));
+      return;
+    }
+
+    next();
+  };
+}

package/api/src/middleware/errorHandler.ts

@@ -0,0 +1,88 @@
+import { NextFunction, Request, Response } from "express";
+
+import { config } from "../config/index.js";
+import { createLogger } from "../utils/logger.js";
+
+const logger = createLogger("ErrorHandler");
+
+export class AppError extends Error {
+  statusCode: number;
+  isOperational: boolean;
+  code?: string;
+
+  constructor(message: string, statusCode = 500, code?: string) {
+    super(message);
+    this.statusCode = statusCode;
+    this.isOperational = true;
+    this.code = code;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string) {
+    super(message, 400, "VALIDATION_ERROR");
+  }
+}
+
+export class AuthenticationError extends AppError {
+  constructor(message = "Authentication required") {
+    super(message, 401, "AUTHENTICATION_ERROR");
+  }
+}
+
+export class AuthorizationError extends AppError {
+  constructor(message = "Insufficient permissions") {
+    super(message, 403, "AUTHORIZATION_ERROR");
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource = "Resource") {
+    super(`${resource} not found`, 404, "NOT_FOUND");
+  }
+}
+
+export class RateLimitError extends AppError {
+  constructor() {
+    super("Too many requests", 429, "RATE_LIMIT_EXCEEDED");
+  }
+}
+
+export function errorHandler(err: Error | AppError, req: Request, res: Response, _next: NextFunction): void {
+  const statusCode = err instanceof AppError ? err.statusCode : 500;
+  const code = err instanceof AppError ? err.code : "INTERNAL_ERROR";
+
+  if (statusCode >= 500) {
+    logger.error("Server error", {
+      method: req.method,
+      path: req.path,
+      statusCode,
+      message: err.message
+    });
+  } else {
+    logger.warn("Client error", {
+      method: req.method,
+      path: req.path,
+      statusCode,
+      message: err.message
+    });
+  }
+
+  res.status(statusCode).json({
+    success: false,
+    error: {
+      code,
+      message: !config.isProduction ? err.message : statusCode >= 500 ? "Unexpected error" : err.message,
+      ...(config.isProduction ? {} : { stack: err.stack })
+    }
+  });
+}
+
+export function asyncHandler(
+  fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>
+) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}

package/api/src/middleware/index.ts

@@ -0,0 +1,4 @@
+export * from "./auth.js";
+export * from "./errorHandler.js";
+export * from "./rateLimit.js";
+export * from "./validation.js";

package/api/src/middleware/rateLimit.ts

@@ -0,0 +1,71 @@
+import { NextFunction, Request, Response } from "express";
+
+import { config } from "../config/index.js";
+import { RateLimitError } from "./errorHandler.js";
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+const rateLimitStore = new Map<string, RateLimitEntry>();
+
+setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of rateLimitStore.entries()) {
+    if (entry.resetAt < now) {
+      rateLimitStore.delete(key);
+    }
+  }
+}, 60_000);
+
+export interface RateLimitOptions {
+  windowMs?: number;
+  max?: number;
+  keyGenerator?: (req: Request) => string;
+  skip?: (req: Request) => boolean;
+}
+
+export function rateLimit(options: RateLimitOptions = {}) {
+  const {
+    windowMs = config.security.rateLimitWindowMs,
+    max = config.security.rateLimitMax,
+    keyGenerator = (req) => req.ip || String(req.headers["x-forwarded-for"] || "unknown"),
+    skip = () => false
+  } = options;
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (skip(req)) {
+      return next();
+    }
+
+    const key = keyGenerator(req);
+    const now = Date.now();
+    let entry = rateLimitStore.get(key);
+
+    if (!entry || entry.resetAt < now) {
+      entry = {
+        count: 1,
+        resetAt: now + windowMs
+      };
+      rateLimitStore.set(key, entry);
+    } else {
+      entry.count += 1;
+    }
+
+    res.setHeader("X-RateLimit-Limit", max);
+    res.setHeader("X-RateLimit-Remaining", Math.max(0, max - entry.count));
+    res.setHeader("X-RateLimit-Reset", Math.ceil(entry.resetAt / 1000));
+
+    if (entry.count > max) {
+      return next(new RateLimitError());
+    }
+
+    next();
+  };
+}
+
+export const apiRateLimit = rateLimit({
+  windowMs: 60_000,
+  max: 60
+});

package/api/src/middleware/validation.ts

@@ -0,0 +1,58 @@
+import { NextFunction, Request, Response } from "express";
+import { z, ZodError, ZodSchema } from "zod";
+
+import { ValidationError } from "./errorHandler.js";
+
+export function validateBody<T>(schema: ZodSchema<T>) {
+  return (req: Request, _res: Response, next: NextFunction): void => {
+    try {
+      req.body = schema.parse(req.body);
+      next();
+    } catch (error) {
+      if (error instanceof ZodError) {
+        const message = error.errors.map((item) => `${item.path.join(".")}: ${item.message}`).join(", ");
+        next(new ValidationError(message));
+        return;
+      }
+      next(error);
+    }
+  };
+}
+
+export function validateQuery<T>(schema: ZodSchema<T>) {
+  return (req: Request, _res: Response, next: NextFunction): void => {
+    try {
+      req.query = schema.parse(req.query) as Request["query"];
+      next();
+    } catch (error) {
+      if (error instanceof ZodError) {
+        const message = error.errors.map((item) => `${item.path.join(".")}: ${item.message}`).join(", ");
+        next(new ValidationError(message));
+        return;
+      }
+      next(error);
+    }
+  };
+}
+
+export const schemas = {
+  testSupabase: z.object({
+    url: z.string().url(),
+    anonKey: z.string().min(10)
+  }),
+  autoProvision: z.object({
+    orgId: z.string().min(1),
+    projectName: z.string().min(1).max(64).optional(),
+    region: z.string().min(1).max(64).optional()
+  }),
+  migrate: z.object({
+    projectRef: z.string().min(1),
+    accessToken: z.string().min(1),
+    anonKey: z.string().min(1).optional()
+  }),
+
+  dispatchProcessing: z.object({
+    source_type: z.string().min(1),
+    payload: z.record(z.unknown())
+  })
+};