@mettlecast/domain-cli 0.2.0

package/src/templates/patterns/flow/autonomous-remediation.ts

@@ -0,0 +1,101 @@
+/**
+ * Autonomous-remediation flow pattern template.
+ * Produces: flow that detects anomalies and self-heals without human intervention.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function autonomousRemediationTemplate(domain: string, id: string): string {
+  const varName = camelCase(id);
+
+  return `import { defineFlow } from '@mettlecast/domain-runtime';
+
+/**
+ * ${id} — Autonomous remediation flow.
+ *
+ * Detects anomaly events, runs diagnostic checks, applies
+ * corrective actions, and verifies resolution — all automated.
+ */
+export const ${varName} = defineFlow({
+  id: '${id}',
+  owningDomain: '${domain}',
+  type: 'standard',
+  name: '${id}',
+  steps: [
+    {
+      type: 'domain-action',
+      name: 'DetectAnomaly',
+      domainId: '${domain}',
+      actionId: 'detect-anomaly',
+      next: 'RunDiagnostics',
+    },
+    {
+      type: 'domain-action',
+      name: 'RunDiagnostics',
+      domainId: '${domain}',
+      actionId: 'run-diagnostics',
+      next: 'DecideAction',
+    },
+    {
+      type: 'choice',
+      name: 'DecideAction',
+      choices: [
+        { when: '$.diagnostics.severity == "critical"', next: 'ApplyCriticalFix' },
+        { when: '$.diagnostics.severity == "warning"', next: 'ApplySoftFix' },
+        { default: true, next: 'LogAndSkip' },
+      ],
+    },
+    {
+      type: 'domain-action',
+      name: 'ApplyCriticalFix',
+      domainId: '${domain}',
+      actionId: 'apply-critical-fix',
+      next: 'VerifyResolution',
+    },
+    {
+      type: 'domain-action',
+      name: 'ApplySoftFix',
+      domainId: '${domain}',
+      actionId: 'apply-soft-fix',
+      next: 'VerifyResolution',
+    },
+    {
+      type: 'domain-action',
+      name: 'LogAndSkip',
+      domainId: '${domain}',
+      actionId: 'log-and-skip',
+      next: 'Done',
+    },
+    {
+      type: 'domain-action',
+      name: 'VerifyResolution',
+      domainId: '${domain}',
+      actionId: 'verify-resolution',
+      next: 'EscalateIfUnresolved',
+    },
+    {
+      type: 'choice',
+      name: 'EscalateIfUnresolved',
+      choices: [
+        { when: '$.resolution === "unresolved"', next: 'EscalateToHuman' },
+        { default: true, next: 'Done' },
+      ],
+    },
+    {
+      type: 'domain-action',
+      name: 'EscalateToHuman',
+      domainId: '${domain}',
+      actionId: 'escalate-to-human',
+      next: 'Done',
+    },
+    {
+      type: 'flow-control',
+      control: 'succeed',
+      name: 'Done',
+    },
+  ],
+});
+`;
+}

package/src/templates/patterns/flow/fan-out-reaction.ts

@@ -0,0 +1,56 @@
+/**
+ * Fan-out-reaction flow pattern template.
+ * Produces: flow that fans out an event to multiple domain actions in parallel.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function fanOutReactionTemplate(domain: string, id: string): string {
+  const varName = camelCase(id);
+
+  return `import { defineFlow } from '@mettlecast/domain-runtime';
+
+/**
+ * ${id} — Fan-out reaction flow.
+ *
+ * When an upstream event arrives, this flow fans out to multiple
+ * domain actions that run in parallel, then joins at a completion step.
+ */
+export const ${varName} = defineFlow({
+  id: '${id}',
+  owningDomain: '${domain}',
+  type: 'express',
+  name: '${id}',
+  steps: [
+    {
+      type: 'domain-action',
+      name: 'NotifyServiceA',
+      domainId: '${domain}',
+      actionId: 'notify-service-a',
+      next: 'NotifyServiceB',
+    },
+    {
+      type: 'domain-action',
+      name: 'NotifyServiceB',
+      domainId: '${domain}',
+      actionId: 'notify-service-b',
+      next: 'AuditFanOut',
+    },
+    {
+      type: 'domain-action',
+      name: 'AuditFanOut',
+      domainId: '${domain}',
+      actionId: 'audit-fan-out',
+      next: 'Done',
+    },
+    {
+      type: 'flow-control',
+      control: 'succeed',
+      name: 'Done',
+    },
+  ],
+});
+`;
+}

package/src/templates/patterns/flow/human-in-loop.ts

@@ -0,0 +1,93 @@
+/**
+ * Human-in-loop flow pattern template.
+ * Produces: flow that pauses for human approval before proceeding.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function humanInLoopTemplate(domain: string, id: string): string {
+  const varName = camelCase(id);
+
+  return `import { defineFlow } from '@mettlecast/domain-runtime';
+
+/**
+ * ${id} — Human-in-the-loop flow.
+ *
+ * Pauses execution at an approval gate, waits for an authorised
+ * human to approve or reject, then proceeds or aborts accordingly.
+ */
+export const ${varName} = defineFlow({
+  id: '${id}',
+  owningDomain: '${domain}',
+  type: 'standard',
+  name: '${id}',
+  steps: [
+    {
+      type: 'domain-action',
+      name: 'PrepareChangeRequest',
+      domainId: '${domain}',
+      actionId: 'prepare-change-request',
+      next: 'NotifyReviewers',
+    },
+    {
+      type: 'domain-action',
+      name: 'NotifyReviewers',
+      domainId: '${domain}',
+      actionId: 'notify-reviewers',
+      next: 'WaitForApproval',
+    },
+    {
+      type: 'domain-action',
+      name: 'WaitForApproval',
+      domainId: '${domain}',
+      actionId: 'wait-for-approval',
+      next: 'EvaluateApproval',
+    },
+    {
+      type: 'choice',
+      name: 'EvaluateApproval',
+      choices: [
+        { when: '$.approval.decision === "approved"', next: 'ApplyChange' },
+        { when: '$.approval.decision === "rejected"', next: 'LogRejection' },
+        { default: true, next: 'RetryApproval' },
+      ],
+    },
+    {
+      type: 'domain-action',
+      name: 'ApplyChange',
+      domainId: '${domain}',
+      actionId: 'apply-change',
+      next: 'NotifyCompletion',
+    },
+    {
+      type: 'domain-action',
+      name: 'LogRejection',
+      domainId: '${domain}',
+      actionId: 'log-rejection',
+      next: 'Done',
+    },
+    {
+      type: 'domain-action',
+      name: 'RetryApproval',
+      domainId: '${domain}',
+      actionId: 'retry-approval',
+      next: 'NotifyReviewers',
+    },
+    {
+      type: 'domain-action',
+      name: 'NotifyCompletion',
+      domainId: '${domain}',
+      actionId: 'notify-completion',
+      next: 'Done',
+    },
+    {
+      type: 'flow-control',
+      control: 'succeed',
+      name: 'Done',
+    },
+  ],
+});
+`;
+}

package/src/templates/patterns/flow/multi-step-orchestration.ts

@@ -0,0 +1,70 @@
+/**
+ * Multi-step-orchestration flow pattern template.
+ * Produces: flow that orchestrates a chain of dependent domain actions.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function multiStepOrchestrationTemplate(domain: string, id: string): string {
+  const varName = camelCase(id);
+
+  return `import { defineFlow } from '@mettlecast/domain-runtime';
+
+/**
+ * ${id} — Multi-step orchestration flow.
+ *
+ * Executes a sequential pipeline of domain actions where each step
+ * depends on the output of the previous step.
+ */
+export const ${varName} = defineFlow({
+  id: '${id}',
+  owningDomain: '${domain}',
+  type: 'standard',
+  name: '${id}',
+  steps: [
+    {
+      type: 'domain-action',
+      name: 'ValidateInput',
+      domainId: '${domain}',
+      actionId: 'validate-input',
+      next: 'ProvisionResource',
+    },
+    {
+      type: 'domain-action',
+      name: 'ProvisionResource',
+      domainId: '${domain}',
+      actionId: 'provision-resource',
+      next: 'ConfigureResource',
+    },
+    {
+      type: 'domain-action',
+      name: 'ConfigureResource',
+      domainId: '${domain}',
+      actionId: 'configure-resource',
+      next: 'ActivateResource',
+    },
+    {
+      type: 'domain-action',
+      name: 'ActivateResource',
+      domainId: '${domain}',
+      actionId: 'activate-resource',
+      next: 'SendNotification',
+    },
+    {
+      type: 'domain-action',
+      name: 'SendNotification',
+      domainId: '${domain}',
+      actionId: 'send-notification',
+      next: 'Done',
+    },
+    {
+      type: 'flow-control',
+      control: 'succeed',
+      name: 'Done',
+    },
+  ],
+});
+`;
+}

package/src/templates/patterns/hook/index.ts

@@ -0,0 +1,382 @@
+/**
+ * Paginated list hook pattern — uses `useInfiniteQuery` from TanStack Query for paginated lists.
+ */
+export function paginatedListHookTemplate(name: string): string {
+  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: string): string {
+  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: string): string {
+  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: string): string {
+  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: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}