@clarify-labs/cli 0.9.3 → 0.10.0

package/output/core/engine/engine.d.ts

@@ -0,0 +1,68 @@
+import { ConfigEnv, Plugin } from 'vite';
+import { ClarifyEmitAsset, ClarifyHtmlTransformInput, ClarifyPlugin, ContentRoute, NavigationTree, ClarifyProjectContext } from '../../types.js';
+import { ClarifyBuildOptions } from '../config/options.js';
+import { runDevConfigureServerHooks } from '../plugin/hooks.js';
+import { VirtualModules } from '../runtime/virtual-modules.js';
+import { ClarifyContext } from './context.js';
+import { ClarifyEngineRuntime, PrepareOptions } from './types.js';
+export type { ClarifyEngineMode, ClarifyEngineRuntime, PrepareOptions } from './types.js';
+export declare class ClarifyEngine {
+    readonly options: ClarifyBuildOptions;
+    readonly root: string;
+    configFilePath?: string;
+    readonly ctx: ClarifyContext;
+    private runtime;
+    private virtualModules;
+    private buildEnabled;
+    private initializedOptions?;
+    constructor(options?: ClarifyBuildOptions);
+    configureRuntime(runtime: Partial<ClarifyEngineRuntime>): void;
+    initialize(env?: ConfigEnv, options?: ClarifyBuildOptions, prepareOptions?: PrepareOptions): Promise<ClarifyBuildOptions>;
+    /**
+     * Runs the full pre-build/pre-dev preparation: initialize (config load +
+     * resolve + plugins:load), site discovery (routes + navigation), and module
+     * building. This is the single entry point that prepares the engine before
+     * handing it to a Vite adapter or running a check, so callers never need to
+     * call initialize/discoverSite separately.
+     *
+     * Options:
+     * - `force`: re-run even if already prepared (config-file hot reload).
+     * - `htmlShell`: toggle the HTML shell builtin plugin (default true).
+     * - `skipModules`: skip `buildModules()` (check command).
+     * - `skipHints`: skip `logStartupHints()` (check command).
+     *
+     * Idempotent: calling prepare() again with the same env is a no-op unless
+     * `force` is set.
+     */
+    prepare(env?: ConfigEnv, options?: ClarifyBuildOptions, prepareOptions?: PrepareOptions): Promise<ClarifyBuildOptions>;
+    get projectConfig(): ClarifyContext['projectConfig'];
+    get generateOptions(): ClarifyContext['generateOptions'];
+    get contentRoot(): string;
+    get routes(): ContentRoute[];
+    get navigation(): NavigationTree;
+    get plugins(): ClarifyPlugin[];
+    get modules(): VirtualModules;
+    loadModule(id: string): string | null;
+    discoverSite(): Promise<void>;
+    logStartupHints(): void;
+    buildModules(): Promise<void>;
+    writeEnvTypes(): void;
+    hasContentRouteForFile(filePath: string): boolean;
+    collectBuildAssets(): Promise<ClarifyEmitAsset[]>;
+    beginBuild(): Promise<boolean>;
+    endBuild(): Promise<void>;
+    shouldRunBuild(): boolean;
+    configureDevServer(server: Parameters<typeof runDevConfigureServerHooks>[1]): Promise<void>;
+    runBuildDone(): Promise<void>;
+    runSSG(): Promise<void>;
+    refresh(): Promise<void>;
+    /**
+     * Runs the `html:transform` pipeline hook and returns the transformed
+     * input. Adapters call this from their `transformIndexHtml` hook instead
+     * of invoking `runHooks` directly, keeping hook execution inside Engine.
+     */
+    transformHtml(input: ClarifyHtmlTransformInput): Promise<ClarifyHtmlTransformInput>;
+    runtimeContext(): ClarifyProjectContext;
+    createSSGVirtualPlugin(): Plugin;
+}
+export declare function createClarifyEngine(options?: ClarifyBuildOptions): ClarifyEngine;

package/output/core/engine/phases.d.ts

