@stritti/vitepress-plugin-openspec 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -0,0 +1,217 @@
+import { Plugin } from 'vite';
+
+/**
+ * Options for the `withOpenSpec()` config helper.
+ * Extends `OpenSpecPluginOptions` with optional nav/sidebar merge controls.
+ */
+interface WithOpenSpecOptions extends OpenSpecPluginOptions {
+    /**
+     * Whether to prepend an openspec nav entry to `themeConfig.nav`.
+     * @default true
+     */
+    nav?: boolean;
+    /**
+     * Whether to inject the openspec sidebar section into `themeConfig.sidebar`.
+     * @default true
+     */
+    sidebar?: boolean;
+}
+/**
+ * Configuration options for the vitepress-plugin-openspec plugin.
+ */
+interface OpenSpecPluginOptions {
+    /**
+     * Path to the openspec/ directory of the project.
+     *
+     * Use an explicit path when your `openspec/` folder is not at the project root
+     * (e.g. when `config.ts` lives inside `docs/.vitepress/`).
+     *
+     * If the directory does not exist a warning is printed and the build continues
+     * without generating any pages or nav/sidebar entries — no error is thrown.
+     *
+     * @default './openspec'
+     * @example
+     * // Resolving from docs/.vitepress/config.ts
+     * import path from 'node:path'
+     * import { fileURLToPath } from 'node:url'
+     * const __dirname = path.dirname(fileURLToPath(import.meta.url))
+     * const specDir = path.resolve(__dirname, '../../openspec')
+     */
+    specDir?: string;
+    /**
+     * Output directory (relative to VitePress `srcDir`) where the generated
+     * Markdown pages will be written.
+     * @default 'openspec'
+     */
+    outDir?: string;
+    /**
+     * VitePress source directory — the directory containing your `.md` files
+     * (i.e. the `docs/` folder). Required when calling `generateOpenSpecPages()`
+     * at config evaluation time so it knows where to write the generated files.
+     *
+     * @default process.cwd()
+     * @example path.resolve(__dirname, '..')  // from docs/.vitepress/config.ts
+     */
+    srcDir?: string;
+}
+/**
+ * A canonical capability specification from openspec/specs/<name>/spec.md
+ */
+interface CapabilitySpec {
+    /** Folder name (kebab-case capability identifier) */
+    name: string;
+    /** Optional display title from spec.md frontmatter. Overrides humanized name. */
+    title?: string;
+    /** Absolute path to the spec.md file */
+    specPath: string;
+    /** Raw Markdown content of the spec */
+    content: string;
+}
+/**
+ * A single artifact (file) belonging to a Change.
+ */
+type ChangeArtifact = 'proposal' | 'design' | 'tasks';
+/**
+ * An OpenSpec change (active or archived).
+ */
+interface Change {
+    /** Change directory name (e.g. "my-feature" or for archived: "my-feature" extracted from "2026-03-10-my-feature") */
+    name: string;
+    /** Optional display title from .openspec.yaml. Overrides humanized name. */
+    title?: string;
+    /** Absolute path to the change directory */
+    dir: string;
+    /** Which artifact files are present */
+    artifacts: ChangeArtifact[];
+    /** Creation date from .openspec.yaml, if available */
+    createdDate?: string;
+    /** For archived changes: the archive date (YYYY-MM-DD) parsed from directory name */
+    archivedDate?: string;
+    /**
+     * For archived changes: the original archive folder name (e.g. "2026-01-15-my-feature" or
+     * "legacy-feature" for non-standard names). Used to build correct archive URLs.
+     */
+    archiveFolderName?: string;
+}
+/**
+ * The full parsed structure of an openspec/ directory.
+ */
+interface OpenSpecFolder {
+    /** Absolute path to the openspec/ root */
+    dir: string;
+    /** Canonical capability specs from openspec/specs/ */
+    specs: CapabilitySpec[];
+    /** Active changes from openspec/changes/ (excluding archive/) */
+    changes: Change[];
+    /** Archived changes from openspec/changes/archive/ */
+    archivedChanges: Change[];
+}
+/**
+ * A nav item compatible with VitePress `DefaultTheme.NavItem`.
+ */
+interface NavItem {
+    text: string;
+    link: string;
+}
+/**
+ * A sidebar item compatible with VitePress `DefaultTheme.SidebarItem`.
+ */
+interface SidebarItem {
+    text: string;
+    link?: string;
+    collapsed?: boolean;
+    items?: SidebarItem[];
+}
+
+/**
+ * Synchronously generates all VitePress Markdown pages from the openspec/
+ * directory and writes them to disk.
+ *
+ * Call this at the top of your `docs/.vitepress/config.ts` **before**
+ * `defineConfig()` so the files exist when VitePress scans the source
+ * directory for routes.
+ *
+ * @example
+ * ```typescript
+ * // docs/.vitepress/config.ts
+ * import { defineConfig } from 'vitepress'
+ * import path from 'node:path'
+ * import { fileURLToPath } from 'node:url'
+ * import openspec, { generateOpenSpecPages } from 'vitepress-plugin-openspec'
+ *
+ * const __dirname = path.dirname(fileURLToPath(import.meta.url))
+ * const specDir = path.resolve(__dirname, '../../openspec')
+ *
+ * // Generate pages before VitePress scans srcDir for routes
+ * generateOpenSpecPages({ specDir, outDir: 'openspec', srcDir: path.resolve(__dirname, '..') })
+ *
+ * export default defineConfig({ ... })
+ * ```
+ */
+declare function generateOpenSpecPages(userOptions?: OpenSpecPluginOptions): void;
+/**
+ * VitePress plugin that reads an openspec/ directory and generates structured
+ * Markdown documentation pages inside the VitePress source directory.
+ *
+ * For the pages to be available on the first build (including CI), also call
+ * `generateOpenSpecPages()` at the top of your `config.ts` before `defineConfig`.
+ *
+ * @example
+ * ```typescript
+ * // .vitepress/config.ts
+ * import { defineConfig } from 'vitepress'
+ * import openspec, { generateOpenSpecPages } from 'vitepress-plugin-openspec'
+ *
+ * generateOpenSpecPages({ specDir, outDir: 'openspec', srcDir: path.resolve(__dirname, '..') })
+ *
+ * export default defineConfig({
+ *   vite: { plugins: [openspec({ specDir: './openspec', outDir: 'project-docs' })] },
+ * })
+ * ```
+ */
+declare function openspec(userOptions?: OpenSpecPluginOptions): Plugin;
+/**
+ * One-call VitePress config helper that wires up the full openspec integration.
+ *
+ * Calls `generateOpenSpecPages()` synchronously (required before VitePress scans
+ * for routes), then merges the openspec Vite plugin, nav entry, and sidebar section
+ * into the provided config object.
+ *
+ * Other Vite plugins go into `vite.plugins` as usual — `withOpenSpec` appends to
+ * the array without replacing it:
+ *
+ * @example
+ * ```typescript
+ * // docs/.vitepress/config.ts
+ * import { defineConfig } from 'vitepress'
+ * import { withOpenSpec } from 'vitepress-plugin-openspec'
+ *
+ * export default defineConfig(
+ *   withOpenSpec({
+ *     vite: { plugins: [myOtherPlugin()] }, // other plugins are preserved
+ *     themeConfig: { nav: [], sidebar: {} },
+ *   })
+ * )
+ * ```
+ *
+ * @param config - Your VitePress `UserConfig` object (same as what `defineConfig` accepts).
+ * @param options - OpenSpec options. All fields are optional; defaults match `generateOpenSpecPages`.
+ */
+declare function withOpenSpec<T extends Record<string, unknown>>(config: T, options?: WithOpenSpecOptions): T;
+
+/**
+ * Returns a VitePress sidebar configuration for the OpenSpec documentation.
+ * Includes groups for Specifications, active Changes, and archived Changes.
+ */
+declare function generateOpenSpecSidebar(specDir: string, options?: {
+    outDir?: string;
+}): SidebarItem[];
+/**
+ * Returns a VitePress nav entry for the OpenSpec documentation section.
+ */
+declare function openspecNav(specDir: string, options?: {
+    outDir?: string;
+    text?: string;
+}): NavItem | null;
+
+export { type CapabilitySpec, type Change, type ChangeArtifact, type NavItem, type OpenSpecFolder, type OpenSpecPluginOptions, type SidebarItem, type WithOpenSpecOptions, openspec as default, generateOpenSpecPages, generateOpenSpecSidebar, openspec, openspecNav, withOpenSpec };

