#!/usr/bin/env node

/**

* XcodeBuildMCP Tools Documentation Updater

*

* Automatically updates docs/TOOLS.md and docs/TOOLS-CLI.md with current tool and workflow information

* using the build tools manifest.

*

* Usage:

* npx tsx scripts/update-tools-docs.ts [--dry-run] [--verbose]

*

* Options:

* --dry-run, -d Show what would be updated without making changes

* --verbose, -v Show detailed information about the update process

* --help, -h Show this help message

*/

import * as fs from 'fs';

import * as path from 'path';

import { fileURLToPath } from 'url';

import { loadManifest as loadYamlManifest } from '../src/core/manifest/load-manifest.ts';

import { getEffectiveCliName } from '../src/core/manifest/schema.ts';

// Get project paths

const __filename = fileURLToPath(import.meta.url);

const __dirname = path.dirname(__filename);

const projectRoot = path.resolve(__dirname, '..');

const docsPath = path.join(projectRoot, 'docs', 'TOOLS.md');

const docsCliPath = path.join(projectRoot, 'docs', 'TOOLS-CLI.md');

const cliExcludedWorkflows = new Set(['session-management', 'workflow-discovery']);

type ToolsManifest = {

generatedAt: string;

stats: {

totalTools: number;

canonicalTools: number;

reExportTools: number;

workflowCount: number;

};

workflows: DocumentationWorkflow[];

tools: DocumentationTool[];

};

// CLI options

const args = process.argv.slice(2);

const options = {

dryRun: args.includes('--dry-run') || args.includes('-d'),

verbose: args.includes('--verbose') || args.includes('-v'),

help: args.includes('--help') || args.includes('-h'),

};

const colors = {

reset: '\x1b[0m',

bright: '\x1b[1m',

red: '\x1b[31m',

green: '\x1b[32m',

yellow: '\x1b[33m',

blue: '\x1b[34m',

cyan: '\x1b[36m',

magenta: '\x1b[35m',

} as const;

if (options.help) {

console.log(`

${colors.bright}${colors.blue}XcodeBuildMCP Tools Documentation Updater${colors.reset}

Automatically updates docs/TOOLS.md and docs/TOOLS-CLI.md with current tool and workflow information.

${colors.bright}Usage:${colors.reset}

npx tsx scripts/update-tools-docs.ts [options]

${colors.bright}Options:${colors.reset}

--dry-run, -d Show what would be updated without making changes

--verbose, -v Show detailed information about the update process

--help, -h Show this help message

${colors.bright}Examples:${colors.reset}

${colors.cyan}npx tsx scripts/update-tools-docs.ts${colors.reset} # Update docs/TOOLS.md + docs/TOOLS-CLI.md

${colors.cyan}npx tsx scripts/update-tools-docs.ts --dry-run${colors.reset} # Preview changes

${colors.cyan}npx tsx scripts/update-tools-docs.ts --verbose${colors.reset} # Show detailed progress

`);

process.exit(0);

}

/**

* Generate the workflow section content

*/

function cleanToolDescription(description: string | undefined): string {

if (!description) {

return 'No description available';

}

return description

.replace(/IMPORTANT:.*?Example:.*?\)/g, '') // Remove IMPORTANT sections

.replace(/\s+/g, ' ') // Normalize whitespace

.trim();

}

type DocumentationTool = {

name: string;

description?: string;

isCanonical?: boolean;

originWorkflowDisplayName?: string;

workflow?: string;

cliName?: string;

originWorkflow?: string;

};

type DocumentationWorkflow = {

name: string;

displayName: string;

description: string;

};

function generateWorkflowSection(

workflow: DocumentationWorkflow,

tools: DocumentationTool[],

): string {

const toolCount = tools.length;

let content = `### ${workflow.displayName} (\`${workflow.name}\`)\n`;

content += `**Purpose**: ${workflow.description} (${toolCount} tools)\n\n`;

// List each tool with its description

const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));

