@open-agent-toolkit/cli 0.3.12 → 0.3.13

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

@@ -0,0 +1,317 @@
+import { lstat, open, realpath, readdir, readFile, stat, unlink, } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { createExclusionMatcher } from '../../docs/index-generate/generator.js';
+import { dirExists, ensureDir } from '../../../fs/io.js';
+import { normalizeToPosixPath, validatePathWithinScope } from '../../../fs/paths.js';
+import { parse as parseYaml } from 'yaml';
+import { humanizeAppName, } from './resolve-options.js';
+/** Validate a dedicated Markdown root, including existing symlink ancestors. */
+export async function validateMarkdownTarget(repoRoot, targetDir) {
+    const target = validatePathWithinScope(resolve(repoRoot, targetDir), repoRoot);
+    const relativeTarget = relative(resolve(repoRoot), target);
+    if (!relativeTarget)
+        throw new Error('Markdown docs require a dedicated directory; the repository root is unsafe.');
+    const canonicalRoot = await realpath(repoRoot);
+    let ancestor = target;
+    while (true) {
+        try {
+            await lstat(ancestor);
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                throw error;
+            ancestor = dirname(ancestor);
+        }
+    }
+    const canonicalAncestor = await realpath(ancestor);
+    const canonicalTarget = resolve(canonicalAncestor, relative(ancestor, target));
+    validatePathWithinScope(canonicalTarget, canonicalRoot);
+    if (canonicalTarget === canonicalRoot)
+        throw new Error('Markdown docs require a dedicated directory; target resolves to the repository root.');
+    if (ancestor === target &&
+        !(await lstat(target)).isDirectory() &&
+        !(await lstat(target)).isSymbolicLink()) {
+        throw new Error(`Markdown docs target must be a directory: ${target}`);
+    }
+    return normalizeToPosixPath(relativeTarget);
+}
+function renderMarkdownTemplate(template, options, contents) {
+    const replacements = {
+        "'{{TITLE_METADATA}}'": JSON.stringify(options.siteName),
+        "'{{DESCRIPTION_METADATA}}'": JSON.stringify(options.siteDescription),
+        '{{SITE_NAME}}': options.siteName,
+        '{{REPO_NAME}}': basename(options.repoRoot),
+        '{{CONTENTS}}': contents,
+        '{{LINT_MODE}}': options.lint,
+        '{{FORMAT_MODE}}': options.format,
+    };
+    return template.replace(/'\{\{(?:TITLE|DESCRIPTION)_METADATA\}\}'|\{\{[A-Z_]+\}\}/g, (token) => replacements[token] ?? token);
+}
+export class MarkdownDocsWriteError extends Error {
+    result;
+    constructor(message, result, cause) {
+        super(message, { cause });
+        this.result = result;
+    }
+}
+export function validateMarkdownConfig(repoRoot, targetDir, declared) {
+    if ((declared?.tooling &&
+        declared.tooling.trim().toLowerCase() !== 'markdown') ||
+        (declared?.root &&
+            resolve(repoRoot, declared.root) !== resolve(repoRoot, targetDir)) ||
+        (declared?.index &&
+            resolve(repoRoot, declared.index) !==
+                resolve(repoRoot, targetDir, 'index.md')) ||
+        declared?.config) {
+        throw new Error('Existing documentation config is incompatible with Markdown setup. Preserve it and choose adoption or framework replacement explicitly.');
+    }
+}
+function isMissing(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+async function readBaseline(repoRoot, path) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return null;
+        throw error;
+    }
+    // Existing symlinks are preserved, but may not point outside the repository.
+    validatePathWithinScope(await realpath(path), await realpath(repoRoot));
+    if (!(await stat(path)).isFile())
+        throw new Error(`Markdown baseline entrypoint must be a readable file: ${path}`);
+    return readFile(path, 'utf8');
+}
+function indexAdvice(content) {
+    const advice = [];
+    try {
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+        const metadata = frontmatter
+            ? parseYaml(frontmatter[1])
+            : null;
+        if (!metadata ||
+            typeof metadata.title !== 'string' ||
+            !metadata.title.trim() ||
+            typeof metadata.description !== 'string' ||
+            !metadata.description.trim()) {
+            advice.push('Existing index.md needs title/description metadata; it was preserved.');
+        }
+    }
+    catch {
+        advice.push('Existing index.md has malformed metadata; it was preserved.');
+    }
+    const contents = /^## Contents\s*\r?\n([\s\S]*?)(?=^## |$(?![\s\S]))/m.exec(content)?.[1];
+    if (!contents || !/\[[^\]]+\]\([^)]+\.md(?:#[^)]*)?\)/.test(contents)) {
+        advice.push('Existing index.md needs a populated Contents map; it was preserved.');
+    }
+    return advice;
+}
+function link(label, path) {
+    const safeLabel = label.replace(/[\r\n]/g, ' ').replace(/([[\]\\])/g, '\\$1');
+    const href = path
+        .split('/')
+        .map((segment) => encodeURIComponent(segment).replaceAll('(', '%28').replaceAll(')', '%29'))
+        .join('/');
+    return `- [${safeLabel}](${href})`;
+}
+async function buildContents(repoRoot, appRoot, excludes, advice) {
+    const matcher = createExclusionMatcher(excludes);
+    const entries = ((await dirExists(appRoot))
+        ? await readdir(appRoot, { withFileTypes: true })
+        : []).sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    const links = [];
+    async function hasMarkdown(directory, prefix) {
+        let children;
+        try {
+            children = await readdir(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                'code' in error &&
+                (error.code === 'EACCES' || error.code === 'EPERM')) {
+                advice.push(`${prefix}/ could not be inspected due to permissions; it was preserved. Run oat-docs-analyze for repair recommendations.`);
+                return false;
+            }
+            throw error;
+        }
+        for (const entry of children) {
+            const path = `${prefix}/${entry.name}`;
+            if (entry.isFile() &&
+                /\.md$/i.test(entry.name) &&
+                !['AGENTS.md', 'CLAUDE.md'].includes(entry.name) &&
+                !matcher.excludesFile(path))
+                return true;
+            if (entry.isDirectory() &&
+                !matcher.excludesDirectory(path) &&
+                (await hasMarkdown(join(directory, entry.name), path)))
+                return true;
+        }
+        return false;
+    }
+    for (const entry of entries) {
+        if (entry.isFile() &&
+            /\.md$/i.test(entry.name) &&
+            !['index.md', 'contributing.md', 'AGENTS.md', 'CLAUDE.md'].includes(entry.name) &&
+            !matcher.excludesFile(entry.name)) {
+            links.push(link(humanizeAppName(entry.name.replace(/\.md$/i, '')), entry.name));
+        }
+        else if (entry.isDirectory() && !matcher.excludesDirectory(entry.name)) {
+            const indexPath = `${entry.name}/index.md`;
+            if (matcher.excludesFile(indexPath))
+                continue;
+            let index;
+            try {
+                index = await readBaseline(repoRoot, join(appRoot, indexPath));
+            }
+            catch {
+                advice.push(`${indexPath} is not a usable in-repository file; it was preserved and omitted from Contents. Run oat-docs-analyze for repair recommendations.`);
+                continue;
+            }
+            if (index !== null) {
+                links.push(link(humanizeAppName(entry.name), indexPath));
+            }
+            else if (await hasMarkdown(join(appRoot, entry.name), entry.name)) {
+                advice.push(`${entry.name}/ has Markdown but no authored index.md; run oat-docs-analyze for repair recommendations.`);
+            }
+        }
+    }
+    if (!matcher.excludesFile('contributing.md'))
+        links.push(link('Contributing', 'contributing.md'));
+    return links.join('\n');
+}
+/** Read-only inspection used by both adoption and CLI dry-run. */
+export async function planMarkdownDocs(options) {
+    const targetDir = await validateMarkdownTarget(options.repoRoot, options.targetDir);
+    validateMarkdownConfig(options.repoRoot, targetDir, options.documentation);
+    const appRoot = resolve(options.repoRoot, targetDir);
+    if (!options.adopt &&
+        (await dirExists(appRoot)) &&
+        (await readdir(appRoot)).length > 0) {
+        throw new Error(`Markdown docs target is not empty: ${targetDir}. Use --adopt to preserve existing docs, then run oat-docs-analyze for content gaps.`);
+    }
+    const documentationConfig = {
+        ...options.documentation,
+        root: targetDir,
+        tooling: 'markdown',
+        index: `${targetDir}/index.md`,
+    };
+    const configChanged = options.documentation?.root !== targetDir ||
+        options.documentation?.tooling !== 'markdown' ||
+        options.documentation?.index !== `${targetDir}/index.md`;
+    const existing = new Map();
+    for (const name of ['index.md', 'contributing.md'])
+        existing.set(name, await readBaseline(options.repoRoot, join(appRoot, name)));
+    const auditAdvice = [];
+    const index = existing.get('index.md');
+    if (index !== null && index !== undefined)
+        auditAdvice.push(...indexAdvice(index));
+    const contents = index == null
+        ? await buildContents(options.repoRoot, appRoot, options.documentation?.excludes ?? [], auditAdvice)
+        : '';
+    if (options.adopt)
+        auditAdvice.push('Adoption preserves existing content. Run oat-docs-analyze to audit context, metadata, navigation, and local instructions; use oat-docs-apply for approved repairs.');
+    const files = [];
+    const preservedFiles = [];
+    for (const [name, content] of existing) {
+        if (content !== null) {
+            preservedFiles.push(name);
+            continue;
+        }
+        const template = await readFile(join(options.assetsRoot, 'templates', 'docs-markdown', name), 'utf8');
+        files.push({
+            name,
+            content: renderMarkdownTemplate(template, options, contents),
+        });
+    }
+    return {
+        repoRoot: options.repoRoot,
+        targetDir,
+        appRoot,
+        files,
+        preservedFiles,
+        auditAdvice,
+        documentationConfig,
+        configChanged,
+    };
+}
+/** Adds missing baseline files exclusively; config is persisted by the caller. */
+export async function applyMarkdownDocsPlan(plan) {
+    const result = {
+        appRoot: plan.appRoot,
+        createdFiles: [],
+        incompleteFiles: [],
+        preservedFiles: [...plan.preservedFiles],
+        auditAdvice: plan.auditAdvice,
+        documentationConfig: plan.documentationConfig,
+    };
+    try {
+        await validateMarkdownTarget(plan.repoRoot, plan.targetDir);
+        if (plan.files.length)
+            await ensureDir(plan.appRoot);
+        for (const { name, content } of plan.files) {
+            await validateMarkdownTarget(plan.repoRoot, plan.targetDir);
+            const path = join(plan.appRoot, name);
+            let handle;
+            try {
+                handle = await open(path, 'wx');
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    'code' in error &&
+                    error.code === 'EEXIST' &&
+                    (await readBaseline(plan.repoRoot, join(plan.appRoot, name))) !== null) {
+                    result.preservedFiles.push(name);
+                    continue;
+                }
+                else
+                    throw error;
+            }
+            let createdIdentity;
+            try {
+                createdIdentity = await handle.stat();
+                await handle.writeFile(content, 'utf8');
+                await handle.close();
+                result.createdFiles.push(name);
+            }
+            catch (error) {
+                try {
+                    await handle.close();
+                }
+                catch {
+                    // Preserve the original write/close error while attempting cleanup.
+                }
+                try {
+                    await validateMarkdownTarget(plan.repoRoot, plan.targetDir);
+                    const current = await lstat(path);
+                    if (!createdIdentity ||
+                        !current.isFile() ||
+                        current.dev !== createdIdentity.dev ||
+                        current.ino !== createdIdentity.ino) {
+                        throw new Error('Baseline file identity changed during creation.', {
+                            cause: error,
+                        });
+                    }
+                    await unlink(path);
+                }
+                catch (cleanupError) {
+                    if (!isMissing(cleanupError)) {
+                        result.incompleteFiles.push(name);
+                        result.auditAdvice.push(`${name} could not be safely cleaned up after a failed write; inspect or repair it before retrying. Adoption preserves existing files.`);
+                    }
+                }
+                throw error;
+            }
+        }
+        if ((await readBaseline(plan.repoRoot, join(plan.appRoot, 'index.md'))) ===
+            null)
+            throw new Error('Authored Markdown index is unavailable; configuration was not persisted.');
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new MarkdownDocsWriteError(message, result, error);
+    }
+}