package/dist/index.d.ts

@@ -0,0 +1,217 @@
+import { Plugin } from 'vite';
+
+/**
+ * Options for the `withOpenSpec()` config helper.
+ * Extends `OpenSpecPluginOptions` with optional nav/sidebar merge controls.
+ */
+interface WithOpenSpecOptions extends OpenSpecPluginOptions {
+    /**
+     * Whether to prepend an openspec nav entry to `themeConfig.nav`.
+     * @default true
+     */
+    nav?: boolean;
+    /**
+     * Whether to inject the openspec sidebar section into `themeConfig.sidebar`.
+     * @default true
+     */
+    sidebar?: boolean;
+}
+/**
+ * Configuration options for the vitepress-plugin-openspec plugin.
+ */
+interface OpenSpecPluginOptions {
+    /**
+     * Path to the openspec/ directory of the project.
+     *
+     * Use an explicit path when your `openspec/` folder is not at the project root
+     * (e.g. when `config.ts` lives inside `docs/.vitepress/`).
+     *
+     * If the directory does not exist a warning is printed and the build continues
+     * without generating any pages or nav/sidebar entries — no error is thrown.
+     *
+     * @default './openspec'
+     * @example
+     * // Resolving from docs/.vitepress/config.ts
+     * import path from 'node:path'
+     * import { fileURLToPath } from 'node:url'
+     * const __dirname = path.dirname(fileURLToPath(import.meta.url))
+     * const specDir = path.resolve(__dirname, '../../openspec')
+     */
+    specDir?: string;
+    /**
+     * Output directory (relative to VitePress `srcDir`) where the generated
+     * Markdown pages will be written.
+     * @default 'openspec'
+     */
+    outDir?: string;
+    /**
+     * VitePress source directory — the directory containing your `.md` files
+     * (i.e. the `docs/` folder). Required when calling `generateOpenSpecPages()`
+     * at config evaluation time so it knows where to write the generated files.
+     *
+     * @default process.cwd()
+     * @example path.resolve(__dirname, '..')  // from docs/.vitepress/config.ts
+     */
+    srcDir?: string;
+}
+/**
+ * A canonical capability specification from openspec/specs/<name>/spec.md
+ */
+interface CapabilitySpec {
+    /** Folder name (kebab-case capability identifier) */
+    name: string;
+    /** Optional display title from spec.md frontmatter. Overrides humanized name. */
+    title?: string;
+    /** Absolute path to the spec.md file */
+    specPath: string;
+    /** Raw Markdown content of the spec */
+    content: string;
+}
+/**
+ * A single artifact (file) belonging to a Change.
+ */
+type ChangeArtifact = 'proposal' | 'design' | 'tasks';
+/**
+ * An OpenSpec change (active or archived).
+ */
+interface Change {
+    /** Change directory name (e.g. "my-feature" or for archived: "my-feature" extracted from "2026-03-10-my-feature") */
+    name: string;
+    /** Optional display title from .openspec.yaml. Overrides humanized name. */
+    title?: string;
+    /** Absolute path to the change directory */
+    dir: string;
+    /** Which artifact files are present */
+    artifacts: ChangeArtifact[];
+    /** Creation date from .openspec.yaml, if available */
+    createdDate?: string;
+    /** For archived changes: the archive date (YYYY-MM-DD) parsed from directory name */
+    archivedDate?: string;
+    /**
+     * For archived changes: the original archive folder name (e.g. "2026-01-15-my-feature" or
+     * "legacy-feature" for non-standard names). Used to build correct archive URLs.
+     */
+    archiveFolderName?: string;
+}
+/**
+ * The full parsed structure of an openspec/ directory.
+ */
+interface OpenSpecFolder {
+    /** Absolute path to the openspec/ root */
+    dir: string;
+    /** Canonical capability specs from openspec/specs/ */
+    specs: CapabilitySpec[];
+    /** Active changes from openspec/changes/ (excluding archive/) */
+    changes: Change[];
+    /** Archived changes from openspec/changes/archive/ */
+    archivedChanges: Change[];
+}
+/**
+ * A nav item compatible with VitePress `DefaultTheme.NavItem`.
+ */
+interface NavItem {
+    text: string;
+    link: string;
+}
+/**
+ * A sidebar item compatible with VitePress `DefaultTheme.SidebarItem`.
+ */
+interface SidebarItem {
+    text: string;
+    link?: string;
+    collapsed?: boolean;
+    items?: SidebarItem[];
+}
+
+/**
+ * Synchronously generates all VitePress Markdown pages from the openspec/
+ * directory and writes them to disk.
+ *
+ * Call this at the top of your `docs/.vitepress/config.ts` **before**
+ * `defineConfig()` so the files exist when VitePress scans the source
+ * directory for routes.
+ *
+ * @example
+ * ```typescript
+ * // docs/.vitepress/config.ts
+ * import { defineConfig } from 'vitepress'
+ * import path from 'node:path'
+ * import { fileURLToPath } from 'node:url'
+ * import openspec, { generateOpenSpecPages } from 'vitepress-plugin-openspec'
+ *
+ * const __dirname = path.dirname(fileURLToPath(import.meta.url))
+ * const specDir = path.resolve(__dirname, '../../openspec')
+ *
+ * // Generate pages before VitePress scans srcDir for routes
+ * generateOpenSpecPages({ specDir, outDir: 'openspec', srcDir: path.resolve(__dirname, '..') })
+ *
+ * export default defineConfig({ ... })
+ * ```
+ */
+declare function generateOpenSpecPages(userOptions?: OpenSpecPluginOptions): void;
+/**
+ * VitePress plugin that reads an openspec/ directory and generates structured
+ * Markdown documentation pages inside the VitePress source directory.
+ *
+ * For the pages to be available on the first build (including CI), also call
+ * `generateOpenSpecPages()` at the top of your `config.ts` before `defineConfig`.
+ *
+ * @example
+ * ```typescript
+ * // .vitepress/config.ts
+ * import { defineConfig } from 'vitepress'
+ * import openspec, { generateOpenSpecPages } from 'vitepress-plugin-openspec'
+ *
+ * generateOpenSpecPages({ specDir, outDir: 'openspec', srcDir: path.resolve(__dirname, '..') })
+ *
+ * export default defineConfig({
+ *   vite: { plugins: [openspec({ specDir: './openspec', outDir: 'project-docs' })] },
+ * })
+ * ```
+ */
+declare function openspec(userOptions?: OpenSpecPluginOptions): Plugin;
+/**
+ * One-call VitePress config helper that wires up the full openspec integration.
+ *
+ * Calls `generateOpenSpecPages()` synchronously (required before VitePress scans
+ * for routes), then merges the openspec Vite plugin, nav entry, and sidebar section
+ * into the provided config object.
+ *
+ * Other Vite plugins go into `vite.plugins` as usual — `withOpenSpec` appends to
+ * the array without replacing it:
+ *
+ * @example
+ * ```typescript
+ * // docs/.vitepress/config.ts
+ * import { defineConfig } from 'vitepress'
+ * import { withOpenSpec } from 'vitepress-plugin-openspec'
+ *
+ * export default defineConfig(
+ *   withOpenSpec({
+ *     vite: { plugins: [myOtherPlugin()] }, // other plugins are preserved
+ *     themeConfig: { nav: [], sidebar: {} },
+ *   })
+ * )
+ * ```
+ *
+ * @param config - Your VitePress `UserConfig` object (same as what `defineConfig` accepts).
+ * @param options - OpenSpec options. All fields are optional; defaults match `generateOpenSpecPages`.
+ */
+declare function withOpenSpec<T extends Record<string, unknown>>(config: T, options?: WithOpenSpecOptions): T;
+
+/**
+ * Returns a VitePress sidebar configuration for the OpenSpec documentation.
+ * Includes groups for Specifications, active Changes, and archived Changes.
+ */
+declare function generateOpenSpecSidebar(specDir: string, options?: {
+    outDir?: string;
+}): SidebarItem[];
+/**
+ * Returns a VitePress nav entry for the OpenSpec documentation section.
+ */
+declare function openspecNav(specDir: string, options?: {
+    outDir?: string;
+    text?: string;
+}): NavItem | null;
+
+export { type CapabilitySpec, type Change, type ChangeArtifact, type NavItem, type OpenSpecFolder, type OpenSpecPluginOptions, type SidebarItem, type WithOpenSpecOptions, openspec as default, generateOpenSpecPages, generateOpenSpecSidebar, openspec, openspecNav, withOpenSpec };