for (const tool of sortedTools) {

let description = tool.description;

if (tool.isCanonical === false) {

if (tool.originWorkflowDisplayName) {

description = `Defined in ${tool.originWorkflowDisplayName} workflow.`;

} else {

description = 'Defined in another workflow.';

}

}

const cleanDescription = cleanToolDescription(description);

content += `- \`${tool.name}\` - ${cleanDescription}\n`;

}

content += '\n\n';

return content;

}

function loadManifest(): ToolsManifest {

const manifest = loadYamlManifest();

const workflowList = Array.from(manifest.workflows.values());

const firstWorkflowByToolId = new Map<string, string>();

const docsTools: DocumentationTool[] = [];

for (const workflow of workflowList) {

for (const toolId of workflow.tools) {

if (!firstWorkflowByToolId.has(toolId)) {

firstWorkflowByToolId.set(toolId, workflow.id);

}

const tool = manifest.tools.get(toolId);

if (!tool) {

continue;

}

const originWorkflow = firstWorkflowByToolId.get(toolId);

docsTools.push({

name: tool.names.mcp,

description: tool.description,

isCanonical: originWorkflow === workflow.id,

originWorkflow,

workflow: workflow.id,

cliName: getEffectiveCliName(tool),

});

}

}

return {

generatedAt: new Date().toISOString(),

stats: {

totalTools: docsTools.length,

canonicalTools: manifest.tools.size,

reExportTools: docsTools.length - manifest.tools.size,

workflowCount: workflowList.length,

},

workflows: workflowList.map((workflow) => ({

name: workflow.id,

displayName: workflow.title,

description: workflow.description,

})),

tools: docsTools,

};

}

/**

* Generate the complete TOOLS.md content

*/

function generateToolsDocumentation(manifest: ToolsManifest): string {

const { workflows, stats, tools } = manifest;

// Sort workflows by display name for consistent ordering

const sortedWorkflows = [...workflows].sort((a, b) => a.displayName.localeCompare(b.displayName));

const workflowMeta = new Map(workflows.map((workflow) => [workflow.name, workflow]));

const toolsByWorkflow = new Map<string, DocumentationTool[]>();

for (const tool of tools) {

const workflowKey = tool.workflow ?? '';

const workflowTools = toolsByWorkflow.get(workflowKey) ?? [];

workflowTools.push(tool);

toolsByWorkflow.set(workflowKey, workflowTools);

}

const workflowSections = sortedWorkflows

.map((workflow) => {

const workflowTools = toolsByWorkflow.get(workflow.name) ?? [];

const docTools = workflowTools.map((tool) => {

const originWorkflow = tool.originWorkflow

? (workflowMeta.get(tool.originWorkflow)?.displayName ?? tool.originWorkflow)

: undefined;

return {

name: tool.name,

description: tool.description,

isCanonical: tool.isCanonical,

originWorkflowDisplayName: originWorkflow,

};

});

return generateWorkflowSection(

{

name: workflow.name,

displayName: workflow.displayName,

description: workflow.description,

},

docTools,

);

})

.join('\n');

const lastUpdated = `${new Date(manifest.generatedAt).toISOString()} UTC`;

const content = `# XcodeBuildMCP MCP Tools Reference

This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP provides ${stats.canonicalTools} canonical tools organized into ${stats.workflowCount} workflow groups for comprehensive Apple development workflows.

## Workflow Groups

${workflowSections}

## Summary Statistics

- **Canonical Tools**: ${stats.canonicalTools}

- **Total Tools**: ${stats.totalTools}

- **Workflow Groups**: ${stats.workflowCount}

---

*This documentation is automatically generated by \`scripts/update-tools-docs.ts\` from the tools manifest. Last updated: ${lastUpdated}*

`;

return content;

}

/**

* Generate CLI tools documentation content

*/

type CliDocumentationStats = {

toolCount: number;

canonicalToolCount: number;

workflowCount: number;

};

