@clarify-labs/cli 0.9.4 → 0.10.1

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

@@ -0,0 +1,10 @@
+import { ClarifyCollectorHook, ClarifyHookContext, ClarifyInterceptHook, ClarifyPipelineHook, ClarifyPlugin, ClarifyTapHook } 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 = ClarifyTapHook;
+export type InterceptHook = ClarifyInterceptHook;
+export type PipelineHook<Input> = ClarifyPipelineHook<Input>;
+export type CollectorHook<Result> = ClarifyCollectorHook<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/plugin/hooks.d.ts

@@ -0,0 +1,7 @@
+import { ViteDevServer } from 'vite';
+import { ClarifyEmitAsset, ClarifyHookContext, ClarifyPipelineHooks, ClarifyPlugin } from '../../types.js';
+export declare function runHooks<K extends keyof ClarifyPipelineHooks>(plugins: ClarifyPlugin[], hookName: K, input: Parameters<NonNullable<ClarifyPipelineHooks[K]>>[0], ctx: ClarifyHookContext): Promise<Parameters<NonNullable<ClarifyPipelineHooks[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-context.d.ts → project/project-context.d.ts}

@@ -1,16 +1,16 @@
 import { ConfigEnv } from 'vite';
-import { ClarifyHookContext, ClarifyProjectContext } from '../types.js';
-import { resolveProjectConfig } from './config.js';
-import { ClarifyBuildOptions, ResolvedBuildOptions } from './options.js';
-import { ClarifyConfig } from './user-config.js';
+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;
-    projectConfig: ReturnType<typeof resolveProjectConfig>;
     buildOptions: ResolvedBuildOptions;
-    config: ClarifyConfig;
-    hookContext: ClarifyHookContext;
+    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 { ClarifyProjectContext } 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

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 { ClarifyProjectContext, ContentRoute, ResolvedProjectConfig } 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, contextOrConfig: ClarifyProjectContext | 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 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 { openApiSpecs } from 'virtual:clarify/openapi/server';\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.loadComponent()\n    entry._resolved = mod.default\n  }))\n  return renderToHTML({ config, routes, navigation, openApiSpecs, 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[], contextOrConfig: ClarifyProjectContext | ResolvedProjectConfig, outputDirectory: string, ssrBundlePath: string, failOnError?: boolean): Promise<void>;

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

@@ -1,12 +1,12 @@
-import { ClarifyPlugin, ContentDiagnostic, 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";
 export declare const VIRTUAL_OPENAPI = "virtual:clarify/openapi";
+export declare const VIRTUAL_OPENAPI_SERVER = "virtual:clarify/openapi/server";
 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 = {
     generateOptions: ResolvedBuildOptions;
@@ -14,7 +14,7 @@ type BuildVirtualModulesArgs = {
     routes: ContentRoute[];
     version?: string;
     plugins?: ClarifyPlugin[];
-    navigation?: NavigationTree;
+    navigation: NavigationTree;
     themeEditor?: boolean;
 };
 type CreateClientEntryModuleOptions = {
@@ -22,8 +22,17 @@ type CreateClientEntryModuleOptions = {
 };
 export declare function resolveVirtualId(id: string): string;
 export declare function stripVirtualPrefix(id: string): 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[], resolvedNavigation?: NavigationTree, projectConfig?: ResolvedProjectConfig, mode?: 'client' | 'server'): 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
@@ -38,13 +47,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>;