@open-agent-toolkit/cli 0.3.10 → 0.3.12

package/dist/commands/docs/nav/fumadocs.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The `meta.json` keys nav sync owns. Every other key (`icon`, `defaultOpen`,
+ * `description`, ...) is left as the author wrote it.
+ */
+export interface FumadocsMeta {
+    title?: string;
+    pages: string[];
+}
+export interface FumadocsMetaFile {
+    /** Docs-relative POSIX path of the `meta.json` file. */
+    path: string;
+    meta: FumadocsMeta;
+    changed: boolean;
+}
+export interface SyncFumadocsNavigationResult {
+    metaFiles: FumadocsMetaFile[];
+    /** Docs-relative paths of the `meta.json` files this run wrote. */
+    written: string[];
+    /**
+     * Docs-relative paths of the `meta.json` files that were missing or differed
+     * by meaning before this run. Equal to `written` unless `check` was set.
+     */
+    stale: string[];
+    /**
+     * Docs-relative paths no Contents map places in the page tree. A folder is
+     * reported once as `folder/` instead of once per page inside it.
+     */
+    unlisted: string[];
+}
+/**
+ * Reduce a Markdown heading to the plain text a sidebar shows: images and
+ * links keep their text, code spans keep their content, and emphasis and
+ * strikethrough markers are dropped.
+ */
+export declare function stripInlineMarkdown(text: string): string;
+/** Folder title: frontmatter `title`, else the first H1 outside code fences. */
+export declare function resolveFolderTitle(markdown: string): string | undefined;
+/**
+ * The `pages` item for a page or folder in the same directory. A name the
+ * builder would read as a directive (`!hidden`, `z...a`, `---`, ...) is
+ * written in the local-path form `./name`, which its path join resolves to
+ * the same file; every other name is written as is.
+ */
+export declare function toFumadocsPageItem(name: string): string;
+/**
+ * Write one strict `meta.json` per docs directory that has an index.md,
+ * derived from that index's Contents map, and report every page the
+ * resulting page tree leaves out.
+ *
+ * Existing files are compared by meaning (parsed and deep-equal), so a run
+ * with no doc changes writes nothing even after a formatter rewrites them.
+ */
+export declare function syncFumadocsNavigation(options: {
+    docsRoot: string;
+    /** Compute and compare only; never write. */
+    check?: boolean;
+}): Promise<SyncFumadocsNavigationResult>;
+//# sourceMappingURL=fumadocs.d.ts.map

package/dist/commands/docs/nav/fumadocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAyDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoCvE;AA8BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAoLD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAkExC"}

package/dist/commands/docs/nav/fumadocs.js

