fix(core): surface jiti missing error and story import failures

.changeset/stories-jiti-check.md

@@ -0,0 +1,5 @@
+---
+'@kidd-cli/core': patch
+---
+
+Surface helpful error when `jiti` peer dependency is missing for stories, and display import errors instead of silent warning count when story discovery fails

packages/core/src/stories/importer.ts

@@ -1,8 +1,9 @@
 import Module from 'node:module'
 
+import type { createJiti } from 'jiti'
+
 import { toError } from '@kidd-cli/utils/fp'
 import { hasTag } from '@kidd-cli/utils/tag'
-import { createJiti } from 'jiti'
 
 import type { StoryEntry } from './types.js'
 
@@ -19,9 +20,17 @@ export interface StoryImporter {
  * Installs a TypeScript extension resolution hook so that ESM-style `.js`
  * imports (e.g. `from './alert.js'`) resolve to `.ts` / `.tsx` source files.
  *
- * @returns A frozen {@link StoryImporter} instance.
+ * Returns an error Result when the `jiti` peer dependency is not installed.
+ *
+ * @returns A Result with a frozen {@link StoryImporter} or an {@link Error}.
  */
-export function createStoryImporter(): StoryImporter {
+export function createStoryImporter(): [Error, null] | [null, StoryImporter] {
+  const [jitiError, createJiti] = resolveJiti()
+
+  if (jitiError) {
+    return [jitiError, null]
+  }
+
   installTsExtensionResolution()
 
   const jiti = createJiti(import.meta.url, {
@@ -31,26 +40,59 @@ export function createStoryImporter(): StoryImporter {
     jsx: { runtime: 'automatic' },
   })
 
-  return Object.freeze({
-    importStory: async (filePath: string): Promise<[Error, null] | [null, StoryEntry]> => {
-      try {
-        const mod = (await jiti.import(filePath)) as Record<string, unknown>
-        const entry = (mod.default ?? mod) as unknown
+  return [
+    null,
+    Object.freeze({
+      importStory: async (filePath: string): Promise<[Error, null] | [null, StoryEntry]> => {
+        try {
+          const mod = (await jiti.import(filePath)) as Record<string, unknown>
+          const entry = (mod.default ?? mod) as unknown
 
-        if (!isStoryEntry(entry)) {
-          return [new Error(`File ${filePath} does not export a valid Story or StoryGroup`), null]
-        }
+          if (!isStoryEntry(entry)) {
+            return [new Error(`File ${filePath} does not export a valid Story or StoryGroup`), null]
+          }
 
-        return [null, entry]
-      } catch (error) {
-        return [toError(error), null]
-      }
-    },
-  })
+          return [null, entry]
+        } catch (error) {
+          return [toError(error), null]
+        }
+      },
+    }),
+  ]
 }
 
 // ---------------------------------------------------------------------------
 
+/**
+ * Attempt to resolve the `jiti` package at runtime.
+ *
+ * `jiti` is an optional peer dependency of `@kidd-cli/core`, but the stories
+ * subsystem cannot function without it. Returns a Result tuple so callers can
+ * surface a helpful message instead of crashing with a cryptic import error.
+ *
+ * @private
+ * @returns A Result with the `createJiti` factory or an {@link Error}.
+ */
+function resolveJiti(): [Error, null] | [null, typeof createJiti] {
+  try {
+    const esmRequire = Module.createRequire(import.meta.url)
+    const mod = esmRequire('jiti') as { readonly createJiti: typeof createJiti }
+    return [null, mod.createJiti]
+  } catch {
+    return [
+      new Error(
+        [
+          'The "jiti" package is required to run stories but was not found.',
+          '',
+          'Install it with:',
+          '  pnpm add jiti',
+        ].join('\n')
+      ),
+      null,
+    ]
+  }
+}
+
 /**
  * TypeScript extensions to try when a `.js` import fails to resolve.
  *

packages/core/src/stories/viewer/stories-check.tsx

@@ -46,7 +46,15 @@ export function StoriesCheck({ include }: StoriesCheckProps): ReactElement {
     }
     started.current = true
 
-    const importer = createStoryImporter()
+    const [importerError, importer] = createStoryImporter()
+
+    if (importerError) {
+      process.exitCode = 1
+      ctx.log.error(importerError.message)
+      exit()
+      return
+    }
+
     const cwd = process.cwd()
     const includePatterns = buildIncludePatterns(include)
 

packages/core/src/stories/viewer/stories-output.tsx

@@ -64,7 +64,13 @@ export function StoriesOutput({ filter, include }: StoriesOutputProps): ReactEle
   const { exit } = useApp()
 
   useEffect(() => {
-    const importer = createStoryImporter()
+    const [importerError, importer] = createStoryImporter()
+
+    if (importerError) {
+      setState({ phase: 'error', message: importerError.message })
+      return
+    }
+
     const cwd = process.cwd()
     const includePatterns = buildIncludePatterns(include)
 

packages/core/src/stories/viewer/stories-screen.tsx

@@ -1,10 +1,11 @@
 import process from 'node:process'
 
-import { Text } from 'ink'
+import { Box, Text } from 'ink'
 import type { ReactElement } from 'react'
 import { useEffect, useState } from 'react'
 import { P, match } from 'ts-pattern'
 
+import type { DiscoverError } from '../discover.js'
 import { discoverStories } from '../discover.js'
 import { createStoryImporter } from '../importer.js'
 import { createStoryRegistry } from '../registry.js'
@@ -36,7 +37,8 @@ interface StoriesScreenProps {
  */
 type DiscoveryState =
   | { readonly phase: 'loading' }
-  | { readonly phase: 'empty'; readonly warningCount: number }
+  | { readonly phase: 'error'; readonly message: string }
+  | { readonly phase: 'empty'; readonly errors: readonly DiscoverError[] }
   | { readonly phase: 'ready' }
 
 // ---------------------------------------------------------------------------
@@ -81,7 +83,13 @@ function StoriesViewer({ include }: { readonly include?: string }): ReactElement
   const { isReloading, onReloadStart, onReloadEnd } = useReloadState()
 
   useEffect(() => {
-    const importer = createStoryImporter()
+    const [importerError, importer] = createStoryImporter()
+
+    if (importerError) {
+      setState({ phase: 'error', message: importerError.message })
+      return () => {}
+    }
+
     const cwd = process.cwd()
     const includePatterns = buildIncludePatterns(include)
 
@@ -96,15 +104,15 @@ function StoriesViewer({ include }: { readonly include?: string }): ReactElement
       entries.map(([name, entry]) => registry.set(name, entry))
 
       if (entries.length === 0) {
-        setState({ phase: 'empty', warningCount: result.errors.length })
+        setState({ phase: 'empty', errors: result.errors })
         return
       }
 
       setState({ phase: 'ready' })
     }
 
     run().catch(() => {
-      setState({ phase: 'empty', warningCount: 0 })
+      setState({ phase: 'empty', errors: [] })
     })
 
     const [watchError, watcher] = createStoryWatcher({
@@ -126,11 +134,23 @@ function StoriesViewer({ include }: { readonly include?: string }): ReactElement
 
   return match(state)
     .with({ phase: 'loading' }, () => <Text>Discovering stories...</Text>)
-    .with({ phase: 'empty' }, ({ warningCount }) => (
-      <Text>
-        No stories found ({warningCount} warnings). Create a .stories.tsx file in your src/
-        directory to get started.
-      </Text>
+    .with({ phase: 'error' }, ({ message }) => <Text color="red">{message}</Text>)
+    .with({ phase: 'empty' }, ({ errors }) => (
+      <Box flexDirection="column">
+        <Text>
+          No stories found. Create a .stories.tsx file in your src/ directory to get started.
+        </Text>
+        {errors.length > 0 && (
+          <Box flexDirection="column" marginTop={1}>
+            <Text color="yellow">{errors.length} file(s) failed to import:</Text>
+            {errors.map((e) => (
+              <Text key={e.filePath} dimColor>
+                {'  '}{e.filePath}: {e.message}
+              </Text>
+            ))}
+          </Box>
+        )}
+      </Box>
     ))
     .with({ phase: 'ready' }, () => <StoriesApp registry={registry} isReloading={isReloading} />)
     .exhaustive()