astro-tractstack 2.0.0-rc.0

package/templates/src/utils/backend.ts

@@ -0,0 +1,243 @@
+import {
+  freshInstallStore,
+  FRESH_INSTALL_CACHE_DURATION,
+} from '@/stores/backend';
+
+/**
+ * Backend health check utilities for TractStack
+ * Handles proper failover logic between maintenance and 404 responses
+ */
+
+export interface BackendHealthResponse {
+  isHealthy: boolean;
+  shouldRedirectToMaint: boolean;
+  shouldReturn404: boolean;
+}
+
+/**
+ * Check if backend is healthy and determine appropriate response action
+ * @param goBackend - Backend URL
+ * @param tenantId - Tenant ID for headers
+ * @param httpStatus - The original HTTP status from the failed request
+ * @returns Object indicating what action to take
+ */
+export async function checkBackendHealth(
+  goBackend: string,
+  tenantId: string,
+  httpStatus: number
+): Promise<BackendHealthResponse> {
+  try {
+    // Quick health check with short timeout
+    const healthCheck = await fetch(`${goBackend}/api/v1/health`, {
+      headers: { 'X-Tenant-ID': tenantId },
+      signal: AbortSignal.timeout(3000), // 3 second timeout
+    });
+
+    const isHealthy = healthCheck.ok;
+
+    // If backend is healthy but we got 404/500, it's a legitimate content error
+    if (isHealthy && (httpStatus === 404 || httpStatus >= 500)) {
+      return {
+        isHealthy: true,
+        shouldRedirectToMaint: false,
+        shouldReturn404: true,
+      };
+    }
+
+    // If backend is unhealthy, go to maintenance
+    if (!isHealthy) {
+      return {
+        isHealthy: false,
+        shouldRedirectToMaint: true,
+        shouldReturn404: false,
+      };
+    }
+
+    // Backend is healthy and status is not 404/500 - shouldn't happen but handle gracefully
+    return {
+      isHealthy: true,
+      shouldRedirectToMaint: false,
+      shouldReturn404: true,
+    };
+  } catch (healthError) {
+    // Health check failed - backend is likely down
+    return {
+      isHealthy: false,
+      shouldRedirectToMaint: true,
+      shouldReturn404: false,
+    };
+  }
+}
+
+/**
+ * Handle response based on backend health check
+ * @param healthResponse - Result from checkBackendHealth
+ * @param originalStatus - Original HTTP status code
+ * @param currentPath - Current URL path for redirect
+ * @returns Astro Response or redirect
+ */
+export function handleBackendResponse(
+  healthResponse: BackendHealthResponse,
+  originalStatus: number,
+  currentPath: string
+) {
+  if (healthResponse.shouldRedirectToMaint) {
+    // Backend is down - redirect to maintenance page
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: `/maint?from=${encodeURIComponent(currentPath)}`,
+      },
+    });
+  }
+
+  if (healthResponse.shouldReturn404) {
+    // Backend is up but content not found - return proper error
+    const statusText =
+      originalStatus === 404
+        ? 'Story not found'
+        : originalStatus >= 500
+          ? 'Server error'
+          : 'Request failed';
+
+    return new Response(null, {
+      status: originalStatus,
+      statusText,
+    });
+  }
+
+  // Fallback - should not reach here
+  return new Response(null, {
+    status: 500,
+    statusText: 'Unexpected error',
+  });
+}
+
+/**
+ * Handle failed backend response - determines if backend is down or content is missing
+ * This replaces the entire if (!response.ok) block in Astro pages
+ * @param response - The failed fetch response
+ * @param goBackend - Backend URL
+ * @param tenantId - Tenant ID
+ * @param currentPath - Current URL path
+ * @returns Astro Response or null (if response was actually ok)
+ */
+export async function handleFailedResponse(
+  response: Response,
+  goBackend: string,
+  tenantId: string,
+  currentPath: string
+): Promise<Response | null> {
+  if (response.ok) {
+    return null; // Response was actually ok, let caller handle it normally
+  }
+
+  if (response.status >= 500 || response.status === 404) {
+    // Use the backend health helper to determine proper response
+    const healthResponse = await checkBackendHealth(
+      goBackend,
+      tenantId,
+      response.status
+    );
+
+    return handleBackendResponse(healthResponse, response.status, currentPath);
+  }
+
+  // Other error status codes (401, 403, etc.) - return as-is
+  return new Response(null, {
+    status: response.status,
+    statusText: 'Story not found',
+  });
+}
+
+/**
+ * Performs a pre-check to detect if the system requires initial setup.
+ * This function is designed to work idiomatically with Astro's control flow.
+ *
+ * - If setup is needed, it returns a Response object to trigger a redirect.
+ * - If the system is healthy, it completes silently by returning void.
+ * - If an unexpected error occurs (e.g., backend is unreachable), it logs
+ * the error and returns a Response object to redirect to a maintenance page.
+ *
+ * @param tenantId The tenant ID for which to perform the health check.
+ * @returns {Promise<Response | void>} A promise that resolves to a Response object
+ * if a redirect is needed, or void if the request can proceed.
+ */
+export async function preHealthCheck(
+  tenantId: string
+): Promise<Response | void> {
+  const currentState = freshInstallStore.get();
+  const now = Date.now();
+
+  // Fast path: Use cache if the tenant is known to be active and the check is recent.
+  if (
+    currentState.activeTenants.includes(tenantId) &&
+    !currentState.needsSetup &&
+    now - currentState.lastChecked < FRESH_INSTALL_CACHE_DURATION
+  ) {
+    return;
+  }
+
+  const goBackend =
+    import.meta.env.PUBLIC_GO_BACKEND || 'http://localhost:8080';
+  const healthCheckUrl = `${goBackend}/api/v1/health`;
+
+  try {
+    const response = await fetch(healthCheckUrl, {
+      headers: { 'X-Tenant-ID': tenantId },
+      signal: AbortSignal.timeout(5000), // 5-second timeout
+    });
+
+    if (!response.ok) {
+      const responseBody = await response.text();
+      console.error(
+        `[preHealthCheck] Health check responded with a non-OK status: ${response.status}`,
+        { tenantId, responseBody }
+      );
+      throw new Error(
+        `Health check failed with status code: ${response.status}`
+      );
+    }
+
+    const result = await response.json();
+
+    if (result.needsSetup === true) {
+      // System requires initial setup. Update state and return a redirect Response.
+      freshInstallStore.set({
+        needsSetup: true,
+        activeTenants: currentState.activeTenants.filter(
+          (id) => id !== tenantId
+        ),
+        lastChecked: now,
+      });
+
+      return new Response(null, {
+        status: 302,
+        headers: { Location: '/storykeep/init' },
+      });
+    }
+
+    // If we reach here, the system is considered initialized and healthy.
+    // Update the cache to reflect this state and continue.
+    freshInstallStore.set({
+      needsSetup: false,
+      activeTenants: [...new Set([...currentState.activeTenants, tenantId])],
+      lastChecked: now,
+    });
+  } catch (error) {
+    // For any error (network failure, JSON parsing error, etc.), log it
+    // and return a Response to redirect to the maintenance page.
+    console.error(
+      '[preHealthCheck] An unexpected error occurred during the health check process.',
+      { tenantId, originalError: error }
+    );
+
+    const maintUrl = `/maint?from=${encodeURIComponent(
+      globalThis.location?.pathname || '/'
+    )}`;
+    return new Response(null, {
+      status: 302,
+      headers: { Location: maintUrl },
+    });
+  }
+}

