@guiho/xdocs 0.1.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# GUIHO XDocs Changelog

package/LICENSE.md

@@ -0,0 +1,23 @@
+@guiho/xdocs
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Cristóvão GUIHO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/jsr.json

@@ -0,0 +1,12 @@
+{
+  "name": "@guiho/xdocs",
+  "version": "0.1.0",
+  "exports": "./source/guiho-xdocs.ts",
+  "publish": {
+    "include": [
+      "source/**/*.ts",
+      "README.md",
+      "LICENSE.md"
+    ]
+  }
+}

package/library/cli.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+/** Main CLI entry point. */
+export declare const runCli: (rawArgs?: string[]) => Promise<void>;
+/** Run the CLI with error handling. */
+export declare const runCliWithErrorHandling: (rawArgs?: string[]) => Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/library/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiBH,4BAA4B;AAC5B,eAAO,MAAM,MAAM,GAAU,UAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CAqDpF,CAAA;AAmBD,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAU,UAAU,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAiB9E,CAAA"}

package/library/cli.js

@@ -0,0 +1,97 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { resolve } from 'node:path';
+import { XDocsError } from './errors.js';
+import { parseArgs, booleanFlag, stringFlag } from './flags.js';
+import { showHelp, showCommandHelp, showVersion } from './help.js';
+import { runInit } from './commands/init.js';
+import { runScan } from './commands/scan.js';
+import { runGenerate } from './commands/generate.js';
+import { runPrompt } from './commands/prompt.js';
+import { runMerge } from './commands/merge.js';
+import { runTree } from './commands/tree.js';
+import { runList } from './commands/list.js';
+const validCommands = new Set(['init', 'scan', 'generate', 'prompt', 'merge', 'tree', 'list']);
+/** Main CLI entry point. */
+export const runCli = async (rawArgs = process.argv.slice(2)) => {
+    const parsed = parseArgs(rawArgs);
+    if (booleanFlag(parsed.flags, 'version')) {
+        process.stdout.write(showVersion() + '\n');
+        return;
+    }
+    if (booleanFlag(parsed.flags, 'help')) {
+        if (parsed.command && validCommands.has(parsed.command)) {
+            process.stdout.write(showCommandHelp(parsed.command) + '\n');
+        }
+        else {
+            process.stdout.write(showHelp() + '\n');
+        }
+        return;
+    }
+    if (!parsed.command) {
+        process.stdout.write(showHelp() + '\n');
+        return;
+    }
+    if (!validCommands.has(parsed.command)) {
+        throw new XDocsError(`Unknown command: ${parsed.command}\n\nRun \`xdocs --help\` for available commands.`);
+    }
+    const options = resolveOptions(parsed.flags);
+    const command = parsed.command;
+    switch (command) {
+        case 'init':
+            await runInit(options, parsed);
+            break;
+        case 'scan':
+            await runScan(options, parsed);
+            break;
+        case 'generate':
+            await runGenerate(options, parsed);
+            break;
+        case 'prompt':
+            await runPrompt(options, parsed);
+            break;
+        case 'merge':
+            await runMerge(options, parsed);
+            break;
+        case 'tree':
+            await runTree(options, parsed);
+            break;
+        case 'list':
+            await runList(options, parsed);
+            break;
+    }
+};
+/** Build XDocsCliOptions from parsed flags. */
+const resolveOptions = (flags) => {
+    const cwd = stringFlag(flags, 'cwd') ?? process.cwd();
+    const format = stringFlag(flags, 'format') ?? 'text';
+    if (format !== 'text' && format !== 'json' && format !== 'markdown') {
+        throw new XDocsError(`Invalid --format value: "${format}". Expected text, json, or markdown.`);
+    }
+    return {
+        cwd: resolve(cwd),
+        config: stringFlag(flags, 'config'),
+        format: format,
+        verbose: booleanFlag(flags, 'verbose'),
+    };
+};
+/** Run the CLI with error handling. */
+export const runCliWithErrorHandling = async (rawArgs) => {
+    try {
+        await runCli(rawArgs);
+    }
+    catch (error) {
+        if (error instanceof XDocsError) {
+            process.stderr.write(`error: ${error.message}\n`);
+            process.exit(error.exitCode);
+        }
+        if (error instanceof Error) {
+            process.stderr.write(`error: ${error.message}\n`);
+        }
+        else {
+            process.stderr.write('error: An unexpected error occurred.\n');
+        }
+        process.exit(1);
+    }
+};

