@useatlas/create 0.0.6 → 0.0.7

package/templates/docker/data/ecommerce-semantic/metrics/operations.yml

@@ -0,0 +1,131 @@
+metrics:
+  - id: avg_fulfillment_time
+    label: Average Fulfillment Time
+    description: >
+      Average days from shipment creation (order processing) to actual ship date.
+      Measures warehouse processing speed.
+    type: atomic
+    unit: days
+    sql: |-
+      SELECT AVG(EXTRACT(DAY FROM (shipped_at - created_at))) AS avg_fulfillment_days
+      FROM shipments
+      WHERE shipped_at IS NOT NULL
+    aggregation: avg
+    objective: minimize
+
+  - id: avg_transit_time
+    label: Average Transit Time
+    description: >
+      Average days from ship date to delivery. Measures carrier performance.
+    type: atomic
+    unit: days
+    sql: |-
+      SELECT AVG(EXTRACT(DAY FROM (delivered_at - shipped_at))) AS avg_transit_days
+      FROM shipments
+      WHERE delivered_at IS NOT NULL
+    aggregation: avg
+    objective: minimize
+
+  - id: avg_order_to_delivery
+    label: Average Order-to-Delivery Time
+    description: >
+      Average total days from order placement to delivery. End-to-end fulfillment
+      metric combining processing + transit time.
+    type: derived
+    unit: days
+    sql: |-
+      SELECT AVG(EXTRACT(DAY FROM (s.delivered_at - o.created_at))) AS avg_days
+      FROM orders o
+      JOIN shipments s ON s.order_id = o.id
+      WHERE s.delivered_at IS NOT NULL
+    aggregation: avg
+    objective: minimize
+
+  - id: return_rate
+    label: Return Rate
+    description: >
+      Percentage of orders that result in a return request.
+    type: derived
+    unit: percent
+    sql: |-
+      SELECT ROUND(100.0 * COUNT(DISTINCT r.order_id) / NULLIF(COUNT(DISTINCT o.id), 0), 1) AS return_rate
+      FROM orders o
+      LEFT JOIN returns r ON r.order_id = o.id
+    aggregation: ratio
+    objective: minimize
+
+  - id: returns_by_reason
+    label: Returns by Reason
+    description: >
+      Return volume by normalized reason. Uses LOWER() to handle case
+      inconsistencies in the reason field.
+    type: breakdown
+    sql: |-
+      SELECT LOWER(reason) AS return_reason,
+             COUNT(*) AS return_count,
+             ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) AS pct
+      FROM returns
+      GROUP BY LOWER(reason)
+      ORDER BY return_count DESC
+
+  - id: carrier_performance
+    label: Carrier Performance
+    description: >
+      Delivery rate and average transit time by shipping carrier.
+    type: breakdown
+    unit: days
+    sql: |-
+      SELECT carrier,
+             COUNT(*) AS shipment_count,
+             COUNT(*) FILTER (WHERE status = 'delivered') AS delivered,
+             ROUND(100.0 * COUNT(*) FILTER (WHERE status = 'delivered') / COUNT(*), 1) AS delivery_rate,
+             AVG(EXTRACT(DAY FROM (delivered_at - shipped_at))) AS avg_transit_days
+      FROM shipments
+      WHERE shipped_at IS NOT NULL
+      GROUP BY carrier
+      ORDER BY shipment_count DESC
+
+  - id: inventory_health
+    label: Inventory Health
+    description: >
+      Summary of stock levels — out of stock, low stock, adequate, and overstock
+      counts across all variant-warehouse combinations.
+    type: breakdown
+    sql: |-
+      SELECT CASE
+               WHEN quantity = 0 THEN 'Out of Stock'
+               WHEN quantity < reorder_point THEN 'Low Stock'
+               WHEN quantity < reorder_point * 3 THEN 'Adequate'
+               ELSE 'Overstock'
+             END AS stock_status,
+             COUNT(*) AS sku_count,
+             SUM(quantity) AS total_units,
+             ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) AS pct
+      FROM inventory_levels
+      GROUP BY stock_status
+      ORDER BY sku_count DESC
+
+  - id: low_stock_alert_count
+    label: Low Stock Alerts
+    description: >
+      Number of variant-warehouse combinations with stock below reorder point.
+    type: atomic
+    sql: |-
+      SELECT COUNT(*) AS low_stock_count
+      FROM inventory_levels
+      WHERE quantity < reorder_point
+    aggregation: count
+    objective: minimize
+
+  - id: avg_return_resolution_time
+    label: Average Return Resolution Time
+    description: >
+      Average days from return request to resolution for completed returns.
+    type: derived
+    unit: days
+    sql: |-
+      SELECT AVG(EXTRACT(DAY FROM (resolved_at - created_at))) AS avg_resolution_days
+      FROM returns
+      WHERE resolved_at IS NOT NULL
+    aggregation: avg
+    objective: minimize