package/templates/src/utils/compositor/TemplateMarkdowns.ts

@@ -0,0 +1,118 @@
+import { getColor } from './tailwindColors';
+import type { TemplateMarkdown } from '@/types/compositorTypes';
+import type { Theme } from '@/types/tractstack';
+
+export const getTemplateSimpleMarkdown = (theme: Theme) => {
+  return {
+    nodeType: 'Markdown',
+    id: '',
+    parentId: '',
+    type: 'markdown',
+    markdownId: '01JD2RGG95PMZ7E6V5MBX9Q3FJ',
+    defaultClasses: {
+      h2: {
+        mobile: {
+          fontWEIGHT: 'bold',
+          textCOLOR: getColor(
+            {
+              light: 'brand-7',
+              'light-bw': 'brand-1',
+              'light-bold': 'brand-5',
+              dark: 'brand-4',
+              'dark-bw': 'brand-8',
+              'dark-bold': 'brand-3',
+            },
+            theme
+          ),
+          textSIZE: '4xl',
+          fontFACE: 'action',
+        },
+        tablet: {
+          textSIZE: '5xl',
+        },
+        desktop: {
+          textSIZE: '6xl',
+        },
+      },
+      h3: {
+        mobile: {
+          fontWEIGHT: 'bold',
+          textCOLOR: 'brand-5',
+          textSIZE: 'xl',
+          fontFACE: 'action',
+        },
+        tablet: {
+          textSIZE: '3xl',
+        },
+        desktop: {},
+      },
+      h4: {
+        mobile: {
+          textCOLOR: 'brand-5',
+          textSIZE: 'xl',
+          fontFACE: 'action',
+        },
+        tablet: {
+          textSIZE: '2xl',
+        },
+        desktop: {},
+      },
+      p: {
+        mobile: {
+          textCOLOR: 'myoffwhite',
+          textSIZE: 'lg',
+          lineHEIGHT: 'snug',
+          mt: '2.5',
+        },
+        tablet: {
+          textSIZE: 'xl',
+          mt: '3.5',
+        },
+        desktop: {},
+      },
+    },
+    parentClasses: [
+      {
+        mobile: {
+          mt: '10',
+          mb: '5',
+          mx: '5',
+        },
+        tablet: {
+          mt: '20',
+          mb: '10',
+          mx: '10',
+        },
+        desktop: {},
+      },
+      {
+        mobile: {
+          maxW: 'none',
+          mx: 'auto',
+        },
+        tablet: {
+          maxW: 'screen-lg',
+        },
+        desktop: {
+          maxW: 'screen-xl',
+        },
+      },
+      {
+        mobile: {
+          px: '9',
+          pt: '12',
+          pb: '10',
+          textALIGN: 'left',
+          textWRAP: 'pretty',
+          maxW: 'none',
+        },
+        tablet: {
+          px: '14',
+        },
+        desktop: {
+          px: '32',
+        },
+      },
+    ],
+  } as TemplateMarkdown;
+};