@@ -0,0 +1,10 @@
+import { ClarifyHookContext, ClarifyPlugin } from '../../types.js';
+export type PhaseName = 'config:load' | 'config:resolve' | 'plugins:load' | 'site:discover' | 'content:process' | 'modules:build' | 'build' | 'ssg' | 'dev:server';
+export type TapPhaseName = `before:${PhaseName}` | `after:${PhaseName}`;
+export type TapHook = (ctx: ClarifyHookContext) => Promise<void> | void;
+export type InterceptHook = (ctx: ClarifyHookContext) => Promise<boolean> | boolean;
+export type PipelineHook<Input> = (input: Input, ctx: ClarifyHookContext) => Promise<Input> | Input;
+export type CollectorHook<Result> = (ctx: ClarifyHookContext) => Promise<Result> | Result;
+export declare function runTapHooks(plugins: ClarifyPlugin[], hookName: TapPhaseName, ctx: ClarifyHookContext): Promise<void>;
+export declare function runInterceptHooks(plugins: ClarifyPlugin[], hookName: 'build:shouldRun' | 'ssg:shouldRun', ctx: ClarifyHookContext): Promise<boolean>;
+export declare function runPhase<T>(plugins: ClarifyPlugin[], phase: PhaseName, ctx: ClarifyHookContext, task: () => Promise<T> | T): Promise<T>;

package/output/core/engine/types.d.ts

@@ -0,0 +1,26 @@
+import { Plugin } from 'vite';
+export type ClarifyEngineMode = 'development' | 'production';
+export type PrepareOptions = {
+    /** Force re-initialization even if already prepared (used by config-file hot reload). */
+    force?: boolean;
+    /** Toggle the HTML shell builtin plugin (default: true). */
+    htmlShell?: boolean;
+    /** Skip building virtual modules (used by check command). */
+    skipModules?: boolean;
+    /** Skip startup hints logging (used by check command). */
+    skipHints?: boolean;
+};
+export type BuildSSRBundleOptions = {
+    root: string;
+    ssrEntry: string;
+    ssrOutDir: string;
+    plugins: Plugin[];
+};
+export type ClarifyEngineRuntime = {
+    command: 'build' | 'serve';
+    mode: ClarifyEngineMode | string;
+    themeEditor?: boolean;
+    outputDirectory?: string;
+    ssrPlugins?: Plugin[];
+    buildSSRBundle?: (options: BuildSSRBundleOptions) => Promise<void>;
+};

package/output/core/{builtin.d.ts → plugin/builtin.d.ts}

@@ -1,4 +1,4 @@
-import { ClarifyPlugin } from '../types.js';
+import { ClarifyPlugin } from '../../types.js';
 export type BuiltinPluginOptions = {
     htmlShell?: boolean;
 };

package/output/core/{hooks.d.ts → plugin/hooks.d.ts}

@@ -1,6 +1,7 @@
 import { ViteDevServer } from 'vite';
-import { ClarifyEmitAsset, ClarifyHookContext, ClarifyHooks, ClarifyPlugin } from '../types.js';
+import { ClarifyEmitAsset, ClarifyHookContext, ClarifyHooks, ClarifyPlugin } from '../../types.js';
 export declare function runHooks<K extends Exclude<keyof ClarifyHooks, 'build:assets' | 'build:done' | 'dev:configureServer'>>(plugins: ClarifyPlugin[], hookName: K, input: Parameters<NonNullable<ClarifyHooks[K]>>[0], ctx: ClarifyHookContext): Promise<Parameters<NonNullable<ClarifyHooks[K]>>[0]>;
 export declare function runDevConfigureServerHooks(plugins: ClarifyPlugin[], server: ViteDevServer, ctx: ClarifyHookContext): Promise<void>;
+export declare function runCollectorHooks<T>(plugins: ClarifyPlugin[], hookName: string, ctx: ClarifyHookContext): Promise<T[]>;
 export declare function runBuildAssetsHooks(plugins: ClarifyPlugin[], ctx: ClarifyHookContext): Promise<ClarifyEmitAsset[]>;
 export declare function runBuildDoneHooks(plugins: ClarifyPlugin[], ctx: ClarifyHookContext): Promise<void>;

