mojulo 0.0.0 → 0.1.1

package/lib/deployers/fly.js

@@ -0,0 +1,432 @@
+/**
+ * Fly.io Machines API deployer.
+ *
+ * Deploys the published GHCR bot image (ghcr.io/zombico/mojulo-bot) to a
+ * user-owned Fly app using their API token. Per-bot config is injected via
+ * the Machines API `files` field — the image stays bot-agnostic.
+ *
+ * Patterns enforced (see lite-template/integration/CLOUD_DEPLOY_GUIDE.md):
+ *   - Pattern 1: One image, config injected per machine via base64 files[].
+ *   - Pattern 2: Volume named "data", find-or-create idempotent, always
+ *                re-attached on update.
+ *   - Pattern 3: Deterministic app name = ${md5(userId).slice(0,8)}-${botName}.
+ *   - Pattern 4: Lifecycle ops are thin platform mappings.
+ *   - Pattern 5: deploy() accepts an onProgress callback for audit-trail
+ *                events; the lifecycle wrapper persists them.
+ *
+ * Credentials are passed by constructor parameter — never read globally —
+ * so future per-user token storage drops in without changing this file.
+ */
+
+import crypto from 'crypto';
+
+const FLY_API_BASE = 'https://api.machines.dev/v1';
+
+const DEFAULT_GUEST = { cpu_kind: 'shared', cpus: 1, memory_mb: 1024 };
+const DEFAULT_REGION = 'iad';
+const DEFAULT_VOLUME_GB = 1;
+
+// Fly's max app-name length; computeAppName truncates to this.
+const FLY_APP_NAME_MAX_LENGTH = 63;
+// Port the bot's Express server listens on inside the container (matches lite-template/server.js).
+const BOT_INTERNAL_PORT = 3000;
+// Healthcheck cadence injected into the Fly machine config.
+const HEALTHCHECK_CONFIG = {
+  interval: '15s',
+  timeout: '5s',
+  grace_period: '20s',
+};
+
+export class FlyDeployer {
+  constructor({
+    apiToken,
+    orgSlug = 'personal',
+    image,
+    defaultRegion = DEFAULT_REGION,
+    defaultGuest = DEFAULT_GUEST,
+    defaultVolumeGb = DEFAULT_VOLUME_GB,
+  } = {}) {
+    if (!apiToken) {
+      throw new Error('FlyDeployer requires apiToken');
+    }
+    this.apiToken = apiToken;
+    this.orgSlug = orgSlug;
+    // Cloud always wants a public registry pin. In the common case BOT_IMAGE
+    // already points at GHCR, so fall back to it. Set MOJULO_CLOUD_IMAGE only
+    // when the cloud tag needs to diverge from the local docker-compose tag
+    // (e.g. BOT_IMAGE is a laptop tag like `mojulo/bot:latest`). The registry
+    // check below catches that case regardless of which env var supplied it.
+    this.image =
+      image ||
+      process.env.MOJULO_CLOUD_IMAGE ||
+      process.env.BOT_IMAGE;
+    if (!this.image || !this.image.includes('/')) {
+      throw new Error(
+        `Cloud image "${this.image}" has no registry prefix; Fly will route it through Docker Hub. ` +
+          `Set MOJULO_CLOUD_IMAGE or BOT_IMAGE to a fully-qualified image like ghcr.io/owner/name:tag.`
+      );
+    }
+    this.defaultRegion = defaultRegion;
+    this.defaultGuest = defaultGuest;
+    this.defaultVolumeGb = defaultVolumeGb;
+  }
+
+  /**
+   * Deterministic app name from user identity + bot name. Same inputs always
+   * yield the same name, which makes deploys self-healing: lose the
+   * control-plane row, redeploy, and you find the existing app + volume.
+   */
+  static computeAppName({ userId = 'local', botName }) {
+    if (!botName) throw new Error('computeAppName requires botName');
+    const userHash = crypto
+      .createHash('md5')
+      .update(String(userId))
+      .digest('hex')
+      .substring(0, 8);
+    return `${userHash}-${botName}`
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/(^-|-$)/g, '')
+      .slice(0, FLY_APP_NAME_MAX_LENGTH);
+  }
+
+  async _request(pathSuffix, options = {}) {
+    const res = await fetch(`${FLY_API_BASE}${pathSuffix}`, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${this.apiToken}`,
+        'Content-Type': 'application/json',
+        ...(options.headers || {}),
+      },
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      const err = new Error(`Fly API ${res.status} ${pathSuffix}: ${text}`);
+      err.status = res.status;
+      err.body = text;
+      throw err;
+    }
+    return text ? JSON.parse(text) : null;
+  }
+
+  /**
+   * Provision (or update) a bot. Idempotent against an existing app + volume
+   * keyed by `appName`.
+   *
+   * @param {Object} params
+   * @param {string} params.appName       Deterministic app name (use computeAppName)
+   * @param {Array}  params.configFiles   [{ guestPath, contents }] — written into the container at machine create
+   * @param {Object} params.env           Env vars for the bot process (LLM key, MOJULO_API_KEY, DOCKER_RUN, etc.)
+   * @param {string} [params.region]
+   * @param {Object} [params.guest]       cpu_kind, cpus, memory_mb
+   * @param {number} [params.volumeGb]
+   * @param {Function} [params.onProgress] called with { step, message } per lifecycle event
+   */
+  async deploy(params) {
+    const {
+      appName,
+      configFiles = [],
+      env = {},
+      region = this.defaultRegion,
+      guest = this.defaultGuest,
+      volumeGb = this.defaultVolumeGb,
+      onProgress = () => {},
+    } = params;
+
+    if (!appName) throw new Error('deploy requires appName');
+
+    onProgress({ step: 'app', message: `Ensuring Fly app ${appName} exists` });
+    await this._ensureApp(appName);
+
+    onProgress({ step: 'ips', message: `Ensuring public IPs for ${appName}` });
+    await this._ensureIps(appName);
+
+    onProgress({ step: 'volume', message: `Ensuring data volume in ${region}` });
+    const volumeId = await this._ensureVolume(appName, region, volumeGb);
+
+    onProgress({ step: 'machine_config', message: 'Building machine config' });
+    const machineConfig = this._buildMachineConfig({
+      env,
+      configFiles,
+      volumeId,
+      guest,
+    });
+
+    onProgress({ step: 'machine', message: 'Creating or updating machine' });
+    const machine = await this._ensureMachine(appName, region, machineConfig);
+
+    onProgress({ step: 'wait', message: 'Waiting for machine to start' });
+    await this._waitForStart(appName, machine.id).catch((err) => {
+      // Healthcheck/start timeout is informational, not fatal — the machine
+      // may still come healthy moments later. Surface as a progress event
+      // and let the caller poll status.
+      onProgress({ step: 'wait_timeout', message: err.message });
+    });
+
+    const url = `https://${appName}.fly.dev`;
+    onProgress({ step: 'complete', message: `Deployed at ${url}` });
+
+    return { appName, url, machineId: machine.id, volumeId };
+  }
+
+  async _ensureApp(appName) {
+    try {
+      await this._request('/apps', {
+        method: 'POST',
+        body: JSON.stringify({ app_name: appName, org_slug: this.orgSlug }),
+      });
+    } catch (err) {
+      const body = err.body || err.message || '';
+      if (
+        err.status === 422 ||
+        /already (exists|been taken|taken)/i.test(body) ||
+        /name has already/i.test(body)
+      ) {
+        // App from a prior deploy — fall through and reuse.
+        return;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Allocate shared_v4 + v6 IPs if missing. Without this, the *.fly.dev
+   * hostname has no DNS records and external requests can never reach the
+   * app — the machine starts fine, health checks pass on Fly's internal
+   * network, but autostart-on-request never fires because nothing routes in.
+   *
+   * The Machines REST API can list IPs, but allocation has historically
+   * required GraphQL (see CLOUD_DEPLOY_GUIDE.md "GraphQL IP allocation").
+   * Same Bearer token works for both endpoints.
+   */
+  async _ensureIps(appName) {
+    let existing = [];
+    try {
+      existing = (await this._request(`/apps/${appName}/ips`)) || [];
+    } catch (err) {
+      if (err.status !== 404) throw err;
+    }
+    const hasV4 = existing.some((ip) =>
+      ['shared_v4', 'v4'].includes(ip.type)
+    );
+    const hasV6 = existing.some((ip) => ip.type === 'v6');
+
+    if (!hasV4) await this._allocateIp(appName, 'shared_v4');
+    if (!hasV6) await this._allocateIp(appName, 'v6');
+  }
+
+  async _allocateIp(appName, type) {
+    const query = `
+      mutation($input: AllocateIPAddressInput!) {
+        allocateIpAddress(input: $input) {
+          ipAddress { address type }
+        }
+      }
+    `;
+    const res = await fetch('https://api.fly.io/graphql', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        query,
+        variables: { input: { appId: appName, type } },
+      }),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(
+        `Fly GraphQL ${res.status} allocateIpAddress(${type}): ${text}`
+      );
+    }
+    const data = JSON.parse(text);
+    if (data.errors && data.errors.length) {
+      const msg = data.errors[0].message || '';
+      // Race: another deploy raced us and already allocated this type.
+      if (/already/i.test(msg)) return;
+      throw new Error(`Fly GraphQL allocateIpAddress(${type}): ${msg}`);
+    }
+  }
+
+  async _ensureVolume(appName, region, sizeGb) {
+    // The Fly Machines API does NOT enforce volume-name uniqueness — POSTing
+    // a second volume with name "data" silently creates a second volume,
+    // which orphans the first. List-first is the only correct approach.
+    const volumes = await this._request(`/apps/${appName}/volumes`).catch(
+      (err) => {
+        if (err.status === 404) return [];
+        throw err;
+      }
+    );
+    const existing = (volumes || []).find(
+      (v) => v.name === 'data' && v.state !== 'destroyed'
+    );
+    if (existing) return existing.id;
+
+    const vol = await this._request(`/apps/${appName}/volumes`, {
+      method: 'POST',
+      body: JSON.stringify({ name: 'data', size_gb: sizeGb, region }),
+    });
+    return vol.id;
+  }
+
+  _buildMachineConfig({ env, configFiles, volumeId, guest }) {
+    const files = configFiles.map((f) => ({
+      guest_path: f.guestPath,
+      raw_value: Buffer.from(f.contents).toString('base64'),
+    }));
+
+    const config = {
+      image: this.image,
+      env: { DOCKER_RUN: 'true', ...env },
+      files,
+      services: [
+        {
+          ports: [
+            { port: 80, handlers: ['http'], force_https: true },
+            { port: 443, handlers: ['tls', 'http'] },
+          ],
+          protocol: 'tcp',
+          internal_port: BOT_INTERNAL_PORT,
+          autostart: true,
+          autostop: 'stop',
+        },
+      ],
+      checks: {
+        httpget: {
+          type: 'http',
+          port: BOT_INTERNAL_PORT,
+          path: '/health',
+          ...HEALTHCHECK_CONFIG,
+        },
+      },
+      guest,
+      restart: { policy: 'on-failure', max_retries: 3 },
+    };
+
+    // Always include mounts last so that any future merge operations on this
+    // object don't clobber the volume attach (failure mode #5 in the
+    // cloud-deploy guide).
+    if (volumeId) {
+      config.mounts = [{ volume: volumeId, path: '/data' }];
+    }
+
+    return config;
+  }
+
+  async _ensureMachine(appName, region, machineConfig) {
+    let existing = [];
+    try {
+      existing = (await this._request(`/apps/${appName}/machines`)) || [];
+    } catch (err) {
+      if (err.status !== 404) throw err;
+    }
+
+    if (existing.length > 0) {
+      const machine = existing[0];
+      // Update path: re-send the full config including the mounts array.
+      // Fly's machines API does not merge mounts — omitting them detaches
+      // the volume.
+      await this._request(`/apps/${appName}/machines/${machine.id}`, {
+        method: 'POST',
+        body: JSON.stringify({ region, config: machineConfig }),
+      });
+      return machine;
+    }
+
+    return this._request(`/apps/${appName}/machines`, {
+      method: 'POST',
+      body: JSON.stringify({ region, config: machineConfig }),
+    });
+  }
+
+  async _waitForStart(appName, machineId, timeoutSeconds = 60) {
+    return this._request(
+      `/apps/${appName}/machines/${machineId}/wait?state=started&timeout=${timeoutSeconds}`
+    );
+  }
+
+  /**
+   * Stop all machines but keep volume + app. Reversible via resume().
+   */
+  async pause(appName) {
+    const machines = await this._listMachines(appName);
+    for (const m of machines) {
+      if (m.state !== 'stopped') {
+        await this._request(`/apps/${appName}/machines/${m.id}/stop`, {
+          method: 'POST',
+        }).catch(() => {});
+      }
+    }
+    return { ok: true, paused: machines.length };
+  }
+
+  async resume(appName) {
+    const machines = await this._listMachines(appName);
+    for (const m of machines) {
+      if (m.state === 'stopped') {
+        await this._request(`/apps/${appName}/machines/${m.id}/start`, {
+          method: 'POST',
+        }).catch(() => {});
+      }
+    }
+    return { ok: true, resumed: machines.length };
+  }
+
+  /**
+   * Stop + delete every machine, then delete the app. App deletion cascades
+   * to volume + IPs on Fly. Use `force=true` on machine delete to avoid
+   * hangs when a machine is in a transitional state.
+   */
+  async destroy(appName) {
+    const machines = await this._listMachines(appName);
+    for (const m of machines) {
+      await this._request(`/apps/${appName}/machines/${m.id}/stop`, {
+        method: 'POST',
+      }).catch(() => {});
+      await this._request(`/apps/${appName}/machines/${m.id}?force=true`, {
+        method: 'DELETE',
+      }).catch(() => {});
+    }
+    await this._request(`/apps/${appName}`, { method: 'DELETE' }).catch(
+      (err) => {
+        if (err.status !== 404) throw err;
+      }
+    );
+    return { ok: true };
+  }
+
+  async getStatus(appName) {
+    let machines;
+    try {
+      machines = await this._listMachines(appName);
+    } catch (err) {
+      if (err.status === 404) return { status: 'not_found' };
+      throw err;
+    }
+    if (!machines.length) return { status: 'not_found' };
+
+    const states = machines.map((m) => m.state);
+    const allStarted = states.every((s) => s === 'started');
+    const allStopped = states.every((s) => s === 'stopped');
+    const status = allStarted ? 'running' : allStopped ? 'stopped' : 'mixed';
+    return {
+      status,
+      url: `https://${appName}.fly.dev`,
+      machines: machines.length,
+      states,
+    };
+  }
+
+  async _listMachines(appName) {
+    try {
+      const machines = await this._request(`/apps/${appName}/machines`);
+      return machines || [];
+    } catch (err) {
+      if (err.status === 404) return [];
+      throw err;
+    }
+  }
+}

package/lib/deployers/index.js

@@ -0,0 +1,38 @@
+import { DockerDeployer } from './docker.js';
+import { FlyDeployer } from './fly.js';
+
+let _deployer = null;
+
+export async function getDeploymentProvider() {
+  if (!_deployer) _deployer = new DockerDeployer();
+  return _deployer;
+}
+
+export async function deploy(params) {
+  const provider = await getDeploymentProvider();
+  return provider.deploy(params);
+}
+
+export async function destroy(appId) {
+  const provider = await getDeploymentProvider();
+  return provider.destroy(appId);
+}
+
+/**
+ * Construct a cloud deployer instance per-call. Cloud deployers are
+ * stateless aside from credentials, so there's no caching layer — the
+ * caller passes the user's token in.
+ *
+ * Currently registered: 'fly'. Add new providers here.
+ */
+export function getCloudDeployer(provider, credentials = {}) {
+  if (provider === 'fly') {
+    return new FlyDeployer({
+      apiToken: credentials.flyApiToken || process.env.FLY_API_TOKEN,
+      orgSlug: credentials.flyOrgSlug || process.env.FLY_ORG_SLUG || 'personal',
+    });
+  }
+  throw new Error(`Unknown cloud provider: ${provider}`);
+}
+
+export const CLOUD_PROVIDERS = ['fly'];

package/lib/deployment-auth.js

@@ -0,0 +1,36 @@
+import crypto from 'crypto';
+
+// Lite encrypts the stored LLM API key with a key derived from the host.
+// In production deployments users set API_KEY_ENCRYPTION_KEY; otherwise a
+// stable machine-derived key keeps round-trips working for local dev.
+function getEncryptionKey() {
+  const envKey = process.env.API_KEY_ENCRYPTION_KEY;
+  if (envKey) {
+    return crypto.createHash('sha256').update(envKey).digest();
+  }
+  return crypto.createHash('sha256').update('mojulo-lite-local-dev').digest();
+}
+
+const ALGO = 'aes-256-gcm';
+
+export function encryptApiKey(plaintext) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(ALGO, getEncryptionKey(), iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, ciphertext]).toString('base64');
+}
+
+export function decryptApiKey(encrypted) {
+  const data = Buffer.from(encrypted, 'base64');
+  const iv = data.subarray(0, 12);
+  const tag = data.subarray(12, 28);
+  const ciphertext = data.subarray(28);
+  const decipher = crypto.createDecipheriv(ALGO, getEncryptionKey(), iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}
+
+export function generateApiKey() {
+  return `bot_${crypto.randomBytes(24).toString('hex')}`;
+}

package/lib/document-parser.js

@@ -0,0 +1,171 @@
+/**
+ * Document Parser Utility
+ * Handles parsing of various document types
+ * - PDFs: Uses pdf2json (Node.js native, no browser APIs)
+ * - DOCX/PPTX/XLSX: Uses officeparser
+ */
+
+const PDFParser = require('pdf2json');
+const officeParser = require('officeparser');
+const { writeFile, unlink } = require('fs/promises');
+const { join } = require('path');
+const { tmpdir } = require('os');
+
+/**
+ * Parse PDF using pdf2json (Node.js native parser)
+ * @param {Buffer} buffer - PDF file buffer
+ * @returns {Promise<string>} Extracted text
+ */
+async function parsePDF(buffer) {
+  return new Promise((resolve, reject) => {
+    const pdfParser = new PDFParser();
+
+    pdfParser.on('pdfParser_dataError', (errData) => {
+      reject(new Error(errData.parserError));
+    });
+
+    pdfParser.on('pdfParser_dataReady', (pdfData) => {
+      try {
+        // Try getRawTextContent() first
+        let text = pdfParser.getRawTextContent();
+
+        console.log('PDF text length:', text ? text.length : 0);
+        console.log('PDF text sample:', text ? text.substring(0, 200) : 'empty');
+
+        // If getRawTextContent() returns empty, try alternative extraction
+        if (!text || text.trim().length === 0) {
+          console.log('Trying alternative text extraction from pdfData');
+          // Extract text from pages manually
+          const pages = pdfData?.Pages || [];
+          const textParts = [];
+
+          for (const page of pages) {
+            const texts = page?.Texts || [];
+            for (const textItem of texts) {
+              try {
+                const encodedText = textItem?.R?.[0]?.T || '';
+                const decodedText = encodedText ? decodeURIComponent(encodedText) : '';
+                if (decodedText) {
+                  textParts.push(decodedText);
+                }
+              } catch (decodeError) {
+                // If decoding fails, use the raw text
+                const rawText = textItem?.R?.[0]?.T || '';
+                if (rawText) {
+                  textParts.push(rawText);
+                }
+              }
+            }
+          }
+
+          text = textParts.join(' ');
+          console.log('Alternative extraction length:', text.length);
+        }
+
+        resolve(text);
+      } catch (error) {
+        reject(error);
+      }
+    });
+
+    // Parse the buffer
+    pdfParser.parseBuffer(buffer);
+  });
+}
+
+/**
+ * Parse Office documents using officeparser (requires file path)
+ * @param {Buffer} buffer - File buffer
+ * @param {string} fileName - Original file name
+ * @returns {Promise<string>} Extracted text
+ */
+async function parseOfficeDocument(buffer, fileName) {
+  const tempFilePath = join(tmpdir(), `temp-${Date.now()}-${fileName}`);
+
+  try {
+    await writeFile(tempFilePath, buffer);
+    const extractedText = await officeParser.parseOfficeAsync(tempFilePath);
+    return extractedText;
+  } finally {
+    try {
+      await unlink(tempFilePath);
+    } catch (unlinkError) {
+      console.warn(`Failed to delete temp file ${tempFilePath}:`, unlinkError);
+    }
+  }
+}
+
+/**
+ * Repair PDFs whose text extraction produced character-positioned output
+ * (every character separated by whitespace), turning "P l a n d ' a s s u r"
+ * back into "Plan d'assurance". Common with PDFs exported from Google Docs
+ * and other tools that embed custom font subsets pdf2json can't decode.
+ *
+ * Heuristic: if >50% of whitespace-split tokens in a 4KB sample are length
+ * 1, the parse is broken. Threshold is conservative — healthy English/French
+ * prose runs ~0-30% single-char tokens (only "I", "a", "à", "y") so the
+ * normalizer is a no-op on well-parsed docs.
+ *
+ * Word-boundary rule: 3+ consecutive spaces (or any newline) marks a real
+ * word break. 1-2 spaces inside a "word" are PDF-positioning artifacts and
+ * get stripped. Edge cases like "A u t o  C  a r e" → "AutoCare" recover
+ * because the intra-word gap stays under 3 spaces.
+ *
+ * Limitation: tight pseudo-ligatures with extra positioning around capitals
+ * (e.g. "L   L   C" with 3-space gaps inside the acronym) reconstruct as
+ * "L L C" — searchable but not pixel-perfect. Acceptable trade-off vs the
+ * unsearchable status quo.
+ */
+function normalizeCharacterSpacing(text) {
+  const sample = text.slice(0, 4000);
+  const sampleTokens = sample.split(/\s+/).filter(Boolean);
+  if (sampleTokens.length < 20) return text;
+
+  const singleCharRatio =
+    sampleTokens.filter((t) => t.length === 1).length / sampleTokens.length;
+  if (singleCharRatio < 0.5) return text;
+
+  console.log(
+    `Detected character-positioned PDF text (${(singleCharRatio * 100).toFixed(0)}% single-char tokens) — normalizing.`
+  );
+
+  return text
+    .split(/[ \t]{3,}|\r?\n+/)
+    .map((w) => w.replace(/\s+/g, ''))
+    .filter(Boolean)
+    .join(' ');
+}
+
+/**
+ * Parse document by writing to temp file first
+ * @param {Buffer} buffer - File buffer
+ * @param {string} fileName - Original file name
+ * @returns {Promise<string>} Extracted text
+ */
+async function parseDocument(buffer, fileName) {
+  try {
+    const fileExtension = fileName.toLowerCase().split('.').pop();
+
+    let extractedText;
+
+    // Use pdf-parse for PDFs (no worker issues)
+    if (fileExtension === 'pdf') {
+      extractedText = await parsePDF(buffer);
+    }
+    // Use officeparser for other document types
+    else {
+      extractedText = await parseOfficeDocument(buffer, fileName);
+    }
+
+    if (!extractedText || extractedText.trim().length === 0) {
+      throw new Error(`No text extracted from ${fileName}`);
+    }
+
+    return normalizeCharacterSpacing(extractedText);
+  } catch (error) {
+    console.error(`Error parsing ${fileName}:`, error);
+    throw new Error(`Failed to parse ${fileName}: ${error.message}`);
+  }
+}
+
+module.exports = { parseDocument };