package/templates/src/utils/compositor/TemplateNodes.ts

@@ -0,0 +1,138 @@
+import type { TemplateNode } from '@/types/compositorTypes';
+
+export const TemplateH2Node = {
+  nodeType: 'TagElement',
+  tagName: 'h2',
+  nodes: [
+    {
+      copy: 'Catchy title',
+      tagName: 'text',
+    },
+  ],
+} as TemplateNode;
+
+export const TemplateH3Node = {
+  nodeType: 'TagElement',
+  tagName: 'h3',
+  nodes: [
+    {
+      copy: 'Catchy sub-title',
+      tagName: 'text',
+    },
+  ],
+} as TemplateNode;
+
+export const TemplateH4Node = {
+  nodeType: 'TagElement',
+  tagName: 'h4',
+  nodes: [
+    {
+      copy: 'Catchy sub-title',
+      tagName: 'text',
+    },
+  ],
+} as TemplateNode;
+
+export const TemplatePNode = {
+  nodeType: 'TagElement',
+  tagName: 'p',
+  nodes: [
+    {
+      copy: '...',
+      tagName: 'text',
+    },
+  ],
+} as TemplateNode;
+
+export const TemplateOLNode = {
+  nodeType: 'TagElement',
+  tagName: 'ol',
+  nodes: [
+    {
+      copy: '...',
+      tagName: 'text',
+    },
+  ],
+} as TemplateNode;
+
+export const TemplateULNode = {
+  nodeType: 'TagElement',
+  tagName: 'ul',
+  nodes: [
+    {
+      copy: '...',
+      tagName: 'text',
+    },
+  ],
+} as TemplateNode;
+
+export const TemplateLINode = {
+  nodeType: 'TagElement',
+  tagName: 'li',
+  nodes: [
+    {
+      copy: '...',
+      tagName: 'text',
+    },
+  ],
+} as TemplateNode;
+
+//export const TemplateAsideNode = {
+//  nodeType: "TagElement",
+//  tagName: "aside",
+//  nodes: [
+//    {
+//      copy: "aside node",
+//      tagName: "text",
+//    },
+//  ],
+//} as TemplateNode;
+
+export const TemplateImgNode = {
+  nodeType: 'TagElement',
+  tagName: 'img',
+  src: '/static.jpg',
+  alt: 'New image coming soon!',
+} as TemplateNode;
+
+export const TemplateYoutubeNode = {
+  nodeType: 'TagElement',
+  tagName: 'code',
+  copy: 'youtube(kJI4XdqiiAI|The Free Web Press)',
+  codeHookParams: ['kJI4XdqiiAI', 'The Free Web Press'],
+} as TemplateNode;
+
+export const TemplateToggleNode = {
+  nodeType: 'TagElement',
+  tagName: 'code',
+  copy: 'toggle(BeliefTag|This is so awesome, right?!)',
+  codeHookParams: ['BeliefTag', 'This is so awesome, right?!'],
+} as TemplateNode;
+
+export const TemplateBeliefNode = {
+  nodeType: 'TagElement',
+  tagName: 'code',
+  copy: 'belief(BeliefTag|likert|prompt)',
+  codeHookParams: ['BeliefTag', 'likert', 'prompt'],
+} as TemplateNode;
+
+export const TemplateBunnyNode = {
+  nodeType: 'TagElement',
+  tagName: 'code',
+  copy: 'bunny(id|title)',
+  codeHookParams: ['id', 'title'],
+} as TemplateNode;
+
+export const TemplateEmailSignUpNode = {
+  nodeType: 'TagElement',
+  tagName: 'code',
+  copy: 'signup(major|Keep in touch!|false)',
+  codeHookParams: ['major', 'Keep in touch!', 'false'],
+} as TemplateNode;
+
+export const TemplateIdentifyAsNode = {
+  nodeType: 'TagElement',
+  tagName: 'code',
+  copy: 'identifyAs(BeliefTag|TARGET_VALUE|prompt)',
+  codeHookParams: ['BeliefTag', 'TARGET_VALUE', 'prompt'],
+} as TemplateNode;