package/output/core/plugin/manager.d.ts

@@ -0,0 +1,9 @@
+import { ClarifyPlugin } from '../../types.js';
+import { ClarifyBuildOptions } from '../config/options.js';
+import { BuiltinPluginOptions } from './builtin.js';
+export type LoadPluginsOptions = BuiltinPluginOptions & {
+    userPlugins?: ClarifyPlugin[];
+};
+export declare function sortPlugins(plugins: ClarifyPlugin[]): ClarifyPlugin[];
+export declare function loadPlugins(options?: LoadPluginsOptions): ClarifyPlugin[];
+export declare function loadBuildPlugins(options?: ClarifyBuildOptions, pluginOptions?: BuiltinPluginOptions): ClarifyPlugin[];

package/output/core/project/project-context.d.ts

@@ -0,0 +1,16 @@
+import { ConfigEnv } from 'vite';
+import { ClarifyProjectContext } from '../../types.js';
+import { resolveProjectConfig } from '../config/config.js';
+import { ClarifyBuildOptions, ResolvedBuildOptions } from '../config/options.js';
+import { ClarifyConfig } from '../config/user-config.js';
+export type ResolvedProjectContext = {
+    projectRoot: string;
+    contentRoot: string;
+    config: ClarifyConfig;
+    configFilePath?: string;
+    buildOptions: ResolvedBuildOptions;
+    resolvedOptions: ClarifyBuildOptions;
+    projectContext: ClarifyProjectContext;
+    projectConfig: ReturnType<typeof resolveProjectConfig>;
+};
+export declare function resolveProjectContext(options?: ClarifyBuildOptions, env?: ConfigEnv): Promise<ResolvedProjectContext>;

package/output/core/{project-info.d.ts → project/project-info.d.ts}

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { ResolvedProjectConfig } from '../types.js';
+import { ClarifyProjectContext } from '../../types.js';
 /**
  * Dev-only HTTP endpoint that exposes project metadata so external tooling
  * (e.g. the VS Code extension) can discover which files Clarify recognizes
@@ -34,9 +34,9 @@ export type ProjectInfoResponse = {
 /**
  * Build the project-info response payload from the resolved plugin state.
  */
-export declare function buildProjectInfo(projectRoot: string, contentRoot: string, projectConfig: ResolvedProjectConfig): ProjectInfoResponse;
+export declare function buildProjectInfo(context: ClarifyProjectContext): ProjectInfoResponse;
 /**
  * Handle a request to the project-info endpoint. Responds to any method
  * (GET is typical) with the JSON payload — there is no request body to parse.
  */
-export declare function handleProjectInfoRequest(_req: IncomingMessage, res: ServerResponse, projectRoot: string, contentRoot: string, projectConfig: ResolvedProjectConfig): void;
+export declare function handleProjectInfoRequest(_req: IncomingMessage, res: ServerResponse, context: ClarifyProjectContext): void;

package/output/core/{env-types.d.ts → runtime/env-types.d.ts}

@@ -1,4 +1,4 @@
-import { ClarifyPlugin } from '../types.js';
+import { ClarifyPlugin } from '../../types.js';
 export declare function generateClarifyEnvDts(_plugins: ClarifyPlugin[]): string;
 /**
  * Writes `clarify-env.d.ts` into the project root. Only rewrites when content

package/output/core/runtime/html-template.d.ts

@@ -0,0 +1,13 @@
+import { ClarifyProjectContext, ContentRoute, ResolvedProjectConfig } from '../../types.js';
+/** Inject `lang` (and optional `dir`) onto the `<html>` tag for the route locale. */
+export declare function injectHtmlLocaleAttributes(html: string, contextOrConfig: ClarifyProjectContext | ResolvedProjectConfig, route?: ContentRoute): string;
+/** Set, replace, or remove a `<meta name="...">` tag in `<head>`. */
+export declare function setNamedMeta(html: string, name: string, content: string | undefined): string;
+/** Remove any existing canonical link and (if a URL is resolved) inject a fresh one. */
+export declare function injectCanonicalUrl(html: string, contextOrConfig: ClarifyProjectContext | ResolvedProjectConfig, route?: ContentRoute): string;
+/**
+ * Render the SSR result into the built HTML template: set `<title>`, the
+ * description/keywords meta, the canonical link, the `<html lang/dir>`, and
+ * replace the `#root` content with the rendered app HTML.
+ */
+export declare function injectSSRIntoTemplate(template: string, appHtml: string, contextOrConfig: ClarifyProjectContext | ResolvedProjectConfig, route?: ContentRoute): string;

