@open-agent-toolkit/cli 0.3.32 → 0.3.34

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

@@ -1,5 +1,5 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { readFile, realpath, writeFile } from 'node:fs/promises';
+import { join, relative, 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';
@@ -9,6 +9,7 @@ import { Command, Option } from 'commander';
 import YAML from 'yaml';
 import { buildDocsNavTree } from './contents.js';
 import { syncFumadocsNavigation } from './fumadocs.js';
+import { compareFumadocsMembership, compareMkDocsMembership, } from './membership.js';
 const MKDOCS_MARKERS = ['mkdocs.yml'];
 const FUMADOCS_MARKERS = [
     'source.config.ts',
@@ -44,39 +45,64 @@ export async function detectDocsNavFramework(appRoot, configuredTooling) {
     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;
-    }
-}
-async function resolveNonReaderPaths(cwd, appRoot) {
+async function resolveConfiguredDocumentation(cwd) {
     let repoRoot;
     try {
         repoRoot = await resolveProjectRoot(cwd);
     }
     catch {
-        return [];
+        return null;
     } // Explicit app targets also work outside a configured repository.
-    const config = await readOatConfig(repoRoot);
-    const root = config.documentation?.root?.trim();
-    return root && resolve(repoRoot, root) === appRoot
-        ? (config.documentation?.nonReaderPaths ?? [])
-        : [];
+    const documentation = (await readOatConfig(repoRoot)).documentation;
+    const configuredRoot = documentation?.root?.trim();
+    if (!configuredRoot)
+        return null;
+    return {
+        root: resolve(repoRoot, configuredRoot),
+        configuredRoot,
+        tooling: documentation?.tooling?.trim() || null,
+        navOwner: documentation?.navOwner,
+        nonReaderPaths: documentation?.nonReaderPaths ?? [],
+    };
+}
+/**
+ * Read-only comparison for `navOwner: hand-authored`: the same
+ * membership-and-order semantics as the `oat docs check` navigation rule,
+ * never strict generator output.
+ */
+export async function checkHandAuthoredNavigation(options) {
+    const docsRoot = join(options.appRoot, 'docs');
+    const framework = await detectDocsNavFramework(options.appRoot, options.configuredTooling);
+    if (framework === 'mkdocs')
+        return {
+            framework,
+            appRoot: options.appRoot,
+            docsRoot,
+            issues: await compareMkDocsMembership({
+                appRoot: options.appRoot,
+                docsRoot,
+                nonReaderPaths: options.nonReaderPaths,
+            }),
+            unlisted: [],
+        };
+    const generated = await syncFumadocsNavigation({
+        docsRoot,
+        check: true,
+        nonReaderPaths: options.nonReaderPaths,
+    });
+    return {
+        framework,
+        appRoot: options.appRoot,
+        docsRoot,
+        issues: await compareFumadocsMembership(docsRoot, generated.metaFiles),
+        unlisted: generated.unlisted,
+    };
 }
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
-    resolveConfiguredTooling,
-    resolveNonReaderPaths,
+    resolveConfiguredDocumentation,
     syncDocsNavigation,
+    checkHandAuthoredNavigation,
 };
 function replaceTopLevelYamlSection(source, key, replacement) {
     const lines = source.split(/\r?\n/);
@@ -135,7 +161,7 @@ export async function syncDocsNavigation(options) {
         stale: nextMkdocsSource === mkdocsSource ? [] : ['mkdocs.yml'],
     };
 }
-function reportFumadocsResult(context, targetDir, result) {
+function reportFumadocsResult(context, targetDir, result, warnings) {
     if (context.json) {
         context.logger.json({
             status: 'ok',
@@ -145,6 +171,7 @@ function reportFumadocsResult(context, targetDir, result) {
             metaFiles: result.metaFiles,
             written: result.written,
             unlisted: result.unlisted,
+            ...(warnings.length ? { warnings } : {}),
         });
         return;
     }
@@ -167,15 +194,18 @@ function reportFumadocsResult(context, targetDir, result) {
             context.logger.warn(`    ${path}`);
         }
     }
+    for (const warning of warnings)
+        context.logger.warn(warning);
 }
 /**
  * `--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.
+ * navigation file is missing or would change or, for Fumadocs, any page or
+ * folder is unlisted, since strict navigation hides it from the sidebar.
  */
-function reportCheckResult(context, targetDir, result) {
+function reportCheckResult(context, targetDir, result, missing, warnings) {
     const unlisted = result.framework === 'fumadocs' ? result.unlisted : [];
     const current = result.stale.length === 0 && unlisted.length === 0;
+    const differing = result.stale.filter((path) => !missing.includes(path));
     if (context.json) {
         context.logger.json({
             status: current ? 'ok' : 'drift',
@@ -184,20 +214,28 @@ function reportCheckResult(context, targetDir, result) {
             appRoot: result.appRoot,
             docsRoot: result.docsRoot,
             stale: result.stale,
+            missing,
             unlisted,
+            ...(warnings.length ? { warnings } : {}),
         });
         return current;
     }
+    for (const warning of warnings)
+        context.logger.warn(warning);
     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) {
+    if (missing.length > 0) {
+        context.logger.error(`  ${missing.length} generated file(s) are missing:`);
+        for (const path of missing)
+            context.logger.error(`    ${path}`);
+    }
+    if (differing.length > 0) {
+        context.logger.error(`  ${differing.length} generated file(s) differ from the index.md Contents maps:`);
+        for (const path of differing)
             context.logger.error(`    ${path}`);
-        }
     }
     if (unlisted.length > 0) {
         context.logger.error(`  ${unlisted.length} path(s) are not listed in any index.md Contents map ` +
@@ -205,26 +243,102 @@ function reportCheckResult(context, targetDir, result) {
         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}\`.`);
+    }
+    else {
+        context.logger.error(`  Run \`oat docs nav sync --target-dir ${targetDir}\` to regenerate the navigation.`);
+    }
+    return current;
+}
+function reportHandAuthoredCheck(context, targetDir, result) {
+    const current = result.issues.length === 0 && result.unlisted.length === 0;
+    if (context.json) {
+        context.logger.json({
+            status: current ? 'ok' : 'drift',
+            check: true,
+            navOwner: 'hand-authored',
+            framework: result.framework,
+            appRoot: result.appRoot,
+            docsRoot: result.docsRoot,
+            stale: [...new Set(result.issues.map((issue) => issue.path))].sort(),
+            missing: [],
+            unlisted: result.unlisted,
+            issues: result.issues,
+        });
+        return current;
+    }
+    if (current) {
+        context.logger.info(`Hand-authored docs navigation matches the index.md Contents maps in ${targetDir} (membership and order).`);
+        return current;
     }
-    context.logger.error(`  List every page in its directory's ## Contents, then run \`oat docs nav sync --target-dir ${targetDir}\`.`);
+    context.logger.error(`Hand-authored docs navigation differs from the index.md Contents maps in ${targetDir}:`);
+    for (const issue of result.issues)
+        context.logger.error(`  ${issue.path}${issue.line === undefined ? '' : `:${issue.line}`} ${issue.message}`);
+    if (result.unlisted.length > 0) {
+        context.logger.error(`  ${result.unlisted.length} path(s) are not listed in any index.md Contents map:`);
+        for (const path of result.unlisted)
+            context.logger.error(`    ${path}`);
+    }
+    context.logger.error('  Edit the hand-authored navigation or the Contents maps; nav sync does not regenerate hand-authored navigation.');
     return current;
 }
+const MARKDOWN_NOT_APPLICABLE = 'oat docs nav sync is not applicable to Markdown docs (documentation.tooling: markdown): the index.md Contents maps are the navigation and nothing is generated. Use oat docs check to validate them.';
 async function runDocsNavSyncCommand(context, options, dependencies) {
     try {
-        const targetDir = options.targetDir ?? '.';
+        const configured = await dependencies.resolveConfiguredDocumentation(context.cwd);
+        // Like `oat docs check`, an omitted target is the configured root.
+        const targetDir = options.targetDir ??
+            (configured ? relative(context.cwd, configured.root) || '.' : '.');
         const appRoot = resolve(context.cwd, targetDir);
-        const result = await dependencies.syncDocsNavigation({
+        // Compare filesystem identity so a symlinked alias of the configured
+        // app keeps its ownership and exclusions.
+        const canonical = async (path) => realpath(path).catch(() => resolve(path));
+        const documentation = configured &&
+            (await canonical(configured.root)) === (await canonical(appRoot))
+            ? configured
+            : null;
+        if (documentation?.tooling?.toLowerCase() === 'markdown')
+            throw new Error(MARKDOWN_NOT_APPLICABLE);
+        const navOwner = documentation?.navOwner;
+        const syncOptions = {
             appRoot,
-            configuredTooling: await dependencies.resolveConfiguredTooling(context.cwd, appRoot),
+            configuredTooling: documentation?.tooling ?? null,
             check: options.check === true,
-            nonReaderPaths: await dependencies.resolveNonReaderPaths?.(context.cwd, appRoot),
-        });
+            nonReaderPaths: documentation?.nonReaderPaths ?? [],
+        };
+        if (navOwner === 'hand-authored') {
+            if (!options.check)
+                throw new Error(`documentation.navOwner is hand-authored, so oat docs nav sync will not overwrite the navigation in ${targetDir}. ` +
+                    'Edit meta.json (Fumadocs) or the mkdocs.yml nav (MkDocs) directly and run oat docs check, ' +
+                    'or compare it with `oat docs nav sync --check`. To hand navigation to nav sync, first run ' +
+                    '`oat config set documentation.navOwner nav-sync`.');
+            const result = await dependencies.checkHandAuthoredNavigation(syncOptions);
+            process.exitCode = reportHandAuthoredCheck(context, targetDir, result)
+                ? 0
+                : 1;
+            return;
+        }
+        const warnings = navOwner === undefined
+            ? [
+                options.check
+                    ? `No documentation.navOwner is declared for ${targetDir}, so this check compares with strict nav sync output. Declare ownership with \`oat config set documentation.navOwner nav-sync\`, or \`hand-authored\` for a membership-and-order comparison.`
+                    : `No documentation.navOwner is declared for ${targetDir}, so nav sync regenerated the navigation as its owner. Declare ownership with \`oat config set documentation.navOwner nav-sync\`, or \`hand-authored\` to protect hand-written navigation from regeneration.`,
+            ]
+            : [];
+        const result = await dependencies.syncDocsNavigation(syncOptions);
         if (options.check) {
-            process.exitCode = reportCheckResult(context, targetDir, result) ? 0 : 1;
+            const missing = [];
+            if (result.framework === 'fumadocs')
+                for (const path of result.stale)
+                    if (!(await fileExists(join(result.docsRoot, path))))
+                        missing.push(path);
+            process.exitCode = reportCheckResult(context, targetDir, result, missing, warnings)
+                ? 0
+                : 1;
             return;
         }
         if (result.framework === 'fumadocs') {
-            reportFumadocsResult(context, targetDir, result);
+            reportFumadocsResult(context, targetDir, result, warnings);
         }
         else if (context.json) {
             context.logger.json({
@@ -233,12 +347,15 @@ async function runDocsNavSyncCommand(context, options, dependencies) {
                 docsRoot: result.docsRoot,
                 mkdocsPath: result.mkdocsPath,
                 nav: result.nav,
+                ...(warnings.length ? { warnings } : {}),
             });
         }
         else {
             context.logger.info(`Synced docs navigation in ${targetDir}`);
             context.logger.info(`  MkDocs config: ${result.mkdocsPath}`);
             context.logger.info(`  Docs root: ${result.docsRoot}`);
+            for (const warning of warnings)
+                context.logger.warn(warning);
         }
         process.exitCode = 0;
     }
@@ -260,8 +377,8 @@ export function createDocsNavSyncCommand(overrides = {}) {
     };
     return new Command('sync')
         .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'))
+        .addOption(new Option('--target-dir <path>', 'Docs app directory containing mkdocs.yml or source.config.ts (default: documentation.root, else the current directory)'))
+        .addOption(new Option('--check', 'Write nothing; exit 1 if any navigation file is missing or stale or any page is unlisted (hand-authored navigation: membership and order only)'))
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         await runDocsNavSyncCommand(context, options, dependencies);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.32",
+  "version": "0.3.34",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -42,8 +42,8 @@
     "unified": "11.0.5",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/docs-transforms": "0.3.32",
-    "@open-agent-toolkit/control-plane": "0.3.32"
+    "@open-agent-toolkit/control-plane": "0.3.34",
+    "@open-agent-toolkit/docs-transforms": "0.3.34"
   },
   "devDependencies": {
     "@types/jsdom": "28.0.3",