feat: update package versions to 0.9.4 across all modules; add startup hints functionality and tests

Author: yinxulai

apps/docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clarify-labs/docs",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "private": true,
   "license": "AGPL-3.0-only",
   "type": "module",

apps/www/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clarify-labs/www",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "private": true,
   "license": "AGPL-3.0-only",
   "type": "module",

extensions/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "clarify-vscode-extension",
   "displayName": "Clarify",
   "description": "Live preview for Clarify documentation projects.",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "license": "AGPL-3.0-only",
   "publisher": "taicode-labs",
   "repository": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "clarify",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "private": true,
   "license": "AGPL-3.0-only",
   "description": "An open-source documentation publishing tool built for MDX and OpenAPI.",

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clarify-labs/cli",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "license": "AGPL-3.0-only",
   "type": "module",
   "repository": {

packages/cli/source/core/env-types.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateClarifyEnvDts } from './env-types.js'
+
+describe('generateClarifyEnvDts', () => {
+  it('only exposes the public slot hook module', () => {
+    const dts = generateClarifyEnvDts([])
+
+    expect(dts).toContain("declare module 'virtual:clarify/slot'")
+    expect(dts).toContain('export function useSlot(): SlotContext')
+    expect(dts).not.toContain("declare module 'virtual:clarify/slots'")
+  })
+})

packages/cli/source/core/env-types.ts

@@ -19,18 +19,6 @@ declare module 'virtual:clarify/slot' {
 
   export function useSlot(): SlotContext
 }
-
-declare module 'virtual:clarify/slots' {
-  import type { ComponentType } from 'react'
-
-  export type RuntimeSlotEntry = {
-    plugin: string
-    /** Lazy import factory — yields the default-exported React component. */
-    component: () => Promise<{ default: ComponentType }>
-  }
-
-  export const runtimeSlots: Record<string, RuntimeSlotEntry[]>
-}
 `
 
 export function generateClarifyEnvDts(_plugins: ClarifyPlugin[]): string {

packages/cli/source/core/plugin.ts

@@ -1,4 +1,4 @@
-import { rmSync } from 'node:fs'
+import { existsSync, rmSync } from 'node:fs'
 import { isAbsolute, join, relative, resolve } from 'node:path'
 
 import mdxPlugin, { type Options as MdxPluginOptions } from '@mdx-js/rollup'
@@ -17,6 +17,7 @@ import { runBuildAssetsHooks, runBuildDoneHooks, runDevConfigureServerHooks, run
 import { resolveBuildOptions, type ClarifyBuildOptions } from './options.js'
 import { CLARIFY_DEV_PROJECT_INFO_ENDPOINT, handleProjectInfoRequest } from './project-info.js'
 import { resolveClarifySite } from './site.js'
+import { logStartupHints } from './startup.js'
 import {
   SSR_ENTRY_CODE,
   createTempEntryFile,
@@ -125,6 +126,12 @@ export function clarifyPlugin(options: ClarifyBuildOptions = {}): Plugin[] {
     name: 'clarify:core',
     async config() {
       await resolveRoutesAndSpecs()
+      logStartupHints({
+        projectRoot: root,
+        contentRoot,
+        contentDirExists: existsSync(contentRoot),
+        hasRoutes: routes.length > 0,
+      })
 
       return {
         base: projectConfig.assetPrefix,

packages/cli/source/core/startup.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { getStartupHints, logStartupHints } from './startup.js'
+
+describe('getStartupHints', () => {
+  it('only reports content-directory issues when no content root exists', () => {
+    const hints = getStartupHints({
+      projectRoot: '/tmp/my-docs',
+      contentRoot: '/tmp/my-docs/source',
+      contentDirExists: false,
+      hasRoutes: false,
+    })
+
+    expect(hints).toEqual([
+      'Content directory "source" was not found. Create it or pass --content <dir> to point Clarify at a different directory.',
+    ])
+  })
+
+  it('recommends adding an entry page when content exists but has no routes', () => {
+    const hints = getStartupHints({
+      projectRoot: '/tmp/my-docs',
+      contentRoot: '/tmp/my-docs/docs',
+      contentDirExists: true,
+      hasRoutes: false,
+    })
+
+    expect(hints).toEqual([
+      'No content pages were found yet. Add docs/index.mdx to get started.',
+    ])
+  })
+})
+
+describe('logStartupHints', () => {
+  it('prints a warn line per startup hint', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    logStartupHints({
+      projectRoot: '/tmp/my-docs',
+      contentRoot: '/tmp/my-docs/source',
+      contentDirExists: false,
+      hasRoutes: false,
+    })
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('[clarify] Content directory'))
+    warn.mockRestore()
+  })
+})

packages/cli/source/core/startup.ts

@@ -0,0 +1,40 @@
+import { relative } from 'node:path'
+
+export type StartupHintOptions = {
+  projectRoot: string
+  contentRoot: string
+  contentDirExists: boolean
+  hasRoutes: boolean
+}
+
+function contentDirectoryLabel(projectRoot: string, contentRoot: string): string {
+  const relativePath = relative(projectRoot, contentRoot)
+  return relativePath && relativePath !== '.' ? relativePath : 'source'
+}
+
+function contentFileExampleLabel(projectRoot: string, contentRoot: string): string {
+  const label = contentDirectoryLabel(projectRoot, contentRoot)
+  return label === '.' ? 'index.mdx' : `${label}/index.mdx`
+}
+
+export function getStartupHints(options: StartupHintOptions): string[] {
+  const hints: string[] = []
+
+  if (!options.contentDirExists) {
+    const label = contentDirectoryLabel(options.projectRoot, options.contentRoot)
+    hints.push(`Content directory "${label}" was not found. Create it or pass --content <dir> to point Clarify at a different directory.`)
+  } else if (!options.hasRoutes) {
+    const example = contentFileExampleLabel(options.projectRoot, options.contentRoot)
+    hints.push(`No content pages were found yet. Add ${example} to get started.`)
+  }
+
+  return hints
+}
+
+export function logStartupHints(options: StartupHintOptions): void {
+  const hints = getStartupHints(options)
+  if (hints.length === 0) return
+
+  const message = hints.map(hint => `[clarify] ${hint}`).join('\n')
+  console.warn(message)
+}