package/templates/docker/data/ecommerce-semantic/metrics/revenue.yml

@@ -0,0 +1,120 @@
+metrics:
+  - id: total_gmv
+    label: Total GMV
+    description: >
+      Gross Merchandise Value — total value of all non-cancelled orders.
+      Calculated from orders.total_cents / 100.
+    type: atomic
+    unit: USD
+    source:
+      entity: Orders
+      measure: total_gmv_cents
+    sql: |-
+      SELECT SUM(total_cents) / 100.0 AS total_gmv
+      FROM orders
+      WHERE status != 'cancelled'
+    aggregation: sum
+    objective: maximize
+
+  - id: aov
+    label: Average Order Value (AOV)
+    description: >
+      Average order value across non-cancelled orders.
+      GMV divided by order count.
+    type: derived
+    unit: USD
+    sql: |-
+      SELECT AVG(total_cents) / 100.0 AS aov
+      FROM orders
+      WHERE status != 'cancelled'
+    aggregation: avg
+    objective: maximize
+
+  - id: monthly_gmv_trend
+    label: Monthly GMV Trend
+    description: GMV and order count by month for trend analysis.
+    type: breakdown
+    unit: USD
+    sql: |-
+      SELECT TO_CHAR(created_at, 'YYYY-MM') AS month,
+             COUNT(*) AS order_count,
+             SUM(total_cents) / 100.0 AS gmv,
+             AVG(total_cents) / 100.0 AS aov
+      FROM orders
+      WHERE status != 'cancelled'
+      GROUP BY TO_CHAR(created_at, 'YYYY-MM')
+      ORDER BY month
+
+  - id: revenue_by_category
+    label: Revenue by Category
+    description: >
+      Product revenue broken down by category. Joins order_items to products
+      and categories for category-level attribution.
+    type: breakdown
+    unit: USD
+    sql: |-
+      SELECT c.name AS category,
+             SUM(oi.total_cents) / 100.0 AS revenue,
+             COUNT(DISTINCT oi.order_id) AS order_count,
+             SUM(oi.quantity) AS units_sold
+      FROM order_items oi
+      JOIN products p ON oi.product_name = p.name
+      JOIN categories c ON p.category_id = c.id
+      GROUP BY c.name
+      ORDER BY revenue DESC
+
+  - id: revenue_dtc_vs_marketplace
+    label: Revenue — DTC vs Marketplace
+    description: >
+      Revenue split between NovaMart's own DTC products (seller_id IS NULL)
+      and third-party marketplace products.
+    type: breakdown
+    unit: USD
+    sql: |-
+      SELECT CASE WHEN p.seller_id IS NULL THEN 'DTC' ELSE 'Marketplace' END AS channel,
+             SUM(oi.total_cents) / 100.0 AS revenue,
+             COUNT(DISTINCT oi.order_id) AS order_count,
+             AVG(oi.unit_price_cents) / 100.0 AS avg_unit_price
+      FROM order_items oi
+      JOIN products p ON oi.product_name = p.name
+      GROUP BY CASE WHEN p.seller_id IS NULL THEN 'DTC' ELSE 'Marketplace' END
+
+  - id: refund_rate
+    label: Refund Rate
+    description: >
+      Percentage of payments that have been refunded. Based on payment status.
+    type: derived
+    unit: percent
+    sql: |-
+      SELECT ROUND(100.0 * COUNT(*) FILTER (WHERE status = 'refunded') / NULLIF(COUNT(*), 0), 1) AS refund_rate
+      FROM payments
+    aggregation: ratio
+    objective: minimize
+
+  - id: net_revenue
+    label: Net Revenue
+    description: >
+      GMV minus refunded payment amounts. Represents actual collected revenue.
+    type: derived
+    unit: USD
+    sql: |-
+      SELECT (SUM(CASE WHEN status = 'captured' THEN amount_cents ELSE 0 END)
+              - SUM(CASE WHEN status = 'refunded' THEN amount_cents ELSE 0 END)) / 100.0 AS net_revenue
+      FROM payments
+    aggregation: sum
+    objective: maximize
+
+  - id: promotion_discount_impact
+    label: Promotion Discount Impact
+    description: >
+      Comparison of AOV and order count between promoted and non-promoted orders.
+    type: breakdown
+    unit: USD
+    sql: |-
+      SELECT CASE WHEN promotion_id IS NOT NULL THEN 'Promoted' ELSE 'Full Price' END AS order_type,
+             COUNT(*) AS order_count,
+             AVG(total_cents) / 100.0 AS avg_order_value,
+             SUM(total_cents) / 100.0 AS total_revenue
+      FROM orders
+      WHERE status != 'cancelled'
+      GROUP BY CASE WHEN promotion_id IS NOT NULL THEN 'Promoted' ELSE 'Full Price' END