@@ -0,0 +1,326 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, extname, join, posix } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { getFrontmatterBlock, parseFrontmatterScalarFields, } from '../../shared/frontmatter.js';
+import { fileExists } from '../../../fs/io.js';
+import { parseIndexContents, resolveEntryTarget } from './contents.js';
+const PAGE_EXTENSIONS = ['.md', '.mdx'];
+const GROUP_FOLDER = /^\(.+\)$/;
+// The `pages` item grammar of the fumadocs-core 16.10.2 page-tree builder
+// (`resolveFolderItem`): exact rest entries, separators, links, and the
+// exclude and extract prefixes are checked before an item is read as a path.
+const FUMADOCS_REST_ITEMS = new Set(['...', 'z...a']);
+const FUMADOCS_SEPARATOR = /^---(?:\[(?<icon>[^\]]+)])?(?<name>.+)---|^---$/;
+const FUMADOCS_LINK = /^(?<external>external:)?(?:\[(?<icon>[^\]]+)])?\[(?<name>[^\]]+)]\((?<url>[^)]+)\)$/;
+const FUMADOCS_PREFIXES = ['!', '...'];
+const H1 = /^#\s+(.+?)\s*#*\s*$/;
+const FENCE = /^\s*(```|~~~)/;
+function parentDir(path) {
+    return posix.dirname(path);
+}
+async function inventoryDocs(docsRoot) {
+    const directories = [];
+    const pages = [];
+    async function walk(relativeDir) {
+        directories.push(relativeDir);
+        const entries = await readdir(join(docsRoot, relativeDir), {
+            withFileTypes: true,
+        });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+                continue;
+            }
+            const entryPath = posix.join(relativeDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryPath);
+            }
+            else if (entry.isFile() &&
+                PAGE_EXTENSIONS.includes(extname(entry.name))) {
+                pages.push(entryPath);
+            }
+        }
+    }
+    await walk('.');
+    directories.sort();
+    pages.sort();
+    return { directories, pages };
+}
+/**
+ * Reduce a Markdown heading to the plain text a sidebar shows: images and
+ * links keep their text, code spans keep their content, and emphasis and
+ * strikethrough markers are dropped.
+ */
+export function stripInlineMarkdown(text) {
+    return text
+        .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/(`+)(.+?)\1/g, '$2')
+        .replace(/(\*\*|__|~~)(.+?)\1/g, '$2')
+        .replace(/(^|[^\w*])[*_]([^*_]+?)[*_](?=[^\w*]|$)/g, '$1$2')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Folder title: frontmatter `title`, else the first H1 outside code fences. */
+export function resolveFolderTitle(markdown) {
+    const frontmatter = getFrontmatterBlock(markdown);
+    if (frontmatter !== null) {
+        const title = parseFrontmatterScalarFields(frontmatter, ['title']).values
+            .title;
+        if (title) {
+            return title;
+        }
+    }
+    const body = frontmatter === null
+        ? markdown
+        : markdown.slice(markdown.indexOf('\n---', 4) + 4);
+    let fence = null;
+    for (const line of body.split(/\r?\n/)) {
+        const fenceMatch = line.match(FENCE);
+        if (fenceMatch) {
+            const marker = fenceMatch[1];
+            if (fence === null) {
+                fence = marker;
+            }
+            else if (fence === marker) {
+                fence = null;
+            }
+            continue;
+        }
+        if (fence !== null) {
+            continue;
+        }
+        const heading = line.match(H1);
+        if (heading?.[1]) {
+            return stripInlineMarkdown(heading[1]) || undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * The URL Fumadocs assigns a page, following `getSlugs` in fumadocs-core's
+ * slugs plugin with the scaffolded `baseUrl: '/'`: group folders are dropped,
+ * segments are URI-encoded, and an `index` file maps to its folder.
+ */
+function pageUrl(pagePath) {
+    const slugs = parentDir(pagePath)
+        .split('/')
+        .filter((segment) => segment.length > 0 && segment !== '.')
+        .filter((segment) => !GROUP_FOLDER.test(segment))
+        .map((segment) => encodeURI(segment));
+    const name = basename(pagePath, extname(pagePath));
+    if (name !== 'index') {
+        slugs.push(encodeURI(name));
+    }
+    return `/${slugs.join('/')}`;
+}
+/** Whether the Fumadocs page-tree builder reads `item` as a directive, not a path. */
+function isFumadocsDirective(item) {
+    return (FUMADOCS_REST_ITEMS.has(item) ||
+        FUMADOCS_SEPARATOR.test(item) ||
+        FUMADOCS_LINK.test(item) ||
+        FUMADOCS_PREFIXES.some((prefix) => item.startsWith(prefix)));
+}
+/**
+ * The `pages` item for a page or folder in the same directory. A name the
+ * builder would read as a directive (`!hidden`, `z...a`, `---`, ...) is
+ * written in the local-path form `./name`, which its path join resolves to
+ * the same file; every other name is written as is.
+ */
+export function toFumadocsPageItem(name) {
+    return isFumadocsDirective(name) ? `./${name}` : name;
+}
+function hrefFragment(href) {
+    const hashIndex = href.indexOf('#');
+    return hashIndex >= 0 ? href.slice(hashIndex) : '';
+}
+/**
+ * Build one folder's `pages` from its index.md Contents map.
+ *
+ * A page in this folder or an immediate subfolder is referenced by name. Any
+ * other target becomes a Fumadocs link entry, so no page is claimed by two
+ * folders. There is never a `"..."` rest entry: pages the Contents map does
+ * not list stay out of the tree and are reported instead.
+ */
+/**
+ * Whether the fumadocs-core 16.10.2 page-tree builder supplies this folder's
+ * `index` page on its own, given the folder's effective metadata.
+ *
+ * `buildFolder` attaches `<folder>/index` as the folder index only when the
+ * folder is not a root folder (the docs root, or a preserved `root: true`)
+ * and no `pagesIndex` names a different page. Otherwise the page is shown
+ * only if `pages` lists it.
+ */
+function hasImplicitIndex(relativeDir, existing) {
+    if (relativeDir === '.' || existing?.root === true) {
+        return false;
+    }
+    const pagesIndex = existing?.pagesIndex;
+    return pagesIndex === undefined || pagesIndex === 'index';
+}
+async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex) {
+    const indexPath = join(docsRoot, relativeDir, 'index.md');
+    const entries = parseIndexContents(markdown, indexPath);
+    // A folder the loader gives no implicit index (the docs root, a `root: true`
+    // folder) must list `index` to show its landing page. Elsewhere, listing
+    // `index` would demote the folder index to an ordinary child, so it is left
+    // implicit.
+    const pages = implicitIndex ? [] : ['index'];
+    for (const entry of entries) {
+        const target = await resolveEntryTarget(docsRoot, join(docsRoot, relativeDir), relativeDir, entry, PAGE_EXTENSIONS);
+        const targetDir = parentDir(target.path);
+        let item;
+        if (target.kind === 'section' && targetDir === relativeDir) {
+            continue;
+        }
+        else if (target.kind === 'section' &&
+            parentDir(targetDir) === relativeDir) {
+            item = toFumadocsPageItem(basename(targetDir));
+        }
+        else if (target.kind === 'page' && targetDir === relativeDir) {
+            item = toFumadocsPageItem(basename(target.path, extname(target.path)));
+        }
+        else {
+            item = `[${entry.title}](${pageUrl(target.path)}${hrefFragment(entry.href)})`;
+        }
+        if (!pages.includes(item)) {
+            pages.push(item);
+        }
+    }
+    return pages;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function readExistingMeta(metaPath) {
+    if (!(await fileExists(metaPath))) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(metaPath, 'utf8'));
+        return isPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        // A generated file that no longer parses (for example after a merge
+        // conflict) is regenerated rather than preserved.
+        return null;
+    }
+}
+function mergeMeta(existing, meta) {
+    const { title: _title, pages: _pages, ...unowned } = existing ?? {};
+    return {
+        ...unowned,
+        ...(meta.title === undefined ? {} : { title: meta.title }),
+        pages: meta.pages,
+    };
+}
+function collectUnlisted(inventory, metas, implicitIndexDirs) {
+    const reachableDirs = new Set();
+    const reachablePages = new Set();
+    const pagesByFlattenPath = new Map(inventory.pages.map((page) => [
+        page.slice(0, page.length - extname(page).length),
+        page,
+    ]));
+    function visit(relativeDir) {
+        reachableDirs.add(relativeDir);
+        const meta = metas.get(relativeDir);
+        if (!meta) {
+            return;
+        }
+        // A landing page is reachable only when the loader attaches it as the
+        // folder index or `pages` lists it, never just because the file exists.
+        const index = pagesByFlattenPath.get(posix.join(relativeDir, 'index'));
+        if (index && implicitIndexDirs.has(relativeDir)) {
+            reachablePages.add(index);
+        }
+        for (const item of meta.pages) {
+            // Read items the way the loader does: a directive (including a link
+            // entry) names no local page, and `./name` joins to `name`.
+            if (isFumadocsDirective(item)) {
+                continue;
+            }
+            const itemPath = posix.join(relativeDir, item);
+            if (metas.has(itemPath) && !reachableDirs.has(itemPath)) {
+                visit(itemPath);
+                continue;
+            }
+            const page = pagesByFlattenPath.get(itemPath);
+            if (page) {
+                reachablePages.add(page);
+            }
+        }
+    }
+    visit('.');
+    const unlisted = new Set();
+    for (const page of inventory.pages) {
+        if (reachablePages.has(page)) {
+            continue;
+        }
+        let topmostHiddenDir = null;
+        for (let dir = parentDir(page); dir !== '.' && dir.length > 0; dir = parentDir(dir)) {
+            if (!reachableDirs.has(dir)) {
+                topmostHiddenDir = dir;
+            }
+        }
+        unlisted.add(topmostHiddenDir === null ? page : `${topmostHiddenDir}/`);
+    }
+    return [...unlisted].sort();
+}
+/**
+ * Write one strict `meta.json` per docs directory that has an index.md,
+ * derived from that index's Contents map, and report every page the
+ * resulting page tree leaves out.
+ *
+ * Existing files are compared by meaning (parsed and deep-equal), so a run
+ * with no doc changes writes nothing even after a formatter rewrites them.
+ */
+export async function syncFumadocsNavigation(options) {
+    const { docsRoot } = options;
+    const inventory = await inventoryDocs(docsRoot);
+    const metas = new Map();
+    const existingMetas = new Map();
+    const implicitIndexDirs = new Set();
+    for (const relativeDir of inventory.directories) {
+        const indexPath = join(docsRoot, relativeDir, 'index.md');
+        if (!(await fileExists(indexPath))) {
+            continue;
+        }
+        // Index handling depends on the effective metadata, which keeps the
+        // author-owned `root` and `pagesIndex` keys of an existing meta.json.
+        const existing = await readExistingMeta(join(docsRoot, relativeDir, 'meta.json'));
+        existingMetas.set(relativeDir, existing);
+        const implicitIndex = hasImplicitIndex(relativeDir, existing);
+        if (implicitIndex) {
+            implicitIndexDirs.add(relativeDir);
+        }
+        const markdown = await readFile(indexPath, 'utf8');
+        const title = resolveFolderTitle(markdown);
+        metas.set(relativeDir, {
+            ...(title === undefined ? {} : { title }),
+            pages: await buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex),
+        });
+    }
+    if (!metas.has('.')) {
+        throw new Error(`Missing required index.md at ${join(docsRoot, 'index.md')}`);
+    }
+    const metaFiles = [];
+    for (const [relativeDir, meta] of metas) {
+        const relativePath = posix.join(relativeDir, 'meta.json');
+        const metaPath = join(docsRoot, relativePath);
+        const existing = existingMetas.get(relativeDir) ?? null;
+        const next = mergeMeta(existing, meta);
+        const changed = existing === null || !isDeepStrictEqual(existing, next);
+        if (changed && !options.check) {
+            await writeFile(metaPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+        }
+        metaFiles.push({ path: relativePath, meta, changed });
+    }
+    metaFiles.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const stale = metaFiles
+        .filter((file) => file.changed)
+        .map((file) => file.path);
+    return {
+        metaFiles,
+        written: options.check ? [] : stale,
+        stale,
+        unlisted: collectUnlisted(inventory, metas, implicitIndexDirs),
+    };
+}

package/dist/commands/docs/nav/sync.d.ts

@@ -1,19 +1,49 @@
 import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
 import { Command } from 'commander';
 import { type DocsNavTree } from './contents.js';
+import { type FumadocsMetaFile } from './fumadocs.js';
+export type DocsNavFramework = 'fumadocs' | 'mkdocs';
 interface SyncDocsNavigationOptions {
     appRoot: string;
+    /**
+     * `documentation.tooling` from `.oat/config.json` when the app is the
+     * configured docs root. Used only when no framework marker file is found.
+     */
+    configuredTooling?: string | null;
+    /** Compute the navigation and compare it with the files; write nothing. */
+    check?: boolean;
 }
-interface SyncDocsNavigationResult {
+interface MkDocsNavigationResult {
+    framework: 'mkdocs';
     appRoot: string;
     docsRoot: string;
     mkdocsPath: string;
     nav: DocsNavTree;
+    /** `['mkdocs.yml']` when its `nav:` block differed before this run. */
+    stale: string[];
 }
+interface FumadocsNavigationResult {
+    framework: 'fumadocs';
+    appRoot: string;
+    docsRoot: string;
+    metaFiles: FumadocsMetaFile[];
+    written: string[];
+    stale: string[];
+    unlisted: string[];
+}
+type SyncDocsNavigationResult = MkDocsNavigationResult | FumadocsNavigationResult;
 interface DocsNavSyncDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
+    resolveConfiguredTooling: (cwd: string, appRoot: string) => Promise<string | null>;
     syncDocsNavigation: (options: SyncDocsNavigationOptions) => Promise<SyncDocsNavigationResult>;
 }
+/**
+ * Detect the docs framework from the app's own files: `mkdocs.yml` keeps the
+ * MkDocs path (checked first, so existing MkDocs apps behave as before) and a
+ * Fumadocs `source.config.*` selects `meta.json` output. Without either
+ * marker, a configured `documentation.tooling` decides.
+ */
+export declare function detectDocsNavFramework(appRoot: string, configuredTooling?: string | null): Promise<DocsNavFramework>;
 export declare function syncDocsNavigation(options: SyncDocsNavigationOptions): Promise<SyncDocsNavigationResult>;
 export declare function createDocsNavSyncCommand(overrides?: Partial<DocsNavSyncDependencies>): Command;
 export {};

package/dist/commands/docs/nav/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/sync.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAMhE,UAAU,yBAAyB;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,wBAAwB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,WAAW,CAAC;CAClB;AAED,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAClB,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACxC;AAmCD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAmBnC;AAuCD,wBAAgB,wBAAwB,CACtC,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAoBT"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/sync.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAOrD,UAAU,yBAAyB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,sBAAsB;IAC9B,SAAS,EAAE,QAAQ,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,WAAW,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,UAAU,wBAAwB;IAChC,SAAS,EAAE,UAAU,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,KAAK,wBAAwB,GACzB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,wBAAwB,EAAE,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,kBAAkB,EAAE,CAClB,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACxC;AAsBD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAe3B;AAqDD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA0CnC;AAmJD,wBAAgB,wBAAwB,CACtC,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CA4BT"}

