@mettlecast/domain-cli 0.2.0

package/src/templates/patterns/migration/column-add.ts

@@ -0,0 +1,54 @@
+/**
+ * Column-add migration pattern template.
+ * Produces: ALTER TABLE to add a new column with optional default and NOT NULL constraint.
+ */
+
+export function columnAddTemplate(domain: string, name: string): string {
+  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/src/templates/patterns/migration/event-store.ts

@@ -0,0 +1,99 @@
+/**
+ * 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: string, name: string): string {
+  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/src/templates/patterns/migration/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Index migration pattern template.
+ * Produces: CREATE INDEX statements with CONCURRENTLY option and performance notes.
+ */
+
+export function indexTemplate(domain: string, name: string): string {
+  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/src/templates/patterns/migration/rls-policy.ts

@@ -0,0 +1,80 @@
+/**
+ * RLS-policy migration pattern template.
+ * Produces: ALTER TABLE to add/enable RLS policies on an existing table.
+ */
+
+export function rlsPolicyTemplate(domain: string, name: string): string {
+  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/src/templates/patterns/migration/tenant-scoped-table.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 function tenantScopedTableTemplate(domain: string, name: string): string {
+  const tableName = name.replace(/-/g, '_');
+  const timestamp = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14);
+
+  return `-- Migration: ${timestamp}_${name}
+-- Domain: ${domain}
+-- Pattern: tenant-scoped-table
+-- Creates a tenant-scoped table with RLS, audit columns, and updated_at trigger.
+
+CREATE TABLE IF NOT EXISTS ${tableName} (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id   UUID NOT NULL,
+  workspace_id UUID,
+  org_id      UUID,
+
+  -- Domain-specific columns
+  name        VARCHAR(255) NOT NULL,
+  status      VARCHAR(50) NOT NULL DEFAULT 'active',
+  metadata    JSONB DEFAULT '{}'::jsonb,
+
+  -- Audit columns
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+  created_by  UUID,
+  updated_by  UUID,
+  deleted_at  TIMESTAMPTZ
+);
+
+-- ── Indexes ──────────────────────────────────────────────────
+
+CREATE INDEX IF NOT EXISTS idx_${tableName}_tenant_id
+  ON ${tableName}(tenant_id);
+
+CREATE INDEX IF NOT EXISTS idx_${tableName}_workspace_id
+  ON ${tableName}(workspace_id)
+  WHERE workspace_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_${tableName}_status
+  ON ${tableName}(tenant_id, status);
+
+CREATE INDEX IF NOT EXISTS idx_${tableName}_created_at
+  ON ${tableName}(created_at DESC);
+
+-- ── Row-Level Security ───────────────────────────────────────
+
+ALTER TABLE ${tableName} ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY ${tableName}_tenant_isolation
+  ON ${tableName}
+  FOR ALL
+  TO authenticated
+  USING (tenant_id = current_setting('app.current_tenant_id')::UUID);
+
+-- ── Updated-at trigger ───────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION update_${tableName}_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_${tableName}_updated_at
+  BEFORE UPDATE ON ${tableName}
+  FOR EACH ROW
+  EXECUTE FUNCTION update_${tableName}_updated_at();
+
+-- ── Soft-delete policy ───────────────────────────────────────
+
+CREATE POLICY ${tableName}_soft_delete
+  ON ${tableName}
+  FOR SELECT
+  TO authenticated
+  USING (deleted_at IS NULL);
+`;
+}

package/src/templates/patterns/page/dashboard.ts

@@ -0,0 +1,164 @@
+/**
+ * Dashboard page pattern template — dashboard page with widget grid layout.
+ */
+export function dashboardPageTemplate(pageName: string): string {
+  const componentName = `${pageName}Page`;
+  return `import { useQuery } from '@tanstack/react-query';
+import { useTib } from '@/hooks/useTib';
+import { Page } from '@/components/layout/Page';
+import { PageHeader } from '@/components/layout/PageHeader';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { ErrorState } from '@/components/state/ErrorState';
+import { LoadingState } from '@/components/state/LoadingState';
+import { EmptyState } from '@/components/state/EmptyState';
+import { BarChart3, Activity, Users, Clock } from 'lucide-react';
+
+interface ${componentName}Props {
+  workspaceId: string;
+}
+
+interface DashboardStats {
+  totalItems: number;
+  activeItems: number;
+  recentActivity: number;
+  avgCompletion: string;
+}
+
+interface RecentItem {
+  id: string;
+  name: string;
+  status: string;
+  updatedAt: string;
+}
+
+export function ${componentName}({ workspaceId }: ${componentName}Props) {
+  const tib = useTib();
+
+  const { data: stats, isLoading: statsLoading, isError: statsError, refetch: refetchStats } = useQuery({
+    queryKey: ['dashboard-stats', workspaceId],
+    queryFn: () => tib.dashboard.get() as Promise<DashboardStats>,
+    staleTime: 30_000,
+  });
+
+  const { data: recent, isLoading: recentLoading } = useQuery({
+    queryKey: ['dashboard-recent', workspaceId],
+    queryFn: () => tib.data.list({ workspaceId, limit: 5 }) as Promise<{ items: RecentItem[] }>,
+    staleTime: 30_000,
+  });
+
+  const isLoading = statsLoading || recentLoading;
+
+  return (
+    <Page title="Dashboard" description="Overview of your workspace">
+      <Page.Header
+        breadcrumb={[{ label: '${pageName}' }]}
+      />
+      <Page.Body>
+        {statsError ? (
+          <ErrorState
+            message="Failed to load dashboard data"
+            onRetry={() => refetchStats()}
+          />
+        ) : isLoading ? (
+          <LoadingState variant="page" />
+        ) : !stats ? (
+          <EmptyState
+            icon={BarChart3}
+            title="No data yet"
+            description="Start creating items to see your dashboard."
+          />
+        ) : (
+          <div className="space-y-6">
+            {/* Stat cards grid */}
+            <div className="layout-cards">
+              <Card>
+                <CardHeader className="flex flex-row items-center justify-between pb-2">
+                  <CardTitle className="text-sm font-medium text-muted-foreground">
+                    Total Items
+                  </CardTitle>
+                  <BarChart3 className="h-4 w-4 text-muted-foreground" />
+                </CardHeader>
+                <CardContent>
+                  <p className="text-2xl font-semibold">{stats.totalItems}</p>
+                </CardContent>
+              </Card>
+
+              <Card>
+                <CardHeader className="flex flex-row items-center justify-between pb-2">
+                  <CardTitle className="text-sm font-medium text-muted-foreground">
+                    Active
+                  </CardTitle>
+                  <Activity className="h-4 w-4 text-muted-foreground" />
+                </CardHeader>
+                <CardContent>
+                  <p className="text-2xl font-semibold">{stats.activeItems}</p>
+                </CardContent>
+              </Card>
+
+              <Card>
+                <CardHeader className="flex flex-row items-center justify-between pb-2">
+                  <CardTitle className="text-sm font-medium text-muted-foreground">
+                    Recent Activity
+                  </CardTitle>
+                  <Users className="h-4 w-4 text-muted-foreground" />
+                </CardHeader>
+                <CardContent>
+                  <p className="text-2xl font-semibold">{stats.recentActivity}</p>
+                </CardContent>
+              </Card>
+
+              <Card>
+                <CardHeader className="flex flex-row items-center justify-between pb-2">
+                  <CardTitle className="text-sm font-medium text-muted-foreground">
+                    Avg Completion
+                  </CardTitle>
+                  <Clock className="h-4 w-4 text-muted-foreground" />
+                </CardHeader>
+                <CardContent>
+                  <p className="text-2xl font-semibold">{stats.avgCompletion}</p>
+                </CardContent>
+              </Card>
+            </div>
+
+            {/* Recent items */}
+            <Card>
+              <CardHeader>
+                <CardTitle className="text-lg font-semibold">Recent Items</CardTitle>
+              </CardHeader>
+              <CardContent>
+                {!recent?.items?.length ? (
+                  <EmptyState
+                    icon={BarChart3}
+                    title="No recent items"
+                    description="Items you create will appear here."
+                  />
+                ) : (
+                  <div className="space-y-3">
+                    {recent.items.map((item) => (
+                      <div
+                        key={item.id}
+                        className="flex items-center justify-between rounded-lg border border-border p-3"
+                      >
+                        <div>
+                          <p className="text-sm font-medium">{item.name}</p>
+                          <p className="text-xs text-muted-foreground">
+                            Updated {new Date(item.updatedAt).toLocaleDateString()}
+                          </p>
+                        </div>
+                        <span className="text-xs text-muted-foreground">{item.status}</span>
+                      </div>
+                    ))}
+                  </div>
+                )}
+              </CardContent>
+            </Card>
+          </div>
+        )}
+      </Page.Body>
+    </Page>
+  );
+}
+
+export default ${componentName};
+`;
+}