@open-agent-toolkit/cli 0.3.12 → 0.3.13

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

@@ -1,12 +1,13 @@
 import { join } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
-import { formatAgentsMdGuidanceResult, formatAgentsMdMutationFailure, upsertAgentsMdSection, } from '../../shared/agents-md.js';
+import { formatAgentsMdGuidanceResult, formatAgentsMdMutationFailure, previewAgentsMdSection, upsertAgentsMdSection, } from '../../shared/agents-md.js';
 import { confirmAction, inputWithDefault, selectWithAbort, } from '../../shared/shared.prompts.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { readOatConfig, writeOatConfig, } from '../../../config/oat-config.js';
 import { resolveAssetsRoot } from '../../../fs/assets.js';
 import { Command, Option } from 'commander';
 import { buildDocsCommands } from './docs-commands.js';
+import { applyMarkdownDocsPlan, MarkdownDocsWriteError, planMarkdownDocs, validateMarkdownConfig, validateMarkdownTarget, } from './markdown.js';
 import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, getDefaultDocsAppName, resolveDocsInitOptions, } from './resolve-options.js';
 import { patchRootPackageJson, } from './root-package.js';
 import { scaffoldDocsApp } from './scaffold.js';
@@ -52,6 +53,84 @@ const DEFAULT_DEPENDENCIES = {
     inputWithDefault,
     selectWithAbort,
     runDocsInit: async (context, options, assetsRoot) => {
+        if (options.framework === 'markdown') {
+            const config = await readOatConfig(context.cwd);
+            const plan = await planMarkdownDocs({
+                ...options,
+                assetsRoot,
+                documentation: config.documentation,
+            });
+            const report = {
+                appRoot: plan.appRoot,
+                createdFiles: [],
+                preservedFiles: plan.preservedFiles,
+                auditAdvice: plan.auditAdvice,
+                changes: {
+                    files: plan.files.map(({ name }) => name),
+                    config: plan.configChanged,
+                },
+                configStatus: plan.configChanged ? 'planned' : 'no-change',
+            };
+            if (context.dryRun) {
+                return {
+                    ...report,
+                    dryRun: true,
+                    plannedFiles: plan.files.map(({ name }) => name),
+                };
+            }
+            try {
+                const result = await applyMarkdownDocsPlan(plan);
+                report.createdFiles = result.createdFiles;
+                report.preservedFiles = result.preservedFiles;
+            }
+            catch (error) {
+                if (!(error instanceof MarkdownDocsWriteError))
+                    throw error;
+                return {
+                    ...report,
+                    ...error.result,
+                    configStatus: 'not-attempted',
+                    changes: { files: error.result.createdFiles, config: false },
+                    failure: { stage: 'scaffold', message: error.message },
+                };
+            }
+            if (plan.configChanged) {
+                try {
+                    // Re-read after scaffolding so unrelated concurrent config edits survive.
+                    const latest = await readOatConfig(context.cwd);
+                    validateMarkdownConfig(context.cwd, plan.targetDir, latest.documentation);
+                    latest.documentation = {
+                        ...latest.documentation,
+                        root: plan.targetDir,
+                        tooling: 'markdown',
+                        index: `${plan.targetDir}/index.md`,
+                    };
+                    await writeOatConfig(context.cwd, latest);
+                    report.configStatus = 'updated';
+                }
+                catch (error) {
+                    return {
+                        ...report,
+                        configStatus: 'failed',
+                        changes: { files: report.createdFiles, config: false },
+                        failure: {
+                            stage: 'config',
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    };
+                }
+            }
+            report.changes = {
+                files: report.createdFiles,
+                config: report.configStatus === 'updated',
+            };
+            if (!context.json) {
+                context.logger.info(`Markdown docs at ${plan.targetDir}: ${report.createdFiles.length} baseline file(s) created, ${report.preservedFiles?.length ?? 0} preserved.`);
+                for (const advice of plan.auditAdvice)
+                    context.logger.info(advice);
+            }
+            return report;
+        }
         const result = await scaffoldDocsApp({
             assetsRoot,
             ...options,
@@ -75,7 +154,8 @@ const DEFAULT_DEPENDENCIES = {
             context.logger.info(`  App name: ${options.appName}`);
             context.logger.info(`  Lint: ${options.lint}`);
             context.logger.info(`  Format: ${options.format}`);
-            logRootPackagePatch(context, rootPackagePatch);
+            if (rootPackagePatch)
+                logRootPackagePatch(context, rootPackagePatch);
         }
         return {
             createdFiles: result.createdFiles,
@@ -84,12 +164,14 @@ const DEFAULT_DEPENDENCIES = {
         };
     },
     upsertAgentsMdSection,
+    previewAgentsMdSection,
     readOatConfig,
     confirmAction,
 };
 const FRAMEWORK_LABELS = {
     fumadocs: 'Fumadocs (Next.js + MDX)',
     mkdocs: 'MkDocs (Python)',
+    markdown: 'Markdown',
 };
 /**
  * The AGENTS.md `## Documentation` section for a freshly scaffolded app.
@@ -103,6 +185,19 @@ const FRAMEWORK_LABELS = {
  * `documentation.index` is the nav YAML the Config bullet already names.
  */
 export function buildDocsSectionBody(options) {
+    if (options.framework === 'markdown') {
+        return [
+            '## Documentation',
+            '',
+            `- **Docs root:** \`${options.targetDir}\``,
+            '- **Tooling:** Markdown',
+            `- **Authored index:** \`${options.targetDir}/index.md\``,
+            `- **Contributing:** \`${options.targetDir}/contributing.md\``,
+            '',
+            'Keep authored context, title/description metadata, and Contents maps with relative Markdown links current. Preserve local instructions; asset-only directories are exempt from indexes.',
+            'Use `oat-docs-analyze` to audit gaps and `oat-docs-apply` for approved repairs. Optional generated inventories belong outside the content tree and do not replace the authored index.',
+        ].join('\n');
+    }
     const lines = [
         '## Documentation',
         '',
@@ -130,6 +225,7 @@ async function runDocsInitCommand(context, options, dependencies) {
             interactive: context.interactive,
             acceptDefaults: options.yes ?? false,
             providedFramework: options.framework,
+            providedAdopt: options.adopt,
             providedAppName: options.appName,
             providedSiteName: options.siteName,
             providedTargetDir: options.targetDir,
@@ -147,8 +243,25 @@ async function runDocsInitCommand(context, options, dependencies) {
             process.exitCode = 0;
             return;
         }
+        if (context.dryRun && resolved.framework !== 'markdown') {
+            throw new Error('--dry-run applies only to --framework markdown.');
+        }
+        if (options.adopt && resolved.framework !== 'markdown') {
+            throw new Error('--adopt applies only to --framework markdown.');
+        }
+        const inapplicableOptions = [];
         const existingConfig = await dependencies.readOatConfig(context.cwd);
-        if (existingConfig.documentation?.root) {
+        if (resolved.framework === 'markdown') {
+            resolved.targetDir = await validateMarkdownTarget(context.cwd, resolved.targetDir);
+            validateMarkdownConfig(context.cwd, resolved.targetDir, existingConfig.documentation);
+            if (options.appName !== undefined)
+                inapplicableOptions.push('--app-name');
+            if (options.rootPatch === false)
+                inapplicableOptions.push('--no-root-patch');
+            if (!context.json && inapplicableOptions.length)
+                context.logger.warn(`Inapplicable to Markdown: ${inapplicableOptions.join(', ')}. No app or package changes will be made.`);
+        }
+        else if (existingConfig.documentation?.root) {
             const configDesc = `root: ${existingConfig.documentation.root}, tooling: ${existingConfig.documentation.tooling ?? 'unknown'}`;
             if (context.json) {
                 // JSON mode: include warning in output, proceed only with --yes
@@ -175,21 +288,78 @@ async function runDocsInitCommand(context, options, dependencies) {
         }
         const assetsRoot = await dependencies.resolveAssetsRoot();
         const scaffold = await dependencies.runDocsInit(context, resolved, assetsRoot);
+        if (scaffold?.failure) {
+            if (context.json) {
+                context.logger.json({
+                    status: 'partial',
+                    ...resolved,
+                    ...scaffold,
+                    scaffold: {
+                        status: scaffold.failure.stage === 'scaffold' ? 'partial' : 'complete',
+                        targetDir: resolved.targetDir,
+                        createdFiles: scaffold.createdFiles,
+                    },
+                    guidance: { action: 'not-attempted' },
+                });
+            }
+            else {
+                context.logger.warn(`Markdown setup is partial: ${scaffold.failure.stage} failed: ${scaffold.failure.message}`);
+                context.logger.info(`Created baseline files: ${scaffold.createdFiles.join(', ') || 'none'}. Configuration: ${scaffold.configStatus}. Guidance was not attempted; preserve created content when retrying with --adopt.`);
+                if (scaffold.incompleteFiles?.length) {
+                    context.logger.warn(`Baseline files requiring inspection: ${scaffold.incompleteFiles.join(', ')}. Automatic cleanup could not be completed; inspect or repair these paths before retrying. Adoption preserves existing files.`);
+                }
+            }
+            process.exitCode = 1;
+            return;
+        }
         const sectionBody = buildDocsSectionBody(resolved);
         let sectionResult;
         try {
-            sectionResult = await dependencies.upsertAgentsMdSection(context.cwd, 'docs', sectionBody);
+            sectionResult =
+                resolved.framework === 'markdown' && context.dryRun
+                    ? await dependencies.previewAgentsMdSection(context.cwd, 'docs', sectionBody)
+                    : await dependencies.upsertAgentsMdSection(context.cwd, 'docs', sectionBody);
         }
         catch (error) {
-            throw new Error(formatAgentsMdMutationFailure(error), { cause: error });
+            if (resolved.framework !== 'markdown')
+                throw new Error(formatAgentsMdMutationFailure(error), { cause: error });
+            sectionResult = {
+                action: 'blocked',
+                blocked: {
+                    code: 'blocked',
+                    target: 'AGENTS.md',
+                    reason: formatAgentsMdMutationFailure(error),
+                    action: 'Review root guidance and retry.',
+                },
+            };
+        }
+        const markdownDetails = resolved.framework === 'markdown'
+            ? {
+                ...resolved,
+                ...scaffold,
+                dryRun: context.dryRun,
+                inapplicableOptions,
+                changes: {
+                    ...scaffold?.changes,
+                    guidance: sectionResult.action !== 'no-change',
+                },
+            }
+            : {};
+        if (resolved.framework === 'markdown' && context.dryRun && !context.json) {
+            context.logger.info(`Dry run: ${scaffold?.plannedFiles?.length ?? 0} planned baseline file(s); configuration ${scaffold?.configStatus}; guidance ${sectionResult.action}. No changes were written.`);
+            for (const advice of scaffold?.auditAdvice ?? [])
+                context.logger.info(advice);
         }
         if (sectionResult.action === 'manual-required' ||
             sectionResult.action === 'blocked') {
             if (context.json) {
                 context.logger.json({
                     status: 'partial',
+                    ...markdownDetails,
                     scaffold: {
-                        status: 'complete',
+                        status: resolved.framework === 'markdown' && context.dryRun
+                            ? 'planned'
+                            : 'complete',
                         targetDir: resolved.targetDir,
                         framework: resolved.framework,
                     },
@@ -197,7 +367,7 @@ async function runDocsInitCommand(context, options, dependencies) {
                 });
             }
             else {
-                context.logger.warn(`Docs scaffold completed; AGENTS.md guidance is ${sectionResult.action}.`);
+                context.logger.warn(`${resolved.framework === 'markdown' && context.dryRun ? 'Docs scaffold planned' : 'Docs scaffold completed'}; AGENTS.md guidance is ${sectionResult.action}.`);
                 for (const line of formatAgentsMdGuidanceResult(sectionResult)) {
                     context.logger.info(line);
                 }
@@ -211,14 +381,21 @@ async function runDocsInitCommand(context, options, dependencies) {
                 ...resolved,
                 ...scaffold,
                 guidance: sectionResult,
+                ...markdownDetails,
             });
         }
         else if (sectionResult.action !== 'no-change') {
-            context.logger.info(`AGENTS.md docs section ${sectionResult.action}.`);
+            context.logger.info(`AGENTS.md docs section ${resolved.framework === 'markdown' && context.dryRun ? 'planned: ' : ''}${sectionResult.action}.`);
         }
         if (!context.json) {
             context.logger.info('');
             context.logger.info('Next steps:');
+            if (resolved.framework === 'markdown') {
+                context.logger.info(`  Read ${resolved.targetDir}/index.md and ${resolved.targetDir}/contributing.md.`);
+                context.logger.info('  Use oat-docs-analyze to audit documentation and oat-docs-apply for approved repairs.');
+                process.exitCode = 0;
+                return;
+            }
             const commands = buildDocsCommands(resolved.repoShape, resolved.targetDir, resolved.appName);
             context.logger.info(`  ${commands.install}`);
             context.logger.info(`  ${commands.dev}`);
@@ -250,15 +427,16 @@ export function createDocsInitCommand(overrides = {}) {
         ...overrides,
     };
     return new Command('init')
-        .description('Scaffold an OAT docs app')
+        .description('Bootstrap an OAT docs app or authored Markdown documentation')
         .addOption(new Option('--framework <framework>', 'Documentation framework').choices([
         'fumadocs',
         'mkdocs',
+        'markdown',
     ]))
-        .addOption(new Option('--app-name <name>', 'Docs app name'))
-        .addOption(new Option('--site-name <name>', 'Display title (distinct from --app-name)'))
-        .addOption(new Option('--target-dir <path>', 'Target directory for the docs app'))
-        .addOption(new Option('--description <text>', 'Site description'))
+        .addOption(new Option('--app-name <name>', 'Docs app name (inapplicable to Markdown)'))
+        .addOption(new Option('--site-name <name>', 'Site display title or Markdown documentation title'))
+        .addOption(new Option('--target-dir <path>', 'Docs directory (Markdown defaults to docs; requires a dedicated directory)'))
+        .addOption(new Option('--description <text>', 'Documentation description'))
         .addOption(new Option('--lint <mode>', 'Markdown lint mode').choices([
         'none',
         'markdownlint-cli2',
@@ -267,7 +445,9 @@ export function createDocsInitCommand(overrides = {}) {
         'oxfmt',
         'none',
     ]))
-        .option('--no-root-patch', 'Skip patching the consumer root package.json')
+        .option('--no-root-patch', 'Skip root package.json patch (inapplicable to Markdown)')
+        .option('--adopt', 'Add missing baseline files to existing Markdown docs; preserve authored content (Markdown only)')
+        .option('--dry-run', 'Preview Markdown files, config, and guidance without writes (Markdown only)')
         .option('--yes', 'Accept defaults without prompting')
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));

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

@@ -0,0 +1,39 @@
+import type { OatDocumentationConfig } from '../../../config/oat-config.js';
+import { type DocsInitResolvedOptions } from './resolve-options.js';
+/** Validate a dedicated Markdown root, including existing symlink ancestors. */
+export declare function validateMarkdownTarget(repoRoot: string, targetDir: string): Promise<string>;
+export interface MarkdownDocsOptions extends DocsInitResolvedOptions {
+    assetsRoot: string;
+    documentation?: OatDocumentationConfig;
+}
+export interface MarkdownDocsPlan {
+    repoRoot: string;
+    targetDir: string;
+    appRoot: string;
+    files: {
+        name: string;
+        content: string;
+    }[];
+    preservedFiles: string[];
+    auditAdvice: string[];
+    documentationConfig: OatDocumentationConfig;
+    configChanged: boolean;
+}
+export interface MarkdownDocsResult {
+    appRoot: string;
+    createdFiles: string[];
+    incompleteFiles: string[];
+    preservedFiles: string[];
+    auditAdvice: string[];
+    documentationConfig: OatDocumentationConfig;
+}
+export declare class MarkdownDocsWriteError extends Error {
+    readonly result: MarkdownDocsResult;
+    constructor(message: string, result: MarkdownDocsResult, cause: unknown);
+}
+export declare function validateMarkdownConfig(repoRoot: string, targetDir: string, declared?: OatDocumentationConfig): void;
+/** Read-only inspection used by both adoption and CLI dry-run. */
+export declare function planMarkdownDocs(options: MarkdownDocsOptions): Promise<MarkdownDocsPlan>;
+/** Adds missing baseline files exclusively; config is persisted by the caller. */
+export declare function applyMarkdownDocsPlan(plan: MarkdownDocsPlan): Promise<MarkdownDocsResult>;
+//# sourceMappingURL=markdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/markdown.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAKjE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAsBD,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;IAC5C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,MAAM,EAAE,kBAAkB;IAFrC,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,kBAAkB,EACnC,KAAK,EAAE,OAAO,EAGf;CACF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,IAAI,CAeN;AA6JD,kEAAkE;AAClE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CA2E3B;AAED,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA8E7B"}