package/library/commands/generate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
+/** Run the generate command. */
+export declare const runGenerate: (options: XDocsCliOptions, parsed: XDocsParsedArgs) => Promise<void>;
+//# sourceMappingURL=generate.d.ts.map

package/library/commands/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../source/commands/generate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAMnE,gCAAgC;AAChC,eAAO,MAAM,WAAW,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CA2BjG,CAAA"}

package/library/commands/generate.js

@@ -0,0 +1,122 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { readdir } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { loadConfigOrDefaults } from '../config.js';
+import { scanProject } from '../discovery.js';
+import { buildTree, renderTree } from '../tree.js';
+import { stringFlag } from '../flags.js';
+/** Run the generate command. */
+export const runGenerate = async (options, parsed) => {
+    const config = await loadConfigOrDefaults(options);
+    const targetPath = parsed.positionals[0] ? resolve(options.cwd, parsed.positionals[0]) : options.cwd;
+    const outputPath = stringFlag(parsed.flags, 'output');
+    const result = await scanProject(config);
+    const isProjectScope = targetPath === options.cwd;
+    let content;
+    if (isProjectScope) {
+        content = await generateProjectDoc(config.project.name, result.xdocsFiles, config.cwd);
+    }
+    else {
+        const relTarget = relative(config.cwd, targetPath);
+        const relevantFiles = result.xdocsFiles.filter((f) => f.path.startsWith(targetPath));
+        content = await generateModuleDoc(relTarget, relevantFiles, config.cwd, targetPath);
+    }
+    if (outputPath) {
+        await writeFile(resolve(options.cwd, outputPath), content, 'utf8');
+        process.stdout.write(`generated: ${outputPath}\n`);
+    }
+    else {
+        process.stdout.write(content);
+    }
+};
+/** Generate a project-level documentation file. */
+const generateProjectDoc = async (projectName, xdocsFiles, _cwd) => {
+    const lines = [
+        `# ${projectName}`,
+        '',
+        '## Project Overview',
+        '',
+        `This document was generated by xdocs. It describes the full project structure.`,
+        '',
+    ];
+    // Tree
+    const tree = buildTree(xdocsFiles);
+    lines.push('## Hierarchy', '', '```');
+    lines.push(renderTree(tree));
+    lines.push('```', '');
+    // Modules
+    lines.push('## Modules', '');
+    for (const file of xdocsFiles) {
+        if (!file.metadata)
+            continue;
+        lines.push(`### ${file.metadata.subject}`, '');
+        lines.push(file.metadata.description, '');
+        lines.push(`Location: \`${file.relativePath}\``, '');
+        const fileEntries = Object.entries(file.metadata.files);
+        if (fileEntries.length > 0) {
+            lines.push('Files:', '');
+            for (const [name, desc] of fileEntries) {
+                lines.push(`- \`${name}\`: ${desc}`);
+            }
+            lines.push('');
+        }
+        if (file.body.trim()) {
+            lines.push(file.body.trim(), '');
+        }
+    }
+    return lines.join('\n');
+};
+/** Generate a module-level documentation file. */
+const generateModuleDoc = async (moduleName, xdocsFiles, _cwd, targetPath) => {
+    const lines = [
+        `# ${moduleName}`,
+        '',
+    ];
+    // List all files in the target directory
+    let dirEntries = [];
+    try {
+        const entries = await readdir(targetPath);
+        dirEntries = entries.filter((e) => !e.startsWith('.'));
+    }
+    catch {
+        // Directory might not exist
+    }
+    if (xdocsFiles.length > 0) {
+        for (const file of xdocsFiles) {
+            if (!file.metadata)
+                continue;
+            lines.push(`## ${file.metadata.subject}`, '');
+            lines.push(file.metadata.description, '');
+            const fileEntries = Object.entries(file.metadata.files);
+            if (fileEntries.length > 0) {
+                lines.push('### Files', '');
+                for (const [name, desc] of fileEntries) {
+                    lines.push(`- \`${name}\`: ${desc}`);
+                }
+                lines.push('');
+            }
+            if (file.metadata.children.length > 0) {
+                lines.push('### Submodules', '');
+                for (const child of file.metadata.children) {
+                    lines.push(`- ${child}`);
+                }
+                lines.push('');
+            }
+            if (file.body.trim()) {
+                lines.push(file.body.trim(), '');
+            }
+        }
+    }
+    else {
+        lines.push(`No xdocs files found in this directory.`, '');
+        lines.push('### Directory contents', '');
+        for (const entry of dirEntries) {
+            lines.push(`- \`${entry}\``);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+};

package/library/commands/init.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
+/** Run the init command. */
+export declare const runInit: (options: XDocsCliOptions, _parsed: XDocsParsedArgs) => Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/library/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../source/commands/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AA8BnE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,SAAS,eAAe,KAAG,OAAO,CAAC,IAAI,CAqC9F,CAAA"}

package/library/commands/init.js

@@ -0,0 +1,71 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { writeDefaultConfig } from '../config.js';
+const ROOT_XDOCS_CONTENT = `
+# GUIHO XDocs Documentation
+
+## Files
+
+## Directories
+`.trim() + '\n';
+const AGENTS_XDOCS_BLOCK = `
+<!-- BEGIN XDOCS — DO NOT EDIT THIS SECTION -->
+## XDocs
+
+This project uses xdocs for structured documentation. xdocs files describe
+modules, their purpose, files, and hierarchy.
+
+- Configuration: \`xdocs.config.toml\`
+- Root documentation: \`XDOCS.md\`
+- File extensions: \`.docs.md\`, \`.xdocs.md\`
+
+When modifying code, check the xdocs configuration for AI behavior mode.
+In "prompt" mode, announce documentation updates and wait for confirmation.
+In "auto" mode, update documentation immediately.
+
+Use the xdocs CLI for operations: \`xdocs scan\`, \`xdocs generate\`, \`xdocs tree\`, etc.
+<!-- END XDOCS -->
+`.trim();
+/** Run the init command. */
+export const runInit = async (options, _parsed) => {
+    const cwd = options.cwd;
+    // 1. Create xdocs.config.toml
+    const configPath = resolve(cwd, 'xdocs.config.toml');
+    if (existsSync(configPath)) {
+        process.stdout.write(`exists: xdocs.config.toml\n`);
+    }
+    else {
+        await writeDefaultConfig(cwd);
+        process.stdout.write(`created: xdocs.config.toml\n`);
+    }
+    // 2. Create XDOCS.md
+    const xdocsPath = resolve(cwd, 'XDOCS.md');
+    if (existsSync(xdocsPath)) {
+        process.stdout.write(`exists: XDOCS.md\n`);
+    }
+    else {
+        await writeFile(xdocsPath, ROOT_XDOCS_CONTENT, 'utf8');
+        process.stdout.write(`created: XDOCS.md\n`);
+    }
+    // 3. Update AGENTS.md
+    const agentsPath = resolve(cwd, 'AGENTS.md');
+    if (existsSync(agentsPath)) {
+        const content = await readFile(agentsPath, 'utf8');
+        if (content.includes('<!-- BEGIN XDOCS')) {
+            process.stdout.write(`exists: AGENTS.md (xdocs section already present)\n`);
+        }
+        else {
+            await writeFile(agentsPath, content.trimEnd() + '\n\n' + AGENTS_XDOCS_BLOCK + '\n', 'utf8');
+            process.stdout.write(`updated: AGENTS.md (added xdocs section)\n`);
+        }
+    }
+    else {
+        await writeFile(agentsPath, '# Agent Instructions\n\n' + AGENTS_XDOCS_BLOCK + '\n', 'utf8');
+        process.stdout.write(`created: AGENTS.md\n`);
+    }
+    process.stdout.write(`\nxdocs initialized.\n`);
+};

package/library/commands/list.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
+/** Run the list command. */
+export declare const runList: (options: XDocsCliOptions, parsed: XDocsParsedArgs) => Promise<void>;
+//# sourceMappingURL=list.d.ts.map

package/library/commands/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../source/commands/list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAInE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CA2C7F,CAAA"}

package/library/commands/list.js

@@ -0,0 +1,41 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { resolve, relative } from 'node:path';
+import { loadConfigOrDefaults } from '../config.js';
+import { scanProject } from '../discovery.js';
+/** Run the list command. */
+export const runList = async (options, parsed) => {
+    const config = await loadConfigOrDefaults(options);
+    const targetPath = parsed.positionals[0] ? resolve(options.cwd, parsed.positionals[0]) : options.cwd;
+    const result = await scanProject(config);
+    const relevantFiles = result.xdocsFiles.filter((f) => f.path.startsWith(targetPath));
+    // Collect all files with descriptions from metadata
+    const fileList = [];
+    for (const xdocsFile of relevantFiles) {
+        if (!xdocsFile.metadata)
+            continue;
+        for (const [fileName, description] of Object.entries(xdocsFile.metadata.files)) {
+            fileList.push({
+                file: fileName,
+                description,
+                source: xdocsFile.relativePath,
+            });
+        }
+    }
+    if (options.format === 'json') {
+        process.stdout.write(JSON.stringify(fileList, null, 2) + '\n');
+        return;
+    }
+    if (fileList.length === 0) {
+        const scope = targetPath === options.cwd ? 'project' : relative(options.cwd, targetPath);
+        process.stdout.write(`No documented files found in ${scope}.\n`);
+        return;
+    }
+    const scope = targetPath === options.cwd ? 'project' : relative(options.cwd, targetPath);
+    process.stdout.write(`\nfiles in ${scope}:\n\n`);
+    for (const entry of fileList) {
+        process.stdout.write(`  ${entry.file}: ${entry.description}\n`);
+    }
+    process.stdout.write('\n');
+};

package/library/commands/merge.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
+/** Run the merge command. */
+export declare const runMerge: (options: XDocsCliOptions, parsed: XDocsParsedArgs) => Promise<void>;
+//# sourceMappingURL=merge.d.ts.map

package/library/commands/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../source/commands/merge.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAKnE,6BAA6B;AAC7B,eAAO,MAAM,QAAQ,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CAyD9F,CAAA"}

package/library/commands/merge.js

@@ -0,0 +1,55 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { loadConfigOrDefaults } from '../config.js';
+import { scanProject } from '../discovery.js';
+import { stringFlag } from '../flags.js';
+/** Run the merge command. */
+export const runMerge = async (options, parsed) => {
+    const config = await loadConfigOrDefaults(options);
+    const targetPath = parsed.positionals[0] ? resolve(options.cwd, parsed.positionals[0]) : options.cwd;
+    const outputPath = stringFlag(parsed.flags, 'output');
+    const result = await scanProject(config);
+    const relevantFiles = result.xdocsFiles.filter((f) => f.path.startsWith(targetPath));
+    if (relevantFiles.length === 0) {
+        process.stdout.write('No xdocs files found in the specified path.\n');
+        return;
+    }
+    const lines = [];
+    for (const file of relevantFiles) {
+        lines.push(`<!-- source: ${file.relativePath} -->`);
+        if (file.metadata) {
+            lines.push(`# ${file.metadata.subject}`, '');
+            lines.push(file.metadata.description, '');
+            const fileEntries = Object.entries(file.metadata.files);
+            if (fileEntries.length > 0) {
+                lines.push('## Files', '');
+                for (const [name, desc] of fileEntries) {
+                    lines.push(`- \`${name}\`: ${desc}`);
+                }
+                lines.push('');
+            }
+            if (file.metadata.children.length > 0) {
+                lines.push('## Submodules', '');
+                for (const child of file.metadata.children) {
+                    lines.push(`- ${child}`);
+                }
+                lines.push('');
+            }
+        }
+        if (file.body.trim()) {
+            lines.push(file.body.trim(), '');
+        }
+        lines.push('---', '');
+    }
+    const content = lines.join('\n');
+    if (outputPath) {
+        await writeFile(resolve(options.cwd, outputPath), content, 'utf8');
+        process.stdout.write(`merged: ${outputPath} (${relevantFiles.length} files)\n`);
+    }
+    else {
+        process.stdout.write(content);
+    }
+};

package/library/commands/prompt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
+/** Run the prompt command. */
+export declare const runPrompt: (_options: XDocsCliOptions, parsed: XDocsParsedArgs) => Promise<void>;
+//# sourceMappingURL=prompt.d.ts.map

package/library/commands/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../source/commands/prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAKnE,8BAA8B;AAC9B,eAAO,MAAM,SAAS,GAAU,UAAU,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CAehG,CAAA"}

package/library/commands/prompt.js

@@ -0,0 +1,19 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { XDocsError } from '../errors.js';
+import { stringFlag } from '../flags.js';
+import { getPrompt, getPromptNames } from '../prompts.js';
+/** Run the prompt command. */
+export const runPrompt = async (_options, parsed) => {
+    const name = stringFlag(parsed.flags, 'name');
+    const available = getPromptNames().join(', ');
+    if (!name) {
+        throw new XDocsError(`Missing --name flag. Usage: xdocs prompt --name=write\n\nAvailable prompts: ${available}`);
+    }
+    const prompt = getPrompt(name);
+    if (!prompt) {
+        throw new XDocsError(`Unknown prompt name: "${name}"\n\nAvailable prompts: ${available}`);
+    }
+    process.stdout.write(prompt.body + '\n');
+};

package/library/commands/scan.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
+/** Run the scan command. */
+export declare const runScan: (options: XDocsCliOptions, _parsed: XDocsParsedArgs) => Promise<void>;
+//# sourceMappingURL=scan.d.ts.map

package/library/commands/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../source/commands/scan.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAInE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,SAAS,eAAe,KAAG,OAAO,CAAC,IAAI,CAoD9F,CAAA"}

package/library/commands/scan.js

@@ -0,0 +1,53 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { loadConfigOrDefaults } from '../config.js';
+import { scanProject } from '../discovery.js';
+/** Run the scan command. */
+export const runScan = async (options, _parsed) => {
+    const config = await loadConfigOrDefaults(options);
+    const result = await scanProject(config);
+    if (options.format === 'json') {
+        process.stdout.write(JSON.stringify({
+            totalFiles: result.totalFiles,
+            totalDirectories: result.totalDirectories,
+            coveredDirectories: result.coveredDirectories,
+            uncoveredDirectories: result.uncoveredDirectories,
+            xdocsFiles: result.xdocsFiles.map((f) => ({
+                path: f.relativePath,
+                valid: f.valid,
+                subject: f.metadata?.subject ?? null,
+                errors: f.errors,
+            })),
+            uncoveredPaths: result.uncoveredPaths,
+        }, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write(`\nxdocs scan\n\n`);
+    process.stdout.write(`extensions: ${config.extensions.supported.join(', ')}\n`);
+    process.stdout.write(`total files scanned: ${result.totalFiles}\n`);
+    process.stdout.write(`total directories: ${result.totalDirectories}\n`);
+    process.stdout.write(`covered directories: ${result.coveredDirectories}\n`);
+    process.stdout.write(`uncovered directories: ${result.uncoveredDirectories}\n`);
+    process.stdout.write(`xdocs files found: ${result.xdocsFiles.length}\n`);
+    if (result.xdocsFiles.length > 0) {
+        process.stdout.write(`\nfiles:\n`);
+        for (const file of result.xdocsFiles) {
+            const status = file.valid ? 'valid' : 'incomplete';
+            const subject = file.metadata?.subject ? ` (${file.metadata.subject})` : '';
+            process.stdout.write(`  ${file.relativePath} [${status}]${subject}\n`);
+            if (options.verbose && file.errors.length > 0) {
+                for (const error of file.errors) {
+                    process.stdout.write(`    error: ${error}\n`);
+                }
+            }
+        }
+    }
+    if (options.verbose && result.uncoveredPaths.length > 0) {
+        process.stdout.write(`\nuncovered directories:\n`);
+        for (const uncovered of result.uncoveredPaths) {
+            process.stdout.write(`  ${uncovered}\n`);
+        }
+    }
+    process.stdout.write('\n');
+};

package/library/commands/tree.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
+/** Run the tree command. */
+export declare const runTree: (options: XDocsCliOptions, parsed: XDocsParsedArgs) => Promise<void>;
+//# sourceMappingURL=tree.d.ts.map

package/library/commands/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../source/commands/tree.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAMnE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CA0C7F,CAAA"}

package/library/commands/tree.js

@@ -0,0 +1,49 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { loadConfigOrDefaults } from '../config.js';
+import { scanProject } from '../discovery.js';
+import { buildTree, validateTree, renderTree, renderTreeMarkdown } from '../tree.js';
+import { stringFlag } from '../flags.js';
+/** Run the tree command. */
+export const runTree = async (options, parsed) => {
+    const config = await loadConfigOrDefaults(options);
+    const outputPath = stringFlag(parsed.flags, 'output');
+    const result = await scanProject(config);
+    const tree = buildTree(result.xdocsFiles);
+    // Validate tree integrity
+    if (options.verbose) {
+        const validation = validateTree(result.xdocsFiles);
+        if (validation.warnings.length > 0) {
+            process.stderr.write('\nwarnings:\n');
+            for (const warning of validation.warnings) {
+                process.stderr.write(`  ${warning}\n`);
+            }
+        }
+        if (validation.errors.length > 0) {
+            process.stderr.write('\nerrors:\n');
+            for (const error of validation.errors) {
+                process.stderr.write(`  ${error}\n`);
+            }
+        }
+    }
+    let content;
+    if (options.format === 'markdown') {
+        content = `# Project Hierarchy\n\n${renderTreeMarkdown(tree)}\n`;
+    }
+    else if (options.format === 'json') {
+        content = JSON.stringify(tree, null, 2) + '\n';
+    }
+    else {
+        content = renderTree(tree) + '\n';
+    }
+    if (outputPath) {
+        await writeFile(resolve(options.cwd, outputPath), content, 'utf8');
+        process.stdout.write(`tree: ${outputPath}\n`);
+    }
+    else {
+        process.stdout.write(content);
+    }
+};