package/templates/docker/docs/deploy.md

@@ -135,7 +135,8 @@ Atlas runs agent-generated commands (filesystem exploration, future code executi
 | 1 | Vercel Sandbox | Vercel | Firecracker microVM (hardware-level). No network, ephemeral filesystem |
 | 2 | nsjail | Self-hosted Docker/VM | Linux namespaces. No network, read-only mount, separate PID/user space |
 | 3 | Sidecar service | Railway | Separate container with no secrets. Process-level isolation via private networking |
-| 4 | just-bash | Everywhere (fallback) | In-memory OverlayFS + path-traversal protection. No process isolation |
+| 4 | Sidecar (local) | Local dev (Docker Compose) | Same as tier 3 — sidecar container started by `bun run db:up` |
+| 5 | just-bash | Fallback | In-memory OverlayFS + path-traversal protection. No process isolation |
 
 ### What's right for you?
 

package/templates/docker/ee/src/__mocks__/internal.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared mock factory for EE test files.
+ *
+ * 8 EE test files mock all three of these modules; 1 additional file
+ * (approval.test.ts) uses only the DB and logger mocks:
+ *   - `../index` (enterprise gate)
+ *   - `@atlas/api/lib/db/internal` (internal DB)
+ *   - `@atlas/api/lib/logger` (logger)
+ *
+ * This factory centralises the default shape so that changes to these
+ * modules only need updating here.
+ *
+ * Usage:
+ *   import { createEEMock } from "../__mocks__/internal";
+ *   const ee = createEEMock();
+ *   mock.module("../index", () => ee.enterpriseMock);
+ *   mock.module("@atlas/api/lib/db/internal", () => ee.internalDBMock);
+ *   mock.module("@atlas/api/lib/logger", () => ee.loggerMock);
+ *
+ * @module
+ */
+
+import { EnterpriseError } from "../index";
+
+// Re-export so tests can import from the mock factory
+export { EnterpriseError };
+
+export interface EEMockOverrides {
+  /** Extra exports merged into the enterprise mock (`../index`). */
+  enterprise?: Record<string, unknown>;
+  /** Extra exports merged into the internal DB mock. */
+  internalDB?: Record<string, unknown>;
+  /** Extra exports merged into the logger mock. */
+  logger?: Record<string, unknown>;
+}
+
+export interface EEMock {
+  // ── Module mocks (pass directly to mock.module) ──────────────
+  enterpriseMock: Record<string, unknown>;
+  internalDBMock: Record<string, unknown>;
+  loggerMock: Record<string, unknown>;
+
+  // ── State ────────────────────────────────────────────────────
+  capturedQueries: { sql: string; params: unknown[] }[];
+
+  // ── Helpers ──────────────────────────────────────────────────
+  /** Append row batches to the queue — subsequent internalQuery / getInternalDB().query calls consume them in order. */
+  queueMockRows: (...batches: Record<string, unknown>[][]) => void;
+  /** Toggle the enterprise-enabled flag. */
+  setEnterpriseEnabled: (enabled: boolean) => void;
+  /** Set or clear the enterprise license key. */
+  setEnterpriseLicenseKey: (key: string | undefined) => void;
+  /** Toggle hasInternalDB return value. */
+  setHasInternalDB: (has: boolean) => void;
+  /** Reset all mock state (call in beforeEach). */
+  reset: () => void;
+}
+
+/**
+ * Returns a fresh set of mocks. Each call creates new objects so tests
+ * don't leak state.
+ */
+export function createEEMock(overrides?: EEMockOverrides): EEMock {
+  // ── Mutable state ──────────────────────────────────────────────
+  let enterpriseEnabled = true;
+  let enterpriseLicenseKey: string | undefined = "test-key";
+  let hasInternalDB = true;
+  const mockRows: Record<string, unknown>[][] = [];
+  let queryCallCount = 0;
+  const capturedQueries: { sql: string; params: unknown[] }[] = [];
+
+  // ── Internal DB query handler (shared by internalQuery & getInternalDB) ─
+  function handleQuery(sql: string, params?: unknown[]) {
+    capturedQueries.push({ sql, params: params ?? [] });
+    const rows = mockRows[queryCallCount] ?? [];
+    queryCallCount++;
+    return rows;
+  }
+
+  // ── Enterprise mock ────────────────────────────────────────────
+  const enterpriseMock: Record<string, unknown> = {
+    isEnterpriseEnabled: () => enterpriseEnabled,
+    getEnterpriseLicenseKey: () => enterpriseLicenseKey,
+    EnterpriseError,
+    requireEnterprise: (feature?: string) => {
+      const label = feature ? ` (${feature})` : "";
+      if (!enterpriseEnabled) {
+        throw new EnterpriseError(
+          `Enterprise features${label} are not enabled. ` +
+          `Set ATLAS_ENTERPRISE_ENABLED=true or configure enterprise.enabled in atlas.config.ts.`,
+        );
+      }
+    },
+    ...overrides?.enterprise,
+  };
+
+  // ── Internal DB mock ───────────────────────────────────────────
+  const internalDBMock: Record<string, unknown> = {
+    hasInternalDB: () => hasInternalDB,
+    getInternalDB: () => ({
+      query: async (sql: string, params?: unknown[]) => {
+        const rows = handleQuery(sql, params);
+        return { rows, rowCount: rows.length };
+      },
+      end: async () => {},
+      on: () => {},
+    }),
+    internalQuery: async (sql: string, params?: unknown[]) => {
+      return handleQuery(sql, params);
+    },
+    internalExecute: () => {},
+    encryptUrl: (v: string) => `encrypted:${v}`,
+    decryptUrl: (v: string) => (v.startsWith("encrypted:") ? v.slice(10) : v),
+    getEncryptionKey: () => Buffer.from("test-key-32-bytes-long-enough!!!"),
+    closeInternalDB: async () => {},
+    migrateInternalDB: async () => {},
+    _resetPool: () => {},
+    loadSavedConnections: async () => 0,
+    ...overrides?.internalDB,
+  };
+
+  // ── Logger mock ────────────────────────────────────────────────
+  const loggerMock: Record<string, unknown> = {
+    createLogger: () => ({
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }),
+    ...overrides?.logger,
+  };
+
+  // ── Helpers ────────────────────────────────────────────────────
+  function queueMockRows(...batches: Record<string, unknown>[][]) {
+    mockRows.push(...batches);
+  }
+
+  function setEnterpriseEnabled(enabled: boolean) {
+    enterpriseEnabled = enabled;
+  }
+
+  function setEnterpriseLicenseKey(key: string | undefined) {
+    enterpriseLicenseKey = key;
+  }
+
+  function setHasInternalDB(has: boolean) {
+    hasInternalDB = has;
+  }
+
+  function reset() {
+    mockRows.length = 0;
+    queryCallCount = 0;
+    capturedQueries.length = 0;
+    enterpriseEnabled = true;
+    enterpriseLicenseKey = "test-key";
+    hasInternalDB = true;
+  }
+
+  return {
+    enterpriseMock,
+    internalDBMock,
+    loggerMock,
+    capturedQueries,
+    queueMockRows,
+    setEnterpriseEnabled,
+    setEnterpriseLicenseKey,
+    setHasInternalDB,
+    reset,
+  };
+}

package/templates/docker/ee/src/audit/purge-scheduler.ts

@@ -0,0 +1,113 @@
+/**
+ * Audit log purge scheduler — daily interval-based purge of expired audit entries.
+ *
+ * Runs soft-delete purge and hard-delete cleanup on a configurable interval
+ * (default: daily at startup, then every 24 hours).
+ *
+ * Start via `startAuditPurgeScheduler()` during API startup when
+ * enterprise features are enabled.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import { isEnterpriseEnabled } from "../index";
+import { hasInternalDB } from "@atlas/api/lib/db/internal";
+
+const log = createLogger("ee:audit-purge");
+
+/** Default purge interval: 24 hours in milliseconds. */
+const DEFAULT_PURGE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+let _timer: ReturnType<typeof setInterval> | null = null;
+let _running = false;
+
+/**
+ * Run a single purge cycle: soft-delete expired entries, then hard-delete old ones.
+ * Errors are logged but never thrown — the scheduler must not crash.
+ */
+export async function runPurgeCycle(): Promise<void> {
+  if (!isEnterpriseEnabled() || !hasInternalDB()) return;
+
+  try {
+    const { purgeExpiredEntries, hardDeleteExpired } = await import("./retention");
+
+    // Soft-delete expired entries across all orgs
+    const softResults = await purgeExpiredEntries();
+    const totalSoftDeleted = softResults.reduce((sum, r) => sum + r.softDeletedCount, 0);
+
+    if (totalSoftDeleted > 0) {
+      log.info({ totalSoftDeleted, orgs: softResults.length }, "Audit purge cycle: soft-delete complete");
+    }
+
+    // Hard-delete entries past the delay
+    const hardResult = await hardDeleteExpired();
+    if (hardResult.deletedCount > 0) {
+      log.info({ deletedCount: hardResult.deletedCount }, "Audit purge cycle: hard-delete complete");
+    }
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Audit purge cycle failed — will retry next interval",
+    );
+  }
+}
+
+/**
+ * Start the audit purge scheduler.
+ *
+ * Runs an initial purge cycle immediately, then repeats at the configured interval.
+ * No-op if enterprise features are disabled or already running.
+ */
+export function startAuditPurgeScheduler(intervalMs?: number): void {
+  if (_running) {
+    log.debug("Audit purge scheduler already running — skipping start");
+    return;
+  }
+
+  if (!isEnterpriseEnabled()) {
+    log.debug("Enterprise features not enabled — audit purge scheduler not started");
+    return;
+  }
+
+  if (!hasInternalDB()) {
+    log.debug("No internal database — audit purge scheduler not started");
+    return;
+  }
+
+  const interval = intervalMs ?? DEFAULT_PURGE_INTERVAL_MS;
+  _running = true;
+
+  log.info({ intervalMs: interval }, "Starting audit purge scheduler");
+
+  // Run initial purge cycle (non-blocking)
+  void runPurgeCycle();
+
+  // Schedule recurring purge
+  _timer = setInterval(() => {
+    void runPurgeCycle();
+  }, interval);
+
+  // Don't prevent process exit
+  _timer.unref();
+}
+
+/**
+ * Stop the audit purge scheduler.
+ */
+export function stopAuditPurgeScheduler(): void {
+  if (_timer) {
+    clearInterval(_timer);
+    _timer = null;
+  }
+  _running = false;
+  log.info("Audit purge scheduler stopped");
+}
+
+/** Check if the scheduler is running. */
+export function isPurgeSchedulerRunning(): boolean {
+  return _running;
+}
+
+/** Reset scheduler state — for testing only. */
+export function _resetPurgeScheduler(): void {
+  stopAuditPurgeScheduler();
+}