@mettlecast/domain-cli 0.2.0

package/dist/templates/patterns/hook/index.js

@@ -0,0 +1,378 @@
+/**
+ * Paginated list hook pattern — uses `useInfiniteQuery` from TanStack Query for paginated lists.
+ */
+export function paginatedListHookTemplate(name) {
+    const hookName = `use${capitalize(name)}`;
+    return `import { useInfiniteQuery } from '@tanstack/react-query';
+import { useTib } from '@/hooks/useTib';
+
+/** Request shape for paginated list endpoints. */
+export interface ${capitalize(name)}ListRequest {
+  workspaceId: string;
+  status?: string;
+  search?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+/** Single item in the paginated response. */
+export interface ${capitalize(name)}Item {
+  id: string;
+  name: string;
+  status: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Paginated response from the API. */
+export interface ${capitalize(name)}ListResponse {
+  items: ${capitalize(name)}Item[];
+  nextCursor: string | null;
+  totalCount: number;
+}
+
+/**
+ * Infinite-query hook for paginated ${name} lists.
+ *
+ * Uses TanStack Query \`useInfiniteQuery\` with cursor-based pagination.
+ * Each page is fetched as the user scrolls, keeping memory bounded.
+ */
+export function ${hookName}(args: ${capitalize(name)}ListRequest) {
+  const tib = useTib();
+
+  return useInfiniteQuery<${capitalize(name)}ListResponse, Error>({
+    queryKey: ['${name}-list', args.workspaceId, args.status, args.search],
+    queryFn: ({ pageParam }) =>
+      tib.data.list({
+        workspaceId: args.workspaceId,
+        status: args.status,
+        search: args.search,
+        cursor: pageParam as string | undefined,
+        limit: args.limit ?? 20,
+      }),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+    staleTime: 10_000,
+  });
+}
+`;
+}
+export function mutationHookTemplate(name) {
+    const hookName = `use${capitalize(name)}`;
+    return `import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useTib } from '@/hooks/useTib';
+import { toast } from 'sonner';
+
+/** Input shape for the mutation. */
+export interface ${capitalize(name)}Input {
+  workspaceId: string;
+  /** Fields to create or update. */
+  values: Record<string, unknown>;
+}
+
+/** Response from the API after a successful mutation. */
+export interface ${capitalize(name)}Response {
+  id: string;
+  ok: boolean;
+}
+
+/**
+ * Mutation hook for creating or updating ${name} entities.
+ *
+ * Uses TanStack Query \`useMutation\` with optimistic update support,
+ * automatic error rollback, and toast notifications.
+ */
+export function ${hookName}() {
+  const tib = useTib();
+  const queryClient = useQueryClient();
+
+  return useMutation<${capitalize(name)}Response, Error, ${capitalize(name)}Input>({
+    mutationFn: (input: ${capitalize(name)}Input) =>
+      tib.data.upsert({
+        workspaceId: input.workspaceId,
+        ...input.values,
+      }),
+
+    onMutate: async (input) => {
+      // Cancel outgoing refetches so they don't overwrite the optimistic update
+      const key = ['${name}-list', input.workspaceId];
+      await queryClient.cancelQueries({ queryKey: key });
+
+      // Snapshot the previous value for rollback
+      const previous = queryClient.getQueryData(key);
+      return { previous, key };
+    },
+
+    onError: (err, input, context) => {
+      // Roll back to the previous value on error
+      if (context?.previous) {
+        queryClient.setQueryData(context.key, context.previous);
+      }
+      toast.error('Operation failed', {
+        description: err.message,
+      });
+    },
+
+    onSuccess: (_data, input) => {
+      toast.success('Operation successful');
+    },
+
+    onSettled: (_data, _error, input) => {
+      // Always refetch to ensure cache is fresh
+      queryClient.invalidateQueries({
+        queryKey: ['${name}', input.workspaceId],
+      });
+    },
+  });
+}
+
+/**
+ * Mutation hook for deleting ${name} entities.
+ */
+export function useDelete${capitalize(name)}() {
+  const tib = useTib();
+  const queryClient = useQueryClient();
+
+  return useMutation<void, Error, { workspaceId: string; id: string }>({
+    mutationFn: ({ workspaceId, id }) =>
+      tib.data.delete({ workspaceId, id }),
+
+    onSuccess: (_data, { workspaceId }) => {
+      toast.success('Deleted');
+      queryClient.invalidateQueries({
+        queryKey: ['${name}', workspaceId],
+      });
+    },
+
+    onError: (err) => {
+      toast.error('Delete failed', {
+        description: err.message,
+      });
+    },
+  });
+}
+`;
+}
+export function featureFlagHookTemplate(name) {
+    const hookName = `use${capitalize(name)}`;
+    return `import { useQuery } from '@tanstack/react-query';
+import { useTib } from '@/hooks/useTib';
+
+/** W6-style error shape returned by the TIB SDK. */
+interface TibErrorShape {
+  code?: string;
+  traceId?: string;
+  message: string;
+}
+
+interface FeatureFlagResult {
+  enabled: boolean;
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Hook that checks a feature flag via the TIB SDK.
+ *
+ * Uses TanStack Query with a 60-second stale time (matching the
+ * backend flag cache TTL). Returns \`{ enabled: false }\` on error
+ * so the UI degrades safely when the flags service is unreachable.
+ */
+export function ${hookName}(flagKey: string): {
+  enabled: boolean;
+  config?: Record<string, unknown>;
+  isLoading: boolean;
+  isError: boolean;
+  error: Error | null;
+} {
+  const tib = useTib();
+
+  const { data, isLoading, isError, error } = useQuery<FeatureFlagResult, Error>({
+    queryKey: ['feature-flag', flagKey],
+    queryFn: async () => {
+      try {
+        const result = await tib.flags.get(flagKey) as { value: boolean; config?: Record<string, unknown> };
+        return { enabled: result.value, config: result.config };
+      } catch (err) {
+        // Degrade gracefully: return disabled on error
+        return { enabled: false };
+      }
+    },
+    staleTime: 60_000, // matches backend flag cache TTL
+    retry: 1,
+  });
+
+  return {
+    enabled: data?.enabled ?? false,
+    config: data?.config,
+    isLoading,
+    isError,
+    error,
+  };
+}
+`;
+}
+export function subscriptionHookTemplate(name) {
+    const hookName = `use${capitalize(name)}`;
+    return `import { useEffect, useRef, useCallback } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useTib } from '@/hooks/useTib';
+
+/** Message envelope received over the subscription channel. */
+interface ${capitalize(name)}Message {
+  eventId: string;
+  type: string;
+  payload: Record<string, unknown>;
+  timestamp: string;
+}
+
+/** Callback invoked for each received message. */
+type ${capitalize(name)}Handler = (message: ${capitalize(name)}Message) => void;
+
+/** Connection states for the subscription. */
+type ConnectionStatus = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+
+/**
+ * Hook for subscribing to a real-time ${name} event stream.
+ *
+ * Uses EventSource (SSE) with automatic reconnection (exponential
+ * backoff, capped at 16 s). Incoming events are dispatched to the
+ * provided handler and optionally update TanStack Query caches.
+ *
+ * Heartbeat: server emits \`ping\` every 25 s. Missing two consecutive
+ * pings triggers reconnection.
+ */
+export function ${hookName}(
+  workspaceId: string,
+  onMessage?: ${capitalize(name)}Handler,
+): {
+  status: ConnectionStatus;
+  disconnect: () => void;
+  reconnect: () => void;
+} {
+  const tib = useTib();
+  const queryClient = useQueryClient();
+  const eventSourceRef = useRef<EventSource | null>(null);
+  const reconnectAttemptRef = useRef<number>(0);
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastPingRef = useRef<number>(Date.now());
+  const pingCheckTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const statusRef = useRef<ConnectionStatus>('disconnected');
+
+  const connect = useCallback(() => {
+    // Clean up any existing connection
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+    }
+
+    statusRef.current = reconnectAttemptRef.current > 0 ? 'reconnecting' : 'connecting';
+
+    const url = new URL('\\\${import.meta.env.VITE_API_URL}/v1/stream');
+    url.searchParams.set('workspaceId', workspaceId);
+
+    const es = new EventSource(url.toString());
+    eventSourceRef.current = es;
+    lastPingRef.current = Date.now();
+
+    es.addEventListener('ping', () => {
+      lastPingRef.current = Date.now();
+    });
+
+    es.addEventListener('message', (event) => {
+      try {
+        const data = JSON.parse(event.data) as ${capitalize(name)}Message;
+        statusRef.current = 'connected';
+        reconnectAttemptRef.current = 0;
+
+        if (onMessage) {
+          onMessage(data);
+        }
+
+        // Optionally update a query cache key with the latest event
+        queryClient.setQueryData(['${name}-stream', workspaceId], data);
+      } catch {
+        // Ignore malformed messages
+      }
+    });
+
+    es.onerror = () => {
+      es.close();
+      scheduleReconnect();
+    };
+
+    es.onopen = () => {
+      statusRef.current = 'connected';
+      reconnectAttemptRef.current = 0;
+    };
+
+    // Start ping heartbeat checker
+    if (pingCheckTimerRef.current) {
+      clearInterval(pingCheckTimerRef.current);
+    }
+    pingCheckTimerRef.current = setInterval(() => {
+      const elapsed = Date.now() - lastPingRef.current;
+      if (elapsed > 50_000) {
+        // Missed two consecutive pings (> 50 s)
+        es.close();
+        scheduleReconnect();
+      }
+    }, 25_000);
+  }, [workspaceId, onMessage, queryClient]);
+
+  const scheduleReconnect = useCallback(() => {
+    if (reconnectTimerRef.current) {
+      clearTimeout(reconnectTimerRef.current);
+    }
+
+    const attempt = reconnectAttemptRef.current;
+    const delay = Math.min(1000 * Math.pow(2, attempt), 16_000) +
+      Math.random() * 1000; // ± jitter
+
+    reconnectAttemptRef.current = attempt + 1;
+    statusRef.current = 'reconnecting';
+
+    reconnectTimerRef.current = setTimeout(() => {
+      connect();
+    }, delay);
+  }, [connect]);
+
+  const disconnect = useCallback(() => {
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+      eventSourceRef.current = null;
+    }
+    if (reconnectTimerRef.current) {
+      clearTimeout(reconnectTimerRef.current);
+      reconnectTimerRef.current = null;
+    }
+    if (pingCheckTimerRef.current) {
+      clearInterval(pingCheckTimerRef.current);
+      pingCheckTimerRef.current = null;
+    }
+    statusRef.current = 'disconnected';
+  }, []);
+
+  const reconnect = useCallback(() => {
+    reconnectAttemptRef.current = 0;
+    disconnect();
+    connect();
+  }, [connect, disconnect]);
+
+  useEffect(() => {
+    connect();
+    return () => disconnect();
+  }, [connect, disconnect]);
+
+  return {
+    get status() {
+      return statusRef.current;
+    },
+    disconnect,
+    reconnect,
+  };
+}
+`;
+}
+/** Capitalizes the first character of a string. */
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/dist/templates/patterns/migration/column-add.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Column-add migration pattern template.
+ * Produces: ALTER TABLE to add a new column with optional default and NOT NULL constraint.
+ */
+export declare function columnAddTemplate(domain: string, name: string): string;

