@stritti/vitepress-plugin-openspec 0.7.1 → 0.8.0

package/dist/plugin.d.ts

@@ -6,45 +6,24 @@ import type { OpenSpecPluginOptions, WithOpenSpecOptions } from './types.js';
  *
  * 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({ ... })
- * ```
+ * 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): void;
+export declare function generateOpenSpecPages(userOptions?: OpenSpecPluginOptions): boolean;
 /**
- * VitePress plugin that reads an openspec/ directory and generates structured
- * Markdown documentation pages inside the VitePress source directory.
+ * 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), 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' })] },
- * })
- * ```
+ * 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;
 /**
@@ -55,24 +34,16 @@ export declare function openspec(userOptions?: OpenSpecPluginOptions): Plugin;
  * 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'
+ * the array without replacing it.
  *
- * export default defineConfig(
- *   withOpenSpec({
- *     vite: { plugins: [myOtherPlugin()] }, // other plugins are preserved
- *     themeConfig: { nav: [], sidebar: {} },
- *   })
- * )
- * ```
+ * 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;

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAClC,OAAO,KAAK,EAAU,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAmBpF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,GAAE,qBAA0B,GAAG,IAAI,CA0EnF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,WAAW,GAAE,qBAA0B,GAAG,MAAM,CAYxE;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,mBAAwB,GAChC,CAAC,CAsCH;eAEc,QAAQ"}
+{"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

@@ -13,6 +13,11 @@ export interface WithOpenSpecOptions extends OpenSpecPluginOptions {
      * @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.
@@ -21,13 +26,16 @@ export 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/`).
+     * 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 './openspec'
+     * @default auto-detected (`<nearest ancestor>/openspec`, falling back to `'./openspec'`)
      * @example
      * // Resolving from docs/.vitepress/config.ts
      * import path from 'node:path'
@@ -44,10 +52,12 @@ export interface OpenSpecPluginOptions {
     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.
+     * (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 process.cwd()
+     * @default auto-detected (directory containing `.vitepress`, falling back to the working directory)
      * @example path.resolve(__dirname, '..')  // from docs/.vitepress/config.ts
      */
     srcDir?: string;

package/dist/types.d.ts.map

@@ -1 +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;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;OAOG;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"}
+{"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

@@ -1,60 +1,9 @@
-import type { CapabilitySpec, Change, NavItem, OpenSpecFolder, SidebarItem } from './types.js';
 /**
- * Scans an openspec/ directory and returns a structured representation of all
- * canonical specs, active changes, and archived changes.
- *
- * Throws if the directory does not exist.
+ * Compatibility re-exports. The implementation lives in `./lib/` modules;
+ * these named exports are kept stable for existing consumers.
  */
-export declare function readOpenSpecFolder(dir: string): OpenSpecFolder;
-/**
- * Generates VitePress Markdown for a canonical capability spec page.
- */
-export declare function generateSpecPage(spec: CapabilitySpec): string;
-/**
- * Generates the index page listing all canonical specs.
- */
-export declare function generateSpecsIndexPage(specs: CapabilitySpec[], outDir: string): string;
-/**
- * Generates the index page for a single change.
- */
-export declare function generateChangeIndexPage(change: Change, outDir: string): string;
-/**
- * Generates the changes overview page listing active and archived changes.
- */
-export declare function generateChangesIndexPage(folder: OpenSpecFolder, outDir: string): string;
-/**
- * Rewrites relative markdown links in an artifact file's content so that they
- * use absolute VitePress paths instead of paths relative to the original
- * openspec source directory.
- *
- * When artifact files (proposal.md, design.md, tasks.md) are copied from the
- * openspec source directory into the VitePress output directory, any relative
- * links they contain that reference other files within the openspec directory
- * must be rewritten to absolute VitePress paths — otherwise VitePress will
- * report them as dead links.
- *
- * Links that point outside the openspec root, absolute paths, HTTP URLs, and
- * anchor-only links are left unchanged.
- *
- * @param content - The markdown content of the artifact file.
- * @param srcFilePath - The absolute path of the source artifact file.
- * @param openspecRootDir - The absolute path of the openspec root directory.
- * @param outDir - The VitePress output directory name (e.g. `"openspec"`).
- * @returns The content with rewritten links.
- */
-export declare function rewriteRelativeLinks(content: string, srcFilePath: string, openspecRootDir: string, outDir: string): string;
-/**
- * Returns a VitePress sidebar configuration for the OpenSpec documentation.
- * Includes groups for Specifications, active Changes, and archived Changes.
- */
-export declare function generateOpenSpecSidebar(specDir: string, options?: {
-    outDir?: string;
-}): SidebarItem[];
-/**
- * Returns a VitePress nav entry for the OpenSpec documentation section.
- */
-export declare function openspecNav(specDir: string, options?: {
-    outDir?: string;
-    text?: string;
-}): NavItem | null;
+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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,MAAM,EAEN,OAAO,EACP,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAA;AA0EnB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAoE9D;AA6DD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAe7D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAetF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAuB9E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA8BvF;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,GACb,MAAM,CAoDR;AAgBD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,WAAW,EAAE,CA+Cf;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/C,OAAO,GAAG,IAAI,CAUhB"}
+{"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.1",
+  "version": "0.8.0",
   "description": "A VitePress plugin that integrates OpenSpec documentation into your VitePress site",
   "keywords": [
     "openspec",