@open-agent-toolkit/cli 0.3.27 → 0.3.29

package/dist/commands/docs/check/files.js

@@ -0,0 +1,121 @@
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
+import { readOatConfig, resolveDocumentationContentRoot, } from '../../../config/oat-config.js';
+import { resolveProjectRoot } from '../../../fs/paths.js';
+import { parsePage } from './markdown.js';
+export function posix(path) {
+    return path.replaceAll('\\', '/');
+}
+export function inside(root, path) {
+    const rel = relative(root, path);
+    return (rel !== '..' &&
+        !rel.startsWith('../') &&
+        !rel.startsWith('..\\') &&
+        !isAbsolute(rel));
+}
+export async function present(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+            return false;
+        throw error;
+    }
+}
+// Preserve the lexical missing-path diagnostic, but compare existing aliases by identity.
+async function canonicalPath(path) {
+    return (await present(path)) ? realpath(path) : path;
+}
+export async function resolveCheckTarget(cwd, targetDir) {
+    let repoRoot;
+    try {
+        repoRoot = await resolveProjectRoot(cwd);
+    }
+    catch {
+        repoRoot = cwd;
+    }
+    repoRoot = await realpath(repoRoot);
+    const config = await readOatConfig(repoRoot);
+    const doc = config.documentation ?? {};
+    const configured = doc.root
+        ? await canonicalPath(resolve(repoRoot, doc.root))
+        : undefined;
+    const requested = resolve(cwd, targetDir ?? configured ?? join(repoRoot, 'docs'));
+    const appRoot = await canonicalPath(requested);
+    const matching = configured === appRoot;
+    const framework = matching && doc.tooling === 'markdown'
+        ? 'markdown'
+        : (await present(join(appRoot, 'mkdocs.yml')))
+            ? 'mkdocs'
+            : (await Promise.all(['ts', 'mts', 'js', 'mjs'].map((ext) => present(join(appRoot, `source.config.${ext}`))))).some(Boolean)
+                ? 'fumadocs'
+                : matching && (doc.tooling === 'mkdocs' || doc.tooling === 'fumadocs')
+                    ? doc.tooling
+                    : 'markdown';
+    // The established resolver owns configured nested docs semantics. An
+    // unrelated explicit Markdown root remains literal, even with a docs child.
+    const configuredContent = await resolveDocumentationContentRoot(repoRoot, config);
+    const configuredContentPath = configuredContent
+        ? await canonicalPath(resolve(repoRoot, configuredContent))
+        : undefined;
+    const contentRoot = matching && configuredContentPath
+        ? configuredContentPath
+        : framework === 'markdown'
+            ? appRoot
+            : join(appRoot, 'docs');
+    if (!(await present(contentRoot)))
+        throw new Error(`Docs content directory does not exist: ${contentRoot}. Set documentation.root or pass --target-dir.`);
+    const matchesContent = configuredContentPath !== undefined && configuredContentPath === appRoot;
+    const documentation = matching || matchesContent ? doc : {};
+    return {
+        repoRoot,
+        appRoot,
+        contentRoot: await realpath(contentRoot),
+        framework,
+        documentation,
+        matcher: createExclusionMatcher(documentation.nonReaderPaths ?? []),
+    };
+}
+export async function readerFiles(target) {
+    const files = [];
+    const walk = async (dir) => {
+        const entries = await readdir(join(target.contentRoot, dir), {
+            withFileTypes: true,
+        });
+        for (const e of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            const path = posix(join(dir, e.name));
+            if (e.isDirectory() && !isExcludedPath(target.matcher, path, true))
+                await walk(path);
+            else if (e.isFile() &&
+                /\.mdx?$/.test(e.name) &&
+                !isExcludedPath(target.matcher, path))
+                files.push(path);
+        }
+    };
+    await walk('');
+    return files;
+}
+export async function readPage(target, path) {
+    return parsePage(path, await readFile(join(target.contentRoot, path), 'utf8'));
+}
+/** Never follow a link outside its allowed root, including symlink escapes. */
+export async function containedFile(root, path) {
+    if (!inside(root, path) || !(await present(path)))
+        return false;
+    return (inside(await realpath(root), await realpath(path)) &&
+        (await stat(path)).isFile());
+}
+export function readerDirectories(paths) {
+    const dirs = new Set(['.']);
+    for (const path of paths) {
+        let dir = dirname(path);
+        while (dir !== '.') {
+            dirs.add(posix(dir));
+            dir = dirname(dir);
+        }
+    }
+    return [...dirs].sort();
+}

package/dist/commands/docs/check/markdown.d.ts

