@clarify-labs/cli 0.9.3 → 0.10.0

package/output/index.d.ts

@@ -1,6 +1,8 @@
-export { clarifyPlugin } from './core/plugin.js';
-export { defineConfig } from './core/user-config.js';
-export type { Plugin } from 'vite';
+export { createViteAdapter } from './core/adapters.js';
+export { ClarifyEngine, createClarifyEngine } from './core/engine/engine.js';
+export { defineConfig } from './core/config/user-config.js';
+export type { ClarifyEngineRuntime, PrepareOptions } from './core/engine/engine.js';
+export type { PhaseName, TapPhaseName, TapHook, InterceptHook, PipelineHook, CollectorHook } from './core/engine/phases.js';
 export * from './types.js';
-export type { ClarifyConfig } from './core/user-config.js';
+export type { ClarifyConfig } from './core/config/user-config.js';
 export type { UISlotName, SlotContext, UISlotRegistration } from '@clarify-labs/renderer';

package/output/index.js

@@ -1,2 +1,2 @@
-import { i as defineConfig, t as clarifyPlugin } from "./plugin-poS3N83A.js";
-export { clarifyPlugin, defineConfig };
+import { c as defineConfig, n as createClarifyEngine, s as createViteAdapter, t as ClarifyEngine } from "./engine-3f5Tpa-6.js";
+export { ClarifyEngine, createClarifyEngine, createViteAdapter, defineConfig };

package/output/parsers/content/content.d.ts

@@ -0,0 +1,20 @@
+import { ClarifyContentKind, ClarifyContentTransformInput, ClarifyHookContext, ClarifyPlugin } from '../../types.js';
+export type ProcessedMdxContent = {
+    frontmatter: Record<string, unknown>;
+    content: string;
+};
+export type ContentTransform = (input: ClarifyContentTransformInput) => Promise<ClarifyContentTransformInput> | ClarifyContentTransformInput;
+export type ContentProcessor = {
+    processMdx(source: string, filePath?: string): Promise<ProcessedMdxContent>;
+    processText(source: string, kind: Exclude<ClarifyContentKind, 'mdx'>, filePath?: string): Promise<string>;
+};
+export declare function createContentProcessor(transform?: ContentTransform): ContentProcessor;
+/**
+ * Creates a ContentProcessor that forwards each piece of content through the
+ * `content:transform` pipeline hook before it is parsed.
+ *
+ * Plugins that need to read content (site-discovery, openapi) call this with
+ * the plugins list from their hook context. There is no global registry -
+ * each call produces an independent processor bound to the given plugins.
+ */
+export declare function createProjectContentProcessor(plugins: ClarifyPlugin[], ctx: ClarifyHookContext): ContentProcessor;

package/output/parsers/markdown/mdx.d.ts

@@ -0,0 +1,37 @@
+import { ContentDiagnostic } from '../../types.js';
+type HastNode = {
+    type: string;
+    tagName?: string;
+    value?: string;
+    properties?: Record<string, unknown>;
+    children?: HastNode[];
+};
+export declare function rehypeParseCodeBlocks(): (tree: HastNode) => void;
+export declare function rehypeShiki(): (tree: HastNode) => Promise<void>;
+export declare function rehypeSlugSections(): (tree: HastNode) => void;
+export declare const remarkPlugins: unknown[];
+export declare const rehypePlugins: (typeof rehypeSlugSections)[];
+/**
+ * Validate MDX content for diagnostics WITHOUT running the build-time rehype
+ * pipeline (Shiki highlighting, slug injection, code-block parsing).
+ *
+ * `rehypePlugins` includes `rehypeShiki`, which loads grammar/WASM assets and
+ * is expensive. The real highlighting happens at Vite build time via the
+ * `@mdx-js/rollup` plugin (see `createMdxPlugin` in `core/adapters.ts`), which
+ * runs the full remark + rehype pipeline. Re-running it here, during route
+ * discovery (Phase 3), would compile every `.mdx` file twice and invoke Shiki
+ * once per file per `engine.refresh()` — see ARCHITECTURE.md §2.2 which states
+ * "不应在 core 中执行代码高亮".
+ *
+ * The remark pipeline still runs (shared with the Vite plugin via
+ * `remarkPlugins`), so MDX/JSX syntax errors — the only class of error this
+ * diagnostic is meant to surface ahead of the Vite build — are caught. The
+ * output is discarded; only the thrown error is used.
+ */
+export declare function compileMdxContent(content: string, filePath?: string, projectRoot?: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    diagnostic: ContentDiagnostic;
+}>;
+export {};

