@open-agent-toolkit/cli 0.2.55 → 0.2.56

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

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

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAKjE,OAAO,KAAK,EAGV,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAmF3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACjE,0BAA0B,EAAE,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,YAAY,CAAC,OAAO,CAAC,CAAC;CAC5B;AAUD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAgOD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CAkDhC"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAKjE,OAAO,KAAK,EAEV,aAAa,EACb,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAmF3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACjE,0BAA0B,EAAE,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,YAAY,CAAC,OAAO,CAAC,CAAC;CAC5B;AAUD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAiMD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAexB;AAaD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CAkDhC"}

package/dist/commands/docs/init/scaffold.js

@@ -256,12 +256,21 @@ function renderTemplate(template, options, depContext, packageManagerField) {
     };
     return Object.entries(replacements).reduce((content, [token, value]) => content.replaceAll(token, value), template);
 }
-function buildDocumentationConfig(framework, targetDir) {
+/**
+ * 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 function buildDocumentationConfig(framework, targetDir) {
     if (framework === 'fumadocs') {
         return {
             root: targetDir,
             tooling: 'fumadocs',
-            index: join(targetDir, 'docs', 'index.md'),
+            index: join(targetDir, 'index.md'),
         };
     }
     return {

package/dist/config/oat-config.d.ts

@@ -6,6 +6,12 @@ export interface OatDocumentationConfig {
     config?: string;
     index?: string;
     requireForProjectCompletion?: boolean;
+    /**
+     * Globs, relative to the docs directory `oat docs generate-index` indexes,
+     * whose matches are left out of the generated index. Trimmed, de-duplicated,
+     * and order-preserving.
+     */
+    excludes?: string[];
 }
 export interface OatGitConfig {
     defaultBranch?: string;
@@ -203,6 +209,14 @@ export declare function normalizeProjectPath(repoRoot: string, pathValue: string
 export declare function resolveLocalPaths(config: OatConfig): string[];
 export declare function readOatConfig(repoRoot: string): Promise<OatConfig>;
 export declare function readOatConfigForDefaultScopeRepair(repoRoot: string): Promise<OatConfig>;
+/**
+ * Read shared config with an unusable `documentation.excludes` dropped, so
+ * `oat config set documentation.excludes ...` can perform the repair its own
+ * validation error prescribes. Mirrors the `projects.defaultScope` precedent
+ * above: without it, the only key-specific repair command the error names is
+ * itself blocked by the invalid value.
+ */
+export declare function readOatConfigForDocumentationExcludesRepair(repoRoot: string): Promise<OatConfig>;
 export declare function readOatLocalConfig(repoRoot: string): Promise<OatLocalConfig>;
 export declare function writeOatConfig(repoRoot: string, config: OatConfig): Promise<void>;
 export declare function writeOatLocalConfig(repoRoot: string, config: OatLocalConfig): Promise<void>;

package/dist/config/oat-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oat-config.d.ts","sourceRoot":"","sources":["../../src/config/oat-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oat-config.d.ts","sourceRoot":"","sources":["../../src/config/oat-config.ts"],"names":[],"mappings":"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"}

package/dist/config/oat-config.js

@@ -626,6 +626,38 @@ async function normalizeReadableProjectPath(repoRoot, pathValue) {
         return null;
     }
 }
+/**
+ * Parse `documentation.excludes` into a trimmed, de-duplicated,
+ * order-preserving list.
+ *
+ * Unlike its scalar `documentation.*` siblings, a malformed value is rejected
+ * rather than silently dropped: a typo in an exclusion list would otherwise
+ * publish pages the operator believed were excluded, with no signal anywhere.
+ * An absent key and an empty array are both "no exclusions".
+ */
+function normalizeDocumentationExcludes(value, configPath) {
+    if (value === undefined) {
+        return [];
+    }
+    const invalid = () => {
+        throw new CliError(`Invalid documentation.excludes in ${configPath}: expected an array of non-empty strings. ` +
+            'Repair it with oat config set documentation.excludes "<glob>,<glob>" (an empty value clears it).', 2);
+    };
+    if (!Array.isArray(value)) {
+        invalid();
+    }
+    const normalized = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string' || !entry.trim()) {
+            invalid();
+        }
+        const trimmedEntry = entry.trim();
+        if (!normalized.includes(trimmedEntry)) {
+            normalized.push(trimmedEntry);
+        }
+    }
+    return normalized;
+}
 function normalizeOatConfig(parsed, configPath = '.oat/config.json') {
     const next = { ...DEFAULT_OAT_CONFIG };
     if (!isRecord(parsed)) {
@@ -741,6 +773,10 @@ function normalizeOatConfig(parsed, configPath = '.oat/config.json') {
             doc.requireForProjectCompletion =
                 parsed.documentation.requireForProjectCompletion;
         }
+        const excludes = normalizeDocumentationExcludes(parsed.documentation.excludes, configPath);
+        if (excludes.length > 0) {
+            doc.excludes = excludes;
+        }
         if (Object.keys(doc).length > 0) {
             next.documentation = doc;
         }
@@ -828,6 +864,31 @@ export async function readOatConfigForDefaultScopeRepair(repoRoot) {
         throw error;
     }
 }
+/**
+ * Read shared config with an unusable `documentation.excludes` dropped, so
+ * `oat config set documentation.excludes ...` can perform the repair its own
+ * validation error prescribes. Mirrors the `projects.defaultScope` precedent
+ * above: without it, the only key-specific repair command the error names is
+ * itself blocked by the invalid value.
+ */
+export async function readOatConfigForDocumentationExcludesRepair(repoRoot) {
+    const configPath = getConfigPath(repoRoot);
+    try {
+        const raw = await readFile(configPath, 'utf8');
+        const parsed = parseJsonConfig(raw, configPath);
+        if (isRecord(parsed) && isRecord(parsed.documentation)) {
+            const { excludes: _invalidExcludes, ...documentation } = parsed.documentation;
+            return normalizeOatConfig({ ...parsed, documentation }, configPath);
+        }
+        return normalizeOatConfig(parsed, configPath);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return { ...DEFAULT_OAT_CONFIG };
+        }
+        throw error;
+    }
+}
 export async function readOatLocalConfig(repoRoot) {
     const configPath = getLocalConfigPath(repoRoot);
     try {