@@ -0,0 +1,60 @@
+export interface MarkdownNode {
+    type: string;
+    name?: string;
+    value?: string;
+    depth?: number;
+    url?: string;
+    alt?: string;
+    identifier?: string;
+    lang?: string | null;
+    children?: MarkdownNode[];
+    position?: {
+        start: {
+            line: number;
+            column: number;
+            offset?: number;
+        };
+        end: {
+            line: number;
+            column: number;
+            offset?: number;
+        };
+    };
+}
+export interface PageLink {
+    href: string;
+    line: number;
+    image: boolean;
+    alt?: string;
+    html?: boolean;
+    describedBy?: string;
+}
+export interface ParsedPage {
+    path: string;
+    source: string;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    frontmatterError?: string;
+    nodes: MarkdownNode[];
+    anchors: Set<string>;
+    links: PageLink[];
+    text: string;
+}
+export declare function nodeText(node: MarkdownNode): string;
+interface HtmlNode {
+    nodeName: string;
+    value?: string;
+    attrs?: Array<{
+        name: string;
+        value: string;
+    }>;
+    childNodes?: HtmlNode[];
+    sourceCodeLocation?: {
+        startLine: number;
+    };
+}
+export declare function htmlNodes(html: string): HtmlNode[];
+export declare function attributes(node: HtmlNode): Record<string, string>;
+export declare function parsePage(path: string, source: string): ParsedPage;
+export {};
+//# sourceMappingURL=markdown.d.ts.map

package/dist/commands/docs/check/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/markdown.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACzD,GAAG,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACxD,CAAC;CACH;AACD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AACD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAInD;AACD,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AACD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAQlD;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEjE;AACD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAoGlE"}

package/dist/commands/docs/check/markdown.js

