@open-agent-toolkit/cli 0.2.55 → 0.2.57

package/dist/commands/docs/index-generate/generator.js

@@ -1,5 +1,155 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+const NO_EXCLUSIONS = {
+    excludesFile: () => false,
+    excludesDirectory: () => false,
+};
+/**
+ * Match one path segment against one pattern segment, where `*` is the only
+ * metacharacter and never crosses `/`.
+ *
+ * This is the classic greedy two-pointer wildcard match, deliberately not a
+ * compiled regular expression: a pattern like `*a*a*a...` translates to
+ * nested-quantifier alternatives that backtrack exponentially, and exclusion
+ * patterns come from config and flags where a typo should not hang generation.
+ * Restarting from the last `*` instead bounds the work at O(pattern x text).
+ */
+function matchSegment(pattern, text) {
+    let patternIndex = 0;
+    let textIndex = 0;
+    let starPatternIndex = -1;
+    let starTextIndex = 0;
+    while (textIndex < text.length) {
+        if (pattern[patternIndex] === '*') {
+            // Collapse a run of stars: within a segment they are all equivalent.
+            while (pattern[patternIndex] === '*') {
+                patternIndex += 1;
+            }
+            if (patternIndex === pattern.length) {
+                return true;
+            }
+            starPatternIndex = patternIndex;
+            starTextIndex = textIndex;
+            continue;
+        }
+        if (patternIndex < pattern.length &&
+            pattern[patternIndex] === text[textIndex]) {
+            patternIndex += 1;
+            textIndex += 1;
+            continue;
+        }
+        if (starPatternIndex === -1) {
+            return false;
+        }
+        // Give the last star one more character and retry from just after it.
+        starTextIndex += 1;
+        patternIndex = starPatternIndex;
+        textIndex = starTextIndex;
+    }
+    while (pattern[patternIndex] === '*') {
+        patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
+}
+/**
+ * Match a docs-root-relative path against a pattern, segment by segment, where
+ * a whole-segment `**` spans zero or more path segments.
+ *
+ * Same greedy-restart shape as {@link matchSegment}, one level up, so a pattern
+ * full of `**` segments stays bounded too.
+ */
+function matchPath(patternSegments, pathSegments) {
+    let patternIndex = 0;
+    let pathIndex = 0;
+    let starPatternIndex = -1;
+    let starPathIndex = 0;
+    while (pathIndex < pathSegments.length) {
+        if (patternSegments[patternIndex] === '**') {
+            while (patternSegments[patternIndex] === '**') {
+                patternIndex += 1;
+            }
+            if (patternIndex === patternSegments.length) {
+                return true;
+            }
+            starPatternIndex = patternIndex;
+            starPathIndex = pathIndex;
+            continue;
+        }
+        if (patternIndex < patternSegments.length &&
+            matchSegment(patternSegments[patternIndex], pathSegments[pathIndex])) {
+            patternIndex += 1;
+            pathIndex += 1;
+            continue;
+        }
+        if (starPatternIndex === -1) {
+            return false;
+        }
+        starPathIndex += 1;
+        patternIndex = starPatternIndex;
+        pathIndex = starPathIndex;
+    }
+    while (patternSegments[patternIndex] === '**') {
+        patternIndex += 1;
+    }
+    return patternIndex === patternSegments.length;
+}
+/**
+ * Compile exclusion globs matched against **docs-root-relative POSIX paths**
+ * (`api/auth.md`, `api/nested`), never against absolute or CWD-relative ones.
+ *
+ * Grammar, defined once and documented in
+ * `apps/oat-docs/docs/reference/oat-directory-structure.md`:
+ *
+ * - `*` matches any run of characters inside a single path segment.
+ * - `**` spans `/` only as a whole segment, where it covers zero or more
+ *   segments: `**\/CLAUDE.md` matches `CLAUDE.md` and `api/CLAUDE.md`. Inside a
+ *   segment (`a**b`) it is an ordinary single-segment wildcard.
+ * - Patterns are anchored at both ends against the whole relative path, so a
+ *   bare `CLAUDE.md` matches only the root-level file. Use `**\/CLAUDE.md` for
+ *   every depth.
+ * - A trailing `/` restricts a pattern to directories: `drafts/` prunes the
+ *   `drafts` directory and everything beneath it, and never matches a file.
+ *   Without it, a pattern that matches a directory path prunes it too.
+ * - Matching is case-sensitive, `/` is the separator on every platform, and
+ *   `*` is the only metacharacter — `.`, `+`, and friends are literal.
+ *
+ * Entries are trimmed; a leading `./` or `/` is stripped so both spellings
+ * anchor at the docs root. Blank entries are ignored.
+ */
+export function createExclusionMatcher(patterns) {
+    const filePatterns = [];
+    const directoryPatterns = [];
+    for (const rawPattern of patterns) {
+        const trimmedPattern = rawPattern.trim();
+        if (!trimmedPattern) {
+            continue;
+        }
+        const directoryOnly = trimmedPattern.endsWith('/');
+        const normalized = trimmedPattern
+            .replace(/\/+$/, '')
+            .replace(/^\.\//, '')
+            .replace(/^\/+/, '');
+        if (!normalized) {
+            continue;
+        }
+        const segments = normalized.split('/');
+        directoryPatterns.push(segments);
+        if (!directoryOnly) {
+            filePatterns.push(segments);
+        }
+    }
+    if (directoryPatterns.length === 0) {
+        return NO_EXCLUSIONS;
+    }
+    const matches = (compiled, relativePath) => {
+        const pathSegments = relativePath.split('/');
+        return compiled.some((segments) => matchPath(segments, pathSegments));
+    };
+    return {
+        excludesFile: (relativePath) => matches(filePatterns, relativePath),
+        excludesDirectory: (relativePath) => matches(directoryPatterns, relativePath),
+    };
+}
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
 const HEADING_RE = /^#\s+(.+)$/m;
 function fileNameToTitle(fileName) {
@@ -60,15 +210,25 @@ function prefixEntryPath(entry, prefix) {
         children: entry.children?.map((child) => prefixEntryPath(child, prefix)),
     };
 }
-export async function generateIndex(docsDir) {
+/** Docs-root-relative POSIX path used for matching, never for reading files. */
+function relativeKey(base, name) {
+    return base ? `${base}/${name}` : name;
+}
+async function collectEntries(docsDir, relativeBase, matcher) {
     const entries = [];
     const subdirs = [];
     const dirEntries = await readdir(docsDir, { withFileTypes: true });
     for (const entry of dirEntries) {
+        const relativePath = relativeKey(relativeBase, entry.name);
         if (entry.isDirectory()) {
-            subdirs.push(entry.name);
+            if (!matcher.excludesDirectory(relativePath)) {
+                subdirs.push(entry.name);
+            }
         }
         else if (entry.isFile() && entry.name.endsWith('.md')) {
+            if (matcher.excludesFile(relativePath)) {
+                continue;
+            }
             const filePath = join(docsDir, entry.name);
             const content = await readFile(filePath, 'utf8');
             const { title, description } = resolveTitle(content, entry.name);
@@ -80,7 +240,10 @@ export async function generateIndex(docsDir) {
         }
     }
     for (const subdir of subdirs.sort()) {
-        const children = await generateIndex(join(docsDir, subdir));
+        const children = await collectEntries(join(docsDir, subdir), relativeKey(relativeBase, subdir), matcher);
+        // A directory with no surviving children emits no heading. This already
+        // pruned genuinely empty directories; exclusion simply empties more of
+        // them, and it composes upward through the recursion.
         if (children.length > 0) {
             entries.push({
                 title: fileNameToTitle(subdir),
@@ -91,6 +254,9 @@ export async function generateIndex(docsDir) {
     }
     return sortEntries(entries);
 }
+export async function generateIndex(docsDir, options = {}) {
+    return collectEntries(docsDir, '', createExclusionMatcher(options.excludes ?? []));
+}
 function renderEntries(entries, indent) {
     const lines = [];
     const prefix = '  '.repeat(indent);

package/dist/commands/docs/index-generate/index.d.ts

@@ -1,13 +1,18 @@
 import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
+import { type OatConfig } from '../../../config/oat-config.js';
 import { Command } from 'commander';
 export declare const GENERATED_INDEX_WARNING = "<!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->";
 interface IndexGenerateFileDependencies {
-    generateIndex: (docsDir: string) => Promise<import('./generator.js').IndexEntry[]>;
+    generateIndex: (docsDir: string, options: import('./generator.js').GenerateIndexOptions) => Promise<import('./generator.js').IndexEntry[]>;
     renderIndex: (entries: import('./generator.js').IndexEntry[]) => string;
     writeFile: (path: string, content: string, encoding: BufferEncoding) => Promise<void>;
-    readOatConfig: (repoRoot: string) => Promise<import('../../../config/oat-config.js').OatConfig>;
-    writeOatConfig: (repoRoot: string, config: import('../../../config/oat-config.js').OatConfig) => Promise<void>;
+    readOatConfig: (repoRoot: string) => Promise<OatConfig>;
+    writeOatConfig: (repoRoot: string, config: OatConfig) => Promise<void>;
     resolveRepoRoot: (cwd: string) => Promise<string>;
+    dirExists: (path: string) => Promise<boolean>;
+    readFileIfPresent: (path: string) => Promise<string | null>;
+    realpath: (path: string) => Promise<string>;
+    readLinkIfSymlink: (path: string) => Promise<string | null>;
 }
 interface IndexGenerateDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;

package/dist/commands/docs/index-generate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAOjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAqFD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAuBjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,aAAa,EAAE,oBAAoB,KAChD,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAggBD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAgCT"}

package/dist/commands/docs/index-generate/index.js

@@ -1,12 +1,48 @@
-import { writeFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { readFile, readlink, realpath, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
-import { readOatConfig, writeOatConfig } from '../../../config/oat-config.js';
-import { resolveProjectRoot } from '../../../fs/paths.js';
+import { readOatConfig, writeOatConfig, } from '../../../config/oat-config.js';
+import { CliError } from '../../../errors/cli-error.js';
+import { dirExists } from '../../../fs/io.js';
+import { normalizeToPosixPath, resolveProjectRoot } from '../../../fs/paths.js';
 import { Command, Option } from 'commander';
 import { generateIndex, renderIndex } from './generator.js';
 export const GENERATED_INDEX_WARNING = '<!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->';
+const YAML_EXTENSIONS = ['.yml', '.yaml'];
+/**
+ * Exit codes, per the `packages/cli/AGENTS.md` taxonomy.
+ *
+ * A refused output target is an actionable user error: the operator passed a
+ * path the command will not write to, and the message names what to pass
+ * instead. Unusable path *configuration* keeps the exit code the external plan
+ * mandates in its step 1, matching the `oat-config.ts` precedent for an invalid
+ * repository config value paired with a repair command.
+ */
+const REFUSAL_EXIT_CODE = 1;
+const CONFIGURATION_EXIT_CODE = 2;
+async function readFileIfPresent(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            return null;
+        }
+        throw error;
+    }
+}
+/** The link destination when `path` is a symlink (dangling or not), else null. */
+async function readLinkIfSymlink(path) {
+    try {
+        return await readlink(path);
+    }
+    catch {
+        // EINVAL (not a symlink) and ENOENT (absent) are both "nothing to follow".
+        return null;
+    }
+}
 const DEFAULT_FILE_DEPS = {
     generateIndex,
     renderIndex,
@@ -14,6 +50,10 @@ const DEFAULT_FILE_DEPS = {
     readOatConfig,
     writeOatConfig,
     resolveRepoRoot: resolveProjectRoot,
+    dirExists,
+    readFileIfPresent,
+    realpath,
+    readLinkIfSymlink,
 };
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -25,35 +65,310 @@ function buildGeneratedIndexOutput(content) {
     }
     return `${GENERATED_INDEX_WARNING}\n\n${content}`;
 }
+/**
+ * True when the relative path escapes its base. A bare `startsWith('..')` test
+ * is wrong: it also matches ordinary children such as `..draft/page.md`, which
+ * would let a target inside the indexed tree pass the safety checks.
+ */
+function escapesBase(relativePath) {
+    return (isAbsolute(relativePath) ||
+        relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`));
+}
+/**
+ * True when `candidate` is `parent` itself or lives underneath it. Used for the
+ * output-safety checks, so an exact match must count as "inside".
+ */
+function isAtOrInside(parent, candidate) {
+    const relativePath = relative(parent, candidate);
+    return relativePath === '' || !escapesBase(relativePath);
+}
+/** True when `candidate` lives strictly underneath `parent`. */
+function isInside(parent, candidate) {
+    const relativePath = relative(parent, candidate);
+    return relativePath !== '' && !escapesBase(relativePath);
+}
+/**
+ * Maximum symlink hops followed while canonicalizing, mirroring the kernel's
+ * own bound. `realpath` handles resolvable chains; this only bounds the
+ * dangling-link hops resolved below.
+ */
+const MAX_SYMLINK_HOPS = 32;
+/**
+ * Absolute path with symlinks resolved, so a symlinked parent cannot smuggle a
+ * write into a protected tree past the lexical containment checks.
+ *
+ * Output paths usually do not exist yet, so `realpath` fails and the nearest
+ * existing ancestor is resolved instead. A *dangling* symlink also fails
+ * `realpath`, yet `writeFile` still follows it, so read its destination
+ * explicitly. Components are resolved parent-first, in filesystem order, so a
+ * relative link destination is joined to the parent's *real* location rather
+ * than its lexical spelling.
+ */
+async function canonicalize(target, deps, linkHops = 0) {
+    const absolute = resolve(target);
+    try {
+        return await deps.realpath(absolute);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+            throw error;
+        }
+    }
+    const parent = dirname(absolute);
+    if (parent === absolute) {
+        return absolute;
+    }
+    const canonicalParent = await canonicalize(parent, deps, linkHops);
+    const candidate = join(canonicalParent, basename(absolute));
+    const linkTarget = await deps.readLinkIfSymlink(candidate);
+    if (linkTarget === null) {
+        return candidate;
+    }
+    if (linkHops >= MAX_SYMLINK_HOPS) {
+        // Fail closed: falling through would hand the writer an unresolved link.
+        throw new CliError(`Refusing to resolve ${target}: its symlink chain exceeds ${MAX_SYMLINK_HOPS} hops. ` +
+            'Pass --output with a path that is not a deep symlink chain.', REFUSAL_EXIT_CODE);
+    }
+    return canonicalize(resolve(canonicalParent, linkTarget), deps, linkHops + 1);
+}
+function trimmed(value) {
+    const trimmedValue = value?.trim();
+    return trimmedValue ? trimmedValue : null;
+}
+/** Commander collector for the repeatable `--exclude` flag. */
+function collectExclude(value, previous) {
+    return [...(previous ?? []), value];
+}
+/**
+ * The exclusion list handed to the generator: `documentation.excludes` first,
+ * then the `--exclude` flags.
+ *
+ * Flags **extend** the configured defaults rather than replacing them, so a
+ * one-off exclusion on the command line cannot silently republish the pages a
+ * repository deliberately excluded. Entries are trimmed, blanks are dropped,
+ * and duplicates collapse while preserving first-seen order.
+ */
+function resolveExcludes(config, flagValues) {
+    const merged = [];
+    for (const value of [
+        ...(config.documentation?.excludes ?? []),
+        ...(flagValues ?? []),
+    ]) {
+        const entry = value.trim();
+        if (entry && !merged.includes(entry)) {
+            merged.push(entry);
+        }
+    }
+    return merged;
+}
+function missingRootError(flag) {
+    return new CliError(`Cannot resolve ${flag === '--docs-dir' ? 'the docs directory' : 'the output path'}: ` +
+        '`documentation.root` is not set in .oat/config.json. ' +
+        'Set it with `oat config set documentation.root <path>` (or run `oat docs init`), ' +
+        `or pass ${flag} <path> explicitly.`, CONFIGURATION_EXIT_CODE);
+}
+/**
+ * Resolve the docs directory and output path.
+ *
+ * Omitted options come from repository configuration; explicitly supplied
+ * options stay CWD-relative for backward compatibility. `documentation.root`
+ * canonically names the docs **app root** written by `oat docs init`. The
+ * `<root>/docs` preference is compatibility behavior for legacy configs whose
+ * `root` names a docs *source* directory; `--docs-dir` overrides it.
+ */
+async function resolveIndexGeneratePaths(context, options, deps) {
+    const repoRoot = await deps.resolveRepoRoot(context.cwd);
+    const config = await deps.readOatConfig(repoRoot);
+    const configuredRootValue = trimmed(config.documentation?.root);
+    const configuredRoot = configuredRootValue
+        ? resolve(repoRoot, configuredRootValue)
+        : null;
+    // Either omitted option needs a usable configured root, so validate it once
+    // up front rather than only on the path that happens to be derived first.
+    if (options.docsDir === undefined || options.output === undefined) {
+        if (!configuredRoot) {
+            throw missingRootError(options.docsDir === undefined ? '--docs-dir' : '--output');
+        }
+        if (!(await deps.dirExists(configuredRoot))) {
+            // Fail with the config-repair path rather than letting the generator or
+            // the writer surface a raw ENOENT under the generic exit code.
+            throw new CliError(`Cannot resolve documentation paths: \`documentation.root\` is set to "${configuredRootValue}" ` +
+                `in .oat/config.json, but ${configuredRoot} is not a directory. ` +
+                'Repair it with `oat config set documentation.root <path>`, or pass --docs-dir and --output explicitly.', CONFIGURATION_EXIT_CODE);
+        }
+    }
+    let docsDir;
+    let docsDirSource;
+    if (options.docsDir !== undefined) {
+        docsDir = resolve(context.cwd, options.docsDir);
+        docsDirSource = 'flag';
+    }
+    else if (await deps.dirExists(join(configuredRoot, 'docs'))) {
+        docsDir = join(configuredRoot, 'docs');
+        docsDirSource = 'config-docs-subdirectory';
+    }
+    else {
+        docsDir = configuredRoot;
+        docsDirSource = 'config-root';
+    }
+    const outputIsExplicit = options.output !== undefined;
+    const outputPath = outputIsExplicit
+        ? resolve(context.cwd, options.output)
+        : join(configuredRoot, 'index.md');
+    return {
+        repoRoot,
+        config,
+        configuredRoot,
+        docsDir,
+        docsDirSource,
+        outputPath,
+        outputIsExplicit,
+        excludes: resolveExcludes(config, options.exclude),
+    };
+}
+/** `canonicalize`, but an unresolvable path yields null instead of throwing. */
+async function canonicalizeOrNull(target, deps) {
+    try {
+        return await canonicalize(target, deps);
+    }
+    catch {
+        return null;
+    }
+}
+async function canonicalizeIndexGeneratePaths(resolved, deps) {
+    const documentationConfigValue = trimmed(resolved.config.documentation?.config);
+    const lexicalDocumentationConfig = documentationConfigValue
+        ? resolve(resolved.repoRoot, documentationConfigValue)
+        : null;
+    return {
+        docsDir: await canonicalize(resolved.docsDir, deps),
+        outputPath: await canonicalize(resolved.outputPath, deps),
+        // An unusable configured root only makes the config write ineligible; it
+        // must not fail a run whose paths were both supplied explicitly.
+        configuredRoot: resolved.configuredRoot
+            ? await canonicalizeOrNull(resolved.configuredRoot, deps)
+            : null,
+        lexicalDocumentationConfig,
+        // Falling back to the lexical path keeps the refusal guard intact when the
+        // configured tool config cannot be canonicalized.
+        documentationConfig: lexicalDocumentationConfig
+            ? ((await canonicalizeOrNull(lexicalDocumentationConfig, deps)) ??
+                lexicalDocumentationConfig)
+            : null,
+    };
+}
+/**
+ * Reject unsafe output targets before anything is generated or written. Applies
+ * to derived and explicit paths alike, and compares canonical paths so a
+ * symlinked target cannot slip past. Messages name the operator-supplied path.
+ */
+async function assertOutputIsSafe(resolved, canonical, deps) {
+    const { docsDir, outputPath, outputIsExplicit } = resolved;
+    if (isAtOrInside(canonical.docsDir, canonical.outputPath)) {
+        throw new CliError(`Refusing to write the generated index inside the docs directory it indexes: ` +
+            `${outputPath} is inside ${docsDir}. Pass --output with a path outside the docs directory.`, REFUSAL_EXIT_CODE);
+    }
+    const configuredConfigPaths = new Set([
+        canonical.documentationConfig,
+        canonical.lexicalDocumentationConfig,
+    ].filter((value) => value !== null));
+    if (configuredConfigPaths.has(canonical.outputPath) ||
+        configuredConfigPaths.has(outputPath)) {
+        throw new CliError(`Refusing to overwrite the documentation tool config at ${outputPath} ` +
+            '(`documentation.config` in .oat/config.json). Pass --output with a different path.', REFUSAL_EXIT_CODE);
+    }
+    const yamlCandidates = [
+        outputPath.toLowerCase(),
+        canonical.outputPath.toLowerCase(),
+    ];
+    if (YAML_EXTENSIONS.some((extension) => yamlCandidates.some((candidate) => candidate.endsWith(extension)))) {
+        throw new CliError(`Refusing to write the generated Markdown index to a YAML file: ${outputPath}. ` +
+            'Pass --output with a Markdown path.', REFUSAL_EXIT_CODE);
+    }
+    if (outputIsExplicit) {
+        return;
+    }
+    const existing = await deps.readFileIfPresent(outputPath);
+    if (existing !== null && !existing.includes(GENERATED_INDEX_WARNING)) {
+        throw new CliError(`Refusing to overwrite ${outputPath}: the file exists and is not a generated index ` +
+            '(it has no `oat docs generate-index` AUTOGENERATED header). ' +
+            'Move or delete it, or pass --output to name it explicitly.', REFUSAL_EXIT_CODE);
+    }
+}
+/**
+ * The only configuration write this command performs: the Fumadocs bootstrap
+ * transition that records the generated app-root manifest in
+ * `documentation.index`. MkDocs (and any other declared tooling) never writes.
+ */
+function isFumadocsManifestTransition(resolved, canonical) {
+    const { config } = resolved;
+    if (!canonical.configuredRoot ||
+        !isInside(canonical.configuredRoot, canonical.outputPath)) {
+        return false;
+    }
+    const tooling = trimmed(config.documentation?.tooling)?.toLowerCase();
+    if (tooling) {
+        return tooling === 'fumadocs';
+    }
+    return trimmed(config.documentation?.config) === null;
+}
+/**
+ * The repo-relative value recorded in `documentation.index`.
+ *
+ * Eligibility is decided on canonical paths, so an operator who supplied an
+ * aliased spelling of the output (`/private/tmp/...` for `/tmp/...`) would
+ * otherwise persist a machine-specific path into tracked config. Take the
+ * canonical suffix inside the configured root and rebase it onto that root's
+ * configured spelling, which is repo-relative by construction.
+ */
+function buildDocumentationIndexValue(resolved, canonical) {
+    const suffix = relative(canonical.configuredRoot, canonical.outputPath);
+    const portableOutput = join(resolved.configuredRoot, suffix);
+    const relativeOutput = relative(resolved.repoRoot, portableOutput);
+    // An empty relative path means the output *is* the repository root directory,
+    // which is never written. A `documentation.root` outside the repository would
+    // persist an absolute or `../` path. Withhold the key in both cases rather
+    // than record a value pointing at a file this run did not produce.
+    if (!relativeOutput || escapesBase(relativeOutput)) {
+        return null;
+    }
+    return normalizeToPosixPath(relativeOutput);
+}
 async function runIndexGenerate(context, options, deps) {
-    const docsDir = join(context.cwd, options.docsDir);
-    const outputPath = options.output
-        ? join(context.cwd, options.output)
-        : join(context.cwd, 'index.md');
-    const entries = await deps.generateIndex(docsDir);
+    const resolved = await resolveIndexGeneratePaths(context, options, deps);
+    const canonical = await canonicalizeIndexGeneratePaths(resolved, deps);
+    await assertOutputIsSafe(resolved, canonical, deps);
+    const { config, docsDir, outputPath, repoRoot } = resolved;
+    const entries = await deps.generateIndex(docsDir, {
+        excludes: resolved.excludes,
+    });
     const content = buildGeneratedIndexOutput(deps.renderIndex(entries));
     await deps.writeFile(outputPath, content, 'utf8');
-    const repoRoot = await deps.resolveRepoRoot(context.cwd);
-    const config = await deps.readOatConfig(repoRoot);
-    const indexPath = relative(repoRoot, outputPath) || 'index.md';
-    if (config.documentation?.index !== indexPath) {
-        await deps.writeOatConfig(repoRoot, {
-            ...config,
-            documentation: {
-                ...config.documentation,
-                index: indexPath,
-            },
-        });
+    if (isFumadocsManifestTransition(resolved, canonical)) {
+        const indexPath = buildDocumentationIndexValue(resolved, canonical);
+        if (indexPath !== null && config.documentation?.index !== indexPath) {
+            await deps.writeOatConfig(repoRoot, {
+                ...config,
+                documentation: {
+                    ...config.documentation,
+                    index: indexPath,
+                },
+            });
+        }
     }
     if (context.json) {
         context.logger.json({
             status: 'ok',
             entriesGenerated: entries.length,
+            docsDir,
+            docsDirSource: resolved.docsDirSource,
             outputPath,
         });
         return;
     }
-    context.logger.info(`Generated index with ${entries.length} entries → ${outputPath}`);
+    context.logger.info(`Generated index with ${entries.length} entries from ${docsDir} → ${outputPath}`);
 }
 async function runIndexGenerateCommand(context, options, dependencies) {
     try {
@@ -68,7 +383,7 @@ async function runIndexGenerateCommand(context, options, dependencies) {
         else {
             context.logger.error(message);
         }
-        process.exitCode = 1;
+        process.exitCode = error instanceof CliError ? error.exitCode : 1;
     }
 }
 export function createDocsGenerateIndexCommand(overrides = {}) {
@@ -78,8 +393,9 @@ export function createDocsGenerateIndexCommand(overrides = {}) {
     };
     return new Command('generate-index')
         .description('Generate a docs index from markdown files')
-        .addOption(new Option('--docs-dir <path>', 'Documentation source directory').default('docs'))
-        .addOption(new Option('--output <path>', 'Output file path (default: index.md)'))
+        .addOption(new Option('--docs-dir <path>', 'Documentation source directory, resolved from the CWD (default: `<documentation.root>/docs` when that directory exists, otherwise `<documentation.root>`)'))
+        .addOption(new Option('--output <path>', 'Output file path, resolved from the CWD (default: `<documentation.root>/index.md`)'))
+        .addOption(new Option('--exclude <glob>', 'Exclude matching paths, relative to the docs directory (`*` within a segment, `**` across segments, trailing `/` for directories only). Repeatable, and additive to `documentation.excludes`').argParser(collectExclude))
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         await runIndexGenerateCommand(context, options, dependencies);

package/dist/commands/docs/init/scaffold.d.ts

@@ -1,5 +1,5 @@
 import type { OatDocumentationConfig } from '../../../config/oat-config.js';
-import type { DocsInitResolvedOptions } from './resolve-options.js';
+import type { DocsFramework, DocsInitResolvedOptions } from './resolve-options.js';
 export interface ScaffoldDocsAppOptions extends DocsInitResolvedOptions {
     assetsRoot: string;
 }
@@ -21,6 +21,16 @@ export interface ScaffoldDocsAppDependencies {
 export declare const PNPM_FALLBACK = "10.13.1";
 export declare function detectIsOatRepo(repoRoot: string): Promise<boolean>;
 export declare function resolveOatDepContext(repoRoot: string, assetsRoot: string): Promise<OatDepContext>;
+/**
+ * Seed `documentation.*` for a freshly scaffolded app.
+ *
+ * For Fumadocs, `index` names the generated app-root manifest that
+ * `oat docs generate-index` writes (`<root>/index.md`), not the authored source
+ * page at `<root>/docs/index.md`: the scaffold must be correct before the first
+ * build rather than depending on a later config mutation. The MkDocs seed keeps
+ * pointing at the nav/config YAML, which is that framework's entry point.
+ */
+export declare function buildDocumentationConfig(framework: DocsFramework, targetDir: string): OatDocumentationConfig;
 export declare function scaffoldDocsApp(options: ScaffoldDocsAppOptions, overrides?: Partial<ScaffoldDocsAppDependencies>): Promise<ScaffoldDocsAppResult>;
 export {};
 //# sourceMappingURL=scaffold.d.ts.map