type CliDocumentationResult = {

content: string;

stats: CliDocumentationStats;

};

function generateCliToolsDocumentation(manifest: ToolsManifest): CliDocumentationResult {

const workflowMeta = new Map(manifest.workflows.map((workflow) => [workflow.name, workflow]));

const toolsByWorkflow = new Map<string, DocumentationTool[]>();

let canonicalToolCount = 0;

for (const tool of manifest.tools) {

if (cliExcludedWorkflows.has(tool.workflow)) {

continue;

}

if (tool.isCanonical) {

canonicalToolCount++;

}

const tools = toolsByWorkflow.get(tool.workflow) ?? [];

const originWorkflow = tool.originWorkflow

? (workflowMeta.get(tool.originWorkflow)?.displayName ?? tool.originWorkflow)

: undefined;

tools.push({

name: tool.cliName ?? tool.name,

description: tool.description,

isCanonical: tool.isCanonical,

originWorkflowDisplayName: originWorkflow,

});

toolsByWorkflow.set(tool.workflow, tools);

}

const sortedWorkflows = [...manifest.workflows]

.filter((workflow) => toolsByWorkflow.has(workflow.name))

.filter((workflow) => !cliExcludedWorkflows.has(workflow.name))

.sort((a, b) => a.displayName.localeCompare(b.displayName));

const workflowSections = sortedWorkflows

.map((workflow) => {

const tools = toolsByWorkflow.get(workflow.name) ?? [];

const meta = workflowMeta.get(workflow.name);

return generateWorkflowSection(

{

name: workflow.name,

displayName: meta?.displayName ?? workflow.name,

description: meta?.description ?? `${workflow.name} related tools`,

},

tools,

);

})

.join('\n');

const workflowCount = sortedWorkflows.length;

const totalTools = Array.from(toolsByWorkflow.values()).reduce(

(sum, tools) => sum + tools.length,

0,

);

const lastUpdated = `${new Date(manifest.generatedAt).toISOString()} UTC`;

const content = `# XcodeBuildMCP CLI Tools Reference

This document lists CLI tool names as exposed by \`xcodebuildmcp <workflow> <tool>\`.

XcodeBuildMCP provides ${canonicalToolCount} canonical tools organized into ${workflowCount} workflow groups.

## Workflow Groups

${workflowSections}

## Summary Statistics

- **Canonical Tools**: ${canonicalToolCount}

- **Total Tools**: ${totalTools}

- **Workflow Groups**: ${workflowCount}

---

*This documentation is automatically generated by \`scripts/update-tools-docs.ts\` from the tools manifest. Last updated: ${lastUpdated}*

`;

return {

content,

stats: {

toolCount: totalTools,

canonicalToolCount,

workflowCount,

},

};

}

/**

* Compare old and new content to show what changed

*/

function showDiff(oldContent: string, newContent: string): void {

if (!options.verbose) return;

console.log(`${colors.bright}${colors.cyan}📄 Content Comparison:${colors.reset}`);

console.log('─'.repeat(50));

const oldLines = oldContent.split('\n');

const newLines = newContent.split('\n');

const maxLength = Math.max(oldLines.length, newLines.length);

let changes = 0;

for (let i = 0; i < maxLength; i++) {

const oldLine = oldLines[i] || '';

const newLine = newLines[i] || '';

if (oldLine !== newLine) {

changes++;

if (changes <= 10) {

// Show first 10 changes

console.log(`${colors.red}- Line ${i + 1}: ${oldLine}${colors.reset}`);

console.log(`${colors.green}+ Line ${i + 1}: ${newLine}${colors.reset}`);

}

}

}

if (changes > 10) {

console.log(`${colors.yellow}... and ${changes - 10} more changes${colors.reset}`);

}

console.log(`${colors.blue}Total changes: ${changes} lines${colors.reset}\n`);

}

/**

* Main execution function

*/