package/dist/templates/patterns/migration/column-add.js

@@ -0,0 +1,52 @@
+/**
+ * Column-add migration pattern template.
+ * Produces: ALTER TABLE to add a new column with optional default and NOT NULL constraint.
+ */
+export function columnAddTemplate(domain, name) {
+    const timestamp = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14);
+    return `-- Migration: ${timestamp}_${name}
+-- Domain: ${domain}
+-- Pattern: column-add
+-- Adds one or more columns to an existing table with safe defaults.
+
+-- ── Example: add a new column ────────────────────────────────
+-- Replace table_name, column_name, type, and default_value as needed.
+
+-- ALTER TABLE table_name
+--   ADD COLUMN IF NOT EXISTS column_name VARCHAR(255) NOT NULL DEFAULT 'default_value';
+
+-- ── Backfill existing rows (if default is not sufficient) ────
+-- UPDATE table_name
+--   SET column_name = 'default_value'
+--   WHERE column_name IS NULL;
+
+-- ── Add index on new column (if frequently queried) ──────────
+-- CREATE INDEX IF NOT EXISTS idx_table_name_column_name
+--   ON table_name(tenant_id, column_name);
+
+-- ── Template for adding multiple columns ─────────────────────
+
+DO $$
+BEGIN
+  -- Column 1
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_name = 'REPLACE_WITH_TABLE_NAME'
+      AND column_name = 'REPLACE_WITH_COLUMN_1'
+  ) THEN
+    ALTER TABLE REPLACE_WITH_TABLE_NAME
+      ADD COLUMN REPLACE_WITH_COLUMN_1 TEXT;
+  END IF;
+
+  -- Column 2
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_name = 'REPLACE_WITH_TABLE_NAME'
+      AND column_name = 'REPLACE_WITH_COLUMN_2'
+  ) THEN
+    ALTER TABLE REPLACE_WITH_TABLE_NAME
+      ADD COLUMN REPLACE_WITH_COLUMN_2 JSONB DEFAULT '{}'::jsonb;
+  END IF;
+END $$;
+`;
+}