package/templates/src/utils/compositor/TemplatePanes.ts

@@ -0,0 +1,100 @@
+import {
+  //TemplateAsideNode,
+  TemplateH2Node,
+  TemplateH3Node,
+  TemplatePNode,
+} from './TemplateNodes';
+import { getTemplateSimpleMarkdown } from './TemplateMarkdowns';
+import { getColor, tailwindToHex } from './tailwindColors';
+import type { TemplatePane } from '@/types/compositorTypes';
+import type { Theme } from '@/types/tractstack';
+
+export const getTemplateVisualBreakPane = (variant: string) => {
+  // colour will be set on insert based on adjacent nodes
+  const breakConfig = {
+    collection: 'kCz',
+    image: variant,
+    svgFill: 'black',
+  };
+  return {
+    nodeType: 'Pane',
+    title: '',
+    slug: '',
+    isDecorative: true,
+    bgColour: 'white',
+    bgPane: {
+      nodeType: 'BgPane',
+      type: 'visual-break',
+      breakDesktop: breakConfig,
+      breakTablet: breakConfig,
+      breakMobile: breakConfig,
+    },
+  } as TemplatePane;
+};
+
+export const getTemplateSimplePane = (
+  theme: Theme,
+  brand: string,
+  useOdd: boolean = false
+) => {
+  return {
+    nodeType: 'Pane',
+    title: '',
+    slug: '',
+    bgColour: tailwindToHex(
+      getColor(
+        {
+          light: !useOdd ? 'brand-2' : 'white',
+          'light-bw': !useOdd ? 'white' : 'brand-2',
+          'light-bold': !useOdd ? 'brand-2' : 'white',
+          dark: !useOdd ? 'black' : 'brand-1',
+          'dark-bw': !useOdd ? 'black' : 'brand-1',
+          'dark-bold': !useOdd ? 'brand-1' : 'black',
+        },
+        theme
+      ),
+      brand
+    ),
+    markdown: {
+      ...getTemplateSimpleMarkdown(theme),
+      nodes: [
+        { ...TemplateH2Node, copy: 'H2 node in simple pane' },
+        { ...TemplatePNode, copy: 'P node in simple pane' },
+        { ...TemplateH3Node, copy: 'H3 node in simple pane' },
+        //{ ...TemplateAsideNode, copy: "Aside node in simple pane" },
+      ],
+    },
+  } as TemplatePane;
+};
+
+export const getTemplateMarkdownPane = (
+  theme: Theme,
+  variant: string,
+  brand: string,
+  useOdd: boolean = false
+) => {
+  console.log(`variant: ${variant}`);
+  return {
+    nodeType: 'Pane',
+    title: '',
+    slug: '',
+    bgColour: tailwindToHex(
+      getColor(
+        {
+          light: !useOdd ? 'brand-2' : 'white',
+          'light-bw': !useOdd ? 'white' : 'brand-2',
+          'light-bold': !useOdd ? 'brand-2' : 'white',
+          dark: !useOdd ? 'black' : 'brand-1',
+          'dark-bw': !useOdd ? 'black' : 'brand-1',
+          'dark-bold': !useOdd ? 'brand-1' : 'black',
+        },
+        theme
+      ),
+      brand
+    ),
+    markdown: {
+      ...getTemplateSimpleMarkdown(theme),
+      markdownBody: `## add a catchy title here\n\nyour story continues... and continues... and continues... and continues... and continues... and continues... with nice layout and typography.\n\n[Try it now!](try)   [Learn more](learn)\n`,
+    },
+  } as TemplatePane;
+};