package/output/{core → parsers/router}/dev-routes.d.ts

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { ContentRoute, ResolvedProjectConfig } from '../types.js';
+import { ClarifyProjectContext, ContentRoute } from '../../types.js';
 /**
  * Dev-only HTTP endpoint that exposes the in-memory route manifest so external
  * tools (e.g. the VS Code extension) can resolve a content file path to its
@@ -55,4 +55,4 @@ export declare function inferRouteForFile(filePath: string, contentRoot: string,
  * Handle a request to the dev route endpoint. Pure function — does not touch
  * the network directly, only reads the request body and writes to `res`.
  */
-export declare function handleDevRouteRequest(req: IncomingMessage, res: ServerResponse, routes: ContentRoute[], projectConfig: ResolvedProjectConfig, contentRoot: string): Promise<void>;
+export declare function handleDevRouteRequest(req: IncomingMessage, res: ServerResponse, routes: ContentRoute[], context: ClarifyProjectContext): Promise<void>;

package/output/parsers/{routes.d.ts → routes/routes.d.ts}

@@ -1,5 +1,5 @@
-import { ContentRoute, ContentSection, ClarifyNavigationNode, ClarifyPagesConfig, ClarifyPagesGroup, ClarifyLocalizedText, ClarifyTabsConfig, LocalizedNavigation, LocalizedTabbedNavigation, ResolvedClarifyI18nConfig, TabbedNavigation } from '../types.js';
-import { ContentProcessor } from './content.js';
+import { ContentRoute, ContentSection, ClarifyNavigationNode, ClarifyPagesConfig, ClarifyPagesGroup, ClarifyLocalizedText, ClarifyTabsConfig, LocalizedNavigation, LocalizedTabbedNavigation, ResolvedClarifyI18nConfig, TabbedNavigation } from '../../types.js';
+import { ContentProcessor } from '../content/content.js';
 export type FindContentRoutesOptions = {
     contentProcessor?: ContentProcessor;
 };

package/output/parsers/{routes.test-utils.d.ts → routes/routes.test-utils.d.ts}

@@ -1,3 +1,3 @@
-import { ContentRoute, ResolvedClarifyI18nConfig } from '../types.js';
+import { ContentRoute, ResolvedClarifyI18nConfig } from '../../types.js';
 export declare function mdxRoute(route: Omit<ContentRoute, 'kind'>): ContentRoute;
 export declare const testI18n: ResolvedClarifyI18nConfig;

package/output/plugins/openapi/parser.d.ts