package/dist/templates/patterns/migration/event-store.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Event-store migration pattern template.
+ * Produces: CREATE TABLE for an event-store with append-only semantics,
+ * event_id sequence, aggregate root, and version tracking.
+ */
+export declare function eventStoreTemplate(domain: string, name: string): string;

package/dist/templates/patterns/migration/event-store.js

@@ -0,0 +1,97 @@
+/**
+ * Event-store migration pattern template.
+ * Produces: CREATE TABLE for an event-store with append-only semantics,
+ * event_id sequence, aggregate root, and version tracking.
+ */
+export function eventStoreTemplate(domain, name) {
+    const tableName = name.replace(/-/g, '_');
+    const timestamp = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14);
+    return `-- Migration: ${timestamp}_${name}
+-- Domain: ${domain}
+-- Pattern: event-store
+-- Creates an append-only event-store table with aggregate-root tracking.
+
+CREATE TABLE IF NOT EXISTS ${tableName} (
+  -- Event identity
+  id            BIGSERIAL PRIMARY KEY,
+  event_id      UUID NOT NULL UNIQUE DEFAULT gen_random_uuid(),
+
+  -- Aggregate root
+  aggregate_type VARCHAR(100) NOT NULL,
+  aggregate_id   UUID NOT NULL,
+  aggregate_version INT NOT NULL DEFAULT 1,
+
+  -- Event metadata
+  event_type    VARCHAR(200) NOT NULL,
+  event_version INT NOT NULL DEFAULT 1,
+  payload       JSONB NOT NULL,
+  metadata      JSONB DEFAULT '{}'::jsonb,
+
+  -- Tenancy
+  tenant_id     UUID NOT NULL,
+  workspace_id  UUID,
+
+  -- Audit
+  occurred_at   TIMESTAMPTZ NOT NULL,
+  recorded_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+  correlation_id UUID,
+  causation_id  UUID,
+
+  -- Concurrency guard
+  UNIQUE(aggregate_type, aggregate_id, aggregate_version)
+);
+
+-- ── Indexes ──────────────────────────────────────────────────
+
+CREATE INDEX IF NOT EXISTS idx_${tableName}_aggregate
+  ON ${tableName}(aggregate_type, aggregate_id, aggregate_version);
+
+CREATE INDEX IF NOT EXISTS idx_${tableName}_tenant_occurred
+  ON ${tableName}(tenant_id, occurred_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_${tableName}_event_type
+  ON ${tableName}(event_type, occurred_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_${tableName}_correlation
+  ON ${tableName}(correlation_id)
+  WHERE correlation_id IS NOT NULL;
+
+-- ── Row-Level Security ───────────────────────────────────────
+
+ALTER TABLE ${tableName} ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY ${tableName}_tenant_isolation
+  ON ${tableName}
+  FOR SELECT
+  TO authenticated
+  USING (tenant_id = current_setting('app.current_tenant_id')::UUID);
+
+-- ── Append-only guard ────────────────────────────────────────
+-- No UPDATE or DELETE allowed; only INSERT and SELECT.
+
+CREATE POLICY ${tableName}_insert_only
+  ON ${tableName}
+  FOR INSERT
+  TO authenticated
+  WITH CHECK (true);
+
+-- ── Helper: next aggregate version ───────────────────────────
+
+CREATE OR REPLACE FUNCTION ${tableName}_next_version(
+  p_aggregate_type VARCHAR,
+  p_aggregate_id UUID
+)
+RETURNS INT AS $$
+DECLARE
+  v_next INT;
+BEGIN
+  SELECT COALESCE(MAX(aggregate_version), 0) + 1
+    INTO v_next
+    FROM ${tableName}
+    WHERE aggregate_type = p_aggregate_type
+      AND aggregate_id = p_aggregate_id;
+  RETURN v_next;
+END;
+$$ LANGUAGE plpgsql;
+`;
+}