package/output/core/{ssg.d.ts → runtime/ssg.d.ts}

@@ -1,10 +1,10 @@
 import { Plugin } from 'vite';
-import { ResolvedProjectConfig, ContentRoute } from '../types.js';
+import { ClarifyProjectContext, ContentRoute, ResolvedProjectConfig } from '../../types.js';
+export { injectSSRIntoTemplate } from './html-template.js';
 export declare function readIndexHtml(outputDirectory: string): string | undefined;
-export declare function injectSSRIntoTemplate(template: string, appHtml: string, projectConfig: ResolvedProjectConfig, route?: ContentRoute): string;
 export declare function isNotFoundRoute(route: ContentRoute): boolean;
 export declare function routeOutputFiles(outputDirectory: string, route: ContentRoute): string[];
 export declare const SSR_ENTRY_CODE = "import { renderToHTML } from '@clarify-labs/renderer/server';\nimport { routes, navigation } from 'virtual:clarify/routes/server';\nimport { config } from 'virtual:clarify/config';\nimport { openApis } from 'virtual:clarify/openapi';\nimport { runtimeSlots } from 'virtual:clarify/slots';\n\nexport async function render(url) {\n  // Pre-resolve every slot component factory so renderToString can use\n  // them synchronously (renderToString has no Suspense support).\n  const entries = Object.values(runtimeSlots).flat()\n  await Promise.all(entries.map(async (entry) => {\n    const mod = await entry.component()\n    entry._resolved = mod.default\n  }))\n  return renderToHTML({ config, routes, navigation, openApis, runtimeSlots, url, themeEditor: config.theme.editor });\n}";
 export declare function createTempEntryFile(content: string): string;
 export declare function buildSSRBundle(root: string, ssrEntry: string, ssrOutDir: string, plugins: Plugin[]): Promise<void>;
-export declare function renderSSGRoutes(routes: ContentRoute[], projectConfig: ResolvedProjectConfig, outputDirectory: string, ssrBundlePath: string, failOnError?: boolean): Promise<void>;
+export declare function renderSSGRoutes(routes: ContentRoute[], contextOrConfig: ClarifyProjectContext | ResolvedProjectConfig, outputDirectory: string, ssrBundlePath: string, failOnError?: boolean): Promise<void>;

package/output/core/runtime/startup.d.ts

@@ -0,0 +1,8 @@
+export type StartupHintOptions = {
+    projectRoot: string;
+    contentRoot: string;
+    contentDirExists: boolean;
+    hasRoutes: boolean;
+};
+export declare function getStartupHints(options: StartupHintOptions): string[];
+export declare function logStartupHints(options: StartupHintOptions): void;

package/output/core/{virtual-modules.d.ts → runtime/virtual-modules.d.ts}

@@ -1,4 +1,4 @@
-import { ClarifyPlugin, ContentRoute, NavigationTree, ResolvedBuildOptions, ResolvedProjectConfig } from '../types.js';
+import { ClarifyPlugin, ContentDiagnostic, ContentRoute, NavigationTree, ResolvedBuildOptions, ResolvedProjectConfig } from '../../types.js';
 export declare const VIRTUAL_CONFIG = "virtual:clarify/config";
 export declare const VIRTUAL_ROUTES = "virtual:clarify/routes";
 export declare const VIRTUAL_SERVER_ROUTES = "virtual:clarify/routes/server";