package/dist/commands/docs/init/resolve-options.d.ts

@@ -1,7 +1,7 @@
 import type { PromptContext, SelectChoice } from '../../shared/shared.prompts.js';
 export type DocsRepoShape = 'monorepo' | 'single-package' | 'nested-standalone';
 export type DocsDetectedRepoShape = Exclude<DocsRepoShape, 'nested-standalone'>;
-export type DocsFramework = 'fumadocs' | 'mkdocs';
+export type DocsFramework = 'fumadocs' | 'mkdocs' | 'markdown';
 export type DocsLintMode = 'none' | 'markdownlint-cli2';
 export type DocsFormatMode = 'oxfmt' | 'none';
 export interface DocsInitResolvedOptions {
@@ -15,6 +15,7 @@ export interface DocsInitResolvedOptions {
     lint: DocsLintMode;
     format: DocsFormatMode;
     rootPatch: boolean;
+    adopt?: boolean;
 }
 export interface ResolveDocsInitOptionsInput {
     repoRoot: string;
@@ -22,6 +23,7 @@ export interface ResolveDocsInitOptionsInput {
     interactive: boolean;
     acceptDefaults: boolean;
     providedFramework?: DocsFramework;
+    providedAdopt?: boolean;
     providedAppName?: string;
     providedSiteName?: string;
     providedTargetDir?: string;

package/dist/commands/docs/init/resolve-options.d.ts.map

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

package/dist/commands/docs/init/resolve-options.js

@@ -3,6 +3,7 @@ import { dirExists, fileExists } from '../../../fs/io.js';
 const FRAMEWORK_CHOICES = [
     { label: 'Fumadocs (Next.js + MDX, static export)', value: 'fumadocs' },
     { label: 'MkDocs (Python, Material theme)', value: 'mkdocs' },
+    { label: 'Plain Markdown (authored pages, no site app)', value: 'markdown' },
 ];
 const LINT_CHOICES = [
     { label: 'none', value: 'none' },
@@ -62,6 +63,8 @@ export async function detectDocsRepoShape(repoRoot, dependencies) {
     return 'single-package';
 }
 export function getTemplateDir(framework) {
+    if (framework === 'markdown')
+        return 'docs-markdown';
     return framework === 'fumadocs' ? 'docs-app-fuma' : 'docs-app-mkdocs';
 }
 export function resolveEffectiveDocsShape(repoShape, framework, repoRoot, targetDir) {
@@ -88,6 +91,39 @@ export async function resolveDocsInitOptions(input) {
     if (!framework) {
         return null;
     }
+    if (framework === 'markdown') {
+        const defaultSiteName = humanizeAppName(basename(input.repoRoot)).trim() || 'Documentation';
+        const requestedSiteName = input.providedSiteName ??
+            (input.interactive && !input.acceptDefaults
+                ? await input.inputWithDefault('Documentation title', defaultSiteName, ctx)
+                : defaultSiteName);
+        if (requestedSiteName === null)
+            return null;
+        const siteName = requestedSiteName.trim()
+            ? requestedSiteName
+            : defaultSiteName;
+        const targetDir = input.providedTargetDir?.trim() ||
+            (input.interactive && !input.acceptDefaults
+                ? await input.inputWithDefault('Documentation directory', 'docs', ctx)
+                : 'docs');
+        if (!targetDir)
+            return null;
+        return {
+            repoRoot: input.repoRoot,
+            repoShape: input.repoShape,
+            framework,
+            appName: 'docs',
+            siteName,
+            targetDir,
+            siteDescription: input.providedSiteDescription?.trim()
+                ? input.providedSiteDescription
+                : `Documentation for ${basename(input.repoRoot).trim() || 'this repository'}.`,
+            lint: input.providedLint ?? 'none',
+            format: input.providedFormat ?? 'none',
+            rootPatch: false,
+            adopt: input.providedAdopt ?? false,
+        };
+    }
     const defaultAppName = getDefaultDocsAppName(input.repoRoot, input.repoShape);
     const appName = input.providedAppName?.trim() ||
         (input.interactive && !input.acceptDefaults

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,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"}
+{"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;AAMjE,OAAO,KAAK,EAEV,aAAa,EACb,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAsF3B,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,CAsBxB;AAaD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CAqDhC"}

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

@@ -3,6 +3,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, } from 'node:pa
 import { dirExists, ensureDir, fileExists } from '../../../fs/io.js';
 import { OAT_VERSION } from '../../../shared/oat-version.js';
 import { buildDocsCommands } from './docs-commands.js';
+import { applyMarkdownDocsPlan, planMarkdownDocs } from './markdown.js';
 import { getTemplateDir } from './resolve-options.js';
 const MKDOCS_TEMPLATE_FILES = [
     { source: '.gitignore', destination: '.gitignore' },
@@ -266,6 +267,13 @@ function renderTemplate(template, options, depContext, packageManagerField) {
  * pointing at the nav/config YAML, which is that framework's entry point.
  */
 export function buildDocumentationConfig(framework, targetDir) {
+    if (framework === 'markdown') {
+        return {
+            root: targetDir,
+            tooling: 'markdown',
+            index: join(targetDir, 'index.md'),
+        };
+    }
     if (framework === 'fumadocs') {
         return {
             root: targetDir,
@@ -290,6 +298,9 @@ async function ensureTargetWritable(appRoot) {
     }
 }
 export async function scaffoldDocsApp(options, overrides = {}) {
+    if (options.framework === 'markdown') {
+        return applyMarkdownDocsPlan(await planMarkdownDocs(options));
+    }
     const appRoot = join(options.repoRoot, options.targetDir);
     const templateDir = getTemplateDir(options.framework);
     const templateRoot = join(options.assetsRoot, 'templates', templateDir);

package/dist/commands/shared/agents-md.d.ts

@@ -61,6 +61,13 @@ export declare function formatAgentsMdGuidanceResult(result: UpsertSectionResult
  * hanging; it has no effect on regular-file writes.
  */
 export declare const AGENTS_MD_APPEND_FLAGS: number;
+/**
+ * Predict managed guidance actions from current bytes without writing. This
+ * advisory result does not establish write permission or guarantee a later
+ * upsert; mutation independently rechecks path identity and opened handles.
+ */
+export declare function previewAgentsMdSections(repoRoot: string, sections: readonly AgentsMdSectionInput[], options?: Pick<AgentsMdMutationOptions, 'fileSystem'>): Promise<Record<string, UpsertSectionResult>>;
+export declare function previewAgentsMdSection(repoRoot: string, key: string, body: string, options?: AgentsMdMutationOptions): Promise<UpsertSectionResult>;
 export declare function upsertAgentsMdSections(repoRoot: string, sections: readonly AgentsMdSectionInput[], options?: Pick<AgentsMdMutationOptions, 'fileSystem'>): Promise<Record<string, UpsertSectionResult>>;
 export declare function upsertAgentsMdSection(repoRoot: string, key: string, body: string, options?: AgentsMdMutationOptions): Promise<UpsertSectionResult>;
 export declare function removeAgentsMdSection(repoRoot: string, key: string, options?: Pick<AgentsMdMutationOptions, 'fileSystem'>): Promise<boolean | 'manual-required' | 'blocked'>;

package/dist/commands/shared/agents-md.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-md.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/agents-md.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,SAAS,EACV,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;GAQG;AAEH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,SAAS,EAAE,OAAO,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAmCD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,UAAU,GAAG,iBAAiB,CAAC;IAClD,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAC7E,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAcD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3E;AAySD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGpE;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,mBAAmB,GAC1B,SAAS,MAAM,EAAE,CAoBnB;AAmDD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAIb,CAAC;AA+RvB,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,oBAAoB,EAAE,EACzC,OAAO,GAAE,IAAI,CAAC,uBAAuB,EAAE,YAAY,CAAM,GACxD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAS9C;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,mBAAmB,CAAC,CAS9B;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,uBAAuB,EAAE,YAAY,CAAM,GACxD,OAAO,CAAC,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAAC,CAYlD"}
+{"version":3,"file":"agents-md.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/agents-md.ts"],"names":[],"mappings":"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"}