async function main(): Promise<void> {

try {

console.log(

`${colors.bright}${colors.blue}🔧 XcodeBuildMCP Tools Documentation Updater${colors.reset}`,

);

if (options.dryRun) {

console.log(

`${colors.yellow}🔍 Running in dry-run mode - no files will be modified${colors.reset}`,

);

}

console.log(`${colors.cyan}📊 Analyzing tools...${colors.reset}`);

const manifest = loadManifest();

if (options.verbose) {

console.log(

`${colors.green}✓ Found ${manifest.stats.canonicalTools} canonical tools in ${manifest.stats.workflowCount} workflows${colors.reset}`,

);

}

// Generate new documentation content

console.log(`${colors.cyan}📝 Generating documentation...${colors.reset}`);

const mcpContent = generateToolsDocumentation(manifest);

const cliDocumentation = generateCliToolsDocumentation(manifest);

const cliContent = cliDocumentation.content;

const cliStats = cliDocumentation.stats;

const targets = [

{ label: 'MCP tools', path: docsPath, content: mcpContent },

{ label: 'CLI tools', path: docsCliPath, content: cliContent },

];

const changes = targets.map((target) => {

const existing = fs.existsSync(target.path) ? fs.readFileSync(target.path, 'utf-8') : '';

const changed = existing !== target.content;

return { ...target, existing, changed };

});

const changedTargets = changes.filter((target) => target.changed);

// Check if content has changed

if (changedTargets.length === 0) {

console.log(`${colors.green}✅ Documentation is already up to date!${colors.reset}`);

return;

}

// Show differences if verbose

if (options.verbose) {

for (const target of changedTargets) {

if (target.existing) {

console.log(

`${colors.bright}${colors.magenta}📄 ${target.label} content comparison:${colors.reset}`,

);

showDiff(target.existing, target.content);

}

}

}

if (options.dryRun) {

console.log(

`${colors.yellow}📋 Dry run completed. Documentation would be updated with:${colors.reset}`,

);

for (const target of changedTargets) {

console.log(` - ${path.relative(projectRoot, target.path)} (${target.label})`);

}

console.log(` - MCP tools: ${manifest.stats.canonicalTools} canonical tools`);

console.log(

` - CLI tools: ${cliStats.toolCount} tools across ${cliStats.workflowCount} workflows`,

);

console.log(` - MCP lines: ${mcpContent.split('\n').length}`);

console.log(` - CLI lines: ${cliContent.split('\n').length}`);

if (!options.verbose) {

console.log(`\n${colors.cyan}💡 Use --verbose to see detailed changes${colors.reset}`);

}

return;

}

// Write new content

console.log(`${colors.cyan}✏️ Writing updated documentation...${colors.reset}`);

for (const target of changedTargets) {

fs.writeFileSync(target.path, target.content, 'utf-8');

console.log(

`${colors.green}✅ Successfully updated ${path.relative(projectRoot, target.path)}!${colors.reset}`,

);

}

if (options.verbose) {

console.log(`\n${colors.bright}📈 Update Summary:${colors.reset}`);

console.log(

` MCP tools: ${manifest.stats.canonicalTools} canonical (${manifest.stats.totalTools} total)`,

);

console.log(` MCP workflows: ${manifest.stats.workflowCount}`);

console.log(` CLI tools: ${cliStats.toolCount} across ${cliStats.workflowCount} workflows`);

console.log(` MCP file size: ${(mcpContent.length / 1024).toFixed(1)}KB`);

console.log(` CLI file size: ${(cliContent.length / 1024).toFixed(1)}KB`);

console.log(` MCP lines: ${mcpContent.split('\n').length}`);

console.log(` CLI lines: ${cliContent.split('\n').length}`);

}

} catch (error) {

console.error(`${colors.red}❌ Error: ${(error as Error).message}${colors.reset}`);

process.exit(1);

}

}

// Run the updater

main();