package/dist/templates/patterns/migration/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Index migration pattern template.
+ * Produces: CREATE INDEX statements with CONCURRENTLY option and performance notes.
+ */
+export declare function indexTemplate(domain: string, name: string): string;

package/dist/templates/patterns/migration/index.js

@@ -0,0 +1,52 @@
+/**
+ * Index migration pattern template.
+ * Produces: CREATE INDEX statements with CONCURRENTLY option and performance notes.
+ */
+export function indexTemplate(domain, name) {
+    const timestamp = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14);
+    return `-- Migration: ${timestamp}_${name}
+-- Domain: ${domain}
+-- Pattern: index
+-- Creates indexes to optimise query performance.
+--
+-- IMPORTANT: CREATE INDEX CONCURRENTLY must run outside a transaction.
+-- Run this migration with --no-transaction if the tooling supports it.
+
+-- ── Single-column index ──────────────────────────────────────
+-- CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_table_name_column
+--   ON table_name(column_name);
+
+-- ── Composite index (tenant-scoped queries) ──────────────────
+-- CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_table_name_tenant_column
+--   ON table_name(tenant_id, column_name);
+
+-- ── Partial index (filtered) ─────────────────────────────────
+-- CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_table_name_active
+--   ON table_name(tenant_id, created_at DESC)
+--   WHERE status = 'active';
+
+-- ── GIN index for JSONB columns ──────────────────────────────
+-- CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_table_name_metadata_gin
+--   ON table_name USING GIN(metadata jsonb_path_ops);
+
+-- ── Unique index (enforce business constraint) ───────────────
+-- CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS uq_table_name_tenant_name
+--   ON table_name(tenant_id, name)
+--   WHERE deleted_at IS NULL;
+
+-- ── Template: safe index creation with existence check ───────
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_indexes
+    WHERE schemaname = 'public'
+      AND tablename = 'REPLACE_WITH_TABLE_NAME'
+      AND indexname = 'REPLACE_WITH_INDEX_NAME'
+  ) THEN
+    CREATE INDEX CONCURRENTLY REPLACE_WITH_INDEX_NAME
+      ON REPLACE_WITH_TABLE_NAME(REPLACE_WITH_COLUMN_NAME);
+  END IF;
+END $$;
+`;
+}