@@ -6,14 +6,14 @@ export declare const VIRTUAL_OPENAPI = "virtual:clarify/openapi";
 export declare const VIRTUAL_SLOTS = "virtual:clarify/slots";
 export declare const VIRTUAL_SLOT = "virtual:clarify/slot";
 export declare const VIRTUAL_CLIENT_ENTRY = "virtual:clarify/entry-client";
-export declare const RESOLVED_CLIENT_ENTRY: string;
 export type VirtualModules = Map<string, string>;
 type BuildVirtualModulesArgs = {
-    projectConfig: ResolvedProjectConfig;
     generateOptions: ResolvedBuildOptions;
+    projectConfig: ResolvedProjectConfig;
     routes: ContentRoute[];
-    navigation?: NavigationTree;
+    version?: string;
     plugins?: ClarifyPlugin[];
+    navigation: NavigationTree;
     themeEditor?: boolean;
 };
 type CreateClientEntryModuleOptions = {
@@ -21,8 +21,17 @@ type CreateClientEntryModuleOptions = {
 };
 export declare function resolveVirtualId(id: string): string;
 export declare function stripVirtualPrefix(id: string): string;
-export declare function generateConfigModule(projectConfig: ResolvedProjectConfig, buildOptions: ResolvedBuildOptions): string;
-export declare function generateRoutesModule(routes: ContentRoute[], resolvedNavigation?: NavigationTree, projectConfig?: ResolvedProjectConfig, mode?: 'client' | 'server'): string;
+/**
+ * Shared `resolveId` logic for all Clarify virtual modules. Used by both the
+ * Vite core plugin (dev + build) and the SSG virtual plugin so the ID-to-
+ * resolved-ID mapping has a single source of truth.
+ *
+ * Returns the resolved ID (with `\0` prefix per Vite convention) or `null`
+ * if the ID is not a Clarify virtual module.
+ */
+export declare function resolveVirtualModuleId(id: string, modules: VirtualModules, routes: readonly ContentRoute[]): string | null;
+export declare function generateConfigModule(projectConfig: ResolvedProjectConfig, buildOptions: ResolvedBuildOptions, version?: string): string;
+export declare function generateRoutesModule(routes: ContentRoute[], navigation: NavigationTree, mode?: 'client' | 'server'): string;
 export declare function createClientEntryModule(options?: CreateClientEntryModuleOptions): string;
 /**
  * Collect every plugin's `slots` declarations into a single runtime registry
@@ -37,12 +46,6 @@ export declare function createClientEntryModule(options?: CreateClientEntryModul
  * type — no runtime validation is needed.
  */
 export declare function createRuntimeSlotsModule(plugins?: ClarifyPlugin[], root?: string): string;
-/**
- * Re-exports the slot context hook from the renderer so plugin components can
- * `import { useSlot } from 'virtual:clarify/slot'` without depending on
- * renderer internals directly.
- */
-export declare function createSlotModule(): string;
+export declare function generateMdxErrorModule(diagnostic: ContentDiagnostic): string;
 export declare function buildVirtualModules(args: BuildVirtualModulesArgs): VirtualModules;
-export declare function generateOpenApiModule(): string;
 export {};

package/output/core/{vite-config.d.ts → runtime/vite-config.d.ts}

@@ -1,4 +1,5 @@
 import { ConfigEnv, InlineConfig } from 'vite';
+import { ClarifyEngine } from '../engine/engine.js';
 export type ClarifyViteConfigOptions = {
     root: string;
     content: string;
@@ -7,4 +8,4 @@ export type ClarifyViteConfigOptions = {
     port?: number;
     open?: boolean | string;
 };
-export declare function createViteConfig(options: ClarifyViteConfigOptions, env: ConfigEnv): Promise<InlineConfig>;
+export declare function createViteConfig(options: ClarifyViteConfigOptions, env: ConfigEnv, engine: ClarifyEngine): Promise<InlineConfig>;