package/dist/commands/docs/nav/sync.js

@@ -2,11 +2,65 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { readOatConfig } from '../../../config/oat-config.js';
+import { fileExists } from '../../../fs/io.js';
+import { resolveProjectRoot } from '../../../fs/paths.js';
 import { Command, Option } from 'commander';
 import YAML from 'yaml';
 import { buildDocsNavTree } from './contents.js';
+import { syncFumadocsNavigation } from './fumadocs.js';
+const MKDOCS_MARKERS = ['mkdocs.yml'];
+const FUMADOCS_MARKERS = [
+    'source.config.ts',
+    'source.config.mts',
+    'source.config.js',
+    'source.config.mjs',
+];
+async function hasAnyMarker(appRoot, markers) {
+    for (const marker of markers) {
+        if (await fileExists(join(appRoot, marker))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Detect the docs framework from the app's own files: `mkdocs.yml` keeps the
+ * MkDocs path (checked first, so existing MkDocs apps behave as before) and a
+ * Fumadocs `source.config.*` selects `meta.json` output. Without either
+ * marker, a configured `documentation.tooling` decides.
+ */
+export async function detectDocsNavFramework(appRoot, configuredTooling) {
+    if (await hasAnyMarker(appRoot, MKDOCS_MARKERS)) {
+        return 'mkdocs';
+    }
+    if (await hasAnyMarker(appRoot, FUMADOCS_MARKERS)) {
+        return 'fumadocs';
+    }
+    const tooling = configuredTooling?.trim().toLowerCase();
+    if (tooling === 'mkdocs' || tooling === 'fumadocs') {
+        return tooling;
+    }
+    throw new Error(`Could not detect the docs framework in ${appRoot}: expected mkdocs.yml (MkDocs) ` +
+        'or source.config.ts (Fumadocs).');
+}
+async function resolveConfiguredTooling(cwd, appRoot) {
+    try {
+        const repoRoot = await resolveProjectRoot(cwd);
+        const config = await readOatConfig(repoRoot);
+        const root = config.documentation?.root?.trim();
+        if (!root || resolve(repoRoot, root) !== appRoot) {
+            return null;
+        }
+        return config.documentation?.tooling?.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
+    resolveConfiguredTooling,
     syncDocsNavigation,
 };
 function replaceTopLevelYamlSection(source, key, replacement) {
@@ -30,27 +84,129 @@ function replaceTopLevelYamlSection(source, key, replacement) {
     ].join('\n');
 }
 export async function syncDocsNavigation(options) {
-    const mkdocsPath = join(options.appRoot, 'mkdocs.yml');
     const docsRoot = join(options.appRoot, 'docs');
+    const framework = await detectDocsNavFramework(options.appRoot, options.configuredTooling);
+    if (framework === 'fumadocs') {
+        const result = await syncFumadocsNavigation({
+            docsRoot,
+            check: options.check,
+        });
+        return {
+            framework,
+            appRoot: options.appRoot,
+            docsRoot,
+            ...result,
+        };
+    }
+    const mkdocsPath = join(options.appRoot, 'mkdocs.yml');
     const nav = await buildDocsNavTree({ docsRoot });
     const mkdocsSource = await readFile(mkdocsPath, 'utf8');
     const navSection = YAML.stringify({ nav }).trimEnd();
     const updatedMkdocsSource = replaceTopLevelYamlSection(mkdocsSource, 'nav', navSection);
-    await writeFile(mkdocsPath, `${updatedMkdocsSource.trimEnd()}\n`, 'utf8');
+    const nextMkdocsSource = `${updatedMkdocsSource.trimEnd()}\n`;
+    if (!options.check) {
+        await writeFile(mkdocsPath, nextMkdocsSource, 'utf8');
+    }
     return {
+        framework,
         appRoot: options.appRoot,
         docsRoot,
         mkdocsPath,
         nav,
+        stale: nextMkdocsSource === mkdocsSource ? [] : ['mkdocs.yml'],
     };
 }
+function reportFumadocsResult(context, targetDir, result) {
+    if (context.json) {
+        context.logger.json({
+            status: 'ok',
+            framework: result.framework,
+            appRoot: result.appRoot,
+            docsRoot: result.docsRoot,
+            metaFiles: result.metaFiles,
+            written: result.written,
+            unlisted: result.unlisted,
+        });
+        return;
+    }
+    context.logger.info(`Synced docs navigation in ${targetDir}`);
+    context.logger.info('  Framework: Fumadocs (meta.json)');
+    context.logger.info(`  Docs root: ${result.docsRoot}`);
+    if (result.written.length === 0) {
+        context.logger.info('  No meta.json changes');
+    }
+    else {
+        context.logger.info(`  Wrote ${result.written.length} meta.json file(s):`);
+        for (const path of result.written) {
+            context.logger.info(`    ${path}`);
+        }
+    }
+    if (result.unlisted.length > 0) {
+        context.logger.warn(`  ${result.unlisted.length} path(s) are not listed in any index.md Contents map ` +
+            'and stay out of the navigation:');
+        for (const path of result.unlisted) {
+            context.logger.warn(`    ${path}`);
+        }
+    }
+}
+/**
+ * `--check`: report drift without writing. Fails (exit 1) when any generated
+ * navigation file would change or, for Fumadocs, any page or folder is
+ * unlisted, since strict navigation hides it from the sidebar.
+ */
+function reportCheckResult(context, targetDir, result) {
+    const unlisted = result.framework === 'fumadocs' ? result.unlisted : [];
+    const current = result.stale.length === 0 && unlisted.length === 0;
+    if (context.json) {
+        context.logger.json({
+            status: current ? 'ok' : 'drift',
+            check: true,
+            framework: result.framework,
+            appRoot: result.appRoot,
+            docsRoot: result.docsRoot,
+            stale: result.stale,
+            unlisted,
+        });
+        return current;
+    }
+    if (current) {
+        context.logger.info(`Docs navigation is up to date in ${targetDir}`);
+        return current;
+    }
+    context.logger.error(`Docs navigation is out of date in ${targetDir}`);
+    if (result.stale.length > 0) {
+        context.logger.error(`  ${result.stale.length} generated file(s) differ from the index.md Contents maps:`);
+        for (const path of result.stale) {
+            context.logger.error(`    ${path}`);
+        }
+    }
+    if (unlisted.length > 0) {
+        context.logger.error(`  ${unlisted.length} path(s) are not listed in any index.md Contents map ` +
+            'and would be hidden from the sidebar:');
+        for (const path of unlisted) {
+            context.logger.error(`    ${path}`);
+        }
+    }
+    context.logger.error(`  List every page in its directory's ## Contents, then run \`oat docs nav sync --target-dir ${targetDir}\`.`);
+    return current;
+}
 async function runDocsNavSyncCommand(context, options, dependencies) {
     try {
         const targetDir = options.targetDir ?? '.';
+        const appRoot = resolve(context.cwd, targetDir);
         const result = await dependencies.syncDocsNavigation({
-            appRoot: resolve(context.cwd, targetDir),
+            appRoot,
+            configuredTooling: await dependencies.resolveConfiguredTooling(context.cwd, appRoot),
+            check: options.check === true,
         });
-        if (context.json) {
+        if (options.check) {
+            process.exitCode = reportCheckResult(context, targetDir, result) ? 0 : 1;
+            return;
+        }
+        if (result.framework === 'fumadocs') {
+            reportFumadocsResult(context, targetDir, result);
+        }
+        else if (context.json) {
             context.logger.json({
                 status: 'ok',
                 appRoot: result.appRoot,
@@ -83,8 +239,9 @@ export function createDocsNavSyncCommand(overrides = {}) {
         ...overrides,
     };
     return new Command('sync')
-        .description('Regenerate docs navigation from index.md contents')
-        .addOption(new Option('--target-dir <path>', 'Docs app directory containing mkdocs.yml'))
+        .description('Regenerate docs navigation from index.md contents: mkdocs.yml nav (MkDocs) or strict meta.json files (Fumadocs)')
+        .addOption(new Option('--target-dir <path>', 'Docs app directory containing mkdocs.yml or source.config.ts'))
+        .addOption(new Option('--check', 'Write nothing; exit 1 if any navigation file is stale or any page is unlisted'))
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         await runDocsNavSyncCommand(context, options, dependencies);

package/dist/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyBzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0BvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2BvD"}

package/dist/commands/index.js

@@ -20,6 +20,7 @@ import { createReviewCommand } from './review/index.js';
 import { createStateCommand } from './state/index.js';
 import { createStatusCommand } from './status/index.js';
 import { createSyncCommand } from './sync/index.js';
+import { createTemplateCommand } from './template/index.js';
 import { createToolsCommand } from './tools/index.js';
 export function registerCommands(program) {
     program.addCommand(createBacklogCommand());
@@ -42,6 +43,7 @@ export function registerCommands(program) {
     program.addCommand(createPjmCommand());
     program.addCommand(createProjectCommand());
     program.addCommand(createStateCommand());
+    program.addCommand(createTemplateCommand());
     program.addCommand(createToolsCommand());
     program.addCommand(createInternalCommand());
     // Commander's .addCommand() does not inherit help config from the parent.