package/dist/templates/patterns/migration/rls-policy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * RLS-policy migration pattern template.
+ * Produces: ALTER TABLE to add/enable RLS policies on an existing table.
+ */
+export declare function rlsPolicyTemplate(domain: string, name: string): string;

package/dist/templates/patterns/migration/rls-policy.js

@@ -0,0 +1,78 @@
+/**
+ * RLS-policy migration pattern template.
+ * Produces: ALTER TABLE to add/enable RLS policies on an existing table.
+ */
+export function rlsPolicyTemplate(domain, name) {
+    const tableName = name.replace(/-/g, '_');
+    const timestamp = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14);
+    return `-- Migration: ${timestamp}_${name}
+-- Domain: ${domain}
+-- Pattern: rls-policy
+-- Adds Row-Level Security policies to an existing table.
+
+-- ── Enable RLS if not already enabled ────────────────────────
+
+ALTER TABLE ${tableName} ENABLE ROW LEVEL SECURITY;
+
+-- ── Tenant isolation policy ──────────────────────────────────
+-- Ensures rows are only visible within the same tenant context.
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = 'public'
+      AND tablename = '${tableName}'
+      AND policyname = '${tableName}_tenant_isolation'
+  ) THEN
+    CREATE POLICY ${tableName}_tenant_isolation
+      ON ${tableName}
+      FOR ALL
+      TO authenticated
+      USING (tenant_id = current_setting('app.current_tenant_id')::UUID)
+      WITH CHECK (tenant_id = current_setting('app.current_tenant_id')::UUID);
+  END IF;
+END $$;
+
+-- ── Soft-delete filter policy ────────────────────────────────
+-- Automatically excludes soft-deleted rows from SELECT queries.
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = 'public'
+      AND tablename = '${tableName}'
+      AND policyname = '${tableName}_soft_delete_filter'
+  ) THEN
+    CREATE POLICY ${tableName}_soft_delete_filter
+      ON ${tableName}
+      FOR SELECT
+      TO authenticated
+      USING (deleted_at IS NULL);
+  END IF;
+END $$;
+
+-- ── Workspace-scoped access policy ───────────────────────────
+-- Restricts access to rows belonging to the current workspace.
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = 'public'
+      AND tablename = '${tableName}'
+      AND policyname = '${tableName}_workspace_scope'
+  ) THEN
+    CREATE POLICY ${tableName}_workspace_scope
+      ON ${tableName}
+      FOR SELECT
+      TO authenticated
+      USING (
+        workspace_id IS NULL
+        OR workspace_id = current_setting('app.current_workspace_id', true)::UUID
+      );
+  END IF;
+END $$;
+`;
+}

package/dist/templates/patterns/migration/tenant-scoped-table.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tenant-scoped-table migration pattern template.
+ * Produces: CREATE TABLE with tenancy trio (tenant_id, workspace_id, org_id),
+ * RLS policy, updated_at trigger, and standard indexes.
+ */
+export declare function tenantScopedTableTemplate(domain: string, name: string): string;