@@ -0,0 +1,125 @@
+import { remarkTabs } from '@open-agent-toolkit/docs-transforms';
+import Slugger from 'github-slugger';
+import { parseFragment } from 'parse5';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import YAML from 'yaml';
+export function nodeText(node) {
+    return node.children
+        ? node.children.map(nodeText).join('')
+        : (node.value ?? '');
+}
+export function htmlNodes(html) {
+    const nodes = [];
+    const walk = (n) => {
+        nodes.push(n);
+        n.childNodes?.forEach(walk);
+    };
+    walk(parseFragment(html, { sourceCodeLocationInfo: true }));
+    return nodes;
+}
+export function attributes(node) {
+    return Object.fromEntries(node.attrs?.map((a) => [a.name, a.value]) ?? []);
+}
+export function parsePage(path, source) {
+    let body = source;
+    let frontmatter = {};
+    let frontmatterError;
+    const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+    if (match) {
+        // Preserve physical positions for both AST and Contents diagnostics.
+        body = match[0].replace(/[^\r\n]/g, ' ') + source.slice(match[0].length);
+        try {
+            const doc = YAML.parseDocument(match[1]);
+            if (doc.errors.length)
+                frontmatterError = `Invalid YAML frontmatter: ${doc.errors[0].message}`;
+            else {
+                const data = doc.toJS();
+                if (typeof data !== 'object' || data === null || Array.isArray(data))
+                    frontmatterError = 'Frontmatter must be a YAML mapping';
+                else
+                    frontmatter = data;
+            }
+        }
+        catch (error) {
+            frontmatterError = `Invalid YAML frontmatter: ${error.message}`;
+        }
+    }
+    const processor = unified().use(remarkParse).use(remarkGfm).use(remarkTabs);
+    const tree = processor.runSync(processor.parse(body), {
+        value: body,
+    });
+    const nodes = [];
+    const walk = (node) => {
+        nodes.push(node);
+        node.children?.forEach(walk);
+    };
+    walk(tree);
+    const definitions = new Map();
+    for (const n of nodes)
+        if (n.type === 'definition' &&
+            n.identifier &&
+            n.url &&
+            !definitions.has(n.identifier))
+            definitions.set(n.identifier, n.url);
+    const anchors = new Set();
+    const slugger = new Slugger();
+    const links = [];
+    for (const n of nodes) {
+        const line = n.position?.start.line ?? 1;
+        if (n.type === 'heading') {
+            const text = nodeText(n);
+            const custom = /\s*(?:\[#([^\]]+)\]|\{#([^}]+)\})\s*$/.exec(text);
+            anchors.add(custom?.[1] ?? custom?.[2] ?? slugger.slug(text));
+        }
+        if (['link', 'image', 'linkReference', 'imageReference'].includes(n.type)) {
+            const href = n.url ?? definitions.get(n.identifier ?? '');
+            if (href !== undefined)
+                links.push({
+                    href,
+                    line,
+                    image: n.type.startsWith('image'),
+                    alt: n.alt,
+                });
+        }
+        if (n.type === 'html')
+            for (const element of htmlNodes(n.value ?? '')) {
+                const a = attributes(element);
+                if (a.id)
+                    anchors.add(a.id);
+                if (element.nodeName === 'a' && a.name)
+                    anchors.add(a.name);
+                if (element.nodeName === 'a' && a.href)
+                    links.push({
+                        href: a.href,
+                        image: false,
+                        html: true,
+                        line: line + (element.sourceCodeLocation?.startLine ?? 1) - 1,
+                    });
+                if (element.nodeName === 'img' && a.src)
+                    links.push({
+                        href: a.src,
+                        alt: a.alt,
+                        image: true,
+                        html: true,
+                        describedBy: a['aria-describedby'],
+                        line: line + (element.sourceCodeLocation?.startLine ?? 1) - 1,
+                    });
+            }
+    }
+    return {
+        path,
+        source,
+        body,
+        frontmatter,
+        ...(frontmatterError ? { frontmatterError } : {}),
+        nodes,
+        anchors,
+        links,
+        text: nodes
+            .filter((n) => n.type === 'text')
+            .map((n) => n.value ?? '')
+            .join(' '),
+    };
+}

package/dist/commands/docs/check/mermaid-runtime.d.ts

@@ -0,0 +1,3 @@
+/** Lazy, real Node DOM for Mermaid syntax parsing only. Never renders SVG. */
+export declare function parseMermaid(source: string): Promise<void>;
+//# sourceMappingURL=mermaid-runtime.d.ts.map

package/dist/commands/docs/check/mermaid-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid-runtime.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/mermaid-runtime.ts"],"names":[],"mappings":"AA6CA,8EAA8E;AAC9E,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAehE"}

package/dist/commands/docs/check/mermaid-runtime.js

@@ -0,0 +1,57 @@
+let runtime;
+let queue = Promise.resolve();
+async function withDom(dom, action) {
+    const keys = ['window', 'document'];
+    const saved = keys.map((key) => Object.getOwnPropertyDescriptor(globalThis, key));
+    Object.defineProperty(globalThis, 'window', {
+        configurable: true,
+        value: dom.window,
+    });
+    Object.defineProperty(globalThis, 'document', {
+        configurable: true,
+        value: dom.window.document,
+    });
+    try {
+        return await action();
+    }
+    finally {
+        keys.forEach((key, index) => {
+            const descriptor = saved[index];
+            if (descriptor)
+                Object.defineProperty(globalThis, key, descriptor);
+            else
+                Reflect.deleteProperty(globalThis, key);
+        });
+    }
+}
+async function loadRuntime() {
+    const { JSDOM } = await import('jsdom');
+    // Defaults intentionally disable script execution and external resources.
+    const dom = new JSDOM('');
+    try {
+        const mermaid = await withDom(dom, async () => (await import('mermaid')).default);
+        process.once('beforeExit', () => dom.window.close());
+        return { dom, mermaid };
+    }
+    catch (error) {
+        dom.window.close();
+        throw error;
+    }
+}
+/** Lazy, real Node DOM for Mermaid syntax parsing only. Never renders SVG. */
+export async function parseMermaid(source) {
+    const result = queue.then(async () => {
+        runtime ??= loadRuntime();
+        const { dom, mermaid } = await runtime;
+        await withDom(dom, async () => {
+            mermaid.initialize({
+                startOnLoad: false,
+                securityLevel: 'strict',
+                logLevel: 'fatal',
+            });
+            await mermaid.parse(source);
+        });
+    });
+    queue = result.catch(() => undefined);
+    await result;
+}

package/dist/commands/docs/check/navigation.d.ts

@@ -0,0 +1,4 @@
+import type { Report } from './check.types.js';
+import { type CheckTarget } from './files.js';
+export declare function checkNavigation(target: CheckTarget, report: Report): Promise<void>;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/commands/docs/check/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/navigation.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAgCpD,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmGf"}

package/dist/commands/docs/check/navigation.js

@@ -0,0 +1,104 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { buildDocsNavTree } from '../../docs/nav/contents.js';
+import { syncFumadocsNavigation } from '../../docs/nav/fumadocs.js';
+import { syncDocsNavigation } from '../../docs/nav/sync.js';
+import YAML from 'yaml';
+import { present } from './files.js';
+function pageIdentity(item) {
+    // Hand-authored collision links can use their own display labels.
+    return item.replace(/^\[[^\]]*\]\((.*)\)$/, '[]($1)').replace(/^\.\//, '');
+}
+function navIdentity(value, expected) {
+    if (!Array.isArray(value))
+        return value;
+    return value.map((item, index) => {
+        if (typeof item === 'string')
+            return item;
+        if (typeof item !== 'object' || item === null)
+            return item;
+        const entry = Object.entries(item)[0];
+        if (!entry)
+            return item;
+        const expectedItem = Array.isArray(expected) ? expected[index] : undefined;
+        const children = expectedItem && typeof expectedItem === 'object'
+            ? Object.values(expectedItem)[0]
+            : undefined;
+        // The Contents-derived tree identifies sections by their direct landing path.
+        // Actual landing/page labels are presentation; explicit group labels remain meaningful.
+        const section = Array.isArray(children) &&
+            children.some((child) => typeof child === 'string' && child.endsWith('/index.md'));
+        return Array.isArray(entry[1])
+            ? {
+                [section ? '$section' : entry[0]]: navIdentity(entry[1], children),
+            }
+            : entry[1];
+    });
+}
+export async function checkNavigation(target, report) {
+    if (target.framework === 'markdown')
+        return;
+    try {
+        const generated = target.documentation.navOwner === 'nav-sync';
+        const nonReaderPaths = target.documentation.nonReaderPaths;
+        if (target.framework === 'fumadocs') {
+            const result = await syncFumadocsNavigation({
+                docsRoot: target.contentRoot,
+                check: true,
+                nonReaderPaths,
+            });
+            for (const file of result.metaFiles) {
+                let stale = file.changed;
+                if (!generated) {
+                    if (!(await present(join(target.contentRoot, file.path))))
+                        continue;
+                    try {
+                        const actual = JSON.parse(await readFile(join(target.contentRoot, file.path), 'utf8'));
+                        if (actual &&
+                            typeof actual === 'object' &&
+                            !Array.isArray(actual) &&
+                            !Object.hasOwn(actual, 'pages'))
+                            continue;
+                        stale =
+                            !Array.isArray(actual.pages) ||
+                                !isDeepStrictEqual(actual.pages.map((p) => typeof p === 'string' ? pageIdentity(p) : p), file.meta.pages.map(pageIdentity));
+                    }
+                    catch {
+                        report('navigation', 'error', file.path, 'Cannot read or parse meta.json; check file permissions and JSON syntax.');
+                        continue;
+                    }
+                }
+                if (stale)
+                    report('navigation', 'error', file.path, generated
+                        ? 'Generated navigation is stale; run oat docs nav sync.'
+                        : 'Navigation membership/order differs from authored Contents; update pages or Contents.');
+            }
+            for (const path of result.unlisted)
+                report('navigation', 'error', path, 'Reader page/folder is unlisted in authored Contents and would be hidden from navigation.');
+        }
+        else if (generated) {
+            const result = await syncDocsNavigation({
+                appRoot: target.appRoot,
+                check: true,
+                nonReaderPaths,
+            });
+            for (const path of result.stale)
+                report('navigation', 'error', path, 'Generated navigation is stale; run oat docs nav sync.');
+        }
+        else {
+            const expected = await buildDocsNavTree({
+                docsRoot: target.contentRoot,
+                nonReaderPaths,
+            });
+            const actual = YAML.parse(await readFile(join(target.appRoot, 'mkdocs.yml'), 'utf8'));
+            if (!actual || !Object.hasOwn(actual, 'nav'))
+                return;
+            if (!isDeepStrictEqual(navIdentity(actual.nav, expected), navIdentity(expected, expected)))
+                report('navigation', 'error', 'mkdocs.yml', 'Navigation membership/order differs from authored Contents; update nav or Contents.');
+        }
+    }
+    catch (error) {
+        report('navigation', 'error', 'index.md', error.message);
+    }
+}

package/dist/commands/docs/check/reader-rules.d.ts

@@ -0,0 +1,6 @@
+import type { Report } from './check.types.js';
+import { type CheckTarget } from './files.js';
+import { type ParsedPage } from './markdown.js';
+export declare function checkReaders(target: CheckTarget, pages: ParsedPage[], report: Report): Promise<void>;
+export declare function checkProvenance(target: CheckTarget, pages: ParsedPage[], report: Report): void;
+//# sourceMappingURL=reader-rules.d.ts.map

package/dist/commands/docs/check/reader-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader-rules.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/reader-rules.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAuVf;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CA+CN"}