@stritti/vitepress-plugin-openspec 0.7.0 → 0.8.0

package/dist/plugin.d.ts

@@ -0,0 +1,50 @@
+import type { Plugin } from 'vite';
+import type { OpenSpecPluginOptions, WithOpenSpecOptions } from './types.js';
+/**
+ * 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. In most cases `withOpenSpec()` (which calls this
+ * internally) is the simpler integration point.
+ *
+ * @returns true when pages were written; false when generation was skipped
+ *   (missing or unreadable source, ambiguous source-directory detection) or
+ *   failed.
+ * @throws if `outDir` is not a relative path inside `srcDir` (absolute,
+ *   traversal, or empty).
+ */
+export declare function generateOpenSpecPages(userOptions?: OpenSpecPluginOptions): boolean;
+/**
+ * Vite plugin that regenerates the openspec documentation pages whenever a
+ * file inside the openspec/ directory changes. This makes `vitepress dev`
+ * pick up spec edits without a manual restart.
+ *
+ * For the pages to be available on the first build (including CI), the pages
+ * are generated once in `configResolved`. When using `withOpenSpec()` this
+ * plugin is wired up automatically.
+ */
+export 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.
+ *
+ * When the VitePress source directory cannot be detected unambiguously
+ * (multiple `.vitepress` folders at the same level), a warning is emitted and
+ * the config is returned with only the sidebar shape normalized — nothing is
+ * generated or injected.
+ *
+ * @param config - Your VitePress `UserConfig` object (same as what `defineConfig` accepts).
+ * @param options - OpenSpec options. All fields are optional; defaults match `generateOpenSpecPages`.
+ * @throws if `outDir` is not a relative path inside `srcDir` (absolute, traversal, or empty).
+ */
+export declare function withOpenSpec<T extends Record<string, unknown>>(config: T, options?: WithOpenSpecOptions): T;
+export default openspec;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAS5E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,GAAE,qBAA0B,GAAG,OAAO,CAQtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,WAAW,GAAE,qBAA0B,GAAG,MAAM,CAyFxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,mBAAwB,GAChC,CAAC,CA+DH;eAEc,QAAQ"}

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Options for the `withOpenSpec()` config helper.
+ * Extends `OpenSpecPluginOptions` with optional nav/sidebar merge controls.
+ */
+export 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;
+    /**
+     * Label for the nav entry injected into `themeConfig.nav`.
+     * @default 'Docs'
+     */
+    navText?: string;
+}
+/**
+ * Configuration options for the vitepress-plugin-openspec plugin.
+ */
+export interface OpenSpecPluginOptions {
+    /**
+     * Path to the openspec/ directory of the project.
+     *
+     * By default the plugin walks up from the current working directory looking
+     * for an `openspec/` folder (skipping generated output recognized by its
+     * marker), so no configuration is needed when it lives at the project root.
+     * Set an explicit path only for custom locations.
+     *
+     * 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.
+     * An invalid `outDir` (absolute, empty, or escaping `srcDir`) throws instead.
+     *
+     * @default auto-detected (`<nearest ancestor>/openspec`, falling back to `'./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). By default the plugin detects the directory that
+     * contains `.vitepress` (the working directory, a first-level subdirectory
+     * such as `docs/`, or the parent when the config is evaluated from inside
+     * `docs/.vitepress/`), so no configuration is needed for standard layouts.
+     *
+     * @default auto-detected (directory containing `.vitepress`, falling back to the working directory)
+     * @example path.resolve(__dirname, '..')  // from docs/.vitepress/config.ts
+     */
+    srcDir?: string;
+}
+/**
+ * A canonical capability specification from openspec/specs/<name>/spec.md
+ */
+export 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.
+ */
+export type ChangeArtifact = 'proposal' | 'design' | 'tasks';
+/**
+ * An OpenSpec change (active or archived).
+ */
+export 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.
+ */
+export 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`.
+ */
+export interface NavItem {
+    text: string;
+    link: string;
+}
+/**
+ * A sidebar item compatible with VitePress `DefaultTheme.SidebarItem`.
+ */
+export interface SidebarItem {
+    text: string;
+    link?: string;
+    collapsed?: boolean;
+    items?: SidebarItem[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAA;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE5D;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,qHAAqH;IACrH,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAA;IACX,uCAAuC;IACvC,SAAS,EAAE,cAAc,EAAE,CAAA;IAC3B,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX,sDAAsD;IACtD,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,sDAAsD;IACtD,eAAe,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,KAAK,CAAC,EAAE,WAAW,EAAE,CAAA;CACtB"}

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compatibility re-exports. The implementation lives in `./lib/` modules;
+ * these named exports are kept stable for existing consumers.
+ */
+export { readOpenSpecFolder } from './lib/reader.js';
+export { rewriteRelativeLinks } from './lib/links.js';
+export { generateSpecPage, generateSpecsIndexPage, generateChangeIndexPage, generateChangesIndexPage, } from './lib/pages.js';
+export { generateOpenSpecSidebar, openspecNav } from './lib/navigation.js';
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stritti/vitepress-plugin-openspec",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A VitePress plugin that integrates OpenSpec documentation into your VitePress site",
   "keywords": [
     "openspec",
@@ -32,7 +32,7 @@
     }
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationMap --outDir dist",
     "dev": "tsup --watch",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build",
@@ -42,7 +42,7 @@
     "docs:build": "cd docs && bun run build"
   },
   "dependencies": {
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^5.4.2",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
@@ -54,8 +54,8 @@
     "@types/node": "^25.4.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.0.5",
     "vitepress": "^1.6.4",
     "vitest": "^4.0.18"
   },

package/dist/index.d.cts

@@ -1,217 +0,0 @@
-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 };