package/templates/src/utils/compositor/allowInsert.ts

@@ -0,0 +1,100 @@
+import type { Tag, FlatNode } from '@/types/compositorTypes';
+
+const allowInsert = (
+  node: FlatNode,
+  tagName: Tag,
+  tagNameNew: Tag,
+  tagNameAdjacent?: Tag
+): boolean => {
+  switch (tagName) {
+    case 'p':
+    case 'h2':
+    case 'h3':
+    case 'h4':
+    case 'h5':
+    case 'ul':
+    case 'ol':
+      {
+        switch (tagNameNew) {
+          case 'bunny':
+          case 'yt':
+          case 'belief':
+          case 'toggle':
+          case 'identify':
+          case 'signup':
+          case 'img':
+            //if (tagName === `ul` || tagNameAdjacent === `ul`) return false;
+            return true;
+          case 'p':
+          case 'h2':
+          case 'h3':
+          case 'h4':
+          case 'h5':
+            if (!tagNameAdjacent) return true;
+            switch (tagNameAdjacent) {
+              case 'p':
+              case 'h2':
+              case 'h3':
+              case 'h4':
+              case 'h5':
+              case 'ul':
+              case 'ol':
+                return true;
+
+              default:
+                console.log(
+                  `1 miss on allowInsert: tagName:${tagName} tagNameNew:${tagNameNew} tagNameAdjacent:${tagNameAdjacent}`
+                );
+            }
+            break;
+
+          default:
+            console.log(
+              `2 miss on allowInsert: tagName:${tagName} tagNameNew:${tagNameNew} tagNameAdjacent:${tagNameAdjacent}`
+            );
+        }
+      }
+      break;
+
+    case 'li': {
+      switch (tagNameNew) {
+        case 'bunny':
+        case 'yt':
+        case 'belief':
+        case 'toggle':
+        case 'identify':
+        case 'signup':
+          return false;
+        case 'img':
+          if (node.tagNameCustom === `img` && tagNameAdjacent !== `ul`)
+            return true;
+          return false;
+        case 'p':
+        case 'h2':
+        case 'h3':
+        case 'h4':
+        case 'h5':
+          if (
+            node.tagNameCustom &&
+            [`p`, `h2`, `h3`, `h4`, `h5`].includes(node.tagNameCustom)
+          )
+            // treat these as li, unless this li is for image or widget
+            return true;
+          return false;
+        default:
+          console.log(
+            `3 miss on allowInsert: tagName:${tagName} tagNameNew:${tagNameNew} tagNameAdjacent:${tagNameAdjacent}`
+          );
+      }
+      break;
+    }
+
+    default:
+      console.log(
+        `miss on allowInsert: tagName:${tagName} tagNameNew:${tagNameNew} tagNameAdjacent:${tagNameAdjacent}`
+      );
+  }
+  return false;
+};
+
+export default allowInsert;