@clarify-labs/cli 0.10.0 → 0.10.2

package/output/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_engine = require("./engine-I04EZzjg.cjs");
+const require_engine = require("./engine-qafLfnXQ.cjs");
 exports.ClarifyEngine = require_engine.ClarifyEngine;
 exports.createClarifyEngine = require_engine.createClarifyEngine;
 exports.createViteAdapter = require_engine.createViteAdapter;

package/output/index.d.ts

@@ -5,4 +5,4 @@ export type { ClarifyEngineRuntime, PrepareOptions } from './core/engine/engine.
 export type { PhaseName, TapPhaseName, TapHook, InterceptHook, PipelineHook, CollectorHook } from './core/engine/phases.js';
 export * from './types.js';
 export type { ClarifyConfig } from './core/config/user-config.js';
-export type { UISlotName, SlotContext, UISlotRegistration } from '@clarify-labs/renderer';
+export type { UISlotName, UISlotContext, UISlotRegistration } from '@clarify-labs/renderer';

package/output/index.js

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

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

@@ -1,3 +1,4 @@
+import { CompileOptions } from '@mdx-js/mdx';
 import { ContentDiagnostic } from '../../types.js';
 type HastNode = {
     type: string;
@@ -7,17 +8,16 @@ type HastNode = {
     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 declare const rehypePlugins: NonNullable<CompileOptions['rehypePlugins']>;
 /**
  * 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
+ * `@mdx-js/rollup` plugins (see `createMarkdownPlugin` and `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

package/output/parsers/routes/routes.d.ts

@@ -1,4 +1,4 @@
-import { ContentRoute, ContentSection, ClarifyNavigationNode, ClarifyPagesConfig, ClarifyPagesGroup, ClarifyLocalizedText, ClarifyTabsConfig, LocalizedNavigation, LocalizedTabbedNavigation, ResolvedClarifyI18nConfig, TabbedNavigation } from '../../types.js';
+import { ContentRoute, ContentSection, ClarifyNavigationNode, ClarifyPagesConfig, ClarifyPagesGroup, ClarifyPagesItem, ClarifyRouteIntent, ClarifyLocalizedText, ClarifyTabsConfig, LocalizedNavigation, LocalizedTabbedNavigation, ResolvedClarifyI18nConfig, TabbedNavigation } from '../../types.js';
 import { ContentProcessor } from '../content/content.js';
 export type FindContentRoutesOptions = {
     contentProcessor?: ContentProcessor;
@@ -18,6 +18,7 @@ export declare function findContentRoutes(dir: string, base?: string, options?:
 export declare function withAlternates(route: ContentRoute, routes: ContentRoute[], i18n: ResolvedClarifyI18nConfig): ContentRoute;
 export declare function findLocalizedContentRoutes(contentRoot: string, i18n?: ResolvedClarifyI18nConfig, options?: FindContentRoutesOptions): Promise<ContentRoute[]>;
 export declare function buildNavigation(routes: ContentRoute[]): ClarifyNavigationNode[];
+export declare function routeIntentFromPagesItem(item: ClarifyPagesItem): ClarifyRouteIntent;
 export declare function applyConfiguredPageRoutePaths(routes: ContentRoute[], tabs?: ClarifyTabsConfig, i18n?: ResolvedClarifyI18nConfig): ContentRoute[];
 export declare function buildNavigationFromTabsConfig(routes: ContentRoute[], tabs: ClarifyTabsConfig): TabbedNavigation;
 export declare function buildNavigationFromConfig(routes: ContentRoute[], config: ClarifyPagesGroup[]): ClarifyNavigationNode[];

package/output/parsers/routes/routes.test-utils.d.ts

@@ -1,3 +1,20 @@
 import { ContentRoute, ResolvedClarifyI18nConfig } from '../../types.js';
-export declare function mdxRoute(route: Omit<ContentRoute, 'kind'>): ContentRoute;
+type ContentRouteFixture = Partial<Omit<ContentRoute, 'kind' | 'meta' | 'module' | 'source'>> & {
+    kind?: ContentRoute['kind'];
+    title?: string;
+    description?: string;
+    keywords?: ContentRoute['meta']['keywords'];
+    sections?: ContentRoute['meta']['sections'];
+    filePath?: string;
+    frontmatter?: ContentRoute['source']['frontmatter'];
+    content?: string;
+    sourceEditUrl?: string;
+    virtualModuleId?: string;
+    meta?: Partial<ContentRoute['meta']>;
+    module?: Partial<ContentRoute['module']>;
+    source?: Partial<ContentRoute['source']>;
+};
+export declare function contentRoute(route?: ContentRouteFixture): ContentRoute;
+export declare function mdxRoute(route?: ContentRouteFixture): ContentRoute;
 export declare const testI18n: ResolvedClarifyI18nConfig;
+export {};

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

@@ -8,6 +8,7 @@ export type OpenAPIParseResult = {
     diagnostic: ContentDiagnostic;
 };
 export declare function findOpenAPIRoutes(dir: string, base?: string): ContentRoute[];
+export declare function normalizeOpenAPISpecSectionIds(spec: OpenAPISpec): OpenAPISpec;
 /** Filter an OpenAPI spec to only include paths that have at least one operation matching the given tags. */
 export declare function filterSpecByTags(spec: OpenAPISpec, tags: string[]): OpenAPISpec;
 /** Extract endpoint operations from an OpenAPI spec as page sections. */

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

@@ -1,13 +1,14 @@
 import { ContentDiagnostic, OpenAPISpec } from '../../types.js';
 export declare const openApiRegistryModuleId = "virtual:clarify/openapi";
+export declare const openApiServerRegistryModuleId = "virtual:clarify/openapi/server";
 export declare const OPENAPI_SPEC_PREFIX = "virtual:clarify/openapi-spec/";
 export declare function specVirtualModuleId(specKey: string): string;
-export declare function generateOpenAPIRegistryModule(openApis: Record<string, OpenAPISpec>): string;
+export declare function generateOpenAPIRegistryModule(openApiSpecs: Record<string, string>): string;
+export declare function generateOpenAPIServerRegistryModule(openApiSpecs: Record<string, OpenAPISpec>): string;
 /** Generate a virtual module that exports a single spec as default. */
 export declare function generateOpenAPISpecModule(spec: OpenAPISpec): string;
 type OpenAPIPageModuleOptions = {
-    spec: OpenAPISpec;
-    tagFilter?: string[];
+    specModuleId: string;
 };
 export declare function generateOpenAPIPageModule(opts: OpenAPIPageModuleOptions): string;
 export declare function generateOpenAPIErrorModule(diagnostic: ContentDiagnostic): string;

package/output/plugins/source-links/source-links.d.ts

@@ -1,3 +1,3 @@
 import { ClarifySourceConfig, ContentRoute } from '../../types.js';
-export declare function createSourceUrl(filePath: string, contentRoot: string, source: ClarifySourceConfig): string;
-export declare function attachSourceUrls(routes: ContentRoute[], contentRoot: string, source?: ClarifySourceConfig): void;
+export declare function createSourceEditUrl(filePath: string, contentRoot: string, source: ClarifySourceConfig): string;
+export declare function attachSourceEditUrls(routes: ContentRoute[], contentRoot: string, source?: ClarifySourceConfig): void;

package/output/types.d.ts

@@ -148,6 +148,23 @@ export type ClarifyPagesGroup = {
 };
 /** Use the string "FileTree" to auto-generate pages from the file system. */
 export type ClarifyPagesConfig = ClarifyPagesGroup[] | 'FileTree';
+export type ClarifyPageRouteIntent = {
+    kind: 'page';
+    ref: string;
+    path?: string;
+    redirect?: string;
+    title?: ClarifyLocalizedText;
+    icon?: string;
+};
+export type ClarifyOpenAPIRouteIntent = {
+    kind: 'openapi';
+    ref: string;
+    path?: string;
+    tagFilter?: string[];
+    title?: ClarifyLocalizedText;
+    icon?: string;
+};
+export type ClarifyRouteIntent = ClarifyPageRouteIntent | ClarifyOpenAPIRouteIntent;
 export type ClarifyTabItem = {
     tab: ClarifyLocalizedText;
     /** Icon name from lucide-react, e.g. "BookOpen". */
@@ -226,6 +243,35 @@ export type ContentDiagnostic = {
     details?: string;
     filePath?: string;
 };
+export type ContentRouteMeta = {
+    title: string;
+    description?: string;
+    keywords?: string[];
+    sections?: ContentSection[];
+};
+export type ContentRouteModule = {
+    virtualModuleId: string;
+};
+export type OpenAPIContentRouteState = {
+    /** Operation tag filter applied to this route. Undefined means all operations. */
+    tagFilter?: string[];
+    /** Deduplicated id derived from the source OpenAPI spec file path. */
+    sourceSpecId?: string;
+    /** Spec virtual module id fragment used by this route after route-level filtering. */
+    routeSpecModuleId?: string;
+};
+export type ContentRouteArtifacts = {
+    /** Public URL for the machine-readable content artifact served or emitted for this route. */
+    contentArtifactUrl?: string;
+};
+export type ContentRouteSource = {
+    filePath: string;
+    frontmatter?: Record<string, unknown>;
+    /** Normalized source content captured during route discovery. */
+    content?: string;
+    /** Public edit URL for this route's source file. */
+    sourceEditUrl?: string;
+};
 export type ContentRoute = {
     path: string;
     basePath?: string;
@@ -234,24 +280,14 @@ export type ContentRoute = {
     /** Indicates this route is a bare alias for the default locale (e.g., /path instead of /locale/path). Should not be indexed. */
     isBareAlias?: boolean;
     alternates?: Record<string, string>;
-    title: string;
-    description?: string;
-    keywords?: string[];
-    filePath: string;
-    virtualModuleId: string;
     kind: string;
-    /** OpenAPI operation tag filter applied to this route. Undefined means all operations. */
-    openapiTagFilter?: string[];
-    /** Deduplicated key derived from the source OpenAPI spec file path. Routes sharing
-     * the same spec file (e.g. filtered sub-routes) share the same key. */
-    specFileKey?: string;
-    frontmatter?: Record<string, unknown>;
-    /** Normalized source content captured during route discovery. */
-    content?: string;
+    meta: ContentRouteMeta;
+    module: ContentRouteModule;
+    source: ContentRouteSource;
+    /** OpenAPI-specific route state. Present only for OpenAPI routes. */
+    openapi?: OpenAPIContentRouteState;
     diagnostic?: ContentDiagnostic;
-    sections?: ContentSection[];
-    contentArtifactUrl?: string;
-    sourceUrl?: string;
+    artifacts?: ContentRouteArtifacts;
 };
 export type ClarifyNavigationTab = {
     type: 'tab';
@@ -260,41 +296,64 @@ export type ClarifyNavigationTab = {
     icon?: string;
     children: ClarifyNavigationNode[];
 };
+export type FlatNavigationTree = {
+    kind: 'flat';
+    nodes: ClarifyNavigationNode[];
+};
 export type TabbedNavigation = {
+    kind: 'tabbed';
     tabs: ClarifyNavigationTab[];
 };
-export type LocalizedNavigation = Record<string, ClarifyNavigationNode[]>;
-export type LocalizedTabbedNavigation = Record<string, TabbedNavigation>;
-export type NavigationTree = ClarifyNavigationNode[] | LocalizedNavigation | TabbedNavigation | LocalizedTabbedNavigation;
+export type LocalizedNavigation = {
+    kind: 'localized';
+    locales: Record<string, ClarifyNavigationNode[]>;
+};
+export type LocalizedTabbedNavigation = {
+    kind: 'localized-tabbed';
+    locales: Record<string, Omit<TabbedNavigation, 'kind'>>;
+};
+export type NavigationTree = FlatNavigationTree | LocalizedNavigation | TabbedNavigation | LocalizedTabbedNavigation;
 export type ClarifyPage = {
     path: string;
     filePath: string;
     frontmatter: Record<string, unknown>;
     content: string;
 };
+export type NavigationSection = {
+    id: string;
+    title: string;
+    level?: number;
+    badge?: string;
+    tags?: string[];
+};
 export type ClarifyNavigationNode = {
     path: string;
     title: string;
     icon?: string;
     children?: ClarifyNavigationNode[];
-    sections?: Pick<ContentSection, 'id' | 'title' | 'badge' | 'tags'>[];
+    sections?: NavigationSection[];
 };
 export type ClarifyProjectContext = {
+    version: string;
     projectRoot: string;
     contentRoot: string;
     projectConfig: ResolvedProjectConfig;
     generateOptions: ResolvedBuildOptions;
-    version: string;
 };
-export type ClarifyHookContext = ClarifyProjectContext & {
+export type ClarifyRouteState = {
     routes: ContentRoute[];
     navigation: NavigationTree;
+};
+export type ClarifyPluginState = {
     plugins: ClarifyPlugin[];
+};
+export type ClarifyPluginStore = {
     get<T>(key: string): T | undefined;
     set<T>(key: string, value: T): void;
     has(key: string): boolean;
     delete(key: string): boolean;
 };
+export type ClarifyHookContext = ClarifyProjectContext & ClarifyRouteState & ClarifyPluginState & ClarifyPluginStore;
 export type ClarifyRouteDiscoveryInput = {
     contentRoot: string;
     locale?: string;
@@ -320,28 +379,16 @@ 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[];
-    'routes:discover'?: (input: ClarifyRouteDiscoveryInput, ctx: ClarifyHookContext) => Promise<ClarifyRouteDiscoveryInput> | ClarifyRouteDiscoveryInput;
-    'routes:discovered'?: (routes: ContentRoute[], ctx: ClarifyHookContext) => Promise<ContentRoute[]> | ContentRoute[];
-    'routes:resolved'?: (input: {
-        routes: ContentRoute[];
-        navigation: NavigationTree;
-    }, ctx: ClarifyHookContext) => Promise<{
-        routes: ContentRoute[];
-        navigation: NavigationTree;
-    }> | {
-        routes: ContentRoute[];
-        navigation: NavigationTree;
-    };
-    'modules:before'?: (modules: Map<string, string>, ctx: ClarifyHookContext) => Promise<Map<string, string>> | Map<string, string>;
-    'html:transform'?: (input: ClarifyHtmlTransformInput, ctx: ClarifyHookContext) => Promise<ClarifyHtmlTransformInput> | ClarifyHtmlTransformInput;
-    'dev:configureServer'?: (server: ViteDevServer, ctx: ClarifyHookContext) => Promise<void> | void;
-    'build:assets'?: (ctx: ClarifyHookContext) => Promise<ClarifyEmitAsset[]> | ClarifyEmitAsset[];
-    'build:done'?: (ctx: ClarifyHookContext) => Promise<void> | void;
+export type MaybePromise<T> = T | Promise<T>;
+export type ClarifyTapHook = (ctx: ClarifyHookContext) => MaybePromise<void>;
+export type ClarifyInterceptHook = (ctx: ClarifyHookContext) => MaybePromise<boolean>;
+export type ClarifyPipelineHook<Input> = (input: Input, ctx: ClarifyHookContext) => MaybePromise<Input>;
+export type ClarifyCollectorHook<Result> = (ctx: ClarifyHookContext) => MaybePromise<Result[]>;
+export type ClarifyRoutesResolvedInput = {
+    routes: ContentRoute[];
+    navigation: NavigationTree;
+};
+export type ClarifyLifecycleHooks = {
     'before:config:load'?: ClarifyTapHook;
     'after:config:load'?: ClarifyTapHook;
     'before:config:resolve'?: ClarifyTapHook;
@@ -360,9 +407,26 @@ export type ClarifyHooks = {
     'after:ssg'?: ClarifyTapHook;
     'before:dev:server'?: ClarifyTapHook;
     'after:dev:server'?: ClarifyTapHook;
+};
+export type ClarifyPipelineHooks = {
+    'content:transform'?: ClarifyPipelineHook<ClarifyContentTransformInput>;
+    'pages:resolved'?: ClarifyPipelineHook<ClarifyPage[]>;
+    'routes:discover'?: ClarifyPipelineHook<ClarifyRouteDiscoveryInput>;
+    'routes:discovered'?: ClarifyPipelineHook<ContentRoute[]>;
+    'routes:resolved'?: ClarifyPipelineHook<ClarifyRoutesResolvedInput>;
+    'modules:before'?: ClarifyPipelineHook<Map<string, string>>;
+    'html:transform'?: ClarifyPipelineHook<ClarifyHtmlTransformInput>;
+};
+export type ClarifyBuildHooks = {
+    'build:assets'?: ClarifyCollectorHook<ClarifyEmitAsset>;
+    'build:done'?: ClarifyTapHook;
     'build:shouldRun'?: ClarifyInterceptHook;
     'ssg:shouldRun'?: ClarifyInterceptHook;
 };
+export type ClarifyDevHooks = {
+    'dev:configureServer'?: (server: ViteDevServer, ctx: ClarifyHookContext) => MaybePromise<void>;
+};
+export type ClarifyHooks = ClarifyLifecycleHooks & ClarifyPipelineHooks & ClarifyBuildHooks & ClarifyDevHooks;
 export type ClarifyPlugin = {
     name: string;
     enforce?: 'pre' | 'post';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clarify-labs/cli",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "repository": {
@@ -39,10 +39,11 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "@clarify-labs/renderer": "0.10.0",
-    "@clarify-labs/templates": "0.10.0",
+    "@clarify-labs/renderer": "0.10.2",
+    "@clarify-labs/templates": "0.10.2",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
+    "@shikijs/rehype": "^4.3.0",
     "@tailwindcss/vite": "^4.3.2",
     "@vitejs/plugin-react": "^6.0.3",
     "cac": "^7.0.0",
@@ -57,6 +58,8 @@
     "react-router": "^7.0.0",
     "react-router-dom": "^7.0.0",
     "react-zoom-pan-pinch": "^4.0.3",
+    "rehype-raw": "^7.0.0",
+    "rehype-slug": "^6.0.0",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
     "shiki": "4.3.0",