@@ -1,4 +1,4 @@
-import { ContentProcessor } from '../../parsers/content.js';
+import { ContentProcessor } from '../../parsers/content/content.js';
 import { ContentDiagnostic, ContentRoute, ContentSection, OpenAPISpec } from '../../types.js';
 export type OpenAPIParseResult = {
     ok: true;

package/output/plugins/openapi/virtual-modules.d.ts

@@ -6,10 +6,7 @@ export declare function generateOpenAPIRegistryModule(openApis: Record<string, O
 /** Generate a virtual module that exports a single spec as default. */
 export declare function generateOpenAPISpecModule(spec: OpenAPISpec): string;
 type OpenAPIPageModuleOptions = {
-    /** specFileKey used for per-spec virtual module lazy-loading (namespace 2). */
-    specKey: string;
-    /** virtual:clarify-page/… key used for OpenApisContext registry lookup (namespace 3). */
-    specRegistryKey: string;
+    spec: OpenAPISpec;
     tagFilter?: string[];
 };
 export declare function generateOpenAPIPageModule(opts: OpenAPIPageModuleOptions): string;

package/output/plugins/variables/index.d.ts

@@ -1,2 +1,3 @@
-import { ClarifyPlugin } from '../../types.js';
+import { ClarifyVariablesConfig, ClarifyPlugin } from '../../types.js';
+export declare function applyVariables(content: string, variables?: ClarifyVariablesConfig): string;
 export declare function createVariablesPlugin(): ClarifyPlugin;

package/output/types.d.ts

@@ -1,8 +1,8 @@
 import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import { HtmlTagDescriptor, ViteDevServer } from 'vite';
 import { UISlotRegistration } from '@clarify-labs/renderer';
-import { ResolvedBuildOptions } from './core/options.js';
-export type { ClarifyBuildOptions, ResolvedBuildOptions, } from './core/options.js';
+import { ResolvedBuildOptions } from './core/config/options.js';
+export type { ClarifyBuildOptions, ResolvedBuildOptions, } from './core/config/options.js';
 export type OpenAPISpec = OpenAPIV3.Document | OpenAPIV3_1.Document;
 export type ClarifyLogoConfig = string | {
     light?: string;
@@ -220,10 +220,11 @@ export type ContentSection = {
     tags?: string[];
 };
 export type ContentDiagnostic = {
+    kind: string;
     title: string;
     message: string;
+    details?: string;
     filePath?: string;
-    cause?: string;
 };
 export type ContentRoute = {
     path: string;
@@ -278,11 +279,21 @@ export type ClarifyNavigationNode = {
     children?: ClarifyNavigationNode[];
     sections?: Pick<ContentSection, 'id' | 'title' | 'badge' | 'tags'>[];
 };
-export type ClarifyHookContext = {
+export type ClarifyProjectContext = {
+    projectRoot: string;
+    contentRoot: string;
     projectConfig: ResolvedProjectConfig;
     generateOptions: ResolvedBuildOptions;
+    version: string;
+};
+export type ClarifyHookContext = ClarifyProjectContext & {
     routes: ContentRoute[];
     navigation: NavigationTree;
+    plugins: ClarifyPlugin[];
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
 };
 export type ClarifyRouteDiscoveryInput = {
     contentRoot: string;
@@ -309,10 +320,11 @@ export type ClarifyEmitAsset = {
     /** Asset content as a UTF-8 string or raw bytes. */
     source: string | Uint8Array;
 };
+export type ClarifyTapHook = (ctx: ClarifyHookContext) => Promise<void> | void;
+export type ClarifyInterceptHook = (ctx: ClarifyHookContext) => Promise<boolean> | boolean;
 export type ClarifyHooks = {
     'content:transform'?: (input: ClarifyContentTransformInput, ctx: ClarifyHookContext) => Promise<ClarifyContentTransformInput> | ClarifyContentTransformInput;
     'pages:resolved'?: (pages: ClarifyPage[], ctx: ClarifyHookContext) => Promise<ClarifyPage[]> | ClarifyPage[];
-    'page:transform'?: (page: ClarifyPage, ctx: ClarifyHookContext) => Promise<ClarifyPage> | ClarifyPage;
     'routes:discover'?: (input: ClarifyRouteDiscoveryInput, ctx: ClarifyHookContext) => Promise<ClarifyRouteDiscoveryInput> | ClarifyRouteDiscoveryInput;
     'routes:discovered'?: (routes: ContentRoute[], ctx: ClarifyHookContext) => Promise<ContentRoute[]> | ContentRoute[];
     'routes:resolved'?: (input: {
@@ -330,9 +342,32 @@ export type ClarifyHooks = {
     'dev:configureServer'?: (server: ViteDevServer, ctx: ClarifyHookContext) => Promise<void> | void;
     'build:assets'?: (ctx: ClarifyHookContext) => Promise<ClarifyEmitAsset[]> | ClarifyEmitAsset[];
     'build:done'?: (ctx: ClarifyHookContext) => Promise<void> | void;
+    'before:config:load'?: ClarifyTapHook;
+    'after:config:load'?: ClarifyTapHook;
+    'before:config:resolve'?: ClarifyTapHook;
+    'after:config:resolve'?: ClarifyTapHook;
+    'before:plugins:load'?: ClarifyTapHook;
+    'after:plugins:load'?: ClarifyTapHook;
+    'before:site:discover'?: ClarifyTapHook;
+    'after:site:discover'?: ClarifyTapHook;
+    'before:content:process'?: ClarifyTapHook;
+    'after:content:process'?: ClarifyTapHook;
+    'before:modules:build'?: ClarifyTapHook;
+    'after:modules:build'?: ClarifyTapHook;
+    'before:build'?: ClarifyTapHook;
+    'after:build'?: ClarifyTapHook;
+    'before:ssg'?: ClarifyTapHook;
+    'after:ssg'?: ClarifyTapHook;
+    'before:dev:server'?: ClarifyTapHook;
+    'after:dev:server'?: ClarifyTapHook;
+    'build:shouldRun'?: ClarifyInterceptHook;
+    'ssg:shouldRun'?: ClarifyInterceptHook;
 };
 export type ClarifyPlugin = {
     name: string;
+    enforce?: 'pre' | 'post';
+    priority?: number;
+    dependsOn?: string[];
     hooks?: Partial<ClarifyHooks>;
     slots?: UISlotRegistration[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clarify-labs/cli",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "license": "AGPL-3.0-only",
   "type": "module",
   "repository": {
@@ -39,11 +39,12 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "@clarify-labs/renderer": "0.9.3",
-    "@clarify-labs/templates": "0.9.3",
+    "@clarify-labs/renderer": "0.10.0",
+    "@clarify-labs/templates": "0.10.0",
+    "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
-    "@tailwindcss/vite": "^4.1.11",
-    "@vitejs/plugin-react": "^6.0.2",
+    "@tailwindcss/vite": "^4.3.2",
+    "@vitejs/plugin-react": "^6.0.3",
     "cac": "^7.0.0",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
@@ -58,17 +59,16 @@
     "react-zoom-pan-pinch": "^4.0.3",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
-    "shiki": "0.14.7",
+    "shiki": "4.3.0",
     "unist-util-visit": "^5.1.0",
-    "vite": "^8.0.15",
+    "vite": "^8.1.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@mdx-js/mdx": "^3.1.1",
-    "@types/react": "^19.1.8",
-    "typescript": "^5.8.3",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.9"
+    "@types/react": "^19.2.17",
+    "typescript": "^6.0.3",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.10"
   }
 }

package/output/core/content.d.ts

@@ -1,5 +0,0 @@
-import { ContentProcessor } from '../parsers/content.js';
-import { ClarifyHookContext, ClarifyPlugin } from '../types.js';
-export declare function createProjectContentProcessor(plugins: ClarifyPlugin[], ctx: ClarifyHookContext): ContentProcessor;
-export declare function setProjectContentProcessor(ctx: ClarifyHookContext, processor: ContentProcessor): void;
-export declare function getProjectContentProcessor(ctx: ClarifyHookContext): ContentProcessor | undefined;

package/output/core/plugin.d.ts

@@ -1,3 +0,0 @@
-import { Plugin } from 'vite';
-import { ClarifyBuildOptions } from './options.js';
-export declare function clarifyPlugin(options?: ClarifyBuildOptions): Plugin[];

package/output/core/site.d.ts

@@ -1,17 +0,0 @@
-import { ClarifyHookContext, ClarifyPlugin, ContentRoute, NavigationTree } from '../types.js';
-import { resolveProjectConfig } from './config.js';
-import { ClarifyBuildOptions, ResolvedBuildOptions } from './options.js';
-export type ResolvedClarifySite = {
-    root: string;
-    contentRoot: string;
-    projectConfig: ReturnType<typeof resolveProjectConfig>;
-    generateOptions: ResolvedBuildOptions;
-    plugins: ClarifyPlugin[];
-    ctx: ClarifyHookContext;
-    routes: ContentRoute[];
-    navigation: NavigationTree;
-};
-export type ResolveClarifySiteOptions = {
-    includeHtmlShellPlugin?: boolean;
-};
-export declare function resolveClarifySite(options?: ClarifyBuildOptions, resolveOptions?: ResolveClarifySiteOptions): Promise<ResolvedClarifySite>;

package/output/parsers/content.d.ts

@@ -1,11 +0,0 @@
-import { ClarifyContentKind, ClarifyContentTransformInput } from '../types.js';
-export type ProcessedMdxContent = {
-    frontmatter: Record<string, unknown>;
-    content: string;
-};
-export type ContentTransform = (input: ClarifyContentTransformInput) => Promise<ClarifyContentTransformInput> | ClarifyContentTransformInput;
-export type ContentProcessor = {
-    processMdx(source: string, filePath?: string): Promise<ProcessedMdxContent>;
-    processText(source: string, kind: Exclude<ClarifyContentKind, 'mdx'>, filePath?: string): Promise<string>;
-};
-export declare function createContentProcessor(transform?: ContentTransform): ContentProcessor;

package/output/parsers/mdx.d.ts

@@ -1,13 +0,0 @@
-type HastNode = {
-    type: string;
-    tagName?: string;
-    value?: string;
-    properties?: Record<string, unknown>;
-    children?: HastNode[];
-};
-export declare function rehypeParseCodeBlocks(): (tree: HastNode) => void;
-export declare function rehypeShiki(): (tree: HastNode) => Promise<void>;
-export declare function rehypeSlugSections(): (tree: HastNode) => void;
-export declare const remarkPlugins: unknown[];
-export declare const rehypePlugins: (typeof rehypeSlugSections)[];
-export {};

package/output/parsers/variables.d.ts

@@ -1,2 +0,0 @@
-import { ClarifyVariablesConfig } from '../types.js';
-export declare function applyVariables(content: string, variables?: ClarifyVariablesConfig): string;